rsc-universal 0.1.1

package/skills/planetscale/references/no-foreign-keys.md

@@ -0,0 +1,88 @@
+# Designing without foreign keys on PlanetScale
+
+Offloaded depth from SKILL.md §"Design without foreign keys". The body has the rule and one Bad→Good
+fence; this file covers emulated cascades, the ORM specifics, and the unsharded opt-in caveats.
+
+## Why FKs fight Vitess
+
+Two of Vitess's first-class features make native FKs a poor default:
+
+- **Horizontal sharding** — a foreign key between rows on different shards has no meaning; the
+  constraint cannot be enforced across the shard boundary.
+- **Online DDL** — FK constraints complicate the shadow-table copy + cutover dance.
+
+On top of that, FK constraint checks add per-write overhead that **degrades high-concurrency
+workloads**. PlanetScale historically disallowed FKs entirely; they are now an **opt-in but
+unsharded-only** feature. So the scale-safe default is app-level referential integrity.
+
+## Emulated relations
+
+You keep the relationship — you just stop asking the database to enforce it.
+
+- **Index the relation column.** A non-FK relation still needs its index for join/lookup performance.
+  `KEY idx_orders_user_id (user_id)`.
+- **Enforce existence in the app/ORM.** Validate that `user_id` points at a real user before insert.
+- **Cascade explicitly.** There is no `ON DELETE CASCADE`. Delete dependents yourself, in a
+  transaction or a background job:
+
+```sql
+-- App-side cascade, in one transaction (or a queued job for large fan-out):
+START TRANSACTION;
+DELETE FROM order_items WHERE order_id IN (SELECT id FROM orders WHERE user_id = ?);
+DELETE FROM orders      WHERE user_id = ?;
+DELETE FROM users       WHERE id = ?;
+COMMIT;
+```
+
+For large fan-out, prefer a batched background job over one giant transaction so you do not hold writes.
+
+## Prisma: relationMode = "prisma"
+
+Setting `relationMode = "prisma"` tells Prisma to emulate relations in the client instead of emitting
+DB-level foreign keys. Prisma then also creates the **implicit indexes** on relation scalar fields that
+a real FK would have given you for free.
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+
+model Order {
+  id     BigInt @id @default(autoincrement())
+  userId BigInt
+  user   User   @relation(fields: [userId], references: [id])
+
+  @@index([userId]) // required under relationMode="prisma" — no implicit FK index from the DB
+}
+```
+
+ORM-client ergonomics beyond this knob belong to the `prisma-orm` sibling, not here.
+
+## Drizzle: app-level relations
+
+Drizzle models relations in app code via `relations()` and queries them with the relational API. On
+PlanetScale you index the join column and skip the `references()`-backed DB constraint; the relation
+lives in code, not in the database. The query-builder side is the `../drizzle-orm/SKILL.md` sibling.
+
+## The unsharded FK opt-in
+
+Native FKs are available again, but **only on unsharded keyspaces**. It is acceptable to use one when:
+
+- you are certain the table will **never** shard (small, bounded, low-write reference data), and
+- you accept the extra Online DDL friction the FK introduces, and
+- you remember that FK constraint changes are **excluded from clean schema reverts** (see
+  deploy-requests.md).
+
+If any of those is shaky, default back to emulated relations. Document *why* a given table is allowed
+an FK so the next person does not "fix" it.
+
+## Bad → Good patterns
+
+| Pattern | Bad on PlanetScale at scale | Good |
+| --- | --- | --- |
+| Relation | DB `FOREIGN KEY … REFERENCES` | Indexed column + app/ORM-emulated relation |
+| Delete dependents | `ON DELETE CASCADE` | Explicit transactional or batched delete in app code |
+| Index on relation column | Relying on the FK's implicit index | Declare the index yourself (`@@index`, `KEY`) |
+| Integrity guarantee | "the database will reject orphans" | Validate before write; reconcile orphans in a job |

package/skills/planetscale/scripts/verify.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — planetscale skill content gate. Read-only, idempotent, never writes.
+#
+# Checks the SKILL's own SKILL.md + references/*.md for accuracy and consistency:
+#   1. The deploy-request CLI verbs (create / diff / review / deploy) are all present and
+#      correctly named — the workflow is the spine of this skill.
+#   2. No claim that PlanetScale "enforces foreign keys by default" (the opposite is true:
+#      FKs are an opt-in, unsharded-only feature).
+#   3. The serverless driver is spelled EXACTLY @planetscale/database — no invented names
+#      (@planetscale/serverless, planetscale-js, @planetscale/mysql, ...).
+#   4. Every fenced code block is language-tagged.
+#
+# Exit code: non-zero ONLY on a real content failure. An empty / clean target exits 0 with no
+# false failure: if no SKILL.md is found we [skip] and pass (so this is safe to run anywhere).
+#
+# Portability: stock macOS bash 3.2 (no mapfile / associative arrays). Arrays are initialised
+# so they expand safely under `set -u`.
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# Resolve the skill root: directory containing this script's parent (scripts/ -> skill dir).
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+
+if [ ! -f "$SKILL_MD" ]; then
+  skip "no SKILL.md found at $SKILL_MD — nothing to check"
+  exit 0
+fi
+
+# Gather the content files: SKILL.md + every references/*.md. Initialised array (set -u safe).
+FILES=("$SKILL_MD")
+if [ -d "$SKILL_DIR/references" ]; then
+  while IFS= read -r -d '' f; do
+    FILES+=("$f")
+  done < <(find "$SKILL_DIR/references" -type f -name '*.md' -print0 2>/dev/null)
+fi
+
+# Concatenate once for whole-skill greps.
+ALL="$(cat "${FILES[@]}" 2>/dev/null || true)"
+
+# ---- 1. deploy-request CLI verbs present ----
+MISSING=""
+for verb in create diff review deploy; do
+  if ! printf '%s' "$ALL" | grep -Eq "deploy-request[[:space:]]+$verb"; then
+    MISSING="$MISSING $verb"
+  fi
+done
+if [ -n "$MISSING" ]; then
+  err "missing deploy-request verb(s):$MISSING"
+else
+  ok "deploy-request workflow verbs present (create / diff / review / deploy)"
+fi
+
+# ---- 2. no 'enforces foreign keys by default' style claim ----
+if printf '%s' "$ALL" | grep -Eiq 'enforce[sd]?[^.]*foreign[[:space:]]+key[^.]*by[[:space:]]+default'; then
+  err "found a claim that PlanetScale enforces foreign keys by default — it does not (opt-in, unsharded-only)"
+else
+  ok "no false 'enforces foreign keys by default' claim"
+fi
+
+# ---- 3. serverless driver spelled exactly @planetscale/database ----
+# Only inspect lines that actually USE the driver (import / require / from / a pkg-manager add) so
+# that an anti-patterns row deliberately LISTING wrong names as a banlist is not a false failure.
+USAGE="$(printf '%s' "$ALL" | grep -E '(^|[^A-Za-z])(import|require|from)([^A-Za-z]|$)|(npm|pnpm|yarn|bun)[[:space:]]+(add|install|i)[[:space:]]' || true)"
+if printf '%s' "$ALL" | grep -Eq '@planetscale/'; then
+  if printf '%s' "$USAGE" | grep -Eoq '@planetscale/[a-z-]+'; then
+    BADPKG="$(printf '%s' "$USAGE" | grep -Eo '@planetscale/[a-z-]+' | grep -v '^@planetscale/database$' || true)"
+    if [ -n "$BADPKG" ]; then
+      err "imported a non-canonical @planetscale package: $(printf '%s' "$BADPKG" | sort -u | tr '\n' ' ')"
+    else
+      ok "serverless driver imported exactly as @planetscale/database"
+    fi
+  else
+    ok "@planetscale/database referenced; no non-canonical import found"
+  fi
+else
+  skip "@planetscale/* package not referenced — nothing to check"
+fi
+if printf '%s' "$USAGE" | grep -Eq '\bplanetscale-js\b'; then
+  err "imported an invented driver name 'planetscale-js'"
+fi
+
+# ---- 4. every code fence is language-tagged ----
+# Count opening fences (those followed by a language token) vs total fences. A bare ``` that opens
+# a block has no trailing word; closing fences are bare too. We pair them: every other ``` is a
+# closer, so opening fences are the odd-indexed ones. Simplest robust check: no opening fence may be
+# bare. We walk fences in order and require odd (1st,3rd,...) fences to carry a language tag.
+for f in "${FILES[@]}"; do
+  bad="$(awk '
+    /^```/ {
+      n++
+      if (n % 2 == 1) {            # opening fence
+        tag = substr($0, 4)
+        gsub(/[[:space:]]/, "", tag)
+        if (tag == "") { print FILENAME ":" NR }
+      }
+    }
+  ' "$f")"
+  if [ -n "$bad" ]; then
+    err "untagged opening code fence(s) in:"
+    printf '%s\n' "$bad"
+  fi
+done
+if [ "$EXIT" -eq 0 ]; then ok "all code fences language-tagged"; fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/podcast/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: podcast
+description: "Use when planning, recording, editing, or publishing one podcast episode end to end — the run-of-show and guest brief, recording settings (double-ender, 48 kHz WAV multitrack), the loudness master, the Podcasting 2.0 sidecars (chapters.json, transcript.vtt), the RSS <item>, and timestamped SEO show notes. Use when audio sounds quiet on Spotify but loud on Apple, a feed is rejected for bad artwork, or chapters and transcripts will not show in the app. Triggers: 'plan the run-of-show for a 40-minute interview', 'what LUFS for Apple and Spotify', 'master once to -16 LUFS', 'wire the transcript tag', 'valid RSS item with chapters and transcript for episode 14', 'generate a chapters.json from the double-ender locals', 'write timestamped SEO show notes', 'masteritzar l'àudio del podcast', 'escribe las show notes con timestamps'. NOT clipping the episode into social posts (that is social-publisher) and NOT cutting the vertical short (that is video-shorts)."
+tags: [podcast, audio, rss, show-notes, podcasting-2.0]
+recommends: [social-publisher, video-shorts, newsletter, brand-voice, content-engine]
+origin: risco
+---
+
+# Podcast — One Episode, Plan to Published
+
+*You own the production craft and the distribution surface of a single audio episode: the run-of-show, the recording settings, the loudness target, the chapters and transcript sidecars, the RSS `<item>`, and the show-notes page that ranks. You do not invent the show's voice, plan the content calendar, or cut the clips — you take one episode from idea to a feed entry an app can ingest.*
+
+An episode moves through four phases: **plan → record → edit & master → publish** (plus the show-notes page that ships with publish). Every load-bearing number below is sourced and dated (accessed 2026-06-02). Use the current numbers; do not guess from memory.
+
+## The flow — find the phase, do that phase
+
+Read the ask, drop it into one phase, execute that phase, and stop at its hand-off. Do not redo earlier phases the user already has.
+
+| The ask sounds like | Phase | You produce |
+| --- | --- | --- |
+| format, run-of-show, guest brief, questions, cold-open | 1 Plan | an episode outline + question list |
+| double-ender, sample rate, multitrack, "how do I record remotely" | 2 Record | a recording-settings checklist |
+| "how loud", LUFS, true peak, mono vs stereo, export format | 3 Edit & master | a mastering target sheet + export plan |
+| RSS item, enclosure, chapters, transcript, artwork, submit to Apple | 4 Publish | a valid `<item>` + `chapters.json` + `transcript.vtt` |
+| show notes, episode page, timestamps, SEO | Show notes | a blog-shaped, timestamped page |
+
+## Phase 1 — Plan
+
+Pick the format first; it sets everything downstream.
+
+| Format | Use when | Why |
+| --- | --- | --- |
+| Solo | you own the expertise and want tight control | no scheduling, fastest to ship, easiest to master (mono) |
+| Interview | the value is a guest's knowledge | borrowed audience + authority; needs a guest brief |
+| Co-host | a recurring two-voice dynamic | chemistry carries it; needs two locals |
+| Narrative | story-driven, scripted, sound-designed | highest production cost; script before you record |
+
+**Run-of-show.** Write a timed segment table before recording so the edit has a spine. Target minutes for a ~40-min interview:
+
+| Segment | Target | Purpose |
+| --- | --- | --- |
+| Cold-open | 0:30 | best 30s of tape, pulled forward to hook |
+| Intro | 1:00 | show ID + episode promise + guest one-liner |
+| Segment(s) | 30:00 | the body — 2-4 themed blocks, not one shapeless chat |
+| CTA | 0:30 | one ask (subscribe / a specific link), never three |
+| Outro | 1:00 | recap + where to go next + sign-off |
+
+**Guest brief** (send before the record): episode topic + angle, 4-6 question themes (not the verbatim list — keep some spontaneity), tech check (headphones + a quiet room + the recording link), the time/timezone, and how their name and links should appear. A guest who knows the themes gives sharper tape.
+
+**Question design.** Open-ended, single-barrel, no yes/no. One idea per question.
+
+```text
+Bad   "Did you find fundraising hard, and what would you change?"  (double-barreled yes/no)
+Good  "Walk me through the moment fundraising got hardest."         (open, single, invites a story)
+```
+
+## Phase 2 — Record
+
+**Record locals, never the call.** A remote double-ender records each participant *locally* — Riverside/Descript capture every speaker on their own machine at 48 kHz uncompressed WAV, one track per speaker, cloud-backed in real time, so quality is independent of the connection. The Zoom/Meet mixdown is compressed, single-track, and drops out with the bandwidth. (Riverside double-ender; Buzzsprout remote-recording guide 2026 — accessed 2026-06-02.)
+
+```text
+Bad   Hit "record" in Zoom and edit the resulting compressed stereo mixdown.
+Good  Double-ender: each speaker's local 48 kHz WAV on its own track, cloud-backed,
+      assembled into a multitrack you edit downstream.
+```
+
+Recording checklist:
+
+- [ ] **Remote** → double-ender (Riverside/Descript). **In-person** → multitrack recorder/interface, one mic per speaker.
+- [ ] **48 kHz, uncompressed WAV**, separate track per speaker — never a pre-mixed single track.
+- [ ] **Local + cloud backup** running before you start talking.
+- [ ] **Track to ~-18 dBFS peaks**, leaving headroom — do not record hot toward 0 dBFS; clipped tracks are unrecoverable and you fix loudness at the master, not the mic.
+- [ ] Headphones on every speaker (kills echo/bleed); record 10s of room tone for noise cleanup.
+
+## Phase 3 — Edit & master
+
+**Edit order.** Assemble → content edit (cut tangents, fix flow) → cleanup (noise reduction, level the tracks against each other) → master last. Master on the finished mix, never mid-edit.
+
+**Master once to -16 LUFS integrated, stereo, true peak -1 dBTP.** This is the single safe target. Apple Podcasts recommends -16 LUFS integrated; Spotify normalizes podcasts to -14 LUFS and turns *down* anything louder on playback — so you do not master a separate file per platform. The -1 dBTP ceiling prevents inter-sample clipping after MP3 encoding. (SONE "Podcast Loudness Standards 2026"; Descript "Podcast Loudness Standard"; Podnews LUFS FAQ — accessed 2026-06-02.)
+
+| Destination | Integrated LUFS | True peak | Channels | Note |
+| --- | --- | --- | --- | --- |
+| Apple Podcasts | -16 | -1 dBTP | stereo | the reference target |
+| Spotify | normalizes to -14 | -1 dBTP | stereo | louder uploads are turned down; do not over-master for it |
+| Mono voice (solo) | -19 (≈ -16 stereo) | -1 dBTP | mono | mono is ~half the file size for a single voice |
+| YouTube (if you also post audio video) | ~-14 | -1 dBTP | stereo | normalized like Spotify |
+
+The mono equivalent of -16 LUFS stereo is **-19 LUFS** — relevant only when you publish a single-voice episode as mono. (SONE / Podnews — accessed 2026-06-02.)
+
+**Export.** Keep the **WAV master** as your archive. Encode the distribution file to **MP3** (commonly 128 kbps stereo / 96 kbps mono for voice) — that MP3 is what the RSS `<enclosure>` points at. Note its byte length and MIME type; you need both for the `<item>`.
+
+## Phase 4 — Publish
+
+The deliverable is a valid RSS episode `<item>` plus its sidecars. A complete annotated `<item>`, the full iTunes/RSS channel tag list, and the Podcasting 2.0 tag set with every attribute live in `references/rss-and-namespace.md` — load it before hand-writing a feed.
+
+**The `<item>` must carry** (Apple's required set + the enclosure):
+
+- `<title>` and `<itunes:title>`, `<description>` (the show notes), `<pubDate>` (RFC-822).
+- `<enclosure url="…" length="…BYTES" type="audio/mpeg"/>` — the MP3 URL, its size in **bytes**, and the MIME type. A wrong `length` breaks the player's scrubber.
+- `<guid isPermaLink="false">` — a stable unique ID that never changes after publish; changing it duplicates the episode in every app.
+- `<itunes:duration>` (seconds or HH:MM:SS) and `<itunes:image href="…"/>`.
+
+**Artwork constraints (feeds are rejected otherwise):** cover art must be a **square JPG or PNG, RGB color space, minimum 1400×1400 px and maximum 3000×3000 px**. (RSS.com hosting guide 2026 — accessed 2026-06-02.)
+
+**Podcasting 2.0 sidecars** (wire them in the `<item>`; full shapes in the reference):
+
+- `chapters.json` → `<podcast:chapters url="…" type="application/json+chapters"/>`. The JSON has `version` + a `chapters[]` array; each chapter has a numeric `startTime` (seconds) and `title`, and startTimes are **monotonically non-decreasing**. The hosted file can be edited after publish.
+- `transcript.vtt` / `.srt` → `<podcast:transcript url="…" type="text/vtt"/>`. The **`type` attribute is required** (`text/vtt`, `application/srt`, or `application/json`); you may add multiple `podcast:transcript` tags for multiple formats. Creator-supplied transcripts beat Apple's auto-generated ones. (Podcasting 2.0 namespace docs — accessed 2026-06-02.)
+- `<podcast:person>` for host and guest (role + image href).
+
+**Apple auto-generates transcripts (since 2024-03) and chapters (iOS 26.2), but auto-chapters only fire when the creator supplied none** — your manual `podcast:chapters` always wins, so supply them when timestamps matter. (Apple Newsroom 2024-03; Castopod/TechBuzz iOS 26.2 coverage — accessed 2026-06-02.)
+
+**Submission reality.** A feed needs **at least one published episode** before you can submit it — Apple requires it and Spotify for Creators hides RSS distribution until the first episode ships. Apple review can take **up to 72 hours**; most hosts publish new episodes within hours. (VNYL RSS guide; RSS.com; Spotify for Creators — accessed 2026-06-02.)
+
+## Show notes
+
+Top-ranking show notes are **blog-shaped, ~1,500+ words**, not a one-paragraph blurb. Timestamps are both a UX and an SEO signal. (Sweetfish "Show Notes Template"; Increv "SEO show notes 2025" — accessed 2026-06-02.)
+
+Template:
+
+```text
+H1            target keyword as the episode title
+Summary       2-3 sentences, keyword-bearing, what the listener gets
+Chapters      timestamped list (00:00 Intro / 04:12 …) mirroring chapters.json
+Takeaways     3-5 bullets — the episode's claims, skimmable
+Guest         short bio + links (site, social)
+Resources     every tool/book/link mentioned
+CTA           one ask (subscribe / a specific URL)
+```
+
+**Title craft** — specific and outcome-bearing beats sequential:
+
+```text
+Bad   "Episode 12"
+Good  "Episode 12: How Marta scaled a solo SaaS to $40k MRR without ads"
+```
+
+Embed `PodcastEpisode` JSON-LD on the page (name, datePublished, duration as ISO-8601 `PT35M`, `associatedMedia` → the MP3, `partOfSeries` → the show) so the episode is eligible for rich results — see `references/rss-and-namespace.md` for the block.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+| --- | --- | --- |
+| Mastering a separate file per platform | Spotify turns down anything over -14 anyway; you just add work and risk inconsistency | Master once to -16 LUFS stereo / -1 dBTP |
+| Editing the recorded Zoom/Meet mixdown | Compressed, single-track, drops out with bandwidth; unrecoverable | Double-ender local 48 kHz WAV, one track per speaker |
+| Tracking hot toward 0 dBFS | Clipped peaks are permanent; loudness is a master-stage fix, not a mic-gain fix | Track to ~-18 dBFS peaks, set loudness at the master |
+| `<podcast:transcript>` without a `type` | Apps cannot parse it; the tag is ignored | Always include `type=` (`text/vtt`, `application/srt`, `application/json`) |
+| Wrong/blank `<enclosure length>` | Breaks the player scrubber and progress | Use the MP3's exact size in bytes |
+| Changing `<guid>` after publish | Apps treat it as a brand-new episode — duplicates the feed | Set a stable guid once; never change it |
+| 1024×1024 or non-square cover art | Below the 1400 px floor / non-square → feed rejected | Square JPG/PNG, RGB, 1400-3000 px |
+| Show notes as a one-paragraph summary | No keywords, no timestamps → no ranking, no UX value | Blog-shaped ~1,500 words with timestamped chapters + takeaways |
+| Relying on Apple auto-chapters when timing matters | Auto-chapters only fire when you supplied none, and you lose control of titles | Ship a manual `chapters.json` via `podcast:chapters` |
+
+## Hand-offs
+
+- Clip the episode into posts for X/LinkedIn/IG and schedule them → `../social-publisher/SKILL.md`.
+- Cut the vertical/short video of a moment → `../video-shorts/SKILL.md`.
+- Write the email that announces the episode to the list → `../newsletter/SKILL.md`.
+- Define the show's tone/persona the episode should sound like → `../brand-voice/SKILL.md`.
+- Decide *which* episodes exist and the cadence across the catalog → `../content-engine/SKILL.md`.
+
+## References
+
+- `references/rss-and-namespace.md` — required + recommended iTunes/RSS channel and item tags, a full annotated `<item>` example, the Podcasting 2.0 tag set with attributes (`transcript`, `chapters`, `person`, `funding`, `season`, `episode`), a sample `chapters.json`, a `transcript.vtt` snippet, and the `PodcastEpisode` JSON-LD block.
+
+After you emit a `chapters.json`, a feed/`<item>`, or a `transcript.vtt`, run `scripts/verify.sh <dir-or-file>` to lint the shape (parse, monotonic startTimes, required enclosure attributes, transcript `type`, artwork size).

package/skills/podcast/evals/README.md

@@ -0,0 +1,17 @@
+# Evals — podcast
+
+These cases are routing + capability checks for a human or an LLM judge; there is no
+automated test runner beyond `scripts/verify.sh` (which lints emitted artifacts — a
+`chapters.json`, an RSS feed/`<item>`, or a `transcript.vtt` — not these prompts). To
+run them: read `cases.yaml` and confirm the skill's `description` would fire on every
+`should_trigger` prompt (including the jargon-only "chapters.json + double-ender + -16
+master" case that never says "podcast" and the Catalan "masteritzar l'àudio" phrasing),
+that each `should_not_trigger` prompt routes to the named sibling instead
+(`video-shorts`, `social-publisher`, `brand-voice`, `newsletter`, `content-engine`), and
+that an end-to-end answer to the `capability` scenario satisfies every line of its
+`must_include` rubric — the -16 LUFS / -1 dBTP master-once rule with Spotify's -14
+normalization, 48 kHz WAV master + MP3 enclosure, a monotonic `chapters.json` wired via
+`podcast:chapters`, a `podcast:transcript` carrying a `type`, an `<item>` with the
+required enclosure/guid/duration/artwork fields, blog-shaped timestamped show notes, and
+the one-episode-first + 72h-Apple submission note. To check an actual emitted artifact,
+point `scripts/verify.sh` at the file or directory it produced.

package/skills/podcast/evals/cases.yaml

@@ -0,0 +1,61 @@
+skill: podcast
+
+# Prompts that MUST load `podcast`. The skill owns ONE episode end to end: the
+# run-of-show, recording settings, the loudness master, the Podcasting 2.0
+# sidecars, the RSS <item>, and the timestamped show-notes page. It does NOT
+# clip the episode for social (social-publisher), cut the vertical short
+# (video-shorts), define the show voice (brand-voice), pick which episodes
+# exist (content-engine), or write the announcement email (newsletter).
+should_trigger:
+  - prompt: "Plan the run-of-show for a 40-minute interview episode with a founder guest."
+    why: "Core Phase 1 — format choice, timed segments, guest brief and question design are exactly this skill's plan deliverable."
+
+  - prompt: "What LUFS and true-peak should I master this episode to for Apple and Spotify?"
+    why: "Core Phase 3 — the central loudness number (-16 LUFS stereo / -1 dBTP, Spotify normalizes to -14) lives here."
+
+  - prompt: "Write a valid RSS item with the transcript and chapters tags for episode 14."
+    why: "Core Phase 4 — a compliant <item> with Podcasting 2.0 enclosure/guid/transcript/chapters is the publish deliverable."
+
+  - prompt: "Write timestamped, SEO show notes for this episode."
+    why: "The show-notes phase — blog-shaped, timestamped, ~1,500-word page is owned here."
+
+  - prompt: "Generate a chapters.json and wire the double-ender locals into a -16 master."
+    why: "Non-obvious — jargon only, never says the word 'podcast'; chapters.json + double-ender + -16 master are unambiguously this skill."
+
+  - prompt: "Masteritzar l'àudio del podcast i escriure les show notes amb timestamps."
+    why: "Catalan for 'master the podcast audio and write the show notes with timestamps' — covers Phase 3 + show notes in another language."
+
+should_not_trigger:
+  - prompt: "Cut three vertical clips from this episode for Reels and TikTok."
+    route_to: video-shorts
+    why: "Editing the vertical/short video cut is video-shorts; podcast delivers the full-length audio master and its sidecars, not the clip."
+
+  - prompt: "Schedule this episode's promo posts across X, LinkedIn, and Instagram."
+    route_to: social-publisher
+    why: "Distribution and repurposing scheduling is social-publisher; podcast stops at the RSS item and the show-notes page."
+
+  - prompt: "Define the tone and personality our show should sound like."
+    route_to: brand-voice
+    why: "The verbal identity/persona spec is brand-voice; podcast shapes one episode but does not invent the voice."
+
+  - prompt: "Write the email announcing the new episode to our subscriber list."
+    route_to: newsletter
+    why: "The list email is newsletter; podcast produces the episode page, not the broadcast email."
+
+  - prompt: "Which episode topics should we line up for next quarter?"
+    route_to: content-engine
+    why: "Deciding WHICH episodes exist and the catalog cadence is content-engine; podcast produces ONE chosen episode."
+
+capability:
+  - scenario: >
+      Take a recorded 35-minute remote founder interview to publish-ready: give the
+      mastering target, produce a chapters.json and wire the transcript, write a valid
+      RSS <item>, and draft the show-notes page.
+    must_include:
+      - "States master ONCE to -16 LUFS integrated, stereo, -1 dBTP true peak, and notes Spotify normalizes to -14 (no per-platform master)."
+      - "Specifies 48 kHz WAV as the archive master and an MP3 for the enclosure (and that the interview should have been a double-ender, locals not the call)."
+      - "Produces a chapters.json with version + chapters[], numeric startTimes that are monotonically non-decreasing, wired via <podcast:chapters>."
+      - "Wires the transcript via <podcast:transcript> WITH a required type attribute (e.g. text/vtt)."
+      - "Writes an RSS <item> with <enclosure url length type>, a stable <guid>, an <itunes:duration>, and square 1400-3000 px artwork."
+      - "Drafts blog-shaped show notes: H1 target keyword, 2-3 sentence summary, timestamped chapter list, key takeaways, guest bio + links, one CTA, ~1,500 words."
+      - "Notes a feed needs one published episode before submission and that Apple review can take up to 72 hours."

package/skills/podcast/references/rss-and-namespace.md

@@ -0,0 +1,136 @@
+# RSS, iTunes, and the Podcasting 2.0 namespace
+
+Deep reference for Phase 4 (Publish). All facts accessed 2026-06-02. Load this when hand-writing or auditing a feed; the SKILL body has the rules, this has the full shapes.
+
+## Channel-level tags (the show, once per feed)
+
+Required by Apple at the `<channel>` level:
+
+- `<title>` — the show name.
+- `<description>` — show description.
+- `<itunes:image href="…"/>` — square JPG/PNG, RGB, **1400-3000 px** (same constraint as episode art).
+- `<language>` — ISO 639 (e.g. `en`, `ca`, `es`).
+- `<itunes:category text="…"/>` — at least one valid Apple category (nest a `<itunes:category>` child for a subcategory).
+- `<itunes:explicit>` — `true` or `false`.
+- `<link>` — the show's site URL.
+- `<itunes:author>` and `<itunes:owner>` (`<itunes:name>` + `<itunes:email>`) — owner email is how Apple verifies the feed.
+
+Recommended: `<itunes:type>` (`episodic` or `serial`), `<copyright>`, `<generator>`, `<atom:link rel="self" .../>`, and the Podcasting 2.0 `<podcast:guid>` (a feed-stable GUID that follows the show across hosts).
+
+## Item-level tags (one per episode)
+
+Required / strongly recommended:
+
+```xml
+<item>
+  <title>Episode 12: How Marta scaled a solo SaaS to $40k MRR without ads</title>
+  <itunes:title>How Marta scaled a solo SaaS to $40k MRR</itunes:title>
+  <itunes:episode>12</itunes:episode>
+  <itunes:season>2</itunes:season>
+  <itunes:episodeType>full</itunes:episodeType>
+  <pubDate>Mon, 02 Jun 2026 08:00:00 GMT</pubDate>
+  <enclosure url="https://cdn.example.com/ep12.mp3" length="34185216" type="audio/mpeg"/>
+  <guid isPermaLink="false">ep-2026-012-a1b2c3</guid>
+  <itunes:duration>35:14</itunes:duration>
+  <itunes:image href="https://cdn.example.com/ep12-cover.jpg"/>
+  <itunes:explicit>false</itunes:explicit>
+  <description><![CDATA[ ...blog-shaped show notes HTML... ]]></description>
+
+  <!-- Podcasting 2.0 enrichments -->
+  <podcast:transcript url="https://cdn.example.com/ep12.vtt" type="text/vtt"/>
+  <podcast:transcript url="https://cdn.example.com/ep12.srt" type="application/srt"/>
+  <podcast:chapters url="https://cdn.example.com/ep12.chapters.json"
+                    type="application/json+chapters"/>
+  <podcast:person role="host"  img="https://cdn.example.com/host.jpg">Alex Host</podcast:person>
+  <podcast:person role="guest" img="https://cdn.example.com/marta.jpg">Marta Founder</podcast:person>
+  <podcast:season name="Season 2">2</podcast:season>
+  <podcast:episode>12</podcast:episode>
+</item>
+```
+
+Tag notes that bite:
+
+- **`<enclosure length>` is bytes**, not duration. Wrong value breaks the scrubber. Read the file's actual size.
+- **`<guid>` is permanent.** Set it once; changing it makes every app treat the episode as new (duplicate). `isPermaLink="false"` when it is an opaque ID rather than a URL.
+- **`<pubDate>` is RFC-822.** Future-dated items may be held until that date by some hosts.
+- **`<itunes:episodeType>`** is `full`, `trailer`, or `bonus`.
+
+## Podcasting 2.0 tags (namespace `xmlns:podcast="https://podcastindex.org/namespace/1.0"`)
+
+| Tag | Key attributes | Purpose |
+| --- | --- | --- |
+| `podcast:transcript` | `url`, **`type` (required)** | links a transcript; `type` ∈ `text/vtt`, `application/srt`, `application/json`. Multiple allowed. |
+| `podcast:chapters` | `url`, `type="application/json+chapters"` | links a hosted chapters JSON; editable after publish. |
+| `podcast:person` | `role`, `group`, `img`, `href` | identifies host/guest with role + image. |
+| `podcast:season` | `name` (text body = number) | names/numbers the season. |
+| `podcast:episode` | `display` (text body = number) | episode number, separate from `<itunes:episode>`. |
+| `podcast:funding` | `url` (text body = label) | a support/donate link shown in-app. |
+
+Apple auto-generates transcripts (since 2024-03) and chapters (iOS 26.2). **Auto-chapters only fire when no `podcast:chapters` is supplied** — a manual file always wins, so ship one when titles/timing matter.
+
+## chapters.json shape
+
+```json
+{
+  "version": "1.2.0",
+  "chapters": [
+    { "startTime": 0,    "title": "Cold open" },
+    { "startTime": 30,   "title": "Intro" },
+    { "startTime": 252,  "title": "The first paying customer", "img": "https://cdn.example.com/ch3.jpg" },
+    { "startTime": 1140, "title": "Why no paid ads" },
+    { "startTime": 2050, "title": "What's next + CTA" }
+  ]
+}
+```
+
+Rules: `startTime` is **seconds** (number), titles present, and startTimes **monotonically non-decreasing**. Optional per-chapter `img`, `url`, `endTime`, `toc`. (Conforms to the Podcast Namespace JSON Chapters spec.)
+
+## transcript.vtt snippet
+
+```text
+WEBVTT
+
+00:00:00.000 --> 00:00:04.500
+<v Alex>Welcome back to the show. Today, Marta.
+
+00:00:04.500 --> 00:00:09.200
+<v Marta>Thanks for having me — happy to get into it.
+```
+
+`WEBVTT` must be the first line. Speaker labels via `<v Name>` are optional but improve readability and accessibility.
+
+## PodcastEpisode JSON-LD (show-notes page)
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "PodcastEpisode",
+  "name": "How Marta scaled a solo SaaS to $40k MRR without ads",
+  "datePublished": "2026-06-02",
+  "duration": "PT35M14S",
+  "url": "https://example.com/podcast/ep12",
+  "associatedMedia": {
+    "@type": "MediaObject",
+    "contentUrl": "https://cdn.example.com/ep12.mp3"
+  },
+  "partOfSeries": {
+    "@type": "PodcastSeries",
+    "name": "The Solo SaaS Show",
+    "url": "https://example.com/podcast"
+  }
+}
+</script>
+```
+
+`duration` is ISO-8601 (`PT35M14S` = 35 min 14 s). This makes the episode page eligible for rich results and feeds AI engines a structured episode object.
+
+## Sources
+
+- RSS.com — Best Podcast Hosting Platforms / submission + artwork (2026).
+- Apple Podcasters — Enhance episodes with chapters, links, and more; Apple Newsroom — transcripts (2024-03); Castopod/TechBuzz — iOS 26.2 auto-chapters.
+- Podcasting 2.0 — Podcast Namespace docs (podcasting2.org / podcastindex.org).
+- VNYL RSS guide; Spotify for Creators.
+- SONE — Podcast Loudness Standards 2026; Descript — Podcast Loudness Standard; Podnews — LUFS/LKFS FAQ.
+
+All accessed 2026-06-02.