dots
/
nvim
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

consolidate and update agent instruction files

This commit is contained in:
Ray Elliott 2026-01-05 20:31:36 +00:00
parent 025222da2a
commit 7a98fa5b5c
3 changed files with 56 additions and 175 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
.github/copilot-instructions.md vendored
View File

@ -1,183 +1,27 @@
# Neovim Config - AI Agent Instructions # Neovim Config - AI Agent Instructions
## Project Overview **All agent instructions are in `AGENTS.md` at the repository root.**
Modern Lua-first Neovim configuration using lazy.nvim, currently in active migration from legacy Vimscript. Target: minimal, fast, tab-per-context workflow with Neo-tree, Telescope, LSP, and Copilot.
**Critical**: Read `AGENTS.md` first—it defines all coding rules, migration strategy, and what NOT to reintroduce. This file exists to satisfy GitHub Copilot's convention of looking for instructions in `.github/copilot-instructions.md`.
## Architecture & Files ## Quick Reference
``` - **Primary instructions**: See `/home/ray/.config/nvim/AGENTS.md`
~/.config/nvim/ - **Migration plan**: See `MIGRATION_PLAN.md`
├── init.lua # Entry point: loads settings/keymaps/autocmds, bootstraps lazy.nvim - **Decision log**: See `LOG.md`
├── lua/ - **Keymap reference**: See `README.md`
│ ├── settings.lua # Non-plugin vim options (exrc, secure, spelllang, listchars)
│ ├── keymaps.lua # Non-plugin keymaps
│ ├── autocmds.lua # Non-plugin autocommands
│ ├── abbreviations.lua # Insert-mode abbreviations (typo corrections)
│ ├── netrw-config.lua # Netrw configuration
│ └── plugins/ # One file per plugin/domain (lazy.nvim specs)
│ ├── lsp.lua # LSP via vim.lsp.config + vim.lsp.enable (Neovim 0.11+)
│ ├── cmp.lua # Completion: nvim-cmp + LuaSnip
│ └── mason*.lua # LSP server installation
├── AGENTS.md # PRIMARY: All rules, migration plan, do-not-reintroduce list
├── MIGRATION_PLAN.md # Phase-by-phase checklist (source of truth for progress)
├── LOG.md # Decision log and design rationale
└── legacy/ # Archived Vimscript (do not edit; reference only)
```
## Critical Patterns ## Key Rules (Summary)
### 1. LSP Configuration (Phase 3 Complete) 1. **Read `AGENTS.md` first** - it contains all coding rules, architecture decisions, and what NOT to reintroduce
**Modern API (Neovim 0.11+)**: Uses `vim.lsp.config()` + `vim.lsp.enable()`, NOT `require('lspconfig')[server].setup()`. 2. **Update docs after changes**:
- Config changes → update `MIGRATION_PLAN.md`
- Decisions → update `LOG.md`
- Keymap changes → update `README.md`
3. **Modern Lua-first**: Use `vim.opt`, `vim.keymap.set`, `vim.api` - avoid Vimscript
4. **LSP (Neovim 0.11+)**: Use `vim.lsp.config()` + `vim.lsp.enable()`, NOT lspconfig `.setup()`
5. **Project config**: Native `exrc` + `secure`, no neoconf plugin
6. **No new plugins** without explicit user approval
**CRITICAL (2025-12-07)**: Neovim 0.11+ does NOT support `on_new_config` callback. Use `LspAttach` autocmd instead. For complete details, workflow requirements, architecture decisions, and troubleshooting, see `AGENTS.md`.
```lua
-- lua/plugins/lsp.lua pattern:
-- Define config
vim.lsp.config(server_name, {
capabilities = capabilities,
-- NO on_attach here, NO on_new_config here
})
-- Enable server
vim.lsp.enable({ "lua_ls", "intelephense", ... })
-- Load project settings via LspAttach autocmd
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
-- Load .nvim.lua from client.root_dir
-- Merge into client.settings
-- Send workspace/didChangeConfiguration notification
end,
})
```
**Key decisions**:
- No neoconf (incompatible with Neovim 0.11+, issue #116)
- Native `exrc` + `secure` for project config (see settings.lua)
- Project settings loaded via `LspAttach` autocmd (NOT `on_new_config` which is deprecated)
- `workspace/didChangeConfiguration` sent after merging settings into `client.settings`
### 2. Project-Local Configuration
**Format**: `.nvim.lua` at project root, returns:
```lua
return {
lsp = {
intelephense = {
settings = {
intelephense = {
environment = {
includePaths = { "/absolute/path/to/external/lib" }
}
}
}
}
}
}
```
**Security**: `vim.opt.secure = true` prompts user before loading (one-time per file hash). Trusted files stored in `~/.local/state/nvim/trust`.
### 3. Plugin Management
- **lazy.nvim**: All plugins in `lua/plugins/` as individual files returning spec tables
- **Mason**: Installs LSP servers only; custom lspconfig setup retained
- **Plugin specs**: Use `opts = {}` for defaults, `config = function(_, opts)` for setup
- **Approval policy**: Do not install unlisted plugins without explicit user confirmation
### 4. Tab-Per-Context Workflow (Future Phase 4)
- Each tab maintains own Neo-tree root
- Splits stay within tabs
- Neo-tree: sidebar toggle + floating view + preview (no buffer pollution)
- Heavy PHP/HTML/JS/Markdown usage (WordPress plugin dev)
## Conventions
### Code Style
- **Lua APIs only**: `vim.opt`, `vim.keymap.set`, `vim.api.nvim_create_autocmd`
- **No Vimscript**: Avoid `vim.cmd` blocks unless strictly necessary
- **Keymaps**: `{ silent = true, noremap = true }` by default
- **Autocommands**: Group via `vim.api.nvim_create_augroup`, narrow scope
### File Organization
- One plugin = one file in `lua/plugins/`
- Keep plugin config self-contained in its spec
- Settings/keymaps/autocmds: only non-plugin logic in respective files
- No global state; return tables from modules
### Migration Process
1. Check `MIGRATION_PLAN.md` for current phase and priorities
2. **Before large changes**: Update plan via CLI `update_plan` tool (if available)
3. **After any change**: Immediately update `MIGRATION_PLAN.md` (check off items, add notes)
4. **After decisions**: Update `LOG.md` decisions log
5. **After adding/removing/editing any keymaps**: Immediately update `README.md` with the change (add new entries, remove deleted mappings, or update descriptions)
6. Execute phases via subphases (N.x); one bullet = one implement-and-test step
7. Archive legacy files to `legacy/` instead of deleting
## Do NOT Reintroduce (from AGENTS.md)
- Custom Vimscript tabline/statusline/foldtext
- Legacy autocommands (cursorline/column per window)
- CoC or CoC-specific config
- netrw settings (Neo-tree replaces it)
- Providers for ruby/perl/node (disabled unless required)
- Auto-reload vimrc-on-write templates
- `cursorcolumn` and old folding logic (UFO will handle folding)
- neoconf plugin (incompatible with Neovim 0.11+)
## Developer Workflows
### Testing Changes
```bash
# Quick syntax check
nvim --headless -c 'lua print("Config loads")' -c 'quitall'
# Check LSP status in test workspace
cd ~/.config/nvim/WORKSPACE_TEST
nvim site/external.php # Then :LspInfo
# Validate goto-definition for external libs
# In external.php, cursor on Util::greetExternal, press gd
```
### Validation Workspaces
- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git`
- `EXTERNAL_TEST/`: External library referenced via includePaths
- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST
### Current Migration Status (as of 2025-12-07)
- ✅ Phase 1-2: Archive legacy, bootstrap lazy.nvim
- ✅ Phase 3: Core editing & LSP complete
- Settings, completion, LSP servers, Mason installed
- Native exrc + vim.lsp.config migration done
- Project-local `.nvim.lua` working
- ⏸️ Phase 4+: Navigation (Neo-tree, Telescope), Treesitter, UX plugins pending
## Integration Points
### External Dependencies
- **Neovim 0.11+**: Required for `vim.lsp.config` API
- **LSP Servers** (via Mason): lua_ls, ts_ls, html, cssls, jsonls, bashls, marksman, intelephense
- **PHP**: intelephense with `single_file_support = false`, uses `environment.includePaths` for external libs
### Cross-Component Communication
- LSP settings flow: `.nvim.lua` → `on_new_config` → `new_config.settings` → `workspace/didChangeConfiguration`
- Completion: cmp-nvim-lsp provides capabilities → lspconfig → LSP servers
## Common Issues
### lua_ls Won't Start
Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead.
### LSP Root Detection
If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root.
### Duplicate gd Results (Fixed)
Was caused by settings loading at wrong time; fixed by using `on_new_config` with actual `root_dir`.
## When Stuck
1. Check `MIGRATION_PLAN.md` for known issues and current phase
2. Review `AGENTS.md` for rules about what to avoid
3. Read `LOG.md` decisions log for context on past choices
4. Validate with test workspaces before modifying production config

37
AGENTS.md
View File

@ -158,6 +158,43 @@ This repository is being migrated to a modern, minimal Neovim setup driven by Lu
- **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag - **Features**: Incremental selection (CR/BS), textobjects (functions, classes, parameters), autotag
- **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm` - **Custom queries**: `after/queries/css/highlights.scm`, `after/queries/html/highlights.scm`
### Session Management
- **Auto-load**: On `VimEnter`, loads `Session.vim` if it exists (unless files specified on command line)
- **Auto-save**: On `VimLeavePre`, saves to `Session.vim` if it already exists
- **Manual control**: Create with `:mksession` to enable; delete to disable
- **Per-directory**: Sessions are opt-in and workspace-specific
## Developer Workflows
### Testing Changes
```bash
# Quick syntax check
nvim --headless -c 'lua print("Config loads")' -c 'quitall'
# Check LSP status in test workspace
cd ~/.config/nvim/WORKSPACE_TEST
nvim site/external.php # Then :LspInfo
# Validate goto-definition for external libs
# In external.php, cursor on Util::greetExternal, press gd
```
### Validation Workspaces
- `WORKSPACE_TEST/`: PHP project with `.nvim.lua` and `.git`
- `EXTERNAL_TEST/`: External library referenced via includePaths
- Test that `gd` resolves symbols in EXTERNAL_TEST from WORKSPACE_TEST
## Common Issues
### lua_ls Won't Start
Mason-installed lua_ls may fail with missing `libbfd-2.38-system.so`. Install via system package manager instead.
### LSP Root Detection
If parent repo picked as root, create empty `.git` or `.nvimroot` marker in intended workspace root.
### Duplicate gd Results (Fixed)
Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd with actual `root_dir`.
## Process ## Process
- Before large changes, update the task plan via the CLI `update_plan` tool. - 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. - Keep the live checklist in `MIGRATION_PLAN.md:1` up to date and in sync with changes.

2
REGRESSION_FIX_2025-12-07.md
View File

@ -110,7 +110,7 @@ vim.api.nvim_create_autocmd('LspAttach', {
## Documentation Updated ## Documentation Updated
- `LOG.md`: Added decision log entry for 2025-12-07 - `LOG.md`: Added decision log entry for 2025-12-07
- `.github/copilot-instructions.md`: Documents LspAttach pattern - `.github/copilot-instructions.md`: Now a simple pointer to AGENTS.md
- `AGENTS.md`: Already notes "Native exrc + vim.lsp.config migration done" - `AGENTS.md`: Already notes "Native exrc + vim.lsp.config migration done"
## Prevention ## Prevention