@genex-ai/cli-demo 1.34.0-dev.693 → 1.34.1-dev.694

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.34.0-dev.693",
+  "version": "1.34.1-dev.694",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -381,3 +381,9 @@ game with a generated character, every remote wears it — one
   re-run from the id of the stage before it, never from the beginning.
 - **The rig or a pose is bad** — reject and regenerate. Never repair limbs at
   runtime; validation never rewrites limb animation.
+
+## Choose the body by its role
+
+Use this paid custom-character workflow for the player's body and characters the player examines or interacts with closely. For a background population, first reuse procedural bodies and motion or compatible existing rigged assets. Add distinct paid bodies only for a requirement reuse cannot satisfy, or an explicit user request. Catalog motion needs a compatible skeleton and may be paid.
+
+Structural QA reports blocking findings separately from advisories. In the direct-text lane, the server already tries both Meshy rest poses and can fall back to Uthana; do not pay for another T-pose attempt merely because the combined diagnostic names both failures. Read the delivered rig provider and capabilities: Uthana fallback has no Meshy controller pack or catalog clips. Use its supported motion workflow. Joint-visibility framing improves the input specification but is not proof a generated rig will pass.

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

@@ -61,7 +61,7 @@ Genre + mood + instrumentation + tempo + loop wording:
 
 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:
+them. Copy the shared [gesture gate](references/genex-audio-gesture.md) into your audio module first. It resumes the context from a gesture independently of decoding:
 
 ```ts
 import * as THREE from "three";
@@ -72,24 +72,21 @@ 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);
+let audioEnabled = true; // bind to playing && !muted; pause existing music when false
+let loaded = false;
+const audioGate = installAudioGestureGate(listener.context, () => {
+  if (loaded && !music.isPlaying) music.play();
+}, () => audioEnabled);
 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();
-});
+  music.setVolume(0.30);
+  loaded = true;
+  audioGate.refresh(); // a gesture may already have arrived while decoding
+}).catch(error => console.warn("Music failed to load", error));
+// On pause/mute: set audioEnabled, pause music if needed, then audioGate.refresh().
+// Dispose audioGate when this scene is destroyed.
+
 ```
 
 Decode the track (and every sfx clip) while the **menu** is up, not on PLAY:
@@ -143,9 +140,9 @@ hard settings rule — wire the sliders in the same milestone as the track.
 - **"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`.
+- **No sound** — call `listener.context.resume()` directly in the intended
+  click/keydown, independently of decoding. Check that it reaches `running`,
+  then verify a triggered event after final gain and positional attenuation.
 - **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

package/templates/skills/genex-ai-music/references/genex-audio-gesture.md

@@ -0,0 +1,47 @@
+# Genex audio gesture gate
+
+Copy this helper into the game's audio module once, shared by music, SFX and voice.
+Install it before starting asynchronous decoding. `enabled` reads the current
+playing/unmuted state; `ready` starts loaded continuous audio idempotently.
+Call `refresh()` after decoding or a pause/mute state change. One-shots still
+belong to their actual gameplay event, never replay a backlog after unlock.
+
+```js
+function installAudioGestureGate(context, ready, enabled = () => true) {
+  let authorized = false, disposed = false, resuming = false;
+  const refresh = () => {
+    if (!disposed && authorized && enabled() && !document.hidden && context.state === 'running') ready();
+  };
+  const gesture = () => {
+    if (disposed || !enabled() || document.hidden || resuming) return;
+    resuming = true;
+    // resume is invoked IN the gesture, before any await or asset decoding.
+    let resumed;
+    try { resumed = context.resume(); }
+    catch (error) { resuming = false; console.warn('Audio resume failed', error); return; }
+    Promise.resolve(resumed).then(() => { authorized = true; refresh(); })
+      .catch(error => console.warn('Audio resume failed', error))
+      .finally(() => { resuming = false; });
+  };
+  const visibility = () => {
+    if (document.hidden) void context.suspend().catch(error => console.warn('Audio suspend failed', error));
+    else if (authorized && enabled()) gesture();
+  };
+  window.addEventListener('pointerdown', gesture);
+  window.addEventListener('keydown', gesture);
+  document.addEventListener('visibilitychange', visibility);
+  return { refresh,
+    canPlay: () => authorized && enabled() && !document.hidden && context.state === 'running',
+    dispose() {
+      disposed = true;
+      window.removeEventListener('pointerdown', gesture);
+      window.removeEventListener('keydown', gesture);
+      document.removeEventListener('visibilitychange', visibility);
+    }
+  };
+}
+```
+
+Mute/pause handlers stop or pause current playback themselves and then call
+`refresh()`. The gate never changes gains or unmutes a game. If the context
+cannot resume on visibility return, the next gesture can retry.

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

