@vibeframe/cli 0.113.26 → 0.113.28

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

@@ -122,4 +122,11 @@ export interface CreateBuildPlanOptions {
  * (e.g. 7 beats quoted as ~$21 when the real cost is ~$0.35–1.40).
  */
 export declare function backdropCostUsd(quality: "standard" | "hd"): number;
+/**
+ * Per-beat narration cost by resolved TTS provider. Kokoro runs locally and
+ * costs $0 — a flat per-narration charge here is what made zero-key builds
+ * report phantom spend. Shared by the dry-run estimate and the post-build
+ * actuals so the two can never disagree.
+ */
+export declare function narrationCostUsd(provider: string | undefined): number;
 export declare function createBuildPlan(opts: CreateBuildPlanOptions): Promise<BuildPlanResult>;

package/dist/commands/_shared/compose-beat-prompt.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module _shared/compose-beat-prompt
+ *
+ * Per-beat authoring contract handed to the HOST agent. `getComposePrompts()`
+ * (and therefore `vibe scene compose-prompts` / `scene_compose_prompts`) uses
+ * this to describe exactly what one `compositions/scene-<id>.html` fragment
+ * must contain: the bare `<template>` shape, the paused GSAP timeline anchored
+ * to the full beat duration, full-window `.clip` rules, and which generated
+ * assets to reference.
+ *
+ * These rules were written against the Hyperframes sub-composition contract
+ * and every one of them encodes a render bug we hit: black holds from a short
+ * timeline, stacked text from non-zero `data-start` phase clips, shimmer from
+ * transforms on text ancestors.
+ */
+import type { Beat } from "./storyboard-parse.js";
+import type { SceneTranscriptWord } from "./scene-html-emit.js";
+/** The slice of beat context the prompt builder needs. */
+export interface ComposeBeatPromptContext {
+    beat: Beat;
+    storyboardGlobal: string;
+    retryFeedback?: string;
+    finalDurationSec?: number;
+    transcript?: SceneTranscriptWord[];
+}
+/**
+ * Word-level timing entries above this count are downgraded to coarse,
+ * phrase-level anchors in the prompt. A token-budget guard: a 60s narration
+ * can exceed 150 words, and inlining every `[start, "word"]` pair bloats the
+ * prompt (and the cache key) for little composer benefit past a point.
+ */
+export declare const TRANSCRIPT_PROMPT_MAX_WORDS = 120;
+/**
+ * Render narration word timings as a compact, deterministic prompt section.
+ * Token-budget guard (the `oversized` case is the reason this is a function,
+ * not an inline template):
+ *   - no transcript → `""` (section omitted entirely; prompt unchanged).
+ *   - ≤ {@link TRANSCRIPT_PROMPT_MAX_WORDS} → full word-level `[start, "word"]`
+ *     table the composer can map 1:1 to GSAP reveals.
+ *   - more → group into ~`MAX/2` phrase anchors (start time of each phrase),
+ *     tagged "approximate" so the composer paces reveals across the beat
+ *     rather than over-trusting per-word truth.
+ * Pure and stable for a given input → the compose cache stays consistent.
+ */
+export declare function formatTranscriptSection(transcript: SceneTranscriptWord[] | undefined, maxWords?: number): string;
+/** Build the user prompt — instructions + storyboard global + beat body. */
+export declare function buildUserPrompt(ctx: ComposeBeatPromptContext): string;

package/dist/commands/_shared/compose-prompts.d.ts

@@ -13,7 +13,7 @@
  *     "projectDir": "<abs>",
  *     "designReference":     "DESIGN.md",
  *     "storyboardReference": "STORYBOARD.md",
- *     "skillReference":      "SKILL.md",        // present after `scene install-skill`
+ *     "skillReference":      ".agents/skills/hyperframes/SKILL.md",
  *     "compositionsDir":     "compositions",
  *     "beats": [
  *       { "id": "hook", "outputPath": "compositions/scene-hook.html",
@@ -22,14 +22,14 @@
  *     "instructions": [...]
  *   }
  *
- * Pairs with H1 (`vibe scene install-skill`) — the host agent reads
- * `SKILL.md` for framework rules, `DESIGN.md` for visual identity, then
+ * Pairs with `vibe scene install-skill` — the host agent reads the
+ * Hyperframes rules, `DESIGN.md` for visual identity, then
  * writes each `compositions/scene-<id>.html`. After authoring, runs
- * `vibe scene lint --fix` to verify and `vibe render` to produce MP4.
+ * `vibe build <project> --stage sync` to assemble the root composition,
+ * `vibe scene lint <project> --fix` to verify, and `vibe render` for MP4.
  *
- * The internal-LLM path (`vibe scene build`, PR #176) still works — it's
- * the batch / non-agent fallback. H3 will add mode dispatch so a single
- * entry point picks between agentic and batch depending on context.
+ * This is the only model-authored compose path: the host agent writes each
+ * file. `--composer template` is the deterministic alternative.
  */
 export interface ComposePromptsBeat {
     /** Stable beat id from `parseStoryboard().deriveBeatId()`. */
@@ -54,7 +54,7 @@ export interface ComposePromptsBeat {
     /**
      * Pre-built user prompt — the same shape `composeBeatHtml` would send to
      * Claude / OpenAI / Gemini. The host agent consumes this directly so the
-     * agentic and batch paths produce equivalent HTML.
+     * the host agent and the template composer produce equivalent structure.
      */
     userPrompt: string;
     /**
@@ -95,8 +95,6 @@ export interface ComposePromptsResult {
     beats: ComposePromptsBeat[];
     /** Step-by-step instructions for the host agent. */
     instructions: string[];
-    /** Hyperframes bundle version — informational; ties cache keys back to the internal-LLM path. */
-    bundleVersion: string;
     /** Non-fatal hints surfaced to the agent (e.g. missing SKILL.md). */
     warnings: string[];
     /** Set when {@link success} is false. */

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## 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 \u2014 `vibe init` does **not** copy it into the project.\n- Otherwise `vibe init` writes a local copy: universal `SKILL.md` (with\n  `references/*.md`) at the project root, plus host layouts\n  (`.claude/skills/hyperframes/`, `.cursor/rules/hyperframes.mdc`).\n\nTo get editable per-project copies on demand, run\n`vibe scene install-skill [--host all]` (these copies are gitignored by\ndefault \u2014 see `.gitignore`).\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) \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";
 /**
  * Claude Code project file. Imports AGENTS.md so guidance stays
  * single-sourced; adds Claude-specific overrides (slash commands, etc.).
@@ -47,7 +47,7 @@ export interface EnvExampleOptions {
  */
 export declare function renderEnvExample(opts?: EnvExampleOptions): string;
 /** Lines vibe init merges into the project's .gitignore (idempotent). */
-export declare const GITIGNORE_ADDITIONS = "\n# VibeFrame\n.env\n.env.local\nrenders/\n.pipeline-state.yaml\n*.vibe.json\n.vibeframe/\n\n# Vendored Hyperframes skill copies \u2014 regenerable via 'vibe scene install-skill'.\n# Delete these lines if you eject and want to commit per-project customizations.\n/SKILL.md\n/references/\n/.claude/skills/hyperframes/\n/.cursor/rules/hyperframes.mdc\n";
+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

package/dist/commands/_shared/install-skill.d.ts

@@ -1,117 +1,94 @@
 /**
  * @module _shared/install-skill
  *
- * Phase H1 — install the vendored Hyperframes skill bundle into a user's
- * scene project so that the host agent (Claude Code, Cursor, Codex, Aider,
- * etc.) can read the framework rules + house style directly. This is the
- * agentic-CLI-native pattern: the host agent is the sole LLM that reasons
- * about scene composition, and it does so with the skill files in its
- * context — VibeFrame's CLI is the deterministic toolbelt.
+ * Put the Hyperframes composition rules where the host agent will read them,
+ * by running upstream's own installer instead of shipping a copy.
  *
- * Layout written:
+ * VibeFrame used to vendor a snapshot of Hyperframes' skill markdown and write
+ * it into each project under hand-maintained per-host layouts (project-root
+ * `SKILL.md` + `references/`, `.claude/skills/hyperframes/`,
+ * `.cursor/rules/hyperframes.mdc`). That snapshot went stale - upstream has
+ * since restructured the skill into a router plus a `references/` tree and
+ * ships 31 skills, none of which a frozen copy can follow - and the two host
+ * layouts covered a fraction of what upstream's installer reaches.
  *
- *   <project>/
- *     SKILL.md                              # universal — all agents see this
- *     references/
- *       house-style.md
- *       motion-principles.md
- *       typography.md
- *       transitions.md
- *     .claude/skills/hyperframes/           # if hosts includes "claude-code"
- *       SKILL.md (copy)
- *       references/{house-style,...}.md
- *     .cursor/rules/hyperframes.mdc         # if hosts includes "cursor"
+ *   npx skills add heygen-com/hyperframes -s hyperframes -y
  *
- * Codex + Aider are AGENTS.md-driven hosts; they discover the project-root
- * SKILL.md because AGENTS.md points at it in prose (the init-templates
- * AGENTS_MD "Composition rules" section, not an `@`-import).
+ * installs to `.agents/skills/hyperframes/`, serves ~19 agents universally
+ * (Amp, Antigravity, Cline, Codex, and more), symlinks the ones that want
+ * their own directory (Claude Code, Eve), and records the result in
+ * `skills-lock.json`. The generated `AGENTS.md` has pointed users at this
+ * command for a while; now the code agrees with the docs.
  *
- * The content is byte-identical to what `loadHyperframesSkillBundle()`
- * uses — same vendored files, same `BUNDLE_VERSION`. Build/render never read
- * these project files (they use the vendored bundle); they exist only so host
- * agents can read the rules and so users can edit them per project.
- *
- * Lean scaffolds: the automatic `vibe init` path passes `lean: true`, so when
- * the Hyperframes skill is already installed globally
- * (`hasGlobalHyperframesSkill()`) it skips the redundant copies — the
- * `.claude/skills/hyperframes/` copy always, and the root `SKILL.md` +
- * `references/` unless a root-reading host (codex/aider/gemini/opencode) needs
- * them. Explicit `vibe scene install-skill` omits `lean`, fully materializing
- * editable copies regardless (the "eject").
+ * Nothing in build or render reads these files. They exist so the host agent
+ * can read the rules while it authors scene HTML.
  */
-import type { AgentHostId } from "../../utils/agent-host-detect.js";
+/** Upstream repository the `skills` CLI installs from. */
+export declare const HYPERFRAMES_SKILL_PACKAGE = "heygen-com/hyperframes";
+/** The command a user can run by hand to get the same result. */
+export declare const HYPERFRAMES_SKILL_INSTALL_COMMAND = "npx skills add heygen-com/hyperframes";
+/** Where upstream's installer puts the skill inside a project. */
+export declare const PROJECT_SKILL_PATH: string;
 /**
  * True when the Hyperframes skill is installed at the user's global Claude
- * skills dir (`~/.claude/skills/hyperframes/`). When present, materializing the
- * skill into a project is redundant — the host agent already loads it globally —
- * so `vibe init` keeps the scaffold lean and skips the copies. Explicit
- * `vibe scene install-skill` ignores this (it's the opt-in "eject" path).
+ * skills dir (`~/.claude/skills/hyperframes/`). A host agent already loads it
+ * from there, so installing into the project is redundant.
  */
 export declare function hasGlobalHyperframesSkill(): boolean;
-/** Hosts the install-skill command knows file layouts for. */
-export type InstallSkillHost = "claude-code" | "cursor" | "all";
+/** True when upstream's installer has already run in this project. */
+export declare function hasProjectHyperframesSkill(projectDir: string): boolean;
+/**
+ * Project-relative path to the composition rules a host agent should read, or
+ * `null` when neither the project nor the global install has them.
+ *
+ * The bare root `SKILL.md` is still honoured: projects scaffolded before the
+ * switch to upstream's installer have one, and it should keep working.
+ */
+export declare function resolveSkillReference(projectDir: string): string | null;
+/**
+ * True when the host agent can read the Hyperframes rules from anywhere -
+ * this project or the user's global skills dir. Callers that only need to
+ * decide whether to nag should use this rather than
+ * {@link resolveSkillReference}, which is about the in-project path and is
+ * null for a global-only install.
+ */
+export declare function hyperframesSkillAvailable(projectDir: string): boolean;
+export type InstallSkillStatus = "installed" | "already-installed" | "would-install" | "failed";
 export interface InstallSkillOptions {
-    /** Project directory (must exist or be creatable). */
+    /** Project to install into. The installer runs with this as its cwd. */
     projectDir: string;
-    /**
-     * Hosts to install host-specific copies for. The universal `SKILL.md` +
-     * `references/` directory at the project root are always written.
-     * Pass `["all"]` to install every host-specific layout.
-     */
-    hosts: InstallSkillHost[];
-    /** Overwrite existing files. Default false (skip-on-exist). */
+    /** Install at user level (`~/.claude/skills/...`) rather than per project. */
+    global?: boolean;
+    /** Reinstall even when the skill is already present. */
     force?: boolean;
-    /** Don't write — just describe what would happen. */
+    /** Report the command without running it. */
     dryRun?: boolean;
     /**
-     * Opt into redundancy gating: skip copies the globally-installed Hyperframes
-     * skill already provides. The automatic `vibe init` path sets this so the
-     * scaffold stays lean; the explicit `vibe scene install-skill` path leaves it
-     * false to fully materialize editable copies (the "eject"). Default false.
-     */
-    lean?: boolean;
-    /**
-     * Caller signals a root-reading host (codex / aider / gemini / opencode) is
-     * present, so the root `SKILL.md` + `references/` must be written even when
-     * the global Claude skill exists. Default false. Only consulted when `lean`.
-     */
-    rootReaderHostPresent?: boolean;
-    /**
-     * Override the global-skill probe (testing seam). Defaults to
-     * {@link hasGlobalHyperframesSkill}. Only consulted when `lean`.
+     * Override the global-skill probe. Testing seam - a developer machine that
+     * already has the skill would otherwise short-circuit every install.
      */
     hasGlobalSkill?: boolean;
 }
-export type InstallSkillFileStatus = "wrote" | "skipped-exists" | "would-write" | "would-skip-exists";
-export interface InstallSkillFileAction {
-    path: string;
-    status: InstallSkillFileStatus;
-    bytes: number;
-}
 export interface InstallSkillResult {
     success: boolean;
-    bundleVersion: string;
-    files: InstallSkillFileAction[];
+    status: InstallSkillStatus;
+    /** The exact command run (or that would run). */
+    command: string;
+    /** Project-relative path to the installed rules, when they are present. */
+    skillPath: string | null;
+    /** Installer output, trimmed. Present on a real run. */
+    output?: string;
+    error?: string;
+    retryWith?: string[];
 }
+/** Build the argv for upstream's installer. Pure - unit-testable. */
+export declare function buildInstallSkillArgs(opts?: {
+    global?: boolean;
+}): string[];
 /**
- * Map an `AgentHostId[]` to whether a root-reading host is present. Codex,
- * Aider, Gemini, and OpenCode read the project-root `SKILL.md` via AGENTS.md
- * prose — they have no global-skill mechanism, so the root files must be
- * written for them even when the global Claude skill exists.
- */
-export declare function deriveRootReaderPresent(detected: AgentHostId[]): boolean;
-/**
- * Install Hyperframes skill files at the project + host-specific paths.
+ * Run upstream's installer for the Hyperframes skill.
  *
- * Idempotent by default — existing files are skipped (logged as
- * `skipped-exists`). Pass `force: true` to overwrite. `dryRun: true`
- * reports the same actions but with `would-*` status and writes nothing.
+ * Skips when the skill is already available (globally or in the project)
+ * unless `force` is set, so calling it twice costs nothing.
  */
 export declare function installHyperframesSkill(opts: InstallSkillOptions): Promise<InstallSkillResult>;
-/**
- * Map an `AgentHostId[]` (from `detectedAgentHosts()`) to the
- * install-skill command's host vocabulary. Codex / Aider don't get
- * host-specific layouts — they read the universal `SKILL.md` via
- * AGENTS.md, so they're filtered out here.
- */
-export declare function deriveInstallHosts(detected: AgentHostId[]): InstallSkillHost[];

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

@@ -1,4 +1,19 @@
 export type SceneBuildMode = "agent" | "batch" | "auto";
+/**
+ * Resolve which compose path a build takes.
+ *
+ * `agent` is the only LLM-authored path VibeFrame ships: the host's agent
+ * writes each `compositions/scene-<id>.html` and the CLI lints, syncs, and
+ * renders around it. `batch` now means one thing - the deterministic
+ * `--composer template` path, which authors HTML without any model.
+ *
+ * The mode used to also select a CLI-internal LLM composer that called
+ * Claude/OpenAI/Gemini directly. That path is gone: the host agent is the
+ * outer loop, and duplicating its job inside the CLI meant carrying a stale
+ * copy of upstream's authoring skill and demanding an extra API key.
+ * `VIBE_BUILD_MODE=batch` therefore no longer forces a model-authored build;
+ * without `--composer template` it resolves to `agent`.
+ */
 export declare function resolveSceneBuildMode(opts: {
     mode?: SceneBuildMode;
 }): "agent" | "batch";

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

@@ -19,7 +19,6 @@
  *     already have one with sub-composition references.
  */
 import { type ImageOptions } from "@vibeframe/ai-providers";
-import { type ComposeEffort, type ComposeProgressEvent, type ComposeScenesActionResult } from "./compose-scenes-skills.js";
 import type { ComposerProvider } from "./composer-resolve.js";
 import { type ComposePromptsBeat } from "./compose-prompts.js";
 import { type SceneRenderResult } from "./scene-render.js";
@@ -155,7 +154,7 @@ export type SceneBuildProgressEvent = {
     type: "music-skipped";
     beatId: string;
     reason: string;
-} | ComposeProgressEvent | {
+} | {
     type: "render-start";
 } | {
     type: "render-done";
@@ -240,8 +239,6 @@ export interface SceneBuildOptions {
      * Build mode dispatch. See {@link SceneBuildMode}. Default: `auto`.
      */
     mode?: SceneBuildMode;
-    /** Compose effort tier — passed through to `compose-scenes-with-skills`. */
-    effort?: ComposeEffort;
     /**
      * Composer LLM provider. Defaults to whatever `resolveComposer()` picks
      * based on env keys (claude > gemini > openai). Pass an explicit value
@@ -343,7 +340,6 @@ export interface SceneBuildResult {
     beats: BeatBuildOutcome[];
     /** MP4 path when `skipRender` is false and render succeeded. */
     outputPath?: string;
-    composeData?: ComposeScenesActionResult["data"];
     renderResult?: SceneRenderResult;
     /**
      * Populated only in agent mode when {@link phase} === `"needs-author"`.
@@ -358,7 +354,6 @@ export interface SceneBuildResult {
         compositionsDir: string;
         instructions: string[];
         beats: ComposePromptsBeat[];
-        bundleVersion: string;
         warnings: string[];
     };
     selectedStage?: BuildStage;
@@ -463,7 +458,6 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
             path: string;
             exists: boolean;
             status: BuildReportCompositionStatus;
-            cacheKey?: string;
         };
         narrationPath: string | undefined;
         narrationDurationSec: number | undefined;
@@ -505,4 +499,4 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
     retryWith: string[];
     totalLatencyMs: number;
 };
-type BuildReportCompositionStatus = "generated" | "cached" | "exists" | "needs-author" | "skipped" | "failed";
+type BuildReportCompositionStatus = "exists" | "needs-author" | "skipped" | "failed";

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

@@ -137,3 +137,26 @@ export declare function runProjectLint(opts: RunProjectLintOptions): Promise<Pro
 /** True if `root` exists and is a regular file. Used by callers that want to
  *  pre-validate before invoking `runProjectLint`. */
 export declare function rootExists(projectDir: string, rootRel?: string): Promise<boolean>;
+export interface BeatLintResult {
+    errorCount: number;
+    warningCount: number;
+    findings: LintFinding[];
+}
+/**
+ * Lint one beat's HTML in memory, with no temp project shell and no
+ * subprocess. Sub-composition false positives are filtered the same way
+ * `vibe scene lint` filters them, so an agent submitting a beat sees the
+ * findings it would see after the file landed in the project.
+ */
+export declare function lintBeatHtml(html: string, beatId: string): Promise<BeatLintResult>;
+/** Thrown when a submission carries no recoverable HTML. */
+export declare class BeatHtmlError extends Error {
+    readonly code: "no-html-in-response";
+    constructor(code: "no-html-in-response", message: string);
+}
+/**
+ * Pull the HTML fragment out of an agent's reply. Prefers a fenced ```html
+ * block and accepts a bare fragment, since hosts often skip the fence when
+ * the whole reply is the document.
+ */
+export declare function extractHtml(responseText: string): string;

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

@@ -12,7 +12,7 @@
  * tool and the C5 `--format scenes` pipeline can call it the same way. It
  * returns a structured result instead of throwing or exiting.
  */
-import { type RenderConfig } from "@hyperframes/producer";
+import { type RenderConfigInput } from "@hyperframes/producer";
 import { type SceneAspect } from "./scene-project.js";
 export type RenderFps = 24 | 30 | 60;
 export type RenderQuality = "draft" | "standard" | "high";
@@ -105,8 +105,14 @@ export declare function defaultOutputPath(opts: {
     now?: Date;
 }): string;
 /**
- * Build the producer's `RenderConfig` from caller options. Pure — useful for
+ * Build the producer's render config from caller options. Pure - useful for
  * unit tests that want to assert defaults without touching Chrome.
+ *
+ * Returns `RenderConfigInput` (not `RenderConfig`) so `fps` stays an integer:
+ * the producer models fps as a rational `{num, den}` internally but accepts a
+ * plain number on the way in. The intersection pins `fps`/`format` to our
+ * narrower unions so callers keep arithmetic on fps and never see the
+ * producer-only formats (`gif`, `png-sequence`) VibeFrame does not expose.
  */
 export declare function buildRenderConfig(opts: {
     fps?: RenderFps;
@@ -114,7 +120,10 @@ export declare function buildRenderConfig(opts: {
     format?: RenderFormat;
     workers?: number;
     entryFile?: string;
-}): RenderConfig;
+}): RenderConfigInput & {
+    fps: RenderFps;
+    format: RenderFormat;
+};
 export declare function buildMediaOpenCommand(action: RenderOpenAction, filePath: string, platform?: NodeJS.Platform): MediaOpenCommand;
 /**
  * Render a scene project. Mirrors the contract of the existing Hyperframes

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

@@ -12,7 +12,7 @@
  * a terminal) gets the same step-by-step authoring guide that the
  * slash commands deliver in Claude Code. The content is vendored as
  * TS template-literal strings so the CLI binary ships with zero
- * filesystem dependencies — same approach as `hf-skill-bundle`.
+ * filesystem dependencies.
  *
  * Source of truth lives here. The Claude Code slash command files
  * under `.claude/skills/vibe-{scene,pipeline}/SKILL.md` mirror this