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/resolve.test.mjs

@@ -492,6 +492,46 @@ test("--from registers a derived video as documented", () => {
   cleanup();
 });
 
+test("--from type error lists video exactly once", () => {
+  const result = spawnResolve(["--from", "missing.mp4"]);
+  assert.equal(result.status, 2);
+  assert.match(result.stderr, /--from requires --type \(one of:/);
+  assert.equal(result.stderr.match(/\bvideo\b/g)?.length, 1);
+});
+
+test("--from uses .mp4 as the default video extension", () => {
+  setup();
+  const source = join(tmp, "extensionless-video");
+  writeFileSync(source, "video bytes");
+
+  const out = runResolve(["--from", source, "--type", "video", "--project", tmp, "--json"]);
+  const parsed = JSON.parse(out.trim());
+  assert.match(parsed.path, /^\.media\/video\/video_001\.mp4$/);
+  cleanup();
+});
+
+test("--avatar-id/--voice-id parse as real CLI flags (regression guard: docs promise them, parseArgs must not reject them)", () => {
+  setup();
+  const result = spawnResolve(
+    [
+      "--type",
+      "video",
+      "--intent",
+      "regression guard",
+      "--local-only",
+      "--avatar-id",
+      "avatar-override",
+      "--voice-id",
+      "voice-override",
+      "--project",
+      tmp,
+    ],
+    { stdio: "pipe" },
+  );
+  assert.doesNotMatch(result.stderr || "", /ERR_PARSE_ARGS_UNKNOWN_OPTION/);
+  cleanup();
+});
+
 test("unknown type error lists grade and lut", () => {
   try {
     runResolve(["--type", "bogus", "--intent", "x"], { stdio: "pipe" });