From 01fb9f72922174e1ba6beb0828a80cada8328035 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Onur=20=C3=96zkan?= <work@onurozkan.dev>
Date: Mon, 10 Aug 2026 15:24:45 +0300
Subject: [PATCH] docs: describe Ground Suite scope

---
 docs/src/SUMMARY.md      |  1 +
 docs/src/ground-suite.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 docs/src/ground-suite.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 9b7a1ca..95c867d 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -9,6 +9,7 @@
 - [Configuration](configuration.md)
 - [Logs](logs.md)
 - [Errors](errors.md)
+- [Ground Suite](ground-suite.md)
 - [Boards](boards/index.md)
   - [Kakute F7 Mini V3](boards/kakute-f7-mini-v3.md)
   - [GEPRC GEP-F722-HD V2](boards/geprc-f722-v2.md)
diff --git a/docs/src/ground-suite.md b/docs/src/ground-suite.md
new file mode 100644
index 0000000..615b3eb
--- /dev/null
+++ b/docs/src/ground-suite.md
@@ -0,0 +1,30 @@
+# 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+See [Ground Suite's README](../../ground-suite/README.md) for its project
+layout, development commands, and scoped follow-up work.