@vibeframe/cli 0.80.0 → 0.80.1

package/dist/index.js

@@ -14298,7 +14298,8 @@ function getSetupProviders() {
     key: k.configKey,
     name: k.label,
     env: k.envVar,
-    desc: k.setupDescription ?? ""
+    desc: k.setupDescription ?? "",
+    url: k.envExampleUrl
   }));
 }
 function getAllApiKeys() {
@@ -17263,18 +17264,18 @@ ${transcriptWithTimestamps}`
     return emptyViralAnalysis("Analysis failed");
   }
 }
-async function suggestPlatformCuts(api, transcriptSegments, viralAnalysis, platform, clips) {
-  const emptyResult = { platform: platform.id, segments: [], totalDuration: 0 };
+async function suggestPlatformCuts(api, transcriptSegments, viralAnalysis, platform2, clips) {
+  const emptyResult = { platform: platform2.id, segments: [], totalDuration: 0 };
   const transcriptWithTimestamps = transcriptSegments.map((seg) => `[${seg.startTime.toFixed(1)}s - ${seg.endTime.toFixed(1)}s] ${seg.text}`).join("\n");
   const clipsInfo = clips.map((c) => `[${c.id}] ${c.startTime.toFixed(1)}s - ${(c.startTime + c.duration).toFixed(1)}s (${c.duration.toFixed(1)}s)`).join("\n");
-  const systemPrompt = `You are an expert video editor optimizing content for ${platform.name}.
+  const systemPrompt = `You are an expert video editor optimizing content for ${platform2.name}.
 
 Platform requirements:
-- Aspect ratio: ${platform.aspectRatio}
-- Maximum duration: ${platform.maxDuration}s
-- Ideal duration: ${platform.idealDuration.min}-${platform.idealDuration.max}s
-- Needs strong hook: ${platform.features.hook ? "Yes" : "No"}
-- Needs captions: ${platform.features.captions ? "Yes" : "No"}
+- Aspect ratio: ${platform2.aspectRatio}
+- Maximum duration: ${platform2.maxDuration}s
+- Ideal duration: ${platform2.idealDuration.min}-${platform2.idealDuration.max}s
+- Needs strong hook: ${platform2.features.hook ? "Yes" : "No"}
+- Needs captions: ${platform2.features.captions ? "Yes" : "No"}
 
 Previous analysis found:
 - Hook strength: ${viralAnalysis.hookStrength}%
@@ -17290,7 +17291,7 @@ Your task:
 
 Respond with JSON only:
 {
-  "platform": "${platform.id}",
+  "platform": "${platform2.id}",
   "segments": [
     {"sourceClipId": "clip-id", "startTime": 0, "endTime": 45.5, "priority": 1.0}
   ],
@@ -17301,7 +17302,7 @@ Respond with JSON only:
       system: systemPrompt,
       messages: [{
         role: "user",
-        content: `Optimize this video for ${platform.name}:
+        content: `Optimize this video for ${platform2.name}:
 
 ## Transcript:
 ${transcriptWithTimestamps}
@@ -17997,10 +17998,10 @@ Instruction: ${instruction}`
         }
         return analyzeViralPotential(this.api, transcriptSegments, projectMeta, targetPlatforms);
       }
-      async suggestPlatformCuts(transcriptSegments, viralAnalysis, platform, clips) {
+      async suggestPlatformCuts(transcriptSegments, viralAnalysis, platform2, clips) {
         if (!this.api)
-          return { platform: platform.id, segments: [], totalDuration: 0 };
-        return suggestPlatformCuts(this.api, transcriptSegments, viralAnalysis, platform, clips);
+          return { platform: platform2.id, segments: [], totalDuration: 0 };
+        return suggestPlatformCuts(this.api, transcriptSegments, viralAnalysis, platform2, clips);
       }
       async generateViralCaptions(transcriptSegments, style) {
         if (!this.api)
@@ -31526,6 +31527,44 @@ var init_storyboard = __esm({
   }
 });
 
+// src/utils/open-url.ts
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+async function openUrl(url) {
+  const { command, args } = resolveOpener(url);
+  if (!command) return;
+  try {
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: "ignore",
+      shell: false
+    });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+function resolveOpener(url) {
+  switch (platform()) {
+    case "darwin":
+      return { command: "open", args: [url] };
+    case "win32":
+      return { command: "cmd", args: ["/c", "start", "", url] };
+    case "linux":
+    case "freebsd":
+    case "openbsd":
+      return { command: "xdg-open", args: [url] };
+    default:
+      return { command: null, args: [] };
+  }
+}
+var init_open_url = __esm({
+  "src/utils/open-url.ts"() {
+    "use strict";
+  }
+});
+
 // src/utils/tty.ts
 import { createInterface as createInterface2 } from "node:readline";
 import { ReadStream } from "node:tty";
@@ -31579,7 +31618,7 @@ async function prompt2(question) {
     });
   });
 }
