@genex-ai/cli-demo 0.1.1 → 0.2.0

package/README.md

@@ -4,8 +4,12 @@ Set up your `~/.claude` workspace, authorize, create a game project, and publish
 This is the `cli` app of the [genex monorepo](../../README.md).
 
 ```bash
-genex init <name>     # authorize + create the draft project
-genex publish         # push the built game + list it in the gallery
+genex init <name>          # authorize + create the draft project
+genex publish              # push the built game + list it in the gallery
+genex model "<prompt>"     # generate a 3D model  → assets/models/
+genex skybox "<prompt>"    # generate a 360° sky  → assets/skybox/
+genex sfx "<prompt>"       # generate a sound fx  → assets/sfx/
+genex texture "<prompt>"   # generate a texture   → assets/textures/
 ```
 
 `genex init` does four things:
@@ -31,6 +35,31 @@ push. Defaults: API `https://demo-api.glotech.world`, auth site
 `https://demo-web.glotech.world` — override with `--api-url` / `--auth-url` (or
 `GENEX_API_URL` / `GENEX_AUTH_URL`) for local dev.
 
+## Generating assets
+
+`genex model | skybox | sfx | texture "<prompt>"` turn a prompt into a real,
+game-ready asset and download it into the project's `./assets/<kind>/` folder. The
+command blocks until the asset is ready (poll loop), then writes the file(s):
+
+| Command | Provider | Writes |
+| --- | --- | --- |
+| `genex model "<prompt>"` | Tripo | `assets/models/<slug>.glb` |
+| `genex skybox "<prompt>"` | Blockade Labs | `assets/skybox/<slug>.jpg` |
+| `genex sfx "<prompt>" [--duration <s>]` | ElevenLabs | `assets/sfx/<slug>.mp3` |
+| `genex texture "<prompt>" [--terrain]` | Gemini | `assets/textures/<slug>/basecolor.<ext>` |
+
+Because the file lands in the project and `genex publish` commits the whole working
+directory, generated assets **ship inside the published GitHub Pages build** — load
+them by **relative** path (`./assets/...`) and players get them from the same origin
+(no CORS, no runtime dependency on this API). Each kind has a scaffolded
+`genex-ai-<kind>` skill with the exact Three.js loader code.
+
+Auth reuses the existing `GENEX_TOKEN` (run `genex init` first). Server-side, each
+provider is keyed by an env var (`TRIPO_API_KEY`, `BLOCKADE_LABS_API_KEY`,
+`ELEVENLABS_API_KEY`, `GEMINI_API_KEY`); when a key is unset that kind falls back to
+a built-in **mock** provider that returns sample assets, so the flow runs keyless.
+`--no-wait` enqueues without downloading.
+
 ## Install / run
 
 From the monorepo root (the CLI runs directly via Node — no build step):
