@genex-ai/cli-demo 0.74.0 → 0.76.0-dev.195

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

@@ -87,7 +87,7 @@ scene.background = texture; // keep the raw texture for the visible sky
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this skybox generation. Tell the user the facts the CLI printed: their balance, this
   generation's cost, and when their credits refill. Then offer to continue the build

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

@@ -225,7 +225,7 @@ first one is the one a screenshot of the whole arena will not show you.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this texture generation. Tell the user the facts the CLI printed: their balance,
   this generation's cost, and when their credits refill. Then offer to continue the

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

@@ -145,7 +145,7 @@ set belongs to `$genex-ai-hud` — both build on `npx genex image`/`video`.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user

package/templates/skills/genex-explore/SKILL.md

@@ -71,7 +71,7 @@ Add `--json` for machine-readable output.
 
 1. `git clone <clone URL from the output> <name>` — pick a short one-word name.
 2. `cd <name>`, then run init on the SAME CLI channel your current project
-   uses: `npx @genex-ai/cli-demo@latest init <name>` — or `@dev` when you're
+   uses: `npx @genex-ai/cli-demo@dev init <name>` — or `@dev` when you're
    on the dev stand (unsure? `dashboardOrigins` in your current project's
    `.genex/project.json` says which). Never use `--force`. This creates your
    own project; the original is untouched.

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

@@ -130,7 +130,7 @@ and re-link the clone to the same live game:
 ```bash
 git clone <the game's repo url> my-game && cd my-game
 npm install
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 ```
 
 Don't know the slug? **`npx genex list`** prints every game on your account —
@@ -157,7 +157,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

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

@@ -23,20 +23,32 @@ you still verify on desktop only.
 npx genex controller quality
 ```
 
-Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts}` —
-game-owned code, edit freely.
+Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts,
+gltf-loader.ts}` — game-owned code, edit freely — plus the KTX2 basis
+transcoder (`basis_transcoder.js` + `.wasm`) into `public/assets/` (loaded by
+path at runtime; Vite would drop it anywhere else).
 
 ## Wire the tier at boot (before renderer construction)
 
 ```ts
-import { detectTier } from "./controllers/quality/tier.ts";
+import { detectTier, rendererAntialias } from "./controllers/quality/tier.ts";
 import { QualityGovernor } from "./controllers/quality/governor.ts";
 
-const tier = detectTier(); // phone-low | phone | desktop; manual Quality setting wins
-const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias });
+const tier = detectTier(); // phone-low | phone | desktop-low | desktop; manual Quality setting wins
+// Context MSAA is WASTED under an EffectComposer (it multisamples a buffer the
+// composer never reads — the classic weak-MacBook lag recipe). Games with a
+// post stack pass willRunPost=true and get their AA from the composer target:
+const renderer = new THREE.WebGLRenderer({ antialias: rendererAntialias(tier, true) });
 renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap));
+// With post: AA comes from the composer's multisampled target instead —
+const target = new THREE.WebGLRenderTarget(innerWidth, innerHeight, { samples: tier.composerSamples });
+const composer = new EffectComposer(renderer, target);
 ```
 
+`detectTier()` also demotes WEAK desktops (Intel iGPU MacBooks, old integrated
+AMD — desktop GPU strings are unmasked, unlike iOS) to `desktop-low`: DPR 1.5,
+no MSAA, 1024 shadows, light post. The Quality picker still overrides.
+
 The tier owns every budget decision: `dprCap` (1.5 on phones — the single
 biggest framebuffer lever), `antialias` (off on phones; it is fixed at context
 creation and can never change live), `shadowMapSize` (1024 phone / 2048
@@ -51,6 +63,10 @@ knobs may change at runtime vs load time vs never: [references/adaptive-quality.
 const governor = new QualityGovernor(tier, {
   setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)),
   setPostEnabled: (on) => (composerEnabled = on),
+  setShadowQuality: (level) => {
+    sun.shadow.mapSize.setScalar(level === 'full' ? tier.shadowMapSize : tier.shadowMapSize / 2);
+    sun.shadow.map?.dispose(); sun.shadow.map = null; // realloc at the new size
+  },
   setDrawDistanceScale: (m) => (scene.fog!.far = baseFogFar * tier.drawDistanceScale * m),
 }, renderer);
 
@@ -58,9 +74,9 @@ const governor = new QualityGovernor(tier, {
 governor.frame(deltaMs);
 ```
 
