takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/motion-graphics/SKILL.md

@@ -1,172 +1,172 @@
----
-name: motion-graphics
-description: >
-  Use when the user wants a short, design-led motion graphic where motion is the
-  message: kinetic typography, stat or number count-up, chart/data-viz hit,
-  logo sting, brand lockup, lower-third, callout, social overlay, animated
-  headline/tweet/news item, motion poster, or quick captured-page highlight.
-  Usually under 10s and up to ~30s, with no narration arc, voice-over, or
-  live-action subject. Can render to MP4 or transparent overlay. Not for longer,
-  multi-scene, narrated, or brand-reel pieces (use general-video), narrated
-  website videos (website-to-video), topic explainers
-  (faceless-explainer), product promos (product-launch-video), PR videos
-  (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a
-  quick motion-first piece or a longer / narrated treatment, see /hyperframes.
-metadata:
-  {
-    "tags": "orchestrator, motion-graphics, kinetic-type, data-viz, logo-reveal, lower-thirds, news, tweet, webpage, asset-fusion, short-form, overlay, no-narration",
-  }
----
-
-# motion-graphics — dispatch entry
-
-> **Confirm the route before Step 0.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). A **longer, multi-scene, or narrated** treatment → `/general-video`; a **narrated video of a website** → `/website-to-video`; a **topic explainer** → `/faceless-explainer`; a **product promo** → `/product-launch-video`; **captions on existing footage** → `/embedded-captions`. **Out of scope**: live / at-render-time data, or footage it can't capture. Unsure motion-first-vs-narrated? **Read `/hyperframes` first.**
-
-A short design-led motion graphic. **Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities. All artifacts go to `PROJECT_DIR = videos/<project-name>/` (created in Step 0); all paths below are relative to it.
-
-| Phase    | Execution                                                             | Primary artifact                                                 | Detailed flow                 |
-| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------- |
-| init     | Bash                                                                  | `hyperframes.json`                                               | Step 0                        |
-| plan     | subagent — **decide search?** + classify + asset strategy             | `shot-plan.json` (draft: category, `asset_needs` queries, brief) | `agents/director.md` (Part 1) |
-| source ◇ | Bash — media-use resolve (**skip if `asset_needs` is empty**)         | `assets/` + `assets/index.md`                                    | `phases/source/guide.md`      |
-| design   | subagent — shot design around resolved assets                         | `shot-plan.json` (final: block(s) + layout + motion + positions) | `agents/director.md` (Part 2) |
-| build    | subagent — reuse-first composition                                    | `compositions/index.html`                                        | `agents/builder.md`           |
-| render   | Bash — `hyperframes render` (MP4, or `--format webm/mov` for overlay) | `renders/video.mp4`                                              | Step 5                        |
-| verify   | Bash — `lint` / `inspect` -> repair subagent on failure               | (fixes in place)                                                 | `agents/finalize.md`          |
-
-`◇ source` runs only when the chosen category declares assets. Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design.
-
-## Categories — split by the search decision
-
-`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**. Each category is one `categories/<id>/module.md` (its planning + build rules); the shared motion vocabulary lives in `references/motion-vocabulary.md` (→ `hyperframes-animation` rules/blueprints + registry blocks).
-
-**Form categories — no search; the user supplies the content:**
-
-| Category       | Intent                                         | Leans on                                                                    |
-| -------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
-| `kinetic-type` | punchy line / quote / title, motion-first text | `caption-*` blocks + animation rules                                        |
-| `stat`         | single hero number / count-up + ring           | `apple-money-count` / `rules/{counting-dynamic-scale, stat-bars-and-fills}` |
-| `charts`       | bar / line / pie / race / % from data          | `data-chart` block                                                          |
-| `logo-reveal`  | logo sting / brand lockup (user logo)          | `logo-outro` / `rules/svg-path-draw`                                        |
-| `lower-thirds` | name / title bars, callouts, social overlays   | `caption-*` + registry overlay blocks                                       |
-
-**Search-driven categories — search first, then animate by content type** (the RWA path):
-
-| Returned content | Category       | Animation                                                      |
-| ---------------- | -------------- | -------------------------------------------------------------- |
-| webpage / link   | `webpage`      | webpage / UI animation (scroll, reveal, cursor, callouts)      |
-| news article     | `news`         | headline reveal + source card + key-fact callouts              |
-| tweet            | `tweet`        | animated tweet card                                            |
-| image / entity   | `asset-fusion` | the asset's geometry _becomes_ the chart (RWA diegetic fusion) |
-
-Build order: one at a time, coverage-first (rough is fine). `kinetic-type` ported from the prototype; the rest follow.
-
-## Prerequisites
-
-macOS Apple Silicon or Linux x64. System tools: `brew install node ffmpeg`. `npx hyperframes doctor` once. macOS GPU render: `export PRODUCER_BROWSER_GPU_MODE=hardware`.
-
-Optional keys (local fallbacks if unset) — only needed by categories that source/generate assets via media-use:
-
-| Key                                 | Used for                                                    | Fallback                        |
-| ----------------------------------- | ----------------------------------------------------------- | ------------------------------- |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | image generation (media-use resolve)                        | skip generate / search-only     |
-| (asset_scout / search providers)    | `webpage`/`news`/`tweet` + `asset-fusion` real-asset search | category degrades to asset-free |
-
-## Flow
-
-### Step 0 — Initialize
-
-cwd is the agent workspace root; write all artifacts under `PROJECT_DIR = videos/<project-name>/`. `<project-name>`: use the dir the user gave, else a short kebab-case name from the intent (`<subject>-motion`). Not the workspace basename or a timestamp.
-
-Only when `$PROJECT_DIR/hyperframes.json` is absent:
-
-```bash
-PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
-mkdir -p "$(dirname "$PROJECT_DIR")"
-npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank
-```
-
-`init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
-
-**Constraints:** never `hyperframes init` in the workspace root; never nest another `hyperframes/` inside `PROJECT_DIR`; every Bash command (master + subagents) is a `(cd "$PROJECT_DIR" && ...)` subshell — never bare `cd`.
-
-### Step 1 — Plan (subagent: Director Part 1)
-
-Dispatch one subagent. prompt = full `agents/director.md` + `## Dispatch context` (`SKILL_DIR` / `PROJECT_DIR` / the user's request / `Schema: <SKILL_DIR>/references/shot-plan-ir.md`). It must:
-
-1. **Decide: does this need a search?** (the first fork)
-   - **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds); content is user-supplied; `asset_needs: []`.
-   - **Yes** → emit a **search plan** into `asset_needs[]` (news / web / tweet / image; two-pole queries). The specific **search-driven category** (webpage / news / tweet / asset-fusion) is confirmed by the content type returned in Step 2, and finalized in Step 3.
-2. Write a draft `shot-plan.json` (envelope + chosen form category _or_ search intent + `asset_needs` + a one-paragraph shot brief). Schema: `references/shot-plan-ir.md`.
-
-Validation: `[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing`.
-
-### Step 2 — Source ◇ (Bash: media-use, conditional)
-
-If `shot-plan.json.asset_needs` is non-empty, resolve assets (search / generate / fetch → frozen project-local paths + ledger). See `phases/source/guide.md` (wraps `media-use resolve`; the search-driven categories use the news/web/tweet/image search). If `asset_needs` is empty, **skip to Step 3**.
-
-```bash
-# illustrative — see phases/source/guide.md
-(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)
-```
-
-Degrade gracefully: if a search/provider is unavailable, the category falls back to asset-free (note it in `context.log`).
-
-### Step 3 — Design (subagent: Director Part 2)
-
-Dispatch a subagent (prompt = `agents/director.md` Part 2 + dispatch context including the resolved `assets/index.md` if Step 2 ran + `catalog-map.md`). It designs the shot **around the available assets**: pick the catalog block(s) + the `hyperframes-animation` rules/blueprints, the layout, the motion, beats, and (for `asset-fusion`) the `element_positions` + eyedropper palette. Finalizes `shot-plan.json` (`content.block` + `content.customize` + per-category content).
-
-### Step 4 — Build (subagent: Builder, reuse-first)
-
-Dispatch a subagent. prompt = full `agents/builder.md` + dispatch context (`shot-plan.json`, `catalog-map.md`, the category's `module.md`, `references/motion-vocabulary.md`, `references/builder-contract.md`). **Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).
-
-### Step 5 — Render (Bash)
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)
-# transparent overlay variant: --format webm  (or mov)
-```
-
-### Step 6 — Verify (Bash → repair subagent on failure)
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)
-```
-
-exit 0 → done. On lint/inspect errors, dispatch the repair subagent (`agents/finalize.md`: snapshot QA + one in-place fix pass + re-render). Never change a fixed duration in repair.
-
-### Report + optional preview
-
-Report the final output (`renders/video.mp4`, or the `.webm` / `.mov` overlay variant) + duration. **Don't open a preview during the run.** Offer one only on request, started **after** render so it serves the final file:
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI; or `npx hyperframes play` for a shareable link
-```
-
-Flags live in the `hyperframes-cli` skill (`references/preview-render.md`).
-
-## Resume table
-
-| State                                                    | Continue from            |
-| -------------------------------------------------------- | ------------------------ |
-| no `shot-plan.json`                                      | Step 1 (plan)            |
-| `shot-plan.json` has `asset_needs`, no `assets/`         | Step 2 (source)          |
-| `shot-plan.json` final, no `compositions/index.html`     | Step 3/4 (design+build)  |
-| `compositions/index.html` exists, no `renders/video.mp4` | Step 5 (render) + Step 6 |
-| `renders/video.mp4` exists                               | Report + stop            |
-
-## Design notes (maintainers — execution does not read this)
-
-- **Asset-first rationale:** sourcing is front-loaded and informs shot design (the RWA flow: analyze → search → review → compose). the search-driven categories (`webpage`/`news`/`tweet`) and `asset-fusion` both lean on media-use search (news/web/tweet/image), which is media-use's documented RWA lineage.
-- **Reuse-first:** the in-ecosystem analog of LLM-generated templates is "compose catalog blocks + `hyperframes-animation` rules". HF's paused GSAP timeline ≙ Remotion's `useCurrentFrame`.
-- **Category module contract:** one `categories/<id>/module.md` (planning + build), sharing `references/motion-vocabulary.md` (+ optional eval). Adding a category = drop the folder + register its classifier line in `agents/director.md` + its row in `catalog-map.md`; the phase pipeline is untouched.
-- **Directory shape:**
-  ```
-  videos/<project-name>/
-    hyperframes.json  context.log
-    shot-plan.json            # the IR (Director output)
-    assets/  assets/index.md  # media-use output (if sourced)
-    compositions/index.html   # Builder output
-    renders/video.mp4
-  ```
-- **Registration:** in `hyperframes` router — add the "design-led short motion graphic" intent + Workflow description; carve the motion-graphics triggers out of `/general-video`; add reverse Do-NOT-use edges. See `motion-graphics-genre.md` §5-7.
+---
+name: motion-graphics
+description: >
+  Use when the user wants a short, design-led motion graphic where motion is the
+  message: kinetic typography, stat or number count-up, chart/data-viz hit,
+  logo sting, brand lockup, lower-third, callout, social overlay, animated
+  headline/tweet/news item, motion poster, or quick captured-page highlight.
+  Usually under 10s and up to ~30s, with no narration arc, voice-over, or
+  live-action subject. Can render to MP4 or transparent overlay. Not for longer,
+  multi-scene, narrated, or brand-reel pieces (use general-video), narrated
+  website videos (website-to-video), topic explainers
+  (faceless-explainer), product promos (product-launch-video), PR videos
+  (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a
+  quick motion-first piece or a longer / narrated treatment, see /hyperframes.
+metadata:
+  {
+    "tags": "orchestrator, motion-graphics, kinetic-type, data-viz, logo-reveal, lower-thirds, news, tweet, webpage, asset-fusion, short-form, overlay, no-narration",
+  }
+---
+
+# motion-graphics — dispatch entry
+
+> **Confirm the route before Step 0.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). A **longer, multi-scene, or narrated** treatment → `/general-video`; a **narrated video of a website** → `/website-to-video`; a **topic explainer** → `/faceless-explainer`; a **product promo** → `/product-launch-video`; **captions on existing footage** → `/embedded-captions`. **Out of scope**: live / at-render-time data, or footage it can't capture. Unsure motion-first-vs-narrated? **Read `/hyperframes` first.**
+
+A short design-led motion graphic. **Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities. All artifacts go to `PROJECT_DIR = videos/<project-name>/` (created in Step 0); all paths below are relative to it.
+
+| Phase    | Execution                                                             | Primary artifact                                                 | Detailed flow                 |
+| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------- |
+| init     | Bash                                                                  | `hyperframes.json`                                               | Step 0                        |
+| plan     | subagent — **decide search?** + classify + asset strategy             | `shot-plan.json` (draft: category, `asset_needs` queries, brief) | `agents/director.md` (Part 1) |
+| source ◇ | Bash — media-use resolve (**skip if `asset_needs` is empty**)         | `assets/` + `assets/index.md`                                    | `phases/source/guide.md`      |
+| design   | subagent — shot design around resolved assets                         | `shot-plan.json` (final: block(s) + layout + motion + positions) | `agents/director.md` (Part 2) |
+| build    | subagent — reuse-first composition                                    | `compositions/index.html`                                        | `agents/builder.md`           |
+| render   | Bash — `hyperframes render` (MP4, or `--format webm/mov` for overlay) | `renders/video.mp4`                                              | Step 5                        |
+| verify   | Bash — `lint` / `inspect` -> repair subagent on failure               | (fixes in place)                                                 | `agents/finalize.md`          |
+
+`◇ source` runs only when the chosen category declares assets. Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design.
+
+## Categories — split by the search decision
+
+`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**. Each category is one `categories/<id>/module.md` (its planning + build rules); the shared motion vocabulary lives in `references/motion-vocabulary.md` (→ `hyperframes-animation` rules/blueprints + registry blocks).
+
+**Form categories — no search; the user supplies the content:**
+
+| Category       | Intent                                         | Leans on                                                                    |
+| -------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
+| `kinetic-type` | punchy line / quote / title, motion-first text | `caption-*` blocks + animation rules                                        |
+| `stat`         | single hero number / count-up + ring           | `apple-money-count` / `rules/{counting-dynamic-scale, stat-bars-and-fills}` |
+| `charts`       | bar / line / pie / race / % from data          | `data-chart` block                                                          |
+| `logo-reveal`  | logo sting / brand lockup (user logo)          | `logo-outro` / `rules/svg-path-draw`                                        |
+| `lower-thirds` | name / title bars, callouts, social overlays   | `caption-*` + registry overlay blocks                                       |
+
+**Search-driven categories — search first, then animate by content type** (the RWA path):
+
+| Returned content | Category       | Animation                                                      |
+| ---------------- | -------------- | -------------------------------------------------------------- |
+| webpage / link   | `webpage`      | webpage / UI animation (scroll, reveal, cursor, callouts)      |
+| news article     | `news`         | headline reveal + source card + key-fact callouts              |
+| tweet            | `tweet`        | animated tweet card                                            |
+| image / entity   | `asset-fusion` | the asset's geometry _becomes_ the chart (RWA diegetic fusion) |
+
+Build order: one at a time, coverage-first (rough is fine). `kinetic-type` ported from the prototype; the rest follow.
+
+## Prerequisites
+
+macOS Apple Silicon or Linux x64. System tools: `brew install node ffmpeg`. `npx hyperframes doctor` once. macOS GPU render: `export PRODUCER_BROWSER_GPU_MODE=hardware`.
+
+Optional keys (local fallbacks if unset) — only needed by categories that source/generate assets via media-use:
+
+| Key                                 | Used for                                                    | Fallback                        |
+| ----------------------------------- | ----------------------------------------------------------- | ------------------------------- |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | image generation (media-use resolve)                        | skip generate / search-only     |
+| (asset_scout / search providers)    | `webpage`/`news`/`tweet` + `asset-fusion` real-asset search | category degrades to asset-free |
+
+## Flow
+
+### Step 0 — Initialize
+
+cwd is the agent workspace root; write all artifacts under `PROJECT_DIR = videos/<project-name>/`. `<project-name>`: use the dir the user gave, else a short kebab-case name from the intent (`<subject>-motion`). Not the workspace basename or a timestamp.
+
+Only when `$PROJECT_DIR/hyperframes.json` is absent:
+
+```bash
+PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
+mkdir -p "$(dirname "$PROJECT_DIR")"
+npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank
+```
+
+`init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
+
+**Constraints:** never `hyperframes init` in the workspace root; never nest another `hyperframes/` inside `PROJECT_DIR`; every Bash command (master + subagents) is a `(cd "$PROJECT_DIR" && ...)` subshell — never bare `cd`.
+
+### Step 1 — Plan (subagent: Director Part 1)
+
+Dispatch one subagent. prompt = full `agents/director.md` + `## Dispatch context` (`SKILL_DIR` / `PROJECT_DIR` / the user's request / `Schema: <SKILL_DIR>/references/shot-plan-ir.md`). It must:
+
+1. **Decide: does this need a search?** (the first fork)
+   - **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds); content is user-supplied; `asset_needs: []`.
+   - **Yes** → emit a **search plan** into `asset_needs[]` (news / web / tweet / image; two-pole queries). The specific **search-driven category** (webpage / news / tweet / asset-fusion) is confirmed by the content type returned in Step 2, and finalized in Step 3.
+2. Write a draft `shot-plan.json` (envelope + chosen form category _or_ search intent + `asset_needs` + a one-paragraph shot brief). Schema: `references/shot-plan-ir.md`.
+
+Validation: `[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing`.
+
+### Step 2 — Source ◇ (Bash: media-use, conditional)
+
+If `shot-plan.json.asset_needs` is non-empty, resolve assets (search / generate / fetch → frozen project-local paths + ledger). See `phases/source/guide.md` (wraps `media-use resolve`; the search-driven categories use the news/web/tweet/image search). If `asset_needs` is empty, **skip to Step 3**.
+
+```bash
+# illustrative — see phases/source/guide.md
+(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)
+```
+
+Degrade gracefully: if a search/provider is unavailable, the category falls back to asset-free (note it in `context.log`).
+
+### Step 3 — Design (subagent: Director Part 2)
+
+Dispatch a subagent (prompt = `agents/director.md` Part 2 + dispatch context including the resolved `assets/index.md` if Step 2 ran + `catalog-map.md`). It designs the shot **around the available assets**: pick the catalog block(s) + the `hyperframes-animation` rules/blueprints, the layout, the motion, beats, and (for `asset-fusion`) the `element_positions` + eyedropper palette. Finalizes `shot-plan.json` (`content.block` + `content.customize` + per-category content).
+
+### Step 4 — Build (subagent: Builder, reuse-first)
+
+Dispatch a subagent. prompt = full `agents/builder.md` + dispatch context (`shot-plan.json`, `catalog-map.md`, the category's `module.md`, `references/motion-vocabulary.md`, `references/builder-contract.md`). **Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).
+
+### Step 5 — Render (Bash)
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)
+# transparent overlay variant: --format webm  (or mov)
+```
+
+### Step 6 — Verify (Bash → repair subagent on failure)
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)
+```
+
+exit 0 → done. On lint/inspect errors, dispatch the repair subagent (`agents/finalize.md`: snapshot QA + one in-place fix pass + re-render). Never change a fixed duration in repair.
+
+### Report + optional preview
+
+Report the final output (`renders/video.mp4`, or the `.webm` / `.mov` overlay variant) + duration. **Don't open a preview during the run.** Offer one only on request, started **after** render so it serves the final file:
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI; or `npx hyperframes play` for a shareable link
+```
+
+Flags live in the `hyperframes-cli` skill (`references/preview-render.md`).
+
+## Resume table
+
+| State                                                    | Continue from            |
+| -------------------------------------------------------- | ------------------------ |
+| no `shot-plan.json`                                      | Step 1 (plan)            |
+| `shot-plan.json` has `asset_needs`, no `assets/`         | Step 2 (source)          |
+| `shot-plan.json` final, no `compositions/index.html`     | Step 3/4 (design+build)  |
+| `compositions/index.html` exists, no `renders/video.mp4` | Step 5 (render) + Step 6 |
+| `renders/video.mp4` exists                               | Report + stop            |
+
+## Design notes (maintainers — execution does not read this)
+
+- **Asset-first rationale:** sourcing is front-loaded and informs shot design (the RWA flow: analyze → search → review → compose). the search-driven categories (`webpage`/`news`/`tweet`) and `asset-fusion` both lean on media-use search (news/web/tweet/image), which is media-use's documented RWA lineage.
+- **Reuse-first:** the in-ecosystem analog of LLM-generated templates is "compose catalog blocks + `hyperframes-animation` rules". HF's paused GSAP timeline ≙ Remotion's `useCurrentFrame`.
+- **Category module contract:** one `categories/<id>/module.md` (planning + build), sharing `references/motion-vocabulary.md` (+ optional eval). Adding a category = drop the folder + register its classifier line in `agents/director.md` + its row in `catalog-map.md`; the phase pipeline is untouched.
+- **Directory shape:**
+  ```
+  videos/<project-name>/
+    hyperframes.json  context.log
+    shot-plan.json            # the IR (Director output)
+    assets/  assets/index.md  # media-use output (if sourced)
+    compositions/index.html   # Builder output
+    renders/video.mp4
+  ```
+- **Registration:** in `hyperframes` router — add the "design-led short motion graphic" intent + Workflow description; carve the motion-graphics triggers out of `/general-video`; add reverse Do-NOT-use edges. See `motion-graphics-genre.md` §5-7.

package/assets/.agent/skills/motion-graphics/agents/builder.md

@@ -1,40 +1,40 @@
-# Motion-Graphics Builder
-
-Turn `shot-plan.json` into one renderable HyperFrames composition (`compositions/index.html`). Everything stays in the HF ecosystem — HTML is the source of truth; a single **paused** GSAP timeline carries all motion; the engine seeks it. Category-specific build rules live in `categories/<id>/module.md`; this file is the shared contract.
-
-## Reuse-first (the default)
-
-Default = **compose existing catalog capabilities, not hand-author**:
-
-- `npx hyperframes add <block>` (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = **add + edit**.
-- `hyperframes-animation` rules / blueprints / transitions for motion; runtime adapters (GSAP default).
-
-Hand-author only (a) gaps no block/rule covers, (b) the `asset-fusion` affordance binding. The Director named the block(s) + customizations in `shot-plan.json` (`content.block` + `content.customize`); see `catalog-map.md`.
-
-## The HF contract (non-negotiable)
-
-- Root `#stage` carries `data-composition-id`, `data-start="0"`, `data-duration=<s>`, `data-fps`, `data-width`, `data-height`.
-- Exactly ONE `gsap.timeline({ paused:true })`; register `window.__timelines["<id>"] = tl;`; end with `tl.seek(0)`. **Never `tl.play()`** for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
-- **Timed clips** need `class="clip"` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
-- **Fonts**: prefer local `@font-face` (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects `@font-face`) but warn + need network.
-- **Deterministic only** — no `Date.now()` / `Math.random()` / network.
-
-## Layout before animation
-
-Build the **hero-frame end-state** in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Then `gsap.from()` entrances INTO it; exits via transitions or the final scene. Full rules: `references/builder-contract.md`.
-
-## IR → composition
-
-- `content.block` → `hyperframes add` it (or inline) + apply `content.customize`.
-- per-category `content` (text scenes / chart data / fusion positions / news-tweet content) → realize per `categories/<id>/module.md`.
-- resolved `asset_needs` → reference **frozen project-local paths** (never a remote URL or a prompt).
-- `palette[-1]` / bg + `font` from the envelope.
-- `export: alpha-overlay` → transparent bg; render `--format webm` (or `mov`).
-
-## Critical correctness (GSAP / seek)
-
-Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes inspect` for overflow / collisions.
-
-## Verify-fix
-
-`hyperframes lint` → `inspect` → `render -q draft`. On failure, fix the offending element + re-run. (Remotion-sourced prior art is graded by the `/remotion-to-hyperframes` SSIM harness.) **Never change a fixed `data-duration` during repair.**
+# Motion-Graphics Builder
+
+Turn `shot-plan.json` into one renderable HyperFrames composition (`compositions/index.html`). Everything stays in the HF ecosystem — HTML is the source of truth; a single **paused** GSAP timeline carries all motion; the engine seeks it. Category-specific build rules live in `categories/<id>/module.md`; this file is the shared contract.
+
+## Reuse-first (the default)
+
+Default = **compose existing catalog capabilities, not hand-author**:
+
+- `npx hyperframes add <block>` (registry) → customize in place. Most blocks bake content/data into their own script (only a few expose CSS-var params), so reuse = **add + edit**.
+- `hyperframes-animation` rules / blueprints / transitions for motion; runtime adapters (GSAP default).
+
+Hand-author only (a) gaps no block/rule covers, (b) the `asset-fusion` affordance binding. The Director named the block(s) + customizations in `shot-plan.json` (`content.block` + `content.customize`); see `catalog-map.md`.
+
+## The HF contract (non-negotiable)
+
+- Root `#stage` carries `data-composition-id`, `data-start="0"`, `data-duration=<s>`, `data-fps`, `data-width`, `data-height`.
+- Exactly ONE `gsap.timeline({ paused:true })`; register `window.__timelines["<id>"] = tl;`; end with `tl.seek(0)`. **Never `tl.play()`** for render-critical motion. No timers / async / event-driven timeline build. Finite repeats only.
+- **Timed clips** need `class="clip"` + a stable `id`. Timeline-driven groups inside one full-duration clip don't each need timing attrs.
+- **Fonts**: prefer local `@font-face` (.woff2) for deterministic / offline render; CDN Google Fonts do render (compiler caches + injects `@font-face`) but warn + need network.
+- **Deterministic only** — no `Date.now()` / `Math.random()` / network.
+
+## Layout before animation
+
+Build the **hero-frame end-state** in CSS first (flex + padding; never absolute offsets on content containers; the root must be sized). Then `gsap.from()` entrances INTO it; exits via transitions or the final scene. Full rules: `references/builder-contract.md`.
+
+## IR → composition
+
+- `content.block` → `hyperframes add` it (or inline) + apply `content.customize`.
+- per-category `content` (text scenes / chart data / fusion positions / news-tweet content) → realize per `categories/<id>/module.md`.
+- resolved `asset_needs` → reference **frozen project-local paths** (never a remote URL or a prompt).
+- `palette[-1]` / bg + `font` from the envelope.
+- `export: alpha-overlay` → transparent bg; render `--format webm` (or `mov`).
+
+## Critical correctness (GSAP / seek)
+
+Opacity-gate delayed elements (set hidden until their entrance). Clamp at tween bounds (no overshoot past a held value). Allowed eases: `power1–4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine` (`.in/.out/.inOut`). One motif per scene. Run `hyperframes inspect` for overflow / collisions.
+
+## Verify-fix
+
+`hyperframes lint` → `inspect` → `render -q draft`. On failure, fix the offending element + re-run. (Remotion-sourced prior art is graded by the `/remotion-to-hyperframes` SSIM harness.) **Never change a fixed `data-duration` during repair.**

