From c522401ceeb7004720125a88ec0944a813338d67 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Thu, 25 Jun 2026 17:03:20 +0200
Subject: [PATCH 01/14] build-docs.py: add iterative development conveniences

---
 build-docs.py | 124 +++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 112 insertions(+), 12 deletions(-)

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
         

From 587da826e9ffa8cd01a42a8ec744aecc9ef8b253 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Wed, 1 Jul 2026 20:42:15 +0200
Subject: [PATCH 02/14] add standalone dead link checker

---
 build_scripts/check_links.py | 705 +++++++++++++++++++++++++++++++++++
 1 file changed, 705 insertions(+)
 create mode 100644 build_scripts/check_links.py

diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
new file mode 100644
index 00000000..bd7a92c1
--- /dev/null
+++ b/build_scripts/check_links.py
@@ -0,0 +1,705 @@
+#!/usr/bin/env python
+"""
+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 os
+import sys
+import urllib.error
+import urllib.request
+from collections import defaultdict, deque
+from html.parser import HTMLParser
+from pathlib import Path
+from queue import Empty, Queue
+from threading import Thread
+from time import monotonic
+from typing import NamedTuple
+from urllib.parse import unquote, urldefrag, urlsplit
+
+
+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]) -> 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()
+
+# 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]) -> 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
+) -> 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."""
+    refs: dict[Target, dict[str, list[int]]] = {}
+    anchors_by_file: dict[str, set[str]] = {}
+    for page in root.rglob("*.html"):
+        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)
+    return refs, anchors_by_file
+
+
+def cmd_enumerate(args: list[str]) -> 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)
+    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"
+)
+
+
+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().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 (urllib.error.URLError, TimeoutError, ValueError) as error:
+            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 = 8
+) -> 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."""
+    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)
+    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:
+            done_q.put((task, fetch_external(task.url, task.need_body)))
+
+    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)
+
+    workers = [Thread(target=worker) for _ in range(max_workers)]
+    for thread in workers:
+        thread.start()
+
+    remaining = len(need_body)
+    admit()
+    while remaining:
+        try:
+            task, result = done_q.get(timeout=_next_cooldown_wait(pending, cooldown, monotonic()))
+        except Empty:
+            admit()  # a cooldown expired; that host is eligible again
+            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()
+
+    for _ in workers:
+        work_q.put(None)
+    for thread in workers:
+        thread.join()
+
+    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]) -> 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:
+          https://example.com/gone
+    """
+    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:
+        urls = {_display_url(failure.target) for breaks in warnings.values() for failure, _ in breaks}
+        print("External URLs to verify:")
+        for url in sorted(urls):
+            print(url)
+
+    return 1 if errors else 0
+
+
+def print_diagnostics(stats: dict[str, HostStats], elapsed: float) -> None:
+    """Print per-host fetch diagnostics: requests, 429s, cooldown time, HEAD fallbacks, final cap, Retry-After set."""
+    active = {host: stat for host, stat in stats.items() if stat.requests}
+    print(f"\n--- fetch diagnostics ({elapsed:.1f}s, {len(active)} hosts) ---")
+    print(f"{'reqs':>5} {'429s':>5} {'wait(s)':>8} {'fb':>4} {'cap':>4}  host  [retry-after seen]")
+    ranked = sorted(active.items(), key=lambda kv: (kv[1].rate_limited, kv[1].wait_seconds), reverse=True)
+    for host, stat in ranked:
+        seen = sorted(stat.retry_after_seen)
+        tail = f"  {seen}" if stat.rate_limited else ""
+        print(f"{stat.requests:>5} {stat.rate_limited:>5} {stat.wait_seconds:>8.1f} "
+              f"{stat.head_fallbacks:>4} {stat.final_cap:>4}  {host}{tail}")
+
+
+def cmd_validate(args: list[str]) -> 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
+
+    refs, anchors_by_file = enumerate_site(root, source_prefix)
+    existing = _existing_files(root)
+    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:
+        external, stats = fetch_all_external(refs)
+    elapsed = monotonic() - started
+
+    exit_code = report(validate(refs, anchors_by_file, existing, external), root, content_only="all" not in flags)
+    if "stats" in flags:
+        print_diagnostics(stats, elapsed)
+    return exit_code
+
+
+COMMANDS = {
+    "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
+    return COMMANDS[argv[0]](argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

From 4a511fb5161f92b77cb27b829afe1bc58c03bf98 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Thu, 2 Jul 2026 23:54:48 +0200
Subject: [PATCH 03/14] Add csharp_doctest tooling and fixtures

---
 build_scripts/csharp_doctest.py               | 505 ++++++++++++++++++
 build_scripts/te_script_runner.py             | 341 ++++++++++++
 .../test-fixtures/doc-compile-drift.md        |  13 +
 build_scripts/test-fixtures/doc-mismatch.md   |   9 +
 build_scripts/test-fixtures/doc-valid.md      |  35 ++
 .../test-fixtures/err-missing-option.md       |   3 +
 .../test-fixtures/err-no-output-fence.md      |   5 +
 .../test-fixtures/err-run-on-yaml.md          |   3 +
 .../test-fixtures/err-unknown-after.md        |   3 +
 .../test-fixtures/err-unknown-annotation.md   |   3 +
 .../test-fixtures/te-compile-error.json       |   1 +
 .../test-fixtures/te-dryrun-fail.json         |   1 +
 build_scripts/test-fixtures/te-dryrun-ok.json |   1 +
 build_scripts/test-fixtures/te-run-ok.json    |   1 +
 .../test-fixtures/te-runtime-error.json       |   1 +
 15 files changed, 925 insertions(+)
 create mode 100644 build_scripts/csharp_doctest.py
 create mode 100755 build_scripts/te_script_runner.py
 create mode 100644 build_scripts/test-fixtures/doc-compile-drift.md
 create mode 100644 build_scripts/test-fixtures/doc-mismatch.md
 create mode 100644 build_scripts/test-fixtures/doc-valid.md
 create mode 100644 build_scripts/test-fixtures/err-missing-option.md
 create mode 100644 build_scripts/test-fixtures/err-no-output-fence.md
 create mode 100644 build_scripts/test-fixtures/err-run-on-yaml.md
 create mode 100644 build_scripts/test-fixtures/err-unknown-after.md
 create mode 100644 build_scripts/test-fixtures/err-unknown-annotation.md
 create mode 100644 build_scripts/test-fixtures/te-compile-error.json
 create mode 100644 build_scripts/test-fixtures/te-dryrun-fail.json
 create mode 100644 build_scripts/test-fixtures/te-dryrun-ok.json
 create mode 100644 build_scripts/test-fixtures/te-run-ok.json
 create mode 100644 build_scripts/test-fixtures/te-runtime-error.json

diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
new file mode 100644
index 00000000..8fc528f2
--- /dev/null
+++ b/build_scripts/csharp_doctest.py
@@ -0,0 +1,505 @@
+#!/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. A subcommand runs by calling block.check(mode) on every block: each block 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,
+_write_with_edits, _report, cmd_* wrappers) does subprocess and file IO. Every layer is
+a COMMANDS subcommand.
+
+Usage:
+    csharp_doctest.py <command> [args]
+"""
+
+import difflib
+import re
+import sys
+from collections import Counter
+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"}
+
+
+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]  # lines emitted to stderr when it fails
+    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 ("compile", "compare", "update"):
+            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)
+        result = run_snippets([Snippet("expr", script) for script in self.plan(runs)])
+        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 PASS/FAIL per outcome (failure detail to stderr) and a summary; return 1 if any failed. Imperative shell."""
+    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}", file=sys.stderr)
+    print(f"# {len(outcomes)} block(s): {len(outcomes) - failures} pass, {failures} fail")
+    return 1 if failures else 0
+
+
+def _process(path: str, mode: str) -> int:
+    """Run one subcommand mode over every block in a doc via block.check(). Imperative shell.
+
+    Any fence edits the blocks return (update mode) are applied to the file in place.
+    """
+    text = Path(path).read_text(encoding="utf-8")
+    blocks = build_blocks(parse_fences(text))
+    runs = index_runs(blocks)
+    outcomes = [outcome for block in blocks if (outcome := block.check(mode, runs)) 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 cmd_validate(args: list[str]) -> int:
+    """Validate the code-block annotations in a how-to <file> and report coverage counts.
+
+    build_blocks is the validation pass; it raises on any malformed block, so the
+    report is printed only when every {compile}/{run} block is valid.
+    """
+    if not args:
+        raise ValueError("validate requires a markdown file path")
+    fences = parse_fences(Path(args[0]).read_text(encoding="utf-8"))
+    blocks = build_blocks(fences)
+    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}")
+    return 0
+
+
+def cmd_compile(args: list[str]) -> int:
+    """Compile-check every {compile} and {run} block in <file> against the live TE CLI (no execution)."""
+    if not args:
+        raise ValueError("compile requires a markdown file path")
+    return _process(args[0], "compile")
+
+
+def cmd_compare(args: list[str]) -> int:
+    """Execute every {run} block in <file> and diff Output() vs the documented fence; also compile {compile} blocks."""
+    if not args:
+        raise ValueError("compare requires a markdown file path")
+    return _process(args[0], "compare")
+
+
+def cmd_update(args: list[str]) -> int:
+    """Execute every {run} block in <file> and rewrite each documented fence in place with produced Output(); also compile {compile} blocks."""
+    if not args:
+        raise ValueError("update requires a markdown file path")
+    return _process(args[0], "update")
+
+
+COMMANDS = {
+    "validate": cmd_validate,
+    "compile": cmd_compile,
+    "compare": cmd_compare,
+    "update": cmd_update,
+}
+
+
+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) 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..d1ea132a
--- /dev/null
+++ b/build_scripts/te_script_runner.py
@@ -0,0 +1,341 @@
+#!/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."
+
+
+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 run_snippets(
+    snippets: Sequence[Snippet],
+    *,
+    te_bin: str = DEFAULT_TE_BIN,
+    keep_workdir: bool = False,
+    dry_run: 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).
+    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)
+        script_files = materialize(snippets, workdir / "snippets")
+        exit_code, stdout = run_te_script(model_path, script_files, te_bin=te_bin, dry_run=dry_run)
+        return summarize(stdout, exit_code)
+    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"}]}

