@vibeframe/cli 0.113.27 → 0.113.28

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/index.js

@@ -27192,8 +27192,8 @@ no unresolved unacknowledged host-agent issues.
 **Load the \`hyperframes\` skill before authoring scenes** \u2014 it encodes the
 composition rules, motion principles, type system, and visual-identity gate.
 If your agent has it installed globally it is already available; otherwise run
-\`vibe scene install-skill\` to eject a local, editable copy (\`SKILL.md\` +
-\`references/\`, gitignored by default) and read \`SKILL.md\`.
+\`vibe scene install-skill\`, which runs upstream's installer and writes
+\`.agents/skills/hyperframes/SKILL.md\`. Read that file before authoring.
 
 **Always invoke the relevant skill before authoring scenes.** Skills encode
 framework-specific patterns (GSAP timeline registration, data-attribute
@@ -27223,7 +27223,7 @@ the framework-level minimum, not the cinematic craft layer.
 - \`index.html\` \u2014 root composition (timeline)
 - \`compositions/scene-*.html\` \u2014 per-scene HTML authored by you or the agent
 - \`assets/\` \u2014 generated/canonical build media (narration audio, images, video)
-- \`references/\` \u2014 composition rule docs, only when ejected via \`vibe scene install-skill\` (not user media)
+- \`.agents/skills/hyperframes/\` \u2014 upstream composition rules, when installed here rather than globally
 - \`transcript.json\` \u2014 Whisper word-level transcript (if narration exists)
 - \`hyperframes.json\` \u2014 HF registry config (speak to both toolchains)
 - \`vibe.config.json\` \u2014 canonical VibeFrame config (providers, budget)
@@ -27287,8 +27287,9 @@ function buildSceneGitignore() {
 renders/*.mp4
 tmp/
 
-# Vendored Hyperframes skill copies \u2014 regenerable via 'vibe scene install-skill'.
-# Delete these lines if you eject and want to commit per-project customizations.
+# Hyperframes skill copies left by older VibeFrame versions. Nothing writes
+# these now - upstream's installer owns the rules and puts them under
+# .agents/skills/hyperframes/, which is yours to commit or ignore.
 /SKILL.md
 /references/
 /.claude/skills/hyperframes/
@@ -27329,12 +27330,7 @@ function describeSceneScaffold(opts) {
     ];
   }
   if (profile === "agent" || profile === "full") {
-    groups.agent = [
-      resolve7(dir, "AGENTS.md"),
-      resolve7(dir, "SKILL.md"),
-      resolve7(dir, "references"),
-      resolve7(dir, "CLAUDE.md")
-    ];
+    groups.agent = [resolve7(dir, "AGENTS.md"), resolve7(dir, "CLAUDE.md")];
   }
   return groups;
 }
@@ -57569,11 +57565,11 @@ narration / backdrop intent.
 1. \`vibe init my-promo --visual-style "Swiss Pulse"\` \u2014 seeds
    \`DESIGN.md\` (palette, typography, motion, transitions) plus the
    \`vibe.config.json\` / \`hyperframes.json\` / \`index.html\` scaffold.
-   In Plan H this **also installs local composition rules** at the
-   right place for your host (\`.claude/skills/hyperframes/\` for Claude
-   Code, \`.cursor/rules/hyperframes.mdc\` for Cursor, universal
-   \`SKILL.md\` for everyone else).
-2. Read \`SKILL.md\` (or the host-specific copy) \u2014 Hyperframes
+   It does **not** install the composition rules; if your agent does not
+   already have the \`hyperframes\` skill, run
+   \`vibe scene install-skill\` to fetch them from upstream into
+   \`.agents/skills/hyperframes/\`.
+2. Read \`.agents/skills/hyperframes/SKILL.md\` (or your global copy) \u2014
    framework rules, motion principles, type system, transition recipes.
 3. Read \`DESIGN.md\` \u2014 project-specific palette / typography / motion
    signature (visual identity hard-gate).
@@ -57903,9 +57899,10 @@ vibe generate motion "animated product logo reveal" --render -o logo-reveal.mp4
         title: "Scene authoring with vibe",
         summary: "Author per-scene HTML compositions and render to MP4 (BUILD flow)",
         steps: [
-          'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project + install local composition rules.',
+          'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project.',
+          "Run `vibe scene install-skill` unless your agent already has the `hyperframes` skill; `vibe doctor` tells you which.",
           "Edit `STORYBOARD.md` with per-beat YAML cues (narration / backdrop / duration).",
-          "Read `SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
+          "Read `.agents/skills/hyperframes/SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
           "Run `vibe build <dir>`. With an agent host detected, the CLI emits a `needs-author` plan; the host agent authors each `compositions/scene-<id>.html` and re-invokes to render.",
           "Run `vibe build <dir> --stage sync` to assemble index.html, `vibe scene lint <dir> --fix` to validate, then `vibe render <dir>` to produce the MP4."
         ],
