nvim/AGENTS.md

# AGENTS: Neovim Config Migration

Scope: applies to the entire `~/.config/nvim` directory tree.

This repository is being migrated to a modern, minimal Neovim setup driven by Lua and lazy.nvim. Follow these rules when making changes.

## Goals
- Modern Lua-first config; avoid Vimscript unless explicitly requested.
- Keep it minimal, fast, and maintainable.
- Base plugin management on `lazy.nvim` with modular plugin specs.
- Support Telescope navigation, netrw for file browsing/preview, Oil.nvim for file operations, LSP, Treesitter, Copilot, and sane UX defaults.
- Native project-local configuration via `exrc` + `secure` (no external config plugins).

## Do Not Reintroduce
- Custom Vimscript tabline/statusline, foldtext, UI hacks.
- Legacy autocommands toggling cursorline/column per window.
- CoC or CoC-specific config.
- Neo-tree (skipped in favor of netrw for navigation).
- Providers for ruby/perl/node (disable unless required by a plugin).
- Auto-reload vimrc-on-write templates.
- `cursorcolumn` and old folding logic not related to UFO.
- neoconf plugin (incompatible with Neovim 0.11+, use native exrc instead).
- Motion plugins like leap.nvim or flash.nvim (not needed).
- Markdown rendering plugins (skipped entirely).

## Repository Structure (target)
```
~/.config/nvim/
├── init.lua                   -- entrypoint; bootstraps lazy.nvim and loads Lua modules
└── lua/
    ├── settings.lua          -- non-plugin options
    ├── keymaps.lua           -- non-plugin keymaps
    ├── autocmds.lua          -- non-plugin autocommands
    ├── abbreviations.lua     -- insert-mode abbreviations
    ├── netrw-config.lua      -- netrw configuration
    ├── utils.lua             -- helpers (only if needed)
    └── plugins/              -- one file per plugin or domain
        ├── telescope.lua
        ├── treesitter.lua
        ├── cmp.lua
        ├── lsp.lua
        ├── copilot.lua
        ├── oil.lua
        ├── ufo.lua
        ├── gitsigns.lua
        ├── none-ls.lua
        ├── nvim-lint.lua
        ├── mason.lua
        ├── mason-lspconfig.lua
        ├── mason-tool-installer.lua
        ├── comment.lua
        ├── surround.lua
        ├── autopairs.lua
        └── indent-blankline.lua
├── after/
│   ├── ftplugin/
│   │   └── php.lua           -- PHP-specific settings (includeexpr for gf)
│   └── queries/              -- Custom Treesitter queries
│       ├── css/
│       │   └── highlights.scm
│       └── html/
│           └── highlights.scm
├── templates/
│   └── template.sh           -- Shell script template
└── legacy/                   -- Archived Vimscript config (reference only)
```

## Coding Conventions
- Use Lua APIs: `vim.opt`, `vim.api.nvim_create_autocmd`, `vim.keymap.set`.
- No inline Vimscript or `vim.cmd` blocks unless strictly necessary.
- Keep plugin configuration self-contained in its plugin spec file.
- Prefer small, readable modules and minimal configuration over heavy customization.
- Keymaps: use `vim.keymap.set` with `{ silent = true, noremap = true }` defaults unless otherwise required.
- Autocommands: group via `vim.api.nvim_create_augroup` and create specific, narrowly scoped autocmds.
- Avoid global state; return tables from modules and plugin specs.

## Plugin Management (lazy.nvim)
- Each plugin lives in `lua/plugins/<name>.lua` and returns a spec table.
- Use `opts = {}` for default options and `config = function(_, opts) ... end` for setup.
- Do not install any plugin not listed without explicit user confirmation (proposal and rationale are welcome).
- Rejected: `folke/neoconf.nvim` (incompatible with Neovim 0.11+ vim.lsp.config API).

## Required Plugin Categories
- Core: `nvim-lspconfig`, `nvim-cmp`, `cmp-nvim-lsp`, `cmp-buffer`, `cmp-path`, `LuaSnip`.
- Navigation: `telescope.nvim` + `telescope-fzf-native.nvim`, `oil.nvim`.
- Treesitter: `nvim-treesitter`, `nvim-treesitter-textobjects`, `nvim-ts-autotag`.
- UX/Editing: `Comment.nvim`, `nvim-surround`, `nvim-autopairs`, `indent-blankline.nvim`, `nvim-ufo`, `undotree`.
- Git: `gitsigns.nvim`.
- Copilot: `copilot.lua`, `copilot-cmp`.
- Formatting/Linting: `none-ls.nvim`, `nvim-lint`.
- LSP Management: `mason.nvim`, `mason-lspconfig.nvim`, `mason-tool-installer.nvim`.

