diff --git a/.claude/docs/adr/0009-tutorial-code-from-examples-via-region-includes.md b/.claude/docs/adr/0009-tutorial-code-from-examples-via-region-includes.md
index 4d414677..c7e3988b 100644
--- a/.claude/docs/adr/0009-tutorial-code-from-examples-via-region-includes.md
+++ b/.claude/docs/adr/0009-tutorial-code-from-examples-via-region-includes.md
@@ -1,3 +1,3 @@
-# Tutorial code is single-sourced from `examples/` via docfx region includes; template pack strips the markers
+# Tutorial code is single-sourced from `examples/` via `#region docs:` markers, synced into docs by a snippet pipeline
 
-Tutorial markdown contains no inline C# snippets for load-bearing code; instead it embeds `[!code-csharp[](<path>#docs:<name>)]` includes that pull `#region docs:<name> ... #endregion` ranges out of the canonical example projects under `examples/starter/`. The example files are the source of truth — touching the example changes the tutorial mechanically, and touching the tutorial requires touching the example, so the two cannot drift. The `docs:` prefix is the contract: only regions named `docs:*` are doc-relevant, and the example's own `#region`s (e.g., `#region Constructors`) are left alone. Because `examples/starter/*` projects also ship as `dotnet new` templates, a private nx subtarget `_strip-doc-regions` runs before pack and deletes every `^\s*#(region|endregion)\s+docs:.*$` line into a `pack-staging/` dir; the pack target consumes the staging dir, not the source tree, so contributors and the docs build see the real example with regions intact while template instantiators get a clean copy. The rejected alternatives were (A) inline ```csharp blocks compiled in isolation by a CI extractor — caught syntactic drift but not semantic mismatch against `examples/`, and required per-snippet scaffolding — and (C) a hybrid convention where small blocks stay inline and only "load-bearing" code uses includes; the line between the two was fuzzy enough that we expect convention drift, so we picked the all-includes rule for tutorials specifically. Guides and Explanation pages still allow inline blocks because their snippets are illustrative-of-a-concept rather than prescriptive-code-the-reader-will-copy. See [ADR-0008](./0008-documentation-honesty-three-error-phases.md) for the broader honesty framework this fits into.
+Tutorial markdown contains no hand-written load-bearing C#; the canonical example projects under `examples/starter/` own that code and mark the doc-relevant ranges with `#region docs:<label> … #endregion`. The `docs:` prefix is the contract — it distinguishes a doc-region from an ordinary `#region Constructors`, it is what the template-pack strip step removes, and the `<label>` is globally unique and identical on both sides of the pipeline. Two NX targets move the code across a clean `dist` boundary: `examples:generate-snippets` extracts each `docs:` region into `dist/examples/docs/snippets/docs-<label>.md` as a dedented fenced code block (the `examples` project owns the source language, so it picks the `csharp`/`python` fence), and `docs:sync-snippets` — which `dependsOn` it — splices each snippet into a managed marker block in `docs/**/*.md`, expanding an author's one-line sentinel `<!-- flowthru:snippet docs:<label> -->` in place on first run and refreshing the body between markers thereafter, the same managed-block mechanism `scripts/update-example-readmes.mjs` uses for README mermaid/filetree blocks. The source of truth is the C# source; the two projects communicate only through the `dist` artifact (a clear chain of possession), never by reaching into each other's trees. Honesty is enforced three ways, all per [ADR-0008](./0008-documentation-honesty-three-error-phases.md): `sync-snippets` hard-fails atomically — writing nothing — if a sentinel references a label absent from `dist` (a doc pointing at code that no longer exists) or if a `dist` label is never referenced by any sentinel (an orphan doc-region marking code that documents nothing), and CI additionally runs `git diff --exit-code docs/` to catch C# edits that were never re-synced. None of this touches the example build or run: `#region` is a compile-time no-op, so the examples build and run unchanged whether markers are present, orphaned, or stripped. Because `examples/starter/*` also ship as `dotnet new` templates, a strip step deletes every `^\s*#(region|endregion)\s+docs:.*$` line from the packaged artifact so template instantiators never see doc-only markers. The rejected alternative was docfx's `[!code-csharp[](<path>#region)]` include directive: docfx is present in this repo but only for *metadata* — API-reference extraction into `docs/reference/src/` via `scripts/docfx-metadata.sh` — while the site itself is built by Starlight/Astro, which does not process docfx include directives, so adopting that syntax would have shipped literal unresolved `[!code-csharp[]` text to the rendered site. We kept docfx's spirit (single-source tutorial code from `examples/`) but built our own resolver, and deliberately chose a path-free, refactor-resilient token (`docs:<label>`, the same string in the C# marker and the markdown sentinel) over docfx's file-relative `[!code]` path, so moving a snippet's source file between locations never breaks its reference.
diff --git a/.claude/docs/adr/0018-docs-review-provenance-frontmatter.md b/.claude/docs/adr/0018-docs-review-provenance-frontmatter.md
new file mode 100644
index 00000000..a4dc81ec
--- /dev/null
+++ b/.claude/docs/adr/0018-docs-review-provenance-frontmatter.md
@@ -0,0 +1,3 @@
+# Docs frontmatter carries a `review` provenance field; `draft` is a pre-flight warning
+
+Every page under `docs/{tutorials,guides,explanation}/` may declare a `review` frontmatter field with the enum value `draft` or `reviewed`. The field does *not* record who typed the characters — AI-assisted drafting is now a common and legitimate origin — it records whether a human has refined and signed off on the content. An AI draft a maintainer has gone through is `reviewed` and trustworthy; a draft nobody re-read is not, regardless of who wrote it. The lifecycle is a two-state loop driven entirely by humans: a page is `draft` on initial creation (the boilerplate default), it is **always manually** promoted to `reviewed` — promotion is never automated, because the whole point is to assert a human looked — and any substantive update flips it back to `draft`, because reviewed-ness attaches to specific content and stale approval is worse than none. **Absent is treated as `draft`**: the field fails toward "needs review" so a forgotten field can never masquerade as reviewed, which also means existing pages read as `draft` automatically and the rollout requires *zero* backfill — a maintainer flips each page to `reviewed` as they sweep it. `draft` status is a **pre-flight warning, not a design-time gate** under [ADR-0008](./0008-documentation-honesty-three-error-phases.md): draft docs still ship, they surface in the same non-blocking warnings list as the terminology lint and through the same GitHub step-summary surface — a single warning harness, not a second parallel one. The field is registered as an optional enum (default `draft`) in the Starlight `docsSchema` extension alongside the required `description`, so it is first-class in the content layer and a future Starlight component could render a "needs review" banner from it; the warning meta-test that emits the draft list reads raw frontmatter, parallel to how `lint-docs.mjs` validates the hard `title`/`description` contract before the Astro build. The meta-test itself is deferred — this ADR commits to the field and its semantics so content authored under it is correct from birth, and the emitter lands with the terminology-lint warning surface. Rejected alternatives were (A) a boolean `reviewed` — equivalent in expressiveness to the two-value enum but it framed the question as a static flag rather than a lifecycle, and an enum leaves room to name a third state later without a type change; (B) a `review: { state, by, at }` object — the audit trail is appealing but the per-page ceremony invites rot, and `by`/`at` duplicate what `git blame` already records authoritatively; and (C) an authorship-origin framing (`authored-by: ai | human`) — rejected outright because origin is not the risk, un-reviewed-ness is, so recording origin would gate on the wrong signal.
diff --git a/.github/workflows/docs-external-links.yml b/.github/workflows/docs-external-links.yml
new file mode 100644
index 00000000..286506e5
--- /dev/null
+++ b/.github/workflows/docs-external-links.yml
@@ -0,0 +1,64 @@
+name: Docs External Links
+
+# Out-of-band external link checking. External link rot is third-party reality
+# changing, not a Flowthru contract violation, so it must NOT gate PRs — it is
+# surfaced on a schedule and filed as an issue for human triage.
+#
+# Internal links are already gated at site-build time by Starlight; in-source
+# snippet references are gated by docs:sync-snippets. This workflow only checks
+# external (http/https) links under docs/.
+
+on:
+  schedule:
+    # Mondays 09:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+concurrency:
+  group: docs-external-links
+  cancel-in-progress: false
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check external links
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # Scope to external links only; internal/relative links are gated at
+          # build time. `--no-progress` keeps the log readable in CI.
+          args: >-
+            --no-progress
+            --scheme https --scheme http
+            --exclude-loopback
+            "docs/**/*.md"
+          output: ./lychee-report.md
+          fail: false
+
+      - name: File or update broken-links issue
+        if: steps.lychee.outputs.exit_code != 0
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          # Dedupe: append to the existing open issue if one is already filed,
+          # otherwise create a fresh one. Keeps the tracker from accumulating a
+          # duplicate every Monday.
+          existing=$(gh issue list --state open --label documentation \
+            --search 'Broken external links in docs/ in:title' \
+            --json number --jq '.[0].number // empty')
+          if [ -n "$existing" ]; then
+            gh issue comment "$existing" --body-file lychee-report.md
+          else
+            gh issue create \
+              --title 'Broken external links in docs/' \
+              --body-file lychee-report.md \
+              --label documentation --label needs-triage
+          fi
diff --git a/docs/diagnostics/site-build-honesty.md b/docs/diagnostics/site-build-honesty.md
new file mode 100644
index 00000000..8177f6ce
--- /dev/null
+++ b/docs/diagnostics/site-build-honesty.md
@@ -0,0 +1,46 @@
+# site:build honesty verification
+
+Verification record for whether the docs build fails on the design-time /
+pre-flight documentation errors the honesty model requires it to catch.
+`docs/diagnostics/` is repo-internal — not ingested or served.
+
+## Audit: no masking flags
+
+`.github/workflows/website-deploy.yml` runs `pnpm nx run site:build` with no
+`continue-on-error`, no `--ignore-errors`, no `--no-fail-on-error`.
+`src/website/project.json`'s `build` target runs `astro build` plainly.
+There is nothing suppressing a build failure.
+
+## Broken in-source snippet reference → GATED ✓
+
+A `<!-- flowthru:snippet docs:<label> -->` sentinel referencing a label with no
+extracted snippet causes `docs:sync-snippets` to exit non-zero (verified:
+"references with no snippet in dist … Nothing written"). `docs-checks.yml` runs
+`docs:sync-snippets`, so this fails the PR check. The reverse (an orphan
+`#region docs:` nothing references) is gated the same way.
+
+## Broken internal markdown link → NOW GATED ✓ (was a real gap)
+
+The ticket assumed "Starlight errors on broken internal links by default." It
+did NOT — an early smoke (`[x](./does-not-exist.md)`) built clean, exit 0,
+silently. Closed by adding the `starlight-links-validator` plugin to
+`src/website/astro.config.mjs` (`errorOnRelativeLinks: false`, so relative
+links — the repo convention — are allowed but still resolved).
+
+Proven the hard way: on its first run the validator failed the build with
+**5 real pre-existing broken links** in `index.mdx` (root-absolute hrefs that
+double-encoded the `/flowthru` base — never shipped only because `index.mdx`
+was untracked). Fixing them to relative links returned the build to green:
+
+```
+pnpm nx run site:build --skip-nx-cache
+# with broken links:  "✗ Found 5 invalid links", exit 1
+# after fixing:       "✓ All internal links are valid", "[build] Complete!", exit 0
+```
+
+PR-time gating: `pr-tests.yml` runs `nx affected -t build`, which includes
+`site:build` whenever docs change (site `implicitDependencies` docs), so a
+broken internal link now fails the PR check — not just the release deploy.
+
+External link rot remains out-of-band (scheduled `docs-external-links.yml`),
+per the honesty model.
diff --git a/docs/explanation/advanced/core-architecture.md b/docs/explanation/advanced/core-architecture.md
index 9c2e7773..b22ba03e 100644
--- a/docs/explanation/advanced/core-architecture.md
+++ b/docs/explanation/advanced/core-architecture.md
@@ -3,7 +3,7 @@ title: Core Architecture for Contributors
 description: How Flowthru's functional core is shaped, how extensions hook into it, and why Flow and Catalog Developers never see any of it. Written for prospective Core Contributors who know FP basics (closure, currying, monads, side effects) but haven't yet seen those primitives organised into a working framework.
 ---
 
-This document explains the *why* behind Flowthru's core. It is the architectural companion to [CONTRIBUTING.md](../../../CONTRIBUTING.md) — that file tells you the rules; this file tells you why those rules produce the shape they do.
+This document explains the *why* behind Flowthru's core. It is the architectural companion to [CONTRIBUTING.md](/CONTRIBUTING.md) — that file tells you the rules; this file tells you why those rules produce the shape they do.
 
 The intended reader knows FP basics (closures, currying, monads as `Bind`-able effect values, side effects as a thing to push to the edges) but hasn't necessarily seen those primitives composed into a framework before. By the end of this doc you should be able to answer:
 
@@ -17,7 +17,7 @@ We'll take those questions in order.
 
 ### 1.1 Start from the promise, not the primitives
 
-Flowthru's promise — restated from [CONTRIBUTING.md](../../../CONTRIBUTING.md) — is:
+Flowthru's promise — restated from [CONTRIBUTING.md](/CONTRIBUTING.md) — is:
 
 > If an error can occur in the flow they've created, it will occur as soon in the development process as possible.
 
@@ -29,15 +29,15 @@ Errors are then sorted into three phases — **build-time**, **pre-flight**, and
 | Pre-flight | Missing files, unreachable databases, schema drift, duplicate producers | **Accumulate every error at once** so the user fixes them in one pass                   |
 | Runtime    | Network drops, OOM, transform exceptions                                | **Capture errors as values** so they can't be silently dropped or thrown into the void  |
 
-The FP layer in [src/core/Flowthru.Core/Prelude/](../../../src/core/Flowthru.Core/Prelude/) is not chosen for its own sake — each primitive is the *minimum* shape that makes one of those guarantees mechanically true. Read the Prelude with that lens and the choices stop looking like style.
+The FP layer in [src/core/Flowthru.Core/Prelude/](/src/core/Flowthru.Core/Prelude/) is not chosen for its own sake — each primitive is the *minimum* shape that makes one of those guarantees mechanically true. Read the Prelude with that lens and the choices stop looking like style.
 
 ### 1.2 The Prelude — a deliberately small subset
 
