Source drift: reference pages

The reference pages under /reference/ are generated from the service repositories by tools/docs-engine/generate.mjs and compared against the files on disk by the gate (--check). When the source moves (a new route, a renamed flag, a new error code) and the page does not, the gate fails:

node tools/docs-engine/generate.mjs --check
drift src/content/docs/reference/api.md: the file does not match the generated text
# exit 1

That is the correct failure. It means a source changed and the page is now stale, not that the generator is broken. The fix is to regenerate from a clean source, then re-run the gate until it is green.

Find the drift

node tools/docs-engine/generate.mjs --check      # list every drifting page
node tools/docs-engine/generate.mjs --json       # machine report: source + reason per page

Each contract page that drifts reports the file ... does not match the generated text, or does not exist if the page was removed. A page listed as skip is not drift: its source repository is absent in this checkout (a laptop without the sibling repo). The scheduled cycle runs with --require-sources, so an absent source is a failure there rather than a silent skip.

Regenerate from a clean export

The generator reads the sources named in tools/docs-engine/sources.json. Those paths resolve against this repository’s root by default, which means a shared working tree with uncommitted changes would bake someone’s dirty state into the published page. Regenerate only from a clean git archive export:

# one export per source repository, into throwaway directories
git -C /srv/acumen-vnext archive origin/main | tar -x -C /tmp/dpu-acumen-main
git -C /srv/cli           archive origin/main | tar -x -C /tmp/dpu-cli
# point the generator at the clean exports, never at a live checkout
DOCS_ENGINE_REPO_ACUMEN=/tmp/dpu-acumen-main \
DOCS_ENGINE_REPO_CLI=/tmp/dpu-cli \
  node tools/docs-engine/generate.mjs --write

--write overwrites each contract page and prints write <target> per page, or skip <target>: <reason> for an absent source. It never writes the changelog’s content as a contract (that page is a feed, excluded from the gate) and never copies a credential value (the renderer redacts a value that looks like one).

Verify the fix

node tools/docs-engine/generate.mjs --check      # must exit 0
bash tools/ci.sh --skip-deploy                   # the full gate, end to end

The gate must exit 0 with the regenerated pages committed. If --check still reports drift after --write, the source export is stale or the wrong revision: re-pull the export from the source’s origin/main and regenerate again.

Safety boundary

• Never regenerate from a working tree with uncommitted changes. A clean git archive origin/main is the only safe input. The DOCS-PUBLISH-UNBLOCK card (2026-11-04) found drift caused by a shared acumen-vnext checkout that held dirty internal/store/*.go; publishing reference pages from it would have baked uncommitted state into the live site, which is worse than serving a stale page.
• Never hand-edit a generated page to clear the gate. The page is <!-- generated by tools/docs-engine/generate.mjs -->; an edit is overwritten on the next --write and hides the real gap. Fix the source or the generator.
• Do not deploy to clear reference drift. Regeneration is a source change committed through the gate; a content rollback would re-serve the stale page. Deploy only after the gate is green and the change is reviewed.
• Dated claims only. A page that asserts a contract version (for example contract 1.10.0) carries the date it was observed; the build itself proves the version once regenerated.