hyper-animator-codex 0.8.0 → 0.8.3

package/README.md

@@ -3,9 +3,9 @@
 Install the `hyper-animator-codex` Codex skill from npm.
 
 The skill guides Codex through a contract-first HyperFrames animation workflow:
-natural-language brief, outline/narration detection, dual-catalog shot planning
-(HyperFrames + ShotCraft), MiniMax mainland China audio, HTML animation
-authoring, validation, user approval, and render handoff.
+natural-language brief, outline/narration detection, visual-first dual-catalog
+shot planning (HyperFrames + ShotCraft), HTML animation authoring, MiniMax
+mainland China audio after visual approval, validation, and render handoff.
 
 ## Install
 
@@ -77,14 +77,13 @@ generate music and voiceover without asking for credentials later:
 ```bash
 npx hyper-animator-codex install --force \
   --minimax-api-key "$MINIMAX_API_KEY" \
-  --minimax-group-id "$MINIMAX_GROUP_ID" \
-  --minimax-model music-2.6-free
+  --minimax-model music-3.0-free
 ```
 
 Environment fallback is also supported:
 
 ```bash
-MINIMAX_API_KEY=... MINIMAX_GROUP_ID=... npx hyper-animator-codex install --force
+MINIMAX_API_KEY=... npx hyper-animator-codex install --force
 ```
 
 Or load a JSON config file:
@@ -107,7 +106,8 @@ Preview HTML can include a bottom page indicator and thin draggable progress bar
 
 ```bash
 node skills/hyper-animator-codex/scripts/inject_preview_controls.mjs composition.html -o composition.preview.html --force
-python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.preview.html --preview-controls
+python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.preview.html \
+  --preview-controls --shot-plan shot-plan.json
 ```
 
 The injected controls support dragging the progress bar and using ArrowLeft or ArrowRight to move between pages.
@@ -124,6 +124,11 @@ When rendering video, hide preview controls with any one of:
 
 ## Narration And Subtitles
 
+The workflow detects narration needs early, but generated narration and
+subtitles are deferred until the user approves the page, transitions, and
+animation. Visual drafts use `audio.narration.mode: "deferred"` in the shot
+plan.
+
 Detect outline and narration files in a project directory:
 
 ```bash
@@ -180,20 +185,29 @@ node skills/hyper-animator-codex/scripts/query_shotcraft.mjs \
 ```
 
 HyperFrames entries remain the renderable catalog; ShotCraft supplies shot
-grammar and motion references that are translated into HyperFrames/GSAP HTML.
+grammar and motion references that are translated into `motion_contract`
+commitments and then into HyperFrames/GSAP HTML.
+
+For high-impact ShotCraft refs, the validator requires an explicit
+`motion_contract.motion_preset`. The bundled
+`references/shotcraft/motion-pack/` directory contains small GSAP helpers to
+copy before freehanding the animation.
+
 Validate a dual-catalog plan before authoring:
 
 ```bash
 node skills/hyper-animator-codex/scripts/validate_shot_plan.mjs shot-plan.json
+python3 skills/hyper-animator-codex/scripts/validate_hyperframes_html.py composition.html --shot-plan shot-plan.json
 ```
 
-When model routing is available, `gpt-5.6-sol` is reserved for page generation
-and animation authoring. Planning, discovery, audio prompting, validation, and
-packaging use a faster cost-efficient model.
+When model routing is available, the client's `high_quality` tier is reserved
+for page generation and animation authoring. Planning, discovery, audio
+prompting, validation, and packaging use its `fast` tier; the shot plan records
+the actual model names.
 
 ## Contents
 
-- `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
+- `skills/hyper-animator-codex/SKILL.md`: Codex and Claude Code skill instructions.
 - `skills/hyper-animator-codex/contracts/`: provider/model policy and shot-plan schema.
 - `skills/hyper-animator-codex/references/`: HyperFrames catalog, ShotCraft knowledge bundle, authoring patterns, workflows, and examples.
 - `skills/hyper-animator-codex/scripts/query_shotcraft.mjs`: ShotCraft intent/reference search.
@@ -209,7 +223,8 @@ packaging use a faster cost-efficient model.
 
 The skill can analyze background music and guide Codex to align HyperFrames/GSAP transitions to beats, bars, energy peaks, and detected music segments.
 
-Install optional Python dependencies:
+Install optional Python dependencies yourself if you want automatic beat
+analysis. The skill will not install them during a run:
 
 ```bash
 python3 -m pip install librosa pydub numpy click
