# AGENTS.md

## Purpose
This file gives future coding agents a fast, reliable workflow for this Neovim repo.

## Repo Layout
- `init.vim`: minimal entrypoint, only plugin bootstrap + `source` statements + tiny misc settings.
- `nvim-config/*.vim`: Vimscript modules by concern (leader maps, coc, lint, theme, etc.).
- `nvim-config/*.lua`: Lua plugin configs and modern Neovim setup.
- `coc-settings.json`: CoC language server and extension behavior.
- `KEYMAPS.md`: user-facing shortcut overview. Keep in sync with mappings.

## Editing Rules
- Keep `init.vim` small. New logic belongs in a focused file under `nvim-config/`.
- Prefer one concern per file (example: lint logic in `nvim-config/lint.vim`).
- Avoid breaking existing `<leader>` mappings unless explicitly requested.
- Do not silently remove language support; replace with an equivalent path first.
- Preserve user customizations and avoid wide refactors unless needed for a concrete fix.

## Validation Checklist (run after changes)
- Config load:
  - `/usr/local/bin/nvim --headless "+qa"`
- Command existence:
  - `/usr/local/bin/nvim --headless "+verbose command LintFile" "+qa"`
- Mapping existence:
  - `rg --line-number "<leader>lf|<leader>a|CocAction|LintFile" /Users/leon/.config/nvim/nvim-config`
- Health checks when touching plugins/LSP:
  - Open Neovim and run `:checkhealth`
  - Run `:messages` after startup and after `:CocRestart`

## Known Environment Notes
- In non-interactive shells `nvim` may be missing from `PATH`; use `/usr/local/bin/nvim`.
- A recurring message may appear: `Failed to find executable tmux`. Treat separately from lint/LSP issues.
- CoC is used for LSP/code actions. Formatting is handled by `conform.nvim` (not `coc-prettier`).

## Linting/Formatting Behavior
- `:LintFile` lives in `nvim-config/lint.vim`.
- JS/TS/Vue/Svelte/Astro:
  - First try CoC ESLint autofix command.
  - Fallback to local `node_modules/.bin/eslint --fix`.
- Terraform/HCL: use `tflint` if installed.
- Java diagnostics: via `coc-java` (JDTLS).
- Formatting on save should remain with `conform.nvim` unless user asks otherwise.

## Git Workflow
- Make small, reviewable commits with clear messages.
- Do not use destructive git commands (`reset --hard`, forced checkout) unless explicitly asked.
- Never revert unrelated user changes.

## When Unsure
- Prefer adding a small module file over expanding `init.vim`.
- Prefer explicit diagnostics (`echom`, `:messages`, `:checkhealth`) over guessing.
- If behavior changes for a key mapping, update `KEYMAPS.md` in the same change.