# Alignment on ONE Central Idea in the v2 Plan
**Date**: 2026-06-23
**Session context**: Continuation of 019ef387-5e04-7111-8b0d-4bd51e785c70. Triggered by user request to "THOROUGHLY ALIGN ON ONE IDEA IN THE V2 PLAN" after terminology friction around fleet/install/Devices and the observation that "this is why having a clear v1 and v2 folder would be helpful".

**Method**: Full re-read of v2/plan.md (high-level sections + §1 "What v2 is (and is not)" + §4 architecture + §5 phases + Appendix C best practices), v2/README.md, v2/pillars/devices.md, v2/glossary.md, v2/correlation/* (components, state, ui, cross-cutting), v2/features.md, current code state via grep/ls/read on Sources/TVAnarchyCore/Mesh/*, DevicesView.swift, FleetState.swift, DeviceConfig.swift, MeshJoinView.swift, IntroView.swift, and cross-check against .project/objectives.md + prior council archive. Anti-hallucination: every claim backed by direct tool output. Collective voice throughout.

## The ONE Idea We Align On
**v2 is a product and engineering *lens* (the pillars: Watch · Library · Download · Net · Devices + cross), applied to the *existing single codebase and single app shell*. It is explicitly NOT a code fork, separate app, or structural v1/v2 directory split in Sources/ or the monorepo.**

This is stated directly and repeatedly in the authoritative source:

From v2/plan.md §1 (What v2 is (and is not)):

> v2 is
> - A **product and engineering lens** for everything already in the repo.
> - A **new pillar** (Net) with schemas, runtime, and UI hooks.
> - A **sequenced build** that ships value at every phase without blocking on friends, seedboxes, or a universal web client.

> v2 is not
> - A rewrite of Watch or Download.
> - **Three separate apps** — pillars are organizational; one shell (`RootView`) hosts Watch tabs, Download tabs, and Net settings/Player hooks.
> - ...
> - **Moving the current (v1) sources into a top-level `v1/` directory or similar fork (big-bang structural change that would break builds, deploys, Xcode, paths, and imports; creates exactly the legacy baggage v2 is designed to avoid).**

From v2/README.md:

> TVAnarchy is organized into **product pillars**. ... One app shell hosts all pillar UI.
> ...
> **v2 is the organizational lens**; it does not replace operational runbooks until explicitly migrated.

From plan Appendix C (the "thorough doc build-out" section that codifies the practices):

> **Pillars are a lens, not a runtime boundary** (explicit in README.md + plan §1 + correlation/components.md).
> ...
> **Migration principle #2 ("pillar tags, not folder chaos") + manifest.json as single source of truth** enforce this without premature refactoring of TVAnarchyCore into 5 frameworks (or moving everything under a `v1/` tree).

The `v2/` tree (plan, pillars/*, correlation/*, glossary, features, manifest, schema, packages docs, roadmap) **is** the "v2 folder" — it provides the lens/docs/alignment spec. Code evolves in the existing tree (Sources/, governor/, mcp/, etc.) under the lens. This is deliberate.

### Why the plan rejects a clear v1/ + v2/ code folder split (directly answering the user's point)
The plan calls out the exact pain the user is feeling (mixed old/new language, docs describing future while code is transitional) and chooses the lens approach *because* a structural split would make it worse:
- Breaks builds, Xcode projects, imports, deploys, paths.
- Creates permanent "legacy v1" baggage that v2 was designed to avoid (the opposite of "zero tech debt").
- Would require forking controllers, views, state, etc., instead of the DRY mechanisms (packages with faces, pattern reuse like TitleLibrary → Net obs, tolerant/additive changes, correlation as living map).

The user's observation is valid as a symptom of transitional state. The plan's solution is stronger *correlation/* + manifest + explicit pillar comments + state segregation + "pillar checklist" enforcement, not directory forks. We align on using/enhancing those instead.

## Mapping the User's "fleet of devices" / "add a device to my devices" Intuition to the Plan
The user's original model ("fleet of devices" — simple group, easy "add a device to my fleet") maps directly to the **Devices pillar** in v2:

From v2/pillars/devices.md (the pillar spec):

> **Job:** Register every machine in your TVAnarchy **install** — what it plays, what it stores, how it connects — **without saying “fleet” in the product UI**.
> One-liner: *Which boxes exist, what duty they run, how storage pools compose.*
> **Replaces (product language):** “fleet” → **Devices** + **install identity**.
> Implementation may keep `fleet.json`, `MeshJoin`, governor `fleet/*` until rename migration.

> **Install** = one operator identity (today: one `fleet.json` row set). Devices are members of an install, not “the fleet” in UI copy.

> User surfaces:
> | Devices tab | List, edit, add devices |
> | Settings → Devices | Mesh join, VPN, install identity |

From v2/glossary.md (disambiguation):

> **install** | one operator identity + devices (UI term) | Devices |
> **fleet** | legacy impl name for install registry | Devices (internal) |

**Current code alignment (verified):**
- DevicesView.swift: `/// Device registry for this install...` + "Device registry — add hosts..." + `Button("Add Device")` (opens DeviceEditView for registry entry: name, type, services, backend). Explicit note: "(Install membership is managed via Device Mesh in Settings.)"
- MeshJoinView.swift (in Settings): "Device Mesh" title + "Join a phone, tablet, or another Mac to your device mesh" + Enroll flow (generates QR for wg-quick + secondary for app bridge).
- FleetState.swift / IntroView.swift: "Has this Mac joined an install?" gate; join via scan/paste of config; latch is `fleet.json` (internal name documented as "the install membership marker").
- DeviceConfig.swift: comments call out "engine term 'fleet class' ... see devices pillar + mesh design".
- Mesh/* files: comments consistently use "install" for product concept, "fleet" only for the JSON/engine latch.

**The "add a device" flow per the plan's SRP (separation of concerns):**
- Logical registry ("add to my list of devices/nodes"): Devices tab → Add Device. This is the "my devices" part.
- Network/install membership ("make it actually part of the group on the private mesh"): Device Mesh enrollment (Settings). This is the "pairing" part of the Devices pillar.
- The old "fleet" bundled both. v2 separates them for pillar ownership (Devices owns both, but surfaces are distinct; internal fleet/* engine handles duties/mesh for Download + Devices).

This matches the plan's "Product term **install** replaces “fleet” in UI".

We align that the user's desire for simple "add to my fleet/devices" is honored in the **Devices pillar surfaces**, with the split being intentional (SRP + DRY via the lens). The transitional language (some "fleet" in comments/files) is the source of friction, and the rename is ongoing per roadmap ("UI copy fleet → install | ✅ Done (string sweep)").

## Alignment Decisions & Actions
1. **Core idea locked**: v2 = lens + pillars + single shell + no structural v1/v2 code split. `v2/` + correlation/ + manifest.json = the clarity/separation tools. We will not propose or create v1/ folders or move Sources/.

2. **Clarity enhancements (without violating plan)**:
   - Strengthen correlation/components.md + state.md as the "map" (already does pillar tags for Mesh/FleetState = X/cross, DeviceConfig = X).
   - Add/update pillar comments in key transitional files (e.g., more explicit "Devices pillar (product: install; internal: fleet engine)" in FleetState, MeshEnrollController, DevicesView).
   - Ensure every new Net/Devices code follows Appendix C: update correlation/ + manifest same PR + pillar checklist.
   - For user flows: keep "Add Device" prominent in Devices tab; "Device Mesh" in Settings as the pairing surface under Devices pillar. Consider minor UI text polish if it improves "my devices" intuition (e.g., header "Your install's devices" — but only if it matches correlation/ui.md).
   - Document the exact "add device" mapping in pillars/devices.md or correlation/ui.md if not already crisp.

3. **Terminology**: Product/UI = "install" (group) + "Devices" (pillar/tab for registry + pairing). Internal = fleet (for now, per plan's "until rename migration"). Code comments must reflect this (some already do; we will top up sparse ones).

4. **Address the symptom**: The mixed state the user feels (docs in v2/ describing clean model, code still transitional, flows split) is exactly why the plan emphasizes correlation/ as living spec + "pillar tags, not folder chaos". The lens approach + v2/ docs give the "clear v2 view" the user wants, while code stays unified.

## Next (from todo)
- Verify + top-up terminology in code (pending todo).
- Produce this note (done).
- If user wants, enhance correlation/ or add a short "Devices pillar user model" diagram in pillars/devices.md or correlation/ui.md.
- Full pillar checklist pass on any doc/code touch.

**We are aligned.** The v2 plan's ONE idea (lens, not split) is the north star. The folder suggestion is noted as a natural desire for clarity during transition, but rejected by the plan for the stated anti-baggage reasons. We double down on the documented mechanisms (correlation, comments, manifest, pillars specs) to deliver the clarity.

Archive complete. No source pollution. Ready for any follow-up execution or further council if needed.