@genex-ai/cli-demo 0.93.0 → 0.94.0-dev.249

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

@@ -1,232 +0,0 @@
-# Procedural field-stack recipes
-
-Use this reference to construct coherent field bundles for spherical terrain, altitude-filtered detail, terrain wetness, water optics, and structured stochastic placement.
-
-## Contents
-
-- 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
-
-
-## Stable coordinate ownership
-
-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.
-
-## pooled VFX system terrain coupling
-
-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
-
-Expose:
-
-```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

@@ -1,39 +0,0 @@
----
-name: genex-threejs-procedural-geometry
-description: Build procedural mesh systems for Genex Three.js games. Use for mesh writers, profile sweeps, rails, branches, frames, collision-aware shapes, UV density, custom normals, material groups, instancing decisions, and geometry that must hold up to close gameplay inspection.
----
-
-# Genex Three.js Procedural Geometry
-
-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 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.
-
-## 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,202 +0,0 @@
-# Sculpted profiles and semantic mesh emission
-
-Use this reference for reusable profile sweeps, rail skins and caps, oriented branch rings, semantic mesh writers, material slots, and geometry-level diagnostics.
-
-## Contents
-
-- 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
-
-
-## selective gallery pipeline sculpted frame profile
-
-The frame is not a beveled box. A normalized rail coordinate `t` drives a
-profile assembled from named lobes:
-
-```text
-crown:
-  0.355 * scale * sin(pi*t)^0.56
-
-inner bead:
-  0.105 * scale * exp(-((t - 0.085) / 0.033)^2)
-
-outer bead:
-  0.092 * scale * exp(-((t - 0.905) / 0.038)^2)
-
-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/references/material-systems.md

