@vibeframe/cli 0.70.0 → 0.71.0

package/dist/index.js

@@ -29108,6 +29108,26 @@ function detectAgentHosts(env2 = process.env) {
       detected: false,
       signals: [],
       projectFiles: ["AGENTS.md", ".aider.conf.yml"]
+    },
+    {
+      id: "gemini-cli",
+      label: "Gemini CLI",
+      detected: false,
+      signals: [],
+      // Per https://geminicli.com/docs/cli/gemini-md/ Gemini CLI's primary
+      // context file is GEMINI.md; AGENTS.md is the cross-tool fallback
+      // VibeFrame writes by default. Both are honoured.
+      projectFiles: ["GEMINI.md", "AGENTS.md", ".gemini/"]
+    },
+    {
+      id: "opencode",
+      label: "OpenCode",
+      detected: false,
+      signals: [],
+      // sst/opencode officially supports the agents.md spec — AGENTS.md at
+      // project root is the standard place. Local config also under
+      // `.opencode/` per https://opencode.ai/docs/config/.
+      projectFiles: ["AGENTS.md", ".opencode/"]
     }
   ].map((host) => {
     const signals2 = [];
@@ -29165,14 +29185,21 @@ var init_agent_host_detect = __esm({
       "claude-code": "claude",
       codex: "codex",
       cursor: "cursor",
-      aider: "aider"
+      aider: "aider",
+      "gemini-cli": "gemini",
+      opencode: "opencode"
     };
     HOST_CONFIG_DIRS = {
       "claude-code": ".claude",
       codex: ".codex",
       cursor: ".cursor",
       // some installs; macOS app stores prefs elsewhere
-      aider: null
+      aider: null,
+      "gemini-cli": ".gemini",
+      // sst/opencode uses XDG-style `~/.config/opencode/` per
+      // https://opencode.ai/docs/config/. The path is relative to $HOME so
+      // the join in detectAgentHosts() resolves correctly.
+      opencode: ".config/opencode"
     };
   }
 });
