@genex-ai/cli-demo 1.8.1-dev.501 → 1.9.0-dev.502

package/dist/index.js

@@ -992,14 +992,14 @@ var CONTRACT_END = "<!-- genex:contract:end -->";
 var GENEX_CONTRACT_BLOCK = `${CONTRACT_BEGIN}
 # Genex build contract (always in effect for this game)
 
-Your agentic capabilities that can boost your creation (all via \`npx genex \u2026\`): generate \`model\` \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|chat\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\` \xB7 \`rename <name>\` (move the game to a new address \u2014 keeps its plays and likes, kills the old link, needs \`--yes\` once published, and the game must be rebuilt after). Full options: \`npx genex --help\`. There is NO sky generator: every sky, horizon, time of day and weather mood is built in code \u2014 your call how, from a background colour and fog to an atmospheric sky shader with a real sun. It costs nothing, weighs nothing on phones, and keeps the sun in sync with the scene's own lighting, which a painted panorama never can. 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 agentic capabilities that can boost your creation (all via \`npx genex \u2026\`): generate \`model\` (\`--image\` from a reference image; \`model segment <id>\` into named parts; \`model rig <id>\` + \`model animate <rig-id> --preset walk\` for non-biped bodies \u2014 7 body plans) \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|chat\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\` \xB7 \`rename <name>\` (move the game to a new address \u2014 keeps its plays and likes, kills the old link, needs \`--yes\` once published, and the game must be rebuilt after). Full options: \`npx genex --help\`. There is NO sky generator: every sky, horizon, time of day and weather mood is built in code \u2014 your call how, from a background colour and fog to an atmospheric sky shader with a real sun. It costs nothing, weighs nothing on phones, and keeps the sun in sync with the scene's own lighting, which a painted panorama never can. 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.
 
 Important note: put soul into your creations, with many details and love. Aim to make them realistic and feel real. Use genex capabilities as an extension, but never limit your imagination \u2014 you are a powerful agent. Use your built-in sub-agents and iteration loops (\`/loop\` or your platform's equivalent) where you need them to reach outstanding results. Verify yourself. Anything you put in front of the player should already feel alive and impressive \u2014 never a bare scene waiting for "later". Build what's still missing before polishing what already works.
 
 1. Load the \`genex-game-director\` skill before starting the requested work. Route from the player's latest clear request: a focused request starts directly without replaying discovery or commissioning unrelated lanes. 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. Ask only when one unresolved answer materially changes the work. If the request is clear, do not repeat an interview, confirm the pitch, force a concept round, or ask whole-game-vs-one-part again. For a genuinely broad new game, ask one decision: whole coordinated build or one request-relevant part first. If there is no clear request \u2014 a setup prompt pasted with nothing of their own \u2014 ask in PLAIN CHAT what they want to make, in their own words, and never fill the blank by pitching concepts. Once you know what you are building, ask one decision at a time with your built-in question tool with clickable answer options when you have one; use a short plain-chat question otherwise. If the player stays silent after a necessary question, proceed on stated assumptions where reasonable and record each as "assumed \u2014 player didn't answer" in DESIGN.md \u2192 Decisions.
 3. \`DESIGN.md\` at the project root is the durable design contract AND build plan. Keep three truths distinct: the player's requested outcome, the current \`Now:\` focus, and open commitments. It must carry a \`## Build plan & status\` section with the working mode (\`whole coordinated build\`, \`step by step\`, or \`focused change\`), numbered milestones with status marks, and a \`Now:\` line naming the current one \u2014 a milestone is done only when its work reached a preview. The latest clear request may replace \`Now:\` immediately; it never silently shrinks the requested outcome or deletes unrelated commitments. Keep every decision, assumption, generation id/URL, local output, and wiring state current. When the plan first lands, tell the player in one plain line that you recorded what they asked for in \`DESIGN.md\` and will keep it current.
-4. Use \`genex\` commands to generate art, audio, video, characters, and UI. A local reference image is not a reason to switch tools: pass its file path to genex (\`--edit\` and \`--inpaint\` accept local paths). Don't limit yourself: add details, and mix generated assets with procedural generation to make scenes and games detailed and lively.
+4. Use \`genex\` commands to generate art, audio, video, characters, and UI. A local reference image is not a reason to switch tools: pass its file path to genex (\`--edit\`, \`--inpaint\`, and model's \`--image\` accept local paths). Don't limit yourself: add details, and mix generated assets with procedural generation to make scenes and games detailed and lively.
 5. When shipping your game / project: building, previewing, and publishing go only through \`genex preview\` / \`genex publish\` \u2014 never load your platform's own site-building, hosting, or deploy skills for this game.
 6. Generated UI art is a tool you reach for, not a pipeline you owe. A restrained interface built in clean CSS is a finished, legitimate HUD \u2014 not a placeholder. Reach for the sprite lane (\`genex-ai-hud\`) when the game's own style genuinely wants drawn chrome \u2014 ornate, painterly, comic, hand-made \u2014 or when the player asks for HUD art. Generating ONE element you decided the game needs \u2014 a frame, a mask, an icon, a wordmark, a menu backdrop, a menu video \u2014 is a normal use of these tools, never a half-run pipeline. There is NO global game-concept image and no UI plan recited in chat: the art direction lives in the game's brief in words. A lane's own concept step survives only where the player is choosing a concrete thing (a character's candidates). Whatever you do generate, run its quality steps in full \u2014 extraction, masks, wiring, \`npx genex ui audit\`.
 7. 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\`.
@@ -5498,6 +5498,11 @@ async function runShop(opts) {
     process.exitCode = 1;
     return;
   }
+  if (opts.type !== void 0 && opts.type !== "consumable" && opts.type !== "durable") {
+    log.error(`Invalid --type value for shop: ${opts.type} (consumable or durable)`);
+    process.exitCode = 1;
+    return;
+  }
   const meta = await readProject();
   if (!meta?.id) {
     log.error("This folder isn't linked to a game.");
@@ -6818,6 +6823,7 @@ function applySkyboxGuard(prompt, raw) {
 }
 function buildGenOptions(kind, opts) {
   const options = { ...opts.generationOptions };
+  if (kind === "model" && opts.imageUrl) options.imageUrl = opts.imageUrl;
   if (kind === "texture" && opts.terrain) options.terrain = true;
   if ((kind === "sfx" || kind === "music") && opts.duration) options.durationSeconds = opts.duration;
   if (kind === "voice") {
@@ -6862,7 +6868,11 @@ function buildGenOptions(kind, opts) {
 }
 async function runGenerate(kind, opts) {
   const log = createLogger({ quiet: opts.quiet || opts.json });
-  const typedPrompt = opts.prompt?.trim();
+  let typedPrompt = opts.prompt?.trim();
+  if (!typedPrompt && kind === "model" && opts.imageUrl) {
+    const ref = opts.imageUrl.startsWith("data:") ? "local image" : opts.imageUrl;
+    typedPrompt = `from image: ${path19.basename(ref).slice(0, 120)}`;
+  }
   if (!typedPrompt) {
     log.error(`Missing prompt. Usage: ${c.cyan(`genex ${kind} "<prompt>"`)}`);
     process.exitCode = 1;
@@ -6931,6 +6941,15 @@ async function runGenerate(kind, opts) {
     }
     opts = { ...opts, frameUrl: inlined.dataUri };
   }
+  if (kind === "model" && opts.imageUrl && !isRemoteRef(opts.imageUrl)) {
+    const inlined = await inlineLocalImage(opts.imageUrl, "--image");
+    if (!inlined.ok) {
+      log.error(inlined.error);
+      process.exitCode = 1;
+      return;
+    }
+    opts = { ...opts, imageUrl: inlined.dataUri };
+  }
   if (kind === "voice" && prompt.length > 1e3) {
     log.warn(
       `Voice text is ${prompt.length} chars \u2014 the server clamps at 1000 (billing follows the clamp). Split longer copy into separate lines.`
@@ -7174,6 +7193,12 @@ async function reportTerminal(kind, view, log, open = false, json = false) {
   }
   log.plain("");
   if (kind === "texture" && files[0]) await reportTextureSeam(files[0].url, log);
+  if (kind === "model_segment") {
+    const parts = metadataOf(view).partNames;
+    if (Array.isArray(parts) && parts.length > 0) {
+      log.dim(`  Parts: ${parts.filter((p) => typeof p === "string").join(", ")}`);
+    }
+  }
   if (open && files[0]) {
     openUrl(files[0].url);
     log.plain(
@@ -7322,7 +7347,10 @@ function printHint(kind, view, files, log) {
     character_preview: "Show all four preview views to the user and wait for explicit approval before finalizing.",
     character: `Install the controller and current manifest with genex controller character --character ${view.id}.`,
     character_animation: "The action is now part of the character's current manifest; refresh the local controller manifest before testing.",
-    character_motion: `The clips are part of the character's current manifest \u2014 install them with genex controller character --character ${view.id}, then play the game and watch the motion on the real character before calling it done.`
+    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.`,
+    model_segment: `One GLB with NAMED parts \u2014 load with GLTFLoader, then getObjectByName / traverse scene.children to move, detach, or swap a part. Part names print above when the provider reports them. url = "${url}"`,
+    model_rig: `Rigged GLB (Tripo skeleton) \u2014 load with GLTFLoader; give it motion with genex model animate ${view.id} --preset walk, or drive the bones in code. url = "${url}"`,
+    model_animation: `Animated GLB \u2014 load with GLTFLoader and play its clips via THREE.AnimationMixer (gltf.animations). url = "${url}"`
   };
   log.dim(`  ${hint[kind]}`);
   log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
@@ -7488,6 +7516,97 @@ function writeJson(value) {
 `);
 }
 
