Update firmware documentation and agent guidance

doc/05_led_system.md

@@ -14,9 +14,12 @@ Dünner Wrapper um **Adafruit NeoPixel** (bit-bang, kein DMA, kein SERCOM).
 | `ws2812_show()` | Bit-Bang-Übertragung (~600 µs, Interrupts gesperrt) |
 | `ws2812_clear()` | `clear()` + `show()` |
 
-`ws2812_show()` wird in `CMainController::updateLEDs()` **nur** aufgerufen wenn mindestens ein Button dirty war – 600 µs Blockzeit werden so vermieden wenn keine Änderung nötig ist.
+`ws2812_show()` wird in `CMainController::updateLEDs()` nur aufgerufen, wenn
+mindestens ein Button dirty war oder eine Animation läuft. Bei einer endlos
+laufenden Animation wird daher in jedem Loop ein Frame übertragen.
 
-**Warum kein DMA?** DMA + SERCOM-SPI würde ~1,5 KB extra RAM (1440 Byte Kodier-Puffer) und erhebliche Implementierungskomplexität erfordern. Bei 20 LEDs und ~20 ms Loop-Rate sind 600 µs gesperrte Interrupts (= 3 % der Loop-Zeit) unkritisch.
+Der Treiber nutzt `Adafruit NeoPixel` per Bit-Banging; es gibt keinen
+DMA-/SERCOM-Ausgabepfad.
 
 ## 2-Schicht-Modell (CButton)
 
@@ -34,7 +37,7 @@ Aktive Farbe = `override` wenn aktiv, sonst `base`. `clear_override()` kehrt sof
 | Animation | Typ | Verhalten | Endbedingung |
 |---|---|---|---|
 | `STATIC` | — | Feste Farbe | — |
-| `BLINK` | Helligkeit | An/Aus, `period_ms` = Halbperiode | endlos |
+| `BLINK` | Helligkeit | erste Hälfte an, zweite Hälfte aus; `period_ms` = Vollperiode | endlos |
 | `PULSE` | Helligkeit | Lineares Dreieck 0→255→0 | endlos |
 | `FADE_IN` | Helligkeit | Einmalig schwarz → voll | → STATIC (voll) |
 | `FADE_OUT` | Helligkeit | Einmalig voll → schwarz | → STATIC (base=schwarz) |
@@ -45,6 +48,12 @@ Aktive Farbe = `override` wenn aktiv, sonst `base`. `clear_override()` kehrt sof
 
 **Farb-Animationen** (`compute_rgb`): Berechnen RGB direkt; base/override werden nicht verändert (außer bei Abschluss).
 
+Die globale und LED-spezifische Helligkeit werden beim Initialisieren in die
+Base-Farbe eingerechnet. `COLOR_CYCLE` ignoriert diese Base-Farbe und rendert
+mit einem festen Faktor von 40 %. Auch CDC-Overrides werden von
+`COLOR_CYCLE`/`COLOR_FADE` visuell überdeckt, solange die Farbanimation aktiv
+ist.
+
 ### COLOR_CYCLE – Hue-Arithmetik (kein Float)
 
 Hue 0–255 aufgeteilt in 6 Segmente à 43 Einheiten. Innerhalb jedes Segments steigt/fällt ein Kanal linear:
@@ -60,7 +69,16 @@ Seg 5: R=255, B fällt      (Magenta → Rot)
 
 Ausgabe wird auf 40 % Helligkeit skaliert (Faktor 102/255) damit die LEDs nicht blenden.
 
-`Adafruit_NeoPixel::ColorHSV()` ist nicht nutzbar: verwendet intern float (kein FPU auf M0+).
+Die Firmware verwendet eine eigene ganzzahlige Hue-Umrechnung und ruft
+`Adafruit_NeoPixel::ColorHSV()` nicht auf.
+
+Für `PULSE` muss `period_ms >= 2` gelten, da der Code durch die halbe Periode
+teilt. Eingehende Configs validieren diesen Grenzwert aktuell nicht.
+
+`COLOR_FADE` benötigt `set_color_fade(to, period_ms)`, weil dort Start- und
+Zielfarbe gesetzt werden. Ein bloßes `set_anim(COLOR_FADE, ...)`, wie es beim
+direkten Laden dieses Enum-Werts aus der Config geschieht, initialisiert diese
+Farben nicht aus den Configdaten.
 
 ### Phasenversatz (Regenbogen-Wellen)