How to read this documentation

Documentation should be practical, not an archive of everything. Every important page should answer:

• who it is for,
• when to use it,
• what the source of truth is,
• when it was last verified,
• who owns it.

Content states

State	Meaning
Draft	The page is a proposal and needs expert review.
Reviewed	Someone verified the page against the product or code.
Source of truth	The page is the canonical source for the topic.

Staleness is derived, never declared: there is no “Stale” state to set. A page grows stale simply by being unreviewed for long enough, which is a fact tooling can compute from the reviewed date rather than a label an author would have to remember to add.

Conflict rule

When documentation disagrees with production behavior, production behavior is the fact and the documentation is a hypothesis. When documentation disagrees with an agreed process, the area owner decides whether to fix the process, the product, or the text.

Provenance markers

Inside a page, mark what kind of statement you are making. A marker is a bold label at the start of a paragraph. Readers get a callout; the agent bundle gets per-paragraph provenance, so it can tell a verified invariant from a guess.

Fact: This page is the convention itself, and npm run check enforces it.

Marker	Use it for	What a reader may do with it
**Fact:**	Behavior verified against the product or the code.	Rely on it.
**Verified:**	A freshness note pinning a claim to a commit or environment.	Trust the claim as of that point.
**Assumption:**	Something believed but not checked.	Treat as unconfirmed; verify before acting.
**Open question:**	A question this page does not answer.	Do not answer it from this page.
**Missing:**	An artifact or explanation that should exist and does not.	Expect to go to the code.
**Decision:**	A recorded choice. Must start with (YYYY-MM-DD, Name).	Context, not behavior.

Example:

**Assumption:** Repeating assignments recompute nightly. Not verified against the scheduler.
**Decision:** (2026-08-22, Jirka) Licence exhaustion is out of scope for this page.

npm run check rejects an unrecognised label, a marker with no text, and a Decision without an attribution.

Target page structure

Important pages should gradually move toward this structure:

Section	Why it matters
Audience	Separates client-facing wording from internal detail.
When to use	Helps readers decide whether the page is the right source.
Summary	Gives fast understanding without reading the full history.
Detail	Describes the process, domain, or API behavior.
Edge cases	Captures quirks, exceptions, legacy behavior, and non-obvious links.
Sources	Links to code, OpenAPI, old documents, or decisions.
Feedback	Explains how to challenge or improve the text.