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.

.gitea/workflows/lint.yml

@@ -172,3 +172,46 @@ jobs:
 
       - name: Vendored pi-extensions skill floor matches the package
         run: bash scripts/check-skill-floor.sh
+
+  doc-drift:
+    # Gate hand-maintained doc claims against the build files they describe.
+    # Its own job for the same reason as skill-floor: "the docs lie" should be a
+    # distinct red name, not a line buried in a job about workflow syntax.
+    #
+    # The gap it closes, measured 2026-09-10 while preparing v1.9.0 — five
+    # claims had rotted, every one of them a fact written by hand in a file
+    # nothing verified:
+    #   * README.md's "Version pins" table was wrong on ALL THREE rows (pi
+    #     0.84.4 vs 0.85.1, pi-atelier v0.10.0 vs v0.10.1, mempalace 3.8.0 vs
+    #     3.9.0) — and that table exists specifically to be the reviewable
+    #     record of what the repo freezes on purpose, so a wrong row destroys
+    #     the only thing it is for.
+    #   * README.md listed already-shipped typst PDF export under "Planned for
+    #     an upcoming minor release", marked "(shipped in Unreleased/base)".
+    #   * DOCKER_HUB.md claimed "Node.js v22" while v1.9.0 ships Node 24.
+    #
+    # DOCKER_HUB.md is why this is a gate and not a habit. It is PUBLISHED —
+    # update-description POSTs it to Docker Hub as full_description on every tag
+    # — and it had gone eight releases (v1.8.6 -> v1.9.0) untouched. Nothing
+    # generates it and nothing checked it, so the only thing keeping it true was
+    # someone remembering. It is also read from the TAG, so a fix pushed to main
+    # after tagging never reaches the published page.
+    #
+    # Cheap and hermetic on purpose: every check compares a doc string against a
+    # value that exists in this repo, so no network, no token, no built image,
+    # and no sibling clone. Claims that genuinely need a running container (image
+    # sizes, the "N mempalace_* tools" count) are deliberately left out — a gate
+    # that cannot evaluate a claim honestly would have to guess, and a guessing
+    # gate is worse than none. Assert those in scripts/smoke-test.sh instead.
+    #
+    # Exit codes 0 in sync / 1 drift / 2 cannot-run, matching lint-shell.sh and
+    # check-skill-floor.sh. A renamed ARG makes the gate blind, so that is a red
+    # 2, not a green tick.
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Doc claims match the build files
+        run: bash scripts/check-doc-drift.sh