Initial release — OpenMontage: the first open-source agentic video production system

11 production pipelines, 47 tools, 124 agent skills.
Supports cloud APIs (fal.ai, OpenAI, ElevenLabs, Suno, HeyGen, Runway) and
free local providers (diffusers, Piper TTS, WAN 2.1, Hunyuan, CogVideo).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

skills/pipelines/animation/asset-director.md

@@ -0,0 +1,70 @@
+# Asset Director - Animation Pipeline
+
+## When To Use
+
+This stage prepares the actual animated ingredients: narration, diagrams, math renders, motion backgrounds, code visuals, and reusable type or layout systems.
+
+## Prerequisites
+
+| 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 |
+| 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 |
+
+## Process
+
+### 1. Start With Deterministic Assets
+
+Prefer the lowest-variance useful path:
+
+- `diagram_gen` before generic image generation for structured diagrams,
+- `code_snippet` for code scenes,
+- `math_animate` for real math motion,
+- provided artwork before new generation.
+
+### 1b. Sample Preview (Prevents Wasted Spend)
+
+Before batch-generating assets, produce one sample of each expensive type and show the user:
+
+1. **TTS sample** (if narration-led): Generate one section. Confirm voice and tone before batching.
+2. **Visual sample**: Generate one representative scene visual (diagram, illustration, or motion background). Confirm style and quality before batching the rest.
+
+If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
+
+### 2. Build Reusable Systems
+
+Create once:
+
+- typography treatments,
+- lower-third or label styles,
+- repeated motif assets,
+- background containers.
+
+### 3. Narration Is Optional, But The Plan Must Be Explicit
+
+If the project is narration-led, produce or source narration. If it is text-led or music-led, say so clearly in metadata.
+
+### 4. Use Metadata For Feasibility Truth
+
+Recommended metadata keys:
+
+- `tool_path_map`
+- `reusable_assets`
+- `narration_assets`
+- `scene_asset_index`
+- `blocked_assets`
+
+### 5. Quality Gate
+
+- the asset path is explicit per scene,
+- reusable assets are actually reused,
+- missing capabilities are surfaced honestly,
+- every referenced file exists.
+
+## 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.

skills/pipelines/animation/compose-director.md

@@ -0,0 +1,47 @@
+# Compose Director - Animation Pipeline
+
+## When To Use
+
+Render the animation with an emphasis on text sharpness, timing integrity, and consistent output cadence.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Timing plan and asset files |
+| Tools | `video_compose`, `audio_mixer`, `video_stitch` | Final assembly |
+| Playbook | Active style playbook | Render consistency |
+
+## Process
+
+### 1. Preserve Motion Timing
+
+Do not let export settings or careless composition change the perceived timing of holds, stagger, or scene transitions.
+
+### 2. Protect Text And Diagram Sharpness
+
+Animation often fails on export through soft text, muddy thin lines, or cramped mobile framing.
+
+### 3. Verify The First And Last Frames
+
+Ensure:
+
+- the opening frame reads immediately,
+- the final frame lands cleanly,
+- nothing important is clipped by safe zones.
+
+### 4. Use Render Metadata
+
+Recommended metadata keys:
+
+- `render_fps`
+- `sharpness_checks`
+- `safe_zone_checks`
+- `variant_outputs`
+
+## Common Pitfalls
+
+- Soft or aliased text after rendering.
+- Compression choices that damage diagrams.
+- Scene cadence changing between preview and final.

skills/pipelines/animation/edit-director.md

@@ -0,0 +1,54 @@
+# Edit Director - Animation Pipeline
+
+## When To Use
+
+This stage turns the scene plan into an animatic-grade edit plan. Timing is the product.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, timing plan, and beats |
+| Playbook | Active style playbook | Motion and typography rules |
+
+## Process
+
+### 1. Protect Hold Time
+
+After key reveals, plan enough time for the viewer to process the frame. Do not stack every scene edge to edge with motion.
+
+### 2. Stagger Secondary Elements
+
+Primary element first, supporting elements second. The edit decisions should reinforce hierarchy.
+
+### 3. Keep Motion Meaningful
+
+Motion should signal:
+
+- emphasis,
+- transition,
+- transformation,
+- contrast.
+
+### 4. Use Metadata For Timing Detail
+
+Recommended metadata keys:
+
+- `hold_windows`
+- `stagger_rules`
+- `transition_map`
+- `scene_timing_notes`
+
+### 5. Quality Gate
+
+- key information has enough dwell time,
+- movement clarifies hierarchy,
+- transitions stay consistent,
+- the edit remains readable on the target platform.
+
+## Common Pitfalls
+
+- Overcrowding the timeline with continuous motion.
+- Revealing all elements at once.
+- Letting stylistic motion reduce readability.

skills/pipelines/animation/executive-producer.md

@@ -0,0 +1,420 @@
+# Executive Producer — Animation Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a generated animation video. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision. You are the stateful brain; the directors are stateless workers.
+
+**You replace the default parallel/sequential execution model.** Instead of running all stages blindly, you exercise judgment at every gate.
+
+## Why This Exists
+
+Animation pipelines have unique failure modes that parallel execution cannot catch:
+
+- Motion consistency breaks when scenes are generated independently
+- Mathematical accuracy errors compound if not caught after script
+- Animation timing requires hold times and reveals that get squeezed out without cross-stage awareness
+- Reuse strategy degrades when each stage plans independently
+- Budget allocation between AI-generated assets and free programmatic animation needs active management
+- Text readability and diagram sharpness must be verified at compose time, not assumed
+
+The EP solves all of these by maintaining cumulative state and applying animation-specific judgment at each gate.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/animation.yaml` | Stage definitions, review focus, success criteria |
+| Skills | All 9 director skills + `meta/reviewer` | Stage execution knowledge |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+| Tools | Full tool registry | Available capabilities |
+
+## Cumulative State
+
+The EP maintains a running state object that flows through the entire pipeline:
+
+```
+EP_STATE:
+  pipeline: animation
+  playbook: <selected playbook name>
+  target_duration_seconds: <from proposal_packet.selected_concept>
+  budget_total_usd: <from proposal_packet.approval.approved_budget_usd or configured limit>
+  budget_spent_usd: 0.0
+  budget_remaining_usd: <budget_total>
+
+  # Animation-specific state
+  animation_mode: <manim | remotion | ai_video | diagram_stills | mixed>
+  reuse_strategy:
+    recurring_motifs: []
+    layout_system: null
+    transition_family: null
+    typography_hierarchy: null
+    unique_scene_count: 0
+    reused_template_count: 0
+  math_accuracy_notes: []      # constraints from research on what NOT to oversimplify
+
+  # Accumulated from each stage (8 stages)
+  artifacts:
+    research: null      # → research_brief
+    proposal: null      # → proposal_packet (includes approval gate)
+    script: null        # → script
+    scene_plan: null    # → scene_plan
+    assets: null        # → asset_manifest
+    edit: null          # → edit_decisions
+    compose: null       # → render_report
+    publish: null       # → publish_log
+
+  # Pre-production context (carried forward from research + proposal)
+  research_brief: null         # full research_brief artifact
+  selected_concept: null       # the approved concept from proposal_packet
+  production_plan: null        # the approved tool/provider plan
+  approved_budget_usd: null    # explicit user-approved spend cap
+
+  # Cross-stage tracking
+  narration_durations: {}    # section_id → actual_seconds
+  total_narration_seconds: 0
+  total_visual_seconds: 0
+  style_anchors: {}          # consistency tokens carried forward
+  revision_counts: {}        # stage_name → number of revisions
+  issues_log: []             # all issues found, with resolution status
+```
+
+## Execution Protocol
+
+### Phase 0: Initialize
+
+1. Load the pipeline manifest (`animation.yaml`)
+2. Load the playbook (from user selection or default)
+3. Set budget from configuration or user input (default: $2.00)
+4. Initialize EP_STATE
+
+### Phase 1: Execute Stages Serially
+
+For each stage in order: `research → proposal → script → scene_plan → assets → edit → compose → publish`
+
+**Pre-production stages (research, proposal)** run before any money is spent:
+- **research** gathers topic data AND animation technique references via web search — zero cost
+- **proposal** presents concepts with animation mode selection and costs to the user — zero cost, but contains the **approval gate**
+- The pipeline MUST NOT proceed past proposal without `approval.status == "approved"` or `"approved_with_changes"`
+
+After proposal approval, extract and store in EP_STATE:
+- `selected_concept` from `proposal_packet.selected_concept`
+- `animation_mode` from `selected_concept.animation_mode`
+- `reuse_strategy` from `selected_concept.reuse_strategy`
+- `production_plan` from `proposal_packet.production_plan`
+- `approved_budget_usd` from `proposal_packet.approval.approved_budget_usd`
+- `playbook` from `proposal_packet.selected_concept → suggested_playbook`
+- `math_accuracy_notes` from research_brief (if applicable)
+
+```
+EXECUTE_STAGE(stage_name):
+
+  1. PREPARE
+     - Load the director skill for this stage
+     - Inject EP_STATE as context (prior artifacts, budget remaining, style anchors, animation mode, reuse strategy)
+     - Inject any EP feedback from previous revision attempts
+
+  2. SPAWN DIRECTOR
+     - The director executes its full process (as defined in its skill MD)
+     - Director produces an artifact
+
+  3. REVIEW (EP performs this, not a separate reviewer)
+     - Schema validation against artifact schema
+     - Check review_focus items from pipeline manifest
+     - Check success_criteria from pipeline manifest
+     - Cross-check against playbook constraints
+     - Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
+
+  4. GATE DECISION
+     If PASS:
+       - Store artifact in EP_STATE
+       - Update cumulative tracking (budget, durations, etc.)
+       - Log: "[stage] PASSED — moving to next stage"
+       - Continue to next stage
+
+     If REVISE:
+       - Increment revision_counts[stage_name]
+       - If revision_counts[stage_name] >= 3:
+           - PASS WITH WARNINGS (never block forever)
+           - Log unresolved issues
+       - Else:
+           - Compose specific feedback for the director
+           - Re-run SPAWN DIRECTOR with feedback injected
+           - Re-run REVIEW
+
+     If SEND_BACK(target_stage):
+       - Only used when a downstream discovery invalidates upstream work
+       - Re-execute from target_stage forward (artifacts after target are invalidated)
+       - Max 1 send-back per stage pair (prevent infinite loops)
+```
+
+### Phase 2: Final Quality Assurance
+
+After all stages complete, the EP performs a holistic review:
+
+```
+FINAL_QA:
+  1. PROBE the output video:
+     - Duration: within ±5% of target?
+     - Resolution: matches media profile?
+     - Audio: narration audible throughout? Music balanced?
+     - File: valid container, reasonable size?
+
+  2. TEXT AND DIAGRAM SHARPNESS (ANIMATION-SPECIFIC):
+     - Are text elements readable at target resolution?
+     - Are diagram lines crisp, not blurry from scaling?
+     - Are mathematical symbols rendered correctly?
+     - Is typography hierarchy maintained across scenes?
+
+  3. MOTION CONSISTENCY:
+     - Do transitions follow the declared transition family?
+     - Are hold times preserved (not squeezed by timing)?
+     - Do staggered reveals play correctly?
+     - Is the pacing animation-friendly (not rushed)?
+
+  4. STYLE CONSISTENCY:
+     - Do all scenes follow the reuse strategy?
+     - Is the color palette consistent?
+     - Do recurring motifs appear correctly across scenes?
+
+  5. MATHEMATICAL ACCURACY (if applicable):
+     - Do animated formulas/diagrams match the research brief's accuracy notes?
+     - Are any simplifications flagged in the research still correct?
+
+  6. BUDGET RECONCILIATION:
+     - Total actual spend vs. budget
+     - Log per-stage cost breakdown
+
+  7. DECISION:
+     If all checks pass → APPROVE for publish stage
+     If issues found → Send back to the specific stage(s) that can fix them
+       - Text/diagram issues → compose director (re-render) or asset director (regenerate)
+       - Motion issues → edit director (re-time) or scene director (replan)
+       - Audio issues → compose director
+       - Duration issues → script director (rewrite)
+       - Math errors → script director (fix content) then cascade forward
+```
+
+## EP-Specific Cross-Stage Checks
+
+These checks use information accumulated across stages — something no individual director can do.
+
+### After RESEARCH stage:
+```
+CHECK: Research depth
+  - At least 3 data_points with source URLs?
+  - At least 3 angles_discovered with grounded_in references?
+  - At least 2 animation technique references?
+  - At least 5 sources cited?
+  - If any minimum not met: REVISE research
+  - Note: Do NOT checkpoint with user — research is informational, not a decision point
+```
+
+### After PROPOSAL stage:
+```
+CHECK: Approval gate (CRITICAL)
+  - Is approval.status == "approved" or "approved_with_changes"?
+  - If "pending" or "rejected": STOP. Present to user and wait.
+  - If "approved_with_changes": apply modifications before proceeding
+  - Extract: animation_mode, reuse_strategy, target_duration, playbook, budget, tool selections
+
+CHECK: Animation mode feasibility
+  - Does the selected animation mode's required tools exist in the registry?
+  - If Manim mode selected: is math_animate available?
+  - If Remotion mode selected: is video_compose (Remotion) available?
+  - If AI video mode selected: are video generation providers available?
+  - If any required tool is unavailable: alert user, offer alternatives
+
+CHECK: Reuse strategy validity
+  - Does the reuse strategy define recurring motifs?
+  - Is the unique-to-template ratio reasonable (aim for ≤ 3:1)?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Word count vs. duration target
+  - Calculate: total_words / 150 = estimated_minutes
+  - If estimated_minutes > target_duration * 1.15:
+      REVISE script: "Script is {X} words → {Y}min. Target: {Z}min. Cut {N} words."
+  - If estimated_minutes < target_duration * 0.7:
+      REVISE script: "Script is too short. Add {N} words."
+
+CHECK: Animation beat structure
+  - Does each section express ONE clear visual idea?
+  - Are hold times budgeted (not every second filled with new information)?
+  - Is on-screen text concise (phrases, not paragraphs)?
+
+CHECK: Mathematical accuracy (if applicable)
+  - Does the script's explanation match the research brief's accuracy notes?
+  - Are any simplifications technically defensible?
+  - If inaccurate: REVISE script with specific correction from research
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Total scene duration covers full script
+  - Sum all scene durations
+  - Compare to script's total duration
+  - If gaps > 1 second: REVISE scene_plan
+  - If overlaps: REVISE scene_plan
+
+CHECK: Animation mode adherence
+  - Does every scene specify which animation mode/tool it uses?
+  - Are mode choices consistent with the proposal's selected mode?
+  - If mixed mode: are transitions between modes planned?
+
+CHECK: Reuse strategy enforcement
+  - Does the scene plan reference the recurring motifs from the proposal?
+  - Are templates reused where specified?
+  - If every scene is unique: flag as potential over-complexity
+
+CHECK: Visual variety within constraints
+  - Count consecutive same-type scenes
+  - If > 3 consecutive: REVISE scene_plan
+```
+
+### After ASSETS stage:
+```
+CHECK: Narration duration feedback loop (CRITICAL)
+  - For each TTS audio file, probe actual duration
+  - Store in EP_STATE.narration_durations
+  - For each section:
+      If actual_duration > planned_duration * 1.15:
+        Option A: SEND_BACK to script director
+        Option B (within 25% over): Adjust scene_plan durations
+  - Update EP_STATE.total_narration_seconds
+
+CHECK: Budget gate
+  - If budget_spent > budget_total * 0.9 and stages remain:
+      Alert: "90% budget consumed with {N} stages remaining"
+      Adjust remaining stages to free/cheap alternatives
+
+CHECK: Style consistency
+  - Compare visual styles across all generated assets
+  - Are recurring motifs visually consistent?
+  - Store style_anchors for downstream use
+
+CHECK: Programmatic asset integrity (if Manim/Remotion)
+  - Did math_animate or video_compose succeed without errors?
+  - Are output files valid and correctly sized?
+```
+
+### After EDIT stage:
+```
+CHECK: Timeline completeness
+  - Verify edit decisions cover 0 to total_duration with no gaps
+  - Verify all asset references point to existing files
+  - Verify audio ducking is configured for all narration segments
+
+CHECK: Hold time preservation (ANIMATION-SPECIFIC)
+  - Verify hold times from scene_plan are preserved in edit decisions
+  - Verify staggered reveals are not compressed
+  - Verify motion serves hierarchy, not decoration
+
+CHECK: A/V sync pre-validation
+  - For each cut: narration_start aligns with visual_start (±0.5s)
+  - For each scene: narration_duration ≤ visual_duration
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe the output: duration, resolution, codec, audio channels
+  - If duration drift > 5%: investigate which stage caused it
+  - If audio missing: check audio_mixer configuration
+  - If resolution wrong: check media profile selection
+
+CHECK: Text and diagram sharpness (ANIMATION-CRITICAL)
+  - Text must be readable at target resolution
+  - Diagram lines must be crisp (no scaling artifacts)
+  - Mathematical symbols must render correctly
+  - If any text/diagram is blurry: REVISE compose with resolution/scaling adjustments
+```
+
+## Feedback Message Templates
+
+### To Script Director:
+```
+EP FEEDBACK — Script Revision Required
+Reason: {reason}
+Specific issue: {detail}
+Constraint: {word_count_limit / duration_target / math_accuracy}
+Animation mode: {current mode — affects how text and beats should be structured}
+Keep: {what was good}
+Change: {what specifically needs to change}
+```
+
+### To Scene Director:
+```
+EP FEEDBACK — Scene Plan Revision Required
+Reason: {reason}
+Affected scenes: {scene_ids}
+Animation mode: {current mode}
+Reuse strategy: {what motifs/templates should be reused}
+Available tools: {current tool registry status}
+```
+
+### To Asset Director:
+```
+EP FEEDBACK — Asset Regeneration Required
+Reason: {reason}
+Affected assets: {asset_ids}
+Style anchors: {consistency requirements}
+Animation mode: {current mode — affects which tools to use}
+Budget remaining: ${remaining}
+```
+
+### To Compose Director:
+```
+EP FEEDBACK — Re-render Required
+Reason: {reason}
+Specific issue: {text_sharpness / motion_timing / audio_sync / etc.}
+Expected: {what the output should be}
+Actual: {what was produced}
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | research | Data depth, technique references, angle diversity | Revise research |
+| G2 | proposal | Concept quality, mode feasibility, user approval | Revise proposal OR wait for user |
+| G3 | script | Word count, beat structure, math accuracy | Revise script |
+| G4 | scene_plan | Coverage, mode adherence, reuse strategy, variety | Revise scene_plan |
+| G5 | assets | Narration duration, budget, style, asset integrity | Revise assets OR send-back to script |
+| G6 | edit | Timeline completeness, hold times, A/V pre-sync | Revise edit |
+| G7 | compose | Output probe, text sharpness, motion timing | Revise compose OR send-back |
+| G8 | publish | Metadata, packaging, animation-mode tags | Revise publish |
+| FINAL | all | Holistic review: sharpness, motion, accuracy, style | Send-back to specific stage |
+
+## Execution Limits (Anti-Loop Protection)
+
+| Limit | Value | Rationale |
+|-------|-------|-----------|
+| Max revisions per stage | 3 | Prevent perfectionism loops |
+| Max send-backs per stage pair | 1 | Prevent ping-pong |
+| Max total send-backs | 3 | Cap total re-work |
+| Max total budget | Configurable (default $2) | Hard stop on spending |
+| Max total wall-time | 15 minutes | Timeout for entire pipeline |
+
+After any limit is hit: **proceed with warnings**, never block indefinitely.
+
+## Integration with Existing Skills
+
+The EP doesn't replace any director skill — it wraps them. Each director skill continues to work exactly as documented. The EP adds:
+
+1. **Context injection**: Directors receive EP_STATE with cross-stage information
+2. **Feedback injection**: Directors receive specific revision instructions when sent back
+3. **Budget awareness**: Directors receive remaining budget and adjust tool choices
+4. **Animation mode context**: Directors know the selected mode and reuse strategy
+5. **Style anchors**: Directors receive consistency tokens from prior stages
+6. **Math accuracy notes**: Directors receive constraints on technical accuracy
+
+## Common Pitfalls
+
+- **Over-revising**: A "good enough" animation in the right mode is better than a "perfect" one after 5 rounds.
+- **Ignoring text sharpness**: The #1 animation quality issue. Always verify text readability at final resolution.
+- **Letting reuse strategy erode**: If the proposal specified 3 templates, the scene plan should use 3 templates, not 8 unique designs.
+- **Not probing outputs**: Always ffprobe the final video. Never trust metadata alone.
+- **Losing animation mode context**: If the proposal selected Manim, every downstream stage should know it's a Manim project. Don't let stages default to generic image_selector when programmatic animation was approved.
+- **Skipping math accuracy checks**: For technical topics, this is non-negotiable. A wrong animation is worse than no animation.

skills/pipelines/animation/idea-director.md

@@ -0,0 +1,72 @@
+# Idea Director - Animation Pipeline
+
+## When To Use
+
+Use this pipeline when the video should be built primarily through designed motion: motion graphics, kinetic typography, diagram-led explainers, math visuals, or illustrative animation.
+
+Do not use this pipeline when the project is really footage-led with a few overlays. That belongs in `hybrid`.
+
+## Reference Inputs
+
+- `docs/animation-best-practices.md`
+- `skills/creative/animation-pipeline.md`
+- `skills/creative/storytelling.md`
+
+## Process
+
+### 1. Classify The Animation Mode
+
+Choose the primary mode:
+
+- `diagrammatic`
+- `motion_graphics`
+- `kinetic_type`
+- `math_animation`
+- `illustrative`
+- `mixed_animation`
+
+### 2. Decide The Visual Path Early
+
+Figure out which tools are supposed to do the work:
+
+- `diagram_gen`
+- `math_animate`
+- `code_snippet`
+- `image_selector`
+- `video_selector` or a concrete video provider tool
+- source-provided art
+
+If the requested mode depends on unavailable tools, say so in the brief metadata immediately.
+
+### 3. Choose A Reuse Strategy
+
+Animation gets expensive when every scene is unique. Define:
+
+- recurring motifs,
+- layout system,
+- transition family,
+- typography hierarchy.
+
+### 4. Build The Brief
+
+Recommended metadata keys:
+
+- `animation_mode`
+- `visual_path`
+- `narration_strategy`
+- `reuse_strategy`
+- `timing_style`
+- `blocked_capabilities`
+
+### 5. Quality Gate
+
+- the animation mode is explicit,
+- the visual path is feasible,
+- the project is designed for reuse,
+- the brief is honest about missing tools.
+
+## Common Pitfalls
+
+- Treating all animation as one generic category.
+- Planning bespoke visuals for every scene.
+- Hiding missing tool paths until the asset stage.

skills/pipelines/animation/proposal-director.md

