feat(samples): publish ntt-fpga self-improvement history incl. CFNTT-KRED redesign

The ntt-fpga detail page now tells the whole story step by step (web
profile, 1.7 MB, 30 runs): 24 visual self-improve runs, the formal-
verification epoch (incl. the hand-authored 17-check z3 suite run,
pass=true), and the two CFNTT-KRED redesign iterations (85 -> 90 -> 94)
whose critiques document the verified 1-multiplier butterfly + issue-#7
fix. examples/ntt-fpga/notes.md gains the improvement-arc learnings so the
evidence seed stays in sync; CLAUDE.md documents the --web profile.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: grandchildrice

CLAUDE.md

@@ -79,7 +79,8 @@ When converting/adding a CLI file: write `.ts`, add its generated `.js` to
   best-scene ratchet.
 - `lib/upload.ts` — `visually upload <id>`: publish a scene into the WEB GALLERY
   `public/samples/` (what the site serves: `<id>.json` + `index.json` entry +
-  `runs/<id>/` history; full as-is, `--scrub` for the lean set). ONE verb that
+  `runs/<id>/` history; full as-is, `--scrub` for the lean set, `--web` for only
+  what the detail page's self-improvement timeline renders + its `manifest.json`). ONE verb that
   branches on `isRepoCheckout()` (does `PKG_ROOT` have a `.git`?): **repo checkout
   (dev/bun)** → write public/samples + commit those paths + `git push origin
   <branch>` (`--no-push`/`--dry-run` available); **installed (npx/npm)** →

examples/ntt-fpga/notes.md

@@ -52,3 +52,24 @@ verify. Record them in the spec as documentary `[src]` facts, but treat their
 - `amend` must never fabricate a `[source-missing]` value; gather evidence first.
 - Resource/timing claims need a different backend (RTL synthesis) — until then,
   reproducibility, not fidelity-on-hardware-claims, is the axis that can move.
