diff --git a/.github/workflows/docs-pr-check.yml b/.github/workflows/docs-pr-check.yml
index 0cf3b3c..19724db 100644
--- a/.github/workflows/docs-pr-check.yml
+++ b/.github/workflows/docs-pr-check.yml
@@ -23,10 +23,78 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      # The build is the gate. docs/.vuepress/config.ts sets the theme's
-      # linksCheck plugin to `build: 'error'`, so VuePress throws and exits
-      # non-zero on a dead internal link. Nothing here greps the log: a
-      # log-string check passes whenever the message wording changes, and it
-      # passed for exactly that reason before.
-      - name: Build docs (fails on broken internal links)
+      # The build catches ONE class of dead link, not all of them. See the
+      # coverage map on the next step before concluding anything is redundant.
+      #
+      # docs/.vuepress/config.ts sets the theme's linksCheck plugin to
+      # `build: 'error'`, so VuePress throws and exits non-zero on a dead
+      # internal link *that is written as a markdown link to a .md target*. The
+      # plugin filters candidates on /\.md(?:[?#]|$)/, which is about 861 of
+      # roughly 1331 internal links; it cannot see links in config.ts, in
+      # frontmatter, in raw HTML, or written with a .html / no extension.
+      #
+      # Nothing here greps the log: a log-string check passes whenever the
+      # message wording changes, and it passed for exactly that reason before.
+      - name: Build docs (fails on broken internal markdown links)
         run: npm run docs:build
