feat(ground-suite): add replay observability console

ground-suite/README.md

@@ -0,0 +1,61 @@
+# Ground Suite
+
+Ground Suite is Kaptan's desktop ground-control software. Its application
+identifier is `com.orkavian.ground_suite`.
+
+## Current scope
+
+The first vertical slice is a **read-only observability console**. It uses a
+deterministic replay fixture to present a vehicle identity, heartbeat state,
+telemetry presence, ordinary logs, runtime errors, and orderly-shutdown
+observations. It never sends bytes to a vehicle.
+
+This is deliberate: the current F722 firmware rejects every inbound MAVLink
+frame, and `kaptan-sitl serve` has no MAVLink endpoint. A connected-looking UI
+must not suggest the vehicle is controllable, safe, armed, or writable.
+
+## Architecture
+
+```text
+VehicleDataPort (replay now; MAVLink adapter later)
+        -> typed observation-or-drop updates
+        -> Riverpod observability state
+        -> Overview / Diagnostics presentation
+```
+
+`MavlinkByteSource` and `MavlinkEventDecoder` are receive-only seams. The
+future decoder must combine pinned MAVLink Common definitions with Kaptan's
+`kaptan.xml` root, and preserve the firmware's semantic rules for bounded
+`KAPTAN_LOG`, `KAPTAN_ERROR`, and `KAPTAN_SHUTDOWN` payloads. Raw severity,
+shutdown-reason, and diagnostic-flag values remain visible even when an app
+does not yet recognise them. Expected malformed or unsupported frames become
+parser/semantic drop updates and never terminate the observation stream.
+
+## Development
+
+From the repository root:
+
+```sh
+nix develop -c flutter analyze ground-suite
+nix develop -c dart format --set-exit-if-changed ground-suite
+nix develop -c sh -c 'cd ground-suite && flutter test'
+nix develop -c sh -c 'cd ground-suite && flutter run -d linux'
+```
+
+Linux is the first tested desktop runner. Native macOS and Windows runners
+will be added only with their respective CI coverage.
+
+## Deliberately deferred work
+
+- TODO(gcs-live-mavlink): generated MAVLink Common plus custom-dialect
+  bindings, a MAVLink 2 receive parser, semantic validation, and
+  serial/UDP/recording endpoints.
+- TODO(gcs-connection): endpoint lifecycle, reconnect generation, link-loss
+  policy, and parser/semantic-drop accounting sourced from real frames.
+- TODO(gcs-config): descriptor-driven configuration UI only after firmware has
+  authenticated ingress, source binding, persistent anti-replay state, target
+  storage, and a disarmed atomic activation path.
+- TODO(gcs-upload): CBOR import/export only through the reviewed transaction
+  protocol; never treat a local file as active vehicle configuration.
+- TODO(gcs-control): arm, command, calibration, and shutdown workflows need
+  their own reviewed authority and safety contracts.