#343: Guided Tour numbering + wording, and fix stale Explorer prose figures

[rdhyee]

#343 — Guided Tour numbering and wording

Eric reported that the tour's headings render as "1 Stop 1 —", "2 Stop 2 —" and so on. Confirmed: the site sets number-sections globally, and the headings already carried a hand-written "Stop N", so the number appeared twice.

Both changes as requested:

• number-sections: false for this page only. The step numbers are written by hand because the numbering is part of the tour's voice, so the automatic numbering is what gets removed — not the manual one.
• "Stop" → "Step" in all seven headings, plus the three prose references, so the page doesn't say "steps" in the titles and "stops" in the body.

Verified on staging: headings now read Step 1 — … through Step 7 — …, no duplicate numbering.

Coherence-audit follow-up — the "How This Demo Works" figures were a generation stale

The size table asserted figures that no longer matched anything published. Corrected against the release manifest, with cluster counts verified independently against the parquet row counts (38,462 / 112,019 / 176,669 — the manifest doesn't carry row counts).

The interesting part is why they were wrong, because the obvious fix was the wrong one. The old figures (580 KB / 1.6 MB / 2.5 MB) are correct — for the 202601 snapshot, which SERIALIZATIONS.md, how-to-use.qmd, data.qmd and tutorials/why_h3.qmd still legitimately document. This page describes the live app, which serves 202608, so it had silently drifted one release behind.

I checked those four other files against the live 202601 objects (594,541 / 1,627,502 / 2,543,412 bytes) and they're accurate, so they are deliberately untouched. Worth internalising: a "wrong number" in this repo may be a right number for a different release — check which snapshot a doc describes before correcting it.

Also:

• Dropped the "4 parquet files" claim, which was simply false. The published release is 21 objects (18 parquet + 3 JSON search-index files), and the boot manifest check enumerates them. Replaced with the real figure plus a pointer to isamples_202608_release_manifest.json and CANONICAL.md as the authoritative inventory.
• Added a collapsed "check these numbers against the source" callout with the curl/jq and SQL one-liners to re-derive every figure — so the next reader doesn't have to trust the page.
• Units are now consistently decimal MB. The old row silently mixed conventions (580 KB was KiB while 1.6/2.5 MB were decimal), which is part of why it read as internally consistent while being stale.

Verification

Check	Result
quarto render both pages	clean
tests/test_smoke.py (local and staging)	PASS
tests/test_frontend_derived.py	40 passed
#341/#342 count behavior unaffected	search → 60/60 dashes, 0 stuck; facet-only → real counts
pageerrors	none
Staging headings	Step 1 … Step 7, no duplicate numbering

Scope note

I drafted a live OJS cell that fetched the manifest and rendered the true sizes on the page, then removed it. explorer.qmd is the most fragile file in the repo, I broke it once already this week with a bad OJS declaration, and adding a boot-time network fetch there is not a documentation fix. The static callout with re-derivation commands gets the same honesty at none of the risk.

Refs #343

🤖 Generated with Claude Code

https://claude.ai/code/session_01QCCDurpcLzMe7L72y2HDAa

[rdhyee]

🤖 rbotyee (Claude, operated by @rdhyee) — Raymond's intent: "if it's CC+Codex LGTM and it looks good on rdhyee, merge it." What I did: ran the Codex review loop to convergence (six rounds), verified on the fork's staging deploy, and am recording the verdict here before merging.

Codex verdict — round 6

LGTM — no blocking findings.

The three must-fix items are correctly resolved in the real files, commit d44a642 is clean and limited to the nine expected files, and git diff --check passes. I independently reran tests/test_frontend_derived.py: 40 passed.

The smoke test could not launch Chromium in this sandbox due macOS Mach-port permissions; that is an environment failure, not a branch regression. Your successful smoke test and full render cover that gap.

Safe to merge.

What the review loop actually caught

Worth recording, because this started as a two-line heading fix and Codex blocked it five times:

Round	Blocked on
1	"21 objects" undercounted the release (excluded 847 search shards); a 60 MB/63 MB binary-vs-decimal straggler; "every figure comes from the manifest" was false (cluster counts come from parquet rows)
2	Four more stale strings my grep missed, incl. a comment naming sample_facets_v2 and two calling the facets parquet 63 MB when that's map_lite's size
3	My query-spec.qmd drift banner understated the problem and was itself partly wrong; DATA_PROVENANCE.md and EXPLORER_STATE.md needed labeling
4	Six main-navbar pages presenting 202601 artifacts as current Explorer inputs
5	The banners claimed pages "pin 202601" when they actually mix generations; the provenance caveat was incomplete about its own incompleteness
6	— LGTM

The most useful catch was conceptual rather than textual: the old figures weren't invented — they were correct for the 202601 snapshot. Only explorer.qmd was genuinely wrong, because it describes the live app, which serves 202608. Four other docs quoting 202601 bytes were verified accurate and deliberately left alone. That's now written into the code comment so the next person doesn't "fix" correct numbers.

Verified on staging (rdhyee.github.io)

• Guided Tour headings render Step 1 … Step 7, no duplicate numbering
• Explorer prose: 0.5 MB, 63 MB lite parquet, "Static files, zero backend", "every file-size figure"
• Snapshot banners present on the labeled pages
• tests/test_smoke.py passes against staging; full 55-page render clean

Deliberately deferred (Codex's own follow-up list, not blocking)

Full refresh of DATA_PROVENANCE.md / SERIALIZATIONS.md / query-spec.qmd; rewriting the instructional tables around 202608; splitting the docs into "current release" vs "archival snapshot" sections. All are labeled in-place rather than silently left wrong.