@genex-ai/cli-demo 0.90.0-dev.227 → 0.92.0-dev.229

package/dist/index.js

@@ -252,7 +252,7 @@ var CONTRACT_END = "<!-- genex:contract:end -->";
 var GENEX_CONTRACT_BLOCK = `${CONTRACT_BEGIN}
 # Genex build contract (always in effect for this game)
 
-Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skybox\` \xB7 \`sfx\` \xB7 \`music\` \xB7 \`voice\` \xB7 \`texture\` \xB7 \`image\` (\`--edit\` \xB7 \`--inpaint\` \xB7 \`--glass\` \xB7 \`--clean\` \xB7 \`--upscale\`) \xB7 \`video\` \xB7 rigged \`character\` / \`creature\` \xB7 the pixel toolbox \`ui extract|masks|plate|text-color|trim|audit\` \xB7 vendored \`controller character|car|drone|touch|quality\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\`. Full options: \`npx genex --help\`. Task\u2192lane routing lives in the \`genex-game-director\` skill's routing map \u2014 re-load it whenever you're unsure which lane owns a task.
+Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skybox\` \xB7 \`sfx\` \xB7 \`music\` \xB7 \`voice\` \xB7 \`texture\` \xB7 \`image\` (\`--edit\` \xB7 \`--inpaint\` \xB7 \`--glass\` \xB7 \`--clean\` \xB7 \`--upscale\`) \xB7 \`video\` \xB7 rigged \`character\` / \`creature\` \xB7 \`character animate <id> "<verb>"\` (also \`creature animate\`; \`--locomotion\` for the 8-way movement set, \`--video\` for your own footage) \xB7 the pixel toolbox \`ui extract|masks|plate|text-color|trim|audit\` \xB7 vendored \`controller character|car|drone|touch|quality\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\`. Full options: \`npx genex --help\`. Task\u2192lane routing lives in the \`genex-game-director\` skill's routing map \u2014 re-load it whenever you're unsure which lane owns a task.
 
 1. Load the \`genex-game-director\` skill and follow it end to end before any game code. After ANY context compaction or session resume, re-read this file and \`DESIGN.md\`, re-load the skill for the stage you are executing, and continue from the Build plan's \`Now:\` line \u2014 never from memory alone.
 2. The design interview always happens: 2\u20134 build-forking questions, ONE round, before DESIGN.md is written \u2014 even when the request already names the game (then it confirms the pitch). Ask with your built-in question tool with clickable answer options when you have one; a short numbered list in plain chat otherwise. Only after asking may you proceed on stated assumptions if the player stays silent; record each as "assumed \u2014 player didn't answer" in DESIGN.md \u2192 Decisions.
@@ -265,13 +265,16 @@ Your capabilities (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skyb
 9. Never draw a rectangular backing plate behind bars, digits, or icons \u2014 in sprites or CSS. Ornament lives on the widget's own silhouette; a truly needed shaped plate comes from \`npx genex ui plate\`.
 10. Fonts: the brief's display + body pair comes from the menu skill's genre table (or carries a one-line stated reason) and is LOADED for real in \`index.html\`.
 11. Never park ready work behind a question, and never stall on an unanswered one \u2014 decide, state the decision in chat, record it, keep building.
-12. Wire-in floors before any publish and before ending a session: sprite HUD wired (or the recorded CSS lane finished), menu video playing (or its recorded still fallback), logotype placed, fonts loaded, Escape pause, branded loader. Run \`npx genex wait\` on every generation you enqueued and wire what landed \u2014 never park landed assets.
-13. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
-14. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification.
+12. Wire-in floors before any publish and before ending a session: sprite HUD wired (or the recorded CSS lane finished), menu video playing (or its recorded still fallback), logotype placed, fonts loaded, Escape pause, branded loader, the player wearing the game's own generated character (or DESIGN.md recording why it isn't). Run \`npx genex wait\` on every generation you enqueued and wire what landed \u2014 never park landed assets.
+13. The player's body is the game's own generated character (\`npx genex character "<look>"\` \u2192 \`npx genex controller character --character <id>\`), enqueued with your first art actions, not after them. It applies wherever a human body appears on screen \u2014 first-person included, the moment remotes, a look-down body, a shadow, or a menu portrait shows one. The profile VRM avatar is the FALLBACK: a temporary body while the character renders (say in one plain line that it's temporary), or the stand-in when generation genuinely could not happen \u2014 out of credits, failed, unverified; record which in DESIGN.md as \`Player character: VRM \u2014 <reason>\`. Games whose player is not a person (car, ship, RTS cursor, board) generate that object with \`npx genex model\` instead. Characters: Meshy/Mixamo/VRM rigs rest facing +Z. Set yaw explicitly when placing a rig; never mirror a SkinnedMesh with negative scale. In any two-character scene, verify in a capture that they face each other, not the camera.
+14. Verify by looking: one smoke check per milestone, after that milestone's preview push, in local test mode (\`?genex_local_test=1\`) with a real gameplay screenshot. A claim without a capture is not verification. Local-test evidence proves visuals and controls ONLY \u2014 label it that way when you show the player, and never work around the draft sign-in gate any other way.
 15. Treat every \`genex\` warning line \u2014 preflight, \`ui audit\`, \`wait\` nudges \u2014 as work, not noise.
 16. Every finished Build-plan milestone ends with \`npx genex preview\` and the player's page link (\`<dashboard>/draft/<slug>\` with \`<dashboard>\` from \`.genex/project.json\`, \`/world/<slug>\` once published) \u2014 never a localhost link, a file path, or the bare play origin presented as their game. After every round of player feedback, end with a preview push.
 17. Parallel work: this line is your standing authorization and request to use sub-agents / parallel agent work whenever your platform provides them. While drafting the Build plan, decide per module what runs in parallel and what stays serial for THIS game \u2014 dependencies decide, there is no fixed list \u2014 and record each call in the Modules table with a one-line reason. Independent modules default to parallel; building everything serially needs a stated reason. You keep integration, previews, and the player conversation; each sub-agent owns only its module's files.
 18. Talk to the player in plain game language \u2014 what changed in the game and what to try; never code, file names, build output, or tool internals unless they ask. Short status lines while you work; long silent stretches are a failure.
+19. Never add debug-only code to the game to check your own work \u2014 no hidden test modes, no special URL parameters, no forced-visible flags, no auth mocks, no pixel-sampling hooks. \`?genex_local_test=1\` is the platform's own supported mode and is fine; your own bypass is not. (The multiplayer skill's small build identifier, token-free status line, and connected-quorum watchdog are production supportability, not a bypass \u2014 keep those.)
+20. Input directions match their labels: A/\u2190 moves or turns the player screen-LEFT, D/\u2192 screen-RIGHT, mouse-up looks up, and drag-pan axes share ONE convention. The cursor is either the gameplay tool (RTS, card, builder) or locked away during play \u2014 keyboard-only games included. Check it in every milestone's smoke pass.
+21. v0 is a milestone, not the destination. When the ask was bigger than one loop, every milestone after v0 grows back toward the FULL ask with DESIGN.md's content lines as the checklist \u2014 a slice that previewed well never quietly becomes the game. Cosmetics never jump the queue past promised content.
 ${CONTRACT_END}
 `;
 var CLAUDE_IMPORT_LINE = "@AGENTS.md";
