videodraft 0.2.0 → 0.2.1

package/README.md

@@ -30,18 +30,9 @@ export VIDEODRAFT_API_KEY=vd_mcp_…  # headless / CI — no login command neede
 
 Credentials are stored in `~/.config/videodraft/config.json` (0600). `videodraft logout` revokes and clears them.
 
-## The pipeline
+## Asset generation first
 
-```bash
-videodraft credits                              # know your budget
-videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
-videodraft shots <project> --grid --estimate    # preview the cost…
-videodraft shots <project> --grid               # …then batch-generate every shot image
-videodraft produce <project>                    # voiceovers + captions + production timeline
-videodraft export <project> --download final.mp4
-```
-
-Single assets don't need a project:
+Standalone images, clips and audio are complete deliverables. They do not need a VideoDraft project unless you want to attach them to an existing project or turn them into a multi-scene production.
 
 ```bash
 videodraft generate image "isometric workspace, warm light" --num 4 --download "./out/{job_id}_{index}.{ext}"
@@ -56,6 +47,32 @@ videodraft upscale image ./photo.png --scale 4x --download ./photo-4x.png
 videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our launch' --json | jq -r .script)"
 ```
 
+Discover the full asset lane:
+
+```bash
+videodraft tools list
+videodraft tools list --lane assets
+videodraft tools list --lane asset_io
+videodraft models image
+videodraft models video
+videodraft models audio
+```
+
+Asset I/O is part of the asset workflow: `videodraft upload`, `videodraft download`, generation `--download`, and local refs like `--ref ./image.png` make files usable by agents and visible in local workspaces.
+
+## The project pipeline
+
+Use projects when the user asks for a story, storyboard, editable web project, timeline, production flow, or exported MP4.
+
+```bash
+videodraft credits                              # know your budget
+videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
+videodraft shots <project> --grid --estimate    # preview the cost…
+videodraft shots <project> --grid               # …then batch-generate every shot image
+videodraft produce <project>                    # voiceovers + captions + production timeline
+videodraft export <project> --download final.mp4
+```
+
 ## Commands
 
 | Group | Commands |
@@ -67,7 +84,7 @@ videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our
 | Generate | `generate image/video/voiceover/music/sound-effect/dialogue/voice-changer/dub` `upscale image/video` `avatar script/create/render/get/list` |
 | Jobs | `status <job>` `wait <job>` `generations` |
 | Media | `upload <file>` `media list` `describe <url\|file>` `download <url>` |
-| Everything else | `tools list` `tools schema <name>` `call <tool> --args '<json>'` |
+| Everything else | `tools list [--lane assets\|asset_io\|project_data\|production]` `tools schema <name>` `call <tool> --args '<json>'` |
 | Agents | `skills install [--agent claude\|codex\|cursor]` `skills path` |
 | Utility | `config get/set/path` `completion bash\|zsh` `docs` `--version` |
 

package/dist/index.js

@@ -24,8 +24,8 @@ function readVersionFromDisk() {
   }
 }
 function resolveVersion() {
-  if ("0.2.0") {
-    return "0.2.0";
+  if ("0.2.1") {
+    return "0.2.1";
   }
   return readVersionFromDisk();
 }
@@ -2576,19 +2576,97 @@ function parseKeyValueArgs(pairs) {
   }
   return args;
 }
