Keep --help from downloading, and give process a JSON stdout

.well-known/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "podcli": {
+      "command": "podcli",
+      "args": ["mcp"],
+      "description": "Transcribe, shortlist clips, and render shorts. Run podcli setup once before this."
+    }
+  }
+}

CLAUDE.md

@@ -31,15 +31,15 @@ Both share the same knowledge base at `.podcli/knowledge/`.
 
 ## MCP tools (podcli engine)
 
-All 30 tools registered by the MCP server.
+All 32 tools registered by the MCP server.
 
 **Transcription and input**
 
 | Tool | What it does |
 |------|-------------|
 | `transcribe_podcast` | Transcribe audio/video with Whisper word timestamps + speaker detection |
 | `transcribe_start` | Start transcription as a background job, returns a job_id immediately |
-| `job_status` | Poll any background job (transcription, render, batch export) with long-polling |
+| `job_status` | Poll any background job (transcription, render, batch export, process_episode) with long-polling |
 | `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 |
@@ -51,6 +51,8 @@ All 30 tools registered by the MCP server.
 | Tool | What it does |
 |------|-------------|
 | `get_ui_state` | Read session state (video, transcript, suggestions, settings) and next steps |
+| `rank_clip_candidates` | Return ~20 pre-ranked, sentence-aligned clip candidates from the cached transcript (no full transcript in the result) |
+| `process_episode` | One-shot job: transcribe, rank, render; poll with `job_status` and read clip paths from the result |
 | `suggest_clips` | Submit clip suggestions, assigns clip numbers, pushes them to the web UI |
 | `modify_clip` | Adjust a suggested clip: timing, title, caption style, or delete it |
 | `toggle_clip` | Select or deselect a suggested clip for export |

README.md

@@ -30,7 +30,7 @@
 podcli process episode.mp4
 ```
 
-That one command transcribes the episode, picks the moments worth clipping, crops to whoever is speaking, and burns the captions in. Transcription and rendering run on your machine. The only network calls are the optional Claude or Codex requests when you use AI clip scoring.
+That one command transcribes the episode, picks the moments worth clipping, crops to whoever is speaking, and burns the captions in. Transcription and rendering run on your machine. Clip scoring uses Claude Code or Codex login, or an Anthropic API key; without those it falls back to heuristics.
 
 ## Install
 
@@ -48,7 +48,7 @@ curl -fsSL https://podcli.com/install.sh | sh
 irm https://podcli.com/install.ps1 | iex
 ```
 
-Runs on macOS (Apple Silicon), Linux (x64 and arm64), and Windows (x64). Intel Mac support is in progress.
+Runs on macOS (Apple Silicon), Linux (x64 and arm64), and Windows (x64). Intel Macs aren't supported.
 
 ## Quick start
 
@@ -97,7 +97,7 @@ Clips land in `podcli-clips/` in the directory you ran it from, so each show kee
 
 **Shipping it**
 
-- 30 MCP tools, so an agent can transcribe, score, render, and publish through conversation
+- 32 MCP tools, so an agent can transcribe, score, render, and publish through conversation
 - YouTube publishing plus performance analytics to see which clips landed
 - DaVinci Resolve export as FCPXML when you want to finish by hand
 - Presets, clip history with duplicate detection, and a transcript cache
@@ -108,7 +108,7 @@ If you are weighing podcli against the cloud clippers, this is the difference:
 
 - Runs locally. Transcription and rendering happen on your machine by default, so episodes stay there. Only the optional cloud engine (AssemblyAI) and publishing to YouTube send anything out.
 - Free and open source under AGPL-3.0. Exports are unlimited, full quality, and watermark-free.
-- Agent-native. 30 MCP tools let Claude Code or Codex drive the whole flow, transcription through publishing.
+- Agent-native. 32 MCP tools let Claude Code or Codex drive the whole flow, transcription through publishing.
 - A knowledge base keeps titles, captions, and descriptions in your show's voice, and stops the engine from resuggesting moments you already published.
 - DaVinci Resolve handoff. Export any clip as FCPXML when you want to finish the edit yourself.
 
@@ -120,6 +120,17 @@ podcli is an [MCP](https://modelcontextprotocol.io) server, so an agent can tran
 podcli mcp install    # registers it with Claude Code and Codex, whichever CLI is on PATH
 ```
 