-Sustained slow frames step down (DPR ×0.8 → post off → draw distance →
-30 fps cap); twenty smooth seconds step back up; a knob that failed twice
-stays down for the session. It keeps governing forever — thermal throttling
+Sustained slow frames step down (DPR ×0.8 → post off → shadows reduced →
+DPR ×0.65 → draw distance → 30 fps cap); twenty smooth seconds step back up; a
+knob whose recovery failed twice stays down for the session. It keeps governing forever — thermal throttling
 arrives at minute eight, not second thirty. It also pauses judgment when the
 tab is hidden and publishes memory counts the platform's crash telemetry
 reads; pause your own loop and audio on `visibilitychange` too.
@@ -84,6 +100,31 @@ Desktop loads the original, phones the `@2048` rung (~11 MB), and a missing
 rung falls back to the original — never a broken boot. The `$genex-ai-skybox`
 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
+compressed ON the GPU (~6× less texture VRAM). A plain `GLTFLoader` can decode
+neither — wire the decoders once and load through the ladder:
+
+```ts
+import { createGltfLoader } from "./controllers/quality/gltf-loader.ts";
+import { loadModelWithFallback } from "./controllers/quality/pick-asset.ts";
+
+const gltfLoader = createGltfLoader(renderer); // meshopt always; KTX2 when the transcoder is present
+const gltf = await loadModelWithFallback(
+  MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
+);
+```
+
+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
+`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.
+
 ## Quality picker in settings
 
 The pause/settings screen (see `$genex-threejs-game-ui`) always carries a

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

@@ -14,19 +14,28 @@ cost of guessing high is a dead page.
 
 ## The tier ladder
 
-| Knob | phone-low | phone | desktop |
-|---|---|---|---|
-| DPR cap | 1.0 | 1.5 | 2 |
-| antialias (context) | off | off | on |
-| Shadow map | 512 (static-cached) | 1024 | 2048 |
-| Post level | tone map only | + FXAA/vignette | full named stack |
-| Skybox rung | @2048 (~11 MB) | @4096 (~45 MB) | original |
-| Texture rung (props) | @1024 | @2048 | original |
-| Particles/scatter | 0.25× | 0.5× | 1× |
-| Draw distance | 0.5× | 0.75× | 1× |
-| Frame target | stable 30 | 60 | 60 |
-| Remote avatars animated | 4 | 8 | all |
-| Prop colliders | hull/cuboid | hull | as designed |
+| Knob | phone-low | phone | desktop-low | desktop |
+|---|---|---|---|---|
+| DPR cap | 1.0 | 1.5 | 1.5 | 2 |
+| antialias (context, no-post games) | off | off | off | on |
+| Composer MSAA samples | 0 | 0 | 0 | 4 |
+| 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 |
+| Texture rung (props) | @1024 | @2048 | original | original |
+| Particles/scatter | 0.25× | 0.5× | 0.75× | 1× |
+| Draw distance | 0.5× | 0.75× | 1× | 1× |
+| Frame target | stable 30 | 60 | 60 | 60 |
+| Remote avatars animated | 4 | 8 | all | all |
+| Prop colliders | hull/cuboid | hull | as designed | as designed |
+
+`desktop-low` is the weak-desktop demotion (Intel iGPU MacBooks, old integrated
+AMD): desktop GPU renderer strings are UNMASKED (unlike iOS), so one boot probe
+separates a 2015 Intel Air from an M3 Max. The full desktop path on those
+machines — DPR 2 + 4× MSAA + 2048 PCFSoft shadows + full bloom — is the classic
+"huge lags on a MacBook" recipe, and two of its costs (context MSAA, shadow
+budget) were previously invisible to the governor.
 
 A DPR drop from 3 (raw iPhone) to 1.5 cuts every full-screen surface — color,
 depth, and each post target — to a quarter of the bytes. It is the single
@@ -40,7 +49,10 @@ Getting this wrong produces silent no-ops or a session stuck ugly:
   `stencil`, `powerPreference` on WebGL. Changing them means a new context and
   a full re-init — the tier must decide them BEFORE the renderer exists.
   (WebGPU differs: MSAA is per-render-target sample count and is runtime-
-  changeable.)
+  changeable.) **Context MSAA under an EffectComposer is pure waste** — it
+  multisamples a buffer the composer never reads. Post games construct with
+  `rendererAntialias(tier, true)` (false) and put their AA on the composer's
+  own target via `tier.composerSamples`; only no-post games keep context MSAA.
 - **Load-time (fixed for the session once fetched):** asset rungs (skybox and
   texture resolutions), model LOD sets. `pickAsset` decides them from the tier
   at load; switching later means a re-fetch — treat as fixed.
@@ -56,8 +68,11 @@ Getting this wrong produces silent no-ops or a session stuck ugly:
   `renderer.compileAsync` during the loader screen removes most spikes at the
   source (and keeps first-frame jank from reading as a stall to the platform's
   telemetry).
-- Step-down order: DPR ×0.8 → post off → draw distance ×0.6 → 30 fps cap.
-  Each step is the cheapest remaining lever with the biggest headroom return.
+- Step-down order: DPR ×0.8 → post off → shadows reduced (half the map +
+  realloc via `setShadowQuality`) → DPR ×0.65 → draw distance ×0.6 → 30 fps
+  cap. Each step is the cheapest remaining lever with the biggest headroom
+  return; the shadow rung and second DPR step exist because one ×0.8 was
+  often not enough on weak desktops.
 - Step-up needs 20 smooth seconds (hysteresis), and a step that had to be
   re-applied twice is pinned for the session — oscillating quality reads worse
   than stable-low.

package/templates/skills/genex-threejs-character-controller/SKILL.md

@@ -57,7 +57,10 @@ 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.
+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.)
 
 That is a separate, **same-rig Meshy-native lane**. Its animation-only GLBs are
 accepted only when their skeleton signature matches the active character

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

@@ -50,7 +50,9 @@ Rules that make the contract real:
   a milestone on the way to the contract, never a quiet replacement for it.
   If the full ask genuinely doesn't fit, shrinking any line is a structured
   question to the user with real options — never a silent cut justified as
-  "standard practice".
+  "standard practice". (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.)
 - **Minute ten is the design test.** If the honest answer is "the same sixty
   seconds, again", the contract needs another beat (a new area unlocks, a
   quest chain escalates, a build comes online) before any polish work.

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

@@ -67,31 +67,37 @@ AAA games of the genre, and state in one line which structural conventions
 you're borrowing. The bar is what those games ship, not "good enough for a
 demo". Conventions only — never logos, exact layouts, or trade dress. The
 same 2–3 names carry into the router's visual-direction gate for the scene.
-Then turn references + brief into ONE **concept frame** — a single generated
-image of a PLAYABLE MOMENT of this game, not key art. Build the prompt from
-the game contract, not just the mood: what the player is DOING mid-action
-(the verb), what threatens them right now (enemy silhouettes), what they
-are chasing (the objective — a finish gate, a goal, a pickup), and how the
-space reads (route, scale) — plus the brief's palette, materials, and
-light. A beautiful empty vista with nothing to fight and nowhere to go is a
-FAILED concept; so is one that invents mechanics the game doesn't have (a
-lap counter in a game without laps). `--aspect 16:9 --quality high
---no-wait`, enqueued FIRST of all art; the URL goes into the style-brief
-comment.
+Then turn references + brief into ONE **concept mockup** — the game concept
+and the HUD Stage-1 mockup are the SAME image, generated once (never a
+separate UI-free concept first): a single image of a PLAYABLE MOMENT of this
+game with its complete HUD composited over it, built with `$genex-ai-hud`'s
+Stage-1 prompt template. The scene half of the prompt comes from the game
+contract in TEXT, not from a prior image: what the player is DOING
+mid-action (the verb), what threatens them right now (enemy silhouettes),
+what they are chasing (the objective — a finish gate, a goal, a pickup),
+and how the space reads (route, scale) — plus the brief's palette,
+materials, and light. A beautiful empty vista with nothing to fight and
+nowhere to go is a FAILED concept; so is one that invents mechanics the
+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 concept lands, enqueue the Tier-2 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
+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 link. Paste that URL as a clickable link in
-your message — a URL is invisible in a terminal, and "do you like it?" with
+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 will look: keep it, or change something?" — **as
+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; only explicit notes reopen the style. An unanswered style
+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
@@ -103,19 +109,25 @@ 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-anchor the style-carrying art made against
-the old frame: the menu still is re-edited (`--edit`) against the new frame
-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 chrome
-re-runs its pipeline from Stage 1 with the new frame as the `--edit` anchor
-(`$genex-ai-hud` — budget the full serial chain; it is the most expensive
-re-anchor in the set). Style-neutral assets (most textures, sfx, models)
-usually survive — judge each in one line. The same "open it + paste the
+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.
 
 **The concept anchors STYLE, not truth.** Palette, materials, light, and
-register come from the frame; CONTENT comes from the game contract. When
+register come from the frame; CONTENT comes from the game contract. This
+matters MORE now that the concept carries a HUD: every widget in the mockup
+is a PROPOSAL, and a widget with no backing mechanic is cut before Stage 2 —
+mechanics come from the agreed game, never from the picture. Extra widgets
+the image invented are recorded in the plan message as "deferred from
+mockup" — never silently wired, never silently dropped. When
 the frame lands, diff it against the contract in one visible line — what
 does this game have that the frame doesn't show (enemies? arenas? the
 finish? the pickup)? Carry those requirements in words into every later
@@ -125,9 +137,11 @@ an invented mechanic, or the absence of a real one, from a picture.
 **4. Ask only when genuinely ambiguous.** If the concept pins the mood (a
 "gothic horror dungeon crawler" pins it), decide and state the plan in one
 line. Only when the art direction is truly open, ask ONE structured question
-(your environment's `AskUserQuestion`-style tool) with 2–3 concrete directions,
-each naming its palette + font pair. Never ask about the screen inventory —
-it derives from the game type.
+with 2–3 concrete directions, each naming its palette + font pair — using
+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. Never ask about the screen
+inventory — it derives from the game type.
 
 **5. Style follows THIS game's concept.** The examples in every Genex skill
 are examples, not defaults. Do not default to neon/cyberpunk/synthwave — or
@@ -143,8 +157,11 @@ UI plan
 • Screens: <list with tiers — loader / menu / pause (Esc) / win/lose / …>
 • Style: <4–5 named hues> · fonts <display> / <body>
 • References: <2–3 AAA games — one line on what's borrowed>
-• Concept frame: <generation id>
-• Queued: HUD chrome <id> · menu video <id or "no menu: reason">
+• 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">
+• Deferred from mockup: <widgets the image invented but the game lacks — or "none">
 ```
 
 A message missing any line means the gate did not run — go back and run it.