-The Prelude is derived from a small slice of [LanguageExt](https://github.com/louthy/language-ext), but the [Flowthru.Core README](../../../src/core/Flowthru.Core/README.md) is emphatic that this is **not a port**. We took only the FP primitives Flowthru actively uses, and we own them going forward. No HKTs (`K<F, A>`), no generic `Functor<F>` / `Applicative<F>` / `Monad<F>` typeclasses, no monad transformer stack, no `Either` / `Option` / `Try` / `Fin`, no `Seq` / `Lst` / `Iterable`. Every additional abstraction would buy generality we don't need at the cost of API surface a future contributor would have to learn.
+The Prelude is derived from a small slice of [LanguageExt](https://github.com/louthy/language-ext), but the [Flowthru.Core README](/src/core/Flowthru.Core/README.md) is emphatic that this is **not a port**. We took only the FP primitives Flowthru actively uses, and we own them going forward. No HKTs (`K<F, A>`), no generic `Functor<F>` / `Applicative<F>` / `Monad<F>` typeclasses, no monad transformer stack, no `Either` / `Option` / `Try` / `Fin`, no `Seq` / `Lst` / `Iterable`. Every additional abstraction would buy generality we don't need at the cost of API surface a future contributor would have to learn.
 
 The four primitives that survived the cut are:
 
-#### `FlowIO<A>` — [Prelude/FlowIO.cs](../../../src/core/Flowthru.Core/Prelude/FlowIO.cs)
+#### `FlowIO<A>` — [Prelude/FlowIO.cs](/src/core/Flowthru.Core/Prelude/FlowIO.cs)
 
 The runtime effect type. `FlowIO<A>` is a description of a computation that, when run, yields either a value of type `A` or a `RuntimeError`. It is structurally a `Func<CancellationToken, Task<EffResult<A>>>`, but you should not think of it as a function: think of it as a **Kleisli arrow** in the category of Flowthru effects.
 
@@ -60,7 +60,7 @@ Two consequences fall out for free:
 
 **Errors can't be silently swallowed.** A failing `FlowIO<A>` is still a value; consumers must pattern-match `EffResult<A>` to get at the success. Forgetting to handle the failure is a compile-time error at every consumer site.
 
-#### `EffResult<A>` — [Prelude/EffResult.cs](../../../src/core/Flowthru.Core/Prelude/EffResult.cs)
+#### `EffResult<A>` — [Prelude/EffResult.cs](/src/core/Flowthru.Core/Prelude/EffResult.cs)
 
 The closed sum returned by `FlowIO<A>.Run`:
 
@@ -73,9 +73,9 @@ public abstract record EffResult<A>
 }
 ```
 
-The private constructor is load-bearing. Because no derived case can be added outside this file, every consumer's `switch` on `EffResult<A>` is exhaustive *forever*; if Flowthru ever added a third case (it won't), every site would surface as a compile diagnostic until handled. The same construction pattern is used in [`RuntimeError`](../../../src/core/Flowthru.Core/Validation/Runtime/RuntimeError.cs), [`PreFlightError`](../../../src/core/Flowthru.Core/Validation/PreFlight/PreFlightError.cs), [`Validated`](../../../src/core/Flowthru.Core/Prelude/Validated.cs), [`DependencyAnalyzer.Result`](../../../src/core/Flowthru.Core/Flow/DependencyAnalyzer.cs), and [`StepResult`](../../../src/core/Flowthru.Core/Flow/StepResult.cs). When you see `private Foo() { }` with `sealed record` cases, that's a closed sum. Treat it as a non-extensible algebraic data type.
+The private constructor is load-bearing. Because no derived case can be added outside this file, every consumer's `switch` on `EffResult<A>` is exhaustive *forever*; if Flowthru ever added a third case (it won't), every site would surface as a compile diagnostic until handled. The same construction pattern is used in [`RuntimeError`](/src/core/Flowthru.Core/Validation/Runtime/RuntimeError.cs), [`PreFlightError`](/src/core/Flowthru.Core/Validation/PreFlight/PreFlightError.cs), [`Validated`](/src/core/Flowthru.Core/Prelude/Validated.cs), [`DependencyAnalyzer.Result`](/src/core/Flowthru.Core/Flow/DependencyAnalyzer.cs), and [`StepResult`](/src/core/Flowthru.Core/Flow/StepResult.cs). When you see `private Foo() { }` with `sealed record` cases, that's a closed sum. Treat it as a non-extensible algebraic data type.
 
-#### `Validated<TError, TValue>` — [Prelude/Validated.cs](../../../src/core/Flowthru.Core/Prelude/Validated.cs)
+#### `Validated<TError, TValue>` — [Prelude/Validated.cs](/src/core/Flowthru.Core/Prelude/Validated.cs)
 
 The pre-flight error-accumulating applicative. Conceptually similar to a `Result` / `Either`, but with one critical difference: when both sides of a `Zip` are `Invalid`, the resulting `Invalid` carries errors from **both**:
 
@@ -88,7 +88,7 @@ This is the right shape for pre-flight specifically because of the user experien
 
 (Note: `Validated`'s LINQ syntax is monadic — it short-circuits — because LINQ is a sequencing notation. Use `Zip` / `ZipAll` explicitly when you want accumulation.)
 
-#### `FlowResource<TScope>` — [Prelude/FlowResource.cs](../../../src/core/Flowthru.Core/Prelude/FlowResource.cs)
+#### `FlowResource<TScope>` — [Prelude/FlowResource.cs](/src/core/Flowthru.Core/Prelude/FlowResource.cs)
 
 A pair of effects: an `acquire` step that produces a scope, and a `release` step that disposes it. Modelled on Haskell's `bracket` / cats-effect's `Resource`. The framework guarantees release runs on every exit path — success, failure, cancellation — and the release closure receives the body's `RuntimeError?` so it can apply policies like "preserve files on failure."
 
@@ -98,8 +98,8 @@ The fact that acquire and release are **bundled into one value** is the point. A
 
 `FlowIO<A>` and `Validated<E, T>` are language-level primitives with two type parameters — the value, and the error. The Flowthru-specific error types fill in those parameters:
 
-- [`RuntimeError`](../../../src/core/Flowthru.Core/Validation/Runtime/RuntimeError.cs) is the failure type of every `FlowIO<A>`. Its closed-sum cases name every distinct way Flowthru execution can fail at runtime: `External` (act of God), `StepFailed` (attribution), `Cancelled` (control flow), `InvariantViolated` (a Flowthru bug — see §1.4), `ConstraintViolated` (a deliberately-narrowed catalog item was used wrong), `SchemaMismatch` (format adapter saw a structural mismatch mid-stream), and `ExtensionError` (the open extension point — see §2).
-- [`PreFlightError`](../../../src/core/Flowthru.Core/Validation/PreFlight/PreFlightError.cs) is the error type of every pre-flight `Validated`. Its cases are the failure modes detectable *before* any pipeline logic runs: `DuplicateProducer`, `CircularDependency`, `MissingInput`, `SchemaDrift`, `InspectionFailed`, `RegistrationCheckFailed`, and the open extension variant `External`.
+- [`RuntimeError`](/src/core/Flowthru.Core/Validation/Runtime/RuntimeError.cs) is the failure type of every `FlowIO<A>`. Its closed-sum cases name every distinct way Flowthru execution can fail at runtime: `External` (act of God), `StepFailed` (attribution), `Cancelled` (control flow), `InvariantViolated` (a Flowthru bug — see §1.4), `ConstraintViolated` (a deliberately-narrowed catalog item was used wrong), `SchemaMismatch` (format adapter saw a structural mismatch mid-stream), and `ExtensionError` (the open extension point — see §2).
+- [`PreFlightError`](/src/core/Flowthru.Core/Validation/PreFlight/PreFlightError.cs) is the error type of every pre-flight `Validated`. Its cases are the failure modes detectable *before* any pipeline logic runs: `DuplicateProducer`, `CircularDependency`, `MissingInput`, `SchemaDrift`, `InspectionFailed`, `RegistrationCheckFailed`, and the open extension variant `External`.
 
 The split between *language-level* primitives (in `Flowthru.Prelude`) and *phase-specific* ADTs (in `Flowthru.Validation.*`) is intentional. The Prelude does not know about Flowthru; the phase ADTs *are* Flowthru. Adding a new pre-flight failure mode means editing `PreFlightError`, not `Validated`.
 
@@ -113,25 +113,25 @@ Surfacing this as a typed value (rather than letting it disappear into a generic
 
 ### 1.5 The bipartite DAG: places and arrows
 
-A Flowthru pipeline is a [Petri-net-like](https://en.wikipedia.org/wiki/Petri_net) bipartite graph: items are *places* (where data lives), steps are *arrows* (how data moves between places). The two facets are reflected in the type hierarchy under [INode](../../../src/core/Flowthru.Core/Data/Catalog/INode.cs):
+A Flowthru pipeline is a [Petri-net-like](https://en.wikipedia.org/wiki/Petri_net) bipartite graph: items are *places* (where data lives), steps are *arrows* (how data moves between places). The two facets are reflected in the type hierarchy under [INode](/src/core/Flowthru.Core/Data/Catalog/INode.cs):
 
-- [`IItem<T>`](../../../src/core/Flowthru.Core/Data/Catalog/IItem.cs) is the place archetype. It exposes `Load(): FlowIO<T>` and `Save(T): FlowIO<FlowUnit>` — Kleisli arrows in and out of the catalog. The untyped `IItem` interface exists so the engine can iterate over a step's `Inputs` / `Outputs` without naming each item's element type.
-- [`IStepNode<TIn, TOut>`](../../../src/core/Flowthru.Core/Step/IStepNode.cs) is the arrow archetype. It carries a `Transform: Func<TIn, FlowIO<TOut>>` — the Kleisli arrow this step represents — plus the declared `Inputs` and `Outputs` (lists of `IItem`s) the dependency analyzer needs.
+- [`IItem<T>`](/src/core/Flowthru.Core/Data/Catalog/IItem.cs) is the place archetype. It exposes `Load(): FlowIO<T>` and `Save(T): FlowIO<FlowUnit>` — Kleisli arrows in and out of the catalog. The untyped `IItem` interface exists so the engine can iterate over a step's `Inputs` / `Outputs` without naming each item's element type.
+- [`IStepNode<TIn, TOut>`](/src/core/Flowthru.Core/Step/IStepNode.cs) is the arrow archetype. It carries a `Transform: Func<TIn, FlowIO<TOut>>` — the Kleisli arrow this step represents — plus the declared `Inputs` and `Outputs` (lists of `IItem`s) the dependency analyzer needs.
 
 Why bipartite? Because the two key invariants — single-producer per item, no cycles — are statements about how arrows connect places. Encoding each as its own kind of vertex makes those invariants natural to express:
 
-- **Single producer:** "no two arrows have the same place as their target." Mechanised in [DependencyAnalyzer](../../../src/core/Flowthru.Core/Flow/DependencyAnalyzer.cs) — a duplicate output label is rejected as `Result.DuplicateProducer` before any topological sort runs.
+- **Single producer:** "no two arrows have the same place as their target." Mechanised in [DependencyAnalyzer](/src/core/Flowthru.Core/Flow/DependencyAnalyzer.cs) — a duplicate output label is rejected as `Result.DuplicateProducer` before any topological sort runs.
 - **No cycles:** Kahn's algorithm over the arrow→arrow adjacency derived from the producer map; a residual non-zero in-degree at the end yields `Result.CycleDetected`.
 
 Both are pre-flight failures. Both surface as cases on `DependencyAnalyzer.Result`'s closed sum. Neither can ever reach runtime.
 
 ### 1.6 `FlowBuilder` is an algebra; `BuiltFlow` is a program
 
-`FlowBuilder` is the construction algebra for flows — a small set of operations (`AddStep<…>`, `Add(IStepNode)`, `Build`) that produce an immutable [`BuiltFlow`](../../../src/core/Flowthru.Core/Flow/BuiltFlow.cs). The `AddStep<…>` overload matrix — every input arity × output arity × (sync, async, async-with-cancellation) — is **emitted by the source generator** in [FlowBuilderGenerator.cs](../../../src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs), not hand-written, because (a) hand-writing 75+ shapes is a lot of boilerplate, and (b) doing so in a generator lets us widen the matrix later without disturbing call sites.
+`FlowBuilder` is the construction algebra for flows — a small set of operations (`AddStep<…>`, `Add(IStepNode)`, `Build`) that produce an immutable [`BuiltFlow`](/src/core/Flowthru.Core/Flow/BuiltFlow.cs). The `AddStep<…>` overload matrix — every input arity × output arity × (sync, async, async-with-cancellation) — is **emitted by the source generator** in [FlowBuilderGenerator.cs](/src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs), not hand-written, because (a) hand-writing 75+ shapes is a lot of boilerplate, and (b) doing so in a generator lets us widen the matrix later without disturbing call sites.
 
 The name *algebra* matters. Construction returns a description, not an action: a `BuiltFlow` is a value you can inspect, slice, persist, or run multiple times. Construction itself is total — the only way `Build()` fails is by raising `FlowBuildException` for one of `DependencyAnalyzer`'s closed-sum violation cases, and even those are pre-flight, not runtime.
 
-The runtime — [`ParallelFlowScheduler`](../../../src/core/Flowthru.Core/Flow/ParallelFlowScheduler.cs) — interprets the `BuiltFlow` by walking the topological order, calling `step.Execute().Run(ct)` on each, and collecting `EffResult<FlowUnit>`s into [`StepResult`](../../../src/core/Flowthru.Core/Flow/StepResult.cs) (another closed sum: `Succeeded | Failed | Skipped`). The scheduler does not know about the FP types beyond `EffResult` pattern-matching — interpretation is straightforward by design, because the description side carries all the structure.
+The runtime — [`ParallelFlowScheduler`](/src/core/Flowthru.Core/Flow/ParallelFlowScheduler.cs) — interprets the `BuiltFlow` by walking the topological order, calling `step.Execute().Run(ct)` on each, and collecting `EffResult<FlowUnit>`s into [`StepResult`](/src/core/Flowthru.Core/Flow/StepResult.cs) (another closed sum: `Succeeded | Failed | Skipped`). The scheduler does not know about the FP types beyond `EffResult` pattern-matching — interpretation is straightforward by design, because the description side carries all the structure.
 
 This separation — **build a description, then interpret it** — is what makes the same `BuiltFlow` runnable in the parallel scheduler, in dry-run mode, sliced to a subgraph, or by a future scheduler we haven't written yet. None of those interpreters need to be aware of each other.
 
@@ -143,7 +143,7 @@ There are four such points, in roughly increasing depth:
 
 ### 2.1 New formats and storage mediums
 
-The most common extension shape: support for CSV, Parquet, Excel, EFCore, HTTP. Look at [Flowthru.Extensions.Csv/Data/Catalog/CsvItemFactoryExtensions.cs](../../../src/extensions/Flowthru.Extensions.Csv/Data/Catalog/CsvItemFactoryExtensions.cs) for the canonical shape:
+The most common extension shape: support for CSV, Parquet, Excel, EFCore, HTTP. Look at [Flowthru.Extensions.Csv/Data/Catalog/CsvItemFactoryExtensions.cs](/src/extensions/Flowthru.Extensions.Csv/Data/Catalog/CsvItemFactoryExtensions.cs) for the canonical shape:
 
 ```csharp
 namespace Flowthru.Data.Catalog;   // *Core's* namespace, not the extension's
@@ -165,22 +165,22 @@ public static class CsvItemFactoryExtensions
 
 A few things to notice:
 
-- The extension method hangs off [`EnumerableItemFactory`](../../../src/core/Flowthru.Core/Data/Catalog/ItemFactory.cs) — a *factory anchor* that exists specifically so extensions can attach smart constructors. Core ships JSON and Memory by extension methods on the same anchor; extensions add CSV, Parquet, EFCore, etc. End users see a uniform `ItemFactory.Enumerable.<format>(…)` surface.
+- The extension method hangs off [`EnumerableItemFactory`](/src/core/Flowthru.Core/Data/Catalog/ItemFactory.cs) — a *factory anchor* that exists specifically so extensions can attach smart constructors. Core ships JSON and Memory by extension methods on the same anchor; extensions add CSV, Parquet, EFCore, etc. End users see a uniform `ItemFactory.Enumerable.<format>(…)` surface.
 - The generic constraints (`IFlatSchema`, `ITextSerializable`) come from the schema source generator's marker interfaces — that's how "you can't save a nested schema as CSV" becomes a build error rather than a runtime check. The extension does not have to police this itself; the type system does.
-- Composition is preferred where possible: `ComposedStorageAdapter` combines a [medium](../../../src/core/Flowthru.Core/Data/Storage/IStorageMedium.cs), a [format](../../../src/core/Flowthru.Core/Data/Storage/IFormatSerializer.cs), and a [container](../../../src/core/Flowthru.Core/Data/Storage/IContainerAdapter.cs). New format × existing mediums (or vice versa) costs one implementation, not M×N. See [storage-composition.md](./storage-composition.md) for the full picture.
-- For storage shapes where composition doesn't apply — databases, HTTP — implementations satisfy [`IStorageAdapter<T>`](../../../src/core/Flowthru.Core/Data/Storage/IStorageAdapter.cs) directly. EFCore in [EFCoreStorageAdapter.cs](../../../src/extensions/Flowthru.Extensions.EFCore/Data/Storage/EFCore/EFCoreStorageAdapter.cs) is the canonical example.
+- Composition is preferred where possible: `ComposedStorageAdapter` combines a [medium](/src/core/Flowthru.Core/Data/Storage/IStorageMedium.cs), a [format](/src/core/Flowthru.Core/Data/Storage/IFormatSerializer.cs), and a [container](/src/core/Flowthru.Core/Data/Storage/IContainerAdapter.cs). New format × existing mediums (or vice versa) costs one implementation, not M×N. See [storage-composition.md](./storage-composition.md) for the full picture.
+- For storage shapes where composition doesn't apply — databases, HTTP — implementations satisfy [`IStorageAdapter<T>`](/src/core/Flowthru.Core/Data/Storage/IStorageAdapter.cs) directly. EFCore in [EFCoreStorageAdapter.cs](/src/extensions/Flowthru.Extensions.EFCore/Data/Storage/EFCore/EFCoreStorageAdapter.cs) is the canonical example.
 
 The adapter's `Load` and `Save` return `FlowIO<…>`. This is the one place extension authors *do* see Prelude types — they're writing the leaf effects that Core's machinery composes.
 
 ### 2.2 New step archetypes
 
-Core ships exactly one step archetype: `[FlowthruStep]` over a static class with a `Create()` factory returning a `Func<TIn, TOut>`. Extensions can add others by implementing [`IStepNode`](../../../src/core/Flowthru.Core/Step/IStepNode.cs) directly and offering a custom `AddPythonStep` / `AddSparkStep` / etc. that calls `FlowBuilder.Add(IStepNode)` — the hand-written half of [FlowBuilder.cs](../../../src/core/Flowthru.Core/Flow/FlowBuilder.cs) exposes that escape hatch deliberately.
+Core ships exactly one step archetype: `[FlowthruStep]` over a static class with a `Create()` factory returning a `Func<TIn, TOut>`. Extensions can add others by implementing [`IStepNode`](/src/core/Flowthru.Core/Step/IStepNode.cs) directly and offering a custom `AddPythonStep` / `AddSparkStep` / etc. that calls `FlowBuilder.Add(IStepNode)` — the hand-written half of [FlowBuilder.cs](/src/core/Flowthru.Core/Flow/FlowBuilder.cs) exposes that escape hatch deliberately.
 
 An archetype extension takes on more responsibility: it needs to wrap its underlying machinery (a Python interpreter, a Spark session) into a `FlowIO`-typed `Execute()`, declare its inputs and outputs the same way the standard `Step<TIn, TOut>` does, and surface its errors through `RuntimeError` (typically by way of `ExtensionError` — see §2.4).
 
 ### 2.3 Registration-time validation hooks
 
-Extensions can plug into the pre-flight phase by registering `IRegistrationValidationHook`s on the host builder. The canonical example is [`VerifyEFCoreConnection<TContext>()`](../../../src/extensions/Flowthru.Extensions.EFCore/Hosting/EFCoreFlowthruBuilderExtensions.cs):
+Extensions can plug into the pre-flight phase by registering `IRegistrationValidationHook`s on the host builder. The canonical example is [`VerifyEFCoreConnection<TContext>()`](/src/extensions/Flowthru.Extensions.EFCore/Hosting/EFCoreFlowthruBuilderExtensions.cs):
 
 ```csharp
 return builder.RegisterValidationHook(id, services =>
@@ -219,7 +219,7 @@ The third question — and the one most worth getting right — is **why none of
 
 ### 3.1 What a Flow Developer actually writes
 
-This is a real, complete step from the Iris starter ([SplitAndEncodeStep.cs](../../../examples/starter/IrisFUnit/Flows/DataEngineering/Steps/SplitAndEncodeStep.cs)):
+This is a real, complete step from the Iris starter ([SplitAndEncodeStep.cs](/examples/starter/IrisFUnit/Flows/DataEngineering/Steps/SplitAndEncodeStep.cs)):
 
 ```csharp
 [FlowthruStep]
@@ -243,7 +243,7 @@ There is no `FlowIO`, no `Bind`, no `EffResult`, no `RuntimeError`, no `Validate
 
 ### 3.2 What the framework does with it
 
-The boundary lives in [FlowBuilderGenerator.cs](../../../src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs). When the user calls:
+The boundary lives in [FlowBuilderGenerator.cs](/src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs). When the user calls:
 
 ```csharp
 pipeline.AddStep<IEnumerable<IrisRawSchema>, IEnumerable<IrisFeatureSchema>, …>(
@@ -261,7 +261,7 @@ the generated overload — emitted by `FlowBuilderGenerator` for the user's spec
 2. **Builds a `loadInputs` closure** that chains the catalog items' `Load()` calls through `Bind`, materialising the input tuple: `input1.Load().Bind(v1 => input2.Load().Bind(v2 => Pure((v1, v2))))`.
 3. **Builds a `saveOutputs` closure** that chains the outputs' `Save(...)` calls through `Bind`, propagating the first failure and short-circuiting the rest.
 
-The resulting [`Step<TIn, TOut>`](../../../src/core/Flowthru.Core/Step/Step.cs) holds these as private fields, and its `Execute()` method composes them in three lines of LINQ:
+The resulting [`Step<TIn, TOut>`](/src/core/Flowthru.Core/Step/Step.cs) holds these as private fields, and its `Execute()` method composes them in three lines of LINQ:
 
 ```csharp
 public FlowIO<FlowUnit> Execute() =>
@@ -286,7 +286,7 @@ public IItem<IEnumerable<IrisRawSchema>> IrisRaw =>
 
 The smart constructor returns an `IItem<IEnumerable<IrisRawSchema>>` whose `Load()` and `Save(…)` are `FlowIO`-typed. But the catalog developer never calls those methods — they hand the `IItem<…>` to a step's `AddStep` call, and the framework calls `Load`/`Save` from inside the generated `loadInputs` / `saveOutputs` closures. From the catalog developer's perspective, an `IItem<T>` is a typed handle to a place data lives. The fact that it's also a Kleisli arrow into the runtime is a framework concern.
 
-[CatalogAbstract](../../../src/core/Flowthru.Core/Data/Catalog/CatalogAbstract.cs) caches each property's item by name on first access, so the DAG sees one stable `IItem<T>` instance per catalog property — object identity is what makes catalogs usable as DAG vertices.
+[CatalogAbstract](/src/core/Flowthru.Core/Data/Catalog/CatalogAbstract.cs) caches each property's item by name on first access, so the DAG sees one stable `IItem<T>` instance per catalog property — object identity is what makes catalogs usable as DAG vertices.
 
 ### 3.4 The compact statement of the boundary
 
@@ -303,21 +303,21 @@ When you contribute to Core, ask: *which row of that table is this name supposed
 
 ### 3.5 Source generators do most of the boundary work
 
-The four source generators in [src/core/Flowthru.Core.SourceGenerators/](../../../src/core/Flowthru.Core.SourceGenerators/) each enforce a piece of this boundary:
+The four source generators in [src/core/Flowthru.Core.SourceGenerators/](/src/core/Flowthru.Core.SourceGenerators/) each enforce a piece of this boundary:
 
-- [FlowBuilderGenerator](../../../src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs) — emits the `AddStep<…>` matrix that translates raw `Func<TIn, TOut>` into `FlowIO`-wrapped Kleisli arrows. This is the single largest contributor to the boundary.
-- [SchemaInterfaceGenerator](../../../src/core/Flowthru.Core.SourceGenerators/Schema/SchemaInterfaceGenerator.cs) — analyses `[FlowthruSchema]` records, classifies them as flat / nested, and emits the marker interfaces (`IFlatSchema`, `INestedSchema`, `ITextSerializable`, `IStructuredSerializable`) that gate which adapters will accept the schema. This is what makes "save nested schema as CSV" a build error rather than a runtime explosion.
-- [CatalogPropertyGenerator](../../../src/core/Flowthru.Core.SourceGenerators/Catalog/CatalogPropertyGenerator.cs) — emits the bodies for attribute-driven partial properties (`[JsonItem(...)]`, `[CsvItem(...)]`, etc.) on the catalog so Catalog Developers don't have to repeat `CreateItem(() => ItemFactory.…)` boilerplate.
-- [StepMetadataGenerator](../../../src/core/Flowthru.Core.SourceGenerators/Step/StepMetadataGenerator.cs) — emits a companion `{StepName}_Metadata` record alongside every `[FlowthruStep]`-decorated class, so diagnostics, metadata exporters, and architecture tests can walk every step in an assembly without reflecting at runtime.
+- [FlowBuilderGenerator](/src/core/Flowthru.Core.SourceGenerators/Flow/FlowBuilderGenerator.cs) — emits the `AddStep<…>` matrix that translates raw `Func<TIn, TOut>` into `FlowIO`-wrapped Kleisli arrows. This is the single largest contributor to the boundary.
+- [SchemaInterfaceGenerator](/src/core/Flowthru.Core.SourceGenerators/Schema/SchemaInterfaceGenerator.cs) — analyses `[FlowthruSchema]` records, classifies them as flat / nested, and emits the marker interfaces (`IFlatSchema`, `INestedSchema`, `ITextSerializable`, `IStructuredSerializable`) that gate which adapters will accept the schema. This is what makes "save nested schema as CSV" a build error rather than a runtime explosion.
+- [CatalogPropertyGenerator](/src/core/Flowthru.Core.SourceGenerators/Catalog/CatalogPropertyGenerator.cs) — emits the bodies for attribute-driven partial properties (`[JsonItem(...)]`, `[CsvItem(...)]`, etc.) on the catalog so Catalog Developers don't have to repeat `CreateItem(() => ItemFactory.…)` boilerplate.
+- [StepMetadataGenerator](/src/core/Flowthru.Core.SourceGenerators/Step/StepMetadataGenerator.cs) — emits a companion `{StepName}_Metadata` record alongside every `[FlowthruStep]`-decorated class, so diagnostics, metadata exporters, and architecture tests can walk every step in an assembly without reflecting at runtime.
 
 The generators are *part* of the design, not an optimisation. Without them, the boundary would have to be enforced by convention or by burdening the user with FP-typed APIs. With them, the user's code is straightforward C# and the framework absorbs the structure.
 
 ## 4. Where to go next
 
-- [CONTRIBUTING.md](../../../CONTRIBUTING.md) — the rules and the three error phases.
-- [Flowthru.Core README](../../../src/core/Flowthru.Core/README.md) — the Prelude's provenance and scope.
+- [CONTRIBUTING.md](/CONTRIBUTING.md) — the rules and the three error phases.
+- [Flowthru.Core README](/src/core/Flowthru.Core/README.md) — the Prelude's provenance and scope.
 - [storage-composition.md](./storage-composition.md) — how `IStorageMedium` × `IFormatSerializer` × `IContainerAdapter` factor.
-- [anatomy-of-a-flow.md](../anatomy-of-a-flow.md) — the same picture, from the Flow Developer's side, useful for sanity-checking that the boundary holds.
-- The Prelude itself: [FlowIO](../../../src/core/Flowthru.Core/Prelude/FlowIO.cs), [Validated](../../../src/core/Flowthru.Core/Prelude/Validated.cs), [EffResult](../../../src/core/Flowthru.Core/Prelude/EffResult.cs), [FlowResource](../../../src/core/Flowthru.Core/Prelude/FlowResource.cs). Each file is short. Read them.
+- [anatomy-of-a-flow.md](/docs/explanation/anatomy-of-a-flow.md) — the same picture, from the Flow Developer's side, useful for sanity-checking that the boundary holds.
+- The Prelude itself: [FlowIO](/src/core/Flowthru.Core/Prelude/FlowIO.cs), [Validated](/src/core/Flowthru.Core/Prelude/Validated.cs), [EffResult](/src/core/Flowthru.Core/Prelude/EffResult.cs), [FlowResource](/src/core/Flowthru.Core/Prelude/FlowResource.cs). Each file is short. Read them.
 
 If something in this document disagrees with the code, the code is correct and this document is stale — please send a PR.
diff --git a/docs/explanation/anatomy-of-a-flow.md b/docs/explanation/anatomy-of-a-flow.md
index ac0ae2f4..4c037a3d 100644
--- a/docs/explanation/anatomy-of-a-flow.md
+++ b/docs/explanation/anatomy-of-a-flow.md
@@ -59,7 +59,7 @@ Key points:
 
 - **`[FlowthruSchema]`** protects against attempts to store a schema in an incompatible format.
   - The generator inspects every property type and classifies the schema as flat (CSV-compatible) or nested (JSON/Parquet only). Primitives, enums, `Guid`, `DateTime`, and similar single-value types are flat. Collections and nested objects make a schema nested.
-  - For user-defined types such as NewTypes or strong-typed identifiers, implement `IScalar` to declare that the type serializes to a single value. See [Customizing Schema Property Types](../guides/customizing-schema-property-types.md) for the full classification rules and examples.
+  - For user-defined types such as NewTypes or strong-typed identifiers, implement `IScalar` to declare that the type serializes to a single value. See [Customizing Schema Property Types](/docs/guides/customizing-schema-property-types.md) for the full classification rules and examples.
 - **`required`** enforces that data in that column will never be null.
 - **`[SerializedLabel("...")]`** maps C# property names to external field names (e.g., CSV headers). Omit it when names match.
 
diff --git a/docs/explanation/index.md b/docs/explanation/index.md
new file mode 100644
index 00000000..d54cde87
--- /dev/null
+++ b/docs/explanation/index.md
@@ -0,0 +1,20 @@
+---
+title: Explanation
+description: Understanding-oriented discussion of Flowthru's design — the primitives, the fail-fast philosophy, and the tradeoffs behind them.
+review: draft
+---
+
+Explanation pages are **understanding-oriented**: they step back from any single task to discuss *why* Flowthru is built the way it is — its primitives, its fail-fast philosophy, and the tradeoffs behind the design. Read these when you want the mental model, not a procedure.
+
+## What's here
+
+- **[Anatomy of a Flowthru Flow](anatomy-of-a-flow/)** — the pieces that make up a Flow (schemas, catalogs, Steps, Flows) and how they connect.
+
+### Advanced
+
+- **[Core Architecture for Contributors](advanced/core-architecture/)** — how the engine fits together, for people working on Flowthru itself.
+- **[Storage Adapter Architecture](advanced/storage-composition/)** — how formats and storage adapters compose.
+
+## Where to start
+
+[Anatomy of a Flowthru Flow](anatomy-of-a-flow/) is the best entry point. To put these concepts into practice, see the [Tutorials](/docs/tutorials/) and [Guides](/docs/guides/).
diff --git a/docs/guides/advanced/container-deployment.md b/docs/guides/advanced/container-deployment.md
index 30c4454e..a706a780 100644
--- a/docs/guides/advanced/container-deployment.md
+++ b/docs/guides/advanced/container-deployment.md
@@ -7,9 +7,9 @@ Deploy a Flowthru pipeline as a standalone container image for execution in envi
 
 ## Prerequisites
 
-- A working Flowthru pipeline project (see the [starter tutorial](../../tutorials/) if you need one)
+- A working Flowthru pipeline project (see the [starter tutorial](/docs/tutorials/) if you need one)
 - Docker or a compatible container runtime
-- Familiarity with [pipeline slicing](../slicing-pipelines.md)
+- Familiarity with [pipeline slicing](/docs/guides/slicing-pipelines.md)
 
 ## The Entry Point
 
@@ -175,5 +175,5 @@ if (!result.Success)
 
 ## See Also
 
-- [Pipeline slicing](../slicing-pipelines.md) — all slice strategies and how they compose
+- [Pipeline slicing](/docs/guides/slicing-pipelines.md) — all slice strategies and how they compose
 - [Service integration](service-integration.md) — embedding Flowthru in an existing .NET host instead of a standalone container
diff --git a/docs/guides/advanced/metadata-providers.md b/docs/guides/advanced/metadata-providers.md
index f912d110..03081a08 100644
--- a/docs/guides/advanced/metadata-providers.md
+++ b/docs/guides/advanced/metadata-providers.md
@@ -8,7 +8,7 @@ This guide shows how to create custom metadata providers that receive pipeline m
 ## Prerequisites
 
 You should already understand:
-- Basic Flowthru pipeline structure (see [Anatomy of a Pipeline](../../explanation/anatomy-of-a-pipeline.md))
+- Basic Flowthru Flow structure (see [Anatomy of a Flow](/docs/explanation/anatomy-of-a-flow.md))
 - Dependency injection with `AddFlowthru()`
 
 ## Creating a Provider
diff --git a/docs/guides/advanced/service-integration.md b/docs/guides/advanced/service-integration.md
index 3027165a..3d46e0ad 100644
--- a/docs/guides/advanced/service-integration.md
+++ b/docs/guides/advanced/service-integration.md
@@ -9,7 +9,7 @@ Register `IFlowthruService` into an existing .NET application and invoke pipelin
 
 - An existing .NET application with dependency injection (ASP.NET Core, worker service, etc.)
 - A Flowthru pipeline project referenced as a project dependency or NuGet package
-- Familiarity with [pipeline slicing](../slicing-pipelines.md)
+- Familiarity with [pipeline slicing](/docs/guides/slicing-pipelines.md)
 
 ## Registration
 
@@ -214,5 +214,5 @@ For most applications — one set of pipelines, invoked by various triggers —
 
 ## See Also
 
-- [Pipeline slicing](../slicing-pipelines.md) — all slice strategies and how they compose
+- [Pipeline slicing](/docs/guides/slicing-pipelines.md) — all slice strategies and how they compose
 - [Container deployment](container-deployment.md) — deploying a pipeline as a standalone container instead of embedding it
diff --git a/docs/guides/constraining-catalog-entries.md b/docs/guides/constraining-catalog-entries.md
index 082cc1d0..e02ce075 100644
--- a/docs/guides/constraining-catalog-entries.md
+++ b/docs/guides/constraining-catalog-entries.md
@@ -225,4 +225,4 @@ Use `RawData` as output in ingestion pipelines, `RawDataReadOnly` as input in tr
 ## See Also
 
 - **[Storage Adapter Architecture](/docs/explanation/advanced/storage-composition.md)** — How traits propagate through storage layers (contributor documentation)
-- **[Slicing Pipelines](/docs/guides/slicing-pipelines.md)** — Execute subsets of your pipeline for testing
+- **[Slicing Flows](slicing-pipelines.md)** — Execute subsets of your Flow for testing
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 00000000..f7e3ce06
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,24 @@
+---
+title: Guides
+description: Goal-oriented recipes for accomplishing a specific task with Flowthru — assumes you already know the basics from the tutorial.
+review: draft
+---
+
+Guides are **task-oriented**: focused recipes for getting a specific job done. Unlike the tutorial, they assume you already know the basics and want the shortest path to a result. Each guide answers a single "how do I…?" question.
+
+## What's here
+
+- **[Constraining Catalog Entries](constraining-catalog-entries/)** — apply read-only, append-only, and similar constraints to catch policy violations at Flow construction rather than runtime.
+- **[Customizing Schema Property Types](customizing-schema-property-types/)** — use `IScalar` to let custom types (newtypes, value objects, strong-typed IDs) appear as columns in a flat schema.
+- **[Slicing Flows](slicing-pipelines/)** — run subsets of a Flow with `--from`, `--to`, and `--only` for testing and debugging.
+- **[Using EFCore Catalog Entries](using-efcore-catalog-entries/)** — back catalog entries with a relational database instead of files.
+
+### Advanced
+
+- **[Deploying a Flow in a Container](advanced/container-deployment/)** — package and run a Flow in a container image.
+- **[Custom Metadata Providers](advanced/metadata-providers/)** — emit your own run metadata alongside the built-in JSON and Mermaid providers.
+- **[Using Flowthru as a Service Dependency](advanced/service-integration/)** — host Flowthru inside a longer-running application.
+
+## Where to start
+
+If you're new, work through the [Spaceflights tutorial](/docs/tutorials/spaceflights/) first — the guides assume that grounding. For the reasoning behind these tasks, see the [Explanation](/docs/explanation/) section.
diff --git a/docs/index.md b/docs/index.md
deleted file mode 100644
index 989f51ae..00000000
--- a/docs/index.md
+++ /dev/null
@@ -1 +0,0 @@
-test!
diff --git a/docs/project.json b/docs/project.json
index eba141c9..3789fcbd 100644
--- a/docs/project.json
+++ b/docs/project.json
@@ -3,6 +3,8 @@
   "$schema": "../node_modules/nx/schemas/project-schema.json",
   "projectType": "library",
   "sourceRoot": "./docs",
+  "//": "implicitDependencies on `examples` makes `nx affected` reach docs when example source changes — the doc-snippet freshness check (docs:_test:snippet-freshness) depends on `#region docs:*` ranges in examples/**, so an example edit must mark `docs` affected even though no docs/ file changed.",
+  "implicitDependencies": [ "examples" ],
   "targets": {
     "_build-reference": {
       "//": "Generates markdown API reference from C# docstrings into docs/reference/src/. Inputs are scoped to the C# source + the docfx script — hand-written docs (tutorials/, guides/, explanation/) do NOT invalidate this cache, since docfx doesn't read them. Private subtarget; composed into docs:build.",
@@ -53,6 +55,85 @@
         "parallel": false
       }
     },
+    "sync-snippets": {
+      "//": "The `docs` half of the doc-snippet pipeline. Consumes dist/examples/docs/snippets/ (produced by examples:generate-snippets) and splices each snippet into managed marker blocks in docs/{tutorials,guides,explanation}. NOT cached — it mutates source docs in place (same as examples:sync-readmes); caching a source mutation would be wrong. The non-mutating freshness check lives in docs:_test:snippet-freshness (runs in `nx affected -t test`). Hard-fails on a sentinel referencing a missing snippet or an orphan snippet.",
+      "executor": "nx:run-commands",
+      "dependsOn": [ "examples:generate-snippets" ],
+      "options": {
+        "commands": [
+          "node scripts/sync-doc-snippets.mjs"
+        ],
+        "cwd": "{workspaceRoot}",
+        "parallel": false
+      }
+    },
+    "test": {
+      "//": "Public docs meta-test barrel — mirrors tests:test. Composes the doc-integrity subtargets via dependsOn; run by `nx affected -t test`. _test:link-audit and _test:snippet-freshness gate (broken link / drift → fail); _test:doc-warnings is advisory (terminology + review-state, never fails) until the corpus is cleaned and terminology promotes to a gate.",
+      "executor": "nx:noop",
+      "dependsOn": [
+        "_test:link-audit",
+        "_test:snippet-freshness",
+        "_test:doc-warnings"
+      ]
+    },
+    "_test:link-audit": {
+      "//": "GATING. Deterministic filesystem audit of internal links in hand-authored docs: flags root-absolute links (404 under base) and relative links whose target page doesn't exist. Pure function of the docs source — NX caches it honestly and it returns the same result locally and in CI, unlike the Starlight build validator (which is incremental-cache-sensitive and skips relative links). Private subtarget; composed into docs:test.",
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/docs/tutorials/**/*.md",
+        "{workspaceRoot}/docs/guides/**/*.md",
+        "{workspaceRoot}/docs/explanation/**/*.md",
+        "{workspaceRoot}/scripts/lint-doc-links.mjs"
+      ],
+      "outputs": [],
+      "options": {
+        "commands": [ "node scripts/lint-doc-links.mjs" ],
+        "cwd": "{workspaceRoot}",
+        "parallel": false
+      }
+    },
+    "_test:snippet-freshness": {
+      "//": "GATING. Regenerates the snippet artifacts (via examples:generate-snippets) and asserts every committed doc is in sync — fails if a `#region docs:*` changed without a re-sync, if a sentinel references a missing snippet, or if a region is orphaned. Non-mutating (`--check`): writes nothing, so it leaves no working-tree side effects. Private subtarget; composed into docs:test.",
+      "executor": "nx:run-commands",
+      "cache": true,
+      "dependsOn": [ "examples:generate-snippets" ],
+      "inputs": [
+        "{workspaceRoot}/examples/starter/**/*.cs",
+        "{workspaceRoot}/examples/starter/**/*.py",
+        "{workspaceRoot}/examples/advanced/**/*.cs",
+        "{workspaceRoot}/examples/advanced/**/*.py",
+        "{workspaceRoot}/docs/tutorials/**/*.md",
+        "{workspaceRoot}/docs/guides/**/*.md",
+        "{workspaceRoot}/docs/explanation/**/*.md",
+        "{workspaceRoot}/scripts/generate-doc-snippets.mjs",
+        "{workspaceRoot}/scripts/sync-doc-snippets.mjs"
+      ],
+      "outputs": [],
+      "options": {
+        "commands": [ "node scripts/sync-doc-snippets.mjs --check" ],
+        "cwd": "{workspaceRoot}",
+        "parallel": false
+      }
+    },
+    "_test:doc-warnings": {
+      "//": "ADVISORY (exits 0). Emits terminology (`_Avoid_:` glossary terms) and review-state (`review:` frontmatter not `reviewed`) warnings to the GitHub step summary. Non-gating per the docs-honesty model until the corpus is cleaned; flipping it to a gate is removing the exit-0 in the script. Private subtarget; composed into docs:test.",
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/docs/tutorials/**/*.md",
+        "{workspaceRoot}/docs/guides/**/*.md",
+        "{workspaceRoot}/docs/explanation/**/*.md",
+        "{workspaceRoot}/examples/CONTRIBUTING.md",
+        "{workspaceRoot}/scripts/lint-docs-warnings.mjs"
+      ],
+      "outputs": [],
+      "options": {
+        "commands": [ "node scripts/lint-docs-warnings.mjs" ],
+        "cwd": "{workspaceRoot}",
+        "parallel": false
+      }
+    },
     "build": {
       "//": "Public docs build barrel. Composes private _build-* subtargets via dependsOn — each subtarget owns its own input/output footprint and caches independently. Adding a new MD generator (e.g., a future schema-gallery or diagnostic-id catalog) is a new _build-<name> private subtarget plus one line here. Mirrors the tests:test pattern.",
       "executor": "nx:noop",
diff --git a/docs/reference/index.md b/docs/reference/index.md
new file mode 100644
index 00000000..7da21cf7
--- /dev/null
+++ b/docs/reference/index.md
@@ -0,0 +1,16 @@
+---
+title: Reference
+description: Information-oriented reference for Flowthru — the auto-generated API surface plus the storage capability matrix.
+review: draft
+---
+
+Reference is **information-oriented**: precise, lookup-style material you consult when you already know what you're after. Most of it is generated directly from Flowthru's C# source, so it stays in lockstep with the code — it is not hand-edited.
+
+## What's here
+
+- **[Storage Capability Matrix](extensions/capability-matrix/)** — which formats (CSV, Excel, Parquet, …) support row vs. stream reading and writing. Generated from the format-extension surface.
+- **API Reference** — every public type under `Flowthru.Core` and the extensions, generated from XML doc comments. Browse it from the **Reference** section in the sidebar.
+
+## Where to start
+
+If you're exploring what Flowthru can read and write, the [capability matrix](extensions/capability-matrix/) is the fastest orientation. For conceptual grounding behind the types, see the [Explanation](../explanation/) section; for step-by-step usage, the [Guides](../guides/).
diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
new file mode 100644
index 00000000..7aed3359
--- /dev/null
+++ b/docs/tutorials/index.md
@@ -0,0 +1,15 @@
+---
+title: Tutorials
+description: Learning-oriented walkthroughs that build a complete Flowthru project from scratch — the place to start if you're new to the framework.
+review: draft
+---
+
+Tutorials are **learning-oriented**: hands-on walkthroughs that take you from an empty project to a working Flow, explaining each concept as you meet it. They're the place to start if you're new to Flowthru — you'll touch schemas, catalogs, Steps, and Flows in the order you'd actually build them.
+
+## What's here
+
+- **[Spaceflights](spaceflights/)** — the end-to-end starter tutorial. You'll scaffold a project from the Flowthru template, register CSV and Excel datasets, define typed schemas, and build the Flows that turn raw data into a price-prediction model input.
+
+## Where to start
+
+Begin with the [Spaceflights tutorial](spaceflights/) and work through the chapters in order. Once you're comfortable, the [Guides](/docs/guides/) cover specific tasks and the [Explanation](/docs/explanation/) pages cover the *why* behind the design.
diff --git a/docs/tutorials/spaceflights/02-set-up-data.md b/docs/tutorials/spaceflights/02-set-up-data.md
index feb1bb74..67f00a1e 100644
--- a/docs/tutorials/spaceflights/02-set-up-data.md
+++ b/docs/tutorials/spaceflights/02-set-up-data.md
@@ -1,6 +1,7 @@
 ---
 title: Set Up Data
 description: Add the Spaceflights datasets to your project, define a schema for each, and register catalog items that connect those schemas to the physical CSV and Excel files.
+review: draft
 ---
 
 This page explains how to add datasets to your project and register them in Flowthru's Catalog. You'll define schemas for each dataset and create catalog items that connect schemas to physical files.
@@ -92,33 +93,51 @@ Spaceflights
 
 Now that we have the file, we'll fill it in with the schema. For companies, the schema will look like:
 
+<!-- flowthru:snippet:docs:schema-company:start -->
 ```csharp
-using Flowthru.Abstractions;
+using Flowthru.Data.Schema;
 
 namespace Spaceflights.Data._01_Raw.Schemas;
 
+/// <summary>
+/// Represents raw company data as imported from text files.
+/// All fields are stored as strings pending parsing.
+/// </summary>
 [FlowthruSchema]
 public partial record CompanySchema
 {
+  /// <summary>
+  /// Unique identifier for the company.
+  /// </summary>
   [SerializedLabel("id")]
-  public required string Id { get; init; }
+  public string Id { get; init; } = null!;
 
+  /// <summary>
+  /// Company rating as a percentage string (e.g., "90%").
+  /// </summary>
   [SerializedLabel("company_rating")]
-  public required string CompanyRating { get; init; }
+  public string CompanyRating { get; init; } = null!;
 
+  /// <summary>
+  /// IATA approval status as a string flag ("t" for true, "f" for false).
+  /// </summary>
   [SerializedLabel("iata_approved")]
-  public required string IataApproved { get; init; }
+  public string IataApproved { get; init; } = null!;
 
+  /// <summary>
+  /// Geographic location of the company.
+  /// </summary>
   [SerializedLabel("company_location")]
-  public required string CompanyLocation { get; init; }
+  public string CompanyLocation { get; init; } = null!;
 }
 ```
+<!-- flowthru:snippet:docs:schema-company:end -->
 
 Let's go through what we've done here, step by step.
 
 1. `record CompanySchema` defines how we reference data that has this shape in other places in the application. Whenever you're working with any data that has these columns, and these data types, we can say that data is a piece of `CompanySchema` data.
-2. In your code, you may not always want to reference a column by its name in the file. After all, you're not working with CSVs by hand — you're using C#! The `[SerializedLabel]` lets us define what column we're referencing in the original file.
-3. For each column, we define the **type** of that column, as well as how we'll reference the column in our code later. `string CompanyRating` C#, and our future selves writing nodes, that CompanyRating will be a string.
+2. In your code, you may not always want to reference a column by its name in the file. After all, you're not working with CSVs by hand — you're using C#! The `[SerializedLabel]` attribute lets us define which column in the original file each property maps to.
+3. For each column, we declare its **type** and the name we'll use to reference it in our code later. `public string CompanyRating` tells C#, and our future selves writing Steps, that `CompanyRating` is a string. (The `= null!` initializer tells the compiler these required fields are populated during deserialization.)
 
 ### Review & Shuttles Schemas
 
@@ -161,13 +180,10 @@ public partial class Catalog
   /// ...
 
   public IItem<IEnumerable<__SCHEMA__>> __NAME__ =>
-    GetOrCreateEntry(
-      () =>
-        Items.Enumerable.__FORMAT__<__SCHEMA__>(
-          label: "__NAME__",
-          path: "__PATH__"
-        )
-    );
+    CreateItem(() => Item.Of<IEnumerable<__SCHEMA__>>("__NAME__")
+      .__FORMAT__()
+      .AtPath("__PATH__")
+      .Build());
   
   /// ...
 }
