# AGENTS.md - LazyVim Configuration Guide

This document provides essential information for AI agents working with this LazyVim Neovim configuration.

## Overview

This is a LazyVim-based Neovim configuration located at `/Users/alice/.config/nvim`. LazyVim is a Neovim distribution that provides a solid foundation for modern Neovim development with lazy loading and sensible defaults.

## Project Structure

```
~/.config/nvim/
├── init.lua                 # Main entry point
├── lazy-lock.json          # Plugin version lock file
├── lazyvim.json            # LazyVim configuration
├── stylua.toml             # Lua code formatter config
├── lua/
│   ├── config/
│   │   ├── autocmds.lua    # Auto commands
│   │   ├── keymaps.lua     # Key mappings
│   │   ├── lazy.lua        # Lazy.nvim setup
│   │   └── options.lua     # Neovim options
│   └── plugins/
│       ├── example.lua     # Example plugin configuration
│       ├── general.lua     # General plugins (tmux-navigator)
│       ├── harpoon.lua     # Harpoon file navigation
│       └── ui.lua          # UI plugins (catppuccin theme)
```

## Key Configuration Details

### LazyVim Version
- **Version**: 8
- **Install Version**: 8
- **Extras**: JSON, Markdown, and Python language support

### Plugin Management
- Uses [lazy.nvim](https://github.com/folke/lazy.nvim) for plugin management
- Plugins are lazy-loaded by default for performance
- Auto-updates are enabled but notifications are disabled

### Custom Plugins

#### 1. **Harpoon** (`lua/plugins/harpoon.lua`)
- **Purpose**: Fast file navigation and project management
- **Key Bindings**:
  - `<leader>H`: Add current file to harpoon
  - `<leader>h`: Toggle harpoon quick menu
  - `<leader>1-9`: Jump to harpoon file 1-9
- **Configuration**: Auto-save on toggle, dynamic menu width

#### 2. **Tmux Navigator** (`lua/plugins/general.lua`)
- **Purpose**: Seamless navigation between Neovim and tmux panes
- **Commands**: TmuxNavigateLeft/Down/Up/Right/Previous

#### 3. **Catppuccin Theme** (`lua/plugins/ui.lua`)
- **Purpose**: Modern, beautiful color scheme
- **Theme**: catppuccin-frappe (default)
- **Features**: Extensive integration with LSP, treesitter, and other plugins

## Important Files for Agents

### Configuration Files
- `init.lua`: Entry point - just loads `config.lazy`
- `lua/config/lazy.lua`: Main lazy.nvim configuration
- `lua/config/options.lua`: Neovim options and settings
- `lua/config/keymaps.lua`: Key mappings and shortcuts
- `lua/config/autocmds.lua`: Auto commands and file type settings

### Plugin Files
- Each file in `lua/plugins/` represents a plugin or group of related plugins
- Plugin configurations return a table with plugin specifications
- Use `lazy = true` for lazy loading, `lazy = false` for immediate loading

## Development Guidelines for Agents

### 1. **Adding New Plugins**
```lua
-- In lua/plugins/your-plugin.lua
return {
  {
    "author/plugin-name",
    version = "*", -- or specific version
    lazy = true,   -- or false for immediate loading
    opts = {
      -- plugin options
    },
    keys = {
      -- key mappings
    },
  },
}
```

### 2. **Modifying Existing Plugins**
- Edit the corresponding file in `lua/plugins/`
- Use `opts` table to override default options
- Use `keys` table to add custom key mappings

### 3. **Key Mapping Conventions**
- Leader key is typically `<leader>` (usually space)
- Use descriptive `desc` fields for all key mappings
- Group related mappings in the same plugin file

### 4. **LazyVim Integration**
- LazyVim provides many built-in plugins and configurations
- Use `LazyVim/LazyVim` import to access core functionality
- Override LazyVim defaults in your plugin files

## Common Tasks for Agents

### Adding Language Support
1. Check if LazyVim already provides the language support
2. If not, add language-specific plugins to `lua/plugins/`
3. Configure LSP, treesitter, and other language tools

### Customizing UI
1. Modify `lua/plugins/ui.lua` for theme changes
2. Add statusline, bufferline, or other UI plugins
3. Configure colorscheme in the LazyVim options

### Adding Key Mappings
1. Add global mappings to `lua/config/keymaps.lua`
2. Add plugin-specific mappings in the plugin file
3. Use `vim.keymap.set()` for modern key mapping

### Performance Optimization
1. Ensure plugins are properly lazy-loaded
2. Use `lazy = true` for non-essential plugins
3. Configure `cmd`, `event`, or `ft` triggers for lazy loading

## Troubleshooting

### Plugin Issues
- Check `lazy-lock.json` for version conflicts
- Use `:Lazy` to manage plugins interactively
- Check `:checkhealth` for system issues

### Configuration Issues
- Validate Lua syntax with `:luafile %`
- Check for circular dependencies in plugin imports
- Use `:LazyVim profile` for performance analysis

## Resources

- [LazyVim Documentation](https://lazyvim.github.io/)
- [lazy.nvim Documentation](https://github.com/folke/lazy.nvim)
- [Neovim Lua Guide](https://neovim.io/doc/user/lua-guide.html)

## Notes for AI Agents

- This configuration is optimized for modern Neovim development
- Always test changes in a safe environment before applying
- Respect the existing code style and structure
- Use descriptive commit messages when making changes
- Consider performance implications of new plugins