# Docs review TODO

Walk-through of every user-facing section in `docs/user/docs/`. Tick each box once the section has been reviewed against the current code and rewritten where needed.

Conventions: nav titles match `docs/user/mkdocs.yml`. Paths are relative to `docs/user/docs/`. Verdicts in parentheses come from `docs/user/guide-audit.md` (2026-04-19) where available.

To process the next item, invoke the `docs-todo-next` skill (e.g. "do the next docs todo"). It picks the first unchecked box, verifies the code, drafts the page, dispatches a reviewer, and ticks the box.

## Missing sections to add

New pages that need to be written and wired into the nav.

- [x] **Getting Started → Quickstart (5-min)** `getting-started/quickstart.md` — pure copy-paste path to a green check, shorter than First Contract.
- [x] **Getting Started → Core Concepts in 3 Minutes** `getting-started/core-concepts.md` — what is Turbine, mental model before installation.
- [x] **Concepts → QualitySpec vs Contract** `concepts/qualityspec-vs-contract.md` — non-trivial distinction, deserves its own page.
- [x] **Concepts → Quality Dimensions** `concepts/quality-dimensions.md` — split out of `scoring.md`; dimension is always the user's explicit choice.
- [x] **Concepts → Metadata Schema** `concepts/metadata-schema.md` — explain how Turbine's metadata schema works (registry tables, lifecycle, what gets persisted where).
- [x] **Guides → Authoring Contracts (ODCS)** `guides/authoring-contracts.md` — how to write a contract from scratch; complements the tutorial.
- [x] **Guides → Custom Check Types / Plugin Authoring** `guides/custom-checks.md` — if extensible, document; if not, say so explicitly.
- [x] **Reference → ODCS Schema Reference** `reference/odcs-schema.md` — full contract YAML schema (fields, types, defaults).
- [x] **Reference → SLA Properties Schema** `reference/sla-schema.md` — full SLA property list (SLA is mandatory, deserves dedicated reference).
- [x] **Reference → Environment Variables** `reference/env-vars.md` — grep-friendly list next to Configuration.
- [x] **Reference → Exit Codes** `reference/exit-codes.md` — CI users need this.

## Sections to remove

- [x] **DELETE** `reference/comparison.md` — comparison docs age fast, read like marketing, violates explain-don't-sell.
- [x] **DELETE** `reference/sli-slo.md` — orphan, not in nav.
- [x] **DELETE** `guides/custom-backends.md` — flagged MAJOR REWRITE in audit; API is fictional. Delete before any rewrite, then decide whether to rebuild from current code.

## Home

- [x] `index.md`

## Getting Started

- [x] `getting-started/index.md`
- [x] `getting-started/installation.md`
- [x] `getting-started/first-contract.md`
- [x] `getting-started/next-steps.md`

## Guides

- [x] `guides/index.md`
- [x] `guides/workflow.md` (NEEDS UPDATE — thin on `ci`, missing `new datasource`/`new check`)
- [x] `guides/dev-workflow.md` (NEEDS UPDATE — `--verbose` ghost flag, `serve --datasource` shape wrong)
- [x] `guides/scaffolding.md`
- [x] `guides/onboarding.md`

### Writing Checks

- [x] `guides/checks/turbine-checks.md` (NEEDS UPDATE — `failed_rows`/`values_in` missing from CHECK_CATALOG, stale SodaCL asset names)
- [x] `guides/checks/sql.md` (MAJOR REWRITE — obsolete top-level `sql: { enabled, checks }` DSL, current schema is flat `quality:` list)
- [x] `guides/checks/python.md` (NEEDS UPDATE — em-dash violations L88/L183/L193, `--flag` missing)
- [x] `guides/checks/window.md` (NEEDS UPDATE — phantom `threshold` field, snake_case vs camelCase drift)
- [x] `guides/checks/tune-mode.md`

### Data Handling

- [x] `guides/row-flagging.md` (NEEDS UPDATE — lifecycle `removed` should be `retired`, `contract_flags` example misleading, missing `contract_id`)
- [x] `guides/incremental.md` (MAJOR REWRITE — `check_runs` table section is fabricated; matching is `contract_id + table_name` via LastRunReader; `ci check` incremental by default, `check` is not)
- [x] `guides/quality-specs.md` (NEEDS UPDATE — `--flag` underexposed, dimension-choice guidance implicit)

### Contracts

- [x] `guides/linting.md` (NEEDS UPDATE — "eight rules" ambiguous; 8 single + 5 cross = 13)
- [x] `guides/schema-validation.md` (NEEDS UPDATE — `Unique`/`Length`/`Precision` rule classes don't exist, extra-in-db severity is INFO not WARNING)
- [x] `guides/sla-properties.md` (PASS minor — fabricated view_builder latency-ordering claim)
- [ ] `guides/contract-versioning.md` (PASS — JSON example keys wrong: `overall_bump` → `highest_bump`, `contracts` → `entries`)
- [ ] `guides/codegen.md` (NEEDS UPDATE — wrong import path; nonexistent `DELETED` SyncStatus)

### Editor Integration

- [x] `guides/vscode.md` (PASS minor — verify onboarding step names)
- [x] `guides/lsp-clients.md`

### Datasources

- [x] `guides/datasources.md` (MAJOR REWRITE — fabricated Postgres `schema`/`sslmode`, fabricated Snowflake `authenticator`/`private_key_passphrase`, unimplemented Redshift/Yugabyte/CockroachDB, widespread em-dash violations)

### Observability

- [ ] `guides/dashboard.md` (NEEDS UPDATE — Alerts page described with wrong model; page ordering mismatch)

### Deployment

- [x] `guides/api-server.md`
- [ ] `guides/python-api.md`
- [ ] `guides/ci-cd.md`
- [ ] `guides/scoring-gates.md`
- [ ] `guides/security.md`
- [ ] `guides/performance.md`

## Concepts

- [ ] `concepts/index.md`
- [x] `concepts/contracts.md`
- [ ] `concepts/scoring.md`
- [ ] `concepts/check-pipeline.md`
- [ ] `concepts/row-flagging.md`
- [ ] `concepts/codegen.md`
- [ ] `concepts/incremental.md`
- [ ] `concepts/lsp.md`

## Cookbook

- [x] `cookbook/index.md`
- [ ] `cookbook/new-data-product.md`
- [x] `cookbook/anomaly-detection.md`
- [ ] `cookbook/gitlab-ci.md`
- [ ] `cookbook/multi-database.md`
- [ ] `cookbook/migrate-from-soda.md`
- [x] `cookbook/api-server-setup.md`

## Reference

- [ ] `reference/index.md`
- [ ] `reference/cli.md`
- [ ] `reference/configuration.md`
- [x] `reference/api.md`
- [ ] `reference/errors.md`
- [ ] `reference/diagnostic-ids.md`
- [ ] `reference/troubleshooting.md`
- [ ] `reference/glossary.md`
- [ ] `reference/databases.md`

## Changelog

- [ ] `changelog/index.md`

## Notes

- Audit reference: `docs/user/guide-audit.md` (2026-04-19) — verdicts above pulled from there.
- Non-negotiables to enforce on every page: `uv add` not `pip install`, Python 3.13+, YAML block style (no flow `{k: v, k: v}`), no em-dashes, explain-don't-sell, run the humanizer pass on prose.
- Pages **not** in nav (orphans worth deciding on): `playground.md`, `reference/api-playground.md`, the `contributing/` tree.
