# Repository Guidelines

## Project Structure & Module Organization
- `init.lua` sets core options (tab width 2, tabs preserved) and wires `config.lazy`, `config.mappings`, and `config.autocmd`.
- `lua/config/` holds shared behavior: `lazy.lua` bootstraps lazy.nvim and leaders, `mappings.lua` defines keys, `autocmd.lua` holds events and filetype tweaks.
- `lua/plugins/` contains one-file-per-topic plugin specs for lazy.nvim; add new plugins here using a returned table.
- `lazy-lock.json` pins plugin revisions; update only when deliberately bumping dependencies.
- `spell/` contains custom spelling wordlists loaded by the config.

## Build, Test, and Development Commands
- Install/sync plugins: `nvim --headless "+Lazy sync" +qa` (also respects `lazy-lock.json`).
- Check runtime health: `nvim --headless "+checkhealth" +qa`.
- Minimal repro session: `nvim --clean -u init.lua` from the repo root.
- Format Lua locally when available: `stylua lua` (uses conform.nvim/stylua in-editor).

## Coding Style & Naming Conventions
- Lua uses tabs with a visual width of 2 (`noexpandtab`, `tabstop=2`, `shiftwidth=2`).
- Prefer readable tables with trailing commas and module-level `return { ... }` style for plugin specs.
- Name plugin files by feature (`lua/plugins/telescope.lua`, `lua/plugins/git.lua`); keep config helpers in `lua/config/`.
- Keep user-facing strings concise; avoid hardcoding machine-specific paths beyond `$HOME`.

## Testing Guidelines
- After changes, run `nvim --headless "+Lazy sync" +qa` to ensure specs load and dependencies resolve.
- Run `nvim --headless "+checkhealth" +qa` to catch missing tools (e.g., `stylua`, `rustfmt`, `typstyle`, `styler` for R).
- For keymap or autocmd changes, open a clean session (`nvim --clean -u init.lua`) and exercise the affected commands or filetypes.

## Commit & Pull Request Guidelines
- Recent history favors brief, present-tense summaries (e.g., `update LSP`, `buffer`); keep subjects under ~50 characters.
- When adding plugins or mappings, mention the feature in the subject and note key bindings or defaults in the body.
- For pull requests, include: what changed, why it helps editing workflows, any new dependencies, and screenshots/gifs if UI-facing (statusline, dashboard).
- If you update `lazy-lock.json`, call that out explicitly and describe any notable plugin upgrades or breaking changes.

## Security & Configuration Tips
- Do not commit API keys or machine-specific credentials; prefer environment variables consumed by plugins when needed.
- Keep external tooling installs (Mason, system packages) documented so others can reproduce formatter/linter availability.
- Avoid introducing autocmds or keymaps that shadow common defaults without noting the rationale in `lua/config/mappings.lua`.