@genex-ai/cli-demo 0.48.0-dev.76 → 0.48.0-dev.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.48.0-dev.76",
+  "version": "0.48.0-dev.79",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-hud
-description: Generate a production HUD sprite set — matched frames, masks, and icons in one coherent art style — via the mockup-then-deconstruct pipeline (`npx genex image` + `npx genex ui`), then wire it as a DOM overlay with channel-accurate masked fills. Use when the game wants a cohesive art-directed HUD (fantasy brass, sci-fi glass, racing carbon) rather than a clean minimal CSS HUD.
+description: Generate a production HUD sprite set — matched frames, masks, and icons in one coherent art style — via the mockup-then-deconstruct pipeline (`npx genex image` + `npx genex ui`), then wire it as a DOM overlay with channel-accurate masked fills. Use for EVERY game, kicked off at `genex-threejs-game-ui`'s "Plan the UI first" gate: the sprite HUD is the production HUD of a Genex game; hand-written CSS is only the placeholder while the sprites render.
 ---
 
 # Genex AI · HUD
@@ -11,16 +11,46 @@ with masked fills that track the art's real channels. The result is an
 art-directed HUD (etched steel ammo strip, parchment HP bar, chrome minimap
 ring) that no hand-written CSS can fake.
 
-## When to use this vs. a hand-coded CSS HUD
-
-- **Use `$genex-threejs-game-ui` alone** (clean CSS bars, text, plates) for
-  most games — it's faster, crisper, and always readable. That skill also owns
-  the overlay architecture this one plugs into.
-- **Use this skill** when the game's identity wants a *materially* art-directed
-  HUD — gothic filigree frames, rusted post-apocalyptic panels, carbon-fiber
-  racing telemetry, hand-painted storybook plates — where the frames themselves
-  are illustrations. You'll spend ~10 image generations and real wiring effort;
-  make sure the game deserves it.
+## This is the default HUD — hand-coded CSS is the placeholder
+
+- **Every game runs this pipeline.** Kick the Stage-1 mockup off at
+  `$genex-threejs-game-ui`'s "Plan the UI first" gate (`--no-wait`) and build
+  against that skill's plain-CSS placeholder while it renders — that skill
+  also owns the overlay architecture this one plugs into. The game is not
+  done until the sprites have landed and been wired in.
+- The art direction comes from the shared style brief — gothic filigree
+  frames, rusted post-apocalyptic panels, carbon-fiber racing telemetry,
+  hand-painted storybook plates, or a restrained modern register for a clean
+  concept; restrained still means built from the generated set. ~10 image
+  generations is the normal price of a production HUD, not a premium to
+  justify.
+- **The only exit:** the user explicitly declines the generated HUD — then
+  the CSS placeholder, finished to `$genex-threejs-game-ui`'s Tier-1 floor,
+  ships as the HUD.
+
+## Three layers — glass is CSS, chrome is sprites, data is DOM
+
+- **Glass (DOM).** The translucent plate behind every widget is CSS —
+  `background: rgba(<brief's darkest hue>, 0.35–0.6)` plus
+  `backdrop-filter: blur(6–12px)` (and its `-webkit-` twin). 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 — so glass
+  is NEVER baked into a sprite. This is how AAA smoked-glass HUDs are built:
+  live glass panels, crisp art on top.
+- **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
+  fill or glass surface baked in.
+- **Data (DOM).** Numbers, labels, and bar fills are DOM text and masked
+  fills (the fillBox pattern below) — always over the glass, never
+  rasterized into art.
+- **Micro-elements are designed, not defaulted.** The sheet excludes
+  primitive-only shapes (plain crosshair ticks, dots, pips) because CSS
+  renders them crisper — but CSS never means default: the reticle and every
+  cue, toast, and counter still get the brief's treatment (stroke weight,
+  glow, state changes — hit, low-ammo, empowered). An ornamented,
+  identity-bearing reticle (engraved ring, sculpted brackets) is chrome —
+  put it on the sheet like any other asset.
 
 ## Framing rules — internalize before prompting
 
@@ -30,6 +60,10 @@ The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
   fabric, wood board) as part of the HUD. Material aesthetics belong on the
   widget FRAMES — the HP bar frame is parchment, the minimap ring is leather —
   never on a screen-filling sprite.
