fix: resolve cross-file consistency issues and doc gaps (#5)

- 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) <noreply@anthropic.com>

Author: benvinegar

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

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/<slug>/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.

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.

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

prompts/chapters.md

@@ -11,7 +11,7 @@ Workflow:
    `uv run python scripts/prepare_transcript_analysis.py <transcript-dir> --output-dir dist/analysis/<slug> --slug <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/<slug>/chapters.txt`.
+5. Write the final chapter block to `dist/analysis/<slug>/chapters.md`.
 6. Reply with the output path and the final chapter block.
 
 Formatting rules:

prompts/full-review.md

@@ -20,7 +20,7 @@ Workflow:
    - `dist/analysis/<slug>/transcript_chunks.md`
    - `dist/analysis/<slug>/transcript_index.json`
 5. Produce these outputs under `dist/analysis/<slug>/`:
-   - `dist/analysis/<slug>/chapters.txt`
+   - `dist/analysis/<slug>/chapters.md`
    - `dist/analysis/<slug>/clips.md`
    - `dist/analysis/<slug>/cut_report.md`
    - `dist/analysis/<slug>/show_notes.md`

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 <transcript-dir> --output-dir dist/analysis/<slug> --slug <slug> --plain-output-names`
-4. Ground all editorial work in the prepared artifacts:
-   - `dist/analysis/<slug>/transcript_chunks.md`
-   - `dist/analysis/<slug>/transcript_index.json`
-5. Produce these outputs under `dist/analysis/<slug>/`:
-   - `dist/analysis/<slug>/chapters.txt`
-   - `dist/analysis/<slug>/clips.md`
-   - `dist/analysis/<slug>/cut_report.md`
-   - `dist/analysis/<slug>/show_notes.md`
-   - `dist/analysis/<slug>/quotes.md`
-   - `dist/analysis/<slug>/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: $@

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."
     )
 

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/<episode>/transcript_large/` when keeping multiple transcript variants
 - `dist/analysis/<episode>/transcript_chunks.md`
 - `dist/analysis/<episode>/transcript_index.json`
-- `dist/analysis/<episode>/chapters.txt`
+- `dist/analysis/<episode>/chapters.md`
 - `dist/analysis/<episode>/clips.md`
 - `dist/analysis/<episode>/clips/cuts/`
 - `dist/analysis/<episode>/clips/shorts/`

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",
     ]);
   });