From 5938b46b68cce45942d3194b948700d1936c53e6 Mon Sep 17 00:00:00 2001 From: Ben Vinegar <2153+benvinegar@users.noreply.github.com> Date: Fri, 12 Jun 2026 21:43:57 -0400 Subject: [PATCH] fix: resolve cross-file consistency issues and doc gaps - standardize the chapters artifact on chapters.md everywhere; the post-production workflow wrote chapters.txt while the YouTube publish workflow looked for chapters.md - point the launcher's "pi is not installed" error at npm install and the renamed @earendil-works/pi-coding-agent package - reduce /phase1 to a thin alias for /full-review and drop it from the startup widget (also dedupe /cut-clips) - give the "no transcription backend found" error actionable uv sync --group commands - document the OAuth test-user step in the README, testing-mode refresh token expiry in the publisher skill, uv first-run venv behavior, and the non-macOS scanner skip rule (AGENTS.md + skill) - move /login guidance to after first launch in Quick start; note that Common workflows commands are reference, not required UX Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 2 +- CHANGELOG.md | 5 ++++ README.md | 14 ++++++----- podguy | 7 +++--- prompts/chapters.md | 2 +- prompts/full-review.md | 2 +- prompts/phase1.md | 34 +-------------------------- scripts/transcribe_video.py | 7 +++++- src/podguy-post-production/SKILL.md | 4 ++-- src/podguy-startup.ts | 2 +- src/podguy-youtube-publisher/SKILL.md | 5 +++- 11 files changed, 34 insertions(+), 50 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f3468e8..6287135 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Default to the `podguy-post-production` workflow unless the user explicitly asks - reuse existing analysis outputs when they already match the requested episode/version - treat scanner results as heuristic review aids, not exact edit points - support audio-only files, video drafts, preview exports, and final renders -- skip the visual scanner for audio-only inputs +- skip the visual scanner for audio-only inputs and on non-macOS systems (it requires Swift/AVFoundation); say why when skipping - use transcript evidence and timecodes whenever possible when giving editorial feedback - treat generated clip media as review exports, not final mastered social edits - never upload to YouTube without explicit user confirmation of the final metadata; default uploads to private diff --git a/CHANGELOG.md b/CHANGELOG.md index 8cad42d..965362e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,3 +12,8 @@ All notable user-visible changes to this project are documented in this file. ### Changed ### Fixed + +- Standardize the chapters artifact on `dist/analysis//chapters.md` so the chapters and YouTube publish workflows agree. +- Correct the launcher's "pi is not installed" message to point at `npm install` and the renamed `@earendil-works/pi-coding-agent` package. +- Document the OAuth test-user requirement, testing-mode token expiry, uv first-run behavior, and the macOS-only scanner skip rule. +- Give the "no transcription backend found" error actionable `uv sync --group ...` commands. diff --git a/README.md b/README.md index 61f34c0..31c5926 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,8 @@ brew install uv ffmpeg 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. +- `uv` runs the Python scripts and optional transcription dependency groups. The first `uv` command creates a local `.venv/` and may download Python automatically — this is normal and only happens once. +- The video scanner is macOS-only and uses Swift / AVFoundation / Vision. Everything else works cross-platform (Linux: install `uv` and `ffmpeg` via your package manager). Set up a real transcription backend when you are ready to transcribe episodes: @@ -62,6 +60,8 @@ Start podguy from the repo root: ./podguy ``` +On first launch, type `/login` inside pi to connect your model provider (or use your usual API key setup). + Then ask pi for a concrete episode task: ```text @@ -79,6 +79,8 @@ For broad requests, podguy should clarify between: ## Common workflows +You don't need to memorize these — pi runs them for you when you ask in natural language. They're here for reference and debugging. + ### Scan a video ```bash @@ -160,7 +162,7 @@ The cutter writes generated media plus `manifest.json`. Vertical and square mode ### Publish to YouTube -One-time setup: create a Google Cloud project with the YouTube Data API v3 enabled, create a Desktop-app OAuth client, save the JSON to `~/.config/podguy/youtube/client_secret.json`, then authenticate: +One-time setup: create a Google Cloud project with the YouTube Data API v3 enabled, create a Desktop-app OAuth client, and save the downloaded JSON to `~/.config/podguy/youtube/client_secret.json`. On the OAuth consent screen, keep the app in Testing mode and add your own Google account as a test user — otherwise the auth flow fails with `access_denied`. Then authenticate: ```bash uv sync --group youtube @@ -208,7 +210,7 @@ hosts = ["Host One", "Host Two"] tone = "curious, direct, practical" audience = "builders and technical operators" chapter_style = "concise descriptive titles" -preferred_review = "quick pass" +preferred_review = "quick_pass" ``` `podcast.toml` is also accepted as a compatible profile name. diff --git a/podguy b/podguy index 7377fb1..d917a09 100755 --- a/podguy +++ b/podguy @@ -14,9 +14,10 @@ else cat >&2 <<'EOF' error: pi is not installed. -Install it with one of: - npm install -g @mariozechner/pi-coding-agent - npm install --save-dev @mariozechner/pi-coding-agent +From the repo root, run: + npm install + +(or install globally: npm install -g @earendil-works/pi-coding-agent) Then run ./podguy again. EOF diff --git a/prompts/chapters.md b/prompts/chapters.md index 365e3a7..6d77fbf 100644 --- a/prompts/chapters.md +++ b/prompts/chapters.md @@ -11,7 +11,7 @@ Workflow: `uv run python scripts/prepare_transcript_analysis.py --output-dir dist/analysis/ --slug --plain-output-names` 3. Read the prepared transcript artifacts. For long transcripts, use the chunk index first and then inspect the most relevant chunk sections. 4. Decide chapter boundaries and titles with pi-driven judgment. Use `chapter_style` from `podguy.toml` or `podcast.toml` when present. -5. Write the final chapter block to `dist/analysis//chapters.txt`. +5. Write the final chapter block to `dist/analysis//chapters.md`. 6. Reply with the output path and the final chapter block. Formatting rules: diff --git a/prompts/full-review.md b/prompts/full-review.md index d15936e..245e699 100644 --- a/prompts/full-review.md +++ b/prompts/full-review.md @@ -20,7 +20,7 @@ Workflow: - `dist/analysis//transcript_chunks.md` - `dist/analysis//transcript_index.json` 5. Produce these outputs under `dist/analysis//`: - - `dist/analysis//chapters.txt` + - `dist/analysis//chapters.md` - `dist/analysis//clips.md` - `dist/analysis//cut_report.md` - `dist/analysis//show_notes.md` diff --git a/prompts/phase1.md b/prompts/phase1.md index 6830f21..087d171 100644 --- a/prompts/phase1.md +++ b/prompts/phase1.md @@ -2,36 +2,4 @@ description: Compatibility alias for the full podguy transcript and editorial review workflow --- -Run the full podguy review workflow for: $@ - -`/phase1` is kept as a compatibility shortcut. Prefer `/full-review` for new usage. - -Goal: - -- use pi for editorial judgment -- use repo scripts only for deterministic prep and formatting support -- use `podguy.toml` or `podcast.toml` show context when present - -Workflow: - -1. Identify the media file, transcript output directory, prepared transcript artifacts, and target episode slug. -2. If the transcript does not exist yet, ask for the media file/transcript directory or offer the exact `scripts/transcribe_video.py` command needed. -3. Ensure prepared transcript artifacts exist. If needed, run: - `uv run python scripts/prepare_transcript_analysis.py --output-dir dist/analysis/ --slug --plain-output-names` -4. Ground all editorial work in the prepared artifacts: - - `dist/analysis//transcript_chunks.md` - - `dist/analysis//transcript_index.json` -5. Produce these outputs under `dist/analysis//`: - - `dist/analysis//chapters.txt` - - `dist/analysis//clips.md` - - `dist/analysis//cut_report.md` - - `dist/analysis//show_notes.md` - - `dist/analysis//quotes.md` - - `dist/analysis//proper_nouns.md` -6. Write the outputs to disk and summarize what was generated. - -Rules: - -- Keep judgment in pi; do not try to replace it with repo-local heuristics. -- Reuse existing prepared artifacts when they already match the requested transcript. -- If something is ambiguous, ask a short clarifying question before writing files. +`/phase1` is a compatibility alias. Follow the `/full-review` workflow for: $@ diff --git a/scripts/transcribe_video.py b/scripts/transcribe_video.py index 18402de..985aa30 100755 --- a/scripts/transcribe_video.py +++ b/scripts/transcribe_video.py @@ -91,7 +91,12 @@ def choose_backend(requested: str) -> str: return name raise SystemExit( - "no transcription backend found. Install one of: mlx-whisper, faster-whisper, or whisper. " + "no transcription backend found.\n" + "Install one and re-run with the matching dependency group, e.g.:\n" + " uv sync --group transcribe-mlx\n" + " uv run --group transcribe-mlx python scripts/transcribe_video.py ...\n" + "(groups: transcribe-mlx for Apple Silicon, transcribe-faster cross-platform, " + "transcribe-whisper for OpenAI Whisper)\n" "Or run the smoke test with --backend mock." ) diff --git a/src/podguy-post-production/SKILL.md b/src/podguy-post-production/SKILL.md index 1d0c1a7..8deb2aa 100644 --- a/src/podguy-post-production/SKILL.md +++ b/src/podguy-post-production/SKILL.md @@ -63,7 +63,7 @@ For synthetic or test fixture inputs, default to a leaner evaluation mindset and ### Quick pass 1. Start from the input media file. It can be audio or video as long as `scripts/transcribe_video.py` can process it. -2. If the input is video, optionally run the visual scanner to find likely interstitials and other non-host inserts. Skip this for audio-only inputs. +2. If the input is video and you are on macOS, optionally run the visual scanner to find likely interstitials and other non-host inserts. Skip this for audio-only inputs and on non-macOS systems (say why when skipping). 3. Run the transcript tool on the same media file. 4. Prepare deterministic transcript artifacts for pi with `scripts/prepare_transcript_analysis.py`. 5. Return a short grounded summary with: @@ -105,7 +105,7 @@ Recommended single-show pattern: - `dist/analysis//transcript_large/` when keeping multiple transcript variants - `dist/analysis//transcript_chunks.md` - `dist/analysis//transcript_index.json` -- `dist/analysis//chapters.txt` +- `dist/analysis//chapters.md` - `dist/analysis//clips.md` - `dist/analysis//clips/cuts/` - `dist/analysis//clips/shorts/` diff --git a/src/podguy-startup.ts b/src/podguy-startup.ts index 12572eb..9e1a1d0 100644 --- a/src/podguy-startup.ts +++ b/src/podguy-startup.ts @@ -134,7 +134,7 @@ export default function podguyStartupExtension(pi: ExtensionAPI) { "- Full review = quick pass + chapters + clips + cuts + notes + quotes + cleanup", "- Cut social exports after clips exist: /cut-clips ep006", "- Upload finished episodes to YouTube: /publish-youtube ep006", - "- Optional shortcuts: /phase1 ep006 | /full-review ep006 | /chapters ep006 | /cuts ep006 | /cut-clips ep006 | /publish-youtube ep006", + "- Optional shortcuts: /full-review ep006 | /chapters ep006 | /clips ep006 | /cuts ep006 | /show-notes ep006", ]); }); diff --git a/src/podguy-youtube-publisher/SKILL.md b/src/podguy-youtube-publisher/SKILL.md index bda2365..b427beb 100644 --- a/src/podguy-youtube-publisher/SKILL.md +++ b/src/podguy-youtube-publisher/SKILL.md @@ -29,7 +29,10 @@ uv run --group youtube python scripts/youtube_publish.py auth The token is cached at `~/.config/podguy/youtube/token.json`. Both paths can be overridden with `--client-secrets` / `--token` or `PODGUY_YT_CLIENT_SECRETS` / `PODGUY_YT_TOKEN`. -Personal-channel projects can stay in OAuth "testing" mode with the user's account added as a test user. Warn the user: videos uploaded through unverified API projects may be locked private until the project passes a YouTube API audit, so verify scheduling behavior before relying on it. +Personal-channel projects can stay in OAuth "testing" mode with the user's account added as a test user. Two caveats to surface: + +- Videos uploaded through unverified API projects may be locked private until the project passes a YouTube API audit, so verify scheduling behavior before relying on it. +- While the OAuth app is in Testing mode, Google expires refresh tokens after about 7 days; expect to re-run the `auth` command periodically (or move the consent screen to "In production" to stop the expiry). ## Inputs to gather