Fold bootloader documentation into the main doc/ index

Adds doc/10_usb_bootloader.md as the primary reference for the UF2
bootloader (memory layout, key-based boot entry, build/flash steps,
hardware test findings, known limitations), following the existing
numbered-doc convention. Updates doc/INDEX.md, doc/09_known_limitations.md
(bootloader is no longer "not supported", just scoped), and
doc/08_development.md accordingly.

Removes bootloader/TESTING.md (its findings now live in
doc/10_usb_bootloader.md) and trims bootloader/README.md down to what
belongs with that subproject specifically: upstream attribution/license
and local build/flash commands, plus the OpenOCD manual-flashing
warning since that's implementation-specific detail that would clutter
the higher-level doc.

Updates the top-level README.md (feature table, hardware table,
quickstart, project tree, doc links) to reflect USB flashing as a
supported path alongside SWD.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

doc/08_development.md

@@ -26,9 +26,9 @@ pio run -e versapad --target upload
 Der Upload nutzt `upload_openocd.py`, das das von PlatformIO installierte
 OpenOCD mit `interface/cmsis-dap.cfg` und `target/at91samdXX.cfg` startet.
 
-Das in `platformio.ini` nur als Beispiel enthaltene Environment
-`versapad_usb` ist auskommentiert und mit dem aktuellen NVM-/Linker-Layout
-nicht als unterstützt anzusehen.
+Für App-Updates über USB (nach einem einmaligen Bootloader-Flash) gibt es
+zusätzlich `env:versapad_usb`, siehe
+[10_usb_bootloader.md](10_usb_bootloader.md).
 
 ## Was beim Start passiert
 
@@ -63,6 +63,7 @@ und NVM-Schreibvorgängen. Es gibt keinen Scheduler und keine Threads.
 | LEDs | `05_led_system.md` | `CButton.*`, `hal/ws2812.*` |
 | Persistente Config | `06_nvm_config.md` | `config/nvm_config.*`, Linker-Skripte |
 | Host-Protokoll | `07_serial_protocol.md` | `hal/usb_serial.*`, Controller |
+| USB-Bootloader | `10_usb_bootloader.md` | `bootloader/`, `variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`, `boards/versapad.json`, `uf2conv.py`, `upload_uf2.py` |
 
 ## Verifikation
 

doc/09_known_limitations.md

@@ -3,36 +3,33 @@
 Diese Liste beschreibt den aktuellen Implementierungsstand nach den
 Robustheitskorrekturen. Sie ist keine Liste bereits umgesetzter Features.
 
-## Bootloader-Ziel bleibt nicht unterstützt
+## USB-Bootloader hat einen eingeschränkten Gültigkeitsbereich
 
-Das aktive Ziel `versapad_nobl` reserviert den kompletten Bereich
-`0x1FB00..0x1FFFF` für Makros und Config.
+Der UF2-Bootloader (`bootloader/`, App-Environment `env:versapad_usb`,
+Details in [10_usb_bootloader.md](10_usb_bootloader.md)) ist auf echter
+Hardware verifiziert und ergänzt den SWD-Weg, ersetzt ihn aber nicht: der
+Bootloader selbst muss weiterhin einmalig per Atmel-ICE/SWD geflasht werden.
 
-Ein USB-Bootloader-Pfad wird im Branch `feature/usb-bootloader` aufgebaut
-(`bootloader/`, App-Environment `env:versapad_usb`). Der komplette Weg ist
-dort auf echter Hardware verifiziert: Bootloader-Flash, USB-Enumeration,
-Tastencheck-Einstieg (kein physischer Reset-Taster auf diesem Board, siehe
-`bootloader/README.md`, "Hardware-Bootloader-Einstieg"), App-Firmware per
-`.uf2` über `env:versapad_usb --target upload` schreiben, automatischer
-Rücksprung in die neue App. Details und ein gefundener/behobener
-Hard-Fault-Bug beim Sprung Bootloader→App (fehlende `__DSB()`/`__ISB()` vor
-dem `bx`) stehen in `bootloader/README.md`, "Hardwaretest".
-`env:versapad_usb`s Linkerskript
-(`variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`) reserviert
-inzwischen denselben NVM-Bereich wie `flash_without_bootloader.ld`.
+Verbleibende Einschränkungen:
 
