agentleFS
schmugschmug/clodcast/skills/daily-podcast/SKILL.md

daily-podcast

Skill1 starsChanged 3 months agoMITView on GitHub

Use when the user asks to ship a daily digest podcast — turns a list of saved items (URLs / articles) into a fully-produced episode using Qwen3-TTS, a deterministic script template, and publishes it to the show's public RSS feed. Skips the standard production interview because defaults are pre-set.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 8 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never a person's name, and never a first-person human claim: Don't say anyone read, chose or checked these stories by hand — nobody did.

    line 150
  2. Very specific:

    Don't replace the table with arithmetic.

    line 179
  3. Distinctive:

    Never read URLs aloud

    line 196
  4. Distinctive:

    No new facts in any of them, and the same rule as segments: don't tell listeners to check the show notes or description.

    line 225
  5. Distinctive:

    Dry: No exclamation marks, no winking at the listener, no "haha".

    line 244
  6. Distinctive:

    No em dashes — TTS encoding flakes.

    line 256
  7. Very specific:

    Update ~/.config/daily-podcast/voices/house.txt with the exact transcript

    line 418
  8. Very specific:

    On for this show since 2026-09-10: Every manifest carries the music block in the schema above.

    line 480
  9. Distinctive:

    Read that before this audio is distributed anywhere new.

    line 501
  10. Very specific:

    Every key but enabled and asset is optional and defaults to the value above — the reference mix.

    line 531
  11. Distinctive:

    Every music-free show renders at ffmpeg's loudnorm default (about -24 LUFS).

    line 536
  12. Very specific:

    Every deletion is logged (episode_uri + created_at + title) to stdout and recorded under pruned_episodes in runs.jsonl.

    line 730
  13. Very specific:

    save-to-spotify is never invoked: No upload, no timeline set, no readiness poll, no episode-cap capacity check or prune, and no in-flight …

    line 832
  14. Very specific:

    Credentials never go in config.json: Read from env (preferred for cron) or an optional ~/.config/daily-podcast/secrets.json (mode 0600):

    line 895
  15. Very specific:

    Pages deploy hook (optional, independent of the five above): After a successful publish, render.py POSTs PAGES_DEPLOY_HOOK_URL to rebuild …

    line 908
  16. Very specific:

    Create an OAuth client of type Desktop app in a Google Cloud project with the YouTube Data API v3 enabled, download its JSON, then run …

    line 988
  17. Very specific:

    Use Python with feedparser (declared in pyproject.toml).

    line 1050
  18. Distinctive:

    If you cannot find at least 5 items meeting the bar, ship a shorter episode rather than padding.

    line 1073
  19. Very specific:

    Headless (unattended schedule): Use the orchestrator, which gathers + curates deterministically and summarizes each item in its own …

    line 1134

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Daily Podcast

Turn a list of saved items into a finished, published episode in one pass — no interview, deterministic script template, dated cover.

