@genex-ai/cli-demo 1.31.1 → 1.32.0-dev.650

package/templates/skills/genex-getting-started/SKILL.md

@@ -161,7 +161,7 @@ downloads the game too, binary assets and all:
 
 ```bash
 mkdir my-game && cd my-game
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 npm install
 ```
 
@@ -225,7 +225,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

package/templates/skills/genex-lane-card/SKILL.md

@@ -0,0 +1,78 @@
+---
+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.
+
+## Generate in batches you can finish
+
+The belt has a **shipping ratchet**: generations that have not been shown to the
+player are counted, and the count resets to zero every time you `npx genex
+preview`. Hit it and the command refuses with the number and the fix.
+
+It is not a spend limit and there is no total — preview between batches and
+generate as much as the game needs. What it stops is one thing: fanning out a
+whole cast or a shelf of props before the player has seen any of it. If you are
+refused, you are not out of anything. You have work that nobody has looked at.
+
+```bash
+npx genex model "..." --no-wait   # a batch you can finish
+npx genex wait --all              # collect it
+# wire it, then:
+npx genex preview                 # free, seconds — and the count is zero again
+```
+
+## 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-adaptive-quality/SKILL.md

@@ -217,6 +217,27 @@ the same ladder through
 KTX2-capable games can also pass `ktx2Load` to `loadTextureWithFallback` so
 textures use their `.ktx2` variants.
 
+**A texture that arrived through a `.ktx2` rung is NOT drawable.** Its `.image`
+is `{ width, height, mipmaps }`, never an `HTMLImageElement` — so
+`ctx.drawImage(tex.image, …)` throws *"The provided value is not of type
+'(CSSImageValue or HTMLCanvasElement or …)'"*. MEASURED 2026-09-07: a village
+build wrote its own `capTextures()` pass to cap every texture's long edge and
+cast `tex.image as CanvasImageSource` to silence the type error. All ten of its
+generated buildings and both villager bodies then failed to load behind a
+swallowed warning — a fully generated, fully wired world that rendered EMPTY,
+and scored 1/9 with the assets sitting in R2. **Do not hand-roll a texture
+downscaler: the rungs ARE the downscaler**, and `@1024` already did it before
+the bytes left our side. If you must touch pixels, skip the compressed ones
+first — `if ((tex as THREE.CompressedTexture).isCompressedTexture) return;`.
+
+Every generated GLB ladders — `genex model` including its `segment` / `rig` /
+`animate` outputs, and generated characters. If `pickModel` hands a generated
+model URL back unchanged, this game's vendored kit predates that role: the
+quality kit is copied into the game ONCE and is yours from then on, so it
+never updates itself. Re-vendor it with `npx genex controller quality --force`
+(that overwrites the kit files — keep your own edits, if any, before running
+it), and the ladder starts resolving for those models.
+
 ## Quality picker in settings
 
 The pause/settings screen (see `$genex-threejs-game-ui`) always carries a

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
@@ -135,6 +136,9 @@ fork as a migration strategy. Install a fresh copy elsewhere and port only the n
 ## Minimal wiring
 
 ```ts
+import { initEmbed, waitForPlayer } from "@genex-ai/embed-sdk";
+import { GENEX } from "./genex.config";
+import * as THREE from "three";
 import { PhysicsWorld } from "./controllers/shared/physics-world.ts";
 import { CharacterController } from "./controllers/character/character-controller.ts";
 import { CharacterAnimations } from "./controllers/character/character-animations.ts";
@@ -145,7 +149,15 @@ import { createAimCue } from "./controllers/character/aim-cue.ts";
 import { KeyboardInput } from "./controllers/character/keyboard-input.ts";
 import { loadPlayerCharacter } from "./controllers/character/player-character.ts";
 import { capsuleFromModel } from "./controllers/character/vrm/capsule-fit.ts";
-import { waitForPlayer } from "@genex-ai/embed-sdk";
+
+initEmbed({ slug: GENEX.slug, apiUrl: GENEX.apiUrl, dashboardOrigins: GENEX.dashboardOrigins }); // FIRST — before any await
+
+// draw first; identity takes seconds on a hosted page
+const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias, ...depthRendererOptions() }); // tier + depthRendererOptions: the quality kit
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(60, innerWidth / innerHeight, near, far);
+document.body.appendChild(renderer.domElement);
+renderer.render(scene, camera); // a frame is on screen before anything below is awaited
 
 const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run before this resolves
 
@@ -154,13 +166,13 @@ const physics = await PhysicsWorld.create(); // nothing RAPIER-related may run b
 // (with that character's exact-rig clips and locomotion profile), and falls
 // back to the visiting player's own profile avatar when it isn't — retargeting
 // the bundled core library plus any packs installed by `genex controller
