@genex-ai/cli-demo 0.6.0 → 0.6.2

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

@@ -1,35 +1,232 @@
-# Field Systems
+# Procedural field-stack recipes
 
-Use this guide to build reusable fields for Genex scenes.
+Use this reference to construct coherent field bundles for spherical terrain, altitude-filtered detail, terrain wetness, water optics, and structured stochastic placement.
 
-## Field stack
+## Contents
 
-- `base`: low-frequency silhouette or terrain structure.
-- `detail`: mid-frequency material and shape variation.
-- `micro`: high-frequency normals or roughness, filtered by distance.
-- `mask`: semantic influence such as water, biome, damage, snow, or wear.
-- `flow`: vector direction for wind, particles, waves, or erosion.
+- Stable coordinate ownership
+- planet-space implementation sphere fields
+- Altitude filtering
+- pooled VFX system terrain coupling
+- atlas-based renderer water field coupling
+- Structured stochastic placement
+- Cross-system implementation contract
+- Diagnostics
 
-## Domain rules
 
-- World-space fields should not swim when objects move.
-- Object-space fields should travel with the mesh.
-- UV-space fields should be reserved for authored assets or atlases.
-- Screen-space fields should never drive persistent world identity.
+## Stable coordinate ownership
 
-## Diagnostics
+The strongest common rule is that one stable coordinate domain owns related
+visual channels.
+
+planet-space implementation stores normalized undeformed sphere direction in a
+`surfaceDirection` attribute. Terrain shader fields sample:
+
+```text
+terrainCoordinateKm = normalize(surfaceDirection) * radiusKm
+```
+
+They do not sample the interpolated displaced position. This prevents noise
+stretching over steep relief and allows orbit/close-detail filtering in the
+same kilometer domain.
+
+pooled VFX system terrain samples `positionWorld`, because wetness is tied to a world water
+height. atlas-based renderer water also samples world XZ so near tiles and far ocean quads
+share wave phase.
+
+Choose coordinates from the cause:
+
+```text
+planet geology -> undeformed radial direction * physical radius
+water/wetness -> shared world plane
+tree growth -> branch-local longitudinal and radial coordinates
+```
+
+## planet-space implementation sphere fields
+
+The planet material performs tangential warp:
+
+```text
+warp = three seeded noise channels - 0.5
+tangentWarp = warp - radial * dot(warp, radial)
+warpAmplitudeKm = max(radiusKm * 0.012, 36)
+warped = normalize(terrainKm + tangentWarp * warpAmplitudeKm) * radiusKm
+```
+
+Its broad terrain synthesis uses separated bands:
+
+```text
+macro A frequency = 0.00034, weight 0.52
+macro B frequency = 0.00092, internal scale 0.52, weight 0.33
+ridge frequency = 0.0029, weight 0.25
+crater-like frequency = 0.0069, exponent 2.9
+```
+
+The CPU geometry uses a different deterministic value-noise stack:
+
+```text
+continental: 5 octaves, lacunarity 2.03, gain 0.50
+highlands: 4 octaves, lacunarity 2.15, gain 0.55
+ridges: 4 octaves, lacunarity 2.08, gain 0.52
+crater-like: 3 octaves, pow(1 - noise, 3.2)
+```
+
+This mismatch is an observed defect, not a recommended pattern. The material
+mixes only `8%` actual geometry displacement into shader macro height. A new
+implementation should share one deterministic field or validate CPU/GPU parity
+at fixed sphere directions.
+
+Derived climate causes in this field stack:
+
+```text
+humidity =
+  0.65 * broadNoise(0.0022)
+  + 0.35 * detailNoise(0.0075)
+
+temperature =
+  (1 - abs(latitude)^1.35) * 0.85
+  + 0.15
+  - macroHeight * 0.32
+
+slope =
+  1 - abs(dot(localNormal, radialDirection))
+```
+
+Snow, arid, lush, and rock masks combine those fields with altitude, ridges,
+and a smaller jitter field. The important mechanism is causal reuse, not the
+specific color palette.
+
+## Altitude filtering
+
+planet-space implementation computes:
+
+```text
+cameraAltitude = max(distance(camera, center) - radius, 0)
+detailAltitude = min(cameraAltitude, externally supplied detail altitude)
+
+near = max(radius * 0.022, 6.5)
+mid  = max(radius * 0.11, 24)
+far  = max(radius * 0.50, 140)
+
+nearWeight = 1 - smoothstep(near, mid, detailAltitude)
+farWeight = smoothstep(mid, far, detailAltitude)
+midWeight = clamp(1 - nearWeight - farWeight, 0, 1)
+```
+
+These weights attenuate bump, coastline sharpness, wave detail, clearcoat, and
+micro material variation. The frequencies remain stable; contribution fades.
 
