docs-sync

name	docs-sync
description	Keep user-facing docs and DESIGN specification aligned with behavior and API changes.

Docs Synchronization Workflow

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

When to update docs

What changed	Update
CLI flags or commands	docs/guide/cli/index.md + docs/ai/SKILL.md (Build and run section)
Template syntax or directives	docs/guide/concepts/directives/ + docs/ai/SKILL.md
Component authoring model	docs/guide/concepts/interactivity.md + docs/ai/SKILL.md
Hydration markers or mechanism	docs/guide/concepts/hydration.md + DESIGN.md (WebUI Framework Plugin)
Routing behavior	docs/guide/concepts/routing.md + docs/ai/SKILL.md
State management or path resolution	docs/guide/concepts/state-management/index.md
Handler API (Rust, Node, FFI)	docs/guide/concepts/handlers/ + docs/guide/integrations.md
Protocol fields or fragment types	DESIGN.md (Protocol Specification)
Plugin system (parser or handler)	docs/guide/concepts/plugins/index.md + DESIGN.md
Performance characteristics	docs/guide/concepts/performance.md
Public API (Rust crate, npm package)	DESIGN.md + relevant handler/integration docs
Error variants or error messages	DESIGN.md
@microsoft/webui-framework decorators or API	docs/guide/concepts/interactivity.md + docs/ai/SKILL.md + packages/webui-framework/README.md
@microsoft/webui-router behavior	docs/guide/concepts/routing.md + packages/webui-router/README.md

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/SKILL.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/SKILL.md file is the single-page AI reference and should be kept in sync with all other docs.

docs/ai/SKILL.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/SKILL.md rather than duplicating it there.

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