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 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
Developers: …/DEV_INDEX.md
Contracts: …/CONTRACT_INDEX.md
Archive: …/archive/ARCHIVE_INDEX.md
Surfaces map: 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
Page results / prefer / fingerprints	contracts/page-result.md
Export / `content_revision`	contracts/notebook-export.md
Workspace settings / profiles	contracts/workspace-settings.md
Workspace backup	contracts/workspace-backup.md
Public surfaces / support policy	public_surfaces.md
Corpus / import / integrity	contracts/notebook-corpus.md · import-run.md · corpus-integrity.md
Analysis / detection	analysis-* and detection-* under CONTRACT_INDEX
Terminology index	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¶

Confirm CLI / UI examples in README and public_surfaces.md match code
Confirm runtime/docker.md matches docker-compose.yml mounts and ports
Confirm no archived plans are presented as active roadmaps in USER_INDEX / README
When changing ROADMAP Now / product-focus copy, keep usability_wave_plan.md in sync and ensure README Advanced + USER_INDEX / DEV_INDEX / index.md still link the active focus plan. Keep Path to 0.9.0 / 0.9-1 / 1.0 and After 1.0 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
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. Tag checklist: release_governance.md. Before opening a PR that touches Python:

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. Prefer tests that stay offline. Do not add a TranscriptX dependency.