@@ -0,0 +1,263 @@
+# Proposal Director — Animation Pipeline
+
+## When to Use
+
+You are the **Proposal Director** for a generated animation video. You sit between the Research Director and the Script Director. You receive a `research_brief` full of raw findings — both topic data and animation technique research — 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."
+
+Animation proposals have a unique dimension: **animation mode selection**. Unlike explainer videos where the visual approach is secondary to the narrative, animation videos ARE their visual approach. The mode choice (Manim vs Remotion vs AI video vs motion graphics) fundamentally shapes the entire production.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/proposal_packet.schema.json` | Artifact validation |
+| Prior artifact | `research_brief` from Research Director | Raw findings + technique research |
+| Pipeline manifest | `pipeline_defs/animation.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 | Topic, any preferences expressed | Creative direction |
+
+## Process
+
+### Step 1: Absorb the Research
+
+Read the `research_brief` thoroughly. Extract:
+
+- **`research_summary`** — read first. Contains both the key insight and the most promising animation approach.
+- **`angles_discovered`** — raw concept candidates, each with an `animation_fit` field.
+- **`data_points`** — especially those with high `visual_potential` ratings.
+- **Animation technique references** — from the animation-specific research step. These directly inform mode selection.
+- **`audience_insights.misconceptions`** — animation excels at showing "wrong way → right way" transitions.
+- **Mathematical/technical accuracy notes** — critical constraints on what we can and cannot simplify.
+
+### 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))"
+```
+
+Also check the capability catalog:
+
+```bash
+python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.capability_catalog(), indent=2))"
+```
+
+**Animation-specific preflight checks:**
+
+| Capability | What to Check | Impact if Missing |
+|------------|---------------|-------------------|
+| `math_animate` | Is ManimCE installed and working? | Cannot do programmatic math animation — fall back to diagram_gen + image_selector |
+| `diagram_gen` | Is Mermaid rendering available? | Cannot do diagram-led animation — fall back to image_selector |
+| `video_selector` | Which video gen providers are available? | Limits AI video clip options |
+| `image_selector` | Which image gen providers are available? | Limits still frame options |
+| `tts_selector` | Which TTS providers are available? | Affects narration quality |
+| `video_compose` | Is FFmpeg/Remotion available? | Critical — cannot render without this |
+
+Record all findings. **Do not propose an animation mode that requires tools you don't have.**
+
+### Step 3: Animation Mode Decision Matrix
+
+This is the key differentiator from the explainer proposal. For each viable animation mode, evaluate:
+
+| Mode | Best For | Tool Required | Visual Quality | Cost | Iteration Speed |
+|------|----------|---------------|----------------|------|-----------------|
+| **Manim (ManimCE)** | Math, physics, geometry, algorithms | `math_animate` | Precise, programmatic | Free (local) | Fast (code-driven) |
+| **Remotion** | Data viz, charts, React components, kinetic type | `video_compose` (Remotion mode) | Smooth, web-native | Free (local) | Fast (code-driven) |
+| **AI Video Generation** | Abstract concepts, metaphors, transitions | `video_selector` providers | Variable, cinematic | $0.05-0.50/clip | Slow (generation time) |
+| **Diagram + Image Stills** | Process flows, architecture, comparisons | `diagram_gen` + `image_selector` | Clean, reliable | $0-0.05/image | Fast |
+| **Mixed Mode** | Complex topics needing multiple techniques | Multiple tools | Varied | Varies | Moderate |
+
+**Mode selection rules:**
+- If the topic involves math/formulas/geometry → prefer Manim
+- If the topic involves data/statistics/charts → prefer Remotion or diagram_gen
+- If the topic is abstract/conceptual → consider AI video for key moments
+- If the topic is process/workflow → prefer diagram builds
+- Always check tool availability before committing to a mode
+- Mixed mode is valid when different sections need different approaches
+
+### Step 4: Design Concept Options
+
+Build **at least 3 genuinely different concepts.** Start from the `angles_discovered` in the research brief and the animation mode analysis.
+
+For each concept, specify:
+
+#### 4a: Title and Hook
+
+**Hook construction patterns for animation:**
+
+| Pattern | Template | When to Use |
+|---------|----------|-------------|
+| **Visual surprise** | "Watch [thing] transform into [unexpected thing]." | When the animation itself IS the hook |
+| **Misconception flip** | "You've been visualizing [topic] wrong. Here's what it actually looks like." | When common mental models are wrong |
+| **Progressive reveal** | "Start with [simple]. End with [complex]. Every step animated." | When the topic has layered complexity |
+| **Impossible camera** | "What if you could see [invisible process] happening in real time?" | When animation reveals the unseeable |
+| **Data surprise** | "[Counterintuitive number]. Watch it happen." | When animated data is more powerful than static |
+
+**Rules:**
+- Hook must be under 20 words
+- Hook must promise a VISUAL experience, not just information
+- Hook must be grounded in a specific research finding
+
+#### 4b: Animation Mode and Approach
+
+For each concept, specify:
+- **Primary animation mode**: manim / remotion / ai_video / diagram_stills / mixed
+- **Why this mode**: grounded in technique research from the brief
+- **Reuse strategy**: What's the visual system? (recurring motifs, layout grid, color scheme, transition family)
+- **Complexity estimate**: How many unique scene types vs. reusable templates?
+
+#### 4c: Narrative Structure
+
+Choose from: `myth_busting`, `problem_solution`, `data_narrative`, `comparison`, `timeline`, `journey`, `analogy`, `progressive_build`, `transformation`
+
+**Animation-specific structure: `progressive_build`** — start simple, add complexity layer by layer. This is the classic 3Blue1Brown approach and works exceptionally well for math/technical topics.
+
+#### 4d: Duration and Platform
+
+| Platform | Duration Range | Word Budget (150 WPM) |
+|----------|---------------|----------------------|
+| TikTok | 30-60s | 65-150 words |
+| YouTube Shorts | 30-60s | 65-150 words |
+| YouTube | 60-300s | 150-750 words |
+| LinkedIn | 60-120s | 150-300 words |
+
+**Animation note:** Animation videos can be longer than live-action explainers because the visual density sustains attention. A 3-minute math animation holds attention better than a 3-minute talking head.
+
+#### 4e: Concept Diversity Check
+
+- [ ] No two concepts use the same animation mode
+- [ ] No two concepts use the same narrative structure
+- [ ] At least one concept is achievable with free/local tools only
+- [ ] At least one concept leverages the most surprising data point
+- [ ] Each concept's animation mode is grounded in technique research
+
+### Step 5: Present Concepts and Get Selection
+
+Present all concepts clearly to the user. For each concept, show:
+
+1. **Title** and **hook** — the creative pitch
+2. **Animation mode** — what the video will LOOK like (with a plain-language description)
+3. **Why this works** — research backing, in one sentence
+4. **Duration** — how long
+5. **Reuse strategy** — "5 scenes built from 2 templates" vs "8 unique scenes"
+
+Let the user select, combine, modify, or redirect.
+
+Record the selection in `selected_concept` with rationale and any modifications.
+
+### Step 6: Build the Production Plan
+
+For the selected concept, design the stage-by-stage production plan.
+
+**Animation-specific production plan fields:**
+
+```
+PRODUCTION PLAN (Animation Pipeline)
+
+animation_mode: [selected mode]
+reuse_strategy:
+  recurring_motifs: [list]
+  layout_system: [description]
+  transition_family: [type]
+  typography_hierarchy: [levels]
+  estimated_unique_scenes: [N]
+  estimated_reusable_templates: [N]
+
+stages:
+  script:
+    tools: [none — creative work]
+    cost: $0
+    notes: "Script must be written in animation beats — one visual idea per section"
+
+  scene_plan:
+    tools: [none — planning work]
+    cost: $0
+    notes: "Scene plan must specify animation mode per scene and reuse template references"
+
+  assets:
+    tools: [specific providers from preflight]
+    cost: [itemized]
+    notes: "Reusable motifs generated once, referenced by multiple scenes"
+
+  edit:
+    tools: [none — planning work]
+    cost: $0
+    notes: "Edit must preserve hold times and staggered reveals"
+
+  compose:
+    tools: [video_compose, audio_mixer]
+    cost: $0 (local rendering)
+    notes: "Text and diagrams must remain sharp at final resolution"
+
+  publish:
+    tools: [none — metadata work]
+    cost: $0
+```
+
+### Step 7: Build the Cost Estimate
+
+Itemize every paid operation:
+
+```
+COST ESTIMATE
+├── TTS Narration: [provider] × 1 run              $X.XX
+├── Image Generation: [provider] × N scenes          $X.XX
+│   (N unique + M reused = total scenes)
+├── AI Video Clips: [provider] × K clips (if any)   $X.XX
+├── Music: music_gen × 1 track                       $X.XX
+├── Math Animation: math_animate (local/free)        $0.00
+├── Diagram Generation: diagram_gen (local/free)     $0.00
+└── TOTAL ESTIMATED                                  $X.XX
+    Budget cap: $X.XX
+    Verdict: within_budget ✓ / over_budget ✗
+    Headroom: $X.XX for revisions
+```
+
+**Animation cost note:** Programmatic animation (Manim, Remotion, diagram_gen) is FREE. This means animation pipelines can often be much cheaper than explainer pipelines — the primary cost is TTS narration and any AI-generated images/video used as backgrounds or transitions.
+
+### Step 8: Assemble the Approval Gate
+
+```
+────────────────────────────────────────
+PROPOSAL READY FOR APPROVAL
+
+Concept: [selected title]
+Animation mode: [mode] — [plain description]
+Duration: [X] seconds for [platform]
+Reuse strategy: [N] unique scenes from [M] templates
+Estimated cost: $[X.XX] of $[budget] budget
+Production path: [premium/standard/budget/free]
+
+Proceed? (approve / approve with changes / reject)
+────────────────────────────────────────
+```
+
+**Critical rule:** The pipeline MUST NOT proceed past this stage without explicit approval.
+
+### Step 9: Submit
+
+Validate the `proposal_packet` artifact against `schemas/artifacts/proposal_packet.schema.json` and submit.
+
+## How This Connects Downstream
+
+| Downstream Stage | What It Takes From proposal_packet |
+|------------------|------------------------------------|
+| Script Director | `selected_concept` (title, hook, key_points, animation_mode, narrative_structure) + research data |
+| Scene Director | `selected_concept.animation_mode` + `reuse_strategy` + `production_plan.playbook` |
+| Asset Director | `production_plan.stages[assets].tools` — knows exactly which providers to use |
+| Executive Producer | `cost_estimate` — initializes budget tracking |
+| All stages | `approval.approved_budget_usd` — hard spending cap |
+
+## Common Pitfalls
+
+- **Ignoring animation mode feasibility**: If Manim isn't installed, don't propose a Manim-based concept. Design around constraints.
+- **Three versions of the same concept with different titles**: Structural diversity means different animation modes, different narrative structures, different hooks.
+- **Not leveraging free tools**: Animation has a huge cost advantage — Manim, Remotion, and diagram_gen are free. If proposing expensive AI video, justify why free alternatives won't work.
+- **Over-promising visual complexity**: 20 unique hand-crafted scenes is not realistic. Design reuse strategies that look varied but share underlying templates.
+- **Skipping the approval gate**: This is the whole point of pre-production. No shortcuts.
+- **Ignoring mathematical accuracy**: If the research brief flagged technical accuracy constraints, the concept MUST respect them. A beautiful but wrong animation is a failure.

skills/pipelines/animation/publish-director.md

@@ -0,0 +1,45 @@
+# Publish Director - Animation Pipeline
+
+## When To Use
+
+Package the animation so the metadata, thumbnail concept, and platform framing reflect the actual visual system of the project.
+
+## Prerequisites
+
+| 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 |
+| Playbook | Active style playbook | Visual naming consistency |
+
+## Process
+
+### 1. Match Packaging To The Animation Mode
+
+Examples:
+
+- diagram-heavy videos should look structured and legible,
+- kinetic-type pieces should package around strong copy,
+- illustrative animation should package around hero imagery.
+
+### 2. Preserve Visual-System Truth
+
+Store in `publish_log.metadata`:
+
+- `animation_mode`
+- `hero_frame_notes`
+- `thumbnail_concept`
+- `platform_notes`
+
+### 3. Quality Gate
+
+- metadata fits the actual animation mode,
+- thumbnail concept matches the final visual system,
+- exports are labeled by purpose and platform,
+- the package is usable without extra manual work.
+
+## Common Pitfalls
+
+- Writing generic metadata that ignores the animation style.
+- Creating a thumbnail concept unrelated to the final frames.
+- Mixing platform variants without clear labels.

skills/pipelines/animation/research-director.md

@@ -0,0 +1,256 @@
+# Research Director — Animation Pipeline
+
+## When to Use
+
+You are the **Research Director** for a generated animation video. You are the first stage in the pipeline — before any creative decisions, before any script, before any money is spent. Your job is to **deeply research the topic AND the animation approach** using web search and produce a `research_brief` artifact that grounds the entire video in real data, real pedagogy, and proven visual techniques.
+
+Animation videos differ from general explainers: the research must cover both **what to explain** (topic) and **how to animate it** (technique). A math-animation video about eigenvalues needs different visual research than a kinetic-typography brand video.
+
+**You do NOT make creative decisions.** You gather raw material. The Proposal Director downstream will use your findings to craft concept options with animation-mode recommendations.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/research_brief.schema.json` | Artifact validation |
+| User input | Topic, audience hint, animation hint | Research scope |
+| Tools | Web search, web fetch | Research execution |
+
+## Process
+
+### Step 1: Scope the Research
+
+Before searching anything, establish boundaries:
+
+- **Topic**: What is the core subject? Extract from user input.
+- **Audience hint**: Did the user mention who this is for? (developers, students, general public, professionals)
+- **Animation hint**: Did the user mention an animation style? (math animation, motion graphics, kinetic typography, diagram-led, illustrative)
+- **Platform hint**: Did the user mention where this will go? (YouTube, TikTok, LinkedIn, classroom)
+- **Depth**: Is this a well-known topic or niche?
+
+If the user's request is a single phrase like "make a math animation about eigenvalues," that's fine — you have enough to research. Do NOT ask clarifying questions at this stage.
+
+### Step 2: Content Landscape Scan
+
+**Goal:** Understand what already exists so we can find gaps.
+
+```
+SEARCH BATCH 1 — Landscape (run all in parallel)
+
+Q1: "[topic] animation" site:youtube.com
+    → Find: Existing animated explainers. Note animation styles used, view counts, quality.
+
+Q2: "[topic]" (animation OR "motion graphics" OR "animated explainer") -site:youtube.com
+    → Find: Articles, tutorials, and write-ups about animating this topic.
+
+Q3: "[topic] [current month] [current year]"
+    → Find: The freshest content. What's being published RIGHT NOW?
+
+Q4: "[topic]" (manim OR "3blue1brown" OR "motion design" OR "animated diagram")
+    → Find: Programmatic or technical animation approaches to this topic.
+```
+
+**Parse results for:**
+- Which animation styles have been used for this topic (and which haven't)
+- Quality benchmarks — what do the best animations of this topic look like?
+- Gaps — which visual approaches haven't been tried?
+- Whether programmatic animation (Manim) has been used for this topic before
+
+Record at least 3 entries in `landscape.existing_content` with specific titles, sources, and gap analysis.
+
+### Step 3: Trending Pulse
+
+**Goal:** Find what's happening RIGHT NOW — news, debates, discoveries.
+
+```
+SEARCH BATCH 2 — Trending (run all in parallel)
+
+Q5: "[topic]" (announcement OR discovery OR update OR breakthrough) after:[current year]-01-01
+    → Find: Recent events that make this topic timely.
+
+Q6: "[topic]" site:reddit.com after:[6 months ago]
+    → Find: Active community discussions, pain points.
+
+Q7: "[topic]" site:news.ycombinator.com
+    → Find: Technical audience opinions and analysis.
+
+Q8: "why is [topic]" (trending OR important OR everywhere) [current year]
+    → Find: Meta-commentary on why people care right now.
+```
+
+If no trending signal exists, note `timeliness_window: "evergreen"` and move on.
+
+### Step 4: Data and Evidence Gathering
+
+**Goal:** Find specific, citable facts that will anchor the script AND drive visual moments.
+
+```
+SEARCH BATCH 3 — Data (run all in parallel)
+
+Q9: "[topic]" statistics [current year]
+    → Find: Hard numbers — adoption rates, performance benchmarks, measurements.
+
+Q10: "[topic]" (study OR research OR survey) [current year - 1] OR [current year]
+     → Find: Academic or industry research.
+
+Q11: "[topic]" "surprisingly" OR "counterintuitively" OR "most people don't know"
+     → Find: Surprising facts — these become visual hooks.
+
+Q12: "[topic]" (comparison OR benchmark OR "vs") data
+     → Find: Comparative data that becomes animated stat cards or side-by-side visuals.
+```
+
+**For each data point, record:**
+- The specific claim (precise, not vague)
+- Source URL and source name
+- Credibility rating: `primary_source`, `secondary_source`, `anecdotal`
+- Surprise factor: expected or counterintuitive?
+- **Visual potential**: Can this be animated? (e.g., "73% → 23%" is a great shrinking bar chart moment; "it's important" is not animatable)
+
+**Minimum: 3 data points. Target: 5-8.**
+
+### Step 5: Audience Mining
+
+**Goal:** Understand what real people ask, believe, and get wrong.
+
+```
+SEARCH BATCH 4 — Audience (run all in parallel)
+
+Q13: "[topic]" site:reddit.com "help" OR "confused" OR "why does" OR "ELI5"
+     → Find: Real questions from real people.
+
+Q14: "[topic]" site:quora.com OR site:stackoverflow.com
+     → Find: Structured Q&A — what do beginners ask?
+
+Q15: "[topic]" "common mistakes" OR "myths" OR "misconceptions"
+     → Find: What people get wrong — animation can powerfully show myth vs reality.
+
+Q16: "[topic]" "wish I knew" OR "before you start" OR "nobody tells you"
+     → Find: Insider knowledge.
+```
+
+**Parse results for:**
+- Top 5+ real questions
+- Common misconceptions (great for "wrong way → right way" animation transitions)
+- Knowledge level of the target audience
+
+### Step 6: Animation Technique Research (ANIMATION-SPECIFIC)
+
+**Goal:** Research how to best ANIMATE this topic — what visual techniques work.
+
+This step is what makes the animation research-director different from the explainer version.
+
+```
+SEARCH BATCH 5 — Animation Techniques (run all in parallel)
+
+Q17: "[topic]" (visualization OR "visual explanation" OR infographic OR diagram)
+     → Find: How others have visualized this concept.
+
+Q18: "[topic category]" animation technique (motion graphics OR manim OR "after effects")
+     → Find: Specific animation techniques used for this kind of content.
+
+Q19: "[topic]" "step by step" OR "how it works" visual
+     → Find: Sequential visual breakdowns — inform scene progression.
+
+Q20: "animate [topic-related-process]" OR "[topic] animation tutorial"
+     → Find: Technical approaches to animating this concept.
+```
+
+**For each technique found, record:**
+- What the technique is (e.g., "progressive diagram build", "morph between states", "particle simulation")
+- Where it was used (source URL)
+- Which animation mode it maps to: `manim`, `remotion`, `motion_graphics`, `ai_video`, `illustrative`
+- Complexity: `simple` (reusable components), `moderate` (custom but repeatable), `complex` (bespoke per scene)
+- Whether it's been done before for this topic (novelty signal)
+
+**Minimum: 2 technique references. Target: 4-6.**
+
+### Step 7: Mathematical/Technical Accuracy Check (If Applicable)
+
+**For math-animation, science, or technical topics:**
+
+```
+Q21: "[topic]" (formal definition OR mathematical OR "technically")
+     → Find: The precise technical definition — animation must not oversimplify to the point of being wrong.
+
+Q22: "[topic]" "common error" OR "often confused with" OR "technically incorrect"
+     → Find: Technical pitfalls that the animation must avoid.
+```
+
+**Record:**
+- The precise definition or formula
+- Common simplification errors
+- What level of simplification is acceptable for the target audience
+- Any visual metaphors that are technically misleading (e.g., "electrons orbiting like planets" is wrong)
+
+If the topic is not math/science, skip this step.
+
+### Step 8: Angle Synthesis
+
+Using everything from Steps 2-7, identify at least 3 genuinely different angle candidates.
+
+For each angle, specify:
+
+| Field | What | Quality Bar |
+|-------|------|-------------|
+| `name` | Short title (5-8 words) | Specific, not generic |
+| `hook` | One-sentence grabber | Must create an information gap or surprise |
+| `type` | `trending`, `evergreen`, `contrarian`, `narrative`, `data_driven` | Categorize honestly |
+| `why_now` | Why this angle is compelling right now | Must cite specific research findings |
+| `grounded_in` | Which data points or audience insights support it | Cross-reference your findings |
+| `animation_fit` | Which animation mode(s) best serve this angle | Must reference technique research from Step 6 |
+
+**Angle diversity checklist:**
+- [ ] At least one angle leverages a surprising data point or visual
+- [ ] At least one angle is evergreen
+- [ ] At least one angle maps to a different animation mode than the others
+- [ ] No two angles use the same hook structure
+- [ ] Each angle's `animation_fit` references specific technique research
+
+### Step 9: Source Bibliography
+
+Compile all URLs used, organized by section. Minimum 5 sources.
+
+**Source quality rules:**
+- Primary sources > secondary > anecdotal
+- At least 2 primary sources
+- Every data_point must have a source_url
+- Flag sources older than 2 years
+
+### Step 10: Assemble and Submit
+
+Build the `research_brief` artifact per the schema. Include:
+
+1. `research_summary` — one paragraph: the most important insight AND the most promising animation approach.
+2. All sections from Steps 2-9
+
+Validate against `schemas/artifacts/research_brief.schema.json` before submitting.
+
+## Quality Bar
+
+| Criterion | Minimum | Target |
+|-----------|---------|--------|
+| Existing content surveyed | 3 pieces | 5-8 pieces |
+| Data points with sources | 3 | 5-8 |
+| Audience questions sourced | 3 | 5-10 |
+| Animation techniques researched | 2 | 4-6 |
+| Angle candidates | 3 | 4-5 |
+| Total sources cited | 5 | 10-15 |
+| Searches executed | 12 | 18-22 |
+
+## Execution Constraints
+
+| Constraint | Value | Why |
+|------------|-------|-----|
+| Max time on research | 3-5 minutes | Diminishing returns |
+| Max searches | 25 | Prevent rabbit holes |
+| Min searches | 12 | Ensure coverage |
+| No paid tools | — | Research uses web search only — zero cost |
+
+## Common Pitfalls
+
+- **Skipping animation technique research**: The explainer research-director doesn't need this, but animation does. The `animation_fit` field in angles is mandatory.
+- **Ignoring mathematical accuracy**: For math topics, the research MUST include the precise definition. An animation that looks cool but teaches wrong math is worse than no animation.
+- **Only searching topic, not visualization**: If the topic is "Fourier transforms," you must search both "Fourier transforms" AND "Fourier transform visualization/animation." The technique research is half the value.
+- **Treating all animation as one category**: Manim, Remotion, AI video, and motion graphics are fundamentally different tools with different strengths. Research should inform which mode fits the topic.
+- **Recording vague visual references**: "A nice animation" is not useful. "Progressive circle-to-wave morph showing sine decomposition (3Blue1Brown style, Manim)" is useful.

skills/pipelines/animation/scene-director.md

@@ -0,0 +1,65 @@
+# Scene Director - Animation Pipeline
+
+## When To Use
+
+You are converting the script into a feasible animation plan. This is the stage that decides whether the project feels designed or chaotic.
+
+## Prerequisites
+
+| 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 |
+| Playbook | Active style playbook | Palette, typography, motion consistency |
+
+## Process
+
+### 1. Make An Animatic-Minded Plan
+
+For each scene, define:
+
+- what appears first,
+- what changes,
+- what is held,
+- how the scene exits.
+
+### 2. Limit Transition Families
+
+Choose a small set of transition meanings:
+
+- cut,
+- fade,
+- slide,
+- transform.
+
+### 3. Match Scene Type To Tool Path
+
+Use:
+
+- `diagram` scenes for structured explanation,
+- `animation` scenes for motion-first sequences,
+- `text_card` for clean high-impact copy moments,
+- `generated` only where needed.
+
+### 4. Use Metadata For Timing Rules
+
+Recommended metadata keys:
+
+- `animatic_rules`
+- `transition_rules`
+- `hold_rules`
+- `tool_path_map`
+- `reusable_motifs`
+
+### 5. Quality Gate
+
+- every scene has a clear timing intent,
+- the transition system is limited and meaningful,
+- the tool path is explicit,
+- the sequence feels like one designed system.
+
+## Common Pitfalls
+
+- Adding a new transition idea in every scene.
+- Planning scenes that have no realistic production path.
+- Overanimating text-heavy scenes.

skills/pipelines/animation/script-director.md

@@ -0,0 +1,117 @@
+# Script Director — Animation Pipeline
+
+## When to Use
+
+This stage turns the approved proposal into animation-ready beats. The script must leave room for motion, staging, and hold time — and must integrate the research findings and respect the selected animation mode.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `proposal_packet` from Proposal Director | Selected concept, animation mode, target duration, reuse strategy |
+| Optional artifact | `research_brief` from Research Director | Data points, audience insights, accuracy constraints |
+| Tools | `transcriber` | Optional source transcript support |
+
+## Process
+
+### 1. Absorb the Proposal
+
+Read the `proposal_packet.selected_concept` thoroughly. Extract:
+
+- **Title and hook** — the opening must deliver on this promise
+- **Animation mode** — `manim`, `remotion`, `ai_video`, `diagram_stills`, or `mixed`. This constrains how you write.
+- **Narrative structure** — `progressive_build`, `myth_busting`, `journey`, etc. Follow it.
+- **Target duration** — word budget = target_seconds × 2.5 words/sec (at 150 WPM)
+- **Key points** — from `selected_concept.key_points`
+- **Reuse strategy** — recurring motifs mean recurring script structures
+
+If `research_brief` is available, also extract:
+- **Data points** — weave specific, sourced facts into the narration (not vague claims)
+- **Audience misconceptions** — address them directly in the script
+- **Mathematical accuracy notes** — constraints on what can and cannot be simplified
+
+### 2. Write in Animation Beats
+
+Each section should express ONE clear visual idea:
+
+- **Statement** — introduce a concept (entrance animation)
+- **Demonstration** — show it working (the main animation)
+- **Transformation** — morph from one state to another (transition)
+- **Comparison** — show two things side by side (split screen or sequential)
+- **Conclusion** — land the insight (hold + emphasis)
+
+**Animation mode affects writing style:**
+
+| Mode | Writing Style |
+|------|---------------|
+| Manim | Precise, mathematical. Each beat maps to a specific geometric transformation. Write narration that describes what's being shown. |
+| Remotion | Data-driven, punchy. Each beat maps to a chart/component animation. Narration complements the visual data. |
+| AI Video | Descriptive, evocative. Each beat describes a scene the AI should generate. Narration adds context the visual can't convey. |
+| Diagram Stills | Explanatory, progressive. Each beat adds a layer to a building diagram. Narration walks through the build. |
+| Mixed | Varies per section — tag each section's mode in metadata. |
+
+### 3. Keep On-Screen Text Tight
+
+Animation-heavy pieces fail when the viewer has to read too much while motion is happening:
+
+- **Max 8 words** for on-screen titles
+- **Max 15 words** for on-screen descriptions
+- Prefer phrases over sentences
+- Prefer numbers and labels over paragraphs
+- Mathematical notation is fine — it IS the content in math-animation mode
+
+### 4. Leave Room for Visual Holds
+
+Do NOT fill every second with new information. The scene plan will need time for:
+
+- **Entrances** (0.5-1s): objects appearing on screen
+- **Reveals** (1-2s): progressive disclosure of complexity
+- **Holds** (1-3s): letting the viewer absorb what they see
+- **Exits** (0.5s): clearing the stage for the next beat
+
+**Rule of thumb:** For every 10 seconds of narration, budget 3-4 seconds of visual breathing room. A 90-second video should have ~60-65 seconds of narration and ~25-30 seconds of visual holds.
+
+### 5. Use Metadata for Motion Intent
+
+Recommended metadata keys per section:
+
+- `beat_type`: statement / demonstration / transformation / comparison / conclusion
+- `animation_mode`: which mode this section uses (important for mixed mode)
+- `text_constraints`: max words for on-screen text in this section
+- `narration_plan`: how narration relates to visual (describes / complements / silent)
+- `visual_priority`: what the viewer should focus on (the animation, the text, the data)
+- `hold_time_seconds`: minimum visual hold time after this section's content
+- `data_source`: if this section uses a research data point, reference it
+
+### 6. Research Integration
+
+If a `research_brief` is available:
+
+- Use at least 2 data points from the research in the narration
+- Ground the hook in the research's most surprising finding
+- Address at least 1 audience misconception if the narrative structure supports it
+- Cite sources naturally ("According to [source]..." or "A [year] study found...")
+- Do NOT invent statistics — only use what the research found
+
+### 7. Quality Gate
+
+Before submitting the script, verify:
+
+- [ ] Every section supports ONE strong visual idea
+- [ ] On-screen text is concise (phrases, not paragraphs)
+- [ ] Timing is animation-friendly (holds budgeted)
+- [ ] Word count is within ±10% of target duration
+- [ ] Animation mode is respected in writing style
+- [ ] Research data points are integrated (if research_brief available)
+- [ ] Mathematical accuracy is maintained (if applicable)
+- [ ] Later stages can map scenes cleanly from this script
+
+## Common Pitfalls
+
+- **Writing too many ideas into one section.** One beat = one visual idea.
+- **Treating captions and on-screen text as the same thing.** Subtitles are narration transcribed. On-screen text is designed content that's part of the animation.
+- **Forgetting that motion needs pause and emphasis.** Budget hold times.
+- **Ignoring the animation mode.** A Manim script reads differently than an AI video script.
+- **Writing research-less scripts when a research_brief exists.** If the research found surprising data, use it. Generic scripts waste the research investment.
+- **Oversimplifying math to the point of being wrong.** Check the research brief's accuracy notes.

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

@@ -0,0 +1,101 @@
+# Asset Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+This stage prepares the actual spokesperson ingredients: narration, avatar or lip-sync footage, subtitle assets, branded backgrounds, and the minimal support graphics needed to complete the cut.
+
+## Prerequisites
+
+| 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"]` | Presenter plan and narration needs |
+| Tools | `talking_head`, `lip_sync`, `tts_selector`, `subtitle_gen`, `image_selector`, `audio_enhance` — selectors auto-discover all available providers from the registry | Avatar, narration, and support asset options |
+| Playbook | Active style playbook | Background, type, and subtitle rules |
+
+## Process
+
+### 1. Lock The Avatar Generation Path
+
+Use one primary path and record it clearly:
+
+- `talking_head` from still image plus audio,
+- `lip_sync` from existing presenter plate plus new audio,
+- externally supplied avatar render if created outside the current runtime.
+
+Do not hide a blocked avatar path. Record it.
+
+### 1b. Sample Preview (Prevents Wasted Spend)
+
+Before batch-generating assets, produce one sample of each expensive type and show the user:
+
+1. **TTS sample** (if generating narration): Generate one section. Confirm voice, pace, and persona before batching the rest.
+2. **Avatar sample** (if using `talking_head`): Generate a short test clip. Confirm the avatar quality is acceptable before committing to full generation.
+
+If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
+
+### 2. Resolve Narration Before Support Graphics
+
+Spokesperson videos depend on speech. Determine whether narration is:
+
+- supplied,
+- TTS-generated,
+- already embedded in a presenter plate.
+
+If narration is missing and no TTS tool is available, mark the project blocked instead of pretending the stage succeeded.
+
+### 3. Build The Minimal Support Kit
+
+Prepare only what the scene plan actually needs:
+
+- subtitle files,
+- one lower-third system,
+- CTA card,
+- background or plate assets,
+- optional still or product support images.
+
+### 4. Use Metadata For Capability Truth
+
+Recommended metadata keys:
+
+- `avatar_generation_path`
+- `narration_assets`
+- `subtitle_assets`
+- `background_assets`
+- `scene_asset_index`
+- `blocked_assets`
+
+### 5. Quality Gate
+
+- the avatar path is explicit,
+- narration and avatar assets align,
+- support graphics stay minimal,
+- every referenced file exists.
+
+## No-Avatar Path
+
+When the EP has triggered a narration-over-graphics pivot (neither `talking_head` nor `lip_sync` available), skip avatar generation entirely and produce a graphics-driven asset kit instead:
+
+### What to produce:
+1. **Narration audio** — via `tts_selector` (mandatory; block the project if no TTS is available either).
+2. **Scene visuals** — via `image_selector` or `video_selector`. One primary visual per scene that reinforces the spoken point (diagram, illustration, product shot, or stock footage).
+3. **Subtitle files** — same as standard path.
+4. **Text cards** — key-point overlays, stat cards, CTA end card.
+5. **Backgrounds** — consistent family matching the playbook.
+
+### What to skip:
+- No `talking_head` or `lip_sync` calls.
+- No presenter framing metadata.
+- `avatar_generation_path` should be set to `"none — narration-over-graphics pivot"`.
+
+### Metadata for this path:
+- `avatar_generation_path`: `"narration_over_graphics"`
+- `pivot_reason`: why the no-avatar path was chosen
+- All other metadata keys remain the same.
+
+## 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.

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

@@ -0,0 +1,60 @@
+# Compose Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Render the final spokesperson outputs. The bar is simple: the presenter must look stable, speech must be clear, and subtitles or support cards must not crowd the frame.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | What to render |
+| Tools | `video_compose`, `audio_mixer`, `video_stitch`, `audio_enhance` | Render and audio finishing |
+| Playbook | Active style playbook | Typography and layout rules |
+
+## Process
+
+### 1. Render The Hero Cut First
+
+Prefer one strong master before derivatives. Compose:
+
+- presenter video,
+- subtitles,
+- lower-thirds,
+- CTA cards,
+- mixed narration.
+
+### 2. Keep The Frame Clean
+
+Subtitle and CTA placement matter more here than flashy transitions. Leave the face and mouth region unobstructed.
+
+### 3. Verify Mouth Timing And Audio
+
+If the avatar path used lip sync or audio-driven talking head, check:
+
+- mouth timing,
+- face artifacts,
+- drift on long sections,
+- audio clarity.
+
+### 4. Verify Every Output
+
+Record important findings in:
+
+- `render_report.verification_notes`
+- `render_report.warnings`
+- `render_report.metadata.variant_notes`
+
+### 5. Quality Gate
+
+- the output file is valid,
+- speech is clear,
+- subtitles stay readable,
+- the presenter remains visually stable.
+
+## Common Pitfalls
+
+- Letting subtitles cover the chin or mouth area.
+- Shipping a long lip-sync render without spot-checking drift.
+- Making derivative crops that cut off the presenter or CTA.

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

@@ -0,0 +1,47 @@
+# Edit Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Turn the planned presenter scenes and produced assets into a coherent spokesperson timeline. The quality bar is steady delivery, readable support layers, and a clear CTA landing.
+
+## Process
+
+### 1. Cut The Presenter Track First
+
+Assemble the core spokesperson performance before adding support layers. If the presenter cut is weak, extra graphics will not rescue it.
+
+### 2. Add Support Layers Sparingly
+
+Use overlays only where they help:
+
+- short proof points,
+- product names,
+- pricing or feature cards,
+- CTA reinforcement,
+- subtitles.
+
+### 3. Respect Spoken Rhythm
+
+Keep pauses where they help emphasis. Do not trim so tightly that the avatar feels rushed or robotic.
+
+### 4. Plan Deliverables Clearly
+
+Recommended metadata keys:
+
+- `hero_cut_order`
+- `cta_frame_range`
+- `overlay_timing_map`
+- `variant_decisions`
+
+### 5. Quality Gate
+
+- the presenter remains the anchor,
+- overlays are timed cleanly,
+- scene transitions are calm and intentional,
+- the CTA lands once and clearly.
+
+## Common Pitfalls
+
+- Overcutting to simulate energy.
+- Letting captions, side panels, and lower thirds compete for the same area.
+- Ending without a clean CTA hold.

skills/pipelines/avatar-spokesperson/executive-producer.md

@@ -0,0 +1,171 @@
+# Executive Producer — Avatar Spokesperson Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for an avatar spokesperson video. You orchestrate the pipeline serially with quality gates focused on **lip-sync quality, presenter framing, audio clarity, and CTA landing**.
+
+**No pre-production stages.** The project is script-driven with a digital presenter as the anchor. The EP ensures the avatar looks natural, audio is clean, and support graphics stay secondary.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/avatar-spokesperson.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: avatar-spokesperson
+  playbook: <selected>
+  target_duration_seconds: <from brief>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Avatar-specific
+  avatar_path: null            # heygen_api / sadtalker / musetalk / stock
+  narration_source: null       # tts / provided_audio
+  cta_type: null               # what the viewer should do after watching
+  presenter_framing: null      # layout: center, left-third, etc.
+
+  artifacts:
+    idea: null
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## Pivot Decision Matrix
+
+`talking_head` is the preferred tool but commonly unavailable (requires GPU or HeyGen API key). When blocked, the EP must route the project explicitly — not improvise.
+
+```
+IF talking_head AVAILABLE:
+  → Standard avatar path. Proceed as normal.
+
+IF talking_head UNAVAILABLE and lip_sync AVAILABLE:
+  → Lip-sync path. User must supply a presenter plate (existing footage).
+    Script and scene plan stay the same.
+
+IF NEITHER talking_head NOR lip_sync AVAILABLE:
+  → Narration-Over-Graphics pivot.
+    Tell the user: "No avatar tool is configured. I can produce a
+    narration-over-graphics video instead — your script and CTA stay the same,
+    but the presenter is replaced with styled visuals, text overlays, and
+    voice-over narration."
+    If the user approves:
+      - Switch scene-director to narration-over-graphics layout (see its fallback section).
+      - Switch asset-director to no-avatar path (see its fallback section).
+      - CTA and script are unchanged.
+    If the user declines:
+      - Mark the project blocked. Do not proceed with a half-working avatar.
+```
+
+**The pivot decision happens at G1 (after IDEA).** Do not wait until the ASSETS stage to discover the tool is missing.
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Avatar path feasibility
+  - Is the avatar generation path explicit (which tool)?
+  - Is the required tool available in the registry?
+  - If tool unavailable: run the Pivot Decision Matrix above
+  - Are CTA and audience appropriate for spokesperson format?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Spoken copy quality
+  - Is the script concise and natural-sounding when read aloud?
+  - Are scene breaks realistic for avatar delivery (no mid-sentence cuts)?
+  - Is on-screen text restrained (presenter is the focus, not graphics)?
+
+CHECK: Duration fit
+  - Word count aligns with natural speaking pace (~140-160 WPM for spokesperson)
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Presenter layout
+  - Is the speaker layout consistent and coherent?
+  - Are support overlays secondary to the presenter?
+  - Are background changes minimal (max 2-3 distinct backgrounds)?
+
+CHECK: Subtitle safety
+  - Is subtitle placement planned to avoid overlapping the presenter's face?
+```
+
+### After ASSETS stage:
+```
+CHECK: Avatar generation
+  - Did the avatar tool produce a usable video?
+  - Is lip-sync timing acceptable?
+  - Is narration audio clear and natural?
+  - Budget gate: 90% threshold warning
+
+CHECK: Support asset restraint
+  - Are support graphics (backgrounds, overlays) minimal?
+  - Do they match the playbook style?
+```
+
+### After EDIT stage:
+```
+CHECK: Presenter primacy
+  - Is the presenter visually primary in every scene?
+  - Are graphics and captions reinforcing, not crowding?
+  - Does CTA land clearly (dedicated end section)?
+
+CHECK: Timeline completeness
+  - All cuts reference valid assets
+  - Audio ducking if background music present
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe: duration, resolution, codec
+  - Lip-sync or mouth timing acceptable for the chosen path
+  - Subtitle placement clean and non-overlapping
+  - Audio clear and presenter-focused
+  - No uncanny-valley artifacts that break immersion
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Avatar path feasibility, CTA fit | Revise |
+| G2 | script | Spoken copy quality, duration | Revise |
+| G3 | scene_plan | Presenter layout, subtitle safety | Revise |
+| G4 | assets | Avatar quality, lip-sync, budget | Revise |
+| G5 | edit | Presenter primacy, CTA landing | Revise |
+| G6 | compose | Lip-sync, subtitle placement, audio | Revise or send-back |
+| G7 | publish | Metadata, presenter thumbnail | Revise |
+| FINAL | all | Avatar naturalness, audio, CTA | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $2) |
+| Max total wall-time | 12 minutes |
+
+## Common Pitfalls
+
+- **Uncanny valley**: If avatar quality is low, it undermines the entire video. Be honest about tool capabilities.
+- **Graphics overload**: The presenter IS the content. Support graphics should be minimal.
+- **Unnatural script**: Spokesperson scripts must sound conversational, not robotic or essay-like.
+- **Ignoring CTA**: Every spokesperson video has a purpose. The CTA must land clearly.

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

@@ -0,0 +1,73 @@
+# Idea Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Use this pipeline when the deliverable is a presenter-led avatar video: a spokesperson spot, product intro, onboarding message, internal comms update, or short scripted explainer where the speaker remains the visual anchor.
+
+Your first job is to classify the avatar path honestly before anyone writes polished copy for an impossible production setup.
+
+## Reference Inputs
+
+- `docs/avatar-spokesperson-best-practices.md`
+- `skills/creative/storytelling.md`
+- `skills/creative/short-form.md`
+
+## Process
+
+### 1. Classify The Avatar Path
+
+Record which production mode the project actually has:
+
+- `platform_avatar`
+- `photo_talking_head`
+- `presenter_plate_lip_sync`
+
+Also record whether the avatar already exists or still has to be created outside the current run.
+
+### 2. Define The Message Shape
+
+Capture:
+
+- audience,
+- core offer or CTA,
+- runtime target,
+- platform targets,
+- whether the video is sales, onboarding, support, or announcement led.
+
+Spokesperson videos work best when they have one clear job.
+
+### 3. Capture Source Reality
+
+The brief should explicitly state:
+
+- whether clean narration is supplied,
+- whether TTS is acceptable,
+- whether brand backgrounds or overlays exist,
+- whether subtitles are required,
+- whether multilingual variants are expected.
+
+### 4. Build The Brief
+
+Recommended metadata keys:
+
+- `avatar_path`
+- `avatar_exists`
+- `narration_source`
+- `target_audience`
+- `cta_type`
+- `background_strategy`
+- `deliverable_mix`
+- `missing_capabilities`
+
+### 5. Quality Gate
+
+- the avatar path is explicit,
+- the message is narrow enough for a spokesperson format,
+- missing narration or avatar dependencies are visible early,
+- deliverables fit the actual source setup.
+
+## Common Pitfalls
+
+- Treating a generic generated-video request as a deterministic avatar workflow.
+- Writing the CTA before confirming the avatar and narration path.
+- Planning multiple aspect ratios before the hero layout is proven.

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

@@ -0,0 +1,44 @@
+# Publish Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Package the finished spokesperson outputs for delivery. This stage should make it obvious which file is the hero cut, which are derivatives, and what message or audience each version serves.
+
+## Process
+
+### 1. Label Deliverables Clearly
+
+Distinguish:
+
+- hero cut,
+- vertical cutdown,
+- square cutdown,
+- language variants,
+- watermark or review versions.
+
+### 2. Keep Metadata Message-Led
+
+Recommended metadata keys:
+
+- `audience_segment`
+- `cta_copy`
+- `offer_name`
+- `locale`
+- `thumbnail_concept`
+
+### 3. Package Review Notes
+
+If the avatar path has limitations such as visible lip-sync risk, retain that note in the package instead of hiding it.
+
+### 4. Quality Gate
+
+- exports are clearly named,
+- metadata matches the intended message,
+- poster frame or thumbnail concept features the presenter cleanly,
+- review notes stay attached to the package.
+
+## Common Pitfalls
+
+- Mixing hero and derivative exports without clear naming.
+- Reusing generic metadata that ignores the spokesperson offer.
+- Dropping risk notes that matter for downstream publishing teams.

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

@@ -0,0 +1,82 @@
+# Scene Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Plan the visual system for the presenter-led cut. This stage decides how the speaker sits in frame, what support layers appear, and which aspect ratios are actually worth building.
+
+## Reference Inputs
+
+- `docs/avatar-spokesperson-best-practices.md`
+- `skills/creative/typography.md`
+
+## Process
+
+### 1. Lock The Presenter Layout
+
+Choose a primary layout:
+
+- full presenter center frame,
+- presenter plus side panel,
+- presenter plus lower-third system,
+- presenter over branded background.
+
+Keep the hero layout simple and reusable.
+
+### 2. Choose Background Discipline
+
+Use one family:
+
+- clean solid or gradient background,
+- branded office or set,
+- product UI or image plate,
+- transparent-avatar composite plan.
+
+Background changes should mark real section changes, not compensate for weak copy.
+
+### 3. Map Support Layers
+
+For each scene, decide whether the support layer is:
+
+- none,
+- subtitle only,
+- lower third,
+- product image,
+- side-panel proof point,
+- CTA card.
+
+### 4. Plan Variants Late
+
+Default to one hero cut first. Only plan vertical or square variants if the presenter layout and text system can survive the crop.
+
+### 5. Quality Gate
+
+- the presenter remains primary,
+- support layers solve specific communication needs,
+- the background system is consistent,
+- variant ambition stays realistic.
+
+## Narration-Over-Graphics Fallback
+
+When the EP triggers a no-avatar pivot (no `talking_head` or `lip_sync` available), redesign the visual system to carry the story with graphics and voice-over instead of a presenter:
+
+### Layout changes:
+- **Primary frame**: full-screen visual (background, image, diagram, or motion graphic) with voice-over narration underneath.
+- **Support layers**: key-point text cards, lower-third stats, illustrated diagrams, product screenshots.
+- **CTA scene**: dedicated end card with clear CTA text, no presenter needed.
+
+### What stays the same:
+- The script and scene breaks are unchanged — the narration drives pacing.
+- Subtitle planning is unchanged.
+- Background discipline still applies (consistent family, not random).
+
+### What changes:
+- No presenter framing decisions (center, left-third, etc.) — replaced with full-frame visual compositions.
+- Each scene needs a **primary visual** that reinforces the spoken content, since there's no face to anchor attention.
+- Plan more visual variety per scene — without a presenter, static backgrounds feel empty.
+
+## Common Pitfalls
+
+- Switching backgrounds every few seconds.
+- Filling empty space with decorative panels.
+- Assuming a landscape presenter layout will survive a vertical crop untouched.
+- (Fallback mode) Producing a wall of text on screen to compensate for no presenter — let the narration carry the content.

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

@@ -0,0 +1,65 @@
+# Script Director - Avatar Spokesperson Pipeline
+
+## When To Use
+
+Turn the approved brief into scene-safe spoken copy for an avatar presenter. The quality bar is not literary flourish. It is spoken clarity, believable pacing, and one clean point per scene.
+
+## Reference Inputs
+
+- `docs/avatar-spokesperson-best-practices.md`
+- `skills/creative/storytelling.md`
+
+## Process
+
+### 1. Write For Speech, Not For Slides
+
+Prefer:
+
+- short sentences,
+- direct verbs,
+- one idea per beat,
+- explicit transitions,
+- conversational emphasis.
+
+If the copy sounds like a brochure when read aloud, rewrite it.
+
+### 2. Break Into Scene-Safe Chunks
+
+Avatar scenes are easier to manage when each section is compact. A useful starting point is:
+
+- hook,
+- value statement,
+- proof or feature beat,
+- CTA.
+
+### 3. Keep On-Screen Text Light
+
+The presenter is already carrying attention. Use on-screen text only for:
+
+- product names,
+- short proof points,
+- CTA copy,
+- legal or compliance text that must appear.
+
+### 4. Use Metadata For Delivery Notes
+
+Recommended metadata keys:
+
+- `scene_copy_map`
+- `cta_language`
+- `pronunciation_notes`
+- `supplied_script_source`
+- `legal_text_requirements`
+
+### 5. Quality Gate
+
+- the copy sounds spoken,
+- scene lengths are realistic,
+- CTA placement is clear,
+- text overlays are restrained.
+
+## Common Pitfalls
+
+- Overstuffing one scene because the script reads well on paper.
+- Duplicating the same sentence in speech and large text overlays.
+- Writing humor or improvisational beats the avatar path cannot sell.

skills/pipelines/cinematic/asset-director.md

@@ -0,0 +1,78 @@
+# Asset Director - Cinematic Pipeline
+
+## When To Use
+
+This stage prepares the usable media for the final cinematic edit: source selects, title-card assets, optional support inserts, music, ambience, and subtitle assets when needed.
+
+## Prerequisites
+
+| 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 |
+| 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 |
+
+## Process
+
+### 1. Prioritize Source Selects
+
+Start with:
+
+- source footage selects,
+- stills,
+- title-card backgrounds,
+- any approved provided music or ambient beds.
+
+These are the primary materials. Everything else is support.
+
+### 1b. Sample Preview (Prevents Wasted Spend)
+
+Before batch-generating support assets, produce one sample of each expensive generated type and show the user:
+
+1. **Generated insert sample** (if using `image_selector` or `video_selector`): Generate one representative visual. Confirm it complements the source footage before batching.
+2. **Music sample** (if using `music_gen`): Generate a short clip. Confirm mood and energy match the beat plan.
+
+If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
+
+### 2. Generate Support Assets Only Where Needed
+
+Optional generated assets should fill clear gaps:
+
+- missing transitional b-roll,
+- concept-led inserts,
+- texture or atmosphere cards,
+- simple textural motion backgrounds.
+
+### 3. Prepare A Real Audio Plan
+
+Store:
+
+- chosen music track or prompt,
+- ambience layers,
+- impact or transition sounds,
+- subtitle assets if dialogue or narration is present.
+
+### 4. Use Metadata For Rights And Intent
+
+Recommended metadata keys:
+
+- `source_selects`
+- `music_plan`
+- `ambience_plan`
+- `title_assets`
+- `generated_support_assets`
+- `rights_notes`
+
+### 5. Quality Gate
+
+- source and support assets are clearly distinguished,
+- generated inserts are limited and purposeful,
+- audio plan matches the beat map,
+- every referenced file exists.
+
+## Common Pitfalls
+
+- Generating extra shots before proving the source edit works.
+- Treating music as a single loop instead of a beat-aware element.
+- Forgetting rights or provenance notes for supplied assets.

skills/pipelines/cinematic/compose-director.md

@@ -0,0 +1,53 @@
+# Compose Director - Cinematic Pipeline
+
+## When To Use
+
+Render the cinematic piece with careful attention to grade, audio dynamics, and frame treatment. This is not a generic export step.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Edit plan and media assets |
+| Tools | `video_compose`, `audio_mixer`, `video_stitch`, `video_trimmer`, `color_grade`, `audio_enhance` | Render and finishing |
+| Playbook | Active style playbook | Finish consistency |
+
+## Process
+
+### 1. Use Frame Treatment Deliberately
+
+Only use letterbox, 24fps intent, or heavy grading if they help the piece. Do not apply them because the pipeline name says cinematic.
+
+### 2. Preserve Audio Dynamics
+
+The mix should allow:
+
+- quiet moments,
+- impact moments,
+- clear dialogue or narration,
+- controlled music swells.
+
+### 3. Verify The Final Mood
+
+Check:
+
+- opening frame,
+- reveal beat,
+- final landing,
+- subtitle readability where relevant.
+
+### 4. Use Render Metadata
+
+Recommended metadata keys:
+
+- `frame_treatment`
+- `grade_profile`
+- `mix_notes`
+- `variant_outputs`
+
+## Common Pitfalls
+
+- Flattening the audio so the piece loses dynamics.
+- Applying letterbox to footage that needs every pixel.
+- Letting grading or sharpening damage faces or text.

skills/pipelines/cinematic/edit-director.md

@@ -0,0 +1,56 @@
+# Edit Director - Cinematic Pipeline
+
+## When To Use
+
+This stage turns the beat map into a paced cinematic timeline. Rhythm and restraint matter more than effect count.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, hero frames, beat map |
+| Playbook | Active style playbook | Typography and transition consistency |
+
+## Process
+
+### 1. Cut By Emotion First
+
+Cuts should follow:
+
+- emotional emphasis,
+- reveal timing,
+- musical turns,
+- visual contrast.
+
+Do not optimize only for information density.
+
+### 2. Protect Strong Moments
+
+If a look, line, or gesture is doing the work, let it live. Do not over-cover it with extra inserts.
+
+### 3. Use Sound To Push The Edit
+
+Ambience, impacts, dropouts, and music changes should help create momentum between scenes.
+
+### 4. Use Metadata For Timing Logic
+
+Recommended metadata keys:
+
+- `beat_timing`
+- `audio_turns`
+- `title_card_windows`
+- `reframe_notes`
+
+### 5. Quality Gate
+
+- the emotional arc is intact,
+- reveals land clearly,
+- title cards are sparse and timed with intent,
+- strong moments are not buried under coverage.
+
+## Common Pitfalls
+
+- Overcutting emotional material.
+- Using speed ramps or flashy transitions by default.
+- Letting title cards replace editorial clarity.

