docs(j5): product docs cleanup — kinds, identifiers, definitions

FORK.md

@@ -266,7 +266,7 @@ Fork-owned workflows use the Node version in `.nvmrc`, pnpm `11.10.0`, the froze
 the repo-local Vite Plus binary. `J5 CI` is the push/PR gate for `j5/**`; `J5 Weekly Full Build` is the
 scheduled and manually dispatchable pre-rebase suite plus Apple Silicon desktop build.
 
-See [`docs/j5/macos-packaging.md`](docs/j5/macos-packaging.md) for the local build, signature
+See [`docs/j5/runbooks/macos-packaging.md`](docs/j5/runbooks/macos-packaging.md) for the local build, signature
 verification, install, Gatekeeper approval, and workflow runbook.
 
 ## Final upstream-file review — 2026-09-06

apps/server/src/j5/a2a/EnvelopeFormatter.test.ts

@@ -27,7 +27,7 @@ const readDocumentedSendToolDescription = Effect.fn("readDocumentedSendToolDescr
       decodeURIComponent(documentedSendToolContract.pathname),
     );
     const description = document.match(
-      /## `send_message`[\s\S]*?\*\*Description \(contract(?:, [^)]*)?\):\*\* "([\s\S]*?)"\n\n\| Input/,
+      /## `send_message`[\s\S]*?\*\*Description:\*\* "([\s\S]*?)"\n\n\| Input/,
     )?.[1];
     if (description === undefined) {
       return yield* Effect.die("send_message contract description is missing from agent-tools.md");
@@ -117,11 +117,11 @@ it("does not interpret caller text as an envelope template", () => {
 it("keeps the tool descriptions on their documented contracts", () => {
   assert.equal(
     A2A_SEND_TOOL_DESCRIPTION,
-    "Send one durable message. To another agent, three uses: a **plain send** when you don't need a reply; an **ask** — set expect_reply=true with a one-line intent, opening an exchange the receiver owes a reply to; a **reply** — include the exchange_id from the ask you are answering, which closes that exchange. To the human, only an ask or a reply: a plain send to a person is refused — if nobody needs to act, say it in your own thread instead. Set urgency only when asking the human. Use this tool only for participants already returned by list_participants; when creating a Peer Agent, put any reply expectation in spawn_agent's brief instead of sending a follow-up ask. Returns once the message is committed; delivery continues asynchronously — carry on with your work, and the reply arrives later as an incoming message. A caller without a registered home is refused. Reuse client_request_id to retry the same send safely.",
+    "Send one durable message. To another agent, three uses: a **plain send** when you don't need a reply; an **ask** — set expect_reply=true with a one-line intent, opening an exchange the receiver owes a reply to; a **reply** — include the exchange_id from the ask you are answering, which closes that exchange. To the human, only an ask: a plain send to a person is refused — if nobody needs to act, say it in your own thread instead. Set urgency only when asking the human. Use this tool only for participants already returned by list_participants; when creating a Peer Agent, put any reply expectation in spawn_agent's brief instead of sending a follow-up ask. Returns once the message is committed; delivery continues asynchronously — carry on with your work, and the reply arrives later as an incoming message. A caller without a registered home is refused. Reuse client_request_id to retry the same send safely.",
   );
   assert.include(
     A2A_SEND_TOOL_DESCRIPTION,
-    "To the human, only an ask or a reply: a plain send to a person is refused",
+    "To the human, only an ask: a plain send to a person is refused",
   );
   assert.include(A2A_CLEAR_OWN_ASK_TOOL_DESCRIPTION, "Withdraw an ask you sent");
   assert.include(A2A_CLEAR_OWN_ASK_TOOL_DESCRIPTION, "sender-cleared");

apps/server/src/j5/a2a/envelopes.v1.json

@@ -7,7 +7,7 @@
   "replyInstruction": "Reply once with send_message(to=\"{{senderId}}\", exchange_id=\"{{exchangeId}}\", message=\"...\") to close the exchange. Follow-ups from the asker carrying this id join the same exchange.",
   "oneShotInstruction": "No reply is required. Use send_message without exchange_id only if a new message is needed.",
   "closedExchangeInstruction": "The platform closed this exchange when this reply was sent. No further reply is required.",
-  "sendToolDescription": "Send one durable message. To another agent, three uses: a **plain send** when you don't need a reply; an **ask** — set expect_reply=true with a one-line intent, opening an exchange the receiver owes a reply to; a **reply** — include the exchange_id from the ask you are answering, which closes that exchange. To the human, only an ask or a reply: a plain send to a person is refused — if nobody needs to act, say it in your own thread instead. Set urgency only when asking the human. Use this tool only for participants already returned by list_participants; when creating a Peer Agent, put any reply expectation in spawn_agent's brief instead of sending a follow-up ask. Returns once the message is committed; delivery continues asynchronously — carry on with your work, and the reply arrives later as an incoming message. A caller without a registered home is refused. Reuse client_request_id to retry the same send safely.",
+  "sendToolDescription": "Send one durable message. To another agent, three uses: a **plain send** when you don't need a reply; an **ask** — set expect_reply=true with a one-line intent, opening an exchange the receiver owes a reply to; a **reply** — include the exchange_id from the ask you are answering, which closes that exchange. To the human, only an ask: a plain send to a person is refused — if nobody needs to act, say it in your own thread instead. Set urgency only when asking the human. Use this tool only for participants already returned by list_participants; when creating a Peer Agent, put any reply expectation in spawn_agent's brief instead of sending a follow-up ask. Returns once the message is committed; delivery continues asynchronously — carry on with your work, and the reply arrives later as an incoming message. A caller without a registered home is refused. Reuse client_request_id to retry the same send safely.",
   "listToolDescription": "Your address book: the participants around you — agents and the human — with the display name to recognize them by, the participant_id to address them with, and what each accepts (messages, exchanges, urgency). When you're told to message someone by name or role, resolve them here first. Your own row is marked self=true; it cannot receive messages or open exchanges from you — use schedule_task if you need a future trigger for yourself. Native threads that never received a Squadron home do not appear here and cannot be messaged. Archived agents are hidden by default; set include_archived=true to see them with archived=true. They cannot receive messages or open Exchanges. The roster changes — after you spawn, archive, unarchive, or delete an agent, call this again instead of reusing a stale listing.",
   "clearOwnAskToolDescription": "Withdraw an ask you sent: closes your open exchange without a reply message. Use when the answer already arrived outside the exchange — for example, the human answered you directly in your thread — so the obligation exits their inbox honestly. Only the exchange's sender may clear it; the closure is recorded as sender-cleared, distinct from an answered exchange. Reuse client_request_id to retry safely."
 }

apps/server/src/j5/a2a/mcp/tools.test.ts

@@ -18,7 +18,7 @@ it("publishes the ratified single-target lifecycle contracts fail-closed", () =>
   assert.equal(J5SendMessageTool.description, A2A_SEND_TOOL_DESCRIPTION);
   assert.include(
     J5SendMessageTool.description ?? "",
-    "To the human, only an ask or a reply: a plain send to a person is refused",
+    "To the human, only an ask: a plain send to a person is refused",
   );
   assert.equal(J5ArchiveAgentTool.description, J5_ARCHIVE_AGENT_DESCRIPTION);
   assert.equal(J5SpawnAgentTool.description, J5_SPAWN_AGENT_DESCRIPTION);

docs/j5/README.md

@@ -1,69 +1,27 @@
-# J5 design docs — mirrored from the design workspace
+# J5 documentation
 
-This tree mirrors the durable product, research, and planning documents for the
-J5 fleet-management effort. They were authored in the team's agent design
-workspace (Traycer epic artifacts) and are mirrored here so anyone working in
-this repo — human or agent — can read the reasoning behind the build without
-access to that workspace.
+Everything about J5 Code — the product built on this fork of T3 Code — lives under `docs/j5/`. Upstream's own documentation (`docs/user/`, `docs/internals/`, `docs/operations/`) is left as upstream wrote it; J5 never edits it.
 
-**The mirror is a snapshot, not the working medium.** Design sessions continue
-in the workspace; settled changes land here through docs PRs. Each document
-describes the codebase and decisions _as of when it was written_ — check dates
-before treating details as current. Documents carry YAML frontmatter from the
-source system (`kind`: spec = durable context, ticket/story = work items with
-`status` 0/1/2 = todo/in-progress/done); it is preserved for fidelity.
-Note: this tree was reorganized 2026-08-23 (single-doc folders flattened to
-`topic.md`, feature docs grouped under `features/`), so its layout no longer
-matches the workspace's folder structure — content, not paths, is what mirrors.
+Every document here is one of five kinds, and the kind tells you how far to trust it: **definitions** describe the product and are kept true; **plans** sequence work and are history once executed; **research** reports what we learned as of a date; **records** say what happened on a day; **runbooks** tell an operator what to do. The kinds, their lifetimes, the identifier scheme, and the rules for changing a definition are in [how the docs are organized](process/docs.md) — read it before writing anything here.
 
 ## Reading order for newcomers
 
-1. `product/problems.md` — what hurts and what's wanted: the problem statement
-   and goals, in Jackson's voice.
-2. `product/fleet-vision.md` — why this exists: the operating model and thesis.
-3. `product/principles.md` — the beliefs, lenses, and principles: the machine
-   that turns the problems and goals into product.
-4. `product/use-cases.md` — the concrete fleets every feature is tested
-   against.
-5. `research/synthesis.md` — what we learned from T3 Code and Traycer, and the
-   engineering principles adopted from each.
-6. `research/jackson-prior-art/fleet-interviews-synthesis.md` — field lessons
-   from a real production agent fleet, and the platform/non-platform boundary
-   that governs scope decisions.
-7. `product/decision-log.md` — every settled product decision, one row each.
-8. `product/a2a/` — the A2A (agent-to-agent communication) design: decision
-   register, grounding model, and `plan.md` with the milestone plan.
-9. `product/features/` — the feature definitions of record: Squadrons, Crews,
-   Roles, Playbooks, Memos, Shared Squadrons, and the PR pane.
+1. [Problems and goals](product/problems.md) — what hurts and what is wanted, in Jackson's voice.
+2. [Fleet vision](product/fleet-vision.md) — why this exists: the operating model and the thesis.
+3. [Principles](product/principles.md) — the beliefs, lenses and principles that turn the problems into product.
+4. [Use cases](product/use-cases.md) — the concrete fleets every feature is tested against.
+5. [Glossary](product/glossary.md) — the vocabulary; every name in these docs resolves here.
+6. [Agent-to-agent communication](product/a2a/index.md), then [Squadron](product/features/squadron.md) — the two definitions everything else stands on.
+7. The rest of [`product/features/`](product/features/) — the feature definitions of record.
+8. [Research synthesis](research/synthesis.md) — what we learned from T3 Code and Traycer.
 
 ## Contents
 
-- `backlog.md` — the prioritized roadmap.
-- `product/features/` — feature definitions of record: `squadron.md`,
-  `crews.md`, `roles.md`, `playbooks.md`, `memos.md`, `shared-squadrons.md`,
-  `pr-pane.md`.
-- `product/` — product designs and decisions: problems & goals, the
-  beliefs/lenses/principles machine, use cases, decision log, fleet vision,
-  glossary, the A2A design + plan, communication graph, cross-device position,
-  and the 2026-08-21 design-review register that defined Crews/Roles/Captains.
-- `research/` — the studies behind the decisions: T3 Code deep dives (the
-  upstream this repo forks), Traycer's A2A/organization model, and the
-  prior-art fleet studies. A quarantined, superseded early T3 snapshot was
-  deliberately not mirrored.
-- `process/` — contributor-facing rules for working in this repository. How the
-  agent fleet is run is Jackson's personal practice and lives outside the product
-  repo, in his playbooks.
-- `worklog/` — build-time records, kept out of the evergreen docs: the A2A
-  implementation tickets with their reviews and retros (`a2a-tickets/`), how
-  this fork was established (`fork-setup-plan/` — base pin, rebrand, CI,
-  load-test baseline), and PR triage reviews. Historical by nature; read the
-  product docs for current truth.
+- **`product/`** — definitions: the core documents above, the [A2A trio](product/a2a/) (the communication protocol, the upstream substrate, the agent tool contracts), and [`features/`](product/features/) (Squadron, inbox, thread rendering, archive flow, Roles, Crews, Memos, Playbooks, Spawning Guide, sidebar and roster, PR pane, Shared Squadrons).
+- **`plans/`** — the [dogfood v0 plan](plans/dogfood-v0.md) and the [A2A plan](plans/a2a.md). Build status against a definition's criteria lives only here. The backlog beyond these is the repository's GitHub milestones, in outcome order.
+- **`research/`** — the studies behind the decisions: T3 Code, Traycer, the prior-art fleets, remote hosting. Each carries an `as_of` date; none is a source of truth about the product.
+- **`worklog/`** — records, named date-first: design sessions and rulings, the tickets and reviews of the A2A build and the dogfood queue, how the fork was set up, the phase-3 friction list.
+- **`runbooks/`** — operating the software: the [dogfood runtime](runbooks/dogfood-runtime.md), [agent migration](runbooks/agent-migration.md), [macOS packaging](runbooks/macos-packaging.md).
+- **`process/`** — rules for working in this repository: [how the docs are organized](process/docs.md) and [working in the repo](process/working-in-the-repo.md). How the fleet is run day to day is the operator's own practice and lives outside the repository.
 
-Cross-references between documents use relative paths and survive within this
-tree. References to `interviews/` point at the public
-`Jacksondr5/pr-group` repository.
-
-## Not part of the mirror
-
-Hand-written fork docs coexist in this directory (currently `macos-packaging.md`).
-Mirror refreshes must exclude them — they are owned in-repo, not in the workspace.
+Cross-references are relative paths and survive within this tree.