-Expose a way to render:
+## pooled VFX system terrain coupling
 
-- raw field values;
-- threshold masks;
-- gradient or normal direction;
-- warped versus unwarped domains;
-- seed variations;
-- near and far camera views.
+The pooled VFX system terrain material uses three world-space noise bands:
+
+```text
+noise1: position * (0.2, 1, 0.2), amplitude 0.05, bias 0.2
+noise2: position * 9, amplitude 0.4, bias 0.5
+noise3: position * (14, 3, 14), amplitude 2, bias 0.5
+soilNoise = noise1 + noise2 + noise3
+```
+
+Surface identity derives from geometry orientation:
+
+```text
+grassness = smoothstep(0.01, 1, normalWorld.y^1.6)
+color = mix(soilColor, grassColor, grassness)
+```
+
+The same identity blends soil and grass roughness fields. World height adds a
+wetness response near the water level:
+
+```text
+wetness = smoothstep(-1, -7, positionWorld.y) * noise1 * 3.5
+roughness -= wetness
+```
+
+The reversed-looking edges are intentional GLSL `smoothstep` usage in the
+source but are undefined by the GLSL specification when `edge0 > edge1`.
+Rewrite as `1 - smoothstep(-7, -1, y)` for portable behavior.
+
+## atlas-based renderer water field coupling
+
+atlas-based renderer evaluates six directional wave bands in one function and returns:
+
+```text
+RGB = analytic normal from summed gradients
+A = crest metric derived from the same slopes and phases
+```
+
+Wavelengths:
+
+```text
+12, 6, 2.5, 5.25, 3.0, 1.5 world units
+```
+
+Amplitudes relative to the base:
+
+```text
+1.0, 0.55, 0.22, 0.12, 0.08, 0.05
+```
+
+The three smallest bands are attenuated from screen derivatives using their
+wavenumbers. Foam consumes the returned crest metric; it does not sample an
+unrelated scrolling mask.
+
+## Structured stochastic placement
+
+`branch-growth implementation` demonstrates a different kind of field: constrained discrete
+placement. Child branches use stratified longitudinal slots and independently
+permuted angular slots. Randomness selects within valid slots rather than
+choosing every position freely.
+
+That same mechanism applies to:
+
+```text
+branch emergence
+façade variants
+particle burst directions
+crater distribution
+cloud-cell placement
+```
+
+When a pattern must remain authored, stratify the domain before applying
+random jitter.
+
+## Cross-system implementation contract
+
+Before coding, record:
+
+```text
+coordinate domain
+physical/perceptual units
+primary fields
+derived causes
+consuming channels
+filtering rule
+CPU/GPU parity requirement
+seed ownership
+```
+
+Reject a field stack when:
+
+- color, roughness, and normal use unrelated structure;
+- geometry and shading claim the same feature but evaluate different functions;
+- a categorical mask is only a narrow noise threshold;
+- high-frequency terms survive after their projected footprint is subpixel;
+- world effects use object coordinates or planetary effects use flat world Y;
+- random placement has no strata, budget, or semantic constraints.
+
+## Diagnostics
 
-## Performance
+Expose:
 