+// src/commands/model-sub.ts
+var MODEL_SUBCOMMANDS = ["segment", "rig", "animate"];
+var SEGMENT_GRANULARITIES = ["simple", "balanced", "detailed"];
+var MODEL_RIG_TYPES = [
+  "biped",
+  "quadruped",
+  "hexapod",
+  "octopod",
+  "avian",
+  "serpentine",
+  "aquatic"
+];
+var MODEL_ANIMATE_PRESETS = {
+  biped: ["idle", "walk", "run", "dive", "climb", "jump", "slash", "shoot", "hurt", "fall", "turn"],
+  quadruped: ["walk"],
+  hexapod: ["walk"],
+  octopod: ["walk"],
+  avian: [],
+  serpentine: ["march"],
+  aquatic: ["march"]
+};
+var ALL_PRESETS = [...new Set(Object.values(MODEL_ANIMATE_PRESETS).flat())];
+function requireSourceId(opts, usage) {
+  const id = opts.sourceId?.trim();
+  if (id) return id;
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  log.error(`Missing generation id. Usage: ${c.cyan(usage)}`);
+  process.exitCode = 1;
+  return void 0;
+}
+async function runModelSegment(opts) {
+  const sourceId = requireSourceId(opts, "genex model segment <generation-id>");
+  if (!sourceId) return;
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  if (opts.granularity && !SEGMENT_GRANULARITIES.includes(opts.granularity)) {
+    log.error(`Invalid --granularity value: ${opts.granularity} (expected ${SEGMENT_GRANULARITIES.join("|")})`);
+    process.exitCode = 1;
+    return;
+  }
+  await runGenerate("model_segment", {
+    ...opts,
+    prompt: `segment ${sourceId}`,
+    generationOptions: {
+      sourceGenerationId: sourceId,
+      ...opts.granularity ? { granularity: opts.granularity } : {}
+    }
+  });
+}
+async function runModelRig(opts) {
+  const sourceId = requireSourceId(opts, "genex model rig <generation-id>");
+  if (!sourceId) return;
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  if (opts.type && !MODEL_RIG_TYPES.includes(opts.type)) {
+    log.error(`Invalid --type value: ${opts.type} (expected ${MODEL_RIG_TYPES.join("|")})`);
+    process.exitCode = 1;
+    return;
+  }
+  await runGenerate("model_rig", {
+    ...opts,
+    prompt: `rig ${sourceId}`,
+    generationOptions: {
+      sourceGenerationId: sourceId,
+      ...opts.type ? { rigType: opts.type } : {}
+    }
+  });
+}
+async function runModelAnimate(opts) {
+  const rigId = requireSourceId(opts, "genex model animate <rig-generation-id> --preset walk");
+  if (!rigId) return;
+  const log = createLogger({ quiet: opts.quiet || opts.json });
+  const presets = opts.presets ?? [];
+  if (presets.length === 0) {
+    log.error(`Missing --preset. Usage: ${c.cyan("genex model animate <rig-id> --preset walk,run")}`);
+    log.dim(`  Presets by body plan \u2014 biped: ${MODEL_ANIMATE_PRESETS.biped.join(", ")}; quadruped/hexapod/octopod: walk; serpentine/aquatic: march.`);
+    process.exitCode = 1;
+    return;
+  }
+  const unknown = presets.filter((p) => !ALL_PRESETS.includes(p));
+  if (unknown.length > 0) {
+    log.error(`Unknown preset${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Valid: ${ALL_PRESETS.join(", ")}.`);
+    log.dim("  (Which of these apply depends on the rig's body plan \u2014 the server checks that too.)");
+    process.exitCode = 1;
+    return;
+  }
+  await runGenerate("model_animation", {
+    ...opts,
+    prompt: `animate ${rigId}: ${presets.join(", ")}`,
+    generationOptions: { rigGenerationId: rigId, presets }
+  });
+}
+
 // src/commands/wait.ts
 var TERMINAL2 = /* @__PURE__ */ new Set(["completed", "failed"]);
 async function runWait(opts) {
@@ -20243,6 +20362,7 @@ async function runAssetNew(options) {
 }
 
 // src/index.ts
+var MODEL_SUB_SET = new Set(MODEL_SUBCOMMANDS);
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "music", "voice", "texture", "image", "video"]);
 var HELP = `${c.bold("genex")} \u2014 set up your project's agent workspace, authorize, and publish 3D games.
 
@@ -20302,6 +20422,23 @@ ${c.bold("Usage")}
                                      other on the market; durable items only, off by
                                      default, and --no-resellable turns it back off.
   genex model "<prompt>" [options]   Generate a 3D model (GLB); prints a public asset URL.
+                                     --image <path|url> builds it FROM a reference
+                                     image instead (prompt optional).
+  genex model segment <id>           Split a generated model into NAMED parts \u2014
+                                     one GLB, parts addressable by name (doors,
+                                     magazines, turrets, destructibles).
+                                     --granularity simple|balanced|detailed.
+  genex model rig <id>               Give any generated mesh a skeleton (7 body
+                                     plans: biped|quadruped|hexapod|octopod|
+                                     avian|serpentine|aquatic). Auto-detects the
+                                     plan; --type picks it explicitly. Unriggable
+                                     meshes are refused and auto-refunded.
+  genex model animate <rig-id> --preset walk[,run,\u2026]
+                                     Retarget ready-made motion clips onto a
+                                     'model rig' result (billed per clip).
+                                     biped: idle|walk|run|dive|climb|jump|slash|
+                                     shoot|hurt|fall|turn; quadruped/hexapod/
+                                     octopod: walk; serpentine/aquatic: march.
   genex sfx "<prompt>" [options]     Generate a sound effect (mp3); prints a public asset URL.
   genex music "<prompt>" [options]   Generate an instrumental music track (mp3); prints a
                                      public asset URL. --duration 10-300s (default 90).
@@ -20384,6 +20521,16 @@ ${c.bold("Usage")}
                                      --summary --tags --out --force.
 
 ${c.bold("Options for the generators (`model` `sfx` `music` `voice` `texture` `image` `video`)")}
+  --image <path|url>   (model) build the model FROM this reference image \u2014 a
+                       local file (\u22644 MB, inlined) or a previous generation's
+                       asset URL. The prompt becomes optional.
+  --granularity <g>    (model segment) part granularity: simple | balanced |
+                       detailed (default balanced).
+  --type <plan>        (model rig) body plan: biped | quadruped | hexapod |
+                       octopod | avian | serpentine | aquatic (default:
+                       auto-detected by the free rig check).
+  --preset <list>      (model animate) comma-separated motion clips (see the
+                       per-plan lists above); each clip is billed.
   --terrain            (texture) seamless tiling surface for terrain/ground.
   --duration <sec>     (sfx, video, music) target clip length in seconds;
                        (character/creature animate) 3-6 s of reference video for
@@ -20558,6 +20705,10 @@ ${c.bold("Examples")}
   genex shop remove sku_123
   genex publish --no-push --title "My Game"
   genex model "weathered wooden barrel with iron bands"
+  genex model --image ./concept.png
+  genex model segment <model-generation-id> --granularity detailed
+  genex model rig <model-generation-id> --type quadruped
+  genex model animate <rig-generation-id> --preset walk
   genex sfx "punchy laser zap" --duration 2
   genex music "brooding orchestral battle loop, seamless loop, no intro or outro" --no-wait
   genex voice "You shall not pass!" --voice gruff
@@ -20631,6 +20782,10 @@ function parseArgs(argv) {
     "--first-frame",
     "--last-frame",
     "--resolution",
+    // `genex model` mesh-lane value flags (AG-908).
+    "--image",
+    "--granularity",
+    "--preset",
     // `genex ui` string flags (the numeric ones come from UI_NUMBER_FLAGS).
     "--in",
     "--out-dir",
@@ -20803,6 +20958,13 @@ function parseArgs(argv) {
           parsed.command = arg;
         } else if (parsed.options.name === void 0) {
           parsed.options.name = arg;
+        } else if (parsed.command === "model" && MODEL_SUB_SET.has(parsed.options.name ?? "")) {
+          if (parsed.options.sourceId === void 0) {
+            parsed.options.sourceId = arg;
+          } else {
+            parsed.error = `Unexpected argument: ${arg}`;
+            return parsed;
+          }
         } else if (parsed.command === "explore") {
           parsed.options.name = `${parsed.options.name} ${arg}`;
         } else if (parsed.command === "controller") {
@@ -21051,8 +21213,10 @@ function applyValueFlag(options, flag, value) {
       options.icon = value;
       break;
     case "--type": {
-      if (value !== "consumable" && value !== "durable") {
-        throw new Error(`Invalid --type value: ${value} (consumable or durable)`);
+      if (value !== "consumable" && value !== "durable" && !MODEL_RIG_TYPES.includes(value)) {
+        throw new Error(
+          `Invalid --type value: ${value} (shop: consumable|durable; model rig: ${MODEL_RIG_TYPES.join("|")})`
+        );
       }
       options.type = value;
       break;
@@ -21121,6 +21285,15 @@ function applyValueFlag(options, flag, value) {
     case "--frame":
       options.frameUrl = value;
       break;
+    case "--image":
+      options.imageUrl = value;
+      break;
+    case "--granularity":
+      options.granularity = value;
+      break;
+    case "--preset":
+      options.presets = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      break;
     case "--video":
       options.video = value;
       break;
@@ -21215,6 +21388,12 @@ async function main() {
       return;
     }
     if (GEN_KINDS.has(parsed.command)) {
+      if (parsed.command === "model" && MODEL_SUB_SET.has(parsed.options.name ?? "")) {
+        if (parsed.options.name === "segment") await runModelSegment(parsed.options);
+        else if (parsed.options.name === "rig") await runModelRig(parsed.options);
+        else await runModelAnimate(parsed.options);
+        return;
+      }
       await runGenerate(parsed.command, {
         ...parsed.options,
         prompt: parsed.options.name
@@ -21278,7 +21457,7 @@ async function main() {
         }
         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."
+            "  Biped-shaped creatures only (Meshy rig limit) \u2014 for a true quadruped/flier/serpent, generate it with `npx genex model` and rig it with `npx genex model rig` (7 body plans), or go static + the genex-threejs-creatures procedural recipes."
           );
         }
         await runCharacter({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.8.1-dev.501",
+  "version": "1.9.0-dev.502",
   "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/references/motion-generation.md

@@ -53,8 +53,10 @@ These will not come back usable — pick a different approach instead:
 - **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.
+- **Non-bipeds** — quadrupeds, fliers, serpents. See `$genex-threejs-creatures`;
+  those route to the model-rig lane (`npx genex model rig` +
+  `npx genex model animate`, 7 body plans — `$genex-ai-model`). Blobs and
+  swarms stay static models plus procedural motion.
 
 ## Room to land the beats: `--duration`
 

package/templates/skills/genex-ai-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-model
-description: Generate a real 3D model (GLB mesh) from a text prompt with `npx genex model`, then load it into the Three.js scene. Use when the user wants a specific prop, item, character, vehicle, building, or any concrete object as an actual mesh ("add a wooden barrel", "I need a spaceship", "generate a sword") rather than a procedurally-coded shape.
+description: Generate a real 3D model (GLB mesh) from a text prompt or a reference image with `npx genex model`, then load it into the Three.js scene — and, when the game needs it, split it into named parts (`model segment`), or rig and animate any mesh (`model rig` / `model animate`, 7 body plans incl. quadrupeds, birds, snakes). Use for any concrete object as an actual mesh rather than a procedurally-coded shape.
 ---
 
 # Genex AI · Model
@@ -17,13 +17,17 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
   scene is the normal way to build a detailed world — generated hero pieces
   over procedural dressing.
 
-**The output is a STATIC, unrigged mesh — no skeleton, no animation clips.**
-A "wolf" or "guard" from this command can be posed and moved as one object,
-but its limbs cannot animate. Anything that must walk, attack, or die on
-screen routes to the creature lane instead: `npx genex creature` for
-biped-shaped bodies (real rig + library clips), or this command plus the
-procedural-motion recipes for everything else — `$genex-threejs-creatures`
-owns that split. The player's own character is `$genex-ai-character`.
+**The output is a STATIC, unrigged mesh by default — no skeleton, no animation
+clips.** A "wolf" or "guard" from this command can be posed and moved as one
+object, but its limbs cannot animate out of the box. When the game needs more,
+this same lane goes further: `npx genex model segment <id>` splits the mesh
+into named parts (doors, magazines, turrets), and `npx genex model rig <id>` +
+`npx genex model animate <rig-id> --preset walk` give any mesh a real skeleton
+and motion — including body plans Meshy refuses (quadrupeds, birds, snakes,
+fish, multi-legged things). See the sections below. For a biped-shaped enemy,
+`npx genex creature` (real rig + the animation library) is still the default,
+and `$genex-threejs-creatures` owns that split. The player's own character is
+`$genex-ai-character`.
 
 ## Run
 
@@ -44,6 +48,74 @@ download it** and **nothing is committed to your repo** — copy the URL the com
 prints into your loader. The URL is permanent, so it works the same in local dev, your
 published game, and remixes.
 
+## From a reference image
+
+```bash
+npx genex model --image ./concept.png
+npx genex model --image https://assets.genex.technology/generations/<id>/image-main
+```
+
+`--image` builds the model FROM a picture instead of a prompt — a user's
+reference photo, a concept the image lane generated, a screenshot. A local file
+(png/jpg/webp, ≤4 MB) is inlined automatically; a previous generation's asset
+URL passes through. The prompt becomes optional (it's recorded for the ledger,
+the provider works from the image alone). A clear, single-object image on a
+plain background converts best.
+
+## Split into parts (`model segment`)
+
+```bash
+npx genex model segment <model-generation-id> --granularity detailed
+```
+
+Takes a finished model generation's id and returns ONE new GLB whose meshes are
+**named parts** — a rifle becomes body/magazine/scope, a car becomes
+doors/wheels/chassis. What the parts are for is your call per game: detach a
+magazine for a reload animation, swing a door on its own pivot, blow a turret
+off a destructible tank, recolor one part.
+
+```ts
+const gltf = await loader.loadAsync(SEGMENTED_URL);
+const magazine = gltf.scene.getObjectByName("magazine"); // names print on completion
+```
+
+`--granularity simple|balanced|detailed` sets how finely it splits (default
+balanced). The provider owns the split and the part textures — ship its output
+as-is; if a part comes back oddly textured, regenerate rather than patching
+pixels. Part names print with the result when the provider reports them;
+otherwise `traverse` the scene and read `child.name`.
+
+## Rig and animate any mesh (`model rig` / `model animate`)
+
+```bash
+npx genex model rig <model-generation-id>            # body plan auto-detected (free check)
+npx genex model rig <model-generation-id> --type quadruped
+npx genex model animate <rig-generation-id> --preset walk
+```
+
+This is the route for **non-biped bodies that must move** — the lane Meshy
+refuses. Seven body plans: `biped`, `quadruped`, `hexapod`, `octopod`, `avian`,
+`serpentine`, `aquatic`. A free rig-check runs first: an unriggable mesh is
+refused and auto-refunded before anything is charged.
+
+`model animate` retargets ready-made clips onto the rig (billed per clip).
+Presets by plan — biped: `idle walk run dive climb jump slash shoot hurt fall
+turn`; quadruped/hexapod/octopod: `walk`; serpentine/aquatic: `march`; avian
+has a rig but no preset clips (drive its bones in code). Play the result like
+any animated GLB:
+
+```ts
+const gltf = await loader.loadAsync(ANIMATED_URL);
+const mixer = new THREE.AnimationMixer(gltf.scene);
+mixer.clipAction(gltf.animations[0]).play(); // and mixer.update(dt) per frame
+```
+
+Honest limits, so you plan around them and never oversell: **no finger bones**
+on any plan; presets are generic locomotion/action clips, not bespoke motion;
+and this rig is a plain Tripo skeleton — it does NOT join the character lane's
+manifest/controller system. The player's own body and biped enemies with the
+full animation library stay on `$genex-ai-character` / `npx genex creature`.
+
 ## Models that point somewhere must face forward
 
 Any model with a "front" the game aims — the hero the player controls, an **NPC that
@@ -178,8 +250,13 @@ scene is a ghost: players and objects pass straight through it.
 
 ## Options
 
-- `--no-wait` — enqueue and return immediately (won't print the URL; re-run without
-  `--no-wait` to get it).
+- `--image <path|url>` — build from a reference image (local file ≤4 MB, or a
+  generated-asset URL); the prompt becomes optional.
+- `--granularity simple|balanced|detailed` — (`model segment`) part granularity.
+- `--type <plan>` — (`model rig`) body plan; omit to let the free rig-check pick.
+- `--preset walk[,run,…]` — (`model animate`) clips to retarget; billed per clip.
+- `--no-wait` — enqueue and return immediately (won't print the URL; pick it up
+  with `npx genex wait <id>`).
 - `--api-url <url>` — override the API base (local dev).
 
 ## Troubleshooting

package/templates/skills/genex-game-director/SKILL.md

@@ -104,7 +104,9 @@ modules are conditional on the request and existing project.
 Use the [routing map](references/routing-map.md) for exact ownership. The main
 Genex asset and runtime lanes are:
 
-- `npx genex model "<prompt>"`—a static GLB → `$genex-ai-model`
+- `npx genex model "<prompt>"`—a generated GLB (also `--image` from a
+  reference picture, `model segment` into named parts, `model rig` +
+  `model animate` for non-biped bodies) → `$genex-ai-model`
 - `npx genex texture "<prompt>"`—a generated surface → `$genex-ai-texture`
 - sky, horizon, time of day, weather mood—built in code, never generated; no
   command and no skill owns it, so pick what this game needs
@@ -125,7 +127,8 @@ Genex asset and runtime lanes are:
   these → `$genex-threejs-procedural-assets`
 
 For “make this image 3D,” ask **one** route question only when both results
-honestly fit: a generated static GLB, or editable parameterized Three.js code.
+honestly fit: a generated GLB built from the picture itself
+(`npx genex model --image <path>`), or editable parameterized Three.js code.
 If the request says procedural, parametric, code-built, reusable variations,
 or names a GLB, start the corresponding route directly. An image alone never
 auto-triggers the procedural lane. Player bodies, rigged characters/creatures,

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

@@ -40,7 +40,7 @@ copy demo architecture.
 | the game's own generated character—the player's body wherever a human body appears—or Meshy animation coverage beyond the stock pack: reference-informed A-pose concepts, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
 | a character/enemy needs motion the catalog lacks—a signature move, boss telegraph, death, full 8-way set, or the player's footage; free plan before spend | `$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, otherwise the player's `p.avatarUrl` VRM | `$genex-threejs-multiplayer` + `$genex-threejs-character-controller` |
