Bump version to v0.2.1 — channel protection and offset features

## Channel protection (--protect flag)
Users can now preserve specific Tunarr channels during a deploy instead of
always nuking everything. Protected channel numbers are passed to create.py
via --protect N1,N2,... and skipped during the deletion phase.

- create.py: added --protect NUMS argparse flag; delete_channels() accepts a
  protect=set[int] and skips those numbers, printing "Preserving #N name (protected)"
- pipeline_router.py: deploy endpoint accepts protected= query param and no_delete bool;
  DeployRequest Pydantic model adds protected_numbers: list[int] and no_delete: bool;
  deploy-selective passes --protect and --no-delete to create.py as needed

## Channel offset (--start flag)
generate_no_ai.py now accepts --start N (default 10) which offsets all block
ranges by N-10, so users can leave lower channel numbers free for channels
they want to keep. The web UI passes this automatically based on the user's
selection in the Channel Planner step.

- generate_no_ai.py: --start N flag; all hardcoded block numbers (TV Marathons
  at 10, TV Blocks at 20, Movies at 30–49, Franchise at 50–69, Specialty at 70–71)
  now add offset; renamed loop var start -> yr_start to avoid shadowing
- pipeline_router.py: get_prompt accepts start param and replaces block range
  strings in PROMPT.md (**10–19** etc.) and example numbers; run_no_ai passes
  --start N when start != 10

## Channel Planner UI (AI path step 2, formerly "LLM Handoff")
The LLM Handoff step was renamed to Channel Planner and now serves as the
decision point for what to do with existing channels before generating a new
lineup. This makes the workflow feel more intentional: see your current lineup,
decide what to keep, then generate channels that fit around what you're keeping.

- Shows all current Tunarr channels as a scrollable checklist on mount
- All channels checked by default (keep all); uncheck to clear and replace
- Summary text turns yellow with explicit "cleared / rebuilt as new stations"
  language when any channel will be deleted
