@vibeframe/mcp-server 0.113.28 → 0.113.30

package/README.md

@@ -1,6 +1,6 @@
 # @vibeframe/mcp-server
 
-The MCP (Model Context Protocol) **server** for [VibeFrame](https://github.com/vericontext/vibeframe). This package is _only_ the MCP adapter — it exposes VibeFrame's operations as typed MCP tools so an MCP-capable host can call them by natural language.
+The MCP (Model Context Protocol) **server** for [VibeFrame](https://github.com/vericontext/vibeframe), the frontier-video-generation layer for coding agents: generate video assets on your own provider keys (Seedance, Runway, Veo, Kling), behind dry runs and a hard `--max-cost` ceiling. This package is _only_ the MCP adapter - it exposes VibeFrame's operations as typed MCP tools so an MCP-capable host can call them by natural language.
 
 VibeFrame is CLI-first, not terminal-only. The CLI is the stable runtime; MCP is the app-host surface for clients that prefer typed tools over shell commands.
 

package/dist/index.js

@@ -24010,6 +24010,9 @@ function exitWithError(err) {
     if (err.suggestion) {
       console.error(source_default.dim(`  ${err.suggestion}`));
     }
+    if (err.retryWith && err.retryWith.length > 0) {
+      console.error(source_default.dim(`  Retry: ${err.retryWith[0]}`));
+    }
     console.error();
   }
   process.exit(err.exitCode);
@@ -26064,12 +26067,12 @@ colors:
 ---
 
 `;
-  const intro = style ? `Visual identity for **${name}**, scaffolded from the **${style.name}** style (after ${style.designer}). Customise freely \u2014 this file is the single source of truth for every scene's palette, typography, and motion.` : `Visual identity for **${name}**. Fill the sections below before authoring any scene HTML or generating any backdrop. Pick a named style with \`vibe scene list-styles\` if you want a credible starting point.`;
-  const moodLine = style ? `**Mood:** ${style.mood} \xB7 **Best for:** ${style.bestFor}` : `**Mood:** _(one line \u2014 what should the viewer FEEL?)_`;
+  const intro = style ? `Visual identity for **${name}**, scaffolded from the **${style.name}** style (after ${style.designer}). Customise freely - this file is the single source of truth for every scene's palette, typography, and motion.` : `Visual identity for **${name}**. Fill the sections below before authoring any scene HTML or generating any backdrop. Pick a named style with \`vibe scene list-styles\` if you want a credible starting point.`;
+  const moodLine = style ? `**Mood:** ${style.mood} \xB7 **Best for:** ${style.bestFor}` : `**Mood:** _(one line - what should the viewer FEEL?)_`;
   const palette = style ? `${style.palette.map((c2) => `- \`${c2}\``).join("\n")}
 
