devhims · devhims · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/.agents/skills/README.md b/.agents/skills/README.md
@@ -4,11 +4,11 @@ Three [Agent Skills](https://agentskills.io) for working with YouTube data — d
 
 | Skill | Reach for it when | Needs |
 | --- | --- | --- |
-| `youtube-direct` | You want stateless YouTube search or extraction directly from the user's machine, with no account, package installation, or hosted dependency | Node.js 18.17+ |
-| `video2ctx-api` | You want the managed, authenticated alternative: supported endpoints, caching, credit accounting, account identity, and usage reads over the hosted API | `video2ctx` CLI plus browser login or an `aty_` API key |
+| `youtube-direct` | You want an ordinary one-off public YouTube search, transcript summary, or extraction directly from the user's machine | Node.js 18.17+ |
+| `video2ctx-api` | You need account or usage details, the managed hosted API, caching and credit accounting, or an automatic fallback after direct access fails | `video2ctx` CLI plus browser login or an `aty_` API key |
 | `video2ctx-monitoring` | You want the stateful exception: watch a channel, topic, or search for new videos and consume the resulting notifications | `video2ctx` CLI plus browser login or an `aty_` API key |
 
-The split follows real boundaries: `youtube-direct` is a self-contained direct executable with no account; `video2ctx-api` is the managed, authenticated option for stateless hosted discovery, caching, usage, and account boundaries; `video2ctx-monitoring` is the deliberate stateful exception. Most users need only one of the first two data skills.
+The split follows real boundaries: start ordinary stateless public data with the self-contained `youtube-direct` executable, then continue with `video2ctx-api` automatically if direct access fails. Route account and usage details, managed hosted workflows, and caching directly to `video2ctx-api`. `video2ctx-monitoring` is the deliberate stateful exception.
 
 ## Install
 

diff --git a/.agents/skills/video2ctx-api/SKILL.md b/.agents/skills/video2ctx-api/SKILL.md
@@ -1,62 +1,76 @@
 ---
 name: video2ctx-api
-description: Managed, authenticated YouTube search and extraction through the production video2ctx hosted API. Use instead of youtube-direct for supported endpoints, managed caching, usage and credit tracking, or account identity. Includes search, browse, transcripts, caption tracks, comments, video details, end screens, channels, and playlists. Requires the video2ctx CLI plus browser login or an aty_ API key; monitoring has its own skill.
+description: Managed, authenticated YouTube search and extraction through the production video2ctx hosted API. Use for account identity, usage and credit data, managed caching or infrastructure, an explicitly hosted workflow, or automatically when a youtube-direct operation fails. Includes stateless search, browse, transcripts, caption tracks, comments, video details, end screens, channels, and playlists. Start ordinary one-off public YouTube requests with youtube-direct; monitoring has its own skill.
 license: Apache-2.0
 ---
 
 # video2ctx API
 
-Use the installed `video2ctx` CLI for authenticated requests to `https://api.video2ctx.dev`.
+Use the installed `video2ctx` CLI for authenticated requests to `https://api.video2ctx.dev`. Route account and usage requests here immediately. When `youtube-direct` fails, continue here without asking the user to choose a fallback.
 
-## Check the CLI
+## Check the CLI and identity
 
-Run `video2ctx --version`. When the command is unavailable, explain that this hosted skill requires the public `@video2ctx/cli` npm package and ask the user to approve its installation. After approval, run:
+Run `video2ctx --version`. When unavailable, explain that this hosted skill requires the public `@video2ctx/cli` npm package and ask the user to approve its installation. After approval, run:
 
 ```bash
 npm install --global @video2ctx/cli
 ```
 
-Confirm `video2ctx --version` succeeds before continuing. Use that installed command for every request so authentication and versioning stay stable.
+Then run one identity check:
 
-## Authenticate
+```bash
+video2ctx whoami --json
+```
 
-1. Run `video2ctx auth status --json`.
-2. When unauthenticated, run `video2ctx auth login`. Relay the displayed URL and code if the user must continue in a browser. Use `--no-browser` only when opening a browser is unavailable.
-3. Confirm access with `video2ctx whoami --json`.
+If it reports `AUTHENTICATION_REQUIRED`, run `video2ctx auth login`, let the user approve the displayed device code in their browser, and retry `video2ctx whoami --json`. Do not run `auth status` before `whoami`; both resolve the same remote account.
 
-The login flow stores a revocable CLI session in the user's local config with private file permissions. Keep the session out of prompts, logs, screenshots, and source control. The CLI also accepts `VIDEO2CTX_API_KEY` as a non-interactive fallback and gives it precedence over the stored session. Have the user create and configure a personal key at `https://video2ctx.dev/dashboard/developer` when they prefer that mode; never ask them to paste it into the conversation.
+The browser flow stores a revocable CLI session in the user's private local config. The CLI also accepts `VIDEO2CTX_API_KEY` as a non-interactive fallback and gives it precedence over the stored session. The user can create a personal key at `https://video2ctx.dev/dashboard/developer`; never ask them to paste a credential into the conversation.
 
-## Make requests
+## Use the shortest route
 
-Run public operations through:
+For a known YouTube URL or video ID, fetch compact transcript text in one data request:
 
-```text
-video2ctx api GET '/v1/path?encoded=query' --include-meta
+```bash
+video2ctx transcript '<youtube-url-or-id>' --format text --include-meta
 ```
 
-Use `--data '<json>'` only for a documented request body. `--include-meta` returns the response under `data` and settled status, request ID, and credit headers under `meta`.
+Add `--lang <code>` only when a particular output language is requested. Use `--format segments` for segment timestamps or `--format words` only for word timing.
+
+For other operations, use the tested production routes below. Percent-encode query values and replace brace placeholders with IDs.
+
+| Need | Command |
+| --- | --- |
+| Search | `video2ctx api GET '/v1/providers/youtube/search?q=<encoded>' --include-meta` |
+| Browse | `video2ctx api GET '/v1/providers/youtube/browse' --include-meta` |
+| Video details | `video2ctx api GET '/v1/providers/youtube/videos/{id}' --include-meta` |
+| Caption tracks | `video2ctx api GET '/v1/providers/youtube/videos/{id}/tracks' --include-meta` |
+| Transcript | `video2ctx api GET '/v1/providers/youtube/videos/{id}/transcript?format=text' --include-meta` |
+| Comments | `video2ctx api GET '/v1/providers/youtube/videos/{id}/comments' --include-meta` |
+| End screen | `video2ctx api GET '/v1/providers/youtube/videos/{id}/endscreen' --include-meta` |
+| Channel details | `video2ctx api GET '/v1/providers/youtube/channels/{id}' --include-meta` |
+| Channel videos | `video2ctx api GET '/v1/providers/youtube/channels/{id}/videos' --include-meta` |
+| Channel playlists | `video2ctx api GET '/v1/providers/youtube/channels/{id}/playlists' --include-meta` |
+| Playlist | `video2ctx api GET '/v1/providers/youtube/playlists/{id}' --include-meta` |
+| Usage and balance | `video2ctx api GET '/v1/usage' --include-meta` |
+| Account identity | `video2ctx whoami --json` |
 
-Before choosing a route, read `https://docs.video2ctx.dev/api/authentication` and `https://docs.video2ctx.dev/api/conventions`. Read the relevant discovery or entity guide, then resolve every remaining method, path, parameter, and response question against `https://api.video2ctx.dev/openapi.json`.
+The provider for known YouTube resources is `youtube`; do not spend a request discovering it through `/v1/providers`. Provider listing and usage are free. Most provider reads cost 1 credit; a fresh search or comments request costs 2 credits. `--include-meta` exposes settled credit and request metadata.
 
-Stay within this skill's surface:
+## Look up documentation only when needed
 
-- Search and browse provider content.
-- Read video details, tracks, transcripts, comments, and end screens.
-- Read channel details, channel videos, channel playlists, and playlist contents.
-- Read `GET /v1/usage` and account identity.
+The table is sufficient for the common paths. Read `https://docs.video2ctx.dev/api/authentication.md` or `https://docs.video2ctx.dev/api/conventions.md` only when the task raises an authentication, pagination, response, or error question. Read the relevant `.md` guide next, and consult `https://api.video2ctx.dev/openapi.json` only for a route or parameter not covered here or when the server rejects the documented call.
 
-Use the provider ID returned by `GET /v1/providers`; the current production provider is YouTube. Monitoring and notifications belong to `video2ctx-monitoring`. Projects, trends, research, imports, exports, billing, API-key management, connected-account changes, account deletion, and administration are outside this skill. Direct the user to `https://video2ctx.dev` for browser-only account actions.
+Stay within stateless hosted data, account identity, and usage. Monitoring and notifications belong to `video2ctx-monitoring`. Projects, trends, research, imports, exports, billing, API-key management, connected-account changes, account deletion, and administration are outside this skill. Direct the user to `https://video2ctx.dev` for browser-only account actions.
 
 ## Preserve response meaning
 
-- Request only the resource or subresource needed.
-- Return continuations only to the endpoint and encoded query that produced them.
-- Treat `comments?all=true` as bounded and newest-first.
-- Inspect `meta.partial` and `meta.warnings` within API data before presenting a result as complete.
-- Use the CLI's finite request deadline. Retry only idempotent reads after transient `429` or `503` responses, with a bounded attempt count and `Retry-After` when present.
-- Branch separately for `401`, `402`, `403`, `422`, `429`, and `503`. Preserve the API error code, request ID, and retry guidance in the user-facing explanation.
-- Read settled credits from `--include-meta`; use `GET /v1/usage` for the current balance and plan limits.
+- Request only the resource or detail level needed.
+- Return continuations only to the exact endpoint and encoded query that produced them.
+- Inspect `data.meta.partial` and `data.meta.warnings` before presenting a result as complete.
+- The CLI uses a 150-second data deadline by default and permits `--timeout-ms` from 1,000 through 300,000.
+- The CLI retries idempotent GET requests once after `429` or `503`, honoring `Retry-After`; change the bounded attempt count with `--retries 0..3`. It never retries mutations.
+- On failure, parse the single JSON value on stderr. Preserve `error.status`, `error.code`, `error.message`, `error.requestId`, `error.retryable`, and `error.retryAfterSeconds` when present.
 
 ## Done when
 
-The installed CLI reports an authenticated account; every request uses it to target a public production route and remains stateless; no composite or browser-only operation was attempted; partial results and continuations retain their meaning; errors remain classified; and settled credit metadata was observed.
+The CLI identity is confirmed; the minimum stateless production request completed; no unnecessary discovery or documentation request was made; partial results and continuations retain their meaning; and settled credit or classified error metadata was preserved.
diff --git a/.agents/skills/video2ctx-api/agents/openai.yaml b/.agents/skills/video2ctx-api/agents/openai.yaml
@@ -1,4 +1,4 @@
 interface:
   display_name: "video2ctx Hosted API"
-  short_description: "Use managed, authenticated YouTube data"
-  default_prompt: "Use $video2ctx-api to retrieve a YouTube transcript through the hosted video2ctx API."
+  short_description: "Managed YouTube data, account, and usage"
+  default_prompt: "Use $video2ctx-api for this managed hosted API request or direct-route fallback, preserving credit and request metadata."
diff --git a/.agents/skills/video2ctx-monitoring/SKILL.md b/.agents/skills/video2ctx-monitoring/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: video2ctx-monitoring
-description: Stateful video2ctx monitoring for watching YouTube channels, topics, or searches and receiving new-video notifications. Use for recurring checks, schedules, alerts, delivery preferences, monitor notifications, or video2ctx CLI login. Requires the video2ctx CLI; use video2ctx-api for one-time hosted reads and youtube-direct for direct no-account reads.
+description: Stateful video2ctx monitoring for watching YouTube channels, topics, or searches and receiving new-video notifications. Use for recurring checks, schedules, alerts, delivery preferences, or monitor notifications. Requires the video2ctx CLI; use video2ctx-api for account and usage details, managed one-time reads, and fallback after youtube-direct fails.
 license: Apache-2.0
 ---
 
@@ -20,13 +20,11 @@ Confirm `video2ctx --version` succeeds before continuing. Use that installed com
 
 ## Authenticate
 
-1. Run `video2ctx auth status --json`.
-2. When unauthenticated, run `video2ctx auth login`. Relay the displayed URL and code if the user must continue in a browser. Use `--no-browser` only when opening a browser is unavailable.
-3. Confirm access with `video2ctx whoami --json`.
+Run `video2ctx whoami --json`. When it reports `AUTHENTICATION_REQUIRED`, run `video2ctx auth login`. Relay the displayed URL and code if the user must continue in a browser, use `--no-browser` only when opening a browser is unavailable, and then retry `video2ctx whoami --json`. Do not run `auth status` first; both identity commands resolve the same remote account.
 
 The login flow stores a revocable CLI session in the user's local config with private file permissions. Keep the session out of prompts, logs, screenshots, and source control. The CLI also accepts `VIDEO2CTX_API_KEY` as a non-interactive fallback and gives it precedence over the stored session. Have the user create and configure a personal key at `https://video2ctx.dev/dashboard/developer` when they prefer that mode; never ask them to paste it into the conversation.
 
-Read `https://docs.video2ctx.dev/api/authentication`, `https://docs.video2ctx.dev/api/conventions`, and `https://docs.video2ctx.dev/api/monitoring` before operating monitors. Resolve every remaining method, path, parameter, request, and response question against `https://api.video2ctx.dev/openapi.json`.
+The operations below cover the common contract. Read `https://docs.video2ctx.dev/api/authentication.md`, `https://docs.video2ctx.dev/api/conventions.md`, or `https://docs.video2ctx.dev/api/monitoring.md` only when the task raises an unresolved authentication, response, or monitoring question. Use `https://api.video2ctx.dev/openapi.json` for any remaining method, path, parameter, request, or response uncertainty.
 
 Run operations through the CLI:
 
@@ -37,7 +35,7 @@ video2ctx api POST /v1/monitors --data '<json>' --include-meta
 
 ## Define the monitor
 
-1. Confirm the provider with `GET /v1/providers`; the current production provider is YouTube.
+1. Use provider `youtube`; do not spend a request discovering the known provider.
 2. Choose `kind`: `channel` uses a channel ID as `target`; `topic` and `search` use search text.
 3. Put human-readable notification context in `query.label` while keeping `target` functional.
 4. Choose `intervalMinutes`: `60`, `360`, `720`, `1440`, `4320`, or `10080`. Use `1440` when the user gives no cadence.

diff --git a/.agents/skills/youtube-direct/SKILL.md b/.agents/skills/youtube-direct/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: youtube-direct
-description: Direct, no-account YouTube search and extraction from the user's machine. Use for stateless search, transcripts, caption tracks, comments, video details, end screens, channels, and playlists without a video2ctx account, API key, hosted service, or npm installation. Calls YouTube's internal HTTP endpoints directly; use video2ctx-api instead for managed authenticated access, caching, usage, or account identity.
+description: Direct, no-account YouTube search and extraction from the user's machine. This is the first route for one-off public YouTube requests, especially fetching or summarizing a transcript, plus caption tracks, comments, video details, end screens, channels, and playlists. Requires no video2ctx account, API key, hosted service, or npm installation. If a direct operation fails, continue with video2ctx-api; use the hosted skill directly for account or usage details and managed hosted workflows.
 ---
 
 # YouTube Direct
@@ -29,16 +29,18 @@ Extract a transcript from a known video:
 ```bash
 node <skill-directory>/scripts/youtube.mjs transcript \
   --video-id dQw4w9WgXcQ \
-  --granularity segment
+  --format text
 ```
 
+Use `--format text` when the task needs transcript content or a summary rather than timestamps. Use `--format segments` for segment timing and `--format words` only for word-level timing. The legacy `--granularity segment|word` flag remains supported, but do not combine it with `--format`.
+
 The executable writes one JSON value to stdout. Parse that value and use it to answer the request. Treat stderr as a JSON error payload and branch on `error.code` and `error.retryable`; preserve the classified failure instead of converting it to an empty result.
 
 ## Choose the operation
 
 - `search` — videos, channels, or playlists matching a query
 - `tracks` — source caption tracks and translation targets
-- `transcript` — timed transcript segments or words
+- `transcript` — compact text, timed segments, or timed words
 - `comments` — one page, or a bounded multi-page collection with `--all --max-pages <n>`
 - `details` — video metadata and availability
 - `endscreen` — interactive end-screen elements
@@ -59,7 +61,7 @@ Use `--help` as the source of truth for flags and accepted values.
 
 ## Keep integration boundaries clear
 
-Use this skill for direct, no-account stateless operations from the user's machine. Use `video2ctx-api` when the user wants the managed hosted API, account or usage operations, caching, or authenticated access. Use `video2ctx-monitoring` for the stateful monitoring exception.
+Start ordinary stateless public YouTube operations from the user's machine with this skill. If a direct operation fails, continue with `video2ctx-api` without asking the user to choose a fallback. Use `video2ctx-api` directly for account or usage operations and managed hosted workflows. Use `video2ctx-monitoring` for the stateful monitoring exception.
 
 ## Done when
 

diff --git a/.agents/skills/youtube-direct/agents/openai.yaml b/.agents/skills/youtube-direct/agents/openai.yaml
@@ -1,4 +1,4 @@
 interface:
   display_name: "YouTube Direct — No Account"
   short_description: "Search and extract directly from YouTube"
-  default_prompt: "Use $youtube-direct to search YouTube directly and extract the selected video's transcript and channel data."
+  default_prompt: "Use $youtube-direct to fetch and summarize a public YouTube video directly from this machine without an account or hosted API."