takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/motion-graphics/catalog-map.md

@@ -1,40 +1,40 @@
-# Director → catalog block map (reuse-first)
-
-The Builder's **default is to compose existing HF catalog blocks, not hand-author.** `npx hyperframes add <block>` drops a block's source into `compositions/`; the Builder then **customizes in place** — most blocks bake their content/data into their own script (only a few expose CSS-var `params`), so reuse = **add + edit**, not pure variable injection. Hand-author only (a) gaps no block covers and (b) the asset-fusion affordance binding.
-
-After classifying intent → category, the **Director names the block(s) + what to customize** in the shot-plan IR:
-
-```jsonc
-"content": { "block": "data-chart", "customize": { "data": [...], "headline": "…", "palette": ["…"] } }
-```
-
-## Category → block(s)
-
-| Category               | Borrow from catalog                                                                                                                                                                                                                                                                                                                                                                                                | Customize                                                                                        | Gaps → hand-author                                                                                             |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| **kinetic-typo**       | one of **18 `caption-*`** (kinetic-slam, editorial-emphasis, clip-wipe, gradient-fill, neon-glow, glitch-rgb, matrix-decode, particle-burst, weight-shift, pill-karaoke, highlight, blend-difference…)                                                                                                                                                                                                             | words; `emphasis_words` → `word--emphasis`; palette; font; timing                                | a motif none of the 18 cover                                                                                   |
-| **charts**             | `data-chart` (bar+line, staggered, value labels)                                                                                                                                                                                                                                                                                                                                                                   | edit the data array + headline/subtitle; `--bg`/`--text`                                         | pie/donut, bar-chart-race, ring/%                                                                              |
-| **stat**               | `apple-money-count` (finance: $ counter + burst + SFX) **or** our generic `stat-motion` (any %/number + ring)                                                                                                                                                                                                                                                                                                      | target, prefix/suffix, label, palette                                                            | —                                                                                                              |
-| maps/geo               | **vector lane**: `us-map` (+bubble/hex/flow), `world-map`, `spain-map` + **hand-author** `geo-highlight`/`geo-flow`/`flag-borders`/`pin-rollout` (NOT in registry — build per `categories/maps/module.md`). **basemap lane** (real satellite/dark / zoom-to-place): bake via `categories/maps/bake-basemap.mjs` → `<video>` + geo-aligned SVG overlay (border draw-on + colour-block fills)                        | regions/data, palette, callouts/connectors, basemap style                                        | (basemap lane now covers real imagery + zoom-to-address — was the gap)                                         |
-| diagram                | `flowchart` (SVG connectors + nodes)                                                                                                                                                                                                                                                                                                                                                                               | nodes, edges, labels                                                                             | —                                                                                                              |
-| **code / code-reveal** | one of the **9 Code Animations** blocks: `code-typing` (live typing), `code-diff` (a change), `code-morph` (a refactor), `code-highlight` (spotlight a line), `code-scroll` (walk a file), `code-snippet-flight` (assemble); GPU hero reveals `code-3d-extrude` / `code-shader-dissolve` / `code-particle-assemble` for a title-card moment; for a static themed code/terminal window use a `code-snippet-*` block | the baked code string / diff / theme                                                             | a code motion none cover                                                                                       |
-| **brand reveal**       | `logo-outro` (piece assembly + glow + tagline + URL pill)                                                                                                                                                                                                                                                                                                                                                          | logo asset, tagline, URL, palette                                                                | —                                                                                                              |
-| transitions            | 15+ shader transitions (domain-warp, whip-pan, sdf-iris, glitch…)                                                                                                                                                                                                                                                                                                                                                  | direction, timing                                                                                | —                                                                                                              |
-| social overlay         | ig / tiktok / yt / x / reddit / spotify / macos cards                                                                                                                                                                                                                                                                                                                                                              | handle, metrics, avatar                                                                          | —                                                                                                              |
-| polish                 | grain-overlay, vignette, shimmer-sweep, texture-mask-text                                                                                                                                                                                                                                                                                                                                                          | intensity                                                                                        | —                                                                                                              |
-| **asset-fusion (RWA)** | **annotation kit from `north-korea-locked-down`** — scribble-circle draw-on, pop-up pill + pointer, red-wash, scanline, corners, camera push; + `us-map-bubble` callouts/connectors                                                                                                                                                                                                                                | asset, annotation position (`element_positions`), label, palette **eyedropper'd from the asset** | **NET-NEW (not in catalog): the affordance binding — asset geometry _becomes_ the chart axis (straw → gauge)** |
-
-## Reuse mechanics
-
-- `npx hyperframes add <block>` → source lands in `compositions/<block>.html`; inline it or reference via `data-composition-src`; customize content/data/palette/positions in place.
-- Blocks ship at fixed canvases (1920×1080 / 1080×1920 / 1080×1080) — match or adapt.
-- Blocks already follow the HF contract (paused timeline, seek) — keep it.
-
-## Asset-fusion: borrow + net-new (the only real net-new IP)
-
-Borrow `north-korea-locked-down`'s annotation _language_; the net-new is the RWA fusion _logic_ (see the RWA study):
-
-1. Classify the data type; read the asset's **geometric affordance** — linearity → timeline/gauge, volume/texture → pie, height → bar, container → exploded view.
-2. **`element_positions`** — measure the asset's feature (center / extent / safe-zones / avoid-zones). This is the reverse-engineer step (vision); in the prototype it's hand-estimated.
-3. **Eyedropper palette** from the asset (never generic #FFF/#000).
-4. **Two layers** — asset (z0, full-bleed) + data graphics fused to its geometry (z1+), anchored by `element_positions`; connectors/scribble physically tie the data to the asset; the asset stays visible.
+# Director → catalog block map (reuse-first)
+
+The Builder's **default is to compose existing HF catalog blocks, not hand-author.** `npx hyperframes add <block>` drops a block's source into `compositions/`; the Builder then **customizes in place** — most blocks bake their content/data into their own script (only a few expose CSS-var `params`), so reuse = **add + edit**, not pure variable injection. Hand-author only (a) gaps no block covers and (b) the asset-fusion affordance binding.
+
+After classifying intent → category, the **Director names the block(s) + what to customize** in the shot-plan IR:
+
+```jsonc
+"content": { "block": "data-chart", "customize": { "data": [...], "headline": "…", "palette": ["…"] } }
+```
+
+## Category → block(s)
+
+| Category               | Borrow from catalog                                                                                                                                                                                                                                                                                                                                                                                                | Customize                                                                                        | Gaps → hand-author                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **kinetic-typo**       | one of **18 `caption-*`** (kinetic-slam, editorial-emphasis, clip-wipe, gradient-fill, neon-glow, glitch-rgb, matrix-decode, particle-burst, weight-shift, pill-karaoke, highlight, blend-difference…)                                                                                                                                                                                                             | words; `emphasis_words` → `word--emphasis`; palette; font; timing                                | a motif none of the 18 cover                                                                                   |
+| **charts**             | `data-chart` (bar+line, staggered, value labels)                                                                                                                                                                                                                                                                                                                                                                   | edit the data array + headline/subtitle; `--bg`/`--text`                                         | pie/donut, bar-chart-race, ring/%                                                                              |
+| **stat**               | `apple-money-count` (finance: $ counter + burst + SFX) **or** our generic `stat-motion` (any %/number + ring)                                                                                                                                                                                                                                                                                                      | target, prefix/suffix, label, palette                                                            | —                                                                                                              |
+| maps/geo               | **vector lane**: `us-map` (+bubble/hex/flow), `world-map`, `spain-map` + **hand-author** `geo-highlight`/`geo-flow`/`flag-borders`/`pin-rollout` (NOT in registry — build per `categories/maps/module.md`). **basemap lane** (real satellite/dark / zoom-to-place): bake via `categories/maps/bake-basemap.mjs` → `<video>` + geo-aligned SVG overlay (border draw-on + colour-block fills)                        | regions/data, palette, callouts/connectors, basemap style                                        | (basemap lane now covers real imagery + zoom-to-address — was the gap)                                         |
+| diagram                | `flowchart` (SVG connectors + nodes)                                                                                                                                                                                                                                                                                                                                                                               | nodes, edges, labels                                                                             | —                                                                                                              |
+| **code / code-reveal** | one of the **9 Code Animations** blocks: `code-typing` (live typing), `code-diff` (a change), `code-morph` (a refactor), `code-highlight` (spotlight a line), `code-scroll` (walk a file), `code-snippet-flight` (assemble); GPU hero reveals `code-3d-extrude` / `code-shader-dissolve` / `code-particle-assemble` for a title-card moment; for a static themed code/terminal window use a `code-snippet-*` block | the baked code string / diff / theme                                                             | a code motion none cover                                                                                       |
+| **brand reveal**       | `logo-outro` (piece assembly + glow + tagline + URL pill)                                                                                                                                                                                                                                                                                                                                                          | logo asset, tagline, URL, palette                                                                | —                                                                                                              |
+| transitions            | 15+ shader transitions (domain-warp, whip-pan, sdf-iris, glitch…)                                                                                                                                                                                                                                                                                                                                                  | direction, timing                                                                                | —                                                                                                              |
+| social overlay         | ig / tiktok / yt / x / reddit / spotify / macos cards                                                                                                                                                                                                                                                                                                                                                              | handle, metrics, avatar                                                                          | —                                                                                                              |
+| polish                 | grain-overlay, vignette, shimmer-sweep, texture-mask-text                                                                                                                                                                                                                                                                                                                                                          | intensity                                                                                        | —                                                                                                              |
+| **asset-fusion (RWA)** | **annotation kit from `north-korea-locked-down`** — scribble-circle draw-on, pop-up pill + pointer, red-wash, scanline, corners, camera push; + `us-map-bubble` callouts/connectors                                                                                                                                                                                                                                | asset, annotation position (`element_positions`), label, palette **eyedropper'd from the asset** | **NET-NEW (not in catalog): the affordance binding — asset geometry _becomes_ the chart axis (straw → gauge)** |
+
+## Reuse mechanics
+
+- `npx hyperframes add <block>` → source lands in `compositions/<block>.html`; inline it or reference via `data-composition-src`; customize content/data/palette/positions in place.
+- Blocks ship at fixed canvases (1920×1080 / 1080×1920 / 1080×1080) — match or adapt.
+- Blocks already follow the HF contract (paused timeline, seek) — keep it.
+
+## Asset-fusion: borrow + net-new (the only real net-new IP)
+
+Borrow `north-korea-locked-down`'s annotation _language_; the net-new is the RWA fusion _logic_ (see the RWA study):
+
+1. Classify the data type; read the asset's **geometric affordance** — linearity → timeline/gauge, volume/texture → pie, height → bar, container → exploded view.
+2. **`element_positions`** — measure the asset's feature (center / extent / safe-zones / avoid-zones). This is the reverse-engineer step (vision); in the prototype it's hand-estimated.
+3. **Eyedropper palette** from the asset (never generic #FFF/#000).
+4. **Two layers** — asset (z0, full-bleed) + data graphics fused to its geometry (z1+), anchored by `element_positions`; connectors/scribble physically tie the data to the asset; the asset stays visible.

package/assets/.agent/skills/motion-graphics/categories/asset-fusion/module.md

@@ -1,37 +1,37 @@
-# asset-fusion — category module (search-driven · the net-new IP)
-
-**A real asset's geometry _becomes_ the chart** — RWA diegetic fusion (the straw becomes a gauge; a glass's liquid becomes a pie). Not in any catalog; the genuinely net-new capability. ~5–8s.
-
-## Source (Step 2)
-
-Search or generate one **hero asset** with strong geometric affordance. `asset_needs`: `{ kind: image, query|generate, treatment: cutout|none }`. Freeze it project-local.
-
-## Plan (Director Part 2) — the fusion logic
-
-1. Classify the **data type** (temporal / quantitative / proportion / spatial).
-2. Read the asset's **geometric affordance** — linearity → timeline/gauge · volume/texture → pie · height → bar · container → exploded view.
-3. `element_positions`: **GROUND with the locate protocol — never eyeball pixel coords.** Read **`grounding/PROTOCOL.md`** and run the loop with `node grounding/locate.mjs` (`overlay` → read strips → `region` → read crop → `final` → **`mark` + verify**). Zero keys/deps assumed (node + ffmpeg only); the optional `auto` fast path exists only when `GEMINI_API_KEY` happens to be set. Why: eyeballing put rings off-subject (~16–24% center error on weak vision models); the grid loop pulls it to ~2–4% (measured E2E: eyeball 6.5% → protocol 2.3% avg center error, no case worse).
-4. **Eyedropper palette** from the asset (never generic #FFF/#000).
-
-## Highlight + circle recipe (the common case)
-
-"Ring / spotlight object X in a real image" → use the drop-in template **`samples/asset-fusion/_ref-circle-highlight.html`**: set `CFG.box` (from the locate protocol), `CFG.label`, `CFG.asset`, EVEN `CFG.W/H`, `CFG.mode` (`full` = ring+connector+label+brackets+scanlines, `circle` = ring only). It computes the radial wash, the amber double over-stroke ring, connector, callout, and corner-bracket reticle from the box. The whole pipeline is: locate (PROTOCOL.md) → fill template → render.
-
-## Render gotchas (codified — skipping these breaks the render)
-
-- **EVEN width & height** — odd width _or height_ (e.g. 1400×933) → `ffmpeg` encode fails / distorts. Resize the asset/stage to even dims (1400×932).
-- **`data-width`/`data-height` must be STATIC HTML attrs on the stage** — the renderer's StaticGuard reads them at compile time, before JS runs. Setting them via `setAttribute` is too late → render falls back to portrait 1080×1920 and distorts. (The circle-highlight template now hard-codes them; keep them equal to `CFG.W/H`.)
-- **Draw-on (`stroke-dashoffset`) must be `autoAlpha:0`-gated** — `getTotalLength()` can read 0 before layout → dash disabled → a solid line shows at t=0. Gate every draw-on element with `autoAlpha:0` until it draws, and fall back `getTotalLength() || <const>`.
-- **CSS var tween scope** — `gsap.to(":root", {"--x":..})` won't reach an element that has its own inline `--x`; tween the var on the element itself.
-- **No camera push under a fixed overlay** — scaling the image while the ring/wash stay fixed drifts the target out of the ring. Either skip the push or scale the whole scene together.
-- Lossless delivery: `--format mov` (ProRes); `mp4` is lossy.
-
-## Vocabulary / leans on
-
-- Borrow the annotation kit from registry **`north-korea-locked-down`** (hand-drawn scribble circle draw-on, pop-up label + pointer, editorial wash, camera push).
-- Primitives: gauge fill / marker-rise along the affordance · connector (data → asset point) · diegetic chart fused to the asset's geometry.
-- Adapt the diegetic chart to each asset's affordance (read the geometry, fuse the data into it).
-
-## Build (reuse-first + hand-author the affordance)
-
-**Two layers**: asset (z0, full-bleed) + data graphics (z1+) fused to its geometry, anchored by `element_positions`; connectors/scribble physically tie the data to the asset; asset stays visible. Reference impl: the prototype `fusion-demo/index-annotated.html` (straw → gauge + borrowed annotation kit).
+# asset-fusion — category module (search-driven · the net-new IP)
+
+**A real asset's geometry _becomes_ the chart** — RWA diegetic fusion (the straw becomes a gauge; a glass's liquid becomes a pie). Not in any catalog; the genuinely net-new capability. ~5–8s.
+
+## Source (Step 2)
+
+Search or generate one **hero asset** with strong geometric affordance. `asset_needs`: `{ kind: image, query|generate, treatment: cutout|none }`. Freeze it project-local.
+
+## Plan (Director Part 2) — the fusion logic
+
+1. Classify the **data type** (temporal / quantitative / proportion / spatial).
+2. Read the asset's **geometric affordance** — linearity → timeline/gauge · volume/texture → pie · height → bar · container → exploded view.
+3. `element_positions`: **GROUND with the locate protocol — never eyeball pixel coords.** Read **`grounding/PROTOCOL.md`** and run the loop with `node grounding/locate.mjs` (`overlay` → read strips → `region` → read crop → `final` → **`mark` + verify**). Zero keys/deps assumed (node + ffmpeg only); the optional `auto` fast path exists only when `GEMINI_API_KEY` happens to be set. Why: eyeballing put rings off-subject (~16–24% center error on weak vision models); the grid loop pulls it to ~2–4% (measured E2E: eyeball 6.5% → protocol 2.3% avg center error, no case worse).
+4. **Eyedropper palette** from the asset (never generic #FFF/#000).
+
+## Highlight + circle recipe (the common case)
+
+"Ring / spotlight object X in a real image" → use the drop-in template **`samples/asset-fusion/_ref-circle-highlight.html`**: set `CFG.box` (from the locate protocol), `CFG.label`, `CFG.asset`, EVEN `CFG.W/H`, `CFG.mode` (`full` = ring+connector+label+brackets+scanlines, `circle` = ring only). It computes the radial wash, the amber double over-stroke ring, connector, callout, and corner-bracket reticle from the box. The whole pipeline is: locate (PROTOCOL.md) → fill template → render.
+
+## Render gotchas (codified — skipping these breaks the render)
+
+- **EVEN width & height** — odd width _or height_ (e.g. 1400×933) → `ffmpeg` encode fails / distorts. Resize the asset/stage to even dims (1400×932).
+- **`data-width`/`data-height` must be STATIC HTML attrs on the stage** — the renderer's StaticGuard reads them at compile time, before JS runs. Setting them via `setAttribute` is too late → render falls back to portrait 1080×1920 and distorts. (The circle-highlight template now hard-codes them; keep them equal to `CFG.W/H`.)
+- **Draw-on (`stroke-dashoffset`) must be `autoAlpha:0`-gated** — `getTotalLength()` can read 0 before layout → dash disabled → a solid line shows at t=0. Gate every draw-on element with `autoAlpha:0` until it draws, and fall back `getTotalLength() || <const>`.
+- **CSS var tween scope** — `gsap.to(":root", {"--x":..})` won't reach an element that has its own inline `--x`; tween the var on the element itself.
+- **No camera push under a fixed overlay** — scaling the image while the ring/wash stay fixed drifts the target out of the ring. Either skip the push or scale the whole scene together.
+- Lossless delivery: `--format mov` (ProRes); `mp4` is lossy.
+
+## Vocabulary / leans on
+
+- Borrow the annotation kit from registry **`north-korea-locked-down`** (hand-drawn scribble circle draw-on, pop-up label + pointer, editorial wash, camera push).
+- Primitives: gauge fill / marker-rise along the affordance · connector (data → asset point) · diegetic chart fused to the asset's geometry.
+- Adapt the diegetic chart to each asset's affordance (read the geometry, fuse the data into it).
+
+## Build (reuse-first + hand-author the affordance)
+
+**Two layers**: asset (z0, full-bleed) + data graphics (z1+) fused to its geometry, anchored by `element_positions`; connectors/scribble physically tie the data to the asset; asset stays visible. Reference impl: the prototype `fusion-demo/index-annotated.html` (straw → gauge + borrowed annotation kit).

package/assets/.agent/skills/motion-graphics/categories/charts/module.md

@@ -1,21 +1,21 @@
-# charts — category module
-
-Animated **data-viz** from data. Asset-free (the "input" is the data). "One chart, one message" for short durations.
-
-## Plan (Director)
-
-`content`: `{ type: bar|line|pie|race|pct, data[], labels[], headline, axes: bool }`. For `race`, data must be cumulative/time-staged.
-
-## Vocabulary / leans on
-
-- Block: **`data-chart`** (animated **bar + line**, staggered reveal, value labels — proven: borrowed + customized + rendered to MP4 in the prototype `charts-demo`).
-- Gaps (hand-author): **pie / donut, bar-chart-race, ring/%** — `data-chart` doesn't cover these. Use D3/visx for data→geometry + GSAP for motion.
-- Signature animations: bar stagger-grow · line `stroke-dashoffset` draw-on · pie radial sweep · ring fill · KPI count-up · race reorder.
-
-## Build (reuse-first)
-
-Reuse `data-chart`: `npx hyperframes add data-chart` → edit the data arrays + scales + headline/labels + palette in place (its data is baked in the script, not a `--variables` flag). Axes hidden by default; show muted only when magnitude is the message. Determinism: drive any animation from the seek clock, never wall-clock.
-
-## Dashboard-skeleton variant
-
-For a **product-dashboard** case: lay out a skeleton dashboard — a top bar with a **real test logo** (e.g. the hyperframes logo in `samples/_assets/`) + a title, then a grid of 3–4 **KPI cards** (each a `stat` count-up) + one `data-chart` panel. Reveal order: header/logo in → cards stagger in → the chart animates. Composes the `stat` + `charts` primitives inside a dashboard frame; the logo is a frozen project-local asset.
+# charts — category module
+
+Animated **data-viz** from data. Asset-free (the "input" is the data). "One chart, one message" for short durations.
+
+## Plan (Director)
+
+`content`: `{ type: bar|line|pie|race|pct, data[], labels[], headline, axes: bool }`. For `race`, data must be cumulative/time-staged.
+
+## Vocabulary / leans on
+
+- Block: **`data-chart`** (animated **bar + line**, staggered reveal, value labels — proven: borrowed + customized + rendered to MP4 in the prototype `charts-demo`).
+- Gaps (hand-author): **pie / donut, bar-chart-race, ring/%** — `data-chart` doesn't cover these. Use D3/visx for data→geometry + GSAP for motion.
+- Signature animations: bar stagger-grow · line `stroke-dashoffset` draw-on · pie radial sweep · ring fill · KPI count-up · race reorder.
+
+## Build (reuse-first)
+
+Reuse `data-chart`: `npx hyperframes add data-chart` → edit the data arrays + scales + headline/labels + palette in place (its data is baked in the script, not a `--variables` flag). Axes hidden by default; show muted only when magnitude is the message. Determinism: drive any animation from the seek clock, never wall-clock.
+
+## Dashboard-skeleton variant
+
+For a **product-dashboard** case: lay out a skeleton dashboard — a top bar with a **real test logo** (e.g. the hyperframes logo in `samples/_assets/`) + a title, then a grid of 3–4 **KPI cards** (each a `stat` count-up) + one `data-chart` panel. Reveal order: header/logo in → cards stagger in → the chart animates. Composes the `stat` + `charts` primitives inside a dashboard frame; the logo is a frozen project-local asset.

package/assets/.agent/skills/motion-graphics/categories/kinetic-type/module.md

@@ -1,19 +1,19 @@
-# kinetic-type — category module
-
-Text is the hero; typography + motion carry the message. Usually asset-free (`asset_needs: []`).
-
-## Plan (Director)
-
-- **Style first.** If the project has a **`design.md` / `frame.md`** (precedence: `frame.md` → `design.md` → `DESIGN.md`), READ it and use its **exact palette / fonts / constraints** — do not invent. No spec → pick a named style, or ask: mood + light/dark + any brand color/font. (Style is an input the case must exercise; the same shot in two `design.md`s should look different.)
-- Segment the copy into scenes by meaning / breath (EN ~3–7 words; ZH ~4–12 chars). Tag each scene **Hook → Build → Punch → Resolve**.
-- 1–2 `emphasis_words` per scene. Per scene: `emotion` + `motion` (free-form) + `beats`.
-
-## Vocabulary
-
-Motion primitives + registry blocks: **`references/motion-vocabulary.md`** (slide / scale / fade / blur / typewriter / word_reveal / wave / bounce / slam / scale_pulse / shake / glow / color_shift, plus the 18 `caption-*` blocks).
-
-## Build (reuse-first)
-
-- Prefer a **`caption-*` block** when one fits (`caption-kinetic-slam` / `caption-editorial-emphasis` / …): `npx hyperframes add` + set words / `emphasis_words` / palette / font.
-- Else hand-author: one full-duration `.clip`; a `.group` per scene (flex-centered); words as spans; `gsap.from()` entrances per the scene `motion`; emphasis words → `glow` / `scale_pulse` on the beat; **seek-safe reveal** (`autoAlpha`). Honor `references/builder-contract.md`.
-- Reference impl: prototype `v0-text-motion-demo` + `pipeline-demo`.
+# kinetic-type — category module
+
+Text is the hero; typography + motion carry the message. Usually asset-free (`asset_needs: []`).
+
+## Plan (Director)
+
+- **Style first.** If the project has a **`design.md` / `frame.md`** (precedence: `frame.md` → `design.md` → `DESIGN.md`), READ it and use its **exact palette / fonts / constraints** — do not invent. No spec → pick a named style, or ask: mood + light/dark + any brand color/font. (Style is an input the case must exercise; the same shot in two `design.md`s should look different.)
+- Segment the copy into scenes by meaning / breath (EN ~3–7 words; ZH ~4–12 chars). Tag each scene **Hook → Build → Punch → Resolve**.
+- 1–2 `emphasis_words` per scene. Per scene: `emotion` + `motion` (free-form) + `beats`.
+
+## Vocabulary
+
+Motion primitives + registry blocks: **`references/motion-vocabulary.md`** (slide / scale / fade / blur / typewriter / word_reveal / wave / bounce / slam / scale_pulse / shake / glow / color_shift, plus the 18 `caption-*` blocks).
+
+## Build (reuse-first)
+
+- Prefer a **`caption-*` block** when one fits (`caption-kinetic-slam` / `caption-editorial-emphasis` / …): `npx hyperframes add` + set words / `emphasis_words` / palette / font.
+- Else hand-author: one full-duration `.clip`; a `.group` per scene (flex-centered); words as spans; `gsap.from()` entrances per the scene `motion`; emphasis words → `glow` / `scale_pulse` on the beat; **seek-safe reveal** (`autoAlpha`). Honor `references/builder-contract.md`.
+- Reference impl: prototype `v0-text-motion-demo` + `pipeline-demo`.

package/assets/.agent/skills/motion-graphics/categories/logo-reveal/module.md

@@ -1,17 +1,17 @@
-# logo-reveal — category module
-
-A **logo sting / brand lockup**. The logo is user-supplied (`asset_needs` = one logo `source`, not a search). ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage).
-
-## Plan (Director)
-
-`content`: `{ logo: <asset path>, tagline, url }`. Envelope: brand palette (or eyedropper from the logo), elegant pacing.
-
-## Vocabulary / leans on
-
-- Block: **`logo-outro`** (piece-by-piece assembly + glow bloom + tagline fade + URL pill).
-- Rules: `rules/svg-path-draw` (draw-on for vector logos) · `rules/scale-swap-transition` · `rules/3d-text-depth-layers`.
-- Primitives: draw-on / mask-reveal / particle-assemble · `glow` bloom · `underline_sweep` · hold.
-
-## Build (reuse-first)
-
-Reuse `logo-outro` + swap logo / tagline / url / palette; **or** hand-author: place the logo at its hero frame (CSS), reveal via draw-on (SVG `stroke-dashoffset`) or mask/scale, add a glow bloom + accent underline sweep, hold. For an SVG logo, prefer draw-on; for a raster logo, mask/scale + glow. Transparent bg when exporting as an overlay.
+# logo-reveal — category module
+
+A **logo sting / brand lockup**. The logo is user-supplied (`asset_needs` = one logo `source`, not a search). ~3–5s. Often `export: alpha-overlay` (sting to drop on other footage).
+
+## Plan (Director)
+
+`content`: `{ logo: <asset path>, tagline, url }`. Envelope: brand palette (or eyedropper from the logo), elegant pacing.
+
+## Vocabulary / leans on
+
+- Block: **`logo-outro`** (piece-by-piece assembly + glow bloom + tagline fade + URL pill).
+- Rules: `rules/svg-path-draw` (draw-on for vector logos) · `rules/scale-swap-transition` · `rules/3d-text-depth-layers`.
+- Primitives: draw-on / mask-reveal / particle-assemble · `glow` bloom · `underline_sweep` · hold.
+
+## Build (reuse-first)
+
+Reuse `logo-outro` + swap logo / tagline / url / palette; **or** hand-author: place the logo at its hero frame (CSS), reveal via draw-on (SVG `stroke-dashoffset`) or mask/scale, add a glow bloom + accent underline sweep, hold. For an SVG logo, prefer draw-on; for a raster logo, mask/scale + glow. Transparent bg when exporting as an overlay.

package/assets/.agent/skills/motion-graphics/categories/lower-thirds/module.md

@@ -1,16 +1,16 @@
-# lower-thirds — category module
-
-**Name/title bars, callouts, social overlays** — graphics meant to sit over other footage. Asset-free (+ optional logo). Usually `export: alpha-overlay` (transparent). ~3–6s (or loop/hold).
-
-## Plan (Director)
-
-`content`: `{ name, role, position (lower-left / lower-third / corner), brand_colors[] }`. Default `export: alpha-overlay`.
-
-## Vocabulary / leans on
-
-- Blocks: `caption-*` (pill-karaoke, neon-accent, editorial-emphasis) + registry **overlay** blocks (`instagram-follow`, `tiktok-follow`, `yt-lower-third`, `x-post`, `spotify-card`, `macos-notification`).
-- Primitives: slide/wipe-in · bar reveal · `glow` · fade/slide-out.
-
-## Build (reuse-first)
-
-Reuse the closest overlay/caption block + set name / role / handle / brand colors / position; **or** hand-author a bar that wipes in (`scaleX` from 0, `transform-origin:left`) with text sliding up behind it, hold, slide out. **Transparent background** (`export: alpha-overlay` → `render --format webm/mov`) so it composites over footage. Keep it in the title-safe lower band.
+# lower-thirds — category module
+
+**Name/title bars, callouts, social overlays** — graphics meant to sit over other footage. Asset-free (+ optional logo). Usually `export: alpha-overlay` (transparent). ~3–6s (or loop/hold).
+
+## Plan (Director)
+
+`content`: `{ name, role, position (lower-left / lower-third / corner), brand_colors[] }`. Default `export: alpha-overlay`.
+
+## Vocabulary / leans on
+
+- Blocks: `caption-*` (pill-karaoke, neon-accent, editorial-emphasis) + registry **overlay** blocks (`instagram-follow`, `tiktok-follow`, `yt-lower-third`, `x-post`, `spotify-card`, `macos-notification`).
+- Primitives: slide/wipe-in · bar reveal · `glow` · fade/slide-out.
+
+## Build (reuse-first)
+
+Reuse the closest overlay/caption block + set name / role / handle / brand colors / position; **or** hand-author a bar that wipes in (`scaleX` from 0, `transform-origin:left`) with text sliding up behind it, hold, slide out. **Transparent background** (`export: alpha-overlay` → `render --format webm/mov`) so it composites over footage. Keep it in the title-safe lower band.