The original series reserved a dedicated Features guide. Since then, DockLayouts gained resizable split and edge boundaries, auto-hide rails, perspectives, grouped tab movement and overflow, locking, keyboard behavior, and a default inline action rail with reload, pin, pop-out, maximize, and close.
The Problem
The current guides explain the architecture and adoption decisions, but not the landed product surface as a coherent reader journey. A developer must search examples, tests, and source to learn what exists, which capabilities are policy-controlled, and which combinations belong together.
The Architectural Reality
The feature surface spans Workspace.mjs, interaction/{Rail,RevealOverlay,KeyboardCommands,TabSortZone,DockSplitter}.mjs, projection configuration, perspectives, and host-contributed action/lifecycle hooks. Features share the same committed-document and projection architecture; they are not independent widgets.
The Fix
Create learn/guides/uibuildingblocks/DockLayoutsFeatures.md: a narrative tour of the complete stabilized feature surface, organized by user outcome and configuration decision rather than a flat checklist.
Contract Ledger
Target Surface
Source of Authority
Proposed Behavior
Fallback
Docs
Evidence
Feature guide
Current Workspace, interactions, examples, ADR 0029
Explain supported outcomes and how consumers opt in/configure policy
Do not promise unverified behavior
New guide
Live consumer journeys plus current-source checks
Capability claims
Live classes + rendered consumers
Demonstrated outcomes name their receipts; current-source explanations are labelled separately, with honest limits
Never present a source explanation as an observed journey
Same guide
Named consumer receipts and current implementation/ADR checks
Registration
Existing guide siblings
One discoverable UI-building-blocks guide
No generated-output edits
tree + SEO inputs
lint + rendered portal
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains landed capabilities.
Acceptance Criteria
The guide clears the full guide-authoring bar: source/tool-grounded narrative, reader-owned benefits, lived maintainer voice, and at least one render-verified flowchart TD.
The guide separates explanation from reference: no inlined API/schema/test catalog, and no ticket or PR ids in guide prose.
The new source guide is registered in learn/tree.json and the SEO PRIORITIES input; generated sitemap/LLM outputs remain untouched.
Current-source consistency, guide lint, tree lint, portal rendering, and an independent cross-family whole-guide review are recorded in the PR.
The guide covers the stabilized feature families: resizing, tabs/overflow, rails/pin, perspectives, action rail, lock/keyboard, and drag/drop outcomes.
Each feature is grounded in current implementation/ADR authority, with capability/policy limits stated. Claims of live demonstration carry a real consumer-action or subsystem-tool receipt; source-explained contracts are explicitly distinguished from demonstrated outcomes.
The narrative routes readers to the deeper mechanics, state, window, pane, and styling guides instead of duplicating them.
Demonstrated outcomes, current-source contracts not exercised in this guide, and unclaimed/future behavior are explicitly separated.
Review scope clarification
PR #18700 R1 allowed accurate source-contract explanation in place of invented live-demonstration claims. As the original ticket author, I am aligning the evidence rows and AC-6/AC-8 with that accepted distinction: the guide still covers every feature family, but does not claim it exercised every family on one example page. This supersedes the original all-features-live-demonstrated wording and adds no execution evidence. The public review records the concrete receipts and their limits.
Out of Scope
An API/config reference table, roadmap checklist, or implementation change.
Avoided Traps
Do not write a marketing matrix, call a hidden action unsupported, infer support from a class name alone, or present a source explanation as a live journey.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Retrieval Hint: query_raw_memories("DockLayouts guide series post-refactor final API")
Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.
Context
The original series reserved a dedicated Features guide. Since then, DockLayouts gained resizable split and edge boundaries, auto-hide rails, perspectives, grouped tab movement and overflow, locking, keyboard behavior, and a default inline action rail with reload, pin, pop-out, maximize, and close.
The Problem
The current guides explain the architecture and adoption decisions, but not the landed product surface as a coherent reader journey. A developer must search examples, tests, and source to learn what exists, which capabilities are policy-controlled, and which combinations belong together.
The Architectural Reality
The feature surface spans
Workspace.mjs,interaction/{Rail,RevealOverlay,KeyboardCommands,TabSortZone,DockSplitter}.mjs, projection configuration, perspectives, and host-contributed action/lifecycle hooks. Features share the same committed-document and projection architecture; they are not independent widgets.The Fix
Create
learn/guides/uibuildingblocks/DockLayoutsFeatures.md: a narrative tour of the complete stabilized feature surface, organized by user outcome and configuration decision rather than a flat checklist.Contract Ledger
Decision Record impact
aligned-with ADR 0029
Decision Record
Not needed; this guide explains landed capabilities.
Acceptance Criteria
flowchart TD.learn/tree.jsonand the SEOPRIORITIESinput; generated sitemap/LLM outputs remain untouched.Review scope clarification
PR #18700 R1 allowed accurate source-contract explanation in place of invented live-demonstration claims. As the original ticket author, I am aligning the evidence rows and AC-6/AC-8 with that accepted distinction: the guide still covers every feature family, but does not claim it exercised every family on one example page. This supersedes the original all-features-live-demonstrated wording and adds no execution evidence. The public review records the concrete receipts and their limits.
Out of Scope
An API/config reference table, roadmap checklist, or implementation change.
Avoided Traps
Do not write a marketing matrix, call a hidden action unsupported, infer support from a class name alone, or present a source explanation as a live journey.
Activation Gate
Do not author the guide while #17836 remains an active refactoring authority. At pickup, re-run Memory Core mining, read the current ADR 0029 and source/test surfaces named below, exercise the relevant live subsystem, and revalidate the proposed guide boundary. If the final API makes this split wrong, reshape this ticket before writing—do not preserve a stale outline.
Related
Related: parent guide Epic #17540; blocked by active DockLayouts refactor Epic #17836; authority ADR 0029.
Origin Session ID: 309a78d7-2d95-4f23-bdfc-69d2ae393a5d
Retrieval Hint:
query_raw_memories("DockLayouts guide series post-refactor final API")Creation freshness: live created-descending sweep of the latest 20 open Engine issues at 2026-09-01T17:49:38Z found no equivalent guide ticket; the all-state latest-30 A2A sweep found no overlapping guide claim. The Knowledge Base returned stale pre-cut names, so live source, ADR 0029, and the current guide tree remain authority.