Docs Sync

Docs Synchronization Workflow

Use this skill whenever a change touches user-visible behavior, APIs, or contracts.

When to update docs

DESIGN.md rules

DESIGN.md is the living technical specification. Update it in the same commit when modifying:

• Public APIs or type signatures
• Protocol fields or fragment types
• Behavioral contracts (matching semantics, expression evaluation, state resolution)
• Error variants
• SSR marker formats
• Metadata object format

If DESIGN.md and the code disagree, that is a bug - fix both.

docs/ rules

Update docs/ in the same commit when the change is user-visible:

• CLI usage or flags changed
• Template syntax or rendering output changed
• Integration behavior that external developers depend on
• New features or removed features

Public API boundary

Developer documentation (docs/, crate/package READMEs, and docs/ai.md) documents only supported public APIs and externally observable contracts. Every addition must map to at least one public entry point:

• an exported Rust, Node, WASM, FFI, or package API;
• a CLI command, flag, configuration field, or supported identifier;
• supported template/component authoring syntax;
• a documented protocol or integration contract.

Do not document private or pub(crate) items, internal callbacks, intermediate representations, cache algorithms, implementation sequencing, regression-test details, or dependency-specific workarounds in developer docs. Put architecture and implementation invariants in DESIGN.md; keep local rationale in succinct ordinary source comments.

Rust /// documentation comments are for exported public APIs only. Use // sparingly for non-public implementation rationale. Before finishing, audit the documentation diff against the public exports and remove text that has no public entry point.

Do not update user-facing docs for internal implementation details, regression tests, refactors, or bug fixes that only restore already-documented behavior. Every addition must help developers author, configure, debug, or integrate a WebUI application. Do not add release-note-style implementation observations to reference docs.

Keep protocol internals out of general user docs. The docs/ai.md file is the single-page AI reference and should be kept in sync with all other docs.

docs/ai.md is authoring-first by design. Keep deep reference material (full CLI flag tables, error-code lists, per-language integration snippets) in its canonical page and link to it from docs/ai.md rather than duplicating it there.

ai/SKILL.md is only the stable loader. Update docs/ai.md for authoring changes, not the loader or the generated packages/webui/ai.md. The package prepack step refreshes the generated reference; ordinary builds do not write it.

Validation

cd docs && pnpm build

This catches broken links, VitePress syntax errors (unescaped {{ outside code blocks), and missing pages. Run it when docs are changed.

Style rules for docs

• No emdashes (-). Use hyphens (-).
• Escape {{ outside fenced code blocks with <code v-pre>{{expr}}</code>.
• Use correct CLI flag names (check crates/webui-cli/src/commands/).
• Verify SSR markers match source code (crates/webui-handler/src/plugin/webui.rs).