Doc Sync

Docs/
├── README.md                      # Index: Quick Start + categorized tables
├── _toc.yaml                      # TOC: pages, sections, source mappings
├── _meta/
│   ├── GENERATION.md              # commit, branch, timestamp
│   └── SUMMARY.md                 # coverage and validation report
├── core/                          # Architecture, auth, data model, principles
├── api/                           # API_REFERENCE.md and per-surface API docs
├── features/                      # One page per major feature or integration
├── operations/                    # Runbooks, monitoring, deploy, secrets
├── design-system/                 # UI/UX standards (only for UI projects)
├── frontend/                      # Frontend-specific guides (only when applicable)
├── plans/                         # Active design / planning docs (manual)
└── archive/                       # Historical docs (manual)

Omit folders that have no relevant pages. Add other folders only when the repo demands it (e.g., desktop-agent/, branding/).

Three Modes

The skill operates in one of three modes. Detect the mode from the user's argument, the state of Docs/, and the recency of generation metadata.

If the argument is empty: pick init when no Docs/_toc.yaml, otherwise update.

References (read before writing)

Load these reference files before generating or updating any page. They contain the rules you must follow:

• references/page-template.md — required page structure, markers, headings
• references/citation-policy.md — evidence rules, source URL format, line numbers
• references/mermaid-policy.md — diagram syntax rules and validation
• references/toc-schema.md — _toc.yaml schema and ID conventions
• references/doc-categories.md — when to create which page type
• references/incremental-update.md — safe AUTOGEN replacement rules
• references/readme-template.md — Docs/README.md index structure

Page templates live in templates/:

• overview.md, architecture.md, api-reference.md, feature.md, database-schema.md, module.md, data-flow.md, runbook.md, getting-started.md, configuration.md, glossary.md, _toc.yaml.template

Each template defines required sections and minimum content expectations. Do not skip required sections; mark them _TBD_ with a reason if no source exists.

Mode: init (full generation)

Step 1: Scan the repository

1. Capture git metadata. Run in parallel:
   • git rev-parse HEAD (commit hash)
   • git rev-parse --abbrev-ref HEAD (branch)
   • git config --get remote.origin.url (repo URL → derive repo_base_url)
2. Use Glob to enumerate the repo:
   • Top-level directories
   • Entry points: **/main.{ts,js,py,go,rs}, **/index.{ts,js,tsx}, **/cmd/**/main.go
   • Config: package.json, pyproject.toml, Cargo.toml, go.mod, Dockerfile*, docker-compose*, *.tf, .env.example
   • Build/CI: Makefile, .github/workflows/*, turbo.json, nx.json
   • Existing docs: README*, **/*.md outside Docs/ and node_modules/
3. Read README.md, package.json (or equivalent), and 2-3 entry-point files to understand purpose, stack, and structure.
4. Identify language(s), frameworks, key services, and module boundaries.

Step 2: Design the TOC

1. Read references/toc-schema.md and references/doc-categories.md.

2. Pick page categories that match the project. Use the page-count guideline:

   Project size	Files	Pages
   Small	< 10	3-5
   Medium	10-50	5-8
   Large	50-200	8-14
   Very Large	> 200	12-20

3. Group pages into folders (core/, features/, operations/, etc.) per the folder layout above.

4. For each page, decide:

   • id ({repo}_{NN}_{slug}), title, filename, description
   • source_files (page-level glob patterns)
   • sections[] with id, title, autogen: true, optional section-level source_files, diagrams_needed, diagram_types
   • related_pages[] for cross-linking

5. Write Docs/_toc.yaml using templates/_toc.yaml.template as a starting point. Replace placeholders with real values.

Step 3: Generate pages

For each page in _toc.yaml:

1. Resolve source_files (page-level + section-level) using Glob.
2. Read each resolved file with Read (no line-number guessing — use the actual numbers Read returns).
3. Pick the matching template from templates/ based on the page category.
4. Write the page to Docs/{folder}/{filename} following references/page-template.md:
   • <!-- PAGE_ID: {id} --> at the very top
   • Collapsible "Relevant source files" block listing inputs with line ranges
   • # {title} H1
   • > **Related Pages**: line linking to related_pages
   • One AUTOGEN block per section, with H2 heading, content, inline citations, and end-of-section Sources: line
   • --- separator between sections
