Source of truth

This page defines where each piece of documentation content comes from, so the public docs never silently diverge from the product.

Content classes and their sources of truth

Content class	Source of truth	Authoring model
Architecture and kernel contracts	docs/DESIGN.md and docs/KERNEL_CONTRACT.md in the core repository	Authored in core; this site links to them, never duplicates them as hand-maintained public guides
SDK API reference	Public exports in sdk/ (source comments)	Generated with TypeDoc from the canonical source revision; never hand-copied
Package catalog	packages/*/package.json metadata (plus packageMetadata declarations)	Generated from package metadata; never a second handwritten registry
SDK recipes (agent guidance)	sdk/recipes/*.md in the core repository	Authored in core; linked from this site when relevant
User guides, concepts, tutorials	This docs project (site/src/content/docs/)	Authored here; validated in CI
Operations and policy documents	This docs project	Authored here

Engineering contracts stay contracts

DESIGN.md and KERNEL_CONTRACT.md are engineering contracts: precise, versioned with the kernel, and read by people modifying Muoto itself. The public docs explain them for users and extension authors. When this site explains an architecture concept, the corresponding contract section is linked rather than restated, and behavior claims must match the shipped product.

Generated content pipeline

• API reference: TypeDoc runs against the SDK entry points in the core repository revision the docs describe. The output identifies the SDK/package version. Internal protocol/kernel-only APIs are excluded.
• Package catalog: a small generator reads packages/*/package.json and emits catalog pages. The same metadata is consumed by CI/build tooling; there is no separate registry.

Both generators run before astro build and their output is committed or produced in CI so the site never contains stale hand-written signatures.

Cross-repository links and edit paths

• Links to core repository files use stable repository paths: docs/DESIGN.md, docs/KERNEL_CONTRACT.md, sdk/, packages/, and the GitHub blob URLs derived from the main branch.
• Edit paths for this site are predictable: every page links to https://github.com/arutkowski00/muoto/edit/main/site/src/content/docs/<path> (the editLink configuration).
• Edit paths for core files go to the same repository’s normal edit flow; the docs site never forks content into its own editing silo.

Validation

CI (.woodpecker/docs.yml) runs formatting, astro check (type and link validation), and a production build on every pull request, so broken internal links and stale navigation fail before merge.