hyper-animator-codex 0.7.0 → 0.8.0

package/README.md

@@ -2,7 +2,10 @@
 
 Install the `hyper-animator-codex` Codex skill from npm.
 
-The skill guides Codex through a HyperFrames animation workflow: natural-language brief, outline/narration detection, clarification questions, catalog-map intent matching, style and motion selection, HTML animation authoring, validation, user approval, and render handoff.
+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.
 
 ## Install
 
@@ -22,19 +25,31 @@ Or install the CLI globally:
 
 ```bash
 npm install -g hyper-animator-codex
-hyper-animator-codex install --force
 ```
 
-By default the installer copies the skill to:
+Global install runs a postinstall step that copies the skill to both Codex and Claude Code:
 
 ```text
 ${CODEX_HOME:-$HOME/.codex}/skills/hyper-animator-codex
+${CLAUDE_HOME:-$HOME/.claude}/skills/hyper-animator-codex
+```
+
+To skip automatic skill installation during npm install:
+
+```bash
+HYPER_ANIMATOR_CODEX_SKIP_POSTINSTALL=1 npm install -g hyper-animator-codex
+```
+
+You can also run or re-run installation manually:
+
+```bash
+hyper-animator-codex install --force
 ```
 
-Use a custom Codex skills directory:
+Use one custom skills directory:
 
 ```bash
-npx hyper-animator-codex install --target /path/to/codex/skills
+npx hyper-animator-codex install --target /path/to/skills
 ```
 
 ## Git Checkpoints
@@ -54,7 +69,10 @@ Existing Git repositories with uncommitted changes are protected: the helper sto
 
 ## MiniMax Audio Configuration
 
-MiniMax is the preferred generated-background-music provider and the required narration TTS provider. Configure it during install so the copied Codex skill can generate music and voiceover without asking for credentials later:
+MiniMax mainland China (`api.minimaxi.com`) is the required provider for both
+generated narration and generated BGM. HeyGen, Kokoro, and MusicGen are not
+automatic fallbacks. Configure MiniMax during install so the copied skill can
+generate music and voiceover without asking for credentials later:
 
 ```bash
 npx hyper-animator-codex install --force \
@@ -123,22 +141,64 @@ Generate narration audio from `narration.json`:
 ```bash
 node skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs \
   --narration-json narration.json \
+  --split-scenes \
   --output-dir hyper-animator-output/voice
 ```
 
+`--split-scenes` writes one audio file per narration scene and
+`narration-manifest.json` with exact MiniMax durations. Use it to time the shot
+plan and subtitles:
+
 Generate timed subtitle JSON and SRT:
 
 ```bash
 node skills/hyper-animator-codex/scripts/generate_subtitles.mjs \
   --narration narration.json \
+  --timing-manifest hyper-animator-output/voice/narration-manifest.json \
   --output-dir hyper-animator-output/subtitles \
   --style clean
 ```
 
+If a MiniMax call fails, the workflow asks whether to retry, use a local
+user-provided file, or skip that track. It does not install another speech or
+music model.
+
+## Dual-Catalog Shot Planning
+
+The installed skill bundles a lightweight ShotCraft knowledge layer: 106 shot
+cards, 164 style records, core production notes, and source-backed TSX
+references. Video previews, audio, raster assets, dependencies, and a runnable
+Remotion project are excluded.
+
+Search the ShotCraft references:
+
+```bash
+node skills/hyper-animator-codex/scripts/query_shotcraft.mjs \
+  --query "premium product reveal, beat-synced theme changes" \
+  --limit 8 \
+  --json
+```
+
+HyperFrames entries remain the renderable catalog; ShotCraft supplies shot
+grammar and motion references that are translated into HyperFrames/GSAP HTML.
+Validate a dual-catalog plan before authoring:
+
+```bash
+node skills/hyper-animator-codex/scripts/validate_shot_plan.mjs 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.
+
 ## Contents
 
 - `skills/hyper-animator-codex/SKILL.md`: Codex skill instructions.
