From aa2b4fd770e8cef995a31c9d0c3973adb08a9d4c Mon Sep 17 00:00:00 2001
From: BeatSeat <137616995+BeatSeat@users.noreply.github.com>
Date: Sun, 15 Nov 2026 17:20:10 +0800
Subject: [PATCH 1/2] [feat] agent: add H3 cinematography compiler, storyboard
 audit, contact-sheet QC, and shot revision

## summary

- Add `opendirector.domain.h3_cinematography` encoding MiniMax-H3's canonical
  cinematography vocabulary (`SHOT_SIZES`, 20 `CAMERA_MOTIONS` across 12
  families, natural-English amplitude/speed phrasing, dialogue and
  `Overall Soundscape` / `Non-Diegetic Music` structure, `17n+5` latent frame
  grid math, and `<Picture N>` / `<Video N>` / `<Audio N>` ordinal alignment
  with `fasth3.native_prompt` embedded video soundtracks), plus
  `compile_h3_prompt`, `lint_h3_prompt`, and anti-homogenization `lint_shot_plan`.
- Extend `asset.preview` (`videoScope="contact_sheet"`) and
  `opendirector.media.shot_inspection` to render timestamped JPEG contact sheets
  for registered project video assets and local files while reporting
  deterministic `measuredFacts` (`meanFrameDelta`, `maxFrameDelta`,
  `suspectedFrozen`, `blackFrameIndices`, `matchesH3Grid`, `hasAudio`) separate
  from Agent creative review.
- Add `storyboard.audit` (`opendirector.application.creation_storyboard`) across
  HTTP `/queries`, Agent `query`, and `opendirector video audit-storyboard` to
  audit cross-shot `Subject` anchor continuity, upstream keyframe readiness,
  continuation chain depth, unlinked timeline clips, and pilot-gate budgets on
  live `ProjectSnapshot` state.
- Extend `opendirector video` (`create --last-frame/--continue-from`,
  `compile-h3-prompt`, `lint-h3-prompt`, `lint-shot-plan`, `audit-storyboard`,
  `inspect-shot --asset`, and lineage-aware `revise-shot`), ship the built-in
  `h3-shot-director` Agent skill, regenerate creation contracts, and update
  bilingual CLI documentation.

## validation

- `python scripts/generate_contracts.py --check`
- `lint-imports`
- `pytest tests/test_h3_shot_orchestration.py tests/test_creation_contracts.py tests/test_skill_snapshot.py tests/test_agent_metadata.py tests/test_agent_gateway.py tests/test_cli.py -q`
- `npm run check:i18n`

Fixes: #338
Refs: #107, #191, #261, #263
---
 apps/api/src/opendirector_api/creation.py     |  27 +-
 docs/guides/cli.md                            |  40 +
 .../agent/skills/h3-shot-director/SKILL.md    |  21 +
 .../skills/h3-shot-director/h3-vocabulary.md  |  71 ++
 .../h3-shot-director/shot-orchestration.md    |  85 ++
 packages/core/src/opendirector/agent/tools.py |   8 +-
 .../application/creation_assets.py            |  45 +-
 .../application/creation_canvas.py            |  18 +-
 .../application/creation_storyboard.py        | 558 +++++++++++
 packages/core/src/opendirector/cli.py         | 297 +++++-
 .../opendirector/domain/creation/commands.py  |  19 +-
 .../opendirector/domain/h3_cinematography.py  | 689 ++++++++++++++
 .../src/opendirector/media/shot_inspection.py | 244 +++++
 src/contracts/creation.schema.json            | 236 ++++-
 src/contracts/generated.ts                    |  24 +-
 tests/test_h3_shot_orchestration.py           | 890 ++++++++++++++++++
 16 files changed, 3245 insertions(+), 27 deletions(-)
 create mode 100644 packages/agent/skills/h3-shot-director/SKILL.md
 create mode 100644 packages/agent/skills/h3-shot-director/h3-vocabulary.md
 create mode 100644 packages/agent/skills/h3-shot-director/shot-orchestration.md
 create mode 100644 packages/core/src/opendirector/application/creation_storyboard.py
 create mode 100644 packages/core/src/opendirector/domain/h3_cinematography.py
 create mode 100644 packages/core/src/opendirector/media/shot_inspection.py
 create mode 100644 tests/test_h3_shot_orchestration.py

diff --git a/apps/api/src/opendirector_api/creation.py b/apps/api/src/opendirector_api/creation.py
index c1de28496..9e17aa54c 100644
--- a/apps/api/src/opendirector_api/creation.py
+++ b/apps/api/src/opendirector_api/creation.py
@@ -1,4 +1,5 @@
 """Authoritative project endpoints for the canvas creation workflow."""
+from typing import Literal
 from uuid import UUID
 from pathlib import Path
 from base64 import b64encode
@@ -185,13 +186,33 @@ async def query(project_id: UUID, value: CreationQuery):
         result = await canvas.query(value)
         if value.type == 'asset.preview' and 'preview' in result:
             result['preview'].pop('path')
-            result['preview']['url'] = f'/api/creation/projects/{project_id}/assets/{value.objectId}/preview'
+            base_url = f'/api/creation/projects/{project_id}/assets/{value.objectId}/preview'
+            if value.videoScope == 'contact_sheet':
+                result['preview']['url'] = (
+                    f'{base_url}?video_scope=contact_sheet&columns={value.columns}&rows={value.rows}'
+                )
+            else:
+                result['preview']['url'] = base_url
         return result
 
     @router.get('/projects/{project_id}/assets/{asset_id}/preview')
-    async def asset_preview(project_id: UUID, asset_id: UUID):
+    async def asset_preview(
+        project_id: UUID,
+        asset_id: UUID,
+        video_scope: Literal['first_frame', 'contact_sheet'] = Query(default='first_frame'),
+        columns: int = Query(default=4, ge=1, le=8),
+        rows: int = Query(default=3, ge=1, le=8),
+    ):
         target = projects.local.state_dir / 'previews' / str(project_id)
-        result = await run_in_threadpool(assets.preview, project_id, asset_id, target)
+        result = await run_in_threadpool(
+            assets.preview,
+            project_id,
+            asset_id,
+            target,
+            video_scope=video_scope,
+            columns=columns,
+            rows=rows,
+        )
         if 'preview' not in result:
             return result
         return FileResponse(result['preview']['path'], media_type=result['preview']['mimeType'])
diff --git a/docs/guides/cli.md b/docs/guides/cli.md
index cc85732e2..a7f6f732b 100644
--- a/docs/guides/cli.md
+++ b/docs/guides/cli.md
@@ -42,6 +42,46 @@ CLI 输出 JSON。修改回执附带对应的 assetId、itemId、specId 及其
 Agent 的 Shell 通过 PATH 使用同一个 `opendirector`。宿主提供受令牌保护的本轮连接、工程范围、编辑会话和执行目录，文件登记限制在本轮执行目录。每次调用产生业务活动及回执，供聊天与轨迹页展示。
 
 
+## H3 专业分镜提示词编排、连续性审计、多帧质检与单镜头局部修订
+
+`opendirector video` 支持首帧（`--first-frame`）、尾帧（`--last-frame`）、首尾帧插值（同时传 `--first-frame` 与 `--last-frame`）、多模态参考（`--reference-item`）与续写模式（`--continue-from`），并提供 H3 分镜计划校验、结构化提示词编译/标签校验、工程级跨镜头连续性审计（`storyboard.audit`）、视频多帧拼图预览与客观测量质检（`measuredFacts`），以及不破坏相邻轨道与字幕的时间线单镜头局部替换：
+
+```bash
+# 校验多镜头景别与运镜多样性（防止同质化）及 4—15 秒时长约束
+opendirector video lint-shot-plan --file ./shot-plan.json
+
+# 编译并校验符合 MiniMax-H3 规范的 T2VA / I2VA / FL2VA / L2VA / Ref2VA 英文提示词
+opendirector video compile-h3-prompt --file ./shot-01-spec.json
+
+# 创建首尾帧（FL2VA）或续写视频节点，并结合工程实际参考顺序校验 <Picture N>/<Video N>/<Audio N> 序号
+opendirector --project PROJECT_UUID video create \
+  --model MiniMax-H3 --prompt "..." --duration 6 --x 480 --y 0 \
+  --first-frame START_ITEM_UUID --last-frame END_ITEM_UUID --title "Shot 01"
+opendirector --project PROJECT_UUID video lint-h3-prompt --spec-id SPEC_UUID
+
+# 审计当前工程跨镜头角色锚点（Subject）、上游关键帧就绪度与试拍门控预算
+opendirector --project PROJECT_UUID video audit-storyboard --timeline-editor TIMELINE_EDITOR_UUID
+
+# 按工程视频 assetId 或执行目录文件做带时间戳十二宫格审看与客观静帧/黑场测量（不污染工程素材库）
+opendirector --project PROJECT_UUID video inspect-shot --asset VIDEO_ASSET_UUID --contact-sheet ./shot-01-qc.jpg
+opendirector video inspect-shot ./shot-01.mp4 --contact-sheet ./shot-01-qc.jpg
+
+# 时间线单镜头局部重拍替换：可显式指定片段与素材，也可直接按已关联的上游画布节点同步最新采纳结果
+opendirector --project PROJECT_UUID video revise-shot \
+  --timeline-editor TIMELINE_EDITOR_UUID --source-item SHOT_2_ITEM_UUID
+```
+
+### H3 shot orchestration, continuity audit, multi-frame QC, and single-shot timeline revision
+
+`opendirector video` supports first-frame (`--first-frame`), last-frame (`--last-frame`), first-and-last keyframe (`FL2VA` with both options), reference (`--reference-item`), and continuation (`--continue-from`) creation, paired with H3 shot-plan diversity checks, structured prompt compilation/linting, live project continuity auditing (`storyboard.audit`), multi-frame contact-sheet QC (`measuredFacts`), and surgical single-clip timeline replacement:
+
+- `video lint-shot-plan` checks 4–15s H3 bounds, canonical framing/camera vocabulary, and consecutive `(shotSize, cameraMotion)` repetition before creating nodes.
+- `video compile-h3-prompt` builds canonical `T2VA`, `I2VA`, `FL2VA`, `L2VA`, or 6-section `Ref2VA` prompts; `video lint-h3-prompt --spec-id` verifies alignment headers, `[Shot N] At MM:SS.mmm` cut timestamps, and `<Picture N>` / `<Video N>` / `<Audio N>` ordinals against the node's live active references (including embedded video audio offsets).
+- `video audit-storyboard` (`query storyboard.audit`) inspects the live `ProjectSnapshot` to detect unanchored `T2VA` shots alongside `Subject` anchors, unrendered upstream keyframes, excessive continuation chains, unlinked timeline clips, and pilot-gate pending video duration.
+- `video inspect-shot` (and `query asset.preview` with `videoScope="contact_sheet"`) renders a timestamped JPEG contact sheet for a registered project video `assetId` or local file and reports deterministic `measuredFacts` (`suspectedFrozen`, `blackFrameIndices`, `matchesH3Grid`, `hasAudio`) separately from creative judgment.
+- `video revise-shot` replaces only the target clip's `AssetRef` inside a `timeline` `EditorDocument` (by `--clip-id`/`--asset` or automatically following `--source-item` via `inputConnections`) using its exact `expectedVersions`, preserving neighbor clips, audio tracks, fonts, and timed text overlays.
+
+
 ## 检查已有生成结果
 
 `job show` / `job wait` 在任务成功后返回 `delivery`：已登记的 AssetRef、当前采用状态及展示该素材的画布项。生成成功不等于质量验收；Agent 应检查现有素材。复制到执行目录做媒体探测、抽帧和审看不需要重新发布，也不应为同一次交付新增画布项。编辑产生的新交付文件才需要登记；独立副本展示应有用户要求。
diff --git a/packages/agent/skills/h3-shot-director/SKILL.md b/packages/agent/skills/h3-shot-director/SKILL.md
new file mode 100644
index 000000000..b6c30f55c
--- /dev/null
+++ b/packages/agent/skills/h3-shot-director/SKILL.md
@@ -0,0 +1,21 @@
+---
+name: h3-shot-director
+description: Direct single-shot and multi-shot MiniMax-H3 videos using canonical cinematography vocabulary, structured T2VA/I2VA/FL2VA/L2VA/Ref2VA prompt compilation, pilot-anchor gates, contact-sheet QC, and surgical single-shot timeline revision.
+---
+
+# H3 Shot Director
+
+Translate creative requests or reference videos into executable, visually diverse MiniMax-H3 shot plans, canonical H3 prompts, verified media deliveries, and editable timelines through `opendirector` CLI commands on `PATH`.
+
+Planning or prompt drafting alone never authorizes submitting remote generation jobs. Separate planning receipts, generation execution facts, technical/visual QC, and user adoption.
+
+## End-to-End Workflow
+
+1. **Inspect Project & Reference Footage**: Run `opendirector project show` and `opendirector model list --kind video` first. When adapting a reference video, copy or read it inside the authorized execution directory and run `opendirector video inspect-shot <file> --contact-sheet ./ref-sheet.jpg` to extract stream facts (`durationSeconds`, `width`, `height`, `fps`, `hasAudio`, `matchesH3Grid`) and a timestamped visual contact sheet before planning shots.
+2. **Draft & Lint Anti-Homogenization Shot Plan**: Read [shot-orchestration.md](shot-orchestration.md). Produce a shot table specifying `shotSize`, `cameraMotion`, `durationSeconds` (`4–15s`), `mode` (`t2va`, `i2va`, `fl2va`, `l2va`, `ref2va`, or `continuation`), anchor assets, and audiovisual action. Validate the plan with `opendirector video lint-shot-plan --file ./shot-plan.json` so 3+ consecutive shots never repeat the same `(shotSize, cameraMotion)` pair.
+3. **Pilot Anchor & Project Continuity Gate**: For multi-shot sequences (3+ shots) or costly cloud runs, bind shared `Subject` or scene anchor assets across shots, generate/adopt keyframe anchors first, and audit the live project graph with `opendirector video audit-storyboard` (`query storyboard.audit`) to catch unanchored `T2VA` islands, unrendered upstream keyframes, or monotonous shot streaks before submitting batch video jobs.
+4. **Compile & Lint Canonical H3 Prompts**: Read [h3-vocabulary.md](h3-vocabulary.md). Write prompts strictly in H3's English section structure while preserving verbatim original language inside `<d>[Language] ...</d>` and quoted on-screen text. Use `opendirector video compile-h3-prompt --file ./shot-spec.json` to build structured prompts and `opendirector video lint-h3-prompt --spec-id <SPEC_UUID>` after `video create` to verify alignment headers, cut timestamps, and `<Picture N>` / `<Video N>` / `<Audio N>` ordinals (accounting for embedded audio tracks on reference videos).
+5. **Execute, Inspect Across Time & Assemble**: Create nodes with `opendirector video create` (`--first-frame`, `--last-frame`, `--reference-item`, or `--continue-from`), submit authorized jobs, wait with `job wait`, and inspect delivered project video assets across time via `opendirector video inspect-shot --asset <ASSET_UUID>` (or `query asset.preview` with `videoScope="contact_sheet"`). Report deterministic `measuredFacts` (`suspectedFrozen`, `blackFrameIndices`, `matchesH3Grid`, `hasAudio`) separately from your visual/creative review, without importing inspection contact sheets as project assets. Assemble verified clips onto an editable timeline (`editor create` / `editor save`) with `inputConnections` linking each `slotId` to its source shot item.
+6. **Surgical Single-Shot Local Revision**: When a user or QC review asks to reshoot or fix one shot in an assembled timeline, regenerate and adopt only that shot's replacement candidate, then run `opendirector video revise-shot --timeline-editor <EDITOR_UUID> --source-item <SHOT_ITEM_UUID>` (or `--clip-id <CLIP_ID> --asset <NEW_ASSET_UUID>`) so neighbor clips, audio tracks, fonts, and text overlays remain untouched.
+
+Resolve relative links (`h3-vocabulary.md`, `shot-orchestration.md`) from this skill directory. Keep user model, resolution, aspect-ratio, and audio choices intact unless explicitly asked to change them.
diff --git a/packages/agent/skills/h3-shot-director/h3-vocabulary.md b/packages/agent/skills/h3-shot-director/h3-vocabulary.md
new file mode 100644
index 000000000..5a94514f7
--- /dev/null
+++ b/packages/agent/skills/h3-shot-director/h3-vocabulary.md
@@ -0,0 +1,71 @@
+# MiniMax-H3 Cinematography & Prompt Grammar
+
+MiniMax-H3 (`MiniMax-H3`, `MiniMax-H3-Max`, `MiniMax-H3-Highspeed`, `MiniMax-H3-Lite`, and `vllm_omni` / FastH3 deployments) expects structured English prompts with exact section order, natural-English camera actions, sequential `[Shot N]` markers, and strict per-modality reference ordinals.
+
+## 1. Choosing the H3 Mode
+
+| Mode | CLI `video create` flags | Prompt structure | Best use case |
+| --- | --- | --- | --- |
+| `t2va` | *(no media flags)* | 3 core sections (no alignment header) | Pure text-to-audiovisual shot when no visual anchor exists yet |
+| `i2va` | `--first-frame <ITEM>` | `I2VA` alignment line + blank line + 3 core sections | Forward action starting from an anchor keyframe at `0.00s` |
+| `fl2va` | `--first-frame <ITEM> --last-frame <ITEM>` | `FL2VA` alignment line + blank line + 3 core sections | Controlled state/pose/camera transition bridging two keyframes (prefer single shot) |
+| `l2va` | `--last-frame <ITEM>` | `L2VA` alignment line + blank line + 3 core sections | Plausible preceding action converging onto a target landing frame at `S.SSs` |
+| `ref2va` | `--reference-item <ITEM> ...` | 6 full-reference sections | Multi-subject identity consistency, voice timbre reference, or source-video structure/editing |
+| `continuation` | `--continue-from <VIDEO_ITEM>` | Continuity prompt extending prior latent tail | Seamless multi-segment extension on `vllm_omni` (`17n+5` frame grid at 24 fps) |
+
+Duration bounds are `4.0–15.0` seconds per H3 generation. On 24-fps FastH3 / `vllm_omni`, frames snap up to `17n + 5` (for example `5s -> 124 frames`, `7s -> 175 frames`).
+
+## 2. Exact Alignment Headers (`I2VA` / `FL2VA` / `L2VA`)
+
+Place the alignment instruction on line 1, followed by **one blank line**, where `N` is the final `[Shot N]` index and `S.SS` is the target duration to two decimals:
+
+- **I2VA**:
+  `For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.`
+- **FL2VA**:
+  `How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot N) aligns with the S.SS-second mark of the target video.`
+- **L2VA**:
+  `How the reference pictures align with the target video — <Picture 1> (from [Shot N]) aligns with the S.SS-second mark of the target video.`
+
+`T2VA` and `Ref2VA` never include a keyframe alignment header.
+
+## 3. Core Sections: Base (`T2VA` / `I2VA` / `FL2VA` / `L2VA`) vs `Ref2VA`
+
+### Base 3-Section Order
+1. `integrated_multimodal_description:` — Style + `[Shot 1]` (never timestamped) + optional `[Shot 2] At MM:SS.mmm, the camera cuts to ...`, including subject actions, camera motion, `(S1)` dialogue `<d>[Language] ...</d>`, and synchronized diegetic sound.
+2. `overall_soundscape:` — 1–4 sentences of continuous room tone, weather, footsteps, cloth, and non-verbal human sound across the clip (`N/A` only when explicit complete silence is requested). Never put `<d>` here.
+3. `non_diegetic_music:` — 1–3 sentences describing instrumentation, tempo, and dynamics of audience-only score (avoid abstract mood words; use `N/A` when unscored).
+
+### Ref2VA 6-Section Order
+1. `subject_definitions:` — One line per tracked `<Subject N>`, frame-anchor `<Picture N>`, structural `<Video N>`, or `<Audio N>`. Cite source images inside `<Subject N>` definitions when used only for identity/style.
+2. `summary:` — Must begin with `[task type]` combining `keyframe completion`, `reference generation`, `video editing`, `video continuation`, `audio reuse`, or `audio reference` with ` + `.
+3. `retention_analysis:` — One line per label using fixed markers (`fully_preserved`, `partially_preserved`, `attribute_transfer`, `weak_reference` for visual labels; `fully_copy`, `partially_copy`, `reference`, `weak_reference` for `<Audio N>`). Never write `(S1)` speaker IDs in `retention_analysis`.
+4. `detailed_description:` — 1–2 style sentences **before** `[Shot 1]`, followed by shot-by-shot playback description weaving `<Subject N>`, `<Picture N>`, `<Video N>`, `<Audio N>`, and `(Sx)` `<d>[Language] ...</d>`.
+5. `overall_soundscape:`
+6. `non_diegetic_music:`
+
+## 4. Reference Ordinal Rule (`<Audio N>` Offset)
+
+OpenDirector's FastH3 adapter numbers each modality in reference order, **reserving `<Audio 1..K>` for reference videos that contain an audio stream (`hasAudio: true`) before standalone audio references**:
+
+- Example: Reference 1 = `hero.mp4` (`hasAudio: true`), Reference 2 = `voice.wav` (`audio`).
+  - `hero.mp4` -> `<Video 1>` (and embedded soundtrack `<Audio 1>`)
+  - `voice.wav` -> `<Audio 2>` (not `<Audio 1>`!)
+- Always run `opendirector video lint-h3-prompt --spec-id <SPEC_UUID>` before `generation submit` to inspect `referenceOrdinals` and catch off-by-one `<Audio N>` tags automatically.
+
+## 5. Camera Vocabulary & Framing Variety
+
+Express camera movement as a **natural English action** inside the shot sentence rather than comma-separated tags at the end:
+
+- **Shot sizes**: `extreme wide shot`, `wide shot`, `medium-wide shot`, `medium shot`, `medium close-up`, `close shot`, `close-up`, `extreme close-up`, `over-the-shoulder shot`, `two-shot`, `low-angle shot`, `high-angle shot`, `overhead shot`, `bird's-eye shot`.
+- **12 H3 motion families**: `Zoom In` / `Zoom Out`, `Push In` / `Pull Out`, `Pan Left` / `Pan Right`, `Truck Left` / `Truck Right`, `Tilt Up` / `Tilt Down`, `Pedestal Up` / `Pedestal Down`, `Arc Shot`, `Tracking Shot`, `Static Shot`, `Shake Slightly` / `Shake Strongly`, `POV`, `Roll Clockwise` / `Roll Counterclockwise`.
+- **Amplitude & speed** (omit medium/normal): `with small amplitude` / `with large amplitude`, `at slow speed` / `at fast speed`.
+- Example: `The camera pushes in with small amplitude at slow speed toward the brass key in her palm.`
+
+## 6. Dialogue, Voiceover, and On-Screen Text
+
+- Assign `(S1)`, `(S2)` in order of first vocal event; reuse across shots. Non-speaking characters receive no speaker ID.
+- Keep verbatim spoken words and original language inside `<d>[Language] ...</d>`:
+  `The calm detective (S1) says: <d>[Chinese] 先别动那封信。</d>`
+- Off-screen voiceover must use `says in an off-screen voiceover:` and state closed lips immediately after `</d>`:
+  `The man (S1) says in an off-screen voiceover: <d>[English] We never returned.</d> while his lips remain completely closed.`
+- Use `<scenetrans>` on both sides when speech crosses an internal `[Shot N]` cut, and `<cutoff>` when truncated by clip end. Quote visible signage/text verbatim in English double quotes (for example `"24H OPEN"`).
diff --git a/packages/agent/skills/h3-shot-director/shot-orchestration.md b/packages/agent/skills/h3-shot-director/shot-orchestration.md
new file mode 100644
index 000000000..46c87b514
--- /dev/null
+++ b/packages/agent/skills/h3-shot-director/shot-orchestration.md
@@ -0,0 +1,85 @@
+# Multi-Shot Orchestration, QC & Local Timeline Revision
+
+## 1. Anti-Homogenization Shot Planning
+
+Before creating generation nodes for a multi-shot film or reference-video remake, write a JSON shot plan in the execution directory and validate it:
+
+```json
+{
+  "shots": [
+    {"shotNumber": 1, "durationSeconds": 5, "mode": "i2va", "shotSize": "wide shot", "cameraMotion": "Push In", "action": "Establish rain-slicked alley and courier silhouette"},
+    {"shotNumber": 2, "durationSeconds": 5, "mode": "ref2va", "shotSize": "medium close-up", "cameraMotion": "Truck Right", "action": "Courier checks glowing parcel address"},
+    {"shotNumber": 3, "durationSeconds": 6, "mode": "fl2va", "shotSize": "close-up", "cameraMotion": "Tilt Up", "action": "Fingers break wax seal and lift eyes toward doorway"}
+  ]
+}
+```
+
+```bash
+opendirector video lint-shot-plan --file ./shot-plan.json
+```
+
+Design rules for cinematic rhythm:
+- Alternate spatial scale (`wide shot` -> `medium close-up` -> `close-up` or `over-the-shoulder shot`) so cuts introduce new visual information rather than micro-jumping from a nearly identical angle.
+- Never repeat the exact `(shotSize, cameraMotion)` pair for 3+ consecutive shots.
+- Balance moving camera shots (`Push In`, `Truck Right`, `Arc Shot`, `Tracking Shot`) with deliberate `Static Shot` beats during rapid subject motion or dialogue punchlines.
+
+## 2. Pilot Anchor Gate Before Full Batch Submission
+
+To avoid wasting generation time and quota on drifted character faces or mismatched lighting:
+1. Prepare or generate reusable character/environment anchor assets first (or extract reference anchors when authorized).
+2. On sequences of 3+ shots or commercial API models, generate and inspect the anchor keyframes or Shot 1 pilot before submitting the remaining shots, unless the user explicitly instructed full immediate execution.
+3. Arrange canvas nodes on clean non-overlapping coordinates (`--x`, `--y`) read from `opendirector project show`, grouping anchor assets to the left and sequential shot nodes left-to-right.
+
+## 3. Compiling & Verifying H3 Prompts via CLI
+
+Compile structured shot specs deterministically instead of hand-assembling headers:
+
+```bash
+opendirector video compile-h3-prompt --file ./shot-01-spec.json
+```
+
+After creating the project node (`opendirector video create ...`), verify the persisted `GenerationSpec` against its live active references before submitting:
+
+```bash
+opendirector --project PROJECT_UUID video lint-h3-prompt --spec-id SPEC_UUID
+```
+
+## 4. Live Storyboard Continuity Audit & Pilot Gate
+
+Before submitting expensive multi-shot video jobs, audit the live project graph (`ProjectSnapshot`):
+
+```bash
+opendirector --project PROJECT_UUID video audit-storyboard
+# Or scoped to a timeline / canvas group:
+opendirector --project PROJECT_UUID video audit-storyboard --timeline-editor TIMELINE_EDITOR_UUID
+```
+
+Inspect `gate` (`readyShotSpecIds`, `blockedShotSpecIds`, `estimatedPendingVideoSeconds`), `continuity.warnings` (shots missing shared `Subject` anchors or timeline clips missing `inputConnections`), and `sequenceLint`.
+
+## 5. Multi-Modal Temporal QC (`contact_sheet` + `measuredFacts`)
+
+A `"succeeded"` job receipt proves delivery, not visual or narrative quality, and a single `first_frame` preview cannot reveal frozen motion or mid-shot morphing. Inspect registered project video assets across time:
+
+```bash
+opendirector --project PROJECT_UUID video inspect-shot --asset VIDEO_ASSET_UUID --contact-sheet ./shot-01-qc.jpg
+# Or inspect a local file in the execution directory:
+opendirector video inspect-shot ./shot-01.mp4 --contact-sheet ./shot-01-qc.jpg
+```
+
+Keep three layers strictly distinct when reporting to the user:
+- **Deterministic `measuredFacts`**: `technical` (`durationSeconds`, `width`x`height`, `hasAudio`, `matchesH3Grid`), `motion` (`meanFrameDelta`, `maxFrameDelta`, `suspectedFrozen`), and `exposure` (`blackFrameIndices`, `blackFrameRatio`).
+- **Agent visual review (via contact sheet)**: Identity retention across tiles `#01..#12`, camera trajectory fidelity, hand/prop continuity, and `FL2VA` / `L2VA` landing pose accuracy.
+- **User creative approval**: Adopt (`result select`) or reshoot within explicit user authorization. Do **not** import `./shot-01-qc.jpg` as a project asset unless requested.
+
+## 6. Timeline Assembly & Lineage-Aware Single-Shot Revision
+
+1. Assemble verified shot `AssetRef`s onto a single `visual` track in an editable `timeline` `EditorDocument` (`editor create` / `editor save`) with `inputConnections` recording each `slotId`'s `sourceId` shot node.
+2. When one shot needs a reshoot (for example `shot-2` has an object-count defect or dialogue change):
+   - Regenerate, inspect, and adopt (`result select`) only that shot's node.
+   - Sync **only** that clip on the timeline (auto-resolving `clipId` and the adopted `Asset` from `--source-item`, or passing `--clip-id` / `--asset` explicitly):
+     ```bash
+     opendirector --project PROJECT_UUID video revise-shot \
+       --timeline-editor TIMELINE_EDITOR_UUID \
+       --source-item SHOT_2_CANVAS_ITEM_UUID
+     ```
+   - By default `--keep-slot-duration` preserves the clip's existing timeline span (clamped safely if the new asset is shorter) so downstream audio cues and timed text overlays stay aligned; pass `--use-asset-duration` or `--in-point` / `--out-point` when intentionally retiming the cut.
diff --git a/packages/core/src/opendirector/agent/tools.py b/packages/core/src/opendirector/agent/tools.py
index 64da5bd17..86c7cf298 100644
--- a/packages/core/src/opendirector/agent/tools.py
+++ b/packages/core/src/opendirector/agent/tools.py
@@ -71,6 +71,7 @@ def query_guidance(failure):
 Successful generation results are already registered project assets. Inspect them using their existing asset identity and canvas item. Do not publish inspection copies or extracted inspection frames, or add another canvas item for the same delivery unless the user requests it. Publish newly created deliverables after editing or processing.
 A command receipt is execution evidence, not quality approval. Preserve user constraints.
 Plans and prompt requests do not authorize generation. Never resubmit an unknown job.