- "Channels start at" auto-calculates from the highest checked channel,
  rounded up to the nearest 10 (e.g. highest kept is #24 → start at 30).
  Auto-updates live as checkboxes are toggled. Resets to 1 when all unchecked.
- Checked channel numbers are passed up to AIPath as protectedNums and down
  to DeployStep as inheritedProtectedNums, bypassing the per-deploy panel

## Deploy step simplification
Removed the "Replace existing channels / Add new channels only" SegmentedControl
toggle. The checkbox model in Channel Planner subsumes both modes:
  - All checked = keep all (equivalent to "add new only")
  - None checked = replace all (equivalent to "replace existing")
  - Mix = granular per-channel control the old toggle couldn't offer

- DeployStep: removed deployMode prop/state/SegmentedControl; added
  inheritedProtectedNums?: number[] prop; shows inherited protection summary
  when provided (AI path) or own protection panel when not (No-AI/Collections)
- Protection panel in Deploy (No-AI/Collections path): channels not being
  redeployed are protected by default; channels being redeployed are not
- Conflict detection unchanged: red highlight + disabled deploy button when a
  protected number collides with a deploy channel number

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: AlpineArchitecture

CLAUDE.md

@@ -166,6 +166,7 @@ See `config.json.example` for the template.
 - Auto-generates decade channels (year filtering) and genre channels (genre tag matching)
 - Auto-generates TV marathon channels for shows with 50+ episodes
 - Writes placeholder entries for franchise/themed channels (user fills manually)
+- `--start N` — offsets all block ranges by `N - 10` (default: 10). E.g. `--start 30` shifts TV Marathons to 30–39, TV Blocks to 40–49, etc., leaving lower numbers free for pre-existing channels. Passed automatically by the web UI.
 - Output: `channels.json`
 
 **`generate_from_collections.py`** (Option C — Plex collections as channels)
@@ -180,6 +181,7 @@ See `config.json.example` for the template.
 - Reads `channels.json`
 - Indexes Tunarr library (exact title matching, case-insensitive)
 - Deletes all existing channels then creates new ones (use `--from N` to scope to channels >= N, preserving lower channels and their custom images)
+- `--protect N1,N2,...` — comma-separated channel numbers to skip during deletion; these channels remain in Tunarr untouched regardless of scope. Printed as "Preserving #N name (protected)" during the run.
 - Builds Tunarr random-schedule payloads (30-day rolling window — channels loop forever, no dead air)
 - Output: channels live in Tunarr
 
@@ -270,15 +272,15 @@ A title can appear on multiple channels — this is intentional and expected.
 | POST | `/api/pipeline/export` | SSE-stream `export.py`; JSON body `{"no_crossref": bool, "movie_sections": ["1","2"], "tv_sections": ["3"]}` — sections are Plex section keys; `null` = auto-detect, `[]` = skip that type |
 | GET | `/api/pipeline/csv` | Download `plex_library.csv` |
 | GET | `/api/pipeline/csv/info` | Stats: rows, movies, tv_shows, skipped counts, preview lines |
-| GET | `/api/pipeline/prompt` | Fetch `PROMPT.md` with `{TARGET}` and preferences injected |
+| GET | `/api/pipeline/prompt` | Fetch `PROMPT.md` with `{TARGET}`, preferences, and `start` (block offset) injected; query params: `target`, `preferences`, `start` |
 | POST | `/api/pipeline/validate` | Parse/validate LLM output (file upload or raw text), write `channels.json` |
-| POST | `/api/pipeline/no-ai` | SSE-stream `generate_no_ai.py` |
+| POST | `/api/pipeline/no-ai` | SSE-stream `generate_no_ai.py`; query param `start=N` passed as `--start N` |
 | GET | `/api/pipeline/collections` | Fetch all Plex collections (id, name, count, section, summary, has_poster) |
 | GET | `/api/pipeline/collections/{id}/poster` | Proxy Plex collection poster image |
 | POST | `/api/pipeline/collections/apply` | Write selected collections into `channels.json` |
 | POST | `/api/pipeline/probe` | SSE-stream `create.py --probe` |
-| POST | `/api/pipeline/deploy` | SSE-stream `create.py` (full deploy) |
-| POST | `/api/pipeline/deploy-selective` | Filter channels by `DeploySelection[]`, write `deploy_temp.json`, SSE-stream `create.py --json deploy_temp.json` |
+| POST | `/api/pipeline/deploy` | SSE-stream `create.py`; query params: `protected` (comma-separated channel numbers to preserve), `no_delete` (bool) |
+| POST | `/api/pipeline/deploy-selective` | JSON body `DeployRequest{selections, protected_numbers, no_delete}`; filters channels.json to selected entries, writes `deploy_temp.json`, SSE-streams `create.py --json deploy_temp.json [--protect N1,N2,...] [--no-delete]` |
 | POST | `/api/pipeline/images` | SSE-stream `fetch_images.py --apply` |
 | POST | `/api/pipeline/sync` | SSE-stream `sync_plex.py` |
 
@@ -293,15 +295,27 @@ A title can appear on multiple channels — this is intentional and expected.
 
 **AI Path (6 steps):**
 1. **Export** — fetches Plex library list on mount; shows "Libraries to scan" card with checkboxes grouped by Movies / TV Shows (all checked by default, supports multi-select across libraries of the same type); runs `export.py` with selected section keys; shows compact stats card on success; manual Continue
-2. **LLM Handoff** — config card (channel count NumberInput + theme Textarea); side-by-side prompt copy + CSV download; paste/upload LLM output; post-validate results card showing channel breakdown; "Add Plex Collections" or "Skip to Deploy" buttons
-3. **Add Plex Collections** — fetches collections on mount; 2-column grid with poster, name, count, editable channel number, checkbox (all checked by default); applies selections to `channels.json`
-4. **Deploy** — probe explainer card; runs probe; after probe completes: 2-column layout [terminal | scrollable channel review card with checkboxes + editable channel numbers]; selective deploy via `/pipeline/deploy-selective`
+2. **Channel Planner** — shows current Tunarr lineup as a scrollable checkable list (all checked by default = keep; uncheck = delete and replace with new station); auto-calculates "Channels start at" from the highest checked channel number, rounded up to the nearest 10 (e.g. highest checked is #24 → start at 30); summary line turns yellow and uses explicit "cleared / rebuilt" language when channels will be deleted; config card (target channel count NumberInput + "Channels start at" NumberInput + theme Textarea); side-by-side prompt copy + CSV download; paste/upload LLM output; post-validate results card showing channel breakdown; "Add Plex Collections" or "Skip to Deploy" buttons. Checked channel numbers are passed to Deploy step as `inheritedProtectedNums`.
+3. **Add Plex Collections** — fetches collections on mount; list with poster, name, count, editable channel number, checkbox (all checked by default); applies selections to `channels.json`
+4. **Deploy** — probe explainer card; shows note about how many channels will be kept (from Channel Planner); runs probe; after probe completes: 2-column layout [terminal | scrollable channel review card with checkboxes + editable channel numbers]; conflict detection highlights red when a deploy number collides with a protected number; selective deploy via `/pipeline/deploy-selective` with `protected_numbers` from Channel Planner
 5. **Fetch Images** — skippable step; runs `fetch_images.py --apply`
 6. **Sync Plex** — skippable step; runs `sync_plex.py`; post-deploy stats + links to Tunarr and Plex Live TV
 
-**No-AI Path (6 steps):** Same as AI but step 2 runs `generate_no_ai.py` instead of LLM handoff. Step 1 (Export) has the same library picker.
-
-**Collections Path (4 steps):** Collections → Deploy → Fetch Images → Sync Plex (no export or LLM).
+**No-AI Path (6 steps):**
+1. **Export** — same as AI path
+2. **Generate** — "Channels start at" NumberInput (default 1); runs `generate_no_ai.py --start N`; shows channel count on success
+3. **Collections** — same as AI path
+4. **Deploy** — same as AI Deploy step but with its own protection panel (no inherited protection): shows all existing Tunarr channels after probe, with channels NOT being redeployed checked (protected) by default; user adjusts before deploying
+5. **Fetch Images** — same as AI path
+6. **Sync Plex** — same as AI path
+
+**Collections Path (4 steps):** Collections → Deploy (with own protection panel) → Fetch Images → Sync Plex (no export or LLM).
+
+**Channel protection model:**
+- AI path: user decides which existing channels to keep in the **Channel Planner** step, before even generating the LLM prompt. Checked = protected (passed to deploy as `inheritedProtectedNums`). Deploy step shows a summary and skips the per-deploy panel.
+- No-AI / Collections path: user decides in the **Deploy** step's own protection panel after the probe. Channels not in the current deploy are protected by default; channels being redeployed are unprotected by default.
+- In both cases, protected channel numbers are passed to `create.py` via `--protect N1,N2,...`.
+- Conflict detection: if a protected number equals a deploy channel's `deployNumber`, the row highlights red and the deploy button is disabled until resolved (renumber or unprotect).
 
 **`deploy_temp.json`:** Written by `/pipeline/deploy-selective` when the user excludes channels from a deploy session. The original `channels.json` is not modified — only the channels the user chose are deployed.
 

README.md

@@ -147,6 +147,8 @@ All three paths end with a probe (dry run) → deploy to Tunarr. The app streams
 
 ### Also included
 
+- **Channel protection** — before deploying, choose which existing Tunarr channels to keep. Checked = preserved; unchecked = cleared and rebuilt as new stations. The "Channels start at" number auto-adjusts to leave room for whatever you keep.
+- **Channel offset** — set a starting channel number so new channels don't collide with ones you want to keep. Auto-calculated from your highest protected channel, rounded to the nearest 10.
 - **Library picker** — choose which Plex libraries to scan (Movies, 4K Movies, Kids TV, etc.) before each export; supports mixing multiple libraries of the same type
 - **Channel logo fetching** — pulls TMDB clearlogos for single-show/movie channels
 - **Plex DVR sync** — maps new channels into the Plex Live TV guide automatically

backend/routers/pipeline_router.py

@@ -182,7 +182,7 @@ def csv_info():
 
 
 @router.get("/pipeline/prompt")
-def get_prompt(target: str = "", preferences: str = ""):
+def get_prompt(target: str = "", preferences: str = "", start: int = 10):
     for candidate in [DATA_DIR / "PROMPT.md", SCRIPTS_DIR / "PROMPT.md"]:
         if candidate.exists():
             content = candidate.read_text(encoding="utf-8")
@@ -197,6 +197,16 @@ def get_prompt(target: str = "", preferences: str = ""):
                     f"{preferences}\n"
                 )
                 content = content.replace("## Channel Numbering Scheme", inj + "\n## Channel Numbering Scheme")
+            if start != 10:
+                o = start - 10
+                content = content.replace("**10–19**", f"**{10+o}–{19+o}**")
+                content = content.replace("**20–29**", f"**{20+o}–{29+o}**")
+                content = content.replace("**30–49**", f"**{30+o}–{49+o}**")
+                content = content.replace("**50–69**", f"**{50+o}–{69+o}**")
+                content = content.replace("**70–79**", f"**{70+o}–{79+o}**")
+                content = content.replace('"number": 10,', f'"number": {10+o},')
+                content = content.replace('"number": 20,', f'"number": {20+o},')
+                content = content.replace('"number": 30,', f'"number": {30+o},')
             return {"content": content}
     raise HTTPException(404, "PROMPT.md not found")
 
@@ -238,8 +248,11 @@ async def validate(file: Optional[UploadFile] = File(None), content: Optional[st
 
 
 @router.post("/pipeline/no-ai")
-async def run_no_ai():
-    return _sse(_stream("generate_no_ai.py", [], "no_ai"))
+async def run_no_ai(start: int = Query(10)):
+    args = []
+    if start != 10:
+        args += ["--start", str(start)]
+    return _sse(_stream("generate_no_ai.py", args, "no_ai"))
 
 
 @router.post("/pipeline/collections")
@@ -263,23 +276,33 @@ async def run_probe(from_channel: Optional[str] = Query(None)):
 
 
 @router.post("/pipeline/deploy")
-async def run_deploy(from_channel: Optional[str] = Query(None)):
+async def run_deploy(from_channel: Optional[str] = Query(None), protected: str = Query(""), no_delete: bool = Query(False)):
     args = []
+    if no_delete:
+        args.append("--no-delete")
     if from_channel:
         args += ["--from", from_channel]
+    if protected:
+        args += ["--protect", protected]
     return _sse(_stream("create.py", args, "deploy"))
 
 
+class DeployRequest(BaseModel):
+    selections: list[DeploySelection]
+    protected_numbers: list[int] = []
+    no_delete: bool = False
+
+
 @router.post("/pipeline/deploy-selective")
-async def run_deploy_selective(selections: list[DeploySelection]):
+async def run_deploy_selective(req: DeployRequest):
     channels_path = DATA_DIR / "channels.json"
     if not channels_path.exists():
         raise HTTPException(404, "channels.json not found")
 
     with open(channels_path, encoding="utf-8") as f:
         data = json.load(f)
 
-    sel_map = {s.original_number: s for s in selections if s.include}
+    sel_map = {s.original_number: s for s in req.selections if s.include}
     new_channels = [
         {**ch, "number": sel_map[ch["number"]].deploy_number}
         for ch in data.get("channels", [])
@@ -291,7 +314,12 @@ async def run_deploy_selective(selections: list[DeploySelection]):
     with open(temp_path, "w", encoding="utf-8") as f:
         json.dump(data, f, indent=2, ensure_ascii=False)
 
-    return _sse(_stream("create.py", ["--json", "deploy_temp.json"], "deploy"))
+    args = ["--json", "deploy_temp.json"]
+    if req.no_delete:
+        args.append("--no-delete")
+    if req.protected_numbers:
+        args += ["--protect", ",".join(str(n) for n in req.protected_numbers)]
+    return _sse(_stream("create.py", args, "deploy"))
 
 
 @router.post("/pipeline/images")

create.py

@@ -246,25 +246,31 @@ def build_schedule(shuffle_type, resolved_items):
 
 # ── Channel operations ─────────────────────────────────────────────────────────
 
-def delete_channels(tunarr_url, probe, from_ch=None):
+def delete_channels(tunarr_url, probe, from_ch=None, protect=None):
+    protect = protect or set()
     existing = api(tunarr_url, "GET", "/api/channels") or []
     if not existing:
         print("  No existing channels to delete")
         return
-    targets = [ch for ch in existing if from_ch is None or ch.get("number", 0) >= from_ch]
-    if not targets:
+    in_scope = [ch for ch in existing if from_ch is None or ch.get("number", 0) >= from_ch]
+    targets = [ch for ch in in_scope if ch.get("number", 0) not in protect]
+    preserved = [ch for ch in in_scope if ch.get("number", 0) in protect]
+    if not targets and not preserved:
         print(f"  No channels >= {from_ch} to delete")
         return
     scope = f">= #{from_ch}" if from_ch is not None else "all"
-    print(f"  Deleting {len(targets)} channels ({scope})...")
-    for ch in targets:
-        if probe:
-            print(f"    [PROBE] Would delete #{ch['number']} {ch['name']}")
-        else:
-            result = api(tunarr_url, "DELETE", f"/api/channels/{ch['id']}")
-            if result is not None:
-                print(f"    Deleted #{ch['number']} {ch['name']}")
-            time.sleep(0.1)
+    if targets:
+        print(f"  Deleting {len(targets)} channels ({scope})...")
+        for ch in targets:
+            if probe:
+                print(f"    [PROBE] Would delete #{ch['number']} {ch['name']}")
+            else:
+                result = api(tunarr_url, "DELETE", f"/api/channels/{ch['id']}")
+                if result is not None:
+                    print(f"    Deleted #{ch['number']} {ch['name']}")
+                time.sleep(0.1)
+    for ch in preserved:
+        print(f"    {'[PROBE] ' if probe else ''}Preserving #{ch['number']} {ch['name']} (protected)")
 
 
 def create_channel(tunarr_url, number, name, transcode_id):
@@ -321,6 +327,8 @@ def main():
     parser.add_argument("--no-delete", action="store_true", help="Skip deleting existing channels")
     parser.add_argument("--from", dest="from_ch", type=int, default=None, metavar="N",
                         help="Only operate on channels numbered N and above (preserves lower channels)")
+    parser.add_argument("--protect", dest="protect", default="", metavar="NUMS",
+                        help="Comma-separated channel numbers to protect from deletion")
     args = parser.parse_args()
 
     cfg = load_config()
@@ -374,9 +382,17 @@ def main():
         sys.exit(1)
 
     # ── Delete existing channels ───────────────────────────────────────────────
+    protect_set: set[int] = set()
+    if args.protect:
+        for n in args.protect.split(","):
+            try:
+                protect_set.add(int(n.strip()))
+            except ValueError:
+                pass
+
     if not args.no_delete:
         print("\nDeleting existing channels...")
-        delete_channels(tunarr_url, args.probe, from_ch=args.from_ch)
+        delete_channels(tunarr_url, args.probe, from_ch=args.from_ch, protect=protect_set)
 
     # ── Create channels ────────────────────────────────────────────────────────
     print(f"\n{'[PROBE] ' if args.probe else ''}Creating {len(channels)} channels...")

docker-compose.yml

@@ -1,7 +1,7 @@
 services:
   programmarr:
     image: ghcr.io/alpinearchitecture/programmarr:latest
-    # build: .   # uncomment to build from source instead
+    # build: .   # uncomment for local testing
     container_name: programmarr
     restart: unless-stopped
     ports:

frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "programmarr",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "scripts": {

frontend/src/api/client.ts

@@ -30,10 +30,11 @@ export const api = {
   getLibraryTitles: () => req<string[]>('/library/titles'),
 
   getCsvInfo: () => req<CsvInfo>('/pipeline/csv/info'),
-  getPrompt: (target?: string, prefs?: string) => {
+  getPrompt: (target?: string, prefs?: string, start?: number) => {
     const p = new URLSearchParams();
     if (target) p.set('target', target);
     if (prefs) p.set('preferences', prefs);
+    if (start !== undefined && start !== 10) p.set('start', String(start));
     return req<{ content: string }>(`/pipeline/prompt?${p}`);
   },
   validateText: async (content: string) => {