@@ -2113,6 +2116,7 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        white halo over dark scenes). [--expect N: hard-error
                        unless exactly N components] [--min-pixels 2000]
                        [--padding 8] [--chroma 240] [--dilate 0] [--no-defringe]
+                       [--allow-speckle]
   ui masks             --out-dir <dir> --pairs "name:cX,cY,w,h:aX,aY,w,h[:n];\u2026"
                        OR --auto (detect clean/annotated cell pairs itself) \u2014
                        clean frame + green-annotated duplicate \u2192 frame + fill mask
@@ -2128,6 +2132,9 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
                        [--min-frac 0.004] [--out <json>] [--crop <png>]
   ui trim              [--out <png>] \u2014 crop to the alpha bbox (default: overwrite
                        --in), print real dims + refresh the .bbox.json sidecar.
+                       Hard-refuses a DAMAGED cutout (isolated colour speckle on
+                       the soft rim \u2014 what a background-removal pass does to an
+                       image that was already transparent). [--allow-speckle]
   ui seams             measure a tiling texture's wrap seam (opposite edges vs
                        interior detail) \u2192 ratio + verdict as JSON; nonzero exit on
                        a visible seam. [--seam-tolerance 3]
@@ -2139,7 +2146,9 @@ var UI_USAGE = `${c.bold("Options for `ui` (all tools read --in <png path or htt
   ui audit             mechanical HUD-wiring scan (no --in): mask\u2194frame pairing
                        mismatches (recorded crops disagree \u2014 PROVABLE, exit 1),
                        white-painted meter troughs (baked sheet-white inside a
-                       fill channel \u2014 PROVABLE, exit 1), loosened-check stamps,
+                       fill channel \u2014 PROVABLE, exit 1), damaged cutouts (colour
+                       speckle on a wired sprite's rim \u2014 PROVABLE, exit 1),
+                       loosened-check stamps,
                        extracted-but-never-wired sprites, generated-but-
                        unreferenced masks, naive JS %-width fills, phones-
                        preload-video heuristic. Everything but the two provable
@@ -2422,6 +2431,15 @@ async function uiExtract(opts, log) {
     if (inputMode === "chroma" && opts.defringe !== false) {
       defringed = defringeAgainstMatte(out) > 0;
     }
+    const speckle = rimSpeckleRatio(out);
+    if (speckle && speckle.ratio > SPECKLE_MAX_RATIO && !opts.allowSpeckle) {
+      fail(speckleRefusal(name, speckle.ratio), {
+        input,
+        sprite: name,
+        speckleRatio: Number(speckle.ratio.toFixed(4)),
+        rimPixels: speckle.sampled
+      });
+    }
     const outPath = path11.join(outDir, `${name}.png`);
     await writePng(outPath, out);
     const sidecar = {
@@ -3180,13 +3198,30 @@ async function uiTrim(opts, log) {
     h: bbox.maxY - bbox.minY + 1
   };
   const trimmed = cropPng(png, cropBox);
+  const speckle = rimSpeckleRatio(trimmed);
+  if (speckle && speckle.ratio > SPECKLE_MAX_RATIO && !opts.allowSpeckle) {
+    fail(speckleRefusal("this image", speckle.ratio), {
+      input,
+      speckleRatio: Number(speckle.ratio.toFixed(4)),
+      rimPixels: speckle.sampled
+    });
+  }
   await writePng(outPath, trimmed);
   const sidecar = computeBBoxes(trimmed);
+  const speckleAllowed = !!(speckle && speckle.ratio > SPECKLE_MAX_RATIO);
   const sidecarPath = outPath.replace(/\.png$/i, "") + ".bbox.json";
-  await fs11.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2));
+  await fs11.writeFile(
+    sidecarPath,
+    JSON.stringify(speckleAllowed ? { ...sidecar, speckleAllowed: true } : sidecar, null, 2)
+  );
   log.success(
     `Trimmed ${png.width}x${png.height} \u2192 ${trimmed.width}x${trimmed.height} (${outPath}).`
   );
+  if (speckleAllowed) {
+    log.warn(
+      "Shipped with --allow-speckle: this cutout is damaged and the override is stamped in its sidecar. Eyeball it over a bright background before it reaches the player."
+    );
+  }
   process.stdout.write(
     `${JSON.stringify({
       out: outPath,
@@ -3195,7 +3230,9 @@ async function uiTrim(opts, log) {
       aspectRatio: sidecar.aspectRatio,
       outerBBox: sidecar.outerBBox,
       innerBBox: sidecar.innerBBox,
-      sidecar: sidecarPath
+      sidecar: sidecarPath,
+      ...speckle ? { speckleRatio: Number(speckle.ratio.toFixed(4)) } : {},
+      ...speckleAllowed ? { speckleAllowed: true } : {}
     })}
 `
   );
@@ -3292,6 +3329,51 @@ async function uiPlate(opts, log) {
 `
   );
 }