-${style.paletteNotes}` : `- _hex_ \u2014 primary
-- _hex_ \u2014 accent
+${style.paletteNotes}` : `- _hex_ - primary
+- _hex_ - accent
 
 _2\u20133 colours max. Declare explicit hex values; never name colours abstractly._`;
   const typography = style ? style.typography : `_One family, two weights. State the role of each (headline / label / body)._`;
@@ -26083,7 +26086,7 @@ _2\u20133 colours max. Declare explicit hex values; never name colours abstractl
   const avoid = style ? style.avoid.map((a4) => `- ${a4}`).join("\n") : `- _anti-pattern 1_
 - _anti-pattern 2_
 - _anti-pattern 3_`;
-  return `${frontmatter}# ${name} \u2014 Design
+  return `${frontmatter}# ${name} - Design
 
 > **Hard-gate (BUILD flow only).** This file is the visual contract for
 > the scene-project flow (\`vibe build\`, \`vibe scene ...\`, composition
@@ -26127,12 +26130,12 @@ ${avoid}
 ---
 
 _Browse other named styles: \`vibe scene list-styles\`_
-${style ? `_This file was seeded by \`vibe scene init --visual-style "${style.name}"\`._` : `_Seed this file from a named style: \`vibe scene init <dir> --visual-style "<name>"\`._`}
+${style ? `_This file was seeded by \`vibe init --visual-style "${style.name}"\`._` : `_Seed this file from a named style: \`vibe init <dir> --visual-style "<name>"\`._`}
 `;
 }
 function buildScriptMd(name, kind3 = DEFAULT_SCENE_KIND) {
-  const intent = kind3 === "product" ? "Product walkthrough \u2014 what each section demonstrates, in order." : kind3 === "motion" ? "Motion piece \u2014 the message and the beats of on-screen text/graphics." : kind3 === "aivideo" ? "AI-video script \u2014 the spoken/voiced narrative the generated shots illustrate." : "Narrative script \u2014 scene-by-scene story, dialogue, and voiceover.";
-  return `# ${name} \u2014 Script
+  const intent = kind3 === "product" ? "Product walkthrough - what each section demonstrates, in order." : kind3 === "motion" ? "Motion piece - the message and the beats of on-screen text/graphics." : kind3 === "aivideo" ? "AI-video script - the spoken/voiced narrative the generated shots illustrate." : "Narrative script - scene-by-scene story, dialogue, and voiceover.";
+  return `# ${name} - Script
 
 > **Authoring order:** SCRIPT.md (this file) \u2192 STORYBOARD.md (beats + cues)${kindHasCast(kind3) ? " \u2192 CHARACTERS.md (cast bible)" : ""}.
 > ${intent}
@@ -26160,7 +26163,7 @@ Voiceover / on-screen: \u2026
 `;
 }
 function buildCharactersMd(name) {
-  return `# ${name} \u2014 Characters
+  return `# ${name} - Characters
 
 > Each character is referenced from STORYBOARD beats via the \`characters:\` cue.
 > The reference sheet + identity block keep keyframes and image-to-video on-model
@@ -26169,8 +26172,8 @@ function buildCharactersMd(name) {
 ## hero
 
 - **Reference sheet:** \`assets/characters/hero.png\` (a clean, front-lit full-body
-  or portrait sheet \u2014 the identity anchor for keyframe edits).
-- **Identity:** one paragraph of fixed, on-model traits \u2014 age, build, hair,
+  or portrait sheet - the identity anchor for keyframe edits).
+- **Identity:** one paragraph of fixed, on-model traits - age, build, hair,
   wardrobe, palette. Keep this stable across every beat.
 - **Range:** expressions / poses this character should hit.
 
@@ -26188,14 +26191,14 @@ tts: auto
 imageProvider: openai
 ---
 
-# ${name} \u2014 Storyboard
+# ${name} - Storyboard
 
 Edit these beats before running \`vibe build\`. Each beat starts with
 YAML cues that drive narration, backdrop generation, and timing.
 Pacing: keep beats 6-15 seconds (split longer ones); a 90s video should
 have 6-8 beats, not 3 long ones.
 
-## Beat hook \u2014 Hook
+## Beat hook - Hook
 
 \`\`\`yaml
 narration: "Introduce the promise in one crisp sentence."
@@ -26206,7 +26209,7 @@ duration: 4
 Show the core visual identity immediately. Keep copy short enough for one
 screen and one spoken breath.
 
-## Beat proof \u2014 Proof
+## Beat proof - Proof
 
 \`\`\`yaml
 narration: "Show the mechanism or proof point that makes the promise believable."
@@ -26217,7 +26220,7 @@ duration: 4
 Use this beat for the concrete differentiator: command, workflow, metric, or
 before/after.
 
-## Beat close \u2014 Close
+## Beat close - Close
 
 \`\`\`yaml
 narration: "Close with the action the viewer should remember."
@@ -26230,7 +26233,7 @@ final beat.
 `;
 }
 function buildProjectAgentsMd(name) {
-  return `# ${name} \u2014 Scene Authoring Project
+  return `# ${name} - Scene Authoring Project
 
 This is the canonical cross-agent guidance file for this scene project.
 Claude Code imports it through \`CLAUDE.md\`; Codex, Cursor, Aider,
@@ -26269,10 +26272,10 @@ contradict DESIGN.md are rejected by the Hyperframes \`hyperframes\`
 skill.
 
 Single-asset requests (\`vibe generate image|video|speech|...\`) do NOT
-consult this file \u2014 run the generate command directly.
+consult this file - run the generate command directly.
 
 Browse named styles: \`vibe scene list-styles\`. Re-seed from one with
-\`vibe scene init . --visual-style "Swiss Pulse"\` (idempotent).
+\`vibe init . --visual-style "Swiss Pulse"\` (idempotent).
 
 ## Brief and local media
 
@@ -26284,8 +26287,9 @@ after init, those two files are the working source of truth.
 Use \`media/\` for user-provided source files: product photos, screenshots,
 logos, B-roll, recorded narration, or reference clips. Keep those inputs
 inside this project so build references stay project-relative. Do not put user
-media in \`references/\`; that directory is reserved for local composition
-rules installed by VibeFrame.
+media in \`references/\`; older VibeFrame versions vendored composition rules
+there, and current installs keep the rules under \`.agents/skills/hyperframes/\`
+via \`vibe scene install-skill\`.
 
 When a beat should reuse a local file, reference it from \`STORYBOARD.md\`
 with a project-relative path:
@@ -26341,7 +26345,7 @@ project-level agent loop; it provides \`--json\` commands, dry runs, cost caps,
 \`requiresConfirmation\`, \`fixOwner\`, deterministic repair, and render
 inspection for the host agent to reason over.
 
-Copy-paste agent prompts \u2014 plain prompts, not a built-in command:
+Copy-paste agent prompts - plain prompts, not a built-in command:
 
 \`\`\`text
 Build this VibeFrame project into renders/final.mp4. Use --json for every
@@ -26369,9 +26373,9 @@ target duration/aspect ratio, clean render inspection, any AI review score >= 90
 no unresolved unacknowledged host-agent issues.
 \`\`\`
 
-## Skills \u2014 USE THESE FIRST
+## Skills - USE THESE FIRST
 
-**Load the \`hyperframes\` skill before authoring scenes** \u2014 it encodes the
+**Load the \`hyperframes\` skill before authoring scenes** - it encodes the
 composition rules, motion principles, type system, and visual-identity gate.
 If your agent has it installed globally it is already available; otherwise run
 \`vibe scene install-skill\`, which runs upstream's installer and writes
@@ -26383,7 +26387,7 @@ semantics, VibeFrame pipeline conventions) that are NOT in generic web docs.
 
 | Skill             | Command          | When to use                                                                           |
 | ----------------- | ---------------- | ------------------------------------------------------------------------------------- |
-| **hyperframes**   | \`/hyperframes\`   | Cinematic-quality composition \u2014 DESIGN.md hard-gate, named styles, motion principles  |
+| **hyperframes**   | \`/hyperframes\`   | Cinematic-quality composition - DESIGN.md hard-gate, named styles, motion principles  |
 | **vibe-scene**    | \`/vibe-scene\`    | VibeFrame's authoring loop, AI assets, lint feedback, pipeline integration            |
 | **gsap**          | \`/gsap\`          | GSAP tweens, timelines, easing                                                        |
 
@@ -26394,22 +26398,22 @@ npx skills add heygen-com/hyperframes
 \`\`\`
 
 Restart your agent session (or reload the skill list) after installing.
-If skills aren't available, follow the **Key Rules** below \u2014 they cover
+If skills aren't available, follow the **Key Rules** below - they cover
 the framework-level minimum, not the cinematic craft layer.
 
 ## Project structure
 
-- \`DESIGN.md\` \u2014 visual identity contract (palette, type, motion, transitions)
-- \`STORYBOARD.md\` \u2014 per-beat narration/backdrop/duration cues for \`vibe build\`
-- \`media/\` \u2014 user-provided source files (photos, logos, clips, voice recordings)
-- \`index.html\` \u2014 root composition (timeline)
-- \`compositions/scene-*.html\` \u2014 per-scene HTML authored by you or the agent
-- \`assets/\` \u2014 generated/canonical build media (narration audio, images, video)
-- \`.agents/skills/hyperframes/\` \u2014 upstream composition rules, when installed here rather than globally
-- \`transcript.json\` \u2014 Whisper word-level transcript (if narration exists)
-- \`hyperframes.json\` \u2014 HF registry config (speak to both toolchains)
-- \`vibe.config.json\` \u2014 canonical VibeFrame config (providers, budget)
-- \`renders/\` \u2014 output MP4s
+- \`DESIGN.md\` - visual identity contract (palette, type, motion, transitions)
+- \`STORYBOARD.md\` - per-beat narration/backdrop/duration cues for \`vibe build\`
+- \`media/\` - user-provided source files (photos, logos, clips, voice recordings)
+- \`index.html\` - root composition (timeline)
+- \`compositions/scene-*.html\` - per-scene HTML authored by you or the agent
+- \`assets/\` - generated/canonical build media (narration audio, images, video)
+- \`.agents/skills/hyperframes/\` - upstream composition rules, when installed here rather than globally
+- \`transcript.json\` - Whisper word-level transcript (if narration exists)
+- \`hyperframes.json\` - HF registry config (speak to both toolchains)
+- \`vibe.config.json\` - canonical VibeFrame config (providers, budget)
+- \`renders/\` - output MP4s
 
 ## Commands
 
@@ -26419,16 +26423,28 @@ vibe build                                                 # STORYBOARD.md \u219
 vibe scene lint                                             # Validate scenes (in-process HF linter)
 vibe render                                                 # Render to MP4
 
-# Hyperframes CLI (if installed \u2014 works in this project too)
+# Hyperframes CLI (if installed - works in this project too)
 npx hyperframes preview
 npx hyperframes render
 \`\`\`
 
 ## Key Rules (for hand-authored scene HTML)
 
+0. A scene file is a \`<template id="scene-<id>-template">\` wrapping ONE
+   composition div - not a standalone \`<!doctype html>\` document:
+   \`\`\`html
+   <template id="scene-hook-template">
+     <div data-composition-id="scene-hook" data-start="0" data-duration="3.3"
+          data-width="1920" data-height="1080">\u2026</div>
+   </template>
+   \`\`\`
+   The composition div **MUST** carry \`data-width\` and \`data-height\`.
 1. Every timed element needs \`data-start\`, \`data-duration\`, and \`data-track-index\`.
-2. Elements with timing **MUST** have \`class="clip"\` \u2014 the framework uses this for visibility control.
-3. Timelines must be paused and registered on \`window.__timelines\`:
+2. Elements with timing **MUST** have \`class="clip"\` - the framework uses this for visibility control.
+3. Timelines must be paused and registered on \`window.__timelines\`, which is an
+   OBJECT keyed by composition id - not an array, and \`.push()\` leaves the
+   timeline undiscovered, which renders a black frame because \`gsap.from\` holds
+   elements at their start state:
    \`\`\`js
    window.__timelines = window.__timelines || {};
    window.__timelines["composition-id"] = gsap.timeline({ paused: true });
@@ -26439,12 +26455,12 @@ npx hyperframes render
    \`filter\` tweens to \`.scene-content\` or any ancestor containing live text.
    Animate background/media layers instead; text/cards should enter briefly and
    then hold still at their final CSS positions.
-7. Only deterministic logic \u2014 no \`Date.now()\`, \`Math.random()\`, or network fetches.
+7. Only deterministic logic - no \`Date.now()\`, \`Math.random()\`, or network fetches.
 
-## Linting \u2014 run after changes
+## Linting - run after changes
 
 \`\`\`bash
-vibe scene lint           # preferred \u2014 in-process, no network
+vibe scene lint           # preferred - in-process, no network
 vibe scene lint --fix     # auto-fix mechanical issues
 vibe scene lint --json    # structured output for agent loops
 \`\`\`
@@ -26453,7 +26469,7 @@ vibe scene lint --json    # structured output for agent loops
 function buildProjectClaudeMd(name) {
   return `@AGENTS.md
 
-# ${name} \u2014 Claude Code Overrides
+# ${name} - Claude Code Overrides
 
 This file imports \`AGENTS.md\`; keep cross-agent VibeFrame and
 Hyperframes instructions there so Codex, Cursor, Aider, Gemini CLI, and
@@ -26462,7 +26478,7 @@ only when this project needs them.
 `;
 }
 function buildSceneGitignore() {
-  return `# VibeFrame \u2014 caches, checkpoints, and project-scope config.yaml (may contain API keys)
+  return `# VibeFrame - caches, checkpoints, and project-scope config.yaml (may contain API keys)
 .vibeframe/
 
 # Render outputs
@@ -268803,10 +268819,10 @@ async function getComposePrompts(opts) {
     error: msg
   });
   if (!existsSync43(designPath)) {
-    return baseError(`DESIGN.md not found at ${designPath}. Run \`vibe scene init <dir>\` first.`);
+    return baseError(`DESIGN.md not found at ${designPath}. Run \`vibe init <dir>\` first.`);
   }
   if (!existsSync43(storyboardPath)) {
-    return baseError(`STORYBOARD.md not found at ${storyboardPath}. Run \`vibe scene init <dir>\` to create a starter, or add STORYBOARD.md with per-beat cues.`);
+    return baseError(`STORYBOARD.md not found at ${storyboardPath}. Run \`vibe init <dir>\` to create a starter, or add STORYBOARD.md with per-beat cues.`);
   }
   if (!hyperframesSkillAvailable(projectDir)) {
     warnings.push(
@@ -268886,7 +268902,9 @@ function buildInstructions(args) {
   if (args.skillRef) {
     lines.push(`1. Read \`${args.skillRef}\` for the Hyperframes framework rules + house style. This is the visual-identity hard-gate.`);
   } else {
-    lines.push(`1. Run \`vibe scene install-skill\` to install the Hyperframes composition rules, then read them.`);
+    lines.push(
+      `1. Read this project's \`AGENTS.md\` section "Key Rules (for hand-authored scene HTML)" - written by \`vibe init\`, and the authoritative local contract. \`vibe scene install-skill\` adds Hyperframes' house style on top, but note it installs a ROUTER whose full contract sits behind \`/hyperframes-core\`, which resolves only in a host that has upstream's Hyperframes skills.`
+    );
   }
   lines.push(`2. Read \`DESIGN.md\` for project-specific palette, typography, motion signature.`);
   if (args.compositionRef) {
@@ -268896,6 +268914,7 @@ function buildInstructions(args) {
   lines.push(`3b. Use each beat's \`finalDurationSec\` (narration-synced) for \`data-duration\` and timeline anchors when present \u2014 NOT the storyboard \`duration\`, which is only the minimum. Scenes composed at the storyboard duration end early and render black tails.`);
   lines.push(`3c. Never give inner \`.clip\` elements a non-zero \`data-start\` \u2014 the renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render all phases at once (overlapping text). Use full-window clips and GSAP autoAlpha phase transitions instead. Also keep beats 6-15s; split anything longer in the storyboard first.`);
   lines.push(`3d. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
+  lines.push(`3e. Hard requirements the linter fails on, so satisfy them even without the full contract. A scene file is a \`<template id="scene-<id>-template">\` wrapping ONE \`<div data-composition-id="scene-<id>" data-start="0" data-duration="<sec>" data-width="1920" data-height="1080">\` \u2014 not a standalone \`<!doctype html>\` document. Register the paused GSAP timeline on the registry OBJECT keyed by composition id: \`window.__timelines = window.__timelines || {}; window.__timelines["scene-<id>"] = tl;\` \u2014 it is not an array, and \`.push()\` leaves the timeline undiscovered, which renders a black frame because \`gsap.from\` holds elements at their start state. Also put \`class="clip"\` on every timed element and give timeline-visible elements a stable \`id\`. Generate a reference scene with \`vibe scene add <id> --style <preset> --no-audio --no-image\` and match its shape.`);
   if (args.beatCount > 1) {
     lines.push(`4. After authoring all ${args.beatCount} beat(s), run \`vibe build <project> --stage sync --json\` to assemble the root composition (index.html) from the fragments. Lint needs that root, so sync comes first.`);
   } else if (args.filtered) {
@@ -269990,7 +270009,7 @@ async function executeSceneRender(opts = {}) {
       kind: "render",
       beat: opts.beatId ?? null,
       root: root2,
-      error: `Root composition not found: ${resolve33(projectDir, root2)}. Run \`vibe scene init\` first.`
+      error: `Root composition not found: ${resolve33(projectDir, root2)}. Run \`vibe build ${projectDir}\` once to create the render scaffold, or scaffold it up front with \`vibe init <dir> --profile full\`.`
     };
   }
   const chrome2 = await preflightChrome();
@@ -272240,7 +272259,7 @@ async function executeSceneBuild(opts) {
       phase: "failed",
       mode,
       selectedStage,
-      error: `STORYBOARD.md not found at ${storyboardPath}. Run \`vibe scene init <dir>\` to create a starter, or add STORYBOARD.md with per-beat cues.`,
+      error: `STORYBOARD.md not found at ${storyboardPath}. Run \`vibe init <dir>\` to create a starter, or add STORYBOARD.md with per-beat cues.`,
       beats: [],
       stageReports,
       warnings,
@@ -305085,7 +305104,7 @@ function insertClipIntoRoot(rootHtml, clip) {
   const closeMatch = rootHtml.match(/\n(\s*)<\/div>(\s*\n\s*<script>)/);
   if (!closeMatch) {
     throw new Error(
-      "Could not find root composition closing </div>. Ensure index.html follows the layout from `vibe scene init`."
+      "Could not find root composition closing </div>. Ensure index.html follows the layout from `vibe init`."
     );
   }
   const closeIdx = closeMatch.index;
@@ -305486,7 +305505,7 @@ sceneCommand.command("list-styles").description("List vendored visual styles (or
     console.log(source_default.dim("Show details: "), source_default.cyan('vibe scene list-styles "<name>"'));
     console.log(
       source_default.dim("Seed DESIGN.md:"),
-      source_default.cyan('vibe scene init <dir> --visual-style "<name>"')
+      source_default.cyan('vibe init <dir> --visual-style "<name>"')
     );
     return;
   }
@@ -305521,7 +305540,7 @@ sceneCommand.command("list-styles").description("List vendored visual styles (or
   console.log();
   console.log(
     source_default.dim("Seed DESIGN.md:"),
-    source_default.cyan(`vibe scene init <dir> --visual-style "${style.name}"`)
+    source_default.cyan(`vibe init <dir> --visual-style "${style.name}"`)
   );
 });
 sceneCommand.command("add").description("Add a new scene to a project: AI narration + image + per-scene HTML").argument("<name>", "Scene name (slugified into the composition id)").option("--style <preset>", `Style preset: ${SCENE_PRESETS.join(", ")}`, "simple").option(
@@ -305779,7 +305798,9 @@ async function executeSceneAdd(opts) {
     error
   });
   if (!await pathExists2(rootPath)) {
-    return errResult(`Root composition not found: ${rootPath}. Run \`vibe scene init\` first.`);
+    return errResult(
+      `Root composition not found: ${rootPath}. Run \`vibe build\` once to create the render scaffold, or scaffold it up front with \`vibe init <dir> --profile full\`.`
+    );
   }
   if (!opts.force && await pathExists2(scenePath)) {
     return errResult(`Scene already exists: ${sceneRel}. Re-run with --force to overwrite.`);
@@ -314669,13 +314690,15 @@ import { z as z17 } from "zod";
 var SCENE_WALKTHROUGH = `# Scene authoring with vibe
 
 A scene project is a directory that is **bilingual**: it works with both
-\`vibe\` and \`npx hyperframes\`. Each scene is one HTML file with scoped CSS
-and a paused GSAP timeline. Cheap to edit, cheap to lint, expensive only
+\`vibe\` and \`npx hyperframes\`. Scene composition is Hyperframes' job:
+each scene is one HTML file with scoped CSS and a paused GSAP timeline,
+authored to upstream's composition rules (install them with
+\`vibe scene install-skill\`). Cheap to edit, cheap to lint, expensive only
 at render.
 
-\`vibe build\` (v0.60+) is the supported one-shot driver from a
-written storyboard to an MP4. Plan H (v0.70) added \`--mode agent\` so the
-host agent itself authors the per-beat HTML \u2014 no internal LLM call.
+\`vibe build\` is the supported one-shot driver from a written storyboard
+to an MP4. The host agent authors the per-beat HTML - the CLI makes no
+internal LLM call.
 
 ## Three authoring paths
 
@@ -314690,20 +314713,20 @@ narration / backdrop intent.
 
 ## High-craft path
 
-1. \`vibe init my-promo --visual-style "Swiss Pulse"\` \u2014 seeds
+1. \`vibe init my-promo --visual-style "Swiss Pulse"\` - seeds
    \`DESIGN.md\` (palette, typography, motion, transitions) plus the
    \`vibe.config.json\` / \`hyperframes.json\` / \`index.html\` scaffold.
    It does **not** install the composition rules; if your agent does not
    already have the \`hyperframes\` skill, run
    \`vibe scene install-skill\` to fetch them from upstream into
    \`.agents/skills/hyperframes/\`.
-2. Read \`.agents/skills/hyperframes/SKILL.md\` (or your global copy) \u2014
+2. Read \`.agents/skills/hyperframes/SKILL.md\` (or your global copy) -
    framework rules, motion principles, type system, transition recipes.
-3. Read \`DESIGN.md\` \u2014 project-specific palette / typography / motion
+3. Read \`DESIGN.md\` - project-specific palette / typography / motion
    signature (visual identity hard-gate).
 4. Author each scene HTML directly under \`compositions/scene-<id>.html\`
    using the rules from steps 2 and 3. The skill enforces the visual
-   identity contract \u2014 scenes that contradict DESIGN.md fail lint.
+   identity contract - scenes that contradict DESIGN.md fail lint.
 5. \`vibe scene lint --fix\` for mechanical issues, \`vibe render my-promo\`
    to MP4.
 
@@ -314717,16 +314740,16 @@ vibe scene lint
 vibe render my-promo
 \`\`\`
 
-\`vibe init\` is **idempotent** \u2014 running it on an existing Hyperframes
+\`vibe init\` is **idempotent** - running it on an existing Hyperframes
 directory merges \`hyperframes.json\` instead of clobbering it. Safe to
 invoke on user-provided projects.
 
 ## Subcommands
 
 \`\`\`bash
-# Project flow (top-level \u2014 preferred entry points)
+# Project flow (top-level - preferred entry points)
 vibe init <dir> [-r 16:9|9:16|1:1|4:5] [-d <sec>] [--visual-style "<name>"]
-vibe build [<dir>] [--mode agent|batch|auto]         # H3 dispatch
+vibe build [<dir>] [--composer template]          # agent authors scenes by default
 vibe render [<dir>] [--fps 30] [--quality standard] [--format mp4]
 
 # Lower-level scene authoring
@@ -314739,11 +314762,11 @@ vibe scene lint [<root>] [--json] [--fix]
 
 ## Style presets (for \`vibe scene add --style\`)
 
-- **simple** \u2014 backdrop + bottom caption (default)
-- **announcement** \u2014 single huge headline, gradient text
-- **explainer** \u2014 kicker + title + subtitle stack
-- **kinetic-type** \u2014 words animate in word-by-word
-- **product-shot** \u2014 corner label + bottom headline + slow zoom
+- **simple** - backdrop + bottom caption (default)
+- **announcement** - single huge headline, gradient text
+- **explainer** - kicker + title + subtitle stack
+- **kinetic-type** - words animate in word-by-word
+- **product-shot** - corner label + bottom headline + slow zoom
 
 All presets accept \`--narration <text|file>\`, \`--visuals <prompt>\`,
 \`--headline\`, \`--kicker\`. With \`--narration\`, scene duration auto-derives
@@ -314753,21 +314776,19 @@ from the generated TTS audio.
 
 \`\`\`bash
 vibe init my-promo --visual-style "Swiss Pulse" -d 12
-# (edit STORYBOARD.md with per-beat YAML cues \u2014 narration, backdrop, duration)
+# (edit STORYBOARD.md with per-beat YAML cues - narration, backdrop, duration)
 vibe build my-promo
 \`\`\`
 
 \`vibe build\` reads the STORYBOARD frontmatter + per-beat cues,
 dispatches TTS + image-gen per beat, then either:
 
-- **\`--mode agent\`** (default when an agent host is detected) \u2014 emits a
-  \`needs-author\` plan via \`vibe scene compose-prompts\`. The host agent
-  authors each \`compositions/scene-<id>.html\` itself, then re-invoking
-  \`vibe build\` proceeds to lint + render.
-- **\`--mode batch\`** \u2014 VibeFrame runs an internal LLM (Claude / OpenAI /
-  Gemini) to compose the HTML, then renders.
-
-\`VIBE_BUILD_MODE\` env var overrides the auto-resolve.
+- **Agent authoring** (default) - emits a \`needs-author\` plan via
+  \`vibe scene compose-prompts\`. The host agent authors each
+  \`compositions/scene-<id>.html\` itself, then re-invoking \`vibe build\`
+  proceeds to lint + render. The CLI makes no internal LLM call.
+- **\`--composer template\`** - the deterministic no-model composer
+  (concat background + lower-thirds), for when no agent is available.
 
 ## Lint feedback loop
 
@@ -314777,7 +314798,7 @@ vibe scene lint --json --fix
 
 Returns structured findings. The recommended loop: 1) run lint with
 \`--fix\` (mechanical fixes applied), 2) if \`errorCount > 0\`, edit the
-scene HTML, 3) re-lint. Cap retries at 3 \u2014 if errors persist, fall back
+scene HTML, 3) re-lint. Cap retries at 3 - if errors persist, fall back
 to a template preset (\`vibe scene add <id> --style simple --force\`)
 and surface the error to the user.
 
@@ -314853,9 +314874,9 @@ The full set lives in \`packages/cli/src/pipeline/executor.ts\`.
 
 ## Variable references
 
-- \`$<step-id>.output\` \u2014 previous step's output path
-- \`$<step-id>.result.<field>\` \u2014 structured field from JSON result
-- \`\${ENV_VAR}\` \u2014 environment variable
+- \`$<step-id>.output\` - previous step's output path
+- \`$<step-id>.result.<field>\` - structured field from JSON result
+- \`\${ENV_VAR}\` - environment variable
 - Values can be templated: \`"\${SCRIPT_TITLE} - Episode \${EPISODE}"\`
 
 ## Running
@@ -314872,12 +314893,12 @@ Checkpoints land next to the YAML: \`pipeline.yaml.checkpoint.json\`.
 
 ## Authoring tips
 
-1. **Start from a tiny YAML** \u2014 keep it in your project directory and run
+1. **Start from a tiny YAML** - keep it in your project directory and run
    \`vibe run pipeline.yaml --dry-run\` before spending provider budget.
-2. **Dry-run first** \u2014 you see estimated cost and resolved variable
+2. **Dry-run first** - you see estimated cost and resolved variable
    graph before spending API credits.
 3. **Keep step ids short and descriptive** (\`intro\`, \`scene1\`, \`voice\`,
-   \`bgm\`) \u2014 they appear in logs and variable refs.
+   \`bgm\`) - they appear in logs and variable refs.
 4. **Name outputs** with extensions matching the action (\`.mp4\`, \`.mp3\`,
    \`.png\`, \`.json\`).
 5. **Declare \`budget:\`** on expensive pipelines:
@@ -314901,9 +314922,9 @@ When the user has a working shell sequence, extract steps:
 - Wrap the entire chain in a \`name:\` + \`steps:\` skeleton
 
 The \`compose\` action is the catch-all assembly step (audio mux, video
-overlay, etc.) \u2014 useful at the tail of a pipeline.
+overlay, etc.) - useful at the tail of a pipeline.
 `;
-var ARCHITECTURE_WALKTHROUGH = `# vibe agent / build / run \u2014 when to pick which
+var ARCHITECTURE_WALKTHROUGH = `# vibe agent / build / run - when to pick which
 
 The CLI has three orchestrating commands that coordinate other primitives:
 \`vibe agent\`, \`vibe build\`, \`vibe run\`. New users routinely ask which one
@@ -314932,14 +314953,14 @@ built-in fallback when you do not already have an agent host.
 - "I have a finished script + visual identity" \u2192 \`vibe build\`
 - "I want this to run again next month" \u2192 \`vibe run\`
 
-If two seem to fit, pick the rightmost one \u2014 more reproducible, less surprise.
+If two seem to fit, pick the rightmost one - more reproducible, less surprise.
 
 ## Cost-tier awareness (v0.83+)
 
 Every primitive subcommand carries a cost tier (\`free\` / \`low\` / \`high\` /
 \`very-high\`). \`vibe schema --list\` exposes the tier as JSON, and each
 \`vibe <group> <sub> --help\` page shows it as a colored footer. Use
-\`vibe doctor --test-keys\` before kicking off any high-cost orchestrator \u2014
+\`vibe doctor --test-keys\` before kicking off any high-cost orchestrator -
 a single bad key wastes time and money.
 
 ## Cross-command primitives
@@ -315049,7 +315070,7 @@ var META = {
     title: "YAML pipelines (Video as Code)",
     summary: "Author and run reproducible multi-step video workflows",
     steps: [
-      "Sketch the workflow as YAML \u2014 `name`, `description`, then `steps:` with `id` + `action` + inputs/outputs.",
+      "Sketch the workflow as YAML - `name`, `description`, then `steps:` with `id` + `action` + inputs/outputs.",
       "Reference previous step outputs via `$<step-id>.output` (or `$<step-id>.result.<field>` for structured returns).",
       "Run `vibe run pipeline.yaml --dry-run` to see the resolved graph + cost estimate before spending API budget.",
       "Add a `budget:` block (tokens / cost_usd / max_tool_errors) to cap expensive runs.",
@@ -316033,9 +316054,10 @@ function usage3(version2) {
   return [
     `VibeFrame MCP Server v${version2}`,
     "",
-    "AI-native video editing exposed over the Model Context Protocol (stdio).",
+    "AI video generation and editing exposed over the Model Context Protocol",
+    "(stdio), on your own provider keys and behind dry runs and cost caps.",
     "It is launched by an MCP client (Claude Desktop, Cursor, Claude Code), not",
-    "run directly \u2014 there is normally nothing to interact with on the terminal.",
+    "run directly - there is normally nothing to interact with on the terminal.",
     "",
     "Add it to your client config:",
     "",
@@ -316068,7 +316090,7 @@ function handleCliFlags(argv, version2) {
 }
 
 // src/index.ts
-if (handleCliFlags(process.argv.slice(2), "0.113.28")) {
+if (handleCliFlags(process.argv.slice(2), "0.113.30")) {
   process.exit(0);
 }
 console.log = (...args) => console.error(...args);
@@ -316081,7 +316103,7 @@ var server = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.113.28"
+    version: "0.113.30"
   },
   {
     capabilities: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.113.28",
-  "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
+  "version": "0.113.30",
+  "description": "VibeFrame MCP Server - frontier AI video generation for agents (Seedance, Runway, Veo, Kling) on your own keys, behind a hard cost cap",
   "type": "module",
   "bin": {
     "vibeframe-mcp": "./dist/index.js"
@@ -15,8 +15,14 @@
     "mcp",
     "model-context-protocol",
     "vibeframe",
-    "video-editing",
-    "ai",
+    "ai-video",
+    "video-generation",
+    "text-to-video",
+    "image-to-video",
+    "seedance",
+    "runway",
+    "veo",
+    "kling",
     "claude-desktop",
     "cursor"
   ],
@@ -30,7 +36,7 @@
   "bugs": {
     "url": "https://github.com/vericontext/vibeframe/issues"
   },
-  "homepage": "https://github.com/vericontext/vibeframe#mcp-integration",
+  "homepage": "https://vibeframe.ai",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.22.4"
@@ -60,8 +66,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/core": "0.113.28",
-    "@vibeframe/cli": "0.113.28"
+    "@vibeframe/core": "0.113.30",
+    "@vibeframe/cli": "0.113.30"
   },
   "engines": {
     "node": ">=20"