takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/music-to-video/references/planning.md

@@ -1,104 +1,104 @@
-# Planning (Step 3) — pick the brand, fill every frame
-
-At Step 3 **you (the orchestrator)** turn the Step-2 skeleton into a complete, approved
-`STORYBOARD.md`. You edit the **same file** in place: pick the brand spine, then for each
-frame decide its **groups**, give each group a treatment, bind real beat anchors, and write
-the copy.
-
-Your mantra: **music is the spine; a template is a head start, not a cage; typography is the
-floor and assets are an optional ingredient on the same beat grid.**
-
-**You own WHAT, not HOW.** You name the template / primitives, the content, the brand, the
-anchor seconds, and the intent. The frame-worker (Step 4) decides HOW — micro-timing,
-realization, intra-frame cuts. **Never write millisecond tweens into the storyboard.**
-
-## Inputs
-
-- The Step-2 skeleton already in `STORYBOARD.md` — frames with `span_sec` + `pacing` + `mood` + `feel`.
-- `audiomap.json` — timing truth; read the real anchor seconds inside each frame's span.
-- [`template-catalog.md`](template-catalog.md) — the template selection menu.
-- [`motion-primitive-catalog.md`](motion-primitive-catalog.md) — the free-compose menu (L0 recipes).
-- [`montage.md`](montage.md) — asset treatments (only if the user supplied images/videos).
-- User brief / supplied copy — topic, mood, exact words to keep.
-
-## Step A — pick the brand spine (one preset, unmodified)
-
-The whole video shares one type family + palette. Pick **one ready-made preset** from
-`../hyperframes-creative/frame-presets/` using the preset table in
-`../hyperframes-creative/references/design-spec.md` — choose by the track's mood + the brief,
-and **only its fonts + colors matter** (templates own composition + motion; the preset only
-sets the look). Copy it in **unmodified**:
-
-```bash
-cp ../hyperframes-creative/frame-presets/<preset>/FRAME.md "$PROJECT_DIR/frame.md"
-```
-
-Then fill the storyboard frontmatter `style` from it: the `font` from its `typography:` and a
-≤4–6 swatch `palette` from its `colors:`. **Quote the hex / family verbatim — never invent or
-round.** Every group's palette params draw from this one palette; that unity is what makes
-different templates read as one piece.
-
-## Step B — per frame, decide its groups
-
-A frame is usually **one group** (one template or one free composition spanning the frame).
-Subdivide into 2+ groups **only when a single treatment can't cover the frame** — e.g. a busy
-opener plus a closing lockup. When you split, cut at a **real audiomap anchor** inside the
-frame's span (a `key_moment` / `phrase` edge / onset-cluster gap), **never inside a `rolls[]`
-run**, and keep every group **≥ ~1 bar**. Density does **not** force more groups — a dense
-frame is usually ONE group whose template absorbs the density internally (a meta-template like
-`poster-tile-mosaic`). **Group count tracks distinct treatments, not beats.**
-
-## Step C — per group, pick a treatment (exactly one of three)
-
-### A. Match a template
-
-Read [`template-catalog.md`](template-catalog.md). Match the group's `feel` + `mood` + `pacing`
-to a template's **Reach for it when**; take the closest fit. Then bind it:
-
-- Fill `params` (keys from the catalog entry) — your copy into text slots, palette from the brand spine, `duration` = the group's span length.
-- Fill `role_bindings` with this group's **real anchor seconds** read from `audiomap.json` over its span (not example times).
-- If the template's natural stop and the group's span end disagree, snap to the nearest anchor.
-
-### B. Free-compose (no template fits)
-
-Write a `free_design` — one visual thesis from [`motion-primitive-catalog.md`](motion-primitive-catalog.md)
-(a dominant system + the named L0 primitives + a density topology) + `anchors` (the real
-beat / onset seconds the moves ride). Free-compose is a **first-class** choice, written as
-carefully as a matched group — never a failure.
-
-### C. Asset treatment (only when the user supplied assets and they fit)
-
-Make it an `asset` group ([`montage.md`](montage.md)). **Obey `pacing`:** on a `beat_cut`
-frame use `beat_cut` (one clip per anchor) or `bg_under_text`; on a `phrase_flow` frame use
-`ken_burns` or a slow crossfade — **never** per-onset hard cuts. Assets are additive: if none
-fits a group, fall back to template / free (typography is the floor — a complete video needs
-no assets).
-
-## Copy (you own the words)
-
-- Keep exact user words; else invent with taste, on the brief's mood.
-- **Message vs texture:** a readable word holds ≥1 beat (headline 3–8, sentence 4–10), stable + focal; a word held <1 beat is texture (strobe / grid / ticks). Never force a message onto a sub-beat — demote it to texture.
-- Place copy into the template's text params, onto a free group's anchors, or as an asset group's `overlay_copy`. Declare the anchor + accumulate / stagger intent; leave micro-timing to the worker.
-- A closing logo / CTA lands on the final hit / hard stop and holds through trailing silence.
-
-## Transitions (you do not emit them)
-
-Everything is a **0ms hard cut** for now. **frame → frame** is owned by the assembler
-(back-to-back files); adjacent `span_sec` already imply the cut. **group → group inside a
-frame** is owned by the worker on its frame timeline; you only set each group's `span_sec`.
-
-## Write + validate
-
-Complete `STORYBOARD.md` ([`storyboard-format.md`](storyboard-format.md)), then run
-`node scripts/validate-plan.mjs` and fix every `✗`. Show the user a frame-by-frame summary and
-iterate until approved.
-
-## Self-check
-
-- `frame.md` is a verbatim copy of one preset; frontmatter `style.font` / `style.palette` are drawn from it (exact values).
-- Every frame became ≥1 group; groups tile the frame span in order; no group < ~1 bar; no group boundary inside a `rolls[]` run.
-- Each group is exactly one of template / free_design / asset.
-- Template `params` keys match the catalog entry; `role_bindings` / `anchors` use real audiomap seconds.
-- Asset treatments obey `pacing` (no `beat_cut` on a `phrase_flow` frame).
-- Every group's palette draws from the one brand palette.
-- `duration_s == audiomap.audio.duration_sec`; `validate-plan.mjs` passes.
+# Planning (Step 3) — pick the brand, fill every frame
+
+At Step 3 **you (the orchestrator)** turn the Step-2 skeleton into a complete, approved
+`STORYBOARD.md`. You edit the **same file** in place: pick the brand spine, then for each
+frame decide its **groups**, give each group a treatment, bind real beat anchors, and write
+the copy.
+
+Your mantra: **music is the spine; a template is a head start, not a cage; typography is the
+floor and assets are an optional ingredient on the same beat grid.**
+
+**You own WHAT, not HOW.** You name the template / primitives, the content, the brand, the
+anchor seconds, and the intent. The frame-worker (Step 4) decides HOW — micro-timing,
+realization, intra-frame cuts. **Never write millisecond tweens into the storyboard.**
+
+## Inputs
+
+- The Step-2 skeleton already in `STORYBOARD.md` — frames with `span_sec` + `pacing` + `mood` + `feel`.
+- `audiomap.json` — timing truth; read the real anchor seconds inside each frame's span.
+- [`template-catalog.md`](template-catalog.md) — the template selection menu.
+- [`motion-primitive-catalog.md`](motion-primitive-catalog.md) — the free-compose menu (L0 recipes).
+- [`montage.md`](montage.md) — asset treatments (only if the user supplied images/videos).
+- User brief / supplied copy — topic, mood, exact words to keep.
+
+## Step A — pick the brand spine (one preset, unmodified)
+
+The whole video shares one type family + palette. Pick **one ready-made preset** from
+`../hyperframes-creative/frame-presets/` using the preset table in
+`../hyperframes-creative/references/design-spec.md` — choose by the track's mood + the brief,
+and **only its fonts + colors matter** (templates own composition + motion; the preset only
+sets the look). Copy it in **unmodified**:
+
+```bash
+cp ../hyperframes-creative/frame-presets/<preset>/FRAME.md "$PROJECT_DIR/frame.md"
+```
+
+Then fill the storyboard frontmatter `style` from it: the `font` from its `typography:` and a
+≤4–6 swatch `palette` from its `colors:`. **Quote the hex / family verbatim — never invent or
+round.** Every group's palette params draw from this one palette; that unity is what makes
+different templates read as one piece.
+
+## Step B — per frame, decide its groups
+
+A frame is usually **one group** (one template or one free composition spanning the frame).
+Subdivide into 2+ groups **only when a single treatment can't cover the frame** — e.g. a busy
+opener plus a closing lockup. When you split, cut at a **real audiomap anchor** inside the
+frame's span (a `key_moment` / `phrase` edge / onset-cluster gap), **never inside a `rolls[]`
+run**, and keep every group **≥ ~1 bar**. Density does **not** force more groups — a dense
+frame is usually ONE group whose template absorbs the density internally (a meta-template like
+`poster-tile-mosaic`). **Group count tracks distinct treatments, not beats.**
+
+## Step C — per group, pick a treatment (exactly one of three)
+
+### A. Match a template
+
+Read [`template-catalog.md`](template-catalog.md). Match the group's `feel` + `mood` + `pacing`
+to a template's **Reach for it when**; take the closest fit. Then bind it:
+
+- Fill `params` (keys from the catalog entry) — your copy into text slots, palette from the brand spine, `duration` = the group's span length.
+- Fill `role_bindings` with this group's **real anchor seconds** read from `audiomap.json` over its span (not example times).
+- If the template's natural stop and the group's span end disagree, snap to the nearest anchor.
+
+### B. Free-compose (no template fits)
+
+Write a `free_design` — one visual thesis from [`motion-primitive-catalog.md`](motion-primitive-catalog.md)
+(a dominant system + the named L0 primitives + a density topology) + `anchors` (the real
+beat / onset seconds the moves ride). Free-compose is a **first-class** choice, written as
+carefully as a matched group — never a failure.
+
+### C. Asset treatment (only when the user supplied assets and they fit)
+
+Make it an `asset` group ([`montage.md`](montage.md)). **Obey `pacing`:** on a `beat_cut`
+frame use `beat_cut` (one clip per anchor) or `bg_under_text`; on a `phrase_flow` frame use
+`ken_burns` or a slow crossfade — **never** per-onset hard cuts. Assets are additive: if none
+fits a group, fall back to template / free (typography is the floor — a complete video needs
+no assets).
+
+## Copy (you own the words)
+
+- Keep exact user words; else invent with taste, on the brief's mood.
+- **Message vs texture:** a readable word holds ≥1 beat (headline 3–8, sentence 4–10), stable + focal; a word held <1 beat is texture (strobe / grid / ticks). Never force a message onto a sub-beat — demote it to texture.
+- Place copy into the template's text params, onto a free group's anchors, or as an asset group's `overlay_copy`. Declare the anchor + accumulate / stagger intent; leave micro-timing to the worker.
+- A closing logo / CTA lands on the final hit / hard stop and holds through trailing silence.
+
+## Transitions (you do not emit them)
+
+Everything is a **0ms hard cut** for now. **frame → frame** is owned by the assembler
+(back-to-back files); adjacent `span_sec` already imply the cut. **group → group inside a
+frame** is owned by the worker on its frame timeline; you only set each group's `span_sec`.
+
+## Write + validate
+
+Complete `STORYBOARD.md` ([`storyboard-format.md`](storyboard-format.md)), then run
+`node scripts/validate-plan.mjs` and fix every `✗`. Show the user a frame-by-frame summary and
+iterate until approved.
+
+## Self-check
+
+- `frame.md` is a verbatim copy of one preset; frontmatter `style.font` / `style.palette` are drawn from it (exact values).
+- Every frame became ≥1 group; groups tile the frame span in order; no group < ~1 bar; no group boundary inside a `rolls[]` run.
+- Each group is exactly one of template / free_design / asset.
+- Template `params` keys match the catalog entry; `role_bindings` / `anchors` use real audiomap seconds.
+- Asset treatments obey `pacing` (no `beat_cut` on a `phrase_flow` frame).
+- Every group's palette draws from the one brand palette.
+- `duration_s == audiomap.audio.duration_sec`; `validate-plan.mjs` passes.

