@mevdragon/vidfarm-devcli 0.13.0 → 0.15.0

package/.agents/skills/embedded-captions/modes/cinematic/_archive/champion/spec.md

@@ -0,0 +1,98 @@
+# Template: champion
+
+**Look:** podcast / interview, upper-side column with intro→phrase→emph
+beats building toward a center-stage CROWN that crosses the subject's body.
+"Wimbledon Champion" energy.
+
+**Visual identity (LOCKED):**
+
+- 5 typography slots: intro / phrase / emph / dream / crown
+- `mix-blend-mode: screen` over warm bone color (#fff5df)
+- Deep text-shadow + brightness boost
+- Single-caption-swap layout (caps stack at one point in the column)
+- Center-stage crown crosses the subject for cinematic occlusion
+
+## When to apply
+
+✅ **Good fit:**
+
+- Podcast / interview style with a single seated subject
+- Cluttered backdrop (bookshelf, props, dark) — screen blend reads through
+- Subject roughly centered with clear clean zones on one or both sides
+- Speech has a clear payoff line that can become a "crown" (1-3 short words)
+- 16:9 landscape, 1920×1080 ideal
+
+❌ **Wrong fit:**
+
+- Bright/sky/window backdrop (screen blend washes out)
+- Subject heavily off-center such that there's no clean column zone
+- Speech has no clear climax line
+- Portrait 9:16 → use `portrait-header` template instead
+
+## Layout decisions agent makes
+
+| Field                         | What                                                                                                                                        | Example (1920×1080)                            |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `plane.top/left/width/height` | Where the side column sits. Pick the side opposite the subject's gaze (looking room) and hug the cleanest backdrop zone.                    | `{top: 40, left: 40, width: 720, height: 420}` |
+| `plane.rotateY`               | Slight perspective into the wall. Positive for left column (recedes right), negative for right column. Keep small (3-7°).                   | `4`                                            |
+| `crown_top`                   | Y position of the crown. Should fall on the subject's chest/neck so the body occludes the middle letters.                                   | `420`                                          |
+| `font_scale`                  | Multiplier on locked sizes.                                                                                                                 | `1.0` for 1920×1080                            |
+| `crown_enabled`               | Whether to render a crown. Skip if the speech has no clean payoff line, or if the subject is too far off-center for a center crown to land. | `true`                                         |
+
+### Crown placement rules
+
+Before enabling the crown, verify all 3 conditions:
+
+1. Subject body center within ±10% of frame horizontal center
+2. Clean zones ≥15% of frame width on each side of subject
+3. Crown text width (uppercase 140px × ~chars) > subject body width + 400px
+
+If any fails: disable the crown OR use a smaller font + place it in the
+larger clean zone instead of center. See `references/layout-heuristics.md`.
+
+## Slot assignment
+
+| Slot   | Use for                                                    |
+| ------ | ---------------------------------------------------------- |
+| intro  | Filler / discourse markers ("you know,", "for me,", "so…") |
+| phrase | Main statement clauses                                     |
+| emph   | Key achievement / superlative line                         |
+| dream  | Aspirational lines, past-tense reflection                  |
+| crown  | The single climax line — center-stage payoff               |
+
+Aim for ≤3 slots per video (excluding crown). Don't use all 4 in a 12s clip.
+
+## Plan.json shape
+
+```json
+{
+  "mode": "template",
+  "template": "champion",
+  "duration": 12.08, "fps": 24, "width": 1920, "height": 1080,
+  "plane": {
+    "top": 40, "left": 40, "width": 720, "height": 420,
+    "rotateY": 4
+  },
+  "crown_top": 420,
+  "font_scale": 1.0,
+  "groups": [
+    { "id": "cg-0", "slot": "intro", "tone": "soft",
+      "in": 0.10, "out": 1.45, "words": [...] },
+    { "id": "cg-1", "slot": "phrase", "tone": "soft",
+      "in": 1.55, "out": 4.20, "words": [...] },
+    { "id": "cg-2", "slot": "emph", "tone": "present",
+      "in": 6.50, "out": 8.30, "words": [...] }
+  ],
+  "crown_group": {
+    "id": "cg-crown", "tone": "present",
+    "in": 10.85, "out": 12.08,
+    "words": [
+      {"text": "Wimbledon", "start": 10.94, "end": 11.28},
+      {"text": "Champion",  "start": 11.38, "end": 11.84}
+    ]
+  }
+}
+```
+
+`crown_group` always uses the crown slot — no need to specify `slot`.
+Set `crown_group: null` to disable.

package/.agents/skills/embedded-captions/modes/cinematic/_archive/champion/template.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<!--
+  TEMPLATE: champion
+  STYLE LOCKED. LAYOUT OPEN.
+
+  Look: podcast / interview, upper-left column with intro→phrase→emph
+  beats, big center-stage CROWN crossing the subject for the payoff.
+
+  Locked:
+    - 5 typography slots: intro / phrase / emph / dream / crown
+    - mix-blend-mode: screen, color #fff5df, deep text-shadow
+    - Single-caption-swap layout (caps absolute-positioned in left-plane)
+    - GSAP soft/present per-word reveal
+
+  Open via plan.json:
+    - left-plane geometry + perspective
+    - crown_plane top
+    - --font-scale
+    - GROUPS array + slot per group
+    - whether crown is enabled (crown_group)
+-->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width={{WIDTH}}, height={{HEIGHT}}" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      :root { --font-scale: {{FONT_SCALE}}; }
+
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body {
+        margin: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        overflow: hidden;
+        background: #000;
+        font-family: "Inter", system-ui, sans-serif;
+      }
+      #a-roll { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+
+      #stage {
+        position: absolute;
+        top: 0; left: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        perspective: 2400px;
+        perspective-origin: 25% 50%;
+        pointer-events: none;
+        z-index: 2;
+      }
+
+      /* LAYOUT */
+      .left-plane {
+        position: absolute;
+        top: {{PLANE_TOP}}px;
+        left: {{PLANE_LEFT}}px;
+        width: {{PLANE_WIDTH}}px;
+        height: {{PLANE_HEIGHT}}px;
+        transform-style: preserve-3d;
+        transform: rotateY({{ROTATE_Y}}deg);
+        transform-origin: left center;
+        padding: 24px 36px;
+      }
+      .left-plane .cap {
+        position: absolute;
+        top: 24px;
+        right: 36px;
+        max-width: calc({{PLANE_WIDTH}}px - 72px);
+      }
+      .crown-plane {
+        position: absolute;
+        top: {{CROWN_TOP}}px;
+        left: {{CROWN_LEFT}}px;
+        right: {{CROWN_RIGHT}}px;
+        text-align: {{CROWN_ALIGN}};
+        pointer-events: none;
+      }
+      .crown-plane .cap-crown {
+        font-size: calc(140px * var(--font-scale) * {{CROWN_SCALE}});
+      }
+
+      /* STYLE (locked) */
+      .cap {
+        display: block;
+        position: relative;
+        line-height: 1.02;
+        opacity: 0;
+        mix-blend-mode: {{BLEND_MODE}};
+        color: {{CAP_COLOR}};
+        text-shadow: {{TEXT_SHADOW}};
+        filter: {{TEXT_FILTER}};
+        will-change: transform, opacity;
+      }
+      .cap .w { display: inline-block; opacity: 0; will-change: opacity, transform; }
+
+      .cap-intro  { font-size: calc(52px * var(--font-scale));
+                    font-weight: 500; font-style: italic;
+                    letter-spacing: -0.005em; }
+      .cap-phrase { font-size: calc(60px * var(--font-scale));
+                    font-weight: 600;
+                    letter-spacing: -0.015em; }
+      .cap-emph   { font-size: calc(70px * var(--font-scale));
+                    font-weight: 800;
+                    letter-spacing: -0.025em; }
+      .cap-dream  { font-size: calc(64px * var(--font-scale));
+                    font-weight: 700; font-style: italic;
+                    letter-spacing: -0.015em; }
+      .cap-crown  { font-size: calc(140px * var(--font-scale));
+                    font-weight: 900;
+                    letter-spacing: -0.035em; text-transform: uppercase;
+                    line-height: 1.0; }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="{{DURATION}}"
+      data-width="{{WIDTH}}"
+      data-height="{{HEIGHT}}"
+    >
+      <video
+        id="a-roll"
+        src="source.mp4"
+        muted
+        playsinline
+        data-duration="{{DURATION}}"
+        data-track-index="0"
+        style="z-index: 1"
+      ></video>
+
+      <div id="stage">
+        <div class="left-plane">{{GROUPS_HTML}}</div>
+        <div class="crown-plane">{{CROWN_HTML}}</div>
+      </div>
+
+      <audio
+        id="a-roll-audio"
+        src="source.mp4"
+        data-start="0"
+        data-duration="{{DURATION}}"
+        data-track-index="3"
+        data-volume="1"
+      ></audio>
+    </div>
+
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      const DUR = {{DURATION}};
+      const GROUPS = {{GROUPS_JSON}};
+      const CROWN  = {{CROWN_JSON}};
+
+      function animateGroup(g) {
+        var sel = "#" + g.id;
+        var isSoft = g.tone === "soft";
+        tl.set(sel, { opacity: 1, y: 0 }, Math.max(0, g.in - 0.01));
+
+        g.words.forEach(function (w, i) {
+          var wsel = sel + " .w[data-i='" + i + "']";
+          if (isSoft) {
+            tl.fromTo(wsel,
+              { opacity: 0, y: 8 },
+              { opacity: 1, y: 0, duration: 0.42, ease: "power2.out", overwrite: "auto" },
+              w.start);
+          } else {
+            tl.fromTo(wsel,
+              { opacity: 0, y: 6, scale: 1.04 },
+              { opacity: 1, y: 0, scale: 1.0, duration: 0.22,
+                ease: "power3.out", overwrite: "auto", transformOrigin: "50% 50%" },
+              w.start);
+          }
+        });
+
+        if (g.out < DUR) {
+          tl.to(sel, { opacity: 0, duration: 0.45, ease: "power2.in", overwrite: "auto" },
+                g.out - 0.45);
+        }
+        tl.set(sel, { opacity: 0, visibility: "hidden" }, g.out);
+      }
+
+      GROUPS.forEach(animateGroup);
+      if (CROWN) animateGroup(CROWN);
+
+      tl.seek(0);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>