@@ -1,198 +0,0 @@
-# Procedural PBR material systems
-
-Use this reference for atlas filtering, shared shadow and light causes, planet-space material fields, wetness, per-instance dissolve, and authored physical-material identities.
-
-## Contents
-
-- atlas-based renderer block material
-- Atlas and minification response
-- Shared shadow/light causes
-- planet-space implementation planetary material
-- pooled VFX system terrain and debris
-- selective gallery pipeline authored PBR identities
-- Selection rules and limitations
-- Diagnostics
-
-
-## atlas-based renderer block material
-
-The block material is a complete custom shader whose inputs include:
-
-```text
-atlas albedo and optional normal
-per-vertex AO/skylight/tint color
-sun direction/color
-four custom shadow cascades
-projected procedural cloud shadow
-environment cube
-roughness/metalness
-daylight and starlight factors
-```
-
-Its useful material mechanisms are:
-
-1. world position and view-space depth remain available for cascade choice;
-2. world-space shadow texel width scales bias and filter radius;
-3. cloud shadow projects a receiver point to a cloud plane along sun direction;
-4. normal derivatives increase effective roughness;
-5. atlas sampling clamps to the current tile interior;
-6. anisotropic minification chooses a major-axis multi-tap filter.
-
-Specular antialiasing:
-
-```text
-variance =
-  max(dot(dFdx(N), dFdx(N)),
-      dot(dFdy(N), dFdy(N)))
-
-filteredRoughness =
-  clamp(sqrt(roughness^2 + variance), 0, 1)
-```
-
-This is a practical filtering mechanism. It should still be compared against the
-renderer’s current physical-material and normal-filtering behavior before
-replacing built-in shading.
-
-## Atlas and minification response
-
-For an atlas with `atlasSize` tiles across and `tileSize` texels per tile:
-
-```text
-tile width = 1 / atlasSize
-horizontal inset = 0.5 / (atlasSize * tileSize)
-vertical inset = 0.5 / tileSize
-```
-
-Estimate the `dFdx/dFdy` footprint in texels. When minification grows, blend
-away from the base sample. If anisotropy exceeds `2`, sample `7` or `9` taps
-along the major axis.
-
-This avoids adjacent-tile bleed for direct taps, but shader clamping cannot fix
-atlas mip levels that were generated without duplicated tile borders. Require
-offline mip-safe padding when adopting this mechanism.
-
-## Shared shadow/light causes
-
-atlas-based renderer’s cloud shadow uses the same conceptual field as its visible cloud
-layer:
-
-```text
-project receiver to cloud altitude along sun direction
-advect by shared wind and time scale
-evaluate the same five-octave cloud field
-apply coverage and density shaping
-attenuate direct sunlight
-```
-
-The material does not darken emission or all ambient response with this term.
-Keep projected environmental shadows attached to direct-light ownership.
-
-## planet-space implementation planetary material
-
-planet-space implementation’s solid planets preserve an undeformed radial attribute and use it for
-all geological sampling. Camera-altitude weights reduce high-frequency bump
-and optical detail.
-
-For gas and ice giants, seam-free longitude is represented as:
-
-```text
-longitude = atan(z, x)
-longitude circle = (cos(longitude + advection), sin(longitude + advection))
-coordinate = (circle.x, circle.y, latitude01)
-```
-
-Latitude bands, seeded warp, turbulence, and storm masks share this coordinate.
-Roughness responds to the same final mask. Limb haze and wrapped diffuse
-lighting are added separately.
-
-For solid bodies, procedural bump normal is derived from screen derivatives of
-the height node and view position. This keeps the renderer’s material lighting
-path while changing only the normal input.
-
-The known debt is geometry/material field mismatch; see the planet and field
-references. Do not infer that close bump can substitute for silhouette parity.
-
-## pooled VFX system terrain and debris
-
-Terrain identity:
-
-```text
-grassness = smoothstep(0.01, 1, normalWorld.y^1.6)
-color = mix(shared-noise soil, shared-noise grass, grassness)
-roughness = blend(soil response, grass response, grassness) - wetness
-metalness = 0.2
-```
-
-Wetness comes from world height near the water plane and the broad noise field.
-It changes roughness and color together.
-
-Debris uses per-instance `isOrange` and `removalTimeSeconds`. Geometry-space
-noise controls discard as lifetime expires. Its color is reinforced at the rim
-through Fresnel and receives a small environment term of `0.05`.
-
-The reusable pattern is per-instance material state, not one cloned material
-per object.
-
-## selective gallery pipeline authored PBR identities
-
-The gallery defines distinct frame surfaces with real texture and response
-bundles:
-
-| Surface | Roughness | Metalness | Clearcoat | Clearcoat roughness | Bump |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| walnut | 0.42 | 0.04 | 0.62 | 0.28 | 0.022 |
-| antique gold | 0.24 | 0.78 | 0.24 | 0.20 | 0.012 |
-| ebony | 0.40 | 0.03 | 0.70 | 0.24 | 0.018 |
-
-Wall plaster stays near roughness `0.94–0.96`, floor `0.92`, and mat board
-`0.92`. These ranges preserve material separation before bloom.
-
-Chandelier bloom meshes intentionally use `MeshBasicMaterial`, with bulb and
-filament materials marked `toneMapped = false`. That is contribution ownership
-for a stylized light source, not a physically based metal recipe.
-
-## Selection rules and limitations
-
-Use the material mechanisms according to representation:
-
-```text
-atlas voxel surface -> atlas-based renderer filtering and custom shadow hooks
-planet surface -> planet-space implementation radial fields and altitude filtering
-terrain/wetness -> pooled VFX system world-height causal blend
-authored luxury material -> selective gallery pipeline response bundle
-pooled effect debris -> pooled VFX system per-instance attributes
-```
-
-Do not combine every mechanism into one universal material.
-
-Exact node/material extension hooks are version-sensitive. Inspect the
-installed renderer before porting atlas-based renderer's full custom shader or adapting
-planet-space implementation's node-material normal and emissive inputs.
-
-Observed limits:
-
-- atlas-based renderer replaces the full physical shader, increasing maintenance and making
-  backend migration harder.
-- Its custom lighting must be checked for energy consistency and environment
-  parity.
-- selective gallery pipeline’s chandelier basic materials rely on selective bloom and are not a
-  substitute for lit metal in non-emissive views.
-- pooled VFX system uses undefined reversed-edge `smoothstep` in wetness expressions; write
-  portable equivalent logic.
-- planet-space implementation has approximate rather than exact geometry/material field parity.
-
-## Diagnostics
-
-Expose:
-
-```text
-atlas tile and sample footprint
-roughness before/after specular AA
-cloud shadow field
-shadow cascade and world texel size
-planet coordinate, altitude weights, and material masks
-terrain grassness and wetness
-debris instance attributes and dissolve threshold
-base frame material without post
-raw emissive contribution for bloom-only materials
-```