-- `skills/hyper-animator-codex/references/`: HyperFrames catalog map, workflow guide, pseudocode, and request examples.
+- `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.
+- `skills/hyper-animator-codex/scripts/validate_provider_policy.mjs`: generated-audio provider/endpoint guard.
+- `skills/hyper-animator-codex/scripts/validate_shot_plan.mjs`: dual-catalog shot-plan validator.
 - `skills/hyper-animator-codex/scripts/detect_project_files.mjs`: top-level outline and narration detector for first-run/restart workflows.
 - `skills/hyper-animator-codex/scripts/generate_minimax_tts.mjs`: MiniMax voice listing and narration TTS helper.
 - `skills/hyper-animator-codex/scripts/generate_subtitles.mjs`: timed subtitle JSON/SRT generator.

package/bin/hyper-animator-codex.mjs

@@ -1,24 +1,32 @@
 #!/usr/bin/env node
-import { installSkill, resolveCodexSkillsRoot, SKILL_NAME } from "../lib/install-skill.mjs";
+import {
+  installSkillToTargets,
+  resolveClaudeCodeSkillsRoot,
+  resolveCodexSkillsRoot,
+  SKILL_NAME,
+} from "../lib/install-skill.mjs";
 import { parseInstallArgs } from "../lib/install-options.mjs";
 
 function printHelp() {
   console.log(`Usage:
   hyper-animator-codex install [--force] [--target <skills-dir>] [MiniMax options]
   hyper-animator-codex path
+  hyper-animator-codex paths
   hyper-animator-codex help
 
 Commands:
-  install  Install the packaged ${SKILL_NAME} skill into Codex
+  install  Install the packaged ${SKILL_NAME} skill into Codex and Claude Code
   path     Print the default Codex skills directory
+  paths    Print default Codex and Claude Code skills directories
   help     Show this help
 
 Options:
   --force                         Replace an existing installed skill
-  --target <dir>                  Install into a specific Codex skills directory
+  --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-2.6 or music-2.6-free
+  --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
 
 Environment fallback:
@@ -39,20 +47,34 @@ async function main() {
     return;
   }
 
+  if (command === "paths") {
+    console.log(`Codex: ${resolveCodexSkillsRoot()}`);
+    console.log(`Claude Code: ${resolveClaudeCodeSkillsRoot()}`);
+    return;
+  }
+
   if (command !== "install") {
     throw new Error(`Unknown command: ${command}`);
   }
 
   const options = parseInstallArgs(args);
-  const result = await installSkill(options);
+  const result = await installSkillToTargets(options);
+
+  if (options.quiet) {
+    return;
+  }
 
   console.log(`Installed ${result.skillName}`);
   console.log(`Source: ${result.sourcePath}`);
-  console.log(`Target: ${result.installedPath}`);
 
-  if (result.minimaxConfigPath) {
-    console.log(`MiniMax config: ${result.minimaxConfigPath}`);
-    console.log(`MiniMax model: ${result.minimaxConfig.model}`);
+  for (const install of result.installs) {
+    console.log(`${install.tool}: ${install.installedPath}`);
+    if (install.minimaxConfigPath) {
+      console.log(`${install.tool} MiniMax config: ${install.minimaxConfigPath}`);
+      if (install.minimaxConfig) {
+        console.log(`${install.tool} MiniMax model: ${install.minimaxConfig.model}`);
+      }
+    }
   }
 }
 

package/bin/postinstall.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { installSkillToTargets } from "../lib/install-skill.mjs";
+
+if (process.env.HYPER_ANIMATOR_CODEX_SKIP_POSTINSTALL === "1") {
+  process.exit(0);
+}
+
+try {
+  const result = await installSkillToTargets({
+    force: true,
+    quiet: true,
+    env: process.env,
+  });
+
+  const targets = result.installs.map((install) => `${install.tool}:${install.installedPath}`).join(", ");
+  console.log(`hyper-animator-codex installed skills: ${targets}`);
+} catch (error) {
+  console.warn(`hyper-animator-codex postinstall skipped: ${error.message}`);
+}

package/lib/install-options.mjs