-- Share field functions between CPU generation and shader paths when possible.
-- Cache generated textures that do not change every frame.
-- Use lower resolution or fewer octaves for far-distance fields.
+```text
+source coordinates
+tangential warp vector
+each frequency band
+actual geometry height versus shader height
+humidity, temperature, slope, and identity masks
+near/mid/far weights
+water normal and crest from the same evaluation
+wetness by world height
+seed and stratification cells
+```

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

@@ -5,26 +5,40 @@ description: Build procedural mesh systems for Genex Three.js games. Use for mes
 
 # Genex Three.js Procedural Geometry
 
-Procedural geometry should have semantic structure, stable normals, and a clear
-budget. Build mesh writers that explain what they emit.
-
-Read [references/mesh-systems.md](references/mesh-systems.md) for profile
-sweeps, mesh writers, normals, UVs, and validation.
+Generate geometry from a semantic plan and an explicit coordinate frame. Triangle emission is the final compilation step, not the design model.
 
 ## Build order
 
-1. Define semantic parts and gameplay purpose before vertices.
-2. Choose topology: instanced primitives, merged mesh, skinned mesh, or custom
-   buffer geometry.
-3. Emit positions, normals, UVs, indices, material groups, and bounds together.
-4. Keep resolution tied to screen distance or gameplay importance.
-5. Generate collision/proxy geometry separately when needed.
-6. Add debug modes for wireframe, normals, groups, UV density, and bounds.
-
-## Rules
-
-- Avoid procedural meshes with unnamed arrays and no semantic parts.
-- Keep winding, normals, and tangent expectations consistent.
-- Use material groups deliberately; do not create one material per tiny piece.
-- Recompute bounds after generated changes.
-- Dispose old geometries and materials on regeneration.
+1. Define dimensions and semantic segments.
+2. Generate a centerline, boundary, profile, or placement plan.
+3. Build the mechanism-appropriate local parameterization or branch orientation.
+4. Emit vertices with intentional seams and material ownership.
+5. Generate UVs from real distance.
+6. Validate winding, normals, tangents, bounds, and degenerates.
+7. Select merging, instancing, or LOD by update and material behavior.
+
+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;
+- caps reuse side vertices and create averaged edge normals;
+- UV scale changes with segment count;
+- arbitrary vertex merging destroys hard edges or material boundaries;
+- generated dimensions are hidden in magic multipliers;
+- instancing is used despite per-instance topology differences;
+- triangle count is the only reported complexity metric.
+
+## Routing boundary
+
+This skill owns reusable mesh emission. Use
+`$genex-threejs-procedural-architecture` for a building grammar and
+`$genex-threejs-procedural-vegetation` for a growth hierarchy; those subject skills
+may then apply these geometry mechanisms.

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

@@ -1,36 +1,202 @@
-# Mesh Systems
+# Sculpted profiles and semantic mesh emission
 
-Use this guide for reusable procedural mesh writers.
+Use this reference for reusable profile sweeps, rail skins and caps, oriented branch rings, semantic mesh writers, material slots, and geometry-level diagnostics.
 
-## Mesh writer contract
+## Contents
 
-A mesh writer should declare:
+- selective gallery pipeline sculpted frame profile
+- Rail mesh emission
+- Semantic dimensions and material fit
+- Tree ring emission
+- production WebGPU pipeline mesh writer
+- Selection and LOD
+- Observed limitations
+- Diagnostics
 
-- input seed and parameters;
-- emitted semantic parts;
-- vertex and triangle budget;
-- material slots;
-- UV convention;
-- bounds and collision proxy behavior;
-- regeneration and disposal policy.
 
-## Profile sweeps
+## selective gallery pipeline sculpted frame profile
 
-- Define a 2D profile with named control points.
-- Sweep along a path with stable tangent, normal, and binormal frames.
-- Add caps intentionally.
-- Keep UV length proportional to world distance.
-- Expose cross-section debug lines.
+The frame is not a beveled box. A normalized rail coordinate `t` drives a
+profile assembled from named lobes:
 