@@ -61356,6 +61383,363 @@ 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 scene 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 scene build [project-dir]\` | STORYBOARD.md has YAML frontmatter + per-beat cues |
+| **High-craft (manual)** | \`DESIGN.md\` + Hyperframes skill 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 scene build\` whenever the user has a STORYBOARD with
+narration / backdrop intent.
+
+## High-craft path
+
+1. \`vibe scene 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 the Hyperframes skill** 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 scene render\`
+   to MP4.
+
+## Quick-draft path
+
+\`\`\`bash
+vibe scene init my-promo -r 16:9 -d 30
+vibe scene add intro --style announcement \\
+    --headline "Ship videos, not clicks"
+vibe scene lint
+vibe scene render
+\`\`\`
+
+\`vibe scene 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
+vibe scene init <dir> [-r 16:9|9:16|1:1|4:5] [-d <sec>] [--visual-style "<name>"]
+vibe scene styles [<name>]                   # list / show vendored visual identities
+vibe scene install-skill [<dir>] [--host all]  # retroactive Hyperframes-skill 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]
+vibe scene render [<root>] [--fps 30] [--quality standard] [--format mp4]
+vibe scene build [<dir>] [--mode agent|batch|auto]   # H3 dispatch
+\`\`\`
+
+## 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 scene init my-promo --visual-style "Swiss Pulse" -d 12
+# (edit STORYBOARD.md with per-beat YAML cues \u2014 narration, backdrop, duration)
+vibe scene build my-promo
+\`\`\`
+
+\`vibe scene 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 scene 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 scene build\` |
+| Hand-tweak a single scene's animation | edit \`compositions/<file>.html\` directly |
+| Render the project | \`vibe scene render\` *or* \`npx hyperframes render\` (equivalent) |
+| 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 examples** \u2014 \`examples/demo-pipeline.yaml\` (FFmpeg-only,
+   no keys), \`examples/promo-video.yaml\` (AI providers).
+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 scene init <dir> --visual-style "<style name>"` to scaffold the project + install the Hyperframes skill (Plan H).',
+          "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 scene 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 scene render` to produce the MP4."
+        ],
+        relatedCommands: [
+          "vibe scene init",
+          "vibe scene styles",
+          "vibe scene install-skill",
+          "vibe scene compose-prompts",
+          "vibe scene build",
+          "vibe scene lint",
+          "vibe scene render",
+          "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({
+  "src/tools/manifest/walkthrough.ts"() {
+    "use strict";
+    init_zod();
+    init_define_tool();
+    init_walkthroughs();
+    walkthroughSchema = external_exports.object({
+      topic: external_exports.enum(WALKTHROUGH_TOPICS).optional().describe(
+        "Walkthrough topic to load. Omit to list every available walkthrough \u2014 useful for discovery on first contact."
+      )
+    });
+    walkthroughTool = defineTool({
+      name: "walkthrough",
+      category: "agent",
+      cost: "free",
+      description: "Load the step-by-step authoring guide for a vibe workflow (BUILD scene authoring, YAML pipeline authoring). Universal CLI-equivalent of Claude Code's /vibe-* slash commands \u2014 any host agent that calls this tool gets the same content the slash menu delivers in Claude Code, with no Claude Code dependency. Without a topic, returns the catalog of walkthroughs for discovery.",
+      schema: walkthroughSchema,
+      async execute(args) {
+        if (!args.topic) {
+          const topics = listWalkthroughs();
+          return {
+            success: true,
+            data: { action: "list", topics },
+            humanLines: [
+              `Available walkthroughs: ${topics.map((t) => t.topic).join(", ")}.`,
+              `Call again with topic to load full content.`
+            ]
+          };
+        }
+        const result = loadWalkthrough(args.topic);
+        return {
+          success: true,
+          data: { action: "show", ...result },
+          humanLines: [
+            `Loaded walkthrough: ${result.title}.`,
+            `${result.steps.length} steps, ${result.relatedCommands.length} related commands, ${result.content.length} chars of guide content.`
+          ]
+        };
+      }
+    });
+    walkthroughTools = [walkthroughTool];
+  }
+});
+
 // src/tools/manifest/index.ts
 var manifest_exports = {};
 __export(manifest_exports, {
@@ -61370,7 +61754,8 @@ __export(manifest_exports, {
   pipelineTools: () => pipelineTools,
   projectTools: () => projectTools,
   sceneTools: () => sceneTools,
-  timelineTools: () => timelineTools
+  timelineTools: () => timelineTools,
+  walkthroughTools: () => walkthroughTools
 });
 var manifest;
 var init_manifest = __esm({
@@ -61387,6 +61772,7 @@ var init_manifest = __esm({
     init_project2();
     init_export2();
     init_agent_only();
+    init_walkthrough();
     manifest = [
       ...sceneTools,
       ...audioTools,
@@ -61398,7 +61784,8 @@ var init_manifest = __esm({
       ...timelineTools,
       ...projectTools,
       ...exportTools,
-      ...agentOnlyTools
+      ...agentOnlyTools,
+      ...walkthroughTools
     ];
   }
 });
@@ -61602,7 +61989,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.70.0",
+  version: "0.71.0",
   description: "VibeFrame CLI - natural language video editing from the terminal",
   private: false,
   license: "MIT",
@@ -68651,7 +69038,7 @@ defaults:
 
 // src/commands/init.ts
 init_output();
-var VALID_AGENTS = ["claude-code", "codex", "cursor", "aider", "all", "auto"];
+var VALID_AGENTS = ["claude-code", "codex", "cursor", "aider", "gemini-cli", "opencode", "all", "auto"];
 var initCommand = new Command("init").description("Scaffold project-scope agent files (AGENTS.md / CLAUDE.md / .env.example / .gitignore)").argument("[project-dir]", "Project directory (defaults to cwd)", ".").option("--agent <id>", `Agent target: ${VALID_AGENTS.join(" | ")}`, "auto").option("--force", "Overwrite existing files instead of skipping").option("--dry-run", "Print the file list without writing anything").action(async (projectDirArg, options) => {
   const agent = options.agent;
   if (!VALID_AGENTS.includes(agent)) {
@@ -68744,7 +69131,7 @@ var initCommand = new Command("init").description("Scaffold project-scope agent
 });
 function resolveTargets(agent) {
   if (agent === "all") {
-    return ["claude-code", "codex", "cursor", "aider"];
+    return ["claude-code", "codex", "cursor", "aider", "gemini-cli", "opencode"];
   }
   if (agent === "auto") {
     const detected = detectedAgentHosts().map((h) => h.id);
@@ -70301,6 +70688,74 @@ function getEnvVar(provider) {
   return envVars[provider] || "API_KEY";
 }
 
+// src/commands/walkthrough.ts
+init_esm();
+init_source();
+init_walkthroughs();
+init_output();
+var walkthroughCommand = new Command("walkthrough").description("Step-by-step authoring guide for a vibe workflow (universal /vibe-* slash-command equivalent)").argument("[topic]", `Walkthrough topic: ${WALKTHROUGH_TOPICS.join(" | ")}. Omit to list all.`).option("--list", "List available walkthroughs and exit").action(async (topicArg, options) => {
+  if (!topicArg || options.list) {
+    const topics = listWalkthroughs();
+    if (isJsonMode()) {
+      outputResult({
+        command: "walkthrough",
+        action: "list",
+        topics
+      });
+      return;
+    }
+    console.log();
+    console.log(source_default.bold.cyan("Available walkthroughs"));
+    console.log(source_default.dim("\u2500".repeat(60)));
+    for (const t of topics) {
+      console.log(`  ${source_default.bold(t.topic.padEnd(10))} ${source_default.dim(t.summary)}`);
+    }
+    console.log();
+    console.log(source_default.dim("Run `vibe walkthrough <topic>` for the full guide."));
+    console.log(source_default.dim("Add `--json` to get structured output for an agent host."));
+    console.log();
+    return;
+  }
+  if (!isWalkthroughTopic(topicArg)) {
+    exitWithError(usageError(
+      `Unknown walkthrough topic: ${topicArg}`,
+      `Valid topics: ${WALKTHROUGH_TOPICS.join(", ")}`
+    ));
+  }
+  const topic = topicArg;
+  const result = loadWalkthrough(topic);
+  if (isJsonMode()) {
+    outputResult({
+      command: "walkthrough",
+      action: "show",
+      ...result
+    });
+    return;
+  }
+  console.log();
+  console.log(source_default.bold.cyan(result.title));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  console.log(source_default.dim(result.summary));
+  console.log();
+  console.log(source_default.bold("Quick steps"));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  for (let i = 0; i < result.steps.length; i++) {
+    console.log(`  ${source_default.cyan(`${i + 1}.`)} ${result.steps[i]}`);
+  }
+  console.log();
+  console.log(source_default.bold("Related commands"));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  for (const cmd of result.relatedCommands) {
+    console.log(`  ${source_default.cyan(cmd)}`);
+  }
+  console.log();
+  console.log(source_default.bold("Full guide"));
+  console.log(source_default.dim("\u2500".repeat(60)));
+  console.log();
+  console.log(result.content);
+  console.log();
+});
+
 // src/index.ts
 init_api_key();
 
@@ -70501,6 +70956,7 @@ program2.addCommand(detectCommand);
 program2.addCommand(batchCommand);
 program2.addCommand(schemaCommand);
 program2.addCommand(contextCommand);
+program2.addCommand(walkthroughCommand);
 program2.addCommand(mediaCommand, { hidden: true });
 function propagateErrorHandling(cmd) {
   for (const sub of cmd.commands) {

package/package.json

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