.. include:: /_templates/include-file/page-prefix.rst

.. _hell-ll-infra-b27-build-warning-cleanup-prompt:


================================================================================
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
=========================================

.. code-block:: bash

   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**.


.. ----------------------------------------------------------------------
.. VVN: dv_ClaOp47Max_MMv1_b27-build-warning-cleanup-prompt_2026m05d27
.. ----------------------------------------------------------------------