gen-docs

# Gen Docs ## Overview This repository maintains bilingual user documentation under `docs/`. `docs/en/` and `docs/zh/` are mirrored pairs for most pages; update both in the same change. **Changelog is the exception** — English is the source, and Chinese is translated from English. Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience. For a **full pre-release audit** of all pages (detecting hallucinations and coverage gaps), use the `audit-docs` skill instead. ## Prerequisites This skill depends on the following being in place. If any are missing, stop and report to the user before continuing: - `docs/` directory with `docs/zh/`, `docs/en/`, and `docs/.vitepress/config.ts` set up (VitePress site). - `docs/AGENTS.md` style guide — defines source-of-truth rules, terminology table, typography, and writing style. - `docs/scripts/sync-changelog.mjs` — auto-syncs root `CHANGELOG.md` to `docs/en/release-notes/changelog.md`. - `translate-docs` skill in `.agents/skills/` — handles bilingual synchronization. ## Workflow 1. **Inspect changes** - `git log main..HEAD --oneline` — commits on the current branch - `git diff main..HEAD --stat` — file-level scope - `ls .changeset/*.md` (excluding `README.md`) — pending changeset entries - Read `CHANGELOG.md` and any subpackage `packages/*/CHANGELOG.md` for already-recorded entries. 2. **Understand user-facing impact** For each change, read the actual implementation when needed; **do not infer behavior from commit messages or PR titles alone**. Skip: - Internal refactors with no externally visible behavior change - Tests, CI, type-only changes - Tooling / build-system changes that do not change how users invoke the CLI If after the scan you conclude there is no user-facing impact, say so and stop. 3. **Sync English changelog** Run: ```bash node docs/scripts/sync-changelog.mjs ``` This updates `docs/en/release-notes/changelog.md` from the root `CHANGELOG.md`. Never edit the docs changelog by hand. 4. **Update user docs** Following the rules in `docs/AGENTS.md`, edit the affected pages in whichever locale you are working in, then sync the mirror. Match terminology with the term table in `docs/AGENTS.md` and the existing wording in surrounding pages. Cover all relevant sections: - Guides (getting-started, use cases, interaction, sessions, IDE integration) - Customization (skills, agents, MCP, hooks, plugins, etc.) - Configuration (config files, env vars, providers, data locations) - Reference (CLI subcommands, slash commands, keyboard shortcuts) - Release notes (`docs/zh/release-notes/breaking-changes.md` if a breaking change is involved) 5. **Sync bilingual content** Invoke the `translate-docs` skill. It will: - Sync updated non-changelog pages between `docs/en/` and `docs/zh/` - Translate the English changelog → Chinese under `docs/zh/release-notes/changelog.md` ## Rules and conventions - **Locale sync**: Non-changelog pages stay mirrored between `docs/en/` and `docs/zh/`. Changelog flows English → Chinese. - **Terminology**: Use the term table in `docs/AGENTS.md` exactly. Do not invent new translations or use synonyms. - **Scope discipline**: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs. - **Public examples**: Never write real internal endpoints, key names, account names, or service names into docs. Use neutral placeholders such as `https://api.example.com/v1`, `https://registry.example.com/v1/models/api.json`, `example.test`, and `YOUR_API_KEY`. - **Breaking changes**: If any change is breaking, also update `docs/en/release-notes/breaking-changes.md` (under `## Unreleased`) with `**Affected**` + `**Migration**` subsections, and mirror it in `docs/zh/release-notes/breaking-changes.md`. - **Do not edit auto-synced files**: `docs/en/release-notes/changelog.md` is regenerated by the sync script; any manual edit will be overwritten. ## Common mistakes - Describing what code changed instead of what the user can now do (or can no longer do). - Adding a new section heading per feature instead of weaving the change into existing prose. - Updating only one locale and leaving its mirror stale. - Editing only the mirror to fix wording that should be corrected in the locale you changed first. - Inventing new terminology that drifts from the `docs/AGENTS.md` term table. - Using real internal values in examples instead of neutral `example` placeholders.