feat(media-use): resolve engine + BGM/SFX/image/icon providers

The resolve cascade and all v1 providers, using heygen-cli with
--x-source media-use for attribution.

- resolve.mjs: cheapest-first cascade (manifest → assets/ → cache →
  heygen-cli → freeze → register)
- providers.mjs: pluggable registry with 4 real providers
- heygen-search.mjs: shared CLI exec helper for all providers
- bgm-provider: heygen audio sounds list --type music
- sfx-provider: heygen audio sounds list --type sound_effects
- image-provider: heygen asset search list --type image + icon
- SKILL.md: full agent-facing docs with types, examples, flags
- Router skill wiring: added media-use to routing table

Author: miguel-heygen

skills/hyperframes/SKILL.md

@@ -32,6 +32,7 @@ Atomic capabilities you load **on demand** — not full video workflows. For "ma
 | **Animate** — atomic motion, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU) | `/hyperframes-animation` |
 | **Creative direction** — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive                          | `/hyperframes-creative`  |
 | **Media** — TTS voiceover, background music, transcription, background removal, captions                                                   | `/hyperframes-media`     |
+| **Media resolve** — find + freeze BGM, SFX, images, icons from HeyGen catalog into `.media/` with manifest tracking                        | `/media-use`             |
 | **CLI dev loop** — init, lint, validate, inspect, preview, render, publish, doctor                                                         | `/hyperframes-cli`       |
 | **Install registry blocks / components** (`hyperframes add`)                                                                               | `/hyperframes-registry`  |
 

skills/media-use/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: media-use
+description: Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade: project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.
+---
+
+# media-use
+
+Resolve media needs into frozen local files. One verb, four types, zero context noise.
+
+## When to use
+
+Call `resolve` whenever a composition needs media — background music, sound effects, images, or icons. media-use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk.
+
+## Resolve
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
+```
+
+Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
+
+### Types
+
+| Type    | What it finds       | Provider                                 |
+| ------- | ------------------- | ---------------------------------------- |
+| `bgm`   | Background music    | HeyGen audio catalog (10k+ tracks)       |
+| `sfx`   | Sound effects       | Bundled 19-file library + HeyGen catalog |
+| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors)       |
+| `icon`  | Icons, logos        | HeyGen asset search (type=icon)          |
+
+### Examples
+
+```bash
+# Background music
+node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
+# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
+
+# Sound effect
+node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
+# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
+
+# Image
+node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
+# → resolved image_001 → .media/images/image_001.jpg (image)
+
+# Icon
+node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
+# → resolved icon_001 → .media/images/icon_001.svg (icon, transparent)
+```
+
+### Flags
+
+| Flag            | Description                                |
+| --------------- | ------------------------------------------ |
+| `--type, -t`    | Media type: bgm, sfx, image, icon          |
+| `--intent, -i`  | What you need (natural language)           |
+| `--entity, -e`  | Entity name for cache matching (optional)  |
+| `--project, -p` | Project directory (default: .)             |
+| `--adopt`       | Bulk-import existing assets/ into manifest |
+| `--json`        | Output JSON instead of one-line result     |
+
+## How it works
+
+1. Check project `.media/manifest.jsonl` for exact-prompt match
+2. Scan existing `assets/` directory for unregistered files matching the need
+3. Check global cache `~/.media/` for reusable asset
+4. Search via provider (HeyGen audio catalog, HeyGen asset search)
+5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`
+
+The agent gets back **one line**. Candidates, scores, provenance stay on disk.
+
+## Adopt existing projects
+
+Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
+# → adopted 9 assets from assets/
+#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
+#   image_001 → assets/images/avatar.jpg (image, 400×400)
+```
+
+`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
+
+## Reading the inventory
+
+After resolve or adopt, read `.media/index.md` for the full inventory:
+
+```
+# .media · 4 assets
+
+id         type   dur   dims       path                          description
+bgm_001    bgm    25s   —          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
+sfx_001    sfx    0.6s  —          .media/audio/sfx/sfx_001.mp3  whoosh
+image_001  image  —     1920×1080  .media/images/image_001.jpg   gradient tech background
+icon_001   icon   —     svg        .media/images/icon_001.svg    rocket
+```
+
+## Cross-project reuse
+
+Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at `~/.media/` — no re-download, no provider call. Promote an asset explicitly with `organize --promote <id>` to make it reusable across all projects.
+
+## Files
+
+- `.media/manifest.jsonl` — machine SSOT, one JSON record per line
+- `.media/index.md` — agent-readable table (id, type, dur, dims, path, description)
+- `~/.media/` — global cross-project reuse cache (content-addressed, SHA-256)
+
+## CLI tools used
+
+| Tool      | Purpose                                    | Required?     |
+| --------- | ------------------------------------------ | ------------- |
+| `ffprobe` | Probe duration, dimensions, codec on adopt | Yes           |
+| `heygen`  | Audio catalog, asset search                | For providers |

