# 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:

  ```bash
  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.