@vibeframe/cli 0.113.11 → 0.113.26

package/CONTEXT.md

@@ -5,8 +5,9 @@
 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.
+For long-running video work, your host's agent loop (Claude Code, Codex,
+Cursor, or another coding-agent host) 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.
 
@@ -15,21 +16,21 @@ For the full reference (every flag, default, enum), read
 from `vibe schema --list`. This file is the _agent quickstart_: rules,
 conventions, and discovery hooks.
 
-## Native host goal loop
+## Host agent loop
 
-Use the host's native goal feature rather than inventing a VibeFrame-owned
-goal runner. The canonical loop is:
+Use your host's agent loop as the outer loop rather than inventing a
+VibeFrame-owned loop. The canonical loop is:
 
 ```text
-native host goal -> vibe context/schema -> plan dry-run -> build with budget
+host agent loop -> 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:
+Copy-paste agent prompt (Codex) — a plain prompt, not a built-in command:
 
 ```text
-/goal Build my-video/ into a reviewed VibeFrame MP4. Use --json for every vibe
+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
@@ -43,10 +44,10 @@ AI review score is >= 90 when AI review is requested, and unresolved host-agent
 accepted with a written reason, or reported as blocked.
 ```
 
-Copy-paste Claude Code goal:
+Copy-paste agent prompt (Claude Code) — a plain prompt, not a built-in command:
 
 ```text
-/goal Finish the VibeFrame render for my-video/ using Claude Code goal mode as
+Finish the VibeFrame render for my-video/ using your host's agent loop 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.
@@ -223,7 +224,7 @@ Review report contract:
 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
+The outer loop should not stop while `host-agent` issues remain unless
 they are fixed, intentionally accepted with a written reason, or reported as
 blocked.
 

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

@@ -2,7 +2,7 @@ import { type BuildAssetKind } from "./build-cache.js";
 import { type AssetFreshness } from "./build-asset-metadata.js";
 import { type LoadedProjectConfig } from "./project-config.js";
 import { type StoryboardValidationIssue } from "./storyboard-edit.js";
-export type BuildStage = "assets" | "compose" | "sync" | "render" | "all";
+export type BuildStage = "assets" | "transcript" | "compose" | "sync" | "render" | "all";
 export type BuildPlanStatus = "ready" | "invalid";
 export type AssetPlanReason = "canonical-exists" | "canonical-stale" | "canonical-unknown" | "content-cache-hit" | "force" | "missing" | "referenced-asset" | "invalid-reference" | "stage-skipped";
 export type ProviderResolutionKind = BuildAssetKind | "composer";

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

