From 329791c9e95907e1fb9da60cc4f0ddc8c2f8c823 Mon Sep 17 00:00:00 2001
From: Speculator55005 <50082482+fas89@users.noreply.github.com>
Date: Tue, 15 Sep 2026 06:32:43 +0200
Subject: [PATCH 1/2] docs: a link gate that reads what ships, and the last GCP
 project id
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four things, and the first is the one that matters.

THE ARTIFACT GATE. Every link gate here read SOURCE MARKDOWN: the bundled
links-check plugin filters candidates on /\.md(?:[?#]|$)/ and so sees about 861
of ~1331 internal links; base-prefix-check greps `](/…)`; lychee-source runs over
docs/**.md. None can see the bytes that deploy. Measured on 92925e5: a
one-character typo in the config.ts navbar (`/why` -> `/whyy`) leaves
`npm run docs:build` exiting 0 while shipping 424 dead references across 212 of
the 213 rendered pages. scripts/check-dist-links.mjs walks
docs/.vuepress/dist/**.html instead — 219 pages, 107,738 absolute references,
474 distinct targets on this build, with the census printed, because "passed"
with no numbers is indistinguishable from "inspected nothing".

Its canaries run IN-PROCESS before every scan rather than as a separate step, a
separate step being deletable while the gate keeps reporting green, and there are
floors on pages, references and distinct targets. That machinery earned its keep
immediately: the first version's fixture contained only `<a href>` elements, so
dropping `src` from the extractor moved the counts by 219 of 107,738 — under
every floor — and the gate printed "Clean" while no asset reference in dist was
checked. Reproduced, then closed: the fixture now carries a resolving `<img src>`
and a failing `<script src>`, and that mutant fails four separate assertions. The
"ok" line now derives from the census too; it was a fixed sentence describing an
earlier version of itself.

The step's coverage map says which gate owns which class, so nobody deletes a
sibling believing it redundant. One cell in it was wrong and is corrected: lychee
DOES read raw HTML anchors in markdown, measured, not inferred.

THE SECOND GCP PROJECT ID. `fluid-crypto-tracker` was mostly illustrative, but
two sites were the same shape as the id removed earlier:

    project_id = os.getenv("GCP_PROJECT_ID", "fluid-crypto-tracker")

feeding straight into bigquery.Client(project=project_id). A reader who copies
the script and forgets the export writes to whoever owns that id, silently. The
second one is a deployed Cloud Function on an hourly schedule. Both now fail
loudly with a usage line; the function returns 500. 35 occurrences gone, the
remaining placeholders follow the convention already used elsewhere in the same
file.

THE RELEASE BANNER was a single 266-word paragraph and led with `0.15.0` while
the page's own version line said `0.15.1`. Now: the upgrade break first (a
`0.14.1`-clean contract can fail), three scannable bullets, history collapsed
with each version linking its own notes. It also credited the MCP output-port
gateway to `0.8.7`; RELEASE_NOTES_0.8.6 headlines it and 0.8.7 says outright that
it adds no features. Corrected to `0.8.6`.

THE MONACO MECHANISM is recorded where someone will meet it. Monaco's CSS is
162,004 of the single 251,769-byte stylesheet — 64.3%, contiguous from
`.monaco-aria-container` — on all 213 pages, because bundler-vite 2.0.0-rc.31
hard-sets `cssCodeSplit: false` at dist/index.js:108. Its JAVASCRIPT is split
correctly: 13.1 MB in async chunks that no prerendered page references. The
comment records that overriding the option is mechanically possible via
viteOptions and that the fix is DECLINED rather than blocked, with the reason,
plus the commands to re-verify every number. Comment only: +60/-0, and the built
HTML is byte-identical across all 219 pages.

Verified here, not taken on report: build 0 and gate 1 on the seeded typo (424
refs, 212 pages), both 0 restored; the src mutant caught; lychee reproducing the
raw-anchor finding; zero `fluid-crypto-tracker` in tracked files; check_cli_docs
green (1093 documented invocations, every version claim agreeing with the 0.15.1
pin); check_providers green.
---
 .github/workflows/docs-pr-check.yml |  80 +++-
 docs/.vuepress/config.ts            |  60 +++
 docs/README.md                      |  47 +-
 docs/walkthrough/gcp.md             |  82 ++--
 docs/walkthrough/jenkins-cicd.md    |  18 +-
 scripts/check-dist-links.mjs        | 642 ++++++++++++++++++++++++++++
 6 files changed, 885 insertions(+), 44 deletions(-)
 create mode 100644 scripts/check-dist-links.mjs

diff --git a/.github/workflows/docs-pr-check.yml b/.github/workflows/docs-pr-check.yml
index 0cf3b3c..d836dc1 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     | warn (see the script header)
+      #
+      # 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/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..d0fa65d
--- /dev/null
+++ b/scripts/check-dist-links.mjs
@@ -0,0 +1,642 @@
+#!/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 default to warn. There is one real live 404 today,
+//       confirmed against the published site on 2026-09-15:
+//         curl -s -o /dev/null -w '%{http_code}\n' \
+//           https://agenticstiger.github.io/forge_docs/.vuepress/cli-version.json
+//         -> 404   (the page carrying the link, RELEASE_NOTES_0.7.11.html, -> 200)
+//       docs/RELEASE_NOTES_0.7.11.md links ./.vuepress/cli-version.json, and
+//       .vuepress/ is not copied into dist. lychee-source resolves it against a
+//       mirror where docs/.vuepress/ IS present, so it passes there;
+//       links-check ignores it because the target is not .md. Fix it the way
+//       docs/contributing.md already does (link the file on github.com), then
+//       switch the workflow step to --relative=error and delete this paragraph.
+//       RELEASE_NOTES files are frozen, so this gate does not fail on it —
+//       a red gate nobody is allowed to fix is a gate that gets disabled.
+//   (c) CSS url(...) references are not read.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Reference extraction: a tag-aware scan, not a bare regex over the file.
+//
+// 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', 'warn')
+  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 --relative defaults to warn: one of these lives in a RELEASE_NOTES file that is frozen. Fix them and switch the step to --relative=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)))

From 38beeb86ce2e97d37c8e8de01dde96ce607d661a Mon Sep 17 00:00:00 2001
From: Speculator55005 <50082482+fas89@users.noreply.github.com>
Date: Tue, 15 Sep 2026 08:42:22 +0200
Subject: [PATCH 2/2] docs: close the last live 404, and stop the relative
 check being lenient about it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`docs/RELEASE_NOTES_0.7.11.md` linked `./.vuepress/cli-version.json`. `.vuepress/`
is not copied into dist, so that resolved to nothing on the live site: 404 on the
file while the page carrying it returned 200. The gate reported it warn-only and
said why in its own header — a red gate nobody is permitted to fix is a gate that
gets disabled — so the leniency was load-bearing on the defect existing.

The link now points at the GitHub blob URL that `docs/contributing.md` already
used for the same file, in the same sentence. That changes a destination, not a
claim: the release note still says exactly what `0.7.11` did, which is the line
between fixing a link in a frozen file and rewriting its history. New destination
verified 200.

With the exception gone, `--relative` defaults to `error` rather than `warn`, and
the coverage map's relative row is a YES instead of a footnote. The flag still
accepts `warn` for a local run.

Verified: relative references fall 9 to 8 and scheme rises 970 to 971, which is
the one link moving from one class to the other, and the "Broken RELATIVE
references" section is gone. Then the tightening proved load-bearing rather than
assumed — a raw `<a href="./no-such-relative-target.html">` appended to
docs/why.md leaves `npm run docs:build` exiting 0 while the gate exits 1 and names
`why.html -> ./no-such-relative-target.html`; the same run with `--relative=warn`
exits 0. Seed removed, build and gate clean, self-test clean.
---
 .github/workflows/docs-pr-check.yml |  2 +-
 docs/RELEASE_NOTES_0.7.11.md        |  2 +-
 scripts/check-dist-links.mjs        | 29 +++++++++--------------------
 3 files changed, 11 insertions(+), 22 deletions(-)

diff --git a/.github/workflows/docs-pr-check.yml b/.github/workflows/docs-pr-check.yml
index d836dc1..19724db 100644
--- a/.github/workflows/docs-pr-check.yml
+++ b/.github/workflows/docs-pr-check.yml
@@ -60,7 +60,7 @@ jobs:
       #   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     | warn (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
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/scripts/check-dist-links.mjs b/scripts/check-dist-links.mjs
index d0fa65d..aad0fae 100644
--- a/scripts/check-dist-links.mjs
+++ b/scripts/check-dist-links.mjs
@@ -147,24 +147,13 @@ const ZERO_REF_ALLOWLIST = [/^reels\/[^/]+\.html$/]
 //
 // 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 default to warn. There is one real live 404 today,
-//       confirmed against the published site on 2026-09-15:
-//         curl -s -o /dev/null -w '%{http_code}\n' \
-//           https://agenticstiger.github.io/forge_docs/.vuepress/cli-version.json
-//         -> 404   (the page carrying the link, RELEASE_NOTES_0.7.11.html, -> 200)
-//       docs/RELEASE_NOTES_0.7.11.md links ./.vuepress/cli-version.json, and
-//       .vuepress/ is not copied into dist. lychee-source resolves it against a
-//       mirror where docs/.vuepress/ IS present, so it passes there;
-//       links-check ignores it because the target is not .md. Fix it the way
-//       docs/contributing.md already does (link the file on github.com), then
-//       switch the workflow step to --relative=error and delete this paragraph.
-//       RELEASE_NOTES files are frozen, so this gate does not fail on it —
-//       a red gate nobody is allowed to fix is a gate that gets disabled.
-//   (c) CSS url(...) references are not read.
-// ---------------------------------------------------------------------------
-
-// ---------------------------------------------------------------------------
-// Reference extraction: a tag-aware scan, not a bare regex over the file.
+//   (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.
@@ -495,7 +484,7 @@ function main(argv) {
     return argv[i + 1] ?? fallback
   }
   const selfTestOnly = argv.includes('--self-test') || argv.includes('--self-test-only')
-  const relativeMode = arg('relative', 'warn')
+  const relativeMode = arg('relative', 'error')
   if (!['warn', 'error'].includes(relativeMode)) {
     annotate('error', `--relative must be warn or error, got "${relativeMode}"`)
     return 1
@@ -632,7 +621,7 @@ function main(argv) {
       annotate('error', msg)
       return 1
     }
-    annotate('warning', `${msg} NOT failing the build, because --relative defaults to warn: one of these lives in a RELEASE_NOTES file that is frozen. Fix them and switch the step to --relative=error.`)
+    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.`)