From a498c897f18eb0927e4af7ebe828b99e2ffd90d0 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 00:06:08 +0200
Subject: [PATCH 04/14] parallelize csharp_doctest.py

---
 build_scripts/csharp_doctest.py | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
index 8fc528f2..f48a0e81 100644
--- a/build_scripts/csharp_doctest.py
+++ b/build_scripts/csharp_doctest.py
@@ -34,6 +34,7 @@
 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
@@ -422,12 +423,17 @@ def _report(outcomes: list[Outcome]) -> int:
 def _process(path: str, mode: str) -> int:
     """Run one subcommand mode over every block in a doc via block.check(). Imperative shell.
 
-    Any fence edits the blocks return (update mode) are applied to the file in place.
+    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.
     """
     text = Path(path).read_text(encoding="utf-8")
     blocks = build_blocks(parse_fences(text))
     runs = index_runs(blocks)
-    outcomes = [outcome for block in blocks if (outcome := block.check(mode, runs)) is not None]
+    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)
@@ -448,8 +454,8 @@ def cmd_validate(args: list[str]) -> int:
     build_blocks is the validation pass; it raises on any malformed block, so the
     report is printed only when every {compile}/{run} block is valid.
     """
-    if not args:
-        raise ValueError("validate requires a markdown file path")
+    if len(args) != 1:
+        raise ValueError("validate requires exactly one markdown file path")
     fences = parse_fences(Path(args[0]).read_text(encoding="utf-8"))
     blocks = build_blocks(fences)
     for block in blocks:
@@ -463,22 +469,22 @@ def cmd_validate(args: list[str]) -> int:
 
 def cmd_compile(args: list[str]) -> int:
     """Compile-check every {compile} and {run} block in <file> against the live TE CLI (no execution)."""
-    if not args:
-        raise ValueError("compile requires a markdown file path")
+    if len(args) != 1:
+        raise ValueError("compile requires exactly one markdown file path")
     return _process(args[0], "compile")
 
 
 def cmd_compare(args: list[str]) -> int:
     """Execute every {run} block in <file> and diff Output() vs the documented fence; also compile {compile} blocks."""
-    if not args:
-        raise ValueError("compare requires a markdown file path")
+    if len(args) != 1:
+        raise ValueError("compare requires exactly one markdown file path")
     return _process(args[0], "compare")
 
 
 def cmd_update(args: list[str]) -> int:
     """Execute every {run} block in <file> and rewrite each documented fence in place with produced Output(); also compile {compile} blocks."""
-    if not args:
-        raise ValueError("update requires a markdown file path")
+    if len(args) != 1:
+        raise ValueError("update requires exactly one markdown file path")
     return _process(args[0], "update")
 
 

From 4c1f1d8bdf36df17657bd9d42f8b288222e1a0c7 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 00:13:32 +0200
Subject: [PATCH 05/14] fix exception handling in csharp_doctest.py

---
 build_scripts/csharp_doctest.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
index f48a0e81..90f61cd5 100644
--- a/build_scripts/csharp_doctest.py
+++ b/build_scripts/csharp_doctest.py
@@ -502,7 +502,7 @@ def main(argv: list[str]) -> int:
         return 2
     try:
         return COMMANDS[argv[0]](argv[1:])
-    except (OSError, ValueError) as exc:
+    except (OSError, ValueError, RuntimeError) as exc:
         print(f"csharp_doctest: {exc}", file=sys.stderr)
         return 1
 

From 94bf91cd8e0cfb5c023534069a728b8a4a7efeba Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 02:25:56 +0200
Subject: [PATCH 06/14] streamline and filter last script output for csharp
 build scripts

---
 build_scripts/csharp_doctest.py   | 117 +++++++++++++++---------------
 build_scripts/te_script_runner.py |  54 ++++++++++++--
 2 files changed, 105 insertions(+), 66 deletions(-)

diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
index 90f61cd5..597b6063 100644
--- a/build_scripts/csharp_doctest.py
+++ b/build_scripts/csharp_doctest.py
@@ -18,16 +18,17 @@
 
 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. A subcommand runs by calling block.check(mode) on every block: each block 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,
-_write_with_edits, _report, cmd_* wrappers) does subprocess and file IO. Every layer is
-a COMMANDS subcommand.
+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 <command> [args]
+    csharp_doctest.py <validate|compile|compare|update> <file>
 """
 
 import difflib
