Add HyperFrames skills

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011h6NB8JQtfPc6eRCefEzBB

.agents/skills/media-use/scripts/lib/config-lock.mjs

@@ -0,0 +1,45 @@
+// The one lock on ~/.hyperframes/config.json, for the CLI, its auto-update step and media-use. The auto-update step
+// embeds this function's source, so it must use only its arguments and globals.
+export function withFileLock(lockPath, fs, task) {
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const started = Date.now();
+  for (;;) {
+    let fd;
+    try {
+      fd = fs.openSync(lockPath, "wx");
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      // Never taken over: a lock older than any hold was left by a process that stopped, and a person removes it.
+      let leftover = false;
+      try {
+        leftover = Date.now() - fs.statSync(lockPath).mtimeMs > 5000;
+      } catch {}
+      if (leftover || Date.now() - started > 10000)
+        throw Object.assign(
+          new Error(
+            `Settings are locked by another hyperframes process. If none is running, delete ${lockPath}`,
+          ),
+          { code: "HF_SETTINGS_LOCKED" },
+        );
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+      continue;
+    }
+    try {
+      fs.writeSync(fd, token);
+    } catch (error) {
+      fs.rmSync(lockPath, { force: true });
+      throw error;
+    } finally {
+      fs.closeSync(fd);
+    }
+    break;
+  }
+  try {
+    return task();
+  } finally {
+    // No code removes another's lock, so release needs no check (only a person deleting a live one defeats it).
+    try {
+      fs.rmSync(lockPath);
+    } catch {}
+  }
+}

.agents/skills/media-use/scripts/lib/cutlist.mjs

