From 638ff2812ff4057e326b0bcc7f8b7ac6f1378aa5 Mon Sep 17 00:00:00 2001
From: ray <gitea@rayelliott.dev>
Date: Sat, 6 Dec 2025 19:18:50 +0000
Subject: [PATCH] add migration guide

---
 neovim-migration-guide.md | 223 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 223 insertions(+)
 create mode 100644 neovim-migration-guide.md

diff --git a/neovim-migration-guide.md b/neovim-migration-guide.md
new file mode 100644
index 0000000..6bf2a70
--- /dev/null
+++ b/neovim-migration-guide.md
@@ -0,0 +1,223 @@
+# ✔ **Neovim Migration Guide for AI Assistance**
+
+## **Purpose**
+
+I am transitioning from VS Code back to Neovim.
+This document describes my goals, constraints, preferences, and what I expect from an AI assistant during this rebuild.
+
+---
+
+## **High-Level Goals**
+
+* Create a clean, modern Neovim setup using Lua.
+* Avoid bringing over legacy Vimscript or old config patterns.
+* Keep the configuration minimal but powerful.
+* Base plugins on **lazy.nvim**.
+* Support my workflow: **multiple tabs, each with its own Neo-tree instance**, for working with WordPress plugin development and referencing external codebases (WooCommerce, WordPress core, etc).
+* Use LSP, Treesitter, telescope, and modern UX plugins.
+* Integrate GitHub Copilot into completion.
+* Preserve certain useful behaviours from my old config (see below).
+
+---
+
+## **Do NOT Include / Do NOT Recreate**
+
+These are outdated patterns and I *do not* want them reintroduced:
+
+* custom tabline or statusline implemented in Vimscript
+* custom foldtext functions
+* autocommands that toggle cursorline/cursorcolumn per window
+* manual Redir/shell command buffer logic
+* CoC or any CoC-specific configuration
+* netrw settings (I will be using Neo-tree)
+* ruby, perl, node providers (disable them unless a plugin needs them)
+* template that reloads vimrc on write
+* cursorcolumn
+* old folding logic unrelated to UFO
+* Vimscript-based UI hacks of any kind
+
+If needed, suggest modern replacements instead.
+
+---
+
+## **Required Plugins (Modern Equivalents Only)**
+
+I want help managing these categories using lazy.nvim:
+
+### **Core**
+
+* nvim-lspconfig
+* nvim-cmp
+* cmp-nvim-lsp
+* cmp-buffer
+* cmp-path
+* LuaSnip
+
+### **Navigation**
+
+* neo-tree.nvim
+* telescope.nvim
+* telescope-fzf-native.nvim (optional)
+
+### **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 (folding)
+* undotree (optional)
+
+### **Git**
+
+* gitsigns.nvim
+
+### **Markdown**
+
+* render-markdown.nvim
+
+### **Copilot**
+
+* copilot.lua
+* copilot-cmp
+
+### **Formatting**
+
+* none-ls.nvim
+
+---
+
+## **Behaviours From My Old Config That I Want to KEEP**
+
+When helping me implement these, please use modern Lua (`vim.api.nvim_*`, `vim.keymap.set`, etc), **not Vimscript**.
+
+### ✔ Keybindings to preserve
+
+### ✔ Templates for new files
+
+* Auto-populate `.sh` from templates
+
+### ✔ Abbreviations
+
+* adn → and
+* waht → what
+* tehn → then
+* functin → function
+* positin → position
+
+### ✔ Whitespace highlighting (modern alternatives acceptable)
+
+### ✔ Persistent folds (if not using UFO)
+
+### ✔ Spell & text settings
+
+* `spelllang=en_gb`
+* custom listchars and showbreak
+
+---
+
+## **Agent Behaviour Expectations**
+
+### ✔ The AI should:
+
+* provide modern Neovim/Lua solutions
+* avoid legacy Vimscript unless explicitly requested
+* help translate old behaviours into clean Lua equivalents
+* help structure the new config modularly
+* help migrate step-by-step
+* explain trade-offs briefly if necessary
+* prioritise simplicity and maintainability
+* ensure plugin configs are minimal and only include what is required
+
+### ✘ The AI should **NOT**:
+
+* reintroduce old Vimscript workarounds
+* over-engineer or over-automate
+* add plugins I did not ask for
+* suggest plugin-heavy “mega-setups”
+* attempt to recreate VS Code behaviour unless requested
+* produce large complex boilerplate unless requested
+
+---
+
+## **Config Structure I Want**
+
+I strongly prefer very modular config files.
+Plugin specific settings should be kept in the plugin config files where possible.
+
+```
+~/.config/nvim/
+│
+├── init.lua                  → loads everything
+│
+├── lua/
+│   ├── settings.lua          → non-plugin options only
+│   ├── keymaps.lua           → non-plugin keymaps
+│   ├── autocmds.lua          → non-plugin autocommands
+│   ├── utils.lua             → helper fns if needed
+│   │
+│   ├── plugins/
+│   │   ├── init.lua          → optional, can load automatically
+│   │   ├── neo-tree.lua
+│   │   ├── telescope.lua
+│   │   ├── treesitter.lua
+│   │   ├── cmp.lua
+│   │   ├── lsp.lua
+│   │   ├── copilot.lua
+│   │   ├── ufo.lua
+│   │   ├── gitsigns.lua
+│   │   ├── markdown.lua
+│   │   └── …
+```
+
+Each plugin file returns one table:
+
+```lua
+return {
+  "nvim-telescope/telescope.nvim",
+  keys = { ... },
+  opts = { ... },
+  config = function(_, opts)
+    require("telescope").setup(opts)
+  end
+}
+```
+
+The AI can help refine this structure but should keep it simple.
+
+---
+
+## **My Workflow Requirements**
+
+* Tab-per-context workflow
+* Each tab has its own Neo-tree root
+    - one keymap for floating Neo-tree
+    - one keymap neo-tree sidebar toggle
+    - i would like previews of files activated via keymap (not auto preview)
+    - i would like previewed files to not clutter the buffer list.
+* Splits stay inside tabs
+* Telescope + LSP jump for navigation
+* Heavy HTML/PHP/JS/Markdown usage (WordPress plugin dev)
+* Copilot for completion
+* No LSP-overconfiguration
+
+---
+
+## **End Goal**
+
+A clean Neovim setup with:
+
+* fast startup
+* minimal but powerful plugins
+* strong WordPress/PHP workflow
+* organised code navigation
+* modern folding & UI
+* no legacy cruft
+* easy maintenance