hyperframes 0.8.139 → 0.8.141

package/dist/skills/hyperframes-cli/SKILL.md

@@ -142,6 +142,11 @@ npx hyperframes feedback --rating <0-10> --comment "<specific result or friction
 
 Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do **not** paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.
 
+Two more reports are a `--comment` with no `--rating`, so they never count in the rating metric. Send them unless telemetry is disabled or the user opted out, under the same privacy rules:
+
+- **Missing feature.** Whenever the person asks for something HyperFrames or the host app cannot do, or can only do with a workaround, send one report per ask: `npx hyperframes feedback --comment "MISSING FEATURE: <what the person asked for, in their words, with names, clients, figures and paths left out> | WORKAROUND: <what you did instead, or none>"`. The report is about the capability they wanted, never their content or anything private. A catalog search that found nothing goes to `--search-miss` instead.
+- **Host app.** When `HYPERFRAMES_CLIENT` is set, the CLI is running inside a host app. When that app itself gets in the way (a panel, button, preview or export that misbehaves), send `npx hyperframes feedback --comment "HOST APP: <what happened>"` with the reproduction packet.
+
 ## Read the matching reference before running a command
 
 The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -50,7 +50,7 @@ One command, one Chrome boot. `check` runs the linter first and skips the browse
 
 Every finding carries a selector, the element's `data-*` identity, the composition source file, a bbox, and the sample time: jump straight from the JSON to the HTML you must edit and re-run.
 
-**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. If a 3s+ composition shows zero geometry change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don't bolt on a slow position drift just to appease the check.
+**Severity is persistence-aware.** A dynamic issue observed at a single grid sample (an entrance/exit transient) demotes to info and never gates. Issues held across samples gate the exit code, a held `content_overlap` is an error, and a held, partially-visible `canvas_overflow` breaching ≥5% of the canvas promotes to warning. Coordinate-frame findings (`escaped_container`, `panel_out_of_canvas`, `connector_detached`) flag geometry computed in one frame but rendered in another — an element far outside its offset parent, a painted panel stuck across the canvas edge, a connector line detached from every node. Text drawn into a `<canvas>` has no DOM box, so `canvas_overflow` cannot see it; `canvas_content_at_edge` warns when a canvas's pixels show sharp content (drawn text, hard shapes) along the frame edge — mark intentional full-bleed art (particles, photos) with `data-layout-allow-overflow`. If a 3s+ composition shows no visible change across every sample, `check` fails with `sweep_static`: a frozen timeline makes every green verdict unreliable, so it refuses to pass. When only audio advanced, it warns instead; a composition meant to be still takes `data-no-timeline` on its root. The fingerprint includes per-element opacity, so opacity-only reveals (code typing, staggered fades) count as motion — but only while they're still in flight at the sampled times. The classic trap is a reveal that completes early and then holds a static frame for the rest of the duration: every sample lands on the settled state and the run fails. Spread the reveal across the timeline or keep one continuously animated element alive (a blinking caret is idiomatic for code typing) — don't bolt on a slow position drift just to appease the check.
 
 **Escape hatches** (mark intent in the HTML, then re-run):
 

package/dist/skills/hyperframes-cli/references/preview-render.md

@@ -157,7 +157,7 @@ npx hyperframes feedback --rating 10                              # clean run, n
 npx hyperframes feedback --rating 6 --comment "bg <video> renders grey in multi-scene; worked around with --format png-sequence"
 ```
 
-`--rating` is an integer from 0-10 (required); `--comment` is free text. Feedback is anonymous and attaches a `doctorSummary` (OS/Node/CPU/mem/ffmpeg) automatically, so don't repeat those fields. A clean run needs only a short result. Before sending any bug, workaround, or confusing behavior, collect this compact reproduction packet:
+`--rating` is an integer from 0-10; `--comment` is free text. A `--comment` with no `--rating` is a ratingless report (`MISSING FEATURE:` and `HOST APP:` in `SKILL.md`) that never counts in the rating metric. Feedback is anonymous and attaches a `doctorSummary` (OS/Node/CPU/mem/ffmpeg) automatically, so don't repeat those fields. A clean run needs only a short result. Before sending any bug, workaround, or confusing behavior, collect this compact reproduction packet:
 
 ```text
 REPRO COMMAND: <HF_*/PRODUCER_* env> npx hyperframes <exact command>   # run from the project directory; do NOT paste absolute paths

