feat(media-use): fast heygen CLI onboarding — actionable diagnostics, --doctor, free-usage framing

media-use resolves bgm/sfx/image/icon (catalog), voice (TTS), and avatar video
through the heygen CLI — the free-usage path. Agents hit a dead end when it's
missing/unauthed. This guides them to install it fast, at the point of need.

- Centralized actionable diagnostics (lib/heygen-cli.mjs): every heygen-backed
  resolve, on failure, prints the exact fix on stderr — not-installed (curl
  install one-liner), not-authenticated (heygen auth login), outdated (heygen
  update). Routed through heygen-search + voice-provider. stdout stays clean JSON.
- resolve --doctor preflight (human + --json): checks heygen present/version/
  auth, ffmpeg, ffprobe, node, a fix per gap. Exit 0 unless ffmpeg missing.
- SKILL reframe: install-first callout; heygen as the free-usage gateway for
  bgm/image/voice/avatar-video; removed the false "degrades gracefully" claim.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

Author: miguel-heygen

skills-manifest.json

@@ -46,8 +46,8 @@
       "files": 10
     },
     "media-use": {
-      "hash": "785f83e0431671e8",
-      "files": 115
+      "hash": "26e552b366e86195",
+      "files": 117
     },
     "motion-graphics": {
       "hash": "96ed2f7d8051b009",

skills/media-use/SKILL.md

@@ -0,0 +1,92 @@
+export const HEYGEN_MIN_VERSION = "0.1.6";
+export const HEYGEN_INSTALL_COMMAND =
+  "curl -fsSL https://static.heygen.ai/cli/install.sh | bash  then  heygen auth login --key <key>";
+export const HEYGEN_AUTH_COMMAND = "heygen auth login --key <key>";
+export const HEYGEN_UPDATE_COMMAND = "heygen update";
+
+export const HEYGEN_NOT_FOUND_MESSAGE = `media-use: heygen CLI not found — it's the free path for bgm/image/voice/avatar-video. Install: ${HEYGEN_INSTALL_COMMAND}`;
+export const HEYGEN_NOT_AUTHENTICATED_MESSAGE = `media-use: heygen CLI not authenticated (free usage) — run: ${HEYGEN_AUTH_COMMAND}`;
+export const HEYGEN_OUTDATED_MESSAGE = `media-use: heygen CLI is outdated — run: ${HEYGEN_UPDATE_COMMAND}  (need >= v${HEYGEN_MIN_VERSION})`;
+
+const ACTIONABLE_MESSAGES = new Set([
+  HEYGEN_NOT_FOUND_MESSAGE,
+  HEYGEN_NOT_AUTHENTICATED_MESSAGE,
+  HEYGEN_OUTDATED_MESSAGE,
+]);
+
+export function classifyHeygenError(err) {
+  const detail = heygenErrorDetail(err);
+  const text = [err?.stderr, err?.stdout, err?.message, detail]
+    .map((value) => textOf(value))
+    .filter(Boolean)
+    .join("\n");
+  const lower = text.toLowerCase();
+
+  if (
+    err?.code === "ENOENT" ||
+    lower.includes("command not found") ||
+    lower.includes("not found")
+  ) {
+    return HEYGEN_NOT_FOUND_MESSAGE;
+  }
+
+  if (
+    lower.includes("unauthorized") ||
+    lower.includes("unauthenticated") ||
+    lower.includes("401") ||
+    lower.includes("not logged in") ||
+    lower.includes("no api key") ||
+    lower.includes("missing api key") ||
+    lower.includes("invalid api key") ||
+    lower.includes("login required") ||
+    lower.includes("auth required") ||
+    lower.includes("authentication required")
+  ) {
+    return HEYGEN_NOT_AUTHENTICATED_MESSAGE;
+  }
+
+  const version = firstSemver(text);
+  if (version && versionLessThan(version, HEYGEN_MIN_VERSION)) {
+    return HEYGEN_OUTDATED_MESSAGE;
+  }
+
+  return detail;
+}
+
+export function reportHeygenFailure(err, context) {
+  const message = classifyHeygenError(err);
+  if (ACTIONABLE_MESSAGES.has(message)) {
+    console.error(message);
+  } else {
+    console.error(`media-use: \`${context}\` failed: ${message}`);
+  }
+}
+
+export function firstSemver(text) {
+  const match = String(text || "").match(/\bv?(\d+)\.(\d+)\.(\d+)\b/);
+  return match ? `${match[1]}.${match[2]}.${match[3]}` : null;
+}
+
+export function versionLessThan(version, minimum) {
+  const left = versionParts(version);
+  const right = versionParts(minimum);
+  if (!left || !right) return false;
+  for (let i = 0; i < 3; i++) {
+    if (left[i] < right[i]) return true;
+    if (left[i] > right[i]) return false;
+  }
+  return false;
+}
+
+function heygenErrorDetail(err) {
+  return textOf(err?.stderr) || textOf(err?.stdout) || err?.message || String(err);
+}
+
+function textOf(value) {
+  return value == null ? "" : String(value).trim();
+}
+
+function versionParts(version) {
+  const match = String(version || "").match(/^v?(\d+)\.(\d+)\.(\d+)$/);
+  return match ? match.slice(1).map((part) => Number.parseInt(part, 10)) : null;
+}

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

@@ -0,0 +1,38 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { classifyHeygenError } from "./heygen-cli.mjs";
+
+test("classifies ENOENT-style missing heygen errors with install instructions", () => {
+  const message = classifyHeygenError({ code: "ENOENT", message: "spawn heygen ENOENT" });
+
+  assert.equal(
+    message,
+    "media-use: heygen CLI not found — it's the free path for bgm/image/voice/avatar-video. Install: curl -fsSL https://static.heygen.ai/cli/install.sh | bash  then  heygen auth login --key <key>",
+  );
+});
+
+test("classifies auth failures with login instructions", () => {
+  const message = classifyHeygenError({ stderr: Buffer.from("Error: not logged in") });
+
+  assert.equal(
+    message,
+    "media-use: heygen CLI not authenticated (free usage) — run: heygen auth login --key <key>",
+  );
+});
+
+test("classifies old heygen versions with update instructions", () => {
+  const message = classifyHeygenError({
+    stderr: Buffer.from("heygen v0.1.5 does not support --headers"),
+  });
+
+  assert.equal(message, "media-use: heygen CLI is outdated — run: heygen update  (need >= v0.1.6)");
+});
+
+test("passes through unrelated errors", () => {
+  const message = classifyHeygenError({
+    stderr: Buffer.from("rate limit exceeded"),
+    message: "Command failed",
+  });
+
+  assert.equal(message, "rate limit exceeded");
+});

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

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { reportHeygenFailure } from "./heygen-cli.mjs";
 
 export function heygenSearch(subcommand, query, { type, limit = 5, minScore } = {}) {
   // execFileSync with an argv array (no shell), so query/type/etc. are passed as
@@ -28,8 +29,7 @@ export function heygenSearch(subcommand, query, { type, limit = 5, minScore } =
   } catch (err) {
     // Don't swallow a broken command / auth failure as "no results" — that turns
     // a typo or expired key into a silent dead end. Surface it, then give up.
-    const detail = err.stderr?.toString().trim() || err.stdout?.toString().trim() || err.message;
-    console.error(`media-use: \`heygen ${subcommand}\` failed: ${detail}`);
+    reportHeygenFailure(err, `heygen ${subcommand}`);
     return null;
   }
 

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

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { reportHeygenFailure } from "./heygen-cli.mjs";
 
 // Voice / TTS generation via the HeyGen CLI — the only external CLI media-use
 // shells (CLI-only invariant: media-use holds no keys; the CLI owns auth).
@@ -13,9 +14,7 @@ function runJson(bin, argv, label) {
       stdio: ["pipe", "pipe", "pipe"],
     });
   } catch (err) {
-    console.error(
-      `media-use: \`${bin}\` ${label} failed: ${err.stderr?.toString().trim() || err.message}`,
-    );
+    reportHeygenFailure(err, `${bin} ${label}`);
     return null;
   }
   try {

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { spawnSync } from "node:child_process";
 import { existsSync, statSync, writeFileSync, rmSync } from "node:fs";
 import { resolve, join, extname, basename } from "node:path";
 import { parseArgs } from "node:util";
@@ -17,6 +18,14 @@ import { buildCube, paramsFromIntent } from "./lib/cube-build.mjs";
 import { validateCubeFile } from "./lib/cube-validate.mjs";
 import { analyzeMediaGrade, formatMeasuredNote } from "./lib/grade-analyzer.mjs";
 import { freezeLibraryLut, matchColorLook } from "./lib/lut-preset-provider.mjs";
+import {
+  HEYGEN_AUTH_COMMAND,
+  HEYGEN_INSTALL_COMMAND,
+  HEYGEN_MIN_VERSION,
+  HEYGEN_UPDATE_COMMAND,
+  firstSemver,
+  versionLessThan,
+} from "./lib/heygen-cli.mjs";
 
 const { values: args } = parseArgs({
   options: {
@@ -26,6 +35,7 @@ const { values: args } = parseArgs({
     project: { type: "string", short: "p", default: "." },
     adopt: { type: "boolean", default: false },
     candidates: { type: "boolean", default: false },
+    doctor: { type: "boolean", default: false },
     "dry-run": { type: "boolean", default: false },
     reuse: { type: "string" },
     from: { type: "string" },
@@ -55,6 +65,7 @@ Options:
   --adopt         Adopt all existing assets/ files into the manifest
   --candidates    List reusable assets (project + global cache) for --type; no
                   download, no mutation. Read them and decide reuse yourself.
+  --doctor        Check local CLI dependencies; no manifest changes.
   --reuse <sha>   Import a specific global-cache asset (by content sha/prefix,
                   from --candidates) into this project
   --from <file>   Freeze a local file or direct public URL (ingest)
@@ -95,6 +106,16 @@ if (args.candidates || args["dry-run"]) {
   process.exit(0);
 }
 
+if (args.doctor) {
+  const doctor = runDoctor();
+  if (args.json) {
+    console.log(JSON.stringify({ ok: doctor.ok, checks: doctor.checks }));
+  } else {
+    printDoctor(doctor.checks);
+  }
+  process.exit(doctor.ok ? 0 : 1);
+}
+
 // Reuse: import a specific global-cache asset (by content sha/prefix, taken
 // from --candidates) into this project. `!== undefined` so an empty --reuse ""
 // still routes here (and gets a clear empty-sha error) instead of falling
@@ -679,6 +700,143 @@ async function showCandidates() {
   }
 }
 
+function runDoctor() {
+  const checks = [];
+  const heygenVersionProbe = runCommand("heygen", ["--version"]);
+  const heygenOnPath = heygenVersionProbe.status === 0;
+  const heygenVersionText = commandText(heygenVersionProbe);
+  const heygenVersion = firstSemver(heygenVersionText);
+
+  checks.push({
+    name: "heygen on PATH",
+    ok: heygenOnPath,
+    detail: heygenOnPath
+      ? `heygen ${heygenVersion ? `v${heygenVersion}` : "found"}`
+      : "heygen not found",
+    fix: heygenOnPath ? "" : HEYGEN_INSTALL_COMMAND,
+  });
+
+  if (!heygenOnPath) {
+    checks.push({
+      name: "heygen version",
+      ok: false,
+      detail: "heygen version unavailable",
+      fix: HEYGEN_INSTALL_COMMAND,
+    });
+    checks.push({
+      name: "heygen authenticated",
+      ok: false,
+      detail: "heygen auth status unavailable",
+      fix: HEYGEN_INSTALL_COMMAND,
+    });
+  } else if (heygenVersion) {
+    const versionOk = !versionLessThan(heygenVersion, HEYGEN_MIN_VERSION);
+    checks.push({
+      name: "heygen version",
+      ok: versionOk,
+      detail: `heygen v${heygenVersion} (need >= v${HEYGEN_MIN_VERSION})`,
+      fix: versionOk ? "" : HEYGEN_UPDATE_COMMAND,
+    });
+
+    const authProbe = runCommand("heygen", ["auth", "status"]);
+    const email = authProbe.status === 0 ? emailFromAuthStatus(commandText(authProbe)) : null;
+    checks.push({
+      name: "heygen authenticated",
+      ok: !!email,
+      detail: email ? `heygen authenticated as ${email}` : "heygen not authenticated",
+      fix: email ? "" : HEYGEN_AUTH_COMMAND,
+    });
+  } else {
+    checks.push({
+      name: "heygen version",
+      ok: true,
+      detail: "heygen version did not include semver",
+      fix: "",
+    });
+
+    const authProbe = runCommand("heygen", ["auth", "status"]);
+    const email = authProbe.status === 0 ? emailFromAuthStatus(commandText(authProbe)) : null;
+    checks.push({
+      name: "heygen authenticated",
+      ok: !!email,
+      detail: email ? `heygen authenticated as ${email}` : "heygen not authenticated",
+      fix: email ? "" : HEYGEN_AUTH_COMMAND,
+    });
+  }
+
+  const ffmpegProbe = runCommand("ffmpeg", ["-version"]);
+  checks.push({
+    name: "ffmpeg on PATH",
+    ok: ffmpegProbe.status === 0,
+    detail: ffmpegProbe.status === 0 ? firstLine(ffmpegProbe.stdout) : "ffmpeg not found",
+    fix: ffmpegProbe.status === 0 ? "" : "brew install ffmpeg",
+  });
+
+  const ffprobeProbe = runCommand("ffprobe", ["-version"]);
+  checks.push({
+    name: "ffprobe on PATH",
+    ok: ffprobeProbe.status === 0,
+    detail: ffprobeProbe.status === 0 ? firstLine(ffprobeProbe.stdout) : "ffprobe not found",
+    fix: ffprobeProbe.status === 0 ? "" : "brew install ffmpeg",
+  });
+
+  checks.push({
+    name: "node version",
+    ok: true,
+    detail: process.version,
+    fix: "",
+  });
+
+  const ffmpeg = checks.find((check) => check.name === "ffmpeg on PATH");
+  return { ok: !!ffmpeg?.ok, checks };
+}
+
+function printDoctor(checks) {
+  const heygenChecks = new Set(["heygen on PATH", "heygen version", "heygen authenticated"]);
+  for (const check of checks) {
+    const prefix = check.ok ? "✓" : "✗";
+    const freePath = heygenChecks.has(check.name)
+      ? " — free-usage path: bgm/image/voice/avatar-video"
+      : "";
+    const fix = check.ok || !check.fix ? "" : ` — fix: ${check.fix}`;
+    console.log(`${prefix} ${check.detail}${freePath}${fix}`);
+  }
+}
+
+function runCommand(bin, argv) {
+  return spawnSync(bin, argv, {
+    encoding: "utf8",
+    timeout: 15000,
+  });
+}
+
+function commandText(result) {
+  return [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
+}
+
+function firstLine(text) {
+  return (
+    String(text || "")
+      .trim()
+      .split(/\r?\n/)[0] || ""
+  );
+}
+
+function emailFromAuthStatus(text) {
+  const trimmed = String(text || "").trim();
+  if (!trimmed) return null;
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      return parsed?.data?.email || parsed?.email || null;
+    } catch {
+      return null;
+    }
+  }
+  const match = trimmed.match(/[^\s@]+@[^\s@]+\.[^\s@]+/);
+  return match ? match[0] : null;
+}
+
 async function reuseGlobal(shaArg) {
   const projectDir = resolve(args.project);
   const type = args.type;