+var SPECKLE_RIM_ALPHA_MIN = 16;
+var SPECKLE_RIM_ALPHA_MAX = 220;
+var SPECKLE_CHROMA_EXCESS = 60;
+var SPECKLE_MIN_SAMPLE = 200;
+var SPECKLE_MAX_RATIO = 0.02;
+function rimSpeckleRatio(png) {
+  const { width: W, height: H, data } = png;
+  if (W < 3 || H < 3) return null;
+  const chroma = new Uint8Array(W * H);
+  for (let i = 0; i < W * H; i++) {
+    const o = i * 4;
+    const r = data[o];
+    const g = data[o + 1];
+    const b = data[o + 2];
+    chroma[i] = Math.max(r, g, b) - Math.min(r, g, b);
+  }
+  const neighbourhood = [];
+  let sampled = 0;
+  let speckled = 0;
+  for (let y = 1; y < H - 1; y++) {
+    for (let x = 1; x < W - 1; x++) {
+      const i = y * W + x;
+      const a = data[i * 4 + 3];
+      if (a <= SPECKLE_RIM_ALPHA_MIN || a >= SPECKLE_RIM_ALPHA_MAX) continue;
+      sampled++;
+      neighbourhood.length = 0;
+      for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) neighbourhood.push(chroma[(y + dy) * W + (x + dx)]);
+      }
+      neighbourhood.sort((p, q) => p - q);
+      if (chroma[i] - neighbourhood[4] > SPECKLE_CHROMA_EXCESS) speckled++;
+    }
+  }
+  if (sampled < SPECKLE_MIN_SAMPLE) return null;
+  return { ratio: speckled / sampled, sampled };
+}
+function speckleRefusal(label, ratio) {
+  return [
+    `Damaged cutout \u2014 ${(ratio * 100).toFixed(1)}% of ${label}'s soft edge is isolated colour speckle (want <= ${(SPECKLE_MAX_RATIO * 100).toFixed(0)}%).`,
+    "A background-removal pass over an image that was ALREADY transparent re-keys every edge and sprays colour noise along it. Trimming or defringing cannot fix this.",
+    "  -> From `genex image --clean`? Ship the `--transparent` original instead.",
+    "  -> Source really had a background? Re-clean with `--bg-mode matte` (soft edges).",
+    "  Override (stamped in the output): --allow-speckle"
+  ].join("\n");
+}
 var DEFRINGE_BAND_PX = 2;
 function defringeAgainstMatte(png, matte = { r: 255, g: 255, b: 255 }) {
   const { width: W, height: H, data } = png;
@@ -3374,7 +3456,8 @@ function defringeAgainstMatte(png, matte = { r: 255, g: 255, b: 255 }) {
 }
 var HARD_AUDIT_KINDS = /* @__PURE__ */ new Set([
   "mask-frame-mismatch",
-  "white-trough"
+  "white-trough",
+  "cutout-speckle"
 ]);
 var TROUGH_OPAQUE_MIN_ALPHA = 200;
 var TROUGH_WHITE_MIN = 235;
@@ -3453,7 +3536,7 @@ async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
     } catch {
     }
   }
-  const referenced = (basename) => sources.some((s) => s.text.includes(basename));
+  const referenced = (basename2) => sources.some((s) => s.text.includes(basename2));
   const findings = [...viewportFindings];
   const assetFiles = await walkFiles(absAssets);
   const metaByName = /* @__PURE__ */ new Map();
@@ -3535,6 +3618,22 @@ async function collectUiAuditFindings(assetDir, srcDir, cwd = process.cwd()) {
       }
     }
   }
