Document an OpenOCD ELF-flash pitfall found during hardware debugging

While chasing why the boot-key check stopped working, traced it to
openocd's "program <elf> verify" silently writing raw file bytes
starting at flash 0x0 instead of the ELF's own section addresses,
whenever combined with a prior bootloader write in the same OpenOCD
invocation -- repeatedly clobbering the just-flashed bootloader with
the app's ELF header. Recovered via full chip-erase and reflashing
bootloader and app as separate .bin writes with explicit addresses in
isolated OpenOCD sessions; both regions verified correct afterward and
confirmed working on hardware (key-hold entry and normal app boot).

Documented the pitfall and the safe manual-flashing rule so it doesn't
get rediscovered the expensive way again.

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

bootloader/README.md

@@ -88,6 +88,30 @@ pio run -e versapad_usb --target upload
 Baut die App-Firmware (Repo-Root, nicht `bootloader/`), erzeugt `firmware.uf2`
 und kopiert es aufs `VERSABOOT`-Laufwerk. Kein Atmel-ICE mehr nötig.
 
+## Achtung bei manuellem SWD-Flashen von Bootloader UND App
+
+`upload_openocd.py` (App, `env:versapad`) und der Bootloader-Upload (oben)
+sind sicher, weil sie jeweils nur ihren eigenen Bereich anfassen. **Beim
+manuellen Debuggen über OpenOCD-Kommandozeile aber Vorsicht:**
+
+`openocd -c "program datei.elf verify"` **ohne explizite Zieladresse** hat
+sich in dieser Kombination aus OpenOCD-Version/CMSIS-DAP-Adapter/Target-Skript
+als unzuverlässig erwiesen — statt die im ELF hinterlegten Sektionsadressen
+(`0x2000` für die App) zu nutzen, landeten die rohen Datei-Bytes teils direkt
+ab Flash-Adresse `0x0000` und haben damit den frisch geschriebenen Bootloader
+sofort wieder überschrieben (bestätigt am 2026-08-05: Byte 0 an Adresse
+`0x0000` war `0x7f`, der Beginn der ELF-Magic `\x7fELF` — die rohe Datei, kein
+Firmware-Code). Passierte zuverlässig, wenn Bootloader- und App-Flash im
+selben OpenOCD-Aufruf kombiniert wurden.
+
+**Regel für manuelles SWD-Flashen beider Bereiche:** immer die `.bin`-Datei
+verwenden (nie `.elf`) und die Zieladresse **immer explizit angeben**
+(`program firmware.bin 0x0 verify` für den Bootloader,
+`program firmware.bin 0x2000 verify` für die App), und Bootloader- und
+App-Schreibvorgang **in getrennten OpenOCD-Aufrufen**, nicht in einer
+gemeinsamen `-c`-Kommandokette. Im Zweifel danach mit `dump_image` in einer
+frischen, unabhängigen Sitzung verifizieren.
+
 ## Hardwaretest (2026-08-05)
 
 Erster vollständiger Hardwaretest auf einem echten VersaPad-v2-Board über
@@ -109,6 +133,15 @@ Atmel-ICE/SWD. Ergebnisse:
   für genau dieses Bootloader-Pattern vorgeschrieben, hat im vendorten Code
   gefehlt. Nach dem Fix bootet die App-Firmware zuverlässig, mit und ohne
   angeschlossenen Debugger.
+- **Zweiter Bug beim manuellen Debuggen gefunden:** Beim anschließenden
+  manuellen SWD-Debugging (Suche nach der Ursache des Tastencheck-Problems,
+  siehe oben) hat `openocd -c "program app.elf verify"` ohne explizite
+  Zieladresse wiederholt den Bootloader mit rohen ELF-Datei-Bytes
+  überschrieben, sobald Bootloader- und App-Flash im selben OpenOCD-Aufruf
+  kombiniert wurden — siehe "Achtung bei manuellem SWD-Flashen" oben. Nach
+  einem vollständigen Chip-Erase und getrennten `.bin`-Flashes mit expliziten
+  Adressen liefen beide Bereiche wieder zuverlässig, Tastencheck und
+  App-Start bestätigt funktionsfähig.
 - **Kompletter USB-Flashweg getestet:** `pio run -e versapad_usb --target
   upload` (App-Firmware, Repo-Root) baut `firmware.bin`, wandelt es über
   [`../uf2conv.py`](../uf2conv.py) in `firmware.uf2` und kopiert es über