#168: rebuild chapters 1, 2, 7, 8 and 9 against the source
The audit marked all five REBUILD. Every factual claim on them is now checked in
the code and carries a file:line reference.
What was wrong and is now fixed:
- Ch.1 named a `fleet_read` tool and an SSE `GET /events` route. Neither exists.
It also named Redis Streams and NATS JetStream as the queue; the shipped inbox
is AMQP. The subscription boundary is back as its own section, sourced from
SubscriptionGuard, and the REST list now matches FleetApp.build().
- Ch.2 described tool parameters that were never shipped. The tool table now
comes from each tool's own schema method.
- Ch.7 was built on `ccs` profiles and on send parameters that do not exist.
Every flow now uses the real tools. The portable CLAUDE.md block is unchanged,
byte for byte, and the sync check still passes.
- Ch.8 presented old plans as the current stack. It is now a delivery record in
four states, and "built, not switched on" means no host enables it today —
AMQP and the coordinator mailbox are both on here, so both moved to live.
- Ch.9 had drifted from the source in its package, class and endpoint map.
Also: chapters 1, 2 and 8 had "I checked this in the code" written on the page
itself. That belongs in a worker's report, not in a reference page. The pages now
state the fact and cite the line.
Every Mermaid diagram was rendered with mmdc before this commit.
Match the code cutover: daemon name, config (fleetd.yaml), scripts, launchd/
systemd units, module dir, and MCP tool prefix bridge_* -> fleet_*. Kept:
the BRIDGED_MEMBER security marker, mcp__bridge__ (historical mount name), and
the .bridged-worktrees on-disk path. The portable CLAUDE.md block stays
byte-identical with the repo's CLAUDE.md.
Fold the now-shipped CB-307 into the as-built docs (was stale at Stage 1 only):
- Roadmap: Stage 2 (AmqpReplyInbox/LavinMQ, 2bc5f3a) and Stage 3 (ReplyPushLoop
active push-to-primary, d4c9704, gitea #5 closed) marked shipped; diagram gains
a Stage 3 node; all stages green.
- Implementation: msg core 4->6 classes (AmqpReplyInbox consume-and-hold, ReplyPushLoop
status-gated loop); mcp 6->7 (PrimaryRegistry); bridge_ack tool; stranded-reply
narrative extended with durable landing + active nudge + pull degradation.
- Architecture: late-replies note now covers durable + active push; split-host hook
note clarifies a same-host primary IS injected into (Stage-3 nudge).
Push channel resolved: the same-host primary is a herdr pane, so the loop injects a
bounded, status-gated drain nudge into its own pane; off-host degrades to pull.
Mermaid roadmap diagram re-validated (renders clean).
wiki: consistency pass vs rewritten Architecture (5-agent review)
Independent cold reads of every page against 1-Architecture found no invariant
violations; fixed the drift the rewrite introduced plus one real contradiction:
- terminology: Channel 1/2 -> Mode 1/2, 'two-channel' -> 'two invariants / two
modes' (Approaches, Team, Home, Sidebar, Message-Server); north/south face ->
SERVER/CLIENT face (Message-Server, 6 spots)
- contradiction reconciled: Architecture now acknowledges a non-MCP *worker*
Stop-hook (POSTs reply to bridged) as well as the split-host-primary hook -
both target bridged, never a broker; Message-Server tier table split into
Unified / Hooked / Unmodified to match
- Approaches: footnote credits bridge_reply (Stop-hook = fallback); §4 subtitle
reframed; <payload> mermaid label de-angled (parse-safe)
- Team: SERVER 'role router' -> 'policy brain'; fan-out sequence quoted; inference edges labeled
- Home/README: CLIENT-face node regains 'status-gated injector'
- Operations: 'broker' -> 'internal broker/queue'; Stop-hook framed as split-host exception
- async ticket/bridge_poll reframed as injection-first (push), poll = non-pane fallback
All 16 mermaid blocks validated with mmdc.
wiki: rewrite 1-Architecture from scratch (clean-slate, final consolidated design)
Discard the incrementally-accreted Architecture page and compose a fresh,
coherent one around the two invariants (subscription boundary + sole gateway).
Tighter structure, 4 purposeful diagrams (system overview, blocking seq, async
seq, lifecycle state), no legacy framing. All validated with mmdc.
wiki: bridged is the sole communication gateway (no Claude<->broker, no mainline Stop-hook)
Now that every Claude session mounts bridged over MCP, make bridged the ONLY
thing a Claude session talks to. Claude never posts to / polls a broker; async
delivery is bridged injecting an idle pane (event-driven off agent_status). The
broker drops below the gateway line as bridged-owned durability/cross-host infra.
The Stop-hook survives only as a split-host escape hatch that polls bridged (not
the broker).
- 1-Architecture: add the gateway invariant; rewrite Channel 2 as bridged-mediated
async; redraw components + deployment diagrams (broker below gateway, drop
Claude/Hook -> broker arrows); guardrails now bridged-enforced; failure-modes
updated (bridged down = whole gateway down)
- 2-Message-Server: reply-model, reply-envelope (hook posts bridged not broker),
async-duplex sequence, components/API/tech-stack/milestones/trade-offs, both
deployment diagrams
- 3-Approaches: sole-gateway notes in herdr/AgentAPI/queue sections, matrix + recs
- 4-Setup: split-host Stop-hook polls bridged; queue is internal
- 6-Team: detached jobs via bridged async, not broker
- Home + README: 'one gateway' bullet; intros updated
All 16 mermaid blocks validated with mmdc; 2 rendered to PNG for layout.
Declutter every component diagram to show bridged as ONE standalone daemon
split into a SERVER (north) face — MCP server + REST/SSE + policy brain — and
a CLIENT (south) face — status-gated injector + herdr socket client. Claude
sessions are shown as herdr panes that mount the MCP server (call up) while the
client drives them down over the socket.
- 2-Message-Server: main architecture flowchart rebuilt (herd subgraph of
panes + bridged subgraph with srv/cli); intro reframed; split-host node label
- 1-Architecture: components diagram — bridged subgraph with SERVER/CLIENT faces
- 6-Team: topology — bridged split into faces + role router; worker bridge_reply
- Home + README: overview flowchart — bridged subgraph with SERVER/CLIENT faces
All 16 mermaid blocks validated with mmdc.
wiki: number page filenames (1-..5-) so Gitea Pages list sorts
- git mv content pages to N-Name.md (history preserved); Home + _Sidebar kept
- convert [[wiki-links]] to [display](numbered-slug) markdown links so
resolution is unambiguous and prose display stays clean
Dai Ha
kevin