Update firmware documentation and agent guidance

doc/07_serial_protocol.md

@@ -13,13 +13,14 @@ Alle Pakete sind exakt 8 Byte lang:
 ```text
 Byte 0: command / event id
 Byte 1: key_id oder chunk-index oder chunk-count
-Byte 2: daten a
-Byte 3: daten b
-Byte 4: daten c
-Byte 5..7: reserviert
+Byte 2..7: kommandospezifische Daten
 ```
 
-Es gibt kein Framing und keinen Laengenheader.
+LED-Kommandos verwenden Byte 2..4 für RGB. Config- und Makro-DATA-Pakete
+verwenden alle sechs Bytes 2..7 als Nutzlast. Einfache Events aus
+`usb_serial_send()` nutzen höchstens Byte 2..3 und füllen den Rest mit null.
+
+Es gibt kein Framing, keinen Längenheader und keine Prüfsumme auf Paketebene.
 
 ## Richtungen
 
@@ -49,10 +50,10 @@ Es gibt kein Framing und keinen Laengenheader.
 
 | ID | Name | Zweck |
 |---|---|---|
-| `0x81` | `KEY_DOWN` | Host-Command-Button gedrueckt |
-| `0x82` | `KEY_UP` | Host-Command-Button losgelassen |
-| `0x83` | `ENC_CW` | Encoder Host-Command im Uhrzeigersinn |
-| `0x84` | `ENC_CCW` | Encoder Host-Command gegen Uhrzeigersinn |
+| `0x81` | `KEY_DOWN` | wird für jede aktuelle Host-Action gesendet |
+| `0x82` | `KEY_UP` | definiert, aktuell nicht gesendet |
+| `0x83` | `ENC_CW` | definiert, aktuell nicht gesendet |
+| `0x84` | `ENC_CCW` | definiert, aktuell nicht gesendet |
 | `0x85` | `PONG` | Antwort auf Ping |
 | `0x90` | `CONFIG_ACK` | Config erfolgreich gespeichert |
 | `0x91` | `CONFIG_NACK` | Config ungueltig oder NVM-Timeout |
@@ -65,6 +66,10 @@ Es gibt kein Framing und keinen Laengenheader.
 | `0x98` | `MACRO_END` | Makro-Dump fertig |
 | `0x99` | `MACRO_NACK` | Makro-Speichern fehlgeschlagen |
 
+Bei `ActionType::HOST_COMMAND` enthält Byte 1 die Matrix-Key-ID oder die
+Encoder-ID. `SAction.data` wird nicht übertragen. Auch CW- und CCW-Actions
+senden aktuell `0x81`; die Drehrichtung ist im Paket nicht enthalten.
+
 ## Chunk-Zahlen
 
 Aktuelle Blob-Groessen:
@@ -115,15 +120,30 @@ Nur bei erfolgreicher Pruefung wird in NVM geschrieben.
 
 `MACRO_COMMIT` schreibt ohne CRC direkt nach NVM und signalisiert nur Erfolg oder Fehler.
 
+Die in `BEGIN` angekündigte Chunkzahl wird zwar gespeichert, aber beim Commit
+nicht ausgewertet. Die Firmware verfolgt nicht, welche Chunkindizes tatsächlich
+eingetroffen sind. Doppelte, fehlende und ungeordnete Chunks werden deshalb
+nicht als solche erkannt. Bei Configdaten schlägt ein unvollständiger Transfer
+typischerweise an der CRC fehl; bei Makrodaten kann ein unvollständiger
+Null-gefüllter Puffer gespeichert werden.
+
+Die Configvalidierung prüft keine Feldwerte oder Enum-Bereiche. Insbesondere
+müssen Hostimplementierungen gültige Profilindizes, Actiontypen, LED-Enums und
+Animationsperioden liefern.
+
 ## Praktische Hinweise fuer die GUI
 
 - nach `CONFIG_COMMIT` auf `CONFIG_ACK` oder `CONFIG_NACK` warten
 - danach erst `MACRO_*` senden
 - Dumps besser sequenziell lesen: zuerst Config, danach Makros
 - `DtrEnable` muss aktiv sein, sonst verwirft das Board CDC-Ausgaben
+- ausschließlich vollständige 8-Byte-Pakete schreiben; schon ein verlorenes
+  Byte verschiebt die Paketgrenzen für alle folgenden Daten
+- Encoder-Host-Actions derzeit nicht anhand von `0x83/0x84` erwarten
 
 ## Implementierungsdetails
 
-- RX-Ringbuffer: 256 Byte = 32 volle Pakete
+- RX-Ringbuffer: 256 Byte = 32 volle Pakete; er ist ein laufender
+  Zwischenpuffer und fasst keinen kompletten Configtransfer
 - feste 8-Byte-Pakete vereinfachen Firmware und GUI
 - nach einem reinen SWD-Reflash kann ein physischer USB-Reconnect noetig sein