package/assets/.agent/skills/music-to-video/references/storyboard-format.md

@@ -1,94 +1,94 @@
-# STORYBOARD.md format — frames → groups
-
-`STORYBOARD.md` is the single reviewable plan the user approves at Step 3 and the **manual**
-each frame-worker follows at Step 4. It is **hierarchical**: one block per **frame**, written
-as a `## Frame N — <frame_id>` heading (the parser recognizes `Frame`). **One frame = one
-scene = one composition file.** Inside each frame block are its **groups** (the treatment
-units). The assembler reads the frame level (`duration` → `data-start`, `src`); the worker
-reads its own frame block. A frame's **composition id = its `src` file stem**
-(`compositions/frames/01-f1.html` → `01-f1`), which the worker uses as `data-composition-id`
-and the `window.__timelines` key.
-
-Step 2 writes the skeleton (frame fields, groups `TBD`); Step 3 fills the groups + brand. It
-is a build spec, not code — the planner writes WHAT, the worker decides HOW. **Never write
-millisecond tweens here.**
-
-## File shape
-
-YAML frontmatter (the video-wide spine) + one `## Frame N — <frame_id>` block per frame.
-
-```markdown
----
-compositionId: bgm
-duration_s: 30.0 # == audiomap.audio.duration_sec, exactly
-canvas: { w: 1920, h: 1080, fps: 30 }
-style: # brand spine — from the chosen frame.md preset (Step 3)
-  font: "EB Garamond / Inter / JetBrains Mono" # the preset's typography, verbatim
-  palette: ["#FAF9F5", "#141413", "#CC785C", "#181715"] # ≤4–6 swatches from the preset's colors
-assets: false # false, or a note like "assets/ has 6 user photos"
-build_notes: ["one paused timeline per frame", "no remote assets"]
-avoid: ["generic slideshow", "tiny unreadable hero text"]
----
-
-## Frame 1 — f1
-
-- src: compositions/frames/01-f1.html # worker writes here; assembler refs it; stem (01-f1) = composition id
-- duration: 7.198s # = span length; the assembler reads this for cumulative data-start
-- span_sec: [0.0, 7.198] # track seconds; frames tile the track
-- pacing: beat_cut # beat_cut | phrase_flow (from the skeleton; obey it)
-- mood: [hype]
-- feel: accelerating onset stream into a held downbeat
-
-### Groups
-
-- **g1** — template: `intro-kinetic-cascade`
-  - span_sec: [0.0, 4.017] # frame-LOCAL build is 0-based; these are TRACK seconds (worker subtracts frame start)
-  - params: { theme: "light", icon: "bolt", phrases: "[…]", climax: "{…}" }
-  - role_bindings: { phrase: { times: [0.14, 0.55, 0.87] }, climax: { in: 3.79, iconAt: 4.9 } }
-  - copy: "GROWTH THROUGH CREATIVITY"
-- **g2** — free_design
-  - span_sec: [4.017, 7.198]
-  - free_design: { dominant_system: "per-onset typography", primitives: ["content-swap", "braam-punch"], density_topology: "accumulate" }
-  - anchors: [4.10, 4.80, 5.50, 6.20] # onset seconds the reveals ride (from audiomap)
-  - copy: ["BUILD", "SHIP", "REPEAT"]
-
-## Frame 2 — f2
-
-…
-```
-
-## Frame block — required fields
-
-| field                             | meaning                                                                                                                        |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| heading `## Frame N — <frame_id>` | `frame_id` matches the `src` stem; `N` = the 1-based index.                                                                    |
-| `src`                             | `compositions/frames/NN-<frame_id>.html` — where the worker writes; the assembler references it. Stem = `data-composition-id`. |
-| `duration`                        | the frame span length in seconds (e.g. `7.198s`) — **required**; the assembler sums these for cumulative `data-start`.         |
-| `span_sec`                        | `[start, end]` track seconds. `duration = end − start`.                                                                        |
-| `pacing`                          | `beat_cut` \| `phrase_flow` — from the skeleton; the worker must obey (no hard-cut on `phrase_flow`).                          |
-| `mood`, `feel`                    | from the skeleton; tone + the one-line music situation the planner matched against.                                            |
-| `### Groups` list                 | ≥1 group; groups tile the frame span in order.                                                                                 |
-
-## Group entry — exactly one of three kinds
-
-Every group is **template** OR **free_design** OR **asset** — never two, never none. All three
-carry `span_sec` (track seconds, tiling the frame) and may carry `copy`.
-
-- **template** — `template: <catalog id>` + `params` (keys from the catalog entry) + `role_bindings` (real audiomap anchor seconds) + `copy`.
-- **free_design** — `free_design: { dominant_system, primitives: [catalog ids], density_topology }` + `anchors` (real beat / onset seconds) + `copy`.
-- **asset** — `asset: { treatment, clips: [public/…], anchors?, overlay_copy? }`. `treatment` ∈ `beat_cut` (one clip per anchor — only on a `beat_cut` frame) | `ken_burns` (slow push — fits `phrase_flow`) | `bg_under_text` (clip dimmed behind a template / free group). See [`montage.md`](montage.md).
-
-## Rules
-
-- Frames tile the track (gap-free, first at 0, last at `duration_s`); a frame's groups tile its span; no group < ~1 bar; no group boundary inside a `rolls[]` run.
-- `params` keys come from the template's [`template-catalog.md`](template-catalog.md) entry.
-- All anchor seconds are **track seconds from `audiomap.json`** — the worker converts to frame-local by subtracting the frame start.
-- A `phrase_flow` frame MUST NOT use `beat_cut` asset treatment or per-onset hard cuts.
-- The brand `style` is set once; every group's palette draws from it.
-- Reviewable prose-plus-data; keep it scannable. No GSAP, no millisecond timing.
-
-## Self-check (the planner runs `validate-plan.mjs`)
-
-- frontmatter has `compositionId`, `duration_s` (== audiomap), `canvas`, `style`.
-- every frame has `span_sec` + `src` + positive `duration` + `pacing` + ≥1 group; frames tile the track.
-- every group is exactly one of template / free_design / asset; template ids exist in the catalog; anchors are real audiomap seconds; `phrase_flow` frames have no `beat_cut`.
+# STORYBOARD.md format — frames → groups
+
+`STORYBOARD.md` is the single reviewable plan the user approves at Step 3 and the **manual**
+each frame-worker follows at Step 4. It is **hierarchical**: one block per **frame**, written
+as a `## Frame N — <frame_id>` heading (the parser recognizes `Frame`). **One frame = one
+scene = one composition file.** Inside each frame block are its **groups** (the treatment
+units). The assembler reads the frame level (`duration` → `data-start`, `src`); the worker
+reads its own frame block. A frame's **composition id = its `src` file stem**
+(`compositions/frames/01-f1.html` → `01-f1`), which the worker uses as `data-composition-id`
+and the `window.__timelines` key.
+
+Step 2 writes the skeleton (frame fields, groups `TBD`); Step 3 fills the groups + brand. It
+is a build spec, not code — the planner writes WHAT, the worker decides HOW. **Never write
+millisecond tweens here.**
+
+## File shape
+
+YAML frontmatter (the video-wide spine) + one `## Frame N — <frame_id>` block per frame.
+
+```markdown
+---
+compositionId: bgm
+duration_s: 30.0 # == audiomap.audio.duration_sec, exactly
+canvas: { w: 1920, h: 1080, fps: 30 }
+style: # brand spine — from the chosen frame.md preset (Step 3)
+  font: "EB Garamond / Inter / JetBrains Mono" # the preset's typography, verbatim
+  palette: ["#FAF9F5", "#141413", "#CC785C", "#181715"] # ≤4–6 swatches from the preset's colors
+assets: false # false, or a note like "assets/ has 6 user photos"
+build_notes: ["one paused timeline per frame", "no remote assets"]
+avoid: ["generic slideshow", "tiny unreadable hero text"]
+---
+
+## Frame 1 — f1
+
+- src: compositions/frames/01-f1.html # worker writes here; assembler refs it; stem (01-f1) = composition id
+- duration: 7.198s # = span length; the assembler reads this for cumulative data-start
+- span_sec: [0.0, 7.198] # track seconds; frames tile the track
+- pacing: beat_cut # beat_cut | phrase_flow (from the skeleton; obey it)
+- mood: [hype]
+- feel: accelerating onset stream into a held downbeat
+
+### Groups
+
+- **g1** — template: `intro-kinetic-cascade`
+  - span_sec: [0.0, 4.017] # frame-LOCAL build is 0-based; these are TRACK seconds (worker subtracts frame start)
+  - params: { theme: "light", icon: "bolt", phrases: "[…]", climax: "{…}" }
+  - role_bindings: { phrase: { times: [0.14, 0.55, 0.87] }, climax: { in: 3.79, iconAt: 4.9 } }
+  - copy: "GROWTH THROUGH CREATIVITY"
+- **g2** — free_design
+  - span_sec: [4.017, 7.198]
+  - free_design: { dominant_system: "per-onset typography", primitives: ["content-swap", "braam-punch"], density_topology: "accumulate" }
+  - anchors: [4.10, 4.80, 5.50, 6.20] # onset seconds the reveals ride (from audiomap)
+  - copy: ["BUILD", "SHIP", "REPEAT"]
+
+## Frame 2 — f2
+
+…
+```
+
+## Frame block — required fields
+
+| field                             | meaning                                                                                                                        |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| heading `## Frame N — <frame_id>` | `frame_id` matches the `src` stem; `N` = the 1-based index.                                                                    |
+| `src`                             | `compositions/frames/NN-<frame_id>.html` — where the worker writes; the assembler references it. Stem = `data-composition-id`. |
+| `duration`                        | the frame span length in seconds (e.g. `7.198s`) — **required**; the assembler sums these for cumulative `data-start`.         |
+| `span_sec`                        | `[start, end]` track seconds. `duration = end − start`.                                                                        |
+| `pacing`                          | `beat_cut` \| `phrase_flow` — from the skeleton; the worker must obey (no hard-cut on `phrase_flow`).                          |
+| `mood`, `feel`                    | from the skeleton; tone + the one-line music situation the planner matched against.                                            |
+| `### Groups` list                 | ≥1 group; groups tile the frame span in order.                                                                                 |
+
+## Group entry — exactly one of three kinds
+
+Every group is **template** OR **free_design** OR **asset** — never two, never none. All three
+carry `span_sec` (track seconds, tiling the frame) and may carry `copy`.
+
+- **template** — `template: <catalog id>` + `params` (keys from the catalog entry) + `role_bindings` (real audiomap anchor seconds) + `copy`.
+- **free_design** — `free_design: { dominant_system, primitives: [catalog ids], density_topology }` + `anchors` (real beat / onset seconds) + `copy`.
+- **asset** — `asset: { treatment, clips: [public/…], anchors?, overlay_copy? }`. `treatment` ∈ `beat_cut` (one clip per anchor — only on a `beat_cut` frame) | `ken_burns` (slow push — fits `phrase_flow`) | `bg_under_text` (clip dimmed behind a template / free group). See [`montage.md`](montage.md).
+
+## Rules
+
+- Frames tile the track (gap-free, first at 0, last at `duration_s`); a frame's groups tile its span; no group < ~1 bar; no group boundary inside a `rolls[]` run.
+- `params` keys come from the template's [`template-catalog.md`](template-catalog.md) entry.
+- All anchor seconds are **track seconds from `audiomap.json`** — the worker converts to frame-local by subtracting the frame start.
+- A `phrase_flow` frame MUST NOT use `beat_cut` asset treatment or per-onset hard cuts.
+- The brand `style` is set once; every group's palette draws from it.
+- Reviewable prose-plus-data; keep it scannable. No GSAP, no millisecond timing.
+
+## Self-check (the planner runs `validate-plan.mjs`)
+
+- frontmatter has `compositionId`, `duration_s` (== audiomap), `canvas`, `style`.
+- every frame has `span_sec` + `src` + positive `duration` + `pacing` + ≥1 group; frames tile the track.
+- every group is exactly one of template / free_design / asset; template ids exist in the catalog; anchors are real audiomap seconds; `phrase_flow` frames have no `beat_cut`.