@@ -44,6 +44,10 @@ import * as THREE from "three";
 
 const listener = new THREE.AudioListener();
 camera.add(listener);
+// Copy the shared gesture gate below; register BEFORE any asynchronous decode.
+let audioEnabled = true; // Bind to the game's playing and unmuted state.
+const audioGate = installAudioGestureGate(listener.context, () => {}, () => audioEnabled);
+// audioEnabled is the game's current playing && !muted state.
 
 // the URL `npx genex sfx` printed (R2 sends CORS headers, so cross-origin works):
 const SFX_URL = "https://assets.genex.technology/generations/<id>/audio-sfx";
@@ -55,7 +59,7 @@ sound.setRefDistance(5);
 laserMesh.add(sound); // follows the object
 
 // on fire:
-if (!sound.isPlaying) sound.play();
+if (audioGate.canPlay() && !sound.isPlaying) sound.play();
 ```
 
 **Global** (UI/non-spatial — same volume everywhere): use `new THREE.Audio(listener)`
@@ -186,8 +190,9 @@ To silence a loop, ride the volume to 0 and leave it running — never `stop()`/
 - **"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; trigger the
-  first play from a click/keydown. Confirm the camera has an `AudioListener`.
+- **No sound** — call `listener.context.resume()` directly in the intended
+  click/keydown, independently of decoding. Check that it reaches `running`,
+  then verify a triggered event after final gain and positional attenuation.
 - **Too quiet/loud** — `sound.setVolume(0..1)`; for positional, tune
   `setRefDistance` / `setRolloffFactor`.
 - **Stutters on a phone while moving, at every quality setting** — audio, not
@@ -195,3 +200,9 @@ To silence a loop, ride the volume to 0 and leave it running — never `stop()`/
   the same triage from the performance side).
 - **A sound is late the first time, then fine** — it was still decoding. Preload
   during the menu.
+
+## Gesture unlock and audible evidence
+
+Copy the `$genex-ai-music` shared gesture gate (`references/genex-audio-gesture.md`) once into your audio module and share it with every lane. Define `audioEnabled` from playing/unmuted state before installing it. Register before decoding; `THREE.Audio.play()` does not resume a suspended context. Keep mute/pause ownership in the game. Do not queue stale one-shots for later unlock.
+
+For **no sound**, first check a real gesture called `listener.context.resume()` and that it reached running. Then check decoded data, source start, gains and positional attenuation. Measure a deliberately triggered audible event using $genex-threejs-visual-validation; a running context or loaded file alone is insufficient.

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

@@ -81,7 +81,11 @@ Non-positional (`THREE.Audio`) for narrator/announcer voices; positional
 import * as THREE from "three";
 
 const listener = new THREE.AudioListener();
-camera.add(listener); // ONE listener serves music, sfx, and voice
+camera.add(listener);
+// Copy the shared gesture gate below; register BEFORE any asynchronous decode.
+let audioEnabled = true; // Bind to the game's playing and unmuted state.
+const audioGate = installAudioGestureGate(listener.context, () => {}, () => audioEnabled);
+// audioEnabled is the game's current playing && !muted state. // ONE listener serves music, sfx, and voice
 
 const VOICE_URL = "https://assets.genex.technology/generations/<id>/audio-voice";
 const line = new THREE.Audio(listener); // PositionalAudio(listener) at the speaker's mesh for world speech
@@ -93,6 +97,7 @@ new THREE.AudioLoader().loadAsync(VOICE_URL).then((buffer) => {
 });
 
 function sayLine(text: string): void {
+  if (!line.buffer || !audioGate.canPlay()) return;
   if (line.isPlaying) line.stop(); // a new line interrupts the old — never overlap voices
   line.play();
   subtitles.textContent = text;    // SUBTITLE every voice line, always
@@ -148,6 +153,12 @@ function sayLine(text: string): void {
 - **Wrong language/accent** — the model speaks the language of the TEXT; for
   an accent, pick a different cast voice (or a specific `--voice-id`) rather
   than describing the accent in the text.
-- **No sound** — the `AudioContext` is suspended until a user gesture; confirm
-  the camera has an `AudioListener` and the first play comes from a
-  click/keydown.
+- **No sound** — call `listener.context.resume()` directly in the intended
+  click/keydown, independently of decoding. Check that it reaches `running`,
+  then verify a triggered event after final gain and positional attenuation.
+
+## Gesture unlock and audible evidence
+
+Copy the `$genex-ai-music` shared gesture gate (`references/genex-audio-gesture.md`) once into your audio module and share it with every lane. Define `audioEnabled` from playing/unmuted state before installing it. Register before decoding; `THREE.Audio.play()` does not resume a suspended context. Keep mute/pause ownership in the game. Do not queue stale one-shots for later unlock.
+
+For **no sound**, first check a real gesture called `listener.context.resume()` and that it reached running. Then check decoded data, source start, gains and positional attenuation. Measure a deliberately triggered audible event using $genex-threejs-visual-validation; a running context or loaded file alone is insufficient.

package/templates/skills/genex-game-director/SKILL.md

@@ -148,9 +148,9 @@ vendored code from memory of another engine.
 | eye adaptation, tone mapping, output color, LUT grading, and proven static grain | `$genex-threejs-exposure-color-grading` |
 | fixed-view screenshots, input direction, facing, temporal and budget evidence | `$genex-threejs-visual-validation` |
 | **a model the player already has** — a `.glb` they exported, bought or made elsewhere: it is IMPORTED, never rebuilt. `npx genex model import <file.glb>` (free) for props and non-biped bodies (then `model rig`/`model animate`), `npx genex character import <file.glb>` for a humanoid that should walk (Uthana auto-rig, then `character animate --locomotion`) | `$genex-ai-model` · `$genex-ai-character` |
-| the default for a concrete object the player looks at up close: a generated GLB for a prop, vehicle, building, or object — from text or a reference image (`--image`); split into named parts (`model segment`); rig + animate any mesh (`model rig` / `model animate`). A space routed to code above does NOT settle these: a village's ground plan can be code while the forge you walk up to is generated | `$genex-ai-model` (first time this session: `$genex-lane-card`) |
+| the default for a concrete object the player looks at up close: a generated GLB for a prop, vehicle, building, or object — from text or a reference image (`--image`); split into named parts (`model segment`); rig + animate any mesh (`model rig` / `model animate`). A space routed to code above does NOT settle these: the ground plan can be code while an object examined up close is generated | `$genex-ai-model` (first time this session: `$genex-lane-card`) |
 | generated surface or terrain texture with real-world UV scale | `$genex-ai-texture` |
-| sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code in the scene—there is no sky command and no owning skill, so pick the technique this game needs |
+| sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code; $genex-threejs-exposure-color-grading owns gameplay lighting and time-of-day readability, with atmosphere techniques chosen for the scene |
 | poster, sign, sprite, decal, reference sheet, or other 2D art | `$genex-ai-image` |
 | in-world motion art or another requested video | `$genex-ai-video` |
 | sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
@@ -185,25 +185,11 @@ supplied and creating one is part of the requested work, use the existing
 `npx genex image` lane unchanged and record that paid reference as its own
 Assets row.
 
-The request sets the floor for the asset plan, never the ceiling: a world
-should feel dressed and alive, so plan the detail its genre implies — and
-choose the engine per object, never per category. The bar is the same for both
-engines: whatever the player looks at must read as the thing it is, in this
-game's own style — a building as that building, a person as a person, a prop as
-that prop. A coloured box, a capsule or a flat grey block is not a finished
-version of any of them. Generation is the default route to that bar wherever
-code will not honestly reach it: the player's character, anything the request
-names, anything the player walks up to, enters, or interacts with, and the
-music and sound under it. Procedural code (`$genex-threejs-procedural-assets`)
-is a first-class engine for what is structural, repeated, distant, or
-parametric — terrain, sky (never generated), fences, paving, modular kits,
-filler — and for anything else only when the result meets the same bar and you
-have checked it in a capture before its row says `landed`. Write the route on
-each Assets row: the paid flow for generated pieces, the procedural flow with
-its local path for code-built ones — the table is where the per-object decision
-lives, and a table with no generated row records
-`Generation: none — <why code alone reaches the bar here>` beside it. Mixing
-both in one scene is the normal way to build, never a fallback. In focused
+Every asset must read as the thing it is from the gameplay camera. Decide per object which engine meets that bar; procedural authoring is a first-class engine.
+
+Plan one reusable implementation per distinct required gameplay or visual role before adding variants. Each Assets row records **role**, **reuse** (instances or compatible existing assets), and **done when** (the visible or playable requirement it satisfies), beside its route and price. Background populations default to reusable procedural bodies and motion, or compatible existing rigged assets. Catalog clips require a compatible skeleton and may cost credits; they are not free animation for arbitrary procedural meshes. Reserve custom paid character workflows for the player body and characters examined or interacted with closely; explicit user requests still take precedence.
+
+Add a variant only when reuse leaves a demonstrated requirement unmet. Unspent allowance is not unfinished work. Procedural pieces must meet the same visual bar as generated ones; a placeholder capsule or box is not a finished person or prop. Keep the existing Assets table, and record `Generation: none — <why code or reuse reaches the bar>` when no paid generation is needed. Mixing engines is normal. In focused
 work, stay inside the touched scope. Generate in batches you can finish, and
 generate what the wallet can carry: every build has an asset allowance, and
 `npx genex budget` prints it live with the price of each kind. Each Assets row
@@ -433,3 +419,5 @@ than restarting design discovery.
 requested acceptance and relevant owning-lane checks are true. Never report a
 skill as applied because you read it, an asset as wired because it generated,
 or the full requested outcome as complete while Open commitments remain.
+
+For an allowance increase or any approval question, call `ask_user` with `timeoutPolicy: no-consent`. A recommended option is not permission. On timeout the trim stands: keep the existing allowance and continue independent work. Use `assume-default` only for reversible design choices, never spending or permissions.

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

@@ -121,12 +121,13 @@ HUD lane: sprites (<which elements the sprite lane is producing>)
 Menu video: <generation id/URL, or the still standing in while it renders>
 
 ## Assets — the generation plan AND budget (only when used)
-| Asset | Kind | Status | Wired? |
-|---|---|---|---|
-| <asset> | <model/image/texture/…> | planned | — |
-| <asset> | <kind> | generating (<id>) | — |
-| <asset> | <kind> | landed → <URL> | yes/no |
-| <asset> | procedural-code | building (blockout) | — |
+| Asset | Kind | Status | Wired? | Role | Reuse | Done when |
+|---|---|---|---|---|---|---|
+| <asset> | <model/image/texture/…> | planned | — | <required gameplay/visual role> | <instances or existing asset> | <observable requirement> |
+| <asset> | <kind> | generating (<id>) | — | <role> | <reuse> | <requirement> |
+| <asset> | <kind> | landed → <URL> | yes/no | <role> | <reuse> | <requirement> |
+| <asset> | procedural-code | building (blockout) | — | <role> | <reuse> | <requirement> |
+Start with one implementation per distinct required role. Add variants only for an unmet requirement; unspent allowance is not unfinished work. Trim to the allowance or ask before increasing it.
 Status flow: proposed → planned → generating (id) → landed (URL) → wired.
 Code-built rows: proposed → planned → building (…) → landed (<local path>) → wired.
 Generation: none — <why code alone reaches the bar in this game> (only when no row is generated)

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

@@ -113,15 +113,13 @@ SPACE the player moves through — a level, an interior, a whole building — is
 is off on the stand.
 
 **That fallback claims the SPACE, never the things standing in it.** MEASURED
-2026-09-03: a village brief matched the space row, the Blender lane was off, and
-the whole world — every house, the forge, the well, and five villagers — was
-built as code with no Assets table written and not one generation run. Routing
-the ground plan to this lane is not a decision about the forge the player walks
-up to, the smith they talk to, or the props they pick up: those are their own
-rows (`$genex-ai-model`, `$genex-ai-character`, `$genex-threejs-creatures`) and
-they are still decided per object against the asset bar. A village's layout in
-code with generated buildings and characters standing on it is the normal shape,
-not a contradiction.
+The space row claims the SPACE, never the things standing in it. Routing
+terrain or a ground plan to code does not decide how close-interaction props,
+characters or structures are made. Choose each by its gameplay/visual role,
+reuse and completion requirement. Background populations can reuse procedural
+bodies/motion or compatible existing rigs; custom paid character workflows
+serve the player body and close interactions, subject to explicit requests.
+Catalog animation requires a compatible skeleton and may be paid.
 
 - Prefer a supplied reference. A private attachment stays local unless the
   player explicitly permits upload, publication, or commit.

package/templates/skills/genex-lane-card/SKILL.md

@@ -72,9 +72,7 @@ after that. `npx genex budget` prints it live: balance, spendable, the
 allowance, spent this build, remaining, and the price of every kind. Run it
 before the first batch and after each preview.
 
-The allowance is the build's asset money and it is MEANT to go on what the
-brief names — leaving it unspent while you code-build the named things is as
-wrong as draining it on props. Plan the asset table against it: the named
+The allowance is a ceiling, not a target. Unspent allowance is not unfinished work. Start with one reusable implementation per required role, and add variants only when reuse leaves a demonstrated requirement unmet. Plan the asset table against it: the named
 things first, then what makes the scene read, on the cheapest lane that reaches
 the bar. If the plan needs more than it holds, ask the player with the number
 BEFORE trimming; only their word raises it (`npx genex budget --assets
