Initial GeoIntel V1 foundation

docs/18-ultra-prep/FRONTEND_STATE_MACHINE.md

@@ -0,0 +1,30 @@
+# Frontend State Machine
+
+Every async module must model these states explicitly:
+
+- `idle`
+- `loading`
+- `empty`
+- `ready`
+- `error`
+- `unavailable`
+- `disabled`
+
+## Dataset Card
+- idle: not selected
+- loading: metadata extraction running
+- empty: no datasets uploaded
+- ready: dataset metadata available
+- error: upload/extraction failed
+- unavailable: operation unsupported for this dataset type
+- disabled: feature flag off
+
+## Analysis Run
+- queued
+- running
+- succeeded
+- failed
+- cancelled
+
+## UI Rule
+Never leave users with a blank panel. Every panel must explain what is happening or what to do next.