Harden clips, transcription and multicam; add opening hooks and Omnilingual

.claude/commands/auto.md

@@ -1,6 +1,6 @@
 ---
 description: One-verb pipeline — drop a video, confirm strategy, render clips
-allowed-tools: Read, Bash, mcp__podcli__transcribe_podcast, mcp__podcli__transcribe_start, mcp__podcli__transcribe_status, mcp__podcli__get_ui_state, mcp__podcli__set_video, mcp__podcli__suggest_clips, mcp__podcli__batch_create_clips, mcp__podcli__knowledge_base, mcp__podcli__clip_history
+allowed-tools: Read, Bash, mcp__podcli__transcribe_podcast, mcp__podcli__transcribe_start, mcp__podcli__job_status, mcp__podcli__get_ui_state, mcp__podcli__set_video, mcp__podcli__suggest_clips, mcp__podcli__batch_create_clips, mcp__podcli__knowledge_base, mcp__podcli__clip_history, mcp__podcli__record_decisions
 argument-hint: [video-path-or-episode-slug] [optional: count e.g. "5 clips"]
 triggers:
   - auto
@@ -21,7 +21,7 @@ This command orchestrates the existing MCP tools on top of the compact packed tr
 
 1. **Read, don't watch.** Reason about clips from the packed markdown view — not raw segments, not frame dumps.
 2. **Strategy first, render after.** Propose the cut list and WAIT for user confirmation before calling `batch_create_clips`.
-3. **Knowledge base is context, not template.** If `` exists, read it for brand voice and format preferences. If not, infer from the content itself.
+3. **Knowledge base is context, not template.** If `.podcli/knowledge/` exists, read it for brand voice and format preferences. If not, infer from the content itself.
 4. **Never silently render.** Every clip that ships must appear in the proposal the user approved.
 5. **Every clip carries its own context.** A stranger who never heard the episode has to follow it from the first second. If the moment is an answer, the question comes with it.
 
@@ -46,14 +46,16 @@ This command orchestrates the existing MCP tools on top of the compact packed tr
    - Call `transcribe_start(file_path)` → returns `{job_id, cached, estimate}` immediately.
    - If `cached: true`, skip to step 3.
    - Otherwise emit a short status to the user: _"Transcription started — estimated {estimate}. I'll check progress every 30s."_
-   - Loop: call `transcribe_status(job_id, wait_seconds: 30)`. Between calls, emit ONE terse line to the user like `"Progress: 47% — pyannote diarization"`. Keep it to one line per poll — no repeat prose. Exit the loop when `done: true`.
+   - Loop: call `job_status(job_id, wait_seconds: 30)`. Between calls, emit ONE terse line to the user like `"Progress: 47%, pyannote diarization"`. Keep it to one line per poll, no repeat prose. Exit the loop when `done: true`.
    - If `status: "error"`, stop and report the error.
 3. Read the packed transcript: `get_ui_state(include_transcript: true)`. This returns a compact phrase-grouped view with speakers, silence gaps, and energy peaks.
    - **If the header says speakers: 0**, stop and tell the user before going further. Without speaker labels you cannot tell a question from an answer, so the whole question-with-the-answer rule below is inert and the picks will be worse. Offer to re-transcribe with `transcribe_start(file_path, enable_diarization: true)`. Only continue without it if the user says to.
-4. If `` exists, read `01-brand-identity.md`, `02-voice-and-tone.md`, and `04-shorts-creation-guide.md` for show context. Skip silently if missing — `/auto` works on any content.
+4. If `.podcli/knowledge/` exists, read `01-brand-identity.md`, `02-voice-and-tone.md`, and `04-shorts-creation-guide.md` for show context. Skip silently if missing: `/auto` works on any content.
 5. Call `clip_history` to see what's already been shipped for this episode. Avoid duplicates in the proposal.
 
-**Fallback**: if `transcribe_start` returns an error about the Web UI not running, tell the user and offer either (a) run `npm run ui` in another terminal then retry, or (b) fall back to the synchronous `transcribe_podcast` (no live progress, works silently).
+**Fallback**: if `transcribe_start` returns an error about the Web UI not running, tell the user and offer either (a) start the Web UI in another terminal then retry (`podcli studio` for a launcher install, `npm run ui` in a source checkout), or (b) fall back to the synchronous `transcribe_podcast` (no live progress, works silently).
+
+6. **Ask once, reuse the answer.** `get_ui_state` lists this episode's unanswered decisions under `OPEN QUESTIONS` (clip count, duration range, captions, language, thumbnails, delivery target). Ask whichever are relevant to this run, batched, not one dialog box per field, then call `record_decisions(video_path, ...)` with the answers. On every later run against this same video, those fields are already answered and won't appear in `OPEN QUESTIONS` again.
 
 ### Phase 2 — Topic Map (silent)
 
