Surface YOLO preflight in Detection Lab

docs/API_CONTRACTS.md

@@ -636,6 +636,52 @@ Returns object-detection model capability descriptors.
 }
 ```
 
+### GET `/api/v1/detection/yolo/preflight`
+
+Returns a canonical envelope with read-only configured-YOLO runtime preflight
+state. Optional query parameters:
+
+- `tile_manifest_path`: existing raster tile manifest path to validate.
+- `check_model_load`: default `false`; when `true`, explicitly loads only the
+  configured local model file for compatibility smoke. It never downloads
+  weights and never runs inference.
+
+Response data:
+
+```json
+{
+  "model_id": "yolo-configured",
+  "model_path": null,
+  "tile_manifest_path": null,
+  "status": "not_configured",
+  "message": "YOLO_MODEL_PATH is not set. GeoIntel will not download model weights automatically.",
+  "checks": {
+    "enabled": true,
+    "dependencies_available": true,
+    "model_path_set": false,
+    "model_file_exists": null,
+    "model_load_requested": false,
+    "model_load_ok": null,
+    "manifest_path_set": null,
+    "manifest_valid": null,
+    "tile_paths_exist": null,
+    "tile_limit_ok": null
+  },
+  "runtime": {
+    "dependencies_assumed": false,
+    "model_directory": null,
+    "yolo_config_dir": "/app/storage/ultralytics",
+    "torch_version": "2.12.1",
+    "ultralytics_version": "8.4.88",
+    "cuda_available": false
+  },
+  "tile_count": 0,
+  "max_tiles": 100,
+  "will_download_models": false,
+  "will_run_inference": false
+}
+```
+
 ### POST `/api/v1/detection/run`
 
 Creates a detection job and detection analysis run. If the requested model is unavailable, the job and analysis run are marked `failed` with `DETECTION_MODEL_UNAVAILABLE` or `DETECTION_DEPENDENCY_UNAVAILABLE`.