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

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

@@ -1,207 +0,0 @@
-# Touch-history frost accumulation
-
-Use this reference for screen-space frost whose visible mask and refractive response depend on persistent touch history, reduced-resolution scene blur, static crystalline fields, and two-scale normals.
-
-## Contents
-
-- Exact pass graph
-- Render-target ownership
-- Persistent pointer state
-- Frost composite
-- Refraction output
-- Observed defects and required corrections
-- Diagnostic contract
-
-
-## Exact pass graph
-
-The frame graph owns these targets:
-
-| Target | Resolution | Lifetime | Purpose |
-| --- | --- | --- | --- |
-| root | display DPR | every frame | source scene |
-| vertical blur | `0.4` DPR | every frame | first separable blur axis |
-| horizontal blur | `0.4` DPR | every frame | broad blurred source |
-| frost composite | display DPR | every frame | scene, blur, structure, interaction |
-| pointer read/write | display DPR, half-float | persistent | touched/cleared history plus tilt |
-| frost noise | `0.4` DPR | once | coarse crystalline structure |
-| frozen noise | display DPR | once | dense frozen structure |
-| highlight noise | display DPR | once | highlight breakup |
-
-Per-frame order is fixed:
-
-```text
-root scene
-  -> vertical blur
-  -> horizontal blur
-  -> frost composite
-  -> pointer history write and swap
-  -> display output samples the new frost target
-```
-
-The frost pass therefore reads the pointer state from the previous completed
-frame. Preserve that one-frame history relationship unless changing it
-deliberately and validating the response.
-
-## Render-target ownership
-
-The single-target helper:
-
-1. stores `renderer.autoClear`;
-2. sets the requested clear mode;
-3. binds the target;
-4. renders;
-5. restores the default target;
-6. restores `autoClear`;
-7. disposes the target on owner teardown.
-
-The double-target helper writes only to `write`, exposes `read.texture` before
-the draw, swaps after the draw, and returns the new `read.texture`.
-
-```text
-read = completed state
-write = destination for this update
-render(write, sampling read)
-swap(read, write)
-```
-
-Both targets resize together. A production adaptation must also define whether
-resize preserves, resamples, or clears state. The hook resizes the
-targets but does not explicitly clear both histories.
-
-## Persistent pointer state
-
-The pointer target uses:
-
-```text
-R = accumulated interaction mask
-A = accumulated tilt-response mask
-G/B = duplicate R in the output
-```
-
-Defaults:
-
-```text
-decay per rendered frame = 0.002
-noise strength = 0.16
-frost-noise strength = 0.10
-mask strength = 0.30
-radius = 0.15 -> 0.17
-corner fade = 0.50 -> 0.60
-side fade = 0.00 -> 0.50
-```
-
-The update is:
-
-```text
-previous = max(previous - decay, 0)
-center = pointer * 0.5 + 0.5
-distance = aspect-corrected distance to center
-deposit = edge-masked noisy radial brush when touching
-Rnext = clamp(Rprevious + noisyDeposit, 0, 1)
-Anext = clamp(Aprevious + lower-noiseDeposit, 0, 1)
-```
-
-The side and corner masks keep a circular deposit from clipping abruptly at
-viewport boundaries. The alpha channel deliberately uses a less noisy brush so
-device tilt can react smoothly while the visible thaw/frost boundary stays
-irregular.
-
-## Frost composite
-
-The frost pass inverts pointer history:
-
-```text
-clearAmount = 1 - pointer.R
-```
-
-It combines three static structures:
-
-```text
-base structure = mix(frozenNoise, highlightNoise, 0.30)
-coarse frost = contrast(frostNoise * 1.70 + frostAmount, 1.60)
-mask = contrast(base structure + coarse frost * clearAmount, 1.80)
-```
-
-The scene treatment is coupled:
-
-```text
-blurMix = clamp(clearAmount * (mask + 0.30), 0, 1)
-scene = mix(sharpScene, blurredScene, blurMix)
-scene *= (0.90, 0.90, 1.03)
-saturation *= 1.20
-brightness *= 0.70
-```
-
-Frost color then mixes:
-
-```text
-thin tint  = (0.82, 0.86, 1.05)
-thick tint = (0.92, 0.96, 1.10)
-frost tint strength = 0.70
-highlight tint strength = 0.80
-```
-
-The composite alpha stores the structural frost mask before the pointer is
-applied. The output pass uses that alpha to gate normal-map refraction.
-
-## Refraction output
-
-The final pass samples two mirrored-repeat normal maps in screen coordinates:
-
-```text
-main scale size = 1200, strength = 0.30
-sub scale size = 350, strength = 2.0
-IOR = 1.31
-thickness = 1.0
-source inset = 0.17
-Fresnel strength = 0.80
-```
-
-The main map also produces a grayscale height weight for the sub-map. Device
-tilt rotates the view vector, with pointer alpha contributing up to `0.8`.
-Refraction is mixed only where both frost alpha and the inverse pointer mask
-permit it.
-
-## Observed defects and required corrections
-
-Do not preserve these weaknesses silently:
-
-- Pointer decay is per frame, not per second. Convert it to
-  `1 - exp(-rate * deltaSeconds)` or an equivalent time-based update.
-- The alpha-aware blur divides RGB and alpha by `sumW`. Fully transparent
-  neighborhoods can make `sumW == 0`; guard with an epsilon and define the
-  transparent result.
-- Blur alpha is accumulated with unmodified kernel weights but divided by the
-  alpha-weighted RGB denominator. Treat RGB normalization and alpha
-  normalization separately.
-- Pointer aspect is assigned from the low-resolution target although pointer
-  state is high resolution. The ratio is normally equal, but ownership should
-  use the actual pointer target.
-- Static targets opt out of auto-resize. A resize policy must regenerate or
-  remap them.
-- Screen-space state follows the viewport, not the depicted surface. Do not use
-  this representation for world footprints or object-bound paint.
-
-## Diagnostic contract
-
-Expose:
-
-```text
-root scene
-vertical blur
-horizontal blur
-each static noise target
-previous pointer R/A
-current deposit R/A
-next pointer R/A
-frost mask before pointer
-frost mask after pointer
-sharp/blur mix
-main and sub refraction offsets
-final without refraction
-final
-```
-
-Add pause and single-step controls. Verify decay at 30, 60, and 120 FPS after
-correcting it to time-based behavior.