@@ -189,59 +205,52 @@ For our CompanySchema then:
 
 Our entry for Companies, then, will look like:
 
-```cs
-  public IItem<IEnumerable<CompanySchema>> Companies =>
-    GetOrCreateEntry(
-      () =>
-        Items.Enumerable.Csv<CompanySchema>(
-          label: "Companies",
-          path: $"{basePath}/Data/_01_Raw/Datasets/companies.csv"
-        )
-    );
+<!-- flowthru:snippet:docs:catalog-raw-companies:start -->
+```csharp
+/// <summary>Raw company data imported from external sources.</summary>
+public IItem<IEnumerable<CompanySchema>> Companies =>
+  CreateItem(() => Item.Of<IEnumerable<CompanySchema>>("Companies")
+    .Csv()
+    .AtPath($"{_basePath}/_01_Raw/Datasets/companies.csv")
+    .Build());
 ```
+<!-- flowthru:snippet:docs:catalog-raw-companies:end -->
 
-We can use this pattern to add the three new entries for our three input tables:
+We use the same pattern to add all three entries for our input tables. Note that the Excel item adds one extra call, `.WithSheet("Sheet1")`, to pick the worksheet:
 
-```cs
-using Flowthru.Data;
+<!-- flowthru:snippet:docs:catalog-raw-all:start -->
+```csharp
+using Flowthru.Data.Catalog;
 using Spaceflights.Data._01_Raw.Schemas;
 
 namespace Spaceflights.Data;
 
 public partial class Catalog
 {
-
-  // Minimal "Names" Entry — keep it for now, to keep the project building.
-
+  /// <summary>Raw company data imported from external sources.</summary>
   public IItem<IEnumerable<CompanySchema>> Companies =>
-    GetOrCreateEntry(
-      () =>
-        Items.Enumerable.Csv<CompanySchema>(
-          label: "Companies",
-          filePath: $"{_basePath}/_01_Raw/Datasets/companies.csv"
-        )
-    );
+    CreateItem(() => Item.Of<IEnumerable<CompanySchema>>("Companies")
+      .Csv()
+      .AtPath($"{_basePath}/_01_Raw/Datasets/companies.csv")
+      .Build());
 
+  /// <summary>Raw review data imported from external sources.</summary>
   public IItem<IEnumerable<ReviewSchema>> Reviews =>
-    GetOrCreateEntry(
-      () =>
-        Items.Enumerable.Csv<ReviewSchema>(
-          label: "Reviews",
-          filePath: $"{_basePath}/_01_Raw/Datasets/reviews.csv"
-        )
-    );
+    CreateItem(() => Item.Of<IEnumerable<ReviewSchema>>("Reviews")
+      .Csv()
+      .AtPath($"{_basePath}/_01_Raw/Datasets/reviews.csv")
+      .Build());
 
+  /// <summary>Raw shuttle data imported from external sources (Excel).</summary>
   public IItem<IEnumerable<ShuttleSchema>> Shuttles =>
-    GetOrCreateEntry(
-      () =>
-        Items.Enumerable.Excel<ShuttleSchema>(
-          label: "Shuttles",
-          filePath: $"{_basePath}/_01_Raw/Datasets/shuttles.xlsx",
-          sheetName: "Sheet1"
-        )
-    );
+    CreateItem(() => Item.Of<IEnumerable<ShuttleSchema>>("Shuttles")
+      .Excel()
+      .AtPath($"{_basePath}/_01_Raw/Datasets/shuttles.xlsx")
+      .WithSheet("Sheet1")
+      .Build());
 }
 ```