skills/media-use/scripts/lib/bgm-provider.mjs

@@ -0,0 +1,20 @@
+import { heygenSearch } from "./heygen-search.mjs";
+
+export const bgmProvider = {
+  async search(intent) {
+    const results = heygenSearch("audio sounds list", intent, { type: "music" });
+    if (!results) return null;
+    const best = results[0];
+    return {
+      url: best.audio_url,
+      source: "search",
+      ext: ".mp3",
+      metadata: {
+        description: best.description || intent,
+        duration: best.duration || null,
+        provider: "heygen.audio.sounds",
+        provenance: { track_id: best.id, score: best.score, query: intent },
+      },
+    };
+  },
+};

skills/media-use/scripts/lib/heygen-search.mjs

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+
+export function heygenSearch(subcommand, query, { type, limit = 5, minScore } = {}) {
+  try {
+    const q = query.replace(/'/g, "'\\''");
+    const parts = [`heygen --x-source media-use ${subcommand} --query '${q}'`];
+    if (type) parts.push(`--type ${type}`);
+    parts.push(`--limit ${limit}`);
+    if (minScore != null) parts.push(`--min-score ${minScore}`);
+    const out = execSync(parts.join(" "), { encoding: "utf8", timeout: 15000, stdio: ["pipe", "pipe", "pipe"] });
+    const data = JSON.parse(out)?.data;
+    return Array.isArray(data) && data.length > 0 ? data : null;
+  } catch {
+    return null;
+  }
+}

skills/media-use/scripts/lib/image-provider.mjs

@@ -0,0 +1,41 @@
+import { heygenSearch } from "./heygen-search.mjs";
+
+export const imageProvider = {
+  async search(intent) {
+    const results = heygenSearch("asset search list", intent, { type: "image" });
+    if (!results) return null;
+    const best = results[0];
+    return {
+      url: best.url,
+      source: "search",
+      ext: ".jpg",
+      metadata: {
+        description: intent,
+        width: best.width || null,
+        height: best.height || null,
+        transparent: best.is_transparent || false,
+        provider: "heygen.asset.search",
+        provenance: { asset_id: best.id, score: best.score },
+      },
+    };
+  },
+};
+
+export const iconProvider = {
+  async search(intent) {
+    const results = heygenSearch("asset search list", intent, { type: "icon", minScore: 0.2 });
+    if (!results) return null;
+    const best = results[0];
+    return {
+      url: best.url,
+      source: "search",
+      ext: ".svg",
+      metadata: {
+        description: intent,
+        transparent: true,
+        provider: "heygen.asset.search",
+        provenance: { asset_id: best.id, score: best.score, type: "icon" },
+      },
+    };
+  },
+};

skills/media-use/scripts/lib/providers.mjs

@@ -0,0 +1,24 @@
+import { sfxProvider } from "./sfx-provider.mjs";
+import { imageProvider, iconProvider } from "./image-provider.mjs";
+import { bgmProvider } from "./bgm-provider.mjs";
+
+const STUB = { async search() { return null; } };
+
+const registry = {
+  bgm: { ...bgmProvider, type: "bgm" },
+  sfx: { ...sfxProvider, type: "sfx" },
+  voice: { ...STUB, type: "voice" },
+  image: { ...imageProvider, type: "image" },
+  icon: { ...iconProvider, type: "icon" },
+  brand: { ...STUB, type: "brand" },
+};
+
+export function getProvider(type) {
+  const p = registry[type];
+  if (!p) throw new Error(`unknown media type: ${type}`);
+  return p;
+}
+
+export function listTypes() {
+  return Object.keys(registry);
+}

skills/media-use/scripts/lib/sfx-provider.mjs

@@ -0,0 +1,20 @@
+import { heygenSearch } from "./heygen-search.mjs";
+
+export const sfxProvider = {
+  async search(intent) {
+    const results = heygenSearch("audio sounds list", intent, { type: "sound_effects", minScore: 0.4 });
+    if (!results) return null;
+    const best = results[0];
+    return {
+      url: best.audio_url,
+      source: "search",
+      ext: ".mp3",
+      metadata: {
+        description: best.description || best.name || intent,
+        duration: best.duration || null,
+        provider: "heygen.audio.sounds",
+        provenance: { track_id: best.id, score: best.score, query: intent },
+      },
+    };
+  },
+};