@@ -236,6 +251,8 @@ Then analyze the generated audio with `analyze_music_beats.py` and align animati
 ## Development
 
 ```bash
+npm run preflight
 npm test
+npm run check
 npm run pack:check
 ```

package/bin/hyper-animator-codex.mjs

@@ -25,12 +25,12 @@ Options:
   --quiet                         Suppress successful install output
   --target <dir>                  Install into one specific skills directory
   --minimax-api-key <key>         Save MiniMax API key into installed skill config
-  --minimax-group-id <group_id>   Save MiniMax group_id into installed skill config
-  --minimax-model <model>         MiniMax text music model: music-3.0, music-2.6, or music-2.6-free
-  --minimax-config <file>         Load MiniMax JSON config with api_key, group_id, and model
+  --minimax-group-id <group_id>   Optional legacy account metadata
+  --minimax-model <model>         MiniMax text music model; default music-3.0
+  --minimax-config <file>         Load MiniMax JSON config with api_key and optional model
 
 Environment fallback:
-  MINIMAX_API_KEY, MINIMAX_GROUP_ID, MINIMAX_MODEL
+  MINIMAX_API_KEY, MINIMAX_MODEL (MINIMAX_GROUP_ID remains optional)
 `);
 }
 

package/lib/install-skill.mjs

@@ -1,6 +1,6 @@
-import { chmod, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { chmod, cp, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
@@ -84,46 +84,75 @@ async function restoreExistingMinimaxConfig(installedPath, existingConfig) {
 
 export async function installSkill(options = {}) {
   const targetRoot = options.targetRoot || resolveCodexSkillsRoot(options.env);
-  const sourcePath = options.sourcePath || join(packageRoot, "skills", SKILL_NAME);
-  const installedPath = join(targetRoot, SKILL_NAME);
+  const sourcePath = resolve(options.sourcePath || join(packageRoot, "skills", SKILL_NAME));
+  const installedPath = resolve(targetRoot, SKILL_NAME);
   const force = Boolean(options.force);
 
+  if (sourcePath === installedPath
+    || sourcePath.startsWith(`${installedPath}${sep}`)
+    || installedPath.startsWith(`${sourcePath}${sep}`)) {
+    throw new Error(`Source and install paths overlap: ${sourcePath} -> ${installedPath}`);
+  }
   if (!(await pathExists(sourcePath))) {
     throw new Error(`Packaged skill not found at ${sourcePath}`);
   }
 
   await mkdir(targetRoot, { recursive: true });
-
-  const existingMinimaxConfig = force ? await readExistingMinimaxConfig(installedPath) : null;
-
-  if (await pathExists(installedPath)) {
+  const installExists = await pathExists(installedPath);
+  if (installExists) {
     if (!force) {
       throw new Error(`${SKILL_NAME} already exists at ${installedPath}; rerun with --force to replace it`);
     }
-    await rm(installedPath, { recursive: true, force: true });
   }
 
-  await cp(sourcePath, installedPath, {
-    recursive: true,
-    filter: shouldCopy,
-  });
-
   const resolvedMinimaxConfig = await resolveInstallMinimaxConfig({
     cliConfig: options.minimaxConfig || {},
     env: options.env || process.env,
   });
-  const minimaxWrite = resolvedMinimaxConfig
-    ? await writeMinimaxConfig(installedPath, resolvedMinimaxConfig)
-    : null;
-  const restoredMinimaxConfigPath = minimaxWrite ? null : await restoreExistingMinimaxConfig(installedPath, existingMinimaxConfig);
+  const existingMinimaxConfig = force ? await readExistingMinimaxConfig(installedPath) : null;
+  const stagingRoot = await mkdtemp(join(resolve(targetRoot), `.${SKILL_NAME}-install-`));
+  const stagingPath = join(stagingRoot, SKILL_NAME);
+  let backupRoot = null;
+  let backupPath = null;
+
+  try {
+    await cp(sourcePath, stagingPath, {
+      recursive: true,
+      filter: shouldCopy,
+    });
+    if (resolvedMinimaxConfig) {
+      await writeMinimaxConfig(stagingPath, resolvedMinimaxConfig);
+    } else {
+      await restoreExistingMinimaxConfig(stagingPath, existingMinimaxConfig);
+    }
+
+    if (installExists) {
+      backupRoot = await mkdtemp(join(resolve(targetRoot), `.${SKILL_NAME}-backup-`));
+      backupPath = join(backupRoot, SKILL_NAME);
+      await rename(installedPath, backupPath);
+    }
+    try {
+      await rename(stagingPath, installedPath);
+    } catch (error) {
+      if (backupPath && await pathExists(backupPath)) {
+        await rename(backupPath, installedPath);
+      }
+      throw error;
+    }
+  } finally {
+    await rm(stagingRoot, { recursive: true, force: true });
+    if (backupRoot) await rm(backupRoot, { recursive: true, force: true });
+  }
 
   return {
     skillName: SKILL_NAME,
     tool: options.tool || "codex",
     sourcePath,
     installedPath,
-    minimaxConfigPath: minimaxWrite ? minimaxWrite.configPath : restoredMinimaxConfigPath,
-    minimaxConfig: minimaxWrite ? redactMinimaxConfig(minimaxWrite.config) : null,
+    minimaxConfigPath: resolvedMinimaxConfig || existingMinimaxConfig
+      ? join(installedPath, MINIMAX_CONFIG_RELATIVE_PATH)
+      : null,
+    minimaxConfig: resolvedMinimaxConfig ? redactMinimaxConfig(resolvedMinimaxConfig) : null,
   };
 }
 

package/lib/minimax-config.mjs

@@ -1,8 +1,8 @@
 import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-export const DEFAULT_MINIMAX_MODEL = "music-2.6";
-export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-2.6", "music-2.6-free"]);
+export const DEFAULT_MINIMAX_MODEL = "music-3.0";
+export const TEXT_MUSIC_MODELS = new Set(["music-3.0", "music-3.0-free", "music-2.6", "music-2.6-free"]);
 export const MINIMAX_CONFIG_RELATIVE_PATH = join("config", "minimax.json");
 
 async function pathExists(path) {
@@ -62,19 +62,15 @@ export function validateMinimaxConfig(config = {}) {
     throw new Error("MiniMax api_key is required when MiniMax config is provided");
   }
 
-  if (!normalized.group_id) {
-    throw new Error("MiniMax group_id is required when MiniMax config is provided");
-  }
-
   const model = normalized.model || DEFAULT_MINIMAX_MODEL;
 
   if (!TEXT_MUSIC_MODELS.has(model)) {
-    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-2.6, or music-2.6-free.`);
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-3.0-free, music-2.6, or music-2.6-free.`);
   }
 
   return {
     api_key: normalized.api_key,
-    group_id: normalized.group_id,
+    ...(normalized.group_id ? { group_id: normalized.group_id } : {}),
     model,
   };
 }
@@ -156,7 +152,7 @@ export function redactMinimaxConfig(config = {}) {
 
   return {
     api_key: normalized.api_key ? "[redacted]" : undefined,
-    group_id: normalized.group_id,
+    ...(normalized.group_id ? { group_id: normalized.group_id } : {}),
     model: normalized.model || DEFAULT_MINIMAX_MODEL,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.8.0",
+  "version": "0.8.3",
   "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -8,8 +8,13 @@
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
+    "build:contracts": "node tools/build-shot-plan-validator.mjs",
+    "preflight": "node tools/verify-governance.mjs",
     "test": "node --test",
-    "pack:check": "npm pack --dry-run"
+    "test:contracts": "node --test test/shot-plan-contract.test.mjs test/workflow-policy.test.mjs test/provider-policy.test.mjs",
+    "check": "npm run preflight && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run check"
   },
   "files": [
     "bin/",
@@ -36,5 +41,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1"
   }
 }

package/skills/hyper-animator-codex/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hyper-animator-codex
-description: Use when a user asks Codex to create, plan, author, customize, validate, preview, or render a HyperFrames, HTML, or GSAP animation/video from natural-language requirements, including product demos, code demos, data videos, podcast captions, social shorts, catalog assembly, new HyperFrames HTML, outline/narration detection, voiceover, subtitles, sound effects, background music, rhythm, BPM, final mixing, or beat-synced transitions.
+description: Use when a user asks a coding agent to create, plan, author, customize, validate, preview, or render a HyperFrames, HTML, or GSAP animation/video from natural-language requirements, including product demos, code demos, data videos, podcast captions, social shorts, catalog assembly, new HyperFrames HTML, outline/narration detection, voiceover, subtitles, sound effects, background music, rhythm, BPM, final mixing, or beat-synced transitions.
 ---
 
 # Hyper Animator Codex
@@ -11,41 +11,41 @@ Turn a natural-language animation or video brief into a validated HyperFrames HT
 
 ## Required Flow
 
-1. Read `contracts/workflow-policy.json` before doing any orchestration. Treat it as an executable product contract, not optional guidance. Generated narration and generated BGM must use `minimax_cn` at the declared `minimaxi.com` endpoints.
-2. Enforce the provider boundary. Never run `hyperframes auth login` or `hyperframes tts`. Do not use HeyGen, Kokoro, or MusicGen. Do not install a fallback audio runtime or fallback model. If MiniMax is unavailable or fails, stop that audio stage and ask the user to choose: retry MiniMax CN, provide a local audio file, or skip the track.
+1. Read `contracts/workflow-policy.json` before doing any orchestration. Treat it as an executable product contract, not optional guidance. Generated narration and generated BGM must use `minimax_cn` at the declared `minimaxi.com` endpoints; generated narration is gated until visual confirmation.
+2. Enforce the provider boundary. Never run `hyperframes auth login` or `hyperframes tts`. Do not use HeyGen, Kokoro, or MusicGen. Do not install a fallback audio runtime, fallback model, or beat-analysis dependency. If MiniMax or optional beat analysis is unavailable, stop that stage and ask the user to choose: retry MiniMax CN, provide a local audio file/beat map, or skip the track.
 3. Read `references/git-checkpoint-workflow.md` and run `scripts/git_checkpoint.mjs --phase init --message "chore: initialize hyper animator workspace" --allow-empty` before requirement capture. If the helper reports an existing dirty repository or linked worktree, stop and ask the user to resolve it.
-4. When starting in a new directory, restarting, or handling outline/narration/voiceover/subtitle/full-mix work, read `references/narration-audio-workflow.md` and run `scripts/detect_project_files.mjs --dir . --pretty` before visual planning.
+4. When starting in a new directory, restarting, or handling outline/narration/voiceover/subtitle/full-mix work, read `references/narration-audio-workflow.md` and run `scripts/detect_project_files.mjs --dir . --pretty` before visual planning. Detect outline/narration inputs only; do not process narration yet.
 5. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
 6. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
 7. Query both catalogs:
    - Read `references/hyperframes-catalog-map.json` and score renderable HyperFrames candidates.
    - Run `scripts/query_shotcraft.mjs --query "<purpose style motion>" --limit 8 --json` against `references/shotcraft/catalog.json` for shot grammar, pacing, transition, and camera references.
-8. Pick candidate HyperFrames blocks/components plus ShotCraft references for each main scene, caption, effect, transition, and outro. ShotCraft TSX is a design reference; do not introduce Remotion or copy it as the final renderer.
+8. Pick candidate HyperFrames blocks/components plus ShotCraft references for each main scene, caption, effect, transition, and outro. Open the selected ShotCraft card READMEs and translate their timing, camera, transition, and known pitfalls into explicit `motion_contract.shotcraft_commitments`; ShotCraft TSX is a design reference, not the renderer. If a selected card is covered by `references/shotcraft/motion-pack/README.md`, use its `motion_contract.motion_preset` and GSAP helper before freehanding motion.
 9. Decide generation mode:
    - `generate_new_hyperframes_html` when the user asks to write HTML, create a new effect, customize style, match a brand, use complex animation, or when component snippets are only paste placeholders.
    - `assemble_existing_catalog_items` only when the user asks to use existing catalog items or quickly compose installed blocks/components.
-10. Apply model routing when model selection is available: use `gpt-5.6-sol` for page and animation authoring only; use `gpt-5.6-terra` or another fast cost-efficient model for requirements, discovery, catalog queries, shot planning, audio prompting, validation, and packaging. Do not create an extra agent/entity only to implement this routing.
-11. Write a shot plan that follows `contracts/shot-plan.schema.json`, uses `catalog_strategy: "dual_catalog"`, and gives every shot explicit start/end timing and both catalog reference lists. Run `scripts/validate_shot_plan.mjs shot-plan.json`; fix every error before audio generation or HTML authoring.
-12. Clarify audio: ask whether to use narration, subtitles, animation/transition sound effects, and background music.
-13. If generated narration is used, first run `scripts/validate_provider_policy.mjs --kind narration --provider minimax_cn --endpoint https://api.minimaxi.com/v1/t2a_v2`. Use `scripts/generate_minimax_tts.mjs` for voice listing and TTS; do not construct MiniMax HTTP calls directly. For multi-scene narration, use `--split-scenes` and treat `narration-manifest.json` actual durations as the scene-timing source. Reconcile shot boundaries with those durations and run `scripts/validate_shot_plan.mjs` again. If subtitles are requested, run `scripts/generate_subtitles.mjs --timing-manifest <voice-output>/narration-manifest.json`.
-14. If generated BGM is requested, read `references/minimax-music-workflow.md`, run `scripts/validate_provider_policy.mjs --kind bgm --provider minimax_cn --endpoint https://api.minimaxi.com/v1/music_generation`, and use `scripts/generate_minimax_music.mjs`. Do not construct MiniMax HTTP calls directly.
-15. If background music is used, read `references/beat-sync-workflow.md`, generate or obtain the audio, and run `scripts/analyze_music_beats.py` when the file is available.
-16. Ask the second clarification round with dual-catalog candidate context: visual direction, motion rhythm, generation mode, narration/subtitle/audio choices, music prompt/model when MiniMax is used, and beat-sync assumptions when background music is present.
-17. Write or assemble HTML using `references/HyperFrames-AI-Generation-Patterns-codex.md`. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, narration beats, subtitle cues, and visual accents to the beat map instead of arbitrary timestamps.
-18. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
-19. Run pre-render quality gates on the base HTML.
-20. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy, and run `scripts/validate_hyperframes_html.py preview.html --preview-controls`.
-21. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-22. Render only after user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
+10. Apply capability-based model routing when model selection is available: use the client's `high_quality` model for page and animation authoring only, and a `fast` cost-efficient model for requirements, discovery, catalog queries, shot planning, audio prompting, validation, and packaging. On Codex, prefer `gpt-5.6-sol` and `gpt-5.6-terra` respectively; on Claude Code, record the actual Claude models selected. Do not create an extra agent/entity only to implement this routing.
+11. Write a visual-first shot plan that follows `contracts/shot-plan.schema.json`, sets workflow_stage: `visual_draft`, `catalog_strategy: "dual_catalog"`, `audio.narration.mode: "deferred"` when narration is requested, provider-neutral model routing tiers plus actual model names, explicit start/end timing, both catalog reference lists, and one `motion_contract` per shot including `motion_preset`. Run `scripts/validate_shot_plan.mjs shot-plan.json`; fix every error before HTML authoring.
+12. Clarify audio intent only: ask whether the final piece should use narration, subtitles, transition sound effects, and background music. Do not generate narration audio or subtitles before the user confirms the page, transition, and animation. If BGM is the rhythm source, it may be generated or imported before HTML; otherwise defer it with narration.
+13. If generated BGM is needed as the rhythm source, read `references/minimax-music-workflow.md`, run `scripts/validate_provider_policy.mjs --kind bgm --provider minimax_cn --endpoint https://api.minimaxi.com/v1/music_generation`, and use `scripts/generate_minimax_music.mjs`. Then read `references/beat-sync-workflow.md` and run `scripts/analyze_music_beats.py` when dependencies and the file are already available. Do not install beat-analysis dependencies during the run.
+14. Ask the second clarification round with dual-catalog candidate context: visual direction, motion rhythm, selected ShotCraft commitments, generation mode, BGM/beat-sync assumptions when present, and the fact that narration is deferred until visual approval.
+15. Write or assemble the visual HTML using `references/HyperFrames-AI-Generation-Patterns-codex.md`. When beat-sync is enabled, align major reveals, cuts, transitions, camera moves, subtitle placeholders, and visual accents to the beat map instead of arbitrary timestamps.
+16. After each file-writing stage, run `scripts/git_checkpoint.mjs` with the phase-specific allowlist from `references/git-checkpoint-workflow.md`. Do not create, switch, or recommend Git branches or worktrees.
+17. Mark every shot root with `data-shot-id` and `data-motion-preset`, then run `scripts/validate_hyperframes_html.py composition.html --shot-plan shot-plan.json` so planned ShotCraft motion is proven in executable HTML.
+18. Read `references/preview-controls-workflow.md`, run `scripts/inject_preview_controls.mjs` to create a preview HTML copy (with play/pause and interactive autoplay), and run `scripts/validate_hyperframes_html.py preview.html --preview-controls --shot-plan shot-plan.json`.
+19. Show a concise visual plan summary and preview path. Ask the user to confirm or revise the page, transition, and animation before any generated narration or subtitle work.
+20. After visual confirmation, handle narration. If generated narration is used, first run `scripts/validate_provider_policy.mjs --kind narration --provider minimax_cn --endpoint https://api.minimaxi.com/v1/t2a_v2`. Use `scripts/generate_minimax_tts.mjs` for voice listing and TTS; do not construct MiniMax HTTP calls directly. For multi-scene narration, use `--split-scenes` and treat `narration-manifest.json` actual durations as the scene-timing source. Generate subtitles only after this with `scripts/generate_subtitles.mjs --timing-manifest <voice-output>/narration-manifest.json`.
+21. Reconcile shot boundaries with actual narration durations, update the shot plan to `workflow_stage: "audio_integrated"`, re-run `scripts/validate_shot_plan.mjs`, update the HTML/audio preview, and ask for final render confirmation.
+22. Render only after final user confirmation. Prefer rendering the base HTML; if rendering the preview copy, use `?render=1`, `?preview=0`, or `<html data-render-mode="video">` so preview controls are hidden. Then report output path and any caveats.
 
 ## Interactive Questions
 
