@genex-ai/cli-demo 0.81.0-dev.214 → 0.85.0-dev.216

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.81.0-dev.214",
+  "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/controllers/character/first-person.ts

@@ -0,0 +1,54 @@
+// First-person body treatment (Revenant pilot D2): hide the LOCAL player's
+// body from its own camera while keeping its shadow on the ground.
+//
+// Why not `visible = false`? That removes the mesh from the shadow pass too —
+// the player loses their own shadow, one of the strongest grounding cues a
+// first-person game has. Instead the meshes keep rendering but write no color
+// and no depth: the shadow-map pass uses its own depth-material override, so
+// the silhouette still lands in the shadow map.
+//
+// Why CLONED materials? VRM/Meshy loaders share materials across instances
+// (the multiplayer clone pool shares one GPU set for every remote) — flipping
+// `colorWrite` on a shared material would erase every REMOTE player's body
+// too. Cloning localizes the change to this one model; restore disposes the
+// clones and puts the originals back.
+import * as THREE from "three";
+
+const savedMaterials = new WeakMap<THREE.Mesh, THREE.Material | THREE.Material[]>();
+
+/**
+ * Hide (or restore) a character model for first-person play. Call with the
+ * LOCAL player's model root after it loads — never with a remote player's
+ * clone. Idempotent in both directions.
+ *
+ * ```ts
+ * followCam.firstPerson = true;         // camera at the eye anchor
+ * setFirstPersonBody(playerModel, true); // body invisible, shadow kept
+ * ```
+ */
+export function setFirstPersonBody(root: THREE.Object3D, hidden: boolean): void {
+  root.traverse((obj) => {
+    const mesh = obj as THREE.Mesh;
+    if (!mesh.isMesh) return;
+    if (hidden) {
+      if (savedMaterials.has(mesh)) return; // already hidden
+      savedMaterials.set(mesh, mesh.material);
+      const clones = (Array.isArray(mesh.material) ? mesh.material : [mesh.material]).map(
+        (material) => {
+          const clone = material.clone();
+          clone.colorWrite = false; // draws nothing…
+          clone.depthWrite = false; // …and never occludes the scene
+          return clone;
+        },
+      );
+      mesh.material = Array.isArray(mesh.material) ? clones : clones[0]!;
+    } else {
+      const original = savedMaterials.get(mesh);
+      if (original === undefined) return; // was never hidden
+      const clones = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      for (const clone of clones) clone.dispose();
+      mesh.material = original;
+      savedMaterials.delete(mesh);
+    }
+  });
+}

package/templates/controllers/character/follow-camera.ts

@@ -81,6 +81,19 @@ export type FollowCameraOptions = {
    * reference).
    */
   pointerLockAim?: boolean;
+  /**
+   * REAL first-person mode (Revenant pilot D2) — not the follow-distance hack.
+   * The camera sits AT the follow target (feed it the character's EYE height,
+   * ~1.6–1.7 m, not the head-top orbit anchor) and looks OUT along the exact
+   * direction the orbit camera would have looked from behind, so the
+   * pointer-lock aim math — and its verified input signs — are shared, not
+   * duplicated. While on: wheel zoom is ignored and collision pullback is
+   * skipped (there is nothing behind the eyes). Toggle at runtime via the
+   * public `firstPerson` field (e.g. enter/exit a vehicle). Hide the local
+   * body with `setFirstPersonBody()` (first-person.ts) — it keeps the shadow.
+   * Default false.
+   */
+  firstPerson?: boolean;
   /** Radians of view rotation per pixel of locked mouse movement. Default 0.0023. Mutable via `aimSensitivity` setter. */
   aimSensitivity?: number;
   /**
@@ -208,6 +221,8 @@ export class FollowCamera {
   smoothTime: number;
   /** Static environment meshes for collision pullback; mutate freely (e.g. after level load). */
   colliderMeshes: THREE.Mesh[];
+  /** First-person mode (see {@link FollowCameraOptions.firstPerson}); toggle freely at runtime. */
+  firstPerson: boolean;
 
   private _camera: THREE.PerspectiveCamera;
   private _domElement: HTMLElement;
