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

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

@@ -31,7 +31,7 @@ ring) that no hand-written CSS can fake.
 ## Three layers — plates are DOM, chrome is sprites, data is DOM
 
 - **Plate (DOM).** The backing surface behind a widget is built in CSS — in
-  whatever register the brief and concept frame call for: smoked glass
+  whatever register the brief and concept mockup call for: smoked glass
   (`background: rgba(<darkest hue>, 0.35–0.6)` + `backdrop-filter: blur(6–12px)`
   and its `-webkit-` twin) when the style wants translucency, a solid painted
   plate, a subtle gradient — or no plate at all for an outline-led look.
@@ -62,6 +62,32 @@ ring) that no hand-written CSS can fake.
   identity-bearing reticle (engraved ring, sculpted brackets) is chrome —
   put it on the sheet like any other asset.
 
+### Sprite vs CSS — two decision rules
+
+- **Rule A — container vs content (the FUSED-unit test).** When a widget's
+  frame and its interior detail are one crafted unit — an engraved border
+  flowing into an engraved interior, a medallion whose emblem grows out of
+  its ring — separating them and reassembling in CSS coordinates is fragile:
+  keep them FUSED in one sprite and treat the whole thing as chrome. When
+  the interior is runtime territory (a fill channel, a number, map blips),
+  the container is the sprite and the content is DOM — the default split.
+- **Rule B — image vs code (the 5-minute test).** If CSS can build the
+  element in under ~5 minutes without losing fidelity — flat plates, simple
+  dots/pips, plain strokes, a chamfered corner — it is CSS. If it needs
+  craft (material, ornament, painterly texture), it is a sprite. One
+  exception cuts the other way: a static label engraved/embossed into a
+  frame's craft stays BAKED in the sprite (`baked_static` below) even
+  though DOM text is "code".
+- **CSS-chrome recipes — the middle ground.** Between bare CSS and the full
+  sprite pipeline sits brief-styled CSS chrome, right for utilitarian panels
+  and secondary screens: a two-hue gradient frame (border + inset
+  box-shadow in brief hues), a clip-path chamfer (execution bar per
+  `$genex-threejs-game-ui`'s corner rules), a 9-slice-ish panel from nested
+  divs (outer div = border hue, inset div = plate hue, 2–3px reveal). What
+  makes these legitimate: **CSS elements are styled FROM THE BRIEF — hue,
+  weight, texture. Default-gray CSS anywhere on screen is a defect** (the
+  classic failure: score pips shipped as unstyled "○ ●" system glyphs).
+
 ## Framing rules — internalize before prompting
 
 The HUD overlays a **live 3D scene**. The pixels between widgets show the game.
@@ -118,7 +144,32 @@ buckets. The Stage-2 prompt KEEPS or REMOVES accordingly:
 
 The test: "is this fixed identity artwork, or should runtime code own it?"
 Baking a runtime value into a sprite is a failure; stripping a carved identity
-label flattens the art.
+label flattens the art. **One label per widget:** whoever the table says owns
+a word, owns it alone — if a sprite ships with a `baked_static` label, the
+DOM must never render the same word again on that widget (the double-label
+failure). The classification survives to wiring: carry it into the code
+comments, not just this analysis.
+
+### Placing runtime text on frame sprites — measured, never eyeballed
+
+- **Position from `innerBBox`.** The trim/extract sidecars (`.bbox.json`)
+  carry `innerBBox` — the frame's central transparent cavity. Box the DOM
+  text to `innerBBox` scaled to the widget's on-screen size; never hand-tune
+  magic paddings until it "looks right" (they break on the first resize or
+  art swap). If `innerBBox` is null on a genuine frame (no cavity), fall
+  back to the frame's visual center and say so in the wiring notes — solid
+  plates without a cavity are DOM plates anyway (three layers).
+- **Occupancy bands.** Value text fills 65–85% of its zone's height; labels
+  55–75%. Below the band the text rattles inside the frame; above it, it
+  crowds the art.
+- **Width buffers for display fonts.** Display faces run wide: budget +25%
+  width over a naive estimate, +40% for heavy weights in uppercase, +50% for
+  heavy + uppercase + serif — then verify `scrollWidth <= clientWidth` at
+  the widest real value (the 888,888 test).
+- **`genex ui text-color` is a MANDATORY step for every widget that carries
+  DOM text** — sample the mockup region and use the returned hex verbatim.
+  Free-picking a "close enough" palette color is how text drifts off the
+  art's actual plate.
 
 ## Icons & mechanics must match the game — diff before Stage 2
 
@@ -135,8 +186,10 @@ are committing to build):
   grenade slot on a rifle-only HUD, an armor bar with no armor, a minimap over
   no map — is a failure, and "the model drew it so I kept it" is how it happens.
 
