docs: document RepeaterBook CSV integration + live-verified CI-V findings

README.md

@@ -42,6 +42,28 @@ is up** (one process owns `/dev/ttyUSB0`). The page polls `/api/status` ~1/s for
 live frequency, mode, S-meter, squelch, and levels; controls POST to
 `/api/{freq,mode,vol,sql}`.
 
+## Repeaters (RepeaterBook CSV)
+
+The panel's **Repeaters** card lists nearby repeaters from a local `repeaters.json`,
+in RepeaterBook's proximity order, and tunes the radio (freq + duplex + tone) on tap.
+
+```bash
+# refresh the data: drop a new CSV into repeaterbook/, then re-ingest
+python3 repeaters.py ingest repeaterbook/RB_2606141409.csv repeaters.json
+```
+
+- **Data source:** a RepeaterBook CSV proximity export (download from your account for
+  your area). It has no lat/long, but it's sorted nearest-first, so row order is the rank.
+- **Filter:** keeps FM + D-STAR on 2m/70cm (drops DMR/P25/NXDN-only). ~1073 of 1258 rows.
+- **API:** `GET /api/repeaters?q=&limit=` (search + nearest-first list);
+  `POST /api/tune-repeater` (body = one record) → per-step result
+  `{ok, steps:{freq,duplex,tone_freq,tone_on}, errors}`.
+- **Offset:** the offset *amount* is **not** set over CI-V (the ID-5100 rejects it);
+  only the duplex *direction* (DUP±) is sent, and the radio applies its own configured
+  offset (standard 0.6/5 MHz). Non-standard offsets are set on the radio head.
+- **D-STAR:** DV rows tune freq/direction only — call routing (URCALL/RPT1/RPT2) is the
+  separate RS-MS1A protocol, set on the head.
+
 ## Library
 
 ```python
@@ -67,6 +89,10 @@ python3 -m unittest test_civ -v
 - **Frequency BCD is little-endian; level/meter BCD is big-endian** (`128 -> 01 28`).
 - **Mode FM = 0x05** confirmed empirically. `DV = 0x17` is from the generic
   ICOM table and **not yet verified on this radio** — confirm before relying on it.
+- **Repeater commands (verified live 2026-06-14):** duplex direction `0x0F`
+  (0x10 simplex / 0x11 DUP− / 0x12 DUP+), repeater tone `0x1B/0x00`, tone on/off
+  `0x16/0x42`. The tone wire field is **3 bytes** (`00` pad + 2-byte BCD; `00 08 85`
+  = 88.5 Hz). **Offset-amount `0x0D` is rejected (NG)** by the ID-5100 — not supported.
 - Scope is CI-V (operate the radio). D-STAR DR routing / callsign entry live in
   the separate RS-MS1A data-jack protocol, not here.
 ```