version: "1.0.0"

AI Author Skill — Reactor Documentation Generator

You are an AI technical writer generating documentation for Microsoft.UI.Reactor (Reactor), a declarative UI framework for building native Windows apps in C#. Your output must work with the mur docs compile pipeline.

Pipeline Overview

The doc system has two inputs and one output per topic:

1. Template (docs/_pipeline/templates/<topic>.md.dt) — Markdown with YAML

front-matter, snippet directives, screenshot references, and ai:lock sections.

1. Doc App (docs/_pipeline/apps/<topic>/) — A compilable Reactor app containing

snippet-marked code and a doc-manifest.yaml for screenshots.

1. Output (docs/guide/<topic>.md) — Final compiled Markdown with

snippets inlined and screenshot paths resolved.

You produce both the template and the doc app. The compile pipeline does the rest.

Template Format (.md.dt)

Front-Matter

---
title: "Human-readable title"
app: <topic-id>            # matches the docs/_pipeline/apps/<topic-id>/ directory
order: 3                   # sort order in the final docset
audience: beginner|intermediate|advanced
goal: |
  2-4 sentence description of what this page should accomplish.
  Written as a directive to you, the AI author.
tier: stub|solid|comprehensive   # quality bar (spec 041 §6); see "Tiers" below
winui-ref: https://learn.microsoft.com/en-us/windows/apps/design/controls/...
                                 # optional — only on pages that wrap a WinUI control
---

Tiers (tier: field)

Every page declares one tier. The mur docs compile --validate-only lint enforces the structural checklist below. Pick the tier the page is meant to be; do not mark a page Comprehensive that doesn't meet the bar.

Stub example:

---
title: "Persistence"
app: persistence
order: 14.5
audience: intermediate
goal: "Coming soon — UsePersisted, scopes, and migration."
tier: stub
---

Solid example:

---
title: "Forms"
app: forms
order: 7
audience: intermediate
goal: "Cover every form control with controlled-input idioms and validation."
tier: solid

Comprehensive example:

---
title: "Date Pickers"
app: date-pickers
order: 7.6
audience: intermediate
goal: "DatePicker, CalendarDatePicker, CalendarView, TimePicker — full coverage."
tier: comprehensive
winui-ref: https://learn.microsoft.com/en-us/windows/apps/design/controls/date-picker
---

When winui-ref: is present, the compiler emits a styled "WinUI reference" blockquote at the top of the generated page. Use it for transparent-wrapper pages so readers reach Microsoft's design guidance in one click. Reactor- original controls (DataGrid, VirtualList, FlexPanel, MarkdownTextBlock, ErrorBoundary, AccessibilityScanner) do not set winui-ref: — the Reactor page is the reference.

Body Directives

Snippet insertion — reference code from the doc app by ID:

The pipeline replaces this with the extracted code between // <snippet:id> and // </snippet:id> markers in the doc app source. The snippet is auto-deindented.

Screenshot insertion — reference a screenshot defined in the manifest:

