Add device-authorized hosted agent skills

[devhims]

Summary

This PR adds three distinct agent skills and the authenticated CLI boundary used by the two hosted skills:

• youtube-direct is self-contained and performs stateless YouTube search and extraction directly from the user's machine. It requires no video2ctx account, hosted API, API key, or separately installed CLI.
• video2ctx-api covers stateless reads through the supported video2ctx hosted API, including managed caching, account information, and usage.
• video2ctx-monitoring is the stateful exception for monitors, schedules, notifications, and delivery preferences.
• @video2ctx/cli@0.1.0 provides browser device login, whoami, auth status, logout, credential storage, and authenticated hosted-API transport for the two hosted skills. It is now published publicly and versioned independently from the skills.

The hosted skills follow the separate CLI + skill model: they teach agents how to use video2ctx, while authentication and transport remain in the CLI. They do not bundle a private copy of it.

Why

The direct and hosted surfaces solve different problems:

• Use youtube-direct for unauthenticated, local, stateless YouTube access.
• Use video2ctx-api for production-supported hosted endpoints, managed caching, account boundaries, and usage tracking.
• Use video2ctx-monitoring for recurring, stateful monitoring workflows.

For hosted access, device authorization avoids asking an agent to handle a long-lived API key while retaining API keys as an explicit alternative for automation and existing integrations.

Better Auth integration

No separate Better Auth device-auth package was installed. The repository already depended on better-auth@1.6.26 and @better-auth/api-key@1.6.26.

This PR activates plugins included with the existing core better-auth package:

• deviceAuthorization() implements the server-side OAuth device-code flow.
• deviceAuthorizationClient() lets the web application approve or deny a device request.
• bearer() accepts the resulting Better Auth session token through Authorization: Bearer <token>.

@better-auth/api-key remains the existing implementation for aty_... API keys; it was not introduced for CLI device login.

Application-owned work around Better Auth includes:

• client and scope validation for video2ctx-cli with data:read account:access
• the deviceCode D1 migration
• the /device browser approval experience
• CLI code issuance, polling, timeouts, local credential storage, logout, and revocation
• authorization boundaries separating browser sessions, CLI sessions, and API keys

CLI sessions may read supported data, account information, usage, and monitoring resources. Browser-only operations remain blocked, including API-key management, billing, connected accounts, account deletion, and administration.

Suggested review order

The diff contains many generated and mechanical files, so a practical review sequence is:

1. Architecture and skill boundaries
   • .agents/skills/README.md
   • .agents/skills/*/SKILL.md
   • reference/agents/platform-internals.md
2. Better Auth and authorization boundaries
   • platform/src/lib/auth.ts
   • platform/src/middlewares/authentication.ts
   • platform/migrations/0013_device_authorization.sql
3. Hosted CLI
   • packages/video2ctx-cli/src/
   • packages/video2ctx-cli/package.json
   • packages/video2ctx-cli/README.md
4. Browser approval flow
   • web/app/device/
   • web/lib/device-authorization.ts
5. Integration and E2E coverage
   • platform/test/auth-worker.integration.test.ts
   • platform/test/e2e/auth-device.spec.ts
   • platform/scripts/start-auth-e2e-worker.mjs
6. Generated and mechanical files last
   • .agents/skills/youtube-direct/scripts/youtube.mjs
   • package lockfiles
   • docs/api-reference/openapi.json

Validation

All current PR checks pass.

• clean dependency installation for the library, hosted CLI, platform, and web workspaces
• all-things-youtube: build, tests, CLI behavior, and skill-bundle staleness check
• @video2ctx/cli: 13 unit tests, build, help/version smoke tests, and npm pack --dry-run
• platform unit tests and YouTube processor tests
• Worker/D1 integration coverage for device-code issuance, browser approval, token exchange, permission boundaries, replay rejection, logout, and revocation
• Chromium E2E covering the built CLI, real Next.js approval page, whoami, usage, monitor listing, logout, credential removal, and action-button contrast
• web tests and production build
• generated docs, OpenAPI audience checks, broken-link checks, MDX accessibility checks, and skill validation

Preview-backed release test

The complete pending preview migration sequence (0006 through 0013) was applied to the shared Cloudflare preview D1 database. The deviceCode table is present.

Because the platform's D1, KV, R2, queues, workflows, Durable Objects, and containers are not all safely isolated in an automatic branch deployment, the branch was run locally while connected to the remote preview D1 and KV resources. The web approval page and Worker ran locally, and the YouTube processor ran in Docker.

The registry-published @video2ctx/cli@0.1.0 was then installed anonymously into a clean temporary prefix and tested against that stack. It:

• reported version 0.1.0 from the installed video2ctx binary
• automatically opened the browser approval URL
• authenticated thinktank.himanshu@gmail.com
• passed auth status, whoami, usage, monitor-list, and provider-list requests
• rendered the primary approval action with black background and white text
• revoked the test session successfully on logout

This is a real preview-resource smoke test, but not a public HTTPS deployment test of the platform Worker.

Rollout state and required follow-up

State checked on 2026-08-17:

• CLI: @video2ctx/cli@0.1.0 is public on npm and its clean registry installation is verified.
• Preview D1: migrations through 0013_device_authorization.sql are applied and the flow is verified.
• Production D1: 0013_device_authorization.sql remains pending; production was not modified.
• Production application: the device-auth platform and web changes are not deployed until this PR is merged and released.

Recommended remaining rollout order:

1. Complete review and merge this PR.
2. Apply production migration 0013_device_authorization.sql immediately before deploying the platform code that uses it.
3. Deploy the platform and web changes.
4. Smoke-test the installed npm CLI against the production HTTPS flow, including approval, whoami, logout, and revocation.
5. Treat the hosted skills as released only after that production verification.

The npm package is available now, but its default production login flow depends on the server and web changes in this PR being deployed.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
video2ctx	🟢 Ready	View Preview	Aug 15, 2026, 5:19 PM

💡 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 16, 2026 5:55pm