@genex-ai/cli-demo 0.20.0 → 0.22.0

package/README.md

@@ -8,10 +8,10 @@ genex init <name>          # authorize + create the draft project
 genex link <slug>          # re-link this folder to an existing game of yours (recovery)
 genex preview              # build + push to the hosted draft URL (unlisted)
 genex publish              # build + push, then list the game 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 model "<prompt>"     # generate a 3D model  → prints an asset URL
+genex skybox "<prompt>"    # generate a 360° sky  → prints an asset URL
+genex sfx "<prompt>"       # generate a sound fx  → prints an asset URL
+genex texture "<prompt>"   # generate a texture   → prints an asset URL
 genex controller <type>    # install a tuned character|car|drone controller → src/controllers/
 ```
 
@@ -70,22 +70,22 @@ Defaults: API `https://demo-api.glotech.world`, auth site
 ## 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):
+game-ready asset stored in R2. The command blocks until the asset is ready (live SSE
+stream), then prints its public URL — the game loads it directly, nothing is
+downloaded or committed:
 
-| Command | Provider | Writes |
+| Command | Provider | Prints (role) |
 | --- | --- | --- |
-| `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` uploads the whole built
-directory, generated assets **ship inside the published R2 bundle** — games serve
-at the domain root (`https://<slug>.genex.technology/`), so both absolute
-(`/assets/...`) and relative (`./assets/...`) paths resolve, 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.
+| `genex model "<prompt>"` | Tripo | `…/generations/<id>/model-glb` |
+| `genex skybox "<prompt>"` | Blockade Labs | `…/generations/<id>/skybox-equirect` |
+| `genex sfx "<prompt>" [--duration <s>]` | ElevenLabs | `…/generations/<id>/audio-sfx` |
+| `genex texture "<prompt>" [--terrain]` | Gemini | `…/generations/<id>/texture-basecolor` |
+
+Each URL is a permanent `https://assets.genex.technology/...` address served straight
+from R2 (with CORS, so three.js loads it cross-origin without tainting). It resolves
+the same in local dev, the published game, and remixes, and the bytes never pass back
+through 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`,

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync } from "fs";
-import path14 from "path";
+import path12 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // src/commands/init.ts
@@ -1399,6 +1399,9 @@ async function runPublish(opts) {
     if (opts.description) body.description = opts.description;
     if (opts.regenerateCover) body.regenerateCover = true;
     if (opts.categories?.length) body.categories = opts.categories;
+    if (opts.sourceRepoUrl) body.sourceRepoUrl = opts.sourceRepoUrl;
+    if (opts.sourceAuthor) body.sourceAuthor = opts.sourceAuthor;
+    if (opts.license) body.license = opts.license;
     if (detections.embedSdkVersion) body.embedSdkVersion = detections.embedSdkVersion;
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
@@ -1465,25 +1468,6 @@ async function runPreview(opts) {
   log.success("Preview deployed \u2014 unlisted draft (run `genex publish` to list it).");
 }
 
-// src/commands/generate.ts
-import path12 from "path";
-
-// src/lib/assets.ts
-import fs10 from "fs/promises";
-import path11 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 fs10.mkdir(path11.dirname(dest), { recursive: true });
-  await fs10.writeFile(dest, buf);
-  return buf.byteLength;
-}
-
 // src/lib/sse.ts
 async function* readSSE(body) {
   const decoder = new TextDecoder();
@@ -1524,24 +1508,7 @@ async function* readSSE(body) {
 }
 
 // src/commands/generate.ts
-var PUBLIC_PREFIX = "public/";
-var KIND_DIR = {
-  model: "public/assets/models",
-  skybox: "public/assets/skybox",
-  sfx: "public/assets/sfx",
-  texture: "public/assets/textures"
-};
-function runtimePath(rel) {
-  return `./${rel.replace(PUBLIC_PREFIX, "")}`;
-}
 var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
-function fileDest(kind, slug, f) {
-  if (kind === "texture") {
-    const name = f.role.replace(/^texture-/, "");
-    return `public/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();
@@ -1588,7 +1555,7 @@ async function runGenerate(kind, opts) {
     return;
   }
   if (opts.noWait) {
-    log.success(`Queued (${id}). Re-run without --no-wait to fetch the finished asset.`);
+    log.success(`Queued (${id}). Re-run without --no-wait to get the finished asset URL.`);
     return;
   }
   log.step("Generating\u2026 (this can take up to a minute)");
