docs: rewrite README for OSS onboarding

benvinegar · benvinegar · commit 791d843284de · 2026-05-18T21:17:36.000-04:00
diff --git a/README.md b/README.md
@@ -1,173 +1,120 @@
 # podguy
 
-Pi-first post-production workflow for podcasts and video podcasts. Run `./podguy` to open pi in a focused editing mode for this repo.
+Pi-first post-production tooling for podcast and video-podcast editors who want transcripts, chapters, clip candidates, cuts, and social review exports from local media.
 
-## Why podguy
+[![CI](https://github.com/modem-dev/podguy/actions/workflows/ci.yml/badge.svg)](https://github.com/modem-dev/podguy/actions/workflows/ci.yml)
 
-- Launch `./podguy` and work through a repo-local pi skill.
-- Generate transcripts and subtitle files from local audio or video media.
-- Prepare long transcript artifacts for reliable editorial review.
-- Find likely interstitial and inserted-content timecodes from episode videos.
-- Ask the agent for chapters, clip candidates, cut suggestions, show notes, quotes, and proper noun cleanup.
-- Cut selected clip candidates into review exports for TikTok, Reels, YouTube Shorts, trailers, or social posts.
-- Optionally download an open-license Cordkillers video-podcast excerpt for local evaluation.
-- Configure show-specific context with `podguy.toml` without changing the workflow.
+## What it does
+
+- Launches `pi` with podcast-specific skills, prompts, and a startup widget.
+- Transcribes local audio/video files with Whisper-compatible backends.
+- Prepares long transcripts into timecoded chunks for editorial review.
+- Scans video episodes for likely interstitials and non-host inserts.
+- Generates chapters, clip candidates, cut reports, show notes, quotes, and proper noun checks.
+- Cuts selected highlight ranges into review exports for TikTok, Reels, YouTube Shorts, trailers, or social posts.
+
+Generated transcripts, scans, thumbnails, notes, and clip exports go under gitignored `dist/` by default.
 
 ## Install
 
-This project is designed to be operated through `pi`, with `./podguy` as the main entrypoint.
+Clone the repo and install the local Node tooling:
 
-Install the required tools:
+```bash
+git clone https://github.com/modem-dev/podguy.git
+cd podguy
+npm install
+```
+
+Install the required system tools:
 
 ```bash
-npm install -g @mariozechner/pi-coding-agent
-brew install uv
-# optional for local transcription backends, video scanning, and clip cutting
-brew install ffmpeg
+brew install uv ffmpeg
 ```
 
-You can install pi globally or as a repo-local dev dependency. The `./podguy` launcher uses `node_modules/.bin/pi` when present and falls back to a global `pi` install.
+Notes:
+
+- `ffmpeg` is used for fixtures, transcription backends, and clip cutting.
+- `uv` runs the Python scripts and optional transcription dependency groups.
+- The video scanner is macOS-only and uses Swift / AVFoundation / Vision.
 
 Before first use, authenticate pi with `/login` or your usual provider API key setup.
 
-Set up one transcript backend if you want real transcription:
+Set up a real transcription backend when you are ready to transcribe episodes:
 
 ```bash
 uv sync --group transcribe-mlx      # Apple Silicon
 uv sync --group transcribe-faster   # Cross-platform
-uv sync --group transcribe-whisper  # OpenAI Whisper
+uv sync --group transcribe-whisper  # OpenAI Whisper package
 ```
 
-Notes:
-
-- `scripts/scan_podcast.swift` is macOS-only and requires `swift`.
-- `scripts/transcribe_video.py` and `scripts/cut_clips.py` require Python 3.9+ and `uv`.
-- The `mock` backend exists for tests and setup validation, not real transcription.
-
-## Configure a show
+## Quick start
 
-Copy the example profile and customize it for your podcast:
+Create an optional show profile:
 
 ```bash
 cp podguy.example.toml podguy.toml
 ```
 
-The profile can define the show name, hosts, tone, audience, chapter style, and default output preferences. Podguy also accepts `podcast.toml` as a compatible profile name.
-
-You can use podguy without a profile; the agent will only ask for show-specific context when it matters.
-
-## Quick start
-
-Start the dedicated launcher from the repo root:
+Start podguy from the repo root:
 
 ```bash
-cd podguy
 ./podguy
 ```
 
-The launcher starts pi with only the podguy repo skills and startup widget loaded, adds a podguy-specific system hint, and stores sessions under `.pi/sessions`.
-
-If you want the raw pi command instead, `./podguy` is a thin wrapper around pi for this repo.
-
-You should see a short help widget above the editor with example actions.
-
-Then ask pi to work the episode. For example:
+Then ask pi for a concrete episode task:
 
 ```text
 Analyze "episode-006-draft.mp4" as ep006.
 
 Generate chapters for ep006 in timestamp-title format.
 
-Review this episode and suggest cuts, highlight moments, and weak sections.
-```
-
-## Episode workflow
-
-The intended flow is:
-
-1. Start with a new episode recording, draft export, or preview export. Audio and video files are both supported for transcription.
-2. For video episodes, generate timecodes for likely interstitials and inserted content so they are easy to review.
-3. Generate a transcript for the current cut of the episode.
-4. Prepare transcript chunks and an index for pi-driven editorial work.
-5. Use the transcript to propose chapters in this format:
-
-```text
-00:00 Intro
-05:34 Section title
+Find likely TikTok/Shorts clips for ep006 and cut vertical review exports.
 ```
 
-6. Use the transcript to suggest:
-   - cuts for time
-   - strong and weak sections
-   - highlight-worthy clips
-   - exported social/review cuts from selected clip candidates
-   - show notes and references
-   - quote candidates
-   - proper noun or spelling issues
-   - places where interstitials or inserts would help, when video is available
-
-## Quick pass vs full review
-
-When an ask is broad, podguy should clarify between:
-
-- **quick pass** = optional video scan + transcript + prepared transcript artifacts + short summary
-- **full review** = quick pass + chapters + clips + cuts + show notes + quotes + proper noun review
-
-If you ask for one specific deliverable, podguy should do that directly.
-
-## Output location
-
-Podguy writes generated episode artifacts under `dist/analysis/` by default. The entire `dist/` directory is gitignored so transcripts, scans, thumbnails, notes, and local media-derived files stay out of version control.
-
-## Repo skills
+For broad requests, podguy should clarify between:
 
-The repo-local skills are the main interface for this project:
+- **quick pass**: optional video scan + transcript + prepared transcript artifacts + short summary
+- **full review**: quick pass + chapters + clips + cuts + show notes + quotes + proper noun review
 
-- Launcher: [podguy](podguy)
-- Main skill: [src/podguy-post-production/SKILL.md](src/podguy-post-production/SKILL.md)
-- Clip cutting skill: [src/podguy-clip-cutter/SKILL.md](src/podguy-clip-cutter/SKILL.md)
-- Startup widget extension: [src/podguy-startup.ts](src/podguy-startup.ts)
-- Prompt templates: [prompts](prompts)
-- Profile example: [podguy.example.toml](podguy.example.toml)
-- Discovery: [package.json](package.json)
-- Project instructions: [AGENTS.md](AGENTS.md)
-- Underlying tools: [scripts/scan_podcast.swift](scripts/scan_podcast.swift), [scripts/transcribe_video.py](scripts/transcribe_video.py), [scripts/prepare_transcript_analysis.py](scripts/prepare_transcript_analysis.py), [scripts/cut_clips.py](scripts/cut_clips.py)
-
-The launcher and skills explain the user workflow and tell pi how to run the software stack.
-
-## Manual tool reference
-
-You normally use this repo through pi, but the underlying commands are:
+## Common workflows
 
 ### Scan a video
 
-```bash
-swift scripts/scan_podcast.swift <input-video> <output-dir> [sample-interval-seconds]
-```
-
-Example:
-
 ```bash
 swift scripts/scan_podcast.swift "episode-006-draft.mp4" dist/analysis/ep006/scan 0.5
 open dist/analysis/ep006/scan/report.html
 ```
 
+Key outputs:
+
+- `interstitial_candidates.csv`
+- `non_host_candidates.csv`
+- `report.html`
+- `thumbs/`
+
+Scanner results are heuristic review aids, not exact edit points.
+
 ### Transcribe media
 
 ```bash
 uv run python scripts/transcribe_video.py --list-backends
-uv run python scripts/transcribe_video.py <input-media> <output-dir> [options]
-```
-
-Example:
 
-```bash
 uv run --group transcribe-mlx python scripts/transcribe_video.py \
   "episode-006-draft.mp4" \
   dist/analysis/ep006/transcript \
   --backend mlx-whisper
 ```
 
+Key outputs:
+
+- `segments.json`
+- `transcript.txt`
+- `transcript.srt`
+- `transcript.vtt`
+- `summary.txt`
+
+Use `--backend mock` only for tests and setup validation.
+
 ### Prepare transcript artifacts
 
 ```bash
@@ -178,9 +125,16 @@ uv run python scripts/prepare_transcript_analysis.py \
   --plain-output-names
 ```
 
-### Cut selected clip candidates
+Key outputs:
 
-After generating `dist/analysis/ep006/clips.md`, cut original-aspect review exports:
+- `dist/analysis/ep006/transcript_chunks.md`
+- `dist/analysis/ep006/transcript_index.json`
+
+These are the main inputs for chaptering and editorial analysis.
+
+### Cut selected clips
+
+After pi writes `dist/analysis/ep006/clips.md`, cut original-aspect review exports:
 
 ```bash
 uv run python scripts/cut_clips.py \
@@ -201,11 +155,11 @@ uv run python scripts/cut_clips.py \
   --pad-end 1
 ```
 
-The cutter writes generated media plus `manifest.json`. Vertical/square modes use center-crop framing, so treat them as review exports unless the framing has been checked.
+The cutter writes generated media plus `manifest.json`. Vertical and square modes use center-crop framing, so treat them as review exports unless the framing has been checked.
 
-### Download open-license sample media
+### Download real sample media
 
-For a real video-podcast sample, download a local excerpt from Cordkillers 572:
+Use the Cordkillers open-license video-podcast excerpt for local evaluation:
 
 ```bash
 scripts/download_sample_media.sh
@@ -217,31 +171,38 @@ This writes to:
 dist/test-fixtures/open-license/cordkillers-572/
 ```
 
-The script cuts a 3m50s excerpt starting at `00:08:00` from the CC BY-SA 4.0 source video. That range was chosen because it includes multiple podcast layouts, lower thirds, chat/sidebar graphics, a Patreon bumper, and an outro/interstitial card. The script also writes `ATTRIBUTION.md` and keeps all generated media under gitignored `dist/`.
-
-## Docs
-
-- Launcher: [podguy](podguy)
-- Main skill: [src/podguy-post-production/SKILL.md](src/podguy-post-production/SKILL.md)
-- Clip cutting skill: [src/podguy-clip-cutter/SKILL.md](src/podguy-clip-cutter/SKILL.md)
-- Startup widget extension: [src/podguy-startup.ts](src/podguy-startup.ts)
-- Project instructions: [AGENTS.md](AGENTS.md)
-- Profile example: [podguy.example.toml](podguy.example.toml)
-- Scanner CLI: [scripts/scan_podcast.swift](scripts/scan_podcast.swift)
-- Transcript CLI: [scripts/transcribe_video.py](scripts/transcribe_video.py)
-- Transcript prep CLI: [scripts/prepare_transcript_analysis.py](scripts/prepare_transcript_analysis.py)
-- Clip cutter CLI: [scripts/cut_clips.py](scripts/cut_clips.py)
-- Fixture builder: [scripts/make_test_fixture.sh](scripts/make_test_fixture.sh)
-- Open-license sample downloader: [scripts/download_sample_media.sh](scripts/download_sample_media.sh)
-- Test wrapper: [scripts/test.sh](scripts/test.sh)
-- CI workflow: [.github/workflows/ci.yml](.github/workflows/ci.yml)
-- Smoke tests: [tests/test_scan_podcast.sh](tests/test_scan_podcast.sh), [tests/test_transcribe_video.sh](tests/test_transcribe_video.sh), [tests/test_prepare_transcript_analysis.sh](tests/test_prepare_transcript_analysis.sh), [tests/test_cut_clips.sh](tests/test_cut_clips.sh), [tests/test_download_sample_media.sh](tests/test_download_sample_media.sh), [tests/test_launcher.sh](tests/test_launcher.sh)
+The default sample is a 3m50s excerpt from `00:08:00` of Cordkillers 572, licensed CC BY-SA 4.0. The range includes multiple podcast layouts, lower thirds, chat/sidebar graphics, a Patreon bumper, and an outro/interstitial card. The script writes `ATTRIBUTION.md` next to the generated media.
 
-## Contributing
+## Configuration
+
+`podguy.toml` lets you define show-specific context without changing the workflow:
+
+```toml
+show_name = "Example Podcast"
+show_slug = "example"
+hosts = ["Host One", "Host Two"]
+tone = "curious, direct, practical"
+audience = "builders and technical operators"
+chapter_style = "concise descriptive titles"
+preferred_review = "quick pass"
+```
+
+`podcast.toml` is also accepted as a compatible profile name.
 
-Small, focused PRs are welcome.
+## Project layout
 
-Before opening a PR:
+- [`podguy`](podguy): launcher for pi with repo-local skills, prompts, and startup extension.
+- [`src/podguy-post-production/SKILL.md`](src/podguy-post-production/SKILL.md): main editorial workflow skill.
+- [`src/podguy-clip-cutter/SKILL.md`](src/podguy-clip-cutter/SKILL.md): social clip export workflow skill.
+- [`src/podguy-startup.ts`](src/podguy-startup.ts): pi startup widget.
+- [`prompts/`](prompts): optional prompt shortcuts.
+- [`scripts/`](scripts): deterministic scanner, transcript, prep, fixture, sample, and clip-cutting tools.
+- [`tests/`](tests): smoke tests wrapped by Vitest.
+- [`AGENTS.md`](AGENTS.md): repo guidance for coding agents.
+
+## Development
+
+Run the full validation surface:
 
 ```bash
 npm run format:check
@@ -250,17 +211,29 @@ npm run typecheck
 npm test
 ```
 
-You can also run the shell smoke tests directly:
+Run the shell smoke tests directly:
 
 ```bash
 bash scripts/test.sh
 ```
 
-For larger workflow or heuristic changes, open an issue first with the media type, expected vs actual output, and your OS/backend/model details.
+CI runs the same checks on macOS because the scanner depends on macOS media APIs.
+
+## Contributing
+
+Small, focused PRs are welcome. Before opening a PR, run the validation commands above.
+
+For workflow or heuristic changes, include:
+
+- media type and OS/backend details
+- expected vs actual output
+- relevant transcript, scan, or manifest paths when available
+
+See [`CHANGELOG.md`](CHANGELOG.md) for user-visible changes and [`AGENTS.md`](AGENTS.md) for repo maintenance guidance.
 
 ## Security
 
-This repo does not have a published security policy yet. If you find a sensitive issue, do not open a public issue.
+This repo does not have a published security policy yet. If you find a sensitive issue, do not open a public issue. Contact the maintainers privately first.
 
 ## Sponsor
 
@@ -276,8 +249,8 @@ Sponsored by [Modem](https://modem.dev?utm_source=github&utm_medium=oss&utm_camp
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [`LICENSE`](LICENSE).
 
 ## Support
 
-Use GitHub issues for bugs, questions, and workflow discussion once this repo has a public issue tracker.
+Use [GitHub issues](https://github.com/modem-dev/podguy/issues) for bugs, questions, and workflow discussion.
