Initial public release

docs/workflows/GOLDEN_PATHS.md

@@ -0,0 +1,98 @@
+# Golden Paths
+
+Golden paths are protected workflows. Every major Codex pass must avoid breaking them.
+
+## Golden Path 1 — Project Area Dataset Foundation
+
+Goal: prove that the app can create a geospatial workspace.
+
+Steps:
+
+1. Create project.
+2. Create an Area from GeoJSON.
+3. Upload/register a vector dataset.
+4. Extract metadata.
+5. Persist dataset and geometry metadata.
+6. Display project, area and dataset in frontend.
+
+Pass criteria:
+
+- project exists via API;
+- area geometry validates;
+- dataset reaches `READY` or honest failure state;
+- frontend can show the state.
+
+## Golden Path 2 — Reference Building QA
+
+Goal: prove core GeoAI value without requiring real model inference yet.
+
+Steps:
+
+1. Load demo reference buildings.
+2. Load demo predicted buildings.
+3. Run matching algorithm.
+4. Produce precision, recall, F1 and IoU summary.
+5. Store QA run.
+6. Export matched/unmatched features as GeoJSON.
+
+Pass criteria:
+
+- metrics are deterministic on fixtures;
+- thresholds are configurable;
+- false positives/false negatives are visible;
+- export is valid GeoJSON.
+
+## Golden Path 3 — Raster Metadata and Tiling Readiness
+
+Goal: prove raster handling foundation.
+
+Steps:
+
+1. Register/upload GeoTIFF.
+2. Extract metadata.
+3. Validate CRS/transform.
+4. Generate tile manifest without necessarily running AI.
+5. Store tile parameters.
+
+Pass criteria:
+
+- metadata is persisted;
+- tile count is deterministic;
+- georeferencing is preserved;
+- unsupported rasters fail honestly.
+
+## Golden Path 4 — Detection Result Lifecycle
+
+Goal: prove detection outputs can travel through the system.
+
+Steps:
+
+1. Create or import detection run.
+2. Store detections with class/confidence/geometry.
+3. Render detections as layer.
+4. Run QA against reference.
+5. Export detections.
+
+Pass criteria:
+
+- no frontend-only detections;
+- every detection belongs to analysis run;
+- geometries are valid;
+- export works.
+
+## Golden Path 5 — V1 Recruiter Demo
+
+Goal: show portfolio value.
+
+Narrative:
+
+> GeoIntel loads a Kempen area, compares predicted building detections with reference building polygons, reports QA metrics, shows spatial errors and exports usable GIS output.
+
+Minimum demo artifacts:
+
+- map layer with reference buildings;
+- map layer with predicted detections;
+- QA metrics panel;
+- unmatched features layer;
+- GeoJSON export;
+- concise explanation of methods and limitations.