This leaf turns the existing DockLayoutsAdoption guide into the practical stage-one integration guide for real applications. The host PR already updates its normative Decisions 1–2 in the same freeze as the API; this leaf delivers the broader explanatory rewrite and validated migration path.
The first-layout tutorial is a separate beginner deliverable. This guide answers how an application supplies ordinary panes, initial selection and existing document state without becoming a dock-engine implementer.
The Problem
The existing guide teaches manual seed/mount and resolvePane as basic application responsibilities. Minimal normative corrections keep it truthful when the host lands, but do not by themselves explain integration: lazy modules, header/policy data, computed initial declarations, supplied-document precedence, runtime operations, and migration from the manual pattern.
The Architectural Reality
Target: learn/guides/uibuildingblocks/DockLayoutsAdoption.md; preserve its existing public route rather than adding a competing adoption guide.
Its source registrations already exist in learn/tree.json and buildScripts/docs/seo/generate.mjs PRIORITIES. Change registration only if the actual navigation/title changes.
#18476 is the source of truth for once-only consumption, current-document precedence, post-consumption assignment and declared-pane lifecycle.
#18477 is the concrete manual-to-declarative example. Model detail remains in learn/agentos/DockZoneModel.md and public API JSDoc.
Ordinary state/provider and component construction remain framework concerns; the guide must not invent a dock-specific provider registry or a reactive panes_ contract.
The Fix
Rewrite the guide around a real application's integration decisions, validated by running the resulting code:
Declare ordinary panes with lazy module/ntype/className, header content, existing policy hints and normal component configuration. Explain pane key as a stable application reference, including two same-class panes with different configuration.
Declare initial zones, or compute the initial pane selection/placement at the exact lifecycle point supported by #18476. A static choice based on available application data is not a live authorization subscription.
Supply an existing valid dockModel when the application already owns one; demonstrate that its placement wins over defaults. Explain post-consumption assignment behavior exactly as shipped.
Use documented runtime operations and the host's standard declared-pane lifecycle after boot. Distinguish altering a future default from changing the current layout.
Migrate a manual graph/resolver consumer using #18477's before/after responsibilities. Name what disappears and what remains legitimate application work, including the example's existing perspective/tour code.
Keep detailed grammar and operation tables in the reference. Cross-link the first-layout tutorial when available, the existing runnable example, source/API reference and ADR. Teach no proposed perspectives, persistence, workspaces or reactive-bound-panes config.
Reader can replace initial graph/resolver responsibilities without deleting unrelated application features
Advanced custom hooks remain explicit, not the default path
Before/after responsibility walkthrough
Execute migrated example and inspect retained behaviors
Discovery/reference boundary
Existing guide route, tree.json, SEO PRIORITIES
One authoritative adoption guide linked from beginner/example/reference material
No broken or duplicate guide route
Cross-links and existing registration
Portal navigation/render/link verification
Discussion Criteria Mapping
Source criteria 1, 2 and 4: a real application can supply ordinary panes, compute its initial selection at the documented lifecycle point, preserve supplied state and migrate from manual plumbing.
Acceptance Criteria
AC-1: Rewrite DockLayoutsAdoption.md into a complete real-application stage-one guide; preserve the same public route and the host PR's normative semantics.
AC-2: Run the lazy-pane/header/policy example, two same-class panes with distinct configuration, and computed initial selection at the documented lifecycle point. Document observed behavior without claiming live rebinding.
AC-3: Demonstrate supplied-document precedence against a deliberately different declared default. After a runtime move, a later panes/zones assignment behaves exactly as the host contract states and does not restore defaults.
AC-4: Include a concrete manual-to-declarative migration based on #18477. The basic consumer needs no custom resolver/cache/projection hook; existing perspective/tour behavior remains application code until its own later stage.
AC-5: Update the introductory learn/guides/uibuildingblocks/DockLayouts.md section "Adopting docking in your application" so it no longer teaches manual graph seeding, first-shell mounting and a custom resolver as the default adoption path; replace or redirect it to the shipped declarative guidance while keeping advanced raw-document support explicit. Cross-link the beginner tutorial, public example and detailed API/model reference without duplicating their catalogs. If the beginner tutorial is still pending, retain usable existing links and add its link in the later of the two guide PRs.
AC-6: Render-verify the whole rewritten guide, including a useful diagram, snippets, navigation and links in the portal. The PR carries live-use grounding and exact-head evidence; prose-only review is insufficient.
AC-7: Do not introduce later-stage APIs, API implementation changes, client-specific examples, tracker archaeology in learn/guides, or generated portal SEO output commits.
Validation
Run the documented application/examples from the exact implementation checkout:
npm run server-start -- --port <free-port> --no-open
Reproduce the guide's cases and open the complete guide through the portal navigation. Record the exact head, the compared default/supplied layouts, lazy/same-class observations and the later-assignment result. Verify source registration and link integrity with the canonical available guide/navigation checks; do not substitute a unit test for rendering or for executing the instructions.
Dependencies and Decision Record
Native blocked-by dependencies: #18476 and #18477. This order avoids overwriting the host's same-PR normative Decisions 1–2 changes and provides a real completed migration example. The beginner guide may proceed in parallel after these dependencies.
Decision Record: REQUIRED at the parent capability; the normative ADR amendment is delivered by #18476.
Decision Record impact: aligned-with the host's ADR 0029 amendment. This guide explains the shipped API and does not reopen its design.
Out of Scope
Beginner first-run tutorial authoring, exhaustive reference duplication, model/host changes, new example features, storage ownership, topology/window authoring, reactive catalog/authorization/history policy.
Avoided Traps
No renamed copy of the old manual-resolver guide; no documentation of scratch functions as public APIs; no required import from projection/reconciliation/native-admission internals; no assumption that readable prose proves the code path works.
Related and Pickup
Related: #18474; #18476; #18477.
unowned-rationale: Dedicated adoption-guide work available for peer self-selection; coordinate the existing guide file with the host owner before editing.
Retrieval Hint: DockLayoutsAdoption stage-one rewrite; ordinary panes, computed initial config, supplied dockModel precedence, manual graph/resolver migration, portal verification.
Latest 20 open issues and latest 30 all-state A2A checked immediately before filing. #18478 owns a new beginner tutorial; this leaf deliberately rewrites the existing application-adoption route, so their audiences and file ownership differ. No competing adoption-guide leaf exists. MC problem query covered manual resolver/seed guidance in application integration; no actionable conflicting ruling surfaced. Eight own assignments checked; generic contributor onboarding is not this guide. Existing learning-tree and SEO registrations, the server command, and the shipped-source baseline were verified. No new .mjs file or source directory is prescribed.
Part of #18474. Blocked by #18476 and #18477.
Context
This leaf turns the existing DockLayoutsAdoption guide into the practical stage-one integration guide for real applications. The host PR already updates its normative Decisions 1–2 in the same freeze as the API; this leaf delivers the broader explanatory rewrite and validated migration path.
The first-layout tutorial is a separate beginner deliverable. This guide answers how an application supplies ordinary panes, initial selection and existing document state without becoming a dock-engine implementer.
The Problem
The existing guide teaches manual seed/mount and resolvePane as basic application responsibilities. Minimal normative corrections keep it truthful when the host lands, but do not by themselves explain integration: lazy modules, header/policy data, computed initial declarations, supplied-document precedence, runtime operations, and migration from the manual pattern.
The Architectural Reality
The Fix
Rewrite the guide around a real application's integration decisions, validated by running the resulting code:
Keep detailed grammar and operation tables in the reference. Cross-link the first-layout tutorial when available, the existing runnable example, source/API reference and ADR. Teach no proposed perspectives, persistence, workspaces or reactive-bound-panes config.
Contract Ledger Matrix
Discussion Criteria Mapping
Source criteria 1, 2 and 4: a real application can supply ordinary panes, compute its initial selection at the documented lifecycle point, preserve supplied state and migrate from manual plumbing.
Acceptance Criteria
learn/guides/uibuildingblocks/DockLayouts.mdsection "Adopting docking in your application" so it no longer teaches manual graph seeding, first-shell mounting and a custom resolver as the default adoption path; replace or redirect it to the shipped declarative guidance while keeping advanced raw-document support explicit. Cross-link the beginner tutorial, public example and detailed API/model reference without duplicating their catalogs. If the beginner tutorial is still pending, retain usable existing links and add its link in the later of the two guide PRs.Validation
Run the documented application/examples from the exact implementation checkout:
Reproduce the guide's cases and open the complete guide through the portal navigation. Record the exact head, the compared default/supplied layouts, lazy/same-class observations and the later-assignment result. Verify source registration and link integrity with the canonical available guide/navigation checks; do not substitute a unit test for rendering or for executing the instructions.
Dependencies and Decision Record
Native blocked-by dependencies: #18476 and #18477. This order avoids overwriting the host's same-PR normative Decisions 1–2 changes and provides a real completed migration example. The beginner guide may proceed in parallel after these dependencies.
Decision Record: REQUIRED at the parent capability; the normative ADR amendment is delivered by #18476.
Decision Record impact: aligned-with the host's ADR 0029 amendment. This guide explains the shipped API and does not reopen its design.
Out of Scope
Beginner first-run tutorial authoring, exhaustive reference duplication, model/host changes, new example features, storage ownership, topology/window authoring, reactive catalog/authorization/history policy.
Avoided Traps
No renamed copy of the old manual-resolver guide; no documentation of scratch functions as public APIs; no required import from projection/reconciliation/native-admission internals; no assumption that readable prose proves the code path works.
Related and Pickup
Related: #18474; #18476; #18477. unowned-rationale: Dedicated adoption-guide work available for peer self-selection; coordinate the existing guide file with the host owner before editing. Retrieval Hint: DockLayoutsAdoption stage-one rewrite; ordinary panes, computed initial config, supplied dockModel precedence, manual graph/resolver migration, portal verification.
Origin Session ID: 4f9b7bbe-9dbc-4d36-a167-38fe0d288113
Creation checks
Latest 20 open issues and latest 30 all-state A2A checked immediately before filing. #18478 owns a new beginner tutorial; this leaf deliberately rewrites the existing application-adoption route, so their audiences and file ownership differ. No competing adoption-guide leaf exists. MC problem query covered manual resolver/seed guidance in application integration; no actionable conflicting ruling surfaced. Eight own assignments checked; generic contributor onboarding is not this guide. Existing learning-tree and SEO registrations, the server command, and the shipped-source baseline were verified. No new .mjs file or source directory is prescribed.