@@ -1606,25 +1573,20 @@ async function runGenerate(kind, opts) {
     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, path12.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)}`);
+  const files = view.files ?? [];
+  if (files.length === 0) {
+    log.error("Generation completed but produced no files.");
     process.exitCode = 1;
     return;
   }
   log.plain("");
-  printHint(kind, written, log);
+  log.success("Done \u2014 live on R2 (nothing downloaded or committed):");
+  for (const f of files) {
+    const label = files.length > 1 ? `${c.dim(`${f.role.replace(/^texture-/, "")}: `)}` : "";
+    log.plain(`  ${label}${f.url}`);
+  }
+  log.plain("");
+  printHint(kind, files, log);
 }
 var WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
 var TERMINAL = /* @__PURE__ */ new Set(["completed", "failed"]);
@@ -1703,23 +1665,21 @@ async function poll(apiUrl, token, id, onProgress) {
   }
   return null;
 }
-function printHint(kind, written, log) {
-  const load = runtimePath(written[0] ?? "");
+function printHint(kind, files, log) {
+  const url = files[0]?.url ?? "";
   const hint = {
-    model: `Load with GLTFLoader and add to the scene \u2014 see the genex-ai-model skill. Use the relative path "${load}".`,
-    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. Path "${load}".`,
-    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. Path "${load}".`,
-    texture: `Load with TextureLoader, set RepeatWrapping, build a MeshStandardMaterial \u2014 see genex-ai-texture. Path "${load}".`
+    model: `Load with GLTFLoader from the URL and add it to the scene \u2014 see the genex-ai-model skill. url = "${url}"`,
+    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. url = "${url}"`,
+    sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. url = "${url}"`,
+    texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`
   };
-  log.success(
-    "Done. Asset saved into public/assets (so Vite ships it; load it as ./assets/\u2026 \u2014 `genex publish` commits and ships it with the game)."
-  );
   log.dim(`  ${hint[kind]}`);
+  log.dim("  Reference the URL directly in your code \u2014 don't download it into the repo.");
 }
 
 // src/commands/controller.ts
