@nodaro/prompts 1.0.1

package/src/prompt-templates.ts

@@ -0,0 +1,50 @@
+/**
+ * Default prompt templates and template resolution/application functions.
+ * Shared between frontend and backend.
+ */
+
+export const DEFAULT_TEMPLATES: Record<string, string> = {
+  "character-description": "Include character '{name}': {description}.",
+  "object-description": "Include object '{name}': {description}.",
+  "location-description": "Include location '{name}': {description}.",
+  "face-description":
+    "Include the exact face and facial features of '{name}' from the reference image. Maintain perfect likeness and facial identity.",
+  // `-generation` templates drive standalone entity generation routes
+  // (`/v1/generate-character`, `/v1/generate-face`, etc.). Duplicated between
+  // frontend and backend historically; consolidated here so the backend DAG
+  // orchestrator produces the same prompt as a single-node HTTP call.
+  "character-generation":
+    "Create a full-body character portrait: {description}. Style: {style}. Gender: {gender}. High quality, detailed, consistent lighting, neutral background.",
+  "object-generation":
+    "Create a product photo of: {description}. Category: {category}. Clean background, professional studio lighting, high detail.",
+  "location-generation":
+    "Create a cinematic scene of: {description}. Category: {category}. Atmospheric lighting, high detail, wide angle.",
+  "face-generation":
+    "Create a professional close-up face portrait headshot: {description}. Style: {style}. Looking directly at camera, sharp focus on facial features, clean background, studio lighting, high resolution. Maintain exact facial identity and features from the reference image.",
+  "generate-image-wrapper": "{userPrompt}\n{assetDescriptions}",
+}
+
+/**
+ * Resolve a template by key, checking flow-level overrides, then user overrides,
+ * then the system defaults.
+ */
+export function resolveTemplate(
+  key: string,
+  userTemplates?: Record<string, string>,
+  flowTemplates?: Record<string, string>,
+): string {
+  return flowTemplates?.[key] ?? userTemplates?.[key] ?? DEFAULT_TEMPLATES[key] ?? ""
+}
+
+/**
+ * Replace `{varName}` placeholders in a template string with values from vars.
+ */
+export function applyTemplate(
+  template: string,
+  vars: Record<string, string>,
+): string {
+  return Object.entries(vars).reduce(
+    (result, [key, value]) => result.replaceAll(`{${key}}`, value || ""),
+    template,
+  )
+}

package/src/prompt-wizard-categories.ts