-| enemies, NPCs, or creatures: rigged bipeds via `npx genex creature`; static plus procedural motion for other body shapes; collider, facing, hit reaction, death | `$genex-threejs-creatures` |
+| enemies, NPCs, or creatures: rigged bipeds via `npx genex creature`; non-biped body plans (quadruped, flier, serpent, aquatic, multi-leg) via `npx genex model rig` + `model animate`; static plus procedural motion only for shapes with no body plan; collider, facing, hit reaction, death | `$genex-threejs-creatures` |
 | cars, drones, vehicle physics, gearbox, character↔vehicle enter/exit | `$genex-threejs-vehicle-controllers` |
 | playable on phones: joystick, virtual buttons, drag zones, genre touch recipes, rotate-device overlay | `$genex-threejs-touch-controls` |
 | phone-survivable rendering: device tiers, DPR/shadow/post budgets, runtime governor, generated-asset rungs, Quality picker, dispose-on-swap | `$genex-threejs-adaptive-quality` |
@@ -52,7 +52,7 @@ copy demo architecture.
 | stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
 | eye adaptation, tone mapping, output color, LUT grading, and proven static grain | `$genex-threejs-exposure-color-grading` |
 | fixed-view screenshots, input direction, facing, temporal and budget evidence | `$genex-threejs-visual-validation` |