-Prefer Codex interactive question tools such as `AskUserQuestion` or `request_user_input` when available. If they are unavailable, ask the same questions as ordinary concise text and continue after the user answers.
+Prefer the current client's interactive question tool when available. If unavailable, ask the same questions as ordinary concise text and continue after the user answers.
 
 Use two rounds:
 
-- Round 1: purpose, format, duration, platform, required content, outline/narration status, narration/subtitles, brand assets, sound effects, background music, and whether video render is expected in this turn.
-- Round 2: after catalog scoring, ask about style, motion, candidate selection, generation mode, voice/emotion/subtitle style, and beat-sync assumptions when background music is present.
+- Round 1: purpose, format, duration, platform, required content, outline/narration status, desired final narration/subtitles, brand assets, sound effects, background music, and whether video render is expected in this turn.
+- Round 2: after catalog scoring, ask about style, motion, candidate selection, generation mode, selected ShotCraft commitments, and beat-sync assumptions when background music is present. Defer voice/emotion/subtitle generation choices until page, transition, and animation approval.
 
 Do not ask everything upfront when the brief is already specific. Ask only for missing or decision-changing information.
 
@@ -57,6 +57,7 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 - Read `references/hyperframes-catalog-map.json` whenever selecting catalog candidates or determining visual references.
 - Read `references/shotcraft/catalog.json` and use `scripts/query_shotcraft.mjs` whenever building or revising a shot plan. Open only the selected cards and source references, not the entire bundle.
 - Read selected `references/shotcraft/cards/<name>/README.md` files for intent, timing, parameters, and known failure modes. Treat selected `references/shotcraft/source/**/*.tsx` as motion references that must be translated into the HyperFrames/GSAP contract.