@@ -0,0 +1,334 @@
+/**
+ * Prompt Wizard — shared types, category definitions, and provider capabilities.
+ *
+ * Used by the backend (system prompt building) and frontend (type-checking, UI).
+ */
+
+// ── Types ──
+
+export interface WizardCategory {
+  readonly key: string
+  readonly label: string
+  readonly optional?: boolean
+}
+
+export interface WizardQuestion {
+  category: string
+  label: string
+  options: WizardOption[]
+  selected: string | string[] | null
+  allowCustom: boolean
+  multi?: boolean
+}
+
+export interface WizardOption {
+  value: string
+  label: string
+  description?: string
+}
+
+export interface WizardSelection {
+  category: string
+  value: string
+  isCustom: boolean
+}
+
+export interface RecommendedModel {
+  provider: string
+  field: string
+  label: string
+  reason: string
+}
+
+export interface WizardNodeContext {
+  connectedInputTypes?: string[]
+  referenceImageCount?: number
+  referenceImageUrls?: string[]
+  hasSourceVideo?: boolean
+}
+
+export interface ModelChange {
+  field: string
+  value: string
+}
+
+// ── Category Definitions ──
+
+// ── Image (generate-image, image-to-image) ──
+export const IMAGE_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "subject", label: "Subject" },
+  { key: "environment", label: "Environment / Setting" },
+  { key: "lighting", label: "Lighting" },
+  { key: "camera-composition", label: "Camera & Composition" },
+  { key: "style-medium", label: "Style / Medium" },
+  { key: "mood-tone", label: "Mood & Tone" },
+  { key: "details-texture", label: "Details / Texture", optional: true },
+  { key: "what-to-avoid", label: "What to Avoid", optional: true },
+]
+
+// ── Video (text-to-video, image-to-video, video-to-video, motion-transfer, extend-video, speech-to-video) ──
+export const VIDEO_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "subject-action", label: "Subject & Action" },
+  { key: "environment", label: "Environment / Setting" },
+  { key: "camera-movement", label: "Camera Movement" },
+  { key: "pacing-speed", label: "Pacing / Speed" },
+  { key: "style-look", label: "Style / Look" },
+  { key: "mood-tone", label: "Mood & Tone" },
+]
+
+// ── Music (generate-music, suno-generate) ──
+export const MUSIC_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "genre-style", label: "Genre / Style" },
+  { key: "mood-energy", label: "Mood & Energy" },
+  { key: "instruments", label: "Instruments" },
+  { key: "tempo", label: "Tempo" },
+  { key: "vocals", label: "Vocals" },
+  { key: "production-style", label: "Production Style" },
+]
+
+// ── Audio / SFX (text-to-audio) ──
+export const AUDIO_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "sound-type", label: "Sound Type" },
+  { key: "environment", label: "Environment" },
+  { key: "intensity", label: "Intensity" },
+  { key: "texture-quality", label: "Texture / Quality" },
+]
+
+// ── Text / General (text-prompt) ──
+export const TEXT_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "purpose-intent", label: "Purpose / Intent" },
+  { key: "tone-voice", label: "Tone / Voice" },
+  { key: "audience", label: "Audience" },
+  { key: "length-format", label: "Length / Format" },
+]
+
+// ── LLM Chat (llm-chat) ──
+export const LLM_CHAT_WIZARD_CATEGORIES: readonly WizardCategory[] = [
+  { key: "task", label: "Task / Goal" },
+  { key: "tone", label: "Tone & Style" },
+  { key: "format", label: "Output Format" },
+  { key: "constraints", label: "Constraints" },
+]
+
+// ── Node Type Mapping ──
+
+const NODE_TYPE_TO_CATEGORIES: Record<string, readonly WizardCategory[]> = {
+  "llm-chat": LLM_CHAT_WIZARD_CATEGORIES,
+  "generate-image": IMAGE_WIZARD_CATEGORIES,
+  "image-to-image": IMAGE_WIZARD_CATEGORIES,
+  "modify-image": IMAGE_WIZARD_CATEGORIES,
+  "text-to-video": VIDEO_WIZARD_CATEGORIES,
+  "image-to-video": VIDEO_WIZARD_CATEGORIES,
+  "generate-video": VIDEO_WIZARD_CATEGORIES,
+  "video-to-video": VIDEO_WIZARD_CATEGORIES,
+  "motion-transfer": VIDEO_WIZARD_CATEGORIES,
+  "extend-video": VIDEO_WIZARD_CATEGORIES,
+  "speech-to-video": VIDEO_WIZARD_CATEGORIES,
+  // cinematic-avatar's `prompt` IS a generative prompt (unlike ai-avatar's
+  // verbatim `script`), so the wizard applies — see design spec Part B.
+  "cinematic-avatar": VIDEO_WIZARD_CATEGORIES,
+  "generate-music": MUSIC_WIZARD_CATEGORIES,
+  "suno-generate": MUSIC_WIZARD_CATEGORIES,
+  // Composite wizard targets: same music form as suno-generate, but the backend
+  // system-prompt builder reshapes the OUTPUT per field (not prose):
+  //   :style         → comma-separated Suno *style tags*
+  //   :negativeStyle → comma-separated tags of styles/sounds to AVOID
+  //   :lyrics        → full sectioned song LYRICS ([Verse]/[Chorus]/…)
+  "suno-generate:style": MUSIC_WIZARD_CATEGORIES,
+  "suno-generate:negativeStyle": MUSIC_WIZARD_CATEGORIES,
+  "suno-generate:lyrics": MUSIC_WIZARD_CATEGORIES,
+  "text-to-audio": AUDIO_WIZARD_CATEGORIES,
+  "text-prompt": TEXT_WIZARD_CATEGORIES,
+}
+
+export function getCategoriesForNodeType(nodeType: string): readonly WizardCategory[] | undefined {
+  return NODE_TYPE_TO_CATEGORIES[nodeType]
+}
+
+/** Node types that support the wizard (excludes edit-image, text-to-speech, lip-sync) */
+export function isWizardSupported(nodeType: string): boolean {
+  return nodeType in NODE_TYPE_TO_CATEGORIES
+}
+
+// ── Provider Capabilities (for model recommendation) ──
+// Must be updated when providers are added (see Provider Enum Sync in CLAUDE.md)
+
+export const PROVIDER_CAPABILITIES: Record<string, Record<string, string>> = {
+  "generate-image": {
+    "flux": "Photorealistic, highly detailed, best overall quality",
+    "flux-flex": "Fast Flux variant, good quality at lower cost",
+    "flux-kontext": "Character consistency, reference-image-aware generation",
+    "flux-kontext-max": "Premium character consistency with highest detail",
+    "nano-banana": "Fast generation, style flexibility, reference image support",
+    "nano-banana-pro": "Higher quality Nano Banana with better detail",
+    "nano-banana-2": "Latest Nano Banana with resolution options (1K/2K/4K)",
+    "gpt-image": "Creative concepts, illustration, variable quality tiers",
+    "gpt-image-2": "Latest GPT Image — sharp text, photorealism, 1K/2K/4K resolution",
+    "grok": "General purpose, good text understanding",
+    "imagen4": "Google's latest, strong photorealism and text rendering",
+    "imagen4-fast": "Faster Imagen 4 variant",
+    "imagen4-ultra": "Highest quality Imagen 4",
+    "ideogram-v3": "Best for typography, text-in-image, logos, reference images",
+    "qwen": "Versatile, good prompt adherence",
+    "seedream": "Artistic, painterly styles, creative interpretation",
+    "seedream-5-lite": "Lighter Seedream, faster artistic generation",
+    "z-image": "Experimental, novel generation approaches",
+    "wan-2.7":     "Wan 2.7 T2I — 1K/2K/4K, up to 9 ref images",
+    "wan-2.7-pro": "Wan 2.7 Pro T2I — higher quality, 1K/2K/4K",
+    "flux-2-klein": "Open Flux 2 9B via Replicate — fast, no safety filter",
+    "flux-2-pro": "BFL Flux 2 Pro via Replicate — flagship quality, safety_tolerance=5 (max for Pro)",
+    "flux-2-max": "BFL Flux 2 Max via Replicate — even larger than Pro, safety_tolerance=5, up to 8 refs (variable pricing)",
+  },
+  "image-to-image": {
+    "nano-banana": "Fast style transfer and transformation",
+    "nano-banana-pro": "Higher quality transformations",
+    "grok-i2i": "General purpose image transformation",
+    "flux-i2i": "High quality image-to-image with strong prompt adherence",
+    "flux-pro-i2i": "Premium Flux transformation",
+    "gpt-image-i2i": "Creative reinterpretation of source images",
+    "gpt-image-2-i2i": "Latest GPT Image — pixel-level edits with original lighting/texture preservation, up to 4K",
+    "ideogram-edit": "Instruction-based editing with text preservation",
+    "ideogram-remix": "Style remixing while preserving structure",
+    "ideogram-reframe": "Aspect ratio changes with AI fill",
+    "qwen-i2i": "Versatile transformation",
+    "qwen-edit": "Instruction-based editing",
+    "seedream-edit": "Artistic style editing",
+    "seedream-5-lite-i2i": "Light artistic transformation",
+    "flux-kontext": "Character-consistent edits with reference awareness",
+    "flux-kontext-max": "Premium character-consistent editing",
+    "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",
+    "flux-2-pro": "BFL Flux 2 Pro via Replicate — flagship quality with reference images, safety_tolerance=5",
+    "flux-2-max": "BFL Flux 2 Max via Replicate — even larger sibling, up to 8 refs, safety_tolerance=5 (variable pricing)",
+  },
+  "modify-image": {
+    "nano-banana": "Fast style transfer and transformation",
+    "nano-banana-pro": "Higher quality transformations",
+    "nano-banana-edit": "AI-powered image editing with instructions",
+    "grok-i2i": "General purpose image transformation",
+    "flux-i2i": "High quality image-to-image with strong prompt adherence",
+    "flux-pro-i2i": "Premium Flux transformation",
+    "gpt-image-i2i": "Creative reinterpretation of source images",
+    "gpt-image-2-i2i": "Latest GPT Image — pixel-level edits with original lighting/texture preservation, up to 4K",
+    "ideogram-edit": "Instruction-based editing with text preservation",
+    "ideogram-remix": "Style remixing while preserving structure",
+    "ideogram-reframe": "Aspect ratio changes with AI fill",
+    "qwen-i2i": "Versatile transformation",
+    "qwen-edit": "Instruction-based editing",
+    "seedream-edit": "Artistic style editing",
+    "seedream-5-lite-i2i": "Light artistic transformation",
+    "flux-kontext": "Character-consistent edits with reference awareness",
+    "flux-kontext-max": "Premium character-consistent editing",
+    "kontext-multi": "Multi-image Kontext via Replicate — up to 4 refs, no safety filter",
+    "flux-2-pro": "BFL Flux 2 Pro via Replicate — flagship quality with reference images, safety_tolerance=5",
+    "flux-2-max": "BFL Flux 2 Max via Replicate — even larger sibling, up to 8 refs, safety_tolerance=5 (variable pricing)",
+  },
+  "generate-mask": {
+    "grounded-sam": "Text-prompted segmentation — isolates the subject you describe in words (Grounding DINO + Segment Anything)",
+  },
+  "text-to-video": {
+    "minimax": "Versatile, good motion quality, reliable",
+    "veo3": "Google's latest, photorealistic, audio generation support",
+    "veo3.1": "Enhanced VEO with improved motion",
+    "veo3_lite": "Cheapest VEO tier, 4/6/8s output, ideal for high-volume/test runs",
+    "kling": "Cinematic, precise camera control, high motion quality",
+    "kling-turbo": "Faster Kling generation",
+    "kling-3.0": "Latest Kling with motion control and multi-shot",
+    "grok": "General purpose video generation",
+    "seedance": "Seedance 1.5 Pro — general-purpose cinematic model, end-frame support, 4/8/12s",
+    "seedance-2": "Seedance 2.0 — multimodal refs (9 images / 3 videos / 3 audio), native multi-track audio, multi-shot storytelling, 4-15s",
+    "seedance-2-fast": "Seedance 2.0 Fast — same multimodal + audio capabilities, cheaper and quicker",
+    "seedance-2-mini": "Seedance 2.0 Mini — same multimodal + audio capabilities, budget tier, 480p/720p, 4-15s",
+    "wan": "Versatile, good for animations and transformations",
+    "wan-turbo": "Faster Wan generation",
+    "hailuo-standard": "Standard quality, cost-effective",
+    "bytedance-lite": "Fast, lightweight generation",
+    "bytedance-pro": "Higher quality ByteDance",
+    "runway-kie": "Runway via KIE, strong cinematic quality",
+    "wan-2.7-t2v": "Wan 2.7 T2V — 2–15s, 720p/1080p",
+    "happyhorse":   "HappyHorse T2V — 3–15s, 720p/1080p",
+    "ltx-2.3-pro":  "Lightricks LTX 2.3 Pro — text/image/audio→video, 6–10s, up to 4K",
+    "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — text/image→video, 6–20s, up to 4K",
+    "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
+    "grok-imagine-video-1.5": "Grok Imagine 1.5 — image-to-video only; requires an input image",
+  },
+  "image-to-video": {
+    "minimax": "Versatile animation from still images",
+    "veo3": "Photorealistic animation with audio",
+    "veo3.1": "Enhanced image animation",
+    "veo3_lite": "Cheapest VEO tier — half the cost of Fast, 4/6/8s + audio + first/last-frame",
+    "kling": "Precise motion from stills, camera control",
+    "kling-turbo": "Faster Kling animation",
+    "kling-3.0": "Latest Kling with advanced motion",
+    "kling-master": "Highest quality Kling",
+    "seedance": "Seedance 1.5 Pro — general i2v from a still, start/end frame, 4/8/12s",
+    "seedance-2": "Seedance 2.0 — start/end frame + multimodal refs, native audio, 4-15s",
+    "seedance-2-fast": "Seedance 2.0 Fast — same capabilities, cheaper and quicker",
+    "seedance-2-mini": "Seedance 2.0 Mini — same capabilities, budget tier, 480p/720p",
+    "hailuo-2.3-pro": "Premium Hailuo animation",
+    "hailuo-2.3": "Standard Hailuo animation",
+    "hailuo-standard": "Cost-effective animation",
+    "wan-i2v": "Versatile image-to-video",
+    "wan-turbo": "Fast image animation",
+    "bytedance-lite": "Fast, lightweight",
+    "bytedance-pro": "Higher quality ByteDance",
+    "bytedance-pro-fast": "Fast premium ByteDance",
+    "grok-i2v": "General purpose animation",
+    "runway-kie": "Cinematic image animation",
+    "wan-2.7-i2v":    "Wan 2.7 I2V — 2–15s, 720p/1080p, start+end frame",
+    "happyhorse-i2v":  "HappyHorse I2V — 3–15s, 720p/1080p",
+    "happyhorse-ref2v": "HappyHorse Ref2V — multi-ref image to video, 3–15s",
+    "ltx-2.3-pro":  "Lightricks LTX 2.3 Pro — start/end frame i2v + audio→video, 6–10s, up to 4K",
+    "ltx-2.3-fast": "Lightricks LTX 2.3 Fast — start/end frame i2v, 6–20s, up to 4K",
+    "gemini-omni-video": "Google Gemini Omni — multimodal video with native audio, 4–10s, up to 4K.",
+    "grok-imagine-video-1.5": "Grok Imagine 1.5 — stylized animation, 1–15s, 480p/720p (image required)",
+  },
+  "video-to-video": {
+    "wan": "Style transfer and video transformation",
+    "luma-modify": "Video modification preserving structure",
+    "runway-aleph": "Advanced video transformation",
+    "happyhorse-edit": "HappyHorse video-to-video editing",
+  },
+  "motion-transfer": {
+    "kling": "Motion transfer with camera control",
+    "kling-3.0": "Advanced motion transfer",
+    "wan-animate-move": "Movement-based motion transfer",
+    "wan-animate-replace": "Subject replacement with motion preservation",
+  },
+  "extend-video": {
+    "veo-extend": "Extend VEO-generated videos",
+    "runway-extend": "Extend Runway-generated videos",
+    "seedance-2-extend": "Extend ANY video by URL — seamless trim-stitched continuation with audio (Seedance 2.0)",
+  },
+  "speech-to-video": {
+    "wan-speech": "Wan 2.2 speech-driven video generation",
+  },
+  "ai-avatar": {
+    "heygen": "HeyGen — industry-standard AI avatars; Avatar IV for established quality, Avatar V for premium fidelity",
+  },
+  "cinematic-avatar": {
+    "heygen": "HeyGen Cinematic Avatar — prompt-driven generative clip (Seedance pipeline) from 1-3 avatar looks",
+  },
+  "generate-music": {
+    "minimax": "General music generation, multiple genres",
+  },
+  "suno-generate": {
+    "V4": "Standard Suno generation",
+    "V4_5": "Improved quality and coherence",
+    "V4_5PLUS": "Enhanced V4.5 with better production",
+    "V4_5ALL": "Full-featured V4.5",
+    "V5": "Latest Suno with highest quality",
+  },
+  "text-to-audio": {
+    "elevenlabs-sfx": "High quality sound effects and ambient audio",
+  },
+  "text-prompt": {},
+}
+
+/** Reference image role options (for multi-select) */
+export const REFERENCE_IMAGE_ROLES: readonly WizardOption[] = [
+  { value: "character", label: "Character reference", description: "Preserve identity, face, clothing exactly" },
+  { value: "style-mood", label: "Style / mood reference", description: "Apply lighting, color palette, atmosphere only" },
+  { value: "composition", label: "Composition reference", description: "Follow layout and framing" },
+  { value: "scene-background", label: "Scene / background reference", description: "Use as environment, ignore subjects" },
+  { value: "texture-material", label: "Texture / material reference", description: "Apply surface details and textures" },
+]

