docs(release): make docs/releases/ the authoring source, and finish the curation method

.github/workflows/pages.yml

@@ -97,7 +97,9 @@ jobs:
       # that breaks a plan/development page fails here rather than on `main`.
       - name: Build the dev scope (repo-internal docs included)
         env:
-          MKDOCS_EXCLUDE_DOCS: /README.md
+          # /releases/ stays excluded on dev too — those files are GitHub Release
+          # bodies, not site pages (mkdocs.yml documents why).
+          MKDOCS_EXCLUDE_DOCS: "/README.md\n/releases/\n"
         run: mkdocs build --strict --site-dir _site-dev
 
   # Push to main: re-run the PR gate against the merged tree.
@@ -129,7 +131,9 @@ jobs:
       - run: mkdocs build --strict --site-dir _site
       - name: Build the dev scope (repo-internal docs included)
         env:
-          MKDOCS_EXCLUDE_DOCS: /README.md
+          # /releases/ stays excluded on dev too — those files are GitHub Release
+          # bodies, not site pages (mkdocs.yml documents why).
+          MKDOCS_EXCLUDE_DOCS: "/README.md\n/releases/\n"
         run: mkdocs build --strict --site-dir _site-dev
 
   # Push/dispatch: update the mike version tree on gh-pages and deploy it.
@@ -322,8 +326,11 @@ jobs:
           # !ENV default only applies when the variable is ABSENT: a
           # conditional expression falling through to '' would publish the
           # internal docs on every release instead.
+          #
+          # /releases/ is excluded here too: GitHub Release bodies are authored
+          # for github.com's renderer and publish as literal text under MkDocs.
           if [[ "${VERSION}" == "dev" ]]; then
-            export MKDOCS_EXCLUDE_DOCS='/README.md'
+            export MKDOCS_EXCLUDE_DOCS=$'/README.md\n/releases/\n'
           fi
 
           # Links from the docs into the source tree resolve against the ref

docs/README.md

@@ -21,6 +21,7 @@ point see [DESIGN.md](../DESIGN.md).
 | [development/](development/README.md) | Developer workflow — building, testing, kind iteration, Go workspaces, code generation. |
 | [operations/](operations/README.md) | Operator guides — runbook, troubleshooting, observability, upgrades, tenant onboarding. |
 | [plan/](plan/README.md) | Implementation plans and audits. Authoritative ordering lives in [STATUS.md](STATUS.md). |
+| [releases/](releases/README.md) | The curated GitHub Release body for each stable tag, verbatim. Authoring source, not a site page. |
 
 ## Find your path
 

docs/STATUS.md

