save

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

ground-suite/README.md

@@ -1,24 +1,78 @@
-# Ground Suite
+# Kaptan Ground Suite
 
-Ground Suite is Kaptan's desktop ground-control application.
+Kaptan Ground Suite is a map-first web workspace for coordinating missions,
+tasks, groups, roles, and approximately 50 robotic vehicles. This first release
+is deliberately backed by a deterministic simulation. It does **not** connect
+to Kaptan firmware and does not send commands to real vehicles.
 
-## Development
+## Run and verify
 
 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'
+nix run .#ground-suite
+nix run .#ground-suite -- test
+nix flake check
+nix develop .#ground-suite
 ```
 
-## Layout
+The server binds to `127.0.0.1:4173` by default, prints its URL, and prints a
+simulated-data warning. Override only when intentionally exposing the local
+demo:
 
-- `lib/app/` — application shell and appearance.
-- `lib/features/fleet/` — fleet canvas and local-unit workspace.
-- `lib/features/vehicle_workspace/` — installed vehicle definitions and Add-unit flow.
-- `lib/features/diagnostics/` — diagnostic event stream.
-- `lib/core/` — transport and MAVLink decoding boundaries.
+```sh
+KAPTAN_GROUND_SUITE_HOST=127.0.0.1 KAPTAN_GROUND_SUITE_PORT=4173 nix run .#ground-suite
+```
 
-The durable design and integration notes live in [the documentation](../docs/src/ground-suite.md).
+Inside the development shell:
+
+```sh
+cd ground-suite
+npm ci
+npm run dev
+npm test
+npm run test:e2e
+npm run check
+```
+
+The application has no remote runtime dependency: the demonstration map,
+catalog imagery, fonts, simulation, and overlays are local. Catalog imagery is
+covered by `public/assets/vehicle_catalog/LICENSE.md` (CC0 1.0).
+
+## Operating model
+
+The map is one continuously mounted operations scene. Fleet, queue, events,
+deployment, commissioning, recovery, layers, and settings are drawers, trays,
+or overlays; they never replace or remount the map. Strategic, operational,
+tactical, and engineering detail is driven by the same camera and selection.
+
+Selection, operator-local control groups, authoritative mission groups, and
+authority leases are separate. Every consequential intent remains a local
+spatial draft until its immutable targets, authority, energy, link, freshness,
+constraints, and source status have been reviewed. The fake adapter is the only
+mutation-capable source and is labelled as simulation throughout the scene.
+
+The typed interaction controller and its mode contract live in
+`src/interaction/controller.ts`. It owns selection, lasso/marquee, pan, command
+intent, formation, annotation, task/safety geometry, measurement, mission
+points, editing, erasing, and draft undo/redo. The benchmark and composition
+decisions are recorded in `docs/DESIGN_RESET.md`.
+
+Primary code boundaries:
+
+- `src/core/data-plane/`: transport-neutral source, envelope validation,
+  ordering/deduplication, journal, reducers, preview, and command submission.
+- `src/adapters/fake/`: scenario-owned deterministic clock and 50-vehicle
+  source; no UI component imports it.
+- `src/domain/` and `src/projections/`: authoritative types and derived
+  selectors.
+- `src/core/persistence/`: versioned local operator preferences only.
+- `src/adapters/kaptan/` and `src/adapters/cerebrum/`: explicit future ports;
+  neither claims a live integration.
+- `src/app/` and `src/design-system/`: persistent spatial scene, coordinate map,
+  docked workbenches, charts, SVG iconography, and the supplied graphite/navy
+  visual language.
+- `tests/e2e/visual-compositions.spec.ts`: eight deterministic high-fidelity
+  states rendered at 1366×768, 1920×1080, and 3440×1440.
+
+See `docs/` for architecture, safety, source behavior, and issue traceability.