docs:check — the documentation's checkable claims, against the code

"Update the docs before a deploy" is a step that gets skipped at two in the morning, and its absence is
invisible. Every piece of drift found today was mechanical — a count, a route name, a process list — so it is
checkable, and a check that exits non-zero cannot be quietly not done.

It found two things on its first run, both wrong for over a week:

  platform/CLAUDE.md    "27 entries as of 2026-08-13"    the registry holds 18
  officer-dev/CLAUDE.md "Officer is twenty PM2 entries"  there are 13

The second was worse than a wrong number. It listed eleven processes that do not run here — vault, slskd,
headscale, transmission, invoiceshelf, wallet, photos, jellyfin, gitea, music, vnc — while omitting six that
do, and named two mybiblepal entries as sharing the daemon when nothing does. Accurate on 2026-08-07, and
nobody re-derives a list of processes while editing the sentence around it. Both are corrected, with what
they used to claim recorded, because the interesting part is how a maintained list decays rather than that it
did.

Three checks: the permission registry count, the PM2 entry count, and every settings route Spotlight offers
resolving to a section some screen declares. That last one is the class the counts cannot catch — a name, not
a number — and it is the drift that shipped a dead link to /settings/users.

THE RULE FOR ADDING ONE, written into the file: a check compares a documented claim against a value DERIVED
AT RUN TIME, never against a second hard-coded copy. A check with the answer written into it is one more
place to drift, and it drifts in the same edit that misses the doc.

What it deliberately cannot do is read prose and judge it. It looks only at claims with a machine-checkable
counterpart — a small fraction of the documentation, and the fraction that rots fastest.

The settings check parses source rather than importing it, and says why: those sections are object literals
inside components, so importing them drags React and a DOM into a CLI.

`skipped:` lines are printed rather than swallowed — a machine without pm2 cannot check that count, and
saying so beats reporting a pass it did not perform.

Recorded as required before tagging in CLAUDE.md, and in prompts/deploy-commander.md as explicitly NOT the
rollout agent's job: it executes a plan, and a prose edit between two hosts is not that.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

prompts/deploy-commander.md

@@ -96,6 +96,21 @@ load-bearing. A missing report is a missing record; a missing lock is a second d
 It sits under `data/` rather than in the repository so a `git pull` can never clobber it, and so a fresh
 clone does not arrive believing it has deployed nothing.
 
+## Before a release is tagged — not your job, but know it happened
+
+Whoever cuts a release runs `bun run docs:check` first and leaves it green. It compares documented claims
+against values derived at run time — how many permissions the registry holds, how many PM2 entries Officer
+is, whether every settings route Spotlight offers actually exists — and exits non-zero on drift.
+
+It exists because "update the docs before a deploy" is a step that gets skipped at two in the morning and
+whose absence is invisible. On 2026-08-22 it found, immediately: `platform/CLAUDE.md` claiming 27 permission
+entries against a registry holding 18, and the workspace `CLAUDE.md` claiming twenty PM2 entries against
+thirteen, listing eleven processes that do not run here while omitting six that do.
+
+**You do not run it and you do not fix documentation.** You execute a plan and report. It is here so that a
+report saying "the docs are stale" has somewhere to point, and so nobody adds doc-fixing to a rollout, where
+it would put a prose edit between two hosts.
+
 ## The release
 
 The tag names the version. The commit it points at carries the rest: