# Video Project Workflow

`sdtk-marketing video project` stores a renderer-neutral production ledger below `SDTK_MARKETING_HOME/video-projects/<project-id>/`. It records project intent and reviewable evidence references; it never stores media bytes, credentials, or a renderer installation.

## Contract

The project is a set of JSON records with explicit schema versions:

- project: finite state plus paths to brief, storyboard, assets, transitions, claims, creative plan, final audit, and review;
- brief: audience, problem, one takeaway, CTA, and output format;
- storyboard: stable IDs, timings, purpose/role, and transitions;
- asset: honesty role, normalized capture method, source/hash, technical probe, and QA;
- transition/claim ledgers: reasoned joins and grounded statements;
- creative plan: licensed audio/SFX or SHA-bound voiceover declarations, per-shot motion treatment and coverage, and locked media thresholds;
- final audit: complete video/audio probe evidence against the creative plan;
- visual review: SHA-bound entry and representative frame evidence per shot, with an owner-attested fit/occlusion/safe-area/mobile checklist;
- quality exception: an owner-referenced, single-render waiver for motion-gate findings only;
- review: input SHA and an explicit owner decision.

`FILM_ACCEPTED` and `FILM_REJECTED` are owner-review evidence. Recording either does **not** silently change the project state. Gate advancement remains a separate attended action.

## Commands

```bash
sdtk-marketing video project init <project-id>
sdtk-marketing video project status <project-id> --json
sdtk-marketing video brief validate brief.json --json
sdtk-marketing video storyboard validate storyboard.json --json
sdtk-marketing video asset add <project-id> --file asset.json
sdtk-marketing video asset verify <project-id> --json
sdtk-marketing video project diagnose <project-id> --file storyboard.json --json
sdtk-marketing video creative record <project-id> --file creative.json
sdtk-marketing video project audit <project-id> --file audit.json
sdtk-marketing video quality-exception record <project-id> --file quality-exception.json
sdtk-marketing video visual-review record <project-id> --file visual-review.json
sdtk-marketing video review <project-id> --file review.json
```

`video project diagnose` reports shot distribution, declared text-only time, declared product-on-screen time, repeated transitions, and repeated motion treatments. It is advisory for a work-in-progress storyboard. The final audit reruns it in blocking mode: missing treatment declarations or adjacent repeated treatments cannot be waived by a render.

## Delegated Rendering

HyperFrames remains external. Configure an operator-owned command template only where rendering is authorized:

```bash
export SDTK_MARKETING_VIDEO_CMD_HYPERFRAMES='hyperframes render --input {storyboard} --out {out}'
sdtk-marketing video project render <project-id> --stage rough --out /mounted/review/rough.mp4 --dry-run
```

Supported placeholders are `{project}`, `{brief}`, `{storyboard}`, `{assets}`, `{transitions}`, `{claims}`, `{stage}`, and `{out}`. The CLI shell-quotes every substituted value; templates must leave placeholders unquoted. A missing declared artifact, absent delegate, delegate failure, or missing output fails closed.

For `--stage final`, a direct HyperFrames render is not a completion path. Record `creative.json` first, then configure an operator-owned final media probe that prints JSON only:

```bash
export SDTK_MARKETING_VIDEO_AUDIT_CMD='/absolute/path/reference-video-audit.sh {out}'
```

The final audit requires full motion/content measurements plus exactly one audible stream at `-18..-14 LUFS`, true peak at or below `-1 dBTP`, and no undeclared silence longer than `1.5s`. Public explainers use `voiceover_music_sfx`, which binds the voice file SHA-256, script, timing, provenance, language, and at least one voiceover cue. `music_and_sfx` remains valid for intentionally non-narrated films. A documented `intentional_silence` mode requires an explicit owner-decision reference.

A quality exception can waive only `motion-gate-failed`, must bind one render SHA and one creative-plan SHA, and is recorded into the final audit. It cannot waive audio, media-probe, content, or visual evidence failures. On pass, `audit.json` is atomically recorded and state becomes `REVIEW_READY`.

Before `FILM_ACCEPTED` can be recorded, an owner must record `VISUAL_ACCEPTED` with two hashed frames per storyboard shot: `entry` and `representative`. Each frame explicitly assesses product visibility, text/UI separation, safe area, frame fit, and mobile framing. The kit checks hashes and completeness but does not claim automated visual judgment.

## Boundaries

- Keep MP4/PNG/WAV bytes outside the npm package and ledger fixtures.
- Use the existing `asset verify`, `video calibrate`, copy-check, and SHA-gated publish surfaces; this workflow does not replace them.
- Direct renderer invocations are development-only. They cannot produce final-audit evidence or advance a video-project gate.
- Do not represent generated/reconstructed material as `evidence_capture`.
- Publishing remains an independent attended SHA approval flow.