-async function promptHidden(question) {
+async function promptHidden(question, opts = {}) {
   const input = getTTYInputStream();
   return new Promise((resolve64) => {
     process.stdout.write(question);
@@ -31598,6 +31637,8 @@ async function promptHidden(question) {
           input.setRawMode(false);
           process.stdout.write("\n");
           process.exit(1);
+        } else if (opts.openHotkeyUrl && value.length === 0 && (char === "o" || char === "O")) {
+          void openUrl(opts.openHotkeyUrl);
         } else if (char === "\x7F" || char === "\b") {
           if (value.length > 0) {
             value = value.slice(0, -1);
@@ -31681,6 +31722,59 @@ async function promptSelect(_question, options, defaultIndex = 0) {
   return index;
 }
 async function promptConfirm(question, defaultYes = true) {
+  const input = getTTYInputStream();
+  if (typeof input.setRawMode === "function") {
+    return new Promise((resolve64) => {
+      const options = ["Yes", "No"];
+      let selected = defaultYes ? 0 : 1;
+      let renderCount = 0;
+      process.stdout.write(`${question}
+`);
+      const render = () => {
+        if (renderCount > 0) {
+          process.stdout.write(`\x1B[${options.length}A`);
+        }
+        for (let i = 0; i < options.length; i++) {
+          const marker = i === selected ? "\x1B[36m\u276F\x1B[0m" : " ";
+          const text = i === selected ? `\x1B[1m${options[i]}\x1B[0m` : options[i];
+          process.stdout.write(`\x1B[2K   ${marker} ${text}
+`);
+        }
+        renderCount++;
+      };
+      render();
+      input.setRawMode(true);
+      input.resume();
+      input.setEncoding("utf8");
+      const onData = (char) => {
+        if (char === "\r" || char === "\n") {
+          input.setRawMode(false);
+          input.removeListener("data", onData);
+          resolve64(selected === 0);
+        } else if (char === "") {
+          input.setRawMode(false);
+          process.stdout.write("\n");
+          process.exit(1);
+        } else if (char === "\x1B[A" || char === "\x1B[B" || char === "k" || char === "j") {
+          selected = selected === 0 ? 1 : 0;
+          render();
+        } else if (char === "y" || char === "Y") {
+          selected = 0;
+          input.setRawMode(false);
+          input.removeListener("data", onData);
+          render();
+          resolve64(true);
+        } else if (char === "n" || char === "N") {
+          selected = 1;
+          input.setRawMode(false);
+          input.removeListener("data", onData);
+          render();
+          resolve64(false);
+        }
+      };
+      input.on("data", onData);
+    });
+  }
   const hint = defaultYes ? "(Y/n)" : "(y/N)";
   const answer = await prompt2(`${question} ${hint}: `);
   if (answer === "") return defaultYes;
@@ -31774,6 +31868,7 @@ var ttyStream;
 var init_tty = __esm({
   "src/utils/tty.ts"() {
     "use strict";
+    init_open_url();
     ttyStream = null;
   }
 });
@@ -33531,7 +33626,7 @@ Examples:
           }
         }
       } else if (provider === "runway") {
-        const { spawn: spawn2 } = await import("child_process");
+        const { spawn: spawn3 } = await import("child_process");
         const __filename2 = fileURLToPath(import.meta.url);
         const __dirname2 = dirname7(__filename2);
         const scriptPath = resolve23(
@@ -33546,7 +33641,7 @@ Examples:
         const args = [scriptPath, prompt3, "-o", outputPath, "-r", options.ratio || "16:9"];
         spinner2.text = "Generating image with Runway (gemini_2.5_flash)...";
         await new Promise((resolvePromise, reject) => {
-          const proc = spawn2("python3", args, {
+          const proc = spawn3("python3", args, {
             env: { ...process.env, RUNWAY_API_SECRET: apiKey },
             stdio: ["ignore", "pipe", "pipe"]
           });
@@ -36906,8 +37001,8 @@ var init_translate_srt = __esm({
 import { existsSync as existsSync21 } from "node:fs";
 import { resolve as resolve27 } from "node:path";
 function detectSystemFont() {
-  const platform = process.platform;
-  if (platform === "darwin") {
+  const platform2 = process.platform;
+  if (platform2 === "darwin") {
     const candidates = [
       "/System/Library/Fonts/Helvetica.ttc",
       "/System/Library/Fonts/HelveticaNeue.ttc",
@@ -36916,7 +37011,7 @@ function detectSystemFont() {
     for (const f of candidates) {
       if (existsSync21(f)) return f;
     }
-  } else if (platform === "linux") {
+  } else if (platform2 === "linux") {
     const candidates = [
       "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
       "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
@@ -36925,7 +37020,7 @@ function detectSystemFont() {
     for (const f of candidates) {
       if (existsSync21(f)) return f;
     }
-  } else if (platform === "win32") {
+  } else if (platform2 === "win32") {
     const candidates = [
       "C:\\Windows\\Fonts\\arial.ttf",
       "C:\\Windows\\Fonts\\segoeui.ttf"
@@ -36976,11 +37071,11 @@ async function applyTextOverlays(options) {
     } = await Promise.resolve().then(() => (init_remotion(), remotion_exports));
     const remotionErr = await ensureRemotionInstalled2();
     if (remotionErr) {
-      const platform = process.platform;
+      const platform2 = process.platform;
       let hint = "";
-      if (platform === "darwin") {
+      if (platform2 === "darwin") {
         hint = "\n\nFix: brew uninstall ffmpeg && brew install ffmpeg\n(The default homebrew formula includes libfreetype)";
-      } else if (platform === "linux") {
+      } else if (platform2 === "linux") {
         hint = "\n\nFix: sudo apt install ffmpeg (Ubuntu/Debian)\n     or rebuild FFmpeg with --enable-libfreetype";
       }
       return {
@@ -50813,6 +50908,320 @@ var init_detect = __esm({
   }
 });
 
+// src/commands/_shared/walkthroughs/walkthroughs.ts
+function loadWalkthrough(topic) {
+  const meta = META[topic];
+  const content = CONTENT[topic];
+  if (!meta || !content) {
+    throw new Error(`Unknown walkthrough topic: ${topic}`);
+  }
+  return {
+    topic,
+    title: meta.title,
+    summary: meta.summary,
+    steps: meta.steps,
+    relatedCommands: meta.relatedCommands,
+    content
+  };
+}
+function listWalkthroughs() {
+  return WALKTHROUGH_TOPICS.map((topic) => ({
+    topic,
+    title: META[topic].title,
+    summary: META[topic].summary
+  }));
+}
+function isWalkthroughTopic(value) {
+  return typeof value === "string" && WALKTHROUGH_TOPICS.includes(value);
+}
+var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
+var init_walkthroughs = __esm({
+  "src/commands/_shared/walkthroughs/walkthroughs.ts"() {
+    "use strict";
+    SCENE_WALKTHROUGH = `# Scene authoring with vibe
+
+A scene project is a directory that is **bilingual**: it works with both
+\`vibe\` and \`npx hyperframes\`. Each scene is one HTML file with scoped CSS
+and a paused GSAP timeline. Cheap to edit, cheap to lint, expensive only
+at render.
+
+\`vibe build\` (v0.60+) is the supported one-shot driver from a
+written storyboard to an MP4. Plan H (v0.70) added \`--mode agent\` so the
+host agent itself authors the per-beat HTML \u2014 no internal LLM call.
+
+## Three authoring paths
+
+| Path | Command | When to use |
+|---|---|---|
+| **One-shot (default, v0.60+)** | \`vibe build [project-dir]\` | STORYBOARD.md has YAML frontmatter + per-beat cues |
+| **High-craft (manual)** | \`DESIGN.md\` + local composition rules in your agent | Maximum control: hand-author each scene |
+| **Quick draft** | \`vibe scene add --style <preset>\` | No agent or no API keys; fast iteration |
+
+Recommend \`vibe build\` whenever the user has a STORYBOARD with
+narration / backdrop intent.
+
+## High-craft path
+
+1. \`vibe init my-promo --visual-style "Swiss Pulse"\` \u2014 seeds
+   \`DESIGN.md\` (palette, typography, motion, transitions) plus the
+   \`vibe.project.yaml\` / \`hyperframes.json\` / \`index.html\` scaffold.
+   In Plan H this **also installs local composition rules** at the
+   right place for your host (\`.claude/skills/hyperframes/\` for Claude
+   Code, \`.cursor/rules/hyperframes.mdc\` for Cursor, universal
+   \`SKILL.md\` for everyone else).
+2. Read \`SKILL.md\` (or the host-specific copy) \u2014 Hyperframes
+   framework rules, motion principles, type system, transition recipes.
+3. Read \`DESIGN.md\` \u2014 project-specific palette / typography / motion
+   signature (visual identity hard-gate).
+4. Author each scene HTML directly under \`compositions/scene-<id>.html\`
+   using the rules from steps 2 and 3. The skill enforces the visual
+   identity contract \u2014 scenes that contradict DESIGN.md fail lint.
+5. \`vibe scene lint --fix\` for mechanical issues, \`vibe render my-promo\`
+   to MP4.
+
+## Quick-draft path
+
+\`\`\`bash
+vibe init my-promo -r 16:9 -d 30
+vibe scene add intro --style announcement \\
+    --headline "Ship videos, not clicks"
+vibe scene lint
+vibe render my-promo
+\`\`\`
+
+\`vibe init\` is **idempotent** \u2014 running it on an existing Hyperframes
+directory merges \`hyperframes.json\` instead of clobbering it. Safe to
+invoke on user-provided projects.
+
+## Subcommands
+
+\`\`\`bash
+# Project flow (top-level \u2014 preferred entry points)
+vibe init <dir> [-r 16:9|9:16|1:1|4:5] [-d <sec>] [--visual-style "<name>"]
+vibe build [<dir>] [--mode agent|batch|auto]         # H3 dispatch
+vibe render [<dir>] [--fps 30] [--quality standard] [--format mp4]
+
+# Lower-level scene authoring
+vibe scene list-styles [<name>]                   # list / show vendored visual identities
+vibe scene install-skill [<dir>] [--host all]  # retroactive composition-rules install
+vibe scene add <name> --style <preset> [...]
+vibe scene compose-prompts [<dir>] [--beat <id>]   # H2: emit plan, no LLM call
+vibe scene lint [<root>] [--json] [--fix]
+\`\`\`
+
+## Style presets (for \`vibe scene add --style\`)
+
+- **simple** \u2014 backdrop + bottom caption (default)
+- **announcement** \u2014 single huge headline, gradient text
+- **explainer** \u2014 kicker + title + subtitle stack
+- **kinetic-type** \u2014 words animate in word-by-word
+- **product-shot** \u2014 corner label + bottom headline + slow zoom
+
+All presets accept \`--narration <text|file>\`, \`--visuals <prompt>\`,
+\`--headline\`, \`--kicker\`. With \`--narration\`, scene duration auto-derives
+from the generated TTS audio.
+
+## STORYBOARD-to-MP4 (one command, v0.60+)
+
+\`\`\`bash
+vibe init my-promo --visual-style "Swiss Pulse" -d 12
+# (edit STORYBOARD.md with per-beat YAML cues \u2014 narration, backdrop, duration)
+vibe build my-promo
+\`\`\`
+
+\`vibe build\` reads the STORYBOARD frontmatter + per-beat cues,
+dispatches TTS + image-gen per beat, then either:
+
+- **\`--mode agent\`** (default when an agent host is detected) \u2014 emits a
+  \`needs-author\` plan via \`vibe scene compose-prompts\`. The host agent
+  authors each \`compositions/scene-<id>.html\` itself, then re-invoking
+  \`vibe build\` proceeds to lint + render.
+- **\`--mode batch\`** \u2014 VibeFrame runs an internal LLM (Claude / OpenAI /
+  Gemini) to compose the HTML, then renders.
+
+\`VIBE_BUILD_MODE\` env var overrides the auto-resolve.
+
+## Lint feedback loop
+
+\`\`\`bash
+vibe scene lint --json --fix
+\`\`\`
+
+Returns structured findings. The recommended loop: 1) run lint with
+\`--fix\` (mechanical fixes applied), 2) if \`errorCount > 0\`, edit the
+scene HTML, 3) re-lint. Cap retries at 3 \u2014 if errors persist, fall back
+to a template preset (\`vibe scene add <id> --style simple --force\`)
+and surface the error to the user.
+
+## When to use VibeFrame vs raw Hyperframes
+
+| Task | Tool |
+|------|------|
+| Generate narration + image, then author scene | \`vibe scene add\` |
+| Generate a full scenes project from a STORYBOARD | \`vibe build\` |
+| Hand-tweak a single scene's animation | edit \`compositions/<file>.html\` directly |
+| Render the project | \`vibe render\` (one canonical entry point) |
+| Lint | \`vibe scene lint\` *or* \`npx hyperframes lint\` (equivalent) |
+
+The \`vibe\` CLI adds asset generation, AI orchestration, and pipeline
+integration on top of Hyperframes' rendering primitives.
+
+## Quality checklist before render
+
+- [ ] \`vibe scene lint\` exits 0 (or only warnings)
+- [ ] \`vibe doctor\` confirms a usable Chrome (required for render)
+- [ ] Root \`data-duration\` matches the sum of clip durations
+- [ ] Aspect ratio in \`vibe.project.yaml\` matches the destination platform
+`;
+    PIPELINE_WALKTHROUGH = `# YAML pipelines (Video as Code)
+
+A pipeline is a YAML manifest with steps that reference each other's
+outputs. \`vibe run pipeline.yaml\` executes them with checkpointing and
+cost estimation.
+
+## Minimal skeleton
+
+\`\`\`yaml
+name: promo-video
+description: 15s product teaser
+steps:
+  - id: backdrop
+    action: generate-image
+    prompt: "sleek product shot on white background"
+    output: backdrop.png
+  - id: scene
+    action: generate-video
+    image: $backdrop.output        # reference previous step output
+    prompt: "slow camera pan"
+    duration: 5
+    output: scene.mp4
+  - id: voice
+    action: generate-tts
+    text: "Meet the new standard."
+    output: voice.mp3
+  - id: final
+    action: compose
+    video: $scene.output
+    audio: $voice.output
+    output: final.mp4
+\`\`\`
+
+## Supported actions
+
+- \`generate-image\`, \`generate-video\`, \`generate-tts\`, \`generate-music\`,
+  \`generate-sound-effect\`, \`generate-storyboard\`, \`generate-motion\`
+- \`edit-silence-cut\`, \`edit-jump-cut\`, \`edit-caption\`, \`edit-grade\`,
+  \`edit-reframe\`, \`edit-speed-ramp\`, \`edit-fade\`, \`edit-noise-reduce\`,
+  \`edit-text-overlay\`, \`edit-fill-gaps\`
+- \`analyze-media\`, \`analyze-video\`, \`analyze-review\`, \`analyze-suggest\`
+- \`audio-transcribe\`, \`audio-isolate\`, \`audio-voice-clone\`, \`audio-dub\`,
+  \`audio-duck\`
+- \`detect-scenes\`, \`detect-silence\`, \`detect-beats\`
+- \`compose\`, \`export\`
+- \`scene-build\` (Plan H one-shot driver) and \`scene-render\`
+- \`compose-scenes-with-skills\` (internal-LLM compose pass)
+
+The full set lives in \`packages/cli/src/pipeline/executor.ts\`.
+
+## Variable references
+
+- \`$<step-id>.output\` \u2014 previous step's output path
+- \`$<step-id>.result.<field>\` \u2014 structured field from JSON result
+- \`\${ENV_VAR}\` \u2014 environment variable
+- Values can be templated: \`"\${SCRIPT_TITLE} - Episode \${EPISODE}"\`
+
+## Running
+
+\`\`\`bash
+vibe run pipeline.yaml --dry-run           # plan + cost estimate, no execution
+vibe run pipeline.yaml                     # execute
+vibe run pipeline.yaml --resume            # retry from last successful step
+vibe run pipeline.yaml --from scene        # start at specific step
+vibe run pipeline.yaml --provider-video kling   # override provider
+\`\`\`
+
+Checkpoints land next to the YAML: \`pipeline.yaml.checkpoint.json\`.
+
+## Authoring tips
+
+1. **Start from a tiny YAML** \u2014 keep it in your project directory and run
+   \`vibe run pipeline.yaml --dry-run\` before spending provider budget.
+2. **Dry-run first** \u2014 you see estimated cost and resolved variable
+   graph before spending API credits.
+3. **Keep step ids short and descriptive** (\`intro\`, \`scene1\`, \`voice\`,
+   \`bgm\`) \u2014 they appear in logs and variable refs.
+4. **Name outputs** with extensions matching the action (\`.mp4\`, \`.mp3\`,
+   \`.png\`, \`.json\`).
+5. **Declare \`budget:\`** on expensive pipelines:
+   \`\`\`yaml
+   budget:
+     tokens: 500_000
+     max_tool_errors: 3
+     cost_usd: 5.00
+   \`\`\`
+6. **Split large pipelines** into smaller YAML files and compose via
+   \`action: run-pipeline\` (nested).
+
+## Converting ad-hoc shell sessions to pipelines
+
+When the user has a working shell sequence, extract steps:
+
+- Each \`vibe ...\` command becomes one step
+- File outputs become step outputs; downstream \`-i <file>\` references
+  become \`$<id>.output\`
+- Shared parameters move to a top-level \`defaults:\` section
+- Wrap the entire chain in a \`name:\` + \`steps:\` skeleton
+
+The \`compose\` action is the catch-all assembly step (audio mux, video
+overlay, etc.) \u2014 useful at the tail of a pipeline.
+`;
+    META = {
+      scene: {
+        title: "Scene authoring with vibe",
+        summary: "Author per-scene HTML compositions and render to MP4 (BUILD flow)",
+        steps: [
+          'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project + install local composition rules.',
+          "Edit `STORYBOARD.md` with per-beat YAML cues (narration / backdrop / duration).",
+          "Read `SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
+          "Run `vibe build <dir>`. With an agent host detected, the CLI emits a `needs-author` plan; the host agent authors each `compositions/scene-<id>.html` and re-invokes to render.",
+          "Run `vibe scene lint --fix` to validate, then `vibe render <dir>` to produce the MP4."
+        ],
+        relatedCommands: [
+          "vibe init",
+          "vibe build",
+          "vibe render",
+          "vibe scene list-styles",
+          "vibe scene install-skill",
+          "vibe scene compose-prompts",
+          "vibe scene lint",
+          "vibe scene add"
+        ]
+      },
+      pipeline: {
+        title: "YAML pipelines (Video as Code)",
+        summary: "Author and run reproducible multi-step video workflows",
+        steps: [
+          "Sketch the workflow as YAML \u2014 `name`, `description`, then `steps:` with `id` + `action` + inputs/outputs.",
+          "Reference previous step outputs via `$<step-id>.output` (or `$<step-id>.result.<field>` for structured returns).",
+          "Run `vibe run pipeline.yaml --dry-run` to see the resolved graph + cost estimate before spending API budget.",
+          "Add a `budget:` block (tokens / cost_usd / max_tool_errors) to cap expensive runs.",
+          "Run `vibe run pipeline.yaml` to execute. Failed steps checkpoint to `pipeline.yaml.checkpoint.json`; resume with `--resume`."
+        ],
+        relatedCommands: [
+          "vibe run",
+          "vibe schema --list",
+          "vibe doctor"
+        ]
+      }
+    };
+    CONTENT = {
+      scene: SCENE_WALKTHROUGH,
+      pipeline: PIPELINE_WALKTHROUGH
+    };
+    WALKTHROUGH_TOPICS = ["scene", "pipeline"];
+  }
+});
+
 // src/pipeline/renderers/chrome.ts
 import { existsSync as existsSync32 } from "node:fs";
 import { homedir as homedir5 } from "node:os";
@@ -60062,7 +60471,7 @@ var init_hyperframes = __esm({
 // src/commands/export.ts
 import { readFile as readFile40, access as access8 } from "node:fs/promises";
 import { resolve as resolve61, basename as basename21 } from "node:path";
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 function timelineBaseName(path2) {
   const name = basename21(path2);
   if (name.endsWith(".vibe.json")) return name.slice(0, -".vibe.json".length);
@@ -60536,7 +60945,7 @@ function buildFFmpegArgs(clips, sources, presetSettings, outputPath, options, so
 }
 function runFFmpegProcess(ffmpegPath, args, onProgress) {
   return new Promise((resolve64, reject) => {
-    const ffmpeg = spawn(ffmpegPath, args, {
+    const ffmpeg = spawn2(ffmpegPath, args, {
       stdio: ["pipe", "pipe", "pipe"]
     });
     let duration = 0;
@@ -61819,320 +62228,6 @@ Audio:`);
   }
 });
 
-// src/commands/_shared/walkthroughs/walkthroughs.ts
-function loadWalkthrough(topic) {
-  const meta = META[topic];
-  const content = CONTENT[topic];
-  if (!meta || !content) {
-    throw new Error(`Unknown walkthrough topic: ${topic}`);
-  }
-  return {
-    topic,
-    title: meta.title,
-    summary: meta.summary,
-    steps: meta.steps,
-    relatedCommands: meta.relatedCommands,
-    content
-  };
-}
-function listWalkthroughs() {
-  return WALKTHROUGH_TOPICS.map((topic) => ({
-    topic,
-    title: META[topic].title,
-    summary: META[topic].summary
-  }));
-}
-function isWalkthroughTopic(value) {
-  return typeof value === "string" && WALKTHROUGH_TOPICS.includes(value);
-}
-var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
-var init_walkthroughs = __esm({
-  "src/commands/_shared/walkthroughs/walkthroughs.ts"() {
-    "use strict";
-    SCENE_WALKTHROUGH = `# Scene authoring with vibe
-
-A scene project is a directory that is **bilingual**: it works with both
-\`vibe\` and \`npx hyperframes\`. Each scene is one HTML file with scoped CSS
-and a paused GSAP timeline. Cheap to edit, cheap to lint, expensive only
-at render.
-
-\`vibe build\` (v0.60+) is the supported one-shot driver from a
-written storyboard to an MP4. Plan H (v0.70) added \`--mode agent\` so the
-host agent itself authors the per-beat HTML \u2014 no internal LLM call.
-
-## Three authoring paths
-
-| Path | Command | When to use |
-|---|---|---|
-| **One-shot (default, v0.60+)** | \`vibe build [project-dir]\` | STORYBOARD.md has YAML frontmatter + per-beat cues |
-| **High-craft (manual)** | \`DESIGN.md\` + local composition rules in your agent | Maximum control: hand-author each scene |
-| **Quick draft** | \`vibe scene add --style <preset>\` | No agent or no API keys; fast iteration |
-
-Recommend \`vibe build\` whenever the user has a STORYBOARD with
-narration / backdrop intent.
-
-## High-craft path
-
-1. \`vibe init my-promo --visual-style "Swiss Pulse"\` \u2014 seeds
-   \`DESIGN.md\` (palette, typography, motion, transitions) plus the
-   \`vibe.project.yaml\` / \`hyperframes.json\` / \`index.html\` scaffold.
-   In Plan H this **also installs local composition rules** at the
-   right place for your host (\`.claude/skills/hyperframes/\` for Claude
-   Code, \`.cursor/rules/hyperframes.mdc\` for Cursor, universal
-   \`SKILL.md\` for everyone else).
-2. Read \`SKILL.md\` (or the host-specific copy) \u2014 Hyperframes
-   framework rules, motion principles, type system, transition recipes.
-3. Read \`DESIGN.md\` \u2014 project-specific palette / typography / motion
-   signature (visual identity hard-gate).
-4. Author each scene HTML directly under \`compositions/scene-<id>.html\`
-   using the rules from steps 2 and 3. The skill enforces the visual
-   identity contract \u2014 scenes that contradict DESIGN.md fail lint.
-5. \`vibe scene lint --fix\` for mechanical issues, \`vibe render my-promo\`
-   to MP4.
-
-## Quick-draft path
-
-\`\`\`bash
-vibe init my-promo -r 16:9 -d 30
-vibe scene add intro --style announcement \\
-    --headline "Ship videos, not clicks"
-vibe scene lint
-vibe render my-promo
-\`\`\`
-
-\`vibe init\` is **idempotent** \u2014 running it on an existing Hyperframes
-directory merges \`hyperframes.json\` instead of clobbering it. Safe to
-invoke on user-provided projects.
-
-## Subcommands
-
-\`\`\`bash
-# Project flow (top-level \u2014 preferred entry points)
-vibe init <dir> [-r 16:9|9:16|1:1|4:5] [-d <sec>] [--visual-style "<name>"]
-vibe build [<dir>] [--mode agent|batch|auto]         # H3 dispatch
-vibe render [<dir>] [--fps 30] [--quality standard] [--format mp4]
-
-# Lower-level scene authoring
-vibe scene list-styles [<name>]                   # list / show vendored visual identities
-vibe scene install-skill [<dir>] [--host all]  # retroactive composition-rules install
-vibe scene add <name> --style <preset> [...]
-vibe scene compose-prompts [<dir>] [--beat <id>]   # H2: emit plan, no LLM call
-vibe scene lint [<root>] [--json] [--fix]
-\`\`\`
-
-## Style presets (for \`vibe scene add --style\`)
-
-- **simple** \u2014 backdrop + bottom caption (default)
-- **announcement** \u2014 single huge headline, gradient text
-- **explainer** \u2014 kicker + title + subtitle stack
-- **kinetic-type** \u2014 words animate in word-by-word
-- **product-shot** \u2014 corner label + bottom headline + slow zoom
-
-All presets accept \`--narration <text|file>\`, \`--visuals <prompt>\`,
-\`--headline\`, \`--kicker\`. With \`--narration\`, scene duration auto-derives
-from the generated TTS audio.
-
-## STORYBOARD-to-MP4 (one command, v0.60+)
-
-\`\`\`bash
-vibe init my-promo --visual-style "Swiss Pulse" -d 12
-# (edit STORYBOARD.md with per-beat YAML cues \u2014 narration, backdrop, duration)
-vibe build my-promo
-\`\`\`
-
-\`vibe build\` reads the STORYBOARD frontmatter + per-beat cues,
-dispatches TTS + image-gen per beat, then either:
-
-- **\`--mode agent\`** (default when an agent host is detected) \u2014 emits a
-  \`needs-author\` plan via \`vibe scene compose-prompts\`. The host agent
-  authors each \`compositions/scene-<id>.html\` itself, then re-invoking
-  \`vibe build\` proceeds to lint + render.
-- **\`--mode batch\`** \u2014 VibeFrame runs an internal LLM (Claude / OpenAI /
-  Gemini) to compose the HTML, then renders.
-
-\`VIBE_BUILD_MODE\` env var overrides the auto-resolve.
-
-## Lint feedback loop
-
-\`\`\`bash
-vibe scene lint --json --fix
-\`\`\`
-
-Returns structured findings. The recommended loop: 1) run lint with
-\`--fix\` (mechanical fixes applied), 2) if \`errorCount > 0\`, edit the
-scene HTML, 3) re-lint. Cap retries at 3 \u2014 if errors persist, fall back
-to a template preset (\`vibe scene add <id> --style simple --force\`)
-and surface the error to the user.
-
-## When to use VibeFrame vs raw Hyperframes
-
-| Task | Tool |
-|------|------|
-| Generate narration + image, then author scene | \`vibe scene add\` |
-| Generate a full scenes project from a STORYBOARD | \`vibe build\` |
-| Hand-tweak a single scene's animation | edit \`compositions/<file>.html\` directly |
-| Render the project | \`vibe render\` (one canonical entry point) |
-| Lint | \`vibe scene lint\` *or* \`npx hyperframes lint\` (equivalent) |
-
-The \`vibe\` CLI adds asset generation, AI orchestration, and pipeline
-integration on top of Hyperframes' rendering primitives.
-
-## Quality checklist before render
-
-- [ ] \`vibe scene lint\` exits 0 (or only warnings)
-- [ ] \`vibe doctor\` confirms a usable Chrome (required for render)
-- [ ] Root \`data-duration\` matches the sum of clip durations
-- [ ] Aspect ratio in \`vibe.project.yaml\` matches the destination platform
-`;
-    PIPELINE_WALKTHROUGH = `# YAML pipelines (Video as Code)
-
-A pipeline is a YAML manifest with steps that reference each other's
-outputs. \`vibe run pipeline.yaml\` executes them with checkpointing and
-cost estimation.
-
-## Minimal skeleton
-
-\`\`\`yaml
-name: promo-video
-description: 15s product teaser
-steps:
-  - id: backdrop
-    action: generate-image
-    prompt: "sleek product shot on white background"
-    output: backdrop.png
-  - id: scene
-    action: generate-video
-    image: $backdrop.output        # reference previous step output
-    prompt: "slow camera pan"
-    duration: 5
-    output: scene.mp4
-  - id: voice
-    action: generate-tts
-    text: "Meet the new standard."
-    output: voice.mp3
-  - id: final
-    action: compose
-    video: $scene.output
-    audio: $voice.output
-    output: final.mp4
-\`\`\`
-
-## Supported actions
-
-- \`generate-image\`, \`generate-video\`, \`generate-tts\`, \`generate-music\`,
-  \`generate-sound-effect\`, \`generate-storyboard\`, \`generate-motion\`
-- \`edit-silence-cut\`, \`edit-jump-cut\`, \`edit-caption\`, \`edit-grade\`,
-  \`edit-reframe\`, \`edit-speed-ramp\`, \`edit-fade\`, \`edit-noise-reduce\`,
-  \`edit-text-overlay\`, \`edit-fill-gaps\`
-- \`analyze-media\`, \`analyze-video\`, \`analyze-review\`, \`analyze-suggest\`
-- \`audio-transcribe\`, \`audio-isolate\`, \`audio-voice-clone\`, \`audio-dub\`,
-  \`audio-duck\`
-- \`detect-scenes\`, \`detect-silence\`, \`detect-beats\`
-- \`compose\`, \`export\`
-- \`scene-build\` (Plan H one-shot driver) and \`scene-render\`
-- \`compose-scenes-with-skills\` (internal-LLM compose pass)
-
-The full set lives in \`packages/cli/src/pipeline/executor.ts\`.
-
-## Variable references
-
-- \`$<step-id>.output\` \u2014 previous step's output path
-- \`$<step-id>.result.<field>\` \u2014 structured field from JSON result
-- \`\${ENV_VAR}\` \u2014 environment variable
-- Values can be templated: \`"\${SCRIPT_TITLE} - Episode \${EPISODE}"\`
-
-## Running
-
-\`\`\`bash
-vibe run pipeline.yaml --dry-run           # plan + cost estimate, no execution
-vibe run pipeline.yaml                     # execute
-vibe run pipeline.yaml --resume            # retry from last successful step
-vibe run pipeline.yaml --from scene        # start at specific step
-vibe run pipeline.yaml --provider-video kling   # override provider
-\`\`\`
-
-Checkpoints land next to the YAML: \`pipeline.yaml.checkpoint.json\`.
-
-## Authoring tips
-
-1. **Start from a tiny YAML** \u2014 keep it in your project directory and run
-   \`vibe run pipeline.yaml --dry-run\` before spending provider budget.
-2. **Dry-run first** \u2014 you see estimated cost and resolved variable
-   graph before spending API credits.
-3. **Keep step ids short and descriptive** (\`intro\`, \`scene1\`, \`voice\`,
-   \`bgm\`) \u2014 they appear in logs and variable refs.
-4. **Name outputs** with extensions matching the action (\`.mp4\`, \`.mp3\`,
-   \`.png\`, \`.json\`).
-5. **Declare \`budget:\`** on expensive pipelines:
-   \`\`\`yaml
-   budget:
-     tokens: 500_000
-     max_tool_errors: 3
-     cost_usd: 5.00
-   \`\`\`
-6. **Split large pipelines** into smaller YAML files and compose via
-   \`action: run-pipeline\` (nested).
-
-## Converting ad-hoc shell sessions to pipelines
-
-When the user has a working shell sequence, extract steps:
-
-- Each \`vibe ...\` command becomes one step
-- File outputs become step outputs; downstream \`-i <file>\` references
-  become \`$<id>.output\`
-- Shared parameters move to a top-level \`defaults:\` section
-- Wrap the entire chain in a \`name:\` + \`steps:\` skeleton
-
-The \`compose\` action is the catch-all assembly step (audio mux, video
-overlay, etc.) \u2014 useful at the tail of a pipeline.
-`;
-    META = {
-      scene: {
-        title: "Scene authoring with vibe",
-        summary: "Author per-scene HTML compositions and render to MP4 (BUILD flow)",
-        steps: [
-          'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project + install local composition rules.',
-          "Edit `STORYBOARD.md` with per-beat YAML cues (narration / backdrop / duration).",
-          "Read `SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
-          "Run `vibe build <dir>`. With an agent host detected, the CLI emits a `needs-author` plan; the host agent authors each `compositions/scene-<id>.html` and re-invokes to render.",
-          "Run `vibe scene lint --fix` to validate, then `vibe render <dir>` to produce the MP4."
-        ],
-        relatedCommands: [
-          "vibe init",
-          "vibe build",
-          "vibe render",
-          "vibe scene list-styles",
-          "vibe scene install-skill",
-          "vibe scene compose-prompts",
-          "vibe scene lint",
-          "vibe scene add"
-        ]
-      },
-      pipeline: {
-        title: "YAML pipelines (Video as Code)",
-        summary: "Author and run reproducible multi-step video workflows",
-        steps: [
-          "Sketch the workflow as YAML \u2014 `name`, `description`, then `steps:` with `id` + `action` + inputs/outputs.",
-          "Reference previous step outputs via `$<step-id>.output` (or `$<step-id>.result.<field>` for structured returns).",
-          "Run `vibe run pipeline.yaml --dry-run` to see the resolved graph + cost estimate before spending API budget.",
-          "Add a `budget:` block (tokens / cost_usd / max_tool_errors) to cap expensive runs.",
-          "Run `vibe run pipeline.yaml` to execute. Failed steps checkpoint to `pipeline.yaml.checkpoint.json`; resume with `--resume`."
-        ],
-        relatedCommands: [
-          "vibe run",
-          "vibe schema --list",
-          "vibe doctor"
-        ]
-      }
-    };
-    CONTENT = {
-      scene: SCENE_WALKTHROUGH,
-      pipeline: PIPELINE_WALKTHROUGH
-    };
-    WALKTHROUGH_TOPICS = ["scene", "pipeline"];
-  }
-});
-
 // src/tools/manifest/walkthrough.ts
 var walkthroughSchema, walkthroughTool, walkthroughTools;
 var init_walkthrough = __esm({
@@ -62428,7 +62523,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.80.0",
+  version: "0.80.1",
   description: "VibeFrame CLI - natural language video editing from the terminal",
   private: false,
   license: "MIT",
@@ -69305,6 +69400,7 @@ function validateKeyFormat(configKey, value) {
 // src/commands/setup.ts
 init_agent_host_detect();
 init_dist2();
+init_walkthroughs();
 var VALID_LLM_PROVIDERS = [
   "claude",
   "openai",
@@ -69552,8 +69648,11 @@ async function runSetupWizard(fullSetup = false) {
         continue;
       }
       console.log(source_default.dim(`  ${keyDef.what}`));
-      console.log(source_default.dim(`  Get key: ${keyDef.url}`));
-      const newKey = await promptHidden(source_default.cyan(`  ${keyDef.name.padEnd(14)} ${source_default.dim(keyDef.envVar)}: `));
+      console.log(source_default.dim(`  Get key: ${keyDef.url}  [o] open in browser`));
+      const newKey = await promptHidden(
+        source_default.cyan(`  ${keyDef.name.padEnd(14)} ${source_default.dim(keyDef.envVar)}: `),
+        { openHotkeyUrl: keyDef.url }
+      );
       if (newKey.trim()) {
         const trimmed = newKey.trim();
         config2.providers[keyDef.configKey] = trimmed;
@@ -69587,8 +69686,11 @@ async function collectKeys(config2, keys) {
       continue;
     }
     console.log(source_default.dim(`  ${keyDef.what}`));
-    console.log(source_default.dim(`  Get key: ${keyDef.url}`));
-    const newKey = await promptHidden(source_default.cyan(`  ${keyDef.name.padEnd(14)} ${source_default.dim(keyDef.envVar)}: `));
+    console.log(source_default.dim(`  Get key: ${keyDef.url}  [o] open in browser`));
+    const newKey = await promptHidden(
+      source_default.cyan(`  ${keyDef.name.padEnd(14)} ${source_default.dim(keyDef.envVar)}: `),
+      { openHotkeyUrl: keyDef.url }
+    );
     if (newKey.trim()) {
       const trimmed = newKey.trim();
       config2.providers[keyDef.configKey] = trimmed;
@@ -69639,7 +69741,11 @@ async function runCustomSetup(config2) {
       console.log(`  ${source_default.green("\u2713")} ${p.name.padEnd(12)} ${maskApiKey(existing)} ${source_default.dim(p.desc)}`);
       const change = await promptConfirm(source_default.cyan("    Update?"), false);
       if (change) {
-        const newKey = await promptHidden(source_default.cyan("    New key: "));
+        console.log(source_default.dim(`    Get key: ${p.url}  [o] open in browser`));
+        const newKey = await promptHidden(
+          source_default.cyan("    New key: "),
+          { openHotkeyUrl: p.url }
+        );
         if (newKey.trim()) {
           const trimmed = newKey.trim();
           config2.providers[p.key] = trimmed;
@@ -69652,7 +69758,11 @@ async function runCustomSetup(config2) {
         }
       }
     } else {
-      const newKey = await promptHidden(source_default.cyan(`  ${source_default.dim("\u25CB")} ${p.name.padEnd(12)} ${source_default.dim(p.desc)}: `));
+      console.log(source_default.dim(`  ${source_default.dim("\u25CB")} ${p.name.padEnd(12)} ${source_default.dim(p.desc)}  Get key: ${p.url}  [o] open`));
+      const newKey = await promptHidden(
+        source_default.cyan(`    ${p.env}: `),
+        { openHotkeyUrl: p.url }
+      );
       if (newKey.trim()) {
         const trimmed = newKey.trim();
         config2.providers[p.key] = trimmed;
@@ -69686,7 +69796,12 @@ function showComplete(config2, defaultTryCommand, features = []) {
   console.log();
   console.log(source_default.bold("  Next steps:"));
   console.log(source_default.dim("    cd <project>; vibe init   Scaffold AGENTS.md / CLAUDE.md / .env.example (project scope)"));
-  console.log(source_default.dim("    vibe walkthrough scene    5-step authoring guide (storyboard \u2192 MP4)"));
+  const hostDetected = detectedAgentHosts().length > 0;
+  for (const w of listWalkthroughs()) {
+    const cmd = `vibe walkthrough ${w.topic}`.padEnd(26);
+    const tag = hostDetected && w.topic === "scene" ? source_default.cyan(" (recommended)") : "";
+    console.log(source_default.dim(`    ${cmd}${w.summary}${tag}`));
+  }
   console.log(source_default.dim("    vibe doctor               Check system health + available commands"));
   console.log(source_default.dim("    vibe schema --list        Discover every command"));
   console.log(source_default.dim("    vibe setup                Re-run user-scope setup anytime"));
@@ -70805,14 +70920,14 @@ async function runDiagnostics() {
     try {
       const filtersResult = await execSafe("ffmpeg", ["-filters"]);
       const filtersOutput = filtersResult.stdout;
-      const platform = process.platform;
+      const platform2 = process.platform;
       ffmpegFilters = {};
       for (const [filterName, info] of Object.entries(REQUIRED_FFMPEG_FILTERS)) {
         const available = filtersOutput.includes(filterName);
         ffmpegFilters[filterName] = {
           available,
           commands: info.commands,
-          ...!available && info.fix[platform] ? { fix: info.fix[platform] } : {}
+          ...!available && info.fix[platform2] ? { fix: info.fix[platform2] } : {}
         };
       }
     } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.80.0",
+  "version": "0.80.1",
   "description": "VibeFrame CLI - natural language video editing from the terminal",
   "private": false,
   "license": "MIT",
@@ -183,8 +183,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.80.0",
-    "@vibeframe/core": "0.80.0"
+    "@vibeframe/ai-providers": "0.80.1",
+    "@vibeframe/core": "0.80.1"
   },
   "engines": {
     "node": ">=20"