@genex-ai/cli-demo 1.19.0-dev.601 → 1.20.0-dev.602

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.19.0-dev.601",
+  "version": "1.20.0-dev.602",
   "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/controllers/character/meshy/meshy-loader.ts

@@ -23,7 +23,8 @@ export interface MeshyCharacterManifest {
   characterId: string;
   revision: number;
   manifestVersion: number;
-  rig: "meshy-biped";
+  /** `meshy-biped`, or `uthana-biped` for a body imported with `genex character import` (same manifest shape). */
+  rig: "meshy-biped" | "uthana-biped";
   controllerPack?: {
     key: string;
     version: number;
@@ -95,7 +96,7 @@ function validateManifest(value: unknown): MeshyCharacterManifest {
   if (
     !manifest ||
     manifest.schema !== 1 ||
-    manifest.rig !== "meshy-biped" ||
+    (manifest.rig !== "meshy-biped" && manifest.rig !== "uthana-biped") ||
     !manifest.model?.url ||
     !manifest.model.skeletonSignature ||
     !Array.isArray(manifest.clips) ||

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

@@ -101,12 +101,13 @@ they crop well to a portrait and read as one set across the cast.
 npx genex character preview <concept-id> --candidate <1|2|3> --user-approved
 ```
 
-Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
-front, back, left, and right views and report its measured face count.
-Preserve that model in R2. The 10,000-face triangle remesh—not the
-high-detail source—is rigged and animated. In the default lane, proceed to
-the remesh directly; when the player explicitly requested a custom character,
-ask for their explicit approval first. (For the custom lane's approvals, use
+Meshy 7 Image-to-3D (Ultra, 4k textures by default) first produces an
+unremeshed high-detail model. Show its front, back, left, and right views and
+report its measured face count. Preserve that model in R2. A triangle remesh
+at the face budget you approve—not the high-detail source—is rigged and
+animated. In the default lane, proceed to the remesh directly; when the player
+explicitly requested a custom character, ask for their explicit approval
+first. (For the custom lane's approvals, use
 your question tool when you have one; if you have none, a short numbered list
 in chat.)
 
@@ -122,10 +123,10 @@ npx genex character finalize <preview-id> \
   --animation <action-id>
 ```
 
-`--animation` is repeatable. Finalization uses Meshy 6, creates the approved
-10k triangle remesh, rigs it, adds the immutable preview-reviewed neutral-v3
-idle/walk/run/crouch/jump controller pack, and stores the source, remesh, rig,
-and clips at permanent Genex asset URLs. It prints the complete Genex-credit
+`--animation` is repeatable. Finalization creates the approved triangle
+remesh from the Meshy 7 preview, rigs it, adds the immutable preview-reviewed
+neutral-v3 idle/walk/run/crouch/jump controller pack, and stores the source,
+remesh, rig, and clips at permanent Genex asset URLs. It prints the complete Genex-credit
 quote before enqueueing. The Meshy API key remains server-side; never ask the
 user for one or call Meshy directly from game code.
 
@@ -133,18 +134,40 @@ Meshy's public API performs automatic rigging. The manual joint-marker step
 shown in Meshy Web is not exposed through that API, so do not claim that this
 part of the hosted workflow is reproduced.
 
-The legacy one-shot text workflow is explicit and does not masquerade as the
-reviewed image-first path:
+The one-shot text workflow is explicit and does not masquerade as the
+reviewed image-first path. It runs the same Meshy 7 (Ultra, 4k) — the only
+thing it skips is the review:
 
 ```bash
 npx genex character "compact fantasy knight" --direct-text
 ```
 
+## The quality knobs are yours to set
+
+Every lane runs Meshy 7 with Ultra and 4k textures unless you say otherwise,
+and every knob is priced in the quote the command prints before enqueueing.
+Choose per role, and say the choice in one line of chat:
+
+- `--approve-remesh <faces>` (finalize) / `--polycount <faces>` (one shot):
+  the rigging copy's face budget, 10000-100000. **10000** for anything seen
+  in a crowd or at a distance; **20000-30000** for the player's body in a
+  third-person game; **50000+** only for a hero seen in close-up cutscenes.
+  Mobile budgets favour the low end. The number moves no cost.
+- `--texture 2k|4k|8k` (preview / one shot): 4k is the default; 8k (+5
+  credits) only for a body the camera sits on in close-up; 2k for crowds.
+- `--no-ultra` (preview / one shot): −5 credits and less surface detail —
+  crowd enemies and stand-ins, never the player's body.
+- `--pose a-pose|t-pose` (one shot): the preferred rest pose; the other
+  stays the structural-QA fallback.
+- `--height <metres>`: 0.5-3, default 1.7.
+
 Useful options:
 
 ```bash
-npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --height 1.7
+npx genex character preview <concept-id> --candidate 2 --user-approved --texture 8k
+npx genex character finalize <preview-id> --user-approved --approve-remesh 30000 --height 1.7
 npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 --animation 466 --no-wait
+npx genex character "market guard" --direct-text --polycount 10000 --no-ultra --texture 2k
 npx genex wait <generation-id>
 ```
 
@@ -153,10 +176,10 @@ npx genex wait <generation-id>
 compatibility path. The guided parity workflow always installs neutral-v3.
 `--no-wait` returns a generation id for `genex wait`; it does not create a
 second paid request. In the default lane, `--user-approved` and
-`--approve-remesh 10000` record the pick you made and announced after showing
+`--approve-remesh <faces>` record the pick you made and announced after showing
 the real images. When the player explicitly requested a custom character,
 never add `--user-approved` until they have actually seen and selected the
-candidate, and never add `--approve-remesh 10000` until they have seen the
+candidate, and never add `--approve-remesh <faces>` until they have seen the
 four high-detail views and measured face count.
 
 Before handoff, capture idle, walk, run, crouch-idle, crouch-move, and jump.
@@ -165,6 +188,35 @@ shrugging palms-up poses, permanently raised elbows, or a gait whose
 upper-body style contradicts the requested character. “No T-pose” is not
 an animation-quality check.
 
+## Import a character the player already has (`character import`)
+
+When the player hands you a humanoid mesh — their own Blender character, a
+bought asset, an export from another tool — **import it, never regenerate
+it**. The upload is free; Uthana then auto-rigs it (one paid call, finger
+joints included) and it becomes a character of theirs:
+
+```bash
+npx genex character import ./assets/knight.glb --height 1.8
+npx genex character animate <character-id> --locomotion --no-wait   # the 16-clip walk/run set
+npx genex controller character --character <character-id>          # once locomotion lands
+```
+
+What Uthana needs: a **biped humanoid** in a **T- or A-pose, feet on the
+ground, facing +Z**, as a `.glb` under **30 MB** (textures are the bulk —
+shrink them, not the mesh). Non-biped bodies go through `npx genex model
+import` + `npx genex model rig` (7 body plans) instead. `--no-fingers` skips
+finger joints when the hands are blobs (Uthana warns poor finger geometry
+lowers rig quality).
+
+An imported character is **Uthana-rigged**: `character animate` in plain
+words, `--locomotion` and `--video` all work on it, and the manifest reads
+`rig: "uthana-biped"`. The Meshy catalog (`--animation <id>`) and the
+neutral-v3 controller pack do **not** apply — those are Meshy-rig clips — so
+run `--locomotion` before installing the controller, or the body stands
+still. `--texture`, `--no-ultra`, `--pose` and `--polycount` are Meshy
+generation knobs and are refused here: an import keeps the mesh exactly as it
+is.
+
 ## Search first; use action IDs
 
 ```bash

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

@@ -66,6 +66,26 @@ 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.
 
+## Bring your own mesh (`model import`)
+
+A model the player already has — a Blender export, a bought asset, a file
+from another tool — is **imported, never rebuilt**. Importing is free and
+makes it a model of theirs, so every id-only lane works on it: `model rig`,
+`model animate`, `model segment`, `blender import`, and "Use in game" on the
+dashboard.
+
+```bash
+npx genex model import ./assets/hero-cart.glb
+```
+
+- `.glb` only (binary glTF 2.0), up to 64 MB. A `.gltf` + `.bin` pair or an
+  FBX is exported as one `.glb` first — in Blender, File → Export → glTF 2.0
+  with format "glTF Binary".
+- The file is checked (magic, version, triangle geometry) before the row
+  completes; a bad file is refused and nothing is charged.
+- A humanoid that should walk goes through `$genex-ai-character`'s
+  `character import` instead — same upload, plus a Uthana auto-rig.
+
 ## Split into parts (`model segment`)
 
 ```bash
@@ -256,6 +276,18 @@ scene is a ghost: players and objects pass straight through it.
 
 - `--image <path|url>` — build from a reference image (local file ≤4 MB, or a
   generated-asset URL); the prompt becomes optional.
+- **Quality knobs** (Tripo H3.1; each is priced in the quote, choose per
+  asset and say it in one line): `--texture standard|detailed|none` (detailed
+  is the default and +10 credits over standard; `none` is geometry only, for
+  something you texture in code), `--geometry detailed` (+20 — a hero prop
+  the camera sits on; never for a crate), `--quad` (+5, quad-dominant mesh
+  for anything you will deform or edit further; face limit ≤150000),
+  `--low-poly` (+10, smart low-poly topology — the game-ready choice for
+  props that appear in numbers), `--parts` (+20, separated named parts at
+  generation — cheaper than `model segment` when you know up front you need
+  doors, wheels, magazines), `--face-limit <n>` (1000-2000000, default
+  150000; the raw cap — the game still loads the @2048/@1024 rungs),
+  `--auto-size` (real-world metres by AI estimate).
 - `--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.

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

@@ -139,6 +139,7 @@ vendored code from memory of another engine.
 | 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 model the player already has** — a `.glb` they exported, bought or made elsewhere: it is IMPORTED, never rebuilt. `npx genex model import <file.glb>` (free) for props and non-biped bodies (then `model rig`/`model animate`), `npx genex character import <file.glb>` for a humanoid that should walk (Uthana auto-rig, then `character animate --locomotion`) | `$genex-ai-model` · `$genex-ai-character` |
 | the default for a concrete object the player looks at up close: a generated GLB for a 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`). A space routed to code above does NOT settle these: a village's ground plan can be code while the forge you walk up to is generated | `$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 |
@@ -355,13 +356,14 @@ your pick. The announced pick carries the lane:
 
 `npx genex character preview <concept-id> --candidate <1|2|3> --user-approved`
 
-Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
+Meshy 7 Image-to-3D first produces an unremeshed high-detail model. Show its
 front, back, left, and right views and report its measured face count.
-Preserve that model in R2. The 10,000-face triangle remesh—not the high-detail
-source—is rigged and animated. In the default lane, the pick authorizes that
-remesh:
+Preserve that model in R2. A triangle remesh at the face budget you approve
+(10000-100000; 10000 for crowds, 20000-30000 for a third-person player
+body)—not the high-detail source—is rigged and animated. In the default lane,
+the pick authorizes that remesh:
 
-`npx genex character finalize <preview-id> --user-approved --approve-remesh 10000 [--animation <action-id>…]`
+`npx genex character finalize <preview-id> --user-approved --approve-remesh <faces> [--animation <action-id>…]`
 
 When the player explicitly requested a custom character, keep the existing
 two stops: wait for their explicit candidate selection before Image-to-3D,

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

@@ -85,7 +85,8 @@ npx genex controller character --character <character-id>
 
 Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
 front, back, left, and right views and report its measured face count. Preserve
-that model in R2. The 10,000-face triangle remesh—not the high-detail
+that model in R2. The triangle remesh at the approved face budget (10,000
+by default; up to 100,000 for a hero)—not the high-detail
 source—is rigged and animated. In the default lane proceed to it directly;
 for a player-requested custom character, ask for their explicit approval
 first (question tool when you have one; a short numbered list in chat

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

@@ -29,6 +29,10 @@ the rig). Route by silhouette:
   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).
+- **A mesh the player already has** (their own creature file): `npx genex
+  model import <file.glb>` first — free — then the same routing by
+  silhouette: biped → `npx genex character import` (Uthana auto-rig),
+  anything else → `npx genex model rig`. Never rebuild what they handed you.
 - **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:
@@ -53,7 +57,10 @@ npx genex creature "hulking bone seraph, tattered wing membranes, upright stance
 ```
 
 Each creature is one Assets-table row (visible spend — the usual budget
-rules). The result is a rigged GLB whose clips play on a standard
+rules). It runs Meshy 7 like the player body; the knobs are yours: a crowd
+enemy is `--polycount 10000 --no-ultra --texture 2k`, a boss seen in close-up
+`--polycount 30000` (`--texture 8k` if the camera lingers), `--pose t-pose`
+when a rig keeps failing structural QA in a-pose. The result is a rigged GLB whose clips play on a standard
 `THREE.AnimationMixer`; Meshy limb rotations play unchanged — never apply
 post-mixer limb corrections. Prompt the body UPRIGHT and unpropped (held
 props fuse into bodies); prompt "facing the viewer" but never trust it —

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -37,7 +37,8 @@ overlapping props or straps can fuse into the character or hide a limb.
 
 Meshy Image-to-3D first produces an unremeshed high-detail model. Show its
 front, back, left, and right views and report its measured face count. Preserve
-that model in R2. The 10,000-face triangle remesh—not the high-detail
+that model in R2. The triangle remesh at the approved face budget (10,000
+by default; up to 100,000 for a hero)—not the high-detail
 source—is rigged and animated. In the default lane the remesh proceeds
 directly; for a player-requested custom character, wait for their explicit
 approval first (question tool when you have one; a short numbered list in

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

@@ -24,13 +24,28 @@ npx genex character preview <concept-id> --candidate 2 --user-approved
 # → a 3D preview of that one, four views. Show it; wait for approval.
 
 npx genex character finalize <preview-id> --user-approved --approve-remesh 10000
-# → the rigged, game-ready character.
+# → the rigged, game-ready character at that face budget.
 ```
 
 Each step needs the previous step's generation id. The approval flags are not
 ceremony: they record that a person actually looked and chose, and each step
 costs credits.
 
+## The knobs (Meshy 7 on every lane)
+
+Ultra and 4k textures are the defaults; every knob is priced in the quote.
+Pick per role and say so in one line:
+
+- `--approve-remesh <faces>` (finalize) / `--polycount <faces>` (one shot):
+  the rigging copy's face budget, 10000-100000 — 10000 for crowds and
+  distance, 20000-30000 for a third-person player body, 50000+ only for a
+  close-up hero. Moves no cost.
+- `--texture 2k|4k|8k` (preview / one shot): 8k is +5 credits, for close-ups.
+- `--no-ultra` (preview / one shot): −5 credits, less surface detail — stand-ins
+  and crowd enemies.
+- `--pose a-pose|t-pose` (one shot): the preferred rest pose.
+- `--height <metres>`: 0.5-3, default 1.7.
+
 ## One shot
 
 When nobody is choosing — a background NPC, a quick test:
@@ -41,7 +56,21 @@ npx genex creature "hulking bone seraph, upright stance"
 ```
 
 `creature` is the same lane with enemy defaults: no approval steps, no player
-controller pack. Biped-shaped bodies only.
+controller pack (and priced without one). Biped-shaped bodies only. The knobs
+above apply: a crowd enemy is `--polycount 10000 --no-ultra --texture 2k`.
+
+## Import a character the user already has
+
+```bash
+npx genex character import ./knight.glb --height 1.8   # free upload + Uthana auto-rig (finger joints; --no-fingers skips them)
+npx genex character animate <id> --locomotion          # then the walk/run set — an import has no clips yet
+```
+
+Biped humanoid, T- or A-pose, feet on the ground, facing +Z, `.glb` ≤ 30 MB.
+**Never rebuild a mesh the user gives you** — import it. The result is a
+Uthana-rigged body: verbs, `--locomotion` and `--video` work; the Meshy
+catalog and controller pack do not. Non-biped bodies: `npx genex model
+import` + `npx genex model rig`.
 
 ## Animating it
 
@@ -75,9 +104,11 @@ look here first — a library clip costs nothing to generate.
 
 ## Cost
 
-Typical: **15** concept · **20** preview · **30** finalize · **50** one-shot
-character · **26 per clip** for a generated move · **free** for a library
-search. Live prices and your balance: `npx genex doctor`.
+Typical: **32** concept · **41** preview · **29** finalize · **64** one-shot
+character · **46** creature · **18** import (Uthana auto-rig; the upload is
+free) · **46 per clip** for a generated move · **free** for a library search
+(1 credit = $0.01). `--texture 8k` adds 6, `--no-ultra`
+takes 6 off. Live prices and your balance: `npx genex doctor`.
 
 ## Waiting
 

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

@@ -21,6 +21,17 @@ npx genex model --image ./reference-photo.jpg       # build it FROM an image; pr
 Blocks until ready, saves the GLB into `./assets`, and prints the path. Wire the
 local path; the URL printed beside it is provenance, not hosting.
 
+## Bring your own mesh
+
+```bash
+npx genex model import ./hero-cart.glb           # free — a file you already have becomes a model of yours
+```
+
+`.glb` only, ≤ 64 MB (export a `.gltf`/FBX as one binary `.glb` first). The
+import is free and checked before it completes; after it, `segment`, `rig`,
+`animate` and `character import` all take its id. **Never rebuild a mesh the
+user hands you** — import it.
+
 ## Mesh lanes
 
 Each takes the **generation id** of a previous model — never a URL.
@@ -38,15 +49,17 @@ npx genex model animate <rig-id> --preset walk,run
 ## Options
 
 - `--image <path|url>` — build the model from a reference image (local file ≤ 4 MB, or a previous generation's URL). The prompt becomes optional.
+- **Quality knobs** (Tripo H3.1, each priced in the quote — pick per asset, say it in one line): `--texture standard|detailed|none` (detailed default, +10 over standard; none = geometry only), `--geometry detailed` (+20, hero pieces only), `--quad` (+5, for meshes you will edit; face limit ≤150000), `--low-poly` (+10, game-ready topology for props in numbers), `--parts` (+20, named parts at generation), `--face-limit <n>` (1000-2000000, default 150000), `--auto-size` (real-world metres).
 - `--out-dir <dir>` — where the file lands (default `./assets`).
 - `--no-download` — print the URL only.
 - `--no-wait` — enqueue and return; pick it up with `npx genex wait <id>`.
 
 ## Cost
 
-From **35 credits** a model (**46** from a reference image) · **46** segment ·
-**29** rig · **12 per clip** for animate (1 credit = $0.01). Live prices and your
-balance: `npx genex doctor`.
+From **35 credits** a model (**46** from a reference image; `--texture standard`
+**23**, `--geometry detailed` **58**, `--low-poly` **46**, `--parts` **58**) ·
+**46** segment · **29** rig · **12 per clip** for animate (1 credit = $0.01).
+Live prices and your balance: `npx genex doctor`.
 
 ## Waiting