nvim/MIGRATION_PLAN.md

Neovim Migration Checklist

Source of truth for the step-by-step rebuild. Keep this concise and up to date. See details in neovim-migration-guide.md.

Phase 0 — Ground Rules

• Create AGENTS.md with rules

Phase 1 — Clean & Archive Legacy Config

Phase 1.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 1.2 — Inventory legacy files

• Inventory existing Vimscript, plugin files, and directories

Phase 1.3 — Create archive location

• Create legacy/ archive folder within this config

Phase 1.4 — Move legacy files into archive

• Move legacy init files and plugin directories into legacy/ (do not delete)

Phase 1.5 — Document archived contents

• Optionally add legacy/README.md noting what was archived

Phase 1.6 — Preserve selected directories

• Keep undodir, spell, view, UltiSnips, templates as-is for now (review later)

Phase 2 — Bootstrap

Phase 2.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase

Phase 2.2 — Scaffold Lua config skeleton

• Scaffold Lua config skeleton (init.lua, lua/settings.lua, lua/keymaps.lua, lua/autocmds.lua, lua/utils.lua, lua/plugins/)

Phase 2.3 — Bootstrap lazy.nvim

• Bootstrap lazy.nvim plugin manager

Phase 2.4 — Disable unused providers

• Disable unused providers (ruby, perl, node)

Phase 2.5 — Ensure lazy boots without specs

• Ensure lazy boots without specs (add empty lua/plugins/init.lua)

Phase 3 — Core Editing & LSP

Phase 3.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: PHP LSP = intelephense
• Decision: Enable Markdown LSP = marksman
• Decision: Use legacy listchars and showbreak values
• Decision: Support per‑project config for intelephense.includePaths
• Decision: No direnv fallback for local config

Phase 3.2 — Non-plugin settings to Lua

• Port non-plugin settings to Lua (options, listchars, showbreak, spelllang=en_gb)

Phase 3.3 — Core completion stack

• Add core completion stack: nvim-cmp, cmp-nvim-lsp, cmp-buffer, cmp-path, LuaSnip

Phase 3.4 — Project‑local configuration (native exrc)

• Confirm scope and priorities for this subphase
• Decision: Use native exrc + secure instead of neoconf (neoconf incompatible with Neovim 0.11+ vim.lsp.config API)
• Enable exrc and secure in settings.lua
• Implement .nvim.lua loader in LSP config using on_new_config hook
• Wire intelephense.environment.includePaths via .nvim.lua
• Create validation workspaces: WORKSPACE_TEST/ and EXTERNAL_TEST/ with sample PHP files
• Migrate to vim.lsp.config() and vim.lsp.enable() (Neovim 0.11+ native API)
• Verify project settings load correctly from actual root_dir
• Clean up debug notifications and temporary code

Phase 3.7 — Clean LSP config

• Remove debug/helper logic from LSP config
• Migrate from deprecated require('lspconfig')[server].setup() to vim.lsp.config() + vim.lsp.enable()
• Use on_new_config hook for project-local settings loading (loads from actual root_dir, not cwd)

Phase 3.8 — Validate project-local LSP settings

• Create test workspaces with .nvim.lua files
• Validate settings load from actual root_dir via on_new_config hook
• Verify gd works for external library references via intelephense.environment.includePaths
• Clean up debug code and notifications

Phase 3.9 — Native exrc + vim.lsp.config migration (RESOLVED)

