@genex-ai/cli-demo 1.20.0-dev.602 → 1.21.0-dev.604

package/dist/{blender-mcp-FQJFZETR.js → blender-mcp-PWOUSXK4.js}

@@ -7,7 +7,7 @@ import {
   isRenderMode,
   sceneSummary,
   sheetOf
-} from "./chunk-YSMZVFJM.js";
+} from "./chunk-HEDRWUVP.js";
 import {
   getCliVersion
 } from "./chunk-HYCSNWYX.js";

package/dist/{chunk-YSMZVFJM.js → chunk-HEDRWUVP.js}

@@ -447,6 +447,13 @@ async function apiFetch(url, init = {}, opts = {}) {
       if (body?.error === "generation_paused") {
         process.stderr.write(
           `${c.red("\u2717")} ${body.message ?? "Generation is temporarily paused platform-wide. Try again later."}
+`
+        );
+        structuredPrinted.add(res);
+      }
+      if (body?.error === "provider_unavailable") {
+        process.stderr.write(
+          `${c.red("\u2717")} ${body.message ?? "This generation lane is unavailable \u2014 our provider account is out of credit. Build it in code and move on."}
 `
         );
         structuredPrinted.add(res);

package/dist/index.js

@@ -42,7 +42,7 @@ import {
   writeProject,
   writeUserToken,
   writeWorkspace
-} from "./chunk-YSMZVFJM.js";
+} from "./chunk-HEDRWUVP.js";
 import {
   CLI_CHANNEL,
   DEFAULT_API_URL,
@@ -2397,6 +2397,16 @@ async function recordTerminal(id, status, urls, cwd = process.cwd()) {
 async function countFailed(kind, cwd = process.cwd()) {
   return (await readLedger(cwd)).filter((e) => e.kind === kind && e.status === "failed").length;
 }
+async function trailingFailures(kind, cwd = process.cwd()) {
+  const rows = (await readLedger(cwd)).filter((e) => e.kind === kind);
+  let run2 = 0;
+  for (let i = rows.length - 1; i >= 0; i -= 1) {
+    const status = rows[i].status;
+    if (status === "completed") break;
+    if (status === "failed") run2 += 1;
+  }
+  return run2;
+}
 async function countOutcomes(kind, cwd = process.cwd()) {
   const rows = (await readLedger(cwd)).filter((e) => e.kind === kind);
   return {
@@ -2516,26 +2526,32 @@ function auditGenerationPlan(input) {
     const lane = m[1] ? LANE_OF_SKILL[m[1]] : void 0;
     if (lane) declaredLanes.add(lane);
   }
-  const lanesRun = new Set(ledger.map((e) => LANE_OF_KIND[e.kind] ?? e.kind));
+  const lanesRun = new Set(
+    ledger.filter((e) => e.status === "completed").map((e) => LANE_OF_KIND[e.kind] ?? e.kind)
+  );
+  const lanesPending = new Set(
+    ledger.filter((e) => e.status === "queued").map((e) => LANE_OF_KIND[e.kind] ?? e.kind).filter((lane) => !lanesRun.has(lane))
+  );
   const warnings = [];
   const owed = /* @__PURE__ */ new Map();
   for (const row of rows) {
     if (row.procedural || row.lane === null) continue;
     if (row.status !== "planned" && row.status !== "generating") continue;
     if (lanesRun.has(row.lane)) continue;
+    if (lanesPending.has(row.lane)) continue;
     if (row.lane === "skybox") continue;
     const held = owed.get(row.lane) ?? [];
     held.push(row.status === "generating" ? `${row.name} (says generating, not in this project's ledger)` : row.name);
     owed.set(row.lane, held);
   }
   for (const lane of declaredLanes) {
-    if (lanesRun.has(lane) || owed.has(lane) || lane === "skybox") continue;
+    if (lanesRun.has(lane) || lanesPending.has(lane) || owed.has(lane) || lane === "skybox") continue;
     if (!rows.some((r) => r.lane === lane)) owed.set(lane, ["declared as this subsystem's lane"]);
   }
   for (const [lane, names] of owed) {
     const shown = names.slice(0, 3).join(", ") + (names.length > 3 ? `, +${names.length - 3} more` : "");
     warnings.push(
-      `DESIGN.md plans generated ${lane} work (${shown}) and this project has never run a ${lane} generation \u2014 the plan says so and the generation ledger has nothing. Generate it (${LANE_COMMAND[lane] ?? `npx genex ${lane}`} "<prompt>" --no-wait), or change the row to say what happens instead and why.`
+      `DESIGN.md plans generated ${lane} work (${shown}) and this project has no ${lane} generation that landed \u2014 the plan says so and the generation ledger has nothing completed. Generate it (${LANE_COMMAND[lane] ?? `npx genex ${lane}`} "<prompt>" --no-wait), or change the row to say what happens instead and why.`
     );
   }
   const paidRows = rows.filter((r) => !r.procedural);
@@ -6056,7 +6072,18 @@ async function detectSurfaceScan(cwd = process.cwd()) {
   }
   return found;
 }
-var WIRED_BY_URL = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "music", "texture", "video"]);
+var WIRED_BY_URL = /* @__PURE__ */ new Set([
+  "model",
+  "model_segment",
+  "model_rig",
+  "model_animation",
+  "skybox",
+  "sfx",
+  "music",
+  "voice",
+  "texture",
+  "video"
+]);
 var UNPICKED_AFTER_MS = 15 * 60 * 1e3;
 async function detectGenerationAudit(cwd = process.cwd()) {
   const ledger = await readLedger(cwd);
@@ -6067,7 +6094,10 @@ async function detectGenerationAudit(cwd = process.cwd()) {
   let haystack = "";
   const read = async (file) => {
     try {
-      haystack += await fs15.readFile(file, "utf8");
+      const raw = await fs15.readFile(file, "utf8");
+      const ext = path14.extname(file).toLowerCase();
+      if (ext === ".txt") return;
+      haystack += ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".jsx" || ext === ".css" ? blankComments(raw) : ext === ".html" ? raw.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " ")) : raw;
     } catch {
     }
   };
@@ -7566,7 +7596,10 @@ async function reportTerminal(kind, view, log, open = false, json = false, local
         const failures = await countFailed("video");
         (failures >= 2 ? log.plain : log.dim)(videoFailureAdvice(failures));
       } else if (!failure?.billing) {
-        const advice = laneFailureAdvice(kind, await countOutcomes(kind));
+        const advice = laneFailureAdvice(kind, {
+          ...await countOutcomes(kind),
+          trailingFailed: await trailingFailures(kind)
+        });
         if (advice) log.plain(advice);
       }
     }
@@ -7660,8 +7693,11 @@ function reportLocalFiles(result, log, json) {
   }
 }
 function laneFailureAdvice(kind, outcomes) {
-  if (outcomes.failed < 2 || outcomes.completed > 0) return null;
-  return `  ${c.bold(`\u270B ${outcomes.failed} ${kind} generations attempted in this project, ${outcomes.failed} failed, none succeeded.`)} That pattern is the LANE, not your prompt \u2014 a fourth attempt bills the same and returns the same. Build this one in code, use a different lane, or tell the user in one plain line what is unavailable and carry on with the rest of the game.`;
+  const run2 = outcomes.trailingFailed ?? (outcomes.completed > 0 ? 0 : outcomes.failed);
+  if (run2 < 2) return null;
+  const everSucceeded = outcomes.completed > 0;
+  const opening = everSucceeded ? `\u270B the last ${run2} ${kind} generations in this project all failed.` : `\u270B ${run2} ${kind} generations attempted in this project, ${run2} failed, none succeeded.`;
+  return `  ${c.bold(opening)} That pattern is the LANE, not your prompt \u2014 a fourth attempt bills the same and returns the same. Build this one in code, use a different lane, or tell the user in one plain line what is unavailable and carry on with the rest of the game.`;
 }
 function videoFailureAdvice(failures) {
   if (failures >= 2) {
@@ -7796,7 +7832,14 @@ var HINT_URL_KINDS = /* @__PURE__ */ new Set([
 ]);
 function assetHint(kind, view, url) {
   const hint = {
-    model: `Standard GLB \u2014 load with GLTFLoader straight from the URL \u2014 see the genex-ai-model skill.`,
+    // "straight from the URL" was the OPPOSITE of the kit's own rule, which
+    // reads: "EVERY tier loads a game-ready rung — provider-raw originals are
+    // archival/remix source, not game assets" (controllers/quality/pick-asset.ts).
+    // A bare GLTFLoader on this URL fetches the original — a Tripo prop is
+    // ~500k tris and 3x4096 textures, and a scene of them floored an M4 Max.
+    // The url clause stays: the BARE url is the right thing to store, because
+    // `pickModel` resolves the tier's rung at load time.
+    model: `Standard GLB. Load it through the quality kit \u2014 createGltfLoader(renderer) then loadModelWithFallback(url, tier, (u) => gltf.loader.loadAsync(u), { ktx2: gltf.ktx2 }) \u2014 so the tier gets a game-ready rung; a bare GLTFLoader on this URL fetches the provider-raw original (~500k tris, 3x4096 textures). Install it with npx genex controller quality. See genex-ai-model.`,
     // Unreachable while the lane is paused (see src/index.ts) — kept so a
     // restore is one deletion. Games that already ship a panorama still load
     // it this way.
@@ -7817,9 +7860,9 @@ function assetHint(kind, view, url) {
     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.`,
-    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.`,
-    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.`,
-    model_animation: `Animated GLB \u2014 load with GLTFLoader and play its clips via THREE.AnimationMixer (gltf.animations).`
+    model_segment: `One GLB with NAMED parts \u2014 load it through the quality kit (loadModelWithFallback, as for a plain model), then getObjectByName / traverse scene.children to move, detach, or swap a part. Part names print above when the provider reports them.`,
+    model_rig: `Rigged GLB (Tripo skeleton) \u2014 load it through the quality kit (loadModelWithFallback); give it motion with genex model animate ${view.id} --preset walk, or drive the bones in code.`,
+    model_animation: `Animated GLB \u2014 load it through the quality kit (loadModelWithFallback) and play its clips via THREE.AnimationMixer (gltf.animations).`
   };
   const base = hint[kind];
   return url && HINT_URL_KINDS.has(kind) ? `${base} url = "${url}"` : base;
@@ -17939,6 +17982,7 @@ var CONTROLLER_FILE_SETS = {
     code: [
       "quality/tier.ts",
       "quality/governor.ts",
+      "quality/deadline.ts",
       "quality/pick-asset.ts",
       "quality/gltf-loader.ts",
       "quality/depth.ts",
@@ -20898,7 +20942,7 @@ async function runBlender(opts) {
     return serveLocalBlender({ port, log });
   }
   if (sub === "mcp") {
-    const { runBlenderMcp } = await import("./blender-mcp-FQJFZETR.js");
+    const { runBlenderMcp } = await import("./blender-mcp-PWOUSXK4.js");
     return runBlenderMcp();
   }
   if (sub === "seat") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.20.0-dev.602",
+  "version": "1.21.0-dev.604",
   "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/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-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` |
@@ -140,7 +141,7 @@ vendored code from memory of another engine.
 | 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` |
+| 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` |
@@ -196,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
 

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.