@genex-ai/cli-demo 0.1.0

package/src/lib/env.ts

@@ -0,0 +1,109 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+export type EnvWriteMode = "created" | "updated" | "appended";
+
+export interface EnvWriteResult {
+  mode: EnvWriteMode;
+  path: string;
+}
+
+/**
+ * Set `KEY=value` in a `.env` file without disturbing the rest of it.
+ *
+ * - If the file does not exist, it is created (`created`).
+ * - If the key already exists, its line is replaced in place (`updated`).
+ * - Otherwise the assignment is appended to the end (`appended`).
+ *
+ * The file is written/owned at mode 0600 since it holds a secret. Values that
+ * contain whitespace or shell-significant characters are double-quoted.
+ */
+export async function writeEnvVar(
+  envPath: string,
+  key: string,
+  value: string,
+): Promise<EnvWriteResult> {
+  let content = "";
+  let existed = false;
+  try {
+    content = await fs.readFile(envPath, "utf8");
+    existed = true;
+  } catch {
+    // Missing file — we'll create it below.
+  }
+
+  const assignment = `${key}=${formatValue(value)}`;
+  // Match `KEY=...` (optionally preceded by `export `) on any line. The `g`
+  // flag ensures *every* occurrence is rewritten, so a file that already has
+  // duplicate entries for the key never keeps a stale value.
+  const keyPattern = new RegExp(
+    `^(\\s*export\\s+)?${escapeRegExp(key)}=.*$`,
+    "gm",
+  );
+
+  let next: string;
+  let mode: EnvWriteMode;
+
+  if (keyPattern.test(content)) {
+    next = content.replace(keyPattern, assignment);
+    mode = "updated";
+  } else {
+    let prefix = content;
+    if (prefix.length > 0 && !prefix.endsWith("\n")) prefix += "\n";
+    next = prefix + assignment + "\n";
+    mode = existed ? "appended" : "created";
+  }
+
+  // Create the parent dir if missing (e.g. ~/.genex on first run).
+  await fs.mkdir(path.dirname(envPath), { recursive: true });
+  await fs.writeFile(envPath, next, { mode: 0o600 });
+  await restrictFilePermissions(envPath);
+
+  return { mode, path: envPath };
+}
+
+/**
+ * Restrict a secret file to the current user only.
+ *
+ * On POSIX this is a `chmod 0600`. On Windows, POSIX modes are ignored, so we
+ * make a best-effort attempt to strip inherited ACLs and grant only the current
+ * user via `icacls`. Every step is non-fatal — if it fails the token is still
+ * written (see the Windows caveat in the README).
+ */
+async function restrictFilePermissions(filePath: string): Promise<void> {
+  if (process.platform !== "win32") {
+    // writeFile's mode only applies on creation; enforce it for existing files too.
+    await fs.chmod(filePath, 0o600).catch(() => {});
+    return;
+  }
+
+  const user = process.env.USERNAME ?? process.env.USER;
+  if (!user) return;
+
+  await new Promise<void>((resolve) => {
+    try {
+      const child = spawn(
+        "icacls",
+        [filePath, "/inheritance:r", "/grant:r", `${user}:F`],
+        { stdio: "ignore" },
+      );
+      child.on("error", () => resolve());
+      child.on("close", () => resolve());
+    } catch {
+      resolve();
+    }
+  });
+}
+
+function formatValue(value: string): string {
+  if (/[\s#"'$`\\]/.test(value)) {
+    // Quote and escape backslashes/double-quotes for dotenv-style parsers.
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+  }
+  return value;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/lib/project.ts

@@ -0,0 +1,109 @@
+import crypto from "node:crypto";
+import type { Logger } from "../utils/logger.ts";
+import { c } from "../utils/colors.ts";
+import type { ProjectMetadata } from "./store.ts";
+
+export interface CreateProjectOptions {
+  /** API base URL (e.g. https://demo-api.glotech.world or http://localhost:3000). */
+  apiUrl: string;
+  /** Bearer token (from ~/.genex/env). */
+  token: string;
+  /** Desired project name (the API slugifies it). */
+  name: string;
+  /** OpenSSH PUBLIC key registered as the repo's write deploy key (required). */
+  deployKey: string;
+  /** Colyseus relay URL, stored in metadata for the game's connect(). */
+  colyseusUrl: string;
+  /** Auth/web origin, used to print the dashboard link. */
+  dashboardUrl: string;
+  log: Logger;
+}
+
+interface ProjectResponse {
+  project?: {
+    id: string;
+    slug: string;
+    title: string;
+    playUrl?: string | null;
+  };
+  sshUrl?: string;
+  error?: string;
+}
+
+/**
+ * Create a draft project via `POST /api/projects { name, deployKey }`. Returns
+ * the project metadata (incl. the `sshUrl` the agent pushes to) for the caller
+ * to persist, or null on failure. Best-effort: a network/HTTP failure is logged
+ * and returns null — it never aborts `genex init` (the token is already saved).
+ */
+export async function createDraftProject(
+  opts: CreateProjectOptions,
+): Promise<ProjectMetadata | null> {
+  const { apiUrl, token, deployKey, colyseusUrl, dashboardUrl, log } = opts;
+
+  log.step("Creating your project…");
+
+  // Try the requested name, then one retry with a unique suffix on a slug clash.
+  const names = [opts.name, `${opts.name}-${randomSuffix()}`];
+
+  for (let i = 0; i < names.length; i++) {
+    const name = names[i] as string;
+    let res: Response;
+    try {
+      res = await fetch(`${apiUrl}/api/projects`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({ name, deployKey }),
+      });
+    } catch (err) {
+      log.warn(`Couldn't reach the API at ${apiUrl} to create the project.`);
+      log.dim(`  ${String(err)}`);
+      return null;
+    }
+
+    if (res.status === 409 && i === 0) continue; // slug taken — retry suffixed
+    if (res.status === 401) {
+      log.warn("Not authorized to create the project (token rejected).");
+      return null;
+    }
+    if (res.status === 400) {
+      log.warn("The API rejected the deploy key (must be an OpenSSH public key).");
+      return null;
+    }
+    if (!res.ok) {
+      log.warn(`Couldn't create the project (HTTP ${res.status}).`);
+      return null;
+    }
+
+    const data = (await res.json().catch(() => null)) as ProjectResponse | null;
+    const project = data?.project;
+    if (!project || !data?.sshUrl) {
+      log.warn("Project created, but the API response was unexpected.");
+      return null;
+    }
+
+    log.success(`Created project ${c.cyan(project.slug)}.`);
+    if (project.playUrl) log.dim(`  play (after publish): ${project.playUrl}`);
+    log.dim(`  dashboard: ${dashboardUrl}/dashboard`);
+
+    return {
+      id: project.id,
+      slug: project.slug,
+      sshUrl: data.sshUrl,
+      apiUrl,
+      colyseusUrl,
+      playUrl: project.playUrl ?? undefined,
+      status: "draft",
+    };
+  }
+
+  log.warn("Couldn't create a project with a unique name. Try `--name <unique>`.");
+  return null;
+}
+
+function randomSuffix(): string {
+  return crypto.randomBytes(3).toString("hex");
+}

package/src/lib/ssh.ts

@@ -0,0 +1,104 @@
+// Per-project SSH deploy key for `genex init` / `genex publish`.
+//
+// We generate an ed25519 keypair in the project dir; the PUBLIC key is sent to
+// the API as the repo's write deploy key, the PRIVATE key (`genex_key`) stays
+// local and is used by `genex publish` to push over SSH. The private key is
+// gitignored so it never lands in the public game repo.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import type { Logger } from "../utils/logger.ts";
+
+/** The private key filename in the project dir (public key is `<name>.pub`). */
+export const KEY_NAME = "genex_key";
+
+/**
+ * Ensure a per-project ed25519 deploy keypair exists in `dir` and return its
+ * public key. Idempotent: a re-run of `genex init` reuses the existing key (it's
+ * already registered as the repo's deploy key). Returns null if `ssh-keygen`
+ * isn't available — the caller warns and skips project creation.
+ */
+export async function generateSshKeypair(
+  dir: string,
+  log: Logger,
+): Promise<{ publicKey: string } | null> {
+  const keyPath = path.join(dir, KEY_NAME);
+  const pubPath = `${keyPath}.pub`;
+
+  // Reuse an existing key (idempotent re-init).
+  try {
+    const existing = (await fs.readFile(pubPath, "utf8")).trim();
+    if (existing) {
+      log.dim(`Reusing existing deploy key (${KEY_NAME}).`);
+      return { publicKey: existing };
+    }
+  } catch {
+    /* no existing key — generate below */
+  }
+
+  log.step("Generating a deploy key…");
+  const ok = await runSshKeygen(keyPath, log);
+  if (!ok) return null;
+
+  try {
+    const pub = (await fs.readFile(pubPath, "utf8")).trim();
+    if (!pub) {
+      log.warn("ssh-keygen produced no public key.");
+      return null;
+    }
+    await fs.chmod(keyPath, 0o600).catch(() => {});
+    return { publicKey: pub };
+  } catch (err) {
+    log.warn(`Couldn't read the generated public key: ${String(err)}`);
+    return null;
+  }
+}
+
+function runSshKeygen(keyPath: string, log: Logger): Promise<boolean> {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(
+        "ssh-keygen",
+        ["-t", "ed25519", "-f", keyPath, "-N", "", "-C", "genex-agent"],
+        { stdio: "ignore" },
+      );
+    } catch {
+      log.warn("ssh-keygen not found — install OpenSSH (ssh-keygen) and re-run.");
+      resolve(false);
+      return;
+    }
+    child.on("error", () => {
+      log.warn("ssh-keygen not found — install OpenSSH (ssh-keygen) and re-run.");
+      resolve(false);
+    });
+    child.on("close", (code) => resolve(code === 0));
+  });
+}
+
+/**
+ * Append the genex artifacts to `<dir>/.gitignore` so `genex publish`'s
+ * `git add -A` never pushes the PRIVATE key (or local metadata) to the public
+ * game repo. Idempotent; creates the file if absent; never rewrites existing rules.
+ */
+export async function writeGitignore(dir: string, log: Logger): Promise<void> {
+  const file = path.join(dir, ".gitignore");
+  let content = "";
+  try {
+    content = await fs.readFile(file, "utf8");
+  } catch {
+    /* create below */
+  }
+
+  const present = new Set(content.split("\n").map((l) => l.trim()));
+  const toAdd = [KEY_NAME, `${KEY_NAME}.pub`, ".genex/"].filter((e) => !present.has(e));
+  if (toAdd.length === 0) return;
+
+  let next = content;
+  if (next.length > 0 && !next.endsWith("\n")) next += "\n";
+  if (!content.trim()) next += "# genex (deploy key + local metadata — never publish)\n";
+  next += toAdd.join("\n") + "\n";
+
+  await fs.writeFile(file, next);
+  log.dim(`Updated .gitignore (${toAdd.join(", ")}).`);
+}

