@genex-ai/cli-demo 0.77.1-dev.199 → 0.78.1-dev.203

package/dist/index.js

@@ -3225,7 +3225,7 @@ async function deployGame(ctx, opts, log) {
     return false;
   }
   log.step(`Uploading ${files.length} files\u2026`);
-  if (!await uploadAll(grant.uploadUrl, grant.token, files, log)) {
+  if (!await uploadAll(grant, files, log)) {
     log.error("Couldn't upload your game \u2014 please try again.");
     return false;
   }
@@ -3306,21 +3306,24 @@ async function getUploadToken(ctx, commit, log) {
   }
   return await res.json();
 }
-async function uploadAll(uploadUrl, uploadToken, files, log) {
-  const base = uploadUrl.replace(/\/+$/, "");
+async function uploadAll(grant, files, log) {
+  const base = grant.uploadUrl.replace(/\/+$/, "");
+  const threshold = grant.limits.singlePutMaxBytes ?? grant.limits.maxFileBytes;
+  const small = files.filter((f) => f.bytes.length <= threshold);
+  const large = files.filter((f) => f.bytes.length > threshold);
   let failed = false;
   let next = 0;
   const worker = async () => {
     while (!failed) {
       const i = next++;
-      if (i >= files.length) return;
-      const f = files[i];
+      if (i >= small.length) return;
+      const f = small[i];
       const encoded = f.relPath.split("/").map(encodeURIComponent).join("/");
       let res = null;
       try {
         res = await fetch(`${base}/${encoded}`, {
           method: "PUT",
-          headers: { Authorization: `Bearer ${uploadToken}` },
+          headers: { Authorization: `Bearer ${grant.token}` },
           body: f.bytes
         });
       } catch {
@@ -3332,8 +3335,97 @@ async function uploadAll(uploadUrl, uploadToken, files, log) {
       }
     }
   };
-  await Promise.all(Array.from({ length: Math.min(8, files.length) }, () => worker()));
-  return !failed;
+  await Promise.all(Array.from({ length: Math.min(8, small.length) }, () => worker()));
+  if (failed) return false;
+  for (const f of large) {
+    if (!await uploadMultipart(base, grant.token, f, grant.limits.partSizeBytes, log)) return false;
+  }
+  return true;
+}
+async function uploadMultipart(base, uploadToken, f, partSize, log) {
+  const encoded = f.relPath.split("/").map(encodeURIComponent).join("/");
+  const auth = { Authorization: `Bearer ${uploadToken}` };
+  const totalParts = Math.ceil(f.bytes.length / partSize);
+  log.step(`Uploading ${f.relPath} (${(f.bytes.length / 1048576).toFixed(1)} MB in ${totalParts} parts)\u2026`);
+  let uploadId;
+  try {
+    const res = await fetch(`${base}/${encoded}?action=mpu-create`, { method: "POST", headers: auth });
+    if (!res.ok) {
+      log.warn(`Upload failed for ${f.relPath} (HTTP ${res.status} starting multipart).`);
+      return false;
+    }
+    uploadId = (await res.json()).uploadId;
+  } catch {
+    log.warn(`Upload failed for ${f.relPath} (network error starting multipart).`);
+    return false;
+  }
+  const abort = async () => {
+    try {
+      await fetch(`${base}/${encoded}?action=mpu-abort&uploadId=${encodeURIComponent(uploadId)}`, {
+        method: "DELETE",
+        headers: auth
+      });
+    } catch {
+    }
+  };
+  const parts = [];
+  let failed = false;
+  let next = 0;
+  const partWorker = async () => {
+    while (!failed) {
+      const i = next++;
+      if (i >= totalParts) return;
+      const partNumber = i + 1;
+      const bytes = f.bytes.subarray(i * partSize, Math.min((i + 1) * partSize, f.bytes.length));
+      const part = await uploadPartWithRetry(base, encoded, auth, uploadId, partNumber, bytes);
+      if (!part) {
+        failed = true;
+        log.warn(`Upload failed for ${f.relPath} (part ${partNumber}/${totalParts}).`);
+        return;
+      }
+      parts.push(part);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, totalParts) }, () => partWorker()));
+  if (failed) {
+    await abort();
+    return false;
+  }
+  parts.sort((a, b) => a.partNumber - b.partNumber);
+  try {
+    const res = await fetch(`${base}/${encoded}?action=mpu-complete&uploadId=${encodeURIComponent(uploadId)}`, {
+      method: "POST",
+      headers: { ...auth, "Content-Type": "application/json" },
+      body: JSON.stringify({ parts })
+    });
+    if (!res.ok) {
+      log.warn(`Upload failed for ${f.relPath} (HTTP ${res.status} completing multipart).`);
+      await abort();
+      return false;
+    }
+  } catch {
+    log.warn(`Upload failed for ${f.relPath} (network error completing multipart).`);
+    await abort();
+    return false;
+  }
+  return true;
+}
+async function uploadPartWithRetry(base, encoded, auth, uploadId, partNumber, bytes) {
+  for (let attempt = 0; ; attempt++) {
+    let res = null;
+    try {
+      res = await fetch(
+        `${base}/${encoded}?action=mpu-part&uploadId=${encodeURIComponent(uploadId)}&partNumber=${partNumber}`,
+        { method: "PUT", headers: auth, body: bytes }
+      );
+      if (res.ok) return await res.json();
+    } catch {
+      res = null;
+    }
+    if (res && res.status < 500) return null;
+    if (attempt >= 2) return null;
+    await new Promise((resolve) => setTimeout(resolve, attempt === 0 ? 500 : 2e3));
+  }
 }
 async function callPublish(ctx, commit, opts, log) {
   let res;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.77.1-dev.199",
+  "version": "0.78.1-dev.203",
   "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/pick-asset.ts

@@ -80,26 +80,31 @@ export async function loadTextureWithFallback<T>(
 // Generated MODELS (mesh-compression lane). GLB rungs use the same numeric
 // suffix — `model-glb@1024` = embedded textures ≤1024 + meshopt (+simplify) —
 // but unlike images there is NO edge rewrite for old games: selection happens
-// ONLY here, in games that wired the decoders (createGltfLoader). Desktop
-// always loads the original.
+// ONLY here, in games that wired the decoders (createGltfLoader). EVERY tier
+// loads a game-ready rung — provider-raw originals are archival/remix source,
+// not game assets (a Tripo prop is ~500k tris + 3x4096² textures; a scene of
+// them floored an M4 Max). Desktop gets @2048, phones @1024; the original is
+// only ever the fallback of last resort.
 
-const MODEL_TEXTURE_BUDGET = 1024;
+/** Per-tier texture budget: desktop tiers @2048, phone tiers @1024. */
+function modelBudgetFor(tier: QualityTier): number {
+  return tier.name === "phone" || tier.name === "phone-low" ? 1024 : 2048;
+}
 const MODEL_ROLE_RE = /^(model-glb|character-rigged(-a\d+)?-glb(-r\d+)?)$/;
 
 /** Resolve the model URL a THIS-tier device should load. `ktx2: true` (from
- *  createGltfLoader) upgrades phones to the GPU-compressed sibling. */
+ *  createGltfLoader) upgrades to the GPU-compressed sibling. */
 export function pickModel(url: string, tier: QualityTier, opts?: { ktx2?: boolean }): string {
   if (!GENEX_GENERATIONS_RE.test(url)) return url;
   const role = url.split("/").pop() ?? "";
   if (!MODEL_ROLE_RE.test(role)) return url;
-  if (tier.name !== "phone" && tier.name !== "phone-low") return url;
-  const rung = `${url}@${MODEL_TEXTURE_BUDGET}`;
+  const rung = `${url}@${modelBudgetFor(tier)}`;
   return opts?.ktx2 ? `${rung}.ktx2` : rung;
 }
 
 /**
  * Load a generated model through the rung ladder with the full fallback chain
- * (`.ktx2` → `@1024` → original). Use with the decoder-wired loader:
+ * (`.ktx2` → the tier's rung → original). Use with the decoder-wired loader:
  *
  *   const gltf = createGltfLoader(renderer);
  *   const model = await loadModelWithFallback(MODEL_URL, tier, (u) => gltf.loader.loadAsync(u), { ktx2: gltf.ktx2 });

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

@@ -35,6 +35,13 @@ ring) that no hand-written CSS can fake.
   (`background: rgba(<darkest hue>, 0.35–0.6)` + `backdrop-filter: blur(6–12px)`
   and its `-webkit-` twin) when the style wants translucency, a solid painted
   plate, a subtle gradient — or no plate at all for an outline-led look.
+  **A plate exists only where the widget's own art doesn't already back it.**
+  Behind an OPAQUE frame sprite there is no plate — the frame IS the backing
+  surface, and a dark div stacked behind it only protrudes as a box over the
+  scene (the recurring black-box defect). Where a plate IS needed — bare DOM
+  readouts, thin-outline widgets — it stays WITHIN the widget's silhouette:
+  inset inside the frame, or shaped to it, never a full rectangle spilling
+  past the art onto the scene.
   **Glass is a technique, not a default** — do not reach for translucency
   because this skill mentions it; reach for it when THIS game's brief does.
   What is fixed is WHERE plates are built — the DOM — because
@@ -44,7 +51,9 @@ ring) that no hand-written CSS can fake.
   corners with `border-radius` or a clean `clip-path`/`mask` shape — a CSS
   chamfer/notch is allowed, as long as the cut never clips the plate's
   content (text, padding, a glow), leaves no jagged-edge artifacts, and
-  nothing ends up crooked; a genuinely ornamented angular frame is still
+  nothing ends up crooked — and a plain `border`/`box-shadow` won't follow a
+  `clip-path` cut, so use `$genex-threejs-game-ui`'s two-layer chamfer-border
+  recipe when a chamfer needs a frame; a genuinely ornamented angular frame is still
   best as chrome, generated. The load-bearing `mask`/`clip-path` in this
   skill is the masked-fill reveal below.
 - **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
@@ -105,7 +114,10 @@ The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
   burns generations.
 - **Every widget needs internal contrast** — a panel fill, outline stroke, or
   semi-opaque backdrop — because the scene behind it might be a snowfield or a
-  torchlit dungeon. Pure-outline widgets over arbitrary scenes fail.
+  torchlit dungeon. Pure-outline widgets over arbitrary scenes fail. An opaque
+  frame sprite already IS that contrast; don't stack a plate behind it. A
+  needed backdrop lives inside the widget's silhouette, never as a rectangle
+  spilling past the art (see the plate rule under "three layers").
 - **The mockup must be flat and head-on** — a 2D screen-space overlay, never
   tilted, isometric, or in perspective. Angled panels have no clean silhouette
   and deconstruct into skewed slices. If the mockup comes back tilted,
@@ -203,13 +215,18 @@ and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
 gate — the Stage-1 mockup IS the game concept.** There is no separate
 UI-free concept image before it: this one generation carries scene + HUD,
 serves as the user's style checkpoint, and anchors all later art
-(`$genex-threejs-game-ui` owns the checkpoint choreography). The scene half
+(`$genex-threejs-game-ui` owns the checkpoint choreography). **Stage 2 onward
+is frame-anchored, so it waits for the user's keep/change YES on that
+checkpoint — kick it off the instant they approve, not before.** The scene half
 of the prompt is written in TEXT from the game plan — `[GAME_SCENE]` in the
 Stage-1 template: setting, the moment, what the player is doing, lighting —
 never `--edit`-anchored to a prior image (there is none). Then write the
 widget layout and wiring code (placement, masked-fill scaffolding,
 plain-CSS placeholder bars) while it renders — the CSS HUD keeps
-the game playable until the sprites land. The mockup is a STYLE anchor
+the game playable until the sprites land. When a sprite lands it REPLACES
+its placeholder: delete the placeholder's own background/plate as you wire
+the opaque frame in — a placeholder dark div left behind an opaque sprite
+is the black-box defect. The mockup is a STYLE anchor
 only: the widget set and
 layout come from the element inventory and the game contract — a mechanic
 the mockup invented (a lap counter, a stamina orb) does not enter the HUD,
@@ -311,11 +328,13 @@ To fix ONE sprite, don't re-run the pipeline:
   painted ON TOP. Never put the gradient on the scaling fill itself — its `%`
   stops anchor to the fill's own width and the segments visibly compress as
   the value drops.
-- **Every numeric readout gets a backing plate** — a
-  `background: rgba(10, 8, 6, 0.6)` rounded div behind the text by default, an
+- **A numeric readout sitting as bare text over the scene gets a backing
+  plate** — a `background: rgba(10, 8, 6, 0.6)` rounded div behind the text, an
   extracted plate sprite when the art has one, or a deliberate skip documented
   in a comment (`/* no plate — reads against <reason> */`). Bare digits look
-  fine over the dev background and vanish over a bright scene.
+  fine over the dev background and vanish over a bright scene. A readout
+  already sitting on an opaque frame sprite needs NO separate plate — the frame
+  backs it; a second dark div only boxes it (the no-double-backing rule above).
 
 ## Discrete vs continuous — classify every meter before Stage 2
 

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

@@ -173,8 +173,10 @@ Pause both videos when the menu phase hides (they're decode work), and
 resume the front one when it returns. Watch ONE full cycle in the browser
 before calling the menu done — that's the seam check.
 
-**Work async — the menu must never block the game.** Generate the frame right
-after the UI plan gate, enqueue the video with `--no-wait`, ship the CSS menu
+**Work async — the menu must never block the game.** The still is
+`--edit`-anchored to the concept mockup, so it's style-dependent: generate it
+the moment the user approves the concept (not before), enqueue the video with
+`--no-wait`, ship the CSS menu
 (buttons + title over the frame IMAGE as a static backdrop), and swap the
 `<video>` in when `genex wait` prints the URL. The frame image doubles as the
 **loading screen background** — it exists minutes before the video does (see

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

@@ -67,11 +67,12 @@ side — reads as broken at a glance.
 
 Load through the quality kit's decoder-wired loader and the model rung ladder
 (`$genex-threejs-adaptive-quality`; `npx genex controller quality` installs
-it). The bare URL is the provider-raw original — multiple 1–4K PBR textures +
-dense geometry; phones load the `@1024` rung instead (textures budgeted to
-1024, meshopt-compressed, simplified) and KTX2-capable games get the
-GPU-compressed sibling. Desktop always loads the original. R2 sends the right
-CORS headers, so cross-origin loading just works:
+it). The bare URL is the provider-raw original — ~500k triangles + several 4K
+PBR textures, archival/remix source, NOT a game asset (31 raw props once
+floored an M4 Max). Every model ships a game-ready ladder instead: desktop
+tiers load the `@2048` rung, phones the `@1024` rung (both meshopt-compressed
+and simplified), and KTX2-capable games get the GPU-compressed sibling. R2
+sends the right CORS headers, so cross-origin loading just works:
 
 ```ts
 import { createGltfLoader } from "./controllers/quality/gltf-loader.ts";
@@ -86,6 +87,16 @@ const gltf = await loadModelWithFallback(
   MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
 );
 const model = gltf.scene;
+// Clamp the provider's mirror-metal PBR (metalness~1 reflects the whole sky
+// env and swims with every camera move):
+model.traverse((o) => {
+  const m = (o as THREE.Mesh).material as THREE.MeshStandardMaterial;
+  if (m?.isMeshStandardMaterial) {
+    m.metalness = Math.min(m.metalness, 0.6);
+    m.roughness = Math.max(m.roughness, 0.35);
+    m.envMapIntensity = 0.6;
+  }
+});
 model.scale.setScalar(1); // tune to taste
 model.position.set(0, 0, 0);
 scene.add(model);
@@ -100,8 +111,42 @@ Never swallow a failed load silently: if you wrap a generated-asset load in a
 `catch`, `console.warn` the asset name in it — your own self-check reads the
 console, and a bare `.catch(() => null)` hides a missing model from you too.
 
-To place many copies, `model.clone()` per instance. For animated GLBs, drive
-`gltf.animations` with a `THREE.AnimationMixer`.
+**Copies**: one or two, `model.clone()` (clones share geometry/textures on the
+GPU). **Three or more of the same model → `InstancedMesh`** — clones still cost
+one draw call per mesh per copy; instancing renders all copies in one draw
+call per source mesh:
+
+```ts
+// placements: THREE.Matrix4[] — one world transform per copy
+const group = new THREE.Group();
+gltf.scene.updateMatrixWorld(true);
+const tmp = new THREE.Matrix4();
+gltf.scene.traverse((o) => {
+  const src = o as THREE.Mesh;
+  if (!src.isMesh) return;
+  const im = new THREE.InstancedMesh(src.geometry, src.material, placements.length);
+  placements.forEach((p, i) => im.setMatrixAt(i, tmp.multiplyMatrices(p, src.matrixWorld)));
+  im.instanceMatrix.needsUpdate = true;
+  im.castShadow = im.receiveShadow = true;
+  group.add(im);
+});
+scene.add(group);
+```
+
+**Distance LOD** (open worlds / long sightlines): the rung ladder already ships
+a lighter mesh — use the phone rung as the far level. One extra fetch; worth it
+past ~25 m draw ranges, skip it in small arenas:
+
+```ts
+const far = await gltfLoader.loader.loadAsync(`${MODEL_URL}@1024`);
+const lod = new THREE.LOD();
+lod.addLevel(gltf.scene, 0);   // near: the tier's rung
+lod.addLevel(far.scene, 25);   // far: phone rung — three swaps by camera distance
+scene.add(lod);
+```
+
+For animated GLBs, drive `gltf.animations` with a `THREE.AnimationMixer`
+(animated/skinned meshes can't instance — clone those).
 
 **If the game has physics, give the model a collider** — a GLB added only to the
 scene is a ghost: players and objects pass straight through it.

package/templates/skills/genex-threejs-adaptive-quality/SKILL.md

@@ -112,11 +112,13 @@ and `$genex-ai-texture` skills show the wiring in place.
 
 ## Generated models: load through the rungs
 
-Generated GLBs are provider-raw — multiple 1–4K PBR textures + dense geometry.
-Every model ships a `@1024` mobile rung (textures budgeted to 1024, meshopt-
-compressed, simplified where safe) plus a `.ktx2` sibling whose textures stay
+Provider-raw GLBs are NOT game assets: one prop is ~500k triangles + several
+4K PBR textures (a pilot scene of them submitted 66M triangles/frame and
+floored an M4 Max). Every model ships a game-ready ladder — `@2048` (the
+desktop rung) and `@1024` (the phone rung), both meshopt-compressed and
+simplified where safe, each with a `.ktx2` sibling whose textures stay
 compressed ON the GPU (~6× less texture VRAM). A plain `GLTFLoader` can decode
-neither — wire the decoders once and load through the ladder:
+none of them — wire the decoders once and load through the ladder:
 
 ```ts
 import { createGltfLoader } from "./controllers/quality/gltf-loader.ts";
@@ -126,11 +128,22 @@ const gltfLoader = createGltfLoader(renderer); // meshopt always; KTX2 when the
 const gltf = await loadModelWithFallback(
   MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
 );
+// Provider PBR ships mirror-metal (metalness~1) that reflects the sky env and
+// swims with camera motion — clamp it on every loaded model:
+gltf.scene.traverse((o) => {
+  const m = (o as THREE.Mesh).material as THREE.MeshStandardMaterial;
+  if (m?.isMeshStandardMaterial) {
+    m.metalness = Math.min(m.metalness, 0.6);
+    m.roughness = Math.max(m.roughness, 0.35);
+    m.envMapIntensity = 0.6;
+  }
+});
 ```
 
-Fallback chain: `.ktx2` rung → universal `@1024` rung → original — each step
-warns, the worst case is today's full download, never a broken boot. Desktop
-always loads the original. Meshy characters take the same ladder through
+Fallback chain: `.ktx2` rung → the tier's universal rung (`@2048` desktop,
+`@1024` phones) → original — each step warns; the original is archival/remix
+source, fetched only as the fallback of last resort. Meshy characters take
+the same ladder through
 `loadMeshyCharacter(manifestUrl, { loader: gltfLoader.loader, modelUrlCandidates: (u) => [pickModel(u, tier, { ktx2: gltfLoader.ktx2 }), pickModel(u, tier), u] })`.
 KTX2-capable games can also pass `ktx2Load` to `loadTextureWithFallback` so
 skyboxes/textures use their `.ktx2` variants.

package/templates/skills/genex-threejs-adaptive-quality/references/adaptive-quality.md

@@ -22,7 +22,7 @@ cost of guessing high is a dead page.
 | Shadow map | 512 (static-cached) | 1024 | 1024 | 2048 |
 | Post level | tone map only | + FXAA/vignette | + FXAA/vignette | full named stack |
 | Skybox rung | @2048 (~11 MB) | @4096 (~45 MB) | original | original |
-| Model rung | @1024 (+.ktx2 when wired) | @1024 (+.ktx2 when wired) | original | original |
+| Model rung | @1024 (+.ktx2 when wired) | @1024 (+.ktx2 when wired) | @2048 (+.ktx2) | @2048 (+.ktx2) |
 | Texture rung (props) | @1024 | @2048 | original | original |
 | Particles/scatter | 0.25× | 0.5× | 0.75× | 1× |
 | Draw distance | 0.5× | 0.75× | 1× | 1× |
@@ -69,6 +69,12 @@ Getting this wrong produces silent no-ops or a session stuck ugly:
   fog, LOD bias, particle counts, mixer update rates, frame cap, remote-avatar
   animation count. Light `intensity` is runtime-free; light COUNT is not (see
   above).
+- **Shadow maps of STATIC lights render once, not per frame:** shadow maps
+  default to re-rendering every frame, and a PointLight's is a 6-face cube —
+  four static shadow lanterns = 24 redundant passes/frame over the whole
+  caster set (measured 66M submitted triangles/frame in a pilot). Freeze them:
+  `light.shadow.autoUpdate = false; light.shadow.needsUpdate = true;` — only
+  the key light that shadows moving actors stays dynamic.
 
 ## Governor mechanics
 
@@ -113,9 +119,15 @@ Getting this wrong produces silent no-ops or a session stuck ugly:
 - Watch `renderer.info.memory.{textures,geometries}` across swaps in dev; a
   monotonic climb is a leak marching toward the OS kill. The governor
   publishes these counts for the platform's field telemetry.
-- Prefer meshopt/instanced geometry for repeats; `BatchedMesh` batches
-  HETEROGENEOUS static meshes into one draw where instancing (identical
-  meshes only) can't.
+- Prefer meshopt/instanced geometry for repeats: 3+ copies of the same
+  generated model → `InstancedMesh` (one draw call per source mesh instead of
+  per copy — `$genex-ai-model` has the collapse snippet); `BatchedMesh`
+  batches HETEROGENEOUS static meshes into one draw where instancing
+  (identical meshes only) can't.
+- Distance LOD comes free with the rung ladder: `THREE.LOD` with the phone
+  rung (`@1024`) as the far level — `lod.addLevel(near, 0);
+  lod.addLevel(far, 25)`. One extra fetch; worth it past ~25 m sightlines,
+  skip in small arenas.
 - Half-resolution transparency: render heavy particle/transparency passes to a
   half-size target and composite up — fill-rate is the phone bottleneck.
 

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

@@ -82,44 +82,63 @@ game doesn't have (a lap counter in a game without laps). Generate it
 `--size 2560x1440 --quality high --candidates 2 --no-wait`, enqueued FIRST
 of all art; the picked candidate's URL goes into the style-brief comment.
 
-**Share it the moment it lands — queue first, show immediately, never wait.**
-When the mockup lands, pick the stronger of the two candidates yourself,
-enqueue the downstream UI jobs and the core asset set against it in the same
-breath — the frame you just generated IS the working style until the user
-says otherwise. Then pick it up with
-`genex wait <id> --open` (or generate it with `--open`): it opens in the
-user's browser AND prints the links. Paste BOTH candidates' URLs as
-clickable links in your message and say which one you picked and why — a URL
-is invisible in a terminal, and "do you like it?" with
-no picture in front of the user is the #1 way this checkpoint fails (they end
-up digging logs for the file path). Ask ONE keep-or-change question — "this
-is roughly how the game and its HUD will look: keep it, or change
-something?" — **as
-plain chat text, never via the blocking structured-question tool: a suspended
-turn is a gate, and this question must not gate anything.** Silence is
-acceptance of YOUR pick; only explicit notes reopen the style. An unanswered style
-question that parks the art pipeline is how a finished game ships bare walls
-and a placeholder HUD — strictly worse than re-rolling a few assets later.
-**Feedback triggers a LOOP whenever it arrives:** if the user comes back
-disliking ANYTHING — immediately or an hour later — regenerate with their
-exact notes (`--candidates 2–3` gives them options to choose from), open +
-link the new frame, and ask again the same non-blocking way. Carry every note
-forward so each round compounds; if two rounds don't converge, offer 2–3
-distinct directions instead of re-rolling blind (plain chat, same rule).
-Every shown frame becomes the working style exactly like the first did:
-silence after a shown regeneration accepts THAT frame, and when
-`--candidates` goes unanswered, pick the strongest yourself and say so. When
-the style actually changes, re-run Stage 1 — the concept mockup itself —
-with the user's exact notes (strictly CHEAPER than it used to be: one image
-carries scene + HUD, there is no separate concept to redo), then re-anchor
-the style-carrying art made against the old mockup: the menu still is
-re-edited (`--edit`) against the new mockup and its video re-run once from
-the new still (`$genex-ai-menu` — a user-driven style change re-opens its
-one-video rule), and the HUD deconstruct (Stage 2 onward, `$genex-ai-hud`)
-restarts from the new mockup. Style-neutral assets (most textures, sfx,
-models) usually survive — judge each in one line. The same "open it + paste the
-link" rule covers every image the user weighs in on — the menu still, the
-HUD mockup candidates.
+**Describe the concept, show it, then get a YES before the style-dependent
+work fans out.** First lay the concept out in WORDS — the playable moment
+(the verb), what threatens the player, what they chase, how the space reads,
+and the brief's palette / materials / light / references — so the user is
+weighing a stated direction, not guessing at a picture. Generate the mockup
+FIRST of all art (`--candidates 2`) and get it in front of the user AS FAST
+AS POSSIBLE: pick the stronger candidate yourself, pick it up with
+`genex wait <id> --open` (or generate it with `--open`) so it opens in the
+user's browser AND prints the links, and paste BOTH candidates' URLs as
+clickable links saying which one you picked and why — a URL is invisible in a
+terminal, and "do you like it?" with no picture in front of the user is the
+#1 way this checkpoint fails (they end up digging logs for the file path).
+
+**Then ask for the yes with your environment's structured question tool** —
+Claude Code: `AskUserQuestion`; Codex: `request_user_input`; a short numbered
+list only where there is none (e.g. Cursor). ONE question — "this is roughly
+how the game and its HUD will look — keep this direction, or change
+something?" — with concrete keep / change options. This confirmation is
+REQUIRED for every game: the concept sets the STYLE every later asset
+inherits, so the user gets a real say before that style is committed. This
+reverses the old "advisory, never gate" rule — the concept now gates, but
+ONLY the style-dependent work (below), never the whole build.
+
+**The yes gates the STYLE-DEPENDENT work — nothing else.** Until the user
+approves a frame, do NOT fan out the art or subagents that build ON the
+chosen look: the HUD Stage-2 deconstruct (from the picked candidate), the
+menu still + video (`--edit`-anchored to the mockup), and the logotype. (The core asset set — hero model, ground texture, skybox,
+sfx — is prompted from the game IDEA, not the picked image, and mostly
+survives a style change, so it does NOT wait: launch it up front with
+placeholders, re-rolling only the few that don't survive if the look shifts.)
+Everything else that does NOT depend on the look
+keeps moving at full speed IN PARALLEL — the scaffold and boot wiring, the
+core gameplay / network loop, the controller, and the gameplay-LOGIC subagent
+modules (world, quests, enemies, items — their structure comes from the
+contract, not the picture). The wait is therefore never idle: a slow-to-answer
+user still gets a walkable first version, and the instant they say yes the
+style pipeline launches against the frame they approved. (A user who vanishes
+entirely leaves the LOOK pending, not the game — the deliberate trade for
+never committing a style behind their back.)
+
+**Change reopens the loop, same shape.** If the user picks "change" — or
+comes back with notes immediately or an hour later — re-run Stage 1 (the
+concept mockup itself) with their exact notes (`--candidates 2–3` gives them
+options to choose from), open + link the new frame, and ask again the same
+structured way. Carry every note forward so each round compounds; if two
+rounds don't converge, offer 2–3 distinct directions instead of re-rolling
+blind. Each frame the user approves becomes the working style, and the
+style-dependent pipeline stays gated on the latest yes (strictly CHEAPER than
+it used to be: one image carries scene + HUD, there is no separate concept to
+redo). When the style actually changes after downstream art already ran,
+re-anchor it: the menu still is re-edited (`--edit`) against the new mockup
+and its video re-run once from the new still (`$genex-ai-menu` — a
+user-driven style change re-opens its one-video rule), and the HUD deconstruct
+(Stage 2 onward, `$genex-ai-hud`) restarts from the new mockup. Style-neutral
+assets (most textures, sfx, models) usually survive — judge each in one line.
+The same "open it + paste the link" rule covers every image the user weighs
+in on — the menu still, the HUD mockup candidates.
 
 **The concept anchors STYLE, not truth.** Palette, materials, light, and
 register come from the frame; CONTENT comes from the game contract. This
@@ -158,9 +177,11 @@ UI plan
 • Style: <4–5 named hues> · fonts <display> / <body>
 • References: <2–3 AAA games — one line on what's borrowed>
 • Menu: <archetype + button treatment, one-line reason from the brief>
-• Concept (HUD mockup): <generation id — 2 candidates>
-• Queued next: HUD sheet (Stage 2, from the picked mockup) · menu still →
-  video <or "no menu: reason"> · logotype <or "skipped: reason">
+• Concept (HUD mockup): <generation id — 2 candidates> — awaiting your keep / change
+• Queued ON YOUR YES (style-dependent): HUD sheet (Stage 2, from the picked
+  mockup) · menu still → video <or "no menu: reason"> · logotype <or
+  "skipped: reason">
+• Building now (style-independent): <core loop · logic modules already moving>
 • Deferred from mockup: <widgets the image invented but the game lacks — or "none">
 ```
 
@@ -178,7 +199,8 @@ A message missing any line means the gate did not run — go back and run it.
   every game), and the generated **logotype** — one `--transparent` wordmark
   in the brief's display register (`$genex-ai-menu`'s logotype step), default
   YES for every game with a menu; skipping it needs a one-line stated reason.
-  Enqueue the chain at the plan gate with `--no-wait`,
+  Enqueue this chain the instant the user approves the concept
+  (`--no-wait`) — it is style-dependent, so it waits on the yes — then
   keep building, pick results up with `npx genex wait <id>`, swap them in as
   they land. **Tier 2 must never block a playable v0 — but the game is NOT
   DONE until its Tier-2 assets have landed and been wired in** (the only
@@ -454,6 +476,30 @@ Order the HUD by what the player loses the game for ignoring:
   frame, a generated frame sprite (`$genex-ai-hud` chrome, or a Tier-3
   9-slice panel) is still the richer tool. The masked-fill HUD reveal and
   `genex ui` masks remain the other established uses of `mask`/`clip-path`.
+  - **The #1 chamfer defect: a frame that STOPS at the cut.** A plain
+    `border` or `box-shadow` does NOT follow a `clip-path` chamfer — the clip
+    shears it off along the diagonal, so the straight sides keep their frame
+    while the cut edge goes bare and the panel reads as broken. Two clean
+    fixes: prefer **`border-radius`** when a soft corner reads fine (it keeps
+    its `border` natively — no clip needed); for a HARD angular cut, draw the
+    frame by clipping TWO stacked layers to the SAME polygon — outer = the
+    frame, inner (inset by the frame width) = the fill — so the outer shows
+    through as a uniform edge on the diagonal too:
+
+    ```css
+    /* Chamfered panel whose frame follows the cut. Never `border` + clip-path. */
+    .panel {
+      --chamfer: 16px; --edge: 2px;                  /* --edge = frame width */
+      --cut: polygon(var(--chamfer) 0, 100% 0, 100% calc(100% - var(--chamfer)),
+        calc(100% - var(--chamfer)) 100%, 0 100%, 0 var(--chamfer));
+      clip-path: var(--cut); background: var(--frame-hue);  /* this IS the frame */
+      padding: var(--edge);                          /* revealed all around, incl. the diagonal */
+    }
+    .panel > .panel__fill { clip-path: var(--cut); background: var(--plate-hue); }
+    ```
+
+    Same rule for chamfered buttons and any notched plate; verify the frame
+    is unbroken at every corner over real gameplay.
 - **One cohesion layer.** A single full-screen vignette div (a subtle radial
   gradient darkening the corners, optionally faint grain) over canvas + UI is
   the cheapest way to make DOM-over-WebGL read as one composed image instead
@@ -510,12 +556,19 @@ architecture and consume the shared style brief.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that
   teleport.
 - A silent menu; a bare "Loading…" over black.
-- The art pipeline parked on an unanswered look question — the question is
-  advisory: queue Tier-2 + the asset set against the shown frame and keep
-  moving; silence is acceptance.
+- Style-dependent art fanned out before the user approved the concept — the
+  concept confirmation is REQUIRED and gates the look-dependent work (HUD
+  Stage 2, menu still/video, logotype, style-matched assets); OR the whole
+  build stalled waiting on that yes, when concept-INDEPENDENT work (scaffold,
+  core loop, logic subagents) must keep moving in parallel while it is pending.
 - A CSS-cut corner (`clip-path`/`mask`) that shears its own content — clipped
-  text or padding, a lost focus ring or glow, a jagged aliased edge — the
+  text or padding, a lost focus ring or glow, a jagged aliased edge, or a
+  border/frame that stops at the cut instead of following it — the
   technique is fine; the sloppy cut is the defect.
+- A rectangular semi-transparent plate protruding past an opaque/angular
+  widget frame — a dark box floating over the scene. The frame's own art is
+  the backing; a plate is only for bare-text/outline widgets and stays inside
+  the widget silhouette (`$genex-ai-hud`'s plate rule).
 - UI panels covering the player or the thing about to kill them.
 - Layout shifting as numbers grow.
 - A fail state with no visible restart key, or a restart that reloads the page.

package/templates/skills/genex-threejs-game-ui/references/style-capsules.md

@@ -9,8 +9,9 @@ the capsule says a racing HUD leans oblique and bottom-right-heavy; your brief
 says what it's made of in THIS game.
 
 Every capsule below assumes the base rules from the skill: corners/edges for
-UI, one display + one body font, tabular numerals, contrast plates over
-arbitrary scenes, and panel/button corners executed cleanly — `border-radius`,
+UI, one display + one body font, tabular numerals, contrast plates for bare
+text over arbitrary scenes (never a second plate stacked behind an opaque
+frame sprite), and panel/button corners executed cleanly — `border-radius`,
 a CSS `clip-path`/`mask` shape, or a generated frame all work, as long as the
 cut never clips content (text, padding, glow), stays free of jagged-edge
 artifacts, and text never collides or truncates.

package/templates/skills/genex-threejs-lighting-design/SKILL.md

@@ -111,6 +111,13 @@ kill-switch diagnostic.
   legitimate time the population changes.
 - Couple a practical to its emitter: one color, one envelope, one on/off state.
 - The key owns shadows; practicals cast none until a shot proves they must.
+- **A shadow-casting practical that never moves gets a FROZEN map**: a
+  PointLight shadow is a 6-face cube render, re-drawn every frame by default —
+  four static lanterns cost 24 shadow passes/frame over your densest props for
+  zero visual change (a pilot game submitted 66M triangles/frame this way).
+  Set `light.shadow.autoUpdate = false; light.shadow.needsUpdate = true;` so
+  the cube renders once; keep only the key (which shadows the movers) dynamic,
+  and budget frozen practicals at ≤1024 map size.
 - Tune intensities only after the renderer baseline is locked — retuning the
   whole rig after a tone-mapping change is self-inflicted.
 - Never repair unbalanced light ratios with exposure — fix the lights.

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -98,9 +98,10 @@ ECCTRL-derived character controller owns collision and world translation.
 **UI is mandatory routing:** every game has an interface — load
 `$genex-threejs-game-ui` for every NEW game and run its "Plan the UI first" gate
 (screen inventory, one shared style brief, tier decisions) right after the game
-concept is locked, before any UI code. Its Tier-2 generations (cinematic menu,
-sprite HUD) are enqueued async (`--no-wait` + `npx genex wait <id>`) so they land
-while the game is being built — they never block a playable v0, and the game is
+concept is locked, before any UI code. Its frame-anchored Tier-2 generations
+(cinematic menu, sprite HUD) are enqueued async (`--no-wait` + `npx genex wait
+<id>`) the moment the user approves the concept, so they land while the game is
+being built — they never block a playable v0, and the game is
 not done, published, or handed off until they've been picked up (`npx genex wait`)
 and wired in.
 
@@ -195,8 +196,10 @@ Prefer the **procedural** skills above for abstract/parametric/animated systems
 each other.
 
 **Generate a core asset set by default — don't wait to be asked.** For any game that
-needs concrete objects or surfaces, decide a small core set from the concept and start
-generating it **up front, in parallel** (each `npx genex` is an independent ~1-minute
+needs concrete objects or surfaces, decide a small core set from the game IDEA and start
+generating it **up front, in parallel** — this set is concept-INDEPENDENT (prompted from
+the idea, not the concept image, and it mostly survives a style change), so it does NOT
+wait on the concept yes (each `npx genex` is an independent ~1-minute
 job — launch them concurrently in the background, then scaffold the scene while they run
 and wire each asset in as it lands, with a procedural placeholder as fallback until then):
 

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -40,21 +40,26 @@ Three.js release or branch, and do not blindly copy demo architecture.
    saves, leaderboards, and multiplayer auth all come from it.
 3. Run `$genex-threejs-game-ui`'s "Plan the UI first" gate: screen inventory,
    one shared style brief, a tier per screen — stated visibly in chat, never
-   decided silently. Enqueue the Tier-2 UI generations now with `--no-wait`
-   (pick them up later with `npx genex wait <id>`) — they render server-side
-   while you build the game. FIRST of all art: the gate's **concept mockup** —
+   decided silently. FIRST of all art, generate the gate's **concept mockup** —
    a playable-moment shot (verb + threat + objective in frame, per the
    game-ui gate) WITH the full HUD composited over it: the `$genex-ai-hud`
    Stage-1 image, one generation serving as concept, style checkpoint, and
-   HUD blueprint (never a separate UI-free concept first). Shown to the user
-   for a keep-or-change answer the moment
-   it lands — the answer is advisory, never a gate: the art pipeline starts
-   against the frame as-is, and the game-ui skill owns the re-anchor loop
-   when notes arrive; later `--edit`-able generations anchor to it for STYLE
-   while the game contract owns content. Then the `$genex-ai-hud` Stage-1 mockup, enqueued
-   here for EVERY game; and the `$genex-ai-menu` video whenever the menu
-   decision is yes (the default for every game — "it's only a draft" is not a
-   reason to decide no). Skipping this enqueue is
+   HUD blueprint (never a separate UI-free concept first). Show it to the user
+   the moment it lands and get a keep-or-change answer through the
+   environment's structured question tool (Claude Code: `AskUserQuestion`;
+   Codex: `request_user_input`; numbered-list fallback otherwise). This answer
+   GATES — but only the style-dependent pipeline: until the user approves a
+   frame, do NOT enqueue the Tier-2 art that builds on the look (the
+   `$genex-ai-hud` Stage-2 chain, and the `$genex-ai-menu` still + video
+   whenever the menu decision is yes — the default for every game, "it's only
+   a draft" is not a reason to decide no — plus the logotype). The instant
+   they say yes, fire those with `--no-wait` (pick them up with
+   `npx genex wait <id>`); the game-ui skill owns the re-anchor loop when notes
+   arrive, and later `--edit`-able generations anchor to the approved frame for
+   STYLE while the game contract owns content. Everything that does NOT depend
+   on the look — scaffold, boot wiring, the core loop, and the
+   concept-independent content subagents below — keeps building in parallel
+   while the answer is pending, so the wait is never idle. Skipping this enqueue is
    the #1 way a finished game ships an ugly HUD — by step 12 there is nothing
    to swap in.
 4. Lock the visual direction — the same plan-first logic as the UI gate, in
@@ -212,19 +217,29 @@ Three.js release or branch, and do not blindly copy demo architecture.
 13. Validate in a real browser with fixed seeds, captures, interaction checks,
     and performance evidence.
 
-## Parallelize with subagents (when the environment has them)
+## Parallelize with subagents — the default whenever the environment has them
 
 Generations already render server-side in parallel — the wall-clock savings
-live in the ATTENDED chains. When the coding agent supports background
-subagents (e.g. Claude Code's Agent tool), split these off; in environments
-without them (Cursor), the same order simply runs sequentially and the
-`--no-wait` pattern still hides most generation latency.
+live in the ATTENDED chains. Whenever the coding agent supports background
+subagents (e.g. Claude Code's Agent tool), fanning the independent work out is
+the DEFAULT, not a big-scope special case: split every disjoint chain below off
+by default and keep the main thread building. In environments without them
+(Cursor), the same order simply runs sequentially and the `--no-wait` pattern
+still hides most generation latency.
 
-- **HUD chain worker.** The moment the Stage-1 mockup (the game concept)
-  lands, hand the whole
+**One ordering rule from the concept gate (step 3):** subagents that build ON
+the look are CONCEPT-DEPENDENT and wait for the user's keep/change yes — the
+HUD chain worker and any style-matched art. Subagents that do NOT depend on the
+look — the content-module fan-out, verification of concept-independent parts —
+launch immediately and run while the concept answer is still pending. Never let
+the pending yes stall concept-independent work, and never fan out
+concept-dependent work before it.
+
+- **HUD chain worker (concept-dependent — starts on the yes).** The moment the
+  user APPROVES the concept, hand the whole
   `$genex-ai-hud` chain to one subagent: pick the better candidate → Stage-2
   sheet → clean → extract → masks → write the sprite wiring. Its prompt must
-  be self-contained — the style brief, the mockup URL, the
+  be self-contained — the style brief, the approved mockup URL, the
   output dir, and exactly which files it owns. **Handoff rule:** whoever
   wires the HUD after the subagent finishes MUST read the produced
   `*.annotated-progress.json` and `.bbox.json` files from disk — fillBox
@@ -237,7 +252,8 @@ without them (Cursor), the same order simply runs sequentially and the
 - **Verification runner.** Browser evidence — screenshots, control presses,
   the menu loop-seam watch, in-situ checks of placed art — can run in a
   subagent while the main agent keeps building.
-- **Content module fan-out (big scopes).** When the content contract names a
+- **Content module fan-out (big scopes — concept-independent, launch immediately).**
+  When the content contract names a
   big world or several content systems, serial hand-typing is what runs out
   of session: split the gameplay modules across parallel subagents instead —
   one each for world/terrain, quest + dialogue DATA, enemies/AI, items/