.. meta::
   :description: POST AA b21 --- Three deferred build/site tasks: a browsable full-page sitemap tree, 154 CRITICAL llog heading errors, and the RFC 5321 FF slug-length limit.
   :keywords: AnyAims, POST AA b21, sitemap, toctree, llog heading errors, RFC 5321, FF slug, build warnings
   :author: LLoL as Laurence Loewe of Laodicea, ClaudeOp46-50Max, and Everyone

.. _post-aa-b21-deferred-build-and-site-tasks:


****************************************************************************************
POST AA b21: deferred build and site tasks
****************************************************************************************

| **Status:** OPEN (3 tasks, all previously marked deferred)
| **Scope:** site-wide build and infrastructure. Not HELL-specific, not paper-specific ---
  therefore **POST AA** under the placement rule.
| **Origin:** migrated 2026m08d04 from ``AHA/aa-code/``, which held three task documents
  (``engaging-sitemap.md``, ``fix-llog-level-build-errors-is-hard.md``,
  ``slug-length-limit.md``). They were **tasks, not lessons learned** --- each is framed as
  "here is a problem, here is what was deferred" --- so AHA was the wrong home. The
  originals are kept verbatim in ``AHA/HH/`` as dated snapshots.


Task list
=============

.. list-table::
   :header-rows: 1
   :widths: 5 5 42 48

   * - k
     - s
     - Task
     - Notes
   * - k3
     - s1
     - **Browsable full-page tree on the sitemap page.**
     - Deferred 2026m04d01: "the curated table is sufficient for now; implement when the
       site is closer to public launch and discoverability matters more." See the detail
       section below for the three implementation options and the duplicate-toctree
       constraint.
   * - k3
     - s1
     - **154 CRITICAL heading errors from 4 llog files.**
     - Deferred 2026m04d01: cosmetic --- pages render correctly and the build completes.
       Fixing needs an explicit exception to the append-only llog rule. **Re-check the
       count**: the paths recorded in 2026m04d01 are pre-HELL-migration
       (``matheology/vv/jub/...``) and the current full build reports 890 warnings in
       total, so these numbers need re-measuring before any work starts. Interacts with
       :doc:`POST AA b18 </_post/aa/b/18/b18-build-warning-gating-and-link-guards>` --- a
       blanket ``-W`` gate cannot be turned on while 154 CRITICALs stand.
   * - k3
     - s1
     - **RFC 5321 FF slug-length limit --- proper fix.**
     - Workaround in place since 2026m03d31; proper fix deferred until programmatic slug
       generation is feasible.


Detail 1 --- browsable full-page sitemap tree
===============================================

**Problem.** ``source/sitemap/index.rst`` has a hand-curated table of ~18 top-level
sections. There is no way for a visitor to see all 400+ pages in a structured, browsable
view. (The ``genindex.html`` link was mislabelled "complete page index" --- it is a glossary
term index; corrected to "glossary index".)

