videoclaw 3.0.0-alpha.1

package/references/video/camera-bible.md

@@ -0,0 +1,294 @@
+# Camera Bible — Complete Cinematography Reference
+
+Read this entire file before making any camera choice.
+Every option includes: what it is, what emotion it creates, real example, AI prompt words.
+
+---
+
+## THE 3 DIAGNOSTIC QUESTIONS
+
+Answer these before any camera setting:
+
+1. **What emotion should the audience feel?** (one word)
+2. **Who holds power in this scene?** (character or "neither")
+3. **What is the single most important visual element?** (what the eye must land on)
+
+All camera choices flow from these answers. Never choose randomly.
+
+---
+
+## SHOT TYPES — 13 Options
+
+### EWS — Extreme Wide Shot
+**Emotion:** Isolation, scale, overwhelm, loneliness
+**What it says:** Character is tiny. World is vast. They are small in it.
+**Example:** Lawrence of Arabia — tiny figure crossing infinite desert.
+**AI prompt:** `extreme wide shot, subject tiny in vast environment, isolation, scale`
+
+### WS — Wide Shot
+**Emotion:** Context, arrival, journey, placement
+**What it says:** Character exists within a world. They are part of something larger.
+**Example:** Every establishing shot. Character shown within their environment.
+**AI prompt:** `wide shot, full environment visible, character placed in world`
+
+### MWS — Medium Wide Shot
+**Emotion:** Action, physical storytelling, posture reads
+**What it says:** Full body visible. How they carry themselves tells us who they are.
+**Example:** A character's walk — confident, defeated, afraid — reads at MWS.
+**AI prompt:** `medium wide shot, full body visible, posture and movement readable`
+
+### MS — Medium Shot
+**Emotion:** Conversation, relationship, neutrality
+**What it says:** We are at normal human distance. No agenda. Just listening.
+**Example:** Standard dialogue shot. The honest, neutral shot.
+**AI prompt:** `medium shot, waist up, eye level, neutral, conversational`
+
+### MCU — Medium Close-Up
+**Emotion:** Emotional engagement beginning, investment
+**What it says:** We are starting to feel WITH this person, not just watch them.
+**Example:** The moment before a character makes a decision — tension building.
+**AI prompt:** `medium close-up, chest to head, emotional engagement, investment`
+
+### CU — Close-Up
+**Emotion:** Deep emotion, truth, vulnerability, revelation
+**What it says:** This person's inner life IS the story right now.
+**Example:** Any great actor's face in their defining scene.
+**AI prompt:** `close-up, face fills frame, emotion is the subject, shallow depth of field`
+
+### ECU — Extreme Close-Up
+**Emotion:** Obsession, dread, the world narrows to one thing
+**What it says:** This single detail IS everything right now. Nothing else exists.
+**Example:** Tea crossing the bowl rim. An eye. A trigger finger. A signature being signed.
+**AI prompt:** `extreme close-up, one specific element fills entire frame, world narrows`
+
+### 2S — Two-Shot
+**Emotion:** Relationship, tension, contrast, dynamic between two people
+**What it says:** The space between them tells us everything.
+**Example:** Two characters facing a decision together — or facing each other.
+**Tip:** Left side of frame = past/established. Right side = future/change.
+**AI prompt:** `two-shot, both characters in frame, [describe space between them]`
+
+### OTS — Over The Shoulder
+**Emotion:** Perspective, shared view, we are in the conversation
+**What it says:** We see what this character sees. We share their position.
+**Example:** From Tobun's shoulder looking at Renzo — suddenly Renzo looks smaller.
+**AI prompt:** `over the shoulder shot, camera behind [Character A], looking at [Character B]`
+
+### POV — Point of View
+**Emotion:** Full immersion, we ARE the character, first person
+**What it says:** This is not observation — this is experience.
+**Example:** Walking through a door. Looking down at your own hands.
+**AI prompt:** `point of view shot, first person perspective, we are the character`
+
+### DA — Dutch Angle
+**Emotion:** Psychological unease, instability, something is wrong
+**What it says:** The world is tilted. Normal rules don't apply here.
+**Example:** Every villain reveal. Every moment of psychological horror.
+**AI prompt:** `dutch angle, tilted frame 15-30 degrees, horizon line wrong, unease`
+
+### BA — Bird's Eye / Top Down
+**Emotion:** Detachment, god view, pattern, insignificance
+**What it says:** We observe from above. We are removed from the character's experience.
+**Example:** Final empty bowl — story is over, we step back and look down.
+**AI prompt:** `bird's eye view, camera directly overhead, top-down, subject seen as pattern`
+
+### WE — Worm's Eye
+**Emotion:** Overwhelm, the subject is massive, we are small
+**What it says:** Looking up makes the subject dominant, threatening, or heroic.
+**Example:** Renzo at the gate — three swords against dawn sky. He feels like a force.
+**AI prompt:** `worm's eye view, camera at ground level looking up, subject towers against sky`
+
+---
+
+## CAMERA ANGLE
+
+| Angle | Emotional Effect |
+|-------|-----------------|
+| Low angle | Subject looks powerful, heroic, threatening |
+| Eye level | Neutral, equal, honest, natural |
+| High angle | Subject looks small, judged, vulnerable |
+| Overhead | Abstract, pattern, emotionally removed |
+| Canted/tilted | Psychological unease, instability |
+
+---
+
+## CAMERA MOVEMENTS — 12 Options
+
+### Static Locked
+**Emotion:** Authority, calm, indifference, the world does not react
+**What it says:** When nothing moves — the world accepts what is happening.
+**Power:** Most underused and most powerful movement in cinema.
+**Example:** Tea pour — camera refuses to move while tea overflows. That stillness IS the lesson.
+**Seedance syntax:** `static camera` / `locked off`
+**AI prompt:** `static locked camera, zero movement, locked tripod, absolute stillness`
+
+### Dolly In (Push In)
+**Emotion:** Tension builds, revelation approaching, we enter someone's interior
+**What it says:** We are being pulled into this moment. Something is coming.
+**Example:** Renzo's face cracking — imperceptible dolly in as his certainty collapses.
+**Seedance syntax:** `slow dolly in` / `medium dolly in` / `fast dolly in`
+**AI prompt:** `slow dolly in, camera pushes toward subject, tension building, revelation`
+
+### Dolly Out (Pull Back)
+**Emotion:** Isolation, scale revealed, character left alone, endings
+**What it says:** We are leaving them. The world around them grows.
+**Example:** Renzo laying swords down — pull back gives him privacy in transformation.
+**Seedance syntax:** `slow dolly out` / `pull back`
+**AI prompt:** `slow dolly out, camera retreats, subject grows smaller, isolation, release`
+
+### Pan Left / Pan Right
+**Emotion:** Reveal, following action, world opening in one direction
+**What it says:** The world extends in this direction — follow it.
+**Seedance syntax:** `pan left` / `pan right`
+**AI prompt:** `pan [direction], camera rotates horizontally, [following action / revealing space]`
+
+### Tilt Up
+**Emotion:** Awe, aspiration, power, subject is greater than we realized
+**What it says:** We look up at what dominates. Scale revealed vertically.
+**Seedance syntax:** `tilt up`
+**AI prompt:** `slow tilt up, camera rotates upward, subject revealed bottom to top, awe`
+
+### Tilt Down
+**Emotion:** Shame, defeat, weight, judgment from above
+**What it says:** We look down at what has fallen or been diminished.
+**Seedance syntax:** `tilt down`
+**AI prompt:** `slow tilt down, camera rotates downward, gravity, defeat, weight`
+
+### Orbit / Arc Shot
+**Emotion:** Wonder, examination, god-like observation, nothing hidden
+**What it says:** We see all sides. The subject is worth examining completely.
+**Example:** Product reveals. A character revealed from all angles.
+**Seedance syntax:** `slow orbit left` / `orbit right`
+**AI prompt:** `slow orbit [direction], camera arcs around subject, wonder, examination`
+
+### Tracking Shot
+**Emotion:** Journey, accompaniment, we walk with them
+**What it says:** We are witnesses. We follow at the same distance.
+**Seedance syntax:** `tracking shot`
+**AI prompt:** `tracking shot, camera follows subject at same distance, journey, witness`
+
+### Handheld
+**Emotion:** Intimacy, reality, urgency, documentary truth
+**What it says:** This is real. A human held this camera. We are there.
+**CRITICAL for Seedance:** Always add "subtle" — without it, models shake too violently.
+**Seedance syntax:** `handheld, subtle`
+**AI prompt:** `subtle handheld, organic human sway, documentary feel, intimate, NOT shaky`
+
+### Crane Up
+**Emotion:** Transcendence, release, story ending, we leave the characters
+**What it says:** The story is complete. We rise above the immediate and see the larger picture.
+**Example:** Renzo laying swords down + crane up = giving him space in transformation.
+**Seedance syntax:** `slow crane up`
+**AI prompt:** `slow crane up, camera rises above scene, transcendence, story releasing`
+
+### Whip Pan
+**Emotion:** Surprise, energy shift, time skip, momentum
+**What it says:** Everything just changed. We have moved to something new.
+**Seedance syntax:** Use as transition description in prompt
+**AI prompt:** `whip pan [direction], fast horizontal snap, motion blur smear, energy shift`
+
+### Vertigo Effect (Push-Pull)
+**Emotion:** Existential dread, reality shifting, something deeply wrong
+**What it says:** The world changes around this person. Reality warps.
+**Use:** Maximum once per video. Loses power if repeated.
+**AI prompt:** `vertigo effect, dolly out while zooming in, background warps, subject stays, dread`
+
+---
+
+## LENS & FOCAL LENGTH
+
+| Focal Length | Character | Best For |
+|-------------|-----------|----------|
+| 14mm | Extreme distortion, immersive | Horror, epic environment, overwhelming scale |
+| 24mm | Wide, natural, cinematic | Establishing shots, character in world |
+| 35mm | Slightly wide, honest | Street, documentary, natural arrival |
+| 50mm | Human eye, neutral truth | Dialogue, honest scenes, no agenda |
+| 85mm | Flattering compression | Character close-ups, emotional scenes |
+| 100mm | Intimate, subject isolated | Strong emotional moments, detail |
+| 135mm+ | Heavy compression, watched | Surveillance feel, observed subject |
+| Macro | Tiny becomes universe | Objects, textures, extreme detail |
+| Anamorphic | Horizontal flares, epic scope | Brand films, epic scale, cinematic |
+
+**Depth of Field:**
+- **Shallow** — Subject sharp, background bokeh. Subject is isolated from world.
+- **Medium** — Subject sharp, background soft. Balance.
+- **Deep** — Everything sharp. Full environment readable.
+
+**Camera Body Feel:**
+- **ARRI Alexa LF** — Warm, organic, filmic. Industry gold standard.
+- **IMAX 70mm** — Epic scale, rich shadow, enormous detail.
+- **16mm Film** — Grain, texture, gritty intimacy. Raw emotion.
+- **Panavision 35mm** — Classic Hollywood. Rich, balanced.
+- **Anamorphic** — Horizontal lens flares. Epic widescreen scope.
+
+---
+
+## LIGHTING DIRECTION
+
+### Light Quality
+- **Hard light** — Sharp shadows. Drama. Conflict. Chiaroscuro.
+- **Soft light** — Diffused. Gentle. Safe. Contemplative.
+- **Mixed** — Hard key, soft fill. Cinematic standard.
+
+### Key Light Direction
+
+| Position | Effect |
+|----------|--------|
+| Rembrandt (45° above side) | Classic drama. Triangle of light on shadow cheek. Trusted. |
+| Side lit | Half face in shadow. Duality, mystery, moral ambiguity. |
+| Backlit | Silhouette or rim. Separation, mystery, divinity. |
+| Front lit | Flat, honest, vulnerable, exposed. |
+| Under lit | From below. Unsettling. Unnatural power. Wrong. |
+| Top lit | From above. Judgment, interrogation, isolation. |
+
+### Color Temperature — Kelvin Scale
+
+| Temp | Quality | Emotion |
+|------|---------|---------|
+| 1800K | Candlelight | Ancient, intimate, fragile, last two people awake |
+| 2700K | Warm tungsten | Safe, nostalgic, human, home |
+| 3200K | Film standard warm | Professional interior, balanced warmth |
+| 4000K | Neutral morning | Truth, reality, early light |
+| 5600K | Daylight | Outdoor, balanced, real world |
+| 6500K | Overcast | Flat, cold, melancholy, no warmth |
+| 7000K+ | Blue steel | Night, clinical, isolated, dangerous |
+
+**Two-temperature technique:** Mix warm key + cool fill (or reverse).
+Two temperatures in one shot = depth, complexity, dimension.
+One temperature = flat, safe, less interesting.
+
+---
+
+## COLOR GRADE & ATMOSPHERE
+
+### Color Grades
+
+| Grade | Emotion | Use For |
+|-------|---------|---------|
+| Warm desaturated / wabi-sabi | Ancient, weighted, earned | Period pieces, zen, craft, tradition |
+| Cold blue steel | Isolated, clinical, controlled | Modern thriller, loneliness, power |
+| Golden bloom | Memory, warmth, nostalgia, earned | Endings, reunion, achievement |
+| Teal & orange | Hollywood cinematic | Action, contrast, drama |
+| Bleach bypass | Gritty, raw, high contrast | War, struggle, harsh reality |
+| High contrast noir | Moral extremes, mystery | Crime, divided world, secrets |
+
+### Atmosphere Words — The Secret Weapon
+
+**Always include exactly 5 sensory words per scene:**
+- One smell
+- One texture
+- One sound
+- Two feelings
+
+**Why it works:** AI models are trained on human language. Sensory language —
+especially smell and sound in a visual prompt — activates a deeper,
+more instinctive visual library than purely visual descriptions.
+
+**Example — Tobun's studio:**
+`incense / worn tatami / brush on paper / restraint / waiting`
+
+**Example — Renzo at gate:**
+`cold iron / damp bamboo / silence before dawn / weight / unease`
+
+**Example — Tea overflow:**
+`steam / ceramic / dripping / inevitable / held breath`

