Refine visual identity guidance across pipelines

skills/pipelines/explainer/asset-director.md

@@ -79,9 +79,13 @@ For each script section:
 Process asset tasks grouped by tool for efficiency:
 
 **Images (`image_selector`)**:
-1. Build the prompt: `playbook.asset_generation.image_prompt_prefix` + scene description + style cues
+1. Build the prompt from the scene's actual purpose:
+   - scene-specific shot/lighting/texture cues from `shot_language`, `shot_intent`, and `texture_keywords`
+   - an adapted visual anchor from the playbook or custom identity
+   - the concrete subject/action/environment
+   Use `lib/shot_prompt_builder.py` when helpful.
 2. Add negative prompt from playbook
-3. Include consistency anchors (same palette, same style across all images)
+3. Include consistency anchors (same character/world/palette family), but do NOT reuse the exact same phrasing for every image
 4. Generate and verify the file exists
 5. If the result doesn't match expectations, refine the prompt and regenerate (max 2 retries)
 
@@ -202,7 +206,7 @@ the AI model's training data — it may be wrong or outdated.
 ## Common Pitfalls
 
 - **Generating before checking budget**: Always estimate total cost first. A 60-second video with 15 images can burn $3+ quickly.
-- **Inconsistent image style**: Each image_selector call is independent. Without explicit consistency anchors in every prompt, images will drift. Always include the playbook prefix.
+- **Inconsistent image style**: Each image_selector call is independent. Use consistent anchors, but adapt them per scene. If you paste the same style prefix into every prompt, the video will feel machine-made and repetitive.
 - **Ignoring narration timing**: If TTS produces 12s of audio for a 10s section, the edit phase will struggle. Check durations.
 - **Missing pronunciation guide**: "PostgreSQL" or "Kubernetes" will be mispronounced without explicit guidance.
 - **One retry then give up**: If an image doesn't match, refine the prompt specifically — don't just retry the same prompt.

skills/pipelines/explainer/proposal-director.md

@@ -117,17 +117,36 @@ Choose the structure that best fits the research findings:
 | `tutorial` | Audience wants to DO something | `audience_insights.common_questions` are how-to |
 | `story` | Human interest angle exists | Expert voices or real-world cases available |
 
-#### 3c: Visual Approach and Playbook
+#### 3c: Visual Identity — Design It, Don't Pick It
 
-Match the visual approach to the content. **Check Remotion availability first** — if `video_compose` reports `render_engines.remotion: true`, the Remotion render path unlocks animated text cards, stat cards, charts, spring-physics transitions, and component-based scenes. This should change your visual design:
+**Your job is to design a visual identity for THIS video, not to pick from a preset menu.**
 
-| Content Type | Visual Approach (Remotion available) | Visual Approach (FFmpeg only) | Playbook |
-|--------------|--------------------------------------|-------------------------------|----------|
-| Technical architecture/process | Remotion animated diagrams, flowcharts with spring transitions | Static diagrams with Ken Burns motion | `minimalist-diagram` |
-| Data-heavy narrative | Remotion stat cards, animated charts, comparison cards | Static image cards with zoom-in | `flat-motion-graphics` |
-| Professional/business | Remotion text cards with clean typography | Image-based title cards | `clean-professional` |
-| Storytelling/analogy | Remotion scenes with animated character cards | Image sequence with pan | Warm/narrative playbook |
-| Tutorial/how-to | Screen captures + Remotion callout overlays | Screen captures + static overlays | `minimalist-diagram` |
+The existing playbooks (`clean-professional`, `flat-motion-graphics`, `minimalist-diagram`) are starting points, not destinations. Most videos should get a **custom visual identity** derived from the subject matter, audience, and tone. A video about coffee should feel warm and tactile. A video about cybersecurity should feel technical and urgent. A video about marine biology should feel deep and fluid.
+
+**How to design visual identity:**
+
+1. **Start from the content.** What colors does the subject naturally evoke? What textures, materials, lighting? A video about volcanoes should feel different from a video about meditation — in colors, motion speed, typography weight, and transition style.
+
+2. **Consider the audience.** A Gen Z TikTok audience expects bold, high-contrast, fast motion. A corporate training audience expects restrained, professional, readable. A kids' educational audience expects bright, playful, bouncy.
+
+3. **Consider the tone.** The user's mood board and creative intake should guide this. "Cinematic" means different colors/motion than "playful" which means different from "clinical."
+
+4. **Build the palette from the subject.** Don't default to blue. Choose 2-3 colors that serve the content:
+   - Primary: the dominant brand/feel color
+   - Accent: for emphasis, stats, highlights
+   - Background: sets the overall mood (light = approachable, dark = dramatic/technical)
+
+5. **Use a preset playbook only when it genuinely fits.** If the video is a straightforward corporate explainer, `clean-professional` is fine. But if the topic has its own visual world (nature, space, food, music, sports, history), design a custom identity.
+
+6. **Generate a custom playbook when presets don't match.** Use `lib/playbook_generator.py` to create one from your design decisions. The Remotion theme system will automatically derive colors, fonts, and motion from whatever playbook you create — including custom ones.
+
+**Record your visual identity choices in the proposal_packet:**
+- `production_plan.playbook`: name of preset OR "custom"
+- If custom, include color choices and font choices in the concept's `visual_approach`
+- Include the reasoning: "Warm amber palette because the subject is coffee craftsmanship"
+- Log as decision: `category: "playbook_selection"`
+
+**Check Remotion availability** — if `video_compose` reports `render_engines.remotion: true`, design for animated components (text cards, stat cards, charts, spring transitions). This is a major quality upgrade.
 
 **Remotion components available** (when Remotion engine is active):
 - `text_card` — animated text with spring entrance