@@ -0,0 +1,191 @@
+import { normalizeWords } from "./words.mjs";
+
+const MIN_SEGMENT_SECONDS = 0.2;
+const SILENCE_PAD_SECONDS = 0.15;
+
+export function compileCutList(transcript, opts = {}) {
+  const words = normalizeWords(transcript);
+  if (opts.keep != null && hasRemovalSource(opts)) {
+    throw new Error("--keep is mutually exclusive with removal options");
+  }
+
+  if (opts.keep != null) {
+    const duration = durationFrom(words, opts);
+    const ranges = parseTimeRanges(opts.keep);
+    return finalizeKept(duration != null ? clampRanges(ranges, duration) : ranges);
+  }
+
+  const duration = durationFrom(words, opts);
+  if (!duration) return [];
+
+  const removals = [
+    ...parseTimeRanges(opts.remove),
+    ...wordIndexRanges(words, opts.removeWords),
+    ...fillerRanges(words, opts.removeFillers),
+    ...silenceRanges(words, opts.cutSilence),
+  ];
+  const mergedRemovals = mergeRanges(clampRanges(removals, duration));
+  return finalizeKept(invertRanges(mergedRemovals, duration));
+}
+
+function hasRemovalSource(opts) {
+  return (
+    opts.remove != null ||
+    opts.removeWords != null ||
+    opts.removeFillers != null ||
+    opts.cutSilence != null
+  );
+}
+
+function durationFrom(words, opts) {
+  const explicit = Number(opts.duration ?? opts.totalDuration);
+  if (Number.isFinite(explicit) && explicit > 0) return explicit;
+  const last = words.at(-1);
+  return last && Number.isFinite(last.end) && last.end > 0 ? last.end : null;
+}
+
+function parseTimeRanges(value) {
+  if (value == null || value === false || value === "") return [];
+  if (typeof value === "string") {
+    return value
+      .split(",")
+      .map((part) => part.trim())
+      .filter(Boolean)
+      .map(parseRangeString);
+  }
+  if (!Array.isArray(value)) throw new Error("range list must be a string or array");
+  return value.map((range) => {
+    if (Array.isArray(range)) return cleanRange(Number(range[0]), Number(range[1]));
+    return cleanRange(Number(range?.start), Number(range?.end));
+  });
+}
+
+function parseRangeString(value) {
+  const match = value.match(/^([0-9]*\.?[0-9]+)\s*-\s*([0-9]*\.?[0-9]+)$/);
+  if (!match) throw new Error(`invalid range: ${value}`);
+  return cleanRange(Number(match[1]), Number(match[2]));
+}
+
+function cleanRange(start, end) {
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error("range start/end must be finite numbers");
+  }
+  if (end < start) throw new Error(`range end ${end} is before start ${start}`);
+  return { start, end };
+}
+
+function wordIndexRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const ranges = typeof value === "string" ? value.split(",") : value;
+  if (!Array.isArray(ranges)) throw new Error("--remove-words must be a string or array");
+  return ranges
+    .map((range) => (typeof range === "string" ? range.trim() : range))
+    .filter(Boolean)
+    .map((range) => {
+      const [first, last = first] =
+        typeof range === "string" ? range.split("-").map((n) => n.trim()) : range;
+      const startIndex = Number(first);
+      const endIndex = Number(last);
+      if (!Number.isInteger(startIndex) || !Number.isInteger(endIndex)) {
+        throw new Error(`invalid word range: ${range}`);
+      }
+      if (startIndex < 0 || endIndex < startIndex || endIndex >= words.length) {
+        throw new Error(`word range out of bounds: ${range}`);
+      }
+      return { start: words[startIndex].start, end: words[endIndex].end };
+    });
+}
+
+function fillerRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const fillers = Array.isArray(value)
+    ? value
+    : String(value)
+        .split(",")
+        .map((s) => s.trim());
+  const set = new Set(fillers.filter(Boolean).map(bareToken));
+  if (set.size === 0) return [];
+  // Whisper emits words with attached punctuation and arbitrary case
+  // ("UM," / "Um."), so compare bare tokens.
+  return words
+    .filter((word) => set.has(bareToken(word.text)))
+    .map((word) => ({ start: word.start, end: word.end }));
+}
+
+function bareToken(text) {
+  return String(text)
+    .toLowerCase()
+    .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "");
+}
+
+function silenceRanges(words, value) {
+  if (value == null || value === false || value === "") return [];
+  const threshold = Number(value);
+  if (!Number.isFinite(threshold) || threshold <= 0) {
+    throw new Error("--cut-silence must be a positive number");
+  }
+  const ranges = [];
+  for (let i = 0; i < words.length - 1; i++) {
+    const current = words[i];
+    const next = words[i + 1];
+    const gap = next.start - current.end;
+    if (gap <= threshold) continue;
+    const start = current.end + SILENCE_PAD_SECONDS;
+    const end = next.start - SILENCE_PAD_SECONDS;
+    if (end > start) ranges.push({ start, end });
+  }
+  return ranges;
+}
+
+function clampRanges(ranges, duration) {
+  return ranges
+    .map((range) => ({
+      start: Math.max(0, Math.min(duration, range.start)),
+      end: Math.max(0, Math.min(duration, range.end)),
+    }))
+    .filter((range) => range.end > range.start);
+}
+
+function mergeRanges(ranges) {
+  const sorted = ranges
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const range of sorted) {
+    const prev = merged.at(-1);
+    if (prev && range.start <= prev.end) {
+      prev.end = Math.max(prev.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function invertRanges(removals, duration) {
+  const kept = [];
+  let cursor = 0;
+  for (const range of removals) {
+    if (range.start > cursor) kept.push({ start: cursor, end: range.start });
+    cursor = Math.max(cursor, range.end);
+  }
+  if (cursor < duration) kept.push({ start: cursor, end: duration });
+  return kept;
+}
+
+// Range bounds are rounded only to shed float noise, never to the millisecond:
+// these values become ffmpeg's -ss/-to, where a millisecond is wide enough to
+// step a boundary onto the next frame at 29.97/30/60 fps.
+function finalizeKept(ranges) {
+  return mergeRanges(ranges)
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
+    .filter((range) => round3(range.end - range.start) >= MIN_SEGMENT_SECONDS);
+}
+
+function round6(n) {
+  return Math.round(Number(n) * 1e6) / 1e6;
+}
+
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}

.agents/skills/media-use/scripts/lib/duck.mjs

@@ -0,0 +1,96 @@
+import { wordListsFromMediaMeta } from "./words.mjs";
+
+// audio_meta.json word times are relative to each line's own file.
+export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false, gap = 0 } = {}) {
+  const merge = Number(mergeGap);
+  const lists = wordListsFromMediaMeta(meta);
+  const voices = Array.isArray(meta?.voices) ? meta.voices : [];
+  if (lists.filter((words) => words.length > 0).length > 1 && !offsets && !sequential) {
+    throw new Error(
+      "audio_meta has multiple voice lines with file-relative times; pass --sequential or --offsets so spans land at composition time",
+    );
+  }
+  const intervals = [];
+  let cursor = 0;
+  for (let i = 0; i < lists.length; i++) {
+    const voice = voices[i];
+    let offset = 0;
+    if (offsets) {
+      if (lists[i].length === 0) continue;
+      const id = voice?.id ?? String(i);
+      if (!(id in offsets)) throw new Error(`--offsets is missing voice "${id}"`);
+      offset = Number(offsets[id]) || 0;
+    } else if (sequential) {
+      offset = cursor;
+      const lineDuration = Number(voice?.duration_s) || Math.max(...lists[i].map((w) => w.end), 0);
+      cursor += lineDuration + (Number(gap) || 0);
+    }
+    for (const word of lists[i]) {
+      if (word.end > word.start)
+        intervals.push({ start: word.start + offset, end: word.end + offset });
+    }
+  }
+  return mergeIntervals(intervals, Number.isFinite(merge) && merge >= 0 ? merge : 0.6);
+}
+
+export function duckKeyframes(
+  spans,
+  { duck = 0.25, attack = 0.15, release = 0.4, baseVolume = 1 } = {},
+) {
+  const base = finiteOr(baseVolume, 1);
+  const ducked = round3(base * finiteOr(duck, 0.25));
+  const keyframes = [];
+  for (const span of spans) {
+    keyframes.push({
+      time: round3(Math.max(0, finiteOr(span.start, 0))),
+      volume: ducked,
+      duration: round3(finiteOr(attack, 0.15)),
+    });
+    keyframes.push({
+      time: round3(Math.max(0, finiteOr(span.end, 0))),
+      volume: round3(base),
+      duration: round3(finiteOr(release, 0.4)),
+    });
+  }
+  return keyframes.sort((a, b) => a.time - b.time);
+}
+
+/** Volume lane for `data-automation`: composition-time keyframes as clip-local ramps. */
+export function duckLane(keyframes, { clipStart = 0, baseVolume = 1 } = {}) {
+  const start = finiteOr(clipStart, 0);
+  const points = [{ t: 0, v: round3(finiteOr(baseVolume, 1)) }];
+  const push = (t, v) => {
+    if (t > points.at(-1).t) points.push({ t: round3(t), v });
+  };
+  for (const kf of keyframes) {
+    const t = Math.max(0, kf.time - start);
+    push(t, points.at(-1).v);
+    push(t + kf.duration, kf.volume);
+  }
+  return { version: 1, lanes: [{ target: "volume", points }] };
+}
+
+function mergeIntervals(intervals, mergeGap) {
+  const sorted = intervals
+    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .sort((a, b) => a.start - b.start || a.end - b.end);
+  const merged = [];
+  for (const range of sorted) {
+    const prev = merged.at(-1);
+    if (prev && (range.start <= prev.end || range.start - prev.end < mergeGap)) {
+      prev.end = Math.max(prev.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function finiteOr(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}

.agents/skills/media-use/scripts/lib/error-diffusion.mjs

@@ -0,0 +1,230 @@
+export const ERROR_DIFFUSION_ALGORITHMS = {
+  "floyd-steinberg": {
+    kernel: [
+      [1, 0, 7],
+      [-1, 1, 3],
+      [0, 1, 5],
+      [1, 1, 1],
+    ],
+    divisor: 16,
+  },
+  atkinson: {
+    kernel: [
+      [1, 0, 1],
+      [2, 0, 1],
+      [-1, 1, 1],
+      [0, 1, 1],
+      [1, 1, 1],
+      [0, 2, 1],
+    ],
+    divisor: 8,
+  },
+  "jarvis-judice-ninke": {
+    kernel: [
+      [1, 0, 7],
+      [2, 0, 5],
+      [-2, 1, 3],
+      [-1, 1, 5],
+      [0, 1, 7],
+      [1, 1, 5],
+      [2, 1, 3],
+      [-2, 2, 1],
+      [-1, 2, 3],
+      [0, 2, 5],
+      [1, 2, 3],
+      [2, 2, 1],
+    ],
+    divisor: 48,
+  },
+  stucki: {
+    kernel: [
+      [1, 0, 8],
+      [2, 0, 4],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 8],
+      [1, 1, 4],
+      [2, 1, 2],
+      [-2, 2, 1],
+      [-1, 2, 2],
+      [0, 2, 4],
+      [1, 2, 2],
+      [2, 2, 1],
+    ],
+    divisor: 42,
+  },
+  burkes: {
+    kernel: [
+      [1, 0, 8],
+      [2, 0, 4],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 8],
+      [1, 1, 4],
+      [2, 1, 2],
+    ],
+    divisor: 32,
+  },
+  sierra: {
+    kernel: [
+      [1, 0, 5],
+      [2, 0, 3],
+      [-2, 1, 2],
+      [-1, 1, 4],
+      [0, 1, 5],
+      [1, 1, 4],
+      [2, 1, 2],
+      [-1, 2, 2],
+      [0, 2, 3],
+      [1, 2, 2],
+    ],
+    divisor: 32,
+  },
+  "sierra-lite": {
+    kernel: [
+      [1, 0, 2],
+      [-1, 1, 1],
+      [0, 1, 1],
+    ],
+    divisor: 4,
+  },
+  "two-row-sierra": {
+    kernel: [
+      [1, 0, 4],
+      [2, 0, 3],
+      [-2, 1, 1],
+      [-1, 1, 2],
+      [0, 1, 3],
+      [1, 1, 2],
+      [2, 1, 1],
+    ],
+    divisor: 16,
+  },
+};
+
+const DEFAULTS = {
+  algorithm: "floyd-steinberg",
+  brightness: 1,
+  contrast: 1.2,
+  detail: 1,
+  palette: ["#000000", "#ffffff"],
+  pointSize: 3,
+};
+
+export function errorDiffusionBufferLength(width, height, pointSize) {
+  return Math.ceil(width / pointSize) * Math.ceil(height / pointSize) * 3;
+}
+
+export function applyErrorDiffusionRgba(data, width, height, options = {}, errorBuffer) {
+  if (!Number.isInteger(width) || width < 1 || !Number.isInteger(height) || height < 1) {
+    throw new Error("width and height must be positive integers");
+  }
+  if (!data || data.length !== width * height * 4) {
+    throw new Error(`RGBA data must contain ${width * height * 4} bytes`);
+  }
+
+  const algorithm = options.algorithm ?? DEFAULTS.algorithm;
+  const diffusion = ERROR_DIFFUSION_ALGORITHMS[algorithm];
+  if (!diffusion) throw new Error(`unknown error-diffusion algorithm: ${algorithm}`);
+
+  const pointSize = integerInRange(options.pointSize ?? DEFAULTS.pointSize, 1, 20, "pointSize");
+  const brightness = numberInRange(options.brightness ?? DEFAULTS.brightness, 0.5, 2, "brightness");
+  const contrast = numberInRange(options.contrast ?? DEFAULTS.contrast, 0.5, 2, "contrast");
+  const detail = numberInRange(options.detail ?? DEFAULTS.detail, 0.1, 1, "detail");
+  const palette = parsePalette(options.palette ?? DEFAULTS.palette);
+  const blockColumns = Math.ceil(width / pointSize);
+  const blockRows = Math.ceil(height / pointSize);
+  const errorLength = errorDiffusionBufferLength(width, height, pointSize);
+  const errors = errorBuffer ?? new Float32Array(errorLength);
+  if (!(errors instanceof Float32Array) || errors.length !== errorLength) {
+    throw new Error(`errorBuffer must be a Float32Array of length ${errorLength}`);
+  }
+  errors.fill(0);
+
+  const centerOffset = Math.floor(pointSize / 2);
+  for (let blockRow = 0; blockRow < blockRows; blockRow++) {
+    const blockY = blockRow * pointSize;
+    for (let blockColumn = 0; blockColumn < blockColumns; blockColumn++) {
+      const blockX = blockColumn * pointSize;
+      const centerX = Math.min(blockX + centerOffset, width - 1);
+      const centerY = Math.min(blockY + centerOffset, height - 1);
+      const rgbaIndex = (centerY * width + centerX) * 4;
+      const errorIndex = (blockRow * blockColumns + blockColumn) * 3;
+      const red = correctedChannel(data[rgbaIndex], errors[errorIndex], brightness, contrast);
+      const green = correctedChannel(
+        data[rgbaIndex + 1],
+        errors[errorIndex + 1],
+        brightness,
+        contrast,
+      );
+      const blue = correctedChannel(
+        data[rgbaIndex + 2],
+        errors[errorIndex + 2],
+        brightness,
+        contrast,
+      );
+      const luminance = 0.299 * red + 0.587 * green + 0.114 * blue;
+      const output = palette[Math.min(palette.length - 1, Math.floor(luminance * palette.length))];
+
+      for (let y = blockY; y < Math.min(blockY + pointSize, height); y++) {
+        for (let x = blockX; x < Math.min(blockX + pointSize, width); x++) {
+          const outputIndex = (y * width + x) * 4;
+          data[outputIndex] = Math.round(output[0] * 255);
+          data[outputIndex + 1] = Math.round(output[1] * 255);
+          data[outputIndex + 2] = Math.round(output[2] * 255);
+        }
+      }
+
+      for (const [dx, dy, weight] of diffusion.kernel) {
+        const targetColumn = blockColumn + dx;
+        const targetRow = blockRow + dy;
+        if (
+          targetColumn < 0 ||
+          targetColumn >= blockColumns ||
+          targetRow < 0 ||
+          targetRow >= blockRows
+        ) {
+          continue;
+        }
+        const target = (targetRow * blockColumns + targetColumn) * 3;
+        const scale = (weight / diffusion.divisor) * detail;
+        errors[target] += (red - output[0]) * scale;
+        errors[target + 1] += (green - output[1]) * scale;
+        errors[target + 2] += (blue - output[2]) * scale;
+      }
+    }
+  }
+  return data;
+}
+
+function correctedChannel(byte, error, brightness, contrast) {
+  return Math.min(1, Math.max(0, ((byte / 255 - 0.5) * contrast + 0.5) * brightness + error));
+}
+
+function parsePalette(colors) {
+  if (!Array.isArray(colors) || colors.length < 2 || colors.length > 6) {
+    throw new Error("palette must contain 2 to 6 colors");
+  }
+  return colors.map((color) => {
+    const match = /^#([0-9a-f]{6})$/i.exec(color);
+    if (!match) throw new Error(`palette color must use #rrggbb: ${color}`);
+    const value = Number.parseInt(match[1], 16);
+    return [(value >> 16) / 255, ((value >> 8) & 255) / 255, (value & 255) / 255];
+  });
+}
+
+function numberInRange(value, min, max, name) {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number < min || number > max) {
+    throw new Error(`${name} must be between ${min} and ${max}`);
+  }
+  return number;
+}
+
+function integerInRange(value, min, max, name) {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < min || number > max) {
+    throw new Error(`${name} must be an integer between ${min} and ${max}`);
+  }
+  return number;
+}

