nvim/AGENTS.md

AGENTS: Neovim Configuration

Scope: the entire ~/.config/nvim repository.

Current setup

This is the active, daily-use Neovim 0.12 configuration. It is Lua-first, managed with lazy.nvim, and intended to remain small, fast, and maintainable.

The main workflows are:

• netrw for tree browsing, previews, and file operations
• Telescope for fuzzy files, grep, buffers, and symbols
• native vim.lsp.config() / vim.lsp.enable() configuration
• native insert-mode completion and snippets
• Copilot inline suggestions, separate from the completion menu
• Tree-sitter, Conform, nvim-lint, Gitsigns, and nvim-ufo
• native nvim.undotree
• project-local .nvim.lua files through native exrc + secure

README.md documents the user-facing workflows and keymaps. LOG.md records architectural decisions.

Maintenance rules

• Prefer Lua APIs such as vim.opt, vim.keymap.set, and vim.api.nvim_create_autocmd; use Vimscript only when a native integration requires it.
• Keep non-plugin behavior in focused modules under lua/.
• Keep each plugin specification self-contained under lua/plugins/.
• Continue using lazy.nvim; do not mix plugin managers without an explicit decision to migrate.
• Do not add a plugin without explicit user confirmation.
• Keep netrw as the sole file explorer and Telescope as the fuzzy navigator.
• Use Neovim's native completion rather than reintroducing nvim-cmp or LuaSnip.
• Keep Copilot as inline suggestions rather than a completion-menu source.
• Use the modern LSP API; do not restore legacy lspconfig.setup() calls or neoconf.
• Preserve native project-local configuration through exrc + secure.
• Keep providers for Ruby, Perl, and Node disabled unless an active plugin requires one.
• Preserve the existing Lua tabline, but do not restore the old Vimscript tabline/statusline, foldtext, cursorline/column window hacks, CoC, Neo-tree, motion plugins, or Markdown rendering plugins unless the user explicitly revisits those decisions.
• Preserve unrelated user changes and keep patches narrowly scoped.

Documentation and validation

• Update README.md whenever user-facing behavior or keymaps change.

• Update its configuration section when formatter, linter, or tool resolution changes.

• Record significant architectural decisions in LOG.md.

• After configuration or plugin changes, run at least:

  nvim --headless -c 'lua print("Config loads")' -c 'quitall'
  

• For relevant changes, also exercise the affected workflow interactively.

History

This configuration began as a large Vimscript setup with bundled plugins and was incrementally rebuilt as a modern Lua configuration. The migration covered lazy.nvim, native LSP and project configuration, native completion and Undotree, Telescope, a netrw-centered explorer workflow, Tree-sitter, Copilot, formatting, linting, and the Paper Tonic colorscheme. After sustained daily use on Neovim 0.12.6, the migration was declared complete on 2026-10-28. The decision history remains in LOG.md and Git history.