+- **No glass in sprites.** Translucent panel plates in the mockup are welcome
+  as the LOOK, but the Stage-2 asset list requests only their opaque chrome
+  (frame, brackets, ornament); the plate itself is rebuilt at runtime as CSS
+  glass matching the mockup's tint (see the three layers above).
 - **4–7 widgets.** Fewer doesn't read as a HUD; more clutters the screen and
   burns generations.
 - **Every widget needs internal contrast** — a panel fill, outline stroke, or
@@ -86,7 +120,10 @@ and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
 **Order of work: kick Stage 1 off as your FIRST action after the UI plan
 gate**, 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. Generate 2 mockup candidates in one
+the game playable until the sprites land. When the gate produced a concept
+frame, anchor Stage 1 to it — `--edit <concept-url>` holds the game's
+register far better than a text-only prompt; single-sprite regenerations
+anchor the same way. Generate 2 mockup candidates in one
 call (`--candidates 2`) and pick the better one: a re-roll costs the whole
 serial chain, a second candidate costs nothing extra in wall-clock.
 

package/templates/skills/genex-ai-hud/references/stage2-prompt-template.md

@@ -15,6 +15,10 @@ Fill `[ASSET_LIST]`, then pass the whole text as the prompt to
   identity labels);
 - **states what to REMOVE** (`runtime_static` labels and `runtime_dynamic`
   values, fills, items);
+- **requests chrome only** — never a panel's translucent plate or glass
+  surface: plates are rebuilt at runtime as CSS glass (rgba +
+  backdrop-filter), so ask for the panel's frame/brackets/ornament, not the
+  panel surface itself;
 - **requests the annotated duplicate** for every bar/meter frame (the
   template's progress block below covers the mechanics — your item just says
   "output the clean frame + annotated duplicate pair").
@@ -61,7 +65,7 @@ DO NOT include in the output sheet:
 - Simple dot indicators, status pips, blip markers
 - Fills inside bars, items inside slots, map terrain inside minimap rings (these are added at runtime by CSS / game code)
 
