nvim-config

name	nvim-config
description	Use when editing lua/plugins/, lua/config/, or any nvim config file. Use when asked about keymaps, plugin options, or LazyVim settings. Use when you need to verify config changes work.

Working with pickled-lazyvim

Core principle: Verify, don't ask. Run query scripts to confirm changes work instead of asking user to verify.

Scripts

Script	Purpose
./scripts/validate.sh	Check config loads without errors
./scripts/nvim-query "expr"	Run Lua expression in headless nvim
./scripts/query-keymaps [filter]	Query keymap definitions
./scripts/query-explorer [filter]	Test explorer file visibility

Exploration Queries

# Snacks picker config
./scripts/nvim-query "require('snacks.picker.config').get({ source = 'explorer' })"

# Where is keymap defined?
./scripts/nvim-query "vim.fn.execute('verbose map <leader>ff')"

# Plugin loaded?
./scripts/nvim-query "package.loaded['which-key'] ~= nil"

# Plugin spec from lazy.nvim
./scripts/nvim-query "require('lazy.core.config').plugins['snacks.nvim'].opts"

# LazyVim extras
./scripts/nvim-query "require('lazyvim.config').json.data.extras"

# Search keymaps
./scripts/query-keymaps telescope
./scripts/query-keymaps --vague  # short/missing descriptions

Making Changes

Adding plugins: Create lua/plugins/my-plugin.lua:

return { "author/plugin-name", opts = { } }

Keymaps: Add to plugin spec or lua/config/keymaps.lua:

keys = { { "<leader>xx", "<cmd>Cmd<cr>", desc = "Description" } }

Override options: Use same plugin name, opts are deep-merged:

return { "folke/snacks.nvim", opts = { explorer = { hidden = true } } }

Verification Workflow

# 1. Always validate after edits
./scripts/validate.sh

# 2. Verify specific changes took effect
./scripts/nvim-query "require('snacks.picker.config').get({ source = 'explorer' }).hidden"

# 3. For explorer changes
./scripts/query-explorer         # all test files
./scripts/query-explorer hidden  # only hidden

Only ask user to verify when: visual confirmation needed, query ambiguous, or requires interaction.

Common Mistakes

Mistake	Fix
Editing plugins in ~/.local/share/nvim/lazy/	Edit lua/plugins/ instead - lazy dir gets overwritten
Forgetting to run validate.sh	Always validate before trusting changes
Asking user "does this work?"	Run query script to verify programmatically
Missing desc on keymaps	Always add description for which-key

File Locations

What	Where
This config	~/workspace/pickled-lazyvim/
Installed plugins	~/.local/share/nvim/lazy/

nvim-query Options

./scripts/nvim-query "expr"           # Lua expression
./scripts/nvim-query -f file.lua      # Lua file
./scripts/nvim-query --json "expr"    # JSON output
./scripts/nvim-query -t 5000 "expr"   # Custom timeout (ms)