@genex-ai/cli-demo 0.78.0-dev.200 → 0.80.0-dev.211

package/dist/index.js

@@ -287,7 +287,7 @@ async function hasGenexSkills(skillsDir) {
     return false;
   }
 }
-var REMOVED_SKILLS = ["genex-explore"];
+var REMOVED_SKILLS = ["genex-explore", "genex-threejs-skill-router"];
 async function pruneRemovedSkills(skillsDir, log) {
   const removed = [];
   for (const name of REMOVED_SKILLS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.78.0-dev.200",
+  "version": "0.80.0-dev.211",
   "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/README.md

@@ -17,5 +17,5 @@ command keeps them in sync with the installed CLI version automatically
 - `agents/` - example subagent definitions.
 - `commands/` - example slash commands.
 
-Start with `skills/genex-threejs-skill-router/SKILL.md` when asking your agent
+Start with `skills/genex-game-director/SKILL.md` when asking your agent
 to build or improve a 3D browser game.

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

@@ -43,10 +43,8 @@ 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. Before rigging, ask the user to approve a separate
 10,000-face triangle remesh. The 10k remesh—not the high-detail source—is
-rigged and animated. (For these approvals, use your environment's structured
-question tool when it has one — Claude Code: `AskUserQuestion`; Codex:
-`request_user_input`; if it has none, e.g. Cursor, a short numbered list in
-chat.)
+rigged and animated. (For these approvals, use your question tool when you
+have one; if you have none, a short numbered list in chat.)
 
 The high-detail pre-rig generation stays in the selected neutral A-pose. There
 is no dynamic-pose concept and no silent T-pose fallback. After the user has

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

@@ -35,18 +35,25 @@ 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
   semi-transparency physically cannot survive sprite extraction: a composited
   panel's pixels are a blend of panel and background, and no cutout can
   un-blend them. Plates are NEVER baked into sprites. Give the plate its
-  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
-  best as chrome, generated. The load-bearing `mask`/`clip-path` in this
-  skill is the masked-fill reveal below.
+  corners with `border-radius` — **never a raw `clip-path`/`mask` chamfer**
+  (it shears off borders, shadows, and content near the cut and re-breaks on
+  every padding/value change: the recurring "cut corners" defect). A genuinely
+  ornamented or angular frame belongs in chrome, generated. The one
+  load-bearing `mask`/`clip-path` in this skill is the masked-fill reveal
+  below — never corner shaping.
 - **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
   brackets, ornaments, emblems, icons, medallions — hard-alpha art laid over
   the glass. The Stage-2 sheet contains ONLY chrome; never a panel with its
@@ -73,7 +80,7 @@ ring) that no hand-written CSS can fake.
   the container is the sprite and the content is DOM — the default split.
 - **Rule B — image vs code (the 5-minute test).** If CSS can build the
   element in under ~5 minutes without losing fidelity — flat plates, simple
-  dots/pips, plain strokes, a chamfered corner — it is CSS. If it needs
+  dots/pips, plain strokes, a rounded corner — it is CSS. If it needs
   craft (material, ornament, painterly texture), it is a sprite. One
   exception cuts the other way: a static label engraved/embossed into a
   frame's craft stays BAKED in the sprite (`baked_static` below) even
@@ -81,9 +88,10 @@ ring) that no hand-written CSS can fake.
 - **CSS-chrome recipes — the middle ground.** Between bare CSS and the full
   sprite pipeline sits brief-styled CSS chrome, right for utilitarian panels
   and secondary screens: a two-hue gradient frame (border + inset
-  box-shadow in brief hues), a clip-path chamfer (execution bar per
-  `$genex-threejs-game-ui`'s corner rules), a 9-slice-ish panel from nested
-  divs (outer div = border hue, inset div = plate hue, 2–3px reveal). What
+  box-shadow in brief hues), rounded with `border-radius` (never a raw
+  `clip-path` chamfer — see `$genex-threejs-game-ui`'s corner rules), a
+  9-slice-ish panel from nested divs (outer div = border hue, inset div =
+  plate hue, 2–3px reveal). What
   makes these legitimate: **CSS elements are styled FROM THE BRIEF — hue,
   weight, texture. Default-gray CSS anywhere on screen is a defect** (the
   classic failure: score pips shipped as unstyled "○ ●" system glyphs).
@@ -105,7 +113,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 +214,26 @@ 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
+Stage-1 template: setting, the moment, what the player is doing, lighting.
+**If a concept/reference image already exists — the user's own concept art, or
+a look frame you generated and they approved — anchor Stage 1 to it with
+`--edit <that-url>` so the HUD inherits its exact palette, materials, and
+lighting; that anchoring is what makes the final HUD actually match the
+concept, and skipping it is why a text-only mockup drifts.** A text-only
+Stage 1 is the fallback for when no reference exists. (To `--edit` a
+user-supplied image it must be reachable as an R2 URL — a bare chat attachment
+is not; reproduce it as a generation first, or say plainly you can't anchor to
+it rather than silently guessing.) 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,
@@ -221,8 +245,9 @@ re-run from Stage 1 with their notes — cheaper than it sounds (one image
 is the whole concept now), so say so in one line and do it.
 
 ```bash
-# Stage 1 — the game CONCEPT: full HUD composited over the game's own scene,
-# described in TEXT (one generation covers concept + layout reference).
+# Stage 1 — the game CONCEPT: full HUD composited over the game's own scene.
+# TEXT-described; add `--edit <concept-url>` to anchor it to an existing
+# concept/reference image so the HUD inherits its exact style.
 # Two candidates in one call; pick the better, save its URL:
 npx genex image "<filled stage-1 prompt>" --size 2560x1440 --quality high --candidates 2
 
@@ -311,11 +336,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
 
@@ -473,6 +500,13 @@ Two hard rules:
 
 ## Verify before calling it done
 
+**This is a gate, not a suggestion — the HUD is not "done", does not ship, and
+is not called a milestone until you have looked at it running.** The field
+failure is an agent that wires the sprites, takes one glance, notices a possible
+clip or cutoff, and ships anyway with "I'll refine if the user reports issues."
+That punt IS the defect. You are the one who verifies, not the user. If you are
+out of budget to check, say the HUD is unverified — never call it done.
+
 - **Open every extracted PNG and eyeball it** — right subject, right name.
   The reading-order sort can mismap when rows are uneven; re-run `extract`
   with corrected name order rather than regenerating anything.
@@ -483,9 +517,11 @@ Two hard rules:
   Display fonts run 25–50% wider than a naive estimate; widen the box or drop
   the weight, don't shrink the font.
 - **No widget overlaps** at the reference viewport, and none off-screen.
-- **Screenshot-check over real gameplay** — bright AND dark scenes — with
-  `$genex-threejs-visual-validation`'s capture discipline. Judge the pixels,
-  not your intent.
+- **Screenshot the running HUD and inspect it** — bright AND dark scenes —
+  with `$genex-threejs-visual-validation`'s capture discipline. **Zoom every
+  corner:** no sheared frames, no clipped/cut corners, no text truncated or
+  colliding with an edge. Judge the pixels, not your intent — skipping this is
+  exactly how the "cut corners" defect ships.
 
 ## The closing wiring audit — the pipeline's final stage, not optional
 
@@ -517,6 +553,16 @@ does not count. fillBox numbers, `segments`, and real sprite dims do not
 survive paraphrase; the canonical version of this failure is a subagent
 reporting "masks validated" while the parent ships width% fills.
 
+**Do not fire-and-forget the whole HUD/menu/logo into one background subagent.**
+The field failure: the entire production art pipeline was handed to a single
+background agent that then stalled overnight, so every preview the user played
+showed the CSS placeholder and the real HUD only landed hours later, unseen. If
+art runs in a subagent it is a BOUNDED task you wait on, then wire and verify in
+THIS session — not an overnight handoff. While the art is pending the HUD is
+unverified: do not call the game done or push it as a finished milestone. If a
+subagent stalls or misses its window, wire what landed and say plainly what is
+still placeholder — never present a placeholder HUD as the finished look.
+
 ## Cost & latency honesty
 
 A full HUD is **~9 image generations** (mockup + deconstruct + clean + a few

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
@@ -368,13 +370,14 @@ not):
   re-anchored the look) re-opens this rule once — re-edit the still
   (`--edit` against the new concept mockup) and re-run the video from the
   new still. Agent-initiated polish never does.
-- **1080p is the default — leave it.** The menu clip is full-screen key art,
-  the first moving thing the player sees, and 720p visibly softens it on any
-  modern display. `genex video` renders 1080p by default; pass
-  `--resolution 720p` only as an explicit cost fallback (about half the
-  credits) when the user asks to economize. The flip side of 1080p: getting
-  the phone rule above wrong now costs twice as much bandwidth — poster on
-  phone tiers, always.
+- **The menu (`--frame`) path renders 720p — don't force 1080p.** The
+  frame-conditioned first-last-frame route was rejected by the provider at
+  1080p (repeated 422 failures that shipped a dead static menu), so the menu
+  video path defaults to the proven-good, seamless-looping 720p — no flag
+  needed. The DOM crossfade + full-screen scale read fine at 720p; do NOT pass
+  `--resolution 1080p` on a `--frame` menu clip just to sharpen it, or you risk
+  re-triggering the 422 and losing the video entirely. (Plain text-to-video,
+  without `--frame`, still defaults to 1080p.)
 - **Pause/victory/defeat variants reuse the same video — as GRADES.** Same
   `<video>` element or URL, different emotion via CSS `filter` on the
   background: pause = a plain dark overlay (`rgba(0,0,0,0.55)`); defeat =
@@ -404,9 +407,11 @@ not):
   genuine state change; expect a loop seam.
 - `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
   default 8.
-- `--resolution <720p|1080p>` (video) — default 1080p; `720p` is the
-  explicit cost fallback (~half the credits). Loop clips (`--loop`) ignore
-  it (that model has no resolution parameter).
+- `--resolution <720p|1080p>` (video) — plain text-to-video defaults to 1080p;
+  the frame-conditioned (`--frame`) menu path defaults to **720p** for
+  reliability (1080p was rejected there). `720p` is also the cost fallback
+  (~half the credits). Loop clips (`--loop`) ignore it (that model has no
+  resolution parameter).
 - `--aspect 16:9 --quality high` (image) — the right settings for a menu frame.
 - `--no-wait` — enqueue and return immediately with the generation id; pick
   the result up later with `npx genex wait <id>` (safe to re-run — it attaches

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,22 @@ const gltf = await loadModelWithFallback(
   MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
 );
 const model = gltf.scene;
+// Tame ONLY the provider's mirror-metal artifact (metalness≈1 + near-zero
+// roughness mirrors the whole sky env and swims with every camera move). Do
+// NOT flatten every material to 0.6 — that was dulling legitimately metallic
+// props (gunmetal, chrome, gold, polished stone). Clamp the extreme case only;
+// leave everything else as authored.
+model.traverse((o) => {
+  const m = (o as THREE.Mesh).material as THREE.MeshStandardMaterial;
+  if (!m?.isMeshStandardMaterial) return;
+  if (m.metalness > 0.85 && m.roughness < 0.2) {
+    m.metalness = 0.7; // still reads metallic, no longer a full mirror
+    m.roughness = Math.max(m.roughness, 0.3);
+  }
+  m.envMapIntensity = Math.min(m.envMapIntensity, 0.8);
+});
+// If a model that SHOULD read metallic still looks dull, this clamp is not the
+// cause — check the model against the concept and lift per-material as needed.
 model.scale.setScalar(1); // tune to taste
 model.position.set(0, 0, 0);
 scene.add(model);
@@ -100,8 +117,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.