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#

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 POST AA b18 — 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:

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

As measured 2026m04d01 — paths are PRE-HELL-migration, re-measure first#
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).

POST AA b21: deferred build and site tasks#

Task list#

Detail 1 — browsable full-page sitemap tree#

Detail 2 — the 154 CRITICAL llog heading errors#

Detail 3 — RFC 5321 FF slug-length limit#

See also#