@@ -69586,7 +69583,7 @@ var init_scene2 = __esm({
       cost: "free",
       title: "Get Scene Authoring Prompts",
       annotations: { readOnly: true, openWorld: false },
-      description: "Emit the per-beat compose plan for the host agent to author scene HTML itself. Reads STORYBOARD.md + DESIGN.md and returns each beat's outputPath + userPrompt + cues + body, plus references to the project's SKILL.md (Hyperframes rules) and DESIGN.md (visual identity). The host agent writes each compositions/scene-<id>.html file directly \u2014 VibeFrame makes NO LLM call here. Hosts that cannot write files (e.g. Claude Desktop) submit each authored beat with scene_submit instead. Pairs with scene_install_skill (Phase H1). Phase H2 of the agentic-native composer plan; the internal-LLM batch path (build) remains as a fallback for non-agent contexts.",
+      description: "Emit the per-beat compose plan for the host agent to author scene HTML itself. Reads STORYBOARD.md + DESIGN.md and returns each beat's outputPath + userPrompt + cues + body, plus the path to the Hyperframes rules (skillReference) and DESIGN.md (visual identity). The host agent writes each compositions/scene-<id>.html file directly \u2014 VibeFrame makes NO LLM call here, and there is no internal-LLM fallback: authoring is always the host agent's job. Hosts that cannot write files (e.g. Claude Desktop) submit each authored beat with scene_submit instead. Pairs with scene_install_skill, which fetches the rules from upstream when the agent does not already have them.",
       schema: sceneComposePromptsSchema,
       async execute(args, ctx) {
         const projectDir = resolve79(ctx.workingDirectory, args.projectDir);
@@ -74251,7 +74248,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.113.27",
+  version: "0.113.28",
   description: "VibeFrame CLI - agentic video workflow runtime",
   private: false,
   license: "MIT",
@@ -83580,14 +83577,14 @@ agreement.
 Where the skill comes from depends on your setup:
 
 - If the \`hyperframes\` skill is installed globally (e.g. Claude Code), your
-  agent already has it \u2014 \`vibe init\` does **not** copy it into the project.
-- Otherwise \`vibe init\` writes a local copy: universal \`SKILL.md\` (with
-  \`references/*.md\`) at the project root, plus host layouts
-  (\`.claude/skills/hyperframes/\`, \`.cursor/rules/hyperframes.mdc\`).
+  agent already has it and nothing else is needed.
+- Otherwise install it into this project with \`vibe scene install-skill\`,
+  which runs upstream's own installer and writes
+  \`.agents/skills/hyperframes/\`.
 
-To get editable per-project copies on demand, run
-\`vibe scene install-skill [--host all]\` (these copies are gitignored by
-default \u2014 see \`.gitignore\`).
+\`vibe init\` never copies the rules in. They come from upstream so they stay
+current, and fetching them is a network call the scaffold does not make on
+your behalf. \`vibe doctor\` reports whether your agent can read them.
 
 For render-stable text, do not apply continuous \`scale\`, \`x\`, \`y\`,
 \`filter\`, or other transform tweens to \`.scene-content\` or any ancestor
@@ -83721,8 +83718,10 @@ renders/
 *.vibe.json
 .vibeframe/
 
-# Vendored Hyperframes skill copies \u2014 regenerable via 'vibe scene install-skill'.
-# Delete these lines if you eject and want to commit per-project customizations.
+# Hyperframes skill copies left by older VibeFrame versions, which vendored a
+# snapshot of upstream's rules. Nothing writes these now - upstream's installer
+# owns the rules and puts them under .agents/skills/hyperframes/, which is
+# yours to commit or ignore. These lines only keep pre-existing copies quiet.
 /SKILL.md
 /references/
 /.claude/skills/hyperframes/
@@ -85772,6 +85771,7 @@ import { existsSync as existsSync53 } from "node:fs";
 import { resolve as resolve73 } from "node:path";
 init_composer_resolve();
 init_cost_tier();
+init_install_skill();
 init_output();
 var COMMAND_KEY_MAP = getCommandKeyMap();
 var FREE_COMMANDS = [
@@ -85979,7 +85979,8 @@ async function runDiagnostics() {
     if (!(err instanceof ComposerResolveError)) throw err;
   }
   const sceneProjectInCwd = existsSync53(resolve73(cwd, "STORYBOARD.md"));
-  const skillInstalled = existsSync53(resolve73(cwd, "SKILL.md"));
+  const skillInstalled = hyperframesSkillAvailable(cwd);
+  const skillPath = resolveSkillReference(cwd);
   return {
     system: {
       node: { version: nodeVersion, ok: true },
@@ -86016,7 +86017,8 @@ async function runDiagnostics() {
         composer: composerResolved,
         composerEnvVar: composerEnv,
         sceneProjectInCwd,
-        skillInstalled
+        skillInstalled,
+        skillPath
       },
       ...configError ? { configError } : {}
     },
@@ -86147,17 +86149,16 @@ function printReport(results, opts = { verbose: false }) {
     }
     if (sc.sceneProjectInCwd) {
       if (sc.skillInstalled) {
-        console.log(
-          `    SKILL.md     ${source_default.green("OK")}     ${source_default.dim("installed in this scene project")}`
-        );
+        const where = sc.skillPath ?? "installed globally for your agent";
+        console.log(`    HF rules     ${source_default.green("OK")}     ${source_default.dim(where)}`);
       } else {
         console.log(
-          `    SKILL.md     ${source_default.yellow("MISSING")} ${source_default.dim("Run: vibe scene install-skill")}`
+          `    HF rules     ${source_default.yellow("MISSING")} ${source_default.dim(`Run: vibe scene install-skill`)}`
         );
       }
     } else {
       console.log(
-        `    SKILL.md     ${source_default.dim("(no STORYBOARD.md in cwd \u2014 skill is per-scene-project)")}`
+        `    HF rules     ${source_default.dim("(no STORYBOARD.md in cwd \u2014 rules are per-scene-project)")}`
       );
     }
   }
@@ -86317,7 +86318,7 @@ function pickNextStep(results, hasMissingProviders) {
   }
   const sc = results.scope.sceneComposer;
   if (sc.sceneProjectInCwd && !sc.skillInstalled) {
-    return "Next: run 'vibe scene install-skill' so your host agent can read the Hyperframes rules from this project.";
+    return `Next: run 'vibe scene install-skill' (or '${HYPERFRAMES_SKILL_INSTALL_COMMAND}') so your host agent can read the Hyperframes composition rules.`;
   }
   if (hasMissingProviders) {
     return "Run 'vibe setup' to add more provider keys.";

package/dist/tools/manifest/index.js

@@ -26374,8 +26374,8 @@ no unresolved unacknowledged host-agent issues.
 **Load the \`hyperframes\` skill before authoring scenes** \u2014 it encodes the
 composition rules, motion principles, type system, and visual-identity gate.
 If your agent has it installed globally it is already available; otherwise run
-\`vibe scene install-skill\` to eject a local, editable copy (\`SKILL.md\` +
-\`references/\`, gitignored by default) and read \`SKILL.md\`.
+\`vibe scene install-skill\`, which runs upstream's installer and writes
+\`.agents/skills/hyperframes/SKILL.md\`. Read that file before authoring.
 
 **Always invoke the relevant skill before authoring scenes.** Skills encode
 framework-specific patterns (GSAP timeline registration, data-attribute
@@ -26405,7 +26405,7 @@ the framework-level minimum, not the cinematic craft layer.
 - \`index.html\` \u2014 root composition (timeline)
 - \`compositions/scene-*.html\` \u2014 per-scene HTML authored by you or the agent
 - \`assets/\` \u2014 generated/canonical build media (narration audio, images, video)
-- \`references/\` \u2014 composition rule docs, only when ejected via \`vibe scene install-skill\` (not user media)
+- \`.agents/skills/hyperframes/\` \u2014 upstream composition rules, when installed here rather than globally
 - \`transcript.json\` \u2014 Whisper word-level transcript (if narration exists)
 - \`hyperframes.json\` \u2014 HF registry config (speak to both toolchains)
 - \`vibe.config.json\` \u2014 canonical VibeFrame config (providers, budget)
@@ -26469,8 +26469,9 @@ function buildSceneGitignore() {
 renders/*.mp4
 tmp/
 
-# Vendored Hyperframes skill copies \u2014 regenerable via 'vibe scene install-skill'.
-# Delete these lines if you eject and want to commit per-project customizations.
+# Hyperframes skill copies left by older VibeFrame versions. Nothing writes
+# these now - upstream's installer owns the rules and puts them under
+# .agents/skills/hyperframes/, which is yours to commit or ignore.
 /SKILL.md
 /references/
 /.claude/skills/hyperframes/
@@ -26508,12 +26509,7 @@ function describeSceneScaffold(opts) {
     ];
   }
   if (profile === "agent" || profile === "full") {
-    groups.agent = [
-      resolve8(dir, "AGENTS.md"),
-      resolve8(dir, "SKILL.md"),
-      resolve8(dir, "references"),
-      resolve8(dir, "CLAUDE.md")
-    ];
+    groups.agent = [resolve8(dir, "AGENTS.md"), resolve8(dir, "CLAUDE.md")];
   }
   return groups;
 }
@@ -54724,7 +54720,7 @@ var sceneComposePromptsTool = defineTool({
   cost: "free",
   title: "Get Scene Authoring Prompts",
   annotations: { readOnly: true, openWorld: false },
-  description: "Emit the per-beat compose plan for the host agent to author scene HTML itself. Reads STORYBOARD.md + DESIGN.md and returns each beat's outputPath + userPrompt + cues + body, plus references to the project's SKILL.md (Hyperframes rules) and DESIGN.md (visual identity). The host agent writes each compositions/scene-<id>.html file directly \u2014 VibeFrame makes NO LLM call here. Hosts that cannot write files (e.g. Claude Desktop) submit each authored beat with scene_submit instead. Pairs with scene_install_skill (Phase H1). Phase H2 of the agentic-native composer plan; the internal-LLM batch path (build) remains as a fallback for non-agent contexts.",
+  description: "Emit the per-beat compose plan for the host agent to author scene HTML itself. Reads STORYBOARD.md + DESIGN.md and returns each beat's outputPath + userPrompt + cues + body, plus the path to the Hyperframes rules (skillReference) and DESIGN.md (visual identity). The host agent writes each compositions/scene-<id>.html file directly \u2014 VibeFrame makes NO LLM call here, and there is no internal-LLM fallback: authoring is always the host agent's job. Hosts that cannot write files (e.g. Claude Desktop) submit each authored beat with scene_submit instead. Pairs with scene_install_skill, which fetches the rules from upstream when the agent does not already have them.",
   schema: sceneComposePromptsSchema,
   async execute(args, ctx) {
     const projectDir = resolve27(ctx.workingDirectory, args.projectDir);
@@ -62572,11 +62568,11 @@ narration / backdrop intent.
 1. \`vibe init my-promo --visual-style "Swiss Pulse"\` \u2014 seeds
    \`DESIGN.md\` (palette, typography, motion, transitions) plus the
    \`vibe.config.json\` / \`hyperframes.json\` / \`index.html\` scaffold.
-   In Plan H this **also installs local composition rules** at the
-   right place for your host (\`.claude/skills/hyperframes/\` for Claude
-   Code, \`.cursor/rules/hyperframes.mdc\` for Cursor, universal
-   \`SKILL.md\` for everyone else).
-2. Read \`SKILL.md\` (or the host-specific copy) \u2014 Hyperframes
+   It does **not** install the composition rules; if your agent does not
+   already have the \`hyperframes\` skill, run
+   \`vibe scene install-skill\` to fetch them from upstream into
+   \`.agents/skills/hyperframes/\`.
+2. Read \`.agents/skills/hyperframes/SKILL.md\` (or your global copy) \u2014
    framework rules, motion principles, type system, transition recipes.
 3. Read \`DESIGN.md\` \u2014 project-specific palette / typography / motion
    signature (visual identity hard-gate).
@@ -62906,9 +62902,10 @@ var META = {
     title: "Scene authoring with vibe",
     summary: "Author per-scene HTML compositions and render to MP4 (BUILD flow)",
     steps: [
-      'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project + install local composition rules.',
+      'Run `vibe init <dir> --visual-style "<style name>"` to scaffold the project.',
+      "Run `vibe scene install-skill` unless your agent already has the `hyperframes` skill; `vibe doctor` tells you which.",
       "Edit `STORYBOARD.md` with per-beat YAML cues (narration / backdrop / duration).",
-      "Read `SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
+      "Read `.agents/skills/hyperframes/SKILL.md` for the framework rules and `DESIGN.md` for the visual-identity hard-gate.",
       "Run `vibe build <dir>`. With an agent host detected, the CLI emits a `needs-author` plan; the host agent authors each `compositions/scene-<id>.html` and re-invokes to render.",
       "Run `vibe build <dir> --stage sync` to assemble index.html, `vibe scene lint <dir> --fix` to validate, then `vibe render <dir>` to produce the MP4."
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.113.27",
+  "version": "0.113.28",
   "description": "VibeFrame CLI - agentic video workflow runtime",
   "private": false,
   "license": "MIT",
@@ -83,8 +83,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.113.27",
-    "@vibeframe/core": "0.113.27"
+    "@vibeframe/ai-providers": "0.113.28",
+    "@vibeframe/core": "0.113.28"
   },
   "engines": {
     "node": ">=20"