docs: richer report — data figures, success/failure frames, commit-pinned repo links

- experiment_charts.py generates 4 figures from experiments/ artifacts:
  held-out per-film F1, 16-combo ranking, DE search landscape, and the
  Downton detector-vs-tracker ghost timeline (replaces the blank
  title-card screenshot)
- new frames: 19-correct wedding shot (success case), Many Saints
  ghost-vs-unknown frame (three error classes in one image)
- rename rep4-optimizer-results.md -> model-bakeoff.md; rep4 kept only
  as the on-disk artifact prefix, explained once
- repo file references are now links via https://REPOLINK/<path>
  placeholders; build_site.sh pins them to the HEAD commit's raw URLs
  and fails the build if a linked path doesn't exist at HEAD
- drop references to removed scripts (scene_score.py, score_config.py)
  and to session-memory names; mark artifact-registry paths with their
  pull commands
- commit readme_example.jpg + pipeline_topology.svg so README renders
  on the plain Gitea repo view
- deploy_pages.sh: push built site/ to the gitea-pages branch

scripts/docs/build_site.sh

@@ -11,7 +11,7 @@ cd "$REPO_ROOT"
 ASSETS_DIR="docs/assets/images"
 mkdir -p "$ASSETS_DIR"
 
-# Frames referenced by docs/rep4-optimizer-results.md. Pull the film's montage
+# 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
@@ -23,14 +23,29 @@ fi
 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/fpi/fpi_t07242.jpg" \
-      "${ASSETS_DIR}/downton_abbey_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
 
 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.
+
 if [ ! -d experiments/galleries ] || [ -z "$(ls -A experiments/galleries 2>/dev/null)" ]; then
     echo "==> pulling galleries (not found locally)..."
     scripts/artifacts/pull_artifacts.sh galleries
@@ -39,7 +54,44 @@ fi
 echo "==> generating calibration curve chart"
 python3 scripts/docs/calibration_chart.py --out "${ASSETS_DIR}/calibration_curves.png"
 
+echo "==> generating experiment charts (16-combo ranking, DE landscape, held-out F1, ghost timeline)"
+python3 scripts/docs/experiment_charts.py --out-dir "${ASSETS_DIR}"
+
 echo "==> building site"
 mkdocs build
 
+# -- commit-pinned repo links -------------------------------------------------
+# Docs reference repo files via the placeholder hosts https://REPOLINK/<path>
+# (this repo) and https://KPNLINK/<path> (the KPN++ submodule). Substitute them
+# with raw URLs pinned to the exact commit being published, and fail the build
+# if any linked path doesn't actually exist at that commit — no dead links.
+HEAD_SHA="$(git rev-parse HEAD)"
+KPN_SHA="$(git rev-parse HEAD:external/KPN)"
+REPO_RAW="https://gitea.tourolle.paris/dtourolle/scene-actor-extraction/raw/commit/${HEAD_SHA}"
+KPN_RAW="https://gitea.tourolle.paris/dtourolle/KPN/raw/commit/${KPN_SHA}"
+
+if [ -n "$(git status --porcelain -- docs scripts src experiments)" ]; then
+    echo "WARN: working tree is dirty — commit-pinned links will point at ${HEAD_SHA}," >&2
+    echo "      which may not contain your latest changes. Commit before deploying." >&2
+fi
+
+echo "==> verifying repo-linked paths exist at ${HEAD_SHA}"
+missing=0
+for p in $(grep -rhoE 'https://REPOLINK/[A-Za-z0-9_./-]+' docs/*.md | sed 's|https://REPOLINK/||' | sort -u); do
+    if ! git cat-file -e "HEAD:${p}" 2>/dev/null; then
+        echo "error: docs link to '${p}', which does not exist at HEAD" >&2
+        missing=1
+    fi
+done
+[ "$missing" -eq 0 ] || exit 1
+
+echo "==> pinning repo links to ${HEAD_SHA} (KPN: ${KPN_SHA})"
+find site -name '*.html' -exec \
+    sed -i "s|https://REPOLINK|${REPO_RAW}|g; s|https://KPNLINK|${KPN_RAW}|g" {} +
+
+if grep -rq 'REPOLINK\|KPNLINK' site; then
+    echo "error: unsubstituted REPOLINK/KPNLINK placeholder left in site/" >&2
+    exit 1
+fi
+
 echo "==> done. site/ is ready to deploy to the gitea-pages branch."