docs: document board configuration workflow

docs/src/logs.md

@@ -9,9 +9,13 @@ log::warn!("range aid stale");
 log::error!("sensor transfer failed"); // emitted as KAPTAN_ERROR
 ```
 
-`kaptan-log` formats once into a fixed bounded buffer, queues locally, and
-never sends MAVLink, allocates, blocks, changes flight state, or touches DMA.
-The sole MAVLink worker drains admitted records. F722 deliberately does not
+`kaptan-log` formats each event once into a fixed bounded buffer and never
+sends MAVLink, allocates, blocks, changes flight state, or touches DMA. The
+composition fans the event into each enabled sink; the sole MAVLink worker
+drains its bounded sink queue. Ordinary text, error paths, and error details
+use distinct 160-, 96-, and 64-byte storage types, so a queued record retains
+exactly the common diagnostic-envelope capacity and needs no adapter-side
+clipping buffer. F722 deliberately does not
 link this facade in ISR, DMA, control, actuator, panic, hard-fault, or shutdown
 contexts; those paths use static fault mailboxes that the worker turns into
 messages later.
@@ -25,7 +29,7 @@ orderly-shutdown observations:
 ```text
 KAPTAN_LOG { level, flags, message_length, message[160] }
 KAPTAN_ERROR {
-  flags, path_length, additional_information_length,
+  level, flags, path_length, additional_information_length,
   path[96], additional_information[64]
 }
 KAPTAN_SHUTDOWN { reason }
@@ -38,31 +42,54 @@ fixed arrays into UTF-8 prefixes. Generated MAVLink framing alone does not
 enforce these semantic length fields. `KAPTAN_LOG` displays its text at the
 MAVLink severity in `level`; `TRACE` is encoded as `DEBUG` plus the `TRACE`
 flag.
-`KAPTAN_ERROR` is error-only and accepts only `TRUNCATED` and `COALESCED`; a
-`TRACE` bit is never emitted there. Unknown future flag bits must be ignored.
+`KAPTAN_ERROR.level` preserves the originating MAVLink-compatible severity from
+Emergency through Error. The error channel accepts only `TRUNCATED` and
+`COALESCED`; a `TRACE` bit is never emitted there. Unknown future flag bits
+must be ignored. `COALESCED` means that one or more later observations from
+the same source mailbox were folded while the retained first error was pending;
+it does not claim that their paths or details were identical.
 
 The derived error path is intentionally not a numeric error catalog; renaming
 its Rust module/type/variant changes that identity. Error details requiring
 machine action stay in their owning protocol, notably `KAPTAN_CONFIG_RESULT`.
 `KAPTAN_SHUTDOWN` has only its typed reason and is valid only after an orderly
 output-inhibited completion. Delivery is bounded and lossy under link pressure;
-heartbeat and safety telemetry use separate paths.
+heartbeat and safety telemetry use separate paths. Logs have no publication
+rate setting and are not periodic streams. A retained event leaves the
+MAVLink sink queue once the lower transport admits it; temporary queue pressure
+only defers that same event.
 
 ## Filtering
 
-The SITL profile’s restart-only `observability.maximum_log_level` accepts
-MAVLink severities Error (3) through Debug (7). For example, selecting Warning
-permits warning records while suppressing info and debug records. Error-level
-records always use `KAPTAN_ERROR` and remain non-filterable. F722 uses its
-immutable board log threshold instead, because it has no active runtime
-profile.
+The restart-only `mavlink.logging.enabled` field controls the MAVLink
+diagnostic sink independently from future sinks such as a blackbox.
+`mavlink.logging.maximum_severity` accepts the complete MAVLink severity range,
+Emergency (0) through Debug (7). For example, selecting Warning permits warning
+and more severe events while suppressing notice, info, and debug. Disabling the
+sink suppresses both `KAPTAN_LOG` and `KAPTAN_ERROR` on MAVLink without
+suppressing events from another sink. F722 uses the validated policy recovered
+at boot, falling back to its board factory when the journal is empty or
+invalid.
+
+Severity remains a typed `Severity` value inside the board and runtime. Generic
+schema discovery exposes its named choices one at a time to the configurator,
+so the UI does not carry a field-key-specific severity list; numeric conversion
+exists only at the generic configuration transport and snapshot boundary. The MAVLink `level`
+field intentionally remains `uint8_t`: this generator represents XML enums as
+four-byte Rust values, so attaching an XML enum would widen the generated
+payload type. The adapter performs the checked one-byte conversion at that
+unavoidable wire boundary instead.
 
 Cargo `log/max_level_*` features compile calls away before the facade sees
 them; they are not a supported filtering mechanism. The build policy keeps
 that decision out of workspace dependencies.
 
-The tested `SitlConfigRuntime` composition proves `log!` reaches a generated
+The SITL facade ingress is transport-neutral and unfiltered. The tested
+`SitlConfigRuntime` composition applies the configured MAVLink policy when
+fanning an event into that sink and proves `log!` reaches a generated
 `KAPTAN_LOG` payload, and rejected configuration replies enqueue a generated
-`KAPTAN_ERROR` companion without replacing their authoritative result. `kaptan-sitl
-serve` does not yet attach a config/diagnostic MAVLink link, and F722 emits only
-outbound telemetry/diagnostic frames while rejecting all inbound authority.
+`KAPTAN_ERROR` companion without replacing their authoritative result.
+`kaptan-sitl serve` does not yet attach a config/diagnostic MAVLink link. F722
+images accept only the unsigned configuration service on their directly wired
+local UART; that direct-wire assumption does not extend to a shared or remote
+MAVLink network.