docs/public/md/*.md are committed copies of docs/pages/*.mdx, kept in the repo "so agents can curl them" (docs/scripts/build-md.sh). The Docs workflow regenerates them on every build via the prebuild hook before deploying, so the published site is always current — but the regenerated files are never committed back, and nothing verifies the committed copies. Staying in sync relies on each author remembering to rerun build-md.sh and commit.

Predictably, they drift: on current main a fresh build-md.sh run dirties eight mirrors (extend/acme-example, extend/apps, operate/slack-etl, reference/tool-directory, reference/configuration, secrets/environment, secrets/onepassword, what-is-centaur). For example, secrets/onepassword.md still tells readers to exec into deploy/centaur-centaur-api, which the mdx long since corrected to deploy/centaur-centaur-api-rs. Agents reading raw md from the repo get outdated instructions while the website looks fine — which is why nobody notices.

Proposal: add a drift check to the Docs workflow (it already triggers on docs/** for PRs and main) — run build-md.sh, fail on git diff --exit-code -- public/md with a rerun-and-commit message. The script is a plain cp loop, so the check costs nothing. Resync the eight stale mirrors together with the check so it starts green.

(#996 mentioned this staleness in passing; this issue tracks the resync + verification specifically.)