# Contributing (docs and code orientation)

## Documentation layers

| Type | Owns | Must not |
|------|------|----------|
| **CONTRACT** | Invariants, schemas, support policy | Duplicate the same rule in a second contract |
| **GUIDE** | Flows and examples | Invent “must/required/invariant” rules |
| **ARCHITECTURE** | Shape and boundaries | Define persisted schemas or support policy |
| **PRODUCT** | Vision, roadmap, status | Own on-disk schema details |

Do **not** put `Type:` / `Authority:` rows at the top of Markdown files. The layers are writing rules, not page headers — they rendered on hosted Sphinx pages. Classification is by location and index. Authority lives in [CONTRACT_INDEX.md](../CONTRACT_INDEX.md) and the contract files themselves.

Archived docs under `docs/archive/` carry an **Archived / superseded** banner and link to a current authority. Do not list them as live product docs in `USER_INDEX`.

## Three voices

| Voice | Surfaces | Job |
|-------|----------|-----|
| **User guide** | README, website, Sphinx “Start here”, `user_guide.md`, runtime how-tos | Outcomes, GUI labels, what to do first |
| **Technical reference** | Contracts, `public_surfaces.md`, TERMS, model matrix/recipes | Invariants, schemas, support policy |
| **Maintainer** | ROADMAP, `docs/dev/`, archive, reviews | Sequencing, alignment, delivery history |

README is a user-guide entry: product, outcomes, first notebook, install, privacy. Do not put public-surfaces tables, schema names, or release-history paragraphs on the first screen.

## Indexes

- Users: [../USER_INDEX.md](../USER_INDEX.md)
- Developers: [../DEV_INDEX.md](../DEV_INDEX.md)
- Contracts: [../CONTRACT_INDEX.md](../CONTRACT_INDEX.md)
- Archive: [../archive/ARCHIVE_INDEX.md](../archive/ARCHIVE_INDEX.md)
- Surfaces map: [docs_architecture.md](docs_architecture.md)

## Contract authorities (single source of truth)

When you change behaviour for a concept, update the **owning** contract first, then adjust guides to summarize and link.

| Concept | Authority |
|---------|-----------|
| Project layout / journal / locks | [contracts/project-on-disk.md](../contracts/project-on-disk.md) |
| Page results / prefer / fingerprints | [contracts/page-result.md](../contracts/page-result.md) |
| Export / `content_revision` | [contracts/notebook-export.md](../contracts/notebook-export.md) |
| Workspace settings / profiles | [contracts/workspace-settings.md](../contracts/workspace-settings.md) |
| Workspace backup | [contracts/workspace-backup.md](../contracts/workspace-backup.md) |
| Public surfaces / support policy | [public_surfaces.md](../public_surfaces.md) |
| Corpus / import / integrity | [contracts/notebook-corpus.md](../contracts/notebook-corpus.md) · [import-run.md](../contracts/import-run.md) · [corpus-integrity.md](../contracts/corpus-integrity.md) |
| Analysis / detection | analysis-* and detection-* under [CONTRACT_INDEX](../CONTRACT_INDEX.md) |
| Terminology index | [TERMS.md](../TERMS.md) (GUIDE; not authoritative alone) |

## Documentation sync checklist

### 1. Contract changes

It is a docs failure if behaviour changes are only described in README, runtime guides, or architecture without being reflected in the owning contract.

### 2. Guides, architecture, and runtime docs

Hard failure conditions:

- Any GUIDE or ARCHITECTURE that defines project layout, provenance, export schema, or support policy as new rules
- Any `docs/runtime/*` doc that invents invariants instead of summarizing + linking a contract

Fix by moving the rule into the contract and replacing the original with a short summary + link.

### 3. Entry points and examples

1. Confirm CLI / UI examples in README and [public_surfaces.md](../public_surfaces.md) match code
2. Confirm [runtime/docker.md](../runtime/docker.md) matches `docker-compose.yml` mounts and ports
3. Confirm no archived plans are presented as active roadmaps in `USER_INDEX` / README
4. When changing ROADMAP **Now** / product-focus copy, keep [usability_wave_plan.md](../usability_wave_plan.md) in sync and ensure README Advanced + [USER_INDEX](../USER_INDEX.md) / [DEV_INDEX](../DEV_INDEX.md) / [index.md](../index.md) still link the active focus plan. Keep [Path to 0.9.0 / 0.9-1 / 1.0](../ROADMAP.md#path-to-090--09-1--10) and [After 1.0](../ROADMAP.md#after-10--notebook-anchored-autobiography-workbench----planned) distinct — do not present After 1.0 as current core while U2 / I6 remain open.

### 4. When code changes (quick map)

| Change | Update |
|--------|--------|
| Corpus / import / doctor | corpus contracts |
| Page-result / multipass / preference | page-result · ocr-multipass · ocr-preference |
| Analysis / detection | analysis-* · detection-* · notebook-eligibility |
| Tags / organisation catalog | [tag-catalog.md](../contracts/tag-catalog.md) |
| Export / backup | notebook-export · workspace-backup · runtime guides |
| CLI/UI entrypoints | public_surfaces + README links |
| Ownership / shape | ARCHITECTURE |
| Vision / roadmap | PRODUCT · ROADMAP (0.9.0 / 0.9-1 / 1.0 + After 1.0) · usability_wave_plan · user_testing_0_9 |


Then skim guides for stale summaries.

## Formatting

`pyproject.toml` pins **Black** and **Ruff** to line-length **100** and **py310**. Named test lanes: root `Makefile` and [tests/README.md](../../tests/README.md). Tag checklist: [release_governance.md](release_governance.md). Before opening a PR that touches Python:

```bash
make lint                 # ruff critical (CI)
make test-smoke && make test-fast
make docs                 # Sphinx HTML; pip install -e '.[docs]'
pre-commit install        # once; hooks in .pre-commit-config.yaml (I3)
black src tests           # optional local format; not a PR CI gate yet
ruff check --fix src tests
```

## Code orientation

See [developer_quickstart.md](../developer_quickstart.md). Prefer tests that stay offline. Do not add a TranscriptX dependency.