-## Normals and UVs
+```text
+crown:
+  0.355 * scale * sin(pi*t)^0.56
 
-- Use smooth normals for organic forms and split normals for hard surfaces.
-- Avoid accidental smoothing across material or silhouette seams.
-- Keep UV density consistent across parts that share a material.
-- Validate mirrored or repeated UV islands against normal maps.
+inner bead:
+  0.105 * scale * exp(-((t - 0.085) / 0.033)^2)
 
-## Instancing
+outer bead:
+  0.092 * scale * exp(-((t - 0.905) / 0.038)^2)
 
-Use instancing when many pieces share geometry and material. Avoid instancing
-when each piece needs unique topology, unique material state, or separate
-collision behavior that dominates the cost.
+inner groove:
+  -0.115 * scale * exp(-((t - 0.205) / 0.043)^2)
+
+outer groove:
+  -0.102 * scale * exp(-((t - 0.735) / 0.052)^2)
+
+shoulder:
+  0.045 * scale * exp(-((t - 0.42) / 0.15)^2)
+
+cove:
+  -0.035 * scale * exp(-((t - 0.61) / 0.095)^2)
+```
+
+`scale = railWidth / 0.75`. The inner and outer ends are blended to controlled
+terminal depths, preventing a crown shape from meeting the artwork or wall
+with an accidental vertical edge.
+
+The profile uses `92` samples. This is deliberate high curvature
+resolution for close hero framing, not a universal default.
+
+## Rail mesh emission
+
+Each of four orientations has its own coordinate mapping. The profile travels
+across the rail width while `s` travels along the frame side. Top/bottom rails
+use `132` length segments; left/right use `156`.
+
+For every profile sample and length sample, emit:
+
+```text
+top vertex at profile depth
+bottom vertex at fixed backing depth
+UV = (s, t)
+```
+
+Then emit:
+
+```text
+top skin
+bottom skin
+inner wall
+outer wall
+two end caps
+```
+
+The index winding helper emits:
+
+```text
+a, b, c
+b, d, c
+```
+
+Normals are computed after all faces are assembled; a bounding sphere is also
+computed. Four rail meshes meet at miter-like endpoints because their length
+shrinks/expands as `t` moves from inner to outer edge.
+
+## Semantic dimensions and material fit
+
+The frame dimensions are derived:
+
+```text
+innerWidth = postWidth
+innerHeight = innerWidth / embedAspectRatio
+railWidthX = (outerWidth - innerWidth) / 2
+railWidthY = (outerHeight - innerHeight) / 2
+profileRailWidth = min(railWidthX, railWidthY)
+art card Z = rail offset + profileDepth(innerRimT)
+```
+
+This keeps artwork, mat, frame profile, and backing coupled. Avoid tuning their
+Z positions independently.
+
+The same file pairs the geometry with walnut, antique-gold, and ebony material
+bundles. Geometry is judged under grazing spotlights and shadow maps, so profile
+depth must create readable highlights without bloom.
+
+## Tree ring emission
+
+`branch-growth implementation` emits branches as oriented rings. Every branch section owns:
+
+```text
+center
+orientation
+radius
+longitudinal fraction
+branch level
+```
+
+Ring vertices use branch-local radial angle and an explicit seam. Bark UV
+length follows branch length and circumference instead of normalizing every
+branch to identical density.
+
+Child branches are generated from the growth hierarchy before geometry is
+batched. This separation makes it possible to lower radial segments by level
+without changing topology ownership.
+
+Leaf cards use canopy-oriented normals rather than only card-plane normals,
+showing that generated shading attributes can intentionally differ from
+geometric face normals.
+
+## production WebGPU pipeline mesh writer
+
+The architecture compiler accumulates vertices and indices by
+material slot. Modules emit semantic geometry into a shared writer rather than
+constructing one `Mesh` each.
+
+Preserve this contract:
+
+```text
+module plan
+  -> transformed semantic vertices
+  -> triangles tagged with material slot
+  -> grouped BufferGeometry
+```
+
+The writer also keeps module transforms and real dimensions outside raw buffer
+code. This allows façade, roof, cornice, and ornament generators to share
+emission without sharing design logic.
+
+## Selection and LOD
+
+Use:
+
+```text
+custom profile mesh
+  when silhouette and grazing response define identity
+
+oriented rings
+  when hierarchy and taper define identity
+
+semantic mesh writer
+  when many varied modules must batch by material
+
+instancing
+  only when topology is identical and variation is attribute/transform based
+```
+
+Derive LOD from the generator:
+
+- reduce profile samples while retaining crown and groove extrema;
+- reduce branch radial segments by branch level;
+- replace ornaments with relief only after silhouette contribution is small;
+- preserve UV density and material slots across levels.
+
+## Observed limitations
+
+- selective gallery pipeline computes smooth normals across all connected frame faces. If hard
+  backing edges become visible, duplicate vertices by smoothing group.
+- Its profile and segment counts are expensive for many frames. Cache geometry
+  by dimension set and add a lower-detail authored profile.
+- The four rails are separate meshes; a larger gallery may need material-based
+  merging after transforms are fixed.
+- Global `computeVertexNormals()` cannot infer semantic hard edges.
+- Generic mesh decimation may erase the narrow beads and grooves that create
+  the frame’s material response.
+
+## Diagnostics
+
+Expose:
+
+```text
+profile curve with named lobe contributions
+profile sample indices
+rail orientation and top/bottom skins
+face winding and normal direction
+UV checker
+frame/art/backing depth relationship
+tree branch rings and seams
+material groups from the mesh writer
+triangle, vertex, group, and draw counts
+LOD overlay at the design camera
+```

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

