add phase for colorscheme migration

Paper Tonic colorscheme and custom highlights

- Port Paper Tonic colorscheme as a local plugin.
- Add custom TreeSitter captures for CSS and HTML.
- Verify and extend highlights for plugins and captures.
- Retire legacy highlights and validate performance.

AGENTS.md

@@ -8,16 +8,20 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 - 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 tab-per-context workflow with Neo-tree per tab, Telescope navigation, LSP, Treesitter, Copilot, and sane UX defaults.
+- 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.
-- netrw settings (Neo-tree will be used).
+- 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)
 ```
@@ -39,7 +43,26 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
         ├── oil.lua
         ├── ufo.lua
         ├── gitsigns.lua
-        └── none-ls.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
@@ -55,24 +78,26 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 - 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).
-- Approved additions: `folke/neoconf.nvim` for project-local configuration.
+- 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: `neo-tree.nvim`, `telescope.nvim` (+ optional `telescope-fzf-native.nvim`).
+- Navigation: `telescope.nvim` + `telescope-fzf-native.nvim`, `oil.nvim`.
 - Treesitter: `nvim-treesitter`, `nvim-treesitter-textobjects`, `nvim-ts-autotag`.
-- UX/Editing: `Comment.nvim`, `surround.nvim`, `nvim-autopairs`, `indent-blankline.nvim`, `leap.nvim` or `flash.nvim`, `nvim-ufo`, `undotree` (optional).
+- UX/Editing: `Comment.nvim`, `nvim-surround`, `nvim-autopairs`, `indent-blankline.nvim`, `nvim-ufo`, `undotree`.
 - Git: `gitsigns.nvim`.
-- Markdown: `render-markdown.nvim`.
 - Copilot: `copilot.lua`, `copilot-cmp`.
-- Formatting: `none-ls.nvim`.
+- Formatting/Linting: `none-ls.nvim`, `nvim-lint`.
+- LSP Management: `mason.nvim`, `mason-lspconfig.nvim`, `mason-tool-installer.nvim`.
 
 ## Workflow Requirements to Preserve
-- Tab-per-context: each tab has its own Neo-tree root.
-- Provide keymaps for: Neo-tree floating, Neo-tree sidebar toggle, and file preview. Previews should not pollute buffer list.
-- Keep splits inside tabs.
-- Use Telescope and LSP for navigation.
+- 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`.
@@ -80,6 +105,19 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 - 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.
@@ -90,9 +128,36 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
 
 ## Validation
 - Ensure Neovim starts without errors and with minimal startup time.
-- Verify tab workflow, Neo-tree behaviour, Telescope, LSP basics, and completion.
+- 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.