Docs Sync

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

• 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; use git show main:<path> or git worktree add when needed.

• 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.

• 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.

• 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.

• 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.

• Produce a Docs Sync Report and ask for approval
• Provide a clear report with evidence, suggested doc locations, and proposed edits.
• Ask the user whether to proceed with doc updates.

• 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.
• Place any code snippets under examples/docs/<doc-filename>/ so the directory name matches the target doc file, mirroring existing patterns.
• Verify doc code snippets build successfully with 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