Implementation spec: governance, decision intelligence, theme system, and E2E bug fixes

Implements the 2026-04-02 transformation spec (Phases 1-8) and fixes all
critical bugs found during 5-pipeline E2E testing.

Governance & Decision Intelligence:
- Pipeline-specific stage order in checkpoint (replaces global STAGES list)
- Provider scoring engine (lib/scoring.py) with 7-dimension weighted ranking
- Decision log artifact enforced at proposal/idea stage across all 10 pipelines
- Delivery promise classifier prevents silent motion-to-still downgrades
- Structured shot language in scene_plan schema (camera, lens, lighting, DOF)
- Variation checker and slideshow risk scorer block samey output before render
- Creative intake, capability extension, and creative-intake meta skills
- Final self-review artifact with 5 mandatory checks before presenting output
- Source media review contract for user-supplied footage

Render & Theme System:
- Remotion AnimatedBackground now derives colors from playbook (no more hardcoded
  dark blue fintech gradient on every video)
- video_compose builds custom ThemeConfig from playbook YAML colors/fonts —
  custom playbooks flow through to Remotion automatically
- Explainer component wires theme to all child components (charts, cards, etc.)
- resolveAsset() handles absolute paths on Windows/Unix via file:// URIs
- RENDERER_FAMILY_MAP synced with actual Remotion compositions

Critical Bug Fixes:
- Windows npx subprocess: run_command() resolves .cmd wrappers via shutil.which()
- Silent renderer downgrade: Remotion failure now returns explicit error with
  options instead of silently falling back to FFmpeg
- .env inline comment parsing strips trailing # comments from API keys
- concat_path UnboundLocalError in video_compose finally block
- audio_mixer and showcase_card capture=True kwarg bug
- Selector estimate_cost() calls fixed (_select_tool -> _select_best_tool)
- asset_manifest schema expanded with provider, license, subtype fields
- screen-demo subtitle_gen moved from required to optional tools
- Duration drift detection in post-render final review (>25% warns)

skills/pipelines/animation/asset-director.md

@@ -9,7 +9,7 @@ This stage prepares the actual animated ingredients: narration, diagrams, math r
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Tool path and beat map |
+| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Tool path and beat map |
 | Tools | `tts_selector`, `image_selector`, `video_selector`, `math_animate`, `diagram_gen`, `code_snippet`, `music_gen` — selectors auto-discover all available providers from the registry | Asset production options |
 | Playbook | Active style playbook | Visual consistency |
 
@@ -95,8 +95,38 @@ Recommended metadata keys:
 - missing capabilities are surfaced honestly,
 - every referenced file exists.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Using high-variance generation when a deterministic asset would work better.
 - Rebuilding the same title or label system repeatedly.
 - Hiding failed asset paths instead of reporting them.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/animation/proposal-director.md

@@ -164,7 +164,32 @@ Note: This approach is not yet proven in the OpenMontage pipeline.
 - **Always offer at least one free/local option** alongside paid approaches
 - **Never silently downgrade** — if the best approach needs a key the user doesn't have, say so explicitly
 
-### Step 4: Design Concept Options
+### Step 3d: Mood Board (Before Concepts)
+
+Before developing full concepts, present a quick mood board to catch direction mismatches early:
+
+- **3-5 reference images** (animation style examples from web search — show what each approach LOOKS like)
+- **Color palette direction** (2-3 options, e.g. clean data-viz vs vibrant motion graphics vs sketchy hand-drawn)
+- **Tone references** ("Think: 3Blue1Brown meets Kurzgesagt" or "Think: Pixar short meets infographic")
+- **1-2 animation style samples** (if Manim: mathematical elegance; if Remotion: smooth data transitions; if AI video: cinematic motion)
+
+Ask: **"Does this FEEL like what you're imagining? Any of these off-track?"**
+
+This catches style misalignment before concept design. If the user expected hand-drawn and you're heading toward data-viz, better to know now.
+
+### Step 4: Progressive Reveal and Concept Design
+
+Don't dump the full proposal at once. Build understanding step by step:
+
+1. **Research summary** (2-3 sentences): "Here's what I found..."
+   → User reacts, course-corrects if needed.
+2. **Mood board** (from Step 3d — already presented)
+   → User confirms animation style direction.
+3. **Concept options** (3+ approaches):
+   → Present below.
+4. **Invite mixing** (see Step 4c below).
+5. **Production plan for selected concept** (tools, cost, timeline):
+   → User approves budget and approach.
 
 Build **at least 3 genuinely different concepts.** Start from the `angles_discovered` in the research brief and the animation mode analysis.
 
@@ -233,6 +258,13 @@ Present all concepts clearly to the user. For each concept, show:
 4. **Duration** — how long
 5. **Reuse strategy** — "5 scenes built from 2 templates" vs "8 unique scenes"
 
+#### Step 5b: Invite Mixing
+
+After presenting concepts, always say something like:
+> "You can also mix elements — for example, Concept A's hook with Concept C's animation approach, or Concept B's narrative with Concept A's visual style. What speaks to you?"
+
+If the user mixes, create a new hybrid concept entry in the proposal_packet with clear attribution: "Hook from Concept A, animation approach from Concept C, narrative structure from Concept B."
+
 Let the user select, combine, modify, or redirect.
 
 Record the selection in `selected_concept` with rationale and any modifications.
@@ -351,3 +383,22 @@ Validate the `proposal_packet` artifact against `schemas/artifacts/proposal_pack
 - **Ignoring mathematical accuracy**: If the research brief flagged technical accuracy constraints, the concept MUST respect them. A beautiful but wrong animation is a failure.
 - **Not distinguishing image_animation from clip_video**: These are fundamentally different. Image-based animation (Approach A) generates still images and uses Remotion for motion/crossfade. Clip-based video (Approach B) generates actual video clips with an AI video model. The user should understand this distinction clearly.
 - **Silent downgrades**: If the user picked image_animation but image generation fails, STOP and tell them. Never silently fall back to text cards or diagram stills.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/animation/publish-director.md

@@ -9,7 +9,7 @@ Package the animation so the metadata, thumbnail concept, and platform framing r
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]`, `state.artifacts["script"]["script"]` | Final outputs and topic framing |
+| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["proposal"]["proposal_packet"]`, `state.artifacts["research"]["research_brief"]`, `state.artifacts["script"]["script"]` | Final outputs and topic framing |
 | Playbook | Active style playbook | Visual naming consistency |
 
 ## Process

skills/pipelines/animation/scene-director.md

@@ -9,7 +9,7 @@ You are converting the script into a feasible animation plan. This is the stage
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Beat map and tool path |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Beat map and tool path |
 | Playbook | Active style playbook | Palette, typography, motion consistency |
 
 ## Process

skills/pipelines/animation/script-director.md

@@ -107,6 +107,17 @@ Before submitting the script, verify:
 - [ ] Mathematical accuracy is maintained (if applicable)
 - [ ] Later stages can map scenes cleanly from this script
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - **Writing too many ideas into one section.** One beat = one visual idea.

skills/pipelines/avatar-spokesperson/asset-director.md

@@ -93,9 +93,39 @@ When the EP has triggered a narration-over-graphics pivot (neither `talking_head
 - `pivot_reason`: why the no-avatar path was chosen
 - All other metadata keys remain the same.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Building decorative assets before the narration path is solved.
 - Mixing multiple avatar-generation strategies in one simple spokesperson video.
 - Marking the stage complete when the core presenter asset is still hypothetical.
 - (No-avatar path) Generating filler visuals with no connection to the narration — every image must reinforce the spoken point.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/avatar-spokesperson/script-director.md