skills/pipelines/cinematic/executive-producer.md

@@ -0,0 +1,147 @@
+# Executive Producer — Cinematic Pipeline
+
+## When to Use
+
+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.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/cinematic.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: cinematic
+  playbook: <selected>
+  target_duration_seconds: <from brief>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Cinematic-specific
+  emotional_arc: null         # from brief: build → reveal → landing
+  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
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## Execution Protocol
+
+Same as standard EP: Initialize → Execute stages serially (idea → script → scene_plan → assets → edit → compose → publish) → Final QA.
+
+Each stage: PREPARE → SPAWN DIRECTOR → REVIEW → GATE DECISION (pass / revise / send-back).
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Emotional arc definition
+  - Is the emotional arc explicit (build → reveal → landing)?
+  - Is source mode clear (supplied footage vs generated inserts)?
+  - Is the target mood defined and achievable?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Beat escalation
+  - Does the beat map escalate cleanly toward the reveal?
+  - Are dialogue/title cards sparse and purposeful?
+  - Is the landing beat distinct from the build?
+
+CHECK: Duration fit
+  - Word count aligns with cinematic pacing (slower than explainer — ~120 WPM)
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Hero moment definition
+  - Are hero frames (climax, reveal) explicitly identified?
+  - Is source footage prioritized over generated inserts?
+  - Do transitions support mood (not distract)?
+
+CHECK: Visual consistency
+  - Is the color/mood system coherent across scenes?
+  - Are aspect ratio choices consistent (letterbox if used)?
+```
+
+### After ASSETS stage:
+```
+CHECK: Music/ambience alignment
+  - Does the music beat map align with the script beat map?
+  - Are generated inserts limited and justified?
+  - Budget gate: 90% threshold warning
+
+CHECK: Source selects quality
+  - Are source clips properly identified and accessible?
+  - Do support assets (generated or stock) match source quality level?
+```
+
+### After EDIT stage:
+```
+CHECK: Emotional pacing
+  - Strong moments are not overcut
+  - Audio cues reinforce story beats
+  - Title-card timing is restrained
+
+CHECK: Timeline completeness
+  - Full runtime covered, no gaps
+  - All asset references valid
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe: duration, resolution, codec
+  - Color grade applied and consistent
+  - Audio dynamics controlled — dialogue intelligible, music balanced
+  - Letterbox or frame treatment improves (not harms) the output
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Emotional arc, source mode | Revise |
+| G2 | script | Beat escalation, duration | Revise |
+| G3 | scene_plan | Hero moments, visual consistency | Revise |
+| G4 | assets | Music alignment, source quality, budget | Revise |
+| G5 | edit | Emotional pacing, timeline | Revise |
+| G6 | compose | Output probe, color grade, audio dynamics | Revise or send-back |
+| G7 | publish | Metadata, poster frame | Revise |
+| FINAL | all | Mood coherence, audio, visual polish | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $2) |
+| Max total wall-time | 12 minutes |
+
+## Common Pitfalls
+
+- **Over-grading**: Color grade should enhance mood, not make footage look artificial.
+- **Overuse of generated inserts**: Source footage should be primary. Generated content fills gaps, not replaces.
+- **Ignoring audio dynamics**: Cinematic videos live and die by their audio. Music/dialogue balance is critical.
+- **Rushing the reveal**: The climax moment needs breathing room. Don't let pacing compress it.

skills/pipelines/cinematic/idea-director.md

@@ -0,0 +1,79 @@
+# Idea Director - Cinematic Pipeline
+
+## When To Use
+
+Use this pipeline for trailers, brand films, dramatic montages, or mood-led short videos where rhythm, atmosphere, and emotional escalation matter more than direct explanation.
+
+Do not use this pipeline just because the user said "make it look cinematic." If the project is really a screen demo, explainer, or repurposing job, route it there instead.
+
+## Reference Inputs
+
+- `docs/cinematic-best-practices.md`
+- `skills/creative/cinematic.md`
+- `skills/creative/storytelling.md`
+
+## Process
+
+### 1. Classify The Source Reality
+
+Capture the source mode:
+
+- `footage_only`
+- `footage_plus_stills`
+- `still_led`
+- `generated_support`
+- `mixed_montage`
+
+Do not assume stock, generated b-roll, or music exists unless the user has provided it or the environment can actually make it.
+
+### 2. Define The Emotional Arc
+
+Choose the arc in plain language:
+
+- tension -> reveal
+- wonder -> scale
+- intimacy -> payoff
+- urgency -> resolution
+- mystery -> CTA
+
+The brief should tell later stages what the video is trying to make the viewer feel, not just what it is about.
+
+### 3. Pick The Delivery Shape
+
+Common output shapes:
+
+- `teaser`
+- `trailer`
+- `hero_brand_film`
+- `mood_cut`
+- `social_cutdown`
+
+Store longer planning detail in `brief.metadata`.
+
+Recommended metadata keys:
+
+- `source_mode`
+- `delivery_shape`
+- `emotional_arc`
+- `anchor_assets`
+- `music_strategy`
+- `generated_support_level`
+- `aspect_ratio_plan`
+- `rights_constraints`
+
+### 4. Reality Check The Treatment
+
+If the user has weak source media and no generation path, say so. A cinematic result still needs enough visual or audio material to carry mood.
+
+### 5. Quality Gate
+
+- the source truth is explicit,
+- the emotional arc is specific,
+- the output shape fits the available assets,
+- the treatment is cinematic for a reason, not by label only.
+
+## Common Pitfalls
+
+- Calling something cinematic when it is really just a normal edit with black bars.
+- Assuming generated inserts are available without checking tools.
+- Planning a trailer shape with no reveal or payoff.

skills/pipelines/cinematic/publish-director.md

@@ -0,0 +1,56 @@
+# Publish Director - Cinematic Pipeline
+
+## When To Use
+
+Package the cinematic piece and any cutdowns so the hero version stays clear and the distribution intent is obvious.
+
+## Prerequisites
+
+| 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 |
+| Playbook | Active style playbook | Tone and naming consistency |
+
+## Process
+
+### 1. Separate Hero And Derivatives
+
+Typical deliverables:
+
+- hero trailer or brand film,
+- teaser cut,
+- social cutdown,
+- poster-frame or thumbnail concept.
+
+### 2. Match Metadata To Tone
+
+Packaging should reflect the actual mood:
+
+- dramatic,
+- premium,
+- mysterious,
+- reflective,
+- urgent.
+
+### 3. Preserve Editorial Truth
+
+Store in `publish_log.metadata`:
+
+- `hero_output`
+- `derivative_outputs`
+- `poster_frame_notes`
+- `distribution_notes`
+
+### 4. Quality Gate
+
+- hero export is clearly identified,
+- derivative exports are labeled by purpose,
+- metadata fits the tone,
+- the package is usable without manual cleanup.
+
+## Common Pitfalls
+
+- Mixing teaser and hero outputs without clear naming.
+- Writing generic metadata that ignores the mood.
+- Treating all cutdowns as interchangeable.

skills/pipelines/cinematic/scene-director.md

@@ -0,0 +1,63 @@
+# Scene Director - Cinematic Pipeline
+
+## When To Use
+
+You are deciding how each cinematic beat will look and transition. This is where mood becomes a visual plan.
+
+## Prerequisites
+
+| 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 |
+| Tools | `frame_sampler`, `scene_detect` | Source inspection and reframing checks |
+| Playbook | Active style playbook | Color and typography consistency |
+
+## Process
+
+### 1. Make Hero Frames Explicit
+
+Every cinematic piece needs a few memorable frames. Define them directly:
+
+- opening image,
+- reveal image,
+- final image,
+- any title-card hero moments.
+
+### 2. Keep Source-Led Scenes Primary
+
+If source footage exists, let it carry the piece. Generated inserts or text cards should support transitions, emphasis, or missing coverage, not dominate the timeline.
+
+### 3. Limit Transition Vocabulary
+
+Choose a small set:
+
+- hard cut,
+- fade to black,
+- slow dissolve,
+- restrained push or punch-in.
+
+Too many transition types kill the mood.
+
+### 4. Use Metadata For Visual Rules
+
+Recommended metadata keys:
+
+- `hero_frames`
+- `transition_rules`
+- `aspect_ratio_rules`
+- `title_card_rules`
+- `support_insert_rules`
+
+### 5. Quality Gate
+
+- every beat has a scene treatment,
+- hero frames are identifiable,
+- support inserts are justified,
+- the visual language stays consistent across the piece.
+
+## Common Pitfalls
+
+- Using title cards as filler.
+- Treating generated inserts like the primary story without saying so.
+- Planning flashy transitions for every beat.

skills/pipelines/cinematic/script-director.md

@@ -0,0 +1,69 @@
+# Script Director - Cinematic Pipeline
+
+## When To Use
+
+This stage builds the beat map, selected lines, title-card copy, and reveal structure for the cinematic piece. You are shaping rhythm, not writing a dense explainer.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Emotional arc and source truth |
+| Tools | `transcriber`, `scene_detect` | Optional dialogue mining and source review |
+
+## Process
+
+### 1. Build A Beat Map First
+
+Use a simple structure:
+
+- hook,
+- escalation,
+- reveal,
+- landing.
+
+If the piece is longer, add one midpoint turn. Do not let it become essay-shaped.
+
+### 2. Use Dialogue Sparingly
+
+If source speech exists, use `transcriber` to find:
+
+- strong standalone lines,
+- emotional phrases,
+- concise declarations,
+- reveal phrases.
+
+If there is no useful dialogue, keep the script title-led or narration-led and say so in metadata.
+
+### 3. Keep Title Cards Short
+
+Title-card copy should feel trailer-like:
+
+- fewer words,
+- more contrast,
+- more whitespace,
+- more timing precision.
+
+### 4. Store Beat Truth In Metadata
+
+Recommended metadata keys:
+
+- `beat_map`
+- `dialogue_selects`
+- `title_card_copy`
+- `music_turns`
+- `silence_windows`
+
+### 5. Quality Gate
+
+- the beat map escalates cleanly,
+- dialogue and title cards do not explain the same thing twice,
+- the reveal lands distinctly,
+- the landing gives the viewer a final feeling or action.
+
+## Common Pitfalls
+
+- Writing full explanatory paragraphs instead of beats.
+- Using too many title cards.
+- Revealing the best moment too early.

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

@@ -0,0 +1,68 @@
+# Asset Director - Clip Factory Pipeline
+
+## When To Use
+
+This stage builds the shared visual and audio kit for the entire clip batch. The key is reuse, not bespoke design per clip.
+
+## Prerequisites
+
+| 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"]` | Clip plans and rankings |
+| Tools | `subtitle_gen`, `audio_enhance` | Batch-ready subtitles and audio cleanup |
+| Playbook | Active style playbook | Subtitle and overlay consistency |
+
+## Process
+
+### 1. Build Shared Assets First
+
+Prefer reusable assets over per-clip reinvention:
+
+- one subtitle style system,
+- one hook text treatment,
+- one lower-third treatment,
+- one watermark / brand frame,
+- one CTA / end-tag treatment if needed.
+
+### 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.
+
+Store clip-relative timing details in `asset_manifest.metadata.subtitle_map`.
+
+### 3. Normalize Audio Consistently
+
+Use `audio_enhance` across the clip set so the batch feels like one series:
+
+- similar loudness,
+- similar noise floor,
+- similar vocal clarity.
+
+### 4. Keep Hook Assets Lightweight
+
+Most hook overlays should be text-first and template-based. Do not spend time or budget generating bespoke art unless the batch truly benefits.
+
+### 5. Use Metadata For Batch Structure
+
+Recommended metadata keys:
+
+- `shared_assets`
+- `subtitle_map`
+- `audio_profile`
+- `clip_asset_index`
+- `style_tokens`
+
+### 6. Quality Gate
+
+- every clip has subtitles,
+- every clip has a clean audio asset or verified source audio path,
+- shared assets are referenced consistently,
+- the asset count stays practical for the batch size.
+
+## 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.

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

@@ -0,0 +1,61 @@
+# Compose Director - Clip Factory Pipeline
+
+## When To Use
+
+Render each clip and platform variant independently. The important behaviors here are consistency, batch resilience, and clear reporting of partial failures.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Clip edits and assets |
+| Tools | `video_trimmer`, `video_compose`, `audio_mixer`, `color_grade` | Render pipeline |
+| Media profiles | `lib/media_profiles.py` | Platform targets |
+
+## Process
+
+### 1. Treat Each Output As Its Own Job
+
+One clip across three platforms is three render jobs. Name and track them explicitly.
+
+### 2. Reuse What Can Be Shared
+
+- shared audio mix where possible,
+- shared subtitle styling,
+- shared overlay assets,
+- shared grading if the source needs it.
+
+### 3. Fail Softly
+
+If one clip or one platform variant fails:
+
+- log it clearly,
+- continue the rest of the batch,
+- do not block successful exports.
+
+### 4. Verify Every Output
+
+Per render:
+
+- correct duration,
+- correct resolution/aspect ratio,
+- no black opening frame,
+- hook appears on time,
+- subtitles render correctly,
+- audio is present and consistent.
+
+### 5. Use Render Report Metadata
+
+Recommended metadata keys:
+
+- `job_index`
+- `failed_jobs`
+- `shared_intermediates`
+- `platform_groupings`
+
+## Common Pitfalls
+
+- Rendering sequentially without reason when jobs are independent.
+- Treating a failed clip as a reason to stop the batch.
+- Letting one platform variant quietly use the wrong framing or subtitle zone.

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

@@ -0,0 +1,66 @@
+# Edit Director - Clip Factory Pipeline
+
+## When To Use
+
+This stage turns the approved clips into independent mini-edits. Each clip must work alone, but the collection should still feel like a coherent series.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, layouts, transcripts |
+| Playbook | Active style playbook | Transition and subtitle consistency |
+
+## Process
+
+### 1. Build A Shared Edit Template
+
+Lock the batch defaults first:
+
+- subtitle style,
+- hook timing,
+- lower-third timing,
+- watermark behavior,
+- audio fade lengths.
+
+Then apply per-clip overrides only where necessary.
+
+### 2. Optimize The First 2-3 Seconds
+
+For every clip:
+
+- start on motion, face, or result,
+- show hook text immediately if needed,
+- let subtitles begin with the first spoken word,
+- avoid intros that delay the point.
+
+### 3. Keep Boundaries Clean
+
+- no cuts mid-word,
+- no trailing silence after the point lands,
+- no "setup for setup's sake" before the hook,
+- no outro cards unless they earn the time.
+
+### 4. Use Metadata For Multi-Variant Detail
+
+Recommended metadata keys:
+
+- `batch_template`
+- `clip_variants`
+- `hook_windows`
+- `cta_windows`
+
+### 5. Quality Gate
+
+- each clip is self-contained,
+- the first seconds hook fast,
+- overlay stack is readable on mobile,
+- the batch retains consistent styling and fades.
+
+## Common Pitfalls
+
+- Building one highlight reel instead of independent clips.
+- Letting branding delay the hook.
+- Overcrowding the screen with hook text, subtitles, watermark, and lower third simultaneously.
+- Applying inconsistent transition timing across the batch.

skills/pipelines/clip-factory/executive-producer.md

@@ -0,0 +1,136 @@
+# Executive Producer — Clip Factory Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a clip factory project. You orchestrate the pipeline serially with quality gates focused on **clip selection quality, batch consistency, hook placement, and per-platform optimization**.
+
+**No pre-production stages.** Long-form source content exists. The EP manages the extraction of multiple independent short clips, ensuring each stands alone while maintaining series consistency.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/clip-factory.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: clip-factory
+  playbook: <selected>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Clip-factory specific
+  source_type: null            # webinar / stream / presentation / interview
+  clip_count_target: 0
+  platform_targets: []         # per-clip platform assignments
+  clips_completed: 0
+
+  artifacts:
+    idea: null
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Source and targets
+  - Source content type identified?
+  - Clip count target realistic for source duration? (rule of thumb: 1 clip per 5-10 min source)
+  - Platform mix defined?
+  - Clip selection criteria clear?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Transcript and ranking
+  - Full transcription with accurate timestamps?
+  - At least N candidate clips where N >= clip_count_target?
+  - Each candidate is self-contained (standalone test)?
+  - Clips ranked by quality/engagement potential?
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Clip boundaries
+  - Each clip has clean in/out points (no mid-sentence cuts)?
+  - Platform-specific framing planned (vertical vs square vs landscape)?
+  - No clip exceeds platform max duration?
+
+CHECK: Batch diversity
+  - Clips cover different topics/moments from the source?
+  - Not all clips from one section of the source?
+```
+
+### After ASSETS stage:
+```
+CHECK: Batch consistency
+  - Per-clip subtitles with correct time offsets?
+  - Shared branding assets (title cards, hooks) prepared?
+  - Audio normalized consistently across all clips?
+  - Budget gate: 90% threshold warning
+```
+
+### After EDIT stage:
+```
+CHECK: Hook placement
+  - Each clip has its hook within first 2-3 seconds?
+  - Subtitle styling consistent across all clips?
+  - Each edit is independent (no cross-clip dependencies)?
+
+CHECK: Completeness
+  - Edit decisions exist for every planned clip?
+```
+
+### After COMPOSE stage:
+```
+CHECK: Batch render validation
+  - All clips rendered successfully?
+  - Each clip meets target platform specs (resolution, aspect ratio)?
+  - Audio levels consistent across clips?
+  - No clip has rendering artifacts?
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Source assessment, clip targets | Revise |
+| G2 | script | Transcript quality, clip ranking | Revise |
+| G3 | scene_plan | Clip boundaries, batch diversity | Revise |
+| G4 | assets | Batch consistency, audio normalization | Revise |
+| G5 | edit | Hook placement, completeness | Revise |
+| G6 | compose | Batch render probe, platform specs | Revise or send-back |
+| G7 | publish | Per-clip metadata, posting order | Revise |
+| FINAL | all | Clip quality, consistency, hooks | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $1) |
+| Max total wall-time | 12 minutes |
+
+## Common Pitfalls
+
+- **Context-dependent clips**: Each clip must make sense alone. No "as I was saying" openings.
+- **Slow hooks**: Social clips need to hook in 2-3 seconds. Front-load the interesting part.
+- **Inconsistent audio levels**: Clips from different parts of the source have different audio levels. Normalize.
+- **Missing platform optimization**: A YouTube clip and a TikTok clip need different aspect ratios.
+- **All clips from one section**: Diverse clips from across the source perform better than 5 clips from the same 10 minutes.

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

@@ -0,0 +1,98 @@
+# Idea Director - Clip Factory Pipeline
+
+## When To Use
+
+Use this pipeline when the source is long-form footage and the goal is multiple short-form deliverables: webinar clips, interview cuts, livestream highlights, keynote excerpts, or presentation snippets.
+
+You are not planning one video. You are planning a ranked portfolio of clips.
+
+## Reference Inputs
+
+- `docs/clip-factory-best-practices.md`
+- `skills/creative/short-form.md`
+- `skills/creative/video-editing.md`
+
+## Process
+
+### 1. Understand The Source And The Goal
+
+Capture the source shape:
+
+- webinar
+- interview
+- panel
+- keynote
+- stream
+- customer story
+
+Then capture the business goal:
+
+- awareness
+- thought leadership
+- lead generation
+- product education
+- event recap
+
+### 2. Choose A Clip Portfolio Strategy
+
+A good batch mixes clip types instead of extracting the same energy repeatedly.
+
+Common clip families:
+
+- `hook`: surprising claim or strong cold open
+- `insight`: useful takeaway or lesson
+- `story`: narrative moment with emotional shape
+- `proof`: stat, case study, demo result
+- `opinion`: hot take, disagreement, contrarian point
+
+Use the brief metadata to define the intended balance across those families.
+
+### 3. Set Yield Targets Realistically
+
+Guideline ranges:
+
+- `15-30 min`: 3-6 strong clips
+- `30-60 min`: 5-10 strong clips
+- `60+ min`: 8-15 strong clips if the source quality supports it
+
+Do not inflate clip count to satisfy a round number. A smaller strong batch beats a padded weak batch.
+
+### 4. Map Platforms Before Extraction
+
+Plan platform fit early:
+
+- `9:16` for Shorts, Reels, TikTok
+- `1:1` for LinkedIn and safer feed repurposing
+- `16:9` when slides, demos, or wide context matter
+
+If the source framing clearly will not survive vertical crops, say so in the brief metadata now.
+
+### 5. Build The Brief
+
+Keep the schema-level brief concise and put the richer batch plan in `brief.metadata`.
+
+Recommended metadata keys:
+
+- `source_type`
+- `source_duration_seconds`
+- `clip_target_range`
+- `clip_families`
+- `primary_platforms`
+- `secondary_platforms`
+- `selection_criteria`
+- `known_visual_constraints`
+- `distribution_goal`
+
+### 6. Quality Gate
+
+- the clip count target is realistic,
+- the platform mix matches the content,
+- the brief defines ranking criteria before extraction starts,
+- the agent has acknowledged any obvious reframing limits.
+
+## Common Pitfalls
+
+- Planning a batch around quantity before quality.
+- Assuming every source can produce vertical clips cleanly.
+- Treating all clips as interchangeable instead of intentionally varied.
+- Starting extraction without defining what "good" means for this batch.

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

@@ -0,0 +1,60 @@
+# Publish Director - Clip Factory Pipeline
+
+## When To Use
+
+This stage packages the clip batch into a distribution plan. The goal is not just exported files. The goal is a usable content engine.
+
+## Prerequisites
+
+| 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"]` | Outputs, rankings, and goals |
+| Playbook | Active style playbook | Brand voice |
+
+## Process
+
+### 1. Lead With The Strongest Clip
+
+Do not schedule by chronology. Schedule by ranking.
+
+The first published clip should usually be:
+
+- the strongest hook,
+- the cleanest standalone clip,
+- the clip most aligned with the batch goal.
+
+### 2. Tailor Copy By Platform
+
+Each platform needs its own tone and packaging:
+
+- TikTok / Reels: direct, fast, hook-led
+- Shorts: searchable, keyword-aware
+- LinkedIn: insight-led and more professional
+- X: short, punchy, opinion-friendly
+
+### 3. Package The Batch Cleanly
+
+Group by platform and include ready-to-paste text assets, not just video files.
+
+### 4. Preserve Batch Truth
+
+Store in `publish_log.metadata`:
+
+- `clip_catalog`
+- `posting_order`
+- `platform_copy_map`
+- `schedule_notes`
+
+### 5. Quality Gate
+
+- strongest clips lead the rollout,
+- captions are platform-specific,
+- export folders are usable without extra cleanup,
+- the batch catalog clearly links ranking, file paths, and publishing intent.
+
+## Common Pitfalls
+
+- Publishing the whole batch on the same day.
+- Using one caption everywhere.
+- Losing the rank/order logic after rendering is complete.

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

@@ -0,0 +1,76 @@
+# Scene Director - Clip Factory Pipeline
+
+## When To Use
+
+You are planning how each selected clip will be framed and packaged for its destination platform. This is where clip viability gets proven or disproven.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Selected clips and platform goals |
+| Tools | `frame_sampler`, `scene_detect` | Visual checks and boundary inspection |
+| Playbook | Active style playbook | Layout language and safe zones |
+
+## Process
+
+### 1. Choose The Right Frame For Each Clip
+
+Do not default every clip to `9:16`.
+
+Use:
+
+- `9:16` when a face-first crop works,
+- `1:1` when speaker plus context both matter,
+- `16:9` when slides, demos, or multi-speaker width are essential.
+
+OpenMontage does not yet have first-class auto-reframe. If a vertical crop is weak, plan a safer aspect ratio instead of pretending the crop will work.
+
+### 2. Plan First-Second Composition
+
+For each clip, define:
+
+- what the viewer sees on frame 1,
+- where hook text can safely appear,
+- where subtitles can live,
+- whether the speaker needs a punch-in or whether the original framing is already good.
+
+### 3. Standardize The Batch
+
+Use the scene plan to lock series consistency:
+
+- same top hook zone,
+- same subtitle zone,
+- same watermark / brand area,
+- same lower-third logic.
+
+### 4. Store Reframe Detail In Metadata
+
+The schema is generic, so store richer layout notes in `scene_plan.metadata`.
+
+Recommended metadata keys:
+
+- `clip_layouts`
+- `safe_zones`
+- `crop_variants`
+- `speaker_positions`
+- `platform_variants`
+
+### 5. Use Scenes To Represent Deliverables
+
+Each scene should map to one clip variant or one clip family deliverable. Keep `description` human-readable and use `required_assets` for hook overlays, lower thirds, or branded frames.
+
+### 6. Quality Gate
+
+- every clip has a platform-aware framing plan,
+- hook and subtitle zones do not collide,
+- weak vertical crops are downgraded honestly,
+- the batch will feel visually consistent when rendered together.
+
+## Common Pitfalls
+
+- Center-cropping a wide shot and calling it vertical optimization.
+- Ignoring slide or screen-share content while focusing only on faces.
+- Letting each clip invent its own layout.
+- Forgetting that the first frame determines whether a viewer keeps watching.

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

@@ -0,0 +1,90 @@
+# Script Director - Clip Factory Pipeline
+
+## When To Use
+
+This stage converts the long-form source into a ranked candidate list and then into the final clip selections. You are mining for standout moments, not summarizing the entire source.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Batch goals and platform targets |
+| Tools | `transcriber`, `scene_detect` | Transcript-first selection and visual checks |
+
+## Process
+
+### 1. Transcribe The Full Source
+
+Use `transcriber` first. The transcript is the search surface for hooks, not an afterthought.
+
+Use `scene_detect` only to sanity-check visual boundaries, speaker changes, or slide changes near promising moments.
+
+### 2. Score Candidate Moments
+
+Use the brief's ranking criteria and evaluate each moment on:
+
+- `hook`
+- `coherence`
+- `value`
+- `energy`
+- `platform_fit`
+
+This mirrors the way modern clipping products talk about virality and clip quality, while keeping the judgment transparent.
+
+### 3. Apply The Standalone Test
+
+Every approved clip must make sense to a cold viewer.
+
+Reject or widen clips that contain:
+
+- unresolved pronouns,
+- references to earlier context,
+- long lead-ins before the point lands,
+- endings that stop before the payoff.
+
+### 4. Select The Final Batch
+
+Pick the smallest set that best satisfies the batch goal.
+
+Maintain diversity across:
+
+- source sections,
+- speakers,
+- clip families,
+- energy levels.
+
+### 5. Use Metadata For Ranking Truth
+
+The script schema is small, so store the richer batch analysis in `script.metadata`.
+
+Recommended metadata keys:
+
+- `candidate_clips`
+- `selected_clip_ids`
+- `ranking_model`
+- `rejected_candidates`
+- `source_coverage_map`
+- `platform_assignments`
+
+Each candidate should record:
+
+- source in/out,
+- hook text,
+- reason selected or rejected,
+- scoring dimensions,
+- likely crop viability.
+
+### 6. Quality Gate
+
+- the top-ranked clips are genuinely the strongest, not just the earliest found,
+- every selected clip passes the standalone test,
+- the set covers the source deliberately instead of clustering in one section,
+- low-quality candidates are rejected honestly.
+
+## Common Pitfalls
+
+- Trusting first-pass candidate timestamps without transcript-level review.
+- Selecting too many calm, same-energy clips.
+- Preserving chronological order instead of ranking by quality.
+- Treating transcript quality issues as minor when they affect selection accuracy.

skills/pipelines/explainer/asset-director.md

