@genex-ai/cli-demo 0.17.0 → 0.18.0

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -18,13 +18,20 @@ already did, and stacking two smoothers adds visible lag.
 ```ts
 import * as THREE from "three";
 import { connect } from "@genex-ai/multiplayer";
+import { waitForPlayer, getColyseusAuth } from "@genex-ai/embed-sdk";
 import { GENEX } from "./genex.config";
 
 // Your published state — EVERY synced field, including discrete ones like hp. `me.set`
 // replaces your state wholesale, so the tick must send all of these every time (below).
 type S = { x: number; z: number; q: number[]; hp: number };
 
-const room = await connect<S>({ url: GENEX.colyseusUrl, room: GENEX.slug });
+const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — never waitForAuth()
+const room = await connect<S>({
+  url: GENEX.colyseusUrl,
+  room: GENEX.slug,
+  name: user.name,
+  auth: getColyseusAuth()!,  // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
+});
 
 // --- local player: input mutates this; we render yourself from it (zero latency) ---
 // This ONE object holds everything you sync. Keep hp/ammo/etc. here too — see the warning below.
@@ -132,8 +139,11 @@ Rules that keep it correct:
 
 ## Host authority (scores, rounds, world)
 
-One client is `room.host` (the first joiner, re-elected on leave). Let only the host write agreed
-state, so there's a single source of truth — no "who increments the score" races:
+One client is `room.host` — the earliest **signed-in** player (guests host only while no account
+is present), and the host can change on **join** as well as leave: the first account entering a
+guest-hosted room takes over. Always react to `on('host')` / read `isHost` in your loop, never
+once at startup. Let only the host write agreed state, so there's a single source of truth — no
+"who increments the score" races:
 
 ```ts
 function updateHud() {
@@ -147,8 +157,9 @@ function goal(team: "a" | "b") {
 room.on("host", () => {/* host migrated — the new host takes over writing */});
 ```
 
-`room.on('shared', …)` fires when a key is **first set**, not on every change — for a live value,
-read `room.shared.get(...)` in your loop (as `updateHud` does) rather than relying on the event.
+`room.on('shared', …)` fires on every **distinct** change of a key (a set to the same value is
+de-duped) — but for a value you render every frame, read `room.shared.get(...)` in your loop (as
+`updateHud` does) rather than wiring render state through the event.
 
 ## Custom events (shots, emotes, chat)
 

package/templates/skills/genex-threejs-physics-rapier/SKILL.md

@@ -62,7 +62,8 @@ physics.onBeforeStep(() => {
 const clock = new THREE.Clock();
 renderer.setAnimationLoop(() => {
   physics.step(clock.getDelta()); // fixed substeps + mesh sync + events
-  // camera follow, animation mixers — render-delta work stays OUT here
+  // camera follow, mixers, HUD go HERE (render-delta work, after the step) —
+  // never inside onBeforeStep above
   renderer.render(scene, camera);
 });
 ```

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

@@ -179,7 +179,7 @@ reference).
 ## End-to-end: a genex model prop
 
 ```ts
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 import { collidersFromObject } from "./controllers/shared/colliders.ts";
 
 const loader = new GLTFLoader();

package/templates/skills/genex-threejs-procedural-animation/references/procedural-motion.md

@@ -188,8 +188,8 @@ shot. That is a presentation-aware choice, not a physical rule.
 Docking phases:
 
 ```text
-Endurance spin = 3.15 rad/s
-Ranger spin-up = 6.5 s
+station spin = 3.15 rad/s
+shuttle spin-up = 6.5 s
 approach starts = 4.0 s
 approach duration = 14.5 s
 dock settle = 3.0 s
@@ -201,7 +201,7 @@ dock radial offset = 0.35
 Every phase uses a named `smoothstepRange(start, end, time)`. The sequence does
 not hide all timing in one normalized zero-to-one value.
 
-Endurance:
+The rotating station:
 
 ```text
 currentSpinRate = lerp(3.15, 0, spinDownT)
@@ -209,14 +209,14 @@ spinAngle += currentSpinRate * dt
 orientation = baseOrientation * rotation(localForward, spinAngle)
 ```
 
-The docking frame is recomputed from the newly rotated Endurance every frame.
+The docking frame is recomputed from the newly rotated station every frame.
 
 ## Docking-frame decomposition
 
 At approach start:
 
 ```text
-offset = rangerPosition - dockPort
+offset = shuttlePosition - dockPort
 parallel = dot(offset, dockAxis)
 radialVector = offset - dockAxis * parallel
 radialDistance = length(radialVector)
@@ -250,7 +250,7 @@ lateral error.
 
 ## Spring convergence and terminal lock
 
-Ranger position follows target through a vector spring:
+The shuttle position follows target through a vector spring:
 
 ```text
 acceleration =
@@ -269,7 +269,7 @@ the docking axis:
 
 ```text
 alignment = quaternionFromUnitVectors(localUp, -dockAxis)
-spin = quaternionAround(dockAxis, rangerSpinAngle)
+spin = quaternionAround(dockAxis, shuttleSpinAngle)
 orientation = spin * alignment
 ```
 
@@ -279,7 +279,7 @@ can retain imperceptible but destabilizing residual motion.
 
 ## Peeling and released debris
 
-Endurance debris has two states.
+Station debris has two states.
 
 Attached peel:
 

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-screen-space-ambient-occlusion
-description: Implement screen-space ambient occlusion for Genex Three.js games. Use for GTAO-style horizon sampling, bent normals, contact grounding, depth reconstruction, bilateral upsampling, temporal smoothing, halo diagnosis, and AO that supports readable form.
+description: Implement screen-space ambient occlusion for Genex Three.js games. Use for GTAO-style horizon sampling, bent normals, contact grounding, depth reconstruction, bilateral upsampling, halo diagnosis, and AO that supports readable form.
 ---
 
 # Genex Three.js Screen-Space Ambient Occlusion

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

@@ -2,6 +2,8 @@
 
 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.
+
 ## Contents
 
 1. Gather budget and depth convention

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

@@ -1,10 +1,15 @@
 ---
 name: genex-threejs-shadow-systems
-description: Implement stable shadow systems for Genex Three.js games. Use for large worlds, directional cascades, cached clipmaps, terrain shadows, city scenes, moving cameras, targeted invalidation, quality tiers, texel stabilization, and readable contact shadows.
+description: Implement stable shadow systems for Genex Three.js games. Use for large worlds, directional cascades, cached clipmaps, terrain shadows, city scenes, moving cameras, targeted invalidation, texel stabilization, and readable contact shadows.
 ---
 
 # Genex Three.js Shadow Systems
 
+**When NOT to load this:** for a bounded scene (an arena, a room, a small level),
+three.js's default `shadowMap` on one directional light with a tight shadow
+frustum is enough — skip this skill. Load it when the camera roams a large world
+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.
 
 ## Cached clipmap workflow

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

@@ -2,6 +2,8 @@
 
 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.
+
 ## Contents
 
 1. Representation and defaults

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

@@ -28,8 +28,8 @@ map, execution order, and acceptance gate.
 | planets, terrain, craters, biome fields, coastlines, spherical detail | `$genex-threejs-procedural-planets` |
 | sky scattering, planetary shells, depth-based aerial perspective | `$genex-threejs-atmosphere-aerial-perspective` |
 | weather-driven raymarched clouds and cloud shadows | `$genex-threejs-volumetric-clouds` |
-| FFT oceans, hybrid FFT/Gerstner clear water, stylized above/below ocean optics, spectral cascades, choppy derivatives, Jacobian whitecaps | `$genex-threejs-spectral-ocean` |
-| authored analytic waves, bounded heightfield pools, object ripples, differential-area caustics, ray-traced pool volume optics, shared normals, heuristic refraction, fallback absorption, crest foam | `$genex-threejs-water-optics` |
+| hero open-water FFT oceans (expensive — only when open water IS the game): spectral cascades, hybrid FFT/Gerstner clear water, choppy derivatives, Jacobian whitecaps | `$genex-threejs-spectral-ocean` |
+| **default water**: an ocean, sea, lake, river, or pool the game plays on or around — authored analytic waves, bounded heightfield pools, object ripples, differential-area caustics, shared normals, heuristic refraction, fallback absorption, crest foam | `$genex-threejs-water-optics` |
 | falling snow, snow accumulation, model snow caps, wet asphalt puddles, procedural ripple normals, splash flipbooks, rain streaks, shared weather envelopes, surface wetness | `$genex-threejs-precipitation-surfaces` |
 | curved-ray black holes, accretion disks, wormholes | `$genex-threejs-raymarched-space-effects` |
 | particles, trails, plasma, shockwaves, layered event effects | `$genex-threejs-procedural-vfx` |
@@ -40,7 +40,16 @@ map, execution order, and acceptance gate.
 | eye adaptation, tone mapping, LUT grading, output color | `$genex-threejs-exposure-color-grading` |
 | shared depth/normal/velocity ownership and multi-pass ordering | `$genex-threejs-image-pipeline` |
 | fixed-view diagnostics, seed sweeps, temporal and budget evidence | `$genex-threejs-visual-validation` |
+| HUD, menus, pause/win/lose screens, score and health displays, overlays, loading screens, on-screen text and buttons, UI state flow | `$genex-threejs-game-ui` |
+| the game works but feels flat, floaty, or unresponsive: input response, acceleration curves, camera shake, hit feedback, hitstop, cooldowns, difficulty ramp, fail/retry loop | `$genex-threejs-game-feel` |
 | realtime multiplayer: movement sync, a shared ball/NPC, host-run scores/enemies, shots/emotes, persistence | `$genex-threejs-multiplayer` |
+| player identity, sign-in, guests, saves/progress, per-player state, a shared persistent world, leaderboards — **mandatory for every game** | `$genex-threejs-embed-auth` |
+
+**Identity is mandatory routing:** every Genex game ships with the embed SDK — load
+`$genex-threejs-embed-auth` unconditionally before writing boot code (it wires
+`initEmbed(...)` and the `waitForPlayer()` gate), and route to it whenever the task
+mentions sign-in, saves, progress, per-player state, a persistent world, or
+leaderboards. Multiplayer auth (`getColyseusAuth`) comes from it too.
 
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading
 `$genex-threejs-multiplayer` is **required** before any networking code — the SDK auto-smooths
@@ -90,7 +99,18 @@ concept-driven — a richer first build beats a grey-box one.
 - Start from the playable game target: player verb, scene scale, camera distance,
   input mode, and frame budget.
 - Build silhouette, motion, and material readability before adding image effects.
+  Never dress a primitive shape in glow or bloom to fake quality — authored
+  forms first, then materials, then lighting, then effects last.
 - Prefer deterministic seeds and named controls for every procedural system.
 - Keep game logic, simulation state, visual fields, and screen-space passes
   separated unless coupling is intentional.
-- Use `$genex-threejs-visual-validation` before declaring a visual task done.
+- 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.
+- Entering an **existing or remixed project**: read before writing — learn the
+  current renderer choice, physics setup, and file conventions first, then
+  extend them. Don't rebuild working systems or switch renderers mid-project.
+- For three.js APIs **not covered by any skill here**, consult the official
+  three.js documentation (https://threejs.org/docs/) rather than guessing —
+  the skills cover Genex-specific and hard-won patterns, not the whole engine.

package/templates/skills/genex-threejs-skill-router/references/routing-map.md

@@ -4,9 +4,9 @@ Use this reference when a Genex game request touches multiple visual systems.
 
 ## Three.js version and references
 
-For new Genex browser-game projects, use the current stable Three.js release and
-pin it exactly in `package.json`. As of June 26, 2026, that is
-`"three": "0.185.0"`.
+For new Genex browser-game projects, use the current stable Three.js release
+(what `npm i three` installs) and keep the project on the version that is
+actually installed — match all docs and examples to it.
 
 For existing projects, inspect and respect the installed Three.js version unless
 the user asks to upgrade. Use official Three.js docs first, then official
@@ -17,25 +17,42 @@ Three.js release or branch, and do not blindly copy demo architecture.
 
 1. Define the game contract: player verb, win/interaction loop, target device,
    camera distance, scene scale, motion, and frame budget.
-2. Wire the gameplay layer for the player verb: the physics world via
+2. Wire player identity before any boot code: `$genex-threejs-embed-auth` is
+   mandatory for every game (`initEmbed(...)` + the `waitForPlayer()` gate) —
+   saves, leaderboards, and multiplayer auth all come from it.
+3. Wire the gameplay layer for the player verb: the physics world via
    `$genex-threejs-physics-rapier` when anything falls, collides, or gets
    pushed; on-foot movement via `$genex-threejs-character-controller`;
    driving/flying and character↔vehicle enter/exit via
    `$genex-threejs-vehicle-controllers`.
-3. Select the minimum scene-generation skills: geometry, materials, vegetation,
-   architecture, planets, water, precipitation, clouds, or VFX.
-4. Add camera direction when framing, controls, transitions, or scale perception
+4. Select the minimum scene-generation skills: geometry, materials, vegetation,
+   architecture, planets, water, precipitation, clouds, or VFX. Show a loading
+   overlay from the very first asset load — a player must never stare at a black
+   screen; the rest of the UI states come at step 10.
+5. Add camera direction when framing, controls, transitions, or scale perception
    affect play.
-5. Add procedural animation when object motion needs authored phases,
+6. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
-6. Add shared fields before writing multiple independent noise layers.
-7. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
-8. Add image-pipeline, bloom, exposure, grading, or AO last.
-9. Validate in a real browser with fixed seeds, captures, interaction checks,
-   and performance evidence.
+7. Add shared fields before writing multiple independent noise layers.
+8. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
+9. Add image-pipeline, bloom, exposure, grading, or AO last.
+10. Once the loop is playable, wire the interface states via
+    `$genex-threejs-game-ui` (HUD, pause, fail/retry, win, and the full loading
+    state grown from the step-4 overlay) and run a feel pass via
+    `$genex-threejs-game-feel` (input response, camera, impact feedback, retry
+    speed).
+11. Validate in a real browser with fixed seeds, captures, interaction checks,
+    and performance evidence.
 
 ## Acceptance gate
 
+**Game fast path:** for a game task that loaded no procedural/visual-system skill,
+done = a screenshot plus an interaction smoke check (load the page, press each
+control, assert a visible response — `$genex-threejs-visual-validation` has the
+procedure). The list below applies to routed *visual-system* scenes, and each
+system-specific item (debug views, seed manifests, tier knobs) applies only when
+the corresponding skill was loaded.
+
 A routed Genex scene is incomplete until it exposes:
 
 - deterministic or reproducible inputs;
@@ -69,8 +86,4 @@ NPC, claimed on contact) and a room `host` (single writer of scores, single simu
 enemies). That skill covers the rules that keep it smooth (draw `state` directly, render
 yourself and objects you own from a local object, quaternion rotation, `stateRaw` for
 hit-tests), the per-genre recipes (sports/ball, shooter, co-op), config wiring, and the
-persistent-world API. Reconnection is built into the SDK (render `reconnecting`/
-`reconnected`, never rebuild it), and **contested physics** (two players pushing one
-object — sumo, tug-of-war, shared crates) routes to its host-authoritative pattern
-(`inputs` + `onHostTick`, see that skill's host-physics reference) — never claim-on-touch.
-Use only the APIs that skill documents — do not invent transport methods.
+persistent-world API. Use only the APIs that skill documents — do not invent transport methods.

package/templates/skills/genex-threejs-spectral-ocean/SKILL.md

@@ -5,6 +5,8 @@ description: Build large procedural oceans for Genex Three.js games. Use for FFT
 
 # Genex Three.js Spectral Ocean
 
+**If the game just needs a sea/lake to float on or fly over, use `$genex-threejs-water-optics` instead** — this skill is the expensive hero-water path, for scenes where open water IS the subject.
+
 Treat an ocean as a sampled stochastic wave field with explicit frequency-space ownership. Do not approximate this target with a pile of Gerstner waves, scrolling normal maps, or unrelated foam noise.
 
 ## Build order

package/templates/skills/genex-threejs-spectral-ocean/references/spectral-ocean.md

@@ -2,6 +2,8 @@
 
 Use this reference for a large, unbounded-looking ocean whose identity comes from directional spectral synthesis, staged inverse FFTs, derivative maps, Jacobian whitecaps, and coherent optical shading.
 
+> **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.
+
 ## Contents
 
 1. Architecture and cascade partition

package/templates/skills/genex-threejs-vehicle-controllers/SKILL.md

@@ -57,6 +57,13 @@ renderer.setAnimationLoop(() => {
 Never call a controller's `update()` from the render loop, never step the
 world yourself, and never feed the render delta into physics code.
 
+**One input path.** With an `EnterExitManager`, vehicle input flows ONLY through
+each `registerVehicle`'s `applyInput` (routed while driving). Delete any direct
+`car.setMovement(...)`/`drone.setMovement(...)` calls from your before-step —
+leaving one in makes WASD drive the empty car while the player is on foot. The
+standalone `setMovement` wiring in the car/drone references applies only to
+games with no on-foot character.
+
 ## Wiring references
 
 - [references/car.md](references/car.md) — chassis body + colliders, wheels,
@@ -82,6 +89,23 @@ from its recipe (exact code in the references).
 | `racing-drone` | drone | agile FPV-style racer (~5 kg) | Genex-authored |
 | `heavy-lifter` | drone | ~298 kg cargo platform, POSITION gains pre-scaled | upstream demo, verbatim |
 
+## Custom generated bodies
+
+`npx genex model` GLBs drop straight in as vehicle visuals — but generate them
+**without the moving parts**: a car body with no wheels ("red sports car body,
+no wheels"), a drone frame with no propellers. Wheels and blades are
+code-driven (`wheel.modelObject` steers/bounces/spins; a propeller spins its
+`spinModel`), so moving parts baked into the body mesh stand frozen while the
+physics moves the vehicle — it reads as broken. A wheel-less or bladeless body
+is valid and drives/flies correctly; add per-corner wheel meshes or per-mount
+blades only when you want them visible. Exact wiring in the car/drone
+references.
+
+On enter/exit: the on-foot character **disappears into the vehicle on enter
+(`park()` hides it) and reappears at the exit point on dismount** — designed
+behavior, not a bug. Don't leave the character mesh standing next to a car it
+is supposedly driving; see [references/enter-exit.md](references/enter-exit.md).
+
 ## Multiplayer: vehicle occupancy is shared state
 
 If the game is multiplayer, **who is in what vehicle must be synced** — a

package/templates/skills/genex-threejs-vehicle-controllers/references/car.md

@@ -68,6 +68,10 @@ scene.add(car.chassisObject);
 physics.registerBody(car.body, car.chassisObject); // interpolated render sync
 
 // 5. Input + fixed-step update (BEFORE world.step(), via onBeforeStep).
+// NOTE: this direct setMovement wiring is for a car-only game. When an
+// EnterExitManager is in play, DELETE it — the manager routes input via its
+// applyInput only while driving (see enter-exit.md); keeping this line too
+// makes WASD drive the empty car while the player is on foot.
 const kb = new KeyboardInput(); // WASD/arrows drive+steer, Space = brake
 physics.onBeforeStep(() => {
   car.setMovement(kb.getCarMovement());
@@ -77,13 +81,37 @@ physics.onBeforeStep(() => {
 
 `setMovement` merges field-wise — send the complete `CarMovementIntent`
 every frame (a stale partial leaves old `true`s behind), which
-`kb.getCarMovement()` already does. Touch input: pass
-`{ joystickL: { x, y } }` from `TouchJoystick` (pushing right steers right).
+`kb.getCarMovement()` already does.
+
+**Touch input — wire it by default, not on request:** published games get opened
+on phones from shared links. Pass `{ joystickL: { x, y } }` from `TouchJoystick`
+(pushing right steers right) and show it only on touch devices
+(`joy.setVisible(navigator.maxTouchPoints > 0)`) — invisible on desktop.
+Phone-specific layouts stay ask-only.
 
 If an on-foot character shares the world, create its body with
 `userData: { controller: { excludeVehicleRay: true } }` so the wheels never
 treat the player as drivable ground.
 
+## Custom generated bodies (`npx genex model`)
+
+A generated GLB works as the visual chassis — add it under `car.chassisObject`
+exactly like `carBodyMesh` above. Two rules keep it looking right:
+
+- **Generate the body WITHOUT wheels** — prompt it explicitly, e.g.
+  `npx genex model "red sports car body, no wheels"`. Wheels are code-driven:
+  each `ShapeCastWheel` steers, bounces, and spins whatever sits in
+  `wheel.modelObject`, so wheels baked into the body mesh stand frozen while
+  the invisible real wheels do the work — it reads as a broken car.
+- **Wheel-less is a valid look.** The suspension shapecasts need no wheel
+  visuals at all: a body with empty `modelObject`s sits and drives correctly.
+  Add per-corner wheel meshes (the cylinder in the wiring above, or a small
+  generated wheel model) only when you want wheels visible.
+
+Scale and center the GLB to hug the chassis colliders, and mind the
++Z-forward convention when orienting it. Collider strategy for GLBs lives in
+`$genex-threejs-physics-rapier`.
+
 ## Presets and provenance
 
 | Preset | Drivetrain | Suspension | Notes |

package/templates/skills/genex-threejs-vehicle-controllers/references/drone.md

@@ -65,6 +65,9 @@ const drone = new DroneController({
   propellers,
   config: preset.config,
 });
+// NOTE: direct setMovement wiring is for a drone-only game. With an
+// EnterExitManager, DELETE it — the manager's applyInput routes input only
+// while piloting (see enter-exit.md); keeping it flies the empty drone.
 const kb = new KeyboardInput(); // W/S throttle, A/D yaw, arrows pitch/roll
 physics.onBeforeStep(() => {
   drone.setMovement(kb.getDroneMovement());
@@ -73,8 +76,24 @@ physics.onBeforeStep(() => {
 ```
 
 The keyboard scheme is deliberately asymmetric (WASD = throttle/yaw, arrows
-= pitch/roll — they are NOT aliases; do not "unify" them). Touch sticks map
-as `joystickL` = climb/yaw, `joystickR` = pitch/roll.
+= pitch/roll — they are NOT aliases; do not "unify" them).
+
+**Touch input — wire it by default, not on request:** published games get opened
+on phones from shared links. Two `TouchJoystick`s map as `joystickL` =
+climb/yaw, `joystickR` = pitch/roll; show them only on touch devices
+(`setVisible(navigator.maxTouchPoints > 0)`) — invisible on desktop.
+Phone-specific layouts stay ask-only.
+
+## Custom generated frames (`npx genex model`)
+
+A generated GLB works as the body visual (`chassis.add(glb)`), but **generate
+the frame only, without propellers** — prompt it explicitly, e.g.
+`npx genex model "carbon quadcopter drone frame, no propellers"`. Blades are
+code-driven: each propeller spins its `spinModel` object, so blades baked into
+the body mesh stand still while the drone flies — it reads as broken. Keep the
+one-mount-`Object3D`-per-propeller wiring above and put a blade mesh (simple
+geometry or a small generated model) in each mount as `spinModel`; a bladeless
+frame also flies correctly if that's the look.
 
 ## Control modes: VELOCITY vs POSITION
 

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

@@ -22,6 +22,21 @@ Read [references/visual-validation.md](references/visual-validation.md)
 for visual contracts, required inspection controls, mechanism-specific
 evidence, temporal checks, budgets, and explicit rejection criteria.
 
+## Interaction smoke check (the game fast path)
+
+For plain game tasks — nothing from the procedural/visual-system pack loaded —
+this is the whole acceptance gate, and it is also the minimum for every game:
+
+1. Load the page in a real browser; the canvas renders (no black screen, no
+   console errors).
+2. Press each documented control once (keys, pointer); assert a **visible
+   response** to every one — the player moves, the camera turns, the button
+   fires.
+3. Capture one screenshot of live gameplay.
+
+Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
+visual-system work — the sequence above.
+
 ## Required evidence
 
 - fixed camera and seed manifest;

package/templates/skills/genex-threejs-volumetric-clouds/SKILL.md

@@ -5,6 +5,10 @@ description: Build volumetric cloud systems for Genex Three.js games. Use for we
 
 # Genex Three.js Volumetric Clouds
 
+**Static clouds in a fixed sky → `$genex-ai-skybox` instead** (one command, a
+real 360° image). This skill is for moving, weather-driven, or fly-through
+clouds.
+
 Cloud quality comes from density organization, lighting, and temporal stability—not from increasing march steps over unstructured noise.
 
 ## System order

package/templates/skills/genex-threejs-water-optics/references/water-optics.md

@@ -2,6 +2,8 @@
 
 Use this reference for bounded or analytic water with shared displacement and normals, derivative-filtered detail, analytic reflection, heuristic refraction, absorption, and crest foam. Use `$genex-threejs-spectral-ocean` for stochastic FFT seas.
 
+> **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.
+
 ## Contents
 
 - cinematic implementation displaced ocean
@@ -16,7 +18,7 @@ Use this reference for bounded or analytic water with shared displacement and no
 
 ## cinematic implementation displaced ocean
 
-The Miller’s Planet scene uses five authored Gerstner-style components:
+The shallow-sea demo scene uses five authored Gerstner-style components:
 
 | Direction X/Z | Amplitude | Wavelength | Steepness |
 | --- | ---: | ---: | ---: |

package/templates/controllers/shared/NETWORKING.md

@@ -1,11 +0,0 @@
-# Networking these controllers
-
-These controllers simulate **your own player only** (self-authoritative, zero input
-latency). To show OTHER players' rigs in a multiplayer game, publish a small flat state on
-a fixed tick and play it back on a visual-only remote rig — never instantiate a controller
-or a Rapier body for a remote player.
-
-The complete recipe (what to publish per controller, remote playback, contested-contact
-physics via the host) lives in the multiplayer skill:
-`genex-threejs-multiplayer` → `references/host-physics.md`. Load that skill before writing
-any networking code.

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

@@ -1,111 +0,0 @@
-# Host-authoritative physics — contested objects + networked controllers
-
-Two networking tiers exist for moving things, and picking the right one per object is the
-whole trick:
-
-| Object kind | Tier | Why |
-| --- | --- | --- |
-| One-touch (kick a ball, throw a crate once) | **claim-on-touch** (`objects.claim` on contact, owner simulates) | lowest latency — your kick lands instantly |
-| Sustained contact / contested (two players pushing one crate, tug-of-war, sumo, shared vehicles) | **host-authoritative** (this doc) | one simulation owns the contest — no ownership ping-pong, physics stays consistent |
-
-Claim-on-touch under sustained contact means every contact steals ownership, resets the
-simulation, and the object judders between two owners' views. Host-authoritative kills that
-by construction: **the host runs the ONE Rapier world for contested objects; everyone else
-sends inputs.**
-
-## The pattern (complete)
-
-Every client runs this same code — `onHostTick` only fires on the current host, so there is
-no "am I host?" bookkeeping and host migration is automatic:
-
-```ts
-// ---- inputs: NON-hosts (and the host itself) report intent, ~10-15Hz or on action ----
-// Routed by the relay to the CURRENT HOST ONLY — never broadcast, cheap.
-if (pushingCrate) room.inputs.send({ obj: "crate", push: dir.toArray() });
-
-// ---- simulation: runs ONLY on the host, survives migration ----
-const pending: { obj: string; push: number[] }[] = [];
-room.inputs.on((fromId, payload) => {
-  const p = payload as { obj?: string; push?: number[] };
-  if (p?.obj && Array.isArray(p.push)) pending.push(p as { obj: string; push: number[] });
-});
-
-room.onHostTick(30, (dtMs) => {
-  // 1) First tick after election: adopt the objects + seed the physics world from the
-  //    last published truth (stateRaw) — NEVER from zero, or the world teleports.
-  for (const id of CONTESTED_IDS) {
-    const view = room.objects.get(id);
-    if (!view || !view.isMine) {
-      room.objects.claim(id);
-      seedRapierBody(id, view?.stateRaw); // position/rotation/velocity from the wire
-    }
-  }
-  // 2) Apply everyone's inputs to the ONE authoritative Rapier world.
-  for (const { obj, push } of pending.splice(0)) applyImpulse(obj, push);
-  // 3) Step and publish (flat state: numbers + one [x,y,z,w] quaternion).
-  rapierWorld.step();
-  for (const id of CONTESTED_IDS) {
-    const b = bodyOf(id);
-    room.objects.set(id, {
-      x: r2(b.translation().x), y: r2(b.translation().y), z: r2(b.translation().z),
-      q: quatArray(b.rotation()),
-    });
-  }
-});
-const r2 = (v: number) => Math.round(v * 100) / 100; // quantize — floats are JSON bloat
-
-// ---- rendering: identical on every client, host included ----
-for (const id of CONTESTED_IDS) {
-  const view = room.objects.get(id);
-  if (view) meshOf(id).position.set(view.state.x, view.state.y, view.state.z); // auto-smoothed
-}
-```
-
-Rules that make it correct:
-
-- **Sim internals that must survive migration** (velocities, cooldowns, aggro) either live in
-  the published object state or get mirrored at low rate into a dedicated object
-  (`objects.set("sim", …)`) the next host reads on adoption. Positions/rotations come free
-  via `stateRaw`.
-- **Latency honesty:** a non-host's push lands after ~RTT to the relay. At casual scale that
-  reads as weight, not lag. The host's own pushes are instant — that asymmetry is the tier's
-  price; don't fight it with client-side guessing.
-- **Rate budget:** the host publishes N contested objects at 20–30 Hz; keep N modest (≤ ~10)
-  and state flat + quantized. Inputs are single-receiver and cheap.
-- **Do not** run a second Rapier body for a contested object on non-hosts "for prediction" —
-  that's the double-simulation version of double-smoothing. Draw `state`.
-
-## Networked controllers (the vendored character / vehicle / drone)
-
-The `genex controller` controllers are **local-only physics** — each player simulates their
-OWN rig (self-authoritative, zero latency). Networking them is publish-and-playback, never
-remote simulation:
-
-```ts
-// You: after your controller's update, on the fixed tick (~15Hz)
-room.me.set({
-  x: r2(rig.position.x), y: r2(rig.position.y), z: r2(rig.position.z),
-  q: rig.quaternion.toArray().map(r2),      // quaternion — never a scalar yaw
-  anim: rig.animState,                       // discrete → remotes read via stateRaw
-  // vehicle extras: steer: r2(steerAngle), wheel: r2(wheelSpinPhase)
-});
-
-// Remote players: drive a VISUAL-ONLY rig from smoothed state — no Rapier body, no
-// controller instance for remotes. Wheels/limbs animate from the published params.
-const p = room.players.get(id)!;
-remoteMesh.position.set(p.state.x, p.state.y, p.state.z);
-remoteMesh.quaternion.fromArray(p.state.q);
-remoteAnimator.play(p.stateRaw.anim);        // discrete values from stateRaw
-```
-
-What to publish per controller:
-
-- **character**: `x/y/z`, `q`, `anim` (state-machine id), optionally `speed` for blend trees.
-- **vehicle**: body `x/y/z` + `q`, `steer` angle, a `wheel` spin phase (remotes spin wheels
-  procedurally — never sync per-wheel transforms).
-- **drone**: `x/y/z`, `q`, rotor throttle if the visual needs it.
-
-Player-vs-player physical contact (bumping cars) stays approximate at this tier — each
-client is authoritative over itself, so contacts are cosmetic. If a game's core loop IS
-contested vehicle contact, that's the host-authoritative tier above, with the vehicles as
-host-simulated objects and player inputs over `inputs.send`.