Site redesign: build spec

Goal (Dennis, 2026-10-13): one simple, intuitive site. One nav, one page per machine, one machines table. Old URLs may break. The CLI commands keep their arguments. No information is lost: it moves.

Everything stays static HTML, written by stdlib Python with atomic writes, using relative links and no external requests. tools/serve.py stays exactly as it is.

0. Facts the spec is built on (2026-10-13)

• 64 machine directories: 31 kills, 1 active, 1 waiting, 31 parked (8 of them cryptid candidates). 678 machines on the list are untouched.
• 54 directories have an observe.json, so 54 have a card.html. The other 10 are delta machines with a status.json parent: 8 kills (#24, #25, #11b, #12b, W4-3b, W4-3c, W5-8b, W5-8c) and 2 that are not killed (#32, a cryptid; #23, stuck).
• There are 30 kill.html pages. W5-4 has none, because rebuild_pages.sh never runs killreview. The new rebuild closes this gap.
• PRs: #14, #15 and #16 are merged; #17 and #18 are open. dashboard.build_records() already groups kills per PR in meta["prs"].
• Package folders: submission/family/ (#15, #16, #17), submission/pr/ (#18), and for #14 the older form submission/discord.md + submission/discord/. Each package holds pr_title.txt, pr_body.md, discord.txt (with placeholders), discord_dennis.txt (links filled in), attachments/*_writeup.md, images/*_spacetime_{10k,1e9}.png, and optionally forum/*.txt and names.txt.
• All 18 decision.json files are answered, so the nav count is 0 today.
• Cost: build_records() takes 3.0 s, of which 2.8 s is guess_class. With a 5-line list it takes 0.4 s. killreview.Ctx() takes 0.4 s, one killreview.build 0.13 s, one card.render_card 0.02 s.
• Test baseline: test_card 26/26, test_dashboard 26/26 and test_decisions 18/18 are OK. test_killreview has 1 failure, test_automatic_checks: W4-3c has "coqchk finished" not met. That is a data fact, not a page bug, and it stays out of scope.

1. Pages and URLs

Unchanged outputs: dashboard/data.json, dashboard/kills.json, dashboard/thumbs/, dashboard/screens/.

Removed outputs: every machines/<tm>/card.html, every machines/<tm>/kill.html, machines/index.html and machines/kills.html (§6).

The machine page sits in the same folder as card.html and kill.html did. Every relative link those fragments produce (proof.md, img/x.png, submission/…, <tm>.v) therefore stays valid as it is.

2. Shared module tools/site.py

site.py has no top-level imports of card, dashboard or killreview. Any loader that needs them imports them inside the function, so card.py can import site.py without a cycle.

3. Each page: sections and their sources

3.1 Machine page: tools/machinepage.py (new)

render(repo, tm, vsmode="cache") -> (html, info) and build(repo, tm, vsmode) -> Path. The page works for every machine directory, with or without observe.json.

There are two refactors, and both keep the old functions' output byte-for-byte identical:

• card.card_parts(obs, mdir, prefix="") returns {rank_txt, class_html, state, state_html, howp, intro, look, folds, warns, plan}. It is the body of render_card cut at its existing comments (header, intro, look, folds, footer warnings). prefix is threaded through resolve(), figure_html, other_viewers, stats_html and the discord src, so a delta page can show the parent's figures with ../<parent>/img/…. render_card is deleted.
• killreview.build_parts(ctx, tm, vsmode, ns="p") returns {secs: [(sid, title, check, body)], verdict_html, summary, hp}. It is the body of build() before # ---- page. figure() takes ns, which gives ids pfig-N and labels Fig P1, P2…, so they never clash with the card's fig-N. Section 5 ("Mechanism pictures") is dropped from secs: its standard picture moves to the Overview and its card figures to Mechanism. Its check line moves under the Mechanism heading. In-body links change: ../<o>/kill.html becomes ../<o>/index.html#proof, ../<o>/kill.html#same becomes ../<o>/index.html#same, ../<o>/card.html becomes ../<o>/index.html#mechanism, and card.html#q- becomes #q-. card_ref() is replaced by mechanism_ref(), which returns the own page, else the first parent that has an observe.json. build(ctx, tm, vsmode) -> (proof_fragment_html, summary) keeps its name for the tests.

Page layout: the nav, then <header class="mh">, then four <section class="mp" id=…> blocks, then the footer. A jump row under the header links Overview · Mechanism · Proof & checks · Files; it is not sticky, so the card's sticky checkpoint column is unaffected.

CSS is card.CSS + K.CSS_EXTRA + a small mp- block (header, two-column overview, jump row). JS is card.JS; killreview's "no JS" rule still holds for the Proof & checks fragment itself.

3.2 Home: dashboard.render_home(repo), replacing render_page

3.3 Machines: dashboard.render_machines(repo)

Header: "64 machine folders", the status chips per live status (from the old cards index header), the thumbnail label, and a folded "How to read this table" with the kills index's "What to check here" text and its colour key.

Filter bar: dashboard's #bar, reused. Search, bucket chips (the 7 + untouched), the class menu with counts, sort, and "n of N shown". DASH_JS is generalised: items are [data-tm], groups tbody[data-b] / .minis, families tbody.fam. With a sort other than the default, rows render flat and the group headers hide; switching back restores data-o. A #b-X hash on load selects bucket X. Without JS the whole table shows, grouped.

The table has one <tbody data-b=…> per bucket, in the order of §2. Kill buckets have one <tbody class="fam"> per family. The family header comes from ctx.family(): "Family of #3 · class · 4 killed, 1 not; not killed: line 604 (untouched), …". Today's grouping ran within buckets on the dashboard and across buckets in kills.html. Now members that sit in another bucket are named as "also #3b in Accepted". Rows carry D._data_attrs(rec, order).

At 760 px and below each row becomes a card (CSS grid on tr/td): picture, then machine, state and now. Proof, related, changed and flags shrink to one small line. Nothing scrolls sideways.

Below the table: <details id="untouched">, "Not started: 678 holdouts on the list with no folder". Inside is the old Untouched grid unchanged (D.tile_mini, the tier ordering and its key line, content-visibility:auto). The filters apply to it, and pressing the untouched chip opens it.

The footer keeps the dashboard's data-sources list (list files, sheet, buckets, PR sync, kill numbers, same table, flags, off-list reasons) word for word.

Dropped on purpose: the "no card" and "card stale" flags (every page is rebuilt together now), and the cards index's Fig 1 thumbnails (Fig 1 is the top of Mechanism; the table uses the uniform standard picture).

3.4 Submissions: tools/submissions.py (new), render(repo)

• #pr-<n> cards, newest PR first, one per entry in repo.prs:
• State chip (D.pr_chip), opened, merged at/by, comments (highlighted when > 0), title (pr_title.txt).
• Machines: name_html + kill N + upstream file (names.txt column 2, else status.json pr_file) + links to .v/proof.md with view + ?download.
• Discord: posted / not posted (status.json posted); the text in a <pre> with a copy button. Text priority: discord_dennis.txt, then discord.txt, then the ```text blocks of submission/discord.md (+ submission/discord/part2.txt), with a link to the placeholder version.
• Forum posts (forum/*.txt, folded, copy).
• PR body (pr_body.md view + ?download).
• Write-ups (attachments/*_writeup.md, else submission/discord/*_writeup.md: view + ?download).
• Pictures (images/*.png: a small preview + ?download).
• Checks: n/7, and the write-up lint from kill_summaries.
• Package lookup find_package(pr): for each machine of the PR, the first of submission/pr/, submission/family/ that has pr_title.txt or discord*.txt. Failing that, the legacy pair submission/discord.md + submission/discord/. Read-only.
• #ready, "Ready to submit": claimed kills by family (as on Machines), each with submission/README.md, the discord.md draft (copy), the write-up (submission/proof.md + ?download), .v, n/7 and the write-up lint. Plus D.kill_key("claimed").
• A PR closed unmerged (if one ever exists) gets its own card, in red.

3.5 Decisions: decisions.py, changes only

• render_page uses site.page(active="decisions"); the old header links (dashboard · cards index · kills) go away.
• The open_n in the header comes from site.open_decisions, with unreadable files counted and said so.
• Rank comes from site.Names.label.
• The thumbnail and the "card or folder" links point to machines/<tm>/index.html.
• figure_ev_html/link_href: card.html#fig-N and #fig-N resolve to …/index.html#fig-N (has_card becomes "has observe.json").
• Each article gets an inner <span id="tm-<tm>"></span>.
• The form, the sticky footer, STORE_KEY and the copied text stay unchanged.

3.6 Reports: tools/reports.py (new), render(repo)

• REPORTS registry: 1. "Latest report": the newest reports/overnight-20*.md (not -plan, not -ledger). 2. "How we proved them": reports/how-proved.md. 3. "Wave rankings": reports/wave*/ranking.md, newest first. 4. "Landscape": reports/landscape.md. 5. "Targeting": reports/targeting.md. 6. "Project status": STATUS.md, PLAN.md.
• Each entry: the first # heading as its title, the first paragraph (≤ 200 chars) as its description, mtime and size, a link to the .md (serve.py renders it), and ?raw.
• Folded "More notes": every other reports/**/*.md (checkpoint-A-batch1, family-sweep, holdouts-740-impact, kill-forensics, discord-drafts, overnight-plan-, phase0_compile, forensics/.md, site-redesign.md).
• Never listed: *.log, *.tsv, overnight-ledger.md (Home shows its tail), the screenshot folders.
• serve.py's rendered .md pages have no site nav. The browser's Back button covers that, and serve.py stays untouched.

4. CLI mapping (same arguments, new outputs)

New tools/rebuild_pages.sh, which rebuilds everything when any input changed:

#!/bin/bash
# tools/rebuild_pages.sh: rebuild the whole site when anything it is built from changed (bb6-pages timer, every 5 min).
cd [local working file] || exit 1
exec 9>dashboard/.rebuild.lock; flock -n 9 || exit 0        # one build at a time
stamp=dashboard/.built                                      # dot-file: serve.py never serves it
changed() {
  find machines -maxdepth 5 -type f -newer "$stamp" ! -name index.html ! -name 'vs-parent*' ! -path '*/__pycache__/*' -print -quit
  find reports -maxdepth 2 -name '*.md' -newer "$stamp" -print -quit
  find data/holdouts tools -maxdepth 1 -type f \( -name '*.py' -o -name '*.txt' \) -newer "$stamp" -print -quit
}
if [ ! -f "$stamp" ] || [ ! -f dashboard/index.html ] || [ -n "$(changed)" ]; then
  touch dashboard/.built.new                              # changes made during the build trigger the next run
  nice -n 10 python3 -B tools/site.py >/dev/null && mv dashboard/.built.new "$stamp"
fi

The excluded names are what the build itself writes; without the exclusions every run would trigger the next. The rebuild costs about 15 s niced: build_records 3 s, 64 pages ≈ 5 s, then the rest. vsmode="fill" computes a new derived kill's comparison once (≈ 7 s) and caches it.

5. Code removed with the old pages

• card.py: render_card, card_path, build_card, render_index, build_index, INDEX_CSS, _rank_key, GROUP_ORDER/GROUP_HEAD, plus page() (now site.page).
• killreview.py: build_index, the page assembly in build(), card_ref.
• dashboard.py:
• Removed: render_page, _cards_index_link, tile_big, the kill-section and family block code, kill.html in REVIEW_GLOBS, and the card/parent_card flags.
• Kept: kill_key and fam_blocks, only if used.
• machine_state gains open_q (it already has has_observe, which replaces card); WORK_SKIP keeps index.html, card.html and kill.html.
• Everything that is reused stays: chips, class_html, meta_html, table_*, pr_*, ask_html, via_html, tile_mini, thumb_*, TIME_JS, DASH_JS (generalised), DASH_CSS.

6. Deletion: what and when

1. After the machine pages are built for all 64 folders and the link check passes (§7, test_site 3), run a one-time inventory script. It is a scratchpad script, not shipped. It pulls the visible facts from today's pages: chips, kr-sub, howp-tag, kr-verdict, figcaptions, summary, kr-tab cells, tsum/kf/kpr lines. It checks that each fact appears in the new page that took over that content, and it prints any misses for a fix round. Old copies go to the scratchpad for the headless review comparison.
2. Then delete, in the integration step: bash rm machines/*/card.html machines/*/kill.html machines/index.html machines/kills.html That is 54 + 30 + 2 files. Nothing else in machines/ is touched: review.html, compare.html, the img/vs-parent caches and all data stay.
3. Rewrite links once in human reports (not machine data), using sed on paths only: - reports/how-proved.md (18 links), reports/overnight-2026-10-10.md (Links section) and STATUS.md: machines/<tm>/card.html becomes machines/<tm>/index.html#mechanism, kill.html becomes index.html#proof, and machines/kills.html / machines/index.html become dashboard/machines.html. - overnight-ledger.md is history and is not rewritten. - The card.html links in machines/*/notes.md and decision.json files stay as they are (data files). decisions.py maps the figure ones.
4. Update the docs in the same step: README-card.md, README-killreview.md, README-dashboard.md, README-decisions.md (their page sections now point to §3 of the new pages), a new short README-site.md (nav, names, Repo, CLI table, rebuild), and the root ROOT_INDEX links.

7. Tests

Run with python3 -B tools/test_<x>.py. The headless parts use CLAUDE.md's playwright-core + chromium + .syslibs, never Dennis's desktop.

test_card.py (26). Every fragment test stays as it is. They render through machinepage.render(Repo(tmp, list_path=tmp_list), tm), or through card.card_parts for the purely fragment-level ones.

• test_full_card: the same assertions, split across the two sections. The header line, state line, How box, one sentence and folded notes are in #overview. Primary figures, label cells, Q backlinks, checkpoint tags, see Fig 2, "n open" and the six closed folds with their summaries are in #mechanism. The order is Overview, then Mechanism.
• test_how_proved: the box sits under the state line and above "In one sentence", appears exactly once on the page, and only for KILLED_* or a pr. The "card stale" assertion is replaced by a check that rebuild_pages.sh's changed() lists a touched how_proved.md (a shell-level test with a temp stamp).
• test_index / test_index_empty become Machines page tests: one row per folder; a broken observe.json becomes a row with the flag "observe.json unreadable"; question objects are counted; the empty tree says "no machine folders".
• test_cli: card.py <tm> writes only <tm>/index.html (no card.html); --lint still exits 1 on a missing label field while rendering succeeds; --index writes <out>/machines.html; a folder without observe.json builds with exit 0.
• test_no_js_static, test_links_resolve and the anchor checks (check_anchors: every # link has a target, ids unique) run on the full page, including a killed fixture with Proof & checks (pfig-N vs fig-N).
• test_browser_no_js: the same checks on the machine page (images load, no external requests, no console errors, no overflow at 390 px, Fig 4 opens "More figures", the zoom view).
• RealCards: every real folder, all 64 including the 10 without observe.json, renders in memory.

test_dashboard.py (26). Inputs, Guess, Tables, Machines, Submission and Ledger are unchanged (build_records logic).

• test_counts_and_thumbs: the Home tiles, with 7 buckets plus untouched; cryptid equals parked-with-CRYPTID_CANDIDATE.
• test_static_page: Home + Machines without JS. Every folder has a row, the untouched grid is present, and the filter bar is hidden.
• test_hostile_strings and RealPage: run on Home + Machines.
• The how-proved.md header link assertion (line 483) moves to the Reports test.
• Browser: the Machines filters (search #3, line 604, a bucket chip, the class menu, #b-parked on load); Home at 390 px with no overflow; the nav menu collapsed at 390 px.

test_killreview.py (27). Parse, Compare, Markdown and SameMachine are unchanged.

• Pages.test_sections: on the fragment from K.build(), "What to check here:" appears 7 times if derived, else 6 (s5 dropped). id="same" only on derived kills. There is no <script in the fragment, no external src, and no absolute links.
• test_index* become the Machines page family groups: one tbody.fam per family, non-killed members named, sub_chip per kill row, the header tally in Home's tiles.
• test_how_proved_box: on the machine page Overview; a derived kill shows its own file, never the parent's.
• test_parent_links_same_section: the family table links ../<child>/index.html#same.
• test_automatic_checks: unchanged. W4-3c's coqchk miss is the known data failure.

test_decisions.py (18). Unchanged except: - Links go to machines/<tm>/index.html (#fig-N for figures). - The nav is present, with a count equal to unanswered + unreadable decision.json in the fixture tree. - #tm-<tm> anchors exist and are unique.

New tools/test_site.py.

1. Nav: Home, Machines, Submissions, Decisions, Reports and three machine pages each have one nav.sn with the six links in order, aria-current on the right one, both link lists identical, and N = the fixture's open decisions (2 open + 1 unreadable + 1 answered → 3).
2. Names: the precedence table of §2 (rank > label > twin > 740 line > 778 line > off-list) and the alias tooltip. On real data Names.label == D.member_name == Ctx.name for every folder. A fixture machine's tag reads the same on all six page types.
3. Link check: crawl the temp build (and, in integration, the real one). Every relative href/src resolves on disk, with ?download/?raw stripped and #frag checked against the target's ids. Nothing links to card.html, kill.html, kills.html or machines/index.html.
4. Machine page kinds: a kill with observe.json; a delta kill without (Mechanism images are ../<parent>/img/… and exist; #same sits in Proof & checks; the How box is its own); a cryptid (state "Parked", no kill sections, "Calls on file" shows parked); a broken observe.json (the page renders, with a banner).
5. Submissions: fixture packages in family/, pr/ and legacy discord.md give one card per PR, highest number first, with discord_dennis.txt preferred. Download links carry ?download and resolve. "Not posted" shows when posted is missing. #ready lists the claimed kills by family.
6. Reports: the curated order, with the newest overnight report first; titles come from # headings; no .log/.tsv/ledger links.
7. Home: the tiles sum to the folder count; needs-you lists the open decisions, the waiting ask, a PR with comments > 0 and an unposted open PR; recent events are sorted newest first, all within 4 days.
8. CLI: on temp trees each command of §4 writes exactly its files, and none writes card.html or kill.html.
9. Headless, over every page type at 1280 and 390 px, light and dark: no horizontal overflow, an explicit body background, no console errors, no external requests, all images load, and the nav menu opens at 390 px.

8. Build order (file ownership, so steps can run in parallel)

Done means: all suites green apart from the known W4-3c data failure; the link check is clean on the real build; the inventory script reports 0 misses; rebuild_pages.sh run twice in a row rebuilds once, then exits as a no-op.