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

package/dist/_skills/game-direction/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: game-direction
+description: "Set the feel, level pacing, and art direction before building or revising a native game. Use for a new game, a showcase, a visual overhaul, or a game that plays correctly but feels flat. Pairs with native-game, which owns every tool and schema contract."
+---
+
+# Direct a native game
+
+Lock a short direction spec before the first game edit or asset generation.
+State the spec in the conversation, then build within the requested scope.
+For an existing game, read it and preserve its established direction unless
+the brief asks for a change. `native-game` owns the tool and schema contracts.
+
+## Direction spec
+
+| Decision | Record before building |
+|---|---|
+| Player promise | The action that should feel satisfying, the challenge, and the observable win condition |
+| Style string | One exact reusable string naming medium, palette, edge treatment, lighting, and texture |
+| Layer plan | Sky, far background, midground, play layer, and foreground, with their depth, contrast, and parallax |
+| Feel parameters | Movement speed, acceleration and braking, jump height and duration, coyote ticks, buffer ticks, and feedback timing |
+| Pacing sheet | Ordered teaching beats, their safe practice area, challenge, recovery, and finish |
+| Asset plan | Hero poses, aligned frames, terrain edge variants, effects, sound cues, music, and fonts |
+| Proof route | Start scene, required targets, win signal, expected duration, and captures at the teaching beat and hardest section |
+
+For a small prototype, keep each row to one sentence and use only the layers
+and assets the brief needs. The jump, coyote and layer rows assume a side-view
+platformer. For a top-down game (the 2D default), record movement speed,
+acceleration, braking and facing instead of jump rows, and replace the depth
+layers with ground, props, overhead decoration and lighting. For a 3D
+exploration game, record the controller speed, jump, follow-camera offset
+and pitch limits, and plan sky, lighting and landmarks instead of parallax layers.
+A showcase needs a visible depth plan and a finished art pass. Load
+`native-game` for the build loop, `native-game-reference` for the document
+fields, and `list_example_games` and `get_example_game` for shipped references. Study Kindle for a platformer
+with animated poses, terrain edges, parallax, lights, sound cues, and a grade.
+Use its decisions as a benchmark for the brief, without copying its theme.
+
+## One style string
+
+Repeat the locked style string verbatim in every visual prompt. Add the asset's
+role, dimensions, framing, and transparency requirements after that string.
+Pass one installed style reference as `reference_slot` on `generate_game_asset`
+when the selected model accepts an input image.
+Changing the palette or edge treatment for one asset requires updating the
+spec and the related assets.
+
+Keep the player's silhouette readable against the play layer. Background
+contrast and detail should fall with distance. Foreground decoration must leave
+hazards and landing surfaces visible. Check the composition at the target
+screen size, including touch controls and HUD.
+
+## Game feel
+
+Measure timings in ticks at the engine's 60 Hz rate. For a side-view prototype,
+start with 6–8 coyote ticks and 6–8 buffer ticks, then tune them against the
+actual level. Coyote time permits a jump shortly after leaving support. A jump
+buffer remembers a press shortly before landing. Implement these in persistent
+script state using `entity.touching.down` and `justPressed`.
+
+Set jump velocity and gravity from the intended height and airtime. Holding
+jump may preserve ascent while release cuts it. Make braking fast enough to
+land on the narrowest required platform. Decide whether air steering and wall
+jumps are part of the game before laying out challenges that need them.
+
+Give an action a clear response. A jump can use a pose change, a sound cue, and
+a brief dust puff. A landing can compress the sprite, then restore it. A hit
+needs an immediate flash or recoil and a clear recovery window. Keep squash,
+stretch, and screen effects visual so the collider remains predictable. Use
+`setVisual`, animation clips, particles, and event-driven audio through the
+contracts in `native-game`. Avoid repeated camera motion that obscures a jump.
+
+## Level pacing
+
+Write the pacing sheet before placing the level. Each row identifies the
+mechanic, what the player sees before committing, and where a failed attempt
+returns them. Introduce a mechanic in safety, ask for one clear use, then
+combine it with an earlier mechanic. Put recovery after a demanding section.
+Keep checkpoints near the section they protect and make their activation
+visible and audible.
+
+Place the first required target where normal play teaches movement. Show the
+next landing or objective before asking for a blind commitment. Optional
+collectibles can reward risk, but the win route must remain readable without
+them unless collection is the stated objective. Test the narrowest clearance,
+longest jump, moving platform timing, and respawn state individually.
+
+## Finish and proof
+
+Obtain the proof route with autoplay or a written route, replay it, and
+assert the win as `native-game` § Build and revise describes. For a custom
+scripted goal, assert the game's own victory signal, not only a target contact.
+
+Capture the start, a representative play section, the busiest frame, and the
+finish using the proof route. Captures return image refs, so call
+`view_image` on each frame before judging it. Inspect the images against the
+locked layer plan, silhouette contrast, terrain joins, foot alignment, HUD, lighting, and grade.
+Schema validation proves structure. An executed route proves that route can
+reach its observed target. Visual quality requires inspecting the rendered
+frames. Report which of these checks passed and what remains unverified.