+- Read `references/shotcraft/motion-pack/README.md` before HTML authoring when selected ShotCraft refs include a supported preset. Copy only needed helpers from `references/shotcraft/motion-pack/shotcraft-motion-pack.js`.
 - Read `contracts/shot-plan.schema.json` before writing a shot plan and validate the result with `scripts/validate_shot_plan.mjs`.
 - Read `references/HyperFrames-AI-Generation-Patterns-codex.md` before generating new HyperFrames HTML.
 - Read `references/hyperframes-agent-pseudocode.ts` when implementing the end-to-end loop or when the correct sequence is ambiguous.
@@ -71,6 +72,8 @@ Hard constraints beat score:
 
 - Use the HyperFrames map and ShotCraft together. HyperFrames answers “what can be rendered”; ShotCraft answers “how the shot should communicate and move.”
 - Query ShotCraft first, then open only the top relevant cards. By default exclude `reference-only` styles.
+- Every selected ShotCraft reference must become a concrete `motion_contract.shotcraft_commitments` item in the shot plan before HTML authoring.
+- Supported ShotCraft refs must also select the matching `motion_contract.motion_preset`; use the motion pack helper before inventing a new GSAP pattern.
 - Do not install React, Remotion, or ShotCraft dependencies merely to use a ShotCraft reference.
 - Portrait requests prioritize portrait items such as `instagram-follow`, `tiktok-follow`, `spotify-card`, and `flowchart-vertical`.
 - Caption requests prioritize `caption-*` components.
