@vibeframe/cli 0.115.4 → 0.115.6

package/CONTEXT.md

@@ -3,7 +3,7 @@
 ## Overview
 
 VibeFrame CLI (`vibe`) generates AI video on the user's own provider keys
-(Seedance, Runway, Veo, Kling), behind dry runs and a hard `--max-cost`
+(Seedance, Runway, Kling, Gemini Omni), behind dry runs and a hard `--max-cost`
 ceiling, and edits the results. Every operation is
 a shell command. The same surface is exposed as MCP tools through
 [`@vibeframe/mcp-server`](https://www.npmjs.com/package/@vibeframe/mcp-server).

package/dist/commands/_shared/init-templates.d.ts

@@ -18,7 +18,7 @@
  * file. Keep this as the canonical source of truth for agent guidance -
  * \`CLAUDE.md\` and \`GEMINI.md\` just import it.
  */
-export declare const AGENTS_MD = "# AGENTS.md\n\nThis project uses [VibeFrame](https://github.com/vericontext/vibeframe) -\na CLI for AI video generation on the user's own provider keys (Seedance,\nRunway, Veo, Kling), behind dry runs and a hard `--max-cost` ceiling.\nThe `vibe` command provides 80+ subcommands for video generation,\nediting, and analysis. Cost tiers below - **always confirm with the user\nbefore running High / Very High tier commands**.\n\n## Agent host coverage\n\nVibeFrame's CLI works with any bash-capable AI coding agent. Six host\nfamilies have first-class auto-detection and scaffolds today:\n\n- **Claude Code** - `CLAUDE.md` (this file's import wrapper) +\n  `AGENTS.md` + `/vibe-*` slash commands.\n- **OpenAI Codex** - reads `AGENTS.md` natively (agents.md spec).\n- **Cursor** - reads `AGENTS.md` plus `.cursor/rules/` for project\n  rules; supports MCP via `.cursor/mcp.json`.\n- **Aider** - reads `AGENTS.md` (binary-only detection by VibeFrame).\n- **Gemini CLI** - primary context file is `GEMINI.md`; also reads\n  `AGENTS.md` if present.\n- **OpenCode** - reads `AGENTS.md` (officially supported per\n  `opencode.ai/docs/rules`); supports MCP via `.opencode/mcp.json`.\n\nRun `vibe doctor` to see which host(s) the CLI detects in your\nenvironment. Anyone running another bash-capable agent (Continue,\nSourcegraph Cody, etc.) still gets this `AGENTS.md` as the universal\nfallback.\n\n## Self-discovery\n\nDon't memorise the command surface - read it from the CLI:\n\n```bash\nvibe --help                    # command groups overview\nvibe schema --list             # full machine-readable catalog (80+)\nvibe schema --list --surface public  # small first-run/product command surface\nvibe schema generate.video     # JSON Schema for any single command\nvibe doctor                    # available providers + system health\nvibe host setup all            # print Codex/Claude/Cursor app integration snippets\nvibe host doctor all --json    # verify project guidance + MCP config\nvibe guide motion              # choose text-overlay vs motion-overlay vs generate motion\nvibe guide scene               # step-by-step authoring guide (scene)\nvibe guide pipeline            # step-by-step authoring guide (pipeline)\n```\n\n## Route by the user's actual request\n\nRouting the user's request correctly is the most important judgement call\nyou'll make. Do not force everything into a scene project.\n\n**ASSET - default for any single-asset request OR ambiguous prompt.**\nIf the user asks for a single image, single video clip, sound effect, music\nbed, or narration file - **OR pastes a visual/audio brief without explicit\nstoryboard / scene / multi-scene language** - treat it as ASSET. Use\n`vibe generate ...` directly. Do **not** edit `DESIGN.md`,\n`STORYBOARD.md`, run `vibe scene ...`, or auto-load the hyperframes\nskill until BUILD intent is explicit. The visual-identity hard-gate\napplies to BUILD only.\n\nExamples:\n- \"make this image\" \u2192 `vibe generate image \"...\" -o assets/name.png`\n- \"use this image to make a video\" \u2192 `vibe generate video \"...\" -i image.png -o renders/name.mp4`\n- \"add a lower-third/title/animated overlay/grain/vignette to this clip\" \u2192 prefer `vibe edit motion-overlay clip.mp4 \"...\" --understand auto -o out.mp4` when the request asks for designed or animated motion graphics.\n- \"please add visuals using OpenAI image gen\" \u2192 `vibe generate image \"...\" -p openai ...`\n- *(verb-less paste)* \"aerial view of a misty mountain peak at sunrise...\" \u2192 `vibe generate image \"<paste>\" -o assets/mountain-peak.png`. **Don't** read it as a brief for DESIGN.md.\n\nIf genuinely uncertain, ask one short question: *\"single asset or\nmulti-scene project?\"* before authoring DESIGN.md or loading the\nhyperframes skill.\n\n**BUILD - create new video from text intent.**\nUse `vibe build` with a STORYBOARD.md + DESIGN.md. The\nskills-driven pipeline (v0.60+) dispatches narration TTS + backdrop\nimage-gen per beat, composes scene HTML via the bundled composition rules\nbundle, then renders to MP4. Idempotent re-runs reuse cached assets.\n\n**REMIX - transform existing video / audio.**\nUse `vibe remix`, `vibe edit`, or `vibe audio`. One-shot,\nbatch-oriented operations on a file the user already has on disk.\n`vibe edit text-overlay` is the free deterministic path for simple static\ntext burn-in. If the user asks for motion design, animated lower-thirds,\ndesigned titles, grain/vignette as part of a graphic treatment, or says\n\"motion graphics\", use `vibe edit motion-overlay ... --understand auto` instead.\n\nDecision rule: if the user asks for one asset, it's ASSET. If the user asks\nfor a multi-scene/storyboard/composed video, it's BUILD. If the user is\nstarting from a media file and wants it transformed, it's REMIX.\n\n## Common workflows\n\n### BUILD (new video from text)\n\n| Task | Command |\n|---|---|\n| One-shot storyboard \u2192 video | `vibe build [project-dir]` |\n| Render an existing scene project | `vibe render [project-dir] -o out.mp4` |\n| Lint scene HTML | `vibe scene lint --json` |\n| Generate a single image | `vibe generate image \"prompt\" -o img.png --quality hd` |\n| Generate a single video | `vibe generate video \"prompt\" -i image.png -o clip.mp4` |\n| Generate narration | `vibe generate narration \"text\" -o voice.mp3` |\n\n### REMIX (transform existing media)\n\n| Task | Command |\n|---|---|\n| Extract highlights from a long video | `vibe remix highlights file.mp4 -d 60` |\n| Long video \u2192 vertical shorts | `vibe remix auto-shorts file.mp4 -n 3 --add-captions` |\n| Add animated word-by-word captions | `vibe remix animated-caption file.mp4 -s karaoke-sweep` |\n| Add designed motion graphics overlay | `vibe edit motion-overlay file.mp4 \"lower-third...\" --understand auto -o out.mp4` |\n| Remove silence | `vibe edit silence-cut in.mp4 -o out.mp4` |\n| Add static captions | `vibe edit caption in.mp4 -o out.mp4` |\n| Translate audio (transcribe \u2192 TTS) | `vibe audio dub file.mp4 -t ko` |\n| Transcribe (Whisper, word-level) | `vibe audio transcribe file.mp4 --granularity word` |\n| Inspect media with Gemini | `vibe inspect media file.mp4 \"summarise\" --json` |\n\n### Compose pipelines (Video as Code)\n\n| Task | Command |\n|---|---|\n| Run a YAML pipeline | `vibe run pipeline.yaml --dry-run` |\n| Resume from last checkpoint | `vibe run pipeline.yaml --resume` |\n\n## Cost tiers\n\n| Tier | Examples | Approx. per call |\n|---|---|---|\n| **Free** | `schema/context/doctor`, `detect *`, `status *`, `plan`, `storyboard validate`, `inspect project/render --cheap`, deterministic edits | $0 |\n| **Low** | `generate narration/sound-effect/music`, `audio transcribe`, `inspect media`, optional AI review | $0.01\u2013$0.10 |\n| **High** | `generate image/motion`, `edit image/reframe/grade/speed-ramp` | $1\u2013$5 |\n| **Very High** | `generate video`, `edit fill-gaps`, `remix highlights/auto-shorts`, `build` with generated assets | $5\u2013$50+ |\n\n## Agent invariants\n\nWhen you run vibe commands programmatically:\n\n1. **Always `--json`** for structured output you can parse without regex\n2. **Always `--dry-run` first** for any High/Very-High tier command - it returns\n   the cost estimate without spending API budget\n3. **Use `vibe schema <command>`** to discover parameters; do not guess flags\n4. **Pass complex options via `--stdin`**:\n   ```bash\n   echo '{\"video\":\"long.mp4\",\"count\":3,\"aspect\":\"9:16\"}' | vibe remix auto-shorts --stdin --json\n   ```\n\n## Provider keys and project scope\n\nPrefer `vibe setup --scope project` for project-local keys. It writes\n`.vibeframe/config.yaml` in the setup directory; when you work from a\nnested scene directory, the `vibe` CLI automatically searches parent\ndirectories and uses the nearest project config. Do not assume the config\nfile must exist in the current subdirectory.\n\nRun `vibe doctor --json` from the directory where you will run commands\nand check `data.scope.project.configPath` / `data.scope.activeScope` before\ndeciding keys are missing. Never print or copy config file contents.\n\nFor generated project assets, use VibeFrame commands such as\n`vibe generate image|video|speech ...` so these project-scope keys are\nused. Do not switch to a host agent's built-in image/audio generation tool\nunless the user explicitly asks for a non-VibeFrame asset.\n\n`.env` is still supported as a gitignored fallback. Copy `.env.example`\nto start if you prefer environment variables.\n\n## App host setup\n\nVibeFrame is CLI-first, not terminal-only. Codex, Claude Code, and Cursor can\ndrive the same project through shell commands, and app hosts can also use\nVibeFrame's MCP server as a typed tool surface.\n\n```bash\nvibe host setup all         # print snippets only\nvibe host setup all --write # write project/app config\nvibe host doctor all --json # verify readiness\n```\n\nDefault setup is snippet-only; use `--write` when you want VibeFrame to merge\nthe generated config. Keep provider keys in `.vibeframe/config.yaml`, user\nconfig, or env files - not in app host config.\n\n## Host agent loop\n\nFor long-running work, use your host's agent loop (Claude Code, Codex, Cursor,\nor another coding-agent host) as the outer loop. VibeFrame should not own a\ncompeting project-level agent loop. It provides `--json` commands, dry runs,\nbudget caps, `build-report.json`, `review-report.json`, `nextActions`,\n`safeToAutoRun`, `requiresConfirmation`, `fixOwner`, deterministic repair,\nand render inspection for the host agent to decide what to do next.\n\nCopy-paste agent prompt (Codex) - a plain prompt, not a built-in command:\n\n```text\nBuild this VibeFrame project into renders/final.mp4. Use --json for every\nvibe command, run --dry-run before paid operations, use --max-cost 5 for builds\nunless the user gives another budget, read build-report.json and\nreview-report.json before deciding the next action, prefer nextActions before\nguessing, run only safeToAutoRun:true actions automatically, and ask before\nrequiresConfirmation:true actions. Treat retryWith as the compatibility\nfallback, fixOwner:\"vibe\" as CLI repair work, and fixOwner:\"host-agent\" as\nSTORYBOARD.md, DESIGN.md, or composition edits.\nStop only when renders/final.mp4 exists, target duration and aspect ratio are\nmet, inspect render --cheap has no errors, any AI review score is >= 90 when AI review is requested, and every\nremaining host-agent issue is fixed, accepted with rationale, or reported as\nblocked.\n```\n\nCopy-paste agent prompt (Claude Code) - a plain prompt, not a built-in command:\n\n```text\nFinish this VibeFrame render using your host's agent loop as the outer\nloop. Use vibe context/schema when unsure, --json everywhere, dry-run before\npaid operations, budget cap via --max-cost 5, nextActions before guessing,\nbuild-report.json/review-report.json as loop state, and safeToAutoRun,\nrequiresConfirmation, and fixOwner to decide between vibe scene repair and\nhost-agent edits. Stop only after final MP4,\ntarget duration/aspect ratio, clean render inspection, any AI review score >= 90 when AI review is requested, and\nno unresolved unacknowledged host-agent issues.\n```\n\n### Composition rules (scene HTML)\n\nComposition rules live in the **Hyperframes skill** - framework rules, motion\nprinciples, type system, and visual-identity hard-gate. **Load that skill\nbefore authoring any scene composition HTML under `compositions/`.** The same\nrules govern `vibe scene lint`, so your authored HTML and the linter stay in\nagreement.\n\nWhere the skill comes from depends on your setup:\n\n- If the `hyperframes` skill is installed globally (e.g. Claude Code), your\n  agent already has it and nothing else is needed.\n- Otherwise install it into this project with `vibe scene install-skill`,\n  which runs upstream's own installer and writes\n  `.agents/skills/hyperframes/`.\n\n`vibe init` never copies the rules in. They come from upstream so they stay\ncurrent, and fetching them is a network call the scaffold does not make on\nyour behalf. `vibe doctor` reports whether your agent can read them.\n\nFor render-stable text, do not apply continuous `scale`, `x`, `y`,\n`filter`, or other transform tweens to `.scene-content` or any ancestor\ncontaining live text/cards. Put ambient zoom/parallax on background or media\nlayers only; text should enter briefly and then hold still at its final CSS\nposition.\n\n### Scene composer (non-agent fallback)\n\nScene HTML is authored by you, the host agent - the CLI makes no LLM call\nduring `vibe build`. When no agent is available to author scenes, pass\n`--composer template` for the deterministic no-model composer\n(concat background + lower-thirds).\n\n## Project conventions\n\n<!-- Edit this section with YOUR project's specifics. Examples below. -->\n\n- Default aspect ratio: `16:9`\n- Default scene duration: `3 seconds` (per beat)\n- Brand voice: <describe>\n- Output naming: `renders/<name>-<timestamp>.mp4`\n";
+export declare const AGENTS_MD = "# AGENTS.md\n\nThis project uses [VibeFrame](https://github.com/vericontext/vibeframe) -\na CLI for AI video generation on the user's own provider keys (Seedance,\nRunway, Kling, Gemini Omni), behind dry runs and a hard `--max-cost` ceiling.\nThe `vibe` command provides 80+ subcommands for video generation,\nediting, and analysis. Cost tiers below - **always confirm with the user\nbefore running High / Very High tier commands**.\n\n## Agent host coverage\n\nVibeFrame's CLI works with any bash-capable AI coding agent. Six host\nfamilies have first-class auto-detection and scaffolds today:\n\n- **Claude Code** - `CLAUDE.md` (this file's import wrapper) +\n  `AGENTS.md` + `/vibe-*` slash commands.\n- **OpenAI Codex** - reads `AGENTS.md` natively (agents.md spec).\n- **Cursor** - reads `AGENTS.md` plus `.cursor/rules/` for project\n  rules; supports MCP via `.cursor/mcp.json`.\n- **Aider** - reads `AGENTS.md` (binary-only detection by VibeFrame).\n- **Gemini CLI** - primary context file is `GEMINI.md`; also reads\n  `AGENTS.md` if present.\n- **OpenCode** - reads `AGENTS.md` (officially supported per\n  `opencode.ai/docs/rules`); supports MCP via `.opencode/mcp.json`.\n\nRun `vibe doctor` to see which host(s) the CLI detects in your\nenvironment. Anyone running another bash-capable agent (Continue,\nSourcegraph Cody, etc.) still gets this `AGENTS.md` as the universal\nfallback.\n\n## Self-discovery\n\nDon't memorise the command surface - read it from the CLI:\n\n```bash\nvibe --help                    # command groups overview\nvibe schema --list             # full machine-readable catalog (80+)\nvibe schema --list --surface public  # small first-run/product command surface\nvibe schema generate.video     # JSON Schema for any single command\nvibe doctor                    # available providers + system health\nvibe host setup all            # print Codex/Claude/Cursor app integration snippets\nvibe host doctor all --json    # verify project guidance + MCP config\nvibe guide motion              # choose text-overlay vs motion-overlay vs generate motion\nvibe guide scene               # step-by-step authoring guide (scene)\nvibe guide pipeline            # step-by-step authoring guide (pipeline)\n```\n\n## Route by the user's actual request\n\nRouting the user's request correctly is the most important judgement call\nyou'll make. Do not force everything into a scene project.\n\n**ASSET - default for any single-asset request OR ambiguous prompt.**\nIf the user asks for a single image, single video clip, sound effect, music\nbed, or narration file - **OR pastes a visual/audio brief without explicit\nstoryboard / scene / multi-scene language** - treat it as ASSET. Use\n`vibe generate ...` directly. Do **not** edit `DESIGN.md`,\n`STORYBOARD.md`, run `vibe scene ...`, or auto-load the hyperframes\nskill until BUILD intent is explicit. The visual-identity hard-gate\napplies to BUILD only.\n\nExamples:\n- \"make this image\" \u2192 `vibe generate image \"...\" -o assets/name.png`\n- \"use this image to make a video\" \u2192 `vibe generate video \"...\" -i image.png -o renders/name.mp4`\n- \"add a lower-third/title/animated overlay/grain/vignette to this clip\" \u2192 prefer `vibe edit motion-overlay clip.mp4 \"...\" --understand auto -o out.mp4` when the request asks for designed or animated motion graphics.\n- \"please add visuals using OpenAI image gen\" \u2192 `vibe generate image \"...\" -p openai ...`\n- *(verb-less paste)* \"aerial view of a misty mountain peak at sunrise...\" \u2192 `vibe generate image \"<paste>\" -o assets/mountain-peak.png`. **Don't** read it as a brief for DESIGN.md.\n\nIf genuinely uncertain, ask one short question: *\"single asset or\nmulti-scene project?\"* before authoring DESIGN.md or loading the\nhyperframes skill.\n\n**BUILD - create new video from text intent.**\nUse `vibe build` with a STORYBOARD.md + DESIGN.md. The\nskills-driven pipeline (v0.60+) dispatches narration TTS + backdrop\nimage-gen per beat, composes scene HTML via the bundled composition rules\nbundle, then renders to MP4. Idempotent re-runs reuse cached assets.\n\n**REMIX - transform existing video / audio.**\nUse `vibe remix`, `vibe edit`, or `vibe audio`. One-shot,\nbatch-oriented operations on a file the user already has on disk.\n`vibe edit text-overlay` is the free deterministic path for simple static\ntext burn-in. If the user asks for motion design, animated lower-thirds,\ndesigned titles, grain/vignette as part of a graphic treatment, or says\n\"motion graphics\", use `vibe edit motion-overlay ... --understand auto` instead.\n\nDecision rule: if the user asks for one asset, it's ASSET. If the user asks\nfor a multi-scene/storyboard/composed video, it's BUILD. If the user is\nstarting from a media file and wants it transformed, it's REMIX.\n\n## Common workflows\n\n### BUILD (new video from text)\n\n| Task | Command |\n|---|---|\n| One-shot storyboard \u2192 video | `vibe build [project-dir]` |\n| Render an existing scene project | `vibe render [project-dir] -o out.mp4` |\n| Lint scene HTML | `vibe scene lint --json` |\n| Generate a single image | `vibe generate image \"prompt\" -o img.png --quality hd` |\n| Generate a single video | `vibe generate video \"prompt\" -i image.png -o clip.mp4` |\n| Generate narration | `vibe generate narration \"text\" -o voice.mp3` |\n\n### REMIX (transform existing media)\n\n| Task | Command |\n|---|---|\n| Extract highlights from a long video | `vibe remix highlights file.mp4 -d 60` |\n| Long video \u2192 vertical shorts | `vibe remix auto-shorts file.mp4 -n 3 --add-captions` |\n| Add animated word-by-word captions | `vibe remix animated-caption file.mp4 -s karaoke-sweep` |\n| Add designed motion graphics overlay | `vibe edit motion-overlay file.mp4 \"lower-third...\" --understand auto -o out.mp4` |\n| Remove silence | `vibe edit silence-cut in.mp4 -o out.mp4` |\n| Add static captions | `vibe edit caption in.mp4 -o out.mp4` |\n| Translate audio (transcribe \u2192 TTS) | `vibe audio dub file.mp4 -t ko` |\n| Transcribe (Whisper, word-level) | `vibe audio transcribe file.mp4 --granularity word` |\n| Inspect media with Gemini | `vibe inspect media file.mp4 \"summarise\" --json` |\n\n### Compose pipelines (Video as Code)\n\n| Task | Command |\n|---|---|\n| Run a YAML pipeline | `vibe run pipeline.yaml --dry-run` |\n| Resume from last checkpoint | `vibe run pipeline.yaml --resume` |\n\n## Cost tiers\n\n| Tier | Examples | Approx. per call |\n|---|---|---|\n| **Free** | `schema/context/doctor`, `detect *`, `status *`, `plan`, `storyboard validate`, `inspect project/render --cheap`, deterministic edits | $0 |\n| **Low** | `generate narration/sound-effect/music`, `audio transcribe`, `inspect media`, optional AI review | $0.01\u2013$0.10 |\n| **High** | `generate image/motion`, `edit image/reframe/grade/speed-ramp` | $1\u2013$5 |\n| **Very High** | `generate video`, `edit fill-gaps`, `remix highlights/auto-shorts`, `build` with generated assets | $5\u2013$50+ |\n\n## Agent invariants\n\nWhen you run vibe commands programmatically:\n\n1. **Always `--json`** for structured output you can parse without regex\n2. **Always `--dry-run` first** for any High/Very-High tier command - it returns\n   the cost estimate without spending API budget\n3. **Use `vibe schema <command>`** to discover parameters; do not guess flags\n4. **Pass complex options via `--stdin`**:\n   ```bash\n   echo '{\"video\":\"long.mp4\",\"count\":3,\"aspect\":\"9:16\"}' | vibe remix auto-shorts --stdin --json\n   ```\n\n## Provider keys and project scope\n\nPrefer `vibe setup --scope project` for project-local keys. It writes\n`.vibeframe/config.yaml` in the setup directory; when you work from a\nnested scene directory, the `vibe` CLI automatically searches parent\ndirectories and uses the nearest project config. Do not assume the config\nfile must exist in the current subdirectory.\n\nRun `vibe doctor --json` from the directory where you will run commands\nand check `data.scope.project.configPath` / `data.scope.activeScope` before\ndeciding keys are missing. Never print or copy config file contents.\n\nFor generated project assets, use VibeFrame commands such as\n`vibe generate image|video|speech ...` so these project-scope keys are\nused. Do not switch to a host agent's built-in image/audio generation tool\nunless the user explicitly asks for a non-VibeFrame asset.\n\n`.env` is still supported as a gitignored fallback. Copy `.env.example`\nto start if you prefer environment variables.\n\n## App host setup\n\nVibeFrame is CLI-first, not terminal-only. Codex, Claude Code, and Cursor can\ndrive the same project through shell commands, and app hosts can also use\nVibeFrame's MCP server as a typed tool surface.\n\n```bash\nvibe host setup all         # print snippets only\nvibe host setup all --write # write project/app config\nvibe host doctor all --json # verify readiness\n```\n\nDefault setup is snippet-only; use `--write` when you want VibeFrame to merge\nthe generated config. Keep provider keys in `.vibeframe/config.yaml`, user\nconfig, or env files - not in app host config.\n\n## Host agent loop\n\nFor long-running work, use your host's agent loop (Claude Code, Codex, Cursor,\nor another coding-agent host) as the outer loop. VibeFrame should not own a\ncompeting project-level agent loop. It provides `--json` commands, dry runs,\nbudget caps, `build-report.json`, `review-report.json`, `nextActions`,\n`safeToAutoRun`, `requiresConfirmation`, `fixOwner`, deterministic repair,\nand render inspection for the host agent to decide what to do next.\n\nCopy-paste agent prompt (Codex) - a plain prompt, not a built-in command:\n\n```text\nBuild this VibeFrame project into renders/final.mp4. Use --json for every\nvibe command, run --dry-run before paid operations, use --max-cost 5 for builds\nunless the user gives another budget, read build-report.json and\nreview-report.json before deciding the next action, prefer nextActions before\nguessing, run only safeToAutoRun:true actions automatically, and ask before\nrequiresConfirmation:true actions. Treat retryWith as the compatibility\nfallback, fixOwner:\"vibe\" as CLI repair work, and fixOwner:\"host-agent\" as\nSTORYBOARD.md, DESIGN.md, or composition edits.\nStop only when renders/final.mp4 exists, target duration and aspect ratio are\nmet, inspect render --cheap has no errors, any AI review score is >= 90 when AI review is requested, and every\nremaining host-agent issue is fixed, accepted with rationale, or reported as\nblocked.\n```\n\nCopy-paste agent prompt (Claude Code) - a plain prompt, not a built-in command:\n\n```text\nFinish this VibeFrame render using your host's agent loop as the outer\nloop. Use vibe context/schema when unsure, --json everywhere, dry-run before\npaid operations, budget cap via --max-cost 5, nextActions before guessing,\nbuild-report.json/review-report.json as loop state, and safeToAutoRun,\nrequiresConfirmation, and fixOwner to decide between vibe scene repair and\nhost-agent edits. Stop only after final MP4,\ntarget duration/aspect ratio, clean render inspection, any AI review score >= 90 when AI review is requested, and\nno unresolved unacknowledged host-agent issues.\n```\n\n### Composition rules (scene HTML)\n\nComposition rules live in the **Hyperframes skill** - framework rules, motion\nprinciples, type system, and visual-identity hard-gate. **Load that skill\nbefore authoring any scene composition HTML under `compositions/`.** The same\nrules govern `vibe scene lint`, so your authored HTML and the linter stay in\nagreement.\n\nWhere the skill comes from depends on your setup:\n\n- If the `hyperframes` skill is installed globally (e.g. Claude Code), your\n  agent already has it and nothing else is needed.\n- Otherwise install it into this project with `vibe scene install-skill`,\n  which runs upstream's own installer and writes\n  `.agents/skills/hyperframes/`.\n\n`vibe init` never copies the rules in. They come from upstream so they stay\ncurrent, and fetching them is a network call the scaffold does not make on\nyour behalf. `vibe doctor` reports whether your agent can read them.\n\nFor render-stable text, do not apply continuous `scale`, `x`, `y`,\n`filter`, or other transform tweens to `.scene-content` or any ancestor\ncontaining live text/cards. Put ambient zoom/parallax on background or media\nlayers only; text should enter briefly and then hold still at its final CSS\nposition.\n\n### Scene composer (non-agent fallback)\n\nScene HTML is authored by you, the host agent - the CLI makes no LLM call\nduring `vibe build`. When no agent is available to author scenes, pass\n`--composer template` for the deterministic no-model composer\n(concat background + lower-thirds).\n\n## Project conventions\n\n<!-- Edit this section with YOUR project's specifics. Examples below. -->\n\n- Default aspect ratio: `16:9`\n- Default scene duration: `3 seconds` (per beat)\n- Brand voice: <describe>\n- Output naming: `renders/<name>-<timestamp>.mp4`\n";
 /**
  * Claude Code project file. Imports AGENTS.md so guidance stays
  * single-sourced; adds Claude-specific overrides (slash commands, etc.).

package/dist/commands/_shared/status-jobs.d.ts

@@ -1,3 +1,4 @@
+import { type VideoJob } from "@vibeframe/ai-providers";
 import type { BuildAssetKind } from "./build-cache.js";
 import type { ReviewAction } from "./review-report.js";
 export type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "unknown";
@@ -26,7 +27,10 @@ export interface JobRecord {
     command: string;
     provider: string;
     providerTaskId: string;
+    /** Kling task type; superseded by `providerJob` and kept for older records. */
     providerTaskType?: "text2video" | "image2video";
+    /** The provider's job handle, so a refresh polls exactly the job that was submitted. */
+    providerJob?: VideoJob;
     progress?: number;
     resultUrl?: string;
     beatId?: string;
@@ -60,6 +64,7 @@ export interface CreateJobRecordOptions {
     provider: string;
     providerTaskId: string;
     providerTaskType?: "text2video" | "image2video";
+    providerJob?: VideoJob;
     projectDir?: string;
     workingDirectory?: string;
     command: string;

package/dist/commands/_shared/video-jobs.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The CLI side of the video job contract: open a provider by name with the
+ * user's key, and turn local files into the image form it takes. Video
+ * executors, job records, and builds go through here instead of branching
+ * on provider names.
+ */
+import { type VideoGenerator, type VideoJob } from "@vibeframe/ai-providers";
+/** Env var holding each video provider's key. */
+export declare const VIDEO_PROVIDER_ENV: Readonly<Record<string, string>>;
+/** `fal` is the old name for `seedance`. */
+export declare function canonicalVideoProvider(provider: string): string;
+/** A video generator for `provider`, with the given key or the configured one. */
+export declare function openVideoGenerator(provider: string, apiKey?: string): Promise<VideoGenerator>;
+/**
+ * A job handle for a bare task ID (a user typed it, or an old job record
+ * predates stored handles). Providers that need more than the ID recover
+ * it themselves: Kling tries both task types, Seedance uses its model's app.
+ */
+export declare function jobFromTaskId(provider: string, taskId: string, opts?: {
+    model?: string;
+    taskType?: string;
+}): VideoJob;
+export declare function mimeTypeForPath(path: string, fallback: string): string;
+/** A local path, URL, or data URI as a URL or data URI (local files are inlined). */
+export declare function fileToUrlOrDataUri(input: string, fallbackMimeType: string): Promise<string>;
+/**
+ * An input image in the form `generator` takes: uploaded to the configured
+ * upload host for URL-only providers, inlined as a data URI otherwise.
+ *
+ * Remote URLs are never fetched here: an inline-only provider gets a usage
+ * error instead, so a tool call cannot make the CLI read an internal URL
+ * and forward its contents to a provider.
+ */
+export declare function videoImageInput(generator: VideoGenerator, input: string): Promise<string>;

package/dist/commands/ai-video.d.ts

@@ -1,21 +1,21 @@
 /**
  * @module ai-video
- * @description Library functions for video generation, status, cancel, and
- * extension. Powers the manifest tools `generate_video`,
- * `generate_video_status`, `generate_video_cancel`, `generate_video_extend`
- * (the user reaches these via `vibe generate video[-...]`).
- *
- * The legacy `vibe ai video / video-status / video-cancel / kling / kling-status /
- * video-extend` Commander registrations were removed alongside the dead
- * `commands/ai.ts` orchestrator (the `vibe ai *` namespace was never
- * `addCommand`'d to `program`).
+ * @description Video generation, status, cancel, and extension on the video
+ * job contract. Powers the manifest tools `generate_video`,
+ * `generate_video_cancel`, `generate_video_extend`, and job refreshes in
+ * `vibe status`; every provider goes through `VideoGenerator`, so nothing
+ * here branches on provider names.
  *
  * @see MODELS.md for AI model configuration
  */
+import { type ProviderErrorKind, type VideoJob, type VideoJobState } from "@vibeframe/ai-providers";
 export interface VideoGenerateOptions {
     prompt: string;
+    /** Default: the configured or first available video provider. */
     provider?: "grok" | "runway" | "kling" | "veo" | "seedance" | "fal" | "omni";
     image?: string;
+    /** Ending frame for providers that interpolate between two frames. */
+    endImage?: string;
     refImages?: string[];
     refVideos?: string[];
     refAudio?: string[];
@@ -34,21 +34,37 @@ export interface VideoGenerateOptions {
     output?: string;
     wait?: boolean;
     apiKey?: string;
+    /**
+     * Called as soon as the provider accepts the job, before waiting, so the
+     * caller can record it: a crash or timeout mid-wait then leaves a job that
+     * can still be polled and downloaded.
+     */
+    onSubmitted?: (job: VideoJob) => void | Promise<void>;
+    /** Called after every poll while waiting. */
+    onProgress?: (state: VideoJobState) => void;
+    /** Veo only: `allow_all` or `allow_adult`. */
+    personGeneration?: string;
 }
 export interface VideoGenerateResult {
     success: boolean;
     taskId?: string;
+    /** The provider job handle; store it to poll, cancel, or extend later. */
+    job?: VideoJob;
     status?: string;
     videoUrl?: string;
     duration?: number;
     outputPath?: string;
     provider?: string;
     error?: string;
+    errorKind?: ProviderErrorKind;
 }
 export declare function executeVideoGenerate(options: VideoGenerateOptions): Promise<VideoGenerateResult>;
 export interface VideoStatusOptions {
     taskId: string;
-    provider?: "grok" | "runway" | "kling" | "veo";
+    provider?: string;
+    /** The stored job handle; preferred over `taskId` + `taskType`. */
+    job?: VideoJob;
+    /** Kling task type, for a bare task ID. */
     taskType?: "text2video" | "image2video";
     wait?: boolean;
     output?: string;
@@ -63,20 +79,28 @@ export interface VideoStatusResult {
     duration?: number;
     outputPath?: string;
     error?: string;
+    errorKind?: ProviderErrorKind;
 }
 export declare function executeVideoStatus(options: VideoStatusOptions): Promise<VideoStatusResult>;
 export interface VideoCancelOptions {
     taskId: string;
+    /** Default: runway. */
+    provider?: string;
+    job?: VideoJob;
     apiKey?: string;
 }
 export interface VideoCancelResult {
     success: boolean;
     error?: string;
+    errorKind?: ProviderErrorKind;
 }
 export declare function executeVideoCancel(options: VideoCancelOptions): Promise<VideoCancelResult>;
 export interface VideoExtendOptions {
+    /** The task ID of the video to extend (Veo: its operation name). */
     videoId: string;
-    provider?: "kling" | "veo";
+    /** Default: kling. */
+    provider?: string;
+    job?: VideoJob;
     prompt?: string;
     duration?: number;
     negative?: string;
@@ -88,10 +112,12 @@ export interface VideoExtendOptions {
 export interface VideoExtendResult {
     success: boolean;
     taskId?: string;
+    job?: VideoJob;
     status?: string;
     videoUrl?: string;
     duration?: number;
     outputPath?: string;
     error?: string;
+    errorKind?: ProviderErrorKind;
 }
 export declare function executeVideoExtend(options: VideoExtendOptions): Promise<VideoExtendResult>;

package/dist/commands/ai-video.network.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/generate/video-cancel.d.ts

@@ -1,8 +1,7 @@
 /**
  * @module generate/video-cancel
- * @description `vibe generate video-cancel` (hidden) — cancel in-flight Grok
- * or Runway video generation. Split out of `generate.ts` in v0.69 (Plan G
- * Phase 2).
+ * @description `vibe generate video-cancel` (hidden) — cancel an in-flight
+ * video job on a provider with a cancel API (Runway, Seedance, Gemini Omni).
  */
 import type { Command } from "commander";
 export declare function registerVideoCancelCommand(parent: Command): void;

package/dist/commands/generate/video-extend.d.ts

@@ -1,8 +1,8 @@
 /**
  * @module generate/video-extend
- * @description `vibe generate video-extend` (hidden) — extend video duration
- * via Kling or Veo (Gemini). Split out of `generate.ts` in v0.69 (Plan G
- * Phase 2).
+ * @description `vibe generate video-extend` (hidden) — extend a generated
+ * video from its last frame, on any provider that can (Kling, Grok classic,
+ * Gemini Omni, and Veo until 2026-10-22).
  */
 import type { Command } from "commander";
 export declare function registerVideoExtendCommand(parent: Command): void;

package/dist/commands/generate/video.d.ts

@@ -1,12 +1,22 @@
 /**
  * @module generate/video
  * @description `vibe generate video` (alias `vid`) — multi-provider video
- * generation. fal.ai (Seedance 2.0), Grok, Veo (Gemini), Kling, Runway,
- * plus Gemini Omni 1.1 Flash (`-p omni`).
- * Split out of `generate.ts` in v0.69 (Plan G Phase 2).
+ * generation (Seedance via fal.ai, Grok, Kling, Runway, Gemini Omni, and Veo
+ * until 2026-10-22). Validation, provider choice, and the dry run live here;
+ * generation itself is `executeVideoGenerate`, the same executor the MCP
+ * tool and builds use.
  */
 import type { Command } from "commander";
 export declare function registerVideoCommand(parent: Command): void;
+/**
+ * Cost figure for a REAL (non-dry-run) generation envelope.
+ *
+ * Seedance has a token-accurate estimator; every other provider reports the
+ * command's tier upper bound with a warning naming it an estimate. Without
+ * this the success envelope defaulted to costUsd 0, which an agent budget
+ * loop reads as "free" - the hybrid-brew dogfood run billed Runway twice
+ * while reporting $0.
+ */
 export declare function realRunCost(provider: string, options: {
     duration?: string;
     resolution?: string;

package/dist/commands/generate.d.ts

@@ -5,7 +5,7 @@
  *
  * Commands:
  *   generate image          - Generate image (Gemini, OpenAI, Grok, Runway)
- *   generate video          - Generate video (Seedance, Grok, Kling, Runway, Veo)
+ *   generate video          - Generate video (Seedance, Grok, Kling, Runway, Omni, Veo)
  *   generate sound-effect   - Sound effects (ElevenLabs)
  *   generate music          - Music generation (ElevenLabs default, Replicate MusicGen)
  *   generate motion         - Standalone motion assets (Claude/Gemini + Remotion)

package/dist/commands/output.d.ts

@@ -22,6 +22,8 @@ export interface StructuredError {
     retryWith?: string[];
     recoverable?: boolean;
     retryable: boolean;
+    /** The provider error kind (`auth`, `quota`, `likeness`, ...) when a provider call failed. */
+    errorKind?: string;
     /**
      * Structured context carried alongside the failure, so a refusal can hand
      * back the evidence it refused on instead of forcing a second call. Used by
@@ -32,6 +34,11 @@ export interface StructuredError {
 export declare function usageError(msg: string, suggestion?: string): StructuredError;
 export declare function authError(envVar: string, provider: string): StructuredError;
 export declare function apiError(msg: string, retryable?: boolean): StructuredError;
+/**
+ * The structured error for a failed provider call, chosen by its error kind
+ * (`ProviderError.kind`) instead of by matching provider wording.
+ */
+export declare function providerFailure(message: string, kind?: string): StructuredError;
 export declare function notFoundError(path: string): StructuredError;
 export declare function networkError(msg: string): StructuredError;
 export declare function generalError(msg: string, suggestion?: string): StructuredError;
@@ -75,6 +82,11 @@ export interface SuccessEnvelopeOptions {
     warnings?: string[];
     /** Pass-through of `--dry-run` flag — surfaces as a top-level `dryRun: true` in the envelope. */
     dryRun?: boolean;
+    /**
+     * The caller already printed its own human-readable output (a build plan,
+     * a render summary), so human mode adds nothing for this dry run.
+     */
+    humanRendered?: boolean;
 }
 /** Look up the upper-bound cost estimate for a command (used by dry-run). */
 /**
@@ -87,12 +99,15 @@ export declare function lookupCostEstimateUpperBound(command: string): number;
  * Emit a canonical success envelope (#33 — 2c). JSON mode prints the
  * envelope; quiet mode prints a single primary value extracted from
  * `data.outputPath ?? data.output ?? data.path ?? data.url ?? data.id`;
- * human mode prints nothing — the caller renders human output itself.
+ * human mode prints a summary for dry runs (unless the caller rendered its
+ * own) and otherwise nothing — the caller renders human output itself.
  *
  * Canary scope: `generate image` only in 2c-canary. 2c-sweep migrates
  * the rest. Old `outputResult()` remains for the sweep transition.
  */
 export declare function outputSuccess(opts: SuccessEnvelopeOptions): void;
+/** Print warnings to stderr in human mode; JSON envelopes carry them instead. */
+export declare function printWarnings(warnings: readonly string[]): void;
 /** Output result - JSON mode outputs JSON, quiet mode outputs primary value only */
 export declare function outputResult(result: Record<string, unknown>): void;
 /** Wrap console output - suppressed in JSON/quiet mode */