@@ -97,3 +95,5 @@ A lane whose provider wallet is empty fails every call and refunds every one.
 `npx genex doctor` prints each lane live/mock/paused with its credit state. If a
 lane is red: **build that thing in code and move on** — do not re-run it, and do
 not stall the game waiting for it. Say in chat what you fell back to.
+
+Use `timeoutPolicy: no-consent` for allowance questions. Background populations reuse procedural bodies/motion or compatible existing rigs; catalog animation needs a compatible skeleton and can be paid. Custom character workflows serve the player body and close interactions, subject to explicit user direction.

package/templates/skills/genex-threejs-exposure-color-grading/SKILL.md

@@ -71,8 +71,17 @@ c += g * uGrain * lw;                        // uGrain ~0.02–0.03, NOT 0.045
 - **See it in the running game**, and specifically look for shimmer while nothing
   moves (`$genex-threejs-visual-validation` has the two-frozen-frame check).
 
+## Gameplay lighting and dark-phase readability
+
+Own the scene's key/fill/environment balance across its playable time-of-day phases. Keep useful fill or environmental illumination when the key light fades; tune the final rendered image rather than prescribing a universal light intensity. Preserve the intended mood and avoid clipping the bright phase.
+
+Capture the darkest intended **playable** phase at a representative view after reaching it with real controls or time progression. Split the full gameplay screenshot into 4×4 tiles. For each pixel use sRGB luma `(0.2126*r + 0.7152*g + 0.0722*b)/255`. For tile `(x,y)` in 0..3, its weight is `1 / (1 + (x-1.5)**2 + (y-1.5)**2)`: centre 0.666667, edge 0.285714, corner 0.181818. Divide the weighted sum of tile means by total weight. Require **>= 0.08**; retain the bright-phase upper band of 0.85 and inspect tonal range and contrast. This is screenshot-domain luma, not the HDR/linear luminance used for exposure adaptation.
+
+Inspect the screenshot too: bright HUD text must not hide unreadable gameplay. The general prober's median exposure result is separate; it cannot prove the darkest phase. Without a confirmed darkest-phase capture, report unknown. Fold this into the milestone smoke pass.
+
 ## Failure conditions
 
