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

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

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

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

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

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

@@ -81,7 +81,10 @@ reason is the failure mode this section exists to kill:**
 (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
+generation — Tier 2b, when the brief is ornate) / real glass
+(`npx genex image "<frosted panel>" --glass` — menus love frosted panels,
+and the solved RGBA carries TRUE translucency over the moving backdrop;
+`$genex-ai-image` documents the lane). The per-genre lean lives
 in the style capsules (`$genex-threejs-game-ui`'s
 references/style-capsules.md) — a lean, not a rule.
 
@@ -136,7 +139,7 @@ cycle. Two stacked `<video>` elements with the same src crossfade at the
 cycle end; any seam disappears deterministically, no regeneration lottery.
 
 **Phone tiers get the poster, not the videos** (`$genex-threejs-adaptive-quality`):
-two preloading 720p decoders while the 3D scene boots is a spike at exactly the
+two preloading HD decoders while the 3D scene boots is a spike at exactly the
 moment phones get killed for memory. On a phone tier, show the key-art poster
 image (a captured frame of the clip works) and skip `seamlessLoop` entirely —
 or defer ONE non-preloading video until after the first gameplay frame:
@@ -171,19 +174,40 @@ export function seamlessLoop(holder: HTMLElement, url: string, fade = 0.6): void
 
 Pause both videos when the menu phase hides (they're decode work), and
 resume the front one when it returns. Watch ONE full cycle in the browser
-before calling the menu done — that's the seam check.
+before calling the menu done — that's the seam check, and once the video is
+wired it is the menu's capture in the milestone smoke pass: one full loop
+cycle watched AS RENDERED. A metadata probe (ffprobe) can't see a seam, a
+panel covering the video, or a video that never plays — only watching can.
 
 **Work async — the menu must never block the game.** The still is
-`--edit`-anchored to the concept mockup, so it's style-dependent: generate it
-the moment the user approves the concept (not before), enqueue the video with
-`--no-wait`, ship the CSS menu
-(buttons + title over the frame IMAGE as a static backdrop), and swap the
-`<video>` in when `genex wait` prints the URL. The frame image doubles as the
+`--edit`-anchored to the concept mockup, so it's style-dependent: enqueue it
+`--no-wait` **the moment the concept mockup LANDS** — it rides the same
+immediate chain as the HUD Stage-2 sheet and the logotype; the user's
+keep/change answer never gates it (a later "change" just re-edits it against
+the new frame, image-priced). **Only the VIDEO — the expensive item — waits,
+and its trigger is an event, never a clock: fire it at the FIRST of (a) the
+user's yes to the concept, (b) the next `genex preview` push after the still
+has landed (a shipped milestone with the user silent = the pick stands), or
+(c) style art being the only work left. Never fire it while a user objection
+is open** ("change the colors" blocks it until the loop resolves). Ship the
+CSS menu (buttons + title over the frame IMAGE as a static backdrop) and
+swap the `<video>` in when `genex wait` prints the URL. The frame image doubles as the
 **loading screen background** — it exists minutes before the video does (see
 `$genex-threejs-game-ui`'s loader spec). Both assets live in Genex storage
 (R2) — permanent, public, CORS-open; you load them straight from the printed
 URLs, nothing is downloaded or committed.
 
+**When the generated art lands, the upgrade is a RE-COMPOSITION — not a
+backdrop swap.** DELETE the placeholder panel/card the moment the still or
+video goes in: the still was generated with negative space precisely so the
+buttons and logo sit DIRECTLY on the key art. A placeholder card left
+floating over the finished video is the single most common bad menu — a
+near-opaque panel (plus its darkening layers) hides the art you just paid
+for, and the menu reads as the plain CSS draft it started as. Allowed over
+the art: a thin, low-opacity scrim strictly behind the button rail for
+legibility, and at most ONE subtle full-screen grade layer. NEVER a
+card/panel covering the art.
+
 **Two failed video attempts = ship the still. Hard stop.** Video is the one
 generation that fails server-side with real frequency (render timeouts), and
 every attempt costs minutes of waiting. One retry is fair — shorten the clip
@@ -350,7 +374,11 @@ not):
   `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
+  counters get eaten, trim with `npx genex ui trim`. Then VERIFY it is
+  actually transparent — view the trimmed PNG over a bright test background;
+  background removal sometimes leaves an opaque disc or plate behind the
+  mark, and that plate ships as a hole punched in your key art. If any
+  background remains, re-run the clean. 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).
@@ -370,14 +398,12 @@ not):
   re-anchored the look) re-opens this rule once — re-edit the still
   (`--edit` against the new concept mockup) and re-run the video from the
   new still. Agent-initiated polish never does.
-- **The menu (`--frame`) path renders 720p — don't force 1080p.** The
-  frame-conditioned first-last-frame route was rejected by the provider at
-  1080p (repeated 422 failures that shipped a dead static menu), so the menu
-  video path defaults to the proven-good, seamless-looping 720p — no flag
-  needed. The DOM crossfade + full-screen scale read fine at 720p; do NOT pass
-  `--resolution 1080p` on a `--frame` menu clip just to sharpen it, or you risk
-  re-triggering the 422 and losing the video entirely. (Plain text-to-video,
-  without `--frame`, still defaults to 1080p.)
+- **The menu video renders 1080p by default — leave it alone.** Every video
+  path, the frame-conditioned (`--frame`) menu route included, defaults to
+  1080p: the menu clip is full-screen key art, and 720p stretched across a
+  desktop reads soft. Don't pass a resolution flag at all; `--resolution 720p`
+  exists only as a deliberate cost opt-down for clips that are genuinely
+  incidental — never the main menu.
 - **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 =
@@ -407,11 +433,10 @@ not):
   genuine state change; expect a loop seam.
 - `--duration <sec>` (video) — 4, 6, or 8 for frame-conditioned clips;
   default 8.
-- `--resolution <720p|1080p>` (video) — plain text-to-video defaults to 1080p;
-  the frame-conditioned (`--frame`) menu path defaults to **720p** for
-  reliability (1080p was rejected there). `720p` is also the cost fallback
-  (~half the credits). Loop clips (`--loop`) ignore it (that model has no
-  resolution parameter).
+- `--resolution <720p|1080p>` (video) — every path defaults to **1080p**, the
+  `--frame` menu route included. `720p` is the deliberate cost opt-down
+  (~half the credits) for incidental clips — not for the menu. 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

@@ -14,6 +14,14 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
 - **Use `$genex-threejs-procedural-geometry`** for parametric/abstract shapes,
   terrain, or anything you want to generate in code (infinite variations, no files).
 
+**The output is a STATIC, unrigged mesh — no skeleton, no animation clips.**
+A "wolf" or "guard" from this command can be posed and moved as one object,
+but its limbs cannot animate. Anything that must walk, attack, or die on
+screen routes to the creature lane instead: `npx genex creature` for
+biped-shaped bodies (real rig + library clips), or this command plus the
+procedural-motion recipes for everything else — `$genex-threejs-creatures`
+owns that split. The player's own character is `$genex-ai-character`.
+
 ## Run
 
 ```bash

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

@@ -0,0 +1,142 @@
+---
+name: genex-ai-music
+description: Generate a real instrumental background-music track (mp3) from a text prompt with `npx genex music`, then loop it quietly under the game in Three.js. Use for the one looping gameplay track every game with generated audio should have (reused on the menu at lower volume), plus optional boss or menu-specific tracks — always instrumental, always behind Music/SFX volume sliders in settings.
+---
+
+# Genex AI · Music
+
+Turn a prompt into a real **mp3** instrumental track and loop it under the game.
+One track transforms how finished a game feels — a silent game with polished art
+still reads as a tech demo.
+
+## When to use this vs. sfx
+
+- **Use `npx genex music`** for the continuous bed: the gameplay loop, a boss
+  theme, a menu theme. Tracks are instrumental by design (the API enforces it —
+  vocals under gameplay read as karaoke).
+- **Use `$genex-ai-sfx`** for event sounds — impacts, pickups, UI ticks. The
+  0.5–22 s sfx lane cannot produce a music bed; don't try.
+
+**The default plan is ONE track:** a ~90 s loopable gameplay track, reused on
+the menu (same URL, lower volume). Propose extra tracks (boss/menu-specific) as
+their own Assets-table rows only when the game's shape earns them.
+
+## Run
+
+```bash
+npx genex music "<prompt>" --no-wait
+npx genex music "dark orchestral hunt, low strings and taiko, steady menace, seamless loop, consistent energy, no intro, no outro" --duration 120 --no-wait
+```
+
+`--duration <sec>` (10–300) sets the length; the default **90 s** is the sweet
+spot for a loop. Music takes a minute-plus — enqueue with `--no-wait` alongside
+your other generations and pick it up with `npx genex wait <id>`. Prints:
+
+```
+https://assets.genex.technology/generations/<id>/audio-music
+```
+
+The mp3 lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (local
+dev, published game, and remixes alike).
+
+## Prompt recipe for loopable game music
+
+Mood + instrumentation + energy + loop wording:
+
+- Name the game's emotional register and 2–3 instruments ("brooding synthwave,
+  analog pads and arpeggio", "cozy acoustic folk, fingerpicked guitar and soft
+  strings").
+- Always end with: **"seamless loop, consistent energy, no intro, no outro"** —
+  there is no API loop flag; consistent energy at both ends is what makes
+  `setLoop(true)` inaudible. A track with a big intro pops every cycle.
+- Don't ask for vocals — the lane forces instrumental regardless.
+
+## Wire it in Three.js
+
+Music is **non-positional** (`THREE.Audio`, not `PositionalAudio`), looped,
+and QUIET — the default volume is **0.30**: it sits under the sfx, never over
+them. Browsers block autoplay, so start it on the first user gesture:
+
+```ts
+import * as THREE from "three";
+
+const listener = new THREE.AudioListener();
+camera.add(listener); // ONE listener serves music and every sfx
+
+// the URL `npx genex music` printed (R2 sends CORS headers, cross-origin works):
+const MUSIC_URL = "https://assets.genex.technology/generations/<id>/audio-music";
+const music = new THREE.Audio(listener);
+new THREE.AudioLoader().loadAsync(MUSIC_URL).then((buffer) => {
+  music.setBuffer(buffer);
+  music.setLoop(true);
+  music.setVolume(0.30); // the default — under the sfx, never over them
+  // autoplay policy: start on the first gesture (the menu's PLAY click is ideal)
+  const start = (): void => {
+    if (!music.isPlaying) music.play();
+  };
+  window.addEventListener("click", start, { once: true });
+  window.addEventListener("keydown", start, { once: true });
+});
+
+// Suspend when the tab hides (decode work + politeness), resume on return:
+document.addEventListener("visibilitychange", () => {
+  const ctx = listener.context;
+  if (document.hidden) void ctx.suspend();
+  else void ctx.resume();
+});
+```
+
+**Menu reuse:** the same `music` object at lower volume (`setVolume(0.18)`)
+during the menu phase, restored to the setting's value on PLAY — zero extra
+generations. If the loop point is audible (the track came back with an
+intro/outro despite the prompt), crossfade the tail into the head with a second
+`THREE.Audio` on the same buffer rather than regenerating.
+
+## Volume sliders are NOT optional
+
+A game with generated audio and no volume control is a failure mode. The
+settings screen gets **two sliders — Music and SFX** (music default 0.30, sfx
+~0.7), persisted (localStorage or the save slot) and applied live:
+`music.setVolume(v)` for the music bed; keep every sfx's volume routed through
+one shared multiplier. `$genex-threejs-game-ui` carries this as a hard settings
+rule — wire the sliders in the same milestone as the track.
+
+## Publish checklist
+
+- Load it from the **URL** the command printed — absolute and permanent, so it
+  resolves the same in local dev, the published game, and remixes. Nothing to
+  commit.
+- The track must be audible in the shipped game AND adjustable in settings —
+  an unwired paid track is flagged at preview/publish (the wiring audit).
+
+## Options
+
+- `--duration <sec>` — track length 10–300; default 90 (the loop sweet spot).
+  Longer costs more; a 90–120 s loop outlasts most sessions.
+- `--no-wait` — enqueue and return immediately with the generation id; pick it
+  up later with `npx genex wait <id>` (safe to re-run — it attaches to the SAME
+  generation). The default for music: build while it renders.
+- `--api-url <url>` — override the API base (local dev).
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx genex init` first (in the project — it resolves this project's own CLI) (it writes your `GENEX_TOKEN`).
+- **"Out of credits" (`insufficient_credits`)** — the account has no credits left
+  for this music generation. Tell the user the facts the CLI printed: their
+  balance, this generation's cost, and when their credits refill. Then continue
+  the build without a music bed (the game must work silent anyway) and mark the
+  spot with `// TODO(genex): regenerate when credits refill` so the real track
+  is one command away later. Do not stop the session over this.
+- **"Email not verified" (`email_verification_required`)** — generation credits
+  unlock after the account's email is verified. Give the user the verify link
+  the CLI printed, wait for them to confirm, then re-run the command.
+- **No sound** — the `AudioContext` is suspended until a user gesture; the
+  first `music.play()` must come from a click/keydown. Confirm the camera has
+  an `AudioListener`.
+- **The loop "pops" every cycle** — the track has an intro/outro (the prompt
+  missed the loop wording). One regeneration with "seamless loop, consistent
+  energy, no intro, no outro" is fair; after that, crossfade tail-into-head
+  with a second `THREE.Audio` on the same buffer instead of re-rolling.
+- **Music drowns the game** — 0.30 is the ceiling for a bed, not the floor;
+  drop it further under dialogue-heavy or ambience-led scenes.

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

@@ -10,13 +10,26 @@ also lights it (image-based lighting).
 
 ## When to use this vs. a procedural sky
 
-- **Use `npx genex skybox`** for a specific, recognizable sky/backdrop you can
-  describe — "golden hour over misty mountains", "stormy alien sky", "city at
-  night". You get a real image.
+- **Use `npx genex skybox`** for a specific, describable ENVIRONMENT — "golden
+  hour over misty mountains", "rolling thunderstorm, towering cumulonimbus",
+  "alien purple nebula", "hazy dusk sky over a distant sea horizon". You get a
+  real image.
 - **Use `$genex-threejs-atmosphere-aerial-perspective`** (or
   `$genex-threejs-volumetric-clouds`) for a fully procedural, animated,
   time-of-day sky generated in shaders.
 
+**A skybox is environment only — never content.** Buildings, trees, ruins,
+towers, or any object painted into the sky render at infinite distance: they
+never get closer as the player moves, they sit at the wrong parallax against
+the real 3D world, and they read as broken the moment the camera strafes.
+Structures belong in the scene as geometry (`npx genex model`); the sky
+carries atmosphere — light, weather, clouds, haze, stars. The CLI enforces
+this: every skybox prompt gets an environment-only suffix appended (you'll
+see `↳ environment-only guard applied` and the full final prompt is stored
+with the generation). If you genuinely need content baked into the sky —
+e.g. a space station panorama for a scene with no world geometry — pass
+`--raw` to send your prompt exactly as written.
+
 ## Run
 
 ```bash
@@ -81,8 +94,11 @@ scene.background = texture; // keep the raw texture for the visible sky
 
 ## Options
 
-- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
-  re-run without `--no-wait` to fetch it).
+- `--raw` — send the prompt exactly as written, skipping the appended
+  environment-only guard (for the rare sky that must carry content).
+- `--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
+  to the SAME generation).
 - `--api-url <url>` — override the API base (local dev).
 
 ## Troubleshooting

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

