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

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

@@ -1,187 +0,0 @@
-# HDR bloom systems
-
-Use this reference to choose bloom ownership, signal order, selective contribution, and scene-relative emissive ranges without making bloom responsible for the underlying form.
-
-> **Renderer note:** this reference assumes `WebGPURenderer` + TSL node materials. Check the project's actual renderer first — the Genex scaffold ships vanilla WebGL three.js. On WebGL, adapt the technique with standard materials / `EffectComposer` passes or pick a simpler alternative; never switch renderers mid-project. Either way the effect obeys the device tier (`$genex-threejs-adaptive-quality`): expensive passes are desktop-tier, and on WebGPU the per-target MSAA sample count is a runtime knob the governor may drive.
-
-## Contents
-
-- production WebGPU pipeline signal order
-- production WebGPU pipeline bloom controls
-- selective gallery pipeline selective ownership
-- Material substitution invariant
-- atlas-based renderer baseline
-- pooled VFX system HDR hierarchy
-- Implementation limits
-- Diagnostics
-
-
-## production WebGPU pipeline signal order
-
-The WebGPU pipeline owns bloom before exposure and render output:
-
-```text
-scene pass
-  -> optional GTAO composite
-  -> optional atmosphere
-  -> bloom node
-  -> sampled scene + bloom
-  -> eye-adaptation exposure
-  -> renderOutput / tone map
-  -> optional 3D LUT
-  -> optional FXAA
-```
-
-The render pipeline disables its automatic output color transform and assigns
-one final output node. Preserve this one-owner rule when adapting to current
-Three.js `RenderPipeline`.
-
-## production WebGPU pipeline bloom controls
-
-Bloom defaults:
-
-```text
-enabled = false
-strength = 0
-radius = 0.35
-threshold = 0.72
-smooth width = 0.08
-```
-
-The Three.js bloom node reads the HDR texture produced after atmosphere. Its
-strength becomes zero when disabled; radius, threshold, and smooth width remain
-independently updateable.
-
-This path does not implement a custom pyramid. Its contract is signal placement
-and parameter ownership around the renderer’s bloom node.
-Verify the installed Three.js node API before using the exact constructor or
-property names.
-
-## selective gallery pipeline selective ownership
-
-The gallery uses two separate selective bloom pipelines:
-
-```text
-neon layer -> neon UnrealBloomPass
-chandelier layer -> chandelier UnrealBloomPass
-base scene -> final composer
-
-final = base + neon bloom + chandelier bloom
-```
-
-Each bloom composer renders off-screen. A final shader adds both bloom textures
-to the base render, then an `OutputPass` performs display output.
-
-Separate ownership lets neon animation change strength/radius without forcing
-the chandelier glow to share the same threshold or spread.
-
-Chandelier bulbs, filaments, and glow meshes use unlit materials; bulb and
-filament materials set `toneMapped = false`. The pipeline therefore combines
-explicit layer membership with material-level HDR/display behavior.
-
-## Material substitution invariant
-
-For each selective pass, selective gallery pipeline traverses visible meshes and replaces every
-non-member material with one shared black material.
-
-Required transaction:
-
-```text
-set active bloom layer
-traverse visible meshes
-record { mesh, original material }
-replace non-members with shared black material
-try:
-  render bloom composer
-finally:
-  restore every recorded material
-  clear restoration list
-```
-
-Support material arrays by storing the complete original `mesh.material`
-value. Also toggle the high-detail and simplified
-chandelier representations so only the intended version contributes.
-
-The `finally` block is non-negotiable. Without it, a render error permanently
-blackens scene meshes.
-
-## atlas-based renderer baseline
-
-atlas-based renderer wraps `UnrealBloomPass` with:
-
-```text
-strength = 0.30
-radius = 0.50
-threshold = 0.05
-```
-
-Composer order:
-
-```text
-scene -> SSAO -> volumetrics -> bloom -> lens flare -> fog/color
-```
-
-This is a useful comparison, not the quality target — note its fog/color stage runs AFTER bloom, deviating from the canonical order in $genex-threejs-image-pipeline (fog belongs before bloom so bright fog does not glow). The threshold is very low
-and can bloom ordinary bright surfaces. The wrapper exposes only enabled,
-strength, and threshold, while radius stays at its constructor value.
-
-## pooled VFX system HDR hierarchy
-
-pooled VFX system assigns compact effect luminance before bloom:
-
-```text
-spark initial RGB multiplier = 80
-homing projectile = 30
-laser = 10
-```
-
-These values establish a material-level contribution hierarchy, but they do
-not define the bloom pass. Validate them against actual renderer exposure
-before reuse.
-
-Use the relationship, not the raw numbers:
-
-```text
-short spark flash
-  > projectile core
-  > persistent laser
-  > ordinary lit surface
-```
-
-## Implementation limits
-
-- selective gallery pipeline renders the scene multiple times for selective bloom. This is
-  acceptable for its bounded gallery but expensive for large scenes.
-- Temporary material substitution can trigger shader/program changes and must
-  account for newly added meshes.
-- The final selective gallery pipeline composite adds bloom textures directly; energy is
-  artistic, not physically conserved.
-- atlas-based renderer’s low threshold is not evidence for a general HDR calibration.
-- production WebGPU pipeline depends on version-sensitive Three.js bloom-node behavior.
-- pooled VFX system material multipliers are scene-relative and cannot be treated as
-  exposure-independent units.
-
-Prefer a dedicated contribution target when MRT/backend architecture supports
-it and the scene cannot afford multiple full renders. Validate that decision
-against the target scene’s measured cost and contribution masks.
-
-## Diagnostics
-
-Expose:
-
-```text
-HDR scene before bloom
-false-color luminance
-neon contribution
-chandelier contribution
-each bloom result
-base without bloom
-final composite
-active layer membership
-material restoration count and leak assertion
-transparent-emitter contribution
-bloom GPU time per render
-```
-
-Acceptance requires the base frame to retain form and material hierarchy with
-both bloom textures disabled.

