docs(agents): trim section 2 layout tree to a thin pointer surface

[notno]

Intent

Trim AGENTS.md section 2's annotated layout tree to a thin pointer surface, per the firstmate-coding-guidelines skill and AGENTS.md's own "Maintaining this file" rules.

Goal and scope:

• The file was 63,377 chars, above Claude Code's ~40k large-memory warning floor, and the tree duplicated content whose single owners are docs/configuration.md and the producing scripts' headers, as section 2 itself declares.
• Replace the big annotated tree (every tracked file, config/ knob, data/ file, and state/ artifact with per-line explanations) with a compact summary: top-level directories with one-line purposes, plus explicit pointers - docs/configuration.md for layout and configuration schemas, each producing script's header for its own artifacts' exact fields and mechanics.
• Do not restructure other sections; incidental one-line touch-ups only where the tree's removal orphans a cross-reference.
• CLAUDE.md is a symlink to AGENTS.md; only AGENTS.md is edited.

Accepted decision (supersedes the original stretch target):

• Ship the section-2 trim as-is at 53,563 chars. The under-40k stretch goal is withdrawn: trimming other sections expands scope beyond what was approved, and the always-loaded contract there needs deliberate redesign, not a passing cut.
• The PR body must state plainly: the final size, that the large-memory warning threshold is still exceeded, and that further reduction would need its own considered effort.

Safety-boundary sweep (required in the PR description):

• Normative tree annotations with no other owner were deliberately relocated into section 2 prose: the state/ dot-file never-edit rule (watcher, wake-queue, auto-arm, away-mode, sub-supervisor internals), the rule that a registered process-to-event source under state/procevent/ keeps supervision required by its presence alone, the read-each-bin-script-header-before-first-use rule, and the CLAUDE.md/.claude-skills symlink edit-the-originals rule (a deliberate one-line reinforcement; CONTRIBUTING.md remains the owner).
• Every other normative tree line was verified as already covered: by kept section 2 prose (status lines are wake events not current-state truth, captain.md canonical regardless of harness memory, projects/ read-only, fm-send fail-closed), by other AGENTS.md sections (.env presence-gating in section 14, skills/ not loaded in section 12, .tasks.toml in section 10, check.sh registration contract in section 7, .afk in section 8, gitignored captain-private list in section 1), or by the owning doc or script header (all config/ knob semantics including crew-harness/secondmate-harness inheritance in docs/configuration.md and the backend docs it references; .meta fields via fm-spawn.sh and the runtime-backend section; watcher beacon via docs/watcher-continuity.md; Relay artifacts via the Relay section and fm-x-lib.sh; pr-poll/check-trust via the check and PR-check script headers; open-decisions cursor via fm-classify-lib.sh).

Constraints honored:

• One full sentence per line in tracked Markdown, plain dashes only, no em dash, no agent co-author on commits.
• Every skill, script, and doc referenced by the new pointer text was verified to exist.
• bin/fm-doc-audience-check.sh passes on the result.

What Changed

• Replaced AGENTS.md section 2's fully annotated layout tree (every tracked file, config/ knob, data/ file, and state/ artifact with per-line explanations) with a compact top-level directory summary plus explicit pointers: docs/configuration.md for layout entries and config/ knob semantics, and each producing script's header for its own data/ and state/ artifacts. AGENTS.md shrinks from 63,377 to 53,563 chars; this still exceeds Claude Code's ~40k large-memory warning threshold, and further reduction is deliberately deferred to its own considered effort rather than a passing cut here.
• Normative tree annotations with no other owner were relocated into section 2 prose rather than dropped: the state/ dot-file never-edit rule (watcher, wake-queue, auto-arm, away-mode, and sub-supervisor internals), the rule that a registered state/procevent/ source keeps supervision required by its presence alone, the read-each-bin/-script-header-before-first-use rule, and a one-line reinforcement of the CLAUDE.md/.claude/skills symlink edit-the-originals rule (CONTRIBUTING.md remains the owner). Every other normative tree line was verified as already covered by kept section 2 prose, another AGENTS.md section (e.g. .env presence-gating in section 14, skills/ not loaded in section 12, the gitignored captain-private list in section 1), or the owning doc or script header.
• No other sections were restructured; CLAUDE.md remains a symlink so only AGENTS.md is edited. The Test gate confirmed the exact size delta, the presence of all four relocated rules, that all pointer targets exist, and that bin/fm-doc-audience-check.sh passes on the result.

