b27 — Sphinx build-warning cleanup (post-launch, delegatable)#

Mode: CRAFT suggested (mechanical); switch to EDEN only for the one judgment call in §3.B (the aaa.rst ↔ study/index.rst overlap).
Effort: Medium.
Run when: After the 2026m05d27 launch. Not a launch blocker.
Status: Prompt, not executed. Drafted by dv_ClaOp47Max 2026m05d27.

1. Why this exists#

A full make clean && make html surfaces ~544 warnings + 1 error. The fast make dev (incremental) reports only ~39 — it shows warnings for changed files only, masking the rest. None of these block the build or the Cloudflare deploy: the site builds and ships fine with them. They are pre-existing structural debt (labels, toctrees, orphans), not content errors. Clean them post-launch, in priority order, verifying the count drops.

This work is bounded, mostly mechanical, low-risk, and highly verifiable (the warning count is the metric) — which is why it is safe to delegate. The only judgment item is §3.B.

2. Step 1 — full categorised inventory#

make clean && make html 2>&1 | tee /tmp/warns.log
echo "TOTAL:"; grep -c "WARNING:" /tmp/warns.log; grep -c "ERROR:" /tmp/warns.log
echo "BY TYPE:"; grep "WARNING:" /tmp/warns.log \
  | grep -oE "WARNING: [a-zA-Z'][a-zA-Z' ]+" | sort | uniq -c | sort -rn
echo "BY FILE:"; grep -oE "^[^:]+\.rst" /tmp/warns.log | sort | uniq -c | sort -rn | head -30

Record the before-counts. (Observed categories at draft time: document isn’t included in any toctree; duplicate label aaa-*; duplicated entry found in toctree; toctree contains reference to nonexisting document; Citation not referenced; + 1 Invalid meta directive ERROR.)

3. Step 2 — fix the safe categories#

A. “document isn’t included in any toctree” (the bulk). For each orphan, decide:

  • Intentionally-standalone artifacts (HELL factsheets, prompt files, mm drafts not meant for nav) → add :orphan: at the file top.

  • Pages that should be reachable → add to the nearest sensible toctree.

(Blog posts auto-handle this via ablog; this is about hell/ and mm/ docs.)

B. The ``aaa.rst`` ↔ ``study/index.rst`` cluster — JUDGMENT CALL, ask LLoL. These two files appear to overlap heavily: shared labels (aaa-latest-papers, aaa-all-prompts, aaa-new, aaa-recent, aaa-series-cleanup-aa → duplicate label warnings), duplicated toctree entries, and both referencing the same missing document (see C). This one overlap likely accounts for a large fraction of the 544. Root-cause fix: decide which file is canonical and de-duplicate (or uniquely prefix one set of labels). This needs LLoL’s input on canonical-vs-copy — do not guess; surface options first.

C. Dead toctree target. Both files reference matheology/hell/ll/study/b/18/study_ll_2026m04d18_sgir-paper-review-llog, which does not exist. Find whether it was moved/renamed (fix the path) or is gone (remove the entry). Also clear the duplicated entry found in toctree items in the same toctrees.

D. The 1 ERROR — “Invalid meta directive” (``study/index.rst:1``). Fix the malformed .. meta:: block (likely a stray/duplicate directive or bad field syntax).

E. “Citation [Matheo-2-m-v2] is not referenced” (b13 mmv2). Minor: either cite it in-text or remove the unused entry. (Mind the Matheo-bNN citation convention.)

4. Step 3 — verify#

Re-run make clean && make html; report before/after counts overall and by category. Document any warnings deliberately left, with the reason. The target is a substantial drop, not necessarily zero (some third-party or intentional ones may remain).

5. Out of scope & safety#

  • No content changes — axioms, theorems, equations, symbol definitions untouched.

  • HELL llogs are append-only. Only TELES-class RST fixes (indentation, orphan flags, label scoping) with a dated admonition noting the repair.

  • File Safety: move obsolete files to HH/; never delete; only LLoL deletes.

  • The §3.B canonical decision is LLoL’s.