@nodaro/prompts 1.5.0 → 1.7.0

package/src/provider-prompt-doctrine.ts

@@ -19,6 +19,12 @@
  *   - KIE API docs https://docs.kie.ai/market/kling/kling-3-0
  *   - Live KIE-path dialogue probe 2026-07-16 (scripted lines spoken verbatim,
  *     lip-synced, on both kling-2.6 and kling-3.0 with sound=true)
+ *   MiniMax Hailuo 3:
+ *   - KIE API docs https://docs.kie.ai/market/minimax-h3 (text-to-video /
+ *     image-to-video / reference-to-video — the API contract is the doctrine
+ *     source: limits, modes, aspect rules, pricing dimensions). No live probe
+ *     yet — structure guidance mirrors the platform's ordinal-reference
+ *     conventions rather than vendor style claims.
  */
 export interface ProviderPromptDoctrine {
   /** MODEL_CATALOG ids this doctrine covers. */
@@ -32,14 +38,16 @@ export interface ProviderPromptDoctrine {
 }
 
 const SEEDANCE_2_DOCTRINE: ProviderPromptDoctrine = {
-  providers: ["seedance-2", "seedance-2-fast", "seedance-2-mini"],
-  heading: "Seedance 2.0 (seedance-2, seedance-2-fast, seedance-2-mini)",
+  providers: ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2-5"],
+  heading: "Seedance 2 (seedance-2, seedance-2-fast, seedance-2-mini, seedance-2-5)",
   tips: [
     "Storyboard complex videos as 'Shot 1: … Shot 2: …' WITHOUT timestamps — timed shots like '(0-3s)' are officially unstable and can break generation.",
     "One camera movement per shot; describe actions per body part with degree ('slowly raises a hand'); express emotion as physical detail, never abstract words.",
     "Native multi-track audio — cue it inline: （background music）, <sound effects>, and quoted dialogue.",
     "References go by ordinal (@Image 1, Video 2) in attachment order; earlier = higher priority. Identity = ONE headshot + ONE full-body (multi-view sheets cause ID drift). 4-5 assets total beats maxing the 9/3/3 caps.",
     "No negative-prompt parameter — put constraints in the prompt: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
+    "seedance-2-5 only: one shot runs to 30s (the 2.0 SKUs stop at 15s), so storyboard a whole beat instead of planning a stitch. Ref caps are wider (30/10/10), but 4-5 assets still gives the best identity fidelity.",
+    "Auto-path formula: Subject → Action → Environment → Camera → Style → Constraints in 60-100 words; ONE camera instruction (chain with 'then'); separate camera motion from subject motion; always add one lighting phrase.",
   ],
   doctrine: `Prompt structure (front-load what matters most):
 precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints.
@@ -51,6 +59,12 @@ precise subject → action details → scene/environment → lighting & color to
 - Prefer slow, gentle, continuous movements over high-burst action (sprints, big jumps, violent rolls morph). Describe actions per body part with quantified degree: "slowly raises a hand", "pushes hard off the ground". Chain actions with inertia: "uses the momentum of the turn to naturally raise an arm".
 - Express emotion as externalized physical detail, never abstract words: not "very sad" but "lowering the head, shoulders trembling slightly, eyes reddening, fingers clutching the corner of clothing".
 
+**Generation differences (seedance-2-5 vs the 2.0 SKUs)**
+- A single 2.5 shot runs to 30s, where every 2.0 SKU stops at 15s. Plan a complete 4-6 shot beat inside ONE generation instead of splitting it into two clips and stitching — no seam to hide, and continuity holds because it never leaves the model.
+- 2.5 also takes far more reference material (30 images / 10 videos / 10 audio vs 9/3/3). Treat that as room for COVERAGE — more distinct characters, locations and props in one shot — not as licence to pile refs onto one identity. The "ONE headshot + ONE full-body, 4-5 assets total" rule above still produces the best likeness on 2.5.
+- 2.5 renders at 480p/720p only: there is no 1080p or 4K tier, so route a job that needs one to seedance-2 (which has both) or upscale afterwards.
+- With a start frame, 2.5 always derives the output aspect from that frame — an explicit aspect ratio is rejected outright, so compose the frame at the ratio you want.
+
 **References (when reference media is attached)**
 - Refer to assets by ordinal in attachment order: "@Image 1", "Video 2", "Audio 1". Asset ORDER is priority — put the most identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding — \`{image:1:person}\` resolves to "the person from @image_1" — so a wired reference and its mention stay in sync.)
 - Define each subject once, then reuse the label consistently: 'Define the woman in the red dress in Image 1 as the courier' … 'the courier opens the door'. In multi-character scenes bind every character to its image ("the man from Image 1 hands the box to the woman from Image 2") and append: "do not generate duplicate copies of the same character".
@@ -71,12 +85,35 @@ precise subject → action details → scene/environment → lighting & color to
 **Known weaknesses → workarounds**
 - Text rendering is weak: keep on-screen text to short common words; for exact text or logos, attach the artwork as a reference image and instruct "the logo from Image N stays in the corner unchanged".
 - More than 4 referenced people gets unstable: group people into composite images of ≤4 first (image generation), then reference those composites.
-- Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.`,
+- Repeated extension degrades quality: prefer high-definition reference assets and avoid stacking many continuations.
+
+**Auto-path formula (community-sourced enrichment — apiyi.com Seedance 2.0 prompt guide,
+higgsfield.ai 4K breakdown; captured 2026-08-09)**
+- Six steps IN ORDER, 60-100 words total (longer measurably degrades): Subject → Action → Environment → Camera → Style → Constraints.
+- ONE primary camera instruction per shot. Compound moves chain with "then": "camera slow tracking then subtle rise" — never two competing verbs. The 8 reliable camera types: push-in, pull-out, pan, tracking, orbit/arc, aerial, handheld, locked-off.
+- SEPARATE camera movement from subject movement — the single biggest quality lever: "The dancer spins slowly. Camera holds fixed framing." — never "spinning camera around a dancing person".
+- Pace with human words (slow / gentle / gradual / smooth / controlled) — never fps numbers or f-stops in the basic path.
+- ALWAYS add one lighting phrase (highest-impact single addition): golden hour / rim light / neon glow / backlit / overcast.
+- Bake stability constraints in: "avoid jitter and bent limbs", "avoid temporal flicker", "avoid identity drift".
+- Ban vague adjectives standing alone ("epic", "amazing", "beautiful", bare "cinematic") — every adjective needs a concrete noun.
+- Mode notes: i2v — skip subject description (the frame has it), focus on motion, append "preserve composition and colors". v2v — describe the style TRANSFORM, keep motion + identity.
+- Advanced (pro path): focal angles in degrees ("47° normal", "29° telephoto", "107° wide"); "180° shutter" for filmic motion blur; handheld texture as "organic shake, micro-drift, subtle dutch"; "white balance locked 5200K"; explicit POSITIVE LOCKS section + "100% matches the reference" for identity-critical shots.
+
+**Camera-path control — the magenta-line method (STORYBOARD community technique; the
+manual pro path for precise trajectories, NOT the auto path)**
+1. Duplicate the start frame; on the COPY draw a thick magenta line + arrowhead — the line is the camera's flight path, the arrow its end point. Keep the clean original.
+2. Attach BOTH frames and declare the guide: "Image N contains a magenta line and arrow — a hidden camera trajectory guide, NOT part of the scene. Completely remove it: no line, no arrow, no paint, no trail, no reflection." Skipping the removal order RENDERS the line.
+3. Command the path: "one continuous FPV drone glide following the S-shaped curve as closely as possible — do not shortcut. Camera motion is the priority." Lock the clean frame as first frame + scene reference; lock the destination frame if wired.
+4. Pace with timing blocks ("[00:00-00:02] rise over the rooftop … [00:07-00:09] settle on the doorway") and keep any dialogue SHORT — long lines fight the move.
+5. Assign image-input roles explicitly: first-frame/scene-ref · destination frame · path-guide · 3-6 character-identity refs — and bind identities with @-mentions exactly like the platform's reference pills.`,
 }
 
 const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
-  providers: ["kling", "kling-3.0", "kling-3-omni"],
-  heading: "Kling 2.6 / 3.0 / 3 Omni (kling, kling-3.0, kling-3-omni)",
+  // kling-turbo (2.5 Turbo Pro) + kling-master (2.1 Master) are SILENT tiers of
+  // the same engine: the structure/motion guidance applies, the Audio block
+  // does not (variant note in the doctrine body).
+  providers: ["kling", "kling-3.0", "kling-3-omni", "kling-turbo", "kling-master"],
+  heading: "Kling 2.1 / 2.5 / 2.6 / 3.0 / 3 Omni (kling, kling-3.0, kling-3-omni, kling-turbo, kling-master)",
   tips: [
     "Kling speaks scripted dialogue natively with lip sync — quote the line and enable sound: [Anna: warm calm voice]: \"We made it.\" On kling/kling-3.0 audio raises the credit cost; kling-3-omni includes it.",
     "Structure prompts as Scene → character/element → Motion → Audio → style. Put ALL sound in one 'Audio:' block: dialogue in quotes, then SFX and ambience described plainly ('rain tapping on glass, no music').",
@@ -108,12 +145,248 @@ const KLING_AUDIO_DOCTRINE: ProviderPromptDoctrine = {
 
 **Limits**
 - Kling 2.6 prompts cap at 1000 characters — front-load scene + dialogue and trim style tails first. kling-3.0 accepts long prompts.
-- Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.`,
+- Durations: 2.6 = 5/10s; 3.0/omni = 3-15s. A spoken line needs roughly 1s per 2-3 words — don't script more dialogue than the clip can hold.
+
+**Variant note — kling-turbo (2.5 Turbo Pro) & kling-master (2.1 Master)**
+- SILENT tiers: no audio parameter, so the entire Audio block above does not apply — skip dialogue/SFX cues; the Scene → Character → Motion → Style structure and motion guidance carry over unchanged.
+- Durations 5/10s; kling-turbo takes an end frame (tail_image_url); kling-master is single-image i2v.`,
+}
+
+const MINIMAX_H3_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["minimax-h3"],
+  heading: "MiniMax Hailuo 3 (minimax-h3)",
+  tips: [
+    "Natural-language prompts up to 7000 chars. Front-load what matters: subject → action → scene/environment → lighting → camera move → style. One camera movement per shot.",
+    "Output 2K (default) or 768P (cheaper tier). Aspect: pure text-to-video needs a concrete ratio (21:9/16:9/4:3/1:1/3:4/9:16); reference runs default to adaptive (match the input).",
+    "References go by ordinal in attachment order (@Image 1, Video 1) — earlier = higher priority. Caps: 9 images, 3 videos (2-15s each, ≤15s total), 3 audio clips (≤15s total).",
+    "Reference audio drives speech/lip-sync but never rides alone — pair it with an image or video reference. Audio input is free; the first 5 input images are free, extras bill per image.",
+    "No negative-prompt parameter — put constraints in the prompt text: 'keep it subtitle-free, do not generate a watermark, do not generate a logo'.",
+  ],
+  doctrine: `Prompt structure (front-load what matters most):
+precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints. Prompts are natural language, 1-7000 characters, across all three modes.
+
+**Modes (picked automatically from the wired inputs)**
+- First frame and/or last frame connected, nothing else → exact frame mode (image-to-video): the output opens on the first frame and/or closes on the last. The clip's aspect is inferred from the frame — there is no aspect parameter in this mode.
+- ANY reference connected (image, video, or audio) → reference mode (reference-to-video): frames ride along as reference images with a prompt directive binding them to the opening/closing position. Aspect defaults to adaptive (matches the input); a concrete ratio can be forced.
+- Nothing visual connected → text-to-video. A concrete aspect ratio is required (21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 — no adaptive); Nodaro renders 16:9 unless one is picked.
+
+**References (when reference media is attached)**
+- Refer to assets by ordinal in attachment order: "@Image 1", "Video 1", "Audio 1". Put the identity-critical asset first. (In the editor, the \`{image:N:label}\` / \`{video:N}\` / \`{audio:N}\` prompt tokens auto-emit this binding, so a wired reference and its mention stay in sync.)
+- Caps: 9 reference images; 3 reference videos, each 2-15s and ≤15s combined; 3 reference audio clips, ≤15s combined. Reference audio cannot be used alone — it must accompany an image or video reference.
+- Define each subject once, then reuse the label consistently ("the woman from @Image 1 … the woman opens the door"). A focused set of 4-5 assets beats maxing every cap.
+- Billing note: generated seconds AND reference-video input seconds bill at the same per-second rate; the first 5 input images are free and each extra image adds a small surcharge; audio input is free.
+
+**Audio**
+- Audio is always generated — there is no on/off toggle. With reference audio attached, the model syncs speech to the supplied track (the platform's lip-sync surface routes image + voice line through this mode automatically).
+- Quoted dialogue in the prompt gives the model the line to perform; describe the voice in words when no reference audio is supplied.
+
+**Duration & pacing**
+- 4-15 seconds, integer, default 6. Per-second pricing — a 15s clip costs ~3.7× a 4s clip, so pick the shortest duration that serves the shot.
+- One camera movement type per shot; chain actions with physical, quantified detail ("slowly raises a hand", "pushes hard off the ground") rather than abstract emotion words.
+
+**Constraints**
+- There is NO negative-prompt parameter — all constraints belong in the prompt text itself: "keep it subtitle-free, do not generate a watermark, do not generate a logo, stable picture".`,
+}
+
+const VEO_31_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["veo3", "veo3.1", "veo3_lite", "veo-1080p", "veo-4k", "veo-extend"],
+  heading: "VEO 3.1 — Quality / Fast / Lite (veo3, veo3.1, veo3_lite)",
+  tips: [
+    "Structure prompts as [Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance] — lead with the camera, not the subject (Google's official formula).",
+    "Dialogue: quote the exact line with attribution — A woman says, \"We have to leave now.\" (no subtitles). Cue sound as separate lines: SFX: thunder cracks; Ambient noise: quiet hum of a starship bridge.",
+    "Multi-shot pacing via timestamp blocks: [00:00-00:02] medium shot… [00:02-00:04] reverse shot… — VEO honors per-window actions inside one 8s generation.",
+    "Negative prompting is positive phrasing: not 'no buildings' but 'a desolate landscape with no buildings or roads'. Keep prompts under ~175 words — longer overloads the generation.",
+    "Start+end frame: pass both and describe the transition move ('smooth 180-degree arc ending on the POV behind her'). References (ingredients) keep characters/objects consistent and DO generate audio.",
+  ],
+  doctrine: `Prompt structure (Google's official Veo 3.1 formula — lead with the camera):
+[Cinematography] + [Subject] + [Action] + [Context] + [Style & Ambiance].
+Example: "Medium shot, a tired corporate worker, rubbing his temples in exhaustion, in front of a bulky 1980s computer in a cluttered office late at night, lit by harsh fluorescents and the green monitor glow. Retro aesthetic, 1980s color film, slightly grainy."
+
+**Camera vocabulary (use the exact terms)**
+- Movement: dolly shot, tracking shot, crane shot, aerial view, slow pan, POV shot, 180-degree arc shot.
+- Composition: wide shot, medium shot, close-up, extreme close-up, two-shot, low angle, high angle.
+- Lens/focus: shallow depth of field, deep focus, wide-angle lens, macro lens, soft focus.
+
+**Audio (native, multi-track — dialogue / SFX / ambience)**
+- Dialogue: quote the exact line with attribution: The detective says in a weary voice, "Of all the offices in this town, you had to walk into mine." Append "(no subtitles)" — VEO otherwise tends to burn captions in.
+- Sound effects on their own line: "SFX: a crystal wine glass shatters on the marble floor". Ambient bed: "Ambient noise: rain against the window, distant traffic".
+- Sound can drive the visual ("the sound reverberating through the empty ballroom") — VEO syncs audio-visual timing.
+
+**Multi-shot timestamp prompting (inside one generation)**
+- Split the clip into [mm:ss-mm:ss] windows, one action per window:
+[00:00-00:02] Medium shot from behind a young explorer walking toward a clearing.
+[00:02-00:04] Reverse shot of her freckled face, eyes widening.
+[00:04-00:08] Wide, high-angle crane shot revealing the ruins below.
+- 4 / 6 / 8 second clips; budget ~2s per window.
+
+**Frames & references**
+- Start + end frame: wire both (imageUrls [start, end]) and describe the camera path between them — "a smooth 180-degree arc shot, starting front-facing and circling to end on the POV from behind her".
+- Reference images (ingredients): attach character/object/scene refs and name them in the prompt ("using the provided images for the detective and the office, …"). Reference runs DO generate audio.
+
+**Constraints**
+- Negative prompting works by positive description: write "a desolate landscape with no buildings or roads", not "no buildings".
+- Keep prompts ≤ ~175 words — beyond that instructions conflict and adherence drops. Resolution 720p/1080p; aspect 16:9 / 9:16.
+
+Sources: Google Cloud "Ultimate prompting guide for Veo 3.1"
+(cloud.google.com/blog/products/ai-machine-learning/ultimate-prompting-guide-for-veo-3-1),
+KIE VEO API docs (docs.kie.ai/veo3-api/generate-veo-3-video). Captured 2026-08-09.`,
+}
+
+const GEMINI_OMNI_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["gemini-omni-video"],
+  heading: "Gemini Omni Video (gemini-omni-video)",
+  tips: [
+    "Multimodal Google video with native audio: text-to-video, image-to-video, and video-edit through the same prompt surface. 4/6/8/10s; 720p/1080p or 4K tier.",
+    "Structure like the platform default: subject → action → scene → lighting → camera → style. Quote dialogue lines to have them spoken; describe SFX/ambience plainly in the prompt.",
+    "Text-to-video REQUIRES a concrete aspect ratio (the API hard-rejects a missing one); image runs infer aspect from the input.",
+    "Reference images ride along as additional imageUrls — bind them in the prompt ('the woman from the first image'). Video-edit: wire a source clip and describe the change, not the whole scene.",
+  ],
+  doctrine: `Prompt structure (no public Google prompt guide exists for the Omni video endpoint —
+the API contract is the doctrine source, like MiniMax H3; structure guidance mirrors the
+platform's ordinal-reference conventions):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Modes (picked from the wired inputs)**
+- Nothing visual → text-to-video. A concrete aspect ratio is REQUIRED — the API hard-rejects a missing one (Nodaro sends the node's ratio; there is no adaptive).
+- Image(s) wired → image-to-video: the first image anchors the scene; extra images are references — bind each in the prompt ("the woman from the first image", "the interior from the second image").
+- Source video wired → video-edit (served through the same handle): describe the CHANGE ("replace the daylight with dusk, keep the motion and framing"), not a full re-description.
+
+**Audio (native)**
+- Audio is generated with the clip. Quote dialogue to have it spoken; describe SFX and ambience plainly ("rain on glass, low synth bed"). State exclusions ("no music") or a bed may be invented.
+
+**Duration & tiers**
+- 4 / 6 / 8 / 10 seconds. 720p/1080p tier or the pricier 4K tier — pick 4K only when the deliverable needs it (nearly 2× the credits).
+
+Source: KIE gemini-omni-video market contract (parameters + live behavior probed for the
+aspect-ratio hard-reject, see providers/kie/video.ts). Captured 2026-08-09.`,
+}
+
+const GROK_IMAGINE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["grok-i2v", "grok-imagine-video-1.5"],
+  heading: "Grok Imagine (grok-i2v, grok-imagine-video-1.5)",
+  tips: [
+    "Keep prompts simple and direct — Subject + Action + Setting + Camera + Mood. Grok expands the prompt itself; over-specification fights the expander.",
+    "Image-to-video: the input image IS the first frame (composition, identity, and style are preserved) — describe the MOTION, don't re-describe the still.",
+    "Video 1.5: 1-15s (default 8), 480p/720p/1080p, up to 7 input images (1080p allows only one). Native audio incl. music, SFX, and lip-synced dialogue — quote the line to have it spoken.",
+    "Aspect ratio applies to text runs (1:1/16:9/9:16/3:2/2:3/auto); a single input image locks the output to the image's own aspect.",
+  ],
+  doctrine: `Prompt structure (xAI's guidance is minimal by design — the model auto-expands prompts):
+Subject + Action + Setting + Camera + Lighting/Mood, written simply and directly. Reduce
+descriptions of static/unchanged parts — spend the words on what MOVES.
+
+**Image-to-video (the primary mode)**
+- The input image is the FIRST FRAME, not a loose reference: composition, subject identity, and visual style carry over. Describe motion and camera only ("she turns toward the window as the camera slowly pushes in"); re-describing the still wastes adherence.
+- grok-imagine-video-1.5 accepts up to 7 images (identity/scene references beyond the first frame); at 1080p only ONE image is allowed.
+
+**Audio (video-1.5)**
+- Native audio generates with the clip — background music, SFX, and lip-synced dialogue. Quote the spoken line; describe the music/SFX plainly. There is no audio toggle on the KIE contract — cue (or exclude) sound in the prompt text.
+
+**Durations / tiers**
+- grok-i2v: 6 or 10 seconds. grok-imagine-video-1.5: 1-15 seconds in 1s steps (default 8), 480p (default) / 720p / 1080p. Prompt cap 4096 chars — but shorter is better here.
+
+Sources: KIE Grok Imagine contracts (docs.kie.ai/market/grok-imagine/image-to-video,
+docs.kie.ai/market/grok-imagine/1-5-preview), xAI Grok Imagine 1.5 release notes
+(x.ai/news/grok-imagine-1-5). Captured 2026-08-09.`,
+}
+
+const WAN_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["wan", "wan-i2v", "wan-turbo", "wan-flash", "wan-2.7", "wan-2.7-i2v", "wan-2.7-t2v", "wan-2.7-pro", "wan-videoedit"],
+  heading: "Wan 2.x (wan, wan-i2v, wan-turbo, wan-2.7 family)",
+  tips: [
+    "Alibaba's official formula: Entity + Scene + Motion (basic) → add Aesthetic control + Stylization (advanced). Image-to-video: Motion + Camera only — the image already defines entity and scene.",
+    "Sound (2.5+): append a sound description block — voice / sound effects / background music. Avoid scripting EXACT lip-synced lines (official anti-pattern); describe the voice and intent instead.",
+    "Multi-shot (2.6/2.7): Overall description + shot number + timestamp + per-shot content. For ONE continuous take write 'Generate single shot' (the shot_type parameter is gone in 2.7).",
+    "References go by 'Image 1' / 'Video 1' (capitalized, with a space). Anti-patterns: naming real people, demanding exact legible text, rapid scene changes in one clip, very long choreography.",
+    "Style words are strong levers: cyberpunk, claymation, pixel style, felt style, tilt-shift, time-lapse. wan-videoedit: describe the transform, keep motion + identity.",
+  ],
+  doctrine: `Prompt structure (Alibaba Model Studio's official formulas):
+- Basic: Entity + Scene + Motion.
+- Advanced: Entity (description) + Scene (description) + Motion (description) + Aesthetic control + Stylization.
+- Image-to-video: Motion + Camera movement ONLY — the wired image already defines entity and scene; re-describing it fights the frame.
+- Sound (2.5/2.6/2.7): … + Sound description (voice / sound effects / background music).
+- Multi-shot (2.6/2.7): Overall description + Shot number + Timestamp + Shot content.
+- Reference-to-video (2.6/2.7): Reference identifier + Action + Scene + optional Lines + optional BGM.
+
+**Camera vocabulary**
+push-in (intimacy/tension), pull-out (scale/isolation), tracking shot, orbit, fixed camera, and compound movements chained sequentially for epic scale.
+
+**Single-shot control (2.7)**
+- The shot_type parameter no longer exists — write "Generate single shot" in the prompt to force one continuous take; otherwise 2.7's planner may cut.
+
+**References**
+- English format is "Image 1" / "Video 1" (capitalized, space-separated) — bind every wired asset by that name or it may be ignored.
+
+**Official anti-patterns (from Alibaba's guide)**
+- Do NOT name specific real people.
+- Do NOT script exact lip-synced dialogue — describe the voice and intent ("she murmurs a reassurance, warm and low") instead of demanding word-perfect lips.
+- Avoid rapid scene changes inside a single clip, very long choreographed sequences, and demands for exactly legible on-screen text.
+
+**Stylization**
+- Style words are strong levers: cyberpunk, line-art illustration, felt style, 3D cartoon, pixel style, puppet animation, claymation, black-and-white animation, tilt-shift, time-lapse.
+
+Source: Alibaba Cloud Model Studio — "Text-to-video / image-to-video prompt guide"
+(alibabacloud.com/help/en/model-studio/text-to-video-prompt). Captured 2026-08-09.`,
+}
+
+const HAPPYHORSE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["happyhorse", "happyhorse-i2v", "happyhorse-ref2v", "happyhorse-edit"],
+  heading: "HappyHorse 1.1 (happyhorse, happyhorse-i2v, happyhorse-ref2v)",
+  tips: [
+    "Any-language prompts up to 5000 chars (2500 Chinese) — excess is silently truncated, so front-load subject → action → scene → camera → style.",
+    "3-15 seconds per second of billing; 720p or 1080p; ratios 16:9 / 9:16 / 1:1 / 4:3 / 3:4. Pick the shortest duration that serves the shot.",
+    "ref2v is one of the few true REFERENCE modes on the roster: wired refs keep identity across the clip — bind each reference explicitly in the prompt.",
+    "No published vendor style guide — the platform's standard structure applies; keep one camera move per shot and quantify motion physically.",
+  ],
+  doctrine: `Prompt structure (no public HappyHorse prompt guide exists — the KIE API contract is the
+doctrine source; platform-standard structure applies):
+subject → action → scene/environment → lighting → camera movement → style → constraints.
+
+**Contract facts (KIE, per-mode pages)**
+- Prompts: any language, up to 5000 non-Chinese / 2500 Chinese characters — excess is TRUNCATED silently, so put the load-bearing content first.
+- Duration 3-15s (default 5), billed per second. Resolution 720p / 1080p (default). Aspect 16:9 (default) / 9:16 / 1:1 / 4:3 / 3:4.
+- Modes: text-to-video (happyhorse), image-to-video (happyhorse-i2v), reference-to-video (happyhorse-ref2v) — ref2v preserves wired identities; name each reference in the prompt so the binding is explicit.
+
+**Style guidance (platform-standard, honestly generic)**
+- One camera movement per shot; physical, quantified action ("slowly raises a hand") over abstract emotion words; state exclusions ("no on-screen text, no watermark") in the prompt.
+
+Source: KIE HappyHorse 1.1 contracts (docs.kie.ai/market/happyhorse/text-to-video,
+…/happyhorse-1-1/image-to-video, …/happyhorse-1-1/reference-to-video). Captured 2026-08-09.`,
+}
+
+const RUNWAY_KIE_DOCTRINE: ProviderPromptDoctrine = {
+  providers: ["runway-kie", "runway-extend", "runway-aleph"],
+  heading: "Runway via KIE (runway-kie)",
+  tips: [
+    "Prompt cap is 1800 chars; KIE's own guidance: be specific about subject, action, style, and setting. No native audio — plan sound as a separate pass.",
+    "Durations 5 or 10s with a hard trade-off: 10s cannot be 1080p, 1080p cannot exceed 5s — pick per deliverable.",
+    "Text runs REQUIRE an aspect ratio (16:9/4:3/1:1/3:4/9:16); image runs IGNORE it — the input image dictates output dimensions.",
+    "Image-to-video treats the image as the anchor frame: describe motion and camera, not the still.",
+  ],
+  doctrine: `Prompt structure (KIE contract guidance): "be specific about subject, action, style, and
+setting" — subject → action → scene → camera → style, within the 1800-character cap.
+
+**Contract facts (KIE Runway endpoint)**
+- Duration 5 or 10 seconds; quality 720p or 1080p — 10s@1080p does NOT exist (10s forces 720p; 1080p forces 5s). Choose by deliverable: crisp hero shot → 5s/1080p; longer beat → 10s/720p.
+- Text-to-video REQUIRES aspectRatio (16:9 / 4:3 / 1:1 / 3:4 / 9:16). Image-to-video IGNORES aspectRatio — the input image dictates output dimensions.
+- No audio is generated — score/SFX are a separate pass (merge-video-audio / video-sfx downstream).
+
+**Style guidance**
+- The image input anchors composition and identity — describe the motion ("she pushes the door open as the camera tracks left"), not the still.
+- Keep one continuous camera idea per clip; front-load the subject and action.
+
+Source: KIE Runway contract (docs.kie.ai/runway-api/generate-ai-video). Captured 2026-08-09.`,
 }
 
 export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
   SEEDANCE_2_DOCTRINE,
   KLING_AUDIO_DOCTRINE,
