# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

SUB/WAVE is a personal internet radio station: one Icecast stream, all listeners hear the same broadcast, AI DJ picks tracks and reads scripts between them. See `README.md` for the architecture diagram and rationale.

## Common commands

Three operator entry points, all driving the same compose files + `state/` layout: the **standalone `subwave` CLI** (single binary, no clone — default for new installs), raw `docker compose` (no-CLI alternative), and `npm start` (contributor convenience inside a clone).

```bash
# --- dev (Mac smoke test, requires git clone) ---
docker compose -f docker-compose.dev.yml up -d     # Broadcast (icecast2+liquidsoap) + Controller (tsx watch)
cd web && npm install && npm run dev               # web UI on :7700, separate process

docker compose logs -f controller        # prod default
curl http://localhost:7700/api/health    # liveness via Caddy edge (prod)
```

The CLI resolves its install location via `SUBWAVE_HOME` (priority: `--home` → `SUBWAVE_HOME` env → `~/.config/subwave/config.json` → cwd if it has a `docker-compose.yml` → `~/subwave` if it exists → error). The cwd fallback is what makes `cd subwave-repo && npm start` work with zero config.

There is no `/skip` endpoint — track-end is the only natural transition. Liquidsoap controls pacing.

**Compose files live at the repo root**, not under `docker/`. One root `.env` is the entire boot config surface — everything else lives in `state/settings.json`, managed by the wizard + admin UI.

**Dev hot-reloads; prod needs a rebuild.** In dev compose, `controller/src/`, `controller/scripts/`, and `radio.liq` are bind-mounted and the controller runs `tsx watch`, so edits restart in-place. In **prod** images `COPY` source at build time, so `restart` reruns the *same baked-in code* — changes need `up -d --build`.

```bash
docker compose -f docker-compose.dev.yml restart controller  # rarely needed — tsx watch handles src/** edits
docker compose -f docker-compose.dev.yml restart broadcast   # after radio.liq edits in DEV (bind-mounted)
docker compose up -d --build controller     # after controller/src/** in PROD
docker compose up -d --build broadcast      # after radio.liq / icecast.xml.template / Dockerfile.broadcast in PROD
```

`web` runs as a Next.js dev server (`npm run dev`) and hot-reloads in dev; prod builds the web image and needs a rebuild like the others.

**Lint is the merge gate; tests are not.** `controller/` and `web/` each expose `npm run lint` (`eslint . && tsc --noEmit`), and `mcp-subwave/` exposes `npm run lint` (`tsc --noEmit`); CI runs all three on every PR (`.github/workflows/lint.yml`, plus a theme-token mirror drift check on `controller`) and those jobs are what block a merge.

`controller/` also has a test suite — `npm test` (`scripts/run-tests.ts`) auto-discovers every `scripts/*.test.ts` and runs each as its own tsx subprocess, so a test that fails by `process.exit(1)` and one that fails by a thrown `assert` are caught the same way. **Dropping a `*.test.ts` file into `controller/scripts/` is the whole registration step** — no package.json edit. `npm test -- <substring>` filters to matching files. `web/` and `mcp-subwave/` have no tests. Since CI doesn't run any of this, run `npm test` yourself before pushing controller changes.

## Architecture

Four cooperating processes with **file-based IPC** through a shared `state/` dir (mounted at `/var/sub-wave` in containers). This is the load-bearing fact about how the system works — there is no socket or RPC channel between controller and Liquidsoap.

- **Controller → Liquidsoap**:
  - `next.txt` — controller writes one annotated track URI; Liquidsoap polls every 1.0s, drains, and `request.queue.push`es it.
  - `say.txt` — WAV path; polled every 0.5s, fed through `voice_queue`, **heavy-ducked** (`smooth_add p=0.22`). Station IDs, hourly time, weather, request intros.
  - `intro.txt` — between-track auto-DJ links; polled every 0.5s, fed through `intro_queue`, **light-ducked** (`smooth_add p=0.30`) so the song that just started stays audible under the voice.
  - `auto.m3u` — fallback playlist the controller rewrites every `AUTO_QUEUE_REFRESH_MINUTES` (default 60) for the current mood; Liquidsoap reloads on file change (`reload_mode="watch"`).
  - `liquidsoap_*.txt` (jingle_ratio, crossfade, opus_enabled, opus_bitrate, flac_enabled, aac_enabled, aac_bitrate, …) — tiny files written by `settings.update()`, read once at `radio.liq` startup. Changes need a Liquidsoap restart (controller triggers via `/restart-mixer` → telnet).