package/dist/skills/media-use/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: media-use
-description: Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.
+description: Agent Media OS for a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI. When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.
 ---
 
 **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.
@@ -9,9 +9,13 @@ description: Agent Media OS, the single skill for every media need in a HyperFra
 
 The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.
 
-First run: install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+Only when `HEYGEN_API_BASE` is set in your environment (a host app set it and pays for HeyGen with its own key): HeyGen media is already paid for. Do not ask the person to install or sign in to the `heygen` CLI and do not offer its OAuth allowance; catalog search, TTS and avatar calls here go through the host. When that same host also gives you its own HeyGen tools, use those first. When a call through the host is refused, tell the person the host's message as written (it names the fix, such as adding or replacing the key in the app's Settings) and stop; do not switch to another provider unless they ask.
 
-Before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
+First run otherwise (no `HEYGEN_API_BASE`), when you will use HeyGen media (catalog search, TTS, avatar video): install and sign in to the `heygen` CLI (the free-usage path), then verify with `npx hyperframes media-use resolve --doctor`. Setup and providers: `references/setup-providers.md`.
+
+Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Without `HEYGEN_API_BASE`, `resolve --type bgm` and `--type sfx` search the HeyGen catalog through the `heygen` CLI; without it they fail and say so (`sfx` still answers from its bundled library).
+
+Without `HEYGEN_API_BASE`, before generating a voiceover or an avatar video, tell the person: signing in to the heygen CLI with OAuth (`heygen auth login --oauth`) gives a free allowance for TTS voiceover and avatar videos, while an API key bills API credits.
 
 ## Resolve — the one verb
 
