Guide audit: fix stale samples, phantom APIs, and the doc-pipeline gaps that let them rot

[Alexandre Zollinger Chohfi (azchohfi)]

Audit of the entire user guide for staleness, run as nine parallel sessions over disjoint slices, then integrated. Every slice's commits are preserved.

Why this was needed

The docs pipeline compiles code blocks written as ```csharp snippet="topic/id", but not bare ```csharp blocks, ```xml blocks, prose inside backticks, code inside string literals, or /// XML doc comments. At the start, 239 of 654 code blocks (37%) had no compile gate at all.

That is where the rot was. All 50 doc apps built clean on main the whole time — the snippet-backed code was fine. The damage was concentrated exactly where nothing looked.

Headline fixes

• The documented minimal .csproj did not work for anyone outside this repo. index.md.dt told readers to use <ProjectReference Include="..\Reactor\Reactor.csproj" />. Now a PackageReference pinned to the {{reactorVersion}} token. Verified by actually building it: the block was extracted from the template by regex, scaffolded outside the repo with all package sources cleared, and compiled. Six variants were tested to establish that <Platforms> is neither necessary nor sufficient — the load-bearing property is the RuntimeIdentifier auto-resolve line, without which a bare dotnet run (which the next sentence tells the reader to do) fails with the Windows App SDK architecture error.
• controls.md claimed to catalogue "every control" and listed 46 of ~93. Three whole categories were missing. Now 99 rows, plus a ControlCatalogCompletenessTests gate that parses the registration bootstrap and fails the build when a registered control has no catalog row.
• A documented SetWindowRgn recipe was a double-free. using var region = … then SetWindowRgn(hwnd, region.DangerousGetHandle(), true) — the system takes ownership on success, so the using freed GDI memory the compositor still read.
• charting documented .Margin(t, r, b, l) in CSS order; the real signature is Margin(left, top, right, bottom). Silently wrong margins, no error.
• UseEffect's reference page documented 1 of its 8 overloads. The generator keyed pages by short name, so overloads collided and all but one were silently dropped — including the Func<Action> cleanup form.
• Unresolvable <!-- ref:X --> markers were emitted verbatim into published Markdown, rendering as three invisible gaps mid-sentence in win2d-canvas.md.
• docs check-tier --topic fabricated errors for any topic whose app directory name differs from its template id (11 topics), reporting found 0 snippet refs for pages with five.
• ~40 phantom APIs removed across the guide: UseTheme(), RenderContext.Current, ElementDescription.Of, mur devtools serve, ProgressBar(...), VStackElement, A11Y_KEYBOARD_001 (a fabricated analyzer ID promising runtime coverage that doesn't exist), Optional.Of(...), Text(...) as an element factory, and more.

The rot ran backwards, into shipped source

Text(...), UseTheme(), Optional.Of(...) and three With*Transition modifiers were not only in the guide — they were in /// doc comments in src/, which ship in Reactor.xml as the IntelliSense every NuGet consumer sees. In several cases the templates were quoting the source comment; extending-reactor-controls.md.dt tracks Optional.cs's wording almost verbatim. Element.cs's implicit string operator calls Factories.TextBlock(text) while its own doc comment two lines above said Text("Hello").

Fixing only the guide would have let the source re-seed it.

The same phantoms had also reached contributor guidance: AGENTS.md and two pr-review skill dimensions documented RegisterV1BuiltInHandlers (deleted by spec 048) and a PoolableWireFlags type that never existed. Those misdirect every future contributor and agent session before work starts.

Durability, not just cleanup

Cleanup alone would rot again, so this adds gates:

• REACTOR_DOC_PHANTOM_001 — a docs-pipeline lint over templates, string literals and /// comments. Deliberately not a mur check rule: CheckCommand only invokes rules per parsed MSBuild diagnostic and prints ok when there are none, so a rule over surfaces that compile clean could never fire. Ships at Error severity, so mur docs compile --ci fails the Docs build on new rot; Warning was tried first and did not gate CI. The pre-existing backlog still passes via a per-(file, phantom) ceiling budget rather than a blanket suppression (new rot fails; fixing rot passes). The lint reads fenced blocks and inline code spans, since code formatting in prose reads as an endorsement, and matches phantom receivers (UI.Text()) as well as phantom members.
• AgentKitMarkdown_NamesNoPhantomApis — extends the same matcher over the plugins/ and skills/ markdown packed into the NuGet under agentkit/, which is what an AI assistant reads when writing Reactor code. It asserts it found files before reporting clean, so a broken sweep reddens instead of looking green.
• ControlCatalogCompletenessTests — makes the "every control" claim checkable.
• MinimalCsprojDocTests — asserts the landing-page csproj parses, references the package not a project path, uses the version token not a literal, and keeps the RuntimeIdentifier line.
• ~130 bare blocks promoted to compiled snippets, so CI enforces them permanently. Promotion paid for itself immediately — it surfaced defects nobody predicted, including ComponentElement having no .Set, a WithKey example that never compiled (CS0314), and a keys.FirstOrDefault() that compiled fine but silently yielded default(RowKey) instead of null.

Verification

• 53/53 doc apps build Release/x64 clean.
• Reactor.Tests: 13,334 passed, 0 failed. Reactor.DocPipeline.Tests: 379/379.
• docs/guide is idempotent — 190 generated files byte-identical on recompile.
• Every fix that could be mutation-tested was, against real historical defects rather than synthetic fixtures. The phantom lint's own author noted that had the fixture been written by hand as Text("Hello") instead of copied from the real pre-fix line — which uses escaped quotes inside a string literal — it would have passed and shipped blind.

Not verified locally: the full Release solution build cannot complete on an offline machine — three src/vs-reactor/** projects fail restore with NU1301. Confirmed environmental by running the identical command on unmodified main, which fails identically; this branch touches only src/vs-reactor/README.md. CI has network and will run that gate properly.

Known issues, deliberately not fixed

• The reference generator skips #ctor, so positional records lose their <param> docs entirely. MutationOptions.md has no Parameters section because OnError/OnSuccess documentation lives on the skipped constructor. Separate bug, larger than this change.
• REACTOR_DOC_REFGEN_001 rises 54 → 64, and that is correct. −12 from the cref fix, +22 newly surfaced: 18 previously-dropped overloads are now rendered and their prose cites out-of-category types, which degrade to inline code by design. Those crefs were "absent" only because the prose containing them was being deleted. A per-cref diff confirms no in-category cref regressed.
• The three Win2D <!-- ref: --> markers are removed, not bypassed. If Advanced element types become routable later, that capability would ship with nothing pointing at it; restoring the cross-references needs a deliberate edit to win2d-canvas.md.dt.
• 21 of 71 templates declare an app: directory that doesn't exist. Benign — 17 are 100% source: snippets, which need no doc app — but the metadata is inaccurate.

Reviewing this

The nine slices are independent and each merge commit is one slice, so reviewing per-merge works well. Two files have two authors (index.md.dt, text-and-media.md.dt) and both contributions were verified to survive.

One caveat worth knowing: docs/guide/** is generated. docs/guide/win2d-canvas.md conflicted at integration and was resolved by regenerating, not by picking hunks — merging generated output textually can produce a file matching no valid regeneration. UseFocusTrap.md also needed regeneration to pick up a compound effect no single branch produced: a doc-comment fix on one branch only becomes visible once the generator on another branch renders <example> blocks it previously dropped.

[Copilot]

Pull request overview

Copilot reviewed 256 out of 294 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/Reactor.Cli/Docs/PhantomSymbolLint.cs:124

• The new Text guard still misses valid single-argument phantom calls whose argument starts with an unlisted expression shape, such as Text(enabled ? "On" : "Off"), Text(prefix + value), or Text((string)value). Those examples remain uncompiled and pass this lint, so the durability gate can silently regress. Detect an unqualified Text invocation with exactly one top-level argument (using balanced-token scanning) instead of enumerating selected argument prefixes, and add regression cases for these shapes.

[Copilot]

Pull request overview

Copilot reviewed 255 out of 294 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

src/Reactor.Cli/Docs/PhantomSymbolLint.cs:517

• This prose discriminator also rejects valid C# expressions that use word operators. For example, both Text(value is null ? "" : value) and Text(value as string) contain adjacent identifier tokens, so HasAdjacentIdentifiers returns true and the phantom call silently passes. The matcher needs to recognize C# operator/token shapes rather than treating every adjacent identifier pair as prose.

[Copilot]

Pull request overview

Copilot reviewed 255 out of 294 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/Reactor.Cli/Docs/ReferenceGen/CrefSignature.cs:151

• A complete <typeparam> set is not necessarily in declaration order—XML documentation preserves the tags in authoring order. For a valid method declared <TKey, TValue> but documented with the TValue tag first, this branch emits Method<TValue, TKey> and substitutes those names into the wrong parameter slots and anchors. Either obtain ordinals from assembly metadata, or use placeholders for multi-parameter methods when order cannot be proven.

[Copilot]

Pull request overview

Copilot reviewed 255 out of 294 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

samples/apps/demo-script-tool/App/DemoScriptShell.cs:176

• This explanation no longer matches the implementation: cts.Token is captured synchronously before Task.Run, so the previous worker cannot still be reading that property. The remaining hazard is disposing the source while Task.Delay or the file write registers the captured token; likewise, the worker still indirectly uses the source through CancellationToken. Update the comment to describe that registration race.

[Copilot]

Pull request overview

Copilot reviewed 255 out of 294 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 255 out of 294 changed files in this pull request and generated no new comments.