# ✔ **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 colour scheme used but modernise it if needed.

---

## **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
* install any plugin not listed without explicit confirmation
* 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