-Trotzdem noch kein Merge-fertiges Produktionsziel: Der `.bin`→`.uf2`-Weg
-(`uf2conv.py`, `upload_uf2.py`, Repo-Root) sucht das `VERSABOOT`-Laufwerk
-bisher nur über die Windows-API, keine macOS/Linux-Unterstützung. Die
-Bootloader-USB-PID (`0x0043`) ist zwar kollisionsfrei verifiziert, aber kein
-offiziell registrierter Wert unter Adafruits VID `0x239A`.
+- `uf2conv.py`/`upload_uf2.py` (Repo-Root) suchen das `VERSABOOT`-Laufwerk
+  nur über die Windows-API, keine macOS/Linux-Unterstützung.
+- Die Bootloader-USB-PID (`0x0043`) ist kollisionsfrei verifiziert, aber kein
+  offiziell registrierter Wert unter Adafruits VID `0x239A`.
+- Kein Software-Trigger, um aus der laufenden App heraus in den
+  Bootloader-Modus zu wechseln — nur der physische Weg (Kabel ziehen, Taste
+  halten, wieder einstecken).
+- Bootloader-Flash-Auslastung ~90 % (7364 von 8192 Byte), wenig Puffer für
+  Änderungen am Bootloader selbst.
 
-Die aktive Boarddatei benennt die MCU als `samd21g17d`, setzt für den
+Sowohl `boards/versapad_nobl.json` (SWD-Ziel) als auch `boards/versapad.json`
+(USB-Bootloader-Ziel) benennen die MCU als `samd21g17d`, setzen für den
 Arduino-Core aber weiterhin das Kompatibilitätsmakro `__SAMD21G18A__`. Der
 PlatformIO-Build meldet korrekt 128 KiB physischen Flash, 16 KiB RAM und
-129.792 Byte nutzbaren Firmwarebereich. Vor device-spezifischen
-Core-Änderungen sollte die historische Makro-Abweichung trotzdem geprüft
-werden.
+129.792 Byte (`versapad_nobl`) beziehungsweise 121.600 Byte
+(`versapad`, abzüglich 8 KiB Bootloader) nutzbaren Firmwarebereich. Vor
+device-spezifischen Core-Änderungen sollte die historische Makro-Abweichung
+trotzdem geprüft werden.
 
 ## Event-Queue hat eine feste Kapazität
 

doc/10_usb_bootloader.md

