# AGENTS.md - Neovim Configuration Guide

## Overview
This is a kickstart.nvim fork - a modular Neovim configuration written in Lua. Code is organized in:
- `/init.lua` - Main entry point (kept concise for learning)
- `/lua/custom/` - User custom configurations and plugins
- `/lua/kickstart/` - Core plugin configurations

## Code Style Guidelines

### Lua Formatting
- **Formatter**: Stylua (enforced via CI)
- **Config**: `.stylua.toml` (column_width=160, indent=2 spaces, auto quote style)
- **Command**: `stylua .` to format all files, `stylua --check .` to verify

### Code Conventions
- **Imports**: Use `require()` to load modules; prefer relative paths from `/lua/`
- **Comments**: Use `--` for single-line, `--[[` for block comments; include URLs for plugins
- **Naming**: snake_case for variables/functions, PascalCase for classes
- **Lua tables**: Preferred data structure; use clear key names
- **Error handling**: Use `pcall()` for risky operations; fail gracefully with fallbacks

### Plugin Structure
- Each plugin is a separate file returning a table with name, dependencies, config
- Use `event`, `cmd`, `ft` keys for lazy-loading optimization
- Config functions should be self-contained and well-commented

## Build/Lint/Test Commands

### Format & Lint
```bash
# Format all Lua files
stylua .

# Check formatting without changing files
stylua --check .

# Format specific file
stylua path/to/file.lua
```

### No traditional tests
This is a configuration repo, not a testable library. Validation is manual:
- Start Neovim: `nvim` 
- Check `:Lazy` status for plugin errors
- Review `:checkhealth` for configuration issues
- Test manually in editor to verify keymaps/features work

### Linting
- Neovim's built-in Lua LSP provides type checking (integrated via plugin)
- The GitHub Actions workflow runs `stylua --check` on PRs

## Key Notes
- **Language**: Lua 5.1+ (Neovim's version)
- **No external build process**: Configuration is interpreted at runtime
- **Plugin manager**: Lazy.nvim (auto-installs missing plugins on startup)
- **Target**: Latest Neovim stable + nightly versions