+- the confirmed darkest playable phase falls below 0.08 centre-weighted sRGB luma, or a bright HUD masks unreadable play;
 - tone mapping occurs in both materials and post;
 - exposure is used to repair physically inconsistent light ratios;
 - meter weighting and scene framing are not inspected;
@@ -87,4 +96,4 @@ c += g * uGrain * lw;                        // uGrain ~0.02–0.03, NOT 0.045
 
 Keep HDR glow, AO, atmosphere, and shared render-target ordering in the game's
 existing post stack. This skill owns exposure, tone mapping, grading, and output
-conversion only.
+conversion, gameplay lighting and time-of-day readability.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -153,7 +153,7 @@ everything twice.
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.
 
-### The screenshot has three blind spots — query them
+### The screenshot has four blind spots — query them
 
 A capture of the whole arena is taken from one camera at one distance. Three real
 defect classes are invisible in it and all shipped to players:
@@ -383,3 +383,9 @@ visual-system work — the sequence above.
 This skill evaluates an implementation; it does not supply the implementation
 mechanism. Load the subject or image-effect skill first, then use this protocol
 to decide whether the result is acceptable.
+
+## Audio and dark phases in the same smoke check
+
+A still cannot prove audible output. Use the [development-only final-mix check](references/genex-audio-output.md) after a real gesture and trigger an intended audible event. Require observed peak RMS **> 0.002**, at least ten running-context samples, and mute off; missing evidence is unknown. Record context state, sample count, RMS, mute and event. Loaded audio and graph edges alone are not audibility.
+
+For games with a dark playable phase, observe the darkest intended phase through the game's real controls or time progression and capture it, then follow $genex-threejs-exposure-color-grading. No dark-phase observation means unknown, never an assumed pass. Add these observations to the existing milestone smoke check rather than starting a repeated inspection loop.