@@ -138,7 +157,7 @@ Match the visual approach to the content. **Check Remotion availability first**
 - `chart` — bar, line, pie charts with animated data entry
 - `kpi_grid` — multi-stat dashboard layout
 
-**Important:** When Remotion is available and the playbook is `flat-motion-graphics`, **always design for Remotion component scenes** rather than static AI-generated images with Ken Burns pan. This is the difference between a professional motion graphics video and a slideshow.
+**Important:** When Remotion is available, **always design for Remotion component scenes** rather than static AI-generated images with Ken Burns pan. This is the difference between a professional motion graphics video and a slideshow.
 
 #### 3d: Duration and Platform
 
@@ -401,7 +420,7 @@ The `selected_concept` in the proposal_packet effectively replaces what the old
 **Concept 1: "The 200ms Journey" (data_driven)**
 - Hook: "Every website you visit starts with a 200-millisecond treasure hunt across the internet."
 - Structure: journey — follow a DNS query step by step
-- Visual: minimalist-diagram, animated packet flow
+- Visual: custom signal-map identity — midnight background, electric route traces, packet-flow motion language
 - Duration: 90s (YouTube)
 - Grounded in: recursive resolution timing data, audience gap about multi-step process
 - Why it works: Most viewers think DNS is instant and singular. Showing the real journey is the aha moment.
@@ -409,7 +428,7 @@ The `selected_concept` in the proposal_packet effectively replaces what the old
 **Concept 2: "Your ISP Knows Everything" (contrarian)**
 - Hook: "Your internet provider logs every website you visit. Here's the 40-year-old system that makes it possible."
 - Structure: myth_busting — challenge "private browsing = private" belief
-- Visual: clean-professional, privacy-focused with dark tones
+- Visual: custom surveillance-noir identity — low-key contrast, privacy-warning accents, restrained typography
 - Duration: 75s (YouTube)
 - Grounded in: DNS privacy misconception (audience research), DoH trending signal
 - Why it works: Privacy is emotionally charged. The misconception that HTTPS = full privacy is widespread.
@@ -417,7 +436,7 @@ The `selected_concept` in the proposal_packet effectively replaces what the old
 **Concept 3: "The Internet's Phone Book" (analogy)**
 - Hook: "DNS is a phone book designed in 1983 that somehow still runs the modern internet."
 - Structure: analogy — phone book metaphor through historical evolution
-- Visual: flat-motion-graphics, retro-to-modern visual timeline
+- Visual: custom retro-systems identity — off-white paper base, archival type, neon-modern contrast for present-day beats
 - Duration: 60s (LinkedIn)
 - Grounded in: audience knowledge gap about DNS age, landscape gap (no historical angle found)
 - Why it works: Simplest on-ramp for non-technical audience. The "still works after 40 years" angle is inherently surprising.

skills/pipelines/explainer/scene-director.md

@@ -67,7 +67,7 @@ Transform each script section into 1-3 visual scenes. Each scene is a distinct v
 
 | Type | Best For | Available Tools | Duration Guidance |
 |------|----------|-----------------|-------------------|
-| `hero_title` | Opening titles, dramatic reveals | Remotion HeroTitle (cyan first word, animated underline) | 3-5s |
+| `hero_title` | Opening titles, dramatic reveals | Remotion HeroTitle (theme-driven title treatment) | 3-5s |
 | `stat_card` | Big dramatic numbers, impactful metrics | Remotion StatCard (large stat + subtitle) | 4-6s |
 | `bar_chart` | Category comparisons, rankings | Remotion BarChart (animated grow-up/slide-in/pop) | 5-7s |
 | `line_chart` | Trends, time series, growth curves | Remotion LineChart (draw/fade animation, multi-series) | 5-7s |
