feat(export): QA overlay renderer for exported alert datasets

CLAUDE.md

@@ -98,6 +98,15 @@ make export-alerts OUTPUT_DIR=outputs/alerts_export
 
 Writes `manifest.jsonl` (one line per alert) plus `images/{source_api}/{platform_alert_id}/{detection_id}.jpg`; each frame carries an `image_path` into that tree. Only alerts whose every lane reached `ANNOTATED` are exported. Re-runs are idempotent — the manifest is rewritten and only missing images are downloaded.
 
+### Export QA overlays
+
+```bash
+# Draw the exported boxes onto the exported frames for visual review
+make render-overlays DATASET_DIR=outputs/alerts_export
+```
+
+Writes `<dataset>/overlays/`: one contact sheet per object under `smoke/` and `false_positive/`, a combined sheet per multi-object alert under `multi_object/`, and an `index.csv`. Each cell pairs the full frame with a magnified crop of the box, since exported boxes are often ~0.05% of the frame area. Every smoke lane is rendered plus `FP_SAMPLE` false-positive lanes (round-robin across type combinations). `FP_SAMPLE` caps only the per-object sheets — the multi-object pass always covers every multi-lane alert; `--alerts` and `--mode` (script-only flags) are what bound a run.
+
 ## Key Architecture Concepts
 
 **Backend data flow**: Alert API → ingestion scripts → annotation_api DB → frontend UI → human annotations

README.md

@@ -62,7 +62,7 @@ Annotations stay on the API you annotated against; the file-based local→remote
 
 #### B. Other commands
 
-**Export annotated alerts for ML training**: `GET /api/v1/export/alerts` returns finished alerts (false positives and localized smoke) as nested alert → objects → frames → boxes JSON with presigned image URLs, keyset-paginated via `cursor` and incrementally syncable via `annotation_updated_gte`. See `docs/specs/2026-08-06-export-alerts-endpoint-design.md`. The old `make export-dataset` YOLO exporter was removed with the `/export/detections` endpoint it consumed; a pull script against the new endpoint is planned.
+**Export annotated alerts for ML training**: `GET /api/v1/export/alerts` returns finished alerts (false positives and localized smoke) as nested alert → objects → frames → boxes JSON with presigned image URLs, keyset-paginated via `cursor` and incrementally syncable via `annotation_updated_gte`. See `docs/specs/2026-08-06-export-alerts-endpoint-design.md`. The old `make export-dataset` YOLO exporter was removed with the `/export/detections` endpoint it consumed. Pull a dataset with `make export-alerts OUTPUT_DIR=...` (manifest + images), then review it visually with `make render-overlays DATASET_DIR=...`, which draws the exported boxes onto the exported frames.
 
 ## Admin Workflow — Populate the main API from the alert API
 

annotation_api/Makefile

@@ -23,6 +23,7 @@ help:
 	@echo "Other data commands:"
 	@echo "  import-alert-api     - (Admin) Import from alert API into annotation API"
 	@echo "  export-alerts        - Export annotated alerts (manifest + images) from annotation API"
+	@echo "  render-overlays      - Render QA contact sheets from an exported alert dataset"
 	@echo ""
 	@echo "Override variables inline, e.g.:"
 	@echo "  make import-alert-api DATE_FROM=2025-03-04 MAX_SEQUENCES=20"
@@ -131,6 +132,17 @@ export-alerts:
 		--max-workers $(MAX_WORKERS) \
 		--loglevel $(LOGLEVEL)
 
+# Render QA contact sheets (boxes drawn on the frames) from a dataset written
+# by export-alerts, so annotations can be eyeballed against the UI.
+# Usage: make render-overlays [DATASET_DIR=outputs/alerts_export] [FP_SAMPLE=40]
+render-overlays: DATASET_DIR ?= outputs/alerts_export
+render-overlays: FP_SAMPLE ?= 40
+render-overlays:
+	uv run python -m scripts.data_transfer.export.render_overlays \
+		--dataset-dir $(DATASET_DIR) \
+		--fp-sample $(FP_SAMPLE) \
+		--loglevel $(LOGLEVEL)
+
 .PHONY: help lint fix docker-build start stop clean test test-specific \
 	migrate migrate-up \
-	import-alert-api export-alerts
+	import-alert-api export-alerts render-overlays