@@ -83,7 +86,7 @@ Hard constraints beat score:
 Before render, run:
 
 ```bash
-python3 scripts/validate_hyperframes_html.py path/to/composition.html
+python3 scripts/validate_hyperframes_html.py path/to/composition.html --shot-plan path/to/shot-plan.json
 ```
 
 Generated block HTML must include:
@@ -93,6 +96,8 @@ Generated block HTML must include:
 - scoped CSS under `[data-composition-id="..."]` or another unique composition selector;
 - `gsap.timeline({ paused: true })`;
 - `window.__timelines[id]` registration;
+- one `data-shot-id` and matching `data-motion-preset` per planned shot;
+- a real motion-pack helper call for every supported non-`none` preset;
 - no unresolved `<!-- paste from ... -->` placeholders;
 - no wall-clock `Date.now()` or `setInterval()` driving primary timeline progress;
 - no `Math.random()` for visual generation; use a fixed-seed deterministic PRNG;
@@ -102,7 +107,7 @@ Generated block HTML must include:
 Preview HTML must pass:
 
 ```bash
-python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --preview-controls
+python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --preview-controls --shot-plan path/to/shot-plan.json
 ```
 
 If the validator fails, fix the HTML before asking the user to approve render.
@@ -113,7 +118,10 @@ Before approval, inspect the preview against the selected ShotCraft cards:
 
 - every required product capability has a distinct, readable shot;
 - every shot adds new information and preserves the selected card's motion
