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

package/dist/index.js

@@ -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";
@@ -5041,6 +5042,156 @@ async function runDomain(opts) {
   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;
@@ -19255,6 +19406,11 @@ ${c.bold("Usage")}
                                      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.
@@ -19502,6 +19658,10 @@ ${c.bold("Examples")}
   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"
@@ -19554,6 +19714,10 @@ function parseArgs(argv) {
     "--name",
     "--repo",
     "--remixed-from",
+    "--price",
+    "--icon",
+    "--rename",
+    "--type",
     "--title",
     "--description",
     "--categories",
@@ -19762,6 +19926,12 @@ 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 {
@@ -19938,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;
@@ -20103,6 +20294,9 @@ 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.4.2-dev.382",
+  "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-game-director/references/routing-map.md

@@ -59,6 +59,7 @@ copy demo architecture.
 | 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-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.