@vibeframe/cli 0.113.28 → 0.113.30

package/CONTEXT.md

@@ -2,7 +2,9 @@
 
 ## Overview
 
-VibeFrame CLI (`vibe`) is a CLI-first video toolkit. Every operation is
+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`
+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).
 For long-running video work, your host's agent loop (Claude Code, Codex,
@@ -12,7 +14,7 @@ VibeFrame owns the video-specific command surface, JSON reports, cost gates,
 deterministic repair, render inspection, and `retryWith` recovery hints.
 
 For the full reference (every flag, default, enum), read
-[`docs/cli-reference.md`](../../docs/cli-reference.md) — auto-generated
+[`docs/cli-reference.md`](../../docs/cli-reference.md) - auto-generated
 from `vibe schema --list`. This file is the _agent quickstart_: rules,
 conventions, and discovery hooks.
 
@@ -27,7 +29,7 @@ host agent loop -> vibe context/schema -> plan dry-run -> build with budget
 -> repair/edit using nextActions/fixOwner -> repeat until stop rules pass
 ```
 
-Copy-paste agent prompt (Codex) — a plain prompt, not a built-in command:
+Copy-paste agent prompt (Codex) - a plain prompt, not a built-in command:
 
 ```text
 Build my-video/ into a reviewed VibeFrame MP4. Use --json for every vibe
@@ -44,7 +46,7 @@ AI review score is >= 90 when AI review is requested, and unresolved host-agent
 accepted with a written reason, or reported as blocked.
 ```
 
-Copy-paste agent prompt (Claude Code) — a plain prompt, not a built-in command:
+Copy-paste agent prompt (Claude Code) - a plain prompt, not a built-in command:
 
 ```text
 Finish the VibeFrame render for my-video/ using your host's agent loop as
@@ -71,15 +73,15 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 
 ## Global rules
 
-1. **`--json` everywhere** — auto-enabled on non-TTY stdout but pass
+1. **`--json` everywhere** - auto-enabled on non-TTY stdout but pass
    explicitly for clarity. Output goes to **stdout**.
-2. **`--dry-run` before any paid call** — returns a `costUsd` estimate
+2. **`--dry-run` before any paid call** - returns a `costUsd` estimate
    in the JSON envelope without spending. Validates inputs.
-3. **`--stdin` for complex options** — `echo '{"key":"value"}' | vibe
+3. **`--stdin` for complex options** - `echo '{"key":"value"}' | vibe
 <cmd> --stdin --json`. CLI flags still win on conflict.
-4. **`--fields <list>`** — limit JSON output fields on read-heavy
+4. **`--fields <list>`** - limit JSON output fields on read-heavy
    commands (e.g. `--fields "path,duration"`).
-5. **`--describe`** — print a command's JSON Schema and exit (no
+5. **`--describe`** - print a command's JSON Schema and exit (no
    execution). Useful for prompt-time discovery.
 
 ## Cost tiers
