[BeatSeat]

Summary

• Add opendirector.domain.h3_cinematography for canonical HappyHorse-1.0 (H3) shot compilation and deterministic linting across 7 canonical shot sizes, 20 camera motions in 12 motion families, natural-English speed/amplitude phrasing, 17n+5 frame-grid helpers, dialogue + soundscape linting, <Picture N> / <Video N> / <Audio N> ordinal alignment (accounting for embedded video audio tracks as wired in happyhorse_local), and multi-shot anti-homogenization sequence checks.
• Upgrade asset.preview (AssetPreviewQuery, CreationAssets.preview, /projects/{id}/assets/{asset_id}/preview, and AgentTools) with videoScope="contact_sheet" (columns, rows), rendering timestamped multi-frame JPEG contact sheets (work/previews/{asset_id}-sheet-{columns}x{rows}.jpg) plus objective measuredFacts (meanFrameDelta, maxFrameDelta, firstLastSimilarity, suspectedFrozen, blackFrameIndices, blackFrameRatio, matchesH3Grid, hasAudio) so Agents are no longer limited to Frame-0 video previews while keeping technical measurements strictly separate from creative acceptance.
• Add shared query storyboard.audit (StoryboardAuditQuery + opendirector.application.creation_storyboard.audit_project_storyboard) exposed uniformly across HTTP /queries, AgentTools, and opendirector video audit-storyboard to check cross-shot Subject continuity gaps, unrendered upstream reference keyframes, video continuation depth (> 3), unlinked timeline visual clips, live H3 prompt/ordinal regressions, sequence diversity, and pilot-gate pending video duration.
• Upgrade opendirector video CLI (create with --last-frame, --continue-from, --aspect-ratio, --resolution, --audio, --title; compile-h3-prompt; lint-h3-prompt; lint-shot-plan; audit-storyboard; inspect-shot for local files or --asset UUID; and lineage-aware revise-shot resolving target timeline clips automatically via TimelineDocument.inputConnections and returning non-destructive canvas.materialize commands).
• Add the h3-shot-director skill (SKILL.md, h3-vocabulary.md, shot-orchestration.md), regenerate src/contracts/creation.schema.json and src/contracts/generated.ts, and document the new workflows bilingually in docs/guides/cli.md.

Linked issue

Fixes #338
Refs #107, #191, #261, #263

• Fixes #N or Refs #N is included, or no issue applies

Labels

Suggested labels (external contributor cannot apply labels directly): type:feat, area:agent, area:assets, area:timeline, area:docs, modality:video.

• Labels applied

Test plan

• Local:
  • python3 scripts/generate_contracts.py --check (passed)
  • PYTHONPATH=packages/core/src:apps/api/src lint-imports (passed: 137 files, 4 contracts kept, 0 broken)
  • PYTHONPATH=packages/core/src:apps/api/src pytest tests/test_h3_shot_orchestration.py -q (10 passed, 1 skipped because ffmpeg/ffprobe binaries are not installed in this container)
  • PYTHONPATH=packages/core/src:apps/api/src pytest 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 (141 passed)
  • npm run check:i18n (passed: 3014 keys, 0 problems)
• Left to CI:
  • npm run build (node_modules / tsc not installed in local environment)
  • Real ffmpeg/ffprobe execution (test_real_ffmpeg_shot_inspection in tests/test_h3_shot_orchestration.py)
  • Full Python/API/frontend/browser matrix and bundled OpenCode CLI checks in GitHub Actions

Evidence that it works

• Media attached, or N/A because: Backend domain/application query, agent tool gateway, skill, contract schema, and CLI feature with no React canvas/UI component layout change; verified end-to-end via FastAPI ASGI + ToolGateway + real PIL contact-sheet JPEG rendering + CliRunner in tests/test_h3_shot_orchestration.py.

Provider verification

• Real-provider calls are described honestly, or none were made: Verified against real local project storage, real PIL JPEG contact-sheet rendering, and deterministic media/model doubles (FakeHappyHorseAdapter / deterministic frame probe & extractor); no live GPU happyhorse_local worker or external commercial video API calls were executed in this environment.

Bilingual UI

• Both locales are updated, or no user-facing copy changed (docs/guides/cli.md updated in both zh-CN and en-US; npm run check:i18n passed with 0 problems).