# Keyframe-first final visuals for mechanism-reveal shorts

Use this when a final/visual proof is rejected as generic, abstract, dark, preview-board-like, or semantically unclear.

## Trigger phrases / rejection signals

- “not a harmonious AI video”
- “looks like text-to-video random output”
- “too dark / too generic / fantasy form”
- “Wan is only background under overlays”
- “we need deliberate keyframes, not blind T2V”
- “content only makes sense because of the text overlay”

## Core rule

Do **not** use this sequence for final visuals:

```text
text prompt → Wan video → captions/labels over it
```

Use this instead:

```text
mechanism concept → start/end/style keyframes → human/vision review → Wan I2V or first-last-frame → deterministic minimal overlays
```

Wan should carry the visual scene. Captions, arrows, and labels only clarify the already-understandable mechanism.

## Keyframe-first plan shape

For each scene, create auditable keyframe specs before video generation:

- `KeyframeSpec`
  - `scene_id`
  - `role`: `start_frame`, `end_frame`, or `style_reference`
  - `visual_goal`
  - `composition`
  - `foreground_subject`
  - `background`
  - `motion_intent`
  - `style_notes`
  - `forbidden_elements`
  - `renderer_owned_overlays`
  - `approval_required`

- `KeyframeFirstScenePlan`
  - `scene_id`
  - `start_keyframe`
  - optional `end_keyframe`
  - `wan_mode`: `image_to_video` or `first_last_frame_to_video`
  - `duration_seconds`
  - `expected_motion`
  - `max_allowed_overlays`

## Proof gate

Under an `APPROVED_FOR_KEYFRAME_PROOF`-style state, allow only:

- 1–2 styleframe/keyframe drafts for one scene
- one short I2V/first-last-frame proof of roughly 5–8 seconds
- no 38s full final
- no render series
- no posting or platform API

If I2V fails, do not call the output a valid visual proof. It is acceptable to produce a clearly labelled keyframe animatic for composition review, but mark it as `not_wan` / `not_final`.

## Example: s03 mechanism — decision target

Theme:

```text
Without a decision target, AI compresses every sentence equally.
```

Start keyframe:

- clean modern digital meeting workspace
- meeting circle / participants as abstract dots
- many small blank note fragments moving toward a transparent compression funnel
- empty unlit decision-target circle off to the side, visibly unconnected
- balanced exposure; not a dark sci-fi tunnel

End keyframe:

- notes have become a polished but generic summary sphere/box
- decision-target circle remains outside, unlit, and unconnected
- mechanism should be readable without captions

Forbidden:

- readable text baked into the image
- fake UI text, logos, watermarks
- document cards with paragraphs
- random abstract fantasy shapes
- dark sci-fi tubes/tunnels
- large overlay frames or debug boards

Allowed renderer-owned overlays:

- captions in lower safe area
- one small arrow
- one small label such as `NO DECISION TARGET`

## Review criteria

A keyframe/I2V proof is only useful if:

- a meeting/information/summary mechanism is visually recognizable
- the decision target is visibly separate/unprotected
- it does not look like a random AI fantasy video
- it is not so dark that the mechanism disappears
- overlays are minimal and not the main content
- without captions, the rough story still makes sense

## Implementation notes

- Prefer keyframe generation via a high-quality image provider when available, then reserve local GPU for Wan video.
- Keep generated keyframes text-free; deterministic renderer owns all labels and captions.
- Use static phrase captions with active-word highlight, but integrate them softly: no debug bars, no hard boxes, no giant caption slabs.
- Treat a technically successful clip as rejectable if it fails semantic clarity. Content success outranks render success.