CLAUDE.md · git:20261115.857e622 · 2026-11-15 · sha256 c42ab0809c6af2a0

CLAUDE.md git:20261115.857e622A

Immutable. This exact content never changes and is served at /api/v1/blob/c42ab0809c6af2a0.

# CLAUDE.md

SUB/WAVE is a personal internet radio station: one Icecast stream that every listener hears, with an AI DJ that picks the tracks and talks between them.

This file loads into every session, so it holds the map, the commands and one line per invariant. The reasoning behind each invariant lives in the doc named beside it, or in the module's own header comment, and you read it before changing the thing it describes: most of those paragraphs exist because the obvious fix shipped first and was wrong. New rules go in the same shape: one line here, the reasoning in the doc.

## Where the detail lives

| Working on | Read |
| --- | --- |
| `controller/src/**` | [`controller/CLAUDE.md`](controller/CLAUDE.md) |
| `liquidsoap/radio.liq` | [`liquidsoap/CLAUDE.md`](liquidsoap/CLAUDE.md) |
| `web/**` | [`web/CLAUDE.md`](web/CLAUDE.md) |
| queue, talk scheduling, speech timing, transitions, TTS, personas | [`docs/internals/broadcast.md`](docs/internals/broadcast.md) |
| show changes and sign-off/greeting handoffs | [`docs/internals/show-boundary-handoffs.md`](docs/internals/show-boundary-handoffs.md) |
| library, tagging, picker, requests, blocklist | [`docs/internals/music.md`](docs/internals/music.md) |
| zod schemas, the `/settings` patch registry | [`docs/internals/schemas.md`](docs/internals/schemas.md) |
| analyzer, Icecast rendering, auth gates, privacy, multi-station, state layout | [`docs/internals/infrastructure.md`](docs/internals/infrastructure.md) |

## Commands

```bash
docker compose -f docker-compose.dev.yml up -d   # dev stack: broadcast, controller (tsx watch), analyzer, socket proxy
cd web && npm install && npm run dev             # web UI on :7700, a separate process
docker compose logs -f controller
curl http://localhost:7700/api/health            # liveness through the Caddy edge (prod)
```

**Dev hot-reloads; prod needs a rebuild.** Dev bind-mounts `controller/src`, `controller/scripts`, `radio.liq` and `sounds/`: the controller restarts itself, and a `radio.liq` edit needs `docker compose -f docker-compose.dev.yml restart broadcast`. Prod images `COPY` the source, so `restart` reruns the old code and a change needs `docker compose up -d --build <service>`.