**What exists.** The curated table (keep it); ``genindex.html`` (glossary terms only);
``sitemap.xml`` (machine-readable SEO, not human-visible); the left sidebar (full toctree,
but only the current section's neighbourhood).

**Proposal.** A "Browse all pages" section below the curated table rendering the entire
toctree as a nested, collapsible list. Useful for scanning structure at a glance,
discovering deep pages (llogs, VV pages, axiom systems), and SEO internal-link weight.

**Option A --- conf.py hook (recommended, ~30 min).** An ``html-page-context`` handler in
``setup()`` that, for the sitemap page only, walks ``app.env.tocs`` and renders the full
toctree:

.. code-block:: python

   def _inject_full_toctree(app, pagename, templatename, context, doctree):
       if pagename != 'sitemap/index':
           return
       toctree_html = context['toctree'](maxdepth=-1, collapse=False, includehidden=True)
       context['full_sitemap_tree'] = toctree_html

   app.connect('html-page-context', _inject_full_toctree)

**Option B --- Jinja2 component.** ``source/_templates/components/sitemap-tree.html``
calling pydata-sphinx-theme's ``generate_toctree_html()`` at full depth.

**Option C --- JavaScript.** Build a client-side expandable tree from the search JSON. No
build changes, but needs custom JS and does not help SEO.

.. important::

   **Constraint: no duplicate toctree entries.** Sphinx allows each page in only ONE
   ``.. toctree::``. Adding a second toctree on the sitemap page listing all sections would
   raise "document is already in a toctree" warnings. All three options avoid this by
   *reading* existing toctree data rather than declaring a new one.

**Styling.** Reuse ``collapse-sections.css`` / ``.js``, or ``<details>``/``<summary>`` for a
no-JS fallback. Top level expanded, deeper levels collapsed. Match the sidebar's style.


Detail 2 --- the 154 CRITICAL llog heading errors
===================================================

A clean ``make html`` produced **154 CRITICAL errors** from 4 llog files. They vanish on
incremental rebuilds because Sphinx only reports on files it re-processes --- **the errors
are still there, just hidden.** (This is the same "green build hides real breakage" pattern
that let the 2026m08d03 path-case bug run for months.)

.. list-table:: As measured 2026m04d01 --- paths are PRE-HELL-migration, re-measure first
   :header-rows: 1
   :widths: 58 12 15 15

   * - File
     - Errors
     - Heading chars
     - Structural
   * - ``matheology/vv/jub/oov2/llog/llog_2026m03d21_restructuring-phase1-prompts-reply-overviews-for-debugs.rst``
     - 82
     - 28
     - 54
   * - ``matheology/compiler/forge/llog/sa3_2026m03d28/llog.rst``
     - 42
     - 42
     - 0
   * - ``matheology/vv/jub/oov2/llog/2I-por-field-testing.rst``
     - 17
     - 0
     - 17
   * - ``matheology/vv/jub/oov2/llog/deprecated/2I-por-field-testing-part-a.rst``
     - 13
     - 0
     - 13
   * - **Total**
     - **154**
     - **70**
     - **84**

**Two error types.** *"Title level inconsistent"* (70) --- underline characters do not match
the hierarchy established earlier in the file; mechanically fixable. *"Unexpected section
title"* (84) --- headings and ``----`` transitions appear **inside indented blocks**. RST
forbids section titles inside indented content regardless of underline character. These come
from verbatim AI prompts pasted with indentation.

**Why fixing is hard.** (1) Llogs are append-only --- any fix is a retroactive exception to
that rule, and would fall under the TELES contract. (2) The 70 heading-char errors are
mechanical; ``sa3_2026m03d28/llog.rst`` is the cleanest target, all 42 of its errors being
this type. (3) The 84 structural errors need one of: un-indenting headings (changes document
structure and may break verbatim prompt flow), wrapping in ``.. code-block:: text`` (changes
rendering to monospace), or replacing underlines with bold ``**Heading**`` (changes
appearance, avoids the parser issue). (4) The 4 files total ~20,000 lines.

**Suppression is not clean.** Sphinx has no ``suppress_warnings`` tag for these CRITICAL
types. ``-Q`` hides everything including real issues.

.. note::

   **Already fixed separately on 2026m04d01**, recorded here so nobody re-hunts them: a
   missing include at ``source/index.rst:228``
   (``/_templates/include-file/matheology-call.rst``, commented out), and undefined
   substitutions ``|beta|``, ``|R|``, ``|Z|``, ``|leq|`` in 3 llog files, which were math
   notation RST read as substitution references --- fixed by escaping (``\|beta\|``).


Detail 3 --- RFC 5321 FF slug-length limit
============================================

**Problem.** RFC 5321 §4.5.3.1.1 limits email local parts to 64 octets. With the ``FF+``
prefix, FF page slugs can be at most **61 characters**. Many llog filenames exceed this ---
the longest is 101 --- so full path-based slugs cannot serve as email addresses.

**Workaround in place** (2026m03d31): slugs ≤ 61 chars use the full path-based slug; longer
ones use ``slug[:50] + "_" + md5(full_slug)[:10]`` (exactly 61 chars); all abbreviated slugs
are registered in ``AHA/ff-slug-index.md``; and the full source path is always included in
the email **body** regardless of slug length.

**Proper fix**, when programmatic slug generation becomes feasible (build script or Sphinx
extension): auto-generate abbreviated slugs during ``make html``; auto-populate or auto-check
the slug index; possibly emit a reverse-lookup JSON for email processing; consider a shorter
hash (6 chars may suffice once collision statistics are known); and check whether Google
Workspace ``+`` notation imposes practical limits beyond RFC 5321.

**Scope.** ~40 llog files in the repo. **All** llogs exceed 61 chars on full path-based slugs
(72--101); non-llog pages are typically 5--30 chars and unaffected.

**References.** ``AHA/ff-slug-index.md`` (registry), ``AHA/feedbackflow.md`` (FF overview),
``source/ff/system/index.rst`` (FF system design).


See also
==========

- :doc:`/_post/aa/index` --- POST AA registry (parent), and the placement rule
- :doc:`/_post/aa/b/18/b18-build-warning-gating-and-link-guards` --- warning gating; task 2
  above is a precondition for it
- ``AHA/aa-anyaims-sorting.md`` --- which AA file lives where, and why