@vibeframe/cli 0.113.0 → 0.113.2

package/CONTEXT.md

@@ -5,12 +5,57 @@
 VibeFrame CLI (`vibe`) is a CLI-first video toolkit. 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, native Codex Goal mode and Claude Code `/goal`
+should own the outer loop: persistence, iteration, and stop decisions.
+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
 from `vibe schema --list`. This file is the _agent quickstart_: rules,
 conventions, and discovery hooks.
 
+## Native host goal loop
+
+Use the host's native goal feature rather than inventing a VibeFrame-owned
+goal runner. The canonical loop is:
+
+```text
+native host goal -> vibe context/schema -> plan dry-run -> build with budget
+-> status polling -> inspect project -> render -> inspect render
+-> repair/edit using nextActions/fixOwner -> repeat until stop rules pass
+```
+
+Copy-paste Codex goal:
+
+```text
+/goal Build my-video/ into a reviewed VibeFrame MP4. Use --json for every vibe
+command, run --dry-run before paid operations, cap generated-asset spend with
+--max-cost 5 where supported, and read build-report.json plus
+review-report.json before deciding the next action. Prefer nextActions: run
+only safeToAutoRun:true actions automatically, ask before
+requiresConfirmation:true actions, and use retryWith only as the compatibility
+fallback. Treat fixOwner:"vibe" as deterministic CLI repair work and
+fixOwner:"host-agent" as storyboard, DESIGN.md, or composition edits.
+Stop only when my-video/renders/final.mp4 exists, duration is within the target,
+aspect ratio matches the brief, inspect render --cheap has no errors, review
+AI review score is >= 90 when AI review is requested, and unresolved host-agent issues are fixed, intentionally
+accepted with a written reason, or reported as blocked.
+```
+
+Copy-paste Claude Code goal:
+
+```text
+/goal Finish the VibeFrame render for my-video/ using Claude Code goal mode as
+the outer loop. Use vibe context/schema when unsure, --json everywhere,
+dry-run before paid operations, --max-cost 5 for builds, nextActions before
+custom recovery, and build-report.json/review-report.json as loop state.
+Stop only when renders/final.mp4 exists, target duration and aspect ratio are
+met, render inspection has no errors, any AI review score is at least 90 when AI review is requested, and every
+remaining host-agent issue is fixed, accepted with rationale, or reported as
+blocked.
+```
+
 ## Discovery (use these first)
 
 ```bash
@@ -38,12 +83,12 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 
 ## Cost tiers
 
-| Tier      | Commands                                                                                                                        | Per-call cost |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| Tier      | Commands                                                                                                                              | Per-call cost |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
 | Free      | `schema/context/doctor`, `detect *`, `status *`, `plan`, `storyboard validate`, `inspect project/render --cheap`, deterministic edits | $0            |
-| Low       | `generate narration/sound-effect/music`, `audio transcribe/list-voices`, `inspect media`, optional AI review                         | $0.01–0.10    |
-| High      | `generate image/motion`, `edit image/reframe/grade/speed-ramp`                                                                       | $1–5          |
-| Very High | `generate video`, `edit fill-gaps`, `remix highlights/auto-shorts`, `build` with generated assets                                      | $5–50+        |
+| Low       | `generate narration/sound-effect/music`, `audio transcribe/list-voices`, `inspect media`, optional AI review                          | $0.01–0.10    |
+| High      | `generate image/motion`, `edit image/reframe/grade/speed-ramp`                                                                        | $1–5          |
+| Very High | `generate video`, `edit fill-gaps`, `remix highlights/auto-shorts`, `build` with generated assets                                     | $5–50+        |
 
 > Rule: **confirm with the user before any High / Very-High call**.
 
@@ -173,10 +218,14 @@ Review report contract:
 `review-report.json` by default. The file uses `kind:"review"`,
 `mode:"project"|"render"`, `status`, `score`, `issues[]`,
 `summary:{issueCount,errorCount,warningCount,infoCount,fixOwners}`,
-`sourceReports`, and `retryWith`. Each issue has `fixOwner:"vibe"` for
-deterministic CLI recovery or `fixOwner:"host-agent"` for storyboard/design/
-composition edits the host agent should make. Use `retryWith` first, then
-hand remaining `host-agent` issues to the agent.
+`sourceReports`, `nextActions`, and `retryWith`. Each issue has
+`fixOwner:"vibe"` for deterministic CLI recovery or `fixOwner:"host-agent"`
+for storyboard/design/composition edits the host agent should make. Prefer
+`nextActions` first: run only `safeToAutoRun:true` actions automatically, ask
+before `requiresConfirmation:true`, and use `retryWith` only as the fallback.
+A host-native goal should not stop while `host-agent` issues remain unless
+they are fixed, intentionally accepted with a written reason, or reported as
+blocked.
 
 Product surface contract:
 
@@ -242,7 +291,7 @@ vibe scene repair --project my-video --json
 
 `vibe status job --json` emits the normal success envelope with `data.kind:"job"`, flat job fields (`id`, `jobType`, `provider`, `status`, timestamps), `progress`, `result`, `retryWith`, and the raw `job` record for compatibility.
 
-`vibe status project --json` emits `data.kind:"project"`, `status`, `currentStage`, `beats:{total,assetsReady,compositionsReady,needsAuthor}`, `jobs.latest`, `build`, `review`, `warnings`, and `retryWith`. `review` includes `mode`, `issueCount`, `errorCount`, `warningCount`, `infoCount`, `fixOwners`, `sourceReports`, and its own `retryWith`; top-level `retryWith` carries the next resume command. Use `retryWith` rather than guessing the next command.
+`vibe status project --json` emits `data.kind:"project"`, `status`, `currentStage`, `beats:{total,assetsReady,compositionsReady,needsAuthor}`, `jobs.latest`, `build`, `review`, `warnings`, `nextActions`, and `retryWith`. `review` includes `mode`, `issueCount`, `errorCount`, `warningCount`, `infoCount`, `fixOwners`, `sourceReports`, `nextActions`, and its own `retryWith`; top-level `nextActions` carries the preferred resume contract while `retryWith` remains the compatibility fallback.
 
 ### Storyboard revision contract
 

package/dist/commands/_shared/build-cache.d.ts

@@ -1,4 +1,4 @@
-export type BuildAssetKind = "narration" | "backdrop" | "video" | "music";
+export type BuildAssetKind = "narration" | "backdrop" | "character" | "video" | "music";
 export interface CacheAssetDescriptor {
     key: string;
     path: string;
@@ -20,12 +20,21 @@ export declare function backdropCacheDescriptor(opts: {
     size: string;
     ratio?: string;
 }): CacheAssetDescriptor;
+export declare function characterCacheDescriptor(opts: {
+    name: string;
+    cue: string;
+    provider: string;
+    quality: "standard" | "hd";
+    size: string;
+}): CacheAssetDescriptor;
 export declare function imageRatioForSize(size: string | undefined): string;
 export declare function videoCacheDescriptor(opts: {
     beatId: string;
     cue: string;
     provider: string;
     duration: number | undefined;
+    /** Character reference image paths — changing them must invalidate the clip. */
+    characters?: string[];
 }): CacheAssetDescriptor;
 export declare function musicCacheDescriptor(opts: {
     beatId: string;

package/dist/commands/_shared/build-cache.test.d.ts

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

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) \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### Composition rules (scene HTML)\n\n`vibe init` installs local composition rules into your project. The\nuniversal copy lives at `SKILL.md` (with `references/*.md`), and\nhost-specific copies are placed where each agent expects them\n(`.claude/skills/hyperframes/` for Claude Code, `.cursor/rules/hyperframes.mdc`\nfor Cursor). **Read `SKILL.md` before authoring any scene composition HTML\nunder `compositions/`** \u2014 it defines the framework rules, motion\nprinciples, type system, and visual-identity hard-gate. The same skill\ngoverns `vibe scene lint` so your authored HTML and the linter stay in\nagreement.\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\nTo retro-install on a project scaffolded before this command existed, run\n`vibe scene install-skill [--host all]`.\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) \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## Native host goal loop\n\nFor long-running work, use Codex Goal mode, Claude Code `/goal`, Cursor, or\nanother host-native goal feature as the outer loop. VibeFrame should not own a\ncompeting project-level goal runner. 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 Codex:\n\n```text\n/goal Build 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 Claude Code:\n\n```text\n/goal Finish this VibeFrame render using Claude Code goal mode 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\n`vibe init` installs local composition rules into your project. The\nuniversal copy lives at `SKILL.md` (with `references/*.md`), and\nhost-specific copies are placed where each agent expects them\n(`.claude/skills/hyperframes/` for Claude Code, `.cursor/rules/hyperframes.mdc`\nfor Cursor). **Read `SKILL.md` before authoring any scene composition HTML\nunder `compositions/`** \u2014 it defines the framework rules, motion\nprinciples, type system, and visual-identity hard-gate. The same skill\ngoverns `vibe scene lint` so your authored HTML and the linter stay in\nagreement.\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\nTo retro-install on a project scaffolded before this command existed, run\n`vibe scene install-skill [--host all]`.\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";
 /**
  * Claude Code project file. Imports AGENTS.md so guidance stays
  * single-sourced; adds Claude-specific overrides (slash commands, etc.).

package/dist/commands/_shared/render-inspect.d.ts

@@ -1,5 +1,5 @@
 import type { VideoReviewFeedback } from "../ai-edit.js";
-import { type ReviewIssue, type ReviewSeverity, type ReviewSummary, type ReviewStatus } from "./review-report.js";
+import { type ReviewAction, type ReviewIssue, type ReviewSeverity, type ReviewSummary, type ReviewStatus } from "./review-report.js";
 export interface TimeRange {
     start: number;
     end: number;
@@ -64,6 +64,7 @@ export interface RenderInspectResult {
     score: number;
     issues: ReviewIssue[];
     summary: ReviewSummary;
+    nextActions: ReviewAction[];
     sourceReports: string[];
     checks: {
         renderFound: boolean;
@@ -75,6 +76,7 @@ export interface RenderInspectResult {
         height?: number;
         expectedAspect?: string;
         hasAudio?: boolean;
+        expectedAudio?: boolean;
         blackFrames: TimeRange[];
         staticFrames: TimeRange[];
         silences: TimeRange[];
@@ -101,4 +103,5 @@ export declare function aiReviewSeverity(score: number): ReviewSeverity;
 export declare function mapAiReviewFeedbackToIssues(feedback: VideoReviewFeedback, videoPath?: string): ReviewIssue[];
 export declare function scoreRenderReview(issues: ReviewIssue[], aiOverallScore?: number): number;
 export declare function inspectRender(opts: RenderInspectOptions): Promise<RenderInspectResult>;
+export declare function renderExpectsAudio(projectDir: string, beatId?: string): Promise<boolean>;
 export declare function resolveRenderVideoPath(projectDir: string, explicit?: string, beatId?: string): Promise<string | null>;

package/dist/commands/_shared/review-report.d.ts

@@ -2,6 +2,21 @@ export type ReviewSeverity = "error" | "warning" | "info";
 export type ReviewStatus = "pass" | "warn" | "fail";
 export type ReviewMode = "project" | "render";
 export type ReviewFixOwner = "vibe" | "host-agent";
+export type ReviewActionKind = "command" | "agent" | "manual";
+export type ReviewActionCostTier = "free" | "low" | "high" | "very-high" | "unknown";
+export interface ReviewAction {
+    id: string;
+    kind: ReviewActionKind;
+    label: string;
+    command?: string;
+    agentPrompt?: string;
+    fixOwner: ReviewFixOwner;
+    costTier: ReviewActionCostTier;
+    safeToAutoRun: boolean;
+    requiresConfirmation: boolean;
+    reason: string;
+    sourceIssueCodes?: string[];
+}
 export interface ReviewIssue {
     severity: ReviewSeverity;
     code: string;
@@ -19,6 +34,7 @@ export interface ReviewIssue {
     audioCoverageRatio?: number;
     fixOwner?: ReviewFixOwner;
     suggestedFix?: string;
+    actions?: ReviewAction[];
 }
 export interface ReviewSummary {
     issueCount: number;
@@ -40,6 +56,7 @@ export interface ReviewReport {
     score: number;
     issues: ReviewIssue[];
     summary: ReviewSummary;
+    nextActions: ReviewAction[];
     retryWith: string[];
     sourceReports: string[];
     reportPath?: string;
@@ -47,8 +64,40 @@ export interface ReviewReport {
 export declare function statusFromIssues(issues: ReviewIssue[]): ReviewStatus;
 export declare function scoreIssues(issues: ReviewIssue[]): number;
 export declare function uniqueRetryWith(items: Array<string | undefined | null>): string[];
+export declare function commandReviewAction(command: string, opts: {
+    label?: string;
+    fixOwner?: ReviewFixOwner;
+    reason: string;
+    sourceIssueCodes?: string[];
+    costTier?: ReviewActionCostTier;
+    safeToAutoRun?: boolean;
+    requiresConfirmation?: boolean;
+}): ReviewAction;
+export declare function agentReviewAction(opts: {
+    label: string;
+    agentPrompt: string;
+    reason: string;
+    sourceIssueCodes?: string[];
+}): ReviewAction;
+export declare function manualReviewAction(opts: {
+    label: string;
+    reason: string;
+    fixOwner?: ReviewFixOwner;
+    sourceIssueCodes?: string[];
+}): ReviewAction;
+export declare function reviewActionsFromRetryWith(retryWith: string[], sourceIssueCodes?: string[]): ReviewAction[];
+export declare function normalizeReviewActions(actions: ReviewAction[]): ReviewAction[];
+export declare function deriveNextReviewActions(opts: {
+    issues: ReviewIssue[];
+    retryWith: string[];
+    projectDir?: string;
+}): ReviewAction[];
 export declare function fixOwnerForIssue(issue: Pick<ReviewIssue, "code" | "fixOwner">): ReviewFixOwner;
-export declare function normalizeReviewIssues(issues: ReviewIssue[], fallbackOwner?: ReviewFixOwner): ReviewIssue[];
+export declare function normalizeReviewIssues(issues: ReviewIssue[], opts?: ReviewFixOwner | {
+    fallbackOwner?: ReviewFixOwner;
+    projectDir?: string;
+    retryWith?: string[];
+}): ReviewIssue[];
 export declare function summarizeReviewIssues(issues: ReviewIssue[]): ReviewSummary;
 export declare function buildReviewReport(opts: {
     project: string;

package/dist/commands/_shared/review-report.test.d.ts

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

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

@@ -34,6 +34,19 @@ export type BuildImageProvider = "openai" | "gemini" | "grok";
 export type SceneBuildProgressEvent = {
     type: "phase-start";
     phase: "primitives" | "compose" | "render";
+} | {
+    type: "character-cached";
+    name: string;
+    path: string;
+} | {
+    type: "character-generated";
+    name: string;
+    path: string;
+    provider: string;
+} | {
+    type: "character-failed";
+    name: string;
+    error: string;
 } | {
     type: "narration-cached";
     beatId: string;

package/dist/commands/_shared/scene-html-emit.d.ts

@@ -46,7 +46,7 @@ export interface LottieOverlayInput {
     loop?: boolean;
 }
 export interface EmitSceneInput {
-    /** Kebab-case scene id; appears in `data-composition-id` and template id. */
+    /** Kebab-case beat id; emitted composition id is `scene-<id>` to match root-sync. */
     id: string;
     preset: ScenePreset;
     /** Canvas width in px (must match the root composition). */
