feat: make spatial entry optional and authoritative

docs/API_CONTRACTS.md

@@ -262,6 +262,19 @@ area list endpoint and includes persisted GeoJSON geometry for map display.
 Updates the area name and/or geometry. Geometry updates follow the same
 validation, repair and metric-calculation rules as area creation.
 
+### GET `/api/v1/projects/{project_id}/areas/municipalities`
+
+Searches the persisted authoritative NGI AdminVector municipality layer by
+Dutch, French or German name and NIS code. `query` is optional and `limit` is
+bounded to 50. Results contain names and NIS identity but no fabricated or
+browser-fetched geometry.
+
+### POST `/api/v1/projects/{project_id}/areas/municipalities/{niscode}/activate`
+
+Idempotently creates or returns a project Area from the exact persisted NGI
+municipality geometry. The resulting Area can be used by all existing bounded
+selection, acquisition, analysis and export contracts.
+
 ## Datasets
 
 ### POST `/api/v1/projects/{project_id}/datasets/upload`

docs/CODEX_EXECUTION_LOG.md

@@ -11326,3 +11326,23 @@ Validation:
 Known limitation:
 
 - the authenticated live workbench still requires a user session for visual browser verification after deployment; public landing and runtime health remain independently testable.
+
+## 2026-07-26 - Optional spatial entry and authoritative municipality activation
+
+Implemented:
+
+- corrected the false assumption that municipalities were already project Areas: the national workspace contains 565 official NGI AdminVector municipality features instead;
+- added bounded search across the persisted Dutch, French and German NGI names plus NIS code, and an idempotent activation route that creates a normal project Area from the exact persisted geometry;
+- replaced the non-functional Area-only datalist with an asynchronous official municipality search, explicit result selection, loading/error states and active-area feedback;
+- repositioned municipality search as an optional map shortcut alongside free drawing rather than a mandatory first step;
+- reframed themes as optional map focus: they select the visible layer and primary metric while the insights workflow continues to report broader source availability;
+- removed misleading step numbers, clarified the spatial research flow and reduced both the application rail and map focus panel;
+- constrained narrow theme cards so titles, descriptions and availability labels remain inside their bounds;
+- replaced the compass illustration with a new vector GeoIntel mark: a geometric G/geo-lens, coordinate point and subtle contour field, applied to every existing favicon and application-icon derivative.
+
+Validation:
+
+- verified the production database contains 565 authoritative municipality features and inspected the actual multilingual NGI property contract read-only;
+- added backend API/service tests for multilingual/NIS search and persisted-area activation;
+- added frontend tests for live search, activation and explicit optional/free-selection semantics;
+- visually inspected the 512 px application mark and 32 px favicon derivative.

docs/TODO.md

@@ -908,3 +908,13 @@ This file now starts with the current implementation status. Older preparation/b
 - [x] Replace passive management naming with an actionable system/source monitor.
 - [x] Preserve existing persisted Area, source, analysis and QA contracts.
 - [ ] Add more direct quality-review actions only when a persisted candidate/reference pair exists; never synthesize a check.
+
+# Sprint 228 - Optional spatial entry and municipality activation
+
+- [x] Search the real persisted NGI municipality catalog instead of existing project Areas.
+- [x] Match Dutch, French and German names plus NIS codes.
+- [x] Activate the exact official geometry idempotently as a reusable project Area.
+- [x] Present municipality search as an optional shortcut beside free map drawing.
+- [x] Explain theme choice as map and primary-metric focus rather than a mandatory workflow gate.
+- [x] Keep narrow theme-card copy and status labels inside their cards.
+- [x] Replace the former compass icon with a scale-safe GeoIntel geo-lens mark.