@@ -58,6 +58,17 @@ Recommended metadata keys:
 - CTA placement is clear,
 - text overlays are restrained.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Overstuffing one scene because the script reads well on paper.

skills/pipelines/cinematic/asset-director.md

@@ -9,7 +9,7 @@ This stage prepares the usable media for the final cinematic edit: source select
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Scene intent and beat plan |
+| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Scene intent and beat plan |
 | Tools | `subtitle_gen`, `audio_enhance`, `image_selector`, `video_selector`, `music_gen` — selectors auto-discover all available providers from the registry | Optional support asset creation |
 | Playbook | Active style playbook | Brand and typography consistency |
 
@@ -26,7 +26,7 @@ Start with:
 
 These are the primary materials. Everything else is support.
 
-If `brief.metadata.motion_required = true`, actual moving footage or generated video clips are mandatory. In that case:
+If `proposal_packet.metadata.motion_required = true`, actual moving footage or generated video clips are mandatory. In that case:
 
 - stills may be used only as reference material or backing elements inside a larger motion composition,
 - stills may not replace the planned motion shots,
@@ -92,6 +92,17 @@ Recommended metadata keys:
 - every referenced file exists.
 - if motion is required, the asset set contains actual video clips for the motion-led beats.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Generating extra shots before proving the source edit works.
@@ -99,3 +110,22 @@ Recommended metadata keys:
 - Forgetting rights or provenance notes for supplied assets.
 - Quietly downgrading from video clips to still images because one provider or renderer failed.
 - Quietly switching providers or models after the user approved a generation path.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/cinematic/executive-producer.md

@@ -4,14 +4,14 @@
 
 You are the **Executive Producer (EP)** for a cinematic video (trailers, brand films, montages, short dramatic edits). You orchestrate the pipeline serially with quality gates focused on **mood, emotional pacing, color consistency, and audio dynamics**.
 
-**No pre-production stages.** Source footage or direction exists. The EP adds cross-stage gates that enforce emotional arc integrity and cinematic polish.
+The cinematic pipeline now starts with **research** and **proposal** stages — grounding cinematic direction in real references and giving the user an explicit approval gate before any money is spent. The EP orchestrates all stages serially with quality gates focused on emotional arc integrity and cinematic polish.
 
 ## Prerequisites
 
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Pipeline | `pipeline_defs/cinematic.yaml` | Stage definitions |
-| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Skills | All 9 director skills + `meta/reviewer` | Stage execution |
 | Schemas | All artifact schemas | Validation |
 | Playbook | Active style playbook | Quality constraints |
 