+  for (const [base, p] of pngByBase) {
+    if (/-mask\.png$/.test(base)) continue;
+    if (!referenced(base)) continue;
+    let png;
+    try {
+      png = PNG2.sync.read(await fs11.readFile(p));
+    } catch {
+      continue;
+    }
+    const speckle = rimSpeckleRatio(png);
+    if (!speckle || speckle.ratio <= SPECKLE_MAX_RATIO) continue;
+    findings.push({
+      kind: "cutout-speckle",
+      message: `${base}: ${(speckle.ratio * 100).toFixed(1)}% of the soft edge is isolated colour speckle (want <= ${(SPECKLE_MAX_RATIO * 100).toFixed(0)}%) \u2014 a background-removal pass re-keyed edges that were already transparent and sprayed colour noise along them. Nothing downstream repairs it: ship the \`--transparent\` original, or re-clean the true source with \`--bg-mode matte\`. Do not ship this sprite.`
+    });
+  }
   const loosenedNames = [...metaByName.entries()].filter(([, meta]) => meta.loosened).map(([name]) => name);
   if (loosenedNames.length > 0) {
     findings.push({
@@ -3866,13 +3965,109 @@ async function inlineLocalImage(filePath, flag) {
   const mime = IMAGE_MIME_BY_EXT[path13.extname(filePath).toLowerCase()] ?? "image/png";
   return { ok: true, dataUri: `data:${mime};base64,${bytes.toString("base64")}` };
 }
-var SKYBOX_ENVIRONMENT_SUFFIX = ". Pure environment: sky, clouds, atmosphere, distant horizon haze. No buildings, no structures, no trees, no objects, no ground detail.";
+var SKYBOX_ENVIRONMENT_SUFFIX = ". The image contains ONLY sky: cloud, atmosphere, light, weather and distant haze at the horizon. Every structure, object, plant and ground surface is outside the frame.";
 var SKYBOX_PROMPT_MAX = 2e3;
+var SKYBOX_STRUCTURE_NOUNS = [
+  "building",
+  "buildings",
+  "house",
+  "houses",
+  "hut",
+  "huts",
+  "cabin",
+  "cabins",
+  "tower",
+  "towers",
+  "castle",
+  "castles",
+  "cathedral",
+  "cathedrals",
+  "church",
+  "churches",
+  "temple",
+  "temples",
+  "shrine",
+  "shrines",
+  "monastery",
+  "palace",
+  "fortress",
+  "citadel",
+  "ruin",
+  "ruins",
+  "city",
+  "cityscape",
+  "skyline",
+  "town",
+  "village",
+  "settlement",
+  "street",
+  "streets",
+  "road",
+  "roads",
+  "courtyard",
+  "plaza",
+  "bridge",
+  "bridges",
+  "wall",
+  "walls",
+  "gate",
+  "gates",
+  "fence",
+  "fences",
+  "pillar",
+  "pillars",
+  "column",
+  "columns",
+  "statue",
+  "statues",
+  "monument",
+  "obelisk",
+  "spire",
+  "spires",
+  "rooftop",
+  "rooftops",
+  "tree",
+  "trees",
+  "forest",
+  "jungle",
+  "ship",
+  "ships",
+  "boat",
+  "boats",
+  "car",
+  "cars",
+  "vehicle",
+  "vehicles",
+  "person",
+  "people",
+  "figure",
+  "figures",
+  "character",
+  "characters",
+  "creature",
+  "creatures",
+  "dragon",
+  "banner",
+  "banners",
+  "flag",
+  "flags",
+  "torch",
+  "torches",
+  "lamp",
+  "lamps"
+];
+var SKYBOX_NOUN_RE = new RegExp(`\\b(${SKYBOX_STRUCTURE_NOUNS.join("|")})\\b`, "gi");
+function skyboxStructureNouns(prompt) {
+  const found = /* @__PURE__ */ new Set();
+  for (const m of prompt.matchAll(SKYBOX_NOUN_RE)) found.add(m[1].toLowerCase());
+  return [...found];
+}
 function applySkyboxGuard(prompt, raw) {
-  if (raw) return { prompt, guarded: false };
+  if (raw) return { prompt, guarded: false, nouns: [] };
+  const nouns = skyboxStructureNouns(prompt);
   const guarded = `${prompt}${SKYBOX_ENVIRONMENT_SUFFIX}`;
-  if (guarded.length > SKYBOX_PROMPT_MAX) return { prompt, guarded: false };
-  return { prompt: guarded, guarded: true };
+  if (guarded.length > SKYBOX_PROMPT_MAX) return { prompt, guarded: false, nouns };
+  return { prompt: guarded, guarded: true, nouns };
 }
 function buildGenOptions(kind, opts) {
   const options = { ...opts.generationOptions };
@@ -3927,6 +4122,23 @@ async function runGenerate(kind, opts) {
     return;
   }
   const skyboxGuard = kind === "skybox" ? applySkyboxGuard(typedPrompt, opts.raw) : void 0;
+  if (skyboxGuard && skyboxGuard.nouns.length > 0) {
+    log.error(
+      `A skybox is sky only \u2014 this prompt names ${skyboxGuard.nouns.join(", ")}.`
+    );
+    log.plain(
+      [
+        "  Structures painted into a sky render at infinite distance: they never get closer",
+        "  as the player moves, and they read as broken the moment the camera strafes.",
+        `  ${c.cyan("\u2192")} Build them as scene geometry (${c.cyan("npx genex model")}); describe only light, colour,`,
+        "    cloud, weather and time of day here.",
+        `  ${c.cyan("\u2192")} Genuinely want it painted into the sky (a space-station panorama for a scene`,
+        `    with no world geometry)? Re-run with ${c.cyan("--raw")}.`
+      ].join("\n")
+    );
+    process.exitCode = 1;
+    return;
+  }
   let prompt = skyboxGuard?.prompt ?? typedPrompt;
   if (kind === "image" && opts.glass) {
     const conflict = opts.transparent ? "--transparent" : opts.removeBackground ? "--remove-bg" : opts.editUrl ? "--edit" : opts.cleanUrl ? "--clean" : opts.upscaleUrl ? "--upscale" : opts.noWait ? "--no-wait" : void 0;
@@ -4264,7 +4476,10 @@ var KIND_WAIT_TIMEOUT_MS = {
   character_concept: 15 * 60 * 1e3,
   character_preview: 30 * 60 * 1e3,
   character: 30 * 60 * 1e3,
-  character_animation: 20 * 60 * 1e3
+  character_animation: 20 * 60 * 1e3,
+  // Per clip this lane is fast (locomotion ~2s, video ~51s, described ~130s) —
+  // the BATCH is what takes time. A 20-clip standard set is the sizing case.
+  character_motion: 30 * 60 * 1e3
 };
 var waitTimeoutFor = (kind) => KIND_WAIT_TIMEOUT_MS[kind] ?? WAIT_TIMEOUT_MS;
 var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed"]);
@@ -4380,7 +4595,8 @@ function printHint(kind, view, files, log) {
     character_concept: "Show all three concept candidates to the user and wait for an explicit selection.",
     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_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.`
   };
   log.dim(`  ${hint[kind]}`);
   log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
@@ -4660,6 +4876,14 @@ async function printPipelineStatePreflight(log, cwd = process.cwd()) {
         );
       }
     }
+    if (!/player character:/i.test(design)) {
+      const hasCharacter = await fs14.access(path14.join(cwd, "public", "assets", "meshy-character.json")).then(() => true, () => false);
+      if (!hasCharacter && await loadsPlayerBody(cwd)) {
+        warnings.push(
+          `Player character is the stock avatar \u2014 no generated character is wired. The game's own generated character is the player's body wherever a human body appears on screen, first-person included (genex-ai-character). Generate it, or record "Player character: VRM \u2014 <reason>" in DESIGN.md (no human body in this game / out of credits / player declined).`
+        );
+      }
+    }
     for (const w of warnings) log.warn(w);
   } catch {
   }
@@ -4687,6 +4911,21 @@ async function hasHudLikeDom(cwd) {
   }
   return false;
 }
+async function loadsPlayerBody(cwd) {
+  const BODY_LOADERS = /\bloadPlayerCharacter\s*\(|\bloadVrm(?:Clone)?\s*\(/;
+  try {
+    const entries = await fs14.readdir(path14.join(cwd, "src"), { recursive: true });
+    for (const rel of entries) {
+      if (rel.includes("node_modules")) continue;
+      if (rel.split(path14.sep)[0] === "controllers" || rel.startsWith("controllers/")) continue;
+      if (!/\.(ts|tsx|js|jsx)$/.test(rel)) continue;
+      const text = await fs14.readFile(path14.join(cwd, "src", rel), "utf8").catch(() => "");
+      if (BODY_LOADERS.test(text)) return true;
+    }
+  } catch {
+  }
+  return false;
+}
 async function hasExtractionSidecars(cwd) {
   try {
     const entries = await fs14.readdir(path14.join(cwd, "public"), { recursive: true });
@@ -15372,9 +15611,14 @@ var CONTROLLER_FILE_SETS = {
       "character/animation-packs.ts",
       "character/motion-actions.ts",
       "character/meshy/meshy-loader.ts",
+      // The player's body, resolved once: this game's own generated character
+      // when it has one, the visiting player's avatar when it doesn't. ONE
+      // shape for both lanes, so a character that lands at hour 2 is a file
+      // drop and not a rewrite of the boot path written at hour 0.
+      "character/player-character.ts",
       "character/presets.ts",
       // VRM avatar support (three-vrm): load + retarget the UAL clips + auto-fit
-      // the capsule + optional foot IK. Owner's avatar replaces the old mannequin.
+      // the capsule + optional foot IK — the FALLBACK body's lane.
       "character/vrm/vrm-loader.ts",
       "character/vrm/vrm-retarget.ts",
       "character/vrm/capsule-fit.ts",
@@ -15383,22 +15627,27 @@ var CONTROLLER_FILE_SETS = {
       NOTICE
     ],
     // The FALLBACK VRM is written to public/assets/avatar.vrm at install time by
-    // installOwnerAvatar (owner's avatar, or the bundled default) — so it is NOT
-    // a static manifest asset; at runtime the game loads the playing user's own
-    // avatar (user.avatarUrl from the embed identity, AG-804) and this file
-    // covers local dev + load failures. animation-library.glb (the 12-clip core)
-    // still is a manifest asset; extra clips arrive via `genex controller anims`
-    // into public/assets/anims/.
+    // installFallbackAvatar (the bundled CC0 default) — so it is NOT a static
+    // manifest asset; at runtime the game loads the playing user's own avatar
+    // (user.avatarUrl from the embed identity, AG-804) and this file covers
+    // local dev + load failures. It is only ever the FALLBACK body: the player
+    // is this game's own generated character whenever it has one.
+    // animation-library.glb (the 12-clip core) still is a manifest asset; extra
+    // clips arrive via `genex controller anims` into public/assets/anims/.
     assets: ["assets/animation-library.glb"],
     skill: "genex-threejs-character-controller",
+    // ONE sketch, with or without --character. The lane is a runtime decision
+    // inside loadPlayerCharacter, never a code edit the agent has to remember
+    // to make once the generated character lands.
     sketch: [
       `const physics = await PhysicsWorld.create();`,
-      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk \u2014 the player's own avatar`,
-      `const { scene, vrm } = await loadVrm(user.avatarUrl ?? "./assets/avatar.vrm").catch(() => loadVrm("./assets/avatar.vrm"));`,
-      `const clips = await loadCharacterClips(vrm); // core library + every genex-controller-anims pack`,
-      `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...capsuleFromModel(scene), position: { x: 0, y: 2, z: 0 } });`,
-      `character.root.add(scene); const anims = new CharacterAnimations(scene, clips);`,
-      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); vrm.update(dt);`
+      `const { user } = await waitForPlayer(); // @genex-ai/embed-sdk`,
+      `const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl }); // this game's character, else the avatar fallback`,
+      `const fit = capsuleFromModel(player.scene);`,
+      `const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...fit, position: { x: 0, y: 2, z: 0 } });`,
+      `character.root.add(player.scene); player.scene.position.y = fit.modelOffsetY;`,
+      `const anims = new CharacterAnimations(player.scene, player.clips, { locomotionProfile: player.locomotionProfile });`,
+      `addEventListener("pointerdown", () => anims.playOneShot("Punch_Jab")); // per frame: anims.update(character, dt); player.update(dt);`
     ]
   },
   car: {
@@ -15557,8 +15806,7 @@ async function runController(opts) {
         return;
       }
     } else {
-      const token = opts.token !== void 0 ? opts.token : await readUserToken();
-      await installOwnerAvatar({ root, srcDir, apiUrl: getApiUrl(opts.apiUrl), token, log });
+      await installFallbackAvatar({ root, srcDir, log });
     }
     log.plain("");
   }
@@ -15577,16 +15825,18 @@ async function runController(opts) {
   log.plain(
     kind === "touch" ? `  ${stepOffset + 2}. Wiring sketch (create behind a touch check; read per frame):` : `  ${stepOffset + 2}. Wiring sketch (controllers update BEFORE the physics step):`
   );
-  const sketch = kind === "character" && opts.character ? [
-    `const physics = await PhysicsWorld.create();`,
-    `const native = await loadMeshyCharacter("./assets/meshy-character.json");`,
-    `const fit = capsuleFromModel(native.scene); const character = new CharacterController(physics.world, camera, { ...characterPresets["default"].options, ...fit, position: { x: 0, y: 2, z: 0 } });`,
-    `character.root.add(native.scene); const anims = new CharacterAnimations(native.scene, native.clips, { locomotionProfile: native.locomotionProfile });`,
-    `physics.onBeforeStep(() => character.update(dt, input)); // Rapier owns movement; then anims.update(character, dt)`
-  ] : set.sketch;
-  for (const line of sketch) {
+  for (const line of set.sketch) {
     log.dim(`       ${line}`);
   }
+  if (kind === "character" && !await exists3(path17.join(root, ASSETS_DEST, "meshy-character.json"))) {
+    log.plain("");
+    log.plain(
+      `  ${stepOffset + 3}. This game has no generated character yet \u2014 ${c.cyan(
+        'npx genex character "<look>"'
+      )} makes the player's real body;`
+    );
+    log.plain("     the avatar above is only the fallback until it lands. No code change when it does.");
+  }
 }
 async function installMeshyCharacterManifest(args) {
   const response = await apiFetch(
@@ -15618,6 +15868,7 @@ async function installMeshyCharacterManifest(args) {
 `
   );
   args.log.dim(`  public/assets/meshy-character.json (${args.characterId}, current revision)`);
+  args.log.success("This game's generated character is now the player's body \u2014 picked up on the next reload, no code change needed.");
   const pack2 = manifest.controllerPack;
   if (typeof pack2?.key === "string" && typeof pack2.version === "number") {
     args.log.success(`Meshy controller pack ${pack2.key} v${pack2.version}`);
@@ -15747,36 +15998,12 @@ function assertCompleteMeshyControllerPack(manifest) {
     incompletePack(`${pack2.key} v${pack2.version} fingerprint does not match its action bindings.`);
   }
 }
-async function installOwnerAvatar(args) {
-  const { root, srcDir, apiUrl, token, log } = args;
+async function installFallbackAvatar(args) {
+  const { root, srcDir, log } = args;
   const dest = path17.join(root, ASSETS_DEST, "avatar.vrm");
   await fs17.mkdir(path17.dirname(dest), { recursive: true });
-  if (token) {
-    try {
-      const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
-        headers: { Authorization: `Bearer ${token}` }
-      });
-      if (res.ok) {
-        const me = await res.json();
-        if (me.vrmUrl) {
-          const vrmRes = await fetch(me.vrmUrl);
-          if (vrmRes.ok) {
-            const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs17.writeFile(dest, buf);
-            log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
-            return;
-          }
-        }
-      }
-      log.dim("  couldn't fetch your avatar; using the bundled default.");
-    } catch {
-      log.dim("  avatar fetch failed (offline?); using the bundled default.");
-    }
-  }
   await fs17.copyFile(path17.join(srcDir, "assets", "default-avatar.vrm"), dest);
-  log.dim(
-    token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
-  );
+  log.dim("  public/assets/avatar.vrm (fallback avatar \u2014 bundled CC0 default)");
 }
 async function exists3(p) {
   try {
@@ -16263,6 +16490,226 @@ 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 MAX_VIDEO_BYTES = 200 * 1024 * 1024;
+async function context2(opts) {
+  const token = opts.token ?? await readUserToken(opts.envPath);
+  if (!token) return null;
+  const project = await readProject();
+  return { token, apiUrl: getApiUrl(opts.apiUrl ?? project?.apiUrl) };
+}
+async function readVideo(path19, log) {
+  let bytes;
+  try {
+    bytes = await readFile(path19);
+  } catch {
+    log.error(`Can't read ${path19}.`);
+    return null;
+  }
+  if (bytes.byteLength > MAX_VIDEO_BYTES) {
+    log.error(`${basename(path19)} is ${(bytes.byteLength / 1e6).toFixed(0)} MB \u2014 the limit is ${MAX_VIDEO_BYTES / 1e6} MB.`);
+    return null;
+  }
+  return bytes;
+}
+async function uploadVideo(apiUrl, token, characterId, path19, bytes, log) {
+  const contentType = /\.mov$/i.test(path19) ? "video/quicktime" : "video/mp4";
+  const minted = await apiFetch(
+    `${apiUrl}/api/characters/${encodeURIComponent(characterId)}/motions/video-url`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ bytes: bytes.byteLength, contentType })
+    }
+  );
+  if (printedStructuredError(minted)) return null;
+  if (!minted.ok) {
+    log.error(`Couldn't start the video upload (HTTP ${minted.status}).`);
+    return null;
+  }
+  const { uploadUrl, videoUrl } = await minted.json();
+  log.dim(`  uploading ${basename(path19)} (${(bytes.byteLength / 1e6).toFixed(1)} MB)\u2026`);
+  const put = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType, "Content-Length": String(bytes.byteLength) },
+    body: new Uint8Array(bytes)
+  });
+  if (!put.ok) {
+    log.error(`Video upload failed (HTTP ${put.status}).`);
+    return null;
+  }
+  return videoUrl;
+}
+function printPlan(plan, log, creature) {
+  log.plain(c.bold(creature ? "Creature animation plan" : "Animation plan"));
+  for (const item of plan.items) {
+    const count = item.clips > 1 ? ` (${item.clips} clips)` : "";
+    log.plain(`  \xB7 ${c.bold(item.request)}${count} \u2014 ${item.explanation}`);
+    if (item.supersededSlots.length > 0) {
+      log.plain(
+        `      ${c.dim(`${item.supersededSlots.join(", ")} stay on the reviewed pack clips \u2014 those slots are pinned.`)}`
+      );
+    }
+  }
+  if (plan.secondsApplied === false) {
+    log.plain(
+      `  ${c.dim("--duration sets the reference-video length; none of these verbs took the video route, so it did nothing.")}`
+    );
+  }
+  log.plain("");
+  if (plan.credits > 0) log.dim(`  ${plan.totalClips} clips \xB7 ${plan.credits} credits`);
+  else log.dim(`  ${plan.totalClips} clips`);
+  log.plain("");
+}
+async function runCharacterAnimateMotion(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const characterId = opts.characterId?.trim();
+  if (!characterId) {
+    log.error("Missing character id.");
+    process.exitCode = 1;
+    return;
+  }
+  const verbs = (opts.verbs ?? []).map((v) => v.trim()).filter(Boolean);
+  if (verbs.length === 0 && !opts.locomotion) {
+    log.error(
+      `Say what the character should do. ${c.cyan(`genex character animate ${characterId} "overhead slam"`)}`
+    );
+    log.dim(`  Or generate the movement set: ${c.cyan(`genex character animate ${characterId} --locomotion`)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.video && verbs.length !== 1) {
+    log.error("--video applies to exactly one verb \u2014 name the action the footage shows.");
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.duration !== void 0 && !VIDEO_SECONDS.includes(opts.duration)) {
+    log.error(`--duration must be one of ${VIDEO_SECONDS.join(", ")} seconds (got ${opts.duration}).`);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.duration !== void 0 && opts.video) {
+    log.error("--duration sets the length of a GENERATED reference video \u2014 it cannot change footage you supplied.");
+    process.exitCode = 1;
+    return;
+  }
+  let videoBytes;
+  if (opts.video) {
+    const read = await readVideo(opts.video, log);
+    if (!read) {
+      process.exitCode = 1;
+      return;
+    }
+    videoBytes = read;
+  }
+  const ctx = await context2(opts);
+  if (!ctx) {
+    log.error("Not authorized. Run `genex init` first to sign in.");
+    process.exitCode = 1;
+    return;
+  }
+  let videoUrl;
+  if (opts.video && videoBytes) {
+    const uploaded = await uploadVideo(ctx.apiUrl, ctx.token, characterId, opts.video, videoBytes, log);
+    if (!uploaded) {
+      process.exitCode = 1;
+      return;
+    }
+    videoUrl = uploaded;
+  }
+  const response = await apiFetch(
+    `${ctx.apiUrl}/api/characters/${encodeURIComponent(characterId)}/motions/plan`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${ctx.token}` },
+      body: JSON.stringify({
+        verbs,
+        locomotion: Boolean(opts.locomotion),
+        lean: Boolean(opts.lean),
+        ...videoUrl ? { videoUrl } : {},
+        ...opts.duration === void 0 ? {} : { seconds: opts.duration }
+      })
+    }
+  );
+  if (printedStructuredError(response)) {
+    process.exitCode = 1;
+    return;
+  }
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    log.error(body.message ?? `Couldn't plan those animations (HTTP ${response.status}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const planned = await response.json();
+  if (opts.json) {
+    writeJson({ kind: "character_motion", stage: "plan", ...planned.plan });
+  } else {
+    printPlan(planned.plan, log, Boolean(opts.creature));
+  }
+  await runGenerate("character_motion", {
+    ...opts,
+    prompt: verbs.length > 0 ? `Animate character ${characterId}: ${verbs.join(", ")}` : `Generate the locomotion set for character ${characterId}`,
+    token: ctx.token,
+    apiUrl: ctx.apiUrl,
+    generationOptions: planned.request.options
+  });
+}
+async function runCharacterMotions(opts) {
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const characterId = opts.characterId?.trim();
+  if (!characterId) {
+    log.error("Missing character id.");
+    process.exitCode = 1;
+    return;
+  }
+  const ctx = await context2(opts);
+  if (!ctx) {
+    log.error("Not authorized. Run `genex init` first to sign in.");
+    process.exitCode = 1;
+    return;
+  }
+  const response = await apiFetch(
+    `${ctx.apiUrl}/api/characters/${encodeURIComponent(characterId)}/manifest`,
+    { headers: { Authorization: `Bearer ${ctx.token}` } }
+  );
+  if (printedStructuredError(response)) {
+    process.exitCode = 1;
+    return;
+  }
+  if (!response.ok) {
+    log.error(`Couldn't read that character (HTTP ${response.status}).`);
+    process.exitCode = 1;
+    return;
+  }
+  const { manifest } = await response.json();
+  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)
+      }))
+    });
+    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 where = slots.length > 0 ? ` \u2192 ${slots.join(", ")}` : "";
+    const source = clip.provider === "uthana" ? c.dim(" generated") : "";
+    log.plain(`  ${clip.key}${source}${where}`);
+  }
+}
+
 // src/commands/animations.ts
 function animationSearchView(entry) {
   return {
@@ -17978,20 +18425,26 @@ ${c.bold("Usage")}
   genex character finalize <preview-id>
                                      Finalize an approved preview as a 10,000-face
                                      controller-ready Meshy character.
-  genex character animate <id>       Add Meshy library actions to that character.
+  genex character animate <id> "<verb>" \u2026
+                                     Animate the character: say what it should DO,
+                                     in plain words ("overhead slam"), one clip per
+                                     verb. The platform picks how each is made and
+                                     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
+                                     multi-beat moves; --action <id-or-query> still
+                                     picks a catalog clip.
+  genex character motions <id>       List the clips installed on that character.
   genex creature "<desc>"            One-shot rigged enemy/creature (biped-shaped
                                      bodies only \u2014 Meshy rig limit): model \u2192 rig \u2192
                                      bind library clips via --animation. No approval
                                      ceremony, no player controller pack.
+  genex creature animate <id> "<verb>" \u2026
+                                     Same as character animate, for an enemy \u2014 a boss's
+                                     signature move. --lean keeps movement to forward
+                                     walk + run (enemies follow a path).
   genex animations search "<intent>" Search Meshy's animation library by gameplay intent.
-  genex motion <sub> [args]          Custom character animations from text (ARDY):
-                                     gen "<prompt>" (GPU service, bills per take) |
-                                     verify <takes\u2026> | compile <takes\u2026> --out \u2026 |
-                                     install [--set rifle] | constraints \u2014 the
-                                     local toolkit + vendored runtime the agent
-                                     owns. Catalog actions (genex animations
-                                     search) stay the first stop; motion covers
-                                     the verbs the catalog lacks.
   genex wait <id>                    Attach to a generation enqueued with --no-wait and
                                      print its asset URL(s) when it finishes. Safe to
                                      re-run \u2014 it never creates a new generation.
@@ -18006,9 +18459,11 @@ ${c.bold("Usage")}
                                      without a physics controller. "quality" = the
                                      adaptive-quality kit (device tier, runtime governor,
                                      per-tier asset rungs) every game wires at boot.
-                                     Character defaults to the player's VRM + UAL pack.
+                                     Character's player body is the game's own generated
+                                     character, with a VRM avatar as the fallback.
   genex controller character --character <id>
-                                     Install the Meshy-native controller variant.
+                                     Point the game at its generated character (writes the
+                                     manifest; no code change \u2014 the loader picks it up).
   genex controller anims <sel \u2026>     Install legacy VRM + UAL animation clips by tag/name
                                      into public/assets/anims/. --list shows the catalog;
                                      --reset forgets the previous selection first.
@@ -18020,8 +18475,13 @@ ${c.bold("Usage")}
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `music` `voice` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --raw                (skybox) send the prompt exactly as written \u2014 skip the
-                       appended environment-only guard.
-  --duration <sec>     (sfx, video, music) target clip length in seconds
+                       appended environment-only clause AND the refusal on
+                       prompts that name structures/objects (a sky is sky only;
+                       landforms and weather always pass).
+  --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
+                       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.
   --glass              (image) magenta-key glass lane: generate the panel on a
@@ -18136,15 +18596,13 @@ ${c.bold("Options for `character` / `animations search`")}
                        controller slots, requirements, review status, and estimated cost.
 
 ${c.bold("Options for `controller character` / legacy `controller anims`")}
-  --character <id>     (character) install the owned Meshy character manifest and
-                       same-rig native loader instead of the player's VRM.
+  --character <id>     (character) install the owned Meshy character manifest \u2014 the
+                       game's own generated character becomes the player's body.
   --list [selectors]   (anims) show the bundled VRM + UAL tag/name catalog.
   --reset              (anims) forget the previous game-local UAL selection.
 
 ${UI_USAGE}
 
-${MOTION_USAGE}
-
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -18188,15 +18646,17 @@ ${c.bold("Examples")}
   genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466
   genex character "stylized sci-fi courier" --direct-text --no-wait
   genex character animate <character-id> --action <action-id>
+  genex character animate <character-id> "overhead slam" "parry and recover" --no-wait
+  genex character animate <character-id> --locomotion --no-wait
+  genex character animate <character-id> "leap the gap and roll on landing" --duration 6
+  genex character animate <character-id> "victory pose" --video ./take-3.mp4
+  genex character motions <character-id>
   genex creature "hulking bone seraph, upright stance" --animation <walk-id> --animation <attack-id> --no-wait
+  genex creature animate <creature-id> "wind-up ground pound" --no-wait
   genex controller character --character <character-id>
   genex controller anims sword pistol
   genex controller touch
   genex controller networked-physics
-  genex motion gen "soldier rifle low-ready idle, fully upright, head held high" --takes 4 --no-wait
-  genex motion verify takes/ --json
-  genex motion compile takes/rifle-idle.npz takes/rifle-run-forward.npz --out src/motion/rifle.json
-  genex motion install --set rifle
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -18266,7 +18726,8 @@ function parseArgs(argv) {
     "--gates",
     "--config",
     "--set",
-    "--speed"
+    "--speed",
+    "--video"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -18302,6 +18763,12 @@ function parseArgs(argv) {
       case "--direct-text":
         parsed.options.directText = true;
         break;
+      case "--locomotion":
+        parsed.options.locomotion = true;
+        break;
+      case "--lean":
+        parsed.options.lean = true;
+        break;
       case "--in-place":
         parsed.options.inPlace = true;
         break;
@@ -18323,6 +18790,9 @@ function parseArgs(argv) {
       case "--no-defringe":
         parsed.options.defringe = false;
         break;
+      case "--allow-speckle":
+        parsed.options.allowSpeckle = true;
+        break;
       case "--loop":
         parsed.options.loop = true;
         break;
@@ -18379,20 +18849,27 @@ function parseArgs(argv) {
         } else if (parsed.command === "controller") {
           (parsed.options.selectors ??= []).push(arg);
         } else if (parsed.command === "character") {
-          if (parsed.options.name === "animate" && !parsed.options.characterId) {
+          if ((parsed.options.name === "animate" || parsed.options.name === "motions") && !parsed.options.characterId) {
             parsed.options.characterId = arg;
+          } else if (parsed.options.name === "animate") {
+            (parsed.options.verbs ??= []).push(arg);
           } else if (parsed.options.name === "preview" && !parsed.options.conceptId) {
             parsed.options.conceptId = arg;
           } else if (parsed.options.name === "finalize" && !parsed.options.previewId) {
             parsed.options.previewId = arg;
-          } else if (!["animate", "preview", "finalize"].includes(parsed.options.name ?? "")) {
+          } else if (!["animate", "motions", "preview", "finalize"].includes(parsed.options.name ?? "")) {
             parsed.options.name = `${parsed.options.name} ${arg}`;
           } else {
             parsed.error = `Unexpected argument: ${arg}`;
             return parsed;
           }
         } else if (parsed.command === "creature") {
-          parsed.options.name = `${parsed.options.name} ${arg}`;
+          if (parsed.options.name === "animate") {
+            if (!parsed.options.characterId) parsed.options.characterId = arg;
+            else (parsed.options.verbs ??= []).push(arg);
+          } else {
+            parsed.options.name = `${parsed.options.name} ${arg}`;
+          }
         } else if (parsed.command === "motion") {
           if (parsed.options.name === "gen") {
             parsed.options.query = parsed.options.query ? `${parsed.options.query} ${arg}` : arg;
@@ -18630,6 +19107,9 @@ function applyValueFlag(options, flag, value) {
     case "--frame":
       options.frameUrl = value;
       break;
+    case "--video":
+      options.video = value;
+      break;
     case "--first-frame":
       options.firstFrameUrl = value;
       break;
@@ -18729,7 +19209,13 @@ async function main() {
         break;
       case "character":
         if (parsed.options.name === "animate") {
-          await runCharacterAnimate(parsed.options);
+          if ((parsed.options.actions?.length ?? 0) > 0) {
+            await runCharacterAnimate(parsed.options);
+          } else {
+            await runCharacterAnimateMotion(parsed.options);
+          }
+        } else if (parsed.options.name === "motions") {
+          await runCharacterMotions(parsed.options);
         } else if (parsed.options.name === "preview") {
           await runCharacterPreview(parsed.options);
         } else if (parsed.options.name === "finalize") {
@@ -18739,6 +19225,10 @@ async function main() {
         }
         break;
       case "creature":
+        if (parsed.options.name === "animate") {
+          await runCharacterAnimateMotion({ ...parsed.options, creature: true });
+          break;
+        }
         if (!parsed.options.json && !parsed.options.quiet) {
           log.dim(
             "  Biped-shaped creatures only (Meshy rig limit) \u2014 for true quadrupeds/fliers use a static model + the genex-threejs-creatures procedural recipes."
@@ -18771,6 +19261,23 @@ async function main() {
       case "ui":
         await runUi({ ...parsed.options, sub: parsed.options.name });
         break;
+      // PARKED (AG-824 D12) — still dispatches, deliberately unlisted in --help
+      // and gone from the skills, the same way `genex explore` is parked.
+      //
+      // Why: `genex character animate` replaced it. That lane generates motion
+      // that binds to the character's OWN rig with no retargeting (measured: the
+      // provider returns our exact skeleton), which is what the ~1,700 lines of
+      // local retargeting behind this command existed to solve.
+      //
+      // Everything under it is intact and dormant: src/commands/motion.ts,
+      // src/lib/motion/**, templates/motion/**, the API's runpod-motion provider
+      // and its `motion` kind, and the RunPod worker (idle cost measured at $0).
+      //
+      // To re-enable: restore MOTION_USAGE + the examples in this file and the
+      // skill cross-links. The trap that already cost time —
+      // RUNPOD_MOTION_ENDPOINT_ID must be a GitHub Environment `vars.` entry,
+      // NOT a secret of the same name: a same-named secret upserts EMPTY, and
+      // the provider then silently falls back to the mock with no error anywhere.
       case "motion":
         await runMotion({ ...parsed.options, sub: parsed.options.name });
         break;