• Discovered neoconf incompatible with Neovim 0.11+ (GitHub issue #116, unresolved since May 2024)
• Migrated to native exrc + secure approach (zero dependencies, aligned with minimal philosophy)
• Implemented .nvim.lua loader using on_new_config hook (loads from actual root_dir)
• Migrated from deprecated require('lspconfig') framework to vim.lsp.config() + vim.lsp.enable()
• Root detection handled by nvim-lspconfig's native configs (no custom root_dir needed)
• Validated gd works for external library symbols via intelephense.environment.includePaths
• Settings schema: .nvim.lua returns { lsp = { [server_name] = { settings = {...} } } }
• Security: secure mode prompts user to trust .nvim.lua files before execution
• Kept single_file_support = false for intelephense
• Fixed duplicate gd results issue

Phase 3.5 — LSP minimal defaults

• Add nvim-lspconfig with minimal defaults (no over-configuration)
• Add minimal LSP on-attach keymaps (gd, gr, K, gD, gI)
• Add global LSP keymaps with fallback in lua/keymaps.lua
• Intelephense: set single_file_support=false, root detection via nvim-lspconfig defaults
• Project settings loaded via on_new_config hook from .nvim.lua files

Phase 3.6 — LSP server management (Mason)

• Confirm scope and priorities for this subphase
• Add williamboman/mason.nvim and williamboman/mason-lspconfig.nvim
• Ensure servers installed: lua_ls, tsserver, html, cssls, jsonls, bashls, marksman, intelephense
• Keep our custom per-server setup; use Mason only for installation

Phase 4 — Navigation

Phase 4.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Skip Neo-tree in favor of netrw for navigation/visual context
• Decision: Use netrw for project structure visualization and file preview
• Decision: Telescope as primary "find file" tool
• Decision: Add Oil.nvim for file manipulation (handles buffer sync on rename/move/delete)
• Note: Oil.nvim is for evaluation; alternative is mini.files if too heavy

Phase 4.2 — Configure netrw

• Configure netrw with tree view, preview split, and basic settings (no banner, sensible defaults)
• Created lua/netrw-config.lua with settings: tree view, horizontal preview split below, 50/50 split, human-readable sizes
• Add netrw keymaps: <leader>te (new tab at current file's directory), <leader>tE (new tab at project root)
• Decision: No <leader>e or <leader>v keymaps - use :Ex, :Vex directly when needed
• Preview behavior: Enter opens file in netrw window, p opens 50/50 horizontal split below

Phase 4.2.1 — PHP gf enhancement

• Add PHP includeexpr for intelligent gf behavior (handles __DIR__, __FILE__, dirname(__FILE__) patterns)
• Created after/ftplugin/php.lua with path resolution for WordPress/PHP patterns
• Tested and validated with test-gf.php

Phase 4.3 — Telescope setup

• Add telescope.nvim + telescope-fzf-native.nvim for fuzzy finding
• Configure basic pickers: find_files, live_grep, buffers, help_tags, oldfiles, current_buffer_fuzzy_find
• Add LSP pickers: lsp_document_symbols, lsp_workspace_symbols
• Keymaps configured:
  • <leader>ff - Find files
  • <leader>fg - Live grep (search text)
  • <leader>fb - Find buffers (with <C-d> to delete)
  • <leader>fh - Find help
  • <leader>fr - Recent files
  • <leader>/ - Search current buffer
  • <leader>fs - Document symbols (LSP)
  • <leader>fS - Workspace symbols (LSP)
• Minimal UI: dropdown theme for files/buffers, no previewer for quick selection

Phase 4.4 — Oil.nvim for file manipulation

• Add stevearc/oil.nvim for filesystem operations (rename, create, delete, copy, move)
• Configure to handle buffer name sync on file operations
• Keep minimal - use only when shell operations would cause buffer issues
• Keymaps configured:
  • <leader>fo - Open Oil file browser (regular buffer)
  • <leader>fO - Open Oil in floating window (with floating previews)
  • <C-p> in Oil - Preview files (vertical split to right for regular, floating window for float mode)
• Preview splits open to the right via vertical = true and split = 'belowright'
• Floating window preview direction: preview_split = "right"
• Note: Evaluate practicality; can switch to mini.files if preferred

Phase 5 — Treesitter

Phase 5.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Focus on languages: PHP, HTML, JavaScript, TypeScript, CSS, Markdown, Lua, Bash, JSON
• Decision: Enable syntax highlighting and incremental selection (CR to expand, BS to shrink)
• Decision: Enable textobjects for functions, classes, parameters, conditionals, loops
• Decision: Enable autotag for HTML/PHP/JS/React files
• Decision: Disable indent (experimental) to start; can enable per-filetype if stable

Phase 5.2 — Base Treesitter

• Add nvim-treesitter with incremental selection, highlighting
• Configure parsers: lua, vim, vimdoc, php, html, javascript, typescript, tsx, css, scss, json, markdown, markdown_inline, bash, regex
• Enable auto-install for missing parsers
• Incremental selection keymaps: CR (init/expand), S-CR (scope expand), BS (shrink)
• Disable for large files (>100KB) to maintain performance

Phase 5.3 — Treesitter textobjects

• Add nvim-treesitter-textobjects
• Select keymaps: af/if (function), ac/ic (class), aa/ia (parameter), ai/ii (conditional), al/il (loop), a/ (comment)
• Move keymaps: ]f/[f (next/prev function start), ]F/[F (function end), similar for classes and parameters
• Swap keymaps: <leader>a/<leader>A (swap parameter with next/prev)

Phase 5.4 — Treesitter autotag

• Add nvim-ts-autotag
• Enable auto-close, auto-rename, and close-on-slash for HTML/PHP/JS/React/TS/Vue files

Phase 6 — UX / Editing

Phase 6.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: No cursorcolumn (as per AGENTS.md)
• Decision: No auto-window toggling behavior (keep settings static)
• Decision: No motion plugin (skip leap/flash)
• Decision: Move undotree to separate Phase 6.8
• UX settings to add: signcolumn, cursorline, colorcolumn

Phase 6.2 — Core UX settings

• Add signcolumn=yes (always show gutter for LSP/git)
• Add cursorline (highlight current line)
• Add colorcolumn=80,120 (visual guides)
• No cursorcolumn (excluded as per AGENTS.md)
• No per-window autocommands (keep simple)

Phase 6.3 — Comment.nvim

• Add numToStr/Comment.nvim
• Configure for gcc/gc commenting
• Add keymaps if needed

Phase 6.4 — Surround

• Add kylechui/nvim-surround
• Minimal config with default keymaps (ys, ds, cs)

Phase 6.5 — Autopairs

• Add windwp/nvim-autopairs
• Integrate with nvim-cmp

Phase 6.6 — Indent guides

• Add lukas-reineke/indent-blankline.nvim
• Configure scope highlighting

Phase 6.7 — Folding (UFO)

• Add kevinhwang91/nvim-ufo for folding
• Configure with Treesitter and LSP providers
• Add fold keymaps (za, zR, zM, etc.)

Phase 6.8 — Undotree

• Add mbbill/undotree
• Add keymap to toggle undotree
• Configure minimal settings

Phase 7 — Git Integration

Phase 7.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Gitsigns with minimal config - signs in gutter, hunk navigation/actions only
• Decision: Skip markdown rendering plugins entirely

Phase 7.2 — Gitsigns

• Add lewis6991/gitsigns.nvim
• Configure signs in gutter (add, change, delete, topdelete, changedelete)
• Add hunk navigation keymaps (]h/[h for next/prev hunk)
• Add hunk action keymaps (stage, reset, preview)
• Keep minimal - no inline blame, no advanced features

Phase 8 — Copilot

Phase 8.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Integrate Copilot into nvim-cmp as completion source
• Decision: Auto-trigger suggestions as you type
• Decision: No specific Copilot keymaps needed (use existing cmp keymaps)
• Decision: Enable for all filetypes
• Decision: Copilot suggestions appear before LSP suggestions in completion menu
• Node.js v22.21.1 upgraded and confirmed working

Phase 8.2 — Copilot setup

• Add zbirenbaum/copilot.lua + zbirenbaum/copilot-cmp
• Configure copilot.lua with auto-trigger and all filetypes
• Add copilot-cmp as source to nvim-cmp
• Set copilot-cmp priority higher than LSP in completion menu
• Note: Copilot initializes on first InsertEnter; enter/exit insert mode once before using :Copilot auth

Phase 9 — Formatting & Linting

Phase 9.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Formatters - prettier (JS/TS/CSS/JSON/MD/HTML), phpcbf (PHP), stylua (Lua), black (Python)
• Decision: Linters - eslint (JS/TS), phpcs (PHP), markdownlint (Markdown), ruff (Python)
• Decision: Project-local executables preferred, fallback to global (node_modules/.bin/, vendor/bin/)
• Decision: phpcs/phpcbf already installed globally with WordPress coding standards - no installation needed
• Decision: Format-on-save enabled by default with toggle capability
• Decision: Manual format keymaps: <leader>lf (normal), <leader>lf (visual range)
• Decision: Respect project config files (.prettierrc, phpcs.xml, .eslintrc, pyproject.toml, etc.)
• Strategy: Helper function detects project-local executables first, then global
• WordPress: phpcs.xml in project root or --standard=WordPress flag for WordPress projects
• Philosophy: Formatters are authoritative source of truth; Neovim settings should match formatter rules per filetype
• Note: Phase 9.4 will align Neovim editor settings (tabstop, shiftwidth, expandtab) with formatter configurations

Phase 9.2 — none-ls setup with project-aware executables

• Add nvimtools/none-ls.nvim
• Create helper function to detect project-local executables (node_modules/.bin/, vendor/bin/, Mason bin)
• Configure formatters:
  • prettier (project-local first, then Mason, then global)
  • phpcbf (project-local first, then global system install - already available)
  • stylua (Mason installed)
• Add mfussenegger/nvim-lint for linting (none-ls removed most linters from builtins)
• Configure linters via nvim-lint:
  • eslint_d (project-local first, then Mason, then global - daemon version for speed)
  • phpcs (project-local first, then global system install - already available)
  • markdownlint (Mason installed)
• Add format-on-save autocommand with toggle capability (<leader>lt to toggle)
• Add manual format keymaps: <leader>lf (buffer), <leader>lf (visual range)
• Ensure WordPress coding standards work via phpcs.xml or --standard flag
• Search order: project node_modules/.bin/ → project vendor/bin/ → Mason bin → system PATH
• Note: Linting runs on BufEnter, BufWritePost, InsertLeave events

Phase 9.3 — Mason formatter/linter installation

• Add WhoIsSethDaniel/mason-tool-installer.nvim for automated installation
• Install via Mason: prettier, eslint_d, markdownlint, stylua, black, ruff
• Note: phpcs/phpcbf already installed globally, skip Mason installation
• Verify all tools available: Tools installed to ~/.local/share/nvim/mason/bin/

Phase 9.4 — Align Neovim settings with formatter rules

• Configure per-filetype settings to match formatter defaults
• PHP: tabs, 2-width display (WordPress standards)
• JS/TS/CSS/JSON/HTML: spaces, 2-width (Prettier defaults)
• Lua: spaces, 2-width (common Neovim convention)
• Markdown: spaces, 2-width (Prettier defaults)
• Python: spaces, 4-width (Black/PEP 8 defaults)
• Use autocmds in lua/autocmds.lua for filetype-specific tabstop, shiftwidth, expandtab
• Set global defaults: 4-width, spaces (reasonable baseline)
• Goal: Manual editing feels natural and matches what formatter will produce on save
• Note: All settings kept explicit per-filetype for clarity and maintainability

Phase 10 — Migrate Kept Behaviours

Phase 10.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Port abbreviations to Lua via vim.cmd.iabbrev
• Decision: Port shell template auto-loading via autocmd + BufReadPost
• Decision: Whitespace highlighting already handled via listchars (Phase 3.2)
• Decision: Skip persistent folds (UFO handles folding, no explicit persistence needed)

Phase 10.2 — Abbreviations

• Abbreviations: adn→and, waht→what, tehn→then, functin→function, positin→position
• Created dedicated lua/abbreviations.lua for modularity and easier maintenance

Phase 10.3 — Templates

• Templates: auto-populate new .sh from template
• Added BufNewFile autocmd for *.sh in lua/autocmds.lua

Phase 10.4 — Whitespace highlighting

• Whitespace highlighting (modern approach)
• Note: Already handled via listchars in Phase 3.2 (settings.lua)

Phase 10.5 — Persistent folds

• Persistent folds (via UFO) -- no need, this is no longer required.
• Note: UFO handles folding; no explicit persistence mechanism needed

Phase 11 — Colorscheme: Modern Paper Tonic

Phase 11.1 — Confirm scope and priorities

• Confirm scope and priorities for this phase
• Decision: Create modern Paper Tonic fork from scratch
• Decision: Name = "paper-tonic-modern"
• Decision: Location = inside nvim config initially, move to repo later
• Decision: Structure = modular Lua colorscheme (colors.lua, groups/*.lua)
• Phased approach:
  • Phase 11.2-11.4: Extract palette and base groups
  • Phase 11.5-11.6: General TreeSitter highlights (modern @* groups)
  • Phase 11.7: Semantic highlighting (custom CSS/HTML captures)
  • Phase 11.8: Plugin support (LSP, Telescope, Gitsigns, etc.)

Phase 11.2 — Extract Paper Tonic color palette

• Create lua/paper-tonic-modern/colors.lua
• Extract all c_* color variables from Paper Tonic
• Document what each color represents (foreground, background, accent colors)
• Convert to modern format (keep hex, 256-color, ANSI mappings)

Phase 11.3 — Create colorscheme structure

• Create directory structure:
  • colors/paper-tonic-modern.lua (entry point)
  • lua/paper-tonic-modern/init.lua (main logic)
  • lua/paper-tonic-modern/colors.lua (palette)
  • lua/paper-tonic-modern/groups/ (highlight group definitions)
• Create helper function for setting highlights
• Set up colorscheme loading mechanism

Phase 11.4 — Base vim highlight groups

• Create lua/paper-tonic-modern/groups/editor.lua
• Map Paper Tonic colors to base groups: Normal, Comment, LineNr, CursorLine, etc.
• Create lua/paper-tonic-modern/groups/syntax.lua
• Map to syntax groups: Function, String, Keyword, Identifier, etc.
• Test with simple Lua file to verify base colors work

Phase 11.5 — Modern TreeSitter highlight groups

• Create lua/paper-tonic-modern/groups/treesitter.lua
• Map modern @* groups to Paper Tonic colors:
  • Core: @variable, @function, @keyword, @string, @number, @boolean, @comment
  • Types: @type, @property, @field, @parameter
  • Operators: @operator, @punctuation.delimiter, @punctuation.bracket
  • Language constructs: @keyword.function, @keyword.return, @keyword.conditional
• Use :help treesitter-highlight-groups as reference
• Test with multiple languages: Lua, PHP, JavaScript, HTML, CSS

Phase 11.6 — Language-specific TreeSitter groups

• Add language-specific overrides (e.g., @variable.php, @tag.html)
• Ensure HTML tags, CSS selectors, PHP variables have appropriate colors
• Test across primary languages (HTML, PHP, JS, CSS, Markdown)
• Added comprehensive language-specific groups:
  • CSS/SCSS: properties, variables, functions (green c2 tones)
  • HTML: tags, attributes, delimiters (blue c3)
  • PHP: variables, functions, methods, built-ins (primary brownish-red)
  • JavaScript/TypeScript: variables, functions, properties, JSX tags (primary + blue for JSX)
  • Lua: variables, functions, built-ins (primary)
  • Markdown: headings, links, code blocks (primary for structure)
  • JSON: properties, strings, numbers (neutral)
  • Bash: variables, functions, built-ins (primary)

Phase 11.7 — Semantic highlighting (custom captures)

• Create lua/paper-tonic-modern/groups/semantic.lua
• Define your custom semantic captures:
  • @CssClassName (for CSS .class and HTML class="" - same color)
  • @CssIdentifier (for CSS #id and HTML id="" - same color)
  • @DataAttribute, @DataAttributeValue (HTML data-* attributes)
  • @cssPseudoClass, @cssNestingSelector, @CssUniversalSelector (CSS-specific)
• Verify cross-language consistency: class names in HTML match CSS
• Implemented semantic highlights:
  • CSS: @CssClassName (green c2), @CssIdentifier (strong green c2_strong), @cssPseudoClass (weak green c2_weak)
  • CSS: @cssNestingSelector (strong green), @CssUniversalSelector (SpecialChar)
  • CSS: @CssProp (primary_weak), @CssPropertyValue (bold), @CssUnit (Delimiter)
  • HTML: @ClassNameAttribute, @IdAttribute, @DataAttribute (all fg_weak for attribute names)
  • HTML: @DataAttributeValue (Function)
  • Cross-language: class values and #id values in HTML use same colors as CSS selectors
• Test with existing custom queries (after/queries/css/highlights.scm, after/queries/html/highlights.scm)

Phase 11.8 — Plugin highlight groups

• Create lua/paper-tonic-modern/groups/lsp.lua
• Define LSP diagnostics: DiagnosticError, DiagnosticWarn, DiagnosticHint, DiagnosticInfo
• Define LSP UI: LspReferenceText, LspReferenceRead, LspReferenceWrite
• Create lua/paper-tonic-modern/groups/plugins.lua
• Add Telescope highlights (TelescopeNormal, TelescopeBorder, TelescopeSelection)
• Add Gitsigns highlights (GitSignsAdd, GitSignsChange, GitSignsDelete)
• Add nvim-cmp highlights (CmpItemKind*, CmpItemMenu, etc.)
• Add Oil.nvim highlights if needed

Notes:

• LSP diagnostics use red (error), orange (warn), blue (info), green (hint)
• LSP references use cyan backgrounds with varying intensity (text/read/write)
• LSP semantic tokens link to TreeSitter groups for consistency
• Telescope uses neutral colors with primary accent for matching and selection
• Gitsigns uses status colors: green (add), blue (change), red (delete)
• nvim-cmp uses primary tones for kinds, bold for matching text
• Oil.nvim uses bold for directories, status colors for permissions and operations
• indent-blankline and ufo use subtle grays for non-intrusive UI

Phase 11.9 — Update plugin configuration

• Update lua/plugins/colorscheme.lua to use paper-tonic-modern
• Remove old Paper Tonic reference
• Remove colorscheme-overrides.lua (no longer needed)
• Test full config reload

Notes:

• lua/plugins/colorscheme.lua already updated to load paper-tonic-modern
• Old paper-tonic/ directory moved to legacy/paper-tonic-original/ (archived)
• No colorscheme-overrides.lua existed (not needed with modern implementation)
• Full config reload tested: Normal ✓, DiagnosticError ✓, TelescopeNormal ✓, GitSignsAdd ✓
• Colorscheme loads correctly: vim.g.colors_name = 'paper-tonic-modern'

Phase 11.10 — Validation and polish

• Test all primary languages (Lua, PHP, HTML, CSS, JS, Markdown)
• Verify semantic consistency (CSS classes in HTML match CSS files)
• Check plugin UI colors (Telescope, Gitsigns, nvim-cmp)
• Verify LSP diagnostics are visible and distinct
• Document color scheme in README

Phase 11.11 — Extract to separate repo (later)

• Move to ~/projects/paper-tonic-modern/
• Update plugin config to point to new location
• Add proper README, LICENSE, screenshots
• Consider publishing to GitHub

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 12.3 — Startup performance

• Validate startup performance (no errors, fast launch)

Phase 12.4 — Navigation validation

• Validate Telescope navigation + LSP jumps
• Validate netrw browsing and preview splits
• Validate Oil.nvim file operations

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

---

Notes:

• Keep plugin specs minimal; configure in their own lua/plugins/*.lua files.
• Avoid adding plugins not listed in the guide unless explicitly requested.
• Prefer simple defaults; only add settings that clearly improve workflow.
• Plugin approval policy: unlisted plugins may be proposed, but must be explicitly confirmed before installation.

Known Issues / Follow-ups:

• lua-language-server (lua_ls) from Mason failed to start due to missing shared library libbfd-2.38-system.so. RESOLVED: Installed lua-language-server via system package manager (pacman) instead of Mason. Removed lua_ls from Mason's ensure_installed list in lua/plugins/mason-lspconfig.lua.
• LSP root detection: In some cases, the parent repository is picked as the root (e.g., when a workspace lives inside another repo). Workaround: create an empty .git directory (or a marker like .nvimroot) in the intended workspace root to pin the project root for LSPs.

Decisions & Changes:

• Neoconf dropped: folke/neoconf.nvim incompatible with Neovim 0.11+ vim.lsp.config API (GitHub issue #116, open since May 2024, no resolution). Migrated to native exrc + secure approach.
• vim.lsp.config migration: Migrated from deprecated require('lspconfig')[server].setup() to vim.lsp.config() + vim.lsp.enable() (Neovim 0.11+ native API).
• Project config format: .nvim.lua files return { lsp = { [server_name] = { settings = {...} } } }.
• Security model: secure mode prompts user to trust .nvim.lua files before execution (one-time per file hash).
• Settings loading: on_new_config hook loads project settings from actual root_dir (not cwd), ensuring correct behavior across different workspace structures.
• Phase 4 Navigation Strategy: Skipped Neo-tree in favor of built-in netrw for visual context and project structure browsing. Telescope for fuzzy finding. Oil.nvim for file manipulation (evaluation phase; alternative is mini.files). Rationale: User needs visual context and preview, not per-tab roots or complex tree features. File manipulation primarily done in shell, but Oil.nvim handles buffer sync issues when renaming/moving files.