diff --git a/README.md b/README.md
index 9807b021..e7d013c0 100644
--- a/README.md
+++ b/README.md
@@ -1,80 +1,105 @@
 # DongLoRa
 
-Transparent LoRa radio over USB. Plug in a board, talk LoRa from your host.
+Transparent LoRa radio over USB. Plug in a supported board, talk LoRa
+from your host. The firmware is a dumb pipe — it exposes clean LoRa
+parameters (frequency, bandwidth, spreading factor, coding rate, TX power)
+and gets out of the way. No mesh logic, no protocol opinions, no config files.
+
+## Quick Start
+
+1. Get a [supported board](#supported-boards)
+2. Install toolchain (see [Building](#building))
+3. Build and flash: `just flash heltec_v4`
+4. Run an example: `uv run examples/simple_rx.py`
+5. See packets
 
 ## Supported Boards
 
-| Board | Status | MCU | Radio |
-|---|---|---|---|
-| Heltec v3 | builds | ESP32-S3 | SX1262 |
-| Heltec v4 | builds | ESP32-S3 | SX1262 |
-| RAK WisBlock / WisMesh (RAK 4631) | **firmware** | nRF52840 | SX1262 |
+| Board | MCU | Radio | Display |
+|-------|-----|-------|---------|
+| Heltec V3 | ESP32-S3 | SX1262 | SSD1306 OLED |
+| Heltec V4 | ESP32-S3 | SX1262 | SSD1315 OLED |
+| RAK WisBlock 4631 | nRF52840 | SX1262 | SSD1306 OLED (optional) |
 
-## Next Up
+## Protocol
 
-High-priority boards — popular, well-documented, should be straightforward:
+DongLoRa speaks a binary protocol over USB CDC-ACM: COBS-framed
+[postcard](https://postcard.jamesmunns.com/) messages. 8 commands,
+6 response types — everything you need to configure the radio,
+transmit, and receive.
 
-| Board | MCU | Radio | Notes |
-|---|---|---|---|
-| Heltec v2 | ESP32 | SX1276 | Xtensa, older radio |
-| Heltec Wireless Tracker (v1/v2) | ESP32-S3 | SX1262 | GPS + display |
-| Heltec Vision Master E213 / E290 | ESP32-S3 | SX1262 | E-ink display |
-| LilyGo T-Beam (SX1262) | ESP32 | SX1262 | GPS, popular |
-| LilyGo T-Beam Supreme (SX1262) | ESP32-S3 | SX1262 | GPS, newer |
-| LilyGo T-Echo | nRF52840 | SX1262 | E-ink, BLE |
-| LilyGo T3 S3 (SX126x) | ESP32-S3 | SX1262 | Common dev board |
-| RAK WisBlock 3112 | ? | SX1262 | RAK ecosystem |
-| RAK WisMesh 1W Booster (3401 + 13302) | ? | SX1262 | High power |
-| RAK WisMesh Tag | ? | SX1262 | Small form factor |
-| Seeed Studio Xiao nRF52 WIO | nRF52840 | SX1262 | Tiny |
-| Seeed Studio SenseCAP T1000-E | ? | SX1262 | Tracker |
+See **[docs/PROTOCOL.md](docs/PROTOCOL.md)** for the complete wire format
+specification with worked examples.
 
-## Future
+## Examples
 
-Lower priority or niche — contributions welcome:
+All examples use [uv](https://docs.astral.sh/uv/) for dependency management:
 
-| Board | MCU | Radio |
-|---|---|---|
-| Elecrow ThinkNode M1 / M2 / M3 / M5 / M6 | various | various |
-| GAT-IoT GAT562 30s / Tracker | ? | ? |
-| Heltec Heltec Wireless Paper | ESP32-S3 | SX1262 |
-| Heltec MeshPocket | ESP32-S3 | SX1262 |
-| Heltec MeshSolar / MeshTower | ESP32-S3 | SX1262 |
-| Heltec T114 | nRF52840 | SX1262 |
-| Heltec WSL3 | ? | ? |
-| Ikoka Nano / Stick | ? | ? |
-| Keepteen LT1 | ? | ? |
-| LilyGo T-Beam 1.2 (SX1276) | ESP32 | SX1276 |
-| LilyGo T-Deck (community) | ESP32-S3 | SX1262 |
-| LilyGo T-Echo Lite | nRF52840 | SX1262 |
-| LilyGo T3 S3 (SX127x) | ESP32-S3 | SX1276 |
-| LilyGo LoRa32 V2.1.1.6 | ESP32 | SX1276 |
-| ProMicro nRF52 (faketec) | nRF52840 | SX1262 |
-| RPI Pico 2040 + WaveShare SX1262 | RP2040 | SX1262 |
-| Seeed Studio SenseCAP Solar | ? | SX1262 |
-| Seeed Studio Wio Tracker L1 EINK / Pro | ? | SX1262 |
-| Seeed Studio Xiao C3 | ESP32-C3 | SX1262 |
-| Seeed Studio Xiao S3 WIO | ESP32-S3 | SX1262 |
-| UnitEng Nano G2 Ultra / Station G2 | ? | ? |
+| Script | Description |
+|--------|-------------|
+| [`simple_rx.py`](examples/simple_rx.py) | Configure radio, receive and print packets |
+| [`simple_tx.py`](examples/simple_tx.py) | Transmit a single packet |
+| [`ping_pong.py`](examples/ping_pong.py) | Two-dongle demo (`--role tx` / `--role rx`) |
+| [`meshcore/`](examples/meshcore/) | Full MeshCore packet decoder (advanced example) |
 
 ## Building
 
+Requires [just](https://github.com/casey/just) and Rust.
+
 ```sh
-just build-all          # build firmware for all boards with available toolchains
+just build-all          # build firmware for all boards (skips unavailable toolchains)
 just build heltec_v4    # build a specific board
-just check-all          # compile-check all boards (no firmware output)
-just flash heltec_v4    # build + flash via probe-rs
+just check-all          # compile-check only (no firmware output)
+just flash heltec_v4    # build + flash
+just clippy heltec_v4   # lint
 ```
 
-### Xtensa (ESP32) boards
+### Xtensa boards (Heltec V3/V4)
 
-Requires the [esp toolchain](https://github.com/esp-rs/espup):
+Requires the [ESP toolchain](https://github.com/esp-rs/espup):
 
 ```sh
 cargo install espup
 espup install --toolchain-version 1.82.0.3
 ```
 
-### ARM (nRF, STM32) boards
+### ARM boards (RAK 4631)
 
 Stock Rust stable. Targets are installed automatically.
+
+<details>
+<summary><strong>Board Roadmap</strong></summary>
+
+### Next Up
+
+| Board | MCU | Radio |
+|-------|-----|-------|
+| Heltec V2 | ESP32 | SX1276 |
+| Heltec Wireless Tracker | ESP32-S3 | SX1262 |
+| Heltec Vision Master E213/E290 | ESP32-S3 | SX1262 |
+| LilyGo T-Beam (SX1262) | ESP32 | SX1262 |
+| LilyGo T-Beam Supreme | ESP32-S3 | SX1262 |
+| LilyGo T-Echo | nRF52840 | SX1262 |
+| LilyGo T3 S3 | ESP32-S3 | SX1262 |
+| Seeed Studio Xiao nRF52 WIO | nRF52840 | SX1262 |
+
+### Future
+
+| Board | MCU | Radio |
+|-------|-----|-------|
+| Elecrow ThinkNode M1-M6 | various | various |
+| Heltec Wireless Paper / MeshPocket / T114 | various | SX1262 |
+| LilyGo T-Deck / T-Echo Lite / LoRa32 | various | various |
+| RAK WisBlock 3112 / WisMesh variants | various | SX1262 |
+| RPI Pico 2040 + WaveShare SX1262 | RP2040 | SX1262 |
+| Seeed Studio SenseCAP / Xiao variants | various | SX1262 |
+
+</details>
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) — Stephen Waits