@nodetool-ai/agents 0.8.4-a24.2 → 0.8.4

package/dist/_skills/trailer-template/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: trailer-template
+description: Structure a trailer or teaser as eight audio-first beats — hook, setup, inciting incident, escalation, drop, climax, title, button — with a runtime-scaled timecode grid, event/reception shot pairs, a planted-and-harvested motif, and one unbroken music bed, then store it as a NodeTool storyboard with a character entity behind every recurring face. Use when someone asks for a trailer, teaser, sizzle or announcement cut structure, says a cut has no spine or no build, or needs to know where the drop and the title card go. Pairs with short-film, which sets the cast, look and blocking. Not for ads (commercial-beat-sheet) or music videos (music-video-treatment).
+---
+
+You are a single agent. Take a title, a genre and a runtime and produce a complete, timecoded trailer plan as a NodeTool storyboard. You call the storyboard, entity and timeline capabilities directly. You do not build a workflow. You do not render or assemble unless asked.
+
+Fill the header first. Every field below is required and none is guessed — a fact you do not have is `[CLIENT INPUT NEEDED]`.
+
+```text
+TITLE:
+GENRE:
+LENGTH:           [seconds]
+FORMAT:           16:9 / 2.39:1 / 9:16
+THESIS:           [the one idea the trailer argues, one sentence]
+CENTRAL QUESTION: [the question left OPEN at the end]
+MOTIF:            [recurring visual element — hands, doors, water, mirrors]
+                  Planted in SETUP, paid off in PEAK or BUTTON.
+```
+
+---
+
+## Two principles nothing overrides
+
+**Event → reception.** The unit is a pair, never a single shot. Something happens, then a face receives it. Meaning lives in the second shot. An escalation section without receptions is world-building, not escalation.
+
+**Audio is the clamp.** The picture is discontinuous — shots from different scenes, places and times. The sound is one unbroken bed across the whole runtime, and that bed is what makes the fragments read as one thing. Never cut the audio to silence. Dip it.
+
+---
+
+## The dynamic curve
+
+```text
+  quiet / slow  ~65%          |  loud / fast  ~35%
+  ─────────────────────────── DROP ──────────────────────
+  Beats 1–4                   |  Beats 6–8
+```
+
+One hinge. The drop lands at **~65% of runtime**. Everything else is subordinate to this curve.
+
+**Minimum perceptual durations** — below these a beat does not read:
+
+| Beat | Minimum |
+| --- | --- |
+| Drop | 1.0s |
+| Setup | 4.0s |
+| Button | 2.0s |
+| Any reception shot | 0.8s |
+
+**Compression rule.** Below 25s the proportions break, so a short trailer **fuses** beats rather than shrinking all eight. Fusion order: Hook + Setup merge → Inciting + Escalation become one build → the Drop stays untouched → Button merges into Title.
+
+---
+
+## Beat budget
+
+Compute timecodes from the runtime, rounded to 0.5s. Check every beat against its minimum after rounding, and fuse per the rule above when one falls under.
+
+| Beat | % of runtime | Job |
+| --- | --- | --- |
+| 1 Hook | 0–8% | Interrupt. Open an information deficit. |
+| 2 Setup / World | 8–25% | Install identification. The normal state as precious or fragile. Plant the motif. |
+| 3 Inciting incident | 25–32% | One nameable event turns the state into a problem. |
+| 4 Escalation / Stakes | 32–65% | Accumulate. Each unit raises a new dimension. Longest section. |
+| 5 Drop | 65–68% | The hinge. Maximum contrast, not maximum volume. |
+| 6 Climax / Peak | 68–85% | Payoff as fragments. The emotional summit is a human beat inside the spectacle. |
+| 7 Title card | 85–90% | Name the feeling. Lands on the impact. |
+| 8 Button / Stinger | 90–100% | Recency. One small, single beat that works without context. |
+
+---
+
+## The eight beats
+
+### Beat 1 — Hook
+
+Event before face. No genre marker yet. Never explain. Start quiet — opening loud burns the dynamic range the drop needs.
+
+| type | shot |
+| --- | --- |
+| event | a phenomenon with a timestamp — a thing that **happens**, not a state |
+| reception | a face receiving it. Attention, not yet fear. |
+
+### Beat 2 — Setup / World
+
+Not plot: an emotional anchor. Show the normal state as precious or fragile, or its destruction means nothing. Plant the musical motif here; you harvest it at the climax. If two characters will conflict later, stage one **disagreement** beat now — otherwise their conflict is asserted, not prepared.
+
+| type | shot |
+| --- | --- |
+| setup | protagonist in the normal state — warm, ordinary, specific |
+| setup | intimacy or fragility — a small physical gesture, the **motif** planted |
+| setup | disagreement — two positions, silently staged |
+
+### Beat 3 — Inciting incident
+
+One identifiable event, never a montage. If the viewer cannot name what changed, the trailer has no spine. First real impact — it works because you spent none before. Impacts are currency: spend them ascending.
+
+| type | shot |
+| --- | --- |
+| event | the turn — one nameable event |
+| reception A | character 1 reads it as `[reading A]` |
+| reception B | character 2, the **same** event, reads it as `[reading B]` — the thesis in two faces |
+
+### Beat 4 — Escalation / Stakes
+
+Accumulate, never repeat. Tension is a function of duration, so this is the longest section. The reveal ratio climbs like a ladder and never completes. **Every event needs a receiver.** Ladder the dimensions: intimate → social → institutional → domestic → personal.
+
+| type | shot | dimension |
+| --- | --- | --- |
+| event | scale widens — the world notices | society |
+| reception | a stranger's face | |
+| event | institutions respond | state |
+| reception | the protagonist's protector reacts — fear turns domestic | |
+| event | the threat enters the home | intimate |
+| reception | the protagonist chooses — a small physical act of crossing | |
+| reception | stakes crystallize — someone realizes what they have lost | |
+
+### Beat 5 — Drop
+
+The hinge between question and promise. Not the loudest moment: the moment of maximum **contrast**. You are not making silence, you are manufacturing headroom, and it must land on an image worth the pressure. Under 1s it reads as an edit error, not a pause.
+
+| type | shot |
+| --- | --- |
+| DROP | stillness. The single best held image. Small figure, vast unseen force. |
+
+### Beat 6 — Climax / Peak
+
+Payoff as fragments, never answers. Highest kinetic energy, but the summit is a human beat inside the spectacle — spectacle without a face is noise. Consequence, never outcome. The motif from Beat 2 returns in full orchestration.
+
+| type | shot |
+| --- | --- |
+| climax | the face — emotion rising, readable |
+| **PEAK** | the emotional summit — the motif paid off, in granular sensory detail |
+| reversal | optional: everything snaps out — the sudden absence |
+
+### Beat 7 — Title card
+
+The title arrives at maximum emotional charge so the name and the feeling weld. It lands **on** the impact, not after — sound and type in the same frame.
+
+### Beat 8 — Button / Stinger
+
+The last thing is what gets carried out. Controlled discharge plus a residue that makes the film specific instead of generic — this is where you tell the truth about the genre. Small and single after the bigness, and it must work without context. Advanced move: put the biggest reveal here, after the title, when the audience thinks it is over.
+
+| type | shot |
+| --- | --- |
+| BUTTON | one last beat — punchline, scare, tenderness or reveal. Deny the expected hit. |
+
+---
+
+## Audio bed — one unbroken track
+
+```text
+[Hook]        sub-bass drone + ambience + ONE distant tonal element
+[Setup]       THE SEED: fragile motif enters — instrument: [INSTRUMENT]
+[Inciting]    motif bends. First impact. Sub grows.
+[Escalation]  layers stack: pulses → riser → strings. Accelerating.
+[Drop]        ★ DIP to bare sub-rumble. Never fully out.
+[Climax]      THE HARVEST: motif returns fully orchestrated + choir/strings bloom
+[Title]       one sustained luminous chord + sub-boom → title
+[Button]      minimal. Withhold the stinger hit if the button is tender.
+```
+
+**Cut on the transient.** Picture cuts land on hits, not between them. **Sound design over music at impact.** The braam carries the blow, the score carries the emotion.
+
+---
+
+## Entities
+
+Any character in more than one shot is a **character entity**, or you get a different person every time. The protagonist, the protector and whoever carries reception B usually make three. A recurring home is a **location** entity, the grade a **style** entity, the motif object (if it is an object) a **prop**.
+
+```js
+import { list_entities, create_entity } from "@nodetool-ai/sandbox-nodetool/entities";
+
+await list_entities({});   // reuse before you generate
+
+const still = await nodetool.media.generateImage(
+  "<the character, neutral background, in the trailer's grade>",
+  await nodetool.models.pick("text_to_image")
+);
+await create_entity({
+  asset_id: still.asset_id,
+  kind: "character",
+  name: "<Name>",
+  descriptor: "<one to two dense sentences describing exactly what the reference shows>"
+});
+const entityId = still.asset_id;   // the entity IS its asset
+```
+
+The descriptor is the face. Name entities in plain text in a shot's `action` or `motion` — "Mara turns from the window", never `@Mara` — and do not re-describe them in shot text. The render attaches a character or prop entity to a shot only when its name appears in that shot's text (style and location entities always apply), so a reception shot that says "she" instead of "Mara" renders a stranger. Show the roster before drafting beats.
+
+---
+
+## Storyboard
+
+### 1. Create the board
+
+```js
+import { create_storyboard, edit_storyboard } from "@nodetool-ai/sandbox-nodetool/storyboards";
+
+const board = await create_storyboard({
+  name: `${title} — trailer (${runtime}s)`,
+  brief: `${thesis}\nCENTRAL QUESTION: ${centralQuestion}\nMOTIF: ${motif}`,
+  style: "<the grade in one line>",
+  aspect_ratio: "16:9"
+});
+const boardId = board.storyboard_id;
+```
+
+### 2. Roster and models
+
+The full contract — the fifteen `edit_storyboard` ops, every key `set_board` accepts (`music_prompt` among them), and which fields and entities each shot's prompt receives — is in `storyboard-core` § Tool contract. Models come from `find_model` — pass each result's `.ref`; there is no default, and an unset model fails the render. For the cast, the look and the blocking, load `short-film`; this skill only sets where the beats go.
+
+```js
+const stills = await find_model({ capability: "text_to_image" });
+const clips = await find_model({ capability: "image_to_video" });
+await edit_storyboard({
+  storyboard_id: boardId,
+  ops: [{ op: "set_board", entity_ids: roster,
+          image_model: stills.ref, video_model: clips.ref }]
+});
+```
+
+Each result also names a `prompting_skill`. Load it before step 3: the shot `action`, `motion` and `camera` are the prompt the generator reads (`motion`, `action`, then the camera movement, for a keyframe clip), and a trailer's receptions and its drop are worded differently for a line that wants beats in order (Hailuo), a shot list (Kling) or a sound brief (Seedance).
+
+### 3. One shot per row
+
+Every row in the beat tables is one `add_shot`. The slug carries the beat and the type, so the pair structure survives into the board and the cut.
+
+```js
+await edit_storyboard({
+  storyboard_id: boardId,
+  ops: [{
+    op: "add_shot",
+    slug: "3-event",                     // <beat>-<type>: 1-event, 1-reception, 3-reception-a, 5-drop, 6-peak, 8-button
+    action: "INCITING (0:09–0:10.5): the turn — <one nameable event>, Mara in frame",
+    camera: { framing: "close", lens: "50mm", angle: "eye", movement: "static" },
+    motion: "<what moves, with counts — 'she looks up once', not 'tense'>",
+    duration_seconds: 1.5,
+    render_mode: "keyframe"
+  }]
+});
+```
+
+Rules for the shot text:
+
+- `action` opens with the beat name and timecode, then the shot. Under 400 characters.
+- A reception shot's `action` names whose face it is and what it reads. Its `motion` is a single small physical event.
+- The drop shot's `motion` is stillness, stated: "nothing moves except the water".
+- The title card and any on-screen text are **not** shots. Type goes in post (`caption-titles`), because generators render text unreliably.
+- `render_mode: "direct"` only for a heavy-motion climax shot. Receptions and the drop stay on `keyframe`, where the face holds.
+
+### 4. The audio bed lives on the board, not on the shots
+
+Put the eight-line bed into the board's `brief` as a `MUSIC:` block, one line per beat with its timecode. Per-shot `narration` stays empty — native per-shot audio is fragments, the opposite of the clamp. `edit_storyboard` → `{op: "set_board", music_prompt}` writes the same text into the board's music prompt, headless, and `assemble_storyboard_timeline` then turns it into a draft music clip.
+
+---
+
+## Pre-delivery check
+
+Run before showing anyone. Every line must be true of the board, not the plan.
+
+- [ ] Hook is event before face, no genre marker
+- [ ] Every escalation event has a reception shot
+- [ ] Setup shows the normal state as precious or fragile
+- [ ] Disagreement beat present if characters conflict later
+- [ ] Motif planted in Beat 2, harvested in Beat 6
+- [ ] Drop sits at ~65% and lands on an image worth the pressure
+- [ ] Emotional summit is not on the spectacle shot
+- [ ] Title lands on the impact, same frame
+- [ ] Button is small, single, works without context
+- [ ] Audio never cuts to true silence — dips only
+- [ ] Central question still open at the end
+- [ ] No beat below its minimum perceptual duration
+- [ ] Every face appearing twice is an entity on the board
+
+---
+
+## Render and cut (only on request)
+
+**Stills first.** `render_storyboard_stills` costs less than clips, and you look at them before any clip renders. A wrong face is fixed at the entity, never in one shot's prompt.
+
+**Fuse or render long, and say which before the clip pass.** A 1.5s beat still buys the video model's shortest clip, often 5s or more, so a shot rendered on its own comes back long without bumping `duration_seconds`. Where consecutive beats share a setting — an event and its reception, a run of escalation cuts — render them as one generation and split it with `covered_by` (`storyboard-core` § Fusing shots): fewer clips for the same cut. Render a beat on its own and trim it where it needs a picture no neighbour can share. Report the clip count and get the user's go-ahead when it is more than the request implied. Clips mute their own audio; `analyze_video` on a clip gives its real length before you trim.
+
+**The bed is one clip.** After `assemble_storyboard_timeline`:
+
+1. `generate_music` once, for the full runtime, from the eight-line bed. One prompt, one clip.
+2. `edit_timeline` → `add_track` (audio), then `add_media_clip` for that one asset at 0:00. Mute the per-shot "Shot Audio" clips the assembly created (`set_clip_params {muted: true}`), and delete its draft music clip if the board has a music prompt, so this bed is the only music.
+3. `detect_audio_events` on the bed, then `beat-sync-editing`: every picture cut moves to the nearest transient. The drop shot's in-point sits on the dip.
+4. The dip is a volume keyframe on the bed, not a cut. Never a gap.
+5. `caption-titles` for the title card, timed to the same frame as the title impact in the bed.
+6. `validate_timeline`, then `preview_timeline_frame` at the drop, the peak and the title.
+
+`timeline-edit-ops` carries the timeline op contract, `motion-graphics` the build loop, `video-audio-continuity` the case where a shot's own sound has to survive, `color-motion` the grade that makes shots from different scenes cut together, and `logo-reveal` a studio mark after the button.