.agents/skills/media-use/scripts/lib/index-gen.mjs

@@ -0,0 +1,63 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { currentRecords, indexPath } from "./manifest.mjs";
+
+function pad(str, len) {
+  return String(str ?? "").padEnd(len);
+}
+
+function formatDur(record) {
+  if (record.duration == null) return "—";
+  return `${record.duration}s`;
+}
+
+function formatDims(record) {
+  if (record.width && record.height) return `${record.width}×${record.height}`;
+  if (record.type === "icon" && record.transparent) return "svg";
+  return "—";
+}
+
+export function generateIndexContent(records) {
+  const count = records.length;
+  const header = `# .media · ${count} asset${count === 1 ? "" : "s"}\n`;
+  if (count === 0) return header;
+
+  const cols = { id: 4, type: 5, dur: 4, dims: 5, path: 5, desc: 11 };
+  for (const r of records) {
+    cols.id = Math.max(cols.id, (r.id ?? "").length);
+    cols.type = Math.max(cols.type, (r.type ?? "").length);
+    cols.dur = Math.max(cols.dur, formatDur(r).length);
+    cols.dims = Math.max(cols.dims, formatDims(r).length);
+    cols.path = Math.max(cols.path, (r.path ?? "").length);
+  }
+
+  const heading =
+    pad("id", cols.id + 2) +
+    pad("type", cols.type + 2) +
+    pad("dur", cols.dur + 2) +
+    pad("dims", cols.dims + 2) +
+    pad("path", cols.path + 2) +
+    "description";
+
+  const lines = [header, heading];
+  for (const r of records) {
+    lines.push(
+      pad(r.id, cols.id + 2) +
+        pad(r.type, cols.type + 2) +
+        pad(formatDur(r), cols.dur + 2) +
+        pad(formatDims(r), cols.dims + 2) +
+        pad(r.path, cols.path + 2) +
+        (r.description ?? ""),
+    );
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function regenerateIndex(projectDir) {
+  const records = currentRecords(projectDir);
+  const content = generateIndexContent(records);
+  const p = indexPath(projectDir);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, content);
+  return content;
+}

.agents/skills/media-use/scripts/lib/manifest.mjs

@@ -0,0 +1,279 @@
+import {
+  readFileSync,
+  appendFileSync,
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  openSync,
+  closeSync,
+  writeFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
+
+const MANIFEST_FILE = "manifest.jsonl";
+const INDEX_FILE = "index.md";
+
+const TYPE_DIRS = {
+  bgm: "audio/bgm",
+  sfx: "audio/sfx",
+  voice: "audio/voice",
+  image: "images",
+  icon: "images",
+  logo: "images",
+  brand: "images",
+  video: "video",
+  grade: "luts",
+  lut: "luts",
+  recipe: "recipes",
+};
+
+export function mediaDir(projectDir) {
+  return join(projectDir, ".media");
+}
+
+export function manifestPath(projectDir) {
+  return join(mediaDir(projectDir), MANIFEST_FILE);
+}
+
+export function indexPath(projectDir) {
+  return join(mediaDir(projectDir), INDEX_FILE);
+}
+
+export function typeSubdir(type) {
+  const sub = TYPE_DIRS[type];
+  if (!sub) throw new Error(`unknown media type: ${type}`);
+  return sub;
+}
+
+export function typeDirPath(projectDir, type) {
+  return join(mediaDir(projectDir), typeSubdir(type));
+}
+
+export function readManifest(projectDir) {
+  const p = manifestPath(projectDir);
+  if (!existsSync(p)) return [];
+  const raw = readFileSync(p, "utf8");
+  const records = [];
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      // ponytail: skip malformed lines, don't crash
+    }
+  }
+  return records;
+}
+
+export function appendRecord(projectDir, record) {
+  const dir = mediaDir(projectDir);
+  mkdirSync(dir, { recursive: true });
+  const typeDir = typeDirPath(projectDir, record.type);
+  mkdirSync(typeDir, { recursive: true });
+
+  const p = manifestPath(projectDir);
+  const line = JSON.stringify(record) + "\n";
+  appendFileSync(p, line);
+}
+
+/** Sources that mean the agent made or fetched the file; any other file is the person's own. */
+export const AGENT_SOURCES = ["generated", "search", "bundled"];
+
+/** The record a path has now: the manifest only appends, so the last one for a path wins. */
+export function latestRecordFor(projectDir, path) {
+  return readManifest(projectDir).findLast((record) => record.path === path);
+}
+
+/** Records with every older record for the same path dropped, since the last one for a path is its record. */
+export function currentRecords(projectDir) {
+  const records = readManifest(projectDir);
+  const last = new Map(records.map((record, index) => [record.path, index]));
+  return records.filter((record, index) => !record.path || last.get(record.path) === index);
+}
+
+/** Records a file already in the project where it is, unless its current record already says the same thing. */
+export function recordInPlace(
+  projectDir,
+  { type, path, source, description, duration, provenance },
+) {
+  const fields = {
+    type,
+    path,
+    source,
+    description: description || basename(path),
+    ...(duration != null && { duration: Math.round(duration * 10) / 10 }),
+  };
+  mkdirSync(mediaDir(projectDir), { recursive: true });
+  return withLock(mediaDir(projectDir), () => {
+    const latest = latestRecordFor(projectDir, path);
+    const same = ["source", "description", "duration"].every(
+      (key) => latest?.[key] === fields[key],
+    );
+    if (latest && same) return latest;
+    const record = { id: nextFreeId(projectDir, type), ...fields, provenance };
+    appendRecord(projectDir, record);
+    return record;
+  });
+}
+
+// Match prompts forgivingly. Agents rarely re-emit a byte-identical intent, so
+// keying cache lookups on exact equality meant "Calm piano" and "calm  piano"
+// re-searched and re-downloaded. Normalize (trim, lowercase, collapse internal
+// whitespace) on both sides; the raw prompt is still stored for audit.
+export function normalizePrompt(prompt) {
+  return String(prompt ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ");
+}
+
+export function findByPrompt(projectDir, prompt, type) {
+  const key = normalizePrompt(prompt);
+  if (!key) return null;
+  const records = currentRecords(projectDir);
+  return (
+    records.find(
+      (r) => normalizePrompt(r.provenance?.prompt) === key && (type == null || r.type === type),
+    ) || null
+  );
+}
+
+export function findByEntity(projectDir, entity) {
+  const lower = entity.toLowerCase();
+  const records = currentRecords(projectDir);
+  return records.find((r) => r.entity && r.entity.toLowerCase() === lower) || null;
+}
+
+export function nextId(projectDir, type) {
+  const records = readManifest(projectDir);
+  const prefix = type;
+  let max = 0;
+  for (const r of records) {
+    if (r.type !== type) continue;
+    const m = r.id?.match(new RegExp(`^${prefix}_(\\d+)$`));
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return `${prefix}_${String(max + 1).padStart(3, "0")}`;
+}
+
+// Sync sleep (no busy-spin) for the allocation lock retry.
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Coarse per-project lock so concurrent resolves don't race on id allocation.
+// ponytail: one lock file with a 15s stale-steal (a crashed holder can't wedge
+// the project); fine for agent-scale concurrency — revisit if throughput needs
+// finer locking. Date.now() is available here (a normal Node CLI, not a
+// workflow DSL), so mtime-based staleness is safe.
+const LOCK_STALE_MS = 15000;
+const LOCK_TIMEOUT_MS = 20000;
+
+function withLock(dir, fn) {
+  const lock = join(dir, ".lock");
+  const start = Date.now();
+  for (;;) {
+    try {
+      closeSync(openSync(lock, "wx")); // O_EXCL: atomic acquire
+      break;
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      try {
+        if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {
+          rmSync(lock, { force: true }); // steal a stale lock from a dead holder
+          continue;
+        }
+      } catch {
+        continue; // lock vanished between check and stat — retry the acquire
+      }
+      if (Date.now() - start > LOCK_TIMEOUT_MS) {
+        throw new Error("media-use: timed out acquiring .media/.lock");
+      }
+      sleepMs(25);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    rmSync(lock, { force: true });
+  }
+}
+
+// Atomically allocate the next free id for `type` AND reserve it on disk, so a
+// slow download/copy between allocation and appendRecord can't let a concurrent
+// caller grab the same id (the MU-23 clobber). Under the lock we take the max id
+// across BOTH the manifest and any already-reserved files in the type dir, then
+// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
+// project history skips. Returns { id, localPath, markerPath }.
+export function allocateId(projectDir, type, ext) {
+  mkdirSync(mediaDir(projectDir), { recursive: true });
+  const typeDir = typeDirPath(projectDir, type);
+  mkdirSync(typeDir, { recursive: true });
+  return withLock(mediaDir(projectDir), () => {
+    const id = nextFreeId(projectDir, type);
+    const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
+    // Same shape as core atomicTempPath: an empty file at the final name would be committed.
+    const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString("hex")}.tmp`;
+    writeFileSync(markerPath, "", { flag: "wx" }); // durable reservation
+    return { id, localPath, markerPath };
+  });
+}
+
+// Call under the lock: counts recorded ids and ids reserved by a file not yet recorded.
+function nextFreeId(projectDir, type) {
+  const re = new RegExp(`^${type}_(\\d+)`);
+  let max = 0;
+  for (const r of readManifest(projectDir)) {
+    if (r.type !== type) continue;
+    const m = r.id?.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  const typeDir = typeDirPath(projectDir, type);
+  for (const f of existsSync(typeDir) ? readdirSync(typeDir) : []) {
+    const m = f.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return `${type}_${String(max + 1).padStart(3, "0")}`;
+}
+
+function reservedFile(projectDir, type, ext) {
+  const allocation = allocateId(projectDir, type, ext);
+  return { ...allocation, fullPath: join(projectDir, allocation.localPath) };
+}
+
+function releaseReservation(reservation, committed) {
+  if (!committed) rmSync(reservation.fullPath, { force: true });
+  rmSync(reservation.markerPath, { force: true });
+}
+
+// A reservation is committed only when populate returns a non-null value.
+// Throwing/rejecting or returning null means no usable asset was produced, so
+// the reservation and any partial asset are released. Keeping this transaction
+// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.
+export function withReservedFileSync(projectDir, type, ext, populate) {
+  const reservation = reservedFile(projectDir, type, ext);
+  try {
+    const result = populate(reservation);
+    releaseReservation(reservation, result != null);
+    return result;
+  } catch (error) {
+    releaseReservation(reservation, false);
+    throw error;
+  }
+}
+
+export async function withReservedFile(projectDir, type, ext, populate) {
+  const reservation = reservedFile(projectDir, type, ext);
+  try {
+    const result = await populate(reservation);
+    releaseReservation(reservation, result != null);
+    return result;
+  } catch (error) {
+    releaseReservation(reservation, false);
+    throw error;
+  }
+}

.agents/skills/media-use/scripts/lib/media-fetch.mjs

@@ -0,0 +1,85 @@
+// Media downloads use public HTTP(S) URLs. Validate every redirect target;
+// a provider result must meet the same host policy as a direct ingest URL.
+// Public HTTPS-to-HTTP redirects are allowed, matching direct HTTP support.
+// This is a literal-host policy, not DNS pinning: DNS resolution remains trusted.
+
+import { BlockList, isIP } from "node:net";
+
+const blocked = new BlockList();
+for (const [network, prefix] of [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.0.0.0", 24],
+  ["192.0.2.0", 24],
+  ["192.88.99.0", 24],
+  ["192.168.0.0", 16],
+  ["198.18.0.0", 15],
+  ["198.51.100.0", 24],
+  ["203.0.113.0", 24],
+  ["224.0.0.0", 4],
+  ["240.0.0.0", 4],
+])
+  blocked.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [
+  ["::", 128],
+  ["::1", 128],
+  ["fc00::", 7],
+  ["fe80::", 10],
+  ["fec0::", 10],
+  ["ff00::", 8],
+  ["2001:db8::", 32],
+])
+  blocked.addSubnet(network, prefix, "ipv6");
+
+export function isPublicMediaUrl(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+    const host = url.hostname.replace(/\.$/, "");
+    if (
+      host === "localhost" ||
+      host.endsWith(".localhost") ||
+      host.endsWith(".local") ||
+      host.endsWith(".internal")
+    )
+      return false;
+    const address = host.replace(/^\[|\]$/g, "");
+    const family = isIP(address);
+    return family === 0 || !blocked.check(address, family === 4 ? "ipv4" : "ipv6");
+  } catch {
+    return false;
+  }
+}
+
+export async function fetchMedia(url, { method = "GET", signal, fetchImpl = fetch } = {}) {
+  let current = String(url);
+  for (let hop = 0; hop <= 5; hop++) {
+    if (!isPublicMediaUrl(current))
+      throw new Error("Media download blocked: URL is not public HTTP(S)");
+    const response = await fetchImpl(current, { method, signal, redirect: "manual" });
+    if (!(response.status >= 300 && response.status < 400)) return response;
+    const location = response.headers.get("location");
+    if (!location) return response;
+    await response.body?.cancel();
+    current = new URL(location, current).href;
+  }
+  throw new Error("Media download exceeded redirect limit");
+}
+
+// Stream and abort once the cap is crossed, so a lying or chunked body can't buffer past it.
+export async function readCappedBody(res, maxBytes, label) {
+  const declared = Number(res.headers.get("content-length"));
+  if (declared > maxBytes) throw new Error(`${label}: ${declared} bytes exceeds ${maxBytes} cap`);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    total += chunk.length;
+    if (total > maxBytes) throw new Error(`${label}: stream exceeds ${maxBytes} cap`);
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, total);
+}

.agents/skills/media-use/scripts/lib/media-home.mjs

@@ -0,0 +1,20 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The one owner of where the person's media library lives. This repo's test runs set
+// HYPERFRAMES_MEDIA_HOME_REQUIRED, so a test that forgot HYPERFRAMES_MEDIA_HOME fails instead
+// of writing fixtures into the media library apps list as the person's own files.
+export function mediaHome() {
+  const override = process.env.HYPERFRAMES_MEDIA_HOME;
+  if (override) return override;
+  if (process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED) {
+    throw new Error(
+      "media-use: a test reached the real ~/.media; set HYPERFRAMES_MEDIA_HOME to a temp dir",
+    );
+  }
+  return homedir();
+}
+
+export function globalMediaDir() {
+  return join(mediaHome(), ".media");
+}

.agents/skills/media-use/scripts/lib/npx-sync.mjs

@@ -0,0 +1,57 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+function resolveNpxCliPath(env, pathExists) {
+  const npmExecPath = env.npm_execpath;
+  const nodeExecPath = env.npm_node_execpath || process.execPath;
+  if (npmExecPath) {
+    const fileName = npmExecPath.replace(/\\/g, "/").split("/").pop()?.toLowerCase();
+    const candidate =
+      fileName === "npx-cli.js" ? npmExecPath : join(dirname(npmExecPath), "npx-cli.js");
+    if (pathExists(candidate)) return candidate;
+  }
+  const besideNode = join(dirname(nodeExecPath), "node_modules", "npm", "bin", "npx-cli.js");
+  return pathExists(besideNode) ? besideNode : null;
+}
+
+// Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites
+// that must hard-fail (rather than fall through to another provider) when npx
+// cannot be resolved. On Windows a bare "npx" is npx.cmd, which
+// execFileSync/spawnSync cannot exec (spawnSync npx ENOENT) —
+// resolveSpawnCommand reroutes it through node + npx-cli.js, no shell:true.
+//
+// `platform`/`env`/`pathExists` params (defaulting to the real values) exist
+// so tests can exercise the win32 branch without mocking node:child_process
+// (its ESM exports are non-configurable) — same idiom as spawnP and
+// localTtsGenerate.
+export function resolveNpxInvocation(
+  argv,
+  opts,
+  platform = process.platform,
+  env = process.env,
+  pathExists = existsSync,
+) {
+  const resolved =
+    platform !== "win32"
+      ? { cmd: "npx", args: argv, opts: { stdio: "ignore", ...opts } }
+      : (() => {
+          const nodeExecPath = env.npm_node_execpath || process.execPath;
+          const npxCliPath = resolveNpxCliPath(env, pathExists);
+          return npxCliPath
+            ? {
+                cmd: nodeExecPath,
+                args: [npxCliPath, ...argv.map((arg) => String(arg))],
+                opts: { stdio: "ignore", windowsHide: true, ...opts },
+              }
+            : null;
+        })();
+  if (!resolved) {
+    // npx-on-win32 with no resolvable npx-cli.js — same terminal condition
+    // spawnP warns about, surfaced as a throw for callers with no fallback.
+    throw new Error(
+      "cannot run npx on Windows: npm's npx-cli.js was not found " +
+        "(install npm with Node, or run via npx/npm run so npm_execpath is set)",
+    );
+  }
+  return resolved;
+}

.agents/skills/media-use/scripts/lib/parakeet-words.mjs

@@ -0,0 +1,27 @@
+// Merge Parakeet-MLX token timestamps into word timestamps.
+//
+// parakeet-mlx JSON emits SUB-WORD tokens (" H", "ello", ...) with per-token
+// start/end. Captions + transcript-cut need WORD timestamps, so join tokens
+// into words on the space boundary: a token whose text starts with a space
+// (or the very first token) begins a new word; the rest append. Output matches
+// the { words: [{ text, start, end }] } shape the rest of media-use consumes
+// (see words.mjs / cutlist.mjs).
+
+export function mergeTokensToWords(parakeet) {
+  const sentences = Array.isArray(parakeet?.sentences) ? parakeet.sentences : [];
+  const words = [];
+  for (const s of sentences) {
+    for (const t of s.tokens ?? []) {
+      const raw = typeof t.text === "string" ? t.text : "";
+      const startsWord = raw.startsWith(" ") || words.length === 0;
+      if (startsWord) {
+        words.push({ text: raw.trim(), start: t.start, end: t.end });
+      } else {
+        const w = words[words.length - 1];
+        w.text += raw;
+        w.end = t.end;
+      }
+    }
+  }
+  return { text: (parakeet?.text ?? "").trim(), words: words.filter((w) => w.text.length > 0) };
+}

.agents/skills/media-use/scripts/lib/prefs-store.mjs

@@ -0,0 +1,180 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
+
+/**
+ * Remembered defaults — the lightweight tier of HyperFrames user memory.
+ *
+ * Two files, same shape as the rest of media-use's storage split:
+ * - project `.media/preferences.json` — committed with the repo, so the whole
+ *   team inherits it; written every time a brief answer is confirmed.
+ * - user `~/.media/preferences.json` — personal, cross-repo. A key is promoted
+ *   here only once the same value has been confirmed in two different projects
+ *   (`PROMOTE_AT`), so a one-off choice never pollutes the global defaults.
+ *   Pre-promotion evidence accumulates in the user file's `sightings` ledger —
+ *   project files can't see each other, so the cross-project count has to live
+ *   user-side.
+ *
+ * Consumption contract (brief-contract § 2, Remembered defaults): a remembered
+ * value becomes the recommended option with a receipt naming its source — it
+ * never skips a question, and explicit request content always wins.
+ */
+
+const PREFS_FILE = "preferences.json";
+
+/** Keys the brief contract records; `style_preset` is stored per workflow. */
+export const PREFERENCE_KEYS = [
+  "destination",
+  "aspect",
+  "language",
+  "flow",
+  "storyboard",
+  "voice",
+  "style_preset",
+];
+
+/** A value must be confirmed in this many distinct projects to go user-tier. */
+export const PROMOTE_AT = 2;
+
+export function projectPrefsPath(projectDir) {
+  return join(resolve(projectDir), ".media", PREFS_FILE);
+}
+
+export function userPrefsPath() {
+  return join(globalMediaDir(), PREFS_FILE);
+}
+
+function emptyFile() {
+  return { version: 1, preferences: {}, sightings: {} };
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Tolerant read — a missing or malformed file counts as empty. */
+function readPrefsFile(path) {
+  try {
+    if (!existsSync(path)) return emptyFile();
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!isRecord(parsed)) return emptyFile();
+    return {
+      version: 1,
+      preferences: isRecord(parsed.preferences) ? parsed.preferences : {},
+      sightings: isRecord(parsed.sightings) ? parsed.sightings : {},
+    };
+  } catch {
+    return emptyFile();
+  }
+}
+
+/** Atomic write (tmp + rename) so a crash never leaves a torn file. */
+function writePrefsFile(path, file) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/** `style_preset` entries are stored per workflow as `style_preset.<workflow>`. */
+export function preferenceKeyFor(key, workflow) {
+  return key === "style_preset" && workflow ? `style_preset.${workflow}` : key;
+}
+
+function validEntry(entry) {
+  return isRecord(entry) && typeof entry.value === "string" && entry.value.length > 0;
+}
+
+/**
+ * The merged view the brief reads: user-tier promoted entries first, project
+ * entries on top (project wins). Each entry carries `source` plus the receipt
+ * material (`confirmed_in`, `updated_at`).
+ */
+export function mergedPreferences(projectDir) {
+  const user = readPrefsFile(userPrefsPath());
+  const project = readPrefsFile(projectPrefsPath(projectDir));
+  const merged = {};
+  for (const [key, entry] of Object.entries(user.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "user" };
+  }
+  for (const [key, entry] of Object.entries(project.preferences)) {
+    if (validEntry(entry)) merged[key] = { ...entry, source: "project" };
+  }
+  return merged;
+}
+
+function dedupe(list) {
+  return [...new Set(list)];
+}
+
+/**
+ * Project tier: same value accumulates confirmations; a changed value starts
+ * provenance over (the old confirmations vouched for the old value).
+ */
+function recordProjectTier(projectDir, fullKey, value, projectName, now) {
+  const path = projectPrefsPath(projectDir);
+  const file = readPrefsFile(path);
+  const previous = file.preferences[fullKey];
+  const keepProvenance = validEntry(previous) && previous.value === value;
+  const confirmedIn = keepProvenance
+    ? dedupe([...(Array.isArray(previous.confirmed_in) ? previous.confirmed_in : []), projectName])
+    : [projectName];
+  file.preferences[fullKey] = { value, confirmed_in: confirmedIn, updated_at: now };
+  writePrefsFile(path, file);
+  return confirmedIn;
+}
+
+/**
+ * User tier: accumulate this sighting in the ledger, and promote the key once
+ * the same value has been confirmed in PROMOTE_AT distinct projects.
+ */
+function recordUserSighting(fullKey, value, projectName, now) {
+  const path = userPrefsPath();
+  const file = readPrefsFile(path);
+  const keySightings = isRecord(file.sightings[fullKey]) ? file.sightings[fullKey] : {};
+  const seenIn = dedupe([
+    ...(Array.isArray(keySightings[value]) ? keySightings[value] : []),
+    projectName,
+  ]);
+  keySightings[value] = seenIn;
+  file.sightings[fullKey] = keySightings;
+  const promoted = seenIn.length >= PROMOTE_AT;
+  if (promoted) {
+    file.preferences[fullKey] = { value, confirmed_in: seenIn, updated_at: now };
+  }
+  writePrefsFile(path, file);
+  return promoted;
+}
+
+/**
+ * Record one confirmed brief answer. Always writes the project tier; feeds the
+ * user tier's sightings ledger and promotes once the same value has been
+ * confirmed in PROMOTE_AT distinct projects. Idempotent per project.
+ */
+export function recordPreference({ projectDir, key, value, workflow }) {
+  if (!PREFERENCE_KEYS.includes(key)) {
+    throw new Error(`unknown preference key: "${key}" (known: ${PREFERENCE_KEYS.join(", ")})`);
+  }
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error("a preference needs a non-empty string value");
+  }
+  if (key === "style_preset" && (!workflow || !String(workflow).trim())) {
+    throw new Error("style_preset is stored per workflow — pass --workflow <w>");
+  }
+  const fullKey = preferenceKeyFor(key, workflow);
+  const projectName = basename(resolve(projectDir));
+  const trimmed = value.trim();
+  const now = new Date().toISOString();
+
+  const confirmedIn = recordProjectTier(projectDir, fullKey, trimmed, projectName, now);
+
+  // Best-effort — a read-only home directory must never fail a brief.
+  let promoted = false;
+  try {
+    promoted = recordUserSighting(fullKey, trimmed, projectName, now);
+  } catch {
+    // The project record already landed; promotion just waits for next time.
+  }
+
+  return { key: fullKey, value: trimmed, confirmed_in: confirmedIn, promoted };
+}

.agents/skills/media-use/scripts/lib/recipe-store.mjs

@@ -0,0 +1,367 @@
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { globalMediaDir } from "./media-home.mjs";
+import { appendRecord, mediaDir, nextId } from "./manifest.mjs";
+import { regenerateIndex } from "./index-gen.mjs";
+import { mergedPreferences } from "./prefs-store.mjs";
+
+/**
+ * Recipes — the heavyweight tier of HyperFrames user memory.
+ *
+ * A recipe is the full confirmed bundle for one video type: the frozen design
+ * spec (`frame.md`), the storyboard skeleton (structure with the content
+ * blanked), and the confirmed brief values — frozen after the run's final
+ * approval, reused to start the next video of the same type from everything
+ * already approved.
+ *
+ * Storage is **named folders**, not content-addressed cache entries: a recipe
+ * is an evolving bundle with a `version`, so re-freezing the same name bumps
+ * the version and archives the old folder as `<name>@v<N>`. Two tiers, same
+ * split as everything else in media-use: project `.media/recipes/<name>/`
+ * (committed) and user `~/.media/recipes/<name>/` (a freeze is already a
+ * confirmed bundle, so it promotes immediately — no two-project rule here).
+ */
+
+/** Frontmatter keys that describe THIS video, not the reusable type. */
+const FRONTMATTER_CONTENT_KEYS = new Set(["message", "audience", "mode"]);
+
+/** BRIEF.md frontmatter keys that describe this run, not the reusable type —
+ * a recipe never locks the run's shape, so the intent layer always re-asks. */
+const BRIEF_CONTENT_KEYS = new Set(["flow", "storyboard", "message", "audience"]);
+
+/** Per-frame metadata that is content, not structure. */
+const FRAME_CONTENT_KEYS = new Set([
+  "voiceover",
+  "vo",
+  "voice_over",
+  "narration",
+  "scene",
+  "description",
+  "summary",
+  "caption",
+  "asset_candidates",
+]);
+
+const FRAME_HEADING_RE = /^(#{2,3})\s+(?:frame|beat|scene)\s+\d+/i;
+
+export function projectRecipesDir(projectDir) {
+  return join(mediaDir(projectDir), "recipes");
+}
+
+export function userRecipesDir() {
+  return join(globalMediaDir(), "recipes");
+}
+
+export function slugifyRecipeName(name) {
+  const slug = String(name ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  if (!slug) throw new Error(`recipe name "${name}" has no usable characters`);
+  return slug;
+}
+
+function frameTitle(headingLine) {
+  const dash = headingLine.split(/\s+—\s+/)[1];
+  if (dash && dash.trim()) return dash.trim();
+  return headingLine.replace(/^#+\s*/, "").trim();
+}
+
+/** Frontmatter: drop the content keys, keep structure/style keys verbatim. */
+function skeletonFrontmatter(lines, out, contentKeys = FRONTMATTER_CONTENT_KEYS) {
+  if (lines[0]?.trim() !== "---") return 0;
+  out.push(lines[0]);
+  let i = 1;
+  while (i < lines.length && lines[i].trim() !== "---") {
+    const key = lines[i].match(/^(\w+)\s*:/)?.[1]?.toLowerCase();
+    if (!key || !contentKeys.has(key)) out.push(lines[i]);
+    i++;
+  }
+  if (i < lines.length) {
+    out.push(lines[i]); // closing ---
+    i++;
+  }
+  return i;
+}
+
+/** One line inside a frame section — returns the replacement lines (may be none). */
+function skeletonFrameLine(line, state, out) {
+  const bulletKey = line.match(/^-\s+(\w+)\s*:/)?.[1]?.toLowerCase();
+  if (bulletKey) {
+    if (bulletKey === "status") out.push("- status: outline");
+    else if (!FRAME_CONTENT_KEYS.has(bulletKey)) out.push(line);
+    return;
+  }
+  if (!line.trim()) {
+    out.push(line);
+    return;
+  }
+  // Frame prose: one placeholder per frame in place of the narrative.
+  if (!state.proseReplaced) {
+    out.push(
+      `<fill in: this video's content for the "${state.title}" beat — keep the layout role, replace the words.>`,
+    );
+    state.proseReplaced = true;
+  }
+}
+
+/**
+ * Skeletonize a STORYBOARD.md: keep the reusable structure (frame count,
+ * durations, transitions, src paths, the Video direction block, style-ish
+ * frontmatter), reset every status to `outline`, and blank the content
+ * (message/audience, narration guides, per-frame prose) down to a fill-in
+ * placeholder that names the frame's role.
+ */
+/**
+ * Skeletonize a BRIEF.md: keep the frontmatter's reusable keys (workflow,
+ * destination, aspect, language, length, angle…), drop the run-shape and
+ * content keys (flow, storyboard, message, audience), and blank each body
+ * section down to a fill-in placeholder under its kept heading.
+ */
+export function skeletonizeBrief(source) {
+  const lines = String(source ?? "").split(/\r?\n/);
+  const out = [];
+  let i = skeletonFrontmatter(lines, out, BRIEF_CONTENT_KEYS);
+  for (; i < lines.length; i++) {
+    const heading = lines[i].match(/^##\s+(.+)$/);
+    if (heading) {
+      out.push(lines[i], "");
+      out.push(
+        `<fill in: this video's ${heading[1].trim().toLowerCase()} — the recipe keeps the shape, this run supplies the specifics.>`,
+      );
+      out.push("");
+    }
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+export function skeletonizeStoryboard(source) {
+  const lines = String(source ?? "").split(/\r?\n/);
+  const out = [];
+  const state = { inFrame: false, proseReplaced: false, title: "" };
+  for (let i = skeletonFrontmatter(lines, out); i < lines.length; i++) {
+    const line = lines[i];
+    if (/^#{2,3}\s/.test(line)) {
+      state.inFrame = FRAME_HEADING_RE.test(line);
+      state.proseReplaced = false;
+      state.title = state.inFrame ? frameTitle(line) : "";
+      out.push(line);
+    } else if (!state.inFrame) {
+      out.push(line);
+    } else {
+      skeletonFrameLine(line, state, out);
+    }
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+
+/** The run's workflow as BRIEF.md records it — the source of truth a freeze
+ * must not contradict. Undefined when no BRIEF.md (or no `workflow:`) exists. */
+function briefWorkflow(root) {
+  const brief = join(root, "BRIEF.md");
+  if (!existsSync(brief)) return undefined;
+  const lines = readFileSync(brief, "utf8").split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return undefined;
+  for (let i = 1; i < lines.length && lines[i].trim() !== "---"; i++) {
+    const match = lines[i].match(/^workflow\s*:\s*(.+?)\s*$/);
+    if (match) return match[1].replace(/^["']|["']$/g, "") || undefined;
+  }
+  return undefined;
+}
+
+function readRecipeJson(dir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, "recipe.json"), "utf8"));
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.name !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function prefValue(prefs, key) {
+  return prefs[key]?.value;
+}
+
+/**
+ * Freeze the current project's approved run as a named recipe. Writes the
+ * project-tier folder + a manifest record, then copies to the user tier (a
+ * freeze is already confirmed — it promotes immediately).
+ */
+export function freezeRecipe({ projectDir, name, workflow, blocks }) {
+  const slug = slugifyRecipeName(name);
+  const root = resolve(projectDir);
+  const fromBrief = briefWorkflow(root);
+  const fromFlag = workflow && String(workflow).trim() ? String(workflow).trim() : undefined;
+  // BRIEF.md decides; the flag only covers projects briefed before it existed.
+  const resolvedWorkflow = fromBrief ?? fromFlag;
+  if (!resolvedWorkflow) {
+    throw new Error("no workflow found — BRIEF.md names none and no --workflow was given");
+  }
+  const frameSpec = join(root, "frame.md");
+  const storyboard = join(root, "STORYBOARD.md");
+  if (!existsSync(frameSpec)) throw new Error("no frame.md to freeze — run the design step first");
+  if (!existsSync(storyboard)) throw new Error("no STORYBOARD.md to freeze");
+
+  const dir = join(projectRecipesDir(root), slug);
+  let version = 1;
+  const previous = existsSync(dir) ? readRecipeJson(dir) : null;
+  if (previous) {
+    version = (Number.isInteger(previous.version) ? previous.version : 1) + 1;
+    const archive = `${dir}@v${previous.version ?? 1}`;
+    rmSync(archive, { recursive: true, force: true });
+    renameSync(dir, archive);
+  }
+  mkdirSync(dir, { recursive: true });
+
+  const prefs = mergedPreferences(root);
+  const recipe = {
+    version,
+    name: slug,
+    workflow: resolvedWorkflow,
+    approved_at: new Date().toISOString(),
+    source_project: basename(root),
+    destination: prefValue(prefs, "destination"),
+    aspect: prefValue(prefs, "aspect"),
+    language: prefValue(prefs, "language"),
+    voice: prefValue(prefs, "voice"),
+    // The bare-key fallback tolerates records made before the store required
+    // style_preset to be workflow-scoped.
+    style_preset:
+      prefValue(prefs, `style_preset.${resolvedWorkflow}`) ?? prefValue(prefs, "style_preset"),
+    blocks: Array.isArray(blocks) && blocks.length > 0 ? blocks : undefined,
+  };
+
+  writeFileSync(join(dir, "recipe.json"), `${JSON.stringify(recipe, null, 2)}\n`);
+  cpSync(frameSpec, join(dir, "frame.md"));
+  writeFileSync(
+    join(dir, "storyboard-skeleton.md"),
+    `${skeletonizeStoryboard(readFileSync(storyboard, "utf8")).trimEnd()}\n`,
+  );
+
+  // Best-effort fourth artifact — projects briefed before BRIEF.md existed
+  // (or by workflows that don't write one) freeze fine without it.
+  const brief = join(root, "BRIEF.md");
+  const briefSkeleton = existsSync(brief);
+  if (briefSkeleton) {
+    writeFileSync(
+      join(dir, "brief-skeleton.md"),
+      `${skeletonizeBrief(readFileSync(brief, "utf8")).trimEnd()}\n`,
+    );
+  }
+
+  const id = nextId(root, "recipe");
+  appendRecord(root, {
+    id,
+    type: "recipe",
+    path: `.media/recipes/${slug}/recipe.json`,
+    entity: slug,
+    description: `recipe: ${slug} (${recipe.workflow}, v${version})`,
+    provenance: { provider: "recipe.freeze", version, source_project: recipe.source_project },
+  });
+  regenerateIndex(root);
+
+  // User tier — best-effort, like every other promotion.
+  try {
+    const userDir = join(userRecipesDir(), slug);
+    mkdirSync(userDir, { recursive: true });
+    cpSync(dir, userDir, { recursive: true, force: true });
+  } catch {
+    // The project-tier freeze already landed.
+  }
+
+  return {
+    id,
+    slug,
+    version,
+    dir,
+    briefSkeleton,
+    workflow: resolvedWorkflow,
+    workflowOverridden: Boolean(fromBrief && fromFlag && fromBrief !== fromFlag),
+  };
+}
+
+function scanRecipesDir(dir, source) {
+  if (!existsSync(dir)) return [];
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.includes("@v")) continue;
+    const recipe = readRecipeJson(join(dir, entry.name));
+    if (recipe) found.push({ ...recipe, source, dir: join(dir, entry.name) });
+  }
+  return found;
+}
+
+/** Two-tier merged listing (project wins), newest approval first. */
+export function listRecipes({ projectDir, workflow }) {
+  const merged = new Map();
+  for (const recipe of scanRecipesDir(userRecipesDir(), "user")) merged.set(recipe.name, recipe);
+  for (const recipe of scanRecipesDir(projectRecipesDir(resolve(projectDir)), "project")) {
+    merged.set(recipe.name, recipe);
+  }
+  let list = [...merged.values()];
+  if (workflow) list = list.filter((r) => r.workflow === workflow);
+  return list.sort((a, b) =>
+    String(b.approved_at ?? "").localeCompare(String(a.approved_at ?? "")),
+  );
+}
+
+/**
+ * Adopt a recipe into the current project: import the folder from the user
+ * tier when the project doesn't have it, copy its frame.md over the project's,
+ * and hand back the values + the skeleton path for the storyboard draft.
+ */
+export function useRecipe({ projectDir, name }) {
+  const slug = slugifyRecipeName(name);
+  const root = resolve(projectDir);
+  let dir = join(projectRecipesDir(root), slug);
+
+  if (!readRecipeJson(dir)) {
+    const userDir = join(userRecipesDir(), slug);
+    if (!readRecipeJson(userDir)) {
+      const known = listRecipes({ projectDir: root }).map((r) => r.name);
+      throw new Error(
+        `no recipe named "${slug}"${known.length ? ` (known: ${known.join(", ")})` : ""}`,
+      );
+    }
+    mkdirSync(dir, { recursive: true });
+    cpSync(userDir, dir, { recursive: true, force: true });
+    const imported = readRecipeJson(dir);
+    appendRecord(root, {
+      id: nextId(root, "recipe"),
+      type: "recipe",
+      path: `.media/recipes/${slug}/recipe.json`,
+      entity: slug,
+      description: `recipe: ${slug} (${imported.workflow}, v${imported.version})`,
+      provenance: { provider: "recipe.local", imported_from: "user-tier" },
+    });
+    regenerateIndex(root);
+  }
+
+  const recipe = readRecipeJson(dir);
+  cpSync(join(dir, "frame.md"), join(root, "frame.md"));
+  return {
+    recipe,
+    dir,
+    frameSpecPath: "frame.md",
+    skeletonPath: `.media/recipes/${slug}/storyboard-skeleton.md`,
+    // Recipes frozen before BRIEF.md existed have no brief skeleton — degrade.
+    briefSkeletonPath: existsSync(join(dir, "brief-skeleton.md"))
+      ? `.media/recipes/${slug}/brief-skeleton.md`
+      : undefined,
+  };
+}

.agents/skills/media-use/scripts/lib/telemetry.mjs

@@ -0,0 +1,213 @@
+// Usage tracking shares the CLI and Studio identity. Properties stay coarse and
+// never carry intent text, file names, or paths.
+
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { withFileLock } from "./config-lock.mjs";
+import { globalMediaDir } from "./media-home.mjs";
+
+const POSTHOG_API_KEY = "phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+const TIMEOUT_MS = 1500;
+let identifiedAccount = false;
+let warnedNonDefaultHost = false;
+
+function isTestOrCiContext() {
+  return (
+    process.env.CI === "true" ||
+    process.env.CI === "1" ||
+    process.env.NODE_ENV === "test" ||
+    process.env.NODE_ENV === "development"
+  );
+}
+
+function posthogHost() {
+  const override = process.env.MEDIA_USE_TELEMETRY_HOST;
+  if (override && !warnedNonDefaultHost && !isTestOrCiContext()) {
+    warnedNonDefaultHost = true;
+    console.error(
+      `media-use: telemetry is redirected to a non-default host via MEDIA_USE_TELEMETRY_HOST (${override}) — unset it unless this is intentional.`,
+    );
+  }
+  return override || POSTHOG_HOST;
+}
+
+/** True when telemetry must NOT be sent (opt-out envs, CI, dev, shared config). */
+export function optedOut() {
+  return (
+    // `hyperframes telemetry disable` writes telemetryEnabled: false to the
+    // shared config; one opt-out must cover the CLI and the media-use scripts.
+    readSharedConfig().telemetryEnabled === false ||
+    process.env.HYPERFRAMES_NO_TELEMETRY === "1" ||
+    process.env.DO_NOT_TRACK === "1" ||
+    process.env.CI === "true" ||
+    process.env.CI === "1" ||
+    process.env.NODE_ENV === "development"
+  );
+}
+
+// Read and write the shared config so media-use keeps one identity per install.
+function sharedConfigPath() {
+  return join(homedir(), ".hyperframes", "config.json");
+}
+
+function readSharedConfig() {
+  try {
+    const file = sharedConfigPath();
+    if (existsSync(file)) {
+      const parsed = JSON.parse(readFileSync(file, "utf8"));
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+    }
+  } catch {
+    // unreadable config → treat as empty; never throw
+  }
+  return {};
+}
+
+// Best effort: skipped when the lock cannot be taken or the file cannot be read, never written unlocked.
+function updateSharedConfig(patch) {
+  const file = sharedConfigPath();
+  mkdirSync(dirname(file), { recursive: true });
+  try {
+    withFileLock(`${file}.lock`, fs, () => {
+      let config = {};
+      try {
+        config = JSON.parse(readFileSync(file, "utf8"));
+      } catch (error) {
+        if (error.code !== "ENOENT") return;
+      }
+      if (!config || typeof config !== "object" || Array.isArray(config)) return;
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify({ ...config, ...patch }, null, 2) + "\n", { mode: 0o600 });
+      renameSync(tmp, file);
+    });
+  } catch {}
+}
+
+// Adopt a pre-existing media-use-only id (~/.media/anon-id from before this
+// change) so upgraders keep their PostHog persona instead of resetting to a new
+// one — otherwise cross-surface continuity would start over on upgrade.
+function legacyMediaAnonId() {
+  try {
+    const file = join(globalMediaDir(), "anon-id");
+    if (existsSync(file)) {
+      const id = readFileSync(file, "utf8").trim();
+      if (id) return id;
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+// Stable per-machine id from the shared config; seeds it (adopting a legacy
+// media-use id when present) if absent.
+function anonymousId() {
+  try {
+    const config = readSharedConfig();
+    if (typeof config.anonymousId === "string" && config.anonymousId.trim()) {
+      return config.anonymousId.trim();
+    }
+    const id = legacyMediaAnonId() || randomUUID();
+    updateSharedConfig({ anonymousId: id });
+    return id;
+  } catch {
+    return "anon"; // best-effort; a shared bucket is fine if the fs is read-only
+  }
+}
+
+function heygenAccountDistinctId() {
+  const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
+  try {
+    if (!existsSync(file)) return null;
+    const raw = readFileSync(file, "utf8").trim();
+    if (!raw.startsWith("{")) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const user = parsed.user;
+    if (!user || typeof user !== "object" || Array.isArray(user)) return null;
+    const id = typeof user.email === "string" && user.email.trim() ? user.email : user.username;
+    // Lowercased so this joins with the CLI's own identify call regardless of
+    // the account's stored email casing — two different-case distinct ids
+    // would otherwise split one person across two PostHog profiles.
+    return typeof id === "string" && id.trim() ? id.trim().toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
+function showTelemetryNotice() {
+  if (optedOut()) return;
+  try {
+    const config = readSharedConfig();
+    // Shared with the CLI (config.telemetryNoticeShown): shown once per person
+    // across surfaces, not once per tool.
+    if (config.telemetryNoticeShown === true) return;
+    console.error(
+      [
+        "media-use sends usage telemetry: media type, resolution source, and provider; never intent text, file names, or paths.",
+        "If you sign in to HeyGen, usage links to your account email or username. Opt out with HYPERFRAMES_NO_TELEMETRY=1 or DO_NOT_TRACK=1.",
+      ].join("\n"),
+    );
+    updateSharedConfig({ telemetryNoticeShown: true });
+  } catch {
+    // notice is best-effort; never surface into the command
+  }
+}
+
+async function postBatch(batch) {
+  try {
+    await fetch(`${posthogHost()}/batch/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Connection: "close" },
+      body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+  } catch {
+    // telemetry is best-effort; never surface into the command
+  }
+}
+
+async function postEvent(event, properties, distinctId) {
+  await postBatch([
+    {
+      event,
+      properties: { ...properties, surface: "media-use", $ip: null },
+      distinct_id: distinctId,
+      timestamp: new Date().toISOString(),
+    },
+  ]);
+}
+
+async function identifyAccount(anonId) {
+  if (optedOut() || identifiedAccount) return;
+  const distinctId = heygenAccountDistinctId();
+  if (!distinctId) return;
+  identifiedAccount = true;
+  await postEvent("$identify", { $anon_distinct_id: anonId }, distinctId);
+}
+
+/**
+ * Fire-and-forget a single event to PostHog. Best-effort: awaited with a short
+ * timeout so a short-lived script flushes before exit, but any failure (offline,
+ * opted out) is swallowed. `properties` must be non-PII (no intent/paths).
+ */
+export async function track(event, properties = {}) {
+  if (optedOut()) return;
+  showTelemetryNotice();
+  const anonId = anonymousId();
+  await identifyAccount(anonId);
+  await postEvent(event, properties, anonId);
+}
+
+export function __anonymousIdForTest() {
+  return anonymousId();
+}
+
+export function __resetTelemetryForTest() {
+  identifiedAccount = false;
+  warnedNonDefaultHost = false;
+}

.agents/skills/media-use/scripts/lib/telemetry.test.mjs

@@ -0,0 +1,73 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { test } from "node:test";
+import { optedOut } from "./telemetry.mjs";
+
+// optedOut() reads ~/.hyperframes/config.json and env vars. Point HOME at a temp
+// dir so the run never touches the real config, and pin the env opt-outs to a
+// neutral state; restore both afterwards.
+const ENV_KEYS = [
+  "HOME",
+  "USERPROFILE",
+  "HYPERFRAMES_NO_TELEMETRY",
+  "DO_NOT_TRACK",
+  "CI",
+  "NODE_ENV",
+];
+const savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+const home = mkdtempSync(join(tmpdir(), "mu-telemetry-"));
+const configPath = join(home, ".hyperframes", "config.json");
+
+function writeConfig(contents) {
+  if (contents === null) {
+    rmSync(configPath, { force: true });
+  } else {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, contents);
+  }
+}
+
+test.before(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+  process.env.HOME = process.env.USERPROFILE = home;
+});
+
+test.after(() => {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+  rmSync(home, { recursive: true, force: true });
+});
+
+test("optedOut is false with no config and no opt-out env", () => {
+  writeConfig(null);
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut honors telemetryEnabled: false from the shared config", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: false }));
+  assert.equal(optedOut(), true);
+});
+
+test("optedOut is false when the shared config enables telemetry", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: true }));
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut treats an unreadable shared config as no opt-out", () => {
+  writeConfig("{not json");
+  assert.equal(optedOut(), false);
+});
+
+test("optedOut still honors the env opt-outs", () => {
+  writeConfig(JSON.stringify({ telemetryEnabled: true }));
+  process.env.DO_NOT_TRACK = "1";
+  try {
+    assert.equal(optedOut(), true);
+  } finally {
+    delete process.env.DO_NOT_TRACK;
+  }
+});

.agents/skills/media-use/scripts/lib/transcriptCutFade.mjs

@@ -0,0 +1,21 @@
+function round3(n) {
+  return Math.round(Number(n) * 1000) / 1000;
+}
+
+// 30ms in/out ramps kill the click at every concat boundary. A segment shorter
+// than 4x the ramp would spend its whole length fading, so scale down there and
+// skip entirely on a degenerate one. fadeIn/fadeOut are false at the export's
+// own true start/end, where there is no splice to smooth.
+export function fadeFilterFor(durationSeconds, { fadeIn, fadeOut }) {
+  if (!fadeIn && !fadeOut) return null;
+  const FADE_SECONDS = 0.03;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0.01) return null;
+  const d = Math.min(FADE_SECONDS, durationSeconds / 4);
+  const parts = [];
+  if (fadeIn) parts.push(`afade=t=in:st=0:d=${round3(d)}`);
+  if (fadeOut) {
+    const out = round3(durationSeconds - d);
+    if (out > 0) parts.push(`afade=t=out:st=${out}:d=${round3(d)}`);
+  }
+  return parts.length ? parts.join(",") : null;
+}

.agents/skills/media-use/scripts/lib/words.mjs

@@ -0,0 +1,18 @@
+export function normalizeWords(input) {
+  const raw = Array.isArray(input) ? input : Array.isArray(input?.words) ? input.words : [];
+  return raw
+    .map((w, index) => {
+      const text = String(w?.text ?? w?.word ?? "").trim();
+      const start = Number(w?.start);
+      const end = Number(w?.end);
+      if (!text || !Number.isFinite(start) || !Number.isFinite(end)) return null;
+      return { id: w?.id ?? `w${index}`, text, start, end };
+    })
+    .filter(Boolean);
+}
+
+export function wordListsFromMediaMeta(input) {
+  if (Array.isArray(input) || Array.isArray(input?.words)) return [normalizeWords(input)];
+  if (!Array.isArray(input?.voices)) return [];
+  return input.voices.map((voice) => normalizeWords(voice));
+}