Update firmware documentation and agent guidance

doc/03_action_engine.md

@@ -25,7 +25,7 @@ Das `packed` ist zwingend, weil Config v3 bytegenau zwischen Firmware und GUI ue
 | `NONE` | keine Aktion | - |
 | `HID_KEY` | Tastaturtaste ueber USB HID | low byte = keycode, high byte = modifier |
 | `HID_CONSUMER` | Media/Consumer-HID | usage id |
-| `HOST_COMMAND` | Event an die GUI | command id |
+| `HOST_COMMAND` | Event an die GUI | aktuell nicht ausgewertet |
 | `MACRO` | Makro aus `SMacroTable` | slot 0..31 |
 | `PROFILE_SWITCH` | Profilwechsel | 0..2 oder `0xFF` fuer naechstes Profil |
 
@@ -35,7 +35,7 @@ Das `packed` ist zwingend, weil Config v3 bytegenau zwischen Firmware und GUI ue
 |---|---|
 | `HID_KEY` | `usb_hid_send_key()` |
 | `HID_CONSUMER` | `usb_hid_send_consumer()` |
-| `HOST_COMMAND` | `usb_serial_send(KEY_DOWN/ENC_*)` |
+| `HOST_COMMAND` | `USB_EVT_KEY_DOWN (0x81)` mit `key_id` senden |
 | `MACRO` | komplette Sequenz sofort abspielen |
 | `PROFILE_SWITCH` | Config aus NVM laden, Profil aendern, CRC neu berechnen, speichern, Buttons neu initialisieren |
 | `NONE` | nichts |
@@ -46,7 +46,7 @@ Das `packed` ist zwingend, weil Config v3 bytegenau zwischen Firmware und GUI ue
 |---|---|
 | `HID_KEY` | `usb_hid_release_key()` |
 | `HID_CONSUMER` | `usb_hid_release_consumer()` |
-| `HOST_COMMAND` | optionaler Up-Pfad, derzeit praktisch ohne Nutzlast |
+| `HOST_COMMAND` | keine Ausgabe; `USB_EVT_KEY_UP` ist nur definiert |
 | `MACRO` | nichts |
 | `PROFILE_SWITCH` | nichts |
 | `NONE` | nichts |
@@ -62,6 +62,26 @@ down -> delay(10 ms) -> up
 
 - Makros laufen komplett synchron in der Firmware.
 
+Das Hold-Modell verwaltet keine Menge gleichzeitig gedrückter Tasten. Ein
+neuer Keyboard-Down ersetzt den vorherigen Report und jeder Keyboard-Up leert
+den gesamten Report. Consumer-HID hat dieselbe Einschränkung mit genau einem
+Usage-Wert.
+
+## Host-Commands
+
+Der aktuelle Code sendet für jede `HOST_COMMAND`-Action nur:
+
+```text
+Byte 0 = USB_EVT_KEY_DOWN (0x81)
+Byte 1 = Matrix-Key-ID oder Encoder-ID
+```
+
+`SAction.data` wird dabei nicht übertragen. Auch Encoder-Actions verwenden
+aktuell `0x81`; die definierten Events `ENC_CW (0x83)` und `ENC_CCW (0x84)`
+werden nicht emittiert. Ein Release erzeugt kein `KEY_UP`-Paket. Das ist
+aktuelles Verhalten und als Einschränkung in
+[09_known_limitations.md](09_known_limitations.md) festgehalten.
+
 ## Makro-Ausfuehrung
 
 Bei `ActionType::MACRO` wird `action.data` als Slot interpretiert.