feat: add YouTube publisher skill and upload CLI (#4)

* feat: add YouTube publisher skill and upload CLI

Add scripts/youtube_publish.py, a YouTube Data API v3 CLI with OAuth
auth, resumable uploads, thumbnails, SRT captions, playlists, scheduled
publishing, status checks, and metadata updates. Uploads default to
private and support --dry-run previews.

Add the podguy-youtube-publisher skill and /publish-youtube prompt so pi
composes titles, descriptions, chapters, and tags from existing analysis
artifacts, plus a [youtube] profile section for show defaults and a
youtube uv dependency group. Wire the skill into the startup header and
add a smoke test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: address code review findings in youtube_publish.py

- carry defaultLanguage through videos.update so it is not wiped
- validate 5000-char description limit in the update path
- print 100% on the final upload chunk
- include video_id in playlist/thumbnail/caption failure messages
- re-apply 0600 mode after token refresh writes
- require seconds in --publish-at timestamps
- strip whitespace-only playlist_id profile values
- document update --description-file asymmetry and TOML fallback limits

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix: address second-pass review findings

- make the TOML fallback parser quote-aware when stripping # comments so
  hashtags in quoted values (e.g. description_footer) survive
- only enforce the 5000-char description limit in update when the
  description is actually being changed
- cover the hashtag-footer case in the smoke test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: benvinegar

AGENTS.md

@@ -2,7 +2,7 @@
 
 This repository is primarily operated through `pi` for podcast post-production work.
 
-Default to the `podguy-post-production` workflow unless the user explicitly asks for something else. Use `podguy-clip-cutter` when the user asks to export or cut social clips.
+Default to the `podguy-post-production` workflow unless the user explicitly asks for something else. Use `podguy-clip-cutter` when the user asks to export or cut social clips. Use `podguy-youtube-publisher` when the user asks to upload, schedule, or manage episodes on YouTube.
 
 ## Primary tasks
 
@@ -12,6 +12,7 @@ Default to the `podguy-post-production` workflow unless the user explicitly asks
 - give editorial feedback such as cuts, highlights, weak sections, and insert opportunities
 - cut selected highlight moments into review exports for TikTok, Reels, YouTube Shorts, trailers, or social posts
 - draft publishing assets such as show notes, quote sheets, and proper noun review
+- upload finished episodes to YouTube with metadata composed from analysis artifacts
 
 ## Podcast profile
 
@@ -28,6 +29,7 @@ Default to the `podguy-post-production` workflow unless the user explicitly asks
 - skip the visual scanner for audio-only inputs
 - 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
 - use `scripts/download_sample_media.sh` when a real open-license video-podcast sample is helpful; keep downloaded samples under gitignored `dist/`
 
 ## Interaction guidance
@@ -55,10 +57,12 @@ For synthetic or test fixture inputs, default to a leaner evaluation mindset:
 - Startup extension: `src/podguy-startup.ts`
 - Post-production skill: `src/podguy-post-production/SKILL.md`
 - Clip-cutter skill: `src/podguy-clip-cutter/SKILL.md`
+- YouTube publisher skill: `src/podguy-youtube-publisher/SKILL.md`
 - Transcript CLI: `scripts/transcribe_video.py`
 - Transcript prep CLI: `scripts/prepare_transcript_analysis.py`
 - Scanner CLI: `scripts/scan_podcast.swift`
 - Clip cutter CLI: `scripts/cut_clips.py`
+- YouTube publisher CLI: `scripts/youtube_publish.py`
 
 ## Validation commands
 

CHANGELOG.md

@@ -7,6 +7,7 @@ All notable user-visible changes to this project are documented in this file.
 ### Added
 
 - Add CI and local maintenance scripts for formatting, linting, typechecking, and smoke tests.
+- Add YouTube publishing: `scripts/youtube_publish.py` CLI (OAuth, resumable uploads, thumbnails, captions, playlists, scheduled publishing), the `podguy-youtube-publisher` skill, a `/publish-youtube` prompt shortcut, and a `[youtube]` profile section.
 
 ### Changed
 

README.md

@@ -12,6 +12,7 @@ Pi-first post-production tooling for podcast and video-podcast editors who want
 - 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.
+- Uploads finished episodes to YouTube with metadata composed from analysis artifacts.
 
 Generated transcripts, scans, thumbnails, notes, and clip exports go under gitignored `dist/` by default.
 
@@ -157,6 +158,29 @@ uv run python scripts/cut_clips.py \
 
 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.
 
+### 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:
+
+```bash
+uv sync --group youtube
+uv run --group youtube python scripts/youtube_publish.py auth
+```
+
+Upload an episode (private by default; use `--dry-run` first to preview the request):
+
+```bash
+uv run --group youtube python scripts/youtube_publish.py upload \
+  "episode-006-final.mp4" \
+  --title "Ep 6: Why this market flipped" \
+  --description-file dist/analysis/ep006/youtube-description.md \
+  --chapters-file dist/analysis/ep006/chapters.md
+```
+
+Other subcommands cover thumbnails, SRT captions, playlists, scheduled publishing (`--publish-at`), status checks, and metadata updates. Defaults like privacy, category, tags, and a description footer come from the `[youtube]` section of `podguy.toml`.
+
+Each upload costs 1600 of the default 10000 daily YouTube API quota units, and videos uploaded through unverified API projects may stay locked private until the project passes a YouTube API audit.
+
 ### Download real sample media
 
 Use the Cordkillers open-license video-podcast excerpt for local evaluation:
@@ -194,9 +218,10 @@ preferred_review = "quick pass"
 - [`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-youtube-publisher/SKILL.md`](src/podguy-youtube-publisher/SKILL.md): YouTube upload 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.
+- [`scripts/`](scripts): deterministic scanner, transcript, prep, fixture, sample, clip-cutting, and YouTube publishing tools.
 - [`tests/`](tests): smoke tests wrapped by Vitest.
 - [`AGENTS.md`](AGENTS.md): repo guidance for coding agents.
 

podguy.example.toml

@@ -24,3 +24,12 @@ preferred_model = ""
 [video_scan]
 enabled = true
 sample_interval_seconds = 0.5
+
+[youtube]
+# Defaults for scripts/youtube_publish.py; flags override these.
+default_privacy = "private"
+default_category = "22"
+default_tags = []
+playlist_id = ""
+description_footer = ""
+made_for_kids = false

prompts/publish-youtube.md

@@ -0,0 +1,26 @@
+---
+description: Upload an episode video to YouTube with metadata drafted from analysis artifacts
+---
+
+Publish to YouTube: $@
+
+Workflow:
+
+1. Identify the episode slug and the final episode video file (a real export, not a review cut).
+2. Check auth: if `~/.config/podguy/youtube/token.json` is missing, walk through the one-time setup in the `podguy-youtube-publisher` skill before anything else.
+3. Draft metadata from existing artifacts and the `[youtube]` section of `podguy.toml`:
+   - Title (max 100 characters) from show notes or the user's wording.
+   - Description body written to `dist/analysis/<slug>/youtube-description.md`.
+   - Chapters from `dist/analysis/<slug>/chapters.md` when present (first chapter must start at `00:00`).
+   - Tags from proper-noun review or profile `default_tags`.
+4. Show the user the drafted metadata and confirm privacy/timing (private default, unlisted, public, or `--publish-at`).
+5. Preview the request with `--dry-run`, then upload:
+   `uv run --group youtube python scripts/youtube_publish.py upload <video> --title "<title>" --description-file dist/analysis/<slug>/youtube-description.md --chapters-file dist/analysis/<slug>/chapters.md`
+6. Add `--thumbnail`, `--caption <transcript.srt>`, `--playlist-id`, or `--publish-at` as requested.
+7. Confirm with `status <video-id>` and report the YouTube Studio link.
+
+Output expectations:
+
+- Never upload without the user confirming the final metadata.
+- State the resulting privacy status plainly (private/scheduled/public) and link YouTube Studio.
+- Surface quota or processing errors directly instead of retrying silently.

pyproject.toml

@@ -9,6 +9,7 @@ dependencies = []
 transcribe-mlx = ["mlx-whisper>=0.4.3"]
 transcribe-faster = ["faster-whisper"]
 transcribe-whisper = ["openai-whisper"]
+youtube = ["google-api-python-client>=2.100", "google-auth-oauthlib>=1.0"]
 
 [tool.uv]
 package = false

scripts/test.sh

@@ -8,5 +8,6 @@ bash tests/test_transcribe_video.sh
 bash tests/test_prepare_transcript_analysis.sh
 bash tests/test_scan_podcast.sh
 bash tests/test_cut_clips.sh
+bash tests/test_youtube_publish.sh
 bash tests/test_download_sample_media.sh
 bash tests/test_launcher.sh