package/dist/_skills/gpt-image-2-prompting/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: gpt-image-2-prompting
+description: Prompt OpenAI's GPT Image 2 — the five-slot Scene/Subject/Details/Use case/Constraints template it responds to, the change-versus-preserve shape for edits, labelled multi-image compositing, and how to get text on an image to render verbatim. Use whenever the model id contains gpt-image-2 (openai/gpt-image-2, openai/gpt-image-2/edit, openai/gpt-image-2/text-to-image, kie's gpt-image-2-text-to-image and gpt-image-2-image-to-image) on generate_image, edit_image or a TextToImage node. Not for GPT Image 1, 1-mini, 1.5 or 2.5.
+---
+
+# GPT Image 2 → five slots, in order
+
+The model responds to structure: scene, subject, specific details, intended
+artifact, constraints, in that order, with line breaks between sections once
+the prompt runs past a short paragraph. Everything else sits on top of that
+spine.
+
+Reach it with `find_model` for `text_to_image` or `image_to_image`, then
+`generate_image` / `edit_image`. `generate_image` forwards only the prompt, a
+negative prompt, the size and a quality string, and `edit_image` only the
+images, the prompt, a negative prompt, a target size and a strength. Output
+format and `background` 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`.
+
+## The template
+
+```
+Scene:
+[where this happens, time of day, background, environment]
+
+Subject:
+[who or what is the main focus]
+
+Important details:
+[materials, clothing, texture, lighting, camera angle, lens feel, composition, mood]
+
+Use case:
+[editorial photo / product mockup / poster / UI screen / infographic / concept frame]
+
+Constraints:
+[no watermark / no logos / no extra text / preserve face / preserve layout]
+```
+
+Five slots, five problems people usually blur together: where the image exists,
+what it is about, what must be visible, what kind of finished artifact you
+want, and what must not drift. The fifth is where mediocre prompts fail
+silently — describe the idea without bounding it and the model gets inventive
+in directions you will regret.
+
+Filled in:
+
+```
+Scene:
+A quiet classical museum gallery in soft afternoon light.
+
+Subject:
+A woman in her 30s standing casually in front of a large oil painting.
+
+Important details:
+Natural smile, realistic skin texture, beige knit sweater, dark jeans, white
+sneakers, eye-level full-body framing, marble floor reflections, warm neutral
+colour balance, shallow depth of field, believable indoor ambient light.
+
+Use case:
+Editorial lifestyle photograph.
+
+Constraints:
+No watermark, no logos, no extra people in the foreground, no heavy retouching.
+```
+
+## Rules
+
+1. **Visual facts over vague praise.** Drop stunning, incredible, epic,
+   masterpiece, insane detail. Use overcast daylight, brushed aluminium,
+   chipped paint, clean kerning, 50mm feel, soft bounce light, worn canvas.
+2. **Style tags need visual targets.** "Minimalist brutalist editorial luxury
+   premium" is noise. "Cream background, heavy black condensed sans serif,
+   asymmetrical type block, one hero object, generous negative space, studio
+   tabletop lighting" is a layout.
+3. **Say the real thing.** Transit kiosk. Boarding pass. Preserve the face.
+   Mood language buries the brief.
+4. **Separate change from preserve in edits.** "Change only X", "keep
+   everything else the same", and repeat the preserve list on every pass.
+5. **Treat text as typography.** Wrap literal copy in quotes or ALL CAPS, mark
+   it EXACT TEXT, and specify font class, size, colour and placement. Add "no
+   extra words" and "no duplicate text".
+6. **One revision per turn.** Small iterative edits beat one giant rewrite.
+
+## Three modes
+
+**Generate from scratch** — the five-slot template above. One clean pass lands
+believable mundane realism once the prompt locks the lighting, the camera
+behaviour and the environment details.
+
+**Edit one image** — two columns, plus a physical-realism line:
+
+```
+Change:
+Replace the parked car with a vintage bicycle.
+
+Preserve:
+The house, fence, driveway concrete, landscaping, lighting direction, and time
+of day, exactly.
+
+Constraints:
+Match the bicycle's scale and shadow pattern to the existing scene. No extra
+objects, no redesign, no watermark.
+```
+
+The preserve list carries the edit. Inventory what must stay — awning, brick
+facade, mullions, reflections, sidewalk, every person on it — and the edit
+stays in scope.
+
+**Combine multiple images** — label every input by role and reference the
+labels in the instruction. fal's edit route and kie's image-to-image route take
+up to 16 reference images; the other routes state no cap.
+
+```
+Image 1: base scene to preserve.
+Image 2: jacket reference.
+Image 3: boots reference.
+
+Dress the person from Image 1 using the jacket from Image 2 and the boots from
+Image 3. Preserve the face, body shape, pose, background, lighting, and framing
+from Image 1. Fit the garments naturally with realistic folds, drape, occlusion
+and contact shadows. No extra accessories.
+```
+
+Unlabelled inputs make the model guess which image is content and which is
+reference, and it guesses wrong.
+
+## What it is good at
+
+- **Photoreal editorial.** Describe the photograph, not the fantasy: lens,
+  framing, time of day, light source, surface wear, an ordinary background
+  detail, one believable imperfection.
+- **Product.** Material accuracy, lighting consistency, label fidelity. A flat
+  inventory of physical objects plus one piece of print that must stay legible
+  is the entire recipe.
+- **UI and screenshots.** Name the screen type, the hierarchy, the exact copy,
+  the state, and the layout logic. "Clean survival HUD along the bottom,
+  believable UI spacing" does the layout work; remove those clauses and the HUD
+  collapses into noise.
+- **Text in image.** Give the copy verbatim, then typography, then layout, then
+  "render the text verbatim / no extra words / no duplicate text". For a still
+  that will sit on a timeline or seed a video clip, leave the copy off and add
+  it as a text clip afterwards (`caption-titles`) so it stays editable.
+- **Style transfer.** "Same style" is not enough. Name the parts: chunky pixel
+  forms, limited arcade palette, bright glow accents, clean silhouette edges.
+- **Drawing to photo.** Say whether the drawing is a suggestion or a contract:
+  "preserve the exact layout, horizon line, proportions, river path, mountain
+  placement, tree placement, and overall perspective".
+- **Character consistency.** First prompt establishes the anchor. Second prompt
+  repeats the anchor details verbatim and adds "do not redesign the character".
+
+Transparency needs a route with a `background` field set to `transparent`:
+kie's (only at 1K resolution, per its field note) or Replicate's
+`openai/gpt-image-2`, with PNG or WebP output. The fal and AtlasCloud routes
+have no `background` field.
+
+Check the render rather than assuming it: `critique_image`, or
+`score_image_adherence` when the prompt has copy or a layout to hold.
+
+Adapted from fal's GPT Image 2 prompting guide:
+https://fal.ai/learn/tools/prompting-gpt-image-2

package/dist/_skills/hailuo-prompting/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: hailuo-prompting
+description: Prompt MiniMax's Hailuo video line — the chronological beat order it animates from, the fifteen bracketed camera commands the Director endpoints accept and the three-per-bracket rule, when to switch prompt_optimizer off, why there is no negative prompt to fall back on, and prompting the delta on image-to-video. Use whenever the model id names Hailuo or MiniMax video-01 (fal-ai/minimax/hailuo-2.3/pro/text-to-video, fal-ai/minimax/hailuo-02/pro/image-to-video, fal-ai/minimax/hailuo-02-fast/image-to-video, fal-ai/minimax/video-01-director, fal-ai/minimax/video-01-subject-reference, hailuo/2-3-image-to-video-pro, minimax/hailuo-2.3, minimax/hailuo-02-fast, and the direct MiniMax provider's MiniMax-Hailuo-2.3, MiniMax-Hailuo-02, T2V-01-Director, I2V-01-Director and S2V-01) on generate_video, animate_image, generate_video_from_references or a TextToVideo node. Not for MiniMax H3, which has its own guide.
+---
+
+# Hailuo → a sequence of beats, in order
+
+Hailuo animates the order it reads. It has no negative prompt, no shot list and
+no CFG dial, so every control you get is in the wording: what happens, in what
+order, and how the camera behaves while it happens. Clips run 6 or 10 seconds
+(10 s is unavailable at 1080p on Hailuo 02).
+
+Reach it with `find_model` for `text_to_video` or `image_to_video`, then
+`generate_video` / `animate_image`. Those forward only the prompt (and the
+image), the duration, the aspect ratio and the resolution. `prompt_optimizer`
+exists 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`.
+
+## Write the action as beats
+
+Break one motion into the beats it is made of and connect them with sequencing
+words — first, then, as, finally. The model animates that order.
+
+> A skateboarder rolls toward a handrail in an empty underground car park.
+> First he crouches low over the deck, then he pops the tail and the board
+> snaps up under him, and as he lands on the rail the trucks grind along the
+> steel, sparks trailing behind. Finally he drops off the end and rolls out of
+> frame past a pillar.
+
+Compare "a skateboarder does a trick on a rail", which gives the model the
+whole choreography to invent and no reason to resolve it the way you meant.
+
+Emotional beats work the same way. "She reads the letter with growing concern,
+tears well up, then she crumples the paper and throws it" is three animatable
+states; "she is sad about the letter" is one adjective.
+
+## Camera
+
+On the Director endpoints (`video-01-director` and its image-to-video form,
+and MiniMax's own `T2V-01-Director` and `I2V-01-Director`), camera moves are
+commands in square brackets. Fifteen are supported:
+
+`[Truck left]` `[Truck right]` `[Pan left]` `[Pan right]` `[Push in]`
+`[Pull out]` `[Pedestal up]` `[Pedestal down]` `[Tilt up]` `[Tilt down]`
+`[Zoom in]` `[Zoom out]` `[Shake]` `[Tracking shot]` `[Static shot]`
+
+Two placement rules carry all of it. Commands inside one bracket happen at the
+same time, capped at three: `[Truck left, Pan right, Zoom in]`. Commands at
+different points in the prompt happen in that order:
+
+```
+[Static shot] The chef sets the plate down under the pass light. [Push in]
+He wipes the rim with a cloth, then looks up. [Tilt up, Pan right] The dining
+room comes into view behind him.
+```
+
+The bracket contract is documented for the Director endpoints only, so on
+every other Hailuo endpoint write camera direction as prose — "a slow tracking
+shot follows her", "the camera racks focus from the leaves to her face".
+
+## prompt_optimizer
+
+It rewrites your prompt with an LLM before generation. It defaults to true on
+every fal and Replicate Hailuo and video-01 route and to false on kie's Hailuo
+02 routes. kie's Hailuo 2.3, the AtlasCloud routes and the direct MiniMax video
+models have no such field. Leave it on for a short prompt: it fills in the
+detail you did not write. Switch it off once your prompt is a deliberate brief
+— it will otherwise rewrite away the specific wardrobe, the specific light, and
+the beat order you just spent effort on.
+
+## Image to video
+
+The frame is already decided. Prompt only what changes: motion, camera, light
+over time, environment animation. Naming the subject briefly to anchor the
+reference is fine — "the red-haired woman turns slowly to face camera" — but a
+paragraph re-describing the still is a paragraph not spent on the delta.
+
+Keep the framing consistent with the source. Asking a close-up input for a wide
+establishing move is how you get a hallucinated body.
+
+`video-01-subject-reference` (and MiniMax's own `S2V-01`, reached through
+`generate_video_from_references`) holds a face across the clip from one
+reference image; describe the person's action, not their appearance.
+
+## No negative prompt
+
+There is no field, and "no text, no watermark, not blurry" in the prompt is
+read as content. Say what should be there instead. Empty sky, not "no birds".
+A bare concrete wall, not "no graffiti".
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| The action resolves in the wrong order | Number the beats with first / then / as / finally |
+| The camera drifts | Use a bracketed command on a Director endpoint, or name the move in prose |
+| Your specifics disappeared | Set `prompt_optimizer` false on the route's node |
+| A body appears where the input image was cropped | Match the prompt's framing to the input |
+| The thing you excluded shows up anyway | Rewrite the exclusion as a positive description |
+
+Grade the render with `analyze_video` and `detect_video_scenes`, and
+`understand_video` when you need a written read of what landed.
+
+Adapted from MiniMax's camera-movement contract as documented on the fal
+Director endpoints, and Akool's Hailuo prompt guide:
+https://fal.ai/models/fal-ai/minimax/video-01-director/api
+https://akool.com/blog-posts/minimax-hailuo-video-prompt-guide

package/dist/_skills/kling-video-prompting/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: kling-video-prompting
+description: Prompt Kuaishou's Kling video line from 2.5-turbo onward — which version exposes a shot list, tagged elements, native audio and a CFG dial at all, one shot per entry in multi_prompt rather than one paragraph, characters tagged @Element1/@Element2 so a face survives a cut, the labelled dialogue format native audio lip-syncs to, a negative prompt aimed at the artifacts Kling actually produces, and what motion-control takes instead of a prompt. Use whenever the model id names Kling 2.5-turbo, 2.6, v3, O1 or O3 (fal-ai/kling-video/v3/pro/text-to-video, fal-ai/kling-video/o3/pro/reference-to-video, fal-ai/kling-video/v2.6/pro/image-to-video, kling-3.0-omni/text-to-video, kling-2.6/text-to-video, kwaivgi/kling-v3.0-pro, kwaivgi/kling-video-o3-pro, kwaivgi/kling-o1) on generate_video, animate_image, generate_video_from_references or a TextToVideo node. Not for Kling 1.x, 2.0 or 2.1, and not for Kling Image.
+---
+
+# Kling → write shots, not paragraphs
+
+The newer Kling versions take a shot list rather than a prompt: one call
+carries several shots, generates native audio with lip sync, and holds a tagged
+character across every cut. A single dense paragraph throws all three away and
+comes back as one drifting take.
+
+Which of those you get depends on the version and on the provider, so check
+the route before you write. On fal:
+
+| Version (fal) | Shot list | Tagged elements | Native audio (`generate_audio`) | cfg_scale / negative prompt |
+| :--- | :--- | :--- | :--- | :--- |
+| 2.5-turbo | — | — | — | yes |
+| 2.6 | — | — | on by default | negative prompt; `cfg_scale` on text-to-video only |
+| O1 | — | reference and video-to-video routes | — | — |
+| v3 | yes | image-to-video routes | on by default | yes |
+| v3 turbo | `multi_prompt` only | — | — | — |
+| O3 | yes | reference and video-to-video routes | **off** by default | — |
+
+The other providers name and default the same controls differently:
+
+- **kie** — audio is `sound` (default false) on `kling-2.6/*` and
+  `kling-3.0/video`, and `audio` (default false) on `kling-3.0-omni/*`.
+  `kling-3.0/video` takes `multi_shots` with up to 12 `multi_prompt` entries
+  and up to 3 `kling_elements`. The omni routes take `customize_multi_shots` /
+  `prefer_multi_shots`, up to 6 `multi_prompt` entries, and `elements`.
+  `kling/v3-turbo-*` takes only a prompt and a duration.
+- **AtlasCloud** — audio is `sound`, on by default except on the O3
+  reference-to-video routes. There is no `multi_prompt`: the shot switch is
+  `multi_shot` with `shot_type` `customize` or `intelligence`. `cfg_scale` and
+  `negative_prompt` exist on v2.6 and v3.0, not O3. `kling-v3.0-turbo/*` takes
+  only a prompt and a duration.
+- **Replicate** — `generate_audio` is off by default on `kling-v3-video` and
+  `kling-v3-omni-video`, and on by default on `kling-v2.6`.
+
+Native audio belongs to the call that made it. Several separately generated
+clips cut together drop their sound at each join — `video-audio-continuity`
+covers the two builds that avoid it.
+
+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` with `find_model` for `reference_to_video`;
+it sends plain reference images and videos, not tagged elements. Those tools
+forward the prompt (and the media), a negative prompt (not `animate_image`),
+the duration, the aspect ratio and the resolution. The shot list, `elements`,
+`cfg_scale`, the audio switch and an end frame 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.
+
+Clips run 3–15 seconds on v3 and O3 and 5 or 10 on most 2.x routes, 720p to
+4K, in 16:9, 9:16 or 1:1. The prompt caps at 2500 characters on most fal
+routes, 3072 on fal's v3 turbo and kie's omni routes, and 1000 on kie's 2.6.
+
+## One shot per prompt
+
+On v3 and O3, `multi_prompt` takes the shots and `prompt` takes a single shot;
+they are mutually exclusive, so send one or the other. With fal's `shot_type`
+set to `customize` (or kie omni's `customize_multi_shots` true), your shot
+boundaries are used verbatim; with `intelligent` (or `prefer_multi_shots`) the
+model cuts the narrative itself. Pick customize whenever you know the beats.
+The provider list above gives each route's shot fields and caps.
+
+On 2.5-turbo, 2.6 and O1 there is no shot list — one call is one shot, and a
+sequence is several calls cut together in the timeline. Writing three labelled
+shots into a single `prompt` there gets you one confused take.
+
+Two to five sentences per shot is the working range. Each one names framing,
+subject action, and camera behaviour:
+
+```
+Shot 1 (4s): Wide. A courier in a wet orange jacket steps off a tram into
+  a night market, steam rising off the food stalls. Camera locked off.
+Shot 2 (3s): Close on her hands unfolding a paper note, the ink running.
+  Slow push-in, shallow focus.
+Shot 3 (5s): Medium tracking shot alongside her as she pushes through the
+  crowd toward a lit doorway, neon reflections sliding over the jacket.
+```
+
+Repeat the subject description in every shot that contains it. A pronoun in
+shot 3 is a new person.
+
+## Elements keep a face across the cut
+
+`elements` takes reference images or a reference video per character or object;
+the prompt addresses them as `@Element1`, `@Element2`. Which routes carry it is
+in the table and provider list above. On the reference-to-video endpoints,
+style references come in separately through `images` and are addressed as
+`@Image1`. Elements plus reference images cap at four when a video reference is
+in play; kie's omni endpoint takes up to seven image subjects, or three video
+character subjects.
+
+```
+@Element1 sets the espresso cup down on the counter beside @Element2 without
+looking up. Medium two-shot, warm window light from the left.
+```
+
+Tagging is what gives Kling three or more distinct characters in one clip
+without their faces blending. Describe each element once, then refer to it by
+tag only.
+
+## Dialogue and native audio
+
+Native audio's switch and default differ per route (the table and provider list
+above). On fal an O3 clip comes back silent unless you set `generate_audio`.
+It produces dialogue with lip sync, plus ambience. Direct it with a labelled
+line:
+
+```
+[Detective Voss, low and tired]: "You left the light on."
+Immediately, [Marla, brittle, too fast]: "I was coming back."
+```
+
+Four rules the format depends on:
+
+- **Labels are unique and constant.** `Detective Voss` in every line, never
+  "he" and never "the detective".
+- **Bind each line to an action.** Write the action first, then the line. An
+  unanchored line drifts off the picture.
+- **Sequence with a linking word.** "Immediately", "after a beat", "as she
+  turns" — without one, two lines overlap into mush.
+- **Case matters for English speech.** fal's guide says to write it lowercase
+  and reserve capitals for acronyms and proper nouns, which is how the model
+  decides to spell a word out.
+
+fal's guide says Chinese and English are voiced natively and anything else is
+translated to English before it is spoken, so write the line in the language
+you want heard.
+
+## Controls
+
+| Parameter | Where it exists | What to do with it |
+| :--- | :--- | :--- |
+| `cfg_scale` | 2.5-turbo, fal 2.6 text-to-video, AtlasCloud 2.6, v3 (not turbo) | 0.5 default; 0.3 for a freer read, 0.7 only when spatial layout is fixed |
+| `negative_prompt` | 2.5-turbo, 2.6, v3 (not turbo) | fal's default is "blur, distort, and low quality"; add what you see — sliding feet, extra fingers, warped faces, jittery camera |
+| `duration` | every route | 3–15s on v3 and O3; each shot in a multi-shot list gets its own |
+| `generate_audio` / `sound` / `audio` | 2.6, v3, O3 (not turbo) | Off costs less per second; leave it off when you are scoring in the timeline anyway |
+
+Negative prompts earn their place here more than on most lines: Kling's
+failures are limb and contact artifacts during fast motion, and naming the one
+you are actually seeing suppresses it. O1, O3 and v3 turbo expose neither
+dial, so on those the prompt is the whole instrument — spend the words the parameters would
+have saved.
+
+## Image to video
+
+The image is the anchor. Prompt only the change — camera move, what the subject
+does next, how the light shifts. Re-describing what is already in the frame
+spends words and invites the model to re-render it slightly differently.
+A start image plus an end image (`end_image_url` on fal, `tail_image_url` on
+fal's 2.5-turbo, `end_image` on AtlasCloud and Replicate) gives you a move with
+a fixed landing frame. `animate_image` sends one image, so an end frame needs
+the route's own node. Aspect ratio follows the input image; the parameter is
+ignored.
+
+## Motion control is not a prompt job
+
+The motion-control endpoints copy character motion from a reference video onto
+a reference image, and the prompt only colours the result. What decides the
+output is `character_orientation`: `video` matches the reference clip's
+orientation and handles complex motion up to 30 s; `image` matches the still
+and follows camera movement better, capped at 10 s. The reference image needs
+an unobstructed figure occupying more than 5% of the frame.
+
+## Symptoms
+
+| What went wrong | What to change |
+| :--- | :--- |
+| One drifting take instead of beats | Move the shots into the route's shot list with customize set, or move to v3/O3 if your version has no shot list |
+| A clip came back silent | That route's audio switch defaults to false — check the provider list |
+| A character changes face at the cut | Give them an element and tag every mention |
+| Two lines of dialogue collide | Add a linking word and bind each line to an action |
+| Sliding feet, bent fingers | Name that artifact in `negative_prompt` |
+| Composition ignores a stated layout | Raise `cfg_scale` toward 0.7 |
+| Spoken line comes out in the wrong language | Write the line in Chinese or English — everything else is translated |
+
+Grade the render with `analyze_video` and `detect_video_scenes` rather than
+watching it, and `understand_video` when you need a written read of what
+landed.
+
+Adapted from fal's Kling 3.0 prompting guide and Kling 3.0 Pro usage notes:
+https://blog.fal.ai/kling-3-0-prompting-guide/
+https://fal.ai/learn/tools/how-to-use-kling-3-0-pro