Documentation workflow

Source code has no comments (ADR 0002, docs/decisions/0002-no-comments-in-source.md), so every explanation lives in Markdown: on this site, or in the repository for decisions and research. Each layer below is enforced by a check, not by discipline.

Where docs live

What	Where	Appears at
Package guides and API	packages/<pkg>/docs/*.{md,mdx}	/packages/<pkg>/…
Package changelog	packages/<pkg>/CHANGELOG.md	/packages/<pkg>/changelog/
Runnable examples	packages/<pkg>/docs/examples/*.ts	Embedded in guide pages
User guide	apps/docs/src/content/docs/guide/	/guide/…
Decisions and research	docs/decisions/, docs/research/	Repository only, not the site
Site-only pages	apps/docs/src/content/docs/	/…
Generated API reference	Built from the package’s exports	/api/<pkg>/…

Package docs sit next to the code, so a code change and its docs land in the same diff.

The rules

1. Every export is documented. Each package doc page lists the exports it explains in its symbols frontmatter. The docs build fails on any export that no page lists, and on any listed symbol that is no longer exported.
2. Every source change has a changelog line. Committing a change under packages/<pkg>/src/ without also staging packages/<pkg>/CHANGELOG.md is rejected by the pre-commit hook. Entries go under Unreleased, in Keep a Changelog sections (Added, Changed, Fixed, Removed).
3. Examples are real code. Examples are .ts files that import the package by name. They are type-checked by vp check and exercised by tests in tests/docs-examples.test.ts, then embedded into pages with ?raw imports. An API change that breaks an example breaks the build.
4. Every page has a title and description, and internal links use site paths such as /packages/shapes/overview/. The site build validates the frontmatter schema and every internal link.

Checks and when they run

Check	Runs in
Format, lint, type check	pre-commit (vp staged)
Changelog entry for src/	pre-commit (vp staged)
Tests, including examples	pre-push (vp run ready)
Site build, links, coverage	pre-push (vp run ready)

Adding an export, step by step

1. Write the code in packages/<pkg>/src/ and its tests in tests/.
2. Explain it on a page in packages/<pkg>/docs/ and add its name to that page’s symbols.
3. If it benefits from an example, add docs/examples/<name>.ts, embed it, and assert it in tests/docs-examples.test.ts.
4. Add a line to CHANGELOG.md under Unreleased.
5. Preview with vp run @draw/docs#dev.