@@ -255,6 +270,7 @@ export class FollowCamera {
   // Preallocated scratch (no allocations in the per-frame path).
   private _sdRef: ScalarRef;
   private _sphericalDir: THREE.Vector3;
+  private _fpLook: THREE.Vector3;
   private _camDir: THREE.Vector3;
   private _finalDir: THREE.Vector3;
   private _crossAxis: THREE.Vector3;
@@ -295,6 +311,7 @@ export class FollowCamera {
     this.followEnabled = true;
     this.smoothTime = options.smoothTime ?? 0.1;
     this.colliderMeshes = options.colliderMeshes ?? [];
+    this.firstPerson = options.firstPerson ?? false;
 
     this._draggingSmoothTime = options.draggingSmoothTime ?? 0.125;
     this._upLerpFactor = options.upLerpFactor ?? 0.1;
@@ -339,6 +356,7 @@ export class FollowCamera {
 
     this._sdRef = { value: 0 };
     this._sphericalDir = new THREE.Vector3();
+    this._fpLook = new THREE.Vector3();
     this._camDir = new THREE.Vector3();
     this._finalDir = new THREE.Vector3();
     this._crossAxis = new THREE.Vector3();
@@ -433,6 +451,10 @@ export class FollowCamera {
     this._onWheel = (e: WheelEvent) => {
       if (!this.enabled) return;
       e.preventDefault();
+      // First-person has no zoom — and letting the wheel mutate the hidden
+      // orbit distance would make the NEXT third-person switch snap to a
+      // surprise distance.
+      if (this.firstPerson) return;
       // Upstream wheel normalization (unclamped, proportional): pixel mode divides deltaY by
       // deltaYFactor*10 (-30, or -10 on Mac); line mode (Firefox) or ctrlKey (trackpad pinch
       // gesture) divides by deltaYFactor only. Then multiplicative zoom, dollyScale =
@@ -735,7 +757,7 @@ export class FollowCamera {
     // the DAMPED distance itself is clamped to the hit; `_distanceEnd` (and the velocity) stay
     // untouched, so when the obstruction clears, SmoothDamp eases the camera back out to the
     // user's zoom instead of snapping.
-    if (this.colliderMeshes.length > 0) {
+    if (!this.firstPerson && this.colliderMeshes.length > 0) {
       this._distance = Math.min(this._distance, this._collisionTest());
     }
 
@@ -747,6 +769,18 @@ export class FollowCamera {
       Math.sin(this._polar) * Math.cos(this._azimuth)
     );
 
+    if (this.firstPerson) {
+      // First-person: the camera sits AT the (eye-height) follow target and
+      // looks OUT along the exact direction the orbit camera would have looked
+      // from behind (-dir). Sharing the angle state means the pointer-lock aim
+      // math — and its verified mouse-direction signs — apply unchanged, and a
+      // runtime toggle back to third-person keeps view continuity.
+      this._camera.position.copy(this._target);
+      this._fpLook.copy(this._target).addScaledVector(dir, -1);
+      this._camera.lookAt(this._fpLook);
+      return;
+    }
+
     this._camera.position.copy(this._target).addScaledVector(dir, this._distance);
     this._camera.lookAt(this._target);
   }

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

@@ -1,14 +1,34 @@
 ---
 name: genex-ai-character
-description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use when a game needs a custom playable character or motion not covered by the default VRM + UAL lane.
+description: Generate a controller-ready Meshy humanoid with Genex, search the committed Meshy animation catalog by gameplay intent, add exact same-rig actions, and install the shared physics controller's Meshy-native adapter. Use for the game's themed character — the default whenever the protagonist is visible — or for motion not covered by the VRM + UAL lane.
 ---
 
 # Genex AI Character
 
-Use the existing VRM + UAL character controller by default. Use this lane when
-the game needs a custom generated humanoid or an action unavailable in UAL.
-Both lanes use the same ECCTRL-derived Rapier controller, camera, inputs,
-crossfades, transition rules, and multiplayer authority contract.
+A themed Meshy character is the DEFAULT for any game whose protagonist is
+visible (third-person, or first-person with co-op/remote players); the
+VRM + UAL controller is the instant placeholder while it builds, and the
+final character only for games with no themed protagonist. Both lanes use
+the same ECCTRL-derived Rapier controller, camera, inputs, crossfades,
+transition rules, and multiplayer authority contract.
+
+**Two lanes, two approval shapes:**
+
+- **The game-default lane (one user stop).** The three concept candidates
+  ride the SAME review beat as the game-concept keep-or-change question —
+  one review, two picks. The player's pick authorizes the whole lane
+  (preview and the 10,000-face rigging remesh both proceed on it — state
+  each step plainly as you run it). If the player hasn't picked by the
+  time the character blocks progress (or ~10 minutes), pick the strongest
+  candidate yourself, say which and why in chat, and proceed. That
+  auto-proceed — including its generation spend — is owner-ratified
+  platform policy (2026-07-23), not an agent liberty: record the pick in
+  DESIGN.md → Decisions.
+- **The user-initiated custom-character lane (two stops — the ceremony
+  below, in full).** When the user themselves asked for a custom
+  character, the approvals ARE the product: an explicit candidate
+  selection, then an explicit approval of the separate 10,000-face
+  remesh. Never compress these two stops for a user-initiated ask.
 
 ## Generate a controller-ready character
 

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

@@ -39,25 +39,38 @@ ring) that no hand-written CSS can fake.
   Behind an OPAQUE frame sprite there is no plate — the frame IS the backing
   surface, and a dark div stacked behind it only protrudes as a box over the
   scene (the recurring black-box defect). Where a plate IS needed — bare DOM
-  readouts, thin-outline widgets — it stays WITHIN the widget's silhouette:
-  inset inside the frame, or shaped to it, never a full rectangle spilling
-  past the art onto the scene.
+  readouts, thin-outline widgets — it stays WITHIN the widget's silhouette,
+  and the mechanism is the **silhouette plate**: run
+  `npx genex ui plate --in <frame.png>` (free, local) to trace the frame's
+  REAL interior into a mask PNG, then give the plate div
+  `mask-image: url(<name>-plate.png)` (+ `-webkit-` twin,
+  `mask-size: 100% 100%`) alongside its usual `rgba`/`backdrop-filter`. The
+  plate then fits spiky gothic panels and shaped medallions exactly — a bare
+  rounded rectangle spills past thin frames and can't follow shaped art (the
+  recurring plate-spill defect).
   **Glass is a technique, not a default** — do not reach for translucency
   because this skill mentions it; reach for it when THIS game's brief does.
-  What is fixed is WHERE plates are built — the DOM — because
-  semi-transparency physically cannot survive sprite extraction: a composited
-  panel's pixels are a blend of panel and background, and no cutout can
-  un-blend them. Plates are NEVER baked into sprites. Give the plate its
-  corners with `border-radius` — **never a raw `clip-path`/`mask` chamfer**
+  Plates stay DOM by default because a sprite cut from an UNKNOWN background
+  cannot carry translucency (its pixels are a blend of panel and scene) — but
+  a genuinely glassy identity panel has a second lane now:
+  `npx genex image "<glass panel prompt>" --glass` generates it on a
+  controlled flat-magenta key screen and solves REAL per-pixel translucency
+  into the shipped PNG (`$genex-ai-image` documents the lane; a frosted panel
+  reads as true glass over any scene). Use DOM plates for tint-and-blur
+  backing; use `--glass` when the glass itself is crafted identity art. Give
+  a DOM plate its corners with `border-radius` or shape it with a `ui plate`
+  silhouette mask — **never a raw `clip-path`/`mask` chamfer**
   (it shears off borders, shadows, and content near the cut and re-breaks on
   every padding/value change: the recurring "cut corners" defect). A genuinely
-  ornamented or angular frame belongs in chrome, generated. The one
-  load-bearing `mask`/`clip-path` in this skill is the masked-fill reveal
-  below — never corner shaping.
+  ornamented or angular frame belongs in chrome, generated. The load-bearing
+  `mask`/`clip-path` uses in this skill are the masked-fill reveal below and
+  the `ui plate` silhouette — never corner shaping.
 - **Chrome (sprites — what THIS pipeline generates).** Opaque frames, corner
   brackets, ornaments, emblems, icons, medallions — hard-alpha art laid over
   the glass. The Stage-2 sheet contains ONLY chrome; never a panel with its
-  fill or glass surface baked in.
+  fill or glass surface baked in. One deliberate exception to "no fills":
+  every meter frame ships WITH its EMPTY dark in-style track baked in (the
+  Stage-2 track rule) — the empty state is art; only the moving fill is DOM.
 - **Data (DOM).** Numbers, labels, and bar fills are DOM text and masked
   fills (the fillBox pattern below) — always over the glass, never
   rasterized into art.
@@ -109,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
@@ -212,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
@@ -237,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
@@ -306,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.
@@ -314,13 +344,43 @@ To fix ONE sprite, don't re-run the pipeline:
   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.
 
+## The sheet repair lane — model edits, never pixel hacks
+
+When a sheet defect surfaces AFTER generation — a white-painted trough
+(`ui audit`'s hard `white-trough` finding, or `ui masks`' refusal), a wrong
+ornament, a mis-drawn cell — the fix is a MODEL edit of the sheet, then
+re-clean + re-extract. Never patch shipped pixels by hand (threshold-punching
+a trough chews the frame's bezel — a tried-and-rejected workaround; the one
+allowed pixel surgery is extraction's own known-matte rim defringe):
+
+```bash
+# Whole-sheet repair (all bar cells at once — proven to preserve bezels,
+# ornaments AND the green annotated twins):
+npx genex image "Repaint every meter channel interior as the meter's EMPTY state: a flat dark in-style track. Change nothing else." --edit <sheet-url>
+
+# Region repair (one cell, others must not re-roll): add a mask whose
+# TRANSPARENT hole covers the zone to change — assemble it from the channel
+# mask + the cell's crop rect, or a hand-drawn rectangle:
+npx genex image "<same repaint ask>" --edit <sheet-url> --inpaint <mask.png>
+```
+
+**`--inpaint` honesty — a targeting scope, not a scalpel.** The mask focuses
+WHERE the change happens (proven: the masked cell's trough repainted while the
+other bar's design survived untouched) — but the WHOLE sheet still re-renders
+and any transparency is destroyed either way. So after ANY repair edit,
+mandatory: re-run `--clean` on the result, re-extract, and re-derive masks —
+the old crops/masks describe the pre-edit sheet.
+
 ## Composition rules (each one is a documented failure class)
 
-- **Continuous fills = masked reveal.** HP, mana, fuel, XP, stamina, charge —
-  NEVER generate `*-fill.png` sprites, and NEVER use a naive `width`/`height`
-  percentage of the widget box (it drifts ~12% off the art's real channel:
-  empty at 25%, full by 75%). The frame stays a sprite; the fill is the
-  masked-fill DOM pattern below.
+- **Continuous fills = fill-on-top masked reveal.** HP, mana, fuel, XP,
+  stamina, charge — NEVER generate `*-fill.png` sprites, and NEVER use a
+  naive `width`/`height` percentage of the widget box (it drifts ~12% off the
+  art's real channel: empty at 25%, full by 75%). THE bar recipe: the frame
+  sprite carries its EMPTY dark track baked at source (Stage-2 track rule),
+  and a near-opaque gradient fill paints ON TOP of it, clipped to `FB` inside
+  the channel mask — the masked-fill DOM pattern below. Never a plate/track
+  div stacked behind the frame to fake an empty state.
 - **Minimap/radar interiors are an empty CSS disc** (`border-radius: 50%`,
   dark background). Only the decorative ring frame is a sprite, prompted with
   an explicitly **transparent center — no map, no terrain inside**. Gameplay
@@ -389,12 +449,12 @@ form:
 
 ```html
 <div class="widget" id="hud-hp">          <!-- root: overflow VISIBLE (glows may bleed) -->
-  <div class="hp-mask">                   <!-- outer: the silhouette mask -->
+  <img class="hp-frame" src="/assets/hud/hp-frame.png" alt="">  <!-- frame + baked empty track -->
+  <div class="hp-mask">                   <!-- outer: the silhouette mask, ON TOP of the frame -->
     <div class="hp-fill" data-fill data-fill-mask="hp-mask.png"
          data-fill-box="0.0784,0.3469,0.9216,0.3605"
          data-fill-from="left" data-fill-ratio="0.72"></div>
   </div>
-  <img class="hp-frame" src="/assets/hud/hp-frame.png" alt="">
 </div>
 ```
 
@@ -408,7 +468,7 @@ form:
 .hp-fill { position: absolute; inset: 0;   /* FULL-BOX gradient; the clip places the edge */
            background: linear-gradient(180deg, #ef5b5b, #7a1d18); }
 .hp-frame { position: absolute; inset: 0; width: 100%; height: 100%;
-            object-fit: fill; }            /* frame paints on top */
+            object-fit: fill; }            /* under the fill: its baked track IS empty */
 ```
 
 ```ts
@@ -426,17 +486,19 @@ function setHp(hp: number, maxHp: number): void {
 }
 ```
 
-The structure, in one breath: the OUTER div carries the alpha mask
-(`mask-image` + `mask-size: 100% 100%`, `overflow: hidden`) so the fill can
-only exist inside the art's silhouette; the INNER div is a FULL-BOX gradient
+The structure, in one breath: the frame `<img>` (with its baked EMPTY track)
+paints first with `object-fit: fill`; the OUTER div after it carries the alpha
+mask (`mask-image` + `mask-size: 100% 100%`, `overflow: hidden`) so the fill
+can only exist inside the art's channel; the INNER div is a FULL-BOX gradient
 whose `clip-path` places the leading edge at the **channel-relative** level
 using `FB` — for a left fill the right edge sits at `(FB.x + ratio * FB.w) * 100%`,
 for a bottom fill the top edge at `(FB.y + (1 - ratio) * FB.h) * 100%`. Stamp
 `data-fill`, `data-fill-mask`, `data-fill-box`, `data-fill-from`, and
 `data-fill-ratio` on the inner div — they make every fill auditable against
-the mask JSON. The frame `<img>` sits on top with `object-fit: fill`, and the
-widget root keeps `overflow: visible` so glow effects bleed past the art
-instead of clipping to a hard square.
+the mask JSON. The widget root keeps `overflow: visible` so glow effects bleed
+past the art instead of clipping to a hard square. (Fill UNDER the frame is
+the exception, for genuinely transparent channel cavities with a reason —
+[references/masked-fill.md](references/masked-fill.md) has the rule.)
 
 ## Reactivity — the juice floor
 
@@ -512,7 +574,10 @@ out of budget to check, say the HUD is unverified — never call it done.
   with corrected name order rather than regenerating anything.
 - **Fills grow monotonically** — drive each fill through 0 → 50 → 100 and
   confirm the reveal grows and stays inside the art's channel (never bulging
-  past the frame's track).
+  past the frame's track). A screenshot at full HP proves nothing about a
+  meter — the classic shipped defect (a painted-full trough behind the mask)
+  is invisible at 100%. This is why the milestone smoke pass's gameplay
+  capture is taken AFTER taking damage once.
 - **No text clips** — for every text node, `scrollWidth <= clientWidth`.
   Display fonts run 25–50% wider than a naive estimate; widen the box or drop
   the weight, don't shrink the font.
@@ -571,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
 
@@ -593,13 +658,19 @@ 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`);
+  (`glyph` for digits/closed shapes; `--clean` defaults to `sheet`; `matte`
+  = BiRefNet soft alpha for hair/glow/smoke edges the binary cutters butcher);
   `--no-wait` enqueue and continue — `npx genex wait <id>` picks the result
-  up later (safe to re-run; never creates a new generation).
+  up later (safe to re-run; never creates a new generation);
+  `--inpaint <mask.png|url>` region mask for `--edit` (transparent hole =
+  the zone to change — see the repair lane's honesty note);
+  `--upscale <url>` 2x utility upscale of an existing asset;
+  `--glass` the magenta-key glass lane (`$genex-ai-image`).
 - `npx genex ui extract --in <png|url> --out-dir <dir> --names a,b,c` — also
   writes a `.bbox.json` sidecar per sprite (with `innerBBox` for text
   placement); `--expect <n>` hard-errors on a component miscount before
@@ -614,10 +685,17 @@ after a bad single costs the whole chain).
   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 plate --in <frame.png> [--erode 2]` — trace the frame's real
+  interior (art + enclosed cavity) into `<name>-plate.png`; wire it as the
+  CSS plate's `mask-image` (the silhouette-plate rule above). Free, local.
 - `npx genex ui audit [--dir public/assets/hud] [--src src]` — the mechanical
   wiring scan (unreferenced sprites/masks, naive %-fill patterns, and a
-  missing/incomplete mobile viewport meta in the root `index.html`); warn-only,
-  `--strict` exits 1 on findings.
+  missing/incomplete mobile viewport meta in the root `index.html`); warn-only
+  except the provable kinds (`mask-frame-mismatch`, `white-trough`), which
+  exit 1; `--strict` exits 1 on any findings.
+- Extraction defringes chroma-keyed sprite rims by default (2px matte
+  un-blend against the sheet white — kills the halo over dark scenes; the
+  sidecar stamps `defringed`); `--no-defringe` opts out.
 
 ## Troubleshooting
 
@@ -637,15 +715,49 @@ after a bad single costs the whole chain).
 - **The fill drifts off the art's channel** — a naive `width`/`height` % crept
   in, or `FB` doesn't match the mask. Use the clipPath formula with the
   `fillBox` from the masks JSON, verbatim.
-- **The fill never shows, at any ratio** — the frame PNG's channel interior is
-  opaque track art occluding the fill beneath it. Raise the mask div above the
-  frame (`z-index`); the mask keeps the fill inside the channel, so the rim
-  and baked labels are unaffected (see the z-order note in
-  [references/masked-fill.md](references/masked-fill.md)).
+- **The fill never shows, at any ratio** — the fill is painting UNDER the
+  frame while the frame's channel is opaque track art. The recipe puts the
+  mask div AFTER the frame `<img>` in source order (fill on top); check the
+  DOM order first. The mask keeps the fill inside the channel, so the rim and
+  baked labels are unaffected (see [references/masked-fill.md](references/masked-fill.md)).
 - **`genex ui masks` fails registration/coverage checks** — the annotated
   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.
+  Do NOT loosen the tolerance to force a pair through: a mask registered off
+  its frame ships a fill that floats off the art, and loosened runs are
+  stamped in the metadata (preview/publish will warn about them).
+- **`ui masks` refuses: "the fill channel is painted filled in the frame
+  art"** — the sheet model ignored "REMOVE the fill" and left the bar painted
+  full (usually near-white). The defect is invisible at 100% and shows the
+  moment the value drops. Region-edit that cell so the trough is EMPTY
+  (dark/recessed, no fill), then re-run — never wire that frame as-is.
+- **`ui audit` errors with `white-trough`** — a shipped frame's fill channel
+  measures opaque near-sheet-white: the model drew the trough white/filled and
+  the cleaner can't reach enclosed regions. Under-fills silently never show
+  behind it. Run the sheet repair lane (region-edit the trough to its EMPTY
+  dark track, `--inpaint` for one cell), then re-clean + re-extract — never
+  ship the frame, never pixel-punch the white out.
+- **After any `--edit`/`--inpaint` repair the sprites look stale/wrong** —
+  the whole sheet re-rendered (that's the edit contract): the OLD extractions
+  and masks describe the pre-edit sheet. Re-run `--clean`, re-extract, and
+  re-derive masks against the new sheet URL.
+- **Wisps, glows, smoke, hair get chopped by `--remove-bg`** — the binary
+  cutters can't do soft edges. Recut with `--bg-mode matte` (BiRefNet soft
+  alpha).
+- **`ui masks`/`ui extract` refuses: "the crop catches another sheet
+  element"** — elements sit too close on the sheet, so the crop would bake a
+  sliver of a neighbor into this asset. Regenerate the sheet with more
+  spacing between elements (or tighten the crop / lower `--padding`).
+- **"the crop box is slicing the element" (flush edge)** — widen the crop box
+  if the sheet has room; otherwise the sheet ran out of margin here —
+  region-edit or regenerate it with more margin around the element. There is
+  no tolerance to bump: a sliced frame ships as a cut-off corner.
+- **`ui audit` errors with `mask-frame-mismatch`** — the CSS ships a frame
+  PNG cut from DIFFERENT sheet geometry than the crop the mask was derived
+  against, so the fill floats off the frame. If you swap which frame variant
+  ships, re-run `ui masks` against it (or ship the mask's own `-frame.png`) —
+  a frame swap is never cosmetic once a mask is involved.
 - **`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).

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

@@ -18,24 +18,30 @@ mask's opaque pixels and prints in its JSON.
 
 ```
 widget root            position:absolute; overflow: VISIBLE   ← glows may bleed past the art
-├─ outer mask div      inset:0; overflow:hidden; mask-image:url(<mask.png>); mask-size:100% 100%
-│  └─ inner fill div   inset:0; FULL-BOX gradient; clip-path places the edge; data-fill-* stamps
-└─ frame <img>         inset:0; width/height:100%; object-fit:fill   ← painted on top
+├─ frame <img>         inset:0; width/height:100%; object-fit:fill   ← the frame WITH its baked
+│                                                                      empty dark track (Stage-2 rule)
+└─ outer mask div      inset:0; overflow:hidden; mask-image:url(<mask.png>); mask-size:100% 100%
+   └─ inner fill div   inset:0; FULL-BOX gradient; clip-path places the edge; data-fill-* stamps
 ```
 
 Confinement is the outer div's job (`overflow: hidden` + the mask). The
 widget **root stays `overflow: visible`** — otherwise any glow/halo that
 blooms past the silhouette gets sliced to a hard square.
 
-**Z-order depends on the frame art's channel.** "Frame on top" assumes the
-frame PNG's fill channel is transparent or translucent glass. This pipeline's
-deconstructed frames usually keep an **opaque** dark track texture inside the
-channel — a fill underneath is completely occluded (the bar looks stuck at
-empty no matter the ratio). In that case raise the mask div above the frame
-(`z-index` on the outer mask div): the mask confines the fill to the channel
-pixels, so the rim and any baked labels stay untouched. Check one extracted
-frame's channel pixels before wiring; if you can't see the fill move, this
-z-order is the first suspect.
+**The fill paints ON TOP of the frame — that is the recipe, not a fallback.**
+The Stage-2 sheet rule bakes every meter's EMPTY dark in-style track into the
+frame art, so the empty state is the art itself; the fill is a near-opaque
+gradient revealed over that track, and the mask confines it to the channel
+pixels so the rim, bezels, and any baked labels stay untouched. (Source order
+does the stacking: frame `<img>` first, mask div after — no z-index needed.)
+Painting the fill UNDER the frame is the exception, taken only when the frame
+has a genuinely transparent channel cavity AND a reason to use it — e.g. a
+real-translucency glass channel (`genex image --glass` art) the fill should
+glow through, or ornament overhangs that must paint over the moving fill.
+Never stack a plate/track div behind an opaque frame to compensate for a
+white-painted trough — a white or stained trough is a sheet defect
+(`ui audit` flags it); repair the SHEET (region-edit the trough to its empty
+dark track, re-clean, re-extract), never patch it at composite time.
 
 ## The reveal formulas
 
@@ -146,12 +152,12 @@ pair; the run's index `annotated-progress.json` nests the same objects in a
 
 ```html
 <div class="widget" id="hud-hp">
+  <img class="frame" src="/assets/hud/hp-frame.png" alt="">  <!-- frame + baked empty track -->
   <div class="fill-mask" style="-webkit-mask-image: url(/assets/hud/hp-mask.png); mask-image: url(/assets/hud/hp-mask.png);">
     <div class="fill" data-fill data-fill-mask="hp-mask.png"
          data-fill-box="0.0784,0.3469,0.9216,0.3605"
          data-fill-from="left" data-fill-ratio="0.72"></div>
   </div>
-  <img class="frame" src="/assets/hud/hp-frame.png" alt="">
 </div>
 ```