package/.agents/skills/embedded-captions/modes/cinematic/_archive/memory-wall/spec.md

@@ -0,0 +1,134 @@
+# Template: memory-wall
+
+**Look:** introspective monologue, italic poem stacking on a back wall,
+right-aligned cascade for the climax. Sam Harris / Pico Iyer territory.
+
+**Visual identity (LOCKED — do not change):**
+
+- 4-slot typography arc: italic 600 → italic 500 hanging-indent → upright
+  700 pivot → uppercase 900 climax
+- `mix-blend-mode: screen` over warm-bone color (#fff4dc)
+- soft text-shadow + brightness boost
+- Per-word fade with subtle Y-drift (soft tone) or pop+scale (present tone)
+
+## When to apply
+
+✅ **Good fit:**
+
+- Talking-head with a flat back wall (acoustic foam, plain plaster, soft
+  bookshelf) on one side
+- Single subject, fixed or near-fixed camera
+- Voice-over feel: introspective, narrative, "I was thinking…"
+- Mid-tone or dark backdrop (luminance < 180)
+
+❌ **Wrong fit:**
+
+- Bright window/sky backdrop → screen blend blows out
+- Cluttered backdrop with text/graphics → conflicts with caption text
+- Energetic / vlog / TikTok style → wrong vibe
+- Multiple speakers / hard cuts → caption arc breaks
+
+## What agent decides per scene
+
+| Field                          | What                                                                                                               | Example                                                            |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `plane.top/right/width/height` | Where the wall plane sits in frame. Plane should HUG the side of the wall, not float over the subject.             | `{top: 90, right: 30, width: 720, height: 520}` for 1280×720       |
+| `plane.rotateY`                | Match the wall's perspective angle. Negative for right-side wall (text recedes left), positive for left-side wall. | `-13` for a right-side wall at slight angle                        |
+| `plane.rotateX`                | Tiny vertical tilt if wall is angled up/down. Usually 0-2 deg.                                                     | `1`                                                                |
+| `font_scale`                   | Multiplier on the locked cap-N base sizes. Tune for frame height.                                                  | `1.0` for 1280×720, `~1.5` for 1920×1080, `~0.7` for 720p portrait |
+| `groups[].slot`                | Which of the 4 typography slots this group uses (1/2/3/4). Drives the arc.                                         | See below                                                          |
+| `groups[].tone`                | "soft" or "present" — drives motion curve                                                                          | `"soft"` for opening lines, `"present"` for pivot+climax           |
+
+## Slot assignment rules
+
+Aim for ONE arc across the video: `1 → 2 → 3 → 4`. Don't repeat slots if you
+can avoid it; don't skip slots without reason.
+
+| Slot | Use for                                                                                                                                  |
+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | The opener. The "I was thinking" line. Italic, soft entry.                                                                               |
+| 2    | The dreamy continuation / modifier. Smaller italic, hanging-indent — feels like the second half of a sentence with some staggered drift. |
+| 3    | The pivot. Upright (no italic), the syntactic turn. ("but suddenly", "and then…")                                                        |
+| 4    | The climax. Big uppercase 900. The payoff line. Aim for ≤4 short words so the right-aligned cascade naturally wraps to 2-3 lines.        |
+
+If the script is longer than 4 groups, repeat slot 1 or 2 for additional
+soft lines, but reserve slot 4 for the SINGLE climax.
+
+## Plan.json shape
+
+```json
+{
+  "mode": "template",
+  "template": "memory-wall",
+  "duration": 8.04,
+  "fps": 24,
+  "width": 1280,
+  "height": 720,
+  "plane": {
+    "top": 90,
+    "right": 30,
+    "width": 720,
+    "height": 520,
+    "rotateY": -13,
+    "rotateX": 1
+  },
+  "font_scale": 1.0,
+  "groups": [
+    {
+      "id": "cg-0",
+      "slot": 1,
+      "tone": "soft",
+      "in": 0.2,
+      "out": 4.85,
+      "words": [
+        { "text": "Some", "start": 0.24, "end": 0.44 },
+        { "text": "memories", "start": 0.48, "end": 0.82 },
+        { "text": "feel", "start": 0.92, "end": 1.14 },
+        { "text": "soft", "start": 1.2, "end": 1.64 }
+      ]
+    },
+    {
+      "id": "cg-1",
+      "slot": 2,
+      "tone": "soft",
+      "in": 2.55,
+      "out": 4.85,
+      "words": [
+        { "text": "like", "start": 2.66, "end": 2.78 },
+        { "text": "old", "start": 2.86, "end": 3.02 },
+        { "text": "film", "start": 3.16, "end": 3.46 }
+      ]
+    },
+    {
+      "id": "cg-2",
+      "slot": 3,
+      "tone": "present",
+      "in": 4.9,
+      "out": 8.04,
+      "words": [
+        { "text": "but", "start": 5.04, "end": 5.18 },
+        { "text": "suddenly", "start": 5.24, "end": 5.76 }
+      ]
+    },
+    {
+      "id": "cg-3",
+      "slot": 4,
+      "tone": "present",
+      "in": 6.7,
+      "out": 8.04,
+      "words": [
+        { "text": "everything", "start": 6.82, "end": 7.14 },
+        { "text": "is", "start": 7.18, "end": 7.28 },
+        { "text": "sharp", "start": 7.32, "end": 7.52 },
+        { "text": "again", "start": 7.58, "end": 7.92 }
+      ]
+    }
+  ]
+}
+```
+
+## Don't fight the template
+
+If the user wants different typography, different blend, or different motion:
+**use Standard mode** (`../../standard/`). Don't try to override the locked CSS — the
+template's visual consistency is the whole point.

package/.agents/skills/embedded-captions/modes/cinematic/_archive/memory-wall/template.html

@@ -0,0 +1,179 @@
+<!doctype html>
+<!--
+  TEMPLATE: memory-wall
+  STYLE LOCKED. LAYOUT OPEN.
+
+  Locked (do not edit — overriding breaks visual consistency):
+    - cap-1/2/3/4 typography (weights, italic, letter-spacing, padding-right)
+    - mix-blend-mode: screen
+    - color, text-shadow, filter
+    - GSAP motion: container fade-in via tl.set, per-word opacity+y reveal,
+      group fade-out 0.45s before g.out
+
+  Open (agent fills via plan.json):
+    - {{PLANE_TOP}} {{PLANE_RIGHT}} {{PLANE_WIDTH}} {{PLANE_HEIGHT}}
+    - {{ROTATE_Y}} {{ROTATE_X}}  (perspective angle on the wall)
+    - --font-scale CSS var (multiplies all cap-N sizes — agent tunes for frame)
+    - GROUPS array (transcript groups, slot assignment 1/2/3/4, in/out/words)
+
+  Style typography is keyed to "slots", semantic positions in the arc:
+    cap-1: opener (italic, soft entry)
+    cap-2: continuation (smaller italic, hanging indent — ragged poem feel)
+    cap-3: pivot (upright, no italic, syntactic turn)
+    cap-4: climax (UPPERCASE 900, the payoff line)
+-->
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width={{WIDTH}}, height={{HEIGHT}}" />
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <style>
+      :root { --font-scale: {{FONT_SCALE}}; }
+
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body {
+        margin: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        overflow: hidden;
+        background: #000;
+        font-family: "Inter", system-ui, sans-serif;
+      }
+
+      #a-roll {
+        position: absolute; inset: 0;
+        width: 100%; height: 100%;
+        object-fit: cover;
+      }
+
+      #stage {
+        position: absolute;
+        top: 0; left: 0;
+        width: {{WIDTH}}px; height: {{HEIGHT}}px;
+        perspective: 1400px;
+        perspective-origin: 30% 40%;
+        pointer-events: none;
+        z-index: 2;
+      }
+
+      /* LAYOUT (agent-tunable via plan.json) */
+      .wall-plane {
+        position: absolute;
+        top: {{PLANE_TOP}}px;
+        right: {{PLANE_RIGHT}}px;
+        width: {{PLANE_WIDTH}}px;
+        height: {{PLANE_HEIGHT}}px;
+        transform-style: preserve-3d;
+        transform: rotateY({{ROTATE_Y}}deg) rotateX({{ROTATE_X}}deg);
+        transform-origin: right center;
+        padding: 24px 32px;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        align-items: flex-end;
+        text-align: right;
+        gap: 14px;
+      }
+
+      /* STYLE (locked) */
+      .cap {
+        display: block;
+        position: relative;
+        line-height: 1.05;
+        opacity: 0;
+        mix-blend-mode: {{BLEND_MODE}};
+        color: {{CAP_COLOR}};
+        text-shadow: {{TEXT_SHADOW}};
+        filter: {{TEXT_FILTER}};
+        will-change: transform, opacity;
+      }
+      .cap .w { display: inline-block; opacity: 0; will-change: opacity, transform; }
+
+      .cap-1 { font-size: calc(78px * var(--font-scale));
+               font-weight: 600; font-style: italic;
+               letter-spacing: -0.01em; }
+      .cap-2 { font-size: calc(66px * var(--font-scale));
+               font-weight: 500; font-style: italic;
+               letter-spacing: -0.005em;
+               padding-right: calc(44px * var(--font-scale)); }
+      .cap-3 { font-size: calc(72px * var(--font-scale));
+               font-weight: 700;
+               letter-spacing: -0.015em; }
+      .cap-4 { font-size: calc(90px * var(--font-scale));
+               font-weight: 900;
+               letter-spacing: -0.03em;
+               text-transform: uppercase;
+               line-height: 1.0; }
+    </style>
+  </head>
+  <body>
+    <div
+      id="root"
+      data-composition-id="main"
+      data-start="0"
+      data-duration="{{DURATION}}"
+      data-width="{{WIDTH}}"
+      data-height="{{HEIGHT}}"
+    >
+      <video
+        id="a-roll"
+        src="source.mp4"
+        muted
+        playsinline
+        data-duration="{{DURATION}}"
+        data-track-index="0"
+        style="z-index: 1"
+      ></video>
+
+      <div id="stage">
+        <div class="wall-plane">{{GROUPS_HTML}}</div>
+      </div>
+
+      <audio
+        id="a-roll-audio"
+        src="source.mp4"
+        data-start="0"
+        data-duration="{{DURATION}}"
+        data-track-index="3"
+        data-volume="1"
+      ></audio>
+    </div>
+
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      const DUR = {{DURATION}};
+      const GROUPS = {{GROUPS_JSON}};
+
+      GROUPS.forEach(function (g) {
+        var sel = "#" + g.id;
+        var isSoft = g.tone === "soft";
+        tl.set(sel, { opacity: 1, y: 0 }, Math.max(0, g.in - 0.01));
+
+        g.words.forEach(function (w, i) {
+          var wsel = sel + " .w[data-i='" + i + "']";
+          if (isSoft) {
+            tl.fromTo(wsel,
+              { opacity: 0, y: 8 },
+              { opacity: 1, y: 0, duration: 0.45, ease: "power2.out", overwrite: "auto" },
+              w.start);
+          } else {
+            tl.fromTo(wsel,
+              { opacity: 0, y: 6, scale: 1.04 },
+              { opacity: 1, y: 0, scale: 1.0, duration: 0.22,
+                ease: "power3.out", overwrite: "auto", transformOrigin: "100% 50%" },
+              w.start);
+          }
+        });
+
+        if (g.out < DUR) {
+          tl.to(sel, { opacity: 0, duration: 0.5, ease: "power2.in", overwrite: "auto" },
+                g.out - 0.5);
+        }
+        tl.set(sel, { opacity: 0, visibility: "hidden" }, g.out);
+      });
+
+      tl.seek(0);
+      window.__timelines["main"] = tl;
+    </script>
+  </body>
+</html>

