Sync Public Docs

Sync public docs (react-zmage)

Why this skill exists

The repo has four "outward-facing" documentation surfaces and only two of them are guarded automatically:

When core's public API changes, drift across these surfaces is silent — TS will flag a renamed type symbol but won't flag a stale default value, an outdated prop description in Props.tsx, or a removed prop still mentioned in README.md.

The cost of drift is real: README is what npm shows; llms.txt is what AI agents read; home/docs is what the live site renders. They can each go wrong independently.

When to invoke

Strong triggers (just do it):

• Any change to packages/core/src/types/global.ts, types/default.ts, or index.ts
• Any change to packages/core/package.json exports field, peerDependencies, or version
• Adding, renaming, or removing a prop on <Zmage>
• Changing a default value in defProp or defPreset
• Changing the static method surface of Zmage (e.g. adding a new Zmage.X)
• Changing what react-zmage/ssr exports
• The user says "sync docs", "propagate this", "update public docs", "同步文档", "准备发版"

Weak triggers (consider, then judge):

• Pure internal refactors that don't change public types or defaults — usually skip
• Documentation-only PRs that already touch one destination — still run steps 5–6 to verify the others didn't drift
• Tooling/build config changes — only if they alter exports, peerDeps, or what consumers see

The 6-step flow

These steps are deliberately separated so each one can be paused for human review. The reason for splitting "draft" from "write" is that drafts are cheap to throw away; writes touch many files and are expensive to revert.

Step 1 — Diagnose what changed

Read the diff. List every change to public API surface, grouped by category:

• Type symbols added/removed/renamed in packages/core/src/types/global.ts
• Default values changed in packages/core/src/types/default.ts (defProp, defPreset.desktop, defPreset.mobile)
• Runtime exports changed in packages/core/src/index.ts (default export, static methods, named exports)
• exports field / subpaths / peerDeps in packages/core/package.json

Use git diff against master (the default branch is master, not main). If the user is mid-refactor and the change is uncommitted, use the working tree.

If nothing on this list moved, stop here. Tell the user the change doesn't affect public surface, no sync needed.

Step 2 — Enumerate sync destinations

For each change, identify which destinations need updating. Use this map. Each cell = "yes" unless marked –.

Multi-language parity (hard rule, not optional)

Any prose change in home/src/docs/sections/*.tsx or any user-visible label in home/src/playground/ MUST land in all 7 home/src/i18n/*.ts files: en, de, es, fr, ja, ko, zh-CN. Divergent key sets break useT() lookups silently — there is no compiler error for a missing key. Untranslated entries may use the English source verbatim as a placeholder (better) or omit the value (worse, but acceptable temporarily) — but the key itself must exist in every file.

Verify before committing:

for lang in en de es fr ja ko zh-CN; do
  count=$(grep -cE "^[[:space:]]+'[^']+':" "packages/home/src/i18n/$lang.ts")
  echo "$lang: $count keys"
done

All 7 numbers must match. If they diverge, find the missing key with diff <(grep ... en.ts) <(grep ... <other>.ts) and add the placeholder.

Other edge cases

• llms-eval: if the change adds new public API, also add a contract assertion in packages/llms-eval/eval.test.mjs so future drift is caught.
• alias members on Zmage: source defines both Zmage.wrapper / Zmage.Wrapper and Zmage.browsing / Zmage.Browsing. Pick one casing per document and stay consistent within that document — mixed casing in the same file confuses readers. Cross-document, the recommended convention is PascalCase for the component-shaped wrapper (<Zmage.Wrapper>, since JSX wants PascalCase for components) and camelCase for the imperative method (Zmage.browsing()).

Step 3 — Draft the patches

Write out — in your reply, not yet on disk — the exact intended diff for each destination. This is the human review checkpoint: it's much cheaper to revise prose at this stage than to revise after files are written.

Keep drafts terse: file path + before/after snippet, not full file content. The user should be able to skim and approve in one read.

If a destination needs more than ~30 lines of prose, flag it as "needs careful writing" rather than rushing through it.