From 33ba37704e618b38b6925941e92d7ca0d3f90cad Mon Sep 17 00:00:00 2001
From: calesthio <celesthioailabs@gmail.com>
Date: Mon, 13 Apr 2026 16:22:15 -0700
Subject: [PATCH] docmontage: add children's fantasy content routing +
 CaptionOverlayOnly composition

Teach the agent to automatically use Pixabay AI-generated fantasy clips
for children's content. scene-director.md gets query rewriting rules
(10-row table) and source routing. asset-director.md gets source lock,
visual consistency check, and fallback rules. Root.tsx adds a
CaptionOverlayOnly Remotion composition for transparent caption
rendering used in the TikTok-style subtitle pipeline.
---
 remotion-composer/src/Root.tsx                | 16 ++++++++
 .../documentary-montage/asset-director.md     | 40 +++++++++++++++++++
 .../documentary-montage/scene-director.md     | 35 ++++++++++++++++
 3 files changed, 91 insertions(+)

diff --git a/remotion-composer/src/Root.tsx b/remotion-composer/src/Root.tsx
index 2ae51415..175e5dac 100644
--- a/remotion-composer/src/Root.tsx
+++ b/remotion-composer/src/Root.tsx
@@ -13,6 +13,7 @@ import {
 import { EndTag, EndTagProps } from "./components/EndTag";
 import { HeroTitle } from "./components/HeroTitle";
 import { ProductReveal, ProductRevealProps } from "./components/ProductReveal";
+import { CaptionOverlay, WordCaption } from "./components/CaptionOverlay";
 
 // ---------------------------------------------------------------------------
 // Theme System — prevents every video from looking like dark fintech
@@ -250,6 +251,21 @@ export const Root: React.FC = () => {
           accentColor: "#00D4FF",
         } as ProductRevealProps}
       />
+      <Composition
+        id="CaptionOverlayOnly"
+        component={CaptionOverlay}
+        durationInFrames={30 * 300}
+        fps={30}
+        width={1920}
+        height={1080}
+        defaultProps={{
+          words: [] as WordCaption[],
+          wordsPerPage: 3,
+          fontSize: 58,
+          highlightColor: "#FACC15",
+          backgroundColor: "rgba(15, 23, 42, 0.75)",
+        }}
+      />
       <Composition
         id="EndTag"
         component={EndTag}
diff --git a/skills/pipelines/documentary-montage/asset-director.md b/skills/pipelines/documentary-montage/asset-director.md
index e2f8f0bd..17e58db7 100644
--- a/skills/pipelines/documentary-montage/asset-director.md
+++ b/skills/pipelines/documentary-montage/asset-director.md
@@ -74,6 +74,46 @@ Three rules that follow from that:
 3. **Pick per slot, not per clip.** Every clip only belongs to one
    slot in the final edit. Use `exclude_ids` to prevent double-use.
 
+## Children's / Fairy-Tale Content — Source Override
+
+When the scene plan's `metadata.tone` or `metadata.target_audience`
+indicates children's content (fairy tale, bedtime story, kids'
+explainer, animated story), **override normal source routing** and
+acquire exclusively from Pixabay Video.
+
+### Why Pixabay Video Only
+
+Pixabay's community library contains thousands of AI-generated fantasy
+animations — glowing forests, enchanted landscapes, magical creatures —
+uploaded by creators using Midjourney/Stable Diffusion video workflows.
+These dramatically outperform real footage for children's engagement.
+No other free source has comparable depth in this style.
+
+### Acquisition Rules
+
+1. **Source lock.** Set `sources: ["pixabay_video"]` for ALL queries.
+   Do not mix real footage providers (Pexels, Dareful, etc.) with
+   fantasy clips — the style clash breaks immersion for children.
+
+2. **Query rewriting.** The scene director will have already rewritten
+   slot descriptions for fantasy style. If you need to write fallback
+   queries, prepend fantasy keywords:
+   - Magic keywords: `fairy tale`, `fantasy`, `enchanted`, `magical`,
+     `glowing`, `dreamy`, `mystical`, `fairy`, `enchanted forest`,
+     `magical world`
+   - Example: slot needs "caterpillar on leaf" → query
+     `"fairy tale caterpillar magical forest glowing"`
+
+3. **Visual consistency check.** After downloading, verify that ALL
+   clips share the AI-generated fantasy aesthetic. Reject any clip
+   that looks like real footage — even if the CLIP score is higher.
+   A single real clip in a fantasy montage breaks the spell.
+
+4. **Fallback.** If Pixabay returns no fantasy results for a slot,
+   rewrite the query with different fantasy keywords before trying
+   broader terms. Two rewrites per slot. If still empty, flag the
+   slot to the user — do not silently substitute real footage.
+
 ## Process — Fast Path (Direct Search)
 
 Use this when producing act-by-act with user review between acts, or
diff --git a/skills/pipelines/documentary-montage/scene-director.md b/skills/pipelines/documentary-montage/scene-director.md
index 8ff0bbce..3e3905a7 100644
--- a/skills/pipelines/documentary-montage/scene-director.md
+++ b/skills/pipelines/documentary-montage/scene-director.md
@@ -168,6 +168,41 @@ queries in period-appropriate vocabulary ("commuter", "housewife",
 If `era_mix = "any"`, mix sources per slot — the scene director
 decides which slot gets which source based on the beat's meaning.
 
+#### Children's / Fairy-Tale Content
+
+When the brief's `tone` or `target_audience` indicates children's
+content (fairy tale, bedtime story, kids' explainer, animated story),
+**switch the visual strategy from real footage to AI-generated fantasy
+clips on Pixabay**.
+
+Pixabay's community library contains thousands of AI-generated fantasy
+animations (glowing forests, enchanted landscapes, magical creatures)
+that dramatically outperform real footage for children's engagement.
+
+**Query rewriting rules for children's content:**
+
+| Slot intent | Real-footage query | Fantasy rewrite |
+|-------------|-------------------|-----------------|
+| Garden / nature | `garden flowers morning` | `enchanted fairy tale garden glowing magical` |
+| Insects / creatures | `caterpillar leaf close up` | `fairy tale caterpillar magical forest glowing` |
+| Transformation / cocoon | `chrysalis butterfly cocoon` | `magical chrysalis enchanted tree glowing` |
+| Butterfly / flight | `butterfly flying sky` | `fantasy butterfly glowing magical wings` |
+| Sunset / landscape | `sunset landscape golden` | `enchanted fantasy landscape magical sunset` |
+| Rain / weather | `rain leaves gentle` | `fairy tale rain magical forest enchanted` |
+| Night sky / stars | `milky way timelapse` | `fantasy night sky magical stars enchanted` |
+| Ocean / water | `river water golden` | `magical underwater world fairy tale` |
+| Mountains / aerial | `mountain peaks golden` | `fantasy mountain castle fairy tale magical` |
+| Forest / trees | `forest path morning` | `fairy tale mushroom forest glowing enchanted` |
+
+**Source routing:** Set `preferred_sources: ["pixabay_video"]` for ALL
+slots. Pixabay is the only free source with a deep AI-generated fantasy
+library. Do not mix real footage with fantasy — the style clash breaks
+immersion for children.
+
+**Keywords that surface AI fantasy content:** `fairy tale`, `fantasy`,
+`enchanted`, `magical`, `glowing`, `dreamy`, `mystical`, `fairy`,
+`enchanted forest`, `magical world`.
+
 ### 6. Mark Hero Slots
 
 Every montage has 2-3 slots the whole piece depends on: the opening