+<!-- flowthru:snippet:docs:catalog-raw-all:end -->
 
 
 ## What's Next?
@@ -256,8 +265,8 @@ At this point, your schemas and Catalog Entries should be correctly set up. You
 dotnet build
 ```
 
-If you have zero build issues: congratulations! We're ready to move onto our next steps: Defining new nodes!
+If you have zero build issues: congratulations! We're ready to move onto our next step: defining the Steps that process this data.
 
-You've defined schemas and registered raw datasets in the catalog. Next, you'll create a pipeline that processes this data into a format ready for data science!
+You've defined schemas and registered raw datasets in the catalog. Next, you'll create a Flow that processes this data into a format ready for data science!
 
-**Continue to: [Create a Pipeline](03-create-a-pipeline.md)**
+**Continue to: [Create a Flow](03-create-a-pipeline.md)**
diff --git a/examples/project.json b/examples/project.json
index 2c2cdcd8..b53f9d90 100644
--- a/examples/project.json
+++ b/examples/project.json
@@ -4,6 +4,26 @@
   "projectType": "library",
   "sourceRoot": "examples",
   "targets": {
+    "generate-snippets": {
+      "//": "Extracts `#region docs:<label>` ranges from example source into fenced snippet files under dist/examples/docs/snippets/. The `examples` half of the doc-snippet pipeline; docs:sync-snippets consumes the dist output. Inputs scoped to example source so unrelated changes don't invalidate; cached.",
+      "executor": "nx:run-commands",
+      "cache": true,
+      "inputs": [
+        "{workspaceRoot}/examples/starter/**/*.cs",
+        "{workspaceRoot}/examples/starter/**/*.py",
+        "{workspaceRoot}/examples/advanced/**/*.cs",
+        "{workspaceRoot}/examples/advanced/**/*.py",
+        "{workspaceRoot}/scripts/generate-doc-snippets.mjs"
+      ],
+      "outputs": [ "{workspaceRoot}/dist/examples/docs/snippets" ],
+      "options": {
+        "commands": [
+          "node scripts/generate-doc-snippets.mjs"
+        ],
+        "cwd": "{workspaceRoot}",
+        "parallel": false
+      }
+    },
     "sync-readmes": {
       "//": "Per example under starter/ and advanced/: runs `dotnet run --dry-run` to emit Metadata/dag-merged.md via the Mermaid extension, then splices it into the example's README between the <!-- flowthru:mermaid:start --> / <!-- flowthru:mermaid:end --> markers. Missing READMEs are scaffolded; missing markers are appended at EOF; examples whose dry-run fails (e.g. live-infra dependencies) are skipped with a warning.",
       "executor": "nx:run-commands",
diff --git a/examples/starter/Spaceflights/Data/_01_Raw/Catalog.Raw.cs b/examples/starter/Spaceflights/Data/_01_Raw/Catalog.Raw.cs
index 5ebc0aa4..fc4df7c8 100644
--- a/examples/starter/Spaceflights/Data/_01_Raw/Catalog.Raw.cs
+++ b/examples/starter/Spaceflights/Data/_01_Raw/Catalog.Raw.cs
@@ -1,3 +1,4 @@
+#region docs:catalog-raw-all
 using Flowthru.Data.Catalog;
 using Spaceflights.Data._01_Raw.Schemas;
 
@@ -5,12 +6,14 @@ namespace Spaceflights.Data;
 
 public partial class Catalog
 {
+  #region docs:catalog-raw-companies
   /// <summary>Raw company data imported from external sources.</summary>
   public IItem<IEnumerable<CompanySchema>> Companies =>
     CreateItem(() => Item.Of<IEnumerable<CompanySchema>>("Companies")
       .Csv()
       .AtPath($"{_basePath}/_01_Raw/Datasets/companies.csv")
       .Build());
+  #endregion
 
   /// <summary>Raw review data imported from external sources.</summary>
   public IItem<IEnumerable<ReviewSchema>> Reviews =>
@@ -27,3 +30,4 @@ public partial class Catalog
       .WithSheet("Sheet1")
       .Build());
 }