-The mockup (and any concept frame) anchors STYLE; the game contract owns WHAT
-EXISTS. When the picture and the mechanics disagree, the mechanics win.
+The mockup — which IS the game concept — anchors STYLE; the game contract owns
+WHAT EXISTS. When the picture and the mechanics disagree, the mechanics win.
+Cut widgets are recorded in the UI plan message as "deferred from mockup"
+(`$genex-threejs-game-ui`) — never silently wired, never silently dropped.
 
 ## The pipeline
 
@@ -146,24 +199,30 @@ printed. Fill the two prompt templates —
 and [references/stage2-prompt-template.md](references/stage2-prompt-template.md)
 — before Stages 1 and 2.
 
-**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. 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. The concept is a STYLE anchor only: the widget set and
+**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). The scene half
+of the prompt is written in TEXT from the game plan — `[GAME_SCENE]` in the
+Stage-1 template: setting, the moment, what the player is doing, lighting —
+never `--edit`-anchored to a prior image (there is none). Then write the
+widget layout and wiring code (placement, masked-fill scaffolding,
+plain-CSS placeholder bars) while it renders — the CSS HUD keeps
+the game playable until the sprites land. The mockup is a STYLE anchor
+only: the widget set and
 layout come from the element inventory and the game contract — a mechanic
