save

Signed-off-by: Onur Özkan <work@onurozkan.dev>

docs/src/ground-suite.md

@@ -1,72 +1,67 @@
 # Ground Suite
 
-`ground-suite/` is Kaptan's desktop Flutter application. Its primary
-workspace is the Tactical Command surface: a spatial local scene, local units,
-and session-local drawings and markers. The decoded diagnostic event stream is
-always reachable from the tactical header.
+`ground-suite/` is Kaptan's web-based mission-control workspace. It is a
+map-first React and TypeScript application for working from mission intent to
+tasks, groups, roles, vehicles, and explicit engineering detail.
+
+> **Simulation boundary:** the first release always displays deterministic
+> simulated data. It has no live Kaptan or Cerebrum connection and cannot
+> command a physical vehicle.
 
 ## Application model
 
-The core model keeps these concepts independent:
+The core model keeps these categories independent:
 
-- **Vehicle definition** — immutable reviewed profile, catalog identity, and
-  bundled presentation media.
-- **Local fleet unit** — an operator-created instance of a vehicle definition.
-  Local-unit IDs and in-memory planning placements belong to the workspace,
-  not the vehicle definition. Current placement is local presentation data and
-  is not yet persisted.
-- **Received vehicle data** — transport input and diagnostic events. It cannot
-  create, position, identify, or authorize a local fleet unit.
+- **Mission truth** — source-owned missions, tasks, groups, vehicles,
+  operators, authority, alerts, and command receipts.
+- **Derived projections** — fleet health, task coverage, selection summaries,
+  and deterministic recommendations.
+- **Local UI state and preferences** — panels, viewport, layers, density,
+  reduced motion, and configurable hotkeys.
+- **Audit journal** — ordered source and command envelopes.
 
 This separation gives the fleet interface a stable path from local planning to
 future live operation without coupling visual selection to incoming telemetry.
 
 ## Tactical workspace
 
-The default route is Tactical Command. Its map-edge `UNITS`, `CURSOR`, and
-`VIEW` groups are local interactions, not MAVLink controls. `Selection cursor`
-is the default mode for map and rectangle selection. `Pencil cursor` creates
-session-local freehand strokes; its top toolbar controls hue, saturation,
-brightness, and thickness. `Marker cursor` has an independent full-color
-style and creates a named local marker only after a map click and explicit
-save. The shared disclosure keeps local scene data,
-vehicle link state, and command authority separate. Local drawings and markers
-are never reported vehicle positions.
+The central map uses an owned offline demonstration raster and local SVG/DOM
+overlays. Four semantic levels progressively disclose group, formation,
+vehicle telemetry, and engineering diagnostics. Click, Shift selection,
+rectangle selection, structured smart filters, configurable group keys, and
+accessible tables all operate on the same explicit selection model. Selection
+never grants command authority.
 
-`Add local unit` opens the horizontal local hangar. Choosing a definition only
-prepares a local unit draft; the explicit setup confirmation creates and
-selects a locally scattered scene unit, without asking the operator to click
-the map. Local setup currently permits only the workspace label. Vehicle
-configuration remains unavailable until verified binding, compatible schema,
-command authority, and safe activation are available. This presentation
-placement is temporary until reviewed MAVLink position data can drive a
-distinct reported-position layer. The right inspector and bottom selection
-console are available outside the map for keyboard and assistive-technology
-access. These interactions create only session-local workspace data.
+Consequential actions go through an exact-target preview covering authority,
+energy, link, staleness, constraints, connectivity, next state, and failure
+effect. The deterministic source then emits an acknowledgement or rejection
+into the same journal used for live mission projection.
 
 ## Architecture
 
 ```text
-VehicleDataPort -> typed observation updates -> observability state -> event stream
-Vehicle catalog -> local-unit workspace state -> tactical scene and unit inspector
+DataSource -> validation -> ordering/deduplication -> DataPlane journal
+  -> mission projection/selectors -> useSyncExternalStore -> React
+
+UI intent -> preview/authority/safety -> confirmation -> DataSource receipt
+  -> DataPlane journal -> mission projection
 ```
 
-The transport path and local-fleet path intentionally meet only through future
-explicit bindings. A future MAVLink adapter combines pinned MAVLink Common and
-Kaptan dialect definitions at the decoding boundary.
+The fake and future Kaptan sources implement the same transport-neutral
+contract. React never imports the fake adapter. See `ground-suite/docs/` for
+the complete boundary and integration unknowns.
 
 ## Follow-up work
 
-- TODO(gcs-fleet-storage): versioned persistence for local units and catalog
-  identities.
-- TODO(gcs-source-binding): explicit source-to-unit binding.
+- TODO(gcs-source-binding): authenticated explicit source-to-vehicle binding.
 - TODO(gcs-map-pose): coordinate datum, timestamped pose, uncertainty, and
   staleness handling for physical map placement.
 - TODO(gcs-map-renderer): owned Linux GPU map host, pinned MapLibre assets,
   and reviewed vector/DEM data source.
 - TODO(gcs-platform-match): compare reported build/schema metadata to the
   local definition.
-- TODO(gcs-command-surface): add command interaction only with its reviewed
-  authority, target-binding, and safety contracts.
+- TODO(gcs-command-surface): add a command transport only after its authority,
+  authentication, replay protection, target binding, and acknowledgement
+  contracts are reviewed.
 - TODO(gcs-catalog): generate installed definitions and category metadata from
   reviewed firmware build manifests.