doc-sync

name	doc-sync
description	Sync docs and skills so they never drift from the code. Use before opening or updating a PR, or when a change touches a command, path, convention, or the skill set a doc or skill documents.

Doc Sync

A change ships with its docs or it ships drift. This is the procedure to catch drift across every hand-authored surface before the PR goes up. AGENTS.md makes the sync mandatory; this makes it checkable.

Surfaces

Hand-authored, keep these in step with the code:

Surface	Documents	Drifts when
web/next/content/docs/**.mdx	concepts and how-to (getting-started, deployment, manage, resources)	a feature, convention, API, command, script, or env var it describes changes
web/next/docs.config.ts	the docs nav and page registry, the single source the sidebar, meta.json, and MDX frontmatter all derive from	a doc page is added, removed, renamed, or re-slugged
README.md	top-level story: stack, structure, quick start, scripts, deployment	the stack, setup, scripts, or pitch changes
.agents/skills/<name>/SKILL.md	one task procedure each (canonical; .claude and .github symlink in)	a command, path, convention, or tooling a skill encodes changes, or a skill is added or removed
AGENTS.md (CLAUDE.md symlinks in)	the rules and the skills catalog table	a rule changes, or the skill set changes

Generated, never hand-edit (they regenerate from the surfaces above): content/docs/meta.json (git-ignored), the /llms.txt and /llms-full.txt routes, and the fumadocs search index.

Procedure

1. Scope the change

List what the diff touched: paths, commands, script names, env vars, conventions, tooling, and whether the skill set changed. Start from git diff --stat and the code diff.

2. Hunt drift

Grep every surface for each changed path, command, or symbol. Every hit is a candidate:

rg -n "<changed-path-or-command>" web/next/content/docs README.md AGENTS.md .agents/skills web/next/docs.config.ts

3. Sync, coupled surfaces included

Update each hit in the same change. Two couplings are easy to miss:

• Add or remove a skill touches three places: the AGENTS.md skills table, the resources/ai-skills.mdx catalog row, and that file's "N skills" counts.
• Add, remove, or rename a doc page touches web/next/docs.config.ts, not the .mdx alone.

4. Verify with the repo's own drift gate

bun .github/scripts/docs.ts --strict

This is the fast gate (seconds): it exits non-zero on any .mdx missing from docs.config.ts, any config entry with no file, or frontmatter drifted from docs.config.ts. To fix a failure, run it without --strict to rewrite the managed frontmatter and scaffold missing pages, then commit. Before the PR, also run cd web/next && bun run build once: it reruns this check inside the full build and additionally catches type errors and rebuilds the search index. Done when the strict gate passes AND a fresh rg for every removed or renamed path, command, and skill name finds zero stale mentions across the surfaces.

Notes

• Skills are symlinked: .agents/skills is canonical, edit once.
• The /llms.txt and /llms-full.txt routes mirror the docs and regenerate at build, so fix the doc, never the route.