@@ -123,13 +125,17 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 }
 ```
 
-| Code            | Exit | Meaning             | Recovery                   |
-| --------------- | ---- | ------------------- | -------------------------- |
-| `USAGE_ERROR`   | 2    | bad arg             | check `vibe schema <cmd>`  |
-| `NOT_FOUND`     | 3    | file missing        | verify path                |
-| `AUTH_ERROR`    | 4    | key missing/invalid | `vibe doctor`              |
-| `API_ERROR`     | 5    | provider failed     | retry if `retryable: true` |
-| `NETWORK_ERROR` | 6    | connection          | retry with backoff         |
+| Code                 | Exit | Meaning                     | Recovery                          |
+| -------------------- | ---- | --------------------------- | --------------------------------- |
+| `COST_CAP_EXCEEDED`  | 1    | estimate over `--max-cost`  | follow `retryWith`; do not re-run as-is |
+| `USAGE_ERROR`        | 2    | bad arg                     | check `vibe schema <cmd>`         |
+| `NOT_FOUND`          | 3    | file missing                | verify path                       |
+| `AUTH_ERROR`         | 4    | key missing/invalid         | `vibe doctor`                     |
+| `API_ERROR`          | 5    | provider failed             | retry if `retryable: true`        |
+| `NETWORK_ERROR`      | 6    | connection                  | retry with backoff                |
+
+`COST_CAP_EXCEEDED` also carries `data.plan` - the priced plan the refusal was
+based on - so a refused call still tells you what the build would have cost.
 
 ## Authentication
 

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

@@ -15,15 +15,15 @@
  * OpenAI Codex, Cursor, Aider, Sourcegraph Cody, OpenCode, and (via
  * the @AGENTS.md import) Claude Code. Gemini CLI users may want to
  * also keep a sibling \`GEMINI.md\` since that's its primary context
- * file. Keep this as the canonical source of truth for agent guidance —
+ * 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) \u2014\na CLI for AI-powered video editing. The `vibe` command provides 80+\nsubcommands for video generation, editing, analysis, and pipeline\norchestration. Cost tiers below \u2014 **always confirm with the user before\nrunning 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** \u2014 `CLAUDE.md` (this file's import wrapper) +\n  `AGENTS.md` + `/vibe-*` slash commands.\n- **OpenAI Codex** \u2014 reads `AGENTS.md` natively (agents.md spec).\n- **Cursor** \u2014 reads `AGENTS.md` plus `.cursor/rules/` for project\n  rules; supports MCP via `.cursor/mcp.json`.\n- **Aider** \u2014 reads `AGENTS.md` (binary-only detection by VibeFrame).\n- **Gemini CLI** \u2014 primary context file is `GEMINI.md`; also reads\n  `AGENTS.md` if present.\n- **OpenCode** \u2014 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 \u2014 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 \u2014 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 \u2014 **OR pastes a visual/audio brief without explicit\nstoryboard / scene / multi-scene language** \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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) \u2014 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) \u2014 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** \u2014 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 (batch / non-agent fallback)\n\nWhen you don't want to author HTML yourself, `vibe build --mode batch` runs an\nLLM internally with the same skill bundle. It auto-picks a provider based\non available keys (`claude > gemini > openai`) \u2014 pass `--composer <name>`\nto force one:\n\n| Provider | Env var | Spike notes (v0.70) |\n|---|---|---|\n| Claude (default) | `ANTHROPIC_API_KEY` | ~9 s/beat. Fastest, validated baseline. |\n| Gemini | `GOOGLE_API_KEY` | ~20 s/beat. ~2.6\u00D7 cheaper than Claude. |\n| OpenAI | `OPENAI_API_KEY` | ~70 s/beat. gpt-5 reasoning latency \u2014 opt-in only. |\n\nAll three pass first-shot lint at every effort tier on the `vibeframe-promo`\nfixture. Quality on more complex storyboards may differ \u2014 fall back to\n`--composer claude` if a non-default provider repeatedly fails lint.\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, 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";
 /**
  * Claude Code project file. Imports AGENTS.md so guidance stays
  * single-sourced; adds Claude-specific overrides (slash commands, etc.).
  */
-export declare const CLAUDE_MD = "@AGENTS.md\n\n# Claude Code overrides\n\nThis file imports `AGENTS.md` (above) \u2014 that's the canonical source.\nAdd anything Claude-Code-specific *below*; everything generic should\nstay in AGENTS.md so other agent hosts (Codex, Cursor, Aider, Gemini CLI, OpenCode) see it\ntoo.\n\n## Skills\n\nIf you ran `vibe init` with Claude Code detected, the VibeFrame skill\npack is available as slash commands (consolidated to 2 in v0.62 \u2014 the\noverview content moved into AGENTS.md above):\n\n- `/vibe-pipeline` \u2014 YAML pipeline authoring helper (Video as Code)\n- `/vibe-scene` \u2014 per-scene HTML authoring + `vibe build`\n\nClaude-specific routing note: follow the ASSET / BUILD / REMIX decision\nrules in `AGENTS.md`. In particular, a request for one generated image or\none generated video clip is an ASSET request: use `vibe generate image` or\n`vibe generate video` directly. A request for designed/animated overlays\non an existing clip is usually `vibe edit motion-overlay ... --understand auto`,\nnot `vibe edit text-overlay`, unless the user explicitly asks for a simple\nstatic text burn-in. Do not invoke `/vibe-scene`, edit\n`DESIGN.md`, or edit `STORYBOARD.md` unless the user explicitly asks for a\nscene, storyboard, or composed video.\n\nTo install / update them later:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vericontext/vibeframe/main/scripts/install-skills.sh | bash\n```\n\n## Project-specific guidance\n\n<!-- Add Claude-specific notes here: which sub-agents to prefer, custom\n     slash commands you've added, conversational style preferences, etc. -->\n";
+export declare const CLAUDE_MD = "@AGENTS.md\n\n# Claude Code overrides\n\nThis file imports `AGENTS.md` (above) - that's the canonical source.\nAdd anything Claude-Code-specific *below*; everything generic should\nstay in AGENTS.md so other agent hosts (Codex, Cursor, Aider, Gemini CLI, OpenCode) see it\ntoo.\n\n## Skills\n\nIf you ran `vibe init` with Claude Code detected, the VibeFrame skill\npack is available as slash commands (consolidated to 2 in v0.62 - the\noverview content moved into AGENTS.md above):\n\n- `/vibe-pipeline` - YAML pipeline authoring helper (Video as Code)\n- `/vibe-scene` - per-scene HTML authoring + `vibe build`\n\nClaude-specific routing note: follow the ASSET / BUILD / REMIX decision\nrules in `AGENTS.md`. In particular, a request for one generated image or\none generated video clip is an ASSET request: use `vibe generate image` or\n`vibe generate video` directly. A request for designed/animated overlays\non an existing clip is usually `vibe edit motion-overlay ... --understand auto`,\nnot `vibe edit text-overlay`, unless the user explicitly asks for a simple\nstatic text burn-in. Do not invoke `/vibe-scene`, edit\n`DESIGN.md`, or edit `STORYBOARD.md` unless the user explicitly asks for a\nscene, storyboard, or composed video.\n\nTo install / update them later:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vericontext/vibeframe/main/scripts/install-skills.sh | bash\n```\n\n## Project-specific guidance\n\n<!-- Add Claude-specific notes here: which sub-agents to prefer, custom\n     slash commands you've added, conversational style preferences, etc. -->\n";
 /**
  * Gemini CLI project file. Gemini CLI's primary context file is
  * `GEMINI.md` (per https://geminicli.com/docs/cli/gemini-md/), so this
@@ -34,7 +34,7 @@ export declare const CLAUDE_MD = "@AGENTS.md\n\n# Claude Code overrides\n\nThis
  * human-readable note below ensures the agent picks up `AGENTS.md`
  * either way.
  */