+
+## The improvement arc (v24+, 2026-07): CFNTT-KRED — verified redesign
+The formal-verification epoch (source-grounded z3 + Yosys/SymbiYosys, see
+NyxFoundation/ntt-fpga-z3) found the released radix-2 RTL omits the per-stage
+INTT halving (`modular_half.v` shipped but instantiated nowhere → INTT output
+scaled 2^10; upstream issue #7), and that the Barrett multiplier spends THREE
+hardware multipliers where q = 12289 = 3*2^12+1 (Proth) needs ONE:
+- K-RED reduction (3*2^12 ≡ −1 mod q): two shift-add folds + one conditional
+  subtraction reduce the 28-bit product; unit returns 9ab mod q.
+- Fold the 9 away in the ROM (store W = 9^-1·w); the INTT twiddle is
+  op21(W) = (2·9)^-1·w derived from the SAME ROM word — which fuses the
+  multiply-path halving, fixing issue #7 at zero multiplier cost. Add path
+  gets one op21 gate. PWM double-passes the unit with the constant 81^-1.
+- Gains: multipliers/butterfly 3→1 (DSP −67%), mult −21% cells, butterfly
+  −10% cells while ADDING the fix. Same ports/latency — drop-in.
+- All machine-checked: z3 full-domain (divider-free linear congruence
+  identities — URem/`%` goldens DIVERGE in solvers, restate congruences as
+  nonneg linear identities), SymbiYosys compositional proofs (leaf-unit
+  equivalences justify behavioural abstractions), bit-exact e2e polymult,
+  mutation probes. The improvement history is published on this scene's
+  gallery page (public/samples/runs/ntt-fpga/, `--web` profile).

public/samples/runs/ntt-fpga/improve-20260617-175805/iter-01-render.png

@@ -0,0 +1,27 @@
+{
+  "scores": {
+    "recognizability": 8,
+    "internal_legibility": 17,
+    "structural_decomposition": 13,
+    "buildability": 16,
+    "geometric_fidelity": 12,
+    "proportional_accuracy": 8,
+    "annotation_depth": 5,
+    "self_consistency": 5
+  },
+  "total": 84,
+  "verdict": "improve",
+  "critique": "In the ISO render the 16x12 board is an oversized flat slab (bounds.radius ~10, over the ~9 limit) so the floorplan reads as a dark featureless plate with low parts crouching on it; the TOP view is the only legible angle. The four butterfly clusters used a single opaque 'housing' box per cluster — a build-test failure because the paper's whole point is the symmetric add/sub operators and the DSP multiplier, which were collapsed into one ALU box rather than modeled as distinct members. The conflict-free schedule controller (the central algorithmic contribution) was missing entirely, and primitives were almost all boxes.",
+  "changelog": [
+    "Shrank board to 14x0.4x9 (bounds.radius 10 -> 8.3) and re-pitched all eight BRAM banks to fit, fixing the proportional violation",
+    "Replaced each opaque butterfly 'housing' with a thin open baseplate so internals are fully exposed in ISO (X-ray test)",
+    "Split every butterfly cluster into four real members — DSP modular multiplier, symmetric modular adder, symmetric modular subtractor, and a pipeline register — modeled 4x with distinct ids",
+    "Added the Conflict-Free Schedule/FSM Controller (the loop-reordering contribution) on the right cluster",
+    "Raised component heights and tightened the connection graph into a clean assembly order rooted at the PCB"
+  ],
+  "remaining_gaps": [
+    "Add an exploded copy of one butterfly cluster floating ~2.5 m above the board to make the radix-4 datapath unmistakable from ISO",
+    "Add an FPGA die/package outline plus a heatsink so the silhouette reads instantly as an FPGA accelerator, not a generic PCB",
+    "Differentiate a forward-NTT vs inverse-NTT (INTT) annotation/path and vary primitives further (e.g. capsule pipeline FIFOs) for the geometry axis"
+  ]
+}

public/samples/runs/ntt-fpga/improve-20260617-175805/iter-01-review.json

@@ -0,0 +1,27 @@
+{
+  "scores": {
+    "recognizability": 9,
+    "internal_legibility": 19,
+    "structural_decomposition": 14,
+    "buildability": 18,
+    "geometric_fidelity": 13,
+    "proportional_accuracy": 9,
+    "annotation_depth": 5,
+    "self_consistency": 5
+  },
+  "total": 92,
+  "verdict": "improve",
+  "critique": "The TOP view is now genuinely legible — eight blue BRAM banks, four butterfly clusters with copper DSP multipliers and grey symmetric add/sub pairs, the reduction spine, twiddle ROM and controllers all read cleanly. But in ISO the scene still reads as a generic populated PCB, not an FPGA accelerator: there is no silicon-die outline and no heatsink, the previous iteration's top two gaps. The paper's headline contribution — the radix-4 butterfly datapath — is legible only in plan; an orbiting viewer cannot see the multiply->add/sub->register flow from ISO because every cluster lies flat. There is also no distinct inverse-NTT element, so forward and inverse passes are indistinguishable.",
+  "changelog": [
+    "Added an exploded radix-4 butterfly cluster floating directly above cluster 1 (ex_base/ex_mult/ex_add/ex_sub/ex_reg) so the DSP-multiply -> symmetric add/sub -> pipeline-register datapath is unmistakable from the ISO render",
+    "Added an FPGA silicon-die outline plate (fpga_die) framing the floorplan plus an exploded aluminum heatsink (heatsink_base + 3 distinct fins) above the package so the silhouette reads as an FPGA accelerator",
+    "Added a dedicated inverse-NTT N^-1 scaling unit (intt_scale) on the output side and re-annotated the input FIFO as the forward-NTT path, differentiating NTT vs INTT",
+    "Varied primitives: converted both FIFOs from boxes to Z-axis capsules; kept DSP multipliers and PLL as cylinders",
+    "Updated assembly_instructions and the connection graph to include the die, heatsink, INTT unit and exploded view"
+  ],
+  "remaining_gaps": [
+    "The exploded butterfly cluster and heatsink necessarily float in the FRONT/SIDE elevations; consider faint riser stubs or a die-frame rail set to make the exploded relationship unambiguous and recover the last ~2 geometry points",
+    "Model the second four butterfly units (paper uses up to 8) as a mirrored array, or add a clear '4 of 8 modeled' ghost, to fully match the benchmark configuration",
+    "Differentiate Barrett vs Montgomery internals inside the reduction spine (currently one tall box) by splitting it into a multiplier + shift/subtract member to remove the last near-opaque block"
+  ]
+}

public/samples/runs/ntt-fpga/improve-20260617-175805/iter-02-render.png

@@ -0,0 +1,27 @@
+{
+  "scores": {
+    "recognizability": 9,
+    "internal_legibility": 20,
+    "structural_decomposition": 14,
+    "buildability": 18,
+    "geometric_fidelity": 14,
+    "proportional_accuracy": 9,
+    "annotation_depth": 5,
+    "self_consistency": 5
+  },
+  "total": 94,
+  "verdict": "improve",
+  "critique": "The render now reads clearly as an FPGA accelerator: the FRONT view shows the exploded heatsink fins above the package, the TOP view is fully legible with eight blue BRAM banks, copper DSP multipliers, the symmetric add/sub clusters, the reduction spine and the right-edge controllers, and the ISO exploded butterfly cluster makes the radix-4 datapath orbit-visible. Two carried-over defects survived this render: the shared modular-reduction unit is still one tall welded-steel wall (a near-opaque block hiding its Barrett internals), and the exploded butterfly cluster and heatsink float free in the FRONT/SIDE elevations with no visible riser, so the exploded relationship is ambiguous. Only 4 of the benchmark's 8 butterfly units are modeled, so the array still under-represents the headline parallel configuration.",
+  "changelog": [
+    "Split the single opaque modular_reduction_unit wall into two adjacent thinner members — a Barrett q-multiplier (mod_red_mult) and a shift/subtract+conditional-correction member (mod_red_subshift) — removing the last near-opaque block and exposing the reduction internals (closes carried-over gap 3)",
+    "Added two thin brushed-steel riser posts (ex_riser_a/ex_riser_b) physically linking the exploded butterfly cluster baseplate to its source baseplate bu_base_1, so the exploded relationship is unambiguous in the FRONT/SIDE elevations (closes carried-over gap 1, exploded cluster)",
+    "Added a heatsink riser stub (heatsink_riser) from the silicon die up to the heatsink baseplate so the lifted heatsink is grounded to the package in elevation (closes carried-over gap 1, heatsink)",
+    "Rewired the datapath so each pipeline register feeds mod_red_mult, mod_red_mult feeds mod_red_subshift, and mod_red_subshift returns to the crossbar — a legible reduction assembly order",
+    "Updated assembly_instructions, pcb_substrate/crossbar connection lists, and the facts note to reflect the split reduction unit and riser supports"
+  ],
+  "remaining_gaps": [
+    "Model the remaining four butterfly units (paper benchmarks 8 parallel BUs) as a second mirrored cluster array — e.g. interleave 8 narrower clusters across the 9 m depth or stack a second row — to match the headline configuration and recover ~2 structural/proportional points; the current scene still only shows 4 of 8",
+    "The two reduction members (mod_red_mult, mod_red_subshift) are still abstract boxes; consider giving the Barrett multiplier a cylindrical DSP silhouette to distinguish it from the subtract member at a glance",
+    "Add a faint dashed/ghost connector or arrow geometry from each pipeline register into the crossbar to make the operand-return path readable in ISO, not just inferable from the connection graph"
+  ]
+}

public/samples/runs/ntt-fpga/improve-20260617-175805/iter-02-review.json

@@ -0,0 +1,27 @@
+{
+  "scores": {
+    "recognizability": 9,
+    "internal_legibility": 20,
+    "structural_decomposition": 14,
+    "buildability": 18,
+    "geometric_fidelity": 14,
+    "proportional_accuracy": 9,
+    "annotation_depth": 5,
+    "self_consistency": 5
+  },
+  "total": 94,
+  "verdict": "improve",
+  "critique": "The render now reads clearly as an FPGA accelerator: the FRONT view shows the exploded heatsink fins above the package, the TOP view is fully legible with eight blue BRAM banks, copper DSP multipliers, the symmetric add/sub clusters, the reduction spine and the right-edge controllers, and the ISO exploded butterfly cluster makes the radix-4 datapath orbit-visible. Two carried-over defects survived this render: the shared modular-reduction unit is still one tall welded-steel wall (a near-opaque block hiding its Barrett internals), and the exploded butterfly cluster and heatsink float free in the FRONT/SIDE elevations with no visible riser, so the exploded relationship is ambiguous. Only 4 of the benchmark's 8 butterfly units are modeled, so the array still under-represents the headline parallel configuration.",
+  "changelog": [
+    "Split the single opaque modular_reduction_unit wall into two adjacent thinner members — a Barrett q-multiplier (mod_red_mult) and a shift/subtract+conditional-correction member (mod_red_subshift) — removing the last near-opaque block and exposing the reduction internals (closes carried-over gap 3)",
+    "Added two thin brushed-steel riser posts (ex_riser_a/ex_riser_b) physically linking the exploded butterfly cluster baseplate to its source baseplate bu_base_1, so the exploded relationship is unambiguous in the FRONT/SIDE elevations (closes carried-over gap 1, exploded cluster)",
+    "Added a heatsink riser stub (heatsink_riser) from the silicon die up to the heatsink baseplate so the lifted heatsink is grounded to the package in elevation (closes carried-over gap 1, heatsink)",
+    "Rewired the datapath so each pipeline register feeds mod_red_mult, mod_red_mult feeds mod_red_subshift, and mod_red_subshift returns to the crossbar — a legible reduction assembly order",
+    "Updated assembly_instructions, pcb_substrate/crossbar connection lists, and the facts note to reflect the split reduction unit and riser supports"
+  ],
+  "remaining_gaps": [
+    "Model the remaining four butterfly units (paper benchmarks 8 parallel BUs) as a second mirrored cluster array — e.g. interleave 8 narrower clusters across the 9 m depth or stack a second row — to match the headline configuration and recover ~2 structural/proportional points; the current scene still only shows 4 of 8",
+    "The two reduction members (mod_red_mult, mod_red_subshift) are still abstract boxes; consider giving the Barrett multiplier a cylindrical DSP silhouette to distinguish it from the subtract member at a glance",
+    "Add a faint dashed/ghost connector or arrow geometry from each pipeline register into the crossbar to make the operand-return path readable in ISO, not just inferable from the connection graph"
+  ]
+}