Risk Assessment

✅ Low: Docs-only trim of one AGENTS.md section that matches the authoritative intent exactly: the final size (53,563 chars) is as accepted, all four relocated normative rules appear in the new prose, and every dropped annotation's claimed owner (other AGENTS.md sections, docs/configuration.md, or the producing script headers) was verified to exist and cover it.

Testing

Verified the section-2 trim end-to-end against the intent: exact before/after char counts (63,377 → 53,563), a single-hunk section-2-only diff with symlinks untouched, all four relocated safety rules present in the new prose, the sweep's coverage claims confirmed in their owning sections, every new pointer target existing on disk, no em/en dashes in added lines, and the intent-named bin/fm-doc-audience-check.sh acceptance check passing; the change is a plain-Markdown agent-context surface, so the evidence is a CLI transcript of the new section rather than a screenshot.

Evidence: Section-2 trim validation transcript (sizes, audience check, new section 2 surface)

base 345de4e: 63377 chars → head 224b13e: 53563 chars (matches intent; still above ~40k floor per accepted decision) fm-doc-audience-check: ok surfaces=65 local_links=205 (exit 0) Added lines: 0 em/en dashes; CLAUDE.md and .claude/skills remain symlinks; only AGENTS.md changed (1 file, +12/-67) All four relocated rules present: state/ dot-file never-edit, procevent presence-keeps-supervision, read-bin-headers-first, edit-the-originals symlink rule

== AGENTS.md section-2 trim: validation transcript (commit 224b13e vs base 345de4e) ==

-- File size before/after (chars) --
base 345de4e: 63377
head 224b13e: 53563  (intent states 53,563; still above the ~40k large-memory warning floor, as the accepted decision acknowledges)

-- Only AGENTS.md changed; CLAUDE.md remains a symlink --
 AGENTS.md | 79 ++++++++++-----------------------------------------------------
 1 file changed, 12 insertions(+), 67 deletions(-)
  lrwxrwxrwx - nathan  6 Aug 15:36 CLAUDE.md -> AGENTS.md
  
  .claude/skills:
  drwxrwxr-x - nathan  6 Aug 15:36 afk
  drwxrwxr-x - nathan  6 Aug 15:36 ahoy
  drwxrwxr-x - nathan  6 Aug 15:36 ask-user-authority
  drwxrwxr-x - nathan  6 Aug 15:36 bearings
  drwxrwxr-x - nathan  6 Aug 15:36 bootstrap-diagnostics
  drwxrwxr-x - nathan  6 Aug 15:36 decision-hold-lifecycle
  drwxrwxr-x - nathan  6 Aug 15:36 diagnostic-reasoning
  drwxrwxr-x - nathan  6 Aug 15:36 firstmate-codexapp
  drwxrwxr-x - nathan  6 Aug 15:36 firstmate-coding-guidelines
  drwxrwxr-x - nathan  6 Aug 15:36 firstmate-orca
  drwxrwxr-x - nathan  6 Aug 15:36 fmx-respond
  drwxrwxr-x - nathan  6 Aug 15:36 harness-adapters
  drwxrwxr-x - nathan  6 Aug 15:36 process-event-sources
  drwxrwxr-x - nathan  6 Aug 15:36 project-management
  drwxrwxr-x - nathan  6 Aug 15:36 quota-array-dispatch
  drwxrwxr-x - nathan  6 Aug 15:36 secondmate-provisioning
  drwxrwxr-x - nathan  6 Aug 15:36 stow
  drwxrwxr-x - nathan  6 Aug 15:36 stuck-crewmate-recovery
  drwxrwxr-x - nathan  6 Aug 15:36 updatefirstmate

-- bin/fm-doc-audience-check.sh (named acceptance check) --
fm-doc-audience-check: ok surfaces=65 local_links=205
exit code: 0

