docs(@applications/tv-anarchy): 📝 update app description and architecture details

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

README.md

@@ -1,14 +1,16 @@
 # TVAnarchy
 
-Native macOS app (SwiftUI) for the home media stack on **plum**. Unifies what was
-previously CLI/MCP-only: pick a **playback target** (plum's VLC or the HDMI TV on
-**black**) and drive transport; later phases add a cached library browser, a
-download searcher/manager, and a local (MLX) filename→metadata pipeline.
+Native macOS app (SwiftUI) for the home media stack on **plum**, plus an iOS
+companion. Unifies what was previously CLI/MCP-only: pick a **playback device**
+(plum's VLC/QuickTime or the HDMI TV on **black**) and drive transport, browse a
+cached library, search and manage downloads, enrich metadata, and manage the
+device registry — all from one app.
 
-**Hybrid architecture:** the control plane is native Swift (SSH shell-outs to the
-deployed `black-tv` script; HTTP to VLC's Lua interface — zero new runtime deps);
-the data-heavy plane reuses existing projects (`plum-control-mcp`, `media-recommender`)
-as helper subprocesses. See the build plan for phases.
+**Hybrid architecture:** the control plane is native Swift (HTTP to VLC's Lua
+interface; mpv JSON-IPC over SSH to black — zero new runtime deps); the
+data-heavy plane reuses the vendored helper projects (`mcp/`, `recommender/`,
+`search/`) as subprocesses. See [docs/](docs/README.md) for the full picture and
+[docs/roadmap.md](docs/roadmap.md) for built-vs-designed status.
 
 ## Build
 
@@ -23,13 +25,26 @@ xcodebuild -scheme TVAnarchy -destination 'platform=macOS' build
 
 ## Layout
 
-- `Sources/TVAnarchyCore/` — framework: models, `PlayerTarget` protocol + impls, target selector.
-- `Sources/TVAnarchy/` — SwiftUI app (App, RootView, feature views).
-- `Tests/TVAnarchyCoreTests/` — unit tests for the core (status decoders, mappings).
+- `Sources/TVAnarchyCore/` — framework: models, `PlayerTarget` protocol + impls,
+  library/metadata/torrents/VPN subsystems, device registry.
+- `Sources/TVAnarchy/` — SwiftUI macOS app (App, RootView, feature views:
+  Home/Player/Library/Search/Downloads/Metadata/Adult/Devices/Logs/Settings).
+- `Sources/TVAnarchyiOS/` — iOS companion (VLCKit player, library, downloads,
+  remote control over an HTTP bridge).
+- `Tests/TVAnarchyCoreTests/`, `Tests/TVAnarchyiOSUITests/` — unit + UI tests.
+- `governor/`, `mcp/`, `recommender/`, `search/` — helper subsystems (own READMEs).
+- `fleet/` — designed-only mesh layer; `tools/` — release/update/stamping scripts;
+  `docs/` — cross-cutting documentation.
 
-## Targets
+## Playback devices
 
 - **Plum VLC** — HTTP to `http://127.0.0.1:8080/requests/…` (password from
   `~/.config/portable-net-tv/config.json` or `$VLC_HTTP_PASSWORD`).
-- **Black TV** — `ssh lilith@10.9.0.4 /usr/local/bin/black-tv <verb>` (the overlay IP;
-  the LAN address flaps). All playback intelligence lives in `black-tv` on black.
+- **Black (mpv)** — mpv JSON-IPC over SSH, endpoints LAN `10.0.0.11` →
+  WG overlay `10.9.0.4` fallback (the LAN address flaps). Launch/library/stats
+  are delegated to per-device command templates wrapping `/usr/local/bin/black-tv`
+  (the legacy `blacktv` kind auto-migrates to this).
+- **QuickTime** — local, zero-install, AppleScript-driven.
+
+Devices live in `~/.config/tv-anarchy/devices.json` and are editable in the
+Devices tab.

docs/README.md

@@ -1,11 +1,11 @@
 # TV Anarchy — Documentation
 
-TV Anarchy is a native macOS (SwiftUI) front end for a home media stack centered
-on **plum** (the laptop) and **black** (the media server). It unifies what was
-previously CLI/MCP-only: pick a playback target, browse a cached library, search
-and manage torrents, and enrich metadata — all from one app. A larger,
-forward-looking layer (the self-healing torrent **fleet/mesh**) is designed but
-not yet built.
+TV Anarchy is a native macOS (SwiftUI) front end — plus an iOS companion app —
+for a home media stack centered on **plum** (the laptop) and **black** (the
+media server). It unifies what was previously CLI/MCP-only: pick a playback
+device, browse a cached library, search and manage torrents, enrich metadata,
+and manage the device registry — all from one app. A larger, forward-looking
+layer (the self-healing torrent **fleet/mesh**) is designed but not yet built.
 
 This directory is the project's living documentation. Component-level READMEs stay
 next to their code; these documents are the cross-cutting reference.
@@ -22,9 +22,10 @@ next to their code; these documents are the cross-cutting reference.
 
 ## Component docs (next to the code)
 
-- [`../README.md`](../README.md) — the Swift app: targets, layout, build
+- [`../README.md`](../README.md) — the Swift apps (macOS + iOS): targets, layout, build
 - [`../governor/README.md`](../governor/README.md) — `portable-net-tv`: watch tracking + prefetch buffer
 - [`../mcp/README.md`](../mcp/README.md) — `plum-control-mcp`: VLC / black-tv / transmission / display tools
+- [`../search/README.md`](../search/README.md) — vendored torrent-search MCP fork (TPB/Nyaa/1337x)
 - [`../fleet/README.md`](../fleet/README.md) — fleet/mesh placeholder (not yet implemented)
 - [`../recommender/`](../recommender/) — Python enrichment + recommendations (`recommend_local.py`, `media_rec/`)
 

docs/data-model.md

@@ -7,26 +7,37 @@ and write these), and the **planned fleet/mesh data model** (designed, unbuilt).
 
 ## In use today
 
-### `hosts.json` — playback target config
+### `devices.json` — device registry + playback target config
 
-Path: `~/.config/tv-anarchy/hosts.json` (auto-migrated forward from the pre-rename
-`~/.config/plumtv/hosts.json`). Source: `Sources/TVAnarchyCore/HostConfig.swift`.
-Written pretty-printed + sorted-keys; seeded on first run with Plum VLC + Black
-(mpv) if absent.
+Path: `~/.config/tv-anarchy/devices.json` (auto-migrated forward from
+`~/.config/tv-anarchy/hosts.json`, and before that `~/.config/plumtv/hosts.json`).
+Source: `Sources/TVAnarchyCore/DeviceConfig.swift`. Written pretty-printed +
+sorted-keys; seeded on first run with Plum VLC + Black (mpv) if absent. The
+decoder accepts the legacy top-level `hosts` key alongside `devices`.
+
+Each device carries a `type` — `cellphone | laptop | storage | seed | broadcast`,
+mapping to the planned fleet classes `consumer | roamer | server | seedbox |
+broadcast` — and an overridable `services` preset (`stream`, `offlineCache`,
+`ttlSeed`, `custody`, `publicSwarmFace`, `f2fRelay`, `meshAnchor`). Legacy
+entries without a `type` get one inferred from the player backend.
 
 ```jsonc
 {
-  "hosts": [
+  "devices": [
     {
       "id": "plum-vlc",
       "name": "Plum VLC",
       "kind": "vlc",                 // vlc | mpv-ipc | quicktime | blacktv(legacy)
+      "type": "laptop",              // cellphone | laptop | storage | seed | broadcast
+      "services": { "stream": true, "offlineCache": true, "ttlSeed": true },
       "vlc": { "host": "127.0.0.1", "port": 8080 }
     },
     {
       "id": "black",
       "name": "Black TV",
       "kind": "mpv-ipc",
+      "type": "storage",
+      "services": { "stream": true, "custody": true },
       "mpv": {
         "endpoints": ["lilith@10.0.0.11", "lilith@10.9.0.4"], // LAN first, WG overlay fallback
         "socket": "/tmp/mpv.sock",   // default
@@ -88,6 +99,7 @@ filename (everything before the `SxxEyy` marker).
 
 | Artifact | Path | Writer |
 |---|---|---|
+| App settings | `~/.local/state/tv-anarchy/settings.json` | `SettingsStore` (adult gating, hover previews, media-key forwarding, offline-cache sizing; tolerant decode) |
 | Library snapshot | `~/.local/state/tv-anarchy/library.json` | `LibraryStore` |
 | Metadata sidecar | `~/.local/state/tv-anarchy/meta/<sha256(path)>.json` | `MetaWriter` (mirrored best-effort to `<remotePath>.meta` on black) |
 | Artwork cache | frame-grab JPEGs (keyed by path) | `ArtworkService` |
@@ -146,6 +158,12 @@ Duty = custody_floor | public_swarm_face | f2f_relay | broadcast
 Example fleet: black = server, apricot = secondary always-on, plum = roamer (TTL
 seeder), phone = consumer (pure sink, never any duty).
 
+> **Partially landed:** the app's `devices.json` (above) already carries the
+> class mapping (`DeviceType.fleetClass`) and a `services` preset that mirrors
+> the duty vocabulary. What does **not** exist is the manager that *assigns*
+> duties from capacity/reachability — services today are user-set presets, not
+> computed duties.
+
 ### Duty-assignment rules (deterministic, run on registry change)
 
 | Duty | Eligibility | Rule |

docs/operations.md

@@ -75,7 +75,8 @@ localhost+overlay networking).
 
 | File | Purpose |
 |---|---|
-| `~/.config/tv-anarchy/hosts.json` | Playback targets (migrates from `~/.config/plumtv/hosts.json`) |
+| `~/.config/tv-anarchy/devices.json` | Device registry + playback targets (migrates from `hosts.json`, then `~/.config/plumtv/hosts.json`) |
+| `~/.local/state/tv-anarchy/settings.json` | App settings (adult gating, previews, media keys, offline cache) |
 | `~/.config/portable-net-tv/config.json` | Governor config **and** the VLC HTTP password source |
 | `~/.local/state/plum-control-mcp/watched.jsonl` | Shared watch log |
 | `~/.local/state/tv-anarchy/library.json` | Cached library snapshot |
@@ -93,8 +94,9 @@ localhost+overlay networking).
   (`10.9.0.4`) because the LAN address flaps.
 - **QuickTime** — local, zero-install; no setup.
 
-Hosts are editable in-app (Hosts tab: add/edit/delete, make-active, reload, reset,
-reveal `hosts.json`).
+Devices are editable in-app (Devices tab: add/edit/delete, make-active, set
+type/services, reload, reset, reveal `devices.json`). The list shows a
+per-device system-load badge (low/med/high).
 
 ## governor (`portable-net-tv`)