The compose files sit at the repo root: `docker-compose.yml` (prod, with Caddy as the only host port), `docker-compose.byo.yml` (your own reverse proxy, which must replicate `docker/Caddyfile`'s routes on one hostname) and `docker-compose.dev.yml`. Each one's header explains it. Operators drive them through the standalone `subwave` CLI, raw `docker compose`, or `npm start` in a clone.

## Lint and tests

- **Lint is the merge gate.** `npm run lint` in `controller/`, `web/` and `mcp-subwave/` runs in `.github/workflows/lint.yml`, alongside the theme-token, schema-mirror, zod-parity and publish-matrix checks. Only the controller and web lint jobs are required to merge.
- **CI does not run the test suites** (apart from two ffmpeg tests in `audio-tests.yml`). Run `npm test` yourself in `controller/` or `web/` before pushing changes there.
- **Always run tests through `npm test`** (`npm test -- <substring>` filters). The controller runner gives each file its own temp `STATE_DIR`; `node --test` or `tsx <file>` can write into the repo's `state/`, the dev station's own. Files run one at a time by default (`--jobs N` in the controller). Dropping in `controller/scripts/*.test.ts`, or a web test under a root listed in `web/scripts/run-tests.mjs`, is the whole registration. The `controller/scripts/run-tests.ts` header covers the rest (`node:test`, reserved ports, `createTempDir`). A test removes its temp dir with `await removeTempDir(dir)` (`scripts/test-utils/temp-dir.ts`), never a bare `rmSync`, which races in-flight writes into `ENOTEMPTY`.
- **Run heavy commands one at a time, never in parallel.** Lint, `tsc`, a test suite, `npm ci` and a build each get the machine to themselves: no two in one message, no second one while a background one runs, and one package's suite at a time. Together they have OOM-killed a 16 GB dev box.
- The scale benches (`npm run bench:admin`, `bench:lookups`, `bench:observatory`) are outside `npm test` because they seed GB-sized libraries (`bench:observatory` peaks at ~1.3 GB RSS plus a ~0.9 GB DB at its default 200k rows). Run one only when asked or after touching its read path, alone, with its `*_TMP` on real disk (`/tmp` is tmpfs on some hosts, and a full one fails the seed with `SQLITE_IOERR_WRITE`).

## Pull requests target `develop`

Use `gh pr create --base develop`. `main` is the release branch, and `enforce-main-source.yml` fails any PR into it from anything but `develop` or release-please. Ignore the session preamble's "Main branch: main" line: it is computed locally and is wrong for this repo. The release PR (`develop` → `main`) is merged with a merge commit, never squashed (CONTRIBUTING.md explains), and is cut with the `subwave-release-pr` skill, which now lives in the maintainers' shared skills repo.

## Architecture

The pieces are Broadcast (Icecast + Liquidsoap), Controller (Express, ESM, TypeScript), Web (Next.js). The native iOS + Android app is its own repo, [getsubwave/app](https://github.com/getsubwave/app), and talks to the controller over the same HTTP API as the web player. Controller and Liquidsoap share the `state/` dir (`/var/sub-wave` in containers) and must mount the same host path. Data passes as files in it; control (reloads, restart, skip, probes) goes over Liquidsoap's telnet on `broadcast:1234` (`broadcast/liquidsoap-control.ts`).

**Controller → Liquidsoap.** Liquidsoap reads; the controller only writes. The five polled files are written only by `Queue` methods, each through its own serialised `writeHandoff` chain, which waits for Liquidsoap to consume the previous write. Each poll interval caps the latency it adds.

| File | Read | Purpose |
| --- | --- | --- |
| `next.txt` | 1.0 s poll | one annotated track URI → `dj_queue` |
| `jingle-now.txt` | 0.5 s poll | one jingle URI → a priority queue for the next safe boundary (an operator press, or the controller-owned rotate) |
| `say.txt` | 0.5 s poll | voice WAV → `voice_queue`, heavy duck (`ducking.voice`, 0.22): idents, time, weather, request intros |
| `intro.txt` | 0.5 s poll | between-track link → `intro_queue`, light duck (`ducking.intro`, 0.30) |
| `sfx.txt` | 0.5 s poll | sound effect → `sfx_queue` |
| `auto.m3u` | telnet `auto.reload` | the coast playlist for the current mood |
| `jingles.m3u` | telnet `jingles.reload` | the mixer's own jingle rotate, rebuilt by `broadcast/jingles.ts` |
| `liquidsoap_*.txt` | once, at startup | crossfade, jingle ratio, duck depths, per-mount enable…, written by `settings.update()`; a change needs `/restart-mixer`. The Icecast renderers read the stream bitrates and hand them on as `SUBWAVE_*_BITRATE` (`infrastructure.md`) |

**Liquidsoap → Controller.** Marker files written by `radio.liq` (the rules are in `liquidsoap/CLAUDE.md`):
- `now-playing.json`: the live track, from `music_meta`, the pre-cross handle.
- `jingle-playing.json`: a jingle is on air, so `airVoice` holds speech until its window passes.
- `bed-playing.json`: an instrumental bed started. Beds never reach `now-playing.json`, so this is the only signal that airs the link over one.
- `voice-playing.json`: a spoken clip started, which is what makes air-time stamps real (#1382).
- `pause-talk-playing.json` → `pause-talk-voice-accepted.json` → `pause-talk-voice-started.json`: the ordered pause-and-talk handshake that makes a controller-only restart exactly-once.
- `music-starved.json`: the dead-air guard's state, with a heartbeat. Surfaced as `musicStarved` on `GET /state`.

**Controller → browsers** is HTTP: `web/hooks/useStationFeed.ts` polls `/now-playing`, `/state` and `/session` every 5 s. **Browsers → Icecast** is a direct `<audio>` on `/stream.mp3`, which must always be served (Sonos, hardware radios, cars, older Safari); `web/CLAUDE.md` has the Opus upgrade rules.

**DJ session.** `state/session.json` is the DJ's live chat-history session (`broadcast/session.ts`), archived on roll. Prompt memory follows that session, never the station-wide booth log (`Queue.djLog`); the roll and handoff rules are in `broadcast.md`. Never offer the outgoing show's raw speech to the incoming prompt. Words no model wrote (a RAW `/dj/say`, a jingle's script) are stamped `meta.verbatim` and withheld from every prompt by `broadcast/prompt-memory.ts` `withheldFromPrompts()`. `Session.boothCarry` is display-only.

**Config.** Three root `.env` vars boot the stack (`ADMIN_USER`, `ADMIN_PASS`, `SITE_URL`). `npm run setup` and `/onboarding` persist everything else to one layer: Navidrome credentials to `state/setup-config.json`, cloud keys to `state/secrets.env` (0600), the rest through `settings.update()` to `state/settings.json`. Env beats the wizards, except Navidrome env in multi-station mode.

## Invariants

**Structure**
- **One writer per file**: `queue.playJingle()` is the only writer of `jingle-now.txt` (the automatic rotate calls it), and `queue.onSpoken()` is the only place post-air bookkeeping happens.
- **A pushed track is "handed over", never "playable".** Resolution is the `proto_subhttp` probe outcome, consumed by `queue.verifyPushResolved()`; never infer it from `dj_queue.queue()` membership.
- **Policy lives in its own module** (`*-policy.ts`, `dj-budget.ts`, `talk-scheduler.ts`, `util/request-guard.ts`, `music/blocklist-rules.ts`, …). A decision reached from several call sites is made in one place, and a second copy of the check is the bug.
- **A gate's failure direction is deliberate; never unify two.** `POST /listener-auth` fails open while listener auth is off, while `POST /station-auth` and `middleware/station-auth.ts` fail closed. The listener-count gates fail open on an unknown count, while `presentListeners()` fails closed, and the idle wake probe (`peekListeners()`) commits nothing and acts only on a positive reading. `validate*Strict` throws and `normalize*` repairs or drops, and neither restates a rule.
- **A validated shape is defined once**, in `controller/src/schemas/<feature>.ts`, and mirrored to `web/lib/schemas.generated.ts` by `npm run gen:schemas` (CI diffs it; never hand-edit it). Those files import only `zod`; impure rules go in a `*-server.ts` sibling.
- **A behaviour-preserving refactor preserves behaviour, accidental leniency included.** Tightening it is a separate PR, stated as a behaviour change (`schemas.md`, on the patch registry).
- **Keep the broadcast entrypoint and the AIO supervisor in lockstep.** `docker/broadcast-entrypoint.sh` and the AIO duplicate six things (`infrastructure.md` lists them, and six tests drive both copies), so fix one, fix both.
- **An AIO CUDA architecture tag names a GPU, not a wheel.** Each `subwave-aio-cuda` architecture tag (`:pascal`, `:blackwell`, …) points at the newest build that still supports its GPU: never at a build that dropped it, and never one tag for several GPUs. Only the `primary` build takes `:latest` (`infrastructure.md`, the AIO CUDA tag table).
- **State bootstrap is never fatal.** Guard each step and warn; Icecast and the dead-air guard must still come up.
- **The admin lockout counts distinct guesses, never requests**, and `ADMIN_LOCKOUT=off` (env only) is the operator's final say (`infrastructure.md`). The web console sends `X-Subwave-Console` so it is never answered with a Basic challenge.
- **The edge drops Icecast's Basic challenge only for a client that can't answer it** (`?auth=`, or `Sec-Fetch-Dest: audio|video` from the same origin), in both Caddyfiles and every `docs/reverse-proxy.md` recipe. Unconditional either way is the bug: stripped, ffmpeg and mpv can't log in; kept, the browser's "Sign in" dialog covers the player (`infrastructure.md`).
- **The listener-country chain fails open link by link** (`broadcast/listener-country.ts`). A later link runs when an earlier one misses (`XX`/`T1`), not only when it is absent.

**Timing** (`broadcast.md`)
- **Published timestamps are live-edge**, and listeners sit `stream.bufferSeconds` (22 s) behind. What `/now-playing` advertises is the burst the running mounts were rendered with (`stream-mounts.json`), never a setting saved since. Listener surfaces add the offset (`useStationFeed.leadMs`, which is less whatever the web player skipped); operator surfaces don't. `<burst-size>` is bytes, computed per mount from the bitrate liquidsoap is handed. Never judge the cushion with `buffered.end − currentTime`.
- **The web player skips only stale idle silence, never music, and only on the MP3 mount** (`web/lib/idleSkip.ts`). Opus is CBR since #2138, but an older broadcast image's VBR Opus burst reaches back past the pause, and the player cannot tell which one it is tuned to.
- **Every scheduled spoken segment is a row in one slot table** (`broadcast/talk-scheduler.ts`), driven by one per-minute `talkTick`, one talker per minute. A slot is a window, and a held row postpones, never cancels. A second talk cron is the bug.
- **One sanctioned exception is the over-music jingle ID** (`jinglePlacement: over | both`): the now-playing watcher offers it once per song, at the opening, and it stands down to any speech rather than taking a slot (`broadcast.md`).
- **The other is a per-skill `cron:` timer** (`scheduler.speakSkillCron`). With `djTalkOnlyBetweenTracks` on it claims the one boundary before generating, and a fire that finds it taken stands down until its next cron tick; off, it speaks at once, outside any talk-air scope (`broadcast.md`).
- **A rendered segment is placed, not trimmed**: the lever at a boundary is which boundary it takes (`broadcast/vocal-runway.ts`).
- **A pause-and-talk break is silence on the music timeline.** The voice still goes through `say.txt`.
- **A show handoff is prepared for the confirmed final outgoing track**, never by look-ahead alone (`show-boundary-handoffs.md`).
- **A programme plan waits for its episode preparation to settle** (`preparationSettled`), and the greeting uses a plan's angle only while the occurrence and subject it was written from still match (`preparedPlanAngle`); before then it names only a subject the skill already chose (`preparationOpening`). A plan whose tool failed for good is kept honest by its no-subject brief (`NO_SUBJECT_LINE`), so every beat trusts its angle alike (`broadcast.md`, #2321).
- **A spoken clock is a forecast**, guarded by two paired checks in `broadcast/queue/pure.ts`.
- **A show-boundary cut is a fade through the existing `liq_cue_out` path.** It is measured from the pick's expected air time, and that forecast must count the bed.
- **Anything that detects starvation fires immediately and ramps the level**: a guard that waits before firing does not fire.
- **Degrade silently and immediately, never through a timeout.** An unmeasured value is `estimated: true`, with its timestamps absent, not zeroed.

**Audio** (`liquidsoap/CLAUDE.md`)
- Keep fade duration equal to the cross buffer; vary the buffer, not the fade.
- Ducking is `smooth_add`, never an RMS follower; `p` is the fraction of the music left up.
- Every transition effect runs on Liquidsoap's single streaming thread, so its cost is its shape: the dissolve sums its combs and subtracts the dry once, never per tap.
- Both sides of a rendered seam are gained by `music/loudness.ts` `resolveGainDb`, never from the analyzer's LUFS.
- The Opus encoder is hard CBR (`vbr="none"`): `<burst-size>` is bytes, and VBR idle silence stretched a new listener's burst back past the pause (#2138).
- Loudness and peak are one whole-file measurement (`loudness` v2, stamped `loudness_version`); nothing that measures less may overwrite it. The `edges` facet outranks the window figures in silence trim.

**Library, picker, LLM, TTS** (`music.md`, `broadcast.md`)
- Write `genres`, never `genre` (a generated column); `subsonic.songGenres()` is the one ingest normaliser. Genre matching is one-directional.
- Judge era with `resolveEraYear` and `yearUntrusted`, never raw `year`, and keep the JS and SQL era filters in agreement.
- Silence trim measures against an absolute floor, and `music/silence-trim.ts` owns every onset shift.
- A track's instrumental verdict is `isInstrumental` over both measured windows, each judged alone (`music/lyric-vocal.ts`). A row carrying `vocalRanges` carries the tail evidence too, and SQL reads it through `SQL_TAIL_VOCAL_RANGES`, never the whole `outro_json`.
- The opening and closing vocal gates have their own mix floors (`HEAD_`/`TAIL_VOCAL_MIX_FLOOR`); never unify them. Demucs separates with `shifts=0`, so one file gives one verdict (`music.md`, #2237).
- A write that moves a `Sound:` word marks the vector through `markTextVectorDirtyIfSoundChanged`: by part (measured or moods), against the words stored with the vector (`text_vector_sound`), never the row before the write. An unknown part never marks: NULL, or the moods a relabel-all moved, which it forgets (`forgetVectorSoundIfMoved`) rather than marks, except a new track's first moods, judged before the pass writes (`music.md`, #2236, #2313).
- Library coverage never counts on the read path; only `refresh()` counts it.
- Scheduled tagging (`tagger.auto`, off by default) starts at most one run per station day, never over a run already going, holds its start for a Navidrome scan and for Quiet times, catches up the same day only a run it owed while the controller was down (a save that turns it on or moves its time past today's waits for tomorrow), and never answers a replaced-file hold. Every decision (check order, holds, outcomes, record writes) is `music/tag-schedule-policy.ts`, and `broadcast/tag-schedule.ts` only reads, writes and logs. Work counts only what the run can close: untagged rows it would ask the LLM about when it tags moods, and Navidrome's song count above a saved baseline. library.db's row count stands in for that baseline only until the first skip or clean run saves a real one, and is lowered like it, because the walk's exclusions keep it below Navidrome's count and stale rows can keep it above (`music.md`).
- Show filters answer from the row they are given: a library-row mapper writes each `energy`, `genre`/`genres` and vocal-window column it selects even when unknown (an explicit `null`, or `[]`), the readers trust that, and only a shape lacking it looks the track up, so a mapper never emits one of these keys for a column it did not select (`music.md`).
- Anything going to Liquidsoap uses `getAnnotatedUri`.
- An LLM tag answer with no usable mood is untaggable, never tagged: every answer, bulk or Retag, is stored by `recordTagAnswer` (`tag-library/tag-input.ts`), which leaves the row untagged in `clearTrackTags`' shape with `untaggable_key` naming what was asked, and the bulk run doesn't re-send it while that still matches (`music.md`, #2283).
- The tagger's own `moods`/`energy` never enter the embed text. Bump `TAGGER_CONTRACT_VERSION` (`music/tagger-core.ts`) when the prompt asks for something different.
- The tagging prompt hears a track's audio only through `tagInputFor`: `taggerSoundWords` (tempo word, key mode, `isInstrumental`) and its Last.fm tags, never raw BPM, audio moods, `audioEnergy`, LUFS, lyrics or descriptors. `recordTagAnswer` stamps `tracks.tagged_measured` with whether it heard the audio, and only a Re-decide the operator starts revisits a blind row (`music.md`, #2281).
- CLAP cosines are not comparable across moods, so calibrate per mood.
- The sound map fits UMAP on a seeded sample of at most `SAMPLE_CAP` tracks and places the rest at their nearest sampled neighbours (`music/map-placement.ts`): umap-js's fit memory outgrows the library. An out-of-heap run holds the boot retry, and any other failure holds after one boot retry, until the vector count passes the stale threshold or `SUBWAVE_MAP_HEAP_MB` changes; a manual run is never held (`music/map-projection-policy.ts`, `music.md`, #2314).
- Sound descriptors (`music/audio-descriptors.ts`) are CLAP guesses, stored and read only through `usableDescriptors`, by the admin dossier: never the embed text, Sleeve Notes, fact packets, the picker payload or a public read. They stay out of the `Sound:` line until selection can tell an absent instrument from a rare one, measured on real masters across genres (`music.md`). Below the baseline floor they select nothing, and `isInstrumental` alone owns the vocal question.
- A prepared artist episode's tracks are one set whichever path builds the catalogue: the mirror and the albums path both judge credits with `music/artist-credit.ts` `creditsArtist`, and once every row it needs carries `album_artist_id` the mirror is trusted when it covers the songs Navidrome counts on the artist's albums; before that walk the pre-column rule (the artist's own rows against that count) stands, so an upgrade never does worse (`music.md`, #2333).
- Enforce variety (artist spacing, album cooldown) at the point of choice, never inside the discovery tools.
- The track-length cap and floor are different mechanisms; never unify them. A never-starve filter never returns its input array.
- Tempo-derived timing is octave-safe: fold, then halve, never clamp.
- The seed track id is not a pick (`util/pick-seed.ts`).
- A clean show (`show.excludeExplicit`) holds back only a positive `explicit` tag; no tag and unknown pass (`music/explicit-policy.ts`). It filters before every never-starve step, is hard on the pick paths and requests, and only the coast may relax it, last, in the booth log. The drain judges an unsent automatic pick again, and a tagged pick running into one fades where it begins (`music.md`).
- The blocklist is absolute, with no never-starve anywhere, requests included. Its rules ride the existing chokepoints, and every name tier keys through one fold (`recency.nameKey`).
- The analyzer writes shared folders 777 and files 666 whatever its umask, and a folder the sweep cannot delete leaves the budget check, before any delete if the `access()` probe catches it, otherwise once its own delete fails (`broadcast.md`).
- The stem cache's scan order and eviction order are one rule (`music/stem-priority.ts`).
- A stem window is used only beside a stamp naming the same recording (`head-meta.json`/`tail-meta.json`, written last; `music/stem-provenance.ts`, mirrored in the worker), and with the row's `tracks.file_size`, which `hasWindow` reads itself and every stems request sends the worker to stamp (`analyzer.ts` `withStemSource`). A mismatch is a miss, never an eviction, and a folder from before the stamps matches. A proven tail that did not land leaves `stems_at` unset, up to a bound (`music/stem-stamp-policy.ts`), and accepting a replaced file with a new size clears it (`broadcast.md`).
- Pick-time stems start only after the pair is sent, for the held track, and the drain never awaits them. They may take a full stem cache over its budget, by a bounded allowance the hourly sweep evicts, judged on the bytes it can evict (folders it cannot delete are recorded beside the total, `unevictableBytes`), and never touch the pass's own budget rule; while they are on, both sweeps evict a queued track's stems last; quiet-only analysis switches them off, and the blend render stands down while one runs unless the sidecar pool has a spare member (`broadcast/pick-stems-policy.ts`, `broadcast.md`).
- Track-level Last.fm tags are opt-in and `lastfm_tags` stays the one list: `lastfm.getMergedTags` is the bulk pass's and the retag route's one read, `db.recordLastfmTrackTags` their one write, and only a genuine answer stamps `lastfm_track_tags_at`. A failure never does, or an outage marks the library done. The merge is additive, the song's own tags ahead of the artist's whole list, so turning this on can only make a `tag` rule match more, never less. On both paths only tags replace a stored list: an empty or failed artist lookup, or Last.fm tags off, keeps it (`lastfm-tag-policy.listAfterArtistLookup`, `music.md`).
- The orphan purge moves only what reads as a stem dir, deletes only from its quarantine, only what still reads as stems, and only past the grace (one exception: a newer live copy replaces a quarantined one of the same id, on a fresh stamp), releases only stems proven to be the returning row's audio (`sameAudio`, failing closed: a returning id is not returning audio), and keeps quarantine bytes outside the budget (`music/orphan-purge.ts`).
- LRCLIB lyrics reach the listener Lyrics panel only, never the analyzer, and are looked up when a track is queued and again at air time, never on the read path (`music/lyrics-sources.ts`).
- `getLocalPath()` is for Liquidsoap: it answers only for a mount the mixer proved it can read (`music/library-mount.ts`), and anything short of that proof streams. The proof covers the mount, not a file, so the drain also asks about each pick's own file (`mixerReadablePath`) within its budget, decides local or stream once per handoff, and streams on anything but a timely yes. A reader in the controller uses `findLibraryFile()`. A file existing is not proof it is the track: a real path outside the mount plays only when its size matches and its tags give it the title stock Navidrome reports (the subtitle appended, cut at 1,024 bytes), and every tag shape the reader knows Navidrome reads another way streams (`music/tag-title.ts` lists them, and the shapes that still play a wrong file; `music.md`).
- LLM calls go through the `llm/sdk` primitives, and provider quirks live only in `llm/internal/provider/capabilities.ts`. The default provider is a slow homelab Ollama, so add no aggressive retry.
- TTS goes through `tts.speak(text, {kind})`. The rescue chain is a list of voice slots, and a rescue target is engine + provider.
- A whole line that is a listed stand-in (`placeholder`, `TBD`, template text) is dropped before TTS: `queue.speakable` judges model-written speech with `broadcast/stand-in-policy.ts`, on the line both before and after `normalizeForDisplay` and past any leading label, and `push()` reports a dropped intro so no caller records it as said. The list is a net, not a guarantee: `[laughs] placeholder` and `{text}` still air.

**Product behaviour**
- The station keeps making sound: the token cap, a muted voice and an LLM outage never stop the music.
- Manual operator triggers are exempt from every automatic gate (frequency, budget, voice switch, clock switch).
- An operator block (`POST /dj/queue-block`) reuses `queue.push()` and its existing opt-outs, with no new bypass; the never-play list still applies.
- `requestedBy` says which exemptions a track gets, not who is waiting. Count waiting listeners as `queue.pendingListenerRequests()` plus the requests still resolving in `routes/request.ts`, which hold no queue slot yet.
- Gate before generation, never at `speak()`.
- Public reads are explicit allowlists: never widen one to TTS config, skills or behaviour dials. A persona's `soul` is a system prompt, published only behind `publishPersonaSouls`, and absent (not empty) when off.
- A DJ template without `{location}` withholds the place from every model: prompts and skill tools see the live context only through `settings.spokenContext()` (`buildContextLines`, `segment-tools.ts`); display and operator surfaces keep it (#2099).
- Absent or malformed settings coerce to the pre-existing behaviour, so an upgrade is byte-identical. The exceptions, each announced, are legacy `llm.pickerAgent: false` → Track Shortlist, the Lyrics panel with its LRCLIB fallback (`settings.lyrics`), which an upgrade turns on, and the `published` day on each dated item from the generated feed tool, which reaches the DJ with no key to set.
- A multi-station switch is a pointer write + mixer restart + controller `process.exit`; never hot-swap state paths in-process.
- A scheduled job deletes only files it wrote itself, matched on an anchored name (`backup/pure.ts`).
- Operator curation outranks listener signal: an operator heart skips the `topLiked` cutoff and survives the trim.
- Listeners never get a skip. `POST /dj/skip` is admin-only, and listener remote controls omit it.