package/templates/skills/genex-threejs-visual-validation/references/visual-validation.md

@@ -1,427 +0,0 @@
-# Graphics validation protocol
-
-Use this protocol to evaluate authored graphics through deterministic final
-frames, mechanism-isolation views, temporal evidence, scale tests, seed sweeps,
-and explicit GPU budgets.
-
-## Contents
-
-- Acceptance principle
-- Visual contract
-- Required inspection controls
-- Mechanism-specific evidence
-- No-post and isolation gates
-- Determinism and captures
-- Temporal validation
-- Performance and resolution
-- Rejection criteria
-- Sign-off record
-
-## Acceptance principle
-
-Accept an implementation only when all four layers agree:
-
-```text
-declared visual mechanism
-  -> inspectable implementation
-  -> diagnostic evidence
-  -> final image that satisfies the visual contract
-```
-
-Code plausibility is insufficient. A visually weak result means the mechanism
-is incomplete, misweighted, or badly presented. A beautiful final frame is
-also insufficient when it hides field instability, broken depth, temporal
-failure, or dependence on post-processing.
-
-## Visual contract
-
-Write this before tuning:
-
-```ts
-type VisualContract = {
-  subject: string
-  identity: string[]
-  silhouette: string[]
-  materialSeparation: string[]
-  motion: string[]
-  cameraEnvelope: {
-    near: number
-    design: number
-    far: number
-  }
-  lightingEnvelope: string[]
-  invariants: string[]
-  allowedDivergences: string[]
-  frameBudgetMs: number
-  memoryBudgetMB?: number
-}
-```
-
-Each invariant must be observable. Replace “looks cinematic” with statements
-such as:
-
-```text
-the primary rim remains visible without bloom
-the water horizon does not reveal the mesh boundary
-tree card roots remain attached under maximum wind
-planet coast width is stable from orbit to mid approach
-cloud history rejects across a foreground disocclusion
-```
-
-When matching a supplied visual reference, record the mechanisms that create
-its identity and every deliberate divergence in backend, resolution, asset,
-scale, or composition. Do not substitute a generic category match for the
-specific visual contract.
-
-For a Meshy player character, the pre-animation sign-off record additionally
-contains:
-
-```text
-two or three discussed visual directions
-the inspected references, when the user named one
-three actual concept-image URLs, all neutral A-pose
-the user's selected candidate
-high-detail source URL in R2
-front / back / left / right high-detail views
-measured high-detail face count
-the user's explicit approval of the separate 10,000-face triangle remesh
-```
-
-Do not accept a dynamic-pose concept, a silent T-pose fallback, or a rig built
-from the unremeshed high-detail source. Warn before generation when held,
-slung, or overlapping props and straps can fuse into the body or hide limbs.
-Animation naturally leaves the A-pose; its limb rotations remain native.
-Never freeze or correct arm, hand, leg, or foot tracks. Only horizontal root or
-hip translation may be normalized for Rapier.
-
-## Required inspection controls
-
-Any runnable inspection surface should expose the controls relevant to its
-mechanism:
-
-```text
-pause / resume
-fixed time or time scale
-fixed seed
-fixed camera bookmarks
-viewport and DPR
-quality tier
-debug mode
-canvas capture
-runtime metrics
-reset history
-```
-
-At minimum, provide:
-
-- one design camera;
-- near and far camera bookmarks;
-- final and no-post views;
-- every controlling field or pass needed to prove the mechanism;
-- a deterministic reset;
-- visible runtime errors and performance metrics.
-
-Controls must alter the actual pipeline. A debug dropdown that only changes a
-label is worse than no diagnostic because it creates false confidence.
-
-## Mechanism-specific evidence
-
-### Procedural growth
-
-Report topology separately from final composition:
-
-```text
-branch jobs by level
-terminal continuations by level
-lateral children by level
-ring and leaf-card counts
-branch and leaf bounds
-seed
-```
-
-Inspect:
-
-- hierarchy-only;
-- continuation branches;
-- foliage roots and rounded normals;
-- final composition;
-- maximum wind;
-- at least three seeds.
-
-The species identity must survive the seed sweep. Seed changes may alter
-branch placement and crown asymmetry; they may not turn one growth model into
-another.
-
-### Spectral water
-
-Require:
-
-```text
-disjoint wavelength ownership per cascade
-independent FFT impulse and frequency tests
-height and horizontal displacement fields
-transformed derivative maps
-Jacobian or breaking metric
-persistent foam history
-shared sky/reflection parameters
-```
-
-Inspect individual cascades, resolved normals, breaking/foam state, and final
-shading. A plausible ocean frame does not prove that the FFT, derivatives, or
-history are correct.
-
-### Analytic water
-
-Require displacement and normals to derive from the same wave bundle. Inspect:
-
-```text
-displacement only
-resolved normals
-Fresnel
-reflection
-refraction
-absorption or thickness estimate
-crest response and foam
-```
-
-Test near-grazing views, far-horizon minification, and a high-DPR capture.
-Reject sparkling micro-bands that survive below one pixel.
-
-### Planet fields and atmosphere
-
-Require:
-
-```text
-undeformed sphere direction
-macro height
-continents and coast
-climate or biome causes
-resolved normals and roughness
-surface lighting without atmosphere
-atmosphere only
-combined final
-```
-
-Inspect orbit, mid approach, and close approach. Surface and atmosphere must
-share body center, radius, sun direction, and scale conversion. A shell that
-looks acceptable only against black space is not sufficient evidence of
-ground-to-space continuity.
-
-### Volumetric clouds
-
-Require:
-
-```text
-weather channels
-base-shape density
-detail erosion
-bounded ray interval
-beauty transmittance
-lighting contribution
-history confidence or rejection
-cloud shadow
-```
-
-Test camera translation, foreground disocclusion, sun-angle changes, and
-quality-tier transitions. Still frames cannot validate temporal reconstruction.
-
-### Curved-ray and volumetric effects
-
-Expose:
-
-```text
-integration bounds
-step or iteration count
-accumulated steering
-density contribution
-remaining transmittance
-background lookup direction
-capped or invalid pixels
-```
-
-Use a stress camera that approaches the singular or highest-curvature region.
-Reject NaNs, persistent capped bands, and unexplained asymmetry.
-
-### Temporal surfaces
-
-Expose the complete state transition:
-
-```text
-previous history
-current deposit or erase input
-next history
-blurred scene
-static structure
-composite mask
-resolved normal/refraction
-```
-
-Test reset, resize, pointer release, repeated deposition, frame-rate changes,
-and long idle decay. Per-frame decay must be converted to a
-frame-rate-independent response.
-
-### Shadows and post-processing
-
-For shadows, inspect:
-
-```text
-level ownership
-committed light-space centers
-texel grid
-levels refreshed this frame
-cross-level blend weights
-normal bias in world units
-unshadowed outside-coverage weight
-```
-
-For post effects, inspect the pre-effect signal, contribution, and final
-composite. Tone mapping and output conversion must have one owner.
-
-## No-post and isolation gates
-
-Every example with image effects must expose:
-
-```text
-final
-no bloom or presentation treatment
-effect contribution only
-controlling field or mask
-normal / depth / history when relevant
-```
-
-Reject when:
-
-- bloom supplies the only readable silhouette;
-- atmosphere hides flat planet fields;
-- post blur hides aliasing;
-- a normal map implies waves absent from displaced geometry;
-- temporal output cannot show previous state, deposit, and next state;
-- a raymarch cannot reveal iteration pressure or capped pixels;
-- shadows are judged only in the final graded image.
-
-## Determinism and captures
-
-Freeze:
-
-```text
-seed
-camera transform and projection
-viewport
-DPR
-time or paused state
-quality tier
-backend
-asset versions
-```
-
-Capture:
-
-```text
-design view
-near/detail view
-far/silhouette view
-no-post baseline
-one controlling diagnostic
-one failure-sensitive diagnostic
-one stress condition
-```
-
-Use exact camera matrices or named camera bookmarks. Reproducing a comparison
-by manually orbiting until it “looks close” invalidates image evidence.
-
-For stochastic pixels, either freeze the stochastic sequence or compare a
-stable accumulated result. Do not loosen image thresholds until they stop
-detecting real regressions.
-
-## Temporal validation
-
-Use fixed-duration clips or sampled checkpoints for:
-
-- camera motion;
-- object motion;
-- history accumulation and rejection;
-- shadow-cache refresh;
-- ocean foam persistence;
-- cloud reconstruction;
-- wind deformation;
-- particle birth, death, and pool reuse.
-
-Record at least:
-
-```text
-t = 0 reset
-t = first visible response
-t = steady state
-t = disocclusion or invalidation
-t = recovery
-```
-
-Inspect at normal playback speed and frame-by-frame. Still captures cannot
-prove the absence of shimmer, swimming, stale history, or lifetime pops.
-
-## Performance and resolution
-
-Report:
-
-```text
-CPU frame time
-GPU frame time when available
-draw calls
-triangles / points / instances
-simulation resolution
-render-target count, format, and dimensions
-active quality tier
-cache updates this frame
-estimated GPU memory
-```
-
-Never infer GPU cost solely from CPU frame time. Run a warm-up period before
-recording and separate shader compilation from steady-state cost.
-
-When reducing quality, identify the preserved mechanism and expected loss:
-
-| Reduction | Preserve | Expected loss |
-| --- | --- | --- |
-| lower cloud beauty resolution | density organization and lighting | edge fidelity and thin wisps |
-| fewer atmosphere view steps | shared scattering model | horizon smoothness |
-| smaller spectral grids | cascade and FFT architecture | high-frequency wave richness |
-| reduced shadow update budget | stable committed maps | delayed coarse-level refresh |
-| lower frost blur DPR | history and structure | refraction smoothness |
-
-Do not silently lower resolution until a frame looks fast enough.
-
-## Rejection criteria
-
-Delete or withhold an example when any applies:
-
-- it is visually weaker than the supplied reference in the target feature;
-- its code is mostly generic material or noise boilerplate;
-- mechanism-defining constants or ownership were replaced by guesses;
-- it has no diagnostic mode proving the claimed mechanism;
-- it relies on post-processing to manufacture missing form;
-- it contains undisclosed backend, algorithm, asset, or scale divergences;
-- deterministic reset or fixed-camera capture is impossible;
-- the implementation cannot meet its declared performance envelope;
-- the available evidence is too weak to support excellence-level guidance.
-
-## Sign-off record
-
-Record:
-
-```text
-skill and example ID
-visual contract and invariants
-Three.js version and backend
-viewport, DPR, camera bookmark, seed, and time
-mechanisms exercised
-deliberate divergences
-debug modes inspected
-temporal cases inspected
-performance and memory metrics
-known defects
-review decision
-```
-
-Publish only accepted examples. Repeat the same evidence set whenever
-mechanism code, Three.js version, renderer backend, camera, or quality tier
-changes.