package/templates/skills/genex-threejs-exposure-color-grading/references/exposure-grading.md

@@ -1,205 +0,0 @@
-# Scene-referred exposure and color pipeline
-
-Use this reference for a measured HDR-to-display path with encoded luminance readback, asymmetric adaptation, one tone-map owner, and a generated display-domain 3D LUT.
-
-## Contents
-
-- Exact pipeline order
-- Luminance meter
-- Exposure target and adaptation
-- 3D LUT construction
-- LUT placement
-- Tone mapping ownership
-- Observed limitations
-- Diagnostics
-
-
-## Exact pipeline order
-
-The pipeline computes:
-
-```text
-HDR scene after AO/atmosphere
-  -> bloom added in HDR
-  -> multiply by adapted exposure
-  -> renderOutput using renderer tone mapping
-  -> saturate to LUT domain
-  -> sample 3D LUT
-  -> blend LUT intensity
-  -> optional FXAA
-```
-
-`RenderPipeline.outputColorTransform` is disabled and one output node owns the
-final conversion. Renderer tone-mapping mode and renderer exposure are still
-configuration inputs to `renderOutput`.
-
-## Luminance meter
-
-The implementation renders a `64 x 36` meter target using unsigned bytes. It encodes
-unbounded luminance:
-
-```text
-encoded = luminance / (luminance + 1)
-decoded = encoded / max(0.0001, 1 - encoded)
-```
-
-Readback occurs asynchronously every `12` frames by default. While one readback
-is pending, another is not started.
-
-CPU reduction uses weighted log average:
-
-```text
-weight = 1.0 when luminance > 0.002
-weight = 0.15 otherwise
-
-average =
-  exp(sum(log(max(luminance, 0.0001)) * weight) / sum(weight))
-```
-
-This suppresses black-pixel dominance without requiring a histogram.
-
-## Exposure target and adaptation
-
-Defaults:
-
-```text
-minimum exposure = 0.45
-maximum exposure = 1.85
-middle gray = 0.18
-compensation = 0 EV
-speed up = 3.2
-speed down = 1.1
-```
-
-Target:
-
-```text
-target =
-  clamp(
-    middleGray / averageLuminance
-    * 2^exposureCompensation,
-    minExposure,
-    maxExposure
-  )
-```
-
-Frame-rate-independent adaptation:
-
-```text
-speed = target > current ? speedUp : speedDown
-amount = 1 - exp(-max(deltaSeconds, 0) * speed)
-current += (target - current) * amount
-```
-
-When disabled, current and target reset to `1`.
-
-## 3D LUT construction
-
-Build a `32^3` RGBA `Data3DTexture` with linear filtering, clamp wrapping, no
-mipmaps, and unsigned-byte storage.
-
-Each preset recipe owns:
-
-```text
-contrast
-saturation
-vibrance
-black/white point
-per-channel gamma
-shadow/midtone/highlight tint
-strength for each tonal range
-```
-
-Recipe order:
-
-```text
-normalize black/white range
-S-curve blend, fixed amount 0.44
-contrast around 0.5
-shadow tint
-midtone tint
-highlight tint
-per-channel gamma
-saturation
-vibrance
-small highlight glow bias
-clamp to [0, 1]
-```
-
-Tonal weights are calculated from pre-grade luminance:
-
-```text
-shadow = 1 - smoothstep(0.12, 0.54, luma)
-highlight = smoothstep(0.48, 0.92, luma)
-midtone = max(0, 1 - abs(luma - 0.5) * 2)
-```
-
-## LUT placement
-
-The LUT samples tone-mapped display-linear RGB after saturation:
-
-```text
-uv = saturate(displayColor.rgb) * ((32 - 1) / 32) + 0.5 / 32
-graded = texture3D(lut, uv)
-final = mix(displayColor, graded, lutIntensity)
-```
-
-This means the included recipes are authored for a bounded post-tone-map
-domain. Do not move them before tone mapping without rebuilding the recipes and
-documenting a scene-linear or log domain.
-
-## Tone mapping ownership
-
-Available renderer modes include:
-
-```text
-None, Linear, Reinhard, Cineon, ACES, AgX, Neutral
-```
-
-Color defaults:
-
-```text
-tone mapping = ACES
-renderer exposure = 0.72
-LUT = Real Daylight
-LUT intensity = 1
-```
-
-The feature factory initially disables LUT intensity and eye adaptation until
-enabled through settings. Distinguish configuration defaults from active
-feature state.
-
-## Observed limitations
-
-- The meter has no center weighting, percentile clipping, sky mask, or UI mask.
-- Unsigned-byte encoding loses precision near extreme luminance.
-- Readback cadence is frame-count based, so wall-clock cadence changes with
-  frame rate.
-- A failed readback resets target exposure to `1`, which can cause a visible
-  adaptation shift.
-- LUT generation clamps every entry to `[0,1]`; it is display-domain grading,
-  not HDR scene-referred grading.
-- The pipeline exposes both renderer `toneMappingExposure` and a separate
-  adapted exposure multiplier. Their combined ownership must be documented to
-  avoid accidental double exposure.
-- FXAA is applied after grading, but dithering/gamut compression are absent.
-
-## Diagnostics
-
-Expose:
-
-```text
-meter source
-encoded meter target
-decoded luminance
-weight mask
-measured average
-target/current exposure over time
-readback pending and cadence
-HDR before exposure
-tone-mapped before LUT
-neutral versus selected LUT
-per-recipe tonal weights
-clipped/out-of-domain mask
-final with one exposure stage disabled at a time
-```

