@genex-ai/cli-demo 1.19.0-dev.601 → 1.21.0-dev.603

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.19.0-dev.601",
+  "version": "1.21.0-dev.603",
   "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/controllers/quality/deadline.ts

@@ -0,0 +1,117 @@
+// Genex adaptive-quality: BOUNDED loading.
+//
+// WHY THIS EXISTS. Before 2026-09-07 there was no timeout anywhere in the
+// vendored kits — `grep -rn "setTimeout|AbortController|AbortSignal|timeout"`
+// across quality/ and character/ returned NOTHING. Every fallback in
+// `pick-asset.ts` lives inside a `catch`, so it advances on a REJECTION and
+// never on silence: a rung that hangs rather than 404s parks the boot forever,
+// and the player watches a black canvas with no error in the console. The one
+// local Opus run that shipped had to hand-write its own `withDeadline` in
+// `src/main.ts` to get around exactly this, which is the clearest possible
+// signal that the kit owed it.
+//
+// WHAT THIS BOUNDS, HONESTLY. `withDeadline` bounds the WAIT, not the fetch.
+// The abandoned request keeps running in the background until the browser gives
+// up on it; what changes is that the fallback chain ADVANCES instead of
+// stalling, which is the failure being fixed. Real cancellation needs the
+// caller to own the request (`fetchArrayBufferWithDeadline` below is that door,
+// for callers that can hand bytes to `loader.parse`).
+//
+// Zero dependencies and browser-only APIs, because this ships inside a player's
+// game bundle.
+
+/** Thrown when a load outlives its deadline. Distinct so a caller can tell a
+ *  timeout from a genuine 404 — they mean different things about the asset. */
+export class DeadlineError extends Error {
+  readonly label: string;
+  readonly ms: number;
+  constructor(label: string, ms: number) {
+    super(`[genex-quality] ${label} exceeded ${ms}ms`);
+    this.name = "DeadlineError";
+    this.label = label;
+    this.ms = ms;
+  }
+}
+
+/**
+ * Resolve `work`, or reject with `DeadlineError` after `ms`.
+ *
+ * The timer is always cleared, including on the success path: a pending timer
+ * keeps a closure over the promise alive, and twenty of them per boot is a leak
+ * a long session notices.
+ */
+export function withDeadline<T>(work: Promise<T>, ms: number, label: string): Promise<T> {
+  if (!(ms > 0) || !Number.isFinite(ms)) return work;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const bell = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new DeadlineError(label, ms)), ms);
+  });
+  return Promise.race([work, bell]).finally(() => {
+    if (timer !== undefined) clearTimeout(timer);
+  }) as Promise<T>;
+}
+
+/**
+ * A budget shared across a boot, so N slow assets cannot SERIALISE into a wait
+ * no per-attempt deadline would ever catch.
+ *
+ * A per-attempt deadline alone is not enough and the arithmetic is the reason:
+ * twenty props at a 15 s rung deadline is five minutes of black screen, with
+ * every individual attempt inside its limit. `remaining()` is what makes the
+ * ceiling the BOOT's rather than each asset's.
+ *
+ * Never returns a negative, and `expired()` is the honest question to ask
+ * before starting more optional work.
+ */
+export function createBootBudget(totalMs: number, now: () => number = () => Date.now()) {
+  const startedAt = now();
+  return {
+    remaining(): number {
+      return Math.max(0, totalMs - (now() - startedAt));
+    },
+    expired(): boolean {
+      return now() - startedAt >= totalMs;
+    },
+    /** The deadline to give the next attempt: its own cap, clipped to what is
+     *  left of the boot. */
+    slice(attemptMs: number): number {
+      return Math.min(attemptMs, Math.max(0, totalMs - (now() - startedAt)));
+    },
+  };
+}
+
+/**
+ * REAL cancellation, for a caller that can parse bytes itself:
+ *
+ *   const buf = await fetchArrayBufferWithDeadline(url, 15000);
+ *   const gltf = await loader.parseAsync(buf, "");
+ *
+ * Safe for OUR generated rungs specifically, because they embed their textures
+ * — a GLB with external resources would lose its base URL this way, which is
+ * why the loaders do NOT use this by default.
+ */
+export async function fetchArrayBufferWithDeadline(
+  url: string,
+  ms: number,
+  label = url,
+): Promise<ArrayBuffer> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), ms);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) throw new Error(`[genex-quality] ${label} → HTTP ${res.status}`);
+    return await res.arrayBuffer();
+  } catch (err) {
+    // An abort is a deadline, and the caller must be able to tell the two apart.
+    if (err instanceof Error && err.name === "AbortError") throw new DeadlineError(label, ms);
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Per-attempt defaults. A rung is small by construction; the original is the
+ *  archival asset and is allowed to be slower, because reaching it at all means
+ *  every rung already failed. */
+export const RUNG_DEADLINE_MS = 15_000;
+export const ORIGINAL_DEADLINE_MS = 30_000;

package/templates/controllers/quality/pick-asset.ts

@@ -9,6 +9,7 @@
 // whose backfill hasn't run). loadTextureWithFallback retries the bare URL on
 // a rung failure, so the worst case is today's behavior — never a broken boot.
 import type { QualityTier } from './tier.ts';
+import { withDeadline, RUNG_DEADLINE_MS, ORIGINAL_DEADLINE_MS } from './deadline.ts';
 
 // Host-agnostic on purpose: each stand serves generated assets from its own
 // domain (prod assets.genex.technology, dev assets.auras.cc), and baking one
@@ -56,23 +57,28 @@ export async function loadTextureWithFallback<T>(
   url: string,
   tier: QualityTier,
   load: (resolvedUrl: string) => Promise<T>,
-  opts?: { ktx2Load?: (resolvedUrl: string) => Promise<T> },
+  opts?: { ktx2Load?: (resolvedUrl: string) => Promise<T>; deadlineMs?: number },
 ): Promise<T> {
+  // EVERY RUNG IS BOUNDED. The fallbacks below live in `catch`, so they advance
+  // on a rejection and never on silence — a rung that HANGS rather than 404s
+  // parked the boot forever, with no error in the console. `deadlineMs: 0`
+  // opts out.
+  const rungMs = opts?.deadlineMs ?? RUNG_DEADLINE_MS;
   const picked = pickAsset(url, tier);
   if (picked !== url && opts?.ktx2Load) {
     try {
-      return await opts.ktx2Load(`${picked}.ktx2`);
+      return await withDeadline(opts.ktx2Load(`${picked}.ktx2`), rungMs, `ktx2 texture ${picked}`);
     } catch {
-      console.warn(`[genex-quality] ktx2 variant missing for ${picked} — using the browser-decodable rung`);
+      console.warn(`[genex-quality] ktx2 variant missing or too slow for ${picked} — using the browser-decodable rung`);
     }
   }
-  if (picked === url) return load(url);
+  if (picked === url) return withDeadline(load(url), opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS, `texture ${url}`);
   try {
-    return await load(picked);
+    return await withDeadline(load(picked), rungMs, `texture rung ${picked}`);
   } catch {
-    // Missing rung (old asset, un-backfilled env) — degrade to the original.
-    console.warn(`[genex-quality] rung missing for ${url} — loading the original`);
-    return load(url);
+    // Missing or hung rung (old asset, un-backfilled env) — degrade to the original.
+    console.warn(`[genex-quality] rung missing or too slow for ${url} — loading the original`);
+    return withDeadline(load(url), opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS, `texture ${url}`);
   }
 }
 
@@ -130,22 +136,28 @@ export async function loadModelWithFallback<T>(
   url: string,
   tier: QualityTier,
   load: (resolvedUrl: string) => Promise<T>,
-  opts?: { ktx2?: boolean },
+  opts?: { ktx2?: boolean; deadlineMs?: number },
 ): Promise<T> {
+  // See the note in `loadTextureWithFallback`: without a deadline a hung rung
+  // never reaches these `catch` blocks and the boot never finishes. The
+  // original gets a longer one — reaching it at all means every rung failed,
+  // and it is the archival asset.
+  const rungMs = opts?.deadlineMs ?? RUNG_DEADLINE_MS;
+  const originalMs = opts?.deadlineMs ?? ORIGINAL_DEADLINE_MS;
   const withKtx2 = pickModel(url, tier, opts);
   const universal = pickModel(url, tier, { ktx2: false });
   if (withKtx2 !== universal) {
     try {
-      return await load(withKtx2);
+      return await withDeadline(load(withKtx2), rungMs, `ktx2 model rung ${withKtx2}`);
     } catch {
-      console.warn(`[genex-quality] ktx2 model rung missing for ${url} — trying the universal rung`);
+      console.warn(`[genex-quality] ktx2 model rung missing or too slow for ${url} — trying the universal rung`);
     }
   }
-  if (universal === url) return load(url);
+  if (universal === url) return withDeadline(load(url), originalMs, `model ${url}`);
   try {
-    return await load(universal);
+    return await withDeadline(load(universal), rungMs, `model rung ${universal}`);
   } catch {
-    console.warn(`[genex-quality] model rung missing for ${url} — loading the original`);
-    return load(url);
+    console.warn(`[genex-quality] model rung missing or too slow for ${url} — loading the original`);
+    return withDeadline(load(url), originalMs, `model ${url}`);
   }
 }

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

@@ -119,11 +119,12 @@ vendored code from memory of another engine.
 
 | Work needed | Load |
 | --- | --- |
+| **your first `npx genex model` or `npx genex character` this session** — the command, what comes back, how to scale and ground it, and what to do when a lane is dead. One page, thirty seconds. The full lanes below are long; measured across 105 generation-lane invocations, 94% ran without the owning skill open, and placement is where that showed | `$genex-lane-card` |
 | shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action, mouse-look, the screen-direction contract for hand-rolled steering/pan/look input signs, 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` |
 | **attacking, casting, aiming or reloading WHILE moving** — any action the legs must keep running under; a weapon carry stance over stock locomotion; a wind-up the character holds while walking | `$genex-threejs-character-controller` (`references/animations.md`, upper-body layering) |
 | dash, dodge, roll, blink, backstep, a lunging attack — any burst that moves the character itself | `$genex-threejs-character-controller` (`references/tuning-and-presets.md`, dash recipe) |
-| 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` |
+| 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` (first time this session: `$genex-lane-card`) |
 | 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`; 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` |
@@ -139,7 +140,8 @@ 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` |
-| 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` |
+| **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` (first time this session: `$genex-lane-card`) |
 | 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` |
@@ -195,9 +197,14 @@ its local path for code-built ones — the table is where the per-object decisio
 lives, and a table with no generated row records
 `Generation: none — <why code alone reaches the bar here>` beside it. Mixing
 both in one scene is the normal way to build, never a fallback. In focused
-work, stay inside the touched scope. Run independent planned generations with
-`--no-wait`, scaffold while they land, and preserve their IDs, URLs, and
-wiring state.
+work, stay inside the touched scope. Generate in batches you can finish. The first
+batch is the smallest set that makes the scene read — the player's body,
+whatever the request names, and the first thing they walk up to — enqueued
+together with `--no-wait` while you scaffold. Before a second batch starts,
+every id in the first is collected with `npx genex wait --all`, loaded from a
+file in `src/`, and seen in a capture. A batch begun while the previous one is
+still uncollected is how a game ends up with an asset library and an empty
+world. Preserve every id, URL and wiring state across a compaction.
 
 ## 5. Execute by working mode
 
@@ -355,13 +362,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-lane-card/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: genex-lane-card
+description: The asset belt on one page — the command, what comes back, how to place it so it is not a speck or a wall, and what to do when a lane is dead. Read this before your first `npx genex model` or `npx genex character`. The full lanes are `$genex-ai-model` and `$genex-ai-character`; this card is what you need to not get it wrong.
+---
+
+# Genex · Lane card
+
+## Object → mesh
+
+```bash
+npx genex model "weathered oak barrel, iron bands, damp staves" --no-wait
+npx genex wait --all      # prints every id this project enqueued, with its URL
+```
+
+A specific prompt beats a noun: "barrel" gives you a barrel-shaped guess, the
+line above gives you the one in your scene. The URL is permanent — paste it into
+the loader, never download it into the repo.
+
+## Player body → character
+
+```bash
+npx genex character "stylized desert courier, layered dust-worn cloth"
+npx genex character preview <concept-id> --candidate 1 --user-approved
+npx genex character finalize <preview-id> --user-approved --approve-remesh 10000
+npx genex controller character --character <id>   # the whole integration
+```
+
+Look at the three concepts, pick the strongest yourself, say which and why, and
+keep going. Never foreground-`wait` on a character stage — they take minutes.
+
+## Place it — a GLB arrives at any scale, with any origin
+
+```ts
+const o = gltf.scene;
+const box = new THREE.Box3().setFromObject(o);
+const size = new THREE.Vector3();
+box.getSize(size);
+o.scale.multiplyScalar(TARGET_HEIGHT_M / size.y);  // the metres you want
+box.setFromObject(o);                              // re-measure, then ground it
+o.position.y -= box.min.y;
+scene.add(o);
+```
+
+Skip this and the mesh is a speck or a wall — it is the single most common way a
+generated asset ships broken. Rigged bodies mismeasure here; those go through
+the controller's own boot path, not this snippet.
+
+## The one rule
+
+An asset is not done when the command exits. It is done when something in
+`src/` loads it, you have run the game, and you have LOOKED at it. A generation
+nobody wired is money spent on nothing — `npx genex wait --all` marks a row
+`wired` only once its URL appears in your source.
+
+## When a lane is dead
+
+A lane whose provider wallet is empty fails every call and refunds every one.
+`npx genex doctor` prints each lane live/mock/paused with its credit state. If a
+lane is red: **build that thing in code and move on** — do not re-run it, and do
+not stall the game waiting for it. Say in chat what you fell back to.

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