@letta-ai/letta-code 0.34.28 → 0.34.30

package/npm-shrinkwrap.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.28",
+  "version": "0.34.30",
   "lockfileVersion": 3,
   "packages": {
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5633,7 +5633,7 @@
     },
     "": {
       "name": "@letta-ai/letta-code",
-      "version": "0.34.28",
+      "version": "0.34.30",
       "dependencies": {
         "@cursor/sdk": "1.1.0",
         "@earendil-works/pi-ai": "^0.99.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.34.28",
+  "version": "0.34.30",
   "lettaStartupLogProtocol": 1,
   "lettaConfigDirProtocol": 1,
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",

package/scripts/run-api-integration-tests.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import {
   initializeModelCatalog,
   loadPersistedModelCatalog,
+  refreshModelCatalog,
 } from "@/agent/remote-model-catalog";
 import { getApiRequestConfig } from "@/backend/api/request";
 import { settingsManager } from "@/settings-manager";
@@ -12,10 +13,28 @@ import { settingsManager } from "@/settings-manager";
 // Warm it before parallel CLI startups so a failed refresh can use real data.
 const cacheDir = await mkdtemp(join(tmpdir(), "letta-api-test-catalog-"));
 process.env.LETTA_MODEL_CATALOG_CACHE_DIR = cacheDir;
+// This one-time warmup is the only network fetch the shard depends on before
+// any test runs, so a single slow response must not fail the whole shard.
+const WARMUP_ATTEMPTS = 4;
+const WARMUP_BACKOFF_MS = 3_000;
+
 try {
   await settingsManager.initialize();
-  await initializeModelCatalog();
   const { baseUrl } = await getApiRequestConfig();
+  for (let attempt = 1; ; attempt++) {
+    if (
+      (await refreshModelCatalog({ force: true })) ||
+      loadPersistedModelCatalog(baseUrl)
+    ) {
+      break;
+    }
+    if (attempt >= WARMUP_ATTEMPTS) break;
+    console.warn(
+      `Model catalog warmup attempt ${attempt}/${WARMUP_ATTEMPTS} failed; retrying`,
+    );
+    await Bun.sleep(WARMUP_BACKOFF_MS * attempt);
+  }
+  await initializeModelCatalog();
   if (!loadPersistedModelCatalog(baseUrl)) {
     throw new Error(
       "API integration catalog warmup did not persist a valid cache",

package/scripts/source-file-size-baseline.json

@@ -1,6 +1,6 @@
 {
   "src/agent/client-skills.test.ts": 1132,
-  "src/agent/memory-git.ts": 2013,
+  "src/agent/memory-git.ts": 2009,
   "src/backend/local-backend.test.ts": 2472,
   "src/backend/local/local-store.ts": 3260,
   "src/backend/pi-stream-adapter.test.ts": 1255,
@@ -36,7 +36,7 @@
   "src/tools/manager.ts": 2608,
   "src/tools/tool-execution-context.test.ts": 1092,
   "src/types/protocol_v2.ts": 2409,
-  "src/websocket/listen-client-concurrency.test.ts": 2548,
+  "src/websocket/listen-client-concurrency.test.ts": 2519,
   "src/websocket/listen-client-protocol.test.ts": 5664,
   "src/websocket/listener/commands/memory.ts": 1114,
   "src/websocket/listener/file-commands.ts": 1045,

package/skills/video-generation/SKILL.md

@@ -36,7 +36,25 @@ curl -sS "${LETTA_BASE_URL%/}/v1/videos/models" \
 
 Fields on each model worth knowing: `supported_resolutions`, `supported_aspect_ratios`, `supported_sizes`, `supported_durations` (often discrete like `[4,6,8]`, not a range), `supported_frame_images` (which `frame_type` values are accepted), `generate_audio` and `seed` (capability bools), `pricing_skus`, and `allowed_passthrough_parameters`. An out-of-set value returns a 400, so validate client-side.
 
-Models include `google/veo-3.1`, `bytedance/seedance-2.5`, `kwaivgi/kling-v3.0-pro`, `minimax/hailuo-3`, `minimax/hailuo-3-max`, and `heygen/avatar-iv` (a talking head from one photo); the models endpoint has the full list.
+## Choosing a model
+
+Recommendation as of 2026-10-29. Video models move fast, so this will go stale; public leaderboards such as [Artificial Analysis](https://artificialanalysis.ai/video/leaderboard/text-to-video) are one rough signal of what's newer, not a verdict. Only pick models that `/v1/videos/models` lists.
+
+- **Default, when quality matters and there's time:** `bytedance/seedance-2.5`. Top tier on the leaderboard, native audio, clips up to 30s. Renders take about 4–6 minutes.
+- **Fast:** `minimax/hailuo-3-max` (MiniMax H3). Also top tier; renders in well under a minute. Use it for quick replies in a live thread or for iterating on a prompt, then rerun the final cut on Seedance.
+- Other top-tier models on the endpoint include `alibaba/wan-3.0`, `black-forest-labs/flux-3-video` and `heygen/heygen-video-1`. Some providers filter prompts more strictly than others; if one rejects a prompt, try another model rather than rewording around the filter.
+- `heygen/avatar-iv` makes a talking head from one photo.
+
+## Writing the prompt
+
+For a single clip, read [references/cinematography.md](references/cinematography.md).
+For multiple shots or a sequence, read
+[references/storytelling.md](references/storytelling.md).
+
+For worked examples at the right level of detail, see
+[references/example-prompts.md](references/example-prompts.md).
+
+A timestamped shot list ending on the payoff helps multi-beat clips.
 
 ## Full workflow (drop-in)
 
@@ -44,8 +62,8 @@ Models include `google/veo-3.1`, `bytedance/seedance-2.5`, `kwaivgi/kling-v3.0-p
 #!/usr/bin/env bash
 set -euo pipefail
 
-PROMPT="a golden retriever playing fetch on a sunny beach"
-MODEL="google/veo-3.1"
+PROMPT="A golden retriever bounds across wet sand at golden hour to catch a tennis ball mid-air, spray flying off its fur. Low tracking shot at dog height, 35mm, shallow depth of field, warm backlight and lens flare, waves and the ball's thud in the audio. Ends on the dog trotting back toward camera, ball in mouth."
+MODEL="bytedance/seedance-2.5"
 OUTPUT="video-$(date +%Y%m%d-%H%M%S).mp4"
 base_url="${LETTA_BASE_URL%/}"
 

package/skills/video-generation/references/cinematography.md

@@ -0,0 +1,217 @@
+> Adapted from fal-ai-community/skills (https://github.com/fal-ai-community/skills, commit 9ca850412943251fc9a466c4c29fdaf7a303a3d8), MIT License per that repository's README. Changes: execution commands replaced with Letta's /v1/videos.
+
+# Cinematography
+
+Use this reference when the user needs cinematic direction, not generic "make it
+cinematic" prompting.
+
+Write concrete visual direction. Avoid empty prestige words and em dashes.
+
+## Inputs to collect
+
+Ask only for what affects the shot:
+
+- Subject and action.
+- Medium: still image, video, image-to-video, edit, storyboard frame.
+- Genre and mood.
+- Framing: close-up, medium, wide, overhead, POV, profile, locked-off.
+- Camera motion for video: push-in, dolly, tracking, handheld, crane, drone.
+- Lens feel: wide, normal, telephoto, macro, shallow or deep focus.
+- Lighting: natural, practical, studio, noir, high key, low key, backlit.
+- Output: aspect ratio, duration, first frame, last frame, download path.
+- Preferred model, if the user wants a specific cinematography model or
+  quality/cost profile.
+
+## Execution with Letta
+
+Call `/v1/videos` as described in `SKILL.md`. Pick a model from `SKILL.md`'s
+"Choosing a model" section and `/v1/videos/models`, and use only the controls
+that endpoint reports for the selected model.
+
+## Prompt build order
+
+Use the SCLCAM structure:
+
+1. Subject: who or what is in frame.
+2. Context: location, time, weather, story moment.
+3. Lens/framing: distance, angle, focal length feel, depth of field.
+4. Camera motion: only for video or if motion blur is desired.
+5. Atmosphere: haze, rain, practicals, reflections, texture.
+6. Mood/color: palette, contrast, grade, exposure style.
+7. Output controls: aspect ratio, duration, first-frame continuity.
+
+Example structure:
+
+```text
+[subject] in [context], framed as [shot size and angle], [lens feel],
+[lighting setup], [camera movement if video], [color grade], [texture],
+[duration or aspect ratio], [continuity constraints]
+```
+
+## Quality bar
+
+Before returning, check:
+
+- Camera movement is physically plausible for the scene.
+- Lens, shot size, and camera angle do not contradict each other.
+- Lighting direction is clear and consistent.
+- Color grade supports the mood without flattening subject detail.
+- Video prompt describes one shot unless the selected model supports multiple
+  prompts or shot lists.
+- Downloaded video comes from `/v1/videos/{id}/content`.
+
+If a result looks generic, improve specificity in camera, blocking, light, and
+environment before adding more adjectives.
+
+# Shot language reference
+
+## Shot sizes
+
+- Extreme close-up: one detail, texture, eye, hand, product edge.
+- Close-up: face or object detail with emotional focus.
+- Medium close-up: chest-up subject, useful for dialogue and portraits.
+- Medium shot: waist-up subject, body language visible.
+- Full shot: entire body or object, silhouette and stance readable.
+- Wide shot: subject inside environment.
+- Extreme wide: scale, isolation, worldbuilding, architecture.
+
+## Angles
+
+- Eye level: natural, direct, grounded.
+- Low angle: power, threat, awe.
+- High angle: vulnerability, surveillance, layout clarity.
+- Dutch angle: unease, instability. Use sparingly.
+- Over-the-shoulder: relationship, conversation, pursuit.
+- POV: subjective experience.
+- Profile: graphic composition, ritual, tension, fashion.
+
+## Camera movement
+
+- Slow push-in: attention, realization, premium product reveal.
+- Pull-back: isolation, context, reveal.
+- Dolly left or right: spatial discovery.
+- Tracking shot: follow action with continuity.
+- Crane up: scale reveal or emotional release.
+- Handheld: urgency, intimacy, instability.
+- Locked-off: control, deadpan, formalism, surveillance.
+- Orbit: product reveal, character inspection, heightened drama.
+- Macro glide: product texture, food, jewelry, electronics.
+
+## Composition
+
+- Centered symmetry: control, ritual, luxury, unease.
+- Rule of thirds: natural editorial composition.
+- Negative space: loneliness, premium ad copy area, tension.
+- Foreground obstruction: secrecy, surveillance, voyeurism.
+- Leading lines: architecture, movement, precision.
+- Frame within frame: confinement, observation, layered space.
+
+## Continuity language
+
+- "same subject and wardrobe as the reference"
+- "preserve product shape and label"
+- "continue from the uploaded first frame"
+- "single continuous shot"
+- "no cutaways"
+- "no time jump"
+- "same lighting direction throughout"
+
+# Lighting, lens, and color reference
+
+## Lighting setups
+
+- Soft key: flattering, commercial, calm.
+- Hard key: graphic, dramatic, fashion, noir.
+- Backlight: separation, glow, silhouette, premium edge.
+- Rim light: subject outline, product glass, metal highlights.
+- Practical light: lamps, signs, screens, candles in the scene.
+- Motivated light: light that has a visible or logical source.
+- Low key: dark frame, selective highlights, suspense.
+- High key: bright, low contrast, beauty, comedy, clean product work.
+- Top light: interrogation, overhead realism, harsh institutional mood.
+- Window light: natural, intimate, documentary.
+
+## Lens feel
+
+- 14-20mm wide: scale, distortion, kinetic interiors, action.
+- 24-28mm wide-normal: environmental realism, travel, documentary.
+- 35mm: natural cinematic perspective, street, lifestyle, narrative.
+- 50mm: classic portrait and product balance.
+- 85mm: compressed portrait, beauty, isolation.
+- 100mm macro: product detail, jewelry, food texture, eyes.
+- Telephoto compression: distance, surveillance, fashion runway.
+
+## Depth of field
+
+- Shallow focus: isolate subject, premium portrait, product hero.
+- Deep focus: environment and blocking stay readable.
+- Rack focus: attention shifts between two subjects or details.
+
+## Color and grade
+
+- Clean neutral grade: commercial, e-commerce, architecture.
+- Warm golden grade: nostalgia, comfort, luxury hospitality.
+- Cool cyan shadows: thriller, tech, night exterior.
+- Desaturated earth palette: realism, documentary, survival.
+- High contrast monochrome: noir, fashion, graphic product.
+- Pastel palette: beauty, wellness, light lifestyle.
+- Sodium vapor night: urban realism, tension.
+
+## Texture
+
+- Fine film grain: organic image, period mood.
+- Clean digital: tech, luxury, e-commerce, architecture.
+- Halation: glowing highlights, dream, night practicals.
+- Mist filter: soft bloom, romance, beauty.
+- Crisp high shutter: action clarity.
+- Motion blur: speed, energy, handheld realism.
+
+# Cinematography examples
+
+Use these as direction patterns. Replace subject, model fields, and output
+controls with the current task.
+
+## Noir close-up
+
+```text
+a detective sitting alone in a parked car at night, close-up from passenger
+seat angle, 50mm lens feel, rain streaks on the window in foreground, hard
+streetlight slashes across his face, low key noir lighting, deep shadows,
+muted green and amber grade, still frame, no text
+```
+
+## Product macro glide
+
+```text
+single continuous macro glide across the brushed steel edge of a luxury watch,
+100mm macro lens feel, black velvet surface, thin strip light reflected along
+the bevel, shallow depth of field, slow controlled camera movement, clean dark
+commercial grade, no extra text, no logo distortion
+```
+
+## Sci-fi wide shot
+
+```text
+small astronaut crossing a vast white salt flat toward a black monolith,
+extreme wide shot, low horizon, 24mm lens feel, late afternoon backlight,
+long shadow, minimal composition, cool silver color grade, quiet atmospheric
+haze, cinematic still, no extra ships
+```
+
+## Handheld pursuit
+
+```text
+8 second handheld tracking shot following a woman running through a narrow
+market alley at night, camera shoulder-height behind her, practical neon and
+food stall lights, motion blur on background, subject remains readable,
+urgent thriller pacing, one continuous shot, no cuts
+```
+
+## Warm interior drama
+
+```text
+two siblings at a kitchen table after midnight, medium-wide static frame,
+35mm lens feel, warm practical lamp on table, cool moonlight through window,
+subtle haze, quiet tension, naturalistic color grade, deep focus enough to
+read both faces, no melodramatic poses
+```

package/skills/video-generation/references/example-prompts.md

@@ -0,0 +1,55 @@
+# Example prompts
+
+Strong text-to-video prompts from model pages on fal.ai, quoted as published. Each link is the page the prompt came from. Use them as models of the level of detail that works: subject, materials, light, camera, lens, palette, timing, sound, on-screen text, and what to exclude.
+
+## Single-shot still life: no people, light-driven
+
+Source: [Seedance 2.5 text-to-video on fal](https://fal.ai/models/bytedance/seedance-2.5/us/text-to-video)
+
+```text
+Editorial still life for a luxury perfume brand, no people or hands in frame. A single heavy-based glass bottle with a faceted amber-tinted body and a brushed brass cap, standing on a slab of honed travertine against a warm sand-toned plaster wall. Beside it, a low-profile companion object for scale — a folded cream linen card embossed with the brand mark and a single dried sprig of eucalyptus resting on the stone. A slow drip of liquid catches the light on the bottle's shoulder. Hard, directional late-afternoon sunlight from the right rakes across the scene, casting a long, sharp bottle shadow and a bright caustic refraction on the wall behind it; a soft secondary bounce lifts the shadow side. Palette of amber, ivory, warm grey, and dull gold. Eye-level camera, slight three-quarter angle to the bottle, generous negative space above and to the left for type, medium-format look, 90mm lens, shallow but controlled depth of field, subtle film grain. Quiet, architectural, restrained, tactile, with the light doing the storytelling
+```
+
+## Character action with a timed beat
+
+Source: [MiniMax H3 Max text-to-video on fal](https://fal.ai/models/minimax/h3-max/text-to-video)
+
+```text
+An aging warrior-monk in scorched ceremonial armor, a split ceramic mask and a humming prayer-band on his forearm + 0–4s: climbs silently along a cliffside terrace as insect-like surveyor drones comb the sun-bleached ruins, standing alone under as the camera rises over the ruined monastery. Sun-blasted post-apocalyptic sci-fi action, dust, heat haze, practical debris, sweeping crane tracking, silence broken only by wind.
+```
+
+## Kinetic typography with timestamped sections
+
+Source: [H3 Max Turbo text-to-video on fal](https://fal.ai/models/minimax/h3-max-turbo/text-to-video)
+
+```text
+0.00–2.50
+Warm ivory background.
+Large black text: **H3 MAX TURBO.**
+Text slides in fast from the left with a clean ease-out. A thin red line grows underneath it. On the beat, the whole composition compresses slightly and snaps back.
+
+2.50–5.50
+The red line extends across the screen and becomes a crop transition.
+Reveal huge stacked text:
+
+**FASTER**
+**THAN REAL TIME.**
+
+Use aggressive kinetic typography: large scale, edge cropping, fast horizontal movement, strong black/ivory/red composition. Keep the text sharp when it lands.
+
+STYLE
+Premium 2D motion design with very subtle 2.5D card depth. Swiss editorial typography mixed with energetic commercial motion graphics. Warm ivory, black and vermilion red. Large type, strong cropping, fast masks, cards, lines, parallax, precise easing, short motion blur only during transitions. No full 3D scenes, no UI, no particles, no random objects, no glitches, no letter-by-letter animation.
+
+"fal" must always be lowercase.
+```
+
+## Period commercial with dialogue and an overlay
+
+Source: [FLUX 3 Max text-to-video on fal](https://fal.ai/models/blackforestlabs/flux-3-max/text-to-video)
+
+```text
+1985 TV beer commercial, 35mm film grain, golden-hour sunset. One continuous slow push-in on a weathered cowboy leaning against a ranch porch rail, his horse tied up behind him. He pulls an ice-cold Lone Star from a cooler, cracks it open with a hiss, takes a long sip, and turns to camera with a tired grin. Warm amber tones, soft lens flare, slide guitar soundtrack.
+Narrator (deep, gravelly): "Sunup to sundown, [pauses], he's earned every drop."
+Cowboy (raising the bottle): "Now this is quittin' time."
+Overlay: Lone Star logo fades in over the final frame.
+```

package/skills/video-generation/references/storytelling.md

@@ -0,0 +1,269 @@
+> Adapted from fal-ai-community/skills (https://github.com/fal-ai-community/skills, commit 9ca850412943251fc9a466c4c29fdaf7a303a3d8), MIT License per that repository's README. Changes: execution commands replaced with Letta's /v1/videos.
+
+# Storytelling
+
+Use this reference when the user wants a sequence, not a single asset.
+
+The goal is to produce clear story beats and executable video generation. Avoid
+generic inspiration copy, fake dialogue, and em dashes.
+
+## Inputs to collect
+
+Ask only when missing information affects execution.
+
+- Format: ad, short film, music video, documentary, tutorial, social story.
+- Duration and aspect ratio.
+- Number of shots or allowed range.
+- Main subject, character, product, or location.
+- Continuity anchors: character, product, wardrobe, environment, color.
+- Source media: first frame, reference image, product shot, audio track.
+- Audio needs: narration, music, sound design, transcript, no audio.
+- Preferred model or model family, if the user wants to decide quality, cost,
+  speed, audio, or multi-shot tradeoffs.
+
+## Execution with Letta
+
+Call `/v1/videos` as described in `SKILL.md`. Pick models from `SKILL.md`'s
+"Choosing a model" section and `/v1/videos/models`, and use only the sequence,
+reference, audio, and timeline controls that endpoint reports for each selected
+model. Generate clips separately when the selected model supports only one
+prompt, and do not claim they are stitched unless a model or another tool
+actually stitched them.
+
+## Shot planning
+
+Plan every sequence as beats first:
+
+1. Hook: immediate visual reason to keep watching.
+2. Setup: who, what, where, and why it matters.
+3. Development: movement, discovery, proof, or escalation.
+4. Turn: reveal, transformation, result, or emotional change.
+5. Close: final image, product memory, CTA-safe frame, or unresolved mood.
+
+For each shot, write:
+
+- Shot number and duration.
+- Story purpose.
+- Visual prompt.
+- Continuity anchor.
+- Input reference, if any.
+- Letta video model.
+- Expected output path.
+
+## Prompt build order
+
+Use this structure for each shot:
+
+```text
+SHOT [number], [duration]:
+[story purpose]. [subject and action]. [location and time]. [camera framing].
+[camera movement]. [lighting and color]. [continuity anchor]. [transition or
+relationship to previous shot].
+```
+
+Keep one shot to one clear action unless the selected model supports multi-shot
+or timeline prompting.
+
+## Quality bar
+
+Before returning:
+
+- Shot order has a clear narrative function.
+- The first shot is strong enough for the platform.
+- Continuity anchors are repeated without bloating every prompt.
+- Camera motion is varied but not random.
+- Durations add up to the requested runtime.
+- Async request IDs and downloaded files are recorded.
+- The model's actual schema, not assumptions, drove the final command.
+
+# Shot planning reference
+
+## Basic sequence shapes
+
+## 15 second social ad
+
+| Shot | Time | Purpose | Visual role |
+| --- | --- | --- | --- |
+| 1 | 0-2s | Hook | striking product or problem image |
+| 2 | 2-6s | Context | product in use or character reaction |
+| 3 | 6-11s | Proof | feature, texture, process, result |
+| 4 | 11-15s | Close | memorable final frame with safe space |
+
+## 30 second commercial
+
+| Shot | Time | Purpose | Visual role |
+| --- | --- | --- | --- |
+| 1 | 0-3s | Hook | image that defines the world |
+| 2 | 3-7s | Product or hero | show subject clearly |
+| 3 | 7-13s | Benefit | action, feature, transformation |
+| 4 | 13-20s | Lifestyle or proof | real context, emotion, result |
+| 5 | 20-27s | Escalation | strongest beauty or motion shot |
+| 6 | 27-30s | End frame | clean brand-safe final composition |
+
+## Short cinematic scene
+
+| Shot | Purpose |
+| --- | --- |
+| Establishing | where the scene happens and mood |
+| Character reveal | who matters |
+| Action beat | what changes |
+| Reaction | emotional consequence |
+| Detail insert | object, clue, texture, proof |
+| Resolution | new state or unanswered tension |
+
+## Continuity anchors
+
+Character anchor:
+
+```text
+same character face, hair, wardrobe, age, posture, and style as the approved
+reference
+```
+
+Product anchor:
+
+```text
+same product shape, color, packaging, logo placement, and material as the
+reference
+```
+
+Location anchor:
+
+```text
+same room layout, window direction, color palette, and time of day
+```
+
+Motion anchor:
+
+```text
+single continuous shot, starts where previous shot ended, no time jump
+```
+
+## Pacing guidance
+
+- Fast: 1-3 second shots, strong motion, clear graphic frames.
+- Medium: 3-6 second shots, product demos, lifestyle, dialogue-like scenes.
+- Slow: 6-10 second shots, luxury, drama, architecture, atmosphere.
+- Variable: fast hook, slower proof, strong final frame.
+
+# Storytelling workflows
+
+## Native multi-prompt sequence
+
+Use only when the model supports multiple prompts, shot arrays, scenes,
+timeline, or keyframe-like fields.
+
+1. Inspect the model and identify the exact multi-shot fields.
+2. Convert the story into concise shot prompts.
+3. Keep one continuity anchor outside the repeated shot details if the model
+   supports a global prompt.
+4. Run async and download the completed result.
+5. Check whether the model returned one video or per-shot files.
+
+## Manual per-shot video
+
+Use when the model supports only one shot at a time.
+
+1. Create a shot table.
+2. Generate or upload a reference frame for each shot.
+3. Run each shot with unique output paths.
+4. Record model, request id, prompt, local output path, and defects.
+5. Return clips in timeline order. Do not claim they are stitched unless they
+   are actually stitched by the model or another tool.
+
+## First-frame to last-frame
+
+1. Generate or choose the opening frame.
+2. Generate or choose the target final frame.
+3. Supply both frames if supported.
+4. Inspect the model for accepted first/last frame fields.
+5. Prompt the transition as one physical motion or transformation.
+6. Run async and download.
+
+## Character narrative
+
+1. Write the character anchor (see "Continuity anchors" above) and generate an approved still of the character to reuse.
+2. Build shot variables around action, expression, and location.
+3. Use image-to-video from approved stills when identity drift matters.
+4. Compare each result to the anchor before advancing to the next shot.
+
+## Product narrative
+
+1. Write the product anchor (see "Continuity anchors" above): shape, color, packaging, logo placement, material.
+2. Plan the sequence around hook, feature, context, proof, final frame.
+3. Use the same product reference for every shot if the model allows it.
+4. Keep motion modest when packaging fidelity matters.
+
+## Audio narrative
+
+1. Choose a model with narration, music, or sound generation support.
+2. Use the model's supported audio controls.
+3. Use transcript or beat timing to set shot durations.
+4. Return audio path and visual clip paths separately unless a model produces
+   combined audio-video output.
+
+# Storytelling examples
+
+These examples show planning density and prompt tone. Adapt to the user's model
+and references.
+
+## 15 second coffee social ad
+
+| Shot | Duration | Prompt |
+| --- | --- | --- |
+| 1 | 2s | macro close-up of espresso crema swirling in a glass cup, warm morning window light, shallow focus, immediate sensory hook |
+| 2 | 4s | same coffee cup placed beside a small bag of beans on a clean kitchen counter, slow push-in, product and texture readable |
+| 3 | 5s | hand pours milk into the coffee, soft cloud bloom, controlled motion, warm lifestyle lighting, no text |
+| 4 | 4s | final hero frame of cup and beans with clean negative space on right for copy, calm premium breakfast mood |
+
+Execution note: generate still or video per shot unless the selected model
+supports a prompt list.
+
+## 30 second architecture brand film
+
+| Shot | Duration | Purpose |
+| --- | --- | --- |
+| 1 | 4s | dawn exterior of a modern house, wide static frame, warm interior lights |
+| 2 | 5s | slow tracking shot along concrete wall and timber detail, tactile proof |
+| 3 | 5s | architect's hand sketches over plan, natural desk light, human process |
+| 4 | 6s | family crosses the living room, soft backlight, space feels livable |
+| 5 | 6s | crane up from courtyard to roofline, shows scale and geometry |
+| 6 | 4s | quiet final exterior with empty safe space for brand mark |
+
+Continuity anchor:
+
+```text
+same house, same material palette of warm timber, pale concrete, black steel
+frames, and soft morning light
+```
+
+## Cinematic reunion scene
+
+| Shot | Duration | Prompt |
+| --- | --- | --- |
+| 1 | 5s | empty train platform in blue hour rain, wide locked-off frame, practical lights reflected on wet ground |
+| 2 | 4s | close-up of woman noticing someone off screen, same coat and hairstyle, soft backlight, restrained emotion |
+| 3 | 4s | medium shot of man stepping from train doorway, matching eyeline, cool station light |
+| 4 | 5s | slow tracking two-shot as they walk toward each other, shallow depth of field, no crowd distraction |
+| 5 | 6s | close hands meeting, rain on sleeves, quiet emotional detail |
+| 6 | 6s | wide final frame of both under station clock, warm practical light, unresolved calm |
+
+## Product launch sequence
+
+```text
+SHOT 1, 3s:
+black screen opens to a thin rim light tracing the product silhouette, centered
+macro frame, premium suspense, no text.
+
+SHOT 2, 4s:
+slow orbit reveals the product material and main contour, controlled studio
+reflections, same product shape and logo placement as the reference.
+
+SHOT 3, 5s:
+close-up of the key feature in use, clean hand interaction, product remains
+sharp, no fake labels.
+
+SHOT 4, 3s:
+final hero composition on simple surface with large negative space for copy,
+brand-safe end frame, no generated text.
+```