package/assets/.agent/skills/motion-graphics/agents/director.md

@@ -1,53 +1,53 @@
-# Motion-Graphics Director
-
-Turn a request into a `shot-plan.json` for a short (~3–30s) **design-led motion graphic**. You run in **two parts** around the asset-sourcing step: **Part 1 (plan)** before sourcing, **Part 2 (design)** after. You do NOT write composition code — that's the Builder. Schema: `references/shot-plan-ir.md`.
-
-## Part 1 — Plan (before sourcing)
-
-Emit a DRAFT `shot-plan.json`.
-
-0. **Decide first: does this need a search?** No → a **form category** (user supplies content). Yes → emit a search plan; the specific **search-driven category** (`webpage` / `news` / `tweet` / `asset-fusion`) is confirmed by what the search returns (Step 2 → finalized in Part 2).
-
-1. **Classify** — form categories by intent below; search-driven categories are picked post-search:
-
-   | Category       | Pick when…                                                                                                                                                                         |
-   | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-   | `kinetic-type` | a punchy line / quote / title; text is the hero                                                                                                                                    |
-   | `stat`         | a single hero number / count-up                                                                                                                                                    |
-   | `charts`       | bar / line / pie / race / % from data                                                                                                                                              |
-   | `logo-reveal`  | a logo sting / brand lockup (user supplies the logo)                                                                                                                               |
-   | `lower-thirds` | name/title bars, callouts, social overlays                                                                                                                                         |
-   | `maps`         | a geographic shot — highlight regions, connect places, zoom to a location. Sub-fork: **vector** (D3, stylized) vs **basemap** (baked MapLibre — real satellite/dark/zoom-to-place) |
-   | `webpage`      | highlight / animate a real captured web page or UI _(search-driven)_                                                                                                               |
-   | `news`         | a news article → article-highlight: blur → zoom into keyword _(search-driven)_                                                                                                     |
-   | `tweet`        | a tweet → animated card _(search-driven)_                                                                                                                                          |
-   | `asset-fusion` | a real photo/asset's geometry _becomes_ the chart _(search-driven)_                                                                                                                |
-
-   If genuinely ambiguous between two, ask exactly one question. Then load `categories/<id>/module.md` for that category's specifics.
-
-2. **Asset strategy → `asset_needs[]`.** Each item: `{ role, kind: image|icon|logo|svg|news|web|tweet, query|source, treatment }`.
-   - asset-free (`kinetic-type`, most `stat`/`charts`) → `asset_needs: []`.
-   - `maps` → **vector** lane: `asset_needs: []` (D3/TopoJSON, runs live in HF). **basemap** lane (satellite/dark/zoom-to-place): `asset_needs: [{ type: "map-bake", … }]` (baked in Source — see `categories/maps/module.md`).
-   - `webpage` / `news` / `tweet` → search the real source (page / article / tweet) + a supporting image. **Two-pole queries only**: atomic (1–3 words, composable: portraits, logos, objects) OR specific (5–15 words: a news event, a tweet). Never the middle. A failed specific query is dropped, not broadened.
-   - `asset-fusion` → search or generate one hero asset.
-   - `logo-reveal` → user-supplied logo (`source`).
-
-3. **Envelope**: `duration_s` (3–30), `fps` (30), `canvas` (default 1080×1920; 16:9 / 1:1 per platform), `style`, `palette` (hex list, or `"derive-from-asset"`), `font` (from the HF embed list), `beats`, `export` (`mp4` | `alpha-overlay`).
-
-4. **Shot brief**: one paragraph — what the viewer experiences + the single dominant motion idea.
-
-## Part 2 — Design (after sourcing)
-
-Given the draft + resolved `assets/index.md` (if Step 2 ran) + `catalog-map.md`, design the shot **around the assets**:
-
-- Pick the **catalog block(s)** + the `hyperframes-animation` rules / blueprints (catalog-aware — see `catalog-map.md`).
-- Layout (hero-frame), motion (per `references/motion-vocabulary.md`), beats, pacing, exits.
-- `asset-fusion`: read the asset's **geometric affordance** → `element_positions` (center / extent / safe-zones / avoid-zones) + **eyedropper palette** from the asset.
-- Finalize `shot-plan.json`: `content.block` + `content.customize` + the per-category `content`.
-
-## Heuristics (design-led short motion)
-
-- **Motion IS the message**; no narration arc. Hook lands fast (~first 0.5s). **One dominant motif.** Pattern-interrupt if the piece runs >~2.5s (change exactly one thing). Effect intensity matches the energy. Legibility: a key element stays readable ≥~0.3s. Beats may be anticipated ~0.1s for perceived sync.
-- **Reuse-first**: name a catalog block; ask for hand-authored motion only for gaps + the `asset-fusion` affordance.
-
-Then hand `shot-plan.json` to the Builder.
+# Motion-Graphics Director
+
+Turn a request into a `shot-plan.json` for a short (~3–30s) **design-led motion graphic**. You run in **two parts** around the asset-sourcing step: **Part 1 (plan)** before sourcing, **Part 2 (design)** after. You do NOT write composition code — that's the Builder. Schema: `references/shot-plan-ir.md`.
+
+## Part 1 — Plan (before sourcing)
+
+Emit a DRAFT `shot-plan.json`.
+
+0. **Decide first: does this need a search?** No → a **form category** (user supplies content). Yes → emit a search plan; the specific **search-driven category** (`webpage` / `news` / `tweet` / `asset-fusion`) is confirmed by what the search returns (Step 2 → finalized in Part 2).
+
+1. **Classify** — form categories by intent below; search-driven categories are picked post-search:
+
+   | Category       | Pick when…                                                                                                                                                                         |
+   | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+   | `kinetic-type` | a punchy line / quote / title; text is the hero                                                                                                                                    |
+   | `stat`         | a single hero number / count-up                                                                                                                                                    |
+   | `charts`       | bar / line / pie / race / % from data                                                                                                                                              |
+   | `logo-reveal`  | a logo sting / brand lockup (user supplies the logo)                                                                                                                               |
+   | `lower-thirds` | name/title bars, callouts, social overlays                                                                                                                                         |
+   | `maps`         | a geographic shot — highlight regions, connect places, zoom to a location. Sub-fork: **vector** (D3, stylized) vs **basemap** (baked MapLibre — real satellite/dark/zoom-to-place) |
+   | `webpage`      | highlight / animate a real captured web page or UI _(search-driven)_                                                                                                               |
+   | `news`         | a news article → article-highlight: blur → zoom into keyword _(search-driven)_                                                                                                     |
+   | `tweet`        | a tweet → animated card _(search-driven)_                                                                                                                                          |
+   | `asset-fusion` | a real photo/asset's geometry _becomes_ the chart _(search-driven)_                                                                                                                |
+
+   If genuinely ambiguous between two, ask exactly one question. Then load `categories/<id>/module.md` for that category's specifics.
+
+2. **Asset strategy → `asset_needs[]`.** Each item: `{ role, kind: image|icon|logo|svg|news|web|tweet, query|source, treatment }`.
+   - asset-free (`kinetic-type`, most `stat`/`charts`) → `asset_needs: []`.
+   - `maps` → **vector** lane: `asset_needs: []` (D3/TopoJSON, runs live in HF). **basemap** lane (satellite/dark/zoom-to-place): `asset_needs: [{ type: "map-bake", … }]` (baked in Source — see `categories/maps/module.md`).
+   - `webpage` / `news` / `tweet` → search the real source (page / article / tweet) + a supporting image. **Two-pole queries only**: atomic (1–3 words, composable: portraits, logos, objects) OR specific (5–15 words: a news event, a tweet). Never the middle. A failed specific query is dropped, not broadened.
+   - `asset-fusion` → search or generate one hero asset.
+   - `logo-reveal` → user-supplied logo (`source`).
+
+3. **Envelope**: `duration_s` (3–30), `fps` (30), `canvas` (default 1080×1920; 16:9 / 1:1 per platform), `style`, `palette` (hex list, or `"derive-from-asset"`), `font` (from the HF embed list), `beats`, `export` (`mp4` | `alpha-overlay`).
+
+4. **Shot brief**: one paragraph — what the viewer experiences + the single dominant motion idea.
+
+## Part 2 — Design (after sourcing)
+
+Given the draft + resolved `assets/index.md` (if Step 2 ran) + `catalog-map.md`, design the shot **around the assets**:
+
+- Pick the **catalog block(s)** + the `hyperframes-animation` rules / blueprints (catalog-aware — see `catalog-map.md`).
+- Layout (hero-frame), motion (per `references/motion-vocabulary.md`), beats, pacing, exits.
+- `asset-fusion`: read the asset's **geometric affordance** → `element_positions` (center / extent / safe-zones / avoid-zones) + **eyedropper palette** from the asset.
+- Finalize `shot-plan.json`: `content.block` + `content.customize` + the per-category `content`.
+
+## Heuristics (design-led short motion)
+
+- **Motion IS the message**; no narration arc. Hook lands fast (~first 0.5s). **One dominant motif.** Pattern-interrupt if the piece runs >~2.5s (change exactly one thing). Effect intensity matches the energy. Legibility: a key element stays readable ≥~0.3s. Beats may be anticipated ~0.1s for perceived sync.
+- **Reuse-first**: name a catalog block; ask for hand-authored motion only for gaps + the `asset-fusion` affordance.
+
+Then hand `shot-plan.json` to the Builder.

package/assets/.agent/skills/motion-graphics/agents/finalize.md

@@ -1,17 +1,17 @@
-# Finalize / repair (subagent)
-
-Snapshot visual QA + one in-place fix pass + render. Dispatched only when Step 6 `lint`/`inspect` reports issues, or to do the final render.
-
-## Dispatch context
-
-`SKILL_DIR` / `PROJECT_DIR` / `Render quality: draft|standard|high` / snapshot times / lint+inspect tails (if any).
-
-## Flow
-
-1. **Snapshots** — `npx hyperframes inspect . --at <beat times>`; eyeball for: overflow / off-canvas, text collisions, empty frames, wrong content, motion that doesn't read.
-2. **One in-place repair pass** — `Edit` `compositions/index.html` for the visible issues. **Never change a fixed `data-duration`** (timing is set upstream; changing it breaks assembly). Re-run `lint`/`inspect`.
-3. **Render** — `(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q <quality> -o ./renders/video.mp4)` (add `--format webm` for an alpha overlay export). Verify the mp4 exists + duration matches.
-
-## STOP / escalate
-
-Only when the shot is **fundamentally wrong** (whole content off, needs recomposition) — return to Step 3/4 (re-design + re-build), don't force it with edits. Small fixes never escalate.
+# Finalize / repair (subagent)
+
+Snapshot visual QA + one in-place fix pass + render. Dispatched only when Step 6 `lint`/`inspect` reports issues, or to do the final render.
+
+## Dispatch context
+
+`SKILL_DIR` / `PROJECT_DIR` / `Render quality: draft|standard|high` / snapshot times / lint+inspect tails (if any).
+
+## Flow
+
+1. **Snapshots** — `npx hyperframes inspect . --at <beat times>`; eyeball for: overflow / off-canvas, text collisions, empty frames, wrong content, motion that doesn't read.
+2. **One in-place repair pass** — `Edit` `compositions/index.html` for the visible issues. **Never change a fixed `data-duration`** (timing is set upstream; changing it breaks assembly). Re-run `lint`/`inspect`.
+3. **Render** — `(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q <quality> -o ./renders/video.mp4)` (add `--format webm` for an alpha overlay export). Verify the mp4 exists + duration matches.
+
+## STOP / escalate
+
+Only when the shot is **fundamentally wrong** (whole content off, needs recomposition) — return to Step 3/4 (re-design + re-build), don't force it with edits. Small fixes never escalate.