package/src/provider-prompt-doctrine.ts

@@ -0,0 +1,85 @@
+/**
+ * Per-provider prompting doctrine — the single source of truth for "how to
+ * prompt model family X well". Consumed by:
+ *   1. backend/src/prompts/prompt-wizard-system.ts  (enhance/generate system prompts)
+ *   2. backend/scripts/gen-skills (provider-prompting block in video node skills)
+ *   3. backend/src/lib/mcp/tools/models.ts          (list_models promptTips)
+ *   4. compact recipes in MCP tool descriptions point here via get_node_skill
+ *
+ * Sources, in precedence order (conflicts resolve top-down):
+ *   - Official BytePlus ModelArk "Dreamina Seedance 2.0 series prompt guide"
+ *     https://docs.byteplus.com/en/docs/ModelArk/2222480
+ *   - Official launch post https://seed.bytedance.com/en/blog/official-launch-of-seedance-2-0
+ *   - KIE API docs https://docs.kie.ai/market/bytedance/seedance-2
+ */
+export interface ProviderPromptDoctrine {
+  /** MODEL_CATALOG ids this doctrine covers. */
+  readonly providers: readonly string[]
+  /** Human heading for skill docs, e.g. "Seedance 2.0 (seedance-2, seedance-2-fast)". */
+  readonly heading: string
+  /** Short bullets for compact surfaces (list_models promptTips). ≤220 chars each. */
+  readonly tips: readonly string[]
+  /** Full markdown doctrine for system prompts and generated skill docs. */
+  readonly doctrine: string
+}
+
+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)",
+  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'.",
+  ],
+  doctrine: `Prompt structure (front-load what matters most):
+precise subject → action details → scene/environment → lighting & color tone → camera movement → visual style → image quality → constraints.
+
+**Shots & pacing**
+- Storyboard complex videos as "Shot 1: … Shot 2: … Shot 3: …" in event order. Do NOT attach timestamps (e.g. "(0-3s)") — precise-timing support is officially unstable and forcing durations can break generation; let the model pace naturally.
+- Per shot cover, in order: camera move or transition, subject action + expression, spatial/position change, audio for that shot.
+- One camera movement type per shot — never ask for push + pan + orbit at once (image instability).
+- 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".
+
+**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".
+- Character identity: ONE close-up headshot + ONE full-body image is ideal. Do NOT attach multi-view/three-view character sheets — the model reads the views as separate people, causing identity drift and twin duplicates.
+- 4-5 assets total works best (1-2 character images + 1 scene image + 1 camera-movement video + 1 audio clip). Maxing out the 9-image/3-video/3-audio limits degrades feature priority and adherence.
+- Editing/extension instructions name clips directly: "Extend Video 1 backward…", "Remove the chair from Video 1". Saying "reference Video 1" flips the model into reference mode and breaks the edit. Track completion: "Video 1 + [transition description] + followed by Video 2" (≤3 clips, ≤15s total).
+
+**Audio (native multi-track: music + ambience + voice, stereo)**
+- Cue the layers separately with the official symbols: full-width parentheses for music （slow jazz piano in the background）, angle brackets for sound effects <rain tapping on glass>, and dialogue as quoted speech: the man says "It's not that bad". Seedance also accepts curly-brace dialogue, but on Nodaro curly braces are reserved for prompt variables — always use quotes for dialogue here.
+- Mark the language for non-English/Chinese dialogue ("says in Japanese …").
+- With a reference voice attached, also describe the timbre in words: "the low, warm, finely grainy middle-aged male voice of Audio 1".
+
+**Quality & constraints**
+- Quality tail: "HD, rich details, cinematic texture, natural colors, stable picture."
+- Anti-junk constraints (these official templates ARE negative-form): "keep it subtitle-free", "avoid generating any text or subtitles", "do not generate a watermark", "do not generate a logo". Landscape output is markedly less subtitle-prone than portrait — generate 16:9 and crop when portrait text-safety matters.
+- There is NO negative-prompt parameter on Seedance — all constraints belong in the prompt text itself.
+
+**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.`,
+}
+
+export const PROVIDER_PROMPT_DOCTRINES: readonly ProviderPromptDoctrine[] = [
+  SEEDANCE_2_DOCTRINE,
+]
+
+const DOCTRINE_BY_PROVIDER: ReadonlyMap<string, ProviderPromptDoctrine> = new Map(
+  PROVIDER_PROMPT_DOCTRINES.flatMap((d) => d.providers.map((p) => [p, d] as const)),
+)
+
+/** Full doctrine for a provider id, or undefined when none exists. */
+export function getPromptDoctrine(providerId: string): ProviderPromptDoctrine | undefined {
+  return DOCTRINE_BY_PROVIDER.get(providerId)
+}
+
+/** Compact tips for a provider id ([] when none) — used by list_models. */
+export function getPromptTips(providerId: string): readonly string[] {
+  return DOCTRINE_BY_PROVIDER.get(providerId)?.tips ?? []
+}