-the concept invented (a lap counter, a stamina orb) does not enter the HUD,
+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 replaces the anchor frame after Stage 1 ran,
-re-run the pipeline from Stage 1 against the new frame — there is no cheaper
-partial path, so budget the full chain and say so in one line.
+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.
 
 ```bash
-# Stage 1 — full-HUD mockup over a placeholder scene (the LAYOUT REFERENCE).
+# Stage 1 — the game CONCEPT: full HUD composited over the game's own scene,
+# described in TEXT (one generation covers concept + layout reference).
 # Two candidates in one call; pick the better, save its URL:
 npx genex image "<filled stage-1 prompt>" --size 2560x1440 --quality high --candidates 2
 
@@ -178,11 +237,15 @@ npx genex image "clean sheet" --clean <sheet-url>
 # Names in READING ORDER: top-to-bottom, then left-to-right within a band:
 npx genex ui extract --in <cleaned-url> --out-dir public/assets/hud --names hp-frame,ammo-frame,minimap-ring,weapon-icon
 
-# Progress masks — for every bar/meter with a generated frame. The Stage-2
-# sheet holds a clean frame cell PLUS a same-size annotated duplicate with the
-# fill zones painted pure green #00ff00; this converts the green into an alpha
-# mask + the fillBox (FB) the DOM fill reads:
-npx genex ui masks --in <cleaned-url> --out-dir public/assets/hud --pairs "hp:cx,cy,w,h:ax,ay,w,h:1"
+# Progress masks — for every CONTINUOUS bar/meter with a generated frame. The
+# Stage-2 sheet holds a clean frame cell PLUS a same-size annotated duplicate
+# with the fill zones painted pure green #00ff00; this converts the green into
+# an alpha mask + the fillBox (FB) the DOM fill reads (+ per-segment fillBoxes
+# in `segments` for one-frame-N-slots meters). --auto finds the cell pairs
+# itself — prefer it; fall back to hand-computed --pairs crop rects only when
+# it reports ambiguity:
+npx genex ui masks --in <cleaned-url> --out-dir public/assets/hud --auto --names hp
+#   explicit fallback: --pairs "hp:cx,cy,w,h:ax,ay,w,h:1"
 #   pairs = name : clean-cell crop (px) : annotated-cell crop (px) : expected green components
 
 # Text colors — sample the mockup instead of free-picking from the palette:
@@ -208,6 +271,24 @@ To fix ONE sprite, don't re-run the pipeline:
   its alpha content and reports its real pixel dims — the source of truth for
   the box↔art aspect rule below.
 
+### Crop guards — catch a bad sheet before it ships
+
+- **`extract --expect N`** (N = your `--names` count) asserts the component
+  count and hard-errors BEFORE writing any file, listing what it found. Use
+  it on every extraction — a miscount is otherwise silent and mis-names
+  everything after the gap.
+- Extraction also **warns** when a component touches the sheet canvas edge
+  (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).
+- **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.
+- **Fix-up recrop, never a Stage-2 re-run for one sprite.** One bad crop:
+  re-extract from the cleaned sheet with adjusted `--min-pixels`/`--dilate`,
+  or region-`--edit` the sheet and re-extract. Re-running Stage 2 re-rolls
+  every OTHER sprite too — the most expensive way to fix one.
+
 ## Composition rules (each one is a documented failure class)
 
 - **Continuous fills = masked reveal.** HP, mana, fuel, XP, stamina, charge —
@@ -236,6 +317,43 @@ To fix ONE sprite, don't re-run the pipeline:
   in a comment (`/* no plate — reads against <reason> */`). Bare digits look
   fine over the dev background and vanish over a bright scene.
 
+## Discrete vs continuous — classify every meter before Stage 2
+
+**The rule: does the quantity change in whole units the player counts?**
+Hearts, lives, ammo bullets, stars, mana pips, wave markers → DISCRETE.
+HP %, fuel, XP, stamina, charge → CONTINUOUS. The two ship through different
+recipes, and classifying late means re-doing the sheet:
+
+- **Discrete = repeated sprites, NEVER a masked fill.** A masked reveal
+  swept across a row of icons slices an icon mid-body at most values — the
+  classic badly-masked hearts. Ship one `<img>` per unit
+  (`Array.from({ length: count })`), with partial states as sprite VARIANTS —
+  full/half/empty cells requested on the Stage-2 sheet as separate same-size
+  cells. Stacking (empty cell under a lit cell, dimmed vs lit) beats swapping
+  when the art allows it.
+  - **Overflow pre-flight** before placing:
+    `max_count × item_w + (max_count − 1) × gap ≤ widget_w` — at MAX count,
+    not the current one.
+  - **Anchor rule:** align the row to ONE end (start or end, matching the
+    widget's screen anchor); never center a count that changes — it reflows.
+  - Simple-shape counters CSS renders crisper than any sprite (plain
+    dots/pips) stay CSS by Rule B — but styled from the brief: hue, stroke,
+    glow, state change. Unstyled system glyphs are the defect.
+- **Continuous = the masked-fill pattern below.** Frame sprite + green-key
+  mask + fillBox-relative clip. Never a `*-fill.png`, never a naive width%.
+- **Segmented continuous meters** (ONE frame, N visible slots, fractional
+  value — a posture/heat bar with slot dividers): use the `segments` array
+  the masks JSON writes next to `fillBox` (per-slot fillBoxes, sorted
+  left-to-right). Fill `Math.floor(v)` segments fully (each clipped to 100%
+  of its own fillBox), clip segment `Math.floor(v) + 1` fractionally INSIDE
+  its own fillBox, leave the rest empty. Never sweep one clip across all
+  slots — the union `fillBox` is for single-channel fills only.
+- **Never bake a label mid-channel.** A label or ornament painted in the
+  MIDDLE of a fill channel splits the mask into fragments and the fill into
+  pieces. Labels sit above/beside the channel or on the frame's end caps —
+  it's a Stage-2 prompt rule; if a sheet comes back violating it, region-edit
+  that cell before running masks.
+
 ## The masked-fill DOM pattern (the crown jewel)
 
 Full annotated version with all direction variants and a worked HP-bar
@@ -369,11 +487,42 @@ Two hard rules:
   `$genex-threejs-visual-validation`'s capture discipline. Judge the pixels,
   not your intent.
 
+## The closing wiring audit — the pipeline's final stage, not optional
+
+The most expensive failure this pipeline has produced in the field is not
+bad art — it is validated assets that never got WIRED: masks sitting on disk
+while the shipped fill was a naive width%, frame sprites stretched into
+boxes of the wrong aspect. Close every HUD build with this audit:
+
+1. **Wired-or-reasoned table.** Every PNG in `public/assets/hud/` is either
+   referenced in code/CSS or has a one-line written reason it was cut. No
+   third state.
+2. **No naive %-fills.** Grep your own code for dynamic width/height percent
+   writes — every continuous fill goes through the masked-fill clip with a
+   real `FB` from the masks JSON.
+3. **Box aspect = sprite aspect** for every placed widget, computed from the
+   trim/extract sidecar dims — not from the mockup, never by eye.
+4. **Every mask referenced.** Each `<name>-mask.png` appears in a CSS
+   `mask-image` (or its widget has a written reason).
+5. **Text placement from `innerBBox`, colors from `genex ui text-color`** —
+   verbatim hex, no free-picked palette colors.
+6. Run **`npx genex ui audit`** (it also runs automatically as a preflight in
+   `genex preview`/`publish`) and clear or explain every finding — its
+   findings are heuristics, so "checked, fine because X" is a valid close.
+
+**The subagent handoff rule.** If stages 2–3 ran in a subagent or an earlier
+session, the wiring agent MUST read the produced `*.annotated-progress.json`
+and `.bbox.json` files from disk before wiring — a prose summary of them
+does not count. fillBox numbers, `segments`, and real sprite dims do not
+survive paraphrase; the canonical version of this failure is a subagent
+reporting "masks validated" while the parent ships width% fills.
+
 ## Cost & latency honesty
 
-A full HUD is **~10 image generations** (mockup + deconstruct + clean + a few
-sprite re-rolls), a couple of minutes each at high quality — budget an hour
-end to end, not five minutes. That fits comfortably inside the image rate
+A full HUD is **~9 image generations** (mockup + deconstruct + clean + a few
+sprite re-rolls — the mockup doubles as the game concept, so there is no
+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
@@ -406,15 +555,22 @@ after a bad single costs the whole chain).
   `--no-wait` enqueue and continue — `npx genex wait <id>` picks the result
   up later (safe to re-run; never creates a new generation).
 - `npx genex ui extract --in <png|url> --out-dir <dir> --names a,b,c` — also
-  writes a `.bbox.json` sidecar per sprite; `--min-pixels <n>` lowers the
+  writes a `.bbox.json` sidecar per sprite (with `innerBBox` for text
+  placement); `--expect <n>` hard-errors on a component miscount before
+  writing anything; `--min-pixels <n>` lowers the
   component threshold when a small sprite is missed.
-- `npx genex ui masks --in <png|url> --out-dir <dir> --pairs "name:cx,cy,w,h:ax,ay,w,h:n"` —
-  emits `<name>-frame.png`, `<name>-mask.png`, an overlay, and the JSON with
-  `fillBox` (`FB`).
+- `npx genex ui masks --in <png|url> --out-dir <dir> --auto [--names a,b]` —
+  detects the clean/annotated cell pairs itself; explicit fallback
+  `--pairs "name:cx,cy,w,h:ax,ay,w,h:n"`. Emits `<name>-frame.png`,
+  `<name>-mask.png`, an overlay, and the JSON with `fillBox` (`FB`) plus
+  per-slot `segments` for segmented meters.
 - `npx genex ui text-color --in <png|url> --box x,y,w,h` — deterministic
   eyedropper: background/plate color + dark/light/chromatic ink candidates.
   Use the returned hex verbatim for the DOM text over that region.
 - `npx genex ui trim --in <png>` — crop to alpha content + report real dims.
+- `npx genex ui audit [--dir public/assets/hud] [--src src]` — the mechanical
+  wiring scan (unreferenced sprites/masks, naive %-fill patterns); warn-only,
+  `--strict` exits 1 on findings.
 
 ## Troubleshooting
 
@@ -443,6 +599,13 @@ after a bad single costs the whole chain).
   duplicate drifted from the clean cell (different scale/position) or the
   green isn't flat `#00ff00`. Region-edit the sheet (`--edit <sheet-url>`)
   asking for a same-size duplicate with flat green fill zones, then re-run.
