docs: describe tactical Ground Suite workspace

docs/src/ground-suite.md

@@ -1,48 +1,72 @@
 # Ground Suite
 
-`ground-suite/` is Kaptan's desktop Flutter ground-control application. Its
-first implementation is a deterministic, read-only replay console rather than
-a vehicle-control or configuration application.
+`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.
 
-It currently presents a received vehicle identity and heartbeat, telemetry
-presence, ordinary `KAPTAN_LOG` records, distinct `KAPTAN_ERROR` path/detail
-records, and `KAPTAN_SHUTDOWN` observations. It sends no MAVLink bytes.
+## Application model
 
-This scope reflects the firmware boundary: the F722 telemetry image discards
-every inbound MAVLink frame, and SITL does not yet expose a MAVLink endpoint.
-Link presence is never presented as proof of safety, authority, arming state,
-or write capability.
+The core model keeps these concepts independent:
 
-Ground Suite provides light and dark themes, selecting the operating system's
-current preference by default. Its dark theme uses a near-black canvas,
-muted-silver text, and restrained green accents. Locally blurred glass is
-limited to persistent navigation and session chrome; vehicle facts and the
-event stream use opaque instrument surfaces so they remain readable at volume.
-The desktop rail and compact session strip offer a current-session System,
-Light, or Dark appearance selector.
+- **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.
 
-The replay shell is organised as an operator scan path: source and authority,
-then last reported heartbeat and observed streams, then ingress accounting and
-the event stream. It labels reported vehicle state precisely and never infers
-current safety, command authority, or configuration capability from a replay
-or a received diagnostic record. The event stream keeps ordinary logs, runtime
-errors, and orderly shutdown reports visually and semantically distinct. Its
-local history is bounded; the interface prioritises runtime errors and orderly
-shutdown reports, and reports any local UI eviction independently from
-vehicle-side diagnostic loss.
+This separation gives the fleet interface a stable path from local planning to
+future live operation without coupling visual selection to incoming telemetry.
 
-Ground Suite uses a receive-only source/decoder/classifier boundary. The
-replay implementation feeds typed observations today. A future live adapter
-must combine pinned MAVLink Common definitions with `kaptan.xml`, reject
-MAVLink 1 and invalid MAVLink 2 frames, validate diagnostic length fields
-before UTF-8 decoding, retain unknown severity/reason/flag values, and count
-unsupported or malformed data as parser/semantic drops without ending a
-session.
+## Tactical workspace
 
-Configuration screens, CBOR upload, vehicle commands, arm/calibration, and
-shutdown controls are deliberately deferred. They require the corresponding
-firmware authority, authenticated ingress, replay protection, persistence,
-and disarmed activation features first.
+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.
 
-See [Ground Suite's README](../../ground-suite/README.md) for its project
-layout, development commands, and scoped follow-up work.
+`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.
+
+## Architecture
+
+```text
+VehicleDataPort -> typed observation updates -> observability state -> event stream
+Vehicle catalog -> local-unit workspace state -> tactical scene and unit inspector
+```
+
+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.
+
+## 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-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-catalog): generate installed definitions and category metadata from
+  reviewed firmware build manifests.