package/templates/skills/genex-threejs-game-content/SKILL.md

@@ -1,198 +0,0 @@
----
-name: genex-threejs-game-content
-description: Turn a content-shaped request — quests, NPCs, dialogue, shops, loot, XP — into a countable content contract and the data-driven systems that ship it. Use when the ask names game content in the plural or a content genre (RPG, adventure, story, open world), BEFORE the asset batch, and before calling such a game done.
----
-
-# Genex Three.js Game Content
-
-The most common way a content-shaped request fails is not bad code — it is the
-ask silently shrinking: "quests" ships as one hardcoded integer, "NPCs" as
-empty textured huts, "a big world" as one small fogged plane, while every
-visual floor passes, because content is invisible to a screenshot. This skill
-gives content the same teeth the look has: a countable contract written up
-front, data-driven systems that make each contract line cheap to ship, and a
-floor that gates publish.
-
-## The content contract — write it before the asset batch
-
-Run this the moment the game concept is locked, in the SAME plan message as
-`$genex-threejs-game-ui`'s UI gate, whenever the request names content in the
-plural (quests, enemies, bosses, locations, spells, items, factions…) or a
-content genre (an RPG, an adventure, an open world, a story game, a survival
-game). **Walk every plural noun of the request and make each one a countable
-line.** The template:
-
-```
-CONTENT CONTRACT — <game>
-world:       <size class, as a number: one arena | a district (~500 m) | open world (km-class — $genex-threejs-open-world)>
-ground:      <the terrain as a DECISION: flat plane | rolling relief | heightfield; water: none | river/lake/sea>
-locations:   <N, named: village, crypt, bandit camp, watchtower, boss lair…>
-quests:      <N total — a main chain of M gated steps + side quests; each giver named>
-NPCs:        <N speaking (quest givers, merchants) + M flavor villagers>
-enemies:     <N types + where they spawn; which are bosses and what makes each boss FIGHT differently>
-progression: <what grows: XP/levels, gear tiers, learnable abilities — the numbers and their rewards>
-economy:     <currency sources AND sinks — what the player earns and what they spend it on>
-minute ten:  <one sentence: what is the player DOING ten minutes in, and why is it different from minute one?>
-```
-
-Rules that make the contract real:
-
-- **It comes before the asset batch.** The asset set derives from the
-  contract — a world with six locations and four enemy types needs a
-  different `npx genex model` list than one arena, and finding that out after
-  the batch means the world gets shaped around the wrong assets.
-- **Every line is a floor.** Publish and the final handoff wait for the
-  contract's countables exactly the way they wait for the sprite HUD: a
-  request that said "quests" is not done with one; a request that said "big
-  world" is not done with an arena.
-- **Scope belongs to the user.** Building a small first slice is the right
-  ORDER (`$genex-threejs-game-ui`'s v0 beat still applies) — but the slice is
-  a milestone on the way to the contract, never a quiet replacement for it.
-  If the full ask genuinely doesn't fit, shrinking any line is a
-  question to the user with real options — never a silent cut justified as
-  "standard practice". (Use your question tool when you have one; if you
-  have none, a short numbered list in chat.)
-- **Minute ten is the design test.** If the honest answer is "the same sixty
-  seconds, again", the contract needs another beat (a new area unlocks, a
-  quest chain escalates, a build comes online) before any polish work.
-- **The `ground:` line is a decision, not a default.** Flat is fine when
-  DECIDED — but the concept frame the user approved is a promise: if it shows
-  rolling hills or a shoreline and the game ships a flat plane, that visible
-  gap goes through one plain line to the user, exactly like any other cut
-  ($genex-threejs-open-world owns real relief when the answer is yes).
-
-## Data-driven, or you won't finish in one session
-
-The reason a solo agent can ship seven quests and seventeen items in an
-afternoon is architecture, not typing speed:
-
-- **Systems read tables; content lives in tables.** The quest engine, the
-  dialogue walker, the merchant screen, and the spawner are each written
-  ONCE; quest #5, item #12, and enemy #4 are table rows. If adding a quest
-  means touching engine code, the engine is wrong.
-- **Hand-author the beats, table-drive the bulk, seed the placement.** Quest
-  prose, boss mechanics, and location identities deserve human-quality
-  authoring; stats, stocks, and rewards are data; trees, rocks, and chest
-  scatter come from a seeded RNG so "more world" costs zero authoring.
-- **One event bus.** Quests advance on events the game already emits
-  (`enemy:died`, `item:pickup`, `chest:opened`, `npc:talked`, `zone:entered`)
-  — the quest system subscribes; combat and loot never know quests exist.
-  This is also what makes quest logic testable in isolation.
-
-The full engine — quest defs + state machine, dialogue trees with quest
-hooks, merchant stocks, XP curve — is in
-[references/content-tables.md](references/content-tables.md) as copy-paste
-modules. Copy them and fill the tables; don't re-derive the shape.
-
-## Quests: defs + events, never an integer
-
-The minimum honest quest system is a table of defs and an event-driven state
-machine (`locked → available → active → ready → done`), with prereq gating for
-the main chain:
-
-```ts
-type Objective =
-  | { kind: "kill"; target: string; count: number }
-  | { kind: "collect"; item: string; count: number }
-  | { kind: "reach"; location: string }
-  | { kind: "talk"; npc: string };
-
-type QuestDef = {
-  id: string;
-  giver: string;            // NPC id — every quest has a face, not a board
-  prereq?: string;          // quest id that must be done first (main chain)
-  title: string;
-  brief: string;            // 2–3 sentences of authored prose, not filler
-  objective: Objective;
-  rewards: { gold?: number; xp?: number; items?: string[] };
-};
-```
-
-Progress comes only from the event bus (see the reference for the ~60-line
-engine). A tracked quest gets a compass/journal marker
-(`$genex-threejs-game-ui` inventories the journal as a screen element), and
-turn-in happens in dialogue — handing in a quest should feel like talking to
-a person, not watching a counter flip.
-
-## Dialogue: trees with quest hooks
-
-Quest givers and merchants speak. The walker is a dozen lines (reference file)
-over nodes of `{ text, options: [{ label, next | action }] }`; what makes it a
-QUEST system is three dynamic option states injected per NPC: **offer** (quest
-available → "I might have work for you"), **remind** (active → restate the
-objective), **turn-in** (ready → hand rewards, open the next chain link). Add
-a couple of lore branches per named NPC — three authored lines is the
-difference between a person and a signpost. A quest board is an acceptable
-extra for arcade-shaped games; it is never the replacement for speaking
-NPCs when the ask said "NPCs".
-
-## Items, shops, and an economy that closes
-
-An item catalog (id, kind, price, stats), stack-based inventory, and merchant
-stock tables per vendor NPC — all data (reference file). The rule that keeps
-it a game: **currency needs sinks.** Gold the player can only accumulate is a
-score with a coin icon; gold that buys potions, a better sword, and a spell
-tome is an economy. Price the first upgrade to be affordable after the first
-quest, and let drops + chest loot + quest rewards all feed the same wallet.
-
-## Progression: something must grow
-
-Pick at least one growth axis and wire its rewards into the quest/enemy
-tables: an XP curve (`xpNext = 100 * level ** 1.4` is a fine default) with
-flat stat gains per level, gear tiers on the merchant, or learnable abilities
-gated behind tomes/trainers. The contract names which; "nothing grows" is what
-makes minute ten feel like minute one.
-
-## NPCs: the minimum that reads as alive
-
-A named NPC with a role, a home spot, an idle bob, a face-the-player turn
-within a few meters, and dialogue reads as a person — schedules and pathing
-are optional upgrades, speech is not. Place speaking NPCs (givers, merchants)
-by hand at their locations; scatter flavor villagers with one-line barks from
-a table. An empty textured hut village fails the "NPCs" line of any contract.
-For host-simulated NPCs/enemies in multiplayer, `$genex-threejs-multiplayer`
-owns the authority rules.
-
-## Content that can't dead-end — check before shipping
-
-- A kill/collect quest counts progress made BEFORE acceptance (or the brief
-  says why not) — "kill 5 bandits" accepted after clearing the camp must not
-  strand at 0/5.
-- A quest item from a unique source (a boss drop, a one-time chest) must
-  persist until picked up — the source never respawns, so expiring the drop
-  dead-ends the chain.
-- The main chain gates on prereqs, not on geography alone — reaching the
-  final lair early should show a locked door or a warning, not a sequence
-  break that skips the story.
-- The turn-in NPC is reachable after the objective (didn't die in the wave,
-  isn't locked behind the boss arena).
-- Saves restore quest state AND its world side-effects — the opened chest
-  stays open, the armed boss stays armed. Quest stages, inventory, XP, and
-  gold go in the per-player slot via `$genex-threejs-embed-auth`.
-
-## Wiring into the rest of the pack
-
-- World layout, terrain, and location placement at scale:
-  `$genex-threejs-open-world` (the contract's `world:` line decides whether
-  it loads).
-- Quest journal, tracker, toasts, vendor screens: inventory them at
-  `$genex-threejs-game-ui`'s gate — they are screen elements like any other.
-- Level-ups, quest completion, and boss kills are exactly the "moments" the
-  feel pass layers feedback on: `$genex-threejs-game-feel` + a real
-  `npx genex sfx` fanfare (`$genex-ai-sfx`).
-- Location set pieces and speaking-NPC meshes: `$genex-ai-model` /
-  `$genex-ai-character` — generated assets decorate the contract's landmarks;
-  they never decide how many exist.
-
-## Failure modes to catch
-
-- "Quests" (plural, in the ask) shipped as one quest — a stage integer with
-  hardcoded strings and no giver.
-- A village of textured huts where nobody speaks.
-- A gold counter with nothing to spend it on.
-- No growth axis: the player at minute thirty plays exactly like minute one.
-- The contract posted, then quietly abandoned when the first slice previewed
-  well — the slice is a milestone, not the destination.
-- Contract lines silently shrunk without a structured question to the user.
-- The approved concept frame shows rolling hills or water; the game ships one
-  flat plane and nobody said so.