docs(crews): sync the Crews pages and tool contract with what ships

[bryantderosier]

Problem

The Crews pages and the agent tool contract had drifted from what ships (#229), the artifacts user page contradicted itself about handoff versions (#230), and FORK.md case 3 didn't name the Crew-stop replay test that lives in the same upstream test file (#232). None of this is a policy change, except the approver narrowing I ruled on in #234.

What I changed

• docs/j5/product/features/crews.md:
  • History is back in date order, with a 2026-09-21 line for the /crew retirement (Compose Crews in ordinary chat and let members coordinate directly #211) and a 2026-09-24 line for today's changes.
  • The Definition, AC6, and AC20 say the snapshot keeps each member's reason (the person approves every seat).
  • The Lifecycle section says a former seat unarchived on its own is a solo agent.
  • "Roles" in the Lifecycle paragraph becomes "personas".
• docs/j5/product/a2a/agent-tools.md:
  • The propose_crew and request_crew_member contract strings are regenerated from J5_PROPOSE_CREW_DESCRIPTION and J5_REQUEST_CREW_MEMBER_DESCRIPTION.
  • The seat and request tables gain model_selection and runtime_mode and drop the struck agent alias; reason is up to 500 characters.
  • Approval records each member's reason, and persona vocabulary is used throughout.
  • The seat-finish paragraph is rewritten to match CrewSeatFinishNotifier: completed and failed runs only, posts on change, folds into a queued digest, and missing means checked and not there.
• docs/j5/product/glossary.md: Persona replaces Role in the row and the casing example.
• docs/j5/product/agent-personas/index.md: the Captain is told on every finish whether the handoff was written, missing, or never declared.
• apps/server/src/j5/a2a/README.md: the "no cascade" line now names CrewCaptainArchiveCascade.ts and crewSeatArchiveGuard.ts.
• docs/j5/worklog/2026-09-16-crew-command-decoupling.md: one pointer that the Inbox failure alert shipped in feat(agents): Crews, a roster the Captain proposes and the person approves #148; the history is untouched.
• docs/user/artifacts.md (Handoff files keep every version: fix the artifacts user page #230): a rewritten handoff adds a version at the top of the same file.
• docs/user/personas.md: retired crews sit in Fleet's Retired section, across Squadrons.
• FORK.md case 3 (Record the Crew-stop replay test under FORK.md case 3 #232): names replaying a Crew stop does not dispatch a second real interrupt.
• Comments only: apps/web/src/j5/a2a/ThreadA2ARenderer.tsx (no /crew turn) and the FleetCrew comment in packages/contracts/src/j5.ts.

Why this shape

Definitions are rewritten, not appended (docs/j5/process/docs.md), so every sentence was changed in place and History got one line per amendment. The contract strings are copied from tools.ts rather than paraphrased, because EnvelopeFormatter.test.ts already reads this file for the send_message contract and paraphrases drift.

Invariants

• No behavior change: the only code edits are two comments.
• Worklog records stay as written; the one addition is a pointer paragraph.

Surfaces

Surface	Decision
Entry points (chat, Settings, command palette, keybinding)	Unaffected.
Clients (web, desktop, mobile)	Unaffected; one web comment.
Providers	Unaffected.
Contracts (packages/contracts)	One comment.
Reverse states	n/a.
Connection modes (local, remote, tunnel)	Unaffected.
Upstream files / FORK.md	FORK.md case 3 gains one sentence.
Docs	The point of the PR.

Out of scope

• Renaming docs/j5/product/features/roles.md to match the persona vocabulary; the glossary still links it.
• Document the approval token's branch binding and the ACP access restriction #231 (preview binding and ACP access) is its own PR because it touches server text.

Upgrade and data

None.

Verification

• EnvelopeFormatter.test.ts, which reads agent-tools.md, passes.
• Format and lint clean on the changed files.

Review focus

• The seat-finish paragraph in agent-tools.md describes fix(crews): Crew notices report only what the platform measured #292's retry behavior ("a handoff that cannot be read sends nothing"), so this should merge after fix(crews): Crew notices report only what the platform measured #292.
• Check the regenerated contract strings against tools.ts.

Closes #229
Closes #230
Closes #232

Claude Opus 5.5 via Claude Code

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: a8494b2b-8746-4401-b0b8-b3c63408affd

---

_{Comment @coderabbitai help to get the list of available commands.}

[Jacksondr5]

[Review panel: Opus 5.5 + coordinator (Opus 5.5)]

Missed file: docs/j5/product/features/fleet-page.md AC28 still describes the retired roster snapshot as "(seat, agent, who approved it and why, the version it joined at)". The roster has no approver field (FleetCrew.roster in packages/contracts/src/j5.ts is seat, agentId, participantId, addedVersion, reason). This PR removes the approver from crews.md AC6, AC20, and the Definition but not from the Fleet page definition, so the two definitions disagree.

Suggested fix: change it to "(seat, agent, why it joined, the version it joined at)" and add a fleet-page.md History line. Note that #315 also rewrites AC28 and keeps "who approved it and why", so whichever PR lands second needs the corrected wording.

[bryantderosier]

@Jacksondr5 An update on #306:

• Fixed now:
  • fleet-page.md AC28 reads "(seat, agent, why it joined, the version it joined at)" and has a History line.
  • The "Handoffartifacts" typo is fixed.
  • I merged the latest j5/main.
• After the Crews stack lands: I'll rebase docs(crews): sync the Crews pages and tool contract with what ships #306 on it as you suggested and reconcile the "Crews never unarchive as a unit" sentence and History clause with fix(crews): a Crew follows its Captain through every lifecycle step #315's rule. That thread stays open until then. fix(crews): a Crew follows its Captain through every lifecycle step #315 also rewrites AC28, so whichever lands second keeps the "why it joined" wording.

[Jacksondr5]

[Review panel: Opus 5.5 + coordinator (Opus 5.5)]

Re: the fleet-page AC28 finding. Verified at e72d27a. AC28 now reads "(seat, agent, why it joined, the version it joined at)", which matches FleetCrew.roster. The new 2026-09-24 History line explains why the roster records no approver.