feat(ci): gate documentation drift, and make docs a pre-tag release step

Five doc claims had rotted by v1.9.0, all the same shape: a value written once
by hand, in a file nothing verifies, about a number that lives elsewhere and
moved. README pin table wrong on all three rows; a "Planned" section describing
something already shipped; DOCKER_HUB.md claiming Node v22 against Node 24.

DOCKER_HUB.md is why this is a gate and not a resolution to be careful: it is
PUBLISHED (update-description POSTs it as Docker Hub full_description on every
tag), it had gone eight releases untouched, nothing generates it, and it is read
from the TAG -- so the stale page shipped with v1.9.0 regardless.

scripts/check-doc-drift.sh: seven checks, all repo-local (no network, token,
image, or sibling clone). Exit 0/1/2 matching lint-shell.sh; a renamed ARG is a
red 2, not a green tick. Wired as a fourth lint.yml job so "the docs lie" is its
own red name.

Verified with 15 controls, including two false-positive controls: the first
placeholder check flagged README.md:900, a Go template in a legitimate
`docker inspect --format` example. The gate was wrong, not the doc, so the
pattern is now anchored to the UPPER_SNAKE convention CI substitutes.

Not gated, deliberately: counts/sizes needing a running image (they belong in
smoke-test.sh -- a guessing gate is worse than none), and Dockerfile.base
BASE_REBUILD_DATE, because base_tag hashes that file content-wise and demanding
it be current would force a ~60 min rebuild on releases that touch no base
files. Free during a rebuild, expensive otherwise.

AGENTS.md step 3 rewritten around the mechanism: checkout@v4 with no ref: means
every job reads github.ref, the tag. Docs must be right BEFORE tagging.

AGENTS.md

@@ -92,7 +92,44 @@ re-brand of opencode-devbox's `pi-only` variant.
    is hashed into `base_tag`, so it costs a base rebuild (~67 min); and if the
    section the phrase canary names has changed, re-pin it in
    `scripts/smoke-test.sh`.
-3. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
+3. **Update the docs this release makes stale — BEFORE you tag.** Rename
+   `CHANGELOG.md`'s `## Unreleased` to `## vX.Y.Z — YYYY-MM-DD` (em dash, as
+   every prior release heading uses), then run the gate:
+
+   ```bash
+   bash scripts/check-doc-drift.sh      # 0 in sync / 1 drift / 2 cannot run
+   ```
+
+   It compares README.md's version-pin table against the ARGs it names, and
+   DOCKER_HUB.md's Node claim against `ARG NODE_VERSION`, plus Hub's
+   25 000-char limit, unsubstituted `{{PLACEHOLDERS}}`, and stale `Unreleased`
+   pointers in user-facing docs.
+
+   **Why before and not after:** `docker-publish.yml` runs `actions/checkout@v4`
+   with no `ref:`, so every job reads `github.ref` — the **tag**. A doc fix
+   pushed to `main` after tagging does not reach the release, and for
+   `DOCKER_HUB.md` it does not reach the published Hub page either, because
+   `update-description` POSTs that file as Docker Hub's `full_description` from
+   the tag's tree. Getting it in afterwards means re-pointing the tag, which is
+   its own hazard (v1.8.14 went `601fc98` → `361babd` and broke deploy
+   verification until `git fetch --tags --force`).
+
+   The gate is deliberately narrow — it only checks claims verifiable from files
+   in this repo. Still eyeball, because these are NOT gated:
+   - counts and sizes (`~1.1 GB`, "N `mempalace_*` tools", "7 extensions") —
+     they need a running image; assert them in `scripts/smoke-test.sh` instead
+   - feature prose that quietly became false, e.g. a "Planned for an upcoming
+     release" section describing something that already shipped
+   - `Dockerfile.base`'s `# BASE_REBUILD_DATE:` marker. Ungated on purpose:
+     `base_tag` hashes Dockerfile.base's content, comments included, so
+     demanding it be current would force a ~60 min base rebuild on a release
+     that touched no base files. **Fix it when the base is already rebuilding —
+     then it is free.**
+
+   Measured cost of skipping this, 2026-09-10 (v1.9.0): five stale claims, one
+   of them published. README's pin table was wrong on all three rows, and
+   DOCKER_HUB.md — untouched for eight releases — still said Node v22 while the
+   image shipped Node 24.
 4. Verify `docker compose up` works locally with the current `latest` image
    if you're upgrading users from a previous version. Then run the
    **post-recreate sanity check** inside the running container to confirm