Update firmware documentation and agent guidance

AGENTS.md

@@ -0,0 +1,94 @@
+# Arbeitsanweisungen für Coding-Agents
+
+Diese Datei gilt für das gesamte Repository. Sie ist zugleich der kompakte
+Einstiegskontext für LLM-basierte Entwicklungswerkzeuge.
+
+## Ziel und Plattform
+
+VersaMCU ist die Firmware des VersaPad-v2-Makropads. Das aktive und unterstützte
+PlatformIO-Ziel ist `env:versapad`:
+
+- ATSAMD21G17D, Cortex-M0+, 48 MHz
+- 128 KiB Flash, 16 KiB RAM
+- Arduino-SAMD-Core über PlatformIO
+- Upload per Atmel-ICE/CMSIS-DAP und OpenOCD, ohne Bootloader
+- USB Composite Device: Keyboard-HID, Consumer-HID und CDC Serial
+
+Das auskommentierte Bootloader-Ziel in `platformio.ini` ist kein verifiziertes
+Produktionsziel.
+
+## Vor dem Ändern lesen
+
+In dieser Reihenfolge:
+
+1. `README.md` für Scope, Build und Einstieg
+2. `doc/INDEX.md` für die thematische Navigation
+3. `doc/00_architecture.md` für Datenfluss und Laufzeitmodell
+4. `doc/09_known_limitations.md` für bewusst noch nicht gelöste Risiken
+5. die zum Task gehörende Fachdokumentation und anschließend den Quellcode
+
+Bei Widersprüchen ist der kompilierte Code die Quelle für das aktuelle
+Verhalten. Hardwarekonstanten stehen in `src/config/pins.h` und
+`variants/versapad/`; binäre Formate stehen in den Structs unter `src/config/`
+und in `src/hal/usb_serial.h`. Widersprüche zwischen Code und Dokumentation
+müssen im selben Change behoben oder ausdrücklich als bekannte Einschränkung
+festgehalten werden.
+
+## Unverzichtbare Verträge
+
+- `SAction`, `SDeviceProfile`, `SDeviceConfig`, `SMacroStep` und
+  `SMacroTable` sind persistente beziehungsweise hostseitige Binärverträge.
+- Änderungen an Feldreihenfolge, Enum-Werten, Packing, Größen, Magic, Version,
+  CRC-Bereich oder Chunking benötigen gleichzeitig:
+  Firmware-Migration/Versionswechsel, Anpassung der externen GUI und
+  Aktualisierung von `doc/06_nvm_config.md` sowie
+  `doc/07_serial_protocol.md`.
+- Die Windows-GUI gehört nicht zu diesem Repository. Keine Kompatibilität mit
+  ihr behaupten, wenn nur die Firmware geändert oder geprüft wurde.
+- Die NVM-Adressen liegen am oberen Ende des 128-KiB-Flash. Vor Änderungen an
+  Linker-Skripten, Boardgrößen oder NVM-Layouts immer
+  `doc/09_known_limitations.md` lesen.
+- Der Code läuft auf 16 KiB RAM. Keine unnötige dynamische Allokation, keine
+  großen Stackpuffer und keine Float-Arithmetik in Loop-/ISR-Pfaden einführen.
+- ISR-Code muss kurz und nicht blockierend bleiben. Niemals USB, NVM,
+  WS2812-Ausgabe oder `delay()` aus einer ISR aufrufen.
+- Das feste CDC-Protokoll besteht aus 8-Byte-Paketen. Es besitzt aktuell weder
+  Framing noch Sequenz-/Vollständigkeitsprüfung.
+
+## Änderungsleitfaden
+
+- Kleine, lokale Änderungen bevorzugen; HAL, Controller und persistente Config
+  nicht ohne Grund vermischen.
+- Neue Hardwarezugriffe gehören unter `src/hal/`.
+- Neue konfigurierbare Werte benötigen definierte Defaults und eine
+  Validierungsstrategie für Daten vom Host.
+- Neue Action- oder Eventtypen müssen in Firmware, Protokolldoku und externer
+  GUI gemeinsam geplant werden.
+- Bei Matrix- oder Encoderänderungen die ISR-/Queue-Interaktion prüfen.
+- Bei LED-Animationen nur ganzzahlige Arithmetik verwenden und Randwerte wie
+  `period_ms <= 1` behandeln.
+- Bestehende deutsch- und englischsprachige Kommentare dürfen vereinheitlicht
+  werden; Dateien als UTF-8 speichern.
+- Keine generierten Inhalte aus `.pio/` committen.
+
+## Verifikation
+
+Mindestens:
+
+```bash
+pio run -e versapad
+git diff --check
+```
+
+Für Hardware-, USB-, NVM- oder Timingänderungen zusätzlich einen passenden
+Gerätetest beschreiben. Es gibt derzeit keine automatisierten Unit- oder
+Integrationstests. Ein erfolgreicher Build beweist daher weder elektrische
+Funktion noch GUI-Kompatibilität.
+
+Vor Abschluss prüfen:
+
+- Stimmen README und betroffene `doc/*.md` noch?
+- Wurden Binärgrößen und Offsets neu berechnet statt übernommen?
+- Bleiben Firmware und NVM-Bereiche kollisionsfrei?
+- Ist klar getrennt, was verifiziert, nur aus Code abgeleitet oder noch offen
+  ist?