@@ -62,6 +63,11 @@ def _deserialize_from(yaml_path: Path) -> str:
 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."""
@@ -130,7 +136,7 @@ class CompileBlock(Block):
     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 ("compile", "compare", "update"):
+        if mode in _EXECUTE_MODES:
             return _compile_check(self)
         raise ValueError(f"unknown mode: {mode}")
 
@@ -183,7 +189,9 @@ def plan(self, runs: "dict[str, RunBlock]") -> list[str]:
     def check(self, mode: str, runs: "dict[str, RunBlock]") -> "Outcome | None":
         if mode == "compile":
             return _compile_check(self)
-        result = run_snippets([Snippet("expr", script) for script in self.plan(runs)])
+        # 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":
@@ -405,7 +413,12 @@ def _compile_check(block: Block) -> Outcome:
 
 
 def _report(outcomes: list[Outcome]) -> int:
-    """Print PASS/FAIL per outcome (failure detail to stderr) and a summary; return 1 if any failed. Imperative shell."""
+    """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"
@@ -415,21 +428,31 @@ def _report(outcomes: list[Outcome]) -> int:
         if not outcome.passed:
             failures += 1
             for line in outcome.detail:
-                print(f"    {line}", file=sys.stderr)
+                print(f"    {line}")
     print(f"# {len(outcomes)} block(s): {len(outcomes) - failures} pass, {failures} fail")
     return 1 if failures else 0
 
 