@@ -37,11 +37,13 @@ The clip lives in Genex storage (R2) and loads straight from that URL — you do
 download it and nothing is committed to your repo. The URL is permanent (local dev,
 published game, and remixes alike).
 
-> **Cost & length:** the default is a **5-second, 720p** clip, and that IS the right
-> default for a looping screen or backdrop — only pass `--duration` when the content
-> genuinely needs to be longer (a cutscene). Longer, higher-res clips cost more and
-> take longer. mp4 has **no alpha channel**, so a video is always a full rectangle
-> (there are no transparent video decals).
+> **Cost & length:** the default is a **5-second, 1080p** clip — the right default
+> for anything the player looks at directly. Only pass `--duration` when the content
+> genuinely needs to be longer (a cutscene), and `--resolution 720p` only when the
+> clip is genuinely incidental (a small in-world screen seen from a distance): it
+> halves the cost, but 720p stretched across the whole screen reads soft. mp4 has
+> **no alpha channel**, so a video is always a full rectangle (there are no
+> transparent video decals).
 
 ## Play it in Three.js
 
@@ -80,8 +82,9 @@ window.addEventListener("keydown", () => {
 One `VideoTexture` can feed **many** surfaces — a bank of monitors, N sprays. Cost is
 per distinct `<video>` element (media decode + one GPU upload per frame), **not** per
 surface, so sharing one element for every screen is nearly free (all play in sync).
-Keep clips **≤720p**. Pause the element (`video.pause()`) when no video surface is
-visible.
+Pause the element (`video.pause()`) when no video surface is visible; on phones,
+prefer the clip's source still as a poster and start the video only where it plays
+smoothly.
 
 ## Video decals
 
@@ -132,6 +135,9 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 - `--loop` — a seamless loop (for screens, ambient backdrops, video decals).
 - `--duration <sec>` — clip length 1–15; default 5. Only raise it when the content
   genuinely needs more — longer clips cost more and take longer.
+- `--resolution 720p|1080p` — output resolution (default **1080p**). `--resolution
+  720p` halves the cost — use it only when quality genuinely doesn't matter (a small
+  far-away in-world screen). `--loop` clips ignore it (model default).
 - `--frame <url>` — one generated image as BOTH first and last frame — the
   seamless-loop mode (motion must return to its start).
 - `--first-frame <url>` / `--last-frame <url>` — two-frame motion between two