sync-docs

name	sync-docs
description	Sync docs site from docs/public/ source files. Diffs upstream markdown against React pages + i18n keys, identifies gaps, and updates the docs site. Trigger when docs/public/ is updated or user says "sync docs", "同步文档".

Sync Docs Site from docs/public/

Compare docs/public/*.md (canonical technical source) against the docs site React pages, identify content gaps, and update the docs site with distilled user-friendly content.

Relationship

docs/public/*.md        ← Canonical source (system-generated, detailed, technical)
       ↓ distill & simplify
docs site (React pages) ← User-facing (concise, accessible, NOT 1:1 copy)

The docs site does NOT need every detail — only distill what users need to know.

Execution Steps

Step 1 — Discover source files

ls docs/public/*.md

Build the mapping of source files → docs site pages:

Source	Page	i18n prefix
docs/public/architecture.md	src/web/pages/docs/architecture.tsx	docs.arch.*
docs/public/deploy-production.md	src/web/pages/docs/deploy-production.tsx	docs.production.*

If a source file has no corresponding page, note it as "needs new page" but do NOT auto-create — report to user first.

Step 2 — Diff each source against its page

For each source → page pair:

1. Read docs/public/<slug>.md — extract sections (H2 headings) and key content
2. Read src/web/pages/docs/<slug>.tsx — extract rendered sections from t() keys and code blocks
3. Read the corresponding docs.<prefix>.* keys from src/i18n/locales/en.json
4. Compare section-by-section:
   • New sections in source but missing from page
   • Updated content in source but stale in i18n keys (different wording, new details)
   • Removed sections in source that still exist in page
   • Code blocks changed (commands, diagrams, directory trees)

Step 3 — Report gaps

Output a table for each file:

## <slug>.md → <slug>.tsx

| Section | Status | Action Needed |
|---------|--------|---------------|
| Architecture | ✅ In sync | — |
| Requirements | ⚠️ Stale | Source added "min 2GB RAM", page still says 1GB |
| Quick Start | ❌ Missing | New section in source, not in page |

Step 4 — Apply updates

For each gap found:

1. Distill the new/changed content from the markdown into user-friendly text
2. Update src/i18n/locales/en.json with new/changed i18n keys
3. Update src/i18n/locales/zh.json with Chinese translations
4. Update the React page .tsx if structural changes are needed (new sections, reordered sections)
5. Do NOT copy markdown verbatim — simplify for the target audience

Step 5 — Verify

pnpm test:unit   # Ensure nothing broken

Report what was synced:

• Files updated
• i18n keys added/changed
• Sections added/updated/removed

Rules

• Always update both en.json and zh.json — missing keys cause raw key rendering
• Distill, don't copy — the source is technical, the page should be accessible
• Preserve page structure — use existing DocSection, CodeBlock, BulletItem, OpBlock helpers
• Code blocks are literal — shell commands and diagrams don't go through i18n
• Follow existing i18n key naming: docs.<prefix>.<section>.<key>