Update firmware documentation and agent guidance

doc/00_architecture.md

@@ -1,4 +1,4 @@
-# VersaMCU - Architekturuebersicht
+# VersaMCU – Architekturübersicht
 
 ## Zielplattform
 
@@ -7,23 +7,27 @@
 | MCU | ATSAMD21G17D, Cortex-M0+, 48 MHz |
 | Flash | 128 KB |
 | RAM | 16 KB |
-| FPU | keine, deshalb Integer-Arithmetik |
+| FPU | keine; LED-/Timingpfade verwenden Integer-Arithmetik |
 | USB | HID Keyboard + Consumer + CDC Serial |
 | Toolchain | PlatformIO + Arduino Core |
 
 ## Setup und Loop
 
 ```text
-setup()
-  macro_config_load()
-  nvm_config_load()
-  init_buttons()
-  usb_hid_init()
-  usb_serial_init()
-  matrix_init(cb)
-  encoder_init(cb)
+Arduino setup()
+  delay(500)
+  ws2812_init()
+  rotes Startsignal für 1 s
+  CMainController::setup()
+    macro_config_load()
+    init_buttons() -> nvm_config_load()
+    Queue-Bridge setzen
+    usb_hid_init()
+    usb_serial_init()
+    matrix_init(cb)
+    encoder_init(cb)
 
-loop()
+Arduino loop()
   matrix_scan()
   poll_vendor()
   processEvents()
@@ -39,6 +43,9 @@ Die Reihenfolge ist absichtlich simpel:
 - Sonderlogik fuer den Werksreset pruefen
 - LED-Frame nur bei Bedarf rendern
 
+Makros, Encoder-Taps, NVM-Schreiben sowie Start- und Reset-Feedback verwenden
+blockierende Delays. Währenddessen werden Matrix und CDC nicht bearbeitet.
+
 ## Datenfluss
 
 ```text
@@ -67,7 +74,7 @@ LED-Render
 | `main.cpp` | startet den Controller |
 | `CMainController.*` | Orchestrator fuer Inputs, Actions, Serial, LEDs |
 | `CButton.*` | LED-Zustand, Animationen, Action-Referenz |
-| `CEventQueue.*` | ISR-sicherer Ringbuffer |
+| `CEventQueue.*` | fester Ringbuffer mit 16 nutzbaren Slots |
 | `config/nvm_config.*` | Config v3 laden, speichern, Defaults |
 | `config/macro_config.*` | Makros laden, speichern |
 | `hal/matrix.*` | 5x5-Matrixscan mit Debounce |
@@ -76,6 +83,9 @@ LED-Render
 | `hal/usb_serial.*` | CDC-Paketpfad |
 | `hal/ws2812.*` | WS2812-Treiber |
 
+Die drei Fader sind nur im Variant und in `config/pins.h` definiert. Es gibt
+aktuell keinen Fader-HAL und keine Verarbeitung im Controller.
+
 ## Key-ID-Schema
 
 ```text
@@ -100,8 +110,17 @@ Der Werksreset ist keine PC-Funktion, sondern Teil der Firmware:
 
 ## Invarianten
 
-- kein Heap
-- keine Floats
+- Projektcode vermeidet dynamische Allokation
+- Integer-Arithmetik in zeitkritischen LED-/ISR-Pfaden
 - `packed` fuer serielle und NVM-relevante Structs
 - NVM-Schreibpuffer muessen 4-Byte-aligned sein
 - `usb_serial_send()` sendet nur bei aktiver CDC-Verbindung
+
+## Nebenläufigkeit
+
+Encoder-Callbacks laufen im EIC-Interrupt, Matrixcallbacks im Loop. Beide
+schreiben in dieselbe `CEventQueue`; `processEvents()` liest im Loop. Die Queue
+besitzt aktuell keinen Interruptschutz für den Matrix-Push und verwirft Events
+bei Überlauf. Das ist eine bekannte Einschränkung, keine garantierte
+Multi-Producer-Sicherheit; siehe
+[09_known_limitations.md](09_known_limitations.md).