@@ -0,0 +1,82 @@
+import { type Beat } from "./storyboard-parse.js";
+export interface AiVideoDesignTokens {
+    /** Headline + body text colour. */
+    primary: string;
+    /** Scrim / fade-to ground colour. */
+    ground: string;
+    /** Eyebrow rule + single accent. */
+    accent: string;
+    /** Headline / eyebrow font-family. */
+    headFont: string;
+    /** Sub-line (italic) font-family. */
+    bodyFont: string;
+}
+export declare const DEFAULT_AIVIDEO_TOKENS: AiVideoDesignTokens;
+/** Per-scene overlay copy derived from a beat heading + optional cues. */
+export interface OverlayText {
+    kicker: string;
+    title: string;
+    sub: string;
+}
+/**
+ * Derive the lower-third copy for a beat. Authors override deterministically via
+ * `eyebrow`/`title`/`caption` cues; otherwise it falls back to the heading.
+ */
+export declare function beatOverlayText(beat: Beat): OverlayText;
+/**
+ * ffmpeg args to concat clips into one uniform background video. Each input is
+ * scaled+cropped to fill {width}x{height} at {fps}, then concatenated (no
+ * audio — narration rides a separate track).
+ */
+export declare function buildBgConcatArgs(clipPaths: string[], outPath: string, opts?: {
+    width?: number;
+    height?: number;
+    fps?: number;
+    crf?: number;
+}): string[];
+/**
+ * A transparent lower-third overlay scene. The root background video shows
+ * through; a bottom scrim keeps text legible. Entrances only (the producer
+ * cuts on `data-duration`); the final scene fades to ground.
+ */
+export declare function emitOverlayScene(opts: {
+    id: string;
+    text: OverlayText;
+    duration: number;
+    tokens?: AiVideoDesignTokens;
+    isLast?: boolean;
+}): string;
+/**
+ * Insert the single background `<video>` into `#root` (idempotent). Custom and
+ * managed elements are otherwise untouched; the bg video carries no
+ * `class="clip"`, so it is not subject to same-track clip scheduling and sits
+ * behind the scene overlays via `z-index`.
+ */
+export declare function injectBgVideo(indexHtml: string, src: string, totalDuration: number): string;
+export interface ComposeAiVideoResult {
+    bgVideoRel: string;
+    sceneFiles: string[];
+    totalDurationSec: number;
+    beats: number;
+}
+/**
+ * Orchestrate the deterministic compose: concat clips → bg-full.mp4, emit
+ * transparent overlay scenes, inject the bg video into index.html. Caller runs
+ * `root-sync` afterward to wire scene clip refs + narration.
+ */
+export declare function composeAiVideo(opts: {
+    projectDir: string;
+    tokens?: AiVideoDesignTokens;
+    /** Resolve the clip path for a beat (defaults to `assets/video-<id>.mp4`). */
+    clipRelFor?: (beat: Beat) => string;
+}): Promise<ComposeAiVideoResult>;
+/** Minimal root composition shell carrying the single bg video. The sync stage
+ * adds the `<!-- vibe-scene-build -->` block (scene clip refs + narration). */
+export declare function buildRootShell(tokens: AiVideoDesignTokens, bgRel: string, totalDuration: number): string;
+/**
+ * Map a DESIGN.md to background-video tokens. Named color tokens (front-matter
+ * `colors: { primary, ground, accent }` or descriptive keys) win; otherwise the
+ * palette is read by luminance (darkest → ground, lightest → primary) and the
+ * most-saturated remaining color becomes the accent.
+ */
+export declare function extractDesignTokens(designMd: string): AiVideoDesignTokens;

package/dist/commands/_shared/compose-aivideo.test.d.ts

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

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

