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