docs: document configuration and diagnostics contracts

docs/src/architecture.md

@@ -24,6 +24,59 @@ The data channel owns rate selection, mailbox consumption, message encoding,
 and bounded TX classification. Board code supplies physical routes and
 telemetry configuration; it does not receive generic output authority.
 
+Configuration and runtime observability are separate, one-way planes:
+
+```text
+Kaptan GCS custom MAVLink V2 messages
+        │  (future: verified signing, source binding, replay state)
+        ▼
+kaptan-config-mavlink ──► state-only ConfigProtocol
+                                 │ borrows
+                    kaptan-flight-runtime
+                      ├── one ConfigManager ──► kaptan-config ──► flight schema/CBOR
+                      └── one kaptan-log hub
+                                 │
+                   kaptan-log-mavlink payload adapter
+                                 │
+                 platform-owned sole encoder / DMA TX link
+```
+
+The generated dialect is intentionally custom rather than a `PARAM_*` or QGC
+adapter. The core uses numeric field IDs and typed scalar values; descriptor
+text is metadata, not a wire identity. Discovery/value reads, bounded
+descriptor pages, and structured results are custom-dialect records. Runtime
+logs use one bounded text message with MAVLink severity and flags. CBOR import uses a fixed
+4 KiB transaction buffer and
+fixed 192-byte chunks; its decoded candidate still goes through the same whole
+profile validation path. The core owns one RAM transaction and the distinction
+between boot-active, committed, and editable candidate snapshots. In the
+current P1 policy a commit is restart-only. It cannot mutate controller or
+estimator state in flight.
+
+One current CBOR profile format is a bounded complete snapshot. There is no
+migration reader: any other format is rejected. SITL supplies the host file
+adapter and persists a nonzero generation alongside its raw profile payload.
+Motor allocation/mixer topology is immutable compiled
+vehicle capability data, never a scalar field or CBOR candidate member. The
+bare-metal receiver continues to reject inbound control authority. Target
+persistence, authenticated ingress, durable audit logging, disarmed
+activation, and atomic consumer reconstruction remain separate reviewed work
+and cannot be implied by a valid CBOR file or CRC.
+
+The MAVLink dialect root includes `kaptan/config.xml` and `kaptan/log.xml`.
+The build watches every fragment and generates one `message::kaptan` module;
+fragments are never separately generated Rust modules. `kaptan-log` itself has
+no MAVLink, platform, time, allocation, filesystem, or configuration
+dependency. It assigns bounded Critical and BestEffort queues for text logs.
+The platform drains a record only after TX admission; the diagnostic wire
+contract deliberately contains only severity, flags, bounded text length, and
+text. Local saturation accounting remains inside the hub, facade, and producer
+mailboxes; heartbeat and safety telemetry remain separate from diagnostic text.
+
+See [Configuration](configuration.md) for the deployment matrix and GCS upload
+contract, [Logs](logs.md) for the receiver contract, and [Errors](errors.md)
+for derived-error and failure-reporting scope.
+
 ## Ownership rules
 
 - A peripheral owner is local to the platform runtime.