dsh-hyperframes 0.3.1 → 0.4.0

package/skills/media-use/scripts/transcribe.mjs

@@ -12,7 +12,7 @@ import {
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, extname, join, resolve } from "node:path";
-import { parseArgs } from "node:util";
+import { parseArgs, stripVTControlCharacters } from "node:util";
 import { mergeTokensToWords } from "./lib/parakeet-words.mjs";
 import { track } from "./lib/telemetry.mjs";
 import { resolveNpxInvocation } from "./lib/npx-sync.mjs";
@@ -49,7 +49,8 @@ Usage:
 
 Parakeet (default) beats whisper.cpp on accuracy + speed for English/European
 languages; whisper.cpp (99 languages) is the fallback. Install Parakeet once:
-  uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`);
+  npx hyperframes models install parakeet   (macOS, Windows, Linux with glibc 2.32+)
+  uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx   (Apple Silicon)`);
   process.exit(0);
 }
 
@@ -122,33 +123,57 @@ function runParakeet(runner) {
   }
 }
 
-// whisper.cpp via the hyperframes CLI (fetched/built on first use — see
+// The hyperframes CLI (its Parakeet, else whisper.cpp built on first use — see
 // SKILL.md): writes transcript.json into --dir; relocate to --out.
-function runWhisper() {
+function runCli(cliEngine) {
   const workDir = mkdtempSync(join(tmpdir(), "media-use-whisper-"));
   try {
     // On Windows a bare "npx" is npx.cmd, which execFileSync cannot exec
     // (spawnSync npx ENOENT) — resolveNpxInvocation reroutes it through
     // node + npx-cli.js (and throws actionably when it can't), same
     // mechanism as the audio engine's TTS spawns.
+    // Under auto or parakeet the CLI may run its own Parakeet; --json says which engine ran.
     const resolved = resolveNpxInvocation(
-      ["hyperframes", "transcribe", inputPath, "--dir", workDir],
+      ["hyperframes", "transcribe", inputPath, "--dir", workDir, "--engine", cliEngine, "--json"],
       { stdio: ["ignore", "pipe", "pipe"], timeout: 1_800_000 },
     );
-    execFileSync(resolved.cmd, resolved.args, resolved.opts);
+    let stdout;
+    try {
+      stdout = String(execFileSync(resolved.cmd, resolved.args, resolved.opts));
+    } catch (e) {
+      // stderr holds spinner redraws and --json prints the reason on stdout, so keep the last lines.
+      const tail = stripVTControlCharacters(`${e.stderr ?? ""}\n${e.stdout ?? ""}`)
+        .split(/[\r\n]+/)
+        .map((l) => l.trim())
+        .filter((l) => l && l !== "│")
+        .slice(-3)
+        .join("\n");
+      throw new Error(
+        `hyperframes transcribe failed (exit ${e.status ?? e.code})${tail ? `:\n${tail}` : ""}`,
+      );
+    }
     const produced = join(workDir, "transcript.json");
-    if (!existsSync(produced)) throw new Error("whisper produced no transcript.json");
+    if (!existsSync(produced))
+      throw new Error("hyperframes transcribe produced no transcript.json");
     const tmp = `${outPath}.tmp-${process.pid}`;
     copyFileSync(produced, tmp);
     renameSync(tmp, outPath); // atomic publish
     let words;
     try {
       const t = JSON.parse(readFileSync(outPath, "utf8"));
-      words = Array.isArray(t?.words) ? t.words.length : undefined;
+      // The CLI writes a flat word array, not { words }.
+      words = Array.isArray(t) ? t.length : undefined;
     } catch {
       /* leave undefined */
     }
-    report("whisper", words);
+    let ran = "whisper";
+    try {
+      ran = JSON.parse(stdout.trim().split("\n").at(-1)).engine === "parakeet" ? "parakeet" : ran;
+    } catch {
+      /* no JSON line: keep whisper */
+    }
+    report(ran, words);
+    return ran;
   } finally {
     rmSync(workDir, { recursive: true, force: true });
   }
@@ -156,22 +181,11 @@ function runWhisper() {
 
 try {
   const parakeetBin = resolveParakeet();
-  const engine =
-    args.engine === "parakeet" || args.engine === "whisper"
-      ? args.engine
-      : parakeetBin
-        ? "parakeet"
-        : "whisper";
-  if (engine === "parakeet") {
-    if (!parakeetBin) {
-      throw new Error(
-        "parakeet-mlx not found (checked $HYPERFRAMES_PARAKEET, ~/.venvs/parakeet, and PATH). Install: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx (or use --engine whisper)",
-      );
-    }
-    runParakeet(parakeetBin);
-  } else {
-    runWhisper();
-  }
+  const asked = args.engine === "parakeet" || args.engine === "whisper" ? args.engine : "auto";
+  // Without parakeet-mlx, the CLI's own Parakeet (any OS, `hyperframes models install parakeet`).
+  let engine = "parakeet";
+  if (asked !== "whisper" && parakeetBin) runParakeet(parakeetBin);
+  else engine = runCli(asked);
   await track("media_use_transcribe", { engine });
 } catch (err) {
   if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));

package/skills/media-use/scripts/transcribe.test.mjs

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+// The stub stands in for `npx hyperframes transcribe <in> --dir <dir> ...`: it records its args,
+// writes the CLI's flat array and prints the CLI's --json line naming `cliEngine`.
+function runScript(engine, cliEngine) {
+  const root = mkdtempSync(join(tmpdir(), "media-use-transcribe-"));
+  try {
+    const bin = join(root, "bin");
+    mkdirSync(bin);
+    writeFileSync(
+      join(bin, "npx"),
+      `#!/bin/sh\necho "$@" > "${root}/args"\nwhile [ "$1" != "--dir" ]; do shift; done\n` +
+        `echo '[{"text":"a","start":0,"end":1},{"text":"b","start":1,"end":2}]' > "$2/transcript.json"\n` +
+        `echo '{"ok":true,"engine":"${cliEngine}"}'\n`,
+    );
+    chmodSync(join(bin, "npx"), 0o755);
+    const input = join(root, "in.wav");
+    writeFileSync(input, "");
+    const script = fileURLToPath(new URL("./transcribe.mjs", import.meta.url));
+    const env = { ...process.env, PATH: `${bin}:${process.env.PATH}`, HOME: root };
+    delete env.HYPERFRAMES_PARAKEET;
+    const out = execFileSync(
+      process.execPath,
+      [script, "--input", input, "--engine", engine, "--json"],
+      {
+        encoding: "utf8",
+        env: { ...env, HYPERFRAMES_MEDIA_HOME: join(root, "home"), HYPERFRAMES_NO_TELEMETRY: "1" },
+      },
+    );
+    return { result: JSON.parse(out.trim()), args: readFileSync(join(root, "args"), "utf8") };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test(
+  "--engine whisper makes the CLI run whisper and reports the flat transcript's word count",
+  { skip: process.platform === "win32" },
+  () => {
+    const { result, args } = runScript("whisper", "whisper");
+    assert.match(args, /--engine whisper --json/);
+    assert.equal(result.words, 2);
+    assert.equal(result.engine, "whisper");
+  },
+);
+
+test(
+  "auto reports the engine the CLI says it ran, Parakeet included",
+  { skip: process.platform === "win32" },
+  () => {
+    const { result, args } = runScript("auto", "parakeet");
+    assert.match(args, /--engine auto --json/);
+    assert.equal(result.engine, "parakeet");
+  },
+);
+
+test(
+  "--engine parakeet without parakeet-mlx asks the CLI for its Parakeet",
+  { skip: process.platform === "win32" },
+  () => {
+    const { result, args } = runScript("parakeet", "parakeet");
+    assert.match(args, /--engine parakeet --json/);
+    assert.equal(result.engine, "parakeet");
+  },
+);
+
+test(
+  "a failed --engine parakeet run reports the reason the CLI printed on stdout",
+  { skip: process.platform === "win32" },
+  () => {
+    const root = mkdtempSync(join(tmpdir(), "media-use-transcribe-"));
+    try {
+      const bin = join(root, "bin");
+      mkdirSync(bin);
+      const reason =
+        "Parakeet is not installed. Install it with: hyperframes models install parakeet";
+      writeFileSync(
+        join(bin, "npx"),
+        `#!/bin/sh\necho '{"ok":false,"error":"${reason}"}'\nexit 1\n`,
+      );
+      chmodSync(join(bin, "npx"), 0o755);
+      const input = join(root, "in.wav");
+      writeFileSync(input, "");
+      const script = fileURLToPath(new URL("./transcribe.mjs", import.meta.url));
+      const res = spawnSync(
+        process.execPath,
+        [script, "--input", input, "--engine", "parakeet", "--json"],
+        {
+          encoding: "utf8",
+          env: {
+            ...process.env,
+            HYPERFRAMES_PARAKEET: "",
+            PATH: `${bin}:${process.env.PATH}`,
+            HOME: root,
+            HYPERFRAMES_MEDIA_HOME: join(root, "home"),
+            HYPERFRAMES_NO_TELEMETRY: "1",
+          },
+        },
+      );
+      assert.equal(res.status, 1);
+      assert.match(JSON.parse(res.stdout.trim()).error, /hyperframes models install parakeet/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  },
+);

package/skills/media-use/scripts/transcript-cut.mjs

@@ -6,6 +6,7 @@ import { tmpdir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { compileCutList } from "./lib/cutlist.mjs";
+import { fadeFilterFor } from "./lib/transcriptCutFade.mjs";
 import { track } from "./lib/telemetry.mjs";
 
 const { values: args } = parseArgs({
@@ -92,11 +93,23 @@ function run() {
 
   try {
     const parts = segments.map((segment, index) => {
-      const out = join(
-        tmpDir,
-        `segment-${String(index).padStart(4, "0")}${extname(outPath) || ".mp4"}`,
-      );
-      cutSegment(inputPath, segment, out, Boolean(args.copy));
+      // Intermediates carry PCM audio, not the final codec. Encoding each
+      // segment to a lossy codec separately makes the encoder pad every segment
+      // with priming silence (~25-35ms for AAC), which concat then bakes in as a
+      // gap at each cut -- a defect distinct from, and surviving, the fades
+      // below. PCM has no priming, so audio is encoded exactly once, at concat.
+      const ext = args.copy ? extname(outPath) || ".mp4" : isAudioOnly(outPath) ? ".wav" : ".mkv";
+      const out = join(tmpDir, `segment-${String(index).padStart(4, "0")}${ext}`);
+      // --copy stays fade-free (stream copy cannot filter). A segment's true
+      // start/end (index 0's start, the last segment's end) borders nothing
+      // kept, so only an interior splice edge gets a ramp.
+      const fade = args.copy
+        ? null
+        : fadeFilterFor(segment.end - segment.start, {
+            fadeIn: index > 0,
+            fadeOut: index < segments.length - 1,
+          });
+      cutSegment(inputPath, segment, out, args.copy, fade);
       return out;
     });
     const listPath = join(tmpDir, "list.txt");
@@ -107,9 +120,16 @@ function run() {
     // Encode to a sibling temp (same extension so ffmpeg picks the right muxer),
     // then atomic-rename so a SIGKILL mid-encode can't leave a truncated outPath.
     const tmpOut = `${outPath}.part${extname(outPath) || ".mp4"}`;
+    // --copy already produced final-codec segments, so concat can stream-copy.
+    // Otherwise the PCM intermediates are encoded here, once, for the whole file.
+    const concatCodecs = args.copy
+      ? ["-c", "copy"]
+      : isAudioOnly(outPath)
+        ? encodeArgsFor(extname(outPath).toLowerCase())
+        : ["-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart"];
     execFileSync(
       "ffmpeg",
-      ["-y", "-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", tmpOut],
+      ["-y", "-f", "concat", "-safe", "0", "-i", listPath, ...concatCodecs, tmpOut],
       {
         stdio: "ignore",
       },
@@ -158,7 +178,7 @@ function run() {
   console.log(`next: resolve --from ${outPath} --type <type>`);
 }
 
-function cutSegment(inputPath, segment, outPath, copy) {
+function cutSegment(inputPath, segment, outPath, copy, fade) {
   const argv = [
     "-y",
     "-nostdin",
@@ -171,8 +191,15 @@ function cutSegment(inputPath, segment, outPath, copy) {
   ];
   if (copy) {
     argv.push("-c", "copy", "-avoid_negative_ts", "make_zero");
+  } else if (extname(outPath).toLowerCase() === ".mkv") {
+    // Concat splices raw segment edges together; without a short ramp the
+    // waveform steps discontinuously at every boundary and you hear a click.
+    if (fade) argv.push("-af", fade);
+    // Video intermediate: keep the picture cheap and the audio uncompressed.
+    argv.push("-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-c:a", "pcm_s16le");
   } else {
-    argv.push(...encodeArgsFor(extname(outPath).toLowerCase()));
+    if (fade) argv.push("-af", fade);
+    argv.push("-c:a", "pcm_s16le");
   }
   argv.push(outPath);
   execFileSync("ffmpeg", argv, { stdio: "ignore" });
@@ -180,6 +207,10 @@ function cutSegment(inputPath, segment, outPath, copy) {
 
 // Codec set per output container. Audio-only outputs must not get the
 // video-centric aac/x264 set (aac inside .wav breaks timing entirely).
+function isAudioOnly(filePath) {
+  return [".wav", ".mp3", ".m4a", ".aac", ".flac"].includes(extname(filePath).toLowerCase());
+}
+
 function encodeArgsFor(ext) {
   if (ext === ".wav") return ["-c:a", "pcm_s16le"];
   if (ext === ".mp3") return ["-c:a", "libmp3lame", "-q:a", "2"];

package/skills/media-use/scripts/transcript-cut.test.mjs

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT = fileURLToPath(new URL("./transcript-cut.mjs", import.meta.url));
+const HAS_FFMPEG =
+  spawnSync("ffmpeg", ["-version"], { stdio: "ignore" }).status === 0 &&
+  spawnSync("ffprobe", ["-version"], { stdio: "ignore" }).status === 0;
+
+const SAMPLE_RATE = 44100;
+// A continuous tone's own slope between samples never exceeds amplitude * 2*pi*f/rate
+// (~2054 for 440Hz at full scale here); a raw splice between two independently-cut
+// points on the same tone lands at two unrelated phases, so an unfaded join jumps far
+// past that. This threshold sits well above normal tone motion and well below a splice.
+const MAX_CONTINUOUS_STEP = 6000;
+const MIN_SUSPICIOUS_ZERO_RUN = 20;
+
+function fixture() {
+  const dir = mkdtempSync(join(tmpdir(), "media-use-transcript-cut-"));
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+function run(args) {
+  return spawnSync(process.execPath, [SCRIPT, ...args], { encoding: "utf8" });
+}
+
+function readPcm(filePath) {
+  const raw = execFileSync("ffmpeg", [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-i",
+    filePath,
+    "-f",
+    "s16le",
+    "-ac",
+    "1",
+    "-ar",
+    String(SAMPLE_RATE),
+    "-",
+  ]);
+  const samples = new Int16Array(raw.buffer, raw.byteOffset, raw.length / 2);
+  return samples;
+}
+
+test(
+  "keeps a spliced tone continuous at every cut, with no raw phase jump or silence gap",
+  { skip: !HAS_FFMPEG },
+  (t) => {
+    const { dir, cleanup } = fixture();
+    t.after(cleanup);
+
+    const source = join(dir, "tone.wav");
+    execFileSync("ffmpeg", [
+      "-y",
+      "-hide_banner",
+      "-loglevel",
+      "error",
+      "-f",
+      "lavfi",
+      "-i",
+      `sine=frequency=440:duration=6:sample_rate=${SAMPLE_RATE}`,
+      source,
+    ]);
+
+    const transcriptPath = join(dir, "transcript.json");
+    writeFileSync(transcriptPath, JSON.stringify({ words: [{ text: "tone", start: 0, end: 6 }] }));
+
+    const output = join(dir, "out.wav");
+    // Two "ugly" removal ranges: neither aligned to the 440Hz period, so the kept
+    // segments' cut edges land at unrelated phases of the same continuous tone --
+    // exactly the shape that clicks without a fade, and the shape jrusso1020's
+    // review proved this branch never actually fades.
+    const result = run([
+      "--input",
+      source,
+      "--transcript",
+      transcriptPath,
+      "--remove",
+      "1.37-1.83,3.29-3.71",
+      "--out",
+      output,
+      "--json",
+    ]);
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+
+    const samples = readPcm(output);
+    assert.ok(samples.length > SAMPLE_RATE, "expected several seconds of audio");
+
+    let maxStep = 0;
+    let zeroRun = 0;
+    let maxZeroRun = 0;
+    for (let i = 1; i < samples.length; i++) {
+      const step = Math.abs(samples[i] - samples[i - 1]);
+      if (step > maxStep) maxStep = step;
+      if (samples[i] === 0) {
+        zeroRun++;
+        if (zeroRun > maxZeroRun) maxZeroRun = zeroRun;
+      } else {
+        zeroRun = 0;
+      }
+    }
+
+    assert.ok(
+      maxStep <= MAX_CONTINUOUS_STEP,
+      `largest sample-to-sample step was ${maxStep}, expected <= ${MAX_CONTINUOUS_STEP} (a raw, unfaded splice)`,
+    );
+    assert.ok(
+      maxZeroRun < MIN_SUSPICIOUS_ZERO_RUN,
+      `found a run of ${maxZeroRun} consecutive zero samples, expected < ${MIN_SUSPICIOUS_ZERO_RUN} (a priming-silence gap)`,
+    );
+  },
+);

package/skills/motion-graphics/SKILL.md

@@ -11,6 +11,8 @@ description: >
   Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.
 ---
 
+**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.
+
 > **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.
 
 > **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.
@@ -19,7 +21,7 @@ description: >
 
 > **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-core/references/brief-contract.md`. When a `BRIEF.md` exists, read it before the director's question.
+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.
 

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

@@ -6,6 +6,7 @@ Turn `shot-plan.json` into one renderable HyperFrames composition (`compositions
 
 Default = **compose existing catalog capabilities, not hand-author**:
 
+- **Search first, for every named effect** — `npx hyperframes catalog --query "<the move, in plain English>" --json`, including an effect the user names after the plan is written. It needs nothing installed and no project. Author by hand only after a search came back with nothing that does the job, and report that miss with `npx hyperframes feedback --search-miss`.
 - `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).
 

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

@@ -40,7 +40,8 @@ Emit a DRAFT `shot-plan.json`.
 
 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`).
+- **Run `npx hyperframes catalog --query "<the move, in plain English>" --json` for every look or effect the brief names**, before naming any block. It ranks the whole hosted registry and needs nothing installed. `catalog-map.md` is a partial snapshot; the search is the source of truth.
+- Pick the **catalog block(s)** from those results + the `hyperframes-animation` rules / blueprints (see `catalog-map.md` for how each category customizes).
 - 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`.

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

@@ -1,5 +1,18 @@
 # Director → catalog block map (reuse-first)
 
+<!-- registry-items: allow=geo-highlight,geo-flow,flag-borders,pin-rollout,stat-motion,data-composition-src -->
+<!-- allow= entries above are deliberately NOT registry items: geo-*/flag-borders/pin-rollout and stat-motion are hand-authored gaps this file names in order to say they are gaps. -->
+
+**Search the live catalog before you use this table, and again before any hand-authored effect.** Run
+`npx hyperframes catalog --query "<the move, in plain English>" --json` — once per named look or effect the
+user asks for ("CRT scanlines", "glitch", "film grain", "shimmer sweep"), including effects asked for
+mid-build. **The search needs nothing installed**: it ranks the whole hosted registry (~400 items) from any
+directory, with no project, no prior `add`, and no account. The table below is a hand-maintained snapshot of
+part of that registry and it under-covers by design — treat a miss here as unproven, and only the search's
+own empty result as evidence the catalog lacks the move. When it does, say so with
+`npx hyperframes feedback --search-miss "<query>" --wanted "<the move>" --tier <tier from the envelope>`
+before hand-authoring. Full flags and tiers: `/hyperframes-registry` → § Discovery.
+
 The Builder's **default is to compose existing HF catalog blocks, not hand-author.** `npx hyperframes add <block>` drops a block's source into `compositions/`; the Builder then **customizes in place** — most blocks bake their content/data into their own script (only a few expose CSS-var `params`), so reuse = **add + edit**, not pure variable injection. Hand-author only (a) gaps no block covers and (b) the asset-fusion affordance binding.
 
 After classifying intent → category, the **Director names the block(s) + what to customize** in the shot-plan IR:
@@ -10,19 +23,18 @@ After classifying intent → category, the **Director names the block(s) + what
 
 ## Category → block(s)
 
-| Category               | Borrow from catalog                                                                                                                                                                                                                                                                                                                                                                                                                   | Customize                                                                                        | Gaps → hand-author                                                                                             |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| **kinetic-typo**       | one of **18 `caption-*`** (kinetic-slam, editorial-emphasis, clip-wipe, gradient-fill, neon-glow, glitch-rgb, matrix-decode, particle-burst, weight-shift, pill-karaoke, highlight, blend-difference…)                                                                                                                                                                                                                                | words; `emphasis_words` → `word--emphasis`; palette; font; timing                                | a motif none of the 18 cover                                                                                   |
-| **charts**             | `data-chart` (bar+line, staggered, value labels)                                                                                                                                                                                                                                                                                                                                                                                      | edit the data array + headline/subtitle; `--bg`/`--text`                                         | pie/donut, bar-chart-race, ring/%                                                                              |
-| **stat**               | `apple-money-count` (finance: $ counter + burst + SFX) **or** our generic `stat-motion` (any %/number + ring)                                                                                                                                                                                                                                                                                                                         | target, prefix/suffix, label, palette                                                            | —                                                                                                              |
-| maps/geo               | **vector lane**: `us-map` (+bubble/hex/flow), `world-map`, `spain-map` + **hand-author** `geo-highlight`/`geo-flow`/`flag-borders`/`pin-rollout` (NOT in registry — build per `categories/maps/module.md`). **basemap lane** (real satellite/dark / zoom-to-place): bake via `categories/maps/bake-basemap.mjs` → `<video>` + geo-aligned SVG overlay (border draw-on + colour-block fills)                                           | regions/data, palette, callouts/connectors, basemap style                                        | (basemap lane now covers real imagery + zoom-to-address — was the gap)                                         |
-| diagram                | `flowchart` (SVG connectors + nodes)                                                                                                                                                                                                                                                                                                                                                                                                  | nodes, edges, labels                                                                             | —                                                                                                              |
-| **code / code-reveal** | one of the **9 Code Animations** blocks: `code-typing` (live typing), `code-diff` (a change), `code-morph` (a refactor), `code-highlight` (spotlight a line; `line` is 0-based), `code-scroll` (walk a file), `code-snippet-flight` (assemble); GPU hero reveals `code-3d-extrude` / `code-shader-dissolve` / `code-particle-assemble` for a title-card moment; for a static themed code/terminal window use a `code-snippet-*` block | the baked code string / diff / theme                                                             | a code motion none cover                                                                                       |
-| **brand reveal**       | `logo-outro` (piece assembly + glow + tagline + URL pill)                                                                                                                                                                                                                                                                                                                                                                             | logo asset, tagline, URL, palette                                                                | —                                                                                                              |
-| transitions            | 15+ shader transitions (domain-warp, whip-pan, sdf-iris, glitch…)                                                                                                                                                                                                                                                                                                                                                                     | direction, timing                                                                                | —                                                                                                              |
-| social overlay         | ig / tiktok / yt / x / reddit / spotify / macos cards                                                                                                                                                                                                                                                                                                                                                                                 | handle, metrics, avatar                                                                          | —                                                                                                              |
-| polish                 | grain-overlay, vignette, shimmer-sweep, texture-mask-text                                                                                                                                                                                                                                                                                                                                                                             | intensity                                                                                        | —                                                                                                              |
-| **asset-fusion (RWA)** | **annotation kit from `north-korea-locked-down`** — scribble-circle draw-on, pop-up pill + pointer, red-wash, scanline, corners, camera push; + `us-map-bubble` callouts/connectors                                                                                                                                                                                                                                                   | asset, annotation position (`element_positions`), label, palette **eyedropper'd from the asset** | **NET-NEW (not in catalog): the affordance binding — asset geometry _becomes_ the chart axis (straw → gauge)** |
+| Category               | Borrow from catalog                                                                                                                                                                                                                                                                                                                                                                         | Customize                                                                                        | Gaps → hand-author                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| **kinetic-typo**       | one of **17 `caption-*`** (kinetic-slam, editorial-emphasis, clip-wipe, gradient-fill, neon-glow, glitch-rgb, matrix-decode, particle-burst, weight-shift, pill-karaoke, highlight, blend-difference…)                                                                                                                                                                                      | words; `emphasis_words` → `word--emphasis`; palette; font; timing                                | a motif none of the 17 cover                                                                                   |
+| **charts**             | `data-chart` (bar+line, staggered, value labels), `bar-chart-race` (a race)                                                                                                                                                                                                                                                                                                                 | edit the data array + headline/subtitle; `--bg`/`--text`                                         | pie/donut, ring/%                                                                                              |
+| **stat**               | `apple-money-count` (finance: $ counter + burst + SFX) **or** hand-author a generic %/number + ring per `categories/stat/module.md` (there is no `stat-motion` block)                                                                                                                                                                                                                       | target, prefix/suffix, label, palette                                                            | —                                                                                                              |
+| maps/geo               | **vector lane**: `us-map` (+bubble/hex/flow), `world-map`, `spain-map` + **hand-author** `geo-highlight`/`geo-flow`/`flag-borders`/`pin-rollout` (NOT in registry — build per `categories/maps/module.md`). **basemap lane** (real satellite/dark / zoom-to-place): bake via `categories/maps/bake-basemap.mjs` → `<video>` + geo-aligned SVG overlay (border draw-on + colour-block fills) | regions/data, palette, callouts/connectors, basemap style                                        | (basemap lane now covers real imagery + zoom-to-address — was the gap)                                         |
+| diagram                | `flowchart` (SVG connectors + nodes)                                                                                                                                                                                                                                                                                                                                                        | nodes, edges, labels                                                                             | —                                                                                                              |
+| **brand reveal**       | `logo-outro` (piece assembly + glow + tagline + URL pill)                                                                                                                                                                                                                                                                                                                                   | logo asset, tagline, URL, palette                                                                | —                                                                                                              |
+| transitions            | 15+ shader transitions (domain-warp, whip-pan, sdf-iris, glitch…)                                                                                                                                                                                                                                                                                                                           | direction, timing                                                                                | —                                                                                                              |
+| social overlay         | ig / tiktok / yt / x / reddit / spotify / macos cards                                                                                                                                                                                                                                                                                                                                       | handle, metrics, avatar                                                                          | —                                                                                                              |
+| polish                 | grain-overlay, vignette, shimmer-sweep, texture-mask-text                                                                                                                                                                                                                                                                                                                                   | intensity                                                                                        | —                                                                                                              |
+| **asset-fusion (RWA)** | **annotation kit from `north-korea-locked-down`** — scribble-circle draw-on, pop-up pill + pointer, red-wash, scanline, corners, camera push; + `us-map-bubble` callouts/connectors                                                                                                                                                                                                         | asset, annotation position (`element_positions`), label, palette **eyedropper'd from the asset** | **NET-NEW (not in catalog): the affordance binding — asset geometry _becomes_ the chart axis (straw → gauge)** |
 
 ## Reuse mechanics
 

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

@@ -9,7 +9,8 @@ Animated **data-viz** from data. Asset-free (the "input" is the data). "One char
 ## Vocabulary / leans on
 
 - Block: **`data-chart`** (animated **bar + line**, staggered reveal, value labels — proven: borrowed + customized + rendered to MP4 in the prototype `charts-demo`).
-- Gaps (hand-author): **pie / donut, bar-chart-race, ring/%** — `data-chart` doesn't cover these. Use D3/visx for data→geometry + GSAP for motion.
+- Also in the registry: **`bar-chart-race`** — install it rather than hand-authoring a race.
+- Gaps (hand-author): **pie / donut, ring/%** — no registry block covers these. Search first (`npx hyperframes catalog --query "pie chart reveal" --json`), then use D3/visx for data→geometry + GSAP for motion.
 - Signature animations: bar stagger-grow · line `stroke-dashoffset` draw-on · pie radial sweep · ring fill · KPI count-up · race reorder.
 
 ## Build (reuse-first)

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

@@ -1,5 +1,9 @@
 # lower-thirds — category module
 
+<!-- registry-items: allow= -->
+
+**The live search is the source of truth for what the registry has.** The table(s) below are a hand-maintained sample and under-cover by design: run `npx hyperframes catalog --query "<what you want>" --json` — it needs nothing installed — before concluding the registry lacks something. Item names here are checked against `registry/registry.json` by `bun run lint:skills`.
+
 **Name/title bars, callouts, social overlays** — graphics meant to sit over other footage. Asset-free (+ optional logo). Usually `export: alpha-overlay` (transparent). ~3–6s (or loop/hold).
 
 ## Plan (Director)

package/skills/motion-graphics/categories/news/module.md

@@ -11,7 +11,7 @@ Two layouts share that one highlight core — pick by aspect + whether there's a
 
 ## Source (Step 2)
 
-RWA / web search (or `hyperframes capture`) → a real article. The Director extracts the **keyword** (1–2 words / a number / a name — the hook) and, for Layout B, also a **brand logo**, a **date**, and a **person photo**. `asset_needs: { kind: news|web|image, query }` — request the logo (Wikimedia / simple-icons) and the person photo (Wikimedia) as separate asset queries. Run the person photo through `hyperframes remove-background <in> -o <out>.png` to get a transparent cutout.
+RWA / web search (or `hyperframes capture`) → a real article. The Director extracts the **keyword** (1–2 words / a number / a name — the hook) and, for Layout B, also a **brand logo**, a **date**, and a **person photo**. `asset_needs: { kind: news|web|image, query }` — request the logo (`media-use resolve --type logo`, theSVG-first) and the person photo (Wikimedia) as separate asset queries. Run the person photo through `hyperframes remove-background <in> -o <out>.png` to get a transparent cutout.
 
 ## The highlight core (shared by both layouts) — the marker-band technique
 

package/skills/motion-graphics/references/motion-vocabulary.md

@@ -1,5 +1,9 @@
 # text module · motion vocabulary (primitive → GSAP)
 
+<!-- registry-items: allow= -->
+
+**The live search is the source of truth for what the registry has.** The table(s) below are a hand-maintained sample and under-cover by design: run `npx hyperframes catalog --query "<what you want>" --json` — it needs nothing installed — before concluding the registry lacks something. Item names here are checked against `registry/registry.json` by `bun run lint:skills`.
+
 Named primitives the Director references in `motion` strings and the Builder implements. `code_hint`s are framework-neutral physics; the GSAP recipe is the HF implementation. Prefer an HF **registry component** (bottom) when one fits — don't reinvent.
 
 ## Entry