package/assets/.agent/skills/music-to-video/references/template-catalog.md

@@ -1,106 +1,106 @@
-# Template catalog — the selection menu (Step 3)
-
-Reverse-engineered, asset-free **group templates**. This file is the **only** thing the
-planner reads to pick one — you do **not** open the template's `index.html` to choose. One
-template realizes **one group** of a frame (a frame may stack several groups; the brand spine
-unifies them).
-
-**How to pick.** For each group, read its frame's `pacing` + `mood` + the one-line music
-situation from the skeleton, then scan **Reach for it when** + **Best span** below and take the
-closest fit. If nothing fits, **free-compose** from
-[`motion-primitive-catalog.md`](motion-primitive-catalog.md) — that is a first-class choice, not a
-failure.
-
-**Brand comes from `frame.md`, not the template.** Templates ship their own demo palette
-(`theme` / `palette` / color params). Fill those params from the project's `frame.md` (the
-chosen preset's colors + fonts) so every group reads as one piece — the template supplies the
-**motion + layout**, the preset supplies the **look**.
-
-**Params** are listed so you can fill content slots in the storyboard. Exact semantics +
-defaults live in each template's `index.html` (`data-composition-variables`) — the frame-worker
-reads those at build time; you only name the values.
-
-Pacing tag: every template below is **beat_cut** except `held-message-living-field`
-(**phrase_flow**). Never put a beat_cut template on a phrase_flow frame.
-
-## Group duration discipline
-
-Template choice is per **group**, not per frame. A frame longer than a template's **Best span**
-should usually split into multiple groups at real audiomap anchors (`SURGE`, `DROP`, roll edge,
-hard_stop, phrase edge) instead of stretching one template across the whole frame.
-
-- **Best span** below is the active treatment span: the part where the template's system is doing
-  meaningful motion. A short readable hold at the end is fine; a long empty tail means pick another
-  group.
-- **Frames over ~6s** usually need 2+ groups. Beat-cut exceptions are rich programs with real
-  sub-phases (`poster-tile-mosaic`, sometimes `card-flyby`); phrase-flow exceptions use
-  `held-message-living-field`.
-- **Roll templates are one-roll tools.** If a frame has two rolls or a drop between rolls, split it
-  into two groups.
-- Do not extend by slowing every tween. Preserve the template's motion feel, then fill extra time
-  with a hold / palette change / new group.
-
----
-
-### card-flyby
-
-- **What** — a depth column of cards rolls forward through perspective; each landing beat tumbles the next card into the front slot with a solid colored wipe, the old front falls toward camera, dwells shrink card-to-card so the deck accelerates into a held final card.
-- **Reach for it when** — a stream of discrete onsets that **accelerate** (gaps shrinking / a build into a downbeat) and you want to flash a **sequence of items** — titles, projects, posters, tiles — one per hit, climaxing on a held card.
-- **Best span** — **4-6.5s** for 4-7 landings plus a short final hold; split at the next downbeat if it wants to run **>7s**.
-- **Params** — `theme`, `bgColor`, `cards`, `landings`, `yaw`
-
-### held-message-living-field · phrase_flow
-
-- **What** — a readable mark (logo / word / title) held dead still over a soft, color-shifting blurred field; only the field breathes.
-- **Reach for it when** — a **calm / sparse** stretch with an onset desert — energy present but few or no onsets (a held pad or riser); you have one word or mark to hold and let breathe.
-- **Best span** — **6-16s**; this is the long-group exception. Under 4s feels underdeveloped; over ~20s needs a state change or another group.
-- **Params** — `markText`, `titleText`, `tagText`, `palette`, `flowSpeed`, `duration`
-
-### held-text-strobe-burst
-
-- **What** — a dead-still word whose letters flip through texture-filled frames (texture-clipped fill + per-frame tint + bg color) every ~3 frames, in short bursts pinned to a roll.
-- **Reach for it when** — a **dense, hard-hitting roll / fill** and a single word you want to strobe through textures for a few bars. (Ships texture-mask PNGs under `assets/`.)
-- **Best span** — **1.2-3.5s**; strobe fatigue starts fast, so cap at ~4s and cut to a cleaner system.
-- **Params** — `markText`, `fontStyle`, `markScale`, `idleColor`, `idleInk`, `frames`, `strobePlan`, `decor`, `duration`
-
-### intro-kinetic-cascade
-
-- **What** — a line laid out as a sequence of big editorial **phrases** (each a stacked poster with one enlarged hero word), revealed word-by-word on its anchors, hard cut between phrases, climaxing on a phrase that slides in with a swappable ringing **icon** (bell / cursor / sparkle / emoji / SVG).
-- **Reach for it when** — an **intro / opening statement**: a short line to land word-by-word as big type, climaxing on one keyword + an icon. Medium-or-more energy, steady grid.
-- **Best span** — **3.5-7s** for 2-4 phrase beats; if the statement needs more time, make the next clause a new group.
-- **Params** — `theme`, `icon`, `phrases`, `climax`
-
-### logo-split-lockup-pulse
-
-- **What** — a two-part mark joined at center splits left↔right to open a gap, grows a center word-lockup one word per onset (key word lands on the downbeat surge), snap-closes on a hit, then pulses with the beat.
-- **Reach for it when** — a short **logo / brand sting** (not a typed sentence): fast dense onsets + a sustained roll bed to pulse on, with a left/right bracketing mark.
-- **Best span** — **2-4s**; at **>4.5s** it reads like a sting stretched too long. Follow with a separate held-lockup / next idea group.
-- **Params** — `bgColor`, `markColor`, `textColor`, `leftMark`, `rightMark`, `word1`, `word2`, `word3`, `word4`
-
-### poster-tile-mosaic
-
-- **What** — a packed **mosaic** of different-sized colored tiles that tessellate to fill the frame (no overlap), driven by interchangeable beat-synced operations: staggered enter/exit, locked global recolor, snake-fill + overlay.
-- **Reach for it when** — many discrete, individually-placeable onsets (a hit for every tile move) with distinct sub-phases you want articulated differently (accumulate → recolor-on-roll → fill-then-drop). A dense section best held as **one** rich tile program rather than split.
-- **Best span** — **4-7s**, up to **8s** only when the program has clear sub-phases. If the music changes regime, split even if the tile system could continue.
-- **Params** — `bgColor`, `tiles`, `bands`, `gap`, `showText`, `labels`, `program`
-
-### roll-flipbook-word-cycle
-
-- **What** — a hi-hat roll drives a centred word that flips every 16th-note through a word list; optionally the flicker resolves and locks into a final phrase.
-- **Reach for it when** — a **fast sustained-fill roll** (hundreds of hits/min, ~16th-note) with no single readable message — fill the roll with a rapidly-cycling word flipbook.
-- **Best span** — **1.2-3.8s**, one roll into one resolve. Two rolls, or a drop between rolls, means two groups.
-- **Params** — `bgColor`, `textColor`, `accentColor`, `flipWords`, `resolveText`, `periodChar`
-
-### split-anchor-word-slot
-
-- **What** — a held left anchor column of fixed-word rows beside a torn-paper word-slot box on the right, driven by beat-synced operators: anchor lock-in, slot word-group cycle (in/out + per-line color), full-scene background flip, per-beat jitter, box-zoom exit wipe. Row count + number of flips are data.
-- **Reach for it when** — a short section with a **held idea** (a brand / name to anchor on the left) **and** a stream of onsets popping separate words on the right, plus a dense run to ride a shake on and a strong downbeat to wipe out into.
-- **Best span** — **3-6s**; above ~6.5s the fixed anchor goes stale unless the right slot enters a new group/program.
-- **Params** — `bgColor`, `anchors`, `theme`, `showText`, `program`
-
-### typewriter-phrase-keyword-shuffle
-
-- **What** — words type in one-per-onset to spell a phrase, then one keyword cycles typefaces on the beat while everything else holds dead still.
-- **Reach for it when** — a steady grid with a **continuous onset stream** (no desert): a phrase to type out, then a keyword to shuffle. The inverse of `held-message-living-field` (which wants an onset desert).
-- **Best span** — **2.5-5s**; if the phrase cannot type and shuffle inside ~5s, reduce words or split the sentence across groups.
-- **Params** — `bgColor`, `textColor`, `accentColor`, `lead1`, `lead2`, `lead3`, `keyword`, `periodChar`
+# Template catalog — the selection menu (Step 3)
+
+Reverse-engineered, asset-free **group templates**. This file is the **only** thing the
+planner reads to pick one — you do **not** open the template's `index.html` to choose. One
+template realizes **one group** of a frame (a frame may stack several groups; the brand spine
+unifies them).
+
+**How to pick.** For each group, read its frame's `pacing` + `mood` + the one-line music
+situation from the skeleton, then scan **Reach for it when** + **Best span** below and take the
+closest fit. If nothing fits, **free-compose** from
+[`motion-primitive-catalog.md`](motion-primitive-catalog.md) — that is a first-class choice, not a
+failure.
+
+**Brand comes from `frame.md`, not the template.** Templates ship their own demo palette
+(`theme` / `palette` / color params). Fill those params from the project's `frame.md` (the
+chosen preset's colors + fonts) so every group reads as one piece — the template supplies the
+**motion + layout**, the preset supplies the **look**.
+
+**Params** are listed so you can fill content slots in the storyboard. Exact semantics +
+defaults live in each template's `index.html` (`data-composition-variables`) — the frame-worker
+reads those at build time; you only name the values.
+
+Pacing tag: every template below is **beat_cut** except `held-message-living-field`
+(**phrase_flow**). Never put a beat_cut template on a phrase_flow frame.
+
+## Group duration discipline
+
+Template choice is per **group**, not per frame. A frame longer than a template's **Best span**
+should usually split into multiple groups at real audiomap anchors (`SURGE`, `DROP`, roll edge,
+hard_stop, phrase edge) instead of stretching one template across the whole frame.
+
+- **Best span** below is the active treatment span: the part where the template's system is doing
+  meaningful motion. A short readable hold at the end is fine; a long empty tail means pick another
+  group.
+- **Frames over ~6s** usually need 2+ groups. Beat-cut exceptions are rich programs with real
+  sub-phases (`poster-tile-mosaic`, sometimes `card-flyby`); phrase-flow exceptions use
+  `held-message-living-field`.
+- **Roll templates are one-roll tools.** If a frame has two rolls or a drop between rolls, split it
+  into two groups.
+- Do not extend by slowing every tween. Preserve the template's motion feel, then fill extra time
+  with a hold / palette change / new group.
+
+---
+
+### card-flyby
+
+- **What** — a depth column of cards rolls forward through perspective; each landing beat tumbles the next card into the front slot with a solid colored wipe, the old front falls toward camera, dwells shrink card-to-card so the deck accelerates into a held final card.
+- **Reach for it when** — a stream of discrete onsets that **accelerate** (gaps shrinking / a build into a downbeat) and you want to flash a **sequence of items** — titles, projects, posters, tiles — one per hit, climaxing on a held card.
+- **Best span** — **4-6.5s** for 4-7 landings plus a short final hold; split at the next downbeat if it wants to run **>7s**.
+- **Params** — `theme`, `bgColor`, `cards`, `landings`, `yaw`
+
+### held-message-living-field · phrase_flow
+
+- **What** — a readable mark (logo / word / title) held dead still over a soft, color-shifting blurred field; only the field breathes.
+- **Reach for it when** — a **calm / sparse** stretch with an onset desert — energy present but few or no onsets (a held pad or riser); you have one word or mark to hold and let breathe.
+- **Best span** — **6-16s**; this is the long-group exception. Under 4s feels underdeveloped; over ~20s needs a state change or another group.
+- **Params** — `markText`, `titleText`, `tagText`, `palette`, `flowSpeed`, `duration`
+
+### held-text-strobe-burst
+
+- **What** — a dead-still word whose letters flip through texture-filled frames (texture-clipped fill + per-frame tint + bg color) every ~3 frames, in short bursts pinned to a roll.
+- **Reach for it when** — a **dense, hard-hitting roll / fill** and a single word you want to strobe through textures for a few bars. (Ships texture-mask PNGs under `assets/`.)
+- **Best span** — **1.2-3.5s**; strobe fatigue starts fast, so cap at ~4s and cut to a cleaner system.
+- **Params** — `markText`, `fontStyle`, `markScale`, `idleColor`, `idleInk`, `frames`, `strobePlan`, `decor`, `duration`
+
+### intro-kinetic-cascade
+
+- **What** — a line laid out as a sequence of big editorial **phrases** (each a stacked poster with one enlarged hero word), revealed word-by-word on its anchors, hard cut between phrases, climaxing on a phrase that slides in with a swappable ringing **icon** (bell / cursor / sparkle / emoji / SVG).
+- **Reach for it when** — an **intro / opening statement**: a short line to land word-by-word as big type, climaxing on one keyword + an icon. Medium-or-more energy, steady grid.
+- **Best span** — **3.5-7s** for 2-4 phrase beats; if the statement needs more time, make the next clause a new group.
+- **Params** — `theme`, `icon`, `phrases`, `climax`
+
+### logo-split-lockup-pulse
+
+- **What** — a two-part mark joined at center splits left↔right to open a gap, grows a center word-lockup one word per onset (key word lands on the downbeat surge), snap-closes on a hit, then pulses with the beat.
+- **Reach for it when** — a short **logo / brand sting** (not a typed sentence): fast dense onsets + a sustained roll bed to pulse on, with a left/right bracketing mark.
+- **Best span** — **2-4s**; at **>4.5s** it reads like a sting stretched too long. Follow with a separate held-lockup / next idea group.
+- **Params** — `bgColor`, `markColor`, `textColor`, `leftMark`, `rightMark`, `word1`, `word2`, `word3`, `word4`
+
+### poster-tile-mosaic
+
+- **What** — a packed **mosaic** of different-sized colored tiles that tessellate to fill the frame (no overlap), driven by interchangeable beat-synced operations: staggered enter/exit, locked global recolor, snake-fill + overlay.
+- **Reach for it when** — many discrete, individually-placeable onsets (a hit for every tile move) with distinct sub-phases you want articulated differently (accumulate → recolor-on-roll → fill-then-drop). A dense section best held as **one** rich tile program rather than split.
+- **Best span** — **4-7s**, up to **8s** only when the program has clear sub-phases. If the music changes regime, split even if the tile system could continue.
+- **Params** — `bgColor`, `tiles`, `bands`, `gap`, `showText`, `labels`, `program`
+
+### roll-flipbook-word-cycle
+
+- **What** — a hi-hat roll drives a centred word that flips every 16th-note through a word list; optionally the flicker resolves and locks into a final phrase.
+- **Reach for it when** — a **fast sustained-fill roll** (hundreds of hits/min, ~16th-note) with no single readable message — fill the roll with a rapidly-cycling word flipbook.
+- **Best span** — **1.2-3.8s**, one roll into one resolve. Two rolls, or a drop between rolls, means two groups.
+- **Params** — `bgColor`, `textColor`, `accentColor`, `flipWords`, `resolveText`, `periodChar`
+
+### split-anchor-word-slot
+
+- **What** — a held left anchor column of fixed-word rows beside a torn-paper word-slot box on the right, driven by beat-synced operators: anchor lock-in, slot word-group cycle (in/out + per-line color), full-scene background flip, per-beat jitter, box-zoom exit wipe. Row count + number of flips are data.
+- **Reach for it when** — a short section with a **held idea** (a brand / name to anchor on the left) **and** a stream of onsets popping separate words on the right, plus a dense run to ride a shake on and a strong downbeat to wipe out into.
+- **Best span** — **3-6s**; above ~6.5s the fixed anchor goes stale unless the right slot enters a new group/program.
+- **Params** — `bgColor`, `anchors`, `theme`, `showText`, `program`
+
+### typewriter-phrase-keyword-shuffle
+
+- **What** — words type in one-per-onset to spell a phrase, then one keyword cycles typefaces on the beat while everything else holds dead still.
+- **Reach for it when** — a steady grid with a **continuous onset stream** (no desert): a phrase to type out, then a keyword to shuffle. The inverse of `held-message-living-field` (which wants an onset desert).
+- **Best span** — **2.5-5s**; if the phrase cannot type and shuffle inside ~5s, reduce words or split the sentence across groups.
+- **Params** — `bgColor`, `textColor`, `accentColor`, `lead1`, `lead2`, `lead3`, `keyword`, `periodChar`