-| a static generated GLB for a concrete prop, vehicle, building, or non-rigged object | `$genex-ai-model` |
+| a generated GLB for a concrete prop, vehicle, building, or object — from text or a reference image (`--image`); split into named parts (`model segment`); rig + animate any mesh (`model rig` / `model animate`) | `$genex-ai-model` |
 | generated surface or terrain texture with real-world UV scale | `$genex-ai-texture` |
 | sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code in the scene—there is no sky command and no owning skill, so pick the technique this game needs |
 | poster, sign, sprite, decal, reference sheet, or other 2D art | `$genex-ai-image` |

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-creatures
-description: Build enemies and creatures that hold up in play — rigged Meshy bipeds via `npx genex creature` or static models with procedural motion, plus the mechanical floor every enemy owes the player regardless of rigging - a physics collider (no walking through bodies), verified facing, hit reactions, and a death moment. Load whenever the game has enemies, NPCs, or creatures.
+description: Build enemies and creatures that hold up in play — rigged Meshy bipeds via `npx genex creature`, non-biped bodies (quadrupeds, fliers, serpents) rigged via `npx genex model rig`, or static models with procedural motion, plus the mechanical floor every enemy owes the player regardless of rigging - a physics collider (no walking through bodies), verified facing, hit reactions, and a death moment. Load whenever the game has enemies, NPCs, or creatures.
 ---
 
 # Genex Three.js · Creatures & Enemies