+
+      # ---------------------------------------------------------------------
+      # THE ARTIFACT GATE. Every other link gate in this repo reads SOURCE
+      # MARKDOWN. This one reads the bytes that get deployed.
+      #
+      # WHICH GATE COVERS WHICH CLASS — read this before deleting anything.
+      # The comment above this step used to call the build "the gate" while it
+      # covered about 65% of internal links, and a maintainer could reasonably
+      # have deleted link-check.yml believing it redundant. It is not.
+      #
+      #   link class                                  | build | base-prefix | lychee-source | THIS
+      #   --------------------------------------------|-------|-------------|---------------|-----
+      #   [x](./y.md) dead target                     |  YES  |      -      |      YES      | YES
+      #   [x](/cli/y) missing /forge_docs/ base       |   -   |     YES     |      YES      | YES
+      #   navbar / sidebar entry in config.ts         |   -   |      -      |       -       | YES
+      #   docs/README.md frontmatter hero actions     |   -   |      -      |       -       | YES
+      #   raw <a href="..."> in markdown              |   -   |      -      |      YES      | YES
+      #   .html-suffixed and extensionless targets    |   -   |     YES     |      YES      | YES
+      #   theme-generated links (prev/next, edit)     |   -   |      -      |       -       | YES
+      #   a page that renders but is never emitted    |   -   |      -      |       -       | YES
+      #   asset <script src> / <img src> in dist      |   -   |      -      |       -       | YES
+      #   external URL reachability                   |   -   |      -      |       -       |  -   (link-check.yml `external`, weekly)
+      #   #fragment / anchor targets                  |   -   |      -      |       -       |  -   (unguarded; see the script header)
+      #   relative ./x refs in built HTML             |   -   |      -      |    partly     | YES
+      #
+      # The lychee-source cell for the raw-HTML row is measured, not inferred:
+      # appending <a href="/cli/init.html"> to a page makes lychee report
+      # ".linkcheck-root/cli/init.html (at 3:10) | File not found". An earlier
+      # draft of this table put a dash there and so argued for keeping a sibling
+      # gate on a premise that was wrong — the same kind of misleading note this
+      # change set out to remove. Re-measure a cell before trusting it.
+      #
+      # So: THIS step is the only one that sees the config.ts, frontmatter and
+      # raw-HTML classes, and the only one that checks what actually shipped.
+      # The source gates in link-check.yml are the only ones that run on a
+      # source-only change without a build, and the only ones that name a
+      # REPOSITORY path rather than a dist path when they fail — which is what a
+      # contributor can act on. Keep both.
+      #
+      # The script refuses to report a clean result unless it can prove, in the
+      # same run, that it inspected the artifact: in-process canaries (one link
+      # that must resolve, one that must not, one missing the base prefix) run
+      # before the scan, and floors on pages walked, references examined and
+      # distinct targets resolved fail the job if any is implausibly low. The
+      # canaries are in-process rather than a separate step on purpose — a
+      # separate step can be deleted while the gate keeps reporting green.
+      #
+      # It prints its census (counts per resolution rule and per exclusion
+      # class), because "passed" with no numbers is indistinguishable from
+      # "inspected nothing". Read that output when reviewing this job.
+      #
+      # Verified on 92925e5: a one-character typo in the config.ts navbar link
+      # (/why -> /whyy) leaves `npm run docs:build` exiting 0 while shipping 424
+      # dead references across 212 of 219 pages. This step fails on it.
+      #
+      # No `continue-on-error` and no `|| true`. Deliberately NOT `if: always()`
+      # either: a failed build leaves no artifact, and measuring an absent or
+      # stale dist is the exact failure mode this exists to prevent. The script
+      # refuses to pass when dist is missing, so both directions are covered.
+      - name: Check the built artifact for dead internal links
+        run: node scripts/check-dist-links.mjs
diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts
index 4df3a7c..cb5ffec 100644
--- a/docs/.vuepress/config.ts
+++ b/docs/.vuepress/config.ts
@@ -39,6 +39,66 @@ export default defineUserConfig({
   // and the branded NotFound layout overrides the theme's default 404.
   clientConfigFile: resolve(__dirname, './client.ts'),
 
+  // Monaco's CSS ships to every page. That is a RECORDED DECISION to leave it
+  // alone, not an oversight.
+  //
+  // Measured on a fresh build, 2026-09-15, monaco-editor as installed: the
+  // site emits exactly ONE stylesheet, assets/style-<hash>.css, 251,769 bytes,
+  // linked render-blocking from all 213 pages. Monaco is 162,004 of those
+  // bytes (64.3%), about 24 KB of the file's 41 KB gzipped. The editor is used
+  // on ONE page: `<Playground>` appears only in docs/playground/README.md.
+  //
+  // Monaco's JAVASCRIPT is split correctly, and that contrast is the whole
+  // point. Playground.vue reaches it through `await import('monaco-editor')`,
+  // so editor.api, vs and the four language workers land in async-only chunks
+  // totalling 13.1 MB that NO prerendered page references or prefetches (the
+  // shouldPrefetch filter below skips them by name). A visitor who never opens
+  // /playground/ fetches none of it. Only the CSS leaks.
+  //
+  // Cause: @vuepress/bundler-vite 2.0.0-rc.31 hard-sets `cssCodeSplit: false`
+  // inside its `build` block at
+  // node_modules/@vuepress/bundler-vite/dist/index.js:108. That is not a Vite
+  // default and not exposed as a bundler option. With CSS splitting off Vite
+  // has nowhere else to put style reachable only through an async-only chunk,
+  // so Monaco's sheet is concatenated into the single entry stylesheet even
+  // though its JS never is.
+  //
+  // Two fixes were considered and both declined:
+  //
+  // 1. Override it — viteBundler({ viteOptions: { build: { cssCodeSplit: true } } }).
+  //    This does work mechanically: the bundler's own `vuepress:user-config`
+  //    plugin is `enforce: 'post'`, so viteOptions win over line 108. Declined
+  //    because it fights a deliberate framework choice about style ordering
+  //    under static rendering. With one sheet, the prerendered HTML carries the
+  //    <link> and cascade order is fixed at build time. Split per chunk, an
+  //    async chunk's CSS is injected by the chunk loader after hydration and is
+  //    referenced from no prerendered HTML, so theme-vs-editor precedence
+  //    becomes load-order dependent and /playground/ shows an unstyled editor
+  //    until its chunk lands.
+  //
+  // 2. Load Monaco's CSS at runtime — keep it out of the bundle and inject a
+  //    <link> from Playground.vue. Declined because it means hand-managing what
+  //    the bundler currently guarantees: emitting the file, hashing it for
+  //    cache-busting, and ordering it after the theme.
+  //
+  // Before changing this, RE-MEASURE rather than trusting the numbers above.
+  // They move with every monaco-editor bump: earlier passes recorded 58.6% and
+  // 65.9% for what is 64.3% today.
+  //
+  //   rm -rf docs/.vuepress/dist && npm run docs:build
+  //   # one stylesheet, on every page -> 213
+  //   grep -rl 'assets/style-.*\.css' --include='*.html' docs/.vuepress/dist | wc -l
+  //   # Monaco's JS still async-only -> 0 pages reference a Monaco chunk
+  //   grep -rlE 'assets/(editor\.api-|[a-z]+\.worker-)' --include='*.html' docs/.vuepress/dist | wc -l
+  //   # Monaco's share of the sheet -> total, Monaco bytes, percent
+  //   python3 -c "import glob;p=glob.glob('docs/.vuepress/dist/assets/*.css')[0];s=open(p,'rb').read();b=s.index(b'.monaco-aria-container');print(len(s),len(s)-b,round(100*(len(s)-b)/len(s),1))"
+  //
+  // That last command assumes Monaco's block is CONTIGUOUS and runs to EOF,
+  // which holds today: nothing after byte 89,765 contains `--vp-` and nothing
+  // before it contains `--vscode-`. Verify that assumption before believing
+  // the percentage, because an interleaved bundle would make it silently
+  // undercount and read as an improvement. Then confirm /playground/ still
+  // paints a styled editor with no flash.
   bundler: viteBundler(),
 
   // Both of these default to TRUE in VuePress. They were set to false in the
diff --git a/docs/README.md b/docs/README.md
index 13986ab..550b374 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -122,10 +122,53 @@ These are the groups `fluid --help` prints on `0.15.0`. Run it yourself to confi
 
 `--help` promotes a short surface, not the whole one. Commands such as `bundle`, `diff`, `verify`, `publish`, `runs`, `stats`, `ship` and [`mission`](/forge_docs/cli/mission.html) are real and documented, and `--help` itself names the production path as `bundle` → `validate` → `generate artifacts` → `diff` → `plan` → `apply` → `verify` → `publish`. See the [CLI Reference](/forge_docs/cli/) for everything.
 
-::: tip Current release — `0.15.0`, schema **0.7.5** stable (GA)
-`0.15.0` is the current release ([release notes](/forge_docs/RELEASE_NOTES_0.15.0.html)). Its headline is **sovereignty enforcement**: data-residency controls that previously reported clean while checking nothing now actually block, with `sovereignty.enforcementMode` driving severity in both directions, engine defaults realigned to the schema's, and the region→jurisdiction table derived from vendor data. A contract that passed [`fluid validate`](/forge_docs/cli/validate.html) on `0.14.1` can fail here. Recent releases below it: [`0.14.0`](/forge_docs/RELEASE_NOTES_0.14.0.html) was the **live-verification hardening** release (the dbt Iceberg loop reaching all three cloud warehouses); [`0.13.0`](/forge_docs/RELEASE_NOTES_0.13.0.html) brought **verifiable autonomy + declarative packaging** with the new [`fluid mission`](/forge_docs/cli/mission.html) command; [`0.12.0`](/forge_docs/RELEASE_NOTES_0.12.0.html) landed **dbt integration + schema GA**, promoting contract schema `0.7.5` to stable as the default for untagged contracts and shipping the brownfield [`fluid import dbt`](/forge_docs/cli/import.html) importer, the MetricFlow bridge and `fluid verify --reconcile-lineage`; `0.11.0` brought the **AI-ready / RAG** surface (vector output port preview, semantic-drift guard, `ai_ready` agent, LocalStack-compatible AWS apply); `0.10.0` matured the **plugin platform** (operator trust boundary via `FLUID_PLUGINS_ALLOWLIST` / `FLUID_PLUGINS_BLOCKLIST`, [`fluid plugins`](/forge_docs/cli/plugins.html) + [`fluid exporters`](/forge_docs/cli/exporters.html), and the `odps` / `odcs` provider→exporter reclassification); the streaming **Kafka → Iceberg sink** shipped in `0.9.0`; and the **MCP output-port gateway** — runtime `agentPolicy` enforcement with JWT-bearer + mTLS identity — arrived in `0.8.7` ([`fluid mcp`](/forge_docs/cli/mcp.html)). The platform builds on the **SDP / ADP / CDP** Data Mesh vocabulary alongside the medallion `Bronze / Silver / Gold` layers, **six ingestion engines** (`duckdb`, `dlt`, `meltano`, `airbyte`, `kafka-connect`, `debezium`), the guided `fluid forge` UX (mode picker, welcome scan, slash commands, preview panel), and a companion **SDK** (`data-product-forge-sdk`). See [SDK & Plugins](/forge_docs/sdk-and-plugins/), [Source-Aligned Acquisition](/forge_docs/advanced/source-aligned-acquisition.html), and [Product Types](/forge_docs/data-products/product-type.html) for the full picture.
+:::: tip Current release — `0.15.1`, schema **0.7.5** stable (GA)
+`pip install data-product-forge` gives you `0.15.1`. The `0.15.x` changes landed in `0.15.0`, which
+documents them together with `0.14.1` in one baseline (there is no separate `0.15.1` page):
+[`0.15.0` release notes](/forge_docs/RELEASE_NOTES_0.15.0.html).
+
+**Coming from `0.14.1` or earlier? One thing can break you.** A contract that passed
+[`fluid validate`](/forge_docs/cli/validate.html) on `0.14.1` can fail now, with no edit of yours.
+`0.15.0` is the **sovereignty enforcement** release: residency controls that reported clean while
+checking nothing now actually block.
+
+- **`strict` blocks, `advisory` warns, `audit` informs.** `sovereignty.enforcementMode` drives
+  severity in both directions, and the engine's own defaults — previously the permissive inverse of
+  the schema's — now match the schema, where `strict` is the default.
+- **Three regions changed jurisdiction.** The region→jurisdiction table is derived from the vendors'
+  own data instead of typed by hand, which is how it had placed London in the EU and treated
+  Singapore and Seoul as pass-anything wildcards. Re-validate any contract bound there.
+- **A jurisdiction-pinned MCP output port refuses to start** on the default stdio transport, or on
+  HTTP with no auth mode configured: caller jurisdiction is enforced at query time, fail-closed, and
+  neither of those can prove where the caller is.
+
+The notes carry the thirteen-step upgrade checklist and three further risks outside sovereignty.
+`0.14.1`, in the same baseline, closed two HIGH authorisation bypasses in the MCP output port.
+
+::: details Before that, each release keeping its own work
+- [`0.14.0`](/forge_docs/RELEASE_NOTES_0.14.0.html) — live-verification hardening: the dbt Iceberg
+  loop reaching all three cloud warehouses.
+- [`0.13.0`](/forge_docs/RELEASE_NOTES_0.13.0.html) — verifiable autonomy and declarative packaging,
+  with the [`fluid mission`](/forge_docs/cli/mission.html) command.
+- [`0.12.0`](/forge_docs/RELEASE_NOTES_0.12.0.html) — dbt integration and schema GA: `0.7.5` promoted
+  to stable as the default for untagged contracts, plus the brownfield
+  [`fluid import dbt`](/forge_docs/cli/import.html) importer.
+- [`0.11.0`](/forge_docs/RELEASE_NOTES_0.11.0.html) — the AI-ready / RAG surface: vector output port,
+  semantic-drift guard, `ai_ready` agent.
+- [`0.10.0`](/forge_docs/RELEASE_NOTES_0.10.0.html) — plugin governance: an operator trust boundary
+  over plugins, with [`fluid plugins`](/forge_docs/cli/plugins.html) and
+  [`fluid exporters`](/forge_docs/cli/exporters.html).
+- [`0.9.0`](/forge_docs/RELEASE_NOTES_0.9.0.html) — the streaming Kafka → Iceberg sink.
+- [`0.8.6`](/forge_docs/RELEASE_NOTES_0.8.6.html) — the [`fluid mcp`](/forge_docs/cli/mcp.html)
+  output-port gateway: `agentPolicy` enforced at runtime, with JWT-bearer and mTLS identity.
 :::
 
+The vocabulary and the product types behind all of it:
+[SDK & Plugins](/forge_docs/sdk-and-plugins/),
+[Source-Aligned Acquisition](/forge_docs/advanced/source-aligned-acquisition.html),
+[Product Types](/forge_docs/data-products/product-type.html).
+::::
+
 ## Where to go next
 
 - [Getting Started](/forge_docs/getting-started/) for the local-first path
diff --git a/docs/RELEASE_NOTES_0.7.11.md b/docs/RELEASE_NOTES_0.7.11.md
index 5037f86..79fd066 100644
--- a/docs/RELEASE_NOTES_0.7.11.md
+++ b/docs/RELEASE_NOTES_0.7.11.md
@@ -5,7 +5,7 @@
 
 ## What changed in the docs
 
-- Pinned the supported CLI version in [`docs/.vuepress/cli-version.json`](./.vuepress/cli-version.json). One file to bump per CLI release.
+- Pinned the supported CLI version in [`docs/.vuepress/cli-version.json`](https://github.com/Agenticstiger/forge_docs/blob/main/docs/.vuepress/cli-version.json). One file to bump per CLI release.
 - New CI workflow `cli-consistency.yml` installs the pinned CLI from PyPI and fails on docs ↔ CLI drift (version, command list, provider list).
 - Documented every command registered by the CLI's `fluid_build/cli/bootstrap.py`. New pages:
   - `demo`, `skills`, `ai`
diff --git a/docs/walkthrough/gcp.md b/docs/walkthrough/gcp.md
index 2cff5b2..8a21910 100644
--- a/docs/walkthrough/gcp.md
+++ b/docs/walkthrough/gcp.md
@@ -49,20 +49,27 @@ This walkthrough deploys a **production-ready Bitcoin price tracking data produc
 
 ### Create GCP Project
 
+::: warning Substitute your own project id
+`my-project-id` is a placeholder. Project ids are unique across the whole of Google Cloud, so this
+one will not be free: replace it with your own everywhere it appears on this page, and set
+`GCP_PROJECT_ID` before running any of the Python. The scripts below deliberately have no default,
+so an unset variable stops them rather than writing to a project you do not own.
+:::
+
 ```bash
-# Create project (or use existing)
-gcloud projects create fluid-crypto-tracker \
+# Create project (or use existing) - swap in your own id
+gcloud projects create my-project-id \
   --name="Fluid Forge Crypto Tracker"
 
 # Set as active project
-gcloud config set project fluid-crypto-tracker
+gcloud config set project my-project-id
 
 # Link billing account (required for BigQuery)
 # Get billing account ID
 gcloud billing accounts list
 
 # Link it to project
-gcloud billing projects link fluid-crypto-tracker \
+gcloud billing projects link my-project-id \
   --billing-account=XXXXXX-XXXXXX-XXXXXX
 ```
 
@@ -109,6 +116,7 @@ import requests
 from google.cloud import bigquery
 from datetime import datetime
 import os
+import sys
 
 def fetch_bitcoin_price():
     """Fetch current Bitcoin price from CoinGecko API"""
@@ -150,7 +158,18 @@ def insert_to_bigquery(row, project_id, dataset_id="crypto_data", table_id="bitc
     print(f"✅ Inserted Bitcoin price: ${row['price_usd']:,.2f} at {row['price_timestamp']}")
 
 if __name__ == "__main__":
-    project_id = os.getenv("GCP_PROJECT_ID", "fluid-crypto-tracker")
+    # No default project: an unset variable stops the script rather than
+    # writing to whichever project happens to own that id.
+    project_id = os.getenv("GCP_PROJECT_ID")
+
+    if not project_id and len(sys.argv) > 1:
+        project_id = sys.argv[1]
+
+    if not project_id:
+        print("❌ Error: GCP_PROJECT_ID environment variable not set")
+        print("Usage: python ingest_bitcoin_prices.py [PROJECT_ID]")
+        print("   or: export GCP_PROJECT_ID=your-project-id && python ingest_bitcoin_prices.py")
+        sys.exit(1)
     
     # Fetch price
     price_data = fetch_bitcoin_price()
@@ -221,7 +240,7 @@ builds:
           MAX(price_usd) as max_price_usd,
           STDDEV(price_usd) as daily_volatility,
           SUM(volume_24h_usd) as total_volume_usd
-        FROM `fluid-crypto-tracker.crypto_data.bitcoin_prices`
+        FROM `my-project-id.crypto_data.bitcoin_prices`
         GROUP BY DATE(price_timestamp)
         ORDER BY date DESC
     outputs:
@@ -252,7 +271,7 @@ exposes:
       platform: gcp
       format: bigquery_table
       location:
-        project: fluid-crypto-tracker
+        project: my-project-id
         dataset: crypto_data
         table: bitcoin_prices
         region: us-central1
@@ -400,7 +419,7 @@ exposes:
       platform: gcp
       format: bigquery_table
       location:
-        project: fluid-crypto-tracker
+        project: my-project-id
         dataset: crypto_data
         table: daily_summary
     
@@ -516,7 +535,7 @@ See what will be created before deploying:
 ```bash
 # Set provider and project via environment variables
 export FLUID_PROVIDER=gcp
-export FLUID_PROJECT=fluid-crypto-tracker
+export FLUID_PROJECT=my-project-id
 
 fluid plan contract.fluid.yaml
 
@@ -549,13 +568,13 @@ Use `FLUID_PROVIDER` and `FLUID_PROJECT` environment variables instead of comman
 ```bash
 # Ensure environment variables are set
 export FLUID_PROVIDER=gcp
-export FLUID_PROJECT=fluid-crypto-tracker
+export FLUID_PROJECT=my-project-id
 
 fluid apply contract.fluid.yaml
 
 # Expected output:
 # ☁️ Deploying to Google Cloud Platform
-# Project: fluid-crypto-tracker
+# Project: my-project-id
 # 
 # ⏳ Creating dataset 'crypto_data'... ✅ Created (1.2s)
 # ⏳ Creating table 'bitcoin_prices'...
@@ -566,12 +585,12 @@ fluid apply contract.fluid.yaml
 # ✨ Deployment successful!
 # 
 # 📊 Resources created in BigQuery:
-#   • Dataset: fluid-crypto-tracker.crypto_data
+#   • Dataset: my-project-id.crypto_data
 #   • Table: bitcoin_prices (partitioned)
 #   • View: daily_summary
 # 
 # 🔗 View in BigQuery Console:
-#   https://console.cloud.google.com/bigquery?project=fluid-crypto-tracker&d=crypto_data
+#   https://console.cloud.google.com/bigquery?project=my-project-id&d=crypto_data
 # 
 # 💰 Estimated cost: $0.00/month (within free tier)
 ```
@@ -584,7 +603,7 @@ Run the ingestion script to load the first price data point:
 
 ```bash
 # Set environment variable
-export GCP_PROJECT_ID=fluid-crypto-tracker
+export GCP_PROJECT_ID=my-project-id
 
 # Run ingestion
 python ingest_bitcoin_prices.py
@@ -653,7 +672,7 @@ bq query --use_legacy_sql=false \
 bq extract \
   --destination_format CSV \
   crypto_data.bitcoin_prices \
-  gs://fluid-crypto-tracker-exports/bitcoin_prices_*.csv
+  gs://my-project-id-exports/bitcoin_prices_*.csv
 ```
 
 ---
@@ -663,7 +682,7 @@ bq extract \
 ```bash
 # Verify deployment against contract
 export FLUID_PROVIDER=gcp
-export FLUID_PROJECT=fluid-crypto-tracker
+export FLUID_PROJECT=my-project-id
 
 fluid verify contract.fluid.yaml
 
@@ -809,7 +828,10 @@ import os
 @functions_framework.http
 def main(request):
     """HTTP Cloud Function for Bitcoin price ingestion"""
-    project_id = os.getenv("GCP_PROJECT_ID", "fluid-crypto-tracker")
+    # No default: refuse to run rather than write to some other account's project.
+    project_id = os.getenv("GCP_PROJECT_ID")
+    if not project_id:
+        return {"status": "error", "message": "GCP_PROJECT_ID is not set on this function"}, 500
     
     try:
         # Fetch and insert price data
@@ -835,14 +857,14 @@ gcloud functions deploy bitcoin-price-ingestion \
   --trigger-http \
   --entry-point main \
   --source . \
-  --set-env-vars GCP_PROJECT_ID=fluid-crypto-tracker \
+  --set-env-vars GCP_PROJECT_ID=my-project-id \
   --region us-central1 \
   --allow-unauthenticated
 
 # Create Cloud Scheduler job (runs hourly)
 gcloud scheduler jobs create http bitcoin-hourly-ingest \
   --schedule="0 * * * *" \
-  --uri="https://us-central1-fluid-crypto-tracker.cloudfunctions.net/bitcoin-price-ingestion" \
+  --uri="https://us-central1-my-project-id.cloudfunctions.net/bitcoin-price-ingestion" \
   --http-method=GET \
   --location=us-central1
 
@@ -981,7 +1003,7 @@ The labels from your FLUID contract automatically appear in BigQuery for cost tr
 
 ```bash
 # View table with labels
-bq show --format=prettyjson fluid-crypto-tracker:crypto_data.bitcoin_prices | \
+bq show --format=prettyjson my-project-id:crypto_data.bitcoin_prices | \
   jq '.labels'
 
 # Expected output:
@@ -1004,7 +1026,7 @@ SELECT
   REGEXP_EXTRACT(option_value, r'cost-center:([^,}]+)') as cost_center,
   SUM(size_bytes) / POW(10,9) as size_gb,
   SUM(size_bytes) / POW(10,9) * 0.02 as monthly_storage_cost_usd
-FROM `fluid-crypto-tracker.crypto_data.INFORMATION_SCHEMA.TABLE_OPTIONS`
+FROM `my-project-id.crypto_data.INFORMATION_SCHEMA.TABLE_OPTIONS`
 WHERE option_name = 'labels'
 GROUP BY table_schema, table_name, cost_center;
 
@@ -1036,8 +1058,8 @@ SELECT
   SUM(total_rows) as total_rows,
   SUM(size_bytes) / POW(10,9) as size_gb,
   SUM(size_bytes) * 0.02 / POW(10,9) as monthly_cost_usd
-FROM `fluid-crypto-tracker.crypto_data.INFORMATION_SCHEMA.TABLES` t
-LEFT JOIN `fluid-crypto-tracker.crypto_data.INFORMATION_SCHEMA.TABLE_OPTIONS` o
+FROM `my-project-id.crypto_data.INFORMATION_SCHEMA.TABLES` t
+LEFT JOIN `my-project-id.crypto_data.INFORMATION_SCHEMA.TABLE_OPTIONS` o
   ON t.table_name = o.table_name
 WHERE option_name = "labels"
 GROUP BY table_name, team, cost_center
@@ -1155,7 +1177,7 @@ entry for the view-definition SQL and an `exposes[]` entry it produces:
             ORDER BY price_timestamp
             ROWS BETWEEN 167 PRECEDING AND CURRENT ROW
           ) as deviation_from_7day_ma
-        FROM `fluid-crypto-tracker.crypto_data.bitcoin_prices`
+        FROM `my-project-id.crypto_data.bitcoin_prices`
         ORDER BY price_timestamp DESC
     outputs:
       - price_trends
@@ -1168,7 +1190,7 @@ entry for the view-definition SQL and an `exposes[]` entry it produces:
       platform: gcp
       format: bigquery_table
       location:
-        project: fluid-crypto-tracker
+        project: my-project-id
         dataset: crypto_data
         table: price_trends
     
@@ -1240,7 +1262,7 @@ exposes:
       platform: gcp
       format: bigquery_table
       location:
-        project: fluid-crypto-tracker
+        project: my-project-id
         dataset: crypto_data
         table: ethereum_prices
 ```
@@ -1248,7 +1270,7 @@ exposes:
 ### 📊 BI Dashboards
 
 Connect Looker, Tableau, or Google Data Studio:
-- Dataset: `fluid-crypto-tracker.crypto_data`
+- Dataset: `my-project-id.crypto_data`
 - Tables: `bitcoin_prices`, views: `daily_summary`, `price_trends`
 - Credentials: Service account with BigQuery Data Viewer role
 
@@ -1292,7 +1314,7 @@ FROM `crypto_data.bitcoin_prices`;
 
 Grant yourself BigQuery Admin role:
 ```bash
-gcloud projects add-iam-policy-binding fluid-crypto-tracker \
+gcloud projects add-iam-policy-binding my-project-id \
   --member="user:YOUR_EMAIL@example.com" \
   --role="roles/bigquery.admin"
 ```
@@ -1333,7 +1355,7 @@ To avoid any charges, delete everything:
 
 ```bash
 # Delete BigQuery dataset and all tables
-bq rm -r -f -d fluid-crypto-tracker:crypto_data
+bq rm -r -f -d my-project-id:crypto_data
 
 # Delete Cloud Function
 gcloud functions delete bitcoin-price-ingestion --region us-central1
@@ -1342,7 +1364,7 @@ gcloud functions delete bitcoin-price-ingestion --region us-central1
 gcloud scheduler jobs delete bitcoin-hourly-ingest --location us-central1
 
 # Delete project (removes everything)
-gcloud projects delete fluid-crypto-tracker
+gcloud projects delete my-project-id
 ```
 
 ---
diff --git a/docs/walkthrough/jenkins-cicd.md b/docs/walkthrough/jenkins-cicd.md
index 63283c7..02efe3b 100644
--- a/docs/walkthrough/jenkins-cicd.md
+++ b/docs/walkthrough/jenkins-cicd.md
@@ -102,6 +102,12 @@ bitcoin-tracker/
 
 ### 1. Jenkins Setup
 
+::: warning Substitute your own project id
+`my-project-id` on this page is a placeholder. Project ids are unique across the whole of Google
+Cloud, so replace it with your own in the commands, the credential, and the `environment` block
+below.
+:::
+
 **Prerequisites:**
 - Jenkins 2.x or later
 - Plugins:
@@ -118,7 +124,7 @@ bitcoin-tracker/
 // 1. Add GCP credentials
 Credentials → Add Credentials
   Kind: Google Service Account from private key
-  Project Name: fluid-crypto-tracker
+  Project Name: my-project-id
   ID: gcp-data-product-deployer
 
 // 2. Configure tools
@@ -151,16 +157,16 @@ Pipeline → Definition → Pipeline script from SCM
 # 1. Create service account
 gcloud iam service-accounts create fluid-cicd \
   --display-name="FLUID CI/CD Service Account" \
-  --project=fluid-crypto-tracker
+  --project=my-project-id
 
 # 2. Grant permissions
-gcloud projects add-iam-policy-binding fluid-crypto-tracker \
-  --member="serviceAccount:fluid-cicd@fluid-crypto-tracker.iam.gserviceaccount.com" \
+gcloud projects add-iam-policy-binding my-project-id \
+  --member="serviceAccount:fluid-cicd@my-project-id.iam.gserviceaccount.com" \
   --role="roles/bigquery.admin"
 
 # 3. Create key
 gcloud iam service-accounts keys create ~/fluid-cicd-key.json \
-  --iam-account=fluid-cicd@fluid-crypto-tracker.iam.gserviceaccount.com
+  --iam-account=fluid-cicd@my-project-id.iam.gserviceaccount.com
 
 # 4. Add to Jenkins credentials
 # Upload fluid-cicd-key.json as "Secret file" credential
@@ -177,7 +183,7 @@ gcloud auth application-default login
 In Jenkins job configuration:
 ```groovy
 environment {
-    GCP_PROJECT_ID = 'fluid-crypto-tracker'
+    GCP_PROJECT_ID = 'my-project-id'
     GOOGLE_APPLICATION_CREDENTIALS = credentials('gcp-data-product-deployer')
 }
 ```
diff --git a/scripts/check-dist-links.mjs b/scripts/check-dist-links.mjs
new file mode 100644
index 0000000..aad0fae
--- /dev/null
+++ b/scripts/check-dist-links.mjs
@@ -0,0 +1,631 @@
+#!/usr/bin/env node
+/**
+ * check-dist-links.mjs — the only gate in this repo that reads what actually
+ * deploys.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every other link gate here reads SOURCE MARKDOWN:
+ *
+ *   - the bundled @vuepress/plugin-links-check (config.ts: linksCheck.build =
+ *     'error') inspects markdown link tokens and filters targets on
+ *     /\.md(?:[?#]|$)/, so it sees roughly 861 of ~1331 internal links and
+ *     nothing that is not written as a .md target;
+ *   - link-check.yml's base-prefix-check greps `](/…)` in docs/**.md;
+ *   - link-check.yml's lychee-source runs lychee over docs/**.md.
+ *
+ * None of them can see the rendered artifact. Consequences, all proven against
+ * this checkout:
+ *
+ *   - a one-character typo in the navbar or sidebar array in
+ *     docs/.vuepress/config.ts ships a live 404 on 212 of 213 pages while all
+ *     five existing gates exit 0, because config.ts is not markdown;
+ *   - the landing page hero buttons live in docs/README.md FRONTMATTER, not in
+ *     its body, so no markdown-link gate reads them;
+ *   - raw HTML anchors in markdown, `.html`-suffixed targets and extensionless
+ *     targets are invisible to the .md filter.
+ *
+ * So this walks docs/.vuepress/dist/**.html — the bytes that get uploaded —
+ * and checks every absolute reference against the files that are actually
+ * there.
+ *
+ * DESIGNED AGAINST THE FAILURE MODE THIS REPO KEEPS HITTING
+ * --------------------------------------------------------
+ * The recurring defect class here is A GATE THAT REPORTS GREEN WHILE MEASURING
+ * THE WRONG THING (a lychee flag that made it exit before checking a URL; a
+ * log-string grep that passed when the wording changed; a per-line grep -v that
+ * threw a broken link away with a good one on the same line). Four structural
+ * defences, in order of importance:
+ *
+ *   1. CANARIES RUN IN-PROCESS, ALWAYS, BEFORE THE REAL SCAN. A synthetic
+ *      fixture carries one link that must resolve, one that must 404 and one
+ *      that is missing the base prefix. The real scan does not start until the
+ *      checker has proven, this run, that it both resolves and rejects. They
+ *      are not a separate workflow step precisely because a separate step can
+ *      be deleted while the gate keeps reporting green.
+ *   2. FLOORS on pages walked, absolute references examined and DISTINCT
+ *      targets resolved. A regex that decays to matching one link shape, or a
+ *      walk that finds an empty dist, fails instead of passing.
+ *   3. EVERY PAGE MUST CONTRIBUTE. A page that yields zero absolute references
+ *      is an extraction failure, not a clean page — except the handful of
+ *      genuinely self-contained pages named in ZERO_REF_ALLOWLIST.
+ *   4. IT PRINTS ITS CENSUS. Counts per resolution rule, per exclusion class,
+ *      the busiest targets. "Passed" with no numbers is indistinguishable from
+ *      "inspected nothing".
+ *
+ * PRIOR ART (searched before building; see the reuse note at the end of this
+ * comment)
+ * -------------------------------------------------------------------------
+ *   - lychee            https://github.com/lycheeverse/lychee
+ *   - hyperlink         https://github.com/untitaker/hyperlink
+ *   - htmltest          https://github.com/wjdp/htmltest
+ *   - html-proofer      https://github.com/gjtorikian/html-proofer
+ *   - proof-html        https://github.com/anishathalye/proof-html
+ *   - check-html-links  https://github.com/modernweb-dev/check-html-links
+ *
+ * All six check built HTML. None of them can express the rule that actually
+ * matters here — "an absolute reference MUST begin with /forge_docs/" — and
+ * that is not a gap worth papering over: proof-html's swap_urls approach strips
+ * the base before checking, which makes a link missing the base
+ * indistinguishable from one carrying it, i.e. it silently passes the exact bug
+ * this gate exists for. hyperlink explicitly refuses pretty URLs ("one cannot
+ * request /mypage and expect mypage.html"), which is 43 false failures on this
+ * site. And none of them assert a floor on what they inspected or print an
+ * inspection census, which is requirement 1-4 above.
+ *
+ * Reuse strategy: ADAPT THE PATTERN, do not add a dependency.
+ *   - scope ("check the built output, all tag types, internal only") is
+ *     htmltest's CheckInternal and check-html-links' model;
+ *   - the must-resolve / must-not-resolve canary pair is lifted from this
+ *     repo's own lychee-source job in .github/workflows/link-check.yml, which
+ *     established the discipline after lychee "ran" 12 scheduled times while
+ *     checking nothing;
+ *   - implemented in pure Node with no imports beyond node: builtins, so it
+ *     runs in the same job right after `npm run docs:build` with no extra
+ *     toolchain, no network and nothing to install.
+ *
+ * Usage:
+ *   node scripts/check-dist-links.mjs                 # canaries, then scan dist
+ *   node scripts/check-dist-links.mjs --self-test     # canaries only
+ *   node scripts/check-dist-links.mjs --relative=error  # also fail on broken
+ *                                                       # RELATIVE refs (see
+ *                                                       # KNOWN GAPS below)
+ *   node scripts/check-dist-links.mjs --dist DIR --base /prefix/
+ *
+ * Exit codes: 0 clean, 1 findings or a blind-gate assertion tripped.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs'
+import { join, resolve, relative, dirname, sep } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+// ---------------------------------------------------------------------------
+// Blind-gate floors.
+//
+// Measured on a clean build of 92925e5: 219 HTML files, 111,490 href/src
+// attributes of which 107,738 are absolute and same-origin, resolving to 474
+// distinct targets. The floors sit well below those so
+// ordinary growth or pruning does not trip them, and far above zero so a broken
+// walk, a decayed extractor or a half-written dist cannot pass. If a
+// legitimate change takes the site below a floor, RAISE THE PAGE COUNT OR LOWER
+// THE FLOOR DELIBERATELY, in a commit that says which — never delete the
+// assertion.
+// ---------------------------------------------------------------------------
+const FLOORS = {
+  pages: 180,      // 219 today
+  refs: 90000,     // 107,738 today
+  distinct: 400,   // 474 today
+}
+
+// Pages that legitimately carry no absolute reference at all. These six are
+// the standalone terminal reels shipped verbatim from docs/.vuepress/public/:
+// self-contained HTML with no site chrome, no navbar and no asset of their own.
+// Every OTHER page must contribute at least one absolute reference, because a
+// VuePress-rendered page always carries at least its own <script src>. A new
+// entry here needs a reason, not just a path.
+const ZERO_REF_ALLOWLIST = [/^reels\/[^/]+\.html$/]
+
+// ---------------------------------------------------------------------------
+// What is EXCLUDED from the "must exist in dist" check, and why.
+//
+//   - anything with a URI scheme (https:, mailto:, data:, javascript:) — off
+//     this artifact entirely. External reachability is link-check.yml's weekly
+//     `external` job.
+//   - protocol-relative (//host/…) — also a different origin.
+//   - fragment-only (#section) — same page; this gate checks FILE presence, not
+//     anchor targets. Anchors are an unguarded class: see KNOWN GAPS.
+//   - relative (./x, ../x, x.html) — resolved against the containing page.
+//     Counted and resolved, but WARN by default rather than fail; see KNOWN
+//     GAPS for the one live breakage that blocks flipping it to error.
+//   - empty href.
+//
+// Nothing else is excluded. There is no ignore-list of specific paths on
+// purpose: an ignore-list is how a gate ends up inspecting nothing.
+//
+// KNOWN GAPS, stated plainly so nobody mistakes this for total coverage:
+//   (a) fragment/anchor targets are not verified (#no-such-heading passes);
+//   (b) relative refs are checked at --relative=error. They were warn-only while
+//       docs/RELEASE_NOTES_0.7.11.md linked ./.vuepress/cli-version.json, a live
+//       404 in a file under a content freeze: a red gate nobody is permitted to
+//       fix is a gate that gets disabled. That link now points at the GitHub blob
+//       URL that docs/contributing.md already used for the same file, which
+//       changes a destination and not a single claim the release note makes. With
+//       the exception gone the leniency goes too.
+//
+// A bare /href="([^"]*)"/ over the raw bytes also matches text that merely
+// LOOKS like an attribute inside a <script> body or a highlighted code sample.
+// This walks tags, skips comments and skips the bodies of raw-text elements, so
+// only real attribute values are collected. Verified against the naive count on
+// a clean build: identical, 107,734 — the extra rigour costs nothing today and
+// stops a future code sample from producing a phantom finding.
+// ---------------------------------------------------------------------------
+const RAW_TEXT_ELEMENTS = new Set(['script', 'style', 'textarea', 'title'])
+const ATTR_RE = /\b(href|src)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>`=]+))/gi
+
+/** Index of the '>' closing the tag that starts at `start`, skipping quoted values. */
+function tagEnd(html, start) {
+  let quote = null
+  for (let i = start + 1; i < html.length; i++) {
+    const c = html[i]
+    if (quote) {
+      if (c === quote) quote = null
+    } else if (c === '"' || c === "'") {
+      quote = c
+    } else if (c === '>') {
+      return i
+    }
+  }
+  return html.length
+}
+
+function extractRefs(html) {
+  const refs = []
+  let i = 0
+  while (i < html.length) {
+    const lt = html.indexOf('<', i)
+    if (lt === -1) break
+    if (html.startsWith('<!--', lt)) {
+      const end = html.indexOf('-->', lt + 4)
+      i = end === -1 ? html.length : end + 3
+      continue
+    }
+    if (html.startsWith('<!', lt) || html.startsWith('</', lt) || html.startsWith('<?', lt)) {
+      i = tagEnd(html, lt) + 1
+      continue
+    }
+    const nameMatch = /^<([a-zA-Z][a-zA-Z0-9:-]*)/.exec(html.slice(lt, lt + 64))
+    if (!nameMatch) {
+      i = lt + 1
+      continue
+    }
+    const tag = nameMatch[1].toLowerCase()
+    const end = tagEnd(html, lt)
+    const openTag = html.slice(lt, end)
+    const selfClosing = openTag.endsWith('/')
+    for (const m of openTag.matchAll(ATTR_RE)) {
+      refs.push({ attr: m[1].toLowerCase(), tag, value: m[2] ?? m[3] ?? m[4] ?? '' })
+    }
+    i = end + 1
+    if (!selfClosing && RAW_TEXT_ELEMENTS.has(tag)) {
+      const close = new RegExp(`</${tag}[\\s>]`, 'i')
+      close.lastIndex = 0
+      const rest = html.slice(i)
+      const hit = close.exec(rest)
+      if (hit) i += hit.index
+    }
+  }
+  return refs
+}
+
+const ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'", '&apos;': "'" }
+
+function decodeRef(raw) {
+  const unescaped = raw.replace(/&(?:amp|lt|gt|quot|#39|apos);/g, (m) => ENTITIES[m])
+  const pathname = unescaped.split(/[?#]/)[0]
+  try {
+    return { pathname: decodeURIComponent(pathname), ok: true }
+  } catch {
+    // A malformed percent-escape is itself a broken reference. Do not swallow.
+    return { pathname, ok: false }
+  }
+}
+
+function walkHtml(dir) {
+  const out = []
+  const visit = (d) => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, entry.name)
+      if (entry.isDirectory()) visit(p)
+      else if (entry.isFile() && entry.name.toLowerCase().endsWith('.html')) out.push(p)
+    }
+  }
+  visit(dir)
+  return out.sort()
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Resolve a site-root-relative path inside dist, returning WHICH rule resolved
+ * it. The three rules are real, observed behaviours of the two things that
+ * serve this artifact, not conveniences:
+ *
+ *   exact    the file is there.
+ *   index    `/dir/` and `/dir` are served by dist/dir/index.html.
+ *   pretty   `/cli/init` is served by dist/cli/init.html. 95 references in the
+ *            built site (43 distinct) rely on this, so it was verified rather
+ *            than assumed, on both paths that serve this artifact:
+ *              - the live host, 2026-09-15 (.nojekyll is set by
+ *                deploy-docs.yml, and extensionless resolution is the Pages
+ *                static layer, not Jekyll):
+ *                  curl -s -o /dev/null -w '%{http_code}\n' \
+ *                    https://agenticstiger.github.io/forge_docs/cli/init
+ *                -> 200, while .../forge_docs/definitely-not-a-page -> 404, so
+ *                the host is not blanket-200ing unknown paths;
+ *              - VuePress's own client router on a soft navigation:
+ *                @vuepress/shared's inferRoutePath() appends '.html' to any
+ *                path lacking an extension
+ *                (node_modules/@vuepress/shared/dist/index.js).
+ *
+ * If that ever stops holding, this rule turns from a fact about the serving
+ * layer into a leniency that hides live 404s — which is why the buckets are
+ * counted and printed separately, so a shift toward the lenient rule is visible
+ * instead of silent.
+ */
+function resolveInDist(distRoot, relPath) {
+  const cleaned = relPath.replace(/^\/+/, '')
+  const target = resolve(distRoot, cleaned)
+  // Path traversal: /forge_docs/../secret escapes the artifact. Not resolvable.
+  if (target !== distRoot && !target.startsWith(distRoot + sep)) return null
+  if (isFile(target)) return 'exact'
+  if (isFile(join(target, 'index.html'))) return 'index'
+  if (!/\.[a-zA-Z0-9]+$/.test(cleaned) && isFile(`${target}.html`)) return 'pretty'
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// The scan.
+// ---------------------------------------------------------------------------
+function scan({ distRoot, base, relativeMode }) {
+  const pages = walkHtml(distRoot)
+  const census = {
+    pages: pages.length,
+    refs: 0,
+    absolute: 0,
+    byRule: { exact: 0, index: 0, pretty: 0 },
+    excluded: { scheme: 0, protocolRelative: 0, fragment: 0, relative: 0, empty: 0 },
+    zeroRefPages: [],
+    targetHits: new Map(),
+  }
+  const findings = []       // fatal
+  const relativeFindings = []
+
+  for (const file of pages) {
+    const pageRel = relative(distRoot, file)
+    const html = readFileSync(file, 'utf8')
+    let absoluteOnPage = 0
+
+    for (const ref of extractRefs(html)) {
+      census.refs++
+      const raw = ref.value.trim()
+
+      if (raw === '') { census.excluded.empty++; continue }
+      if (raw.startsWith('//')) { census.excluded.protocolRelative++; continue }
+      if (raw.startsWith('#')) { census.excluded.fragment++; continue }
+
+      if (!raw.startsWith('/')) {
+        if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(raw)) { census.excluded.scheme++; continue }
+        census.excluded.relative++
+        // Resolved against the directory of the containing page.
+        const { pathname, ok } = decodeRef(raw)
+        if (pathname === '') continue
+        const fromDir = join(distRoot, dirname(pageRel))
+        const abs = resolve(fromDir, pathname)
+        const asSiteRel = relative(distRoot, abs)
+        if (!ok || asSiteRel.startsWith('..') || !resolveInDist(distRoot, asSiteRel)) {
+          relativeFindings.push({ page: pageRel, ref: raw, attr: ref.attr, tag: ref.tag })
+        }
+        continue
+      }
+
+      // Absolute, same-origin. This is the class this gate owns.
+      census.absolute++
+      absoluteOnPage++
+      const { pathname, ok } = decodeRef(raw)
+
+      if (!ok) {
+        findings.push({ kind: 'undecodable', page: pageRel, ref: raw, attr: ref.attr, tag: ref.tag })
+        continue
+      }
+      if (!pathname.startsWith(base)) {
+        findings.push({ kind: 'missing-base', page: pageRel, ref: raw, attr: ref.attr, tag: ref.tag })
+        continue
+      }
+      const siteRel = pathname.slice(base.length)
+      const rule = resolveInDist(distRoot, siteRel)
+      if (!rule) {
+        findings.push({ kind: 'missing-file', page: pageRel, ref: raw, attr: ref.attr, tag: ref.tag })
+        continue
+      }
+      census.byRule[rule]++
+      census.targetHits.set(pathname, (census.targetHits.get(pathname) ?? 0) + 1)
+    }
+
+    if (absoluteOnPage === 0) census.zeroRefPages.push(pageRel)
+  }
+
+  census.distinct = census.targetHits.size
+  return { census, findings, relativeFindings, relativeMode }
+}
+
+// ---------------------------------------------------------------------------
+// Canaries. A synthetic dist with a known-good link, a known-missing link and
+// a link missing the base prefix. Run in-process before every real scan.
+// ---------------------------------------------------------------------------
+function runCanaries() {
+  const dir = mkdtempSync(join(tmpdir(), 'dist-links-canary-'))
+  try {
+    const base = '/canary_base/'
+    mkdirSync(join(dir, 'guide'), { recursive: true })
+    writeFileSync(join(dir, 'guide', 'index.html'), '<html><body><a href="/canary_base/real.html">dir page</a></body></html>')
+    // A real asset, so the fixture covers a non-.html target as well as a
+    // non-href ATTRIBUTE. Without a `src` in here the canaries could not tell
+    // that the extractor had stopped reading src at all: dropping `src` from
+    // ATTR_RE moves the artifact counts by 219 of 107,738 references, which
+    // clears every floor, and the gate then prints "Clean" while no asset
+    // reference in dist is checked. Verified: that mutant passed --self-test.
+    writeFileSync(join(dir, 'pic.png'), '')
+    writeFileSync(join(dir, 'real.html'), [
+      '<html><body>',
+      '<a href="/canary_base/real.html">must resolve — exact</a>',
+      '<img src="/canary_base/pic.png" alt="must resolve — exact, via src">',
+      '<script src="/canary_base/no-such-script.js"></script>',
+      '<a href="/canary_base/guide/">must resolve — index</a>',
+      '<a href="/canary_base/real">must resolve — pretty</a>',
+      '<a href="/canary_base/no-such-page.html">must NOT resolve — missing file</a>',
+      '<a href="/real.html">must NOT resolve — missing base prefix</a>',
+      '<pre><code>&lt;a href="/canary_base/not-a-real-link.html"&gt;in a code sample&lt;/a&gt;</code></pre>',
+      '<script>var s = "href=\\"/canary_base/also-not-a-link.html\\"";</script>',
+      '</body></html>',
+    ].join('\n'))
+
+    const { census, findings } = scan({ distRoot: resolve(dir), base, relativeMode: 'warn' })
+    const kinds = findings.map((f) => f.kind).sort()
+    const problems = []
+
+    if (census.pages !== 2) problems.push(`walked ${census.pages} canary pages, expected 2`)
+    if (census.byRule.exact !== 3) problems.push(`exact-rule resolutions ${census.byRule.exact}, expected 3`)
+    if (census.byRule.index !== 1) problems.push(`index-rule resolutions ${census.byRule.index}, expected 1`)
+    if (census.byRule.pretty !== 1) problems.push(`pretty-rule resolutions ${census.byRule.pretty}, expected 1`)
+    if (findings.length !== 3) problems.push(`reported ${findings.length} findings, expected exactly 3`)
+    if (kinds.join(',') !== 'missing-base,missing-file,missing-file') {
+      problems.push(`finding kinds were [${kinds.join(', ')}], expected [missing-base, missing-file, missing-file]`)
+    }
+    // The code sample and the script-body string must NOT have been collected.
+    // If either shows up, the extractor is reading page text as markup and
+    // every "finding" it reports is suspect.
+    if (findings.some((f) => /not-a-real-link|also-not-a-link/.test(f.ref))) {
+      problems.push('extractor picked up an attribute-shaped string out of a code sample or a <script> body')
+    }
+    // Both directions of the src class, named explicitly rather than left to the
+    // counts above: a src that resolves must be counted, and a src that does not
+    // must be reported. The coverage map in docs-pr-check.yml promises this gate
+    // sees <script src> and <img src>; this is what keeps that promise true.
+    if (census.byRule.exact !== 3 || !findings.some((f) => f.ref === '/canary_base/no-such-script.js')) {
+      problems.push(
+        'the src attribute class was not inspected — a <img src> that resolves ' +
+        'was not counted, or a <script src> pointing at a missing file was not ' +
+        'reported. Every asset reference in the artifact is unchecked, and the ' +
+        'floors cannot see it: src is ~0.2% of references here.')
+    }
+
+    return { problems, census, findings }
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+const isGitHub = Boolean(process.env.GITHUB_ACTIONS)
+const annotate = (level, msg) => console.log(isGitHub ? `::${level}::${msg}` : `[${level}] ${msg}`)
+
+function num(n) {
+  return n.toLocaleString('en-US')
+}
+
+function printCensus(census, base, distRoot) {
+  console.log('')
+  console.log('What this gate inspected')
+  console.log('------------------------')
+  console.log(`  artifact              ${relative(REPO_ROOT, distRoot) || distRoot}`)
+  console.log(`  required base prefix  ${base}`)
+  console.log(`  HTML pages walked     ${num(census.pages)}   (floor ${num(FLOORS.pages)})`)
+  console.log(`  href/src attributes   ${num(census.refs)}`)
+  console.log(`  absolute, same-origin ${num(census.absolute)}   (floor ${num(FLOORS.refs)})  <- the class this gate owns`)
+  console.log(`  distinct targets      ${num(census.distinct)}   (floor ${num(FLOORS.distinct)})`)
+  console.log('  resolved by rule      ' +
+    `exact ${num(census.byRule.exact)}, ` +
+    `dir index.html ${num(census.byRule.index)}, ` +
+    `extensionless +.html ${num(census.byRule.pretty)}`)
+  console.log('  excluded              ' +
+    `scheme (https:/mailto:/data:) ${num(census.excluded.scheme)}, ` +
+    `fragment-only ${num(census.excluded.fragment)}, ` +
+    `relative ${num(census.excluded.relative)}, ` +
+    `protocol-relative ${num(census.excluded.protocolRelative)}, ` +
+    `empty ${num(census.excluded.empty)}`)
+
+  const top = [...census.targetHits.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5)
+  console.log('  busiest targets       ' + (top.length
+    ? top.map(([p, n]) => `${p} (${num(n)})`).join(', ')
+    : 'none'))
+  if (census.zeroRefPages.length) {
+    console.log(`  pages with no absolute reference (allowlisted): ${census.zeroRefPages.join(', ')}`)
+  }
+  console.log('')
+}
+
+function main(argv) {
+  const arg = (name, fallback) => {
+    const hit = argv.find((a) => a === `--${name}` || a.startsWith(`--${name}=`))
+    if (!hit) return fallback
+    if (hit.includes('=')) return hit.slice(hit.indexOf('=') + 1)
+    const i = argv.indexOf(hit)
+    return argv[i + 1] ?? fallback
+  }
+  const selfTestOnly = argv.includes('--self-test') || argv.includes('--self-test-only')
+  const relativeMode = arg('relative', 'error')
+  if (!['warn', 'error'].includes(relativeMode)) {
+    annotate('error', `--relative must be warn or error, got "${relativeMode}"`)
+    return 1
+  }
+
+  // The base prefix is deliberately NOT read from docs/.vuepress/config.ts.
+  // config.ts is the thing under test: a typo'd base there must fail this gate,
+  // not teach it a new expectation. package.json's "homepage" is an independent
+  // declaration of where this site is published, so the two must agree.
+  const declaredHome = JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')).homepage
+  let base = arg('base', null)
+  if (!base) {
+    if (!declaredHome) {
+      annotate('error', 'package.json has no "homepage", so the deployment base prefix cannot be established. Refusing to guess.')
+      return 1
+    }
+    base = new URL(declaredHome).pathname
+  }
+  if (!base.startsWith('/')) base = `/${base}`
+  if (!base.endsWith('/')) base = `${base}/`
+  if (base === '/') {
+    annotate('error', `Resolved base prefix "/" — every absolute link would pass the prefix rule trivially. Refusing to run a check that cannot fail. Fix package.json "homepage" (got ${declaredHome}) or pass --base.`)
+    return 1
+  }
+
+  // --- canaries, always, first -------------------------------------------
+  console.log('Canaries (a link that must resolve, a link that must not, a link missing the base prefix)')
+  const canary = runCanaries()
+  if (canary.problems.length) {
+    for (const p of canary.problems) annotate('error', `Canary failed: ${p}`)
+    annotate('error', 'The dist link checker cannot be trusted this run: it failed its own must-resolve / must-not-resolve fixture. Refusing to report on the real artifact.')
+    return 1
+  }
+  // Derived from the canary run, never hardcoded. A fixed sentence is how a
+  // summary drifts away from what was actually measured: this line read
+  // "resolved 4 links … caught 1 missing file" for a fixture that resolved 5 and
+  // caught 2, so it was describing an earlier version of itself.
+  {
+    const c = canary.census
+    const kinds = canary.findings.reduce((a, f) => ({ ...a, [f.kind]: (a[f.kind] || 0) + 1 }), {})
+    const resolved = c.byRule.exact + c.byRule.index + c.byRule.pretty
+    const rules = ['exact', 'index', 'pretty'].map((r) => `${c.byRule[r] || 0} ${r}`).join(', ')
+    const caught = Object.keys(kinds).sort().map((k) => `${kinds[k]} ${k}`).join(', ')
+    console.log(`  ok — resolved ${resolved} references in the fixture (${rules}), caught ${caught},`)
+    console.log('       and did not mistake a code sample or a <script> body string for markup.')
+  }
+  if (selfTestOnly) {
+    console.log('')
+    console.log('--self-test only: not scanning the artifact.')
+    return 0
+  }
+
+  // --- the real scan ------------------------------------------------------
+  const distRoot = resolve(REPO_ROOT, arg('dist', 'docs/.vuepress/dist'))
+  if (!existsSync(distRoot)) {
+    annotate('error', `No artifact at ${distRoot}. This gate must run AFTER \`npm run docs:build\`; it has nothing to measure and will not pass by default.`)
+    return 1
+  }
+
+  const { census, findings, relativeFindings } = scan({ distRoot, base, relativeMode })
+  printCensus(census, base, distRoot)
+
+  let failed = false
+
+  // --- blind-gate assertions --------------------------------------------
+  // These come BEFORE the findings verdict on purpose. "No findings" from a
+  // scan that inspected almost nothing is the failure mode this repo keeps
+  // rediscovering, and it must never read as a pass.
+  if (census.pages < FLOORS.pages) {
+    annotate('error', `Walked only ${census.pages} HTML pages (floor ${FLOORS.pages}). A clean build renders 213 pages plus 6 static ones. Either the artifact is incomplete or the walk is broken — this run proves nothing about links.`)
+    failed = true
+  }
+  if (census.absolute < FLOORS.refs) {
+    annotate('error', `Examined only ${num(census.absolute)} absolute references (floor ${num(FLOORS.refs)}). A clean build carries ~107,700. The extractor is not seeing the page; a clean result here would be meaningless.`)
+    failed = true
+  }
+  if (census.distinct < FLOORS.distinct) {
+    annotate('error', `Resolved only ${census.distinct} DISTINCT targets (floor ${FLOORS.distinct}). A clean build has ~474. A high reference count with few distinct targets means the extractor is only seeing repeated site chrome (navbar/sidebar) and is blind to page bodies.`)
+    failed = true
+  }
+  const unexplainedZeroRef = census.zeroRefPages.filter((p) => !ZERO_REF_ALLOWLIST.some((re) => re.test(p)))
+  if (unexplainedZeroRef.length) {
+    annotate('error', `${unexplainedZeroRef.length} page(s) yielded ZERO absolute references, which a VuePress-rendered page cannot do (it always carries its own <script src>): ${unexplainedZeroRef.slice(0, 10).join(', ')}${unexplainedZeroRef.length > 10 ? ', …' : ''}`)
+    annotate('error', 'Either extraction failed on those pages or they are new self-contained pages. If the latter, add them to ZERO_REF_ALLOWLIST in scripts/check-dist-links.mjs with a reason — do not widen it blindly.')
+    failed = true
+  }
+  if (failed) {
+    annotate('error', 'Refusing to report on link health: the checker did not inspect enough of the artifact for a result to mean anything.')
+    return 1
+  }
+
+  // --- findings ----------------------------------------------------------
+  if (findings.length) {
+    const byKind = { 'missing-base': [], 'missing-file': [], undecodable: [] }
+    for (const f of findings) byKind[f.kind].push(f)
+
+    console.log('Broken absolute references in the built artifact')
+    console.log('-----------------------------------------------')
+    for (const [kind, list] of Object.entries(byKind)) {
+      if (!list.length) continue
+      console.log(`\n  ${kind} (${num(list.length)} occurrence(s), ${new Set(list.map((f) => f.ref)).size} distinct):`)
+      const seen = new Map()
+      for (const f of list) {
+        if (!seen.has(f.ref)) seen.set(f.ref, [])
+        seen.get(f.ref).push(f.page)
+      }
+      for (const [ref, pagesHit] of [...seen.entries()].sort((a, b) => b[1].length - a[1].length)) {
+        const uniquePages = [...new Set(pagesHit)]
+        console.log(`    ${ref}`)
+        console.log(`      ${num(pagesHit.length)} occurrence(s) across ${num(uniquePages.length)} page(s), e.g. ${uniquePages.slice(0, 3).join(', ')}`)
+      }
+    }
+    console.log('')
+    if (byKind['missing-base'].length) {
+      annotate('error', `${num(byKind['missing-base'].length)} absolute reference(s) in the built HTML do not start with ${base}. They will 404 on the live site. Body markdown links are NOT auto-prefixed: write /forge_docs/x, or use a relative path.`)
+    }
+    if (byKind['missing-file'].length) {
+      annotate('error', `${num(byKind['missing-file'].length)} absolute reference(s) point at a file that is not in the artifact. Nothing in dist serves them, so they are live 404s. Check for a typo in docs/.vuepress/config.ts (navbar/sidebar), in docs/README.md frontmatter (hero actions) or in a raw HTML anchor — none of those are read by any markdown-based gate.`)
+    }
+    if (byKind.undecodable.length) {
+      annotate('error', `${num(byKind.undecodable.length)} reference(s) carry a malformed percent-escape and cannot be resolved by a browser either.`)
+    }
+    return 1
+  }
+
+  // --- relative refs: secondary, and honest about it ---------------------
+  if (relativeFindings.length) {
+    console.log('Broken RELATIVE references (secondary check)')
+    console.log('-------------------------------------------')
+    for (const f of relativeFindings) console.log(`  ${f.page}  ->  ${f.ref}`)
+    console.log('')
+    const msg = `${relativeFindings.length} relative reference(s) in the built artifact resolve to nothing in dist.`
+    if (relativeMode === 'error') {
+      annotate('error', msg)
+      return 1
+    }
+    annotate('warning', `${msg} NOT failing the build, because this run passed --relative=warn. The default is error.`)
+  }
+
+  console.log(`Clean: all ${num(census.absolute)} absolute references across ${num(census.pages)} built pages carry the ${base} base and name a file that exists in the artifact.`)
+  return 0
+}
+
+process.exit(main(process.argv.slice(2)))