Context
learn/guides/uibuildingblocks/DockLayouts.md (#17514, merged 2026-08-21) is the subsystem's first architecture guide — an intro: the ownership loop, one gesture end to end, the four-row state discipline, the adoption checklist, the wire vocabulary, the traps. It reviewed at 9/10, and it is one page for a subsystem of 29 engine modules, four host apps, and a multi-window choreography.
Operator direction (2026-08-22): once the host-class debt is resolved, double down on guides — mechanics, features, and how docking connects to ordinary Neo UIs — as a series, with one mental model at the front: a human or an AI peer asking "how can I use and configure it inside MY Neo app?"
The Problem
The intro answers "what is this and why does it work"; it does not answer the adopter's questions in order. Today a reader who wants docking in their own app has to reverse-engineer one of the hosts (4–5k lines each until the host class lands), the ADR, and the model contract. The Knowledge Base inherits the same gap: a question about configuring panes, vessels, perspectives or auto-hide in a consumer app has no single guide to cite, so answers are stitched from the ADR and source.
Why an epic: each guide is its own authored, reviewed, tree-registered artifact under guide-authoring (grounding, render-verified Mermaid, cross-family review); the set shares one mental model, one vocabulary, and one sequencing constraint (the adoption guide must teach extends DockWorkspace, so it lands after the host class) — coordination a single ticket cannot carry.
Intended Solution Shape
A series under the existing guides/uibuildingblocks tree node, the intro kept as its front door and each part answering one adopter question in the order an adopter asks it: adopting and configuring docking in your own app (document, panes, policies, vessel render target, persistence, theming by tokens); the mechanics as they run (gesture, claim, vessel lifecycle, conversion, reintegration); the features (perspectives, auto-hide rails, grouped drag, overflow, keyboard); and how it connects to Neo UIs (panes as ordinary components — state providers, stores, tab containers, controllers, layouts). Every part follows the house pattern the intro established (ownership loop plus one-gesture pairing, claims with receipts, traps with tickets), and every code example runs against the engine class, not a hand-rolled host. Placement inside the tree, part naming and the exact split are the first leaf's structural pre-flight, not this body's.
Out of Scope
- Rewriting the intro (
DockLayouts.md) beyond the one correction the host-class epic owes it.
- Reference documentation generated from JSDoc; the ADR and the model contract stay the authority tiers.
- Video or film assets (the
#15252 arc).
Avoided Traps
- One giant page. The intro is already at the length where a reader stops; the series exists so each part can go deep.
- Teaching the hand-rolled host. A guide written against today's 5k-line hosts teaches the debt; the adoption part sequences after the engine class.
- Prose over receipts. The house pattern cites a witness for every mechanical claim; a guide part without receipts fails its own review.
Decision Record impact
none — the guides describe; ADR 0029 and DockZoneModel.md decide.
Related
#17514 (the intro) · the dock-host epic (linked; the adoption part is blocked by its first leaf) · #13158.
Structure-map gate: N/A — learn/guides content; no Agent OS placement.
Live latest-open sweep: checked latest 20 open issues at 2026-08-22T12:58:37Z; no equivalent found (only #17514, closed, the intro). A2A in-flight claim sweep: latest 30 all-state messages at the same timestamp; no overlapping claim found.
Origin Session ID: bd272031-6109-449d-8a0c-38230064a8f3
Retrieval Hint: query_raw_memories("dock layouts guide series adopt configure mechanics features Neo UI mental model")
Mnemosyne (Claude Fable 5, Claude Code) 🪢
Sequencing update 2026-08-28 — parts 2–4 wait for the v13.2 greenfield rewrite (D#17818)
The operator-ruled hard-cut rewrite (Discussion #17818) renames the package anatomy, class namespace, and wire vocabulary this series teaches. Disposition, recorded by the epic owner:
- Part 1 (the adoption guide): SHIPPED — and it is explicitly inside the rewrite's own guide-update scope, so the rewrite carries its refresh.
- Parts 2–4 (mechanics, features, panes) are sequenced BEHIND the rewrite. Authoring them now would teach class names and schema strings the cut renames — the exact rot class this series' own lint rule exists to prevent.
- At the rewrite's implementation-epic filing, parts 2–4 fold there as guide leaves (the rewrite's expected target is code-and-guide leaves only), and this epic closes as superseded by that epic.
No part-2/3/4 sub files under this epic before the cut lands.
Context
learn/guides/uibuildingblocks/DockLayouts.md(#17514, merged 2026-08-21) is the subsystem's first architecture guide — an intro: the ownership loop, one gesture end to end, the four-row state discipline, the adoption checklist, the wire vocabulary, the traps. It reviewed at 9/10, and it is one page for a subsystem of 29 engine modules, four host apps, and a multi-window choreography.Operator direction (2026-08-22): once the host-class debt is resolved, double down on guides — mechanics, features, and how docking connects to ordinary Neo UIs — as a series, with one mental model at the front: a human or an AI peer asking "how can I use and configure it inside MY Neo app?"
The Problem
The intro answers "what is this and why does it work"; it does not answer the adopter's questions in order. Today a reader who wants docking in their own app has to reverse-engineer one of the hosts (4–5k lines each until the host class lands), the ADR, and the model contract. The Knowledge Base inherits the same gap: a question about configuring panes, vessels, perspectives or auto-hide in a consumer app has no single guide to cite, so answers are stitched from the ADR and source.
Why an epic: each guide is its own authored, reviewed, tree-registered artifact under
guide-authoring(grounding, render-verified Mermaid, cross-family review); the set shares one mental model, one vocabulary, and one sequencing constraint (the adoption guide must teachextends DockWorkspace, so it lands after the host class) — coordination a single ticket cannot carry.Intended Solution Shape
A series under the existing
guides/uibuildingblockstree node, the intro kept as its front door and each part answering one adopter question in the order an adopter asks it: adopting and configuring docking in your own app (document, panes, policies, vessel render target, persistence, theming by tokens); the mechanics as they run (gesture, claim, vessel lifecycle, conversion, reintegration); the features (perspectives, auto-hide rails, grouped drag, overflow, keyboard); and how it connects to Neo UIs (panes as ordinary components — state providers, stores, tab containers, controllers, layouts). Every part follows the house pattern the intro established (ownership loop plus one-gesture pairing, claims with receipts, traps with tickets), and every code example runs against the engine class, not a hand-rolled host. Placement inside the tree, part naming and the exact split are the first leaf's structural pre-flight, not this body's.Out of Scope
DockLayouts.md) beyond the one correction the host-class epic owes it.#15252arc).Avoided Traps
Decision Record impact
none — the guides describe; ADR 0029 and
DockZoneModel.mddecide.Related
#17514(the intro) · the dock-host epic (linked; the adoption part is blocked by its first leaf) ·#13158.Structure-map gate: N/A —
learn/guidescontent; no Agent OS placement.Live latest-open sweep: checked latest 20 open issues at 2026-08-22T12:58:37Z; no equivalent found (only
#17514, closed, the intro). A2A in-flight claim sweep: latest 30 all-state messages at the same timestamp; no overlapping claim found.Origin Session ID: bd272031-6109-449d-8a0c-38230064a8f3
Retrieval Hint:
query_raw_memories("dock layouts guide series adopt configure mechanics features Neo UI mental model")Mnemosyne (Claude Fable 5, Claude Code) 🪢
Sequencing update 2026-08-28 — parts 2–4 wait for the v13.2 greenfield rewrite (D#17818)
The operator-ruled hard-cut rewrite (Discussion #17818) renames the package anatomy, class namespace, and wire vocabulary this series teaches. Disposition, recorded by the epic owner:
No part-2/3/4 sub files under this epic before the cut lands.