@genex-ai/cli-demo 0.59.0-dev.133 → 0.59.0-dev.136

package/dist/index.js

@@ -72,16 +72,20 @@ function resolveAgentTargets(opts = {}) {
     return [{ id: "custom", label: "workspace", baseDir: path.resolve(opts.dir), full: true }];
   }
   const home = os.homedir();
+  const projectRoot = process.cwd();
   let ids;
   if (opts.agents && opts.agents.length > 0) {
     ids = opts.agents.filter((id) => KNOWN_AGENTS[id]);
   } else {
-    ids = KNOWN_AGENT_IDS.filter((id) => isDir(path.join(home, KNOWN_AGENTS[id].dirName)));
+    ids = KNOWN_AGENT_IDS.filter((id) => {
+      const dirName = KNOWN_AGENTS[id].dirName;
+      return isDir(path.join(home, dirName)) || isDir(path.join(projectRoot, dirName));
+    });
     if (ids.length === 0) ids = ["claude"];
   }
   return ids.map((id) => {
     const def = KNOWN_AGENTS[id];
-    return { id, label: def.label, baseDir: path.join(home, def.dirName), full: def.full };
+    return { id, label: def.label, baseDir: path.join(projectRoot, def.dirName), full: def.full };
   });
 }
 function isDir(p) {
@@ -242,6 +246,7 @@ async function exists(p) {
 
 // src/lib/updates.ts
 import fs3 from "fs/promises";
+import os3 from "os";
 import path3 from "path";
 function parseSemver(v) {
   const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
@@ -292,8 +297,53 @@ async function syncSkillsForTarget(target, templatesDir = getTemplatesDir(), ver
   await writeSkillsMarker(skillsDir, version);
   return true;
 }
+async function cleanupLegacyGlobalSkills(log) {
+  try {
+    const home = os3.homedir();
+    const [realCwd, realHome] = await Promise.all([
+      fs3.realpath(process.cwd()).catch(() => path3.resolve(process.cwd())),
+      fs3.realpath(home).catch(() => path3.resolve(home))
+    ]);
+    if (realCwd === realHome) return false;
+    let removed = false;
+    for (const dirName of [".claude", ".codex", ".cursor"]) {
+      const skillsDir = path3.join(home, dirName, "skills");
+      let entries = [];
+      try {
+        entries = await fs3.readdir(skillsDir);
+      } catch {
+        continue;
+      }
+      for (const name of entries) {
+        if (!name.startsWith("genex-")) continue;
+        try {
+          await fs3.rm(path3.join(skillsDir, name), { recursive: true });
+          removed = true;
+        } catch {
+        }
+      }
+    }
+    for (const rel of [
+      path3.join("agents", "genex-helper.md"),
+      path3.join("commands", "genex-status.md")
+    ]) {
+      try {
+        await fs3.rm(path3.join(home, ".claude", rel));
+        removed = true;
+      } catch {
+      }
+    }
+    if (removed) {
+      log?.plain("\u{1F9F9} Removed legacy GLOBAL Genex skills \u2014 installs are project-local now");
+    }
+    return removed;
+  } catch {
+    return false;
+  }
+}
 async function syncSkills(log) {
   try {
+    await cleanupLegacyGlobalSkills(log);
     const version = getCliVersion();
     const templatesDir = getTemplatesDir();
     let refreshed = false;
@@ -1123,6 +1173,7 @@ async function runInit(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex init"));
   log.plain("");
+  await cleanupLegacyGlobalSkills(log);
   const templatesDir = getTemplatesDir();
   const targets = resolveAgentTargets({ dir: opts.dir, agents: opts.agents });
   log.step(
@@ -1439,7 +1490,7 @@ function relTime(iso) {
 import { spawn as spawn3 } from "child_process";
 import crypto3 from "crypto";
 import fs9 from "fs/promises";
-import os3 from "os";
+import os4 from "os";
 import path10 from "path";
 function run(cmd, args, env) {
   return new Promise((resolve) => {
@@ -1666,7 +1717,7 @@ async function pushWorktree(cwd, pushUrl, managed, log) {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const gitDir = await fs9.mkdtemp(path10.join(os3.tmpdir(), "genex-source-"));
+  const gitDir = await fs9.mkdtemp(path10.join(os4.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   const ident = {
     GIT_AUTHOR_NAME: "genex",
@@ -13545,7 +13596,7 @@ async function uiSeams(opts, log) {
 
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture", "image", "video"]);
-var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize, and publish 3D games.
+var HELP = `${c.bold("genex")} \u2014 set up your project's agent workspace, authorize, and publish 3D games.
 
 ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.59.0-dev.133",
-  "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
+  "version": "0.59.0-dev.136",
+  "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
     "genex": "./dist/index.js"

package/templates/README.md

@@ -1,9 +1,10 @@
 # Genex workspace
 
-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.
+These files were installed by `genex init` into THIS project's agent
+workspace — Claude Code (`.claude/`), Codex (`.codex/skills/`), and Cursor
+(`.cursor/skills/`) inside the game folder, whichever agents it detected.
+Nothing is installed globally; delete the folder and every trace is gone.
+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.

package/templates/agents/genex-helper.md

@@ -6,8 +6,9 @@ tools: Read, Grep, Glob
 
 You are the Genex helper agent — an example subagent installed by `genex init`.
 
-Your job is to help the user understand and navigate their `~/.claude`
-workspace: the skills, agents, and commands installed by Genex.
+Your job is to help the user understand and navigate this project's `.claude`
+workspace: the skills, agents, and commands Genex installed into the game
+folder (Genex never installs agent files globally).
 
 Guidelines:
 - Be concise and concrete. Point at real files with paths.

package/templates/commands/genex-status.md

@@ -4,8 +4,8 @@ description: Show the current Genex setup — workspace location, installed skil
 
 Report the user's Genex status:
 
-1. Confirm the workspace directory (`~/.claude`) exists and list the
-   `skills/`, `agents/`, and `commands/` it contains.
+1. Confirm the project's workspace directory (`.claude/` in the game folder)
+   exists and list the `skills/`, `agents/`, and `commands/` it contains.
 2. Check whether a `GENEX_TOKEN` is present in the project's `.env` (do not
    print the token value — only whether it is set).
 3. If anything looks missing, suggest running `npx genex init`.

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

@@ -11,11 +11,16 @@ architecture, and team-ready workflows.
 
 ## What got installed
 
-`genex init` installs the Genex skills into **every coding agent it detects** —
-Claude Code (`~/.claude`), Codex (`~/.codex`), and Cursor (`~/.cursor`) — so the
-same skills are available whichever agent you build with. After that, every
+`genex init` installs the Genex skills **into this project's folder** for
+every coding agent it detects — Claude Code (`.claude/`), Codex (`.codex/`),
+and Cursor (`.cursor/`) — so the same skills are available whichever agent you
+build with, and nothing is ever installed globally on the machine (only your
+auth token lives outside the project, in `~/.genex/env`). After that, every
 `genex` command keeps the genex-owned skills in sync with the installed CLI
 automatically (re-running `init` does too); your own files are never touched.
+If an older Genex version ever installed skills globally into `~/.claude`,
+`~/.codex` or `~/.cursor`, any `genex` command now sweeps those legacy copies
+out automatically — only `genex-*`-named files are removed, never yours.
 
 - **skills/** - reusable Genex skills for 3D browser-game work (all agents).
 - **agents/** - example subagent definitions (Claude Code).
@@ -23,8 +28,8 @@ automatically (re-running `init` does too); your own files 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, weather, VFX, post-processing, and visual
-validation.
+materials, atmosphere, water, weather, VFX, lighting, post-processing, and
+visual validation.
 
 ## Generating real assets
 

package/templates/skills/genex-threejs-lighting-design/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: genex-threejs-lighting-design
+description: Light Genex Three.js games from visible causes, and decide WHERE light belongs — walk the scene's sources one by one, the way the visual-direction gate walks surfaces and the moment gate walks moments. Use for light rigs, sun/moon key lights, practical lights (campfire, torch, neon, lava), emissive-to-light coupling, light shafts and visible beams, fog mood, gameplay light signals, flicker, light budgets, and scenes that read flat or uniformly lit.
+---
+
+# Genex Three.js Lighting Design
+
+Light from causes — every light in the frame is the visible consequence of
+something the player can point at. Avoid the uniform ambient wash that lights
+a cave like an office.
+
+## The source gate — run this BEFORE writing any lighting code
+
+The visual-direction gate walks **surfaces**; the moment gate walks
+**moments**. Light lives on neither — it lives on **sources**: what the sky
+pours in and what the fiction burns, glows, or screens. Walk the sources the
+same way, and decide each one.
+
+List the sources the scene contract already names — never invent them. Three
+places to look:
+
+- **the sky** — day, night, overcast, underground, deep space? That one answer
+  sets the rig: a warm sun key with cool sky fill, a dim hard moon, or no sky
+  at all — a cave is keyed by its practicals;
+- **the fiction's emitters** — campfire, torch, lava, neon sign, a monitor,
+  headlights, a portal, a crack of daylight in the roof;
+- **the gameplay signals** — the objective beacon, the telegraph, the
+  checkpoint. Light is information the player navigates by, and it is the
+  cheapest wayfinding you own.
+
+When gameplay needs light where the fiction names no source, add the cause
+first — a lamp prop, embers, a fissure — and then light it; the light alone is
+still a bug. Then judge each source:
+
+> **Does it change what the player sees AROUND it — on the ground, the walls,
+> the player — or does it only need to be seen itself?**
+
+Four verdicts, all legitimate, one forbidden:
+
+- **Seen itself** — an emissive material, no light object. Most sources land
+  here, and that is what keeps the frame cheap; how much it glows is
+  `$genex-threejs-bloom`'s question.
+- **Lights its surroundings** — a real `PointLight` or `SpotLight`, coupled to
+  its emitter (below). A campfire that doesn't paint the ground orange is a
+  prop, not a fire.
+- **Shapes the whole frame** — the key: a sun or moon `DirectionalLight`, the
+  arena floods. One or two per scene, and they own the shadows.
+- **The air itself is lit** — the beam is the point: the cave crack, a dusty
+  window shaft, canopy rays. Build the shaft as geometry first — fog and
+  volumetric passes are scene-wide decisions, never per-beam tools (recipes
+  in the reference).
+- **Not deciding — the only wrong answer.** One white `AmbientLight` over
+  everything is not a rig; it is the unlit look with extra steps, and it is
+  why shipped scenes read the same at noon and at midnight.
+
+"The neon is emissive-only — it doesn't reach the street" is a real answer;
+say it in one line and move on. Then check the inverse: **a light with no
+visible cause reads as a bug**, not mood — the player asks why the floor
+glows. And when the walk returns more real lights than the scene can afford,
+demote the dimmest back to emissive-only: dynamic lights are the scarcest
+resource in the frame, and the eye forgives an unlit distant torch far sooner
+than a dropped frame.
+
+## A practical is coupled, not placed
+
+The light a source throws and the mesh that emits it are one thing. Drive both
+from one envelope — separate flickers, or a light hovering near an unlit prop,
+read instantly as fake:
+
+```ts
+// Values assume a locked renderer baseline — relationships, not mandates.
+const fire = new THREE.PointLight(0xff9142, 14, 18, 2); // range-capped, physical falloff
+fire.position.set(0, 0.9, 0);                 // inside the flame, above the fuel
+campfire.add(fire);
+const flameMat = flame.material as THREE.MeshStandardMaterial;
+flameMat.emissive.set(0xff7a1e);
+
+function flicker(t: number): number {
+  // two incommensurate sines — coherent, frame-rate independent
+  return 0.82 + 0.12 * Math.sin(t * 11.3) + 0.06 * Math.sin(t * 23.7 + 1.7);
+}
+
+function updateFire(elapsed: number): void {
+  const e = flicker(elapsed);
+  fire.intensity = 14 * e;
+  flameMat.emissiveIntensity = 2.4 * e;       // mesh and light breathe together
+  fire.position.x = 0.05 * Math.sin(elapsed * 7.1); // the pool sways with the flame
+}
+```
+
+The same couple serves a neon sign that hums, a monitor whose picture spills
+onto the desk, a muzzle flash (one envelope drives light, emissive, and the
+sound cue). And when `npx genex skybox` has set `scene.environment`, that
+image IS the ambient fill — do not stack an `AmbientLight` on top of it.
+
+Read [references/light-recipes.md](references/light-recipes.md) for rig
+baselines per environment (day, night, interior, cave, space), the shaft and
+fog recipes, light-as-information patterns, budget relationships, and the
+kill-switch diagnostic.
+
+## Rules
+
+- Every light names its cause; a light nothing explains is a bug, not mood.
+- Couple a practical to its emitter: one color, one envelope, one on/off state.
+- The key owns shadows; practicals cast none until a shot proves they must.
+- Tune intensities only after the renderer baseline is locked — retuning the
+  whole rig after a tone-mapping change is self-inflicted.
+- Never repair unbalanced light ratios with exposure — fix the lights.
+- Flicker from elapsed time, never per-frame randomness.
+- Dispose lights and their shadow maps with the level that spawned them.
+- The rig must read with post off: time of day and where-to-go, before bloom.
+
+## Routing boundary
+
+Tone mapping, exposure, and grading are
+`$genex-threejs-exposure-color-grading`. How much an emissive glows is
+`$genex-threejs-bloom`; whether it also illuminates is this skill. Authoring
+the emissive surface itself — lava, hot rock, a screen's picture — is
+`$genex-threejs-procedural-materials`. `$genex-threejs-shadow-systems` owns
+large roaming-world shadows (cascades, clipmaps) — a bounded scene's one
+shadow-casting key with a tight frustum lives here. Sky scattering, haze, and the sun disc are
+`$genex-threejs-atmosphere-aerial-perspective`; shafts inside clouds are
+`$genex-threejs-volumetric-clouds`; ordering a volumetric pass among other
+post effects is `$genex-threejs-image-pipeline`; the environment map that
+feeds the fill is `$genex-ai-skybox`.

package/templates/skills/genex-threejs-lighting-design/references/light-recipes.md

@@ -0,0 +1,137 @@
+# Light Recipes
+
+Contents: rig baselines by environment, the practical couple, shafts and
+visible air, light as information, budgets and lifecycle, the kill-switch
+diagnostic.
+
+Numbers below are relationships, not mandates — validate them against the
+project's renderer baseline (`$genex-threejs-exposure-color-grading`), because
+tone mapping and exposure change what every intensity means.
+
+## Rig baselines by environment
+
+- **Outdoor day** — a warm sun `DirectionalLight` key plus cool sky fill
+  (`HemisphereLight`, or the skybox IBL when one is set). Fill sits well below
+  the key: when fill approaches key strength, shadow shapes die and the scene
+  flattens. The sun owns shadows: size the shadow camera's ortho bounds to the
+  playfield edges, fix acne at contact points with `bias`/`normalBias`, and
+  bump `mapSize` before loosening the frustum. A roaming world (racer, open
+  map) outgrows one frustum — that cascade question is
+  `$genex-threejs-shadow-systems`.
+- **Outdoor night** — the moon is a dim, cool, hard key, not a gray day.
+  Practicals carry visibility; the moon's job is silhouette and geography.
+  Push the fiction's emitters up the ladder before brightening the moon. No
+  moon (a city street)? The settlement's own skyglow is the fill — a dim,
+  warm-tinted hemisphere — and the emitters carry the rest.
+- **Interior** — the openings and fixtures ARE the rig: a window is a
+  `SpotLight` aimed the way the sun outside would aim (or a shaft, below);
+  fixtures are coupled practicals. IBL still fills, well below the windows.
+  When the hard sun-rectangle on the floor IS the shot (a big window, a long
+  room), swap the spot for a shadow-casting `DirectionalLight` through the
+  opening — parallel light keeps the patch's edges straight where a spot's
+  cone diverges.
+- **Cave / underground** — no sky, no free fill. The brightest practical or
+  the crack shaft is the key; darkness is part of the palette, and the
+  player's own torch is a gameplay object. Ration the black, don't erase it.
+- **Space** — one hard star key, black fill, bounce only from IBL or
+  planetshine. The harsh terminator IS the look; softening it reads as a
+  studio shoot.
+
+## The practical couple
+
+- Contain the light: set `distance` so the falloff dies inside the space the
+  source serves, and keep `decay` at the physical `2`. An uncontained point
+  light climbs walls three rooms away, and the scene creeps toward flat.
+- Position the light inside the emitter, slightly above the visible flame or
+  tube — the pool it throws must sit centered under the thing that explains it.
+- An area emitter — neon tube, screen, softbox — is by default a tinted
+  `PointLight` or `SpotLight` sunk into it. Reach for `RectAreaLight` only
+  when the rectangular wash on a nearby wall IS the shot, and know its terms:
+  `RectAreaLightUniformsLib.init()` first, no shadows, standard/physical
+  materials only.
+- When the player roams, the budget follows them — but never add or remove a
+  light mid-play: changing the light count recompiles every shader that sees
+  it, a visible hitch. Allocate a small fixed pool up front, reassign members'
+  position and color to the nearest sources, and retire one by driving its
+  intensity to 0.
+
+## Shafts and visible air
+
+The default shaft is geometry, not a render pass — an open cone or tapered
+cylinder from the aperture, additive, fading along its length:
+
+```ts
+function beamGradient(): THREE.Texture {
+  const c = document.createElement("canvas");
+  c.width = 1; c.height = 64;
+  const ctx = c.getContext("2d")!;
+  const g = ctx.createLinearGradient(0, 0, 0, 64);
+  g.addColorStop(0, "rgba(255,255,255,0.9)");
+  g.addColorStop(1, "rgba(255,255,255,0)");
+  ctx.fillStyle = g;
+  ctx.fillRect(0, 0, 1, 64);
+  const t = new THREE.Texture(c);
+  t.needsUpdate = true;
+  return t;
+}
+
+const shaft = new THREE.Mesh(
+  new THREE.CylinderGeometry(0.25, 1.6, 7, 24, 1, true), // narrow at the crack, wide at the floor
+  new THREE.MeshBasicMaterial({
+    map: beamGradient(),          // flip the gradient if the bright end lands on the floor
+    transparent: true,
+    opacity: 0.35,
+    blending: THREE.AdditiveBlending,
+    depthWrite: false,
+    side: THREE.DoubleSide,
+  }),
+);
+```
+
+- Pair the shaft with a real `SpotLight` from the same aperture: the bright
+  pool at its foot is what sells the beam. A shaft with nothing at its foot
+  reads as a hologram.
+- If the scene earns its one ambient-particle layer (the moment gate's
+  budget), inside the beam is where it pays — slow dust motes, the
+  `$genex-threejs-procedural-vfx` dot-texture recipe.
+- `scene.fog` (or `FogExp2`) is a scene-wide mood decision: every light pool
+  becomes a cone and contrast falls everywhere — choose it for the whole look.
+- A full-screen shaft hanging off the sun disc rides the atmosphere pass
+  (`$genex-threejs-atmosphere-aerial-perspective`); this skill's shafts are
+  per-aperture beams built as geometry. A real raymarched volumetric pass is
+  for scenes whose identity is shafts.
+
+## Light as information
+
+- Reserve a signal hue: pickups and objectives get a color no environment
+  light uses, and it never changes meaning mid-game.
+- Aim the player with brightness before UI: the lit doorway beats the arrow.
+  The eye lands on the highest contrast in frame — put it where the player
+  should go.
+- Telegraph danger with the light's shape — a red cone where the boss will
+  sweep, a pulsing ring under the falling crate — timed to the same event
+  feedback the moment gate placed.
+- A vertical beacon (shaft recipe above) reads across the whole map and over
+  occluding walls — the map's own "you are here".
+
+## Budgets and lifecycle
+
+- The whole rig of most shipped scenes: one shadow-casting key, IBL or
+  hemisphere fill, and a handful of coupled practicals. Each real light
+  beyond that carries a stated reason.
+- A shadow-casting point light renders the scene six more times; a
+  shadow-casting spot, once. Prefer the spot — and prefer no shadow at all on
+  a flickering source, because the moving pool already sells it.
+- `scene.remove(light)` does not free it: call `light.dispose()` when the
+  level unloads, and the shadow map goes with it.
+
+## The kill-switch diagnostic
+
+Wire a debug toggle per light, the same way the other systems expose debug
+views. Turn each light off alone and name what died — "the campfire pool",
+"the corridor signal" — watching the frame time as well as the frame: a light
+whose absence changes nothing is dead weight to delete, and a light that costs
+more milliseconds than the mood it adds is over budget. That observation is
+the budget — there is no magic count. Then take two screenshots with post
+off — the darkest playable corner and the brightest — and check both: if the
+subject and the way forward read in each, the rig holds.

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

@@ -1,6 +1,6 @@
 ---
 name: genex-threejs-skill-router
-description: Route Genex 3D browser-game work to the smallest useful Three.js skill set. Use for new game scenes, graphics upgrades, visual reference matching, game-feel passes, render-pipeline work, publishing readiness, multiplayer-aware scene architecture, or requests spanning cameras, geometry, materials, atmosphere, water, VFX, shadows, post-processing, and validation.
+description: Route Genex 3D browser-game work to the smallest useful Three.js skill set. Use for new game scenes, graphics upgrades, visual reference matching, game-feel passes, render-pipeline work, publishing readiness, multiplayer-aware scene architecture, or requests spanning cameras, geometry, materials, atmosphere, water, VFX, lighting, shadows, post-processing, and validation.
 ---
 
 # Genex Three.js Skill Router
@@ -36,6 +36,7 @@ map, execution order, and acceptance gate.
 | 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` |
+| the light rig and where light belongs: sun/moon key, practical lights (campfire, torch, neon, lava), emissive-to-light coupling, light shafts and visible beams, fog mood, light signals, flicker, a scene that reads flat or uniformly lit | `$genex-threejs-lighting-design` |
 | stable large-world shadows, cascades, clipmaps, cached updates | `$genex-threejs-shadow-systems` |
 | GTAO, bent normals, bilateral reconstruction | `$genex-threejs-screen-space-ambient-occlusion` |
 | HDR bloom and selective emission contribution | `$genex-threejs-bloom` |
@@ -94,7 +95,8 @@ it in the running game), one named
 **ambient-motion loop** that keeps
 the scene alive at rest (emissive pulse, shimmer, drifting dust — shader
 work, zero generations), and the lighting/atmosphere mood from that
-same brief. Planning is not building — effects still land last in the
+same brief — walked source by source, every light with a visible cause
+(`$genex-threejs-lighting-design` owns that gate). Planning is not building — effects still land last in the
 execution order.
 
 **Multiplayer is mandatory routing:** if the game has 2+ players sharing a world, loading

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

@@ -105,8 +105,18 @@ Three.js release or branch, and do not blindly copy demo architecture.
      texture goes on this box" but "what shape is this energy": a primitive
      standing in for an effect is a placeholder no matter how deliberate the
      comment says it is. `$genex-threejs-procedural-vfx` owns this gate;
-   - **lighting/atmosphere mood** from the SAME shared style brief the UI gate
-     wrote — one art direction across scene and UI.
+   - **every light has a cause — walk the sources one by one**: the
+     lighting/atmosphere mood comes from the SAME shared style brief the UI
+     gate wrote — one art direction across scene and UI — but a mood is not a
+     rig. Walk the sources the contract already names: the sky (day, night,
+     underground — that one answer sets the key), the fiction's emitters
+     (campfire, torch, neon, a monitor, a crack of daylight in the roof), and
+     the gameplay signals (beacon, telegraph, checkpoint). For each: does it
+     change what the player sees around it, or only need to be seen itself?
+     Emissive-only is a real answer said in one line; a coupled practical
+     light is the step up; one white ambient wash over everything is the
+     unlit look with extra steps, and it reads the same at noon and at
+     midnight. `$genex-threejs-lighting-design` owns this gate;
    Planning is not building: effects still land LAST (steps 10–11); this step
    only fixes the target so the look isn't improvised pass-by-pass at the end.
 5. Wire the gameplay layer for the player verb: the physics world via
@@ -137,7 +147,9 @@ Three.js release or branch, and do not blindly copy demo architecture.
 8. Add procedural animation when object motion needs authored phases,
    convergence, looping, or deterministic timelines.
 9. Add shared fields before writing multiple independent noise layers.
-10. Add lighting, atmosphere, and shadows only after the no-post baseline reads.
+10. Add lighting, atmosphere, and shadows only after the no-post baseline
+    reads: the step-4 source walk builds now — `$genex-threejs-lighting-design`
+    owns the rig.
 11. Add image-pipeline, bloom, exposure, grading, or AO last — building out the
     step-4 post plan, not inventing one now. This is a completion gate: the
     named post stack must be BUILT before the game is called done, published,