-// anims`. `user.avatarUrl` comes from the embed identity
-// ($genex-threejs-embed-auth boots before this) and is used only in that
+// anims`. `user.avatarUrl` comes from the embed identity (the `initEmbed`
+// call above — $genex-threejs-embed-auth owns it) and is used only in that
 // fallback lane; the baked `./assets/avatar.vrm` covers local dev and load
 // failures. WRITE THIS ONCE: when the generated character lands mid-build,
 // `genex controller character --character <id>` drops the manifest in and the
 // next reload swaps the body. Nothing below changes.
-const { user } = await waitForPlayer();          // from "@genex-ai/embed-sdk"
+const { user } = await waitForPlayer();          // identity, awaited HERE — where the avatar is needed, never as the first line of the boot
 const player = await loadPlayerCharacter({ avatarUrl: user.avatarUrl });
 
 const fit = capsuleFromModel(player.scene);    // collider fits THIS body's bounds

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-embed-auth/SKILL.md

@@ -54,6 +54,14 @@ initEmbed({
 });
 ```
 
+**Create the renderer and draw a frame BEFORE you await identity; `await
+waitForPlayer()` only where you need the name or the token.** On a hosted page
+identity takes seconds (the dashboard handshake, or the standalone bounce), so
+a `main.ts` whose first statement is `const { user } = await waitForPlayer()`
+shows black for all of them — and forever when `initEmbed()` was never called,
+because nothing else resolves that promise. Renderer, scene, camera, first
+frame, then the await, down where the name or the avatar is actually used.
+
 Also give `<body>` a dark background in `index.html` (e.g.
 `<body style="margin:0;background:#080a14">`) — it makes the pre-boot frame
 (before any JS runs) match the SDK's own loading overlay instead of flashing

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -134,14 +134,55 @@ overlay — HTML/CSS on top of the canvas, not text sprites inside the scene:
 
 ```css
 #ui { position: fixed; inset: 0; pointer-events: none; font-variant-numeric: tabular-nums; }