+var CATEGORY_ORDER = [
+  "asset_generation",
+  "asset_io",
+  "asset_library",
+  "project_creation",
+  "project_data",
+  "production",
+  "account_models_costs",
+  "jobs",
+  "danger_zone",
+  "raw"
+];
+var LANE_ORDER = [
+  "assets",
+  "asset_io",
+  "projects",
+  "project_data",
+  "production",
+  "library",
+  "account",
+  "danger",
+  "raw"
+];
+function firstSentence(description) {
+  return description.split(/[.!]\s/)[0].slice(0, 90);
+}
 function registerToolCommands(program) {
   const tools = program.command("tools").description("Inspect the full MCP tool catalog");
-  tools.command("list", { isDefault: true }).description("List every available tool").action(async function() {
+  tools.command("list", { isDefault: true }).description("List the grouped VideoDraft tool catalog").option(
+    "--lane <lane>",
+    "filter by lane: assets | asset_io | projects | project_data | production | library | account | danger | raw"
+  ).option(
+    "--category <category>",
+    "filter by category, e.g. asset_generation, asset_io, project_data, or production"
+  ).action(async function() {
     const ctx = buildContext(this);
-    const list = await ctx.client.listTools();
-    emit(ctx.out, list.map((t) => ({ name: t.name, description: t.description })), (o) => {
-      table(
+    const opts = this.opts();
+    if (opts.lane && !LANE_ORDER.includes(opts.lane)) {
+      throw new CliError(
+        `Unknown lane "${opts.lane}". Expected one of: ${LANE_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    if (opts.category && !CATEGORY_ORDER.includes(opts.category)) {
+      throw new CliError(
+        `Unknown category "${opts.category}". Expected one of: ${CATEGORY_ORDER.join(", ")}`,
+        EXIT.USAGE
+      );
+    }
+    let summary;
+    const catalog = await ctx.client.callTool(
+      "get_tool_catalog",
+      compact({ lane: opts.lane, category: opts.category })
+    );
+    summary = catalog?.tools ?? [];
+    emit(ctx.out, summary, (o) => {
+      const categories = Array.from(
+        new Set(summary.map((tool) => tool.category))
+      ).sort((a, b) => {
+        const ai = CATEGORY_ORDER.indexOf(a);
+        const bi = CATEGORY_ORDER.indexOf(b);
+        return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi) || a.localeCompare(b);
+      });
+      if (categories.length === 0) {
+        table(o, ["name", "type", "risk", "description"], []);
+      }
+      for (const category of categories) {
+        const rows = summary.filter((tool) => tool.category === category);
+        process.stdout.write(`
+${fmt.bold(o, category)}
+`);
+        table(
+          o,
+          ["name", "type", "risk", "description"],
+          rows.map((tool) => [
+            tool.name,
+            tool.subcategory ?? "",
+            tool.risks.join(","),
+            firstSentence(tool.description)
+          ])
+        );
+      }
+      const suffix = opts.lane ? ` in lane "${opts.lane}"` : opts.category ? ` in category "${opts.category}"` : "";
+      note(
         o,
-        ["name", "description"],
-        list.map((t) => [t.name, t.description.split(/[.!]\s/)[0].slice(0, 90)])
+        fmt.dim(
+          o,
+          `
+${summary.length} tools${suffix}. Inspect one: videodraft tools schema <name>`
+        )
       );
-      note(o, fmt.dim(o, `
-${list.length} tools. Inspect one: videodraft tools schema <name>`));
     });
   });
   tools.command("schema <name>").description("Show a tool's description and JSON input schema").action(async function(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "videodraft",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
   "type": "module",

package/skills/videodraft/SKILL.md

@@ -5,7 +5,11 @@ description: Create AI videos, images, voiceovers, music, sound effects, dialogu
 
 # VideoDraft
 
-VideoDraft is an AI video creation platform: idea → script → storyboard (scenes + shot images) → production (voiceover, captions, motion clips, music) → exported MP4. You can drive all of it from this environment.
+VideoDraft is an AI video creation platform where asset generation is the priority lane:
+
+- **Asset generation**: standalone images, video clips, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.
+- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.
+- **Project production**: idea → script → storyboard (scenes + shot images) → project data → production timeline → exported MP4. Use this only when the user asks for a story, storyboard, editable project, timeline, or final video.
 
 ## How to connect
 
@@ -17,15 +21,18 @@ Two equivalent surfaces (same backend, same credits, same projects):
      • HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).
      • SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat — use browser `login` or the env var so the token never lands in the transcript.
    - Every command accepts `--json` (parse this, don't scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (→ tell the user, don't retry).
-   - Full API access: `videodraft tools list`, `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
+   - Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.
+   - Asset lane: `videodraft generate image|video|voiceover|music|sound-effect|dialogue|voice-changer|dub`, `videodraft upload`, and `videodraft download`.
+   - Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
 2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly — the CLI's curated commands map 1:1 onto these tools.
 
-## First decision: asset or video?
+## First decision: asset or project?
 
-- **One standalone asset** (a single image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, or dubbed media file, no story): generate it directly. Do NOT create a project.
+- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.
   - `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
   - `videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --download ./out/`
-- **A video / ad / explainer / anything multi-scene**: create a project so the work stays organized, editable in the web app, and exportable.
+- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations, but do not make a storyboard/project unless the user asks for one.
+- **A multi-scene video / ad / explainer, storyboard, timeline, or final exported video**: create a project so the work stays organized, editable in the web app, and exportable.
   - `videodraft create "30s launch video for our espresso machine" --ar 9:16`
 - **Just a script** (no video asked for): `videodraft create "..." --script-only`. Stop at the script — do not build a storyboard the user didn't ask for.
 - **Iterating on existing work**: find it first (`videodraft projects list`) and reuse that project. Never create a new project to change an existing one.