+- **`masks --auto` reports ambiguity or a missing twin** — it never guesses:
+  fall back to explicit `--pairs` with hand-read crop rects for just that
+  meter (the error lists the candidate cells it saw).
+- **The green mask splits into unexpected components** — a label or ornament
+  is baked mid-channel. Region-edit that cell to move the label onto the
+  frame's end caps (see the mid-channel rule), or treat it as a segmented
+  meter and wire the `segments` array.
 - **Digits or `$`/`%` come back hollow after `--remove-bg`** — closed loops
   read as background to the default cutter. Regenerate with `--bg-mode glyph`.
 - **A widget looks squashed** — the placement box aspect doesn't match the

package/templates/skills/genex-ai-hud/references/masked-fill.md

@@ -55,6 +55,60 @@ liquid rises). For an orb whose empty top would show the scene through the
 glass, add a dark cavity div (a circle at the `FB` box) BEHIND the fill so
 the empty portion reads as deep glass rather than a hole.
 
+## Segmented meters — the `segments` array
+
+A meter whose frame has N visible slots but a CONTINUOUS value (a posture or
+heat bar with dividers) never sweeps ONE clip across all slots — the union
+`FB` would light half a slot's divider at most values. The masks JSON writes
+`segments` next to `fillBox`: per-slot fillBoxes sorted left-to-right, each
+`{ index, fillBox }` in the same 0..1 space. Wire it per slot:
+
+```ts
+// v in [0, N] — e.g. 2.4 = two full slots + 40% of the third.
+function setSegmented(fill: HTMLElement[], segments: { fillBox: FB }[], v: number): void {
+  segments.forEach((seg, i) => {
+    const local = Math.max(0, Math.min(1, v - i));      // this slot's own 0..1
+    const b = seg.fillBox;
+    const cx = (b.x + local * b.w) * 100;
+    // One fill div per slot, all inside the same mask div:
+    fill[i]!.style.clipPath = `polygon(${b.x * 100}% 0%, ${cx}% 0%, ${cx}% 100%, ${b.x * 100}% 100%)`;
+  });
+}
+```
+
+Full slots clip to 100% of their own box, the fractional slot clips inside
+its own box, empty slots clip to zero width. One fill div per slot (same
+gradient, same mask parent) keeps each slot's edge inside its own channel.
+
+## Discrete counters are NOT masked fills
+
+Hearts, lives, ammo pips, stars — anything counted in whole units — never go
+through this pattern at all. A mask swept across a row of hearts slices a
+heart mid-body at most values:
+
+```ts
+// DON'T: one mask + width clip across a row of heart icons.
+// DO: repeated <img> per unit, variants for partial states.
+const hearts = document.getElementById("hud-hearts")!;
+function setHearts(hp: number, max: number): void {   // hp may be 2.5
+  hearts.replaceChildren(
+    ...Array.from({ length: max }, (_, i) => {
+      const img = document.createElement("img");
+      const v = Math.max(0, Math.min(1, hp - i));
+      img.src = v === 1 ? "/assets/hud/heart-full.png"
+        : v >= 0.5 ? "/assets/hud/heart-half.png"
+        : "/assets/hud/heart-empty.png";
+      return img;
+    }),
+  );
+}
+```
+
+The full/half/empty cells come from the Stage-2 sheet as separate same-size
+cells (see the stage-2 template). Pre-flight the row at MAX count:
+`max × item_w + (max − 1) × gap ≤ widget_w`, and anchor the row to one end —
+never center a count that changes.
+
 ## The `data-fill-*` contract
 
 Stamp these on the inner fill div, derived from the SAME variables that

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

