@genex-ai/cli-demo 1.33.0-dev.690 → 1.34.0-dev.692

package/dist/index.js

@@ -1925,7 +1925,8 @@ async function readLedger(cwd = process.cwd()) {
             prompt: typeof e.prompt === "string" ? e.prompt : "",
             ...typeof e.tail === "string" ? { promptTail: e.tail } : {},
             queuedAt: typeof e.at === "string" ? e.at : "",
-            status: "queued"
+            status: "queued",
+            ...typeof e.out === "string" && e.out ? { outDir: e.out } : {}
           });
         }
       } else if (e.t === "done" && typeof e.id === "string") {
@@ -1949,7 +1950,8 @@ async function recordQueued(id, kind, prompt, cwd = process.cwd(), extra = {}) {
     prompt: prompt.slice(0, 120),
     ...prompt.length > 120 ? { tail: prompt.slice(-120) } : {},
     at: (/* @__PURE__ */ new Date()).toISOString(),
-    ...typeof credits === "number" && Number.isFinite(credits) && credits >= 0 ? { credits } : {}
+    ...typeof credits === "number" && Number.isFinite(credits) && credits >= 0 ? { credits } : {},
+    ...typeof extra.outDir === "string" && extra.outDir.trim() ? { out: extra.outDir.trim() } : {}
   });
 }
 async function recordTerminal(id, status, urls, cwd = process.cwd()) {
@@ -2018,9 +2020,10 @@ function localAssetStem(kind, prompt, id) {
 }
 function localAssetName(kind, prompt, id, file, multi) {
   const base = localAssetStem(kind, prompt, id);
-  const role = multi ? `-${file.role.replace(/^(texture|image|character|model|model_anim|model-anim)-/, "")}` : "";
+  const label = file.label ? `-${file.label.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60)}` : "";
+  const role = multi && !label ? `-${file.role.replace(/^(texture|image|character|model|model_anim|model-anim)-/, "")}` : "";
   const ext = file.ext.replace(/^\./, "") || "bin";
-  return `${base}${role}.${ext}`;
+  return `${base}${label}${role}.${ext}`;
 }
 async function downloadAssets(files, opts) {
   const wanted = primaryFiles(files);
@@ -7981,6 +7984,15 @@ function oneLineError(error, max = RAW_ERROR_MAX_CHARS) {
 }
 function describeGenerationFailure(kind, error) {
   if (!isProviderBillingError(error)) {
+    if (error && /both failed native controller QA/.test(error)) {
+      return {
+        billing: false,
+        lines: [
+          c.red(error),
+          `  For a rigged body from any mesh: ${c.cyan('npx genex model "<prompt>" --face-limit 20000')} then ${c.cyan("npx genex character import <that .glb>")} \u2014 Uthana auto-rigs it, and \`character animate\` gives it every move.`
+        ]
+      };
+    }
     return { billing: false, lines: error ? [c.red(error)] : [] };
   }
   return {
@@ -8021,11 +8033,16 @@ function unshippedCounts(rows) {
       break;
     }
   }
+  const failed = /* @__PURE__ */ new Set();
+  for (const r of rows) {
+    if (r?.t === "done" && r.status === "failed" && typeof r.id === "string") failed.add(r.id);
+  }
   let total = 0;
   let character = 0;
   for (let i = lastShip + 1; i < rows.length; i += 1) {
     const r = rows[i];
     if (r?.t !== "q") continue;
+    if (typeof r.id === "string" && failed.has(r.id)) continue;
     total += 1;
     if (typeof r.kind === "string" && CHARACTER_KINDS.has(r.kind)) character += 1;
   }
@@ -8737,7 +8754,10 @@ async function runGenerate(kind, opts) {
     process.exitCode = 1;
     return;
   }
-  await recordQueued(id, kind, prompt, void 0, { credits: creditsQuoted ?? opts.quotedCredits });
+  await recordQueued(id, kind, prompt, void 0, {
+    credits: creditsQuoted ?? opts.quotedCredits,
+    ...opts.outDir ? { outDir: opts.outDir } : {}
+  });
   if (opts.noWait) {
     if (opts.json) {
       writeJson({
@@ -8862,14 +8882,18 @@ async function reportGlassTerminal(view, outDir, log, json) {
   }
 }
 async function awaitAndReport(apiUrl, token, id, kind, log, open = false, json = false, local) {
-  if (!json) log.step("Generating\u2026 (this can take up to a minute)");
+  if (!json) log.step(waitCopy(kind));
+  const started = Date.now();
   const view = await waitForTerminalView(
     apiUrl,
     token,
     id,
     kind,
     json ? () => {
-    } : (p) => log.dim(`  ${p}%`)
+    } : (p) => {
+      const minutes = Math.floor((Date.now() - started) / 6e4);
+      log.dim(`  ${p}%${minutes >= 1 ? `  (${minutes} min)` : ""}`);
+    }
   );
   if (!view) {
     if (json) writeJson({ kind, id, status: "failed", error: "Timed out waiting for the generation." });
@@ -8879,6 +8903,25 @@ async function awaitAndReport(apiUrl, token, id, kind, log, open = false, json =
   }
   await reportTerminal(kind, view, log, open, json, local);
 }
+function waitCopy(kind) {
+  switch (kind) {
+    case "character_motion":
+      return "Generating motion clips\u2026 (each clip is its own provider job \u2014 a batch takes several minutes, a 16-clip walk + run set ten or more; keep building and check back with genex wait --all)";
+    case "character":
+    case "character_concept":
+    case "character_preview":
+      return "Generating\u2026 (character stages take several minutes server-side)";
+    case "model":
+    case "model_segment":
+    case "model_rig":
+    case "model_animation":
+      return "Generating\u2026 (a mesh takes a few minutes; --low-poly up to thirty)";
+    case "video":
+      return "Generating\u2026 (a clip takes a minute or two)";
+    default:
+      return "Generating\u2026 (this can take up to a minute)";
+  }
+}
 async function waitForTerminalView(apiUrl, token, id, kind, onProgress = () => {
 }) {
   const timeoutMs = waitTimeoutFor(kind);
@@ -8934,6 +8977,7 @@ async function reportTerminal(kind, view, log, open = false, json = false, local
     if (!json) reportMocked(view, log);
     return;
   }
+  const batch = motionBatchOutcome(view);
   if (json) {
     writeJson({
       kind,
@@ -8945,12 +8989,25 @@ async function reportTerminal(kind, view, log, open = false, json = false, local
       ...delivered ? { saved: delivered.saved, downloadFailures: delivered.failures } : {},
       ...kind === "character" ? {
         characterId: view.id,
-        nextCommand: `genex controller character --character ${view.id}`
+        nextCommand: `genex controller character --character ${view.id}`,
+        ...rigFallbackOf(view) ? { rigProvider: "uthana", rigFallback: rigFallbackOf(view) } : {}
+      } : {},
+      // A motion batch that lost a clip is `completed` (what landed is real)
+      // AND `partial: true` — the flag a machine reader must check.
+      ...batch ? {
+        characterId: batch.characterId,
+        partial: batch.partial,
+        clipsRequested: batch.requested,
+        clipsInstalled: batch.installed,
+        ...batch.failures.length > 0 ? { failures: batch.failures } : {},
+        ...batch.fallbacks.length > 0 ? { fallbacks: batch.fallbacks } : {},
+        ...batch.refundedCredits ? { refundedCredits: batch.refundedCredits } : {}
       } : {}
     });
     return;
   }
   log.plain("");
+  if (batch?.partial) reportPartialBatch(batch, log);
   if (delivered) {
     reportLocalFiles(delivered, log, false);
   } else {
@@ -8977,8 +9034,70 @@ async function reportTerminal(kind, view, log, open = false, json = false, local
     log.plain(`     ${files[0].url}`);
     log.plain("");
   }
+  if (batch && !batch.partial && batch.fallbacks.length > 0) reportFallbacks(batch, log);
+  if (kind === "character") {
+    const fallback = rigFallbackOf(view);
+    if (fallback) {
+      log.plain(
+        `  ${c.yellow("\u26A0")} Meshy's rig failed pose QA in both rest poses (${fallback.poseMode} mesh kept), so ${c.bold("Uthana auto-rigged it instead")}: no controller pack and no catalog clips on this body. Give it moves with ${c.cyan(`genex character animate ${view.id} --locomotion`)} and plain-word verbs.`
+      );
+    }
+  }
   printHint(kind, view, files, log, delivered !== null);
 }
+function motionBatchOutcome(view) {
+  if (view.kind !== "character_motion" && view.kind !== void 0) return null;
+  const meta = metadataOf(view);
+  const requested = typeof meta.clipsRequested === "number" ? meta.clipsRequested : void 0;
+  const installed = typeof meta.clipsInstalled === "number" ? meta.clipsInstalled : void 0;
+  if (requested === void 0 || installed === void 0) return null;
+  const failures = Array.isArray(meta.failures) ? meta.failures.filter((f) => typeof f === "object" && f !== null && typeof f.clip === "string").map((f) => ({ clip: f.clip, error: typeof f.error === "string" ? f.error : "" })) : [];
+  const fallbacks = Array.isArray(meta.fallbacks) ? meta.fallbacks.filter((f) => typeof f === "object" && f !== null && typeof f.clip === "string") : [];
+  return {
+    ...typeof meta.characterId === "string" ? { characterId: meta.characterId } : {},
+    // Servers before 2026-09-13 sent no `outcome`; a non-empty failure list
+    // says the same thing.
+    partial: meta.outcome === "partial" || failures.length > 0,
+    requested,
+    installed,
+    failures,
+    fallbacks,
+    ...typeof meta.refundedCredits === "number" ? { refundedCredits: meta.refundedCredits } : {}
+  };
+}
+function reportPartialBatch(batch, log) {
+  const missing = batch.requested - batch.installed;
+  log.plain(
+    `${c.yellow("\u26A0")} ${c.bold(`${batch.installed} of ${batch.requested} clips landed`)} \u2014 ${missing} did not:`
+  );
+  for (const f of batch.failures) {
+    log.plain(`    \xB7 ${c.bold(f.clip)}${f.error ? c.dim(` \u2014 ${oneLineError(f.error)}`) : ""}`);
+  }
+  const verbs = batch.failures.map((f) => `"${f.clip}"`).join(" ");
+  if (batch.characterId && verbs) {
+    log.plain(`  Re-run only the missing ones: ${c.cyan(`genex character animate ${batch.characterId} ${verbs}`)}`);
+  }
+  if (batch.refundedCredits) log.dim(`  ${batch.refundedCredits} credits refunded for what did not land.`);
+  if (batch.fallbacks.length > 0) reportFallbacks(batch, log);
+  log.plain("");
+}
+function reportFallbacks(batch, log) {
+  for (const f of batch.fallbacks) {
+    log.plain(
+      `  ${c.yellow("\u21B3")} ${c.bold(f.clip)} was ${f.to === "text" ? "described" : f.to} instead of ${f.from === "video" ? "filmed" : f.from}${f.reason ? c.dim(` (${oneLineError(f.reason)})`) : ""} \u2014 watch it on the character before calling it done.`
+    );
+  }
+}
+function rigFallbackOf(view) {
+  const meta = metadataOf(view);
+  const fallback = meta.rigFallback;
+  if (!fallback || typeof fallback !== "object") return null;
+  const { poseMode, failures } = fallback;
+  return {
+    poseMode: typeof poseMode === "string" ? poseMode : "a-pose",
+    failures: Array.isArray(failures) ? failures.filter((f) => typeof f === "string") : []
+  };
+}
 function reportLocalFiles(result, log, json) {
   if (json) return;
   if (result.saved.length > 0) {
@@ -9161,7 +9280,9 @@ function assetHint(kind, view, url) {
     character_preview: "Show all four preview views to the user and wait for explicit approval before finalizing.",
     character: `Install the controller and current manifest with genex controller character --character ${view.id}.`,
     character_animation: "The action is now part of the character's current manifest; refresh the local controller manifest before testing.",
-    character_motion: `The clips are part of the character's current manifest \u2014 install them with genex controller character --character ${view.id}, then play the game and watch the motion on the real character before calling it done.`,
+    // The CHARACTER's id, not this motion job's: the hint printed the job id
+    // for four months and the command it named did not resolve (2026-09-13).
+    character_motion: `The clips are part of the character's current manifest \u2014 install them with genex controller character --character ${stringValue(metadataOf(view).characterId) ?? "<character-id>"}, then play the game and watch the motion on the real character before calling it done.`,
     model_segment: `One GLB with NAMED parts \u2014 load it through the quality kit (loadModelWithFallback, as for a plain model), then getObjectByName / traverse scene.children to move, detach, or swap a part. Part names print above when the provider reports them.`,
     model_rig: `Rigged GLB (Tripo skeleton) \u2014 load it through the quality kit (loadModelWithFallback); give it motion with genex model animate ${view.id} --preset walk, or drive the bones in code.`,
     model_animation: `Animated GLB \u2014 load it through the quality kit (loadModelWithFallback) and play its clips via THREE.AnimationMixer (gltf.animations).`
@@ -9590,8 +9711,12 @@ async function runWait(opts) {
     return;
   }
   const kind = view.kind ?? "image";
-  const ledgerPrompt = (await readLedger(opts.cwd ?? process.cwd())).find((e) => e.id === id)?.prompt;
-  const local = localDeliveryFor(await workspaceMode(), opts, ledgerPrompt || kind);
+  const ledgerEntry = (await readLedger(opts.cwd ?? process.cwd())).find((e) => e.id === id);
+  const local = localDeliveryFor(
+    await workspaceMode(),
+    { ...opts, outDir: opts.outDir ?? ledgerEntry?.outDir },
+    ledgerEntry?.prompt || kind
+  );
   log.plain(c.bold("genex wait"));
   log.dim(`  ${kind} ${id}`);
   log.plain("");
@@ -9603,6 +9728,10 @@ async function runWait(opts) {
     log.dim(
       `  \u23F3 Character stages take several minutes server-side \u2014 you don't have to sit here. Keep building and check back with ${c.cyan("genex wait --all")}.`
     );
+  } else if (kind === "character_motion") {
+    log.dim(
+      `  \u23F3 Motion batches take several minutes server-side (each clip is its own job; a 16-clip walk + run set ten or more) \u2014 you don't have to sit here. Keep building and check back with ${c.cyan("genex wait --all")}.`
+    );
   }
   await awaitAndReport(apiUrl, token, id, kind, log, opts.open, opts.json, local);
 }
@@ -9667,7 +9796,7 @@ async function runWaitAll(opts) {
     for (const e of ledger) {
       const v = views.get(e.id);
       if (v?.status !== "completed" || !v.files?.length) continue;
-      const local = localDeliveryFor("tools", opts, e.prompt || e.kind);
+      const local = localDeliveryFor("tools", { ...opts, outDir: opts.outDir ?? e.outDir }, e.prompt || e.kind);
       if (!local) continue;
       const outDir = path25.join(path25.relative(process.cwd(), cwd) || ".", local.outDir);
       const target = { kind: e.kind, prompt: local.prompt, id: e.id, outDir };
@@ -9687,21 +9816,27 @@ async function runWaitAll(opts) {
   log.plain(c.bold("genex wait --all"));
   log.plain("");
   for (const r of rows) {
-    const mark = r.status === "done" ? c.green("\u2713") : r.status === "failed" ? c.red("\u2717") : c.yellow("\u2026");
-    const label = r.status === "running" && typeof r.progress === "number" ? `running ${r.progress}%` : r.status;
+    const mark = r.partial ? c.yellow("\u26A0") : r.status === "done" ? c.green("\u2713") : r.status === "failed" ? c.red("\u2717") : c.yellow("\u2026");
+    const label = r.status === "running" && typeof r.progress === "number" ? `running ${r.progress}%` : r.partial ? "partial" : r.status;
     log.plain(`  ${mark} ${label.padEnd(12)} ${r.kind.padEnd(8)} ${r.id}  ${c.dim(`"${r.prompt.slice(0, 56)}"`)}`);
+    if (r.partial) {
+      log.plain(
+        `      ${c.yellow(`${r.partial.installed} of ${r.partial.requested} clips landed`)} \u2014 missing: ${r.partial.failed.join(", ")}. ${c.dim(`genex wait ${r.id}`)} names the fix.`
+      );
+    }
     if (r.status === "failed" && r.error) {
       for (const line of describeGenerationFailure(r.kind, r.error).lines) log.plain(`      ${line}`);
     }
     if (r.status === "done" && r.mocked) log.dim(`      ${MOCKED_LINE}`);
   }
   const count = (s) => rows.filter((r) => r.status === s).length;
+  const partial = rows.filter((r) => r.partial).length;
   const billingFailed = rows.filter(
     (r) => r.status === "failed" && isProviderBillingError(r.error)
   ).length;
   log.plain("");
   log.plain(
-    `  ${count("done")} done \xB7 ${count("running")} running \xB7 ${count("queued")} queued \xB7 ${count("failed")} failed`
+    `  ${count("done")} done${partial > 0 ? ` (${partial} partial)` : ""} \xB7 ${count("running")} running \xB7 ${count("queued")} queued \xB7 ${count("failed")} failed`
   );
   if (billingFailed > 0) {
     log.dim(
@@ -9750,8 +9885,15 @@ async function toRow(e, v, cwd) {
       });
     }
     switch (v.status) {
-      case "completed":
-        return { ...base, status: "done", ...v.mocked === true ? { mocked: true } : {} };
+      case "completed": {
+        const batch = motionBatchOutcome(v);
+        return {
+          ...base,
+          status: "done",
+          ...v.mocked === true ? { mocked: true } : {},
+          ...batch?.partial ? { partial: { installed: batch.installed, requested: batch.requested, failed: batch.failures.map((f) => f.clip) } } : {}
+        };
+      }
       case "failed":
         return { ...base, status: "failed", error: v.error };
       case "processing":
@@ -19952,7 +20094,7 @@ async function postWorkflow(url, token, body) {
 }
 async function runWorkflow(args) {
   const log = createLogger({ quiet: args.opts.quiet || args.opts.json });
-  {
+  if (await workspaceMode() !== "tools") {
     const counts = unshippedCounts(await readLedgerRows());
     const verdict = ceilingVerdict({ kind: args.kind, counts, config: ceilingConfig() });
     if (!verdict.allow) {
@@ -19981,7 +20123,8 @@ async function runWorkflow(args) {
     return;
   }
   await recordQueued(created.id, args.kind, args.prompt, void 0, {
-    credits: created.creditsQuoted ?? args.quotedCredits
+    credits: created.creditsQuoted ?? args.quotedCredits,
+    ...args.opts.outDir ? { outDir: args.opts.outDir } : {}
   });
   if (args.opts.noWait) {
     const nextCommand = `genex wait ${created.id}${args.opts.json ? " --json" : ""}`;
@@ -20376,7 +20519,7 @@ async function runCharacterAnimate(opts) {
 // src/commands/character-motion.ts
 import { readFile } from "fs/promises";
 import { basename } from "path";
-var VIDEO_SECONDS = [3, 4, 5, 6];
+var VIDEO_SECONDS = [5, 6, 7, 8];
 var MAX_VIDEO_BYTES = 200 * 1024 * 1024;
 async function context2(opts) {
   const token = opts.token ?? await readUserToken(opts.envPath);
@@ -20569,28 +20712,44 @@ async function runCharacterMotions(opts) {
     return;
   }
   const { manifest } = await response.json();
+  const isMovementSlot = (slot) => /^(walk|run|crouch)\.[a-z-]+$/.test(slot);
+  const slotsOf = (key) => Object.entries(manifest.locomotion.slots).filter(([, value]) => value === key).map(([slot]) => slot);
   if (opts.json) {
     writeJson({
       kind: "character_motion",
       stage: "list",
       characterId,
-      clips: manifest.clips.map((clip) => ({
-        key: clip.key,
-        name: clip.name,
-        provider: clip.provider ?? "meshy",
-        duration: clip.duration,
-        slots: Object.entries(manifest.locomotion.slots).filter(([, value]) => value === clip.key).map(([slot]) => slot)
-      }))
+      ...manifest.rig ? { rig: manifest.rig } : {},
+      // Additive since 1.34: the body's URL and the per-clip URL the manifest
+      // already carried, so a local downloader needs no second endpoint.
+      ...manifest.model?.url ? { modelUrl: manifest.model.url } : {},
+      ...manifest.model?.skeletonSignature ? { skeletonSignature: manifest.model.skeletonSignature } : {},
+      clips: manifest.clips.map((clip) => {
+        const slots = slotsOf(clip.key);
+        return {
+          key: clip.key,
+          name: clip.name,
+          provider: clip.provider ?? "meshy",
+          duration: clip.duration,
+          ...clip.url ? { url: clip.url } : {},
+          ...typeof clip.loop === "boolean" ? { loop: clip.loop } : {},
+          ...typeof clip.nominalSpeed === "number" ? { nominalSpeed: clip.nominalSpeed } : {},
+          slots,
+          role: slots.some(isMovementSlot) ? "locomotion" : "action"
+        };
+      })
     });
     return;
   }
   log.plain(c.bold(`${manifest.clips.length} clips on ${characterId}`));
   for (const clip of manifest.clips) {
-    const slots = Object.entries(manifest.locomotion.slots).filter(([, value]) => value === clip.key).map(([slot]) => slot);
+    const slots = slotsOf(clip.key);
     const where = slots.length > 0 ? ` \u2192 ${slots.join(", ")}` : "";
     const source = clip.provider === "uthana" ? c.dim(" generated") : "";
-    log.plain(`  ${clip.key}${source}${where}`);
+    const role = slots.some(isMovementSlot) ? "" : c.dim(" action");
+    log.plain(`  ${clip.key}${source}${role}${where}`);
   }
+  log.dim(`  Per-clip URLs and the body's URL: ${c.cyan(`genex character motions ${characterId} --json`)}`);
 }
 
 // src/commands/animations.ts
@@ -23388,6 +23547,7 @@ var TYPICAL_CREDITS = {
   character_import: 18
   // Uthana auto-rig of your own GLB; the upload itself is free
 };
+var CREATURE_TYPICAL_CREDITS = 46;
 
 // src/index.ts
 var TEXTURE_FLAG_VALUES = ["standard", "detailed", "none", "2k", "4k", "8k"];
@@ -23524,7 +23684,7 @@ ${c.bold("Usage")}
                                      prints the plan before anything is charged.
                                      --locomotion generates the 8-way walk + run set;
                                      --video ./clip.mp4 uses your own footage;
-                                     --duration 3-6 lengthens the reference video for
+                                     --duration 5-8 lengthens the reference video for
                                      multi-beat moves; --action <id-or-query> still
                                      picks a catalog clip.
   genex character motions <id>       List the clips installed on that character.
@@ -23620,8 +23780,8 @@ ${c.bold("Options for the generators (`model` `sfx` `music` `voice` `texture` `i
                        per-plan lists above); each clip is billed.
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --duration <sec>     (sfx, video, music) target clip length in seconds;
-                       (character/creature animate) 3-6 s of reference video for
-                       verbs that route to AI video (default 3) \u2014 longer gives a
+                       (character/creature animate) 5-8 s of reference video for
+                       verbs that route to AI video (default 5) \u2014 longer gives a
                        multi-beat move room to land instead of rushing it.
                        (music: 10-300, default 90 \u2014 a looping gameplay track).
   --transparent        (image) transparent background (alpha) \u2014 for decals/stickers.
@@ -23901,11 +24061,14 @@ ${c.bold("Characters")}
                                      The rigged, game-ready character.     ${cr("character_finalize")}
   genex character "<brief>" --direct-text
                                      One shot, no approval steps.          ${cr("character")}
-  genex creature "<desc>"            A rigged enemy (biped-shaped bodies).  ${cr("character")}
+  genex creature "<desc>"            A rigged enemy (biped-shaped bodies).  ${String(CREATURE_TYPICAL_CREDITS).padStart(3)} cr
+  genex character import <file.glb>  Your own humanoid mesh (or a genex model), ${cr("character_import")}
+                                     auto-rigged by Uthana; the upload is free.
   genex character animate <id> "<verb>" \u2026
                                      Any move, in plain words. --locomotion ${cr("character_motion")} each
-                                     for the 8-way walk+run set; --video
-                                     ./clip.mp4 to use your own footage.
+                                     for the 8-way walk+run set ("walk forward"
+                                     is one clip); --video ./clip.mp4 to use
+                                     your own footage.
   genex character motions <id>       List the clips installed on a character.
   genex animations search "<intent>" Search the ready-made animation library. free
 
@@ -23949,6 +24112,74 @@ Hosting, publishing, multiplayer, remixing and custom domains are the Genex
 platform \u2014 build a game there from one prompt: ${c.cyan("https://genex.games")}
 `;
 var COMMAND_HELP = {
+  character: `${c.bold("genex character")} \u2014 a rigged humanoid body, and every move it makes.
+
+${c.bold("Make one")}
+  genex character "<brief>"                        Three concept candidates (guided flow, step 1).
+  genex character preview <concept-id> --candidate <1|2|3> --user-approved
+                                                   A 3D preview of the chosen one (step 2).
+  genex character finalize <preview-id> --user-approved --approve-remesh <faces>
+                                                   The rigged, game-ready character (step 3).
+  genex character "<brief>" --direct-text          One shot, no approval steps.
+  genex creature "<desc>"                          The one-shot lane with enemy defaults (no controller pack).
+  genex character import <file.glb> [--height <m>] [--no-fingers]
+                                                   Your own humanoid mesh \u2014 or a \`genex model\` GLB \u2014
+                                                   auto-rigged by Uthana. T- or A-pose, feet on the
+                                                   ground, facing +Z, .glb only. The upload is free.
+                                                   The result takes verbs, --locomotion and --video;
+                                                   the Meshy catalog and controller pack do not apply.
+  genex character adopt [<id>]                     (game workspaces) claim a remixed game's character.
+
+${c.bold("Knobs (one shot / preview / finalize)")}
+  --polycount <faces> \xB7 --approve-remesh <faces>   10000-100000 (10k crowds, 20-30k a player body).
+  --texture 2k|4k|8k \xB7 --no-ultra \xB7 --pose a-pose|t-pose \xB7 --height <metres>
+
+${c.bold("Animate it")}
+  genex character animate <id> "<verb>" ["<verb>" \u2026]
+                                                   One clip per verb, in plain words. The server
+                                                   prints the plan (route and clip count per verb)
+                                                   before anything is charged.
+  genex character animate <id> --locomotion        The 8-way walk + run set (16 clips).
+  genex character animate <id> "walk forward"      One movement clip: <walk|run> [direction].
+                                                   "walk" alone is the 8-direction walk set.
+  --video ./clip.mp4                               Use your own footage for that one verb.
+  --duration 5-8                                   Reference-video length for verbs the platform
+                                                   films first (default 5).
+  --action <id-or-query>                           A ready-made library clip instead (Meshy rigs).
+  genex character motions <id> [--json]            What is installed: key, verb, slot, role; --json
+                                                   adds the per-clip and body URLs.
+  genex animations search "<intent>"               The ready-made library. Free.
+
+${c.bold("When a batch does not fully land")}
+  A motion batch that lost a clip completes with what landed and says so \u2014 "22 of 23
+  clips landed \u2014 missing: \u2026" with the exact re-run command; --json carries partial:true.
+  A verb the video model refuses is described instead of filmed, and the batch says which.
+  A Meshy rig refused by pose QA in both rest poses is auto-rigged by Uthana instead: no
+  controller pack, so give it moves with \`character animate <id> --locomotion\`.
+`,
+  model: `${c.bold("genex model")} \u2014 a 3D model (GLB), and the mesh lanes on top of one.
+
+${c.bold("Usage")}
+  genex model "<prompt>" [--image <path|url>]     A GLB from text, or built FROM a reference image.
+  genex model import <file.glb>                    A mesh you already have becomes a model of yours.
+                                                   Free; .glb only, \u2264 64 MB. Then segment / rig /
+                                                   animate / character import take its id.
+  genex model segment <id> [--granularity simple|balanced|detailed]
+                                                   One GLB split into named parts (tripo_part_N).
+  genex model rig <id> [--type biped|quadruped|hexapod|octopod|avian|serpentine|aquatic]
+                                                   A skeleton for any mesh; the plan is auto-detected.
+  genex model animate <rig-id> --preset walk[,run,\u2026]
+                                                   Ready-made clips retargeted onto that rig, per clip.
+
+${c.bold("Quality knobs")}
+  --texture standard|detailed|none \xB7 --geometry detailed \xB7 --quad \xB7 --low-poly
+  --face-limit <n> \xB7 --parts \xB7 --auto-size        Each priced in the quote; say it in one line.
+
+${c.bold("Common")}
+  --out-dir <dir> \xB7 --no-wait (then genex wait <id>) \xB7 --no-download \xB7 --json
+  A humanoid \`genex model\` result is the input to \`genex character import\` \u2014 the route to a
+  rigged body when the character lane's pose QA refuses a mesh.
+`,
   budget: `${c.bold("genex budget")} \u2014 this build's asset allowance, and the live numbers to plan against.
 
 ${c.bold("Usage")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.33.0-dev.690",
+  "version": "1.34.0-dev.692",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-tool-character/SKILL.md

@@ -41,7 +41,7 @@ Pick per role and say so in one line:
   distance, 20000-30000 for a third-person player body, 50000+ only for a
   close-up hero. Moves no cost.
 - `--texture 2k|4k|8k` (preview / one shot): 8k is +5 credits, for close-ups.
-- `--no-ultra` (preview / one shot): −5 credits, less surface detail — stand-ins
+- `--no-ultra` (preview / one shot): −6 credits, less surface detail — stand-ins
   and crowd enemies.
 - `--pose a-pose|t-pose` (one shot): the preferred rest pose.
 - `--height <metres>`: 0.5-3, default 1.7.
@@ -72,6 +72,13 @@ Uthana-rigged body: verbs, `--locomotion` and `--video` work; the Meshy
 catalog and controller pack do not. Non-biped bodies: `npx genex model
 import` + `npx genex model rig`.
 
+The same door takes a `npx genex model` result: a humanoid mesh from the
+model lane, imported here, is a rigged character without the character
+lane's pose QA. If `npx genex character` reports that Meshy's rig failed
+pose QA in both rest poses, the platform already did this for you — the
+character lands rigged by Uthana, with no controller pack, and the terminal
+says so. Animate it exactly like an import.
+
 ## Animating it
 
 Say what the character should DO, in plain words — one clip per verb:
@@ -84,15 +91,34 @@ npx genex character motions <character-id>                        # what is inst
 ```
 
 - `--locomotion` — the full 8-direction walk and run set, 16 clips.
+- A movement request by name: `"walk forward"` is ONE clip in the `walk.forward`
+  slot, `"run"` alone is the 8-direction run set, `"strafe"` is walk left + right.
+  A boss that only walks at the player needs `"walk forward"`, not the set.
 - `--video <file>` — use your own footage as the reference.
-- `--duration 3-6` — a longer reference for a multi-beat move, so it lands instead of rushing. Bills per second.
+- `--duration 5-8` — a longer reference video for a multi-beat move, so it lands instead of rushing. Bills per second.
 - `--action <id|query>` — pick a ready-made clip from the library instead of generating.
 
 `npx genex creature animate <id> "<verb>"` is the same lane for an enemy.
 
-Free and spend-free: the command prints its PLAN before anything is charged.
+Free and spend-free: the command prints its PLAN before anything is charged —
+one line per request naming its route and clip count. READ IT: a phrase that
+reads as movement expands to a set, and a stance or an attack is one clip.
 Show that plan to the user when the cost matters.
 
+Derive the list from the game's states first — idle, the moves it actually
+walks, each attack, hurt, defeat — and request those. A full set nobody's
+controller plays is generation time and load time spent on nothing.
+
+## When a batch does not fully land
+
+A batch is not all-or-nothing. Clips that landed are installed and paid for;
+the terminal says `N of M clips landed — missing: …` with the exact re-run
+command for the missing verbs, and the credits for what did not land come
+back. `--json` carries `partial: true` and the `failures` list; `wait --all`
+marks the row `partial`. A verb the video model would not film is described
+instead, and the batch names it — watch that clip on the character before
+calling it done.
+
 ## The ready-made library
 
 ```bash
@@ -106,20 +132,24 @@ look here first — a library clip costs nothing to generate.
 
 Typical: **32** concept · **41** preview · **29** finalize · **64** one-shot
 character · **46** creature · **18** import (Uthana auto-rig; the upload is
-free) · **46 per clip** for a generated move · **free** for a library search
-(1 credit = $0.01). `--texture 8k` adds 6, `--no-ultra`
+free) · **46 per clip** for a described move, less for a movement clip and a
+little more for one filmed first · **free** for a library search
+(1 credit = $0.01). `--texture 8k` adds 5, `--no-ultra`
 takes 6 off. Live prices and your balance: `npx genex doctor`.
 
 ## Waiting
 
-Character stages take SEVERAL MINUTES server-side. Do not sit in a foreground
-wait: pass `--no-wait`, keep building, then `npx genex wait --all` for one
-status line each and `npx genex wait <id>` to pick one up. **Re-running a
-character command bills a NEW character.**
+Character stages take SEVERAL MINUTES server-side, and so does a motion
+batch — each clip is its own provider job; a 16-clip set is ten minutes or
+more. Do not sit in a foreground wait: pass `--no-wait`, keep building, then
+`npx genex wait --all` for one status line each and `npx genex wait <id>` to
+pick one up. **Re-running a character command bills a NEW character.**
 
 ## Troubleshooting
 
 - **A four-legged prompt came back upright** — the rig here is biped-shaped only. Generate the body with `npx genex model` and rig it with `npx genex model rig --type quadruped` (see `$genex-tool-model`), or ship it static and animate in code.
+- **"Rigged by Uthana instead" on a `character` / `creature` result** — Meshy's rig failed pose QA in both rest poses (armored and heavily clothed bodies do), so the platform auto-rigged the mesh. Nothing to redo: give it moves with `npx genex character animate <id> --locomotion` and plain-word verbs; the Meshy catalog does not apply.
+- **`character animate` says the character is still generating** — wait for it first (`npx genex wait <id>`); the animate door only opens on a finished rig.
 - **Rigs rest facing +Z.** Set yaw explicitly when you place one, and never mirror a skinned mesh with a negative scale — it inverts the whole thing silently.
 - **Out of credits** — the error prints balance, price and refill date. Relay it; don't retry.
 - **Anything else** — `npx genex doctor`.

package/templates/skills/genex-tool-workflow/SKILL.md

@@ -60,10 +60,11 @@ credits get wasted.
 
 ## Credits
 
-One balance across everything. Typical prices: texture 3 · sfx 5 · image 8 ·
-voice 10 · rig 20 · model 25 · music 40 · video 20 · character 50 · a generated
-animation clip 26. **Live prices: `npx genex doctor`** — they are set
-server-side and these are only typical.
+One balance across everything, and ONE source for what things cost:
+**`npx genex doctor`** (or `npx genex budget`) prints the live price per lane
+and your balance. Prices are set server-side and change without a release, so
+no card types them — the numbers in `npx genex --help` are typical defaults,
+and a quote printed by a command is the exact charge.
 
 - A FAILED generation is refunded automatically. You never pay for something that did not arrive.
 - Out of credits is a plain refusal that prints your balance, the price, and the date credits refill. Relay those facts to the user and carry on with something else — do not retry.