# Stream Docs: the living documentation and its gates
> **Status 10 Sep:** X1 to X3 landed on 5 Sep (the tier-1 trims, the doc shells, `docmap.py` and the FAIL gates); X4 (the WARN tier, the weekly sweep) is deferred to 23 Sep. Stream N ran the first full freshness pass on 10 Sep (handoff 2026-09-10). The body below is the brief as asked on 4 Sep.
**Written 2026-09-04 (Fri) against build plan v3 §3c and Decision 11.** Runs Fri 4 night →
Sun 6 as one session; then a duty on every stream; then the buffer week for the WARN tier.

## Goal
Documentation a complete stranger, or an agent that has never seen the code, can pick up:
tidy, no redundancy, no stale claims, and kept that way by the build check rather than by
memory. Rian's words: "this project will be massive; it must be extremely tidy to be
maintainable even if nobody else ever takes it over."

## Tonight, in this order; task ids are on /plan
1. **X1 Hygiene.** Fix the five files still titled "professormediagroup"; retitle and rewrite
   `brief.md` to ≤40 lines with a six-line **NOW** block (phase, accepted scope, deadline, live
   version, public airports, next milestone) marked `<!-- rewritten by /checkpoint -->`; delete
   `nginx.conf` and `.logs/deploy-failed.log`; set `poc-dfp.md` frontmatter `status: delivered`
   and move its "Legal guardrails" section into `main/docs/COLLECTORS.md` (create the file if A2
   has not yet, opening "Sources of truth: app/services/collectors/, app/cli.py"); banner
   `site-structure-proposal.md` as superseded by `/structure` (`lib/structure.ts`).
2. **X2 Tier 1 to budget, and the tier-2 shells.** `agents.md` to **≤140 lines**: rules only,
   ≤4 lines each with past-tense provenance, no counts, no paths that can move; merge the three
   robots rules into one; every 2026-09-04 block is a 2–3 line pointer ending "(build plan §9
   #n; not yet built)"; the "read first" chain is `brief.md → main/docs/ARCHITECTURE.md →
   .logs/issues.md → the last three handoff entries`. Create `main/docs/` shells, each opening
   with "Sources of truth: <dirs>" at directory granularity: `ARCHITECTURE.md` (request path;
   the pipeline; a module map **generated**, see X3), `DATA-MODEL.md` (rationale by hand; the
   table list generated), `COLLECTORS.md` (add plan §3b's paragraph and the robots policy; A and
   A2 fill their sections), `SEO.md` (B owns; create the shell), `RUNBOOK.md` (dev loop with
   `dfp-devdb`, `check.sh`, **deploy = dump first, bump version, CHANGELOG, `srv-gw deploy
   --build`**, CLI reference from `python -m app.cli --help`, the three tokens, what a deploy
   kills, backups and restore), `QUALITY.md` (Q owns; create the shell), `CLIENT-SURFACES.md`
   (board, quote, structure, plan page, comment keys, curator settings, positioning rules).
   Move `agents.md`'s Operational/Layout content into RUNBOOK/ARCHITECTURE.
3. **X3 The gates, FAIL tier only tonight.** `main/scripts/docmap.py` generates the module map
   (first docstring line per `app/**/*.py`) and the table map (SQLAlchemy metadata) into marked
   blocks inside ARCHITECTURE.md and DATA-MODEL.md. `main/docs-check.sh`, called from
   `check.sh`, **fails** on: `agents.md` > 140 lines; a generated block differing from a fresh
   generation; `brief.md`'s NOW-block version ≠ `APP_VERSION`; `CHANGELOG.md`'s first
   **versioned** heading ≠ `APP_VERSION` (an "Unreleased" heading above it is allowed). It
   **warns** (never fails tonight) on: a prose doc whose named source directory has a newer git
   commit than the doc; `issues.md` "last swept" older than 7 days; a handoff entry over 25
   lines. `--strict` turns the warnings into failures (Wave 4 uses it). Then a project
   `.claude/commands/checkpoint.md` that extends the server command with the four duties: rewrite
   the NOW block, sweep `issues.md` and stamp "last swept", run `docs-check.sh`, write the diary
   entry; and reminds the session to update `/plan` via `main/scripts/plan-set.py`.
4. **The cwd fix.** One line at the top of `/srv/apps/professormediagroup/CLAUDE.md`: "This is
   Adam's WordPress site. Duty Free Professor work lives in /srv/apps/dutyfreeprofessor; if that
   is your task, stop and restart the session there." Add `alias dfp='cd
   /srv/apps/dutyfreeprofessor && claude'` to RUNBOOK.md for rian.

## If time remains
`issues.md`: dedupe, move to the right section, stamp "last swept 2026-09-05". A first
`.logs/verification/docs-2026-09-05.md` sweep report: stale candidates, duplicate explanations,
dead links.

## Owns
`main/docs/*`, `main/scripts/docmap.py`, `main/docs-check.sh`, **`main/check.sh` (tonight only;
A and B run it, do not edit it)**, `agents.md`, `brief.md`, `.claude/commands/checkpoint.md`,
`.logs/issues.md` structure, `poc-dfp.md` frontmatter, the five mis-titled headers,
`/srv/apps/professormediagroup/CLAUDE.md` (one line).

## Must not touch
Any code under `app/` or `web/src` except reading it to generate maps; no collector, no route.

## Rules
- **Numbers are never typed into docs**: generated, or linked to `/api/stats` and `app.cli status`.
- **One home per mechanism**; the handoff links, it does not explain.
- Comments say why and what it cost; module docstrings are load-bearing (the map is built from
  them). Do not "improve" code comments tonight; note thin modules for the owning stream.
- Every rule you keep in `agents.md` passes the admission rubric: failure-backed,
  tool-enforceable, decision-encoding, or triggerable.
- You never deploy. `check.sh` must still pass for A and B at every point tonight: add
  `docs-check.sh` as a call that cannot fail their hand-back until the FAIL conditions are
  green on the current tree.