@@ -11,6 +11,7 @@ function requireValue(args, index, flag) {
 export function parseInstallArgs(args) {
   const parsed = {
     force: false,
+    quiet: false,
     targetRoot: undefined,
     minimaxConfig: {},
   };
@@ -20,6 +21,8 @@ export function parseInstallArgs(args) {
 
     if (arg === "--force") {
       parsed.force = true;
+    } else if (arg === "--quiet") {
+      parsed.quiet = true;
     } else if (arg === "--target") {
       parsed.targetRoot = requireValue(args, index, arg);
       index += 1;

package/lib/install-skill.mjs

@@ -1,9 +1,10 @@
-import { cp, mkdir, rm, stat } from "node:fs/promises";
+import { chmod, cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
+  MINIMAX_CONFIG_RELATIVE_PATH,
   redactMinimaxConfig,
   resolveInstallMinimaxConfig,
   writeMinimaxConfig,
@@ -43,6 +44,44 @@ export function resolveCodexSkillsRoot(env = process.env) {
   return join(home, ".codex", "skills");
 }
 
+export function resolveClaudeCodeSkillsRoot(env = process.env) {
+  if (env.CLAUDE_HOME) {
+    return join(env.CLAUDE_HOME, "skills");
+  }
+
+  const home = env.HOME || homedir();
+  if (!home) {
+    throw new Error("Cannot resolve Claude Code skills directory: HOME is not set");
+  }
+
+  return join(home, ".claude", "skills");
+}
+
+async function readExistingMinimaxConfig(installedPath) {
+  const configPath = join(installedPath, MINIMAX_CONFIG_RELATIVE_PATH);
+
+  if (!(await pathExists(configPath))) {
+    return null;
+  }
+
+  return {
+    configPath,
+    body: await readFile(configPath, "utf8"),
+  };
+}
+
+async function restoreExistingMinimaxConfig(installedPath, existingConfig) {
+  if (!existingConfig) {
+    return null;
+  }
+
+  const configPath = join(installedPath, MINIMAX_CONFIG_RELATIVE_PATH);
+  await mkdir(dirname(configPath), { recursive: true });
+  await writeFile(configPath, existingConfig.body, { encoding: "utf8", mode: 0o600 });
+  await chmod(configPath, 0o600);
+  return configPath;
+}
+
 export async function installSkill(options = {}) {
   const targetRoot = options.targetRoot || resolveCodexSkillsRoot(options.env);
   const sourcePath = options.sourcePath || join(packageRoot, "skills", SKILL_NAME);
@@ -55,6 +94,8 @@ export async function installSkill(options = {}) {
 
   await mkdir(targetRoot, { recursive: true });
 
+  const existingMinimaxConfig = force ? await readExistingMinimaxConfig(installedPath) : null;
+
   if (await pathExists(installedPath)) {
     if (!force) {
       throw new Error(`${SKILL_NAME} already exists at ${installedPath}; rerun with --force to replace it`);
@@ -74,12 +115,53 @@ export async function installSkill(options = {}) {
   const minimaxWrite = resolvedMinimaxConfig
     ? await writeMinimaxConfig(installedPath, resolvedMinimaxConfig)
     : null;
+  const restoredMinimaxConfigPath = minimaxWrite ? null : await restoreExistingMinimaxConfig(installedPath, existingMinimaxConfig);
 
   return {
     skillName: SKILL_NAME,
+    tool: options.tool || "codex",
     sourcePath,
     installedPath,
-    minimaxConfigPath: minimaxWrite ? minimaxWrite.configPath : null,
+    minimaxConfigPath: minimaxWrite ? minimaxWrite.configPath : restoredMinimaxConfigPath,
     minimaxConfig: minimaxWrite ? redactMinimaxConfig(minimaxWrite.config) : null,
   };
 }
+
+export async function installSkillToTargets(options = {}) {
+  const sourcePath = options.sourcePath || join(packageRoot, "skills", SKILL_NAME);
+
+  if (options.targetRoot) {
+    const install = await installSkill({
+      ...options,
+      sourcePath,
+      tool: "custom",
+    });
+    return {
+      skillName: SKILL_NAME,
+      sourcePath,
+      installs: [install],
+    };
+  }
+
+  const env = options.env || process.env;
+  const installs = [];
+
+  for (const target of [
+    { tool: "codex", targetRoot: resolveCodexSkillsRoot(env) },
+    { tool: "claude-code", targetRoot: resolveClaudeCodeSkillsRoot(env) },
+  ]) {
+    installs.push(await installSkill({
+      ...options,
+      env,
+      sourcePath,
+      targetRoot: target.targetRoot,
+      tool: target.tool,
+    }));
+  }
+
+  return {
+    skillName: SKILL_NAME,
+    sourcePath,
+    installs,
+  };
+}

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-free";
-export const TEXT_MUSIC_MODELS = new Set(["music-2.6", "music-2.6-free"]);
+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 MINIMAX_CONFIG_RELATIVE_PATH = join("config", "minimax.json");
 
 async function pathExists(path) {
@@ -69,7 +69,7 @@ export function validateMinimaxConfig(config = {}) {
   const model = normalized.model || DEFAULT_MINIMAX_MODEL;
 
   if (!TEXT_MUSIC_MODELS.has(model)) {
-    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-2.6 or music-2.6-free.`);
+    throw new Error(`Unsupported MiniMax text music model: ${model}. Use music-3.0, music-2.6, or music-2.6-free.`);
   }
 
   return {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.7.0",
-  "description": "Install the Hyper Animator Codex skill for Codex.",
+  "version": "0.8.0",
+  "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {
     "hyper-animator-codex": "bin/hyper-animator-codex.mjs"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.mjs",
     "test": "node --test",
     "pack:check": "npm pack --dry-run"
   },

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

@@ -7,30 +7,36 @@ description: Use when a user asks Codex to create, plan, author, customize, vali
 
 ## Overview
 
-Turn a natural-language animation or video brief into a validated HyperFrames HTML composition and render handoff. Use catalog items for intent matching and visual references, but keep user confirmation before render.
+Turn a natural-language animation or video brief into a validated HyperFrames HTML composition and render handoff. Use the HyperFrames catalog for renderable building blocks and the ShotCraft catalog for shot-language references, but keep user confirmation before render.
 
 ## Required Flow
 
-1. 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.
-2. 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.
-3. Capture the raw request and extract an initial intent profile: purpose, format, duration, content inputs, style tags, motion tags, and needed roles.
-4. If purpose, format, or core content is unclear, ask the first clarification round before choosing catalog items.
-5. Read `references/hyperframes-catalog-map.json` and score candidates by keyword, intent domain, format, role, style, motion, and constraints.
-6. Pick candidate blocks/components for main scene, caption, effects, transitions, and outro.
-7. Decide generation mode:
+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.
+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.
+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.
+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.
-8. Clarify audio: ask whether to use narration, subtitles, animation/transition sound effects, and background music.
-9. If narration is used, use `scripts/generate_minimax_tts.mjs` for voice listing and TTS. Do not construct MiniMax TTS HTTP calls directly. If subtitles are requested, run `scripts/generate_subtitles.mjs`.
-10. If background music is requested or undecided, read `references/minimax-music-workflow.md` and use `scripts/generate_minimax_music.mjs` for every MiniMax music request. Do not construct MiniMax music HTTP calls directly. If MiniMax is unavailable or declined, ask for a local audio path or continue without BGM.
-11. 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.
-12. Ask the second clarification round with 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.
-13. Write or assemble HTML. 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.
-14. 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.
-15. Run pre-render quality gates on the base HTML.
-16. 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`.
-17. Show a concise plan summary and preview path or HTML file to the user. Ask for confirmation before video render.
-18. 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 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.
 
 ## Interactive Questions
 
@@ -49,6 +55,10 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 - Read `references/narration-audio-workflow.md` when first-run detection, restart, outline, narration, voiceover, subtitle, BGM timing, or final audio/video mixing is mentioned.
 - Read `references/hyperframes-intent-workflow.md` for the full AskUserQuestion workflow, generation-mode rules, scoring model, and render confirmation requirements.
 - 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 `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.
 - Read `references/minimax-music-workflow.md` when generated background music, MiniMax, music prompt, instrumental/vocal choice, or provider fallback is mentioned.
 - Read `references/beat-sync-workflow.md` when sound effects, background music, soundtrack, beat sync, rhythm, BPM, audio-reactive animation, or transition timing to music is mentioned.
@@ -59,6 +69,9 @@ Do not ask everything upfront when the brief is already specific. Ask only for m
 
 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.
+- 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.
 - Complete scene requests prioritize block items with `main_scene`.
@@ -82,6 +95,8 @@ Generated block HTML must include:
 - `window.__timelines[id]` registration;
 - 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;
+- positive numeric dimensions and duration;
 - readable text at the target video dimensions.
 
 Preview HTML must pass:
@@ -92,16 +107,39 @@ python3 scripts/validate_hyperframes_html.py path/to/composition.preview.html --
 
 If the validator fails, fix the HTML before asking the user to approve render.
 
+## Production Quality Gates
+
+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;
+- 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
+  time;
+- brand outro holds at least one second and dense motion resolves into at least
+  0.5 seconds of readable rest;
+- strong-rhythm cuts are checked against the beat map; after render, offsets
+  above three frames require correction.
+
+Use `references/shotcraft/references/final-review.md` and
+`references/shotcraft/references/aesthetic-rules.md` as checklists. A separate
+review agent is optional, not required; do not create one unless the user asks
+for delegated review.
+
 ## Render Handoff
 
 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;
 - 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;
 - sound effects and background music choices;
-- MiniMax provider status, model, generated audio path, metadata path, and redacted config source when MiniMax is used;
+- MiniMax CN provider status, mainland endpoint, model, generated audio path or narration manifest, metadata path, and redacted config source when MiniMax is used;
 - beat map path, BPM, duration, and timing assumptions when beat-sync is enabled;
 - base HTML path and preview HTML path;
 - preview controls injection status and page count source;

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "Hyper Animator Codex"
-  short_description: "Turn animation briefs into HyperFrames videos"
-  default_prompt: "Use $hyper-animator-codex to turn my animation brief into HyperFrames HTML and a rendered video."
+  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."