@genex-ai/cli-demo 0.17.0 → 0.20.0

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;

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 |
 | --- | ---: | ---: | ---: |