The show is RSS-first: it ships "ship_mode": "web" (#218), so the R2 publish is the ship and save-to-spotify is never invoked. The public channel is cortech.online/podcast/rss.xml, which Spotify and every other directory subscribe to. The CLI-uploaded private show it used to also upload to is retired: it was a second copy nobody could listen to, and at the 60/60 episode cap each run permanently deleted the then-oldest published episode to make room. Nothing here needs save-to-spotify installed or authenticated any more — see Web-only shipping.

Trigger phrases: "ship today's podcast", "make the daily digest", "run the daily routine", "podcast from this list of URLs".

Layout

This skill ships an executable render.py and a headless prompt. References in this document are relative to the skill directory:

  • ./render.py — the manifest → episode driver (audio render, cover, timeline, artifact gate, R2 publish; upload + polling only on a legacy Spotify-mode manifest)
  • ./orchestrate.py — the unattended entry point for scheduled runs (deterministic metadata-only curation + one isolated claude -p per item)
  • ./prompts/daily.md — a stub pointing back here; the unattended procedure lives in Unattended daily run
  • ./blocked_sources.json — outlets that can't be fetched for article bodies, with recovery strategies
  • ./video.py + ./video_frames.py — the post-ship episode video: renders a published episode as a 1080p video and uploads it to YouTube, on its own schedule

Input

Two forms accepted. Both resolve to a manifest.json consumed by render.py.

Form 1 — items list (items.json)

User supplies saved items; this skill writes the script and the manifest.

{
  "date": "2026-05-22",                    // optional; defaults to today
  "items": [
    {"url": "https://example.com/post",    // required
     "title": "Post title",                // optional; falls back to <title> from fetch
     "content": "pre-fetched body text",   // optional; if absent, WebFetch the URL
     "saved_at": "2026-05-22T10:00:00Z"}   // optional, informational
  ]
}

Form 2 — pre-built manifest (manifest.json)

Already-written segments. Skip straight to rendering.

{
  // Lead stories then the date, per "Episode title". Display-only free text: it does
  // NOT key the slug/guid (see "Publishing to the web"), so it is safe to enrich.
  "title": "Mojo goes open source, OpenAI's pause, Cursor vs GitHub - May 22, 2026",
  "summary": "Today's one-sentence hook.",
  "show_id": "spotify:show:...",          // legacy; ignored under ship_mode "web" (this show). Only a Spotify-mode manifest reads it
  "show_name": "Daily Digest",             // optional; overrides config.json's show_name on the COVER only (big title + top label). Set it when rendering a SECOND show — render.py reads one config for every show it renders, so without this its covers carry the daily show's branding
  "cover_image": "/path/to/cover.jpg",     // optional; use this image as the episode cover instead of generating one. Absolute, or relative to the MANIFEST's directory (never the CWD). Must be square, 1400-3000px — pre-flight fails the run otherwise. Set it when a show has DESIGNED art: show_name only changes the name on the generated gradient, which is this show's look
  "date": "2026-05-22",                    // optional ISO date; stamps the cover AND keys the web slug/guid. Omit to use today (re-renders of a dated manifest reproduce its date)
  "voice": "house",                        // default; or "random" / preset name; set voice_instruct for custom VoiceDesign
  "ship_mode": "web",                      // THIS SHOW SETS "web" (#218). Optional key, but the default when absent is "spotify", which uploads through save-to-spotify — see "Web-only shipping"
  "tts_engine": "qwen3",                   // optional; "qwen3" (default), "breeze", "voxcpm2", "zonos2", "chatterbox" or "higgs". Closed whitelist that lives on the manifest like ship_mode — see "TTS engines"
  "description_footer_text": "Sources: …", // optional; replaces the standard credit footer on the episode description (see "Episode description footer"). PLAIN TEXT: render.py escapes it into one <p> and rejects markup. Set it when rendering a SECOND show — the default footer credits the daily show's feeds
  "cast": {"anchor": "Ryan", "skeptic": "Ethan"}, // optional; speaker -> preset name OR {"ref_audio","ref_text"} clip, for multi-voice `lines` segments (see "Multi-voice scenes"). The daily show does not use this
  "music": {                               // THIS SHOW SETS THIS (approved 2026-09-10). Omitting it renders
    "enabled": true,                       //   a music-free episode — not a failure, just a different one.
    "asset": "skills/daily-podcast/assets/music/pixel-window.flac", // relative to the PLUGIN ROOT, never the CWD
    "asset_sha256": "6c643cec1c5bec9a901e2948feb274a315bfa79db1cabe840d0e65e3d2987e2b"
  },                                       // full key list + the treatment: "Intro/outro music"
  "segments": [
    {"title": "Intro",    "text": "Intro segment...",            "source_url": null, "role": "intro"},
    {"text": "Item 1 segment, 600+ chars.", "source_url": "https://...", "source_title": "..."},
    {"title": "Sign-off", "text": "Outro segment...",            "source_url": null, "role": "outro"}
  ]
}

Mark the bookends with role. "intro" on the first segment and "outro" on the last, on every manifest — music or not. It is inert without music and required with it: the mix reads the roles to find where the intro ends and the sign-off begins, and a chapter title cannot serve, because a title is display text a writer may reword (the audition's own timeline called these two chapters Segment 1 and Segment 12). Exactly one of each, first and last; anything else dies at validation rather than guessing.

Every segment needs a chapter name. title is the chapter shown in the public show notes; a segment with neither title nor source_title falls back to a Segment N placeholder that ships to the RSS feed as a real chapter name. A story segment is covered by its source_title; the intro and outro are not, which is why they carry an explicit title here — "Intro" and "Sign-off", the names this show has published since it launched. Omitting them put a placeholder in the show notes of every episode from 2026-08-24 to 2026-09-08 (#96); render.py now warns on one, but the warning is a backstop, not a licence to skip the field.

Workflow

1. Load config           -> ~/.config/daily-podcast/config.json (r2_bucket, r2_public_base_url)
2. Load dedup log        -> ~/.config/daily-podcast/covered.json
3. Filter input items    -> drop URLs already in the log
4. Fetch missing content -> WebFetch for any item without `content`
5. Write script          -> intro + one segment per item + outro; per template below
6. Self-critique pass    -> tighten verbose segments; never reorder
7. Render manifest       -> title per "Episode title"; hand to render.py
8. render.py             -> TTS + concat + loudnorm + cover + artifact gate + R2 publish + Pages deploy hook
9. Update dedup log      -> render.py appends covered URLs with today's date + published mp3 URL
10. Report               -> single line: mp3 URL + voice used + chapter count

Script template

The template is a rotation, not a fixed form. Seventy-six consecutive episodes opened with the same sentence and ran twelve identically-shaped segments; the rotation exists to stop that. Take today's assignments from the date, never at random — a re-run of the same day must rebuild the same episode.

Seed: day = day-of-year of today's date (1-365). Every index below is day modulo the bank size.

Cold open (~350-400 chars, one paragraph)

Bank of five, indexed day % 5:

#ModeDo
0classicThe show's standard line: "Today's digest for [date in long form]. [N] stories today, covering [2-4 word theme list]. Here's the rundown."
1theme-firstName the through-line connecting today's headlines in one sentence, then the date and the story count.
2lead-firstOpen on the single biggest story in one line, then say how many more follow, plus the date.
3number-firstOpen on the most striking concrete figure across today's headlines, then the date and the story count.
4tensionOpen on two of today's headlines that pull against each other, then the date and the story count.

classic stays in the rotation deliberately — the show keeps a recognizable open about one day in five instead of losing its signature altogether. Every mode still states the date and the story count; that is the show's contract with a daily listener, not a stylistic flourish.

The fourth-wall line

Every cold open says, once, that the show is machine-made. It replaces the old "I'm [host_name]" credit, which claimed a person was reading you the news. Nobody is: a scheduled job pulls the feeds, ranks them and writes the script, and a model speaks it. The show states that rather than performing a host.

The angle is assigned, the wording is yours. Take the angle from the bank below, indexed day % 4, and write the line fresh every time — a stock disclosure read every morning stops being information and becomes a jingle.

#AngleDo
0machine-bylineState it as flatly as a wire service states its byline: this episode was assembled by a machine. No apology, no flourish.
1pipelinePoint at the mechanism that produced the episode - feeds pulled, items ranked, the script written overnight - rather than a person who read the news.
2synthetic-voiceAcknowledge that the voice itself is generated, in one clause, then keep moving.
3no-one-hereSay plainly that there is no host in the room: the show exists because a scheduled job ran.

Four angles against the cold open's five modes, so the open's mode and its disclosure cycle together over twenty days instead of pairing off forever.

The rules on it:

  • One sentence, 90 characters at most (FOURTH_WALL_MAX_CHARS), and it lives inside the cold open's own 350-400 band. It is a beat of the open, not an extra paragraph — the stories are what the listener came for. It reads most naturally after the date and the story count and before the hand-off into the first story, classic included: that mode's quoted line is the shape of the open, not the whole of it.
  • Dry, and not a joke. The sign-off's button is where the machine gets the punchline; the open states the fact and moves on. The same joke told at both ends of an episode is a bit.
  • No disclaimer voice. Not "as an AI", not an apology, not a hedge about accuracy. It is a byline, said once.
  • Never a person's name, and never a first-person human claim. Don't say anyone read, chose or checked these stories by hand — nobody did.
  • These three are burned — never ship one: "This digest was assembled by a machine." / "Nobody read these headlines to you; a job did." / "The voice is synthetic, the reporting is not." They calibrate the register, and they are the literal FALLBACK_FOURTH_WALLS in orchestrate.py that a failed writer call falls back to. A line cannot be both the example every writer sees and the day's opening without the show opening the same way forever.

Per-item segments

Each segment gets a shape and a length band, both assigned by its position.

Shape — take today's row from the table below by day % 5, then read the shapes left to right across your segments. Positions past the fifth wrap around and reuse the row.

day % 5pos 0pos 1pos 2pos 3pos 4
0stakes-firstsceneplain-ledecontrastnumber-first
1scenestakes-firstcontrastnumber-firstplain-lede
2plain-ledenumber-firstscenestakes-firstcontrast
3contrastplain-ledenumber-firstscenestakes-first
4number-firstcontraststakes-firstplain-ledescene

What each shape means:

#ShapeOpening
0plain-ledeHeadline framing, then the substance.
1stakes-firstWho is affected and what changes for them, then what happened.
2number-firstThe single most concrete figure - a count, a sum, a version, a share - then what it measures.
3sceneOne concrete detail or a short quoted line from the reporting, then widen to the news.
4contrastThe gap between what was assumed and what this item shows, then the substance.

That table is a Latin square, and both of its properties are load-bearing. Every row is a permutation of the bank, so each shape appears once per five segments. Every column holds each shape exactly once, so no position is starved and no position repeats its shape two days running. The rows are deliberately not rotations of one another — under a plain rotation stakes-first would follow plain-lede in every episode ever made.

Don't replace the table with arithmetic. The first version of this used a stride ((day + i * stride) % 5, stride = 1 + day % 4) and looked correct in a year-long coverage check, but pinned positions 4, 9 and 14 to one shape for four days at a time.

Length band — the lead story gets room, and roughly one non-lead segment in four runs short:

PositionBandRole
0850-1100 charsLead read — the day's biggest story
(day + i) % 4 == 0500-650 charsShort take
everything else600-900 charsBody segment

The band measures the story body, not the body plus its segue. A segue is added on top of whatever the band allows, so a 500-650 short take carrying a 100-character bridge lands near 750 in the finished manifest — that is correct, not an overrun. This is not a stylistic reading: in orchestrate.py the band reaches the item writer through fill_prompt, which fills <<MIN_CHARS>>/<<MAX_CHARS>> in prompts/summarize_item.md, and that writer only ever produces the body; make_transitions prepends the segue afterward in assemble_manifest. Measure the two separately when writing by hand, or every short take comes out starved.

500 is a hard floor, not a target: a body under it reads as filler next to its neighbours and orchestrate.py drops the item outright (MIN_SEGMENT_CHARS, checked on the body before any segue is attached). Short takes are only safe at all because Spotify's sub-30s chapter cap was retired upstream — see Chapter-duration guardrail.

Every segment, whatever its shape:

  • Substance in the middle: what, why, the key detail
  • End on the last sentence of substantive analysis. Never verbally reference the source URL, the show notes, the description, or "the link" — source attribution is handled non-verbally by the per-segment link companion in the timeline and by the timestamped chapter links in the HTML description.
  • Never read URLs aloud
  • One source per segment — strict 1:1 mapping

Segues

A segue names the relationship between two adjacent stories. The old fixed list ("Next up", "Moving on", "Also today") was interchangeable filler — nothing about it could differ from one episode to the next, which is the same failure the shape rotation exists to fix.

The story at position i takes the move at column i - 1 of row (day + 2) % 5 in the same table above. The lead story gets no segue — it follows the cold open, which already set the episode up. The row offset keeps segues off the shapes' row, so a given shape doesn't carry the same segue forever.

#MoveDo
0coldNo connective at all. Hard cut straight into the story.
1pivotName the change of subject in a few words, then go.
2contrastSet this story against the one before it - they point different ways.
3escalateMark that this story raises the stakes on the theme just covered.
4echoMark that this story rhymes with the previous one: same pattern, new actor.

Never manufacture a connection. A digest's adjacent items are often genuinely unrelated. If the assigned move needs a relationship the two stories don't have, write a plain topic change instead — a false link between unrelated news items is worse than a blunt hand-off. One short clause each; these are bridges, not summaries.

Sign-off (~250-300 chars, ending on the button)

Bank of three, indexed day % 3:

#ModeDo
0plainA simple thanks.
1throughlineCall back to the episode's through-line in one clause, then sign off.
2forward-lookOne line on what is worth watching next out of today's stories, then sign off.

No new facts in any of them, and the same rule as segments: don't tell listeners to check the show notes or description.

The button

Every sign-off ends on a button: one dry joke about the host being a machine. It replaces the old "I'm [host_name]" close, which was the one line in the episode that could never differ — and a fiction besides, since nobody is there.

The angle is assigned, the wording is yours. Take the angle from the bank below, indexed day % 5, and write the line fresh every time — this is the one place in the template where the model supplies the novelty rather than the rotation, because a joke a daily listener has already heard is not a joke.

#AngleDo
0machine-admissionAdmit the host is not a person, deadpan, as if it were a scheduling detail.
1aliasIntroduce yourself under an invented model-shaped name - a checkpoint, release or lab codename - in place of a real one.
2idiom-swapTake an everyday sign-off idiom and swap one word of it for machine-learning vocabulary.
3scheduled-returnPromise tomorrow as a job that is already scheduled rather than a person choosing to come back.
4provenanceCredit the episode to the corpus, the context window or the checkpoint rather than to a self.

The rules on it:

  • One sentence, 60 characters at most (SIGNOFF_BUTTON_MAX_CHARS), and it is the last thing in the episode. A button lands; a second sentence explains the joke.
  • Dry. No exclamation marks, no winking at the listener, no "haha". The register is a shrug on the way out the door.
  • Never the host's real name. alias invents one on purpose; the other four don't name anybody. host_name reaches no spoken line in the script, here or in the cold open.
  • No new facts. The button is a joke about the show, never about a story.
  • These three are burned — never ship one: "Still a robot. See you tomorrow." / "I'm preswarm. Check back tomorrow." / "Same weights, different day." They calibrate the register, and they are the literal FALLBACK_BUTTONS in orchestrate.py that a failed writer call falls back to. A line cannot be both the example every writer sees and the day's joke without the show closing the same way forever.

The host's name is never spoken — not in the cold open, not in the sign-off, nowhere. host_name in the config is a WRITTEN credit only: it matches the <itunes:author> the public show page carries, and no part of the script reads it aloud. The show does not pretend a person made it — the open says what did (see The fourth-wall line) and the sign-off closes on the button. Neither names anybody.

Rules

  • Convert relative dates from sources to absolute (today's date is available via the system clock)
  • Strip markdown, code blocks, emoji, hashtags before TTS
  • Numbers under 10 in words; abbreviations expanded ("D R I" not "DRI")
  • "CLAUDE dot md" not "CLAUDE.md"
  • No em dashes — TTS encoding flakes; use hyphens
  • Segues are assigned too — see Segues below. Don't fall back to "Next up / Moving on / Also today"
  • The cold open carries the day's fourth-wall line — see The fourth-wall line above. Never open by introducing yourself as a person
  • The sign-off closes on the day's button — see The button above. Never close on the host's name
  • Vary sentence rhythm inside a segment too: don't open every sentence with its subject, and don't close on a summarizing "ultimately" / "in short" clause
  • This is a news digest. Cover security, breach, and research stories at a reporting altitude — what was disclosed, who is affected, the response. Reporting on a disclosed vulnerability or breach is ordinary tech journalism; cover it confidently. Never write exploit steps, payloads, working commands, or attacker how-to; if an item can't be made substantive without them, it doesn't belong in the episode. (The Unattended daily run curation and fetch steps keep coverage at this altitude; this is the writing-side backstop.)

Defense in depth: render.py validates the manifest structure (failing fast with a per-field message before the model loads) and re-strips TTS-hostile characters from every segment — em/en dashes, smart quotes, code fences + backticks, leading markdown headings, and bare URLs — regardless of what the caller wrote. It does not do the stylistic rules above (numbers-to-words, abbreviation spacing, "CLAUDE dot md") — those stay the writer's job. Set "raw_text": true in the manifest to skip normalization (e.g. text pre-formatted for a different TTS).

Episode description footer

render.py appends one credit paragraph to every episode description, after the timestamped chapter blocks. It is DESCRIPTION_FOOTER in render.py — a constant, not model output. Don't write it into a segment, don't reproduce it in the manifest summary, and don't remove it from a rendered description thinking it is stray text:

<p>Sources: <a href="https://cortech.online/podcast/sources.opml">every feed this show reads</a>, curated in <a href="https://donthype.me">Don&#x27;t Hype Me</a>.</p>

Two things about it are load-bearing:

  • It goes after the chapters, never before. cortech.online's summaryText() keeps only the paragraphs before the first (mm:ss) chapter line and renders them as the website summary. Below the chapters the credit reaches Spotify's show notes in full and the web summary not at all; above them it would leak into every episode summary on the site. It is also why the cap-trimmer pins the footer last instead of treating it as a droppable trailing block.
  • The credit links the product, https://donthype.me — never the repo behind it, which is private and would 404 for every listener.

This is a show-notes line only. Nothing in the audio points at it: the sign-off rule above still stands, so never say "check the show notes" or read the source list aloud.

The credit is per-show (#152): a manifest may set "description_footer_text" to replace it — the default names the daily show's feeds, which is wrong attribution on any other show rendered through render.py. The value is PLAIN TEXT by contract: render.py escapes it and builds the single <p> itself, and the manifest validator rejects any </> (an operator-authored HTML fragment would otherwise land verbatim in public RSS show notes). Links are not supported in a custom footer — per-story links live on the chapter lines. Absent, the default footer above is used, byte-identical. Everything else about the footer — placement after the chapters, pinned last by the cap-trimmer — applies to a custom footer unchanged.

Episode title

The title is display text, never narration — nothing in the audio refers to it. It is also the only thing a browsing listener sees before pressing play, so it names the day's lead stories instead of repeating the date.

Format — 3 topics, then the date:

<topic>, <topic>, <topic> - <Month D, YYYY>

Worked example, for the episode of 2026-08-20 (T-Mobile cutting a cable to evict Salt Typhoon, CareCloud confirming a breach, five federal agencies warning on Siemens controllers):

Salt Typhoon, the CareCloud breach, Siemens PLC warnings - August 20, 2026
  • Topics first, date last. Spotify publishes no maximum length for an episode title; its Podcast Delivery Specification (v1.9, §4.3) says only that consumer-facing elements are truncated at whatever the device can display. The front of the string is therefore the budget that matters — and Daily Digest - August 20, 2026 spent all of it on 30 characters that were byte-identical across all 75 published episodes.
  • The date stays, in long form, matching the cover and the cold open. This is a daily show and a listener orients by date; the RSS <pubDate> alone is easy to miss in a Spotify list view. Putting it last is what makes truncation cost the least.
  • Three topics, from the first three stories in the running order — the ranked lead stories, in that order. Fewer stories than that, name as many as there are.
  • Each topic is a short noun phrase, 2-3 words, naming the subject — the company, product, incident or release — not a sentence and not a whole headline. The band is measured, not guessed: at 2-4 words, three topics plus the date routinely overran the ceiling and the third was dropped, losing a searchable keyword outright.
  • Digits stay digits. The narration rules (numbers under ten in words, spaced abbreviations) exist for TTS; a title is read on a screen, where 3.75 million scans better than three point seven five million.
  • Hyphens, never em dashes, and no emoji or smart quotes — special characters render inconsistently across podcast directories, which is why the public show's own title dropped its em dash.
  • "Report, don't instruct" applies here too (step 5): name the subject, never the technique. Citrix NetScaler emergency patch, not the mechanism of the flaw.
  • 100 characters is the ceiling, and it is a runaway guard rather than a platform limit — three short phrases never approach it. Over it, drop a whole trailing topic; never cut a word in half.
  • With nothing worth naming, fall back to Daily Digest - August 20, 2026 — the title every published episode already carries. A blank title fails validate_manifest and costs the whole episode over a cosmetic field.

Why retitling is safe, and what it cannot reach

The R2 slug and the isPermaLink <guid> built from it come from slug_for_date(<episode date>) alone — see slug is keyed on the date, never the title. Nothing may re-couple them. But the two Spotify surfaces differ, and only one is mutable:

SurfaceTitle comes fromMutable after publish?
Public show (RSS-ingested from cortech.online)title in the R2 manifest.json entryYes — ordinary data, and guid-neutral since #128
Private Save-to-Spotify show (retired, #218)upload --titleNo. Episode metadata is immutable after creation; its back catalogue is frozen under whatever format shipped it

Since #218 nothing new lands on the private show, so the only live surface is the mutable one and a format change is reversible. Still pick one and hold it: a churn of formats reads worse to a browsing listener than one merely-adequate format held consistently. That is also why the title format is deliberately not part of the date-seeded rotation that varies the cold open, the segues and the segment shapes — variety is right for prose, wrong for a name.

In orchestrate.py the composition is episode_title(), and the topic phrases come back from the same claude -p call that writes the intro, sign-off and summary — from titles only, so the one-body-per-request invariant is untouched. TITLE_TOPIC_COUNT, TITLE_MAX_CHARS, the fallback and the worked example above are pinned against this section by test_skill_md_states_the_episode_title_format.

Back-filling the published back catalogue

retitle.py applies this same format retroactively to the public show, by rewriting title on entries already in the R2 manifest.json (#144). It is a maintenance CLI, not part of a run — nothing in the daily pipeline calls it.

python3 skills/daily-podcast/retitle.py                        # review every title
python3 skills/daily-podcast/retitle.py --only <slug> --apply  # canary: one episode
python3 skills/daily-podcast/retitle.py --apply                # the rest

The topic phrases are checked-in data (backfill_topics.json, keyed by published slug), and the title is composed by orchestrate.episode_title — so the back-fill applies this format rather than a second one, and a re-run is idempotent. Dry run is the default; --apply writes the manifest, backs the previous one up under ~/.config/daily-podcast/manifest-backups/, and fires the Pages deploy hook (without which the rewrite stays invisible until the next episode ships, because cortech.online reads the manifest at build time). assert_title_only refuses any write where a field other than title moved or the slug order changed — a manifest that fails the consumer's episodeSchema empties the entire public feed.

Covers are deliberately not regenerated; see the module docstring for why.

Voice selection

The default is the locked house voice — ref_audio cloning from a ~22-second reference clip. The Base 1.7B model regenerates that voice's timbre and prosody for any new text, so the voice stays consistent across episodes.

The bundled default lives at refs/house_voice.{wav,txt} in the skill directory. On the first voice: "house" render, render.py copies it to ~/.config/daily-podcast/voices/house.{wav,txt} and reads from there forever after — so plugin updates can't overwrite a customized voice.

Manifest options:

  • "voice": "house" (default) — Base model + ~/.config/daily-podcast/voices/house.{wav,txt} (seeded from bundle on first run)
  • "voice": "random" — preset rotation over [Ryan, Aiden, Ethan, Chelsie]
  • "voice": "Ryan" (or any preset) — single fixed preset
  • "voice_instruct": "..." — VoiceDesign mode, full override; voice becomes a label

The bundled house clip is one good render of a VoiceDesign instruct (HOUSE_VOICE_INSTRUCT, kept in render.py for reference) — mature female, even prosody, bright but human, not performative. To replace the house voice:

  1. Capture a new ~20-30 second reference clip (any TTS or human recording)
  2. Save it to ~/.config/daily-podcast/voices/house.wav (PCM_16, mono, 24 kHz preferred)
  3. Update ~/.config/daily-podcast/voices/house.txt with the exact transcript
  4. Done — every subsequent voice: "house" render uses the new clip

ref_audio precedence: if voice_instruct is also set in a manifest, the explicit instruct wins (so you can A/B against the house voice without unwiring it).

Report the voice in the final summary so the user knows which one ran.

TTS engines

The engine is a property of the show, chosen by the manifest's tts_engine key (default qwen3); a typo dies rather than falling back, the ship_mode posture. The four voice modes above are unchanged by the engine — it is an orthogonal axis, not a fifth mode — but an engine only renders the modes it declares, and render.py refuses the rest before the model load. Pre-flight prints the engine and its license on every run. This table is pinned to render.ENGINES by a test.

enginemodelcapabilitiestake ceilingmin mlx-audiolicensederailment check
qwen3mlx-community/Qwen3-TTS-12Hz-1.7B-Base-8bitclone, design, presetnone0.4.3Apache 2.0no
breezemlx-community/Breeze-TTS-2-mlx-8bitclone, design, direction, events500 chars0.5.1BreezeBlue Research and Non-Commercialyes
voxcpm2mlx-community/VoxCPM2-8bitclone, designnone0.4.4Apache 2.0yes
zonos2mlx-community/Zyphra-ZONOS2clone500 chars0.4.5Apache 2.0yes
chatterboxmlx-community/chatterbox-multilingual-v3clone500 chars0.4.7MITyes
higgsbosonai/higgs-tts-3-4bclone, events500 chars0.4.4Boson Higgs Audio v3 Research and Non-Commercial, with a creator-use grantyes
  • qwen3 designs on a second model (VoiceDesign-bf16); breeze designs on the same model it clones with, so a Breeze episode always pays one load.
  • breeze has no presets: voice: "random", a preset name, or a preset cast entry dies naming the engine. Clones (house, cast clips) and voice_instruct work.
  • The 500-character ceiling is Breeze's own, not the token cap. Measured 2026-09-04: 0 of 24 takes at or under 533 characters derailed; 1 in 5 did at 592–1000. The ceiling binds one take, and a plain-text segment over it is rendered as several: render.py splits it at sentence boundaries into chunks of balanced size (an 1100-character lead becomes three takes of ~370, never 500 + 500 + 100), renders each, and joins them with CHUNK_GAP_MS (350 ms) of silence into the same seg_NN.mp3 — one chapter, one source_url, chapter math untouched. Never mid-sentence: a single sentence over the ceiling dies before the render, naming it. Every band this show writes therefore renders on breeze; a scene line is still one take and is bounded whole.
  • An engine with a derailment check transcribes every take it renders (detect_derailment on the engine; breeze today). The speech-rate gate cannot see a derailment — the rate stays normal and whisper hears babble as words — so the take is judged by the eval bench's rule instead: WER > 0.15 against the script, non-ASCII in the transcript, or a heard-to-script word ratio outside 0.9–1.1. A derailed take is banked to the bloopers bin first, then re-rolled once; a second derailment leaves the take without a cache sidecar and the artifact gate refuses the run, so re-running with the same --workdir re-rolls only that take. --dry-run runs the check and the re-roll but banks nothing. The rule is coarse on a short take (one misheard word in fourteen is already over the threshold), which is why chunks are balanced rather than tail-heavy. Needs mlx-whisper (the bench extra); pre-flight (derailment-detector) fails the run without it, and the whisper model loads once per run.
  • events: (laugh) / (sigh) in a take's text (render.EVENT_MARKERS, a closed list) are performed by an engine that declares it. On one that does not, render.py strips them from the take before the render and logs it — never refuses, a stripped marker is the same line — and every measurement (a scene's derived text, the speech-rate rows) reads the marker-stripped text on every engine, so an event never lengthens the measured script (#201). Paralinguistic markers still do not work on qwen3; they simply never reach it.
  • direction: a scene line may carry "instruct", rendered through the clone-plus-instruct form (generate(text, ref_audio, ref_text, instruct=…, cfg_scale=4.0)) and folded into that take's cache key. On an engine without it the line is refused naming the engine, never stripped — a dropped direction is a different performance. It is an instruction over a clone, so a preset speaker cannot be directed. See Multi-voice scenes.
  • Breeze's weights are non-commercial with no creator or monetization exception: no sponsor reads or paid tiers on a show that renders with it.
  • voxcpm2, zonos2 and chatterbox were registered for the 2026-10-11 engine evaluation; no show selects them. All three clone from the clip (only voxcpm2 uses its transcript, as a continuation prompt), none has presets, events or direction, and only voxcpm2 designs a voice (on its base model). Their audio comes out at 48, 44.1 and 24 kHz; render.py writes each take at the engine's declared rate and dies if the loaded model reports another. The zonos2 and chatterbox ceilings keep a take well inside each model's token cap, not a measured derailment point.
  • higgs (Higgs Audio v3) was added to the same evaluation. It clones from the clip and its transcript, and performs (laugh) / (sigh) as its own inline sfx tags (with a "Haha," / "Haah," attached, which a transcript will hear). It ends a take at about 24 s on its own, so its 500-character ceiling is the bench corpus's floor rather than a clean point. Its weights are non-commercial except under Boson's creator-use grant, which requires crediting Higgs Audio on every episode and keeping consent records for any cloned voice.

Multi-voice scenes (lines)

A segment may carry a lines array instead of text, so one scene can hold several speakers (#172). The daily show does not use this — it exists for multi-voice shows rendering through the same render.py.

"cast": {"anchor": "Ryan", "advocate": "Aiden", "skeptic": "Ethan", "switchboard": "Chelsie"},
"segments": [
  {"source_url": "https://...", "source_title": "...", "lines": [
    {"speaker": "anchor",  "text": "Sets up the post."},
    {"speaker": "skeptic", "text": "Names what is unsupported."}
  ]}
]

The rules, all enforced by validate_manifest:

  • text and lines are mutually exclusive. A scene's text is derived from its line texts and materialized before anything measures the segment — that is what keeps the speech-rate gate and the bloopers bin armed, since a zero-char segment is skipped as unmeasurable. An author-written text beside lines is a malformed manifest and dies naming both fields.
  • speaker is a role, not a voice. It resolves through the manifest's cast, whose values are either a bundled preset name (Ryan / Aiden / Ethan / Chelsie) or a recorded clip {"ref_audio": "<abs path>.wav", "ref_text": "<its exact transcript>"} (#177). Both run on the base model, so a mixed cast still pays one model load. This is not a fifth voice mode — the four-mode precedence above governs the EPISODE voice and is unchanged — and it means recasting a role is a manifest edit, not a script edit.
  • A cast cannot share an episode with voice_instruct where design is a SEPARATE model (qwen3). VoiceDesign there is a second model and it drifts; the cast runs on the base model, so the combination dies. On breeze, which designs on the model it clones with, a designed narrator and a cloned cast are one load and the combination is allowed (#201). voice: "house" (clone) is fine everywhere — same base model, one load.
  • A line may carry instruct (#201). {"speaker": "skeptic", "text": "...", "instruct": "Plainly exasperated, but keeping composure."} renders that one take through the engine's clone-plus-instruct form. Only on an engine with direction, and only for a clip-cast speaker; refused otherwise, naming the engine. The instruct is part of the take's cache key — an undirected line's key is unchanged — so redirecting one line re-renders that line alone. The episode's voice_instruct designs a voice from nothing; a line's instruct tells a clone how to deliver one turn.
  • One scene is still one chapter with one source_url. Lines render to line_NN_LL.mp3 and join into the same seg_NN.mp3 a single-voice segment produces, separated by TURN_GAP_MS (250 ms) — a turn gap, unrelated to the 800 ms between chapters and to the 5 s chapter-spacing floor. Everything downstream is untouched.
  • Caching is per line. Rewriting one line re-renders that line, not the scene; a fully cached re-run still skips the model load.
  • A cast clip is keyed by its BYTES. Re-recording one member's clip, or pointing a member at a different one, re-renders that member's lines and leaves the rest cached. Without that the run would quietly replay the old voice's audio under the new one's name — right text, right length, wrong person — so a clip entry is never cached on its path alone.

Chapter-duration guardrail

Spotify requires consecutive chapter starts to be at least 5 seconds apart (the final chapter is exempt). That is the only platform rule on chapter length, and no real segment comes close to violating it — render.py pads trailing silence only if a segment is short enough to breach the 5s floor.

Chapters under 30 seconds used to be capped at 3 per episode, and render.py padded up to 12s of silence to comply. Upstream dropped that cap (save-to-spotify PR #44), verified 2026-08-22 against CLI 0.2.0. Short segments no longer risk the episode, so the 600+ chars-per-segment target is now editorial pacing, not a platform constraint.

Intro/outro music

On for this show since 2026-09-10. Every manifest carries the music block in the schema above; the theme is Pixel Window. It stays optional in the renderer and off for every other show that does not ask — absent the key, an episode renders byte-for-byte as it did before the feature existed, including its loudness target.

Two treatments, one implementation. mode is a closed whitelist. "bed" (the default, below) is for a loopable theme; "sting" is for a short signature that never overlaps speech — it plays once before narration and once after the sign-off, with de-click edge fades, and its lead_seconds/tail_seconds default to the asset's own measured length. Frontier Commits uses sting for its one-bar Midnight Terminal; see that skill. Both resolve into the same mix plan and the same filter graph, so neither is an untested half. A one-bar asset must not use bed — looping a single bar under a whole introduction is a stutter, not a theme.

The bed treatment. One bar of theme alone before the host; the theme ducked to -18 dB under the intro segment and faded out over the three seconds before the first story; no music at all under the stories; the theme back at -18 dB under the sign-off, rising to full over two seconds once the speech ends; a two-bar finish fading out over its last three seconds. The shipped theme is Pixel Window (skills/daily-podcast/assets/music/pixel-window.flac, 78 BPM, eight bars) — its composition source and its unresolved sample licensing are recorded in assets/music/PROVENANCE.json. Read that before this audio is distributed anywhere new.

Where the switch lives. The manifest is what the renderer reads, so the block in the schema above is the live setting. ~/.config/daily-podcast/config.json carries the same block for orchestrate.py, which resolves it and writes the fully-defaulted object into every manifest it assembles. To turn music OFF, drop the key from the manifest (and from config.json); nothing else changes. The full shape:

"music": {
  "enabled": true,                              // false or absent = no music, no behavior change
  "mode": "bed",                                // default; "sting" for a short non-overlapping
                                                //   signature (Frontier Commits). Closed whitelist
  "asset": "skills/daily-podcast/assets/music/pixel-window.flac",     // RELATIVE PATHS RESOLVE AGAINST skills/daily-podcast/,
                                                //   never the working directory - the scheduled run
                                                //   executes from a version-keyed plugin cache
  "asset_sha256": "6c643cec...",                // optional; pre-flight fails the run if the file's
                                                //   bytes have changed. Record it.
  "lead_seconds": 3.076923076923077,            // one bar at 78 BPM
  "tail_seconds": 6.153846153846154,            // two bars
  "duck_db": -18.0,                             // how far the bed drops under speech
  "intro_fade_seconds": 0.08,                   // the theme's fade-in at t=0
  "outro_fade_seconds": 1.5,                    // the theme's fade-in under the sign-off
  "music_lufs": -23.0,                          // the bed is normalised to this BEFORE ducking, so
                                                //   duck_db means the same thing for any source file
  "output_lufs": -19.0,                         // the finished episode's target
  "true_peak_db": -2.0
}

Every key but enabled and asset is optional and defaults to the value above — the reference mix. Unknown keys die: a typo'd duck_dB that fell through to the default would ship a balance the operator believes they tuned.

output_lufs is the one number that changes the master, and only in bed mode. Every music-free show renders at ffmpeg's loudnorm default (about -24 LUFS); a bed episode renders at -19. Sting mode defaults to -24 — the same default — because a sting sits beside the narration rather than under it, so there is no reason to move a show's loudness to play one. That louder target is a property of the music config and reaches nothing else. A rehearsal on 2026-09-10 measured -18.85 LUFS / -2.0 dBTP / LRA 3.3.

What music does NOT touch. The per-segment seg_NN.mp3 files, and therefore the speech-rate gate, the bloopers bin, and the derailment detector — all of which measure speech, not the master. plan_silences and the 5-second chapter-gap rule are unchanged. The mix is one extra ffmpeg pass folded into the loudnorm that already ran, so it costs no additional lossy encode.

Timeline. Chapter one starts at 0 and contains the theme; every later chapter and every source link shifts by exactly lead_seconds. The bookend positions the audio uses are read off the same segment geometry the timeline walks, so the two cannot disagree. The artifact gate re-checks the finished duration against the plan within 250 ms.

Changing the asset or any number re-mixes, and keeps the speech. A re-run in the same workdir compares <workdir>/music.json against this run's config and asset bytes; on a difference it discards the bed, the assembled audio, the timeline and the description, and drops those stages from state.json. The TTS takes are never touched — they cost minutes and are valid whatever the music does.

If the asset is missing, moved, or not the file the manifest recorded, the run fails at pre-flight (music-asset), under --dry-run too. An episode that was asked for music and published without it is a silent failure; this is the last cheap place to catch one.

Show + dedup config

Since #218 this show ships web-only, which moves two keys across the required line and makes five others inert:

  • r2_bucket + r2_public_base_url are now load-bearing, not optional. R2 is the only channel, so an absent pair fails pre-flight (and --selftest) instead of quietly disabling a bonus feed.
  • show_id, auto_prune_episodes, max_prune_per_run, episode_cap and poll_timeout_s are ignored on every run. They are Spotify-upload settings and nothing invokes the CLI any more.

No config change is required to land the flip, and none was made — this is a code change only. The deployed ~/.config/daily-podcast/config.json already carries r2_bucket: "clodcast" and r2_public_base_url: "https://clodcast.cortech.online" (verified 2026-09-08), which is everything web mode needs. It also still carries show_id, auto_prune_episodes: true and max_prune_per_run: 1; all three are now dead weight and can be deleted whenever convenient. Deleting them is optional cleanup, not a step — auto_prune_episodes in particular is no longer dangerous because nothing reaches the code that reads it, and keeping show_id is what a legacy "ship_mode": "spotify" manifest would still read.

// ~/.config/daily-podcast/config.json
{
  "show_id": "spotify:show:...",       // legacy; ignored under ship_mode "web" (#218)
  "show_name": "Daily Digest",         // rendered onto every generated cover unless
                                       //   a manifest overrides it (a second show
                                       //   sets its own; see the manifest schema), so a
                                       //   change here splits the catalogue's art;
                                       //   the public show is now "Cortech Daily"
                                       //   and this has NOT been renamed to match
                                       //   - that decision is issue #133.
  "host_name": "Schmug",               // WRITTEN credit only - never spoken. The cold
                                       //   open breaks the fourth wall (see "The
                                       //   fourth-wall line") and the sign-off closes
                                       //   on a button (see "The button"), so no part
                                       //   of the script reads this aloud. Matches the
                                       //   public show's <itunes:author>/<itunes:owner>
                                       //   credit; nothing derives a slug or filename
                                       //   from it.
  "opml_files": ["/path/to/feeds.opml"], // optional; used by the unattended run
  "lookback_hours": 24,                  // optional; default 24
  "target_item_count": 10,               // optional; default 10
  "music": {                             // optional; ABSENT = no music, no behavior change.
    "enabled": true,                     //   orchestrate.py resolves this (filling every
    "asset": "skills/daily-podcast/assets/music/pixel-window.flac", //   default) into the manifest it assembles, so
    "asset_sha256": "6c643cec..."        //   a manifest reproduces its own mix. Full key list
  },                                     //   and the treatment: "Intro/outro music" above.
  "auto_prune_episodes": false,          // INERT under ship_mode "web" (#218). Spotify-only:
                                         //   when true, an upload that hits the show's
                                         //   episode cap (429 RATE_LIMIT_EXCEEDED /
                                         //   capacity) prunes the oldest episode(s) and
                                         //   retries the upload once.
  "max_prune_per_run": 1,                // INERT under ship_mode "web". Spotify-only ceiling
                                         //   on how many episodes an auto-prune may delete
                                         //   per run. <= 0 is refused (no prune). Deleting a
                                         //   published episode is irreversible.
  "episode_cap": 60,                     // INERT under ship_mode "web". Spotify-only; the
                                         //   count pre-flight compares against before the
                                         //   render so a cap 429 never costs a TTS pass.
  "poll_timeout_s": 1800,                // INERT under ship_mode "web" (nothing polls). How
                                         //   long to wait for Spotify processing. The old 600
                                         //   expired while an episode was still PROCESSING.
  "r2_bucket": "clodcast",               // REQUIRED under ship_mode "web" — this is the ship
  "r2_public_base_url": "https://audio.cortech.online"  // REQUIRED; public URL for <slug>.mp3
}

Two more append-only logs live beside covered.json and runs.jsonl:

  • rejections.jsonl — artifacts Spotify rejected server-side, keyed by sha256. The artifact gate refuses to re-upload identical bytes; see rejected-artifact.md.
  • incidents/new/ — structured reports written on any non-clean exit (DAILY_PODCAST_INCIDENT_DIR overrides the location, and moves both halves of the queue with it). incidents/handled/ is the other half: triage.py resolve moves a report there once it has been dealt with, so new/ stays a work queue. A move, never a delete — see Incident reports.

Bloopers bin (bloopers/)

An archive of TTS clips worth keeping, written as a side effect of paths that already exist. Nothing in a run ever reads it back — it is write-only until a meta-episode is cut from it by hand. Clips are content-addressed under bloopers/clips/<sha16>.mp3; bloopers/index.jsonl is append-only with one full-key-set row per clip (same line-by-line read contract as runs.jsonl).

reasonFires whenBanks
gatethe artifact gate is about to reject a segment (< MIN_SPEECH_RATE_RATIO)that one segment, with the rate evidence
near-missa segment PASSED but reads slow (MIN_SPEECH_RATE_RATIO–NEAR_MISS_RATE_RATIO)that segment; the episode still ships
derailedthe transcript check flags a take, on an engine that declares it (breeze)that take, before it is re-rolled; the note carries the reasons and what whisper heard
run-failedany run dies after TTSevery seg_*.mp3 in the workdir
manualyou run bloopers.py markan ffmpeg trim of any audio file

Five things here are load-bearing:

  • A derailed take is banked BEFORE it is re-rolled. The re-render overwrites the take's mp3 in place, so the copy has to happen between judging the take and rendering it again — no branch in between, the same rule as the gate capture.
  • Capture runs BEFORE verify_artifact, not after. A speech-rate rejection's documented recovery deletes the offending seg_NN.mp3, and a stale workdir empties itself within days — so anything measured after the die() is already unrecoverable. No branch may be introduced between the measurement and the copy.
  • The run-failed sweep is suppressed on a speech-rate rejection. The gate trigger has already banked the precise offender; sweeping too would bank the eleven clean segments beside it and bury the one clip worth keeping. Every other failure identifies no segment, so there the sweep is the only thing that saves the audio.
  • Capture is best-effort and never changes a run's exit code — the same contract as write_run_log and the incident reports. A full disk loses a joke, not an episode. --dry-run banks nothing and logs what it would have banked.
  • Clips are content-addressed, so a same-day resume (which re-runs the gate against a cache-hit segment) is a no-op rather than a duplicate.

Most failures are upload/poll problems whose audio is perfectly fine, so the bin deliberately fills with non-bloopers; reason is what keeps them siftable:

# what is actually worth listening to
jq -r 'select(.reason!="run-failed") | [.reason,.segment,.note] | @tsv' \
  ~/.config/daily-podcast/bloopers/index.jsonl

# how much material is banked, in seconds
jq -s 'map(.duration_ms // 0) | add / 1000' ~/.config/daily-podcast/bloopers/index.jsonl

# bank a clip you heard yourself (works on a workdir segment, an episode.mp3, or
# a feed episode you downloaded)
python3 bloopers.py mark --from episode.mp3 --start 4:12 --end 4:58 --note "birdsbirdsbirds"
// ~/.config/daily-podcast/covered.json — written by render.py only after the ship
// succeeds: the R2 publish under ship_mode "web" (#218), poll_ready READY on a
// Spotify-mode manifest. Pruned to a 180-day retention window on each write (the
// `date` field drives this); entries with a missing/malformed `date` are kept.
// `episode_uri` holds the published mp3 URL on a web-only ship and a
// spotify:episode: URI on a Spotify one — entries written before the flip keep the
// URI they were written with and are never rewritten.
{
  "https://example.com/post-1": {"date": "2026-09-08", "episode_uri": "https://clodcast.cortech.online/daily-digest-september-8-2026.mp3"},
  "https://example.com/post-2": {"date": "2026-05-21", "episode_uri": "spotify:episode:..."}
}

~/.config/daily-podcast/inflight.json is a transient crash-recovery record (an episode that uploaded but hasn't reached READY+dedup yet) — written after upload() succeeds and cleared after dedup. A web-only run never writes it (#218): nothing uploads, so nothing is ever left in flight. It is not a second dedup source; covered.json stays authoritative. See Automatic cron recovery below.

Episode-cap auto-prune (auto_prune_episodes) — Spotify mode only

Inert for this show since #218. Nothing below runs under "ship_mode": "web": there is no upload, so there is no cap and no prune. It is documented because the Spotify path stays implemented for a manifest that selects it — and because this mechanism is why the flip happened. The show sat at 60/60 with auto_prune_episodes: true, so every run permanently deleted the then-oldest published episode (~29 gone by 2026-08-22, #104). Retiring the upload is what stopped that clock.

A Spotify show has a hard episode cap. When upload() hits it, save-to-spotify returns a 429 with error_code: RATE_LIMIT_EXCEEDED / reason: capacity. By default render.py fails with that structured reason (so it's distinguishable from a transient upload flake, which surfaces the same non-zero exit). Set auto_prune_episodes: true to have the renderer instead delete the oldest episode(s) and retry the upload once. Deleting a published episode is irreversible, so the prune is deliberately conservative:

  • Bounded by max_prune_per_run (default 1; <= 0 is refused).
  • Tiered selection: FAILED episodes first (they count against the cap but have no playable audio), then oldest by created_at. An in-flight NOT_READY episode is never selected, and an episode with a missing/malformed created_at is skipped rather than assumed oldest.
  • Scoped to the configured show_id; never touches this run's own or a concurrent run's just-created episode.
  • --dry-run deletes nothing — it logs what it would delete.
  • Every deletion is logged (episode_uri + created_at + title) to stdout and recorded under pruned_episodes in runs.jsonl.

covered.json is intentionally left unchanged when an episode is pruned: its entries would point at a now-dead episode_uri, but dedup only needs "don't re-cover this URL", which stays correct.

Run log (across-runs observability)

Every render.py run appends one JSON record to ~/.config/daily-podcast/runs.jsonl — on success, on --dry-run, and on failure. Append-only (never rewritten); one line per day, so retention is the operator's job. Each record carries a stable key set (missing values are null, never absent) so the file parses cleanly line-by-line in jq/pandas:

// ~/.config/daily-podcast/runs.jsonl — one line per run
{
  "timestamp": "2026-06-03T06:00:12+00:00",  // ISO 8601 UTC
  "status": "ready",                         // "ready" | "web-ready" (#155) | "dry-run" | "failed"
  "episode_uri": "spotify:episode:...",      // null unless ready; always null on a web-only ship
  "title": "Mojo open source, OpenAI's pause, Cursor vs GitHub - June 3, 2026",
  "voice": "house", "voice_mode": "clone",
  "chapter_count": 6, "duration_s": 412.3, "segment_count": 6,
  "workdir": "/var/folders/.../T/daily-podcast-xxxx",
  "manifest_path": "/tmp/manifest.json",
  "error_message": null,                     // the die() message on failure
  "git_sha": "ea5e845",                      // of render.py (mtime fallback off-git)
  "loudnorm": {"input_i": -19.4, "output_i": -16.0, "output_tp": -1.5, "output_lra": 6.9},
  "pruned_workdirs": null,                    // {count, freed_bytes} when --prune-workdirs ran
  "r2_status": "published",                   // "published" | "skipped" | "failed" or null pre-publish (#48)
  "resumed": false,
  "mp3_url": null,                            // public R2 URL on a web-only ship, else null (#155)
  "bloopers_captured": 0,                     // clips banked into the bloopers bin this run (#169)
  "untitled_segments": [],                    // 1-based segments that fell back to a "Segment N"
                                              // chapter (#96); [] = checked and clean, null = not reached
  "music": null                               // {asset, asset_sha256, lead_ms, tail_ms, duck_db,
                                              // output_lufs} when a mix ran; null on every
                                              // music-free run - see "Intro/outro music"
}

Sample queries:

# Every failure and its error
jq -r 'select(.status == "failed") | "\(.timestamp)  \(.error_message)"' ~/.config/daily-podcast/runs.jsonl
# Loudness drift over time (Spotify targets -16 LUFS)
jq -r 'select(.loudnorm) | "\(.timestamp)  \(.loudnorm.output_i)"' ~/.config/daily-podcast/runs.jsonl
# Which voice ran each day
jq -r '"\(.timestamp)  \(.voice) (\(.voice_mode))"' ~/.config/daily-podcast/runs.jsonl
# Episodes that published a "Segment N" placeholder chapter (#96)
jq -r 'select(.untitled_segments != null and (.untitled_segments | length) > 0)
       | "\(.timestamp)  \(.title)  segments \(.untitled_segments)"' ~/.config/daily-podcast/runs.jsonl
# Which episodes shipped with music, and at what balance
jq -r 'select(.music) | "\(.timestamp)  \(.music.asset)  duck \(.music.duck_db)dB  \(.music.output_lufs) LUFS"' ~/.config/daily-podcast/runs.jsonl

First run with no config.json: ask the user for the R2 bucket and public base URL to publish to, then persist the choice. A show_id is no longer part of setup — nothing uploads (#218).

Publishing to the web (Cloudflare R2)

The ship for this show (#218) and every other one; on a legacy "ship_mode": "spotify" manifest it is instead optional and additive, running after the upload reaches READY. Either way render.py publishes each finished episode to a Cloudflare R2 bucket:

  • <bucket>/<slug>.mp3 — the episode audio (publicly fetchable at r2_public_base_url)
  • <bucket>/<slug>.jpg — the cover (best-effort)
  • <bucket>/manifest.json — a newest-first array of episode entries, capped at 200, conforming to cortech.online's episodeSchema. cortech.online reads this at build time and renders /podcast/ plus an iTunes RSS feed at /podcast/rss.xml.

A manifest may set an optional "r2_manifest_name" — a bare filename matching [A-Za-z0-9._-]+\.json (no path separators; anything else fails validation) — to route its entry into a differently-named manifest object in the same bucket. This is how a second show sharing the bucket keeps its web feed out of the daily show's manifest.json. Unset means manifest.json; episode and cover object keys are unaffected either way.

Episode and cover keys have their own optional "r2_key_prefix" — a bare prefix matching [A-Za-z0-9._-]+ with an optional trailing / (no paths, no dot-only values; anything else fails validation) — prepended to the <slug>.mp3/<slug>.jpg object keys and to the mp3_url/cover_url the web-feed entry advertises. The slug is date-keyed, so two shows publishing the same day into the shared bucket would otherwise mint identical keys and the later publish would overwrite the earlier show's objects (#142). Unset means no prefix — the daily show's keys byte-identical to before. The slug field itself (the permalink guid) is never prefixed.

The slug's own literal is per-show: an optional "slug_prefix" — lowercase kebab matching [a-z0-9]+(-[a-z0-9]+)*, at most 62 chars; anything else fails validation — replaces the historical daily-digest literal in <slug> (#162), so a second show's permalinks and guids stop carrying this show's name. Unset means daily-digest and every published daily slug stays byte-identical. The slug remains keyed on the date alone (#128): the prefix swaps a literal and can never re-couple the slug to the title.

Web-only shipping ("ship_mode": "web")

A manifest may set "ship_mode" to "spotify" (the default when the key is absent) or "web"; anything else fails validation, because falling back to the default on a typo would upload an episode that was never meant to reach Spotify.

"web" inverts the relationship above — the R2 publish stops being additive and becomes the ship itself (#155). Every show now ships this way, this one included (#218); the RSS-first Frontier Commits and Surface Tension shows were built on it and the daily show was flipped onto it:

  • save-to-spotify is never invoked. No upload, no timeline set, no readiness poll, no episode-cap capacity check or prune, and no in-flight reconciliation (nothing is ever left in flight). show_id is not required and is ignored.
  • Pre-flight runs the local subset plus R2, and R2 is REQUIRED. The three-state credential check's absent — a pass on the default path, where the web feed is optional — is a failure here, so a misconfigured host fails in seconds instead of after a full TTS render.
  • verify_artifact still gates the publish, exactly as it gates the upload.
  • covered.json is written only after the publish succeeds. Same only-after-success posture as the default path, with the publish as the success condition; a failed publish fails the run and leaves those URLs in the pool. The dedup entry records the published mp3 URL in place of an episode URI.
  • The run-log record uses "status": "web-ready" and fills mp3_url (null on every Spotify-path record). The final JSON on stdout carries mp3_url instead of episode_uri.

--dry-run behaves the same as it does anywhere else: it renders, runs the artifact gate, previews the R2 URL, and publishes nothing.

slug is keyed on the date, never the title

slug comes from slug_for_date(<episode date>) alone — the manifest title is display-only free text and cannot reach it. This is not cosmetic: cortech.online republishes /podcast/<slug>/ as an isPermaLink <guid>, and Spotify treats a changed guid as a brand-new episode, so every published slug is immutable in practice. Coupling the two (as slugify(title, date) used to) meant rewriting a title silently duplicated the whole back catalogue. Keep them decoupled: enrich titles freely, and never derive the slug from anything but the date.

The slug's shape (daily-digest-august-23-2026) is a compatibility artifact — it reproduces the slugs minted from the old date-only titles, hence the historical daily-digest- prefix, the unpadded day, and the year. tests/data/published_slugs.tsv pins every live slug byte-for-byte; append to it, never edit it. The daily-digest literal is only the default slug_prefix (#162) — a second show swaps the literal, nothing else about the shape. The date resolves the same way resolve_pubdate does (explicit manifest date wins), so a back-fill re-render reproduces its historical slug and upserts the same R2 object instead of minting a second one. --dry-run prints the URL through the same resolver the real publish uses, so the rehearsal is exact.

Each manifest entry carries both a Spotify-flavored description (HTML — <p>summary</p>, one timestamped <p>… - <a>source</a></p> per chapter, then the credit footer — see Episode description footer) and a clean summary field (#45) so web/RSS consumers can render prose without HTML-stripping the description. summary is HTML-by-contract (the user authored it), so a consumer should still escape it as untrusted text rather than trusting it as guaranteed-plain. description and chapters[] are unchanged — the summary field is purely additive.

Read this section in Spotify mode only. It describes the additive publish that a "ship_mode": "spotify" manifest performs. Under "web" — what this show ships (#218) — the publish is the ship and its failure fails the run; Web-only shipping is the authority there. The object layout, slug rules, manifest entry shape, and credentials below are shared by both modes.

On the Spotify path this is strictly additive: Spotify is the canonical artifact. A publish never fails the run, changes the exit code, or rolls back covered.json. The final JSON line reports a 3-state "r2_status" (#48): "published" (uploaded), "skipped" (R2 not configured — a benign no-op), or "failed" (configured but the upload errored — the alarming case an operator should notice; the episode is still live on Spotify). --dry-run skips the publish and prints where it would have gone (r2_would_publish).

Credentials never go in config.json. Read from env (preferred for cron) or an optional ~/.config/daily-podcast/secrets.json (mode 0600):

export R2_ACCESS_KEY_ID=...      # R2 API token access key
export R2_SECRET_ACCESS_KEY=...  # R2 API token secret
export R2_ACCOUNT_ID=...         # Cloudflare account ID (the R2 S3 endpoint host)
# optional: export PAGES_DEPLOY_HOOK_URL=...  # POSTed after publish to rebuild the site

r2_bucket / r2_public_base_url live in config.json (or R2_BUCKET / R2_PUBLIC_BASE_URL env overrides). All five must resolve or the publish no-ops.

Pages deploy hook (optional, independent of the five above). After a successful publish, render.py POSTs PAGES_DEPLOY_HOOK_URL to rebuild the site. It resolves first-non-empty-wins across three homes: env → secrets.json ("PAGES_DEPLOY_HOOK_URL") → config.json ("pages_deploy_hook_url"). A scheduled (launchd/cron) run never inherits the interactive shell env, so the durable home is secrets.json (0600) — also preferred because the URL can trigger builds; config.json is the shareable-file convenience. Unset everywhere → no hook fired (the pre-existing behaviour). --dry-run never fires it.

Resume note: the R2 publish runs on both the fresh run and the --workdir resume path (_resume). A resumed episode (e.g. one that first failed at poll_ready and was recovered) is back-filled to R2 too, so it still lands on the web feed (#40). Resume stays config.json-free: it resolves R2 config from env / secrets.json only (never load_config), and the publish is additive + non-fatal exactly as on the fresh path. (An older workdir from before this change that lacks description.html degrades to a skipped back-fill rather than aborting the resume.)

Episode video (YouTube)

A published episode can also ship as a 1080p video — an audio-reactive spectrum ring and waveform halo, a chapter card per story whose headline "decrypts" in, word-by-word captions, a glitch cut on every story change, and a chapter-ticked progress bar — uploaded to YouTube with chapters, a caption track and a thumbnail.

It is a post-ship step with its own schedule, never part of the audio run. The audio is the product and R2/RSS is its ship; nothing in the Unattended daily run calls it and its outcome cannot change that run's SHIPPED line. video.py reads what the run already published — the public feed manifest, whose chapters carry millisecond starts — so it needs no workdir, no manifest and no Claude credential.

python3 video.py --pending                    # recent published episodes without a video
python3 video.py --slug <slug>                # one episode: explicit back-fill / re-render
python3 video.py --slug <slug> --no-upload --out ~/Movies/ep.mp4   # render only
python3 video.py auth --client-secrets client_secret.json          # one-time OAuth

launchd/com.cortech.clodcast-video.plist runs --pending at 09:30 and 18:30. It is safe to run as often as you like: the ledger decides what is already on the channel.

Config (video in config.json)

Absent or "enabled": false means off — --pending prints VIDEO disabled and exits 0. Unknown keys and an unknown privacy_status die: a typo in the key that decides whether an episode goes public must never fall back to a default.

  "video": {
    "enabled": true,
    "captions": true,          // transcribe for burned-in captions + the caption track
    "lookback_days": 3,        // --pending only considers episodes this recent
    "max_per_run": 1,          // ...and at most this many per invocation
    "show_name": "Cortech Daily",  // the name on screen and in the description: the
                                   //   RSS feed's, NOT config.json's cover label (#133)
    "monogram": "CT",          // the disc at the centre of the ring
    "jobs": 0,                 // render processes; 0 = one per CPU, max 8
    "page_base_url": "https://cortech.online/podcast/",
    "feed_url": "https://cortech.online/podcast/rss.xml",
    "youtube": {
      "enabled": true,         // false = render only, never upload
      "privacy_status": "private",   // private | unlisted | public
      "category_id": "28",           // Science & Technology
      "tags": ["Cortech Daily", "tech news", "cybersecurity", "AI"],
      "playlist_id": null,           // e.g. the channel's podcast playlist
      "caption_track": true,
      "thumbnail": true
    }
  }

privacy_status defaults to private, and that is not only caution: YouTube locks every video uploaded by an unverified API project to private regardless of what the request asks for. Until the Google Cloud project passes YouTube's API audit, publish by flipping the video to public in YouTube Studio. containsSyntheticMedia is always sent true: the house voice is a realistic synthetic clone, which is exactly what YouTube's altered-or-synthetic-content disclosure is for.

YouTube credentials

Create an OAuth client of type Desktop app in a Google Cloud project with the YouTube Data API v3 enabled, download its JSON, then run video.py auth --client-secrets <file> once, on the Mac, in a browser. It stores YOUTUBE_CLIENT_ID, YOUTUBE_CLIENT_SECRET and YOUTUBE_REFRESH_TOKEN in the 0600 secrets.json, merged with what is there. Resolution is env first, then secrets.json — the R2 credentials' order, so a launchd job finds them.

What a run does

  1. Pre-flight — ffmpeg/ffprobe, the bundled fonts, numpy/OpenCV/Pillow importable (pip install -e ".[video]"), and YouTube credentials when uploading. A failure prints FAILED preflight: … before a minute of rendering is spent.
  2. Pick episodes from the public manifest.json: --pending takes the newest episodes inside lookback_days with no uploaded ledger row, at most max_per_run. A failed or render-only attempt never blocks a retry. Back-fill is only ever explicit (--slug), so a wiped ledger cannot walk the back catalogue onto YouTube.
  3. Transcribe the published mp3 with mlx-whisper (small.en) for word timings. No transcriber installed → the video renders without captions, never fails.
  4. Place the cuts: each story's transition moves into the silence just before its first word, never over the previous story's last one.
  5. Render frame ranges in parallel processes and stitch them: H.264 High, 1080p30, AAC-LC 192 kbps stereo (the up-mix is deliberate — Spotify's video spec wants stereo and the episode mp3 is mono by design). Every frame is a pure function of the audio and the frame index, which is what makes the ranges seamless.
  6. Upload (resumable, chunked, resumes from YouTube's own offset after a 5xx), then ledger it immediately — before the caption track, thumbnail and playlist calls, each of which is best-effort (thumbnails are refused until a channel is verified).

One line per episode on stdout: VIDEO uploaded <slug> <url> privacy=… caption_track=ok thumbnail=failed playlist=skipped, VIDEO rendered <slug> <path>, VIDEO none pending, or FAILED <slug> <reason> (exit 1). A failed attempt keeps its workdir ($TMPDIR/clodcast-video-<slug>-*) and says where.

The ledger (videos.jsonl)

~/.config/daily-podcast/videos.jsonl is append-only, one full-key-set JSON line per event (timestamp, slug, status, youtube_id, youtube_url, privacy_status, duration_s, video_bytes, captions, extras, output_path, error_message). status is uploaded, extras (the best-effort calls' outcomes, informational), rendered or failed; only uploaded marks a slug done. --slug refuses to upload a slug that already has one unless --force is passed.

Spotify

Spotify only takes video for an RSS-hosted show by hand: claim the show in Spotify for Creators, then Upload video on the episode (web only). The mp4 already meets Spotify's spec. Render the file to keep with --no-upload --out.

Unattended daily run

This section is the canonical procedure for shipping an episode with no human in the loop — a scheduled Claude routine, a cron claude -p, or any headless invocation. It is the single source of truth: a scheduler should invoke this skill and follow this section rather than carrying its own copy of these steps, which drift.

You are an unattended invocation. Ship today's episode and exit. Be decisive, don't ask clarifying questions, and if you genuinely cannot proceed, exit with a single-line error on stdout.

  1. Read config
    • ~/.config/daily-podcast/config.json — opml_files, lookback_hours, target_item_count, r2_bucket, r2_public_base_url (the last two are the ship; show_id and the prune keys are inert since #218)
    • ~/.config/daily-podcast/covered.json — URLs already covered; treat as "do not repeat". Absent or malformed → {}, never a failed run.
  2. Gather candidates from OPML. For each path in opml_files:
    • Parse the OPML XML (a <body> of nested <outline> elements; leaves with type="rss" carry the feed URL in xmlUrl)
    • Fetch entries newer than lookback_hours ago; skip feeds that 404/timeout after one retry and move on
    • Capture title, link, published, summary (or first 1000 chars of content), feed_name
    • Use Python with feedparser (declared in pyproject.toml); fall back to pip install --user feedparser
    • Drop items whose link is already in covered.json
  3. Curate down to target_item_count (default 10). This is a news digest — cover stories the way a tech-and-security news show would: what happened, who is affected, why it matters, and the response.

    First, drop any item you could only summarize by reproducing attack methodology — exploit proof-of-concept or how-to walkthroughs, step-by-step intrusion write-ups, payloads / working commands, or raw breach-and-leak dumps. Judge this from the title, feed_name, and summary captured in step 2 — before any WebFetch in step 4 — so you never fetch a source you would then have to refuse.

    A security story is in scope when it can be told at a reporting altitude (a vulnerability was disclosed, a breach occurred, a patch shipped); out of scope when the item is the technique. Reporting on a disclosed vulnerability, a breach, or published security research is ordinary tech journalism — the line is operational how-to, not the security topic. Apply the keep/drop test to the specific item, not its feed's reputation: a mainstream security-news feed can still carry one write-up built around exploit detail, and that one gets dropped — while a clean disclosure / impact / response story from any feed is kept. When an item is borderline (newsworthy core wrapped around some operational detail), keep it and pull only the reporting-level summary in step 4; don't drop a whole feed to avoid one item.

    Next, apply the "same story, different URL" test. Step 2 only dropped exact link matches against covered.json, so a story the show already ran arrives under a new URL and sails past it. Check each surviving item against covered.json and against the rest of today's candidate set; three shapes recur:

    • Primary ↔ commentary. A link-blog post and the announcement it links to are one story, and both are in the OPML. Pick whichever has more to say and run it once — never both, and never on consecutive days.
    • Rumor → confirmation. "X reportedly acquires Y" and Y's own announcement are one story. Cover it at confirmation unless the rumor itself was the news; if the rumor already shipped, the confirmation is only worth a segment when the terms changed.
    • Outlet B rewrites outlet A. Match on the entity — CVE ID, company, product, incident — not the URL. The same flaw with the same framing a few days apart is re-coverage, whichever outlet carries it.

    Then drop weekly roundups and conference recaps outright: for a daily show, a "week in review" is by construction a digest of what the show already ran. Match the item's link and title against the roundup_patterns list in blocked_sources.json — separators are interchangeable, so week-in-review matches both "Week in review:" in a title and /week-in-review-…/ in a path. That list is the pattern data; read it there rather than re-inlining it here, and note a preferred outlet's roundup is still a roundup.

    Then rank what remains, in order:

    1. Original reporting and analysis (e.g. Anthropic blog, Simon Willison) over aggregators
    2. Items naming specific products, releases, papers, findings, or numbers (concrete > abstract)
    3. Items from feeds not used in the past 3 days (variety across episodes)
    4. Newer over older within the lookback window

    If you cannot find at least 5 items meeting the bar, ship a shorter episode rather than padding. Dropping out-of-scope, duplicate, and roundup items is normal and counts toward this — never pad to hit a count, and never raise target_item_count to compensate for the extra drops.

  4. Fetch full content for each selected item via WebFetch, at a reporting altitude — the who / what / impact / response. WebFetch is a summarizing fetch, so ask it for the news summary, not a verbatim dump. If an article embeds operational detail, leave it out of what you save. Extract the article body, not the homepage. Save to /tmp/daily-podcast-<date>/item_NN.md.

    Several outlets cannot be fetched at all. Consult blocked_sources.json before spending a fetch: it lists each blocked domain with the reason, a recovery strategy (primary-source, alt-outlet, feed-summary), and a substitute. It also lists preferred outlets that fetch clean, and non_article_hosts (YouTube, Reddit, HN permalinks) that must never be a segment source_url. When you recover a story from a different outlet, use that URL as source_url — it is what you actually read.

  5. Write segments per the script template above. Compute day (day-of-year) once and use it for the cold open, its fourth-wall angle, the sign-off, the sign-off's button angle, and each segment's shape and length band — the template is a date-seeded rotation, so do not fall back to one fixed form. Strict 1:1: segment[i] ↔ source[i], no merging, no reordering. Report, don't instruct: never include exploit steps, payloads, working commands, or any procedure an attacker could follow; if a kept item can't be substantive without them, drop it rather than sanitize it.
  6. Self-critique pass (silent): tighten segments over 900 chars or repetitive. Never reorder, never drop a segment.
  7. Build the manifest at /tmp/daily-podcast-<date>/manifest.json per the manifest schema. Title it per Episode title — the day's three lead stories, then the date, never the bare date. Set "ship_mode": "web" — without it the run defaults to spotify and uploads to the retired private show, which deletes a published episode to make room (#218). Include the music block exactly as the schema shows it: this show has had an intro/outro theme since 2026-09-10, and a manifest that omits the key ships an episode without it. Do not set voice_instruct ("voice": "house" resolves to the locked house voice) and do not set show_id (nothing reads it in this mode).
  8. Run the renderer at the pinned plugin path. ${CLAUDE_PLUGIN_ROOT} is set when this runs under a Claude Code plugin; if it is somehow unset, exit immediately with FAILED CLAUDE_PLUGIN_ROOT unset — do not search the filesystem for render.py.

    python3 "${CLAUDE_PLUGIN_ROOT}/skills/daily-podcast/render.py" \
      --manifest /tmp/daily-podcast-<date>/manifest.json \
      --workdir /tmp/daily-podcast-<date>

    Always pass a stable per-date --workdir — it is what makes a failed run resumable. Never pass --dry-run (this is a real episode) and never pass --skip-preflight: a pre-flight failure is a real problem reported cheaply, and skipping the gate turns a five-second diagnostic into a wasted render or a destructive prune.

    render.py prints a final JSON line on stdout with status ("web-ready" here), mp3_url, voice, voice_mode, chapter_count, duration_s, r2_status, and tts_engine. There is no episode_uri in this mode. It updates covered.json only after the publish succeeds.

  9. Report once and exit. Single-line stdout. All values come from the renderer's final JSON (mp3_url, title, chapter_count, duration_s, tts_engine):

    SHIPPED <mp3_url> - <title> - <chapter_count> chapters - <duration_s>s - r2=ok - engine=<tts_engine>

    r2=ok is the only success value here (#218). The publish is the ship, so anything else means nothing was published: render.py exits non-zero and leaves covered.json untouched, and the correct report is a FAILED line. (On the retired Spotify path r2=FAILED was a successful run because the episode was already live; that no longer applies to any show.) On genuine failure:

    FAILED <reason>

Unattended failure handling

SituationDo
Feed unreachableskip, note, continue
Fewer than 5 viable itemsship shorter; do not pad
render.py non-zero exitprint FAILED <stderr last line> — the last stderr line is always the diagnostic
Pre-flight failurereport it; do not retry with --skip-preflight. The named check is the real problem. A failing r2-credentials check is fatal here: R2 is the ship
R2 publish failed (r2 anything but ok)print FAILED <reason>. Nothing was published and covered.json is untouched, so the sources return to the pool — re-run the same --manifest + --workdir and it renders off the TTS cache
covered.json malformedtreat as {} rather than failing the run
A leftover uploaded.json / inflight.json in the workdirleave it alone. Both are Spotify-upload recovery state from before #218; a web-only run ignores them and never writes either

After the run, any non-clean exit leaves a structured report in ~/.config/daily-podcast/incidents/new/. Mention its path in the FAILED line's context if one was written — a report tagged unclassified is a failure mode nobody has documented yet. The report stays in the queue until someone drains it with triage.py resolve, which archives it to incidents/handled/; do not rm it.

Today's date: resolve via the system, never hardcode. Long form ("May 22, 2026") in the intro, short form ("2026-05-22") in workdir paths.

Running the pipeline

Two entry points:

Interactive (current session): Claude writes the manifest in conversation, then runs:

python3 <skill-dir>/render.py --manifest manifest.json

Headless (unattended schedule): Use the orchestrator, which gathers + curates deterministically and summarizes each item in its own isolated claude -p subprocess:

python3 <skill-dir>/orchestrate.py

Final stdout is a single line: SHIPPED <episode_uri> ... or FAILED <reason>.

prompts/daily.md is a stub: the unattended procedure lives in Unattended daily run so a scheduler has exactly one source of truth to follow.

Orchestrator (unattended)

orchestrate.py is the unattended entry point for scheduled runs. Core invariant: no LLM request ever holds more than one article body — curation is deterministic metadata-only (feedparser titles, dates, summaries), and each ranked item is summarized by its own isolated claude -p subprocess. A per-item classifier block, timeout, or error drops only that item (logged to dropped.jsonl); the remaining items still ship.

Pipeline:

  1. Parse OPML, fetch feeds — metadata only, no article bodies
  2. Deterministic ranking: source tier × recency × concreteness, variety penalty (feeds used within 3 days are deprioritized), per-feed cap
  3. Fan-out: one claude -p prompts/summarize_item.md per ranked item, concurrency-capped
  4. Survivors (non-blocked items) assembled into a manifest and handed to render.py

CLI flags (for orchestrate.py):

FlagPurpose
--dry-runForward to render.py --dry-run; skip upload + feed_usage.json write
--workdir PATHUse this directory for the manifest and render artifacts
--limit NCap items fanned out (useful for testing)
--manifest-onlyAssemble the manifest then stop (no render/upload)
--concurrency NParallel claude -p calls (default: 3; wide fan-out can trip API rate limits)

State files written by the orchestrator (under ~/.config/daily-podcast/):

  • feed_usage.json — {feed_name: last_used_date} map; drives the variety penalty so the same feed doesn't dominate back-to-back episodes. Updated only on a successful real (ready) run; --dry-run leaves it unchanged.
  • dropped.jsonl — append-only JSONL record of every item that was blocked, refused, timed out, errored, or hit an auth failure during a run. One record per dropped item: {timestamp, run_date, feed_name, url, reason, detail} (reason ∈ refused/blocked/auth/timeout/error). Useful for diagnosing feed-level issues or cyber-content policy patterns; an all-auth night means child claude -p could not authenticate (see Unattended runs need durable credentials).

Note: orchestrate.py does not accept --selftest or --prune-workdirs — those flags belong to render.py. For disk hygiene, call render.py --prune-workdirs N separately.

render.py exits non-zero with a diagnostic on any failure. Always check the exit code; do not assume success.

For testing without publishing, use --dry-run — produces the MP3, cover, and timeline.json locally and reports paths (including the R2 URL it would have written), but publishes nothing and leaves covered.json untouched.

Unattended-run flags

FlagPurpose
--selftestStandalone health check (no real run). Mutually exclusive with --manifest.
--load-modelWith --selftest: also load the TTS model (slow; the most thorough check).
--ship-mode {web,spotify}With --selftest: which gate to probe (default web). Refused with --manifest — a run's mode lives on its manifest.
--skip-preflightSkip the built-in pre-flight gate. Escape hatch; you own the outcome.
--keep-workdirKeep the auto-created workdir after a successful run (default: delete it).
--prune-workdirs NBefore rendering, delete auto-created workdirs older than N days.

Pre-flight (automatic, every run)

Every render runs a pre-flight gate before any expensive work. This is not the same thing as --selftest, which is the standalone command you can call yourself; the gate runs inside the render, and a failure aborts before a single TTS segment is generated:

preflight: verifying dependencies, credentials, and capacity...
  [PASS] ffmpeg: /usr/local/bin/ffmpeg
  [PASS] ffprobe: /opt/homebrew/bin/ffprobe
  [PASS] encoder-profile: 1ch @ 44100Hz 192k libmp3lame
  [PASS] house-voice: ref wav + transcript present
  [PASS] tts-module: mlx_audio importable
  [FAIL] r2-credentials: R2 partially configured; missing R2_ACCESS_KEY_ID, …
preflight: FAIL (5/6)
error: preflight failed (r2-credentials); nothing was rendered or uploaded
CheckGates against
ffmpeg / ffprobemissing encoder
encoder-profileencoder settings drifting off mono / 44.1 kHz / 192 kbps
house-voicemissing ref clip or transcript
tts-modulemlx_audio not importable (a find_spec probe, not a model load)
music-asseta missing, moved, altered or undecodable music file (only when music.enabled; runs on --dry-run)
r2-credentialsan R2 config that can't publish — the ship under ship_mode: "web"
show-idno show configured (Spotify mode only)
save-to-spotify-authdead or missing credentials (Spotify mode only; skipped on --dry-run)
episode-capacitythe 60-episode cap — pre-prunes a slot (Spotify mode only; skipped on --dry-run)

R2 is three-state and the mode decides what absent means: under "ship_mode": "web" (this show, #218) it is a failure, because the run would render a full episode and ship it nowhere; on the Spotify path it passes, since the web feed is additive there. Partially configured fails in both. --dry-run runs the local subset only — it never calls Spotify and never prunes.

Artifact gate (automatic, after render, before the ship)

Once the mp3 exists, verify_artifact runs a local conformance check — encoder profile, monotonic chapter starts, the 5 s minimum gap between consecutive chapter starts, last chapter inside the duration, and (with music enabled) the finished duration against the mix plan within 250 ms — and refuses to upload an artifact whose sha256 is in rejections.jsonl (Spotify rejected those exact bytes before; retrying costs a pruned episode). It runs under --dry-run too, so a rehearsal is a real rehearsal.

It also rejects a TTS-degenerated segment: each body segment's chars/sec is compared against the median across body segments, and anything under MIN_SPEECH_RATE_RATIO (0.75x) fails the gate. Qwen3-TTS occasionally derails into looping babble mid-segment, which leaves most of that chapter's script unspoken while every structural check still passes (see incidents/tts-degeneration.md). Intro and sign-off are excluded — they are short and legitimately slower — and the check is skipped below MIN_RATE_SAMPLE_SEGMENTS body segments, where a median means nothing. Fix by deleting the flagged seg_NN.mp3 and re-running: the per-segment cache re-renders only that one, and the failure is stochastic, so a retry normally comes back clean.

The chapter checks read start_time_ms, the key the timeline actually carries. They read start_ms until 2026-09-10 — a key no timeline has ever had — so the monotonicity and 5 s-gap checks matched nothing and passed vacuously on every real run. They are live now; a timeline regression fails the gate rather than shipping.

Durable state + resume

The auto workdir is <tmpdir>/daily-podcast-<date> — deterministic, so an interrupted run resumes by re-invoking the same command. <workdir>/state.json records each completed stage (preflight, segments, concat, cover, timeline, artifact_gate, upload, set_timeline, poll_ready, r2, dedup) with its metadata. A web-only run marks the subset it actually reaches — no upload, set_timeline, or poll_ready.

Incident reports

On any non-clean exit the run writes a structured report (markdown + JSON sidecar) to ~/.config/daily-podcast/incidents/new/ — override with DAILY_PODCAST_INCIDENT_DIR. Each is classified against a known failure mode and points at the matching playbook in the repo's incidents/ directory. A report tagged unclassified means a failure mode nobody has written up yet. Writing a report is best-effort and never changes a run's exit code.

new/ is the intake half; incidents/handled/ is the drain, and triage.py is how a report crosses between them. Nothing in a run calls it (same posture as bloopers.py / retitle.py):

python3 <skill-dir>/triage.py list           # what is actually open
python3 <skill-dir>/triage.py resolve <report> --note "why it is handled"

list re-classifies each report's stored message against today's _INCIDENT_SIGNATURES and prints that beside the kind the run recorded — a report written unclassified before anyone wrote up its failure mode is exactly the one that is already handled, and nothing else on disk says so. It is a display, not a rewrite: the recorded kind is what the run observed and never changes.

resolve moves the report (markdown + sidecar) into incidents/handled/ and appends a row to handled/index.jsonl. Never rm a report — it is the evidence behind whichever playbook covers it. handled/ is an archive: no retention window, never pruned.

--selftest runs an ordered set of checks, prints a pass/fail line each, then a JSON summary {"status": "ok"/"failed", "checks": [...]}. It exits 0 only if every check passes, non-zero otherwise — so a scheduler can gate on it.

Since #218 the probe defaults to the web-only gate, matching what every show now ships: ffmpeg + ffprobe on PATH → config.json parses → R2 credentials resolve (required, the same three-state check pre-flight runs) → house-voice ref clip + transcript present. save-to-spotify is never invoked and show_id is not required, so a host whose CLI auth has lapsed still passes — which is the point: a scheduler gating on this was about to start failing over a credential no run consumes.

--selftest --ship-mode spotify restores the old gate for a legacy Spotify-mode manifest (save-to-spotify --json shows returns valid JSON, config.json carries show_id, no R2 check). --ship-mode applies to --selftest only — passing it with --manifest is refused, because a run's mode lives on its manifest and nowhere else.

python3 <skill-dir>/render.py --selftest || { echo "pre-flight failed" | mail -s "podcast down" you@example.com; exit 1; }

It finishes in under 5 seconds (no model load unless --load-model).

Workdir hygiene. Each run creates <tmpdir>/daily-podcast-<date> (the system temp dir — $TMPDIR on macOS, often /tmp on Linux). On a successful run with default flags the auto-created workdir is deleted (a failed run always keeps it for debugging; an explicit --workdir is never auto-deleted, since it backs the resume path). --prune-workdirs N separately sweeps any daily-podcast-* directory older than N days — it never deletes the active workdir, never follows symlinks, and refuses a non-positive N.

Scheduled runs (cron / launchd)

The render now gates itself (see Pre-flight), so the wrapper no longer has to. --selftest remains useful as a separate liveness probe — for alerting on a broken host without starting a run at all.

#!/usr/bin/env bash
set -euo pipefail
cd "$HOME/clodcast"
# Optional: alert on a broken host without starting a run. The render gates itself
# regardless, so this is monitoring, not a prerequisite.
python3 skills/daily-podcast/render.py --selftest || { echo "selftest failed"; exit 1; }
# Real run: per-item isolated orchestrator (drop-on-block, deterministic curation).
python3 skills/daily-podcast/orchestrate.py
# Triage anything the run left behind. `triage.py resolve <report>` archives one
# to incidents/handled/ once it has been dealt with, so this stays a real queue.
python3 skills/daily-podcast/triage.py list

For disk hygiene, render.py --prune-workdirs N is still the mechanism — pass it when calling render.py directly with --manifest. orchestrate.py does not accept --prune-workdirs; sweep the temp dir separately if needed.

Unattended runs need durable credentials

orchestrate.py summarizes each ranked item — and writes the intro/sign-off — by spawning a child claude -p subprocess. Those children authenticate on their own: they read whatever credential is on disk or in their environment, not the parent's in-memory session login. In an interactive claude session this is invisible, because a persistent OAuth credential (~/.claude/.credentials.json) is already on disk for the children to use.

Under a scheduler (launchd / cron, or any harness that injects a session-scoped credential the parent holds only in memory), the children can start with no usable credential — no on-disk token and no ANTHROPIC_API_KEY. Every item then fails with 401 Invalid authentication credentials. The orchestrator detects this case (the AUTH outcome) and fails fast with a single actionable line rather than silently degrading to the generic "no viable items":

FAILED no viable items; at least one item reported a 401 authentication error - under a scheduler, child `claude -p` likely has no credentials. See SKILL.md "Unattended runs need durable credentials".

The requirement: the scheduled job's child processes must be able to authenticate without the interactive session. That means one of:

  • a persistent on-disk credential the children can read at run time (e.g. a valid ~/.claude/.credentials.json for the user the job runs as), or
  • an API key in the job's own environment (ANTHROPIC_API_KEY) — set in the launchd plist / cron environment itself, since a scheduled job does not inherit your interactive shell env (the same constraint that pushes R2 / Pages secrets into the plist or secrets.json). Keep keys out of config.json and git.

Verify it in your actual scheduler before relying on it. Auth in the scheduled harness is exactly the non-obvious part, so don't assume a recipe works — confirm a bare child can authenticate from inside the scheduled context (not your terminal):

# Run this from the scheduler itself (a one-off scheduled task / `launchctl kickstart`),
# capturing output — NOT from an interactive shell, which has different credentials.
claude -p 'reply with the single word OK' || echo "child claude -p cannot authenticate here"

If that 401s, fix the credential before scheduling the orchestrator; if no durable credential is available to children in your environment, drive the daily run with in-session subagents (which share the parent's working auth) instead of the claude -p fan-out.

Recovering from a partial failure

Most of this section is Spotify-mode machinery and does not run for this show since #218. A web-only run has no upload to fail after, so it writes no uploaded.json and no inflight.json, never resumes, and never reconciles an in-flight episode. Its whole recovery story is one line: nothing was published, covered.json is untouched, so re-run the same --manifest + --workdir and it re-renders off the TTS cache. What follows still applies to a manifest that selects "ship_mode": "spotify", and is kept because the mode is still supported.

Runbook. Most of what used to be manual here is now automatic. The table below is the current division of labour; each row links to a write-up in the repo's incidents/ directory with the symptom, root cause, and the test that guards the remedy.

FailureNow handled byYou do
Processing rejection (FAILED)recovery abandons it, records the artifact, unblocks the runnothing
Episode-cap 429pre-flight pre-prunes; upload prunes + retries oncenothing (watch pruned_episodes)
Poll timeout1800 s window, PROCESSING-aware, transient-tolerantnothing
Transient upload flakeone automatic retrynothing
Connection dropdeterministic workdir + state.jsonre-run the same command
R2 skip on resumeconfig passed into resume; pre-flight fails a partial R2nothing
Rejected artifact re-uploadartifact gate blocks identical bytesre-render to change content
Blocked sourceregistry ships in the skillpick the substitute
Child claude -p 401detection + fail-fast onlyfix the credential

rm ~/.config/daily-podcast/inflight.json is no longer the remedy for a stuck pipeline. Recovery clears a rejected record itself. If you still find a lingering inflight.json, the episode is PROCESSING, not FAILED — leave it.

The upload → timeline set → poll-until-READY → dedup sequence can fail after the episode is already live on Spotify — most commonly a poll_ready timeout where processing simply took longer than the window. To make this recoverable, render.py writes <workdir>/uploaded.json (the episode URI + title) the moment upload() succeeds, before the failure-prone steps.

To resume, re-run the same manifest with the same --workdir:

python3 <skill-dir>/render.py --manifest manifest.json --workdir /tmp/daily-podcast-<date>

When --workdir is passed and it contains uploaded.json, render.py skips TTS rendering, the cover, and the upload, reuses the existing episode.mp3 / cover.jpg / timeline.json, and re-runs only the idempotent tail (timeline set + poll + R2 back-fill + dedup). The final report carries "resumed": true and the same 3-state "r2_status" as a fresh run (#40). Notes:

  • Resume triggers on any workdir containing uploaded.json — including the auto one, which is now deterministic (daily-podcast-<date>), so re-running the identical command recovers an interrupted run. A failed run always keeps its workdir, which is exactly when this matters.
  • If the workdir has uploaded.json but is missing an artifact, render.py fails fast (workdir has uploaded.json but missing …) rather than re-uploading.
  • --dry-run never resumes (it never uploads).
  • After a fully successful run, uploaded.json stays in the workdir, so re-running the same --workdir resumes the existing episode (an idempotent no-op) instead of rendering fresh. To force a fresh render (e.g. you fixed the script and want to re-ship), delete the workdir or its uploaded.json.

Per-segment TTS cache (resume cheaply mid-render)

TTS dominates a run's cost, so a crash on segment 9 of 12 shouldn't re-render segments 1–8. Each rendered seg_NN.mp3 carries a seg_NN.json sidecar with a content-hash cache key over the segment's spoken text and the resolved voice settings (mode + voice/instruct + a hash of the ref_audio bytes + ref_text).

  • Re-running with the same --workdir and same manifest reuses every segment whose key still matches and re-renders only the rest. If every segment is cached, the ~15 s model load is skipped entirely.
  • Editing one segment's text invalidates only that segment; the others are reused.
  • Changing the voice (e.g. house → Ryan), the voice_instruct, or the bytes of refs/house_voice.wav invalidates the affected entries (the key changes).
  • The cache is workdir-scoped — a fresh --workdir always renders fresh, so the cache can't leak across unrelated episodes. A stderr line (cache: N/M segment(s) reusable … / cache hit …) reports what was reused.

Automatic cron recovery (cross-day, workdir-independent)

The workdir uploaded.json resume above is manual — it only helps if you re-run with that exact --workdir. The unattended cron uses a per-date workdir (/tmp/daily-podcast-<date>), so a poll_ready timeout on Monday that dies before dedup would otherwise let Tuesday's run (different workdir, no marker) re-curate Monday's still-undeduped URLs and ship a duplicate.

To close that gap, the moment upload() succeeds render.py also writes a long-lived in-flight log at ~/.config/daily-podcast/inflight.json (episode URI, title, workdir, the segment source_urls). It records the upload independently of the workdir and is cleared only after dedup completes.

On startup — before curating/rendering a new episode, on any non---dry-run run — render.py reconciles a leftover in-flight log:

  1. If the prior workdir + timeline.json still exist, it re-runs timeline set + polls that episode.
  2. READY → it marks the recorded source_urls in covered.json (so curation here can't re-select them), then clears inflight.json.
  3. FAILED → it abandons the record: writes an incident, records the artifact's sha256 in rejections.jsonl, clears inflight.json, and lets today's episode render. covered.json is deliberately not written — those URLs never shipped, so they return to the pool. Without this, one rejected episode disabled every future run (see processing-failed.md).
  4. Timeout → it leaves inflight.json intact and stops; the episode may still be processing.

A crash during recovery leaves inflight.json intact for the next attempt, and covered.json stays the single source of truth — the in-flight log never gates dedup, it only ever drives a write into covered.json. --dry-run skips recovery entirely (it never uploads, calls Spotify, or mutates covered.json).

Dependencies

  • Cloudflare R2 credentials + r2_bucket / r2_public_base_url — the ship (#218); see Web-only shipping
  • save-to-spotify CLI on PATH, authenticated (save-to-spotify auth login) — no longer required. Nothing this show runs invokes it; it is needed only to render a legacy "ship_mode": "spotify" manifest
  • Python 3.10+ with the deps declared in pyproject.toml — pip install -r requirements.txt (canonical list; covers mlx-audio, soundfile, mutagen, Pillow, numpy, feedparser)
  • ffmpeg + ffprobe
  • Apple Silicon Mac (Qwen3-TTS via MLX needs Metal)
  • ~4 GB free disk for the VoiceDesign model on first run
  • Episode video only: the video extra (numpy, opencv-python-headless, Pillow, mlx-whisper) and a YouTube OAuth client — see Episode video. Nothing else in the skill needs either

Final report

After the R2 publish succeeds:

Shipped [episode title]. [N] chapters, voice [voice]. https://clodcast.cortech.online/[slug].mp3

Nothing else. The user can listen and judge.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.