-- Em/en dash scan of added lines --
0
0 (none found)

-- New section 2 as loaded by an agent (the end-user surface) --
## 2. Layout and state

`docs/configuration.md` is the single owner of the top-level operational-home layout and configuration schemas; each producing script's header and help own exact child fields and mutation mechanics.
`FM_HOME` selects an instance's private `data/`, `state/`, `config/`, and `projects/`, while scripts continue to come from their tracked code root.
Each secondmate has a persistent isolated `FM_HOME`, including its own state, backlog, projects, and session lock.
`bin/fm-send.sh` fails closed unless `FM_HOME` is explicit, so a steer cannot silently resolve against another home.

Tracked files hold shared instructions and tooling; `data/` holds durable private fleet records; `state/` holds volatile runtime records and append-only status events; `config/` holds local operating choices; and `projects/` contains clones that are read-only to firstmate except under hard rule 1's concrete captain-approved project operation exception.

`` `
tracked code root  shared instructions, skills, docs, workflows, and bin/ scripts; section 1 lists the shared material
config/            local operating choices, one small gitignored file per knob
data/              durable private fleet records: registries, captain preferences, learnings, backlog, briefs, and scout reports
projects/          cloned project repos; gitignored
state/             volatile runtime records: task metadata, status events, the wake queue, and watcher, Relay, and supervision artifacts
.no-mistakes/      local validation state and evidence; gitignored
`` `

Resolve an individual file's meaning through those owners - `docs/configuration.md` for every layout entry and `config/` knob, the producing script's header and help for its own `data/` and `state/` artifacts - rather than from memory.
`CLAUDE.md` and `.claude/skills` are compatibility symlinks to `AGENTS.md` and `.agents/skills/`; edit the originals.
Read each `bin/` script's header before first use.
The dot-prefixed files under `state/` are internals of the watcher, wake-queue, auto-arm, away-mode, and sub-supervisor machinery; never edit them by hand, and act on them only through their owning paths.
A registered process-to-event source under `state/procevent/` keeps supervision required by its presence alone (section 13).

A `state/<id>.status` line is a wake event, not current-state truth; `bin/fm-crew-state.sh` owns current-state reconciliation.
Treat `data/captain.md` as the domain-local record of captain preferences, optional `data/captain-shared.md` as the main-authoritative shared captain-preference file for secondmate inheritance, and `data/learnings.md` as curated home-local knowledge, regardless of harness memory.

## 3. Session start (run once at every session start)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• git diff --stat 345de4e..224b13e — confirmed only AGENTS.md changed (12 insertions, 67 deletions, one hunk in section 2)
• wc -c AGENTS.md vs git show 345de4e:AGENTS.md | wc -c — verified exact 63,377 → 53,563 char reduction stated in the intent
• bin/fm-doc-audience-check.sh — the acceptance check named in the intent; passed with ok surfaces=65 local_links=205, exit 0
• Manual diff review confirming all four deliberately relocated normative rules appear in section 2 prose: state/ dot-file never-edit rule, procevent presence-keeps-supervision rule, read-bin-script-headers-first rule, and the CLAUDE.md/.claude-skills edit-the-originals line
• Spot-checked the safety-sweep coverage claims: .env presence-gating (section 14 line 468), skills/ not loaded by firstmate (section 12 line 440), captain-private gitignored list (section 1 line 43), status-lines-as-wake-events and captain.md-canonical prose retained in section 2
• ls -ld CLAUDE.md .claude/skills — confirmed both remain symlinks to the edited originals; ls docs/configuration.md bin/fm-doc-audience-check.sh bin/fm-crew-state.sh — all pointer targets exist
• git diff 345de4e..224b13e | grep '^+' | grep -P '\x{2014}|\x{2013}' — no em/en dashes in any added line
• Grep for orphaned cross-references to the removed annotated tree — none found
• git status --porcelain — worktree left clean, no transient test artifacts

✅ **Document** - passed

✅ No issues found.

⚠️ **Lint** - 1 warning

• ⚠️ linter found issues (exit code 127)

✅ **Push** - passed

✅ No issues found.