hyper-animator-codex 0.7.1 → 0.8.1

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, visual-first dual-catalog
+shot planning (HyperFrames + ShotCraft), HTML animation authoring, MiniMax
+mainland China audio after visual approval, validation, 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 \
@@ -118,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
@@ -135,22 +146,71 @@ 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 `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
+```
+
+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.
@@ -161,7 +221,8 @@ node skills/hyper-animator-codex/scripts/generate_subtitles.mjs \
 
 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
@@ -188,6 +249,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

@@ -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.1",
   "description": "Install the Hyper Animator skill for Codex and Claude Code.",
   "type": "module",
   "bin": {
@@ -8,7 +8,10 @@
   },
   "scripts": {
     "postinstall": "node bin/postinstall.mjs",
+    "preflight": "node tools/verify-governance.mjs",
     "test": "node --test",
+    "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"
   },
   "files": [

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; 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. 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. 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.
-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 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, 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. Run pre-render quality gates on the base HTML.
+18. 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`.
+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
 
@@ -38,8 +44,8 @@ Prefer Codex interactive question tools such as `AskUserQuestion` or `request_us
 
 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.
 
@@ -49,6 +55,11 @@ 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 `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.
 - 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 +70,11 @@ 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.
+- 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.
 - Complete scene requests prioritize block items with `main_scene`.
@@ -82,6 +98,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 +110,42 @@ 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, 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
+  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 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

@@ -0,0 +1,280 @@
+{
+  "$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",
+    "workflow_stage",
+    "generation_mode",
+    "catalog_strategy",
+    "dimensions",
+    "duration_seconds",
+    "audio",
+    "model_routing",
+    "shots"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0"
+    },
+    "workflow_stage": {
+      "enum": [
+        "visual_draft",
+        "audio_integrated",
+        "render_ready"
+      ]
+    },
+    "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",
+            "deferred"
+          ]
+        },
+        "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",
+        "motion_contract"
+      ],
+      "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",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "shotcraft_refs": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true
+        },
+        "narration_scene": {
+          "type": [
+            "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
+            }
+          }
+        }
+      }
+    }
+  }
+}