-def _process(path: str, mode: str) -> int:
-    """Run one subcommand mode over every block in a doc via block.check(). Imperative shell.
+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.
     """
-    text = Path(path).read_text(encoding="utf-8")
-    blocks = build_blocks(parse_fences(text))
     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))
@@ -448,60 +471,36 @@ def _write_with_edits(path: str, text: str, edits: list[Edit]) -> None:
     Path(path).write_text("\n".join(lines) + ("\n" if text.endswith("\n") else ""), encoding="utf-8")
 
 
-def cmd_validate(args: list[str]) -> int:
-    """Validate the code-block annotations in a how-to <file> and report coverage counts.
-
-    build_blocks is the validation pass; it raises on any malformed block, so the
-    report is printed only when every {compile}/{run} block is valid.
-    """
-    if len(args) != 1:
-        raise ValueError("validate requires exactly one markdown file path")
-    fences = parse_fences(Path(args[0]).read_text(encoding="utf-8"))
-    blocks = build_blocks(fences)
+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}")
-    return 0
-
-
-def cmd_compile(args: list[str]) -> int:
-    """Compile-check every {compile} and {run} block in <file> against the live TE CLI (no execution)."""
-    if len(args) != 1:
-        raise ValueError("compile requires exactly one markdown file path")
-    return _process(args[0], "compile")
-
-
-def cmd_compare(args: list[str]) -> int:
-    """Execute every {run} block in <file> and diff Output() vs the documented fence; also compile {compile} blocks."""
-    if len(args) != 1:
-        raise ValueError("compare requires exactly one markdown file path")
-    return _process(args[0], "compare")
-
-
-def cmd_update(args: list[str]) -> int:
-    """Execute every {run} block in <file> and rewrite each documented fence in place with produced Output(); also compile {compile} blocks."""
-    if len(args) != 1:
-        raise ValueError("update requires exactly one markdown file path")
-    return _process(args[0], "update")
-
-
-COMMANDS = {
-    "validate": cmd_validate,
-    "compile": cmd_compile,
-    "compare": cmd_compare,
-    "update": cmd_update,
-}
 
 
 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)
+    # 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:
-        return COMMANDS[argv[0]](argv[1:])
+        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
diff --git a/build_scripts/te_script_runner.py b/build_scripts/te_script_runner.py
index d1ea132a..98f7f2f2 100755
--- a/build_scripts/te_script_runner.py
+++ b/build_scripts/te_script_runner.py
@@ -38,6 +38,9 @@
 
 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):
@@ -245,20 +248,50 @@ def run_te_script(
     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).
-    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.
+    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")
@@ -267,9 +300,16 @@ def run_snippets(
     workdir = Path(tempfile.mkdtemp(prefix=_WORKDIR_PREFIX))
     try:
         model_path = init_model(workdir / "model.bim", te_bin=te_bin)
-        script_files = materialize(snippets, workdir / "snippets")
+        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)
-        return summarize(stdout, exit_code)
+        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)

From 0f866ad3f50bb84d32f39e7fb62df75a6bea0d5e Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 03:03:25 +0200
Subject: [PATCH 07/14] Document the build scripts for validation

---
 build_scripts/README.md | 149 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 build_scripts/README.md