-  grammar, critical timing, and documented known pitfalls;
+  grammar, critical timing, documented known pitfalls, and written
+  `motion_contract.shotcraft_commitments`;
+- supported ShotCraft refs use their declared `motion_contract.motion_preset`
+  and corresponding motion-pack helper;
 - real product states/assets are used when supplied, with no invented product
   claims;
 - text, masks, media, fonts, and async resources are fully loaded at render
@@ -134,7 +142,7 @@ Before rendering, summarize:
 
 - generation mode;
 - shot-plan validator result and selected HyperFrames/ShotCraft references per shot;
-- model routing used, including confirmation that Sol was limited to page/animation authoring;
+- model routing used, including confirmation that the high-quality tier was limited to page/animation authoring;
 - detected outline/narration paths, ambiguity status, and any outline/narration generation assumptions;
 - selected or referenced catalog items;
 - narration usage, selected voice, emotion, voice audio path, subtitle style, subtitle JSON/SRT paths, and voice/BGM/SFX volume values when applicable;

package/skills/hyper-animator-codex/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Hyper Animator Codex"
-  short_description: "Plan dual-catalog HyperFrames videos with MiniMax CN audio"
-  default_prompt: "Use $hyper-animator-codex to plan my shots with HyperFrames and ShotCraft, create validated HyperFrames HTML, and use MiniMax CN for generated narration or BGM."
+  short_description: "Plan visual-first HyperFrames videos with ShotCraft"
+  default_prompt: "Use $hyper-animator-codex to plan visual-first shots with HyperFrames and ShotCraft, create validated HyperFrames HTML, and add MiniMax CN narration or BGM only at the approved stage."

