Add clarity to slides

docs/deck/CHANGELOG_2026-08-25.md

@@ -283,13 +283,20 @@ both are landscape, and two of them plus the callout overruns the column by
 ~1.1 in. What did fit, without shrinking the Skylake diagram below the size at
 which its `Fetch/Decode` and `ALU` labels survive projection:
 
-| | |
-|---|---|
-| Skylake core diagram | unchanged at 7.3 in, `M, 1.86` |
-| callout | narrowed 7.9 → 4.55 in, `M, 5.42`, h 1.06 |
-| **Comet Lake die** | **`5.60, 5.42`, 3.00 in wide** |
+| element | before | after |
+|---|--:|--:|
+| Skylake core diagram | 7.3 in | **6.5 in** |
+| Comet Lake die | — | **4.55 in** |
+| callout | 7.9 in, under the diagram | 3.18 in, beside the die |
 
-The die's own text is illegible at 3.0 in, which is fine and matches slide 6:
+Two bands: the core diagram across the top, then the die bottom-left with the
+callout beside it. The diagram still dominates — 6.5 in against 4.55 — but the
+die is now large enough that the ten boxed cores are countable at a glance and
+the orange L3 slab is unmistakable, which is the whole reason it is there. At
+6.5 in the diagram's `Fetch/Decode`, `ALU` and `L2 Data Cache` labels all still
+project (checked by rendering it at 4.75, 5.6 and 6.5 in before choosing).
+
+The die's own core numbering stays illegible, which is fine and matches slide 6:
 neither die is read, both are counted. The caption carries the claim ("10 cores
 boxed; nearly half the die is cache and I/O") exactly as slide 6's does ("144
 blocks, 128 enabled on this card. One SM boxed.").
@@ -302,3 +309,52 @@ its second line rode on the progress track. Trimmed to one line at 6.82, with th
 FP64-scarcity remark moved into the notes — where it now says explicitly that the
 V100 diagram *understates* it, since a GeForce part runs FP64 at 1/64, and that
 this is half of why opt7 pays.
+
+---
+
+## §8 — Code panels read as objects
+
+Twenty-one code panels were drawn on `CODEBG = #0E1420`, which is **1.03:1**
+against the slide background: not a boundary, the same colour with extra steps.
+They were found only because the text inside them was monospaced. On a projector,
+whose black level is poor, they were nothing at all.
+
+Lightening the fill cannot fix that, and the contrast table says why:
+
+| code surface | vs. BG | vs. PANEL | ACCENT ink on it | MUTED ink on it |
+|---|--:|--:|--:|--:|
+| `#0E1420` (was) | 1.03 | 1.06 | 5.11 | 4.22 |
+| `#121A28` (= PANEL) | 1.09 | 1.00 | 4.84 | 4.00 |
+| `#17202E` (now) | 1.16 | 1.07 | 4.54 | 3.75 |
+| `#243043` | 1.43 | 1.31 | 3.69 | 3.05 |
+
+A fill lifted far enough to look wrong still reaches only 1.43:1, and it charges
+for it in the two inks that live on that fill: the box gets more visible as its
+highlighted tokens get less so. **A 1 pt line at `#3A4C66` gives 2.18:1 against
+the background and costs the ink nothing**, because it never touches the ink's
+ground.
+
+So: framed, with the fill lifted only as far as it is free.
+
+- `CODEBG` `#0E1420` → `#17202E`, a hair above `PANEL` rather than below it, so
+  the panel has some body without eating the accent tokens.
+- New `CODEEDGE` `#3A4C66`, 1 pt, on the rounded rect; corner radius pinned to
+  `adjustments[0] = 0.055` so wide panels read as panels, not pills.
+- New `CODEDIM` `#7C8A9E` for the `//` comments and the panel title, both of
+  which were `MUTED` — tuned against the slide background, and down to 3.75:1 on
+  the new fill. `CODEDIM` restores them to **4.67**, above where `MUTED` started.
+  Used inside code panels only; `MUTED` is unchanged everywhere else.
+
+All of it lands in the `code()` helper, so the twenty-one call sites are
+untouched and uniform by construction. Geometry is unchanged — the border is
+centred on the existing boundary, extending 0.007 in — and the overflow sweep is
+clean across all 51 pages.
+
+**What this buys, on 15/33.** The right column stacks three objects that were
+previously two-and-a-half. They now read as three kinds without being read:
+
+| object | container | means |
+|---|---|---|
+| code panel | framed, lighter fill, rounded | source |
+| callout | flat panel, coloured left spine | conclusion |
+| caption | none | provenance |

docs/deck/build_fused_deck.py

@@ -44,7 +44,18 @@ OUT = DOCS / "cf_cuda_fused.pptx"
 # ---------------------------------------------------------------- design tokens
 BG     = RGBColor(0x0B, 0x10, 0x18)
 PANEL  = RGBColor(0x12, 0x1A, 0x28)
-CODEBG = RGBColor(0x0E, 0x14, 0x20)
+# Code panels are framed, not filled, to set them apart. The fill can only ever
+# be a hair lighter than the slide (1.16:1 at #17202E) before the accent-coloured
+# tokens inside start losing contrast against it -- and a projector's black level
+# crushes every dark tone together anyway. The 1 pt edge reaches 2.18:1 against
+# the background without touching the ink's ground, so the boundary is drawn by
+# the line and the fill only has to say "a different surface".
+CODEBG = RGBColor(0x17, 0x20, 0x2E)
+CODEEDGE = RGBColor(0x3A, 0x4C, 0x66)
+# MUTED was tuned against the slide background; on the lighter code fill it drops
+# to 3.75:1, and it carries the comments and the panel title. This puts them back
+# above MUTED's original 4.22 -- inside code panels only.
+CODEDIM = RGBColor(0x7C, 0x8A, 0x9E)
 RULE   = RGBColor(0x1E, 0x28, 0x36)
 ACCENT = RGBColor(0x1E, 0x90, 0xC2)
 AMBER  = RGBColor(0xE8, 0xB2, 0x5C)
@@ -252,17 +263,21 @@ def code(s, x, y, w, lines, size=9, title=None):
     size = max(size, MIN_PT)
     lh = 0.0174 * size
     h = 0.24 + len(lines) * lh + (0.24 if title else 0)
-    rect(s, x, y, w, h, CODEBG, MSO_SHAPE.ROUNDED_RECTANGLE)
+    box = rect(s, x, y, w, h, CODEBG, MSO_SHAPE.ROUNDED_RECTANGLE)
+    box.line.fill.solid()             # rect() cleared the line; put one back
+    box.line.fill.fore_color.rgb = CODEEDGE
+    box.line.width = Pt(1.0)
+    box.adjustments[0] = 0.055        # a small radius: a panel, not a pill
     ty = y + 0.12
     if title:
         tf = tb(s, x + 0.18, ty, w - 0.36, 0.2)
-        run(para(tf, True), title, 9, MUTED, bold=True, spc=1.2)
+        run(para(tf, True), title, 9, CODEDIM, bold=True, spc=1.2)
         ty += 0.24
     tf = tb(s, x + 0.18, ty, w - 0.36, h - 0.24)
     for i, ln in enumerate(lines):
         p = para(tf, i == 0, line=1.12)
         if ln.strip().startswith(("//", "#")):
-            run(p, ln, size, MUTED, MONO)
+            run(p, ln, size, CODEDIM, MONO)
             continue
         for j, part in enumerate(ln.split("«")):
             for k, seg in enumerate(part.split("»")):
@@ -656,21 +671,21 @@ rail(s, [
 s = new_slide()
 chrome(s, 5, "The machine we are starting from",
        "CPU: latency-oriented, built to finish one thread fast")
-figure(s, "img_cpu_core", M, 1.86, 7.3)
+figure(s, "img_cpu_core", M, 1.84, 6.5)
 # The die photo mirrors slide 6's: same grammar, compute units boxed, so the two
 # machines are compared as objects and not only as block diagrams. It is kept
 # WHOLE rather than cropped to the ten cores, because the L3 slab on the right
 # and the I/O block on the left are half the die area -- which is the callout's
 # point standing next to it in silicon.
-callout(s, M, 5.42, 4.55,
+figure(s, "img_cpu_die", M, 5.04, 4.55)
+callout(s, 5.42, 5.04, 3.18,
         "Count the boxes: **6 fetch/decode**, out-of-order instruction selection, two "
         "levels of private cache, all of it to keep **two** instruction streams fed. "
-        "The ALUs are the small part.", h=1.06, size=10)
-figure(s, "img_cpu_die", 5.60, 5.42, 3.00)
-caption(s, 5.60, 6.76, 3.00,
+        "The ALUs are the small part.", h=1.34, size=10)
+caption(s, 5.42, 6.50, 3.18,
         "Comet Lake · 10 cores boxed; nearly half the die is cache and I/O.", size=8)
-caption(s, M, 6.60, 4.55,
-        "Skylake core and Comet Lake die after Stanford CS149, Fall 2025.", size=8)
+caption(s, 5.42, 6.88, 3.18,
+        "Both diagrams after Stanford CS149, Fall 2025.", size=8)
 rail(s, [
     ("label", "pc-moench-04 · AMD Ryzen 9 7950X"),
     ("gap", 0.10),