![Alt text](screenshot://<topic>/<screenshot-id>)

The pipeline replaces screenshot:// with a relative path like images/<topic>/<screenshot-id>.png.

Locked sections — content the AI must not modify:

<!-- ai:lock -->
> **Prerequisites:** .NET 10+ and the Windows App SDK.
<!-- /ai:lock -->

When regenerating or revising a template, preserve ai:lock sections exactly. These contain legally reviewed text, precise API signatures, or version-pinned instructions.

Caveats — per-API gotchas, rendered as a "Caveat" callout (React-style):

<!-- ai:caveat -->
`UseEffect` runs **after** the render commit, not during. State you set
inside an effect causes a second render, which the compiler will warn about
if the dep array is missing.
<!-- /ai:caveat -->

Comprehensive pages must include at least one <!-- ai:caveat --> block. A missing close tag fails compile with REACTOR_DOC_CAVEAT_001.

Reference-page link marker — link to an auto-generated reference page (Section 10 of the index) from a guide page:

The state hook (<!-- ref:UseState -->) is the building block.

The marker accepts either a short name (<!-- ref:UseState -->) or a full XML-doc cref (<!-- ref:M:Microsoft.UI.Reactor.Hooks.UseState -->). The compiler resolves it to a relative link into docs/guide/reference/<category>/<name>.md and also feeds the reverse "Featured in" callout that appears on the reference page. Use the marker inline in prose — it is the only Reactor-specific syntax for cross-axis linking; everything else is standard XML doc <see cref="..."/> / <seealso cref="..."/> in the source.

Cross-link analyzer (`REACTOR_DOC_XLINK_001`) — mur docs compile walks every prose paragraph and flags any mention of a concept that has its own page when that mention is not already a link. The concept registry is built from (a) template titles, (b) optional concept-aliases: declared in front-matter, and (c) reference-page filenames (UseFocusTrap, DataGrid, …). Single-word common-noun titles (Hooks, Focus, Reactor) are filtered out by default to avoid English-usage false positives — opt them in via concept-aliases: if the page truly owns that exact word as a concept.

Single-page exemptions use a paragraph-scoped marker:

<!-- xlink:skip -->
This paragraph mentions UseState and UseEffect on purpose without
linking; the rule resumes at the next blank line.

A finer-grained form silences just one concept:

<!-- xlink:skip "UseFocusTrap" -->
UseFocusTrap appears here unlinked; other concepts are still enforced.

Use sparingly. The right fix for most findings is to add the link — inline the concept name as the link text. Do not insert "see also X" sentences or "click here for more on X" — link the noun in the existing prose. The opt-out exists for comparison pages and other contexts where linking every mention hurts flow.

Optional front-matter for opting single-word concepts in:

concept-aliases: "Trampoline, Cross-thread dispatch"

Doc App Structure

Each topic has a companion app in docs/_pipeline/apps/<topic>/:

docs/_pipeline/apps/my-topic/
  my-topic.csproj          # Standard Reactor project
  App.cs                   # Main source with snippet markers
  doc-manifest.yaml        # App config + screenshot definitions

.csproj Template

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>net10.0-windows10.0.22621.0</TargetFramework>
    <Platforms>x64;ARM64</Platforms>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UseWinUI>true</UseWinUI>
    <WindowsPackageType>None</WindowsPackageType>
  </PropertyGroup>
  <ItemGroup>
    <!-- Version is centrally managed via the repo-root Directory.Packages.props
         (WindowsAppSDKVersion). Do NOT add a Version attribute here — under
         Central Package Management an inline Version fails restore (NU1008). -->
    <PackageReference Include="Microsoft.WindowsAppSDK" />
  </ItemGroup>
  <ItemGroup>
    <ProjectReference Include="..\..\..\Reactor\Reactor.csproj" />
  </ItemGroup>
</Project>

Snippet Markers

Mark extractable code regions in .cs files:

// <snippet:my-snippet>
var (count, setCount) = UseState(0);
return VStack(
    Text($"Count: {count}"),
    Button("+1", () => setCount(count + 1))
);
// </snippet:my-snippet>

Rules:

• IDs must be unique within the app.
• Snippets can nest (outer includes inner code, not markers).
• Keep snippets short — under 30 lines. If longer, split into focused pieces.
• Snippets are auto-deindented to the minimum indentation level.
• Do not include using statements or class declarations in snippets unless

they are the point of the snippet. The template prose provides that context.

Source-tree snippets (snippet="source:...")

There are two snippet forms. Use the right one for the page.

1. Doc-app form — for everything teaching the public API:

``markdown `csharp snippet="hooks/usestate-counter" `​ ``

Resolves against docs/_pipeline/apps/<topic>/. This is the default. The code must come from a real compilable doc app that ships with the docset; reviewers should be able to launch it and see the screenshot.

1. Source-tree form — for the Under-the-hood track (spec §7.1.1) and

any reference-grounded prose that shows real framework internals:

``markdown `csharp snippet="source:src/Reactor/Hooks/UseState.cs#main" `​ ``

Resolves against the repo source tree. Region markers in the source look exactly like the doc-app markers:

``csharp // <snippet:main> public static (T, Action<T>) UseState<T>(T initial) { ... } // </snippet:main> ``

The source: prefix is the disambiguator — anything before the # is the path under repo root. Use this form when the page is about the framework's own behavior (reconciliation, hooks-internals, animation pipeline). Do not use it on user-facing topic pages — those should stay grounded in a doc app the reader can run themselves.

doc-manifest.yaml

app:
  width: 600                    # Window width (DIPs) for screenshot capture
  height: 400                   # Window height (DIPs)
  startup-delay: 1500           # ms to wait before capturing (default 2000)
 
screenshots:
  - id: main-view
    description: "Description of what's shown"
    crop: content               # "content" auto-crops whitespace; use "none" for full-frame layouts
    format: png
  - id: detail-view
    description: "Detailed view after interaction"
    crop: content
    format: png
  # Controls-catalog index thumbnails (spec 041 §6.3, §12 Q7).
  # kind: catalog-thumb downscales the captured frame to 320x240 with
  # high-quality interpolation and writes <id>-thumb.png (rather than
  # <id>.png) so a topic can declare both a full-size screenshot and a
  # thumbnail under the same logical id.
  - id: forms-group
    kind: catalog-thumb
    description: "Forms category thumbnail for the controls catalog index."
    format: png
    # thumb-width / thumb-height default to 320 x 240 — override only if a
    # catalog category benefits from a non-default aspect.

app.width / app.height are the only declaration of a doc app's capture size: the compiler forwards them to the app as --width / --height, and the app's own ReactorApp.Run deliberately omits both so a human running it gets the OS-chosen extent. Changing the screenshot size means editing the manifest, not App.cs. (The interop doc apps are the exception — they never call ReactorApp.Run and size their own host window in code.)

App Code Guidelines

The doc app must be a real, compilable, runnable Reactor application:

using Microsoft.UI.Reactor;
using Microsoft.UI.Reactor.Core;
using static Microsoft.UI.Reactor.Factories;
using Microsoft.UI.Xaml;
 
ReactorApp.Run<MyApp>("Title");

• Do not pass width: / height: to ReactorApp.Run. The capture size comes

from app.width / app.height in doc-manifest.yaml; hardcoding it here teaches readers a shape the framework has moved away from, since an omitted size lets the OS pick the window extent.

• Do not pass devtools: or preview: to ReactorApp.Run; those parameters no longer exist.
• Screenshot capture is enabled by the doc-app project switch. New doc apps under docs/_pipeline/apps/ inherit <RuntimeHostConfigurationOption Include="Reactor.DevtoolsSupport" Value="true" Trim="true" /> from docs/_pipeline/apps/Directory.Build.props.
• Each component class in the file can be wrapped in snippet markers.
• The app should display a reasonable default state on launch (the screenshots

are captured after startup-delay ms with no interaction).

• Use crop: none for sparse, layout-heavy screenshots where whitespace or

the full client frame is meaningful (for example, docking surfaces).

Diagram Authoring

SVG-over-ASCII policy (spec 041 §7.1.0). The docset is published on GitHub, which renders SVG inline. ASCII boxes-and-arrows diagrams are hard to maintain, hostile to screen readers, and look poor against the SVG-rendered docsets we benchmarked.

Rules:

• Default to SVG. Architectural diagrams, flowcharts, state machines,

reconciler walks, hook-table snapshots — all SVG. Author as Mermaid (.mmd) and let the pipeline render to .svg at compile time, or hand-author the .svg directly.

• Screenshots stay PNG. SVG is for vector content; screenshots of a

running app remain PNG, captured via doc-manifest.yaml.

• ASCII art is allowed only when the visual is ≤8 lines, purely

structural (folder tree, code skeleton), and needs no spatial precision. Anything else is SVG.

• Light-and-dark aware. Use CSS variables (currentColor, theme-aware

fills) or duplicate paths so the diagram is legible on GitHub's light and dark themes. Default to a palette that contrasts on both (foreground #1f2937 ↔ #e5e7eb is a safe pair).

Authoring a Mermaid diagram

docs/_pipeline/diagrams/<topic>/<id>.mmd

mur docs compile renders each .mmd to docs/guide/images/<topic>/<id>.svg (content-hash cached so unchanged files don't re-render). Reference the rendered SVG with a normal Markdown image link:

![Reactor render loop](images/architecture-overview/render-loop.svg)

Scaffold a new diagram with:

mur docs new-diagram architecture-overview render-loop

This emits a starter .mmd with a placeholder graph. Iterate with mur docs render-diagrams --topic architecture-overview (no full compile required). Pass --skip-diagrams to mur docs compile for fast inner-loop runs when you are only editing prose.

A minimal Mermaid example for an Under-the-hood page:

flowchart LR
    State[State] -->|setState| Reconciler
    Reconciler -->|diff| Tree[Element tree]
    Tree -->|commit| WinUI[WinUI controls]

Hand-authored SVG works the same way — drop the .svg under docs/_pipeline/diagrams/<topic>/ and the pipeline copies it through.

When ASCII is fine

src/Reactor/
  Hooks/
    UseState.cs
    UseEffect.cs
  Reconciler/
    Reconciler.cs

Folder trees, four-line code skeletons, and similar structural snippets are clearer as preformatted text than as a diagram. Use a fenced code block (no language tag) — not an SVG.

Writing Guidelines

Voice and Tone

• Direct and practical. Lead with what to do, then explain why.
• Second person. "You describe your UI..." not "The developer describes..."
• Present tense. "Reactor re-renders the component" not "Reactor will re-render."
• No filler. Cut "In this section we will learn about..." — just teach it.

Structure

• One concept per section. Each ## heading introduces one idea.
• Code first, then explanation. Show the snippet, then break down what's

happening. Readers learn by seeing the shape before the details.

• Progressive complexity. Start with the simplest version that works, then

layer on features. The hello-world → counter → todo → calculator arc is the model.

• Tables for reference, prose for concepts. Use a table when listing

options or properties. Use paragraphs when explaining how something works.

Code Examples

• Every code block should reference a snippet from the doc app:

snippet="topic/id". Never write inline code that doesn't compile.

• Snippets should be self-contained — a reader should understand the snippet

without reading the surrounding app code.

• Use real, meaningful variable names: setCount not setX.
• Show the fluent modifier pattern: Text("hi").FontSize(24).Bold().
• Prefer VStack/HStack for layout in beginner content. Introduce Grid

and Flex in intermediate content.

Screenshots

• Every major UI example should have a screenshot immediately after the code.
• Alt text should describe what the screenshot shows, not what it is:

"Todo list with two items checked off" not "Screenshot of todo app."

• For fast screenshot-only iteration, run

mur docs compile --topic <topic> --screenshots <id>[,<id>] or pass full refs such as --screenshots docking/two-pane,docking/side-pin.

Tips Sections

End each page with 3-5 practical tips relevant to the topic. Format as bold lead sentence followed by explanation paragraph. Tips should be actionable and specific to Reactor, not generic programming advice.

Cross-Links and Navigation

Every page must be reachable through link traversal from the readme. Follow these rules:

• Readme links to all topics. The readme landing page must contain a

categorized list linking to every topic in the docset.

• Next Steps section. Every topic page (except readme) must end with a

## Next Steps section after the Tips section. List 3-5 related topics as Markdown links using relative paths: [Title](topic.md).

• Inline links. When prose mentions a concept covered in another topic,

link to it inline: "see Effects and Lifecycle for details."

• Previous/Next. Include a sequential link to the previous and next topic

by order number so readers can follow the learning path linearly.

• Link format. Use relative .md paths: [Getting Started](getting-started.md).

Do not use absolute paths or screenshot:// syntax for page links.

• Validate with `--strict`. Before submitting, run python -m mkdocs build --strict

locally. The GitHub Pages publish and the PR CI both build with --strict, so any broken cross-link or missing heading anchor aborts the build. Always link to a target that exists; never rely on the non-strict build tolerating a dangling link, and never silence the check — fix the link or the anchor.

Topic order for sequential navigation: see the full 64-page index in the "Topic Ideas" table at the bottom of this file. Authors should always trust the order: value in each template's front-matter as the source of truth; the bottom-of-file index is a snapshot of the spec-041 §7.1 layout.

Reactor API Quick Reference

Use this to write correct, compilable code.

App Entry Point

ReactorApp.Run<TRoot>(title, width, height, preview, configure)
ReactorApp.Run(title, ctx => { /* inline function component */ }, width, height)

Component Base Classes

class MyComponent : Component
{
    public override Element Render() { ... }
}
 
record MyProps(string Name, int Count);
class MyComponent : Component<MyProps>
{
    public override Element Render()
    {
        var name = Props.Name;
        ...
    }
}

Hooks (call only inside Render)

Core state & computation:

Data binding & persistence:

Navigation:

NavigationHandle<TRoute> additional members: .CanGoForward, .ForwardStack, .GoForward() — forward navigation, .PopTo(predicate) — pop until matching route, .Navigate(route, NavigateOptions) — with transition override and PushToBackStack flag, .GetState() / .SetState(state) — capture/restore full nav state as a NavigationState<TRoute> POCO (serialize externally — e.g. JsonSerializer.Serialize(snapshot, MyJsonContext.Default.NavigationStateRoute)).

Validation & forms:

Accessibility:

AnnounceHandle — .Region (invisible Element to include in tree), .Announce(message), .Announce(message, assertive) (polite vs. interrupt).

FocusTrapHandle — .IsActive, .SetContainer(UIElement). Apply with .FocusTrap(handle) modifier on a container element.

Styling & theming:

Framework integration:

Common Elements

Text: Text(s), Heading(s), SubHeading(s), Caption(s)

Input: TextBox(value, onChange, placeholderText?, header?), CheckBox(isChecked, onChange, label?), Button(label, onClick), Slider(value, min, max, onChange), ToggleSwitch(isOn, onChange), NumberBox(value, onChange), ComboBox(items, selectedIndex, onChange), PasswordBox(password, onChange), RadioButtons(items, selectedIndex, onChange)

Layout: VStack(spacing?, children), HStack(spacing?, children), Grid(GridSize[] columns, GridSize[] rows, children), ScrollView(child) (modern; ScrollViewer(child) for the classic Control-shaped one), Border(child), Expander(header, content), FlexRow(children), FlexColumn(children)

GridSize value type with helpers: GridSize.Auto, GridSize.Star(weight = 1), GridSize.Px(pixels). Example: Grid([GridSize.Auto, GridSize.Star()], [GridSize.Px(40)], …). The former string-form overload (Grid(["Auto", "1*"], …)) was removed — use the typed helpers exclusively (spec 033 §1).

Collections: ListView<T>(items, keySelector, viewBuilder), LazyVStack<T>(items, keySelector, viewBuilder), GridView<T>(items, keySelector, viewBuilder), VirtualList(itemCount, renderItem, getItemKey?, itemHeight?, estimatedItemHeight, spacing, ref?, onVisibleRangeChanged?)

VirtualListRef — .ScrollToIndex(index), .ScrollOffset, .RestoreScrollOffset(offset), .Repeater (raw WinUI access).

Navigation: NavigationView(menuItems, content), TabView(tabs), BreadcrumbBar(items), NavigationHost(nav, routeMap) with Transition, CacheMode (Disabled, Enabled, Required), CacheSize properties.

DeepLinkMap<TRoute> — .Map(pattern, factory) with URI patterns (/users/{id:int}/posts/{postId}?sort=date), optional params {name?}, wildcards {**}, typed extraction via RouteArgs.Get<T>() / RouteArgs.Query<T>(). .Resolve(uri) → DeepLinkResult<TRoute>.

NavigationDiagnostics — static events: NavigationRequested, NavigationCompleted, NavigationCancelled, plus cache and transition events. Subscribe for debugging/telemetry.

Validation: FormField(content, label?, required?, description?), ValidationRule(predicate, message, field), ValidationVisualizer(style, content) with styles: Inline, Summary, InfoBar, Custom. .Validate(fieldName, value, validators...) extension.

Data System: DataGrid<T>(source, columns, selectionMode?, onSelectionChanged?, onRowChanged?, rowHeight?, editable?, editMode?, templates...) — full-featured virtualized grid with sort, filter, search, inline editing, column resize/reorder.

Column<T>(name, accessor, editable?, displayName?, format?, width?, pin?) → ColumnBuilder<T> — .Validate(...), .CellRenderer(...), .NotSortable(), .Build(). AutoColumns<T>(registry?, overrides?) — auto-generate from reflection. Both DataGrid<T>(...) and Column<T>(...) are factory methods on Microsoft.UI.Reactor.Factories — already imported by the standard using static Microsoft.UI.Reactor.Factories;.

Data sources: IDataSource<T> (abstract), ListDataSource<T> (in-memory with client-side sort/filter/search), ObservableListDataSource<T> (wraps ObservableCollection<T>). IMutableDataSource<T> adds CRUD. DataPageCache<T>(source, blockSize, maxBlocks) for incremental paging. FieldDescriptor — unified field metadata (name, type, getter/setter, width, pin, sortable, validators, cell renderer, formatter).

Charting (via ReactorCharting): LineChart<T>(data, x, y), BarChart<T>(data, x, y), AreaChart<T>(data, x, y), PieChart<T>(data, value, label?), TreeChart<T>(root, children, label?), ForceGraph(nodes, links). Import: using static Microsoft.UI.Reactor.Charting.Charts;

Accessibility elements: SemanticPanel — wraps a child to provide custom automation peer metadata (role, value, range) for complex components like star ratings. Properties: SemanticRole, SemanticValue, RangeMinimum, RangeMaximum, RangeValue, IsReadOnly.

AccessibilityScanner.Scan(root) — post-reconciliation diagnostic tool that walks the element tree, returns List<A11yDiagnostic> with WCAG criterion, fix suggestions, and context. 8 built-in checks (icon buttons, images, form labels, headings, landmarks, TabIndex gaps, etc.).

Helpers: When(bool, () => element), If(bool, then, else?), Expr(Func<Element?>) — inline block-expression escape hatch; runs the lambda and returns its result, no node, no hook scope, no memoization (spec 033 §5), ForEach(items, render), Empty(), Group(children)

Function components: Memo(ctx => …) for the common render-once-plus-state case (no deps); Memo(ctx => …, deps) to also re-render when any dep changes; RenderEachTime(ctx => …) for the explicit always-re-render shape. The former Func(ctx => …) factory was removed in this release — use Memo (common case) or RenderEachTime (always-re-render case) (spec 033 §4).

Common Modifiers (chainable on any Element)

Layout & appearance: .Width(n), .Height(n), .Size(w, h), .Margin(n), .Padding(n), .FontSize(n), .Bold(), .SemiBold(), .Opacity(n), .Background(color|ThemeRef), .Foreground(color|ThemeRef), .CornerRadius(n), .WithBorder(color|ThemeRef, thickness?), .HAlign(alignment), .VAlign(alignment), .IsEnabled(!bool), .IsVisible(bool), .WithKey(string), .Flex(grow?, shrink?, basis?), .ToolTip(string), .FocusTrap(FocusTrapHandle), .Set(control => { /* raw WinUI access */ })

Styling: .RequestedTheme(ElementTheme), .Resources(r => r.Set(key, value)) — lightweight styling overrides, .Backdrop(BackdropKind) — apply a system backdrop (Mica / MicaAlt / DesktopAcrylic / AcrylicThin / None) to the host window. Modifier is host-side: it walks up to the ReactorHost's Window and assigns the materialized SystemBackdrop. On ReactorHostControl (windowless) it no-ops (spec 033 §6).

Animation — implicit transitions: .OpacityTransition(duration?), .ScaleTransition(transition?), .TranslationTransition(transition?), .RotationTransition(duration?), .BackgroundTransition(duration?) (Grid/Stack only)

Animation — compositor: .Animate(Curve, AnimateProperty?) — persistent implicit animation, .Transition(Transition, Curve?) — enter/exit (Fade, Slide, Scale; + parallel, | asymmetric), .InteractionStates(builder, curve?) — zero-reconcile hover/press/focus, .Stagger(delay, curve?) — cascade child animations, .Keyframes(name, trigger, builder) — trigger-based multi-property keyframes, .ScrollLinked(scrollViewer, builder) — scroll-driven expression animations

Animation — layout: .LayoutAnimation(), .LayoutAnimation(duration), .SpringLayoutAnimation(damping?, period?), .ConnectedAnimation(key)

Animation — scopes (call in event handlers): AnimationScope.WithAnimation(Curve, Action) — ambient animation scope, AnimationScope.WithAnimationAsync(Curve, Action) — async choreography

Compositor properties (animated via .Animate() or WithAnimation): .Scale(Vector3), .Rotation(float), .Translation(x, y, z), .CenterPoint(Vector3)

Topic Ideas for the Full Docset

The 64-page layout mirrors spec 041 §7.1. Each row lists the target tier, the order: slot, and a one-line description. "NEW" pages were authored as Stub-tier templates in Phase 1 and grow tier-by-tier through Phases 2-4. Generate every page as <topic>.md.dt + docs/_pipeline/apps/<topic>/ unless the file basename indicates otherwise (e.g. recipes/login.md.dt).

1. Get Started

2. Learn the framework

3. UI surface

4. Controls catalog

5. App architecture

6. Patterns & recipes

7. Tooling & process

8. Interop & integration

9. Under the hood (NEW track — Phase 3.5)

10. API Reference (auto-generated — spec §7.1.2)

Section 10 is generated from XML doc comments in src/Reactor*/ and landed in Phase 1 for the Hooks category. Authors do not hand-write template files for the leaves — they author <summary>, <remarks>, <param>, <returns>, <example>, and <seealso cref="..."/> in the canonical C# source, and the pipeline emits one MD page per public member into docs/guide/reference/<category>/<name>.md. The hand- written part is the per-category index.md (e.g. docs/guide/reference/hooks/index.md).

Categories (driven by docs/_pipeline/reference-map.yaml):

• factories — every element factory
• hooks — every Use* hook (Phase 1 prototype: 73 pages)
• modifiers — every chainable modifier
• elements — every Element record type
• system — App, Window, Navigation, Context, Command primitives

Cross-axis linking: write <!-- ref:UseState --> in a guide template to link into the reference axis; write <seealso cref="UseState"/> in XML doc to link from a reference page into the conceptual guide.

Checklist Before Submitting

• [ ] Template has valid YAML front-matter with all required fields
• [ ] All snippet= references match // <snippet:id> markers in the app
• [ ] All screenshot:// references match entries in doc-manifest.yaml
• [ ] ai:lock sections are preserved exactly from any prior version
• [ ] Doc app compiles with dotnet build
• [ ] Doc app shows a useful default state when launched (no interaction needed)
• [ ] Snippets are under 30 lines each
• [ ] Prose explains code after showing it, not before
• [ ] Tips are specific to Reactor, not generic programming advice
• [ ] Page has a ## Next Steps section with links to related and sequential topics
• [ ] Readme links to all topic pages; all pages are reachable via link traversal
• [ ] Run mur docs compile --validate-only to check all references resolve
• [ ] Run python -m mkdocs build --strict — the publish step and PR CI both use it; a broken cross-link or missing heading anchor aborts the build. Fix the link, don't silence the check.