[chore](trx-rs): move autogenerated spec docs into autogendoc/

Keeps README.md, CLAUDE.md, and CONTRIBUTING.md at root as standard project files. Moves AI-generated design/specification documents (AGENTS, AUTH, CONFIGURATION, ENHANCEMENT, MULTI, OVERVIEW, SDR, UI-CAPS) into autogendoc/ to distinguish them from hand-maintained docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Stan Grams <sjg@haxx.space>
2026-02-25 08:11:38 +01:00
parent d7d2b3f790
commit eec5aaf811
8 changed files with 0 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Workspace root contains `Cargo.toml`, `README.md`, and contributor docs.
+- Core crates live under `src/`: `src/trx-core`, `src/trx-server`, and `src/trx-client`.
+- Server backends are under `src/trx-server/trx-backend` (example: `trx-backend-ft817`).
+- Client frontends are under `src/trx-client/trx-frontend` (HTTP, JSON, rigctl).
+- Examples live in `examples/` and static assets in `assets/`.
+- Reference configs are `trx-server.toml.example` and `trx-client.toml.example`.
+
+## Build, Test, and Development Commands
+- `cargo build --release` builds optimized binaries.
+- `cargo test` runs the workspace test suite.
+- `cargo clippy` runs lint checks.
+- Example server run (release build): `./target/release/trx-server -r ft817 "/dev/ttyUSB0 9600"`.
+
+## Coding Style & Naming Conventions
+- Rust standard style: 4-space indentation and rustfmt-compatible formatting.
+- Naming: `snake_case` for modules/functions, `CamelCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
+- Prefer small, crate-focused commits; keep changes localized to the relevant crate.
+
+## Testing Guidelines
+- Tests are run via `cargo test` across the workspace.
+- Add tests near the code they cover (module-level unit tests are preferred).
+- If you change behavior in a crate, add or update tests in that crate.
+
+## Commit & Pull Request Guidelines
+- Commit title format: `[<type>](<crate>): <description>` (example: `[fix](trx-frontend-http): handle disconnect`).
+- Use `(trx-rs)` for repo-wide changes that are not specific to any crate.
+- Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+- Use imperative mood, keep lines under 80 chars, and separate body with a blank line.
+- Sign commits with `git commit -s` and include `Co-authored-by:` for LLM assistance.
+- Write isolated commits for each crate.
+- Pull requests should include a clear summary, test status, and note any config or runtime changes.
+
+## Contribution Workflow
+- Fork the repository and create a new branch for your changes.
+- Follow the project's coding style and conventions.
+- Ensure changes are tested and pass existing tests.
+
+## Configuration & Plugins
+- Configs use TOML. See the example files for required sections and defaults.
+- Plugins can be loaded from `./plugins`, `~/.config/trx-rs/plugins`, or `TRX_PLUGIN_DIRS`.
@@ -0,0 +1,190 @@
+# HTTP Frontend Authentication Draft
+
+## Goal
+Add optional passphrase authentication for `trx-frontend-http` with two roles:
+- `rx` passphrase: read-only access
+- `control` passphrase: read + control (RX+TX)
+
+API/control routes stay locked until a user logs in from the web UI.
+
+This design keeps current behavior when auth is disabled.
+
+## Scope
+- Protect HTTP API endpoints used by the web UI.
+- Protect SSE (`/events`, `/decode`) and audio WebSocket (`/audio`).
+- Keep static assets and login page accessible so user can authenticate.
+- Do not change rigctl/http_json auth behavior in this draft.
+
+## Security Model
+- Two optional passphrases configured locally (`rx`, `control`).
+- On successful login, server issues short-lived session cookie.
+- Session required for all protected routes, with role attached.
+- Brute-force mitigation via simple per-IP rate limiting.
+- TX access can be globally hidden/blocked unless `control` role is present.
+
+This is not multi-user IAM; it is a pragmatic local/ham-shack gate.
+
+## Config Proposal
+Add to `trx-client.toml`:
+
+```toml
+[frontends.http.auth]
+enabled = false
+# Plaintext passphrases (as requested)
+rx_passphrase = "rx-only-passphrase"
+control_passphrase = "full-control-passphrase"
+
+# If true, TX/PTT controls/endpoints are never available without control auth.
+tx_access_control_enabled = true
+
+# Session lifetime in minutes
+session_ttl_min = 480
+
+# Cookie security
+cookie_secure = false      # true if served via HTTPS
+cookie_same_site = "Lax"  # Strict|Lax|None
+```
+
+Validation rules:
+- If `enabled=false`, all auth fields ignored.
+- If `enabled=true`, require at least one passphrase (`rx` and/or `control`).
+- `rx_passphrase` only: read-only deployment.
+- `control_passphrase` only: control-capable deployment.
+- both set: mixed deployment with role split.
+
+Behavior by mode:
+- `enabled=false` (default): no authentication, current behavior unchanged.
+- `enabled=true`: authentication enforced per role/route rules in this document.
+
+## Runtime Structures
+Add in `src/trx-client/trx-frontend/src/lib.rs` (or HTTP crate-local state):
+- `HttpAuthConfig`:
+  - `enabled: bool`
+  - `rx_passphrase: Option<String>`
+  - `control_passphrase: Option<String>`
+  - `tx_access_control_enabled: bool`
+  - `session_ttl: Duration`
+  - `cookie_secure: bool`
+  - `same_site: SameSite`
+- `SessionStore` in-memory map:
+  - key: random session id (128-bit+)
+  - value: `{ role, issued_at, expires_at, last_seen, ip_hash? }`
+
+Role enum:
+- `AuthRole::Rx`
+- `AuthRole::Control`
+
+Periodic cleanup task (e.g., every 5 min) removes expired sessions.
+
+## Route Design
+New endpoints:
+- `POST /auth/login`
+  - body: `{ "passphrase": "..." }`
+  - server checks passphrase against `control` first, then `rx`
+  - on success: set `HttpOnly` cookie `trx_http_sid`, return `{ role: "rx"|"control" }`
+  - on failure: 401 generic error
+- `POST /auth/logout`
+  - clears cookie and invalidates server session
+- `GET /auth/session`
+  - returns `{ authenticated: true|false, role?: "rx"|"control" }`
+
+Protected existing endpoints:
+- Control APIs (`control` role required): `/set_freq`, `/set_mode`, `/set_ptt`, `/toggle_power`, `/toggle_vfo`, `/lock`, `/unlock`, `/set_tx_limit`, `/toggle_*_decode`, `/clear_*_decode`, CW tuning endpoints, etc.
+- Read APIs (`rx` or `control`): `/status`, `/events`, `/decode`, `/audio`
+
+TX/PTT hard-gate behavior when `tx_access_control_enabled=true`:
+- Do not render TX/PTT controls for unauthenticated or `rx` role.
+- Reject TX/PTT and mutating control endpoints unless role is `control`.
+- Prefer returning `404` for hidden TX/PTT endpoints to avoid capability leakage
+  (or `403` if explicit error semantics are preferred).
+
+Public endpoints:
+- `/` (HTML shell)
+- static assets (`/style.css`, `/app.js`, plugin js, logo, favicon)
+- `/auth/*`
+
+## Middleware Behavior
+Implement Actix middleware/wrap fn in `trx-frontend-http`:
+- Resolve session from cookie.
+- Validate in store and expiry.
+- If missing/invalid:
+  - API routes: return `401` JSON/text
+  - SSE/WS routes: return `401`
+- If valid:
+  - enforce route role (`rx` or `control`)
+  - return `403` when authenticated but role is insufficient
+  - continue request
+  - optionally slide expiry (`last_seen + ttl`) with cap.
+
+Keep middleware route-aware by checking request path against allowlist.
+
+## Passphrase Handling
+- Use exact passphrase comparison against config values (no hash layer in this draft).
+- Still use constant-time string comparison helper to reduce timing leakage.
+- Keep passphrases out of logs and API responses.
+
+## Cookie Settings
+Session cookie:
+- `HttpOnly=true`
+- `Secure` configurable (true for TLS)
+- `SameSite=Lax` default
+- `Path=/`
+- Max-Age = session TTL
+
+## Frontend Flow
+In `assets/web/app.js`:
+1. On startup call `/auth/session`.
+2. If unauthenticated, show blocking screen with logo + `Access denied`.
+3. Submit to `/auth/login`.
+4. On success initialize normal app flow (`connect()`, decode stream).
+5. If role is `rx`, disable/hide all TX/PTT/mutating controls.
+6. If role is `control`, enable full UI.
+7. If protected call returns 401/403, stop streams and return to login panel.
+8. Add logout button in About tab or header.
+
+UI minimal requirement:
+- Default unauthenticated view: logo + `Access denied` + passphrase field + login button.
+- Generic error message on failure.
+- No passphrase persistence in localStorage.
+
+## Implementation Steps
+1. Extend client config structs + parser defaults.
+2. Build auth state (passphrases + session store) in HTTP server startup.
+3. Add `/auth/login`, `/auth/logout`, `/auth/session` handlers.
+4. Add middleware and protect selected routes.
+5. Update frontend JS with login gate and 401 handling.
+6. Add docs to `README.md` + `trx-client.toml.example`.
+7. Add role matrix tests and frontend role UI handling.
+
+## Test Plan
+Unit tests:
+- Config validation combinations.
+- Login success/failure.
+- Session expiry.
+- Middleware path allowlist/protection.
+- Role enforcement (`rx` denied on control routes).
+- TX visibility policy (`tx_access_control_enabled`) endpoint behavior.
+
+Integration tests (Actix test server):
+- Unauthed call to `/set_freq` -> 401.
+- `rx` login -> cookie set -> `/status` accepted, `/set_freq` -> 403.
+- `control` login -> `/set_freq` accepted.
+- With `tx_access_control_enabled=true`, unauth/`rx` cannot use `/set_ptt`.
+- Expired session -> 401.
+- `/events` and `/audio` reject unauthenticated clients.
+
+Manual checks:
+- Browser login works.
+- WSJT-X/hamlib unaffected (non-http frontends).
+- Auth disabled mode behaves exactly as before.
+
+## Operational Notes
+- This is in-memory session state. Restart invalidates sessions.
+- For reverse proxy deployments, use TLS and set `cookie_secure=true`.
+- If remote exposure is possible, use strong passphrase and firewall.
+
+## Future Extensions
+- Optional API bearer token for automation scripts.
+- Optional migration to hashed passphrases if threat model increases.
+- Persistent sessions with signed tokens/JWT (if needed).
+- Optional TOTP second factor for internet-exposed deployments.
@@ -0,0 +1,225 @@
+# Configuration
+
+This document lists all currently supported configuration options for `trx-server` and `trx-client`.
+
+## File Locations
+
+### `trx-server`
+Configuration lookup order:
+1. `--config <FILE>`
+2. `./trx-server.toml`
+3. `~/.trx-server.toml`
+4. `~/.config/trx-rs/server.toml`
+5. `/etc/trx-rs/server.toml`
+
+### `trx-client`
+Configuration lookup order:
+1. `--config <FILE>`
+2. `./trx-client.toml`
+3. `~/.config/trx-rs/client.toml`
+4. `/etc/trx-rs/client.toml`
+
+CLI options override file values.
+
+## Environment Variables
+
+- `TRX_PLUGIN_DIRS`: additional plugin directories (path-separated), used by both server and client.
+
+## `trx-server` Options
+
+### `[general]`
+- `callsign` (`string`, default: `"N0CALL"`)
+- `log_level` (`string`, optional): one of `trace|debug|info|warn|error`
+- `latitude` (`float`, optional): `-90..=90`
+- `longitude` (`float`, optional): `-180..=180`
+
+Notes:
+- `latitude` and `longitude` must be set together or both omitted.
+
+### `[rig]`
+- `model` (`string`, required effectively unless provided by CLI `--rig`)
+- `initial_freq_hz` (`u64`, default: `144300000`, must be `> 0`)
+- `initial_mode` (`string`, default: `"USB"`): one of `LSB|USB|CW|CWR|AM|WFM|FM|DIG|PKT`
+
+### `[rig.access]`
+- `type` (`string`, default behavior: `serial` if omitted): `serial|tcp|sdr`
+- Serial mode:
+  - `port` (`string`)
+  - `baud` (`u32`)
+- TCP mode:
+  - `host` (`string`)
+  - `tcp_port` (`u16`)
+- SDR mode:
+  - `args` (`string`, required when `type = "sdr"`): SoapySDR device args string (e.g. `"driver=rtlsdr"` or `"driver=airspy,serial=00000001"`). Passed verbatim to `SoapySDR::Device::new()`.
+
+Notes:
+- For `serial`, both `port` and `baud` are required.
+- For `tcp`, both `host` and `tcp_port` are required.
+- For `sdr`, `args` must be non-empty. The `port`, `baud`, `host`, and `tcp_port` fields are ignored.
+
+### `[behavior]`
+- `poll_interval_ms` (`u64`, default: `500`, must be `> 0`)
+- `poll_interval_tx_ms` (`u64`, default: `100`, must be `> 0`)
+- `max_retries` (`u32`, default: `3`, must be `> 0`)
+- `retry_base_delay_ms` (`u64`, default: `100`, must be `> 0`)
+
+### `[listen]`
+- `enabled` (`bool`, default: `true`)
+- `listen` (`ip`, default: `127.0.0.1`)
+- `port` (`u16`, default: `4530`, must be `> 0` when enabled)
+
+### `[listen.auth]`
+- `tokens` (`string[]`, default: `[]`)
+
+Notes:
+- Empty token strings are invalid.
+- Empty list means no auth required.
+
+### `[audio]`
+- `enabled` (`bool`, default: `true`)
+- `listen` (`ip`, default: `127.0.0.1`)
+- `port` (`u16`, default: `4531`, must be `> 0` when enabled)
+- `rx_enabled` (`bool`, default: `true`)
+- `tx_enabled` (`bool`, default: `true`)
+- `device` (`string`, optional)
+- `sample_rate` (`u32`, default: `48000`, valid: `8000..=192000`)
+- `channels` (`u8`, default: `1`, valid: `1|2`)
+- `frame_duration_ms` (`u16`, default: `20`, valid: `3|5|10|20|40|60`)
+- `bitrate_bps` (`u32`, default: `24000`, must be `> 0`)
+
+Notes:
+- When `[audio].enabled = true`, at least one of `rx_enabled` or `tx_enabled` must be true.
+
+### `[pskreporter]`
+- `enabled` (`bool`, default: `false`)
+- `host` (`string`, default: `"report.pskreporter.info"`, must not be empty when enabled)
+- `port` (`u16`, default: `4739`, must be `> 0` when enabled)
+- `receiver_locator` (`string`, optional)
+
+Notes:
+- If `receiver_locator` is omitted, server tries deriving it from `[general].latitude`/`longitude`.
+- PSK Reporter software ID is hardcoded to: `trx-server v<version> by SP2SJG`.
+
+### `[aprsfi]`
+- `enabled` (`bool`, default: `false`)
+- `host` (`string`, default: `"rotate.aprs.net"`, must not be empty when enabled)
+- `port` (`u16`, default: `14580`, must be `> 0` when enabled)
+- `passcode` (`i32`, default: `-1`)
+
+Notes:
+- When `passcode = -1` (the default), the passcode is auto-computed from `[general].callsign` using the standard APRS-IS hash algorithm.
+- `[general].callsign` must be non-empty when `[aprsfi].enabled = true`; otherwise the IGate is silently disabled at startup.
+- Only APRS packets with valid CRC are forwarded; packets from other decoders (FT8, WSPR, CW) are ignored.
+- The IGate reconnects automatically with exponential backoff (1 s → 2 s → … → 60 s) on TCP errors.
+- Requires `[audio].enabled = true` (APRS packets are decoded from audio).
+
+### `[sdr]`
+- `sample_rate` (`u32`, default: `1920000`, must be `> 0`): IQ capture rate in Hz. Must be supported by the device.
+- `bandwidth` (`u32`, default: `1500000`): Hardware IF filter bandwidth in Hz.
+- `center_offset_hz` (`i64`, default: `100000`): The SDR tunes this many Hz below the dial frequency to keep the signal off the DC spur. Negative values tune above.
+
+### `[sdr.gain]`
+- `mode` (`string`, default: `"auto"`): `"auto"` enables hardware AGC (falls back to `"manual"` with a warning if the device does not support it); `"manual"` uses the fixed `value`.
+- `value` (`f64`, default: `30.0`): Gain in dB. Used only when `mode = "manual"`.
+
+### `[[sdr.channels]]`
+
+Defines one virtual receiver channel within the wideband IQ stream. At least one channel is required when using the `soapysdr` backend. The **first** channel in the list is the *primary* channel: `set_freq` and `set_mode` from rig control apply to it, and `get_status` reads from it.
+
+- `id` (`string`, default: `""`): Human-readable label used in logs.
+- `offset_hz` (`i64`, default: `0`): Frequency offset from the dial frequency in Hz. Primary channel should be `0`.
+- `mode` (`string`, default: `"auto"`): Demodulation mode. `"auto"` follows the RigCat `set_mode` command; or a fixed mode string: `LSB`, `USB`, `CW`, `CWR`, `AM`, `WFM`, `FM`, `DIG`, `PKT`.
+- `audio_bandwidth_hz` (`u32`, default: `3000`): One-sided bandwidth of the post-demodulation audio BPF in Hz.
+- `fir_taps` (`usize`, default: `64`): FIR filter tap count. Higher values give sharper roll-off at the cost of latency.
+- `cw_center_hz` (`u32`, default: `700`): CW tone centre frequency in the audio domain (Hz).
+- `wfm_bandwidth_hz` (`u32`, default: `75000`): Pre-demodulation filter bandwidth for WFM only (Hz).
+- `decoders` (`string[]`, default: `[]`): Decoder IDs that receive this channel's PCM audio. Valid values: `"ft8"`, `"wspr"`, `"aprs"`, `"cw"`. Each decoder ID may appear in at most one channel.
+- `stream_opus` (`bool`, default: `false`): Encode this channel's audio as Opus and stream to clients over the TCP audio port. At most one channel may set this to `true`.
+
+Notes:
+- Requires `libSoapySDR` installed (`brew install soapysdr` on macOS; `libsoapysdr-dev` on Debian/Ubuntu).
+- The SDR backend is RX-only. `[audio] tx_enabled` must be `false`.
+- Channel IF constraint: `|center_offset_hz + offset_hz| < sample_rate / 2` for every channel; violated channels cause a startup error.
+- `[audio] sample_rate` must match the output audio rate of the SDR pipeline (48000 Hz recommended).
+- Use `trx-server --print-config` to see all defaults. SDR fields appear only if the binary was built with `--features soapysdr`.
+
+### `[decode_logs]`
+- `enabled` (`bool`, default: `false`)
+- `dir` (`string`, default: `"$XDG_DATA_HOME/trx-rs/decoders"`; fallback: `"logs/decoders"`, must not be empty when enabled)
+- `aprs_file` (`string`, default: `"TRXRS-APRS-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
+- `cw_file` (`string`, default: `"TRXRS-CW-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
+- `ft8_file` (`string`, default: `"TRXRS-FT8-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
+- `wspr_file` (`string`, default: `"TRXRS-WSPR-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
+
+Notes:
+- Decoder logs are server-side and split by decoder name (APRS/CW/FT8/WSPR).
+- Files are appended in JSON Lines format (one JSON object per line).
+- Supported filename date tokens: `%YYYY%`, `%MM%`, `%DD%` (UTC date).
+
+## `trx-client` Options
+
+### `[general]`
+- `callsign` (`string`, default: `"N0CALL"`)
+- `log_level` (`string`, optional): one of `trace|debug|info|warn|error`
+
+### `[remote]`
+- `url` (`string`, optional in file but required at runtime unless provided by CLI `--url`)
+- `poll_interval_ms` (`u64`, default: `750`, must be `> 0`)
+
+### `[remote.auth]`
+- `token` (`string`, optional)
+
+Notes:
+- If provided, token must not be empty/whitespace.
+
+### `[frontends.http]`
+- `enabled` (`bool`, default: `true`)
+- `listen` (`ip`, default: `127.0.0.1`)
+- `port` (`u16`, default: `8080`, must be `> 0` when enabled)
+
+### `[frontends.rigctl]`
+- `enabled` (`bool`, default: `false`)
+- `listen` (`ip`, default: `127.0.0.1`)
+- `port` (`u16`, default: `4532`, must be `> 0` when enabled)
+
+### `[frontends.http_json]`
+- `enabled` (`bool`, default: `true`)
+- `listen` (`ip`, default: `127.0.0.1`)
+- `port` (`u16`, default: `0`)
+- `auth.tokens` (`string[]`, default: `[]`)
+
+Notes:
+- `port = 0` means ephemeral bind (allowed).
+- Empty token strings are invalid.
+
+### `[frontends.audio]`
+- `enabled` (`bool`, default: `true`)
+- `server_port` (`u16`, default: `4531`, must be `> 0` when enabled)
+- `bridge.enabled` (`bool`, default: `false`): enables local `cpal` audio bridge
+- `bridge.rx_output_device` (`string`, optional): exact local playback device name
+- `bridge.tx_input_device` (`string`, optional): exact local capture device name
+- `bridge.rx_gain` (`float`, default: `1.0`, must be finite and `>= 0`)
+- `bridge.tx_gain` (`float`, default: `1.0`, must be finite and `>= 0`)
+
+Notes:
+- The bridge is intended for local WSJT-X integration via virtual audio devices.
+- Linux: typically use ALSA loopback (`snd-aloop`).
+- macOS: install a virtual CoreAudio device (e.g. BlackHole), then set device names above.
+
+## CLI Override Summary
+
+### `trx-server`
+- `--config`, `--print-config`
+- `--rig`, `--access`, positional `RIG_ADDR`
+- `--callsign`
+- `--listen`, `--port` (JSON listener)
+- SDR backend: all SDR options are file-only (`[sdr]` and `[[sdr.channels]]`).
+
+### `trx-client`
+- `--config`, `--print-config`
+- `--url`, `--token`, `--poll-interval`
+- `--frontend` (comma-separated)
+- `--http-listen`, `--http-port`
+- `--rigctl-listen`, `--rigctl-port`
+- `--http-json-listen`, `--http-json-port`
+- `--callsign`
@@ -0,0 +1,69 @@
+# Top 5 Real Architecture Issues (Post-Refactor)
+
+## 1) Plugin ABI is still brittle and unversioned
+### Files
+- `src/trx-app/src/plugins.rs`
+- `examples/trx-plugin-example/src/lib.rs`
+
+### Why this matters
+Plugin loading is now explicit (good), but still assumes exact symbol names and raw FFI contracts with no ABI/version handshake. A plugin built against an older/newer ABI can fail at runtime in hard-to-diagnose ways.
+
+### Fix steps
+1. Add an ABI version symbol/handshake (`trx_plugin_abi_version`) and reject incompatible plugins with clear errors.
+2. Split plugin capability metadata (backend/frontend/both) from registration symbols to avoid noisy failed-load logs.
+3. Provide a tiny shared plugin-API crate for stable entrypoint signatures.
+
+## 2) Runtime supervision is still ad-hoc (sleep + abort)
+### Files
+- `src/trx-server/src/main.rs`
+- `src/trx-client/src/main.rs`
+
+### Why this matters
+Shutdown is coordinated, but supervision still uses a fixed delay plus manual `abort()` over `Vec<JoinHandle<_>>`. This can mask task failures, race shutdown ordering, and make lifecycle behavior harder to reason about.
+
+### Fix steps
+1. Move to `JoinSet` (or a small supervisor type) for task ownership and result handling.
+2. Replace fixed sleep with bounded graceful-join timeout logic.
+3. Surface task failure reasons consistently in one place.
+
+## 3) JSON/TCP transport logic is duplicated across modules
+### Files
+- `src/trx-server/src/listener.rs`
+- `src/trx-client/trx-frontend/trx-frontend-http-json/src/server.rs`
+- `src/trx-client/src/remote_client.rs`
+
+### Why this matters
+`read_limited_line`, timeout handling, and response write patterns are repeated in multiple places. This increases drift risk and makes protocol hardening changes expensive.
+
+### Fix steps
+1. Extract shared JSON-over-TCP helpers into `trx-protocol` (or a small transport crate/module).
+2. Keep one source of truth for max line size, timeout behavior, and framing errors.
+3. Cover shared transport with focused tests once instead of per-module copies.
+
+## 4) Boundary tests are present but mostly ignored in constrained envs
+### Files
+- `src/trx-server/src/listener.rs`
+- `src/trx-client/src/remote_client.rs`
+- `src/trx-client/trx-frontend/trx-frontend-http-json/src/server.rs`
+
+### Why this matters
+Important network-path tests exist, but are marked `#[ignore]` in this environment due bind restrictions. Without a clear CI strategy, regressions can still slip through.
+
+### Fix steps
+1. Add CI jobs/environment where bind-based tests run by default.
+2. Split pure transport logic from socket bind/accept so more behavior can be tested without real sockets.
+3. Keep ignored tests minimal and document how/when they run.
+
+## 5) Decode/history shared state still relies on global mutexes
+### Files
+- `src/trx-server/src/audio.rs`
+- `src/trx-client/trx-frontend/src/lib.rs`
+- `src/trx-client/trx-frontend/trx-frontend-http/src/audio.rs`
+
+### Why this matters
+History/state paths still use shared mutex-backed globals/contexts with `expect` on lock poisoning in hot paths. This is workable but fragile for long-running async services.
+
+### Fix steps
+1. Replace panic-on-poison lock usage with resilient handling.
+2. Consider bounded channel or lock-free append/read model for decode history.
+3. Define explicit ownership/lifetime for history data instead of implicit shared mutation.
@@ -0,0 +1,156 @@
+# Multi-Rig Support
+
+This document specifies the requirements for running N simultaneous rig backends in one `trx-server` process and the protocol/config changes required to support them.
+
+---
+
+## Progress
+
+> **For AI agents:** This section is the single source of truth for implementation status.
+> Each task has a unique ID (e.g. `MR-01`), a status badge, a description, the files it touches, and any blocking dependencies.
+>
+> Status legend: `[ ]` not started · `[~]` in progress · `[x]` done · `[!]` blocked
+
+### Foundational (parallel)
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| MR-01 | `[x]` | Add `rig_id: Option<String>` to `ClientEnvelope`; add `rig_id: Option<String>` to `ClientResponse`; add `ClientCommand::GetRigs`; add `GetRigsResponseBody` + `RigEntry`; add sentinel arm in `mapping.rs` | `src/trx-protocol/src/types.rs`, `mapping.rs`, `lib.rs` | — |
+| MR-02 | `[x]` | Add `RigInstanceConfig`; add `rigs: Vec<RigInstanceConfig>` to `ServerConfig`; implement `resolved_rigs()`; extend `validate()` for unique IDs + unique audio ports | `src/trx-server/src/config.rs` | — |
+| MR-03 | `[x]` | Remove four `OnceLock` statics from `audio.rs`; add `DecoderHistories { aprs, ft8, wspr }` struct + `new()`; convert history free-fns to take `&DecoderHistories`; update decoder task signatures + `run_audio_listener` | `src/trx-server/src/audio.rs` | — |
+| MR-04 | `[x]` | Create `src/trx-server/src/rig_handle.rs` with `RigHandle { rig_id, rig_tx, state_rx }`; declare mod in `main.rs` | `src/trx-server/src/rig_handle.rs`, `main.rs` | — |
+
+### Sequential
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| MR-05 | `[x]` | Add `rig_id: String` + `histories: Arc<DecoderHistories>` to `RigTaskConfig`; fix `clear_*_history` calls in `process_command` | `src/trx-server/src/rig_task.rs` | MR-03 |
+| MR-06 | `[x]` | Rewrite `run_listener` to take `Arc<HashMap<String, RigHandle>>` + `default_rig_id`; route by `envelope.rig_id`; add `GetRigs` fast path; populate `rig_id` in every `ClientResponse` | `src/trx-server/src/listener.rs` | MR-01, MR-04 |
+| MR-07 | `[x]` | Rewrite `main.rs` spawn loop over `resolved_rigs()`; extract `spawn_rig_audio_stack()`; per-rig pskreporter + aprsfi; build `HashMap<String, RigHandle>`; pass to `run_listener` | `src/trx-server/src/main.rs` | MR-02–06 |
+
+### Tests
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| MR-08 | `[x]` | Config tests: `resolved_rigs()` with multi-rig TOML and legacy TOML; duplicate ID/port rejection | `src/trx-server/src/config.rs` | MR-02 |
+| MR-09 | `[x]` | Protocol tests: `ClientEnvelope` absent `rig_id` parses; `rig_id` in responses; `GetRigs` round-trip; existing tests still pass | `src/trx-protocol/src/codec.rs` | MR-01 |
+
+---
+
+## Goals
+
+- Run N simultaneous rig backends (SDR, transceivers, or any mix) in one server process
+- Route control commands to the correct rig via `rig_id` in the JSON protocol
+- Backward compatibility: single-rig configs (`[rig]`/`[audio]` at top level) continue to work unchanged
+- Per-rig audio streaming on separate TCP ports
+- New `GetRigs` command to enumerate all connected rigs and their states
+
+---
+
+## Non-Goals
+
+- Load-balancing or failover between rigs
+- Sharing a single audio port across multiple rigs (each rig keeps its own port)
+
+---
+
+## Architecture
+
+```
+Single [listen] port (4530)
+  └─ listener.rs: Arc<HashMap<rig_id, RigHandle>>
+       ├─ route by envelope.rig_id  (absent → first rig, backward compat)
+       └─ GetRigs → aggregate all states
+
+Per-rig:
+  rig_task ←→ RigHandle (rig_tx + state_rx)
+  audio capture → pcm_tx → decoder tasks → decode_tx
+  run_audio_listener (own TCP port per rig)
+  pskreporter + aprsfi tasks
+```
+
+---
+
+## TOML Format
+
+### Multi-rig (`[[rigs]]` array)
+
+```toml
+[general]
+callsign = "W1AW"
+
+[listen]
+port = 4530
+
+[[rigs]]
+id = "hf"
+[rigs.rig]
+model = "ft450d"
+initial_freq_hz = 14074000
+[rigs.rig.access]
+type = "serial"
+port = "/dev/ttyUSB0"
+baud = 9600
+[rigs.audio]
+port = 4531
+
+[[rigs]]
+id = "sdr"
+[rigs.rig]
+model = "soapysdr"
+[rigs.rig.access]
+type = "sdr"
+args = "driver=rtlsdr"
+[rigs.audio]
+port = 4532
+[rigs.sdr]
+sample_rate = 1920000
+```
+
+### Legacy (flat `[rig]` + `[audio]`) — continues to work unchanged
+
+```toml
+[rig]
+model = "ft817"
+[rig.access]
+type = "serial"
+port = "/dev/ttyUSB0"
+baud = 9600
+[audio]
+port = 4531
+```
+
+Legacy configs are synthesised into a single-element `[[rigs]]` list with `id = "default"` via `resolved_rigs()`.
+
+---
+
+## Protocol Wire Format
+
+Request (`rig_id` optional; absent = first rig):
+```json
+{"rig_id": "hf", "cmd": "set_freq", "freq_hz": 14074000}
+{"cmd": "get_state"}
+```
+
+Response (`rig_id` always present):
+```json
+{"success": true, "rig_id": "hf", "state": {...}}
+{"success": false, "rig_id": "default", "error": "Unknown rig_id: xyz"}
+```
+
+`GetRigs` response:
+```json
+{"success": true, "rig_id": "server", "rigs": [
+  {"rig_id": "hf",  "state": {...}},
+  {"rig_id": "sdr", "state": {...}}
+]}
+```
+
+---
+
+## Validation Rules (startup)
+
+- When `[[rigs]]` is non-empty: each `id` must be unique (case-sensitive).
+- When `[[rigs]]` is non-empty: each `audio.port` must be unique.
+- When `[[rigs]]` is empty: legacy flat fields are used with `id = "default"`.
+- Mixing `[[rigs]]` and legacy flat `[rig]`/`[audio]` is undefined; `[[rigs]]` takes precedence.
@@ -0,0 +1,326 @@
+# trx-rs Project Overview
+
+## What is trx-rs?
+
+**trx-rs** is a modular transceiver (radio) control stack written in Rust. It provides a backend service for controlling amateur radio transceivers via CAT (Computer-Aided Transceiver) protocols, with multiple frontend interfaces for access and monitoring.
+
+### Current Capabilities
+
+| Feature | Status |
+|---------|--------|
+| Yaesu FT-817 CAT control | Implemented |
+| HTTP/Web UI with SSE | Implemented |
+| rigctl-compatible TCP | Implemented |
+| VFO A/B switching | Implemented |
+| PTT control | Implemented |
+| Signal/TX power metering | Implemented |
+| Front panel lock | Implemented |
+| Multiple rig backends | Extensible (only FT-817) |
+| Backend/frontend registry | Implemented |
+| TCP CAT transport | Partial (config wiring only) |
+| JSON TCP control (line-delimited) | Implemented (configurable frontend) |
+| Plugin registry loading | Implemented (shared libraries) |
+| Configuration file (TOML) | Implemented |
+| Rig state machine | Implemented |
+| Command handlers | Implemented |
+| Event notifications | Implemented (rig task emits events) |
+| Retry/polling policies | Implemented |
+| Controller-based rig task | Implemented |
+
+---
+
+## Current Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                              trx-server/trx-client                                      │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │                        Application                                  │  │
+│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │  │
+│  │  │    Config    │  │     CLI      │  │      Rig Task            │  │  │
+│  │  │  (TOML file) │  │   (clap)     │  │   (main loop)            │  │  │
+│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+│                                  │                                        │
+│              ┌───────────────────┴───────────────────┐                   │
+│              ▼                                       ▼                   │
+│  ┌─────────────────────┐                 ┌─────────────────────┐        │
+│  │   trx-core          │                 │   Frontend Layer    │        │
+│  │  ┌───────────────┐  │                 │  ┌───────────────┐  │        │
+│  │  │  controller/  │  │                 │  │     HTTP      │  │        │
+│  │  │  - machine    │  │                 │  │  (REST+SSE)   │  │        │
+│  │  │  - handlers   │  │                 │  └───────────────┘  │        │
+│  │  │  - events     │  │                 │  ┌───────────────┐  │        │
+│  │  │  - policies   │  │                 │  │  HTTP JSON    │  │        │
+│  │  └───────────────┘  │                 │  │  (TCP/JSON)   │  │        │
+│  └─────────────────────┘                 │  └───────────────┘  │        │
+│              │                           │  ┌───────────────┐  │        │
+│              │                           │  │    rigctl     │  │        │
+│              │                           │  │  (TCP/hamlib) │  │        │
+│              │                           │  └───────────────┘  │        │
+│              │                           └─────────────────────┘        │
+│              ▼                                                           │
+│  ┌─────────────────────┐                                                │
+│  │   trx-backend       │                                                │
+│  │  ┌───────────────┐  │                                                │
+│  │  │ FT-817 Driver │  │                                                │
+│  │  └───────────────┘  │                                                │
+│  └─────────────────────┘                                                │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+| Component | Purpose |
+|-----------|---------|
+| `trx-core` | Core types, traits (`Rig`, `RigCat`), state definitions, controller components |
+| `trx-core/rig/controller` | State machine, command handlers, event system, policies |
+| `trx-backend` | Backend factory and abstraction layer |
+| `trx-backend-ft817` | FT-817 CAT protocol implementation |
+| `trx-frontend` | Frontend trait (`FrontendSpawner`) |
+| `trx-frontend-http` | Web UI with REST API and SSE |
+| `trx-frontend-http-json` | JSON-over-TCP control frontend |
+| `trx-frontend-rigctl` | Hamlib rigctl-compatible TCP interface |
+| `trx-server` | Server binary — connects to rig backend, exposes JSON TCP control |
+| `trx-client` | Client binary — connects to server, runs frontends (HTTP, rigctl) |
+
+---
+
+## Configuration
+
+trx-rs supports TOML configuration files with the following search order:
+
+1. `--config <path>` (explicit CLI argument)
+2. `./trx-server.toml` or `./trx-client.toml` (current directory)
+3. `~/.config/trx-rs/config.toml` (XDG user config)
+4. `/etc/trx-rs/config.toml` (system-wide)
+
+CLI arguments override config file values.
+
+Plugin discovery:
+- Uses shared libraries with a `trx_register` entrypoint.
+- Searches `./plugins`, `~/.config/trx-rs/plugins`, and any paths in `TRX_PLUGIN_DIRS`.
+
+### Example Configuration
+
+```toml
+[general]
+callsign = "N0CALL"
+
+[rig]
+model = "ft817"
+initial_freq_hz = 144300000
+initial_mode = "USB"
+
+[rig.access]
+type = "serial"
+port = "/dev/ttyUSB0"
+baud = 9600
+
+[frontends.http]
+enabled = true
+listen = "127.0.0.1"
+port = 8080
+
+[frontends.rigctl]
+enabled = true
+listen = "127.0.0.1"
+port = 4532
+
+[frontends.http_json]
+enabled = true
+listen = "127.0.0.1"
+port = 9000
+auth.tokens = ["demo-token"]
+
+[behavior]
+poll_interval_ms = 500
+poll_interval_tx_ms = 100
+max_retries = 3
+retry_base_delay_ms = 100
+```
+
+Use `trx-server --print-config` or `trx-client --print-config` to generate an example configuration.
+
+---
+
+## Rig Controller Components
+
+Located in `trx-core/src/rig/controller/`:
+
+### State Machine (`machine.rs`)
+
+Explicit state machine for rig lifecycle management:
+
+```rust
+pub enum RigMachineState {
+    Disconnected,
+    Connecting { started_at: Option<u64> },
+    Initializing { rig_info: Option<RigInfo> },
+    PoweredOff { rig_info: RigInfo },
+    Ready(ReadyStateData),
+    Transmitting(TransmittingStateData),
+    Error { error: RigStateError, previous_state: Box<RigMachineState> },
+}
+```
+
+Events trigger state transitions:
+- `RigEvent::Connected`, `Initialized`, `PoweredOn`, `PoweredOff`
+- `RigEvent::PttOn`, `PttOff`
+- `RigEvent::Error(RigStateError)`, `Recovered`, `Disconnected`
+
+### Command Handlers (`handlers.rs`)
+
+Trait-based command system with validation:
+
+```rust
+pub trait RigCommandHandler: Debug + Send + Sync {
+    fn name(&self) -> &'static str;
+    fn can_execute(&self, ctx: &dyn CommandContext) -> ValidationResult;
+    fn execute<'a>(&'a self, executor: &'a mut dyn CommandExecutor)
+        -> Pin<Box<dyn Future<Output = DynResult<CommandResult>> + Send + 'a>>;
+}
+```
+
+Implemented commands:
+- `SetFreqCommand`, `SetModeCommand`, `SetPttCommand`
+- `PowerOnCommand`, `PowerOffCommand`
+- `ToggleVfoCommand`, `LockCommand`, `UnlockCommand`
+- `GetTxLimitCommand`, `SetTxLimitCommand`, `GetSnapshotCommand`
+
+The rig task (`trx-server/src/rig_task.rs`) now syncs the state machine to the live `RigState`
+and emits events whenever rig status changes.
+
+### Event Notifications (`events.rs`)
+
+Typed event system for rig state changes:
+
+```rust
+pub trait RigListener: Send + Sync {
+    fn on_frequency_change(&self, old: Option<Freq>, new: Freq);
+    fn on_mode_change(&self, old: Option<&RigMode>, new: &RigMode);
+    fn on_ptt_change(&self, transmitting: bool);
+    fn on_state_change(&self, old: &RigMachineState, new: &RigMachineState);
+    fn on_meter_update(&self, rx: Option<&RigRxStatus>, tx: Option<&RigTxStatus>);
+    fn on_lock_change(&self, locked: bool);
+    fn on_power_change(&self, powered: bool);
+}
+
+pub struct RigEventEmitter {
+    // Manages listeners and dispatches events
+}
+```
+
+### Policies (`policies.rs`)
+
+Configurable retry and polling behavior:
+
+```rust
+pub trait RetryPolicy: Send + Sync {
+    fn should_retry(&self, attempt: u32, error: &RigError) -> bool;
+    fn delay(&self, attempt: u32) -> Duration;
+    fn max_attempts(&self) -> u32;
+}
+
+pub trait PollingPolicy: Send + Sync {
+    fn interval(&self, transmitting: bool) -> Duration;
+    fn should_poll(&self, transmitting: bool) -> bool;
+}
+```
+
+Implementations:
+- `ExponentialBackoff` - Exponential delay with max cap
+- `FixedDelay` - Constant delay between retries
+- `NoRetry` - Fail immediately
+- `AdaptivePolling` - Faster polling during TX
+- `FixedPolling` - Constant interval
+- `NoPolling` - Disable automatic polling
+
+### Error Types
+
+`RigError` now includes error classification:
+
+```rust
+pub struct RigError {
+    pub message: String,
+    pub kind: RigErrorKind,  // Transient or Permanent
+}
+
+impl RigError {
+    pub fn timeout() -> Self;           // Transient
+    pub fn communication(msg) -> Self;  // Transient
+    pub fn invalid_state(msg) -> Self;  // Permanent
+    pub fn not_supported(op) -> Self;   // Permanent
+    pub fn is_transient(&self) -> bool;
+}
+```
+
+---
+
+## Remaining Improvement Opportunities
+
+### Integration Work
+
+1. **Plugin UX improvements** - Add structured plugin metadata (name, version, capabilities) and surface it in CLI help.
+
+### Testing
+
+- Add integration tests with mock backends
+- Add more backend/frontend unit tests
+
+### Features
+
+- Add more rig backends (IC-7300, TS-590, etc.)
+- Add TX limit support for FT-817 (or document per-backend constraints in UI)
+- Add WebSocket support for bidirectional communication
+- Add metrics/telemetry export (Prometheus)
+- Add authentication for HTTP frontend
+
+### Code Quality
+
+- Add CI/CD pipeline
+- Add pre-commit hooks
+
+---
+
+## Implementation Status
+
+| Component | Status | Tests |
+|-----------|--------|-------|
+| State Machine | Implemented | 5 tests |
+| Command Handlers | Implemented | 3 tests |
+| Event Notifications | Implemented | 2 tests |
+| Retry/Polling Policies | Implemented | 5 tests |
+| Config File Support | Implemented | 4 tests |
+| rigctl Frontend | Implemented | - |
+| HTTP Frontend | Implemented | - |
+| FT-817 Backend | Implemented | - |
+
+**Total: 19 unit tests passing**
+
+---
+
+## Building and Running
+
+```bash
+# Build
+cargo build --release
+
+# Run server with CLI args
+./target/release/trx-server -r ft817 "/dev/ttyUSB0 9600"
+
+# Run server with config file
+./target/release/trx-server --config /path/to/config.toml
+
+# Run client
+./target/release/trx-client --config /path/to/client-config.toml
+
+# Print example config
+./target/release/trx-server --print-config > trx-server.toml
+
+# Run tests
+cargo test
+
+# Run clippy
+cargo clippy
+```
@@ -0,0 +1,383 @@
+# SDR Backend Requirements
+
+This document specifies the requirements for a SoapySDR-based RX-only backend (`trx-backend-soapysdr`) and the associated IQ-to-audio pipeline changes in `trx-server`.
+
+---
+
+## Progress
+
+> **For AI agents:** This section is the single source of truth for implementation status.
+> Each task has a unique ID (e.g. `SDR-01`), a status badge, a description, the files it touches, and any blocking dependencies.
+> Pick any task whose status is `[ ]` and whose `Needs` list is fully `[x]`. Update status to `[~]` while working, `[x]` when merged. Record notes under the task if you hit non-obvious issues.
+>
+> Status legend: `[ ]` not started · `[~]` in progress · `[x]` done · `[!]` blocked
+
+### Foundational (must land first)
+
+| ID | Status | Task | Touches |
+|----|--------|------|---------|
+| SDR-01 | `[x]` | Add `AudioSource` trait to `trx-core`; add `as_audio_source()` default on `RigCat` | `src/trx-core/src/rig/mod.rs` |
+| SDR-02 | `[x]` | Add `RigAccess::Sdr { args: String }` variant; register `soapysdr` factory (feature-gated `soapysdr`) | `src/trx-server/trx-backend/src/lib.rs` |
+| SDR-03 | `[x]` | Add `SdrConfig`, `SdrGainConfig`, `SdrChannelConfig` structs; parse `type = "sdr"` in `AccessConfig`; add `sdr: SdrConfig` to `ServerConfig`; add startup validation rules (§11) | `src/trx-server/src/config.rs` |
+
+### New crate: `trx-backend-soapysdr`
+
+| ID | Status | Task | Touches | Needs |
+|----|--------|------|---------|-------|
+| SDR-04 | `[x]` | Create crate scaffold: `Cargo.toml` (deps: `soapysdr`, `num-complex`, `tokio`), empty `lib.rs` | `src/trx-server/trx-backend/trx-backend-soapysdr/` | SDR-01, SDR-02 |
+| SDR-05 | `[x]` | Implement `demod.rs`: SSB (USB/LSB), AM envelope, FM quadrature, CW narrow BPF+envelope | `…/src/demod.rs` | SDR-04 |
+| SDR-06 | `[x]` | Implement `dsp.rs`: IQ broadcast loop (SoapySDR read thread → `broadcast::Sender<Vec<Complex<f32>>>`); per-channel mixer → FIR LPF → decimator → demod → frame accumulator → `broadcast::Sender<Vec<f32>>` | `…/src/dsp.rs` | SDR-04, SDR-05 |
+| SDR-07 | `[x]` | Implement `SoapySdrRig` in `lib.rs`: `RigCat` (RX methods + `not_supported` stubs for TX), `AudioSource`, gain control (manual/auto with fallback), primary channel freq/mode tracking | `…/src/lib.rs` | SDR-03, SDR-06 |
+
+### Server integration
+
+| ID | Status | Task | Touches | Needs |
+|----|--------|------|---------|-------|
+| SDR-08 | `[x]` | `main.rs`: after building rig, if `as_audio_source()` is `Some` skip cpal, subscribe each decoder and the Opus encoder to the appropriate channel PCM senders; validate `stream_opus` count ≤ 1 | `src/trx-server/src/main.rs` | SDR-03, SDR-07 |
+| SDR-09 | `[x]` | Add `trx-backend-soapysdr` to workspace `Cargo.toml`; update `CONFIGURATION.md` with new `[sdr]` / `[[sdr.channels]]` options | `Cargo.toml`, `CONFIGURATION.md` | SDR-04 |
+
+### Validation & tests
+
+| ID | Status | Task | Touches | Needs |
+|----|--------|------|---------|-------|
+| SDR-10 | `[x]` | Unit tests for `demod.rs`: known-input tone through each demodulator, check output frequency correct | `…/src/demod.rs` | SDR-05 |
+| SDR-11 | `[x]` | Unit tests for config validation: channel IF out-of-range, dual `stream_opus`, TX enabled with SDR backend, AGC fallback warning | `src/trx-server/src/config.rs` | SDR-03 |
+
+---
+
+## Goals
+
+- Receive-only backend that uses any SoapySDR-compatible device (RTL-SDR, Airspy, HackRF, SDRplay, etc.) as the rig
+- Full IQ pipeline: raw IQ samples → demodulated PCM → existing decoders (FT8, WSPR, APRS, CW) with zero decoder-side changes
+- Wideband capture: one SDR IQ stream feeds multiple simultaneous virtual receivers, each independently tuned and demodulated
+- Configurable per-channel filters and demodulation modes
+- Demodulated audio streamed to clients as Opus over the existing TCP audio channel
+
+---
+
+## Non-Goals
+
+- Transmit (TX/PTT) of any kind
+- Replacing or deprecating the existing cpal-based audio path (it stays for transceiver backends)
+
+---
+
+## 1. Device Abstraction
+
+### 1.1 `RigAccess` extension
+
+A new access type `sdr` is added alongside `serial` and `tcp`:
+
+```toml
+[rig.access]
+type = "sdr"
+args = "driver=rtlsdr"             # SoapySDR device args string
+```
+
+The `args` value is passed verbatim to `SoapySDR::Device::new(args)`. It follows SoapySDR's key=value comma-separated convention (e.g., `driver=airspy`, `driver=rtlsdr,serial=00000001`).
+
+### 1.2 `AudioSource` trait
+
+A new trait is added to `trx-core` (`src/trx-core/src/rig/mod.rs`):
+
+```rust
+pub trait AudioSource: Send + Sync {
+    /// Subscribe to demodulated PCM audio from the primary channel.
+    fn subscribe_pcm(&self) -> broadcast::Receiver<Vec<f32>>;
+}
+```
+
+`RigCat` gains a default opt-in method:
+
+```rust
+pub trait RigCat: Rig + Send {
+    // ... existing methods ...
+    fn as_audio_source(&self) -> Option<&dyn AudioSource> { None }
+}
+```
+
+`SoapySdrRig` overrides `as_audio_source()` to return `Some(self)`. When the server detects this, it skips spawning the cpal capture thread entirely.
+
+### 1.3 TX-only `RigCat` methods
+
+The following methods return `RigError::not_supported(...)` on the SDR backend:
+
+- `set_ptt()`
+- `power_on()` / `power_off()`
+- `get_tx_power()`
+- `get_tx_limit()` / `set_tx_limit()`
+- `toggle_vfo()` (not applicable; channels are defined statically in config)
+- `lock()` / `unlock()`
+
+The following methods are fully supported:
+
+- `get_status()` → returns primary channel's current `(freq, mode, None)`
+- `set_freq()` → re-tunes the SDR center frequency (keeping `center_offset_hz` invariant) and updates all channel mixer offsets
+- `set_mode()` → changes the primary channel's demodulator
+- `get_signal_strength()` → returns instantaneous RSSI for the primary channel (dBFS mapped to 0–255 S-unit range)
+
+---
+
+## 2. IQ Pipeline Architecture
+
+### 2.1 Center frequency offset
+
+SDR hardware has a DC offset spur at exactly 0 Hz in the IQ spectrum. To keep the primary channel off DC, the SDR is tuned to a frequency offset from the desired dial frequency:
+
+```
+sdr_center_freq = dial_freq - center_offset_hz
+```
+
+With `center_offset_hz = 200000` and dial freq 14.074 MHz, the SDR tunes to 13.874 MHz. The 14.074 MHz signal appears at +200 kHz in the IQ spectrum and is mixed down to baseband in software.
+
+`center_offset_hz` is a global SDR parameter (not per-channel). A reasonable default is `100000` (100 kHz).
+
+### 2.2 Wideband channel model
+
+One SoapySDR RX stream produces IQ samples at `sdr.sample_rate` (e.g. 1.92 MHz). This stream is shared among all configured channels. Each channel defines an independent virtual receiver:
+
+```
+SoapySDR RX stream  (complex f32, sdr_sample_rate Hz)
+    │
+    ├──► Channel 0  (primary)   offset_hz=0,      mode=USB,  bw=3000 Hz
+    ├──► Channel 1  (wspr)      offset_hz=+21600, mode=USB,  bw=3000 Hz
+    └──► Channel N  ...
+```
+
+A **channel's frequency** in the real spectrum is:
+
+```
+channel_real_freq = dial_freq + channel.offset_hz
+```
+
+A **channel's IF frequency** within the IQ stream is:
+
+```
+channel_if_hz = center_offset_hz + channel.offset_hz
+```
+
+This is the frequency at which the channel's signal appears in the captured IQ bandwidth, and is what the channel's mixer shifts to baseband.
+
+**Constraint:** `|channel_if_hz|` must be less than `sdr_sample_rate / 2` for every channel. The server validates this at startup and rejects invalid configs.
+
+### 2.3 Per-channel DSP chain
+
+Each channel runs the following stages independently on the shared IQ stream:
+
+```
+IQ input (complex f32, sdr_sample_rate)
+    1. Mixer:     multiply by exp(-j·2π·channel_if_hz·n/sdr_sample_rate)
+                  → complex f32 centred at 0 Hz
+    2. FIR LPF:   cutoff = audio_bandwidth_hz / 2, order configurable
+    3. Decimator: sdr_sample_rate / audio_sample_rate  (must be integer; resampler used otherwise)
+    4. Demodulator (mode-dependent, see §3)
+    5. Output: real f32 at audio_sample_rate
+    6. Frame accumulator: chunks of frame_duration_ms
+    7. broadcast::Sender<Vec<f32>>  →  decoders + optional Opus encoder
+```
+
+Channels run concurrently in separate tasks, all reading from the same raw IQ broadcast channel.
+
+### 2.4 IQ broadcast channel
+
+The SoapySDR read loop runs in a dedicated OS thread (matching the existing cpal thread model). It reads IQ sample blocks from the device and publishes them on:
+
+```rust
+broadcast::Sender<Vec<Complex<f32>>>   // capacity: configurable, default 64 blocks
+```
+
+Each channel task subscribes to this sender. Lagged receivers log a warning and continue.
+
+---
+
+## 3. Demodulators
+
+Demodulator is selected per-channel based on `mode`. Modes map as follows:
+
+| `RigMode` | Demodulator |
+|-----------|-------------|
+| `USB`     | SSB: mix to IF, take real part (upper sideband) |
+| `LSB`     | SSB: mix to IF, take real part (lower sideband, negate IF) |
+| `AM`      | Envelope detector: `sqrt(I² + Q²)`, DC-remove, normalize |
+| `FM`      | Quadrature: `arg(s[n] · conj(s[n-1]))`, i.e. instantaneous frequency |
+| `WFM`     | Same as FM, wider pre-demod filter (`wfm_bandwidth_hz`) |
+| `CW`      | Narrow BPF centred at `cw_center_hz` (audio domain), then envelope |
+| `DIG`/`PKT` | Same as USB (pass audio through for downstream digital decoders) |
+| `CWR`     | Same as CW (reversed sideband, uses same audio envelope) |
+
+For SSB modes (USB/LSB), after mixing to baseband the channel's `audio_bandwidth_hz` defines the one-sided cutoff of the post-demod LPF.
+
+---
+
+## 4. Gain Control
+
+Gain is configured globally under `[sdr.gain]`.
+
+```toml
+[sdr.gain]
+mode  = "auto"    # "auto" (AGC via SoapySDR) or "manual"
+value = 30.0      # dB; ignored when mode = "auto"
+```
+
+- **`auto`**: calls `device.set_gain_mode(SOAPY_SDR_RX, 0, true)` to enable hardware AGC if the device supports it. If the device does not support hardware AGC, falls back to `manual` with a warning.
+- **`manual`**: calls `device.set_gain(SOAPY_SDR_RX, 0, value)` with the specified total gain in dB.
+
+Advanced per-element gain is out of scope for this phase (no `lna`/`vga`/`if` sub-keys initially).
+
+---
+
+## 5. Filter Configuration
+
+Filters are configured per-channel. The following are settable:
+
+```toml
+[[sdr.channels]]
+audio_bandwidth_hz = 3000    # One-sided bandwidth of post-demod BPF (Hz)
+                             # For FM: deviation hint for deemphasis
+fir_taps = 64                # FIR filter tap count (default 64); higher = sharper roll-off
+cw_center_hz = 700           # CW tone centre in audio domain (default 700 Hz)
+wfm_bandwidth_hz = 75000     # Pre-demod bandwidth for WFM only (default 75 kHz)
+```
+
+`fir_taps` controls the same FIR used in stage 2 of the DSP chain (§2.3). It applies uniformly to both the pre-demod decimation filter and the post-demod audio BPF in this phase.
+
+---
+
+## 6. Channel Configuration and Decoder Binding
+
+Channels are declared as a TOML array. The first channel in the list is the **primary channel** and is the one exposed via `RigCat` (`set_freq`/`set_mode` affect it; `get_status` reads from it).
+
+```toml
+[[sdr.channels]]
+id               = "primary"   # Identifier, used in logs
+offset_hz        = 0           # Offset from dial frequency (Hz)
+mode             = "auto"      # "auto" = follows RigCat set_mode; or fixed RigMode string
+audio_bandwidth_hz = 3000
+fir_taps         = 64
+decoders         = ["ft8", "cw"]   # Which decoders receive this channel's PCM
+stream_opus      = true            # Encode and stream via TCP audio channel
+
+[[sdr.channels]]
+id               = "wspr-14"
+offset_hz        = 21600       # 14.0956 MHz when dial = 14.074 MHz
+mode             = "USB"       # Fixed mode, ignores RigCat set_mode
+audio_bandwidth_hz = 3000
+decoders         = ["wspr"]
+stream_opus      = false
+
+[[sdr.channels]]
+id               = "aprs"
+offset_hz        = -673600     # e.g. 144.390 MHz when dial = 145.0635 MHz
+mode             = "FM"
+audio_bandwidth_hz = 8000
+decoders         = ["aprs"]
+stream_opus      = false
+```
+
+**`mode = "auto"`** means the channel's demodulator tracks whatever `set_mode()` last set on the backend. Only the primary channel should use `"auto"` in typical use.
+
+**`decoders`** maps to the decoder task IDs: `"ft8"`, `"wspr"`, `"aprs"`, `"cw"`. Each named decoder subscribes to the PCM broadcast channel of the listed channel(s). A decoder can only be bound to one channel (first binding wins if duplicated).
+
+---
+
+## 7. Opus Streaming
+
+Channels with `stream_opus = true` have their demodulated PCM Opus-encoded and streamed over the server's existing TCP audio port (default 4531).
+
+For this phase, only **one channel** may have `stream_opus = true` (validation error otherwise). This channel's Opus stream replaces what cpal would have produced — the TCP audio protocol and client-side handling are unchanged.
+
+The Opus encoder uses the `[audio]` config for `frame_duration_ms`, `bitrate_bps`, and `sample_rate`. The SDR pipeline must output PCM at the same `sample_rate` as `[audio]`; a mismatch is a startup validation error.
+
+---
+
+## 8. Full Configuration Example
+
+```toml
+[rig]
+model = "soapysdr"
+initial_freq_hz = 14074000
+initial_mode = "USB"
+
+[rig.access]
+type = "sdr"
+args = "driver=rtlsdr"
+
+[sdr]
+sample_rate      = 1920000     # IQ capture rate (Hz) — must be supported by device
+bandwidth        = 1500000     # Hardware IF filter (Hz)
+center_offset_hz = 200000      # SDR tunes this many Hz below dial frequency
+
+[sdr.gain]
+mode  = "auto"
+value = 30.0                   # Effective only when mode = "manual"
+
+[[sdr.channels]]
+id               = "primary"
+offset_hz        = 0
+mode             = "auto"
+audio_bandwidth_hz = 3000
+fir_taps         = 64
+decoders         = ["ft8", "cw"]
+stream_opus      = true
+
+[[sdr.channels]]
+id               = "wspr"
+offset_hz        = 21600
+mode             = "USB"
+audio_bandwidth_hz = 3000
+decoders         = ["wspr"]
+stream_opus      = false
+
+[audio]
+enabled          = true
+listen           = "127.0.0.1"
+port             = 4531
+rx_enabled       = true
+tx_enabled       = false        # No TX on SDR backend
+sample_rate      = 48000
+channels         = 1
+frame_duration_ms = 20
+bitrate_bps      = 24000
+```
+
+---
+
+## 9. Code Changes Map
+
+| File | Change |
+|------|--------|
+| `Cargo.toml` (workspace) | Add `src/trx-server/trx-backend/trx-backend-soapysdr` member |
+| `src/trx-core/src/rig/mod.rs` | Add `AudioSource` trait; add `as_audio_source()` default to `RigCat` |
+| `src/trx-server/trx-backend/src/lib.rs` | Add `RigAccess::Sdr { args }` variant; register `soapysdr` factory (feature-gated) |
+| `src/trx-server/src/config.rs` | Add `SdrConfig`, `SdrGainConfig`, `SdrChannelConfig`; parse `type = "sdr"` in `AccessConfig`; add `sdr: SdrConfig` to `ServerConfig` |
+| `src/trx-server/src/main.rs` | After building rig: if `as_audio_source()` is `Some`, skip cpal, use `AudioSource::subscribe_pcm()` for each decoder and for the Opus encoder; validate at most one `stream_opus = true` channel |
+| `src/trx-server/src/audio.rs` | Expose `spawn_audio_capture` and `run_*_decoder` without assuming cpal as the sole source; no functional change needed — decoders already take `broadcast::Receiver<Vec<f32>>` |
+| `src/trx-server/trx-backend/trx-backend-soapysdr/Cargo.toml` | New crate |
+| `src/trx-server/trx-backend/trx-backend-soapysdr/src/lib.rs` | `SoapySdrRig`: implements `RigCat` + `AudioSource`; spawns IQ read thread and channel DSP tasks |
+| `src/trx-server/trx-backend/trx-backend-soapysdr/src/dsp.rs` | IQ broadcast loop; per-channel mixer, FIR, decimator, demodulator, frame accumulator |
+| `src/trx-server/trx-backend/trx-backend-soapysdr/src/demod.rs` | Mode-specific demodulators: SSB, AM envelope, FM quadrature, CW envelope |
+| `CONFIGURATION.md` | Document new `[rig.access] type = "sdr"`, `[sdr]`, `[[sdr.channels]]` options |
+
+---
+
+## 10. External Dependencies
+
+| Crate | Purpose |
+|-------|---------|
+| `soapysdr` | Rust bindings to `libSoapySDR` (C++) |
+| `num-complex` | `Complex<f32>` for IQ arithmetic |
+
+System requirement: `libSoapySDR` installed (e.g. `brew install soapysdr` on macOS, `libsoapysdr-dev` on Debian/Ubuntu).
+
+---
+
+## 11. Validation Rules (startup)
+
+- `[rig.access] type = "sdr"` requires `args` to be non-empty.
+- `[sdr] sample_rate` must be non-zero.
+- For every channel: `|center_offset_hz + channel.offset_hz| < sdr_sample_rate / 2`.
+- Exactly one channel must have `stream_opus = true` (or none; zero means no TCP audio stream).
+- The audio `sample_rate` in `[audio]` must equal the target audio rate in the SDR pipeline (no cross-rate mismatch).
+- `[audio] tx_enabled` must be `false` when `model = "soapysdr"`.
+- A decoder name may appear in at most one channel's `decoders` list.
+- If the device does not support hardware AGC and `gain.mode = "auto"`, warn and fall back to `manual` using `gain.value`.
@@ -0,0 +1,180 @@
+# UI Capability Gating
+
+This document specifies how `trx-client`'s HTTP frontend adapts its controls to the capabilities of the connected rig backend. Devices such as SDR receivers expose filter controls but not TX controls; traditional transceivers are the reverse.
+
+---
+
+## Progress
+
+> **For AI agents:** This section is the single source of truth for implementation status.
+> Each task has a unique ID (e.g. `UC-01`), a status badge, a description, the files it touches, and any blocking dependencies.
+>
+> Status legend: `[ ]` not started · `[~]` in progress · `[x]` done · `[!]` blocked
+
+### Foundational (parallel)
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| UC-01 | `[ ]` | Extend `RigCapabilities` with `tx`, `tx_limit`, `vfo_switch`, `filter_controls`, `signal_meter` bool flags | `src/trx-core/src/rig/state.rs` | — |
+| UC-02 | `[ ]` | Update capability declarations in all backends to set new flags | `src/trx-server/trx-backend/trx-backend-ft817/src/lib.rs`, `trx-backend-ft450d/src/lib.rs`, `trx-backend-soapysdr/src/lib.rs` | UC-01 |
+| UC-03 | `[ ]` | Add `RigFilterState` struct; add `filter: Option<RigFilterState>` to `RigSnapshot`; populate from SDR rig state | `src/trx-core/src/rig/state.rs`, `src/trx-server/trx-backend/trx-backend-soapysdr/src/lib.rs` | — |
+| UC-04 | `[ ]` | Add `SetBandwidth`, `SetFirTaps` to `ClientCommand`; add mapping arms; update `rig_task.rs` to dispatch them | `src/trx-protocol/src/types.rs`, `mapping.rs`, `src/trx-server/src/rig_task.rs` | UC-03 |
+
+### HTTP layer
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| UC-05 | `[ ]` | Add `/set_bandwidth` and `/set_fir_taps` HTTP endpoints | `src/trx-client/trx-frontend/trx-frontend-http/src/api.rs` | UC-04 |
+
+### Frontend
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| UC-06 | `[ ]` | Read `state.info.capabilities` on each SSE event; toggle visibility of TX controls, meter rows, VFO button, lock button | `assets/web/app.js` | UC-01, UC-02 |
+| UC-07 | `[ ]` | Add "Filters" control panel (bandwidth, FIR taps, CW tone Hz); show only when `capabilities.filter_controls` | `assets/web/index.html`, `assets/web/app.js` | UC-05, UC-06 |
+
+### Tests
+
+| ID | Status | Task | Files | Needs |
+|----|--------|------|-------|-------|
+| UC-08 | `[ ]` | Unit tests: SDR backend declares `tx=false`, `filter_controls=true`; FT-817/450D declare `tx=true`, `filter_controls=false` | `src/trx-server/trx-backend/trx-backend-soapysdr/src/lib.rs`, `trx-backend-ft817`, `trx-backend-ft450d` | UC-02 |
+| UC-09 | `[ ]` | Protocol round-trip test: `RigSnapshot` serialises `filter` field when `Some`, omits it when `None` | `src/trx-protocol/src/codec.rs` or `types.rs` | UC-03 |
+
+---
+
+## Goals
+
+- All UI control groups are **shown/hidden purely from `RigCapabilities`** flags received in the initial `GET /status` and each SSE `status` event — no hard-coding per model name
+- SDR backends show filter controls (bandwidth, FIR taps, CW tone); hide TX controls (PTT, power, TX limit, TX meters, TX audio)
+- Transceiver backends show TX controls; hide filter controls
+- Adding a new backend requires only setting the right capability flags — no frontend changes
+
+---
+
+## Non-Goals
+
+- Per-channel filter control (multi-channel SDR tuning) — out of scope; only the primary channel is exposed here
+- Dynamic capability changes at runtime (capability flags are set once at rig init and treated as static)
+- Changing the rigctl or http-json frontends (HTTP frontend only)
+
+---
+
+## Capability Flags
+
+### New flags added to `RigCapabilities` (UC-01)
+
+| Flag | Type | Meaning |
+|------|------|---------|
+| `tx` | `bool` | Backend supports transmit: PTT, power on/off, TX meters, TX audio |
+| `tx_limit` | `bool` | Backend supports `get_tx_limit` / `set_tx_limit` |
+| `vfo_switch` | `bool` | Backend supports `toggle_vfo` |
+| `filter_controls` | `bool` | Backend supports runtime filter adjustment (bandwidth, FIR taps) |
+| `signal_meter` | `bool` | Backend returns a meaningful RX signal strength value |
+
+Existing flags `lock` and `lockable` are unchanged.
+
+### Backend declarations (UC-02)
+
+| Backend | `tx` | `tx_limit` | `vfo_switch` | `filter_controls` | `signal_meter` | `lock`/`lockable` |
+|---------|------|-----------|--------------|-------------------|----------------|-------------------|
+| FT-817 | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ / ✓ |
+| FT-450D | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ / ✓ |
+| SoapySDR | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ / ✗ |
+
+---
+
+## Filter State
+
+### `RigFilterState` struct (UC-03)
+
+Added to `trx-core/src/rig/state.rs`:
+
+```rust
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RigFilterState {
+    pub bandwidth_hz: u32,      // Audio bandwidth of primary channel
+    pub fir_taps: u32,          // FIR filter tap count
+    pub cw_center_hz: u32,      // CW tone centre frequency (audio domain)
+}
+```
+
+Added to `RigSnapshot`:
+
+```rust
+#[serde(default, skip_serializing_if = "Option::is_none")]
+pub filter: Option<RigFilterState>,
+```
+
+The SDR backend populates this from the primary channel's live DSP state. All other backends leave it `None`.
+
+---
+
+## New Protocol Commands
+
+### `ClientCommand` additions (UC-04)
+
+```rust
+SetBandwidth { bandwidth_hz: u32 },
+SetFirTaps   { taps: u32 },
+```
+
+`SetCwToneHz` already exists and is reused.
+
+### Mapping (UC-04)
+
+```rust
+ClientCommand::SetBandwidth { bandwidth_hz } =>
+    RigCommand::SetBandwidth(bandwidth_hz),
+ClientCommand::SetFirTaps { taps } =>
+    RigCommand::SetFirTaps(taps),
+```
+
+The SDR backend applies changes to the live DSP chain immediately. Other backends return `RigError::not_supported(...)`.
+
+---
+
+## New HTTP Endpoints (UC-05)
+
+| Endpoint | Method | Query param | Action |
+|----------|--------|-------------|--------|
+| `/set_bandwidth` | POST | `hz: u32` | Sets primary channel audio bandwidth |
+| `/set_fir_taps` | POST | `taps: u32` | Sets primary channel FIR tap count |
+
+---
+
+## Frontend Visibility Map (UC-06, UC-07)
+
+| UI element / group | Shown when |
+|--------------------|-----------|
+| PTT button | `capabilities.tx` |
+| Power button | `capabilities.tx` |
+| TX meters (power bar, SWR bar) | `capabilities.tx && state.status.tx_en` |
+| TX Limit row | `capabilities.tx_limit` |
+| TX Audio toggle + volume | `capabilities.tx` |
+| VFO selector buttons | `capabilities.vfo_switch` |
+| Lock button | `capabilities.lock` |
+| Signal meter | `capabilities.signal_meter` |
+| Filters panel | `capabilities.filter_controls` |
+
+Visibility is applied in a single `applyCapabilities(caps)` function called from the SSE `status` handler, using `element.classList.toggle('hidden', !condition)`.
+
+### Filter panel layout (UC-07)
+
+```
+┌─ Filters ──────────────────────────────────┐
+│  Bandwidth  [──────●──────] 3000 Hz        │
+│  FIR taps   [32 ▾] (32 / 64 / 128 / 256)  │
+│  CW tone    [──●───────────] 700 Hz        │
+└────────────────────────────────────────────┘
+```
+
+Each control dispatches to its REST endpoint on `change`/`input` (debounced 200 ms). The panel is hidden by default (`class="hidden"`) and revealed when `capabilities.filter_controls` is set.
+
+---
+
+## Implementation Notes
+
+- `applyCapabilities()` must run **before** the first paint (call it synchronously on the initial `/status` response, not only on SSE events) to avoid layout flash of unsupported controls.
+- `hidden` CSS class should set `display: none` and `aria-hidden: true`.
+- The existing `set_cw_tone` endpoint and CW decoder panel remain in the CW decoder tab — they are decoder settings, not filter settings. The Filters panel bandwidth/taps apply to the DSP chain; CW tone moves to both places or is de-duplicated in a follow-up.
+- If a future backend supports TX but not `tx_limit`, only the TX Limit row is hidden; PTT remains.