package/templates/skills/genex-threejs-volumetric-clouds/SKILL.md

@@ -1,49 +0,0 @@
----
-name: genex-threejs-volumetric-clouds
-description: Build volumetric cloud systems for Genex Three.js games. Use for weather-shaped density, bounded raymarching, cloud layers, erosion detail, lighting cones, silver lining, temporal reconstruction, cloud shadows, quality tiers, and sky drama with controlled budgets.
----
-
-# Genex Three.js Volumetric Clouds
-
-**Static clouds in a fixed sky → `$genex-ai-skybox` instead** (one command, a
-real 360° image). This skill is for moving, weather-driven, or fly-through
-clouds.
-
-Cloud quality comes from density organization, lighting, and temporal stability—not from increasing march steps over unstructured noise.
-
-## System order
-
-1. Define the cloud volume and layer bounds.
-2. Generate or source weather, base-shape, detail, and turbulence fields.
-3. Build a density function with vertical and weather profiles.
-4. Raymarch only the bounded occupied segment.
-5. Integrate transmittance and lighting front-to-back.
-6. Reconstruct low-resolution output temporally.
-7. Project a separate low-cost cloud-shadow solution.
-
-Read [references/volumetric-clouds.md](references/volumetric-clouds.md) before implementing or auditing the cloud system.
-
-## Required controls
-
-- coverage, cloud type, precipitation, and anvil bias;
-- base/top altitude and vertical density profile;
-- shape/detail scales and erosion;
-- wind for each field;
-- primary step count, light step count, and empty-space policy;
-- history weight and disocclusion threshold;
-- cloud-shadow extent, resolution, and update rate.
-
-## Failure conditions
-
-- density is only `fbm(position)`;
-- the raymarch traverses the full camera range;
-- detail noise adds density instead of eroding shaped masses;
-- temporal history is accepted across disocclusion;
-- shadows use the full beauty raymarch;
-- every cloud layer shares the same wind and density profile.
-
-## Routing boundary
-
-Use `$genex-threejs-atmosphere-aerial-perspective` for molecular/aerosol scattering
-without weather density. This skill owns weather-shaped cloud volumes,
-reconstruction, cloud lighting, and cloud shadows.