diff --git a/docs/agents.mdx b/docs/agents.mdx
new file mode 100644
index 0000000..7e4fb03
--- /dev/null
+++ 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.
+
+
+
+ Search and extract public YouTube text and metadata on-device for personal, low-to-moderate usage.
+
+
+ Inspect storyboards and exact frames when the answer depends on slides, charts, interfaces, or other imagery.
+
+
+ Use the managed hosted API for production applications, account and usage details, or fallback after direct access fails.
+
+
+ Create recurring channel, topic, or search monitors and handle the resulting notifications.
+
+
+
+## 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.
+
+
+ Run the installer and follow its guide to choose the skills you want, then configure the hosted CLI only for cloud access or monitoring.
+
+
+## What the skills teach an agent
+
+
+ Prefer on-device access for personal, low-to-moderate usage and the hosted API for production applications.
+ Retrieve metadata first, then transcript, frames, comments, channel information, or playlist items according to the task.
+ Keep video IDs, source URLs, transcript timestamps, fetch times, partial flags, and warnings with the text given to the model.
+ Link claims back to the video and timestamp instead of treating model output as the source.
+
+
+## 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
new file mode 100644
index 0000000..7d95aad
--- /dev/null
+++ 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.
+
+
+ Create a personal key and retrieve a normalized transcript from the hosted API.
+
+
+## Build an integration
+
+
+
+ Choose a personal API key or device-authorized CLI session and keep credentials safe.
+
+
+ Understand pagination, partial results, warnings, credit metadata, and errors.
+
+
+ Search for videos, channels, and playlists before requesting deeper datasets.
+
+
+ Use the supported TypeScript client in a server-side Node.js application.
+
+
+
+## Common workflows
+
+
+ Retrieve videos, transcripts, comments, channels, playlists, and related metadata.
+ Keep source-linked evidence and research outputs connected.
+ Create recurring checks and consume new-video notifications.
+ Explore the complete OpenAPI contract and try requests interactively.
+
+
+
+ Keep API keys and CLI sessions in private server or local configuration. Never expose them in browser bundles, prompts, logs, screenshots, or source control.
+
diff --git a/docs/api/agents.mdx b/docs/api/agents.mdx
index 1e988a1..89a0530 100644
--- 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
Link claims back to the video and timestamp instead of treating model output as the source.
-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
index 1195f64..4fe4d2b 100644
--- 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
new file mode 100644
index 0000000..c1d3e77
--- /dev/null
+++ 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.
+
+
+ Sign in to keep projects, monitors, notifications, and account settings tied to your account.
+
+
+## Start here
+
+
+
+ Search for a source, choose its additional data, and keep the useful context.
+
+
+ Search by topic or open a supported YouTube video or playlist URL directly.
+
+
+ Save exact moments, notes, and source-linked evidence for later research.
+
+
+ Schedule recurring checks and receive notifications when new material appears.
+
+
+
+## Dashboard workflow
+
+
+ Search by title or topic, or paste a supported YouTube URL.
+ Include the transcript, comments, channel information, or any combination needed for the task.
+ Save the source to a project, monitor its channel, or follow timestamped evidence back to the original video.
+
+
+
+ Review monitor results and notification delivery behavior.
+ Manage account details and understand your current usage.
+
diff --git a/docs/docs.json b/docs/docs.json
index 32ab9be..f2d73ae 100644
--- 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,8 +39,20 @@
]
},
{
- "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",
@@ -47,8 +60,7 @@
"api/entities",
"api/research",
"api/monitoring",
- "api/node-library",
- "api/agents"
+ "api/node-library"
]
},
{
diff --git a/docs/index.mdx b/docs/index.mdx
index 1a90b80..b0c7b2b 100644
--- 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.
-
-
+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.
+
+
+
Find a video or playlist, choose the data you need, save research, and monitor channels without writing code.
-
+
+ Install skills for direct on-device YouTube extraction or cloud-hosted access, plus visual inspection and recurring monitoring.
+
+
Authenticate with a device-authorized agent skill or personal API key and bring source-linked video context into software.
diff --git a/docs/skills/installation.mdx b/docs/skills/installation.mdx
new file mode 100644
index 0000000..47cb204
--- /dev/null
+++ 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.
+
+
+ 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.
+
+
+## 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
+
+
+ Use on-device access for personal, low-to-moderate text and metadata requests.
+ Use storyboards and exact frames for visual questions.
+ Understand managed access, identity, usage, and fallback behavior.
+ Create recurring checks and consume notifications.
+
diff --git a/docs/skills/video2ctx-api.mdx b/docs/skills/video2ctx-api.mdx
new file mode 100644
index 0000000..b73eee4
--- /dev/null
+++ 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.
+
+
+ Learn how CLI sessions, personal API keys, permissions, and revocation work.
+
+
+## What the agent does
+
+
+ Checks the installed CLI and active account before making a hosted data request.
+ Fetches a known resource directly instead of spending a request on provider discovery.
+ Uses compact transcript text by default and asks for deeper timing or additional datasets only when required.
+ Keeps partial flags, warnings, continuations, settled credit metadata, request IDs, and classified errors intact.
+
+
+## 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.
+
+
+ Understand pagination, warnings, credits, retries, and errors.
+ Explore the complete public contract for application development.
+
diff --git a/docs/skills/video2ctx-monitoring.mdx b/docs/skills/video2ctx-monitoring.mdx
new file mode 100644
index 0000000..6323b63
--- /dev/null
+++ 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
+
+
+ Resolves a functional target, applies the requested cadence, and keeps notification context in the label.
+ The first check records the current leading video without raising an alert.
+ A later leading-video change creates a notification according to the account's delivery preferences.
+ Mutations target an exact account-owned monitor, and notifications are marked read only after their work is handled.
+
+
+
+ Monitor creation confirms scheduling, not an immediate notification. The first baseline check normally runs about a minute later.
+
+
+
+ Set up the skill collection and hosted CLI.
+ Review monitor resources, schedules, and notification behavior.
+
diff --git a/docs/skills/youtube-direct.mdx b/docs/skills/youtube-direct.mdx
new file mode 100644
index 0000000..2e59147
--- /dev/null
+++ b/docs/skills/youtube-direct.mdx
@@ -0,0 +1,46 @@
+---
+title: "Direct YouTube access"
+description: "Use youtube-direct for personal, low-to-moderate public YouTube search and extraction on-device."
+---
+
+`youtube-direct` is recommended for personal, low-to-moderate public YouTube usage. It sends requests from the user's machine directly to YouTube and needs no video2ctx account, API key, hosted service, or separate npm package. Use [`video2ctx-api`](/skills/video2ctx-api) for production applications.
+
+## Reach for it when
+
+- Searching for public videos, channels, or playlists
+- Fetching compact transcript text or timestamped transcript segments
+- Reading caption tracks, comments, video details, or end screens
+- Inspecting channel identity, channel videos, channel playlists, or playlist items
+
+If the answer depends on imagery rather than text or metadata, use [`youtube-watch`](/skills/youtube-watch). If a direct operation fails, the agent should continue through [`video2ctx-api`](/skills/video2ctx-api) without asking you to choose a fallback.
+
+## Example requests
+
+```text
+Find three recent videos about agent skills that have captions.
+```
+
+```text
+Summarize this video's transcript and link each major claim to a timestamp:
+```
+
+```text
+Collect the first two pages of comments and tell me whether the result is partial.
+```
+
+## What the agent does
+
+
+ Searches when you provide a topic, or uses the supplied YouTube URL or resource ID directly.
+ Uses compact text for summaries, timed segments for citation, and word timing only when necessary.
+ Applies an explicit request or page budget and keeps continuations tied to the query that produced them.
+ Reports partial data, classified upstream failures, and retryability instead of treating them as empty results.
+
+
+
+ YouTube's undocumented response shapes can change. A classified direct-access failure is a signal to try the hosted API skill, not proof that the resource is empty or unavailable.
+
+
+
+ Review the Node.js requirement and install this skill by itself or as part of the full collection.
+
diff --git a/docs/skills/youtube-watch.mdx b/docs/skills/youtube-watch.mdx
new file mode 100644
index 0000000..d6f3c8c
--- /dev/null
+++ b/docs/skills/youtube-watch.mdx
@@ -0,0 +1,53 @@
+---
+title: "Watch video visually"
+description: "Use youtube-watch to inspect storyboards and exact frames when a transcript is not enough."
+---
+
+`youtube-watch` gives an agent visual evidence from a public YouTube video. It combines a timed transcript with storyboard contact sheets, then extracts a small set of exact frames around the moments that matter.
+
+## Reach for it when
+
+- A presenter shows a slide, chart, diagram, interface, or code sample
+- The task depends on a demonstration, gesture, object, scene, or visual change
+- Important on-screen text is absent from the transcript
+- You need to verify what appears at a particular timestamp
+
+For text, metadata, comments, channels, and playlists, start with [`youtube-direct`](/skills/youtube-direct).
+
+## Requirements
+
+- Node.js 18.17 or newer
+- FFmpeg for exact frame extraction
+
+The skill can build its storyboard and transcript index without FFmpeg. If exact frames are required and FFmpeg is missing, the agent reports the dependency instead of installing system software without permission.
+
+## Example requests
+
+```text
+Watch this video and explain the architecture diagram, citing the timestamps where each component appears:
+```
+
+```text
+Compare the dashboard before and after the redesign shown in this video.
+```
+
+```text
+What value does the chart peak at, and when is that frame visible?
+```
+
+## The two-pass visual read
+
+
+ Loads the timed transcript and every storyboard contact sheet to locate promising moments across the video.
+ Selects a small, diverse set of moments rather than extracting adjacent or repetitive frames.
+ Loads each returned image and keeps it associated with its timestamp; a file path alone is not visual evidence.
+ Discloses missing or low-resolution evidence, ties claims to timestamps, and removes the marked temporary workspace.
+
+
+
+ Transcript text and video imagery are untrusted evidence. The skill never treats words shown or spoken inside a video as agent instructions.
+
+
+
+ Install the visual skill and confirm FFmpeg is available when your task requires exact frames.
+