feat: scope detection QA to inference coverage

docs/API_CONTRACTS.md

@@ -872,6 +872,29 @@ Response persists a `quality_check` and `metrics` rows through the existing QA/Q
 - `false_negatives`
 - `quality_check_id`
 
+Configured-YOLO QA automatically reads `tile_manifest_path` from the persisted
+`AnalysisRun.parameters_json`. Candidate and reference geometries are clipped
+to the union of the manifest's tile bounds after explicit CRS transformation to
+EPSG:4326. The response additionally returns:
+
+- `candidate_feature_count_raw` and `reference_feature_count_raw`;
+- `coverage`, including raw/evaluated/excluded/boundary-clipped population
+  counts, tile count, source CRS values and coverage mode;
+- `box_to_footprint_diagnostics`, which compares candidate boxes with reference
+  envelopes at the same IoU threshold.
+
+The canonical precision, recall, F1 and mean IoU always remain based on
+candidate geometry versus the persisted reference footprint. Envelope results
+are explicitly `diagnostic_only` and are persisted in
+`quality_checks.findings_json`; they never replace or inflate canonical metrics.
+
+Configured-YOLO QA fails closed with `DETECTION_QA_COVERAGE_UNAVAILABLE` when
+manifest provenance is absent, `DETECTION_QA_COVERAGE_MISMATCH` when it belongs
+to another raster, `DETECTION_QA_COVERAGE_INVALID` when bounds/CRS are invalid,
+or `REFERENCE_FEATURES_OUTSIDE_COVERAGE` when no reference polygons overlap the
+actual inference coverage. Explicit fixture/legacy runs without a manifest keep
+the documented unbounded comparison behavior.
+
 If the reference dataset has no persisted vector features, the endpoint returns `REFERENCE_FEATURES_NOT_FOUND`. It does not calculate fake QA metrics.
 
 #### Future analysis route: `/api/v1/analysis/building-stats`