package/dist/_skills/ugc-video/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: ugc-video
+description: "Direct phone-shot creator videos, UGC ads, testimonials, or vlogs in NodeTool. For polished product films, use product-commercial; for an ad's beat structure, pair with commercial-beat-sheet."
+---
+
+**Load `/storyboard-core` first.** It carries the loop, the tool contract,
+the entity rules and the gating this skill assumes. Everything below is what is
+different about a phone-shot piece with a person in it. For a UGC ad, this skill
+sets the look and `/commercial-beat-sheet` sets the hook, beats and timecodes.
+
+## What makes this job type its own
+
+The face is the deliverable. One character entity has to survive every shot, and the
+look has to read as a phone rather than a camera. Both are set once, on the board, and
+never re-argued in shot text.
+
+## Casting comes first, and it is two passes
+
+There is no create-from-text, and a face you have not seen is a face you cannot lock.
+
+1. `find_model` (`text_to_image`) → `generate_image` with the character description
+   alone: age, build, skin, hair, no wardrobe, no set, front-lit, neutral expression.
+2. Show it. If the user likes it, `create_entity {asset_id, kind: "character", name,
+   descriptor}`. The descriptor is the face and hair only.
+3. After the first board stills come back, if a frame reads better than the reference,
+   `update_entity {entity_id, asset_id}` to move the entity onto that crop. Do this
+   **before** clips, not after.
+
+Given a photo instead: save it as an asset, then `create_entity` from it. Write the
+descriptor from the face and hair in the photo and **leave the photo's outfit out** —
+wardrobe belongs in shot text, so the same entity can wear a gym set in one board and
+a coat in the next.
+
+## The look goes in the board style, once
+
+Put the camera pretence in `style` via `set_board`, never in each shot:
+
+| Register | `style` |
+|---|---|
+| Front-camera UGC | `handheld front-camera iPhone, mild shake, autofocus hunt, compression grain, window daylight, no beauty filter` |
+| Friend-filmed | `handheld phone at arm's length, natural wind and room noise, slightly off-level framing` |
+| Old-phone ritual | `old iPhone 1x, propped static angle, fluorescent tint, heavy noise` |
+| Vlog | `chest-height phone gimbal, wide lens, natural light, mild bloom` |
+
+No music, no score, no burned-in captions. Natural audio is part of the register — say
+so in the brief so the video model does not add a bed.
+
+## Shot pattern
+
+Five to eight shots. A hook in the first four seconds, a middle that shows the thing
+happening physically, and a verdict to camera.
+
+- **Dialogue is a shot field**, not part of `action`. Set `dialogue` so
+  `extract_script_from_storyboard` can lift the words later if the user wants them
+  voiced properly.
+- Write the physical beat in `motion` with a **count**: `two short spray bursts`,
+  `two head turns`, `she lifts one section of hair and lets it fall, once`. "She
+  reacts" renders as nothing.
+- A talent-free end card (pack hero, logo card) needs its own `entity_ids` naming the
+  product alone — otherwise the character's descriptor seasons a shot she is not in.
+- Native-audio video models are weakest on their image path. For a shot whose spoken
+  line has to look synced, set `render_mode: "direct"`. A direct clip prompt already
+  carries the camera fields and the board style.
+
+## Wardrobe and state
+
+One outfit per piece unless the script changes it on camera. A wet, stained or
+changed-outfit version of the same person is a **second entity** — cast it the same
+way and name it in the shots where it applies.
+
+## Briefs
+
+Adapt these examples to the user's brief. Example deliverables, style choices,
+and approval checkpoints apply only when the user adopts them.
+
+**Briefs** below has four written to these rules: review-to-hero UGC ad,
+Pinterest-fail comedy, locker-room ritual, and a night-city vlog with a shot-collapse
+step. Replace the bracketed placeholders and hand one over after the standing orders.
+
+## Briefs — phone-shot video with talent
+
+One per message, after the standing orders from `/storyboard-core`. Replace
+`[PRODUCT]`, `[CITY]`, `[ACTIVITY]`. `Nova` stands for the character entity's **plain
+name** — that is what makes it season the prompt.
+
+---
+
+### Review-to-hero UGC ad, 30s 9:16
+
+```
+Direct a 30s 9:16 UGC-to-hero ad for [PRODUCT].
+
+Cast first. [PRODUCT] as a prop entity from the attached pack shot. Nova as a
+character entity: generate the reference still (early 20s, natural skin, no
+beauty filter, front-lit, neutral) and show me before you tag it. Descriptor is
+face and hair only.
+
+Board style: handheld front-camera iPhone, bedroom or bright bathroom, mild
+shake, autofocus hunt, compression grain, window daylight, no beauty filter.
+Natural audio only, no music, no burned-in captions.
+
+Seven shots, then stop.
+1a 0-4   hook. Nova touches untreated hair. "I wanted lighter hair..."
+2a 4-8   she finds [PRODUCT] on the dressing table, autofocus hunts onto the
+         label. "...without permanently dyeing it."
+3a 8-13  she sections her hair, two short spray bursts. Physical coverage, not
+         a magic glow.
+4a 13-18 extreme close-up, untreated against treated. "Okay... that is
+         actually a huge difference."
+5a 18-23 mirror selfie, two head turns. "I actually love it."
+6a 23-26 [PRODUCT] held beside her face. "Just spray and switch up your look."
+7a 26-30 no talent. Studio hero of [PRODUCT], slow 8cm push-in, cream
+         cyclorama, copy space right. Set entity_ids on this shot to the
+         product alone.
+
+After I pick a face from the stills, select that still with select_version and
+move the Nova entity onto that crop before any clip renders.
+```
+
+### Pinterest-fail comedy, 30s 16:9
+
+```
+Direct a 30s 16:9 friend-shot phone comedy. Nova tries to get a perfect
+Pinterest still of [ACTIVITY] with [PRODUCT] in frame; reality ruins every
+attempt. Same face and wardrobe throughout.
+
+Cast Nova from text first: generate the reference, show me, then tag it.
+Board style: handheld phone at arm's length, natural wind and room noise,
+slightly off-level framing. No score — wind and laughter only.
+
+1a 0-5   she arranges the cloth and [PRODUCT]. Wind flips the plate once.
+         "...Okay, we'll pretend that didn't happen."
+2a 5-10  deadpan, she does not chase it. A friend's laugh jolts the frame once.
+3a 10-15 serene profile, a bee, one swat, a whip-pan.
+4a 15-20 hair-in-wind walk, cardigan over her head, [PRODUCT] still in one hand.
+5a 20-25 thermos pour, a stain spreads, off-camera "That's going to stain—"
+6a 25-30 she flops onto the cloth, [PRODUCT] on her stomach. "This is the photo.
+         This is the one we're posting." Thumbs up, cut mid-laugh.
+```
+
+### Locker-room ritual, 19s 16:9
+
+```
+Direct a 19s 16:9 everyday phone video of Nova, cast from the attached photo.
+Save the photo as an asset, then create the entity from it. The descriptor pins
+the face and hair from the photo and does not mention its outfit.
+
+Wardrobe in the shot text: black gym set, hair tied. Locker room, full-length
+mirror, bag on the bench, no readable signage.
+Board style: old iPhone 1x, propped static angle, fluorescent green tint, heavy
+noise. No music bed.
+
+1a 0-4   she walks to the mirror, props the phone, adjusts her straps
+2a 4-8   sits, double-knots her laces, bounce-tests the shoes twice
+3a 8-11  earbuds in, one at a time
+4a 11-14 two shoulder rolls, a quiet "okay... let's get it."
+5a 14-17 three arm swings, one glance at the camera
+6a 17-19 picks up the phone, walks to the door, freeze mid-stride
+
+Stills from the photo entity, then one clip pass.
+```
+
+### Night city vlog, 30s
+
+```
+Direct a 30s first-person night vlog in [CITY] with Nova in one outfit
+throughout. Mix selfie, cockpit, aerial and street-level. Short landmark lines
+for [LANDMARK A] and [LANDMARK B]. No text, no logos. Wind in her hair.
+
+Board style: chest-height phone gimbal, wide lens, city sodium and neon, mild
+bloom, natural audio.
+
+Board up to ten shots, then — before any render — propose a six-shot collapse
+and name the four you would drop. Stop there.
+
+1  rooftop selfie, the vehicle behind her. "I'm getting on this in [CITY]."
+2  inside, harness on, a nervous smile
+3  lift-off, wide city and water
+4  open door. "there's no door."
+5  POV, feet over the grid
+6  selfie with [LANDMARK A]. "That's [LANDMARK A]."
+7  aerial over [LANDMARK B], her feet in frame
+8  low pass along a bridge
+9  she steps off, same outfit, walks to camera
+10 crossing the street. "Alright everyone, bye."
+```

