docs: add Neovim agent guides and update utils style

Author: fbosch

.config/nvim/AGENTS.md

@@ -0,0 +1,20 @@
+# Neovim Configuration - Agent Guide
+
+Neovim config with Lazy.nvim, Lua-first modules, and VSCode-mode support.
+
+## Essentials
+
+- Lazy.nvim plugin system is bootstrapped in `lua/config/lazy.lua`.
+- Plugin specs live under `lua/plugins/` and are imported via `lua/plugins/init.lua`.
+- VSCode mode (`vim.g.vscode`) loads `lua/config/vscode.lua` and disables most UI plugins.
+- Neovim state lives in `.config/nvim/.undo`, `.backup`, `.sessions`, `.swp` (do not edit directly).
+
+## More Guidance
+
+- [Local structure and entrypoints](docs/agents/structure.md)
+- [Options, autocmds, and keymaps](docs/agents/behavior.md)
+- [User commands and utils](docs/agents/utils.md)
+- [Plugin layout](docs/agents/plugins.md)
+- [VSCode mode](docs/agents/vscode.md)
+- [Lua style (shared)](../../docs/agents/nvim-lua.md)
+- [File organization (shared)](../../docs/agents/file-organization.md)

.config/nvim/docs/agents/behavior.md

@@ -0,0 +1,20 @@
+# Options, Autocmds, and Keymaps
+
+Options highlights:
+
+- Spellcheck is deferred to text-heavy filetypes (see `config.autocmd`).
+- State dirs: `.undo`, `.backup`, `.swp`, `.sessions` under `stdpath("config")`.
+- Filetype and syntax are disabled early for startup (re-enabled by plugins).
+
+Autocmds:
+
+- Filetype overrides: JSON5, MDX.
+- Spell on for text filetypes (unless VSCode).
+- Relative number toggled by insert/normal state.
+- `checktime` on focus/enter, notify on external changes.
+
+Keymaps:
+
+- Base maps are loaded from `config.keymaps.*`.
+- Plugin maps load on `VeryLazy` to avoid heavy startup.
+- Use `utils.set_keymap` for consistency.

.config/nvim/docs/agents/plugins.md

@@ -0,0 +1,16 @@
+# Plugin Layout
+
+Lazy.nvim setup lives in `lua/config/lazy.lua`.
+
+Plugin categories:
+
+- `ai/`
+- `core/`
+- `lang/`
+- `misc/`
+- `ui/`
+- `workflow/`
+
+Plugins are aggregated via `lua/plugins/init.lua` and further composed by category.
+
+Built-in plugins disabled in `config.lazy` include netrw, tar/zip, tutor, matchit, matchparen, and others.

.config/nvim/docs/agents/structure.md

@@ -0,0 +1,20 @@
+# Local Structure and Entrypoints
+
+Entrypoint flow:
+
+- `.config/nvim/init.lua` sets leaders and loads `config`
+- `lua/config/init.lua` loads core modules in order
+
+Core modules:
+
+- `config.opts`: options and defaults
+- `config.usercmd`: user commands via `utils.set_usrcmd`
+- `config.keymaps`: base keymaps + deferred plugin keymaps
+- `config.autocmd`: filetype rules, spell, UI behaviors
+- `config.abbr`: filetype abbreviations and typo fixes
+- `config.lazy`: Lazy.nvim bootstrap
+
+Plugin loading:
+
+- `lua/plugins/init.lua` imports plugin categories
+- UI/lang/workflow/ai are disabled in VSCode mode

.config/nvim/docs/agents/utils.md

@@ -0,0 +1,13 @@
+# User Commands and Utils
+
+User commands:
+
+- `DiffClip`: compare active buffer with clipboard
+- `WipeAllSessions`: removes sessions in `.config/nvim/.sessions`
+- `Z`: `wa | qa` shortcut
+
+Utils:
+
+- `utils.set_keymap(mode, lhs, rhs, opts_or_desc)` for keymaps
+- `utils.set_usrcmd(cmd, callback, opts_or_desc)` for user commands
+- `utils.wipe_all_sessions()` for session cleanup

.config/nvim/docs/agents/vscode.md

@@ -0,0 +1,7 @@
+# VSCode Mode
+
+When `vim.g.vscode` is set:
+
+- `config.vscode` replaces notifications and maps VSCode actions.
+- UI/lang/workflow/ai plugin categories are disabled.
+- Spellcheck and other behaviors respect VSCode guard clauses.

.config/nvim/lua/utils/init.lua

@@ -7,7 +7,7 @@ function M.load_highlights(group)
 end
 
 function M.set_usrcmd(cmd, callback, opts_or_desc)
-	opts = opts or {}
+	local opts = opts or {}
 	vim.api.nvim_create_user_command(
 		cmd,
 		callback,