docs: Pi install + pm3flash firmware flashing (README, CLAUDE, roadmap)

- README: rewrite Install (from source, submodules, deps, Pi/aarch64); new
  'Flashing firmware (pm3flash)' section — CLI usage, --build, image resolution,
  cross-compile + PLATFORM note, Raspberry Pi bring-up, programmatic API; point
  Firmware Compatibility at it; add a License section (MIT).
- CLAUDE.md: flash.py/_firmware.py/flash_cli.py in the structure; a 'Firmware
  flashing' section with the maintainer gotchas (OLD frame, fullimage-only,
  page-merge, platform != is_rdv4, the pin).
- roadmap: new 2026-07-05-firmware-flasher plan doc + a Firmware-flashing row.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -10,12 +10,18 @@ Pure-Python async client for the [Proxmark3](https://github.com/RfidResearchGrou
 
 ## Install
 
+Not on PyPI yet — install from a clone. Use `--recurse-submodules` so the firmware fork
+(`firmware/`) comes with it (needed for flashing and the live-sim features):
+
 ```bash
+git clone --recurse-submodules <repo-url> pm3py
 cd pm3py
-pip install -e .
+pip install -e .            # or `pip install .`
 ```
 
-Requires Python 3.10+ and `pyserial-asyncio>=0.6` (installed automatically).
+Requires **Python 3.10+**; dependencies (`pyserial-asyncio`, `bitarray`, `pycryptodome`)
+install automatically. It's pure Python + pyserial, so it also runs on a **Raspberry Pi**
+(aarch64) — see [Flashing firmware](#flashing-firmware-pm3flash) for the Pi bring-up.
 
 ## Quick Start
 
@@ -502,6 +508,58 @@ trace card simulation) require our firmware fork, tracked as the `firmware/` git
 submodule (`proxmark3-pm3py`, rebased onto upstream RfidResearchGroup/proxmark3).
 Those add the `CMD_HF_SNIFF_STREAM` live-frame path and the BigBuf response-table +
 WTX relay used by `SimSession`. Everything else degrades gracefully on stock firmware.
+To put the fork on your device, use [`pm3flash`](#flashing-firmware-pm3flash) (below).
+
+## Flashing firmware (`pm3flash`)
+
+The live features (streaming sniff, response-table/trace card sim, `hw.led`) need the
+**firmware fork** (`proxmark3-pm3py`, the `firmware/` submodule). pm3py flashes it for you
+over USB — a pure-Python flasher, no C `pm3-flash`/DFU/JTAG. Each pm3py release is pinned to
+a firmware build, and `pm3.firmware.matches_pin` tells you whether your device runs it.
+
+```bash
+pm3flash                        # detect the device; flash the pinned firmware if it differs
+pm3flash --image fullimage.elf  # flash a specific prebuilt image
+pm3flash --build PM3GENERIC     # build from the submodule (Easy), then flash
+pm3flash --force                # flash even if the device already matches the pin
+```
+
+`pm3flash` auto-detects the port, compares the device firmware to the pin, then (fullimage
+only) flashes and verifies. It's **bootrom-safe** — it never writes the bootloader, so a bad
+flash is recoverable, not a brick.
+
+Image resolution order: `--image`, then `$PM3PY_FIRMWARE`, then a local build at
+`firmware/armsrc/obj/fullimage.elf`. Build one with:
+
+```bash
+make -C firmware PLATFORM=PM3GENERIC armsrc/all   # PM3 Easy / generic
+make -C firmware PLATFORM=PM3RDV4  armsrc/all     # RDV4
+```
+
+The firmware is an ARM **cross-compile** (needs `gcc-arm-none-eabi` + `make`; the FPGA
+bitstream is committed, so no FPGA toolchain), and the `fullimage.elf` it produces is the
+same regardless of build host. **Choose `PLATFORM` yourself** — pm3py can't infer it, because
+a device's `is_rdv4` flag reports the firmware it's running, not the physical board.
+
+**On a Raspberry Pi:** `pip install` pm3py on the Pi (works on aarch64), then either
+cross-build on another Linux box and copy the image over —
+
+```bash
+make -C firmware PLATFORM=PM3GENERIC armsrc/all      # dev box
+scp firmware/armsrc/obj/fullimage.elf pi@rpi:~/
+pm3flash --image ~/fullimage.elf                     # on the Pi
+```
+
+— or build on the Pi itself (with `gcc-arm-none-eabi` + `make`): `pm3flash --build PM3GENERIC`.
+
+**Programmatic** (the CLI wraps `pm3.flasher`):
+
+```python
+pm3 = Proxmark3.sync()
+pm3.firmware.matches_pin            # False -> not on the pinned build
+pm3.firmware.expected_firmware      # the pinned firmware id
+pm3.flasher.flash("firmware/armsrc/obj/fullimage.elf")   # enter bootloader, write, reset, verify
+```
 
 ## Architecture
 
@@ -551,3 +609,7 @@ python -m pytest tests/ -v
 ```
 
 All tests use mock transports — **no hardware required**.
+
+## License
+
+MIT — see [LICENSE](LICENSE).