# Kaptan Ground Suite

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.

## Run and verify

From the repository root:

```sh
nix run .#ground-suite
nix run .#ground-suite -- test
nix flake check
nix develop .#ground-suite
```

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:

```sh
KAPTAN_GROUND_SUITE_HOST=127.0.0.1 KAPTAN_GROUND_SUITE_PORT=4173 nix run .#ground-suite
```

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.