+When directing MiniMax-H3 video shots or multi-shot timelines, load the h3-shot-director skill when available, audit live cross-shot continuity and pilot readiness with opendirector video audit-storyboard (or query storyboard.audit), validate multi-shot plans with opendirector video lint-shot-plan, compile/lint canonical H3 prompts with opendirector video compile-h3-prompt and lint-h3-prompt, inspect rendered video assets across time via opendirector video inspect-shot --asset UUID (or query asset.preview with videoScope="contact_sheet") keeping measuredFacts distinct from creative judgment, and swap a single timeline clip locally via opendirector video revise-shot without regenerating unaffected shots.
 Use stable operation IDs for write retries; report unsupported media editing/export capabilities honestly.
 Reply in the same language as the user's latest request. Keep project content, quoted text, model names,
 identifiers and code unchanged. If a tool error is shown in another language, explain it in the user's language.
@@ -344,7 +345,12 @@ def recording():
                 # Asset IDs identify immutable content; repeating the source's
                 # full fingerprint here adds 65 characters to an already deep
                 # execution path and exceeds Windows' ordinary path limit.
-                destination = child(target, query.objectId.hex + source.suffix)
+                suffix = (
+                    f'-sheet-{query.columns}x{query.rows}{source.suffix}'
+                    if getattr(query, 'videoScope', 'first_frame') == 'contact_sheet'
+                    else source.suffix
+                )
+                destination = child(target, query.objectId.hex + suffix)
                 await asyncio.to_thread(shutil.copyfile, source, destination)
                 result['preview']['path'] = str(destination.resolve())
             return result
diff --git a/packages/core/src/opendirector/application/creation_assets.py b/packages/core/src/opendirector/application/creation_assets.py
index fbee3f0ab..fecb2633d 100644
--- a/packages/core/src/opendirector/application/creation_assets.py
+++ b/packages/core/src/opendirector/application/creation_assets.py
@@ -246,7 +246,16 @@ def signature():
             stream.close()
             raise
 
-    def preview(self, project_id: UUID, asset_id: UUID, target: Path) -> dict:
+    def preview(
+        self,
+        project_id: UUID,
+        asset_id: UUID,
+        target: Path,
+        *,
+        video_scope: str = 'first_frame',
+        columns: int = 4,
+        rows: int = 3,
+    ) -> dict:
         stream, asset = self.open_media(project_id, asset_id)
         with stream:
             target = gateway().directory(target)
@@ -259,6 +268,40 @@ def preview(self, project_id: UUID, asset_id: UUID, target: Path) -> dict:
                 content, _ = self.thumbnail(project_id, asset_id)
                 output, mime = gateway().child(target, stem + '.webp'), 'image/webp'
                 output.write_bytes(content)
+            elif asset.kind == 'video' and video_scope == 'contact_sheet':
+                from opendirector.media.shot_inspection import inspect_video_shot
+
+                output = gateway().child(target, f'{stem}-sheet-{columns}x{rows}.jpg')
+                mime = 'image/jpeg'
+                try:
+                    with TemporaryDirectory(prefix='source-', dir=target) as temporary:
+                        source = Path(temporary) / 'media.mp4'
+                        with source.open('wb') as destination:
+                            shutil.copyfileobj(stream, destination, length=1024 * 1024)
+                        inspected = inspect_video_shot(
+                            source,
+                            contact_sheet_path=output,
+                            columns=columns,
+                            rows=rows,
+                            overwrite_cache=True,
+                        )
+                except (OSError, subprocess.SubprocessError, ProjectError) as error:
+                    raise ProjectError('无法生成素材预览。', 422) from error
+                sheet_info = inspected['contactSheet'] or {}
+                return {
+                    'assetId': str(asset.id),
+                    'kind': asset.kind,
+                    'metadata': asset.metadata.model_dump(mode='json'),
+                    'preview': {
+                        'path': str(output.resolve()),
+                        'mimeType': mime,
+                        'scope': 'contact_sheet',
+                        'columns': columns,
+                        'rows': rows,
+                        'timestamps': sheet_info.get('timestamps', []),
+                    },
+                    'measuredFacts': inspected['measuredFacts'],
+                }
             elif asset.kind in {'video', 'audio'}:
                 output = gateway().child(target, stem + ('.jpg' if asset.kind == 'video' else '.wav'))
                 command = ['ffmpeg', '-nostdin', '-v', 'error', '-y']
diff --git a/packages/core/src/opendirector/application/creation_canvas.py b/packages/core/src/opendirector/application/creation_canvas.py
index 68faf53a2..8e2a1bf37 100644
--- a/packages/core/src/opendirector/application/creation_canvas.py
+++ b/packages/core/src/opendirector/application/creation_canvas.py
@@ -833,7 +833,15 @@ async def query(self, query: Query) -> JsonValue:
             return await self.wait_item_status(query.projectId, query.objectId, query.waitSeconds)
         if query.type == 'asset.preview':
             target = self.projects.local.state_dir / 'previews' / str(query.projectId)
-            return await asyncio.to_thread(CreationAssets(self.projects).preview, query.projectId, query.objectId, target)
+            return await asyncio.to_thread(
+                CreationAssets(self.projects).preview,
+                query.projectId,
+                query.objectId,
+                target,
+                video_scope=query.videoScope,
+                columns=query.columns,
+                rows=query.rows,
+            )
         return to_jsonable_python(await asyncio.to_thread(self.query_snapshot, query))
 
     def query_snapshot(self, query):
@@ -842,6 +850,14 @@ def query_snapshot(self, query):
         history = CreationHistory(self.projects)
         if query.type == 'project.get':
             return snapshot
+        if query.type == 'storyboard.audit':
+            from opendirector.application.creation_storyboard import audit_project_storyboard
+            return audit_project_storyboard(
+                snapshot,
+                timeline_editor_id=query.timelineEditorId,
+                group_id=query.groupId,
+                spec_ids=query.specIds,
+            )
         if query.type == 'generationSpec.versions':
             return history.versions(query.projectId, query.objectId)
         if query.type == 'canvas.versions':
diff --git a/packages/core/src/opendirector/application/creation_storyboard.py b/packages/core/src/opendirector/application/creation_storyboard.py
new file mode 100644
index 000000000..2b5f03e17
--- /dev/null
+++ b/packages/core/src/opendirector/application/creation_storyboard.py
@@ -0,0 +1,558 @@
+"""Project-level storyboard continuity auditing and lineage-aware shot revision."""
+from __future__ import annotations
+
+import json
+import re
+from uuid import UUID, uuid4, uuid5
+
+from opendirector.application.creation_canvas import current_asset
+from opendirector.domain.creation.editors import SubjectDocument, TimelineDocument
+from opendirector.domain.creation.generation import FollowingReference
+from opendirector.domain.creation.project import ProjectSnapshot
+from opendirector.domain.creation.validation import ContractError
+from opendirector.domain.h3_cinematography import (
+    CAMERA_MOTIONS,
+    SHOT_SIZES,
+    h3_reference_ordinals,
+    lint_h3_prompt,
+    lint_shot_plan,
+)
+from opendirector.domain.projects import ProjectError
+
+
+_SORTED_SHOT_SIZES = tuple(sorted(SHOT_SIZES, key=len, reverse=True))
+_SORTED_CAMERA_MOTIONS = tuple(sorted(CAMERA_MOTIONS, key=len, reverse=True))
+
+
+def extract_prompt_shot_features(prompt: str) -> dict[str, str | None]:
+    """Extract primary canonical H3 shot size and camera motion from prompt text."""
+    text = prompt or ""
+    found_size = None
+    for candidate in _SORTED_SHOT_SIZES:
+        if re.search(rf"(?<![A-Za-z]){re.escape(candidate)}(?![A-Za-z])", text, flags=re.IGNORECASE):
+            found_size = candidate
+            break
+    found_motion = None
+    for candidate in _SORTED_CAMERA_MOTIONS:
+        if re.search(rf"(?<![A-Za-z]){re.escape(candidate)}(?![A-Za-z])", text, flags=re.IGNORECASE):
+            found_motion = candidate
+            break
+    return {"shotSize": found_size, "cameraMotion": found_motion}
+
+
+def _infer_h3_mode(video_mode: str | None, roles: list[str]) -> str:
+    if video_mode == "continuation":
+        return "continuation"
+    if video_mode == "reference":
+        return "ref2va"
+    if "first_frame" in roles and "last_frame" in roles:
+        return "fl2va"
+    if "first_frame" in roles:
+        return "i2va"
+    if "last_frame" in roles:
+        return "l2va"
+    return "t2va"
+
+
+def _continuation_depth(snapshot: ProjectSnapshot, spec_id: UUID) -> int:
+    items_by_id = {item.id: item for item in snapshot.canvasItems}
+    depth = 0
+    seen: set[UUID] = set()
+    current_spec_id: UUID | None = spec_id
+    while current_spec_id is not None and current_spec_id not in seen:
+        seen.add(current_spec_id)
+        cont_ref = next(
+            (r for r in snapshot.references
+             if r.active and r.targetSpecId == current_spec_id and r.role == "continuation"),
+            None,
+        )
+        if cont_ref is None:
+            break
+        depth += 1
+        if isinstance(cont_ref, FollowingReference):
+            src_item = items_by_id.get(cont_ref.source.id)
+            if src_item and src_item.binding.role == "generation":
+                current_spec_id = src_item.binding.objectRef.id
+                continue
+        break
+    return depth
+
+
+def audit_project_storyboard(
+    snapshot: ProjectSnapshot,
+    *,
+    timeline_editor_id: UUID | None = None,
+    group_id: UUID | None = None,
+    spec_ids: tuple[UUID, ...] | None = None,
+) -> dict:
+    """Audit multi-shot continuity, H3 prompt/ordinal alignment, and pilot-gate readiness."""
+    assets_by_id = {asset.id: asset for asset in snapshot.assets}
+    items_by_id = {item.id: item for item in snapshot.canvasItems}
+    specs_by_id = {spec.id: spec for spec in snapshot.generationSpecs}
+    docs_by_id = {doc.id: doc for doc in snapshot.editorDocuments}
+    jobs_by_id = {job.id: job for job in snapshot.jobs}
+    results_by_spec: dict[UUID, list] = {}
+    for res in snapshot.results:
+        results_by_spec.setdefault(res.specId, []).append(res)
+
+    item_by_spec: dict[UUID, object] = {}
+    for item in snapshot.canvasItems:
+        if item.binding.role == "generation":
+            item_by_spec.setdefault(item.binding.objectRef.id, item)
+
+    unlinked_timeline_clips: list[str] = []
+    ordered_specs = []
+
+    if spec_ids is not None:
+        for sid in spec_ids:
+            spec = specs_by_id.get(sid)
+            if spec is None or spec.kind != "video":
+                raise ContractError("missing_object", "未找到指定的视频生成配置。", sid)
+            ordered_specs.append(spec)
+    elif timeline_editor_id is not None:
+        doc = docs_by_id.get(timeline_editor_id)
+        if not isinstance(doc, TimelineDocument):
+            raise ContractError("missing_object", "未找到指定的时间线文档。", timeline_editor_id)
+        conn_by_slot = {conn.slotId: conn for conn in doc.inputConnections}
+        visual_track = next((track for track in doc.data.tracks if track.kind == "visual"), None)
+        seen_specs: set[UUID] = set()
+        for clip in visual_track.clips if visual_track else ():
+            resolved_spec = None
+            conn = conn_by_slot.get(clip.id)
+            if conn is not None:
+                source_item = items_by_id.get(conn.sourceId)
+                if source_item is not None and source_item.binding.role == "generation":
+                    candidate = specs_by_id.get(source_item.binding.objectRef.id)
+                    if candidate is not None and candidate.kind == "video":
+                        resolved_spec = candidate
+            else:
+                unlinked_timeline_clips.append(clip.id)
+                asset_obj = assets_by_id.get(clip.resource.asset.assetId)
+                if asset_obj and asset_obj.provenance.jobId:
+                    job = jobs_by_id.get(asset_obj.provenance.jobId)
+                    if job is not None:
+                        candidate = specs_by_id.get(job.inputSnapshot.spec.id)
+                        if candidate is not None and candidate.kind == "video":
+                            resolved_spec = candidate
+            if resolved_spec is not None and resolved_spec.id not in seen_specs:
+                seen_specs.add(resolved_spec.id)
+                ordered_specs.append(resolved_spec)
+    else:
+        if group_id is not None:
+            group_item = items_by_id.get(group_id)
+            if group_item is None or group_item.kind != "group":
+                raise ContractError("missing_object", "未找到指定的画布分组节点。", group_id)
+            candidate_items = [
+                item for item in snapshot.canvasItems
+                if item.parentId == group_id and item.kind == "video" and item.binding.role == "generation"
+            ]
+        else:
+            candidate_items = [
+                item for item in snapshot.canvasItems
+                if item.visible and item.kind == "video" and item.binding.role == "generation"
+            ]
+        candidate_items.sort(key=lambda item: (item.position.y, item.position.x, str(item.id)))
+        for item in candidate_items:
+            spec = specs_by_id.get(item.binding.objectRef.id)
+            if spec is not None and spec.kind == "video":
+                ordered_specs.append(spec)
+
+    project_subject_ids = [item.id for item in snapshot.canvasItems if item.kind == "subject"]
+    shot_reports: list[dict] = []
+    sequence_plan_inputs: list[dict] = []
+    anchored_count = 0
+
+    for index, spec in enumerate(ordered_specs, start=1):
+        canvas_item = item_by_spec.get(spec.id)
+        active_refs = sorted(
+            (ref for ref in snapshot.references if ref.active and ref.targetSpecId == spec.id),
+            key=lambda ref: (ref.order, str(ref.id)),
+        )
+        roles: list[str] = []
+        ref_sources: list[dict] = []
+        subject_item_ids: list[str] = []
+        missing_upstream: list[dict] = []
+        frame_fingerprints: dict[str, str] = {}
+
+        for ref in active_refs:
+            roles.append(ref.role)
+            if ref.binding == "pinned":
+                asset_obj = assets_by_id.get(ref.source.assetId)
+                if asset_obj is None:
+                    missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_asset"})
+                elif asset_obj.kind in {"image", "video", "audio"}:
+                    ref_sources.append({
+                        "id": str(asset_obj.id),
+                        "name": asset_obj.name,
+                        "kind": asset_obj.kind,
+                        "role": ref.role,
+                        "hasAudio": bool(asset_obj.metadata.hasAudio),
+                    })
+                    if ref.role in {"first_frame", "last_frame"}:
+                        frame_fingerprints[ref.role] = asset_obj.fingerprint
+            else:
+                src_item = items_by_id.get(ref.source.id)
+                if src_item is None:
+                    missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_item"})
+                    continue
+                if src_item.kind == "subject":
+                    subject_item_ids.append(str(src_item.id))
+                    sub_doc = docs_by_id.get(src_item.binding.objectRef.id)
+                    if not isinstance(sub_doc, SubjectDocument) or sub_doc.data.main is None:
+                        missing_upstream.append({
+                            "referenceId": str(ref.id),
+                            "sourceItemId": str(src_item.id),
+                            "role": ref.role,
+                            "reason": "empty_subject",
+                        })
+                        continue
+                    slot_refs = [r for r in (sub_doc.data.main, *sub_doc.data.auxiliaries, sub_doc.data.voice) if r]
+                    for slot in slot_refs:
+                        asset_obj = assets_by_id.get(slot.assetId)
+                        if asset_obj and asset_obj.kind in {"image", "video", "audio"}:
+                            ref_sources.append({
+                                "id": str(asset_obj.id),
+                                "name": asset_obj.name,
+                                "kind": asset_obj.kind,
+                                "role": ref.role,
+                                "hasAudio": bool(asset_obj.metadata.hasAudio),
+                            })
+                else:
+                    asset_obj = current_asset(snapshot, src_item)
+                    if asset_obj is None:
+                        missing_upstream.append({
+                            "referenceId": str(ref.id),
+                            "sourceItemId": str(src_item.id),
+                            "role": ref.role,
+                            "reason": "unrendered_upstream_node",
+                        })
+                    elif asset_obj.kind in {"image", "video", "audio"}:
+                        ref_sources.append({
+                            "id": str(asset_obj.id),
+                            "name": asset_obj.name,
+                            "kind": asset_obj.kind,
+                            "role": ref.role,
+                            "hasAudio": bool(asset_obj.metadata.hasAudio),
+                        })
+                        if ref.role in {"first_frame", "last_frame"}:
+                            frame_fingerprints[ref.role] = asset_obj.fingerprint
+
+        if subject_item_ids or ref_sources:
+            anchored_count += 1
+
+        video_mode = getattr(spec.parameters, "videoMode", None)
+        duration = float(getattr(spec.parameters, "durationSeconds", None) or 5.0)
+        generate_audio = bool(getattr(spec.parameters, "generateAudio", True))
+        h3_mode = _infer_h3_mode(video_mode, roles)
+        continuity_issues: list[str] = []
+        continuity_warnings: list[str] = []
+
+        if missing_upstream:
+            continuity_issues.append(
+                f"Shot {index} has {len(missing_upstream)} unrendered or missing upstream reference source(s); "
+                "render/adopt upstream keyframes or media before submitting video generation."
+            )
+        if (
+            "first_frame" in frame_fingerprints
+            and "last_frame" in frame_fingerprints
+            and frame_fingerprints["first_frame"] == frame_fingerprints["last_frame"]
+        ):
+            continuity_warnings.append(
+                f"Shot {index} FL2VA first_frame and last_frame point to identical image bytes; "
+                "expect near-zero bridge progression unless changed."
+            )
+
+        cont_depth = _continuation_depth(snapshot, spec.id) if h3_mode == "continuation" else 0
+        if cont_depth > 3:
+            continuity_warnings.append(
+                f"Shot {index} is at continuation hop depth {cont_depth} (>3); "
+                "re-anchor with a fresh keyframe to avoid latent accumulation drift."
+            )
+
+        lint_mode = "i2va" if h3_mode == "continuation" else h3_mode
+        prompt_lint = lint_h3_prompt(
+            spec.prompt or "",
+            mode=lint_mode,
+            duration_seconds=duration,
+            reference_sources=ref_sources if h3_mode != "continuation" else None,
+        )
+        features = extract_prompt_shot_features(spec.prompt or "")
+        candidates = results_by_spec.get(spec.id, [])
+        adopted_id = str(spec.currentResultId) if spec.currentResultId else None
+
+        sequence_plan_inputs.append({
+            "durationSeconds": duration,
+            "shotSize": features["shotSize"],
+            "cameraMotion": features["cameraMotion"],
+            "mode": "i2va" if h3_mode == "continuation" else h3_mode,
+        })
+
+        ready_for_video = not missing_upstream and prompt_lint["valid"]
+        shot_reports.append({
+            "shotIndex": index,
+            "specId": str(spec.id),
+            "specRevision": spec.revision,
+            "canvasItemId": str(canvas_item.id) if canvas_item is not None else None,
+            "title": getattr(canvas_item, "title", None) if canvas_item is not None else None,
+            "h3Mode": h3_mode,
+            "durationSeconds": duration,
+            "shotSize": features["shotSize"],
+            "cameraMotion": features["cameraMotion"],
+            "subjectItemIds": subject_item_ids,
+            "referenceOrdinals": h3_reference_ordinals(ref_sources) if h3_mode != "continuation" else [],
+            "missingUpstream": missing_upstream,
+            "continuationDepth": cont_depth,
+            "candidateCount": len(candidates),
+            "adoptedResultId": adopted_id,
+            "readyForVideoGeneration": ready_for_video,
+            "promptLint": prompt_lint,
+            "continuityIssues": continuity_issues,
+            "continuityWarnings": continuity_warnings,
+        })
+
+    # Second pass: cross-shot Subject / anchor consistency across the sequence
+    sequence_continuity_warnings: list[str] = []
+    if len(shot_reports) >= 2 and (project_subject_ids or anchored_count > 0):
+        for shot in shot_reports:
+            if not shot["subjectItemIds"] and not shot["referenceOrdinals"] and shot["h3Mode"] == "t2va":
+                msg = (
+                    f"Shot {shot['shotIndex']} ({shot['specId']}) runs bare T2VA with zero Subject or reference "
+                    "anchors while project/sequence anchors exist; character or scene identity may drift."
+                )
+                shot["continuityWarnings"].append(msg)
+                sequence_continuity_warnings.append(msg)
+
+    if unlinked_timeline_clips:
+        sequence_continuity_warnings.append(
+            f"Timeline has {len(unlinked_timeline_clips)} visual clip(s) without inputConnections provenance: "
+            f"{unlinked_timeline_clips}. Link sourceItemId for surgical shot revision."
+        )
+
+    sequence_lint = lint_shot_plan(sequence_plan_inputs) if shot_reports else {
+        "valid": True,
+        "shotCount": 0,
+        "totalDurationSeconds": 0.0,
+        "shotSizeDiversity": 0.0,
+        "cameraMotionDiversity": 0.0,
+        "errors": [],
+        "warnings": [],
+    }
+
+    ready_ids = [s["specId"] for s in shot_reports if s["readyForVideoGeneration"]]
+    blocked_ids = [s["specId"] for s in shot_reports if not s["readyForVideoGeneration"]]
+    adopted_ids = [s["specId"] for s in shot_reports if s["adoptedResultId"] is not None]
+    unreviewed_ids = [
+        s["specId"] for s in shot_reports
+        if s["candidateCount"] > 0 and s["adoptedResultId"] is None
+    ]
+    pending_seconds = sum(
+        float(s["durationSeconds"]) for s in shot_reports if s["adoptedResultId"] is None
+    )
+
+    all_valid = (
+        bool(sequence_lint["valid"])
+        and not blocked_ids
+        and all(not s["continuityIssues"] for s in shot_reports)
+    )
+
+    return {
+        "projectId": str(snapshot.project.id),
+        "valid": all_valid,
+        "shots": shot_reports,
+        "sequenceLint": sequence_lint,
+        "continuity": {
+            "projectSubjectCount": len(project_subject_ids),
+            "unlinkedTimelineClipIds": unlinked_timeline_clips,
+            "warnings": sequence_continuity_warnings,
+        },
+        "gate": {
+            "shotCount": len(shot_reports),
+            "readyShotSpecIds": ready_ids,
+            "blockedShotSpecIds": blocked_ids,
+            "adoptedShotSpecIds": adopted_ids,
+            "unreviewedCandidateSpecIds": unreviewed_ids,
+            "estimatedPendingVideoSeconds": round(pending_seconds, 3),
+            "requiresUserApproval": bool(pending_seconds > 0 or blocked_ids or unreviewed_ids),
+        },
+    }
+
+
+def _resolve_item_adopted_asset_id(snapshot: dict, item_id: str) -> str | None:
+    items_by_id = {item["id"]: item for item in snapshot.get("canvasItems", ())}
+    specs_by_id = {spec["id"]: spec for spec in snapshot.get("generationSpecs", ())}
+    results_by_id = {res["id"]: res for res in snapshot.get("results", ())}
+    item = items_by_id.get(item_id)
+    if item is None:
+        return None
+    binding = item.get("binding", {})
+    if binding.get("role") == "material":
+        return binding.get("objectRef", {}).get("assetId")
+    if binding.get("role") == "generation":
+        if binding.get("materialOverride"):
+            return binding["materialOverride"].get("assetId")
+        spec = specs_by_id.get(binding.get("objectRef", {}).get("id"))
+        if spec and spec.get("currentResultId"):
+            res = results_by_id.get(spec["currentResultId"])
+            if res:
+                return res.get("asset", {}).get("assetId")
+    return None
+
+
+def prepare_timeline_shot_revision(
+    snapshot: dict,
+    *,
+    timeline_editor_id: UUID,
+    clip_id: str | None = None,
+    asset_id: UUID | None = None,
+    source_item_id: UUID | None = None,
+    in_point: float | None = None,
+    out_point: float | None = None,
+    use_asset_duration: bool = False,
+    title: str | None = None,
+    operation_id: UUID | None = None,
+) -> dict:
+    """Prepare a surgical single-clip timeline save payload preserving all sibling clips."""
+    doc = next(
+        (d for d in snapshot.get("editorDocuments", ())
+         if d["id"] == str(timeline_editor_id) and d["kind"] == "timeline"),
+        None,
+    )
+    if doc is None:
+        raise ProjectError(f"Timeline editor document {timeline_editor_id} is not in this project.")
+
+    if source_item_id is not None and not any(
+        item["id"] == str(source_item_id) for item in snapshot.get("canvasItems", ())
+    ):
+        raise ProjectError(f"Source canvas item {source_item_id} is not in this project.")
+
+    resolved_clip_id = clip_id
+    if resolved_clip_id is None:
+        if source_item_id is None:
+            raise ProjectError("Provide --clip-id or --source-item linked in timeline inputConnections.")
+        matched = next(
+            (c["slotId"] for c in (doc.get("inputConnections") or ()) if c["sourceId"] == str(source_item_id)),
+            None,
+        )
+        if matched is None:
+            raise ProjectError(
+                f"Source canvas item {source_item_id} is not linked to any slot in timeline {timeline_editor_id}."
+            )
+        resolved_clip_id = matched
+
+    resolved_asset_id = str(asset_id) if asset_id is not None else None
+    if resolved_asset_id is None:
+        if source_item_id is None:
+            raise ProjectError("Provide --asset or a --source-item with an adopted/material asset.")
+        resolved_asset_id = _resolve_item_adopted_asset_id(snapshot, str(source_item_id))
+        if resolved_asset_id is None:
+            raise ProjectError(
+                f"Source canvas item {source_item_id} has no adopted result or material asset to sync."
+            )
+
+    asset_obj = next((a for a in snapshot.get("assets", ()) if a["id"] == resolved_asset_id), None)
+    if asset_obj is None:
+        raise ProjectError(f"Asset {resolved_asset_id} is not registered in this project.")
+
+    updated_doc = json.loads(json.dumps(doc))
+    target_track = None
+    target_clip = None
+    for track in updated_doc["data"]["tracks"]:
+        for clip in track["clips"]:
+            if clip["id"] == resolved_clip_id:
+                target_track, target_clip = track, clip
+                break
+        if target_clip is not None:
+            break
+    if target_clip is None or target_track is None:
+        raise ProjectError(f"Clip '{resolved_clip_id}' was not found in timeline {timeline_editor_id}.")
+
+    media_kind = asset_obj["kind"]
+    if target_track["kind"] == "visual" and media_kind not in {"image", "video"}:
+        raise ProjectError("Visual timeline clips require an image or video asset.")
+    if target_track["kind"] == "audio" and media_kind != "audio":
+        raise ProjectError("Audio timeline clips require an audio asset.")
+
+    old_asset_id = target_clip["resource"]["asset"]["assetId"]
+    old_in = float(target_clip["inPoint"])
+    old_out = float(target_clip["outPoint"])
+    asset_duration = asset_obj.get("metadata", {}).get("durationSeconds")
+
+    if media_kind == "image":
+        new_in = 0.0
+        new_out = float(out_point) if out_point is not None else (old_out - old_in)
+    else:
+        if asset_duration is None or float(asset_duration) <= 0:
+            raise ProjectError("Video and audio timeline replacements require a probed positive durationSeconds.")
+        total_dur = float(asset_duration)
+        new_in = (
+            float(in_point)
+            if in_point is not None
+            else (old_in if not use_asset_duration and old_in < total_dur else 0.0)
+        )
+        if out_point is not None:
+            new_out = float(out_point)
+        elif use_asset_duration:
+            new_out = total_dur
+        else:
+            new_out = min(total_dur, new_in + (old_out - old_in))
+            if new_out <= new_in:
+                new_in, new_out = 0.0, total_dur
+        if new_out <= new_in or new_out > total_dur + 1e-6:
+            raise ProjectError(f"Invalid trim [{new_in}, {new_out}] for asset duration {total_dur}s.")
+
+    new_asset_ref = {
+        "assetId": asset_obj["id"],
+        "revision": asset_obj["revision"],
+        "fingerprint": asset_obj["fingerprint"],
+        "kind": media_kind,
+    }
+    new_resource = {
+        "asset": new_asset_ref,
+        "title": title if title is not None else asset_obj["name"],
+        "durationSeconds": asset_duration if media_kind != "image" else None,
+    }
+    target_clip["resource"] = new_resource
+    target_clip["inPoint"] = new_in
+    target_clip["outPoint"] = new_out
+
+    imported = list(updated_doc["data"].get("importedAssets") or [])
+    if not any(
+        entry["asset"]["assetId"] == new_asset_ref["assetId"]
+        and entry["asset"]["fingerprint"] == new_asset_ref["fingerprint"]
+        for entry in imported
+    ):
+        imported.append(new_resource)
+    updated_doc["data"]["importedAssets"] = imported
+
+    operation = operation_id or uuid4()
+    existing_conns = updated_doc.get("inputConnections") or []
+    effective_source_id = str(source_item_id) if source_item_id is not None else next(
+        (c["sourceId"] for c in existing_conns if c["slotId"] == resolved_clip_id),
+        None,
+    )
+    connections = [c for c in existing_conns if c["slotId"] != resolved_clip_id]
+    if effective_source_id is not None:
+        if any(c["sourceId"] == effective_source_id for c in connections):
+            raise ProjectError(
+                f"Source canvas item {effective_source_id} is already connected to another timeline slot."
+            )
+        connections.append({
+            "id": str(uuid5(operation, f"connection-{resolved_clip_id}")),
+            "sourceId": effective_source_id,
+            "slotId": resolved_clip_id,
+            "asset": new_asset_ref,
+        })
+    updated_doc["inputConnections"] = connections
+
+    return {
+        "document": updated_doc,
+        "expectedVersions": [
+            {"objectType": "editor_document", "id": str(timeline_editor_id), "revision": doc["revision"]}
+        ],
+        "timelineEditorId": str(timeline_editor_id),
+        "clipId": resolved_clip_id,
+        "previousAssetId": old_asset_id,
+        "newAssetId": asset_obj["id"],
+        "inPoint": new_in,
+        "outPoint": new_out,
+    }
diff --git a/packages/core/src/opendirector/cli.py b/packages/core/src/opendirector/cli.py
index 2b66ec8ad..fb51de1ca 100644
--- a/packages/core/src/opendirector/cli.py
+++ b/packages/core/src/opendirector/cli.py
@@ -33,7 +33,7 @@
     "voice": "List, create or delete voices on a configured speech service.",
     "asset": "Import files, write text and manage registered project assets.",
     "canvas": "Display, arrange, hide and configure canvas items.",