-#ui button, #ui .screen { pointer-events: auto; }
+/* Layout belongs to the SHOWN screen only. Never `#ui .screen { display: … }`:
+   that overrides the browser's `[hidden] { display: none }`, and every hidden
+   screen is laid out full-viewport, invisible, on top of the one that is up. */
+#ui .screen:not([hidden]) { display: flex; }
+/* Clickable only while shown (`.is-on` is the shown class — Motion, below). */
+#ui .screen.is-on, #ui #hud button { pointer-events: auto; }
 ```
 
 `pointer-events: none` on the root keeps the canvas playable; re-enable it only
-on elements that are actually clickable. Keep ALL layout in CSS — never
-position UI by mutating inline pixel styles per frame. In-world (diegetic) UI —
-a health bar floating over an enemy, a scoreboard mesh in a stadium — is the
-exception for things that belong to the world, not the default.
+on elements that are actually clickable — and only while they are on screen.
+Keep ALL layout in CSS — never position UI by mutating inline pixel styles per
+frame. In-world (diegetic) UI — a health bar floating over an enemy, a
+scoreboard mesh in a stadium — is the exception for things that belong to the
+world, not the default.
+
+### Inactive screens are gone, not see-through
+
+An invisible screen that is still laid out is a click trap nobody can see: the
+title's Start button renders, the pointer hovers it, and the click lands on a
+transparent pause card sitting last in DOM order. Three rules:
+
+1. **An inactive screen is `display: none`** — via `hidden` or a class — never
+   merely `opacity: 0`. And NEVER set `display` on the `.screen` selector
+   itself: `.screen { display: flex }` beats the browser's `[hidden]` rule, so
+   `hidden` stops hiding anything. Put `display: flex` on
+   `.screen:not([hidden])` or on the shown class.
+2. **`pointer-events: auto` belongs only to the screen that is currently
+   shown.** An invisible screen with clickable descendants swallows every click
+   meant for the screen under it, so scope `pointer-events` to `.screen.is-on`
+   (and to HUD controls) — never to `#ui .screen` or `#ui button` at large.
+3. **The smoke check for every boot/title/pause screen:** for each visible
+   button, `document.elementFromPoint(cx, cy)` at its centre must return the
+   button or one of its descendants. A top hit whose effective (inherited)
+   opacity is 0 is a defect, not a styling choice — some screen is laid out
+   over the one the player sees. One paste in the console:
+
+   ```js
+   [...document.querySelectorAll("#ui button")].filter((b) => b.getClientRects().length).map((b) => {
+     const r = b.getBoundingClientRect(), top = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+     let o = 1; for (let e = top; e; e = e.parentElement) o *= +getComputedStyle(e).opacity;
+     const ok = !!top && b.contains(top);
+     return { button: b.textContent.trim(), ok, coveredBy: ok ? null : top?.closest(".screen")?.id ?? top?.tagName ?? "offscreen", topOpacity: o };
+   })
+   ```
+
+   Every row reads `ok: true`; a `coveredBy` naming a screen with
+   `topOpacity: 0` is rule 1 or 2 broken. Run it on the title screen and again
+   with the pause screen up — `$genex-threejs-visual-validation` carries the
+   same check in its smoke pass.
 
 ## The states every game needs
 
@@ -279,7 +320,8 @@ black reads as a broken page. The branded version costs nothing:
 ## Motion — screens move or the game feels dead
 
 Phase changes animate. `hidden` alone hard-cuts; pair it with a class so