+`--help` and `--version` never download anything. First run of `process`, `studio`, `transcribe`, or `multicam` provisions the engine. `podcli mcp` does not — stdout is JSON-RPC — so run `podcli setup` once before you point an agent at it.
+
+```bash
+podcli process episode.mp4 --json --yes
+podcli doctor --json
+```
+
+`--json` writes one object to stdout and logs to stderr. `-y/--yes` skips prompts. `NO_COLOR=1` (or a non-TTY) turns off colour and spinners.
+
+`rank_clip_candidates` returns a shortlist so the agent does not have to read the whole transcript. `process_episode` runs the pipeline as one job; poll it with `job_status`. The workflow lives in [SKILL.md](SKILL.md). Tool names are generated into [llms.txt](llms.txt).
+
 Claude Desktop and Codex setup is in the [MCP docs](https://podcli.com/docs/mcp-server).
 
 ## Content workflow

SKILL.md

@@ -0,0 +1,56 @@
+---
+name: podcli
+description: Transcribe a podcast episode, shortlist clips, render shorts, and hand off titles and descriptions for publishing. Use when the user wants to process an episode, make clips, or drive podcli from an agent.
+---
+
+# podcli
+
+Turn a long episode into short clips with face tracking and burned-in captions. Drive it from the CLI, the studio, or MCP.
+
+## Setup
+
+```bash
+curl -fsSL https://podcli.com/install.sh | sh
+podcli setup                  # once; mcp does not auto-provision
+podcli mcp install            # Claude Code / Codex, whichever is on PATH
+podcli doctor --json          # confirm backend, mcp, ffmpeg, models
+```
+
+`--help` and `--version` never download. `podcli mcp` needs setup first because stdout is JSON-RPC.
+
+Clip scoring uses Claude Code or Codex login, or an Anthropic API key. Without those it falls back to heuristics. Speaker diarization needs `HF_TOKEN`.
+
+## Process an episode (CLI)
+
+```bash
+podcli process episode.mp4 --json --yes
+```
+
+JSON on stdout: clip paths, durations, scores, titles, descriptions, tags, caption files. Logs on stderr. `-y/--yes` skips prompts. `NO_COLOR=1` turns off colour and spinners.
+
+Exit codes: 0 success, 1 runtime error, 2 usage, 130 interrupted.
+
+## Process an episode (MCP)
+
+Prefer the short path so you do not load the full transcript:
+
+1. `transcribe_podcast` (or `transcribe_start` + `job_status` on a long file)
+2. `rank_clip_candidates(video_path)` — about 20 sentence-aligned candidates
+3. Pick a subset. `suggest_clips` to store them, or `create_clip` / `batch_create_clips` to render
+4. `list_outputs` if you only need paths on disk
+
+One-shot when the user wants finished files, not a review pass:
+
+1. `process_episode(video_path)`
+2. `job_status(job_id, wait_seconds: 30)` until `done`
+3. Read clip paths, durations, scores, titles, captions from `result`
+
+The original tools stay as they were. These two are extras.
+
+## After clips exist
+
+Titles, descriptions, thumbnails, brand review: PodStack commands (`/produce-shorts`, `/generate-titles`, `/generate-descriptions`, `/plan-thumbnails`, `/review-content`). Knowledge base is `.podcli/knowledge/`.
+
+Publishing is outside podcli unless YouTube is linked (`youtube` CLI / integrations). Hand the JSON (paths + titles + descriptions + tags) to the user's publisher.
+
+Do not call `get_ui_state(include_transcript: true)` unless you need to rewrite a range; use `rank_clip_candidates`. Do not run `podcli mcp` as the first command on a fresh install; run `podcli setup`.