-    "video": "Create video generation nodes with model settings and references.",
+    "video": "Create, compile/lint H3 prompts, inspect and revise video shots.",
     "job": "Inspect, wait for, cancel or recover generation jobs.",
     "artifact": "Register files from the active agent execution directory.",
     "generation-spec": "Create, edit and restore generation settings and prompts.",
@@ -437,16 +437,25 @@ def video_create(ctx: typer.Context,
                  duration: Annotated[float, typer.Option(min=0, help="Video duration in seconds.")],
                  x: Annotated[float, typer.Option(help="Canvas X coordinate. Choose using the current item positions and sizes.")],
                  y: Annotated[float, typer.Option(help="Canvas Y coordinate. Choose using the current item positions and sizes.")],
-                 first_frame: Annotated[UUID | None, typer.Option(help="Source image canvas item for first-frame mode.")] = None,
-                 reference_item: Annotated[list[UUID] | None, typer.Option(help="Source canvas items for reference mode. Repeat for multiple inputs.")] = None):
+                 first_frame: Annotated[UUID | None, typer.Option(help="Source image canvas item for first-frame (I2VA/FL2VA) mode.")] = None,
+                 last_frame: Annotated[UUID | None, typer.Option(help="Source image canvas item for last-frame (FL2VA/L2VA) mode.")] = None,
+                 continue_from: Annotated[UUID | None, typer.Option(help="Source video canvas item for continuation mode.")] = None,
+                 reference_item: Annotated[list[UUID] | None, typer.Option(help="Source canvas items for reference mode. Repeat for multiple inputs.")] = None,
+                 aspect_ratio: Annotated[str | None, typer.Option(help="Optional output width:height ratio such as 16:9 or 9:16.")] = None,
+                 resolution: Annotated[str, typer.Option(help="Requested output resolution or 'auto'.")] = "auto",
+                 audio: Annotated[bool | None, typer.Option(help="Include generated audio (true/false) when supported.")] = None,
+                 title: Annotated[str | None, typer.Option(help="Optional display title for the created video canvas node.")] = None):
     client = ctx.obj
     client.command = ctx.command_path
     config = select_model([value for value in client.models() if value["kind"] == "video"], model)
-    if first_frame and reference_item:
-        raise ProjectError("Choose --first-frame or --reference-item for the selected video mode.")
+    chosen_groups = sum(bool(group_value) for group_value in ((first_frame or last_frame), reference_item, continue_from))
+    if chosen_groups > 1:
+        raise ProjectError("Choose only one mode group: (--first-frame/--last-frame), --reference-item, or --continue-from.")
     allowed = config["inputRules"]["videoModes"]
-    if first_frame:
+    if first_frame or last_frame:
         mode = "first_frame"
+    elif continue_from:
+        mode = "continuation"
     elif reference_item:
         mode = "reference"
     else:
@@ -457,21 +466,39 @@ def video_create(ctx: typer.Context,
     operation = client.operation_id or uuid4()
     spec_id, item_id = str(uuid5(operation, "spec")), str(uuid5(operation, "item"))
     project_id = snapshot["project"]["id"]
+    source_bindings: list[tuple[UUID, str]] = []
+    if first_frame:
+        source_bindings.append((first_frame, "first_frame"))
+    if last_frame:
+        source_bindings.append((last_frame, "last_frame"))
+    if continue_from:
+        source_bindings.append((continue_from, "continuation"))
+    for ref_id in reference_item or []:
+        source_bindings.append((ref_id, "reference"))
     references = []
-    for index, source_id in enumerate(([first_frame] if first_frame else reference_item) or []):
+    for index, (source_id, role) in enumerate(source_bindings):
         source = next((item for item in snapshot["canvasItems"] if item["id"] == str(source_id)), None)
         if source is None:
             raise ProjectError(f"Source canvas item {source_id} is not in this project.")
         references.append({"id": str(uuid5(operation, f"reference-{index}")), "projectId": project_id,
-            "targetSpecId": spec_id, "role": "first_frame" if first_frame else "reference",
+            "targetSpecId": spec_id, "role": role,
             "order": index, "binding": "follow_current", "source": {"id": str(source_id)}})
+    parameters: dict[str, object] = {"videoMode": mode, "durationSeconds": duration, "resolution": resolution}
+    if aspect_ratio is not None:
+        parameters["aspectRatio"] = aspect_ratio
+    if audio is not None:
+        parameters["generateAudio"] = audio
+    item_payload: dict[str, object] = {
+        "id": item_id, "projectId": project_id, "kind": "video",
+        "position": {"x": x, "y": y},
+        "binding": {"role": "generation", "objectRef": {"id": spec_id}},
+    }
+    if title is not None:
+        item_payload["title"] = title
     receipt = client.execute("canvas.createGeneration", {
         "spec": {"id": spec_id, "projectId": project_id, "kind": "video", "purpose": "generation",
-                 "modelConfigId": config["id"], "prompt": prompt,
-                 "parameters": {"videoMode": mode, "durationSeconds": duration}},
-        "item": {"id": item_id, "projectId": project_id, "kind": "video",
-                 "position": {"x": x, "y": y},
-                 "binding": {"role": "generation", "objectRef": {"id": spec_id}}},
+                 "modelConfigId": config["id"], "prompt": prompt, "parameters": parameters},
+        "item": item_payload,
         "references": references,
     }, identity=operation)
     changed = {item["objectType"]: item for item in receipt["changed"]}
@@ -487,6 +514,250 @@ def video_create(ctx: typer.Context,
                    "command": shlex.join(submit)}})
 
 
+def _resolve_spec_reference_sources(snapshot: dict, spec_id: str) -> tuple[list[dict], list[str]]:
+    assets_by_id = {asset["id"]: asset for asset in snapshot.get("assets", ())}
+    items_by_id = {item["id"]: item for item in snapshot.get("canvasItems", ())}
+    specs_by_id = {spec["id"]: spec for spec in snapshot.get("generationSpecs", ())}
+    results_by_id = {res["id"]: res for res in snapshot.get("results", ())}
+    docs_by_id = {doc["id"]: doc for doc in snapshot.get("editorDocuments", ())}
+
+    def item_assets(item: dict) -> list[dict]:
+        if item["kind"] == "subject":
+            doc = docs_by_id.get(item["binding"]["objectRef"]["id"])
+            if not doc:
+                return []
+            data = doc["data"]
+            refs = [r for r in (data.get("main"), *(data.get("auxiliaries") or ()), data.get("voice")) if r]
+            return [assets_by_id[r["assetId"]] for r in refs if r["assetId"] in assets_by_id]
+        binding = item["binding"]
+        if binding["role"] == "material":
+            found = assets_by_id.get(binding["objectRef"]["assetId"])
+            return [found] if found else []
+        if binding["role"] == "generation":
+            if binding.get("materialOverride"):
+                found = assets_by_id.get(binding["materialOverride"]["assetId"])
+                return [found] if found else []
+            src_spec = specs_by_id.get(binding["objectRef"]["id"])
+            if src_spec and src_spec.get("currentResultId"):
+                res = results_by_id.get(src_spec["currentResultId"])
+                if res and res["asset"]["assetId"] in assets_by_id:
+                    return [assets_by_id[res["asset"]["assetId"]]]
+        return []
+
+    active = sorted(
+        (ref for ref in snapshot.get("references", ()) if ref.get("active") and ref.get("targetSpecId") == spec_id),
+        key=lambda ref: (ref.get("order", 0), ref.get("id", "")),
+    )
+    sources: list[dict] = []
+    roles: list[str] = []
+    for ref in active:
+        roles.append(str(ref.get("role") or "reference"))
+        if ref.get("binding") == "pinned":
+            asset_obj = assets_by_id.get(ref["source"]["assetId"])
+            resolved = [asset_obj] if asset_obj else []
+        else:
+            src_item = items_by_id.get(ref["source"]["id"])
+            resolved = item_assets(src_item) if src_item else []
+        for asset_obj in resolved:
+            if asset_obj["kind"] in {"image", "video", "audio"}:
+                sources.append({
+                    "id": asset_obj["id"],
+                    "name": asset_obj["name"],
+                    "kind": asset_obj["kind"],
+                    "role": ref.get("role"),
+                    "hasAudio": bool(asset_obj.get("metadata", {}).get("hasAudio")),
+                })
+    return sources, roles
+
+
+@group("video").command("compile-h3-prompt", help="Compile structured shot/reference JSON into an official MiniMax-H3 prompt.")
+def video_compile_h3_prompt(
+    file: Annotated[Path, typer.Option(help="JSON specification file; use - for stdin.")],
+    check: Annotated[bool, typer.Option("--check/--no-check", help="Exit 1 when the compiled prompt has lint errors.")] = True,
+):
+    from opendirector.domain.h3_cinematography import compile_h3_prompt
+    result = compile_h3_prompt(read_file(file))
+    emit(result)
+    if check and not result["lint"]["valid"]:
+        raise typer.Exit(1)
+
+
+@group("video").command("lint-h3-prompt", help="Validate an H3 prompt file or live GenerationSpec against H3 grammar and ordinals.")
+def video_lint_h3_prompt(
+    ctx: typer.Context,
+    spec_id: Annotated[UUID | None, typer.Option(help="Live project GenerationSpec UUID to validate with active references.")] = None,
+    file: Annotated[Path | None, typer.Option(help="Plain-text prompt file (use - for stdin) when not inspecting --spec-id.")] = None,
+    mode: Annotated[str | None, typer.Option(help="H3 mode: t2va, i2va, fl2va, l2va, or ref2va. Inferred when --spec-id is given.")] = None,
+    duration: Annotated[float | None, typer.Option(min=0, help="Target video duration in seconds.")] = None,
+):
+    from opendirector.domain.h3_cinematography import h3_reference_ordinals, lint_h3_prompt
+    if bool(spec_id) == bool(file):
+        raise ProjectError("Provide exactly one of --spec-id or --file.")
+    reference_sources = None
+    if spec_id is not None:
+        client = ctx.obj
+        client.command = ctx.command_path
+        snapshot = client.snapshot()
+        spec = next((s for s in snapshot.get("generationSpecs", ()) if s["id"] == str(spec_id)), None)
+        if spec is None or spec.get("kind") != "video":
+            raise ProjectError(f"Video GenerationSpec {spec_id} is not in this project.")
+        prompt_text = str(spec.get("prompt") or "")
+        effective_duration = float(duration if duration is not None else (spec.get("parameters", {}).get("durationSeconds") or 5.0))
+        reference_sources, roles = _resolve_spec_reference_sources(snapshot, str(spec_id))
+        if mode is None:
+            vmode = spec.get("parameters", {}).get("videoMode")
+            if vmode == "reference":
+                effective_mode = "ref2va"
+            elif "first_frame" in roles and "last_frame" in roles:
+                effective_mode = "fl2va"
+            elif "first_frame" in roles:
+                effective_mode = "i2va"
+            elif "last_frame" in roles:
+                effective_mode = "l2va"
+            else:
+                effective_mode = "t2va"
+        else:
+            effective_mode = mode
+    else:
+        prompt_text = sys.stdin.read() if str(file) == "-" else file.read_text(encoding="utf-8")
+        effective_mode = mode or "t2va"
+        effective_duration = float(duration if duration is not None else 5.0)
+    report = lint_h3_prompt(
+        prompt_text, mode=effective_mode, duration_seconds=effective_duration, reference_sources=reference_sources,
+    )
+    payload: dict[str, object] = {"lint": report}
+    if reference_sources is not None:
+        payload["referenceOrdinals"] = h3_reference_ordinals(reference_sources)
+    emit(payload)
+    if not report["valid"]:
+        raise typer.Exit(1)
+
+
+@group("video").command("lint-shot-plan", help="Validate a multi-shot storyboard JSON for H3 duration bounds and visual diversity.")
+def video_lint_shot_plan(
+    file: Annotated[Path, typer.Option(help="Shot plan JSON file (array of shots or {'shots': [...]}); use - for stdin.")],
+):
+    from opendirector.domain.h3_cinematography import lint_shot_plan
+    raw = json.loads(sys.stdin.read() if str(file) == "-" else file.read_text(encoding="utf-8"))
+    shots = raw["shots"] if isinstance(raw, dict) and isinstance(raw.get("shots"), list) else raw
+    if not isinstance(shots, list):
+        raise ValueError("Expected a JSON list of shots or an object with a 'shots' list.")
+    report = lint_shot_plan(shots)
+    emit(report)
+    if not report["valid"]:
+        raise typer.Exit(1)
+
+
+@group("video").command("audit-storyboard", help="Audit live project multi-shot continuity, H3 ordinals, diversity, and gate readiness.")
+def video_audit_storyboard(
+    ctx: typer.Context,
+    timeline_editor: Annotated[UUID | None, typer.Option(help="Optional timeline EditorDocument UUID to order shots.")] = None,
+    group_id: Annotated[UUID | None, typer.Option(help="Optional canvas group UUID to scope shots.")] = None,
+    spec_id: Annotated[list[UUID] | None, typer.Option(help="Explicit ordered video GenerationSpec UUIDs.")] = None,
+    strict: Annotated[bool, typer.Option("--strict/--no-strict", help="Exit 1 when audit reports blocking issues.")] = False,
+):
+    client = ctx.obj
+    client.command = ctx.command_path
+    arguments: dict[str, object] = {}
+    if timeline_editor is not None:
+        arguments["timelineEditorId"] = str(timeline_editor)
+    if group_id is not None:
+        arguments["groupId"] = str(group_id)
+    if spec_id:
+        arguments["specIds"] = [str(value) for value in spec_id]
+    report = client.query("storyboard.audit", **arguments)
+    emit(report)
+    if strict and not report.get("valid", True):
+        raise typer.Exit(1)
+
+
+@group("video").command("inspect-shot", help="Probe a local video file or registered project video asset with contact-sheet QC.")
+def video_inspect_shot(
+    ctx: typer.Context,
+    file: Annotated[Path | None, typer.Argument(help="Local video file to inspect when --asset is omitted.")] = None,
+    asset: Annotated[UUID | None, typer.Option(help="Registered project video Asset UUID to inspect via contact-sheet preview.")] = None,
+    contact_sheet: Annotated[Path | None, typer.Option(help="Exclusive output path for a timestamped JPEG contact sheet.")] = None,
+    columns: Annotated[int, typer.Option(min=1, max=8, help="Contact-sheet columns.")] = 4,
+    rows: Annotated[int, typer.Option(min=1, max=8, help="Contact-sheet rows.")] = 3,
+):
+    from opendirector.media.shot_inspection import _write_exclusive_bytes, inspect_video_shot
+    if bool(file) == bool(asset):
+        raise ProjectError("Provide either a local FILE argument or --asset UUID, not both.")
+    if asset is not None:
+        client = ctx.obj
+        client.command = ctx.command_path
+        result = client.query(
+            "asset.preview",
+            objectId=str(asset),
+            videoScope="contact_sheet",
+            columns=columns,
+            rows=rows,
+        )
+        if contact_sheet is not None:
+            preview_info = result.get("preview") or {}
+            if "path" in preview_info:
+                data = Path(preview_info["path"]).read_bytes()
+            elif "url" in preview_info:
+                resp = client.http.get(preview_info["url"])
+                if not resp.is_success:
+                    raise ProjectError(resp.text, resp.status_code)
+                data = resp.content
+            else:
+                raise ProjectError("Contact-sheet preview returned neither path nor URL.", 422)
+            _write_exclusive_bytes(contact_sheet, data)
+            result = {**result, "savedContactSheetPath": str(contact_sheet.resolve())}
+        emit(result)
+        return
+    assert file is not None
+    emit(inspect_video_shot(file, contact_sheet_path=contact_sheet, columns=columns, rows=rows))
+
+
+@group("video").command("revise-shot", help="Replace a single clip on an editable timeline by clip ID or linked source item.")
+def video_revise_shot(
+    ctx: typer.Context,
+    timeline_editor: Annotated[UUID, typer.Option(help="Target timeline EditorDocument UUID.")],
+    clip_id: Annotated[str | None, typer.Option(help="Clip ID inside the timeline, or omit to follow --source-item.")] = None,
+    asset: Annotated[UUID | None, typer.Option(help="Replacement project Asset UUID, or omit to sync --source-item.")] = None,
+    source_item: Annotated[UUID | None, typer.Option(help="Source canvas item UUID for lineage lookup and provenance.")] = None,
+    in_point: Annotated[float | None, typer.Option(min=0, help="Explicit trim start in seconds.")] = None,
+    out_point: Annotated[float | None, typer.Option(min=0, help="Explicit trim end in seconds.")] = None,
+    use_asset_duration: Annotated[bool, typer.Option("--use-asset-duration/--keep-slot-duration", help="Use full new asset duration instead of matching the current slot span.")] = False,
+    title: Annotated[str | None, typer.Option(help="Optional clip resource title; defaults to the asset name.")] = None,
+):
+    from opendirector.application.creation_storyboard import prepare_timeline_shot_revision
+    client = ctx.obj
+    client.command = ctx.command_path
+    snapshot = client.snapshot()
+    operation = client.operation_id or uuid4()
+    prepared = prepare_timeline_shot_revision(
+        snapshot,
+        timeline_editor_id=timeline_editor,
+        clip_id=clip_id,
+        asset_id=asset,
+        source_item_id=source_item,
+        in_point=in_point,
+        out_point=out_point,
+        use_asset_duration=use_asset_duration,
+        title=title,
+        operation_id=operation,
+    )
+    receipt = client.execute(
+        "editor.save",
+        {"document": prepared["document"]},
+        versions=prepared["expectedVersions"],
+        identity=operation,
+    )
+    emit({
+        **receipt,
+        "timelineEditorId": prepared["timelineEditorId"],
+        "clipId": prepared["clipId"],
+        "previousAssetId": prepared["previousAssetId"],
+        "newAssetId": prepared["newAssetId"],
+        "inPoint": prepared["inPoint"],
+        "outPoint": prepared["outPoint"],
+    })
+
+
 @group("job").command("show", help="Read job status once. Use job wait to wait for completion.")
 def job_show(ctx: typer.Context, job_id: UUID):
     ctx.obj.command = ctx.command_path
diff --git a/packages/core/src/opendirector/domain/creation/commands.py b/packages/core/src/opendirector/domain/creation/commands.py
index 2e02ff8ca..402a2e47f 100644
--- a/packages/core/src/opendirector/domain/creation/commands.py
+++ b/packages/core/src/opendirector/domain/creation/commands.py
@@ -487,10 +487,27 @@ class CanvasStatusQuery(QueryBase):
 class AssetPreviewQuery(QueryBase):
     type: Literal['asset.preview'] = Field(description='Preview an asset; does not establish model observation.')
     objectId: UUID = Field(description='Asset ID.')
+    videoScope: Literal['first_frame', 'contact_sheet'] = Field(
+        default='first_frame',
+        description='Video preview mode: single first frame or multi-frame timestamped contact sheet.',
+    )
+    columns: int = Field(default=4, strict=True, ge=1, le=8, description='Contact-sheet grid columns for videoScope="contact_sheet".')
+    rows: int = Field(default=3, strict=True, ge=1, le=8, description='Contact-sheet grid rows for videoScope="contact_sheet".')
+
+
+class StoryboardAuditQuery(QueryBase):
+    type: Literal['storyboard.audit'] = Field(
+        description='Audit multi-shot continuity, H3 prompt/ordinal alignment, diversity, and pilot-gate readiness.'
+    )
+    timelineEditorId: UUID | None = Field(default=None, description='Optional timeline editor document ID to order and scope shots.')
+    groupId: UUID | None = Field(default=None, description='Optional canvas group item ID to scope shots.')
+    specIds: tuple[UUID, ...] | None = Field(
+        default=None, max_length=200, description='Optional explicit ordered video GenerationSpec IDs to audit.'
+    )
 
 
 Query = Annotated[ProjectQuery | ObjectQuery | VersionsQuery | AssetSearchQuery | AssetUsageQuery |
-                  CanvasStatusQuery | AssetPreviewQuery, Field(discriminator='type')]
+                  CanvasStatusQuery | AssetPreviewQuery | StoryboardAuditQuery, Field(discriminator='type')]
 
 
 class ChangedObject(Contract):