@@ -86,6 +88,7 @@ Work inside one topic at a time. Set boundaries by meaning, not by the clock.
 - The question has to be inside the clip. `context_line` is a note for the editor, not a fix: nothing burns it into the video yet, so a clip that relies on it still ships with no setup.
 - If the question rambles past roughly 8 seconds, use `segments` to keep the asked part and cut the rambling, or drop the moment.
 - Never open on a word pointing back before the cut: "that", "it", "they", "yeah", "so", "exactly", "right", "which is why". Widen the start until the reference is inside the clip.
+- If the sharpest line sits mid-clip, you may pass it as `hook` (`{start, end, mode}`, 1-15 seconds) so it plays first. It must be a line actually spoken inside the clip, never invented text. `repeat` replays it in place; `move` lifts it out.
 
 **end_second**
 

.claude/commands/bootstrap-knowledge.md

@@ -18,7 +18,7 @@ triggers:
 
 ## Before starting
 
-1. If `` has no files, run `podcli knowledge init` first so all 14 templates exist.
+1. If `.podcli/knowledge/` has no files, run `podcli knowledge init` first so all 14 templates exist.
 2. Ask for whichever of these the user has not provided:
    - Channel or podcast URL (YouTube channel, Spotify show, RSS feed)
    - Or a few sentences about the show if nothing is published yet

.claude/commands/generate-titles.md

@@ -1,6 +1,6 @@
 ---
 description: Generate 8 verified title options for a clip, moment, or episode
-allowed-tools: Read
+allowed-tools: Read, mcp__podcli__knowledge_base
 argument-hint: [clip-transcript-or-moment-brief]
 triggers:
   - titles for

.claude/commands/plan-episode.md

@@ -1,6 +1,6 @@
 ---
 description: Design questions, story arc, and moment map BEFORE recording an episode
-allowed-tools: Read, Write
+allowed-tools: Read, Write, mcp__podcli__knowledge_base
 argument-hint: [guest-name-and-company]
 triggers:
   - plan episode

.claude/commands/plan-thumbnails.md

@@ -66,6 +66,7 @@ What is the single most compelling image or concept?
 - Guest photo requirements
 - Background suggestion
 - Special visual elements
+- **Layout:** `single` (one face) or `pair` (two people). Propose `pair` for interview clips where the exchange is the point: a question and its answer, a disagreement, a reaction. podcli takes both faces from the clip itself, guest on the left and host on the right. Set it with `manage_thumbnail_config` (`set_layout`), the "Two people" toggle on the clip page, or `podcli thumbnails --layout pair`. Add `--swap` to flip sides, or `--left-image` and `--right-image` to name the people. It falls back to `single` when podcli cannot tell two people apart, so keep a single-face brief ready.
 
 ### Step 4: Quality Check
 - [ ] Readable at phone screen size
@@ -88,6 +89,7 @@ What is the single most compelling image or concept?
 
 **Shorts (9:16):**
 - Text: "[LINE 1] / [LINE 2 — accent]"
+- Layout: [single / pair: guest left, host right]
 - Visual: [action shot / dramatic imagery / B-roll]
 - Text position: Lower third, centered
 

.claude/commands/process-transcript.md

@@ -1,6 +1,6 @@
 ---
 description: Extract, score, and classify the best moments from a raw podcast transcript
-allowed-tools: Read, Write
+allowed-tools: Read, Write, mcp__podcli__knowledge_base
 argument-hint: [transcript-file-or-paste]
 triggers:
   - transcript
@@ -96,6 +96,8 @@ Before scoring, fix each flagged moment's edges and state its payoff.
 
 **Then run the standalone check.** Name what the viewer must already know. If it is anything other than nothing, the start moves back until the clip covers it. If it cannot, drop the moment.
 
+**Optionally mark an opening hook.** If the sharpest line sits mid-clip, it can play first as a `hook` (1-15 seconds, `repeat` replays it in place, `move` lifts it out). It must be a line actually spoken inside the clip, quoted verbatim with its timestamps. Never invent hook text.
+
 ### Phase 4: Score Each Moment
 
 For every flagged moment, score on four dimensions (1-5 each):
@@ -182,6 +184,7 @@ Format: comma-separated, under 500 characters.
 **Payoff:** [What the viewer walks away with. One sentence, second person.]
 **Needs:** [nothing | what the viewer must already know]
 **Setup line:** [The question this answers, in one line, or omit when the clip carries its own setup]
+**Opening hook:** [Optional. "Verbatim line" XX:XX-XX:XX, repeat or move. Omit when the clip opens strong on its own]
 
 **Why it works:** [One sentence explaining the appeal]
 

.claude/commands/produce-shorts.md

@@ -1,6 +1,6 @@
 ---
 description: Full pipeline from transcript to publish-ready content package