package/src/render-quality.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical catalog of Render Engine / Quality presets.
+ *
+ * "Render Quality" is the pure technical-stamp dimension — what tool the image
+ * appears to have been rendered through, or what quality stamp it carries.
+ * Distinct from Style (artistic medium), Lens (optics), and Camera Format
+ * (capture medium): a "raytracing" hint says nothing about whether the look
+ * is anime or photorealistic; it just promises ray-traced-grade reflections,
+ * shadows, and global illumination.
+ *
+ * Three loose families, each adding a different kind of authority signal:
+ *  - Engines: name a real render package (Unreal 5, Octane, Cycles…). Useful
+ *    for hyper-stylized 3D illustration or game-trailer aesthetics.
+ *  - Render-quality keywords: the technical buzzwords that lock in modern
+ *    physically-correct lighting (raytracing, PBR, GI, lumen).
+ *  - Resolution / Detail: explicit "sharp + detailed" stamps (4K/8K/16K,
+ *    "ultra-detailed").
+ *  - Style stamps: portmanteau quality markers ("masterpiece", "raw photo",
+ *    "award-winning") that providers strongly weight.
+ *
+ * Single-pick — only one render-quality stamp is applied per consumer. Shared
+ * between picker UI and prompt-hint injection in the frontend DAG executor
+ * and the backend orchestrator.
+ */
+
+export interface RenderQuality {
+  readonly id: string
+  readonly label: string
+  readonly description: string
+  readonly promptHint: string
+}
+
+export const RENDER_QUALITIES: ReadonlyArray<RenderQuality> = [
+  // ---------------------------- Engines ----------------------------
+  { id: "unreal-engine-5",    label: "Unreal Engine 5",   description: "Real-time path-traced UE5 look", promptHint: "rendered in Unreal Engine 5, real-time path-traced lighting with Lumen reflections, Nanite-grade micro-detail and cinematic post-processing" },
+  { id: "blender-cycles",     label: "Blender Cycles",    description: "Cycles unbiased path tracing",   promptHint: "rendered in Blender Cycles, unbiased path-traced lighting with physically accurate shadows, soft global illumination and clean denoise" },
+  { id: "octane-render",      label: "Octane Render",     description: "GPU spectral path tracing",      promptHint: "rendered in Octane, GPU spectral path tracing with hyper-realistic materials, vivid color response and crisp specular highlights" },
+  { id: "redshift",           label: "Redshift",          description: "Production GPU biased renderer", promptHint: "rendered in Redshift, production-quality GPU rendering with rich material response, controlled GI and film-grade depth" },
+  { id: "houdini-mantra",     label: "Houdini Mantra",    description: "VFX-grade physical rendering",   promptHint: "rendered in Houdini Mantra, VFX-grade physically-based rendering with subtle volumetric scatter and ultra-clean shading" },
+  { id: "arnold-render",      label: "Arnold Render",     description: "Industry-standard VFX path tracer", promptHint: "rendered in Solid Angle Arnold, industry-standard VFX path-traced lighting with physically accurate light transport, smooth noise-free shading, and the flagship Pixar / ILM / Sony feature-film polish" },
+  { id: "corona-renderer",    label: "Corona Renderer",   description: "Photorealistic archviz unbiased renderer", promptHint: "rendered in Chaos Corona, unbiased photorealistic rendering with crisp daylight global illumination, refined material response and the signature architectural-visualization clarity" },
+  { id: "vray",               label: "V-Ray",             description: "Industry-standard product / archviz / VFX renderer", promptHint: "rendered in Chaos V-Ray, industry-standard hybrid path-traced production rendering with razor-sharp detail, accurate reflections and the polished product-viz / archviz / VFX finish" },
+  { id: "aces",               label: "ACES",              description: "Cinema-grade ACES color management", promptHint: "graded through the ACES (Academy Color Encoding System) color management workflow, modern cinema-grade tonal response with consistent wide-gamut color rendering, filmic highlight rolloff and reference-quality color fidelity" },
+
+  // ---------------------------- Render-quality keywords ----------------------------
+  { id: "raytracing",                    label: "Ray Tracing",            description: "Accurate reflections + shadows", promptHint: "ray-traced rendering, physically accurate reflections, refractions and contact shadows with realistic light bounce" },
+  { id: "physically-based-rendering",    label: "PBR",                    description: "Physically-based materials",     promptHint: "physically-based rendering with energy-conserving materials, accurate metallic/roughness response and realistic Fresnel falloff" },
+  { id: "global-illumination",           label: "Global Illumination",    description: "Realistic light bounce",         promptHint: "global illumination, realistic indirect light bounce with soft color bleeding between surfaces and naturally lit shadow regions" },
+  { id: "lumen-reflections",             label: "Lumen Reflections",      description: "Real-time dynamic GI",           promptHint: "Lumen-style real-time dynamic global illumination with crisp screen-space reflections, soft contact shadows and beautifully lit indirect bounces" },
+
+  // ---------------------------- Resolution / Detail ----------------------------
+  { id: "8k-uhd",          label: "8K UHD",          description: "Ultra-sharp 8K resolution",         promptHint: "8K ultra-high-definition resolution, ultra-sharp detail with every micro-texture preserved and zero softness" },
+  { id: "4k-uhd",          label: "4K UHD",          description: "Crisp 4K resolution",                promptHint: "4K UHD resolution, crisp detail with cinema-grade clarity and clean edge definition" },
+  { id: "16k-megapixel",   label: "16K Megapixel",   description: "Insanely high-resolution detail",    promptHint: "16K megapixel-grade resolution, insanely high-resolution detail with surgically clean edges and microscopic surface fidelity" },
+  { id: "ultra-detailed",  label: "Ultra Detailed",  description: "Maximum micro-detail rendering",     promptHint: "ultra-detailed rendering with intricate micro-surface detail, fine pore-level fidelity and meticulously preserved fine structures" },
+
+  // ---------------------------- Style stamps ----------------------------
+  { id: "raw-photo",       label: "Raw Photo",       description: "Unprocessed photographic feel",      promptHint: "raw photograph aesthetic, unprocessed natural color science, authentic photographic detail and untouched documentary realism" },
+  { id: "masterpiece",     label: "Masterpiece",     description: "Hand-of-an-expert quality stamp",    promptHint: "masterpiece-quality rendering, hand-of-an-expert level execution with refined composition, immaculate detail and curated finish" },
+  { id: "award-winning",   label: "Award Winning",   description: "Award-circuit caliber",              promptHint: "award-winning quality, award-circuit caliber image with editorial-grade composition, magazine-cover finish and signature visual authority" },
+
+  // ---------------------------- Lighting / Image-quality passes ----------------------------
+  { id: "volumetric-lighting", label: "Volumetric Lighting", description: "God-ray volumetric light shafts cutting through atmosphere", promptHint: "volumetric lighting with god-ray light shafts cutting through atmospheric haze, beams of illuminated dust and particulate scattering through the scene" },
+  { id: "photon-mapping",      label: "Photon Mapping",      description: "Caustic-aware photon-mapped global illumination renderer", promptHint: "photon-mapped global illumination with caustic-aware light transport, accurate refractive light patterns through glass and water and physically correct indirect bounces" },
+  { id: "ai-upscaled",         label: "AI Upscaled",         description: "Neural-network upscaled detail enhancement, sharp super-resolution", promptHint: "neural-network AI-upscaled detail enhancement, sharp super-resolution clarity with reconstructed micro-detail and surgically clean edge definition" },
+  { id: "denoised",            label: "Denoised",            description: "Clean noise-removed pristine rendering, no grain or speckle", promptHint: "clean denoised rendering with noise removed entirely, pristine smooth surfaces and zero grain or speckle across shadows and midtones" },
+] as const
+
+const renderQualityById = new Map<string, RenderQuality>(
+  RENDER_QUALITIES.map((r) => [r.id, r]),
+)
+
+export function getRenderQuality(id: string | undefined | null): RenderQuality | undefined {
+  if (!id) return undefined
+  return renderQualityById.get(id)
+}
+
+export function getRenderQualityLabel(id: string | undefined | null, fallback?: string): string {
+  const r = getRenderQuality(id)
+  if (r) return r.label
+  if (fallback !== undefined) return fallback
+  return (id ?? "").replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
+export function getRenderQualityPromptHint(id: string | undefined | null): string {
+  return getRenderQuality(id)?.promptHint ?? ""
+}
+
+export const RENDER_QUALITY_IDS: ReadonlyArray<string> = RENDER_QUALITIES.map((r) => r.id)