feat(devx): a docs gate binds each CLI transcript in content/docs to the registry it quotes, so a derived count cannot drift silently

.github/workflows/lint.yml

@@ -4684,6 +4684,39 @@ jobs:
       - name: Build workspace packages
         run: pnpm exec turbo run build --filter='./packages/*' --filter='./examples/*^...'
 
+      # CLI transcripts in content/docs are bound to the registries they quote
+      # (#15373). `content/docs` teaches with pasted CLI output, and some of those
+      # lines quote a number the CLI derives from a live registry at runtime —
+      # `Running author-time rules (42)...` is `authoringRulesFor(<command>).length`.
+      # The page wrote it as a literal; nothing derived it and nothing compared it,
+      # so it drifted on every rule added. Four published pages carried 41 against a
+      # registry holding 42, and what surfaced it was a customer-simulation upgrade
+      # run noticing the CLI printed something else. PR #15369 fixed the four
+      # numbers; this is the mechanism.
+      #
+      # ⚠ ORDER / PLACEMENT — this step is HERE, and not with the other docs gates
+      # in the `Lint & Repo Gates` job, for a measured reason. It derives the number
+      # the way the CLI does, by importing the BUILT @objectstack/lint, so it needs
+      # a dist/:
+      #
+      #   · `Lint & Repo Gates` runs `pnpm install` and NEVER builds. Placed there
+      #     the gate would exit 3 (PREREQUISITE NOT MET) on every CI run forever —
+      #     a gate that never measures, which is the shape #4642 named.
+      #   · ci.yml's `Build Core` builds, and hosts `check:dual-build-cjs-loads` for
+      #     exactly this reason, but it is gated on the `core` paths filter, which
+      #     does not include `content/**` — so it would skip the docs-only PRs that
+      #     ADD a stale transcript, the direction this gate exists for.
+      #   · This lane has NO paths filter, sits behind the required `TypeScript Type
+      #     Check` context, and the step above already built packages/lint.
+      #
+      # So it must stay AFTER `Build workspace packages`. It adds no build and no CI
+      # minutes; the scan is ~405 pages plus one dynamic import, ~0.4s. The gate's
+      # own header is the authority on the declaration syntax (fence meta, measured
+      # against the real fumadocs/MDX pipeline) and on why this is a COMPARE rather
+      # than a stamp. Runs its own --self-test first, through the alias.
+      - name: CLI transcripts in content/docs match the registry they quote
+        run: pnpm check:docs-transcript-drift
+
       # The per-package `typecheck` scripts the coverage gate above requires
       # (#4311). tsc resolves workspace imports through each dependency's built
       # dist/*.d.ts, so the task carries `dependsOn: ^build` in turbo.json —

content/docs/deployment/cli.mdx

@@ -444,7 +444,7 @@ os compile --json                    # JSON output for CI pipelines
 - `--json` — Output compile result as JSON (for CI)
 
 **Output example:**
-```
+```text transcript=os-build
 ◆ Compile
 ────────────────────────────────────────
   → Loading configuration...

content/docs/deployment/validating-metadata.mdx

@@ -548,7 +548,7 @@ runs the other two.
 
 A clean run walks the registry and reports timing:
 
-```
+```text transcript=os-validate
 ◆ Validate
 ────────────────────────────────────────
   → Loading configuration...

content/docs/getting-started/build-with-claude-code.mdx

@@ -259,7 +259,7 @@ visible: 'status != "resolved"'
 
 `npm run validate` (which `AGENTS.md` tells the agent to run) refuses it:
 
-```
+```text transcript=os-validate
 ◆ Validate
 ────────────────────────────────────────
   → Validating against ObjectStack Protocol...

content/docs/ui/react-pages.mdx

@@ -372,7 +372,7 @@ too:
 objectstack validate
 ```
 
-```
+```text transcript=os-validate
 ◆ Validate
 ────────────────────────────────────────
   → Loading configuration...

package.json

@@ -48,6 +48,7 @@
     "check:docs-single-h1": "node scripts/check-docs-single-h1.mjs --self-test && node scripts/check-docs-single-h1.mjs",
     "check:docs-audit-scope": "node scripts/docs-audit/affected-docs.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs --self-test && node scripts/docs-audit/check-audit-scope.mjs",
     "check:docs-redirects": "node scripts/check-docs-redirects.mjs --self-test && node scripts/check-docs-redirects.mjs",
+    "check:docs-transcript-drift": "node scripts/docs-audit/check-docs-transcript-drift.mjs --self-test && node scripts/docs-audit/check-docs-transcript-drift.mjs",
     "check:docs-locale-catch-all": "node scripts/check-docs-locale-catch-all.mjs --self-test && node scripts/check-docs-locale-catch-all.mjs",
     "check:docs-image-tag": "node scripts/check-docs-image-tag.mjs --self-test && node scripts/check-docs-image-tag.mjs",
     "check:docs-image-tag-sync": "node scripts/sync-docs-image-tags.mjs --self-test",