@@ -84,7 +84,7 @@ Transform each script section into 1-3 visual scenes. Each scene is a distinct v
 | `broll` | Context, real-world examples | Stock or generated footage | 3-6s |
 | `screen_recording` | Code demos, UI walkthroughs | Recorded or simulated | 5-15s |
 
-**Zero-key scene selection:** When no image/video generation is available, prefer `hero_title`, `stat_card`, `bar_chart`, `line_chart`, `pie_chart`, `kpi_grid`, `comparison`, `callout`, `progress_bar`, and `text_card`. These render entirely from Remotion components with zero external dependencies and produce professional, animated results. See `skills/core/remotion.md` for the proven formula (all-dark backgrounds, KPI data formatting rules, overlay techniques).
+**Zero-key scene selection:** When no image/video generation is available, prefer `hero_title`, `stat_card`, `bar_chart`, `line_chart`, `pie_chart`, `kpi_grid`, `comparison`, `callout`, `progress_bar`, and `text_card`. These render entirely from Remotion components with zero external dependencies and can still feel distinct if you derive color, typography, and pacing from the subject instead of defaulting to a generic dashboard aesthetic.
 
 ### Step 4: Apply the Visual Technique Library
 
@@ -101,15 +101,15 @@ Show the abstract concept alongside its real-world analogy. Split screen or side
 - Example: "Left: actual vector space with dots. Right: a library with books sorted by topic."
 
 **Stat Card Punch**
-Full-screen number with impact animation (scale up, slight bounce). Use `stat_card` type with a dark background and bold accent color. Hold for 4-5 seconds.
+Full-screen number with impact animation (scale up, slight bounce). Use `stat_card` type with a background and accent treatment chosen for the video's identity. Hold for 4-5 seconds.
 - Tools: Remotion StatCard component
-- Example: stat="1ms", subtitle="vs 500ms with traditional search", accentColor="#22D3EE"
+- Example: stat="1ms", subtitle="vs 500ms with traditional search", accentColor="<theme_accent>"
 
 **Data Dashboard Sequence**
 A series of data visualization scenes that tell a story through numbers. Start with a KPI overview, then drill into specific charts. Use section_title overlays to group related data. This pattern works with zero external tools.
 - Tools: Remotion chart components (bar_chart, line_chart, pie_chart, kpi_grid)
 - Example: kpi_grid (4 key stats) → bar_chart (breakdown) → line_chart (trend) → pie_chart (distribution)
-- Always use dark backgrounds (`backgroundColor: "#0F172A"`) for cinematic feel.
+- Choose the background treatment from the visual identity: dark for dramatic/technical subjects, light for approachable/educational, textured or warm when the topic calls for it.
 
 **Before/After Split**
 Show the problem, then the solution using `comparison` type. The comparison card shows dual values side-by-side with animated entrance.
@@ -167,14 +167,14 @@ The style playbook constrains your visual choices:
 | `motion.transitions` | Allowed transition types (e.g., `gentle-fade`, `soft-dissolve`) |
 | `motion.animation_style` | Animation feel (e.g., `ease-in-out, organic curves`) |
 | `motion.pacing_rules` | Minimum hold times (e.g., "hold establishing shots for 2s minimum") |
-| `asset_generation.image_prompt_prefix` | Prepend to all image generation prompts |
+| `asset_generation.image_prompt_prefix` | Distill into a short visual anchor; do not paste verbatim into all prompts |
 | `asset_generation.consistency_anchors` | What must stay consistent across all images (color palette, lighting, style) |
 
 **Checklist before submitting:**
 - [ ] Every scene uses playbook-compatible transitions
 - [ ] All required_asset descriptions include style cues from the playbook
 - [ ] No scene violates pacing rules (min/max duration)
-- [ ] Image descriptions reference playbook's color palette and texture
+- [ ] Image descriptions reference the video's actual visual identity, not just a preset name
 
 ### Step 6: Verify Coverage and Variety
 
@@ -221,4 +221,5 @@ Call `handle_explainer_scene_plan(state, {"scene_plan": scene_plan_json})` to va
 - **Overly ambitious animations**: "Photorealistic 3D fly-through of a data center" can't be generated with current tools. Keep it achievable.
 - **No transition strategy**: Random transitions feel chaotic. Use the playbook's transition rules consistently. Reserve special transitions for topic shifts.
 - **Vague required_assets**: "An image about databases" is useless for prompt engineering. "Isometric illustration of a vector database with embedding vectors floating in 3D space, using the playbook's blue-green palette" is actionable.
+- **Preset thinking**: A scene plan that says "make it flat-motion-graphics" is not enough. The planner must specify what makes THIS video's motion graphics feel distinct.
 - **Static scenes for dynamic concepts**: If the narrator describes a process or transformation, the visual should move. Use animation or progressive reveal, not a static image.