docs: add CLI guide, unify config docs, fix channel-numbering drift

A user asked how to set tunarr_stream_mode (hls_direct_v2) and
tunarr_channel_group via config.json and the answer was hard to find —
the CLI path had drifted into a 6-line stub and the config docs were
partly stale. This unifies the docs so both web and CLI users have one
canonical config reference.

- docs/cli.md (new): full "go full geek" CLI guide — interactive
  programmarr.py menu, calling the raw scripts directly (export →
  generate/LLM → create → fetch_images → sync) with a cron example,
  and hand-editing config.json for advanced keys. Points to --help for
  exhaustive flags per the repo's own convention.
- README.md: CLI section now links to docs/cli.md instead of a stub.
  Rewrote the stale Channel Numbering section (old channel_blocks
  block-sizes/gaps model → current channel_order sequential-from-1
  tight-pack). README "Advanced Configuration" table stays the single
  canonical config reference for shared keys.
- config.json.example: removed the dead channel_blocks sizes object,
  added a correct channel_order example (verified vs CANONICAL_ORDER).
- PROMPT.md / PROMPT.personal.md: fixed the static CLI numbering scheme
  fed to the LLM (block ranges + "leave gaps" → sequential-from-1, all
  9 categories) so the AI path emits valid numbering. (personal file is
  gitignored — fixed locally only.)

No code changed; the config surface was already unified (both UIs read
the same config.json). The gap was documentation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: AlpineArchitecture

PROMPT.md

@@ -21,9 +21,10 @@ and uses the context window more efficiently.
 Paste the prompt, then paste the full contents of `plex_library.csv` directly
 after it. Works with any LLM or interface that doesn't support file uploads.
 
-> **Note on the Channel Numbering Scheme below:** the ranges shown are the defaults. When you
-> copy the prompt from the web app, it regenerates that section to match your configured block
-> sizes (Settings → Channel Numbering) and start number. The static text here is what the CLI uses.
+> **Note on the Channel Numbering Scheme below:** the category order shown is the default. When
+> you copy the prompt from the web app, it regenerates that section to match your configured
+> category order (Settings → Channel Numbering) and start number. The static text here is what
+> the CLI uses.
 
 ---
 
@@ -40,14 +41,20 @@ You are a TV channel programmer. I have a self-hosted media server with the libr
 
 ## Channel Numbering Scheme
 
-Assign channel numbers following this cable TV block structure:
-- **10–19**: TV Marathons — 24/7 single-show loops (needs 50+ episodes to qualify)
-- **20–29**: TV Blocks — themed multi-show rotations (era blocks, genre blocks, etc.)
-- **30–49**: Movie Channels — genre and decade-based pools
-- **50–69**: Franchise & Curated Series — ordered collections (film series in release order, etc.)
-- **70–79**: Specialty — single-movie loops, holiday, niche themes
+Number channels **sequentially starting at 1**, tight-packed in this category order — no gaps,
+no reserved ranges. A category with no channels is simply skipped (it consumes no numbers).
 
-Keep numbers sequential within each block. Leave gaps for future additions.
+1. **TV Marathons** — 24/7 single-show loops (needs 50+ episodes to qualify)
+2. **TV Blocks** — themed multi-show rotations (era blocks, genre blocks, etc.)
+3. **TV & Movie Mix** — mixed-genre channels spanning shows and films
+4. **Movie Channels** — genre and decade-based pools
+5. **Studios / Directors / Actors** — channels curated by creator or studio
+6. **Networks** — all shows from a single TV network
+7. **Classic TV Blocks** — historical lineups (TGIF, Must See TV, etc.)
+8. **Franchise & Series** — ordered collections (film series in release order, etc.)
+9. **Specialty** — single-movie loops, holiday, niche themes
+
+Assign every channel the next free number — e.g. 12 marathons take 1–12, then TV Blocks start at 13.
 
 ## Shuffle Types
 
@@ -61,9 +68,9 @@ Each channel must have one of these shuffle types:
 Output one channel per line as a JSON object (JSONL). No wrapper object, no markdown fences, no commentary between lines — just one `{...}` per line.
 
 ```
-{"number": 10, "name": "Breaking Bad Marathon", "shuffle": "ordered", "content": ["Breaking Bad"]}
-{"number": 20, "name": "Crime TV Block", "shuffle": "block", "content": ["The Wire", "Ozark", "Justified"]}
-{"number": 30, "name": "80s Action Movies", "shuffle": "shuffle", "content": ["Die Hard", "Lethal Weapon", "Predator"]}
+{"number": 1, "name": "Breaking Bad Marathon", "shuffle": "ordered", "content": ["Breaking Bad"]}
+{"number": 2, "name": "Crime TV Block", "shuffle": "block", "content": ["The Wire", "Ozark", "Justified"]}
+{"number": 3, "name": "80s Action Movies", "shuffle": "shuffle", "content": ["Die Hard", "Lethal Weapon", "Predator"]}
 ```
 
 Each line must have exactly these fields:

