# Documentation contract

This directory has one owner for every fact. The public index is [`README.md`](README.md).

## Page roles

| Role | Audience | Owns | Does not own |
| --- | --- | --- | --- |
| Learn | A new developer | A linear first success and complete labs | API rules or implementation details |
| Guide | A developer completing a task | A working procedure from inputs to a result | Exhaustive declarations or internal invariants |
| Reference | A developer checking an exact fact | Language, SQL, settings and public declarations | Tutorials, design rationale or benchmark claims |
| Internals | A maintainer changing Gizlang | Architecture, invariants, ownership and limits | User onboarding and duplicated API tables |
| Operations | A reviewer checking a release | Measured results and release changes | Unmeasured claims and implementation specifications |

The same rule is never copied between roles. A page may explain a concept briefly, then link to its owner.

`README.md` is the public router. `quickstart.md` is the first-success page and `learning.md` is the learning layer with the platform tour, paths and labs. `labs/` contains only complete, runnable walkthroughs; it is not another API or architecture layer.

## Canonical ownership

| Subject | Canonical page | Supporting pages |
| --- | --- | --- |
| Language meaning and diagnostics | [`reference/language.md`](reference/language.md) | [`guides/language.md`](guides/language.md), [`internals/compiler.md`](internals/compiler.md) |
| CLI workflow | [`guides/command-line.md`](guides/command-line.md) | [`internals/tools.md`](internals/tools.md) |
| Packages and registries | [`guides/packages.md`](guides/packages.md) | [`reference/settings.md`](reference/settings.md) |
| GHTML syntax | [`reference/ghtml.md`](reference/ghtml.md) | [`guides/web.md`](guides/web.md), [`internals/web.md`](internals/web.md) |
| Web application workflow | [`guides/web.md`](guides/web.md) | [`internals/web.md`](internals/web.md) |
| Data model and policy | [`guides/model.md`](guides/model.md) | [`guides/data-access.md`](guides/data-access.md) |
| GizDB use | [`guides/data.md`](guides/data.md) | [`guides/vector.md`](guides/vector.md), [`guides/gizdb-server.md`](guides/gizdb-server.md), [`internals/database.md`](internals/database.md) |
| GizFS use and operations | [`guides/storage.md`](guides/storage.md), [`guides/storage-range.md`](guides/storage-range.md) | [`internals/storage.md`](internals/storage.md) |
| Compute and models | [`guides/compute.md`](guides/compute.md) | [`guides/ml.md`](guides/ml.md), [`internals/compute.md`](internals/compute.md) |
| Agents and GizDesk | [`guides/agent.md`](guides/agent.md), [`guides/desk.md`](guides/desk.md) | `learning.md` labs |
| Runtime and system contracts | [`internals/runtime.md`](internals/runtime.md), [`internals/system.md`](internals/system.md) | [`reference/settings.md`](reference/settings.md) |
| Measurements | [`operations/benchmarks.md`](operations/benchmarks.md) | [`internals/performance.md`](internals/performance.md), `bench/*/README.md` |
| Release changes | [`operations/changelog.md`](operations/changelog.md) | Source and tests for the release |

## Learning policy

[`learning.md`](learning.md) is a learning index and platform tour, not a second specification. It contains role-based paths, runnable examples and links to complete labs.
Long labs live under [`labs/`](labs/), where they can be read and tested as complete documents. Learning
must not contain one-file-per-chapter fragments or restate a complete language, SQL, web, database or runtime reference.
When a lab and a canonical page disagree, the canonical page and its tests win.

Learning covers every platform area through its paths, tour sections and complete labs. A subject is represented by a canonical owner or a runnable lab; it is never left as an empty heading or a future promise.

## Updating a page

1. Find the subject owner in the table above.
2. Update the owner and its source-backed example or test.
3. Update supporting pages only with navigation and the smallest context needed.
4. Update `learning.md` if the learning order, tour or lab changed.
5. Run `bin/giz test docs` and the tests named by the changed source area.

The repository's source and tests are the authority for current behavior. A benchmark belongs in Operations only when its
corpus, command, machine, date, numerator, denominator and failures are recorded.

## Consolidation audit

The former guidebook chapters were not discarded. Their verified material is consolidated into the owning pages:

| Former material | Current owner |
| --- | --- |
| Compilation lifecycle | `internals/compiler.md` |
| Types, values, unions and errors | `reference/language.md` |
| Tasks and channels | `internals/system.md` |
| CLI, VS Code, DAP and test runner | `guides/command-line.md` |
| Models and schema migration | `guides/model.md` |
| Five data-access levels | `guides/data-access.md` |
| Reactive GizWeb and CDP proof | `guides/web.md` |
| Benchmark methodology and results | `operations/benchmarks.md` |
| Todo, agent and GizDesk walkthroughs | `labs/` |

The old one-file-per-chapter paths are removed. The content was merged before removal; the owner table above is the
review checklist for future changes.