docs: document configuration and diagnostics contracts

docs/src/reference.md

@@ -1,19 +1,30 @@
 # Reference
 
-## Build-time configuration
+This page collects stable limits and points to the detailed contracts.
 
-Board configuration is immutable in the compiled image. Runtime parameter
-updates and ground-station tuning are not exposed by the checked-in firmware.
+| Surface | Current contract |
+| --- | --- |
+| Flight profile | One 4 KiB-or-smaller raw CBOR blob, `profile_format = 1`, schema ID `KAPTANPROFILE-01`. |
+| SITL file | Private `[generation, raw-profile-blob]` envelope; not a MAVLink upload blob. |
+| Config transaction | One owner-bound RAM transaction; typed writes or 192-byte idempotent CBOR chunks; commit is restart-required. |
+| Config discovery | Correlated `KAPTAN_CONFIG_INFO_REQUEST` / `KAPTAN_CONFIG_INFO`, then descriptor/value requests. |
+| Diagnostics | `KAPTAN_LOG` (51020) for ordinary severity/text, `KAPTAN_ERROR` (51021) for bounded errors, and `KAPTAN_SHUTDOWN` (51022) for completed orderly output-inhibited shutdowns. |
+| F722 configuration | Immutable compiled board policy only; inbound MAVLink configuration remains disabled. |
 
-`TODO(configuration)`: a future configuration system must validate and stage
-an entire profile while disarmed, commit it atomically, and prove that outputs
-remain inhibited throughout staging, activation, and power-loss recovery.
+Read [Configuration](configuration.md) for the field/consumer matrix and GCS
+upload sequence, [Logs](logs.md) for receiver decoding and filtering, and
+[Errors](errors.md) for error propagation and panic scope.
 
-## Simulation package reproducibility
+## Verification
 
-The host SITL Docker build uses digest-pinned base images and the locked Rust
-dependency graph. The signed Gazebo APT feed is not snapshot-pinned.
+Before review, run:
 
-`TODO(reproducibility)`: snapshot/version-pin the Gazebo package set and
-verify the repository signing-key fingerprint before treating the simulator
-image as byte-for-byte reproducible release input.
+```sh
+cargo fmt --all --check
+cargo test --workspace --locked --offline
+cargo clippy --workspace --all-targets --locked -- -D warnings
+```
+
+The embedded no-std binaries require their target-specific build setup; the
+host workspace test suite continues to assert that the telemetry F722 image
+has no inbound authority or actuator path.