## Workflow Requirements to Preserve
- Netrw for visual context and project structure browsing (tree view, preview splits).
- Telescope for fuzzy finding (files, grep, buffers, LSP symbols).
- Oil.nvim for file manipulation (handles buffer sync on rename/move/delete).
- LSP for navigation (gd, gr, K, etc.).
- Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev) — prioritize these languages in LSP/Treesitter.
- Format-on-save with toggle capability.
- Project-local configuration via `.nvim.lua` files.

## Behaviours to Keep (modernized)
- Abbreviations: `adn→and`, `waht→what`, `tehn→then`, `functin→function`, `positin→position`.
- Templates: auto-populate `.sh` from template.
- Whitespace highlighting (use modern alternatives, e.g., `listchars`, plugins if needed).
- Persistent folds (prefer `nvim-ufo`).
- Spell & text: `spelllang=en_gb`, custom `listchars`, `showbreak`.
- Keyword characters: `iskeyword+=$` (for PHP/shell variables), `iskeyword+=-` (for CSS/HTML/config files).

## Current Status (Phase 10 Complete)
- ✅ Phase 1-2: Archive legacy, bootstrap lazy.nvim
- ✅ Phase 3: Core editing & LSP (native exrc + vim.lsp.config migration complete)
- ✅ Phase 4: Navigation (Telescope, netrw, Oil.nvim)
- ✅ Phase 5: Treesitter (parsers, textobjects, autotag)
- ✅ Phase 6: UX/Editing (Comment, surround, autopairs, indent guides, UFO, undotree)
- ✅ Phase 7: Git integration (Gitsigns)
- ✅ Phase 8: Copilot integration (copilot.lua + copilot-cmp)
- ✅ Phase 9: Formatting & Linting (none-ls, nvim-lint, Mason tool installer)
- ✅ Phase 10: Migrate kept behaviors (abbreviations, templates, custom Treesitter queries)
- ⏸️ Phase 11: Cleanup & validation (pending)

## Migration Notes
- Do not edit legacy Vimscript files except to extract settings to Lua. Keep them intact until migration completes.
- Introduce `init.lua` and bootstrap `lazy.nvim` before adding plugins.
- Disable unnecessary providers early: `vim.g.loaded_ruby_provider = 0`, etc.
- Keep startup fast; avoid unnecessary autoloading or heavy defaults.
- When cleaning, archive existing files into a `legacy/` folder within this config instead of deleting. Maintain a brief index if helpful.

## Validation
- Ensure Neovim starts without errors and with minimal startup time.
- Verify Telescope navigation, netrw browsing, Oil.nvim file operations, LSP basics, and completion.
- Keep plugin count tight; remove anything unused.

## Key Decisions & Architecture

### LSP Configuration
- **Modern API (Neovim 0.11+)**: Uses `vim.lsp.config()` + `vim.lsp.enable()`, NOT `require('lspconfig')[server].setup()`
- **Project-local config**: Native `exrc` + `secure` (no neoconf - incompatible with 0.11+)
- **Config format**: `.nvim.lua` files return `{ lsp = { [server_name] = { settings = {...} } } }`
- **Security**: `secure` mode prompts user to trust `.nvim.lua` files (one-time per file hash)
- **Settings loading**: `on_new_config` hook loads from actual `root_dir` (not cwd)
- **PHP**: intelephense with `single_file_support = false`, uses `environment.includePaths` for external libs

### Navigation Strategy
- **netrw**: Visual context, tree view, preview splits (horizontal 50/50 below)
- **Telescope**: Fuzzy finding (files, grep, buffers, LSP symbols)
- **Oil.nvim**: File manipulation (handles buffer sync on rename/move/delete)
- **PHP gf enhancement**: Custom `includeexpr` in `after/ftplugin/php.lua` for WordPress/PHP patterns

### Formatting & Linting
- **Formatters**: prettier, phpcbf, stylua, black (project-local → Mason → global)
- **Linters**: eslint_d, phpcs, markdownlint, ruff (via nvim-lint)
- **Format-on-save**: Enabled by default, toggle with `<leader>lt`
- **Philosophy**: Formatters are source of truth; Neovim settings match formatter rules per filetype

### Treesitter
- **Parsers**: lua, vim, vimdoc, php, html, javascript, typescript, tsx, css, scss, json, markdown, bash, regex
- **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag
- **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm`

## Process
- Before large changes, update the task plan via the CLI `update_plan` tool.
- Keep the live checklist in `MIGRATION_PLAN.md:1` up to date and in sync with changes.
- After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
- After any change or decision, also update `README.md:1` (decisions log and design docs).
- **After adding/removing/editing any keymaps**, immediately update `KEYMAPS.md` with the change (add new entries, remove deleted mappings, or update descriptions).
- At the start of each phase, confirm scope and priorities for that phase.
- Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
- Record decisions and rationale in `README.md:1` as they're made.
- Keep PR-sized patches; avoid broad unrelated edits.
- Document non-obvious choices in commit messages or short comments near the code that needs it.