@@ -165,6 +194,28 @@ pnpm test        # node --test test/*.test.ts
 pnpm start init --no-auth --dir ./tmp-claude
 ```
 
+### Testing a command like an end user
+
+`pnpm start <cmd>` runs a single command from source — fine for quick checks. To
+exercise the CLI as a *global* command (the way users invoke `genex`), symlink a
+`genexd` shim onto your PATH pointing at the source entrypoint. No build step —
+it runs the TypeScript directly and picks up edits instantly:
+
+```bash
+# one-time, from this package directory: put `genexd` on PATH
+ln -sf "$PWD/src/index.ts" "$(dirname "$(which node)")/genexd"
+
+genexd --help                                  # works from any directory
+genexd init --no-auth --dir ./tmp-claude
+
+rm "$(dirname "$(which node)")/genexd"         # remove it when done
+```
+
+Use `genexd` (not `genex`) so the local shim never shadows a globally installed
+published build — this is the same shim the local scaffold flow uses (see
+`scaffold_prompt.local.md`). `npm link` is unnecessary here: it would require a
+`dist/` build, whereas `genexd` / `pnpm start` run the source as-is.
+
 Relative imports use explicit `.ts` extensions and only erasable TypeScript
 syntax is allowed — both are monorepo-wide rules (see the root README).
 

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import path8 from "path";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -739,10 +739,11 @@ async function runPublish(opts) {
     return;
   }
   const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
+  let pushed = null;
   if (opts.noPush) {
     log.info("Skipping git push (--no-push).");
   } else {
-    await pushGame(meta.sshUrl, log);
+    pushed = await pushGame(meta.sshUrl, log);
   }
   log.step("Publishing to the gallery\u2026");
   let res;
@@ -766,10 +767,17 @@ async function runPublish(opts) {
     return;
   }
   log.plain("");
-  log.success("Published. \u{1F389}");
+  if (pushed === false) {
+    log.warn(
+      "Listed in the gallery, but the game wasn't pushed \u2014 the play URL won't work until the push succeeds."
+    );
+    log.dim("  Fix the push error above and re-run `genex publish`.");
+  } else {
+    log.success("Published. \u{1F389}");
+  }
   if (meta.playUrl) {
     log.dim(`  play: ${meta.playUrl}`);
-    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
+    if (pushed === true) log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
   }
 }
 async function pushGame(sshUrl, log) {
@@ -782,8 +790,8 @@ async function pushGame(sshUrl, log) {
   if (!isRepo) {
     log.step("Initializing git\u2026");
     if ((await run("git", ["init"])).code !== 0) {
-      log.warn("git init failed \u2014 skipping push (use `genex publish --no-push` to silence).");
-      return;
+      log.warn("git init failed \u2014 the game was not pushed (use `genex publish --no-push` to silence).");
+      return false;
     }
   }
   await run("git", ["add", "-A"]);
@@ -792,24 +800,177 @@ async function pushGame(sshUrl, log) {
     log.dim("  (no new commit to push)");
   }
   log.step("Pushing your game over SSH\u2026");
-  const push = await run("git", ["push", sshUrl, "HEAD:main"], {
+  const push = await run("git", ["push", sshUrl, "+HEAD:main"], {
     GIT_SSH_COMMAND: `ssh -i ./${KEY_NAME} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
   });
   if (push.code === 0) {
     log.success("Pushed to main.");
-  } else {
-    log.warn("git push didn't succeed (expected locally \u2014 the mock provider has no real repo).");
-    const tail = push.err.trim().split("\n").slice(-1)[0];
-    if (tail) log.dim(`  ${tail}`);
+    return true;
+  }
+  log.warn("git push failed \u2014 your live game was NOT updated.");
+  const tail = push.err.trim().split("\n").slice(-2).join(" ");
+  if (tail) log.dim(`  ${tail}`);
+  return false;
+}
+
+// src/commands/generate.ts
+import path9 from "path";
+
+// src/lib/assets.ts
+import fs6 from "fs/promises";
+import path8 from "path";
+function slugify(input) {
+  const s = input.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 50).replace(/-+$/g, "");
+  return s || "asset";
+}
+async function downloadToFile(url, dest, headers) {
+  const res = await fetch(url, { headers });
+  if (!res.ok) throw new Error(`download failed (HTTP ${res.status}) for ${url}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  await fs6.mkdir(path8.dirname(dest), { recursive: true });
+  await fs6.writeFile(dest, buf);
+  return buf.byteLength;
+}
+
+// src/commands/generate.ts
+var KIND_DIR = {
+  model: "assets/models",
+  skybox: "assets/skybox",
+  sfx: "assets/sfx",
+  texture: "assets/textures"
+};
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function fileDest(kind, slug, f) {
+  if (kind === "texture") {
+    const name = f.role.replace(/^texture-/, "");
+    return `assets/textures/${slug}/${name}.${f.ext}`;
+  }
+  return `${KIND_DIR[kind]}/${slug}.${f.ext}`;
+}
+async function runGenerate(kind, opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const prompt = opts.prompt?.trim();
+  if (!prompt) {
+    log.error(`Missing prompt. Usage: ${c.cyan(`genex ${kind} "<prompt>"`)}`);
+    process.exitCode = 1;
+    return;
+  }
+  const token = opts.token ?? await readUserToken(opts.envPath);
+  if (!token) {
+    log.error("Not authorized. Run `genex init` first to sign in.");
+    process.exitCode = 1;
+    return;
+  }
+  const meta = await readProject();
+  const apiUrl = getApiUrl(opts.apiUrl ?? meta?.apiUrl);
+  const options = {};
+  if (kind === "texture" && opts.terrain) options.terrain = true;
+  if (kind === "sfx" && opts.duration) options.durationSeconds = opts.duration;
+  log.plain(c.bold(`genex ${kind}`));
+  log.dim(`  ${prompt}`);
+  log.plain("");
+  let id;
+  try {
+    const res = await fetch(`${apiUrl}/api/generations`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ kind, prompt, options })
+    });
+    if (res.status === 401) {
+      log.error("Unauthorized \u2014 your token may have expired. Re-run `genex init`.");
+      process.exitCode = 1;
+      return;
+    }
+    if (!res.ok) {
+      log.error(`Generation request failed (HTTP ${res.status}).`);
+      process.exitCode = 1;
+      return;
+    }
+    ({ id } = await res.json());
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (opts.noWait) {
+    log.success(`Queued (${id}). Re-run without --no-wait to fetch the finished asset.`);
+    return;
+  }
+  log.step("Generating\u2026 (this can take up to a minute)");
+  const view = await poll(apiUrl, token, id, (p) => log.dim(`  ${p}%`));
+  if (!view) {
+    log.error("Timed out waiting for the generation.");
+    process.exitCode = 1;
+    return;
+  }
+  if (view.status !== "completed") {
+    log.error(`Generation ${view.status}${view.error ? `: ${view.error}` : ""}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const slug = slugify(prompt);
+  const written = [];
+  try {
+    for (const f of view.files ?? []) {
+      const rel = fileDest(kind, slug, f);
+      const url = `${apiUrl}/api/generations/${id}/asset/${f.role}`;
+      const bytes = await downloadToFile(url, path9.join(process.cwd(), rel), {
+        Authorization: `Bearer ${token}`
+      });
+      written.push(rel);
+      log.success(`${rel} ${c.dim(`(${(bytes / 1024).toFixed(0)} KB)`)}`);
+    }
+  } catch (err) {
+    log.error(`Download failed: ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  log.plain("");
+  printHint(kind, written, log);
+}
+async function poll(apiUrl, token, id, onProgress) {
+  const deadline = Date.now() + 10 * 60 * 1e3;
+  let last = -1;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${apiUrl}/api/generations/${id}`, {
+        headers: { Authorization: `Bearer ${token}` }
+      });
+      if (res.ok) {
+        const { generation } = await res.json();
+        if (generation.progress !== last) {
+          last = generation.progress;
+          onProgress(generation.progress);
+        }
+        if (generation.status === "completed" || generation.status === "failed") {
+          return generation;
+        }
+      }
+    } catch {
+    }
+    await sleep(3e3);
   }
+  return null;
+}
+function printHint(kind, written, log) {
+  const primary = written[0] ?? "";
+  const hint = {
+    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "./${primary}".`,
+    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "./${primary}".`,
+    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "./${primary}".`,
+    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "./${primary}".`
+  };
+  log.success("Done. Asset saved into ./assets (commit it \u2014 `genex publish` ships it with the game).");
+  log.dim(`  ${hint[kind]}`);
 }
 
 // src/index.ts
