Doc Sync

A change ships with its docs or it ships drift. This is the procedure that catches 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 each in step with the code:

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. The one hand-written part of those routes is the /llms-full.txt preamble, which lives in site.ts above.

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

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

• Adding or removing a skill touches the AGENTS.md skills table (generated, so run bun packages/scripts/src/skills-manager.ts) and the resources/ai-skills.mdx catalog row. A vendored one also touches that page's count of how many skills are vendored, and skills-lock.json when it is a stub pinned for integrity (agent-browser); one copied in full (portless) has no lock entry.
• Adding, removing, or renaming a doc page touches web/next/docs.config.ts, not the .mdx alone.

4. Verify with the repo's own drift gate

bun packages/scripts/src/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, so edit once.
• The /llms.txt and /llms-full.txt routes mirror the docs and regenerate at build, so fix the doc, never the route.