Steps 7 and 8: torrents, OPML, and polish

librqbit replaces the vendored BitTorrent 4.2.1 tree. Torrents download
in place because seeding serves the files it downloaded, so the planned
stage-then-move would have broken it. The stall budget now also covers
magnet metadata resolution, which otherwise never returns against a dead
swarm and wedged the scan.

Adds add/rm/import/export, tracing setup, systemd units and README.

A successful swarm download is unverified: no reachable peers here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RPyeapneuXrCdojsaiXGbe

README.md

@@ -11,21 +11,100 @@ Python 2 engine behind **iPodderX** (2004-2008, Ray Slakinski & August Trometer)
 open-sourced under the MIT License in 2010.
 
 What carries over: the feed scan and TTL handling, GUID/URL dedupe, per-feed and per-date download
-folders, keyword filters, the explicit-content filter, torrent enclosures, and "SmartSpace" — the
+folders, keyword filters, the explicit-content filter, torrent enclosures, and "SmartSpace" -- the
 oldest-first disk quota reaper.
 
 What does not: iTunes and iPhoto export via AppleScript, text-to-speech enclosures, the Windows
 WMP/COM paths, XML plists and Python pickles for state, the `directory.iPodderX.com` survey ping,
 3DES-encrypted preferences, and the `printMSG` stdout protocol (replaced by a JSON-lines socket).
 
-## Status
+## Quickstart
 
-Under construction. See [PROGRESS.md](PROGRESS.md) for what works today.
+```sh
+cargo install --path .
+
+ipx add https://atp.fm/rss          # names the feed from its own title
+ipx list
+ipx fetch                           # scan now
+ipx daemon                          # or run continuously, honouring each feed's <ttl>
+```
+
+Config lives at `~/.config/ipx/config.toml` (mode 0600, since it may hold feed passwords);
+state at `~/.local/share/ipx/state.db`. Override with `IPX_CONFIG` and `IPX_DATA_DIR`.
+Set `IPX_LOG=ipx=debug` for verbose logging on stderr.
+
+## Commands
+
+| command | what it does |
+|---|---|
+| `ipx add <url> [--folder X] [--keywords a,b]` | subscribe; the id comes from the feed title |
+| `ipx rm <feed>` | unsubscribe; downloads and history are kept |
+| `ipx list` / `ipx status` | subscriptions and their state |
+| `ipx fetch [FEED] [--force]` | scan; `--force` ignores the TTL |
+| `ipx reap [--dry-run]` | run retention now |
+| `ipx import/export <file.opml>` | move subscriptions in or out |
+| `ipx daemon` | scheduler plus the control socket |
+
+Any command with a wire form probes the socket first: if a daemon is running it does the work,
+and the CLI just renders the events it streams back. `--local` forces in-process execution.
 
 ## Configuration
 
-`~/.config/ipx/config.toml`, state in `~/.local/share/ipx/state.db`. See PROGRESS.md until the
-usage section lands.
+```toml
+[general]
+download_dir   = "~/Podcasts"
+socket         = "/run/user/1000/ipx.sock"   # default: $XDG_RUNTIME_DIR/ipx.sock
+interval_mins  = 60          # default poll; a feed's own <ttl> wins when longer
+organize       = "feed"      # "feed" | "date"
+max_total_gb   = 50          # 0 = unlimited
+max_age_days   = 30          # 0 = keep forever
+
+[torrent]
+enabled        = true
+seed_ratio     = 1.0         # stop seeding at this ratio ...
+seed_time_mins = 60          # ... or after this long, whichever comes first
+port_range     = "6881-6889"
+stall_mins     = 30          # give up on a torrent making no progress
+
+[feeds.atp]
+url                = "https://atp.fm/rss"
+folder             = "Accidental Tech Podcast"  # default: the feed title
+keywords           = ["deep dive"]   # OR across keywords, AND within one
+allow_explicit     = false
+auto_download      = true
+max_new_per_check  = 3        # the rest wait for the next scan
+username           = "ray"                  # optional HTTP basic auth
+password_env       = "IPX_ATP_PASS"         # or a literal `password`
+```
+
+Retention keeps files that are `flagged` in the database, and deletes read episodes before unread
+ones, oldest first.
+
+## Socket protocol
+
+Newline-delimited JSON over a Unix socket, both directions.
+
+```sh
+$ printf '{"cmd":"fetch","force":true}\n' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/ipx.sock
+{"ev":"feed_start","feed":"atp"}
+{"ev":"progress","feed":"atp","url":"...","file":"ep1.mp3","done":8192,"total":3000000}
+{"ev":"download_done","feed":"atp","url":"...","path":"...","bytes":3000000}
+{"ev":"feed_done","feed":"atp","new":1,"downloaded":1,"failed":0,"torrents":0}
+{"ev":"scan_done","feeds":1}
+```
+
+Commands: `fetch` (optional `feed`, `force`), `reap` (optional `dry_run`), `status`.
+Events: `feed_start`, `feed_skip`, `feed_done`, `feed_error`, `progress`, `download_done`,
+`download_error`, `torrent_deferred`, `reaped`, `reap_done`, `scan_done`, `status`, `error`.
+`scan_done`, `reap_done` and `status` are terminal -- a client that asked for work stops there.
+
+Progress is throttled to whole percents. The stream is a broadcast, so a client attached to a busy
+daemon also sees that daemon's other work.
+
+## Running it as a service
+
+`contrib/` has a systemd user unit for the daemon, and a timer plus one-shot service if you would
+rather run periodic scans with no daemon (in which case there is no socket for a UI to attach to).
 
 ## License