Maintain documentation and examples#

Repository Markdown is the source of prose. The site renders that prose and uses explicit navigation/reference data; the maintained sample site owns its actual interactions. Update the source once rather than copying an authoritative contract into multiple pages.

When behavior changes#

In the same change, review affected guides, exact reference, project status and examples. Public API/configuration/format changes require corresponding documentation. New limitations or removed behavior must be visible where readers encounter the workflow.

Use this review checklist:

• Can a new reader complete the supported journey with the documented prerequisites?
• Do code imports/commands exist at the tested revision and use supported entries?
• Do links, anchors, source paths and declared sample assets resolve?
• Do examples clearly separate observed behavior, fixture data and simulated UI?
• Does the contribution preserve one repository version and canonical decision links?

Author a page#

Use one meaningful H1 title, plain Markdown, descriptive links and fenced code with a language. Organize by reader task: Presentation, Examples and Docs; contributor guidance lives inside Docs. Guides explain tasks, reference states exact contracts, and examples link back to both.

Code examples preserve their literal contents, including replacement-like text and relative asset paths:

$& $` $'
../assets/example.svg

Keep Markdown readable on GitHub through relative repository links. Link substantial canonical integration/contributor prose rather than maintaining a competing copy. New site prose lives under docs/site/; update the site navigation when adding/moving a page.

Keep examples honest#

Reuse the scenario in maintained examples. Do not duplicate it in a documentation widget. Intentional buggy/fixed controls must stay usable and labelled. Prototype recording, evidence and drafts remain simulated/in-memory until real implementation changes that claim.

When documenting runnable APIs, execute snippets against supported built entries and assert an independently expected outcome. Avoid installation instructions assuming a release that does not exist. Keep generated output and screenshots out of tracked source unless intentionally maintained fixtures.

Check before handoff#

Use pnpm build:docs to build the artifact and pnpm dev:docs for the owned server; open documentation/index.html under its printed URL. After building, pnpm check:docs validates every exposed page's links, anchors, repository source targets and sample assets without external network checks. pnpm test:docs executes the authored first-report snippet, validates authored catalog selection, checks curated names against generated public exports, and exercises renderer/artifact regressions. Keep runnable snippets in the tested guide fences rather than copying them into parallel test examples.

These checks and desktop/mobile documentation journeys in pnpm test:pr-preview belong to the complete pnpm verify gate. Observe the final site through the owned T3 preview on desktop/mobile, including navigation, search, code and example links. Behavior/API/format changes require corresponding guide/reference/status/example updates and review of the checklist above in the same change.

Quality guidance and source-bound browser evidence apply to documentation/tooling changes too. Issue tracker rules govern canonical decisions, roadmap reconciliation and pending-merge closure.