# Ground Suite

Ground Suite is Kaptan's desktop ground-control software. Its application
identifier is `dev.kaptan.ground_suite`.

## Current scope

The first vertical slice is a **read-only observability console**. It uses a
deterministic replay fixture to present a reported vehicle identity and
heartbeat, 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
        -> Vehicle observation / Event stream 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.

## Appearance

Ground Suite supplies light and dark themes and follows the operating system
by default. Its dark palette pairs a near-black canvas with muted-silver text
and restrained green accents. The visual system is intentionally layered:
locally blurred glass is reserved for persistent navigation and session
chrome, while vehicle facts and the event stream use opaque instrument
surfaces for reliable scanning at volume.

Use **Appearance** in the desktop rail or compact session strip to select
**System default**, **Light**, or **Dark**. The choice applies for the current
session only.

## Replay workspace

The shell keeps provenance and authority visible before any detail:

- **Vehicle observation** presents the replay source, last reported heartbeat,
  observed data streams, and ingress accounting. Typed replay marks integrity
  as not evaluated; reported state is not a current safety authority.
- **Event stream** is a dense, copyable diagnostic timeline. Logs, runtime
  errors, and orderly shutdown reports remain distinct, and bounded delivery
  flags such as truncation and coalescing remain visible. The app retains a
  bounded local history, prioritising runtime errors and shutdown reports, and
  discloses local UI evictions separately from vehicle-side delivery loss.
- **Vehicle setup · unavailable** is explanatory text, not a disabled control.
  It accurately reflects that this firmware currently accepts no inbound
  MAVLink authority.

## 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.