Part of #18474. Blocked by #18476 and #18477.
Context
A basic declaration API is not adoptable if a newcomer still has to reverse-engineer an advanced demo. This leaf publishes a beginner tutorial that takes a reader from an ordinary Neo application to a visible, usable standalone dock layout using the shipped stage-one API.
The user explicitly requires this guide as a separate deliverable. It is not replaced by model reference documentation or by the example's source comments.
The Problem
Current adoption material begins with manual document seeding and resolution. After #18476 changes that contract, a first-time reader needs a direct working path: declare a few ordinary panes, place them, run the example, and understand the resulting tabs/split/edge rail without learning projection internals.
The Architectural Reality
- #18476 owns the exact public panes/zones, lifecycle, supplied-document and later-assignment semantics; #18477 supplies the shipped example.
- The existing learning tree has DockLayouts and DockLayoutsAdoption under learn/guides/uibuildingblocks. DockZoneModel is technical reference under learn/agentos.
- learn/tree.json is navigation input; buildScripts/docs/seo/generate.mjs PRIORITIES is the ranking input. Generated portal sitemap/llms output is pipeline-owned.
- ADR 0029 keeps pane components layout-blind. A beginner pane should be an ordinary component.
The Fix
Create a first-layout tutorial under learn/guides/uibuildingblocks, choosing a clear non-duplicating title/path at intake and registering it in the source navigation and SEO-priority inputs.
Build and run the tutorial before writing the final prose. Start with an ordinary application/Workspace import, show a small complete panes/zones declaration, then explain what the reader sees and how to change one useful detail. Include at least a split, a tab group, an edge auto-hidden pane and an ordinary lazy module. Give complete run/navigation instructions and a link to the shipped runnable example; no omitted prerequisite should require private Discussion knowledge.
Explain generated structural IDs through the benefit of not maintaining them, not through an algorithm tutorial. Show a runtime move/rail reveal without changing the initial config. Briefly state that stage one is initial-only and persistence is not automatically enabled. Link to the adoption guide for computed/app integration and to the model/API reference for detailed grammar.
Contract Ledger Matrix
| Target surface |
Source of authority |
Required behavior |
Refusal / fallback |
Docs |
Evidence |
| Beginner instructions/snippets |
Final #18476 API and #18477 example |
A reader can create and run the shown standalone layout without internal hooks/imports |
Errors and prerequisites explained from observed behavior |
New first-layout tutorial |
Reproduce the written steps in a fresh basic consumer |
| Navigation/discovery |
learn/tree.json and SEO PRIORITIES |
Guide is reachable from the learning navigation and related dock material |
Broken links or missing registration fail this leaf |
Source registration and cross-links |
Rendered portal navigation/link checks |
| Scope and learning progression |
D#18468 stage one |
Teach declarations and visible behavior; link deeper reference instead of copying it |
No advertised later-stage APIs |
Tutorial plus references |
Source/snippet audit and guide review |
| Rendered explanation |
Guide-authoring bar |
Readable prose/code, observed images where used, and at least one useful rendered diagram |
Repair broken or unreadable rendering before delivery |
Actual portal rendering |
Browser receipt at the PR head |
Discussion Criteria Mapping
Source criteria 1 and 4: a newcomer can discover, follow and run the basic stage-one declaration workflow without projection/resolver internals or private discussion history.
Acceptance Criteria
Validation
Use the shipped example's normal run path:
npm run server-start -- --port <free-port> --no-open
Open the documented example and the portal guide from the same checkout. The PR records the exact head, successful step-by-step run, rendered diagram/code/navigation checks and links followed. Run available source navigation/guide checks through their canonical owner; verify the actual script exists before naming its invocation. A generic unit-test pass is not tutorial usability evidence.
Dependencies and Decision Record
Native blocked-by dependencies: #18476 and #18477. Both APIs and the runnable example must exist before this tutorial can be accepted; drafting preparation may proceed independently.
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. No authority change; explanations link to the committed reference.
Out of Scope
API implementation, example refactoring, exhaustive configuration reference, broad adoption/migration guidance, persistence, multi-window or reactive-pane features.
Avoided Traps
No source-only proof of a runnable tutorial; no copy of the advanced demo presented as a beginner recipe; no generated output commits; no duplicated configuration catalog.
Related and Pickup
Related: #18474; #18476; #18477.
unowned-rationale: Dedicated guide work available for peer self-selection after the host/example contracts; not implicitly owned by their implementers.
Retrieval Hint: first standalone dock layout tutorial; panes/zones beginner run, discoverable navigation and portal render 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: no equivalent first-layout tutorial ticket. The existing adoption page is retained by a separate, deliberately different integration-guide leaf. MC problem query covered the manual seed/mount/resolver burden on first-time readers; no actionable conflicting ruling surfaced. Eight own assignments checked; general contributor onboarding is separate from this product tutorial. learn/tree.json, SEO PRIORITIES, the server-start command and the actual portal/example paths were checked from source. No new .mjs file or source directory is prescribed.
Part of #18474. Blocked by #18476 and #18477.
Context
A basic declaration API is not adoptable if a newcomer still has to reverse-engineer an advanced demo. This leaf publishes a beginner tutorial that takes a reader from an ordinary Neo application to a visible, usable standalone dock layout using the shipped stage-one API.
The user explicitly requires this guide as a separate deliverable. It is not replaced by model reference documentation or by the example's source comments.
The Problem
Current adoption material begins with manual document seeding and resolution. After #18476 changes that contract, a first-time reader needs a direct working path: declare a few ordinary panes, place them, run the example, and understand the resulting tabs/split/edge rail without learning projection internals.
The Architectural Reality
The Fix
Create a first-layout tutorial under learn/guides/uibuildingblocks, choosing a clear non-duplicating title/path at intake and registering it in the source navigation and SEO-priority inputs.
Build and run the tutorial before writing the final prose. Start with an ordinary application/Workspace import, show a small complete panes/zones declaration, then explain what the reader sees and how to change one useful detail. Include at least a split, a tab group, an edge auto-hidden pane and an ordinary lazy module. Give complete run/navigation instructions and a link to the shipped runnable example; no omitted prerequisite should require private Discussion knowledge.
Explain generated structural IDs through the benefit of not maintaining them, not through an algorithm tutorial. Show a runtime move/rail reveal without changing the initial config. Briefly state that stage one is initial-only and persistence is not automatically enabled. Link to the adoption guide for computed/app integration and to the model/API reference for detailed grammar.
Contract Ledger Matrix
Discussion Criteria Mapping
Source criteria 1 and 4: a newcomer can discover, follow and run the basic stage-one declaration workflow without projection/resolver internals or private discussion history.
Acceptance Criteria
Validation
Use the shipped example's normal run path:
Open the documented example and the portal guide from the same checkout. The PR records the exact head, successful step-by-step run, rendered diagram/code/navigation checks and links followed. Run available source navigation/guide checks through their canonical owner; verify the actual script exists before naming its invocation. A generic unit-test pass is not tutorial usability evidence.
Dependencies and Decision Record
Native blocked-by dependencies: #18476 and #18477. Both APIs and the runnable example must exist before this tutorial can be accepted; drafting preparation may proceed independently.
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. No authority change; explanations link to the committed reference.
Out of Scope
API implementation, example refactoring, exhaustive configuration reference, broad adoption/migration guidance, persistence, multi-window or reactive-pane features.
Avoided Traps
No source-only proof of a runnable tutorial; no copy of the advanced demo presented as a beginner recipe; no generated output commits; no duplicated configuration catalog.
Related and Pickup
Related: #18474; #18476; #18477. unowned-rationale: Dedicated guide work available for peer self-selection after the host/example contracts; not implicitly owned by their implementers. Retrieval Hint: first standalone dock layout tutorial; panes/zones beginner run, discoverable navigation and portal render 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: no equivalent first-layout tutorial ticket. The existing adoption page is retained by a separate, deliberately different integration-guide leaf. MC problem query covered the manual seed/mount/resolver burden on first-time readers; no actionable conflicting ruling surfaced. Eight own assignments checked; general contributor onboarding is separate from this product tutorial. learn/tree.json, SEO PRIORITIES, the server-start command and the actual portal/example paths were checked from source. No new .mjs file or source directory is prescribed.