feat: icon overhaul + multi-source library support

Merge feature/icon-overhaul → master

### Icons
- badge_renderer: generated channel badges (glyph + stamped name, Tabler MIT + Anton OFL)
- icon_engine: verified TMDB searches — name must match query; kind-gated policy
- fetch_images rewrite: kind-gated TMDB + badge fallback; pinned channels skipped
- Tunarr helpers: multipart image upload + set/clear channel icon
- Channels-editor icon control: badge / TMDB / custom / reset with pin support
- POST /channels/{number}/icon endpoint

### Multi-source library support
- export.py: auto-supplements primary Plex export from all other Tunarr sources
- channel_engine: indexes all Tunarr Plex sources (not just first)
- pipeline_router: library picker aggregates all Tunarr-connected sources
- Export step: divider-labelled source groups in the library picker

### Planner
- Nuke mode now clears candidate selections on setup screen

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

Author: AlpineArchitecture

CLAUDE.md

@@ -136,7 +136,9 @@ All config lives in `config.json` (gitignored — in `data/` for Docker, project
 See `config.json.example` for the full shape. Keys:
 
 - `tunarr_url`, `plex_url`, `plex_token` — required connection settings.
-- `tmdb_api_key` — optional; only `fetch_images.py` uses it. Free key at https://www.themoviedb.org/settings/api
+- `tmdb_api_key` — optional; used by `fetch_images.py` for verified TMDB logo lookups.
+  Without it, every channel gets a generated badge instead (icons still work). Free key at
+  https://www.themoviedb.org/settings/api
 - `auth_username` / `auth_password` — optional HTTP Basic Auth. **Both blank = auth disabled.** When set, every backend request requires them.
 - `recipes_enabled` (bool, default `false`), `recipe_interval_hours` (number, default `12`) — live-channel scheduler (see Live Channels).
 - `tunarr_channel_group` (string, optional) — Tunarr `groupTitle` for all created channels (default `"tunarr"`).
@@ -159,7 +161,20 @@ and the code — don't restate them here.
 - **`generate_from_collections.py`** — one channel per Plex collection via `{"collection":"Name"}`. Manages the collection block (default ch 80+): keeps everything below `--base`, regenerates from `--base` up. Re-run any time Kometa changes collections.
 - **`channel_engine.py`** — shared, **pure, importable** resolution engine (no `config.json`/argv/`sys.exit`), so it's safe to import into the long-lived FastAPI process. Holds the resolution helpers, franchise `match_titles` (word-boundary), and the in-place live-channel updaters (`read_channel_programming`, `update_channel_in_place`). Imported by `create.py` at runtime and in-process by `recipes_router.py` — **must stay in the Dockerfile `COPY` line**. `build_library_index` indexes **all** enabled movie and shows libraries (not just the first — a Plex server can expose several, e.g. `TV Shows` + `Cartoons`), and indexes a show that appears in more than one library **once**, preferring the copy with the most playable (non-`missing`) episodes so a dead duplicate can't shadow the real one or inflate the live-diff into churn.
 - **`create.py`** — thin CLI wrapper around `channel_engine`. Reads `channels.json`, indexes the Tunarr library (case-insensitive exact title match), and deploys (delete-then-create; `--from N` scopes, `--protect N1,N2` preserves specific channels). Builds 30-day rolling random schedules (no dead air). The delete/recreate path is **initial-deploy only** — never for live channels.
-- **`fetch_images.py`** — for solo-title channels, finds the best TMDB clearlogo and sets the Tunarr channel `icon.path` so Plex shows a real logo in the guide. Multi-title channels are skipped. Dry-run by default; `--apply` to commit. Requires `tmdb_api_key`.
+- **`fetch_images.py`** — sets every channel's Tunarr icon. Verified TMDB logos for
+  solo-title/marathon/franchise/network/studio channels (the result's name must match the
+  query after normalization — never `results[0]`); generated badge art for every other kind
+  and any TMDB miss. Badges upload via Tunarr `POST /api/upload/image`. Channels pinned from
+  the Channels editor (`"icon": {"pinned": true}` in channels.json) are skipped; the script
+  never writes channels.json. `tmdb_api_key` is optional — without it everything badges.
+  Dry-run by default; `--apply` to commit.
+- **`icon_engine.py`** — shared, **pure, importable** icon policy + verified TMDB searches +
+  Tunarr upload/icon helpers (no `config.json`/argv/`sys.exit`). Imported by `fetch_images.py`
+  and in-process by `channels_router.py`. **Must stay in the Dockerfile `COPY` line.**
+- **`badge_renderer.py`** — shared, **pure** Pillow badge rendering from committed
+  `badge_assets/` (Tabler glyphs MIT, Anton font OFL; regenerate via
+  `scripts/make_badge_assets.py`). Badges carry the channel name because Plex hides text
+  labels once an icon is set. **Module + `badge_assets/` must stay in the Dockerfile `COPY` lines.**
 - **`sync_plex.py`** — reconciles Tunarr's XMLTV channel list into Plex's DVR mapping (read-then-update; **never deletes** the DVR). Falls back to printing the XMLTV URL + manual steps.
 
 ## Channel Numbering Scheme
@@ -277,6 +292,12 @@ the basis for future era-matched pooling (90s ads → 90s channel; see `docs/ide
 **Mid-roll (ads inside a show) is deliberately not used — it doesn't stream on hardware-accelerated
 (QSV) Tunarr; see [`docs/tunarr-commercials-findings.md`](docs/tunarr-commercials-findings.md).**
 
+**Icon pin (optional).** A channel may carry `"icon": {"mode": "badge"|"tmdb"|"custom",
+"url": "…", "pinned": true}` — written only by `POST /api/channels/{number}/icon` (the
+Channels-editor icon control). `fetch_images.py` skips pinned channels and never writes
+this field; removing it (the editor's "Reset to automatic") returns the channel to the
+automatic art pass.
+
 ## API Endpoints
 
 All endpoint tables — **Pipeline**, **Recipe**, **Tunarr**, **TMDB**, **Plex** — live in
@@ -303,10 +324,12 @@ AI" toggle is on; Collections only if opted in.
   - **Saved on every change** via a debounced (~500ms) PUT in `PlannerStep` (guarded by
     `restoredRef` so the first-mount restore never overwrites the file).
   - **Restored on every Planner mount** (both Nuke and Edit modes) — `isEdit` gate removed.
-  - **Nuke does NOT clear picks** — `handleNuke` is intentionally a no-op for state.
-  - **"Clear all"** in the Planner build bar is the only thing that resets picks: clears
-    `selected`, `curate`, active genre/decade toggles and all batch toggles to defaults, then
-    calls `DELETE /pipeline/planner-state`.
+  - **Nuke clears candidate selections** — `handleNuke` resets `selected`, `curate`, and
+    `aiExtras`; genres/decades/comm/autoUpdate are preserved. The debounced save persists the
+    blank selections to `planner_state.json` automatically.
+  - **"Clear all"** in the Planner build bar does a full reset: clears `selected`, `curate`,
+    active genre/decade toggles and all batch toggles to defaults, then calls
+    `DELETE /pipeline/planner-state`.
   Contains: `activeGenres, activeDecades, selected, curate, aiExtras, commEnabled, commListId,
   commPad, autoUpdate`. API: `GET/PUT/DELETE /api/pipeline/planner-state`.
 - **The Planner is deterministic:** selected candidates post as `CandidateSpec[]` to
@@ -345,9 +368,10 @@ The blow-by-blow of each step's components and props is the code's job — read
 **Plex guide shows channel icons, not text names.** When Plex receives a channel with any icon
 in the XMLTV feed, it renders only the icon and suppresses the text label — a Plex design
 decision, not a Programmarr bug. Tunarr injects a default icon for every channel, so without
-custom icons the guide is a wall of identical icons. `fetch_images.py` gives solo-title channels
-real TMDB logos; multi-title channels still show the Tunarr default until a logo strategy exists
-for them. Refreshing/restarting Plex does not change this.
+custom icons the guide is a wall of identical icons. `fetch_images.py` now gives **every**
+channel an icon: verified TMDB logos where trustworthy, generated name-stamped badges
+everywhere else — so the guide is readable even though Plex hides the text labels.
+Refreshing/restarting Plex does not change the icon-suppression behavior itself.
 
 ## Git Workflow
 

Dockerfile

@@ -25,7 +25,8 @@ COPY backend/ ./backend/
 
 # Pipeline scripts, prompt template, and static data catalogs
 COPY export.py create.py channel_engine.py channel_blocks.py generate_no_ai.py generate_from_collections.py \
-     fetch_images.py sync_plex.py PROMPT.md programming_blocks.json themed_keywords.json ./
+     fetch_images.py sync_plex.py icon_engine.py badge_renderer.py PROMPT.md programming_blocks.json themed_keywords.json ./
+COPY badge_assets/ ./badge_assets/
 
 # Built React app → served as static files by FastAPI
 COPY --from=frontend-build /build/dist ./backend/static/

backend/requirements.txt

@@ -2,3 +2,4 @@ fastapi>=0.110.0
 uvicorn[standard]>=0.27.0
 python-multipart>=0.0.9
 aiofiles>=23.2.1
+pillow>=10.0.0

backend/routers/channels_router.py

@@ -14,6 +14,8 @@
 
 import channel_engine  # noqa: E402
 import scheduler       # noqa: E402  (shared deploy_lock)
+import badge_renderer  # noqa: E402
+import icon_engine     # noqa: E402
 
 router = APIRouter()
 DATA_DIR = Path(os.environ.get("PROGRAMMARR_DATA", Path(__file__).parent.parent.parent))
@@ -142,6 +144,87 @@ def _do():
         raise HTTPException(409, str(e))
 
 
+@router.post("/channels/{number}/icon")
+async def channel_icon(number: int, body: dict):
+    """Set or pin a channel's Tunarr icon.
+
+    body: {"mode": "badge" | "tmdb" | "custom" | "clear", "url": "..."(custom only)}
+    badge/tmdb/custom write a pin into channels.json ("icon": {..., "pinned": true})
+    so automatic art passes (fetch_images.py) skip the channel; "clear" resets the
+    Tunarr icon to default and removes the pin (back to automatic).
+    """
+    mode = (body or {}).get("mode")
+    if mode not in ("badge", "tmdb", "custom", "clear"):
+        raise HTTPException(422, "mode must be one of: badge, tmdb, custom, clear")
+
+    data = load()
+    ch = next((c for c in data.get("channels", []) if c.get("number") == number), None)
+    if ch is None:
+        raise HTTPException(404, f"Channel {number} not in channels.json")
+
+    cfg = _load_config()
+    tunarr_url = cfg.get("tunarr_url", "").rstrip("/")
+    if not tunarr_url:
+        raise HTTPException(400, "Tunarr not configured")
+
+    name = (ch.get("name") or "").strip()
+
+    def _do():
+        summary = channel_engine.find_channel_by_number(tunarr_url, number)
+        if summary is None:
+            raise channel_engine.ChannelEngineError(
+                f"Channel #{number} not in Tunarr — deploy it first")
+        tch = icon_engine.get_full_channel(tunarr_url, summary["id"])
+        if tch is None:
+            raise channel_engine.ChannelEngineError("Could not read channel from Tunarr")
+
+        if mode == "clear":
+            if not icon_engine.clear_tunarr_channel_icon(tunarr_url, tch):
+                raise channel_engine.ChannelEngineError("Tunarr icon reset failed")
+            return ""
+
+        if mode == "custom":
+            url = (body.get("url") or "").strip()
+            if not url:
+                raise channel_engine.ChannelEngineError("url required for custom mode")
+        elif mode == "badge":
+            spec = icon_engine.load_spec_hints(
+                DATA_DIR / "planner_state.json").get(name.lower(), {})
+            png = badge_renderer.render_badge(
+                name, kind=spec.get("kind"), genre=icon_engine.spec_genre(spec))
+            url = icon_engine.upload_image_to_tunarr(
+                tunarr_url, png, f"programmarr-ch{number}-{os.urandom(4).hex()}.png")
+        else:  # tmdb
+            key = cfg.get("tmdb_api_key", "")
+            if not key:
+                raise channel_engine.ChannelEngineError(
+                    "tmdb_api_key not configured — use a badge or custom URL")
+            spec = icon_engine.load_spec_hints(
+                DATA_DIR / "planner_state.json").get(name.lower(), {})
+            url = icon_engine.resolve_tmdb_logo(
+                icon_engine.icon_attempts(ch, spec.get("kind")), key)
+            if not url:
+                raise channel_engine.ChannelEngineError(
+                    "No verified TMDB logo for this channel — use a badge or custom URL")
+
+        if not icon_engine.set_tunarr_channel_icon(tunarr_url, tch, url):
+            raise channel_engine.ChannelEngineError("Tunarr icon update failed")
+        return url
+
+    try:
+        async with scheduler.deploy_lock:
+            url = await asyncio.to_thread(_do)
+    except channel_engine.ChannelEngineError as e:
+        raise HTTPException(409, str(e))
+
+    if mode == "clear":
+        ch.pop("icon", None)
+    else:
+        ch["icon"] = {"mode": mode, "url": url, "pinned": True}
+    save(data)
+    return {"ok": True, "mode": mode, "url": url}
+
+
 @router.get("/library/titles")
 def library_titles():
     csv = DATA_DIR / "plex_library.csv"

backend/routers/config_router.py

@@ -15,6 +15,9 @@ class ConfigModel(BaseModel):
     tunarr_url: str = ""
     plex_url: str = ""
     plex_token: str = ""
+    # List of {name, url, token} Plex server entries. Replaces the legacy scalar
+    # plex_url/plex_token pair; both are kept for CLI backward compat.
+    plex_servers: list = []
     tmdb_api_key: str = ""
     auth_username: str = ""
     auth_password: str = ""
@@ -47,6 +50,11 @@ def get_config():
         config["plex_token"] = MASK
     if config.get("tmdb_api_key"):
         config["tmdb_api_key"] = MASK
+    if config.get("plex_servers"):
+        config["plex_servers"] = [
+            {**s, "token": MASK} if s.get("token") else s
+            for s in config["plex_servers"]
+        ]
     return config
 
 
@@ -57,11 +65,19 @@ def save_config(config: ConfigModel):
     for field in ("auth_password", "plex_token", "tmdb_api_key"):
         if data.get(field) == MASK:
             data[field] = existing.get(field, "")
-    # channel_order is a list, not a clearable string field: only overwrite it when the
-    # caller actually sends a non-empty list. An empty [] (e.g. an Onboarding save that
-    # skips the order step) must NOT wipe a previously-saved order — so handle it before
-    # the blank-field pruning below.
+    # Lists must bypass the falsy-prune below ([] is falsy but meaningful as "no change").
+    # channel_order: only overwrite when non-empty so an Onboarding save can't wipe it.
     order = data.pop("channel_order", None) or []
+    # plex_servers: restore masked tokens by matching on URL, then write if non-empty.
+    plex_servers = data.pop("plex_servers", None) or []
+    if plex_servers:
+        existing_by_url = {s.get("url", ""): s for s in existing.get("plex_servers", [])}
+        restored = []
+        for srv in plex_servers:
+            if srv.get("token") == MASK:
+                srv = {**srv, "token": existing_by_url.get(srv.get("url", ""), {}).get("token", "")}
+            restored.append(srv)
+        plex_servers = restored
     # Booleans must bypass the falsy-prune below (False is falsy → would be deleted).
     update_check = bool(data.pop("update_check_enabled", True))
     # Merge onto existing so keys the UI form doesn't manage are preserved — e.g.
@@ -76,6 +92,22 @@ def save_config(config: ConfigModel):
             merged.pop(k, None)
     if order:
         merged["channel_order"] = order
+    if plex_servers:
+        merged["plex_servers"] = plex_servers
+        # Keep legacy scalar fields in sync with the primary server for CLI compat.
+        merged["plex_url"]   = plex_servers[0].get("url", "")
+        merged["plex_token"] = plex_servers[0].get("token", "")
+    elif merged.get("plex_servers"):
+        # Legacy-format save (plex_url/plex_token fields) — sync plex_servers[0] to match
+        # so both representations stay consistent.
+        url   = merged.get("plex_url", "")
+        token = merged.get("plex_token", "")
+        primary = dict(merged["plex_servers"][0])
+        if url:
+            primary["url"] = url
+        if token:
+            primary["token"] = token
+        merged["plex_servers"] = [primary] + merged["plex_servers"][1:]
     merged["update_check_enabled"] = update_check
     # Preserve old channel_blocks key silently (don't crash; just ignore it).
     with open(_path(), "w") as f:
@@ -86,10 +118,11 @@ def save_config(config: ConfigModel):
 @router.get("/config/status")
 def config_status():
     config = load_config()
+    has_plex = bool(config.get("plex_servers")) or bool(
+        config.get("plex_url") and config.get("plex_token")
+    )
     return {
-        "configured": bool(
-            config.get("tunarr_url") and config.get("plex_url") and config.get("plex_token")
-        ),
+        "configured": bool(config.get("tunarr_url") and has_plex),
         "has_tmdb": bool(config.get("tmdb_api_key")),
         "has_auth": bool(config.get("auth_username") and config.get("auth_password")),
     }

backend/routers/pipeline_router.py

@@ -156,27 +156,54 @@ async def _locked_stream(script: str, args: list[str], tag: str) -> AsyncGenerat
 
 class ExportOptions(BaseModel):
     no_crossref: bool = False
-    movie_sections: Optional[list[str]] = None  # None = auto-detect; [] = skip type entirely
+    movie_sections: Optional[list[str]] = None   # primary Plex section keys; None = auto, [] = skip
     tv_sections: Optional[list[str]] = None
+    tunarr_movie_libs: Optional[list[str]] = None  # Tunarr library UUIDs for extra sources
+    tunarr_tv_libs: Optional[list[str]] = None
 
 
 @router.get("/pipeline/libraries")
 def list_libraries():
     cfg = _load_config()
-    plex_url = cfg.get("plex_url", "").rstrip("/")
+    plex_url   = cfg.get("plex_url", "").rstrip("/").lower()
     plex_token = cfg.get("plex_token", "")
+    tunarr_url = cfg.get("tunarr_url", "").rstrip("/")
     if not plex_url or not plex_token:
         raise HTTPException(400, "Plex not configured")
+
+    result = []
+
+    # ── Primary Plex sections (via Plex API, key prefixed "plex:") ─────────────
+    srv_name = (cfg.get("plex_servers") or [{}])[0].get("name", "Your Library")
     try:
         data = _plex_get(plex_url, plex_token, "/library/sections")
-        sections = data["MediaContainer"].get("Directory", [])
-    except Exception as e:
-        raise HTTPException(502, f"Could not reach Plex: {e}")
-    return [
-        {"key": s["key"], "title": s["title"], "type": s["type"]}
-        for s in sections
-        if s.get("type") in ("movie", "show")
-    ]
+        for s in data["MediaContainer"].get("Directory", []):
+            if s.get("type") not in ("movie", "show"):
+                continue
+            result.append({"key": f"plex:{s['key']}", "title": s["title"],
+                            "type": s["type"], "server": srv_name})
+    except Exception:
+        pass  # unreachable — UI shows error from libError fallback
+
+    # ── All other Tunarr-connected sources (key prefixed "tunarr:") ────────────
+    if tunarr_url:
+        for source in (channel_engine.api(tunarr_url, "GET", "/api/media-sources") or []):
+            # Skip the primary Plex — its sections are already listed above.
+            if source.get("type") == "plex" and source.get("uri", "").rstrip("/").lower() == plex_url:
+                continue
+            source_name = source.get("name", source.get("type", "Unknown"))
+            for lib in source.get("libraries", []):
+                if not lib.get("enabled"):
+                    continue
+                media_type = lib.get("mediaType", "")
+                lib_type = ("movie" if media_type in ("movie", "movies")
+                            else "show" if media_type == "shows" else None)
+                if not lib_type:
+                    continue
+                result.append({"key": f"tunarr:{lib['id']}", "title": lib.get("name", lib["id"]),
+                                "type": lib_type, "server": source_name})
+
+    return result
 
 
 @router.post("/pipeline/export")
@@ -188,6 +215,10 @@ async def run_export(opts: ExportOptions = ExportOptions()):
         args += ["--movie-sections", ",".join(opts.movie_sections)]
     if opts.tv_sections is not None:
         args += ["--tv-sections", ",".join(opts.tv_sections)]
+    if opts.tunarr_movie_libs is not None:
+        args += ["--tunarr-movie-libs", ",".join(opts.tunarr_movie_libs)]
+    if opts.tunarr_tv_libs is not None:
+        args += ["--tunarr-tv-libs", ",".join(opts.tunarr_tv_libs)]
     return _sse(_stream("export.py", args, "export"))