@@ -80,6 +80,8 @@ export interface EmitSceneInput {
      */
     lottie?: LottieOverlayInput;
 }
+/** Root-sync's canonical composition id for a storyboard beat id. */
+export declare function sceneCompositionId(beatId: string): string;
 /**
  * Slugify a free-form scene name to a kebab-case id usable in HTML attributes
  * and filenames. Strips diacritics, collapses whitespace, lowercases.
@@ -133,7 +135,7 @@ export declare function emitSceneHtml(input: EmitSceneInput): string;
  */
 export declare function nextSceneStart(rootHtml: string, overlap?: number): number;
 export interface ClipReferenceInput {
-    /** Scene id — used to derive the composition src path. */
+    /** Beat id — used to derive `scene-<id>` composition id and src path. */
     id: string;
     start: number;
     duration: number;

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

@@ -1,4 +1,4 @@
-import { type ReviewIssue, type ReviewSummary, type ReviewStatus } from "./review-report.js";
+import { type ReviewAction, type ReviewIssue, type ReviewSummary, type ReviewStatus } from "./review-report.js";
 export interface ProjectInspectOptions {
     projectDir: string;
     beatId?: string;
@@ -15,6 +15,7 @@ export interface ProjectInspectResult {
     score: number;
     issues: ReviewIssue[];
     summary: ReviewSummary;
+    nextActions: ReviewAction[];
     sourceReports: string[];
     checks: {
         files: Record<string, boolean>;

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

@@ -1,4 +1,5 @@
 import type { BuildAssetKind } from "./build-cache.js";
+import type { ReviewAction } from "./review-report.js";
 export type JobStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "unknown";
 /**
  * `generate-video` / `generate-music` are provider-backed jobs refreshed by
@@ -127,6 +128,7 @@ export interface ProjectStatusResult {
         latest: JobSummary[];
     };
     warnings: string[];
+    nextActions: ReviewAction[];
     retryWith: string[];
 }
 export interface BuildSummary {
@@ -161,6 +163,7 @@ export interface ReviewSummary {
     };
     sourceReports: string[];
     updatedAt?: string;
+    nextActions: ReviewAction[];
     retryWith: string[];
 }
 export interface JobSummary {

package/dist/commands/_shared/storyboard-edit.d.ts

@@ -1,5 +1,5 @@
 import { type Beat } from "./storyboard-parse.js";
-export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "motion", "voice", "music", "asset"];
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "motion", "voice", "music", "asset", "characters"];
 export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
 export interface StoryboardValidationIssue {
     severity: "error" | "warning";
@@ -12,10 +12,24 @@ export interface StoryboardValidationResult {
     beats: Beat[];
     issues: StoryboardValidationIssue[];
 }
+export type StoryboardBeatUpsertAction = "replaced-starter" | "appended" | "updated";
+export interface StoryboardBeatUpsertInput {
+    beatId: string;
+    title?: string;
+    duration?: number;
+    narration?: string;
+    backdrop?: string;
+    body?: string;
+}
+export interface StoryboardBeatUpsertResult {
+    markdown: string;
+    action: StoryboardBeatUpsertAction;
+}
 /** Beats beyond this render as static, overstuffed scenes. */
 export declare const MAX_RECOMMENDED_BEAT_SEC = 15;
 export declare function validateStoryboardMarkdown(markdown: string): StoryboardValidationResult;
 export declare function getStoryboardBeat(markdown: string, beatId: string): Beat | null;
+export declare function upsertStoryboardBeat(markdown: string, opts: StoryboardBeatUpsertInput): StoryboardBeatUpsertResult;
 export declare function setStoryboardCue(markdown: string, opts: {
     beatId: string;
     key: string;

package/dist/commands/_shared/storyboard-parse.d.ts

@@ -65,8 +65,35 @@ export interface ProjectFrontmatter {
     defaultDuration?: number;
     /** Visual identity preset hint (informational; e.g. "Swiss Pulse"). */
     style?: string;
+    /**
+     * Reusable character pool. Each entry is either a generation prompt
+     * (string → build renders a turnaround sheet at `assets/character-<name>.png`)
+     * or an object with `description` (same, explicit) and/or `image` (a
+     * bring-your-own reference path, which skips generation). Beats reference
+     * these by name via the `characters:` cue to drive reference-to-video.
+     */
+    characters?: Record<string, CharacterSpec>;
     [key: string]: unknown;
 }
+/** A character pool entry — a prompt string or a structured spec. */
+export type CharacterSpec = string | {
+    description?: string;
+    image?: string;
+};
+/** Normalized character ready for build: generation prompt and/or supplied image. */
+export interface ResolvedCharacter {
+    name: string;
+    /** Generation prompt when the sheet should be rendered (absent if `image` given). */
+    prompt?: string;
+    /** Bring-your-own reference image path, relative to the project dir. */
+    imagePath?: string;
+}
+/**
+ * Flatten the frontmatter `characters` map into build-ready specs. A string or
+ * `{ description }` becomes a generation prompt; `{ image }` is used as-is
+ * (generation skipped). Entries with neither are dropped.
+ */
+export declare function resolveCharacters(frontmatter: ProjectFrontmatter | undefined): ResolvedCharacter[];
 /**
  * Per-beat cues extracted from the first ```yaml fenced block inside a beat
  * body. The driver passes these to TTS / image / compose calls so the
@@ -81,8 +108,15 @@ export interface BeatCues {
     duration?: number;
     /** Voice override for this beat (overrides project frontmatter `voice`). */
     voice?: string;
+    /**
+     * Character pool names whose reference sheets drive this beat's
+     * reference-to-video generation. A single name or a list.
+     */
+    characters?: string | string[];
     [key: string]: unknown;
 }
+/** Normalize a beat's `characters` cue to a clean string[] (single or list). */
+export declare function beatCharacterNames(cues: BeatCues | undefined): string[];
 export interface Beat {
     /**
      * Stable id for the beat. Derivation order:

package/dist/commands/error-envelopes.test.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @file error-envelopes.test.ts
+ *
+ * Contract/drift detection for the CLI's STRUCTURED ERROR envelope — the JSON
+ * that `exitWithError()` (commands/output.ts) writes to stderr when a command
+ * fails. Companion to `envelope-snapshots.test.ts`, which only covers the
+ * SUCCESS envelope (`outputSuccess`) and `--describe` schemas; the error
+ * envelope was previously untested.
+ *
+ * Why:
+ * - Agents and MCP hosts parse the error envelope (`code`, `exitCode`,
+ *   `retryWith`, `recoverable`) to decide recovery. A regression that renames
+ *   or drops a field, or changes a code/exit-code, silently breaks that
+ *   contract. Snapshots make it visible in PR review.
+ * - This test also guards against fabricated contracts: the real envelope has
+ *   no `hint` field and uses SCREAMING_SNAKE codes with no `E_` prefix.
+ *
+ * The asserted codes/exit-codes were verified by running the built CLI:
+ *   NOT_FOUND=3, USAGE_ERROR=2, API_ERROR=5, ERROR=1 (the ExitCode enum in
+ *   commands/output.ts).
+ *
+ * Maintenance:
+ * - Intentional envelope change → update with `pnpm -F @vibeframe/cli exec
+ *   vitest run -u` and review the diff.
+ */
+export {};

package/dist/commands/review-actions-cli.test.d.ts

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

package/dist/commands/scene.d.ts

@@ -19,6 +19,7 @@
 import { Command } from "commander";
 import { type TtsProviderName } from "./_shared/tts-resolve.js";
 import { type ScenePreset, type LottieOverlayInput } from "./_shared/scene-html-emit.js";
+import { type StoryboardBeatUpsertAction } from "./_shared/storyboard-edit.js";
 export declare const sceneCommand: Command;
 export interface SceneAddOptions {
     name: string;
@@ -43,6 +44,11 @@ export interface SceneAddOptions {
     projectDir?: string;
     /** Filename of the root composition (relative to projectDir). */
     insertInto?: string;
+    /**
+     * Sync STORYBOARD.md when present, then rebuild root refs via root-sync.
+     * Defaults to true; pass false for the legacy root-only quick-draft path.
+     */
+    syncStoryboard?: boolean;
     /** "gemini" | "openai". */
     imageProvider?: string;
     /** TTS provider preference. Defaults to `"auto"` (ElevenLabs if key set, else Kokoro). */
@@ -86,6 +92,12 @@ export interface SceneAddResult {
     /** Number of word entries emitted into the transcript JSON. */
     transcriptWordCount?: number;
     lottiePath?: string;
+    /** Project-relative path to STORYBOARD.md when the command synced it. */
+    storyboardPath?: string;
+    /** Whether STORYBOARD.md was used as the root-sync source of truth. */
+    storyboardSynced?: boolean;
+    /** How STORYBOARD.md was changed, or "skipped" when root-only behavior was used. */
+    storyboardAction?: "skipped" | StoryboardBeatUpsertAction;
     error?: string;
 }
 export declare function executeSceneAdd(opts: SceneAddOptions): Promise<SceneAddResult>;