Docs rewrite 5/5: reconcile CLAUDE.md and the doc-drift check

.github/workflows/check-docs.yml

@@ -34,14 +34,30 @@ jobs:
             Your task: check whether the project documentation is still accurate
             and complete given the code changes introduced by this PR.
 
+            The documentation is structured, and each kind of change has a home:
+            - A verb's flags, output, JSON shape, or exit codes → its page in docs/cli/
+              (one page per verb, plus the overview's exit-code contract).
+            - An engine module's responsibility, key symbols, or invariants → its page
+              in docs/api/ (hand-written module tours) and, for cross-cutting shifts,
+              docs/architecture.md.
+            - User-visible behavior (scaffold contents, states, refusal messages,
+              environment model, SLURM, publication) → docs/user/ (getting-started
+              quotes real console output; troubleshooting quotes real refusals) and
+              README.md's quick start.
+            - Test structure, dev workflow, or conventions → docs/contributing/.
+
             Steps to follow:
             1. Run: git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }}
                to get the list of changed files.
-            2. Read the changed source files (focus on .py, .ts, .js, .go, .rs files).
-            3. Read existing documentation files (README*, docs/**/*.md, CHANGELOG*, CONTRIBUTING*).
-            4. SKIP any files under skills/ or named SKILL.md — these are not user-facing docs.
-            5. Identify any documentation that is now inaccurate, incomplete, or missing
-               given the code changes.
+            2. Read the changed source files (focus on src/**/*.py and the workflows).
+            3. Read the documentation pages the map above points at for those changes.
+            4. SKIP CLAUDE.md and evals/ — agent instructions and the eval harness are
+               maintained separately, not user-facing docs.
+            5. Identify documentation that is now inaccurate, incomplete, or missing.
+               Two failure modes matter most here: a quoted console output or refusal
+               message that no longer matches what the CLI prints, and a documented
+               flag, verb, state, or file that no longer exists (the docs must never
+               describe more than the code delivers — no foreshadowing).
 
             Then:
             - Post a comment on PR #${{ github.event.pull_request.number }} summarising

CLAUDE.md

@@ -34,8 +34,10 @@ spec:
 > spec, the decisions win. It lives in the sibling checkout for now
 > (branch `redesign_prototype`), alongside its decision records
 > (rationale, substrate tradeoffs, hermeticity enforcement, the v6
-> review); it moves into this repo's `docs/design/` when the docs are
-> rewritten at the end of the rebuild.
+> review). It stays in the sibling checkout and is **dropped when the
+> rebuild completes** (decision, 2026-08): the design records are not
+> imported into this repo's docs — the rewritten `docs/` carries the
+> current design, and this file carries the decisions.
 
 The pre-rebuild codebase (Snakemake shim, authored Containerfiles,
 `container:` in `astra.yaml`, vendored dask executor plugin, WRROC export)
@@ -104,10 +106,15 @@ Each of these has been asked for in review at least once; none is optional.
 
 - **No dead code.** If nothing in the current layer calls it, it doesn't
   land yet. `lc --help` advertises only verbs that work.
-- **`docs/` is frozen at its pre-rebuild state, by decision.** It still
-  describes the old Snakemake architecture and the full command set.
-  Don't patch it layer by layer — it gets rewritten in one pass once the
-  rebuild is complete. Same for `README.md` and `zensical.toml`.
+- **`docs/` is live again** (rewritten 2026-08, PRs #185–#188; the
+  freeze is over). The site is two tracks — user guide + developer
+  corner — and a change now lands with its docs: a new or changed verb
+  updates its `docs/cli/` page, an engine change updates its
+  `docs/api/` module page, and user-visible behavior updates the user
+  guide. The docs' own rules match this file's: document only what
+  exists, quote refusals from real runs, and verify every command
+  block by executing it. `check-docs.yml` reviews each merged PR for
+  drift.
 - **Port with intent.** Prior implementations (this repo's git history,
   and the `redesign_prototype` branch of the sibling `lightcone-cli`
   checkout) are references, not sources of truth. Neither is the spec by
@@ -201,10 +208,12 @@ uv build                         # wheel + sdist (CI runs this only to publish)
 Test, lint and type-check are the whole loop, and they are what
 `.github/workflows/{tests,lint}.yml` run. There is deliberately no task
 runner in between — the pre-rebuild `justfile` was 90 lines of wrappers
-around them plus recipes for the frozen docs and the dormant eval. The
-other workflows are `eval.yml` (the agentic eval, on dispatch or any
-non-draft PR — flipping a draft to ready triggers it),
-`pypi-publish.yaml`, and `docs-deploy.yml` for the frozen docs.
+around them. The docs build with `uv sync --group docs && uv run
+zensical build`. The other workflows are `eval.yml` (the agentic eval,
+on dispatch or the `run-eval` PR label; re-trigger by re-adding the
+label), `check-docs.yml` (doc-drift review on merged PRs),
+`pypi-publish.yaml`, and `docs-deploy.yml` (deploys on release, so the
+site tracks the released CLI).
 
 ## Key Invariants (layer 1)
 
@@ -2172,7 +2181,7 @@ unlinks before writing; a new tampering test should too.
 
 | To... | Read | Key patterns |
 |---|---|---|
-| Add the next layer | the spec (§11 = the layer ordering) | Land code + tests + deps together; update the layer table above. Docs are deliberately deferred |
+| Add the next layer | the spec (§11 = the layer ordering) | Land code + tests + deps together; update the layer table above and the docs pages the layer touches |
 | Change what a scaffolded file contains | `src/lightcone/engine/templates/files/` | Edit the `.tmpl`; add new ones to `TEMPLATE_NAMES`, and a renderer only if the file needs a substituted value or a merge policy |
 | Add a value to the scaffold | `src/lightcone/engine/templates/__init__.py` | Derive it from the environment or our own metadata before introducing a constant |
 | Change what gets converged | `src/lightcone/engine/project.py` + `tests/test_project.py` | `_Converger.item` / `.file`; repairs only ever append |