@genex-ai/cli-demo 1.4.2 → 1.5.0-dev.389

package/README.md

@@ -11,6 +11,7 @@ genex preview              # build + push to the hosted draft URL (unlisted)
 genex publish              # build + push, then list the game in the gallery
 genex make-remixable          # make this game remixable — migrate a private source to a public repo
 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 image "<prompt>"     # generate an image    → prints an asset URL
@@ -87,7 +88,7 @@ baked at build time via `GENEX_CLI_CHANNEL` (see `src/config.ts`).
 
 ## Generating assets
 
-`genex model | sfx | texture | image | video "<prompt>"` turn a prompt into a
+`genex model | skybox | sfx | texture | image | video "<prompt>"` turn a prompt into a
 real, 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:
@@ -95,6 +96,7 @@ downloaded or committed:
 | Command | Provider | Prints (role) |
 | --- | --- | --- |
 | `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` |
 | `genex image "<prompt>" [--transparent] [--aspect <ratio>]` | fal.ai | `…/generations/<id>/image-main` |

package/dist/index.js

@@ -8,7 +8,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-var RAW_CHANNEL = "latest";
+var RAW_CHANNEL = "dev";
 var CLI_CHANNEL = RAW_CHANNEL === "dev" ? "dev" : "latest";
 var STANDS = {
   prod: { api: "https://api.genex.games", dashboard: "https://genex.games" },
@@ -991,7 +991,7 @@ var CONTRACT_END = "<!-- genex:contract:end -->";
 var GENEX_CONTRACT_BLOCK = `${CONTRACT_BEGIN}
 # Genex build contract (always in effect for this game)
 
-Your agentic capabilities that can boost your creation (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`sfx\` \xB7 \`music\` \xB7 \`voice\` \xB7 \`texture\` \xB7 \`image\` (\`--edit\` \xB7 \`--inpaint\` \xB7 \`--glass\` \xB7 \`--clean\` \xB7 \`--upscale\`) \xB7 \`video\` \xB7 rigged \`character\` / \`creature\` \xB7 \`character animate <id> "<verb>"\` (also \`creature animate\`; \`--locomotion\` for the 8-way movement set, \`--video\` for your own footage) \xB7 the pixel toolbox \`ui extract|masks|plate|text-color|trim|audit\` \xB7 vendored \`controller character|car|drone|touch|quality|chat\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\` \xB7 \`rename <name>\` (move the game to a new address \u2014 keeps its plays and likes, kills the old link, needs \`--yes\` once published, and the game must be rebuilt after). Full options: \`npx genex --help\`. There is NO sky generator: every sky, horizon, time of day and weather mood is built in code \u2014 your call how, from a background colour and fog to an atmospheric sky shader with a real sun. It costs nothing, weighs nothing on phones, and keeps the sun in sync with the scene's own lighting, which a painted panorama never can. Task\u2192lane routing lives in the \`genex-game-director\` skill's routing map \u2014 re-load it whenever you're unsure which lane owns a task.
+Your agentic capabilities that can boost your creation (all via \`npx genex \u2026\`): generate \`model\` \xB7 \`skybox\` \xB7 \`sfx\` \xB7 \`music\` \xB7 \`voice\` \xB7 \`texture\` \xB7 \`image\` (\`--edit\` \xB7 \`--inpaint\` \xB7 \`--glass\` \xB7 \`--clean\` \xB7 \`--upscale\`) \xB7 \`video\` \xB7 rigged \`character\` / \`creature\` \xB7 \`character animate <id> "<verb>"\` (also \`creature animate\`; \`--locomotion\` for the 8-way movement set, \`--video\` for your own footage) \xB7 the pixel toolbox \`ui extract|masks|plate|text-color|trim|audit\` \xB7 vendored \`controller character|car|drone|touch|quality|chat\` \xB7 \`animations search\` \xB7 \`wait <id>\` / \`wait --all\` \xB7 \`preview\` / \`publish\` \xB7 \`rename <name>\` (move the game to a new address \u2014 keeps its plays and likes, kills the old link, needs \`--yes\` once published, and the game must be rebuilt after). Full options: \`npx genex --help\`. Task\u2192lane routing lives in the \`genex-game-director\` skill's routing map \u2014 re-load it whenever you're unsure which lane owns a task.
 
 Important note: put soul into your creations, with many details and love. Aim to make them realistic and feel real. Use genex capabilities as an extension, but never limit your imagination \u2014 you are a powerful agent. Use your built-in sub-agents and iteration loops (\`/loop\` or your platform's equivalent) where you need them to reach outstanding results. Verify yourself. Anything you put in front of the player should already feel alive and impressive \u2014 never a bare scene waiting for "later". Build what's still missing before polishing what already works.
 
@@ -1013,6 +1013,7 @@ Important note: put soul into your creations, with many details and love. Aim to
 16. Never add debug-only code to the game to check your own work \u2014 no hidden test modes, no special URL parameters, no forced-visible flags, no auth mocks, no pixel-sampling hooks. \`?genex_local_test=1\` is the platform's own supported mode and is fine; your own bypass is not. (The multiplayer skill's small build identifier, token-free status line, and connected-quorum watchdog are production supportability, not a bypass \u2014 keep those.)
 17. Input directions match their labels: A/\u2190 moves or turns the player screen-LEFT, D/\u2192 screen-RIGHT, mouse-up looks up, and drag-pan axes share ONE convention. The cursor is either the gameplay tool (RTS, card, builder) or locked away during play \u2014 keyboard-only games included. Check it in every milestone's smoke pass.
 18. NEVER delete, empty, move, rename, or overwrite anything you did not create yourself. This folder may hold the player's own reference images, notes, sketches, or an earlier attempt \u2014 files that exist nowhere else and have no undo, no trash, no backup. A non-empty folder is normal and is NEVER something to clean up, and "start clean" is never a reason. That rules out \`rm\`/\`rm -rf\`, \`git clean\`, \`git checkout -- .\`, \`git reset --hard\` over their work, deleting to resolve a conflict or a stuck interactive prompt, and every setup tool's offer to empty a directory (\`--force\`, \`--overwrite\`, "Remove existing files") \u2014 scaffold into a fresh subfolder and copy in instead. You may add files and edit the ones you wrote. If a step genuinely cannot continue without removing something of theirs, STOP and ask, naming the exact files, and wait for a yes \u2014 "it looks like junk" is never that yes. This binds hardest during setup, where it runs fast and automatically before the player has asked for anything at all.
+19. If the game sells anything, it sells it for coin at a fixed, visible price, and NEVER sells chance. Run this test on any purchasable thing before building it: does the player pay (with coin, or with anything coin bought, directly or indirectly), is the outcome uncertain when they pay, and is there a prize they wanted \u2014 all three yes means it is paid randomness, and you build the deterministic version instead. That rules out loot boxes, gacha, mystery boxes, crates, card packs, prize wheels and raffles; wagering, staking, betting, coinflips and casino or slot mechanics denominated in coin; and donation prompts, tip jars or any player-to-player coin transfer, because coin buys goods and never just moves. Randomness the player EARNS by playing is gameplay, not commerce \u2014 an enemy dropping a random item, a chest found in the level, a procedural layout, a crit roll \u2014 and is completely fine. Every coin price renders its real-money equivalent beside it (the server sends one with every item), item prices sit on the platform's price grid so no player is left holding change they cannot spend, and nothing in a shop carries a countdown, "limited time", or a stock counter. When a request crosses one of these lines, name the mechanic, give the one-sentence reason, propose a specific compliant alternative, and build that \u2014 never the banned version "as an option", never a partial one, and never after asking the player to confirm they want it. Load \`$genex-monetization\` before building a shop.
 ${CONTRACT_END}
 `;
 var CLAUDE_IMPORT_LINE = "@AGENTS.md";
@@ -1118,11 +1119,6 @@ var REMOVED_SKILLS = [
   "genex-explore",
   "genex-threejs-procedural-materials",
   // folded into genex-threejs-procedural-assets (AG-881)
-  // 2026-08-12: the generated-panorama lane is paused at the provider, and
-  // every sky is built in code now. Leaving this SKILL.md
-  // installed would keep pointing agents at `npx genex skybox`, which the CLI
-  // refuses.
-  "genex-ai-skybox",
   "genex-threejs-skill-router",
   "genex-threejs-bloom",
   "genex-threejs-screen-space-ambient-occlusion",
@@ -4895,6 +4891,307 @@ async function runMakeRemixable(opts) {
   }
 }
 
+// src/commands/domain.ts
+var SUBCOMMANDS = ["add", "list", "verify", "remove"];
+function statusWord(d) {
+  if (d.status === "active") return c.green("live");
+  if (d.status === "failed") return c.red("stopped");
+  return c.dim("waiting for DNS");
+}
+async function runDomain(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const sub = (opts.name ?? "list").trim();
+  if (!SUBCOMMANDS.includes(sub)) {
+    log.error(`Unknown subcommand \`${sub}\`. Use: ${SUBCOMMANDS.join(", ")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const needsHost = sub !== "list";
+  const hostname = opts.hostname?.trim();
+  if (needsHost && !hostname) {
+    log.error(`\`genex domain ${sub}\` needs a hostname, e.g. ${c.cyan(`genex domain ${sub} play.yourdomain.com`)}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const meta = await readProject();
+  if (!meta?.id) {
+    log.error("This folder isn't linked to a game.");
+    log.dim(`  Run ${c.cyan("genex link")} (or ${c.cyan("genex list")} to find the slug) first.`);
+    process.exitCode = 1;
+    return;
+  }
+  const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
+  let token = opts.token ?? await readUserToken(opts.envPath);
+  if (!token) {
+    if (opts.noAuth) {
+      log.error("Not signed in. Re-run without --no-auth to connect.");
+      process.exitCode = 1;
+      return;
+    }
+    log.plain("Not signed in \u2014 connecting\u2026");
+    try {
+      token = await authorize(apiUrl, getAuthUrl(opts.authUrl), {
+        log,
+        inlineWaitMs: opts.timeoutSec ? opts.timeoutSec * 1e3 : void 0
+      });
+    } catch (err) {
+      if (err instanceof AuthPendingError) {
+        printAuthHandoff(log, err);
+        log.dim(`Then re-run ${c.cyan(`genex domain ${sub}`)}.`);
+        return;
+      }
+      log.error(`Sign-in didn't complete: ${err instanceof Error ? err.message : String(err)}`);
+      process.exitCode = 1;
+      return;
+    }
+    await writeUserToken(token, opts.envPath);
+  }
+  const base = `${apiUrl}/api/projects/${encodeURIComponent(meta.id)}/domains`;
+  const auth = { Authorization: `Bearer ${token}` };
+  const call = (url, init2) => apiFetch(url, { ...init2, headers: { ...auth, "Content-Type": "application/json", ...init2?.headers ?? {} } });
+  let res;
+  try {
+    if (sub === "list") res = await call(base);
+    else if (sub === "add") res = await call(base, { method: "POST", body: JSON.stringify({ hostname }) });
+    else if (sub === "verify")
+      res = await call(`${base}/${encodeURIComponent(hostname)}/verify`, { method: "POST" });
+    else res = await call(`${base}/${encodeURIComponent(hostname)}`, { method: "DELETE" });
+  } catch (err) {
+    log.error(`Couldn't reach the API at ${apiUrl}.`);
+    log.dim(`  ${String(err)}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (!res.ok) {
+    if (await printedStructuredError(res)) {
+      process.exitCode = 1;
+      return;
+    }
+    const body = await res.json().catch(() => null);
+    if (res.status === 503) {
+      log.error("Custom domains aren't available on this Genex environment yet.");
+    } else if (res.status === 404) {
+      log.error(sub === "list" || sub === "add" ? "That game wasn't found on this account." : `${hostname} isn't connected to this game.`);
+    } else {
+      log.error(body?.message ?? body?.error ?? `Request failed (${res.status}).`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+  const data = await res.json();
+  if (opts.json) {
+    log.plain(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (sub === "list") {
+    const rows = data.domains ?? [];
+    if (rows.length === 0) {
+      log.plain("No domains connected to this game.");
+      log.dim(`  ${c.cyan("genex domain add play.yourdomain.com")} to connect one.`);
+      return;
+    }
+    for (const d of rows) log.plain(`  ${d.hostname.padEnd(34)} ${statusWord(d)}`);
+    return;
+  }
+  if (sub === "add") {
+    if (data.supported === false) {
+      log.plain(String(data.message ?? "That domain's DNS host doesn't support one-click setup."));
+      const manual = data.manual;
+      const records = Array.isArray(manual?.records) ? manual.records : [];
+      if (records.length > 0) {
+        log.plain("");
+        log.plain("  Add these two records at your DNS host:");
+        log.plain("");
+        for (const r of records) {
+          log.plain(`    ${c.cyan(String(r.type ?? ""))}  ${String(r.name ?? "")}`);
+          log.plain(`          ${String(r.value ?? "")}`);
+        }
+        log.plain("");
+        if (manual?.apexHint) {
+          log.dim("  At a root domain your host may call the first one ALIAS or ANAME.");
+        }
+        log.dim(`  Then run: genex domain verify ${String(data.hostname ?? "")}`);
+        log.dim("  DNS can take a few minutes to spread.");
+        return;
+      }
+      log.dim("  Your game stays reachable at its usual address.");
+      return;
+    }
+    const applyUrl = String(data.applyUrl ?? "");
+    const providerName = String(data.providerName ?? "your DNS host");
+    log.success(`${data.hostname} can be connected through ${providerName}.`);
+    log.plain("");
+    log.plain(`  Approve the DNS change here: ${c.cyan(applyUrl)}`);
+    log.plain("");
+    log.dim("  One click writes the records. Nothing to copy or paste.");
+    if (!applyUrl.startsWith("https://")) {
+      log.warn("That DNS host returned a setup link we could not verify \u2014 not opening it.");
+    } else if (!opts.noOpen) {
+      openBrowser(applyUrl, () => log.dim("  (Couldn't open a browser \u2014 use the link above.)"));
+    }
+    log.dim(`  Then ${c.cyan(`genex domain verify ${String(data.hostname)}`)} once you have approved it.`);
+    return;
+  }
+  if (sub === "verify") {
+    const status = String(data.status ?? "");
+    if (status === "active") log.success(`${hostname} is live.`);
+    else if (status === "failed") log.error(`${hostname} is stopped \u2014 its verification record is missing.`);
+    else log.plain(`${hostname} isn't verified yet \u2014 DNS changes can take a few minutes to spread.`);
+    return;
+  }
+  log.success(`${hostname} disconnected.`);
+}
+
+// src/commands/shop.ts
+var SUBS = ["list", "add", "set", "remove"];
+function money(cents) {
+  return cents === void 0 ? "" : ` ($${(cents / 100).toFixed(2)})`;
+}
+async function runShop(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  const sub = opts.name?.trim() || "list";
+  if (!SUBS.includes(sub)) {
+    log.error(`Unknown subcommand ${c.cyan(sub)}. Use: ${SUBS.join(", ")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const meta = await readProject();
+  if (!meta?.id) {
+    log.error("This folder isn't linked to a game.");
+    log.dim(`  Run ${c.cyan("genex link")} (or ${c.cyan("genex list")} to find the slug) first.`);
+    process.exitCode = 1;
+    return;
+  }
+  const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
+  let token = opts.token ?? await readUserToken(opts.envPath);
+  if (!token) {
+    if (opts.noAuth) {
+      log.error("Not signed in. Re-run without --no-auth to connect.");
+      process.exitCode = 1;
+      return;
+    }
+    log.plain("Not signed in \u2014 connecting\u2026");
+    try {
+      token = await authorize(apiUrl, getAuthUrl(opts.authUrl), {
+        log,
+        inlineWaitMs: opts.timeoutSec ? opts.timeoutSec * 1e3 : void 0
+      });
+    } catch (err) {
+      if (err instanceof AuthPendingError) {
+        printAuthHandoff(log, err);
+        log.dim(`Then re-run ${c.cyan(`genex shop ${sub}`)}.`);
+        return;
+      }
+      log.error(`Sign-in didn't complete: ${err instanceof Error ? err.message : String(err)}`);
+      process.exitCode = 1;
+      return;
+    }
+    await writeUserToken(token, opts.envPath);
+  }
+  const auth = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+  const call = (url, init2) => apiFetch(url, { ...init2, headers: { ...auth, ...init2?.headers ?? {} } });
+  const projectSkus = `${apiUrl}/api/coin/projects/${encodeURIComponent(meta.id)}/skus`;
+  async function fail3(res2, what) {
+    if (printedStructuredError(res2)) {
+      process.exitCode = 1;
+      return;
+    }
+    process.exitCode = 1;
+    const body = await res2.json().catch(() => ({}));
+    if (res2.status === 404 && body.error === "not_found") {
+      log.error("In-game purchases aren't enabled on this environment yet.");
+      return;
+    }
+    log.error(body.message ?? `Couldn't ${what} (HTTP ${res2.status}).`);
+    if (body.error === "price_off_grid") {
+      log.dim(`  See the full list any time: ${c.cyan("genex shop list")}`);
+    }
+  }
+  if (sub === "list") {
+    const res2 = await call(projectSkus);
+    if (!res2.ok) return fail3(res2, "read your shop");
+    const body = await res2.json();
+    if (opts.json) {
+      log.plain(JSON.stringify(body, null, 2));
+      return;
+    }
+    if (body.items.length === 0) {
+      log.plain("This game sells nothing yet.");
+      log.dim(`  Add something: ${c.cyan('genex shop add "Iron Key" --price 100')}`);
+      log.dim(`  Prices available: ${body.priceGrid.join(", ")} coin`);
+      return;
+    }
+    log.plain(`${body.items.length} item${body.items.length === 1 ? "" : "s"}:`);
+    for (const s of body.items) {
+      const state = s.active ? "" : c.dim(" (retired)");
+      log.plain(
+        `  ${c.cyan(s.id)}  ${s.name} \u2014 ${s.priceCoins} coin${money(s.priceDisplayUsdCents)}  ${c.dim(s.type)}${state}`
+      );
+    }
+    log.dim(`Prices available: ${body.priceGrid.join(", ")} coin`);
+    return;
+  }
+  if (sub === "add") {
+    const name = opts.hostname?.trim();
+    if (!name) {
+      log.error(`\`genex shop add\` needs a name, e.g. ${c.cyan('genex shop add "Iron Key" --price 100')}.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!opts.price) {
+      log.error(`\`genex shop add\` needs ${c.cyan("--price")}, in coin.`);
+      process.exitCode = 1;
+      return;
+    }
+    const res2 = await call(projectSkus, {
+      method: "POST",
+      body: JSON.stringify({
+        name,
+        priceCoins: opts.price,
+        type: opts.type === "durable" ? "durable" : "consumable",
+        ...opts.icon ? { iconUrl: opts.icon } : {}
+      })
+    });
+    if (!res2.ok) return fail3(res2, "add that item");
+    const sku = await res2.json();
+    if (opts.json) {
+      log.plain(JSON.stringify(sku, null, 2));
+      return;
+    }
+    log.success(`Added ${c.cyan(sku.name)} \u2014 ${sku.priceCoins} coin.`);
+    log.plain(`  id: ${c.cyan(sku.id)}`);
+    log.dim(`  Use it in the game: buy({ skuId: "${sku.id}" })`);
+    return;
+  }
+  const skuId = opts.hostname?.trim();
+  if (!skuId) {
+    log.error(`\`genex shop ${sub}\` needs an item id \u2014 see ${c.cyan("genex shop list")}.`);
+    process.exitCode = 1;
+    return;
+  }
+  const skuUrl = `${apiUrl}/api/coin/skus/${encodeURIComponent(skuId)}`;
+  if (sub === "set") {
+    const patch = {};
+    if (opts.rename) patch.name = opts.rename;
+    if (opts.price) patch.priceCoins = opts.price;
+    if (opts.icon) patch.iconUrl = opts.icon;
+    if (Object.keys(patch).length === 0) {
+      log.error(`Nothing to change. Pass ${c.cyan("--rename")}, ${c.cyan("--price")} or ${c.cyan("--icon")}.`);
+      process.exitCode = 1;
+      return;
+    }
+    const res2 = await call(skuUrl, { method: "PATCH", body: JSON.stringify(patch) });
+    if (!res2.ok) return fail3(res2, "update that item");
+    const sku = await res2.json();
+    log.success(`Updated ${c.cyan(sku.name)} \u2014 ${sku.priceCoins} coin.`);
+    return;
+  }
+  const res = await call(skuUrl, { method: "DELETE" });
+  if (!res.ok) return fail3(res, "remove that item");
+  log.success("Removed from the shop.");
+  log.dim("  Players who already bought it keep it.");
+}
+
 // src/lib/promote.ts
 async function promoteBuild(apiUrl, projectId, token, log) {
   let res;
@@ -6383,10 +6680,7 @@ function printHint(kind, view, files, log) {
   const url = files[0]?.url ?? "";
   const hint = {
     model: `Standard GLB \u2014 load with GLTFLoader straight from the URL \u2014 see the genex-ai-model skill. url = "${url}"`,
-    // Unreachable while the lane is paused (see src/index.ts) — kept so a
-    // restore is one deletion. Games that already ship a panorama still load
-    // it this way.
-    skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment. 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}"`,
     music: `Load with AudioLoader into a non-positional THREE.Audio: setLoop(true), setVolume(0.30), start on the first user gesture \u2014 and the settings screen MUST have Music + SFX volume sliders \u2014 see genex-ai-music. url = "${url}"`,
     voice: `Load with AudioLoader into a THREE.Audio (or PositionalAudio at the speaker); voice lines are content \u2014 keep them short, SUBTITLED, and skippable \u2014 see genex-ai-voice. url = "${url}"`,
@@ -19108,7 +19402,17 @@ ${c.bold("Usage")}
   genex publish [options]            Build + push + make live, then list it in the gallery.
   genex make-remixable [options]     Make THIS game remixable by everyone \u2014 migrates a
                                      private source onto a public managed genex repo.
+  genex domain <sub> [host]          Play this game on a domain you own:
+                                     add | list | verify | remove. "add" opens a
+                                     one-click approval at your DNS host \u2014 no
+                                     records to copy or paste.
+  genex shop <sub> [name|id]         What this game sells: list | add | set | remove.
+                                     "add" prints the item id your game passes to
+                                     buy({ skuId }) \u2014 the platform owns the catalog,
+                                     so this is the only way one exists. Prices come
+                                     off a fixed grid, printed on any refusal.
   genex model "<prompt>" [options]   Generate a 3D model (GLB); prints a public asset URL.
+  genex skybox "<prompt>" [options]  Generate a skybox (equirect); prints a public asset URL.
   genex sfx "<prompt>" [options]     Generate a sound effect (mp3); prints a public asset URL.
   genex music "<prompt>" [options]   Generate an instrumental music track (mp3); prints a
                                      public asset URL. --duration 10-300s (default 90).
@@ -19183,8 +19487,12 @@ ${c.bold("Usage")}
                                      Pure local work (no API); the PNG tools read
                                      a file or URL, audit scans the project.
 
-${c.bold("Options for the generators (`model` `sfx` `music` `voice` `texture` `image` `video`)")}
+${c.bold("Options for the generators (`model` `skybox` `sfx` `music` `voice` `texture` `image` `video`)")}
   --terrain            (texture) seamless tiling surface for terrain/ground.
+  --raw                (skybox) send the prompt exactly as written \u2014 skip the
+                       appended environment-only clause AND the refusal on
+                       prompts that name structures/objects (a sky is sky only;
+                       landforms and weather always pass).
   --duration <sec>     (sfx, video, music) target clip length in seconds;
                        (character/creature animate) 3-6 s of reference video for
                        verbs that route to AI video (default 3) \u2014 longer gives a
@@ -19348,8 +19656,15 @@ ${c.bold("Examples")}
   genex publish
   genex publish --categories games,vfx
   genex make-remixable
+  genex domain add play.mygame.com
+  genex domain list
+  genex shop list
+  genex shop add "Iron Key" --price 100 --type durable
+  genex shop set sku_123 --price 200
+  genex shop remove sku_123
   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 music "brooding orchestral battle loop, seamless loop, no intro or outro" --no-wait
   genex voice "You shall not pass!" --voice gruff
@@ -19399,6 +19714,10 @@ function parseArgs(argv) {
     "--name",
     "--repo",
     "--remixed-from",
+    "--price",
+    "--icon",
+    "--rename",
+    "--type",
     "--title",
     "--description",
     "--categories",
@@ -19470,6 +19789,9 @@ function parseArgs(argv) {
       case "--no-auth":
         parsed.options.noAuth = true;
         break;
+      case "--no-open":
+        parsed.options.noOpen = true;
+        break;
       case "--no-push":
         parsed.options.noPush = true;
         break;
@@ -19604,6 +19926,18 @@ function parseArgs(argv) {
           } else {
             (parsed.options.selectors ??= []).push(arg);
           }
+        } else if (parsed.command === "shop") {
+          if (!parsed.options.hostname) parsed.options.hostname = arg;
+          else {
+            parsed.error = `Unexpected argument: ${arg}`;
+            return parsed;
+          }
+        } else if (parsed.command === "domain") {
+          if (!parsed.options.hostname) parsed.options.hostname = arg;
+          else {
+            parsed.error = `Unexpected argument: ${arg}`;
+            return parsed;
+          }
         } else if (parsed.command === "animations") {
           parsed.options.query = parsed.options.query ? `${parsed.options.query} ${arg}` : arg;
         } else {
@@ -19774,6 +20108,27 @@ function applyValueFlag(options, flag, value) {
       options.duration = n;
       break;
     }
+    case "--price": {
+      const n = Number(value);
+      if (!Number.isInteger(n) || n <= 0) {
+        throw new Error(`Invalid --price value: ${value} (whole coin, e.g. 100)`);
+      }
+      options.price = n;
+      break;
+    }
+    case "--icon":
+      options.icon = value;
+      break;
+    case "--type": {
+      if (value !== "consumable" && value !== "durable") {
+        throw new Error(`Invalid --type value: ${value} (consumable or durable)`);
+      }
+      options.type = value;
+      break;
+    }
+    case "--rename":
+      options.rename = value;
+      break;
     case "--aspect":
       options.aspect = value;
       break;
@@ -19913,21 +20268,6 @@ async function main() {
     ci: !!process.env.CI
   });
   try {
-    if (parsed.command === "skybox") {
-      log.error("The generated-sky lane is paused \u2014 `genex skybox` is not available.");
-      log.plain(
-        [
-          `  ${c.cyan("\u2192")} Build the sky in code instead \u2014 your call how: a background colour with`,
-          `    fog, a gradient dome, or three.js's own ${c.cyan("Sky")} shader with a real sun. It costs`,
-          "    no credits, no download and no phone memory, and the sun stays in sync with",
-          "    your lighting.",
-          `  ${c.cyan("\u2192")} A distant skyline or landmark was never a sky: build it as geometry, or`,
-          `    generate it with ${c.cyan("npx genex model")}.`
-        ].join("\n")
-      );
-      process.exitCode = 1;
-      return;
-    }
     if (GEN_KINDS.has(parsed.command)) {
       await runGenerate(parsed.command, {
         ...parsed.options,
@@ -19954,6 +20294,12 @@ async function main() {
       case "make-remixable":
         await runMakeRemixable(parsed.options);
         break;
+      case "shop":
+        await runShop(parsed.options);
+        break;
+      case "domain":
+        await runDomain(parsed.options);
+        break;
       case "controller":
         await runController({ ...parsed.options, kind: parsed.options.name });
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.4.2",
+  "version": "1.5.0-dev.389",
   "description": "Set up your project's agent workspace (.claude/.codex/.cursor in the game folder), authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,133 @@
+---
+name: genex-ai-skybox
+description: Generate a real 360° skybox (equirectangular panorama) from a text prompt with `npx 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 `npx genex skybox`** for a specific, describable ENVIRONMENT — "golden
+  hour over misty mountains", "rolling thunderstorm, towering cumulonimbus",
+  "alien purple nebula", "hazy dusk sky over a distant sea horizon". You get a
+  real image.
+- Build a procedural, animated, time-of-day sky directly in the game's existing
+  scene/runtime only when that is the requested deliverable; this image lane
+  owns static generated panoramas.
+
+**A skybox is environment only — never content.** Buildings, trees, ruins,
+towers, or any object painted into the sky render at infinite distance: they
+never get closer as the player moves, they sit at the wrong parallax against
+the real 3D world, and they read as broken the moment the camera strafes.
+Structures belong in the scene as geometry (`npx genex model`); the sky
+carries atmosphere — light, weather, clouds, haze, stars.
+
+**Writing "no cathedral" does not rescue a prompt that also says "cathedral".**
+Image models are steered by the nouns they ARE given; a ban loses to any
+positive mention of the same thing in the same prompt. A real pilot asked for
+a *"cinematic dark anime gothic atmosphere, ruined cathedral courtyard mood,
+**no buildings or structures**"* — and got a full gothic cathedral with a
+courtyard balustrade and a baked ground plane. Five negations in that prompt,
+zero effect. So never name a structure in a skybox prompt **even to exclude
+it**: describe only light, colour, cloud, weather and time of day.
+
+The CLI enforces this both ways. It appends a closed-positive environment
+clause to every prompt (you'll see `↳ environment-only guard applied`; the
+full final prompt is stored with the generation), and it **refuses outright,
+before spending any credits**, when the prompt itself names a structure or
+object. Landforms are fine — "golden hour over misty mountains", "a distant
+sea horizon", "towering cumulonimbus" all pass. If you genuinely need content
+baked into the sky — e.g. a space station panorama for a scene with no world
+geometry — pass `--raw` to send your prompt exactly as written.
+
+## Run
+
+```bash
+npx genex skybox "<prompt>"
+```
+
+Blocks until ready, then prints its public URL:
+
+```
+https://assets.genex.technology/generations/<id>/skybox-equirect
+```
+
+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
+
+Load the equirect JPG through the quality tier's rung ladder, mark it
+equirectangular, and use it for both the visible background and the lighting.
+The bare URL is an 8192×4096 original — ~178 MB decoded, over half a phone's
+GPU budget in one texture — so phones must load the downscale rung the platform
+stores next to every skybox (`$genex-threejs-adaptive-quality`):
+
+```ts
+import * as THREE from "three";
+import { detectTier } from "./controllers/quality/tier.ts";
+import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
+
+// 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 tier = detectTier(); // reuse the boot tier if you already have it
+const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
+  new THREE.TextureLoader().loadAsync(u),
+);
+texture.mapping = THREE.EquirectangularReflectionMapping;
+texture.colorSpace = THREE.SRGBColorSpace;
+
+scene.background = texture;   // visible sky
+scene.environment = texture;  // image-based lighting on PBR materials
+```
+
+Desktop gets the original; phones get the `@2048`/`@4096` rung; a missing rung
+falls back to the original automatically — never a broken boot.
+
+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
+// Do NOT dispose `texture` here — it IS the visible background. Dispose it only
+// if you later stop using it as the sky.
+```
+
+## Publish checklist
+
+- 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
+
+- `--raw` — send the prompt exactly as written, skipping the appended
+  environment-only guard (for the rare sky that must carry content).
+- `--no-wait` — enqueue and return immediately with the generation id; pick
+  the result up later with `npx genex wait <id>` (safe to re-run — it attaches
+  to the SAME generation).
+- `--api-url <url>` — override the API base (local dev).
+
+## Troubleshooting
+
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
+- **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
+  this skybox generation. Tell the user the facts the CLI printed: their balance, this
+  generation's cost, and when their credits refill. Then offer to continue the build
+  with a procedurally-coded placeholder (a gradient/procedural sky or a plain
+  `scene.background` color) and mark the spot with
+  `// TODO(genex): regenerate when credits refill` so the real asset is one command
+  away later. Do not stop the session over this.
+- **"Email not verified" (`email_verification_required`)** — generation credits
+  unlock after the account's email is verified. Give the user the verify link the
+  CLI printed, wait for them to confirm, then re-run the command.
+- **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

@@ -225,7 +225,7 @@ first one is the one a screenshot of the whole arena will not show you.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this texture generation. Tell the user the facts the CLI printed: their balance,
   this generation's cost, and when their credits refill. Then offer to continue the

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

@@ -151,7 +151,7 @@ set belongs to `$genex-ai-hud` — both build on `npx genex image`/`video`.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user

package/templates/skills/genex-game-director/SKILL.md

@@ -112,8 +112,8 @@ Genex asset and runtime lanes are:
 
 - `npx genex model "<prompt>"`—a static GLB → `$genex-ai-model`
 - `npx genex texture "<prompt>"`—a generated surface → `$genex-ai-texture`
-- sky, horizon, time of day, weather mood—built in code, never generated; no
-  command and no skill owns it, so pick what this game needs
+- `npx genex skybox "<prompt>"`—a 360° environment-only sky →
+  `$genex-ai-skybox`
 - `npx genex sfx "<prompt>"` / `music` / `voice` →
   `$genex-ai-sfx`, `$genex-ai-music`, `$genex-ai-voice`
 - `npx genex image "<prompt>"` / `video`—2D and motion art →
@@ -146,10 +146,9 @@ Assets row.
 The request sets the floor for the asset plan, never the ceiling: a world
 should feel dressed and alive, so plan the detail its genre implies — and pick
 the more efficient engine per object. Paid generation buys hero pieces (the
-player's character, key props, music); procedural code is the
+player's character, key props, the skybox, music); procedural code is the
 unlimited detail engine for structures, buildings, modular kits, and repeated
-or varied dressing (`$genex-threejs-procedural-assets` owns that lane) — and
-for the sky, which is never generated at all. Mixing
+or varied dressing (`$genex-threejs-procedural-assets` owns that lane). Mixing
 both in one scene is the normal way to build, never a fallback. In focused
 work, stay inside the touched scope. Run independent planned generations with
 `--no-wait`, scaffold while they land, and preserve their IDs, URLs, and

package/templates/skills/genex-game-director/references/routing-map.md

@@ -54,11 +54,12 @@ copy demo architecture.
 | fixed-view screenshots, input direction, facing, temporal and budget evidence | `$genex-threejs-visual-validation` |
 | a static generated GLB for a concrete prop, vehicle, building, or non-rigged object | `$genex-ai-model` |
 | generated surface or terrain texture with real-world UV scale | `$genex-ai-texture` |
-| sky, skybox, horizon, time of day, weather mood, night or space backdrop | build it in code in the scene—there is no sky command and no owning skill, so pick the technique this game needs |
+| environment-only 360° sky | `$genex-ai-skybox` |
 | poster, sign, sprite, decal, reference sheet, or other 2D art | `$genex-ai-image` |
 | in-world motion art or another requested video | `$genex-ai-video` |
 | sound effect, one looping music bed, or a short spoken line | `$genex-ai-sfx`, `$genex-ai-music`, or `$genex-ai-voice` |
 | requested UI/HUD/menu/interface work, a visible UI problem, or an interface you decided this game wants built with generated art | `$genex-threejs-game-ui` |
+| selling anything for platform coin: a shop, an item catalog, boosts, cosmetics, "make it earn"; also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
 | cinematic menu/title/pause/victory/defeat/lobby/credits video treatment | `$genex-ai-menu` |
 | drawn HUD chrome the game's style wants—one element or a matched set of frames, masks, and icons | `$genex-ai-hud` |
 | the game works but feels flat, floaty, or unresponsive: input response, camera, impacts, cooldowns, difficulty, fail/retry | `$genex-threejs-game-feel` |

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

@@ -40,6 +40,7 @@ the asset lives in Genex storage (R2), not your repo, so there's nothing to comm
 
 ```bash
 npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)
+npx genex skybox "golden hour over mountains"  # a 360° sky + lighting
 npx genex sfx "punchy laser zap" --duration 2  # a sound effect (mp3)
 npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 npx genex image "vintage travel poster"        # a picture (poster/sign/sprite/decal)
@@ -50,11 +51,8 @@ npx genex video "waterfall mist drifting" --loop      # a video clip (screen/bac
 `npx genex` resolve to the right CLI.)
 
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
-`$genex-ai-sfx`, `$genex-ai-texture`, `$genex-ai-image`,
-`$genex-ai-video`. The sky is not on that list: there is no sky command, so
-every sky, horizon, and time of day is built in code — your call how, from a
-background colour and fog to an atmospheric sky shader with a real sun. Two
-more workflow skills draw UI art on the same commands,
+`$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`, `$genex-ai-image`,
+`$genex-ai-video`. Two more workflow skills draw UI art on the same commands,
 for games whose style wants it: `$genex-ai-menu` (a cinematic menu — looping
 video backdrop + DOM buttons) and `$genex-ai-hud` (a HUD sprite set with
 masked fills). A restrained interface in clean CSS is a finished UI too —
@@ -161,7 +159,7 @@ and re-link the clone to the same live game:
 ```bash
 git clone <the game's repo url> my-game && cd my-game
 npm install
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 ```
 
 Don't know the slug? **`npx genex list`** prints every game on your account —
@@ -188,7 +186,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

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

@@ -0,0 +1,251 @@
+---
+name: genex-monetization
+description: Build an in-game shop that sells for platform coin — item catalog, purchase flow, delivery, and the per-game soft-currency economy a purchase attaches to. Use when the player asks to sell things, add a shop, monetize, or make the game earn. Carries the hard rules: no paid randomness, no gambling in coin, no donation mechanics, and a real-money price beside every coin price.
+---
+
+# Genex Monetization
+
+Games on Genex can sell things for **coin**, the platform currency. The player
+buys coin with real money once; spending it inside a game is a ledger movement
+the game never touches. You design what is for sale; the platform owns the
+wallet, the confirmation, and the money.
+
+Load this when the game should sell something. Ask first if it should — a game
+with no loop worth monetizing is better without a shop (see §1).
+
+## The hard rules, and the test that generalizes them
+
+Before you build ANY purchasable thing, run this test:
+
+> **Does the player pay?** (with coin, or with anything bought with coin —
+> directly or indirectly, including a per-game token or key that coin bought.)
+> **Is the outcome uncertain when they pay?**
+> **Is there a prize** — an item, currency, or advantage they wanted?
+>
+> **All three yes = paid randomness. Build the deterministic version instead.**
+
+That triad is the test used by every app store to identify gambling, and it
+catches mechanics that do not exist yet — which a list of banned names cannot.
+
+Four things are never built, whatever the request:
+
+1. **No paid randomness.** No loot boxes, gacha, mystery boxes, crates, packs,
+   prize wheels, raffles, "spin for a bonus", "chance to double your coins".
+   Directly or indirectly.
+2. **No gambling in coin.** No wagering, staking, betting, coinflips, casino or
+   slot mechanics denominated in coin or in anything coin buys.
+3. **No donation or begging mechanics.** No "donate to me" prompts, tip jars, or
+   player-to-player coin transfers. Coin buys goods; it never just moves.
+4. **No pressure.** No countdown timers, "ends in", "limited time", "only N
+   left", or stock counters anywhere in the shop.
+
+**Randomness the player EARNS by playing is gameplay, not commerce, and is
+completely fine**: an enemy dropping a random item, a chest you found in the
+level, a procedural layout, a critical-hit roll, a shuffled deck. The line is
+what triggered the roll — play, or payment. Build those freely.
+
+Genex refuses paid randomness outright rather than allowing it with disclosed
+odds. That is stricter than any app store, and it is why no Genex game needs an
+odds table, an age gate, or a per-country check.
+
+### When a request crosses a line
+
+Answer in exactly three parts, then build:
+
+1. **Name it.** "A loot crate is paid randomness — the player pays before
+   knowing what they get."
+2. **Why.** One sentence. "Genex doesn't sell chance; it's a purchase the player
+   can't price, and it's what regulators fine studios over."
+3. **Offer the alternative,** concretely enough to start on, and build that.
+
+Never build the banned version "as an option", never build a partial one, and
+never ask the user to confirm they want it. If they insist, restate the rule
+once and build the compliant version. There is no escalation path.
+
+**What to build instead:**
+
+| They asked for | Build |
+| --- | --- |
+| Loot box, crate, mystery box, card pack | A direct-purchase shop: every item listed at a fixed price, contents visible. For the collecting feel, add a **visible catalog with a completion track** — any purchase advances a meter to a stated milestone reward. |
+| Gacha, banner, pull, summon | A **deterministic unlock**: the character costs a fixed price, or unlocks at a stated number of runs. Coin may buy a stated, visible number of those points. |
+| Prize wheel, spin-to-win, slot machine | A **free spin earned by finishing a run** (never bought), or a **"pick one of three"** screen where all three are visible and the player chooses. Keeps the moment, drops the wager. |
+| Casino game, blackjack, poker, roulette | The same game with **chips that are granted free each session, reset on restart, cannot be bought and cannot become coin**. It becomes a card game. Sell cosmetics — table felt, card backs — for coin. |
+| Coinflip, double-or-nothing, wager my coins | A **skill-based risk/reward inside the run**: a harder route with a bigger payout, staking the run's own score, which was never purchasable. |
+| Betting on matches, PvP wagers | **Leaderboards with a fixed cosmetic reward for placement**, paid by the game. Nobody's balance goes down. |
+| Donate button, tip jar, "pls donate" | A **gift that is a purchase**: they buy a specific item at a stated price and give it. Or a **supporter cosmetic** — a badge or aura at a normal price, where what's delivered is visible. |
+| Pay to remove a wait / energy gate | **Delete the gate** and sell a permanent upgrade or a cosmetic. Pace with difficulty, not with a timer. |
+| Limited-time offer, flash sale | A **permanent tiered ladder** — the value comes from volume, not from a clock. |
+| Pay-to-win stat boost in a competitive game | **Cosmetics**, or a boost that only applies in single-player content. |
+
+## Designing a shop worth buying from
+
+Nine checks. Each one is answerable about your actual design.
+
+1. **The shop attaches to a progression that already exists.** Name the screen
+   it opens from and the meter a purchase moves. Build the loop first; a shop in
+   a game with nothing to want is furniture.
+2. **A boost shortens a grind the player has already felt.** State it in one
+   sentence: "this skips the ore-gathering they've done four times." If you
+   can't, it isn't a boost, it's a number.
+3. **Nothing sold invalidates the core loop.** If a paying and a non-paying
+   player both reach the end, the payer must not have skipped the part that IS
+   the game.
+4. **No manufactured friction.** If the annoyance wouldn't exist without the
+   shop, remove the annoyance instead of selling the cure.
+5. **Everything sold is reachable free.** Spending is a shortcut or a
+   decoration, never the only path.
+6. **Prices land on the grid.** Item prices use 50 / 100 / 200 / 500 / 1000 coin
+   so every coin pack divides evenly into them and nobody is left holding change
+   they cannot spend.
+7. **Every price shows real money next to it.** The server sends
+   `priceDisplayUsdCents` with every item — render it. `250 coins ($2.49)`.
+8. **One currency layer between money and goods.** Coin buys items. A per-game
+   earned currency buys per-game upgrades. They never convert into each other.
+9. **Purchases never expire and survive a reinstall.** Entitlements live on the
+   server; the game re-reads them on every boot.
+
+For a per-game earned currency, the load-bearing number is **minutes of play per
+unit earned**. Set it, then price the cheapest meaningful item at one to three
+sessions of earning. Everything else follows. Spend sinks come in three kinds —
+permanent upgrades, refills, cosmetics — and cosmetics are what absorbs late-game
+currency without touching balance.
+
+## Stocking the shop
+
+Items live on the platform, not in the game's code. You create them with the CLI,
+and the game names them by id — which is what stops a game inventing its own
+items or repricing them.
+
+```bash
+npx genex shop add "Iron Key" --price 100 --type durable
+#   → id: sku_a1b2c3   ← what the game passes to buy()
+
+npx genex shop list                    # what this game sells, and the valid prices
+npx genex shop set sku_a1b2c3 --price 200
+npx genex shop remove sku_a1b2c3       # retires it; players who bought it keep it
+```
+
+`--type consumable` (default) is spent on use; `durable` is owned permanently.
+
+**Prices come off a fixed grid** — `genex shop list` prints it, and an off-grid
+price is refused. The grid exists so every coin pack divides evenly by the
+cheapest item, which is what stops a player being left holding change too small
+to spend. Pick the nearest grid price rather than working around it.
+
+Record the ids in `DESIGN.md` next to what each item does. They are the one
+thing the game's code cannot regenerate for itself.
+
+## The API
+
+From `@genex-ai/embed-sdk`, already installed. `initEmbed()` must have run.
+
+```ts
+import { getShop, buy, getEntitlements, consumeEntitlement } from '@genex-ai/embed-sdk';
+
+const items = await getShop();
+// [{ id, type, name, iconUrl, priceCoins, priceDisplayUsdCents }]
+```
+
+Render `name`, `iconUrl`, `priceCoins` **and** `priceDisplayUsdCents`. Never
+hardcode a price: the server charges what its own catalog says, so a hardcoded
+number can silently disagree with what the player is charged.
+
+### Buying
+
+```ts
+buyButton.addEventListener('click', async () => {   // must be a real click
+  const result = await buy({ skuId: item.id });
+  if (result.status === 'canceled') return;         // normal — say nothing
+  if (result.status !== 'succeeded') {
+    showMessage(result.message ?? 'That did not go through.');
+    return;
+  }
+  await deliverPending();
+});
+```
+
+**Call `buy()` synchronously from the click handler.** On the game's own origin
+the confirmation is a popup, and browsers only allow one while a user gesture is
+live — an `await` before it loses the gesture and nothing opens.
+
+`buy()` resolves when the SERVER says what happened, not when a window closes.
+Statuses: `succeeded`, `canceled`, `expired`, `insufficient_balance`, `failed`.
+
+The player confirms on a Genex-drawn surface — your game does not render the
+price sheet, cannot skin it, and cannot complete a purchase itself. That is
+deliberate: it is what lets a player trust a purchase in a game they have never
+played before.
+
+### Delivering
+
+```ts
+async function deliverPending() {
+  for (const e of await getEntitlements({ excludeConsumed: true })) {
+    const { alreadyConsumed } = await consumeEntitlement(e.id);
+    if (alreadyConsumed) continue;                  // someone got there first
+    applyItem(e.skuId);                             // AFTER the consume
+    await savePlayerState(currentSave());
+  }
+}
+```
+
+**Consume first, apply second, and run `deliverPending()` on every boot.**
+
+That order is not stylistic. If the game dies between consuming and applying,
+the player loses one item — a support ticket. If you apply first and die before
+consuming, every boot re-delivers it forever — an exploit. Re-listing on boot is
+what makes a purchase survive a crash, a refresh, or a closed tab.
+
+`consumable` items are used up. `durable` items are owned permanently — consume
+them once, then record ownership in the player's save.
+
+## Checklist
+
+- [ ] Items exist (`npx genex shop list`) before the shop UI is written
+- [ ] The game has a loop and a progression before it has a shop
+- [ ] Every item price is on the 50/100/200/500/1000 grid
+- [ ] Every price renders `priceDisplayUsdCents` beside the coin figure
+- [ ] `buy()` is called synchronously inside a click/tap handler
+- [ ] `canceled` is silent; only real failures show a message
+- [ ] `deliverPending()` runs on every boot, before the player can act
+- [ ] `consumeEntitlement()` is awaited BEFORE the effect is applied
+- [ ] `alreadyConsumed: true` skips the effect
+- [ ] Durable purchases are written to the player's save
+- [ ] No timer, "limited", "ends in", or stock counter anywhere
+- [ ] Nothing sold is unreachable without paying
+- [ ] No paid randomness, no coin wagering, no donation prompt
+
+## Troubleshooting
+
+**`buy()` returns `failed` with "the confirmation window was blocked"** — `buy()`
+was not called inside a user gesture, or an `await` ran before it. Move it to the
+first line of the click handler.
+
+**The purchase succeeded but the player got nothing** — the game applied the
+effect without consuming, or never ran `deliverPending()` on boot. The
+entitlement is still there; re-list it.
+
+**The player got the item twice** — the effect was applied before consuming, or
+`alreadyConsumed` was ignored. Both are the same bug.
+
+**`unauthorized` from `getShop()`** — no player identity yet. `initEmbed()` must
+have run and `waitForPlayer()` resolved. See `$genex-threejs-embed-auth`.
+
+**`guest_no_wallet`** — guests play but hold no wallet. Show the shop as
+sign-in-to-buy rather than hiding it.
+
+**`staging_no_purchase`** — a `genex preview` build cannot spend real coin. Test
+the shop's layout on staging; test a purchase after `genex promote`.
+
+**`getShop()` returns nothing** — the game has no items yet. `npx genex shop add
+"<name>" --price <coin>` and use the id it prints.
+
+**`price_off_grid`** — that price isn't on the platform's grid. `npx genex shop
+list` prints the valid ones; pick the nearest.
+
+**Everything coin-related 404s** — in-game purchases aren't enabled on this
+environment. Nothing to fix in the game; say so and build the rest.
+
+**Purchases do nothing in local testing** — local test mode has no wallet and no
+server. `buy()` returns `failed` immediately by design. Test purchases on a
+preview or published build.

package/templates/skills/genex-threejs-adaptive-quality/SKILL.md

@@ -7,7 +7,7 @@ description: Make a Genex Three.js game phone-survivable with the vendored adapt
 
 Phones enforce a hard GPU-memory ceiling desktops don't have: iOS silently
 kills the page when a game allocates too much, and the kill arrives at BOOT —
-exactly when textures, models, and the post stack all decode at once. This
+exactly when a skybox, models, and the post stack all decode at once. This
 skill wires the vendored quality kit so the game boots conservatively on
 phones, steps quality UP when the device proves smooth, and never gets uglier
 on desktop. **You can recover from ugly; you cannot recover from a killed
@@ -115,27 +115,22 @@ reads; pause your own loop and audio on `visibilitychange` too.
 
 ## Generated assets: load through the rungs
 
-A generated texture original can be several thousand pixels square — a handful
-of them decode into more memory than a phone has. Every generated image asset
-ships with downscale rungs; phones must load through them:
+Generated skyboxes are 8192×4096 — about 178 MB decoded, over half a phone's
+whole budget in one texture. Every generated image asset ships with downscale
+rungs; phones must load through them:
 
 ```ts
 import { detectTier } from "./controllers/quality/tier.ts";
 import { loadTextureWithFallback } from "./controllers/quality/pick-asset.ts";
 
-const texture = await loadTextureWithFallback(TEXTURE_URL, tier, (u) =>
+const texture = await loadTextureWithFallback(SKYBOX_URL, tier, (u) =>
   new THREE.TextureLoader().loadAsync(u),
 );
 ```
 
-Desktop loads the original, phones the small rung, and a missing rung falls
-back to the original — never a broken boot. The `$genex-ai-texture` skill
-shows the wiring in place.
-
-The sky costs nothing here: it is built in code, so there
-is no panorama to download, no rung ladder, and no boot-time decode. Games
-carrying a generated equirect sky predate that and still load through the
-`skybox-equirect` rungs the kit resolves for them.
+Desktop loads the original, phones the `@2048` rung (~11 MB), and a missing
+rung falls back to the original — never a broken boot. The `$genex-ai-skybox`
+and `$genex-ai-texture` skills show the wiring in place.
 
 ## Generated models: load through the rungs
 
@@ -175,7 +170,7 @@ source, fetched only as the fallback of last resort. Meshy characters take
 the same ladder through
 `loadMeshyCharacter(manifestUrl, { loader: gltfLoader.loader, modelUrlCandidates: (u) => [pickModel(u, tier, { ktx2: gltfLoader.ktx2 }), pickModel(u, tier), u] })`.
 KTX2-capable games can also pass `ktx2Load` to `loadTextureWithFallback` so
-textures use their `.ktx2` variants.
+skyboxes/textures use their `.ktx2` variants.
 
 ## Quality picker in settings
 
@@ -224,10 +219,9 @@ runtime).
   (antialias) are locked wrong for the session. Tier first, renderer second.
 - Governor wired to context-creation flags → no-op at best. Runtime knobs
   only: DPR, post toggles, distances, frame cap.
-- A generated texture loaded with a bare `TextureLoader.loadAsync(url)` on a
-  game that targets phones → the full-size original decoded; route it through
-  `loadTextureWithFallback`. (Same for the equirect sky of a game that predates
-  the procedural sky lane — the `skybox-equirect` rungs still resolve.)
+- Skybox loaded with a bare `TextureLoader.loadAsync(SKYBOX_URL)` on a game
+  that targets phones → ~178 MB decoded; route it through
+  `loadTextureWithFallback`.
 - Quality stepping on every spike → shader compiles read as slowness. The
   governor requires SUSTAINED slow windows; do not shorten them.
 - Testing quality tiers by resizing the desktop window → tiers key off touch +

package/templates/skills/genex-threejs-adaptive-quality/references/adaptive-quality.md

@@ -7,7 +7,7 @@ when, or teaching the governor a game-specific step.
 
 The phone budget is a hard ceiling that includes GPU memory (textures,
 framebuffers), and the OS kill arrives with no catchable event. Boot is the
-danger window: big textures + models + post targets decode together. So phone tiers
+danger window: skybox + models + post targets decode together. So phone tiers
 START one notch below what the heuristics suggest and the governor steps UP
 after ~20 smooth seconds. The cost of guessing low is moments of softness; the
 cost of guessing high is a dead page.

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

@@ -67,7 +67,7 @@ type.
 
 **3. Never stall the build on art.** Scaffold, boot wiring, the core loop,
 and the gameplay-logic modules keep moving in parallel whatever the UI is
-doing — and the core asset set (hero model, ground texture, sky, sfx) is
+doing — and the core asset set (hero model, ground texture, skybox, sfx) is
 prompted from the game IDEA, so it can launch up front behind placeholders.
 Nothing ready to build waits on an art answer: decide, say the decision in
 one line, keep going.

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

@@ -134,9 +134,13 @@ everything twice.
    visible; the lock may only ever engage from the Play/Resume click or a
    gameplay canvas click (the phase binding `setPaused(phase !== "playing")` is
    what guarantees this — check it rides `setPhase`, not the render loop).
-   Headless caveat: `requestPointerLock` throws in headless Chromium —
-   assert the wiring and the unlocked cue in a screenshot, and say plainly that
-   the lock itself needs one manual click (do the both-axes look check there).
+   Headless caveat, measured on Chromium 151: `requestPointerLock` does NOT
+   throw — it locks, with or without a user gesture, so the lock and the
+   unlocked cue ARE yours to assert headless. What does not survive is the
+   both-axes look check: synthesised mouse movement cancels to a net zero
+   delta, so turning right then left proves nothing about direction. Assert the
+   wiring and the cue in a screenshot, and say plainly that confirming which way
+   the view turns needs one manual pass with a real mouse.
 7. **Ask the scene the three things the screenshot cannot answer** (below). Run it
    once, in the same browser you already have open.
 

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

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```