From b946e5b59a66c8421125870f0b17f9a9eee0c832 Mon Sep 17 00:00:00 2001
From: Hermes <piotr@piksar.eu>
Date: Tue, 29 Sep 2026 11:35:50 +0200
Subject: [PATCH] docs: add Ground Station agent guide

---
 AGENTS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1e2d391
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,44 @@
+# Ground Station — agent guide
+
+## Purpose
+
+`groundstation` runs on Orange Pi Zero 3W as the control and observability process for the custom OpenIPC/WFB ground station.
+
+It receives final mixed RC channels from RadioMaster GX12 through the dedicated AUX1 UART, logs/renders pilot state, and starts the independent `fpv-video` launcher for Viture.
+
+## Safety boundaries
+
+- Primary pilot video must remain independent. Never restart, block, or add buffering to WFB/video decode from this process.
+- Never modify sticks, arm, flight mode, or existing AUX channels.
+- The future reverse path may override exactly one explicitly reserved profile AUX with SAFE/NORMAL/HIGH.
+- No valid heartbeat must return that AUX to its native EdgeTX SAFE value.
+- UART wiring is 3.3 V TTL only: crossed TX/RX plus GND. Never connect header 5 V or AUX_BOOT.
+- Do not use headtracking as a transport; it is reserved for a future Viture 3DoF gimbal aircraft.
+
+## Wire protocol v1
+
+```text
+0x47 0x53             magic "GS"
+1 byte                version (1)
+1 byte                type
+2 bytes little-endian sequence
+4 bytes little-endian millisecond timestamp
+N bytes               payload
+2 bytes little-endian CRC-16/CCITT-FALSE over all preceding bytes
+```
+
+`type=1` is `RCChannels`: payload contains 16 signed little-endian int16 values in final EdgeTX output units (`-1024..1024`). Validate length and CRC before accepting frames.
+
+## Development
+
+- Go is the implementation language.
+- Use `golang.org/x/sys/unix` for Linux UART termios. Add `periph.io` only for real GPIO/SPI/I2C display work.
+- Run `gofmt`, `go test ./...`, and `go vet ./...` before committing.
+- Keep hardware paths CLI-configurable.
+- Never commit credentials, Wi-Fi passwords, WFB keys, or live network addresses.
+
+## Repository workflow
+
+- `main` must remain deployable.
+- Keep hardware changes focused and tested separately from protocol parsing.
+- Grzesiu may maintain focused Gitea issues after the baseline protocol and hardware acceptance are recorded.