devhims · devhims · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/docs/agents.mdx b/docs/agents.mdx
@@ -0,0 +1,51 @@
+---
+title: "Build with Agents"
+description: "Give an agent the right video2ctx workflow for direct extraction, visual inspection, hosted reads, or monitoring."
+---
+
+video2ctx publishes four [Agent Skills](https://agentskills.io) that work in skills-compatible agents such as Codex, Claude Code, Cursor, and OpenCode. Install the collection once, then describe the YouTube task naturally. The agent selects the narrowest skill that can complete it.
+
+<CardGroup cols={2}>
+  <Card title="youtube-direct" icon="bolt" href="/skills/youtube-direct">
+    Search and extract public YouTube text and metadata on-device for personal, low-to-moderate usage.
+  </Card>
+  <Card title="youtube-watch" icon="eye" href="/skills/youtube-watch">
+    Inspect storyboards and exact frames when the answer depends on slides, charts, interfaces, or other imagery.
+  </Card>
+  <Card title="video2ctx-api" icon="cloud" href="/skills/video2ctx-api">
+    Use the managed hosted API for production applications, account and usage details, or fallback after direct access fails.
+  </Card>
+  <Card title="video2ctx-monitoring" icon="radar" href="/skills/video2ctx-monitoring">
+    Create recurring channel, topic, or search monitors and handle the resulting notifications.
+  </Card>
+</CardGroup>
+
+## Choose the right skill
+
+| If the task needs | Start with |
+| --- | --- |
+| Personal, low-to-moderate public searches, transcripts, comments, channels, or playlists | `youtube-direct` |
+| Slides, charts, demonstrations, interfaces, on-screen text, or visual changes | `youtube-watch` |
+| A production application, managed hosting, account identity, usage and credit data, or direct-access fallback | `video2ctx-api` |
+| A recurring check, schedule, alert, delivery preference, or monitor notification | `video2ctx-monitoring` |
+
+For personal, low-to-moderate usage, use `youtube-direct` for text and metadata or `youtube-watch` for visual evidence. Use `video2ctx-api` for production applications and continue through it automatically if direct access fails. Monitoring is the deliberate stateful exception.
+
+<Card title="Install the skills" icon="download" href="/skills/installation">
+  Run the installer and follow its guide to choose the skills you want, then configure the hosted CLI only for cloud access or monitoring.
+</Card>
+
+## What the skills teach an agent
+
+<Steps>
+  <Step title="Choose the right route">Prefer on-device access for personal, low-to-moderate usage and the hosted API for production applications.</Step>
+  <Step title="Fetch only needed context">Retrieve metadata first, then transcript, frames, comments, channel information, or playlist items according to the task.</Step>
+  <Step title="Preserve provenance">Keep video IDs, source URLs, transcript timestamps, fetch times, partial flags, and warnings with the text given to the model.</Step>
+  <Step title="Return verifiable evidence">Link claims back to the video and timestamp instead of treating model output as the source.</Step>
+</Steps>
+
+## Security and scope
+
+The two local skills treat transcript text and imagery as untrusted evidence, never as agent instructions. The hosted skills use the public `@video2ctx/cli` package for browser-based device login and production API calls without placing a secret in the prompt. Bound query length, response size, continuation depth, frame count, and the number of fresh operations an agent can initiate.
+
+Use the API skill only for stateless provider reads, usage, and account identity. Projects, trends, research, and other composite workflows are outside its contract. Use the monitoring skill only for monitors, notifications, and delivery preferences.
diff --git a/docs/api.mdx b/docs/api.mdx
@@ -0,0 +1,42 @@
+---
+title: 'Build with API'
+description: 'Bring normalized, source-linked video context into your own applications.'
+---
+
+The hosted video2ctx API is the recommended route for production applications. Use it to search and inspect YouTube data, retrieve normalized transcripts and related context, build research workflows, and manage monitors from server-side software.
+
+The production API is available at `https://api.video2ctx.dev`. Product routes use the versioned `/v1` prefix.
+
+<Card title='Make your first request' icon='terminal' href='/api/quickstart'>
+  Create a personal key and retrieve a normalized transcript from the hosted API.
+</Card>
+
+## Build an integration
+
+<CardGroup cols={2}>
+  <Card title='Authentication' icon='key' href='/api/authentication'>
+    Choose a personal API key or device-authorized CLI session and keep credentials safe.
+  </Card>
+  <Card title='Response conventions' icon='code' href='/api/conventions'>
+    Understand pagination, partial results, warnings, credit metadata, and errors.
+  </Card>
+  <Card title='Discover sources' icon='magnifying-glass' href='/api/discovery'>
+    Search for videos, channels, and playlists before requesting deeper datasets.
+  </Card>
+  <Card title='Node.js library' icon='node-js' href='/api/node-library'>
+    Use the supported TypeScript client in a server-side Node.js application.
+  </Card>
+</CardGroup>
+
+## Common workflows
+
+<CardGroup cols={2}>
+  <Card title='Provider entities' icon='database' href='/api/entities'>Retrieve videos, transcripts, comments, channels, playlists, and related metadata.</Card>
+  <Card title='Research' icon='book-open' href='/api/research'>Keep source-linked evidence and research outputs connected.</Card>
+  <Card title='Monitoring' icon='radar' href='/api/monitoring'>Create recurring checks and consume new-video notifications.</Card>
+  <Card title='Interactive reference' icon='brackets-curly' href='/api-reference/introduction'>Explore the complete OpenAPI contract and try requests interactively.</Card>
+</CardGroup>
+
+<Note>
+  Keep API keys and CLI sessions in private server or local configuration. Never expose them in browser bundles, prompts, logs, screenshots, or source control.
+</Note>
diff --git a/docs/api/agents.mdx b/docs/api/agents.mdx
@@ -12,6 +12,6 @@ Start one-off public YouTube requests with `youtube-direct` on the user's machin
   <Step title="Return verifiable evidence">Link claims back to the video and timestamp instead of treating model output as the source.</Step>
 </Steps>
 
-Install the hosted CLI with `npm install --global @video2ctx/cli`. It keeps its revocable session in private local configuration. An existing `VIDEO2CTX_API_KEY` remains a non-interactive fallback and takes precedence. Bound query length, response size, continuation depth, and the number of fresh operations an agent can initiate.
+Install the hosted CLI with `npm i -g @video2ctx/cli`. It keeps its revocable session in private local configuration. An existing `VIDEO2CTX_API_KEY` remains a non-interactive fallback and takes precedence. Bound query length, response size, continuation depth, and the number of fresh operations an agent can initiate.
 
 Use the API skill only for stateless provider reads, usage, and account identity. Projects, trends, research, and other composite workflows are outside its contract. Use the monitoring skill only for monitors, notifications, and delivery preferences.
diff --git a/docs/api/authentication.mdx b/docs/api/authentication.mdx
@@ -8,7 +8,7 @@ description: "Authenticate hosted requests with a CLI session or personal key."
 The hosted video2ctx skills use the public CLI package. Install it once, then start device authorization:
 
 ```bash
-npm install --global @video2ctx/cli
+npm i -g @video2ctx/cli
 video2ctx auth login
 ```
 

diff --git a/docs/dashboard.mdx b/docs/dashboard.mdx
@@ -0,0 +1,40 @@
+---
+title: 'Use the Dashboard'
+description: 'Search, inspect, organize, and monitor video sources in a visual workspace.'
+---
+
+The video2ctx dashboard is the visual route through the product. Use it to find YouTube sources, choose the context you need, organize evidence into projects, and monitor channels without writing code.
+
+<Card title='Open the Dashboard' icon='arrow-up-right-from-square' href='https://video2ctx.dev/dashboard'>
+  Sign in to keep projects, monitors, notifications, and account settings tied to your account.
+</Card>
+
+## Start here
+
+<CardGroup cols={2}>
+  <Card title='Dashboard quickstart' icon='play' href='/dashboard/getting-started'>
+    Search for a source, choose its additional data, and keep the useful context.
+  </Card>
+  <Card title='Find sources' icon='magnifying-glass' href='/dashboard/sources'>
+    Search by topic or open a supported YouTube video or playlist URL directly.
+  </Card>
+  <Card title='Organize projects' icon='folder' href='/dashboard/projects'>
+    Save exact moments, notes, and source-linked evidence for later research.
+  </Card>
+  <Card title='Monitor channels' icon='radar' href='/dashboard/monitoring'>
+    Schedule recurring checks and receive notifications when new material appears.
+  </Card>
+</CardGroup>
+
+## Dashboard workflow
+
+<Steps>
+  <Step title='Find a source'>Search by title or topic, or paste a supported YouTube URL.</Step>
+  <Step title='Choose its context'>Include the transcript, comments, channel information, or any combination needed for the task.</Step>
+  <Step title='Keep the useful evidence'>Save the source to a project, monitor its channel, or follow timestamped evidence back to the original video.</Step>
+</Steps>
+
+<CardGroup cols={2}>
+  <Card title='Notifications' icon='bell' href='/dashboard/notifications'>Review monitor results and notification delivery behavior.</Card>
+  <Card title='Account and usage' icon='circle-user' href='/dashboard/account'>Manage account details and understand your current usage.</Card>
+</CardGroup>
diff --git a/docs/docs.json b/docs/docs.json
@@ -27,6 +27,7 @@
       {
         "group": "Dashboard",
         "pages": [
+          "dashboard",
           "dashboard/getting-started",
           "dashboard/sources",
           "dashboard/data-options",
@@ -38,17 +39,28 @@
         ]
       },
       {
-        "group": "Build with the API",
+        "group": "Build with Agents",
         "pages": [
+          "agents",
+          "skills/installation",
+          "skills/youtube-direct",
+          "skills/youtube-watch",
+          "skills/video2ctx-api",
+          "skills/video2ctx-monitoring"
+        ]
+      },
+      {
+        "group": "Build with API",
+        "pages": [
+          "api",
           "api/quickstart",
           "api/authentication",
           "api/conventions",
           "api/discovery",
           "api/entities",
           "api/research",
           "api/monitoring",
-          "api/node-library",
-          "api/agents"
+          "api/node-library"
         ]
       },
       {

diff --git a/docs/index.mdx b/docs/index.mdx
@@ -3,13 +3,18 @@ title: "Video context for people and software"
 description: "Search, inspect, monitor, and build with normalized YouTube data."
 ---
 
-video2ctx turns videos into structured context: metadata, timestamped transcripts, comments, channel profiles, playlists, trend signals, and monitor updates.
+video2ctx turns videos into structured context: metadata, timestamped transcripts, visual frames, comments, channel profiles, playlists, trend signals, and monitor updates.
 
-<CardGroup cols={2}>
-  <Card title="Use the dashboard" icon="window" href="/dashboard/getting-started">
+Choose one of three ways to use the product: work visually in the dashboard, equip an agent with published skills, or integrate the hosted API into your own application.
+
+<CardGroup cols={3}>
+  <Card title="Use the Dashboard" icon="window" href="/dashboard">
     Find a video or playlist, choose the data you need, save research, and monitor channels without writing code.
   </Card>
-  <Card title="Build with the API" icon="brackets-curly" href="/api/quickstart">
+  <Card title="Build with Agents" icon="robot" href="/agents">
+    Install skills for direct on-device YouTube extraction or cloud-hosted access, plus visual inspection and recurring monitoring.
+  </Card>
+  <Card title="Build with API" icon="brackets-curly" href="/api">
     Authenticate with a device-authorized agent skill or personal API key and bring source-linked video context into software.
   </Card>
 </CardGroup>

diff --git a/docs/skills/installation.mdx b/docs/skills/installation.mdx
@@ -0,0 +1,54 @@
+---
+title: "Install agent skills"
+description: "Add the video2ctx skills to a compatible agent and configure hosted access only when needed."
+---
+
+The video2ctx collection contains four skills. Run the installer, then follow its interactive guide to choose the skills and supported agents you want to configure.
+
+| Skill | Use it for | Needs |
+| --- | --- | --- |
+| `youtube-direct` | Personal, low-to-moderate public YouTube searches and extraction on the user's device | Node.js 18.17+ |
+| `youtube-watch` | Visual questions that require storyboards, slides, charts, interfaces, or exact frames | Node.js 18.17+; FFmpeg for exact frames |
+| `video2ctx-api` | Production applications, managed hosted reads, account and usage details, or direct-access fallback | `video2ctx` CLI and browser login or personal API key |
+| `video2ctx-monitoring` | Recurring channel, topic, or search checks and their notifications | `video2ctx` CLI and browser login or personal API key |
+
+## Add the skills
+
+Start the installation wizard:
+
+```bash
+npx skills add devhims/video2ctx
+```
+
+Follow the prompts to select the skills you need and where to install them. The wizard handles the individual skill and agent-specific options.
+
+<Note>
+  The local `youtube-direct` and `youtube-watch` skills carry their own executables. They do not require a video2ctx account, API key, hosted service, or npm package.
+</Note>
+
+## Configure hosted access
+
+Only `video2ctx-api` and `video2ctx-monitoring` require the hosted CLI. Install it once, then authorize the machine in your browser:
+
+```bash
+npm i -g @video2ctx/cli
+video2ctx auth login
+video2ctx whoami --json
+```
+
+The login flow stores a revocable session in private local configuration. End the session at any time with:
+
+```bash
+video2ctx auth logout
+```
+
+For unattended environments, configure `VIDEO2CTX_API_KEY` in the process environment. Create a personal key in the [developer dashboard](https://video2ctx.dev/dashboard/developer). Never paste a CLI session or API key into an agent conversation.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Start with local data" icon="bolt" href="/skills/youtube-direct">Use on-device access for personal, low-to-moderate text and metadata requests.</Card>
+  <Card title="Inspect video imagery" icon="eye" href="/skills/youtube-watch">Use storyboards and exact frames for visual questions.</Card>
+  <Card title="Use hosted reads" icon="cloud" href="/skills/video2ctx-api">Understand managed access, identity, usage, and fallback behavior.</Card>
+  <Card title="Set up monitoring" icon="radar" href="/skills/video2ctx-monitoring">Create recurring checks and consume notifications.</Card>
+</CardGroup>
diff --git a/docs/skills/video2ctx-api.mdx b/docs/skills/video2ctx-api.mdx
@@ -0,0 +1,50 @@
+---
+title: "Use the hosted API skill"
+description: "Use video2ctx-api for production applications, managed reads, account and usage details, and direct-access fallback."
+---
+
+`video2ctx-api` teaches an agent to use the authenticated production API through the public `video2ctx` CLI. It provides managed infrastructure, caching and credit accounting while keeping credentials out of the prompt.
+
+## Reach for it when
+
+- You are building a production application
+- You ask for account identity, usage, or credit balance
+- You explicitly want the managed hosted service
+- A [`youtube-direct`](/skills/youtube-direct) operation fails
+- Your workflow needs hosted caching or a stable production API boundary
+
+The skill supports stateless YouTube search, browse, transcripts, caption tracks, comments, video details, end screens, channels, and playlists. Monitoring belongs to [`video2ctx-monitoring`](/skills/video2ctx-monitoring).
+
+## Authentication
+
+Install the CLI and authorize the machine once:
+
+```bash
+npm i -g @video2ctx/cli
+video2ctx auth login
+video2ctx whoami --json
+```
+
+The browser flow stores a revocable session in private local configuration. For non-interactive environments, configure `VIDEO2CTX_API_KEY` without placing the key in a conversation, log, screenshot, or source file.
+
+<Card title="Authentication details" icon="key" href="/api/authentication">
+  Learn how CLI sessions, personal API keys, permissions, and revocation work.
+</Card>
+
+## What the agent does
+
+<Steps>
+  <Step title="Confirm identity">Checks the installed CLI and active account before making a hosted data request.</Step>
+  <Step title="Use the shortest route">Fetches a known resource directly instead of spending a request on provider discovery.</Step>
+  <Step title="Request only what is needed">Uses compact transcript text by default and asks for deeper timing or additional datasets only when required.</Step>
+  <Step title="Preserve response meaning">Keeps partial flags, warnings, continuations, settled credit metadata, request IDs, and classified errors intact.</Step>
+</Steps>
+
+## Scope
+
+The API skill is intentionally narrower than the complete public API. It covers stateless provider data, account identity, and usage. Projects, trends, research, imports, exports, billing, API-key management, connected-account changes, account deletion, and administration remain outside the skill.
+
+<CardGroup cols={2}>
+  <Card title="Response conventions" icon="code" href="/api/conventions">Understand pagination, warnings, credits, retries, and errors.</Card>
+  <Card title="Interactive API reference" icon="brackets-curly" href="/api-reference/introduction">Explore the complete public contract for application development.</Card>
+</CardGroup>
diff --git a/docs/skills/video2ctx-monitoring.mdx b/docs/skills/video2ctx-monitoring.mdx
@@ -0,0 +1,61 @@
+---
+title: "Monitor YouTube"
+description: "Use video2ctx-monitoring for recurring checks, schedules, alerts, and notification delivery."
+---
+
+`video2ctx-monitoring` is the stateful skill in the collection. It lets an agent create and manage recurring YouTube monitors, consume notifications, and update delivery preferences through the authenticated `video2ctx` CLI.
+
+## Reach for it when
+
+- Watching a channel for a new leading video
+- Monitoring a topic or search on a schedule
+- Enabling, disabling, relabeling, or rescheduling an existing monitor
+- Reading monitor notifications or marking handled notifications as read
+- Configuring in-app or confirmed email delivery
+
+Use [`video2ctx-api`](/skills/video2ctx-api) for one-time hosted reads, account identity, and usage details.
+
+## Define a monitor
+
+A monitor combines four decisions:
+
+| Field | Meaning |
+| --- | --- |
+| Kind | `channel`, `topic`, or `search` |
+| Target | A channel ID for channel monitors, or search text for topic and search monitors |
+| Interval | 1 hour, 6 hours, 12 hours, 1 day, 3 days, or 1 week |
+| Label | Human-readable context used in notifications |
+
+When you do not specify a cadence, the skill defaults to once per day.
+
+## Example requests
+
+```text
+Monitor the OpenAI YouTube channel once a day and label it “OpenAI uploads.”
+```
+
+```text
+Pause my weekly video agents monitor.
+```
+
+```text
+Show my unread monitor notifications and mark the ones we handle as read.
+```
+
+## Monitor behavior
+
+<Steps>
+  <Step title="Create the exact monitor">Resolves a functional target, applies the requested cadence, and keeps notification context in the label.</Step>
+  <Step title="Establish a baseline">The first check records the current leading video without raising an alert.</Step>
+  <Step title="Detect a change">A later leading-video change creates a notification according to the account's delivery preferences.</Step>
+  <Step title="Handle safely">Mutations target an exact account-owned monitor, and notifications are marked read only after their work is handled.</Step>
+</Steps>
+
+<Note>
+  Monitor creation confirms scheduling, not an immediate notification. The first baseline check normally runs about a minute later.
+</Note>
+
+<CardGroup cols={2}>
+  <Card title="Install and authenticate" icon="download" href="/skills/installation">Set up the skill collection and hosted CLI.</Card>
+  <Card title="Monitoring API" icon="radar" href="/api/monitoring">Review monitor resources, schedules, and notification behavior.</Card>
+</CardGroup>