@genex-ai/cli-demo 0.6.0 → 0.6.2

package/dist/index.js

@@ -930,6 +930,7 @@ async function runPublish(opts) {
     const body = {};
     if (opts.title) body.title = opts.title;
     if (opts.description) body.description = opts.description;
+    if (opts.regenerateCover) body.regenerateCover = true;
     res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
@@ -1190,6 +1191,7 @@ ${c.bold("Options for `preview` / `publish`")}
   --no-push            (publish) Skip build + push; only flip the gallery flag.
   --title <title>      (publish) Gallery title.
   --description <text> (publish) Gallery description.
+  --regenerate-cover   (publish) Re-mint the disc cover (concept changed).
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
@@ -1266,6 +1268,9 @@ function parseArgs(argv) {
       case "--force":
         parsed.options.force = true;
         break;
+      case "--regenerate-cover":
+        parsed.options.regenerateCover = true;
+        break;
       case "--quiet":
         parsed.options.quiet = true;
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/SKILL.md

@@ -5,26 +5,38 @@ description: Implement sky and aerial perspective for Genex Three.js games. Use
 
 # Genex Three.js Atmosphere And Aerial Perspective
 
-Atmosphere should explain scale and lighting without hiding gameplay. Add it
-after the base scene reads.
+Treat sky rendering and aerial perspective as two views of the same scattering model. They must share radii, density profiles, coefficients, sun direction, exposure scale, and coordinate transforms.
 
-Read [references/atmosphere.md](references/atmosphere.md) for sky, haze,
-lighting handoff, and transition checks.
+## Choose the implementation tier
 
-## Build order
+- Small scene with no orbital camera: analytic height/distance approximation.
+- Planetary ground-to-space camera: ray integration or precomputed LUTs.
+- Large geospatial world: LUTs plus world-to-planet transform, altitude correction, and depth-aware aerial perspective.
 
-1. Define world scale, camera altitude range, sun direction, horizon behavior,
-   and target devices.
-2. Build the sky model or sky gradient first.
-3. Add depth-based aerial perspective for terrain, buildings, and distant props.
-4. Connect sun color, ambient color, fog, and material response coherently.
-5. Add planetary shell or LUT paths only when the scale needs them.
-6. Expose debug views for transmittance, inscattering, depth, and no-atmosphere.
+Read [references/atmosphere.md](references/atmosphere.md)
+before implementation. It separates the LUT/ellipsoid architecture from
+dynamic integration and the shell/post handoff.
 
-## Rules
+## Required outputs
 
-- Keep gameplay silhouettes readable through haze.
-- Use one owner for sky color and sun direction.
-- Avoid stacking multiple fog systems with different assumptions.
-- Keep atmosphere quality adjustable for lower-end browsers.
-- Validate ground, mid-altitude, and high-altitude views.
+- sky radiance;
+- sun transmittance/color;
+- segment transmittance from camera to visible surface;
+- segment inscattering;
+- optional sky irradiance for materials;
+- explicit scale conversion between world units and atmosphere units.
+
+## Failure conditions
+
+- sky and terrain haze use different sun directions or coefficients;
+- the atmosphere is a uniformly transparent sphere;
+- camera altitude is measured in a local flat frame during orbital motion;
+- scene depth is treated as linear when it is not;
+- exposure is used to hide incorrect radiance scale;
+- atmosphere fades abruptly at shell entry.
+
+## Routing boundary
+
+This skill owns molecular/aerosol sky scattering and surface-segment aerial
+perspective. Use `$genex-threejs-volumetric-clouds` for weather-shaped cloud density,
+temporal cloud reconstruction, and cloud shadows.

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/references/atmosphere.md

@@ -1,29 +1,213 @@
-# Atmosphere And Aerial Perspective
+# Atmosphere system contract
 
-Use this reference for outdoor scale and sky rendering.
+Use this contract to choose between a precomputed LUT/ellipsoid atmosphere and bounded dynamic integration while keeping sky, aerial perspective, surface lighting, and coordinate transforms coherent.
 
-## Sky
+## Contents
 
-- Keep sun direction explicit and shared with lighting.
-- Match sky color, ambient color, and direct light temperature.
-- Include sun or moon discs only when they help composition.
-- Keep stars or space backgrounds separated from atmospheric haze.
+- Shared parameter model
+- LUT atmosphere implementation LUT contract
+- Ellipsoid and depth ownership
+- planet-space implementation body profiles
+- planet-space implementation integration
+- Shell/post handoff
+- Implementation limits
+- Diagnostics
 
-## Aerial perspective
 
-- Apply haze by depth or world distance.
-- Preserve contrast for interactable objects and traversal edges.
-- Let distant terrain shift color before it loses all form.
-- Provide a debug toggle to remove atmosphere.
+## Shared parameter model
 
-## Planetary scale
+`LUT atmosphere implementation` keeps one atmosphere object for sky and aerial perspective.
+Earth-like defaults:
 
-- Use altitude-aware behavior for ground-to-space transitions.
-- Keep horizon curvature and shell radius consistent with planet radius.
-- Validate camera positions near ground, high altitude, and orbit.
+```text
+solar irradiance = (1.474, 1.8504, 1.91198)
+sun angular radius = 0.004675 rad
+bottom radius = 6,360,000 m
+top radius = 6,420,000 m
+Rayleigh scattering = (0.005802, 0.013558, 0.0331)
+Mie scattering = (0.003996, 0.003996, 0.003996)
+Mie extinction = (0.00444, 0.00444, 0.00444)
+Mie phase g = 0.8
+absorption extinction = (0.00065, 0.001881, 0.000085)
+ground albedo = 0.1
+```
 
-## Performance
+Density profiles are two-layer functions:
 
-- Prefer simple depth haze for small scenes.
-- Use precomputed or lower-resolution paths for expensive scattering.
-- Expose quality tiers and render-target costs.
+```text
+density(h) =
+  clamp(
+    expTerm * exp(expScale * h)
+    + linearTerm * h
+    + constantTerm,
+    0,
+    1
+  )
+```
+
+The default Rayleigh exponential scale is `-0.125`, Mie `-0.833333`.
+Absorption uses two linear layers centered around the ozone region rather than
+another ground-heavy exponential.
+
+One explicit meter-to-render-unit conversion is applied when parameters become
+uniforms. Preserve this single conversion boundary.
+
+## LUT atmosphere implementation LUT contract
+
+The sky material and aerial-perspective effect consume the same:
+
+```text
+transmittance texture
+scattering 3D texture
+irradiance texture
+optional single-Mie and higher-order scattering textures
+atmosphere parameters
+sun direction
+```
+
+The sky material reconstructs rays from inverse projection and inverse view
+matrices. It can render sun, moon, ground, and shadow-length integration.
+
+The aerial-perspective effect owns:
+
+```text
+camera projection/view and inverses
+camera world position
+depth
+optional normal buffer
+ellipsoid radii
+world-to-ECEF transform
+altitude correction
+geometric-error correction
+overlay/cloud shadow/light-mask inputs
+```
+
+Default composition enables segment transmittance and inscatter. Direct sun
+light and sky-light relighting are separate switches. Do not collapse these
+signals into one fog color.
+
+## Ellipsoid and depth ownership
+
+The geospatial path defaults to `Ellipsoid.WGS84` and can correct both
+camera altitude and geometry error. Atmosphere altitude is therefore not
+`worldPosition.y`.
+
+Required coordinate contract:
+
+```text
+world position
+  -> world-to-ECEF
+  -> ellipsoid-relative position
+  -> corrected altitude
+  -> LUT coordinates / segment scattering
+```
+
+The aerial effect declares depth ownership through its post-processing effect
+attribute. It also supports octahedral normals or normal reconstruction when
+lighting terms require orientation.
+
+## planet-space implementation body profiles
+
+planet-space implementation derives profiles by body kind and density. Terrestrial baseline:
+
+```text
+Rayleigh = (0.0058, 0.0135, 0.0331)
+Mie scattering = (0.0022, 0.0022, 0.0022)
+Mie extinction = (0.0032, 0.0032, 0.0032)
+Rayleigh scale height = lerp(7.2, 10.8, normalized density) km
+Mie scale height = lerp(0.9, 1.7, normalized density) km
+Mie g = 0.76
+ozone extinction = (0.00065, 0.001881, 0.000085)
+solar intensity = 13.8
+```
+
+Rocky bodies reduce scattering and remove ozone. Gas/ice giants use much
+larger scale heights and `g` around `0.80–0.82`.
+
+The implementation enforces:
+
+```text
+mieExtinction[channel] >= mieScattering[channel] + 0.0001
+g <= 0.92
+```
+
+This prevents negative absorption and unstable phase behavior.
+
+## planet-space implementation integration
+
+For each camera ray, planet-space implementation:
+
+1. intersects the top atmosphere sphere;
+2. clamps the segment against the surface sphere;
+3. marches `ATMOSPHERE_VIEW_SAMPLES`;
+4. accumulates Rayleigh, Mie, and triangular ozone depth;
+5. at every view sample, marches a sun segment with
+   `ATMOSPHERE_LIGHT_SAMPLES`;
+6. tests planet occlusion of the sun;
+7. evaluates Rayleigh and anisotropic Mie phase;
+8. returns in-scattered radiance and view transmittance.
+
+It adds an upper-Rayleigh exponential term and fades density over the final
+`24%` of atmosphere thickness to soften the shell edge.
+
+The compact path includes a small multiple-scattering approximation derived
+from `1 - transmittance`; it is not equivalent to the precomputed higher-order
+scattering available in `LUT atmosphere implementation`.
+
+## Shell/post handoff
+
+planet-space implementation renders a double-sided shell and a depth-aware post path from one
+profile. Runtime face-opacity weights avoid a hard front/back cull switch.
+
+The post blend is based on altitude above the atmosphere top:
+
+```text
+entry blend near = 140 km
+entry blend far = max(448 km, visual atmosphere height * 0.58)
+post blend = 1 - smoothstep(near, far, altitudeFromTop)
+```
+
+The post path applies only where scene depth represents a surface. The shell
+continues to own sky pixels and limb appearance.
+
+Preserve:
+
+```text
+one body center and radius
+one atmosphere profile
+one sun direction
+one unit conversion
+surface-depth classification
+continuous shell/post blend
+```
+
+## Implementation limits
+
+- planet-space implementation performs nested dynamic integration and is expensive compared with
+  LUT lookup.
+- Its atmosphere uses spheres, while `LUT atmosphere implementation` supports an ellipsoid
+  and ECEF correction.
+- planet-space implementation’s multiple-scattering term is an artistic approximation.
+- `LUT atmosphere implementation` is version-sensitive and built around its own
+  post-processing/coordinate utilities; adapt the architecture, not imports
+  blindly.
+- Do not combine LUT radiance and dynamic integrated radiance at full weight.
+  Choose ownership or a validated transition.
+
+## Diagnostics
+
+Expose:
+
+```text
+planet/ECEF coordinates and corrected altitude
+top and bottom intersections
+Rayleigh, Mie, and absorption density
+view and sun optical depth
+sun visibility
+segment transmittance
+single and multiple scattering
+sky versus surface depth classification
+shell front/back opacity
+post blend
+LUT coordinates and texture slices
+```

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

@@ -5,26 +5,37 @@ description: Implement controlled HDR bloom for Genex Three.js games. Use for se
 
 # Genex Three.js Bloom
 
-Bloom should reveal strong light and energy. It should not be the only reason an
-object reads.
+Bloom is a camera/display response to bright HDR signal. Establish scene exposure and emissive luminance before tuning blur.
 
-Read [references/bloom.md](references/bloom.md) for HDR signal setup,
-selective contribution, blur hierarchy, and diagnostics.
+## Workflow
 
-## Build order
+1. Inspect pre-tone-map luminance.
+2. Choose which scene values should bloom.
+3. Choose a single-node or dual selective-render ownership model.
+4. Calibrate threshold, radius, smooth width, and strength in HDR.
+5. Restore all substituted materials transactionally for selective passes.
+6. Composite before exposure/tone mapping.
+7. Validate base, contribution, and final views.
 
-1. Confirm the scene uses a consistent HDR signal and tone-mapping path.
-2. Define what is allowed to bloom and why.
-3. Extract bright or selected contribution.
-4. Blur at multiple scales.
-5. Composite with exposure-aware strength.
-6. Expose debug views for source, threshold mask, blur levels, final bloom, and
-   no-bloom baseline.
+Read [references/bloom.md](references/bloom.md) for the
+HDR ordering, dual selective-bloom transaction, compact emissive hierarchy,
+and the costs and limits of each ownership model.
 
-## Rules
+Apply the material substitution/restoration ownership pattern in the
+reference before adding selective bloom to a composed scene.
 
-- Keep emissive intensities scene-relative.
-- Avoid global bloom that washes out gameplay silhouettes.
-- Restore materials if using selective render passes.
-- Tune bloom with exposure and grading visible.
-- Validate readability with bloom disabled.
+## Failure conditions
+
+- bloom creates the only visible form of an effect;
+- all bright materials share one arbitrary emission multiplier;
+- threshold is tuned after tone mapping;
+- 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.
+
+## Routing boundary
+
+Use `$genex-threejs-exposure-color-grading` for metering, adaptation, tone mapping,
+and LUTs. Load `$genex-threejs-image-pipeline` only when bloom must be composed with
+several shared image-space systems.

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

@@ -1,29 +1,185 @@
-# Bloom
+# HDR bloom systems
 
-Use this reference for controlled glow in Genex games.
+Use this reference to choose bloom ownership, signal order, selective contribution, and scene-relative emissive ranges without making bloom responsible for the underlying form.
 
-## Signal ownership
+## Contents
 
-- Establish whether bloom comes from HDR thresholding, selection layers, or both.
-- Keep tone mapping after bloom composition.
-- Keep exposure changes from unpredictably destroying bloom intent.
+- production WebGPU pipeline signal order
+- production WebGPU pipeline bloom controls
+- selective gallery pipeline selective ownership
+- Material substitution invariant
+- atlas-based renderer baseline
+- pooled VFX system HDR hierarchy
+- Implementation limits
+- Diagnostics
 
-## Selective bloom
 
-- Use layers, masks, or a separate render pass.
-- Restore material state after rendering a selected pass.
-- Avoid duplicate contribution from the same object.
-- Keep selected objects documented.
+## production WebGPU pipeline signal order
 
-## Blur levels
+The WebGPU pipeline owns bloom before exposure and render output:
 
-- Small radius: sharp energy and UI-like highlights.
-- Medium radius: glow around light sources.
-- Large radius: atmosphere or spectacle.
-- Keep each level inspectable.
+```text
+scene pass
+  -> optional GTAO composite
+  -> optional atmosphere
+  -> bloom node
+  -> sampled scene + bloom
+  -> eye-adaptation exposure
+  -> renderOutput / tone map
+  -> optional 3D LUT
+  -> optional FXAA
+```
 
-## Failure checks
+The render pipeline disables its automatic output color transform and assigns
+one final output node. Preserve this one-owner rule when adapting to current
+Three.js `RenderPipeline`.
 
-- Bloom cannot carry the silhouette alone.
-- White UI or text should not bloom unless intentionally emissive.
-- Dark scenes should not become foggy because bloom strength is too high.
+## production WebGPU pipeline bloom controls
+
+Bloom defaults:
+
+```text
+enabled = false
+strength = 0
+radius = 0.35
+threshold = 0.72
+smooth width = 0.08
+```
+
+The Three.js bloom node reads the HDR texture produced after atmosphere. Its
+strength becomes zero when disabled; radius, threshold, and smooth width remain
+independently updateable.
+
+This path does not implement a custom pyramid. Its contract is signal placement
+and parameter ownership around the renderer’s bloom node.
+Verify the installed Three.js node API before using the exact constructor or
+property names.
+
+## selective gallery pipeline selective ownership
+
+The gallery uses two separate selective bloom pipelines:
+
+```text
+neon layer -> neon UnrealBloomPass
+chandelier layer -> chandelier UnrealBloomPass
+base scene -> final composer
+
+final = base + neon bloom + chandelier bloom
+```
+
+Each bloom composer renders off-screen. A final shader adds both bloom textures
+to the base render, then an `OutputPass` performs display output.
+
+Separate ownership lets neon animation change strength/radius without forcing
+the chandelier glow to share the same threshold or spread.
+
+Chandelier bulbs, filaments, and glow meshes use unlit materials; bulb and
+filament materials set `toneMapped = false`. The pipeline therefore combines
+explicit layer membership with material-level HDR/display behavior.
+
+## Material substitution invariant
+
+For each selective pass, selective gallery pipeline traverses visible meshes and replaces every
+non-member material with one shared black material.
+
+Required transaction:
+
+```text
+set active bloom layer
+traverse visible meshes
+record { mesh, original material }
+replace non-members with shared black material
+try:
+  render bloom composer
+finally:
+  restore every recorded material
+  clear restoration list
+```
+
+Support material arrays by storing the complete original `mesh.material`
+value. Also toggle the high-detail and simplified
+chandelier representations so only the intended version contributes.
+
+The `finally` block is non-negotiable. Without it, a render error permanently
+blackens scene meshes.
+
+## atlas-based renderer baseline
+
+atlas-based renderer wraps `UnrealBloomPass` with:
+
+```text
+strength = 0.30
+radius = 0.50
+threshold = 0.05
+```
+
+Composer order:
+
+```text
+scene -> SSAO -> volumetrics -> bloom -> lens flare -> fog/color
+```
+
+This is a useful comparison, not the quality target. The threshold is very low
+and can bloom ordinary bright surfaces. The wrapper exposes only enabled,
+strength, and threshold, while radius stays at its constructor value.
+
+## pooled VFX system HDR hierarchy
+
+pooled VFX system assigns compact effect luminance before bloom:
+
+```text
+spark initial RGB multiplier = 80
+homing projectile = 30
+laser = 10
+```
+
+These values establish a material-level contribution hierarchy, but they do
+not define the bloom pass. Validate them against actual renderer exposure
+before reuse.
+
+Use the relationship, not the raw numbers:
+
+```text
+short spark flash
+  > projectile core
+  > persistent laser
+  > ordinary lit surface
+```
+
+## Implementation limits
+
+- selective gallery pipeline renders the scene multiple times for selective bloom. This is
+  acceptable for its bounded gallery but expensive for large scenes.
+- Temporary material substitution can trigger shader/program changes and must
+  account for newly added meshes.
+- The final selective gallery pipeline composite adds bloom textures directly; energy is
+  artistic, not physically conserved.
+- atlas-based renderer’s low threshold is not evidence for a general HDR calibration.
+- production WebGPU pipeline depends on version-sensitive Three.js bloom-node behavior.
+- pooled VFX system material multipliers are scene-relative and cannot be treated as
+  exposure-independent units.
+
+Prefer a dedicated contribution target when MRT/backend architecture supports
+it and the scene cannot afford multiple full renders. Validate that decision
+against the target scene’s measured cost and contribution masks.
+
+## Diagnostics
+
+Expose:
+
+```text
+HDR scene before bloom
+false-color luminance
+neon contribution
+chandelier contribution
+each bloom result
+base without bloom
+final composite
+active layer membership
+material restoration count and leak assertion
+transparent-emitter contribution
+bloom GPU time per render
+```
+
+Acceptance requires the base frame to retain form and material hierarchy with
+both bloom textures disabled.

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

@@ -5,32 +5,44 @@ description: Design advanced Three.js camera systems for Genex browser games. Us
 
 # Genex Three.js Camera Direction
 
-Treat the camera as part of the game design, not a passive viewport. It must
-explain scale, support the player verb, and survive mode changes.
-
-Read [references/camera-rigs.md](references/camera-rigs.md) for concrete rig
-patterns, handoff rules, and browser checks.
+Treat the camera as an authored visual system, not a passive viewport. Compose
+the subject, establish scale, choose a stable up frame, and make every mode
+handoff explicit.
 
 ## Build order
 
-1. Define subject size, play distance, screen occupancy, lens, near/far planes,
-   input mode, and up-axis convention.
-2. Choose semantic camera frames: player body, vehicle, track, planet normal,
-   arena center, or authored shot marker.
-3. Compute target position and orientation separately, then compose the final
-   camera transform once.
-4. Add orbit, chase, side, or pointer-look constraints around the chosen frame.
-5. Use frame-rate-independent smoothing for follow motion; avoid stacked
-   smoothing during explicit transitions.
-6. Snapshot and restore projection, controls, and ownership when scenes mount or
-   dispose.
-
-## Rules
-
-- Derive distances from subject bounds; do not hard-code one offset for every
-  game object.
-- Use `lerp` for positions and `slerp` for orientations.
-- Re-sync yaw and pitch from the active camera when pointer lock is acquired.
-- Update projection matrices after FOV, near, far, or aspect changes.
-- Keep infinite backgrounds camera-relative in large worlds.
-- Validate resize, pointer-lock recovery, mode transitions, and collision edges.
+1. Define the design frame: subject size, screen occupancy, lens, near/far,
+   motion, and horizon/up convention.
+2. Build camera targets in semantic frames: ship, body surface, docking axis,
+   or scene-authored shot.
+3. Derive position and orientation independently, then combine them once.
+4. Add input orbit/look only inside declared yaw/pitch and spatial constraints.
+5. Add frame-rate-independent follow or a bounded spring where the reference
+   uses inertia.
+6. Snapshot and restore camera projection/state when a scene owns it.
+7. Test mode transitions, cuts, pointer-lock reacquisition, resize, and large
+   coordinates.
+
+Read [references/camera-rigs.md](references/camera-rigs.md)
+for exact chase/side/orbit rigs, projection values, transition
+rules, floating-origin shot, pointer controls, and implementation limits.
+
+## Non-negotiable rules
+
+- Use subject dimensions to derive offsets; do not tune one fixed distance for
+  differently scaled assets.
+- For planetary motion, derive up from the dominant body rather than global Y.
+- Interpolate position with `lerp` and orientation with `slerp`.
+- 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.
+- 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.
+- Restore camera and input ownership on scene disposal.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-animation` for object motion timelines, springs,
+docking, staging, and debris. This skill owns how the scene is viewed and how
+camera modes hand off.