diff --git a/build_scripts/README.md b/build_scripts/README.md
new file mode 100644
index 00000000..d2d2a117
--- /dev/null
+++ b/build_scripts/README.md
@@ -0,0 +1,149 @@
+# Build tools
+
+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>
+```
+
+## 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.
+
+#### `te_script_runner.py` -- generic runner
+
+Runs (or compile-checks) C# snippets against a throwaway, empty `.bim` model.
+stdout = the snippets' `Output()`; stderr = te's own stderr
+
+```shell
+$ te_script_runner.py run   -e '<expr>'    # execute (also -f <file>, or stdin)
+$ te_script_runner.py check -e '<expr>'    # compile only (te --dry-run)
+$ te_script_runner.py run -e '<expr1>' -f <file1> -e '<expr2> # execute multiple scripts in order; also works for `check`
+```
+
+Importable: `run_snippets(snippets, dry_run=..., last_only=...) -> Result`.
+Snippets run in order in one te session,
+so state (a loaded Metric View, model mutations) carries across them;
+`last_only` reports only the final snippet's `Output()`.
+
+#### `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>}
+```
+
+- Unannotated csharp fence = skip.
+- `{compile}` = compile-check only (catches API drift; never executes).
+- `output=true` = the immediately-following plain fence is the expected output.
+- `setup` prepends a preamble (see `SETUP_SCRIPTS`, e.g. the sample Metric View).
+- `after` replays earlier run blocks for their state only (not their output).
+
+The grammar for these `run` blocks is explicit:
+every option must be provided in every block.
+
+Commands (each validates first and bails on a malformed doc):
+
+```shell
+$ csharp_doctest.py validate <file>   # grammar + coverage counts, no CLI calls
+$ csharp_doctest.py compile  <file>   # compile every {compile}/{run} block
+$ csharp_doctest.py compare  <file>   # diff each {run} Output() against its fence
+$ csharp_doctest.py update   <file>   # run {run} blocks, rewrite output blocks in place
+```
+
+Exits non-zero on any failure.
+stdout = the report (verdicts + diffs);
+stderr = te's stderr and harness/operational errors.
+
+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
+$ csharp_doctest.py validate test-fixtures/doc-valid.md          # passes
+$ csharp_doctest.py compare  test-fixtures/doc-mismatch.md       # fails with a diff (nonzero exit)
+$ csharp_doctest.py compile  test-fixtures/doc-compile-drift.md  # fails on the drifted API
+$ csharp_doctest.py validate test-fixtures/err-unknown-after.md  # bails with the grammar error
+$ 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.
+
+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 as a set of URLs to verify by hand.
+
+```shell
+$ check_links.py validate                  # check _site: authored content, on-disk + external
+$ check_links.py validate local            # on-disk checks only, skip external fetching
+$ check_links.py validate all              # also include generated API and localized pages
+$ check_links.py validate stats            # add per-host external-fetch diagnostics
+$ check_links.py validate _site under=en   # only check links from pages under _site/en
+```
+
+- `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>`.
+
+`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`.
+
+Including `stats` will show per-host statistics: `python3 build_scripts/check_links.py validate stats`.

From 126829bfdf37415685b3104b0686cbe598ee43c2 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 03:45:14 +0200
Subject: [PATCH 08/14] Boost parallelism and drop github parallel requests

---
 build_scripts/check_links.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
index bd7a92c1..7caf3041 100644
--- a/build_scripts/check_links.py
+++ b/build_scripts/check_links.py
@@ -103,6 +103,10 @@ class Target(NamedTuple):
 # 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"
@@ -324,7 +328,7 @@ def _next_cooldown_wait(pending: dict[str, deque[_Task]], cooldown: dict[str, fl
 
 
 def fetch_all_external(
-    refs: dict[Target, dict[str, list[int]]], max_per_host: int = 8, max_workers: int = 8
+    refs: dict[Target, dict[str, list[int]]], max_per_host: int = 8, max_workers: int = 16
 ) -> 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
@@ -349,6 +353,7 @@ def fetch_all_external(
     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] = {}
 

From 41c63a05d59bda501f416fa4686d3ac524ba79d7 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 12:54:30 +0200
Subject: [PATCH 09/14] check_links.py: harden and add C-t, C-c, C-\ handling

- Error handling for workers so they can't hang
- siginfo, sigquit, sigbreak (C-t, C-\, and C-break) give a status
  update while running
- sigint (C-c) prints stats and exits cleanly
---
 build_scripts/check_links.py | 190 ++++++++++++++++++++++++++++++-----
 1 file changed, 163 insertions(+), 27 deletions(-)

diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
index 7caf3041..c1fbd1c7 100644
--- a/build_scripts/check_links.py
+++ b/build_scripts/check_links.py
@@ -12,19 +12,91 @@
 does filesystem, HTTP, and reporting.
 """
 
+import http.client
 import os
+import signal
 import sys
 import urllib.error
 import urllib.request
 from collections import 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 Thread
+from threading import Event, Thread
 from time import monotonic
-from typing import NamedTuple
+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."""
@@ -77,7 +149,7 @@ def extract(html: str) -> tuple[list[tuple[str, int]], set[str]]:
     return parser.links, parser.anchors
 
 
-def cmd_extract(args: list[str]) -> int:
+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:
@@ -179,7 +251,7 @@ def resolve(href: str, source_page: Path, site_root: Path) -> Target | None:
     return Target("local", os.path.normpath(base), fragment, text_targets)
 
 
-def cmd_resolve(args: list[str]) -> int:
+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")
@@ -192,15 +264,20 @@ def cmd_resolve(args: list[str]) -> int:
 
 
 def enumerate_site(
-    root: Path, source_prefix: str | None = None
+    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."""
+    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
@@ -210,13 +287,15 @@ def enumerate_site(
             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]) -> int:
+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)
+    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")
@@ -233,6 +312,10 @@ def cmd_enumerate(args: list[str]) -> int:
     "(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)."""
@@ -278,7 +361,7 @@ def fetch_external(url: str, need_body: bool) -> FetchResult:
                 if method == "GET" and need_body:
                     charset = response.headers.get_content_charset() or "utf-8"
                     parser = _LinkAnchorParser(collect_text=True)
-                    parser.feed(response.read().decode(charset, "replace"))
+                    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:
@@ -286,7 +369,9 @@ def fetch_external(url: str, need_body: bool) -> FetchResult:
                 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 (urllib.error.URLError, TimeoutError, ValueError) as error:
+        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, "")
@@ -328,7 +413,10 @@ def _next_cooldown_wait(pending: dict[str, deque[_Task]], cooldown: dict[str, fl
 
 
 def fetch_all_external(
-    refs: dict[Target, dict[str, list[int]]], max_per_host: int = 8, max_workers: int = 16
+    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
@@ -337,7 +425,9 @@ def fetch_all_external(
 
     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."""
+    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":
@@ -365,7 +455,11 @@ def fetch_all_external(
 
     def worker() -> None:
         while (task := work_q.get()) is not None:
-            done_q.put((task, fetch_external(task.url, task.need_body)))
+            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()
@@ -390,17 +484,23 @@ def reclaim(host: str) -> None:
         for task in kept:
             work_q.put(task)
 
-    workers = [Thread(target=worker) for _ in range(max_workers)]
+    # 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:
+    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=_next_cooldown_wait(pending, cooldown, monotonic()))
+            task, result = done_q.get(timeout=wait)
         except Empty:
-            admit()  # a cooldown expired; that host is eligible again
+            admit()  # a cooldown expired (or the poll ticked); recheck eligibility
             continue
         outstanding[task.host] -= 1
         requests[task.host] += 1
@@ -420,11 +520,16 @@ def reclaim(host: str) -> None:
             results[task.url] = result
             remaining -= 1
         admit()
+        progress.urls_done = len(results)
+        progress.dispatched = sum(outstanding.values())
 
-    for _ in workers:
-        work_q.put(None)
-    for thread in workers:
-        thread.join()
+    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(
@@ -440,7 +545,7 @@ def reclaim(host: str) -> None:
     return results, stats
 
 
-def cmd_fetch(args: list[str]) -> int:
+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
@@ -647,6 +752,8 @@ def report(failures: list[Failure], root: Path, content_only: bool = True) -> in
 def print_diagnostics(stats: dict[str, HostStats], elapsed: float) -> None:
     """Print per-host fetch diagnostics: requests, 429s, cooldown time, HEAD fallbacks, final cap, Retry-After set."""
     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
     print(f"\n--- fetch diagnostics ({elapsed:.1f}s, {len(active)} hosts) ---")
     print(f"{'reqs':>5} {'429s':>5} {'wait(s)':>8} {'fb':>4} {'cap':>4}  host  [retry-after seen]")
     ranked = sorted(active.items(), key=lambda kv: (kv[1].rate_limited, kv[1].wait_seconds), reverse=True)
@@ -657,7 +764,7 @@ def print_diagnostics(stats: dict[str, HostStats], elapsed: float) -> None:
               f"{stat.head_fallbacks:>4} {stat.final_cap:>4}  {host}{tail}")
 
 
-def cmd_validate(args: list[str]) -> int:
+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>]
@@ -672,8 +779,10 @@ def cmd_validate(args: list[str]) -> int:
     root = Path(positional[0]) if positional else Path("_site")
     source_prefix = os.path.normpath(root / under) if under else None
 
-    refs, anchors_by_file = enumerate_site(root, source_prefix)
+    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()
@@ -681,16 +790,26 @@ def cmd_validate(args: list[str]) -> int:
         refs = {target: sources for target, sources in refs.items() if target.kind == "local"}
         external: dict[str, FetchResult] = {}
     else:
-        external, stats = fetch_all_external(refs)
+        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"
     exit_code = report(validate(refs, anchors_by_file, existing, external), root, content_only="all" not in flags)
     if "stats" in flags:
         print_diagnostics(stats, elapsed)
     return exit_code
 
 
-COMMANDS = {
+COMMANDS: dict[str, Callable[[list[str], _Progress], int]] = {
     "extract": cmd_extract,
     "resolve": cmd_resolve,
     "enumerate": cmd_enumerate,
@@ -703,7 +822,24 @@ 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
-    return COMMANDS[argv[0]](argv[1:])
+
+    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__":

From 22ea6f2eb59472dd6c4a652edc8598bb0556e9fc Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 13:30:01 +0200
Subject: [PATCH 10/14] Update reporting for urls and stats

---
 build_scripts/check_links.py | 108 +++++++++++++++++++++++++++++------
 1 file changed, 92 insertions(+), 16 deletions(-)

diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
index c1fbd1c7..8f438f95 100644
--- a/build_scripts/check_links.py
+++ b/build_scripts/check_links.py
@@ -18,7 +18,7 @@
 import sys
 import urllib.error
 import urllib.request
-from collections import defaultdict, deque
+from collections import Counter, defaultdict, deque
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from html.parser import HTMLParser
@@ -701,8 +701,8 @@ def report(failures: list[Failure], root: Path, content_only: bool = True) -> in
 
         WARNINGS -- 1 broken external reference(s) across 1 file(s)
         ...
-        External URLs to verify:
-          https://example.com/gone
+        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]]]] = {}
@@ -741,26 +741,101 @@ def report(failures: list[Failure], root: Path, content_only: bool = True) -> in
         print()
 
     if warnings:
-        urls = {_display_url(failure.target) for breaks in warnings.values() for failure, _ in breaks}
-        print("External URLs to verify:")
-        for url in sorted(urls):
-            print(url)
+        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
 
 
-def print_diagnostics(stats: dict[str, HostStats], elapsed: float) -> None:
-    """Print per-host fetch diagnostics: requests, 429s, cooldown time, HEAD fallbacks, final cap, Retry-After set."""
+_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
-    print(f"\n--- fetch diagnostics ({elapsed:.1f}s, {len(active)} hosts) ---")
-    print(f"{'reqs':>5} {'429s':>5} {'wait(s)':>8} {'fb':>4} {'cap':>4}  host  [retry-after seen]")
-    ranked = sorted(active.items(), key=lambda kv: (kv[1].rate_limited, kv[1].wait_seconds), reverse=True)
-    for host, stat in ranked:
+    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"{stat.requests:>5} {stat.rate_limited:>5} {stat.wait_seconds:>8.1f} "
+        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}")
 
 
@@ -803,9 +878,10 @@ def cmd_validate(args: list[str], progress: _Progress) -> int:
         refs = {t: s for t, s in refs.items() if t.kind != "external" or t.resource in external}
 
     progress.phase = "validating"
-    exit_code = report(validate(refs, anchors_by_file, existing, external), root, content_only="all" not in flags)
+    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, elapsed)
+        print_diagnostics(stats, summarize_outcomes(external, failures), elapsed)
     return exit_code
 
 

From 209a4fa7cdd144315e109a4062610e6b0a6214ad Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 13:35:10 +0200
Subject: [PATCH 11/14] Update README for check_links reporting

---
 build_scripts/README.md | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/build_scripts/README.md b/build_scripts/README.md
index d2d2a117..b43522a4 100644
--- a/build_scripts/README.md
+++ b/build_scripts/README.md
@@ -112,14 +112,16 @@ Broken link checks:
 - 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).
+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 as a set of URLs to verify by hand.
+listed at the end as URLs to verify by hand, each with two counts:
+how many docs reference it and how many total times.
+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.
 
 ```shell
 $ check_links.py validate                  # check _site: authored content, on-disk + external
 $ check_links.py validate local            # on-disk checks only, skip external fetching