- **Liquidsoap → Controller / UI**:
  - `now-playing.json` — written from `music_meta.on_metadata(on_meta)`. The hook must stay on `music_meta`, the **pre-cross** handle captured before `music` is wrapped in `cross(...)`. Hooking the post-cross source fires twice per transition (because `dj_transition` passes `initial_metadata=` into both `fade.in` and `fade.out`), freezing the UI one song behind. `on_metadata` is used instead of `on_track` because `on_track` gets swallowed by source switches (request queue → auto playlist).
  - `jingle-playing.json` — `{filename, startedAt}` written when a jingle starts feeding the jingle rotate (issue #997). Jingles play outside the controller's voice serialiser (and `music_meta` is captured above the rotate, so the incoming track's metadata fires while the stinger is still in the cross buffer); `airVoice` (`broadcast/queue.ts`) reads this and holds every spoken segment until the stinger's window (start + clip length + crossfade) has passed. `jingleRatio: 0` disables jingles entirely (radio.liq skips the rotate; needs mixer restart like every ratio change).
  - `bed-playing.json` — `{filename, startedAt}` written when a track annotated `subwave_kind="bed"` starts (beds — an instrumental the DJ talks over BETWEEN songs, so a long link isn't talked over the song it's introducing). A bed is pushed into `dj_queue` like any other request but is NOT a song: `on_meta` branches on the annotation BEFORE its `title != ""` gate, so a bed never reaches `now-playing.json` and never pushes an ICY title. That silence is also why the marker exists — the controller learns "the bed is on air, air the link now" only from this file (`queue.onBedStarted`, read on the same 1.5s now-playing tick). Same shape and rationale as `jingle-playing.json`.
- **Controller → Web UI**: HTTP. `useStationFeed` (`web/hooks/useStationFeed.js`) polls `/now-playing` + `/state` every 5s.
- **Controller state**: `session.json` — the live DJ session (chat-history JSON, see `broadcast/session.js`); archived to `state/sessions/<id>.json` on roll. Controller-internal, not read by Liquidsoap.
- **Browsers → Icecast**: direct `<audio>` on `…/stream.opus` (Blink) or `…/stream.mp3` (everything else). `usePlayer` (`web/hooks/usePlayer.ts`) probes `canPlayType('audio/ogg; codecs=opus')` once and upgrades to Opus only on a definitive `'probably'` **and** non-iOS, non-Firefox (both choke on Icecast's chained-Ogg page boundary at a crossfade — issues #168/#215). Opus is **off by default** (see Liquidsoap step 9), so a **fourth** gate decides whether the probe runs at all: the station's own `stream.opusEnabled`, published on `/now-playing` and threaded in from `useStationFeed` — only an explicit `true` upgrades, so an un-polled feed or an older controller that omits the key stays on MP3 rather than pointing Chrome at a 404 (issue #1300). That flag is the SETTING, not a live mount probe (it needs a mixer restart), so `onError` still pins MP3 permanently for the session on a genuine Opus failure. The upgrade never retargets a playing element — it lands on the next `tune()`/`reconnect()`, so tapping play before the first poll rides MP3 for that session. MP3 is the universal floor (Sonos, hardware radios, car receivers, pre-iOS-17 Safari). `useMediaSession` wires lock-screen / headphone / CarPlay controls, artwork from the controller's `/cover/:id` proxy.

### Controller (`controller/src/`, ESM Node.js)

Express + ESM Node, grouped by domain: `server.js`, `config.js`, `settings.js`, `context.js` at the root; everything else under `routes/`, `middleware/`, `music/`, `broadcast/`, `audio/`, `llm/`, `skills/`. Module-by-module detail is in [`controller/CLAUDE.md`](controller/CLAUDE.md).

### Liquidsoap (`liquidsoap/radio.liq`)

The mixer: request queue → auto playlist → cross → two `smooth_add` ducking layers → jingle rotate → emergency fallback → limiter → parallel Icecast mounts. Full pipeline order and the rationale behind each stage are in [`liquidsoap/CLAUDE.md`](liquidsoap/CLAUDE.md); the rules you must not break either way are under **Working on this codebase** below.

### Web UI (`web/`)

Next.js 15 App Router + Tailwind; the player is a headless core plus swappable **skins**. Routes, the skin contract, and the same-origin API/stream defaults are in [`web/CLAUDE.md`](web/CLAUDE.md).

### Native app (`app/`)

A separate **Expo SDK 56 / React Native** project (own `package.json`, `node_modules`, `eas.json`) — the native iOS + Android player. Architecture-critical and easy to break; see [`app/CLAUDE.md`](app/CLAUDE.md) and [`app/docs/TESTING.md`](app/docs/TESTING.md) before touching native config.

### Docker layout

Three compose files at the repo root, three deployment shapes:

- **`docker-compose.yml`** — prod single-host with bundled Caddy. **The default.** `broadcast` (icecast2+liquidsoap), `controller`, `web`, `caddy`. **Only Caddy binds a host port** (`${CADDY_PORT:-7700}:80`); the rest are internal. State path `${STATE_DIR:-./state}`. Cloudflare terminates TLS (`auto_https off`). `controller` is forced `NODE_ENV=production` → admin gate mandatory. Configs baked into images, not bind-mounted.
- **`docker-compose.byo.yml`** — prod for hosts with their own Traefik/nginx/Caddy. Same as default minus bundled Caddy; `web`/`controller`/`broadcast` bind host ports (`${WEB_PORT:-7700}`, `${CONTROLLER_PORT:-7701}`, `${ICECAST_PORT:-7702}`). The web image is baked for same-origin `/api` + `/stream.mp3`, so the operator's proxy must replicate `docker/Caddyfile`'s route table on one hostname; split hostnames need a web rebuild with `NEXT_PUBLIC_*`.
- **`docker-compose.dev.yml`** — Mac local smoke-test. Broadcast + Controller only (web runs separately via `npm run dev`). State `./state`. Bind-mounts `radio.liq`, `sounds/`, `controller/src` so dev edits need no rebuild.

**Optional `tts-heavy` profile** in all three composes — a `tts-heavy` sidecar (`profiles: ["tts-heavy"]`, does NOT start unless `docker compose --profile tts-heavy up -d`) hosting Chatterbox + PocketTTS over HTTP on the shared `/var/sub-wave` volume. Off by default keeps the install lean. It is **TTS-only** — acoustic analysis was moved out into the standalone `analyzer` service (see below).

**Default-on `analyzer` service** — the acoustic-analysis sidecar (`subwave-analyzer` image, `docker/Dockerfile.analyzer` + `docker/analyzer/server.py`). **Starts by default** in all three composes (no profile gate — like controller/web); only `tts-heavy` (voices) stays opt-in. It's the librosa (+ optional CLAP + Demucs) analyzer **split out of tts-heavy**: bpm/key/intro/loudness always, plus **outro analysis** on every tier (last ~20s of each *complete* file → `tracks.outro_json`: fade-vs-cold ending, tail LUFS/tempo/bars; a byte-capped download skips it — the completeness flag rides the analyze request). The outro is what makes transitions ending-aware: `queue.applyMixTransition` stamps each DJ-mode track's OWN exit canvas from its measured ending via `mix.endingCrossSecondsFor` (a fade rides out 8–12s, a cold end cuts ~4s; washout/loop overwrite it) — the per-track answer to #749, which blocks the pair-sized `crossSecondsFor` from ever being applied — and a measured fade vetoes the `chop` effect (`effectAllowedFor`). **Vocal-aware transitions** (heavy tier, vocal detection on): the outro window gets its own Demucs pass → `outro.vocalRanges` (absolute ms, `[]` = instrumental tail; backfill widened via the `tail_vocal` capability flag so stale analyzer images never churn; lyric-decided tracks skip the tail Demucs pass like the head one — their tail ranges are clipped from the synced-lyric timing instead, `lyric-vocal.clipRangesToTail`) — a sung fade pulls its exit canvas to the 8s floor (`Analysis.vocalTail`), a sung ending vetoes `chop`, and a *measured* first-vocal entry under 2.5s drops the DJ link outright (`enforceIntroBudget` — see `docs/stem-transitions-research.md`); "sounds-like" embeddings (multi-window CLAP — start/mid/late windows averaged, so quiet intros don't misrepresent the track), vocal ranges, and the CLAP **text tower** (`POST /embed-text`, capability-flagged in `/health`) are the heavy tier. Text and audio vectors share one 512-d space, which powers the picker's `searchBySound` tool (describe a sound in words → audio KNN) and zero-shot audio moods (`music/audio-moods.ts`: mood-vocab prompts scored against stored audio vectors at the end of every analysis pass → `tracks.audio_moods`, blended into `songsByMood`/`trackMoods`; vocab/prompt changes re-score via `mood_vocab_hash`). **Two published flavours**: `subwave-analyzer` — **LEAN, multi-arch** (~1.1GB — librosa + ffmpeg, no torch — the default everyone pulls), `WITH_CLAP=0 WITH_DEMUCS=0`; and `subwave-analyzer-heavy` — CLAP+Demucs baked (~1.9GB, amd64-only), `WITH_CLAP=1 WITH_DEMUCS=1`. **Opt-in switch is `ANALYZER_HEAVY=1` in `.env`** — the compose `analyzer` service resolves `image: …/subwave-analyzer${ANALYZER_HEAVY:+-heavy}:…` and its `build.args` key off the same var (so pull and local build agree). No `platform` pin (lean is native arm64; heavy on arm64 needs `DOCKER_DEFAULT_PLATFORM=linux/amd64`). Uses the **same `analyze_worker.py`** as the offline CLI (single source of truth). The controller resolves its analysis backend from `config.analyzer.urls` — **`ANALYZE_URL`** (`music/analyzer.ts` probes `/health`), then a local venv (`ANALYZE_PYTHON`). tts-heavy is TTS-only now and is **not** an analysis backend (no `TTS_HEAVY_URL` fallback). **AIO (`Dockerfile.aio`) bundles the analyzer in-process** (local venv, `ANALYZE_PYTHON` + `HF_HOME` under the state dir) rather than a service; `subwave-aio` is lean, `subwave-aio-heavy` bakes CLAP+Demucs. The analyze worker lives in the analyzer image(s) and the AIO.

**Image-first pulls, source-build fallback.** Every service references `ghcr.io/perminder-klair/subwave-{caddy,broadcast,controller,web,tts-heavy,analyzer}:${SUBWAVE_VERSION:-latest}` alongside a `build:` block. `up -d` pulls; `build && up -d` rebuilds. Publishing via `.github/workflows/publish-images.yml` on tag pushes (`v*`).

**Auto-generated Icecast secrets.** The broadcast entrypoint (`docker/broadcast-entrypoint.sh`) resolves `ICECAST_*_PASSWORD`: env override → persisted `state/icecast-secrets.env` → freshly generated hex, then writes back and exports into liquidsoap's env. icecast + liquidsoap share one container, so there's no cross-container handshake. To rotate: delete `state/icecast-secrets.env` and restart `broadcast`.

**Private station mode (#478).** `settings.privacy` holds two independent locks over ONE shared `password`: `privatePlayer` (the web player pages ask for it before rendering — shell-level in `PlayerShell`, rides `/state`, applies live) and `listenerAuth` (Icecast listener auth on every stream mount). Either lock being on requires a password — `settings.update()` throws otherwise, because a lock with no password behind it either fails every listener closed or renders a prompt nobody can satisfy. Listener auth uses Icecast **URL auth**, not htpasswd: `settings.update()` writes `state/icecast_listener_auth.txt`, and the broadcast entrypoint (+ AIO supervisor's `render_icecast()`, re-run on every pair relaunch) renders per-mount `<authentication type="url">` blocks pointing at `POST /listener-auth`. External clients send basic auth (`user:pass@`), the web player rides `?auth=` on the mount query (Icecast forwards the query string in the auth callback; browsers can't basic-auth an `<audio>` element). **Two endpoints, opposite failure modes — do not merge them**: `POST /listener-auth` (Icecast) fails OPEN when `listenerAuth` is off, covering the window where icecast.xml still carries the auth blocks but the setting is already off; `POST /station-auth` (the web gate, rate-limited) fails CLOSED, because `privatePlayer` can be on while `listenerAuth` is off and reusing the Icecast decision there would accept any password. Both live in `util/listener-auth.ts`, pinned by `scripts/listener-auth.test.ts`. Toggling `listenerAuth` needs a mixer restart (rides `requiresRestart`); password changes apply live. `/listen.pls`/`/listen.m3u` 403 while auth is on. Settings UI lives in the **Station** section. See `docs/private-station.md`.

**Public persona disclosure.** `settings.privacy.publishPersonaSouls` (default `false`) sits in the same block but is **a disclosure toggle, not a lock** — it takes no part in the password invariant above, needs no restart, and applies live. It governs the ROSTER-WIDE public reads: `GET /schedule`'s persona index and `GET /personas`. Those always publish `id`/`name`/`tagline`/`avatar` (and each show's `guestPersonaIds`, resolved against the live roster so a deleted guest vanishes); a persona's `soul` rides only when the toggle is on, because a soul is the persona's **system prompt**, not a written bio, and these reads hand over every persona at once. When off the key is **absent, not empty**, so a client can tell "not published" from "published but blank" (`/personas` also reports `soulsPublished`). `GET /dj` is deliberately **out of scope** — it has always published the ON-AIR persona's soul, one at a time, and gating it would break existing public clients. The shape + rule live only in `util/public-persona.ts` (never inline in the route), pinned by `scripts/public-persona.test.ts`. Never widen the shape to TTS config, skills, or the behaviour dials.

**Single config surface.** Three required root `.env` vars boot the stack: `ADMIN_USER`, `ADMIN_PASS`, `SITE_URL`. Everything else is collected by two converging wizards — `npm run setup` (terminal, `cli/src/commands/setup.ts`) and `/onboarding` (browser, `web/components/onboarding/*` → `controller/src/routes/onboarding.ts`). Both persist to the same layer: Navidrome creds + setup timestamp → `state/setup-config.json`; cloud LLM/TTS keys → `state/secrets.env` (mode 0600, sourced on boot via `setup/secrets.ts`); everything else → `settings.update()` → `state/settings.json`. **Env always wins**; wizards only fill gaps. `setup/firstRun.ts` decides `needsSetup` (no Navidrome creds from env or config); `/state` exposes it so the player + AdminShell redirect a fresh operator to `/onboarding`.

The shared `/var/sub-wave` mount in **both** Broadcast and Controller is what makes the file-based IPC work — they must always map to the same host path.

### Jingles

`state/jingles.m3u` is empty by default. Run `scripts/generate-jingles.sh` after the stack is up — it `exec`s into the controller, pipes text through the configured TTS engine, writes WAVs into `${STATE_DIR}/jingles/`, rewrites the M3U. The jingles `playlist(...)` uses `reload_mode="watch"`, so new renders need no restart.

## Working on this codebase

- **Queue/playback path**: `queue.drainToLiquidsoap()` is the single writer of `next.txt` (+ request-intro `say.txt`); `queue.announce()` is the single writer of scheduled `say.txt`/`intro.txt`. Request-intro WAVs are written ~250ms before the track URI so the 0.5s voice poll picks them up first. Poll intervals (1.0s queue, 0.5s voice) are the upper bound on perceived latency. **Pair-aware drains** (`transitions.pairDrain`, default on, **DJ-mode personas only** — `queue.pairDrainActive()`, `broadcast/drain-policy.ts`): picks are HELD unsent until their successor is queued behind them (the deadline routine in the watcher tick picks it ~120s before the on-air track's effective end, `min(duration, cue_out)`, with a failure-retry cooldown of `DEADLINE_PICK_COOLDOWN_SEC`; hard fallback ~45s drains with intrinsic stamps), which is what lets `applyPairStamps` finally apply the pair-sized `crossSecondsFor` (#749) and lets stem blends insert. A successor of ANY kind releases the hold (a request IS the successor arriving — FIFO is never inverted); unknown clock (boot/recover/untracked auto) or a non-DJ persona drains eagerly, byte-for-byte the old behaviour. **Operator skips commit first (#1300 bug 6)**: because the hold makes an empty `dj_queue` the NORMAL mid-track state, `POST /dj/skip` runs `queue.commitBeforeSkip()` — force-drain plus a bounded wait for the `dj_queue_status` telnet probe to report a RESOLVED request (a sent-but-still-fetching request loses the fallback race just the same) — before the telnet `skip`; on timeout the skip proceeds anyway and the response/booth log say the pick wasn't confirmed, so `auto.m3u` filling the slot is reported, never silent. Policy in `broadcast/skip-policy.ts`, pinned by `scripts/skip-policy.test.ts`; an empty queue keeps the bare-skip path byte-for-byte. **Stem blends** (`transitions.stemBlends`, opt-in; `broadcast/stem-blend.ts` + worker `render_transition`): at a pair drain, a cache-hit-only render mixes the outgoing tail stems × incoming head stems (`state/stems/`, written during analysis when `audio.stemCache` is on) into a clip that airs between them — outgoing cues out at the blend start, the clip carries the INCOMING track's identity (now-playing flips at blend start; `lastSeenKey` dedups the real fire; `subwave_clip="1"` keeps telnet rid helpers honest), incoming cues in past its pre-mixed head. Any miss → plain pair-aware crossfade. **A clip carries no `liq_amplify`** (`subsonic.getClipUri`), so its LEVEL is whatever the render baked in: both sides are gained by `music/loudness.ts` `resolveGainDb` — the same figure the drain stamps on a real track — never by re-deriving from the analyzer's leading-window LUFS, which ignores ReplayGain tags (the default source), the boost cap and the peak headroom cap and is what made rendered seams sit at a different level than the tracks around them (#1240). The render's peak guard ducks the BORROWED loop to fit the ceiling rather than scaling the whole clip, because scaling the clip is scaling the incoming track's own content back out of match. Pinned by `scripts/stem-blend-level.test.ts`. Clips sweep after 1h (clips still queued for an unaired seam are exempt — `queue.pendingClipPaths()`); the stem cache is byte-budget LRU (`audio.stemCacheGb`, 1–1000 GB, edited in Settings → Transitions), and tail stems carry a `tail-meta.json` alignment sidecar (exact decoded tail offset — the render treats stems without it as a miss). **The stem cache backfills** like the CLAP/vocal scopes: `tracks.stems_at` (schema v17) stamps every stem ATTEMPT, `db.needsStemsIds()` is the fourth widening in `runAnalysisPass`, so turning the cache on for an already-analysed library fills in over successive resumable passes instead of needing a `--re-analyze` (which wipes every vector and can't resume). The stamp records the attempt, **not disk presence** — the LRU sweep evicts dirs by design, so a presence-based scope would re-separate every evicted track forever on any library bigger than the budget; a miss at seam time just falls back to a plain crossfade. **The budget gates every stem write, not just the widening (#1257)**: `runAnalysisPass` takes ONE `headroomTracks()` figure per pass and spends it per NET-NEW dir via the pure `stemCache.stemWriteDecision` (a rewrite of an existing dir is free) — ride-along stems used to bypass the cap entirely, which is how a vocal backfill grew a 500 GB budget to 674 GB. Headroom is sized off the cache's own measured average once it holds ≥50 dirs (`estimateTrackBytes`; the fixed 25 MB guess ran ~2x pessimistic in the field), and `sweep()` reports `failedDirs`/`overBudgetBytes` so a sweep that can't evict (permissions on a relocated stems mount) is loud in the booth log, the analyze event log and the doctor instead of returning `{removed: 0}` and reading as "nothing to do". The admin queue badges seams arriving via a rendered blend (`stemSeam` on `queue.snapshot()` items — stamped at pair drain, cleared on cancel, definitive rather than predictive). Pinned by `scripts/stem-backfill.test.ts` + `scripts/stem-cache-sweep.test.ts`.
- **`radio.liq` `on_metadata`**: keep it on `music_meta`, the pre-cross handle (post-cross fires twice; `on_track` gets swallowed by source switches). See Architecture.
- **`radio.liq` atomic marker writes (#1240)**: every `file.write(atomic=true)` — `now-playing.json`, `jingle-playing.json`, `bed-playing.json` — MUST carry a `temp_dir=` on the state fs (`ensure_tmp_dir` at the top of the file, one dir per writer). Without it Liquidsoap picks a temp dir under `$TMPDIR`, which on Docker is the container overlay while the state dir is a bind mount: the rename is cross-device, the stdlib logs `Atomic rename failed` and silently degrades to a NON-atomic copy — i.e. the half-written-JSON race `atomic=true` exists to prevent was never actually prevented on any Docker install. One temp dir **per writer**, because the stdlib always names the temp file `atomic.write` inside the dir it is given and the jingle write is `synchronous=false`. `ensure_tmp_dir` probe-writes and returns `null` on failure (`file.mkdir` does NOT raise), so an unwritable state mount degrades to the old behaviour instead of raising inside `on_metadata`.
- **`radio.liq` emergency dead-air fallback position (#1300 bug 7)**: `fallback(id="music_safety", track_sensitive=false, [music, emergency])` MUST stay **above every `add` in the music path** — both the `smooth_add` ducking layers AND the studio-bed mix. It binds to `music`, immediately BEFORE the `bed_enabled` if/else. Anything below an `add` can never fire, because `add` is ready if ANY input is: the stdlib builds smooth_add as `add(normalize=false, [normal, fallback(track_sensitive=false, [special, blank()])])`, that inner fallback falls through to `blank()` so it is ALWAYS ready, and the bed leg is `mksafe(single(bed))` — `mksafe` makes it INFALLIBLE. Either way the bus reports ready with the music chain starved and a fallback under it selects index 0 forever. The guard lived at the BOTTOM of the chain for its whole life and was dead code the entire time; nobody noticed because the failure it guards against also needs the jingle rotate silenced, and the rotate had been masking every starve (that's bug 7 itself). Gating jingles off without moving this turns "stingers forever" into digital silence forever — measured -91.0 dB at the output, versus -3.0 dB with the fallback in its correct position. The bed trap is the same bug re-armed by a **documented** one-line source edit (`bed_enabled = true`, "flip back to `true` to restore it"): measured on the full chain with the bed on, the guard bound to `music_bus` never selected `emergency` at all and the output was the bed alone at -57.1 dB, versus -9.0 dB (the loop, at its own level) with the guard bound to `music`. **Do not leave a second one at the bottom** "for safety": a fallback that looks like a dead-air guard but structurally cannot fire is what caused this. Position also matters upward — it stays BELOW `music_meta` and the jingle rotate so now-playing metadata and jingle counting are untouched. A harness that tests this guard MUST build the duck layers (and, for the bed claim, the bed `add`); one that runs `output.dummy` on the bare rotate proves nothing (that is exactly how the false claim got shipped).
- **`radio.liq` emergency fade-in — not a debounce (#1300 bug 7)**: the guard's emergency branch ramps up over `EMERGENCY_FADE_SEC` (1.0s). `track_sensitive=false` makes it switch the instant `music` reports not-ready, and now that it can actually fire it also fires on brief real gaps — cold boot before `auto.m3u` resolves, and track seams where `dj_queue` and `auto_playlist` are momentarily both unready (auto entries are whole-file `subhttp:` downloads, so a slow Navidrome widens the window). **Never "fix" that by delaying the switch**: a dead-air guard that waits before firing is a guard that doesn't fire, which is the exact bug class above. Fire immediately, ramp the LEVEL — a sub-second stab is inaudible, a real starve is at full level in ~1s, timing untouched. It takes **two** fades and both must stay: `switch` applies no transition to its FIRST selection (measured — `Switch to emergency.` at boot vs `…with transition.` after), and boot IS that first selection, so `emergency` carries its own one-shot `fade.in` (default `track_sensitive=false` memoises the ramp to the source's first frame ever — right for boot, useless later, since a looping single never reaches a fresh track boundary); the `transitions=` entry then ramps every later switch. The music branch keeps the stdlib identity transition — coming BACK must be instant, or a recovered station fades up over its own first second of music. `fade.in` returns extra methods, so both sites cast `(… : source)` to unify with the plain `music` child. Measured (100ms RMS): boot -38.5 → -9.0 dB over 1.0s, mid-run -32.6 → -9.0 dB over 1.0s, recovery a single-window step with no ramp, unchanged after 43 switches in one process.
- **Crossfade**: keep fade duration equal to the cross buffer (`d = crossfade_duration()`, `fade.out(d)` / `fade.in(d)`). Shorter fades inside a fixed buffer let the outgoing track play full while the incoming ramps, summing to +6 dB (audible doubling). Vary the buffer length instead.
- **Spoken clocks on pick-attached links (#864 → #1282 → #1314)**: a link is written when the pick is MADE but airs when the pick STARTS, so any time it speaks is a **forecast** — `linkAirDate(showAt)`, i.e. now plus whatever is left of the on-air track. The forecast holds only if the pick reaches Liquidsoap before that track ends; when the round outruns it, `dj_queue` is empty at the seam, `auto.m3u` fills the slot and the pick airs at the END of that filler, with the link still naming the moment the filler STARTED (#1314's ~4-minute undershoot). #1282's removal of a fixed +120s show-attribution overshoot is what exposed it — the two errors had been cancelling. **Two guards, both in `broadcast/queue/pure.ts`, and they must stay paired**: `linkClockAt(showAt, now)` refuses to hand the generator a clock at all below `LINK_CLOCK_MIN_RUNWAY_SEC` (= `DRAIN_DEADLINE_SEC` — `maybeDeadlinePick`'s empty-queue backstop always fires inside that window on any station, whatever its track lengths; measured over 788 rounds, 27.7% ran past 45s of runway but only 0.3% past 120s; accepted flip side: a sub-2-minute-track library never clears the floor even at track start, so its links never speak the clock at all), and `linkClockDrifted` drops the line at `airIntro` when the real seam lands more than `LINK_CLOCK_DRIFT_TOLERANCE_SEC` (90s) from the stamped `item.linkClockAt`. Runway is read from the LIVE clock at generation, never from the `leadSec` `showAt` was built with — on the pool path the pick call has already spent part of it. The stamp records the clock being **offered**, not used: unlike `shouldDropStaleLink`'s `mentionsTrack`, a clock has no reliable string handle ("18:38" / "twenty to seven" / "eighteen thirty-eight"), so don't narrow it with a regex. Note that even a perfect forecast is heard `stream.bufferSeconds` late — see the next bullet.
- **Listener buffer / live-edge offset (#1114)**: Icecast bursts `settings.stream.bufferSeconds` (default 22s) of already-broadcast audio on connect, so **every listener sits that far behind the live edge for their whole connection**. Two consequences that must stay in sync. (1) `<burst-size>` is a BYTE count, so it's computed **per mount** — `bufferSeconds x that mount's bitrate x 125`, rendered as one `<mount>` block per stream mount by `docker/broadcast-entrypoint.sh` (and the AIO's `render_icecast()`, kept in lockstep), reading `liquidsoap_stream_buffer_seconds.txt` + the per-encoder bitrate files from the state dir; FLAC is VBR so its depth uses a ~900kbps estimate. Never collapse this back to one global figure: the same 528 KB that is 22s of 192k MP3 is ~43s of 96k Opus and ~6s of FLAC (the post-#1114 "Now Spinning runs behind" report). Each mount's `<queue-size>` is 4x its burst (floored at 2 MB) and must stay comfortably above it or clients get evicted the moment they fall behind their own primed buffer. (2) Every timestamp the controller publishes is stamped at the **live edge** (`radio.liq`'s pre-cross `on_metadata`), so listener-facing players shift into listener-time — `useStationFeed` holds the track switch until the audio is actually audible and `trackStartedAt` carries the offset (it can briefly sit in the future; `useElapsed` clamps at 0). The offset the web player applies is the advertised `stream.bufferSeconds` from `/now-playing`, full stop. It used to prefer a per-tab **measurement** (`usePlayer.getListenerLagMs`, `buffered.end − currentTime`) because a byte-sized burst meant a different depth per mount; (1) above fixed that at the source, and the measurement was never the offset anyway. **`buffered.end − currentTime` does NOT measure the listener's distance from the live edge** — it reports only the window the browser has DEMUXED, while Chrome holds the connect burst in an internal cache `buffered` never exposes. Measured directly (tone marker vs `now-playing.json`'s live-edge stamp): true offset **22.5s**, `buffered.end − currentTime` **2.25s**, advertised **22s** — so preferring the measurement flipped every title ~20s early. Don't reintroduce it, and don't use `buffered` to judge cushion health. Operator surfaces (admin dash, MCP) intentionally keep live edge. Changing the depth needs a broadcast **container** bounce, not just a mixer restart — though the telnet `restart` achieves it anyway, since icecast and liquidsoap share a container the entrypoint `wait -n`s on.
- **Real listener IPs / trusted proxies**: Icecast's only peer is the edge, so admin → Listeners shows the proxy's container IP unless `<x-forwarded-for>` names that proxy. Rendered into the template's `<!--@TRUSTED_PROXIES@-->` marker by `docker/broadcast-entrypoint.sh` and the AIO's `render_icecast()` — the **third** thing those two must keep in lockstep, alongside the per-mount burst/queue and the listener-auth blocks. Two icecast-KH facts pin the design: it matches an **EXACT IP** (a CIDR is accepted and then silently never matches, so no subnet shorthand), and it reads the **left-most** entry of the chain (the real client, even though Caddy appends its own peer). Source order is `ICECAST_TRUSTED_PROXY_IPS` (explicit, wins) → DNS for `ICECAST_TRUSTED_PROXY_HOSTS` (default `caddy`). The DNS path is **deliberately best-effort and misses the first cold boot** — caddy `depends_on` broadcast being healthy, which needs icecast already serving, so the name cannot resolve at render time (measured: ~6s unresolved); every later restart picks it up. A miss degrades to the old behaviour (proxy IP shown), never to a wrong IP, so nothing downstream handles a half-applied state. The AIO trusts loopback outright (Caddy is in-container). Malformed entries are dropped rather than interpolated — invalid XML here would turn a cosmetic setting into a station that won't boot. Counting still must NOT key on IP (`groupConnections`): the header may be untrusted, and one NAT is many listeners.
- **State bootstrap is never fatal (#1300 bug 10)**: `bootstrap_state_dirs` in `docker/broadcast-entrypoint.sh` and the AIO's `supervisor.sh` (same function, same list, same messages — the **fourth** thing those two keep in lockstep) creates the shared state dirs and opens them to 777, because the controller and analyzer write there as other uids. Every step is guarded and warns instead of aborting. The entrypoint runs `set -eu`, so the old bulk `mkdir -p a b c` / `chmod 777 a b c` made **every state path load-bearing**: one on a mount that refuses the change — a read-only bind, an NFS export, the exFAT/NTFS disk people move the stem cache to — exited the entrypoint BEFORE icecast started, and compose reported only `dependency failed to start: container sub-wave-broadcast is unhealthy`, naming neither path nor cause (measured: `exit=1`, `health=unhealthy`, one `chmod:` line). A station that refuses to boot over a permission convenience is strictly worse than one on a degraded mount — icecast still serves and the dead-air guard still airs the emergency loop, but an exited container airs nothing. The warning keys on **writability, not on chmod's exit status**: a mount already world-writable that merely refuses chmod is a WORKING config, and a line printed on every boot of a healthy station is one operators learn to skip. `stems` + `transitions` are in the list because a bind mount at `<state>/stems` is the only way to relocate the stem cache (`stemsRoot()` has no setting behind it) and a fresh one lands root-owned 755, which the analyzer (uid 10001) cannot write — measured `ANALYZER_WRITE_DENIED` before, `_OK` after. Pinned by `scripts/state-bootstrap.test.ts`, which drives BOTH scripts through one table.
- **Listener-count gates (#1256)**: **three** gates fail **OPEN** on an unknown count, and all three read a gated reading, **never the raw `getListenerCount()`** — `listeners.djCallsAllowed()` (all autonomous DJ/LLM work, plus `POST /request`) and the idle-pause monitor (`broadcast/stream-idle.ts`) via `listeners.gatedListenerCount()`, and the analysis quiet gate (`music/analyze-quiet-pure.ts`, whose fail-open runs the OPPOSITE way — an unknown count lets the DSP pass proceed) via `probeListenerCount()`, which returns the gated count from the tagger child's own module state. A failed Icecast status poll is not an observation: the pure `gatedCount` holds the last count actually read from Icecast until failures reach `STALE_STATUS_LIMIT` (4), the same hysteresis the cached `StreamStatus` has carried since #461. On the raw count a **single** `fetchWithTimeout` abort read as "unknown" and the gates opened at once — and because `stream-idle.ts` deliberately forces its own poll every 5s while paused (~120 per 10-minute pause, not the 15s monitor cadence a short manual probe would sample), a sub-1% poll failure rate released nearly every pause ~28s after it engaged: the power save was inactive ~95% of the time it should have been active, and each release also reopened the LLM token gate. Fail-open itself is unchanged — a *sustained* outage still reads null, still resumes, still keeps the DJ on air. Two things keep the failure RATE down rather than absorbing it: the poll is `singleFlight()`-coalesced so the 5s, 15s and on-demand cadences can't race each other into an `AbortError`, and `STATUS_TIMEOUT_MS` is 3000 (not the original 1500) — widening `STALE_STATUS_LIMIT` instead would have slowed #461's offline detection, which is a different contract sharing the same constant. `FIRST_POLL_WAIT_MS` is derived from `STATUS_TIMEOUT_MS`, not written flat, so raising the deadline can't silently un-do the boot await. `presentListeners()` deliberately stays on the RAW count: it fails **CLOSED**, where a blip costs at most one skipped scrobble, which is the safe direction — don't unify it onto the gated reading. `startListenerMonitor()` is awaited before `queue.startWatcher()` so "never polled" can't buy a free agent pick on every restart. Pinned by `scripts/listeners-status.test.ts` and `scripts/stream-idle.test.ts`, which replays 120-poll pause AND live windows through both helpers.
- **Ducking**: stick with `smooth_add`. An RMS sidechain follower drove `music_bus` to silence (`f38a9af`). `smooth_add` is gated talkbax — it cares only whether the channel has signal, not how loud.
- **TTS**: callers go through `tts.speak(text, {kind})`, never the engine modules. `tts.js` handles per-kind override + automatic fallback. The Kokoro worker path defaults to `/app/scripts/kokoro_worker.py`; set `KOKORO_WORKER` for non-default layouts. **The rescue chain is a list of voice SLOTS, not engine ids** (`audio/tts-fallback.ts`): the operator's configured fallback (`settings.tts.fallback` — engine AND voice, the TTS analogue of `llm.fallback`, default off), then `defaultEngine` → `piper` → `kokoro`. Only the configured rung carries a `personaTts` override; the hardcoded rungs pass `null`, and that null is load-bearing — a cloud rescue must use the station default's credentials, not the persona provider that just failed. Dedup is by engine, **first-wins**, so a configured fallback naming the same engine as `defaultEngine` keeps its voice rather than reverting to that engine's global default. The same slot serves BOTH triggers (pre-flight reroute in `resolveEngine`, mid-render rescue in `speak`) so there is one answer to "what speaks instead"; `enabled: false` or an absent block is byte-for-byte the pre-fallback behaviour. Pinned by `scripts/tts-fallback.test.ts`.
- **openai-compatible TTS extra params** (`settings.tts.cloud.compatParams`, #1317, default `[]` = off): free-form `{key, value}` body fields merged into the POST to `/audio/speech`, for knobs a self-hosted server defines and the OpenAI API doesn't (Chatterbox's `temperature`/`seed`/`exaggeration`, and whatever the next engine invents — a named setting per server generation doesn't scale). **The merge happens at the fetch layer** (`compatBodyFetch` in `cloud-speech.ts`), not via `providerOptions`: the AI SDK's OpenAI speech model builds a CLOSED body, and its `providerOptions.openai` hatch both validates against a 2-key schema AND (in `@ai-sdk/openai` 4.0.11) drops what it parses through an upstream loop over an empty object — rewriting the serialized body is the only hook that works short of forking the provider. Rules live ONLY in `settings/compat-params.ts`, shared by the validator and the send path so a key that saves is a key that sends; values are stored as text and coerced to JSON types at send time (`0.8` → number, `007` → string, because servers use such values as ids). Four keys are **reserved**: `model`/`voice`/`input` have first-class fields (and an `input` override would mute the segment while still "succeeding"), and `speed` would COMPOUND with the local ffmpeg atempo stretch compat uses instead of server-side speed (#942). The list must stay in `settings.load()`'s explicit `tts.cloud` composition — that block does NOT spread `DEFAULTS`, so a key missing there saves to disk and then silently vanishes on the next restart. Empty keeps the request byte-identical. Pinned by `scripts/compat-tts-params.test.ts`.
- **Subsonic**: keep using `getAnnotatedUri` for anything going to Liquidsoap — raw URLs lose metadata until ID3 arrives, and the `on_metadata` hook needs `subsonic_id` for `/cover/:id` artwork.
- **Genres are multi-value**: `subsonic.songGenres(song)` is the single ingest normaliser (OpenSubsonic `genres: [{name}]` array → `string[]`, legacy scalar fallback). library.db stores `genres` as a JSON array; the scalar `genre` column is GENERATED (genres[0], indexable) — write `genres`, never `genre`. Matching is any-of via `show-filter.ts trackGenres/genreMatches`; LLM-facing shapes carry all tags comma-joined in the `genre` field. **Genre matching is one-directional**: a track's tag may REFINE the show's genre (a "Punk" show admits a `Punk Rock` track) but never broaden it (a "Pop Punk" show rejects a plain `Pop` track), and containment is word-boundary aligned so a "Rap" show doesn't pull `Trap`. The reverse direction is what let strict shows leak broad tags — don't reintroduce it. Note the resolver `subsonic.resolveGenreName` is still deliberately loose both ways: it maps free text to a real library tag for listener requests and server-side fetches, so a show whose genre isn't a library tag can still broaden there (see issue for the fetch-hint/match-target split).
- **Era years (#842)**: a track's era is judged by `show-filter.resolveEraYear`, never raw `year` — the resolved `original_year` wins (walk-time album `originalReleaseDate` on non-compilation albums; MusicBrainz phase-0 enrichment for compilation tracks), and a **compilation's plain `year` is untrusted** (it's the compilation's own release date, so unresolved comp tracks read as unknown-year and drop from era windows). SQL-side era filters (`library-db.filter` yearFrom/yearTo, seed decade bucketing) mirror the same precedence — keep JS and SQL in agreement. `music/musicbrainz.ts` is keyless but hard-throttled to 1 req/s with a descriptive User-Agent (MB policy) — don't widen it; misses are stamped (`original_year_checked_at`) so passes never re-query them.
- **Similarity signal (#1246)**: `music/embeddings.formatTrackText` is the canonical embed text and carries **head line + Last.fm tags + lyric excerpt + a `Sound:` line of measured acoustics + an `Era:` decade line** (Sound: zero-shot CLAP `audio_moods`, a tempo BAND from bpm, major/minor from the Camelot `musical_key`, and `instrumental` as a MINORITY marker (`vocal_ranges = []` speaks, vocal tracks don't — a word ~80% of a library shares clusters nothing) — words, never raw numbers or codes, which embed as arbitrary tokens; Era: the decade word from `show-filter.resolveEraYear`, never raw `year`, and being label-derived it deliberately does NOT count as musical signal in `labelOnlyVectors`. The pace curve is deliberately NOT embedded — its practical range is ~0.02–0.5 so fixed thresholds stamp one word on everything, and relative ones break determinism; see `TrackAcoustics`). The tagger's own `moods`/`energy` must **never** go in: phases run enrich → embed → seed → propagate, so those are decided AFTER the vectors exist by voting over the KNN graph built FROM them (`tag-library.ts`), and feeding them back is circular — on a fresh library they don't even exist yet. With every optional line empty the vector IS the label, so similarity ranks by artist/album wording while presenting itself to the picker as mood similarity (a prolific artist self-clusters; "Nick Drake" lands next to "Drake") — `library-coverage.labelOnlyVectors` is what makes that visible, and `enrichment.lastfmTags` defaulting to `null` = auto (fetch only with an API key) is the usual reason a library has none. Changing the text shape means bumping `EMBED_TEXT_VERSION` + `embedding_meta.text_format`, a SOFT advisory (`embeddingFormatStale`) that never blocks a tag run the way a model/dim change does; `resolveIndexTextFormat` records the OLDEST shape still in the index, because a forward run leaves existing vectors alone.
- **LLM**: calls go through the AI SDK via the `llm/sdk.js` primitives; `matchRequest` + pool picker use `djObject` (Zod-validated, no manual JSON parsing). Default provider is the homelab Ollama box — reliable but maybe slow; **don't add aggressive retry**. Adding a provider: extend `LLM_PROVIDERS` in `settings.js`, add a builder case in `llm/internal/provider/registry.ts`, and a descriptor in `llm/internal/provider/capabilities.ts` (thinking knob + object strategy); call sites never name a provider, and per-provider quirks live ONLY in `capabilities.ts`.
- **Back-to-back artist guard** (agent path, #1124/#1187/#1251): the agent's discovery tools deliberately carry no artist filter (#618 — a strip inside the tools gutted the similarity pool on niche catalogues), so variety is enforced at the point of choice. If the pick repeats the on-air artist, `pickViaAgent` re-picks from the run's own other-artist candidates, escalating to a `blockedArtists` pool call when the run surfaced none, and only then allowing the repeat (logged either way). **Which candidates the re-pick may choose from lives only in `broadcast/dj-agent/artist-guard.ts`** — never inline at the call site — and it excludes the artists of the `ARTIST_VARIETY_WINDOW` (5) surrounding slots — queued-and-unaired, on air, and last played (`queue.neighbourArtistRoots`) — as well as the predecessor: an exclusion that remembers only the on-air artist keeps returning to whoever ranks next-highest, which is the same artist every OTHER slot rather than every slot (#1251). Wholly-recent alternatives fall back to the bare exclusion — never starve. Comparison is on `artistRootKey` (`music/recency.ts`), the lead-artist key, so a collaboration can't walk past a guard on the artist fronting it; `artistKey` stays the raw identity key because `trackKey` must keep matching the `title|artist` keys `queue.recentlyPlayed` builds from tag text. Pinned by `scripts/artist-guard.test.ts`.
- **Daily token budget** (`settings.llm.dailyTokenCap`, default `0` = off): the running per-UTC-day token tally lives in `llm/internal/telemetry/budget.ts` (incremented from the single `record()` chokepoint in `telemetry/log.ts`, the same `ok && usage.total` guard as the lifetime ticker; seeded once at boot from today's `events-*.jsonl` so a restart resumes the count). The pure `budgetMode()` (`core/pure.ts`, unit-pinned) maps `{used, cap, softPct}` → `normal | soft | hard`; **policy lives only in `broadcast/dj-budget.ts`** (the call-site gates), never inline. Tiers: `soft` (≥`budgetSoftPct`%) forces the cheap pool picker and mutes optional segments (links, station IDs, hourly, weather/news/etc.); `hard` (≥cap) makes **no** model call — `runTrackEvent` returns early so Liquidsoap coasts on the LLM-free `auto.m3u` (music never stops). Listener requests stay exempt through the hard cap unless `llm.exemptRequests` is off. Manual `/dj/segment` command routes (the gate-free `runStationId`/`runHourlyCheck`/`runLink` runners) are intentionally **not** budget-gated — an explicit operator action always fires.
- **Station voice switch** (`settings.tts.enabled`, default `true`): `false` makes the station **music only** — no links, idents, hourly checks, skill segments, banter, persona mic-passes, programme beats or spoken request intros. **Policy lives only in `broadcast/voice-policy.ts`** (`autoVoiceAllowed()`, the call-site gates), never inline — same split as `dj-budget.ts`, and the gates sit at the same points those do. The gate is **before generation, not at `speak()`**: gating the dispatcher would still have the LLM write every script and throw it away, so instead `dj-gate.shouldFire()` returns false for every kind (above the frequency ladder — it's not a cadence), `skillsTick`/`ensurePlan`/`maybeRunIntro`/`featureTick`/`outroTick`/`runPersonaHandoff` stand down, `runTrackEvent` forces `wantLink=false` (the agent path's event prompt orders silence, the pool path skips `generateLink`), the request agent's contract drops its intro field (`requestSchema`), and `routes/request.ts` skips `generateIntro` outright. `queue.airIntro()` carries a plain drop as a backstop for items queued before the flip (their WAV render is skipped at drain too; flip back on before the track airs and `airIntro` renders from the script). **Picks keep running** (the stream needs a next track) and **listener requests are still honoured** — track queued, text ack returned, just no spoken intro. Two deliberate non-inclusions: **jingles** are pre-rendered WAVs on Liquidsoap's own rotate, silenced by `jingleRatio: 0` (mixer restart) rather than this switch; and **manual `/dj/segment` triggers still fire**, the same exemption they hold from the frequency gate and the LLM hard cap. Applies live — no restart, no mixer bounce. Absent/non-boolean coerces to ON so an upgrade is byte-identical. Pinned by `scripts/voice-policy.test.ts`. Distinct from per-persona `frequency: 'silent'`, which is per-persona and still speaks request intros, programme beats and manual triggers.
- **Seed vs pick (#1247)**: every pick/request event message hands the agent the ON-AIR track's `[id: …]` so it can seed the discovery tools — and those tools all EXCLUDE the seed from their own results (`library-db/vectors.ts` `knnByBuffer` drops `excludeId`), so that id is the one real, well-formed track id in the model's context that no tool returned. `util/pick-seed.ts` owns the one wording that says so (`SEED_NOT_A_PICK_CLAUSE`, shared by the pick + request schema `id` descriptions AND `picker-tools.ts`'s empty-result `rule`) — never inline a second copy, and don't weaken it to "never invent an id", which an echoed seed literally satisfies. The trigger is upstream: the harness allows exactly ONE discovery call (`COMMIT_AFTER_STEPS = 1`) before pinning `activeTools: ['done']`, so a seed tool that returns nothing corners the model with an empty `seen` — where BOTH salvage stages are structurally dead (`nearestId` has no keys, `repickFromSeen` returns null on its first line). Hence `buildPickerTools`'s cross-index rescue: `tracksLikeThis`/`tracksThatSoundLikeThis` answer from the OTHER index when the one asked holds no vector for this seed (gated on the primary matching *nothing* — an all-filtered-by-recency primary keeps its `emptyResult`), and it says which index answered so the model doesn't reason about audio neighbours on the text axis. A zero-candidate run does NOT count against the agent circuit breaker (`classifyPickFailure`) — it's library coverage, not a model that can't drive tool calls, and opening the breaker there kills the session-aware picker for 10 min while advising "switch model" — but ONLY when at least one real discovery call ran (`toolCalls > 0`; `flattenToolCalls` excludes the synthetic `done`): an empty `seen` with ZERO discovery calls means the model never explored (`no-discovery`), which is exactly the breaker's failure class and still counts.
- **DJ persona**: `settings.dj.souls` is an array (1–10); `djSystem()` picks one at random per call. Legacy `dj.soul` string is migrated on load. Emptying the array falls back to seeded `DJ_SOULS`.
- **Station house rules** (`settings.djHouseRules`, #1182, default `''` = off): the one operator block appended to **both** prompt paths — `renderDjPrompt` (scripted talk) AND `agentPersonaPreamble` (pick/request/segment agents), which the `djPrompt` template never reaches. For path-agnostic correctness rules (TTS control tags, "spell out numbers", locale orthography); the agent-side framing scopes them to spoken fields so ids/reasons stay untouched. Edited in the System prompt modal on `/admin` Personas; empty keeps every prompt byte-identical. Pinned by `scripts/house-rules.test.ts`.
- **Guest co-hosts** (`shows[].guestPersonaIds`, max 3): while a guest show is on air, standalone segments (station ID, hourly, skill segments, manual link) rotate speakers via `settings.pickOnAirSpeaker()` (host ~60%) — the speaker persona rides through the generator prompt AND `queue.announce({persona, meta:{personaId}})`, so the voice, the prompt seat (`settings.onAirRosterClause`), and the session attribution always agree. **Track picks + their tied intros stay with the HOST** (the pick agent reads `session.windowMessages()` from the host's perspective); gating (frequency, capability ownership) is also host-keyed so who speaks never changes how often the station talks. `shows[].banter` (opt-in, needs guests) airs scripted multi-voice exchanges at :20/:50 (`dj-gate` `'banter'`: quiet=never, moderate=:20 only): one `generateBanter` `djObject` call writes the whole exchange, `queue.announceExchange()` renders every line's WAV first (all-or-nothing), then airs them back-to-back through the serialized `airVoice` chain — no audio mixing anywhere.
- **Programmes** (`shows[].programme`, opt-in; optional `shows[].segmentSkill` pins the feature): the show airs as a produced episode — intro at the top, one feature beat per hour (station-minute :35–:39 window), outro in the final hour's closing minutes (station-minute :55+) (`broadcast/programme.ts`; a single `*/5` cron dispatches on `dueBeat()`'s STATION-zone minute — fixed process-minute crons land mid-show on :30/:45-offset zones like IST; manual `runProgramme*` runners in `scheduler.ts`). Coherence comes from a per-episode **producer plan** (one `generateProgrammePlan` `djObject` call at session start: angle, per-hour feature topics, intro/outro notes) stored ON the session (`session.attachProgramme`); beats are marked aired BEFORE generating (the `markHandoffAired` idempotency pattern) so restarts never double-air. Plan-call failure → `fallback`: beats still air from the raw topic brief. Collision rules: the intro replaces the hourly check in hour one (and on a persona-change boundary the handoff **greeting** doubles as the intro — `episodeAngle` rides into `generateHandoffGreeting`; the standalone intro is skipped); `skillsTick` stands down for the whole programme (`programme.onAir()`); idents/banter keep their slots. The feature runs through the forced segment director (`runCapability(kind, ctx, {brief, persona})`) so it gets real data; a stale/absent kind falls to straight talk (`generateProgrammeFeature`). Guest shows open/close with multi-voice exchanges (`generateProgrammeExchange` → `announceExchange`). **Every beat carries `PROGRAMME_GROUNDING_RULE`** (`llm/internal/prompts/programme.ts`, #1301) — one constant appended by all four, never inlined per beat. `PROGRAMME_CONTEXT_FIELDS` shows these prompts NO track fields, so a beat told to be "concrete" about a music topic can only reach for a record it knows from training: a straight-talk feature aired "Smells Like Teen Spirit … blasts in" 16s into an unrelated track. The fix bans the **cue framing** ("playing now / coming up / just heard"), NOT the noun — a grunge feature that can't name *Nevermind* isn't a feature — and asks for certainty as a **separate** half, because real-facts-framed-as-a-cue and invented-credits are independent failure modes. The plan's `featureKindsClause` scopes `kind: null` to topics the host can carry unaided, but that is a frequency lever only: `runFeature` still reaches the ungrounded generator whenever a capability throws at air time. Pure arc helpers (`showSpan`, `planFeature`) live in `broadcast/programme-pure.ts`, pinned by `scripts/programme.test.ts`; the grounding rule + per-beat builders by `scripts/programme-grounding.test.ts`.
- **Festivals**: operator-editable via admin → Settings → Festivals (`settings.festivals`, validated by `validateFestivalsStrict`; seeded from `FESTIVAL_DEFAULTS` in `settings.ts` only when the key is absent — an emptied list stays empty). Fixed month/day schema, so lunar holidays (Easter, Eid, Lunar New Year) shift year-to-year and need per-year entries. `windowDays` spans month/year boundaries (`getFestivalContext` compares real dates).
- **Multi-station profiles**: `state/stations/<id>/` + `stations/active.json` decide the ACTIVE station dir, resolved once per boot in four places — `config.ts` (`STATE_DIR` = resolved dir, `STATE_ROOT` = root), `radio.liq` (`SUBWAVE_STATE_DIR` env), `docker/broadcast-entrypoint.sh`, and the AIO supervisor (kept in lockstep). No `stations/` dir → single-station, everything at the root as before. Switching = pointer write + mixer restart + controller `process.exit` (docker restart policy reboots both against the new dir) — never hot-swap state paths in-process. Only `icecast-secrets.env`, `hf-cache`, `analyze-tmp` stay install-level at the root (`conversionAction` in `stations/pure.ts` is the classifier; new root-level state files must be classified there and in `duplicateAction`). State files holding **absolute paths** must be re-derived at boot rather than trusted — `jingles.m3u` is the one such file today (`ensureDefaultIdent` rewrites it every boot so conversion/duplicate can't leave it pointing at a moved dir).
- **Listener request hardening** (raid 2026-07-28): every on-air safety decision for requests lives in `util/request-guard.ts` (scripted-opener stripping, verbatim-echo guard on intros/acks, requester-name screening), pinned by `scripts/request-guard.test.ts` — never inline a guard in routes or agents. `settings.requests` (enabled / maxPending / cooldownSec / perIpHourlyCap / globalHourlyCap / onePendingPerIp / repeatCooldownMin) drives `POST /request`'s gates and `middleware/ratelimit.ts`, applies live, and coerces to safe defaults when absent; env `REQUESTS_DISABLED` stays the hard override. Conversational messages are classified by an explicit `kind: 'track' | 'chat'` on **both** paths (`matchRequest`'s `REQUEST_SCHEMA_TOLERANT` and the agent's `requestSchema()`), each with `objectFallbacks: { kind: 'track' }` — chat gets an in-persona text ack, nothing queued. The classification must never be inferred from a null `id` alone: `coerceModelPayload` maps an OMITTED key to null, so "the model forgot the field" and "the listener wasn't asking for music" would be the same wire value, and a real request would silently play nothing. An omitted/botched `kind` degrades to `track` and falls through to the repick salvage + stateless cascade. `languageDirective`/`agentLanguageReminder` now ALWAYS render (default English) with a never-switch clause — the empty-when-unset behaviour is what let session-history mimicry flip the station into Russian; do not restore it. Raw request text survives only in the operator request log; the session, prompts, and air see cleaned text.
- **Likes + the operator heart** (#991, #1253): `state/likes.json` (`broadcast/likes.ts`) is accountless — one record per apparent listener per AIRING, keyed `HMAC(persisted secret, ip)`; the raw IP is never stored and one NAT is one key. The **operator's own heart** (the admin library row action) is a real record under the reserved `listenerKey: 'operator'` + `via: 'operator'`, paired with a synthetic `${songId}|operator` airing key so the existing dedup makes it idempotent per song. It counts in `countForSong` and reaches the picker like any like — the `via` marker exists so surfaces can tell them apart, not so one is second-class. Two exemptions are load-bearing and must not be "simplified" away: an operator record **skips the `topLiked` window cutoff** (a listener like ageing out is a taste snapshot expiring, an operator like ageing out is the DJ forgetting curation the operator set by hand) and **survives the `MAX_RECORDS` trim** (`trimTo` evicts oldest LISTENER records first, falling back to plain oldest-first only when curation alone exceeds the cap, so the bound always holds). Deleting likes never unstars in Navidrome, with ONE deliberate exception: the operator un-hearting when **no likes remain** for the song — that is a toggle, not a purge, and the "none remain" guard is what stops a star earned by twenty listener likes being discarded. Row hearts on every library view read one `GET /likes/index` map rather than per-endpoint annotation, because browse/search/sounds-like come from three different sources and Navidrome search rows have no `library.db` row to annotate. Pinned by `scripts/likes.test.ts`.
- **Shared form schemas (zod)**: a validated shape is defined ONCE in `controller/src/schemas/<feature>.ts` and mirrored into `web/lib/schemas.generated.ts` by `npm run gen:schemas`, with `lint.yml` regenerating + `git diff --exit-code`ing it — same mechanism as the theme-token mirror, and for the same reason (the web package can't import `controller/src` at build time: separate package, separate Docker build context). **Files under `src/schemas/` may import ONLY from `zod`** — enforced twice, by a `no-restricted-imports` rule in `controller/eslint.config.mjs` (the merge gate) and by `gen-schemas.ts` itself at generate time (which also catches `export … from`, a module reference no import check sees), because the file is copied verbatim into the browser bundle and has to resolve in the WEB build. Rules that aren't pure functions of one value go in a `*-server.ts` sibling, which is NOT mirrored: for webhooks that's the `authHeader: 'set'` redaction sentinel (needs the existing list) and `resolveWebhookIds` — id minting (a side effect) plus cross-item de-duplication (needs sibling awareness). Never hand-edit the generated mirror. **Both the strict and the lenient path run the schema**: `validate*Strict` throws, `normalize*` repairs-or-drops and never throws, but neither restates a rule — see `controller/CLAUDE.md`. `middleware/validate.ts`'s `validateBody()` runs the schema at the route boundary and returns `{ error, fieldErrors }` — `error` is the flat string every existing client already reads from a 400, `fieldErrors` is keyed by dotted path (`webhooks.1.url`), which is also react-hook-form's `setError` syntax, so a server-only rule lands on the right input. **It does NOT replace `settings.update()`'s validation** — `update()` is reached by backup import and onboarding too and stays the authoritative chokepoint, so `validate*Strict` keeps its name and signature and calls the same schema. Web forms bind via `lib/form.ts`'s `useZodForm`. There is deliberately **no `ui/form.tsx`**: shadcn's `Field` primitives are already vendored and `FieldError` already takes react-hook-form's `{ message }` shape.
- **Blocklist rules** (#1300 FR 1, closes #752): the never-play blocklist carries **rule entries** beside the id entries — attribute predicates (`genre`/`tag`/`mood`/`artist`/`album`/`title`/`playlist` + any-of values) with an optional seasonal **allow-window** (inclusive month/day, wraps year-end, station zone) and an optional show scope — same `blocklist.json`, same routes, same Blocked tab. Pure matching lives in `music/blocklist-rules.ts` (pinned by `scripts/blocklist-rules.test.ts`); `blocklist.ts` owns the evaluation context — a ~15s-memoised active-rule set (clock via `zonedParts`, show via `resolveActiveShow`, both resolved once per sweep, NOT per track) and pre-resolved playlist member sets (the one async input, so `matchOf` stays synchronous). **Enforcement is inherited, not added**: rules ride `hitOf()`/`isBlocked()` inside the existing chokepoints (subsonic reject, library sources, `queue.push` gate, request declines, `annotate`) — never add a second rule-filter at a pick path, that's how the two kinds would drift. `hitOf()` answers entries-FIRST (the UI unblocks exactly the entry), and `BlockRef` is now a `kind: 'entry' | 'rule'` union. Rules are absolute like the id list — no never-starve anywhere, requests included; the row UI deliberately offers **no one-click unblock for a rule ref** (one rule can block hundreds of rows — edits happen on the Blocked tab). `tag` matches EXACT-normalised across every ingested namespace (genres ∪ moods ∪ audioMoods ∪ Last.fm — `show-filter.trackAllTags`); `genre` reuses `genreMatches`' refine direction (blocking "Punk" drops "Punk Rock", not the reverse). Custom file tags (e.g. a country) only work once they land in a field the pipeline ingests — that's an ingestion boundary, not a rules bug. Spec: `docs/superpowers/specs/2026-08-05-exclusion-rules-design.md`.

### Heavy TTS engines (Chatterbox + PocketTTS)

Chatterbox + PocketTTS are heavy PyTorch engines, sidecar-or-local-worker, env-switched on `TTS_HEAVY_URL`. Their shared clone-reference folder (`state/voices/`) is owned by `audio/voice-library.ts` and imported from `/admin/imaging?tab=voices` — the folder deliberately keeps **no JSON sidecar** because it stays operator-writable by hand, and its cheap `scan()` is what the 3s `/settings` poll rides (only the admin-only `list()` probes durations). Details in [`controller/CLAUDE.md`](controller/CLAUDE.md).