@@ -73,6 +73,14 @@ export interface ComposePromptsResult {
     projectDir: string;
     /** Project-root-relative path to DESIGN.md (always "DESIGN.md"). */
     designReference: string;
+    /**
+     * Project-root-relative path to the optional COMPOSITION.md structural
+     * contract (`"COMPOSITION.md"`), or `null` when the project doesn't have one.
+     * Parallel to {@link designReference}: DESIGN.md is the visual hard-gate,
+     * COMPOSITION.md is the structural hard-gate (layout system, GSAP timeline
+     * conventions, element/track rules). The host agent must honor it when present.
+     */
+    compositionReference: string | null;
     /** Project-root-relative path to STORYBOARD.md (always "STORYBOARD.md"). */
     storyboardReference: string;
     /**

package/dist/commands/_shared/compose-scenes-skills.d.ts

@@ -25,6 +25,8 @@
  * Lint feedback retry loop comes in C4 (extends this module).
  */
 import { type LintFinding } from "./scene-lint.js";
+/** Resolve the compose fan-out limit (env override, clamped to the beat count). */
+export declare function composeConcurrency(beatCount: number): number;
 import { type Beat } from "./storyboard-parse.js";
 import { type ComposerProvider } from "./composer-resolve.js";
 import type { SceneTranscriptWord } from "./scene-html-emit.js";
@@ -35,6 +37,13 @@ export interface ComposeBeatContext {
     beat: Beat;
     /** Project's `DESIGN.md` content (visual identity hard-gate). */
     designMd: string;
+    /**
+     * Optional `COMPOSITION.md` content — the per-project STRUCTURAL contract
+     * (layout system, GSAP timeline conventions, element/track rules), parallel
+     * to DESIGN.md's visual contract. Injected into the system prompt as a
+     * hard-gate when present.
+     */
+    compositionMd?: string;
     /** Storyboard's global direction (everything before the first `## Beat`). */
     storyboardGlobal: string;
     /** Hyperframes skill bundle content + hash, from `loadHyperframesSkillBundle()`. */
@@ -101,8 +110,8 @@ export interface ComposeBeatResult {
     /** Composer provider that produced this beat. */
     provider: ComposerProvider;
 }
-/** Build the system prompt — skill bundle + DESIGN.md hard-gate. */
-export declare function buildSystemPrompt(ctx: Pick<ComposeBeatContext, "skillBundle" | "designMd">): string;
+/** Build the system prompt — skill bundle + DESIGN.md hard-gate (+ optional COMPOSITION.md). */
+export declare function buildSystemPrompt(ctx: Pick<ComposeBeatContext, "skillBundle" | "designMd" | "compositionMd">): string;
 /**
  * Word-level timing entries above this count are downgraded to coarse,
  * phrase-level anchors in the prompt. A token-budget guard: a 60s narration
@@ -267,6 +276,11 @@ export type ComposeProgressEvent = {
 export interface ComposeScenesParams {
     /** Path to DESIGN.md, relative to project root. */
     design?: string;
+    /**
+     * Path to the optional COMPOSITION.md structural contract, relative to project
+     * root. Defaults to `COMPOSITION.md`; silently ignored when absent.
+     */
+    composition?: string;
     /** Path to STORYBOARD.md, relative to project root. */
     storyboard?: string;
     /** Scene project root, relative to outputDir. Defaults to outputDir. */

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

@@ -0,0 +1,26 @@
+export interface ParsedDesign {
+    /** `name:` from front-matter, if present. */
+    name?: string;
+    /** Color tokens — front-matter `colors:` map, else extracted from prose hexes. */
+    colors: Record<string, string>;
+    /** Typography tokens from front-matter `typography:` (shape left to the spec). */
+    typography: Record<string, unknown>;
+    /** `## ` section title → prose body (trimmed). */
+    sections: Record<string, string>;
+    /** Raw parsed front-matter object (`{}` when absent/invalid). */
+    frontmatter: Record<string, unknown>;
+    /** Original document. */
+    raw: string;
+}
+export declare function parseDesign(md: string): ParsedDesign;
+export interface DesignValidationIssue {
+    severity: "error" | "warning" | "info";
+    code: string;
+    message: string;
+}
+/**
+ * Lint a DESIGN.md for the soft contract: parseable front-matter, at least a
+ * couple of palette colors, and the core prose sections. Warnings/infos only —
+ * a thin DESIGN.md is valid, just less useful to the composer.
+ */
+export declare function validateDesignMarkdown(md: string): DesignValidationIssue[];

package/dist/commands/_shared/design-parse.test.d.ts

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

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

@@ -0,0 +1,30 @@
+/**
+ * @module _shared/frontmatter
+ *
+ * One canonical "YAML frontmatter + markdown body" splitter for all VibeFrame
+ * `.md` files. Previously each consumer (storyboard, design, install-skill)
+ * declared its own `/^---\n…\n---/` regex + `yaml.parse` — this consolidates
+ * them.
+ *
+ * The shape matches Google's Open Knowledge Format (OKF) and Mintlify: a leading
+ * `---` YAML block, then a free-form markdown body. VibeFrame project files
+ * (STORYBOARD.md, DESIGN.md, CHARACTERS.md, …) are OKF concept documents; docs/
+ * pages carry OKF/Mintlify frontmatter (`type`, `title`, `description`, `tags`).
+ */
+/** Leading `---\n…\n---` block. Anchored to the start of the (normalized) text. */
+export declare const FRONTMATTER_RE: RegExp;
+export interface ExtractedFrontmatter {
+    /** Parsed frontmatter map, or `null` when absent / invalid / not a map. */
+    data: Record<string, unknown> | null;
+    /** Markdown body after the frontmatter block (or the whole doc when absent). */
+    body: string;
+    /** The full document, CRLF-normalized to LF. */
+    raw: string;
+}
+/**
+ * Split a leading YAML frontmatter block from the markdown body. CRLF is
+ * normalized to LF. Returns `data: null` (freeform) when there is no leading
+ * block, the YAML is invalid, or it is not a plain object — callers decide
+ * whether that means `undefined` or `{}`.
+ */
+export declare function extractFrontmatter(md: string): ExtractedFrontmatter;

package/dist/commands/_shared/hf-skill-bundle/bundle.d.ts

@@ -45,8 +45,14 @@ export declare const BUNDLE_VERSION = "970367f-2026-04-25";
  *
  * Side-effect free except for the optional `~/.claude/skills/hyperframes/`
  * filesystem read.
+ *
+ * Async because the vendored snapshot content is loaded via a lazy
+ * `await import("./bundle-content.js")` (see {@link buildVendored}) so paths
+ * that never need it (agent-mode, template composer) don't pay to evaluate the
+ * ~52KB string. When an installed skill is present, the vendored content module
+ * is never imported at all.
  */
-export declare function loadHyperframesSkillBundle(): {
+export declare function loadHyperframesSkillBundle(): Promise<{
     content: string;
     /** "installed" (user has ~/.claude/skills/hyperframes/) or "vendored" (esbuild-inlined snapshot). */
     source: "installed" | "vendored";
@@ -54,4 +60,4 @@ export declare function loadHyperframesSkillBundle(): {
     hint: string;
     /** Stable hash of (BUNDLE_VERSION + content). Used as cache-key input. */
     hash: string;
-};
+}>;

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## 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";
+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";
 /**
  * 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";
+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";
 /**
  * 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

@@ -22,16 +22,32 @@
  *       references/{house-style,...}.md
  *     .cursor/rules/hyperframes.mdc         # if hosts includes "cursor"
  *
- * Codex + Aider are AGENTS.md-driven hosts; they read the project root
- * SKILL.md via an `@SKILL.md` reference in AGENTS.md (handled by the
- * init-templates AGENTS_MD section, not here).
+ * 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).
  *
  * The content is byte-identical to what `loadHyperframesSkillBundle()`
- * uses — same vendored files, same `BUNDLE_VERSION`. After install, the
- * agentic compose path (Phase H2) reads these files instead of the
- * vendored TS string constants, so users can edit them per project.
+ * 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").
  */
 import type { AgentHostId } from "../../utils/agent-host-detect.js";
+/**
+ * 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).
+ */
+export declare function hasGlobalHyperframesSkill(): boolean;
 /** Hosts the install-skill command knows file layouts for. */
 export type InstallSkillHost = "claude-code" | "cursor" | "all";
 export interface InstallSkillOptions {
@@ -47,6 +63,24 @@ export interface InstallSkillOptions {
     force?: boolean;
     /** Don't write — just describe what would happen. */
     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`.
+     */
+    hasGlobalSkill?: boolean;
 }
 export type InstallSkillFileStatus = "wrote" | "skipped-exists" | "would-write" | "would-skip-exists";
 export interface InstallSkillFileAction {
@@ -59,6 +93,13 @@ export interface InstallSkillResult {
     bundleVersion: string;
     files: InstallSkillFileAction[];
 }
+/**
+ * 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.
  *

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

@@ -1,4 +1,4 @@
-import type { SceneAspect } from "./scene-project.js";
+import type { SceneAspect, SceneKind } from "./scene-project.js";
 export declare const VIBE_CONFIG_FILENAME = "vibe.config.json";
 export declare const LEGACY_VIBE_PROJECT_FILENAME = "vibe.project.yaml";
 export type CompositionEngine = "hyperframes";
@@ -11,6 +11,8 @@ export interface VibeProjectConfigV1 {
     schemaVersion: "1";
     name: string;
     aspect: SceneAspect;
+    /** Project kind — drives which pipeline stages run + the default composer. */
+    kind: SceneKind;
     defaults: {
         sceneDurationSec: number;
         narrationPaddingSec: number;
@@ -49,12 +51,14 @@ export interface LoadedProjectConfig {
 export declare function defaultProjectConfig(opts: {
     name: string;
     aspect?: SceneAspect;
+    kind?: SceneKind;
     sceneDurationSec?: number;
 }): VibeProjectConfigV1;
 export declare function mergeProjectConfig(parsed: Partial<VibeProjectConfigV1> | null | undefined, fallback: VibeProjectConfigV1): VibeProjectConfigV1;
 export declare function projectConfigJson(opts: {
     name: string;
     aspect?: SceneAspect;
+    kind?: SceneKind;
     sceneDurationSec?: number;
 }): string;
 export declare function readProjectConfig(projectDir: string): Promise<LoadedProjectConfig>;

package/dist/commands/_shared/project-config.test.d.ts

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

package/dist/commands/_shared/root-sync.d.ts

@@ -22,6 +22,19 @@ export interface RootSyncPlan {
     nextHtml?: string;
     totalDurationSec?: number;
 }
+export interface ExpectedRootSync {
+    block: string;
+    totalDurationSec: number;
+    audioRefs: Array<{
+        beatId: string;
+        kind: "narration" | "music";
+        src: string;
+        start: number;
+        duration: number;
+        trackIndex: number;
+        volume?: number;
+    }>;
+}
 export declare function createRootSyncPlan(opts: {
     projectDir: string;
     beats: RootSyncBeatInput[];
@@ -58,3 +71,15 @@ export declare function resolveSyncedBeatDuration(opts: {
  * {@link loadProjectRootSyncBeats}.
  */
 export declare function resolveProjectBeatDurations(projectDir: string): Promise<Map<string, number>>;
+/**
+ * The managed `<!-- vibe-scene-build -->` block is the SINGLE source of scene
+ * clip refs + narration/music audio. Custom elements (e.g. a `bg-video`,
+ * overlay decorations) are left untouched.
+ *
+ * Fast path: one clean block and no stray managed refs → in-place replace (no
+ * churn). Otherwise (zero/duplicate blocks, or stray `scene-*`/`narration-*`/
+ * `music-*` refs from a hand-edited root) → strip every managed block AND every
+ * stray managed ref, then insert exactly one block. This makes the sync
+ * idempotent and structurally unable to double-wire narration audio.
+ */
+export declare function applyRootSyncHtml(html: string, expected: ExpectedRootSync): string;

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

@@ -0,0 +1,47 @@
+/**
+ * @module _shared/scene-assemble
+ *
+ * The audio-assemble stage: lay a scene project's `<audio>` elements onto an
+ * already-rendered (silent) video in one FFmpeg pass. The Hyperframes producer
+ * emits silent video — sub-composition `<audio>` elements are not captured — so
+ * we scan the project ourselves and mux them in with `-c:v copy` (no re-encode).
+ *
+ * Extracted from `executeSceneRender` so the mux is a first-class, independently
+ * runnable step: `vibe render --silent` emits silent video, `vibe assemble` adds
+ * the audio. The default `vibe render` still renders + assembles in one shot.
+ */
+import type { RenderFormat } from "./scene-render.js";
+export interface SceneAssembleOptions {
+    /** Project directory (the Hyperframes scene project). */
+    projectDir: string;
+    /** Root composition file relative to projectDir (default: "index.html"). */
+    root?: string;
+    /** The rendered (silent) video to mux audio into. Relative paths resolve against projectDir. */
+    videoPath: string;
+    format?: RenderFormat;
+    /**
+     * Known total video duration in seconds (e.g. `job.totalFrames / fps`). When
+     * omitted, it is ffprobed from {@link videoPath}; the mux uses it to cap audio.
+     */
+    videoDuration?: number;
+    onProgress?: (pct: number, stage: string) => void;
+}
+export interface SceneAssembleResult {
+    success: boolean;
+    /** Number of `<audio>` elements found across the project. */
+    audioCount: number;
+    /** True when at least one audio track was muxed into the video. */
+    audioMuxApplied: boolean;
+    /** Non-fatal warning when the mux failed or threw (video left untouched). */
+    audioMuxWarning?: string;
+    /** Absolute path to the (in-place-updated) video. */
+    outputPath: string;
+    /** Set when {@link success} is false (missing inputs). */
+    error?: string;
+}
+/**
+ * Scan the project's audio and mux it onto {@link SceneAssembleOptions.videoPath}
+ * in place. Best-effort on the mux itself: a scan/mux failure becomes a warning,
+ * not a hard error. Returns `success:false` only when a required input is missing.
+ */
+export declare function executeSceneAssemble(opts: SceneAssembleOptions): Promise<SceneAssembleResult>;

package/dist/commands/_shared/scene-assemble.test.d.ts

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

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

@@ -247,7 +247,7 @@ export interface SceneBuildOptions {
      * based on env keys (claude > gemini > openai). Pass an explicit value
      * to require that provider's key.
      */
-    composer?: ComposerProvider;
+    composer?: ComposerProvider | "template";
     skipNarration?: boolean;
     skipBackdrop?: boolean;
     skipRender?: boolean;
@@ -302,9 +302,9 @@ export interface SceneBuildOptions {
  *   - `failed` — primitives, compose, or render errored. {@link error}
  *     carries the message; {@link beats} reflects partial state.
  */
-export type SceneBuildPhase = "done" | "assets-only" | "pending-jobs" | "compose-only" | "sync-only" | "render-only" | "needs-author" | "failed";
+export type SceneBuildPhase = "done" | "assets-only" | "transcript-only" | "pending-jobs" | "compose-only" | "sync-only" | "render-only" | "needs-author" | "failed";
 export type BuildWorkflowStatus = "done" | "running" | "needs-author" | "failed" | "ready";
-export type BuildCurrentStage = "assets" | "compose" | "sync" | "render" | "done";
+export type BuildCurrentStage = "assets" | "transcript" | "compose" | "sync" | "render" | "done";
 export interface BuildBeatSummary {
     total: number;
     assetsReady: number;
@@ -353,6 +353,7 @@ export interface SceneBuildResult {
     composePrompts?: {
         skillReference: string | null;
         designReference: string;
+        compositionReference: string | null;
         storyboardReference: string;
         compositionsDir: string;
         instructions: string[];
@@ -366,7 +367,7 @@ export interface SceneBuildResult {
     beatSummary?: BuildBeatSummary;
     estimatedCostUsd?: number;
     costUsd?: number;
-    stageReports?: Record<"assets" | "compose" | "sync" | "render", StageReport>;
+    stageReports?: Record<"assets" | "transcript" | "compose" | "sync" | "render", StageReport>;
     sceneRepair?: BuildSceneRepairSummary;
     jobs?: JobRecord[];
     warnings?: string[];
@@ -499,7 +500,7 @@ declare function toBuildReport(projectDir: string, result: SceneBuildResult): {
     }[];
     outputPath: string | undefined;
     sceneRepair: BuildSceneRepairSummary;
-    stageReports: Record<"assets" | "compose" | "sync" | "render", StageReport> | undefined;
+    stageReports: Record<"assets" | "compose" | "sync" | "render" | "transcript", StageReport> | undefined;
     warnings: string[];
     retryWith: string[];
     totalLatencyMs: number;