-$ check_links.py validate all              # also include generated API and localized pages
+$ check_links.py validate all              # also include generated API and localized pages; noisy, likely unnecessary
 $ check_links.py validate stats            # add per-host external-fetch diagnostics
 $ check_links.py validate _site under=en   # only check links from pages under _site/en
 ```
@@ -129,6 +131,13 @@ $ check_links.py validate _site under=en   # only check links from pages under _
 - `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.
@@ -146,4 +155,26 @@ 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`.
 
-Including `stats` will show per-host statistics: `python3 build_scripts/check_links.py validate stats`.
+#### 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.

From b3df232f6f015e4a233ba8f02aaac188538d1577 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 14:22:24 +0200
Subject: [PATCH 12/14] Update README with usage and contribution notes

---
 build_scripts/README.md | 150 ++++++++++++++++++++++++++++------------
 1 file changed, 104 insertions(+), 46 deletions(-)

diff --git a/build_scripts/README.md b/build_scripts/README.md
index b43522a4..bd313f8c 100644
--- a/build_scripts/README.md
+++ b/build_scripts/README.md
@@ -1,12 +1,38 @@
 # Build tools
 
-All Python build scripts are linted and type-checked :
+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
@@ -15,22 +41,35 @@ $ uvx mypy --strict  <python_sources>
 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.
-stdout = the snippets' `Output()`; stderr = te's own stderr
+Output:
+- stdout: the snippets' `Output()`, including C# script exceptions and runtime errors
+- stderr: te's own stderr stream, and error from the script runner itself
 
 ```shell
