--- name: docs-standards description: Documentation maintenance rules — which docs map to which code areas, the thin-pointer/no-drift rule, and the graphify-update step. Owned by project-steward. Load for /update-docs and the docs-sync step of the implement-workflow. ---

# Docs standards (project-steward)

## Code → docs map

- IPC contract change (`packages/shared/src/ipc/contracts/`) → write the prose as **TSDoc on the contract member**, then `pnpm gen:api`. `docs/API.md` is generated (`scripts/gen-api-docs.mjs`) and must never be hand-edited; CI enforces freshness via `pnpm gen:api:check`. - New domain/module or boundary change → `docs/knowledge/` + `docs/ARCHITECTURE.md`. - Export/template change → `docs/EXPORT_TEMPLATES.md` + `docs/knowledge/resume-domain.md`. - Scraping/provider change → `docs/knowledge/automation-domain.md`. - Design-system change → `docs/DESIGN_SYSTEM.md`. - Architecture / module / IPC-contract / registry change → also refresh the landing diagrams `apps/landing/src/data/architecture-map.ts` + `apps/landing/src/content/how-it-works/body.html`, then run `pnpm check:landing-drift` (CI enforces it via the Lint & Format job). - A durable architecture decision → an ADR in `docs/knowledge/decision-records/`.

## No-drift rule (thin pointers)

Applies to **everything under `docs/`**, not only `docs/knowledge/` — that is the scope reviewers enforce, so it is the scope to write to.

Describe **shape and contracts**; **never copy drift-prone literals** (scoring weights, thresholds, template/board/applier counts, function signatures, enum members, file lists). Point at the owning source symbol instead (weights → `commands/match_resume.rs`; templates → `export/templates/mod.rs`; registries → `scraping/boards/mod.rs` (SCRAPERS)).

The ~150-line cap is narrower than the rule around it: it applies to `docs/knowledge/` files only, not to every page under `docs/`.

**Self-check before saving a doc edit:** for every number, name or signature on the page, ask "if someone changed this in the code tomorrow, would this page silently become a lie?" If yes, replace it with a pointer to where it lives.

**Generated pages are exempt because they are not editable at all.** A file opening with a `GENERATED FILE` banner (`docs/API.md`) is rendered from its source by a script; restating the contract is its whole purpose. Fix the TSDoc on the contract member and re-run the generator — never the page.

## After editing code or docs

Run `graphify update .` (AST-only, no API cost) so the graph stays current.

## Last-updated header maintenance

Most docs carry a `Last updated: YYYY-MM-DD` header (line ~3). **The auto-bump hook updates the date automatically** when files are staged for commit via `lint-staged`, so no manual date updates are needed.

If a doc's header includes a trailing annotation like `Last updated: YYYY-MM-DD (v0.116.0)` or `(task #16: ...)`, **refresh the annotation to describe the current change** whenever you edit that doc — the hook preserves it. Example:

- Before: `Last updated: 2026-07-16 (v0.116.0)` - After edit for new feature: `Last updated: 2026-07-16 (v0.117.0: new feature)` or just `(v0.117.0)` if the versioning scheme is simple.

This makes commit history and blame queries meaningful — the annotation documents _why_ the doc was touched, not just _when_.

## Lessons graduation

When an **Architecture-decision** lesson becomes an ADR, **remove it from `lessons.jsonl`** — the ADR is then its single source.

## External standards & best-practices (verified 2026-06-19)

- **Diátaxis** — keep the four types distinct, never mixed in one page: **Tutorial** (learning), **How-to** (task), **Reference** (lookup/spec), **Explanation** (the "why"). Axes: action↔cognition, acquisition↔application. https://diataxis.fr/ - **Docs-as-code** — docs in-repo, versioned, reviewed in PRs, built/linted in CI. https://www.writethedocs.org/guide/docs-as-code/ - **Thin-pointer / no-drift** — see §No-drift rule above for the scope and the self-check; it is the whole of `docs/`, not just `docs/knowledge/`. After code changes, re-sync docs + run `graphify update .`.

**Common mistakes:** a "reference" page drifting into tutorial prose (split it — one need per page); pasting code values/signatures into docs instead of pointing at the source (guaranteed drift).