Writing documentation

Pages live under documentation/src/content/docs/ and use Starlight’s file-based routes. Prefer .mdx when importing Starlight components; ordinary Markdown remains suitable for simple prose.

Authoring workflow

Identify the authoritative contract or ADR for the behavior.
Update that source and its executable tests when behavior changes.
Update the curated page that explains the behavior.
Add or revise a Mermaid diagram only when relationships or sequence become clearer than prose.
Run the documentation audit, type check and production build.

MDX components

Import components from @astrojs/starlight/components at the start of the page:

import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';

<Aside type="caution" title="Contract boundary">
  Explain a risk without hiding it in ordinary prose.
</Aside>

Use components for navigation, steps, tabs and materially important notices. Keep ordinary explanation in Markdown so pages remain easy to review.

Mermaid diagrams

Use a fenced mermaid block. astro-mermaid renders it during the site build and follows Starlight’s light/dark theme.

```mermaid
flowchart LR
    API --> Command --> PostgreSQL
```

Diagram rules:

describe one relationship or sequence per diagram;
use stable architectural names rather than transient implementation detail;
accompany diagrams with text for accessibility and search;
avoid encoding guarantees that are not backed by a contract and test;
run the production build so invalid Mermaid syntax fails before review.

Links and source-of-truth

Use site-relative links such as /architecture/runtime/ for curated pages. Link detailed contract sources through the authoritative contracts index. Do not copy entire source documents into this site; summarize their implications so one normative copy remains.

Validation

cd documentation
npm audit --audit-level=low
npm run check
npm run build

Starlight validates internal links during the production build. CI runs the same commands on every pull request.