Dock guide series part 1: the adoption guide — docking in YOUR app, taught against the engine class

Context

Leaf 1 of epic #17540, unblocked today: Neo.dashboard.DockWorkspace is merged with two real consumers proving its shape — the example (examples/dashboard/dock/, minimal) and the workstation (apps/workstation/, richest; #17546 / PR #17565 @ 5c9b8aaddc). The operator's mental model for the whole series fronts this part: a human or an AI peer asking "how can I use and configure it inside MY Neo app?"

The Problem

The intro (learn/guides/uibuildingblocks/DockLayouts.md) answers "what is this and why does it work" and now carries a correct but compressed adoption checklist. An adopter's actual question sequence — what do I extend, what do I seed, how do my components become panes, what policies can I set, how do I skin it, how do layouts persist, what does a tear-out window need from me — has no page that answers it in order, with runnable configuration and receipts. The Knowledge Base inherits the gap.

The Fix

1. Structural pre-flight (recorded on the epic before authoring): the series' placement under the guides/uibuildingblocks tree node, part naming, and the exact split — the intro stays the front door; this leaf ratifies the four-part shape (adopt / mechanics / features / Neo-UIs) or corrects it with reasons.
2. The adoption guide (name per pre-flight, e.g. DockAdoptingInYourApp.md): teaches extends Neo.dashboard.DockWorkspace end to end in a consumer app —
   • the committed document: shape, seeding in construct, the initial projectDockModel() shell mount, dockShellIndex / dockHostReference when chrome or overlay siblings exist;
   • panes: resolvePane mapping the item catalog to YOUR components (live instances vs configs vs blueprints), resolveRevealPane, header text, the FLIP marker arriving for free;
   • policies at the operation layer, taught truthfully: pinnable / movable are enforced by the model today (never by UI code); closable is a declared catalog field whose close-routing enforcement is #17419's open leaf — the guide presents it as a forward contract, not as enforced (corrected 2026-08-22 per PR review round 1: the original wording here claimed three-policy enforcement; closeItem does not yet consult closable);
   • the hooks catalog with the two live receipts: what the minimal consumer overrides (almost nothing) vs what the richest one does (getDockProjectionOptions, getRefreshOptions mapping commit shapes, getReconcileOptions' three sanctioned seams, awaited afterRefreshDockWorkspace) — and the hook-admission rule as the reader's own bar;
   • theming by tokens: override anchor (neo-dock-workspace) vs default carrier (.neo-dashboard), additionalThemeFiles replacement semantics, the app-root Viewport trap;
   • persistence: createSavedLayout / restoreSavedLayout, the perspective-carrying envelope, fail-closed restore;
   • the vessel render target: the deliberately empty child-app viewport a tear-out window needs;
   • failure semantics the adopter inherits: settled-tail commits, loud missing host, the empty projection. Every snippet consistent with one of the two live consumers (cited); house pattern throughout (claims with receipts, traps with tickets, render-verified Mermaid where a diagram earns its place); registered in learn/tree.json; intro gains its forward link to the series.

Acceptance Criteria

• Structural pre-flight recorded as an epic comment (placement, names, split ratified or corrected) before the guide lands.
• The adoption guide exists under learn/guides/uibuildingblocks/, registered in learn/tree.json, and answers the adopter sequence above in order, every code snippet consistent with examples/dashboard/dock/ or apps/workstation/ at head (cited inline).
• House pattern held: receipts for mechanical claims, traps section with ticket references, any Mermaid render-verified.
• DockLayouts.md (the intro) links forward to the series; no other intro change.
• npm run ai:lint-guides 0 hard; lint-tree-json green.
• Cross-family review under guide-authoring.

Out of Scope

• Parts 2–4 (mechanics / features / Neo-UIs) — their own leaves, sequenced by the pre-flight.
• Any engine change; any intro rewrite beyond the forward link.

Related

Parent #17540 · #17514 (the intro) · #17539 / #17541 / #17546 (the class and its two consumers) · #13158.

Live latest-open sweep: latest 12 open issues checked at 2026-08-22T19:48Z; no equivalent found. A2A in-flight claim sweep: inbox drained to zero at 19:23Z + redeliveries verified; no overlapping claim.

Origin Session ID: bd272031-6109-449d-8a0c-38230064a8f3

Retrieval Hint: query_raw_memories("dock adoption guide extends DockWorkspace your app seed document resolvePane policies tokens persistence vessel")

Mnemosyne (Claude Fable 5, Claude Code) 🪢