-allowed-tools: Read, Write, Edit, Task
+allowed-tools: Read, Write, Edit, Task, mcp__podcli__knowledge_base, mcp__podcli__get_ui_state, mcp__podcli__record_decisions
 argument-hint: [transcript-file-or-episode-number]
 triggers:
   - process episode
@@ -29,6 +29,8 @@ Read the full knowledge base with the `knowledge_base` MCP tool:
 - `07-thumbnail-guide.md` — visual specs
 - `13-learnings.md` — past retro patterns (what worked, what didn't)
 
+If a video is already set (`get_ui_state`), check its `OPEN QUESTIONS` block for unanswered episode decisions (clip count, duration range, captions, language, thumbnails, delivery target). Ask whichever are relevant to this run, batched into one NEEDS_INPUT prompt rather than one per field, then call `record_decisions(video_path, ...)` so the next run against this video doesn't ask again.
+
 ---
 
 ## Inputs
@@ -52,6 +54,8 @@ Each phase calls the corresponding skill's logic. Each phase reports its own Com
 
 Extract guest info, flag 15-20 moments, anchor each one (boundaries by meaning, question pulled in or carried as a setup line, payoff written before any title), score them, select top moments, classify by content type, check for duplicates.
 
+A moment may open with a `hook`: a 1-15 second line spoken inside the clip, played first. Quote it from the transcript. Never invent it.
+
 ### Phase 2: Title Development
 *Runs `/generate-titles` logic per moment*
 

.github/workflows/ci.yml

@@ -87,6 +87,18 @@ jobs:
       - run: node scripts/gen-docs-manifest.mjs
       - run: node scripts/check-docs-drift.mjs
 
+  release-hygiene:
+    name: Release hygiene check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "20"
+      - run: node scripts/release-hygiene.mjs
+
   python:
     name: Python tests
     runs-on: ${{ matrix.os }}
@@ -102,6 +114,17 @@ jobs:
         with:
           python-version: "3.12"
           cache: "pip"
+      - name: Install ffmpeg
+        # Without this, every test that shells out to ffmpeg/ffprobe skips.
+        # About 22 tests were silently not running on any OS.
+        shell: bash
+        run: |
+          case "${{ runner.os }}" in
+            Linux)   sudo apt-get update -qq && sudo apt-get install -y -qq ffmpeg ;;
+            macOS)   brew install --quiet ffmpeg ;;
+            Windows) choco install ffmpeg -y --no-progress ;;
+          esac
+          ffmpeg -version | head -1
       - name: Install minimal test deps
         # Skip whisper/torch — tests don't exercise them and they balloon CI time.
         run: |

AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md
+
+This file exists for coding agents (OpenAI Codex, opencode, Aider, Cursor Agent,
+and others) that read `AGENTS.md` by convention.
+
+- `CLAUDE.md` is the primary instruction document: project layout, the MCP tool
+  table, the knowledge base, and the quality gate all live there and are not
+  repeated here.
+- `AGENTS.podstack.md` covers cross-tool PodStack usage: how each host runs the
+  content-production commands (`/plan-episode`, `/process-transcript`,
+  `/generate-titles`, and the rest), and where each host installs them.
+- `.claude/commands/*.md` are the PodStack command sources. Claude Code reads
+  them directly from that path; `podcli auto` (and the other PodStack
+  commands) also installs them as Codex skills under `~/.codex/skills/` when
+  the `codex` CLI is present.
+
+Start with `CLAUDE.md`, then `AGENTS.podstack.md` for command-by-command detail.

AGENTS.podstack.md

@@ -8,7 +8,7 @@ PodStack turns your AI tool into a podcast content team: Episode Architect, Cont
 
 ## How to use
 
-Each skill below is a self-contained instruction file in `commands/` (or `.claude/commands/`, `.codex/prompts/`, `.cursor/rules/`, `.opencode/commands/`, depending on which host installed it).
+Each skill below is a self-contained instruction file in `commands/` (or `.claude/commands/`, `~/.codex/skills/<name>/SKILL.md`, `.cursor/rules/`, `.opencode/commands/`, depending on which host installed it).
 
 **To run a skill:** ask your agent to "run the [skill-name] skill" or invoke its slash command (`/[skill-name]`) where supported. The agent opens the corresponding file and follows it step by step.
 
