docs-sync

---
name: docs-sync
description: Analyze main branch implementation and configuration to find missing, incorrect, or outdated documentation in docs/. Use when asked to audit doc coverage, sync docs with code, or propose doc updates/structure changes. Only update English docs (docs/src/content/docs/**) and never touch translated docs under docs/src/content/docs/ja, ko, or zh. Provide a report and ask for approval before editing docs.
license: MIT
---

# Docs Sync

## Overview

Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.

## Workflow

1. Confirm scope and base branch
   - Identify the current branch and default branch (usually `main`).
   - Prefer analyzing the current branch to keep work aligned with in-flight changes.
   - If the current branch is not `main`, analyze only the diff vs `main` to scope doc updates.
   - Avoid switching branches if it would disrupt local changes. Prefer read-only inspection such as `git show main:<path>`. If a separate checkout is genuinely required, stop and obtain the explicit approval required by `AGENTS.md` before creating or switching a worktree.

2. Build a feature inventory from the selected scope
   - If on `main`: inventory the full surface area and review docs comprehensively.
   - If not on `main`: inventory only changes vs `main` (feature additions/changes/removals).
   - Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
   - Capture evidence for each item (file path + symbol/setting).
   - Use targeted search to find option types and feature flags (for example: `rg "Options"`, `rg "process.env"`, `rg "export"`).
   - When the topic involves OpenAI platform features, invoke `$openai-knowledge` to pull current details from the OpenAI Developer Docs MCP server instead of guessing, while treating the SDK source code as the source of truth when discrepancies appear.
   - For MCP SDK (`modelcontextprotocol/typescript-sdk`) or Vercel AI SDK (`@ai-sdk/*`) topics, optionally use Deepwiki MCP for quick lookups, and still treat the SDK source code as the source of truth.

3. Doc-first pass: review existing pages
   - Walk each relevant page under `docs/src/content/docs` (excluding `docs/src/content/docs/openai`).
   - Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from `packages/`.
   - Propose additions where users would reasonably expect to find them on that page.

4. Code-first pass: map features to docs
   - Review the current docs information architecture under `docs/src/content/docs`.
   - Determine the best page/section for each feature based on existing patterns and package boundaries.
   - Identify features that lack any doc page or have a page but no corresponding content.
   - Note when a structural adjustment would improve discoverability.

5. Detect gaps and inaccuracies
   - **Missing**: features/configs present in main but absent in docs.
   - **Incorrect/outdated**: names, defaults, or behaviors that diverge from main.
   - **Structural issues** (optional): pages overloaded, missing overviews, or mis-grouped topics.

6. Classify the proposed complete diff
   - Use the Documentation Change Verification Tiers in `AGENTS.md` as the single source of truth.
   - Classify the complete proposed diff by its highest applicable Editorial, Content, or Structural tier before editing.
   - Keep the tier-specific verification separate from the existing eligibility rules for `$implementation-final-review`, `$code-change-verification`, `$changeset-validation`, and `$pr-draft-summary`.

7. Produce a Docs Sync Report and ask for approval
   - Provide a clear report with evidence, suggested doc locations, and proposed edits.
   - State the proposed risk tier and its required focused verification.
   - Ask the user whether to proceed with doc updates.

8. If approved, apply changes (English only)
   - Edit only English docs in `docs/src/content/docs/**`.
   - Exclude `docs/src/content/docs/openai` from review and updates.
   - Do **not** edit `docs/src/content/docs/ja`, `docs/src/content/docs/ko`, or `docs/src/content/docs/zh`.
   - Keep changes aligned with the existing docs style and navigation.
   - Do not add TypeScript or TSX fenced blocks directly to MDX. Place every TypeScript or TSX snippet in a compilable source file under `examples/docs/<doc-area>/`, import it into MDX with `?raw`, and render that imported source using the existing docs pattern.
   - If code is not useful enough to maintain as a complete example, explain the behavior in prose instead of adding an unverified snippet.
   - Run the focused verification required by the highest applicable Documentation Change Verification Tier in `AGENTS.md`. When the complete diff changes a rendered TypeScript or TSX snippet source or its MDX import/rendering, run `pnpm -F docs-code build-check` and fix issues before handoff.

## Output format

Use this template when reporting findings:

Docs Sync Report

- Doc-first findings
  - Page + missing content → evidence + suggested insertion point
- Code-first gaps
  - Feature + evidence → suggested doc page/section (or missing page)
- Incorrect or outdated docs
  - Doc file + issue + correct info + evidence
- Structural suggestions (optional)
  - Proposed change + rationale
- Proposed edits
  - Doc file → concise change summary
- Questions for the user

## References

- `references/doc-coverage-checklist.md`