From 6f73aa2f82df7b36ebc399a28a9e79f8a942a2a4 Mon Sep 17 00:00:00 2001
From: Prad Nukala <prad@sonr.io>
Date: Fri, 16 Oct 2026 11:51:11 -0400
Subject: [PATCH] docs(agents): add AGENTS.md documentation

---
 AGENTS.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2c70376
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,65 @@
+# AGENTS.md
+
+chezmoi source for `$HOME`. `mode = "symlink"`: plain files in `$HOME` are symlinks into this repo, so editing `~/.config/foo/bar` edits `dot_config/foo/bar` directly. Templates (`*.tmpl`), `private_`, `executable_` targets are rendered copies — edit the source, then `chezmoi apply`.
+
+Config lives in three places. Check which one before editing.
+
+## 1. Local (this repo)
+
+`dot_*` trees committed here. Edit in place, commit here. Docs for each tool are in `docs/`; update the matching page when behavior changes.
+
+- Never edit a rendered copy of a `.tmpl`; edit the `.tmpl` and run `chezmoi apply <path>`.
+- Scripts: `.chezmoiscripts/run_*`. Data: `.chezmoidata/*.yaml` (packages, aliases, skills).
+- Ignore rules: `.chezmoiignore.tmpl`. Repo docs (`AGENTS.md`, `README.md`, `docs/`) are listed there so they never land in `$HOME`.
+
+## 2. Submodules (`.gitmodules`)
+
+| Path | Repo |
+| --- | --- |
+| `dot_config/fish` | prdlk/fish |
+| `dot_config/hypr` | prdlk/hypr |
+| `dot_config/niri` | prdlk/niri |
+
+Still applied by chezmoi like local files, but the git history is separate:
+
+1. `cd dot_config/<app>`, edit, commit, push there.
+2. `cd` back to the root and commit the updated submodule pointer.
+
+Fresh clone: `git submodule update --init`.
+
+## 3. Externals (`.chezmoiexternals/*.toml`, `.chezmoiexternal.toml`)
+
+`git-repo` externals. chezmoi clones them into `$HOME` when missing and fast-forwards (`--ff-only`) at most every `refreshPeriod`. The source tree holds nothing for these — only the `.toml`.
+
+| Target | Repo | Declared in |
+| --- | --- | --- |
+| `~/.config/kitty` | prdlk/kitty | `.chezmoiexternals/kitty.toml` |
+| `~/.config/ghostty` | prdlk/ghostty | `.chezmoiexternals/ghostty.toml` |
+| `~/.config/tmux` | prdlk/tmux | `.chezmoiexternals/tmux.toml` |
+| `~/.config/tmux-palette` | prdlk/tmux-palette | `.chezmoiexternals/tmux-palette.toml` |
+| `~/.config/television` | prdlk/television | `.chezmoiexternals/television.toml` |
+| `~/.config/yazi` | prdlk/yazi | `.chezmoiexternals/yazi.toml` |
+| `~/.omp` | prdlk/omp | `.chezmoiexternals/omp.toml` |
+| `~/.config/nvim` | prdlk/nvim | `.chezmoiexternal.toml` (no refresh; local checkout wins) |
+| `~/.config/tmux/plugins/tpm` | tmux-plugins/tpm | `.chezmoiexternal.toml` |
+| `~/.config/bat/syntaxes/sublime-purescript-syntax` | tellnobody1/… | `.chezmoiexternal.toml` |
+
+Editing: `cd ~/.config/<app>` (the live checkout), edit, commit, push there. Nothing to commit in this repo. Do not `chezmoi add` these paths.
+
+Local working copies under `~/Code/github.com/prdlk/<app>` are ordinary clones of the same repos; `~/.config/<app>` is the one chezmoi manages and the one tools read.
+
+Pulling a remote change before the refresh window: `chezmoi apply --refresh-externals ~/.config/<app>` (or `git pull` in the checkout). `--ff-only` means a diverged local checkout silently stays put — commit or stash first.
+
+## Moving a config out to an external
+
+1. Create the repo, copy the files (strip chezmoi prefixes; a `symlink_x` file becomes a real symlink), commit, push.
+2. Add `.chezmoiexternals/<app>.toml` copying `tmux.toml`.
+3. `git rm -r dot_config/<app>`; drop any `<app>`-specific lines from `.chezmoiignore.tmpl` / `.gitignore`.
+4. `mv ~/.config/<app> /tmp/bak && chezmoi apply --force ~/.config/<app>`; diff against the repo, then delete the backup.
+5. Update `docs/` (the tool's page, `docs/terminal/index.mdx` or sibling index, `docs/chezmoi/externals-and-ignore.mdx`) and any alias pointing at the old source path (`dot_config/fish/conf.d/20-aliases.fish`, `.chezmoidata/aliases.yaml`).
+
+## Verify
+
+- `chezmoi diff` empty after apply.
+- `chezmoi managed | grep <app>` shows the target.
+- Externals: `git -C ~/.config/<app> status -sb` clean and tracking `origin/main`.