@@ -1,15 +1,29 @@
-# Stage 1 prompt template — full-HUD mockup
+# 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`.
+`npx genex image "<filled prompt>" --size 2560x1440 --quality high --candidates 2`.
+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.
 
 Placeholders:
 
 - `[GENRE_BRIEF]` — one-line genre description, anchored in a recognizable
   register ("a dark gothic action RPG", "a sun-bleached rally racing game",
   "a hand-painted storybook platformer").
-- `[GAME_SCENE]` — what's behind the HUD ("a dark medieval cathedral interior
-  with candlelight"). Only the scene may show 3D depth — never the HUD.
+- `[GAME_SCENE]` — what's behind the HUD, written RICH and from the game
+  plan (this is the concept's scene — a thin phrase wastes the checkpoint):
+  the setting, the moment, what the player is doing right now (the verb),
+  what threatens them, what they're chasing, and the lighting. Only the
+  scene may show 3D depth — never the HUD. Examples:
+  - "a rain-slick neon alley mid-chase, the player character vaulting a
+    barrier toward a glowing extraction gate, two drones closing in from
+    behind, magenta signage cutting through blue dusk"
+  - "a torchlit dungeon arena mid-duel, the player's knight raising a
+    shield against a lunging skeletal champion, a health shrine glowing in
+    a far alcove, embers drifting in the dark"
+  - "a sun-bleached desert rally stage mid-drift, the player's buggy
+    kicking up dust through a canyon gate marked with checkpoint flags, a
+    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.
@@ -39,6 +53,13 @@ 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.
 
-The mockup is the **layout reference**: save its URL, compare the finished
-HUD against it, and sample runtime text colors from it with
-`npx genex ui text-color`.
+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
+beside the channel, or on the frame's end caps. If the mockup comes back
+with a mid-channel label, keep it only if you'll wire that meter as
+segmented (`segments` in the masks JSON) — otherwise regenerate.
+
+The mockup is the **game concept AND the layout reference**: save its URL,
+compare the finished HUD against it, and sample runtime text colors from it
+with `npx genex ui text-color`.

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

@@ -19,9 +19,13 @@ Fill `[ASSET_LIST]`, then pass the whole text as the prompt to
   translucent or solid: plates are rebuilt at runtime in CSS (rgba,
   backdrop-filter, or a solid fill — whatever matches the mockup), 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").
+- **requests the annotated duplicate** for every CONTINUOUS bar/meter frame
+  (the template's progress block below covers the mechanics — your item just
+  says "output the clean frame + annotated duplicate pair");
+- **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.
 
 ## The template
 
@@ -34,7 +38,7 @@ Lay these assets on a pure flat white #ffffff background, separated by at least
 
 If an asset is a generated progress/bar/meter frame, output TWO CELLS immediately beside each other:
 1. LEFT CELL — the clean production asset the game will use. Preserve exact style, baked_static labels, frame metal, bevels, dividers, scratches, proportions, and texture. Remove runtime dynamic fill and values. Do not paint technical colors on this clean cell.
-2. RIGHT CELL — an annotated duplicate of the same production asset. It must be the same asset, same scale, same canvas bounds, same position, and same outer shape as the left cell. The only difference: paint runtime-fill zones with pure green key color #00ff00. Green marks only the places where runtime bar/progress fill should appear. Paint the green as a FLAT, UNIFORM, fully-saturated #00ff00 fill — no shading, no gradient, no inner shadow, no vignette, NO DARKENING TOWARD THE EDGES, no lighting, no highlights, no texture; constant color edge-to-edge with a HARD, CRISP boundary against the frame. The green is a chroma-key, not a lit surface — any edge shading makes the extracted alpha mask ragged. For discrete segment meters, paint each segment slot as a separate green shape; do not merge slots into one continuous strip and do not paint half-segments.
+2. RIGHT CELL — an annotated duplicate of the same production asset. It must be the same asset, same scale, same canvas bounds, same position, and same outer shape as the left cell. The only difference: paint runtime-fill zones with pure green key color #00ff00. Green marks only the places where runtime bar/progress fill should appear. Paint the green as a FLAT, UNIFORM, fully-saturated #00ff00 fill — no shading, no gradient, no inner shadow, no vignette, NO DARKENING TOWARD THE EDGES, no lighting, no highlights, no texture; constant color edge-to-edge with a HARD, CRISP boundary against the frame. The green is a chroma-key, not a lit surface — any edge shading makes the extracted alpha mask ragged. For segmented meters, paint each segment slot as a separate green shape; do not merge slots into one continuous strip and do not paint half-segments. Never place a label or ornament in the middle of a fill channel — labels belong above/beside the channel or on the frame's end caps.
 
 Do NOT create a separate black-background mask cell. Do NOT create a standalone simplified silhouette. The right cell is a registration-safe annotation map; local tooling derives the alpha mask from its green pixels and uses the left cell as the frame.
 

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

@@ -38,6 +38,53 @@ might suggest. Two hard rules for the frame prompt:
   menus baked into the image. All of that is DOM on top. If the image model
   draws UI into the frame, the prompt was wrong — rewrite and regenerate.
 
+This dedicated UI-free **menu still is the ONLY valid `--frame` input** for
+the menu video. The game concept is the HUD mockup now (`$genex-ai-hud`
+Stage 1) — it has a HUD baked into it, so feeding it to `genex video
+--frame` ships a menu with a HUD floating in the backdrop: an instant
+defect, not a shortcut. Anchor the still to the mockup with
+`--edit <mockup-url>` so menu and world share one palette and light — then
+animate the STILL.
+
+## Choose the composition — one archetype per game, justified
+
+The single most common menu failure is every game shipping the same
+left-rail layout regardless of genre. Before writing menu markup, pick ONE
+archetype and justify it from the style brief in the UI plan message
+(`$genex-threejs-game-ui`'s gate) — **defaulting to left-rail without a
+reason is the failure mode this section exists to kill:**
+
+- **Left rail** — title upper-left or top, buttons stacked left of center
+  (~38%), vista breathing on the right. Fits: exploration, RPG, anything
+  whose still has a strong right-side subject. (The worked example below
+  implements this one — it is ONE archetype, not the default.)
+- **Centered stack** — logotype dominant top-center, buttons in a tight
+  column directly under it. Fits: title-driven games, arcade, sports,
+  anything with a strong wordmark. Delta: center the title block, buttons
+  `left: 50%; transform: translateX(-50%)`.
+- **Bottom command bar** — buttons in one horizontal row along the bottom
+  edge, title above the fold. Fits: fighting, racing, arcade cabinets.
+  Delta: a flex row pinned to `bottom: 8%`, generous letter-spacing.
+- **Boxed plate buttons** — buttons carry visible plates (brief-styled CSS
+  plates, or sprite chrome from the HUD sheet). Fits: RPG/fantasy,
+  crafted/ornate briefs. Delta: `.menu-btn` gets a background plate,
+  border, and hover lift instead of bare text.
+- **Diegetic corner** — buttons anchored into a calm region OF THE SCENE
+  (a doorway, a dashboard, dead sky). Fits: horror, immersive sims; pairs
+  with a still prompted to leave negative space ("the lower right third is
+  calm open water").
+- **Minimal fullbleed** — the vista is the hero; tiny corner links, no
+  stack at all. Fits: art games, ambient toys. Delta: 2–3 small text links
+  bottom-left, heavy letter-spacing, nothing over the subject.
+
+**Second choice — button treatment,** stated in the same line: bare text
+(cinematic, the example below) / CSS plate (styled FROM the brief —
+gradients, borders, chamfers per the game-ui corner rules; default-gray
+plates are a defect) / sprite chrome (from the HUD sheet or a dedicated
+generation — Tier 2b, when the brief is ornate). The per-genre lean lives
+in the style capsules (`$genex-threejs-game-ui`'s
+references/style-capsules.md) — a lean, not a rule.
+
 ## Single-frame vs two-frame
 
 - **Single-frame (default — use this).** Generate ONE image and pass it as
@@ -65,9 +112,10 @@ might suggest. Two hard rules for the frame prompt:
 
 ```bash
 # 1. The frame — a still of the scene the loop returns to (this example is a
-# painterly meadow; YOUR prompt comes from YOUR game's style brief). When the
-# game-ui gate produced a concept frame, anchor the still to it with
-# --edit <concept-url> so menu and world share one palette and light:
+# painterly meadow; YOUR prompt comes from YOUR game's style brief). Anchor
+# the still to the concept mockup with --edit <mockup-url> so menu and world
+# share one palette and light (the still stays UI-free; the mockup itself is
+# NEVER the video frame — it has a HUD in it):
 npx genex image "windswept alpine meadow at golden hour, wildflowers leaning in the gusts, painterly light, cinematic wide shot. Edge-to-edge cinematic composition. Full-bleed 16:9 frame. No UI elements, no text, no buttons in the frame." --aspect 16:9 --quality high
 # -> https://assets.genex.technology/generations/<id>/image-main
 
@@ -150,8 +198,10 @@ fallback, not a downgrade to apologize for.
 ## Wire it as a phase screen
 
 The menu is one `data-phase` screen in the `$genex-threejs-game-ui`
-architecture (the `#ui` overlay + `setPhase()` state machine). Complete,
-copy-pasteable example:
+architecture (the `#ui` overlay + `setPhase()` state machine). Complete
+worked example — this implements the **left rail** archetype with **bare
+text** buttons; adapt the positions and treatment to YOUR chosen archetype
+(the wiring — stagger, selection, intents — carries to all of them):
 
 ```html
 <div id="ui">
@@ -288,15 +338,23 @@ One display font + one body font per menu. Give text its own contrast against
 the moving video — layered text-shadows or a subtle dark plate (avoid heavy
 text strokes — they read as a browser game, not a title screen).
 
-**Title treatment.** A bare display font is the floor, not the ceiling. Two
-upgrades, in order of effort:
-
-- **Layered CSS (free):** gradient ink via `background-clip: text` +
-  stacked shadows (a tight dark one for contrast, a wide soft one for glow).
-- **A generated logotype (Tier 3 — offer it, don't pre-build):**
-  `npx genex image "the word 'EMBERFALL' as an ornate engraved game logo, <style brief>" --transparent`,
-  cleaned with `--bg-mode glyph` if letter counters get eaten, trimmed with
-  `npx genex ui trim`. Short names (one or two words) come out best.
+**Title treatment — the generated logotype is the DEFAULT, not an upsell.**
+Every game with a menu gets a generated wordmark (Tier 2; skipping it needs
+a one-line stated reason in the UI plan message — "the brief is minimal
+fullbleed and a set wordmark would fight the vista" is a reason; silence is
+not):
+
+- **Logotype (default yes):**
+  `npx genex image "the word 'EMBERFALL' as an ornate engraved game logo, <style brief>" --transparent`
+  — the wordmark alone on a transparent background, in the brief's display
+  register, no extra text or scenery. Clean with `--bg-mode glyph` if letter
+  counters get eaten, trim with `npx genex ui trim`. Short names (one or two
+  words) come out best. Wire it as the menu title AND the loader mark; the
+  DOM keeps an accessible text fallback (`aria-label` or visually-hidden
+  text).
+- **Layered CSS (the fallback while it renders, or the stated-reason
+  skip):** gradient ink via `background-clip: text` + stacked shadows (a
+  tight dark one for contrast, a wide soft one for glow).
 
 ## Tips
 
@@ -308,10 +366,15 @@ upgrades, in order of effort:
   still frame right first (images are cheap to redo), then animate it once.
   The one exception: a user-driven style change (the game-ui concept loop
   re-anchored the look) re-opens this rule once — re-edit the still
-  (`--edit` against the new concept frame) and re-run the video from the new
-  still. Agent-initiated polish never does.
-- **720p is right.** It's a background under UI; higher resolutions cost more,
-  take longer, and change nothing visible.
+  (`--edit` against the new concept mockup) and re-run the video from the
+  new still. Agent-initiated polish never does.
+- **1080p is the default — leave it.** The menu clip is full-screen key art,
+  the first moving thing the player sees, and 720p visibly softens it on any
+  modern display. `genex video` renders 1080p by default; pass
+  `--resolution 720p` only as an explicit cost fallback (about half the
+  credits) when the user asks to economize. The flip side of 1080p: getting
+  the phone rule above wrong now costs twice as much bandwidth — poster on
+  phone tiers, always.
 - **Pause/victory/defeat variants reuse the same video — as GRADES.** Same
   `<video>` element or URL, different emotion via CSS `filter` on the
   background: pause = a plain dark overlay (`rgba(0,0,0,0.55)`); defeat =
@@ -341,6 +404,9 @@ upgrades, in order of effort:
   genuine state change; expect a loop seam.
 - `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
   default 8.
+- `--resolution <720p|1080p>` (video) — default 1080p; `720p` is the
+  explicit cost fallback (~half the credits). Loop clips (`--loop`) ignore
+  it (that model has no resolution parameter).
 - `--aspect 16:9 --quality high` (image) — the right settings for a menu frame.
 - `--no-wait` — enqueue and return immediately with the generation id; pick
   the result up later with `npx genex wait <id>` (safe to re-run — it attaches

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

@@ -65,22 +65,37 @@ side — reads as broken at a glance.
 
 ## Load it into the scene
 
-Use Three.js `GLTFLoader` with the URL the command printed (R2 sends the right
-CORS headers, so cross-origin loading just works):
+Load through the quality kit's decoder-wired loader and the model rung ladder
+(`$genex-threejs-adaptive-quality`; `npx genex controller quality` installs
+it). The bare URL is the provider-raw original — multiple 1–4K PBR textures +
+dense geometry; phones load the `@1024` rung instead (textures budgeted to
+1024, meshopt-compressed, simplified) and KTX2-capable games get the
+GPU-compressed sibling. Desktop always loads the original. R2 sends the right
+CORS headers, so cross-origin loading just works:
 
 ```ts
-import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { createGltfLoader } from "./controllers/quality/gltf-loader.ts";
+import { loadModelWithFallback } from "./controllers/quality/pick-asset.ts";
+import { detectTier } from "./controllers/quality/tier.ts";
 
-const loader = new GLTFLoader();
+const tier = detectTier(); // reuse the boot tier if you already have it
+const gltfLoader = createGltfLoader(renderer); // once at boot — meshopt + KTX2
 // the URL `npx genex model` printed:
 const MODEL_URL = "https://assets.genex.technology/generations/<id>/model-glb";
-const gltf = await loader.loadAsync(MODEL_URL);
+const gltf = await loadModelWithFallback(
+  MODEL_URL, tier, (u) => gltfLoader.loader.loadAsync(u), { ktx2: gltfLoader.ktx2 },
+);
 const model = gltf.scene;
 model.scale.setScalar(1); // tune to taste
 model.position.set(0, 0, 0);
 scene.add(model);
 ```
 
+A missing rung falls back to the original automatically (each fallback warns —
+never silent). Without the quality kit a plain
+`new GLTFLoader().loadAsync(MODEL_URL)` still works, but every device pays for
+the full original — phones included.
+
 Never swallow a failed load silently: if you wrap a generated-asset load in a
 `catch`, `console.warn` the asset name in it — your own self-check reads the
 console, and a bare `.catch(() => null)` hides a missing model from you too.