# 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:

```text
$& $` $'
../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](../../../contributing/examples.md). 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](testing-and-quality-checks.md) and [source-bound browser evidence](worktrees-and-browser-verification.md) apply to documentation/tooling changes too. [Issue tracker rules](../../../agents/issue-tracker.md) govern canonical decisions, roadmap reconciliation and pending-merge closure.