@@ -30,7 +30,7 @@ Each skill below is a self-contained instruction file in `commands/` (or `.claud
 
 - **role:** Episode Architect
 - **description:** Design questions, story arc, and moment map BEFORE recording
-- **allowed-tools:** Read, Write
+- **allowed-tools:** Read, Write, mcp__podcli__knowledge_base
 - **triggers:** plan episode, upcoming recording, guest prep, prepare for interview
 - **outputs:** episode plan written to `episodes/ep[XX]-[guest]-plan.md`
 - **next:** record → `/process-transcript`
@@ -39,7 +39,7 @@ Each skill below is a self-contained instruction file in `commands/` (or `.claud
 
 - **role:** Content Analyst
 - **description:** Extract, score, classify best moments from a raw transcript
-- **allowed-tools:** Read, Write
+- **allowed-tools:** Read, Write, mcp__podcli__knowledge_base
 - **triggers:** transcript, process transcript, extract moments, podcast transcript
 - **outputs:** moment brief with timestamps, scores, titles, thumbnails, descriptions
 - **next:** `/generate-titles` or `/produce-shorts`
@@ -48,7 +48,7 @@ Each skill below is a self-contained instruction file in `commands/` (or `.claud
 
 - **role:** Title Writer
 - **description:** Generate 8 verified title options for a clip or moment
-- **allowed-tools:** Read
+- **allowed-tools:** Read, mcp__podcli__knowledge_base
 - **triggers:** titles for, title options, write titles, generate titles
 - **outputs:** 8 titles + 2 top picks with rationale
 
@@ -80,7 +80,7 @@ Each skill below is a self-contained instruction file in `commands/` (or `.claud
 
 - **role:** Producer (master orchestrator)
 - **description:** Full pipeline from transcript to publish-ready content package
-- **allowed-tools:** Read, Write, Edit, Task
+- **allowed-tools:** Read, Write, Edit, Task, mcp__podcli__knowledge_base
 - **triggers:** process episode, produce shorts, full pipeline, prep episode, make content package
 - **outputs:** complete content package in `episodes/ep[XX]-[guest]-content-package.md`
 - **orchestrates:** process-transcript → generate-titles → generate-descriptions → plan-thumbnails → review-content
@@ -114,16 +114,16 @@ Skill files read the 14 knowledge files at `.podcli/knowledge/`; the full file t
 
 PodStack ships one source-of-truth (`commands/`) and installs to the right location for each tool:
 
-| Host | Install location | Primary doc |
-|------|-----------------|-------------|
-| Claude Code | `.claude/commands/*.md` | `CLAUDE.md` |
-| OpenAI Codex | `.codex/prompts/*.md` | `AGENTS.podstack.md` (this file) |
-| Cursor | `.cursor/rules/*.mdc` | `AGENTS.podstack.md` |
-| opencode | `.opencode/commands/*.md` | `AGENTS.podstack.md` |
-| Generic | `commands/*.md` | `AGENTS.podstack.md` |
+| Host | Install location | Installed by | Primary doc |
+|------|-----------------|--------------|-------------|
+| Claude Code | `.claude/commands/*.md` (per project) | `podcli auto` / any PodStack command | `CLAUDE.md` |
+| OpenAI Codex | `~/.codex/skills/<name>/SKILL.md` (global) | `podcli auto` / any PodStack command, when the `codex` CLI is on PATH | `AGENTS.podstack.md` (this file) |
+| Cursor | `.cursor/rules/*.mdc` | not automated yet, copy by hand | `AGENTS.podstack.md` |
+| opencode | `.opencode/commands/*.md` | not automated yet, copy by hand | `AGENTS.podstack.md` |
+| Generic | `commands/*.md` | not automated yet, copy by hand | `AGENTS.podstack.md` |
 
-These command files ship with podcli; place the set for your tool (left column) in
-its command dir. See `README.md` for per-host usage examples.
+Claude and Codex installs are automatic and kept in sync on upgrade; see `README.md`
+for per-host usage examples and manual steps for the other hosts.
 
 ---
 

CLAUDE.md

@@ -31,7 +31,7 @@ Both share the same knowledge base at `.podcli/knowledge/`.
 
 ## MCP tools (podcli engine)
 
-All 27 tools registered by the MCP server.
+All 30 tools registered by the MCP server.
 
 **Transcription and input**
 
@@ -43,6 +43,8 @@ All 27 tools registered by the MCP server.
 | `set_video` | Set the working video without transcribing |
 | `import_transcript` | Import an external transcript with word-level timestamps, skips Whisper |
 | `parse_transcript` | Parse a speaker-labeled plain text transcript into word-level timestamps |
+| `compare_transcription_engines` | Transcribe one sample with two engines and write a side-by-side disagreement report |
+| `mine_channel` | List a YouTube channel's uploads or mine one video's existing captions, without downloading the video |
 
 **Clip workflow**
 
@@ -56,6 +58,7 @@ All 27 tools registered by the MCP server.
 | `batch_create_clips` | Render multiple clips in one batch |
 | `manage_reel` | Build a highlights reel: detect once, edit moments, rebuild without re-detecting |
 | `analyze_energy` | Analyze audio energy levels to find high-energy moments |
+| `record_decisions` | Record per-episode decisions (clip count, duration range, captions, language, thumbnails, delivery target) so later runs never re-ask |
 
 **Full-episode editing**