README.md

@@ -224,12 +224,13 @@ These optional keys can be added directly to `config.json` (they're not in the U
 
 ### Channel Numbering
 
-Channels are grouped into five blocks — TV Marathons, TV Blocks, Movie Channels, Franchise &
-Series, Specialty — placed one after another. **Settings → Channel Numbering** lets you set how
-many channel numbers each block reserves (defaults `10/10/20/20/10`); enlarge a block to fit
-more channels if you have a big library. Numbering on a fresh deploy starts at channel **1**, and
-keeping existing channels shifts new ones above the highest you kept. (Stored as `channel_blocks`
-in `config.json`.)
+Channels are numbered **sequentially from 1**, tight-packed in category order — no fixed block
+sizes, no gaps. Categories run in this order: TV Marathons → TV Blocks → TV & Movie Mix → Movie
+Channels → Studios/Directors/Actors → Networks → Classic TV Blocks → Franchise & Series →
+Specialty. Empty categories consume no numbers. **Settings → Channel Numbering** lets you drag
+the categories into whatever order you prefer. Numbering on a fresh deploy starts at channel
+**1**; keeping existing channels shifts new ones above the highest you kept. (Stored as
+`channel_order`, a list of category keys, in `config.json` — omit it for the default order.)
 
 ### Commercials
 
@@ -239,13 +240,16 @@ Any channel can play commercials in the gaps between shows. In Tunarr, create a
 
 ## CLI (advanced)
 
-If you prefer the terminal, all the same functionality is available via `programmarr.py`:
+If you prefer the terminal, everything the web app does is available from the command line — no
+Docker, no extra server. The Python scripts have zero dependencies beyond the standard library.
 
 ```bash
 python programmarr.py
 ```
 
-The Python scripts have zero dependencies beyond the standard library and work standalone without Docker.
+**→ Full walkthrough: [`docs/cli.md`](docs/cli.md)** — the interactive menu, calling the raw
+scripts directly (cron-friendly), and editing `config.json` by hand for advanced keys like
+`tunarr_stream_mode` and `tunarr_channel_group`.
 
 ---
 

config.json.example

@@ -10,12 +10,6 @@
     "tunarr_channel_group": "programmarr",
     "tunarr_stream_mode": "hls",
 
-    "_channel_blocks": "Per-category block sizes — how many channel numbers each category reserves. Omit for defaults (10/10/20/20/10). Scale a category up for a large library. Editable in Settings.",
-    "channel_blocks": {
-        "marathon": 10,
-        "tv_block": 10,
-        "movie": 20,
-        "franchise": 20,
-        "specialty": 10
-    }
+    "_channel_order": "Category order for sequential channel numbering. Channels are tight-packed from 1 in this order — no block sizes, no gaps. Omit for the default order. Editable in Settings → Channel Numbering.",
+    "channel_order": ["marathon", "tv_block", "tv_movie_mix", "movie", "entity", "network", "programming_block", "franchise", "specialty"]
 }

docs/cli.md