+  MINIMAX_H3_DOCTRINE,
+  VEO_31_DOCTRINE,
+  GEMINI_OMNI_DOCTRINE,
+  GROK_IMAGINE_DOCTRINE,
+  WAN_DOCTRINE,
+  HAPPYHORSE_DOCTRINE,
+  RUNWAY_KIE_DOCTRINE,
 ]
 
 const DOCTRINE_BY_PROVIDER: ReadonlyMap<string, ProviderPromptDoctrine> = new Map(

package/src/reference-rules.ts

@@ -0,0 +1,226 @@
+/**
+ * REFERENCE RULES — the two short blocks that decide whether a multi-reference
+ * image obeys its references, and whether it looks like a film frame or a
+ * posed photograph.
+ *
+ * Both were measured on gpt-image-2 at 2K, against one deliberately hard brief:
+ * four references (two people, a street-fashion shot, and a composite holding a
+ * wine glass, a smartphone, a hotel suite AND two other women's faces), with
+ * wardrobe swapped BETWEEN the two people. 36 draws, 2026-08-06. Scored on five
+ * criteria: both faces correct and unblended, each person's wardrobe, the
+ * props, the location, and one coherent composition.
+ *
+ * ─── REFERENCE_RULES ───────────────────────────────────────────────────────
+ *
+ * Two wordings already existed in this codebase and NEITHER was best. Each was
+ * written without knowledge of the other:
+ *
+ *   the `reference-lock` snippet   — default-deny + likeness + compose.
+ *                                    **0 of 4** on the hardest criterion (move
+ *                                    a garment from one reference to another).
+ *                                    Flawless on the other four, which is what
+ *                                    made it feel like it worked.
+ *   gvp's `referenceRules`         — default-deny + face rules + likeness +
+ *                                    "expression, gaze and pose follow the
+ *                                    scene". **1 of 4**.
+ *   the two MERGED                 — **4 of 4** (Fisher exact vs the snippet,
+ *                                    p ≈ 0.03).
+ *
+ * The arms isolate: swapping the performance clause for the compose clause took
+ * it 1/4 → 4/4, and adding the face rules took 0/4 → 4/4. Each half does real
+ * work and neither is sufficient alone. The performance clause is dropped here
+ * because a composite has no scene to perform — it belongs to gvp's SCENE lane,
+ * where a subject must act the beat.
+ *
+ * ─── SCENE_FRAME_RULE ──────────────────────────────────────────────────────
+ *
+ * The separate failure Tal reported: everyone faces the lens and the result
+ * reads as an artfully posed photograph rather than a frame out of a film.
+ * Four fixes were measured against the block above (which is 0/4 on gaze by
+ * itself):
+ *
+ *   "This image is a scene start frame of a video."  0/4 gaze, **0/3 identity**
+ *   "Film still from a feature film."                 gaze ✗ (sampled)
+ *   "A candid moment, unposed, nobody aware of…"      identity ✗ (sampled)
+ *   rewriting the verbs (drinking, not holding)       4/4 gaze, 3/4 identity
+ *   **"Nobody looks at the camera."**                 **4/4 gaze, 4/4 identity,
+ *                                                     4/4 wardrobe**
+ *
+ * Only the short negative is free. Everything longer — a medium declaration, a
+ * genre label, a mood sentence — competes with the reference bindings and the
+ * references lose: the "scene start frame" arm put a woman from INSIDE a
+ * reference into the lead role in every draw. This is the same effect gvp's
+ * block already recorded on a different brief ("more instruction bought LESS
+ * compliance"), now measured twice.
+ *
+ * KEPT SEPARATE FROM THE RULES, deliberately. A portrait, a piece to camera, or
+ * a product shot WANTS the eyeline; suppressing it is a creative choice, not a
+ * correctness rule. They are two controls, defaulting independently.
+ */
+
+/**
+ * Default-deny + likeness + compose. Goes ahead of the scene it governs.
+ *
+ * OPT-IN, NOT INJECTED. An earlier cut of this work defaulted it on for every
+ * image node; Tal's call was that the snippets are enough, and he is right for
+ * a wording still being learned — a platform-wide default would apply the
+ * current best guess to every job at once, and the evidence for WHICH block is
+ * best is still split (see REFERENCE_RULES_MULTI_PERSON).
+ *
+ * ONE STRING, TWO CONSUMERS — the `reference-lock` factory snippet and
+ * gvp/recast's own grounding. They drifted apart once already (the snippet and
+ * gvp each carried a different version, and neither knew the other existed),
+ * which is the whole reason this is a constant rather than two literals.
+ */
+export const REFERENCE_RULES =
+  "Do not use anything from reference images unless specified explicitly. " +
+  "All elements taken from reference images must preserve likeness. " +
+  "Compose them naturally into a single image."
+
+/**
+ * The same rules PLUS the two face clauses — for briefs that move elements
+ * BETWEEN people.
+ *
+ * NOT THE DEFAULT, and the reason is a genuine conflict in the evidence that
+ * should not be quietly resolved by whoever edits this next.
+ *
+ * The controlled comparison: on a four-reference brief with two faces and a
+ * garment crossing from one person to the other, this block moved that garment
+ * 4 times in 4 draws and {@link REFERENCE_RULES} moved it 0 in 4 (Fisher exact,
+ * p ≈ 0.03). On the other four criteria — faces correct, own wardrobe, props,
+ * location, composition — the two were identical, 12/12 both ways.
+ *
+ * Tal's counter-evidence: across his own volume of real jobs, the shorter block
+ * works better IN GENERAL. Both hold. The face clauses earn their place exactly
+ * when two faces are in play and elements cross between them; on a single
+ * subject, a product or a landscape, "do not alter face structure" is dead
+ * weight, and this codebase has already measured twice that more instruction
+ * buys less compliance.
+ *
+ * So the DEFAULT follows the population (the short block) and this is the tool
+ * you reach for on the composition case. Settling "in general" properly needs
+ * the same method applied across brief TYPES, not more draws of one brief.
+ */
+export const REFERENCE_RULES_MULTI_PERSON =
+  "Do not take anything from the reference images unless specified explicitly. " +
+  "Do not alter face structure. Do not blend faces. " +
+  "Preserve the likeness of every element taken. " +
+  "Compose them naturally into a single image."
+
+/**
+ * THE FRAMING PREFIX — a sentence fragment that swallows the scene after it.
+ *
+ * "Medium wide film still of" + "The person from reference image A wears…"
+ * reads as one phrase, and that is the whole trick. Lead with the SHOT SIZE
+ * (see {@link filmStillPrefix}).
+ *
+ * NO "CINEMATIC", and that word was in here for about ten minutes. "Film still"
+ * describes the KIND of picture — a frame lifted out of moving footage, which
+ * is what a UGC clip, a product video and a documentary all are too. "Cinematic"
+ * describes a REGISTER, and imposing one is wrong for most briefs. It is also
+ * the exact category of word every measured arm punished: a genre claim. The same idea as a standalone SENTENCE
+ * ("Film still from a feature film." / "This image is a scene start frame of a
+ * video.") measured badly-to-catastrophically: the sentence competes with the
+ * reference bindings and the references lose — the "scene start frame" arm put
+ * a face from INSIDE a reference into the lead role in 3 of 3 draws. The prefix
+ * costs nothing because it never makes a separate claim.
+ *
+ * What it buys is not just the eyeline. Tal's distinction, which is sharper
+ * than the binary this was first scored on: a subject may be turned toward the
+ * lens and still be IN the scene rather than presenting to the viewer. The
+ * prefix also moves staging, depth and the quality of light — things an
+ * eyeline rule cannot reach.
+ */
+export const FILM_STILL_PREFIX = "Film still of"
+
+/**
+ * The prefix with a SHOT SIZE in front — "Extreme wide cinematic film still of
+ * …", "Medium close-up cinematic film still of …".
+ *
+ * Leading with the framing is standard practice and Tal reports it better
+ * again. HONEST STATUS: the POSITION is measured (a prefix costs nothing where
+ * a standalone claim cost the lead's identity 3 of 3); the shot-size word is
+ * his experience, not a controlled arm. The shot size is safe in a way a genre
+ * label is not — it says how the picture is FRAMED, which the scene needs
+ * anyway, rather than what kind of production it belongs to.
+ */
+export function filmStillPrefix(shotSize?: string): string {
+  const shot = shotSize?.trim()
+  return shot ? `${shot} film still of` : FILM_STILL_PREFIX
+}
+
+/**
+ * The eyeline suppressor. Five words, measured free — it costs nothing on
+ * identity, wardrobe or composition, which none of the longer phrasings
+ * managed.
+ *
+ * DO NOT EXPAND THIS. Every attempt to say more about what the picture IS cost
+ * reference fidelity; the sentence works BECAUSE it constrains exactly one
+ * thing and claims nothing about medium, genre or mood.
+ */
+export const SCENE_FRAME_RULE = "Nobody looks at the camera."
+
+/**
+ * A LOOK TAIL — film stock, lens, light, palette — appended AFTER everything.
+ *
+ * An example to edit, not a universal: a different film wants a different
+ * stock. What generalises is the POSITION.
+ *
+ * THIS one is allowed to say "cinematic" — imposing a register is its entire
+ * job, and a user opts in by name. {@link filmStillPrefix} may not, because it
+ * is a DEFAULT: "film still" describes the kind of picture (a frame out of
+ * moving footage — true of a UGC clip and a documentary too), while
+ * "cinematic" describes a register most briefs did not ask for.
+ *
+ * ─── THE ONE RULE ALL OF THIS TURNED OUT TO BE ─────────────────────────────
+ *
+ * Position decides whether an instruction helps or fights the references:
+ *
+ *   1. RULES FIRST — default-deny, ahead of the bindings it governs.
+ *   2. FRAMING AS A PREFIX that swallows the subject ("Film still of …").
+ *   3. LOOK LAST — stock, lens, lighting, palette.
+ *   4. A separate CLAIM in the middle competes with the reference bindings,
+ *      and the references lose.
+ *
+ * That is why "This image is a scene start frame of a video." (a standalone
+ * claim, mid-prompt) cost the lead's identity in 3 of 3 draws while "Film still
+ * of" (a prefix) costs nothing, and why this tail is free at the end. It
+ * matches the published guidance independently — Subject → Action →
+ * Surroundings → Camera/Lighting → Atmosphere — and gvp's engine had already
+ * found rule 3 the hard way: "THE MEDIUM GOES LAST… a rendering directive at
+ * the end has nothing after it to argue with."
+ *
+ * RECAST DOES NOT NEED THIS SNIPPET. `lookDirective` already appends a tail
+ * built from the look the ANALYSER observed in the source film — stock, grade,
+ * lens, lighting — which beats a hand-written one because it is that film's
+ * own look. This exists for the platform's image nodes, which have no analyser.
+ */
+export const CINEMATIC_LOOK_TAIL =
+  "Shot on Super 16mm Kodak 7298 with Canon K35 lenses, soft naturalistic window light mixed with " +
+  "dim tungsten practicals and muted fluorescent spill, earthy muted palette with faded greens, " +
+  "warm skin tones and gentle shadow fall-off"
+
+/**
+ * Compose the blocks a caller wants, in a stable order, ready to prepend.
+ * Returns `""` when everything is off, so a caller can prepend blind.
+ *
+ * No route calls this today — the platform ships these as SNIPPETS a user
+ * inserts. It exists for gvp/recast (which builds its grounding block in code)
+ * and for whatever calls this next, so the ordering rule lives in one place:
+ * rules first, eyeline rule after them, scene after both.
+ */
+export function referenceRulesBlock(opts?: {
+  /** Default-deny + likeness + compose. Absent = ON. */
+  referenceRules?: boolean
+  /** Add the two face clauses — for briefs moving elements between people. */
+  multiPerson?: boolean
+  /** "Nobody looks at the camera." Absent = OFF (a portrait wants the eyeline). */
+  sceneFrame?: boolean
+}): string {
+  const parts: string[] = []
+  if (opts?.referenceRules !== false) {
+    parts.push(opts?.multiPerson === true ? REFERENCE_RULES_MULTI_PERSON : REFERENCE_RULES)
+  }
+  if (opts?.sceneFrame === true) parts.push(SCENE_FRAME_RULE)
+  return parts.join(" ")
+}