docs: montage-renderer imagery, visual polish, README screenshots

- switch report frames to the scene best/worst montage renderer
  (Onscreen/Offscreen panels + TPI/FPI/FN legend): perfect-second hero,
  wedding couple, funeral 19-of-20, polygraph bridging, crew-scene FN
  ceiling, Robert Patrick ground-truth gap, rapid-cut double label,
  Herbie Hancock on an in-fiction screen
- deep dive restructured: extinction bridging framed as designed
  behavior with a measurable cost (debug overlay draws the boxes; the
  shipped output is presence windows), plus the face-vs-presence
  ceiling and two X-Ray-is-wrong exhibits
- Material polish: light/dark palette toggle, landing-page grid cards,
  figure/caption CSS, how-to-read admonition; site_url set so 404 links
  resolve under the Pages subpath
- README: perfect-second and screen-call frames committed (gitignore
  exceptions), readme_example.jpg retired
- build_site.sh: stage_frame helper downscales montage frames to 1920px
  and pulls any missing montage-frames packages

scripts/docs/build_site.sh

@@ -11,38 +11,65 @@ cd "$REPO_ROOT"
 ASSETS_DIR="docs/assets/images"
 mkdir -p "$ASSETS_DIR"
 
-# Frames referenced by docs/model-bakeoff.md. Pull the film's montage
-# frames from the registry if this machine doesn't already have them locally.
-FRAMES_ROOT="experiments/results/holdout/frames"
-if [ ! -d "$FRAMES_ROOT/many_saints" ] || [ ! -d "$FRAMES_ROOT/downton_abbey" ]; then
-    echo "==> pulling montage frames (not found locally)..."
-    scripts/artifacts/pull_artifacts.sh montage-frames Many_Saints_of_Newark || true
-    scripts/artifacts/pull_artifacts.sh montage-frames Downton_Abbey__A_New_Era || true
-fi
+# Frames referenced by the docs. The scene best/worst montages (proper
+# renderer: Onscreen/Offscreen panel + TPI/FPI/FN legend) live in the
+# montage-frames registry packages, one per film; pull any film that's missing.
+MONTAGE_ROOT="experiments/results/holdout/montage_bestworst"
+for film in Downton_Abbey__A_New_Era Lovelace Café_Society \
+            Valerian_and_the_City_of_a_Thousand_Plan The_Many_Saints_of_Newark; do
+    if [ ! -d "${MONTAGE_ROOT}/${film}" ]; then
+        echo "==> pulling montage-frames/${film} (not found locally)..."
+        scripts/artifacts/pull_artifacts.sh montage-frames "$film" || true
+    fi
+done
+
+# stage_frame <src> <dest-basename>: downscale to <=1920px wide for the site
+stage_frame() {
+    if [ ! -f "$1" ]; then
+        echo "WARN: $1 not present; keeping existing ${ASSETS_DIR}/$2 (if any)"
+        return
+    fi
+    python3 - "$1" "${ASSETS_DIR}/$2" <<'PY'
+import sys
+from PIL import Image
+src, dst = sys.argv[1], sys.argv[2]
+im = Image.open(src)
+if im.width > 1920:
+    im = im.resize((1920, round(im.height * 1920 / im.width)), Image.LANCZOS)
+im.save(dst, quality=88)
+print(f"staged {dst} ({im.width}x{im.height})")
+PY
+}
 
 echo "==> staging referenced frames into ${ASSETS_DIR}"
-cp -v "${FRAMES_ROOT}/many_saints/fpi/fpi_t03543.jpg" \
-      "${ASSETS_DIR}/many_saints_ghost_fpi.jpg"
-cp -v "${FRAMES_ROOT}/downton_abbey/best/best_t00127.jpg" \
-      "${ASSETS_DIR}/downton_wedding_19_correct.jpg"
-if [ -f "${FRAMES_ROOT}/many_saints_intervals/w002_worst/w002_worst_t01382.jpg" ]; then
-    cp -v "${FRAMES_ROOT}/many_saints_intervals/w002_worst/w002_worst_t01382.jpg" \
-          "${ASSETS_DIR}/many_saints_ghosts_vs_unknowns.jpg"
-else
-    echo "WARN: many_saints_intervals frames not present; keeping existing" \
-         "${ASSETS_DIR}/many_saints_ghosts_vs_unknowns.jpg (if any)"
-fi
+stage_frame "${MONTAGE_ROOT}/Downton_Abbey__A_New_Era/scene_4/4_best_t000128.jpg" \
+            downton_wedding_couple.jpg
+stage_frame "${MONTAGE_ROOT}/Downton_Abbey__A_New_Era/scene_16/16_best_t007100.jpg" \
+            downton_funeral_19of20.jpg
+stage_frame "${MONTAGE_ROOT}/Downton_Abbey__A_New_Era/scene_7/7_worst_t001754.jpg" \
+            downton_crew_fn.jpg
+stage_frame "${MONTAGE_ROOT}/Lovelace/scene_24/24_best_t003607.jpg" \
+            lovelace_polygraph_bridged.jpg
+stage_frame "${MONTAGE_ROOT}/Lovelace/scene_6/6_worst_t000421.jpg" \
+            lovelace_robert_patrick_fpi.jpg
+stage_frame "${MONTAGE_ROOT}/Lovelace/scene_15/15_best_t002005.jpg" \
+            lovelace_perfect_second.jpg
+stage_frame "${MONTAGE_ROOT}/Café_Society/scene_20/20_best_t002430.jpg" \
+            cafe_society_rapid_cut.jpg
+stage_frame "${MONTAGE_ROOT}/Valerian_and_the_City_of_a_Thousand_Plan/scene_4/4_best_t001027.jpg" \
+            valerian_screen_call.jpg
+stage_frame "${MONTAGE_ROOT}/The_Many_Saints_of_Newark/out_of_cast_fpi/4_worst_t000871.jpg" \
+            many_saints_outofcast_fpi.jpg
+# debug-overlay example (extinction state drawn as frozen boxes) — from the
+# dump_error_frames output, not the montage package
+stage_frame "experiments/results/holdout/frames/many_saints/fpi/fpi_t03543.jpg" \
+            many_saints_ghost_fpi.jpg
 
 if [ ! -f "${ASSETS_DIR}/germar_beats_xray.jpg" ]; then
     echo "==> pulling report-highlights/germar_beats_xray.jpg..."
     scripts/artifacts/pull_artifacts.sh report-highlights germar_beats_xray.jpg
 fi
 
-if [ ! -f "${ASSETS_DIR}/readme_example.jpg" ]; then
-    echo "==> pulling report-highlights/readme_example.jpg..."
-    scripts/artifacts/pull_artifacts.sh report-highlights readme_example.jpg
-fi
-
 # pipeline_topology.svg is small and hand-authored (not pulled from anywhere) —
 # committed directly at docs/assets/images/, not staged from the registry.