@@ -21,18 +21,21 @@ You are the **Executive Producer (EP)** for a cinematic video (trailers, brand f
 EP_STATE:
   pipeline: cinematic
   playbook: <selected>
-  target_duration_seconds: <from brief>
+  target_duration_seconds: <from proposal_packet>
   budget_total_usd: <configured>
   budget_spent_usd: 0.0
 
   # Cinematic-specific
-  emotional_arc: null         # from brief: build → reveal → landing
+  emotional_arc: null         # from proposal_packet: build → reveal → landing
+  delivery_promise: null      # from proposal_packet: motion_required, tone_mode, quality_floor
+  renderer_family: null       # from proposal_packet: locked at proposal stage
   color_grade_target: null    # mood-driven color palette
   hero_moments: []            # key reveal/climax frames
   music_beat_map: null        # audio-driven pacing reference
 
   artifacts:
-    idea: null
+    research: null
+    proposal: null
     script: null
     scene_plan: null
     assets: null
@@ -46,7 +49,7 @@ EP_STATE:
 
 ## Execution Protocol
 
-Same as standard EP: Initialize → Execute stages serially (idea → script → scene_plan → assets → edit → compose → publish) → Final QA.
+Same as standard EP: Initialize → Execute stages serially (research → proposal → script → scene_plan → assets → edit → compose → publish) → Final QA.
 
 Each stage: PREPARE → SPAWN DIRECTOR → REVIEW → GATE DECISION (pass / revise / send-back).
 
@@ -74,13 +77,26 @@ The EP may not switch providers, models, or mediums without user approval once t
 
 ## EP-Specific Cross-Stage Checks
 
-### After IDEA stage:
+### After RESEARCH stage:
 ```
-CHECK: Emotional arc definition
+CHECK: Research grounding
+  - Are visual references specific and relevant (not generic "cinematic" searches)?
+  - Is sound/music direction substantive?
+  - Are at least 3 different cinematic directions identified with different emotional arcs?
+  - Is the motion commitment honest about available capabilities?
+```
+
+### After PROPOSAL stage:
+```
+CHECK: Delivery promise
   - Is the emotional arc explicit (build → reveal → landing)?
   - Is source mode clear (supplied footage vs generated inserts)?
-  - Does the brief explicitly say whether motion is required?
-  - Is the target mood defined and achievable?
+  - Does the proposal explicitly say whether motion is required?
+  - Is the delivery_promise present with all required fields?
+  - Is the renderer_family selected and locked?
+  - Is the music plan resolved (source chosen or explicitly deferred)?
+  - Is the cost estimate honest and per-item?
+  - Has the user approved the proposal?
 ```
 
 ### After SCRIPT stage:
@@ -145,7 +161,8 @@ CHECK: Output validation
 
 | Gate | After Stage | What's Checked | Fail Action |
 |------|-------------|---------------|-------------|
-| G1 | idea | Emotional arc, source mode | Revise |
+| G0 | research | Visual references, mood grounding | Revise |
+| G1 | proposal | Delivery promise, renderer family, music plan, user approval | Revise |
 | G2 | script | Beat escalation, duration | Revise |
 | G3 | scene_plan | Hero moments, visual consistency | Revise |
 | G4 | assets | Music alignment, source quality, budget | Revise |

skills/pipelines/cinematic/proposal-director.md

@@ -0,0 +1,241 @@
+# Proposal Director — Cinematic Pipeline
+
+## When to Use
+
+You are the **Proposal Director** for a cinematic video (trailers, brand films, montages, dramatic edits). You sit between the Research Director and the Script Director. You receive a `research_brief` full of visual references, mood research, and cinematic direction options, and transform it into a concrete, reviewable proposal that the user approves before any money is spent.
+
+**This is the approval gate.** Nothing downstream runs until the user says "go."
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/proposal_packet.schema.json` | Artifact validation |
+| Prior artifact | `research_brief` from Research Director | Visual references, mood research, cinematic directions |
+| Pipeline manifest | `pipeline_defs/cinematic.yaml` | Stage and tool definitions |
+| Tool registry | `support_envelope()` output | What's actually available right now |
+| Cost tracker | `tools/cost_tracker.py` | Cost estimation data |
+| Style playbooks | `styles/*.yaml` | Available visual styles |
+| User input | Subject, footage, preferences | Creative direction |
+
+## Process
+
+### Step 1: Absorb the Research
+
+Read the `research_brief` thoroughly. Extract:
+
+- **`research_summary`** — the researcher's strongest creative direction.
+- **`angles_discovered`** — these are your raw cinematic direction candidates.
+- **Visual references** — the real-world precedents that inform each direction.
+- **Audio direction** — music mood and sound design notes.
+- **Source reality** — what footage/stills the user actually has.
+- **Motion commitment** — whether motion is required.
+
+### Step 2: Run Preflight
+
+Before designing concepts, know what tools are available:
+
+```bash
+python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
+```
+
+Record:
+- Video generation providers — **critical for cinematic**. If motion is required, these must be available.
+- Image generation providers — for support visuals and mood inserts
+- TTS providers — for narration (if applicable; many cinematic pieces are narration-free)
+- Music generation — check availability honestly
+- Enhancement tools — color_grade, audio_enhance are high-value for cinematic
+- **Remotion render engine** — check `video_compose.get_info()["render_engines"]["remotion"]`
+
+**Motion-required enforcement:** If the research brief indicates `motion_required: true`, verify that video generation or source footage can actually deliver motion. If neither is available, **do not silently downgrade to still-led**. Instead, present the constraint honestly and let the user decide.
+
+### Step 2c: Mood Board (Before Concepts)
+
+Before developing full concepts, present a quick mood board to catch direction mismatches early. Cinematic work is especially susceptible to tone misalignment, so this step is critical:
+
+- **3-5 reference images** (from web search — real film stills, not generic stock)
+- **Color palette direction** (2-3 palettes: e.g. desaturated cold vs warm golden vs high-contrast noir)
+- **Tone references** ("Think: Terrence Malick meets National Geographic" or "Think: David Fincher trailer pacing")
+- **1-2 music mood references** (genre + energy + emotional arc, e.g. "ambient synth building to orchestral crescendo")
+
+Ask: **"Does this FEEL like what you're imagining? Any of these off-track?"**
+
+This is cheaper than building 3 full cinematic directions and catches tone mismatches before they're embedded in concept design. If the user says "less moody, more energetic," you've saved a concept round.
+
+### Step 3: Design Concept Directions
+
+Build **at least 3 genuinely different cinematic directions.** Start from the `angles_discovered` in the research brief.
+
+For each concept, specify all fields in `proposal_packet.concept_options`:
+
+#### 3a: Title and Emotional Hook
+
+Cinematic hooks are different from explainer hooks — they evoke **feeling**, not information gaps.
+
+| Pattern | When to Use |
+|---------|-------------|
+| **Sensory** | "You hear it before you see it. A frequency that shouldn't exist." | When the mood is mystery/tension |
+| **Scale shift** | "In the time it takes to read this sentence, 4.7 million packets crossed the Atlantic." | When the concept involves scale |
+| **Intimate** | "She waters them at 6am. Before the city wakes. Before anyone watches." | When the mood is intimate/human |
+| **Provocation** | "They told us the message was noise. It wasn't." | When the concept involves a reveal |
+| **Contrast** | "Three blocks from Wall Street, on a rooftop covered in clover, 40,000 bees are building a city." | When the subject is surprising in context |
+
+#### 3b: Emotional Arc
+
+Every cinematic concept needs an explicit arc:
+
+| Arc | Structure | Best For |
+|-----|-----------|----------|
+| `tension → reveal` | Build unease, then pay it off | Teasers, sci-fi, thriller |
+| `wonder → scale` | Start small, expand to massive | Nature, tech, cosmos |
+| `intimacy → payoff` | Close, personal, then earned moment | Documentary, human interest |
+| `urgency → resolution` | Fast pace to satisfying close | Product, action, launch |
+| `mystery → CTA` | Intrigue that leads to action | Brand films, campaigns |
+| `stillness → eruption` | Calm before powerful climax | Music videos, art films |
+
+#### 3c: Delivery Promise
+
+For cinematic, explicitly classify:
+
+```yaml
+delivery_promise:
+  promise_type: motion_led  # or source_led, hybrid
+  motion_required: true     # false only if user approves still-led
+  source_required: false    # true if user has footage
+  tone_mode: cinematic      # cinematic, raw, intimate, epic
+  quality_floor: presentable  # draft, presentable, broadcast
+  approved_fallback: null   # animatic, still_led, or null (no fallback)
+```
+
+**Rule:** `motion_led` forbids still-led fallback unless the user explicitly approves `animatic` as the fallback.
+
+#### 3d: Visual Treatment
+
+For each concept, define:
+- **Color palette** — specific hex references, not just "dark"
+- **Lighting approach** — high_key, low_key, natural, golden_hour, etc.
+- **Camera language** — dominant shot sizes, movements
+- **Texture** — film grain, clean digital, anamorphic, handheld
+- **Typography** — if title cards are used, their style and restraint level
+
+#### 3e: Renderer Family Selection
+
+Choose the renderer family and lock it in the proposal:
+
+| Family | When | Composition |
+|--------|------|-------------|
+| `cinematic-trailer` | Trailers, teasers, brand films with generated/source video | CinematicRenderer |
+| `presenter` | Talking head with cinematic enhancement | TalkingHead |
+| `explainer-data` | Only if this is really an explainer that wants cinematic dressing | Explainer |
+
+**Rule:** The renderer family is selected here and locked before scene planning. The compose stage cannot change it without logging a decision and surfacing the change to the user.
+
+### Step 4: Progressive Reveal, Diversity Check, and Concept Selection
+
+#### 4a: Progressive Reveal
+
+Don't dump the full proposal at once. Build understanding step by step:
+
+1. **Research summary** (2-3 sentences): "Here's what I found about the subject and its visual potential..."
+   → User reacts, course-corrects if needed.
+2. **Mood board** (from Step 2c — already presented)
+   → User confirms feel.
+3. **Concept directions** (3+ emotional/visual approaches):
+   → Present each concept's emotional hook, arc, and visual treatment.
+4. **Invite mixing** (see 4c below).
+5. **Production plan for selected direction** (tools, cost, renderer family):
+   → User approves budget and approach.
+
+Each step is a chance for the user to course-correct before the next step builds on it.
+
+#### 4b: Diversity Check
+
+Before presenting concepts:
+- [ ] No two concepts share the same emotional arc
+- [ ] No two concepts use the same visual treatment
+- [ ] At least one concept takes a creative risk
+- [ ] Each concept's visual references are from different sources
+- [ ] Each concept is achievable with current capabilities (or states what's missing)
+
+#### 4c: Invite Mixing
+
+After presenting concepts, always say something like:
+> "You can also mix elements — for example, Concept A's emotional arc with Concept C's visual treatment and Concept B's music direction. What speaks to you?"
+
+If the user mixes, create a new hybrid concept entry in the proposal_packet with clear attribution: "Emotional arc from Concept A, visual treatment from Concept C, music direction from Concept B."
+
+Let the user select, combine, modify, or redirect entirely.
+
+### Step 5: Music Plan (Mandatory for Cinematic)
+
+Cinematic videos live and die by their audio. Surface the music situation before the user approves.
+
+Check availability in this order:
+1. **User music library (`music_library/`)** — list available tracks
+2. **Music generation APIs** — report status, cost, and quality honestly
+3. **Bring-your-own path** — user can drop a track in `music_library/`
+
+Present explicit options:
+```
+MUSIC PLAN
+├── Your music library: [N tracks / empty]
+├── AI generation: [provider] — [AVAILABLE/UNAVAILABLE] [cost]
+└── Bring your own: Drop a track in music_library/ before asset stage
+
+Recommendation: [specific recommendation based on mood research]
+```
+
+### Step 6: Build Production Plan
+
+For the selected concept, design the stage-by-stage plan with specific providers, costs, and honest tradeoffs.
+
+**Cinematic-specific tool priorities:**
+- **Color grade** — high priority. Cinematic output without grade looks flat.
+- **Audio enhance** — high priority. Audio dynamics matter more in mood-driven work.
+- **Video generation** — if motion-required, this is non-negotiable.
+- **Music** — must be resolved. No cinematic piece should have silence as a surprise.
+
+### Step 7: Cost Estimate
+
+Itemize all costs honestly. Cinematic tends to be more expensive than explainer (more generated clips, music, grade passes).
+
+### Step 8: Present and Approve
+
+Present concepts clearly. Invite the user to:
+- Select one as-is
+- Mix elements from multiple concepts
+- Request modifications
+- Redirect entirely
+
+Set `approval.status: "pending"`. Pipeline does NOT proceed without approval.
+
+### Step 9: Submit
+
+Validate `proposal_packet` against schema and submit.
+
+## Common Pitfalls
+
+- **Calling it cinematic because of black bars**: Letterboxing is not cinematography. The treatment must include shot language, lighting, movement, and emotional arc.
+- **Hiding motion downgrade**: If motion-required content will actually be still images with Ken Burns, say so explicitly.
+- **Music as afterthought**: In cinematic work, music is 50% of the mood. Surface it early.
+- **Three versions of "dark and moody"**: Three concepts with the same emotional register but different titles are one concept. Diversity means different arcs, different moods, different risks.
+- **Ignoring source reality**: If the user has no footage and limited generation tools, the proposal must reflect that — not pretend the constraints don't exist.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/cinematic/publish-director.md

@@ -9,7 +9,7 @@ Package the cinematic piece and any cutdowns so the hero version stays clear and
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]`, `state.artifacts["script"]["script"]` | Final outputs and beat map |
+| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["proposal"]["proposal_packet"]`, `state.artifacts["research"]["research_brief"]`, `state.artifacts["script"]["script"]` | Final outputs and beat map |
 | Playbook | Active style playbook | Tone and naming consistency |
 
 ## Process

skills/pipelines/cinematic/research-director.md

@@ -0,0 +1,172 @@
+# Research Director — Cinematic Pipeline
+
+## When to Use
+
+You are the **Research Director** for a cinematic video (trailers, brand films, dramatic montages, mood-led edits). Your job is to deeply research the subject to ground the cinematic direction in real references, real moods, and real audience expectations — before any creative decisions or money is spent.
+
+Unlike explainer research (which focuses on facts, data, and content gaps), cinematic research focuses on **visual references, emotional language, sound design direction, and motion precedents.** The goal is to arm the Proposal Director with enough material to present mood boards and concept directions that feel intentional, not generic.
+
+**You do NOT make creative decisions.** You gather raw material. The Proposal Director will use your findings to craft concept directions.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/research_brief.schema.json` | Artifact validation |
+| User input | Subject, mood hints, footage situation, references | Research scope |
+| Tools | Web search, web fetch | Research execution |
+
+## Process
+
+### Step 1: Classify the Brief
+
+Before searching, extract from the user's request:
+
+- **Subject**: What is this video about?
+- **Source reality**: Does the user have footage, stills, audio, or nothing?
+- **Motion requirement**: Is motion a hard requirement (trailer, teaser, hype reel) or can it be still-led?
+- **Mood hints**: Any emotional direction given? ("dark", "epic", "intimate", "raw", "hopeful")
+- **Platform**: Where will this live?
+- **Duration hint**: Short (15-30s), medium (30-90s), long (90s+)?
+
+### Step 2: Visual Reference Mining
+
+**Goal:** Find real cinematic precedents that match the mood and subject.
+
+```
+SEARCH BATCH 1 — Visual References (run all in parallel)
+
+Q1: "[subject] cinematic [mood hint]" site:youtube.com
+    → Find: Existing trailers, brand films, or mood pieces for this subject.
+
+Q2: "[subject] [delivery shape] visual style" (breakdown OR making-of OR tutorial)
+    → Find: How professionals approach this type of visual storytelling.
+
+Q3: "[mood hint] color palette cinematography" OR "[mood hint] color grading reference"
+    → Find: Color and grade references that match the intended mood.
+
+Q4: "[subject] [mood hint]" (short film OR brand film OR trailer) award OR festival
+    → Find: Award-quality references — the ceiling of what this could look like.
+```
+
+**For each reference, record:**
+- Title and URL
+- What works visually (framing, color, movement, texture)
+- What works emotionally (pacing, reveal structure, tension arc)
+- Relevance to the user's brief
+
+### Step 3: Sound and Music Landscape
+
+**Goal:** Understand the audio palette for this mood.
+
+```
+SEARCH BATCH 2 — Audio References (run in parallel)
+
+Q5: "[mood hint] [subject] soundtrack" OR "[mood hint] film score reference"
+    → Find: Music mood references.
+
+Q6: "[mood hint] sound design" (cinematic OR film OR trailer)
+    → Find: Sound design approaches — ambient, textural, percussive, silent.
+```
+
+**Record:**
+- Music mood direction (not specific tracks — the energy and texture)
+- Sound design notes (atmospheric, minimal, industrial, organic)
+- Whether dialogue or narration is expected or if the piece is music-driven
+
+### Step 4: Subject-Specific Research
+
+**Goal:** Gather factual or contextual depth that grounds the visual choices.
+
+```
+SEARCH BATCH 3 — Subject Depth (run in parallel)
+
+Q7: "[subject]" (story OR history OR origin OR significance)
+    → Find: Narrative depth that can inform visual decisions.
+
+Q8: "[subject]" (visual OR texture OR detail OR close-up OR macro)
+    → Find: Texture and material references for the subject.
+
+Q9: "[subject]" "[current year]" (trend OR development OR news)
+    → Find: Current relevance — is there a timeliness angle?
+```
+
+### Step 5: Motion and Camera Language Research
+
+**Goal:** Find specific cinematic techniques that suit this mood.
+
+```
+SEARCH BATCH 4 — Technique Research (run in parallel)
+
+Q10: "[mood hint] camera movement" (technique OR cinematography)
+     → Find: Which camera movements suit this mood (handheld for raw, steadicam for contemplative, whip pans for energy).
+
+Q11: "[mood hint] editing rhythm" OR "[mood hint] pacing" (film OR trailer)
+     → Find: Editing tempo references.
+
+Q12: "[delivery shape] structure" (beat sheet OR pacing OR breakdown)
+     → Find: Structural templates for this delivery type.
+```
+
+### Step 6: Audience and Distribution Context
+
+```
+SEARCH BATCH 5 — Audience (run in parallel)
+
+Q13: "[subject] [platform]" (best OR viral OR most watched)
+     → Find: What performs well on the target platform for this subject.
+
+Q14: "[subject]" site:reddit.com (mood OR aesthetic OR vibe)
+     → Find: How the community talks about and feels about this subject.
+```
+
+### Step 7: Angle Synthesis
+
+Using everything from Steps 2-6, identify at least 3 genuinely different cinematic directions:
+
+For each direction, specify:
+
+| Field | What | Quality Bar |
+|-------|------|-------------|
+| `name` | Short direction title (5-8 words) | Specific mood, not just the subject |
+| `hook` | One-sentence emotional pitch | Must evoke a feeling, not explain |
+| `type` | `mood_piece`, `tension_arc`, `reveal`, `intimate`, `epic`, `raw` | Categorize honestly |
+| `visual_references` | Which found references inform this direction | Specific URLs and descriptions |
+| `audio_direction` | Music mood, sound design approach | Informed by Step 3 findings |
+| `motion_commitment` | What motion is required and how it'll be achieved | Honest about capabilities |
+| `grounded_in` | Which research findings support this direction | Cross-reference your findings |
+
+**Direction diversity checklist:**
+- [ ] At least one direction uses a different emotional arc than the others
+- [ ] At least one direction emphasizes texture/intimacy over spectacle
+- [ ] No two directions use the same primary camera approach
+- [ ] Each direction is grounded in different visual references
+
+### Step 8: Source Bibliography
+
+Compile all URLs used. Minimum 5 sources.
+
+### Step 9: Assemble and Submit
+
+Build the `research_brief` artifact per the schema. Include:
+
+1. `research_summary` — one paragraph capturing the strongest creative direction found
+2. All sections from Steps 2-8
+
+Validate against `schemas/artifacts/research_brief.schema.json` before submitting.
+
+## Execution Constraints
+
+| Constraint | Value | Why |
+|------------|-------|-----|
+| Max time on research | 3-5 minutes | Research is valuable but has diminishing returns |
+| Max searches | 20 | Prevent infinite rabbit holes |
+| Min searches | 8 | Ensure adequate coverage |
+| No paid tools | — | Research uses web search only — zero cost |
+
+## Common Pitfalls
+
+- **Searching only for "cinematic"**: The word is overused. Search for the specific mood, texture, and subject instead.
+- **Ignoring the source reality**: If the user has no footage and no video generation, the research should account for still-led approaches — not ignore the constraint.
+- **Generic mood words**: "Dark and moody" is not a direction. "Low-key tungsten lighting with shallow depth of field, inspired by Fincher's title sequences" is a direction.
+- **Skipping audio research**: Cinematic videos live and die by their audio. The mood board is incomplete without sound direction.

skills/pipelines/cinematic/scene-director.md

@@ -9,7 +9,7 @@ You are deciding how each cinematic beat will look and transition. This is where
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Beat map and source truth |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Beat map and source truth |
 | Tools | `frame_sampler`, `scene_detect` | Source inspection and reframing checks |
 | Playbook | Active style playbook | Color and typography consistency |
 

skills/pipelines/cinematic/script-director.md

@@ -9,7 +9,7 @@ This stage builds the beat map, selected lines, title-card copy, and reveal stru
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
-| Prior artifact | `state.artifacts["idea"]["brief"]` | Emotional arc and source truth |
+| Prior artifact | `state.artifacts["proposal"]["proposal_packet"]` | Emotional arc and source truth |
 | Tools | `transcriber`, `scene_detect` | Optional dialogue mining and source review |
 
 ## Process
@@ -62,6 +62,17 @@ Recommended metadata keys:
 - the reveal lands distinctly,
 - the landing gives the viewer a final feeling or action.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Writing full explanatory paragraphs instead of beats.

skills/pipelines/clip-factory/asset-director.md

@@ -25,6 +25,16 @@ Prefer reusable assets over per-clip reinvention:
 - one watermark / brand frame,
 - one CTA / end-tag treatment if needed.
 
+### 1b. Hero Scene Sample (Mandatory)
+
+Before batch asset generation:
+1. Identify the hero scene (the visual peak of the batch)
+2. Generate ONE sample visual asset for that scene
+3. Present it: "This is the visual direction for the most important clip. Does this match what you're imagining? I'll generate the rest in this style."
+4. Wait for approval before proceeding to batch generation
+
+This prevents the most expensive mistake: generating 10+ assets in a direction the user doesn't like.
+
 ### 2. Generate Per-Clip Subtitles
 
 Each approved clip needs its own subtitle asset, timed from clip start rather than source start. This timestamp rebasing is critical.
@@ -60,9 +70,39 @@ Recommended metadata keys:
 - shared assets are referenced consistently,
 - the asset count stays practical for the batch size.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Forgetting to rebase subtitle timing per clip.
 - Overdesigning hook assets so the batch becomes inconsistent.
 - Normalizing some clips and not others.
 - Treating a 10-clip batch like 10 unrelated projects.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/clip-factory/script-director.md

@@ -82,6 +82,17 @@ Each candidate should record:
 - the set covers the source deliberately instead of clustering in one section,
 - low-quality candidates are rejected honestly.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Trusting first-pass candidate timestamps without transcript-level review.

skills/pipelines/explainer/asset-director.md

@@ -11,7 +11,7 @@ This is where plans become real files. A missing or low-quality asset will torpe
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | What to produce |
+| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | What to produce |
 | Playbook | Active style playbook | Image prompts, diagram style, audio preferences |
 | Tools | `tts_selector`, `image_selector`, `video_selector`, `diagram_gen`, `code_snippet`, `music_gen` — selectors auto-discover all available providers from the registry | Generation capabilities |
 | Cost tracker | `tools/cost_tracker.py` | Budget governance |
@@ -188,6 +188,17 @@ If any dimension scores below 3, fix before proceeding.
 
 Validate the asset_manifest against the schema and persist via checkpoint.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+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.
@@ -195,3 +206,22 @@ Validate the asset_manifest against the schema and persist via checkpoint.
 - **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.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/explainer/proposal-director.md

@@ -58,6 +58,21 @@ This directly affects what you can promise in the production plan. **Do not prop
 
 **Setup offers:** If critical tools are UNAVAILABLE but fixable with a simple configuration, read each tool's `install_instructions` from the registry and offer the user setup help before designing around the limitation. See AGENT_GUIDE.md "Provider Menu" protocol for the approach. Group related tools that share the same env var dependency.
 
+### Step 2c: Mood Board (Before Concepts)
+
+Before developing full concepts, present a quick mood board to catch direction mismatches early:
+
+- **3-5 reference images** (from web search, stock, or quick generations)
+- **Color palette direction** (2-3 options derived from playbook candidates)
+- **Tone references** ("Think: Kurzgesagt meets Vice" or "Think: Apple product video meets TED-Ed")
+- **1-2 music mood references** (genre + energy level, not specific tracks)
+
+Ask: **"Does this FEEL like what you're imagining? Any of these off-track?"**
+
+This is cheaper than generating 3 full concepts and catches direction mismatches before they become expensive. If the user says "too corporate" or "more playful," you've saved an entire concept round.
+
+If the user confirms the direction, proceed. If they redirect, adjust your concept design to match.
+
 ### Step 3: Design Concept Options
 
 Build **at least 3 genuinely different concepts.** Start from the `angles_discovered` in the research brief, but elevate them into full production concepts.
@@ -137,32 +152,89 @@ Set realistic duration based on platform and content depth:
 | YouTube | 60-180s | 150-450 words |
 | LinkedIn | 60-120s | 150-300 words |
 
-#### 3e: Concept Diversity Check
+#### 3e: When to Break the Patterns
 
-Before finalizing, verify diversity:
+The hook patterns and narrative structures above are starting points, not templates. Here are signs you should invent something new:
 
+**Signs your concepts are cosmetically diverse but conceptually identical:**
+- All three hooks create the same type of curiosity gap
+- Swapping the hooks between concepts would barely change anything
+- All three would produce roughly the same script if you wrote them blind
+- The visual approaches are "dark vs light vs colorful" but the content structure is identical
+
+**Anti-formula rule:** Write the hook in your own words first. Then check if a pattern helps sharpen it. If you start FROM the pattern, you'll produce pattern-shaped content instead of research-shaped content.
+
+**When to deviate from the 6 hook templates:**
+- The research reveals a unique framing that doesn't fit any template
+- The audience is sophisticated enough that template hooks feel condescending
+- The topic's best angle is emotional rather than informational
+- You found a specific quote, anecdote, or event that IS the hook
+
+#### 3f: Concept Diversity Gate
+
+This is two checks, not one:
+
+**Structural diversity (necessary but not sufficient):**
 - [ ] No two concepts use the same narrative structure
 - [ ] No two concepts use the same hook pattern
-- [ ] At least one concept targets a different audience segment
-- [ ] At least one concept leverages the most surprising data point
-- [ ] At least one concept addresses the biggest content gap found
 - [ ] Each concept's `grounded_in` references different research findings
 
-### Step 4: Present Concepts and Get Selection
+**Conceptual diversity (the actual test):**
+- [ ] Each concept offers a genuinely different INSIGHT, not just a different title for the same insight
+- [ ] At least one concept takes a creative risk (unusual structure, unexpected angle, provocative framing)
+- [ ] If you removed the titles and hooks, the concepts would still be distinguishable by their content structure
+- [ ] The concepts are NOT interchangeable — each serves a different audience need or curiosity
 
-Present all concepts clearly to the user. For each concept, show:
+If your concepts fail the conceptual diversity test, go back to the research brief. The problem is usually that you're working from one angle and varying the surface, instead of working from different angles entirely.
 
+#### 3g: Playbook Violation Budget
+
+Up to 20% of scenes in the final video may intentionally deviate from the playbook for creative impact. When presenting concepts, note which moments might benefit from visual surprise (a color shift, a different typography treatment, an unexpected transition). These deviations must be logged as `playbook_override` decisions in the decision log.
+
+#### 3h: Voice Selection
+
+Surface the voice/TTS decision at proposal time:
+- What voice provider and voice ID will be used
+- Why this voice fits the concept's tone
+- Cost implications
+- Whether voice variation is appropriate for hero moments
+
+### Step 4: Progressive Reveal and Concept Selection
+
+Don't dump the full proposal at once. Build understanding step by step:
+
+**4a. Research summary** (2-3 sentences): "Here's what I found..."
+→ User reacts, course-corrects if needed.
+
+**4b. Mood board** (from Step 2c — already presented)
+→ User confirms feel.
+
+**4c. Concept options** (3+ directions):
+
+For each concept, show:
 1. **Title** and **hook** — the creative pitch
 2. **Why this works** — the research backing, in one sentence
 3. **What it'll look like** — visual approach in plain language
 4. **Duration** — how long the video will be
 
+**4d. Invite Mixing:**
+
+After presenting concepts, always say something like:
+> "You can also mix elements — for example, Concept A's hook with Concept C's visual approach. What speaks to you?"
+
+If the user mixes, create a new hybrid concept entry in the proposal_packet with clear attribution: "Hook from Concept A, visual approach from Concept C, narrative structure from Concept B."
+
 Let the user:
 - Select one as-is
-- Combine elements from multiple concepts
+- Combine elements from multiple concepts (hybrid)
 - Request modifications
 - Describe a completely different direction (in which case, use the research to strengthen it)
 
+**4e. Production plan for selected concept** (tools, cost, timeline):
+→ User approves budget and approach.
+
+Each step is a chance for the user to course-correct before the next step builds on it. This prevents the "I approved a proposal and then the video wasn't what I expected" failure mode.
+
 Record the selection in `selected_concept` with rationale and any modifications.
 
 ### Step 5: Build the Production Plan
@@ -378,3 +450,22 @@ TOTAL: $0.64 of $2.00 budget
 - Premium (Remotion): Best available TTS + 4 AI images + 4 Remotion animated scenes = $0.48
 - Standard: Mid-tier TTS + images = $0.40
 - Free: Local TTS + Remotion component scenes only = $0.00 (no images, pure motion graphics)
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/explainer/publish-director.md

@@ -11,7 +11,7 @@ This is where a great video reaches its audience. Without proper metadata and pa
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]` | Video file and original brief |
+| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["proposal"]["proposal_packet"]`, `state.artifacts["research"]["research_brief"]` | Video file and original proposal |
 | Playbook | Active style playbook | Visual style for thumbnail |
 
 ## Process
@@ -19,14 +19,14 @@ This is where a great video reaches its audience. Without proper metadata and pa
 ### Step 1: Gather Context
 
 Collect everything needed for metadata:
-- **Brief**: title, hook, key points, target platform, tone
+- **Proposal packet**: title, hook, key points, target platform, tone
 - **Render report**: output path, duration, resolution
 - **Script**: section summaries for description/chapters
 
 ### Step 2: Generate SEO Metadata
 
 **Title** (max 60 characters for YouTube):
-- Include the primary keyword from the brief
+- Include the primary keyword from the proposal packet
 - Lead with a hook or number
 - Avoid clickbait but be compelling
 - Examples: "Vector Databases Explained in 60 Seconds" > "About Vector Databases"
@@ -39,7 +39,7 @@ Collect everything needed for metadata:
 - Links: relevant resources mentioned in the video
 
 **Tags/Keywords** (platform-dependent):
-- 5-10 specific tags derived from brief's key_points
+- 5-10 specific tags derived from proposal packet's key_points
 - Mix broad and specific: "machine learning" + "vector database tutorial"
 - Include the topic, format ("explainer"), and related terms
 

skills/pipelines/explainer/scene-director.md

@@ -11,7 +11,7 @@ This is where words become visuals. A great script with a bad scene plan produce
 | Layer | Resource | Purpose |
 |-------|----------|---------|
 | Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
-| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Script sections and creative brief |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["proposal"]["proposal_packet"]` | Script sections and proposal packet |
 | Playbook | Active style playbook | Visual language, transitions, motion rules |
 | Layer 3 | `.agents/skills/flux-best-practices/`, `.agents/skills/beautiful-mermaid/`, `.agents/skills/manim-composer/` | Image gen, diagram, animation knowledge |
 

skills/pipelines/explainer/script-director.md

@@ -185,6 +185,17 @@ If any dimension scores below 3, revise before submitting.
 
 Call `handle_explainer_script(state, {"script": script_json})` to validate and persist.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - **Writing too many words**: The #1 failure. TTS pacing is fixed. If you write 250 words for a 60-second video, either the audio will be rushed or the video will be 100 seconds. Count your words.

skills/pipelines/hybrid/asset-director.md

@@ -63,8 +63,38 @@ Recommended metadata keys:
 - source and generated assets are clearly separated,
 - every referenced file exists.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Overbuilding support assets before the anchor cut is proven.
 - Losing track of which assets are generated versus supplied.
 - Creating inconsistent overlay systems across one project.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/hybrid/script-director.md

@@ -52,6 +52,17 @@ Recommended metadata keys:
 - the script does not depend on fake or unavailable assets without saying so,
 - the structure can produce the intended deliverables.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Rewriting strong source dialogue into weaker narration.

skills/pipelines/localization-dub/asset-director.md

@@ -19,6 +19,16 @@ This stage produces the localized asset kit: translated subtitle files, dubbed a
 
 Create the subtitle or caption package for each language. This gives a reviewable fallback even if dubbed-audio generation or lip sync is blocked.
 
+### 1b. Hero Scene Sample (Mandatory)
+
+Before batch asset generation:
+1. Identify the hero scene (the visual peak of the video)
+2. Generate ONE sample dubbed audio clip for that scene in the target language
+3. Present it: "This is the voice direction for the most important scene. Does this match what you're imagining? I'll generate the rest in this style."
+4. Wait for approval before proceeding to batch generation
+
+This prevents the most expensive mistake: generating 10+ dubbed assets in a direction the user doesn't like.
+
 ### 2. Generate Dubbed Audio Per Language
 
 Use the approved translated script package, not raw machine output. Record which voice or synthesis path was used for each language.
@@ -45,8 +55,38 @@ Recommended metadata keys:
 - lip-sync remains explicitly optional,
 - every referenced file exists.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Generating dubbed audio before finalizing translation review.
 - Treating lip sync as mandatory for every language.
 - Failing to record which language asset maps to which voice and subtitle set.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/localization-dub/script-director.md

@@ -47,6 +47,17 @@ Recommended metadata keys:
 - glossary terms are preserved,
 - the script package can be reviewed before audio generation.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Generating audio from an unreviewed transcript.

skills/pipelines/podcast-repurpose/asset-director.md

@@ -24,6 +24,16 @@ Highest priority:
 - speaker attribution assets if multiple speakers appear,
 - quote-card templates for quote-led outputs.
 
+### 1b. Hero Scene Sample (Mandatory)
+
+Before batch asset generation:
+1. Identify the hero clip (the most important or impactful clip in the batch)
+2. Generate ONE sample asset for that clip (subtitle style, speaker card, or quote card)
+3. Present it: "This is the visual direction for the most important clip. Does this match what you're imagining? I'll generate the rest in this style."
+4. Wait for approval before proceeding to batch generation
+
+This prevents the most expensive mistake: generating 10+ assets in a direction the user doesn't like.
+
 ### 2. Treat Topic Graphics As Optional
 
 Generated graphics should support the batch, not dominate it. Use them only when:
@@ -58,8 +68,38 @@ Recommended metadata keys:
 - quote-card text remains mobile-readable,
 - optional generated art stays within budget and style constraints.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Spending budget on optional art before subtitles and attribution assets are complete.
 - Creating inconsistent speaker cards across the same episode.
 - Overproducing topic graphics for long-form companion videos.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/podcast-repurpose/script-director.md

@@ -63,6 +63,17 @@ Use `sections[]` for the structured production-facing segments and put the riche
 - weak clips are rejected instead of padded,
 - chapter markers cover the long-form conversation cleanly.
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Treating diarization errors as minor when they change who said the quote.

skills/pipelines/screen-demo/asset-director.md

@@ -25,6 +25,16 @@ Screen demos do not need a large asset pile. They need the right few assets:
 - optional: one intro card, one outro card, sparse diagram overlays
 - optional only if preflight allows it: generated narration for silent recordings
 
+### 1b. Hero Scene Sample (Mandatory)
+
+Before batch asset generation:
+1. Identify the hero scene (the most important step or interaction in the demo)
+2. Generate ONE sample asset for that scene (subtitle style, highlight overlay, or intro card)
+3. Present it: "This is the visual direction for the most important step. Does this match what you're imagining? I'll generate the rest in this style."
+4. Wait for approval before proceeding to batch generation
+
+This prevents the most expensive mistake: generating 10+ assets in a direction the user doesn't like.
+
 ### 2. Generate Subtitles First
 
 Rules:
@@ -101,9 +111,39 @@ Use `asset_manifest.metadata` for details like:
 - [ ] Callout colors have sufficient contrast
 - [ ] Blur masks fully cover the sensitive content
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
 ## Common Pitfalls
 
 - Generating too many one-off overlay files instead of a reusable kit.
 - Using subtitles that sit directly on top of terminal output or bottom navigation.
 - Assuming silent recordings will magically gain narration without checking TTS.
 - Spending image generation budget on visuals the raw screen already provides.
+
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/screen-demo/script-director.md

@@ -108,6 +108,17 @@ Recommended `script.metadata` fields:
 | **Technical accuracy** | Are all software names, commands, and UI elements named correctly? |
 | **Word economy** | Is narration concise and procedural? |
 
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.
+
 ## Common Pitfalls
 
 - Narrating the cursor instead of the outcome.

skills/pipelines/talking-head/asset-director.md

@@ -16,6 +16,16 @@ You have a scene plan and script. Your job is to generate the supporting assets
 
 ## Process
 
+### Step 0: Hero Scene Sample (Mandatory)
+
+Before batch asset generation:
+1. Identify the hero scene (the visual peak of the video)
+2. Generate ONE sample asset for that scene (subtitle style, overlay, or background)
+3. Present it: "This is the visual direction for the most important scene. Does this match what you're imagining? I'll generate the rest in this style."
+4. Wait for approval before proceeding to batch generation
+
+This prevents the most expensive mistake: generating 10+ assets in a direction the user doesn't like.
+
 ### Step 1: Generate Subtitles
 
 Use the transcription data from the script stage to create:
@@ -167,3 +177,32 @@ Document all generated assets with paths, types, and tool references:
 ### Step 7: Submit
 
 Validate the asset_manifest against the schema and persist via checkpoint.
+
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during asset generation:
+- Use `web_search` to verify visual accuracy of subjects (e.g. what does this building actually look like?)
+- Use `web_search` to find reference images before generating illustrations
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Visual accuracy matters. If the script mentions a specific place, person, or object,
+verify what it actually looks like before generating images. Don't rely on
+the AI model's training data — it may be wrong or outdated.
+
+## When You Do Not Know How
+
+If you encounter a generation technique, provider behavior, or prompting pattern you are unsure about:
+
+1. **Search the web** for current best practices — models and APIs change frequently, and the agent's training data may be stale
+2. **Check `.agents/skills/`** for existing Layer 3 knowledge (provider-specific prompting guides, API patterns)
+3. **If neither helps**, write a project-scoped skill at `projects/<project-name>/skills/<name>.md` documenting what you learned
+4. **Reference source URLs** in the skill so the knowledge is traceable
+5. **Log it** in the decision log: `category: "capability_extension"`, `subject: "learned technique: <name>"`
+
+This is especially important for:
+- **Video generation prompting** — models respond to specific vocabularies that change with each version
+- **Image model parameters** — optimal settings for FLUX, DALL-E, Imagen differ and evolve
+- **Audio provider quirks** — voice cloning, music generation, and TTS each have model-specific best practices
+- **Remotion component patterns** — new composition techniques emerge as the framework evolves
+
+Do not rely on stale knowledge. When in doubt, search first.

skills/pipelines/talking-head/script-director.md

@@ -54,3 +54,14 @@ Assemble the structured script with:
 ### Step 6: Submit
 
 Validate the script against the schema and persist via checkpoint.
+
+### Mid-Production Fact Verification
+
+If you encounter uncertainty during script writing:
+- Use `web_search` to verify factual claims before committing them to the script
+- Use `web_search` to find reference images for visual accuracy
+- Log verification in the decision log: `category="visual_accuracy_check"`
+
+Every factual claim in the script should be traceable to the `research_brief`.
+If you make a claim that isn't in the research, do additional research and
+add the source. Do not invent statistics, dates, or attributions.