# Sync Docs > Keep the agent-facing manual under docs/ in sync with the implementation. Diff-driven from a committed commit baseline; makes conservative, minimal edits only where the code has actually changed user-facing behavior. Run on demand or as part of release prep. - Skill: `onevcat/sync-docs` (Agent Skill) - Install (CLI): `npx skillmds@latest add onevcat/sync-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/onevcat/sync-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: onevcat (https://skillmd.com/u/onevcat) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/onevcat/sync-docs --- # Sync Docs Keep the agent-facing documentation under `docs/` accurate as the implementation evolves. This skill is **diff-driven** (it only looks at source that changed since a committed baseline) and **deliberately conservative** (it makes the smallest edits needed to restore accuracy — it does not rewrite, restyle, or expand the docs). Read `docs/README.md` first for the doc set's structure and intent. The docs are written **for AI agents to read**, are plain Markdown, and are designed to be verifiable: each file lists `Keywords`/`Related`, and the `reference/` files name their source-of-truth. ## Guiding principle: be conservative The goal is to keep facts correct with **low churn**, not to perfect the prose. - **Default to leaving a doc unchanged.** Only edit when a documented fact is now demonstrably **wrong**, a documented feature was **removed**, or a clearly significant new user-facing feature/shortcut/setting was **added**. - **Make the smallest possible edit.** Fix the wrong cell/line; don't reflow tables, reorder sections, or reword surrounding prose. - **Tolerate a wide range.** Ignore internal refactors, renames, and code reshuffles that don't change user-facing behavior. Ignore stylistic/wording differences. Approximate phrasings ("roughly", "typically", "best-effort") are fine — don't tighten them just because you can. - **Don't grow the doc set casually.** Do not add new sections or new files unless a genuinely new top-level feature appeared. If a change is large (a new feature that needs a whole new component manual, or a structural overhaul), **do not do it silently** — describe it in the report and let the human decide. - **Keep "source of truth" pointers correct** if files move or are renamed. - Prefer touching **few files per run**. If you find yourself about to edit many files, stop and re-read this section — most of those are probably tolerable. ## Steps 1. **Read the baseline.** Open `docs/.sync-meta.json` and read the `last_synced_commit` field (the **last-synced commit** hash). 2. **Diff the implementation since the baseline.** List source files that changed: ```bash git diff --name-only ..HEAD -- \ supacode/ ProwlCLI/ Package.swift Resources/git-wt ``` If nothing relevant changed, report "Docs up to date as of ``." then go to step 6 (bump the baseline) and stop. 3. **Map changed source → docs to re-check.** Use this table; only open the docs whose source actually changed. (Most changes touch zero or one doc.) | Source that changed | Docs to re-check | |---------------------|------------------| | `supacode/App/AppShortcuts.swift`, `supacode/Commands/**` | `reference/keyboard-shortcuts.md` (+ shortcut mentions in the relevant `components/*.md`) | | `supacode/Features/Settings/Models/GlobalSettings.swift`, `RepositorySettings.swift`, `UserRepositorySettings.swift` | `reference/settings-fields.md`, `components/settings.md`, `components/custom-actions.md` | | `ProwlCLI/**`, `supacode/CLIService/**` | `components/cli.md` | | `supacode/Clients/CLIInstall/**` | `components/cli.md`, `components/settings.md` | | `supacode/Features/Repositories/**`, `supacode/Domain/Worktree*.swift`, `supacode/Domain/Repository*.swift`, `supacode/Clients/Git/**`, `Resources/git-wt` | `components/repositories-and-worktrees.md` | | `supacode/Features/Terminal/**`, `supacode/Infrastructure/Ghostty/**` | `components/terminal.md` | | `supacode/Features/Canvas/**` | `components/canvas.md` | | `supacode/Features/Shelf/**` | `components/shelf.md` | | `supacode/Features/CommandPalette/**` | `components/command-palette.md` | | `supacode/Features/ActiveAgents/**` | `components/active-agents.md` | | `supacode/Domain/AgentDetection/**`, `supacode/Infrastructure/AgentDetection/**` | `components/agent-detection.md` | | `supacode/Clients/Notifications/**`, `WorktreeTerminalState+Notifications.swift`, `supacode/Clients/Dock/**` | `components/notifications.md` | | `supacode/Features/DiffView/**` | `components/diff-view.md` | | `supacode/Clients/Github/**` | `components/github-pull-requests.md` | | `supacode/Clients/Updates/**`, `supacode/Features/Updates/**` | `components/updates.md` | | view-mode switching (`supacode/Features/App/**`, `ContentView.swift`) | `components/view-modes.md` | `overview.md`, `concepts.md`, and `README.md` only need touch-ups for the addition/removal of a **major** feature — leave them alone otherwise. 4. **Verify against the source of truth.** For each doc identified, check its falsifiable claims against the authoritative source — not against the diff summary — and apply minimal edits per the conservative rules above: | Claim type | Source of truth | |------------|-----------------| | Keyboard shortcuts (key + modifiers + command ID, remappability) | `supacode/App/AppShortcuts.swift`; menu wiring in `supacode/Commands/*.swift` | | Settings field names / types / defaults | `supacode/Features/Settings/Models/GlobalSettings.swift`, `RepositorySettings.swift` | | CLI commands / flags / ranges / error codes / JSON fields | `ProwlCLI/**` and `supacode/CLIService/**` (and, if the CLI is installed, `prowl --help` for confirmation) | | Feature behavior / entry points | the corresponding `supacode/Features/**` or `supacode/Clients/**` | When in doubt whether something is a real, user-facing change, **leave the doc as-is and flag it** in the report rather than editing. 5. **Check internal links if files moved.** If you renamed/added/removed any doc file, re-run a quick relative-link check so nothing in `docs/` is broken. 6. **Bump the baseline.** Set `last_synced_commit` (and `last_synced_date`, `note`) in `docs/.sync-meta.json` to the current `HEAD`. This file is **committed to git** so the baseline persists across sessions and machines — never leave it uncommitted. 7. **Report.** Output a short summary: ``` ## Docs Sync Baseline: → Source files changed in range: ### Updated - docs/ — ### Checked, left unchanged (tolerated) - — ### Needs human decision (not applied) - — ``` ## Committing - **Standalone run:** stage and commit only `docs/**` (which includes `docs/.sync-meta.json`); never `git add .`. If anything in `docs/` changed and you're not on `main`, open a PR targeting `onevcat/Prowl`. - **As part of release prep** (the `release` skill, on `main`): commit the doc + `docs/.sync-meta.json` changes as **their own commit before the version bump and tag** — e.g. `git commit -m "Sync docs for "`. Do **not** leave them staged/uncommitted: `release.sh` aborts on a dirty working tree, and the doc commit must already be on `main` so it becomes an ancestor of the tag and ships inside the release. Bump/tag happen after, never before. - Always bump and commit `docs/.sync-meta.json` even when no doc edits were needed, so the next run starts from a tight diff range. The baseline records the commit the docs were verified against (the current HEAD at run time) — for a release that is the code being shipped, captured before the later doc/bump/tag commits, which is correct (those commits touch no implementation files).