+#endregion
diff --git a/examples/starter/Spaceflights/Data/_01_Raw/Schemas/CompanySchema.cs b/examples/starter/Spaceflights/Data/_01_Raw/Schemas/CompanySchema.cs
index 9b317be5..311d6f25 100644
--- a/examples/starter/Spaceflights/Data/_01_Raw/Schemas/CompanySchema.cs
+++ b/examples/starter/Spaceflights/Data/_01_Raw/Schemas/CompanySchema.cs
@@ -1,3 +1,4 @@
+#region docs:schema-company
 using Flowthru.Data.Schema;
 
 namespace Spaceflights.Data._01_Raw.Schemas;
@@ -33,3 +34,4 @@ public partial record CompanySchema
   [SerializedLabel("company_location")]
   public string CompanyLocation { get; init; } = null!;
 }
+#endregion
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 24cd66da..f7f531fd 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -69,6 +69,9 @@ importers:
       '@types/node':
         specifier: ^22.10.2
         version: 22.19.17
+      starlight-links-validator:
+        specifier: ^0.13
+        version: 0.13.4(@astrojs/starlight@0.30.6(astro@5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3)))(astro@5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3))
       yaml:
         specifier: ^2.8.0
         version: 2.8.3
@@ -2051,6 +2054,9 @@ packages:
   '@types/parse-json@4.0.2':
     resolution: {integrity: sha512-dISoDXWWQwUquiKsyZ4Ng+HX2KsPL7LyHKHQwgGFEA3IaKac4Obd+h2a/a6waisAoepJlBcx9paWqjA8/HVjCw==}
 
