docs: update configuration and diagnostics

docs/src/logs.md

@@ -1,94 +1,85 @@
 # Logs
 
-Normal host/SITL task code can use the standard facade:
+Kaptan code uses the familiar logging macros on both host and flight targets:
 
 ```rust
-log::debug!("estimator waiting for IMU");
-log::info!("configuration loaded");
-log::warn!("range aid stale");
-log::error!("sensor transfer failed"); // emitted as KAPTAN_ERROR
+kaptan_log::debug!("estimator waiting for IMU");
+kaptan_log::info!("configuration loaded");
+kaptan_log::warn!("range aid stale");
+kaptan_log::error!("sensor transfer failed");
+kaptan_log::trace!("prediction step complete");
 ```
 
+All five macros emit `KAPTAN_LOG`; their level never selects a different wire
+message. When a terminal typed firmware error escapes a reviewed
+`#[kaptan_err_propagate::propagate]` function, it makes one bounded admission attempt
+to the separate `KAPTAN_ERROR` ingress.
+
 `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.
+drains its bounded sink queue. Ordinary log text uses one 160-byte bounded
+record. Typed-error records contain the explicit ID and a static reference to
+the annotated propagation boundary until the MAVLink adapter copies its
+`file:line` into the 96-byte `raised_at` field.
+Logs and typed errors use independent fixed atomic
+ingresses; interrupt and worker producers make one nonblocking admission
+attempt, and only the MAVLink worker encodes or transmits a retained event.
+Panic and hard-fault paths still do not attempt live telemetry.
 
 ## Receiver contract
 
-`definitions/kaptan/log.xml`, `definitions/kaptan/error.xml`, and
-`definitions/kaptan/shutdown.xml` separate ordinary logs, errors, and
-orderly-shutdown observations:
+`definitions/kaptan/log.xml` and `definitions/kaptan/error.xml` separate
+ordinary logs and typed errors:
 
 ```text
 KAPTAN_LOG { level, flags, message_length, message[160] }
 KAPTAN_ERROR {
-  level, flags, path_length, additional_information_length,
-  path[96], additional_information[64]
+  error_id, raised_at[96]
 }
-KAPTAN_SHUTDOWN { reason }
 ```
 
 A GCS decoder generated from the same `kaptan.xml` revision must validate
-`message_length <= 160` for `KAPTAN_LOG`, and `path_length <= 96` plus
-`additional_information_length <= 64` for `KAPTAN_ERROR`, before slicing the
-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.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.
+`message_length <= 160` for `KAPTAN_LOG`. `KAPTAN_ERROR.raised_at` is a
+zero-padded UTF-8 `file:line` prefix; receivers use bytes before the first zero,
+or the complete field when no zero is present.
+`KAPTAN_LOG.level` accepts only Error (3), Warning (4), Info (6), and Debug
+(7); Trace is encoded as Debug (7) plus the `TRACE` flag. Other MAVLink
+severity numbers are not Kaptan log levels.
+The `KAPTAN_ERROR` message kind already means a typed firmware error, so it has
+no redundant level or flags field.
 
-The derived error path is intentionally not a numeric error catalog; renaming
-its Rust module/type/variant changes that identity. Error details requiring
+`error_id` is the stable nonzero catalog number explicitly assigned to the
+Rust error variant. Renaming or reordering a variant does not change it.
+`raised_at` identifies the annotated boundary where the `Err` entered
+diagnostics. 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. 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.
+Delivery is bounded and lossy under link pressure; heartbeat and safety
+telemetry use separate paths. Logs have no publication rate setting and are
+not periodic streams. A retained event leaves its MAVLink sink only once the
+lower transport admits it; temporary queue pressure only defers that same
+event.
 
 ## Filtering
 
-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.
+The single restart-only `mavlink.logging.level_filter` field uses the familiar
+Off, Error, Warn, Info, Debug, and Trace choices. `Info`, for example, accepts
+Error, Warn, and Info log events. `Off` suppresses `KAPTAN_LOG` on MAVLink
+without suppressing typed `KAPTAN_ERROR` reports or events sent to another
+sink. There is no separate enable flag and no MAVLink-specific set of extra
+runtime log levels. F722 uses the validated filter 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.
+Events retain the compact typed `Level` and sink configuration retains the
+compact typed `LevelFilter`. Generic schema discovery exposes the filter's
+named choices to the configurator, so the UI carries no hardcoded field list.
+Only the MAVLink adapter converts the five event levels to MAVLink's numeric
+severity representation; Trace uses MAVLink Debug plus the Trace flag.
 
-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 SITL facade ingress is transport-neutral and unfiltered. The tested
+The log 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.
+fanning an event into that sink and proves `kaptan_log::info!` reaches a
+generated `KAPTAN_LOG` payload.
 `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