diff --git a/build-docs.py b/build-docs.py
index 30122c20..91920d98 100644
--- a/build-docs.py
+++ b/build-docs.py
@@ -18,6 +18,10 @@
     --serve         Build and serve locally (English only, for development)
     --skip-gen      Skip running gen_redirects.py (use existing configs)
     --no-api-copy   Skip copying API docs to localized sites
+    --skip-api      Reuse existing content/api instead of regenerating API metadata
+                    (~30-40% faster). LOCAL markdown iteration ONLY, with --serve/--lang;
+                    never for testing, CI/CD, or release builds.
+    --permissive    Don't fail the English build on DocFX warnings (local iteration)
 """
 
 import argparse
@@ -81,6 +85,62 @@ def run_command(cmd: list[str], description: str, check: bool = True, fail_on_wa
     return result.returncode
 
 
+DOCFX: list[str] = []          # cache; populated on first ensure_docfx()
+
+
+def _local_docfx_available() -> bool:
+    """True if a dotnet tool manifest in cwd or an ancestor declares docfx.
+
+    Mirrors dotnet's manifest discovery (cwd upward, `.config/` or legacy path,
+    stop at an isRoot manifest). Filesystem-only — does not verify the tool is
+    restored; a missing restore surfaces as a clear `dotnet docfx` error at build time.
+    """
+    for d in (Path.cwd(), *Path.cwd().parents):
+        manifest = next((m for m in (d / ".config" / "dotnet-tools.json",
+                                      d / "dotnet-tools.json") if m.is_file()), None)
+        if manifest is None:
+            continue
+        try:
+            data = json.loads(manifest.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+        if "docfx" in {k.lower() for k in data.get("tools", {})}:
+            return True
+        if data.get("isRoot"):
+            break  # root manifest without docfx: dotnet stops searching here too
+    return False
+
+
+def resolve_docfx() -> list[str]:
+    """Resolve how to invoke docfx: $DOCFX override, then a repo-pinned local tool
+    (`dotnet docfx`), then a global/PATH `docfx`. Raises if none is available."""
+    override = os.environ.get("DOCFX")
+    if override:
+        return override.split()
+    if shutil.which("dotnet") and _local_docfx_available():
+        return ["dotnet", "docfx"]
+    if shutil.which("docfx"):
+        return ["docfx"]
+    raise SystemExit(
+        "Error: docfx not found.\n"
+        "  Local:  dotnet tool install docfx   (then `dotnet tool restore`)\n"
+        "  Global: dotnet tool install -g docfx"
+    )
+
+
+def ensure_docfx() -> list[str]:
+    """Return the docfx invocation prefix, resolving (and caching) it on first use."""
+    global DOCFX
+    if not DOCFX:
+        DOCFX = resolve_docfx()
+    return DOCFX
+
+
+def run_docfx(args: list[str], description: str, **kwargs) -> int:
+    """Run docfx with the resolved invocation prefix (global/PATH or `dotnet docfx`)."""
+    return run_command([*ensure_docfx(), *args], description, **kwargs)
+
+
 def get_available_languages() -> list[str]:
     """Get list of available languages from metadata/languages.json or scan localizedContent/."""
     manifest_path = Path("metadata/languages.json")
@@ -151,7 +211,7 @@ def prepare_localized_content(lang: str, sync: bool = False) -> int:
     )
 
 
-def build_language(lang: str, sync: bool = False) -> int:
+def build_language(lang: str, sync: bool = False, skip_api: bool = False, permissive: bool = False) -> int:
     """Build documentation for a specific language."""
     config_path = f"localizedContent/{lang}/docfx.json"
 
@@ -164,14 +224,20 @@ def build_language(lang: str, sync: bool = False) -> int:
     result = prepare_localized_content(lang, sync=sync)
     if result != 0:
         return result
-    
+
     # Build the documentation — fail on DocFX warnings only for English (the
     # authored source). Localized content is Crowdin-managed and may carry
-    # translation warnings that must not block deployment.
-    return run_command(
-        ["docfx", config_path],
+    # translation warnings that must not block deployment. `permissive` lifts the
+    # English gate too, for local iteration where transient warnings are expected
+    # (warnings are still printed, just not fatal); full/CI builds leave it off.
+    #
+    # `docfx build` skips API metadata regeneration and reuses the existing
+    # content/api/*.yml (the _apiSource DLLs don't change between content edits),
+    # which is ~30-40% faster; bare `docfx` regenerates metadata then builds.
+    return run_docfx(
+        [*(["build"] if skip_api else []), config_path],
         f"Building {lang} documentation",
-        fail_on_warnings=(lang == "en")
+        fail_on_warnings=(lang == "en" and not permissive)
     )
 
 
@@ -279,7 +345,9 @@ def main() -> int:
     parser.add_argument("--list", action="store_true", help="List available languages")
     parser.add_argument("--serve", action="store_true", help="Build English and serve locally")
     parser.add_argument("--skip-gen", action="store_true", help="Skip gen_redirects.py")
-    parser.add_argument("--no-api-copy", action="store_true", help="Skip copying API docs")
+    parser.add_argument("--no-api-copy", action="store_true", help="Skip copying API docs to localized sites")
+    parser.add_argument("--skip-api", action="store_true", help="LOCAL markdown iteration only (requires --serve/--lang): reuse existing content/api, ~30-40%% faster. NEVER for testing/CI/CD/releases")
+    parser.add_argument("--permissive", action="store_true", help="Don't treat English DocFX warnings as build failures (for local iteration; keep full/CI builds strict)")
     parser.add_argument("--sync", action="store_true", help="Sync English fallback for missing/outdated translations (for local dev)")
     
     args = parser.parse_args()
@@ -292,7 +360,39 @@ def main() -> int:
             suffix = " (default)" if lang == "en" else ""
             print(f"  {lang}{suffix}")
         return 0
-    
+
+    # Resolve docfx now so a missing install exits before any build work happens.
+    ensure_docfx()
+
+    # --skip-api is strictly a fast LOCAL iteration aid for editing markdown: it reuses
+    # the existing content/api/*.yml instead of regenerating API metadata. It must NEVER
+    # be used for full builds, testing, CI/CD, or releases (those must regenerate the API).
+    # Guard it conservatively: require an explicit single-target (--serve or --lang),
+    # forbid --all / the default all-languages build, and require API metadata to already
+    # exist so we never silently ship a site with missing or stale API docs.
+    if args.skip_api:
+        if args.all or not (args.serve or args.lang):
+            print(
+                "Error: --skip-api is for fast LOCAL iteration only and must target a single build.\n"
+                "       Use it with --serve or --lang (e.g. `--serve --skip-api`, `--lang en --skip-api`).\n"
+                "       Never use it for --all, testing, CI/CD, or release builds — omit it so API\n"
+                "       metadata is regenerated.",
+                file=sys.stderr,
+            )
+            return 1
+        if not list(Path("content/api").glob("*.yml")):
+            print(
+                "Error: --skip-api reuses existing API metadata, but content/api/*.yml is missing.\n"
+                "       Run a full build once (e.g. `python3 build-docs.py --lang en`) to generate it.",
+                file=sys.stderr,
+            )
+            return 1
+        print("\n" + "=" * 60)
+        print("  WARNING: --skip-api active — reusing existing content/api/*.yml.")
+        print("  Fast LOCAL markdown iteration ONLY; API docs may be stale.")
+        print("  NEVER use --skip-api for testing, CI/CD, or release builds.")
+        print("=" * 60)
+
     # Run gen_redirects.py first (unless skipped)
     if not args.skip_gen:
         result = run_command(
@@ -315,7 +415,7 @@ def main() -> int:
     
     if args.serve:
         # Build English only and serve
-        result = build_language("en", sync=True)
+        result = build_language("en", sync=True, skip_api=args.skip_api, permissive=args.permissive)
         if result != 0:
             return result
         
@@ -329,8 +429,8 @@ def main() -> int:
             shutil.copy(manifest_src, manifest_dest)
             print("Copied languages.json to _site/en/")
         
-        return run_command(
-            ["docfx", "serve", "_site/en"],
+        return run_docfx(
+            ["serve", "_site/en"],
             "Serving documentation locally"
         )
     
@@ -354,7 +454,7 @@ def main() -> int:
     
     # Build all requested languages
     for lang in build_langs:
-        result = build_language(lang, sync=args.sync)
+        result = build_language(lang, sync=args.sync, skip_api=args.skip_api, permissive=args.permissive)
         if result != 0:
             return result
         
diff --git a/build_scripts/README.md b/build_scripts/README.md
new file mode 100644
index 00000000..bd0a0137
--- /dev/null
+++ b/build_scripts/README.md
@@ -0,0 +1,238 @@
+# Build tools
+
+This document covers new build tools:
+- `te_script_runner.py`: standalone runner and module for other tools that need to execute C# scripts
+- `csharp_doctest.py`: compiles and runs annotated `csharp` code blocks in markdown files
+- `check_links.py`: dead link checker for built site
+
+Existing docfx and localization orchestration can be found in [../README.md](../README.md)
+
+## Prerequisites
+
+Required on PATH:
+
+- `python3` -- 3.10+ (the scripts use 3.10 syntax; validated on 3.14).
+- `uv` -- provides `uvx`, for lint and type-check.
+- `te` -- the Tabular Editor CLI, for the doc-validation scripts; you should use a build aligned with TE3 release for checking docs.
+- `docfx` -- or `dotnet` with the pinned local docfx tool, to build the site.
+
+Run all scripts from the docs repo root;
+paths like `_site` and `content/` resolve relative to the current directory.
+
+## Contributing and development notes
+
+Scripts have no build phase.
+All Python build scripts are linted and type-checked:
+
+```shell
+$ uvx ruff check --select F,B,SIM,I,UP  <python_sources>
+$ uvx mypy --strict  <python_sources>
+```
+
+Scripts named herein are all built with a functional core, imperative shell style.
+Build small components that deal in pure data, orchestrate these with command dispatch.
+Expose useful functions in the command dispatch for testing and future ad-hoc use cases.
+
+## Doc validation
+
+### Code block validation and output generation
+
+`te_script_runner.py` and `csharp_doctest.py` contribute to validating code blocks in docs.
+Both need `te` on PATH.
+
+Current state only validates semantic bridge docs.
+The code block annotations can be used in any doc.
+
+#### `te_script_runner.py` -- generic runner
+
+Runs (or compile-checks) C# snippets against a throwaway, empty `.bim` model.
+Output:
+- stdout: the snippets' `Output()` only (te messages at level `output`), newline-joined
+- stderr: te's own stderr stream (always passed through), plus the runner's diagnostics parsed from te's JSON -- `[compile-error]`, `[runtime-error]`, and `[<level>]` for other non-output messages
+
+```shell
+$ python3 build_scripts/te_script_runner.py run   -e '<expr>'    # execute (also -f <file>, or stdin)
+$ python3 build_scripts/te_script_runner.py check -e '<expr>'    # compile only (te --dry-run)
+$ python3 build_scripts/te_script_runner.py run -e '<expr1>' -f <file1> -e '<expr2>' # execute multiple scripts in order; also works for `check`
+```
+
+Operation:
+1. Creates a new temporary directory
+2. Inits a new empty model in that directory
+3. Creates files for all scripts in temp directory (this is necessary to enforce strict ordering)
+4. Executes all scripts in order with `te` binary; 1 execution of `te`, no `--save`, so all script results are transient
+5. Cleans up temp directory
+
+Additional sub-commands for testing, validation, and ad-hoc use cases:
+
+- `python3 build_scripts/te_script_runner.py init`: set up the temp directory and model, returning the path; does not automatically clean up: that's your responsibility if you use this
+- `python3 build_scripts/te_script_runner.py summarize`: parses and creates output based on `te`'s output
+
+Importable in other Python scripts: `run_snippets(snippets, dry_run=..., last_only=...) -> Result`.
+`last_only` reports only the final snippet's `Output()`, rather than all snippets outputs.
+
+#### `csharp_doctest.py` -- doc orchestrator
+
+Checks annotated C# fences in a markdown file.
+The annotation is invisible in rendered docfx output:
+
+```
+    ```csharp {compile}
+    ```csharp {run id=<slug> setup=<mv-sample|none> after=<id,...|none> output=<true|false>}
+```
+
+Commands (each validates first and bails on a malformed doc):
+
+```shell
+$ python3 build_scripts/csharp_doctest.py validate <file.md>   # check annotation grammar + coverage counts, no CLI calls
+$ python3 build_scripts/csharp_doctest.py compile  <file.md>   # compile every {compile}/{run} block
+$ python3 build_scripts/csharp_doctest.py compare  <file.md>   # diff each {run} Output() against its fence
+$ python3 build_scripts/csharp_doctest.py update   <file.md>   # run {run} blocks, rewrite output blocks in place
+```
+
+Dealing with C# code blocks in a markdown doc:
+
+- code block without `csharp` in fence: skipped, but an annotation on such a block is a validation error
+- code block with `csharp` and no annotation: skip
+- `{compile}`: compile-check only (catches API drift; never executes)
+- `{run ...}`: will execute the code block with `te` binary
+  - `id=<name>`: unique name for this block in the document
+  - `setup=<known setup>`: prepends a preamble (see `SETUP_SCRIPTS`, e.g. the sample Metric View); must be registered in the script before it can be used
+  - `output=<true|false>`: if true, then this code block must be followed by literal `**Output**` on its own line, followed by a fenced code block; will check or update the output to what the script generates
+  - `after=<name>`: replays earlier run blocks for their state only (not their output); for docs where many code blocks are provided and expected to be run in sequence
+
+The grammar for these `run` blocks is explicit:
+every option must be provided in every block.
+
+Exit codes:
+- `0`: all blocks in the doc pass
+- `1`: a block failed (output mismatch, compile error, runtime error)
+- `2`: malformed doc or bad usage (validate bails before any CLI calls).
+
+Output (note: the opposite split from `te_script_runner.py` -- here the whole report, errors included, is on stdout):
+- stdout: the full report -- per-block verdicts, diffs, and compile/runtime error detail
+- stderr: te's own stderr (passed through) and harness/operational errors (bad usage, unreadable file)
+
+Sweep all docs with annotated code blocks for valid annotations, bailing on first error:
+
+```shell
+$ (set -eu; rg '```csharp \{' --glob content/**/*.md --files-with-matches | while read f; do python3 build_scripts/csharp_doctest.py validate $f; done)
+```
+
+Substitute `compile`, `compare`, or `update` for `validate` in above to run in the same way (bailing on first error).
+
+This orchestrator uses a thread pool with a thread per code block.
+Each invocation of `te` as a sub-process takes ~1-2s,
+so parallelizing nets a significant performance gain.
+
+#### Test fixtures (`test-fixtures/`)
+
+Small, self-contained inputs that exercise each code path:
+a manual regression corpus you run by hand (there are no unit tests).
+Run a command against a fixture and eyeball the result.
+
+Markdown fixtures drive `csharp_doctest.py`:
+- `doc-valid.md`: one of every block kind (skip / `{compile}` / `{run}`); everything passes.
+- `doc-mismatch.md`: a `{run}` whose `Output()` differs from its fence, so `compare` fails (and `update` would rewrite it; don't call update and commit, instead revert if you do update).
+- `doc-compile-drift.md`: a `{run}` calling a nonexistent API, so `compile` fails.
+- `err-*.md`: each holds exactly one grammar error (missing option, no output fence, annotation on a non-csharp fence, unknown `after=`, unknown annotation), so `validate` bails.
+
+`te-*.json` are canned `te --output-format json` outputs that drive `te_script_runner.py summarize` (its pure parser, no `te` needed):
+the executed-run and `--dry-run` schemas, each in a success and a failure (compile / runtime) variant.
+
+```shell
+$ python3 build_scripts/csharp_doctest.py validate test-fixtures/doc-valid.md          # passes
+$ python3 build_scripts/csharp_doctest.py compare  test-fixtures/doc-mismatch.md       # fails with a diff (nonzero exit)
+$ python3 build_scripts/csharp_doctest.py compile  test-fixtures/doc-compile-drift.md  # fails on the drifted API
+$ python3 build_scripts/csharp_doctest.py validate test-fixtures/err-unknown-after.md  # bails with the grammar error
+$ python3 build_scripts/te_script_runner.py summarize test-fixtures/te-runtime-error.json
+```
+
+### Link validation
+
+`check_links.py` validates all links (`href`/`src`) in the built `_site`.
+It walks the generated HTML,
+resolves each reference to a local file or an external URL,
+visits every unique target once, and reports references to broken targets.
+
+Build the docs site first with `python3 build-docs.py --lang en` or `python3 build-docs.py --all`.
+
+```shell
+$ python3 build_scripts/check_links.py validate                  # check _site: authored content, on-disk + external; requires built _site/
+$ python3 build_scripts/check_links.py validate stats            # add per-host external-fetch diagnostics
+$ python3 build_scripts/check_links.py validate local            # on-disk checks only, skip external fetching
+$ python3 build_scripts/check_links.py validate _site under=en   # only check links from pages under _site/en
+$ python3 build_scripts/check_links.py validate all              # also include generated API and localized pages; noisy, likely unnecessary; requires build with `--all`
+```
+
+Broken link checks:
+- local links (to something defined in this docs repo): the target file must exist
+  - detect old root links (e.g. `<a href="/Advanced-Scripting" ...>`) and resolve against the live docs site to check redirects; a dead one is an error, not a warning
+- external links (to something not defined in this docs repo): must return a 2xx/3xx status; a bad status (e.g. 404) or a transport error (DNS, TLS/certificate, timeout, refused connection) fails
+- fragments: ensure the `#anchor` is defined in the body of the target page (local file or fetched external page)
+- text links: ensure the literal `:~:text=` string is in the body of the target page (local file or fetched external page)
+
+Internal failures are errors (nonzero exit):
+own-site links, i.e. local files and root-absolute links (the latter checked over HTTP).
+External failures are warnings (network issues may be transient, or the target blocks bots),
+listed at the end as URLs to verify by hand, each with two counts:
+how many docs reference it and how many total times it appears.
+Fragment/text failures keep their `#anchor` / `:~:text=` in that list (the bare URL works;
+the fragment is what broke); a wholly unreachable URL is listed bare.
+
+Exit codes: `1` if any internal (own-site) reference is broken, else `0`. External warnings never fail the run, so third-party link rot will not break CI.
+
+Options to modify output:
+
+- `local`: skip external URL fetching (on-disk checks only)
+- `all`: include generated API and localized pages (default: authored `content/*.md` only)
+- `stats`: print per-host external-fetch diagnostics
+- `under=<subpath>`: only check links from pages under `<root>/<subpath>`
+
+Every built HTML page under `_site` is walked (to index fragment anchors and collect links site-wide).
+But by default only *failures on authored English content* are reported:
+pages under `_site/en/` that map back to `content/*.md`,
+excluding generated API reference (`en/api/`).
+The other-language pages are near-duplicate translations,
+so they and the generated API are hidden unless you pass `all` (which floods the report with those duplicates).
+
+`extract`, `resolve`, `enumerate`, and `fetch` expose the internal stages for testing.
+
+This script uses a rudimentary scheduler to avoid flooding a single host and getting a 429 storm.
+We distribute work across a thread pool and the scheduler interleaves requests to different hosts.
+There is a per-host maximum for in-flight requests,
+and a per-host cooldown when we encounter 429s,
+to avoid slamming a host that has already told us to back off.
+On a 429 we honor `Retry-After` (otherwise exponential backoff: 1, 2, 4, ... seconds)
+and also decrement that host's in-flight cap as ongoing backpressure;
+after a per-URL retry limit we give up and record the last result.
+
+Reachability uses a `HEAD` request;
+a body-downloading `GET` runs only when a fragment or `:~:text=` directive must be verified,
+so it never pulls installers or images just to check a link.
+A failed `HEAD` falls back to `GET` (some hosts reject `HEAD`),
+and known HEAD-hostile hosts skip straight to `GET`.
+
+#### Reading the `stats` table
+
+`stats` prints one row per host, worst-first. Columns:
+
+- `total`: external URLs seen for the host
+- `ok`: reachable, and any `#anchor` / `:~:text=` check passed; `total == ok` means all links to this domain were good
+- `frag`: reachable (url+path), but a fragment or text check failed
+- `bad`: unreachable, total (`= 401 + 403 + 404 + oth + net`)
+- `reqs`: fetch attempts, including retries; `total == reqs` means everything succeeded on first fetch
+- `429`: rate-limited responses seen
+- `401` / `403` / `404`: per-host counts of those statuses
+- `oth`: other failing HTTP (5xx, and 4xx that is not 401/403/404)
+- `net`: non-HTTP failures (DNS, TLS, timeout, connection reset)
+- `wait(s)`: total cooldown time applied to the host (rate limiting on our side for 429s)
+- `fb`: HEAD requests that fell back to GET (candidates for the GET-only list)
+- `cap`: ending in-flight cap (below the start value means it was throttled down)
+
+#### Interactive control (long runs)
+
+A full external run takes minutes; the terminal can query or stop it:
+
+- Status line (phase, counts, in-flight, cooling hosts) on **Ctrl-T** (macOS/BSD `SIGINFO`), **Ctrl-\\** (`SIGQUIT`, Linux/macOS), or **Ctrl-Break** (Windows `SIGBREAK`).
+- **Ctrl-C** stops cleanly and prints a partial report over what was fetched; a second **Ctrl-C** force-quits.
diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
new file mode 100644
index 00000000..7e61d244
--- /dev/null
+++ b/build_scripts/check_links.py
@@ -0,0 +1,922 @@
+#!/usr/bin/env python3
+"""
+Standalone dead-link checker for the generated `_site`.
+
+Walks the built HTML, resolves every href/src to a local file or an external
+URL, visits each unique target once, and reports references to broken targets
+(missing files, missing fragments). Local failures are errors (nonzero exit);
+external failures are warnings (network issues are often transient or the
+target blocks bots), emitted as a copy-paste list of URLs to verify by hand.
+
+The functional core (extract, resolve, validate) is pure; the imperative shell
+does filesystem, HTTP, and reporting.
+"""
+
+import http.client
+import os
+import signal
+import sys
+import urllib.error
+import urllib.request
+from collections import Counter, defaultdict, deque
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+from pathlib import Path
+from queue import Empty, Queue
+from threading import Event, Thread
+from time import monotonic
+from types import FrameType
+from typing import Any, NamedTuple
+from urllib.parse import unquote, urldefrag, urlsplit
+
+# Interactive control: a shared progress view that `main` reads for a Ctrl-T status line, and a stop flag it sets on
+# Ctrl-C so the running command can wind down and still emit a partial report. Commands populate the view as they go.
+
+_STOP_POLL = 1.0  # max seconds the fetch scheduler blocks between stop-flag checks, so Ctrl-C stays responsive
+
+# Terminal keys that print a status line, by platform: Ctrl-T (BSD/macOS), Ctrl-\ (POSIX; overrides the quit/core
+# dump), Ctrl-Break (Windows). We bind whichever the platform defines, so a status key exists everywhere.
+_STATUS_SIGNALS = ("SIGINFO", "SIGQUIT", "SIGBREAK")
+
+_SignalHandler = Callable[[int, FrameType | None], None]
+
+
+@dataclass
+class _Progress:
+    """Live counters for the running command. `main` reads them for the status signal and sets `stop` on Ctrl-C;
+    commands advance the phase, bump the counters, and check `stop` to bail out early for a partial report."""
+
+    phase: str = "starting"
+    pages: int = 0  # built HTML pages scanned (enumerate phase)
+    links: int = 0  # link references seen while scanning
+    targets: int = 0  # unique targets discovered to check
+    urls_total: int = 0  # external URLs queued to fetch
+    urls_done: int = 0  # external URLs fetched so far
+    dispatched: int = 0  # URLs handed to the queue but not yet resolved (>= the few workers actively fetching)
+    workers: int = 0  # size of the fetch worker pool
+    cooling: dict[str, float] = field(default_factory=dict)  # host -> monotonic deadline it is eligible again
+    started: float = 0.0  # monotonic start time, for elapsed
+    stop: Event = field(default_factory=Event)
+
+
+def _status_line(progress: _Progress, now: float) -> str:
+    """A one-line snapshot of our own work for the Ctrl-T status signal (about the run, not OS resource stats)."""
+    p = progress
+    head = f"[check_links] phase={p.phase} elapsed={now - p.started:.0f}s"
+    if p.phase != "fetching external":
+        return f"{head} pages={p.pages} links={p.links} targets={p.targets}"
+    cooling = sorted(
+        ((host, deadline - now) for host, deadline in p.cooling.items() if deadline > now),
+        key=lambda hw: hw[1],
+        reverse=True,
+    )
+    detail = "".join(f" {host}({wait:.1f}s)" for host, wait in cooling)  # wide when many hosts cool at once; fine
+    return (
+        f"{head} fetched={p.urls_done}/{p.urls_total} dispatched={p.dispatched} "
+        f"workers={p.workers} cooling={len(cooling)}{detail}"
+    )
+
+
+def _install_signal_handlers(on_stop: _SignalHandler, on_status: _SignalHandler) -> dict[int, Any]:
+    """Wire SIGINT (Ctrl-C, clean stop) and every available status signal (see `_STATUS_SIGNALS`), returning the
+    prior handlers for restoration. A no-op off the main thread, where handlers cannot be installed."""
+    previous: dict[int, Any] = {}
+    try:
+        previous[signal.SIGINT] = signal.signal(signal.SIGINT, on_stop)
+        for name in _STATUS_SIGNALS:
+            signum = getattr(signal, name, None)
+            if signum is not None:
+                previous[signum] = signal.signal(signum, on_status)
+    except ValueError:
+        pass  # not the main thread; interactive control is simply unavailable
+    return previous
+
+
+def _restore_signal_handlers(previous: dict[int, Any]) -> None:
+    for signum, handler in previous.items():
+        signal.signal(signum, handler)
+
+
+def _normalize_text(text: str) -> str:
+    """Collapse whitespace and case-fold, so text-fragment queries match the page regardless of layout or case."""
+    return " ".join(text.split()).casefold()
+
+
+class _LinkAnchorParser(HTMLParser):
+    """Collects href/src references and fragment targets (`id`, and `name` on `a`), and optionally the page text."""
+
+    def __init__(self, collect_text: bool = False) -> None:
+        super().__init__(convert_charrefs=True)
+        self.links: list[tuple[str, int]] = []  # (href, 1-based line in the source HTML)
+        self.anchors: set[str] = set()
+        self._collect_text = collect_text
+        self._chunks: list[str] = []
+        self._skip_depth = 0  # inside <script>/<style>, whose text is not visible content
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        attr = dict(attrs)
+        line = self.getpos()[0]
+        # <link> is head chrome (canonical/hreflang SEO tags, stylesheets), never authored content.
+        if tag != "link":
+            for key in ("href", "src"):
+                if value := attr.get(key):
+                    self.links.append((value, line))
+        if element_id := attr.get("id"):
+            self.anchors.add(element_id)
+        if tag == "a" and (name := attr.get("name")):
+            self.anchors.add(name)
+        if tag in ("script", "style"):
+            self._skip_depth += 1
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in ("script", "style") and self._skip_depth:
+            self._skip_depth -= 1
+
+    def handle_data(self, data: str) -> None:
+        if self._collect_text and not self._skip_depth:
+            self._chunks.append(data)
+
+    @property
+    def text(self) -> str:
+        return "".join(self._chunks)
+
+
+def extract(html: str) -> tuple[list[tuple[str, int]], set[str]]:
+    """Parse one page into (referenced (URL, line) pairs, fragment targets defined on the page)."""
+    parser = _LinkAnchorParser()
+    parser.feed(html)
+    return parser.links, parser.anchors
+
+
+def cmd_extract(args: list[str], progress: _Progress) -> int:
+    """Print the links (with line numbers) and fragment targets extracted from an HTML file."""
+    links, anchors = extract(Path(args[0]).read_text(encoding="utf-8"))
+    for href, line in links:
+        print(f"link\t{line}\t{href}")
+    for anchor in sorted(anchors):
+        print(f"anchor\t{anchor}")
+    return 0
+
+
+class Target(NamedTuple):
+    """A resolved link destination: a local file, an external URL, or a root-absolute site link."""
+
+    kind: str  # "local" (filesystem), "external" (HTTP), or "site" (root-absolute, resolved by resolve_site_targets)
+    resource: str  # local: normalized filesystem path; external: URL; site: root-absolute URL path
+    fragment: str  # decoded element-id anchor, or "" for none / page-top
+    text_targets: tuple[str, ...]  # decoded text segments of a `:~:text=` directive that must all be on the page
+    internal: bool = False  # a link to our own site; a failure is an error even when checked over HTTP
+
+
+_SKIP_SCHEMES = ("mailto:", "tel:", "javascript:", "data:")
+
+# API endpoints and the like that are documented in the docs but are not pages meant to be fetched. The `api.`
+# heuristic covers most (api.openai.com, *.api.daxoptimizer.com, ...); add other non-gettable hosts explicitly.
+_UNCHECKED_HOSTS: set[str] = set()
+
+# Any hosts where we observe 429s when we use `stats` get a lower max for
+# in-flight requests. Try to be a good citizen of the web.
+_HOST_MAX_IN_FLIGHT_OVERRIDES = {"github.com": 6}
+
+# Where root-absolute ("site") links resolve on the deployed site. Ones missing from the local build are checked
+# here, because the deployed site's redirects (Azure SWA) make many of them valid even without a matching file.
+_LIVE_SITE_BASE = "https://docs.tabulareditor.com"
+
+# Some encoders (DocFX/Markdig) percent-encode the ~ in the :~: text-fragment delimiter, so it must be normalized
+# before the split -- partitioning the still-encoded fragment would miss the delimiter entirely.
+_FRAGMENT_DELIMITER = ":~:"
+_ENCODED_DELIMITER_CHARS = {"%7e": "~", "%7E": "~"}
+
+
+def _is_skippable(href: str) -> bool:
+    """True for hrefs with nothing to check: empty, a bare '#', or a non-navigable scheme."""
+    return not href or href == "#" or href.lower().startswith(_SKIP_SCHEMES)
+
+
+def _is_external(url: str) -> bool:
+    """True for absolute or protocol-relative URLs, which are checked over HTTP rather than on disk."""
+    return url.lower().startswith(("http://", "https://", "//"))
+
+
+def _is_root_absolute(url: str) -> bool:
+    """True for site-root-relative links, resolved against the site root rather than the source page."""
+    return url.startswith("/")
+
+
+def _is_unchecked_host(host: str) -> bool:
+    """True for hosts we deliberately skip -- API endpoints and other documented-but-not-navigable URLs."""
+    return host in _UNCHECKED_HOSTS or host.startswith("api.") or ".api." in host
+
+
+def _split_fragment(raw_fragment: str) -> tuple[str, str]:
+    """Split a raw URL fragment into (element-id anchor, text directive), decoding an encoded delimiter first so
+    the :~: split is found even when the ~ arrives percent-encoded. Delimiters are decoded before the split; the
+    directive's own values stay encoded for `_parse_text_directive` to split and decode."""
+    normalized = raw_fragment
+    for encoded, decoded in _ENCODED_DELIMITER_CHARS.items():
+        normalized = normalized.replace(encoded, decoded)
+    anchor, _, directive = normalized.partition(_FRAGMENT_DELIMITER)
+    return anchor, directive
+
+
+def _parse_text_directive(directive: str) -> tuple[str, ...]:
+    """The decoded text segments of a `:~:text=` fragment directive (textStart and textEnd), all of which must be
+    present on the page. Empty if it is not a text directive. The optional prefix-/-suffix context is dropped."""
+    if not directive.startswith("text="):
+        return ()
+    # value is [prefix-,]textStart[,textEnd][,-suffix]; keep the non-context segments.
+    segments = [seg for seg in directive[len("text=") :].split(",") if seg]
+    return tuple(unquote(seg) for seg in segments if not seg.endswith("-") and not seg.startswith("-"))
+
+
+def resolve(href: str, source_page: Path, site_root: Path) -> Target | None:
+    """Classify and normalize a raw href into a checkable Target, or None when there is nothing to check."""
+    href = href.strip()
+    if _is_skippable(href):
+        return None
+    url, raw_fragment = urldefrag(href)
+    anchor, directive = _split_fragment(raw_fragment)
+    fragment = unquote(anchor)
+    if fragment == "top":  # browsers scroll to the page top for #top even with no matching element
+        fragment = ""
+    text_targets = _parse_text_directive(directive)
+    if _is_external(url):
+        return None if _is_unchecked_host(_host_of(url)) else Target("external", url, fragment, text_targets)
+    if not url:  # a same-page "#fragment" reference (nothing to check for a pure text directive)
+        return Target("local", str(source_page), fragment, text_targets) if fragment else None
+    if _is_root_absolute(url):  # a site link; resolve_site_targets decides on-disk vs live once the tree is known
+        return Target("site", url, fragment, text_targets)
+    base = source_page.parent / url
+    return Target("local", os.path.normpath(base), fragment, text_targets)
+
+
+def cmd_resolve(args: list[str], progress: _Progress) -> int:
+    """Print the resolved Target (or 'skip') for a raw href found in a source page."""
+    href, source_page = args[0], Path(args[1])
+    site_root = Path(args[2]) if len(args) > 2 else Path("_site")
+    target = resolve(href, source_page, site_root)
+    if target is None:
+        print("skip")
+    else:
+        print(f"{target.kind}\t{target.resource}\t{target.fragment}\t{target.text_targets}")
+    return 0
+
+
+def enumerate_site(
+    root: Path, source_prefix: str | None = None, progress: _Progress | None = None
+) -> tuple[dict[Target, dict[str, list[int]]], dict[str, set[str]]]:
+    """Walk the built site under `root`: return (target -> {referring page -> line numbers}) and (page -> anchors).
+
+    Anchors are indexed for every page so fragment targets anywhere resolve, but links are collected only from pages
+    whose path starts with `source_prefix` (when given) -- a way to check just a subset of the docs. Counts flow into
+    `progress` for the status signal, and a Ctrl-C (its stop flag) ends the walk early for a partial report."""
+    progress = progress or _Progress()
+    refs: dict[Target, dict[str, list[int]]] = {}
+    anchors_by_file: dict[str, set[str]] = {}
+    for page in root.rglob("*.html"):
+        if progress.stop.is_set():
+            break
+        progress.pages += 1
+        source = os.path.normpath(page)
+        links, anchors = extract(page.read_text(encoding="utf-8"))
+        anchors_by_file[source] = anchors
+        if source_prefix and not source.startswith(source_prefix):
+            continue  # index this page's anchors, but do not check its outgoing links
+        for href, line in links:
+            target = resolve(href, page, root)
+            if target is not None:
+                refs.setdefault(target, {}).setdefault(source, []).append(line)
+        progress.links += len(links)
+        progress.targets = len(refs)
+    return refs, anchors_by_file
+
+
+def cmd_enumerate(args: list[str], progress: _Progress) -> int:
+    """Print summary counts for the site's links and fragment targets."""
+    root = Path(args[0]) if args else Path("_site")
+    refs, anchors_by_file = enumerate_site(root, progress=progress)
+    local = sum(1 for target in refs if target.kind == "local")
+    external = sum(1 for target in refs if target.kind == "external")
+    site = sum(1 for target in refs if target.kind == "site")
+    total = sum(len(lines) for sources in refs.values() for lines in sources.values())
+    print(f"html files indexed: {len(anchors_by_file)}")
+    print(f"unique targets:     {len(refs)}  (local {local}, external {external}, site {site})")
+    print(f"total references:   {total}")
+    return 0
+
+
+# A real browser User-Agent: stdlib's default python-urllib string is 403'd by GitHub and Microsoft Learn.
+_USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+)
+
+# Cap the body we read for anchor/text checks. The 20s socket timeout bounds a stalled read, but not a server that
+# steadily streams an endless (or huge) body; this bounds it. HTML pages we check are far smaller.
+_MAX_BODY_BYTES = 10 * 1024 * 1024
+
+
+class FetchResult(NamedTuple):
+    """The outcome of visiting one external URL: reachability, status, any error detail, and page anchors (GET only)."""
+
+    ok: bool  # True when the server answered with a 2xx/3xx status
+    status: int  # HTTP status code, or 0 when the request never completed
+    detail: str  # human-readable error for the report, or "" on success
+    anchors: set[str]  # fragment targets found in the body (populated only on a body-parsing GET)
+    retry_after: int  # seconds requested by a 429 Retry-After header; 0 otherwise
+    method: str  # the request method that produced this result ("HEAD"/"GET"), or "" if none completed
+    text: str  # normalized visible page text for text-fragment checks (populated only on a body-parsing GET)
+
+
+# Hosts confirmed to 404 a HEAD they serve on GET; skip the doomed HEAD probe for them. Diagnostics
+# (`head_fallbacks`) surface further candidates to add here.
+_GET_ONLY_HOSTS = {"cdn.tabulareditor.com", "www.nuget.org"}
+
+
+def _host_of(url: str) -> str:
+    """The lowercased host of an external URL (with a scheme prepended for protocol-relative //host)."""
+    return urlsplit("https:" + url if url.startswith("//") else url).netloc.lower()
+
+
+def _parse_retry_after(value: str | None) -> int:
+    """Seconds from a 429 Retry-After header; 0 when absent or given as an HTTP-date we do not parse."""
+    return int(value) if value and value.isdigit() else 0
+
+
+def fetch_external(url: str, need_body: bool) -> FetchResult:
+    """Visit one external URL. HEAD is a cheap reachability probe; any HEAD failure is reconfirmed with a GET before
+    the URL is declared broken, because many hosts 404/405 a HEAD they would serve (known ones skip HEAD via
+    `_GET_ONLY_HOSTS`). GET downloads the body only when a fragment must be verified."""
+    target = "https:" + url if url.startswith("//") else url  # protocol-relative //host needs a scheme
+    get_only = need_body or _host_of(url) in _GET_ONLY_HOSTS
+    for method in (("GET",) if get_only else ("HEAD", "GET")):
+        request = urllib.request.Request(target, method=method, headers={"User-Agent": _USER_AGENT})
+        try:
+            with urllib.request.urlopen(request, timeout=20) as response:
+                anchors: set[str] = set()
+                text = ""
+                # Download the body only to verify a fragment; a reachability GET (the HEAD fallback) needs just the
+                # status, and reading it would pull whole binaries (installers, images) off the CDN.
+                if method == "GET" and need_body:
+                    charset = response.headers.get_content_charset() or "utf-8"
+                    parser = _LinkAnchorParser(collect_text=True)
+                    parser.feed(response.read(_MAX_BODY_BYTES).decode(charset, "replace"))
+                    anchors, text = parser.anchors, _normalize_text(parser.text)
+                return FetchResult(True, response.status, "", anchors, 0, method, text)
+        except urllib.error.HTTPError as error:
+            if method == "HEAD":
+                continue  # HEAD is only a probe; reconfirm the failure with a GET
+            retry_after = _parse_retry_after(error.headers.get("Retry-After")) if error.code == 429 else 0
+            return FetchResult(False, error.code, f"HTTP {error.code} {error.reason}", set(), retry_after, method, "")
+        except (OSError, http.client.HTTPException, ValueError) as error:
+            # OSError covers URLError/TimeoutError/connection resets; HTTPException covers a peer that closes
+            # mid-response (RemoteDisconnected), which urllib does not wrap when it happens during getresponse().
+            if method == "HEAD":
+                continue  # reconfirm transport failures with a GET too
+            return FetchResult(False, 0, str(getattr(error, "reason", error)), set(), 0, method, "")
+    return FetchResult(False, 0, "no request attempted", set(), 0, "", "")
+
+
+class _Task(NamedTuple):
+    """A queued fetch: the URL, whether its body is needed, its host (cached), and the 429 retry count so far."""
+
+    url: str
+    need_body: bool
+    host: str
+    attempt: int
+
+
+class HostStats(NamedTuple):
+    """Per-host fetch diagnostics for understanding timing and rate limiting."""
+
+    requests: int  # fetch attempts completed, including 429 retries
+    rate_limited: int  # 429 responses received
+    wait_seconds: float  # total cooldown time applied to the host
+    head_fallbacks: int  # reachability GETs after a failed HEAD (candidates for _GET_ONLY_HOSTS)
+    final_cap: int  # ending per-host in-flight cap (below the start value means it was throttled down)
+    retry_after_seen: frozenset[int]  # distinct Retry-After values seen on 429s (0 = header absent/unparsed)
+
+
+_MAX_RETRIES = 8  # per-URL: after this many 429 retries, give up on a URL and record the last result
+
+
+def _backoff(attempt: int) -> float:
+    """Seconds to wait before retrying a 429 that carried no Retry-After: 1, 2, 4, ..."""
+    return float(2**attempt)
+
+
+def _next_cooldown_wait(pending: dict[str, deque[_Task]], cooldown: dict[str, float], now: float) -> float | None:
+    """Seconds until the soonest cooling-down host with pending work becomes eligible, or None if none are cooling."""
+    waits = [cooldown[host] - now for host in pending if cooldown.get(host, 0.0) > now]
+    return min(waits) if waits else None
+
+
+def fetch_all_external(
+    refs: dict[Target, dict[str, list[int]]],
+    max_per_host: int = 8,
+    max_workers: int = 12,
+    progress: _Progress | None = None,
+) -> tuple[dict[str, FetchResult], dict[str, HostStats]]:
+    """Fetch every unique external URL once. `max_workers` threads drain a shared work queue kept as full as
+    eligibility allows; admission holds each host to its current cap (starting at `max_per_host`). A 429 cools the
+    host down (honoring Retry-After), drops its cap by one as backpressure, and re-queues its URLs for after the
+    wait. GET only when a fragment must be verified. Returns the results plus per-host diagnostics.
+
+    All scheduling state is owned by this thread alone (workers only pull tasks and push results), so it needs no
+    locks. On a 429 we also reclaim that host's not-yet-claimed tasks from the queue; any a worker already grabbed
+    slip through, which is a bounded, acceptable miss. Progress counts flow into `progress` for the status signal,
+    and a Ctrl-C (its stop flag) ends the loop early, returning whatever has been fetched for a partial report."""
+    progress = progress or _Progress()
+    need_body: dict[str, bool] = {}
+    for target in refs:
+        if target.kind == "external":
+            wants_body = bool(target.fragment) or bool(target.text_targets)
+            need_body[target.resource] = need_body.get(target.resource, False) or wants_body
+
+    pending: dict[str, deque[_Task]] = defaultdict(deque)
+    for url, body in need_body.items():
+        host = _host_of(url)
+        pending[host].append(_Task(url, body, host, 0))
+
+    work_q: Queue[_Task | None] = Queue()
+    done_q: Queue[tuple[_Task, FetchResult]] = Queue()
+    outstanding: dict[str, int] = defaultdict(int)
+    host_cap: dict[str, int] = defaultdict(lambda: max_per_host)
+    host_cap.update(_HOST_MAX_IN_FLIGHT_OVERRIDES)
+    cooldown: dict[str, float] = {}
+    results: dict[str, FetchResult] = {}
+
+    requests: dict[str, int] = defaultdict(int)
+    rate_limited: dict[str, int] = defaultdict(int)
+    wait_seconds: dict[str, float] = defaultdict(float)
+    head_fallbacks: dict[str, int] = defaultdict(int)
+    retry_after_seen: dict[str, set[int]] = defaultdict(set)
+
+    def worker() -> None:
+        while (task := work_q.get()) is not None:
+            try:
+                result = fetch_external(task.url, task.need_body)
+            except Exception as error:  # never die with a task in hand: that result would never come and hang us
+                result = FetchResult(False, 0, f"fetch crashed: {error!r}", set(), 0, "", "")
+            done_q.put((task, result))
+
+    def admit() -> None:
+        now = monotonic()
+        for host, queued in pending.items():
+            while queued and outstanding[host] < host_cap[host] and cooldown.get(host, 0.0) <= now:
+                outstanding[host] += 1
+                work_q.put(queued.popleft())
+
+    def reclaim(host: str) -> None:
+        """Pull the cooling host's not-yet-claimed tasks back out of the work queue so they wait for the cooldown."""
+        kept: list[_Task | None] = []
+        try:
+            while True:
+                task = work_q.get_nowait()
+                if task is not None and task.host == host:
+                    outstanding[host] -= 1
+                    pending[host].appendleft(task)
+                else:
+                    kept.append(task)
+        except Empty:
+            pass
+        for task in kept:
+            work_q.put(task)
+
+    # Daemon workers so a second Ctrl-C (which raises in the main thread) can abandon in-flight requests and exit.
+    workers = [Thread(target=worker, daemon=True) for _ in range(max_workers)]
+    for thread in workers:
+        thread.start()
+
+    remaining = len(need_body)
+    progress.urls_total = remaining
+    progress.workers = max_workers
+    progress.cooling = cooldown  # a live reference; the status handler reads it on the same thread, so no lock
+    admit()
+    while remaining and not progress.stop.is_set():
+        wait = _next_cooldown_wait(pending, cooldown, monotonic())
+        wait = _STOP_POLL if wait is None else min(wait, _STOP_POLL)  # cap the block so the stop flag is seen promptly
+        try:
+            task, result = done_q.get(timeout=wait)
+        except Empty:
+            admit()  # a cooldown expired (or the poll ticked); recheck eligibility
+            continue
+        outstanding[task.host] -= 1
+        requests[task.host] += 1
+        if result.method == "GET" and not task.need_body and task.host not in _GET_ONLY_HOSTS:
+            head_fallbacks[task.host] += 1
+        if result.status == 429:
+            rate_limited[task.host] += 1
+            retry_after_seen[task.host].add(result.retry_after)
+        if result.status == 429 and task.attempt < _MAX_RETRIES:
+            host_cap[task.host] = max(1, host_cap[task.host] - 1)  # adaptive backpressure
+            delay = result.retry_after or _backoff(task.attempt)
+            wait_seconds[task.host] += delay
+            cooldown[task.host] = monotonic() + delay
+            pending[task.host].appendleft(task._replace(attempt=task.attempt + 1))
+            reclaim(task.host)
+        else:
+            results[task.url] = result
+            remaining -= 1
+        admit()
+        progress.urls_done = len(results)
+        progress.dispatched = sum(outstanding.values())
+
+    if not progress.stop.is_set():  # normal completion: retire the workers cleanly
+        for _ in workers:
+            work_q.put(None)
+        for thread in workers:
+            thread.join()
+    # On Ctrl-C we skip the join: a daemon worker may be mid-request, and blocking on a slow socket would stall the
+    # partial report. The workers are abandoned and reaped at interpreter exit; `results` is the partial set.
+
+    stats = {
+        host: HostStats(
+            requests[host],
+            rate_limited[host],
+            wait_seconds[host],
+            head_fallbacks[host],
+            host_cap[host],
+            frozenset(retry_after_seen[host]),
+        )
+        for host in pending
+    }
+    return results, stats
+
+
+def cmd_fetch(args: list[str], progress: _Progress) -> int:
+    """Fetch a single external URL (pass a second arg to force a body-parsing GET) and print the result."""
+    url = args[0]
+    need_body = len(args) > 1
+    result = fetch_external(url, need_body)
+    print(
+        f"ok={result.ok} status={result.status} anchors={len(result.anchors)} "
+        f"retry_after={result.retry_after} detail={result.detail}"
+    )
+    return 0
+
+
+class Failure(NamedTuple):
+    """A broken target: the target, a short reason, and each referring page mapped to the lines it appears on."""
+
+    target: Target
+    reason: str
+    sources: dict[str, list[int]]
+
+
+def _find_local_file(resource: str, existing_files: set[str]) -> str | None:
+    """Map a resolved local path to an existing file, trying `.html` and `index.html` fallbacks; None if absent."""
+    if resource in existing_files:
+        return resource
+    if not resource.endswith(".html"):
+        for fallback in (f"{resource}.html", os.path.normpath(os.path.join(resource, "index.html"))):
+            if fallback in existing_files:
+                return fallback
+    return None
+
+
+def validate(
+    refs: dict[Target, dict[str, list[int]]],
+    anchors_by_file: dict[str, set[str]],
+    existing_files: set[str],
+    external_results: dict[str, FetchResult],
+) -> list[Failure]:
+    """Cross-reference every target against the filesystem snapshot and fetch results into a list of failures."""
+    failures: list[Failure] = []
+    for target, sources in refs.items():
+        if target.kind == "local":
+            resolved = _find_local_file(target.resource, existing_files)
+            if resolved is None:
+                failures.append(Failure(target, "missing file", sources))
+            elif target.fragment and target.fragment not in anchors_by_file.get(resolved, set()):
+                failures.append(Failure(target, "missing anchor", sources))
+        else:
+            result = external_results.get(target.resource)
+            if result is None:
+                failures.append(Failure(target, "not fetched", sources))
+            elif not result.ok:
+                failures.append(Failure(target, result.detail or f"unreachable (status {result.status})", sources))
+            elif target.text_targets and not all(_normalize_text(t) in result.text for t in target.text_targets):
+                failures.append(Failure(target, "missing text", sources))
+            elif target.fragment and target.fragment not in result.anchors:
+                failures.append(Failure(target, "missing anchor", sources))
+    return failures
+
+
+def _existing_files(root: Path) -> set[str]:
+    """Snapshot every file under `root` as a normalized path, for pure existence checks in `validate`."""
+    return {os.path.normpath(path) for path in root.rglob("*") if path.is_file()}
+
+
+def resolve_site_targets(
+    refs: dict[Target, dict[str, list[int]]], existing_files: set[str], site_root: Path, live: bool
+) -> dict[Target, dict[str, list[int]]]:
+    """Resolve root-absolute ("site") links against the built tree: those present on disk become ordinary local
+    checks; those absent are checked against the live site (its redirects usually make them valid) and, being our
+    own links, a failure there is an error, not a warning. With `live` false (offline mode) absent links stay
+    on-disk errors. Non-site targets pass through unchanged."""
+    resolved: dict[Target, dict[str, list[int]]] = {}
+    for target, sources in refs.items():
+        reclassified = target
+        if target.kind == "site":
+            disk_path = os.path.normpath(site_root / target.resource.lstrip("/"))
+            if live and _find_local_file(disk_path, existing_files) is None:
+                url = _LIVE_SITE_BASE + target.resource
+                reclassified = Target("external", url, target.fragment, target.text_targets, internal=True)
+            else:
+                reclassified = target._replace(kind="local", resource=disk_path)
+        merged = resolved.setdefault(reclassified, {})
+        for source, lines in sources.items():
+            merged.setdefault(source, []).extend(lines)
+    return resolved
+
+
+def map_to_source(built: str, root: Path) -> str | None:
+    """Map a built HTML path back to its authored markdown under content/, or None for generated/localized pages."""
+    parts = Path(os.path.relpath(built, root)).parts  # e.g. ("en", "features", "foo.html")
+    if len(parts) >= 2 and parts[0] == "en" and parts[1] != "api":
+        return os.path.normpath(os.path.join("content", str(Path(*parts[1:]).with_suffix(".md"))))
+    return None
+
+
+def _anchor_member(type_stem: str, fragment: str) -> str:
+    """Best-effort member name from a DocFX member anchor; empty when the anchor scheme does not match."""
+    prefix = type_stem.replace(".", "_") + "_"
+    return fragment[len(prefix):].split("_", 1)[0] if fragment.startswith(prefix) else ""
+
+
+def _fragment_suffix(target: Target) -> str:
+    """The full URL fragment for display: the element-id anchor and/or the complete `:~:text=` directive, or ""."""
+    directive = ("text=" + ",".join(target.text_targets)) if target.text_targets else ""
+    if target.fragment and directive:
+        return f"#{target.fragment}:~:{directive}"
+    if target.fragment:
+        return f"#{target.fragment}"
+    return f"#:~:{directive}" if directive else ""
+
+
+def humanize(target: Target) -> str:
+    """A greppable rendering of the destination for finding it in the markdown source (best-effort for API anchors)."""
+    if target.kind == "external":
+        return _display_url(target) + _fragment_suffix(target)
+    stem = os.path.basename(target.resource).removesuffix(".html")
+    if not target.fragment:
+        return stem
+    member = _anchor_member(stem, target.fragment)
+    type_name = stem.rsplit(".", 1)[-1]  # last dotted segment of the type UID
+    return f"{type_name}.{member}" if member else f"{type_name} (#{target.fragment})"
+
+
+def _display_url(target: Target) -> str:
+    """The path or URL shown for a target. Internal (live-checked own-site) links show the authored root-absolute
+    path rather than the live URL; protocol-relative externals get an https scheme."""
+    if target.internal:
+        return target.resource.removeprefix(_LIVE_SITE_BASE)
+    if target.kind == "external" and target.resource.startswith("//"):
+        return "https:" + target.resource
+    return target.resource
+
+
+def report(failures: list[Failure], root: Path, content_only: bool = True) -> int:
+    """Print broken references grouped by source file and return an exit code (nonzero if any on-disk error).
+
+    On-disk breaks are errors; external breaks are warnings with a trailing copy-paste URL list. Each break shows
+    the greppable destination for the markdown, the exact built-HTML href, and clickable `path:line` locations. By
+    default only breaks on authored `content/*.md` pages are shown; `content_only=False` adds generated API and
+    localized pages. Groups sort by displayed path, so `content/` files lead:
+
+        ERRORS -- 2 broken on-disk reference(s) across 1 file(s)
+
+        content/features/semantic-bridge-metric-view-object-model.md
+          built: _site/en/features/semantic-bridge-metric-view-object-model.html
+          missing anchor  (x2)
+            md grep: DatabricksMetricViewService.Load
+            html:    ../../api/TabularEditor.SemanticBridge...DatabricksMetricViewService.html#..._Load_System_String_
+            at:      _site/en/features/semantic-bridge-metric-view-object-model.html:120  ...:145
+          missing file  (x3)
+            md grep: Advanced-features
+            html:    /Advanced-features
+            at:      _site/en/features/semantic-bridge-metric-view-object-model.html:12  ...:30  ...:88
+
+        WARNINGS -- 1 broken external reference(s) across 1 file(s)
+        ...
+        External URLs to verify (url, docs, instances):
+          https://example.com/gone  3  5
+    """
+    errors: dict[str, list[tuple[Failure, list[int]]]] = {}
+    warnings: dict[str, list[tuple[Failure, list[int]]]] = {}
+    for failure in failures:
+        is_error = failure.target.kind == "local" or failure.target.internal  # our own content vs third-party
+        bucket = errors if is_error else warnings
+        for source, lines in failure.sources.items():
+            if content_only and map_to_source(source, root) is None:
+                continue
+            bucket.setdefault(source, []).append((failure, sorted(lines)))
+
+    if not errors and not warnings:
+        print("No broken references found.")
+        return 0
+
+    for label, bucket in (("ERRORS", errors), ("WARNINGS", warnings)):
+        if not bucket:
+            continue
+        kind = "internal" if label == "ERRORS" else "external"
+        total = sum(len(breaks) for breaks in bucket.values())
+        print(f"{label} -- {total} broken {kind} reference(s) across {len(bucket)} file(s)")
+        for source in sorted(bucket, key=lambda s: map_to_source(s, root) or s):
+            md = map_to_source(source, root)
+            print(f"\n{md or source}")
+            print(f"  built: {source}" if md else "  (generated or localized page; no direct .md source)")
+            for failure, lines in sorted(bucket[source], key=lambda fl: (fl[0].reason, fl[0].target.resource)):
+                # A missing file makes any fragment/text directive moot, so drop it from what we display.
+                target = failure.target
+                if failure.reason == "missing file":
+                    target = target._replace(fragment="", text_targets=())
+                locations = "  ".join(f"{source}:{line}" for line in lines)
+                print(f"  {failure.reason}  (x{len(lines)})")
+                print(f"    md grep: {humanize(target)}")
+                print(f"    html:    {_display_url(target)}{_fragment_suffix(target)}")
+                print(f"    at:      {locations}")
+        print()
+
+    if warnings:
+        files: dict[str, set[str]] = defaultdict(set)
+        instances: dict[str, int] = defaultdict(int)
+        for source, breaks in warnings.items():
+            for failure, lines in breaks:
+                # For a reachable-but-fragment/text failure the bare URL works, so keep the fragment that broke;
+                # for an unreachable URL the fragment is moot, so show it bare.
+                shown = _display_url(failure.target)
+                if failure.reason in ("missing anchor", "missing text"):
+                    shown += _fragment_suffix(failure.target)
+                files[shown].add(source)
+                instances[shown] += len(lines)
+        print("External URLs to verify (url, docs, instances):")
+        for url in sorted(files):
+            print(f"{url}  {len(files[url])}  {instances[url]}")
+
+    return 1 if errors else 0
+
+
+_FEATURED_STATUS = (401, 403, 404)  # broken out as their own per-host columns; the rest fold into "5xx/other"
+
+
+class Outcome(NamedTuple):
+    """Per-host validation outcomes for external URLs."""
+
+    ok: int  # reachable, and any fragment/text check passed
+    partial: int  # reachable (url+path), but a fragment or text check on it failed
+    status: Counter[int]  # failing HTTP status code -> count (e.g. 404 -> 3)
+    transport: int  # non-HTTP failures: DNS, TLS, timeout, connection reset (no HTTP status)
+
+    @property
+    def total(self) -> int:
+        """Every external URL seen for this host: successes, fragment/text issues, and unreachable."""
+        return self.ok + self.partial + self.broken
+
+    @property
+    def broken(self) -> int:
+        """Total unreachable: every failing HTTP status plus the transport failures."""
+        return sum(self.status.values()) + self.transport
+
+    @property
+    def other_http(self) -> int:
+        """Failing HTTP statuses beyond the featured columns (5xx, and any 4xx that is not 401/403/404)."""
+        return sum(count for code, count in self.status.items() if code not in _FEATURED_STATUS)
+
+
+def summarize_outcomes(external_results: dict[str, FetchResult], failures: list[Failure]) -> dict[str, Outcome]:
+    """Reduce fetch results and validation failures to a per-host Outcome. Partial hangs off `failures` because a
+    missing fragment/text is only knowable after validation, not from the fetch alone."""
+    frag_urls = {
+        f.target.resource
+        for f in failures
+        if f.target.kind == "external" and f.reason in ("missing anchor", "missing text")
+    }
+    ok: Counter[str] = Counter()
+    partial: Counter[str] = Counter()
+    transport: Counter[str] = Counter()
+    status: defaultdict[str, Counter[int]] = defaultdict(Counter)
+    for url, result in external_results.items():
+        host = _host_of(url)
+        if not result.ok:
+            if result.status == 0:
+                transport[host] += 1  # DNS, TLS, timeout, connection reset -- no HTTP status to bucket
+            else:
+                status[host][result.status] += 1
+        elif url in frag_urls:
+            partial[host] += 1
+        else:
+            ok[host] += 1
+    hosts = set(ok) | set(partial) | set(transport) | set(status)
+    return {h: Outcome(ok[h], partial[h], status.get(h, Counter()), transport[h]) for h in hosts}
+
+
+def print_diagnostics(stats: dict[str, HostStats], outcomes: dict[str, Outcome], elapsed: float) -> None:
+    """Print the combined per-host stats table: validation outcomes (ok/frag/bad, per-status failures, non-HTTP
+    failures) alongside fetch mechanics (reqs/429s/cooldown/HEAD fallbacks/cap). Hosts sort worst-first."""
+    active = {host: stat for host, stat in stats.items() if stat.requests}
+    if not active:  # interrupted before any fetch happened; a header with no rows is just noise
+        return
+    empty = Outcome(0, 0, Counter(), 0)
+
+    def rank(item: tuple[str, HostStats]) -> tuple[int, int, int, float]:
+        host, stat = item
+        outcome = outcomes.get(host, empty)
+        return outcome.broken, outcome.partial, stat.rate_limited, stat.wait_seconds
+
+    print(f"\n--- stats ({elapsed:.1f}s, {len(active)} hosts) ---")
+    print(f"{'total':>5} {'ok':>5} {'frag':>5} {'bad':>5} {'reqs':>5} {'429':>4} {'401':>4} {'403':>4} {'404':>4} "
+          f"{'oth':>4} {'net':>4} {'wait(s)':>8} {'fb':>4} {'cap':>4}  host  [retry-after seen]")
+    for host, stat in sorted(active.items(), key=rank, reverse=True):
+        oc = outcomes.get(host, empty)
+        seen = sorted(stat.retry_after_seen)
+        tail = f"  {seen}" if stat.rate_limited else ""
+        print(f"{oc.total:>5} {oc.ok:>5} {oc.partial:>5} {oc.broken:>5} {stat.requests:>5} {stat.rate_limited:>4} "
+              f"{oc.status.get(401, 0):>4} {oc.status.get(403, 0):>4} {oc.status.get(404, 0):>4} "
+              f"{oc.other_http:>4} {oc.transport:>4} {stat.wait_seconds:>8.1f} "
+              f"{stat.head_fallbacks:>4} {stat.final_cap:>4}  {host}{tail}")
+
+
+def cmd_validate(args: list[str], progress: _Progress) -> int:
+    """Validate a built site and report broken references.
+
+    Usage: validate [root] [local] [all] [stats] [under=<subpath>]
+      local           skip external fetching (on-disk checks only)
+      all             include generated API and localized pages (default: authored content/*.md only)
+      stats           print per-host fetch diagnostics
+      under=<subpath> check only links from pages under root/<subpath> (anchors are still indexed site-wide)
+    """
+    flags = {arg for arg in args if arg in ("local", "all", "stats")}
+    under = next((arg[len("under=") :] for arg in args if arg.startswith("under=")), None)
+    positional = [arg for arg in args if arg not in flags and not arg.startswith("under=")]
+    root = Path(positional[0]) if positional else Path("_site")
+    source_prefix = os.path.normpath(root / under) if under else None
+
+    progress.phase = "enumerating"
+    refs, anchors_by_file = enumerate_site(root, source_prefix, progress)
+    existing = _existing_files(root)
+    progress.phase = "resolving"
+    refs = resolve_site_targets(refs, existing, root, live="local" not in flags)
+    stats: dict[str, HostStats] = {}
+    started = monotonic()
+    if "local" in flags:
+        refs = {target: sources for target, sources in refs.items() if target.kind == "local"}
+        external: dict[str, FetchResult] = {}
+    else:
+        progress.phase = "fetching external"
+        external, stats = fetch_all_external(refs, progress=progress)
+    elapsed = monotonic() - started
+
+    if progress.stop.is_set():  # Ctrl-C: drop the not-yet-fetched externals and flag the report as partial
+        external_urls = {target.resource for target in refs if target.kind == "external"}
+        print(
+            f"\nInterrupted: fetched {len(external)}/{len(external_urls)} external URL(s); report is partial.",
+            file=sys.stderr,
+        )
+        refs = {t: s for t, s in refs.items() if t.kind != "external" or t.resource in external}
+
+    progress.phase = "validating"
+    failures = validate(refs, anchors_by_file, existing, external)
+    exit_code = report(failures, root, content_only="all" not in flags)
+    if "stats" in flags:
+        print_diagnostics(stats, summarize_outcomes(external, failures), elapsed)
+    return exit_code
+
+
+COMMANDS: dict[str, Callable[[list[str], _Progress], int]] = {
+    "extract": cmd_extract,
+    "resolve": cmd_resolve,
+    "enumerate": cmd_enumerate,
+    "fetch": cmd_fetch,
+    "validate": cmd_validate,
+}
+
+
+def main(argv: list[str]) -> int:
+    if not argv or argv[0] not in COMMANDS:
+        print(f"usage: {Path(sys.argv[0]).name} <{'|'.join(COMMANDS)}> [args]", file=sys.stderr)
+        return 2
+
+    progress = _Progress(started=monotonic())
+
+    def on_stop(signum: int, frame: FrameType | None) -> None:
+        # Ctrl-C: ask the running command to wind down for a partial report; a second Ctrl-C force-quits.
+        if progress.stop.is_set():
+            os._exit(130)  # 128 + SIGINT: abandon in-flight work and exit now, no traceback
+        progress.stop.set()
+        print("\nstopping (Ctrl-C again to force-quit)...", file=sys.stderr)
+
+    def on_status(signum: int, frame: FrameType | None) -> None:
+        print(_status_line(progress, monotonic()), file=sys.stderr)
+
+    previous_handlers = _install_signal_handlers(on_stop, on_status)
+    try:
+        return COMMANDS[argv[0]](argv[1:], progress)
+    finally:
+        _restore_signal_handlers(previous_handlers)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
new file mode 100644
index 00000000..220c1be5
--- /dev/null
+++ b/build_scripts/csharp_doctest.py
@@ -0,0 +1,510 @@
+#!/usr/bin/env python3
+"""Validate the C# code blocks in the semantic-bridge how-to docs against the live TE CLI.
+
+Code blocks opt in via a fenced-code annotation (invisible in rendered docfx output):
+
+    ```csharp {compile}
+    ```csharp {run id=<slug> setup=<mv-sample|none> after=<id,...|none> output=<true|false>}
+
+Semantics:
+  - no annotation        -> skip (the only implicit behavior)
+  - {compile}            -> compile-only (te --dry-run); catches API drift, never executes
+  - {run ...}            -> execute; all four options are always required (no defaults)
+        id      unique slug, names the block for after= and for reporting
+        setup   a key in SETUP_SCRIPTS whose C# is prepended, or 'none'
+        after   comma-separated run ids replayed (flat, in order) before this block, or 'none'
+        output  'true' means the immediately-following plain fence is this block's
+                documented output -- compared in compare mode, rewritten in update mode
+
+Design: fences are parsed once into typed Block objects (the base Block is a skipped
+block; CompileBlock and RunBlock add behavior). Only the parser (_classify_fence) and
+the ref validator know the concrete kinds. Every command runs the same validate-first
+gate (_validate); validate then reports coverage, while compile/compare/update call
+block.check(mode) on every block -- each does its own work for that mode (skip: nothing;
+compile: compile-check; run: compile / execute-and-compare / execute-and-update) and
+reports an Outcome, which may carry an in-place fence edit (update mode). The functional
+core (parsing, plan, normalize, RunBlock._diff) is pure and independently testable; the
+imperative shell (Block.check, _run_mode, _write_with_edits, _report, main) does
+subprocess and file IO.
+
+Usage:
+    csharp_doctest.py <validate|compile|compare|update> <file>
+"""
+
+import difflib
+import re
+import sys
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from pathlib import Path
+from typing import ClassVar, NamedTuple
+
+from te_script_runner import Result, Snippet, run_snippets
+
+# Setup scripts prepended before a {run setup=<key>} block. Hard-coded here for now;
+# a future revision may derive them differently. The mv-sample script deserializes the
+# sample Metric View from the how-to include, read at import so there is a single source
+# of truth (the doc's own sample) rather than a drift-prone embedded copy.
+_INCLUDE_DIR = Path(__file__).resolve().parent.parent / "content" / "how-tos" / "includes"
+
+
+def _deserialize_from(yaml_path: Path) -> str:
+    """A C# snippet that deserializes a Metric View from the given yaml file's contents."""
+    yaml = yaml_path.read_text(encoding="utf-8")
+    return f'SemanticBridge.MetricView.Deserialize("""\n{yaml}""");'
+
+
+SETUP_SCRIPTS = {
+    "mv-sample": _deserialize_from(_INCLUDE_DIR / "sample-metricview.yaml"),
+}
+
+# A {run} block must set exactly these options, in this order (no defaults).
+RUN_OPTIONS = ("id", "setup", "after", "output")
+_ALLOWED_SETUPS = {*SETUP_SCRIPTS, "none"}
+
+# Subcommands. compile/compare/update execute against te and double as the modes passed
+# to Block.check; validate only parses and reports coverage.
+_EXECUTE_MODES = ("compile", "compare", "update")
+_COMMANDS = ("validate", *_EXECUTE_MODES)
+
+
+class Fence(NamedTuple):
+    """One fenced code block: language, {...} annotation, body, 1-based opening line, and body line span."""
+
+    lang: str
+    annotation: str
+    code: str
+    line: int
+    body_start: int  # 1-based first body line (exceeds body_end when the body is empty)
+    body_end: int  # 1-based last body line
+
+
+class Edit(NamedTuple):
+    """An in-place rewrite of a fence body: replace 1-based lines [start, end] with text."""
+
+    start: int
+    end: int
+    text: str
+
+
+class Outcome(NamedTuple):
+    """Result of a block's check() for a subcommand: what to print, whether it passed, and any file edit."""
+
+    block: "Block"
+    action: str  # verb shown in the report: "compile" | "compare" | "update"
+    passed: bool
+    detail: list[str]  # failure detail (diffs, compile/runtime errors) printed under the report line on stdout
+    note: str = ""  # short status shown inline on the report line (e.g. "updated")
+    edit: "Edit | None" = None  # a fence rewrite, applied in update mode
+
+
+@dataclass(frozen=True)
+class Block:
+    """A classified code block. The base behavior is a skipped block; subclasses add
+    compile/run behavior. Callers other than the parser and ref validator use this
+    interface (label, summary, register_refs, check) rather than inspecting the kind."""
+
+    code: str
+    line: int
+    kind: ClassVar[str] = "skip"
+
+    @property
+    def label(self) -> str:
+        """Identifier shown in reports; blank when the line already identifies the block."""
+        return ""
+
+    def summary(self) -> str:
+        """One-line description for the validate report."""
+        return f"L{self.line}\t{self.kind}"
+
+    def register_refs(self, seen: set[str]) -> None:
+        """Validate this block's cross-references against ids seen so far, and record its own."""
+        return None
+
+    def check(self, mode: str, runs: "dict[str, RunBlock]") -> "Outcome | None":
+        """Do this block's work for the subcommand mode; return an Outcome, or None if nothing to do. Imperative shell."""
+        return None
+
+
+@dataclass(frozen=True)
+class CompileBlock(Block):
+    """A {compile} block: compile-checked in every mode (compare/update imply compile), never executed."""
+
+    kind: ClassVar[str] = "compile"
+
+    def check(self, mode: str, runs: "dict[str, RunBlock]") -> "Outcome | None":
+        # Compiled in every mode that implies compilation; strict otherwise, so an
+        # unrecognized mode fails loudly rather than silently skipping the block.
+        if mode in _EXECUTE_MODES:
+            return _compile_check(self)
+        raise ValueError(f"unknown mode: {mode}")
+
+
+@dataclass(frozen=True)
+class RunBlock(Block):
+    """A fully-specified {run} block. documented is the following plain fence's text when output is true."""
+
+    id: str
+    setup: str
+    after: tuple[str, ...]
+    output: bool
+    documented: str | None
+    documented_span: tuple[int, int] | None  # (start, end) 1-based body lines of the documented fence
+    kind: ClassVar[str] = "run"
+
+    @property
+    def label(self) -> str:
+        return self.id
+
+    def summary(self) -> str:
+        after = ",".join(self.after) or "none"
+        has_documented = "yes" if self.documented is not None else "no"
+        return (
+            f"L{self.line}\trun\tid={self.id} setup={self.setup} "
+            f"after={after} output={str(self.output).lower()} documented={has_documented}"
+        )
+
+    def register_refs(self, seen: set[str]) -> None:
+        if self.id in seen:
+            raise ValueError(f"duplicate run id: {self.id}")
+        for ref in self.after:
+            if ref not in seen:
+                raise ValueError(f"run {self.id!r} after={ref!r} is not a run id defined earlier")
+        seen.add(self.id)
+
+    def plan(self, runs: "dict[str, RunBlock]") -> list[str]:
+        """The ordered C# scripts to execute for this block: setup + replayed after-blocks + own code. Pure.
+
+        after is flat: only the listed blocks' own code is replayed, in order. This
+        block's setup (not the referenced blocks') governs the preamble.
+        """
+        scripts: list[str] = []
+        if self.setup != "none":
+            scripts.append(SETUP_SCRIPTS[self.setup])
+        scripts.extend(runs[ref].code for ref in self.after)
+        scripts.append(self.code)
+        return scripts
+
+    def check(self, mode: str, runs: "dict[str, RunBlock]") -> "Outcome | None":
+        if mode == "compile":
+            return _compile_check(self)
+        # last_only: report only this block's Output(), not the setup/after replay that
+        # shares its te session (otherwise a dependency's output leaks into the diff).
+        result = run_snippets([Snippet("expr", script) for script in self.plan(runs)], last_only=True)
+        if mode == "compare":
+            return self._compare(result)
+        if mode == "update":
+            return self._update(result)
+        raise ValueError(f"unknown mode: {mode}")
+
+    def _diff(self, result: Result) -> tuple[bool, str, list[str]]:
+        """Compare produced output against documented output. Pure given result.
+
+        Returns (matches, produced, diff_lines). The only place that pairs the documented
+        (in-doc) and produced (fresh) outputs; both compare and update consume it.
+        """
+        documented = normalize(self.documented or "")
+        produced = normalize(result.output)
+        if produced == documented:
+            return True, produced, []
+        diff = difflib.unified_diff(
+            documented.splitlines(),
+            produced.splitlines(),
+            fromfile="documented",
+            tofile="produced",
+            lineterm="",
+        )
+        return False, produced, list(diff)
+
+    def _compare(self, result: Result) -> Outcome:
+        """compare-mode verdict: produced output must match the documented fence. Pure given result."""
+        if not result.success:
+            return Outcome(self, "compare", False, result.diagnostics)
+        if not self.output:
+            return Outcome(self, "compare", True, [])
+        matches, _, diff = self._diff(result)
+        return Outcome(self, "compare", matches, diff)
+
+    def _update(self, result: Result) -> Outcome:
+        """update-mode verdict plus a fence edit; the command applies the edit. Pure given result.
+
+        A failed run is reported without touching the doc. A matching or output=false
+        block needs no edit; otherwise the documented fence is rewritten with produced output.
+        """
+        if not result.success:
+            return Outcome(self, "update", False, result.diagnostics)
+        if not self.output or self.documented_span is None:
+            return Outcome(self, "update", True, [], note="no output")
+        matches, produced, _ = self._diff(result)
+        if matches:
+            return Outcome(self, "update", True, [], note="unchanged")
+        start, end = self.documented_span
+        return Outcome(self, "update", True, [], note="updated", edit=Edit(start, end, produced))
+
+
+def _annotation(info: str) -> str:
+    """The text inside the first {...} of a fence info string, or '' if there is none. Pure."""
+    open_brace = info.find("{")
+    close_brace = info.rfind("}")
+    if open_brace != -1 and close_brace > open_brace:
+        return info[open_brace + 1 : close_brace].strip()
+    return ""
+
+
+def parse_fences(markdown: str) -> list[Fence]:
+    """Extract every fenced code block from markdown, in order. Pure.
+
+    A line whose first non-space content is ``` toggles a fence. The opening fence's
+    remaining text is its info string; its first token is the language ('' for a plain
+    fence) and any {...} is the annotation.
+    """
+    fences: list[Fence] = []
+    lines = markdown.splitlines()
+    index = 0
+    while index < len(lines):
+        if not lines[index].lstrip().startswith("```"):
+            index += 1
+            continue
+        info = lines[index].lstrip()[3:].strip()
+        open_line = index + 1
+        body: list[str] = []
+        index += 1
+        body_start = index + 1  # 1-based first body line
+        while index < len(lines) and not lines[index].lstrip().startswith("```"):
+            body.append(lines[index])
+            index += 1
+        body_end = index  # 1-based last body line (< body_start when the body is empty)
+        lang = "" if not info or info.startswith("{") else info.split(None, 1)[0]
+        fences.append(Fence(lang, _annotation(info), "\n".join(body), open_line, body_start, body_end))
+        index += 1  # step past the closing fence
+    return fences
+
+
+def _parse_run_options(annotation: str) -> dict[str, str]:
+    """Parse and validate a {run ...} annotation's four options into a dict. Pure.
+
+    Every option is required with a valid value -- there are no defaults, so an
+    incompletely specified block is an error rather than a silent assumption.
+    """
+    params: dict[str, str] = {}
+    for token in annotation.split()[1:]:  # [0] is "run"
+        if "=" not in token:
+            raise ValueError(f"run option is not key=value: {token!r}")
+        key, value = token.split("=", 1)
+        if key in params:
+            raise ValueError(f"run block has duplicate option: {key}")
+        params[key] = value
+    missing = [opt for opt in RUN_OPTIONS if opt not in params]
+    if missing:
+        raise ValueError(f"run block missing required options: {', '.join(missing)}")
+    unknown = [key for key in params if key not in RUN_OPTIONS]
+    if unknown:
+        raise ValueError(f"run block has unknown options: {', '.join(unknown)}")
+    if params["id"] == "none":
+        raise ValueError("run block id must not be 'none' (reserved sentinel for after=none)")
+    # A slug id keeps ids clean and, by excluding commas, avoids colliding with the
+    # after= separator (a comma'd id would be unreferenceable). Also rejects empty ids.
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", params["id"]):
+        raise ValueError(f"run block id must be a slug of letters, digits, - or _, got {params['id']!r}")
+    if params["setup"] not in _ALLOWED_SETUPS:
+        raise ValueError(f"run block setup={params['setup']} is not a known setup key")
+    if params["output"] not in ("true", "false"):
+        raise ValueError(f"run block output must be true or false, got {params['output']!r}")
+    return params
+
+
+def _make_run_block(annotation: str, code: str, line: int, following: Fence | None) -> RunBlock:
+    """Build a validated RunBlock, resolving documented output from the following plain fence. Pure."""
+    params = _parse_run_options(annotation)
+    output = params["output"] == "true"
+    documented: str | None = None
+    documented_span: tuple[int, int] | None = None
+    if output:
+        if following is None or following.lang != "":
+            raise ValueError(
+                f"run block {params['id']!r} (line {line}) has output=true "
+                "but is not immediately followed by a plain output fence"
+            )
+        documented = following.code
+        documented_span = (following.body_start, following.body_end)
+    after = () if params["after"] == "none" else tuple(params["after"].split(","))
+    return RunBlock(
+        code=code,
+        line=line,
+        id=params["id"],
+        setup=params["setup"],
+        after=after,
+        output=output,
+        documented=documented,
+        documented_span=documented_span,
+    )
+
+
+def _classify_fence(fence: Fence, following: Fence | None) -> Block | None:
+    """Turn one fence into its typed Block, or None if it is not an actionable block. Pure.
+
+    This and _make_run_block are the only places that map annotations to kinds.
+    """
+    if fence.lang != "csharp":
+        # compile/run are only meaningful on csharp; flag them elsewhere rather than
+        # silently ignoring a block the author expected to be executed.
+        first = fence.annotation.split(None, 1)[0] if fence.annotation else ""
+        if first in ("compile", "run"):
+            raise ValueError(
+                f"{first} annotation is only valid on a csharp block "
+                f"(line {fence.line}, lang={fence.lang or 'plain'})"
+            )
+        return None
+    annotation = fence.annotation
+    if annotation == "":
+        return Block(fence.code, fence.line)  # untagged -> base block (skip)
+    if annotation == "compile":
+        return CompileBlock(fence.code, fence.line)
+    if annotation == "run" or annotation.startswith("run "):
+        return _make_run_block(annotation, fence.code, fence.line, following)
+    raise ValueError(f"unknown code-block annotation: {{{annotation}}}")
+
+
+def build_blocks(fences: list[Fence]) -> list[Block]:
+    """Classify the csharp fences into typed Blocks and validate cross-references. Pure."""
+    blocks: list[Block] = []
+    for position, fence in enumerate(fences):
+        following = fences[position + 1] if position + 1 < len(fences) else None
+        block = _classify_fence(fence, following)
+        if block is not None:
+            blocks.append(block)
+    seen: set[str] = set()
+    for block in blocks:
+        block.register_refs(seen)
+    return blocks
+
+
+def kind_counts(blocks: list[Block]) -> Counter[str]:
+    """Count blocks by kind. Pure."""
+    return Counter(block.kind for block in blocks)
+
+
+def index_runs(blocks: list[Block]) -> dict[str, RunBlock]:
+    """Map each run block's id to itself, in document order. Pure.
+
+    This is the one place that selects run blocks by type; callers use the map so an
+    after= reference resolves to the block whose code should be replayed.
+    """
+    return {block.id: block for block in blocks if isinstance(block, RunBlock)}
+
+
+def normalize(text: str) -> str:
+    """Normalize output for comparison. Pure.
+
+    Strict but forgiving of incidental whitespace: strip trailing whitespace from each
+    line and drop trailing blank lines. Interior content must match exactly.
+    """
+    lines = [line.rstrip() for line in text.splitlines()]
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines)
+
+
+def _compile_check(block: Block) -> Outcome:
+    """Compile-check a single block's code via te --dry-run (no execution). Imperative shell."""
+    result = run_snippets([Snippet("expr", block.code)], dry_run=True)
+    return Outcome(block, "compile", result.success, [] if result.success else result.diagnostics)
+
+
+def _report(outcomes: list[Outcome]) -> int:
+    """Print each outcome and a summary; return 1 if any failed. Imperative shell.
+
+    Verdicts, failure detail (diffs, compile/runtime errors), and the summary are the
+    report -- all on stdout. Only harness-operational problems go to stderr (raised and
+    handled in main), matching how test runners like pytest/go test stream results.
+    """
+    failures = 0
+    for outcome in outcomes:
+        status = "PASS" if outcome.passed else "FAIL"
+        tail = f" {outcome.block.label}" if outcome.block.label else ""
+        note = f" ({outcome.note})" if outcome.note else ""
+        print(f"L{outcome.block.line}\t{status}\t{outcome.action}{tail}{note}")
+        if not outcome.passed:
+            failures += 1
+            for line in outcome.detail:
+                print(f"    {line}")
+    print(f"# {len(outcomes)} block(s): {len(outcomes) - failures} pass, {failures} fail")
+    return 1 if failures else 0
+
+
+def _validate(path: str) -> tuple[str, list[Fence], list[Block]]:
+    """Parse and validate a doc's code-block annotations. Returns (text, fences, blocks). Imperative shell (reads the file).
+
+    build_blocks raises on any malformed block, so this is the gate every command runs
+    first -- compile/compare/update never touch te for a doc whose annotations are invalid.
+    """
+    text = Path(path).read_text(encoding="utf-8")
+    fences = parse_fences(text)
+    blocks = build_blocks(fences)
+    return text, fences, blocks
+
+
+def _run_mode(path: str, text: str, blocks: list[Block], mode: str) -> int:
+    """Run compile/compare/update over already-validated blocks; apply edits; report. Imperative shell.
+
+    Each block shells out to te against its own isolated model, so blocks are checked
+    concurrently (one thread per block -- a doc has few). Results are gathered in
+    document order; any fence edits (update mode) are then applied to the file in place,
+    single-threaded.
+    """
+    runs = index_runs(blocks)
+    with ThreadPoolExecutor(max_workers=max(1, len(blocks))) as pool:
+        results = list(pool.map(lambda block: block.check(mode, runs), blocks))
+    outcomes = [outcome for outcome in results if outcome is not None]
+    edits = [outcome.edit for outcome in outcomes if outcome.edit is not None]
+    if edits:
+        _write_with_edits(path, text, edits)
+    return _report(outcomes)
+
+
+def _write_with_edits(path: str, text: str, edits: list[Edit]) -> None:
+    """Apply fence-body rewrites to the file in place, bottom-up so line numbers stay valid. Imperative shell."""
+    lines = text.splitlines()
+    for edit in sorted(edits, key=lambda e: e.start, reverse=True):
+        lines[edit.start - 1 : edit.end] = edit.text.split("\n") if edit.text else []
+    Path(path).write_text("\n".join(lines) + ("\n" if text.endswith("\n") else ""), encoding="utf-8")
+
+
+def _coverage(fences: list[Fence], blocks: list[Block]) -> None:
+    """Print the validate report: one line per block plus coverage counts. Imperative shell."""
+    for block in blocks:
+        print(block.summary())
+    counts = kind_counts(blocks)
+    csharp = sum(1 for fence in fences if fence.lang == "csharp")
+    breakdown = ", ".join(f"{counts[kind]} {kind}" for kind in ("run", "compile", "skip"))
+    print(f"# {len(fences)} code blocks found ({csharp} csharp) | valid: {breakdown}")
+
+
+def main(argv: list[str]) -> int:
+    # One dispatcher for every subcommand. They share the single-path contract, the
+    # filename header (so batch runs like `xargs -n1` attribute each result to its file),
+    # and the validate-first gate. validate stops after the coverage report; the execute
+    # commands pass their own name to _run_mode as the block.check() mode.
+    if not argv or argv[0] not in _COMMANDS:
+        print(f"usage: {Path(sys.argv[0]).name} <{'|'.join(_COMMANDS)}> <file>", file=sys.stderr)
+        return 2
+    command, rest = argv[0], argv[1:]
+    if len(rest) != 1:
+        print(f"{command} requires exactly one markdown file path", file=sys.stderr)
+        return 2
+    path = rest[0]
+    print(path)
+    try:
+        text, fences, blocks = _validate(path)
+        if command == "validate":
+            _coverage(fences, blocks)
+            return 0
+        return _run_mode(path, text, blocks, command)
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"csharp_doctest: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/build_scripts/te_script_runner.py b/build_scripts/te_script_runner.py
new file mode 100755
index 00000000..98f7f2f2
--- /dev/null
+++ b/build_scripts/te_script_runner.py
@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""Run C# script snippets against a throwaway, empty semantic model via the TE CLI.
+
+Two uses:
+
+1. Standalone CLI (a subcommand is required):
+       te_script_runner.py run -e '<C# expr>'                # execute
+       te_script_runner.py run -f a.cs -e '<expr>' -f b.cs   # many, in order
+       te_script_runner.py check -f a.cs                     # compile-check only, no execution
+       cat snippet.cs | te_script_runner.py run              # one snippet on stdin
+   run and check take the same script arguments.
+
+2. Importable by an orchestrator (e.g. a semantic-bridge doc runner):
+       from te_script_runner import Snippet, run_snippets
+       result = run_snippets([Snippet("expr", preamble), Snippet("file", "block.cs")])
+
+The functional core (summarize and its helpers) is pure and independently
+testable; the imperative shell (init_model, run_snippets, the cmd_* wrappers)
+does subprocess, filesystem, and printing. Every layer is exposed as a COMMANDS
+subcommand so it can be exercised on its own.
+
+Snippets always run against a fresh empty model with no --save: nothing is
+persisted and nothing outside the throwaway directory is touched. Callers that
+need setup (e.g. a loaded Metric View) pass it as the first snippet.
+
+Usage:
+    te_script_runner.py <command> [args]
+"""
+
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, NamedTuple
+
+DEFAULT_TE_BIN = "te"
+_WORKDIR_PREFIX = "te-script-run."
+# Emitted between the next-to-last and last script when last_only is set, so the runner
+# can report only the final script's output. Chosen to be absent from any real output.
+_OUTPUT_BOUNDARY = "<<<te-script-runner-output-boundary>>>"
+
+
+class Result(NamedTuple):
+    """Outcome of a script run, distilled from te's --output-format json stdout.
+
+    output is the snippets' Output() text (newline-joined) -- what a caller
+    compares against expected. diagnostics are tagged non-output lines (compile
+    errors, runtime error, other messages) derived from the json. te's own stderr
+    is never captured -- it inherits the parent's stderr and always prints in full
+    -- so it does not appear here.
+    """
+
+    exit_code: int
+    success: bool
+    output: str
+    diagnostics: list[str]
+
+
+class Snippet(NamedTuple):
+    """One C# snippet: an inline expression (kind='expr') or a path to a file (kind='file')."""
+
+    kind: str
+    value: str
+
+
+def _parse_json(stdout: str) -> dict[str, Any] | None:
+    """te's json object, or None if stdout is empty or not a json object. Pure."""
+    if not stdout.strip():
+        return None
+    try:
+        parsed = json.loads(stdout)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _output_lines(data: dict[str, Any]) -> list[str]:
+    """The text of every output-level message, in order. Pure."""
+    messages = data.get("messages") or []
+    return [
+        str(m.get("text", ""))
+        for m in messages
+        if isinstance(m, dict) and m.get("level") == "output"
+    ]
+
+
+def _diagnostic_lines(data: dict[str, Any]) -> list[str]:
+    """Tagged non-output diagnostics: compile errors, runtime error, other messages. Pure.
+
+    te reports failures in three shapes -- compileErrors[], a runtimeError string,
+    and non-output messages[] -- and any of them can be present, so all three are
+    surfaced rather than only the first.
+    """
+    lines = [f"[compile-error] {e}" for e in data.get("compileErrors") or []]
+    runtime_error = data.get("runtimeError")
+    if runtime_error:
+        lines.append(f"[runtime-error] {runtime_error}")
+    lines += [
+        f"[{m.get('level')}] {m.get('text')}"
+        for m in data.get("messages") or []
+        if isinstance(m, dict) and m.get("level") != "output"
+    ]
+    return lines
+
+
+def _summarize_dry_run(data: dict[str, Any], exit_code: int) -> Result:
+    """Compile-only (--dry-run) results into a Result. Pure.
+
+    --dry-run reports a different shape than an executed run: a per-script
+    success/errors list under "scripts" and no messages, because nothing runs.
+    There is therefore no output; a compile failure in any script fails the whole.
+    """
+    scripts = data.get("scripts") or []
+    diagnostics: list[str] = []
+    all_ok = True
+    for script in scripts:
+        if not isinstance(script, dict):
+            continue
+        all_ok = all_ok and bool(script.get("success", False))
+        source = str(script.get("source", "<script>"))
+        diagnostics += [f"[compile-error] {source}: {e}" for e in script.get("errors") or []]
+    return Result(exit_code=exit_code, success=all_ok, output="", diagnostics=diagnostics)
+
+
+def summarize(stdout: str, exit_code: int) -> Result:
+    """Turn te's json stdout and exit code into a Result. Pure functional core.
+
+    Handles both te json shapes: an executed run (messages/compileErrors/
+    runtimeError) and a compile-only --dry-run (dryRun/scripts). When te emits no
+    json but failed, that fact is itself surfaced as a diagnostic so a failure is
+    never silently swallowed.
+    """
+    data = _parse_json(stdout)
+    if data is None:
+        diagnostics = (
+            [f"[te] failed with exit {exit_code} and no json output"]
+            if exit_code != 0
+            else []
+        )
+        return Result(exit_code, exit_code == 0, "", diagnostics)
+    if data.get("dryRun"):
+        return _summarize_dry_run(data, exit_code)
+    return Result(
+        exit_code=exit_code,
+        success=bool(data.get("success", exit_code == 0)),
+        output="\n".join(_output_lines(data)),
+        diagnostics=_diagnostic_lines(data),
+    )
+
+
+def parse_snippet_args(args: Sequence[str]) -> list[Snippet]:
+    """Parse repeated -e/-f arguments into ordered Snippets. Pure.
+
+    Order across -e and -f is preserved because the run relies on handing te one
+    ordered --script list (te otherwise runs all --script before all -e).
+    """
+    snippets: list[Snippet] = []
+    index = 0
+    while index < len(args):
+        flag = args[index]
+        if flag in ("-e", "--expression"):
+            kind = "expr"
+        elif flag in ("-f", "--file"):
+            kind = "file"
+        else:
+            raise ValueError(f"unexpected argument: {flag}")
+        if index + 1 >= len(args):
+            raise ValueError(f"{flag} requires a value")
+        snippets.append(Snippet(kind, args[index + 1]))
+        index += 2
+    return snippets
+
+
+def _emit(result: Result) -> int:
+    """Write a Result to the real streams the way the standalone CLI should. Imperative shell.
+
+    te's own stderr has already streamed through (it is never captured), so this
+    only adds the snippets' Output() to stdout and the derived diagnostics to stderr.
+    """
+    if result.output:
+        print(result.output)
+    if result.diagnostics:
+        print("\n".join(result.diagnostics), file=sys.stderr)
+    return result.exit_code
+
+
+def init_model(model_path: Path, *, te_bin: str = DEFAULT_TE_BIN) -> Path:
+    """Create an empty single-file .bim model at model_path and return its path. Imperative shell.
+
+    Adds no output of its own: te init's stdout summary is discarded (the throwaway
+    model is an implementation detail). Its stderr inherits the parent's and prints
+    in full. Raises on failure; the detail has already printed on stderr.
+    """
+    proc = subprocess.run(
+        [te_bin, "init", str(model_path), "--serialization", "bim"],
+        stdout=subprocess.DEVNULL,
+        text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(f"te init failed (exit {proc.returncode}); see stderr above")
+    return model_path
+
+
+def materialize(snippets: Sequence[Snippet], snippet_dir: Path) -> list[Path]:
+    """Write every snippet to a .cs file under snippet_dir, preserving order. Imperative shell.
+
+    Inline expressions become numbered files; file snippets are used in place after
+    an existence check. All are handed to te as --script (see parse_snippet_args).
+    """
+    snippet_dir.mkdir(parents=True, exist_ok=True)
+    files: list[Path] = []
+    for index, snippet in enumerate(snippets, start=1):
+        if snippet.kind == "expr":
+            path = snippet_dir / f"{index:02d}-inline.cs"
+            path.write_text(snippet.value + "\n", encoding="utf-8")
+        else:
+            path = Path(snippet.value)
+            if not path.is_file():
+                raise FileNotFoundError(f"script file not found: {snippet.value}")
+        files.append(path)
+    return files
+
+
+def run_te_script(
+    model_path: Path,
+    script_files: Sequence[Path],
+    *,
+    te_bin: str = DEFAULT_TE_BIN,
+    dry_run: bool = False,
+) -> tuple[int, str]:
+    """Run script files in order against model_path in one te session. Imperative shell.
+
+    Returns (exit_code, json_stdout). One session means mutations carry across the
+    files. With dry_run, te compiles the scripts and reports errors without executing
+    them (a different json shape; summarize handles both). stdout is captured for
+    summarize; stderr inherits the parent's and prints in full. No --save, so nothing
+    is persisted.
+    """
+    cmd = [te_bin, "--output-format", "json", "script", str(model_path)]
+    for path in script_files:
+        cmd += ["--script", str(path)]
+    if dry_run:
+        cmd.append("--dry-run")
+    proc = subprocess.run(cmd, stdout=subprocess.PIPE, text=True)
+    return proc.returncode, proc.stdout
+
+
+def _keep_after_boundary(result: Result) -> Result:
+    """Drop everything up to and including the last-only boundary marker. Pure.
+
+    The scripts run in one te session (the only way shared state, e.g. a loaded Metric
+    View, survives), so te reports every script's output in one flat list. To report
+    only the final script's output, a boundary marker is emitted just before it and
+    everything up to it is dropped here.
+
+    A failed run (any script errors -> te stops) is returned unchanged, with the full
+    output and diagnostics -- the whole invocation failed. If the run succeeded but the
+    marker is missing, that is also treated as a failure rather than silently trusted.
+    """
+    if not result.success:
+        return result
+    lines = result.output.split("\n") if result.output else []
+    if _OUTPUT_BOUNDARY not in lines:
+        return result._replace(
+            exit_code=result.exit_code or 1,
+            success=False,
+            diagnostics=[*result.diagnostics, "[harness] output boundary marker missing"],
+        )
+    cut = len(lines) - 1 - lines[::-1].index(_OUTPUT_BOUNDARY)  # last occurrence is ours
+    return result._replace(output="\n".join(lines[cut + 1 :]))
+
+
+def run_snippets(
+    snippets: Sequence[Snippet],
+    *,
+    te_bin: str = DEFAULT_TE_BIN,
+    keep_workdir: bool = False,
+    dry_run: bool = False,
+    last_only: bool = False,
+) -> Result:
+    """Run snippets in order against one fresh, empty .bim model; return a Result. Imperative shell.
+
+    This is the importable entry point. With dry_run the snippets are compiled but not
+    executed (Result.output is empty; compile errors land in Result.diagnostics). With
+    last_only, only the final snippet's Output() is reported (earlier snippets are setup
+    whose output is noise); this is done by emitting a boundary marker before the last
+    script and dropping everything up to it -- necessary because the snippets share one
+    te session and te reports all their output in one flat list. It adds no output of its
+    own (only te's inherited stderr streams through), so an orchestrator can consume the
+    Result as data. The throwaway directory is always removed unless keep_workdir. Raises
+    if te is missing or the model cannot be created.
+    """
+    if not snippets:
+        raise ValueError("run_snippets requires at least one snippet")
+    if shutil.which(te_bin) is None:
+        raise FileNotFoundError(f"{te_bin!r} (Tabular Editor CLI) not found on PATH")
+    workdir = Path(tempfile.mkdtemp(prefix=_WORKDIR_PREFIX))
+    try:
+        model_path = init_model(workdir / "model.bim", te_bin=te_bin)
+        snippet_dir = workdir / "snippets"
+        script_files = materialize(snippets, snippet_dir)
+        bounded = last_only and not dry_run and len(script_files) > 1
+        if bounded:
+            boundary = snippet_dir / "00-boundary.cs"
+            boundary.write_text(f'Output("{_OUTPUT_BOUNDARY}");\n', encoding="utf-8")
+            script_files = [*script_files[:-1], boundary, script_files[-1]]
+        exit_code, stdout = run_te_script(model_path, script_files, te_bin=te_bin, dry_run=dry_run)
+        result = summarize(stdout, exit_code)
+        return _keep_after_boundary(result) if bounded else result
+    finally:
+        if keep_workdir:
+            print(f"[keep] throwaway dir retained: {workdir}", file=sys.stderr)
+        else:
+            shutil.rmtree(workdir, ignore_errors=True)
+
+
+def _gather_snippets(args: list[str]) -> tuple[list[Snippet], bool]:
+    """Parse the shared -e/-f/--keep args (or read one snippet from stdin). Returns (snippets, keep).
+
+    run and check take identical script arguments; this is where that shared parse lives.
+    """
+    keep = "--keep" in args
+    snippets = parse_snippet_args([a for a in args if a != "--keep"])
+    if not snippets:
+        if sys.stdin.isatty():
+            raise ValueError("no snippet provided; use -e, -f, or pipe C# on stdin")
+        snippets = [Snippet("expr", sys.stdin.read())]
+    return snippets, keep
+
+
+def cmd_run(args: list[str]) -> int:
+    """Execute snippets from -e/-f (in order) or stdin against a throwaway model. --keep retains the dir."""
+    snippets, keep = _gather_snippets(args)
+    return _emit(run_snippets(snippets, keep_workdir=keep))
+
+
+def cmd_check(args: list[str]) -> int:
+    """Compile-check snippets from -e/-f (in order) or stdin without executing them. --keep retains the dir."""
+    snippets, keep = _gather_snippets(args)
+    return _emit(run_snippets(snippets, keep_workdir=keep, dry_run=True))
+
+
+def cmd_init(args: list[str]) -> int:
+    """Create an empty .bim model at <path> and print the path (for testing the init step)."""
+    if not args:
+        raise ValueError("init requires a model path")
+    print(init_model(Path(args[0])))
+    return 0
+
+
+def cmd_summarize(args: list[str]) -> int:
+    """Summarize te json from <file> (or stdin if '-'), at optional [exit_code] (default 0)."""
+    stdout = sys.stdin.read() if not args or args[0] == "-" else Path(args[0]).read_text(encoding="utf-8")
+    exit_code = int(args[1]) if len(args) > 1 else 0
+    return _emit(summarize(stdout, exit_code))
+
+
+COMMANDS = {
+    "run": cmd_run,
+    "check": cmd_check,
+    "init": cmd_init,
+    "summarize": cmd_summarize,
+}
+
+
+def main(argv: list[str]) -> int:
+    if not argv or argv[0] not in COMMANDS:
+        print(f"usage: {Path(sys.argv[0]).name} <{'|'.join(COMMANDS)}> [args]", file=sys.stderr)
+        return 2
+    try:
+        return COMMANDS[argv[0]](argv[1:])
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"te_script_runner: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))
diff --git a/build_scripts/test-fixtures/doc-compile-drift.md b/build_scripts/test-fixtures/doc-compile-drift.md
new file mode 100644
index 00000000..0af2190b
--- /dev/null
+++ b/build_scripts/test-fixtures/doc-compile-drift.md
@@ -0,0 +1,13 @@
+# Compile drift
+
+Good compile block:
+
+```csharp {compile}
+var view = SemanticBridge.MetricView.Model;
+```
+
+Run block that calls a nonexistent API (compile FAIL):
+
+```csharp {run id=bad setup=none after=none output=false}
+SemanticBridge.MetricView.NoSuchMethod();
+```
diff --git a/build_scripts/test-fixtures/doc-mismatch.md b/build_scripts/test-fixtures/doc-mismatch.md
new file mode 100644
index 00000000..6a756b5c
--- /dev/null
+++ b/build_scripts/test-fixtures/doc-mismatch.md
@@ -0,0 +1,9 @@
+# Mismatch
+
+```csharp {run id=wrong setup=none after=none output=true}
+Output("actual text");
+```
+**Output:**
+```
+expected text
+```
diff --git a/build_scripts/test-fixtures/doc-valid.md b/build_scripts/test-fixtures/doc-valid.md
new file mode 100644
index 00000000..d79dd135
--- /dev/null
+++ b/build_scripts/test-fixtures/doc-valid.md
@@ -0,0 +1,35 @@
+# Valid doc
+
+Untagged csharp block is skipped:
+
+```csharp
+Output("ignored by the harness");
+```
+
+Compile-only block:
+
+```csharp {compile}
+var view = SemanticBridge.MetricView.Model;
+```
+
+Run block with expected output:
+
+```csharp {run id=first setup=mv-sample after=none output=true}
+Output("hello from a run block");
+```
+**Output:**
+```
+hello from a run block
+```
+
+Chained run block, no output assertion:
+
+```csharp {run id=second setup=none after=first output=false}
+Output("chained after first");
+```
+
+A non-csharp block is ignored:
+
+```yaml
+version: 1.1
+```
diff --git a/build_scripts/test-fixtures/err-missing-option.md b/build_scripts/test-fixtures/err-missing-option.md
new file mode 100644
index 00000000..115488fa
--- /dev/null
+++ b/build_scripts/test-fixtures/err-missing-option.md
@@ -0,0 +1,3 @@
+```csharp {run id=x setup=none output=true}
+Output(1);
+```
diff --git a/build_scripts/test-fixtures/err-no-output-fence.md b/build_scripts/test-fixtures/err-no-output-fence.md
new file mode 100644
index 00000000..704629e0
--- /dev/null
+++ b/build_scripts/test-fixtures/err-no-output-fence.md
@@ -0,0 +1,5 @@
+```csharp {run id=x setup=none after=none output=true}
+Output(1);
+```
+
+No output fence follows this run block.
diff --git a/build_scripts/test-fixtures/err-run-on-yaml.md b/build_scripts/test-fixtures/err-run-on-yaml.md
new file mode 100644
index 00000000..21cb44cb
--- /dev/null
+++ b/build_scripts/test-fixtures/err-run-on-yaml.md
@@ -0,0 +1,3 @@
+```yaml {compile}
+version: 1
+```
diff --git a/build_scripts/test-fixtures/err-unknown-after.md b/build_scripts/test-fixtures/err-unknown-after.md
new file mode 100644
index 00000000..c689fa42
--- /dev/null
+++ b/build_scripts/test-fixtures/err-unknown-after.md
@@ -0,0 +1,3 @@
+```csharp {run id=x setup=none after=nope output=false}
+Output(1);
+```
diff --git a/build_scripts/test-fixtures/err-unknown-annotation.md b/build_scripts/test-fixtures/err-unknown-annotation.md
new file mode 100644
index 00000000..5db65c4d
--- /dev/null
+++ b/build_scripts/test-fixtures/err-unknown-annotation.md
@@ -0,0 +1,3 @@
+```csharp {check}
+Output(1);
+```
diff --git a/build_scripts/test-fixtures/te-compile-error.json b/build_scripts/test-fixtures/te-compile-error.json
new file mode 100644
index 00000000..2b6ecbf7
--- /dev/null
+++ b/build_scripts/test-fixtures/te-compile-error.json
@@ -0,0 +1 @@
+{"success":false,"compileErrors":["error: ; expected"],"messages":[]}
diff --git a/build_scripts/test-fixtures/te-dryrun-fail.json b/build_scripts/test-fixtures/te-dryrun-fail.json
new file mode 100644
index 00000000..95ae1b8a
--- /dev/null
+++ b/build_scripts/test-fixtures/te-dryrun-fail.json
@@ -0,0 +1 @@
+{"dryRun":true,"scripts":[{"source":"01-inline.cs","success":false,"errors":["error: no method 'Foo'"]},{"source":"02-inline.cs","success":true,"errors":[]}]}
diff --git a/build_scripts/test-fixtures/te-dryrun-ok.json b/build_scripts/test-fixtures/te-dryrun-ok.json
new file mode 100644
index 00000000..ad720b1a
--- /dev/null
+++ b/build_scripts/test-fixtures/te-dryrun-ok.json
@@ -0,0 +1 @@
+{"dryRun":true,"scripts":[{"source":"01-inline.cs","success":true,"errors":[]}]}
diff --git a/build_scripts/test-fixtures/te-run-ok.json b/build_scripts/test-fixtures/te-run-ok.json
new file mode 100644
index 00000000..23377318
--- /dev/null
+++ b/build_scripts/test-fixtures/te-run-ok.json
@@ -0,0 +1 @@
+{"success":true,"durationMs":10,"scriptsExecuted":1,"messages":[{"level":"output","text":"line1"},{"level":"output","text":"line2"}],"saved":false}
diff --git a/build_scripts/test-fixtures/te-runtime-error.json b/build_scripts/test-fixtures/te-runtime-error.json
new file mode 100644
index 00000000..8d1ad623
--- /dev/null
+++ b/build_scripts/test-fixtures/te-runtime-error.json
@@ -0,0 +1 @@
+{"success":false,"runtimeError":"boom","compileErrors":[],"messages":[{"level":"info","text":"note"}]}