+  '@types/picomatch@2.3.3':
+    resolution: {integrity: sha512-Yll76ZHikRFCyz/pffKGjrCwe/le2CDwOP5F210KQo27kpRE46U2rDnzikNlVn6/ezH3Mhn46bJMTfeVTtcYMg==}
+
   '@types/sarif@2.1.7':
     resolution: {integrity: sha512-kRz0VEkJqWLf1LLVN4pT1cg1Z9wAuvI6L97V3m2f5B76Tg8d413ddvLBPTEHAZJlnn4XSvu0FkZtViCQGVyrXQ==}
 
@@ -2072,6 +2078,7 @@ packages:
 
   '@ungap/structured-clone@1.3.0':
     resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+    deprecated: Potential CWE-502 - Update to 1.3.1 or higher
 
   '@vitest/expect@2.1.9':
     resolution: {integrity: sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==}
@@ -3064,6 +3071,9 @@ packages:
   hast-util-format@1.1.0:
     resolution: {integrity: sha512-yY1UDz6bC9rDvCWHpx12aIBGRG7krurX0p0Fm6pT547LwDIZZiNr8a+IHDogorAdreULSEzP82Nlv5SZkHZcjA==}
 
+  hast-util-from-html@2.0.1:
+    resolution: {integrity: sha512-RXQBLMl9kjKVNkJTIO6bZyb2n+cUH8LFaSSzo82jiLT6Tfc+Pt7VQCS+/h3YwG4jaNE2TA2sdJisGWR+aJrp0g==}
+
   hast-util-from-html@2.0.3:
     resolution: {integrity: sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw==}
 
@@ -3195,6 +3205,10 @@ packages:
   iron-webcrypto@1.2.1:
     resolution: {integrity: sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==}
 
+  is-absolute-url@4.0.1:
+    resolution: {integrity: sha512-/51/TKE88Lmm7Gc4/8btclNXWS+g50wXhYJq8HWIBAGUBnoAdRu1aXeh364t/O7wXDAcTJDP8PNuNKWUDWie+A==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   is-alphabetical@2.0.1:
     resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
 
@@ -3886,6 +3900,10 @@ packages:
     resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==}
     engines: {node: '>=8.6'}
 
+  picomatch@4.0.2:
+    resolution: {integrity: sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==}
+    engines: {node: '>=12'}
+
   picomatch@4.0.4:
     resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
@@ -4294,6 +4312,13 @@ packages:
   stackback@0.0.2:
     resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
 
+  starlight-links-validator@0.13.4:
+    resolution: {integrity: sha512-LdmLbJyPHVrSUhcuxiP3pJNnW8zRcOg/32C996Ic0LOCKbB8vylqHLvAMdIhT67FvEV4eAROun+2wTVU2J156A==}
+    engines: {node: '>=18.14.1'}
+    peerDependencies:
+      '@astrojs/starlight': '>=0.15.0'
+      astro: '>=4.0.0'
+
   std-env@3.10.0:
     resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
 
@@ -4562,6 +4587,9 @@ packages:
   unist-util-visit-parents@6.0.2:
     resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
 
+  unist-util-visit@5.0.0:
+    resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==}
+
   unist-util-visit@5.1.0:
     resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
 
@@ -6984,6 +7012,8 @@ snapshots:
 
   '@types/parse-json@4.0.2': {}
 
+  '@types/picomatch@2.3.3': {}
+
   '@types/sarif@2.1.7': {}
 
   '@types/sax@1.2.7':
@@ -8230,6 +8260,15 @@ snapshots:
       html-whitespace-sensitive-tag-names: 3.0.1
       unist-util-visit-parents: 6.0.2
 
+  hast-util-from-html@2.0.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      devlop: 1.1.0
+      hast-util-from-parse5: 8.0.3
+      parse5: 7.3.0
+      vfile: 6.0.3
+      vfile-message: 4.0.3
+
   hast-util-from-html@2.0.3:
     dependencies:
       '@types/hast': 3.0.4
@@ -8475,6 +8514,8 @@ snapshots:
 
   iron-webcrypto@1.2.1: {}
 
+  is-absolute-url@4.0.1: {}
+
   is-alphabetical@2.0.1: {}
 
   is-alphanumerical@2.0.1:
@@ -9490,6 +9531,8 @@ snapshots:
 
   picomatch@2.3.1: {}
 
+  picomatch@4.0.2: {}
+
   picomatch@4.0.4: {}
 
   pidtree@0.6.0: {}
@@ -10081,6 +10124,20 @@ snapshots:
 
   stackback@0.0.2: {}
 
+  starlight-links-validator@0.13.4(@astrojs/starlight@0.30.6(astro@5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3)))(astro@5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3)):
+    dependencies:
+      '@astrojs/starlight': 0.30.6(astro@5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3))
+      '@types/picomatch': 2.3.3
+      astro: 5.18.1(@azure/identity@4.13.1)(@types/node@22.19.17)(rollup@4.60.2)(typescript@5.9.3)(yaml@2.8.3)
+      github-slugger: 2.0.0
+      hast-util-from-html: 2.0.1
+      hast-util-has-property: 3.0.0
+      is-absolute-url: 4.0.1
+      kleur: 4.1.5
+      mdast-util-to-string: 4.0.0
+      picomatch: 4.0.2
+      unist-util-visit: 5.0.0
+
   std-env@3.10.0: {}
 
   stream-replace-string@2.0.0: {}
@@ -10349,6 +10406,12 @@ snapshots:
       '@types/unist': 3.0.3
       unist-util-is: 6.0.1
 
+  unist-util-visit@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
   unist-util-visit@5.1.0:
     dependencies:
       '@types/unist': 3.0.3
