@genex-ai/cli-demo 0.84.0-dev.215 → 0.86.0-dev.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.84.0-dev.215",
+  "version": "0.86.0-dev.217",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/controllers/character/character-animations.ts

@@ -324,6 +324,17 @@ export interface PlayOneShotOptions {
   clamp?: boolean;
   /** Fired when the clip finishes (skipped if a newer one-shot interrupts it). */
   onDone?: () => void;
+  /**
+   * Movement cancels this one-shot. Every one-shot is FULL-BODY (there is no
+   * upper-body layering), so it freezes the legs — a moving character SLIDES
+   * across the ground in a static pose for the clip's whole length (a 2.9s hit
+   * reaction, a 2.7s cast). With `interruptible: true`, grounded movement
+   * intent releases the clip via {@link CharacterAnimations.clearOneShot} and
+   * locomotion takes over immediately. Use it for reactions and gestures a
+   * player can walk out of; leave it off for poses that must hold to their end
+   * (a death/knockdown). Default false.
+   */
+  interruptible?: boolean;
 }
 
 type MutableAnimationStateContext = {
@@ -358,6 +369,9 @@ export class CharacterAnimations {
   // When true, the active one-shot holds its final pose on finish (clamp:true —
   // e.g. Death01) instead of crossfading back to locomotion.
   #oneShotHoldPose = false;
+  // When true, grounded movement intent cancels the active one-shot (see
+  // PlayOneShotOptions.interruptible).
+  #oneShotInterruptible = false;
 
   #state: CharacterAnimationState = "IDLE";
   #prevActionName: string | null;
@@ -398,7 +412,27 @@ export class CharacterAnimations {
     options: CharacterAnimationsOptions = {}
   ) {
     this.#model = model;
-    this.#clipMap = buildClipMap(clips, options.clipMap);
+    // Seed the fuzzy name-matched map from the locomotion profile's own slots
+    // (explicit options.clipMap still wins). Simple boolean snapshots (remote
+    // players, bots) never reach the profile's directional resolver and fall
+    // through to this map — without the seed they bind DIFFERENT clips than the
+    // local player ("Running" vs the profile's run.forward), so the same
+    // movement renders as two different gaits on two screens. Jump states are
+    // deliberately NOT seeded: jump.full would one-shot-clamp as a loop.
+    const slots = options.locomotionProfile?.slots ?? {};
+    const profileSeed: Partial<Record<CharacterAnimationState, string>> = {};
+    const seedPairs: ReadonlyArray<[CharacterAnimationState, string]> = [
+      ["IDLE", "idle.default"],
+      ["WALK", "walk.forward"],
+      ["RUN", "run.forward"],
+      ["CROUCH_IDLE", "crouch.idle"],
+      ["CROUCH_MOVE", "crouch.forward"],
+    ];
+    for (const [state, slot] of seedPairs) {
+      const clip = slots[slot];
+      if (clip) profileSeed[state] = clip;
+    }
+    this.#clipMap = buildClipMap(clips, { ...profileSeed, ...options.clipMap });
     this.#resolver = options.resolver ?? resolveAnimationState;
     this.#onChange = options.onChange;
     this.#locomotionProfile = options.locomotionProfile;
@@ -542,6 +576,13 @@ export class CharacterAnimations {
     // Optional in the snapshot (older five-boolean remote-player objects).
     ctx.crouchActive = snapshot.crouchActive ?? false;
 
+    // Grounded movement cancels an interruptible one-shot — otherwise the
+    // frozen full-body pose slides across the ground for the clip's whole
+    // length. clearOneShot crossfades locomotion back in with no T-pose frame.
+    if (this.#oneShotAction && this.#oneShotInterruptible && ctx.isMoving && ctx.isOnGround) {
+      this.clearOneShot();
+    }
+
     const next = this.#resolver(ctx);
     const stateChanged = next !== this.#state;
     if (stateChanged) this.#state = next;
@@ -550,6 +591,19 @@ export class CharacterAnimations {
     // (Jump_Start/Jump_Land) finishes and unlocks, the pending loop clip must still fade in
     // even though the state did not change again. Internal guards make this a no-op otherwise.
     this.#desiredMotionName = this.#resolveLocomotionClip(snapshot, next) ?? this.#clipMap[next];
+    // Rigs whose airborne slots fall back to the SAME clip as jump.start (every
+    // Meshy rig: jump.rise/jump.fall → jump.full) never re-enter #applyTransition
+    // while airborne — the name never changes — so once the one-shot finishes the
+    // character hangs FROZEN in the jump's final frame for the rest of the fall
+    // (long drops, knockback launches). Once the held action has finished
+    // (paused+clamped), retarget sustained airtime at the idle loop so the limbs
+    // keep animating while descending.
+    if ((next === "JUMP_IDLE" || next === "JUMP_FALL") && this.#desiredMotionName !== null) {
+      const held = this.#actions.get(this.#desiredMotionName);
+      if (held && held.paused) {
+        this.#desiredMotionName = this.#resolveProfileSlot("idle.default") ?? this.#clipMap.IDLE;
+      }
+    }
     // A full-jump profile clip may outlast a very short physics hop. Release
     // its one-shot lock as soon as the controller lands so idle/walk can
     // crossfade immediately instead of waiting for the authored clip to end.
@@ -643,6 +697,7 @@ export class CharacterAnimations {
     // finish and the rig snaps to bind pose for a frame — the T-pose flash.
     action.clampWhenFinished = true;
     this.#oneShotHoldPose = options.clamp ?? false;
+    this.#oneShotInterruptible = options.interruptible ?? false;
     action.timeScale = options.timeScale ?? 1;
     action.reset();
     if (current && current !== action) {
@@ -660,6 +715,42 @@ export class CharacterAnimations {
     return true;
   }
 
+  /**
+   * Cancel a one-shot and hand control back to locomotion NOW. The case that
+   * REQUIRES it: a `clamp:true` one-shot (death/knockdown, a held wind-up)
+   * holds its final frame and keeps the locomotion lock closed FOREVER by
+   * design — so a respawn or an aborted action must explicitly release it, or
+   * the rig keeps the clamped pose while the body moves around. Safe to call
+   * at any time; a no-op when nothing is held.
+   *
+   * Call it on TRANSITIONS (respawn, revive, action aborted) — never per
+   * frame, or it cancels every in-flight reaction clip.
+   *
+   * @example
+   * // on respawn, before teleporting the body:
+   * anims.clearOneShot();
+   */
+  clearOneShot(): void {
+    if (this.#disposed) return;
+    const finished = this.#oneShotAction;
+    this.#oneShotAction = null;
+    this.#oneShotOnDone = undefined;
+    this.#oneShotHoldPose = false;
+    this.#oneShotInterruptible = false;
+    this.#canPlayNext = true;
+    // Crossfade the current state's loop in FROM the held pose — same path the
+    // "finished" handler uses, so there is no unposed/T-pose frame.
+    if (finished) this.#recoverFromOneShot(finished);
+  }
+
+  /** Clip name of the currently-playing (or clamped-held) one-shot, or null.
+   *  Lets a caller cancel a SPECIFIC one-shot (e.g. a held charge wind-up)
+   *  without clobbering whatever replaced it:
+   *  `if (anims.currentOneShotName === WINDUP_CLIP) anims.clearOneShot();` */
+  get currentOneShotName(): string | null {
+    return this.#oneShotAction?.getClip().name ?? null;
+  }
+
   /** Stop all actions, uncache clips, remove the mixer's 'finished' listener. */
   dispose(): void {
     if (this.#disposed) return;
@@ -766,9 +857,23 @@ export class CharacterAnimations {
   #releaseStuckLocks(): void {
     const prevActionName = this.#prevActionName;
     if (prevActionName === null) return;
+    // Match BOTH bindings a jump one-shot can have: the fuzzy clipMap names and
+    // the profile slots. On profile rigs the clipMap entries are usually null
+    // (no clip is literally named "jump_start"), which made this escape hatch
+    // dead code — a stuck jump lock could never self-release. The jump.land
+    // slot is ignored when it falls back to idle.default (same guard
+    // #applyTransition uses), or an idle prevAction would spuriously match.
+    const startName = this.#clipMap.JUMP_START ?? this.#resolveProfileSlot("jump.start");
+    const profileLand = this.#resolveProfileSlot("jump.land");
+    const landName =
+      this.#clipMap.JUMP_LAND ??
+      (profileLand !== this.#resolveProfileSlot("idle.default") ? profileLand : null);
+    // A manual playOneShot() lock is NOT ours to release — even when its clip
+    // happens to share a name with the jump binding (clearOneShot owns that).
+    if (this.#oneShotAction) return;
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_START &&
+      prevActionName === startName &&
       this.#state !== "JUMP_IDLE" &&
       this.#state !== "JUMP_START"
     ) {
@@ -776,7 +881,7 @@ export class CharacterAnimations {
     }
     if (
       !this.#canPlayNext &&
-      prevActionName === this.#clipMap.JUMP_LAND &&
+      prevActionName === landName &&
       this.#state !== "IDLE" &&
       this.#state !== "JUMP_LAND"
     ) {
@@ -878,13 +983,19 @@ export class CharacterAnimations {
     snapshot: CharacterStateSnapshot,
     state: CharacterAnimationState,
   ): void {
-    if (!this.#locomotionProfile || !isAdvancedSnapshot(snapshot) || this.oneShotActive) return;
+    // Gate on a numeric moveSpeed rather than the full advanced snapshot:
+    // remote players and bots drive with simple boolean snapshots plus an
+    // estimated speed (position deltas / their own velocity), and without this
+    // they play locomotion at a flat 1.0 while the local player's clips
+    // speed-match — visibly different gaits for the same movement.
+    const speed = (snapshot as Partial<AdvancedCharacterStateSnapshot>).moveSpeed;
+    if (!this.#locomotionProfile || typeof speed !== "number" || this.oneShotActive) return;
     const band = state === "RUN" ? "run" : state === "CROUCH_MOVE" ? "crouch" : state === "WALK" ? "walk" : null;
     if (!band || !this.#prevActionName) return;
     const nominal = this.#locomotionProfile.nominalSpeed?.[band];
     if (!nominal || nominal <= 0) return;
     const limits = this.#locomotionProfile.playbackRate ?? { min: 0.75, max: 1.35 };
-    const rate = THREE.MathUtils.clamp(snapshot.moveSpeed / nominal, limits.min, limits.max);
+    const rate = THREE.MathUtils.clamp(speed / nominal, limits.min, limits.max);
     this.#actions.get(this.#prevActionName)?.setEffectiveTimeScale(rate);
   }
 }

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

@@ -122,6 +122,15 @@ The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
   their opaque chrome (frame, brackets, ornament); the plate itself is
   rebuilt at runtime in CSS matching the mockup's tint (see the three layers
   above).
+- **No rectangular backing plates behind bars, digits, or icons — in the
+  mockup, in sprites, or in CSS.** The Stage-1 template's widget-construction
+  paragraph forbids them at the source (widgets are shaped silhouettes drawn
+  over the scene — never delete that paragraph), and the runtime never adds
+  one back: ornament lives on the widget's own silhouette. A screen that
+  truly needs a plate (a menu sheet, an inventory panel) shapes it from the
+  art's real interior with `npx genex ui plate` — never a bare rounded
+  rectangle. Measured across 7 genres: without this rule every genre grows
+  heavy generic plates behind its bars and digits.
 - **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
@@ -225,22 +234,29 @@ and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
 
 **Order of work: kick Stage 1 off as your FIRST action at the UI plan
 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). **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
+UI-free concept image before it: this ONE generation (no candidate variants
+unless the player asks) carries scene + HUD, serves as the user's style
+checkpoint, and anchors all later art (`$genex-threejs-game-ui` owns the
+checkpoint choreography). **The moment the mockup lands, enqueue Stage 2 +
+the menu still + the logotype `--no-wait` IMMEDIATELY — THEN show the
+player the frame and ask keep/change as information, never as a gate.**
+Silence = the concept stands; a "change" answer loops the concept with the
+player's notes and the chain re-runs from the new frame — image-priced,
+cheap by design, so say so in one line and do it. Only the menu VIDEO waits
+(`$genex-ai-menu` owns its event triple). 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.
 **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
+`--edit <that-url-or-file>` 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
+Stage 1 is the fallback for when no reference exists. A user-supplied
+reference needs no upload step: `--edit` takes a local file path directly
+(`--edit ./reference.png`, ≤4 MB inlined) — a chat attachment saved to disk
+is a perfectly good anchor, and "I can't feed the local screenshot into the
+art chain" is never true and never a reason to reach for another tool.
+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. When a sprite lands it REPLACES
@@ -250,19 +266,14 @@ 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,
-and a mechanic it failed to show still does. 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. If the
-user's concept-loop feedback rejects the style after Stage 2+ ran,
-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.
+and a mechanic it failed to show still does.
 
 ```bash
 # 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
+# TEXT-described; add `--edit <concept-url-or-local-file>` to anchor it to an
+# existing concept/reference image so the HUD inherits its exact style.
+# ONE concept image; save its URL:
+npx genex image "<filled stage-1 prompt>" --size 2560x1440 --quality high
 
 # Stage 2 — deconstruct the mockup into an asset sheet on white:
 npx genex image "<filled stage-2 prompt>" --edit <mockup-url> --quality high
@@ -319,6 +330,12 @@ To fix ONE sprite, don't re-run the pipeline:
   (the canvas sliced it — regenerate the sheet with more margin around every
   element) or looks like a fragment (extreme aspect / near-empty box — try
   `--dilate` to glue split pieces).
+- **Stacked meters cluster.** Meters that sit adjacent/stacked in the mockup
+  (HP directly over stamina) tend to come back as one clustered crop on the
+  sheet — when your mockup stacks meters, ask the Stage-2 sheet for extra
+  whitespace between the STACKED meter cells specifically (measured on a
+  live run: the tools hard-refuse the resulting neighbor-in-crop defect, so
+  spacing up front saves a sheet re-roll).
 - **gpt-image-2 silently squashes past 3:1** — never request a canvas with
   aspect beyond 3:1. For thin strips (a wide bar frame), generate inside a
   ≤3:1 canvas with margins, then `genex ui trim` down to the art.
@@ -619,10 +636,10 @@ separate concept spend), a couple of minutes each at high quality — budget an
 hour end to end, not five minutes. That fits comfortably inside the image rate
 limit; local `genex ui` steps are free and instant. Two rules keep the clock
 honest: the sprite pipeline runs WHILE you build (kick Stage 1 first, code
-against CSS placeholders, swap sprites in as stages land — never make the
-player-facing v0 wait on it), and candidates beat re-rolls (`--candidates 2`
-on the mockup: choosing between two costs zero extra wall-clock; regenerating
-after a bad single costs the whole chain).
+against CSS placeholders, swap sprites in as stages land), and the chain
+never parks behind the keep/change answer — Stage 2, the menu still, and the
+logotype enqueue the moment the mockup lands (the order-of-work rule above);
+a later "change" loops the concept at image prices.
 
 ## Publish checklist
 
@@ -641,8 +658,9 @@ after a bad single costs the whole chain).
 - `npx genex image` — `--size <WxH>` exact pixels (multiples of 16, each side
   ≤ 3840, aspect at most 3:1); `--quality <low|medium|high>` (high for the
   mockup/sheet, medium for single sprites); `--candidates <2|3|4>` several
-  variants in ONE call (use 2 for the mockup — pick the better, skip the
-  re-roll); `--edit <url>` image-to-image edit of an R2 URL; `--clean <url>`
+  variants in ONE call (only when the player asks for variants — the
+  doctrine is ONE concept); `--edit <url|file>` image-to-image edit of an
+  R2 URL or a local image file (≤4 MB, inlined); `--clean <url>`
   background removal only; `--remove-bg` chains removal after a
   generation/edit; `--bg-mode <sprite|glyph|sheet>` picks the removal model
   (`glyph` for digits/closed shapes; `--clean` defaults to `sheet`; `matte`

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

@@ -1,7 +1,8 @@
 # Stage 1 prompt template — the game concept: full-HUD mockup
 
-Fill the four placeholders, then pass the whole text as the prompt to
-`npx genex image "<filled prompt>" --size 2560x1440 --quality high --candidates 2`.
+Fill the placeholders, then pass the whole text as the prompt to
+`npx genex image "<filled prompt>" --size 2560x1440 --quality high`.
+ONE concept image — no candidate variants unless the player asks for them.
 This image IS the game concept — the user's style checkpoint and the anchor
 for all later art — so the scene half deserves the same care as the HUD half.
 
@@ -26,11 +27,35 @@ Placeholders:
     rival truck closing on the left, late-afternoon glare"
 - `[STYLE_BRIEF]` — your full 3–5 sentence style brief with the named 4–5 hue
   palette. Do NOT append the per-sprite cutout sentence here — this is a full
-  frame, not a cutout.
+  frame, not a cutout. **End the brief with a named register anchor**: "in
+  the register of <2–3 real games>" from the table below. Anchors set the
+  REGISTER (stroke weight, ornament budget, composure) — never copy their
+  assets, and never show their names in-game. Pick 2–3; genres between rows
+  blend the neighbors.
+
+  | Genre register | Anchor games (2–3) |
+  |---|---|
+  | Gothic / soulslike | Bloodborne, Elden Ring |
+  | Clean sci-fi / arena shooter | Destiny 2, Titanfall 2 |
+  | Arcade racing / rally | Forza Horizon, vintage Baja rally decals |
+  | Cozy / farming / life sim | Stardew Valley, Spiritfarer |
+  | Analog survival horror | Resident Evil 7, Signalis |
+  | Retro pixel | Shovel Knight |
+  | Ornate high fantasy RPG | Diablo IV |
+
+- `[N]` — the exact count of elements in `[ELEMENT_LIST]`, spelled out in
+  the ONLY-these line. The bans in that line are load-bearing: without them
+  the model completes the genre's canonical HUD past your list (invented
+  kill feeds, leaderboards, timers, extra slots — measured in 5/7 genres).
 - `[ELEMENT_LIST]` — a bullet list of your 4–7 chosen widgets with one-line
   descriptions. List only asset-backed widgets; pure-geometry elements
   (crosshairs, tick rails, plain shapes) are built in code and stay off the
-  list.
+  list. **Name each element as the shaped object it is** — "bare glowing
+  digits with a pip row", "an etched line silhouette", "stencil digits held
+  by two rivet brackets". Never "panel" or "plate" unless a physical plate
+  IS the art (a diegetic device, a pinned note). **State exact counts**
+  ("exactly one tool slot", "exactly three gem sockets") — the model honors
+  them.
 
 ## The template
 
@@ -39,10 +64,12 @@ A screenshot of a complete game HUD for [GENRE_BRIEF]. The HUD is composited ove
 
 Visual style: [STYLE_BRIEF]
 
-The HUD includes these elements, arranged naturally as a real game would lay them out (you decide the layout — do not force a grid, place each element where it makes the HUD readable and combat-ready):
+The HUD includes ONLY these [N] elements and nothing else — do not add any other UI: no kill feed, no leaderboard, no map, no timer, no chat, no crosshair, no extra slots, no duplicates. Arrange them naturally as a real game would lay them out (you decide the layout — do not force a grid, place each element where it makes the HUD readable and combat-ready):
 
 [ELEMENT_LIST]
 
+Widget construction rules: every widget is a shaped object with its own silhouette — an ornamented frame or emblem drawn directly over the game scene. NO rectangular backing panels behind bars, digits, or icons; no dark filler boxes; the game scene stays visible right up to each widget's frame edge. All ornament and material character lives ON the frame outline itself. Keep the frames detailed and characterful — confident AAA game UI, not a sterile minimal overlay. Size widgets like a shipped game: the HUD hugs the screen edges and no single widget exceeds about one eighth of the frame width. Every meter channel interior reads visibly darker than both its fill and its surrounding frame.
+
 This is a real in-game screenshot. Sharp detail on every UI element. No motion blur on the HUD. The HUD is clear and combat-readable. No watermarks. No external annotations.
 
 CRITICAL — flat HUD framing: draw every HUD element flat and head-on, parallel to the screen plane, like a 2D overlay painted directly onto the display (orthographic / screen-space UI). The HUD must NOT be tilted, angled, skewed, rotated in 3D, shown in perspective, or made to recede into depth — no isometric interface, no vanishing point on the panels, no 3D-extruded or floating-at-an-angle widgets, no curved/wrapped screen. ONLY the game scene behind the HUD may show 3D depth and perspective; the HUD layer itself is a flat 2D plane with square-on, axis-aligned edges, so each widget can be cleanly cut out as a flat sprite.
@@ -53,6 +80,16 @@ not deconstruct cleanly (angled panel edges have no clean silhouette, so
 Stage 2 produces sliced, skewed cutouts). If the mockup comes back tilted,
 regenerate it before proceeding; do not try to salvage it downstream.
 
+**Never delete the widget-construction paragraph either** — it is what keeps
+the mockup from coming back as generic rectangles: without it, every genre
+grows heavy rectangular backing plates behind its bars and digits, and the
+lane's whole value (shaped, characterful chrome) is lost. The channel-contrast
+sentence in it is deliberate phrasing: channels read "visibly darker than
+both their fill and their frame" — a RELATIVE rule that works on light
+palettes too (an absolute "dark" trough fought cozy/pale briefs). Stage 2's
+EMPTY-state law (dark empty tracks on the sheet) is separate and stays
+absolute.
+
 One more Stage-1 rule that pays off at mask time: **meter channels must be
 continuous** — never place a label or ornament in the MIDDLE of a fill
 channel (it splits the mask and the fill into fragments); labels sit above or

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

@@ -25,7 +25,11 @@ Fill `[ASSET_LIST]`, then pass the whole text as the prompt to
 - **requests variant cells for discrete icon counters** — hearts, ammo
   pips, stars ship as repeated sprites, not masks, so their item asks for
   the states as SEPARATE same-size cells ("the heart icon: one full, one
-  half, one empty cell") instead of an annotated pair.
+  half, one empty cell") instead of an annotated pair;
+- **asks for extra whitespace between meters that were STACKED in the
+  mockup** ("place the health-bar cells and the stamina-bar cells in
+  separate rows with generous spacing") — adjacent meters otherwise cluster
+  into one crop and the extraction tools refuse the pair.
 
 ## The template
 

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

@@ -180,11 +180,18 @@ cycle watched AS RENDERED. A metadata probe (ffprobe) can't see a seam, a
 panel covering the video, or a video that never plays — only watching can.
 
 **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
+`--edit`-anchored to the concept mockup, so it's style-dependent: enqueue it
+`--no-wait` **the moment the concept mockup LANDS** — it rides the same
+immediate chain as the HUD Stage-2 sheet and the logotype; the user's
+keep/change answer never gates it (a later "change" just re-edits it against
+the new frame, image-priced). **Only the VIDEO — the expensive item — waits,
+and its trigger is an event, never a clock: fire it at the FIRST of (a) the
+user's yes to the concept, (b) the next `genex preview` push after the still
+has landed (a shipped milestone with the user silent = the pick stands), or
+(c) style art being the only work left. Never fire it while a user objection
+is open** ("change the colors" blocks it until the loop resolves). 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
 `$genex-threejs-game-ui`'s loader spec). Both assets live in Genex storage
 (R2) — permanent, public, CORS-open; you load them straight from the printed

package/templates/skills/genex-game-director/SKILL.md

@@ -10,6 +10,12 @@ tech demo that boots. You are the director; the other Genex skills are your
 specialists. Load only the skills that change the result; never the whole
 pack by default.
 
+**After ANY context compaction or session resume**, re-read the game's
+`AGENTS.md` (the Genex build contract block), `DESIGN.md`, and the skill for
+the stage you are executing — never keep building from memory alone. A
+compaction that eats the conversation does not release you from the
+pipeline; those two files are how it comes back.
+
 ## 1. Check what you can do (once, before planning)
 
 Look at your own tool list and note the answers — the rest of this workflow
@@ -27,6 +33,13 @@ uses them:
 Never claim a capability you didn't find, and never stall because one is
 missing.
 
+One more thing to note while you're looking: your platform may bundle its own
+image / video / site generation workflows. **They are not part of any Genex
+lane.** All generated art, audio, video, characters, and UI come from `genex`
+commands, unless the player explicitly asks for another tool by name — and a
+local reference image is never a reason to switch tools: `genex image --edit`
+and `--inpaint` take a local file path directly.
+
 ## 2. Scope check — what is this?
 
 - **A new game** → the full flow: contract (§3), teams menu (§4), build order
@@ -58,7 +71,10 @@ for the user. Ask only what genuinely forks the build:
 - any real ambiguity in the request itself.
 
 Never ask about SDKs, engines, renderers, file layout, or anything
-technical — those are your decisions. If the player is silent or has no way
+technical — those are your decisions. **The silence fallback applies only
+AFTER the questions have been posted in chat.** A request that already names
+the game does not skip the interview — then it's the confirm-pitch round.
+Asking is never optional; waiting is: if the player is silent or has no way
 to answer, proceed on your own stated assumptions and write each one into
 DESIGN.md → Decisions as "assumed — player didn't answer"; the build never
 stalls on the interview.
@@ -132,7 +148,7 @@ game that needs concrete objects or surfaces, decide a small core set from the
 game IDEA — and from the Content lines when there are any (locations and the
 enemy roster name the set) — and put it in the Assets table up front. This set
 is concept-INDEPENDENT (prompted from the idea, not the concept image, and it
-mostly survives a style change), so it does NOT wait on the concept yes. Each
+mostly survives a style change), so it never waits on the concept at all. Each
 `npx genex` job is an independent ~1-minute render: launch them concurrently
 in the background (`--no-wait`), scaffold the scene while they run, and wire
 each in as it lands, with a procedural placeholder until then:
@@ -164,11 +180,18 @@ The mandatory rows, in order, each with its one "done when" line:
    shows; the tier is what keeps a phone boot alive.
 3. **UI plan gate** — `$genex-threejs-game-ui`, every game: the screen
    inventory, one shared style brief, 2–3 AAA references, the menu archetype,
-   then the concept image with its full HUD already on it. Show the player
-   the picture the moment it lands and ask the keep-or-change question with
-   your question tool. Done when: the player said yes to a frame. The yes
-   gates ONLY style-dependent art — everything else keeps moving while you
-   wait.
+   then ONE concept image with its full HUD already on it (no candidate
+   variants unless the player asks). **The moment it lands: decide the HUD
+   lane (the lane beat below), enqueue the Stage-2 sheet + the menu still +
+   the logotype `--no-wait` IMMEDIATELY, and only THEN show the player the
+   frame and ask keep-or-change with your question tool — as information,
+   never as a gate.** Silence = the concept stands; a "change" answer loops
+   the concept with the player's notes and the chain re-runs from the new
+   frame (image-priced — cheap by design). Only the menu VIDEO waits, for
+   the FIRST of: the player's yes · the next `genex preview` after the menu
+   still landed · style work being the only work left — and it never fires
+   while a player objection is open. Done when: the sheet, still, and
+   logotype are enqueued and the frame is in front of the player.
 4. **Content contract when the request names plural content** — quests,
    enemies, bosses, locations, spells, items, or a content genre (an RPG, an
    adventure, an open world, a story game) — `$genex-threejs-game-content`.
@@ -188,10 +211,26 @@ The mandatory rows, in order, each with its one "done when" line:
    declares its `genex.matchmaking` block before preview. Done when: the
    model, start rule, and late-join behavior are stated in DESIGN.md and the
    netcode feel gate ran before handoff.
-7. **Ship the first playable v0 fast and preview it.** The scaffold prompt
-   owns the player-facing milestones and links — don't restate them; obey
-   them. Done when: the player has a draft link within about ten minutes of
-   the build starting.
+7. **Ship the playable v0 and preview it.** The scaffold prompt owns the
+   player-facing milestones and links — don't restate them; obey them. Done
+   when: the v0 loop is genuinely playable and the player has their draft
+   page link.
+
+**The HUD lane — the concept decides it, and DESIGN.md records it.** You
+make this call as the art director the moment the mockup lands: ornate /
+painterly / material widget chrome (carved bone, etched metal, glowing
+runes, brushed gold) → **sprites** — the `$genex-ai-hud` pipeline is
+mandatory. Chrome that is flat geometry + typography, where a CSS rebuild
+would be screenshot-indistinguishable from the mockup → **CSS allowed**,
+styled from the brief. The litmus test: would a screenshot of the CSS
+rebuild pass for the mockup at a glance? Unsure or ambiguous → sprites.
+Record it as one DESIGN.md line — `HUD lane: sprites (…)` or
+`HUD lane: CSS (…, one-line justification)` — the preview preflight checks
+for it. In BOTH lanes: micro-text (damage numbers, timers, ammo digits)
+stays HTML text in the brief's font, and no rectangular backing plates
+behind bars, digits, or icons — ever (a truly needed shaped plate comes
+from `npx genex ui plate`). Only the player may decline the generated HUD,
+and the player's explicit lane request wins in both directions.
 
 Two rules for every game that moves (decide both before building, state them
 in DESIGN.md):
@@ -227,10 +266,12 @@ agent: you stay the director.
   rule is anti-collision, never a reason to serialize work.
 - You stay the integrator and the only writer of shared files (boot, main
   loop, netcode). Workers never spawn workers — one level deep, always.
-- Concept-DEPENDENT rows (the HUD chain, style-matched art) wait for the
-  player's yes on the concept; concept-INDEPENDENT rows (world/terrain,
-  content data, enemies, asset wiring) launch immediately. Typing a big game
-  alone, line by line, is how sessions run out before the world exists.
+- Concept-DEPENDENT rows (the HUD chain, style-matched art) launch the
+  moment the concept LANDS — the Stage-2 chain enqueues immediately (§5.3);
+  only the menu video waits for its event triple. Concept-INDEPENDENT rows
+  (world/terrain, content data, enemies, asset wiring) launch immediately
+  either way. Typing a big game alone, line by line, is how sessions run
+  out before the world exists.
 - Give each worker everything by path: the `DESIGN.md` path, its Modules row,
   and the skill files it needs (skills live in this project —
   `.claude/skills/<name>/SKILL.md`, `.codex/skills/…`, or `.cursor/skills/…`,