@genex-ai/cli-demo 0.71.0 → 0.74.0-dev.190

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

@@ -0,0 +1,141 @@
+---
+name: genex-threejs-adaptive-quality
+description: Make a Genex Three.js game phone-survivable with the vendored adaptive-quality kit — device-tier detection, tier-budgeted renderer settings, a runtime governor that steps quality down before phones run out of memory, per-tier asset rungs for generated skyboxes/textures, and a Quality picker in settings. Load for every game at boot wiring time, and whenever a game is heavy, crashes on phones, or gets flagged desktop-only.
+---
+
+# Genex Three.js Adaptive Quality
+
+Phones enforce a hard GPU-memory ceiling desktops don't have: iOS silently
+kills the page when a game allocates too much, and the kill arrives at BOOT —
+exactly when a skybox, models, and the post stack all decode at once. This
+skill wires the vendored quality kit so the game boots conservatively on
+phones, steps quality UP when the device proves smooth, and never gets uglier
+on desktop. **You can recover from ugly; you cannot recover from a killed
+page.**
+
+This is a completion gate like the post stack: every game wires the tier at
+boot before it is called done. It costs three lines, not a testing burden —
+you still verify on desktop only.
+
+## Install
+
+```bash
+npx genex controller quality
+```
+
+Installs `src/controllers/quality/{tier.ts, governor.ts, pick-asset.ts}` —
+game-owned code, edit freely.
+
+## Wire the tier at boot (before renderer construction)
+
+```ts
+import { detectTier } from "./controllers/quality/tier.ts";
+import { QualityGovernor } from "./controllers/quality/governor.ts";
+
+const tier = detectTier(); // phone-low | phone | desktop; manual Quality setting wins
+const renderer = new THREE.WebGLRenderer({ antialias: tier.antialias });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap));
+```
+
+The tier owns every budget decision: `dprCap` (1.5 on phones — the single
+biggest framebuffer lever), `antialias` (off on phones; it is fixed at context
+creation and can never change live), `shadowMapSize` (1024 phone / 2048
+desktop), `postLevel` (`'light'` = tone mapping + cheap passes on phones;
+`'full'` = the named stack on desktop), `particleScale`, `drawDistanceScale`,
+`frameCap`, and `remoteAvatarCap` for multiplayer. The exact ladder and which
+knobs may change at runtime vs load time vs never: [references/adaptive-quality.md](references/adaptive-quality.md).
+
+## Wire the governor (runtime — phones throttle over minutes)
+
+```ts
+const governor = new QualityGovernor(tier, {
+  setDprScale: (m) => renderer.setPixelRatio(Math.min(window.devicePixelRatio, tier.dprCap * m)),
+  setPostEnabled: (on) => (composerEnabled = on),
+  setDrawDistanceScale: (m) => (scene.fog!.far = baseFogFar * tier.drawDistanceScale * m),
+}, renderer);
+
+// In the render loop, with the same performance.now() delta the loop already computes:
+governor.frame(deltaMs);
+```
+
+Sustained slow frames step down (DPR ×0.8 → post off → draw distance →
+30 fps cap); twenty smooth seconds step back up; a knob that failed twice
+stays down for the session. It keeps governing forever — thermal throttling
+arrives at minute eight, not second thirty. It also pauses judgment when the
+tab is hidden and publishes memory counts the platform's crash telemetry
+reads; pause your own loop and audio on `visibilitychange` too.
+
+## Generated assets: load through the rungs
+
+Generated skyboxes are 8192×4096 — about 178 MB decoded, over half a phone's
+whole budget in one texture. Every generated image asset ships with downscale
+rungs; phones must load through them:
+
+```ts
+import { detectTier } from "./controllers/quality/tier.ts";
+import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
+
+const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
+  new THREE.TextureLoader().loadAsync(u),
+);
+```
+
+Desktop loads the original, phones the `@2048` rung (~11 MB), and a missing
+rung falls back to the original — never a broken boot. The `$genex-ai-skybox`
+and `$genex-ai-texture` skills show the wiring in place.
+
+## Quality picker in settings
+
+The pause/settings screen (see `$genex-threejs-game-ui`) always carries a
+Quality entry: **Auto / Low / Medium / High**, wired to
+`setQualitySetting(...)` from `tier.ts` + a reload or re-tier. Persisted
+per-device in localStorage on purpose — quality is a property of the phone,
+not the player's account. Default Auto.
+
+## Budgets that ride the tier (not separate rules)
+
+- Shadows: `tier.shadowMapSize`, `shadow.autoUpdate = false` for static scenes,
+  at most 2 cascades on phones (`$genex-threejs-shadow-systems`).
+- Post: phone floor is a BUILT tone-mapping/output pass (`postLevel: 'light'`
+  adds FXAA/vignette); SSAO, volumetrics, and DoF are desktop-tier only
+  (`$genex-threejs-skill-router` owns the floor wording).
+- Particles/scatter: multiply counts by `tier.particleScale`; render heavy
+  transparency at half resolution and upsample.
+- Animation: distant mixers update at 1/2–1/4 rate; multiplayer remotes above
+  `tier.remoteAvatarCap` billboard instead of animating
+  (`$genex-threejs-multiplayer`).
+- Physics: phone tiers prefer hull/cuboid colliders for props — trimesh only
+  where gameplay demands it (`$genex-threejs-physics-rapier`).
+- Shaders: default `mediump` (iOS exception: float-texture sampling needs
+  `highp sampler2D`); precompile with `renderer.compileAsync(scene, camera)`
+  during the loader screen so first-frame jank doesn't read as a stall; skip
+  max anisotropy on phones.
+- Disposal: level swaps traverse the outgoing scene and dispose geometry,
+  materials, AND textures (three never frees them for you); watch
+  `renderer.info.memory` while testing — if textures/geometries climb across
+  swaps, you leak toward the kill.
+
+## WebGPU games
+
+The scaffold ships WebGL and stays the default; if this project already uses
+`WebGPURenderer`, keep it (never switch renderers mid-project). Context loss
+differs: WebGL fires `webglcontextlost` events; WebGPU exposes a
+`device.lost` promise — attach a handler that pauses the loop and rebuilds,
+mirroring the scaffold's WebGL pattern. All tier knobs apply identically
+except `antialias` (WebGPU MSAA is per-render-target and CAN change at
+runtime).
+
+## Failure conditions
+
+- Renderer constructed before `detectTier()` → context-creation knobs
+  (antialias) are locked wrong for the session. Tier first, renderer second.
+- Governor wired to context-creation flags → no-op at best. Runtime knobs
+  only: DPR, post toggles, distances, frame cap.
+- Skybox loaded with a bare `TextureLoader.loadAsync(SKYBOX_URL)` on a game
+  that targets phones → ~178 MB decoded; route it through
+  `loadTextureWithFallback`.
+- Quality stepping on every spike → shader compiles read as slowness. The
+  governor requires SUSTAINED slow windows; do not shorten them.
+- Testing quality tiers by resizing the desktop window → tiers key off touch +
+  OS, not viewport. Trust desktop verification plus the preflight report
+  `genex preview` prints.

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 —
@@ -65,6 +73,7 @@ character`) to `onAimChange` and you get the reticle + "click to aim" cue for fr
       domElement: renderer.domElement,
       onAimChange: cue.onAimChange,
     });
+    followCam.setPaused(getPhase() !== "playing"); // park aim if the game boots on a menu/loader
 
 Cursor-core game? Pass `pointerLockAim: false` instead and skip the cue. Want a
 custom HUD? Read `onAimChange` yourself — `{ state }` is one of `locked` /
@@ -86,12 +95,17 @@ grants the permission.
 
 1. Two states only: locked = playing, unlocked = menu/paused. "Unlocked but
    gameplay continues" is the imprecise-aim defect in disguise.
-2. Opening any menu (inventory/shop/dialog): exit the lock
+2. Opening any menu — the BOOT/main menu included — parks aim: exit the lock
    (`followCam.setPaused(true)`), cursor returns, gameplay input pauses. Menu
-   keys are Tab/I/E — never Esc.
+   keys are Tab/I/E — never Esc. The one true wiring is the phase binding
+   `followCam.setPaused(phase !== "playing")` applied on phase transitions,
+   never per frame: an unguarded per-frame resume once re-requested the lock
+   every frame, and any menu click's ~5s of transient activation then locked
+   the pointer over the open menu.
 3. Closing a menu re-locks INSIDE the close click/keypress handler
-   (`followCam.setPaused(false)`) — the browser requires a user gesture, so
-   menus close by click/keypress, never by timeout.
+   (`followCam.setPaused(false)` — the phase binding's `setPhase("playing")`
+   in the Play/Resume click does exactly this) — the browser requires a user
+   gesture, so menus close by click/keypress, never by timeout.
 4. Esc is the browser's release valve (you can't intercept it; Chrome enforces
    a re-lock cooldown) → treat Esc as pause: show the overlay with a
    "click to resume" button.
@@ -108,11 +122,45 @@ grants the permission.
    Chrome's post-Esc cooldown) fires `onAimChange` with reason `needs-gesture` and
    keeps the "click to aim" cue up; the next click or keypress re-locks. Never
    retry on a timer.
+10. The bundled camera OWNS the lock: never call `document.exitPointerLock()` or
+    `canvas.requestPointerLock()` yourself alongside it — raw calls desync
+    `aimState` and the cue. Everything routes through `setPaused` (which is
+    idempotent — a same-value call is a no-op).
 
 **Not an OS setting:** pointer `movementX/movementY` is never inverted by the OS
 (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 +170,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-character-controller/references/wiring.md

@@ -149,9 +149,15 @@ Want a custom HUD? Read `onAimChange: ({ state }) => …` yourself instead of th
 - **Opt out:** cursor-core games (RTS, tower defense, card, builder) pass
   `pointerLockAim: false` — the camera then stays drag-orbit and never grabs the
   cursor.
-- **Menus / vehicles:** `followCam.setPaused(true)` when a menu opens or the
-  player starts driving; `followCam.setPaused(false)` INSIDE the closing
-  click/keypress handler (re-lock needs a user gesture). Aim is on-foot only.
+- **Menus / vehicles:** the BOOT/main menu counts as a menu — park aim from the
+  first frame. The one true wiring is the phase binding
+  `followCam.setPaused(phase !== "playing")` applied on phase TRANSITIONS
+  (inside `setPhase()`), never driven from the render loop: `setPaused` is
+  idempotent, but a per-frame resume once locked the pointer over an open menu
+  the moment a menu click granted transient activation. The Play/Resume click's
+  transition doubles as the required user gesture for the re-lock. Vehicles:
+  combine conditions (`phase !== "playing" || activeId !== CHARACTER_ID`) — aim
+  is on-foot only.
 - **First-person:** the same mode plus `minDistance`/`maxDistance` ≈ 0.1, an
   eye-height target fed to `moveTo`, `avatar.visible = false`, and
   `controller.setLockForward(true)`.

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