Repository Guidelines

Project Structure & Module Organization

init.lua sets core options (tab width 2, tabs preserved) and wires config.lazy, config.mappings, and config.autocmd.
lua/config/ holds shared behavior: lazy.lua bootstraps lazy.nvim and leaders, mappings.lua defines keys, autocmd.lua holds events and filetype tweaks.
lua/plugins/ contains one-file-per-topic plugin specs for lazy.nvim; add new plugins here using a returned table.
lazy-lock.json pins plugin revisions; update only when deliberately bumping dependencies.
spell/ contains custom spelling wordlists loaded by the config.

Install/sync plugins: nvim --headless "+Lazy sync" +qa (also respects lazy-lock.json).
Check runtime health: nvim --headless "+checkhealth" +qa.
Minimal repro session: nvim --clean -u init.lua from the repo root.
Format Lua locally when available: stylua lua (uses conform.nvim/stylua in-editor).

Lua uses tabs with a visual width of 2 (noexpandtab, tabstop=2, shiftwidth=2).
Prefer readable tables with trailing commas and module-level return { ... } style for plugin specs.
Name plugin files by feature (lua/plugins/telescope.lua, lua/plugins/git.lua); keep config helpers in lua/config/.
Keep user-facing strings concise; avoid hardcoding machine-specific paths beyond $HOME.

After changes, run nvim --headless "+Lazy sync" +qa to ensure specs load and dependencies resolve.
Run nvim --headless "+checkhealth" +qa to catch missing tools (e.g., stylua, rustfmt, typstyle, styler for R).
For keymap or autocmd changes, open a clean session (nvim --clean -u init.lua) and exercise the affected commands or filetypes.

Recent history favors brief, present-tense summaries (e.g., update LSP, buffer); keep subjects under ~50 characters.
When adding plugins or mappings, mention the feature in the subject and note key bindings or defaults in the body.
For pull requests, include: what changed, why it helps editing workflows, any new dependencies, and screenshots/gifs if UI-facing (statusline, dashboard).
If you update lazy-lock.json, call that out explicitly and describe any notable plugin upgrades or breaking changes.

Do not commit API keys or machine-specific credentials; prefer environment variables consumed by plugins when needed.
Keep external tooling installs (Mason, system packages) documented so others can reproduce formatter/linter availability.
Avoid introducing autocmds or keymaps that shadow common defaults without noting the rationale in lua/config/mappings.lua.