Fix CS16 capture, CLI tools while connected, sample-rate range, stdout banner

- CS16 streams read into an int16 buffer; files hold raw SC16 Q11 (full
  scale 2048) instead of all zeros
- bladeRF-cli backed tools release the USB claim while they run and
  restore RX/TX settings afterwards; loopback uses the plugin setting
- calibrate_dc runs "calibrate lms" + "calibrate dc rxtx"; a bare "cal dc"
  only printed help and reported success
- report the span of all SoapySDR ranges (rate was capped at 10 Msps)
- parse "Firmware version" from bladeRF-cli 1.10
- startup banner goes to stderr, off the stdio JSON-RPC channel
- shared RX chunk reader: settle discard, overflow and stall handling,
  stream always closed; captures report overflows, clipping, peak dBFS
- spectrum power normalized to dBFS
- unit tests, README troubleshooting, version 2026.10.25

README.md

@@ -82,7 +82,7 @@ claude -p "show bladerf status" --mcp-config .mcp.json --allowedTools "mcp__mcbl
 
 ### IQ Capture
 - `bladerf_capture_iq` - Stream samples to file (CF32/CS16)
-- `bladerf_capture_spectrum` - Capture and compute FFT
+- `bladerf_capture_spectrum` - Capture and compute FFT, power in dBFS
 - `bladerf_stream_status` - Check capture progress
 - `bladerf_stop_capture` - Abort running capture
 
@@ -110,6 +110,22 @@ claude -p "show bladerf status" --mcp-config .mcp.json --allowedTools "mcp__mcbl
 [Uses bladerf_capture_spectrum]
 ```
 
+## Capture Files and Readings
+
+CF32 files are complex64 scaled to ±1.0. CS16 files are the device's raw SC16 Q11 integers, interleaved I/Q with full scale 2048, the same layout `bladeRF-cli` writes with `format=bin`. Spectrum power is dBFS, so a full-scale tone reads 0. Every capture reports `overflows` (dropped-sample events), `clipped_samples` and `peak_dbfs`, so check those before trusting the data.
+
+Gains you leave out keep whatever the device last had, including values set by another process. The radio is often shared, so set all three RX gains explicitly.
+
+While connected, the server holds the USB device and nothing else can open it. The bladeRF-cli backed tools (probe, calibrate, FPGA load, firmware flash, hardware info) release it for the duration and restore the RX/TX settings afterwards. Call `bladerf_disconnect` when you are done so other tools can use the radio.
+
+## Troubleshooting
+
+**`setupStream() -3` / `bladerf_sync_config() returned -3`.** The SoapySDR plugin was built against an older libbladeRF. libbladeRF 2025.10 inserted `BLADERF_FORMAT_SC16_Q11_PACKED` into the `bladerf_format` enum without changing the soname, so a stale `soapybladerf` requests the wrong format and bladeRF1 rejects it. Rebuild `soapybladerf` against the installed headers (the Arch PKGBUILD needs `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` under CMake 4).
+
+**`No device(s) available` (-7) with the board plugged in.** Another process has the device open. Check `pgrep -xa bladeRF-cli`; `pgrep -f` can match your own shell.
+
+**`No module named 'SoapySDR'`.** The venv must see system site-packages. Recreate it with `make setup`.
+
 ## BladeRF 1.0 x40 Specifications
 
 - Frequency: 237.5 MHz - 3.8 GHz