+var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
   try {
-    const here = path8.dirname(fileURLToPath2(import.meta.url));
+    const here = path10.dirname(fileURLToPath2(import.meta.url));
     const pkg = JSON.parse(
-      readFileSync(path8.resolve(here, "..", "package.json"), "utf8")
+      readFileSync(path10.resolve(here, "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -821,6 +982,17 @@ var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize
 ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.
   genex publish [options]            Push the built game and list it in the gallery.
+  genex model "<prompt>" [options]   Generate a 3D model (GLB) into ./assets/models.
+  genex skybox "<prompt>" [options]  Generate a skybox (equirect) into ./assets/skybox.
+  genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into ./assets/sfx.
+  genex texture "<prompt>" [options] Generate a PBR texture into ./assets/textures.
+
+${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
+  --terrain            (texture) seamless tiling surface for terrain/ground.
+  --duration <sec>     (sfx) target clip length in seconds.
+  --no-wait            Enqueue only; don't block waiting for the asset.
+  --api-url <url>      Override the API base URL.
+  --env <path>         Token env file (default: ~/.genex/env).
 
 ${c.bold("Options for `init`")}
   <name>               Project name (positional; default: current directory name).
@@ -857,6 +1029,10 @@ ${c.bold("Examples")}
   genex init my-game --api-url http://localhost:3000 --auth-url http://localhost:5173
   genex publish
   genex publish --no-push --title "My Game"
+  genex model "weathered wooden barrel with iron bands"
+  genex skybox "golden hour over a misty mountain range"
+  genex sfx "punchy laser zap" --duration 2
+  genex texture "mossy cracked cobblestone" --terrain
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -874,7 +1050,8 @@ function parseArgs(argv) {
     "--name",
     "--title",
     "--description",
-    "--timeout"
+    "--timeout",
+    "--duration"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -895,6 +1072,12 @@ function parseArgs(argv) {
       case "--no-push":
         parsed.options.noPush = true;
         break;
+      case "--no-wait":
+        parsed.options.noWait = true;
+        break;
+      case "--terrain":
+        parsed.options.terrain = true;
+        break;
       case "--force":
         parsed.options.force = true;
         break;
@@ -960,6 +1143,14 @@ function applyValueFlag(options, flag, value) {
       options.timeoutSec = n;
       break;
     }
+    case "--duration": {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`Invalid --duration value: ${value}`);
+      }
+      options.duration = n;
+      break;
+    }
   }
 }
 async function main() {
@@ -986,6 +1177,13 @@ async function main() {
     log.plain(HELP);
     return;
   }
+  if (GEN_KINDS.has(parsed.command)) {
+    await runGenerate(parsed.command, {
+      ...parsed.options,
+      prompt: parsed.options.name
+    });
+    return;
+  }
   switch (parsed.command) {
     case "init":
       await runInit(parsed.options);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.1.1",
-  "description": "Set up your ~/.claude workspace, authorize, create a game project, and publish (genex CLI).",
+  "version": "0.2.0",
+  "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
     "genex": "./dist/index.js"

package/templates/skills/genex-ai-model/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: genex-ai-model
+description: Generate a real 3D model (GLB mesh) from a text prompt with `genex model`, then load it into the Three.js scene. Use when the user wants a specific prop, item, character, vehicle, building, or any concrete object as an actual mesh ("add a wooden barrel", "I need a spaceship", "generate a sword") rather than a procedurally-coded shape.
+---
+
+# Genex AI · Model
+
+Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
+
+## When to use this vs. procedural geometry
+
+- **Use `genex model`** for a specific, recognizable object — a barrel, a chair, a
+  sword, a spaceship, an animal. You get a real textured mesh.
+- **Use `$genex-threejs-procedural-geometry`** for parametric/abstract shapes,
+  terrain, or anything you want to generate in code (infinite variations, no files).
+
+## Run
+
+```bash
+genex model "<prompt>"
+```
+
+Write a specific prompt — "weathered wooden barrel with rusted iron bands" beats
+"barrel". The command blocks until the mesh is ready (up to ~a minute), then saves:
+
+```
+assets/models/<slug>.glb
+```
+
+`<slug>` is derived from the prompt (e.g. `weathered-wooden-barrel.glb`). The file
+is **committed by `genex publish`**, so it ships inside your published game.
+
+## Load it into the scene
+
+Use Three.js `GLTFLoader` with the **relative** path (so it works under the
+published subpath `https://<user>.github.io/<slug>/`):
+
+```ts
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+
+const loader = new GLTFLoader();
+const gltf = await loader.loadAsync("./assets/models/weathered-wooden-barrel.glb");
+const model = gltf.scene;
+model.scale.setScalar(1); // tune to taste
+model.position.set(0, 0, 0);
+scene.add(model);
+```
+
+To place many copies, `model.clone()` per instance. For animated GLBs, drive
+`gltf.animations` with a `THREE.AnimationMixer`.
+
+## Publish checklist (so players see the model)
+
+- Reference assets with **relative** paths (`./assets/...`), never absolute
+  (`/assets/...`) — GitHub Pages serves the game at a subpath.
+- Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
+  prompt's publish step).
+- Commit the `assets/` folder — `genex publish` pushes it with the game.
+
+## Options
+
+- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
+  re-run without `--no-wait` to fetch it).
+- `--api-url <url>` — override the API base (local dev).
+
+## Troubleshooting
+
+- **"Not authorized"** — run `genex init` first (it writes your `GENEX_TOKEN`).
+- **The mesh looks low-detail / wrong** — make the prompt more specific
+  (materials, style, parts) and regenerate; each run is a fresh asset.

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: genex-ai-sfx
+description: Generate a real sound effect (mp3) from a text prompt with `genex sfx`, then play it in Three.js (positional or global audio). Use when the user wants a specific sound — a gunshot, footstep, pickup chime, explosion, engine hum, UI click, whoosh — triggered on a game event.
+---
+
+# Genex AI · SFX
+
+Turn a prompt into a real **mp3** sound effect and wire it to a game event.
+
+## Run
+
+```bash
+genex sfx "<prompt>"
+genex sfx "punchy laser zap, short and dry" --duration 2
+```
+
+`--duration <sec>` (0.5–22) sets a target length; omit it to let the model pick.
+Blocks until ready, then saves:
+
+```
+assets/sfx/<slug>.mp3
+```
+
+Committed by `genex publish`, so it ships with your game.
+
+## Play it in Three.js
+
+Audio needs **one `AudioListener` on the camera**. Then load the clip and play it
+on an event. Browsers block autoplay — start audio after a user gesture (click/keydown).
+
+**Positional** (3D, attenuates with distance — attach to an object):
+
+```ts
+import * as THREE from "three";
+
+const listener = new THREE.AudioListener();
+camera.add(listener);
+
+const buffer = await new THREE.AudioLoader().loadAsync("./assets/sfx/laser-zap.mp3");
+
+const sound = new THREE.PositionalAudio(listener);
+sound.setBuffer(buffer);
+sound.setRefDistance(5);
+laserMesh.add(sound); // follows the object
+
+// on fire:
+if (!sound.isPlaying) sound.play();
+```
+
+**Global** (UI/non-spatial — same volume everywhere): use `new THREE.Audio(listener)`
+instead of `PositionalAudio` and don't attach it to a mesh.
+
+Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalAudio`
+(or call `sound.play()` again once stopped) per trigger.
+
+## Publish checklist
+
+- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+
+## Troubleshooting
+
+- **No sound** — the `AudioContext` is suspended until a user gesture; trigger the
+  first play from a click/keydown. Confirm the camera has an `AudioListener`.
+- **Too quiet/loud** — `sound.setVolume(0..1)`; for positional, tune
+  `setRefDistance` / `setRolloffFactor`.

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: genex-ai-skybox
+description: Generate a real 360° skybox (equirectangular panorama) from a text prompt with `genex skybox`, then load it as the scene background + environment lighting in Three.js. Use when the user wants a specific photoreal/painted sky or backdrop ("sunset over the ocean", "alien purple nebula", "foggy pine forest") as an image, rather than a procedural/shader sky.
+---
+
+# Genex AI · Skybox
+
+Turn a prompt into a 360° **equirectangular** panorama that wraps the scene and
+also lights it (image-based lighting).
+
+## When to use this vs. a procedural sky
+
+- **Use `genex skybox`** for a specific, recognizable sky/backdrop you can
+  describe — "golden hour over misty mountains", "stormy alien sky", "city at
+  night". You get a real image.
+- **Use `$genex-threejs-atmosphere-aerial-perspective`** (or
+  `$genex-threejs-volumetric-clouds`) for a fully procedural, animated,
+  time-of-day sky generated in shaders.
+
+## Run
+
+```bash
+genex skybox "<prompt>"
+```
+
+Blocks until ready, then saves:
+
+```
+assets/skybox/<slug>.jpg
+```
+
+The JPG is **committed by `genex publish`**, so it ships with your game.
+
+## Load it as background + environment
+
+Load the equirect JPG, mark it equirectangular, and use it for both the visible
+background and the lighting:
+
+```ts
+import * as THREE from "three";
+
+const texture = await new THREE.TextureLoader().loadAsync(
+  "./assets/skybox/golden-hour-over-misty-mountains.jpg",
+);
+texture.mapping = THREE.EquirectangularReflectionMapping;
+texture.colorSpace = THREE.SRGBColorSpace;
+
+scene.background = texture;   // visible sky
+scene.environment = texture;  // image-based lighting on PBR materials
+```
+
+For sharper reflections/lighting, pre-filter it with `PMREMGenerator`:
+
+```ts
+const pmrem = new THREE.PMREMGenerator(renderer);
+const envMap = pmrem.fromEquirectangular(texture).texture;
+scene.environment = envMap;
+scene.background = texture; // keep the raw texture for the visible sky
+texture.dispose; // (dispose the PMREM source later if you stop using it)
+```
+
+## Publish checklist
+
+- Use the **relative** path `./assets/skybox/...` (GitHub Pages serves at a subpath).
+- `base: "./"` in `vite.config.ts` before `npm run build`.
+- Commit `assets/` — `genex publish` pushes it with the game.
+
+## Troubleshooting
+
+- **Sky looks too dark/bright** — adjust `renderer.toneMappingExposure`, or scale
+  `scene.environment` influence via material `envMapIntensity`.
+- **Seam/pole artifacts** — that's inherent to equirect images; keep the camera
+  away from looking straight up/down, or use PMREM for the lighting.

package/templates/skills/genex-ai-texture/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: genex-ai-texture
+description: Generate a real photoreal surface texture (PBR base-color image) from a text prompt with `genex texture`, then apply it as a tiling material on meshes or terrain in Three.js. Use `--terrain` for seamless ground. Use when the user wants a specific photoreal material on a surface ("rusty metal floor", "mossy cobblestone path", "grassy terrain") rather than a procedural/shader material.
+---
+
+# Genex AI · Texture
+
+Turn a prompt into a real, tileable **base-color** texture image and apply it as a
+material on a primitive, a mesh, or terrain.
+
+## When to use this vs. procedural materials
+
+- **Use `genex texture`** for a specific photoreal surface you can describe —
+  "weathered Roman cobblestone", "cracked desert clay", "oak planks". You get a
+  real raster image.
+- **Use `$genex-threejs-procedural-materials`** for stylized/abstract or
+  fully-parametric materials authored in shaders (instant, perfectly tiling, no
+  files). The two are complementary.
+
+## Run
+
+```bash
+genex texture "<prompt>"
+genex texture "lush green grass" --terrain    # seamless tiling for ground/terrain
+```
+
+Blocks until ready, then saves:
+
+```
+assets/textures/<slug>/basecolor.<ext>
+```
+
+Committed by `genex publish`, so it ships with your game.
+
+> **Scope:** v1 generates the **base-color (albedo)** map only. Normal / roughness
+> / AO are a planned follow-up — for now set sensible `roughness`/`metalness`
+> constants on the material.
+
+## Apply it (tiling material)
+
+```ts
+import * as THREE from "three";
+
+const map = await new THREE.TextureLoader().loadAsync(
+  "./assets/textures/lush-green-grass/basecolor.jpg",
+);
+map.colorSpace = THREE.SRGBColorSpace;
+map.wrapS = map.wrapT = THREE.RepeatWrapping;
+map.repeat.set(8, 8);          // tile count — raise for large surfaces
+map.anisotropy = renderer.capabilities.getMaxAnisotropy();
+
+const material = new THREE.MeshStandardMaterial({ map, roughness: 0.9, metalness: 0 });
+groundMesh.material = material; // e.g. a PlaneGeometry ground
+```
+
+### Terrain
+
+Generate with `--terrain`, lay a large `PlaneGeometry` (rotated flat), and raise
+`repeat` so the texture tiles densely across it:
+
+```ts
+const ground = new THREE.Mesh(new THREE.PlaneGeometry(200, 200), material);
+ground.rotation.x = -Math.PI / 2;
+map.repeat.set(64, 64);
+scene.add(ground);
+```
+
+## Publish checklist
+
+- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; commit `assets/`.
+
+## Troubleshooting
+
+- **Visible tiling seams** — use `--terrain` (tuned for seamless edges), lower the
+  `repeat`, or blend two textures. Perfect seamlessness is a known v1 limitation.
+- **Colors look washed/dark** — ensure `map.colorSpace = THREE.SRGBColorSpace`.

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

@@ -21,6 +21,21 @@ 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.
 
+## Generating real assets
+
+Beyond procedural code, Genex can generate **real, AI-made assets** from a prompt
+and drop them into `./assets/` (committed when you publish):
+
+```bash
+genex model "weathered wooden barrel"      # a 3D mesh (GLB)
+genex skybox "golden hour over mountains"  # a 360° sky + lighting
+genex sfx "punchy laser zap" --duration 2  # a sound effect (mp3)
+genex texture "mossy cobblestone" --terrain # a tiling surface texture
+```
+
+Each has a focused skill with the exact loader code — `$genex-ai-model`,
+`$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
+
 Your existing files were left untouched. `genex init` only adds what is missing.
 
 ## Re-running setup

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

@@ -37,6 +37,25 @@ map, execution order, and acceptance gate.
 | render-target ownership, pass ordering, depth/normal/history signals | `$genex-threejs-image-pipeline` |
 | fixed-view captures, seed sweeps, browser and GPU evidence | `$genex-threejs-visual-validation` |
 
+## Real (AI-generated) assets — `genex` commands
+
+When the user wants a **specific, recognizable asset** (a named object, a described
+sky, a particular sound or surface) rather than something authored in code, generate
+it with a `genex` command. Each drops a real file into `./assets/` (committed by
+`genex publish`), and its skill has the exact Three.js loader code.
+
+| Work needed | Generate with | Skill |
+| --- | --- | --- |
+| a specific prop / item / character / vehicle as a real mesh | `genex model "<prompt>"` | `$genex-ai-model` |
+| a described 360° sky / backdrop + image-based lighting | `genex skybox "<prompt>"` | `$genex-ai-skybox` |
+| a specific sound effect tied to an event | `genex sfx "<prompt>"` | `$genex-ai-sfx` |
+| a photoreal surface/material on a mesh or terrain | `genex texture "<prompt>" [--terrain]` | `$genex-ai-texture` |
+
+Prefer the **procedural** skills above for abstract/parametric/animated systems
+(geometry, materials, sky, water, VFX) — no files, infinite variation. Prefer the
+**`genex` generators** for concrete, describable, photoreal assets. They complement
+each other.
+
 ## Routing rules
 
 - Start from the playable game target: player verb, scene scale, camera distance,