update

README.md

@@ -0,0 +1,115 @@
+# Neovim Rebuild — Decisions & Reference
+
+Authoritative notes for the Neovim migration. Use this alongside `MIGRATION_PLAN.md` and `neovim-migration-guide.md`.
+
+- Migration plan: MIGRATION_PLAN.md
+- Guide and requirements: neovim-migration-guide.md
+
+## Decisions Log
+
+Record every decision here with a short rationale. Append new entries; do not rewrite history.
+
+- 2025-12-06: PHP LSP = `intelephense` (good PHP ecosystem support; integrates includePaths).
+- 2025-12-06: Enable Markdown LSP = `marksman` (lightweight, good MD features).
+- 2025-12-06: Use legacy `listchars` and `showbreak` values (preserve muscle memory).
+- 2025-12-06: No direnv fallback for local config (keep setup simple and repo-driven).
+- 2025-12-06: Project-local config = layered JSON `.nvim.json` + `.nvim.local.json` with `.nvimroot` as workspace boundary marker (multi-repo friendly).
+- 2025-12-06: Switch to `folke/neoconf.nvim` for project-local configuration (supersedes custom layered JSON loader); use `.neoconf.json` at workspace root.
+- 2025-12-06: Plugin approval policy — other plugins are allowed, but do not install any plugin not listed without explicit confirmation.
+
+## Project-Local Configuration (design)
+
+Context: Projects can contain multiple git repositories (e.g., WordPress site with theme + multiple plugins). We need a way to set per-project `intelephense.includePaths` and similar without globalizing settings.
+
+Options considered
+- Layered JSON files (recommended): `.nvim.json` (committed) + `.nvim.local.json` (gitignored)
+  - Walk upward from current file; collect and merge configs until reaching a boundary marker or filesystem root.
+  - Boundary marker: `.nvimroot` to define a workspace that can encompass multiple repos.
+  - Merge order: top → bottom; nearest wins on conflicts; arrays replace by default unless we later add a merge strategy.
+  - Pros: safe (data-only), portable, reviewable in PRs.
+  - Cons: less dynamic than Lua.
+- Layered Lua files: `.nvim.lua` + `.nvim.local.lua`
+  - Pros: maximum flexibility (computed paths).
+  - Cons: executes code from the repo; security gates required.
+- Env/direnv: rejected (decision 2025-12-06).
+- Central registry file in `~/.config/nvim/`: possible later for private overrides, but not primary.
+
+Chosen approach (confirmed)
+- Use `folke/neoconf.nvim` with `.neoconf.json` at the workspace root (or project roots) to supply LSP/plugin settings. Multi-repo: keep a single `.neoconf.json` at the parent workspace folder and open Neovim from there (or use a rooter later if needed).
+
+Example `.neoconf.json`
+```
+{
+  "lspconfig": {
+    "intelephense": {
+      "settings": {
+        "intelephense": {
+          "environment": {
+            "includePaths": [
+              "wp-content/themes/my-theme",
+              "wp-content/plugins/custom-plugin"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+- Files recognized per directory level:
+  - `.nvim.json`: checked into VCS; shared per-project defaults.
+  - `.nvim.local.json`: gitignored; machine-specific overrides.
+- Loader behavior:
+  1. Start at the buffer’s directory; ascend toward root.
+  2. Stop at directory containing `.nvimroot` (if found) or at filesystem root.
+  3. At each level, if `.nvim.json` or `.nvim.local.json` exists, parse and stage for merge.
+  4. Merge staged configs in ascending order; nearest directory applies last.
+- Path resolution:
+  - Relative paths resolve against the topmost boundary (i.e., `.nvimroot` directory if present; otherwise the highest directory in which a config was found). This allows referencing sibling repos (e.g., theme and plugins) from a single top-level site folder.
+
+Example `.nvim.json`
+```
+{
+  "lsp": {
+    "php": {
+      "intelephense": {
+        "includePaths": [
+          "wp-content/themes/my-theme",
+          "wp-content/plugins/custom-plugin",
+          "vendor/some-package/src"
+        ]
+      }
+    }
+  }
+}
+```
+
+Intended integration
+- A helper module `lua/local_config.lua` will expose:
+  - `load(start_dir) -> table` collecting and merging configs
+  - `get(path, default)` for reads, e.g., `get({"lsp","php","intelephense","includePaths"}, {})`
+- LSP wiring (in Phase 3.5):
+  - Read includePaths via the helper and pass to `settings.intelephense.environment.includePaths` in `lspconfig.intelephense.setup{}`.
+
+Open items to confirm
+- Confirm JSON as the format (vs Lua) for project-local config.
+- Confirm `.nvimroot` as the workspace boundary marker name.
+- Confirm array merge behavior (replace vs concatenate). Initial proposal: replace.
+
+## LSP Scope (initial)
+
+- Core servers: `lua_ls`, `tsserver`, `html`, `cssls`, `jsonls`, `bashls`
+- PHP: `intelephense` (decision)
+- Markdown: `marksman` (decision)
+- Keep configuration minimal; defer language-specific tuning.
+
+## Text & Editing Settings
+
+- `spelllang = en_gb`
+- `listchars` and `showbreak` will reuse legacy values.
+- `completeopt = menu,menuone,noselect` for `nvim-cmp`.
+
+## Process Reminders
+
+- After any change or decision, update this README and MIGRATION_PLAN.md.
+- Keep subphases small and verify each step in isolation.