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.
docs: add chapter 13, the operator user guide, for release 1.1
The wiki had twelve chapters and none of them told an operator how to run
the thing. Chapters 1-3 explain why the design is what it is, 9-12 explain
how the code is put together, 11 lists capabilities. The two pages that were
meant to cover bring-up and day-2 - 4-Setup and 5-Operations - were never
written past their scope note, and every technical detail in them had gone
wrong: a decommissioned model host, port 8080, herdr protocol 14, a systemd
unit that does not exist, Redis Streams and NATS that were never built,
"no per-session authz yet" after Authz shipped, and recycle() events that
have no code behind them.
So this adds 13-User-Guide.md, written against the running system on
2026-08-17, and points the two stubs at it rather than leaving wrong claims
in place.
The guide covers:
1. what this is and, more usefully, the five things it is NOT, each with
the reason it is not that;
2. install - herdr (check the PROTOCOL number, not the version), the
daemon, the login-shell rule for secrets.sh, and the lead's tab label;
3. configure - the four knobs that cost money, the live profile table with
who pays for each, the gateway paths, and memberCredentials' two halves;
4. run - the redeploy script, and the four checks that go beyond /healthz,
because health is green while every spawn fails;
5. delegate - the eleven tools, the spawn-all-then-send-all rule, the ~60s
client cap on a blocking send, and the authz table;
6. when it breaks - twelve traps hit for real this year, grouped by
bring-up, losing a member's work, and merging a member's work;
7. where to look next.
Home.md is corrected too: it claimed members launch against ollama.ltms.dev,
a host that no longer exists (the gateway is llm.ltms.dev), it framed the
system as Claude-only with one worker, it listed 8 of the 13 pages, and its
status still said "Design".
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.
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