feat(tooling): X-Ray threshold optimizer, gallery utilities, artifact registry, docs build

Optimizer (scripts/optimizer/): replay.py runs the real C++ tracker/matcher/
scene_tracker chain over a dumped-embeddings HDF5 via sae_kpn, so a threshold
sweep never re-decodes video or re-embeds faces. optimize.py drives scipy's
differential_evolution over the knob space, with DE-level parallelism
(multiple population candidates evaluated concurrently via a ThreadPoolExecutor)
on top of per-film replay parallelism. second_score.py is the per-second X-Ray
scoring metric (TPI/FPI/FN, out-of-cast misID weighted 10x, fair recall masked
to gallery-known cast) that superseded an earlier scene-union metric.
dump_error_frames.py / dump_scene_montage.py extract annotated video frames
(bounding boxes, TPI/FPI/FN captions, onscreen-vs-offscreen split) for visual
review of a replay against ground truth. Gallery utilities: cast_restrict.py,
gallery_membership.py, fetch_missing_actors.py, reembed_gallery.py.

scripts/validation/: X-Ray ground-truth loading and provider-agnostic identity
matching (identity.py's keys_for — an actor is the union of every id we can
derive, since pipeline output and ground truth don't share one id space).

scripts/artifacts/: push/pull scripts for the Gitea generic package registry —
galleries, montage frames, and experiment data (manifests/trajectories/results)
are pushed there instead of committed, since none are needed to run the app,
only benchmarks. Versioned by git short-SHA.

scripts/docs/: MkDocs site build (build_site.sh) and the calibration-curve
comparison chart (calibration_chart.py, matplotlib, reads each gallery's
embedded calibration).

Gallery-building scripts (make_jellyfin_gallery.py, make_gallery.py,
filter_gallery.py, run_from_jellyfin.py, movienet_eval.py, movienet_prep.py,
sae_gallery.py) updated to read/write HDF5 galleries exclusively, matching the
engine-side format switch. run_from_jellyfin.py and the optimizer no longer
carry movie source paths in shared manifests (some source filenames include
scene-release tags) — resolved locally via a gitignored file-lut.json instead.

scripts/build_trt_engines.sh

@@ -4,8 +4,9 @@
 # block the pipeline; this script does it offline so cold starts are instant.
 #
 # Profiles must match src/arcface_embedder.hpp and src/scrfd_decoder.hpp:
-#   ArcFace : min=1x3x112x112 opt=Nx3x112x112 max=Nx3x112x112  (N = embed batch)
-#   SCRFD   : 1x3x640x640 (fixed; we letterbox to this)
+#   ArcFace    : min=1x3x112x112 opt=Nx3x112x112 max=Nx3x112x112  (N = embed batch)
+#   SCRFD      : 1x3x640x640 (fixed; we letterbox to this)
+#   TransNetV2 : 1x100x27x48x3 (fixed; scene detector window), input tensor "input"
 #
 # These trtexec-built engines are *not* picked up by the ORT TRT EP cache —
 # ORT uses its own engine format. The point of this script is:
@@ -22,6 +23,7 @@ mkdir -p "$OUT"
 EMBED_BATCH="${EMBED_BATCH:-4}"
 ARCFACE_MODEL="${ARCFACE_MODEL:-$MODELS/arcface_w600k_r50.onnx}"
 SCRFD_MODEL="${SCRFD_MODEL:-$MODELS/scrfd_500m_bnkps.onnx}"
+SCENE_MODEL="${SCENE_MODEL:-$MODELS/transnetv2.onnx}"
 
 run() { echo "+ $*"; "$@"; }
 
@@ -46,6 +48,24 @@ run trtexec \
     --saveEngine="$OUT/scrfd.$(basename "$SCRFD_MODEL" .onnx).640.fp16.engine" \
     --useCudaGraph
 
+if [[ -f "$SCENE_MODEL" ]]; then
+    echo
+    echo "== TransNetV2 (scene detector) =="
+    # Fixed 1x100x27x48x3 window. The raw-TRT scene detector backend loads this
+    # engine directly via --scene-detector-engine; the ORT-TRT EP builds its own.
+    run trtexec \
+        --onnx="$SCENE_MODEL" \
+        --fp16 \
+        --minShapes=input:1x100x27x48x3 \
+        --optShapes=input:1x100x27x48x3 \
+        --maxShapes=input:1x100x27x48x3 \
+        --saveEngine="$OUT/transnetv2.100x27x48.fp16.engine" \
+        --useCudaGraph
+else
+    echo
+    echo "== TransNetV2 skipped (no $SCENE_MODEL) =="
+fi
+
 echo
 echo "Engines saved under: $OUT"
 echo "Look for 'mean: ... ms' in each section for per-call latency."