package/.agents/skills/embedded-captions/modes/cinematic/_archive/portrait-header/spec.md

@@ -0,0 +1,81 @@
+# Template: portrait-header
+
+**Look:** 9:16 portrait talking-head with captions on a horizontal strip
+across the top of the frame, above the subject's head. Optional crown at
+the bottom for shots that include the subject's waist or below.
+
+**Visual identity (LOCKED):**
+
+- 5 typography slots: intro / phrase / emph / dream / crown (centered)
+- `mix-blend-mode: screen` over warm bone color (#fff5df)
+- Single-caption swap (caps stack at one position in the header strip)
+- Per-word fade with subtle Y-drift (soft) or pop+scale (present)
+
+## When to apply
+
+✅ **Good fit:**
+
+- 9:16 portrait video (1080×1920 typical)
+- Single subject filling the center of the frame
+- Clean band visible above the head
+- Speech is relatively dense (many short phrases) — crown only for the
+  one true climax
+
+❌ **Wrong fit:**
+
+- Subject's head crops to the very top of frame (no header band exists)
+- 16:9 landscape → use `champion` or `memory-wall` instead
+- Multiple speakers / cuts
+
+## Layout decisions
+
+| Field           | What                                                                                                                    | Example (1080×1920)                  |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `header.top`    | Y of the header strip. Should sit above the subject's head with ~30px breathing room.                                   | `30` if hair top is around y=200     |
+| `header.height` | Height of the strip. Bigger for longer captions / 2-line wraps.                                                         | `280`                                |
+| `crown_top`     | Y of the crown line (bottom of frame). Skip if no waist visible.                                                        | `1620` for a near-full-body shot     |
+| `crown_enabled` | Whether to render a bottom crown. Skip if subject body fills the lower half completely (matte will block crown anyway). | `false` for tight head-and-shoulders |
+| `font_scale`    | Scale multiplier on locked sizes.                                                                                       | `1.0` for 1080×1920                  |
+
+## Slot assignment
+
+Same arc as champion: intro / phrase / emph / dream / crown.
+
+For portrait-header specifically, header band is narrow (one strip), so:
+
+- Most groups fit on 1-2 lines
+- Don't use crown if it'd be hidden by the body matte (Pausch-style portraits
+  often need to skip crown entirely and promote the climax to `emph` in the
+  header instead)
+
+## Plan.json shape
+
+```json
+{
+  "mode": "template",
+  "template": "portrait-header",
+  "duration": 25.3, "fps": 24, "width": 1080, "height": 1920,
+  "header": { "top": 30, "height": 280 },
+  "crown_top": 1620,
+  "font_scale": 1.0,
+  "groups": [
+    { "id": "cg-0", "slot": "intro", "tone": "soft",
+      "in": 0.10, "out": 3.20, "words": [...] },
+    { "id": "cg-1", "slot": "phrase", "tone": "soft",
+      "in": 3.55, "out": 5.80, "words": [...] },
+    { "id": "cg-2", "slot": "emph", "tone": "present",
+      "in": 17.85, "out": 22.10,
+      "words": [
+        {"text": "Time", "start": 17.94, "end": 18.26},
+        {"text": "is",   "start": 18.38, "end": 18.54},
+        {"text": "all",  "start": 18.66, "end": 18.80},
+        {"text": "we",   "start": 18.92, "end": 19.02},
+        {"text": "have", "start": 19.12, "end": 19.38}
+      ]}
+  ],
+  "crown_group": null
+}
+```
+
+Set `crown_group: null` if you've checked that a crown would be blocked by
+the subject body or the shot composition.