5. Apply citation rules from references/citation-policy.md:
   • Inline citations wrapped in parentheses, before the period
   • End-of-section Sources: summary
   • Use real line numbers from Read output; never invent
6. Generate Mermaid diagrams per references/mermaid-policy.md when diagrams_needed: true. Use graph TD, quote all node text, no special chars in subgraph names.

For large repos, generate pages in parallel by spawning explorer subagents per page. Each subagent receives: the page entry from TOC, the resolved source files, and the template path. Wait for all to complete before validation.

Step 4: Generate the README index

Write Docs/README.md using references/readme-template.md. Include:

• A "Latest Updates" callout pulled from the most recent CHANGELOG.md entries
• A Quick Start table mapping common goals to entry pages
• One categorized table per folder, listing every generated page with its description from _toc.yaml
• A "Related Resources" section linking to root README.md, agents.md, and CLAUDE.md if they exist

Step 5: Write metadata

Write Docs/_meta/GENERATION.md:

# Generation Metadata

- **Commit:** `{hash}`
- **Branch:** `{branch}`
- **Generated:** {ISO timestamp}
- **Mode:** init
- **Pages generated:** {count}
- **Sections generated:** {count}

Step 6: Validate

Run validation in this order:

1. Structure validation (model-driven, no script needed):
   • Every page has exactly one PAGE_ID marker matching the TOC
   • Every autogen: true section has matched BEGIN:AUTOGEN / END:AUTOGEN markers with the correct ID
   • No orphaned, duplicated, or extra markers
   • Every internal link [text](path) points to a file that exists
