todo: fold the existing claude-md-touchpoints audit into the AGENTS.md sweep

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

todo/docs-conventions/sweep-agents-md-primary-claude-md-pointer.md

@@ -46,3 +46,48 @@ wrong, not just unnecessary:
 `plugins/`, `src/apps/` and `src/databases/` `CLAUDE.md`/`AGENTS.md` files** — apparently a working
 clone related to the Atelier extraction. Worth checking whether it is still live before sweeping it
 twice; if it is a stale branch, the sweep only needs to happen once, in the platform repo.
+
+---
+
+**2026-08-25 — the owner points at prior art: `docs/claude-md-touchpoints.md`, an audit written the
+same day, before any change, exactly so this sweep would not be guessed at.** It replaces the "two
+lookalikes" section above with something precise: **three writers, one reader**, all named by file and
+line —
+
+1. `command-hq/directory.ts:653`, `createCommanderDirectory()` — generates a commander's `CLAUDE.md`
+   ONCE, at creation, from `commanderClaudeMd()`. Never rewritten afterward; the commander extends it
+   itself over its own life, which is why this file is correctly excluded from any flip — there is no
+   "primary content" to move, because the content is written by the commander, not shipped as
+   documentation.
+2. `api/chat/websocket.ts:237`, `installPluginChatBrief()` — copies a plugin's own `chat/CLAUDE.md`
+   into a plugin-chat's directory, content-diffed so it only rewrites on an actual change. Of 19
+   plugins, exactly one (`proxy-manager`) ships one.
+3. `scripts/backfill-commander-credentials.ts` — a manual, idempotent append pass over EXISTING
+   commander files, marker-guarded so it never duplicates a section.
+4. `scripts/docs-check.ts` — read-only, checks `platform/CLAUDE.md` and `officer-dev/CLAUDE.md` (not a
+   plugin's, not a commander's) for numeric drift. This is the one file this sweep must not touch
+   carelessly: whatever ends up as the "pointer" file still has to carry the two numbers `docs:check`
+   parses out of it, or the check needs to move to reading `AGENTS.md` instead.
+
+**Confirms the exclusion already written above, with better grounding — do not re-derive it, cite the
+audit instead.** Commander files and plugin chat briefs are runtime-authored content injected into an
+agent's cwd, not source-tree documentation a coding CLI discovers by walking up from where it starts.
+Flipping "which file is primary" has no meaning for a file with no counterpart and no static content to
+begin with.
+
+**Two things the audit surfaces that are genuinely new and unresolved, not covered by "flip the pointer
+everywhere":**
+
+- **The owner's personal `~/.claude/CLAUDE.md` is explicitly, deliberately, never touched by any of
+  this** — the audit's own "Explicitly not written" section: the owner's sessions are un-isolated, `HOME`
+  points at their real home, and a generated file there would land inside the hand-maintained document
+  the owner edits directly (and that a terminal `claude` also reads). **This file is out of scope for
+  the sweep entirely** — it is not a repository doc, it is the owner's own, and it is inherently
+  Claude-specific by its path (`~/.claude/`), not something an `AGENTS.md` convention could apply to.
+- **A commander's dynamically-generated file is named `CLAUDE.md` specifically, and commanders can run
+  under opencode.** The audit does not ask whether opencode discovers a `CLAUDE.md` in its working
+  directory the way Claude Code does — only Claude/opencode's actual read-side behaviour answers that,
+  and it was out of scope for an audit about WRITING. If opencode does not read `CLAUDE.md` by
+  convention, an opencode-run commander is silently briefed with nothing, which would be a real gap
+  this sweep should catch rather than one it assumes away. Check before deciding whether
+  `commanderClaudeMd()`'s output needs an `AGENTS.md`-named counterpart too.