-$ te_script_runner.py run   -e '<expr>'    # execute (also -f <file>, or stdin)
-$ te_script_runner.py check -e '<expr>'    # compile only (te --dry-run)
-$ te_script_runner.py run -e '<expr1>' -f <file1> -e '<expr2> # execute multiple scripts in order; also works for `check`
+$ 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`
 ```
 
-Importable: `run_snippets(snippets, dry_run=..., last_only=...) -> Result`.
-Snippets run in order in one te session,
-so state (a loaded Metric View, model mutations) carries across them;
-`last_only` reports only the final snippet's `Output()`.
+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
 
@@ -42,27 +81,37 @@ The annotation is invisible in rendered docfx output:
     ```csharp {run id=<slug> setup=<mv-sample|none> after=<id,...|none> output=<true|false>}
 ```
 
-- Unannotated csharp fence = skip.
-- `{compile}` = compile-check only (catches API drift; never executes).
-- `output=true` = the immediately-following plain fence is the expected output.
-- `setup` prepends a preamble (see `SETUP_SCRIPTS`, e.g. the sample Metric View).
-- `after` replays earlier run blocks for their state only (not their output).
-
-The grammar for these `run` blocks is explicit:
-every option must be provided in every block.
-
 Commands (each validates first and bails on a malformed doc):
 
 ```shell
-$ csharp_doctest.py validate <file>   # grammar + coverage counts, no CLI calls
-$ csharp_doctest.py compile  <file>   # compile every {compile}/{run} block
-$ csharp_doctest.py compare  <file>   # diff each {run} Output() against its fence
-$ csharp_doctest.py update   <file>   # run {run} blocks, rewrite output blocks in place
+$ 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
 ```
 
