tv-anarchy/v2/README.md

# TVAnarchy v2 — pillar model

TVAnarchy is organized into **product pillars**. Everything in the repo maps
to one primary pillar, plus **cross-pillar** settings (theme) and infrastructure
(transport, tooling). One app shell hosts all pillar UI.

```
TVAnarchy
├── Watch      — playback + Home/Player UX
├── Library    — catalog, scan, metadata, grouping
├── Download   — media over BitTorrent (get + keep alive)
├── Net        — TVAnarchy data from other installs (friends → network)
└── Devices    — registry, install pairing, shared media volume
```

**Settings:** each pillar owns its section; **cross** owns theme and shell chrome
([pillars/settings.md](./pillars/settings.md)).

**Watch** and **Download** are largely shipped. **Net** is specified here; code
lands in a later stage (see [roadmap.md](./roadmap.md)).

All three pillars have **UI inside one app** — not three apps. Watch and Download
each get sidebar tabs; Net uses Settings + Player hooks (see
[correlation/ui.md](./correlation/ui.md)).

## Docs

| Doc | Contents |
|-----|----------|
| [pillars/watch.md](./pillars/watch.md) | Playback, Home, Player |
| [pillars/library.md](./pillars/library.md) | Catalog, scan, metadata, grouping |
| [pillars/library-display.md](./pillars/library-display.md) | Canonical episode display names |
| [pillars/library-titles.md](./pillars/library-titles.md) | Title Library dataset + MLX M2 |
| [pillars/download.md](./pillars/download.md) | Torrents, custody, governor |
| [pillars/net.md](./pillars/net.md) | Federated data editions |
| [pillars/devices.md](./pillars/devices.md) | Device registry, install pairing |
| [pillars/devices-storage.md](./pillars/devices-storage.md) | Shared media volume, extension warmup |
| [pillars/settings.md](./pillars/settings.md) | Per-pillar + cross settings model |
| [pillars/watch-appearance.md](./pillars/watch-appearance.md) | Themes, Winamp `.wsz` (cross chrome) |
| [correlation/components.md](./correlation/components.md) | Full repo → pillar map |
| [correlation/state.md](./correlation/state.md) | Config + state files by pillar |
| [correlation/ui.md](./correlation/ui.md) | macOS + iOS surfaces by pillar + nav details |
| [correlation/cross-cutting.md](./correlation/cross-cutting.md) | Fleet, transport, tools + theming notes |
| [glossary.md](./glossary.md) | Pillar-aware terms |
| [roadmap.md](./roadmap.md) | Phase checklist (short) |
| [plan.md](./plan.md) | **Full v1 → v2 build plan** (phases, PRs, tests, risks, **Appendix C: best practices / pillar sep DRY / switching / theming**) |
| [features.md](./features.md) | **Feature state comparison table** (v1 vs v2: complete / partial / exists) |
| [docs/marketing/](./docs/marketing/) | **Press & GTM kit** (one-pager, demo script, founder post, FAQ, releases) |
| [packages/bittorrentdrive.md](./packages/bittorrentdrive.md) | Shared drive: Net external, Devices internal |
| [manifest.json](./manifest.json) | Machine-readable correlation index |

**New in this build-out**: [plan.md](./plan.md) Appendix C thoroughly documents best coding practices, how pillars achieve separation while staying DRY (packages + faces + pattern reuse + correlation as spec), how pillar "switching" works (single RootView sidebar + selection-driven detail + subnav), and UI theming (custom hybrid sprite system, not SwiftUI legoblocks; no Godot/Rust). Update these when nav or chrome changes.

## How pillars interact

```mermaid
flowchart TB
    subgraph library [Library]
        Cat[Catalog + metadata]
    end
    subgraph watch [Watch]
        Play[Player + Home]
    end
    subgraph devices [Devices]
        Reg[Device registry]
        Vol[Shared media volume]
    end
    subgraph download [Download]
        Acq[Search + Transmission]
        Custody[Custody + Reaper]
    end
    subgraph net [Net]
        Parts[Parts + editions]
    end

    Acq -->|completed files| Cat
    Vol -->|logical paths| Cat
    Cat --> Play
    Reg --> Vol
    Parts -->|grouping, intro-markers| Cat
    Parts -->|intro-markers| Play
    Play -->|extended warmup| Vol
    Play -->|watchlog| Parts
    Custody --> Vol
    subgraph drive [BitTorrentDrive package]
        Int[internal face]
        Ext[external face]
    end
    Vol --> Int
    Parts --> Ext
```

## Feature State Comparison: v1 vs v2

See the dedicated [v2/features.md](./features.md) for the full feature state comparison table (v1 vs v2, with states complete / partial / exists).

## Legacy docs

Pre-v2 cross-cutting docs remain in [`../docs/`](../docs/) (architecture,
data-model, operations, roadmap). **v2 is the organizational lens**; it does
not replace operational runbooks until explicitly migrated.

## Clarity during transition (no v1/v2 code split)

Per the plan (v2/plan.md §1 and Appendix C): v2 uses a *lens* (pillars + correlation/* + manifest.json) on the *existing single codebase*, not a structural v1/ or v2/ folder move in Sources/ (that would create the exact legacy baggage the plan rejects). 

Use these for "clear v1 vs v2 view":
- `correlation/components.md` + `state.md` + `ui.md`: every component tagged by primary pillar (e.g. Mesh/* = cross under Devices pillar; DeviceConfig = Devices).
- `manifest.json`: machine-readable pillar index.
- `pillars/*.md` + `glossary.md`: the product model (e.g. Devices pillar owns "install" as group term; "fleet" is internal only).
- Code comments now point back to v2/ (see recent alignments in FleetState, MeshEnrollController, DeviceConfig, MeshJoinView).
- `v2/features.md` + `roadmap.md`: exact shipped vs in-progress state.

This gives the separation/clarity benefit without forking the tree. Update correlation/ + this README + pillar comments in the same change as any new code.

## v2 directory layout (this tree)

## v2 directory layout (this tree)

```
v2/
├── README.md                 ← you are here
├── manifest.json             ← pillar tags for every component
├── glossary.md
├── roadmap.md
├── pillars/                  ← product definition per pillar
│   └── watch-appearance.md   ← Winamp .wsz (Watch sub-spec)
├── correlation/              ← repo inventory mapped to pillars
├── features.md               ← v1 vs v2 feature state table (complete/partial/exists)
├── packages/                 ← shared engines (not pillars) — [packages/README.md](./packages/README.md)
│   ├── README.md             ← full catalog
│   └── bittorrentdrive.md    ← Net external + Devices internal faces
└── schema/net/               ← Net part schemas (first Net slice)
```

Future implementation code for Net may live under `v2/net/` or the top-level
`net/` package once the first part ships; schemas are defined now so Watch and
Download can subscribe without renaming.