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

bash

# 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:

lua

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

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

lua

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

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

lua

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

Verification Workflow

bash

# 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

bash

./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)