-Exits non-zero on any failure.
-stdout = the report (verdicts + diffs);
-stderr = te's stderr and harness/operational errors.
+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:
+- stdout: the report (verdicts + diffs);
+- stderr: te's stderr and harness/operational errors.
 
 Sweep all docs with annotated code blocks for valid annotations, bailing on first error:
 
@@ -78,7 +127,8 @@ 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).
+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`:
@@ -91,11 +141,11 @@ Markdown fixtures drive `csharp_doctest.py`:
 the executed-run and `--dry-run` schemas, each in a success and a failure (compile / runtime) variant.
 
 ```shell
-$ csharp_doctest.py validate test-fixtures/doc-valid.md          # passes
-$ csharp_doctest.py compare  test-fixtures/doc-mismatch.md       # fails with a diff (nonzero exit)
-$ csharp_doctest.py compile  test-fixtures/doc-compile-drift.md  # fails on the drifted API
-$ csharp_doctest.py validate test-fixtures/err-unknown-after.md  # bails with the grammar error
-$ te_script_runner.py summarize test-fixtures/te-runtime-error.json
+$ 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
@@ -105,31 +155,39 @@ 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
+- 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).
+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.
-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.
+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.
 
-```shell
-$ check_links.py validate                  # check _site: authored content, on-disk + external
-$ check_links.py validate local            # on-disk checks only, skip external fetching
-$ check_links.py validate all              # also include generated API and localized pages; noisy, likely unnecessary
-$ check_links.py validate stats            # add per-host external-fetch diagnostics
-$ check_links.py validate _site under=en   # only check links from pages under _site/en
-```
+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>`.
+- `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:

From 6667a255e8e0bcecec1a60b79279c5a25d38dd6d Mon Sep 17 00:00:00 2001
From: greggyb <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 16:12:08 +0200
Subject: [PATCH 13/14] use `python3` in shebang

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 build_scripts/check_links.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build_scripts/check_links.py b/build_scripts/check_links.py
index 8f438f95..7e61d244 100644
--- a/build_scripts/check_links.py
+++ b/build_scripts/check_links.py
@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 """
 Standalone dead-link checker for the generated `_site`.
 

From ed1b9c9853b36053255f665180f4aa579e673121 Mon Sep 17 00:00:00 2001
From: Greg Baldini <greg.baldini@tabulareditor.com>
Date: Fri, 3 Jul 2026 16:20:00 +0200
Subject: [PATCH 14/14] clarify README and comments about stdour/stderr

---
 build_scripts/README.md         | 10 +++++-----
 build_scripts/csharp_doctest.py |  2 +-
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/build_scripts/README.md b/build_scripts/README.md
index bd313f8c..bd0a0137 100644
--- a/build_scripts/README.md
+++ b/build_scripts/README.md
@@ -47,8 +47,8 @@ The code block annotations can be used in any doc.
 
 Runs (or compile-checks) C# snippets against a throwaway, empty `.bim` model.
 Output:
-- stdout: the snippets' `Output()`, including C# script exceptions and runtime errors
-- stderr: te's own stderr stream, and error from the script runner itself
+- 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)
@@ -109,9 +109,9 @@ Exit codes:
 - `1`: a block failed (output mismatch, compile error, runtime error)
 - `2`: malformed doc or bad usage (validate bails before any CLI calls).
 
-Output:
-- stdout: the report (verdicts + diffs);
-- stderr: te's stderr and harness/operational errors.
+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:
 
diff --git a/build_scripts/csharp_doctest.py b/build_scripts/csharp_doctest.py
index 597b6063..220c1be5 100644
--- a/build_scripts/csharp_doctest.py
+++ b/build_scripts/csharp_doctest.py
@@ -94,7 +94,7 @@ class Outcome(NamedTuple):
     block: "Block"
     action: str  # verb shown in the report: "compile" | "compare" | "update"
     passed: bool
-    detail: list[str]  # lines emitted to stderr when it fails
+    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