# Agent Instructions

## Project Context

Personal dotfiles managed with **chezmoi** + **Nix Home Manager** on macOS.

- Source: `~/.local/share/chezmoi/`
- Applied to: `~/` via `chezmoi apply`
- Files ending in `.tmpl` use Go templating — never edit deployed files directly, always edit the source in chezmoi
- Encrypted files use age — add with `chezmoi add --encrypt <file>`
- Nix packages: `private_dot_config/home-manager-flake/packages.nix.tmpl`
- AI tools install script: `.chezmoiscripts/darwin/run_onchange_after_11-ai-tools.sh.tmpl`

## Safety Rules (always follow)

- Never run `chezmoi apply` without showing `chezmoi diff` first and getting confirmation
- Never commit without explicit user request
- Never use `git add -A` or `git add .` — stage specific files only
- Never skip hooks (`--no-verify`)
- Never force push
- Never edit files in `~/` directly — always edit the chezmoi source

## Template Conventions

When creating `.tmpl` files, always include the correct Emacs mode line on line 1:
- `*.el.tmpl` → `;;; filename.el -*- mode: emacs-lisp; lexical-binding: t; -*-`
- `*.sh.tmpl` → `# filename.sh -*- mode: sh; lexical-binding: t; -*-`
- `*.nix.tmpl` → `# -*- mode: nix; -*-`
- `*.yml.tmpl` / `*.yaml.tmpl` → `# -*- mode: yaml; -*-`
- `*.toml.tmpl` → `# -*- mode: conf-toml; -*-`

---

## Agents

### dotfiles — Modify any dotfile config

1. Ask what the user wants to change
2. Find the relevant file in `private_dot_config/` using glob/search
3. Read the current file to understand structure and conventions
4. Make the edit in the chezmoi source (never the deployed file)
5. Run `chezmoi diff` and show the output
6. Wait for confirmation, then run `chezmoi apply`

### add-nix-package — Add a package to Home Manager

1. Search nixpkgs to confirm the package name: `nix search nixpkgs <name>`
2. Open `private_dot_config/home-manager-flake/packages.nix.tmpl`
3. Find the appropriate category section (or create one)
4. Add the package with a short inline comment
5. Run `make hm_diff` and show output
6. Wait for confirmation, then run `make hm_update`
7. If `flake.lock` changed, run `make hm_commit`

### hm-update — Update Home Manager packages

1. Run `make hm_diff` and show output
2. Wait for confirmation
3. Run `make hm_update`
4. If `flake.lock` changed, ask user if they want to commit it with `make hm_commit`
5. If update fails, suggest `make hm_rollback`

### add-ai-tool — Add a new AI CLI tool

1. Check if it's available in nixpkgs: `nix search nixpkgs <name>`
2. If in nixpkgs and stable: add to `packages.nix.tmpl` under `# ── AI & LLM Tools`
3. If npm-based or needs latest version: add to `.chezmoiscripts/darwin/run_onchange_after_11-ai-tools.sh.tmpl` under the npm tools section
4. If curl installer: add a new section in the ai-tools script following the same pattern as Claude Code
5. Run `chezmoi diff`, confirm, then `chezmoi apply`