package/src/lib/store.ts

@@ -0,0 +1,102 @@
+// Single source of truth for CLI credential + project storage.
+//
+//  - The USER token lives at ~/.genex/env (per-user, reused across projects),
+//    written via the existing writeEnvVar (0600 + Windows ACL). A legacy
+//    ./.env GENEX_TOKEN is still read as a fallback for older projects.
+//  - PER-PROJECT metadata (id, slug, sshUrl, urls) lives at <cwd>/.genex/project.json
+//    so `genex publish` can run from the project dir without re-authing. The
+//    private SSH key (genex_key) is NEVER stored here — it stays a plain file in
+//    the project dir and is gitignored.
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ENV_TOKEN_KEY, getGenexEnvPath } from "../config.ts";
+import { writeEnvVar } from "./env.ts";
+
+export interface ProjectMetadata {
+  /** API project id (used by `POST /api/projects/:id/publish`). */
+  id: string;
+  /** URL-safe slug (used as the multiplayer room + play URL path). */
+  slug: string;
+  /** git@github.com:org/slug.git — what the agent pushes to (deploy key). */
+  sshUrl: string;
+  /** API base this project was created against. */
+  apiUrl: string;
+  /** Colyseus relay URL for the game's connect(). */
+  colyseusUrl: string;
+  /** Public play URL (GitHub Pages). */
+  playUrl?: string;
+  /** "draft" | "published". */
+  status?: string;
+}
+
+/** Path to the per-project metadata file (`<cwd>/.genex/project.json`). */
+export function getProjectMetadataPath(cwd: string = process.cwd()): string {
+  return path.join(cwd, ".genex", "project.json");
+}
+
+/** Persist the user token to `~/.genex/env` (or an explicit env path). */
+export async function writeUserToken(
+  token: string,
+  envPath?: string,
+): Promise<{ path: string }> {
+  const { path: written } = await writeEnvVar(getGenexEnvPath(envPath), ENV_TOKEN_KEY, token);
+  return { path: written };
+}
+
+/**
+ * Read the user token from `~/.genex/env`, falling back to a legacy `./.env`
+ * (read-only; never deleted). Returns null if no token is found.
+ */
+export async function readUserToken(envPath?: string): Promise<string | null> {
+  const fromGenex = await readTokenFromFile(getGenexEnvPath(envPath));
+  if (fromGenex) return fromGenex;
+  if (!envPath) {
+    // Backcompat: older `genex init` wrote GENEX_TOKEN into the project's ./.env.
+    return readTokenFromFile(path.join(process.cwd(), ".env"));
+  }
+  return null;
+}
+
+async function readTokenFromFile(file: string): Promise<string | null> {
+  let content: string;
+  try {
+    content = await fs.readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+  const m = content.match(/^\s*(?:export\s+)?GENEX_TOKEN=(.*)$/m);
+  if (!m) return null;
+  return stripQuotes(m[1]!.trim()) || null;
+}
+
+function stripQuotes(v: string): string {
+  if (
+    (v.startsWith('"') && v.endsWith('"')) ||
+    (v.startsWith("'") && v.endsWith("'"))
+  ) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/** Read `<cwd>/.genex/project.json`, or null if absent/unparseable. */
+export async function readProject(cwd: string = process.cwd()): Promise<ProjectMetadata | null> {
+  try {
+    const raw = await fs.readFile(getProjectMetadataPath(cwd), "utf8");
+    return JSON.parse(raw) as ProjectMetadata;
+  } catch {
+    return null;
+  }
+}
+
+/** Write `<cwd>/.genex/project.json` (0600 — it identifies the repo, not a secret). */
+export async function writeProject(
+  meta: ProjectMetadata,
+  cwd: string = process.cwd(),
+): Promise<{ path: string }> {
+  const file = getProjectMetadataPath(cwd);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, JSON.stringify(meta, null, 2) + "\n", { mode: 0o600 });
+  await fs.chmod(file, 0o600).catch(() => {});
+  return { path: file };
+}

package/src/utils/colors.ts

@@ -0,0 +1,25 @@
+// Tiny zero-dependency ANSI color helpers. Colors are disabled when stdout is
+// not a TTY, when NO_COLOR is set, or for dumb terminals — so piped/CI output
+// stays clean.
+const useColor =
+  Boolean(process.stdout.isTTY) &&
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb";
+
+const ESC = String.fromCharCode(27); // ASCII escape (\x1b)
+
+const code =
+  (open: number, close: number) =>
+  (s: string): string =>
+    useColor ? `${ESC}[${open}m${s}${ESC}[${close}m` : s;
+
+export const c = {
+  bold: code(1, 22),
+  dim: code(2, 22),
+  red: code(31, 39),
+  green: code(32, 39),
+  yellow: code(33, 39),
+  blue: code(34, 39),
+  cyan: code(36, 39),
+  gray: code(90, 39),
+};

package/src/utils/logger.ts

@@ -0,0 +1,40 @@
+import { c } from "./colors.ts";
+
+export interface Logger {
+  info(msg: string): void;
+  success(msg: string): void;
+  warn(msg: string): void;
+  error(msg: string): void;
+  step(msg: string): void;
+  dim(msg: string): void;
+  plain(msg: string): void;
+}
+
+export function createLogger(opts: { quiet?: boolean } = {}): Logger {
+  const out = (s: string): void => {
+    if (!opts.quiet) process.stdout.write(s + "\n");
+  };
+  const err = (s: string): void => {
+    process.stderr.write(s + "\n");
+  };
+  return {
+    info: (m) => out(`${c.cyan("i")} ${m}`),
+    success: (m) => out(`${c.green("✓")} ${m}`),
+    warn: (m) => out(`${c.yellow("!")} ${m}`),
+    error: (m) => err(`${c.red("✗")} ${m}`),
+    step: (m) => out(`${c.blue("›")} ${m}`),
+    dim: (m) => out(c.dim(m)),
+    plain: (m) => out(m),
+  };
+}
+
+// A no-op logger, handy for tests.
+export const silentLogger: Logger = {
+  info: () => {},
+  success: () => {},
+  warn: () => {},
+  error: () => {},
+  step: () => {},
+  dim: () => {},
+  plain: () => {},
+};

package/templates/README.md

@@ -0,0 +1,19 @@
+# Genex workspace
+
+These files were installed into your `~/.claude` directory by `genex init`.
+They give your coding agent a starter workspace 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. The
+installed files are yours to edit, extend, and keep with each project.
+
+Existing files are never overwritten. Re-running `genex init` only adds files
+you do not already have.
+
+- `skills/` - reusable Genex skills for 3D game creation.
+- `agents/` - example subagent definitions.
+- `commands/` - example slash commands.
+
+Start with `skills/genex-threejs-skill-router/SKILL.md` when asking your agent
+to build or improve a 3D browser game.

package/templates/agents/genex-helper.md

@@ -0,0 +1,16 @@
+---
+name: genex-helper
+description: Example Genex subagent. Answers questions about the local Genex workspace and CLI. Replace or extend this with your own agents.
+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.
+
+Guidelines:
+- Be concise and concrete. Point at real files with paths.
+- When unsure what's installed, search the workspace before answering.
+- This is a starter template — encourage the user to edit or replace it with
+  agents tailored to their own work.

package/templates/commands/genex-status.md

@@ -0,0 +1,13 @@
+---
+description: Show the current Genex setup — workspace location, installed skills/agents, and whether a token is configured.
+---
+
+Report the user's Genex status:
+
+1. Confirm the workspace directory (`~/.claude`) 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`.
+
+Keep the summary short and scannable.

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

@@ -0,0 +1,41 @@
+---
+name: genex-getting-started
+description: Orient a new Genex user to the installed 3D browser-game workspace, including skills, agents, commands, authorization, and re-running setup. Use when the user asks what Genex is, how to get started, or what `genex init` installed.
+---
+
+# Getting started with Genex
+
+`genex init` set up a workspace that helps your coding agent build 3D games in
+the browser. Genex focuses on Three.js game skills, publishing, multiplayer
+architecture, and team-ready workflows.
+
+## What got installed
+
+Everything under `~/.claude`:
+
+- **skills/** - reusable Genex skills for 3D browser-game work.
+- **agents/** - example subagent definitions.
+- **commands/** - example slash commands.
+
+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, VFX, post-processing, and visual validation.
+
+Your existing files were left untouched. `genex init` only adds what is missing.
+
+## Re-running setup
+
+Safe to run any time; it never overwrites your files:
+
+```bash
+npx genex init
+```
+
+Use `--force` only if you intentionally want to overwrite installed templates
+with the latest versions.
+
+## Authorization
+
+`genex init` opens the auth site, then writes a `GENEX_TOKEN` into your
+project's `.env`. If the browser doesn't open, copy the printed URL into a
+browser manually to finish authorizing.

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: genex-threejs-atmosphere-aerial-perspective
+description: Implement sky and aerial perspective for Genex Three.js games. Use for planetary atmospheres, ground-to-space transitions, Rayleigh/Mie-style scattering, sun and moon discs, depth-based haze, distance color, atmospheric lighting, and scale-readable outdoor scenes.
+---
+
+# Genex Three.js Atmosphere And Aerial Perspective
+
+Atmosphere should explain scale and lighting without hiding gameplay. Add it
+after the base scene reads.
+
+Read [references/atmosphere.md](references/atmosphere.md) for sky, haze,
+lighting handoff, and transition checks.
+
+## Build order
+
+1. Define world scale, camera altitude range, sun direction, horizon behavior,
+   and target devices.
+2. Build the sky model or sky gradient first.
+3. Add depth-based aerial perspective for terrain, buildings, and distant props.
+4. Connect sun color, ambient color, fog, and material response coherently.
+5. Add planetary shell or LUT paths only when the scale needs them.
+6. Expose debug views for transmittance, inscattering, depth, and no-atmosphere.
+
+## Rules
+
+- Keep gameplay silhouettes readable through haze.
+- Use one owner for sky color and sun direction.
+- Avoid stacking multiple fog systems with different assumptions.
+- Keep atmosphere quality adjustable for lower-end browsers.
+- Validate ground, mid-altitude, and high-altitude views.

package/templates/skills/genex-threejs-atmosphere-aerial-perspective/references/atmosphere.md

@@ -0,0 +1,29 @@
+# Atmosphere And Aerial Perspective
+
+Use this reference for outdoor scale and sky rendering.
+
+## Sky
+
+- Keep sun direction explicit and shared with lighting.
+- Match sky color, ambient color, and direct light temperature.
+- Include sun or moon discs only when they help composition.
+- Keep stars or space backgrounds separated from atmospheric haze.
+
+## Aerial perspective
+
+- Apply haze by depth or world distance.
+- Preserve contrast for interactable objects and traversal edges.
+- Let distant terrain shift color before it loses all form.
+- Provide a debug toggle to remove atmosphere.
+
+## Planetary scale
+
+- Use altitude-aware behavior for ground-to-space transitions.
+- Keep horizon curvature and shell radius consistent with planet radius.
+- Validate camera positions near ground, high altitude, and orbit.
+
+## Performance
+
+- Prefer simple depth haze for small scenes.
+- Use precomputed or lower-resolution paths for expensive scattering.
+- Expose quality tiers and render-target costs.

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

@@ -0,0 +1,30 @@
+---
+name: genex-threejs-bloom
+description: Implement controlled HDR bloom for Genex Three.js games. Use for selective emission, glow hierarchy, bloom thresholds, multi-scale blur, material restoration, effect isolation, exposure coupling, and diagnostics where glow supports form without replacing it.
+---
+
+# Genex Three.js Bloom
+
+Bloom should reveal strong light and energy. It should not be the only reason an
+object reads.
+
+Read [references/bloom.md](references/bloom.md) for HDR signal setup,
+selective contribution, blur hierarchy, and diagnostics.
+
+## Build order
+
+1. Confirm the scene uses a consistent HDR signal and tone-mapping path.
+2. Define what is allowed to bloom and why.
+3. Extract bright or selected contribution.
+4. Blur at multiple scales.
+5. Composite with exposure-aware strength.
+6. Expose debug views for source, threshold mask, blur levels, final bloom, and
+   no-bloom baseline.
+
+## Rules
+
+- Keep emissive intensities scene-relative.
+- Avoid global bloom that washes out gameplay silhouettes.
+- Restore materials if using selective render passes.
+- Tune bloom with exposure and grading visible.
+- Validate readability with bloom disabled.