package/references/video/character-reference-sheet.md

@@ -0,0 +1,14 @@
+# Character Reference Sheet
+
+Identity sheets are the continuity anchor for director-mode character work.
+
+Recommended coverage:
+
+1. at least one `identity` role reference for every character-bearing scene
+2. two or more identity references when the character appears across multiple scenes
+3. `characterName` set on character-specific identity sheets
+4. explicit bindings to the scenes where the character appears
+
+Use outfit, material, environment, motion-camera, and palette-mood sheets for supporting continuity, but do not treat them as substitutes for identity coverage.
+
+Readiness warnings should stay non-blocking unless a character-bearing director scene has no bound Identity Sheet at all.

package/references/video/checkpoint-protocol.md

@@ -0,0 +1,26 @@
+# Video Checkpoint Protocol
+
+## Required checkpoint fields
+
+1. `stage`
+2. `status`
+3. `generatedAt`
+4. `artifacts`
+5. `summary`
+6. `issues`
+7. `nextAction`
+
+## Status values
+
+1. `completed`
+2. `awaiting-approval`
+3. `retry-required`
+4. `failed`
+5. `pending`
+
+## Hard rules
+
+1. Do not mark a stage complete if its required artifact is missing.
+2. Do not move to publish from a retry review verdict.
+3. Do not silently reinterpret missing outputs as success.
+4. Keep resume logic artifact-based, not log-based.

