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.
+- Netrw for visual context and project structure browsing (tree view, preview splits).
-- Provide keymaps for: Neo-tree floating, Neo-tree sidebar toggle, and file preview. Previews should not pollute buffer list.
+- Telescope for fuzzy finding (files, grep, buffers, LSP symbols).
-- Keep splits inside tabs.
+- Oil.nvim for file manipulation (handles buffer sync on rename/move/delete).
-- Use Telescope and LSP for navigation.
+- 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.

MIGRATION_PLAN.md

@@ -334,25 +334,66 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date.
 - [x] Persistent folds (via UFO) -- no need, this is no longer required.
 - [x] Note: UFO handles folding; no explicit persistence mechanism needed
 
-## Phase 11 — Cleanup & Validation
+## Phase 11 — Colorscheme Integration
 
 ## Phase 11.1 — Confirm scope and priorities
 - [ ] Confirm scope and priorities for this phase
+- [ ] Decision: Port Paper Tonic colorscheme from `~/projects/nvim-paper-tonic`
+- [ ] Decision: Install as local plugin via lazy.nvim (use `dir = '~/projects/nvim-paper-tonic'`)
+- [ ] Decision: Test first, then extend with missing highlights as needed
+- [ ] Custom TreeSitter captures to verify/define: `@CssClassName`, `@CssIdentifier`, `@DataAttribute`, `@DataAttributeValue`, `@cssPseudoClass`, `@cssNestingSelector`, etc.
 
-## Phase 11.2 — Retire legacy files
+## Phase 11.2 — Install Paper Tonic colorscheme
+- [ ] Create `lua/plugins/colorscheme.lua` with Paper Tonic as local plugin
+- [ ] Set `lazy = false` and `priority = 1000` to load first
+- [ ] Apply colorscheme in config function
+
+## Phase 11.3 — Verify custom TreeSitter highlights
+- [ ] Open HTML/CSS files and verify custom captures have colors
+- [ ] Check if `@CssClassName` (HTML class attributes) matches CSS class selector colors
+- [ ] Check if `@CssIdentifier` (HTML id attributes) matches CSS id selector colors
+- [ ] Check if `@DataAttribute` and `@DataAttributeValue` are distinct
+- [ ] Check CSS-specific captures: `@cssPseudoClass`, `@cssNestingSelector`, `@CssUniversalSelector`, etc.
+
+## Phase 11.4 — Verify plugin highlights
+- [ ] Telescope UI (borders, selection, prompts)
+- [ ] Gitsigns (add, change, delete signs in gutter)
+- [ ] nvim-cmp (completion menu, selected item, kind icons)
+- [ ] LSP diagnostics (ERROR, WARN, HINT, INFO signs and virtual text)
+- [ ] Oil.nvim (if distinctive colors needed)
+
+## Phase 11.5 — Add missing highlights (if needed)
+- [ ] Create `lua/colorscheme-overrides.lua` if custom highlights needed
+- [ ] Define highlights for custom TreeSitter captures not in colorscheme
+- [ ] Define highlights for plugins not covered by colorscheme
+- [ ] Load overrides after colorscheme applies (use autocmd or lazy.nvim config)
+
+## Phase 12 — Cleanup & Validation
+
+## Phase 12.1 — Confirm scope and priorities
+- [ ] Confirm scope and priorities for this phase
+
+## Phase 12.2 — Retire legacy files
 - [ ] Retire legacy Vimscript files (keep for reference until verified)
 
-## Phase 11.3 — Startup performance
+## Phase 12.3 — Startup performance
 - [ ] Validate startup performance (no errors, fast launch)
 
-## Phase 11.4 — Tab workflow validation
+## Phase 12.4 — Navigation validation
-- [ ] Validate tab-per-context workflow with Neo-tree (if used)
-
-## Phase 11.5 — Navigation validation
 - [ ] Validate Telescope navigation + LSP jumps
+- [ ] Validate netrw browsing and preview splits
+- [ ] Validate Oil.nvim file operations
 
-## Phase 11.6 — Language tooling validation
+## Phase 12.5 — Language tooling validation
 - [ ] Validate HTML/PHP/JS/Markdown tooling
+- [ ] Verify LSP (gd, gr, K, diagnostics)
+- [ ] Verify formatting (prettier, phpcbf, stylua)
+- [ ] Verify linting (eslint_d, phpcs, markdownlint)
+
+## Phase 12.6 — Final polish
+- [ ] Review all keymaps and ensure they're documented
+- [ ] Update README.md with final architecture and usage
+- [ ] Clean up any remaining debug code or temporary comments
 
 ---
 

after/queries/css/highlights.scm

@@ -0,0 +1,18 @@
+(id_selector (id_name) @CssIdentifier)
+(id_selector (id_name)) @CssIdSelector
+(tag_name) @HtmlTagName
+
+(class_selector (class_name) @CssClassName)
+(selectors (pseudo_class_selector (class_name) @cssPseudoClass))
+(nesting_selector) @cssNestingSelector
+
+; need to find out how to make this more specific?
+(universal_selector) @CssUniversalSelector
+
+((property_name) (_)) @CssProp
+
+(unit) @CssUnit
+
+(declaration (property_name) (_) @CssPropertyValue)
+
+(media_statement (feature_query (feature_name) @cssMediaFeatureName (_ (unit) @cssMediaQueryValueUnit) @cssMediaQueryValue) @cssMediaQuery)

after/queries/html/highlights.scm

@@ -0,0 +1,17 @@
+(start_tag
+	(attribute
+		(attribute_name) @ClassNameAttribute (#eq? @ClassNameAttribute "class")
+		(quoted_attribute_value
+			(attribute_value) @CssClassName )))
+
+(start_tag
+	(attribute
+		(attribute_name) @IdAttribute (#eq? @IdAttribute "id")
+		(quoted_attribute_value
+			(attribute_value) @CssIdentifier )))
+
+(start_tag
+	(attribute
+		(attribute_name) @DataAttribute (#match? @DataAttribute "^data-")
+		(quoted_attribute_value
+			(attribute_value) @DataAttributeValue )))