@@ -0,0 +1,126 @@
+# CLI guide (no Docker required)
+
+Programmarr started as a handful of Python scripts, and they're all still here. If you'd
+rather not run another server on your network, you can do **everything the web app does** from
+the terminal. The scripts have **zero dependencies beyond the Python 3 standard library** and
+run standalone.
+
+> **Where config lives:** in the CLI, `config.json` sits in the **project root** (next to
+> `programmarr.py`). In Docker it lives in `data/`. Same file shape either way — see
+> [`config.json.example`](../config.json.example) and the **Advanced Configuration** table in
+> the [README](../README.md#advanced-configuration) for every key (including `tunarr_stream_mode`
+> and `tunarr_channel_group`).
+
+## Requirements
+
+- Python 3 (no `pip install` needed — stdlib only)
+- A running [Tunarr](https://github.com/chrisbenincasa/tunarr) instance and a Plex server
+- Optionally a [TMDB API key](https://www.themoviedb.org/settings/api) for channel logos
+
+```bash
+git clone https://github.com/AlpineArchitecture/programmarr.git
+cd programmarr
+python programmarr.py
+```
+
+---
+
+## Path A — the interactive menu
+
+`python programmarr.py` is the guided front door. On first run (no `config.json` yet) it walks
+you through a short setup wizard, then drops you at the main menu:
+
+```
+  1) AI path         — export → LLM → deploy
+  2) No-AI path      — auto-generate → deploy
+  3) Collections     — sync Plex collections → deploy
+
+  i) Fetch channel images from TMDB
+  s) Sync channels to Plex DVR
+
+  q) Quit
+```
+
+- **AI path** — exports your library, builds a prompt you paste into an LLM (Claude/Gemini/ChatGPT),
+  then deploys the `channels.json` the LLM returns. Always probes before deploying and asks
+  whether to wipe-and-rebuild or preserve channels below a number.
+- **No-AI path** — generates a starter `channels.json` straight from your library metadata
+  (decade + genre movie channels, 50+ episode TV marathons) and deploys it. No LLM involved.
+- **Collections** — turns your Plex collections (managed by Kometa/Trakt/Letterboxd) into
+  channels, one per collection.
+- **i / s** — run the image fetch or Plex-DVR sync on their own.
+
+> **The wizard only writes the required keys** (`tunarr_url`, `plex_url`, `plex_token`, and TMDB
+> if given). Advanced keys are **not** prompted — see [Setting advanced config](#setting-advanced-config)
+> below to add them by hand.
+
+---
+
+## Path B — raw scripts (for cron and scripting)
+
+The menu just orchestrates these. Call them directly for automation. **Every script takes
+`--help`** — that's the authoritative flag reference; this guide only shows the chain and the
+gotchas worth knowing.
+
+```
+export.py  →  generate_no_ai.py   →  create.py  →  fetch_images.py  →  sync_plex.py
+              (or hand off to an LLM)
+```
+
+| Script | What it does |
+|--------|--------------|
+| `export.py` | Pulls full metadata from Plex → `plex_library.csv` + `export_summary.json`. Auto-detects movie + TV sections. |
+| `generate_no_ai.py` | Builds a starter `channels.json` from the CSV (no AI). `--order KEY,KEY,…` overrides category order; `--start N` sets the first channel number. |
+| `generate_from_collections.py` | One channel per Plex collection. `--apply` to write; manages the collection block from `--base` up. |
+| `create.py` | Reads `channels.json` and deploys to Tunarr (delete-then-create). `--from N` scopes; `--protect N1,N2` preserves specific channels. |
+| `fetch_images.py` | Sets every channel's Tunarr icon (verified TMDB logos + generated badges). **Dry-run by default; `--apply` to commit.** |
+| `sync_plex.py` | Reconciles Tunarr's channel list into Plex's DVR mapping. Never deletes the DVR. |
+
+### Example: nightly no-AI rebuild via cron
+
+```bash
+#!/usr/bin/env bash
+cd /opt/programmarr
+python export.py
+python generate_no_ai.py
+python create.py
+python fetch_images.py --apply
+python sync_plex.py
+```
+
+```cron
+# 4am daily
+0 4 * * *  /opt/programmarr/rebuild.sh >> /var/log/programmarr.log 2>&1
+```
+
+> Live (auto-updating) channels are a feature of the **web app's** in-process scheduler. From the
+> CLI, a cron rebuild like the above is the equivalent — re-run the chain on whatever schedule you like.
+
+---
+
+## Setting advanced config
+
+Keys like the channel stream mode and the Tunarr group aren't in the setup wizard. Add them to
+`config.json` by hand — they sit right alongside the connection settings:
+
+```json
+{
+    "tunarr_url": "http://192.168.1.10:8000",
+    "plex_url": "http://192.168.1.10:32400",
+    "plex_token": "your-plex-token",
+
+    "tunarr_stream_mode": "hls_direct_v2",
+    "tunarr_channel_group": "Saturday Morning"
+}
+```
+
+- **`tunarr_stream_mode`** — one of `hls`, `hls_slower`, `mpegts`, `hls_direct`, `hls_direct_v2`
+  (default `hls`). Applied by `create.py` at channel creation.
+- **`tunarr_channel_group`** — the Tunarr group/folder all created channels land in (default
+  `tunarr`).
+- **`channel_order`** — array of category keys controlling numbering order, e.g.
+  `["marathon","tv_block","movie","franchise","specialty"]`. Omit for the default order. See
+  [Channel Numbering](../README.md#channel-numbering).
+
+The full key list is in [`config.json.example`](../config.json.example) and the README's
+[Advanced Configuration](../README.md#advanced-configuration) table.