CONTRIBUTING.md

@@ -455,6 +455,31 @@ via `command`/`builtin` (`bypasses-shadow(cat)`), and general hazards —
 `destructive`, `network`, `blocking-prompt`. Full tag definitions and
 placement rule: [`docs/function-classification-schema.md`](docs/function-classification-schema.md).
 
+### Dedicated manual sections for complex subsystems
+
+A doc-header's `DESCRIPTION` is for that one function's usage — it stops
+being the right place once a subsystem spans several functions, has its
+own file layout, or has enough behavior (a decision table, a safety
+model) that cramming it into one function's header would make that
+header useless as a quick reference. When that happens, give the
+subsystem its own numbered top-level section under `docs/manual/`
+(follow the sibling sections' frontmatter shape: `title`, `manTitle`,
+`sidebar.order`, `helpKeywords`) instead of stretching the header.
+`docs/manual/16-agent-tooling.md` (`agents-init`/`agents-vault`/the
+`AGENTS/` sub-repository) is the existing example — its own doc-headers
+stay short and point there for the full picture, the same way this
+document points at other reference files rather than repeating them.
+
+This is a genuine exception to "the doc-header is the single source of
+truth" above, and it comes with an obligation `verify-manual.py` cannot
+enforce for you: nothing checks that a dedicated section still describes
+the function's *current* behavior. **Whenever you change what one of
+these functions does, update its dedicated section in the same commit or
+pull request** — not as a follow-up. A function with a dedicated section
+should say so in its own `# NOTES` (see `functions/agents-init.fish` for
+the pattern), so a later reader of just the header still finds the fuller
+page.
+
 ### Private/internal helper functions
 
 Functions named with a leading `_` (e.g. `_agents_init_ensure_gitignore`,

docs/manual/16-agent-tooling.md

@@ -220,6 +220,48 @@ warning naming the file and explaining why, rather than staying silent
 about a directory it chose not to touch.
 
 
+## Scenario reference
+
+Every combination of what a directory can hold, laid out directly. "No"
+in the tracked column also covers a tracked file in a project with no
+populated `.gitignore` (the bootstrap case, above) — both behave the same
+way. Whenever the tracked column reads "Yes", that reason always wins
+over the identical-or-different comparison below it, and the warning
+printed names the file as tracked rather than as differing — the outcome
+(left alone) is the same either way, only the explanation differs.
+
+Settling a directory for the first time — a real `AGENTS.md`, a real
+`CLAUDE.md`, both, or neither, discovered fresh:
+
+    Found                             Deliberately tracked?  Result
+    --------------------------------  ---------------------  -----------------------------------------------
+    Only AGENTS.md (real)             No                     Adopted into AGENTS/, symlinked back.
+    Only AGENTS.md (real)             Yes                    Left exactly as it is; not adopted.
+    Only CLAUDE.md (real)             No                     Adopted, renamed to AGENTS.md, symlinked back.
+    Only CLAUDE.md (real)             Yes                    Left exactly as it is; not adopted or renamed.
+    Both, byte-identical              No                     AGENTS.md adopted; duplicate CLAUDE.md dropped.
+    Both, byte-identical              Yes (either)           Left exactly as they are; neither touched.
+    Both, different content           n/a                    Neither touched; warns, resolve by hand.
+    Mirror has CLAUDE.md (real)       n/a                    Flipped in place: renamed, nothing lost.
+    Correct AGENTS.md symlink exists  n/a                    Nothing happens -- already settled.
+
+A new real file appearing after a directory's mirror has already settled
+— an agent's own `/init`-style command, for instance, writing a fresh
+`CLAUDE.md` where an `AGENTS.md` is already symlinked:
+
+    New file vs. mirror  Deliberately tracked?  Result
+    -------------------  ---------------------  --------------------------------------------------------
+    Byte-identical        No                     Adopted as a duplicate; the new file is dropped.
+    Byte-identical        Yes                    Left as it is; not adopted, even though content matches.
+    Different content     No                     Left as it is; warns that it differs, resolve by hand.
+    Different content     Yes                    Left as it is; warns that it's tracked, not adopted.
+
+And whatever a directory holds, it never gets this far at all if
+discovery pruned it outright — see the containment rules above: nested
+repositories, dot-directories, `node_modules/`, generated-output
+directories, and any directory literally named `AGENTS`.
+
+
 ## plans/, specs/, and devlogs/
 
 `agents-init --plugins` (the second half of what a bare `agents-init` run

functions/agents-init.fish

@@ -110,6 +110,15 @@
 #   agents-init --agents
 #   agents-init --plugins
 #   agents-init --quiet
+#
+# NOTES
+#   This header covers usage only. The full concept/behavior/purpose
+#   write-up -- the AGENTS.md convention, the AGENTS/ sub-repository, the
+#   discovery and safety model, and a complete scenario-by-scenario
+#   reference table -- lives in its own manual section:
+#   docs/manual/16-agent-tooling.md. Update that section in the same
+#   change whenever this function's behavior changes; see "Dedicated
+#   manual sections for complex subsystems" in CONTRIBUTING.md.
 function agents-init --description 'scaffold AGENTS/ sub-repo with agent spec files and plugin dirs'
     __fish_palette
 

functions/agents-vault.fish

@@ -188,6 +188,13 @@
 #   machine that has a real global memory directory would move it into a
 #   throwaway directory and leave a dangling symlink behind, which is
 #   strictly worse than having had no backup at all.
+#
+#   This header covers usage only. The full concept/behavior/purpose
+#   write-up -- how this relates to the per-project AGENTS/ repository
+#   agents-init manages, and where each kind of agent state actually lives
+#   -- is in docs/manual/16-agent-tooling.md. Update that section in the
+#   same change whenever this function's behavior changes; see "Dedicated
+#   manual sections for complex subsystems" in CONTRIBUTING.md.
 function agents-vault --description 'track curated agent memory in a host-scoped vault repo'
     __fish_palette