-opacity can transition:
+opacity can transition — the class owns opacity and `pointer-events`, `hidden`
+keeps owning `display`:
 
 ```ts
 function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
@@ -298,6 +340,8 @@ function setPhase(phase: "loading" | "playing" | "paused" | "over" | "won") {
 ```
 
 ```css
+/* Opacity only — `display` stays with `hidden` (Architecture, above). Setting
+   `display` here would lay every hidden screen out over the shown one. */
 #ui .screen { opacity: 0; transition: opacity 280ms ease; }
 #ui .screen.is-on { opacity: 1; }
 
@@ -431,6 +475,11 @@ widget gets its numbers.
   HUD — pick the 2–3 numbers that matter and style them by hierarchy.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that
   teleport.
+- An invisible screen still laid out over the one the player sees — `display`
+  set on `.screen` (defeating `hidden`), or an `opacity: 0` screen that kept
+  `pointer-events: auto` — so the title's Start button never receives its
+  click; the hit-test in "Inactive screens are gone, not see-through" catches
+  it.
 - A silent menu; a bare "Loading…" over black.
 - Generated UI art enqueued and then left on the shelf — a landed sprite sheet
   that never got extracted, masked, and wired is worse than never running the

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

@@ -1,30 +1,34 @@
 ---
 name: genex-threejs-procedural-assets
-description: Build editable, parameterized Three.js objects in code — structures, buildings, modular kits, repeated or varied props — whenever code is the more efficient engine for them, or the user asks for procedural/parametric work. A first-class lane alongside generated GLBs; mix both freely.
+description: Build editable, parameterized Three.js objects in code — modular kits, structural pieces, repeated or varied props, and any object code will honestly make read as the thing it is — or whenever the user asks for procedural/parametric work. A first-class lane alongside generated GLBs, held to the same bar; mix both freely.
 ---
 
 # Genex Three.js Procedural Assets
 
 Build a recognizable asset as local, editable Three.js code. This lane is a
-first-class engine, not a fallback: for structures, buildings, modular kits,
-and anything placed many times with variation, code is often more efficient
-than a generated GLB — and mixing procedural pieces with generated hero
-pieces in the same scene is the normal way to build a detailed, lively world.
+first-class engine, not a fallback — and it is held to the same bar as a
+generated GLB: the result must read as the thing it is when the player looks at
+it, in the game's own style. A coloured box or a flat grey block is a blockout,
+never a landed asset. Mixing procedural pieces with generated pieces in the
+same scene is the normal way to build a detailed, lively world.
 
 ## Choose the route
 
 - Start directly when the user says procedural, parametric, code-built,
   customizable, seeded, or asks for controlled variations.
-- Also start directly when code is plainly the efficient route: buildings and
-  structures, modular environment kits, fences, pipes, rails, and anything
-  placed many times with variation.
+- Also start directly for what is structural, repeated, distant, or
+  parametric: terrain, modular environment kits, fences, pipes, rails, walls,
+  paving, and anything placed many times with variation.
+- For anything the player looks at up close, walks into, or interacts with — a
+  named building, a signature prop, a vehicle — code is a choice, not a
+  default: take it only when you will honestly reach the bar above, and confirm
+  it in a capture at gameplay distance before the row reads `landed`. Otherwise
+  `$genex-ai-model` owns it.
 - An attached or available image does not activate this skill by itself.
 - If “make this image 3D” could honestly mean either route, ask exactly one
   question: **“Do you want a generated textured GLB, or editable procedural
   Three.js code?”**
 - Use `$genex-ai-model` when the user chooses a generated textured GLB.
-- Use this skill for props, hard-surface objects, modular decorations, and
-  simple structures or environment pieces.
 - Do not use it for characters, creatures, rigging, skeletal animation, or
   character likeness. Keep those in their existing specialist lanes.
 
@@ -60,6 +64,9 @@ proposed → planned → building (blockout | detail | material | runtime)
 → landed (<local TypeScript path>) → wired
 ```
 
