@genex-ai/cli-demo 0.6.2 → 0.8.0

package/dist/index.js

@@ -788,32 +788,71 @@ async function deployGame(sshUrl, opts, log) {
     return false;
   }
   const gitDir = await fs6.mkdtemp(path7.join(os2.tmpdir(), "genex-deploy-"));
-  const gitEnv = { GIT_DIR: gitDir, GIT_WORK_TREE: siteDir };
+  const base = { GIT_DIR: gitDir };
+  const ident = {
+    GIT_AUTHOR_NAME: "genex",
+    GIT_AUTHOR_EMAIL: "agent@genex.local",
+    GIT_COMMITTER_NAME: "genex",
+    GIT_COMMITTER_EMAIL: "agent@genex.local"
+  };
+  const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
   try {
-    if ((await run("git", ["init", "-q"], gitEnv)).code !== 0) {
+    if ((await run("git", ["init", "-q"], base)).code !== 0) {
       log.warn("git init failed \u2014 the game was not pushed.");
       return false;
     }
-    await run("git", ["add", "-A"], gitEnv);
-    const tracked = await run("git", ["ls-files"], gitEnv);
-    if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) {
+    await fs6.writeFile(
+      path7.join(gitDir, "info", "exclude"),
+      ["node_modules/", "dist/", ".git/", KEY_NAME, `${KEY_NAME}.pub`, ".genex/", ""].join("\n")
+    );
+    const stage = async (workTree, indexName) => {
+      const env = { ...base, GIT_WORK_TREE: workTree, GIT_INDEX_FILE: path7.join(gitDir, indexName) };
+      await run("git", ["add", "-A"], env);
+      const tracked = await run("git", ["ls-files"], env);
+      if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) throw new Error("KEY_STAGED");
+      if (!tracked.out.trim()) return null;
+      const tree = (await run("git", ["write-tree"], env)).out.trim();
+      return tree || null;
+    };
+    const commitTree = async (tree, message) => (await run("git", ["commit-tree", tree, "-m", message], { ...base, ...ident })).out.trim();
+    let mainTree;
+    try {
+      mainTree = await stage(siteDir, "index-main");
+    } catch {
       log.error(`Refusing to deploy: ${KEY_NAME} is staged. Add it to .gitignore and retry.`);
       return false;
     }
-    const commit = await run(
-      "git",
-      ["-c", "user.email=agent@genex.local", "-c", "user.name=genex", "commit", "-q", "-m", "build"],
-      gitEnv
-    );
-    if (commit.code !== 0 && !/nothing to commit/i.test(commit.out + commit.err)) {
+    if (!mainTree || mainTree === EMPTY_TREE) {
       log.warn("Nothing to commit \u2014 the build produced no files.");
       return false;
     }
+    await run("git", ["update-ref", "refs/heads/main", await commitTree(mainTree, "build")], base);
+    let pushSource = false;
+    if (siteDir !== cwd) {
+      try {
+        const srcTree = await stage(cwd, "index-source");
+        if (srcTree && srcTree !== EMPTY_TREE) {
+          await run("git", ["update-ref", "refs/heads/source", await commitTree(srcTree, "source")], base);
+          pushSource = true;
+        }
+      } catch {
+        log.dim("  (Couldn't publish source for remixing \u2014 the deploy key was in the way.)");
+      }
+    }
     log.step("Pushing your game over SSH\u2026");
-    const push = await run("git", ["push", "-q", sshUrl, "+HEAD:main"], {
-      ...gitEnv,
-      GIT_SSH_COMMAND: `ssh -i ${keyPath} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
-    });
+    const refspecs = ["+refs/heads/main:main"];
+    if (pushSource) refspecs.push("+refs/heads/source:source");
+    const push = await run(
+      "git",
+      ["push", "-q", ...pushSource ? ["--atomic"] : [], sshUrl, ...refspecs],
+      {
+        ...base,
+        // Quote the key path: git splits GIT_SSH_COMMAND with shell-like rules, so a
+        // project folder with a space (e.g. "fly drone") otherwise breaks the `-i`
+        // argument and ssh fails with "Could not resolve hostname …".
+        GIT_SSH_COMMAND: `ssh -i "${keyPath}" -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
+      }
+    );
     if (push.code === 0) {
       log.success("Pushed.");
       if (opts.playUrl) {

package/package.json

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

package/templates/README.md

@@ -1,15 +1,16 @@
 # Genex workspace
 
-These files were installed into your `~/.claude` directory by `genex init`.
-They give your coding agent a starter workspace for making 3D games in the
-browser.
+These files were installed by `genex init` into your coding agent's workspace —
+Claude Code (`~/.claude`), Codex (`~/.codex/skills`), and Cursor
+(`~/.cursor/skills`), whichever it detected. They give your agent superpowers
+for making 3D games in the browser.
 
 Genex is built around agent superpowers for browser games: Three.js skills,
-one-click publishing, multiplayer-ready architecture, and team workflows. The
-installed files are yours to edit, extend, and keep with each project.
+one-click publishing, multiplayer-ready architecture, and team workflows.
 
-Existing files are never overwritten. Re-running `genex init` only adds files
-you do not already have.
+Files whose names start with `genex-` are managed by Genex: re-running
+`genex init` refreshes them to the latest version. Anything you add yourself is
+never touched.
 
 - `skills/` - reusable Genex skills for 3D game creation.
 - `agents/` - example subagent definitions.

package/templates/skills/genex-getting-started/SKILL.md

@@ -23,12 +23,14 @@ are never touched).
 
 Start with `$genex-threejs-skill-router` for broad game or graphics requests.
 It routes the agent to focused skills for cameras, procedural geometry,
-materials, atmosphere, water, VFX, post-processing, and visual validation.
+materials, atmosphere, water, weather, VFX, post-processing, and visual
+validation.
 
 ## Generating real assets
 
 Beyond procedural code, Genex can generate **real, AI-made assets** from a prompt
-and drop them into `./assets/` (committed when you publish):
+and drop them into `public/assets/` (shipped with your published game; load them
+as `./assets/...` — the `public/` prefix is stripped when served):
 
 ```bash
 npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)
@@ -43,18 +45,20 @@ npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
 `$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
 
-Your existing files were left untouched. `genex init` only adds what is missing.
+Your own files were left untouched. `genex init` only adds missing files and
+refreshes the genex-owned ones.
 
 ## Re-running setup
 
-Safe to run any time; it never overwrites your files:
+Safe to run any time — genex-owned skills are refreshed to the latest version,
+and your own files are never touched:
 
 ```bash
 npx @genex-ai/cli-demo@latest init
 ```
 
-Use `--force` only if you intentionally want to overwrite installed templates
-with the latest versions.
+Use `--force` only if you intentionally want your own existing files overwritten
+by the bundled templates too.
 
 ## Authorization
 

package/templates/skills/genex-threejs-precipitation-surfaces/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: genex-threejs-precipitation-surfaces
+description: Build coupled precipitation and weather-affected surfaces for Genex Three.js games. Use for falling snow, snow accumulation, model snow caps, rain, wet asphalt puddles, procedural ripple normals, splash flipbooks, rain streaks, shared weather envelopes, and surface wetness or coverage transitions.
+---
+
+# Genex Three.js Precipitation Surfaces
+
+Treat weather as a coupled event, particle, and surface-response system. Do not
+add rain or snow particles that are visually disconnected from the ground.
+
+## Build order
+
+```text
+weather envelope
+  -> falling precipitation volume
+  -> world/object surface mask
+  -> displaced or optical surface response
+  -> impact residue and splashes
+  -> shared lighting/post presentation
+```
+
+Read [references/precipitation-surfaces.md](references/precipitation-surfaces.md)
+for snow accumulation, object capping, wrapped precipitation volumes, wet
+puddle masks, procedural ripple normals, splash placement, and debug outputs.
+
+For the base ground surface under the wetness or snow (asphalt, dirt, stone),
+generate a real texture with `npx genex texture` and load it via
+`$genex-ai-texture`, then build the precipitation response on top of it.
+Splash flipbook atlases and ripple normals stay procedural (for example a
+canvas-drawn expanding-ring atlas) — they are not generated assets.
+
+## Required controls
+
+- precipitation density and speed;
+- wind direction and strength;
+- shared weather progress or coverage;
+- wetness, snow, or puddle mask threshold and softness;
+- ripple or drift normal strength;
+- surface roughness response;
+- particle/splash opacity;
+- debug modes for masks, normals, particles, and event progress.
+
+## Failure conditions
+
+- falling precipitation ignores the wind or timing used by surface response;
+- snow height and snow normals come from different fields;
+- model snow sticks to vertical faces without an upward-facing filter;
+- puddles only lower roughness without a mask, normal response, or ripples;
+- splashes appear on downward or hidden faces;
+- rain streaks allocate per drop or fail to wrap around the camera;
+- temporal wetness is faked with unrelated time noise.
+
+## Routing boundary
+
+Use `$genex-threejs-water-optics` for bounded pool simulation, caustics, Fresnel,
+refraction, and Beer-Lambert water volumes. Use `$genex-threejs-procedural-vfx` for
+general sparks, plasma, trails, and non-weather particles. Use
+`$genex-threejs-temporal-surfaces` for screen-space touch history or frost clearing.
+This skill owns precipitation events and the surfaces they visibly alter.

package/templates/skills/genex-threejs-precipitation-surfaces/references/precipitation-surfaces.md

@@ -0,0 +1,181 @@
+# Precipitation Surface Systems
+
+Precipitation reads as real only when particles, surface masks, normals,
+roughness, and impact residue share the same event state. The following
+contracts describe two reusable families: snow accumulation and wet rain
+puddles.
+
+## Contents
+
+- Weather state contract
+- Wrapped precipitation volume
+- Snow accumulation contract
+- Object snow capping
+- Wet puddle contract
+- Rain streaks and splashes
+- Debug outputs
+- Boundaries and failure modes
+
+## Weather state contract
+
+Use a small shared state object for weather systems. The state is passed by
+reference into both particles and surfaces.
+
+```js
+const weather = {
+  uTime: { value: 0 },
+  uWind: { value: new THREE.Vector3(1.2, 0, 0.5) },
+  uProgress: { value: 0 },
+};
+
+function updateWeather(delta, target) {
+  weather.uTime.value += delta;
+  weather.uProgress.value = THREE.MathUtils.damp(
+    weather.uProgress.value,
+    target,
+    0.9,
+    delta,
+  );
+}
+```
+
+Do not give rain particles one clock and puddle ripples another. Do not sample
+wind in screen space for particles and world space for surfaces. The wind vector
+is horizontal and is interpreted as world units per second for moving
+precipitation, while scalar progress controls wetness or coverage.
+
+## Wrapped precipitation volume
+
+A camera-centered volume avoids finite emitter edges. Each instance stores a
+normalized spawn point and a random seed. The vertex shader turns that into a
+world position and wraps all axes with `mod`.
+
+```glsl
+vec3 origin = uCameraPos - vec3(vol.x * 0.5, vol.y * 0.4, vol.z * 0.5);
+float speed = uSpeed * (0.6 + 0.7 * aRand);
+vec3 base = aSeed * vol;
+vec3 disp = vec3(uWind.x, -speed, uWind.z) * uTime + sway;
+vec3 pos = mod(base + disp - origin, vol) + origin;
+```
+
+For snow, use soft round camera-facing billboards with opacity around `0.9`,
+flake radius around `0.07`, speed around `3.2`, and a horizontal sway near
+`0.5`. For rain, use narrow vertical or uneven-capsule billboards and a faster
+fall speed, commonly around `5` world units per second in an inspection-scale
+scene.
+
+## Snow accumulation contract
+
+Ground snow needs one height function. The same function displaces vertices and
+feeds finite-difference normals.
+
+```glsl
+float snowMaskAt(vec2 worldXZ) {
+  vec2 p = worldXZ * uSnowScale + uSnowSeed;
+  float n = fbm(p) * 0.5 + 0.5;
+  float threshold = 1.0 - uSnowCoverage;
+  return smoothstep(threshold - uSnowEdge, threshold + uSnowEdge, n);
+}
+
+float snowHeightAt(vec2 worldXZ) {
+  float mask = snowMaskAt(worldXZ);
+  float drift = fbm(worldXZ * uSnowBumpScale) * 0.5 + 0.5;
+  float h = mask * (1.0 - 0.4 * uSnowBumpStrength +
+                    0.4 * uSnowBumpStrength * drift);
+  vec2 edge = smoothstep(10.0, 8.0, abs(worldXZ));
+  return uSnowDepth * h * edge.x * edge.y;
+}
+
+vec3 groundSurfaceNormal(vec2 worldXZ) {
+  float e = 0.08;
+  float h0 = snowHeightAt(worldXZ);
+  float hx = snowHeightAt(worldXZ + vec2(e, 0.0));
+  float hz = snowHeightAt(worldXZ + vec2(0.0, e));
+  vec2 grad = vec2(hx - h0, hz - h0) / e;
+  return normalize(vec3(-grad.x, 1.0, -grad.y));
+}
+```
+
+The snow material response should override albedo toward a cool white, push
+roughness to roughly `0.82`, and add sparse sparkle only inside the snow mask.
+The sparkle is a material response, not a separate particle layer.
+
+## Object snow capping
+
+Object snow must be model-locked. Compute a world-to-model matrix for the host
+object and sample coverage in that coordinate space so moving or rotating the
+object does not slide the snow pattern.
+
+```glsl
+float snowAccumAt(vec3 worldNormal, vec2 modelXZ) {
+  float up = clamp(worldNormal.y, 0.0, 1.0);
+  float top = smoothstep(uSnowFlatThreshold, 1.0, up);
+  return top * snowCoverageMask(modelXZ);
+}
+```
+
+Typical controls are `uSnowFlatThreshold = 0.35`, `uSnowThickness = 0.06`,
+`uSnowCoverage = 0.7`, and `uSnowEdge = 0.15`. Displace along the object normal
+but convert from world units to local units using the mapped normal length.
+
+## Wet puddle contract
+
+Wet asphalt is a material transition driven by rain progress. Use separate
+progress bands: roughness changes early, ripple normals arrive as the rain
+becomes heavy.
+
+```glsl
+float roughnessProgress = smoothstep(0.0, 0.75, uRainFactor);
+float normalProgress = smoothstep(0.75, 1.0, uRainFactor);
+float puddleNoise = getPuddle(vPosition.xy * 15.0);
+float puddleMask = smoothstep(0.0, 1.0, puddleNoise) * normalProgress;
+```
+
+The puddle roughness is intentionally collapsed toward the `0.0..0.1` range
+inside the mask. Ripple normals are analytic: every local cell emits expanding
+rings with finite-difference slope estimation. Keep the ripple normal separate
+from the static asphalt normal until the final normal handoff.
+
+## Rain streaks and splashes
+
+Rain streaks can be instanced quads. Their fragment shape may use an uneven
+capsule SDF and alpha around `0.1 * rainProgress`. Splash placement should use
+surface sampling weighted by upward normals.
+
+```js
+const skyWeight = normal.dot(new THREE.Vector3(0, 1, 0)) >= 0 ? 1 : 0;
+geometry.setAttribute("skyWeight", new THREE.BufferAttribute(weights, 1));
+sampler.setWeightAttribute("skyWeight");
+```
+
+Each splash instance owns a progress attribute. A flipbook shader maps progress
+to a tile in a `4 x 5` atlas, fades by rain progress, and uses additive
+blending. The splash mesh should face the camera around Y.
+
+## Debug outputs
+
+Expose at least:
+
+- `final`: complete weather and surface response;
+- `mask`: snow or puddle coverage only;
+- `normals`: accumulated snow normal or ripple normal;
+- `particles`: precipitation density and fall volume;
+- `progress`: shared rain or snow envelope.
+
+Diagnostics should report active instance count, coverage, and whether the
+surface response is reading the same time/wind uniforms as particles.
+
+## Boundaries and failure modes
+
+Use a water-volume skill when the system needs refraction through a bounded
+water body, caustics, or Beer-Lambert thickness. Use a general VFX skill for
+non-weather particles. Use a screen-space temporal-surface skill for touch
+history, not for world-space wetness.
+
+Known failure modes:
+
+- snow silhouettes rise but normals stay flat;
+- object snow uses world coordinates and slides under animation;
+- puddle masks are independent of roughness and normal changes;
+- splashes sample all triangles and appear under objects;
+- rain progress affects particles but not the material, or the reverse.

package/templates/skills/genex-threejs-procedural-architecture/SKILL.md

@@ -29,7 +29,8 @@ Read [references/architecture-systems.md](references/architecture-systems.md) be
 - Compile by material slot to reduce draw calls without destroying material separation.
 - Preserve real dimensions for floor height, bay width, trim projection, and texture density.
 - Randomness may select among valid designs; it must not repair invalid geometry.
-- Provide topology, placement, material-slot, and UV-density debug modes.
+- Provide topology, façade ownership, material/geometry, and shadow diagnostics
+  appropriate to the renderer path.
 
 ## Acceptance
 

package/templates/skills/genex-threejs-procedural-architecture/references/architecture-systems.md

@@ -73,7 +73,7 @@ Seeded randomness perturbs constrained decisions:
 
 ```text
 towerScale = clamp(
-  authoredTowerScale + random(-0.05, 0.04),
+  settings.towerScale + random(-0.05, 0.04),
   0.62,
   0.96
 )

package/templates/skills/genex-threejs-procedural-fields/SKILL.md

@@ -43,11 +43,6 @@ Read [references/field-systems.md](references/field-systems.md)
 before implementation. It records sphere, terrain, water, and
 structured-placement field contracts plus common parity defects.
 
-Read the
-[procedural planet surface](../threejs-procedural-planets/examples/procedural-planet-surface/planet-system.js)
-for a shared CPU/GLSL field bundle whose height, continents, climate, biomes,
-roughness, and normals remain independently inspectable.
-
 ## Non-negotiable rules
 
 - Independent noise per channel produces visual soup. Share structure.

package/templates/skills/genex-threejs-procedural-geometry/SKILL.md

@@ -21,11 +21,6 @@ Read [references/mesh-systems.md](references/mesh-systems.md)
 for the exact sculpted-frame profile, rail emission, tree rings, semantic mesh
 writer, and their observed scaling limits.
 
-Read the
-[authored financial tower compiler](../threejs-procedural-architecture/examples/authored-financial-tower/building-system.js)
-for semantic placement compilation and material-slot instancing at building
-scale.
-
 ## Failure conditions
 
 - profile orientation flips along a curve;

package/templates/skills/genex-threejs-procedural-materials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-procedural-materials
-description: Author production procedural materials for Genex Three.js games. Use for PBR identity, terrain materials, atlas filtering, specular anti-aliasing, wetness, biome surfaces, dissolves, procedural normals, roughness variation, and readable materials across gameplay distances.
+description: Author production procedural materials for Genex Three.js games. Use for PBR identity, terrain materials, atlas filtering, specular anti-aliasing, wetness, lava and hot emissive surfaces, raymarched material fields, biome surfaces, dissolves, procedural normals, roughness variation, and readable materials across gameplay distances.
 ---
 
 # Genex Three.js Procedural Materials
@@ -23,21 +23,6 @@ Read [references/material-systems.md](references/material-systems.md)
 for atlas filtering, specular AA, planetary coordinates,
 world-height wetness, per-instance dissolve, and authored PBR response bundles.
 
-Read the
-[sculpted gallery frame geometry](../threejs-procedural-geometry/examples/sculpted-gallery-frame/frame-geometry.js)
-for walnut, antique-gold, and ebony texture/roughness/metalness/clearcoat
-bundles under a grazing-light setup.
-
-Read the
-[procedural planet surface](../threejs-procedural-planets/examples/procedural-planet-surface/planet-system.js)
-for shared geological, climate, water, biome, roughness, and derivative-normal
-causes on a procedural planetary surface.
-
-Read the
-[analytic wave optics](../threejs-water-optics/examples/analytic-wave-optics/water-system.js)
-for coupled reflection, refraction, absorption, filtered microstructure,
-resolved crest response, and their diagnostic channels.
-
 ## Required controls
 
 - real or perceptual texture scale;
@@ -46,7 +31,7 @@ resolved crest response, and their diagnostic channels.
 - the causal fields required by the selected material pattern;
 - distance/derivative filtering;
 - specular antialiasing;
-- channel and mask debug modes.
+- channel and mask debug modes;
 - emissive-material debug modes when the material owns glow or volumetric
   accumulation.
 

package/templates/skills/genex-threejs-procedural-vegetation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-procedural-vegetation
-description: Generate procedural vegetation for Genex Three.js games. Use for trees, trunks, roots, recursive branches, canopies, leaf cards, grass clumps, species presets, deterministic variation, growth forces, wind deformation, and vegetation that supports navigation or scene readability.
+description: Generate procedural vegetation for Genex Three.js games. Use for trees, trunks, roots, recursive branches, canopies, leaf cards, stylized meadow grass, GPU-computed grass fields, grass clumps, species presets, deterministic variation, growth forces, rooted blade and leaf wind, wind deformation, and vegetation that supports navigation or scene readability.
 ---
 
 # Genex Three.js Procedural Vegetation
@@ -24,10 +24,20 @@ Represent a plant as a growth hierarchy plus rendering adaptations. Do not model
 
 Read [references/vegetation-systems.md](references/vegetation-systems.md) and preserve its preset, continuation, child-placement, leaf, material, wind, and composition contracts before tuning.
 
+## Grass fields
+
+Grass is either instanced blade clusters (per-instance origin, facing, and
+height, with circular-arc rooted wind that bends blades from the ground up) or
+GPU-generated blade fields (blades written in render targets with Voronoi clump
+variation, folded blade curvature, and distance-based density falloff). Both
+keep terrain height and clump identity as shared causes; scattering blades with
+uniform randomness produces lawn noise, not a meadow.
+
 ## Visual failure conditions
 
 - branches form visible helices;
 - every child emerges at the same relative height;
+- dense grass ignores terrain height or clump-level variation;
 - bark texture scale changes with branch radius;
 - leaves reveal flat card normals under rotation;
 - leaf wind moves card roots instead of remaining anchored;

package/templates/skills/genex-threejs-procedural-vfx/SKILL.md

@@ -35,5 +35,7 @@ spark/debris pools, HDR hierarchy, and implementation limits.
 ## Routing boundary
 
 Use `$genex-threejs-temporal-surfaces` only for the screen-space
-frost/touch-history pipeline. Keep ship-space plasma, generated wakes, sparks,
+frost/touch-history pipeline. Use `$genex-threejs-precipitation-surfaces` for
+falling rain or snow, splash flipbooks, and weather events that alter ground
+materials. Keep ship-space plasma, generated wakes, sparks,
 and pooled debris in this skill.

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

@@ -19,11 +19,6 @@ Use a single shadow map only when its receiver region is genuinely bounded. For
 
 Read [references/shadow-systems.md](references/shadow-systems.md) before implementing a large-world directional light.
 
-Read the
-[cached shadow clipmaps](../threejs-procedural-architecture/examples/authored-financial-tower/shadow-clipmaps.js)
-for three light-space square levels, per-level texel snapping, containment
-cross-fades, cached coarse updates, scaled bias, and unshadowed outside weight.
-
 ## Failure conditions
 
 - projection centers move by fractions of a texel;

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

@@ -20,13 +20,14 @@ map, execution order, and acceptance gate.
 | reusable scalar/vector fields, domain warping, causal masks, procedural normals | `$genex-threejs-procedural-fields` |
 | atlas-filtered blocks, planetary surfaces, terrain wetness, lava/emissive procedural surfaces, authored frame PBR, specular AA | `$genex-threejs-procedural-materials` |
 | sculpted rails/frames, branch rings, semantic mesh writers, material groups | `$genex-threejs-procedural-geometry` |
-| trees, stylized grass, branching organisms, roots, foliage, rooted wind deformation | `$genex-threejs-procedural-vegetation` |
+| trees, stylized grass, GPU-computed grass fields, branching organisms, roots, foliage, rooted wind deformation | `$genex-threejs-procedural-vegetation` |
 | buildings, façade grammars, profiles, ornaments, modular mesh writers | `$genex-threejs-procedural-architecture` |
 | 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` |
+| 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` |
 | accumulated screen frost, touch clearing, reduced blur, and refraction masks | `$genex-threejs-temporal-surfaces` |
@@ -48,7 +49,9 @@ When the user wants a **specific, recognizable asset** (a named object, a descri
 sky, a particular sound or surface) rather than something authored in code, generate
 it with an `npx genex` command (run inside the project, where the `@genex-ai/cli-demo`
 dev dependency makes `genex` resolve to the right CLI). Each drops a real file into
-`./assets/` (committed by `npx genex publish`), and its skill has the exact Three.js
+`public/assets/<kind>/` so it ships with the built game — load it at runtime as
+`./assets/...` (the `public/` prefix is stripped when served; a bare `./assets/` dir
+would be dropped from the production build). Each skill has the exact Three.js
 loader code.
 
 | Work needed | Generate with | Skill |

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

@@ -18,7 +18,7 @@ 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. Select the minimum scene-generation skills: geometry, materials, vegetation,
-   architecture, planets, water, clouds, or VFX.
+   architecture, planets, water, precipitation, clouds, or VFX.
 3. Add camera direction when framing, controls, transitions, or scale perception
    affect play.
 4. Add procedural animation when object motion needs authored phases,

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-spectral-ocean
-description: Build large procedural oceans for Genex Three.js games. Use for FFT-style wave spectra, multi-cascade wave bands, choppy displacement, derivatives, whitecaps, temporal foam, ocean shading, camera-scale transitions, and GPU-budgeted open-water scenes.
+description: Build large procedural oceans for Genex Three.js games. Use for FFT-style wave spectra, multi-cascade wave bands, hybrid FFT plus Gerstner clear water, stylized above/below-surface ocean optics, choppy displacement, derivatives, Jacobian whitecaps, temporal foam, underwater absorption, crest scatter, ocean shading, camera-scale transitions, and GPU-budgeted open-water scenes.
 ---
 
 # Genex Three.js Spectral Ocean
@@ -22,6 +22,16 @@ Treat an ocean as a sampled stochastic wave field with explicit frequency-space
 
 Read [references/spectral-ocean.md](references/spectral-ocean.md) before implementing or auditing a spectral ocean.
 
+## Hybrid and stylized variants
+
+For clear shallow water, a hybrid ocean may add a few authored Gerstner swells on
+top of the FFT cascades — never instead of them — with Beer–Lambert depth color,
+sand-bed caustics, and sharp sun highlights. A stylized ocean meant to be seen
+from above and below can drive color from height gradients, add sun-path glints
+and crest scatter, and composite an underwater Beer–Lambert tint from scene
+depth. Both variants keep the spectral core, its derivatives, and Jacobian foam
+as the single source of surface truth.
+
 ## Non-negotiable gates
 
 - Require a power-of-two grid and a passing FFT impulse/frequency test.

package/templates/skills/genex-threejs-temporal-surfaces/SKILL.md

@@ -36,4 +36,6 @@ coupling, and implementation defects that must be corrected.
 ## Routing boundary
 
 Use `$genex-threejs-procedural-vfx` for world- or object-space residue, particles, and
-dissolves. This skill owns screen-space persistent history and its composite.
+dissolves. Use `$genex-threejs-precipitation-surfaces` for rain wetness, puddles,
+snow accumulation, and weather-surface coupling in world space. This skill owns
+screen-space persistent history and its composite.

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-water-optics
-description: Build analytic water surfaces for Genex Three.js games. Use for rivers, pools, lakes, shoreline water, shared wave displacement, normals, Fresnel, refraction, absorption, crest foam, underwater color, and cheaper water than a full spectral ocean.
+description: Build analytic water surfaces for Genex Three.js games. Use for rivers, pools, lakes, shoreline water, bounded heightfield pool simulation, object-driven ripples, differential-area caustics, ray-traced pool volume optics, shared wave displacement, normals, Fresnel, refraction, absorption, crest foam, underwater color, and cheaper water than a full spectral ocean.
 ---
 
 # Genex Three.js Water Optics
@@ -25,6 +25,16 @@ Read [references/water-optics.md](references/water-optics.md)
 for the exact five-wave displaced ocean, six-band normal-only water, optical
 hierarchy, and the limits that distinguish both from the spectral-ocean skill.
 
+## Bounded pool volumes
+
+A bounded pool couples a small RGBA heightfield simulation (height and velocity,
+with local drop injection and moving-object displacement) with the optical
+layer: normals derive from the simulated heights and feed differential-area
+caustics on the pool floor, and the water volume is shaded by ray-tracing
+against the pool bounds. Keep the simulation, the normal derivation, and the
+caustics reading the same field — a caustic pattern detached from the simulated
+surface is a failure condition below.
+
 ## Failure conditions
 
 - normal texture motion does not agree with displaced crests;
@@ -40,6 +50,8 @@ hierarchy, and the limits that distinguish both from the spectral-ocean skill.
 ## Routing boundary
 
 Use `$genex-threejs-spectral-ocean` for stochastic directional spectra, FFT
-cascades, Jacobian breaking, and persistent ocean foam. This skill owns
+cascades, Jacobian breaking, and persistent ocean foam. Use
+`$genex-threejs-precipitation-surfaces` for rain-driven puddle wetness, ripple
+masks, and weather-coupled splashes on ground surfaces. This skill owns
 authored analytic waves, bounded heightfield simulation, ray-traced
 pool-volume optics, and bounded-water optics.