@genex-ai/cli-demo 0.68.0 → 0.70.0-dev.182

package/templates/skills/genex-threejs-adaptive-quality/references/adaptive-quality.md

@@ -0,0 +1,105 @@
+# Genex adaptive quality — tiers, knobs, and the governor in depth
+
+Use this reference when tuning the tier ladder, deciding which knob may change
+when, or teaching the governor a game-specific step.
+
+## Why boot-conservative
+
+The phone budget is a hard ceiling that includes GPU memory (textures,
+framebuffers), and the OS kill arrives with no catchable event. Boot is the
+danger window: skybox + models + post targets decode together. So phone tiers
+START one notch below what the heuristics suggest and the governor steps UP
+after ~20 smooth seconds. The cost of guessing low is moments of softness; the
+cost of guessing high is a dead page.
+
+## The tier ladder
+
+| Knob | phone-low | phone | desktop |
+|---|---|---|---|
+| DPR cap | 1.0 | 1.5 | 2 |
+| antialias (context) | off | off | on |
+| Shadow map | 512 (static-cached) | 1024 | 2048 |
+| Post level | tone map only | + FXAA/vignette | full named stack |
+| Skybox rung | @2048 (~11 MB) | @4096 (~45 MB) | original |
+| Texture rung (props) | @1024 | @2048 | original |
+| Particles/scatter | 0.25× | 0.5× | 1× |
+| Draw distance | 0.5× | 0.75× | 1× |
+| Frame target | stable 30 | 60 | 60 |
+| Remote avatars animated | 4 | 8 | all |
+| Prop colliders | hull/cuboid | hull | as designed |
+
+A DPR drop from 3 (raw iPhone) to 1.5 cuts every full-screen surface — color,
+depth, and each post target — to a quarter of the bytes. It is the single
+strongest lever the tier owns.
+
+## The knob split — what may change when
+
+Getting this wrong produces silent no-ops or a session stuck ugly:
+
+- **Context-creation-fixed (never changes live):** `antialias`, `alpha`,
+  `stencil`, `powerPreference` on WebGL. Changing them means a new context and
+  a full re-init — the tier must decide them BEFORE the renderer exists.
+  (WebGPU differs: MSAA is per-render-target sample count and is runtime-
+  changeable.)
+- **Load-time (fixed for the session once fetched):** asset rungs (skybox and
+  texture resolutions), model LOD sets. `pickAsset` decides them from the tier
+  at load; switching later means a re-fetch — treat as fixed.
+- **Runtime-free (the governor's domain):** `setPixelRatio`, post passes on/off
+  and their target resolutions, shadow map size (realloc), draw distance and
+  fog, LOD bias, particle counts, mixer update rates, frame cap, remote-avatar
+  animation count.
+
+## Governor mechanics
+
+- Slow = frame delta over budget for a SUSTAINED window (4 s) — never single
+  spikes, which are usually shader compiles or GC. Precompiling with
+  `renderer.compileAsync` during the loader screen removes most spikes at the
+  source (and keeps first-frame jank from reading as a stall to the platform's
+  telemetry).
+- Step-down order: DPR ×0.8 → post off → draw distance ×0.6 → 30 fps cap.
+  Each step is the cheapest remaining lever with the biggest headroom return.
+- Step-up needs 20 smooth seconds (hysteresis), and a step that had to be
+  re-applied twice is pinned for the session — oscillating quality reads worse
+  than stable-low.
+- The governor never stops: thermal throttling degrades phones after minutes
+  of play, so a boot-time benchmark alone always ends up wrong.
+- A stable 30 fps cap beats a stuttery 40–50: consistent frame pacing reads
+  smoother and halves GPU work per second (heat, battery, memory bandwidth).
+- Backgrounded tab (`visibilitychange`): pause the render loop and audio, not
+  just the governor — a hidden game burning GPU is pure thermal debt on the
+  device class that can least afford it.
+
+## Detection honesty
+
+- Apple devices mask the GPU renderer string ("Apple GPU") — screen dims + DPR
+  + iOS major version are the usable signals there, and the governor corrects
+  the rest from measured frames.
+- Android exposes real renderer strings (Adreno/Mali/Xclipse); the vendored
+  lookup in `tier.ts` promotes strong GPUs to the `phone` tier. It is a
+  heuristic on purpose — extend the regex when field data shows a
+  misclassified family, and let the governor absorb the rest.
+- Never burn a probe context on a memory-strapped phone at play time; the one
+  probe in `tier.ts` runs at boot and frees its context immediately.
+
+## Memory discipline that rides the tier
+
+- Dispose on every level swap: traverse the outgoing scene and call
+  `.dispose()` on geometry, material, AND each material's textures — material
+  dispose does not free textures, and three frees nothing automatically.
+- Watch `renderer.info.memory.{textures,geometries}` across swaps in dev; a
+  monotonic climb is a leak marching toward the OS kill. The governor
+  publishes these counts for the platform's field telemetry.
+- Prefer meshopt/instanced geometry for repeats; `BatchedMesh` batches
+  HETEROGENEOUS static meshes into one draw where instancing (identical
+  meshes only) can't.
+- Half-resolution transparency: render heavy particle/transparency passes to a
+  half-size target and composite up — fill-rate is the phone bottleneck.
+
+## Multiplayer at tier
+
+Remotes are visual-only; with the shared avatar file, `loadVrmClone` gives N
+remotes one set of GPU geometry/textures. Animate and fully draw only the
+nearest `tier.remoteAvatarCap`; beyond it, freeze the mixer and billboard or
+hide. Matchmade games can also declare a lower `maxPlayers` in
+`genex.matchmaking` for phone-heavy audiences — capacity is a server-owned
+knob.

package/templates/skills/genex-threejs-bloom/SKILL.md

@@ -32,7 +32,10 @@ reference before adding selective bloom to a composed scene.
 - selective bloom requires mutating scene materials every frame without restoration guarantees;
 - transparent particles disappear from extraction because pass ownership is unclear;
 - bloom radius changes wildly with resolution;
-- highlights become gray because energy is clamped too early.
+- highlights become gray because energy is clamped too early;
+- bloom ships un-tiered: phone tiers run the light post level
+  (`$genex-threejs-adaptive-quality`) — bloom is a desktop-tier pass, and its
+  full-res HDR target is exactly the allocation phones get killed for.
 
 ## Routing boundary
 

package/templates/skills/genex-threejs-bloom/references/bloom.md

@@ -2,7 +2,7 @@
 
 Use this reference to choose bloom ownership, signal order, selective contribution, and scene-relative emissive ranges without making bloom responsible for the underlying form.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -35,9 +35,12 @@ rules, floating-origin shot, pointer controls, and implementation limits.
 
 ## Aiming and pointer lock
 
-On the bundled `FollowCamera`, **pointer-lock aim is ON by default** on desktop:
-a click locks the pointer and raw mouse movement drives the view. You rarely turn
-it on — you decide whether to turn it OFF. Name the bucket in the build plan:
+The rule is binary: during play, **the cursor is either a gameplay tool or it is
+locked away**. An OS arrow parked over the action in a game that never uses it is
+a shipped defect, not a default. On the bundled `FollowCamera`, pointer-lock aim
+is ON by default on desktop — a click locks the pointer and raw mouse movement
+drives the view — so mostly you decide whether to turn it OFF. Name the bucket in
+the build plan:
 
 - **MANDATORY** — first-person of any kind (FPS, walking sim, horror) and any
   mouse-aimed action (third-person shooter, turret/range). Lock is on by default;
@@ -47,11 +50,16 @@ it on — you decide whether to turn it OFF. Name the bucket in the build plan:
   `genex controller character` game). On by default; leave it on. Opt out with
   `pointerLockAim: false` only for a stated reason (a cursor-heavy UI at the core
   of play).