package/references/video/clone-ad-template-workflow.md

@@ -0,0 +1,14 @@
+# Clone Ad Template Workflow
+
+Analyze a reference ad into reusable structure, not copied content.
+
+Capture:
+
+1. hook pattern and first-second tension
+2. beat order and compression strategy for 15-second variants
+3. motion mode: live motion, animated stills, mixed, or unknown
+4. style layers such as casting, setting, framing, lighting, pacing, and edit rhythm
+5. what to keep structurally and what must change for the new intent
+6. reusable variables such as product, audience, offer, proof, objection, and call to action
+
+Clone plans should preserve the reusable mechanism while replacing product facts, claims, people, and brand-specific language.

package/references/video/dialogue-duration-preflight.md

@@ -0,0 +1,17 @@
+# Dialogue Duration Preflight
+
+Short clips need spoken lines that fit the available screen time.
+
+Default budget:
+
+1. assume 15 seconds when a scene has no `durationSeconds`
+2. estimate dialogue at about 2.5 words per second
+3. warn when estimated dialogue duration exceeds the clip target
+4. promote warnings to errors only under strict director preflight
+
+Rewrite guidance:
+
+1. keep one spoken idea per shot
+2. split multi-sentence explanations across scenes
+3. use visuals for setup and proof instead of narration
+4. reserve the final second for reaction, product beat, or transition

package/references/video/generation-telemetry.md

@@ -0,0 +1,18 @@
+# Generation Telemetry
+
+Use this reference whenever a provider route submits, polls, or completes a generation.
+
+Record:
+
+1. route id, operation kind, dry-run/live status, and external job id
+2. task count, scene indices, average clip duration, prompt word count, and reference counts
+3. provider-reported credits, USD cost, generation time, and issues when available
+4. output ingestion count after polling
+
+Cost estimates should use provider-reported USD samples only when the route and task count are clear. Credits are kept as telemetry unless a route-specific conversion exists in code.
+
+Avoid:
+
+1. mixing dry-run estimates with live provider cost samples
+2. converting credits to USD without a route-specific conversion contract
+3. dropping failed or blocked events; they explain why no output was produced