Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

Shorten the README and move reference material into docs (#69)

Nika Siradzec8bc327a136e
diff --git a/.env.example b/.env.example
index 34b1c1e..1319101 100644
--- a/.env.example
+++ b/.env.example
@@ -1,10 +1,5 @@
# podcli Configuration
-
-# Whisper model size: tiny, base, small, medium, large
-WHISPER_MODEL=base
-
-# Device for Whisper: cpu, cuda, auto
-WHISPER_DEVICE=auto
+# Full reference: docs/configuration.md
# FFmpeg paths (leave blank to use system defaults)
FFMPEG_PATH=
@@ -13,7 +8,8 @@ FFPROBE_PATH=
# Python path (leave blank to auto-detect venv)
PYTHON_PATH=
-# Working directory (defaults to .podcli/ in project root)
+# Config home: knowledge, presets, assets, history
+# (defaults to the managed folder, or .podcli/ when running from source)
PODCLI_HOME=
# HuggingFace token for speaker diarization (pyannote)
@@ -30,6 +26,5 @@ PODCLI_TRANSITION_AUTOFIX_PASSES=2
PORT=3847 # Web UI port
-# Logging
-LOG_LEVEL=info
-DEBUG=false
+# Logging verbosity: debug, info, warn, error
+PODCLI_LOG_LEVEL=info
diff --git a/README.md b/README.md
index 95549b0..a3802dc 100644
--- a/README.md
+++ b/README.md
@@ -4,15 +4,14 @@
<p align="center">
<strong>Open-source AI podcast clipper.</strong><br/>
- Generate short clips in 9:16, 16:9, or 1:1 with face tracking and burned-in captions. CLI, MCP server, and web app.
+ Turn a long episode into short clips with face tracking and burned-in captions. Drive it from the CLI, a web studio, or your coding agent.
</p>
<p align="center">
<a href="https://podcli.com"><strong>podcli.com</strong></a> ·
<a href="https://podcli.com/docs">Docs</a> ·
- <a href="#quick-start">Quick start</a> ·
- <a href="#mcp-server-claude-integration">MCP</a> ·
- <a href="#features">Features</a>
+ <a href="#install">Install</a> ·
+ <a href="#use-it-from-your-agent">MCP</a>
</p>
<p align="center">
@@ -31,139 +30,13 @@
podcli process episode.mp4
```
-One command transcribes, picks the best moments, crops to the face, and burns captions in. Nothing leaves your machine.
-
-Full documentation lives at [podcli.com/docs](https://podcli.com/docs). The docs are open source, edit them at [nmbrthirteen/podcli-docs](https://github.com/nmbrthirteen/podcli-docs).
-
----
-
-## What It Does
-
-**podcli** takes a long-form podcast and turns it into a complete content operation:
-
-```
-Record episode
- ↓
-Transcribe (Whisper, speaker detection)
- ↓
-Find viral moments (Claude AI + audio energy + knowledge base)
- ↓
-Render clips (9:16, 16:9, or 1:1, captions, smart crop, normalized audio)
- ↓
-Generate content package (titles, descriptions, thumbnails, SEO) ← PodStack
- ↓
-Publish with optimization checklist ← PodStack
- ↓
-Review performance ← PodStack
-```
-
-The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/podstack), a set of Claude Code slash commands that ship with podcli. Both halves are deeply integrated: the clip suggestion engine reads from your PodStack knowledge base, uses your title formulas and voice rules, checks the episode database for duplicates, and outputs MCP-aligned fields that flow through to export.
-
----
-
-## How It Works (From a User's Perspective)
-
-### 1. Drop in your episode
-
-```bash
-podcli # then choose "Open Web UI"
-# → http://localhost:3847
-```
-
-Drag your video into the Web UI, or use the CLI:
-
-```bash
-podcli process episode.mp4
-```
-
-### 2. Get clips automatically
-
-podcli uses Claude to analyze your transcript against your show's knowledge base, finding the most viral moments. It scores each one on 4 dimensions, suggests clips with multi-cut segments (cutting out filler), and lets you toggle them on/off before rendering.
-
-Clips come out as **upload-ready Shorts**: 1080x1920, 9:16 vertical, with burned-in captions, normalized audio, and your logo.
-
-### 3. Generate the full content package
-
-Open the project in **Claude Code** and run:
-
-```
-/produce-shorts
-```
-
-This runs the [PodStack](https://github.com/nmbrthirteen/podstack) pipeline — a gstack-style workflow that gives you:
-
-- **8-15 scored moments** with timestamps, categories, and reasoning
-- **8 title options per clip** following your show's title spec (verified against 6 quality gates)
-- **Ready-to-paste descriptions** with hooks, guest attribution, hashtags, SEO keywords
-- **Thumbnail briefs** for both podcast (16:9) and shorts (9:16) formats
-- **Brand review** that catches banned words, voice violations, and weak hooks
-- **Publish checklist** covering pre-upload, at-publish, first-24-hours, and day 3-4 optimization
-
-### 4. Publish and track
-
-Run `/publish-checklist` when uploading. A week later, run `/retro-episode` with your YouTube Studio stats to see what worked and what to improve.
-
----
-
-## The Two Halves
-
-| | Video Engine (podcli core) | Content Workflow (PodStack) |
-| ------------- | ------------------------------------------------- | -------------------------------------------- |
-| **What** | Transcription, clip detection, rendering | Titles, descriptions, thumbnails, publishing |
-| **How** | Python + FFmpeg + Whisper + OpenCV + Claude/Codex | Claude Code slash commands |
-| **Interface** | Web UI, CLI, MCP tools | `/slash-commands` in Claude Code |
-| **Output** | `.mp4` files ready to upload | Content packages ready to paste into YouTube |
-
-Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your show's brand, voice, title formulas, episode database, and style guide. Set it up once, everything stays on-brand.
-
----
-
-## Features
-
-### Video Processing
-
-- **AI clip suggestion** — Claude/Codex-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring
-- **Multi-format output** — vertical 9:16, horizontal 16:9, or square 1:1 (`--format`, the studio selector, or the `create_clip` MCP tool); captions scale to each canvas. Defaults to vertical.
-- **Import from a URL** — paste a YouTube or direct video link in the studio to download and process it
-- **Face tracking** — YuNet face detection, exponential-smoothing camera, split-screen support, speaker-aware tracking with snap cooldown
-- **Burned-in captions** — 4 styles: branded, hormozi, karaoke, subtle
-- **Hardware-accelerated encoding** — VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, CPU fallback
-- **Smart cropping** — center crop or face tracking (handles split-screen, Riverside-style mixed layouts)
-- **Multi-segment clips** — automatically cuts out filler, long pauses, and tangents
-- **Whisper transcription** — auto-transcribe with speaker detection (tiny → large)
-- **Transcript import** — paste `Speaker (MM:SS)`, JSON, drag-drop `.txt` / `.srt` / `.vtt`
-
-### Content Workflow (PodStack)
-
-- **`/process-transcript`** — extract and score best moments from any transcript
-- **`/generate-titles`** — 8 titles per clip with 6-point verification checklist
-- **`/generate-descriptions`** — descriptions + hashtags + SEO keywords
-- **`/plan-thumbnails`** — thumbnail text + designer briefs for both formats
-- **`/review-content`** — paranoid brand check (banned words, voice, title rules)
-- **`/produce-shorts`** — full pipeline: transcript → publish-ready package
-- **`/publish-checklist`** — pre/post-publish optimization
-- **`/retro-episode`** — performance analysis after publishing
-
-### Infrastructure
-
-- **Knowledge base** — `.md` files that teach the AI your brand, voice, and style
-- **Asset management** — register logos and videos for quick reuse
-- **Clip history** — tracks everything to avoid duplicates
-- **Preset system** — save named configurations per show
-- **Content studio** — generate titles, descriptions, tags, and hashtags in the web UI; regenerate any section with your own guidance, or ask for anything custom
-- **MCP server** — 22 tools for Claude Desktop / Claude Code integration
-- **Web UI** — multi-page studio at `localhost:3847`
-- **CLI** — one-command processing: `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.
## Install
-No prerequisites — the install fetches a self-contained binary, and the first run
-provisions everything it needs (Python, Node, FFmpeg, whisper.cpp, models) into a
-managed directory. You don't need Go, Node, Python, or FFmpeg installed.
+No prerequisites. The installer fetches a self-contained binary, and the first run provisions Python, Node, FFmpeg, whisper.cpp, and the models it needs into a managed folder.
-**macOS / Linux**
+**macOS and Linux**
```bash
curl -fsSL https://podcli.com/install.sh | sh
@@ -175,310 +48,69 @@ curl -fsSL https://podcli.com/install.sh | sh
irm https://podcli.com/install.ps1 | iex
```
-Then just run it — the first launch sets itself up:
+Runs on macOS (Apple Silicon), Linux (x64 and arm64), and Windows (x64). Intel Mac support is in progress.
-```bash
-podcli # interactive menu (and Web UI)
-podcli process episode.mp4 # transcribe + export clips
-```
-
-Supported platforms: macOS (Apple Silicon), Linux (x64 / arm64), Windows (x64).
-Intel Macs are coming in a follow-up release.
-
-To uninstall, remove podcli and everything under its managed folder — runtime, models, cache, **and your config, knowledge, presets, assets, and history**:
+## Quick start
```bash
-podcli uninstall
+podcli # interactive menu, opens the web studio
+podcli process episode.mp4 # transcribe, pick moments, render clips
```
-This removes all managed data by default. Run `podcli uninstall --dry-run` first to see exactly what will be removed, and back up the folder if you want to keep any of it. (`--purge` is kept as a no-op alias.)
+Clips land in `podcli-clips/` in the directory you ran it from.
-**Optional**, for AI clip suggestion and the PodStack slash commands: install
-[Claude Code](https://docs.anthropic.com/en/docs/claude-code) or
-[Codex](https://openai.com/index/introducing-codex/) (auto-detected).
+## What you get
-> Building from source needs Go 1.23+ (and Node for the studio bundle); see
-> [`plans/native-cli.md`](plans/native-cli.md).
+- Clips in 9:16, 16:9, or 1:1, with captions sized for each canvas
+- Face tracking that follows the speaker, including split-screen layouts
+- Four caption styles: branded, hormozi, karaoke, subtle
+- Hardware encoding on VideoToolbox, NVENC, and VAAPI, with a CPU fallback
+- A web studio at `localhost:3847` for review, thumbnails, and content
+- A knowledge base that teaches the AI your show's voice and title rules
----
+## Use it from your agent
-## Usage
-
-### Web UI
+podcli is an [MCP](https://modelcontextprotocol.io) server, so an agent can transcribe, suggest clips, and render them through conversation.
```bash
-podcli # then choose "Open Web UI"
-# → http://localhost:3847
+podcli mcp install # registers it with Claude Code
```
-1. **Set video** — drag-and-drop or enter a local path
-2. **Add transcript** — drag a `.txt` file, paste `Speaker (MM:SS)` text, or auto-transcribe with Whisper
-3. **Generate Clips** — analyzes audio energy + transcript to suggest viral moments
-4. **Review** — toggle clips on/off, pick caption style, crop mode, logo
-5. **Export** — batch-renders selected clips with hardware acceleration
-6. **Preview / Download** — watch results inline, download individual clips
+Claude Desktop and Codex setup is in the [MCP docs](https://podcli.com/docs/mcp-server).
-### CLI
+## Content workflow
-```bash
-# One command. Auto-transcribes, picks moments, renders clips.
-podcli process episode.mp4
-```
-
-With more control:
+[PodStack](https://github.com/nmbrthirteen/podstack) ships with podcli as a set of Claude Code slash commands. They take a transcript to a publish-ready package: scored moments, titles, descriptions, thumbnail briefs, a brand review, and a publish checklist.
-```bash
-# Use an existing transcript instead of transcribing
-podcli process episode.mp4 --transcript transcript.txt --top 5
-
-# Full options
-podcli process episode.mp4 \
- --transcript transcript.txt \
- --top 8 \
- --caption-style branded \
- --crop center \
- --logo logo.png
-```
-
-### Presets
-
-```bash
-podcli presets save myshow --caption-style branded --logo logo.png --top 5
-podcli presets list
-podcli process video.mp4 --preset myshow
```
-
-### Content Workflow (PodStack)
-
-Open the project in Claude Code, then use slash commands:
-
-```bash
-# Full pipeline — transcript to publish-ready package
/produce-shorts
-
-# Individual steps
-/process-transcript # extract moments from a transcript
-/generate-titles # get 8 title options for a clip
-/generate-descriptions # get descriptions + hashtags
-/plan-thumbnails # get thumbnail briefs for your designer
-/review-content # brand and quality review
-/publish-checklist # pre/post-publish ops
-/retro-episode # performance analysis
```
-Or just paste a transcript — Claude auto-detects the input and runs the right command.
-
----
+The commands live in `.claude/commands/`. [CLAUDE.md](CLAUDE.md) describes each one.
-## Knowledge Base
-
-The knowledge base is what makes podcli understand _your_ show. Drop `.md` files into `.podcli/knowledge/` and both the video engine and content workflow use them. The clip suggestion engine reads 8 of these files (prioritized by relevance), checks the episode database for duplicate avoidance, and applies your voice rules and title formulas when generating suggestions.
-
-PodStack ships with **13 starter templates** that you fill in with your show's details:
-
-| File | What It Teaches The AI |
-| ----------------------------- | ---------------------------------------------------- |
-| `00-master-instructions.md` | Auto-detection rules, decision tree, quality gates |
-| `01-brand-identity.md` | Show name, positioning, tagline, hosts, format |
-| `02-voice-and-tone.md` | Voice fingerprint, banned words, the Coffee Test |
-| `03-episodes-database.md` | Episode tracking, existing shorts (for dedup) |
-| `04-shorts-creation-guide.md` | Moment types, selection criteria, extraction process |
-| `05-title-formulas.md` | Title shapes, rules, templates by content type |
-| `06-descriptions-template.md` | Description formulas, hashtag library, SEO keywords |
-| `07-thumbnail-guide.md` | Layouts, brand colors, typography, visual specs |
-| `08-topics-themes.md` | Core topics, cross-cutting themes, audience map |
-| `09-content-workflow.md` | End-to-end workflow phases, handoff specs |
-| `10-internal-processing.md` | Auto-execution rules, internal quality gates |
-| `11-inspiration-channels.md` | Reference channels, viral hooks, hybrid formulas |
-| `12-quick-reference.md` | Copy-paste hooks, hashtags, CTAs, checklists |
-
-Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or through the `knowledge_base` MCP tool.
-
----
-
-## MCP Server (Claude Integration)
-
-podcli is a [Model Context Protocol](https://modelcontextprotocol.io) server — Claude can use it as a tool to create clips through conversation.
-
-**Claude Code** — register the bundled MCP server in one command:
-
-```bash
-podcli mcp install
-```
-
-**Claude Desktop** — add to `claude_desktop_config.json`:
-
-```json
-{
- "mcpServers": {
- "podcli": {
- "command": "podcli",
- "args": ["mcp"]
- }
- }
-}
-```
+## Docs
-### MCP Tools
-
-| Tool | Description |
-| -------------------- | ------------------------------------------------------------------------ |
-| `transcribe_podcast` | Transcribe audio/video with Whisper + speaker detection |
-| `suggest_clips` | Submit clip suggestions (includes duplicate check) |
-| `create_clip` | Render a single short-form clip as a vertical short |
-| `batch_create_clips` | Render multiple clips in one batch |
-| `knowledge_base` | Read/manage podcast context files (hosts, style, audience, etc.) |
-| `manage_assets` | Register/list reusable assets (logos, videos) |
-| `clip_history` | View previously created clips, check for duplicates |
-| `get_ui_state` | Read current session state and get workflow next-step guidance |
-| `modify_clip` | Adjust a suggested clip's timing, title, or caption style (or delete it) |
-| `toggle_clip` | Select or deselect a suggested clip for export |
-| `update_settings` | Update rendering settings (caption style, crop strategy, logo, outro) |
-| `list_outputs` | List all rendered clip files in the output directory |
-| `manage_presets` | Save, load, list, or delete rendering presets |
-| `analyze_energy` | Analyze audio energy levels to find high-energy moments |
-| `set_video` | Set the working video file without transcribing |
-| `import_transcript` | Import an external transcript with word-level timestamps (skips Whisper) |
-| `parse_transcript` | Parse raw speaker-labeled plain text into word-level timestamps |
-
----
-
-## Caption Styles
-
-| Style | Look |
-| ----------- | ----------------------------------------------------------------------------------- |
-| **branded** | Large bold text, dark box highlight on active word, gradient overlay, optional logo |
-| **hormozi** | Bold uppercase pop-on text, yellow active word (Alex Hormozi style) |
-| **karaoke** | Full sentence visible, words highlight progressively |
-| **subtle** | Clean minimal white text at bottom |
-
----
-
-## Project Structure
+| Guide | What's in it |
+| ----- | ------------ |
+| [Getting started](https://podcli.com/docs) | Install, first episode, the whole flow |
+| [The studio](https://podcli.com/docs/the-studio) | Web UI: library, episodes, content, highlights |
+| [CLI](https://podcli.com/docs/cli) | Commands, flags, presets, assets |
+| [MCP server](https://podcli.com/docs/mcp-server) | Agent setup and available tools |
+| [Captions and formats](https://podcli.com/docs/captions-and-formats) | Styles, aspect ratios, cropping |
+| [Configuration](docs/configuration.md) | Environment variables, config profiles, transcript format |
-```
-podcli/
-├── cli/ # Go launcher (native binary, provisioning, self-update)
-├── install.sh / install.ps1 # node-less installers
-├── setup.sh # dev environment setup (venv + npm)
-├── package.json
-├── CLAUDE.md # PodStack master config
-│
-├── .claude/commands/ # PodStack slash commands
-│ ├── process-transcript.md
-│ ├── generate-titles.md
-│ ├── generate-descriptions.md
-│ ├── plan-thumbnails.md
-│ ├── review-content.md
-│ ├── produce-shorts.md
-│ ├── publish-checklist.md
-│ └── retro-episode.md
-│
-├── src/ # TypeScript
-│ ├── index.ts # MCP server entry (stdio)
-│ ├── server.ts # MCP tool definitions
-│ ├── config/paths.ts
-│ ├── models/index.ts
-│ ├── handlers/ # MCP tool handlers
-│ ├── services/
-│ │ ├── python-executor.ts
-│ │ ├── file-manager.ts
-│ │ ├── asset-manager.ts
-│ │ ├── clips-history.ts
-│ │ ├── knowledge-base.ts
-│ │ └── transcript-cache.ts
-│ └── ui/
-│ ├── web-server.ts # Express server + API
-│ └── public/ # Frontend (React SPA)
-│
-├── backend/ # Python
-│ ├── main.py # stdin/stdout JSON dispatcher
-│ ├── cli.py # CLI entry point
-│ ├── presets.py
-│ ├── requirements.txt
-│ ├── models/ # ML model files
-│ │ └── face_detection_yunet_2023mar.onnx
-│ ├── services/ # Whisper, FFmpeg, captions, face tracking, etc.
-│ │ ├── face_detector.py # shared YuNet face detector
-│ │ └── ...
-│ └── config/
-│ └── caption_styles.py
-│
-├── .podcli/ # config home (gitignored) — knowledge, presets, assets
-│ ├── knowledge/
-│ ├── assets/
-│ ├── presets/
-│ └── history/
-└── data/ # runtime data (gitignored) — cache, output, working
- ├── cache/ # CLI transcription cache + remotion bundle
- │ └── transcripts/ # MCP/UI transcript cache
- ├── output/ # rendered clips
- └── working/ # temp uploads and task dirs
-```
-
-## Configuration
-
-Copy `.env.example` to `.env` (setup.sh does this automatically):
-
-| Variable | Default | Description |
-| ---------------- | ---------- | ----------------------------------------------------- |
-| `WHISPER_MODEL` | `base` | Whisper model size (tiny, base, small, medium, large) |
-| `WHISPER_DEVICE` | `auto` | `cpu`, `cuda`, or `auto` |
-| `PYTHON_PATH` | (venv) | Path to Python binary |
-| `PODCLI_HOME` | `.podcli/` | Config home (knowledge, presets, assets, settings) |
-| `PODCLI_DATA` | `data/` | Runtime data (cache, output, working, logs) |
-| `FFMPEG_PATH` | `ffmpeg` | Custom FFmpeg path |
-| `LOG_LEVEL` | `info` | Logging verbosity |
-
-### Config profiles (multi-show / multi-machine)
-
-Portable bundles zip your config home (not cache or rendered clips):
-
-```bash
-podcli config export ~/backups/myshow.zip
-podcli config import ~/backups/myshow.zip --home ~/.podcli-myshow --activate
-podcli config status
-```
-
-Activate a config root without importing: `podcli config use ~/.podcli-myshow` (writes `.podcli-home` in the project).
-
-### Upgrading from older layouts
-
-Older releases stored transcription cache under `project/.podcli/cache/` (now `data/cache/`) and presets under `project/presets/` (now `.podcli/presets/`). After upgrading, migration runs automatically when legacy files are still present (CLI, Web UI, MCP). To preview or run manually:
-
-```bash
-podcli config migrate --dry-run # preview only
-podcli config migrate # apply (same as auto when legacy cache exists)
-```
-
-**One source of truth:** settings live in **config home** (`PODCLI_HOME` or `.podcli/`, tracked by `.podcli-home`); heavy/runtime files live under **data** (`PODCLI_DATA` or `data/`). The marker file only points at which config home is active — it does not replace either root.
-
-MCP: `manage_config(action=migrate)`.
-
-Web UI: [Config profiles](http://localhost:3847/config.html) (when `npm run ui` is running).
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development conventions.
-
-## Transcript Format
-
-```
-Speaker Name (00:00)
-What they said goes here as plain text.
-
-Another Speaker (00:45)
-Their response text here.
-```
+Docs are open source at [nmbrthirteen/podcli-docs](https://github.com/nmbrthirteen/podcli-docs).
-The time offset field (default: -1s) shifts all timestamps to sync with audio.
+## Contributing
----
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup and conventions, and [RELEASE.md](RELEASE.md) for how releases are cut.
## Credits
-Content workflow powered by [PodStack](https://github.com/nmbrthirteen/podstack) — inspired by [gstack](https://github.com/garrytan/gstack) by Garry Tan.
+Content workflow powered by [PodStack](https://github.com/nmbrthirteen/podstack), inspired by [gstack](https://github.com/garrytan/gstack) by Garry Tan.
## License
AGPL-3.0. See [LICENSE](LICENSE).
-**Need to use Podcli without AGPL terms?** A commercial license is available — email [[email protected]](mailto:[email protected]) with a one-line description of your use case.
+Need podcli without AGPL terms? A commercial license is available. Email [[email protected]](mailto:[email protected]) with a one-line description of your use case.
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..e6cdcdc
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,87 @@
+# Configuration
+
+## Environment variables
+
+Copy `.env.example` to `.env`, or export these in your shell. `setup.sh` copies the file for you.
+
+| Variable | Default | What it does |
+| -------- | ------- | ------------ |
+| `PODCLI_HOME` | managed folder (installed) or `./.podcli` (source) | Config home: knowledge, presets, assets, history, settings |
+| `PODCLI_DATA` | managed folder (installed) or `./data` (source) | Runtime data: cache, working files, logs |
+| `PODCLI_OUTPUT` | `./podcli-clips` (installed) or `$PODCLI_DATA/output` (source) | Where rendered clips are written |
+| `PODCLI_QUALITY` | `high` | Render quality profile |
+| `PODCLI_NO_UPDATE` | unset | Set to `1` to skip the update check. Same as `podcli config set update.auto off` |
+| `PODCLI_LOG_LEVEL` | `info` | Logging verbosity |
+| `PORT` | `3847` | Web studio port |
+| `HF_TOKEN` | unset | Hugging Face token, required for speaker diarization |
+| `PODCLI_ENV_FILE` | `./.env` | Path to an alternate `.env` |
+| `PODCLI_BACKEND` | resolved | Override the Python backend directory |
+| `PODCLI_PYTHON` | resolved | Override the Python interpreter |
+| `FFMPEG_PATH` / `FFPROBE_PATH` | `ffmpeg` / `ffprobe` | Override the FFmpeg binaries |
+
+Installed builds provision their own Python, Node, FFmpeg, and whisper.cpp, so the
+override variables are only needed when running from source or debugging.
+
+The Whisper model is chosen per run with `--model` (or `podcli setup --model`), not
+through an environment variable.
+
+## Config profiles
+
+A portable bundle zips your config home. Cache and rendered clips are excluded.
+
+```bash
+podcli config export ~/backups/myshow.zip
+podcli config import ~/backups/myshow.zip --home ~/.podcli-myshow --activate
+podcli config status
+```
+
+To point at a config root without importing:
+
+```bash
+podcli config use ~/.podcli-myshow # writes .podcli-home in the project
+```
+
+Settings live in the config home (`PODCLI_HOME`, tracked by the `.podcli-home`
+marker). Heavy runtime files live under `PODCLI_DATA`. The marker file records
+which config home is active; it does not replace either root.
+
+MCP equivalent: `manage_config`.
+
+## Upgrading from older layouts
+
+Older releases kept the transcription cache under `project/.podcli/cache/` (now
+`data/cache/`) and presets under `project/presets/` (now `.podcli/presets/`).
+Migration runs automatically when legacy files are still present, across the CLI,
+web UI, and MCP server. To preview or run it by hand:
+
+```bash
+podcli config migrate --dry-run # preview only
+podcli config migrate # apply
+```
+
+## Transcript format
+
+podcli auto-transcribes with Whisper, and it accepts an existing transcript with
+`--transcript`. Drag-drop `.txt`, `.srt`, and `.vtt` work in the studio.
+
+```
+Speaker Name (00:00)
+What they said goes here as plain text.
+
+Another Speaker (00:45)
+Their response text here.
+```
+
+The time offset field (default `-1s`) shifts every timestamp to sync with the audio.
+
+## Knowledge base
+
+`.md` files in `$PODCLI_HOME/knowledge/` teach the AI your show. The clip suggestion
+engine reads them for voice rules and title formulas, and checks the episode database
+so it does not resuggest a moment you already published.
+
+PodStack ships 13 starter templates covering brand identity, voice and tone, the
+episode database, shorts criteria, title formulas, description templates, thumbnail
+guides, topics, workflow, and quick reference. Fill them in with your show's details.
+
+Edit them in the studio under Knowledge, or through the `knowledge_base` MCP tool.