docs(agent-tooling): add scenario reference table, cross-reference from code

Adds a 'Scenario reference' subsection to docs/manual/16-agent-tooling.md:
two ruled tables covering every combination of what a directory can hold
(only AGENTS.md, only CLAUDE.md, both identical, both different, an
inverted mirror, an already-settled symlink) crossed with whether the
file is deliberately git-tracked, plus the settled-mirror/later-arrival
case separately. Verified against build-manual.py's actual table parser
and the generated Starlight site output, not just visual inspection.

Also closes the gap this section itself pointed out: nothing previously
linked a reader of agents-init.fish or agents-vault.fish's own doc-header
to this page, and nothing told a future contributor the page has to be
kept in sync. Adds:
- CONTRIBUTING.md: a new 'Dedicated manual sections for complex
  subsystems' subsection documenting the pattern in general (when to use
  one, and the update-it-in-the-same-change obligation verify-manual.py
  cannot check for you).
- functions/agents-init.fish, functions/agents-vault.fish: a NOTES
  pointer to the section from each function's own header, so a reader
  who only sees the header still finds the fuller page.

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