diff --git a/packages/core/src/opendirector/domain/h3_cinematography.py b/packages/core/src/opendirector/domain/h3_cinematography.py
new file mode 100644
index 000000000..c50a0c8ef
--- /dev/null
+++ b/packages/core/src/opendirector/domain/h3_cinematography.py
@@ -0,0 +1,689 @@
+"""MiniMax-H3 cinematography vocabulary, prompt compiler, and shot-plan linter.
+
+Pure domain logic shared by Agent tools, CLI subcommands, and tests. It encodes
+the official H3 prompt grammar across T2VA, I2VA, FL2VA, L2VA, and Ref2VA, plus
+H3's per-modality reference numbering and 17n+5 frame-grid rules.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from opendirector.domain.projects import ProjectError
+
+H3_MIN_DURATION = 4.0
+H3_MAX_DURATION = 15.0
+H3_DEFAULT_FPS = 24
+
+H3_MODES = ("t2va", "i2va", "fl2va", "l2va", "ref2va")
+
+H3_STYLES = (
+    "Live-action, cinematic",
+    "Cinematic",
+    "live-action",
+    "2D-animated",
+    "3D CG",
+    "claymation",
+    "watercolor",
+    "vintage film",
+)
+
+SHOT_SIZES = (
+    "extreme wide shot",
+    "wide shot",
+    "medium-wide shot",
+    "medium shot",
+    "medium close-up",
+    "close shot",
+    "close-up",
+    "extreme close-up",
+    "over-the-shoulder shot",
+    "two-shot",
+    "low-angle shot",
+    "high-angle shot",
+    "overhead shot",
+    "bird's-eye shot",
+)
+
+CAMERA_MOTIONS: dict[str, str] = {
+    "Zoom In": "zooms in",
+    "Zoom Out": "zooms out",
+    "Push In": "pushes in",
+    "Pull Out": "pulls out",
+    "Pan Left": "pans left",
+    "Pan Right": "pans right",
+    "Truck Left": "trucks left",
+    "Truck Right": "trucks right",
+    "Tilt Up": "tilts up",
+    "Tilt Down": "tilts down",
+    "Pedestal Up": "pedestals up",
+    "Pedestal Down": "pedestals down",
+    "Arc Shot": "moves in an arc shot",
+    "Tracking Shot": "tracks in a tracking shot",
+    "Static Shot": "holds a static shot",
+    "Shake Slightly": "shakes slightly",
+    "Shake Strongly": "shakes strongly",
+    "POV": "frames from a first-person POV",
+    "Roll Clockwise": "rolls clockwise",
+    "Roll Counterclockwise": "rolls counterclockwise",
+}
+
+CAMERA_AMPLITUDES: dict[str, str] = {
+    "small": "with small amplitude",
+    "medium": "",
+    "large": "with large amplitude",
+}
+
+CAMERA_SPEEDS: dict[str, str] = {
+    "slow": "at slow speed",
+    "normal": "",
+    "fast": "at fast speed",
+}
+
+CUT_TRANSITIONS = (
+    "the camera cuts to",
+    "the shot cuts to",
+    "the shot transitions to",
+    "the shot changes to",
+    "the shot switches to",
+    "cross-dissolves to",
+    "fades to",
+    "wipes to",
+)
+
+REF2VA_TASK_TYPES = (
+    "keyframe completion",
+    "reference generation",
+    "video editing",
+    "video continuation",
+    "audio reuse",
+    "audio reference",
+)
+
+VISUAL_RETENTION_MARKERS = (
+    "fully_preserved",
+    "partially_preserved",
+    "attribute_transfer",
+    "weak_reference",
+)
+
+AUDIO_RETENTION_MARKERS = (
+    "fully_copy",
+    "partially_copy",
+    "reference",
+    "weak_reference",
+)
+
+BASE_SECTIONS = (
+    "integrated_multimodal_description",
+    "overall_soundscape",
+    "non_diegetic_music",
+)
+
+REF2VA_SECTIONS = (
+    "subject_definitions",
+    "summary",
+    "retention_analysis",
+    "detailed_description",
+    "overall_soundscape",
+    "non_diegetic_music",
+)
+
+_SHOT_HEADER_RE = re.compile(r"\[Shot (\d+)\]")
+_CUT_TIME_RE = re.compile(r"^\s*At (\d{2}):(\d{2}\.\d{3}),\s*")
+_SPEAKER_ID_RE = re.compile(r"\(S\d+(?:,S\d+)*\)")
+_DIALOGUE_BLOCK_RE = re.compile(r"<d>(.*?)</d>", re.S)
+_DIALOGUE_LANG_RE = re.compile(r"^\s*\[[^\[\]\n]+\]\s+\S", re.S)
+_TAG_RE = re.compile(r"<(Subject|Picture|Video|Audio) (\d+)>")
+_ABSTRACT_TAG_RE = re.compile(r"\b(?:8k|4k\s*uhd|masterpiece|best quality|unreal engine|photorealistic|trending on artstation)\b", re.I)
+
+
+def h3_frame_grid(duration_seconds: float, fps: int = H3_DEFAULT_FPS) -> dict[str, int | float]:
+    """Compute H3's 17n+5 latent frame grid for a 4-15s clip."""
+    seconds = float(duration_seconds)
+    if not H3_MIN_DURATION <= seconds <= H3_MAX_DURATION:
+        raise ProjectError(f"MiniMax-H3 duration must be between {H3_MIN_DURATION:g} and {H3_MAX_DURATION:g} seconds.")
+    if fps <= 0:
+        raise ProjectError("FPS must be positive.")
+    requested = round(seconds * fps)
+    frames = requested + (5 - requested) % 17
+    return {
+        "durationSeconds": round(seconds, 4),
+        "fps": fps,
+        "requestedFrames": requested,
+        "gridFrames": frames,
+        "effectiveGridSeconds": round(frames / fps, 4),
+    }
+
+
+def h3_reference_ordinals(sources: list[dict[str, Any]] | tuple[dict[str, Any], ...]) -> list[dict[str, Any]]:
+    """Compute H3 per-modality tags matching fasth3.native_prompt's audio offset.
+
+    FastH3 reserves `<Audio 1..K>` for embedded soundtracks of reference videos
+    (`hasAudio=True`) in source order before numbering standalone audio files.
+    """
+    audio_offset = sum(
+        item.get("kind") == "video" and bool(item.get("hasAudio"))
+        for item in sources
+    )
+    counts: dict[str, int] = {}
+    embedded_audio_index = 0
+    assigned: list[dict[str, Any]] = []
+    for item in sources:
+        kind = str(item.get("kind") or "")
+        counts[kind] = counts.get(kind, 0) + 1
+        tag = None
+        embedded_audio_tag = None
+        if kind == "image":
+            tag = f"<Picture {counts[kind]}>"
+        elif kind == "video":
+            tag = f"<Video {counts[kind]}>"
+            if bool(item.get("hasAudio")):
+                embedded_audio_index += 1
+                embedded_audio_tag = f"<Audio {embedded_audio_index}>"
+        elif kind == "audio":
+            tag = f"<Audio {counts[kind] + audio_offset}>"
+        assigned.append({
+            "id": str(item.get("id") or ""),
+            "name": str(item.get("name") or ""),
+            "kind": kind,
+            "role": item.get("role"),
+            "hasAudio": bool(item.get("hasAudio")),
+            "tag": tag,
+            "embeddedAudioTag": embedded_audio_tag,
+        })
+    return assigned
+
+
+def format_cut_timestamp(seconds: float) -> str:
+    if seconds <= 0:
+        raise ProjectError("Subsequent H3 shot cut timestamps must be strictly greater than 0.")
+    minutes = int(seconds // 60)
+    remainder = seconds - minutes * 60
+    return f"{minutes:02d}:{remainder:06.3f}"
+
+
+def format_camera_motion(
+    motion: str,
+    *,
+    amplitude: str = "medium",
+    speed: str = "normal",
+    detail: str = "",
+) -> str:
+    """Format an H3 camera movement as a natural English sentence."""
+    canonical = next((key for key in CAMERA_MOTIONS if key.lower() == motion.strip().lower()), None)
+    if canonical is None:
+        allowed = ", ".join(CAMERA_MOTIONS)
+        raise ProjectError(f"Unsupported H3 camera motion '{motion}'. Choose one of: {allowed}.")
+    amp_key = amplitude.strip().lower() if amplitude else "medium"
+    speed_key = speed.strip().lower() if speed else "normal"
+    if amp_key not in CAMERA_AMPLITUDES:
+        raise ProjectError(f"Unsupported camera amplitude '{amplitude}'. Use small, medium, or large.")
+    if speed_key not in CAMERA_SPEEDS:
+        raise ProjectError(f"Unsupported camera speed '{speed}'. Use slow, normal, or fast.")
+    parts = ["The camera", CAMERA_MOTIONS[canonical]]
+    if canonical not in {"Static Shot", "POV"}:
+        if CAMERA_AMPLITUDES[amp_key]:
+            parts.append(CAMERA_AMPLITUDES[amp_key])
+        if CAMERA_SPEEDS[speed_key]:
+            parts.append(CAMERA_SPEEDS[speed_key])
+    tail = detail.strip()
+    if tail:
+        tail = tail.rstrip(".")
+        parts.append(tail)
+    return " ".join(parts) + "."
+
+
+def format_dialogue(
+    speaker_id: str,
+    language: str,
+    text: str,
+    *,
+    speaker_intro: str = "The speaker",
+    delivery: str = "says:",
+    voiceover: bool = False,
+    cross_cut: bool = False,
+    cutoff: bool = False,
+    closed_lips_clause: str = "while their lips remain completely closed.",
+) -> str:
+    """Format H3 speaker identity and verbatim <d>[Language] ...</d> dialogue."""
+    sid = speaker_id.strip()
+    if not sid.startswith("("):
+        sid = f"({sid})"
+    if not _SPEAKER_ID_RE.fullmatch(sid):
+        raise ProjectError(f"Invalid H3 speaker ID '{speaker_id}'. Expected '(S1)' or '(S1,S2)'.")
+    lang = language.strip().strip("[]")
+    if not lang:
+        raise ProjectError("Dialogue requires an explicit language tag such as 'English' or 'Chinese'.")
+    spoken = text.strip()
+    if not spoken:
+        raise ProjectError("Dialogue text inside <d> cannot be empty.")
+    markers = ""
+    if cross_cut:
+        markers += " <scenetrans>"
+    if cutoff:
+        markers += " <cutoff>"
+    intro = speaker_intro.strip()
+    verb = "says in an off-screen voiceover:" if voiceover else delivery.strip()
+    prefix = f"{intro} {sid} {verb}".strip()
+    sentence = f"{prefix} <d>[{lang}] {spoken}{markers}</d>"
+    if voiceover:
+        tail = closed_lips_clause.strip()
+        if not tail.endswith("."):
+            tail += "."
+        sentence = f"{sentence} {tail}"
+    return sentence
+
+
+def _alignment_instruction(mode: str, final_shot: int, duration_seconds: float) -> str | None:
+    if mode in {"t2va", "ref2va"}:
+        return None
+    if mode == "i2va":
+        return "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced."
+    stamp = f"{duration_seconds:.2f}"
+    if mode == "fl2va":
+        return (
+            "How the reference pictures align with the target video — "
+            "Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; "
+            f"Picture 2 (from Shot {final_shot}) aligns with the {stamp}-second mark of the target video."
+        )
+    if mode == "l2va":
+        return (
+            "How the reference pictures align with the target video — "
+            f"<Picture 1> (from [Shot {final_shot}]) aligns with the {stamp}-second mark of the target video."
+        )
+    raise ProjectError(f"Unsupported H3 mode '{mode}'.")
+
+
+def _compile_shot_text(index: int, shot: dict[str, Any], *, style_prefix: str = "") -> str:
+    shot_size = str(shot.get("shotSize") or "").strip()
+    subject_action = str(shot.get("description") or shot.get("action") or "").strip()
+    if not subject_action:
+        raise ProjectError(f"Shot {index} requires a non-empty 'description' or 'action'.")
+
+    pieces: list[str] = []
+    if index == 1:
+        opening_parts = [part for part in (style_prefix.strip().rstrip(","), shot_size) if part]
+        if opening_parts and not subject_action.lower().startswith(tuple(p.lower() for p in opening_parts)):
+            if shot_size and not shot_size.lower().startswith(("a ", "an ", "the ")):
+                article = "an" if shot_size[0].lower() in "aeiou" else "a"
+                framing = f"{article} {shot_size}"
+            else:
+                framing = shot_size
+            lead = ", ".join([p for p in (style_prefix.strip().rstrip(","), framing) if p])
+            first_sentence = f"{lead}: {subject_action}" if subject_action[0].isupper() else f"{lead} {subject_action}"
+        else:
+            first_sentence = f"{style_prefix.strip().rstrip(',')}, {subject_action}" if style_prefix else subject_action
+        pieces.append(first_sentence.rstrip(".") + ".")
+    else:
+        at = shot.get("atSeconds")
+        if at is None:
+            raise ProjectError(f"Shot {index} requires 'atSeconds' (> 0 and < durationSeconds).")
+        cut_phrase = str(shot.get("cutTransition") or "the camera cuts to").strip()
+        if shot_size:
+            article = "" if shot_size.lower().startswith(("a ", "an ", "the ")) else ("an " if shot_size[0].lower() in "aeiou" else "a ")
+            pieces.append(f"At {format_cut_timestamp(float(at))}, {cut_phrase} {article}{shot_size}. {subject_action.rstrip('.')}.")
+        else:
+            pieces.append(f"At {format_cut_timestamp(float(at))}, {cut_phrase} {subject_action.rstrip('.')}.")
+
+    motion = shot.get("cameraMotion")
+    if motion:
+        if isinstance(motion, dict):
+            pieces.append(format_camera_motion(
+                str(motion.get("type") or motion.get("motion") or "Static Shot"),
+                amplitude=str(motion.get("amplitude") or "medium"),
+                speed=str(motion.get("speed") or "normal"),
+                detail=str(motion.get("detail") or ""),
+            ))
+        else:
+            pieces.append(format_camera_motion(
+                str(motion),
+                amplitude=str(shot.get("cameraAmplitude") or "medium"),
+                speed=str(shot.get("cameraSpeed") or "normal"),
+                detail=str(shot.get("cameraDetail") or ""),
+            ))
+
+    for line in shot.get("dialogues") or ():
+        pieces.append(format_dialogue(
+            str(line["speakerId"]),
+            str(line["language"]),
+            str(line["text"]),
+            speaker_intro=str(line.get("speakerIntro") or "The speaker"),
+            delivery=str(line.get("delivery") or "says:"),
+            voiceover=bool(line.get("voiceover", False)),
+            cross_cut=bool(line.get("crossCut", False)),
+            cutoff=bool(line.get("cutoff", False)),
+            closed_lips_clause=str(line.get("closedLipsClause") or "while their lips remain completely closed."),
+        ))
+
+    diegetic = str(shot.get("diegeticSound") or "").strip()
+    if diegetic:
+        pieces.append(diegetic.rstrip(".") + ".")
+
+    return f"[Shot {index}] " + " ".join(pieces)
+
+
+def compile_h3_prompt(spec: dict[str, Any]) -> dict[str, Any]:
+    """Compile structured H3 shot/reference metadata into a canonical H3 prompt."""
+    mode = str(spec.get("mode") or "t2va").strip().lower()
+    if mode not in H3_MODES:
+        raise ProjectError(f"Unsupported H3 mode '{mode}'. Choose from {', '.join(H3_MODES)}.")
+    duration = float(spec.get("durationSeconds") or 5.0)
+    grid = h3_frame_grid(duration, int(spec.get("fps") or H3_DEFAULT_FPS))
+    shots = list(spec.get("shots") or ())
+    if not shots:
+        raise ProjectError("H3 prompt compilation requires at least one shot in 'shots'.")
+
+    style = str(spec.get("style") or "Live-action, cinematic").strip()
+    soundscape = str(spec.get("overallSoundscape") or "Natural ambient room tone and subtle physical movement sounds continue throughout the scene.").strip()
+    music = str(spec.get("nonDiegeticMusic") or "N/A").strip()
+
+    if mode != "ref2va":
+        compiled_shots = [
+            _compile_shot_text(idx, shot, style_prefix=style if idx == 1 else "")
+            for idx, shot in enumerate(shots, start=1)
+        ]
+        header = _alignment_instruction(mode, len(shots), duration)
+        body = (
+            f"integrated_multimodal_description: {' '.join(compiled_shots)}\n\n"
+            f"overall_soundscape: {soundscape}\n\n"
+            f"non_diegetic_music: {music}"
+        )
+        prompt = f"{header}\n\n{body}" if header else body
+    else:
+        subject_defs = [str(line).strip() for line in (spec.get("subjectDefinitions") or ()) if str(line).strip()]
+        if not subject_defs:
+            raise ProjectError("Ref2VA compilation requires non-empty 'subjectDefinitions'.")
+        task_types = [str(item).strip() for item in (spec.get("taskTypes") or ("reference generation",)) if str(item).strip()]
+        seen_types: list[str] = []
+        for task_type in task_types:
+            if task_type not in REF2VA_TASK_TYPES:
+                raise ProjectError(f"Unsupported Ref2VA task type '{task_type}'.")
+            if task_type not in seen_types:
+                seen_types.append(task_type)
+        summary_body = str(spec.get("summary") or "").strip()
+        if not summary_body:
+            raise ProjectError("Ref2VA compilation requires a 'summary' sentence.")
+        if not summary_body.startswith("["):
+            summary_body = f"[{' + '.join(seen_types)}] {summary_body}"
+
+        retentions = [str(line).strip() for line in (spec.get("retentionAnalysis") or ()) if str(line).strip()]
+        if not retentions:
+            raise ProjectError("Ref2VA compilation requires non-empty 'retentionAnalysis'.")
+
+        style_opening = str(spec.get("styleOpening") or f"The target video uses a {style.lower()} style.").strip()
+        if not style_opening.endswith("."):
+            style_opening += "."
+        compiled_shots = [_compile_shot_text(idx, shot, style_prefix="") for idx, shot in enumerate(shots, start=1)]
+        detailed = "\n".join([style_opening, *compiled_shots])
+        prompt = (
+            "subject_definitions:\n" + "\n".join(subject_defs) + "\n\n"
+            "summary:\n" + summary_body + "\n\n"
+            "retention_analysis:\n" + "\n".join(retentions) + "\n\n"
+            "detailed_description:\n" + detailed + "\n\n"
+            "overall_soundscape:\n" + soundscape + "\n\n"
+            "non_diegetic_music:\n" + music
+        )
+
+    lint = lint_h3_prompt(
+        prompt,
+        mode=mode,
+        duration_seconds=duration,
+        reference_sources=spec.get("referenceSources"),
+    )
+    return {
+        "mode": mode,
+        "durationSeconds": duration,
+        "frameGrid": grid,
+        "prompt": prompt,
+        "lint": lint,
+    }
+
+
+def _extract_sections(prompt: str, names: tuple[str, ...]) -> tuple[dict[str, str], list[str]]:
+    errors: list[str] = []
+    matches: list[tuple[int, int, str]] = []
+    for name in names:
+        pattern = re.compile(rf"(?m)^{re.escape(name)}:\s*")
+        found = list(pattern.finditer(prompt))
+        if not found:
+            errors.append(f"Missing required section '{name}:'.")
+        elif len(found) > 1:
+            errors.append(f"Duplicate section '{name}:'.")
+        else:
+            matches.append((found[0].start(), found[0].end(), name))
+    if errors:
+        return {}, errors
+    ordered = [name for _, _, name in sorted(matches)]
+    if tuple(ordered) != names:
+        errors.append(f"Sections out of order: found {ordered}, expected {list(names)}.")
+        return {}, errors
+    sorted_matches = sorted(matches)
+    sections: dict[str, str] = {}
+    for index, (_, end, name) in enumerate(sorted_matches):
+        next_start = sorted_matches[index + 1][0] if index + 1 < len(sorted_matches) else len(prompt)
+        sections[name] = prompt[end:next_start].strip()
+    return sections, errors
+
+
+def lint_h3_prompt(
+    prompt: str,
+    *,
+    mode: str,
+    duration_seconds: float,
+    reference_sources: list[dict[str, Any]] | tuple[dict[str, Any], ...] | None = None,
+) -> dict[str, Any]:
+    """Validate an H3 prompt against official structural, temporal, and ordinal rules."""
+    normalized_mode = mode.strip().lower()
+    errors: list[str] = []
+    warnings: list[str] = []
+    if normalized_mode not in H3_MODES:
+        errors.append(f"Unsupported H3 mode '{mode}'. Choose from {', '.join(H3_MODES)}.")
+        return {"valid": False, "mode": normalized_mode, "errors": errors, "warnings": warnings, "detectedShots": 0, "referencedTags": []}
+
+    if not H3_MIN_DURATION <= float(duration_seconds) <= H3_MAX_DURATION:
+        errors.append(f"Duration {duration_seconds:g}s is outside MiniMax-H3's supported {H3_MIN_DURATION:g}-{H3_MAX_DURATION:g}s range.")
+
+    expected_sections = REF2VA_SECTIONS if normalized_mode == "ref2va" else BASE_SECTIONS
+    sections, section_errors = _extract_sections(prompt, expected_sections)
+    errors.extend(section_errors)
+
+    main_field = "detailed_description" if normalized_mode == "ref2va" else "integrated_multimodal_description"
+    shot_body = sections.get(main_field, "")
+    shot_headers = list(_SHOT_HEADER_RE.finditer(shot_body))
+    shot_numbers = [int(match.group(1)) for match in shot_headers]
+    if sections and not shot_numbers:
+        errors.append(f"'{main_field}' must contain at least '[Shot 1]'.")
+    elif shot_numbers and shot_numbers != list(range(1, len(shot_numbers) + 1)):
+        errors.append(f"Shot numbers must start at 1 and increment sequentially; found {shot_numbers}.")
+
+    last_cut = 0.0
+    for idx, match in enumerate(shot_headers, start=1):
+        seg_end = shot_headers[idx].start() if idx < len(shot_headers) else len(shot_body)
+        segment = shot_body[match.end():seg_end]
+        cut_match = _CUT_TIME_RE.match(segment)
+        if idx == 1 and cut_match:
+            errors.append("[Shot 1] must not start with a cut timestamp.")
+        elif idx > 1:
+            if not cut_match:
+                errors.append(f"[Shot {idx}] must begin with 'At MM:SS.mmm, ...'.")
+            else:
+                seconds = int(cut_match.group(1)) * 60 + float(cut_match.group(2))
+                if seconds <= last_cut:
+                    errors.append(f"[Shot {idx}] cut time ({seconds:.3f}s) must strictly exceed the previous cut ({last_cut:.3f}s).")
+                if seconds >= float(duration_seconds):
+                    errors.append(f"[Shot {idx}] cut time ({seconds:.3f}s) must fall strictly within duration ({duration_seconds:.2f}s).")
+                last_cut = seconds
+
+    final_shot = max(len(shot_numbers), 1)
+    expected_header = _alignment_instruction(normalized_mode, final_shot, float(duration_seconds))
+    first_line = prompt.splitlines()[0].strip() if prompt.splitlines() else ""
+    if expected_header is not None:
+        if first_line != expected_header:
+            errors.append(f"First line must match {normalized_mode.upper()} alignment header: '{expected_header}'.")
+        lines = prompt.splitlines()
+        if len(lines) < 2 or lines[1].strip() != "":
+            errors.append("Alignment instruction must be followed by one blank line before core sections.")
+    elif first_line.startswith(("For the target video,", "How the reference pictures align")):
+        errors.append(f"Mode '{normalized_mode}' must not start with a keyframe alignment instruction.")
+
+    for block in _DIALOGUE_BLOCK_RE.findall(shot_body):
+        if not _DIALOGUE_LANG_RE.match(block):
+            warnings.append("Dialogue block '<d>...</d>' should begin with an explicit '[Language]' tag.")
+    if "says in an off-screen voiceover" in shot_body and "lips remain" not in shot_body:
+        warnings.append("Off-screen voiceover should explicitly state after </d> that the on-screen character's lips remain closed.")
+
+    if _ABSTRACT_TAG_RE.search(prompt):
+        warnings.append("Avoid stacked quality buzzwords (e.g. '8k', 'masterpiece', 'unreal engine'); describe concrete visual and acoustic facts.")
+
+    for audio_sec in ("overall_soundscape", "non_diegetic_music"):
+        val = sections.get(audio_sec, "")
+        if "<d>" in val:
+            errors.append(f"'{audio_sec}' must not contain '<d>' dialogue blocks; keep dialogue in '{main_field}'.")
+
+    all_tags = [(m.group(1), int(m.group(2))) for m in _TAG_RE.finditer(prompt)]
+    unique_tag_strings = sorted({f"<{kind} {num}>" for kind, num in all_tags})
+
+    if normalized_mode == "ref2va" and sections:
+        summary_val = sections["summary"]
+        prefix_match = re.match(r"^\[([^\[\]]+)\]\s+\S", summary_val)
+        if not prefix_match:
+            errors.append("Ref2VA 'summary' must begin with '[task type] ...'.")
+        else:
+            raw_types = [part.strip() for part in prefix_match.group(1).split("+")]
+            invalid_types = [item for item in raw_types if item not in REF2VA_TASK_TYPES]
+            if invalid_types:
+                errors.append(f"Ref2VA 'summary' contains unknown task types: {invalid_types}.")
+            if len(set(raw_types)) != len(raw_types):
+                errors.append("Ref2VA 'summary' task types must not contain duplicates.")
+
+        retention_val = sections["retention_analysis"]
+        if _SPEAKER_ID_RE.search(retention_val):
+            errors.append("Ref2VA 'retention_analysis' must not include speaker IDs like '(S1)'.")
+        valid_markers = set(VISUAL_RETENTION_MARKERS) | set(AUDIO_RETENTION_MARKERS)
+        for line in [ln.strip() for ln in retention_val.splitlines() if ln.strip()]:
+            if not any(f": {marker}" in line for marker in valid_markers):
+                warnings.append(f"Retention line does not use a canonical H3 relationship marker: '{line[:80]}'.")
+
+        defined_subjects = {
+            f"<Subject {m.group(2)}>"
+            for m in _TAG_RE.finditer(sections["subject_definitions"])
+            if m.group(1) == "Subject"
+        }
+        used_subjects = {
+            f"<Subject {m.group(2)}>"
+            for sec_name in ("summary", "retention_analysis", "detailed_description")
+            for m in _TAG_RE.finditer(sections[sec_name])
+            if m.group(1) == "Subject"
+        }
+        undefined_subjects = sorted(used_subjects - defined_subjects)
+        if undefined_subjects:
+            errors.append(f"Undefined subject labels referenced outside 'subject_definitions': {undefined_subjects}.")
+
+        if shot_headers and shot_headers[0].start() == 0:
+            warnings.append("Ref2VA 'detailed_description' should establish overall visual style in 1-2 sentences before '[Shot 1]'.")
+
+    if reference_sources is not None:
+        ordinals = h3_reference_ordinals(reference_sources)
+        available_tags = {
+            tag
+            for entry in ordinals
+            for tag in (entry["tag"], entry["embeddedAudioTag"])
+            if tag is not None
+        }
+        used_media_tags = {
+            f"<{kind} {num}>"
+            for kind, num in all_tags
+            if kind in {"Picture", "Video", "Audio"}
+        }
+        missing_tags = sorted(used_media_tags - available_tags)
+        if missing_tags:
+            errors.append(
+                f"Prompt references media tags {missing_tags} that do not match active reference ordinals {sorted(available_tags)}."
+            )
+
+    return {
+        "valid": not errors,
+        "mode": normalized_mode,
+        "errors": errors,
+        "warnings": warnings,
+        "detectedShots": len(shot_numbers),
+        "referencedTags": unique_tag_strings,
+    }
+
+
+def lint_shot_plan(shots: list[dict[str, Any]] | tuple[dict[str, Any], ...]) -> dict[str, Any]:
+    """Validate a multi-shot storyboard plan for H3 bounds and visual variety."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not shots:
+        return {
+            "valid": False,
+            "shotCount": 0,
+            "totalDurationSeconds": 0.0,
+            "shotSizeDiversity": 0.0,
+            "cameraMotionDiversity": 0.0,
+            "errors": ["Shot plan must contain at least one shot."],
+            "warnings": [],
+        }
+
+    total_duration = 0.0
+    normalized_sizes: list[str] = []
+    normalized_motions: list[str] = []
+    run_length = 0
+    previous_pair: tuple[str, str] | None = None
+
+    for idx, shot in enumerate(shots, start=1):
+        duration = float(shot.get("durationSeconds") or 0)
+        if not H3_MIN_DURATION <= duration <= H3_MAX_DURATION:
+            errors.append(
+                f"Shot {idx} duration ({duration:g}s) is outside MiniMax-H3's {H3_MIN_DURATION:g}-{H3_MAX_DURATION:g}s bounds."
+            )
+        total_duration += max(0.0, duration)
+
+        size = str(shot.get("shotSize") or "").strip().lower()
+        if not size:
+            errors.append(f"Shot {idx} is missing 'shotSize'.")
+        elif size not in {s.lower() for s in SHOT_SIZES}:
+            warnings.append(f"Shot {idx} uses non-standard shotSize '{shot.get('shotSize')}'.")
+        normalized_sizes.append(size)
+
+        motion_raw = str(shot.get("cameraMotion") or "").strip()
+        canonical_motion = next((key for key in CAMERA_MOTIONS if key.lower() == motion_raw.lower()), None)
+        if not motion_raw:
+            errors.append(f"Shot {idx} is missing 'cameraMotion'.")
+        elif canonical_motion is None:
+            errors.append(f"Shot {idx} uses unsupported H3 cameraMotion '{motion_raw}'.")
+        normalized_motions.append(canonical_motion or motion_raw)
+
+        mode = str(shot.get("mode") or "i2va").strip().lower()
+        if mode not in H3_MODES and mode != "continuation":
+            errors.append(f"Shot {idx} uses unsupported mode '{mode}'.")
+
+        pair = (size, canonical_motion or motion_raw)
+        if pair == previous_pair and size and motion_raw:
+            run_length += 1
+            if run_length >= 3:
+                errors.append(
+                    f"Shot {idx} repeats ({size}, {canonical_motion or motion_raw}) for {run_length} consecutive shots; vary framing or camera movement to prevent visual homogenization."
+                )
+        else:
+            previous_pair = pair
+            run_length = 1
+
+    valid_sizes = [s for s in normalized_sizes if s]
+    valid_motions = [m for m in normalized_motions if m]
+    if len(shots) >= 3 and len(set(valid_sizes)) <= 1:
+        errors.append("Multi-shot sequence (3+ shots) uses only a single shotSize across all shots.")
+    if len(shots) >= 4 and len(set(valid_motions)) <= 1:
+        warnings.append("Sequence of 4+ shots uses the same cameraMotion throughout; consider alternating static and moving shots.")
+
+    return {
+        "valid": not errors,
+        "shotCount": len(shots),
+        "totalDurationSeconds": round(total_duration, 3),
+        "shotSizeDiversity": round(len(set(valid_sizes)) / len(shots), 3),
+        "cameraMotionDiversity": round(len(set(valid_motions)) / len(shots), 3),
+        "errors": errors,
+        "warnings": warnings,
+    }
diff --git a/packages/core/src/opendirector/media/shot_inspection.py b/packages/core/src/opendirector/media/shot_inspection.py
new file mode 100644
index 000000000..eefae9dbe
--- /dev/null
+++ b/packages/core/src/opendirector/media/shot_inspection.py
@@ -0,0 +1,244 @@
+"""Local shot probing, contact-sheet rendering, and deterministic video QC."""
+from __future__ import annotations
+
+import io
+import json
+import os
+from pathlib import Path
+import tempfile
+
+from PIL import Image, ImageChops, ImageDraw, ImageStat
+
+from opendirector.domain.projects import ProjectError
+from opendirector.media import processing as media
+
+
+def _probe_streams(path: Path) -> dict:
+    raw = json.loads(media._run([
+        "ffprobe",
+        "-v",
+        "error",
+        "-protocol_whitelist",
+        "file,pipe",
+        "-show_entries",
+        "format=duration,size:stream=codec_type,codec_name,width,height,r_frame_rate,nb_frames",
+        "-of",
+        "json",
+        str(path),
+    ], timeout=60))
+    streams = raw.get("streams", [])
+    video = next((item for item in streams if item.get("codec_type") == "video"), None)
+    if video is None:
+        raise ProjectError("素材中没有视频画面。", 422)
+    audio = next((item for item in streams if item.get("codec_type") == "audio"), None)
+    num, _, den = (video.get("r_frame_rate") or "24/1").partition("/")
+    fps = float(num) / float(den or 1) if float(den or 1) else 24.0
+    fps = fps or 24.0
+    duration = float(raw.get("format", {}).get("duration") or 0.0)
+    raw_frames = video.get("nb_frames")
+    frame_count = int(raw_frames) if str(raw_frames or "").isdigit() else max(1, round(duration * fps))
+    nearest_h3 = max(5, 17 * max(0, round((frame_count - 5) / 17)) + 5)
+    return {
+        "durationSeconds": round(duration, 4),
+        "width": int(video["width"]),
+        "height": int(video["height"]),
+        "fps": round(fps, 4),
+        "frameCount": frame_count,
+        "matchesH3Grid": frame_count >= 5 and (frame_count - 5) % 17 == 0,
+        "nearestH3Frames": nearest_h3,
+        "videoCodec": str(video.get("codec_name") or "unknown"),
+        "hasAudio": audio is not None,
+        "audioCodec": str(audio.get("codec_name")) if audio is not None and audio.get("codec_name") else None,
+        "sizeBytes": int(raw.get("format", {}).get("size") or path.stat().st_size),
+    }
+
+
+def _sample_timestamps(duration_seconds: float, count: int, fps: float) -> list[float]:
+    if count <= 0:
+        return []
+    safe_end = max(0.0, duration_seconds - max(1.0 / max(fps, 1.0), 0.05))
+    if count == 1 or safe_end <= 0:
+        return [0.0] * count
+    return [round(safe_end * index / (count - 1), 3) for index in range(count)]
+
+
+def _write_exclusive_bytes(destination: Path, payload: bytes) -> None:
+    """Create destination exclusively without unlinking public paths on error."""
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+    try:
+        fd = os.open(destination, flags, 0o600)
+    except FileExistsError:
+        raise ProjectError(f"Output file already exists: {destination}", 409) from None
+    with os.fdopen(fd, "wb") as handle:
+        handle.write(payload)
+        handle.flush()
+
+
+def _write_cache_bytes(destination: Path, payload: bytes) -> None:
+    """Atomically refresh a trusted internal preview-cache rendition."""
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix=".sheet-", suffix=".tmp", dir=destination.parent)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+        os.replace(temp_name, destination)
+    except BaseException:
+        try:
+            os.unlink(temp_name)
+        except OSError:
+            pass
+        raise
+
+
+def _mean_abs_diff(first: Image.Image, second: Image.Image) -> float:
+    diff = ImageChops.difference(first, second)
+    return float(ImageStat.Stat(diff).mean[0])
+
+
+def _compute_measured_facts(technical: dict, gray_frames: list[Image.Image] | None) -> dict:
+    warnings: list[str] = []
+    if not technical["matchesH3Grid"]:
+        warnings.append(
+            f"Frame count {technical['frameCount']} does not align to MiniMax-H3 17n+5 grid "
+            f"(nearest: {technical['nearestH3Frames']})."
+        )
+    if not technical["hasAudio"]:
+        warnings.append("Video contains no audio stream.")
+
+    motion = None
+    exposure = None
+    if gray_frames:
+        luma_stats = [
+            (float(stat.mean[0]), float(stat.stddev[0]))
+            for stat in (ImageStat.Stat(frame) for frame in gray_frames)
+        ]
+        deltas = [
+            round(_mean_abs_diff(gray_frames[index], gray_frames[index + 1]), 3)
+            for index in range(len(gray_frames) - 1)
+        ]
+        mean_delta = round(sum(deltas) / len(deltas), 3) if deltas else 0.0
+        max_delta = round(max(deltas), 3) if deltas else 0.0
+        first_last_diff = _mean_abs_diff(gray_frames[0], gray_frames[-1]) if len(gray_frames) >= 2 else 0.0
+        similarity = round(max(0.0, min(1.0, 1.0 - first_last_diff / 255.0)), 4)
+        suspected_frozen = bool(len(gray_frames) >= 2 and max_delta < 1.5)
+        black_indices = [
+            index for index, (mean_luma, std_luma) in enumerate(luma_stats)
+            if mean_luma < 6.0 and std_luma < 3.0
+        ]
+        black_ratio = round(len(black_indices) / len(luma_stats), 4)
+        if suspected_frozen:
+            warnings.append(
+                "Sampled frames show near-zero pixel motion (maxFrameDelta < 1.5); "
+                "verify whether the video actually animates."
+            )
+        if black_indices:
+            warnings.append(
+                f"Detected {len(black_indices)} near-black sampled frame(s) at tile index(es) {black_indices}."
+            )
+        motion = {
+            "sampledFrames": len(gray_frames),
+            "meanFrameDelta": mean_delta,
+            "maxFrameDelta": max_delta,
+            "firstLastSimilarity": similarity,
+            "suspectedFrozen": suspected_frozen,
+        }
+        exposure = {
+            "blackFrameIndices": black_indices,
+            "blackFrameRatio": black_ratio,
+        }
+
+    return {
+        "source": "measured",
+        "reviewRequired": True,
+        "technical": technical,
+        "motion": motion,
+        "exposure": exposure,
+        "warnings": warnings,
+    }
+
+
+def inspect_video_shot(
+    video_path: Path,
+    *,
+    contact_sheet_path: Path | None = None,
+    columns: int = 4,
+    rows: int = 3,
+    tile_long_edge: int = 320,
+    overwrite_cache: bool = False,
+) -> dict:
+    """Probe a video file and optionally render a timestamped JPEG contact sheet."""
+    if not video_path.is_file():
+        raise ProjectError(f"Video file does not exist: {video_path}", 404)
+    if columns < 1 or columns > 8 or rows < 1 or rows > 8:
+        raise ProjectError("Contact sheet grid dimensions must be between 1 and 8.", 422)
+
+    technical = _probe_streams(video_path)
+    if contact_sheet_path is None:
+        return {
+            "path": str(video_path.resolve()),
+            "technical": technical,
+            "contactSheet": None,
+            "measuredFacts": _compute_measured_facts(technical, None),
+        }
+    if not overwrite_cache and contact_sheet_path.exists():
+        raise ProjectError(f"Output file already exists: {contact_sheet_path}", 409)
+
+    total_tiles = columns * rows
+    timestamps = _sample_timestamps(technical["durationSeconds"], total_tiles, technical["fps"])
+    aspect = technical["width"] / max(1, technical["height"])
+    if aspect >= 1.0:
+        tile_w = tile_long_edge
+        tile_h = max(48, round(tile_long_edge / aspect))
+    else:
+        tile_h = tile_long_edge
+        tile_w = max(48, round(tile_long_edge * aspect))
+
+    pad = 6
+    sheet_w = columns * tile_w + (columns + 1) * pad
+    sheet_h = rows * tile_h + (rows + 1) * pad
+    sheet = Image.new("RGB", (sheet_w, sheet_h), (18, 18, 22))
+    draw = ImageDraw.Draw(sheet)
+    gray_frames: list[Image.Image] = []
+
+    with media.Workspace() as work:
+        for index, stamp in enumerate(timestamps):
+            frame_bytes = media.frame_at(video_path, stamp, work.path / f"tile-{index:02d}.png")
+            frame = media.open_image(frame_bytes).convert("RGB")
+            gray_frames.append(frame.convert("L").resize((64, 64), Image.Resampling.BILINEAR))
+            resized = media.resize(frame, tile_w, tile_h)
+            col, row = index % columns, index // columns
+            x = pad + col * (tile_w + pad)
+            y = pad + row * (tile_h + pad)
+            sheet.paste(resized, (x, y))
+            minutes = int(stamp // 60)
+            seconds = stamp - minutes * 60
+            label = f"#{index + 1:02d} {minutes:02d}:{seconds:05.2f}"
+            badge_w = max(78, len(label) * 7 + 8)
+            draw.rectangle((x + 4, y + 4, x + 4 + badge_w, y + 20), fill=(0, 0, 0))
+            draw.text((x + 8, y + 6), label, fill=(245, 245, 245))
+
+    buffer = io.BytesIO()
+    sheet.save(buffer, format="JPEG", quality=84, optimize=True)
+    jpeg_bytes = buffer.getvalue()
+    if overwrite_cache:
+        _write_cache_bytes(contact_sheet_path, jpeg_bytes)
+    else:
+        _write_exclusive_bytes(contact_sheet_path, jpeg_bytes)
+
+    return {
+        "path": str(video_path.resolve()),
+        "technical": technical,
+        "contactSheet": {
+            "path": str(contact_sheet_path.resolve()),
+            "columns": columns,
+            "rows": rows,
+            "tileCount": total_tiles,
+            "width": sheet_w,
+            "height": sheet_h,
+            "sizeBytes": len(jpeg_bytes),
+            "timestamps": timestamps,
+        },
+        "measuredFacts": _compute_measured_facts(technical, gray_frames),
+    }
diff --git a/src/contracts/creation.schema.json b/src/contracts/creation.schema.json
index 5eb935515..020a09c6f 100644
--- a/src/contracts/creation.schema.json
+++ b/src/contracts/creation.schema.json
@@ -490,6 +490,32 @@
             "format": "uuid",
             "title": "Objectid",
             "type": "string"
+          },
+          "videoScope": {
+            "default": "first_frame",
+            "description": "Video preview mode: single first frame or multi-frame timestamped contact sheet.",
+            "enum": [
+              "first_frame",
+              "contact_sheet"
+            ],
+            "title": "Videoscope",
+            "type": "string"
+          },
+          "columns": {
+            "default": 4,
+            "description": "Contact-sheet grid columns for videoScope=\"contact_sheet\".",
+            "maximum": 8,
+            "minimum": 1,
+            "title": "Columns",
+            "type": "integer"
+          },
+          "rows": {
+            "default": 3,
+            "description": "Contact-sheet grid rows for videoScope=\"contact_sheet\".",
+            "maximum": 8,
+            "minimum": 1,
+            "title": "Rows",
+            "type": "integer"
           }
         },
         "required": [
@@ -3921,7 +3947,8 @@
                 "generationSpec.versions": "#/$defs/VersionsQuery",
                 "job.get": "#/$defs/ObjectQuery",
                 "object.get": "#/$defs/ObjectQuery",
-                "project.get": "#/$defs/ProjectQuery"
+                "project.get": "#/$defs/ProjectQuery",
+                "storyboard.audit": "#/$defs/StoryboardAuditQuery"
               },
               "propertyName": "type"
             },
@@ -3946,6 +3973,9 @@
               },
               {
                 "$ref": "#/$defs/AssetPreviewQuery"
+              },
+              {
+                "$ref": "#/$defs/StoryboardAuditQuery"
               }
             ],
             "title": "Query"
@@ -11512,6 +11542,82 @@
         "title": "StageTransform",
         "type": "object"
       },
+      "StoryboardAuditQuery": {
+        "additionalProperties": false,
+        "properties": {
+          "queryId": {
+            "description": "Caller-supplied query ID.",
+            "format": "uuid",
+            "title": "Queryid",
+            "type": "string"
+          },
+          "projectId": {
+            "description": "Owning project ID.",
+            "format": "uuid",
+            "title": "Projectid",
+            "type": "string"
+          },
+          "type": {
+            "const": "storyboard.audit",
+            "description": "Audit multi-shot continuity, H3 prompt/ordinal alignment, diversity, and pilot-gate readiness.",
+            "title": "Type",
+            "type": "string"
+          },
+          "timelineEditorId": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional timeline editor document ID to order and scope shots.",
+            "title": "Timelineeditorid"
+          },
+          "groupId": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional canvas group item ID to scope shots.",
+            "title": "Groupid"
+          },
+          "specIds": {
+            "anyOf": [
+              {
+                "items": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "maxItems": 200,
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional explicit ordered video GenerationSpec IDs to audit.",
+            "title": "Specids"
+          }
+        },
+        "required": [
+          "queryId",
+          "projectId",
+          "type"
+        ],
+        "title": "StoryboardAuditQuery",
+        "type": "object"
+      },
       "SubjectCanvasItem": {
         "additionalProperties": false,
         "properties": {
@@ -14962,7 +15068,8 @@
             "generationSpec.versions": "#/$defs/VersionsQuery",
             "job.get": "#/$defs/ObjectQuery",
             "object.get": "#/$defs/ObjectQuery",
-            "project.get": "#/$defs/ProjectQuery"
+            "project.get": "#/$defs/ProjectQuery",
+            "storyboard.audit": "#/$defs/StoryboardAuditQuery"
           },
           "propertyName": "type"
         },
@@ -14987,6 +15094,9 @@
           },
           {
             "$ref": "#/$defs/AssetPreviewQuery"
+          },
+          {
+            "$ref": "#/$defs/StoryboardAuditQuery"
           }
         ],
         "title": "Query"
@@ -15613,13 +15723,42 @@
             "format": "uuid",
             "title": "Objectid",
             "type": "string"
+          },
+          "videoScope": {
+            "default": "first_frame",
+            "description": "Video preview mode: single first frame or multi-frame timestamped contact sheet.",
+            "enum": [
+              "first_frame",
+              "contact_sheet"
+            ],
+            "title": "Videoscope",
+            "type": "string"
+          },
+          "columns": {
+            "default": 4,
+            "description": "Contact-sheet grid columns for videoScope=\"contact_sheet\".",
+            "maximum": 8,
+            "minimum": 1,
+            "title": "Columns",
+            "type": "integer"
+          },
+          "rows": {
+            "default": 3,
+            "description": "Contact-sheet grid rows for videoScope=\"contact_sheet\".",
+            "maximum": 8,
+            "minimum": 1,
+            "title": "Rows",
+            "type": "integer"
           }
         },
         "required": [
           "queryId",
           "projectId",
           "type",
-          "objectId"
+          "objectId",
+          "videoScope",
+          "columns",
+          "rows"
         ],
         "title": "AssetPreviewQuery",
         "type": "object"
@@ -19146,7 +19285,8 @@
                 "generationSpec.versions": "#/$defs/VersionsQuery",
                 "job.get": "#/$defs/ObjectQuery",
                 "object.get": "#/$defs/ObjectQuery",
-                "project.get": "#/$defs/ProjectQuery"
+                "project.get": "#/$defs/ProjectQuery",
+                "storyboard.audit": "#/$defs/StoryboardAuditQuery"
               },
               "propertyName": "type"
             },
@@ -19171,6 +19311,9 @@
               },
               {
                 "$ref": "#/$defs/AssetPreviewQuery"
+              },
+              {
+                "$ref": "#/$defs/StoryboardAuditQuery"
               }
             ],
             "title": "Query"
@@ -27036,6 +27179,85 @@
         "title": "StageTransform",
         "type": "object"
       },
+      "StoryboardAuditQuery": {
+        "additionalProperties": false,
+        "properties": {
+          "queryId": {
+            "description": "Caller-supplied query ID.",
+            "format": "uuid",
+            "title": "Queryid",
+            "type": "string"
+          },
+          "projectId": {
+            "description": "Owning project ID.",
+            "format": "uuid",
+            "title": "Projectid",
+            "type": "string"
+          },
+          "type": {
+            "const": "storyboard.audit",
+            "description": "Audit multi-shot continuity, H3 prompt/ordinal alignment, diversity, and pilot-gate readiness.",
+            "title": "Type",
+            "type": "string"
+          },
+          "timelineEditorId": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional timeline editor document ID to order and scope shots.",
+            "title": "Timelineeditorid"
+          },
+          "groupId": {
+            "anyOf": [
+              {
+                "format": "uuid",
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional canvas group item ID to scope shots.",
+            "title": "Groupid"
+          },
+          "specIds": {
+            "anyOf": [
+              {
+                "items": {
+                  "format": "uuid",
+                  "type": "string"
+                },
+                "maxItems": 200,
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Optional explicit ordered video GenerationSpec IDs to audit.",
+            "title": "Specids"
+          }
+        },
+        "required": [
+          "queryId",
+          "projectId",
+          "type",
+          "timelineEditorId",
+          "groupId",
+          "specIds"
+        ],
+        "title": "StoryboardAuditQuery",
+        "type": "object"
+      },
       "SubjectCanvasItem": {
         "additionalProperties": false,
         "properties": {
@@ -30644,7 +30866,8 @@
             "generationSpec.versions": "#/$defs/VersionsQuery",
             "job.get": "#/$defs/ObjectQuery",
             "object.get": "#/$defs/ObjectQuery",
-            "project.get": "#/$defs/ProjectQuery"
+            "project.get": "#/$defs/ProjectQuery",
+            "storyboard.audit": "#/$defs/StoryboardAuditQuery"
           },
           "propertyName": "type"
         },
@@ -30669,6 +30892,9 @@
           },
           {
             "$ref": "#/$defs/AssetPreviewQuery"
+          },
+          {
+            "$ref": "#/$defs/StoryboardAuditQuery"
           }
         ],
         "title": "Query"
diff --git a/src/contracts/generated.ts b/src/contracts/generated.ts
index 3e5a30968..e5916a9c5 100644
--- a/src/contracts/generated.ts
+++ b/src/contracts/generated.ts
@@ -57,6 +57,9 @@ export interface AssetMetadataUpdateInput extends ContractInput {
 export interface AssetPreviewQueryInput extends QueryBaseInput {
   readonly type: "asset.preview";
   readonly objectId: string;
+  readonly videoScope?: "first_frame" | "contact_sheet";
+  readonly columns?: number;
+  readonly rows?: number;
 }
 
 export interface AssetProvenanceInput extends ContractInput {
@@ -402,7 +405,7 @@ export interface CreationContractsInput extends ContractInput {
   readonly editorDocument: TimelineDocumentInput | SubjectDocumentInput | LayerDocumentInput | ImageCropDocumentInput | StackDocumentInput | ToolDocumentInput | DirectorDocumentInput | MediaEditDocumentInput;
   readonly command: ProjectCreateCommandInput | ProjectRenameCommandInput | ProjectTrashCommandInput | ProjectRestoreCommandInput | AssetImportCommandInput | ArtifactPublishCommandInput | AssetWriteTextCommandInput | AssetMetadataCommandInput | AssetDeleteCommandInput | CanvasCreateGenerationCommandInput | CanvasShowCommandInput | CanvasMoveCommandInput | CanvasUpdateCommandInput | CanvasHideCommandInput | CanvasMaterializeCommandInput | CanvasApplyEditCommandInput | CanvasPublishMediaCommandInput | TimelinePublishRenderCommandInput | NodeVersionApplyCommandInput | CanvasConfigureCommandInput | CanvasEditorAttachCommandInput | CanvasEditorDetachCommandInput | SpecCreateCommandInput | SpecUpdateCommandInput | SpecRestoreCommandInput | SpecPromptCommandInput | ReferenceAddCommandInput | ReferenceUpdateCommandInput | ReferenceRestoreCommandInput | ReferenceRemoveCommandInput | GenerationSubmitCommandInput | JobCancelCommandInput | JobRecoverCommandInput | JobCheckpointCommandInput | ResultSelectCommandInput | EditorCreateCommandInput | EditorSaveCommandInput | HistoryUndoCommandInput | HistoryRedoCommandInput | BatchCommandInput;
   readonly receipt: CommandReceiptInput;
-  readonly query: ProjectQueryInput | ObjectQueryInput | VersionsQueryInput | AssetSearchQueryInput | AssetUsageQueryInput | CanvasStatusQueryInput | AssetPreviewQueryInput;
+  readonly query: ProjectQueryInput | ObjectQueryInput | VersionsQueryInput | AssetSearchQueryInput | AssetUsageQueryInput | CanvasStatusQueryInput | AssetPreviewQueryInput | StoryboardAuditQueryInput;
   readonly event: ProjectEventInput;
   readonly job: JobInput;
   readonly result: ResultVersionInput;
@@ -1213,6 +1216,13 @@ export interface StageTransformInput extends ContractInput {
   readonly scale: Vector3Input;
 }
 
+export interface StoryboardAuditQueryInput extends QueryBaseInput {
+  readonly type: "storyboard.audit";
+  readonly timelineEditorId?: string | null;
+  readonly groupId?: string | null;
+  readonly specIds?: ReadonlyArray<string> | null;
+}
+
 export interface SubjectCanvasItemInput extends EditorCanvasItemInput {
   readonly kind: "subject";
 }
@@ -1632,6 +1642,9 @@ export interface AssetMetadataUpdate extends Contract {
 export interface AssetPreviewQuery extends QueryBase {
   readonly type: "asset.preview";
   readonly objectId: string;
+  readonly videoScope: "first_frame" | "contact_sheet";
+  readonly columns: number;
+  readonly rows: number;
 }
 
 export interface AssetProvenance extends Contract {
@@ -1977,7 +1990,7 @@ export interface CreationContracts extends Contract {
   readonly editorDocument: TimelineDocument | SubjectDocument | LayerDocument | ImageCropDocument | StackDocument | ToolDocument | DirectorDocument | MediaEditDocument;
   readonly command: ProjectCreateCommand | ProjectRenameCommand | ProjectTrashCommand | ProjectRestoreCommand | AssetImportCommand | ArtifactPublishCommand | AssetWriteTextCommand | AssetMetadataCommand | AssetDeleteCommand | CanvasCreateGenerationCommand | CanvasShowCommand | CanvasMoveCommand | CanvasUpdateCommand | CanvasHideCommand | CanvasMaterializeCommand | CanvasApplyEditCommand | CanvasPublishMediaCommand | TimelinePublishRenderCommand | NodeVersionApplyCommand | CanvasConfigureCommand | CanvasEditorAttachCommand | CanvasEditorDetachCommand | SpecCreateCommand | SpecUpdateCommand | SpecRestoreCommand | SpecPromptCommand | ReferenceAddCommand | ReferenceUpdateCommand | ReferenceRestoreCommand | ReferenceRemoveCommand | GenerationSubmitCommand | JobCancelCommand | JobRecoverCommand | JobCheckpointCommand | ResultSelectCommand | EditorCreateCommand | EditorSaveCommand | HistoryUndoCommand | HistoryRedoCommand | BatchCommand;
   readonly receipt: CommandReceipt;
-  readonly query: ProjectQuery | ObjectQuery | VersionsQuery | AssetSearchQuery | AssetUsageQuery | CanvasStatusQuery | AssetPreviewQuery;
+  readonly query: ProjectQuery | ObjectQuery | VersionsQuery | AssetSearchQuery | AssetUsageQuery | CanvasStatusQuery | AssetPreviewQuery | StoryboardAuditQuery;
   readonly event: ProjectEvent;
   readonly job: Job;
   readonly result: ResultVersion;
@@ -2787,6 +2800,13 @@ export interface StageTransform extends Contract {
   readonly scale: Vector3;
 }
 
+export interface StoryboardAuditQuery extends QueryBase {
+  readonly type: "storyboard.audit";
+  readonly timelineEditorId: string | null;
+  readonly groupId: string | null;
+  readonly specIds: ReadonlyArray<string> | null;
+}
+
 export interface SubjectCanvasItem extends EditorCanvasItem {
   readonly kind: "subject";
 }
diff --git a/tests/test_h3_shot_orchestration.py b/tests/test_h3_shot_orchestration.py
new file mode 100644
index 000000000..17f1d9a4b
--- /dev/null
+++ b/tests/test_h3_shot_orchestration.py
@@ -0,0 +1,890 @@
+"""Verify H3 cinematography compilation/linting, shot inspection, skill snapshot, and timeline shot revision."""
+from io import BytesIO
+import json
+from pathlib import Path
+import shutil
+import subprocess
+from uuid import uuid4
+
+from fastapi.testclient import TestClient
+import httpx
+from PIL import Image
+import pytest
+from typer.testing import CliRunner
+
+from opendirector import cli
+from opendirector.agent.context import RunContext
+from opendirector.agent.gateway import ToolGateway
+from opendirector.agent.skill_snapshot import prepare_skills
+from opendirector.agent.tools import AgentTools
+from opendirector.application.creation_assets import CreationAssets
+from opendirector.domain.creation.commands import parse_command
+from opendirector.domain.h3_cinematography import (
+    compile_h3_prompt,
+    format_camera_motion,
+    format_dialogue,
+    h3_frame_grid,
+    h3_reference_ordinals,
+    lint_h3_prompt,
+    lint_shot_plan,
+)
+from opendirector.infrastructure.creation_projects import CreationProjects
+from opendirector.infrastructure.local_projects import LocalProjects
+from opendirector.infrastructure.model_configs import ModelConfigs
+from opendirector.installation import builtin_skills
+from opendirector.integrations.fasth3 import native_prompt
+from opendirector.media import probe as media_probe
+from opendirector.media import processing as media
+from opendirector_api.main import create_app
+
+
+@pytest.fixture
+def anyio_backend():
+    return "asyncio"
+
+
+def _stage_and_import(projects, project_id, session, name, kind, data):
+    handle = uuid4()
+    writer = CreationAssets(projects).uploads.begin(project_id, handle, session, name, expected_kind=kind)
+    try:
+        writer.write(data)
+        writer.finish()
+    finally:
+        writer.abort()
+    receipt = projects.execute(parse_command({
+        "type": "asset.import",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {"uploadHandle": str(handle), "expectedKind": kind, "name": name},
+    }), session=session)
+    assert receipt.status == "applied", receipt
+    asset_id = next(c.id for c in receipt.changed if c.objectType == "asset")
+    return next(a for a in projects.snapshot(project_id).assets if a.id == asset_id)
+
+
+def _png_bytes(color=(30, 90, 160), size=(320, 240)):
+    buf = BytesIO()
+    Image.new("RGB", size, color).save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def test_h3_reference_ordinals_match_fasth3_native_prompt_audio_offset():
+    sources = [
+        ({"id": "img-1", "name": "hero.png", "hasAudio": False}, "image"),
+        ({"id": "vid-1", "name": "ref-dance.mp4", "hasAudio": True}, "video"),
+        ({"id": "aud-1", "name": "voice.wav", "hasAudio": True}, "audio"),
+        ({"id": "vid-2", "name": "silent-cam.mp4", "hasAudio": False}, "video"),
+        ({"id": "img-2", "name": "prop.png", "hasAudio": False}, "image"),
+        ({"id": "aud-2", "name": "bgm.mp3", "hasAudio": True}, "audio"),
+    ]
+    prompt_content = []
+    for meta, _ in sources:
+        prompt_content.append({"type": "reference", "assetId": meta["id"], "name": meta["name"]})
+        prompt_content.append({"type": "text", "text": " "})
+    rendered = native_prompt({"prompt": "", "promptContent": prompt_content}, sources).strip().split()
+
+    ordinal_inputs = [{**meta, "kind": kind} for meta, kind in sources]
+    ordinals = h3_reference_ordinals(ordinal_inputs)
+    assert [entry["tag"] for entry in ordinals] == [
+        "<Picture 1>",
+        "<Video 1>",
+        "<Audio 2>",
+        "<Video 2>",
+        "<Picture 2>",
+        "<Audio 3>",
+    ]
+    assert " ".join(entry["tag"] for entry in ordinals) == " ".join(rendered)
+    assert ordinals[1]["embeddedAudioTag"] == "<Audio 1>"
+    assert ordinals[3]["embeddedAudioTag"] is None
+
+
+@pytest.mark.parametrize("mode", ["t2va", "i2va", "fl2va", "l2va"])
+def test_compile_and_lint_base_h3_modes_and_camera_dialogue_grammar(mode):
+    grid = h3_frame_grid(7.0)
+    assert grid["gridFrames"] == 175
+    assert (grid["gridFrames"] - 5) % 17 == 0
+
+    cam = format_camera_motion("Push In", amplitude="small", speed="slow", detail="toward the brass compass")
+    assert cam == "The camera pushes in with small amplitude at slow speed toward the brass compass."
+
+    vo = format_dialogue(
+        "S1", "English", "We are almost out of time.",
+        speaker_intro="The navigator", voiceover=True,
+    )
+    assert vo == (
+        "The navigator (S1) says in an off-screen voiceover: "
+        "<d>[English] We are almost out of time.</d> while their lips remain completely closed."
+    )
+
+    compiled = compile_h3_prompt({
+        "mode": mode,
+        "durationSeconds": 8.0,
+        "style": "Live-action, cinematic",
+        "shots": [
+            {
+                "shotSize": "medium-wide shot",
+                "description": "The navigator stands beside <Picture 1> at the helm as spray crosses the deck",
+                "cameraMotion": {"type": "Push In", "amplitude": "small", "speed": "slow", "detail": "toward the helm"},
+                "dialogues": [
+                    {
+                        "speakerId": "S1",
+                        "speakerIntro": "The weathered navigator",
+                        "language": "Chinese",
+                        "text": "稳住航向！",
+                    }
+                ],
+            },
+            {
+                "atSeconds": 4.25,
+                "shotSize": "close-up",
+                "description": "The compass needle settles onto north, matching Picture 2 at the end",
+                "cameraMotion": "Static Shot",
+            },
+        ],
+        "overallSoundscape": "Ocean wind and timber creaks continue underneath crashing bow spray.",
+        "nonDiegeticMusic": "Low brass notes at a slow tempo with a restrained percussive pulse.",
+    })
+    assert compiled["lint"]["valid"] is True, compiled["lint"]
+    assert compiled["lint"]["detectedShots"] == 2
+    if mode == "i2va":
+        assert compiled["prompt"].startswith(
+            "For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.\n\n"
+        )
+    elif mode == "fl2va":
+        assert compiled["prompt"].startswith(
+            "How the reference pictures align with the target video — "
+            "Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; "
+            "Picture 2 (from Shot 2) aligns with the 8.00-second mark of the target video.\n\n"
+        )
+    elif mode == "l2va":
+        assert compiled["prompt"].startswith(
+            "How the reference pictures align with the target video — "
+            "<Picture 1> (from [Shot 2]) aligns with the 8.00-second mark of the target video.\n\n"
+        )
+
+
+def test_compile_and_lint_ref2va_catches_ordinal_and_retention_defects():
+    sources = [
+        {"id": "img-1", "name": "cafe.png", "kind": "image", "hasAudio": False},
+        {"id": "vid-1", "name": "actor.mp4", "kind": "video", "hasAudio": True},
+        {"id": "aud-1", "name": "timbre.wav", "kind": "audio", "hasAudio": True},
+    ]
+    valid_spec = {
+        "mode": "ref2va",
+        "durationSeconds": 6.0,
+        "taskTypes": ["reference generation", "audio reference"],
+        "subjectDefinitions": [
+            "<Subject 1> is the sunlit cafe interior in <Picture 1> with dark walnut tables.",
+            "<Subject 2> is the detective in <Video 1> wearing a charcoal trench coat.",
+            "<Audio 2> is the voice-timbre reference for <Subject 2> (S1).",
+        ],
+        "summary": "The target video places <Subject 2> inside <Subject 1>, speaking with the vocal timbre of <Audio 2>.",
+        "retentionAnalysis": [
+            "<Subject 1> (appears in [Shot 1]): fully_preserved - walnut tables and window light are retained.",
+            "<Subject 2> (appears in [Shot 1]): fully_preserved - facial features and charcoal coat are retained.",
+            "<Audio 2>: reference - guides the measured vocal timbre without copying the source waveform.",
+        ],
+        "styleOpening": "The target video uses a live-action neo-noir style with warm practical lamps",
+        "shots": [
+            {
+                "shotSize": "medium close-up",
+                "description": "<Subject 2> sits in <Subject 1> and sets a brass key on the table",
+                "cameraMotion": "Truck Right",
+                "cameraAmplitude": "small",
+                "cameraSpeed": "slow",
+                "dialogues": [
+                    {
+                        "speakerId": "S1",
+                        "speakerIntro": "<Subject 2>",
+                        "language": "English",
+                        "text": "You left this at the pier.",
+                    }
+                ],
+            }
+        ],
+        "overallSoundscape": "Low cafe murmur and rain against glass continue softly.",
+        "nonDiegeticMusic": "N/A",
+        "referenceSources": sources,
+    }
+    compiled = compile_h3_prompt(valid_spec)
+    assert compiled["lint"]["valid"] is True, compiled["lint"]
+
+    broken = compiled["prompt"].replace("<Audio 2>", "<Audio 3>").replace(
+        "fully_preserved - facial", "(S1) fully_preserved - <Subject 9> facial"
+    )
+    report = lint_h3_prompt(broken, mode="ref2va", duration_seconds=6.0, reference_sources=sources)
+    assert report["valid"] is False
+    joined = " | ".join(report["errors"])
+    assert "<Audio 3>" in joined
+    assert "speaker IDs" in joined
+    assert "<Subject 9>" in joined
+
+
+def test_lint_shot_plan_prevents_homogenization_and_enforces_duration_bounds():
+    monotonous = [
+        {"durationSeconds": 5, "shotSize": "medium shot", "cameraMotion": "Static Shot", "mode": "i2va"},
+        {"durationSeconds": 5, "shotSize": "medium shot", "cameraMotion": "Static Shot", "mode": "i2va"},
+        {"durationSeconds": 18, "shotSize": "medium shot", "cameraMotion": "Static Shot", "mode": "i2va"},
+    ]
+    bad = lint_shot_plan(monotonous)
+    assert bad["valid"] is False
+    assert any("consecutive shots" in err for err in bad["errors"])
+    assert any("outside MiniMax-H3" in err for err in bad["errors"])
+
+    diverse = [
+        {"durationSeconds": 5, "shotSize": "wide shot", "cameraMotion": "Push In", "mode": "i2va"},
+        {"durationSeconds": 6, "shotSize": "medium close-up", "cameraMotion": "Truck Right", "mode": "ref2va"},
+        {"durationSeconds": 5, "shotSize": "close-up", "cameraMotion": "Static Shot", "mode": "fl2va"},
+    ]
+    good = lint_shot_plan(diverse)
+    assert good["valid"] is True, good
+    assert good["shotSizeDiversity"] == 1.0
+    assert good["cameraMotionDiversity"] == 1.0
+
+
+def test_cli_h3_workflow_inspect_shot_and_surgical_timeline_revise(tmp_path, monkeypatch):
+    local = LocalProjects(tmp_path)
+    projects = CreationProjects(local)
+    models = ModelConfigs(tmp_path)
+    model_id = models.save(
+        "video", "http://127.0.0.1:19999/v1", "MiniMax-H3", "",
+        connection_type="self_hosted", protocol="vllm_omni", auth_mode="none",
+    )["id"]
+
+    api = TestClient(create_app(local), headers={"X-OpenDirector-Request": "1"})
+    original_client = httpx.Client
+    monkeypatch.setattr(
+        cli.httpx,
+        "Client",
+        lambda **kwargs: original_client(
+            **kwargs,
+            transport=httpx.MockTransport(
+                lambda req: httpx.Response(
+                    *(lambda res: (res.status_code,))(
+                        res := api.request(
+                            req.method,
+                            req.url.path + (f"?{req.url.query.decode()}" if req.url.query else ""),
+                            headers=dict(req.headers),
+                            content=req.read(),
+                        )
+                    ),
+                    headers=res.headers,
+                    content=res.content,
+                )
+            ),
+        ),
+    )
+
+    project_id = uuid4()
+    session = str(uuid4())
+    projects.execute(parse_command({
+        "type": "project.create",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {"name": "H3 Orchestration"},
+    }))
+    projects.open(project_id, session)
+
+    ffprobe_payload = json.dumps({
+        "format": {
+            "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
+            "duration": "5.1667",
+            "size": "12345",
+            "tags": {"major_brand": "isom"},
+        },
+        "streams": [
+            {
+                "codec_type": "video",
+                "codec_name": "h264",
+                "width": 832,
+                "height": 480,
+                "r_frame_rate": "24/1",
+                "avg_frame_rate": "24/1",
+                "nb_frames": "124",
+            },
+            {"codec_type": "audio", "codec_name": "aac"},
+        ],
+    }).encode("utf-8")
+    monkeypatch.setattr(media_probe, "require_ffprobe", lambda: None)
+    monkeypatch.setattr(
+        media_probe.subprocess,
+        "run",
+        lambda cmd, **kw: subprocess.CompletedProcess(cmd, 0, stdout=ffprobe_payload, stderr=b""),
+    )
+    monkeypatch.setattr(media, "_run", lambda cmd, timeout=60: ffprobe_payload)
+    monkeypatch.setattr(
+        media,
+        "frame_at",
+        lambda path, seconds, out: _png_bytes((40, int(seconds * 30) % 255, 120), (832, 480)),
+    )
+
+    img_start = _stage_and_import(projects, project_id, session, "start.png", "image", _png_bytes((20, 40, 80)))
+    img_end = _stage_and_import(projects, project_id, session, "end.png", "image", _png_bytes((180, 90, 40)))
+    img_s1 = _stage_and_import(projects, project_id, session, "shot1.png", "image", _png_bytes((50, 120, 90)))
+    img_s2_old = _stage_and_import(projects, project_id, session, "shot2_old.png", "image", _png_bytes((100, 100, 100)))
+    img_s2_new = _stage_and_import(projects, project_id, session, "shot2_new.png", "image", _png_bytes((220, 160, 60)))
+    img_s3 = _stage_and_import(projects, project_id, session, "shot3.png", "image", _png_bytes((70, 50, 140)))
+    seed_video = _stage_and_import(projects, project_id, session, "seed.mp4", "video", b"mp4-fixture-bytes")
+
+    start_item, end_item, s1_item, s2_new_item = uuid4(), uuid4(), uuid4(), uuid4()
+    for item_id, asset_obj, x_pos in [
+        (start_item, img_start, 0),
+        (end_item, img_end, 0),
+        (s1_item, img_s1, 360),
+        (s2_new_item, img_s2_new, 720),
+    ]:
+        projects.execute(parse_command({
+            "type": "canvas.show",
+            "projectId": project_id,
+            "commandId": uuid4(),
+            "payload": {
+                "item": {
+                    "id": str(item_id),
+                    "projectId": str(project_id),
+                    "kind": asset_obj.kind,
+                    "position": {"x": x_pos, "y": 0},
+                    "binding": {
+                        "role": "material",
+                        "objectRef": {
+                            "assetId": str(asset_obj.id),
+                            "revision": asset_obj.revision,
+                            "fingerprint": asset_obj.fingerprint,
+                            "kind": asset_obj.kind,
+                        },
+                    },
+                },
+            },
+        }), session=session)
+
+    # Also create a populated video generation item on canvas to exercise --continue-from
+    seed_video_spec, seed_video_item = uuid4(), uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(seed_video_spec),
+                "projectId": str(project_id),
+                "kind": "video",
+                "purpose": "generation",
+                "modelConfigId": model_id,
+                "prompt": "Seed clip",
+                "parameters": {"videoMode": "first_frame", "durationSeconds": 5},
+            },
+            "item": {
+                "id": str(seed_video_item),
+                "projectId": str(project_id),
+                "kind": "video",
+                "position": {"x": 1080, "y": 0},
+                "binding": {
+                    "role": "generation",
+                    "objectRef": {"id": str(seed_video_spec)},
+                    "materialOverride": {
+                        "assetId": str(seed_video.id),
+                        "revision": seed_video.revision,
+                        "fingerprint": seed_video.fingerprint,
+                        "kind": seed_video.kind,
+                    },
+                },
+            },
+            "references": [],
+        },
+    }), session=session)
+
+    timeline_id = uuid4()
+
+    def _img_clip(cid, asset_obj, dur=4.5):
+        return {
+            "id": cid,
+            "resource": {
+                "asset": {
+                    "assetId": str(asset_obj.id),
+                    "revision": asset_obj.revision,
+                    "fingerprint": asset_obj.fingerprint,
+                    "kind": asset_obj.kind,
+                },
+                "title": asset_obj.name,
+                "durationSeconds": None,
+            },
+            "inPoint": 0.0,
+            "outPoint": dur,
+        }
+
+    c1 = _img_clip("shot-1", img_s1, 5.0)
+    c2 = _img_clip("shot-2", img_s2_old, 4.5)
+    c3 = _img_clip("shot-3", img_s3, 6.0)
+    tl_receipt = projects.execute(parse_command({
+        "type": "editor.create",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "document": {
+                "id": str(timeline_id),
+                "projectId": str(project_id),
+                "kind": "timeline",
+                "inputConnections": [{
+                    "id": str(uuid4()),
+                    "sourceId": str(s1_item),
+                    "slotId": "shot-1",
+                    "asset": c1["resource"]["asset"],
+                }],
+                "data": {
+                    "fps": 24,
+                    "width": 320,
+                    "height": 240,
+                    "tracks": [
+                        {"id": "visual-main", "kind": "visual", "title": "Main", "clips": [c1, c2, c3]},
+                        {"id": "audio-bgm", "kind": "audio", "title": "BGM", "clips": []},
+                    ],
+                    "importedAssets": [c1["resource"], c2["resource"], c3["resource"]],
+                },
+            },
+        },
+    }), session=session)
+    assert tl_receipt.status == "applied", tl_receipt
+    local.release(session)
+
+    runner = CliRunner()
+
+    # 1. Inspect shot + contact sheet exclusive creation (deterministic media double when ffmpeg is absent)
+    fake_mp4 = tmp_path / "shot1.mp4"
+    fake_mp4.write_bytes(b"mp4-fixture-bytes")
+
+    sheet_path = tmp_path / "qc" / "shot1-sheet.jpg"
+    inspect_res = runner.invoke(cli.app, [
+        "video", "inspect-shot", str(fake_mp4), "--contact-sheet", str(sheet_path), "--columns", "4", "--rows", "3",
+    ])
+    assert inspect_res.exit_code == 0, inspect_res.output
+    inspected = json.loads(inspect_res.output)
+    assert inspected["technical"]["matchesH3Grid"] is True
+    assert inspected["technical"]["hasAudio"] is True
+    assert inspected["contactSheet"]["tileCount"] == 12
+    assert sheet_path.is_file() and sheet_path.stat().st_size > 1000
+
+    # Exclusive creation refuses to overwrite an existing contact sheet
+    dup_res = runner.invoke(cli.app, [
+        "video", "inspect-shot", str(fake_mp4), "--contact-sheet", str(sheet_path),
+    ])
+    assert dup_res.exit_code == 1
+
+    # 2. Lint shot plan via CLI
+    plan_file = tmp_path / "plan.json"
+    plan_file.write_text(json.dumps({
+        "shots": [
+            {"durationSeconds": 5, "shotSize": "wide shot", "cameraMotion": "Push In", "mode": "i2va"},
+            {"durationSeconds": 6, "shotSize": "close-up", "cameraMotion": "Static Shot", "mode": "fl2va"},
+        ]
+    }), encoding="utf-8")
+    plan_res = runner.invoke(cli.app, ["video", "lint-shot-plan", "--file", str(plan_file)])
+    assert plan_res.exit_code == 0, plan_res.output
+    assert json.loads(plan_res.output)["valid"] is True
+
+    # 3. Compile FL2VA prompt, create FL2VA node via CLI, and lint live spec
+    spec_file = tmp_path / "fl2va-spec.json"
+    spec_file.write_text(json.dumps({
+        "mode": "fl2va",
+        "durationSeconds": 6.0,
+        "shots": [{
+            "shotSize": "medium shot",
+            "description": "The courier starts in the pose of Picture 1, turns under the awning, and settles into Picture 2",
+            "cameraMotion": "Pull Out",
+            "cameraAmplitude": "small",
+            "cameraSpeed": "slow",
+        }],
+        "overallSoundscape": "Steady street rain and footsteps on wet stone.",
+        "nonDiegeticMusic": "N/A",
+    }), encoding="utf-8")
+    compile_res = runner.invoke(cli.app, ["video", "compile-h3-prompt", "--file", str(spec_file)])
+    assert compile_res.exit_code == 0, compile_res.output
+    compiled_prompt = json.loads(compile_res.output)["prompt"]
+
+    create_fl2va = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "create",
+        "--model", model_id,
+        "--prompt", compiled_prompt,
+        "--duration", "6",
+        "--x", "400", "--y", "320",
+        "--first-frame", str(start_item),
+        "--last-frame", str(end_item),
+        "--title", "FL2VA Bridge Shot",
+    ])
+    assert create_fl2va.exit_code == 0, create_fl2va.output
+    fl2va_receipt = json.loads(create_fl2va.output)
+    lint_live = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "lint-h3-prompt", "--spec-id", fl2va_receipt["specId"],
+    ])
+    assert lint_live.exit_code == 0, lint_live.output
+    lint_payload = json.loads(lint_live.output)
+    assert lint_payload["lint"]["mode"] == "fl2va"
+    assert lint_payload["lint"]["valid"] is True
+    assert [r["tag"] for r in lint_payload["referenceOrdinals"]] == ["<Picture 1>", "<Picture 2>"]
+
+    # 4. Continuation mode creation via --continue-from
+    create_cont = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "create",
+        "--model", model_id,
+        "--prompt", "Continue camera movement down the corridor.",
+        "--duration", "5",
+        "--x", "800", "--y", "320",
+        "--continue-from", str(seed_video_item),
+    ])
+    assert create_cont.exit_code == 0, create_cont.output
+    cont_spec_id = json.loads(create_cont.output)["specId"]
+    persisted_cont = next(s for s in projects.snapshot(project_id).generationSpecs if str(s.id) == cont_spec_id)
+    assert persisted_cont.parameters.videoMode == "continuation"
+
+    # 5. Surgical single-shot timeline revision (replaces shot-2 ONLY, preserves shot-1, shot-3, and connections)
+    revise_res = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "revise-shot",
+        "--timeline-editor", str(timeline_id),
+        "--clip-id", "shot-2",
+        "--asset", str(img_s2_new.id),
+        "--source-item", str(s2_new_item),
+    ])
+    assert revise_res.exit_code == 0, revise_res.output
+    revised_body = json.loads(revise_res.output)
+    assert revised_body["status"] == "applied"
+    assert revised_body["previousAssetId"] == str(img_s2_old.id)
+    assert revised_body["newAssetId"] == str(img_s2_new.id)
+    assert revised_body["outPoint"] == 4.5
+
+    after_tl = next(d for d in projects.snapshot(project_id).editorDocuments if d.id == timeline_id)
+    assert after_tl.revision == 2
+    visual_clips = after_tl.data.tracks[0].clips
+    assert [c.id for c in visual_clips] == ["shot-1", "shot-2", "shot-3"]
+    assert visual_clips[0].resource.asset.assetId == img_s1.id
+    assert visual_clips[1].resource.asset.assetId == img_s2_new.id
+    assert visual_clips[2].resource.asset.assetId == img_s3.id
+    conn_by_slot = {c.slotId: c for c in after_tl.inputConnections}
+    assert conn_by_slot["shot-1"].sourceId == s1_item
+    assert conn_by_slot["shot-2"].sourceId == s2_new_item
+
+    # 6. Project-native asset.preview contact_sheet + measuredFacts via CLI & HTTP
+    asset_sheet_path = tmp_path / "qc" / "asset-seed-sheet.jpg"
+    inspect_asset_res = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "inspect-shot",
+        "--asset", str(seed_video.id),
+        "--contact-sheet", str(asset_sheet_path),
+        "--columns", "3", "--rows", "2",
+    ])
+    assert inspect_asset_res.exit_code == 0, inspect_asset_res.output
+    asset_qc = json.loads(inspect_asset_res.output)
+    assert asset_qc["preview"]["scope"] == "contact_sheet"
+    assert asset_qc["preview"]["columns"] == 3
+    assert asset_qc["preview"]["rows"] == 2
+    assert asset_qc["measuredFacts"]["source"] == "measured"
+    assert asset_qc["measuredFacts"]["motion"]["sampledFrames"] == 6
+    assert asset_qc["measuredFacts"]["motion"]["suspectedFrozen"] is False
+    assert asset_qc["measuredFacts"]["motion"]["meanFrameDelta"] > 0
+    assert asset_qc["measuredFacts"]["exposure"]["blackFrameIndices"] == []
+    assert asset_sheet_path.is_file() and asset_sheet_path.stat().st_size > 800
+
+    # Frozen + black-frame detection in measuredFacts
+    monkeypatch.setattr(
+        media,
+        "frame_at",
+        lambda path, seconds, out: _png_bytes((0, 0, 0), (320, 240)),
+    )
+    frozen_qc = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "inspect-shot",
+        "--asset", str(seed_video.id),
+        "--columns", "2", "--rows", "2",
+    ])
+    assert frozen_qc.exit_code == 0, frozen_qc.output
+    frozen_facts = json.loads(frozen_qc.output)["measuredFacts"]
+    assert frozen_facts["motion"]["suspectedFrozen"] is True
+    assert frozen_facts["exposure"]["blackFrameIndices"] == [0, 1, 2, 3]
+    assert frozen_facts["exposure"]["blackFrameRatio"] == 1.0
+
+    # 7. Live project storyboard.audit catches unanchored T2VA island, unrendered upstream keyframe, and unlinked timeline clip
+    img_model_id = models.save(
+        "image", "http://127.0.0.1:19999/v1", "Flux-Dev", "",
+        connection_type="self_hosted", protocol="openai", auth_mode="none",
+    )["id"]
+    blank_kf_spec, blank_kf_item = uuid4(), uuid4()
+    projects.open(project_id, session)
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(blank_kf_spec),
+                "projectId": str(project_id),
+                "kind": "image",
+                "purpose": "generation",
+                "modelConfigId": img_model_id,
+                "prompt": "Unrendered keyframe",
+                "parameters": {},
+            },
+            "item": {
+                "id": str(blank_kf_item),
+                "projectId": str(project_id),
+                "kind": "image",
+                "position": {"x": 0, "y": 640},
+                "binding": {"role": "generation", "objectRef": {"id": str(blank_kf_spec)}},
+            },
+            "references": [],
+        },
+    }), session=session)
+    local.release(session)
+
+    # Create a bare T2VA shot (unanchored island) and a blocked I2VA shot pointing at unrendered keyframe
+    bare_t2va = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "create",
+        "--model", model_id,
+        "--prompt", "A wide shot of a courier running in rain, Push In with a medium amplitude at a fast pace.\n\nOverall Soundscape: Rain.\n\nNon-Diegetic Music: N/A",
+        "--duration", "5",
+        "--x", "1200", "--y", "320",
+    ])
+    assert bare_t2va.exit_code == 0, bare_t2va.output
+    bare_spec_id = json.loads(bare_t2va.output)["specId"]
+
+    audit_canvas = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "audit-storyboard",
+        "--spec-id", fl2va_receipt["specId"],
+        "--spec-id", bare_spec_id,
+    ])
+    assert audit_canvas.exit_code == 0, audit_canvas.output
+    audit_report = json.loads(audit_canvas.output)
+    assert audit_report["gate"]["shotCount"] == 2
+    assert any("bare T2VA" in w for w in audit_report["continuity"]["warnings"])
+
+    audit_tl = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "audit-storyboard",
+        "--timeline-editor", str(timeline_id),
+    ])
+    assert audit_tl.exit_code == 0, audit_tl.output
+    tl_audit = json.loads(audit_tl.output)
+    assert "shot-3" in tl_audit["continuity"]["unlinkedTimelineClipIds"]
+
+    # 8. Lineage-aware revise-shot using ONLY --source-item (auto-resolves clipId 'shot-1' and asset from s1_item)
+    projects.open(project_id, session)
+    s1_latest = next(i for i in projects.snapshot(project_id).canvasItems if i.id == s1_item)
+    mat_receipt = projects.execute(parse_command({
+        "type": "canvas.materialize",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "expectedVersions": [{"objectType": "canvas_item", "id": str(s1_item), "revision": s1_latest.revision}],
+        "payload": {
+            "itemId": str(s1_item),
+            "asset": {
+                "assetId": str(img_end.id),
+                "revision": img_end.revision,
+                "fingerprint": img_end.fingerprint,
+                "kind": img_end.kind,
+            },
+        },
+    }), session=session)
+    assert mat_receipt.status == "applied", mat_receipt
+    local.release(session)
+
+    auto_revise = runner.invoke(cli.app, [
+        "--project", str(project_id), "video", "revise-shot",
+        "--timeline-editor", str(timeline_id),
+        "--source-item", str(s1_item),
+    ])
+    assert auto_revise.exit_code == 0, auto_revise.output
+    auto_body = json.loads(auto_revise.output)
+    assert auto_body["clipId"] == "shot-1"
+    assert auto_body["previousAssetId"] == str(img_s1.id)
+    assert auto_body["newAssetId"] == str(img_end.id)
+    final_clips = next(d for d in projects.snapshot(project_id).editorDocuments if d.id == timeline_id).data.tracks[0].clips
+    assert final_clips[0].resource.asset.assetId == img_end.id
+    assert final_clips[1].resource.asset.assetId == img_s2_new.id
+    assert final_clips[2].resource.asset.assetId == img_s3.id
+
+
+@pytest.mark.skipif(not shutil.which("ffmpeg") or not shutil.which("ffprobe"), reason="Requires local ffmpeg/ffprobe")
+def test_real_ffmpeg_shot_inspection(tmp_path):
+    from opendirector.media.shot_inspection import inspect_video_shot
+
+    sample = tmp_path / "real.mp4"
+    subprocess.run([
+        "ffmpeg", "-v", "error", "-y",
+        "-f", "lavfi", "-i", "testsrc=size=320x240:rate=24:duration=5.2",
+        "-f", "lavfi", "-i", "sine=frequency=440:duration=5.2",
+        "-frames:v", "124", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", "-shortest",
+        str(sample),
+    ], check=True, timeout=30)
+    sheet = tmp_path / "sheet.jpg"
+    report = inspect_video_shot(sample, contact_sheet_path=sheet, columns=4, rows=3)
+    assert report["technical"]["matchesH3Grid"] is True
+    assert report["technical"]["hasAudio"] is True
+    assert sheet.is_file()
+
+
+@pytest.mark.anyio
+async def test_h3_shot_director_skill_snapshot_and_gateway_read(tmp_path):
+    skill_dir = builtin_skills() / "h3-shot-director"
+    entry = skill_dir / "SKILL.md"
+    assert entry.is_file()
+    for name in ("SKILL.md", "h3-vocabulary.md", "shot-orchestration.md"):
+        target = skill_dir / name
+        assert target.is_file() and not target.is_symlink()
+        assert target.stat().st_size <= 65536
+
+    work = tmp_path / "agent-work"
+    roots = prepare_skills(work, [{"name": "h3-shot-director", "filePath": str(entry)}])
+    assert len(roots) == 1
+    assert (roots[0] / "h3-vocabulary.md").is_file()
+    assert (roots[0] / "shot-orchestration.md").is_file()
+
+    projects = CreationProjects(LocalProjects(tmp_path))
+    business = AgentTools(projects, None, ModelConfigs(tmp_path))
+    run = RunContext(
+        runtime="codex", project_id=uuid4(), turn_id=uuid4(), session=str(uuid4()),
+        directory=work, config=None, messages=[], selected_skills=["h3-shot-director"],
+    )
+    gateway = ToolGateway(business, run)
+    gateway.roots = roots
+    try:
+        for name in ("SKILL.md", "h3-vocabulary.md", "shot-orchestration.md"):
+            outcome = await gateway.call(f"read-{name}", "read", {"path": str(roots[0] / name)})
+            assert outcome.error is None
+            assert "MiniMax-H3" in outcome.value or "lint-shot-plan" in outcome.value
+    finally:
+        await gateway.close()
+
+
+@pytest.mark.anyio
+async def test_tool_gateway_storyboard_audit_and_video_contact_sheet_preview(tmp_path, monkeypatch):
+    ffprobe_payload = json.dumps({
+        "format": {
+            "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
+            "duration": "5.1667",
+            "size": "12345",
+            "tags": {"major_brand": "isom"},
+        },
+        "streams": [
+            {
+                "codec_type": "video",
+                "codec_name": "h264",
+                "width": 640,
+                "height": 360,
+                "r_frame_rate": "24/1",
+                "avg_frame_rate": "24/1",
+                "nb_frames": "124",
+            },
+            {"codec_type": "audio", "codec_name": "aac"},
+        ],
+    }).encode("utf-8")
+    monkeypatch.setattr(media_probe, "require_ffprobe", lambda: None)
+    monkeypatch.setattr(
+        media_probe.subprocess,
+        "run",
+        lambda cmd, **kw: subprocess.CompletedProcess(cmd, 0, stdout=ffprobe_payload, stderr=b""),
+    )
+    monkeypatch.setattr(media, "_run", lambda cmd, timeout=60: ffprobe_payload)
+    monkeypatch.setattr(
+        media,
+        "frame_at",
+        lambda path, seconds, out: _png_bytes((20 + int(seconds * 25) % 200, 80, 140), (640, 360)),
+    )
+
+    local = LocalProjects(tmp_path)
+    projects = CreationProjects(local)
+    configs = ModelConfigs(tmp_path)
+    model_id = configs.save(
+        "video", "http://127.0.0.1:19999/v1", "MiniMax-H3", "",
+        connection_type="self_hosted", protocol="vllm_omni", auth_mode="none",
+    )["id"]
+    img_model_id = configs.save(
+        "image", "http://127.0.0.1:19999/v1", "Flux-Dev", "",
+        connection_type="self_hosted", protocol="openai", auth_mode="none",
+    )["id"]
+
+    project_id = uuid4()
+    session = str(uuid4())
+    projects.execute(parse_command({
+        "type": "project.create",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {"name": "Gateway Quality"},
+    }))
+    projects.open(project_id, session)
+    vid_asset = _stage_and_import(projects, project_id, session, "clip.mp4", "video", b"mp4-bytes")
+
+    # Create an unrendered image generation node and wire a video generation spec to it via pinned/draft check
+    kf_spec_id, kf_item_id = uuid4(), uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(kf_spec_id),
+                "projectId": str(project_id),
+                "kind": "image",
+                "purpose": "generation",
+                "modelConfigId": img_model_id,
+                "prompt": "Anchor keyframe",
+                "parameters": {},
+            },
+            "item": {
+                "id": str(kf_item_id),
+                "projectId": str(project_id),
+                "kind": "image",
+                "position": {"x": 0, "y": 0},
+                "binding": {"role": "generation", "objectRef": {"id": str(kf_spec_id)}},
+            },
+            "references": [],
+        },
+    }), session=session)
+
+    vid_spec_id, vid_item_id = uuid4(), uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(vid_spec_id),
+                "projectId": str(project_id),
+                "kind": "video",
+                "purpose": "generation",
+                "modelConfigId": model_id,
+                "prompt": "A wide shot of a courier running, Push In slowly.\n\nOverall Soundscape: Rain.\n\nNon-Diegetic Music: N/A",
+                "parameters": {"videoMode": "first_frame", "durationSeconds": 6},
+            },
+            "item": {
+                "id": str(vid_item_id),
+                "projectId": str(project_id),
+                "kind": "video",
+                "position": {"x": 320, "y": 0},
+                "binding": {"role": "generation", "objectRef": {"id": str(vid_spec_id)}},
+            },
+            "references": [],
+        },
+    }), session=session)
+    local.release(session)
+
+    work = tmp_path / "turn-work"
+    work.mkdir(parents=True, exist_ok=True)
+    business = AgentTools(projects, None, configs)
+    run = RunContext(
+        runtime="codex", project_id=project_id, turn_id=uuid4(), session=session,
+        directory=work, config=None, messages=[], selected_skills=[],
+    )
+    gateway = ToolGateway(business, run)
+    gateway.execution_directory = work
+    try:
+        preview_call = await gateway.call(
+            "preview-sheet",
+            "query",
+            {"type": "asset.preview", "objectId": str(vid_asset.id), "videoScope": "contact_sheet", "columns": 3, "rows": 2},
+        )
+        assert preview_call.error is None, preview_call
+        sheet_file = Path(preview_call.value["preview"]["path"])
+        assert sheet_file.is_file() and sheet_file.is_relative_to(work / "previews")
+        assert "-sheet-3x2.jpg" in sheet_file.name
+        assert preview_call.value["measuredFacts"]["motion"]["sampledFrames"] == 6
+
+        audit_call = await gateway.call("audit-board", "query", {"type": "storyboard.audit"})
+        assert audit_call.error is None, audit_call
+        assert audit_call.value["gate"]["shotCount"] == 1
+        assert audit_call.value["gate"]["estimatedPendingVideoSeconds"] == 6.0
+        assert audit_call.value["gate"]["requiresUserApproval"] is True
+    finally:
+        await gateway.close()

From f9993a1fb9db103ab028103859d26bdf93f4935d Mon Sep 17 00:00:00 2001
From: BeatSeat <137616995+BeatSeat@users.noreply.github.com>
Date: Sun, 15 Nov 2026 19:58:10 +0800
Subject: [PATCH 2/2] [bugfix] agent: harden H3 lint checks, reference
 ordinals, and audit contracts

## summary

- Detect contradictory single-shot camera motions and CLI/SD pseudo-parameter
  tags outside `<d>...</d>` dialogue in `lint_h3_prompt`, extract compiled H3
  camera motion verb phrases in `extract_prompt_shot_features`, and publish
  `vllmOmniFrames` alongside `gridFrames` in `h3_frame_grid`.
- Unify H3 reference-source resolution across `storyboard.audit` and
  `opendirector video lint-h3-prompt` in `resolve_h3_spec_reference_sources`,
  preserving `promptContent` mention order, `first_frame` `context_only`
  filtering, and `assetId` deduplication.
- Respect group-inherited canvas visibility in `audit_project_storyboard`,
  enforce mutually exclusive scopes and unique `specIds` in
  `StoryboardAuditQuery`, and regenerate TypeScript and JSON contracts.
- Reuse `TIMELINE_DURATION_EPSILON`, preserve existing `EditorInputConnection`
  IDs on repeated slot revisions, standardize domain error messages, and gate
  real FFmpeg inspection with `@requires_ffmpeg()`.

## validation

- `.venv/bin/python3 scripts/generate_contracts.py --check`
- `PYTHONPATH=packages/core/src:apps/api/src .venv/bin/lint-imports`
- `PYTHONPATH=packages/core/src:apps/api/src .venv/bin/python3 -m pytest tests/test_h3_shot_orchestration.py tests/test_creation_contracts.py tests/test_skill_snapshot.py tests/test_agent_metadata.py tests/test_agent_gateway.py tests/test_cli.py -q`
- `npm run check:i18n`

Refs: #338
---
 .../application/creation_storyboard.py        | 289 ++++++++++-------
 packages/core/src/opendirector/cli.py         |  90 +-----
 .../opendirector/domain/creation/commands.py  |  11 +-
 .../opendirector/domain/h3_cinematography.py  | 113 ++++++-
 .../src/opendirector/media/shot_inspection.py |   8 +-
 src/contracts/creation.schema.json            |   2 +
 tests/test_h3_shot_orchestration.py           | 300 +++++++++++++++++-
 7 files changed, 612 insertions(+), 201 deletions(-)

diff --git a/packages/core/src/opendirector/application/creation_storyboard.py b/packages/core/src/opendirector/application/creation_storyboard.py
index 2b5f03e17..056d232d0 100644
--- a/packages/core/src/opendirector/application/creation_storyboard.py
+++ b/packages/core/src/opendirector/application/creation_storyboard.py
@@ -5,38 +5,36 @@
 import re
 from uuid import UUID, uuid4, uuid5
 
-from opendirector.application.creation_canvas import current_asset
+from opendirector.application.creation_canvas import current_asset, visible_item_ids
 from opendirector.domain.creation.editors import SubjectDocument, TimelineDocument
 from opendirector.domain.creation.generation import FollowingReference
 from opendirector.domain.creation.project import ProjectSnapshot
 from opendirector.domain.creation.validation import ContractError
 from opendirector.domain.h3_cinematography import (
-    CAMERA_MOTIONS,
     SHOT_SIZES,
+    detect_camera_motions,
     h3_reference_ordinals,
     lint_h3_prompt,
     lint_shot_plan,
+    strip_dialogue_blocks,
 )
 from opendirector.domain.projects import ProjectError
+from opendirector.domain.rule_facts import TIMELINE_DURATION_EPSILON
 
 
 _SORTED_SHOT_SIZES = tuple(sorted(SHOT_SIZES, key=len, reverse=True))
-_SORTED_CAMERA_MOTIONS = tuple(sorted(CAMERA_MOTIONS, key=len, reverse=True))
 
 
 def extract_prompt_shot_features(prompt: str) -> dict[str, str | None]:
     """Extract primary canonical H3 shot size and camera motion from prompt text."""
-    text = prompt or ""
+    scrubbed = strip_dialogue_blocks(prompt or "")
     found_size = None
     for candidate in _SORTED_SHOT_SIZES:
-        if re.search(rf"(?<![A-Za-z]){re.escape(candidate)}(?![A-Za-z])", text, flags=re.IGNORECASE):
+        if re.search(rf"(?<![A-Za-z]){re.escape(candidate)}(?![A-Za-z])", scrubbed, flags=re.IGNORECASE):
             found_size = candidate
             break
-    found_motion = None
-    for candidate in _SORTED_CAMERA_MOTIONS:
-        if re.search(rf"(?<![A-Za-z]){re.escape(candidate)}(?![A-Za-z])", text, flags=re.IGNORECASE):
-            found_motion = candidate
-            break
+    motions = detect_camera_motions(scrubbed)
+    found_motion = motions[0] if motions else None
     return {"shotSize": found_size, "cameraMotion": found_motion}
 
 
@@ -78,6 +76,142 @@ def _continuation_depth(snapshot: ProjectSnapshot, spec_id: UUID) -> int:
     return depth
 
 
+def _is_visible_descendant_of_group(item, group_id: UUID, items_by_id: dict[UUID, object]) -> bool:
+    if not item.visible:
+        return False
+    seen: set[UUID] = set()
+    parent_id = getattr(item, "parentId", None)
+    while parent_id is not None and parent_id not in seen:
+        if parent_id == group_id:
+            return True
+        seen.add(parent_id)
+        parent = items_by_id.get(parent_id)
+        if parent is None or not parent.visible:
+            return False
+        parent_id = getattr(parent, "parentId", None)
+    return False
+
+
+def resolve_h3_spec_reference_sources(snapshot: ProjectSnapshot | dict, spec_id: UUID) -> dict:
+    """Resolve transmitted H3 reference sources for a video spec using shared ordering and policy."""
+    snap = ProjectSnapshot.model_validate(snapshot) if isinstance(snapshot, dict) else snapshot
+    spec = next((s for s in snap.generationSpecs if s.id == spec_id), None)
+    if spec is None or spec.kind != "video":
+        raise ContractError("missing_object", "未找到指定的视频生成配置。", spec_id)
+
+    assets_by_id = {asset.id: asset for asset in snap.assets}
+    items_by_id = {item.id: item for item in snap.canvasItems}
+    docs_by_id = {doc.id: doc for doc in snap.editorDocuments}
+
+    mentioned = list(dict.fromkeys(
+        part.referenceId for part in (spec.promptContent or ()) if part.type == "reference"
+    ))
+    active_refs = sorted(
+        (ref for ref in snap.references if ref.active and ref.targetSpecId == spec.id),
+        key=lambda ref: (
+            mentioned.index(ref.id) if ref.id in mentioned else len(mentioned),
+            ref.order,
+            str(ref.id),
+        ),
+    )
+
+    roles: list[str] = []
+    subject_item_ids: list[str] = []
+    missing_upstream: list[dict] = []
+    frame_fingerprints: dict[str, str] = {}
+    raw_candidates: list[tuple[object, str, str | None]] = []
+
+    for ref in active_refs:
+        roles.append(ref.role)
+        if ref.binding == "pinned":
+            asset_obj = assets_by_id.get(ref.source.assetId)
+            if asset_obj is None:
+                missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_asset"})
+            else:
+                raw_candidates.append((asset_obj, ref.role, ref.subjectRole))
+                if ref.role in {"first_frame", "last_frame"} and ref.subjectRole is None and asset_obj.kind == "image":
+                    frame_fingerprints[ref.role] = asset_obj.fingerprint
+        else:
+            src_item = items_by_id.get(ref.source.id)
+            if src_item is None:
+                missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_item"})
+                continue
+            if src_item.kind == "subject":
+                subject_item_ids.append(str(src_item.id))
+                sub_doc = docs_by_id.get(src_item.binding.objectRef.id)
+                if not isinstance(sub_doc, SubjectDocument) or sub_doc.data.main is None:
+                    missing_upstream.append({
+                        "referenceId": str(ref.id),
+                        "sourceItemId": str(src_item.id),
+                        "role": ref.role,
+                        "reason": "empty_subject",
+                    })
+                    continue
+                slot_pairs = [
+                    (sub_doc.data.main, "main"),
+                    *((aux, "auxiliary") for aux in sub_doc.data.auxiliaries),
+                    *([(sub_doc.data.voice, "voice")] if sub_doc.data.voice else []),
+                ]
+                for slot_ref, slot_role in slot_pairs:
+                    asset_obj = assets_by_id.get(slot_ref.assetId)
+                    if asset_obj is not None:
+                        raw_candidates.append((asset_obj, ref.role, slot_role))
+            else:
+                asset_obj = current_asset(snap, src_item)
+                if asset_obj is None:
+                    missing_upstream.append({
+                        "referenceId": str(ref.id),
+                        "sourceItemId": str(src_item.id),
+                        "role": ref.role,
+                        "reason": "unrendered_upstream_node",
+                    })
+                else:
+                    raw_candidates.append((asset_obj, ref.role, None))
+                    if ref.role in {"first_frame", "last_frame"} and asset_obj.kind == "image":
+                        frame_fingerprints[ref.role] = asset_obj.fingerprint
+
+    video_mode = getattr(spec.parameters, "videoMode", None)
+    selected_frame = any(role in {"first_frame", "last_frame"} for role in roles)
+    ref_sources: list[dict] = []
+    seen_asset_ids: set[str] = set()
+
+    for asset_obj, role, subject_role in raw_candidates:
+        if asset_obj.kind not in {"image", "video", "audio"}:
+            continue
+        if video_mode == "first_frame":
+            ignored = (
+                asset_obj.kind != "image"
+                or subject_role is not None
+                or not selected_frame
+                or role not in {"first_frame", "last_frame"}
+            )
+            if ignored:
+                continue
+        if video_mode == "continuation" and subject_role is not None and asset_obj.kind == "video":
+            continue
+        asset_id_str = str(asset_obj.id)
+        if asset_id_str in seen_asset_ids:
+            continue
+        seen_asset_ids.add(asset_id_str)
+        ref_sources.append({
+            "id": asset_id_str,
+            "name": asset_obj.name,
+            "kind": asset_obj.kind,
+            "role": role,
+            "hasAudio": bool(asset_obj.metadata.hasAudio),
+        })
+
+    return {
+        "spec": spec,
+        "h3Mode": _infer_h3_mode(video_mode, roles),
+        "roles": roles,
+        "referenceSources": ref_sources,
+        "subjectItemIds": subject_item_ids,
+        "missingUpstream": missing_upstream,
+        "frameFingerprints": frame_fingerprints,
+    }
+
+
 def audit_project_storyboard(
     snapshot: ProjectSnapshot,
     *,
@@ -144,12 +278,15 @@ def audit_project_storyboard(
                 raise ContractError("missing_object", "未找到指定的画布分组节点。", group_id)
             candidate_items = [
                 item for item in snapshot.canvasItems
-                if item.parentId == group_id and item.kind == "video" and item.binding.role == "generation"
+                if _is_visible_descendant_of_group(item, group_id, items_by_id)
+                and item.kind == "video"
+                and item.binding.role == "generation"
             ]
         else:
+            visible = visible_item_ids(snapshot)
             candidate_items = [
                 item for item in snapshot.canvasItems
-                if item.visible and item.kind == "video" and item.binding.role == "generation"
+                if item.id in visible and item.kind == "video" and item.binding.role == "generation"
             ]
         candidate_items.sort(key=lambda item: (item.position.y, item.position.x, str(item.id)))
         for item in candidate_items:
@@ -164,86 +301,17 @@ def audit_project_storyboard(
 
     for index, spec in enumerate(ordered_specs, start=1):
         canvas_item = item_by_spec.get(spec.id)
-        active_refs = sorted(
-            (ref for ref in snapshot.references if ref.active and ref.targetSpecId == spec.id),
-            key=lambda ref: (ref.order, str(ref.id)),
-        )
-        roles: list[str] = []
-        ref_sources: list[dict] = []
-        subject_item_ids: list[str] = []
-        missing_upstream: list[dict] = []
-        frame_fingerprints: dict[str, str] = {}
-
-        for ref in active_refs:
-            roles.append(ref.role)
-            if ref.binding == "pinned":
-                asset_obj = assets_by_id.get(ref.source.assetId)
-                if asset_obj is None:
-                    missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_asset"})
-                elif asset_obj.kind in {"image", "video", "audio"}:
-                    ref_sources.append({
-                        "id": str(asset_obj.id),
-                        "name": asset_obj.name,
-                        "kind": asset_obj.kind,
-                        "role": ref.role,
-                        "hasAudio": bool(asset_obj.metadata.hasAudio),
-                    })
-                    if ref.role in {"first_frame", "last_frame"}:
-                        frame_fingerprints[ref.role] = asset_obj.fingerprint
-            else:
-                src_item = items_by_id.get(ref.source.id)
-                if src_item is None:
-                    missing_upstream.append({"referenceId": str(ref.id), "role": ref.role, "reason": "missing_item"})
-                    continue
-                if src_item.kind == "subject":
-                    subject_item_ids.append(str(src_item.id))
-                    sub_doc = docs_by_id.get(src_item.binding.objectRef.id)
-                    if not isinstance(sub_doc, SubjectDocument) or sub_doc.data.main is None:
-                        missing_upstream.append({
-                            "referenceId": str(ref.id),
-                            "sourceItemId": str(src_item.id),
-                            "role": ref.role,
-                            "reason": "empty_subject",
-                        })
-                        continue
-                    slot_refs = [r for r in (sub_doc.data.main, *sub_doc.data.auxiliaries, sub_doc.data.voice) if r]
-                    for slot in slot_refs:
-                        asset_obj = assets_by_id.get(slot.assetId)
-                        if asset_obj and asset_obj.kind in {"image", "video", "audio"}:
-                            ref_sources.append({
-                                "id": str(asset_obj.id),
-                                "name": asset_obj.name,
-                                "kind": asset_obj.kind,
-                                "role": ref.role,
-                                "hasAudio": bool(asset_obj.metadata.hasAudio),
-                            })
-                else:
-                    asset_obj = current_asset(snapshot, src_item)
-                    if asset_obj is None:
-                        missing_upstream.append({
-                            "referenceId": str(ref.id),
-                            "sourceItemId": str(src_item.id),
-                            "role": ref.role,
-                            "reason": "unrendered_upstream_node",
-                        })
-                    elif asset_obj.kind in {"image", "video", "audio"}:
-                        ref_sources.append({
-                            "id": str(asset_obj.id),
-                            "name": asset_obj.name,
-                            "kind": asset_obj.kind,
-                            "role": ref.role,
-                            "hasAudio": bool(asset_obj.metadata.hasAudio),
-                        })
-                        if ref.role in {"first_frame", "last_frame"}:
-                            frame_fingerprints[ref.role] = asset_obj.fingerprint
+        resolved = resolve_h3_spec_reference_sources(snapshot, spec.id)
+        ref_sources = resolved["referenceSources"]
+        subject_item_ids = resolved["subjectItemIds"]
+        missing_upstream = resolved["missingUpstream"]
+        frame_fingerprints = resolved["frameFingerprints"]
+        h3_mode = resolved["h3Mode"]
 
         if subject_item_ids or ref_sources:
             anchored_count += 1
 
-        video_mode = getattr(spec.parameters, "videoMode", None)
         duration = float(getattr(spec.parameters, "durationSeconds", None) or 5.0)
-        generate_audio = bool(getattr(spec.parameters, "generateAudio", True))
-        h3_mode = _infer_h3_mode(video_mode, roles)
         continuity_issues: list[str] = []
         continuity_warnings: list[str] = []
 
@@ -418,40 +486,36 @@ def prepare_timeline_shot_revision(
         None,
     )
     if doc is None:
-        raise ProjectError(f"Timeline editor document {timeline_editor_id} is not in this project.")
+        raise ProjectError("未找到指定的时间线文档。", 404)
 
     if source_item_id is not None and not any(
         item["id"] == str(source_item_id) for item in snapshot.get("canvasItems", ())
     ):
-        raise ProjectError(f"Source canvas item {source_item_id} is not in this project.")
+        raise ProjectError("未找到指定的来源画布节点。", 404)
 
     resolved_clip_id = clip_id
     if resolved_clip_id is None:
         if source_item_id is None:
-            raise ProjectError("Provide --clip-id or --source-item linked in timeline inputConnections.")
+            raise ProjectError("请提供 --clip-id，或提供已关联到时间线槽位的 --source-item。", 422)
         matched = next(
             (c["slotId"] for c in (doc.get("inputConnections") or ()) if c["sourceId"] == str(source_item_id)),
             None,
         )
         if matched is None:
-            raise ProjectError(
-                f"Source canvas item {source_item_id} is not linked to any slot in timeline {timeline_editor_id}."
-            )
+            raise ProjectError("来源画布节点尚未关联到当前时间线的任何槽位。", 422)
         resolved_clip_id = matched
 
     resolved_asset_id = str(asset_id) if asset_id is not None else None
     if resolved_asset_id is None:
         if source_item_id is None:
-            raise ProjectError("Provide --asset or a --source-item with an adopted/material asset.")
+            raise ProjectError("请提供 --asset，或提供已有采纳结果或素材的 --source-item。", 422)
         resolved_asset_id = _resolve_item_adopted_asset_id(snapshot, str(source_item_id))
         if resolved_asset_id is None:
-            raise ProjectError(
-                f"Source canvas item {source_item_id} has no adopted result or material asset to sync."
-            )
+            raise ProjectError("来源画布节点尚无已采纳结果或可用素材。", 422)
 
     asset_obj = next((a for a in snapshot.get("assets", ()) if a["id"] == resolved_asset_id), None)
     if asset_obj is None:
-        raise ProjectError(f"Asset {resolved_asset_id} is not registered in this project.")
+        raise ProjectError("替换素材未在当前项目中注册。", 404)
 
     updated_doc = json.loads(json.dumps(doc))
     target_track = None
@@ -464,13 +528,13 @@ def prepare_timeline_shot_revision(
         if target_clip is not None:
             break
     if target_clip is None or target_track is None:
-        raise ProjectError(f"Clip '{resolved_clip_id}' was not found in timeline {timeline_editor_id}.")
+        raise ProjectError(f"未在时间线中找到片段 '{resolved_clip_id}'。", 404)
 
     media_kind = asset_obj["kind"]
     if target_track["kind"] == "visual" and media_kind not in {"image", "video"}:
-        raise ProjectError("Visual timeline clips require an image or video asset.")
+        raise ProjectError("画面轨道片段只能使用图片或视频素材。", 422)
     if target_track["kind"] == "audio" and media_kind != "audio":
-        raise ProjectError("Audio timeline clips require an audio asset.")
+        raise ProjectError("音频轨道片段只能使用音频素材。", 422)
 
     old_asset_id = target_clip["resource"]["asset"]["assetId"]
     old_in = float(target_clip["inPoint"])
@@ -482,7 +546,7 @@ def prepare_timeline_shot_revision(
         new_out = float(out_point) if out_point is not None else (old_out - old_in)
     else:
         if asset_duration is None or float(asset_duration) <= 0:
-            raise ProjectError("Video and audio timeline replacements require a probed positive durationSeconds.")
+            raise ProjectError("替换时间线视频或音频需要已知的正数素材时长。", 422)
         total_dur = float(asset_duration)
         new_in = (
             float(in_point)
@@ -497,8 +561,8 @@ def prepare_timeline_shot_revision(
             new_out = min(total_dur, new_in + (old_out - old_in))
             if new_out <= new_in:
                 new_in, new_out = 0.0, total_dur
-        if new_out <= new_in or new_out > total_dur + 1e-6:
-            raise ProjectError(f"Invalid trim [{new_in}, {new_out}] for asset duration {total_dur}s.")
+        if new_out <= new_in or new_out > total_dur + TIMELINE_DURATION_EPSILON:
+            raise ProjectError(f"裁剪区间 [{new_in}, {new_out}] 超出素材时长 {total_dur} 秒。", 422)
 
     new_asset_ref = {
         "assetId": asset_obj["id"],
@@ -526,18 +590,21 @@ def prepare_timeline_shot_revision(
 
     operation = operation_id or uuid4()
     existing_conns = updated_doc.get("inputConnections") or []
-    effective_source_id = str(source_item_id) if source_item_id is not None else next(
-        (c["sourceId"] for c in existing_conns if c["slotId"] == resolved_clip_id),
-        None,
+    existing_for_slot = next((c for c in existing_conns if c["slotId"] == resolved_clip_id), None)
+    effective_source_id = str(source_item_id) if source_item_id is not None else (
+        existing_for_slot["sourceId"] if existing_for_slot is not None else None
     )
     connections = [c for c in existing_conns if c["slotId"] != resolved_clip_id]
     if effective_source_id is not None:
         if any(c["sourceId"] == effective_source_id for c in connections):
-            raise ProjectError(
-                f"Source canvas item {effective_source_id} is already connected to another timeline slot."
-            )
+            raise ProjectError("来源画布节点已连接到当前时间线的其他槽位。", 409)
+        conn_id = (
+            existing_for_slot["id"]
+            if existing_for_slot is not None and existing_for_slot.get("sourceId") == effective_source_id
+            else str(uuid5(operation, f"connection-{resolved_clip_id}"))
+        )
         connections.append({
-            "id": str(uuid5(operation, f"connection-{resolved_clip_id}")),
+            "id": conn_id,
             "sourceId": effective_source_id,
             "slotId": resolved_clip_id,
             "asset": new_asset_ref,
diff --git a/packages/core/src/opendirector/cli.py b/packages/core/src/opendirector/cli.py
index fb51de1ca..dd00418a7 100644
--- a/packages/core/src/opendirector/cli.py
+++ b/packages/core/src/opendirector/cli.py
@@ -514,62 +514,6 @@ def video_create(ctx: typer.Context,
                    "command": shlex.join(submit)}})
 
 
-def _resolve_spec_reference_sources(snapshot: dict, spec_id: str) -> tuple[list[dict], list[str]]:
-    assets_by_id = {asset["id"]: asset for asset in snapshot.get("assets", ())}
-    items_by_id = {item["id"]: item for item in snapshot.get("canvasItems", ())}
-    specs_by_id = {spec["id"]: spec for spec in snapshot.get("generationSpecs", ())}
-    results_by_id = {res["id"]: res for res in snapshot.get("results", ())}
-    docs_by_id = {doc["id"]: doc for doc in snapshot.get("editorDocuments", ())}
-
-    def item_assets(item: dict) -> list[dict]:
-        if item["kind"] == "subject":
-            doc = docs_by_id.get(item["binding"]["objectRef"]["id"])
-            if not doc:
-                return []
-            data = doc["data"]
-            refs = [r for r in (data.get("main"), *(data.get("auxiliaries") or ()), data.get("voice")) if r]
-            return [assets_by_id[r["assetId"]] for r in refs if r["assetId"] in assets_by_id]
-        binding = item["binding"]
-        if binding["role"] == "material":
-            found = assets_by_id.get(binding["objectRef"]["assetId"])
-            return [found] if found else []
-        if binding["role"] == "generation":
-            if binding.get("materialOverride"):
-                found = assets_by_id.get(binding["materialOverride"]["assetId"])
-                return [found] if found else []
-            src_spec = specs_by_id.get(binding["objectRef"]["id"])
-            if src_spec and src_spec.get("currentResultId"):
-                res = results_by_id.get(src_spec["currentResultId"])
-                if res and res["asset"]["assetId"] in assets_by_id:
-                    return [assets_by_id[res["asset"]["assetId"]]]
-        return []
-
-    active = sorted(
-        (ref for ref in snapshot.get("references", ()) if ref.get("active") and ref.get("targetSpecId") == spec_id),
-        key=lambda ref: (ref.get("order", 0), ref.get("id", "")),
-    )
-    sources: list[dict] = []
-    roles: list[str] = []
-    for ref in active:
-        roles.append(str(ref.get("role") or "reference"))
-        if ref.get("binding") == "pinned":
-            asset_obj = assets_by_id.get(ref["source"]["assetId"])
-            resolved = [asset_obj] if asset_obj else []
-        else:
-            src_item = items_by_id.get(ref["source"]["id"])
-            resolved = item_assets(src_item) if src_item else []
-        for asset_obj in resolved:
-            if asset_obj["kind"] in {"image", "video", "audio"}:
-                sources.append({
-                    "id": asset_obj["id"],
-                    "name": asset_obj["name"],
-                    "kind": asset_obj["kind"],
-                    "role": ref.get("role"),
-                    "hasAudio": bool(asset_obj.get("metadata", {}).get("hasAudio")),
-                })
-    return sources, roles
-
-
 @group("video").command("compile-h3-prompt", help="Compile structured shot/reference JSON into an official MiniMax-H3 prompt.")
 def video_compile_h3_prompt(
     file: Annotated[Path, typer.Option(help="JSON specification file; use - for stdin.")],
@@ -590,34 +534,26 @@ def video_lint_h3_prompt(
     mode: Annotated[str | None, typer.Option(help="H3 mode: t2va, i2va, fl2va, l2va, or ref2va. Inferred when --spec-id is given.")] = None,
     duration: Annotated[float | None, typer.Option(min=0, help="Target video duration in seconds.")] = None,
 ):
+    from opendirector.application.creation_storyboard import resolve_h3_spec_reference_sources
+    from opendirector.domain.creation.validation import ContractError
     from opendirector.domain.h3_cinematography import h3_reference_ordinals, lint_h3_prompt
     if bool(spec_id) == bool(file):
-        raise ProjectError("Provide exactly one of --spec-id or --file.")
+        raise ProjectError("请提供 --spec-id 或 --file 其中之一。", 422)
     reference_sources = None
     if spec_id is not None:
         client = ctx.obj
         client.command = ctx.command_path
         snapshot = client.snapshot()
-        spec = next((s for s in snapshot.get("generationSpecs", ()) if s["id"] == str(spec_id)), None)
-        if spec is None or spec.get("kind") != "video":
-            raise ProjectError(f"Video GenerationSpec {spec_id} is not in this project.")
-        prompt_text = str(spec.get("prompt") or "")
-        effective_duration = float(duration if duration is not None else (spec.get("parameters", {}).get("durationSeconds") or 5.0))
-        reference_sources, roles = _resolve_spec_reference_sources(snapshot, str(spec_id))
-        if mode is None:
-            vmode = spec.get("parameters", {}).get("videoMode")
-            if vmode == "reference":
-                effective_mode = "ref2va"
-            elif "first_frame" in roles and "last_frame" in roles:
-                effective_mode = "fl2va"
-            elif "first_frame" in roles:
-                effective_mode = "i2va"
-            elif "last_frame" in roles:
-                effective_mode = "l2va"
-            else:
-                effective_mode = "t2va"
-        else:
-            effective_mode = mode
+        try:
+            resolved = resolve_h3_spec_reference_sources(snapshot, spec_id)
+        except ContractError as exc:
+            raise ProjectError(exc.issue.message, 404) from None
+        spec = resolved["spec"]
+        prompt_text = str(spec.prompt or "")
+        effective_duration = float(duration if duration is not None else (spec.parameters.durationSeconds or 5.0))
+        h3_mode = resolved["h3Mode"]
+        reference_sources = resolved["referenceSources"] if h3_mode != "continuation" else None
+        effective_mode = mode if mode is not None else ("i2va" if h3_mode == "continuation" else h3_mode)
     else:
         prompt_text = sys.stdin.read() if str(file) == "-" else file.read_text(encoding="utf-8")
         effective_mode = mode or "t2va"
diff --git a/packages/core/src/opendirector/domain/creation/commands.py b/packages/core/src/opendirector/domain/creation/commands.py
index 402a2e47f..cd5826343 100644
--- a/packages/core/src/opendirector/domain/creation/commands.py
+++ b/packages/core/src/opendirector/domain/creation/commands.py
@@ -502,9 +502,18 @@ class StoryboardAuditQuery(QueryBase):
     timelineEditorId: UUID | None = Field(default=None, description='Optional timeline editor document ID to order and scope shots.')
     groupId: UUID | None = Field(default=None, description='Optional canvas group item ID to scope shots.')
     specIds: tuple[UUID, ...] | None = Field(
-        default=None, max_length=200, description='Optional explicit ordered video GenerationSpec IDs to audit.'
+        default=None, min_length=1, max_length=200, description='Optional explicit ordered video GenerationSpec IDs to audit.'
     )
 
+    @model_validator(mode='after')
+    def scope_and_unique_specs(self):
+        if self.specIds is not None:
+            unique(self.specIds, 'audited video configuration IDs')
+        scopes = sum(value is not None for value in (self.timelineEditorId, self.groupId, self.specIds))
+        if scopes > 1:
+            raise ValueError('Choose at most one storyboard audit scope: timelineEditorId, groupId, or specIds')
+        return self
+
 
 Query = Annotated[ProjectQuery | ObjectQuery | VersionsQuery | AssetSearchQuery | AssetUsageQuery |
                   CanvasStatusQuery | AssetPreviewQuery | StoryboardAuditQuery, Field(discriminator='type')]
diff --git a/packages/core/src/opendirector/domain/h3_cinematography.py b/packages/core/src/opendirector/domain/h3_cinematography.py
index c50a0c8ef..3be1ca95e 100644
--- a/packages/core/src/opendirector/domain/h3_cinematography.py
+++ b/packages/core/src/opendirector/domain/h3_cinematography.py
@@ -136,22 +136,90 @@
 _DIALOGUE_LANG_RE = re.compile(r"^\s*\[[^\[\]\n]+\]\s+\S", re.S)
 _TAG_RE = re.compile(r"<(Subject|Picture|Video|Audio) (\d+)>")
 _ABSTRACT_TAG_RE = re.compile(r"\b(?:8k|4k\s*uhd|masterpiece|best quality|unreal engine|photorealistic|trending on artstation)\b", re.I)
+_PSEUDO_PARAM_RE = re.compile(
+    r"(?:(?<!\w)--(?:ar|aspect|v|version|fps|cfg|seed|steps|stylize|chaos|q|quality|iw|no)\b"
+    r"|<lora:[^>\n]+>"
+    r"|\([A-Za-z0-9 _-]+:\d+(?:\.\d+)?\)"
+    r"|\b(?:cfg_scale|num_frames|guidance_scale|fps|aspect_ratio)\s*=\s*\S+)",
+    re.I,
+)
+
+OPPOSING_CAMERA_MOTIONS: tuple[tuple[str, str], ...] = (
+    ("Zoom In", "Zoom Out"),
+    ("Push In", "Pull Out"),
+    ("Pan Left", "Pan Right"),
+    ("Truck Left", "Truck Right"),
+    ("Tilt Up", "Tilt Down"),
+    ("Pedestal Up", "Pedestal Down"),
+    ("Roll Clockwise", "Roll Counterclockwise"),
+    ("Shake Slightly", "Shake Strongly"),
+)
+MOVING_CAMERA_MOTIONS: frozenset[str] = frozenset(
+    key for key in CAMERA_MOTIONS if key not in {"Static Shot", "POV"}
+)
+
+_CAMERA_MOTION_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = tuple(
+    (
+        canonical,
+        re.compile(
+            r"(?<![A-Za-z])(?:"
+            + "|".join(
+                re.escape(phrase)
+                for phrase in sorted({canonical, verb}, key=len, reverse=True)
+            )
+            + r")(?![A-Za-z])",
+            re.I,
+        ),
+    )
+    for canonical, verb in sorted(
+        CAMERA_MOTIONS.items(),
+        key=lambda item: max(len(item[0]), len(item[1])),
+        reverse=True,
+    )
+)
+
+
+def strip_dialogue_blocks(text: str) -> str:
+    """Replace verbatim <d>...</d> spoken lines with spaces before structural scanning."""
+    return _DIALOGUE_BLOCK_RE.sub(" ", text or "")
+
+
+def detect_camera_motions(text: str) -> list[str]:
+    """Return canonical H3 camera motions detected outside dialogue blocks in appearance order."""
+    scrubbed = strip_dialogue_blocks(text)
+    hits: list[tuple[int, str]] = []
+    occupied: list[tuple[int, int]] = []
+    for canonical, pattern in _CAMERA_MOTION_PATTERNS:
+        for match in pattern.finditer(scrubbed):
+            start, end = match.span()
+            if any(not (end <= s or start >= e) for s, e in occupied):
+                continue
+            occupied.append((start, end))
+            hits.append((start, canonical))
+    hits.sort(key=lambda pair: pair[0])
+    ordered: list[str] = []
+    for _, canonical in hits:
+        if canonical not in ordered:
+            ordered.append(canonical)
+    return ordered
 
 
 def h3_frame_grid(duration_seconds: float, fps: int = H3_DEFAULT_FPS) -> dict[str, int | float]:
     """Compute H3's 17n+5 latent frame grid for a 4-15s clip."""
     seconds = float(duration_seconds)
     if not H3_MIN_DURATION <= seconds <= H3_MAX_DURATION:
-        raise ProjectError(f"MiniMax-H3 duration must be between {H3_MIN_DURATION:g} and {H3_MAX_DURATION:g} seconds.")
+        raise ProjectError(f"MiniMax-H3 视频时长必须在 {H3_MIN_DURATION:g} 到 {H3_MAX_DURATION:g} 秒之间。", 422)
     if fps <= 0:
-        raise ProjectError("FPS must be positive.")
+        raise ProjectError("帧率必须大于 0。", 422)
     requested = round(seconds * fps)
     frames = requested + (5 - requested) % 17
+    vllm_omni_frames = 17 * min(max(round((seconds * fps - 5) / 17), 6), 20) + 5
     return {
         "durationSeconds": round(seconds, 4),
         "fps": fps,
         "requestedFrames": requested,
         "gridFrames": frames,
+        "vllmOmniFrames": vllm_omni_frames,
         "effectiveGridSeconds": round(frames / fps, 4),
     }
 
@@ -160,16 +228,27 @@ def h3_reference_ordinals(sources: list[dict[str, Any]] | tuple[dict[str, Any],
     """Compute H3 per-modality tags matching fasth3.native_prompt's audio offset.
 
     FastH3 reserves `<Audio 1..K>` for embedded soundtracks of reference videos
-    (`hasAudio=True`) in source order before numbering standalone audio files.
+    (`hasAudio=True`) in source order before numbering standalone audio files, and
+    `CreationGeneration.task` deduplicates transmitted references by `assetId`.
     """
+    deduped: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    for item in sources:
+        raw_id = str(item.get("id") or "")
+        if raw_id:
+            if raw_id in seen_ids:
+                continue
+            seen_ids.add(raw_id)
+        deduped.append(item)
+
     audio_offset = sum(
         item.get("kind") == "video" and bool(item.get("hasAudio"))
-        for item in sources
+        for item in deduped
     )
     counts: dict[str, int] = {}
     embedded_audio_index = 0
     assigned: list[dict[str, Any]] = []
-    for item in sources:
+    for item in deduped:
         kind = str(item.get("kind") or "")
         counts[kind] = counts.get(kind, 0) + 1
         tag = None
@@ -515,6 +594,21 @@ def lint_h3_prompt(
                     errors.append(f"[Shot {idx}] cut time ({seconds:.3f}s) must fall strictly within duration ({duration_seconds:.2f}s).")
                 last_cut = seconds
 
+        segment_motions = set(detect_camera_motions(segment))
+        for first_motion, second_motion in OPPOSING_CAMERA_MOTIONS:
+            if first_motion in segment_motions and second_motion in segment_motions:
+                errors.append(
+                    f"[Shot {idx}] combines contradictory camera motions ({first_motion} vs {second_motion}); "
+                    "split opposing movements across separate shots."
+                )
+        if "Static Shot" in segment_motions:
+            moving = sorted(segment_motions & MOVING_CAMERA_MOTIONS)
+            if moving:
+                errors.append(
+                    f"[Shot {idx}] combines 'Static Shot' with moving camera instruction(s) {moving}; "
+                    "add a cut timestamp before moving the camera."
+                )
+
     final_shot = max(len(shot_numbers), 1)
     expected_header = _alignment_instruction(normalized_mode, final_shot, float(duration_seconds))
     first_line = prompt.splitlines()[0].strip() if prompt.splitlines() else ""
@@ -533,7 +627,14 @@ def lint_h3_prompt(
     if "says in an off-screen voiceover" in shot_body and "lips remain" not in shot_body:
         warnings.append("Off-screen voiceover should explicitly state after </d> that the on-screen character's lips remain closed.")
 
-    if _ABSTRACT_TAG_RE.search(prompt):
+    scrubbed_prompt = strip_dialogue_blocks(prompt)
+    pseudo_matches = sorted({m.group(0).strip() for m in _PSEUDO_PARAM_RE.finditer(scrubbed_prompt)})
+    if pseudo_matches:
+        errors.append(
+            f"Prompt contains unsupported pseudo-parameter tag(s) {pseudo_matches}; "
+            "pass aspect ratio, duration, and resolution via structured GenerationSpec parameters instead."
+        )
+    if _ABSTRACT_TAG_RE.search(scrubbed_prompt):
         warnings.append("Avoid stacked quality buzzwords (e.g. '8k', 'masterpiece', 'unreal engine'); describe concrete visual and acoustic facts.")
 
     for audio_sec in ("overall_soundscape", "non_diegetic_music"):
diff --git a/packages/core/src/opendirector/media/shot_inspection.py b/packages/core/src/opendirector/media/shot_inspection.py
index eefae9dbe..5cbdb1966 100644
--- a/packages/core/src/opendirector/media/shot_inspection.py
+++ b/packages/core/src/opendirector/media/shot_inspection.py
@@ -69,7 +69,7 @@ def _write_exclusive_bytes(destination: Path, payload: bytes) -> None:
     try:
         fd = os.open(destination, flags, 0o600)
     except FileExistsError:
-        raise ProjectError(f"Output file already exists: {destination}", 409) from None
+        raise ProjectError(f"联系表输出文件已存在：{destination}", 409) from None
     with os.fdopen(fd, "wb") as handle:
         handle.write(payload)
         handle.flush()
@@ -170,9 +170,9 @@ def inspect_video_shot(
 ) -> dict:
     """Probe a video file and optionally render a timestamped JPEG contact sheet."""
     if not video_path.is_file():
-        raise ProjectError(f"Video file does not exist: {video_path}", 404)
+        raise ProjectError(f"视频文件不存在：{video_path}", 404)
     if columns < 1 or columns > 8 or rows < 1 or rows > 8:
-        raise ProjectError("Contact sheet grid dimensions must be between 1 and 8.", 422)
+        raise ProjectError("联系表网格行列数必须在 1 到 8 之间。", 422)
 
     technical = _probe_streams(video_path)
     if contact_sheet_path is None:
@@ -183,7 +183,7 @@ def inspect_video_shot(
             "measuredFacts": _compute_measured_facts(technical, None),
         }
     if not overwrite_cache and contact_sheet_path.exists():
-        raise ProjectError(f"Output file already exists: {contact_sheet_path}", 409)
+        raise ProjectError(f"联系表输出文件已存在：{contact_sheet_path}", 409)
 
     total_tiles = columns * rows
     timestamps = _sample_timestamps(technical["durationSeconds"], total_tiles, technical["fps"])
diff --git a/src/contracts/creation.schema.json b/src/contracts/creation.schema.json
index 020a09c6f..25de37a5c 100644
--- a/src/contracts/creation.schema.json
+++ b/src/contracts/creation.schema.json
@@ -11599,6 +11599,7 @@
                   "type": "string"
                 },
                 "maxItems": 200,
+                "minItems": 1,
                 "type": "array"
               },
               {
@@ -27236,6 +27237,7 @@
                   "type": "string"
                 },
                 "maxItems": 200,
+                "minItems": 1,
                 "type": "array"
               },
               {
diff --git a/tests/test_h3_shot_orchestration.py b/tests/test_h3_shot_orchestration.py
index 17f1d9a4b..7478702b5 100644
--- a/tests/test_h3_shot_orchestration.py
+++ b/tests/test_h3_shot_orchestration.py
@@ -2,10 +2,11 @@
 from io import BytesIO
 import json
 from pathlib import Path
-import shutil
 import subprocess
 from uuid import uuid4
 
+from capabilities import requires_ffmpeg
+
 from fastapi.testclient import TestClient
 import httpx
 from PIL import Image
@@ -696,7 +697,7 @@ def _img_clip(cid, asset_obj, dur=4.5):
     assert final_clips[2].resource.asset.assetId == img_s3.id
 
 
-@pytest.mark.skipif(not shutil.which("ffmpeg") or not shutil.which("ffprobe"), reason="Requires local ffmpeg/ffprobe")
+@requires_ffmpeg()
 def test_real_ffmpeg_shot_inspection(tmp_path):
     from opendirector.media.shot_inspection import inspect_video_shot
 
@@ -888,3 +889,298 @@ async def test_tool_gateway_storyboard_audit_and_video_contact_sheet_preview(tmp
         assert audit_call.value["gate"]["requiresUserApproval"] is True
     finally:
         await gateway.close()
+
+
+def test_lint_contradictory_motions_pseudo_params_and_fractional_17k5():
+    from opendirector.application.creation_storyboard import extract_prompt_shot_features
+
+    # 1. Exact 17k+5 fractional frame duration (158 / 24 = 6.583333s) compiles cleanly and exposes vllmOmniFrames
+    fractional_duration = round(158 / 24, 6)
+    compiled = compile_h3_prompt({
+        "mode": "i2va",
+        "durationSeconds": fractional_duration,
+        "shots": [{
+            "shotSize": "medium close-up",
+            "description": "<Picture 1> turns toward the window",
+            "cameraMotion": "Pull Out",
+            "cameraAmplitude": "small",
+            "cameraSpeed": "slow",
+            "dialogues": [{
+                "speakerId": "S1",
+                "speakerIntro": "The detective",
+                "language": "English",
+                "text": "Push in the latch and pull out the drawer --ar 16:9.",
+            }],
+        }],
+        "overallSoundscape": "Quiet rain on window glass.",
+        "nonDiegeticMusic": "N/A",
+    })
+    assert compiled["lint"]["valid"] is True, compiled["lint"]
+    assert compiled["frameGrid"]["vllmOmniFrames"] == 158
+    features = extract_prompt_shot_features(compiled["prompt"])
+    assert features == {"shotSize": "medium close-up", "cameraMotion": "Pull Out"}
+
+    # 2. Contradictory camera motions and pseudo-parameter flags outside dialogue are rejected
+    contradictory = (
+        "integrated_multimodal_description: [Shot 1] Live-action, a wide shot: The courier walks across the alley. "
+        "The camera pushes in slowly and then pulls out with large amplitude --ar 16:9 cfg_scale=7.\n\n"
+        "overall_soundscape: Distant traffic.\n\n"
+        "non_diegetic_music: N/A"
+    )
+    bad_lint = lint_h3_prompt(contradictory, mode="t2va", duration_seconds=5.0)
+    assert bad_lint["valid"] is False
+    joined_errors = " | ".join(bad_lint["errors"])
+    assert "contradictory camera motions (Push In vs Pull Out)" in joined_errors
+    assert "pseudo-parameter tag(s)" in joined_errors
+
+    static_plus_pan = (
+        "integrated_multimodal_description: [Shot 1] Live-action, a close-up: The watch ticks. "
+        "The camera holds a static shot while it pans left across the desk.\n\n"
+        "overall_soundscape: Soft ticking.\n\n"
+        "non_diegetic_music: N/A"
+    )
+    static_lint = lint_h3_prompt(static_plus_pan, mode="t2va", duration_seconds=5.0)
+    assert static_lint["valid"] is False
+    assert any("Static Shot" in err for err in static_lint["errors"])
+
+
+def test_storyboard_audit_group_visibility_ordinal_policy_and_query_contract(tmp_path):
+    from pydantic import TypeAdapter, ValidationError
+    from opendirector.application.creation_storyboard import (
+        audit_project_storyboard,
+        prepare_timeline_shot_revision,
+        resolve_h3_spec_reference_sources,
+    )
+    from opendirector.domain.creation.commands import Query
+
+    query_adapter = TypeAdapter(Query)
+    g_id, tl_id, s_id = uuid4(), uuid4(), uuid4()
+    with pytest.raises(ValidationError):
+        query_adapter.validate_python({
+            "type": "storyboard.audit",
+            "projectId": str(uuid4()),
+            "queryId": str(uuid4()),
+            "timelineEditorId": str(tl_id),
+            "groupId": str(g_id),
+        })
+    with pytest.raises(ValidationError):
+        query_adapter.validate_python({
+            "type": "storyboard.audit",
+            "projectId": str(uuid4()),
+            "queryId": str(uuid4()),
+            "specIds": [str(s_id), str(s_id)],
+        })
+
+    local = LocalProjects(tmp_path)
+    projects = CreationProjects(local)
+    models = ModelConfigs(tmp_path)
+    model_id = models.save(
+        "video", "http://127.0.0.1:19999/v1", "MiniMax-H3", "",
+        connection_type="self_hosted", protocol="vllm_omni", auth_mode="none",
+    )["id"]
+
+    project_id = uuid4()
+    session = str(uuid4())
+    projects.execute(parse_command({
+        "type": "project.create",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {"name": "Policy & Group Audit"},
+    }))
+    projects.open(project_id, session)
+
+    img_a = _stage_and_import(projects, project_id, session, "a.png", "image", _png_bytes((10, 40, 90)))
+    img_b = _stage_and_import(projects, project_id, session, "b.png", "image", _png_bytes((90, 40, 10)))
+
+    # 1. Reference policy parity: in first_frame mode, a non-frame 'reference' image is context_only and excluded
+    #    from H3 media ordinals, and duplicate asset references collapse to a single <Picture 1>.
+    spec_ff, item_ff = uuid4(), uuid4()
+    ref_frame_id, ref_extra_id = uuid4(), uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(spec_ff),
+                "projectId": str(project_id),
+                "kind": "video",
+                "purpose": "generation",
+                "modelConfigId": model_id,
+                "prompt": compile_h3_prompt({
+                    "mode": "i2va",
+                    "durationSeconds": 5.0,
+                    "shots": [{
+                        "shotSize": "wide shot",
+                        "description": "<Picture 1> opens the scene under warm streetlamps",
+                        "cameraMotion": "Push In",
+                    }],
+                })["prompt"],
+                "parameters": {"videoMode": "first_frame", "durationSeconds": 5},
+            },
+            "item": {
+                "id": str(item_ff),
+                "projectId": str(project_id),
+                "kind": "video",
+                "position": {"x": 0, "y": 0},
+                "binding": {"role": "generation", "objectRef": {"id": str(spec_ff)}},
+            },
+            "references": [
+                {
+                    "id": str(ref_extra_id),
+                    "projectId": str(project_id),
+                    "targetSpecId": str(spec_ff),
+                    "role": "reference",
+                    "order": 0,
+                    "binding": "pinned",
+                    "source": {"assetId": str(img_b.id), "revision": img_b.revision, "fingerprint": img_b.fingerprint, "kind": "image"},
+                },
+                {
+                    "id": str(ref_frame_id),
+                    "projectId": str(project_id),
+                    "targetSpecId": str(spec_ff),
+                    "role": "first_frame",
+                    "order": 1,
+                    "binding": "pinned",
+                    "source": {"assetId": str(img_a.id), "revision": img_a.revision, "fingerprint": img_a.fingerprint, "kind": "image"},
+                },
+            ],
+        },
+    }), session=session)
+
+    snap = projects.snapshot(project_id)
+    resolved_ff = resolve_h3_spec_reference_sources(snap, spec_ff)
+    assert [r["id"] for r in resolved_ff["referenceSources"]] == [str(img_a.id)]
+    assert [r["tag"] for r in h3_reference_ordinals(resolved_ff["referenceSources"])] == ["<Picture 1>"]
+
+    # 2. Hidden parent group excludes child video items from default canvas storyboard.audit
+    hidden_group_id, hidden_spec_id, hidden_item_id = uuid4(), uuid4(), uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.show",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "item": {
+                "id": str(hidden_group_id),
+                "projectId": str(project_id),
+                "kind": "group",
+                "position": {"x": 400, "y": 0},
+                "width": 400,
+                "height": 300,
+                "title": "Archived Shots",
+            },
+        },
+    }), session=session)
+    projects.execute(parse_command({
+        "type": "canvas.createGeneration",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "spec": {
+                "id": str(hidden_spec_id),
+                "projectId": str(project_id),
+                "kind": "video",
+                "purpose": "generation",
+                "modelConfigId": model_id,
+                "prompt": "Broken hidden draft",
+                "parameters": {"videoMode": "first_frame", "durationSeconds": 5},
+            },
+            "item": {
+                "id": str(hidden_item_id),
+                "projectId": str(project_id),
+                "kind": "video",
+                "parentId": str(hidden_group_id),
+                "visible": True,
+                "position": {"x": 420, "y": 40},
+                "binding": {"role": "generation", "objectRef": {"id": str(hidden_spec_id)}},
+            },
+            "references": [],
+        },
+    }), session=session)
+    projects.execute(parse_command({
+        "type": "canvas.hide",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "expectedVersions": [{"objectType": "canvas_item", "id": str(hidden_group_id), "revision": 1}],
+        "payload": {"itemId": str(hidden_group_id)},
+    }), session=session)
+
+    audit = audit_project_storyboard(projects.snapshot(project_id))
+    assert [shot["specId"] for shot in audit["shots"]] == [str(spec_ff)]
+    assert audit["valid"] is True
+
+    # 3. Repeated timeline shot revision on the same (slotId, sourceId) preserves existing connection ID
+    src_img_item = uuid4()
+    projects.execute(parse_command({
+        "type": "canvas.show",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "item": {
+                "id": str(src_img_item),
+                "projectId": str(project_id),
+                "kind": "image",
+                "position": {"x": 0, "y": 320},
+                "binding": {
+                    "role": "material",
+                    "objectRef": {"assetId": str(img_a.id), "revision": img_a.revision, "fingerprint": img_a.fingerprint, "kind": "image"},
+                },
+            },
+        },
+    }), session=session)
+    conn_id = str(uuid4())
+    tl_doc_id = uuid4()
+    tl_create = projects.execute(parse_command({
+        "type": "editor.create",
+        "projectId": project_id,
+        "commandId": uuid4(),
+        "payload": {
+            "document": {
+                "id": str(tl_doc_id),
+                "projectId": str(project_id),
+                "kind": "timeline",
+                "inputConnections": [{
+                    "id": conn_id,
+                    "sourceId": str(src_img_item),
+                    "slotId": "slot-1",
+                    "asset": {"assetId": str(img_a.id), "revision": img_a.revision, "fingerprint": img_a.fingerprint, "kind": "image"},
+                }],
+                "data": {
+                    "fps": 24,
+                    "width": 320,
+                    "height": 240,
+                    "tracks": [{
+                        "id": "v1",
+                        "kind": "visual",
+                        "title": "Main",
+                        "clips": [{
+                            "id": "slot-1",
+                            "resource": {
+                                "asset": {"assetId": str(img_a.id), "revision": img_a.revision, "fingerprint": img_a.fingerprint, "kind": "image"},
+                                "title": "a.png",
+                                "durationSeconds": None,
+                            },
+                            "inPoint": 0.0,
+                            "outPoint": 5.0,
+                        }],
+                    }],
+                    "importedAssets": [{
+                        "asset": {"assetId": str(img_a.id), "revision": img_a.revision, "fingerprint": img_a.fingerprint, "kind": "image"},
+                        "title": "a.png",
+                        "durationSeconds": None,
+                    }],
+                },
+            },
+        },
+    }), session=session)
+    assert tl_create.status == "applied", tl_create
+    local.release(session)
+
+    prepared = prepare_timeline_shot_revision(
+        projects.snapshot(project_id).model_dump(mode="json"),
+        timeline_editor_id=tl_doc_id,
+        clip_id="slot-1",
+        asset_id=img_b.id,
+        source_item_id=src_img_item,
+    )
+    assert prepared["document"]["inputConnections"][0]["id"] == conn_id