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, technology-independent architecture for rebuilding WebUI. Update it in the same change only when modifying:

• Subsystem responsibilities and data flow
• Build-time versus request-time ownership
• Cross-layer design invariants and compatibility boundaries
• Technology choices essential to reproducing the system

Revise existing explanations instead of appending incident histories. Exact schemas, signatures, error codes, SSR marker layouts, metadata tuples, and regression details belong in the defining source and tests; preserve focused subsystem and cross-language contracts in internal specs/ references. A field or API change alone is not an architectural change. If an architectural claim and the code disagree, reconcile them.

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 system-level architecture in DESIGN.md, subsystem technical contracts in specs/, and implementation invariants and local rationale near code and tests.

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).