@genex-ai/cli-demo 0.84.0-dev.215 → 0.85.0-dev.216

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.84.0-dev.215",
+  "version": "0.85.0-dev.216",
   "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/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/…`,

package/templates/skills/genex-game-director/references/design-contract.md

@@ -40,8 +40,8 @@ the bottom._
 
 ## Concept
 One paragraph: what the game is, what playing it feels like.
-Concept image: <asset URL> (candidate <n> — my pick, approved by the player
-on <date>)
+Concept image: <asset URL> (standing — shown <date>; player said
+<yes | nothing — pick stands | change → looped>)
 
 ## Core loop
 - **You do:** <primary verb — drive, shoot, build…>
@@ -61,19 +61,35 @@ Every plural noun from the request becomes a countable line:
 ## Screens & UI
 Screens: <loader, menu, HUD, pause, win/lose…> · Style brief: <one line>
 References: <2–3 named games> · Menu archetype: <name>
+HUD lane: <sprites (…) | CSS (…, one-line justification)> — mandatory line;
+the concept decides it (director §5) and the preview preflight checks for it
+Menu video: <yes (the default for every game) | declined (player's reason)>
 
 ## Assets — the generation plan AND the budget
 | Asset            | Kind        | Status                          | Wired? |
 |------------------|-------------|---------------------------------|--------|
-| Concept + HUD    | image       | landed → <URL> (candidate <n>)  | n/a    |
+| Concept + HUD    | image       | landed → <URL>                  | n/a    |
 | <main surface>   | texture     | generating (<id>)               | —      |
 | <hero model>     | model       | planned                         | —      |
 | Background music | music       | planned (one ~90s looping track)| —      |
-| Menu still+video | image+video | blocked on concept yes → queued | —      |
+| Menu still       | image       | enqueued on concept landing (<id>) | —   |
+| Menu video       | video       | waits: yes / next preview after still / style-only-left | — |
+| Logotype         | image       | enqueued on concept landing (<id>) | —   |
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
 (Optionally note the prompt gist per row — it makes style-change re-rolls one
 command.)
 
+**HUD pipeline state (sprites lane) — keep this current; it is how the
+pipeline survives a context compaction.** One row per stage with its
+generation id / output path, so a resumed session knows exactly where the
+chain stopped and what fires next:
+- Stage-1 mockup: <id → URL>
+- Stage-2 sheet: <id → URL>
+- Cleaned sheet: <id → URL>
+- Extracted sprites: <public/assets/hud/…>
+- Masks: <public/assets/hud/…-mask.png + sidecars>
+- Next stage: <what fires next, one line>
+
 ## World & scale
 <Size in numbers if open world; arena bounds otherwise. Streamed terrain? y/n>
 
@@ -89,7 +105,7 @@ click (when a Play screen exists).
 | World/terrain | src/world/** | sub-agent when available | walkable, matches World & scale |
 | Quests & dialogue data | src/content/** | sub-agent when available | counts match Content lines |
 | Enemies/AI | src/enemies/** | sub-agent when available | roster matches Content |
-| HUD chain (style-dependent) | src/ui/** | sub-agent AFTER concept yes | all screens from Screens & UI |
+| HUD chain (style-dependent) | src/ui/** | sub-agent on concept landing | all screens from Screens & UI |
 
 ## Decisions & changes
 - <date> — <one-liner per decision, including anything the player said no or
@@ -106,7 +122,7 @@ A scrap-robot arena shooter: you skate a magnetized junkyard bot around a
 crusher pit, blasting rival bots into spare parts before the magnet cycle
 pulls everything in. Fast, crunchy, thirty-second lives.
 Concept image: https://assets.genex.technology/g/rustyard/concept.png
-(candidate 2 — approved 2026-07-20)
+(standing — shown 2026-07-20; player said yes)
 
 ## Core loop
 - **You do:** skate + shoot
@@ -121,17 +137,26 @@ Concept image: https://assets.genex.technology/g/rustyard/concept.png
 Screens: loader, title menu, HUD (health, scrap, cycle timer), pause,
 win/lose. Style brief: oily metal, warning-stripe accents, stencil type.
 References: <three named AAA games>. Menu archetype: hangar pan.
+HUD lane: sprites (stencil-cut metal meters + riveted scrap counter — ornate
+material chrome, CSS can't pass for it)
+Menu video: yes
 
 ## Assets
 | Asset            | Kind    | Status                     | Wired? |
 |------------------|---------|----------------------------|--------|
-| Concept + HUD    | image   | landed → <URL> (cand. 2)   | n/a    |
+| Concept + HUD    | image   | landed → <URL>             | n/a    |
 | Junkyard ground  | texture | landed → <URL>             | yes    |
 | Player bot       | model   | generating (gen_8f2k)      | —      |
 | Rival bot        | model   | planned                    | —      |
 | Overcast sky     | skybox  | landed → <URL>             | yes    |
 | Blaster zap      | sfx     | landed → <URL>             | yes    |
-| Menu still+video | image+video | blocked on concept yes | —      |
+| Menu still       | image   | landed → <URL>             | —      |
+| Menu video       | video   | waiting (still landed — fires at yes / next preview / style-only-left) | — |
+| Logotype         | image   | generating (gen_9t3m)      | —      |
+
+HUD pipeline state: Stage-1 mockup gen_7a1x → URL · Stage-2 sheet gen_7b2y →
+URL · cleaned gen_7c3z → URL · extracted public/assets/hud/ · masks derived ·
+next: wire masked fills
 
 ## World & scale
 One 60×60 m arena, walled; no streaming.

package/templates/skills/genex-game-director/references/routing-map.md

@@ -88,24 +88,28 @@ Three.js release or branch, and do not blindly copy demo architecture.
    decided silently. FIRST of all art, generate the gate's **concept mockup** —
    a playable-moment shot (verb + threat + objective in frame, per the
    game-ui gate) WITH the full HUD composited over it: the `$genex-ai-hud`
-   Stage-1 image, one generation serving as concept, style checkpoint, and
-   HUD blueprint (never a separate UI-free concept first). Show it to the user
-   the moment it lands and get a keep-or-change answer through your question
-   tool (a short numbered list in chat when you have none). This answer
-   GATES — but only the style-dependent pipeline: until the user approves a
-   frame, do NOT enqueue the Tier-2 art that builds on the look (the
-   `$genex-ai-hud` Stage-2 chain, and the `$genex-ai-menu` still + video
-   whenever the menu decision is yes — the default for every game, "it's only
-   a draft" is not a reason to decide no — plus the logotype). The instant
-   they say yes, fire those with `--no-wait` (pick them up with
-   `npx genex wait <id>`); the game-ui skill owns the re-anchor loop when notes
-   arrive, and later `--edit`-able generations anchor to the approved frame for
-   STYLE while the game contract owns content. Everything that does NOT depend
-   on the look — scaffold, boot wiring, the core loop, and the
-   concept-independent worker lanes (the director's Delegate section) —
-   keeps building in parallel while the answer is pending, so the wait is
-   never idle. Skipping this enqueue is the #1 way a finished game ships an
-   ugly HUD — by step 12 there is nothing to swap in.
+   Stage-1 image, ONE generation serving as concept, style checkpoint, and
+   HUD blueprint (never a separate UI-free concept first, and no candidate
+   variants unless the player asks for them). **The moment it lands, the
+   cheap style chain fires — nothing waits for the player here**: decide the
+   HUD lane as art director and record the `HUD lane:` line in DESIGN.md
+   (director §5), then enqueue with `--no-wait` the `$genex-ai-hud` Stage-2
+   sheet, the `$genex-ai-menu` still (the menu is the default for every
+   game — "it's only a draft" is not a reason to decide no), and the
+   logotype. THEN show the player the frame and ask keep-or-change through
+   your question tool (a short numbered list in chat when you have none) —
+   the answer is INFORMATION, never a gate: silence means the concept
+   stands; "change" loops the concept with their notes and the chain re-runs
+   from the new frame (image-priced — cheap by design; the game-ui skill
+   owns the re-anchor loop). 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 never while a player objection
+   is open (two failed videos → ship the still). Later `--edit`-able
+   generations anchor to the standing frame for STYLE while the game
+   contract owns content. Everything concept-independent — scaffold, boot
+   wiring, the core loop, the worker lanes — keeps building in parallel.
+   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
@@ -250,12 +254,15 @@ Three.js release or branch, and do not blindly copy demo architecture.
     `$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
+    placeholder CSS (or the recorded `HUD lane: CSS` build lands finished to
+    its brief), the menu video replaces the still frame (wired with the menu
+    skill's loop crossfade), the logotype lands on the menu and loader, 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 (with no recorded CSS lane), without the menu video
+    playing (or its recorded still fallback), 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,
@@ -264,8 +271,9 @@ Three.js release or branch, and do not blindly copy demo architecture.
 ## Delegation
 
 Fan-out is owned by the director: sub-agents own DESIGN.md Modules rows,
-concept-DEPENDENT lanes wait for the player's yes on the concept, one writer
-per file, workers never spawn workers, and the Assets table is the budget —
+concept-DEPENDENT lanes launch the moment the concept lands (only the menu
+video waits for its event triple — step 3), one writer per file, workers
+never spawn workers, and the Assets table is the budget —
 the full rules and the worker prompt shape live in the Delegate section of
 `$genex-game-director`. This map adds no separate delegation rules; it is the
 routing source the director and its workers read.
@@ -285,7 +293,9 @@ routing source the director and its workers read.
 done = a screenshot plus an interaction smoke check (load the page, press each
 control, assert a visible response in its labeled direction — `$genex-threejs-visual-validation` has the
 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
+sprite HUD wired in — not the CSS placeholder — or the DESIGN.md-recorded
+`HUD lane: CSS` build finished to its brief; the menu video playing, or its
+recorded still fallback; the logotype placed; 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 —
@@ -323,7 +333,9 @@ 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
+gate above must pass — sprite HUD wired (or the recorded CSS lane finished),
+the menu video playing (or its recorded still fallback), the logotype placed,
+Escape pause working, branded loader
 with its key art, fonts loaded, renderer baseline + one built post effect
 (tier-aware), the adaptive-quality tier wired at boot, world dressing placed
 or validly waived, and the content contract's countables present or

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

@@ -339,6 +339,25 @@ exempt — the local player may be invisible to themselves
 - Load `$genex-threejs-multiplayer` before writing any networking code; it is
   mandatory for any 2+ player game.
 
+## Placing rigs outside the controller — facing is explicit
+
+The vendored controller owns the local player's facing. Any rig you place
+YOURSELF — a duel opponent, an NPC, a fighter in a side-view game — obeys
+three hard rules:
+
+- **Meshy / Mixamo / VRM rigs rest facing +Z** — from a side camera that
+  means straight at the lens. Set the yaw explicitly from the character's
+  ROLE the moment you place it (`model.rotation.y = …`); never leave the
+  rest pose and assume it reads right.
+- **Never mirror a SkinnedMesh with negative scale.** `scale.x = -1` is a
+  2D-sprite trick: on a 3D rig it flips triangle winding and normals
+  (broken lighting and culling) and does NOT turn the character. Turning is
+  always a yaw rotation.
+- **Duel / side-view / two-character scenes: the combatants face EACH
+  OTHER along the duel axis.** Two fighters staring into the camera is a
+  bug, not a pose — verify it in the milestone smoke capture (an enemy in
+  frame facing the player's CHARACTER, never the lens).
+
 ## If the user asks for ecctrl
 
 ecctrl is a React / React Three Fiber component; a Genex game is plain

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

@@ -140,6 +140,14 @@ front of it once — it must face you. This is part of the milestone smoke
 pass once enemies exist (an enemy in frame, facing the player). Set the
 `yawCorrection` constant per model and move on.
 
+Two hard rules alongside it: **never mirror a rig with negative scale** —
+`scale.x = -1` is a 2D-sprite trick that flips winding and normals on a
+SkinnedMesh and does NOT turn a 3D body; turning is always a yaw
+(`rotation.y`), set explicitly from the creature's role. And in any
+**duel / side-view / two-character scene**, the combatants face EACH OTHER
+along the duel axis — a fighter staring into the camera is a bug, not a
+pose, and the smoke capture is where it gets caught.
+
 ### 3. Hit reaction — damage reads on the body
 
 Rigged: the `hit` clip above. Procedural: a 100–150 ms flinch — scale pulse