@@ -60,6 +60,9 @@ Specific actionable items in priority order. Pick from the top; skip 🚫 items
 | <a id="Q630"></a>Q630 | [A healthy quiet e2e leg is indistinguishable from a wedged one, so the stall report is unusable](../scripts/dogfood/release-sentinel.sh) | `dogfood` `tests` | 🔲 | S | Stall keys on status-file writes, which need relayed heartbeats, which need a fetchable job log. GitHub served `BlobNotFound` for a whole 30-min PASSED run: `hb: none`, false stalls, and re-firing instantly on relaunch. Consult run status instead. |
 | <a id="Q631"></a>Q631 | [The release gate starves itself: routed CI and the e2e leg draw on one global CPU budget](plan/gke-dogfood.md#part-f--e2e-on-gke-kata-containers) | `dogfood` `debt` | 🔲 | S | Deploy routes CI to GAG, scaling `workers` to 8 (32 vCPU) out of the same `CPUS_ALL_REGIONS` the e2e pool then needs. Cost two rc.5 runs at the old limit of 32. Raised to 64, so 52 worst case now fits — but nothing caps the competition. |
 | <a id="Q623"></a>Q623 | [`no-plan-refs-in-code` only scopes Go, but shell and workflow comments rot the same way](../scripts/docs/check-no-plan-refs-in-code.sh) | `ci` `debt` `retro` | 🔲 | S | Three shell files already carry `docs/plan/archive/` paths — they rotted and were repaired by hand. Extending needs care, not a wider glob: workflow `paths:` filters and `probe-investigations-cd.sh` (reads a plan file as data) are legitimate. |
+| <a id="Q635"></a>Q635 | [`doc-links` never reads a new doc's own links until it is staged, so it passes on a file it did not scan](../scripts/docs/check-doc-links.sh) | `ci` `debt` | 🔲 | S | `git ls-files -- '*.md'` lists tracked sources; the existence oracle deliberately adds untracked ones, so a link *to* a new file resolves while links *from* it are never read. Green, on a file count short by one. |
+| <a id="Q636"></a>Q636 | [No gate checks a release note's links, and they are the one doc whose links are all absolute](releases/README.md) | `ci` `docs` | 🔲 | S | `docs/releases/` is now in-repo, but `check-doc-links` skips external URLs, so every anchor into the versioned site is unverified. `site/` is a working oracle — resolving the v1.3.0 notes against it caught a planted bad anchor. |
+| <a id="Q637"></a>Q637 | [The release gate asserts nothing about the capacity gate or the namespace-quota rung](../scripts/dogfood/validate-release.sh) | `dogfood` `tests` | 🔲 | M | `validate-release.sh` has zero references to `capacityGate`, `nodeAutoscaling` or quota; its legs are deploy, e2e, sizing, CRD smoke. It builds an autoscaling cluster with headroom, so the constrained path is never driven on real infra. |
 | <a id="Q166"></a>Q166 | [v2 API M4: cross-namespace EgressProxy sharing](plan/v2-api.md) | `security` `feature` | 🔲 | M | Demand fired 2026-08-01: `sharing.allowedNamespaces` is served v2beta1 API with no enforcement (#1079 sweep), so the beta contract would harden a dormant field. Next: M4 consent check, CA distribution, dual-side NetworkPolicy. |
 | <a id="Q408"></a>Q408 | [Untrusted-PR egress posture for Kata workers](plan/q408-untrusted-pr-egress.md) | `security` | 🔲 | L | Demand fired 2026-07-31; plan written. Athens pattern (Q244) applied to images: per-upstream pull-through mirrors, then swap `e2e-open-egress` for a mirror-scoped NP. Next: Phase 0 egress inventory. |
 | <a id="Q606"></a>Q606 | [A hard-killed AGC still replays an assignment it concluded but had not yet deleted](plan/q603-settle-delete-gap.md#the-residual-stated-precisely) | `bug` | 🔲 | M | Q603 closed the graceful half; a hard kill between `settle` and its `DELETE` remains, and no ordering can close it. Both candidate fixes need something first — a live measurement, or a [Q597](#Q597) decision — and the plan doc states which. |

docs/development/website.md

@@ -402,6 +402,7 @@ Scope is **per version**, not per site (Q558):
 |---|---|
 | `stable` and every numbered release | Operator docs only: `docs/design/`, `docs/operations/`, `docs/index.md`, `why-gag.md`, `features.md`, `roadmap.md` |
 | `dev` | The above **plus** the repo-internal docs: `docs/STATUS.md` (the [backlog](#the-backlog-page)), `docs/plan/`, `docs/development/` (this file included), `docs/assets/`'s READMEs |
+| *no version* | `docs/releases/` — see the trap below |
 
 A release is a frozen build, so a backlog published in one would be a snapshot
 stale from tag day. `dev` redeploys on every push to `main`, which is the only
@@ -426,6 +427,14 @@ Two traps worth keeping in mind when editing that wiring:
   the list keeps that from surfacing as a build warning. Because it is never a
   site page, a doc that links to it must use the absolute `github.com` URL — a
   relative `../README.md` fails `mkdocs build --strict`.
+- **`docs/releases/` is excluded on every version too**, and it is the one entry
+  that is not a repo-internal-vs-operator split: those files are GitHub Release
+  bodies, authored for github.com's comment-flavour renderer. Their GFM alerts
+  (`> [!WARNING]`) have no MkDocs equivalent and would publish as literal text,
+  and their links already point into the versioned site. The exclusion is spelled
+  out in **four** places that must agree — `mkdocs.yml`'s default, the two `env:`
+  blocks and the one `export` in `pages.yml`, and `scripts/docs/docs-preview.sh`.
+  Miss the last and `make docs-build` disagrees with CI.
 
 PR builds validate **both** scopes (`pages.yml`'s `build` job runs `mkdocs build`
 twice), so a PR that breaks a plan or development page fails there rather than on