@genex-ai/cli-demo 0.80.2-dev.213 → 0.84.0-dev.215

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.80.2-dev.213",
+  "version": "0.84.0-dev.215",
   "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.
@@ -314,13 +327,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 +432,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 +451,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 +469,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 +557,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.
@@ -597,9 +645,14 @@ after a bad single costs the whole chain).
   re-roll); `--edit <url>` image-to-image edit of an R2 URL; `--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,9 +667,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); warn-only,
-  `--strict` exits 1 on findings.
+  wiring scan (unreferenced sprites/masks, naive %-fill patterns, and a
+  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
 
@@ -636,15 +697,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>
 ```
 

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

@@ -37,7 +37,7 @@ Lay these assets on a pure flat white #ffffff background, separated by at least
 [ASSET_LIST]
 
 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.
+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. Every meter/bar cell shows the meter EMPTY: the channel interior is painted as the meter's dark empty track in the art's own style — recessed, unlit, like a drained lamp-oil groove or a powered-down light strip. NEVER white, NEVER a filled bar, NEVER the sheet background color inside a frame. 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 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.
@@ -55,7 +55,7 @@ KEEP these baked into the asset — they are part of the panel's IDENTITY and ne
 
 REMOVE runtime-owned content:
 - Current numeric values (the "1247" coins, the "47" ammo count)
-- Current bar fill levels (the colored fill INSIDE a bar — runtime code reveals it through a mask)
+- Current bar fill levels (the colored fill INSIDE a bar — runtime code paints the fill; the emptied channel shows the meter's own dark empty track, never white, never the sheet background)
 - Current item icons inside slots (the sword, potion — runtime renders the equipped item)
 - Current map content / radar blips (the game paints these at runtime)
 - Any editable or localizable label the design does not fuse into the frame, even if it does not change frame-to-frame

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

@@ -141,6 +141,32 @@ use the quad fallback or a hit-spark VFX instead. Impact marks are a first-class
 generated surface for any weapon/collision game — inventory them up front with
 the rest of your art, don't discover the bare walls at the end.
 
+## Real-translucency glass panels — `--glass`
+
+A sprite cut from an unknown background can never carry semi-transparency —
+but a panel generated on a CONTROLLED backdrop can. `--glass` appends a
+flat-magenta key-screen suffix to your prompt, then (after generation) solves
+the per-pixel contamination locally into REAL fractional alpha and writes
+ready RGBA files (`glass-1.png`, one per candidate, into `--out-dir`,
+default `.`) plus the key metrics (key color, strength, flatness):
+
+```bash
+npx genex image "frosted translucent dark glass panel, about 40 percent opacity, thin luminous cyan frame" --glass --size 1280x832 --quality high
+```
+
+- **Steer the translucency with words**: "frosted translucent … about 40
+  percent opacity" → real see-through glass; "dark smoked glass" → near-
+  opaque tint. The suffix handles the backdrop; your prompt owns the glass.
+- **Wire the PNG like any sprite** — its alpha IS the glass. No CSS opacity
+  on top, no plate underneath.
+- **Not for magenta/pink-hued art**: magenta in the SUBJECT keys as
+  translucency. Panels, frames, HUD plates — yes; a pink neon sign — no.
+- A candidate whose backdrop came back shaded is REJECTED with a retryable
+  message (rare — regenerate). `--glass` is generation-only: it conflicts
+  with `--edit`/`--clean`/`--upscale`/`--transparent`/`--remove-bg`/`--no-wait`.
+- Glass files are LOCAL outputs (like HUD sprites) — they ship with the
+  build; commit them under `public/assets/`.
+
 ## Multiplayer
 
 The asset URL is public, permanent, and CORS-open, so it is safe to broadcast the
@@ -181,10 +207,22 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 - `--quality <low|medium|high>` — quality preset; higher costs more and takes longer.
 - `--size <WxH>` — exact pixel size (multiples of 16, each side ≤ 3840, aspect ≤ 3:1).
 - `--edit <url>` — edit THAT generated image with the prompt (image-to-image).
+- `--inpaint <mask.png|url>` — with `--edit`: a region mask (local PNG or
+  asset URL; TRANSPARENT hole = the zone to change). It targets WHERE the
+  edit lands — the other regions keep their designs — but the WHOLE image
+  still re-renders and alpha is destroyed either way: after any masked edit,
+  re-run `--clean`/re-extraction downstream. A targeting scope, not a pixel
+  freeze.
 - `--clean <url>` — ML background removal of THAT image only (prompt recorded, unused).
+- `--upscale <url>` — 2x utility upscale of THAT image (prompt recorded,
+  unused; ~2-credit class). Use before printing/large billboards, not by
+  default.
 - `--remove-bg` — chain ML background removal after the generation/edit.
-- `--bg-mode <sprite|glyph|sheet>` — background-removal model (`glyph` for
-  digits/closed shapes; `--clean` defaults to `sheet`).
+- `--bg-mode <sprite|glyph|sheet|matte>` — background-removal model (`glyph`
+  for digits/closed shapes; `--clean` defaults to `sheet`; `matte` = BiRefNet
+  SOFT alpha for hair/glow/smoke edges the binary cutters butcher).
+- `--glass` — the magenta-key real-translucency lane (section above);
+  writes local RGBA files into `--out-dir` (default `.`).
 - `--no-wait` — enqueue and return immediately, without the URL. Fire-and-forget
   only: re-running the command creates (and bills) a NEW image.
 - `--api-url <url>` — override the API base (local dev).