@genex-ai/cli-demo 0.91.0-dev.228 → 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.
@@ -3536,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();
@@ -4476,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"]);
@@ -4592,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.");
@@ -16486,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 {
@@ -18201,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.
@@ -18248,7 +18478,10 @@ ${c.bold("Options for the generators (`model` `skybox` `sfx` `music` `voice` `te
                        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
+  --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
@@ -18370,8 +18603,6 @@ ${c.bold("Options for `controller character` / legacy `controller anims`")}
 
 ${UI_USAGE}
 
-${MOTION_USAGE}
-
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -18415,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 = {
@@ -18493,7 +18726,8 @@ function parseArgs(argv) {
     "--gates",
     "--config",
     "--set",
-    "--speed"
+    "--speed",
+    "--video"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -18529,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;
@@ -18609,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;
@@ -18860,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;
@@ -18959,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") {
@@ -18969,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."
@@ -19001,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.91.0-dev.228",
+  "version": "0.92.0-dev.229",
   "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-ai-character/SKILL.md

@@ -169,44 +169,64 @@ Catalog entries are metadata-reviewed. Inspect the preview before choosing a
 specialty action. Only provider-declared `InPlace` loops or measured overrides
 may fill locomotion slots automatically.
 
-## Custom animations — `genex motion`
+## Custom animations — `genex character animate "<verb>"`
 
 Catalog search is ALWAYS the first stop — its stock actions cover most verbs
-with no GPU spend. When the catalog genuinely lacks the motion (a bespoke
-weapon-hold locomotion set, a signature move, a boss telegraph), `genex
-motion` generates it from text on the platform GPU service and compiles it
-locally into a rig-independent set:
+with no spend. When the catalog genuinely lacks the motion (a signature move, a
+boss telegraph, a full 8-way movement set), say what the character should DO in
+plain words and the platform generates it for this character's own rig:
 
 ```bash
-npx genex motion gen "soldier rifle low-ready idle, fully upright, head held high" --takes 4 --no-wait
-npx genex motion verify takes/            # objective gates — local, free, reproducible
-npx genex motion compile takes/rifle-idle.npz --out src/motion/rifle.json
-npx genex motion install --set rifle      # vendored runtime + the proven rifle starter set
+npx genex character animate <character-id> "overhead slam" "parry and recover" --no-wait
+npx genex character animate <character-id> --locomotion --no-wait
+npx genex character animate <character-id> "victory pose" --video ./take-3.mp4
 ```
 
-Billing is per take (default 4 per request); everything after `gen` is local.
-Unlike catalog clips (exact-rig only), compiled motion sets retarget onto
-Meshy/Mixamo GLB rigs and VRM avatars alike — the vendored `src/motion/rigs.js`
-carries both verified retarget formulas, and it is the game's file to tune.
-Read [references/motion.md](references/motion.md) BEFORE your first
-`motion gen`: it carries the prompt wording ladder, the take-naming contract
-that drives compilation, the rig limits (finger-less hands cannot curl around
-a grip), and the full wiring. Wording mistakes cost paid takes.
+One clip per verb. You never choose the method — the platform routes each verb
+(reuse a shared-library motion, generate movement, act it out on video first, or
+generate from a description) and prints the plan BEFORE anything is charged.
+
+**Show the plan to the user and let them change it before you continue.** That
+is the one stop in this lane; everything after it runs in the background while
+you keep building.
+
+Read [references/motion-generation.md](references/motion-generation.md) before
+the first run: it carries what makes a good verb, which verbs this cannot do,
+and the footage requirements for `--video`.
+
+`--locomotion` generates the full 8-way walk + run set (16 clips) — the
+directional slots the shipped controller resolves but the stock pack leaves
+empty, so a strafe stops being a faked forward walk. For an enemy that just
+follows a path, `--lean` keeps it to forward walk + run.
+
+Animate an enemy the same way — `genex creature animate <id> "<verb>"`. A
+creature is already a character underneath; the alias exists so you don't have
+to know that.
 
 ## Add actions and refresh the game
 
 ```bash
 npx genex character animate <character-id> --action <action-id>
 npx genex character animate <character-id> --action <first-id> --action <second-id> --no-wait
+npx genex character motions <character-id>     # what is installed right now
 npx genex controller character --character <character-id>
 ```
 
+`--action` picks an existing catalog clip; a free-text verb generates one. Both
+land in the same manifest and play through the same state machine.
+
 Ambiguous text queries print ranked candidates instead of silently spending
 credits. Already-installed actions return without another debit. After an
 animation job completes, rerun `genex controller character --character <id>`
 to refresh `public/assets/meshy-character.json`; existing controller source is
 preserved unless `--force` is explicitly used.
 
+Six slots belong to the reviewed controller pack and cannot be replaced —
+`idle.default`, `walk.forward`, `run.forward`, `crouch.forward`, `crouch.idle`,
+`jump.full`. A generated locomotion set fills the other fourteen directions; the
+plan says so before you spend anything. A character built without the pack
+(every `genex creature`) takes all sixteen.
+
 Meshy manifests bypass browser cache, so newly installed actions must work
 after preview without asking the player to disable cache.
 

package/templates/skills/genex-ai-character/references/motion-generation.md

@@ -0,0 +1,125 @@
+# Generating character motion
+
+`npx genex character animate <character-id> "<verb>"` — one clip per verb, on
+this character's own rig. Read this before the first run; it is short, and the
+first two sections are where the credits go.
+
+```bash
+npx genex character animate <id> "overhead slam" --no-wait
+npx genex character animate <id> --locomotion --no-wait
+npx genex character animate <id> "leap the gap and roll on landing" --duration 6
+npx genex character animate <id> "victory pose" --video ./take-3.mp4
+npx genex character motions <id>
+npx genex creature animate <id> "wind-up ground pound" --no-wait
+```
+
+You do not choose how a verb is made. The platform prints a plan first — which
+verbs it will reuse, generate, or act out on video, and one total. **Show the
+plan to the user.** That is the single stop in this lane; after it, everything
+runs in the background while you keep building. Collect it later with
+`genex wait --all`.
+
+## Write the verb like a stage direction
+
+The generator turns your words into a body performance, so name the BODY, not
+the intent. "Overhead slam" is a motion; "attack" is a category.
+
+| instead of | write |
+| --- | --- |
+| `attack` | `heavy two-handed overhead slam, ending in a low crouch` |
+| `hurt` | `stagger back two steps from a chest impact, arms flailing` |
+| `win` | `plant both feet, raise one fist overhead, chest out` |
+| `die` | `drop to the knees, then fall forward onto the chest` |
+
+Three things make a verb generate well:
+
+- **Name the beats.** A wind-up, a committed main beat, a recovery. A motion with
+  one beat reads as a twitch.
+- **Say where the weight goes.** "Sinks into the knees as it lands" is the single
+  most useful phrase you can add — without it you tend to get a bow from the
+  waist where you wanted a crouch.
+- **Keep it one person, standing, on the floor.** No props that define the pose,
+  no partner, no furniture.
+
+## What this cannot do
+
+Do not spend on these — pick a different approach instead:
+
+- **Fingers and fine manipulation** — picking a lock, typing, a trigger squeeze,
+  threading a needle. Generated rigs have no finger bones, so the hand simply
+  will not do it. Fake it with a prop animation or a cut.
+- **Two characters interacting** — a handshake, a grapple, a carry. Only one body
+  is generated. Animate each side separately and time them in code.
+- **Anything a prop defines** — swinging on a rope, climbing a specific ladder,
+  sitting in a specific chair. The clip does not know your geometry; drive those
+  with `$genex-threejs-procedural-animation` instead.
+- **Non-bipeds** — quadrupeds, fliers, blobs. See `$genex-threejs-creatures`;
+  those stay static models plus procedural motion.
+
+## Room to land the beats: `--duration`
+
+Some verbs are made by generating a short reference video of a performer and
+converting THAT into motion — the plan says which ones ("acted out on video").
+The footage is a hard ceiling on the animation, and the default 3 seconds is a
+tight fit for anything with more than one beat: a performer given too little
+time rushes, and a rushed wind-up-slam-recover comes back as a bow.
+
+`--duration 3|4|5|6` gives those verbs more room. Use it when the verb you wrote
+genuinely has three beats — a leap with a landing roll, a stagger that recovers,
+a combo. Leave it alone for a single action; longer is not better, it is just
+longer, and it costs more.
+
+It only reaches verbs the platform routes to video, and the plan tells you
+whether it applied. It cannot change footage you supplied with `--video` —
+that clip already has a length.
+
+## Movement: `--locomotion`
+
+Generates the full 8-way walk + run set — 16 clips. This fills the directional
+slots the shipped controller already resolves (`walk.forward-left`,
+`run.back-right`, and so on) but that the stock pack leaves empty, so strafing
+stops being a forward walk played sideways.
+
+Six slots belong to the reviewed controller pack and cannot be replaced:
+`idle.default`, `walk.forward`, `run.forward`, `crouch.forward`, `crouch.idle`,
+`jump.full`. A generated set fills the other fourteen; the plan says which. A
+character built without the pack — every `genex creature` — takes all sixteen.
+
+For an enemy that follows a path, `--lean` generates forward walk + run only.
+Enemies have no controller state machine driving a direction picker, so the
+other six directions would never play. Ask for the full set when a boss
+genuinely circles the player.
+
+## Your own footage: `--video`
+
+`--video ./clip.mp4` converts a real performance instead of a generated one.
+The footage is a hard ceiling on the result — nothing can add weight the
+performer never committed — so it has to meet the extractor's requirements:
+
+- **Exactly one person**, alone in frame.
+- **Whole body visible**, head to feet, for the entire clip. A limb that leaves
+  the frame is a gap that cannot be recovered.
+- **Locked-off camera.** No pan, no zoom, no handheld drift, no cuts.
+- **Plain contrasting background**, and clothing in distinct solid colors — no
+  long coat, cape, or skirt over the legs.
+- **Even lighting.** Heavy shadows or a silhouette degrade the extraction.
+- **2–60 seconds.** `.mp4` or `.mov`.
+
+Phone recordings work. So do screen captures and gameplay clips.
+
+The video is checked against these rules before anything is converted, and a
+failure tells you which requirement broke and roughly when — re-shoot against
+that note rather than re-running the same file.
+
+## After the clips land
+
+```bash
+npx genex controller character --character <character-id>
+```
+
+Then play the game and watch the motion on the real character. Numbers and a
+completed job prove the clip installed; only your eyes prove it reads right.
+
+A clip that plays as a T-pose or does not play at all means it did not bind —
+check `genex character motions <id>` to see what is actually installed. Do not
+"fix" it with runtime bone corrections; regenerate it.

package/templates/skills/genex-game-director/references/routing-map.md

@@ -22,6 +22,7 @@ Three.js release or branch, and do not blindly copy demo architecture.
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, the player's body loader, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
 | the game's own generated character — the player's BODY wherever a human body appears on screen (first-person included; the exemption is "no human body ever appears", not "the camera is in the head"), enqueued with the first art actions; one user stop riding the concept review, owner-ratified auto-pick on silence (director §7) — or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
+| a character or enemy needs a motion the catalog lacks — a signature move, a boss telegraph, a death, a full 8-way movement set, or a performance from the user's own footage: free-text verbs, platform-routed, plan shown before any spend (`genex character animate <id> "<verb>"`, `genex creature animate`, `--locomotion`, `--video`) | `$genex-ai-character` (motion section + `references/motion-generation.md`) |
 | remote player bodies in multiplayer — NEVER hand-built primitives: the game's generated character when it has one (everyone wears it), the player's `p.avatarUrl` VRM only when it doesn't | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
 | the game has enemies, NPCs, or creatures — **load whenever an enemy roster exists**: rigged bipeds via `npx genex creature`, static + procedural motion for other body shapes, plus the mechanical floor every enemy owes (collider, verified facing, hit reaction, death moment) | `$genex-threejs-creatures` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -56,10 +56,11 @@ way, so the character arriving mid-build is a file drop
 (`npx genex controller character --character <id>`) and not an edit to your
 most load-bearing code. Wire the block under "Minimal wiring" once, at hour 0.
 
-For a full custom LOCOMOTION SET beyond the UAL packs (a weapon-hold 8-way
-shooter kit, a signature gait), see `$genex-ai-character`'s motion section:
-`npx genex motion install --set rifle` drops the proven rifle set + its own
-runtime, and `genex motion gen` builds new sets from text.
+For a full custom LOCOMOTION SET beyond the UAL packs, see `$genex-ai-character`'s
+motion section: `npx genex character animate <id> --locomotion` generates the
+8-way walk + run set onto the character's own rig, filling the directional slots
+this controller already resolves but the stock pack leaves empty. Signature moves
+are the same command with a verb.
 
 Before generating a Meshy character, discuss two or three visual directions.
 When the user names a visual reference, inspect references before writing the

package/templates/skills/genex-threejs-creatures/SKILL.md

@@ -51,10 +51,20 @@ post-mixer limb corrections. Prompt the body UPRIGHT and unpropped (held
 props fuse into bodies); prompt "facing the viewer" but never trust it —
 facing is verified below.
 
-When the catalog has no clip for a bespoke attack, telegraph, or death move
-on a rigged biped, `genex motion` can generate one from text — see the motion
-section of `$genex-ai-character` (its compiled sets retarget onto any
-humanoid rig, unlike catalog clips).
+When the catalog has no clip for a bespoke attack, telegraph, or death move on
+a rigged biped, generate one for this creature:
+
+```bash
+npx genex creature animate <creature-id> "wind-up ground pound" --no-wait
+npx genex creature animate <creature-id> --locomotion --lean --no-wait
+```
+
+Say what the body does, in beats, with the weight named — "rears back, both
+arms overhead, slams down and sinks into a low crouch" beats "attack". The
+clips land in the creature's own manifest and play through the raw mixer wired
+below; `--lean` keeps movement to forward walk + run, which is all an enemy
+following a path can ever play. See the motion section of `$genex-ai-character`
+for what this can and cannot generate.
 
 ### State → clip wiring (one mixer per creature)
 

package/templates/skills/genex-threejs-procedural-animation/SKILL.md

@@ -11,8 +11,8 @@ coordinate frames, velocities, and ownership before writing per-frame updates.
 Boundary: procedural animation owns held-object and analytic motion (arcs,
 springs, docking, debris). WHOLE-BODY character verbs (a gait, a weapon
 hold, a signature move) belong to the character lane — the catalog first,
-then `genex motion` for verbs it lacks; see the motion section of
-`$genex-ai-character`.
+then `genex character animate <id> "<verb>"` for verbs it lacks; see the
+motion section of `$genex-ai-character`.
 
 ## Build order
 

package/templates/skills/genex-ai-character/references/motion.md

@@ -1,145 +0,0 @@
-# Custom animations with `genex motion` — the full procedure
-
-Text → raw motion takes on the platform GPU service → objective verify →
-YOUR pick → local compile → a rig-independent set the vendored runtime plays
-on any humanoid. The skeleton is a 27-joint humanoid core at 20 fps; takes
-arrive as `.npz` files plus a machine verify report. Everything after `gen`
-runs locally and free — regenerate compiled sets as often as you like.
-
-**Rig limits (say them to the user before promising a move):** biped,
-human-proportioned characters only. Rigs without finger bones (many Meshy
-characters) cannot curl fingers around a grip — prefer weapon-carry looks
-that read well with flat hands there, or use a rig with fingers for hero
-characters. Takes are 2–10 seconds.
-
-## The loop
-
-```bash
-# 1. Generate (bills per take, default 4; ALWAYS --no-wait — jobs run minutes)
-npx genex motion gen "soldier rifle low-ready idle, fully upright, head held high" --takes 4 --no-wait
-npx genex wait <id>                       # prints one URL per take + the report
-
-# 2. Download the takes it printed and RENAME them — filenames drive everything
-mkdir -p takes && curl -o takes/rifle-idle.npz "<take-url>"
-
-# 3. Verify locally (same math the service ran; free, reproducible)
-npx genex motion verify takes/
-
-# 4. Pick the takes whose MOTION reads right (the report is data, not taste),
-#    then compile the set
-npx genex motion compile takes/ --out src/motion/rifle.json
-
-# 5. Vendor the runtime once per game (+ the proven rifle starter set)
-npx genex motion install --set rifle
-```
-
-## Take naming — the routing contract
-
-`verify` and `compile` classify each take by its FILENAME stem. Rename
-downloaded takes before running them:
-
-| Stem pattern | Compiles into |
-|---|---|
-| `<set>-run-forward` / `-back` | `forward` / `back` gait |
-| `<set>-strafe-left` / `-strafe-right` | `strafeLeft` / `strafeRight` |
-| `<set>-run-fl` / `-fr` / `-bl` / `-br` | the four diagonal gaits |
-| `<set>-idle` or `…stance…` | the `idle` loop |
-| `…jump…` (`jump-stand`, `jump-run`) | `jumpStand` / `jumpRun` one-shots |
-| anything else | a named freeform loop |
-
-A stem containing `aim`, `rifle`, or `pistol` marks the take as a WEAPON
-HOLD: verify adds the hold-shape gates, and compile grip-line-normalizes the
-idle (the whole body blades as one) and plucks `aim0`/`aim0Up`/`aim0Dn`
-upper-body mask poses from the hold takes.
-
-## The prompt wording ladder (hard-won — wrong words cost paid takes)
-
-- **Never ask for "sights" or a "cheek weld"** — you get a hunched
-  face-height hold that reads absurd on game rigs. Ask for the third-person
-  hold: *"weapon at chest height, arms extended"*, *"low-ready"* as the
-  fallback.
-- **Always add "fully upright, head held high"** — the model's prior slouches.
-- **Describe hand geometry literally** (*"left hand forward on the handguard,
-  right hand at the grip"*), not by weapon jargon.
-- The model NEVER squares a two-handed hold to the pelvis — real marksmen
-  blade, and compile normalizes the heading by the grip line. Do not fight
-  it with prompt words; it is not a defect.
-- **Gaits need constraints, not prose.** Direction words alone drift; pin
-  the trajectory:
-
-```bash
-npx genex motion constraints --dir strafe-left --speed 2.5 --duration 5 --out strafe-left.json
-npx genex motion gen "soldier strafing with a rifle at low-ready" --constraints strafe-left.json --no-wait
-```
-
-The constraint pins the root path AND the heading (facing stays +Z) — that
-pin is what makes a strafe a strafe. One direction per request; a full
-8-direction set is 8 requests + one idle (run them in parallel with
-`--no-wait`, like any batch).
-
-## Verify semantics
-
-`PASS` (≥70) / `WARN` (≥50) / `FAIL`, with a hard-zero cap: a zero on any
-load-bearing gate fails the take no matter the average. The reasons column
-names the defect in plain words (feet skate, grip line wanders, cheek weld…).
-The report is DATA — freeform verbs have no semantic gate, so watch the take
-on the rig before shipping it. Tune bands via `--gates gates.json` (partial
-JSON, deep-merged: `{"aim": {"hunch": {"bad": 25}}}`).
-
-## Compile semantics + tunables
-
-Compile cuts loop cycles at left-foot strikes (gaits) or the best seam window
-(idles), removes the linear trajectory (residual sway + full Y bob stay),
-normalizes heading to +Z, phase-aligns gaits (frame 0 = left strike), and for
-weapon holds levels the arm assembly, raises the gaze, clamps tall stances,
-and yaws mask poses in the SPINE. All rigid whole-body/assembly operations —
-no joint ever moves relative to another (the no-bake law; it is why compiled
-sets survive retargeting). Every threshold lives in
-`src/motion/motion.config.json` after install — pass `--config` to use it.
-
-## Wiring the runtime
-
-`genex motion install` puts the runtime IN YOUR GAME — `src/motion/rigs.js`
-(both retarget formulas + the load-time normalizations), `anim-runtime.js`
-(ClipSet/Animator/dir8Weights/aimMaskStep), `ik.js`, and the config. They are
-yours: read them, tune them, the comments explain every formula. Load order
-matters:
-
-```js
-import { loadRig, captureRestAnkle, reanchorFeet, groundCalibrate, curlFingers } from "./motion/rigs.js";
-import { ClipSet, Animator, dir8Weights, aimMaskStep } from "./motion/anim-runtime.js";
-
-const set = await (await fetch("./motion-sets/rifle.json")).json(); // copy sets where your bundler serves them
-const rig = await loadRig("./assets/character.glb", set, modelFrame); // GLB or VRM — auto-detected
-rig.computeCorrection();
-const restAnkle = captureRestAnkle(rig, scene);   // BIND pose, before any clip
-reanchorFeet(rig, set, scene);                    // steep-boot fix — BEFORE ClipSet
-const clipSet = new ClipSet(rig, set, set.gaits);
-groundCalibrate(rig, clipSet, scene, restAnkle);  // short-leg fix — AFTER ClipSet
-curlFingers(rig, scene);                          // grips (no-op on finger-less rigs)
-const anim = new Animator(clipSet);
-
-// per frame: your input → blend weights; the mask follows the COMMAND magnitude
-anim.setLoops({ idle: 1 - mag, ...dir8Weights(x, z, mag) }, dt);
-maskW = aimMaskStep(maskW, { mag, grounded, pitch, dt });
-anim.setMask("aim0", maskW, pitch / 0.6);         // ±40° at pitch extremes
-anim.update(dt);
-```
-
-- Physics owns the world transform: hips play LOCAL values only (residual
-  x/z + absolute y); your character root carries position + yaw.
-- Jumps: `anim.playOneShot("jumpRun", { yCap: 0.1 })` — cap hips Y when the
-  physics capsule owns the jump, and gate the impulse on the clip's own
-  takeoff frame. The `--set rifle` install includes the shared jumps set;
-  merge it: `Object.assign(clipSet.tracks, new ClipSet(rig, jumps, jumps.gaits).tracks)`.
-- The aim mask WINS over one-shots on masked bones — a jump keeps aiming.
-- Standing aim = the UNMASKED bladed idle; the spine-yawed mask pose is only
-  for moving/airborne/pitched states. `aimMaskStep` already encodes this.
-
-## Cost + discipline
-
-Per-take billing (a 4-take request ≈ one model generation). One regenerate
-per verb is a fair budget when takes fail the gates — reword with the ladder
-above before spending again, and compare candidates from ONE batch first
-(that is what `--takes 4` is for). Never re-run `motion gen` to "pick up" a
-result — `genex wait <id>` re-attaches free.