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

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 "Settings", rg "Config", rg "os.environ", rg "OPENAI_").
   • 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.

3. Doc-first pass: review existing pages

   • Walk each relevant page under docs/ (excluding docs/ja, docs/ko, and docs/zh).
   • Identify missing mentions of important, supported options (opt-in flags, env vars), customization points, or new features from src/agents/ and examples/.
   • Propose additions where users would reasonably expect to find them on that page.