2. Mermaid validation:
   • If mmdc is on PATH (which mmdc), extract each ```mermaid block and validate. If unavailable, skip with a note.
   • For each invalid block, attempt at most 3 fixes per block using the rules in references/mermaid-policy.md. If still invalid, comment the block out and add a <!-- TODO: invalid mermaid --> marker.
3. Coverage check:
   • List source files referenced by _toc.yaml patterns vs. files actually cited in pages
   • List uncited public APIs (exports, route handlers, CLI commands)

Step 7: Write the SUMMARY report

Write Docs/_meta/SUMMARY.md per references/incremental-update.md (Summary section). Include: pages generated vs. expected, citations per page, diagrams per page, validation errors, uncovered files.

Mode: update (incremental)

Step 1: Detect changes

1. Read the prior commit from Docs/_meta/GENERATION.md (base_commit).
2. Get current commit: git rev-parse HEAD (target_commit).
3. List changed files: git diff --name-status {base_commit}..{target_commit} (added / modified / deleted / renamed).
4. Read Docs/_toc.yaml and resolve every page's source_files glob.
5. Compute the affected set: pages whose resolved files intersect changed files.

Step 2: Detect TOC drift

For every changed file that does NOT match any TOC source pattern:

• If it's a CI/CD/config/docs file, ignore.
• If it's substantive source code, decide whether to add a section to an existing page or create a new page. Update _toc.yaml accordingly.

Step 3: Regenerate affected sections only

For each affected page:

1. Read the existing page file.
2. For each affected section (only those whose source_files intersect the changed files):
   • Re-read source files with Read to get current line numbers
   • Use Edit (NOT Write) to replace ONLY the content between <!-- BEGIN:AUTOGEN {section_id} --> and <!-- END:AUTOGEN {section_id} -->
   • Preserve everything outside the markers verbatim, including manual notes between AUTOGEN blocks
3. Update the "Relevant source files" block at the top to reflect new line ranges only for files that changed.

For each new TOC page: generate as in init Step 3.

For each deleted source file with no remaining coverage:

• If a section's source_files is now empty, remove the AUTOGEN block from the page and delete the section from _toc.yaml.
• If a page has no remaining sections, delete the page file and remove from _toc.yaml.

Step 4: Update README and metadata

1. Update Docs/README.md only if pages were added, removed, or renamed.
2. Rewrite Docs/_meta/GENERATION.md with the new commit, timestamp, and mode: update.
3. Update the "Latest Updates" callout in Docs/README.md from new CHANGELOG.md entries since base_commit.

Step 5: Validate

Run the same validation sequence as init Step 6, scoped to changed files where possible.

Step 6: Write the SUMMARY report

Write Docs/_meta/SUMMARY.md listing: commit range, pages updated, sections regenerated, sections added, sections removed, validation results.

Mode: audit (no rewrites)

Use the legacy lightweight workflow. Do not rewrite anything.

Step 1: Inventory

• Glob Docs/**/*.md and any **/*.md outside Docs/.
• Categorize: API, setup, architecture, user, changelog.

Step 2: Cross-reference

For each doc:

• Stale references (functions, files, endpoints that no longer exist) — Grep the codebase for each named symbol
• Incorrect examples (signatures changed)
• Broken internal links (file paths that no longer resolve)
• Stale version references vs package.json / lockfiles
• Missing docs for new public APIs / endpoints / config

Step 3: Report

Write the audit report to stdout (not to a file unless asked). Format:

# Documentation Audit

## Summary
- Files scanned: N
- Issues: N (high: X, medium: Y, low: Z)

## Findings
[HIGH] Docs/api/API_REFERENCE.md:142 — references removed endpoint POST /v1/foo
[MED]  Docs/core/AUTHENTICATION.md — example uses old `getSession()` signature
[LOW]  Docs/README.md — internal link to features/old-feature.md (file does not exist)

## Missing Documentation
[NEEDS DOCS] src/api/routes/billing.ts — 8 routes with no doc page
[NEEDS DOCS] env var STRIPE_WEBHOOK_SECRET — referenced in code, not in docs

## Recommendations
1. Run `/doc-sync update` to regenerate stale sections.
2. Add a feature page for billing.

Subagent usage

For init mode on medium/large repos, fan out page generation to explorer subagents in parallel. Each subagent prompt must include:

• The page's TOC entry (id, title, sections, source_files, diagrams_needed)
• Absolute path of the matching template
• Absolute paths of the reference files (page-template, citation-policy, mermaid-policy)
• The git ref_commit_hash and repo_base_url for citations
• An explicit instruction: write to Docs/{folder}/{filename} and return only "DONE: {filename}" or an error

Wait for all to complete, then run validation in the main session. Never run validation inside a subagent — it must see the whole output set.

For update mode, single-page jobs are usually fine without subagents. Spawn subagents only if more than 5 pages are affected.

Enforcement rules

• NEVER invent line numbers, file paths, function names, or behavior. If a claim has no source, write _TBD_ with a one-line reason.
• NEVER modify content outside BEGIN:AUTOGEN / END:AUTOGEN markers in update mode.
• NEVER skip the AUTOGEN markers — they are the contract that makes incremental updates safe.
• NEVER write to a path outside Docs/ (the legacy README at the repo root is left alone unless the user asks).
• ALWAYS use graph TD for flowcharts, quote all Mermaid node text, and validate diagrams when mmdc is available.
• ALWAYS update Docs/_meta/GENERATION.md after a successful run so the next update knows the base commit.
• ALWAYS keep Docs/_toc.yaml and Docs/README.md in sync — every TOC page must appear in the README index, and every README link must point to a TOC-tracked file.

Final checklist before reporting completion

• Docs/_toc.yaml valid (unique IDs, kebab-case slugs, every page has ≥ 1 source file)
• Every page has PAGE_ID and matched AUTOGEN markers per references/page-template.md
• Every page has at least: 6 H2 sections, 8 substantive bullets across sections, 2 tables when applicable, 2 code/file snippets when sources exist, 8+ source paths in "Relevant source files"
• Every diagram block parses (or is commented out with TODO)
• Docs/README.md lists every generated page
• Docs/_meta/GENERATION.md reflects the current commit
• Docs/_meta/SUMMARY.md written with coverage and validation results