nvim_config/AGENTS.md

# AGENTS.md

This document is the operating guide for coding agents working in this Neovim
configuration repository.

## Repository Snapshot

- Project type: personal Neovim config (Lua)
- Entry point: `init.lua` -> `lua/core/*` -> `lua/plugins/*`
- Plugin manager: `lazy.nvim`
- No dedicated CI, test suite, formatter config, or lint config is committed
- Primary language: Lua (Neovim runtime APIs)

## Directory Layout

- `init.lua`: bootstrap into core config
- `lua/core/options.lua`: editor options and globals
- `lua/core/keymaps.lua`: global and command keymaps
- `lua/core/lazy.lua`: lazy.nvim bootstrap and setup
- `lua/plugins/init.lua`: plugin spec list
- `lua/plugins/config/*.lua`: per-plugin config modules
- `lua/utils/*.lua`: utility helpers (for example `reload.lua`)

## Build / Lint / Test Commands

There is no Makefile/package manager script layer, so use direct commands.

### Environment checks

- Verify Neovim can start this config:
  - `nvim --headless -u /home/alican/.config/nvim/init.lua +qa`
- Verify plugin bootstrap and lockfile resolution:
  - `nvim --headless -u /home/alican/.config/nvim/init.lua '+Lazy! sync' +qa`
- Optional runtime health checks:
  - `nvim --headless -u /home/alican/.config/nvim/init.lua '+checkhealth' +qa`

### Formatting

- Preferred formatter for Lua: `stylua`
- Format whole repo:
  - `stylua /home/alican/.config/nvim`
- Format a single file:
  - `stylua /home/alican/.config/nvim/lua/plugins/init.lua`

If `stylua` is not installed, do not mass-reformat; preserve existing style in
touched regions only.

### Linting

- No lint config is committed (`.luacheckrc` not found).
- If `luacheck` is available, run ad hoc:
  - `luacheck /home/alican/.config/nvim/lua`
- Treat lint as advisory unless the repository later adds pinned lint rules.

### Testing

- No test framework is currently configured in-repo.
- Use headless startup as the minimum smoke test:
  - `nvim --headless -u /home/alican/.config/nvim/init.lua +qa`

### Running a single test (important)

There are no existing unit/integration test files, so there is no real
single-test command today.

If you add Plenary-based tests, use this pattern for a single test file:

- `nvim --headless -u /home/alican/.config/nvim/init.lua -c "PlenaryBustedFile tests/<name>_spec.lua" -c qa`

If you add a plain Lua test runner later, document exact single-test invocations
here and keep this section updated.

## Code Style Guidelines

Follow local conventions observed in current files first, then these rules.

### Imports and module structure

- Use `require("...")` with explicit module paths.
- Keep imports at top of file unless lazy-loading is intentional.
- Prefer locals for required modules (example: `local cmp = require("cmp")`).
- Return module tables (`local M = {}; ...; return M`) for utility modules.
- Plugin config modules should avoid side effects outside setup behavior.

### Formatting and layout

- Preserve existing indentation style per file (repo currently mixes tabs/spaces).
- Keep lines reasonably short (existing config uses `colorcolumn = "80"`).
- Use trailing commas in multiline Lua tables.
- Keep one logical statement per line.
- Group related options/settings in contiguous blocks.
- Avoid large unrelated reformatting in feature/fix commits.

### Types and annotations

- Lua is dynamically typed here; no strict type checker is configured.
- Keep useful EmmyLua annotations when present (for example `---@type ...`).
- Add annotations only when they improve editor/LSP inference.
- Do not add noisy type comments for obvious locals.

### Naming conventions

- Module/file names: lowercase, path-based (`core.options`, `plugins.config.lsp`).
- Local variables: `snake_case`.
- Exported module tables: `M`.
- User commands: `PascalCase` where already used (`ReloadConfig`).
- Avoid introducing new global functions/variables.
- Exception: if global is required by Vim command callbacks, prefix carefully and
  document intent.

### Neovim API usage

- Prefer modern APIs:
  - `vim.keymap.set` over `vim.api.nvim_set_keymap`
  - `vim.api.nvim_create_user_command` for user commands
- Use buffer-local mappings/options when behavior is buffer-scoped.
- Keep plugin setup isolated in `lua/plugins/config/<plugin>.lua` when practical.
- Keep core bootstrap files (`core/*`) minimal and composable.

### Error handling and resilience

- Fail softly for optional dependencies when reasonable (`pcall(require, ...)`).
- Avoid crashing startup for non-critical plugin behavior.
- Use `vim.notify(..., vim.log.levels.<LEVEL>)` for actionable runtime feedback.
- For external commands in Lua, check return status if failure is meaningful.

### Plugin and dependency changes

- Add/modify plugin specs only in `lua/plugins/init.lua` unless refactoring.
- Keep plugin options in dedicated config modules when they grow beyond trivial.
- For plugins with build hooks (example: markdown preview), do not assume Node/npm
  is available in all environments; mention prerequisites in PR notes.
- Preserve lockfile intent (`lazy-lock.json`) when updating plugin versions.

### Commit hygiene for agents

- Make focused changes with minimal scope.
- Do not fix unrelated style issues opportunistically.
- Include validation notes in your final response (what you ran, what you could
  not run).
- If commands are unavailable locally, state that clearly and provide exact
  follow-up commands.

## Cursor / Copilot Rules

Checked paths:

- `.cursorrules`
- `.cursor/rules/`
- `.github/copilot-instructions.md`

Current status: no Cursor or Copilot instruction files were found in this
repository.

If these files are added later, agents must treat them as higher-priority
repository policy and this document should be updated to summarize them.

## Agent Workflow Checklist

- Read nearby files before editing; match local patterns.
- Keep edits minimal and reversible.
- Run at least one headless Neovim smoke check after non-trivial changes.
- For plugin changes, run `'+Lazy! sync'` headless when possible.
- Update this file when tooling, test framework, or style policy changes.