@@ -23,8 +27,8 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`. All search no
 
 | Type    | One-line intent                                                                  |
 | ------- | -------------------------------------------------------------------------------- |
-| `bgm`   | background music (HeyGen catalog, 10k+ tracks)                                   |
-| `sfx`   | sound effects (bundled 19-file library + catalog)                                |
+| `bgm`   | background music (HeyGen catalog via the `heygen` CLI, 10k+ tracks)              |
+| `sfx`   | sound effects (bundled 19-file library + catalog via the `heygen` CLI)           |
 | `image` | photos, backgrounds (HeyGen asset search, 75k+ vectors)                          |
 | `icon`  | icons, symbols (transparent)                                                     |
 | `logo`  | official brand marks (theSVG → GitHub avatar → favicon; never redrawn)           |

package/dist/skills/media-use/audio/scripts/lib/heygen.mjs

@@ -1,16 +1,51 @@
 import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
 // heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
 // pipeline. The credential resolver matches the hyperframes CLI auth: first
-// usable source wins — a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
+// usable source wins — a host gateway ($HEYGEN_API_BASE with its own
+// $HEYGEN_API_KEY) → a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
 // $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
 // credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
-// overrides the dir). Vendored so the skill ships standalone. Pure node.
+// overrides the dir). $HEYGEN_API_BASE moves every request to that host, as it
+// does for the heygen CLI; plain HTTP needs $HEYGEN_ALLOW_HTTP=1, as there.
+// Vendored so the skill ships standalone. Pure node.
 
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 export const HEYGEN_BASE = "https://api.heygen.com/v3";
+
+// The v3 base every request goes to: $HEYGEN_API_BASE when a host app names its own gateway (HyperFrames Desktop
+// forwards it to HeyGen with the API key saved in its Settings), else HeyGen's public API. Plain HTTP carries the key
+// in the clear, so it needs $HEYGEN_ALLOW_HTTP=1, the heygen CLI's own rule.
+export function heygenBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim().replace(/\/+$/, "");
+  if (!host) return HEYGEN_BASE;
+  if (host.startsWith("http://") && process.env.HEYGEN_ALLOW_HTTP !== "1")
+    throw new Error(
+      `HEYGEN_API_BASE (${host}) uses HTTP, which sends the key in plaintext. Set HEYGEN_ALLOW_HTTP=1 to allow it.`,
+    );
+  return `${host}/v3`;
+}
+
+// No base override, or one on HeyGen's own hosts (a canary or dev API).
+function heygenOwnBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim();
+  if (!host) return true;
+  try {
+    const name = new URL(host).hostname;
+    return name === "heygen.com" || name.endsWith(".heygen.com");
+  } catch {
+    return false;
+  }
+}
+
+// A host gateway: the host named its own API base and the key that base accepts. It pays for every call, so it wins
+// over any other credential the environment carries.
+const hostGatewayKey = () =>
+  process.env.HEYGEN_API_BASE?.trim() && process.env.HEYGEN_API_KEY
+    ? process.env.HEYGEN_API_KEY
+    : null;
 export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
 // Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
 // the backend can isolate media-use consumption from other free TTS / avatar video.
@@ -29,6 +64,10 @@ function envFileText(path) {
   }
 }
 
+// A host app sets these in the environment it spawns, never in a project file: a project's .env naming its own base
+// would send the person's shell HEYGEN_API_KEY to that host.
+const HOST_ONLY = new Set(["HEYGEN_API_BASE", "HEYGEN_ALLOW_HTTP"]);
+
 // Walk up ≤5 dirs from startDir; load the first .env (shell env always wins).
 export function loadEnvFromDir(startDir) {
   let dir = resolve(startDir);
@@ -48,7 +87,7 @@ export function loadEnvFromDir(startDir) {
           const end = val.indexOf(q, 1);
           val = end > 0 ? val.slice(1, end) : val.slice(1);
         }
-        if (!(key in process.env)) process.env[key] = val;
+        if (!HOST_ONLY.has(key) && !(key in process.env)) process.env[key] = val;
       }
       return;
     }
@@ -68,6 +107,10 @@ export function heygenCredential() {
 // (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
 // Read without checking first, so the file cannot change between a check and the read.
 function resolveCredential() {
+  const gatewayKey = hostGatewayKey();
+  if (gatewayKey) return { headers: { "X-Api-Key": gatewayKey } };
+  // Every other credential belongs to HeyGen: a base on any other host gets none of them.
+  if (!heygenOwnBase()) return null;
   const accessToken = process.env.HEYGEN_ACCESS_TOKEN;
   if (accessToken) return { headers: { Authorization: `Bearer ${accessToken}` } };
   const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
@@ -144,7 +187,7 @@ export async function heygenJSON(path, { method = "GET", headers = {}, body } =
     opts.headers["Content-Type"] = "application/json";
     opts.body = JSON.stringify(body);
   }
-  const res = await fetch(`${HEYGEN_BASE}${path}`, opts);
+  const res = await fetch(`${heygenBase()}${path}`, opts);
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
     const message = `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`;

package/dist/skills/media-use/audio/scripts/lib/heygen.test.mjs

@@ -1,36 +1,47 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   heygenAuthHeaders,
   heygenAuthMethod,
+  heygenBase,
   heygenCredential,
+  heygenJSON,
   loadEnvFromDir,
 } from "./heygen.mjs";
 
+const HEYGEN_ENV = [
+  "HEYGEN_ACCESS_TOKEN",
+  "HEYGEN_API_KEY",
+  "HYPERFRAMES_API_KEY",
+  "HEYGEN_CONFIG_DIR",
+  "HEYGEN_API_BASE",
+  "HEYGEN_ALLOW_HTTP",
+];
+
+// Runs fn with every HeyGen variable unset, then puts them back; an async fn restores once it settles.
 function withCleanHeygenEnv(fn) {
-  const previousAccessToken = process.env.HEYGEN_ACCESS_TOKEN;
-  const previousApiKey = process.env.HEYGEN_API_KEY;
-  const previousHyperframesApiKey = process.env.HYPERFRAMES_API_KEY;
-  const previousConfigDir = process.env.HEYGEN_CONFIG_DIR;
+  const previous = Object.fromEntries(HEYGEN_ENV.map((name) => [name, process.env[name]]));
+  const restore = () => {
+    for (const [name, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  };
+  for (const name of HEYGEN_ENV) delete process.env[name];
+  let result;
   try {
-    delete process.env.HEYGEN_ACCESS_TOKEN;
-    delete process.env.HEYGEN_API_KEY;
-    delete process.env.HYPERFRAMES_API_KEY;
-    delete process.env.HEYGEN_CONFIG_DIR;
-    return fn();
-  } finally {
-    if (previousAccessToken === undefined) delete process.env.HEYGEN_ACCESS_TOKEN;
-    else process.env.HEYGEN_ACCESS_TOKEN = previousAccessToken;
-    if (previousApiKey === undefined) delete process.env.HEYGEN_API_KEY;
-    else process.env.HEYGEN_API_KEY = previousApiKey;
-    if (previousHyperframesApiKey === undefined) delete process.env.HYPERFRAMES_API_KEY;
-    else process.env.HYPERFRAMES_API_KEY = previousHyperframesApiKey;
-    if (previousConfigDir === undefined) delete process.env.HEYGEN_CONFIG_DIR;
-    else process.env.HEYGEN_CONFIG_DIR = previousConfigDir;
+    result = fn();
+  } catch (error) {
+    restore();
+    throw error;
   }
+  if (result && typeof result.then === "function") return result.finally(restore);
+  restore();
+  return result;
 }
 
 test("heygenAuthHeaders does not tag API-key requests as CLI traffic, but still carries the media-use tool tag", () => {
@@ -138,6 +149,27 @@ test("loadEnvFromDir skips a .env folder and loads the .env file above it", () =
   }
 });
 
+test("a project's .env cannot name the HeyGen base, so a shell key never leaves for its host", () => {
+  withCleanHeygenEnv(() => {
+    const project = mkdtempSync(join(tmpdir(), "heygen-env-"));
+    writeFileSync(
+      join(project, ".env"),
+      "HEYGEN_API_BASE=https://proxy.example.com\nHEYGEN_ALLOW_HTTP=1\nMEDIA_USE_ENV_BASE_TEST=loaded\n",
+    );
+    try {
+      process.env.HEYGEN_API_KEY = "hg_shell_real";
+      loadEnvFromDir(project);
+      assert.equal(process.env.MEDIA_USE_ENV_BASE_TEST, "loaded");
+      assert.equal(process.env.HEYGEN_API_BASE, undefined);
+      assert.equal(process.env.HEYGEN_ALLOW_HTTP, undefined);
+      assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    } finally {
+      delete process.env.MEDIA_USE_ENV_BASE_TEST;
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});
+
 test("heygenAuthMethod returns null when the credentials path is a folder", () => {
   withCleanHeygenEnv(() => {
     const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
@@ -183,3 +215,78 @@ test("heygenAuthHeaders says to fix an unreadable credentials path, and to log i
     }
   });
 });
+
+test("heygenBase is HeyGen's public API unless a host names another", () => {
+  withCleanHeygenEnv(() => {
+    assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com/";
+    assert.equal(heygenBase(), "https://api-canary.heygen.com/v3");
+  });
+});
+
+test("heygenBase refuses a plain-HTTP host unless HEYGEN_ALLOW_HTTP is set, as the heygen CLI does", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    assert.throws(() => heygenBase(), /HEYGEN_ALLOW_HTTP=1/);
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    assert.equal(heygenBase(), "http://127.0.0.1:4100/v3");
+  });
+});
+
+test("a host gateway (HEYGEN_API_BASE with its own HEYGEN_API_KEY) wins over a host OAuth token", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    process.env.HEYGEN_API_KEY = "gateway-token";
+    process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+    assert.deepEqual(heygenAuthHeaders(), {
+      "X-Api-Key": "gateway-token",
+      "X-HeyGen-Client-Source": "media-use",
+    });
+    assert.equal(heygenAuthMethod(), "api_key");
+  });
+});
+
+test("heygenJSON sends its request to the host's HEYGEN_API_BASE with the host's key", async () => {
+  /** @type {{ url?: string, key?: string | string[] }} */
+  const seen = {};
+  const server = createServer((req, res) => {
+    seen.url = req.url;
+    seen.key = req.headers["x-api-key"];
+    res.writeHead(200, { "content-type": "application/json" }).end('{"data":[]}');
+  });
+  await new Promise((done) => server.listen(0, "127.0.0.1", done));
+  const { port } = /** @type {import("node:net").AddressInfo} */ (server.address());
+  try {
+    await withCleanHeygenEnv(async () => {
+      process.env.HEYGEN_API_BASE = `http://127.0.0.1:${port}`;
+      process.env.HEYGEN_ALLOW_HTTP = "1";
+      process.env.HEYGEN_API_KEY = "gateway-token";
+      const reply = await heygenJSON("/voices?limit=1", { headers: heygenAuthHeaders() });
+      assert.deepEqual(reply, { data: [] });
+    });
+    assert.equal(seen.url, "/v3/voices?limit=1");
+    assert.equal(seen.key, "gateway-token");
+  } finally {
+    server.close();
+  }
+});
+
+test("a base that isn't HeyGen's gets no stored or host OAuth credential, only a key named for it", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      writeFileSync(join(dir, "credentials"), JSON.stringify({ api_key: "hg_stored" }));
+      process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+      process.env.HEYGEN_API_BASE = "https://proxy.example.com";
+      assert.equal(heygenCredential(), null);
+      assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
+      // HeyGen's own hosts keep every credential source.
+      process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com";
+      assert.equal(heygenAuthMethod(), "oauth");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/dist/skills/media-use/audio/scripts/lib/host-audio.mjs

@@ -0,0 +1,28 @@
+// Audio the host app supplied survives every pass that rebuilds audio_meta.json from the storyboard: an entry
+// marked "source": "host" whose file exists. A frame the host scored takes no looked-up cue sound.
+/** The host's own entries in an earlier audio_meta.json, and why any other host-marked entry was dropped; `exists`
+ *  resolves a path from the project root. A frame written as "1" is frame 1. */
+export function hostAudio(previous, exists) {
+  const marked = [[previous?.bgm, "path"], ...(previous?.sfx ?? []).map((s) => [s, "file"])].filter(
+    ([entry]) => entry?.source === "host",
+  );
+  const kept = new Set();
+  const dropped = [];
+  for (const [entry, key] of marked) {
+    const path = entry[key];
+    if (typeof path !== "string") dropped.push(`a host entry has no "${key}"`);
+    else if (!exists(path)) dropped.push(`${path} is not on disk`);
+    else kept.add(entry);
+  }
+  const bgm = kept.has(previous?.bgm) ? previous.bgm : null;
+  const sfx = (previous?.sfx ?? [])
+    .filter((s) => kept.has(s))
+    .map((s) => ({ ...s, frame: Number(s.frame) }));
+  return { bgm, sfx, frames: new Set(sfx.map((s) => s.frame)), dropped };
+}
+
+/** `rebuilt` with the host's bed and sounds put back; the host's bed wins over a looked-up one. */
+export function keepHostAudio(rebuilt, host) {
+  const looked = (rebuilt.sfx ?? []).filter((s) => !host.frames.has(s.frame));
+  return { ...rebuilt, bgm: host.bgm ?? rebuilt.bgm, sfx: [...host.sfx, ...looked] };
+}

package/dist/skills/media-use/audio/scripts/lib/host-audio.test.mjs

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { hostAudio, keepHostAudio } from "./host-audio.mjs";
+
+const onDisk = new Set([
+  "assets/bgm/host.mp3",
+  "assets/sfx/custom-whoosh.mp3",
+  "assets/sfx/whoosh.mp3",
+]);
+const exists = (path) => onDisk.has(path);
+const hostWhoosh = {
+  frame: 1,
+  file: "assets/sfx/custom-whoosh.mp3",
+  offset_s: 0,
+  duration_s: 2,
+  source: "host",
+};
+
+test("a host sound and bed survive a rebuild, and the host's frame takes no looked-up sound", () => {
+  const previous = {
+    bgm: { path: "assets/bgm/host.mp3", source: "host" },
+    sfx: [hostWhoosh, { frame: 2, file: "assets/sfx/whoosh.mp3", offset_s: 0 }],
+  };
+  const rebuilt = {
+    bgm: null,
+    voices: [],
+    sfx: [
+      { frame: 1, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
+      { frame: 2, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
+    ],
+  };
+  const kept = keepHostAudio(rebuilt, hostAudio(previous, exists));
+  assert.deepEqual(kept.bgm, previous.bgm);
+  assert.deepEqual(kept.sfx, [hostWhoosh, rebuilt.sfx[1]]);
+});
+
+test("an unmarked entry or a missing file is not the host's", () => {
+  const previous = {
+    bgm: { path: "assets/bgm/gone.mp3", source: "host" },
+    sfx: [
+      { frame: 1, file: "assets/sfx/whoosh.mp3", offset_s: 0 },
+      { frame: 3, file: "assets/sfx/gone.mp3", source: "host" },
+    ],
+  };
+  const host = hostAudio(previous, exists);
+  assert.equal(host.bgm, null);
+  assert.deepEqual(host.sfx, []);
+  const rebuilt = { bgm: { path: "assets/bgm/looked.mp3" }, voices: [], sfx: [] };
+  assert.deepEqual(keepHostAudio(rebuilt, host), rebuilt);
+});
+
+test("no earlier audio_meta.json keeps the rebuild as it is", () => {
+  const rebuilt = { bgm: null, voices: [], sfx: [{ frame: 1, file: "assets/sfx/whoosh.mp3" }] };
+  assert.deepEqual(keepHostAudio(rebuilt, hostAudio(null, exists)), rebuilt);
+});
+
+// The narrated workflows tell the agent the same host-audio contract and the same meaning of silent.
+const workflowText = (skill, file) =>
+  readFileSync(new URL(`../../../../${skill}/${file}`, import.meta.url), "utf8");
+
+test("each narrated workflow tells a host app's music and sounds the way in, and when a film is silent", () => {
+  for (const skill of ["product-launch-video", "pr-to-video", "faceless-explainer"]) {
+    const steps = workflowText(skill, "SKILL.md");
+    assert.match(
+      steps,
+      /host app's own tools make the music or a sound effect[^\n]+"source": "host"/,
+      skill,
+    );
+    assert.match(steps, /"duration_s": <its length>[^\n]+Every audio pass keeps these/, skill);
+    assert.match(steps, /no `SCRIPT.md`, \*\*and\*\* no `sfx:` cues or host audio/, skill);
+    assert.match(
+      steps,
+      /marked silent \(`music: none`, no `SCRIPT.md`, no `sfx:` cues or host audio\)/,
+      skill,
+    );
+    assert.match(
+      workflowText(skill, "references/story-design.md"),
+      /no `SCRIPT.md` \+ no `sfx:` cues or host audio\*\* — the canonical/,
+      skill,
+    );
+  }
+});
+
+test("a frame written as a string is the same frame, and a gone host file is reported", () => {
+  const previous = {
+    bgm: { path: "assets/bgm/gone.mp3", source: "host" },
+    sfx: [{ ...hostWhoosh, frame: "1" }],
+  };
+  const host = hostAudio(previous, exists);
+  assert.deepEqual(host.sfx, [hostWhoosh]);
+  assert.ok(host.frames.has(1));
+  assert.deepEqual(host.dropped, ["assets/bgm/gone.mp3 is not on disk"]);
+  const rebuilt = { bgm: null, voices: [], sfx: [{ frame: 1, file: "assets/sfx/whoosh.mp3" }] };
+  assert.deepEqual(keepHostAudio(rebuilt, host).sfx, [hostWhoosh]);
+});
+
+test("a host entry with no path is reported, not thrown", () => {
+  const throwsOnNonString = (path) => {
+    if (typeof path !== "string") throw new TypeError("path must be a string");
+    return onDisk.has(path);
+  };
+  const host = hostAudio({ bgm: { src: "x.mp3", source: "host" }, sfx: [] }, throwsOnNonString);
+  assert.equal(host.bgm, null);
+  assert.deepEqual(host.dropped, ['a host entry has no "path"']);
+});

package/dist/skills/media-use/references/setup-providers.md

@@ -15,11 +15,25 @@ This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), a
 npx hyperframes media-use resolve --doctor
 ```
 
+## Host HeyGen access (no CLI sign-in)
+
+A host app can give media-use HeyGen access of its own by setting
+`HEYGEN_API_BASE` (its gateway), `HEYGEN_API_KEY` (the token that gateway
+accepts) and, for a loopback gateway, `HEYGEN_ALLOW_HTTP=1`. The gateway adds
+the host's key, so it never enters the agent's environment, and every
+call is charged to that key's API credits. The `heygen` CLI honours the same
+variables, so `resolve` (bgm/sfx/image/icon/voice/avatar-video) and the audio
+engine's TTS all go through the host. With host access, skip CLI install and
+sign-in, prefer the host's own HeyGen tools where it has them, never fall back
+to a local or third-party generator on your own, and relay a refused call's
+message (for example "add a key in Settings > Account") as written.
+
 ## Providers
 
 media-use holds no keys; every external tool owns its auth. Generation is
 centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
-before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
+before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects from
+a host app's own tools need none of it. Local tools are opt-in
 alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
 transcription, and LTX for local video generation. `resolve` spec-checks
 AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
@@ -27,7 +41,7 @@ see the ladder and override.
 
 | Type      | Provider / path                                                                                                                                                               |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| bgm/sfx   | heygen catalog free-usage path                                                                                                                                                |
+| bgm/sfx   | heygen catalog free-usage path; a host app's own music and sound tools come first                                                                                             |
 | image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
 | voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
 | icon      | heygen asset search free-usage path                                                                                                                                           |

package/dist/skills/media-use/scripts/lib/heygen-cli.mjs

@@ -68,7 +68,11 @@ function classifyHeygenErrorResult(err) {
   }
 
   const version = firstSemver(text);
-  if (version && versionLessThan(version, HEYGEN_MIN_VERSION)) {
+  // A CLI older than the --headers flag rejects it before printing any version.
+  if (
+    (version && versionLessThan(version, HEYGEN_MIN_VERSION)) ||
+    lower.includes("unknown flag: --headers")
+  ) {
     return { code: "outdated", message: HEYGEN_OUTDATED_MESSAGE };
   }
 
@@ -98,6 +102,22 @@ const pendingFailureTracking = new Set();
 // API, move this state into a per-resolve context before reusing that path.
 let pendingRemediation = null;
 
+const TOOL_WORDS = { bgm: "music", sfx: "sound-effect" };
+
+/** A music or sound-effect resolve miss after the heygen CLI was missing or too old: what is missing, the host
+ * app's own tool, the fix. Other types keep the generic miss. */
+export function heygenMiss(type, { code }) {
+  const tool = TOOL_WORDS[type];
+  if (!tool) return null;
+  const outdated = code === "outdated";
+  const state = outdated ? `older than v${HEYGEN_MIN_VERSION}` : "not installed";
+  return {
+    code: outdated ? "heygen_cli_outdated" : "heygen_cli_missing",
+    fix: outdated ? HEYGEN_UPDATE_COMMAND : HEYGEN_INSTALL_COMMAND,
+    error: `${type} needs the heygen CLI, which is ${state}: use your host app's own ${tool} tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
+  };
+}
+
 export function consumeHeygenRemediation() {
   const remediation = pendingRemediation;
   pendingRemediation = null;

package/dist/skills/media-use/scripts/lib/heygen-cli.test.mjs

@@ -9,6 +9,7 @@ import {
   HEYGEN_NOT_AUTHENTICATED_MESSAGE,
   HEYGEN_NOT_FOUND_MESSAGE,
   HEYGEN_OUTDATED_MESSAGE,
+  heygenMiss,
   reportHeygenFailure,
 } from "./heygen-cli.mjs";
 
@@ -299,3 +300,16 @@ test("flushHeygenFailureTracking waits for a pending report before resolving", a
 test("flushHeygenFailureTracking resolves immediately when nothing is pending", async () => {
   await flushHeygenFailureTracking();
 });
+
+test("only a music or sound-effect miss names the heygen CLI and the host app's own tool", () => {
+  for (const type of ["image", "icon", "voice", "video"])
+    assert.equal(heygenMiss(type, { code: "not_found" }), null, type);
+  assert.equal(heygenMiss("bgm", { code: "not_found" }).code, "heygen_cli_missing");
+  const sfx = heygenMiss("sfx", { code: "outdated" });
+  assert.equal(sfx.code, "heygen_cli_outdated");
+  assert.match(sfx.error, /host app's own sound-effect tool/);
+});
+
+test("a CLI that rejects --headers without printing a version is outdated", () => {
+  assert.equal(classifyHeygenErrorCode({ stderr: "Error: unknown flag: --headers" }), "outdated");
+});

package/dist/skills/media-use/scripts/resolve.mjs

@@ -49,6 +49,7 @@ import {
   HEYGEN_MIN_VERSION,
   HEYGEN_UPDATE_COMMAND,
   consumeHeygenRemediation,
+  heygenMiss,
   firstSemver,
   flushHeygenFailureTracking,
   versionLessThan,
@@ -530,10 +531,16 @@ async function run() {
     });
     // brand stays local: no frame.md/design.md -> upsell the HyperFrames design
     // flow rather than reporting a generic miss (B5).
-    const msg =
+    const ownFailure =
       providerFailure instanceof BundledSfxAssetsError ||
-      providerFailure instanceof FfBinarySettingError
-        ? providerFailure.message
+      providerFailure instanceof FfBinarySettingError;
+    const heygen = consumeHeygenRemediation();
+    const miss = heygen && !ownFailure ? heygenMiss(type, heygen) : null;
+    const typed = providerFailure instanceof BundledSfxAssetsError ? providerFailure : miss;
+    const msg = ownFailure
+      ? providerFailure.message
+      : miss
+        ? miss.error
         : type === "brand"
           ? "no brand spec found — add a frame.md or design.md (colors/font/logo) to this project. Run the HyperFrames design flow to create one; brand tokens are read locally for deterministic rendering."
           : args.provider
@@ -543,9 +550,7 @@ async function run() {
       console.log(
         JSON.stringify({
           ok: false,
-          ...(providerFailure instanceof BundledSfxAssetsError
-            ? { code: providerFailure.code, fix: providerFailure.fix }
-            : {}),
+          ...(typed ? { code: typed.code, fix: typed.fix } : {}),
           error: msg,
         }),
       );