AGENTS.md git:20260928.2c5b6b7A

Immutable. This exact content never changes and is served at /api/v1/blob/52a231e62bde7e6e.

# Chezmoi Dotfiles Repository

This repo manages `~` via chezmoi. Edit source files here, run `chezmoi apply` to deploy.

**No pull requests — deploy is the ship step.** Land changes with `chezmoi-deploy <branch>`: it fast-forward-merges the branch into the primary checkout's `main`, runs `chezmoi apply`, and pushes `main` to origin as a mirror. Only `chezmoi apply` mutates your live `~`. Load the chezmoi skill for verify-render-only and deploy mechanics.

**`chezmoi apply` auto-deploys and reloads changed LaunchAgents.** The source template `.chezmoiscripts/run_onchange_after_zz-launch-agents.sh.tmpl` is the generator; during apply, chezmoi renders and runs that template after package installation, then it delegates to `launchd-yaml apply` to render every plist from `dot_config/launchd-yaml/agents.yaml.tmpl` (yq → plutil), reload only agents whose plist content actually changed, and prune agents deleted from the YAML — so unchanged agents are never restarted. The individual plists are NOT chezmoi-managed; the generator owns them.

## Structure

- **`dot_*`** — home directory files and directories (shell, git, editors, app configs)
- `dot_config/omp/private_agent/` manages OMP config under `~/.config/omp/agent/`; `PI_CONFIG_DIR=.config/omp` selects the global root and `PI_CODING_AGENT_DIR` selects the agent path for shells, AoE sessions, and LaunchAgents.
- **`.chezmoidata/mcp.yaml`** — neutral MCP server data rendered into OMP templates.
- **`dot_agents/skills/`** — authored agent skills managed natively at `~/.agents/skills/`; externally installed skills own separate sibling directories.
- **`dot_config/launchd-yaml/agents.yaml.tmpl`** — macOS services (scheduled jobs and daemons) defined declaratively; deployed, reloaded, and pruned by `.chezmoiscripts/run_onchange_after_zz-launch-agents.sh.tmpl`, which chezmoi renders and runs during apply. Individual plists are not chezmoi-managed.
- **`.chezmoidata/packages.yaml`** — single package registry: brew, cask, mise (including Python tools), github releases
- **`.chezmoidata/local.yaml`** — private machine and organization data, including model defaults and per-org overrides; gitignored and represented publicly only by `local.yaml.example`.
- **`dot_config/cal/private_config.json.tmpl`** — renders the private XDG config for standalone cal from gitignored local data; the package itself does not read chezmoi data.
- **`.chezmoiexternal.toml.tmpl`** — generated from packages.yaml, drives chezmoi-native GitHub release downloads
- **`.chezmoiscripts/`** — run on apply only where generation or an external installer is required

## Packages

All packages are declared in `.chezmoidata/packages.yaml` under `brews`, `casks`, `mise`, `github_releases`, or `aoe_plugins` (aoe/Agent of Empires plugins, installed/updated via `run_onchange_after_plugins-aoe.sh.tmpl`). The install scripts and external file are generated from it — edit only the registry.

## Agent Config

dot_config/omp/private_agent/private_config.yml directly manages ~/.config/omp/agent/config.yml. dot_config/omp/private_agent/APPEND_SYSTEM.md owns its system prompt.

## Public Repo — Privacy Guidelines

This is a **public repository**. Before committing any content, check for:

- **Work-specific content** — employer names, internal project names, org names, team names, internal URLs, internal hostnames, internal tool names. Replace with generic equivalents (e.g. `myapp`, `myorg`, `your-work-email`).
- **Secrets** — API keys, tokens, passwords, credentials. These must never appear in committed files. Use `promptStringOnce` in `.chezmoi.toml.tmpl` and `modify_private_dot_env.tmpl` for anything sensitive.
- **Personal identifiers** — email addresses, Slack user IDs, Linear team IDs, phone numbers. These belong in chezmoi data, not in committed files.
- **Infrastructure details** — internal hostnames, IP ranges, VPN configs, cluster names, cloud project IDs. Keep these in `~/.config/zsh/private.zsh` (not tracked).

When writing skills, examples, or documentation: use generic placeholder names (`myapp`, `myorg`, `your-repo`) rather than real project or employer names.

## README

Keep `README.md` up to date when making structural changes: adding or removing skills, new LaunchAgents, new config sections, changes to the package registry design, or anything that affects how someone would use or contribute to this repo. The README is the primary entry point for external readers.