@@ -0,0 +1,192 @@
+# Asset Director — Explainer Pipeline
+
+## When to Use
+
+You are the Asset Producer for a generated explainer video. You have a `scene_plan` with required assets and a `script` with narration text. Your job is to generate every asset needed: narration audio, images, diagrams, code snippets, and background music. Every file must exist on disk before you finish.
+
+This is where plans become real files. A missing or low-quality asset will torpedo the final video.
+
+## Prerequisites
+
+| 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 |
+| 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 |
+
+## Process
+
+### Step 1: Inventory Required Assets
+
+Walk every scene in the scene plan. For each `required_assets` entry, create an asset task:
+
+```
+Asset Task:
+  scene_id: scene-3
+  type: diagram
+  description: "Mermaid flowchart: query -> encode -> search -> rank -> return"
+  source: generate
+  tool: diagram_gen
+  estimated_cost: $0.00
+```
+
+Also create tasks for:
+- **Narration audio** — one per script section (use `tts_selector` or a concrete TTS provider)
+- **Background music** — one track for the whole video (use `music_gen` or select from library)
+- **Sound effects** — per playbook's `sfx_style` (optional, use `music_gen` or stock)
+
+### Step 2: Check Budget
+
+Before generating anything:
+1. Sum all estimated costs from the asset tasks
+2. Compare against the cost tracker's remaining budget
+3. If over budget:
+  - Switch expensive tools to cheaper alternatives (use `tts_selector` with `preferred_provider` to route to cheaper TTS; use `image_selector` to route to cheaper image providers)
+   - Reduce image count (combine similar scenes)
+   - Skip optional assets (SFX, B-roll)
+4. Get cost approval via cost tracker before proceeding
+
+### Step 2b: Sample Preview (Prevents Wasted Spend)
+
+Before batch-generating assets, produce one sample of each expensive asset type and present them to the user for approval:
+
+1. **TTS sample**: Generate narration for the first script section only. Play it for the user. Confirm voice, pace, and tone are acceptable before generating the rest.
+2. **Image sample**: Generate one image for the most representative scene. Show it to the user. Confirm the style, quality, and prompt approach before batch-generating all images.
+3. **Music sample** (if using `music_gen`): Generate one short clip. Confirm mood and energy before committing.
+
+If the user rejects a sample:
+- Adjust the parameters (voice, prompt style, provider) and regenerate the sample.
+- Do not batch-generate until the sample is approved.
+- Max 3 sample iterations per asset type before escalating to the user for a decision.
+
+This step typically costs $0.03–0.08 total and prevents $1–3 of wasted generation.
+
+### Step 3: Generate Narration
+
+For each script section:
+1. Extract the narration text
+2. Apply speaker directions from the script (pace, emphasis, emotion)
+3. Apply the playbook's `audio.voice_style`
+4. Generate using `tts_selector` — it auto-routes to the best available TTS provider based on user preference and availability. Check the registry's `best_for` fields to understand each provider's strengths.
+5. Verify the audio file exists and duration matches expected timing (±15%)
+
+**Pronunciation guide**: If the script contains technical terms, jargon, or names with non-obvious pronunciation, include a pronunciation map in the TTS request.
+
+### Step 4: Generate Visual Assets
+
+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
+2. Add negative prompt from playbook
+3. Include consistency anchors (same palette, same style across all images)
+4. Generate and verify the file exists
+5. If the result doesn't match expectations, refine the prompt and regenerate (max 2 retries)
+
+**Diagrams (`diagram_gen`)**:
+1. Convert the scene description into valid Mermaid syntax
+2. Apply playbook's `asset_generation.diagram_style`
+3. Generate SVG/PNG
+4. Verify all nodes and edges are present
+
+**Code snippets (`code_snippet`)**:
+1. Extract language and code from the scene description
+2. Apply syntax highlighting theme from playbook's overlay styles
+3. Generate highlighted image or Remotion-compatible data
+
+### Step 5: Generate Music
+
+1. Read playbook's `audio.music_mood` and `audio.music_volume`
+2. Generate or select a background track:
+   - **Primary**: `music_gen` (ElevenLabs Music) — custom, costs per generation
+   - **Fallback**: Stock music library (if available)
+3. Duration should match total video duration (or be loopable)
+4. Verify the audio file exists
+
+### Step 6: Build Asset Manifest
+
+Assemble all generated assets into the manifest:
+
+```json
+{
+  "version": "1.0",
+  "assets": [
+    {
+      "id": "narration-s1",
+      "type": "audio",
+      "subtype": "narration",
+      "path": "assets/narration/s1.mp3",
+      "source_tool": "tts_selector",
+      "scene_id": "scene-1",
+      "duration_seconds": 8.2,
+      "cost_usd": 0.003
+    },
+    {
+      "id": "img-scene-3",
+      "type": "image",
+      "path": "assets/images/scene-3-diagram.png",
+      "source_tool": "diagram_gen",
+      "scene_id": "scene-3",
+      "cost_usd": 0.00
+    },
+    {
+      "id": "music-bg",
+      "type": "audio",
+      "subtype": "music",
+      "path": "assets/music/background.mp3",
+      "source_tool": "music_gen",
+      "duration_seconds": 62,
+      "cost_usd": 0.05
+    }
+  ],
+  "total_cost_usd": 0.053,
+  "generation_summary": {
+    "narration_sections": 5,
+    "images_generated": 8,
+    "diagrams_generated": 2,
+    "music_tracks": 1
+  }
+}
+```
+
+### Step 7: Verify All Assets
+
+**Existence check:**
+- [ ] Every asset `path` exists on disk
+- [ ] Every narration section has a corresponding audio file
+- [ ] Every scene with `required_assets` has all assets generated
+- [ ] Background music file exists
+
+**Quality check:**
+- [ ] Narration durations within ±15% of expected timing
+- [ ] Images match the playbook's style (review consistency anchors)
+- [ ] Diagrams are legible and complete
+- [ ] Total cost within budget
+
+### Step 8: Self-Evaluate
+
+Score (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **Completeness** | Does every scene have all required assets? |
+| **Audio quality** | Does narration sound natural with correct pacing? |
+| **Visual consistency** | Do all images look like they belong to the same video? |
+| **Budget adherence** | Is total cost within the approved budget? |
+| **Playbook fidelity** | Do assets match the playbook's style guide? |
+
+If any dimension scores below 3, fix before proceeding.
+
+### Step 9: Submit
+
+Validate the asset_manifest against the schema and persist via checkpoint.
+
+## 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.
+- **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/compose-director.md

@@ -0,0 +1,170 @@
+# Compose Director — Explainer Pipeline
+
+## When to Use
+
+You are the Compositor for a generated explainer video. You have `edit_decisions` with the complete edit timeline and an `asset_manifest` with all file paths. Your job is to render the final video: assemble visuals, layer audio, burn subtitles, and encode to the target format.
+
+This is the last technical stage before the video exists as a playable file. Everything converges here.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | What to render |
+| Playbook | Active style playbook | Quality targets |
+| Tools | `video_compose`, `audio_mixer` | Rendering capabilities |
+| Media profiles | `lib/media_profiles.py` | Output format specs (resolution, codec, bitrate) |
+
+## Process
+
+### Step 1: Choose Render Strategy
+
+Based on the edit decisions, pick the rendering approach:
+
+**FFmpeg pipeline** (simpler videos):
+- Static images with Ken Burns
+- Audio layering
+- Subtitle burn-in
+- Best for: diagram-heavy, image-based explainers
+
+**Remotion render** (motion-heavy videos):
+- Animated text cards, stat cards
+- Complex transitions (morph, zoom)
+- Programmatic motion graphics
+- Best for: flat-motion-graphics playbook, animation-heavy plans
+
+You can combine both: Remotion for animated segments, FFmpeg for final assembly.
+
+### Step 2: Prepare Render Inputs
+
+For each cut in the edit decisions:
+1. Verify the source asset exists at its declared path
+2. Check asset dimensions/duration match expectations
+3. Prepare transform parameters (scale, position, crop)
+
+For audio:
+1. Verify all narration segments exist
+2. Verify music track exists
+3. Prepare ducking parameters from edit decisions
+
+### Step 3: Determine Output Profile
+
+Read the target platform from the brief artifact. Map to a media profile:
+
+| Platform | Profile | Resolution | Notes |
+|----------|---------|-----------|-------|
+| YouTube | `youtube_landscape` | 1920x1080 | Default for most explainers |
+| TikTok/Reels | `tiktok` | 1080x1920 | Vertical, needs reframing |
+| Twitter/X | `twitter_landscape` | 1280x720 | Shorter format |
+| LinkedIn | `linkedin` | 1920x1080 | Professional context |
+
+Get the exact encoding parameters via `ffmpeg_output_args(get_profile(name))`.
+
+### Step 4: Render Video
+
+Call the `video_compose` tool with:
+```
+{
+  "operation": "render",
+  "edit_decisions": <edit_decisions artifact>,
+  "asset_manifest": <asset_manifest artifact>,
+  "output_profile": "youtube_landscape",
+  "output_path": "renders/output.mp4",
+  "options": {
+    "subtitle_burn": true,
+    "audio_normalize": true,
+    "two_pass_encode": true
+  }
+}
+```
+
+If using Remotion for animated segments:
+1. Generate Remotion composition data from edit decisions
+2. Call `video_compose` with `operation: "remotion_render"` for animated segments
+3. Assemble Remotion outputs with remaining segments via FFmpeg
+
+### Step 5: Audio Post-Processing
+
+Call the `audio_mixer` tool to:
+1. Layer narration segments in order
+2. Mix background music at playbook volume
+3. Apply ducking (music dips during narration)
+4. Normalize overall audio levels
+5. Output the final mixed audio track
+
+The video_compose tool will mux this with the video.
+
+### Step 6: Verify Output
+
+**File verification:**
+- [ ] Output file exists at declared path
+- [ ] File size is reasonable (not 0 bytes, not suspiciously small)
+- [ ] File is a valid container (ffprobe succeeds)
+
+**Content verification:**
+- [ ] Duration within ±5% of target
+- [ ] Resolution matches selected profile
+- [ ] Audio channels present (stereo)
+- [ ] No audio clipping or silence gaps > 1s
+
+**Quality check:**
+- [ ] Visual: scrub through at 25%, 50%, 75% marks — images display correctly
+- [ ] Audio: narration is audible and clear throughout
+- [ ] Subtitles: visible and correctly timed
+
+### Step 7: Build Render Report
+
+```json
+{
+  "version": "1.0",
+  "outputs": [
+    {
+      "path": "renders/output.mp4",
+      "format": "mp4",
+      "codec": "h264",
+      "resolution": "1920x1080",
+      "fps": 30,
+      "duration_seconds": 62.4,
+      "file_size_mb": 45.2,
+      "audio_codec": "aac",
+      "audio_channels": 2,
+      "render_strategy": "ffmpeg",
+      "render_time_seconds": 180
+    }
+  ],
+  "render_summary": {
+    "total_cuts_rendered": 12,
+    "subtitles_burned": true,
+    "audio_tracks_mixed": 3,
+    "target_duration_seconds": 60,
+    "actual_duration_seconds": 62.4
+  }
+}
+```
+
+### Step 8: Self-Evaluate
+
+Score (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **Playability** | Does the video play without errors in a standard player? |
+| **Duration accuracy** | Is actual duration within ±5% of target? |
+| **Audio quality** | Is narration clear, music balanced, no clipping? |
+| **Visual quality** | Are images sharp, transitions smooth, no artifacts? |
+| **Subtitle accuracy** | Are subtitles present, readable, and synced? |
+
+If any dimension scores below 3, investigate and re-render.
+
+### Step 9: Submit
+
+Validate the render_report against the schema and persist via checkpoint.
+
+## Common Pitfalls
+
+- **Missing asset files**: Always verify every referenced file exists before starting the render. A missing file mid-render wastes time.
+- **Audio sync drift**: Accumulated timing errors across narration segments cause audio-visual desync. Use absolute timestamps, not relative offsets.
+- **Subtitle encoding**: Burn subtitles into the video (hardcoded) for maximum compatibility. Don't rely on soft subtitles for social media.
+- **Single-pass encode**: Two-pass encoding produces better quality at the same file size. Worth the extra render time.
+- **Ignoring media profile**: YouTube and TikTok have very different requirements. Always check the target profile.

skills/pipelines/explainer/edit-director.md

@@ -0,0 +1,170 @@
+# Edit Director — Explainer Pipeline
+
+## When to Use
+
+You are the Editor for a generated explainer video. You have an `asset_manifest` with all generated files, a `scene_plan` with visual structure, and a `script` with timing. Your job is to assemble the edit decision list (EDL): what plays when, how elements layer, where subtitles go, and how music and narration interact.
+
+This is where raw assets become a coherent video. Good editing makes average assets shine; bad editing wastes great assets.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, visual plan, timing |
+| Playbook | Active style playbook | Transitions, pacing rules, overlay styles |
+
+## Process
+
+### Step 1: Map Assets to Timeline
+
+For each scene in the scene plan:
+1. Find the matching assets from the asset manifest (by `scene_id`)
+2. Find the matching narration audio (by script section)
+3. Note the scene's timing (`start_seconds`, `end_seconds`)
+
+Build a timeline map:
+```
+0s-10s: scene-1 (talking_head) | narration-s1 | img-intro.png
+10s-18s: scene-2 (diagram) | narration-s2 | diagram-flow.svg
+18s-22s: scene-3 (text_card) | narration-s3 | [text overlay]
+...
+```
+
+### Step 2: Define Cuts
+
+Each cut defines what visual is shown and when:
+
+```json
+{
+  "id": "cut-1",
+  "source": "img-scene-1",
+  "in_seconds": 0,
+  "out_seconds": 10,
+  "layer": "primary",
+  "transform": {
+    "scale": 1.0,
+    "position": "center",
+    "animation": "ken-burns-slow-zoom"
+  },
+  "transition_in": "fade",
+  "transition_out": "dissolve",
+  "transition_duration": 0.4
+}
+```
+
+**Layering rules:**
+- `primary` — main visual (one at a time)
+- `overlay` — text cards, stat cards, key terms (on top of primary)
+- `background` — solid color or texture behind everything
+
+### Step 3: Configure Subtitles
+
+Subtitles are mandatory for all explainer content:
+
+```json
+{
+  "subtitles": {
+    "enabled": true,
+    "style": "word-by-word",
+    "font": "Inter",
+    "font_size": 48,
+    "color": "#FFFFFF",
+    "background": "#00000088",
+    "position": "bottom-center",
+    "max_words_per_line": 8
+  }
+}
+```
+
+**Subtitle timing**: Derive from narration audio timestamps. Each word should highlight as it's spoken (word-by-word style) or display in phrase chunks (phrase style).
+
+Use the playbook's typography for font choices.
+
+### Step 4: Configure Audio Layers
+
+```json
+{
+  "audio": {
+    "narration": {
+      "segments": [
+        { "asset_id": "narration-s1", "start_seconds": 0 },
+        { "asset_id": "narration-s2", "start_seconds": 10 }
+      ]
+    },
+    "music": {
+      "asset_id": "music-bg",
+      "volume": 0.08,
+      "fade_in_seconds": 2,
+      "fade_out_seconds": 3,
+      "ducking": {
+        "enabled": true,
+        "threshold_db": -3,
+        "reduction_db": -8,
+        "attack_ms": 200,
+        "release_ms": 500
+      }
+    },
+    "sfx": []
+  }
+}
+```
+
+**Music ducking**: Music volume drops when narration plays, rises during pauses. Use playbook's `audio.ducking_threshold_db`.
+
+### Step 5: Apply Pacing Rules
+
+Check the playbook's `motion.pacing_rules`:
+- No cut shorter than `min_scene_hold_seconds`
+- No cut longer than `max_scene_hold_seconds`
+- Text cards hold for `text_card_hold_seconds`
+- Transitions use `transition_duration_seconds`
+
+Adjust cut timing if any violates these rules.
+
+### Step 6: Verify Edit Completeness
+
+**Timeline coverage:**
+- [ ] Cuts span full video duration (no black frames)
+- [ ] No overlapping primary cuts
+- [ ] Every scene in scene_plan has at least one corresponding cut
+
+**Asset references:**
+- [ ] Every cut's `source` references a valid asset_id from the manifest
+- [ ] Every narration segment references a valid audio asset
+- [ ] Music asset exists
+
+**Audio sync:**
+- [ ] Narration segments are ordered and non-overlapping
+- [ ] Narration timing aligns with corresponding visual cuts
+- [ ] Music ducking is configured
+
+**Subtitles:**
+- [ ] Subtitles enabled
+- [ ] Subtitle style uses playbook-compatible fonts and colors
+
+### Step 7: Self-Evaluate
+
+Score (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **Continuity** | Does every second of the video have a visual? |
+| **Pacing** | Do cuts follow the playbook's timing rules? |
+| **Audio-visual sync** | Does what you see match what you hear at every moment? |
+| **Subtitle quality** | Are subtitles readable and correctly timed? |
+| **Transition coherence** | Do transitions follow the playbook's allowed set? |
+
+If any dimension scores below 3, revise.
+
+### Step 8: Submit
+
+Validate the edit_decisions artifact against the schema and persist via checkpoint.
+
+## Common Pitfalls
+
+- **Forgetting gaps**: If scene-1 ends at 10s and scene-2 starts at 10.5s, there's a 0.5s black frame. Check for gaps.
+- **Audio drift**: Narration audio may be slightly longer/shorter than planned. Adjust visual cuts to match actual narration durations, not planned durations.
+- **No ducking**: Music playing at full volume under narration makes the video unwatchable. Always configure ducking.
+- **Same transition everywhere**: Varying transitions creates rhythm. Use the playbook's allowed set, but don't use the same one for every cut.
+- **Subtitle font mismatch**: Subtitles should use the playbook's body font, not a random default.

skills/pipelines/explainer/executive-producer.md

@@ -0,0 +1,423 @@
+# Executive Producer — Explainer Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a generated explainer video. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision. You are the stateful brain; the directors are stateless workers.
+
+**You replace the default parallel/sequential execution model.** Instead of running all stages blindly, you exercise judgment at every gate.
+
+## Why This Exists
+
+The parallel pipeline produces "technically correct" but low-quality videos because:
+- No feedback loop when TTS narration is too long for the video duration
+- No style consistency enforcement across image generation calls
+- No A/V sync validation before the final render
+- No budget reallocation when early stages overspend
+- No ability to send a single stage back without re-running everything
+
+The EP solves all of these by maintaining cumulative state and applying judgment at each gate.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/animated-explainer.yaml` | Stage definitions, review focus, success criteria |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution knowledge |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+| Tools | Full tool registry | Available capabilities |
+
+## Cumulative State
+
+The EP maintains a running state object that flows through the entire pipeline:
+
+```
+EP_STATE:
+  pipeline: animated-explainer
+  playbook: <selected playbook name>
+  target_duration_seconds: <from proposal_packet.selected_concept>
+  budget_total_usd: <from proposal_packet.approval.approved_budget_usd or configured limit>
+  budget_spent_usd: 0.0
+  budget_remaining_usd: <budget_total>
+
+  # Accumulated from each stage (8 stages)
+  artifacts:
+    research: null      # → research_brief
+    proposal: null      # → proposal_packet (includes approval gate)
+    script: null        # → script
+    scene_plan: null    # → scene_plan
+    assets: null        # → asset_manifest
+    edit: null          # → edit_decisions
+    compose: null       # → render_report
+    publish: null       # → publish_log
+
+  # Pre-production context (carried forward from research + proposal)
+  research_brief: null         # full research_brief artifact — available to all downstream stages
+  selected_concept: null       # the approved concept from proposal_packet
+  production_plan: null        # the approved tool/provider plan
+  approved_budget_usd: null    # explicit user-approved spend cap
+
+  # Cross-stage tracking
+  narration_durations: {}    # section_id → actual_seconds
+  total_narration_seconds: 0
+  total_visual_seconds: 0
+  style_anchors: {}          # consistency tokens carried forward
+  revision_counts: {}        # stage_name → number of revisions
+  issues_log: []             # all issues found, with resolution status
+```
+
+## Execution Protocol
+
+### Phase 0: Initialize
+
+1. Load the pipeline manifest (`animated-explainer.yaml`)
+2. Load the playbook (from user selection or default)
+3. Set budget from configuration or user input (default: $2.00)
+4. Initialize EP_STATE
+
+### Phase 1: Execute Stages Serially
+
+For each stage in order: `research → proposal → script → scene_plan → assets → edit → compose → publish`
+
+**Pre-production stages (research, proposal)** run before any money is spent:
+- **research** gathers raw data via web search — zero cost, no tools
+- **proposal** presents concepts and costs to the user — zero cost, but contains the **approval gate**
+- The pipeline MUST NOT proceed past proposal without `approval.status == "approved"` or `"approved_with_changes"`
+
+After proposal approval, extract and store in EP_STATE:
+- `selected_concept` from `proposal_packet.selected_concept` (drives script, scene, visual decisions)
+- `production_plan` from `proposal_packet.production_plan` (drives tool selection in assets stage)
+- `approved_budget_usd` from `proposal_packet.approval.approved_budget_usd` (overrides default budget)
+- `playbook` from `proposal_packet.selected_concept → concept_options[selected].suggested_playbook`
+
+```
+EXECUTE_STAGE(stage_name):
+
+  1. PREPARE
+     - Load the director skill for this stage
+     - Inject EP_STATE as context (prior artifacts, budget remaining, style anchors)
+     - Inject any EP feedback from previous revision attempts
+
+  2. SPAWN DIRECTOR
+     - The director executes its full process (as defined in its skill MD)
+     - Director produces an artifact
+
+  3. REVIEW (EP performs this, not a separate reviewer)
+     - Schema validation against artifact schema
+     - Check review_focus items from pipeline manifest
+     - Check success_criteria from pipeline manifest
+     - Cross-check against playbook constraints
+     - Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
+
+  4. GATE DECISION
+     If PASS:
+       - Store artifact in EP_STATE
+       - Update cumulative tracking (budget, durations, etc.)
+       - Log: "[stage] PASSED — moving to next stage"
+       - Continue to next stage
+
+     If REVISE:
+       - Increment revision_counts[stage_name]
+       - If revision_counts[stage_name] >= 3:
+           - PASS WITH WARNINGS (never block forever)
+           - Log unresolved issues
+       - Else:
+           - Compose specific feedback for the director
+           - Re-run SPAWN DIRECTOR with feedback injected
+           - Re-run REVIEW
+
+     If SEND_BACK(target_stage):
+       - This is the EP's special power: send work BACK to a prior stage
+       - Only used when a downstream discovery invalidates upstream work
+       - Example: TTS returns 16s audio for a scene planned at 10s
+         → Send back to script director: "Rewrite section 3. Max 25 words."
+       - Re-execute from target_stage forward (artifacts after target are invalidated)
+       - Max 1 send-back per stage pair (prevent infinite loops)
+```
+
+### Phase 2: Final Quality Assurance
+
+After all 7 stages complete, the EP performs a holistic review:
+
+```
+FINAL_QA:
+  1. PROBE the output video:
+     - Duration: within ±5% of target?
+     - Resolution: matches media profile?
+     - Audio: narration audible throughout? Music balanced?
+     - File: valid container, reasonable size?
+
+  2. A/V SYNC CHECK:
+     - Compare narration timestamps to visual cut points
+     - Flag any section where narration plays over the wrong visual
+     - Tolerance: ±0.5 seconds
+
+  3. STYLE CONSISTENCY:
+     - Review all generated images: do they look like the same video?
+     - Check color palette adherence
+     - Check typography consistency
+
+  4. BUDGET RECONCILIATION:
+     - Total actual spend vs. budget
+     - Log per-stage cost breakdown
+
+  5. DECISION:
+     If all checks pass → APPROVE for publish stage
+     If issues found → Send back to the specific stage(s) that can fix them
+       - Audio issues → compose director
+       - Visual issues → asset director (regenerate) or scene director (replan)
+       - Duration issues → script director (rewrite)
+       - Sync issues → edit director (re-cut)
+```
+
+## EP-Specific Cross-Stage Checks
+
+These checks use information accumulated across stages — something no individual director can do.
+
+### After RESEARCH stage:
+```
+CHECK: Research depth
+  - At least 3 data_points with source URLs?
+  - At least 3 angles_discovered with grounded_in references?
+  - At least 5 sources cited?
+  - If any minimum not met: REVISE research
+  - Note: Do NOT checkpoint with user — research is informational, not a decision point
+```
+
+### After PROPOSAL stage:
+```
+CHECK: Approval gate (CRITICAL — the entire point of pre-production)
+  - Is approval.status == "approved" or "approved_with_changes"?
+  - If "pending" or "rejected": STOP. Present to user and wait.
+  - If "approved_with_changes": apply modifications to selected_concept before proceeding
+  - Extract: target_duration_seconds, playbook, budget, tool selections
+  - Initialize budget from approved_budget_usd (not default)
+
+CHECK: Production feasibility
+  - Does the production plan reference tools that are actually available?
+  - Cross-check production_plan.stages[].tools[].available against registry
+  - If any required tool is unavailable: alert user, offer alternatives
+```
+
+### After SCRIPT stage:
+```
+CHECK: Word count vs. duration target
+  - Calculate: total_words / 150 = estimated_minutes (at 150 WPM speaking rate)
+  - If estimated_minutes > target_duration * 1.15:
+      REVISE script: "Script is {X} words. At 150 WPM, that's {Y} minutes.
+      Target is {Z} minutes. Cut {N} words."
+  - If estimated_minutes < target_duration * 0.7:
+      REVISE script: "Script is too short. Add {N} words of content."
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Total scene duration covers full script
+  - Sum all scene durations
+  - Compare to script's total duration
+  - If gaps > 1 second: REVISE scene_plan
+  - If overlaps: REVISE scene_plan
+
+CHECK: Visual variety
+  - Count consecutive same-type scenes
+  - If > 3 consecutive: REVISE scene_plan
+
+CHECK: Asset feasibility
+  - For each required_asset, verify the tool exists in registry
+  - If any asset requires a tool that's unavailable:
+      REVISE scene_plan: "Tool {X} is unavailable. Use {alternative} instead."
+```
+
+### After ASSETS stage:
+```
+CHECK: Narration duration feedback loop (CRITICAL)
+  - For each TTS audio file, probe actual duration
+  - Store in EP_STATE.narration_durations
+  - For each section:
+      If actual_duration > planned_duration * 1.15:
+        Option A: SEND_BACK to script director:
+          "Section {id} narration is {X}s but scene is {Y}s.
+           Rewrite to max {N} words."
+        Option B (if within 25% over): Adjust scene_plan durations to fit
+  - Update EP_STATE.total_narration_seconds
+
+CHECK: Budget gate
+  - If budget_spent > budget_total * 0.9 and stages remain:
+      Alert: "90% budget consumed with {N} stages remaining"
+      Adjust remaining stages to use free/cheap alternatives
+
+CHECK: Style consistency
+  - Compare image descriptions/styles across all generated images
+  - Store style_anchors for downstream use
+```
+
+### After EDIT stage:
+```
+CHECK: Timeline completeness
+  - Verify edit decisions cover 0 to total_duration with no gaps
+  - Verify all asset references point to existing files
+  - Verify audio ducking is configured for all narration segments
+
+CHECK: A/V sync pre-validation
+  - For each cut: narration_start aligns with visual_start (±0.5s)
+  - For each scene: narration_duration ≤ visual_duration
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe the output: duration, resolution, codec, audio channels
+  - If duration drift > 5%: investigate which stage caused it
+  - If audio missing: check audio_mixer configuration
+  - If resolution wrong: check media profile selection
+```
+
+## Feedback Message Templates
+
+When sending work back to a director, use these structured feedback messages:
+
+### To Script Director:
+```
+EP FEEDBACK — Script Revision Required
+Reason: {reason}
+Specific issue: {detail}
+Constraint: {word_count_limit / duration_target / etc.}
+Keep: {what was good about the current script}
+Change: {what specifically needs to change}
+```
+
+### To Scene Director:
+```
+EP FEEDBACK — Scene Plan Revision Required
+Reason: {reason}
+Affected scenes: {scene_ids}
+Constraint: {feasibility / variety / duration / etc.}
+Available tools: {current tool registry status}
+```
+
+### To Asset Director:
+```
+EP FEEDBACK — Asset Regeneration Required
+Reason: {reason}
+Affected assets: {asset_ids}
+Style anchors: {consistency requirements from prior successful assets}
+Budget remaining: ${remaining}
+```
+
+### To Compose Director:
+```
+EP FEEDBACK — Re-render Required
+Reason: {reason}
+Specific issue: {audio_sync / duration / quality / etc.}
+Expected: {what the output should be}
+Actual: {what was produced}
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | research | Data depth, source quality, angle diversity | Revise research |
+| G2 | proposal | Concept quality, cost accuracy, user approval | Revise proposal OR wait for user |
+| G3 | script | Word count vs duration, narrative arc, research integration | Revise script |
+| G4 | scene_plan | Coverage, variety, feasibility against production plan | Revise scene_plan |
+| G5 | assets | File existence, narration duration, budget, style | Revise assets OR send-back to script |
+| G6 | edit | Timeline completeness, A/V pre-sync | Revise edit |
+| G7 | compose | Output probe, duration, audio quality | Revise compose OR send-back to edit/assets |
+| G8 | publish | Metadata, packaging | Revise publish |
+| FINAL | all | Holistic video review | Send-back to specific stage |
+
+## Execution Limits (Anti-Loop Protection)
+
+| Limit | Value | Rationale |
+|-------|-------|-----------|
+| Max revisions per stage | 3 | Prevent perfectionism loops |
+| Max send-backs per stage pair | 1 | Prevent ping-pong between stages |
+| Max total send-backs | 3 | Cap total pipeline re-work |
+| Max total budget | Configurable (default $2) | Hard stop on spending |
+| Max total wall-time | 15 minutes | Timeout for entire pipeline |
+
+After any limit is hit: **proceed with warnings**, never block indefinitely.
+
+## Integration with Existing Skills
+
+The EP doesn't replace any director skill — it wraps them. Each director skill continues to work exactly as documented. The EP adds:
+
+1. **Context injection**: Directors receive EP_STATE with cross-stage information they couldn't access before
+2. **Feedback injection**: Directors receive specific revision instructions when sent back
+3. **Budget awareness**: Directors receive remaining budget and can adjust tool choices accordingly
+4. **Style anchors**: Directors receive consistency tokens from prior stages
+
+## Example EP Run (Abbreviated)
+
+```
+[EP] Starting pipeline: animated-explainer v2.0
+[EP] Default budget: $2.00 | Target: TBD (set after proposal)
+
+[EP] === STAGE 1: research ===
+[EP] Spawning research-director... Topic: "How DNS Works"
+[EP] Research director executed 18 web searches.
+[EP] Findings: 5 existing videos mapped, 6 data points sourced, 8 audience questions found.
+[EP] Top insight: "1.1.1.1 handles 13.5% of queries — most people assume Google dominates."
+[EP] G1 PASS — 6 data points, 4 angles discovered, 12 sources cited.
+[EP] Budget: $0.00 spent (research is free)
+
+[EP] === STAGE 2: proposal ===
+[EP] Spawning proposal-director with research_brief...
+[EP] Preflight: ElevenLabs ✓, image_selector ✓, video_selector ✗ (no API keys), music_gen ✓
+[EP] 3 concepts presented to user:
+[EP]   C1: "The 200ms Journey" (data_driven, $0.64)
+[EP]   C2: "Your ISP Knows Everything" (contrarian, $0.58)
+[EP]   C3: "The Internet's Phone Book" (analogy, $0.52)
+[EP] Awaiting user approval...
+[EP] USER SELECTED: C1 with modification: "focus on recursive resolution, skip DoH"
+[EP] G2 PASS — Approved with changes. Budget: $0.64 approved.
+[EP] Extracted: target=90s, playbook=minimalist-diagram, budget=$0.64
+
+[EP] === STAGE 3: script ===
+[EP] Spawning script-director with proposal_packet + research_brief...
+[EP] Script director produced script. Reviewing...
+[EP] Word count: 210 words → ~84s at 150 WPM. Target: 90s.
+[EP] Script references 3 data points from research. ✓
+[EP] G3 PASS — Within duration, research integrated.
+
+[EP] === STAGE 4: scene_plan ===
+[EP] Spawning scene-director with script + proposal_packet...
+[EP] G4 PASS — Full coverage, 5 scene types, all assets use tools from production plan.
+
+[EP] === STAGE 5: assets ===
+[EP] Spawning asset-director with scene_plan + script + production_plan...
+[EP] Asset director generated 14 assets. Reviewing...
+[EP] Narration check: Section 3 is 8.2s audio for 6s scene.
+[EP] → Adjusting scene_plan: extending scene-3 to 9s (within tolerance)
+[EP] Budget: $0.52 spent, $0.12 remaining
+[EP] Style check: All images use consistent palette. ✓
+[EP] G5 PASS (with scene duration adjustment)
+
+[EP] === STAGE 6: edit ===
+[EP] Spawning edit-director with adjusted scene_plan + asset_manifest...
+[EP] G6 PASS — Timeline complete, audio ducking configured.
+
+[EP] === STAGE 7: compose ===
+[EP] Spawning compose-director with edit_decisions + asset_manifest...
+[EP] Output probe: 88.7s (target 90s, within 5%). Resolution: 1920x1080. Audio: stereo. ✓
+[EP] G7 PASS
+
+[EP] === STAGE 8: publish ===
+[EP] Spawning publish-director with render_report + proposal_packet...
+[EP] G8 PASS — SEO metadata complete, chapters present, research citations included.
+
+[EP] === FINAL QA ===
+[EP] Duration: 88.7s ✓ | A/V sync: within tolerance ✓ | Style: consistent ✓
+[EP] Budget: $0.52 / $0.64 approved ✓
+[EP] PIPELINE COMPLETE — 0 revisions, 0 send-backs
+[EP] Output: renders/output.mp4
+```
+
+## Common Pitfalls
+
+- **Over-revising**: The EP should be pragmatic. A "pretty good" script that's within duration is better than a "perfect" script after 5 rounds. Use the limits.
+- **Ignoring budget**: Don't let early stages consume all budget. Reserve at least 30% for assets + compose.
+- **Sending back too eagerly**: Minor issues (±10% duration) should be handled by adjusting downstream, not re-running upstream. Only send back for structural problems.
+- **Not probing outputs**: Always ffprobe the final video. Never trust metadata alone.
+- **Losing style context**: The EP must carry style anchors forward. If image 1 uses a specific palette, image 5 must match. Pass this explicitly to the asset director.

skills/pipelines/explainer/idea-director.md

@@ -0,0 +1,183 @@
+# Idea Director — Explainer Pipeline
+
+## When to Use
+
+You are the Idea Explorer for a generated explainer video. The user has provided a **topic or idea** (not raw footage). Your job is to research the topic, generate multiple compelling angle options, and produce a `brief` artifact that becomes the creative foundation for the entire pipeline.
+
+This is the most important stage — a weak brief produces a weak video regardless of how good the tools are. Invest time here.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/brief.schema.json` | Artifact validation |
+| Playbooks | `styles/*.yaml` | Visual/audio style options |
+| Skills | `skills/meta/skill-creator.md` | If you encounter unfamiliar domain |
+
+## Process
+
+### Step 1: Understand the Request
+
+Before doing anything, clarify the user's intent:
+
+- **Topic**: What is the core subject? (e.g., "vector databases", "how HTTPS works", "why the sky is blue")
+- **Audience**: Who is this for? (developers, general public, students, executives)
+- **Platform**: Where will this be published? (YouTube, TikTok, Instagram, LinkedIn) — this constrains duration and style
+- **Duration**: Target length. Defaults by platform: TikTok 30-60s, Instagram Reels 60-90s, YouTube 60-180s, LinkedIn 60-120s
+- **Tone**: Casual, professional, educational, provocative, playful
+
+If the user's request is vague (e.g., "make a video about AI"), ask targeted questions. Never guess when you can ask.
+
+### Step 2: Research the Topic
+
+**This step is mandatory.** Do not skip it. The research dossier is what separates a generic explainer from a compelling one.
+
+Use web search to investigate:
+
+1. **Existing content landscape**: Search YouTube and blogs for existing explainer videos on this topic. What angles have been covered? What's missing? What's been done to death?
+2. **Trending discussions**: Search Reddit, X/Twitter, Hacker News, Stack Overflow for what people are currently asking or debating about this topic. What misconceptions exist? What surprises people?
+3. **Key facts and data**: Find 3-5 surprising statistics, quotes, or facts that could anchor the video. Cite your sources.
+4. **Visual inspiration**: How have the best creators visualized this concept? What analogies work? What diagrams are commonly used?
+5. **Audience knowledge gaps**: What do most people get wrong about this topic? Where does the "aha moment" live?
+
+**Output of this step**: A mental research dossier. You don't need to write it all down, but reference specific findings in your angle options.
+
+### Step 3: Generate Angle Options
+
+Generate **at least 3 genuinely different angles**. Not rewordings — structurally different approaches to the same topic.
+
+For each angle, specify:
+
+| Field | What | Quality Bar |
+|-------|------|-------------|
+| `name` | Short title (5-8 words) | Specific, not generic. "Why Vector Search Beats SQL LIKE" not "About Vector Databases" |
+| `hook` | Opening line/question (under 15 words) | Must create curiosity or surprise in one sentence |
+| `narrative_structure` | How the story unfolds | One of: analogy, problem-solution, journey, debate, myth-busting, timeline, comparison |
+| `visual_approach` | Primary visual style | e.g., "animated diagrams with vector space visualizations" |
+| `suggested_playbook` | Best-matching style playbook | Reference available playbooks in `styles/` |
+| `target_audience` | Who this angle serves best | Specific: "mid-level developers evaluating databases" not "developers" |
+| `why_this_works` | Rationale | Reference your research — why is this angle compelling right now? |
+
+**Angle diversity checklist:**
+- [ ] At least one angle is technical/detailed
+- [ ] At least one angle is intuitive/accessible (uses analogy or story)
+- [ ] At least one angle is provocative/surprising (challenges assumptions)
+- [ ] No two angles use the same narrative structure
+- [ ] Each angle suggests a different visual approach
+
+### Step 4: Present to User and Select
+
+Present all angle options clearly. Let the user:
+- Select one as-is
+- Ask you to combine elements from multiple angles
+- Describe a custom direction entirely
+
+If the user provides a custom direction, use it — but apply the research and quality bar from Steps 2-3.
+
+### Step 5: Assemble the Brief
+
+Build the `brief` artifact with all required and relevant optional fields:
+
+```json
+{
+  "version": "1.0",
+  "title": "...",
+  "hook": "...",
+  "key_points": ["...", "...", "..."],
+  "core_message": "...",
+  "cta": "...",
+  "tone": "...",
+  "style": "...",
+  "target_audience": "...",
+  "target_platform": "youtube|instagram|tiktok|linkedin|generic",
+  "target_duration_seconds": 60,
+  "reference_material": ["..."],
+  "angle_options": [
+    {"name": "...", "description": "..."},
+    {"name": "...", "description": "..."},
+    {"name": "...", "description": "..."}
+  ],
+  "selected_angle": "..."
+}
+```
+
+**Field quality bar:**
+
+| Field | Excellent | Mediocre |
+|-------|-----------|----------|
+| `title` | "How Vector Databases Find Your Data in 1ms" | "Vector Databases Explained" |
+| `hook` | "Your database searches every single row. What if it didn't have to?" | "Today we'll learn about vector databases" |
+| `key_points` | Concrete, specific claims the video will prove | Vague topics like "how it works" |
+| `core_message` | One sentence the viewer should remember tomorrow | Absent or too broad |
+| `cta` | Actionable and relevant: "Try building a similarity search with 10 lines of Python" | Generic: "Like and subscribe" |
+| `tone` | Matches audience and platform | Mismatched (e.g., corporate tone on TikTok) |
+
+### Step 6: Self-Evaluate
+
+Before submitting, score your brief on this rubric (1-5 each):
+
+| Criterion | Question |
+|-----------|----------|
+| **Hook strength** | Would someone stop scrolling for this? Does it create an information gap? |
+| **Specificity** | Are key_points concrete claims, not vague topics? |
+| **Research depth** | Does the brief reference real data, trends, or insights from Step 2? |
+| **Audience fit** | Is the tone, complexity, and duration right for the target audience? |
+| **Playbook match** | Does the selected style genuinely fit the content? |
+| **Uniqueness** | Does this angle offer something the existing content landscape doesn't? |
+
+If any dimension scores below 3, iterate before submitting. The reviewer will check the same criteria.
+
+### Step 7: Submit
+
+Call `handle_explainer_idea(state, {"brief": brief_json})` to validate and persist.
+
+## Playbook Selection Guide
+
+| Content Type | Recommended Playbooks | Why |
+|--------------|----------------------|-----|
+| Technical architecture | `minimalist-diagram` | Clean diagrams, whiteboard feel |
+| Business/SaaS concept | `clean-professional` | Polished, trustworthy |
+| Social media / quick explainer | `flat-motion-graphics` | Eye-catching, data-driven |
+| Storytelling / narrative | Warm playbooks (Ghibli, Watercolor) | Emotional connection |
+| Developer tutorial | `minimalist-diagram` or custom | Focus on code/diagrams |
+
+If no existing playbook fits, describe the desired style in `brief.style` and the pipeline can create a custom playbook later.
+
+## Common Pitfalls
+
+- **Skipping research**: The #1 failure mode. Without research, angles are generic and hooks are weak.
+- **Reworded angles**: Three variations of "explain how X works" are not three angles. Change the narrative structure.
+- **Wrong duration for platform**: A 3-minute explainer doesn't work on TikTok. A 30-second video can't explain Kubernetes.
+- **Ignoring the audience**: A video for CTOs needs different framing than one for junior developers, even on the same topic.
+- **Vague key_points**: "How vector databases work" is a topic, not a key point. "Vector databases use high-dimensional math to find similar items in milliseconds" is a key point.
+
+## Examples
+
+### Good Angle Set (Topic: "How HTTPS Works")
+
+**Angle 1: The Spy Analogy**
+- Hook: "Every time you visit a website, you're having a secret conversation. Here's how."
+- Structure: Analogy (spy/espionage metaphor)
+- Visual: Animated characters passing secret messages
+- Playbook: `flat-motion-graphics`
+- Audience: General public, non-technical
+
+**Angle 2: The Handshake Deep Dive**
+- Hook: "The TLS handshake takes 100 milliseconds and involves 4 messages. Here's what each one does."
+- Structure: Timeline/process walkthrough
+- Visual: Technical diagram with packet animations
+- Playbook: `minimalist-diagram`
+- Audience: CS students, junior developers
+
+**Angle 3: The Myth Buster**
+- Hook: "The padlock icon doesn't mean what you think it means."
+- Structure: Myth-busting (challenge assumption, then reveal truth)
+- Visual: Split-screen before/after misconception
+- Playbook: `clean-professional`
+- Audience: Business professionals, security-aware users
+
+### Bad Angle Set (same topic)
+
+- Angle 1: "HTTPS Explained" — generic, no hook
+- Angle 2: "How HTTPS Works" — same thing, reworded
+- Angle 3: "Understanding HTTPS" — still the same, no structural difference

skills/pipelines/explainer/proposal-director.md

@@ -0,0 +1,343 @@
+# Proposal Director — Explainer Pipeline
+
+## When to Use
+
+You are the **Proposal Director** for a generated explainer video. You sit between the Research Director and the Script Director. You receive a `research_brief` full of raw findings 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." Your job is to make that decision easy by presenting clear options, honest costs, and explicit tradeoffs.
+
+Think of yourself as a creative agency pitching to a client: you present concepts backed by research, show what it'll cost, explain the tradeoffs, and let the client choose.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/proposal_packet.schema.json` | Artifact validation |
+| Prior artifact | `research_brief` from Research Director | Raw research findings |
+| Pipeline manifest | `pipeline_defs/animated-explainer.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 | Topic, any preferences expressed | Creative direction |
+
+## Process
+
+### Step 1: Absorb the Research
+
+Read the `research_brief` thoroughly. Extract:
+
+- **`research_summary`** — read this first. This is the researcher's single most important finding.
+- **`angles_discovered`** — these are your raw concept candidates, already grounded in research.
+- **`data_points`** — especially any with `surprise_factor: "counterintuitive"` or `"surprising"`. These become hooks.
+- **`audience_insights.misconceptions`** — myth-busting is a proven engagement pattern.
+- **`landscape.underserved_gaps`** — this is where the opportunity lives. Our video should fill a gap, not repeat what exists.
+- **`trending`** — if there's a timeliness window, factor it into concept urgency.
+
+### 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))"
+```
+
+Also check the capability catalog:
+
+```bash
+python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.capability_catalog(), indent=2))"
+```
+
+Record:
+- Which TTS providers are available — run `registry.get_by_capability("tts")` and check status
+- Which video generation providers are available — run `registry.get_by_capability("video_generation")` and check status
+- Which enhancement tools are available
+- Image generation status — run `registry.get_by_capability("image_generation")` and check status
+- **Remotion render engine status** — check `video_compose.get_info()["render_engines"]["remotion"]`. If `true`, Remotion is available for animated text cards, stat cards, charts, spring-physics transitions, and image-to-video rendering. This is a major quality upgrade over Ken Burns pan-and-zoom.
+
+This directly affects what you can promise in the production plan. **Do not propose a concept that requires tools you don't have.**
+
+**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 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.
+
+For each concept, specify all fields in the `proposal_packet.concept_options` schema:
+
+#### 3a: Title and Hook
+
+The title and hook are the most important two lines. They determine whether the user gets excited or scrolls past.
+
+**Hook construction patterns** (use the research to fill these):
+
+| Pattern | Template | When to Use |
+|---------|----------|-------------|
+| **Surprising stat** | "[Counterintuitive number]. Here's why." | When you have a data point with high surprise factor |
+| **Misconception flip** | "You've been told [myth]. The truth is [reality]." | When audience_insights.misconceptions has a strong entry |
+| **Recency** | "[Thing] just changed everything about [topic]. Here's what happened." | When trending.recent_developments has a timely event |
+| **Question** | "Why does [thing everyone experiences] actually happen?" | When audience_insights.common_questions has a strong entry |
+| **Contrast** | "[Thing A] takes [big number]. [Thing B] takes [small number]. Here's the trick." | When data_points has comparison data |
+| **Insider knowledge** | "The thing about [topic] that nobody explains." | When landscape.underserved_gaps reveals a strong gap |
+
+**Rules:**
+- Hook must be under 20 words
+- Hook must create an information gap — the viewer needs to watch to close it
+- Hook must be grounded in a specific research finding (cite it in `grounded_in`)
+- Never use: "In this video we'll...", "Hey guys...", "Let me explain..."
+
+#### 3b: Narrative Structure
+
+Choose the structure that best fits the research findings:
+
+| Structure | Best When | Research Signal |
+|-----------|-----------|-----------------|
+| `myth_busting` | Strong misconceptions found | `audience_insights.misconceptions` has 2+ entries |
+| `problem_solution` | Clear pain points | `audience_insights.pain_points` is rich |
+| `data_narrative` | Strong surprising data | Multiple data_points with high surprise_factor |
+| `comparison` | Two approaches to compare | Data_points contain comparative data |
+| `timeline` | Topic has evolution/history | Landscape shows topic changing over time |
+| `journey` | Complex topic needs progressive reveal | `audience_insights.knowledge_level` shows big gaps |
+| `analogy` | Abstract topic needs grounding | Audience is non-technical |
+| `debate` | Community is divided | `trending.active_discussions` shows disagreement |
+| `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
+
+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:
+
+| 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` |
+
+**Remotion components available** (when Remotion engine is active):
+- `text_card` — animated text with spring entrance
+- `stat_card` — number + label with count-up animation
+- `callout` — highlighted explanation box
+- `comparison` — side-by-side with animated reveal
+- `progress` — animated progress bar
+- `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.
+
+#### 3d: Duration and Platform
+
+Set realistic duration based on platform and content depth:
+
+| Platform | Duration Range | Word Budget (150 WPM) |
+|----------|---------------|----------------------|
+| TikTok | 30-60s | 65-150 words |
+| Instagram Reels | 30-90s | 65-225 words |
+| YouTube Shorts | 30-60s | 65-150 words |
+| YouTube | 60-180s | 150-450 words |
+| LinkedIn | 60-120s | 150-300 words |
+
+#### 3e: Concept Diversity Check
+
+Before finalizing, verify diversity:
+
+- [ ] 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
+
+Present all concepts clearly to the user. 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
+
+Let the user:
+- Select one as-is
+- Combine elements from multiple concepts
+- Request modifications
+- Describe a completely different direction (in which case, use the research to strengthen it)
+
+Record the selection in `selected_concept` with rationale and any modifications.
+
+### Step 5: Build the Production Plan
+
+For the selected concept, design the stage-by-stage production plan.
+
+For each stage in the pipeline manifest (`animated-explainer.yaml`), specify:
+
+1. **Which tools will be used** — specific provider names, not just selectors
+2. **Whether each tool is available** — from the preflight check
+3. **Estimated cost per tool** — from the tool's cost metadata
+4. **Why this provider** — explain the choice ("ElevenLabs for narration because voice quality is critical for this topic" or "Piper TTS because running local-only and free")
+5. **Fallback if unavailable** — what happens if the primary tool is down
+
+**Tool selection rationale must be honest:**
+- If using a free/local tool because the cloud tool is unavailable, say so
+- If using a cloud tool when a local alternative exists, explain the quality tradeoff
+- If a capability is entirely missing, say what the video will lack
+
+#### Quality/Cost Tradeoff Matrix
+
+For each meaningful choice, present the tradeoff:
+
+```
+TRADEOFF: TTS Provider
+├── Premium: ElevenLabs ($0.18-0.30) — natural voice, emotional delivery
+├── Standard: OpenAI TTS ($0.05-0.15) — good quality, less expressive
+└── Free: Piper local ($0.00) — robotic but works offline
+
+TRADEOFF: Visual Assets
+├── Premium: AI video clips ($0.10-0.50/clip) — motion, dynamic
+├── Standard: AI images ($0.02-0.04/image) — static, reliable
+└── Free: Diagrams/code ($0.00) — text-based, technical feel
+
+TRADEOFF: Render Path (check video_compose render_engines)
+├── Remotion ($0.00, local): Animated text cards, stat cards, charts,
+│   spring-physics transitions, component-based scenes. Professional
+│   motion graphics feel. Requires Node.js.
+└── FFmpeg ($0.00, local): Ken Burns pan-and-zoom on images, video
+    concat. Functional but less engaging for explainer content.
+```
+
+**If Remotion is available:** Design the scene plan around Remotion component types (text_card, stat_card, chart, etc.) rather than generating AI images for every scene. This is both cheaper (fewer image gen calls) and higher quality (animated motion graphics vs. static images with pan).
+
+Also present **alternative production paths** — complete packages at different price points:
+
+| Path | Quality | Cost | What Changes |
+|------|---------|------|-------------|
+| Premium | Best TTS + video clips + music | ~$1.50-2.50 | Full production value |
+| Standard | Good TTS + images + music | ~$0.50-1.00 | Static visuals, still professional |
+| Budget | Local TTS + images | ~$0.05-0.15 | Robotic voice, image-only |
+| Free | Local TTS + diagrams | $0.00 | Functional but minimal |
+
+### Step 6: Build the Cost Estimate
+
+Itemize every paid operation:
+
+```
+COST ESTIMATE
+├── TTS Narration: tts_selector × 1 run (~150 words)       $0.18
+├── Image Generation: image_selector × 6 scenes                  $0.24
+├── Music: music_gen × 1 track (30s)                        $0.10
+├── Video Generation: video_selector × 2 clips (optional)   $0.00 (local)
+├── Audio Enhancement: audio_enhance × 1 pass               $0.00 (local)
+└── TOTAL ESTIMATED                                         $0.52
+    Budget cap: $2.00
+    Verdict: within_budget ✓
+    Headroom: $1.48 for revisions/regeneration
+```
+
+**Rules:**
+- Always show per-item costs, not just the total
+- Always show the budget cap comparison
+- If over budget, list specific savings options (e.g., "Switch to a cheaper TTS provider: saves $0.18" — check each provider's `estimate_cost` via the registry)
+- Include headroom note — some budget should remain for revisions
+
+### Step 7: Assemble the Approval Gate
+
+The approval section is where the user commits. Present it as a clear decision point:
+
+```
+────────────────────────────────────────
+PROPOSAL READY FOR APPROVAL
+
+Concept: [selected title]
+Duration: [X] seconds for [platform]
+Estimated cost: $[X.XX] of $[budget] budget
+Production path: [premium/standard/budget/free]
+
+Proceed? (approve / approve with changes / reject)
+────────────────────────────────────────
+```
+
+Set `approval.status: "pending"` in the artifact. The EP or the user updates this to `approved` before the pipeline continues.
+
+**Critical rule:** The pipeline MUST NOT proceed past this stage without explicit approval. This is the last free exit. Everything after this costs money and time.
+
+### Step 8: Submit
+
+Validate the `proposal_packet` artifact against `schemas/artifacts/proposal_packet.schema.json` and submit.
+
+## How This Connects Downstream
+
+| Downstream Stage | What It Takes From proposal_packet |
+|------------------|------------------------------------|
+| Script Director | `selected_concept` (title, hook, key_points, core_message, tone, narrative_structure) + research_brief data points |
+| Scene Director | `selected_concept.visual_approach` + `production_plan.playbook` |
+| Asset Director | `production_plan.stages[assets].tools` — knows exactly which providers to use |
+| Executive Producer | `cost_estimate` — initializes budget tracking |
+| All stages | `approval.approved_budget_usd` — hard spending cap |
+
+The `selected_concept` in the proposal_packet effectively replaces what the old `brief` artifact used to be — but it's grounded in research and comes with an explicit production plan attached.
+
+## Common Pitfalls
+
+- **Presenting concepts without research grounding**: Every concept's `why_this_works` must reference specific research findings. "This is a popular topic" is not grounding. "Cloudflare Radar shows 13.5% of DNS queries hit 1.1.1.1, which contradicts the common belief that Google DNS dominates" is grounding.
+- **Hiding costs**: Be transparent. If ElevenLabs will cost $0.30, say $0.30. Don't round down or omit items. The user trusts you more when you're honest.
+- **Over-promising tool availability**: If the preflight shows only Piper TTS available, don't design a concept that depends on expressive voice acting. Design around constraints.
+- **Three versions of the same concept**: "Kubernetes Explained", "Understanding Kubernetes", and "Kubernetes Guide" are not three concepts. They're one concept with three titles. Structural diversity means different narrative structures, different hooks, different audiences.
+- **Skipping the approval gate**: This is the whole point of pre-production. No shortcuts.
+- **Not showing alternatives**: The user should always see at least 2 production paths at different price points. Let them make an informed choice.
+
+## Example: Full Proposal Flow
+
+### Input: research_brief on "How DNS Works"
+
+**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
+- 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.
+
+**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
+- 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.
+
+**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
+- 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.
+
+**Production plan (for selected concept 1, Remotion available):**
+```
+script   → no tools, no cost
+scene    → no tools, no cost — design 4 Remotion component scenes + 4 AI image scenes
+assets   → tts_selector ($0.22), image_selector × 4 ($0.16), music_gen ($0.10)
+edit     → no tools, no cost
+compose  → video_compose/Remotion render (free) — animated text cards, stat cards,
+           spring transitions, image scenes with animation. NOT Ken Burns.
+publish  → no tools, no cost
+TOTAL: $0.48 of $2.00 budget (saved $0.16 by using Remotion components instead of
+       generating images for text/data scenes)
+```
+
+**Production plan (for selected concept 1, FFmpeg only):**
+```
+script   → no tools, no cost
+scene    → no tools, no cost
+assets   → tts_selector ($0.22), image_selector × 8 ($0.32), music_gen ($0.10)
+edit     → no tools, no cost
+compose  → video_compose/FFmpeg (free) — Ken Burns pan-and-zoom on images
+publish  → no tools, no cost
+TOTAL: $0.64 of $2.00 budget
+```
+
+**Alternative paths:**
+- 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)

skills/pipelines/explainer/publish-director.md

@@ -0,0 +1,152 @@
+# Publish Director — Explainer Pipeline
+
+## When to Use
+
+You are the Publisher for a generated explainer video. You have a `render_report` with the final video file. Your job is to prepare the video for distribution: generate SEO metadata, create thumbnails, package exports, and log the publish event.
+
+This is where a great video reaches its audience. Without proper metadata and packaging, even the best content gets buried.
+
+## Prerequisites
+
+| 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 |
+| Playbook | Active style playbook | Visual style for thumbnail |
+
+## Process
+
+### Step 1: Gather Context
+
+Collect everything needed for metadata:
+- **Brief**: 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
+- Lead with a hook or number
+- Avoid clickbait but be compelling
+- Examples: "Vector Databases Explained in 60 Seconds" > "About Vector Databases"
+
+**Description** (first 150 chars are critical — shown in search):
+- Opening line: restate the hook with the main value proposition
+- Body: key topics covered, with relevant keywords naturally included
+- Chapters: timestamp markers for each major section (from script sections)
+- Call to action: subscribe/like/follow
+- Links: relevant resources mentioned in the video
+
+**Tags/Keywords** (platform-dependent):
+- 5-10 specific tags derived from brief's key_points
+- Mix broad and specific: "machine learning" + "vector database tutorial"
+- Include the topic, format ("explainer"), and related terms
+
+**Hashtags** (for social platforms):
+- 3-5 relevant hashtags
+- Mix trending and niche
+
+### Step 3: Generate Thumbnail Concept
+
+Describe a thumbnail that:
+1. Uses the playbook's visual style
+2. Features the video's core concept visually
+3. Includes 3-5 words of text (the hook or key stat)
+4. Has high contrast and is readable at small sizes
+5. Uses the playbook's accent colors for text
+
+```json
+{
+  "thumbnail": {
+    "concept": "Split screen: left side shows slow SQL query (red X), right shows fast vector search (green check). Large text: '100x FASTER'",
+    "text_overlay": "100x FASTER",
+    "style_notes": "Use playbook accent colors, bold Inter font, dark background"
+  }
+}
+```
+
+*Note: Actual thumbnail generation happens via image_selector if available, otherwise it's a concept for manual creation.*
+
+### Step 4: Create Chapter Markers
+
+From the script sections, generate YouTube-style chapters:
+
+```
+0:00 - Introduction
+0:15 - What are Vector Databases?
+0:45 - How Embeddings Work
+1:20 - The Search Algorithm
+1:55 - Real-World Examples
+2:30 - When to Use Vector DBs
+```
+
+Each chapter maps to a script section's `start_seconds`.
+
+### Step 5: Package Export
+
+Create the export directory structure:
+
+```
+exports/
+  <project_name>/
+    video/
+      output.mp4            # Final rendered video
+    metadata/
+      metadata.json         # All SEO metadata
+      chapters.txt          # Chapter markers
+      description.txt       # Ready-to-paste description
+      tags.txt              # One tag per line
+    thumbnails/
+      concept.json          # Thumbnail concept (or generated image)
+```
+
+### Step 6: Build Publish Log
+
+```json
+{
+  "version": "1.0",
+  "entries": [
+    {
+      "platform": "youtube",
+      "status": "draft",
+      "timestamp": "2024-01-15T10:30:00Z",
+      "metadata": {
+        "title": "Vector Databases Explained in 60 Seconds",
+        "description_length": 450,
+        "tags_count": 8,
+        "chapters_count": 6,
+        "thumbnail_ready": false
+      },
+      "export_path": "exports/vector-db-explainer/",
+      "video_path": "renders/output.mp4"
+    }
+  ]
+}
+```
+
+### Step 7: Self-Evaluate
+
+Score (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **SEO quality** | Would this title and description rank well for the topic? |
+| **Description completeness** | Does the description include chapters, CTA, and keywords? |
+| **Thumbnail concept** | Would this thumbnail stand out in a feed? |
+| **Export package** | Is everything a creator needs in the export directory? |
+| **Platform fit** | Is metadata tailored to the target platform? |
+
+If any dimension scores below 3, revise.
+
+### Step 8: Submit
+
+Validate the publish_log against the schema and persist via checkpoint.
+
+## Common Pitfalls
+
+- **Generic titles**: "Video About X" loses to "X Explained in 60 Seconds" every time. Be specific and compelling.
+- **No chapters**: YouTube rewards videos with chapters. Always include them.
+- **Description keyword stuffing**: Write for humans first, search engines second. Natural language with keywords woven in.
+- **Forgetting the CTA**: Every description should end with a call to action.
+- **Wrong platform format**: YouTube descriptions differ from TikTok captions. Tailor to the target platform.

skills/pipelines/explainer/research-director.md

@@ -0,0 +1,311 @@
+# Research Director — Explainer Pipeline
+
+## When to Use
+
+You are the **Research Director** for a generated explainer video. You are the first stage in the pipeline — before any creative decisions, before any script, before any money is spent. Your job is to **deeply research the topic** using web search and produce a `research_brief` artifact that grounds the entire video in real data, real trends, and real audience insights.
+
+This stage is what separates an OpenMontage video from generic AI slop. Without research, the agent produces vague platitudes. With research, it produces content that has authority, specificity, and timeliness.
+
+**You do NOT make creative decisions.** You gather raw material. The Proposal Director downstream will use your findings to craft concept options.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/research_brief.schema.json` | Artifact validation |
+| User input | Topic, audience hint, platform hint | Research scope |
+| Tools | Web search, web fetch | Research execution |
+
+## Process
+
+### Step 1: Scope the Research
+
+Before searching anything, establish boundaries:
+
+- **Topic**: What is the core subject? Extract from user input.
+- **Audience hint**: Did the user mention who this is for? (developers, general public, executives, students)
+- **Platform hint**: Did the user mention where this will go? (YouTube, TikTok, LinkedIn)
+- **Depth**: Is this a well-known topic (HTTPS, React) or niche (vector clock CRDTs, QUIC protocol)?
+
+If the user's request is a single phrase like "make a video about kubernetes," that's fine — you have enough to research. Do NOT ask clarifying questions at this stage. Research first, clarify later (in the Proposal stage).
+
+### Step 2: Content Landscape Scan
+
+**Goal:** Understand what already exists so we can find gaps.
+
+Execute these searches in parallel:
+
+```
+SEARCH BATCH 1 — Landscape (run all in parallel)
+
+Q1: "[topic] explained" site:youtube.com
+    → Find: Top existing explainer videos. Note titles, view counts, angles used.
+
+Q2: "[topic]" (guide OR tutorial OR explained OR breakdown) -site:youtube.com
+    → Find: Blog posts and articles covering this topic.
+
+Q3: "[topic] [current month] [current year]"
+    → Find: The freshest content. What's being published RIGHT NOW?
+
+Q4: "best [topic category] [current year]"
+    → Find: Listicles and comparisons — reveals the competitive landscape.
+```
+
+**Parse results for:**
+- Which angles have been done to death (saturated)
+- Which questions remain unanswered (gaps)
+- What the top-performing content looks like (benchmarks)
+- When the most recent quality content was published (freshness)
+
+Record at least 3 entries in `landscape.existing_content` with specific titles, sources, and gap analysis.
+
+### Step 3: Trending Pulse
+
+**Goal:** Find what's happening RIGHT NOW — news, debates, controversies, launches.
+
+```
+SEARCH BATCH 2 — Trending (run all in parallel)
+
+Q5: "[topic]" (announcement OR launch OR update OR controversy) after:[current year]-01-01
+    → Find: Recent events that make this topic timely.
+
+Q6: "[topic]" site:reddit.com after:[6 months ago]
+    → Find: Active community discussions, pain points, hot takes.
+
+Q7: "[topic]" site:news.ycombinator.com
+    → Find: Tech-literate opinions, contrarian takes, deeper analysis.
+
+Q8: "why is [topic]" (trending OR popular OR important OR everywhere) [current year]
+    → Find: Meta-commentary on why people care about this right now.
+```
+
+**Parse results for:**
+- Recent developments that could be the hook ("X just happened, here's what it means")
+- Active debates where people disagree (debate = engagement)
+- Sentiment — is the community excited, frustrated, confused, divided?
+- Timeliness window — is this a "publish this week" moment or evergreen?
+
+If no trending signal exists, that's fine — note `timeliness_window: "evergreen"` and move on. Not every topic has a news hook, and that's okay.
+
+### Step 4: Data and Evidence Gathering
+
+**Goal:** Find specific, citable facts that will anchor the script.
+
+```
+SEARCH BATCH 3 — Data (run all in parallel)
+
+Q9: "[topic]" statistics [current year]
+    → Find: Hard numbers — market size, adoption rates, performance benchmarks.
+
+Q10: "[topic]" (study OR research OR survey OR report) [current year - 1] OR [current year]
+     → Find: Academic or industry research with credible methodology.
+
+Q11: "[topic]" "according to" (report OR study OR survey)
+     → Find: Cited claims with named sources.
+
+Q12: "[topic]" "surprisingly" OR "counterintuitively" OR "most people don't know"
+     → Find: Surprising facts — these become hooks and retention anchors.
+
+Q13: "[topic]" (comparison OR benchmark OR "vs") data
+     → Find: Comparative data that can become visual stat cards.
+```
+
+**For each data point found, record:**
+- The specific claim (not vague — "73% of developers use X" not "most developers use X")
+- Source URL and source name
+- Credibility rating: `primary_source` (original research), `secondary_source` (reporting on research), `anecdotal` (blog post, opinion)
+- Surprise factor: would the target audience find this expected or counterintuitive?
+- How it could be used: `hook`, `stat_card`, `script_anchor`, `closing_punch`
+
+**Minimum: 3 data points. Target: 5-8.** If the topic is data-poor (e.g., philosophical or creative), find expert quotes instead.
+
+### Step 5: Audience Mining
+
+**Goal:** Understand what real people ask, believe, and get wrong about this topic.
+
+```
+SEARCH BATCH 4 — Audience (run all in parallel)
+
+Q14: "[topic]" site:reddit.com "help" OR "confused" OR "why does" OR "ELI5"
+     → Find: Real questions from real people struggling with this topic.
+
+Q15: "[topic]" site:quora.com OR site:stackoverflow.com
+     → Find: Structured Q&A — what do beginners ask?
+
+Q16: "why is [topic] so" (hard OR confusing OR expensive OR slow OR popular)
+     → Find: Pain points and frustrations.
+
+Q17: "[topic]" "common mistakes" OR "myths" OR "misconceptions" OR "wrong about"
+     → Find: What people get wrong — myth-busting is powerful engagement.
+
+Q18: "[topic]" "wish I knew" OR "before you start" OR "nobody tells you"
+     → Find: Insider knowledge that feels valuable.
+```
+
+**Parse results for:**
+- Top 5+ real questions (not generated — sourced from actual forum posts)
+- Common misconceptions with the real answer (myth vs reality)
+- Knowledge level of the target audience (what they already know, what's new)
+- Pain points and frustrations
+
+### Step 6: Expert Voices (Optional but High-Value)
+
+**Goal:** Find named experts and their positions — adds authority.
+
+```
+SEARCH BATCH 5 — Experts (run if topic has known figures)
+
+Q19: "[topic]" (creator OR inventor OR pioneer OR expert) (interview OR talk OR keynote)
+     → Find: The key voices on this topic.
+
+Q20: "[topic]" "unpopular opinion" OR "hot take" OR "controversial"
+     → Find: Contrarian positions that create debate framing.
+```
+
+**For each expert, record:**
+- Name and affiliation
+- Their position or notable quote
+- Whether they're mainstream or contrarian (contrarian views make great "but..." moments in scripts)
+
+### Step 7: Visual Reference Scan (Quick Pass)
+
+**Goal:** See how others visualize this concept — inform the Proposal Director's visual approach.
+
+```
+Q21: "[topic]" (explainer OR animation OR infographic OR diagram)
+     → Find: Visual treatments that work for this topic.
+```
+
+Record 2-3 visual references with what works about each approach.
+
+### Step 8: Angle Synthesis
+
+**This is where you earn your keep.** Using everything from Steps 2-7, identify at least 3 genuinely different angle candidates.
+
+For each angle, specify:
+
+| Field | What | Quality Bar |
+|-------|------|-------------|
+| `name` | Short title (5-8 words) | Specific. "Why Vector Search Beats SQL LIKE" not "About Vector Databases" |
+| `hook` | One-sentence grabber | Must create an information gap or surprise |
+| `type` | `trending`, `evergreen`, `contrarian`, `narrative`, `data_driven` | Categorize honestly |
+| `why_now` | Why this angle is compelling right now | **Must cite specific research findings** — not vibes |
+| `grounded_in` | Which data points or audience insights support it | Cross-reference your findings |
+
+**Angle diversity checklist:**
+- [ ] At least one angle leverages trending/recent findings (if available)
+- [ ] At least one angle is evergreen (works in 6 months too)
+- [ ] At least one angle is surprising or contrarian
+- [ ] No two angles use the same hook structure
+- [ ] Each angle is grounded in different research findings
+
+### Step 9: Source Bibliography
+
+Compile all URLs used, organized by which section of the brief they support. Minimum 5 sources.
+
+**Source quality rules:**
+- Primary sources (original studies, official docs) > secondary (news articles, blog posts) > anecdotal (forum comments, tweets)
+- At least 2 sources should be primary
+- Every data_point must have a source_url
+- Flag any source older than 2 years — it may be outdated
+
+### Step 10: Assemble and Submit
+
+Build the `research_brief` artifact per the schema. Include:
+
+1. `research_summary` — one paragraph capturing the single most important insight. This is what the Proposal Director reads first.
+2. All sections from Steps 2-9
+
+Validate against `schemas/artifacts/research_brief.schema.json` before submitting.
+
+## Search Query Construction Rules
+
+These rules ensure your searches actually find useful results:
+
+### Use the Current Date
+
+Always include time context in queries where freshness matters:
+- `[topic] [current year]` for general freshness
+- `[topic] [current month] [current year]` for trending signals
+- `after:[YYYY-MM-DD]` filters when supported
+
+### Topic Decomposition
+
+For compound topics, search both the whole and the parts:
+- Topic: "how kubernetes autoscaling works"
+- Search 1: `kubernetes autoscaling explained`
+- Search 2: `kubernetes HPA` (the specific mechanism)
+- Search 3: `container orchestration autoscaling` (the broader category)
+
+### Audience-Aware Query Variants
+
+The same topic needs different queries for different audiences:
+- For developers: `[topic] implementation` / `[topic] architecture` / `[topic] code example`
+- For executives: `[topic] ROI` / `[topic] business impact` / `[topic] case study`
+- For general public: `[topic] explained simply` / `what is [topic]` / `[topic] for beginners`
+
+### Quote Mining
+
+To find specific quotable content:
+- `"[topic]" "the problem is"` — finds people articulating problems
+- `"[topic]" "the key insight"` — finds distilled wisdom
+- `"[topic]" "what surprised me"` — finds surprise reactions
+
+### The Negative Space
+
+Search for what's NOT being said:
+- `[topic] "nobody talks about"` — finds underserved angles
+- `[topic] "overlooked"` — finds hidden aspects
+- `[topic] -[obvious_subtopic]` — filters out saturated content
+
+## Quality Bar
+
+Before submitting your research_brief, verify:
+
+| Criterion | Minimum | Target |
+|-----------|---------|--------|
+| Existing content surveyed | 3 pieces | 5-8 pieces |
+| Data points with sources | 3 | 5-8 |
+| Audience questions sourced | 3 | 5-10 |
+| Misconceptions identified | 1 | 2-3 |
+| Angle candidates | 3 | 4-5 |
+| Total sources cited | 5 | 10-15 |
+| Searches executed | 10 | 15-21 |
+
+**If you can't find data points:** The topic may be too niche or too new. That's useful information — record it in `research_summary` and note that the angle should lean narrative/analogy rather than data-driven.
+
+**If you can't find existing content:** That's a strong signal — a content gap IS the opportunity. Note this prominently.
+
+## Execution Constraints
+
+| Constraint | Value | Why |
+|------------|-------|-----|
+| Max time on research | 3-5 minutes | Research is valuable but has diminishing returns |
+| Max searches | 25 | Prevent infinite rabbit holes |
+| Min searches | 10 | Ensure adequate coverage |
+| No paid tools | — | Research uses web search only — zero cost |
+
+## Common Pitfalls
+
+- **Skipping to angles without research**: The angles_discovered must be grounded in findings from the other sections. If you can't point to specific data_points or audience_insights that support an angle, the angle is just a guess.
+- **Recording vague data**: "Most companies use AI" is not a data point. "87% of Fortune 500 companies have active AI projects (McKinsey 2025)" is a data point.
+- **Only searching one way**: If `[topic] statistics` returns nothing, try `[topic] survey`, `[topic] report`, `[topic] data`, `[topic] benchmark`. Vary your query terms.
+- **Ignoring negative results**: If searches for trending content return nothing recent, that IS a finding — it means this topic is evergreen, not trending. Record it.
+- **Treating all sources equally**: A peer-reviewed study and a random blog post are not equal. Label credibility honestly.
+- **Stopping at surface-level**: The first page of Google results is what everyone sees. Dig into specific discussions, specific studies, specific data. The value is in specificity.
+
+## Example: Good vs Bad Research
+
+### Topic: "How DNS Works"
+
+**Bad research output:**
+- "DNS is important for the internet"
+- "There are many DNS providers"
+- Angles: "DNS Explained", "How DNS Works", "Understanding DNS"
+
+**Good research output:**
+- Landscape: "Fireship's 'DNS in 100 seconds' has 2.1M views and covers basics but skips DNSSEC entirely. Cloudflare's blog series is comprehensive but text-only. Gap: no visual explainer covers DNS-over-HTTPS controversy."
+- Data point: "1.1.1.1 handles 13.5% of all DNS queries globally (Cloudflare Radar 2025, primary source). Surprise factor: counterintuitive — most people think Google's 8.8.8.8 is #1."
+- Audience: "Top Reddit question: 'Why does DNS take so long sometimes?' (r/networking, 847 upvotes). Misconception: people think DNS is a single lookup, not a recursive chain."
+- Trending: "Cloudflare just launched DNS-over-QUIC support (March 2026). DoH vs DoT debate is active on HN."
+- Angles: "The 200ms Journey Your Browser Takes Before Loading Anything" (data_driven, grounded in recursive resolution timing data), "Why Your ISP Knows Every Website You Visit — And How to Stop It" (contrarian, grounded in DNS privacy research + DoH trending signal), "DNS is a 40-Year-Old Phone Book Running the Modern Internet" (narrative/analogy, grounded in audience knowledge gap about DNS age + simplicity)

skills/pipelines/explainer/scene-director.md

@@ -0,0 +1,183 @@
+# Scene Director — Explainer Pipeline
+
+## When to Use
+
+You are the Scene Planner for a generated explainer video. You have a `script` artifact with timestamped sections and enhancement cues. Your job is to transform the script into a visual plan: what the viewer sees at every moment, what assets need to be created, and how scenes transition.
+
+This is where words become visuals. A great script with a bad scene plan produces a confusing video.
+
+## Prerequisites
+
+| 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 |
+| 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 |
+
+## Process
+
+### Step 1: Analyze the Script
+
+Read every section. For each, note:
+- What concept is being explained?
+- What enhancement cues did the script writer embed?
+- What's the emotional beat? (curiosity, revelation, emphasis, humor, conclusion)
+- How much time is available? (end_seconds - start_seconds)
+
+### Step 2: Research Visual Approaches
+
+**Use web search** to find visual techniques for this topic:
+
+1. **How do top creators visualize this?** Search YouTube thumbnails, blog diagrams, conference slides for the topic.
+2. **What visual metaphors work?** Some concepts have well-known visual representations (e.g., neural networks as node graphs, encryption as locks/keys). Use these — viewers recognize them instantly.
+3. **What's novel?** Is there a visual approach nobody has tried? A fresh visualization can make an explainer memorable.
+4. **What's feasible?** Match your ambitions to available tools: `image_selector` (static images), `diagram_gen` (Mermaid flowcharts/sequences), `code_snippet` (syntax-highlighted code), Remotion (motion graphics, text animations), Manim (mathematical animations).
+
+If you encounter a visualization need that no existing skill covers, use the **Skill Creator** (`skills/meta/skill-creator.md`) to create a new skill.
+
+### Step 3: Decompose into Scenes
+
+Transform each script section into 1-3 visual scenes. Each scene is a distinct visual moment.
+
+```json
+{
+  "id": "scene-3",
+  "type": "diagram",
+  "description": "Mermaid flowchart showing query → encode → vector search → rank → return results. Nodes appear one by one as narrator describes each step.",
+  "start_seconds": 15,
+  "end_seconds": 22,
+  "script_section_id": "s3",
+  "framing": "full-screen diagram, centered",
+  "movement": "progressive reveal left-to-right",
+  "transition_in": "fade",
+  "transition_out": "dissolve",
+  "overlay_notes": "Label each node as it appears",
+  "required_assets": [
+    {
+      "type": "diagram",
+      "description": "Mermaid flowchart: query → encode embedding → vector search (ANN) → rank by cosine similarity → return top-k results",
+      "source": "generate"
+    }
+  ]
+}
+```
+
+#### Scene Types and When to Use Them
+
+| Type | Best For | Available Tools | Duration Guidance |
+|------|----------|-----------------|-------------------|
+| `animation` | Concepts needing motion (data flow, transformations, math) | Remotion, Manim | 4-10s |
+| `diagram` | Processes, architecture, relationships | `diagram_gen` (Mermaid), `image_selector` (stylized) | 4-8s |
+| `text_card` | Key terms, definitions, statistics, quotes | Remotion TextCard component | 3-5s |
+| `generated` | Illustrations, metaphors, real-world imagery | `image_selector` (FLUX/DALL-E) | 3-6s |
+| `talking_head` | AI avatar speaking (if HeyGen available) | HeyGen tools | 5-15s |
+| `broll` | Context, real-world examples | Stock or generated footage | 3-6s |
+| `transition` | Dedicated transition moment between topics | Remotion transition | 1-2s |
+| `screen_recording` | Code demos, UI walkthroughs | Recorded or simulated | 5-15s |
+
+### Step 4: Apply the Visual Technique Library
+
+These are proven patterns for explainer visuals. Reference them by name in scene descriptions:
+
+**Diagram Reveal**
+Build a diagram progressively — start empty, add components with labels as the narrator describes each part. Perfect for architecture, processes, and systems.
+- Tools: Mermaid + Remotion animation or FLUX-generated diagram
+- Example: "Show the vector database architecture. Add the encoder node when narrator says 'embeddings'. Add the index when narrator says 'search'."
+
+**Analogy Visualization**
+Show the abstract concept alongside its real-world analogy. Split screen or side-by-side.
+- Tools: `image_selector` for both sides
+- Example: "Left: actual vector space with dots. Right: a library with books sorted by topic."
+
+**Stat Card Punch**
+Full-screen number or comparison. Appears with impact animation (scale up, slight bounce). Hold for 2-3 seconds.
+- Tools: Remotion TextCard component
+- Example: "1ms" in large text, then smaller text below: "vs 500ms with traditional search"
+
+**Before/After Split**
+Show the problem, then the solution. Can be sequential (problem → transition → solution) or split-screen.
+- Tools: `image_selector` for both states
+- Example: "Before: SQL query scanning millions of rows (slow). After: vector search finding nearest neighbors (fast)."
+
+**Timeline Progression**
+Left-to-right or top-to-bottom sequence showing evolution or process steps. Each step appears as narrator describes it.
+- Tools: Remotion with animated elements or Mermaid timeline
+- Example: "1990: keyword search → 2010: semantic search → 2020: vector databases → 2024: multimodal search"
+
+**Zoom and Focus**
+Start with a wide view of a system, then zoom into a specific component to explain it in detail. Creates spatial context.
+- Tools: Remotion with scale animation on a generated image
+- Example: "Show full system architecture. Zoom into the 'embedding model' component."
+
+**Code Walkthrough**
+Show code with syntax highlighting. Highlight specific lines as the narrator explains them. Can animate typing or progressive reveal.
+- Tools: `code_snippet` tool + Remotion
+- Example: "Python code: `results = collection.query(embedding, n_results=5)`. Highlight `embedding` parameter when narrator says 'vector'."
+
+### Step 5: Validate Against Playbook
+
+The style playbook constrains your visual choices:
+
+| Playbook Field | Scene Impact |
+|----------------|-------------|
+| `visual_language.color_palette` | All generated images and diagrams must use these colors |
+| `visual_language.composition` | Framing rules (rule-of-thirds, centered, etc.) |
+| `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.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
+
+### Step 6: Verify Coverage and Variety
+
+**Coverage check:**
+- [ ] Scenes span the full script duration (first scene starts at 0s, last scene ends at total_duration)
+- [ ] Every script section has at least one corresponding scene
+- [ ] No gaps > 1s between scenes (unless intentional beat)
+- [ ] All enhancement cues from the script are addressed by a scene or required_asset
+
+**Variety check:**
+- [ ] No more than 3 consecutive scenes of the same type
+- [ ] At least 3 different scene types used in the video
+- [ ] Visual pacing alternates between high-information scenes (diagrams, animations) and breathing room (text cards, generated images)
+
+**Feasibility check:**
+- [ ] Every `required_asset` with `source: "generate"` is achievable with available tools
+- [ ] Diagram descriptions are specific enough for Mermaid syntax generation
+- [ ] Image descriptions are specific enough for FLUX/DALL-E prompt engineering
+- [ ] No scene requires tools that aren't in the tool registry
+
+### Step 7: Self-Evaluate
+
+Score (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **Visual storytelling** | Does each scene advance understanding, not just decorate? |
+| **Script alignment** | Does every scene match what the narrator is saying at that moment? |
+| **Technique variety** | Did you use multiple visual techniques, not just one? |
+| **Playbook fidelity** | Would every scene look like it belongs to the same video? |
+| **Asset feasibility** | Can every required_asset actually be generated with available tools? |
+| **Pacing** | Does the visual rhythm feel natural? High-info scenes balanced with breathing room? |
+
+If any dimension scores below 3, revise.
+
+### Step 8: Submit
+
+Call `handle_explainer_scene_plan(state, {"scene_plan": scene_plan_json})` to validate and persist.
+
+## Common Pitfalls
+
+- **One scene per section**: Script sections often cover multiple concepts. A 10-second section might need 2-3 visual scenes to avoid boring stasis.
+- **Ignoring enhancement cues**: The script writer embedded visual hints in `enhancement_cues`. Don't ignore them — they represent the writer's visual intent.
+- **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.
+- **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.

skills/pipelines/explainer/script-director.md

@@ -0,0 +1,223 @@
+# Script Director — Explainer Pipeline
+
+## When to Use
+
+You are the Script Writer for a generated explainer video. You have a `brief` artifact from the Idea Explorer. Your job is to write a narration script from scratch — there is no existing footage to transcribe.
+
+The script is the backbone of the video. Every visual, every scene, every audio cue flows from what you write here. A mediocre script cannot be saved by great visuals.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `proposal_packet` | Selected concept with title, hook, key_points, core_message, tone, narrative_structure, duration |
+| Prior artifact | `research_brief` (optional but high-value) | Data points, audience insights, expert quotes — ground the script in real facts |
+| Playbook | Active style playbook from `proposal_packet.selected_concept.suggested_playbook` | Voice style, pacing rules |
+| Layer 3 | TTS provider skills (check `agent_skills` on the selected TTS tool) | TTS capabilities for speaker directions |
+
+## Process
+
+### Step 1: Absorb the Proposal and Research
+
+Read the `proposal_packet.selected_concept` carefully. Extract:
+- **Target duration** — this is your word budget (see timing table below)
+- **Hook** — your opening must deliver on this promise
+- **Key points** — these must all be covered in the script
+- **Core message** — the one thing the viewer should remember
+- **Tone** — shapes word choice, sentence length, formality
+- **Target audience** — shapes complexity and assumed knowledge
+- **Narrative structure** — the structural approach (myth_busting, journey, data_narrative, etc.)
+
+Then read the `research_brief` for grounding material:
+- **`data_points`** — specific statistics and facts to weave into the script. Use claims with `surprise_factor: "surprising"` or `"counterintuitive"` as retention anchors.
+- **`audience_insights.misconceptions`** — if the narrative structure is `myth_busting`, these are your myth/reality pairs.
+- **`audience_insights.common_questions`** — address these directly in the script where they naturally fit.
+- **`expert_voices`** — quotable experts add authority. Use sparingly — one or two per script.
+- **`trending.recent_developments`** — if timely, reference them to make the content feel current.
+
+**The research_brief is your cheat sheet.** Every fact, every surprising stat, every misconception is pre-verified and sourced. Use them. A script that cites "73% of developers..." (from research) is more compelling than one that says "many developers..."
+
+### Step 2: Deepen Research Where Needed
+
+The Research Director has already done the heavy lifting — you have a `research_brief` full of sourced facts. Your job here is targeted:
+
+1. **Verify and update**: If any data point from the research_brief feels stale or uncertain, re-search to confirm.
+2. **Fill script-specific gaps**: The research gives you broad facts. You may need a specific analogy, a precise technical detail, or a better example for a particular section.
+3. **Find the best explanation**: How do the best educators (3Blue1Brown, Kurzgesagt, Fireship, Veritasium) explain this concept? What analogies work?
+4. **Source quotable moments**: If the research_brief's expert_voices section has useful quotes, use them. If not, search for one strong quote to anchor a key section.
+
+**Do NOT duplicate the Research Director's work.** If the research_brief already has 6 data points, you don't need to find 6 more. Focus on script-level needs: the right word, the right analogy, the right sequence.
+
+### Step 3: Plan the Narrative Arc
+
+Before writing prose, plan the structure. Every explainer script follows a dramatic arc:
+
+```
+HOOK (0-5s)     → Grab attention. Question, bold claim, or surprising fact.
+                   NEVER: "In this video, we'll learn about..."
+                   NEVER: "Hey guys, welcome back..."
+
+SETUP (5-15s)   → Why should the viewer care? Create a knowledge gap.
+                   Show the problem or the question. Make them NEED the answer.
+
+BUILD (15-Xs)   → Progressive revelation. Each section builds on the last.
+                   Use "therefore / but" transitions, NOT "and then."
+                   South Park rule: "This happened, THEREFORE that happened,
+                   BUT then this complication arose..."
+
+CLIMAX (X-5s before end) → The "aha" moment. Everything clicks into place.
+                            This is the payoff for the setup's knowledge gap.
+
+LANDING (last 5s) → Quick recap of core message + CTA.
+                     Don't introduce new information here.
+```
+
+Map each of the brief's `key_points` to a specific section in the BUILD phase.
+
+### Step 4: Write the Script
+
+Write each section with these fields:
+
+```json
+{
+  "id": "s1",
+  "label": "Hook",
+  "text": "Your database searches every single row. Every. Single. One. What if it didn't have to?",
+  "start_seconds": 0,
+  "end_seconds": 5,
+  "speaker_directions": "Emphasize 'every single row' with measured pacing. Brief pause before the question.",
+  "enhancement_cues": [
+    {
+      "type": "animation",
+      "description": "Database table with rows highlighted one by one, slowing down as count increases",
+      "timestamp_seconds": 1
+    }
+  ],
+  "pronunciation_guides": []
+}
+```
+
+#### Timing Estimation
+
+| Pace | Words/minute | Use when |
+|------|-------------|----------|
+| Conversational | ~150 wpm | Default for most explainers |
+| Contemplative | ~120 wpm | Complex topics, need processing time |
+| Energetic | ~180 wpm | Short-form, high-energy, TikTok/Reels |
+| Technical | ~130 wpm | Code walkthroughs, architecture deep-dives |
+
+**Word budget by duration:**
+- 30s video → ~65-75 words
+- 60s video → ~130-150 words
+- 90s video → ~195-225 words
+- 120s video → ~260-300 words
+
+Count your words. If you're 20%+ over budget, the TTS will either rush or exceed duration. Cut ruthlessly.
+
+#### Speaker Directions
+
+Write directions that TTS can actually implement. Reference ElevenLabs capabilities:
+
+| Direction | TTS Implementation |
+|-----------|-------------------|
+| "Speak slowly, with emphasis" | Lower speed setting, stability boost |
+| "Excited, picking up pace" | Higher speed, higher style setting |
+| "Pause for 1 second" | SSML `<break time="1s"/>` |
+| "Whisper" | SSML whisper tag (model-dependent) |
+| "Emphasize THIS word" | Note for post-processing or SSML emphasis |
+
+Avoid directions TTS can't do: "smile while speaking", "gesture toward screen", "look at camera."
+
+#### Enhancement Cues
+
+Every section should have at least one enhancement cue. These tell the Scene Planner and Asset Generator what visuals to create.
+
+| Cue Type | When to Use | Example |
+|----------|-------------|---------|
+| `overlay` | Key term, definition, label | "Show 'embedding' definition overlay" |
+| `diagram` | Process, architecture, flow | "Mermaid flowchart: query → encode → search → rank" |
+| `stat_card` | Surprising number or comparison | "Display: 1ms vs 500ms search time" |
+| `animation` | Concept that needs motion to understand | "Animate vectors moving through high-dimensional space" |
+| `code_snippet` | Code example | "Show Python: `results = collection.query(embedding)`" |
+| `broll` | Real-world context | "Show examples of apps using vector search" |
+
+**Density rule**: At least one enhancement cue every 8-10 seconds. A 60-second video should have 6-8 cues minimum. Viewers disengage if the visual doesn't change.
+
+#### Pronunciation Guides
+
+For technical terms, acronyms, and non-English words:
+
+```json
+{"word": "FAISS", "phonetic": "FACE"},
+{"word": "Qdrant", "phonetic": "kuh-DRANT"},
+{"word": "cosine", "phonetic": "CO-sign"}
+```
+
+### Step 5: Validate Against Playbook
+
+Read the active style playbook and verify:
+
+| Playbook Field | Script Impact |
+|----------------|---------------|
+| `identity.pace` | Match word density. `contemplative` = fewer words, longer pauses |
+| `audio.voice_style` | Shape tone of speaker directions |
+| `motion.pacing_rules` | E.g., "hold establishing shots for 2s minimum" affects section timing |
+| `identity.mood` | Word choice: `warm` uses casual language; `professional` uses precise language |
+
+### Step 6: Self-Evaluate
+
+Score your script (1-5):
+
+| Criterion | Question |
+|-----------|----------|
+| **Hook power** | Would someone stop scrolling in the first 3 seconds? |
+| **Word count accuracy** | Within ±10% of target for the duration? |
+| **Narrative flow** | Does each section build on the last? "Therefore/but" not "and then"? |
+| **Enhancement density** | At least one cue every 8-10 seconds? |
+| **Jargon management** | Technical terms explained or have pronunciation guides? |
+| **Climax payoff** | Does the aha moment deliver on the hook's promise? |
+| **CTA relevance** | Is the call to action specific and actionable? |
+
+If any dimension scores below 3, revise before submitting.
+
+### Step 7: Submit
+
+Call `handle_explainer_script(state, {"script": script_json})` to validate and persist.
+
+## 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.
+- **Front-loading information**: The hook should create curiosity, not dump information. "HTTPS uses TLS 1.3 with AEAD ciphers" is a terrible opening. "The padlock icon doesn't mean what you think it means" is compelling.
+- **Missing enhancement cues**: A script without visual direction is a podcast script. Every section needs at least one cue telling the visual team what to show.
+- **Generic speaker directions**: "Read naturally" is useless. "Start measured and precise, then accelerate through the list to convey scale" is actionable.
+- **Forgetting the audience**: A script for CTOs should use different words than one for high schoolers, even if covering the same concept.
+- **No transitions between sections**: Each section should have a logical bridge to the next. The viewer should never think "wait, why are we talking about this now?"
+
+## Example: Well-Written Section
+
+```json
+{
+  "id": "s3",
+  "label": "The Core Idea",
+  "text": "Instead of matching keywords, vector databases convert everything — text, images, audio — into lists of numbers called embeddings. Similar things get similar numbers. So finding related content becomes a math problem: which numbers are closest?",
+  "start_seconds": 15,
+  "end_seconds": 28,
+  "speaker_directions": "Measured pace through 'text, images, audio' with slight pause between each. Speed up slightly on 'similar things get similar numbers' — it should feel like a revelation. Brief pause before the final question.",
+  "enhancement_cues": [
+    {
+      "type": "animation",
+      "description": "Show text/image/audio icons transforming into number arrays (embeddings). Arrays cluster by similarity in a 2D space.",
+      "timestamp_seconds": 16
+    },
+    {
+      "type": "stat_card",
+      "description": "Display: 'Everything becomes numbers. Similar things → similar numbers.'",
+      "timestamp_seconds": 22
+    }
+  ],
+  "pronunciation_guides": [
+    {"word": "embeddings", "phonetic": "em-BED-ings"}
+  ]
+}
+```

skills/pipelines/hybrid/asset-director.md

@@ -0,0 +1,70 @@
+# Asset Director - Hybrid Pipeline
+
+## When To Use
+
+This stage prepares the support kit around the anchor edit: subtitles, diagrams, generated inserts, narration, music, and reusable overlay systems.
+
+## Prerequisites
+
+| 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"]` | Support needs and variant plan |
+| Tools | `subtitle_gen`, `tts_selector`, `image_selector`, `video_selector`, `diagram_gen`, `code_snippet`, `music_gen`, `audio_enhance` — selectors auto-discover all available providers from the registry | Optional support asset production |
+| Playbook | Active style playbook | Consistency rules |
+
+## Process
+
+### 1. Build Shared Support Assets First
+
+Start with reusable systems:
+
+- subtitle treatment,
+- lower-third or label system,
+- stat-card system,
+- CTA container,
+- diagram style.
+
+### 1b. Sample Preview (Prevents Wasted Spend)
+
+Before batch-generating support assets, produce one sample of each expensive generated type and show the user:
+
+1. **TTS sample** (if narration is needed): Generate one section. Confirm voice and tone before batching.
+2. **Image/video sample** (if generating inserts): Generate one representative visual. Confirm style fits the source footage before batching.
+
+If rejected, adjust parameters and retry (max 3 iterations). Do not batch until approved.
+
+### 2. Generate Only The Support Assets You Need
+
+Support assets should fill identified needs from the script and scene plan, not speculative possibilities.
+
+### 3. Preserve Anchor Truth
+
+Keep the metadata clear about which assets are:
+
+- source-derived,
+- provided,
+- recorded,
+- generated.
+
+### 4. Use Metadata For The Support Map
+
+Recommended metadata keys:
+
+- `shared_support_assets`
+- `scene_asset_index`
+- `source_vs_generated_map`
+- `variant_assets`
+
+### 5. Quality Gate
+
+- support assets map to real narrative needs,
+- reusable kits are present,
+- source and generated assets are clearly separated,
+- every referenced file exists.
+
+## 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.

skills/pipelines/hybrid/compose-director.md

@@ -0,0 +1,48 @@
+# Compose Director - Hybrid Pipeline
+
+## When To Use
+
+Render the hybrid project so source media, support graphics, and audio all remain coherent across outputs.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Edit logic and support assets |
+| Tools | `video_compose`, `audio_mixer`, `video_stitch`, `video_trimmer`, `color_grade`, `audio_enhance` | Final assembly and polish |
+| Playbook | Active style playbook | Output consistency |
+
+## Process
+
+### 1. Verify Source And Support Balance
+
+The final render should still look like a source-led video with support, not a collage of unrelated systems.
+
+### 2. Check Variant Integrity
+
+For each output variant, verify:
+
+- crop safety,
+- text safety,
+- subtitle legibility,
+- audio consistency.
+
+### 3. Keep Audio Coherent
+
+Source dialogue, narration, music, and effects should feel like one mix, not separate layers fighting for space.
+
+### 4. Use Render Metadata
+
+Recommended metadata keys:
+
+- `variant_outputs`
+- `balance_checks`
+- `subtitle_checks`
+- `audio_notes`
+
+## Common Pitfalls
+
+- Good master cut, broken platform variants.
+- Support graphics clipping in vertical exports.
+- Audio loudness shifting between source and generated sections.

skills/pipelines/hybrid/edit-director.md

@@ -0,0 +1,55 @@
+# Edit Director - Hybrid Pipeline
+
+## When To Use
+
+This stage creates the layered edit logic for a source-led video with support elements. The order matters: anchor cut first, support layers second.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Source/support assets and timeline intent |
+| Playbook | Active style playbook | Typography and motion consistency |
+
+## Process
+
+### 1. Lock The Anchor Cut First
+
+The viewer should understand the story before support overlays are added. If the anchor cut is weak, support layers will not save it.
+
+### 2. Add Support In Priority Order
+
+Typical order:
+
+1. subtitles,
+2. speaker or context labels,
+3. diagrams or stat cards,
+4. optional inserts,
+5. CTA elements.
+
+### 3. Protect Readability
+
+Never stack too many support layers in one moment. If subtitles, labels, charts, and overlays collide, simplify.
+
+### 4. Use Metadata For Layering Logic
+
+Recommended metadata keys:
+
+- `anchor_cut_notes`
+- `layer_order`
+- `overlay_windows`
+- `variant_edit_rules`
+
+### 5. Quality Gate
+
+- the anchor cut works on its own,
+- support layers clarify instead of distract,
+- mobile readability survives,
+- variants remain consistent.
+
+## Common Pitfalls
+
+- Trying to fix a weak cut with extra graphics.
+- Letting support layers compete with the source.
+- Building each platform variant as a separate editorial philosophy.

skills/pipelines/hybrid/executive-producer.md

@@ -0,0 +1,129 @@
+# Executive Producer — Hybrid Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a hybrid video that combines source footage with designed or generated support assets. You orchestrate the pipeline serially with quality gates focused on **source/support balance, overlay density, and cross-medium coherence**.
+
+**No pre-production stages.** The user provides direction and source material. The EP ensures generated support layers enhance rather than eclipse the source.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/hybrid.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: hybrid
+  playbook: <selected>
+  target_duration_seconds: <from brief>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Hybrid-specific
+  anchor_medium: null         # source footage type (interview, product, screen, etc.)
+  support_layers: []          # planned support types (diagrams, overlays, graphics, etc.)
+  source_to_support_ratio: null  # target balance (e.g., 70/30 source/support)
+
+  artifacts:
+    idea: null
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Anchor medium clarity
+  - Is the anchor medium explicitly identified?
+  - Are support layers justified (filling real gaps, not decorating)?
+  - Is the source inventory realistic?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Source/support beat separation
+  - Are source-led and support-led beats clearly separated?
+  - Does the script avoid relying on unsupported assets?
+  - Is narration/dialogue plan realistic?
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Source primacy
+  - Does source footage remain visually primary where intended?
+  - Are overlay and support layers not overloading the frame?
+  - Max concurrent overlay layers: 2
+
+CHECK: Variant planning
+  - If platform variants planned: are they realistic?
+  - Do aspect-ratio variants maintain readability?
+```
+
+### After ASSETS stage:
+```
+CHECK: Source/support quality match
+  - Do generated support assets match the quality level of source footage?
+  - Are shared template assets reused across scenes?
+  - Budget gate: 90% threshold warning
+```
+
+### After EDIT stage:
+```
+CHECK: Anchor-cut coherence
+  - Is the anchor cut coherent BEFORE support layers are added?
+  - Do support visuals clarify rather than distract?
+  - Is variant logic consistent across deliverables?
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe: duration, resolution, codec
+  - Source and support layers remain balanced in the final render
+  - Audio stays coherent across footage and generated elements
+  - Aspect-ratio variants preserve readability
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Anchor medium, support justification | Revise |
+| G2 | script | Source/support separation, narration plan | Revise |
+| G3 | scene_plan | Source primacy, overlay density, variants | Revise |
+| G4 | assets | Quality match, reuse, budget | Revise |
+| G5 | edit | Anchor-cut coherence, support clarity | Revise |
+| G6 | compose | Balance, variants, audio coherence | Revise or send-back |
+| G7 | publish | Metadata, source-mix labeling | Revise |
+| FINAL | all | Source/support balance, readability | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $2) |
+| Max total wall-time | 12 minutes |
+
+## Common Pitfalls
+
+- **Support eclipsing source**: Generated graphics should not dominate. Source footage is the anchor.
+- **Overlay overload**: Max 2 concurrent overlay layers. More creates visual noise.
+- **Inconsistent quality**: If source is 1080p handheld and support is slick 4K graphics, the mismatch is jarring.
+- **Ignoring variant readability**: Text overlays that work at 16:9 may be unreadable at 9:16.

skills/pipelines/hybrid/idea-director.md

@@ -0,0 +1,73 @@
+# Idea Director - Hybrid Pipeline
+
+## When To Use
+
+Use this pipeline when the project combines real source media with support visuals: interviews plus diagrams, footage plus overlays, screen recording plus branded graphics, or source-led edits with generated inserts.
+
+Hybrid is not a catch-all. Your first job is to define what stays primary.
+
+## Reference Inputs
+
+- `docs/hybrid-video-best-practices.md`
+- `skills/creative/storytelling.md`
+- `skills/creative/video-editing.md`
+
+## Process
+
+### 1. Choose The Anchor Medium
+
+Pick the storytelling anchor:
+
+- `talking_head`
+- `broll_footage`
+- `screen_recording`
+- `still_sequence`
+- `narration_led_graphics`
+
+### 2. Define Support Layers
+
+Possible support layers:
+
+- subtitles,
+- diagrams,
+- code visuals,
+- stat cards,
+- generated inserts,
+- narration,
+- music.
+
+Each support layer should solve a specific problem, not just decorate the timeline.
+
+### 3. Decide The Deliverable Mix
+
+Common outputs:
+
+- hero cut,
+- vertical cutdown,
+- square cutdown,
+- chaptered version,
+- ad variant.
+
+### 4. Build The Brief
+
+Recommended metadata keys:
+
+- `anchor_medium`
+- `source_inventory`
+- `support_layers`
+- `deliverable_mix`
+- `missing_capabilities`
+- `fallback_policy`
+
+### 5. Quality Gate
+
+- the anchor medium is explicit,
+- support layers are justified,
+- the deliverable mix fits the source inventory,
+- missing capabilities are surfaced early.
+
+## Common Pitfalls
+
+- Calling everything hybrid without defining a primary medium.
+- Planning support layers before understanding the source.
+- Treating optional generated inserts as guaranteed.

skills/pipelines/hybrid/publish-director.md

@@ -0,0 +1,50 @@
+# Publish Director - Hybrid Pipeline
+
+## When To Use
+
+Package the hybrid outputs so the hero cut and its derivatives stay organized and the source/support mix remains clear.
+
+## Prerequisites
+
+| 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 hybrid framing |
+| Playbook | Active style playbook | Tone consistency |
+
+## Process
+
+### 1. Distinguish Master And Variants
+
+Group outputs as:
+
+- master cut,
+- short-form derivatives,
+- format variants,
+- chaptered or contextual variants.
+
+### 2. Preserve Source Truth In Packaging
+
+If the project uses interview footage, screen recording, or product footage as its anchor, the metadata should reflect that instead of packaging it like a pure generated piece.
+
+### 3. Store Cross-Output Notes
+
+Recommended metadata keys:
+
+- `master_output`
+- `derivative_outputs`
+- `source_mix_notes`
+- `platform_copy_map`
+
+### 4. Quality Gate
+
+- master and variants are clearly labeled,
+- metadata matches the true source mix,
+- export folders are organized by purpose,
+- the package is ready to use without manual cleanup.
+
+## Common Pitfalls
+
+- Hiding which output is the hero cut.
+- Packaging a source-led project like a generic generated asset.
+- Losing platform-specific copy and labeling across variants.

skills/pipelines/hybrid/scene-director.md

@@ -0,0 +1,62 @@
+# Scene Director - Hybrid Pipeline
+
+## When To Use
+
+You are translating the hybrid structure into a visual system that keeps the source visible and the support layers under control.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Hybrid structure and source truth |
+| Tools | `frame_sampler`, `scene_detect` | Optional source inspection |
+| Playbook | Active style playbook | Layout consistency |
+
+## Process
+
+### 1. Keep The Anchor Medium Visible
+
+If the piece is source-led, the source must remain visually primary in the scene plan. Do not hide the anchor behind constant overlays.
+
+### 2. Reserve Support For Clear Jobs
+
+Use support scenes for:
+
+- chapter transitions,
+- clarifying diagrams,
+- stat emphasis,
+- CTA or summary moments,
+- gap-filling inserts.
+
+### 3. Plan Variant Safety
+
+If the project needs multiple aspect ratios, define where:
+
+- subtitles live,
+- speaker labels live,
+- chart or code safe zones live,
+- crop-sensitive source media becomes unsafe.
+
+### 4. Use Metadata For Balance Rules
+
+Recommended metadata keys:
+
+- `anchor_rules`
+- `support_rules`
+- `safe_zones`
+- `variant_rules`
+- `overlay_density_limits`
+
+### 5. Quality Gate
+
+- the anchor medium stays primary where intended,
+- support layers are limited and purposeful,
+- aspect-ratio planning is explicit,
+- no scene relies on invisible future magic.
+
+## Common Pitfalls
+
+- Turning source-led scenes into overlay soup.
+- Forgetting variant-safe zones until compose.
+- Using generated inserts for every transition.

skills/pipelines/hybrid/script-director.md

@@ -0,0 +1,59 @@
+# Script Director - Hybrid Pipeline
+
+## When To Use
+
+This stage maps the story across source-led beats and support-led beats. You are deciding where the source carries the message and where support assets clarify it.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Anchor medium and deliverable mix |
+| Tools | `transcriber`, `scene_detect`, `audio_enhance` | Optional source analysis |
+
+## Process
+
+### 1. Mark Source-Led Versus Support-Led Beats
+
+For each section, state whether it is:
+
+- carried by source dialogue or footage,
+- carried by narration,
+- carried by diagrams or overlays,
+- carried by text only.
+
+### 2. Use Source Speech When It Is Better Than Rewriting
+
+If the supplied footage already contains strong lines, use `transcriber` and keep the authenticity. Do not replace good source material with unnecessary narration.
+
+### 3. Use Support Only To Clarify
+
+Support-led beats should answer:
+
+- what is not visible,
+- what needs summarizing,
+- what needs emphasis,
+- what changes for a different platform.
+
+### 4. Use Metadata For Structure
+
+Recommended metadata keys:
+
+- `anchor_sections`
+- `support_sections`
+- `narration_sections`
+- `required_support_assets`
+
+### 5. Quality Gate
+
+- source-led beats are clearly marked,
+- support-led beats are justified,
+- the script does not depend on fake or unavailable assets without saying so,
+- the structure can produce the intended deliverables.
+
+## Common Pitfalls
+
+- Rewriting strong source dialogue into weaker narration.
+- Adding diagrams or cards where the footage already explains the point.
+- Hiding unsupported requirements until asset generation.

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

@@ -0,0 +1,52 @@
+# Asset Director - Localization Dub Pipeline
+
+## When To Use
+
+This stage produces the localized asset kit: translated subtitle files, dubbed audio, optional lip-sync renders, and any language-specific replacements needed for the final outputs.
+
+## Prerequisites
+
+| 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"]` | Language plan and transcript package |
+| Tools | `tts_selector`, `subtitle_gen`, `lip_sync`, `audio_enhance` — `tts_selector` auto-discovers all available TTS providers from the registry | Dubbed audio, subtitle, and optional lip-sync production |
+| Playbook | Active style playbook | Subtitle and replacement-text rules |
+
+## Process
+
+### 1. Produce Subtitle Assets First
+
+Create the subtitle or caption package for each language. This gives a reviewable fallback even if dubbed-audio generation or lip sync is blocked.
+
+### 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.
+
+### 3. Treat Lip Sync As Optional
+
+Only generate lip-sync assets for scenes and languages that actually need it. If the tool path is blocked, record that and keep the dub-audio path alive.
+
+### 4. Use Metadata For Localization Truth
+
+Recommended metadata keys:
+
+- `subtitle_assets_by_language`
+- `dub_audio_assets_by_language`
+- `lip_sync_assets_by_language`
+- `voice_map`
+- `pronunciation_warnings`
+- `blocked_assets`
+
+### 5. Quality Gate
+
+- subtitle assets exist,
+- dubbed audio assets exist for planned dub outputs,
+- lip-sync remains explicitly optional,
+- every referenced file exists.
+
+## 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.

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

@@ -0,0 +1,57 @@
+# Compose Director - Localization Dub Pipeline
+
+## When To Use
+
+Render the localized outputs. The quality bar is intelligibility, timing coherence, and clear version labeling across every language package.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Locale-specific render instructions |
+| Tools | `video_compose`, `audio_mixer`, `video_trimmer`, `audio_enhance` | Final render and audio finishing |
+| Playbook | Active style playbook | Subtitle placement and output quality |
+
+## Process
+
+### 1. Render By Locale
+
+Treat each target language as its own deliverable set. Keep names and output directories explicit.
+
+### 2. Expect Timing Adjustments
+
+Allow for:
+
+- subtitle reflow,
+- dub-audio duration drift,
+- longer CTA holds,
+- optional trims or coverage sections.
+
+### 3. Verify Every Locale
+
+Record important findings in:
+
+- `render_report.verification_notes`
+- `render_report.warnings`
+- `render_report.metadata.locale_notes`
+
+Check:
+
+- intelligibility,
+- subtitle fit,
+- obvious sync drift,
+- version labeling.
+
+### 4. Quality Gate
+
+- each locale output exists,
+- the dub and subtitle timing are acceptable,
+- labels and filenames are unambiguous,
+- warnings are preserved.
+
+## Common Pitfalls
+
+- Rendering all locales as if they were timing-identical.
+- Forgetting to re-check subtitle line length after translation.
+- Naming outputs in ways that hide the locale or treatment mode.

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

@@ -0,0 +1,46 @@
+# Edit Director - Localization Dub Pipeline
+
+## When To Use
+
+Translate the scene plan and localized asset kit into concrete timeline decisions for each language output. The goal is to preserve the source structure where possible without pretending all languages land on the same timing.
+
+## Process
+
+### 1. Preserve Structure By Default
+
+Keep the original scene order and major timing unless the translated audio clearly requires extension, compression, or coverage.
+
+### 2. Apply The Chosen Dub Mode
+
+Per deliverable, decide where to:
+
+- keep original picture with new subtitles,
+- replace only the audio,
+- use lip-sync output,
+- cover mismatch with graphics or B-roll.
+
+### 3. Keep Language Variants Organized
+
+Separate timeline decisions by locale so versioning stays clear all the way into compose and publish.
+
+### 4. Use Metadata For Variant Control
+
+Recommended metadata keys:
+
+- `locale_timeline_map`
+- `timing_adjustments`
+- `coverage_sections`
+- `subtitle_strategy_by_locale`
+
+### 5. Quality Gate
+
+- language variants are explicit,
+- timing changes are recorded,
+- coverage decisions are deliberate,
+- the original structure is only changed where necessary.
+
+## Common Pitfalls
+
+- Forcing every language to match source timing exactly.
+- Mixing locale-specific notes into one ambiguous edit list.
+- Hiding sections where the dub treatment is visually weak.

skills/pipelines/localization-dub/executive-producer.md

@@ -0,0 +1,133 @@
+# Executive Producer — Localization Dub Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a localization/dubbing project. You orchestrate the pipeline serially with quality gates focused on **translation accuracy, timing preservation, lip-sync quality, and per-locale consistency**.
+
+**No pre-production stages.** Source video exists in one language. The EP manages the complexity of producing multiple language variants while preserving the original's timing and quality.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/localization-dub.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: localization-dub
+  playbook: <selected>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Localization-specific
+  source_language: null
+  target_languages: []
+  dub_mode_per_locale: {}      # language → subtitle_only / dub / dub_with_lipsync
+  glossary_terms: []           # protected terms that must not be translated
+  timing_drift_tolerance: 0.5  # seconds
+
+  artifacts:
+    idea: null
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Scope definition
+  - Source and target languages explicit?
+  - Deliverable mode clear per language (subtitle / dub / dub+lipsync)?
+  - Glossary and protected terms captured?
+  - Review requirements noted?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Transcript truth
+  - Source transcript accurate and timestamped?
+  - Glossary terms preserved in translations?
+  - Translated scripts reviewable before synthesis?
+  - Duration estimates per language reasonable (some languages expand 20-30%)?
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Dub mode feasibility
+  - Is the chosen dub mode realistic per locale?
+  - Lip-sync limited to shots that can support it (front-facing, clear mouth)?
+  - Timing drift risks mapped (which languages will run long)?
+  - On-screen text replacement planned if needed?
+```
+
+### After ASSETS stage:
+```
+CHECK: Locale asset completeness
+  - Subtitle files exist for every target language?
+  - Dubbed audio generated for every dub-mode language?
+  - TTS voice quality acceptable for each language?
+  - Lip-sync applied only where planned?
+  - Budget gate: 90% threshold (localization can be expensive with many languages)
+```
+
+### After EDIT stage:
+```
+CHECK: Timing preservation
+  - Source structure preserved unless timing forces change?
+  - CTA and legal copy survive translation?
+  - Language variants organized consistently?
+  - Timing drift within tolerance per segment?
+```
+
+### After COMPOSE stage:
+```
+CHECK: Per-locale validation
+  - Each language output rendered and intelligible?
+  - Subtitle timing matches speech in each locale?
+  - Version labeling unambiguous (language code in filename)?
+  - Audio quality consistent across locales?
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Scope, languages, dub modes | Revise |
+| G2 | script | Transcript accuracy, glossary, translations | Revise |
+| G3 | scene_plan | Dub mode feasibility, timing risks | Revise |
+| G4 | assets | Locale completeness, TTS quality, budget | Revise |
+| G5 | edit | Timing preservation, structure | Revise |
+| G6 | compose | Per-locale probe, subtitle timing | Revise or send-back |
+| G7 | publish | Locale packaging, metadata | Revise |
+| FINAL | all | Translation quality, timing, lip-sync | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $3 — localization is costlier) |
+| Max total wall-time | 15 minutes |
+
+## Common Pitfalls
+
+- **Ignoring language expansion**: Some languages are 20-30% longer than English. The dubbed audio won't fit the original timing without adjustments.
+- **Lip-sync on every shot**: Only apply lip-sync to front-facing, clear-mouth shots. Side angles and distant shots don't need it.
+- **Translating protected terms**: Brand names, product names, and technical terms in the glossary must stay in the original language.
+- **Inconsistent locale labeling**: Use ISO language codes in filenames. "Spanish" is ambiguous (es-ES vs es-MX).
+- **Degrading source video**: Re-encoding the source video for each locale should preserve quality. Never downgrade resolution.

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

@@ -0,0 +1,70 @@
+# Idea Director - Localization Dub Pipeline
+
+## When To Use
+
+Use this pipeline when the user has a source video and wants translated deliverables: subtitles, dubbed audio, or localized videos in one or more target languages.
+
+Your first responsibility is to define what kind of localization is actually required, because subtitle-only, dubbed-audio, and lip-synced translation are different jobs.
+
+## Reference Inputs
+
+- `docs/localization-dubbing-best-practices.md`
+- `skills/creative/short-form.md`
+- `skills/creative/long-form.md`
+
+## Process
+
+### 1. Define The Localization Scope
+
+Capture:
+
+- source language,
+- target languages,
+- review owner,
+- whether glossary or legal review is required,
+- whether the user needs subtitles, dubbed audio, lip-sync, or a mix.
+
+### 2. Classify The Source
+
+Record the source mode:
+
+- `single_speaker`
+- `multi_speaker`
+- `voiceover_led`
+- `speaker_led_on_camera`
+
+Also record whether on-screen text or motion graphics will need manual replacement or coverage.
+
+### 3. Pick Deliverables That Match Reality
+
+Possible deliverables:
+
+- subtitle package only,
+- dubbed video without lip sync,
+- lip-synced localized video,
+- per-language export bundle.
+
+### 4. Build The Brief
+
+Recommended metadata keys:
+
+- `source_language`
+- `target_languages`
+- `deliverable_mode_map`
+- `glossary_terms`
+- `protected_terms`
+- `review_requirements`
+- `timing_risks`
+
+### 5. Quality Gate
+
+- localization scope is explicit,
+- target outputs are realistic,
+- glossary and review requirements are captured,
+- risk increases from speaker count or visible mouths are surfaced.
+
+## Common Pitfalls
+
+- Calling every translation request a dubbing request.
+- Ignoring glossary control until after audio is generated.
+- Promising lip sync on visually difficult source footage without warning.

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

@@ -0,0 +1,44 @@
+# Publish Director - Localization Dub Pipeline
+
+## When To Use
+
+Package the completed localization outputs so downstream teams can find the right video, subtitle, and metadata bundle for each language without manual cleanup.
+
+## Process
+
+### 1. Package By Locale
+
+Each language package should clearly separate:
+
+- video output,
+- subtitle files,
+- transcript or approved script copy,
+- review notes,
+- metadata.
+
+### 2. Keep Naming Precise
+
+Recommended metadata keys:
+
+- `locale`
+- `language_name`
+- `deliverable_mode`
+- `subtitle_included`
+- `review_owner`
+
+### 3. Preserve Review Context
+
+If a language output has pronunciation caveats, timing warnings, or missing lip sync, keep that note in the published package.
+
+### 4. Quality Gate
+
+- locale packages are clearly labeled,
+- metadata matches the actual treatment,
+- supporting text assets are present,
+- warnings and review notes are not lost.
+
+## Common Pitfalls
+
+- Shipping localized videos without the matching subtitle or transcript files.
+- Mixing audio-dub and subtitle-only variants under the same generic filename.
+- Removing the QA notes that explain known issues.

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

@@ -0,0 +1,65 @@
+# Scene Director - Localization Dub Pipeline
+
+## When To Use
+
+Plan how each localized deliverable will handle timing, visible speech, subtitles, and on-screen text. This is where the pipeline decides whether to preserve the original cut, cover mouth-visible sections, or attempt lip sync.
+
+## Reference Inputs
+
+- `docs/localization-dubbing-best-practices.md`
+- `skills/creative/video-editing.md`
+
+## Process
+
+### 1. Choose The Dub Mode Per Deliverable
+
+Use one of:
+
+- `subtitle_only`
+- `dub_audio_only`
+- `lip_synced`
+- `hybrid_covered`
+
+`hybrid_covered` means using B-roll, graphics, or text coverage during sections where visible mouth mismatch would be distracting.
+
+### 2. Map Timing Risk
+
+Identify scenes likely to drift because of:
+
+- fast speech,
+- dense legal copy,
+- multiple speakers,
+- fast cuts,
+- visible close-up mouths.
+
+### 3. Note On-Screen Language Dependencies
+
+Record scenes that contain:
+
+- UI text,
+- lower thirds,
+- title cards,
+- baked-in subtitles,
+- charts or labels that may need replacement or coverage.
+
+### 4. Use Metadata For Variant Planning
+
+Recommended metadata keys:
+
+- `dub_mode_map`
+- `timing_risk_map`
+- `on_screen_text_replacement_map`
+- `language_variant_notes`
+
+### 5. Quality Gate
+
+- every deliverable has a defined localization treatment,
+- timing risks are mapped,
+- lip-sync usage is selective,
+- text replacement needs are not hidden.
+
+## Common Pitfalls
+
+- Assuming dubbed audio will fit the source timing exactly.
+- Choosing lip sync for every shot instead of only the shots that justify it.
+- Forgetting about baked-in text until compose time.

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

@@ -0,0 +1,54 @@
+# Script Director - Localization Dub Pipeline
+
+## When To Use
+
+Turn the approved localization brief into a transcript-backed, reviewable script package for every target language. This stage should create text truth before any dubbing audio is generated.
+
+## Reference Inputs
+
+- `docs/localization-dubbing-best-practices.md`
+- `skills/creative/storytelling.md`
+
+## Process
+
+### 1. Build Source Transcript Truth
+
+Start with the source transcript and fix obvious errors in:
+
+- names,
+- terminology,
+- speaker allocation,
+- numbers,
+- CTA phrasing.
+
+### 2. Produce Reviewable Target Copy
+
+For each target language, generate text that can be reviewed before synthesis. Record where terms should remain unchanged.
+
+### 3. Preserve Structure Where Practical
+
+Keep section timing and sequence aligned to the source unless the translation clearly needs a different pacing strategy.
+
+### 4. Use Metadata For Localization Control
+
+Recommended metadata keys:
+
+- `source_transcript_status`
+- `target_language_sections`
+- `glossary_terms`
+- `protected_terms`
+- `pronunciation_notes`
+- `review_status_by_language`
+
+### 5. Quality Gate
+
+- the source transcript is strong enough to trust,
+- target-language copy exists for every planned deliverable,
+- glossary terms are preserved,
+- the script package can be reviewed before audio generation.
+
+## Common Pitfalls
+
+- Generating audio from an unreviewed transcript.
+- Letting product names drift across languages.
+- Treating translation text as final timing without acknowledging length drift.

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

@@ -0,0 +1,65 @@
+# Asset Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+This stage builds the reusable kit for podcast-derived video assets: subtitles, speaker cards, quote cards, optional topic art, and optional music support.
+
+## Prerequisites
+
+| 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"]` | Deliverable plan and transcript truth |
+| Tools | `subtitle_gen`, `image_selector`, `diagram_gen`, `music_gen`, `audio_enhance` | Asset generation |
+| Playbook | Active style playbook | Brand consistency |
+
+## Process
+
+### 1. Start With Mandatory Assets
+
+Highest priority:
+
+- subtitles for every clip,
+- clean audio where needed,
+- speaker attribution assets if multiple speakers appear,
+- quote-card templates for quote-led outputs.
+
+### 2. Treat Topic Graphics As Optional
+
+Generated graphics should support the batch, not dominate it. Use them only when:
+
+- the topic truly benefits from a clarifying image,
+- the episode companion needs chapter separation,
+- the budget can support consistent outputs.
+
+### 3. Use Templates, Not Reinvention
+
+Prefer reusable templates for:
+
+- speaker cards,
+- quote cards,
+- end cards,
+- brand containers.
+
+### 4. Store Rich Asset Truth In Metadata
+
+Recommended metadata keys:
+
+- `speaker_assets`
+- `subtitle_assets`
+- `quote_card_assets`
+- `topic_graphics`
+- `music_assets`
+
+### 5. Quality Gate
+
+- all clips have subtitle assets,
+- speaker identity is visually consistent,
+- quote-card text remains mobile-readable,
+- optional generated art stays within budget and style constraints.
+
+## 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.

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

@@ -0,0 +1,63 @@
+# Compose Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+Render the podcast-derived outputs with audio fidelity as the top priority. The visuals need to support the speech, not compete with it.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | Output plans and asset paths |
+| Tools | `video_compose`, `audio_mixer` | Rendering and mix control |
+| Playbook | Active style playbook | Brand consistency |
+
+## Process
+
+### 1. Render Highest-Value Outputs First
+
+Priority order:
+
+1. short highlight clips
+2. quote-led clips
+3. optional long-form companion video
+
+This keeps the most publishable assets available first.
+
+### 2. Preserve Audio Quality
+
+- avoid unnecessary re-encoding,
+- keep speech intelligible and stable,
+- use music sparingly and only when it does not compete,
+- verify subtitle sync after render.
+
+### 3. Respect Platform Shapes
+
+- `9:16` for short-form social
+- `1:1` for quote-led or feed-safe clips
+- `16:9` for long-form YouTube companion output
+
+### 4. Verify Every Deliverable
+
+- correct duration,
+- correct aspect ratio,
+- readable subtitles,
+- accurate speaker attribution,
+- stable audio,
+- consistent brand treatment.
+
+### 5. Use Render Report Metadata
+
+Recommended metadata keys:
+
+- `deliverable_groups`
+- `audio_notes`
+- `subtitle_checks`
+- `failed_outputs`
+
+## Common Pitfalls
+
+- Letting visual treatments degrade audio quality.
+- Rendering the full companion first and delaying the clips that matter most.
+- Forgetting that a simple, readable clip beats a technically elaborate but confusing one.

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

@@ -0,0 +1,60 @@
+# Edit Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+This stage creates the actual timeline logic for short clips and any optional full-episode companion asset. The audio remains the primary content.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, layouts, transcript timing |
+| Playbook | Active style playbook | Motion and subtitle rules |
+
+## Process
+
+### 1. Build Clip Timelines Fast
+
+For short-form clips:
+
+- open on the hook,
+- start captions immediately,
+- make speaker attribution obvious,
+- let the ending land cleanly.
+
+### 2. Match The Edit To The Treatment
+
+- source-video clips should emphasize speaker framing and reactions,
+- audiogram clips should emphasize captions, speaker identity, and pacing,
+- quote-led clips should preserve enough reading time after the line lands.
+
+### 3. Keep Full-Episode Companion Simple
+
+If producing one:
+
+- use chapter cards,
+- use limited recurring visual systems,
+- do not force constant visual novelty if the assets are not there.
+
+### 4. Use Metadata For Richer Timeline Notes
+
+Recommended metadata keys:
+
+- `clip_timelines`
+- `quote_hold_times`
+- `speaker_change_markers`
+- `chapter_card_windows`
+
+### 5. Quality Gate
+
+- every short clip hooks quickly,
+- captions and attribution are present,
+- quote-led clips hold long enough to read,
+- the long-form companion stays editorially honest and technically feasible.
+
+## Common Pitfalls
+
+- Building generic audiograms that ignore who is speaking.
+- Ending quote clips as soon as the audio ends, before the text can be read.
+- Turning a long-form companion into a weak imitation of a fully produced video podcast.

skills/pipelines/podcast-repurpose/executive-producer.md

@@ -0,0 +1,135 @@
+# Executive Producer — Podcast Repurpose Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a podcast repurpose project. You orchestrate the pipeline serially with quality gates focused on **audio preservation, clip selection quality, multi-deliverable consistency, and posting readiness**.
+
+**No pre-production stages.** Source audio/video exists. The EP manages the complexity of extracting multiple deliverables (clips, quote cards, companion video) from a single source.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/podcast-repurpose.yaml` | Stage definitions |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: podcast-repurpose
+  playbook: <selected>
+  budget_total_usd: <configured>
+  budget_spent_usd: 0.0
+
+  # Podcast-specific
+  source_format: null          # solo / interview / panel
+  deliverable_types: []        # audiogram_clips / quote_clips / companion_video
+  clip_count_target: 0
+  speaker_count: 0
+
+  artifacts:
+    idea: null
+    script: null
+    scene_plan: null
+    assets: null
+    edit: null
+    compose: null
+    publish: null
+
+  revision_counts: {}
+  issues_log: []
+```
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Source assessment
+  - Source podcast format identified (solo, interview, panel)?
+  - Output types specified and realistic for source length?
+  - Clip count target achievable given source duration?
+```
+
+### After SCRIPT stage:
+```
+CHECK: Transcript quality
+  - Full episode transcribed with accurate timestamps?
+  - Speaker diarization present if multi-speaker?
+  - Highlight segments and quotable moments identified?
+  - At least N candidate clips where N >= clip_count_target?
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Clip standalone quality
+  - Does each planned clip make sense without episode context?
+  - Does each clip have a strong opening hook?
+  - Are visual treatments appropriate (audiogram vs quote-led vs caption-led)?
+
+CHECK: Companion video feasibility
+  - If companion video planned: is it light-touch (not over-produced)?
+  - Does chapter structure align with topic transitions?
+```
+
+### After ASSETS stage:
+```
+CHECK: Audio preservation
+  - Original podcast audio quality preserved (no degradation)?
+  - Speaker-specific assets (photos, name cards) consistent?
+  - Subtitles generated for all deliverables?
+  - Budget gate: 90% threshold warning
+```
+
+### After EDIT stage:
+```
+CHECK: Clip openings
+  - Each clip opens with its hook within first 3 seconds
+  - Attribution (show name, speaker) present but not slow
+  - Quote cards and captions timed correctly
+
+CHECK: Deliverable consistency
+  - Visual style consistent across all clips
+  - Audio levels consistent across all clips
+```
+
+### After COMPOSE stage:
+```
+CHECK: Multi-deliverable validation
+  - All planned deliverables rendered (clips + companion if planned)?
+  - Each clip meets platform specs (resolution, aspect ratio)?
+  - Audio quality preserved from original podcast?
+  - Waveform/motion treatments correct per layout?
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Source format, deliverable types | Revise |
+| G2 | script | Transcript quality, highlights | Revise |
+| G3 | scene_plan | Clip quality, companion feasibility | Revise |
+| G4 | assets | Audio preservation, subtitles, budget | Revise |
+| G5 | edit | Clip hooks, deliverable consistency | Revise |
+| G6 | compose | Multi-deliverable probe, audio quality | Revise or send-back |
+| G7 | publish | Per-clip metadata, posting schedule | Revise |
+| FINAL | all | Audio quality, clip selection, consistency | Send-back |
+
+## Execution Limits
+
+| Limit | Value |
+|-------|-------|
+| Max revisions per stage | 3 |
+| Max send-backs per stage pair | 1 |
+| Max total send-backs | 3 |
+| Max total budget | Configurable (default $1) |
+| Max total wall-time | 12 minutes |
+
+## Common Pitfalls
+
+- **Degrading source audio**: The podcast audio is the product. Never re-encode at lower quality.
+- **Context-dependent clips**: Every clip must stand alone. Test: would a stranger understand this clip?
+- **Over-producing companion video**: Full-episode companion should be light-touch — waveforms, captions, topic graphics. Not a feature film.
+- **Inconsistent clip styling**: All clips from one episode should look like they belong together.

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

@@ -0,0 +1,86 @@
+# Idea Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+Use this pipeline when the source is a podcast episode, either audio-only or video podcast, and the user wants clips, social assets, or a companion long-form video treatment.
+
+Your first responsibility is to decide what is feasible from the source that actually exists.
+
+## Reference Inputs
+
+- `docs/podcast-repurposing-best-practices.md`
+- `skills/creative/short-form.md`
+- `skills/creative/long-form.md`
+
+## Process
+
+### 1. Classify The Source
+
+Capture the source mode:
+
+- `audio_only`
+- `video_podcast`
+- `hybrid` (audio plus stills, cover art, guest photos)
+
+Also capture the conversational format:
+
+- solo
+- interview
+- panel
+- narrative / produced show
+
+### 2. Choose Deliverables That Match Reality
+
+Default deliverables should be feasible with the source and tools on hand.
+
+Safe options:
+
+- short-form highlight clips,
+- audiogram or caption-led clips,
+- quote-led clips,
+- one optional full-episode companion layout.
+
+Do not assume a high-production full-episode YouTube treatment unless the source video, branding assets, and optional imagery actually exist.
+
+### 3. Set A Sensible Deliverable Mix
+
+Typical starting point:
+
+- `3-5` highlight clips
+- `1-3` quote-led assets if the episode has strong one-liners
+- optional long-form companion if the source justifies it
+
+### 4. Respect Platform Differences
+
+- `9:16` for Shorts, Reels, TikTok
+- `1:1` for LinkedIn and safer feed repurposing
+- `16:9` for YouTube companion video
+
+If the source is audio-only, make that explicit in the brief. Downstream stages should not plan speaker-framed video that does not exist.
+
+### 5. Build The Brief
+
+Use `brief.metadata` for the richer podcast-specific contract:
+
+- `source_mode`
+- `show_name`
+- `episode_title`
+- `episode_number`
+- `speakers`
+- `conversation_format`
+- `deliverable_mix`
+- `brand_assets_available`
+- `full_episode_companion_feasible`
+
+### 6. Quality Gate
+
+- the deliverable mix matches the actual source,
+- clip counts are realistic for the episode length,
+- the brief states whether visuals will be source-led, quote-led, or audiogram-led,
+- long-form ambitions are scaled to the available assets.
+
+## Common Pitfalls
+
+- Treating audio-only and video-podcast sources as the same production problem.
+- Planning too many deliverables from a weak episode.
+- Promising a rich full-episode visual treatment without the assets to support it.

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

@@ -0,0 +1,61 @@
+# Publish Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+Package podcast-derived clips and companion assets so that every short-form piece points back to the episode instead of drifting as an isolated fragment.
+
+## Prerequisites
+
+| 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"]` | Outputs, source truth, chapters |
+| Playbook | Active style playbook | Brand voice |
+
+## Process
+
+### 1. Link Every Clip Back To The Episode
+
+Each short-form asset should reference:
+
+- show name,
+- episode title or number,
+- guest name where relevant,
+- full episode destination.
+
+### 2. Tailor The Copy
+
+- Shorts / Reels / TikTok: hook-led and concise
+- LinkedIn: insight-led and more contextual
+- YouTube companion: chapter-rich and search-friendly
+
+### 3. Sequence The Release
+
+Recommended order:
+
+1. strongest announcement clip
+2. next-best insight clip
+3. quote-led or guest-led follow-ups
+4. remaining supporting clips
+
+### 4. Store Cross-Linking Truth In Metadata
+
+Recommended metadata keys:
+
+- `episode_reference`
+- `guest_tags`
+- `posting_schedule`
+- `clip_to_episode_map`
+
+### 5. Quality Gate
+
+- every clip points back to the episode,
+- guest attribution is correct,
+- copy matches the platform,
+- the release order reflects actual clip strength.
+
+## Common Pitfalls
+
+- Publishing clips without clear episode references.
+- Forgetting to tag or mention the guest when that audience matters.
+- Reusing one caption style across every platform.

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

@@ -0,0 +1,70 @@
+# Scene Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+You are deciding how each podcast deliverable should look based on the actual source mode. This is where you prevent "fake richness" and choose honest, effective treatments.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Highlight set and source truth |
+| Tools | `frame_sampler` | Optional visual inspection for video-podcast sources |
+| Playbook | Active style playbook | Brand consistency |
+
+## Process
+
+### 1. Pick The Right Treatment Per Deliverable
+
+Prefer a source-faithful hierarchy:
+
+- if video podcast footage exists, use speaker-led scenes first,
+- if only audio exists, use audiogram or quote-led layouts,
+- if branding assets are limited, keep the visual system simple and repeatable.
+
+### 2. Avoid Pretend Complexity
+
+Do not plan a full episode with endless generated topic art unless the budget and tools support it. A clean branded companion layout is better than a noisy, underpowered pseudo-production.
+
+### 3. Define Scene Families
+
+Useful schema scene types:
+
+- `talking_head` for source video speaker shots
+- `text_card` for quote cards and chapter cards
+- `generated` for optional topic art
+- `diagram` for the rare cases where the discussion needs a graphic
+- `transition` for chapter moves
+
+### 4. Use Metadata For Layout Strategy
+
+Recommended `scene_plan.metadata` keys:
+
+- `deliverable_layouts`
+- `speaker_card_rules`
+- `quote_card_rules`
+- `audiogram_rules`
+- `full_episode_companion_rules`
+
+### 5. Plan Safe Zones And Attribution
+
+Every layout should clearly preserve:
+
+- speaker attribution,
+- subtitle zone,
+- show branding,
+- CTA or episode reference area if needed.
+
+### 6. Quality Gate
+
+- each deliverable has a treatment that matches the actual source,
+- source video is used when it exists instead of being hidden behind generic graphics,
+- audio-only assets remain visually simple and readable,
+- long-form companion visuals are achievable.
+
+## Common Pitfalls
+
+- Planning speaker-centric layouts for audio-only episodes.
+- Turning every clip into the same waveform-plus-logo composition.
+- Using generated graphics to cover weak editorial choices.

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

@@ -0,0 +1,70 @@
+# Script Director - Podcast Repurpose Pipeline
+
+## When To Use
+
+This stage creates the transcript truth, speaker attribution, highlight set, and chapter structure that every later stage depends on.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Deliverable mix and source truth |
+| Tools | `transcriber`, `audio_enhance` | Diarized transcript and cleanup |
+
+## Process
+
+### 1. Protect Transcript Quality
+
+If the source audio is weak, use `audio_enhance` before or alongside transcription. Speaker diarization quality directly affects quote attribution and clip quality.
+
+### 2. Produce A Speaker-Aware Transcript
+
+Diarization is not optional for multi-speaker episodes. Verify speaker mapping early and store the richer diarization detail in `script.metadata`.
+
+Recommended metadata keys:
+
+- `speaker_map`
+- `transcript_path`
+- `chapter_candidates`
+- `highlight_candidates`
+- `rejected_highlights`
+
+### 3. Rank Highlight Moments
+
+Use the episode transcript to find:
+
+- concise insights,
+- surprising claims,
+- emotional peaks,
+- debates,
+- practical advice,
+- memorable phrasing.
+
+Every highlight should be evaluated for:
+
+- standalone clarity,
+- hook strength,
+- attribution confidence,
+- platform fit.
+
+### 4. Build Chapters For Long-Form Packaging
+
+If the user wants a full-episode companion asset, identify the topic shifts now. These become chapter markers and later visual transition points.
+
+### 5. Keep The Schema Clean
+
+Use `sections[]` for the structured production-facing segments and put the richer highlight inventory in metadata.
+
+### 6. Quality Gate
+
+- speaker attribution is trustworthy,
+- the highlight set is strong enough for the requested deliverables,
+- weak clips are rejected instead of padded,
+- chapter markers cover the long-form conversation cleanly.
+
+## Common Pitfalls
+
+- Treating diarization errors as minor when they change who said the quote.
+- Selecting clips that need too much earlier context.
+- Overfitting the batch to one section of the episode.

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

@@ -0,0 +1,109 @@
+# Asset Director - Screen Demo Pipeline
+
+## When To Use
+
+This stage produces the minimal but high-leverage assets that make a screen demo easier to follow: subtitles, audio cleanup, reusable overlays, masks, and optional light-weight support cards.
+
+## Prerequisites
+
+| 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 |
+| Tools | `subtitle_gen`, `audio_enhance`, `tts_selector`, `image_selector`, `diagram_gen` — selectors auto-discover all available providers from the registry | Generation capabilities |
+| Playbook | Active style playbook | Typography and overlay styling |
+
+## Process
+
+### 1. Prioritize Utility Over Decoration
+
+Screen demos do not need a large asset pile. They need the right few assets:
+
+- mandatory: subtitles
+- usually mandatory: cleaned primary audio
+- usually helpful: reusable highlight box, arrow, step label, blur mask kit
+- optional: one intro card, one outro card, sparse diagram overlays
+- optional only if preflight allows it: generated narration for silent recordings
+
+### 2. Generate Subtitles First
+
+Rules:
+
+- high contrast over unknown UI backgrounds,
+- never cover the text the viewer needs to read,
+- prefer phrase-level chunks unless word-by-word highlighting materially helps,
+- prepare position override notes in `asset_manifest.metadata.subtitle_zones`.
+
+### 3. Build A Reusable Overlay Kit
+
+Do not generate bespoke assets for every click. Build a small shared kit:
+
+- `highlight_box_primary`
+- `arrow_primary`
+- `step_label_primary`
+- `keystroke_badge_primary`
+- `blur_mask_template`
+
+These should be reusable across scenes, with timing and placement handled downstream.
+
+### 4. Clean Or Generate Audio Pragmatically
+
+Goals:
+
+- remove distracting keyboard and room noise,
+- normalize speech,
+- preserve timing,
+- do not over-process into robotic audio.
+
+If the recording is silent:
+
+- only generate narration if TTS passed preflight,
+- otherwise keep the asset plan text-led and note the limitation in metadata.
+
+### 5. Only Generate Supplementary Visuals When They Earn It
+
+Use `image_selector` or `diagram_gen` only for:
+
+- a short opening card,
+- a step transition card,
+- a simple diagram that clarifies a hidden process,
+- an outro card.
+
+Do not create decorative artwork for a workflow the screen already explains.
+
+### 6. Build The Asset Manifest Cleanly
+
+Every asset must have a valid schema type and `scene_id`.
+
+Use `asset_manifest.metadata` for details like:
+
+- `subtitle_zones`
+- `overlay_kit`
+- `audio_settings`
+- `narration_mode`
+- `sensitive_regions`
+
+### 7. Quality Gate
+
+**Existence check:**
+- [ ] Subtitle file exists at declared path and parses without errors
+- [ ] Cleaned audio file exists and has the expected duration
+- [ ] Reusable overlay kit exists and covers planned callout types
+- [ ] All supplementary visuals exist at declared paths
+
+**Timing check:**
+- [ ] Subtitle timestamps align with script section timestamps
+- [ ] If narration was generated, timing matches section duration closely enough for editing
+
+**Quality check:**
+- [ ] Subtitles are readable at output resolution
+- [ ] Cleaned audio has no remaining distracting noise
+- [ ] Callout colors have sufficient contrast
+- [ ] Blur masks fully cover the sensitive content
+
+## 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.

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

@@ -0,0 +1,86 @@
+# Compose Director - Screen Demo Pipeline
+
+## When To Use
+
+Render the final screen-demo outputs. The quality bar is simple: the UI must be readable, the pacing must feel intentional, and the result must match the planned platform shapes.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | What to render |
+| Tools | `video_compose`, `audio_mixer`, `video_trimmer` | Rendering capabilities |
+| Playbook | Active style playbook | Quality targets |
+
+## Process
+
+### 1. Render For Legibility First
+
+Prefer the simplest reliable render chain:
+
+- trim and speed-adjust source footage,
+- compose overlays and subtitles,
+- mix audio only as much as needed,
+- encode at a bitrate suitable for text-heavy content.
+
+### 2. Choose Output Shapes Pragmatically
+
+| Platform | Aspect Ratio | Resolution | Notes |
+|----------|--------------|------------|-------|
+| YouTube / docs | `16:9` | 1920x1080 or higher | safest default for dense UI |
+| LinkedIn feed | `1:1` | 1080x1080 | good compromise when vertical is too tight |
+| Shorts / Reels / TikTok | `9:16` | 1080x1920 | only if crop plan is actually readable |
+
+If the source is 4K and text is tiny, keep a higher resolution when practical.
+
+### 3. Compose In The Right Order
+
+1. apply trims and speed changes,
+2. apply crop and framing strategy,
+3. place masks and overlays,
+4. burn subtitles,
+5. mix audio,
+6. encode with text-preserving settings.
+
+Use sharp scaling and avoid aggressive compression. Screen text is the first thing viewers notice when encode quality drops.
+
+### 4. Keep Audio Honest
+
+- preserve original speech clarity,
+- do not overcompress,
+- mute or simplify useless sped-up noise,
+- use music sparingly, if at all.
+
+### 5. Verify Every Output
+
+**File checks:**
+- [ ] Output file exists and is a valid MP4 container
+- [ ] Duration matches effective target within +/-5%
+- [ ] Resolution matches selected profile
+
+**Visual spot checks:**
+- [ ] Text is sharp and readable at sampled frames
+- [ ] Crop transitions are smooth enough to follow
+- [ ] Callout overlays appear and disappear cleanly
+- [ ] Blur masks fully cover sensitive data
+- [ ] No black frames or timing glitches
+- [ ] Subtitles do not sit on top of critical UI
+
+**Audio spot checks:**
+- [ ] Narration/voiceover is clear and consistent volume
+- [ ] Music, if used, is not competing with speech
+- [ ] No obvious audio glitches at speed boundaries
+- [ ] No clipping or distortion
+
+Record important findings in:
+
+- `render_report.verification_notes`
+- `render_report.warnings`
+- `render_report.metadata.variant_notes`
+
+## Common Pitfalls
+
+- Rendering `9:16` versions that are technically exported but practically unreadable.
+- Encoding screen text with generic low-bitrate social defaults.
+- Letting decorative backgrounds or padding reduce usable UI area too far.

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

@@ -0,0 +1,87 @@
+# Edit Director - Screen Demo Pipeline
+
+## When To Use
+
+This stage turns the plan into a concrete, schema-valid edit: trims, speeds, overlays, subtitles, and transitions. Keep the edit simple enough to execute with the current tooling and explicit enough that composition is predictable.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, visual plan, timing |
+| Playbook | Active style playbook | Overlay and pacing rules |
+
+## Process
+
+### 1. Start With The Smallest Clear Edit
+
+Screen demos get worse when over-edited. Build the timeline in this order:
+
+1. trim or cut dead time,
+2. apply speed changes,
+3. place overlays,
+4. set subtitle behavior,
+5. define audio behavior,
+6. capture detailed crop/ramp notes in `edit_decisions.metadata`.
+
+### 2. Keep The Schema Clean
+
+Use `cuts[]` for actual source segments and speed changes. Use `overlays[]`, `subtitles`, `music`, and `transitions` only for things the schema already models. Put screen-demo-specific detail in metadata:
+
+- `crop_keyframes`
+- `speed_plan`
+- `subtitle_position_overrides`
+- `audio_notes`
+- `variant_notes`
+
+### 3. Editing Rules
+
+- the viewer should see useful motion or result within the first seconds,
+- result moments stay at normal speed,
+- typing, installs, and waiting should be accelerated or removed,
+- no cut starts mid-word or ends before the payoff lands,
+- do not introduce more motion through editing than the scene plan asked for.
+
+### 4. Overlay Rules
+
+- hook or step label can appear immediately,
+- callouts should appear slightly before the action,
+- blur masks must be treated as critical, not optional,
+- subtitles and callouts must not compete for the same space.
+
+### 5. Audio Rules
+
+- keep primary speech clear and centered,
+- mute or greatly reduce meaningless sped-up noise,
+- only use background music if it adds value and survives ducking gracefully,
+- if narration was generated, ensure it fits the tightened timeline.
+
+### 6. Quality Gate
+
+**Timeline integrity:**
+- [ ] Cuts cover the full intended timeline
+- [ ] No accidental black gaps
+- [ ] Speed ramps don't overlap
+- [ ] Effective duration matches the brief closely
+
+**Overlay integrity:**
+- [ ] Every planned callout or mask is represented
+- [ ] No overlay collisions
+- [ ] UI-anchored overlays are documented clearly enough to position during compose
+
+**Audio integrity:**
+- [ ] Primary audio or narration covers the entire timeline
+- [ ] Speed-up segments have intentional audio treatment
+- [ ] Music, if present, will not compete with instruction
+
+**Subtitle integrity:**
+- [ ] Subtitles are present for all narrated sections
+- [ ] Position overrides protect important UI content
+- [ ] Subtitle timing still works after planned speed changes
+
+## Common Pitfalls
+
+- Overbuilding the edit with cinematic transitions the workflow does not need.
+- Letting sped-up audio become a wall of harsh clicks and typing.
+- Forgetting that crop and speed plans live in metadata, not arbitrary schema fields.

skills/pipelines/screen-demo/executive-producer.md

@@ -0,0 +1,277 @@
+# Executive Producer — Screen-Demo Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a screen-demo video. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision.
+
+**This pipeline has no pre-production stages** (no research, no proposal). Source footage already exists. The EP adds cross-stage quality gates that catch legibility, audio clarity, and pacing issues early — before the expensive compose step.
+
+## Why This Exists
+
+Screen-demo videos have specific failure modes that parallel execution misses:
+
+- Text in screen recordings becomes unreadable after crops and scaling
+- Zoom-crop regions that looked fine in planning obscure critical UI elements in practice
+- Keyboard noise and background hum survive into the final render
+- Dead time (loading screens, typing pauses) makes videos unwatchable without speed adjustments
+- Callout overlays block the very UI they're trying to highlight
+- Subtitle positioning conflicts with screen content
+
+The EP catches all of these at the earliest possible stage.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/screen-demo.yaml` | Stage definitions, review focus, success criteria |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution knowledge |
+| Schemas | All artifact schemas | Validation |
+| Playbook | Active style playbook | Quality constraints |
+| Tools | Full tool registry | Available capabilities |
+
+## Cumulative State
+
+```
+EP_STATE:
+  pipeline: screen-demo
+  playbook: <selected playbook name>
+  target_duration_seconds: <from brief or estimated from source>
+  budget_total_usd: <configured limit>
+  budget_spent_usd: 0.0
+  budget_remaining_usd: <budget_total>
+
+  # Screen-demo specific state
+  source_resolution: null       # original recording resolution
+  target_resolution: null       # output resolution
+  has_voiceover: false          # does source have narration audio?
+  has_keyboard_noise: false     # flagged during script/asset stage
+  zoom_regions: []              # crop regions from scene plan, for cross-checking
+
+  # Accumulated from each stage (7 stages)
+  artifacts:
+    idea: null          # → brief
+    script: null        # → script
+    scene_plan: null    # → scene_plan
+    assets: null        # → asset_manifest
+    edit: null          # → edit_decisions
+    compose: null       # → render_report
+    publish: null       # → publish_log
+
+  # Cross-stage tracking
+  narration_durations: {}
+  style_anchors: {}
+  revision_counts: {}
+  issues_log: []
+```
+
+## Execution Protocol
+
+### Phase 0: Initialize
+
+1. Load the pipeline manifest (`screen-demo.yaml`)
+2. Load the playbook (from user selection or default)
+3. Set budget from configuration or user input (default: $1.00 — screen-demo is typically low-cost)
+4. Initialize EP_STATE
+
+### Phase 1: Execute Stages Serially
+
+For each stage in order: `idea → script → scene_plan → assets → edit → compose → publish`
+
+```
+EXECUTE_STAGE(stage_name):
+
+  1. PREPARE
+     - Load the director skill for this stage
+     - Inject EP_STATE as context
+     - Inject any EP feedback from previous revision attempts
+
+  2. SPAWN DIRECTOR
+     - Director executes its full process
+     - Director produces an artifact
+
+  3. REVIEW
+     - Schema validation
+     - Check review_focus from pipeline manifest
+     - Check success_criteria from pipeline manifest
+     - Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
+
+  4. GATE DECISION
+     If PASS → store artifact, update tracking, continue
+     If REVISE → increment revision count, re-run with feedback (max 3)
+     If SEND_BACK(target_stage) → re-execute from target forward (max 1 per pair)
+```
+
+### Phase 2: Final Quality Assurance
+
+```
+FINAL_QA:
+  1. PROBE the output video:
+     - Duration: reasonable for the demo content?
+     - Resolution: matches target?
+     - Audio: voiceover clear? Keyboard noise removed?
+     - File: valid container, reasonable size?
+
+  2. LEGIBILITY CHECK (SCREEN-DEMO CRITICAL):
+     - Is UI text readable at the output resolution?
+     - Are zoom-crop regions showing the intended UI elements?
+     - Are callout overlays not obscuring critical content?
+
+  3. PACING CHECK:
+     - Are loading/typing pauses sped up or cut?
+     - Does the demo flow logically?
+     - Are transitions between workflow steps smooth?
+
+  4. SUBTITLE CHECK:
+     - Do subtitles not overlap with screen content?
+     - Is subtitle timing accurate to speech?
+
+  5. BUDGET RECONCILIATION:
+     - Total actual spend vs. budget
+     - Log per-stage cost breakdown
+
+  6. DECISION:
+     If all pass → APPROVE for publish
+     If legibility issues → send back to compose (re-render) or scene (replan crops)
+     If audio issues → send back to compose (re-mix)
+     If pacing issues → send back to edit (re-time)
+```
+
+## EP-Specific Cross-Stage Checks
+
+### After IDEA stage:
+```
+CHECK: Source assessment
+  - Is source footage referenced and accessible?
+  - Is target platform and duration realistic?
+  - Are callout/zoom needs identified?
+  - If no source footage: STOP — this pipeline requires source footage
+```
+
+### After SCRIPT stage:
+```
+CHECK: Transcript quality
+  - If source has voiceover: is transcript accurate and timestamped?
+  - Are key UI actions annotated with timestamps?
+  - Are workflow steps clearly segmented?
+  - Flag keyboard noise presence for asset stage
+
+CHECK: Duration estimate
+  - Estimated output duration reasonable for the content?
+  - If demo is > 5 minutes: suggest trimming or speed adjustments
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Zoom-crop feasibility
+  - For each crop region: does it capture the intended UI element?
+  - Are crop regions at least 50% of source resolution? (avoid extreme zooms that pixelate)
+  - Store zoom_regions in EP_STATE for compose verification
+
+CHECK: Callout placement
+  - Do callout overlays (arrows, highlights, masks) avoid obscuring the UI element they reference?
+  - Are callouts sparse? (max 2-3 concurrent callouts)
+
+CHECK: Pacing plan
+  - Are dead-time segments (loading, typing) flagged for speed-up or cut?
+  - Are speed changes smooth (not jarring jumps)?
+```
+
+### After ASSETS stage:
+```
+CHECK: Subtitle positioning
+  - Do subtitles avoid overlapping with key screen content?
+  - Is subtitle font readable against screen background?
+
+CHECK: Audio quality
+  - If audio_enhance was used: is keyboard noise reduced?
+  - If TTS was generated: does narration timing match screen actions?
+
+CHECK: Budget gate
+  - If budget_spent > budget_total * 0.9 and stages remain:
+      Alert and adjust remaining stages
+```
+
+### After EDIT stage:
+```
+CHECK: Timeline completeness
+  - All edit decisions reference valid source files and assets
+  - Audio ducking configured if background music added
+  - Speed adjustments are smooth (ramp, not jump)
+
+CHECK: Dead time handling
+  - Loading screens and typing pauses either cut or sped up
+  - Total dead time < 10% of output duration
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe: duration, resolution, codec, audio channels
+  - Text readability at output resolution
+  - Audio clarity — voiceover intelligible throughout
+
+CHECK: Screen sharpness (SCREEN-DEMO CRITICAL)
+  - UI text in the recording must be readable
+  - If crops caused pixelation: flag for scene plan revision
+  - Anti-aliased text must survive compression
+```
+
+## Feedback Message Templates
+
+### To Script Director:
+```
+EP FEEDBACK — Script Revision Required
+Reason: {reason}
+Specific issue: {transcript_accuracy / segmentation / timing}
+Keep: {what was good}
+Change: {what specifically needs to change}
+```
+
+### To Scene Director:
+```
+EP FEEDBACK — Scene Plan Revision Required
+Reason: {reason}
+Affected scenes: {scene_ids}
+Constraint: {crop_feasibility / callout_placement / pacing}
+Source resolution: {W}x{H} — minimum crop: {W/2}x{H/2}
+```
+
+### To Compose Director:
+```
+EP FEEDBACK — Re-render Required
+Reason: {reason}
+Specific issue: {legibility / audio / pacing}
+Expected: {what the output should look/sound like}
+Actual: {what was produced}
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Source assessment, feasibility | Revise idea |
+| G2 | script | Transcript accuracy, duration estimate | Revise script |
+| G3 | scene_plan | Crop feasibility, callout placement, pacing plan | Revise scene_plan |
+| G4 | assets | Subtitle positioning, audio quality, budget | Revise assets |
+| G5 | edit | Timeline completeness, dead time handling | Revise edit |
+| G6 | compose | Output probe, screen sharpness, audio clarity | Revise compose OR send-back |
+| G7 | publish | Metadata, chapters, export packaging | Revise publish |
+| FINAL | all | Legibility, pacing, subtitles, audio | Send-back to specific stage |
+
+## Execution Limits
+
+| Limit | Value | Rationale |
+|-------|-------|-----------|
+| Max revisions per stage | 3 | Prevent perfectionism loops |
+| Max send-backs per stage pair | 1 | Prevent ping-pong |
+| Max total send-backs | 3 | Cap total re-work |
+| Max total budget | Configurable (default $1) | Hard stop on spending |
+| Max total wall-time | 10 minutes | Screen-demo is simpler than generated pipelines |
+
+## Common Pitfalls
+
+- **Ignoring text readability**: The #1 screen-demo issue. Always verify UI text is readable after crops.
+- **Over-cropping**: Extreme zooms pixelate. Minimum crop should be 50% of source resolution.
+- **Leaving dead time**: Loading screens and typing pauses must be handled. Speed-up or cut.
+- **Callout overload**: More than 2-3 concurrent callouts creates visual chaos.
+- **Ignoring keyboard noise**: If the source has keyboard sounds, flag it early for audio cleanup.

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

@@ -0,0 +1,112 @@
+# Idea Director - Screen Demo Pipeline
+
+## When To Use
+
+Use this pipeline when the source is already a screen recording: product walkthrough, software tutorial, coding demo, browser flow, or troubleshooting capture.
+
+Your job is to turn raw capture into a clear procedural video. The main deliverable at this stage is a schema-valid `brief`, with pipeline-specific detail stored in `brief.metadata`.
+
+## Operating Principles
+
+Screen-demo best practices are consistent:
+
+- prioritize procedure over theory,
+- keep scope to one workflow or one outcome,
+- map narration to visible action,
+- plan attention guidance with restraint,
+- optimize for legibility before style.
+
+Reference docs:
+- `docs/screen-demo-best-practices.md`
+- `skills/creative/screen-recording.md`
+
+## Process
+
+### 1. Inspect The Source
+
+Use the available analysis tools before writing the brief:
+
+- `frame_sampler` for representative frames and dense samples around likely key moments
+- `scene_detect` for window switches, page changes, and major layout changes
+- `transcriber` to determine whether the recording has narration, system audio only, or silence
+
+Identify:
+
+- software and surfaces shown,
+- the single workflow being taught,
+- critical interactions: click, type, scroll, submit, result,
+- moments that obviously need zoom or highlight support,
+- dead time: installs, builds, loading, repetitive typing,
+- whether `9:16` is even feasible without losing meaning.
+
+### 2. Classify The Demo
+
+Choose one dominant archetype:
+
+- `tutorial`: step-by-step task completion
+- `feature_showcase`: show what a feature does
+- `troubleshooting`: reproduce and fix a problem
+- `walkthrough`: explain a multi-step flow across tools
+- `comparison`: compare two approaches or outcomes
+
+If the footage mixes several archetypes, pick the one that should drive pacing and packaging.
+
+### 3. Set Deliverable Intent
+
+Screen demos should stay narrow and outcome-led:
+
+- `30-60s`: quick tip or feature reveal
+- `60-120s`: focused product walkthrough or bug fix
+- `120-300s`: chaptered tutorial
+
+Default to the shortest duration that still teaches the task cleanly. Do not preserve raw duration unless the user explicitly wants training footage with minimal compression.
+
+### 4. Choose A Viable Output Shape
+
+Plan the platform around readability, not trend pressure:
+
+- use `youtube` or `linkedin` for dense desktop UI,
+- use `instagram` or `tiktok` only if the active area can survive a narrow crop,
+- prefer `1:1` or `16:9` when the interface has multiple panels or code windows.
+
+### 5. Build The Brief
+
+Use the schema fields for the concise creative contract and store the richer production detail in `metadata`.
+
+Recommended `metadata` keys:
+
+- `source_path`
+- `source_duration_seconds`
+- `source_resolution`
+- `has_voiceover`
+- `software_shown`
+- `demo_archetype`
+- `critical_moments`
+- `dead_time_segments`
+- `recommended_aspect_ratios`
+- `notes_for_scene_planner`
+
+The brief should answer:
+
+- what the viewer will learn,
+- who this is for,
+- what proof/result the video should land on,
+- what the must-show actions are,
+- which crop directions are safe.
+
+### 6. Quality Gate
+
+Before checkpointing, verify:
+
+- the workflow is narrow enough for the chosen duration,
+- the "aha" result is clearly identified,
+- the target platform matches the UI density,
+- the brief names the actual software rather than describing it vaguely,
+- the metadata gives downstream stages enough production truth.
+
+## Common Pitfalls
+
+- Treating a 7-minute recording as a 7-minute deliverable by default.
+- Choosing `9:16` for a dense desktop capture just because the user asked for Shorts.
+- Writing a concept-heavy brief when the user really needs task completion.
+- Failing to note silence; if there is no voiceover, downstream stages must know immediately.

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

@@ -0,0 +1,80 @@
+# Publish Director - Screen Demo Pipeline
+
+## When To Use
+
+Package the finished demo so the user can publish it quickly and so the metadata reflects the actual task, result, and tools involved.
+
+## Prerequisites
+
+| 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"]` | Video, brief, and sections |
+| Playbook | Active style playbook | Thumbnail and copy tone |
+
+## Process
+
+### 1. Build Searchable Metadata
+
+Screen-demo titles work best when they combine:
+
+- task,
+- tool,
+- outcome.
+
+Good patterns:
+
+- `How to deploy on Vercel from Next.js`
+- `Fix CORS in React + Express`
+- `Set up GitHub Actions for Python tests`
+
+Pull keywords from:
+
+- software names,
+- frameworks,
+- commands,
+- exact error text,
+- outcome words such as `deploy`, `fix`, `connect`, `publish`, `ship`.
+
+### 2. Use Chapter Markers As Navigation
+
+Use script sections as the basis for chapter markers and packaging bullets. A good screen-demo package makes the workflow skimmable before the user even presses play.
+
+### 3. Thumbnail Strategy
+
+If a thumbnail concept is needed, it should show:
+
+- the result state, not a generic setup screen,
+- the recognizable tool surface,
+- 2-4 words of value text.
+
+Store the concept in `publish_log.metadata.thumbnail_concepts`.
+
+### 4. Package By Platform
+
+Prepare:
+
+- video file,
+- title and description/caption,
+- chapter markers where relevant,
+- keyword list,
+- thumbnail concept notes.
+
+For developer or product-demo content, also package:
+
+- commands shown,
+- software/version mentions,
+- error terms if it is a troubleshooting demo.
+
+### 5. Quality Gate
+
+- metadata names the real tool and task,
+- chapters match the actual rendered flow,
+- export folders are clean and reusable,
+- copy is tailored to the platform instead of duplicated.
+
+## Common Pitfalls
+
+- Publishing with generic titles that omit the actual software or task.
+- Using the same caption for YouTube, LinkedIn, and short-form social.
+- Building chapter markers from the script without checking the render.

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

@@ -0,0 +1,131 @@
+# Scene Director - Screen Demo Pipeline
+
+## When To Use
+
+You are planning how the viewer's attention moves through an existing screen capture. The source video already exists; your job is to decide when to stay wide, when to crop in, and when to add minimal guidance.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Script timing and source notes |
+| Tools | `frame_sampler`, `scene_detect` | Extract reference frames and transitions |
+| Playbook | Active style playbook | Overlay style and pacing rules |
+
+## Process
+
+### 1. Plan Attention, Not Constant Motion
+
+Modern screen-demo tools converge on click-led zoom because it reduces random camera motion. Use that principle here:
+
+- zoom when the viewer truly needs help reading or locating something,
+- stay steady during comprehension,
+- zoom manually when the key event has no click anchor,
+- reset to a wider context between major steps.
+
+Use `frame_sampler` for exact reference frames around each key action and store detailed crop notes in `scene_plan.metadata`.
+
+### 2. Choose Scene Shapes
+
+Use simple scene types that match the schema:
+
+- `screen_recording` for live UI capture sections
+- `text_card` for step labels, title cards, or recap slides
+- `diagram` only when the UI alone cannot explain the concept
+- `transition` sparingly between major workflow phases
+
+### 3. Plan Crop Strategy In Metadata
+
+The schema does not have first-class zoom objects, so keep the scene descriptions concise and place the detailed crop plan in `scene_plan.metadata.crop_regions`.
+
+Recommended `crop_regions` fields:
+
+- `section_id`
+- `start_seconds`
+- `end_seconds`
+- `region`
+- `zoom_level`
+- `trigger` (`click_cluster`, `typing`, `result`, `manual_focus`)
+- `transition_duration`
+- `rationale`
+
+Useful heuristics:
+
+| UI Element | Zoom Level | Region Sizing | Notes |
+|------------|-----------|---------------|-------|
+| Terminal / code | 1.5-2.2x | keep enough surrounding context to orient the viewer |
+| Small button / icon | 2.0-3.0x | show padding so the viewer knows where it lives |
+| Modal / dialog | 1.4-2.0x | capture the full modal, not a partial crop |
+| Full-page result | 1.0-1.3x | show more context before zooming again |
+
+### 4. Plan Callouts With Restraint
+
+Document overlay needs in `required_assets` and `metadata.callout_plan`.
+
+Use only the patterns that clarify the action:
+
+- `highlight_box`
+- `arrow`
+- `step_label`
+- `keystroke_badge`
+- `blur_mask`
+
+Rules:
+
+- no more than two attention cues at once,
+- show the cue just before the action,
+- remove it quickly after the action,
+- prefer highlight or zoom; do not stack both unless readability truly demands it.
+
+### 5. Plan Speed Treatment
+
+Mark repetitive segments as either:
+
+- `speed_up`
+- `cut`
+- `realtime`
+
+Useful visual treatments for sped-up sections:
+
+- progress label,
+- small status text,
+- simple dissolve over the removed wait.
+
+Do not invent flashy transition behavior for installs, builds, or long typing stretches.
+
+### 6. Choose Aspect Ratio Per Segment
+
+If the whole project targets multiple outputs, note in metadata which scene crops are viable for:
+
+- `16:9`
+- `1:1`
+- `9:16`
+
+If a step cannot survive vertical, say so. The correct answer is sometimes to ship landscape only or create a separate simplified vertical cut.
+
+### 7. Quality Gate
+
+**Zoom coherence:**
+- [ ] motion is intentional, not constant
+- [ ] every zoom exists for legibility or orientation
+- [ ] every major section gets a wider re-establishing view
+- [ ] crops do not cut off the relevant text or control
+
+**Callout coherence:**
+- [ ] every critical action has either a crop or a callout
+- [ ] callouts do not obscure the UI
+- [ ] subtitle and callout zones do not collide
+- [ ] sensitive data has a planned mask
+
+**Pacing coherence:**
+- [ ] result moments stay at normal speed
+- [ ] waiting and repetitive typing are compressed or removed
+- [ ] the output duration still matches the brief
+
+## Common Pitfalls
+
+- Staying zoomed in so long that the viewer loses the interface map.
+- Planning vertical crops for wide UI without admitting they fail.
+- Adding highlight layers everywhere instead of choosing the single clearest cue.
+- Ignoring sensitive data revealed in seemingly minor frames.

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

@@ -0,0 +1,116 @@
+# Script Director - Screen Demo Pipeline
+
+## When To Use
+
+You are turning the inspected recording into a timestamped procedural script. Unlike explainer work, you are not inventing the flow. You are synchronizing language to actions the viewer will literally see.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifact | `state.artifacts["idea"]["brief"]` | Brief with workflow, critical moments, and source notes |
+| Tools | `transcriber`, `frame_sampler`, `audio_enhance` | Audio/transcript inspection and spot checks |
+
+## Process
+
+### 1. Decide The Script Mode
+
+Use the brief metadata to choose one of three modes:
+
+| Voiceover Status | Strategy |
+|-----------------|----------|
+| `voiced` | Transcribe, tighten, and preserve the speaker's phrasing where possible |
+| `silent` | Write text-led or optional TTS-ready narration around the actions |
+| `partial` | Transcribe the existing speech and bridge only where necessary |
+
+If the recording is silent and TTS was not available in preflight, do not pretend there will be narration later. Write the script so the video can still work with captions, hook cards, and step labels.
+
+### 2. Build The Action Map
+
+The action map is the real backbone of this stage. Use `frame_sampler` and `transcriber` together to log:
+
+- exact task boundaries,
+- clicks worth highlighting,
+- typed input worth slowing down,
+- waits worth speeding up or cutting,
+- the result moment to preserve in real time.
+
+Store detailed action information in `script.metadata.interaction_map`. Keep `sections` clean and schema-valid.
+
+Useful `interaction_map` fields:
+
+- `timestamp_seconds`
+- `action_type`
+- `target`
+- `importance`
+- `suggested_treatment` (`realtime`, `speed_up`, `cut`, `highlight`, `zoom`)
+
+### 3. Write Sections By Step
+
+Each `script.sections[]` entry should correspond to a real user step, not a thematic paragraph.
+
+Good section labels:
+
+- `Open the settings panel`
+- `Paste the API token`
+- `Run the build`
+- `Verify the live result`
+
+Every section should do three things:
+
+- say what is happening,
+- say why it matters,
+- leave clear cues for highlights, zooms, or speed changes.
+
+### 4. Keep The Narration Procedural
+
+Use the research-backed rules:
+
+- narrate intent and effect, not obvious cursor motion,
+- keep wording short and direct,
+- avoid jargon unless the target audience clearly expects it,
+- keep the action on screen synchronized with the wording,
+- preserve the speaker's natural voice if the source already has narration.
+
+### 5. Mark Pacing Decisions
+
+Use section-level notes and `metadata.speed_plan` to call out:
+
+| Speed Factor | When to Use | Example |
+|-------------|-------------|---------|
+| `0.75-1.0x` | Important click or result | Small control, key validation moment |
+| `1.5-2.0x` | routine typing or navigation | filling obvious fields |
+| `3.0-6.0x` | installs, builds, loading | dependency install, compile |
+| `cut` | no learning value | long idle wait |
+
+Do not put critical proof moments inside sped-up sections.
+
+### 6. Use Metadata For Screen-Specific Detail
+
+Recommended `script.metadata` fields:
+
+- `interaction_map`
+- `speed_plan`
+- `chapter_candidates`
+- `pronunciation_guides`
+- `callout_candidates`
+- `sections_needing_zoom`
+
+### 7. Quality Gate
+
+| Criterion | Question |
+|-----------|----------|
+| **Action coverage** | Is every critical moment from the brief annotated with a timestamp? |
+| **Narration sync** | Does each narration segment align with what's happening on screen? |
+| **Speed marking** | Are dead-time segments marked for acceleration or removal? |
+| **Enhancement density** | Are highlights reserved for true attention shifts rather than every click? |
+| **Technical accuracy** | Are all software names, commands, and UI elements named correctly? |
+| **Word economy** | Is narration concise and procedural? |
+
+## Common Pitfalls
+
+- Narrating the cursor instead of the outcome.
+- Letting spoken timing drift away from the visual action.
+- Keeping builds and loading screens in real time.
+- Writing a silent-recording script that secretly depends on unavailable TTS.

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

@@ -0,0 +1,50 @@
+# Asset Director — Talking Head Pipeline
+
+## When to Use
+
+You have a scene plan and script. Your job is to generate the supporting assets for a talking-head video: subtitles, extracted audio, and any overlay graphics.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
+| Prior artifacts | Scene plan, Script | What assets to create |
+| Tools | `subtitle_gen`, `audio_mixer`, `image_selector` (optional) | Asset generation |
+
+## Process
+
+### Step 1: Generate Subtitles
+
+Use the transcription data from the script stage to create:
+- SRT or ASS subtitle file with word-level timing
+- Style subtitles per the playbook (font, size, color, position)
+
+### Step 2: Extract and Process Audio
+
+- Extract audio track from raw footage
+- Apply noise reduction if needed (via `audio_mixer`)
+- Normalize audio levels
+
+### Step 3: Generate Overlays (Optional)
+
+If the scene plan includes overlay scenes:
+- Generate text card images
+- Generate lower third graphics
+- Create any B-roll placeholders
+
+### Step 4: Build Asset Manifest
+
+Document all generated assets with paths, types, and tool references.
+
+### Step 5: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Subtitles** | Do subtitles exist and match speech timing? |
+| **Audio** | Is audio clean and normalized? |
+| **Files** | Do all asset paths point to existing files? |
+
+### Step 6: Submit
+
+Validate the asset_manifest against the schema and persist via checkpoint.

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

@@ -0,0 +1,68 @@
+# Compose Director — Talking Head Pipeline
+
+## When to Use
+
+You have edit decisions and an asset manifest. Your job is to render the final talking-head video: apply the enhancement chain, burn subtitles, mix audio, and encode to the target profile.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
+| Prior artifacts | Edit decisions, Asset manifest | Render inputs |
+| Tools | `video_compose`, `audio_mixer` | Rendering |
+| Media profiles | `lib/media_profiles.py` | Output format |
+
+## Process
+
+### Step 1: Run Enhancement Chain
+
+Apply video enhancements in order:
+1. **Face enhancement** (if face_enhance tool available) — sharpen faces
+2. **Color grading** (if color_grade tool available) — apply a profile
+3. **Audio enhancement** (if audio_enhance tool available) — noise reduction, normalization
+
+Each step is optional — check tool availability first.
+
+### Step 2: Burn Subtitles
+
+Use `video_compose` with `burn_subtitles` operation:
+- Input: enhanced video (or raw if no enhancements)
+- Subtitle file from asset manifest
+- Style from playbook
+
+### Step 3: Mix Audio
+
+Use `audio_mixer` to:
+- Layer original audio with any background music
+- Apply ducking if music is present
+- Normalize final levels
+
+### Step 4: Final Encode
+
+Use `video_compose` with `encode` operation:
+- Apply target media profile (youtube_landscape, tiktok, etc.)
+- Two-pass encoding for quality
+
+### Step 5: Verify Output
+
+- Check file exists and is playable
+- Verify duration matches expectations
+- Check audio is present
+
+### Step 6: Build Render Report
+
+Document output: path, format, resolution, duration, file size.
+
+### Step 7: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Playability** | Does the video play without errors? |
+| **Quality** | Are enhancements applied correctly? |
+| **Audio** | Is speech clear with balanced levels? |
+| **Subtitles** | Are subtitles visible and synced? |
+
+### Step 8: Submit
+
+Validate the render_report against the schema and persist via checkpoint.

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

@@ -0,0 +1,52 @@
+# Edit Director — Talking Head Pipeline
+
+## When to Use
+
+You have a scene plan and asset manifest. Your job is to assemble the edit decision list for a talking-head video: primarily keeping the full footage with subtitle overlay and optional enhancements.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
+| Prior artifacts | Scene plan, Asset manifest, Script | Edit inputs |
+| Playbook | Active style playbook | Transition and pacing rules |
+
+## Process
+
+### Step 1: Define Primary Cut
+
+For talking-head, the primary cut is usually the full footage (or trimmed segments). Create cuts that:
+- Reference the raw footage as source
+- Use timestamps from the script sections
+- Apply any trim decisions (cut dead air, false starts)
+
+### Step 2: Configure Subtitles
+
+- Enable subtitles with playbook-compatible styling
+- Reference the subtitle asset from the manifest
+- Set position (usually bottom-center)
+
+### Step 3: Configure Audio
+
+- Set narration to the raw footage audio
+- If background music is desired, configure ducking
+- Set music volume per playbook
+
+### Step 4: Plan Enhancements
+
+If the scene plan includes overlays:
+- Add overlay cuts for text cards, lower thirds
+- Time them to match speech content
+
+### Step 5: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Coverage** | Do cuts span the full intended duration? |
+| **Subtitles** | Are subtitles enabled and styled? |
+| **Audio** | Is audio configuration complete? |
+
+### Step 6: Submit
+
+Validate the edit_decisions against the schema and persist via checkpoint.

skills/pipelines/talking-head/executive-producer.md

@@ -0,0 +1,446 @@
+# Executive Producer — Talking Head Pipeline
+
+## When to Use
+
+You are the **Executive Producer (EP)** for a talking-head video project. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision. You are the stateful brain; the directors are stateless workers.
+
+**You replace the default parallel/sequential execution model.** Instead of running all stages blindly, you exercise judgment at every gate.
+
+## Why This Exists
+
+The talking-head pipeline transforms raw footage of a person speaking into a polished, subtitled video. Without an EP:
+- Transcript errors propagate silently through all downstream stages
+- Subtitle timing drifts from speech with no feedback to correct it
+- Scene coverage gaps leave dead air in the final output
+- No A/V sync validation before the final render
+- No ability to send a single stage back without re-running everything
+- Enhancement decisions (face, color, audio) are made without context of the full picture
+
+The EP solves all of these by maintaining cumulative state and applying judgment at each gate.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Pipeline | `pipeline_defs/talking-head.yaml` | Stage definitions, review focus, success criteria |
+| Skills | All 7 director skills + `meta/reviewer` | Stage execution knowledge |
+| Schemas | All artifact schemas | Validation |
+| Playbook | `clean-professional` (or user-selected) | Quality constraints |
+| Tools | Full tool registry | Available capabilities |
+
+## Key Difference from Explainer EP
+
+The talking-head pipeline is **footage-first**, not idea-first:
+
+| Aspect | Explainer EP | Talking-Head EP |
+|--------|-------------|-----------------|
+| Source material | None — generates everything | Raw footage provided up front |
+| Script stage | Writes from scratch | Extracts from transcription |
+| Core challenge | Creative generation quality | Transcript accuracy + timing |
+| Budget model | Moderate (TTS + image gen) | Low (mostly processing, optional overlays) |
+| Duration source | Target set in proposal | Determined by raw footage length |
+| Critical sync | Narration ↔ visual duration | Subtitles ↔ speech timing |
+| Pre-production | Research + proposal (2 stages) | Idea (1 stage) — no research needed |
+
+## Cumulative State
+
+The EP maintains a running state object that flows through the entire pipeline:
+
+```
+EP_STATE:
+  pipeline: talking-head
+  playbook: <selected playbook name, default: clean-professional>
+  raw_footage_path: <path to source footage>
+  raw_footage_duration_seconds: <from ffprobe>
+  raw_footage_resolution: <from ffprobe>
+  target_duration_seconds: <from brief, may be shorter than raw>
+  budget_total_usd: <from user or default: $0.50>
+  budget_spent_usd: 0.0
+  budget_remaining_usd: <budget_total>
+
+  # Accumulated from each stage (7 stages)
+  artifacts:
+    idea: null          # → brief
+    script: null        # → script (transcript-based)
+    scene_plan: null    # → scene_plan
+    assets: null        # → asset_manifest
+    edit: null          # → edit_decisions
+    compose: null       # → render_report
+    publish: null       # → publish_log
+
+  # Transcript tracking (the core of talking-head quality)
+  transcript_segments: []        # word-level timestamped segments from transcriber
+  transcript_confidence: null    # average word confidence score
+  transcript_language: null      # detected language
+  subtitle_sync_offsets: {}      # section_id → drift_seconds (positive = subtitle late)
+
+  # Cross-stage tracking
+  total_footage_seconds: 0
+  total_edit_seconds: 0        # may differ from footage if trimmed
+  style_anchors: {}            # consistency tokens for overlays
+  revision_counts: {}          # stage_name → number of revisions
+  issues_log: []               # all issues found, with resolution status
+
+  # Enhancement tracking
+  enhancements_applied: []     # face_enhance, color_grade, audio_enhance
+  audio_profile:               # from raw footage analysis
+    has_background_noise: null
+    audio_channels: null
+    sample_rate: null
+```
+
+## Execution Protocol
+
+### Phase 0: Initialize
+
+1. Load the pipeline manifest (`talking-head.yaml`)
+2. Load the playbook (from user selection or default `clean-professional`)
+3. Set budget from configuration or user input (default: $0.50 — talking-head is mostly processing)
+4. Probe the raw footage with ffprobe: duration, resolution, fps, audio channels, codec
+5. Store footage metadata in EP_STATE
+6. Initialize EP_STATE
+
+### Phase 1: Execute Stages Serially
+
+For each stage in order: `idea → script → scene_plan → assets → edit → compose → publish`
+
+```
+EXECUTE_STAGE(stage_name):
+
+  1. PREPARE
+     - Load the director skill for this stage
+     - Inject EP_STATE as context (prior artifacts, budget remaining, style anchors)
+     - Inject any EP feedback from previous revision attempts
+
+  2. SPAWN DIRECTOR
+     - The director executes its full process (as defined in its skill MD)
+     - Director produces an artifact
+
+  3. REVIEW (EP performs this, not a separate reviewer)
+     - Schema validation against artifact schema
+     - Check review_focus items from pipeline manifest
+     - Check success_criteria from pipeline manifest
+     - Cross-check against playbook constraints
+     - Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
+
+  4. GATE DECISION
+     If PASS:
+       - Store artifact in EP_STATE
+       - Update cumulative tracking (budget, durations, etc.)
+       - Log: "[stage] PASSED — moving to next stage"
+       - Continue to next stage
+
+     If REVISE:
+       - Increment revision_counts[stage_name]
+       - If revision_counts[stage_name] >= 3:
+           - PASS WITH WARNINGS (never block forever)
+           - Log unresolved issues
+       - Else:
+           - Compose specific feedback for the director
+           - Re-run SPAWN DIRECTOR with feedback injected
+           - Re-run REVIEW
+
+     If SEND_BACK(target_stage):
+       - This is the EP's special power: send work BACK to a prior stage
+       - Only used when a downstream discovery invalidates upstream work
+       - Example: Subtitle sync check reveals transcript has wrong timestamps
+         → Send back to script director: "Re-transcribe section 3. Timestamps are off."
+       - Re-execute from target_stage forward (artifacts after target are invalidated)
+       - Max 1 send-back per stage pair (prevent infinite loops)
+```
+
+### Phase 2: Final Quality Assurance
+
+After all 7 stages complete, the EP performs a holistic review:
+
+```
+FINAL_QA:
+  1. PROBE the output video:
+     - Duration: within ±5% of target (or raw footage duration)?
+     - Resolution: matches target or raw footage resolution?
+     - Audio: speech audible throughout? No clipping? Balanced levels?
+     - File: valid container, reasonable size?
+
+  2. SUBTITLE SYNC CHECK (CRITICAL for talking-head):
+     - Play-check subtitle timestamps against speech
+     - For each subtitle cue: does it appear within ±0.3s of the spoken word?
+     - Flag any section where subtitles are visibly out of sync
+     - Tolerance: ±0.3 seconds (tighter than explainer because speech is the content)
+
+  3. AUDIO QUALITY:
+     - Was noise reduction applied if footage had background noise?
+     - Are audio levels normalized? (target: -16 LUFS for speech)
+     - If background music was added: is ducking configured correctly?
+
+  4. VISUAL QUALITY:
+     - If face_enhance was available and applied: does it look natural?
+     - If color_grade was available and applied: is it consistent?
+     - If overlays were added: do they appear at the right timestamps?
+
+  5. BUDGET RECONCILIATION:
+     - Total actual spend vs. budget
+     - Log per-stage cost breakdown
+
+  6. DECISION:
+     If all checks pass → APPROVE for publish stage
+     If issues found → Send back to the specific stage(s) that can fix them
+       - Subtitle timing → asset director (regenerate subtitles)
+       - Audio issues → compose director (remix)
+       - Visual enhancement issues → compose director (re-render)
+       - Coverage gaps → scene director (replan) or edit director (re-cut)
+       - Transcript errors → script director (re-transcribe)
+```
+
+## EP-Specific Cross-Stage Checks
+
+These checks use information accumulated across stages — something no individual director can do.
+
+### After IDEA stage:
+```
+CHECK: Footage viability
+  - Does the footage have audio? (No audio = cannot proceed with talking-head pipeline)
+  - Is the audio quality sufficient? (Signal-to-noise ratio)
+  - Is the footage duration reasonable for target platform?
+  - If duration > 3x target: flag that significant trimming is needed
+  - Note: Idea stage DOES checkpoint with user — this is the approval gate
+```
+
+### After SCRIPT stage:
+```
+CHECK: Transcript quality (CRITICAL — everything downstream depends on this)
+  - Average word confidence score (from transcriber output)
+  - If avg_confidence < 0.8:
+      REVISE: "Transcript confidence is low ({X}). Try model: large-v3 if not already used.
+      If still low, flag specific low-confidence sections for manual review."
+  - Spot-check: do timestamps increase monotonically?
+  - Spot-check: are there gaps > 2 seconds with no words? (may indicate missed speech)
+  - Store transcript_segments in EP_STATE for downstream subtitle generation
+
+CHECK: Section boundaries
+  - Do sections align with natural topic changes?
+  - Are timestamps within the raw footage duration?
+  - Any section longer than 60s? (May need splitting for better scene planning)
+```
+
+### After SCENE_PLAN stage:
+```
+CHECK: Full coverage
+  - Sum all scene durations
+  - Compare to raw footage duration (or target edit duration)
+  - Gaps > 1 second: REVISE scene_plan
+  - Overlaps: REVISE scene_plan
+
+CHECK: Enhancement feasibility
+  - For each planned enhancement (face, color, overlay):
+      Verify the required tool exists in the registry
+  - If face_enhance planned but unavailable: remove from plan, log warning
+  - If overlay images planned: verify image tools are available
+
+CHECK: Overlay alignment
+  - If overlays are planned at specific timestamps, verify those timestamps
+    fall within actual scene boundaries from the transcript
+```
+
+### After ASSETS stage:
+```
+CHECK: Subtitle sync (CRITICAL for talking-head)
+  - Compare subtitle cue timestamps to transcript word timestamps
+  - For each cue: |subtitle_start - word_start| < 0.3s
+  - Store sync offsets in EP_STATE.subtitle_sync_offsets
+  - If any offset > 0.5s: REVISE assets: "Subtitle cue {id} is {X}s off.
+    Re-generate from original transcript segments."
+
+CHECK: Audio extraction
+  - Was audio extracted from raw footage?
+  - Was noise reduction applied if needed?
+  - Are audio levels in a reasonable range?
+
+CHECK: Budget gate
+  - If budget_spent > budget_total * 0.8 and stages remain:
+      Alert: "80% budget consumed with {N} stages remaining"
+      Adjust remaining stages to skip optional enhancements
+```
+
+### After EDIT stage:
+```
+CHECK: Timeline completeness
+  - Verify edit decisions cover 0 to total_edit_duration with no gaps
+  - Verify all cut source files reference existing paths from asset_manifest
+  - Verify subtitle configuration is present and points to valid subtitle file
+
+CHECK: Trim validation
+  - If footage was trimmed (edit is shorter than raw): are the right sections kept?
+  - Do the kept sections match the scene_plan?
+  - Are transitions between cuts smooth (no jump cuts unless intentional)?
+```
+
+### After COMPOSE stage:
+```
+CHECK: Output validation
+  - ffprobe the output: duration, resolution, codec, audio channels
+  - Duration drift > 5%: investigate which stage caused it
+  - Audio missing: check audio extraction and mixing
+  - Resolution wrong: check if face_enhance or color_grade changed it
+  - Subtitles: if burn-in was requested, verify they're visible in output
+```
+
+## Feedback Message Templates
+
+When sending work back to a director, use these structured feedback messages:
+
+### To Script Director:
+```
+EP FEEDBACK — Script Revision Required
+Reason: {reason}
+Specific issue: {transcript_quality / timestamp_error / section_boundary}
+Affected sections: {section_ids}
+Action: {re-transcribe / re-segment / re-align}
+Transcriber settings: {model / language hints if applicable}
+```
+
+### To Scene Director:
+```
+EP FEEDBACK — Scene Plan Revision Required
+Reason: {reason}
+Affected scenes: {scene_ids}
+Constraint: {coverage / feasibility / timing}
+Available tools: {current tool registry status}
+```
+
+### To Asset Director:
+```
+EP FEEDBACK — Asset Regeneration Required
+Reason: {reason}
+Affected assets: {asset_ids}
+Specific fix: {subtitle_resync / audio_renormalize / overlay_regen}
+Transcript reference: {original transcript segments for re-alignment}
+Budget remaining: ${remaining}
+```
+
+### To Edit Director:
+```
+EP FEEDBACK — Edit Revision Required
+Reason: {reason}
+Specific issue: {gap_at_timestamp / invalid_reference / missing_subtitle_config}
+Asset manifest: {current valid asset paths}
+```
+
+### To Compose Director:
+```
+EP FEEDBACK — Re-render Required
+Reason: {reason}
+Specific issue: {subtitle_sync / audio_quality / resolution / duration}
+Expected: {what the output should be}
+Actual: {what was produced}
+Enhancement adjustments: {skip/add face_enhance, color_grade, etc.}
+```
+
+## Quality Gates Summary
+
+| Gate | After Stage | What's Checked | Fail Action |
+|------|-------------|---------------|-------------|
+| G1 | idea | Footage viability, audio presence, user approval | Revise brief OR stop pipeline |
+| G2 | script | Transcript confidence, timestamps, section boundaries | Revise script (re-transcribe) |
+| G3 | scene_plan | Full coverage, enhancement feasibility, overlay alignment | Revise scene_plan |
+| G4 | assets | Subtitle sync, audio extraction, budget | Revise assets OR send-back to script |
+| G5 | edit | Timeline completeness, trim validation, subtitle config | Revise edit |
+| G6 | compose | Output probe, duration, audio, subtitle burn-in | Revise compose OR send-back to edit/assets |
+| G7 | publish | Metadata, packaging | Revise publish |
+| FINAL | all | Subtitle sync, audio quality, visual quality | Send-back to specific stage |
+
+## Execution Limits (Anti-Loop Protection)
+
+| Limit | Value | Rationale |
+|-------|-------|-----------|
+| Max revisions per stage | 3 | Prevent perfectionism loops |
+| Max send-backs per stage pair | 1 | Prevent ping-pong between stages |
+| Max total send-backs | 3 | Cap total pipeline re-work |
+| Max total budget | Configurable (default $0.50) | Hard stop on spending |
+| Max total wall-time | 10 minutes | Timeout for entire pipeline (shorter than explainer — less generation) |
+
+After any limit is hit: **proceed with warnings**, never block indefinitely.
+
+## Integration with Existing Skills
+
+The EP doesn't replace any director skill — it wraps them. Each director skill continues to work exactly as documented. The EP adds:
+
+1. **Context injection**: Directors receive EP_STATE with cross-stage information they couldn't access before
+2. **Feedback injection**: Directors receive specific revision instructions when sent back
+3. **Budget awareness**: Directors receive remaining budget and can adjust tool choices accordingly
+4. **Transcript continuity**: The EP carries transcript data forward, ensuring subtitle generation and edit decisions use the same source of truth
+
+## Example EP Run (Abbreviated)
+
+```
+[EP] Starting pipeline: talking-head v2.0
+[EP] Default budget: $0.50 | Playbook: clean-professional
+
+[EP] Probing raw footage: interview_raw.mp4
+[EP] → Duration: 4m22s | Resolution: 1920x1080 | FPS: 30 | Audio: stereo AAC
+[EP] Footage looks viable. Audio present. Proceeding.
+
+[EP] === STAGE 1: idea ===
+[EP] Spawning idea-director... Footage: interview_raw.mp4
+[EP] Brief: "Interview with CTO on API security" | Target: 3m00s (trim from 4m22s)
+[EP] Platform: YouTube Shorts → wait, that's < 60s. User said LinkedIn.
+[EP] G1 PASS — Brief references footage, duration target realistic, user approved.
+
+[EP] === STAGE 2: script ===
+[EP] Spawning script-director with brief...
+[EP] Transcriber: WhisperX large-v3. Processing 4m22s audio...
+[EP] Transcript: 612 words, avg confidence 0.91. Language: en.
+[EP] 8 sections identified. Timestamps monotonic. ✓
+[EP] G2 PASS — Confidence good, sections align with topic changes.
+
+[EP] === STAGE 3: scene_plan ===
+[EP] Spawning scene-director with script...
+[EP] 8 scenes planned. Total duration: 3m02s (target 3m00s).
+[EP] Enhancements: face_enhance on all scenes, color_grade, lower-third overlay at 0:00-0:05.
+[EP] face_enhance: checking registry... AVAILABLE ✓
+[EP] G3 PASS — Full coverage, enhancements feasible.
+
+[EP] === STAGE 4: assets ===
+[EP] Spawning asset-director with scene_plan + script...
+[EP] Subtitles generated: 82 cues, SRT format.
+[EP] Sync check: max offset 0.18s. All within 0.3s tolerance. ✓
+[EP] Audio extracted and normalized to -16 LUFS. ✓
+[EP] Lower-third overlay generated via recraft_image. Cost: $0.02.
+[EP] Budget: $0.02 spent, $0.48 remaining.
+[EP] G4 PASS — Subtitles synced, audio clean, assets on disk.
+
+[EP] === STAGE 5: edit ===
+[EP] Spawning edit-director with scene_plan + asset_manifest...
+[EP] Timeline: 3m02s with 7 cuts. Subtitles enabled.
+[EP] Trim: removed 0:00-0:12 (dead air) and 3:45-4:22 (off-topic).
+[EP] G5 PASS — Timeline complete, all references valid.
+
+[EP] === STAGE 6: compose ===
+[EP] Spawning compose-director with edit_decisions + asset_manifest...
+[EP] face_enhance applied: 8 scenes processed.
+[EP] color_grade applied: unified warm tone.
+[EP] audio_enhance: noise reduction applied.
+[EP] video_compose: final render → output/talking-head-final.mp4
+[EP] Output probe: 3m01s, 1920x1080, stereo audio, H.264. ✓
+[EP] Budget: $0.18 spent (face_enhance + color_grade + overlays).
+[EP] G6 PASS
+
+[EP] === STAGE 7: publish ===
+[EP] Spawning publish-director with render_report...
+[EP] G7 PASS — Title, description, chapters, thumbnail configured.
+
+[EP] === FINAL QA ===
+[EP] Duration: 3m01s ✓ | Subtitle sync: max drift 0.18s ✓ | Audio: -16.2 LUFS ✓
+[EP] Face enhance: natural ✓ | Color: consistent ✓ | Overlays: timed correctly ✓
+[EP] Budget: $0.18 / $0.50 ✓
+[EP] PIPELINE COMPLETE — 0 revisions, 0 send-backs
+[EP] Output: output/talking-head-final.mp4
+```
+
+## Common Pitfalls
+
+- **Ignoring transcript quality**: Everything downstream depends on the transcript. If confidence is low, fix it in the script stage — don't let bad timestamps propagate to subtitles and edits.
+- **Over-enhancing**: Face enhance and color grade are optional. If the raw footage looks good, skip them. Don't add processing for the sake of it.
+- **Subtitle style mismatch**: The subtitle style must come from the playbook. Don't let the asset director use default SRT styling when the playbook specifies font/color/position.
+- **Not probing raw footage**: Always ffprobe before starting. A video with no audio track or a corrupt container will waste every downstream stage.
+- **Trimming too aggressively**: The edit director may cut sections that seem off-topic but contain valuable context. The EP should verify that trimmed content is genuinely unnecessary by checking against the brief.
+- **Losing transcript data**: The EP must carry `transcript_segments` from the script stage all the way to asset generation. Subtitle timing depends on the exact same word-level data the transcriber produced.

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

@@ -0,0 +1,59 @@
+# Idea Director — Talking Head Pipeline
+
+## When to Use
+
+You are starting a talking-head video project. You have raw footage of a person speaking. Your job is to analyze the footage, understand what it contains, and build a brief that captures the content's essence and production goals.
+
+Unlike the explainer pipeline (which starts from a topic), you start from existing footage. The brief documents what you're working with and what the final video should look like.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/brief.schema.json` | Artifact validation |
+| Inputs | Raw footage file path | Source material |
+| Tools | `ffprobe` (via shell) | Footage metadata extraction |
+
+## Process
+
+### Step 1: Inspect the Footage
+
+Use ffprobe to extract metadata:
+- Duration
+- Resolution
+- Frame rate
+- Audio channels and codec
+- File size
+
+This tells you what you're working with — quality, length, format.
+
+### Step 2: Quick Content Assessment
+
+Watch/scan the footage mentally (or sample frames if frame_sampler is available):
+- What is the person talking about?
+- How long is the raw footage?
+- What's the intended platform? (Ask the user if unclear)
+- Is there good audio? Background noise?
+
+### Step 3: Build the Brief
+
+Create a brief artifact documenting:
+- **Title**: Descriptive title based on footage content
+- **Hook**: What makes this worth watching?
+- **Key points**: Main topics covered in the footage
+- **Tone**: Match the speaker's actual tone (casual, professional, educational)
+- **Style**: Usually `clean-professional` for talking head
+- **Target platform**: Where this will be published
+- **Target duration**: May be shorter than raw footage (trimmed)
+
+### Step 4: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Accuracy** | Does the brief reflect what's actually in the footage? |
+| **Completeness** | Are all required brief fields present? |
+| **Platform fit** | Is the target platform appropriate for this content? |
+
+### Step 5: Submit
+
+Validate the brief against the schema and persist via checkpoint.

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

@@ -0,0 +1,52 @@
+# Publish Director — Talking Head Pipeline
+
+## When to Use
+
+You have a render report with the final video. Your job is to prepare metadata, thumbnails, and an export package for publishing.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
+| Prior artifacts | Render report, Brief | Video file and context |
+
+## Process
+
+### Step 1: Generate Metadata
+
+Create platform-specific metadata:
+- **Title**: Based on the brief's title and hook
+- **Description**: Summary of the content with relevant keywords
+- **Tags**: Derived from brief's key_points
+- **Chapters**: From script section timestamps
+
+### Step 2: Thumbnail Concept
+
+Describe or generate a thumbnail:
+- Extract a compelling frame from the footage (if frame_sampler available)
+- Add text overlay concept (title or key stat)
+
+### Step 3: Package Export
+
+Create the export directory:
+- Video file
+- Metadata JSON
+- Description text file
+- Chapter markers
+- Thumbnail concept
+
+### Step 4: Build Publish Log
+
+Document the publish event with platform, status (draft), and export path.
+
+### Step 5: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Metadata quality** | Is the title compelling and description informative? |
+| **Completeness** | Is the export package complete? |
+
+### Step 6: Submit
+
+Validate the publish_log against the schema and persist via checkpoint.

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

@@ -0,0 +1,45 @@
+# Scene Director — Talking Head Pipeline
+
+## When to Use
+
+You have a script (from transcription) and raw footage. Your job is to create a scene plan — mostly simple since talking-head footage is a single continuous shot, but you still need to plan where overlays, text cards, and B-roll might appear.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
+| Prior artifacts | Script, Brief | Section timing and context |
+| Tools | `frame_sampler` (optional) | Extract representative frames |
+
+## Process
+
+### Step 1: Plan Base Scenes
+
+For talking-head, the base is simple: one scene per script section, all type `talking_head`. The raw footage IS the scene.
+
+### Step 2: Plan Enhancement Scenes
+
+Based on script enhancement cues, plan overlay scenes:
+- Text cards for key terms or statistics
+- Lower thirds for speaker identification
+- B-roll suggestions for topic illustrations
+
+### Step 3: Build Scene Plan
+
+Create a scene per section with:
+- Type: `talking_head` (primary)
+- Timing from script sections
+- Required assets: subtitle file, any overlay images
+
+### Step 4: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Coverage** | Every script section has a scene? |
+| **Enhancement** | Are overlay opportunities identified? |
+| **Feasibility** | Can all required assets be generated? |
+
+### Step 5: Submit
+
+Validate the scene_plan against the schema and persist via checkpoint.

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

@@ -0,0 +1,56 @@
+# Script Director — Talking Head Pipeline
+
+## When to Use
+
+You have a brief and raw talking-head footage. Your job is to transcribe the footage and structure it into a script artifact with timestamped sections.
+
+Unlike the explainer pipeline (which writes a script from scratch), you're extracting and structuring existing speech.
+
+## Prerequisites
+
+| Layer | Resource | Purpose |
+|-------|----------|---------|
+| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
+| Prior artifacts | `state.artifacts["idea"]["brief"]` | Content context |
+| Tools | `transcriber` (WhisperX) | Speech-to-text with timestamps |
+
+## Process
+
+### Step 1: Transcribe
+
+Use the transcriber tool to get word-level timestamps:
+- Model: `large-v3` for best quality, `base` for speed
+- Enable word-level alignment for precise timing
+- Note language detection result
+
+### Step 2: Segment into Sections
+
+Group the transcript into logical sections:
+- Detect topic changes by content
+- Respect natural pauses (> 1.5s silence = potential section break)
+- Each section gets: id, text, start_seconds, end_seconds
+
+### Step 3: Enhance Section Metadata
+
+For each section, add:
+- Enhancement cues (where overlays, b-roll, or text cards could go)
+- Speaker notes (emphasis, pace changes detected in audio)
+
+### Step 4: Build Script Artifact
+
+Assemble the structured script with:
+- Total duration (from transcript)
+- All sections with timestamps
+- Enhancement cues per section
+
+### Step 5: Self-Evaluate
+
+| Criterion | Question |
+|-----------|----------|
+| **Transcription accuracy** | Are the words correct? (Spot-check a few sections) |
+| **Timestamp accuracy** | Do section boundaries align with actual speech? |
+| **Coverage** | Does the script span the full footage duration? |
+
+### Step 6: Submit
+
+Validate the script against the schema and persist via checkpoint.