feat(media-use): add video generation (HeyGen avatar-video + local LTX fallback) (#2614)

* fix(media-use): tag HeyGen TTS generation with attribution header

Centralizes the X-HeyGen-Client-Source header into HEYGEN_CLIENT_SOURCE_ARGV
in heygen-cli.mjs and reuses it in heygen-search.mjs (dropping the duplicated
inline literal) so voice-provider's `voice speech create` call carries it too.
The generation call was previously untagged, making media-use TTS usage
invisible in HeyGen's billing/analytics warehouse; the read-only `voice list`
discovery call intentionally stays untagged.

* feat(media-use): add local LTX video generate provider

* feat(media-use): add HeyGen avatar-video generate provider

* feat(media-use): register video as a real provider type

* docs(media-use): document the wired video type and full HeyGen tagging coverage

resolve --type video is now the default path (HeyGen avatar video first,
local LTX fallback, sign-in nudge on auth failure) instead of a manual
recipe; correct the claim that only search requests are tagged now that
TTS and avatar-video generation carry the attribution header too.

* fix(media-use): wire --avatar-id/--voice-id CLI flags and close video-provider auth/cache gaps

- resolve.mjs never implemented the --avatar-id/--voice-id override that
  operations.md documented, so following the docs crashed with
  ERR_PARSE_ARGS_UNKNOWN_OPTION; wire the flags through to ctx.
- defaultAvatarId/defaultStarfishVoiceId cached a failed discovery lookup
  as a permanent null, disabling heygen.video after one transient miss;
  cache only a truthy id, matching the same fix in voice-provider.mjs's
  defaultVoiceId.
- the avatar-video onboarding nudge only fired on a video-create failure,
  never when avatar/voice discovery itself was unauthenticated (the
  common unauthenticated case) -- propagate the discovery failure reason
  so onboarding fires either way.
- dedupe the CLI-shelling JSON helper (heygen-cli.mjs's new runHeygenJson)
  and the local-model argv-template builder (local-models.mjs's new
  buildArgv) instead of leaving byte-identical copies in each provider.

* fix(media-use): address avatar-video PR review feedback

- heygenVideoGenerate short-circuits after the first discovery-call
  failure instead of always attempting both avatar list and voice list,
  so an unauthenticated caller gets one onboarding message and one
  provider-error telemetry ping instead of a double-fire.
- runHeygenJson logs a diagnostic when a CLI call succeeds but returns
  unparseable JSON, instead of silently returning null.
- dedupe the "avatar video is free" onboarding string into one constant
  (was duplicated across three call sites).

* fix(media-use): match review-requested naming and message conventions

- export AVATAR_VIDEO_SIGNIN_MESSAGE from heygen-video-provider.mjs so
  the test imports the canonical string instead of redeclaring it.
- runHeygenJson's non-JSON diagnostic now matches heygen-search.mjs's
  existing wording ("returned non-JSON output").

skills/media-use/scripts/lib/registry.test.mjs

@@ -1,12 +1,31 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
-import { getProviders, getProvider, listTypes, runProviders, runCapability } from "./registry.mjs";
+import {
+  getProviders,
+  getProvider,
+  listTypes,
+  providerMatches,
+  providerNamesFor,
+  runProviders,
+  runCapability,
+} from "./registry.mjs";
 
 // --- registry shape -------------------------------------------------------
 
 test("listTypes exposes the v2 media types", () => {
   const types = listTypes();
-  for (const t of ["bgm", "sfx", "image", "icon", "logo", "voice", "brand", "grade", "lut"]) {
+  for (const t of [
+    "bgm",
+    "sfx",
+    "image",
+    "icon",
+    "logo",
+    "voice",
+    "video",
+    "brand",
+    "grade",
+    "lut",
+  ]) {
     assert.ok(types.includes(t), `missing type: ${t}`);
   }
 });
@@ -19,9 +38,9 @@ test("heygen provider is first for every type it serves", () => {
   }
 });
 
-test("sanctioned providers only: heygen, local mflux/kokoro, codex, design spec, logo tiers", () => {
+test("sanctioned providers only: heygen, local mflux/kokoro/ltx, codex, design spec, logo tiers", () => {
   const allowed =
-    /^heygen|^bundled\.sfx$|^mflux\.local$|^kokoro\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
+    /^heygen|^bundled\.sfx$|^mflux\.local$|^kokoro\.local$|^ltx\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
   for (const t of listTypes()) {
     for (const p of getProviders(t)) {
       assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`);
@@ -52,6 +71,17 @@ test("voice cascade: HeyGen TTS first, Kokoro remains the local fallback", () =>
   assert.ok(!ps[1].paid, "local Kokoro is free");
 });
 
+test("video cascade: HeyGen first, LTX local fallback, generate-only", async () => {
+  assert.deepEqual(providerNamesFor("video"), ["heygen.video", "ltx.local"]);
+  assert.equal(providerMatches("video", "ltx.local"), true);
+
+  const ps = getProviders("video");
+  assert.ok(ps[0].network, "HeyGen video is network (skipped under --local-only)");
+  assert.ok(ps[0].paid, "HeyGen video may bill after the OAuth free allowance");
+  assert.ok(!ps[1].network, "local LTX is kept under --local-only");
+  assert.equal(await runCapability("video", "search", "x", {}), null);
+});
+
 test("sfx cascade: HeyGen catalog first, bundled library remains the local fallback", () => {
   const ps = getProviders("sfx");
   assert.equal(ps[0].name, "heygen.audio.sounds");