merge: captions-first YouTube VideoSource (Worker C, agent/youtube-source)

docs/homelab-integration.md

@@ -69,6 +69,11 @@ This maps directly onto the copied `llm` package: `Client` is the OpenAI-compati
 - **Exact ref format / vault item naming for Tapir:** **confirm / decide during build.** Follow
   the pattern existing services use (e.g. how `gitea-mcp` references `GITEA_MCP_DEFAULT_TOKEN`)
   rather than inventing a new scheme.
+  - **Adapter status (YouTube):** the YouTube `VideoSource` adapter does **not** assume a scheme.
+    The OAuth refresh-token reference is an opaque `Config.TokenSecretRef` resolved through the
+    `SecretStore` port (`youtube.New(cfg, secrets)`). Pinning the actual vault-item name only
+    changes wiring/config, not the adapter — so this `confirm` does not block the adapter. Decide
+    the name when wiring the live connection and record it here.
 
 ## Hosts (for reference)
 
@@ -106,7 +111,17 @@ homelab's actual `GOPROXY`/`GONOSUMCHECK` policy here once known would remove th
 - `koala:4000` (or the NodePort / post-relocation address) — LiteLLM gateway, the Primary.
 - brain-mcp host (`*-mcp.d-ma.be`, **confirm**) — only when the brain sink is enabled.
 - `www.googleapis.com` / YouTube Data API + `oauth2.googleapis.com` (token exchange/refresh) —
-  the YouTube provider adapter.
+  the YouTube provider adapter (`internal/adapters/youtube`). OAuth is hand-rolled on
+  `golang.org/x/oauth2` (ADR-006); the Google token endpoint is hardcoded inline to avoid the
+  heavy `golang.org/x/oauth2/google` dependency.
+  - **`confirm` — captions.download ownership limitation.** The Data API `captions.download`
+    endpoint only authorizes the *owner* of the video; for arbitrary subscribed channels it
+    typically returns `403`. The adapter lists tracks via `captions.list` (no track → `SourceNone`,
+    ADR-007) and downloads the selected track as WebVTT; a download failure surfaces as an error
+    (retryable), not a silent skip. If the owner-only limit proves blocking in practice, the
+    fallback is the unofficial `timedtext` endpoint or the deferred STT path (ADR-007) — a new
+    ADR, not a default. Verify against a real non-owned video before relying on live caption
+    download.
 - `api.vimeo.com` — the Vimeo provider adapter.
 - BYO-AI endpoints, per configured provider and **only when a user opts in**:
   `api.anthropic.com`, `api.openai.com`, `generativelanguage.googleapis.com`.