-Those excluded elements will be recreated by runtime code (CSS shapes and DOM text) — much crisper than a downsampled PNG.
+Those excluded elements will be recreated by runtime code (CSS shapes and DOM text) — much crisper than a downsampled PNG. Recreated does NOT mean default-styled: reticles, pips, and cues still follow the style brief (stroke weight, glow, state colors). An ornamented, identity-bearing reticle — an engraved ring, sculpted brackets — is NOT a simple primitive; include it in the asset list like any other chrome.
 
 Pure white #ffffff background everywhere except where the actual UI assets sit.
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-menu
-description: Generate a cinematic game menu — one looping atmospheric video background plus animated DOM buttons — with `npx genex image` + `npx genex video --frame`. Use for main menus, title/start screens, pause, victory/defeat, lobby, and credits screens when the game deserves a filmic backdrop ("storm light over a lighthouse coast", "sun-drenched poppy meadow") rather than a plain CSS panel.
+description: Generate a cinematic game menu — one looping atmospheric video background plus animated DOM buttons — with `npx genex image` + `npx genex video --frame`. Use for the main menu of every game (the default tier per `genex-threejs-game-ui`'s plan gate, enqueued there with `--no-wait`; declining it needs a stated reason) and for title, victory/defeat, lobby, and credits screens that should feel like the game's opening shot; plain CSS panels are only for utilitarian overlays like pause and settings.
 ---
 
 # Genex AI · Menu
@@ -12,14 +12,16 @@ real game events.
 
 ## When to use this vs. a plain CSS menu
 
-- **Use this skill** when the menu should feel like the game's opening shot —
-  a title screen with weather and light, a defeat screen over smoldering ruins,
-  a lobby with the arena breathing in the background.
+- **Use this skill** for the main menu of every game — it should feel like the
+  game's opening shot: a title screen with weather and light, a defeat screen
+  over smoldering ruins, a lobby with the arena breathing in the background.
+  Enqueue it at `$genex-threejs-game-ui`'s plan gate with `--no-wait`.
 - **Use plain CSS** (`$genex-threejs-game-ui` alone) for utilitarian screens —
-  a quick pause overlay, a settings list, a loading bar. A dark translucent
-  panel is cheaper and often more readable. You can also get the best of both:
-  reuse this skill's menu video under a darker overlay for pause/victory
-  variants (see Tips).
+  a quick pause overlay or a settings list. A dark translucent panel is often
+  more readable there. (The loader is NOT utilitarian: it keeps its branded
+  key-art background per the game-ui spec — "plain CSS" never means a bare
+  loading bar.) You can also get the best of both: reuse this skill's menu
+  video under a darker overlay for pause/victory variants (see Tips).
 
 ## Style brief first
 
@@ -46,6 +48,14 @@ might suggest. Two hard rules for the frame prompt:
   perches", "fog drifts left then back right", "candle flames flicker".
   Bad: "camera dollies forward into the gate" (one-way motion fights the
   identical endpoints and produces a visible hitch).
+  **The seam is YOUR job, not the model's:** in practice the clip lands
+  *near* frame 0, not exactly on it, and a bare `video.loop = true` shows a
+  visible hitch every cycle. Always wire the video with the DOM crossfade
+  below, and watch one full cycle before calling the menu done. (Do not
+  reach for `--loop` here: it routes to a different model with a first-class
+  loop param but NO frame conditioning — the video won't match your key art —
+  and server-side `--frame` overrides `--loop` anyway, so passing both does
+  nothing.)
 - **Two-frame** (`--first-frame` + `--last-frame`) only when the menu
   genuinely needs a state change (rain starts and persists, a figure walks in
   and stays). The loop will have a visible seam where the last frame snaps
@@ -69,6 +79,44 @@ npx genex wait <gen-id>
 # -> https://assets.genex.technology/generations/<gen-id>/video-mp4
 ```
 
+## Seamless in the DOM — the loop crossfade (mandatory wiring)
+
+Never wire the clip as a bare `<video loop>` — the residual seam shows every
+cycle. Two stacked `<video>` elements with the same src crossfade at the
+cycle end; any seam disappears deterministically, no regeneration lottery:
+
+```ts
+/** Deterministic seamless loop: two stacked <video>s crossfade at cycle end. */
+export function seamlessLoop(holder: HTMLElement, url: string, fade = 0.6): void {
+  const mk = (): HTMLVideoElement => {
+    const v = document.createElement("video");
+    v.src = url; v.muted = true; v.playsInline = true; v.preload = "auto";
+    holder.appendChild(v);
+    return v;
+  };
+  let front = mk(), back = mk();
+  front.style.opacity = "1";
+  void front.play();
+  const tick = (): void => {
+    if (front.duration > 0 && front.currentTime >= front.duration - fade && back.paused) {
+      back.currentTime = 0;
+      void back.play();
+      front.style.transition = back.style.transition = `opacity ${fade}s linear`;
+      back.style.opacity = "1";
+      front.style.opacity = "0";
+      const old = front; front = back; back = old;
+      window.setTimeout(() => back.pause(), fade * 1000 + 50);
+    }
+    requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+}
+```
+
+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
 (buttons + title over the frame IMAGE as a static backdrop), and swap the
@@ -87,9 +135,8 @@ copy-pasteable example:
 ```html
 <div id="ui">
   <div id="screen-menu" class="screen" data-phase="menu">
-    <video class="menu-bg"
-      src="https://assets.genex.technology/generations/<id>/video-mp4"
-      autoplay muted loop playsinline></video>
+    <!-- seamlessLoop() (above) injects two crossfading <video>s here -->
+    <div class="menu-bg" id="menu-bg"></div>
     <div class="menu-title stagger" style="--i: 0">EMBERFALL</div>
     <button class="menu-btn stagger" id="menu-play"    style="--i: 1; left: 38%; top: 52%; width: 24%; height: 8%;">PLAY</button>
     <button class="menu-btn stagger" id="menu-options" style="--i: 2; left: 38%; top: 63%; width: 24%; height: 8%;">OPTIONS</button>
@@ -102,7 +149,9 @@ copy-pasteable example:
 
 ```css
 #screen-menu { position: absolute; inset: 0; overflow: hidden; background: #000; }
-.menu-bg { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.menu-bg { position: absolute; inset: 0; }
+.menu-bg video { position: absolute; inset: 0; width: 100%; height: 100%;
+                 object-fit: cover; opacity: 0; }
 .menu-title {
   position: absolute; left: 0; right: 0; top: 14%; text-align: center;
   font-family: "Cinzel", serif; font-size: 9vh; color: #f4e3b8;

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

@@ -23,19 +23,30 @@ in another.
 | Screen | When it exists | Default tier |
 | --- | --- | --- |
 | Loader | always | 1 — branded (see loader spec below) |
-| Main menu | always for a game headed to publish | 2 — cinematic (`$genex-ai-menu`); 1 for a quick prototype |
-| Pause | always | 1 — menu backdrop under a dark overlay |
+| Main menu | always — the decision defaults to YES for every game; a "no" needs a one-line game-type reason (e.g. an instant-restart arcade toy), and "it's only a draft" is never a reason | 2 — cinematic (`$genex-ai-menu`) |
+| Pause | always — opens on the Escape key | 1 — menu backdrop under a dark overlay |
 | Fail / retry | always | 1 — a *graded* variant of the menu screen |
 | Win / next | always | 1 — graded variant, warm |
 | Settings | when there is anything to set | 1 |
 | Lobby / waiting | multiplayer only | 1 over the menu backdrop |
-| HUD | always | 1 CSS; 2 (`$genex-ai-hud`) when the identity earns it |
+| HUD | always | 2 — generated sprite HUD (`$genex-ai-hud`), enqueued at this gate for EVERY game; plain CSS is the placeholder until the sprites land, never the final HUD |
 
 The lobby row is bound by `$genex-threejs-multiplayer`'s MANDATORY rule: the
 waiting overlay's visibility is re-read from `mm.matchmaking.status` every
 frame and closes the instant it flips to `playing` — verified in two browser
 windows. Plan the lobby as a styled screen (roster + count over the menu
-backdrop), not an afterthought `<div>`.
+backdrop), not an afterthought `<div>`. When the menu decision is a reasoned
+"no", every "menu backdrop" row above (pause, fail, win, lobby) grades over
+the loader's key art instead.
+
+The table lists screens; **elements are inventoried separately**. Walk the
+whole loop in your head — loader → menu → spawn → action → pickup → damage →
+death → retry → win — and write down EVERY on-screen element the player will
+ever see: the reticle and each of its states, aim/interact cues, toasts,
+damage numbers, kill feeds, timers, countdowns, pickup popups… Each element
+gets a treatment from the brief. **Nothing ships looking like default
+browser CSS** — an element styled like a bare `<div>` or a system button is
+a bug wherever it appears, listed or not.
 
 **2. One shared style brief — for the WHOLE game, not just the UI.** Write it
 once — 4–5 named hues, materials, one display + one body font, mood — and
@@ -44,12 +55,25 @@ store it as a comment block near the UI code. `$genex-ai-menu`,
 verbatim — and so does the scene: the visual-direction plan (the router's
 next gate) derives its lighting mood, fog, grading, and post-stack choices
 from the same block. Two style briefs in one game is a bug; a scene graded in
-one world under a UI styled in another is the same bug.
+one world under a UI styled in another is the same bug. The brief's font pair
+is LOADED for real — a Google Fonts `<link>` (or `@font-face`) in
+`index.html`, per `$genex-ai-menu`'s genre font table; a display font that
+ships as a system-stack fallback (`Arial Black`, `Impact`) is the same bug in
+type.
 
-**3. Name your references.** Pick the closest capsule in
+**3. Name your references — AAA, by name.** Pick the closest capsule in
 [references/style-capsules.md](references/style-capsules.md), name 2–3 top
-games of the genre, and state in one line which structural conventions you're
-borrowing. Conventions only — never logos, exact layouts, or trade dress.
+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 what THIS game should look like mid-play (scene, mood, lighting;
+a UI impression is welcome but optional):
+`npx genex image "<one-sentence game look from the brief>" --aspect 16:9 --quality high --no-wait`,
+enqueued FIRST of all art. Its URL goes into the style-brief comment as the
+game's north star: every later 2D generation that accepts `--edit` anchors
+to it, and the scene's lighting/grading is judged against it.
 
 **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
@@ -62,16 +86,41 @@ it derives from the game type.
 are examples, not defaults. Do not default to neon/cyberpunk/synthwave — or
 any other single register — unless the concept calls for it.
 
+**6. Close the gate out loud — a fixed-format plan message.** Post this
+message in chat, translated to the user's language, filling every line —
+this exact structure, not a paraphrase (the scaffold's keep-it-short talk
+rule explicitly does not apply to this one message):
+
+```
+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">
+```
+
+A message missing any line means the gate did not run — go back and run it.
+
 ## The tier ladder
 
 - **Tier 1 — instant baseline, every game.** Everything in this skill: planned
   screens, shared brief, branded loader, animated CSS menu with keyboard
   navigation, phase transitions, UI sounds, vignette. Zero generations — the
   game is playable immediately.
-- **Tier 2 — generated upgrades, async.** The cinematic menu video
-  (`$genex-ai-menu`) and the sprite HUD (`$genex-ai-hud`). Enqueue 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.**
+- **Tier 2 — the production UI, generated, async — mandatory, not an upsell.**
+  The sprite HUD (`$genex-ai-hud`) for EVERY game, and 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`,
+  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
+  exit: the user explicitly declines them — on their own initiative; never
+  solicit the decline by presenting these as optional, slow, or costly).
+  Run `npx genex wait` on every enqueued ID before any publish and before
+  the final handoff of a session — never park landed assets for "later".
+  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
   after the player has seen Tier 1+2 working; build on request.
@@ -111,9 +160,11 @@ edits scattered through the code:
 1. **Loading** — the branded loader below; players must never stare at a black
    screen or a bare percentage.
 2. **Playing HUD** — the minimal always-on layer (see hierarchy below).
-3. **Pause** — freeze the loop, dim the scene, show resume/restart. (With the
-   bundled physics pack, freezing is built in: `physics.paused = true` plus
-   `anims.setPaused(true)` — don't hand-roll a second clock.)
+3. **Pause** — freeze the loop, dim the scene, show resume/restart. Bound to
+   the **Escape key in every game** — Escape pauses, Escape again (or Resume)
+   unpauses; on touch, a small pause button. (With the bundled physics pack,
+   freezing is built in: `physics.paused = true` plus `anims.setPaused(true)`
+   — don't hand-roll a second clock.)
 4. **Fail / retry** — what happened, the score, and a ONE-KEY instant restart
    (show which key). Restart must not reload the page.
 5. **Win / next** — celebrate, then offer the next thing to do.
@@ -133,7 +184,10 @@ black reads as a broken page. The branded version costs nothing:
   that image exists BEFORE the video does; show it dimmed
   (`filter: brightness(0.6)`) behind the progress. Menu-less game: one
   `npx genex image` key-art call in the house style, enqueued first thing.
-  Until the image arrives, the flat darkest hue from the style brief.
+  Until the image arrives, the flat darkest hue from the style brief — a
+  placeholder with the same status as the placeholder CSS HUD: a loader
+  still without its key-art/menu-frame background at publish or session
+  handoff is the same failure.
 - **Progress:** a thin bar styled from the brief (its accent hue), driven by
   real asset counts — never an indeterminate spinner alone.
 - **Reveal:** when ready, fade the loader out (400–600 ms) into the menu or
@@ -224,15 +278,23 @@ timer in the game WILL drift apart). Buttons and menu keys emit the same
 intents the gameplay input path uses — a "Restart" button and the R key must
 run identical code.
 
-When the game deserves generated art in this layer: a cinematic menu (looping
-video backdrop behind the buttons) is `$genex-ai-menu`; an art-directed HUD
-built from a generated sprite set is `$genex-ai-hud`. Both slot into this
-exact `#ui` + `data-phase` architecture and consume the shared style brief.
+The generated layer is the default, not a reward: every game's HUD is built
+from a generated sprite set (`$genex-ai-hud`), and a cinematic menu (looping
+video backdrop behind the buttons, `$genex-ai-menu`) backs every game whose
+menu decision is yes. Both slot into this exact `#ui` + `data-phase`
+architecture and consume the shared style brief.
 
 ## Failure modes to catch before the player does
 
 - No UI plan: screens invented one at a time, menu and HUD styled in two
   different worlds.
+- 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.
+- A style brief whose fonts were never actually loaded (a system-stack display
+  font at runtime).
+- A micro-element (reticle, cue, toast, damage number) left as default CSS
+  while the panels got the art treatment.
 - A generic stat dashboard (rows of labels + numbers) instead of a designed
   HUD — pick the 2–3 numbers that matter and style them by hierarchy.
 - Hard-cut phase swaps, a menu whose elements just appear, numbers that

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

@@ -58,17 +58,24 @@ leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 (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.
+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.
 
 **The look is planned up front too:** right after the UI gate, lock the visual
 direction in the same plan block — the camera rig + pointer bucket
 (`$genex-threejs-camera-direction`), the renderer baseline (tone mapping,
 exposure, output color space — set deliberately at boot; stock three.js
 defaults are not a look, `$genex-threejs-exposure-color-grading`), the post
-stack this game ships and deliberately skips (bloom/AO/grade — justified by
-the shared style brief; `$genex-threejs-image-pipeline` owns ordering when 2+
-compose), and the lighting/atmosphere mood from that same brief. Planning is
-not building — effects still land last in the execution order.
+stack this game ships (bloom/AO/grade — at least ONE built render-pass effect
+for EVERY game, justified by the shared style brief; the UI vignette div or a
+CSS filter on the canvas does not count, and a plan that "deliberately skips
+everything" is the stock default, not a look; `$genex-threejs-image-pipeline`
+owns ordering when 2+ compose), one named **ambient-motion loop** that keeps
+the scene alive at rest (emissive pulse, shimmer, drifting dust — shader
+work, zero generations), and the lighting/atmosphere mood from that
+same brief. Planning is not building — effects still land last in the
+execution order.
 
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
@@ -141,7 +148,15 @@ concept-driven — a richer first build beats a grey-box one.
 - Use `$genex-threejs-visual-validation` before declaring graphics/procedural-system
   work done. **Game fast path:** for game tasks that loaded no procedural/visual-system
   skill, done = a screenshot plus an interaction smoke check (load the page, press each
-  control, see the visible response) — don't run the full diagnostic gate.
+  control, see the visible response) — don't run the full diagnostic gate — PLUS the
+  floors from the routing-map's acceptance gate: the generated sprite HUD wired in
+  (not the CSS placeholder), pause on Escape, the branded loader with its key-art
+  background, the brief's fonts actually loaded, the renderer baseline + at least one
+  built render-pass effect, every placed 2D/media piece screenshot-verified in
+  situ, no UI element left as default browser CSS, and no placeholder primitive
+  left where a generated asset was planned. These floors gate `npx genex publish`
+  and the final handoff of a session the
+  same way — they do not wait for the word "done" to be said.
 - Entering an **existing or remixed project**: read before writing — learn the
   current renderer choice, physics setup, and file conventions first, then
   extend them. Don't rebuild working systems or switch renderers mid-project.

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

@@ -21,9 +21,17 @@ Three.js release or branch, and do not blindly copy demo architecture.
    mandatory for every game (`initEmbed(...)` + the `waitForPlayer()` gate) —
    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. Enqueue any 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.
+   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** —
+   the single image of the finished game's look that every later `--edit`-able
+   generation anchors to. 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
+   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
    the same plan block, before any rendering code:
    - **camera**: the rig type and the pointer bucket
@@ -32,9 +40,23 @@ Three.js release or branch, and do not blindly copy demo architecture.
      deliberately at boot (`$genex-threejs-exposure-color-grading` owns the
      staging — stock three.js defaults are not a look);
    - **the post stack**: which image effects THIS game ships (bloom? AO?
-     grade?) and which it deliberately doesn't — each named and justified by
-     the shared style brief; when 2+ effects compose,
-     `$genex-threejs-image-pipeline` owns the pass ordering;
+     grade?) — each named and justified by the shared style brief. The floor
+     for EVERY game is the deliberate renderer baseline PLUS at least one
+     scene-serving render-pass effect (bloom, AO, or a LUT/shader grade — the
+     UI vignette div or a CSS filter on the canvas does not count); "no post
+     at all" is the stock default, not a plan, and "it's only a draft" is not
+     a lower floor. When 2+ effects compose, `$genex-threejs-image-pipeline`
+     owns the pass ordering;
+   - **references**: name 2–3 AAA games whose look this game borrows
+     (conventions, lighting mood, palette, post — never trade dress); the
+     same 2–3 the UI gate named, extended from the interface to the scene,
+     and embodied in the gate's concept frame — the image the scene is
+     judged against;
+   - **ambient motion**: name ONE subtle environmental motion loop that keeps
+     the scene alive at rest — an emissive pulse along edges, heat shimmer,
+     drifting dust, a slowly flowing texture. Shader/procedural, zero
+     generations, built with the scene — a world that is perfectly still
+     reads as a screenshot, not a place;
    - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
      wrote — one art direction across scene and UI.
    Planning is not building: effects still land LAST (steps 10–11); this step
@@ -48,6 +70,19 @@ Three.js release or branch, and do not blindly copy demo architecture.
    architecture, planets, water, precipitation, clouds, or VFX. Show the
    planned loader from the very first asset load — a player must never stare
    at a black screen; the rest of the UI states come at step 12.
+   Then make the world-dressing DECISION — a judgment call, not a quota:
+   does THIS world's fiction support 2D art (posters, signs, graffiti,
+   decals, banners, in-world screens — `$genex-ai-image`; `$genex-ai-video`
+   for anything that should move)? Say the decision in one line in the
+   visual-direction block. Name only the pieces that genuinely belong — a
+   garage wants grease posters and warning decals; a pristine void wants
+   none — and anchor their prompts to the concept frame. **Zero is a valid
+   answer with a stated reason; art placed just to satisfy this step is the
+   failure mode, not skipping it.** Enqueue what you named with `--no-wait`
+   alongside the other assets. Every placed piece is
+   screenshot-checked in situ — right scale, not stretched, unlit material
+   where it must glow, readable at gameplay distance
+   (`$genex-threejs-visual-validation` owns the capture discipline).
 7. Add camera direction when framing, controls, transitions, or scale perception
    affect play — or the game aims with the mouse (shooter/FPS/turret): the
    step-4 bucket decision executes here.