diff --git a/scripts/generate-doc-snippets.mjs b/scripts/generate-doc-snippets.mjs
new file mode 100644
index 00000000..2e2176be
--- /dev/null
+++ b/scripts/generate-doc-snippets.mjs
@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Extracts `#region docs:<label> … #endregion` ranges from example source
+ * into standalone fenced-markdown snippet files under
+ * `dist/examples/docs/snippets/`. The `examples` half of the doc-snippet
+ * pipeline: the `docs:sync-snippets` target consumes this `dist` output and
+ * splices each snippet into the tutorials. The two projects communicate ONLY
+ * through this artifact — `docs` never reaches into `examples/` source
+ * directly.
+ *
+ * Contract:
+ *   - A doc-region is any `#region docs:<label>` (C#) or `# region docs:<label>`
+ *     (Python comment form) paired with a matching `#endregion`. Region
+ *     nesting is tracked by depth, so an inner `#region Constructors` inside
+ *     a doc-region closes correctly.
+ *   - `<label>` is GLOBALLY UNIQUE across all examples. Two regions sharing a
+ *     label collide on the same output filename — this script fails with both
+ *     source locations, which IS the uniqueness lint (no separate check).
+ *   - The emitted snippet is the region body with ALL `#region`/`#endregion`
+ *     lines removed (fold markers are editor noise, not tutorial code),
+ *     dedented to the common minimum indentation, and blank-trimmed.
+ *   - The fence language is chosen from the source extension (.cs → csharp,
+ *     .py → python) — `examples` owns the language; the docs side stays
+ *     ignorant of it.
+ *
+ * Output: `dist/examples/docs/snippets/docs-<label>.md`, one fenced block
+ * each. The `:` in the `docs:<label>` token is sanitized to `-` for the
+ * filename; the token itself stays `docs:<label>` in source and sentinels.
+ *
+ * `#region` is a compile-time no-op, so nothing here affects whether the
+ * examples build or run.
+ */
+
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const OUT_DIR = join(ROOT, 'dist', 'examples', 'docs', 'snippets');
+
+// Scan roots: the two non-archived example groups.
+const SCAN_GROUPS = ['examples/starter', 'examples/advanced'];
+const EXCLUDE_DIR = new Set(['bin', 'obj', 'Metadata', 'node_modules']);
+const LANG_BY_EXT = { '.cs': 'csharp', '.py': 'python' };
+
+// `#region docs:<label>` / `# region docs:<label>` — tolerates the optional
+// space after `#` so the Python comment form works too.
+const REGION_OPEN_RE = /^\s*#\s*region\s+(docs:\S+)\s*$/;
+const REGION_ANY_OPEN_RE = /^\s*#\s*region\b/;
+const REGION_CLOSE_RE = /^\s*#\s*endregion\b/;
+
+function walk(dir, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (EXCLUDE_DIR.has(entry.name)) continue;
+      walk(full, out);
+    } else if (entry.isFile()) {
+      const ext = entry.name.slice(entry.name.lastIndexOf('.'));
+      if (LANG_BY_EXT[ext]) out.push(full);
+    }
+  }
+  return out;
+}
+
+function extractRegions(file) {
+  const lines = readFileSync(file, 'utf8').replace(/\r\n/g, '\n').split('\n');
+  const regions = [];
+  // Stack of ALL open regions (doc and non-doc). Every region marker line is
+  // dropped; every content line is appended to ALL currently-open DOC region
+  // bodies — so nested doc-regions each accumulate their own snippet (the
+  // inner gets its lines; the outer gets the inner's lines too, minus markers).
+  const stack = [];
+  for (let n = 0; n < lines.length; n++) {
+    const line = lines[n];
+    const open = REGION_OPEN_RE.exec(line);
+    if (open) {
+      stack.push({ doc: true, label: open[1], startLine: n + 1, body: [] });
+      continue; // drop the marker line
+    }
+    if (REGION_ANY_OPEN_RE.test(line)) {
+      stack.push({ doc: false }); // e.g. `#region Constructors`
+      continue;
+    }
+    if (REGION_CLOSE_RE.test(line)) {
+      const closed = stack.pop();
+      if (!closed) {
+        throw new Error(
+          `Unmatched '#endregion' in ${relative(ROOT, file)}:${n + 1}`,
+        );
+      }
+      if (closed.doc) {
+        regions.push({
+          label: closed.label,
+          file,
+          startLine: closed.startLine,
+          endLine: n + 1,
+          body: closed.body,
+        });
+      }
+      continue; // drop the marker line
+    }
+    for (const region of stack) {
+      if (region.doc) region.body.push(line);
+    }
+  }
+  if (stack.length) {
+    const open = stack.find((r) => r.doc) ?? stack[0];
+    throw new Error(
+      `Unterminated '#region${open.label ? ' ' + open.label : ''}' in `
+        + `${relative(ROOT, file)}:${open.startLine ?? '?'}`,
+    );
+  }
+  return regions;
+}
+
+// Strip the common leading whitespace from a block of lines, ignoring blank
+// lines when computing the minimum, and trim leading/trailing blank lines.
+function dedent(lines) {
+  const trimmed = [...lines];
+  while (trimmed.length && trimmed[0].trim() === '') trimmed.shift();
+  while (trimmed.length && trimmed[trimmed.length - 1].trim() === '') {
+    trimmed.pop();
+  }
+  let min = Infinity;
+  for (const line of trimmed) {
+    if (line.trim() === '') continue;
+    const indent = line.length - line.trimStart().length;
+    if (indent < min) min = indent;
+  }
+  if (!Number.isFinite(min) || min === 0) return trimmed;
+  return trimmed.map((line) => (line.trim() === '' ? '' : line.slice(min)));
+}
+
+function main() {
+  const files = [];
+  for (const group of SCAN_GROUPS) walk(join(ROOT, group), files);
+  files.sort();
+
+  // label → region. Collision is the global-uniqueness lint.
+  const byLabel = new Map();
+  for (const file of files) {
+    for (const region of extractRegions(file)) {
+      const prior = byLabel.get(region.label);
+      if (prior) {
+        console.error(
+          `[generate-doc-snippets] duplicate region '${region.label}':\n`
+            + `  ${relative(ROOT, prior.file)}:${prior.startLine}\n`
+            + `  ${relative(ROOT, region.file)}:${region.startLine}\n`
+            + `Region labels must be globally unique.`,
+        );
+        process.exit(1);
+      }
+      byLabel.set(region.label, region);
+    }
+  }
+
+  rmSync(OUT_DIR, { recursive: true, force: true });
+  mkdirSync(OUT_DIR, { recursive: true });
+
+  for (const [label, region] of [...byLabel].sort()) {
+    const ext = region.file.slice(region.file.lastIndexOf('.'));
+    const lang = LANG_BY_EXT[ext];
+    const code = dedent(region.body).join('\n');
+    const fenced = `\`\`\`${lang}\n${code}\n\`\`\`\n`;
+    const fileName = `${label.replace(/:/g, '-')}.md`;
+    writeFileSync(join(OUT_DIR, fileName), fenced, 'utf8');
+  }
+
+  console.log(
+    `[generate-doc-snippets] ${byLabel.size} snippet(s) → ${relative(ROOT, OUT_DIR)}`,
+  );
+}
+
+main();
diff --git a/scripts/lint-doc-links.mjs b/scripts/lint-doc-links.mjs
new file mode 100644
index 00000000..7d3d3533
--- /dev/null
+++ b/scripts/lint-doc-links.mjs
@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Deterministic internal-link audit for hand-authored docs. The merge-gating
+ * link check (docs:_test:link-audit) — a PURE function of the docs source, so
+ * NX caches it honestly and it returns the same result locally and in CI,
+ * unlike the Starlight build validator (incremental-cache-sensitive, and it
+ * skips relative links entirely under errorOnRelativeLinks:false).
+ *
+ * Link convention (enforced here, resolved by the ingest interceptor):
+ *   - REPO-ROOT-ANCHORED (`/docs/...`, `/src/...`, `/CONTRIBUTING.md`): the
+ *     target must exist — a docs page for `/docs/...`, a real repo file/dir
+ *     otherwise (the ingest interceptor rewrites the latter to a GitHub URL).
+ *   - FILE-LOCAL DOWNWARD (`sibling.md`, `sub/page.md`, `./x.md`): resolves
+ *     relative to the file; the target page must exist.
+ *   - UPWARD `..` IS BANNED. It's the fragile, ambiguous form (how many levels?
+ *     breaks on move) — anchor at the repo root instead. Both allowed forms
+ *     render correctly on GitHub *and* on the deployed site.
+ *   - External (http/https/mailto) and pure-anchor (#x) links are skipped.
+ *   - Links inside fenced or inline code are ignored.
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, resolve, relative, posix } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const SECTIONS = ['docs/tutorials', 'docs/guides', 'docs/explanation'];
+const LINK_RE = /\]\(([^)]+)\)/g;
+
+function walk(dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) walk(full, out);
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+function maskCode(s) {
+  return s
+    .replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/`[^`\n]*`/g, (m) => m.replace(/./g, ' '));
+}
+
+// Does a path resolve to a real Starlight page? (exact .md file, dir/index.md, or name.md)
+function pageExists(abs) {
+  if (existsSync(abs) && statSync(abs).isFile()) return true;
+  if (existsSync(join(abs, 'index.md'))) return true;
+  if (existsSync(`${abs}.md`)) return true;
+  return false;
+}
+
+function main() {
+  const files = SECTIONS.flatMap((s) => walk(join(ROOT, s)));
+  const broken = [];
+
+  for (const file of files) {
+    const body = maskCode(readFileSync(file, 'utf8'));
+    const rel = relative(ROOT, file);
+    for (const m of body.matchAll(LINK_RE)) {
+      const full = m[1].trim().split(/\s+/)[0]; // drop link title
+      const target = full.split('#')[0]; // drop anchor
+      if (!target) continue; // pure anchor (#section)
+      if (/^(https?:|mailto:|tel:|\/\/)/i.test(full)) continue; // external
+
+      if (target.includes('../')) {
+        broken.push({ rel, target, why: 'uses `..` — anchor at the repo root (/…) or use a file-local downward path' });
+      } else if (target.startsWith('/')) {
+        const repoRel = posix.normalize(target.replace(/^\/+/, ''));
+        const inDocs = repoRel === 'docs' || repoRel.startsWith('docs/');
+        if (inDocs && !pageExists(resolve(ROOT, repoRel))) {
+          broken.push({ rel, target, why: 'docs page does not exist (renamed or typo?)' });
+        } else if (!inDocs && !existsSync(resolve(ROOT, repoRel))) {
+          broken.push({ rel, target, why: 'repo path does not exist (source link)' });
+        }
+      } else if (!pageExists(resolve(dirname(file), target))) {
+        broken.push({ rel, target, why: 'target page does not exist (renamed or typo?)' });
+      }
+    }
+  }
+
+  if (broken.length) {
+    console.error(`[lint-doc-links] ${broken.length} bad internal link(s):\n`);
+    for (const b of broken) console.error(`  ${b.rel}\n     → ${b.target}   [${b.why}]`);
+    console.error('\nLinks must be repo-root-anchored (/…) or file-local downward (no `..`), and resolve.');
+    process.exit(1);
+  }
+  console.log(`[lint-doc-links] ${files.length} page(s) scanned, all internal links valid. ✓`);
+}
+
+main();
diff --git a/scripts/lint-docs-warnings.mjs b/scripts/lint-docs-warnings.mjs
new file mode 100644
index 00000000..e1d4292d
--- /dev/null
+++ b/scripts/lint-docs-warnings.mjs
@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Non-blocking documentation warnings for user-facing markdown. Emits to
+ * stdout and, when running under GitHub Actions, to the step summary
+ * ($GITHUB_STEP_SUMMARY) so warnings surface in the PR Checks UI WITHOUT
+ * failing the check. Always exits 0 — these are pre-flight warnings, not gates.
+ *
+ * Two warning families share this one surface (one harness, not two):
+ *
+ *   1. Terminology — uses of a glossary `_Avoid_:` term where canonical
+ *      Flowthru vocabulary is expected. The {avoid → canonical} map is parsed
+ *      mechanically from examples/CONTRIBUTING.md (the Flow/Catalog Developer
+ *      glossary — the most end-user-facing view). Case-insensitive, whole-word,
+ *      skips fenced code blocks and inline code, and never flags the glossary's
+ *      own `_Avoid_:` lines.
+ *
+ *   2. Review state — pages whose `review:` frontmatter is not `reviewed`
+ *      (absent counts as `draft`). Flags content a human has not yet signed off
+ *      on. See the docs review-provenance decision.
+ *
+ * MVP note: a STOPLIST suppresses avoid-terms that are common English words
+ * (`type`, `model`, `node`, …). Flagging those mechanically buries the
+ * high-signal hits (`pipeline` → Flow). The stoplist is logged on every run —
+ * never a silent cap — and is the obvious curation knob for promoting this
+ * lint toward a gate once the corpus is cleaned.
+ */
+
+import { readdirSync, readFileSync, existsSync, appendFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const GLOSSARY = join(ROOT, 'examples', 'CONTRIBUTING.md');
+const DOC_SECTIONS = ['docs/tutorials', 'docs/guides', 'docs/explanation'];
+// reference/src is generated from C# XML docs; reference/misc/external is
+// vendored third-party source. Neither is human-authored Flowthru prose.
+const SKIP_PATH = /\/reference\/(src|misc\/external)\//;
+
+// Avoid-terms too generic to flag mechanically at MVP. Logged on every run.
+const STOPLIST = new Set([
+  'type', 'model', 'node', 'task', 'job', 'config', 'settings', 'slot',
+  'zone', 'tier', 'operator', 'dto', 'repository', 'data source',
+]);
+
+// ── Parse {avoid → canonical} from the glossary's `_Avoid_:` lines ──
+function parseAvoidMap() {
+  const lines = readFileSync(GLOSSARY, 'utf8').split('\n');
+  const map = new Map(); // avoidTerm(lower) → canonical
+  let canonical = null;
+  const TERM_RE = /^\*\*(.+?)\*\*:/; // **Flow**: …
+  const AVOID_RE = /^_Avoid_:\s*(.+)$/;
+  for (const line of lines) {
+    const t = TERM_RE.exec(line.trim());
+    if (t) { canonical = t[1].trim(); continue; }
+    const a = AVOID_RE.exec(line.trim());
+    if (a && canonical) {
+      for (let term of a[1].split(',')) {
+        term = term.replace(/\(.*$/, '').trim().toLowerCase(); // drop parenthetical
+        if (!term) continue;
+        if (STOPLIST.has(term)) continue;
+        if (!map.has(term)) map.set(term, canonical);
+      }
+    }
+  }
+  return map;
+}
+
+function walk(dir, out) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (SKIP_PATH.test(full.split('\\').join('/'))) continue;
+    if (e.isDirectory()) walk(full, out);
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+// Blank out fenced code blocks and inline code so matches inside them are
+// ignored, while preserving line numbers (replace with spaces, keep newlines).
+function maskCode(content) {
+  let masked = content.replace(/```[\s\S]*?```/g, (m) =>
+    m.replace(/[^\n]/g, ' '),
+  );
+  masked = masked.replace(/`[^`\n]*`/g, (m) => m.replace(/./g, ' '));
+  return masked;
+}
+
+function frontmatterReview(content) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+  if (!m) return 'draft'; // no frontmatter → treat as draft
+  const r = /^review:\s*(\S+)/m.exec(m[1]);
+  return r ? r[1].trim() : 'draft';
+}
+
+function main() {
+  const avoidMap = parseAvoidMap();
+  const files = [];
+  for (const s of DOC_SECTIONS) walk(join(ROOT, s), files);
+  files.sort();
+
+  const termHits = []; // { file, line, term, canonical }
+  const drafts = []; // file
+  const termTotals = new Map();
+
+  for (const file of files) {
+    const raw = readFileSync(file, 'utf8');
+    const rel = relative(ROOT, file);
+    if (frontmatterReview(raw) !== 'reviewed') drafts.push(rel);
+
+    const masked = maskCode(raw).split('\n');
+    for (let i = 0; i < masked.length; i++) {
+      const lineText = masked[i];
+      for (const [term, canonical] of avoidMap) {
+        const re = new RegExp(`\\b${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi');
+        if (re.test(lineText)) {
+          termHits.push({ file: rel, line: i + 1, term, canonical });
+          termTotals.set(term, (termTotals.get(term) ?? 0) + 1);
+        }
+      }
+    }
+  }
+
+  // ── Render ──
+  const out = [];
+  out.push('# Documentation warnings\n');
+  out.push(`_Non-blocking. ${files.length} page(s) scanned. `
+    + `Stoplisted generic avoid-terms (not flagged): ${[...STOPLIST].sort().join(', ')}._\n`);
+
+  out.push(`## Terminology — ${termHits.length} hit(s)\n`);
+  if (termHits.length) {
+    out.push('| File | Line | Avoid | Use instead |');
+    out.push('| --- | --- | --- | --- |');
+    for (const h of termHits) {
+      out.push(`| ${h.file} | ${h.line} | \`${h.term}\` | **${h.canonical}** |`);
+    }
+    out.push('');
+  } else {
+    out.push('None. ✓\n');
+  }
+
+  out.push(`## Review state — ${drafts.length} page(s) not \`reviewed\`\n`);
+  if (drafts.length) {
+    for (const f of drafts) out.push(`- ${f}`);
+    out.push('');
+  } else {
+    out.push('All scanned pages are `reviewed`. ✓\n');
+  }
+
+  const report = out.join('\n');
+  process.stdout.write(report + '\n');
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    appendFileSync(process.env.GITHUB_STEP_SUMMARY, report + '\n');
+  }
+  // Pre-flight warning surface — never fails the check.
+  process.exit(0);
+}
+
+main();
diff --git a/scripts/sync-doc-snippets.mjs b/scripts/sync-doc-snippets.mjs
new file mode 100644
index 00000000..eabeaa11
--- /dev/null
+++ b/scripts/sync-doc-snippets.mjs
@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * Splices example code snippets into the docs. The `docs` half of the
+ * doc-snippet pipeline: consumes the fenced snippet files produced by
+ * `examples:generate-snippets` under `dist/examples/docs/snippets/` and
+ * populates them into `docs/{tutorials,guides,explanation}/**​/*.md`.
+ *
+ * Authoring: drop a one-line sentinel where the code should appear —
+ *   <!-- flowthru:snippet docs:<label> -->
+ * On first run it is expanded IN PLACE into a managed block:
+ *   <!-- flowthru:snippet:docs:<label>:start -->
+ *   ```csharp … ```
+ *   <!-- flowthru:snippet:docs:<label>:end -->
+ * On later runs the block body is refreshed from `dist`. Same managed-block
+ * mechanism as scripts/update-example-readmes.mjs.
+ *
+ * Honesty (both HARD-FAIL, atomic — nothing is written if either trips):
+ *   - missing token: a sentinel references a `docs:<label>` with no snippet in
+ *     `dist` (the source region was deleted/renamed). Doc points at code that
+ *     no longer exists.
+ *   - orphan snippet: a `dist` snippet no sentinel or block ever references
+ *     (a `#region docs:` marking code that documents nothing).
+ * Freshness — a C# edit that wasn't re-synced — is caught separately by
+ * `git diff --exit-code docs/` in CI, per the sync-readmes precedent.
+ *
+ * The source of truth is the C# source; this script only ever transcribes it.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, '..');
+const SNIPPET_DIR = join(ROOT, 'dist', 'examples', 'docs', 'snippets');
+const DOC_SECTIONS = ['docs/tutorials', 'docs/guides', 'docs/explanation'];
+
+const SENTINEL_RE = /<!-- flowthru:snippet (docs:[\w.-]+) -->/g;
+const BLOCK_START_RE = /<!-- flowthru:snippet:(docs:[\w.-]+):start -->/g;
+
+function fileNameForToken(token) {
+  return `${token.replace(/:/g, '-')}.md`;
+}
+function tokenForFileName(name) {
+  // docs-<slug>.md → docs:<slug>  (only the prefix separator was sanitized)
+  return name.replace(/\.md$/, '').replace('-', ':');
+}
+function startMarker(token) {
+  return `<!-- flowthru:snippet:${token}:start -->`;
+}
+function endMarker(token) {
+  return `<!-- flowthru:snippet:${token}:end -->`;
+}
+function wrapBlock(token, payload) {
+  return `${startMarker(token)}\n${payload.trimEnd()}\n${endMarker(token)}`;
+}
+
+function walk(dir, out) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+function loadSnippets() {
+  const map = new Map(); // token → fenced payload
+  if (!existsSync(SNIPPET_DIR)) return map;
+  for (const name of readdirSync(SNIPPET_DIR)) {
+    if (!name.endsWith('.md')) continue;
+    map.set(
+      tokenForFileName(name),
+      readFileSync(join(SNIPPET_DIR, name), 'utf8'),
+    );
+  }
+  return map;
+}
+
+// All tokens referenced by a file, from both bare sentinels and the start
+// markers of already-expanded managed blocks.
+function referencedTokens(content) {
+  const tokens = new Set();
+  for (const m of content.matchAll(SENTINEL_RE)) tokens.add(m[1]);
+  for (const m of content.matchAll(BLOCK_START_RE)) tokens.add(m[1]);
+  return tokens;
+}
+
+function refreshBlocks(content, snippets) {
+  let out = content;
+  for (const m of [...content.matchAll(BLOCK_START_RE)]) {
+    const token = m[1];
+    const start = startMarker(token);
+    const end = endMarker(token);
+    const sIdx = out.indexOf(start);
+    if (sIdx === -1) continue;
+    const eIdx = out.indexOf(end, sIdx + start.length);
+    if (eIdx === -1) continue;
+    const before = out.slice(0, sIdx);
+    const after = out.slice(eIdx + end.length);
+    out = `${before}${wrapBlock(token, snippets.get(token))}${after}`;
+  }
+  return out;
+}
+
+function expandSentinels(content, snippets) {
+  return content.replace(SENTINEL_RE, (_full, token) =>
+    wrapBlock(token, snippets.get(token)),
+  );
+}
+
+function main() {
+  // --check: non-mutating freshness mode for the docs:_test:snippet-freshness
+  // target. Computes what each doc WOULD become and fails if any differs from
+  // its committed state, writing nothing — so it leaves no working-tree side
+  // effects and never false-positives on a dev's unrelated local edits.
+  const check = process.argv.includes('--check');
+  const snippets = loadSnippets();
+  const docFiles = [];
+  for (const section of DOC_SECTIONS) walk(join(ROOT, section), docFiles);
+  docFiles.sort();
+
+  // ── Lint pass (before any write) ──
+  const referenced = new Set();
+  const missing = []; // { file, token }
+  for (const file of docFiles) {
+    const content = readFileSync(file, 'utf8');
+    for (const token of referencedTokens(content)) {
+      referenced.add(token);
+      if (!snippets.has(token)) {
+        missing.push({ file: relative(ROOT, file), token });
+      }
+    }
+  }
+  const orphans = [...snippets.keys()].filter((t) => !referenced.has(t)).sort();
+
+  if (missing.length || orphans.length) {
+    if (missing.length) {
+      console.error('[sync-doc-snippets] references with no snippet in dist:');
+      for (const { file, token } of missing) {
+        console.error(`  ${file}: ${token}  (region deleted or renamed?)`);
+      }
+    }
+    if (orphans.length) {
+      console.error(
+        '[sync-doc-snippets] orphan snippets — #region docs: with no reference:',
+      );
+      for (const token of orphans) console.error(`  ${token}`);
+    }
+    console.error('Nothing written. Fix the regions/sentinels and re-run.');
+    process.exit(1);
+  }
+
+  // ── Write / check pass ──
+  const stale = [];
+  let changed = 0;
+  for (const file of docFiles) {
+    const original = readFileSync(file, 'utf8');
+    const next = expandSentinels(refreshBlocks(original, snippets), snippets);
+    if (next === original) continue;
+    if (check) {
+      stale.push(relative(ROOT, file));
+    } else {
+      writeFileSync(file, next, 'utf8');
+      changed++;
+      console.log(`  updated ${relative(ROOT, file)}`);
+    }
+  }
+
+  if (check) {
+    if (stale.length) {
+      console.error('[sync-doc-snippets] stale doc snippets — re-run `nx run docs:sync-snippets`:');
+      for (const f of stale) console.error(`  ${f}`);
+      process.exit(1);
+    }
+    console.log(`[sync-doc-snippets] ${snippets.size} snippet(s) in sync. ✓`);
+    return;
+  }
+
+  console.log(
+    `[sync-doc-snippets] ${snippets.size} snippet(s), ${referenced.size} referenced, ${changed} file(s) updated`,
+  );
+}
+
+main();
diff --git a/src/website/.gitignore b/src/website/.gitignore
index a3e42a02..8826e031 100644
--- a/src/website/.gitignore
+++ b/src/website/.gitignore
@@ -3,8 +3,11 @@ dist/
 .astro/
 
 # Generated by scripts/ingest-docs.mjs from the canonical docs/ directory.
-# index.mdx is hand-authored and stays under version control.
-src/content/docs/docs/
+# index.mdx is hand-authored and stays under version control. Exclude the
+# directory *contents* (trailing /*) rather than the directory itself, so the
+# negation below can re-include index.mdx — Git cannot re-include a file whose
+# parent directory is excluded.
+src/content/docs/docs/*
 !src/content/docs/docs/index.mdx
 
 # Node
diff --git a/src/website/astro.config.mjs b/src/website/astro.config.mjs
index f56615f0..9e3dba5c 100644
--- a/src/website/astro.config.mjs
+++ b/src/website/astro.config.mjs
@@ -3,6 +3,7 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
+import starlightLinksValidator from "starlight-links-validator";
 
 // https://astro.build/config
 //
@@ -34,6 +35,12 @@ export default defineConfig({
       title: "Flowthru",
       description:
         "A type-safe, fail-fast data engineering framework for .NET.",
+      // Fail the build on broken internal links / anchors — design-time
+      // documentation honesty. External link rot is handled out-of-band by
+      // the scheduled docs-external-links workflow, so it's not checked here.
+      // errorOnRelativeLinks:false allows relative links (which the tutorial
+      // chapters and section landings use) while still validating they resolve.
+      plugins: [starlightLinksValidator({ errorOnRelativeLinks: false })],
       logo: {
         src: "./src/assets/flowthru-mark.svg",
         replacesTitle: false,
diff --git a/src/website/package.json b/src/website/package.json
index 1dcaf70c..c454eab1 100644
--- a/src/website/package.json
+++ b/src/website/package.json
@@ -13,6 +13,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
+    "starlight-links-validator": "^0.13",
     "yaml": "^2.8.0"
   },
   "engines": {
diff --git a/src/website/project.json b/src/website/project.json
index fc0a50e7..8d951055 100644
--- a/src/website/project.json
+++ b/src/website/project.json
@@ -55,7 +55,7 @@
       }
     },
     "build": {
-      "//": "Inputs include the *source* docs (not the ingested copy at src/content/docs/docs/) — Nx hashes inputs at the start of a run, before the upstream ingest produces the new copy on disk, so listing the originals is what actually invalidates this cache when docs change.",
+      "//": "Inputs include the *source* docs (not the ingested copy at src/content/docs/docs/) — Nx hashes inputs at the start of a run, before the upstream ingest produces the new copy on disk, so listing the originals is what actually invalidates this cache when docs change. Runs `astro build --force` to clear Astro's content-layer cache (node_modules/.astro) every build: that cache is hidden state Nx can't see, and the Starlight link validator runs as a build hook — incremental renders skip pages and the validator skips them too, so a cached build could pass broken links Nx then memoizes. --force makes the build a pure function of its inputs (deterministic; cache-safe). Dev uses the serve target, which keeps incremental rendering.",
       "executor": "nx:run-commands",
       "cache": true,
       "inputs": [
@@ -78,7 +78,7 @@
       "outputs": [ "{projectRoot}/dist" ],
       "dependsOn": [ "site:_lint-docs" ],
       "options": {
-        "command": "astro build",
+        "command": "astro build --force",
         "cwd": "src/website"
       }
     },
diff --git a/src/website/scripts/ingest-docs.mjs b/src/website/scripts/ingest-docs.mjs
index 35aee482..29adc8be 100644
--- a/src/website/scripts/ingest-docs.mjs
+++ b/src/website/scripts/ingest-docs.mjs
@@ -26,7 +26,8 @@
 // `<repo>/docs` when run from `src/website`.
 
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -55,6 +56,86 @@ function isExcluded(absPath) {
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 const DOCFX_ANCHOR_RE = /<a\s+id="[^"]*"\s*><\/a>\s*/gi;
 
+// ── Internal-link interceptor ────────────────────────────────────────
+// Rewrites markdown links on their way into the Starlight content tree so they
+// resolve on the deployed site regardless of how an author wrote them:
+//   - resolves INSIDE docs/ → site-internal. Root-anchored `/docs/...` links
+//     get the Astro base prefix + slug normalisation; file-relative links are
+//     left untouched for Astro to resolve.
+//   - ESCAPES docs/ (repo source: src/, examples/, CONTRIBUTING.md, …) →
+//     rewritten to an absolute GitHub URL (blob for files, tree for dirs), so a
+//     contributor page can reference source with a natural relative path and
+//     still render correctly both on GitHub and on the deployed site.
+// Links inside fenced or inline code are never touched. The companion lint
+// (docs:_test:link-audit) enforces the authoring *style*; this makes any style
+// resolve correctly, so site-correctness doesn't depend on the migration.
+const REPO_ROOT = resolve(DOCS_SRC, "..");
+const GH = "https://github.com/chaoticgoodcomputing/flowthru";
+const GH_BRANCH = "main"; // docs deploy ref; mirrors the released docs
+const SITE_BASE = (() => {
+  try {
+    const cfg = readFileSync(resolve(PROJECT_ROOT, "astro.config.mjs"), "utf8");
+    const m = /base:\s*["']([^"']+)["']/.exec(cfg);
+    return (m ? m[1] : "/flowthru").replace(/\/+$/, "");
+  } catch {
+    return "/flowthru";
+  }
+})();
+
+function rewriteOneLink(url, relPath) {
+  if (/^(?:[a-z][a-z0-9+.-]*:|#|\/\/)/i.test(url)) return url; // external / anchor-only / protocol-relative
+  const hash = url.indexOf("#");
+  const path = hash >= 0 ? url.slice(0, hash) : url;
+  const anchor = hash >= 0 ? url.slice(hash) : "";
+  if (!path) return url;
+
+  let repoRel;
+  if (path.startsWith("/")) {
+    repoRel = posix.normalize(path.slice(1)); // repo-root-anchored
+  } else {
+    const fileDir = posix.dirname(relPath.split(sep).join("/"));
+    repoRel = posix.normalize(posix.join("docs", fileDir, path));
+  }
+  const clean = repoRel.replace(/\/+$/, "");
+  const inDocs = clean === "docs" || clean.startsWith("docs/");
+
+  if (inDocs) {
+    if (!path.startsWith("/")) return url; // relative in-docs link — Astro resolves it
+    const slug = clean.replace(/\.md$/, "").replace(/\/index$/, "");
+    return `${SITE_BASE}/${slug}/${anchor}`;
+  }
+
+  // Escapes docs/ → GitHub source URL.
+  let isDir = false;
+  try {
+    isDir = existsSync(resolve(REPO_ROOT, clean)) && statSync(resolve(REPO_ROOT, clean)).isDirectory();
+  } catch {
+    /* unresolved on disk — default to blob */
+  }
+  return `${GH}/${isDir ? "tree" : "blob"}/${GH_BRANCH}/${clean}${anchor}`;
+}
+
+function rewriteLinks(body, relPath) {
+  const fences = [];
+  let s = body.replace(/```[\s\S]*?```/g, (m) => {
+    fences.push(m);
+    return `@@FTSNIP_F${fences.length - 1}@@`;
+  });
+  const inlines = [];
+  s = s.replace(/`[^`\n]*`/g, (m) => {
+    inlines.push(m);
+    return `@@FTSNIP_I${inlines.length - 1}@@`;
+  });
+  s = s.replace(/\]\(([^)]+)\)/g, (full, inner) => {
+    const sp = inner.match(/^(\S+)(\s.*)?$/);
+    if (!sp) return full;
+    return `](${rewriteOneLink(sp[1], relPath)}${sp[2] || ""})`;
+  });
+  s = s.replace(/@@FTSNIP_I(\d+)@@/g, (_m, i) => inlines[+i]);
+  s = s.replace(/@@FTSNIP_F(\d+)@@/g, (_m, i) => fences[+i]);
+  return s;
+}
+
 async function walk(dir) {
   const out = [];
   let entries;
@@ -76,10 +157,11 @@ async function walk(dir) {
   return out;
 }
 
-function passthrough(raw) {
+function passthrough(raw, relPath) {
   const match = FRONTMATTER_RE.exec(raw);
   if (!match) return null;
-  const body = raw.slice(match[0].length).replace(DOCFX_ANCHOR_RE, "");
+  let body = raw.slice(match[0].length).replace(DOCFX_ANCHOR_RE, "");
+  body = rewriteLinks(body, relPath);
   return `---\n${match[1]}\n---\n${body}`;
 }
 
@@ -143,7 +225,7 @@ async function ingest() {
       await mkdir(dirname(dest), { recursive: true });
       const raw = await readFile(file, "utf8");
 
-      const passed = passthrough(raw);
+      const passed = passthrough(raw, rel);
       if (passed) {
         await writeFile(dest, passed, "utf8");
         stats.passthrough++;
diff --git a/src/website/src/content/config.ts b/src/website/src/content/config.ts
index 8222ddfa..36f38f3e 100644
--- a/src/website/src/content/config.ts
+++ b/src/website/src/content/config.ts
@@ -6,6 +6,13 @@ import { docsSchema } from "@astrojs/starlight/schema";
 // `description`. The same schema is enforced at lint time by
 // scripts/lint-docs.mjs against ingested output, and again here by Astro
 // during the Starlight build — single source of truth.
+//
+// `review` records whether a human has refined and signed off on the page (not
+// who drafted it). Absent is treated as `draft` so a forgotten field can never
+// read as reviewed. Promotion to `reviewed` is always a manual human action,
+// never automated; any substantive edit flips the page back to `draft`.
+// `draft` status is a non-blocking pre-flight warning, surfaced by the
+// terminology-lint meta-test — never a build gate.
 export const collections = {
   docs: defineCollection({
     schema: docsSchema({
@@ -15,6 +22,7 @@ export const collections = {
             required_error: "Flowthru docs require a 'description' frontmatter field.",
           })
           .min(1, "Frontmatter 'description' must not be empty."),
+        review: z.enum(["draft", "reviewed"]).default("draft"),
       }),
     }),
   }),
diff --git a/src/website/src/content/docs/docs/index.mdx b/src/website/src/content/docs/docs/index.mdx
new file mode 100644
index 00000000..1bc49314
--- /dev/null
+++ b/src/website/src/content/docs/docs/index.mdx
@@ -0,0 +1,50 @@
+---
+title: Flowthru documentation
+description: Tutorials, guides, explanation, and reference for Flowthru — the type-safe, fail-fast data engineering framework for .NET.
+review: draft
+---
+
+import { CardGrid, LinkCard } from "@astrojs/starlight/components";
+
+Flowthru is a type-safe, fail-fast data engineering framework for .NET. You
+describe your data as typed **schemas**, register where each dataset lives in a
+**catalog**, and compose your transformations into **Steps** and **Flows**. In
+return, the compiler and a pre-flight validation pass catch broken wiring —
+a renamed column, a missing dataset, two Steps writing to the same output —
+*before* any data moves.
+
+That guarantee comes from sorting every possible failure into one of three
+moments, and pulling each one as early as it can go:
+
+- **Design-time** — your editor and the build flag the mistake as you type. This is the goal for as much as possible.
+- **Pre-flight** — after the build, before the first Step runs, a validation pass rejects a misconfigured run instead of failing halfway through.
+- **Runtime** — while data is actually moving. This is the moment Flowthru works hardest to keep empty.
+
+**New to Flowthru? Start with the [Spaceflights tutorial](tutorials/spaceflights/).**
+
+The rest of the site is organized along the
+[Diátaxis](https://diataxis.fr) framework — pick the quadrant that matches
+what you're trying to do.
+
+<CardGrid>
+  <LinkCard
+    title="Tutorials"
+    description="Learning-oriented walkthroughs. Start here if you're new to Flowthru."
+    href="tutorials/spaceflights/"
+  />
+  <LinkCard
+    title="Guides"
+    description="Goal-oriented recipes for getting unstuck on a specific task."
+    href="guides/slicing-pipelines/"
+  />
+  <LinkCard
+    title="Explanation"
+    description="The 'why' — design philosophy, primitives, and tradeoffs."
+    href="explanation/anatomy-of-a-flow/"
+  />
+  <LinkCard
+    title="Reference"
+    description="Auto-generated API reference for every public type."
+    href="reference/"
+  />
+</CardGrid>