> ## Documentation Index
> Fetch the complete documentation index at: https://try.materi.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Contract

> Quality bar, structure, and source-of-truth rules for Materi docs

This document defines the *minimum standard* for documentation in this repository.
It is intentionally operational: it prioritizes clarity, correctness, and maintainability over prose.

## Goals

* Make docs **verifiable** (reviewers can confirm correctness from sources).
* Keep docs **modular** (avoid duplication; prefer shared snippets and canonical references).
* Prevent **drift** between docs and the system (generated/reference-first for specs).
* Scale across **multiple services and repositories** with predictable structure.

## Scope and audiences

This repo contains multiple audiences. When writing or reviewing, be explicit about which audience a page serves.

* **Customer**: product usage and workflows (non-technical or lightly technical)
* **Developer**: integration, API usage, SDKs, service architecture
* **Enterprise**: deployment, compliance/security posture, operations at scale
* **Internal**: engineering/operations runbooks, ADRs, deep design specs

A page should not try to serve two audiences unless it clearly separates sections.

## Document types and required sections

Use the simplest doc type that fits the intent.

### Overview ("what is this?")

Required:

* **Purpose** (what it is)
* **Who it’s for**
* **How it fits** (links to related concepts/guides/reference)

### Concept ("how does it work?")

Required:

* **Problem / motivation**
* **Core model** (entities, invariants, state machine if applicable)
* **Failure modes** (what can go wrong; guarantees and non-guarantees)
* **Related references** (schemas, endpoints, events)

### Guide ("how do I do X?")

Required:

* **Prerequisites**
* **Steps** (ordered, copy/paste friendly)
* **Expected outcomes** (what success looks like)
* **Troubleshooting** (common errors and fixes)

### Reference ("exactly what is supported?")

Required:

* **Canonical source link** (OpenAPI, proto, event schema, config)
* **Versioning policy** (or link to it)

Rule: if the content is already expressed in a machine-readable spec, **do not re-type it**.
Instead, render it (generated) or link to it.

### Runbook / Operations

Required:

* **Signals** (metrics/logs/traces, dashboards)
* **Playbooks** (diagnosis → mitigation)
* **Rollback / recovery**
* **Escalation** (owners/contacts)

### ADR (Architecture Decision Record)

Required:

* **Context**
* **Decision**
* **Consequences**
* **Alternatives considered**

## Stub policy (definition + allowed markers)

A “stub” is any page that reads like a placeholder rather than usable documentation.

A page is considered a stub if **any** of the following are true:

* It includes obvious placeholder language such as: `Stub`, `TODO`, `TBD`, `Placeholder`.
* It has headings without meaningful content under them.
* It does not meet the required sections for its doc type.
* It cannot be validated against a source of truth (links/specs/code) when it claims behavior.

Allowed markers:

* `DRAFT:` in the first paragraph is allowed *only if* the page is still useful.
* `<!-- STUB -->` is allowed for intentionally parked pages (should be rare and tracked).

## Source-of-truth hierarchy (cross-repo scalable)

When information exists in a canonical system, docs should **derive from it** rather than duplicating it.

Preferred order:

1. **Machine-readable specs**: OpenAPI, protobuf, event schema definitions
2. **Executable examples**: SDK samples, integration tests, reference clients
3. **Operational reality**: runbooks + dashboards + incident learnings
4. **Narrative**: concepts, overviews, guides

Practical rules:

* Endpoint shapes, request/response bodies, status codes: **OpenAPI**.
* Event names/payloads/versions: **event schema source** (and generation where feasible).
* Wire formats and shared domain objects: **protobuf**.
* Timeouts, limits, retries, idempotency: **code + config**, summarized with links.

If you must duplicate facts (e.g., to explain intent), keep it *high level* and link to the canonical spec.

## Writing standards

* Prefer **precise language** over marketing language.
* State **guarantees** and **non-guarantees** explicitly.
* Include **version context** when behavior is not timeless.
* Avoid copying the same instructions into multiple pages; use snippets or link to the canonical page.

## Verification standards (implemented as gates in CI)

These are the checks the docs system should be able to enforce:

* **No-stub gate**: blocks known stub markers and missing required sections.
* **Broken link gate**: `mint broken-links` clean.
* **Reference drift gate**: generated reference output matches committed specs.
* **Build gate**: docs preview/build succeeds.

(Automation is added later; this contract defines what automation must enforce.)

## Change management

Documentation updates should ship with the change that requires them:

* New endpoints/events/config knobs → update the canonical spec and regenerate reference pages.
* Behavioral changes → update the concept/guide page and link the PR.
* Incidents → update runbooks with the learning.

If a PR changes runtime behavior and does not update docs (or explicitly justify why not), it is incomplete.

## Ownership model

Every documentation section has a **primary owner** who is accountable for accuracy.

See [`OWNERS.md`](/OWNERS.md) for the full ownership matrix, team aliases, and escalation paths.

Key principles:

* Ownership means **accountability**, not gatekeeping. Owners should enable contributions.
* Changes to a section require approval from its primary owner (or secondary if unavailable).
* Structure changes (navigation, new sections) require `@docs-lead` approval.
* Stale content (not updated in 6 months while the system changed) should be flagged and assigned.