@@ -156,9 +173,12 @@ A message missing any line means the gate did not run — go back and run it.
   navigation, phase transitions, UI sounds, vignette. Zero generations — the
   game is playable immediately.
 - **Tier 2 — the production UI, generated, async — mandatory, not an upsell.**
-  The sprite HUD (`$genex-ai-hud`) for EVERY game, and the cinematic menu
+  The sprite HUD (`$genex-ai-hud`) for EVERY game, the cinematic menu
   video (`$genex-ai-menu`) whenever the menu decision is yes (the default for
-  every game). Enqueue BOTH at the plan gate with `--no-wait`,
+  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`,
   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
@@ -169,7 +189,7 @@ A message missing any line means the gate did not run — go back and run it.
   Shipping the placeholder CSS HUD as the final HUD is a failure, not a
   tier choice.
 - **Tier 3 — offer, don't build.** Video layers over the HUD, 9-slice panel
-  sprites, a generated logotype, animated menu sprites. Offer in one line
+  sprites, animated menu sprites. Offer in one line
   after the player has seen Tier 1+2 working; build on request.
 
 ## Architecture: DOM overlay by default
@@ -470,6 +490,11 @@ architecture and consume the shared style brief.
 
 - No UI plan: screens invented one at a time, menu and HUD styled in two
   different worlds.
+- A separate UI-free concept frame generated before the HUD mockup — the
+  concept IS the Stage-1 mockup, one generation; a second scene image for
+  "the concept" is a wasted spend and a style-drift risk.
+- The concept/mockup fed to `genex video --frame` — it has a HUD baked in;
+  the UI-free menu still is the ONLY valid frame input (`$genex-ai-menu`).
 - HUD sprites never enqueued at the gate — the placeholder CSS shipped as the
   final HUD.
 - No pause screen, or a pause that isn't bound to Escape.

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

@@ -25,6 +25,9 @@ artifacts, and text never collides or truncates.
 - Serif or engraved display type; humanist body; muted earthy palette with ONE
   saturated accent reserved for danger/low-health.
 - Feedback is material: gold glints on pickup, red vignette pulse on damage.
+- Menu lean: **boxed plate buttons** (or left rail when the vista carries a
+  strong subject); ornate engraved logotype; sprite-chrome buttons suit the
+  most crafted briefs.
 
 ## Clean sci-fi / space
 
@@ -35,6 +38,8 @@ artifacts, and text never collides or truncates.
 - Panels read as glass: slight transparency, subtle inner glow, no drop
   shadows heavier than a whisper.
 - Motion is precise and quick (120–200 ms), no bounce.
+- Menu lean: **centered stack** or **minimal fullbleed**; hairline plate
+  buttons or bare text with wide tracking; a thin geometric logotype.
 
 ## Racing / arcade sport
 
@@ -46,6 +51,8 @@ artifacts, and text never collides or truncates.
 - Saturated team/brand hues are fine — but two, not six.
 - Values tween FAST (speed) or pop (position change); a gear change may
   flash — a full-screen flash may not.
+- Menu lean: **bottom command bar** (a garage/grid row); oblique bare-text
+  or chip buttons; a fast angular logotype.
 
 ## Military / modern shooter
 
@@ -54,6 +61,8 @@ artifacts, and text never collides or truncates.
 - Stencil or condensed grotesque display; desaturated palette — amber/red
   exist ONLY as warnings, so they still mean something.
 - Damage reads as a directional vignette, not a number cloud.
+- Menu lean: **left rail** with stencil bare text, or a **bottom command
+  bar**; a stencil logotype, desaturated.
 
 ## Horror
 
@@ -63,6 +72,8 @@ artifacts, and text never collides or truncates.
   grain in the cohesion layer.
 - UI motion is slow (400 ms+) and quiet; a sudden UI move is itself a scare —
   spend it deliberately.
+- Menu lean: **diegetic corner** or **minimal fullbleed** — prompt the still
+  to leave a calm region for the buttons; worn-type logotype, dim.
 
 ## Retro / 8-bit
 
@@ -72,6 +83,8 @@ artifacts, and text never collides or truncates.
   already know; lean on them.
 - Motion is stepped (frame-quantized), not eased; an optional scanline overlay
   in the cohesion layer sells it.
+- Menu lean: **centered stack** (the arcade attract screen); pixel-font bare
+  text with a blinking selector; a chunky pixel logotype at integer scale.
 
 ## Cozy / casual
 
@@ -81,6 +94,8 @@ artifacts, and text never collides or truncates.
   (scale 0.95 → 1.02 → 1) instead of fading.
 - Nothing flashes red; even failure is gentle (desaturate + a soft "try
   again").
+- Menu lean: **centered stack** with plump CSS plate buttons; a rounded
+  friendly logotype.
 
 ## Painterly / stylized adventure
 
@@ -90,3 +105,5 @@ artifacts, and text never collides or truncates.
   readability.
 - Palette lifted from the scene's own key art — sample it, don't invent a
   second palette.
+- Menu lean: **left rail** or **diegetic corner** over the painted vista;
+  brushwork logotype; bare text with calligraphic display face.

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -67,6 +67,9 @@ Infer this yourself when the experience is clear. Do **not** make the player cho
 preset, or config. Ask one plain-language question only when the design genuinely supports both
 models and the answer changes the experience — for example: *"Should this be one ongoing arena
 people drop into, or a fresh fair match that waits for everyone and then starts together?"*
+(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.)
 
 | Player experience | Model | Why |
 | --- | --- | --- |

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

@@ -114,7 +114,10 @@ chain, which locations, what progression), plus the minute-ten answer. Those
 lines are hard floors exactly like the sprite HUD — the game is not done,
 published, or handed off while a contract line is missing, and shrinking one
 is a structured question to the user, never a silent cut ("vertical slice
-first" is a build order, not a smaller destination). A request that says
+first" is a build order, not a smaller destination) — 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. A request that says
 **big/open world** also loads `$genex-threejs-open-world` and fixes the
 world's scale as a number in the same plan — world size comes from streamed
 terrain, never from fog hiding the edges of a small plane. This routing

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

@@ -29,7 +29,10 @@ Three.js release or branch, and do not blindly copy demo architecture.
    additionally fixes the world's scale class as a number here via
    `$genex-threejs-open-world` — kilometers of streamed terrain, never one
    fogged plane. Scope belongs to the user: shipping fewer or smaller than
-   the ask requires their explicit OK through a structured question — a
+   the ask requires their explicit OK through a structured question (your
+   environment's structured question tool when it has one — Claude Code:
+   `AskUserQuestion`; Codex: `request_user_input`; if none, e.g. Cursor, a
+   short numbered list in chat) — a
    "vertical slice first" is a build order, never a license to shrink the
    destination silently. **Close the contract with the reuse sweep:** run
    `npx genex explore` once (no query) and map the plan's systems against the
@@ -49,9 +52,12 @@ Three.js release or branch, and do not blindly copy demo architecture.
    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 frame** —
+   while you build the game. FIRST of all art: the gate's **concept mockup** —
    a playable-moment shot (verb + threat + objective in frame, per the
-   game-ui gate), shown to the user for a keep-or-change answer the moment
+   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
@@ -224,11 +230,17 @@ 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.
 
-- **HUD chain worker.** The moment the Stage-1 mockup lands, hand the whole
+- **HUD chain worker.** The moment the Stage-1 mockup (the game concept)
+  lands, 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, concept-frame and mockup URLs, the
-  output dir, and exactly which files it owns.
+  be self-contained — the style brief, the 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
+  numbers, `segments`, and sprite dims do not survive a prose summary, and
+  wiring from the summary is how validated masks end up on disk while the
+  shipped fill is a naive width%.
 - **Asset shepherd.** One subagent runs `npx genex wait` on every queued ID
   and wires each asset in as it lands (skybox, models, menu video, dressing),
   swapping placeholders out and reporting each swap.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -40,7 +40,10 @@ 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.
+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.)
 
 The selected high-detail model remains in a neutral A-pose before animation.
 Record evidence that the user saw its four views and face count before

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```