@@ -5,26 +5,63 @@ description: Author production procedural materials for Genex Three.js games. Us
 
 # Genex Three.js Procedural Materials
 
-Materials should communicate object identity, state, and gameplay affordance.
-Build them from shared fields and inspectable parameters.
+Build a material from surface identity and causes. Color, roughness, metalness, normal, transmission, and emission should describe the same surface—not unrelated noise textures.
 
-Read [references/material-systems.md](references/material-systems.md) for PBR
-roles, filtering, masks, and shader handoff patterns.
+## Material graph order
 
-## Build order
+```text
+stable coordinates
+  → structural fields
+  → material identity weights
+  → causal modifiers
+  → filtered microstructure
+  → PBR channels
+  → lighting/shadow extensions
+```
 
-1. Define material identity: base color family, metalness, roughness, normal
-   scale, edge wear, and gameplay state.
-2. Choose field causes for variation before writing shader code.
-3. Derive color, roughness, normals, wetness, and emission from named masks.
-4. Add distance-aware filtering for micro detail.
-5. Keep a no-post preview where the material still reads.
-6. Expose debug toggles for albedo, roughness, normals, masks, and emission.
+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.
 
-## Rules
+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.
 
-- Do not rely on bloom or grading to make a weak material interesting.
-- Keep roughness variation physically plausible for the object.
-- Filter high-frequency normals and atlas lookups to reduce shimmer.
-- Treat emission as authored signal, not a blanket glow.
-- Make damage, wetness, heat, or dissolve follow a stable mask.
+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;
+- material identity weights;
+- roughness range and micro-normal strength;
+- the causal fields required by the selected material pattern;
+- distance/derivative filtering;
+- specular antialiasing;
+- channel and mask debug modes.
+- emissive-material debug modes when the material owns glow or volumetric
+  accumulation.
+
+## Failure conditions
+
+- every PBR channel samples independent noise;
+- roughness is a scalar afterthought;
+- high-frequency normals survive below one pixel;
+- triplanar projection has visible orientation or scale seams;
+- atlas padding is ignored under mipmapping;
+- custom lighting removes energy conservation without an explicit stylized goal;
+- post-processing is used to hide unstable highlights.
+
+## Routing boundary
+
+Use `$genex-threejs-procedural-fields` when the main problem is designing shared
+scalar/vector causes. Use `$genex-threejs-procedural-planets` for a complete
+orbit-to-close-approach body, not merely its material.