docs: document the kaptan-native protocol

docs/src/logs.md

@@ -10,10 +10,10 @@ 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
+All five macros emit `LOG`; their level never selects a different wire
 message. When a reportable firmware error escapes a reviewed
 `#[kaptan_err_reportable::propagate]` function, it makes one bounded admission attempt
-to the separate `KAPTAN_ERROR` ingress.
+to the separate `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
@@ -29,31 +29,33 @@ Panic and hard-fault paths still do not attempt live telemetry.
 
 ## Receiver contract
 
-`definitions/kaptan/log.xml` and `definitions/kaptan/error.xml` separate
-ordinary logs and reportable errors:
+`definitions/publish/log.xml` and `definitions/publish/error.xml` define the
+separate ordinary-log and reportable-error publications:
 
 ```text
-KAPTAN_LOG { level, flags, message_length, message[160] }
-KAPTAN_ERROR {
+LOG { level, flags, message_length, message[160] }
+ERROR {
   error_id, raised_at[96]
 }
 ```
 
 A GCS decoder generated from the same `kaptan.xml` revision must validate
-`message_length <= 160` for `KAPTAN_LOG`. `KAPTAN_ERROR.raised_at` is a
+`message_length <= 160` for `LOG`. `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 reportable firmware error, so it has
+`LOG.level` is the typed severity-ordered Kaptan wire enum Trace (1), Debug
+(2), Info (3), Warn (4), or Error (5). Off (0) is a filter-only sentinel and
+is never emitted as a `LOG` event. `LOG.flags` currently owns only the
+Truncated bit (1).
+The `ERROR` message kind already means a reportable firmware error, so it has
 no redundant level or flags field.
 
 `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 reporting point where the `Err` entered
-diagnostics. Error details requiring
-machine action stay in their owning protocol, notably `KAPTAN_CONFIG_RESULT`.
+diagnostics. Protocol failures remain in their owning response; for example, a
+rejected KCFG upload returns a `FILE_CONTROL` failure and readable
+bounded detail.
 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
@@ -62,10 +64,10 @@ event.
 
 ## Filtering
 
-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 reportable `KAPTAN_ERROR` events or logs sent to another
+The single restart-only `mavlink.logging.level_filter` field uses Off (0),
+Trace (1), Debug (2), Info (3), Warn (4), and Error (5). `Info`, for example,
+accepts Info, Warn, and Error log events. `Off` suppresses `LOG` on MAVLink
+without suppressing reportable `ERROR` events or logs 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.
@@ -73,14 +75,14 @@ back to its board factory when the journal is empty or invalid.
 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.
+Only the MAVLink adapter converts the five event levels to the typed Kaptan
+wire enum.
 
 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 `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
+generated `LOG` payload.
+`kaptan-sitl serve` does not yet attach a file/diagnostic MAVLink link. F722
+images accept only the unsigned Kaptan file service on their directly wired
 local UART; that direct-wire assumption does not extend to a shared or remote
 MAVLink network.