hyper-animator-codex 0.7.1 → 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
 
@@ -66,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 \
@@ -135,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

@@ -26,7 +26,7 @@ Options:
   --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:

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,6 +1,6 @@
 {
   "name": "hyper-animator-codex",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {

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."

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

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hyper-animator-codex.local/contracts/shot-plan.schema.json",
+  "title": "Hyper Animator dual-catalog shot plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "generation_mode",
+    "catalog_strategy",
+    "dimensions",
+    "duration_seconds",
+    "audio",
+    "model_routing",
+    "shots"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0"
+    },
+    "generation_mode": {
+      "enum": [
+        "assemble_existing_catalog_items",
+        "generate_new_hyperframes_html"
+      ]
+    },
+    "catalog_strategy": {
+      "const": "dual_catalog"
+    },
+    "dimensions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "width",
+        "height"
+      ],
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "duration_seconds": {
+      "type": "number",
+      "exclusiveMinimum": 0
+    },
+    "audio": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "narration",
+        "bgm"
+      ],
+      "properties": {
+        "narration": {
+          "$ref": "#/$defs/audioTrack"
+        },
+        "bgm": {
+          "$ref": "#/$defs/audioTrack"
+        }
+      }
+    },
+    "model_routing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "page_animation_authoring",
+        "planning_and_validation"
+      ],
+      "properties": {
+        "page_animation_authoring": {
+          "const": "gpt-5.6-sol"
+        },
+        "planning_and_validation": {
+          "not": {
+            "const": "gpt-5.6-sol"
+          }
+        }
+      }
+    },
+    "shots": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/shot"
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "audioTrack": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "mode"
+      ],
+      "properties": {
+        "mode": {
+          "enum": [
+            "generated",
+            "user_local_file",
+            "none"
+          ]
+        },
+        "provider": {
+          "enum": [
+            "minimax_cn"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "generated"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "provider"
+            ],
+            "properties": {
+              "provider": {
+                "const": "minimax_cn"
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "mode": {
+                "const": "user_local_file"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "path"
+            ]
+          }
+        }
+      ]
+    },
+    "shot": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "start_seconds",
+        "end_seconds",
+        "purpose",
+        "hyperframes_refs",
+        "shotcraft_refs"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "start_seconds": {
+          "type": "number",
+          "minimum": 0
+        },
+        "end_seconds": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "purpose": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hyperframes_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "shotcraft_refs": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "narration_scene": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}

package/skills/hyper-animator-codex/contracts/workflow-policy.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "schema_version": "1.0.0",
+  "audio": {
+    "generated_narration": {
+      "provider": "minimax_cn",
+      "endpoint": "https://api.minimaxi.com/v1/t2a_v2",
+      "backup_endpoints": [
+        "https://api-bj.minimaxi.com/v1/t2a_v2"
+      ],
+      "voice_endpoint": "https://api.minimaxi.com/v1/get_voice",
+      "voice_backup_endpoints": [
+        "https://api-bj.minimaxi.com/v1/get_voice"
+      ],
+      "script": "scripts/generate_minimax_tts.mjs"
+    },
+    "generated_bgm": {
+      "provider": "minimax_cn",
+      "endpoint": "https://api.minimaxi.com/v1/music_generation",
+      "script": "scripts/generate_minimax_music.mjs"
+    },
+    "forbidden_providers": [
+      "heygen",
+      "kokoro",
+      "musicgen"
+    ],
+    "forbidden_commands": [
+      "hyperframes auth login",
+      "hyperframes tts"
+    ],
+    "automatic_fallback": false,
+    "automatic_runtime_install": false,
+    "failure_choices": [
+      "retry_minimax_cn",
+      "use_user_local_file",
+      "skip_track"
+    ],
+    "endpoint_override": {
+      "production": false,
+      "test_env_flag": "MINIMAX_ALLOW_TEST_ENDPOINT"
+    }
+  },
+  "model_routing": {
+    "page_animation_authoring": {
+      "model": "gpt-5.6-sol",
+      "use_for": [
+        "page_generation",
+        "animation_authoring"
+      ]
+    },
+    "planning_and_validation": {
+      "model": "gpt-5.6-terra",
+      "use_for": [
+        "requirements",
+        "file_detection",
+        "catalog_query",
+        "shot_planning",
+        "audio_prompting",
+        "validation",
+        "packaging"
+      ]
+    }
+  },
+  "shotcraft": {
+    "role": "reference_knowledge",
+    "catalog_strategy": "dual_catalog",
+    "catalog_path": "references/shotcraft/catalog.json",
+    "query_script": "scripts/query_shotcraft.mjs",
+    "default_statuses": [
+      "implemented"
+    ],
+    "excluded_asset_extensions": [
+      ".mp4",
+      ".mov",
+      ".mp3",
+      ".wav",
+      ".m4a",
+      ".png",
+      ".jpg",
+      ".jpeg",
+      ".webp",
+      ".gif"
+    ]
+  }
+}