tv-anarchy/docs/README.md

# TV Anarchy — Documentation

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.

**v2 pillar model** (Watch · Download · Net): see [`../v2/README.md`](../v2/README.md)
for the organizational lens; [`../v2/plan.md`](../v2/plan.md) for the full v1→v2
build plan.

## Living docs

| Doc | What it covers |
|---|---|
| [architecture.md](./architecture.md) | System shape — the shipped app, its helper subprocesses, and the planned mesh layer |
| [data-model.md](./data-model.md) | Config + state schemas in use today, and the planned fleet/mesh data model |
| [operations.md](./operations.md) | Build, install, run, configure, and deploy every component |
| [roadmap.md](./roadmap.md) | Status (built vs. designed) and the de-risked path to the full vision |
| [glossary.md](./glossary.md) | Domain terms (fleet, custody floor, duty, F2F relay, …) |

## Component docs (next to the code)

- [`../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) — `tv-anarchy-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/`)

## Design source of truth

- [`../.project/history/20260608_fleet-manager-mesh-design.md`](../.project/history/20260608_fleet-manager-mesh-design.md)
  — the captured design conversation for the fleet/mesh. The mesh sections of
  [architecture.md](./architecture.md) and [data-model.md](./data-model.md)
  synthesize it; that file remains the origin record.