Gen Docs

Overview

This repository maintains English-only user documentation under docs/.

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/.vitepress/config.ts set up (VitePress site).
• docs/AGENTS.md style guide — defines source-of-truth rules, terminology table, typography, and writing style.
• The sync-changelog skill — syncs apps/pythinker-code/CHANGELOG.md into docs/release-notes/changelog.md.

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 the changelog

   Run the sync-changelog skill. It curates apps/pythinker-code/CHANGELOG.md into docs/release-notes/changelog.md. Never edit the docs changelog by hand.

4. Update user docs

   Following the rules in docs/AGENTS.md, edit the affected pages under docs/. 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/release-notes/changelog.md, via the sync-changelog skill)

Rules and conventions

• Terminology: Use the term table in docs/AGENTS.md exactly. Do not invent 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, say so in the changeset and describe the migration there; the changelog carries it into docs/release-notes/changelog.md.
• Do not edit auto-synced files: docs/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.
• Inventing new terminology that drifts from the docs/AGENTS.md term table.
• Using real internal values in examples instead of neutral example placeholders.