@@ -21,10 +21,18 @@ the rig). Route by silhouette:
 - **Biped-shaped** (werewolf, orc, skeleton, gargoyle, zombie, knight — two
   legs, two arms, upright): the **rigged lane** below. Real skeleton, real
   library animations. This is the DEFAULT for every enemy that fits it.
-- **Everything else** (true quadrupeds, serpents, swarms, fliers mid-flight,
-  blobs): the **static + procedural lane** — `npx genex model` for the body,
+- **Non-biped body plans** (true quadrupeds, fliers, serpents, fish,
+  multi-legged things): the **model-rig route** — generate the body with
+  `npx genex model`, then `npx genex model rig <id>` (7 body plans:
+  quadruped/hexapod/octopod/avian/serpentine/aquatic and biped too) and
+  `npx genex model animate <rig-id> --preset walk`. A real skeleton and real
+  locomotion clips for exactly the shapes Meshy refuses — see
+  `$genex-ai-model` for the full flow, presets, and honest limits (avian rigs
+  have no preset clips; drive those bones in code).
+- **Everything outside both** (swarms, blobs, amorphous things — no body plan
+  to rig): the **static + procedural lane** — `npx genex model` for the body,
   motion authored in code. Say it honestly in the Assets table:
-  `hound: static + procedural — Meshy rigs bipeds only`. Never pretend a
+  `slime: static + procedural — no riggable body plan`. Never pretend a
   procedural creature is rigged.
 
 ## The rigged lane — `npx genex creature`
@@ -213,9 +221,10 @@ object's state field, never a per-frame broadcast.
 - **"Email not verified" (`email_verification_required`)** — hand over the
   verify link the CLI printed, wait, re-run.
 - **The creature came back standing when you wanted four legs** — that is the
-  documented platform limit, not a bad roll: re-rolling the prompt will not
-  produce a rigged quadruped. Switch that creature to the static + procedural
-  lane and say so in the Assets table.
+  documented Meshy limit, not a bad roll: re-rolling the prompt will not
+  produce a rigged quadruped there. Switch that creature to the model-rig
+  route (`npx genex model` → `model rig --type quadruped` →
+  `model animate --preset walk`) and say so in the Assets table.
 - **Clips look wrong on the body** (arms clip the torso on a bulky model) —
   pick a different library action id (`animations search`); never patch limbs
   post-mixer.