📚 Fumadocs Resync + Drift Gate
Playground · branch chore/fumadocs-resync · 2026-06-04 · fixes stale orchestkit.yonyon.ai/docs/reference/*
86
Reference pages resynced
Symptom: /docs/reference/skills/audit-full showed Opus 4.6/4.7 while the source skill
said Opus 4.8 — 10 days stale. Root cause: reference mdx is generated from src/ but the
generated artifact is committed and served as-is; nobody re-committed it, and no CI gate caught the rot.
Why the site went stale (the pipeline break)
src/skills/*/SKILL.md ──(scripts/build-docs.sh, part of `npm run build`)──> docs/site/content/docs/reference/*.mdx
Local dev npm run build → regenerates mdx → but discarded (treated as "drift")
CI validate npm run build → regenerates mdx → validated in memory, never committed, NO drift gate
Vercel deploy next build only — never runs build-docs.sh → serves COMMITTED mdx
Published site serves mdx from git → STALE whenever src/ changed since last mdx commit
The fix — mirrors the existing plugins/ drift gate
| Part | Change | Effect |
|---|
| Immediate | Regenerate + commit 86 reference + 2 category mdx | Live site updates on next deploy (audit-full → Opus 4.8) |
| Systemic | Add drift gate to .github/workflows/docs.yml validate job | CI fails if committed mdx ≠ regenerated — can't silently rot again |
.github/workflows/docs.yml — validate job
- run: npm run build # regenerates reference mdx from src/
+ - name: Check generated docs drift (reference mdx must match src/)
+ run: |
+ if ! git diff --quiet -- docs/site/content/docs/reference docs/site/content/docs/skills/by-category; then
+ echo "::error::Docs drift detected — generated reference mdx is stale."; exit 1
+ fi
audit-full — before / after
docs/site/content/docs/reference/skills/audit-full.mdx
- leveraging **Opus 4.6** 1M context … On Opus 4.7, prefers xhigh …
+ leveraging Opus 4.8 1M context … Opus 4.8 defaults to high effort; bump to xhigh …
Why a gate, not Vercel-side generation? Vercel's ignoreCommand skips deploys when
docs/site is unchanged. A deploy-time generator wouldn't fire on a pure src/skills
change. Committing the mdx (gated) guarantees docs/site changes whenever a skill does → Vercel always deploys. Same model as the plugins/ drift gate already in CI.