# 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.

Documentation contract

This directory has one owner for every fact. The public index is 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`	`guides/language.md`, `internals/compiler.md`
CLI workflow	`guides/command-line.md`	`internals/tools.md`
Packages and registries	`guides/packages.md`	`reference/settings.md`
GHTML syntax	`reference/ghtml.md`	`guides/web.md`, `internals/web.md`
Web application workflow	`guides/web.md`	`internals/web.md`
Data model and policy	`guides/model.md`	`guides/data-access.md`
GizDB use	`guides/data.md`	`guides/vector.md`, `guides/gizdb-server.md`, `internals/database.md`
GizFS use and operations	`guides/storage.md`, `guides/storage-range.md`	`internals/storage.md`
Compute and models	`guides/compute.md`	`guides/ml.md`, `internals/compute.md`
Agents and GizDesk	`guides/agent.md`, `guides/desk.md`	`learning.md` labs
Runtime and system contracts	`internals/runtime.md`, `internals/system.md`	`reference/settings.md`
Measurements	`operations/benchmarks.md`	`internals/performance.md`, `bench/*/README.md`
Release changes	`operations/changelog.md`	Source and tests for the release

Learning policy

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/, 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

Find the subject owner in the table above.
Update the owner and its source-backed example or test.
Update supporting pages only with navigation and the smallest context needed.
Update learning.md if the learning order, tour or lab changed.
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.