package/dist/_skills/veo-3-prompting/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: veo-3-prompting
+description: Prompt Google's Veo 3 video line — the five-element shot/setting/subject/action/dialogue structure, the cinematography vocabulary it reads directly, duration and aspect-ratio tradeoffs, the audio and auto-fix switches per provider, and the fixes for visual drift, temporal inconsistency and audio mismatch. Use whenever the model id contains veo3 or veo-3 (fal-ai/veo3.1 and its fast, lite, image-to-video, first-last-frame and reference-to-video routes, fal-ai/veo3/image-to-video, google/veo3.1 on atlascloud, google/veo-3 and google/veo-3.1 on replicate, kie's veo-3-1, and Gemini's own veo-3.1-generate-preview) on generate_video, animate_image, generate_video_from_references or a TextToVideo node.
+---
+
+# Veo 3 → a directorial spec, not a description
+
+Veo 3 produces 4 to 8 second clips with synchronized audio: dialogue with
+lip-sync, ambient effects, environmental sound. It parses shot types, camera
+angles and film terminology accurately, and holds coherence across the frame
+sequence. What separates a usable clip from a generic one is writing the prompt
+as a spec rather than a narration.
+
+Reach it with `find_model` for `text_to_video` or `image_to_video`, then
+`generate_video` / `animate_image`; the reference-to-video routes take
+`generate_video_from_references`. Those forward the prompt, the media, a
+negative prompt (not `animate_image`), the duration, the aspect ratio and the
+resolution. The audio switch, `auto_fix`, the seed and an end frame for the
+first-last-frame routes exist only on the route's own node: find it with
+`search_nodes`, read its fields with `get_node_info`, and run it with
+`run_node`. Each run is a paid generation, so confirm the scope with the
+user before rendering several.
+
+The audio is per clip, so a piece cut from several Veo clips restarts its sound
+at every join. `video-audio-continuity` decides whether the scenes belong in one
+generation or under a track you add yourself.
+
+## Five elements, in order
+
+1. **Shot** — the camera work that frames everything else: medium shot,
+   close-up, wide angle, tracking shot.
+2. **Setting and atmosphere** — space, time, lighting quality, environment.
+3. **Subject** — enough visual detail to render consistently across frames.
+4. **Action** — the movement that defines the temporal progression.
+5. **Dialogue** (optional) — spoken lines, for anything needing lip-sync.
+
+> A medium shot frames a cartographer in a cluttered Victorian study. Warm
+> lamplight illuminates ancient maps spread across a mahogany table. The
+> cartographer, wearing round spectacles and a burgundy vest, traces a route
+> with his finger. "According to this sea chart, the lost island exists. We
+> sail at dawn."
+
+Each element builds on the one before it.
+
+## Parameters
+
+**Duration** decides how much temporal complexity fits. 4 seconds holds a
+single action — establishing shots, product showcases. 6 seconds holds a
+multi-stage action or brief dialogue. 8 seconds holds extended dialogue or an
+atmospheric moment. Longer durations spread attention across more frames, so
+per-frame detail density drops.
+
+**Aspect ratio** changes composition, not just framing. 16:9 matches the
+training distribution and composes horizontally. 9:16 concentrates the subject
+in a narrower horizontal band. 1:1 outpaints — the model extends the scene past
+what you described to fill the square, which can surface environment you never
+asked for.
+
+**Resolution**: iterate at 720p, deliver at 1080p.
+
+**Audio** is the cost lever. `generate_audio` defaults to true on fal and
+Replicate and to false on AtlasCloud's `google/veo3.1/*` and
+`google/veo3.1-fast/*`. The lite routes on AtlasCloud and Replicate and kie's
+`veo-3-1` have no audio switch. fal's guide says disabling it cuts the standard
+model to roughly half the price and the fast variant to about two thirds.
+Disable it only when a custom soundtrack is going on in post.
+
+## Cinematography vocabulary
+
+The model was trained on professional film content and reads the terms
+directly:
+
+- **Movement**: slow dolly forward, gentle pan left, crane shot descending,
+  handheld tracking.
+- **Shot types**: extreme close-up, Dutch angle, over-the-shoulder,
+  establishing wide.
+- **Lighting**: golden hour backlighting, harsh overhead fluorescents, dappled
+  forest light, volumetric fog rays.
+
+> A slow tracking shot follows a lone figure walking through fog-shrouded ruins
+> at twilight. Volumetric light rays pierce through broken archways, creating
+> dramatic god rays in the mist.
+
+**Sensory detail feeds the audio.** A prompt that describes neon reflecting in
+rain puddles, steam rising from food stalls and a vendor calling out over
+distant traffic gives the audio synthesis more to work with than the same scene
+described visually only.
+
+**Character consistency comes from distinctive markers.** "A woman in her
+thirties with auburn hair pulled back in a loose bun, wearing a charcoal
+peacoat and silver-rimmed glasses" holds identity across frames where "a woman"
+does not.
+
+## Auto fix
+
+`auto_fix` rewrites a prompt that trips content policy instead of rejecting
+it, trying to keep the intent. It defaults to true on fal's text-to-video
+routes (`fal-ai/veo3.1`, `/fast`, `/lite`) and to false on every fal
+image-to-video, first-last-frame, extend and reference route. AtlasCloud, kie
+and Replicate have no such field. Turn it off when your exact wording matters
+more than getting a clip back.
+
+## Errors and fixes
+
+- **Vague specification** — "a person walks in a city" constrains nothing.
+  Specify appearance, the character of the city, the time, the walk.
+- **Internal contradiction** — "bright sunny day with dramatic moonlight" fights
+  itself. Keep the environment consistent.
+- **Temporal overloading** — multiple scene transitions inside 8 seconds rarely
+  land. Split into discrete prompts.
+- **Unused negative prompt** — use it for "no camera shake", "no lens
+  distortion", "no text overlays". The lite routes on AtlasCloud and
+  Replicate, kie's `veo-3-1` and fal's reference-to-video routes have no
+  negative prompt.
+- **Ignored seed** — the seed is how a series holds a look. Record the ones
+  that worked. kie's `veo-3-1` and fal's reference-to-video routes have none.
+- **Prompt length** — fal's guide puts the working range at 150 to 300
+  characters, with generic output under 100 and unpredictable priorities over
+  400. The fal routes accept far longer prompts, so treat it as a style
+  target, not a limit.
+
+Symptoms map to fixes. Clothing colour shifting or facial features morphing
+means the subject needs more distinctive markers. Objects appearing without
+logical progression means the prompt is too complex for the duration — cut it
+down or shorten the clip. Dialogue out of sync with lips means the audio cue
+needs to be explicit: "a vendor loudly calls out 'Fresh fish!' while
+gesturing".
+
+## Working method
+
+Refine on the fast variant at 4 seconds and 720p, where a bad idea costs
+almost nothing. Move to the standard model, longer durations and 1080p only
+once the prompt is doing what you want. Then vary the seed to explore
+alternatives inside the same concept.
+
+Check what rendered with `analyze_video`, `detect_video_scenes` and
+`understand_video` instead of assuming.
+
+Adapted from fal's Veo 3 prompt guide:
+https://fal.ai/learn/devs/veo3-prompt-guide-master-google-video-generation