Improve YouTube skill routing and transcript transport

[devhims]

What changed

• Starts ordinary one-off public YouTube requests with youtube-direct, automatically continues with video2ctx-api if direct access fails, and routes account, usage, and managed hosted workflows directly to the hosted skill.
• Replaces redundant hosted identity checks with one video2ctx whoami --json call and adds tested common-route recipes so agents do not discover the known YouTube provider or fetch documentation on every request.
• Adds compact transcript formats (text, segments, and words) to the direct skill CLI and hosted API while preserving the hosted API's existing rich response when format is omitted.
• Adds video2ctx transcript <url-or-id> to @video2ctx/cli, bumps it to 0.2.0, and gives hosted data calls a 150-second default deadline with bounded overrides.
• Emits classified JSON errors on stderr and retries idempotent GET requests only for 429/503, honoring Retry-After; mutations are never retried.
• Updates OpenAPI, generated docs, skill selector metadata, package docs, and the committed direct-skill bundle.

Why

Black-box agent tests showed that an installed hosted CLI nudged agents toward video2ctx-api even for simple public transcript summaries. The hosted path also required avoidable discovery and documentation calls, returned unnecessarily large word-timing payloads, used a 30-second deadline below the platform's processor budget, and reduced API failures to prose.

This change keeps the zero-account direct path first without turning hosted access into a manual decision gate. The hosted path remains an automatic fallback and the direct route for account and usage operations.

Validation

• npm test (25 library tests passed, 178 platform tests passed, 7 processor tests passed; one opt-in live library test skipped)
• npm run build (library, CLI, platform TypeScript, and Next.js production build)
• npm --prefix packages/video2ctx-cli run verify (18 tests, build, version, and help)
• npm run skill:check
• Agent Skill quick_validate.py for all three skills
• npm run docs:check
• npm run docs:verify under Node 22 (Mint validate, broken links, and accessibility)
• npm pack --dry-run for @video2ctx/cli@0.2.0

Deliberately deferred

• Composite context commands or API endpoints
• Server-side summarization
• Generic output selectors or output-file flags
• Low-priority pretty-printing and additional subcommand help

This PR does not publish @video2ctx/cli@0.2.0; publishing remains a separate release step after review and deployment.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
video2ctx	🟢 Ready	View Preview	Aug 17, 2026, 8:43 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
video2ctx-web	Ready	Preview	Aug 17, 2026 9:07am