+`landed` means a capture at gameplay distance showed it reads as the thing it
+is — not that the file exists.
+
 A Genex-generated reference keeps its separate image row and normal paid
 generation status. Note that the procedural-code row is derived from that
 image. A private user reference is not a paid generation row.

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
@@ -72,7 +73,13 @@ everything twice.
    console errors). For an unpublished draft, open the dev server in local
    test mode — `http://localhost:5173/?genex_local_test=1` (the embed-auth
    skill's "Self-testing a draft" section) — so you see the game, not the
-   sign-in gate.
+   sign-in gate. Then hit-test the screen that is up (title now, pause later):
+   for every visible button, `document.elementFromPoint(cx, cy)` at its centre
+   must return the button or one of its descendants — a top hit whose
+   effective (inherited) opacity is 0 is an invisible screen still laid out
+   over this one (a `display` rule on `.screen` defeating `hidden`, or an
+   `opacity: 0` screen keeping `pointer-events: auto`), and nobody can enter
+   the game. `$genex-threejs-game-ui` has the one-paste check and the fix.
 2. Press each documented control once (keys, pointer); assert a **visible
    response in its labeled direction** — this is the input-direction pass, and
    it is part of THIS check, not an extra testing loop. Hold `KeyD`/ArrowRight
@@ -359,6 +366,9 @@ visual-system work — the sequence above.
 - a non-cursor-core game that leaves the OS cursor visible during play;
 - a menu or settings click locks the pointer (or the cursor vanishes) while a
   menu screen is still up;
+- a title, boot, or pause button whose centre hit-test returns an element of a
+  screen that is not visibly up (effective opacity 0) — an invisible overlay is
+  swallowing the click;
 - approval relies on a single frame;
 - post-processing cannot be disabled per pass;
 - random seeds are not reproducible;

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

@@ -53,8 +53,9 @@ and let the player skip.
 
 ## Cost
 
-Typical: **5 credits** an sfx · **40** a music track · **10** a voice line.
-Live prices and your balance: `npx genex doctor`.
+From **2 credits** an sfx · **27** a 90 s music track · **2** a short voice line
+(voice bills per character, up to 12 at the 1000-character cap; 1 credit = $0.01).
+Longer `--duration`s cost more. Live prices and your balance: `npx genex doctor`.
 
 ## Waiting
 

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-image/SKILL.md

@@ -43,8 +43,10 @@ Wire the **local path**. The URL is provenance — never fetch it at runtime.
 
 ## Cost
 
-Typical: **8 credits** per image (`--candidates` bills per variant). Live prices
-and your balance: `npx genex doctor`.
+From **4 credits** per image at default quality (1 credit = $0.01);
+`--transparent`, `--quality high`, `--edit` and 4K canvases cost more, and
+`--candidates` bills per variant - the command prints the exact quote. 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.
@@ -31,29 +42,44 @@ npx genex model rig <model-id> --type quadruped
 npx genex model animate <rig-id> --preset walk,run
 ```
 
-- **`segment`** — one GLB whose parts carry NAMES, so you can address them: doors, turrets, magazines, destructibles. `--granularity simple|balanced|detailed`.
+- **`segment`** — one GLB split into addressable parts: doors, turrets, magazines, destructibles. `--granularity simple|balanced|detailed`. The parts are named by index (`tripo_part_0`, `tripo_part_1`, …), not by what they are — find the one you want by its bounds (the sails are the part with the widest extent, the door the lowest thin one), then keep that index in your manifest.
 - **`rig`** — a skeleton for any mesh, across 7 body plans: `biped`, `quadruped`, `hexapod`, `octopod`, `avian`, `serpentine`, `aquatic`. The plan is auto-detected; `--type` picks it. A mesh that cannot be rigged is refused and refunded before the paid step.
 - **`animate`** — retarget ready-made clips onto a rig, billed per clip. biped: `idle|walk|run|dive|climb|jump|slash|shoot|hurt|fall|turn`; quadruped/hexapod/octopod: `walk`; serpentine/aquatic: `march`.
 
 ## 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 — it holds `--face-limit` to 1000-20000, 500-10000 with `--quad`; omit the flag to take 20000; it runs a post-process after the mesh, so allow up to 30 minutes), `--parts` (+20, named parts at generation), `--face-limit <n>` (1000-2000000, default 150000; see `--low-poly` for its band), `--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
 
-Typical: **25 credits** a model · **30** segment · **20** rig · **8 per clip**
-for animate. 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
 
 Models take the longest of any lane. `--no-wait` is the normal way to run
 several at once: enqueue them all, keep building, then `npx genex wait --all`
-for one status line each, and `npx genex wait <id>` to pick one up.
-**Re-running the model command bills a NEW model** — never use it as a status
-check.
+for one status line each — in a tools workspace it also downloads every
+finished model that is not in `./assets` yet, so one call after a break (or a
+restarted session) delivers the whole batch. `npx genex wait <id>` picks one
+up. **Re-running the model command bills a NEW model** — never use it as a
+status check. Five or so in flight at a time is the provider's comfortable
+concurrency; a burst beyond that waits on the server side rather than failing.
+
+## Placing a model
+
+A generated GLB has no shared "front": one building's door faces −x, the next
+one's +z. Do not guess and do not spend a render per side — read the mesh once
+on load (bounding box, and where the detail is: the door, the counter, the
+opening) or check it in a viewer, then record a per-model `front` (a yaw in
+your manifest) beside its path and apply it when you place it. Ask for a facing
+in the prompt too (`"…front toward +Z"`) — it helps, it does not guarantee.
 
 ## Troubleshooting