FM architecture guide — the client topology taught, diagram-first

Operator friction→gold (2026-08-09, verbatim intent): "our ADRs feel more like history trails than actual value… I doubt we have an ADR for a new FM architecture guide inside the learning section… high impact mermaid diagrams to show how things are supposed to work." Verified: no FM architecture guide exists in learn/agentos/ — RunningTheFleetCockpit.md is the operational runbook, ADR 0038 is the decision record, and nothing TEACHES the architecture.

Context

The gap is structural, not a broken ADR: ADRs are decision authority (WHY-shaped — options, falsifiers, amendments); a guide is the comprehension surface (HOW-shaped — the working system, diagram-first, narrative). The FM cluster graduated 13 artifacts from D#16720 and amended four ADRs in two days — the teaching layer never followed. A newcomer (or a waking peer) currently reconstructs the topology from a 200-line ADR plus commit archaeology.

The Problem

Every load-bearing FM concept lives ONLY in decision-record or runbook form: the pure-client topology, the three roles / two registries, the four non-aliased identity facts, the credential-class ledger, the telltale-axes truth model, the wake delivery composition. All of it is now RUNNING (the plane rebuilt to 55219f40d8 today with the fleet profile at first light) — the guide can teach a live system with real receipts.

The Architectural Reality

• Home: learn/agentos/FleetManagerArchitecture.md, sibling to the existing guide family (mermaid is house-standard there).
• The guide-authoring skill bar binds: grounding discipline (mine the subsystem + use its tools before writing), rich-narrative + lived-voice, render-verified TD mermaid, conceptual-vs-reference separation.
• Authority split, explicit: the guide CITES ADR 0038 (+ 0019/0020/0026/0034 amendments) for every "why"; it never re-decides. Divergent content found while writing routes to a Discussion, not into the guide.

The Fix — diagram inventory (the heart; each TD, render-verified)

1. D1 — The three-hop topology: browser/cockpit ↔ authenticated fleet transport ↔ plane services ↔ graph/data — trust boundaries drawn, each credential class (ADR 0038 §2.5.1's six rows) placed AT its boundary. The ledger, visualized.
2. D2 — Three roles, two registries: cockpit client / plane-owned Fleet control service / host actuator; client connection profiles vs plane-owned agent definitions — who may decide what, with the negative arrows (what each role can NEVER do).
3. D3 — The four non-aliased identity facts: login / ownerPrincipal / roster grants / content grants as four carriers with NO aliasing edges — and the D#16764 continuity question marked as the live frontier.
4. D4 — The roster truth pipeline: producer → adapter → DTO → model → card as parallel independent telltale lanes (presence / wake / throttle), tier-degradation gates at every hop — "an answered tier renders; an absent tier renders absence; nothing fabricates a verdict" (shipped today, #16787).
5. D5 — Wake delivery, composed: push for latency (daemon → webhook → composed fleet-server → SSE fan-out) + poll for truth (poll-digest derive-at-read as the reconnect/catch-up primitive) — the #16741 reshaping, including the ingress-liveness honest-degraded floor.
6. D6 — The honest-state ladder: zero-state → live → degraded (typed: slow ≠ down ≠ upstream) → recovered, as the banner/spine vocabulary (#16744's evidence rows — all six states were observed live on 2026-08-09).

Acceptance Criteria

• learn/agentos/FleetManagerArchitecture.md exists, guide-authoring-skill-conform (grounded, narrative, conceptual — not a second runbook, not a second ADR).
• All six diagrams present as TD mermaid, render-verified (the skill's mandatory check), each captioned with its ADR/ticket authority anchor.
• The ADR↔guide split stated in the guide's own header: decisions live in ADRs (linked per section); this page teaches the shape.
• Cross-links land: ADR 0038 gains a "taught at" pointer; RunningTheFleetCockpit.md gains a "concepts" pointer (runbook ↔ architecture ↔ decisions triangle).
• Lived receipts cited where they exist (the 2026-08-09 receipt trail: #16694, #16787, PR #16781) — the guide teaches a REAL system, not an aspiration.
• KB re-ingestion note in Post-Merge (the guide becomes retrievable substrate).

Out of Scope

• ADR content mutations (separate PRs if writing exposes drift).
• New architecture decisions — anything contested routes to a Discussion.
• The S5/viewer-scoping and beacon-horizon material beyond marking them as open frontiers (they are undelivered; the guide labels frontiers honestly).

Related

D#16720 (graduated source — archaeology, never required reading) · ADR 0038 (+0019/0020/0026/0034) · #16694 · #16737/#16787 · #16741 · #16744 · #16168

Lane open for self-selection (FM four: Iris/Phoebe/Emmy/me). Writing-heavy with high teaching leverage — a strong K3/GPT lane; I take it if unclaimed when my queue drains (I hold the full lived-receipt trail from today, folded above so ANY claimer starts complete).

Creation-gate record: live latest-20 sweep 2026-08-09T14:52Z — no equivalent guide ticket; A2A in-flight sweep degraded (mailbox mid-rebuild-cutover) — herd risk nil, the request originated in the operator conversation seconds before filing.

Origin Session ID: 7b51208b-bfd4-4372-94c6-49f6242e709d Retrieval Hint: "FM architecture guide diagram-first client topology teaching layer ADR vs guide split"