geointel/docs/00-start/START_HERE.md

START HERE — GeoIntel Architect Canonical Entry Point

This is the single canonical entry point for Codex, reviewers and future contributors. Older handoff files are historical. If documents conflict, follow the precedence order in this file.

Current milestone

v1.0.0 - Belgium/North Sea release

The implementation is in final release-candidate acceptance for Belgium and the Belgian North Sea. Mol and the Kempen remain golden regression areas, not the product boundary.

Product one-liner

GeoIntel is a map-first GeoAI Workbench for Belgium and the Belgian North Sea that processes governed raster data, vector data and AI outputs into geospatially correct analysis, detections, segmentations, QA/QC metrics and exports.

Non-negotiable product identity

GeoIntel is:

• a GeoAI Workbench;
• a geospatial data processing product;
• a platform for raster/vector/AI/QA workflows;
• a portfolio-grade implementation of GIS, remote sensing, computer vision and data engineering.

GeoIntel is not primarily:

• a generic dashboard;
• a reporting-only tool;
• a chatbot;
• a QGIS clone;
• a mock demo app.

Canonical read order for Codex

Read these files in order before coding:

1. docs/00-start/START_HERE.md
2. docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md
3. docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md
4. docs/governance/GEOINTEL_CONSTITUTION.md
5. docs/governance/ARCHITECTURE_INVARIANTS.md
6. docs/governance/FORBIDDEN_DECISIONS.md
7. docs/API_CONTRACTS.md
8. docs/DATABASE_IMPLEMENTATION_PLAN.md
9. docs/DATA_SPECIFICATION.md
10. docs/DATA_SOURCES.md
11. docs/STORAGE_ARCHITECTURE.md
12. docs/DEFINITION_OF_DONE.md
13. docs/RELEASE_RUNBOOK.md

Canonical first implementation target

The first vertical slice is:

Project + Area + Dataset + Raster/Vector metadata + Reference polygons + Detection result import + QA/QC + GeoJSON export.

Do not start with full AI inference if the foundation is not stable. The first goal is to prove the data lifecycle and geospatial correctness.

Canonical V1 golden path

1. Create project.
2. Create/select an Area in the Kempen.
3. Upload or load a raster/vector dataset.
4. Extract and persist metadata.
5. Load reference polygons, initially demo GRB-like buildings.
6. Import or generate predicted building detections.
7. Convert outputs to valid geospatial features.
8. Run QA/QC against the reference layer.
9. Show results on the map and in metrics panels.
10. Export GeoJSON.

What Codex may improve autonomously

Codex may improve:

• implementation quality;
• test coverage;
• type safety;
• error handling;
• UI clarity;
• documentation clarity;
• internal helper abstractions;
• performance within defined budgets.

Codex may not change:

• product identity;
• core stack;
• CRS policy;
• database choice;
• async job architecture;
• API envelope shape;
• state machine names;
• golden path priority;
• forbidden decisions.

Conflict resolution

If any older document conflicts with the active RC layer, follow this order:

1. Constitution and architecture invariants.
2. Forbidden decisions.
3. State machines and canonical models.
4. API/database contracts.
5. Build order dependency graph.
6. Belgium/North Sea scope freeze and RC roadmap.
7. Older milestone and sprint handoff documents.

Required pass ending

Every Codex pass must end with:

• files changed;
• commands run;
• tests passed/failed;
• known limitations;
• whether golden paths still pass;
• whether any architecture invariant was touched;
• next recommended pass.