-export declare const GEMINI_MD = "@AGENTS.md\n\n# Gemini CLI overrides\n\nThis project's canonical agent guidance lives in `AGENTS.md` \u2014 read\nit first. The `@AGENTS.md` line above is the import marker; if\nGemini CLI doesn't inline imported files in your version, open\n`AGENTS.md` directly. Both files are kept in sync by `vibe init`.\n\n## Project-specific guidance\n\n<!-- Add Gemini-CLI-specific notes here: any conventions specific to\n     how you drive vibe from Gemini CLI (preferred models, tone, etc.). -->\n";
+export declare const GEMINI_MD = "@AGENTS.md\n\n# Gemini CLI overrides\n\nThis project's canonical agent guidance lives in `AGENTS.md` - read\nit first. The `@AGENTS.md` line above is the import marker; if\nGemini CLI doesn't inline imported files in your version, open\n`AGENTS.md` directly. Both files are kept in sync by `vibe init`.\n\n## Project-specific guidance\n\n<!-- Add Gemini-CLI-specific notes here: any conventions specific to\n     how you drive vibe from Gemini CLI (preferred models, tone, etc.). -->\n";
 /** Shape the init renderer can fill in for the .env.example body. */
 export interface EnvExampleOptions {
     /** When true, surfaces a "tier: free local fallbacks" section at the top. */
@@ -50,7 +50,7 @@ export declare function renderEnvExample(opts?: EnvExampleOptions): string;
 export declare const GITIGNORE_ADDITIONS = "\n# VibeFrame\n.env\n.env.local\nrenders/\n.pipeline-state.yaml\n*.vibe.json\n.vibeframe/\n\n# Hyperframes skill copies left by older VibeFrame versions, which vendored a\n# snapshot of upstream's rules. Nothing writes these now - upstream's installer\n# owns the rules and puts them under .agents/skills/hyperframes/, which is\n# yours to commit or ignore. These lines only keep pre-existing copies quiet.\n/SKILL.md\n/references/\n/.claude/skills/hyperframes/\n/.cursor/rules/hyperframes.mdc\n";
 /**
  * vibe.project.yaml minimal scaffold. Only written when no project
- * config exists — `vibe init` never overwrites an existing file unless
+ * config exists - `vibe init` never overwrites an existing file unless
  * --force.
  */
 export declare function renderProjectYaml(opts: {

package/dist/commands/_shared/scene-project.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module _shared/scene-project
  *
- * Helpers for scaffolding a "scene project" — a directory that works as both
+ * Helpers for scaffolding a "scene project" - a directory that works as both
  * a VibeFrame project (via `vibe.config.json`) AND a HeyGen Hyperframes
  * project (via `hyperframes.json` + `meta.json` + `index.html`). Either
  * toolchain can be run inside the directory.
@@ -15,13 +15,13 @@ import type { VisualStyle } from "./visual-styles.js";
 export type SceneAspect = "16:9" | "9:16" | "1:1" | "4:5";
 export type SceneScaffoldProfile = "minimal" | "agent" | "full";
 /**
- * Project KIND — orthogonal to {@link SceneScaffoldProfile} (which decides which
+ * Project KIND - orthogonal to {@link SceneScaffoldProfile} (which decides which
  * files exist). Kind decides which pipeline STAGES run and which composer is the
  * default:
- * - `cinema` / `story` — directed, character-driven; keyframe→i2v, LLM composer.
- * - `aivideo` — character + i2v, the deterministic `template` composer.
- * - `product` — backdrop/asset-centric (no i2v keyframes).
- * - `motion` — pure HTML/CSS/GSAP graphics (no AI image/video assets).
+ * - `cinema` / `story` - directed, character-driven; keyframe→i2v, LLM composer.
+ * - `aivideo` - character + i2v, the deterministic `template` composer.
+ * - `product` - backdrop/asset-centric (no i2v keyframes).
+ * - `motion` - pure HTML/CSS/GSAP graphics (no AI image/video assets).
  */
 export type SceneKind = "cinema" | "product" | "aivideo" | "story" | "motion";
 export declare const VALID_SCENE_KINDS: readonly SceneKind[];
@@ -98,13 +98,13 @@ export declare function buildHyperframesConfig(): HyperframesConfig;
 export declare function buildHyperframesMeta(name: string, now?: Date): HyperframesMeta;
 /**
  * Merge an existing Hyperframes config with our defaults, preserving any
- * user-authored keys and nested values. `vibe scene init` is idempotent:
+ * user-authored keys and nested values. `vibe init` is idempotent:
  * running it on a directory that already has `hyperframes.json` must never
  * lose user config.
  */
 export declare function mergeHyperframesConfig(existing: HyperframesConfig, defaults: HyperframesConfig): HyperframesConfig;
 /**
- * Minimal valid Hyperframes root composition — empty (no sub-compositions
+ * Minimal valid Hyperframes root composition - empty (no sub-compositions
  * yet). A later `vibe scene add` inserts `<div class="clip" ...>` children.
  */
 export declare function buildEmptyRootHtml(opts: {
@@ -116,13 +116,13 @@ export declare function buildDesignMd(opts: {
     style?: VisualStyle;
 }): string;
 /**
- * Always-on `SCRIPT.md` — the narrative spine authored before the beat-level
+ * Always-on `SCRIPT.md` - the narrative spine authored before the beat-level
  * STORYBOARD.md. Kind tailors the guidance (a `motion`/`product` script is a
  * shot/asset list; a `story`/`cinema` script is a scene-by-scene narrative).
  */
 export declare function buildScriptMd(name: string, kind?: SceneKind): string;
 /**
- * Kind-gated `CHARACTERS.md` — the cast bible. Promotes today's STORYBOARD
+ * Kind-gated `CHARACTERS.md` - the cast bible. Promotes today's STORYBOARD
  * \`characters:\` frontmatter into first-class identity blocks (reference sheet
  * path + an identity-lock description used to keep keyframes/i2v on-model).
  */
@@ -149,7 +149,7 @@ export interface ScaffoldOptions {
     visualStyle?: VisualStyle;
     /** Scaffold shape. Defaults to "full" for backward-compatible programmatic use. */
     profile?: SceneScaffoldProfile;
-    /** Project kind — drives which pipeline stages run + the default composer. */
+    /** Project kind - drives which pipeline stages run + the default composer. */
     kind?: SceneKind;
 }
 export interface ScaffoldResult {

package/dist/commands/_shared/walkthroughs/walkthroughs.d.ts

@@ -5,7 +5,7 @@
  * `/vibe-pipeline` slash commands. After Plan H, host agents
  * (Claude Code, Codex, Cursor, Aider, Gemini CLI, OpenCode) all read
  * SKILL.md from the user's project and can drive `vibe build`
- * directly — but discoverability of the *workflow* itself was still
+ * directly - but discoverability of the *workflow* itself was still
  * Claude-Code-only via the slash menu.
  *
  * `vibe guide <topic>` closes that gap: any host (or a human at
@@ -30,12 +30,12 @@ export interface WalkthroughResult {
     steps: string[];
     /** Related vibe CLI commands referenced by the walkthrough. */
     relatedCommands: string[];
-    /** Full markdown body — same content the Claude Code slash command loads. */
+    /** Full markdown body - same content the Claude Code slash command loads. */
     content: string;
 }
 /** All walkthrough topics this CLI knows. */
 export declare const WALKTHROUGH_TOPICS: readonly WalkthroughTopic[];
-/** Pure data accessor — no I/O. Throws on unknown topic. */
+/** Pure data accessor - no I/O. Throws on unknown topic. */
 export declare function loadWalkthrough(topic: WalkthroughTopic): WalkthroughResult;
 /** List all walkthroughs (for `vibe guide --list` / no-arg invocation). */
 export declare function listWalkthroughs(): Array<{

package/dist/commands/output.d.ts

@@ -22,6 +22,12 @@ export interface StructuredError {
     retryWith?: string[];
     recoverable?: boolean;
     retryable: boolean;
+    /**
+     * 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
+     * the `--max-cost` gate to return the priced build plan with the refusal.
+     */
+    data?: Record<string, unknown>;
 }
 export declare function usageError(msg: string, suggestion?: string): StructuredError;
 export declare function authError(envVar: string, provider: string): StructuredError;
@@ -29,6 +35,21 @@ export declare function apiError(msg: string, retryable?: boolean): StructuredEr
 export declare function notFoundError(path: string): StructuredError;
 export declare function networkError(msg: string): StructuredError;
 export declare function generalError(msg: string, suggestion?: string): StructuredError;
+/**
+ * The `--max-cost` refusal. A command that declines to spend is a failure, so
+ * it takes the structured error path like every other refusal: `success:false`
+ * on stderr, exit 1. `data` carries the priced plan the refusal was based on,
+ * so an agent gets the estimate and the reason from one call.
+ *
+ * `recoverable: true` because the caller has two real ways forward (raise the
+ * ceiling, or narrow the scope), both spelled out in `retryWith`.
+ */
+export declare function costCapError(opts: {
+    estimatedCostUsd: number;
+    maxCostUsd: number;
+    retryWith: string[];
+    data?: Record<string, unknown>;
+}): StructuredError;
 /** Output structured error then exit */
 export declare function exitWithError(err: StructuredError): never;
 /** Check if --json flag is active */