package/skills/hyper-animator-codex/contracts/shot-plan.schema.json

@@ -6,6 +6,7 @@
   "additionalProperties": false,
   "required": [
     "schema_version",
+    "workflow_stage",
     "generation_mode",
     "catalog_strategy",
     "dimensions",
@@ -16,7 +17,14 @@
   ],
   "properties": {
     "schema_version": {
-      "const": "1.0.0"
+      "const": "1.1.0"
+    },
+    "workflow_stage": {
+      "enum": [
+        "visual_draft",
+        "audio_integrated",
+        "render_ready"
+      ]
     },
     "generation_mode": {
       "enum": [
@@ -74,12 +82,32 @@
       ],
       "properties": {
         "page_animation_authoring": {
-          "const": "gpt-5.6-sol"
+          "allOf": [
+            {
+              "$ref": "#/$defs/modelRoute"
+            },
+            {
+              "properties": {
+                "tier": {
+                  "const": "high_quality"
+                }
+              }
+            }
+          ]
         },
         "planning_and_validation": {
-          "not": {
-            "const": "gpt-5.6-sol"
-          }
+          "allOf": [
+            {
+              "$ref": "#/$defs/modelRoute"
+            },
+            {
+              "properties": {
+                "tier": {
+                  "const": "fast"
+                }
+              }
+            }
+          ]
         }
       }
     },
@@ -98,6 +126,26 @@
     }
   },
   "$defs": {
+    "modelRoute": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tier",
+        "actual_model"
+      ],
+      "properties": {
+        "tier": {
+          "enum": [
+            "high_quality",
+            "fast"
+          ]
+        },
+        "actual_model": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     "audioTrack": {
       "type": "object",
       "additionalProperties": false,
@@ -109,7 +157,8 @@
           "enum": [
             "generated",
             "user_local_file",
-            "none"
+            "none",
+            "deferred"
           ]
         },
         "provider": {
@@ -167,7 +216,8 @@
         "end_seconds",
         "purpose",
         "hyperframes_refs",
-        "shotcraft_refs"
+        "shotcraft_refs",
+        "motion_contract"
       ],
       "properties": {
         "id": {
@@ -188,6 +238,7 @@
         },
         "hyperframes_refs": {
           "type": "array",
+          "minItems": 1,
           "items": {
             "type": "string",
             "minLength": 1
@@ -196,6 +247,7 @@
         },
         "shotcraft_refs": {
           "type": "array",
+          "minItems": 1,
           "items": {
             "type": "string",
             "minLength": 1
@@ -207,6 +259,60 @@
             "string",
             "null"
           ]
+        },
+        "motion_contract": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "motion_preset",
+            "energy",
+            "camera",
+            "transition",
+            "shotcraft_commitments",
+            "readable_rest_seconds"
+          ],
+          "properties": {
+            "motion_preset": {
+              "enum": [
+                "none",
+                "slam-entrance",
+                "whip-transition",
+                "crash-zoom",
+                "push-stack-wipe",
+                "dataviz-landscape-open",
+                "panel-grid-reflow",
+                "brand-resolve"
+              ]
+            },
+            "energy": {
+              "enum": [
+                "quiet",
+                "balanced",
+                "high",
+                "cinematic"
+              ]
+            },
+            "camera": {
+              "type": "string",
+              "minLength": 1
+            },
+            "transition": {
+              "type": "string",
+              "minLength": 1
+            },
+            "shotcraft_commitments": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "readable_rest_seconds": {
+              "type": "number",
+              "minimum": 0
+            }
+          }
         }
       }
     }