-- **NEVER** — cursor-core games (top-down click-to-move, tower defense, builders,
-  card/board/puzzle) and spectator/orbit showcases. These **must pass
-  `pointerLockAim: false`** — otherwise the bundled camera grabs the cursor on the
-  first click. (Touch needs nothing: pointer lock doesn't exist there and the mode
-  no-ops on coarse pointers.)
+- **Keyboard-driven games lock too** — a racer, platformer, or runner that never
+  reads the mouse still locks the pointer on the play/Start click: the cursor is
+  not a tool there, so lock it away (hidden cursor, no stray clicks, Esc = pause
+  as usual). Bundled-controller games get this for free; a hand-rolled game uses
+  the minimal lock recipe in `$genex-threejs-game-ui` (~6 lines).
+- **NEVER** — cursor-core games where the pointer IS the gameplay tool (top-down
+  click-to-move, tower defense, builders, card/board/puzzle) and spectator/orbit
+  showcases. These **must pass `pointerLockAim: false`** — otherwise the bundled
+  camera grabs the cursor on the first click. (Touch needs nothing: pointer lock
+  doesn't exist there and the mode no-ops on coarse pointers.)
 
 **Mechanism — games on the bundled controller (most games):** do NOT hand-roll
 lock handling. Aim is already enabled; the kit ships a ready-made cue overlay —
@@ -113,6 +121,36 @@ grants the permission.
 (trackpad "natural scrolling" only flips the wheel). If look feels inverted it's a
 sign bug in the rig, not a device quirk — fix the sign, don't sniff the trackpad.
 
+## The screen-direction contract
+
+Every input axis has one correct on-screen direction, for every rig, bundled or
+hand-rolled. These four invariants are testable and non-negotiable:
+
+1. Mouse/touchpad RIGHT turns the view right; mouse UP looks up (down only behind
+   an explicit invert option the player chose).
+2. `KeyD`/ArrowRight moves or turns the player toward screen-RIGHT; `KeyA`/
+   ArrowLeft toward screen-left. Same for a touch stick's +x.
+3. Drag-pan picks ONE convention — grab-the-world (terrain follows the pointer)
+   or move-the-camera — and BOTH axes obey it. One axis each is the
+   "diagonals feel twisted" bug.
+4. See the OS-setting note above: inversion is always your sign, never the device.
+
+The formula that settles every sign argument: `screenRight = cross(cameraForward, worldUp)`.
+For a Y-up world and forward `(sin yaw, 0, cos yaw)`, screen-right is
+`(-cos yaw, 0, sin yaw)`. **Warning — `(cos yaw, 0, -sin yaw)` is the LEFT
+vector** (that's `cross(worldUp, cameraForward)`), and writing it as "right" is
+the single most-shipped direction bug in generated games: two independent
+projects inverted their A/D exactly this way. Related trap: positive
+`rotation.y` turns a +Z-facing object toward +X, which is screen-LEFT from a
+chase camera behind it — so "positive yaw = turn right" is false in this basis.
+
+Never derive signs by intuition — intuition about right-handed frames is wrong
+about half the time and has been wrong in every shipped instance. Copy a
+verified pair (sign AND basis together) from
+[references/camera-rigs.md](references/camera-rigs.md), then confirm with the
+input-direction part of the smoke check: hold D and watch which way the world
+answers.
+
 ## Non-negotiable rules
 
 - Use subject dimensions to derive offsets; do not tune one fixed distance for
@@ -122,6 +160,8 @@ sign bug in the rig, not a device quirk — fix the sign, don't sniff the trackp
 - During an explicit handoff, use one interpolation stage. Do not stack a
   transition blend and a second follow smoother over the same interval.
 - Re-sync yaw/pitch from the camera when pointer lock is acquired.
+- Hand-rolled steering/pan/look math copies a verified basis from the reference
+  and passes the input-direction check — signs are never derived by intuition.
 - Update the projection matrix whenever FOV, near, far, or aspect changes.
 - Keep stars or infinite backgrounds camera-relative when large translation
   would create false parallax or precision loss.

package/templates/skills/genex-threejs-camera-direction/references/camera-rigs.md

@@ -11,6 +11,7 @@ Use this reference for scale-aware chase, side, orbit, authored-shot, pointer-lo
 - Explicit camera handoffs
 - cinematic implementation shot ownership
 - Pointer-look and movement constraints
+- Verified screen-direction bases
 - Floating origin and background handling
 - Projection and lifecycle ownership
 - Failure modes and diagnostics
@@ -166,6 +167,9 @@ yaw -= mouseDeltaX * 0.0022
 pitch -= mouseDeltaY * 0.0018
 ```
 
+Expected on screen: mouse-right orbits the view right, mouse-up tilts it up —
+verify both axes against the screen-direction contract before retuning the scales.
+
 Pitch bounds vary by flight mode. The implementation also enforces camera height above
 the ship:
 
@@ -281,6 +285,9 @@ distance = movementSpeed * dt
 
 Default speed is `9`, sensitivity `0.0023`.
 
+Expected on screen: mouse-right turns the view right, mouse-up looks up — assert
+both axes (yaw-only evidence has let inverted pitch ship).
+
 Keys are cleared on:
 
 - pointer-lock exit;
@@ -295,6 +302,61 @@ Scene-specific constraints then run after controls:
 
 Input control and spatial constraint are separate layers.
 
+## Verified screen-direction bases
+
+Copy these pairs whole — the sign and the basis are only correct TOGETHER. Each
+was derived from `screenRight = cross(cameraForward, worldUp)` and verified
+against the on-screen result; if you change one half, re-verify with the
+input-direction check instead of reasoning about it.
+
+**Chase-cam steering** (vehicle/character heading, camera behind):
+
+```text
+heading  = (sin yaw, 0, cos yaw)          // matches rotation.y for a +Z-front model
+yaw     -= steer * rate * dt              // steer: D/right = +1, A/left = -1
+position += heading * speed * dt
+camera at position - heading * dist, lookAt(position)
+```
+
+Why the minus: the camera looks along `heading`, so screen-right is
+`cross(heading, up) = (-cos yaw, 0, sin yaw)`, while `d(heading)/d(yaw) =
+(cos yaw, 0, -sin yaw)` — exactly screen-LEFT. Increasing yaw always veers the
+nose left on screen, so "D turns right" needs `yaw -=`. (Equivalently
+`yaw += steer` is correct only with heading `(-sin yaw, 0, cos yaw)` — a pair,
+never a lone sign.)
+
+**RTS / overhead pan camera** (fixed pitch, yaw-orbiting):
+
+```text
+right         = (-cos yaw, 0, sin yaw)    // pitch-independent screen-right on the ground
+forwardGround = (sin yaw, 0, cos yaw)     // into the screen along the ground
+D / ArrowRight: target += right * pan     A / ArrowLeft: target -= right * pan
+W / ArrowUp:    target += forwardGround * pan     S: target -= forwardGround * pan
+```
+
+Drag-pan, grab-the-world (terrain follows the pointer; both axes, one
+convention — `movementY` is positive DOWNWARD):
+
+```text
+target -= right * movementX * k
+target += forwardGround * movementY * k
+```
+
+Move-the-camera convention = flip BOTH signs, never one. The classic shipped bug
+writes `right = (cos yaw, 0, -sin yaw)` — that is `cross(up, forward)`, the LEFT
+vector — inverting A/D and the horizontal drag while W/S stay correct.
+
+**Pointer-look** (locked mouse driving yaw/pitch, Euler order `YXZ`):
+
+```text
+yaw   -= movementX * sensitivity          // mouse-right -> view turns RIGHT
+pitch -= movementY * sensitivity          // mouse-up    -> view tilts UP
+```
+
+Expected on screen, both axes, before any tuning: a straight-ahead landmark
+slides LEFT when the mouse moves right (the view pans right) and slides DOWN
+when the mouse moves up (the view tilts up).
+
 ## Floating origin and background handling
 
 The Saturn scene first computes a virtual camera pose, stores its orientation

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -162,7 +162,10 @@ From `@genex-ai/embed-sdk/sentry` (crash reporting; exactly these two):
 - `sentryCanvasSnapshot(canvas)` — session replay records the DOM, not the 3D
   canvas; call this once per frame at the END of the render loop so replays
   show actual gameplay. Works for BOTH WebGL and WebGPU renderers; internally
-  throttled, so calling at 60fps is fine:
+  throttled, so calling at 60fps is fine. On TOUCH devices it is a deliberate
+  no-op (and session replay/tracing sample down): each capture is a full-canvas
+  GPU readback, exactly the overhead phones get memory-killed for — mobile
+  replays are DOM-only by design, on-error replays still record everywhere:
 
 ```ts
 function animate() {

package/templates/skills/genex-threejs-game-feel/SKILL.md

@@ -37,7 +37,10 @@ no matter how good it looks.
   unlocked drag-to-turn camera feels imprecise no matter how tight the numbers
   are. The bucket rule + the bundled `FollowCamera` aim mode live in
   `$genex-threejs-camera-direction`; on the bundled controller it's ON by default
-  (with a ready-made cue), not hand-rolled events.
+  (with a ready-made cue), not hand-rolled events. Direction is half of it: a
+  movement key or look axis whose on-screen direction contradicts its label is a
+  defect, not a tuning issue — the screen-direction contract and verified bases
+  are in `$genex-threejs-camera-direction`.
 
 ## Movement: snappy beats realistic
 

package/templates/skills/genex-threejs-game-ui/SKILL.md

@@ -27,7 +27,7 @@ in another.
 | Pause | always — opens on the Escape key | 1 — menu backdrop under a dark overlay |
 | Fail / retry | always | 1 — a *graded* variant of the menu screen |
 | Win / next | always | 1 — graded variant, warm |
-| Settings | when there is anything to set | 1 |
+| Settings | always — every game carries the Quality picker (Auto/Low/Medium/High, `$genex-threejs-adaptive-quality`), plus whatever else it has to set | 1 |
 | Lobby / waiting | multiplayer only | 1 over the menu backdrop |
 | HUD | always | 2 — generated sprite HUD (`$genex-ai-hud`), enqueued at this gate for EVERY game; plain CSS is the placeholder until the sprites land, never the final HUD |
 
@@ -250,8 +250,15 @@ document.addEventListener("keydown", (e) => {
   so ALSO keep the pointer-lock-loss → pause path (`pointerlockchange`: if
   unlocked while `playing`, `setPhase("paused")`). Escape then always pauses; it
   only *also* drops fullscreen on browsers without the lock — unavoidable there.
-- **Only for immersive/pointer-lock games.** A top-down or menu-driven game never
-  captures the mouse and has no window to shrink — skip all of this.
+- **Skip Keyboard Lock + fullscreen only when the cursor stays a tool.**
+  Cursor-core / top-down / menu-driven games never capture the pointer — skip
+  `enterImmersive` and Keyboard Lock entirely. But ANY game that locks the
+  pointer during play — aim games AND keyboard-only racers/platformers/runners
+  under the lock-or-tool rule (next section) — keeps the Escape → pause path and
+  the `pointerlockchange` fallback (if unlocked while `playing`, pause): without
+  it, Esc frees the cursor while the game keeps running. Keyboard-only games may
+  still skip Keyboard Lock + fullscreen; the lock + pause/resume path is the
+  non-negotiable part.
 - **Dashboard embed:** no setup needed — the platform's game frame grants keyboard
   lock (and pointer lock + fullscreen), so Escape-to-pause works the same inside
   `/world/` + `/draft/` as it does standalone (`<slug>.genex.technology`).
@@ -261,6 +268,28 @@ menu — trackpads feel slower than mice, so let the player tune it. On the bund
 camera the setter is live: `slider.oninput = () => { followCam.aimSensitivity = +slider.value; };`
 (radians per pixel; default `0.0023`, a usable range is ~`0.0008`–`0.005`).
 
+## The cursor during play: locked or a tool
+
+During play the OS cursor is either the gameplay tool (cursor-core: click-to-move,
+tower defense, builders, card/board — it stays visible, that's correct) or it is
+**locked away — including keyboard-only games** (racer, platformer, runner): an
+arrow parked over the action for the whole session is a shipped defect. Games on
+the bundled `FollowCamera` get the lock free (on by default). A hand-rolled game
+locks with ~6 lines, reusing this section's Escape flow:
+
+```ts
+// In the Play/Start/Resume CLICK handler (lock needs a user gesture):
+canvas.requestPointerLock?.();          // hides the cursor, focuses the game
+// Already in the Escape recipe above: pointerlockchange → if unlocked while
+// playing, pause; the Resume click re-locks. Keyboard games need nothing more —
+// no reticle, no aim code; the lock just parks the cursor.
+```
+
+If the lock is genuinely unavailable (a third-party embed without
+`allow="pointer-lock"`), fall back to hiding the idle cursor over the canvas:
+`canvas.style.cursor = "none"` after ~2s without `pointermove`, restored
+instantly on move. Menus and pause screens always keep their cursor.
+
 ## The loader
 
 The loader is the first thing every player sees — a bare "Loading… 3/5" over
@@ -372,11 +401,13 @@ Order the HUD by what the player loses the game for ignoring:
   `vUv` grain shimmers.
 - **Desktop first.** Verify at desktop sizes and survive window resizes
   without clipping; don't design phone layouts or test mobile viewports unless
-  the user asks. Exception: touch *input* is wired by default when a recipe
-  fits — a bundled controller's built-in touch controls, or the touch kit +
-  recipes in `$genex-threejs-touch-controls` — behind
-  `navigator.maxTouchPoints > 0`, invisible on desktop, so the shared link
-  isn't dead on a phone (skipping needs a one-line reason, not silence).
+  the user asks. Two exceptions ship by default precisely BECAUSE you don't
+  test on phones: touch *input* when a recipe fits — a bundled controller's
+  built-in touch controls, or the touch kit + recipes in
+  `$genex-threejs-touch-controls` — behind `navigator.maxTouchPoints > 0`,
+  invisible on desktop (skipping needs a one-line reason, not silence); and
+  the adaptive-quality tier at boot (`$genex-threejs-adaptive-quality`), which
+  keeps the shared link from being a dead OR crashing link on a phone.
 
 ## Wire UI to game state, never the reverse
 
@@ -399,6 +430,9 @@ architecture and consume the shared style brief.
 - HUD sprites never enqueued at the gate — the placeholder CSS shipped as the
   final HUD.
 - No pause screen, or a pause that isn't bound to Escape.
+- The OS arrow parked over the action for the whole session in a keyboard-driven
+  game (the cursor is either a gameplay tool or locked away — see the cursor
+  section).
 - A style brief whose fonts were never actually loaded (a system-stack display
   font at runtime).
 - A micro-element (reticle, cue, toast, damage number) left as default CSS

package/templates/skills/genex-threejs-image-pipeline/SKILL.md

@@ -43,6 +43,11 @@ ownership boundaries between whole-scene and effect-local graphs.
 - Build pass toggles and effect-only views before tuning.
 - UI rendered in the same target needs an explicit protection strategy.
 - Do not load all atomic post skills by default. Route only the effects actually requested.
+- Budget the pipeline per device tier (`$genex-threejs-adaptive-quality`):
+  phone pixel budget ≈ 1,000,000 px at DPR ≤ 1.25–1.5, desktop ≈ 1,650,000 px —
+  every full-res pass target multiplies that cost, so phone tiers run the light
+  post level and per-pass resolution scales (0.4–0.5 DPR blurs) are the norm,
+  not an optimization.
 
 ## Routing boundary
 

package/templates/skills/genex-threejs-image-pipeline/references/image-pipeline.md

@@ -2,7 +2,7 @@
 
 Use this reference to compose shared scene buffers, lighting effects, atmosphere, bloom, exposure, tone mapping, grading, and feature-local render targets with explicit ownership.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-lighting-design/SKILL.md

@@ -107,7 +107,11 @@ kill-switch diagnostic.
   whole rig after a tone-mapping change is self-inflicted.
 - Never repair unbalanced light ratios with exposure — fix the lights.
 - Flicker from elapsed time, never per-frame randomness.
-- Dispose lights and their shadow maps with the level that spawned them.
+- Dispose lights and their shadow maps with the level that spawned them — and
+  the rest of the level with them: traverse the outgoing scene and dispose
+  geometry, materials, AND textures separately (three frees nothing; material
+  dispose does not touch textures). Leaked levels march phones toward the
+  OS memory kill — `$genex-threejs-adaptive-quality` owns the budget watch.
 - The rig must read with post off: time of day and where-to-go, before bloom.
 
 ## Routing boundary

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -536,7 +536,13 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `stateRaw` is the raw latest (hit-tests, discrete values). A reconnect-grace seat remains in this
   map with `connected: false`. `avatarUrl` is that player's verified VRM pick (server-set, `''`
   when unknown) — in a VRM-lane game render each remote with
-  `loadVrm(p.avatarUrl || "./assets/avatar.vrm")`; never publish avatar URLs through `me.set`.
+  `loadVrmClone(p.avatarUrl || "./assets/avatar.vrm")` (the vendored loader's shared-GPU clone:
+  N remotes share one set of geometry/textures instead of re-parsing per player — retarget
+  clips once on `loadVrmClone.base(url)` and play them on each clone's own mixer); never
+  publish avatar URLs through `me.set`. On phone tiers, animate and fully draw only the
+  nearest `tier.remoteAvatarCap` remotes (`$genex-threejs-adaptive-quality`) — freeze the
+  mixer and billboard or hide the rest; a room allows up to 64 players and 64 live avatars
+  is a real phone memory kill on its own.
 - `room.activePlayers` — the connected-only subset of `room.players`; use its size for live quorum.
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
   - `claim(id)` — **legacy** optimistic request. It flips local ownership immediately and is corrected

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -275,9 +275,12 @@ room.me.set({
 
 // Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
 // Build each remote's visual from THEIR OWN model: in a VRM-lane game that is
-// loadVrm(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the relay
-// replicates ('' = unknown → fall back; deepDispose the model on 'leave'). Never reuse your
-// own avatar file for every remote. Position/rotation from smoothed state; animation from the
+// loadVrmClone(pl.avatarUrl || "./assets/avatar.vrm") — the verified per-player pick the
+// relay replicates ('' = unknown → fall back; deepDispose the clone on 'leave'). The clone
+// shares parsed GPU geometry/textures across remotes with the same file (most rooms: all of
+// them) — retarget clips once against loadVrmClone.base(url).vrm and drive each clone's own
+// AnimationMixer. Never reuse your own avatar OBJECT for a remote (clones, not references).
+// Phone tiers animate only the nearest tier.remoteAvatarCap remotes (adaptive-quality skill). Position/rotation from smoothed state; animation from the
 // synced flags via the avatar's own update(flags, dt). The character-controller skill's
 // animations reference owns the flag set.
 const pl = room.players.get(id)!;

package/templates/skills/genex-threejs-physics-rapier/references/colliders-from-assets.md

@@ -26,6 +26,7 @@ already resolved — constructing a collider before WASM init throws.
 | tall dynamic props, posts | `capsuleCollider` / `cylinderCollider` | stable standing shapes |
 | pickups, triggers, zones | any shape + `{ sensor: true, mass: 0 }` | overlap events, no contact forces |
 | the player, cars, drones | none of the above — `npx genex controller` | controllers own their collider recipes |
+| any prop on a PHONE tier (`$genex-threejs-adaptive-quality`) | prefer `cuboidCollider`/hull over trimesh | trimesh contacts scale with triangle count — a phone CPU/memory tax; keep trimesh for static level geometry only |
 
 ## Explicit primitive helpers
 

package/templates/skills/genex-threejs-screen-space-ambient-occlusion/references/ambient-occlusion.md

@@ -2,7 +2,7 @@
 
 Use this reference for a bounded-cost WebGPU/TSL ambient-visibility pass with half-resolution horizon integration, bent normals, bilateral reconstruction, and directional ambient tint.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-shadow-systems/SKILL.md

@@ -12,6 +12,12 @@ and shadows shimmer, swim, or run out of coverage.
 
 Use a single shadow map only when its receiver region is genuinely bounded. For large moving views, make shadow coverage an explicit spatial hierarchy.
 
+**Phone budgets ride the quality tier** (`$genex-threejs-adaptive-quality`):
+shadow maps ≤1024² on phones (512² on the low tier — a 4096² map alone is
+~67 MB of the phone's whole GPU budget), at most 2 cascades where desktop runs
+4, and `shadowMap.autoUpdate = false` for static scenes (re-render on demand:
+a shadow pass is a full extra scene render every frame otherwise).
+
 ## Cached clipmap workflow
 
 1. Define concentric light-space square levels.

package/templates/skills/genex-threejs-shadow-systems/references/shadow-systems.md

@@ -2,7 +2,7 @@
 
 Use this reference for stable directional shadows across a large procedural scene using committed light-space centers, texel snapping, bounded refresh budgets, cross-level blending, and targeted invalidation.
 
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project.
+> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
 
 ## Contents
 

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -15,11 +15,12 @@ map, execution order, and acceptance gate.
 
 | Work needed | Load |
 | --- | --- |
-| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, floating origins | `$genex-threejs-camera-direction` |
+| shot composition, chase/side/orbit rigs, camera handoffs, projection ownership, pointer look, mouse-aimed action (shooter, FPS/first-person, sniper, turret, crosshair/reticle), mouse-look, hand-rolled steering/pan/look input signs (screen-direction contract), floating origins | `$genex-threejs-camera-direction` |
 | on-foot player movement: walk/run/jump/crouch, third-person character, slopes, stairs, moving platforms, personal VRM animation, directional locomotion, transitions, action motion | `$genex-threejs-character-controller` |
 | a custom generated playable humanoid or Meshy animation coverage beyond UAL: reference-informed A-pose concepts, explicit candidate + 10k-remesh approvals, exact action IDs, same-rig adapter | `$genex-ai-character` + `$genex-threejs-character-controller` |
 | the player drives or flies something: cars, drones, vehicle physics, gearbox, enter/exit between character and vehicle | `$genex-threejs-vehicle-controllers` |
 | playable on phones: touch/mobile input for any game — joystick, virtual buttons, drag zones, per-genre touch recipes, rotate-device overlay — wired by default for every NEW game when a recipe fits (skip with a one-line reason) | `$genex-threejs-touch-controls` |
+| phone-survivable rendering — device tiers, DPR/shadow/post budgets, the runtime quality governor, per-tier asset rungs for generated skyboxes/textures, the Quality picker, dispose-on-swap discipline — **mandatory for every game at boot wiring** | `$genex-threejs-adaptive-quality` |
 | anything falls, collides, gets pushed, or needs physics: Rapier world setup, colliders for meshes and GLBs, collision events | `$genex-threejs-physics-rapier` |
 | launch and docking timelines, procedural transform phases, springs, staging, rotating-frame alignment, debris motion | `$genex-threejs-procedural-animation` |
 | reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
@@ -58,6 +59,14 @@ map, execution order, and acceptance gate.
 mentions sign-in, saves, progress, per-player state, a persistent world, or
 leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
+**Adaptive quality is mandatory routing:** every game wires the device tier at
+boot — `$genex-threejs-adaptive-quality` (three lines: `detectTier()` before the
+renderer, tier-capped `setPixelRatio`, the governor in the loop; generated
+skyboxes/textures load through their rungs). Phones enforce a hard GPU-memory
+kill desktops never show you; the tier is what keeps a phone boot alive while
+desktop keeps the full look. This is a completion gate like the post stack —
+cheap to wire, not a new testing burden (desktop-only verification stands).
+
 **Character-animation routing:** use the existing VRM + UAL character
 controller by default. Use `npx genex character` when the game needs a custom
 generated humanoid or an action unavailable in UAL. Before generating a Meshy
@@ -122,7 +131,11 @@ stack this game ships — read off the concept frame's OWN look (the grade, bloo
 level, haze, grain it already shows) and which post the 2–3 AAA references lean
 on, not a default single bloom; ONE built render-pass effect is the FLOOR
 against no-post for EVERY game, never the target — ship the richness the concept
-implies (the UI vignette div or a CSS canvas filter does not count;
+implies. The floor is TIER-AWARE (`$genex-threejs-adaptive-quality`): on phone
+tiers it is satisfied by the built tone-mapping/output pass with the light
+additions the tier allows (FXAA/vignette), while the full named stack remains
+the desktop floor — never ship the heavy stack undropped to phones (the UI
+vignette div or a CSS canvas filter does not count on any tier;
 `$genex-threejs-image-pipeline` owns ordering when 2+ compose), a decision for
 **every primitive surface** the game builds — walls, barriers, kerbs and
 platforms each get a real texture or a **shader** where that surface wants motion
@@ -204,8 +217,16 @@ concept-driven — a richer first build beats a grey-box one.
   drag-orbit (`pointerLockAim: false`) only with a stated reason (e.g. a
   cursor-heavy UI core). **Never** — cursor-core games (click-to-move, tower
   defense, builder, card/puzzle), orbit showcases, touch-only; these MUST pass
-  `pointerLockAim: false`. The mechanism and the full aim contract live in
-  `$genex-threejs-camera-direction`.
+  `pointerLockAim: false`. Keyboard-only games (racer, platformer) lock too —
+  the cursor is either a gameplay tool or locked away during play. The mechanism
+  and the full aim contract live in `$genex-threejs-camera-direction`.
+- Input direction (always — every game that moves with keys or pointer):
+  D/ArrowRight must move or turn the player screen-RIGHT, mouse-right must turn
+  the view right, drag-pan axes share one convention. The screen-direction
+  contract and verified copy-paste bases live in
+  `$genex-threejs-camera-direction` — hand-rolled steering/pan/look math copies
+  one instead of deriving signs, and the smoke check's input-direction pass
+  verifies it.
 - Art direction follows THIS game's concept. The style examples inside skills
   are examples, not defaults — never default to neon/cyberpunk/synthwave (or any
   other single register) unless the concept calls for it.
@@ -222,7 +243,7 @@ concept-driven — a richer first build beats a grey-box one.
 - Use `$genex-threejs-visual-validation` before declaring graphics/procedural-system
   work done. **Game fast path:** for game tasks that loaded no procedural/visual-system
   skill, done = a screenshot plus an interaction smoke check (load the page, press each
-  control, see the visible response) — don't run the full diagnostic gate — PLUS the
+  control, see the visible response in its labeled direction) — don't run the full diagnostic gate — PLUS the
   floors from the routing-map's acceptance gate: the generated sprite HUD wired in
   (not the CSS placeholder), pause on Escape, the branded loader with its key-art
   background, the brief's fonts actually loaded, the renderer baseline + at least one