package/templates/skills/genex-threejs-visual-validation/references/genex-audio-output.md

@@ -0,0 +1,43 @@
+# Genex final-mix audio check
+
+Use in development only. Pass the game's real final master gain (Three.js:
+`listener.getInput()`), after per-source gain and positional attenuation.
+Every intended source must feed that master. This observes the real mix; it
+does not fix a silent source or unlock the browser. First enter gameplay with
+a real gesture and leave mute off. `trigger` fires an actual audible game
+event. Do not use a synthetic test tone as evidence for the game's audio.
+
+```js
+async function measureFinalMix(context, master, { muted, event, trigger }) {
+  if (!event || typeof trigger !== 'function') return { result: 'unknown', reason: 'No intended audible event' };
+  const analyser = context.createAnalyser();
+  const silentSink = context.createGain();
+  analyser.fftSize = 2048;
+  silentSink.gain.value = 0;
+  master.connect(analyser);
+  analyser.connect(silentSink);
+  silentSink.connect(context.destination); // pull the tap without doubling the audible output
+  const samples = new Float32Array(analyser.fftSize);
+  let count = 0, peakRms = 0;
+  try {
+    trigger();
+    for (let i = 0; i < 40; i++) {
+      await new Promise(resolve => setTimeout(resolve, 50));
+      if (context.state !== 'running') continue;
+      analyser.getFloatTimeDomainData(samples);
+      let power = 0;
+      for (const value of samples) power += value * value;
+      peakRms = Math.max(peakRms, Math.sqrt(power / samples.length));
+      count++;
+    }
+    return { result: muted || count < 10 ? 'unknown' : peakRms > 0.002 ? 'pass' : 'fail',
+      contextState: context.state, samples: count, peakRms, muted, event, threshold: 0.002 };
+  } finally { master.disconnect(analyser); analyser.disconnect(); silentSink.disconnect(); }
+}
+```
+
+Run this during the existing milestone smoke check, with the intended event
+and representative listening position recorded. Muted, insufficiently sampled
+or untriggered checks are not passes. Quiet output with a running context
+requires checking source starts, final gains and distance/rolloff. Do not turn
+up a diagnostic-only signal to pass; verify the real event by listening too.