@@ -0,0 +1,104 @@
+# USB-Bootloader (UF2)
+
+Zweiter Firmware-Update-Weg neben SWD: ein UF2-Bootloader unter
+`bootloader/` erlaubt, die App-Firmware über USB zu aktualisieren, ohne
+Atmel-ICE. Der Bootloader selbst wird einmalig per SWD geflasht; danach
+reicht für App-Updates ein PlatformIO-Befehl.
+
+## Speicherlayout
+
+| Bereich | Adresse | Größe | Environment |
+|---|---|---|---|
+| Bootloader | `0x00000..0x01FFF` | 8 KiB | `versapad_bootloader` (in `bootloader/`) |
+| App-Firmware | `0x02000..0x1FAFF` | 118,75 KiB | `versapad_usb` |
+| NVM (Makros + Config) | `0x1FB00..0x1FFFF` | 1,25 KiB | — |
+
+Gleiches NVM-Layout wie beim SWD-Ziel `versapad_nobl`
+(siehe [06_nvm_config.md](06_nvm_config.md)); nur die Firmware-Obergrenze
+sinkt um die 8 KiB Bootloader. Linkerskript:
+`variants/versapad/linker_scripts/gcc/flash_with_bootloader.ld`, Boarddatei:
+`boards/versapad.json`.
+
+## Bootloader-Einstieg ohne Reset-Taster
+
+Die Platine hat keinen dedizierten Reset-/Boot-Taster. Statt eines
+physischen Pins wird die unterste rechte Cherry-MX-Taste (`key_id 24`,
+COL4 × ROW4, siehe [01_matrix.md](01_matrix.md)) beim Boot geprüft:
+`check_start_application()` in `bootloader/src/main.c` treibt ROW4 kurz auf
+LOW und liest COL4 zurück — noch vor der App-Adress-Validierung, funktioniert
+also auch bei kaputter oder fehlender App-Firmware.
+
+Bedienung: USB-Kabel ziehen, Taste gedrückt halten, wieder einstecken (Taste
+weiter halten) → Board bootet in den Massenspeicher-Modus (`VERSABOOT`).
+Ohne gehaltene Taste startet die App normal.
+
+## Bauen und Flashen
+
+Bootloader einmalig per SWD (überschreibt nur `0x0000..0x1FFF`):
+
+```bash
+cd bootloader
+pio run -e versapad_bootloader --target upload
+```
+
+Danach App-Firmware per USB (Board vorher wie oben in den Bootloader-Modus
+versetzen):
+
+```bash
+pio run -e versapad_usb --target upload
+```
+
+Baut die App, wandelt `firmware.bin` über `uf2conv.py` (Repo-Root, eigene
+minimale Implementierung, kein Upstream-Code) in `firmware.uf2` und kopiert
+es über `upload_uf2.py` aufs erkannte `VERSABOOT`-Laufwerk. Der Bootloader
+erkennt den Schreibzugriff und springt selbständig in die neue App.
+
+`upload_uf2.py` sucht das Laufwerk aktuell nur über die Windows-API
+(`GetVolumeInformationW`) — keine macOS/Linux-Unterstützung.
+
+## Herkunft und Details
+
+Der Bootloader ist abgeleitet und stark eingekürzt aus
+[microsoft/uf2-samdx1](https://github.com/microsoft/uf2-samdx1) (MIT), auf
+den `SAMD21G17D`-Chip dieses Boards zugeschnitten. Herkunft, Lizenz und
+vollständige Implementierungsdetails stehen in `bootloader/README.md`.
+
+## Hardwaretest (2026-08-05) und gefundene Bugs
+
+Kompletter Weg auf echter Hardware verifiziert: Bootloader-Flash,
+USB-Enumeration, Tastencheck-Einstieg, App-Firmware per `.uf2` schreiben,
+automatischer Rücksprung in die neue App. Details, Fehlerbilder und Fixes
+stehen in `bootloader/README.md` unter "Hardwaretest"; kurz zusammengefasst:
+
+- **Fehlende Synchronisationsbarriere beim Sprung Bootloader→App.** Der
+  Sprung (`__set_MSP` → `SCB->VTOR` → `bx`) faultete bei jedem
+  eigenständigen Boot. Fix: `__DSB(); __ISB();` vor dem `bx` in
+  `check_start_application()` — von ARM für dieses Pattern vorgeschrieben,
+  fehlte im vendorten Code.
+- **USB-PID-Kollision.** Die ursprünglich übernommene PID `0x0011` ist
+  Adafruits eigene Gemma-M0-Bootloader-PID; Windows-Rechner mit
+  installiertem Adafruit-Treiber banden das Board fälschlich als
+  `Adafruit Circuit Playground`-COM-Port statt als Massenspeicher. Fix:
+  eigene PID `0x0043`.
+- **OpenOCD-Falle beim manuellen SWD-Debuggen:** `program datei.elf verify`
+  ohne explizite Zieladresse hat wiederholt den Bootloader mit rohen
+  ELF-Datei-Bytes überschrieben, sobald Bootloader- und App-Flash im selben
+  OpenOCD-Aufruf kombiniert wurden. Bei manuellem Flashen beider Bereiche
+  immer `.bin` mit expliziter Adresse und getrennte OpenOCD-Aufrufe
+  verwenden — Details in `bootloader/README.md`, "Achtung bei manuellem
+  SWD-Flashen".
+
+## Bekannte Einschränkungen
+
+- Bootloader-Flash-Auslastung ~90 % (7364 von 8192 Byte) — wenig Puffer für
+  Änderungen am Bootloader selbst.
+- Kein Status-LED-Feedback im Bootloader-Modus (nur WS2812-Kette, dafür ist
+  der Original-Code nicht ausgelegt).
+- USB-PID `0x0043` ist kollisionsfrei verifiziert, aber kein offiziell
+  registrierter Wert unter Adafruits VID `0x239A`.
+- `upload_uf2.py` ist Windows-only (siehe oben).
+- Kein Software-Trigger, um aus der laufenden App heraus in den Bootloader
+  zurückzuspringen — nur der physische Kabel-raus/Taste-halten/Kabel-rein-Weg.
+  Wäre über einen neuen CDC-Befehl (siehe
+  [07_serial_protocol.md](07_serial_protocol.md)) nachrüstbar, der dieselbe
+  `DBL_TAP_MAGIC`-RAM-Adresse setzt und `NVIC_SystemReset()` aufruft.

doc/INDEX.md

@@ -17,6 +17,7 @@ Bereiche stehen ausdrücklich in
 | [07_serial_protocol.md](07_serial_protocol.md) | 8-Byte-Protokoll, Config-/Makro-Transfer, ACK/NACK |
 | [08_development.md](08_development.md) | Setup, Build, Einstieg nach Änderungstyp, Verifikation |
 | [09_known_limitations.md](09_known_limitations.md) | Aktuelle technische Einschränkungen und Risiken |
+| [10_usb_bootloader.md](10_usb_bootloader.md) | UF2-Bootloader, Speicherlayout, Tastencheck-Einstieg, USB-Flashweg |
 
 Die Repository-weiten Richtlinien und der kompakte LLM-Kontext stehen in
 [`../AGENTS.md`](../AGENTS.md).
@@ -29,3 +30,4 @@ Die Repository-weiten Richtlinien und der kompakte LLM-Kontext stehen in
 - Action-Semantik und HID-Hold: [03_action_engine.md](03_action_engine.md)
 - CDC-Protokoll und Chunk-Zahlen: [07_serial_protocol.md](07_serial_protocol.md)
 - bekannte Risiken vor strukturellen Änderungen: [09_known_limitations.md](09_known_limitations.md)
+- Firmware per USB statt SWD flashen: [10_usb_bootloader.md](10_usb_bootloader.md)