@@ -56,12 +91,22 @@ Three.js release or branch, and do not blindly copy demo architecture.
 9. Add shared fields before writing multiple independent noise layers.
 10. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
 11. Add image-pipeline, bloom, exposure, grading, or AO last — building out the
-    step-4 post plan, not inventing one now.
+    step-4 post plan, not inventing one now. This is a completion gate: the
+    named post stack must be BUILT before the game is called done, published,
+    or handed off — a game rendering on stock three.js defaults is not done,
+    and the gate does not wait for the word "done" to be said.
 12. Once the loop is playable, build the planned interface states via
-    `$genex-threejs-game-ui` (HUD, pause, fail/retry, win, and the full loading
-    state grown from the step-6 loader), swap in any landed Tier-2 UI assets,
-    and run a feel pass via `$genex-threejs-game-feel` (input response, camera,
-    impact feedback, retry speed).
+    `$genex-threejs-game-ui` (HUD, pause on Escape, fail/retry, win, and the
+    full loading state grown from the step-6 loader), then `npx genex wait`
+    the step-3 UI generations and wire them in — the sprite HUD replaces the
+    placeholder CSS, the menu video replaces the still frame (wired with the
+    menu skill's loop crossfade), and the scene's planned generated models
+    replace their placeholder primitives — a shipped wave of enemies may not
+    be untextured boxes. This swap is a
+    completion gate, not an option: a game still on the placeholder CSS HUD,
+    or without a working Escape pause, is not done. Then run a feel pass via
+    `$genex-threejs-game-feel` (input response, camera, impact feedback,
+    retry speed).
 13. Validate in a real browser with fixed seeds, captures, interaction checks,
     and performance evidence.
 
@@ -70,7 +115,16 @@ Three.js release or branch, and do not blindly copy demo architecture.
 **Game fast path:** for a game task that loaded no procedural/visual-system skill,
 done = a screenshot plus an interaction smoke check (load the page, press each
 control, assert a visible response — `$genex-threejs-visual-validation` has the
-procedure). The list below applies to routed *visual-system* scenes, and each
+procedure), **plus the UI floor from `$genex-threejs-game-ui` (the generated
+sprite HUD wired in — not the CSS placeholder — pause on Escape, the branded
+loader with its key-art background, the brief's font pair actually loaded)
+and the look floor (the step-4 renderer baseline + named post stack actually
+built; every placed 2D/media piece — decals, posters, in-world screens —
+screenshot-verified in situ; no UI element left as default browser CSS; no
+placeholder primitive left where a generated asset was
+planned)**. These floors gate `npx genex publish` and the
+final handoff of a session the same way — "I never said it was done" is not
+an exemption. The list below applies to routed *visual-system* scenes, and each
 system-specific item (debug views, seed manifests, tier knobs) applies only when
 the corresponding skill was loaded.
 
@@ -89,6 +143,12 @@ A routed Genex scene is incomplete until it exposes:
 
 ## Publish and multiplayer awareness
 
+**Publishing IS calling it done.** Before `npx genex publish`, every completion
+gate above must pass — sprite HUD wired, Escape pause working, branded loader
+with its key art, fonts loaded, renderer baseline + one built post effect,
+world dressing placed or validly waived. If any is still pending, say which
+and publish only after an explicit go-ahead.
+
 Do not invent unavailable Genex service APIs. When preparing a game for Genex
 publishing or multiplayer, inspect the project first. Prefer clean boundaries: