dsh-hyperframes 0.9.1 → 0.9.2

package/skills/motion-graphics/SKILL.md

@@ -1,178 +1,10 @@
 ---
 name: motion-graphics
-description: >
-  A short, design-led motion graphic where motion is the message — kinetic
-  typography, stat count-up, chart/data-viz hit, logo sting / brand lockup,
-  lower-third / callout / social overlay, animated map (highlight regions,
-  connect places, zoom to a location), animated tweet / news-article /
-  headline, webpage / UI animation (scroll, cursor, callouts), or fusing a
-  real image's geometry into a chart. Usually under 10s (up to ~30s), no
-  narration or live-action subject; renders to MP4 or transparent overlay.
-  Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.
+description: Compatibility entry for the retired motion-graphics skill; routes to the current official hyperframes skill.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+# motion-graphics: compatibility entry
 
-> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update motion-graphics`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+The current official HyperFrames release merged this workflow into the `hyperframes` skill. Load `hyperframes` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-> **figma source**: If the logo/asset/animation to build from comes from a figma.com URL, run `/figma` first — asset export, brand tokens, and Motion→GSAP translation if the graphic is a Figma Motion import — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
-
-# motion-graphics — dispatch entry
-
-> **The front door is `/hyperframes`.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). Anything longer, narrated, or multi-scene — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
-
-This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review. The intent layer (`/hyperframes` → `references/intent-interview.md`) routes here directly without run-shape questions; a storyboard and companion session add little to a piece this short. Rendering is still user-gated: after checks and proof snapshots pass, ask the canonical “preview first, or render?” question from `../hyperframes/references/brief-contract.md`. When a `BRIEF.md` exists, read it before the director's question.
-
-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`           |
-| verify   | Bash — `lint`, `check`, proof snapshots; repair on failure            | `snapshots/contact-sheet.jpg`                                    | Step 5                        |
-| approve  | Ask preview or render; wait for the answer                            | explicit render approval                                         | Step 6                        |
-| render   | Bash — `hyperframes render` (MP4, or `--format webm/mov` for overlay) | `renders/video.mp4` or transparent overlay                       | Step 6                        |
-
-`◇ 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                                       |
-| `maps`         | geographic motion — highlight regions, connect places, zoom to a location (vector lane, or baked basemap lane) | `us-map` / `world-map` family + `bake-basemap.mjs`                          |
-
-**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 --skill=motion-graphics
-```
-
-`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 — Verify (Bash → repair subagent on failure)
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes lint .)
-(cd "$PROJECT_DIR" && npx hyperframes check .)
-(cd "$PROJECT_DIR" && npx hyperframes snapshot --at <proof-times>)
-```
-
-Choose proof times that show the opening state, signature move, and final hold. Inspect the generated contact or snapshot sheet before continuing. On `lint`, `check`, or snapshot failure, dispatch the repair subagent (`agents/finalize.md`) for one in-place fix pass, then rerun the failed gate. Never change a fixed duration merely to hide a defect.
-
-### Step 6 — Approve and render (Bash)
-
-Ask one question: “preview first, or render?” If the user chooses preview, open Studio and return to the same approval gate after revisions:
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes preview --background)
-```
-
-Render only after an explicit render answer:
-
-```bash
-(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q high -o ./renders/video.mp4)
-# transparent overlay variant: --format webm  (or mov)
-```
-
-Verify the output exists, is non-empty, and has the intended duration. The final handoff names the artifact, actual duration, composition or frame id, proof times, and the inspected contact or snapshot sheet. Flags live in `/hyperframes-cli` → `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, proof snapshots absent | Step 5 (verify)            |
-| checks and proof snapshots pass, no approved render      | Step 6 (approval)          |
-| approved render exists                                   | verify output, then report |
-
-## 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.
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.

package/skills/music-to-video/SKILL.md

@@ -1,210 +1,10 @@
 ---
 name: music-to-video
-description: "Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes."
+description: Compatibility entry for the retired music-to-video skill; routes to the current official hyperframes skill.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+# music-to-video: compatibility entry
 
-> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update music-to-video`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+The current official HyperFrames release merged this workflow into the `hyperframes` skill. Load `hyperframes` from the DSH skill registry and follow its current instructions for the user's task. Use its bundled resources; do not reconstruct the retired workflow or download standalone skills.
 
-# music-to-video — one music-grounded, beat-synced video workflow
-
-Use this skill to turn a **music track** into a beat-synced HyperFrames video. You analyze the track once, lay out the frames, fill in a per-frame plan, and build each frame as a composition. The input is a music track plus optional user images or videos — there is **no narration and no website capture**. Typography and templates are the floor (a complete video needs zero assets); any media the user supplies is cut in on the same beat grid.
-
-You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval) — both are checkpoint gates per `../hyperframes/references/brief-contract.md` (read it before Step 0): in autonomous mode, post the summary as a heads-up and proceed instead of waiting. Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
-
-`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
-
-Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
-
-## Two ideas that shape everything
-
-- **One analyzer, and you trust it.** `analyze-beatgrid.py` is the only beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable. Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it. Deciding which case you're in is each frame's `pacing` (Step 2).
-- **One frame = one file; groups live inside.** Step 2 cuts the track into **frames**, and each frame becomes one composition file `compositions/frames/NN-<frame_id>.html`, built by one frame-worker. A frame can subdivide into **groups** (each a template or a motion-primitives combo). Extra density goes _inside_ a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
-
----
-
-## Step 0: Setup, BGM, and inputs
-
-Goal: Establish the music source, create the HyperFrames project, and note any user-supplied media.
-
-**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it confirms this route's must-haves (the music source, destination → aspect — `../hyperframes/references/routes/music-to-video.md`) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.
-
-The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`references/bgm.md`). Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply one branch:
-
-- **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider.
-- **Autonomous:** state the status and continue through the available local provider.
-
-If no offline provider can satisfy the required music capability, surface the blocker. Never write keys into a per-repo `.env`. Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers. The resulting track lands at `assets/bgm.mp3`. Stage supplied images or videos so frames can use them on the beat grid; otherwise typography carries the video.
-
-**Lyric videos:** for lyrics synced to the vocals, get word/line timing by transcribing the track via `/media-use`, or ask the user for the lyrics text and place lines on the beat grid.
-
-Initialize only if `hyperframes.json` is missing. Name `<project>` from the brief in kebab-case, such as `midnight-drive-loop` — never a timestamp. `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
-
-```bash
-npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video
-mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
-cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"   # extract from a video first if needed
-# only if the user gave you images/videos:
-node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
-```
-
-The **brand** (font + palette) is chosen at Step 3, not here. Don't pick a genre or a track type up front — assets are just an optional ingredient, and the genre emerges from the per-frame choices.
-
-**Gate:** `hyperframes.json` + `assets/bgm.mp3` exist; aspect / length / fps and (if any) the asset inventory are noted.
-
----
-
-## Step 1: Analyze the music
-
-Goal: Produce the one canonical timing analysis the whole video is built on.
-
-`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. It reads the track once and writes `audiomap.json`: energy phases (level / density / feel), onsets + `onset_rate`, rolls, silences, `hard_stops`, `key_moments`, phrases, tempo / grid, and `audio.duration_sec`. It's deterministic — the same file always gives the same map. Most fields are reliable on any music; `bpm` and `beats_sec` are reliable only when the music is genuinely rhythmic, and judging that is the call you make at Step 2.
-
-Prerequisites: Python 3 with `librosa`, `numpy`, and `soundfile` available. If import fails, install them into the active Python environment before running the analyzer:
-
-```bash
-python3 -m pip install librosa numpy soundfile
-```
-
-```bash
-python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-  -o "$PROJECT_DIR/audiomap.json" --print
-```
-
-**Gate:** `audiomap.json` exists; `audio.duration_sec` is known.
-
----
-
-## Step 2: Frame skeleton (structure only)
-
-Goal: Read the music and lay out the frames — the skeleton of `STORYBOARD.md`.
-
-Read [`references/frame-skeleton.md`](references/frame-skeleton.md). Turn `audiomap.json` into the **skeleton** of `STORYBOARD.md` yourself — there is no intermediate JSON. Cut the track into **frames** at real musical changes (`hard_stops`, SURGE / DROP `key_moments`, the edges of a roll, a stretch with no onsets, a big energy jump), snapping every boundary to an audiomap anchor. For each frame set `span_sec`, `pacing` (the verdict from Step 1's trust call — `beat_cut` when the grid is real, `phrase_flow` when it's a metronome imposed on calm music), `mood`, and a one-line `feel` (the plain music situation Step 3 matches a template against). Only classify and lay out here: leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank — no templates, copy, color, or fonts. Expect ~1–6 frames.
-
-**Gate:** frames tile the track (first at 0, last at `duration_s`); each carries `span_sec` + `pacing` + `mood` + `feel`; every `### Groups` is `TBD`; no content anywhere.
-
----
-
-## Step 3: Fill the plan (user-gated)
-
-Goal: Turn the skeleton into an approved, complete `STORYBOARD.md`.
-
-Read [`references/planning.md`](references/planning.md), [`storyboard-format.md`](references/storyboard-format.md), [`template-catalog.md`](references/template-catalog.md), [`motion-primitive-catalog.md`](references/motion-primitive-catalog.md), and [`montage.md`](references/montage.md) (only if the user supplied assets). Editing the same file in place, do two things:
-
-1. **Pick the brand.** Choose one preset from `../hyperframes-creative/frame-presets/` using the table in `../hyperframes-creative/references/design-spec.md` (match the track's mood; **only its fonts and colors matter** — templates own composition). Copy it into `frame.md` **unmodified** and fill the frontmatter `style` (font + a ≤4–6 swatch palette) from it.
-2. **Fill every frame.** Decide its groups and give each a treatment: a matched template from the catalog (with bound params and real audiomap anchors), a free-compose from the primitive catalog, or an asset treatment that **obeys `pacing`**. **Before you free-compose a named look, search the live catalog for it**: for every look, effect, treatment or transition the user asked for — "CRT scanlines", "glitch", "film grain", "shimmer sweep" — run `npx hyperframes catalog --query "<the look, in plain English>" --json` and read the top results. `template-catalog.md` and `motion-primitive-catalog.md` list only this skill's own local materials; the search ranks the whole hosted registry (~400 blocks and components) and needs **nothing installed** — no project, no prior `add`, no account. Free-compose a look only after a search for it came back with nothing that fits. Write the copy. You own WHAT (template / primitives + content + anchors); the frame-worker owns HOW — **never write millisecond tweens into the storyboard**.
-
-```bash
-node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
-  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
-```
-
-Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then present the frame-by-frame summary in chat as a proposal (`../hyperframes/references/review-loop.md` § 1) and iterate on the user's replies until they approve; for `storyboard: yes`, also write it as `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3) for them to open. In autonomous mode this is a checkpoint gate: post the summary as a heads-up and proceed (the `validate-plan.mjs` pass is a quality gate and still blocks).
-
-**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan (autonomous: the summary was posted as a heads-up).
-
----
-
-## Step 4: Build frames from the plan
-
-Goal: Build every frame as a self-contained composition file.
-
-Create `compositions/frames/`. Read [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) and `../hyperframes/references/subagent-dispatch.md`. Dispatch **one frame-worker per frame**, in parallel where possible (otherwise in waves). Each worker gets exactly one frame and this context:
-
-```text
-PROJECT_DIR: <abs path>
-frame_id: <NN-frame_id>              # = the frame file stem, e.g. 02-f2; the composition id
-Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
-audiomap: PROJECT_DIR/audiomap.json
-frame.md: PROJECT_DIR/frame.md
-Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
-           <SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
-Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
-Canvas: <w>×<h>   Pacing: <beat_cut|phrase_flow>
-Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
-```
-
-The worker forks the cited materials, converts every anchor to frame-local seconds (`local_t = track_t − span_sec[0]`), gates its groups with 0ms cuts, and writes one seek-safe frame file. **The worker never runs the `hyperframes` CLI** — those commands operate on the assembled project, which doesn't exist yet, so they'd report on the wrong files. The worker just writes to the contract and stops; you verify after assembly (Step 6). As each worker returns, you can confirm its file landed on disk.
-
-**Gate:** every frame has its `compositions/frames/NN-*.html` on disk.
-
----
-
-## Step 5: Assemble
-
-Goal: Wire the built frames + BGM into the playable `index.html`.
-
-`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
-
-```bash
-node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
-  --hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
-```
-
-Fix any `✗` it reports — a missing or blank frame file means that worker wrote a partial file; re-dispatch it (Step 4) and re-assemble.
-
-**Gate:** `index.html` exists; total duration == `audiomap.audio.duration_sec`.
-
----
-
-## Step 6: Verify and render
-
-Goal: Verify the assembled video, get user approval, and render the final MP4.
-
-Run the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `check` runs structural lint and the headless-browser runtime, layout, motion, and contrast gate in one pass; `--snapshots` also emits the review frames.
-
-```bash
-( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
-```
-
-Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval (autonomous mode: ask the one kept question — "preview first, or render?" — then deliver the MP4 with the contact sheet):
-
-```bash
-( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
-```
-
-**Gate:** `check` passed and the snapshots were inspected; the user approved (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
-
----
-
-## Resume table
-
-| You have                   | Continue from |
-| -------------------------- | ------------- |
-| `assets/bgm.mp3` only      | Step 1        |
-| `audiomap.json`            | Step 2        |
-| `STORYBOARD.md` (skeleton) | Step 3        |
-| `STORYBOARD.md` (complete) | Step 4        |
-| all frame files            | Step 5        |
-| `index.html`               | Step 6        |
-
-## Quick Reference
-
-**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the canvas once in the storyboard frontmatter (`canvas: { w, h, fps }`).
-
-**Scripts** under `scripts/`: `analyze-beatgrid.py` (the one analyzer), `validate-plan.mjs` (plan check), `assemble-index.mjs` (index assembly), `stage-assets.mjs` (stage user media), `lib/storyboard.mjs` (vendored parser). Everything else is the `hyperframes` CLI.
-
-| Read                                                                                                           | When                                                    |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
-| [`references/frame-skeleton.md`](references/frame-skeleton.md)                                                 | Step 2: read the music, lay out the frames, set pacing  |
-| [`references/planning.md`](references/planning.md) · [`storyboard-format.md`](references/storyboard-format.md) | Step 3: pick the brand, fill each frame, write the plan |
-| [`references/template-catalog.md`](references/template-catalog.md)                                             | Step 3: pick a template per group                       |
-| [`references/motion-primitive-catalog.md`](references/motion-primitive-catalog.md)                             | Step 3/4: L0 recipes for free-compose                   |
-| [`references/montage.md`](references/montage.md)                                                               | Step 3/4: asset treatments (beat-cut / ken-burns)       |
-| [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md)                                                     | Step 4: dispatch + build one frame                      |
-| `../hyperframes/references/subagent-dispatch.md`                                                               | Step 4: dispatch sub-agents safely                      |
-| `../hyperframes-creative/references/design-spec.md`                                                            | Step 3: pick the preset (the brand)                     |
-
-## Directory layout
-
-```
-music-to-video/
-  SKILL.md
-  references/   frame-skeleton.md · planning.md · storyboard-format.md
-                template-catalog.md · motion-primitive-catalog.md · montage.md
-                templates/<id>/          { index.html (+ assets/ · program.json) }  ← L1 catalog impls
-                motion-primitives/<id>/  { index.html (mounts the scene), scene.html (the sub-composition) } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls
-  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
-  sub-agents/   frame-worker.md   ← the one subagent (one per frame)
-```
+For an existing project, preserve its files and dependencies. DSH plugin management owns this installed skill bundle. The upstream plugin launcher pins HyperFrames 0.8.207 and suppresses standalone skill installation; run it in the user's project directory. This entry preserves the previous DSH skill name while using the current workflow.