docs: document configuration and diagnostics contracts

docs/src/errors.md

@@ -0,0 +1,47 @@
+# Errors
+
+Public Kaptan error enums derive the pure `KaptanError` implementation:
+
+```rust
+#[derive(Debug, kaptan_log::KaptanError)]
+enum SensorError {
+    TransferFault,
+    UnexpectedIdentity(u8),
+}
+```
+
+The derive implements `core::error::Error`, `Display`, and `ErrorReport`. It
+creates a bounded human-facing `module::Type::Variant` message without
+allocating, publishing telemetry, exposing generic source values, or changing
+safety state. Renaming a module, type, or variant changes that text; it is not
+a stable machine protocol identity.
+
+Normal-task code may use `log::error!("{error}")`; it is routed as a bounded
+`KAPTAN_ERROR`. ISR-adjacent flight paths may enqueue the derived static
+message through their existing bounded mailbox. Neither route is a replacement
+for safety state, actuator inhibit, or typed configuration results.
+
+## What the receiver sees
+
+- Configuration writes receive authoritative structured failures through
+  `KAPTAN_CONFIG_RESULT`: operation, lifecycle state, field IDs, validation
+  rule, and protocol error code.
+- Runtime driver and link faults reach the F722 MAVLink worker as
+  `KAPTAN_ERROR` text, subject to bounded transport admission. The message
+  carries no per-error numeric catalog: a `KaptanError` derive supplies its
+  type/variant display identity.
+- A rejected configuration operation may enqueue a companion `KAPTAN_ERROR`
+  containing the high-level `ProtocolError` identity. It is intentionally not
+  correlated and carries no field/rule detail; the matching
+  `KAPTAN_CONFIG_RESULT` remains the sole precise authority.
+- Control, navigation, safety, and simulator error types are derive-ready but
+  their live owners are not yet attached to a MAVLink worker.
+- `KAPTAN_SHUTDOWN` represents only a future completed orderly,
+  output-inhibited shutdown. It is not a shutdown request, panic, hard-fault,
+  reset, or retention-record protocol. F722 still uses `panic-halt`; it does
+  not claim a live panic frame or retained-record replay.
+
+No diagnostic message may synchronously transmit from a panic handler, hard
+fault, ISR, DMA callback, or motor-inhibit path. A later target integration
+must inhibit outputs first, persist a validated crash record, then report it
+only after the next boot’s static board telemetry is available.