-import fs11 from "fs/promises";
-import path13 from "path";
+import fs10 from "fs/promises";
+import path11 from "path";
 var CONTROLLER_KINDS = ["character", "car", "drone"];
 var SHARED = [
   "shared/math.ts",
@@ -1798,8 +1758,8 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path13.join("src", "controllers");
-var ASSETS_DEST = path13.join("public", "assets");
+var CODE_DEST = path11.join("src", "controllers");
+var ASSETS_DEST = path11.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
   const kind = opts.kind?.trim();
@@ -1812,31 +1772,31 @@ async function runController(opts) {
     process.exitCode = 1;
     return;
   }
-  const srcDir = path13.join(getTemplatesDir(), "controllers");
+  const srcDir = path11.join(getTemplatesDir(), "controllers");
   const root = opts.cwd ?? process.cwd();
   const set = CONTROLLER_FILE_SETS[kind];
   log.plain(c.bold(`genex controller ${kind}`));
   log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path13.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path11.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path13.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path11.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path13.join(ASSETS_DEST, path13.basename(rel))
+      rel: path11.join(ASSETS_DEST, path11.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path13.join(root, file.rel);
+      const dest = path11.join(root, file.rel);
       if (!opts.force && await exists2(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs11.mkdir(path13.dirname(dest), { recursive: true });
-      await fs11.copyFile(path13.join(srcDir, file.from), dest);
+      await fs10.mkdir(path11.dirname(dest), { recursive: true });
+      await fs10.copyFile(path11.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -1868,8 +1828,8 @@ async function runController(opts) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path13.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs11.mkdir(path13.dirname(dest), { recursive: true });
+  const dest = path11.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs10.mkdir(path11.dirname(dest), { recursive: true });
   if (token) {
     try {
       const res = await fetch(`${apiUrl}/api/avatars/me`, {
@@ -1881,7 +1841,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs11.writeFile(dest, buf);
+            await fs10.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -1892,27 +1852,93 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs11.copyFile(path13.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs10.copyFile(path11.join(srcDir, "assets", "default-avatar.vrm"), dest);
   log.dim(
     token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
   );
 }
 async function exists2(p) {
   try {
-    await fs11.access(p);
+    await fs10.access(p);
     return true;
   } catch {
     return false;
   }
 }
 
+// src/commands/explore.ts
+async function runExplore(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const query = opts.query?.trim();
+  if (!query) {
+    log.error('Missing query. Usage: genex explore "<what you need>"');
+    process.exitCode = 1;
+    return;
+  }
+  const apiUrl = getApiUrl(opts.apiUrl);
+  let res;
+  try {
+    res = await fetch(`${apiUrl}/api/gallery/search-corpus?curated=1`);
+  } catch {
+    log.error("Couldn't reach Genex \u2014 please try again.");
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    log.error(`explore: API returned ${res.status} \u2014 please try again.`);
+    process.exitCode = 1;
+    return;
+  }
+  const { items } = await res.json();
+  const ranked = rank(items, query).slice(0, 5);
+  if (opts.json) {
+    console.log(JSON.stringify(ranked, null, 2));
+    return;
+  }
+  if (ranked.length === 0) {
+    log.plain(
+      `No curated projects matched "${query}". Try a broader term (terrain, grass, vehicle, water, building, dungeon, fish, shader).`
+    );
+    return;
+  }
+  for (const [i, p] of ranked.entries()) {
+    const meta = [
+      p.categories.join(", "),
+      p.license ?? "",
+      p.sourceAuthor ? `originally by ${p.sourceAuthor}` : ""
+    ].filter(Boolean).join(" \xB7 ");
+    log.plain(`${c.bold(`${i + 1}. ${p.title}`)} \u2014 ${meta}`);
+    if (p.description) log.plain(`   ${p.description.slice(0, 160)}`);
+    if (p.playUrl) log.plain(`   play:  ${p.playUrl}`);
+    if (p.cloneUrl) log.plain(`   clone: ${p.cloneUrl}   (editable source on main)`);
+    if (p.sourceRepoUrl) log.plain(`   upstream: ${p.sourceRepoUrl}`);
+  }
+  log.plain("");
+  log.plain(
+    `To use one: clone it as a starting template, or borrow parts into your current game \u2014 the genex-explore skill has the exact steps. Keep the credits.`
+  );
+}
+function rank(items, query) {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  return items.map((p) => {
+    const hay = `${p.title} ${p.description} ${p.categories.join(" ")}`.toLowerCase();
+    let score = 0;
+    for (const t of terms) {
+      if (p.title.toLowerCase().includes(t)) score += 3;
+      if (p.categories.some((cat) => cat.includes(t))) score += 2;
+      if (hay.includes(t)) score += 1;
+    }
+    return { p, score };
+  }).filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.p.playsCount - a.p.playsCount).map((x) => x.p);
+}
+
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
 function getVersion() {
   try {
-    const here = path14.dirname(fileURLToPath2(import.meta.url));
+    const here = path12.dirname(fileURLToPath2(import.meta.url));
     const pkg = JSON.parse(
-      readFileSync(path14.resolve(here, "..", "package.json"), "utf8")
+      readFileSync(path12.resolve(here, "..", "package.json"), "utf8")
     );
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1934,6 +1960,8 @@ ${c.bold("Usage")}
   genex texture "<prompt>" [options] Generate a PBR texture into public/assets/textures.
   genex controller <type> [--force]  Install a physics controller (character|car|drone)
                                      into src/controllers (+ assets into public/assets).
+  genex explore "<query>" [options]  Search the curated community gallery \u2014 proven
+                                     Three.js systems you can clone or borrow parts from.
 
 ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
@@ -1972,9 +2000,17 @@ ${c.bold("Options for `preview` / `publish`")}
   --categories <list>  (publish) 1-3 gallery categories, comma-separated.
                        Valid: games, assets, physics, terrain, lighting, vfx.
   --regenerate-cover   (publish) Re-mint the disc cover (concept changed).
+  --source-repo-url <url>  (publish) Upstream repo this game is a port of \u2014
+                       shown as "Ported from \u2026" credit on the game page.
+  --source-author <name>   (publish) Upstream author to credit.
+  --license <label>        (publish) Upstream license label (e.g. MIT).
   --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
+${c.bold("Options for `explore`")}
+  --json               Print the top matches as JSON (for tools/agents).
+  --api-url <url>      Override the API base URL.
+
 ${c.bold("Global")}
   --quiet              Reduce output.
   -h, --help           Show this help.
@@ -1999,6 +2035,7 @@ ${c.bold("Examples")}
   genex sfx "punchy laser zap" --duration 2
   genex texture "mossy cracked cobblestone" --terrain
   genex controller character
+  genex explore "grass"
 `;
 function parseArgs(argv) {
   const parsed = {
@@ -2019,7 +2056,10 @@ function parseArgs(argv) {
     "--description",
     "--categories",
     "--timeout",
-    "--duration"
+    "--duration",
+    "--source-repo-url",
+    "--source-author",
+    "--license"
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -2058,6 +2098,9 @@ function parseArgs(argv) {
       case "--quiet":
         parsed.options.quiet = true;
         break;
+      case "--json":
+        parsed.options.json = true;
+        break;
       default: {
         if (needsValue.has(arg)) {
           const value = argv[i++];
@@ -2073,6 +2116,8 @@ function parseArgs(argv) {
           parsed.command = arg;
         } else if (parsed.options.name === void 0) {
           parsed.options.name = arg;
+        } else if (parsed.command === "explore") {
+          parsed.options.name = `${parsed.options.name} ${arg}`;
         } else {
           parsed.error = `Unexpected argument: ${arg}`;
           return parsed;
@@ -2115,6 +2160,15 @@ function applyValueFlag(options, flag, value) {
     case "--categories":
       options.categories = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
       break;
+    case "--source-repo-url":
+      options.sourceRepoUrl = value;
+      break;
+    case "--source-author":
+      options.sourceAuthor = value;
+      break;
+    case "--license":
+      options.license = value;
+      break;
     case "--timeout": {
       const n = Number(value);
       if (!Number.isFinite(n) || n <= 0) {
@@ -2180,6 +2234,9 @@ async function main() {
     case "publish":
       await runPublish(parsed.options);
       break;
+    case "explore":
+      await runExplore({ ...parsed.options, query: parsed.options.name });
+      break;
     default:
       log.error(`Unknown command: ${parsed.command}`);
       log.plain(`Run ${c.cyan("genex --help")} for usage.`);

package/package.json

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

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

@@ -21,47 +21,58 @@ npx 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:
+"barrel". The command blocks until the mesh is ready (up to ~a minute), then prints
+its public URL:
 
 ```
-public/assets/models/<slug>.glb
+https://assets.genex.technology/generations/<id>/model-glb
 ```
 
-`<slug>` is derived from the prompt (e.g. `weathered-wooden-barrel.glb`). The file
-lives under `public/` so Vite ships it in the build (load it as `./assets/models/...` —
-the `public/` prefix is stripped when served). It is **committed by `npx genex publish`**,
-so it ships inside your published game.
-
-## Hero models must face forward
-
-For the model the player controls (a ship, car, character — the "hero"), the mesh should
-**face forward**: its front pointing down the direction of travel (conventionally `+Z`,
-i.e. "looking forward"). A hero whose nose points sideways reads as broken at a glance.
-
-- **In the prompt:** when it's the player's craft, ask for it facing forward — e.g.
-  `"...game-ready, facing forward, front toward +Z"`.
-- **On load (fallback):** if the imported GLB still isn't forward, rotate it once so its
-  nose aligns with travel. Wrap the model in a parent `Object3D` and apply the correction
-  to the child, so your movement code can rotate the parent cleanly:
+The GLB lives in Genex storage (R2) and loads straight from that URL. You **don't
+download it** and **nothing is committed to your repo** — copy the URL the command
+prints into your loader. The URL is permanent, so it works the same in local dev, your
+published game, and remixes.
+
+## Models that point somewhere must face forward
+
+Any model with a "front" the game aims — the hero the player controls, an **NPC that
+walks toward or looks at players**, a turret, a vehicle — should face **forward**: its
+front toward `+Z` (glTF's "looking forward"), so yaw/`lookAt` code points it correctly.
+A hero whose nose points sideways — or an enemy that chases you while staring off to the
+side — reads as broken at a glance.
+
+- **In the prompt:** ask for it — e.g. `"...game-ready, facing forward, front toward +Z"`.
+  Treat this as a hint, not a guarantee: generated meshes regularly come back rotated
+  anyway, so the check below is never optional.
+- **On load (always check — hero AND NPC):** if the GLB isn't `+Z`-forward, rotate it
+  once. Wrap the model in a parent `Object3D` and put the correction on the child, so
+  game code rotates the parent cleanly:
   ```ts
-  const hero = new THREE.Object3D();
+  const rig = new THREE.Object3D();
   gltf.scene.rotation.y = Math.PI / 2; // one-time facing correction — tune per model
-  hero.add(gltf.scene);
-  scene.add(hero); // move/rotate `hero`, not gltf.scene
+  rig.add(gltf.scene);
+  scene.add(rig); // move/rotate/lookAt `rig`, not gltf.scene
   ```
-- Orientation **is** visible in a still — confirm the hero faces forward in your
-  self-check screenshot before moving on.
+  Clones inherit the fix only if you clone the corrected child (or the whole rig) —
+  never the raw `gltf.scene`.
+- **Verify it, don't assume it.** Orientation **is** visible in a still — in your
+  self-check screenshot confirm the hero faces its travel direction AND that NPCs driven
+  by chase/aim code face their target (an enemy rotated 90° from its victim is this
+  pipeline's most common visible bug). If you can't capture real gameplay (a draft's
+  sign-in gate is up), say so plainly instead of skipping the check silently.
 
 ## Load it into the scene
 
-Use Three.js `GLTFLoader` (the game serves at the domain root
-`https://<slug>.genex.technology/`, so relative or absolute paths both work):
+Use Three.js `GLTFLoader` with the URL the command printed (R2 sends the right CORS
+headers, so cross-origin loading just works):
 
 ```ts
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 
 const loader = new GLTFLoader();
-const gltf = await loader.loadAsync("./assets/models/weathered-wooden-barrel.glb");
+// the URL `npx genex model` printed:
+const MODEL_URL = "https://assets.genex.technology/generations/<id>/model-glb";
+const gltf = await loader.loadAsync(MODEL_URL);
 const model = gltf.scene;
 model.scale.setScalar(1); // tune to taste
 model.position.set(0, 0, 0);
@@ -78,17 +89,14 @@ scene is a ghost: players and objects pass straight through it.
 
 ## Publish checklist (so players see the model)
 
-- Reference assets with **relative** paths (`./assets/...`); absolute
-  (`/assets/...`) also resolves since the game serves at the domain root.
-- Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
-  prompt's publish step).
-- Keep generated assets under `public/assets/` — Vite only ships files under `public/`
-  (or files you `import`); `npx genex publish` ships that folder with the game.
+- Load it from the **URL** the command printed — it's absolute and permanent, so it
+  resolves the same in local dev, the published game, and remixes. Nothing to commit.
+- Don't copy the GLB into `public/assets/` — generated assets live in R2, not the repo.
 
 ## Options
 
-- `--no-wait` — enqueue and return immediately (the file won't be downloaded;
-  re-run without `--no-wait` to fetch it).
+- `--no-wait` — enqueue and return immediately (won't print the URL; re-run without
+  `--no-wait` to get it).
 - `--api-url <url>` — override the API base (local dev).
 
 ## Troubleshooting

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

@@ -15,13 +15,15 @@ npx 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:
+Blocks until ready, then prints its public URL:
 
 ```
-public/assets/sfx/<slug>.mp3
+https://assets.genex.technology/generations/<id>/audio-sfx
 ```
 
-Committed by `npx genex publish`, so it ships with your game.
+The mp3 lives in Genex storage (R2) and loads straight from that URL — you don't download
+it and nothing is committed to your repo. The URL is permanent (local dev, published game,
+and remixes alike).
 
 ## Play it in Three.js
 
@@ -36,7 +38,9 @@ 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");
+// the URL `npx genex sfx` printed (R2 sends CORS headers, so cross-origin works):
+const SFX_URL = "https://assets.genex.technology/generations/<id>/audio-sfx";
+const buffer = await new THREE.AudioLoader().loadAsync(SFX_URL);
 
 const sound = new THREE.PositionalAudio(listener);
 sound.setBuffer(buffer);
@@ -55,8 +59,8 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 
 ## Publish checklist
 
-- Relative path `./assets/sfx/...`; `base: "./"` in `vite.config.ts`; files live under
-  `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
+- Load it from the **URL** the command printed — absolute and permanent, so it resolves
+  the same in local dev, the published game, and remixes. Nothing to commit.
 
 ## Options
 

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

@@ -23,13 +23,15 @@ also lights it (image-based lighting).
 npx genex skybox "<prompt>"
 ```
 
-Blocks until ready, then saves:
+Blocks until ready, then prints its public URL:
 
 ```
-public/assets/skybox/<slug>.jpg
+https://assets.genex.technology/generations/<id>/skybox-equirect
 ```
 
-The JPG is **committed by `npx genex publish`**, so it ships with your game.
+The image lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (works the same
+in local dev, the published game, and remixes).
 
 ## Load it as background + environment
 
@@ -39,9 +41,9 @@ 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",
-);
+// the URL `npx genex skybox` printed (R2 sends CORS headers, so cross-origin works):
+const SKYBOX_URL = "https://assets.genex.technology/generations/<id>/skybox-equirect";
+const texture = await new THREE.TextureLoader().loadAsync(SKYBOX_URL);
 texture.mapping = THREE.EquirectangularReflectionMapping;
 texture.colorSpace = THREE.SRGBColorSpace;
 
@@ -62,10 +64,9 @@ scene.background = texture; // keep the raw texture for the visible sky
 
 ## Publish checklist
 
-- Use the **relative** path `./assets/skybox/...` (absolute `/assets/...` also works — the game serves at the domain root).
-- `base: "./"` in `vite.config.ts` before `npm run build`.
-- Generated files live under `public/assets/` so Vite ships them; `npx genex publish`
-  ships that folder with the game.
+- Load it from the **URL** the command printed — absolute and permanent, so it resolves
+  the same in local dev, the published game, and remixes. Nothing to commit.
+- Don't copy the image into `public/assets/` — generated assets live in R2, not the repo.
 
 ## Options
 

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

@@ -24,13 +24,15 @@ npx genex texture "<prompt>"
 npx genex texture "lush green grass" --terrain    # seamless tiling for ground/terrain
 ```
 
-Blocks until ready, then saves:
+Blocks until ready, then prints its public URL:
 
 ```
-public/assets/textures/<slug>/basecolor.<ext>
+https://assets.genex.technology/generations/<id>/texture-basecolor
 ```
 
-Committed by `npx genex publish`, so it ships with your game.
+The image lives in Genex storage (R2) and loads straight from that URL — you don't
+download it and nothing is committed to your repo. The URL is permanent (local dev,
+published game, and remixes alike).
 
 > **Scope:** v1 generates the **base-color (albedo)** map only. Normal / roughness
 > / AO are a planned follow-up — for now set sensible `roughness`/`metalness`
@@ -41,11 +43,9 @@ Committed by `npx genex publish`, so it ships with your game.
 ```ts
 import * as THREE from "three";
 
-// The extension varies by provider (production emits .png) — use the EXACT
-// path the CLI printed when generation finished, don't assume .jpg.
-const map = await new THREE.TextureLoader().loadAsync(
-  "./assets/textures/lush-green-grass/basecolor.png",
-);
+// the URL `npx genex texture` printed (R2 sends CORS headers, so cross-origin works):
+const TEXTURE_URL = "https://assets.genex.technology/generations/<id>/texture-basecolor";
+const map = await new THREE.TextureLoader().loadAsync(TEXTURE_URL);
 map.colorSpace = THREE.SRGBColorSpace;
 map.wrapS = map.wrapT = THREE.RepeatWrapping;
 map.repeat.set(8, 8);          // tile count — raise for large surfaces
@@ -69,8 +69,8 @@ scene.add(ground);
 
 ## Publish checklist
 
-- Relative path `./assets/textures/...`; `base: "./"` in `vite.config.ts`; files live under
-  `public/assets/` so Vite ships them; `npx genex publish` ships them to R2.
+- Load it from the **URL** the command printed — absolute and permanent, so it resolves
+  the same in local dev, the published game, and remixes. Nothing to commit.
 
 ## Options
 

package/templates/skills/genex-explore/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: genex-explore
+description: Search the curated Genex community gallery with `npx genex explore` before hand-writing hard visual or physics systems. Use when the game needs terrain, grass, water, vehicles, buildings, dungeons, flocking/boids, or advanced shader work — proven open-source Three.js implementations you can clone as a starting point or borrow parts from, credits included.
+---
+
+# Genex Explore — proven building blocks from the community gallery
+
+Some systems are notoriously hard to get right from scratch: believable grass,
+vehicle physics, procedural buildings and dungeons, fish/boid flocking, water,
+advanced shader effects. The curated community gallery holds **faithful ports of
+proven open-source Three.js projects** — playable, cloneable, and licensed for
+reuse. Search it before hand-writing one of those systems.
+
+## When to use
+
+Before building a hard visual/physics system by hand, run:
+
+```bash
+npx genex explore "<what you need>"
+```
+
+Examples: `npx genex explore "grass"`, `npx genex explore "vehicle physics"`,
+`npx genex explore "procedural building"`. No sign-in needed — this works even
+before `genex init`.
+
+Each result prints everything you need to act on it:
+
+- `play:` — open it in the browser to judge whether it fits.
+- `clone:` — the public repo with **editable source on `main`**.
+- `upstream:` — the original source repo, with its author and license.
+
+Add `--json` for machine-readable output.
+
+## How to integrate a result
+
+**As a NEW game (start from the whole project):**
+
+1. `git clone <clone URL from the output> <name>` — pick a short one-word name.
+2. `cd <name>`, then `npx @genex-ai/cli-demo@latest init <name>` — choose
+   "Ignore files and continue" if it warns the folder isn't empty; never use
+   `--force`. This creates your own project; the original is untouched.
+3. `npm install`, keep `base: './'` in `vite.config`, then build your changes
+   and ship with `npx genex preview`.
+
+**To BORROW parts into the current project:**
+
+1. Clone the result somewhere temporary, separate from your project
+   (e.g. `/tmp/genex-explore-src`).
+2. Study how it implements the part you need, then bring **just that** over —
+   real code and assets, adapted to your file paths. Don't wholesale-overwrite
+   your game.
+3. Reused assets must live under `public/assets/` to ship. New assets are
+   generated as usual with `$genex-ai-model`, `$genex-ai-skybox`,
+   `$genex-ai-sfx`, or `$genex-ai-texture`.
+
+## Credits rule (non-negotiable)
+
+Every curated result carries an upstream link, author, and license — that
+credit is part of the deal that makes these projects reusable. Whatever you
+build from one:
+
+- keep the attribution block in the README (upstream source repo URL, author,
+  license) exactly as the port carries it;
+- keep any in-game credits screens or notices in place;
+- carry the credit into anything you publish or remix from it.
+
+If nothing matches your query, try a broader term (terrain, grass, vehicle,
+water, building, dungeon, fish, shader) — or build it with the regular
+`genex-threejs-*` skills instead.

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

@@ -28,9 +28,9 @@ validation.
 
 ## Generating real assets
 
-Beyond procedural code, Genex can generate **real, AI-made assets** from a prompt
-and drop them into `public/assets/` (shipped with your published game; load them
-as `./assets/...` — the `public/` prefix is stripped when served):
+Beyond procedural code, Genex can generate **real, AI-made assets** from a prompt.
+Each command prints a permanent `assets.genex.technology` URL you load directly —
+the asset lives in Genex storage (R2), not your repo, so there's nothing to commit:
 
 ```bash
 npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)

package/templates/skills/genex-threejs-camera-direction/SKILL.md

@@ -33,6 +33,18 @@ Read [references/camera-rigs.md](references/camera-rigs.md)
 for exact chase/side/orbit rigs, projection values, transition
 rules, floating-origin shot, pointer controls, and implementation limits.
 
+## Aiming and pointer lock
+
+Camera-aimed action — a third-person shooter reticle, first-person look —
+wants **pointer lock**, not drag-orbit: request it on canvas click
+(`canvas.requestPointerLock()`), drive yaw/pitch from `mousemove` deltas while
+locked, and treat lock loss (Esc) as aim-paused — show a small "click to aim"
+hint whenever unlocked. Keep drag-orbit for non-combat cameras (exploration,
+building, spectating). Pointer lock works everywhere a Genex game runs:
+standalone the game is the top-level page, and the platform's game frame
+already grants the pointer-lock permission — no setup needed. Re-sync
+yaw/pitch from the camera whenever lock is acquired (rule below).
+
 ## Non-negotiable rules
 
 - Use subject dimensions to derive offsets; do not tune one fixed distance for

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -260,6 +260,24 @@ instead. Don't code around any of this: no `?`/`#` URL params of yours will
 be affected, and `isEmbedded()` / the return-trip handling are internal SDK
 concerns.
 
+### Validating a draft (read before self-testing)
+
+An unpublished draft shows the sign-in gate to any browser that isn't signed
+in as the owner — **including your own test browser** (Playwright, headless
+Chrome). The game still boots behind the overlay: console logs, DOM snapshots,
+and key events all work — but every screenshot shows the gate, not the game,
+and a gate capture is NOT visual evidence.
+
+- Validate what the gate can't hide: a clean console, the canvas booting, the
+  HUD present in a DOM snapshot, controls registering.
+- Do NOT work around the gate: don't dig through the SDK's internals for
+  undocumented URL fragments, and don't drive the user's own signed-in
+  browser.
+- For the visual pass on a draft, hand it off plainly: "open your draft page
+  and tell me what you see" — the owner's view is the real check. Once the
+  game is **published**, any fresh browser gets in as a guest, so your own
+  test browser works again for full visual validation.
+
 ## Checklist
 
 - [ ] `initGameSentry({ slug: GENEX.slug })` is the very first call in `main.ts`.

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

@@ -33,6 +33,10 @@ no matter how good it looks.
   itself, or apply them only to hand-rolled movement.)
 - If an action can't fire (cooldown, no ammo), say so instantly — a click, a
   dimmed icon — silence reads as broken input.
+- Camera-aimed shooting wants **pointer lock** (click to aim, Esc releases —
+  `$genex-threejs-camera-direction` has the rig rules); firing at a reticle
+  with an unlocked drag-to-turn camera feels imprecise no matter how tight
+  the numbers are.
 
 ## Movement: snappy beats realistic
 

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

@@ -32,7 +32,15 @@ this is the whole acceptance gate, and it is also the minimum for every game:
 2. Press each documented control once (keys, pointer); assert a **visible
    response** to every one — the player moves, the camera turns, the button
    fires.
-3. Capture one screenshot of live gameplay.
+3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
+   gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
+   NOT gameplay evidence; if a draft's gate blocks the view, say so plainly
+   (see the embed-auth skill's "Validating a draft" note) instead of passing
+   the capture off as validation.
+4. In that screenshot, check oriented models: the hero faces its travel
+   direction, and NPCs driven by chase/aim code face their target. A model
+   rotated 90° reads as broken — `$genex-ai-model` has the one-time facing
+   fix.
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.