Context
Operator direction (2026-08-21/22, in-session): peers stopped understanding the architecture; the remedy that worked for the embedding lane — visualize the architecture so understanding enables action — becomes the house pattern: "more guides about architecture. dock layout included." Gated behind the harness-misnomer retirement: "no guides as long as ADRs include harness" — that condition CLEARED when PR #17507 merged (2026-08-21T22:04Z, 0e072f05cd).
DockLayouts is the v13.2 centerpiece with many eyes on it. The docking substrate has deep authority documents — learn/agentos/decisions/0029-docking-design.md (prescriptive, ~560 lines) and learn/agentos/DockZoneModel.md (descriptive contract) — but NO conceptual guide: nothing a peer or an adopting app builder reads first to hold the whole system. The ADR's own history proves the gap: its §5 leaf table went 8+ cells stale without anyone noticing (#17503), and this session's #16357 closed as already-resolved because nobody could see that a committed witness already guarded the class.
The Problem
The docking system is the strongest Body capability with the weakest narrative surface. What exists is decision-tier and contract-tier; what's missing is the explanation tier (Diátaxis): who owns what (model / adapter / reconciler / zones / vessels / coordinator / arbiter), how ONE gesture actually runs through the seams, which state lives where (the §2.1 four-row table, told as a story), what an app must do to adopt docking (the workstation as the worked example), the wire vocabulary (8 shipped identifiers, two compatibility classes per §2.9), and the traps (layout-blind panes, no parallel drag system, the schema freeze, engine-paint tokens once #17241 lands). Also missing: the honest moat story — the ADR §4 prior-art sweep shows no surveyed web library offers window-independent live-state docking; that story exists only inside a decision record nobody reads first.
The Architectural Reality
- Home:
learn/guides/uibuildingblocks/DockLayouts.md — Body-side, sibling to Layouts.md. The dock is a Body capability; its conceptual guide belongs in the Body's learning tree (also extraction-proof: wave-one custody keeps learn trees Engine-owned, but a Body guide in the Body section is correct in every topology). The agentos-side ADR + contract stay the deep tier, linked.
- Registration inputs:
learn/tree.json (guides/uibuildingblocks/DockLayouts) + buildScripts/docs/seo/generate.mjs PRIORITIES (0.8, matching Layouts). ⛔ Generated sitemap.xml/llms.txt untouched (pipeline-owned).
- Grounding already banked this session (guide-authoring §1): the same-gesture witness run headed 4/4 green (the subsystem exercised through its own oracle), the full ADR + contract read end-to-end, the wire census derived from source, the
#16357 closure receipts, and lived material from the workstation film arc (including the #17241 layer lesson learned the hard way).
The Fix
Author the guide to the guide-authoring 9/10 bar: narrative arc (the enterprise desktop-to-web friction → why web docking fails at the popout boundary → the SharedWorker answer → what the reader's app gets), ≥1 render-verified flowchart TD (the ownership map; the one-gesture walkthrough), the state-class story, the adoption recipe, the wire vocabulary with its two compatibility classes, the traps, attributed lived voice, and links down to ADR 0029 + DockZoneModel.md for depth. No client names. Never "framework".
Acceptance Criteria
Out of Scope
- Rewriting ADR 0029 or
DockZoneModel.md (deep tier stays as-is).
- The dockdemo relocation (
#16322), styling promotion (#17241), examples normalization (#17504) — the guide cites their current truth and will be touched up by whoever lands them if paths move.
- A dock API reference page (generated-reference territory).
Related
#17503 / PR #17507 (the unlock) · ADR 0029 · #13158 (QT-parity epic) · #17241 · #16322 · #17504 · the EmbeddingLane guide (the house pattern's first instance)
Live latest-open sweep: latest 20 checked 2026-08-22T~00:45 local; no equivalent. A2A claim sweep: Memory Core briefly unavailable at filing (known container wobble tonight) — risk assessed negligible: the guide was operator-directed to this seat in-session minutes ago, and the standing dock-docs lane-intent had an explicit peer no-collision; sweep to be caught up when MC returns.
Origin Session ID: 55e55313-48fa-4295-83fd-37121a2bf4b6
Retrieval Hint: "dock layouts architecture guide uibuildingblocks hero piece ownership map gesture walkthrough"
Context
Operator direction (2026-08-21/22, in-session): peers stopped understanding the architecture; the remedy that worked for the embedding lane — visualize the architecture so understanding enables action — becomes the house pattern: "more guides about architecture. dock layout included." Gated behind the harness-misnomer retirement: "no guides as long as ADRs include harness" — that condition CLEARED when PR #17507 merged (2026-08-21T22:04Z,
0e072f05cd).DockLayouts is the v13.2 centerpiece with many eyes on it. The docking substrate has deep authority documents —
learn/agentos/decisions/0029-docking-design.md(prescriptive, ~560 lines) andlearn/agentos/DockZoneModel.md(descriptive contract) — but NO conceptual guide: nothing a peer or an adopting app builder reads first to hold the whole system. The ADR's own history proves the gap: its §5 leaf table went 8+ cells stale without anyone noticing (#17503), and this session's#16357closed as already-resolved because nobody could see that a committed witness already guarded the class.The Problem
The docking system is the strongest Body capability with the weakest narrative surface. What exists is decision-tier and contract-tier; what's missing is the explanation tier (Diátaxis): who owns what (model / adapter / reconciler / zones / vessels / coordinator / arbiter), how ONE gesture actually runs through the seams, which state lives where (the §2.1 four-row table, told as a story), what an app must do to adopt docking (the workstation as the worked example), the wire vocabulary (8 shipped identifiers, two compatibility classes per §2.9), and the traps (layout-blind panes, no parallel drag system, the schema freeze, engine-paint tokens once
#17241lands). Also missing: the honest moat story — the ADR §4 prior-art sweep shows no surveyed web library offers window-independent live-state docking; that story exists only inside a decision record nobody reads first.The Architectural Reality
learn/guides/uibuildingblocks/DockLayouts.md— Body-side, sibling toLayouts.md. The dock is a Body capability; its conceptual guide belongs in the Body's learning tree (also extraction-proof: wave-one custody keeps learn trees Engine-owned, but a Body guide in the Body section is correct in every topology). The agentos-side ADR + contract stay the deep tier, linked.learn/tree.json(guides/uibuildingblocks/DockLayouts) +buildScripts/docs/seo/generate.mjsPRIORITIES(0.8, matchingLayouts). ⛔ Generatedsitemap.xml/llms.txtuntouched (pipeline-owned).#16357closure receipts, and lived material from the workstation film arc (including the#17241layer lesson learned the hard way).The Fix
Author the guide to the guide-authoring 9/10 bar: narrative arc (the enterprise desktop-to-web friction → why web docking fails at the popout boundary → the SharedWorker answer → what the reader's app gets), ≥1 render-verified
flowchart TD(the ownership map; the one-gesture walkthrough), the state-class story, the adoption recipe, the wire vocabulary with its two compatibility classes, the traps, attributed lived voice, and links down to ADR 0029 + DockZoneModel.md for depth. No client names. Never "framework".Acceptance Criteria
learn/guides/uibuildingblocks/DockLayouts.mdexists and clears the guide-authoring bar §§1–5 (grounding evidence in the PR body; self-grade against the bar included).flowchart TDrender-verified in a browser before merge (method named in the PR).learn/tree.json(ai:lint-tree-jsongreen) + the SEOPRIORITIESmap; generated outputs untouched.Out of Scope
DockZoneModel.md(deep tier stays as-is).#16322), styling promotion (#17241), examples normalization (#17504) — the guide cites their current truth and will be touched up by whoever lands them if paths move.Related
#17503/ PR#17507(the unlock) · ADR 0029 ·#13158(QT-parity epic) ·#17241·#16322·#17504· the EmbeddingLane guide (the house pattern's first instance)Live latest-open sweep: latest 20 checked 2026-08-22T~00:45 local; no equivalent. A2A claim sweep: Memory Core briefly unavailable at filing (known container wobble tonight) — risk assessed negligible: the guide was operator-directed to this seat in-session minutes ago, and the standing dock-docs lane-intent had an explicit peer no-collision; sweep to be caught up when MC returns.
Origin Session ID: 55e55313-48fa-4295-83fd-37121a2bf4b6 Retrieval Hint: "dock layouts architecture guide uibuildingblocks hero piece ownership map gesture walkthrough"