@genex-ai/cli-demo 1.36.15 → 1.36.16-dev.1039

package/templates/skills/genex-llm-in-games/references/pricing.md

@@ -1,16 +1,28 @@
 # Calibrate, then declare
 
-`estimateCoins` is the **fixed price of a started attempt**, not a guess about
-one. The platform charges exactly what you declare, whether the call succeeds,
-fails, is canceled, or stops at its own budget. There is one honest way to pick
-it: run the real prompt on your own coins, read what it charged, and declare the
-number the benchmark recommends.
-
-Never derive it from a model vendor's published rates. Three layers sit between
-that rate and what the player is charged — the provider's cost, the platform's
-tariff, and the headroom a declared price needs — and only the benchmark sees
-all three. A number worked out from the vendor's page silently drops the middle
-layer and under-prices every call you will ever make.
+An in-game call is paid from the player's Genex credits and **billed as used**:
+its real provider cost plus the platform fee. The game declares no price. It
+declares a per-call **ceiling** — `maxCredits` on `generate()`,
+`perCallMaxCredits` on a standing budget — and no call is ever billed past it.
+
+The ceiling is still a number with two jobs, and both punish a guess:
+
+- **It bounds the cost.** A budget's worst case, shown to the player beside
+  your own estimate, is built from `perCallMaxCredits`. A ceiling far above what
+  a call really costs asks the player to approve money the game will never
+  spend, and makes the sheet look like a withdrawal.
+- **It sizes the answer.** Each call's room to answer is funded from its
+  ceiling, so a ceiling below what the answer needs cuts it off — and a cut-off
+  attempt is still billed for the work it did.
+
+There is one honest way to pick it: run the real prompt on your own credits,
+read what it really cost, and declare the numbers the benchmark prints.
+
+Never derive them from a model vendor's published rates. Three layers sit
+between that rate and what the player is billed — the provider's cost for YOUR
+prompt, the platform fee, and the headroom a ceiling needs — and only the
+benchmark sees the first. The other two come from the server; a number worked
+out from the vendor's page drops at least one of them.
 
 ## 1. Freeze the prompt first
 
@@ -22,7 +34,7 @@ that the real game then cannot fund.
 If the feature returns structured data, write the schema to a file now
 (`./answer.schema.json`) and benchmark with it. Schema'd JSON and free text do
 not cost the same, and shipping without a schema is the commonest way a call is
-charged for an unusable result.
+billed for an unusable result.
 
 ## 2. Run the benchmark
 
@@ -33,89 +45,105 @@ npx genex llm bench "<the frozen prompt, one real example filled in>" \
   --model <id from the line above> \
   --schema ./answer.schema.json \
   --samples 3 \
-  --max-coins <n> --user-approved
+  --max-credits <n> --user-approved
 ```
 
-- It spends **your** coins, on the development lane, through the CLI's own
-  credential. Nothing here runs in a shipped build.
-- `--max-coins <n> --user-approved` is a hard gate, refused before any network
+- It spends **your** credits, on the development lane, through the CLI's own
+  credential. Nothing here runs in a shipped build. The build's asset allowance
+  does not count it, which is why it has its own gate.
+- `--max-credits <n> --user-approved` is a hard gate, refused before any network
   call. That is the same shape as every other spend approval in the CLI: you
-  state the ceiling for this run, out loud, once.
+  state the ceiling for this run, out loud, once. Your spendable balance has to
+  cover one attempt at it, or the run is refused before it starts.
+  `--max-coins` is the old name of the same flag and still works.
 - `--samples 3` is the floor. The same prompt costs different amounts on
   different runs, because the model's own output length varies.
 - `npx genex llm price` re-prints the last run's recommendation without spending
-  anything again.
+  anything again. A file from before credits is reprinted as history, with a
+  request to re-run.
 
 ## 3. Read the output
 
-Each sample prints what it actually charged. The aggregate prints p50, p95 and
-max of the charged coins **over the samples that succeeded and settled**, plus
-one recommendation. A sample that failed is printed with its code and stays
-out of the numbers; a sample the provider refused at its door
-(`provider_http_<status>`) ran no inference, cost nothing, and prints the
-provider's own message under its row — on a 401 or 403 that is the stand's
-provider configuration refusing the model, which is the operator's to fix. A
-sample refused as `generation_limit` never started and ends the run: the
-account's three ad-hoc calls are open or recently stopped with a pending
-bill. `npx genex llm status` lists them with what each holds;
-`npx genex llm cancel <id>` stops an active one; a stopped one frees on its
-own once its bill resolves, and stops holding a slot ten minutes after
-dispatch. Re-running the bench into the same refusal spends nothing and
+Each sample prints its real cost and the whole credits it was charged. The
+aggregate prints p50, p95 and max of both **over the samples that succeeded and
+settled**. A sample that failed is printed with its code and stays out of the
+numbers; a sample the provider refused at its door (`provider_http_<status>`)
+ran no inference, cost nothing, and prints the provider's own message under its
+row — on a 401 or 403 that is the stand's provider configuration refusing the
+model, which is the operator's to fix. A sample refused as `generation_limit`
+never started and ends the run: the account's three ad-hoc calls are open or
+recently stopped with a pending bill. `npx genex llm status` lists them with
+what each holds; `npx genex llm cancel <id>` stops an active one; a stopped one
+frees on its own once its bill resolves, and stops holding a slot ten minutes
+after dispatch. Re-running the bench into the same refusal spends nothing and
 learns nothing.
 
 A sample the model had to stop writing (`provider_token_limit`) was cut off at
-your `--max-coins`: it was charged, it is not a sample, and its real length is
-unknown — so the run recommends no price and asks you to re-run with a higher
-`--max-coins`. When the stand itself cannot hold the answer, the run says the
-answer is longer than one call there may produce; no price fixes that, a
+your `--max-credits`: it was billed, it is not a sample, and its real length is
+unknown — so the run recommends no ceiling and asks you to re-run with a higher
+`--max-credits`. When the stand itself cannot hold the answer, the run says the
+answer is longer than one call there may produce; no ceiling fixes that, a
 shorter answer does.
 
 - **p50** is what a typical call costs. It is the number to reason about when
-  you ask "can the game afford this loop?" — multiply it by the calls per
-  minute you are about to disclose.
+  you ask "can the game afford this loop?".
 - **p95** is what a bad-but-normal call costs: a long answer, a model that
-  reasons its way around. It is the number to **declare**, because a declared
-  price below it means the unlucky calls cannot fund themselves and get refused
-  mid-session.
+  reasons its way around. It is what the **ceiling** has to cover, because a
+  ceiling below it cuts the unlucky calls off.
 - **max** is diagnostic. When max sits far above p95, the prompt has an
   unbounded branch in it — usually an unconstrained list or a missing schema.
   Fix the prompt rather than declaring a bigger number.
 
-The recommendation line already applies the **server's own recommended
-headroom** on top of p95. It also covers the answer's **length**: the declared
-price decides how long each call's answer may be, because the room to answer is
-funded from it, so a price built from charged coins alone can cut the answer
-off in the game while the bench — run under a larger `--max-coins` — never saw
-it. The recommendation is never below the smallest price that leaves room for
-the benchmarked answer, and when the length is what set it the run says so in
-one sentence. Either way, declare that figure verbatim — never the bare charged
-number:
+Then the run prints what to declare:
+
+- **`Declare maxCredits`** — the p95 real cost with the platform fee and the
+  **server's own recommended headroom** applied, in whole credits. It also
+  covers the answer's **length**: it is never below the smallest ceiling that
+  leaves room for the benchmarked answer, and when the length is what set it
+  the run says so in one sentence. A ceiling built from cost alone can cut the
+  answer off in the game while the bench — run under a larger `--max-credits`
+  — never saw it.
+- **`Grant perCallMaxCredits`** — the same over the worst sample, never below
+  the line above it. It is emphatically NOT the benchmark's `max` of charged
+  credits: that number carries neither the headroom nor the answer's length,
+  so a ceiling set from it lands under the call ceiling and the budget's calls
+  are refused (`grant_price_unreasonable`).
+- **`Per-call estimate: about … credits per call`** — the measured average,
+  fee included, no headroom: a fraction of a credit for a short call. It is the
+  honest figure for the disclosure.
+- **`Grant perCallEstimateCredits`** — that average rounded up to a whole
+  credit.
+
+Declare each verbatim:
 
 ```ts
-const NPC_CALL_PRICE = <the recommended figure>;    // from `npx genex llm bench`, <date>
-const NPC_CALL_CEILING = <the printed ceiling>;     // same run — grants only
+const NPC_CALL_MAX = <Declare maxCredits>;                 // from `npx genex llm bench`, <date>
+const NPC_GRANT_MAX = <Grant perCallMaxCredits>;           // same run — budgets only
+const NPC_CALL_ESTIMATE = <Grant perCallEstimateCredits>;  // same run — budgets only
+const NPC_CALL_AVERAGE = <the "about … credits per call" figure>;  // same run
 ```
 
-Write the benchmark date and the model id beside it in `DESIGN.md`, so the next
-person knows what the number describes. Do not add a margin of your own on top
-of the recommendation, and do not round it down to look cheaper.
+Write the benchmark date and the model id beside them in `DESIGN.md`, so the
+next person knows what the numbers describe. Do not add a margin of your own on
+top, and do not round them down to look cheaper.
 
-For a grant, the run prints a **second** number beside the price: the ceiling,
-`perCallMaxCoins`. Declare that one verbatim too, and do not work it out by
-hand. It is emphatically NOT the benchmark's `max`: p95 is nearest-rank, so at
-the sample counts a benchmark actually takes, p95 and max are the same figure —
-a ceiling set from `max` therefore lands *below* the recommended price, and
-`requestSpendGrant()` refuses that pair before the request ever leaves the page.
-
-The invariant, which the SDK and the server both enforce:
+The invariants, which the SDK and the server both enforce:
 
 ```
-perCallEstimateCoins  ≤  perCallMaxCoins  ≤  the limit the player approves
+perCallEstimateCredits  ≤  perCallMaxCredits  ≤  the limit the player approves
+maxCredits on each call  ≤  perCallMaxCredits
 ```
 
-The ceiling is the price's room to be wrong, not a second price: no call is ever
-charged more than the price it declares, and the platform separately refuses any
-declared price out of proportion to what the model could really cost.
+A ceiling is not a second price: a call is billed the real cost of the work it
+did plus the fee (a one-time call rounded up to a whole credit), and never past
+its ceiling.
+
+**One-time calls round up; budgets do not.** A one-time `generate()` is captured
+rounded UP to a whole credit when it settles, so a call that really costs a
+fraction of a credit still costs the player one whole credit each time. Under a
+budget each call adds its exact fraction and the player's credits move one
+whole credit at a time. That is one more reason a repeated call belongs under a
+budget.
 
 ## 4. Turn the game's loop into the disclosure
 
@@ -129,27 +157,39 @@ from the loop you wrote, counted honestly:
 3. **Multiply, and pick the period that makes the number legible.** Five NPCs at
    one call per thirty seconds is ten calls a minute, so `periodLabel: 'minute'`
    and `estimatedCallsPerPeriod: 10`.
-4. **Coins per period is calls × the declared price** —
-   `estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE`. Not the p50, not a hope: the
-   price you declare is the price charged.
+4. **Credits per period is calls × the measured average, rounded up** —
+   `estimatedCreditsPerPeriod: Math.ceil(10 * NPC_CALL_AVERAGE)`. Not the
+   ceiling: a call is billed what it uses, so the honest estimate is what calls
+   really average.
 
 ```ts
+perCallMaxCredits: NPC_GRANT_MAX,
+perCallEstimateCredits: NPC_CALL_ESTIMATE,
 disclosure: {
   periodLabel: 'minute',
   estimatedCallsPerPeriod: 10,
-  estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE,
+  estimatedCreditsPerPeriod: Math.ceil(10 * NPC_CALL_AVERAGE),
 }
 ```
 
 The player sees this attributed to your game — "the game estimates about …" —
-beside the platform's own worst case computed from `perCallMaxCoins`. The two
+beside the platform's own worst case computed from `perCallMaxCredits`. The two
 being far apart is normal; the estimate being far below what the game really
 does is what breaks trust and burns the grant mid-session.
 
-**Batching changes this arithmetic more than any price tuning can.** Five NPCs
+**Batching changes this arithmetic more than any tuning can.** Five NPCs
 answered by one call that returns five decisions is two calls a minute, not ten,
-and one benchmarked price for the batched prompt replaces five of the unbatched
-one. Do that before you reach for a cheaper model.
+and one benchmark of the batched prompt replaces five of the unbatched one. Do
+that before you reach for a cheaper model.
+
+## Old code
+
+`estimateCoins`, `perCallMaxCoins`, `perCallEstimateCoins` and
+`disclosure.estimatedCoinsPerPeriod` are the names from before credits. The
+server still accepts them and reads them as the same numbers in credits, but
+they are deprecated: rename them to `maxCredits`, `perCallMaxCredits`,
+`perCallEstimateCredits` and `estimatedCreditsPerPeriod` when you touch the
+code, and re-benchmark — a number measured as a Nex price is not a ceiling.
 
 ## Worked example
 
@@ -160,20 +200,21 @@ speech). The prompt carries the NPC's memory and the last two player lines.
 1. Freeze the prompt with a full memory and a long player line. Write
    `./answer.schema.json` with the two fields.
 2. `npx genex llm bench "<that prompt>" --schema ./answer.schema.json
-   --samples 3 --max-coins <ceiling> --user-approved`.
-3. Read: p50 `<p50>`, p95 `<p95>`, max `<max>`, and the two printed
-   declarations — `Declare estimateCoins: <recommended>` and
-   `Grant perCallMaxCoins: <ceiling>`.
-4. Declare `NPC_CALL_PRICE = <recommended>` and
-   `NPC_CALL_CEILING = <ceiling>`, each verbatim from the line that printed it.
-5. Unbatched, the loop is ten calls a minute, so the disclosure is
-   `10` and `10 * <recommended>` coins per minute.
+   --samples 3 --max-credits <ceiling> --user-approved`.
+3. Read: p50 `<p50>`, p95 `<p95>`, max `<max>`, and the printed lines —
+   `Declare maxCredits: <call ceiling>`, `Grant perCallMaxCredits: <grant ceiling>`,
+   `Per-call estimate: about <average> credits per call` and
+   `Grant perCallEstimateCredits: <estimate>`.
+4. Declare `NPC_CALL_MAX`, `NPC_GRANT_MAX`, `NPC_CALL_ESTIMATE` and
+   `NPC_CALL_AVERAGE`, each verbatim from the line that printed it.
+5. Unbatched, the loop is ten calls a minute, so the disclosure is `10` calls
+   and `Math.ceil(10 * NPC_CALL_AVERAGE)` credits per minute.
 6. Batch the five NPCs into one call — benchmark the batched prompt separately,
    because it is a different prompt — and the disclosure becomes two calls a
-   minute at the batched price.
+   minute at the batched average.
 7. Re-run steps 1–4 whenever the prompt, the schema or the model changes. A
-   prompt edit is a price change; treat it like one.
+   prompt edit changes the ceiling; treat it like one.
 
 Every `<placeholder>` above is read off your own benchmark run. None of these
 figures is a platform constant, and none of them should be copied from another
-game — a different prompt has a different price.
+game — a different prompt has a different cost.

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

@@ -1,24 +1,48 @@
 ---
 name: genex-monetization
-description: Add dynamic coin payments for game goods or actions — platform consent, recoverable receipts, and idempotent delivery without a required product catalog. 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.
+description: Sell things in a Genex game for Nex, the currency players buy with real money — fixed-price Genex store items (`genex shop add`) by default, dynamic payment requests only for amounts decided while playing. 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, no donation mechanics, and a real-money price beside every Nex 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.
+Genex's own currency is **Nex**: players buy it with real money and spend it in
+the Genex store. 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. Nex is a name: "1,200 Nex", never "Nexes".
 
 Load this when the user asks to sell something or add payments. Build the game
-loop before adding commerce; no shop screen or product catalog is required.
+loop before adding commerce.
+
+## Which currency the person means
+
+- **A price in Nex means a Genex store item.** Build the thing into the game,
+  then list it with `npx genex shop add … --json` without asking, before or
+  after the first publish (a folder with no linked game keeps a local draft).
+  Price it from the store's grid: `npx genex shop list` prints it, and a price
+  off the grid is refused with `price_off_grid`. The person puts it on sale.
+  `$genex-items` owns the steps.
+- **A price in coins, gold, gems or any other name is a currency of the game's
+  own**, earned by playing (see the per-game currency note below). If the
+  person also says it is for real money, ask once whether they mean Nex.
+- **Selling something for real money with no currency named** ("paid
+  characters", "sell skins") means Nex store items.
+
+## Store items first, payment requests for amounts decided in play
+
+Anything with a fixed Nex price is a **store item** (`$genex-items`): a sword,
+a skin, a character, a level pack, a boost. The store draws its card, its
+purchase sheet and its receipt; the game delivers it from `getEntitlements()`.
+
+A **dynamic payment request** (`requestPayment()`, below) is only for an amount
+decided while playing: a player-approved action whose price the run sets, or a
+top-up of a size the player picks. Never wrap a fixed-price item in one.
 
 ## 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.)
+> **Does the player pay?** (with Nex, or with anything bought with Nex —
+> directly or indirectly, including a per-game token or key that Nex bought.)
 > **Is the outcome uncertain when they pay?**
 > **Is there a prize** — an item, currency, or advantage they wanted?
 >
@@ -30,12 +54,12 @@ 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".
+   prize wheels, raffles, "spin for a bonus", "chance to double your Nex".
    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.
+2. **No gambling in Nex.** No wagering, staking, betting, coinflips, casino or
+   slot mechanics denominated in Nex or in anything Nex 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.
+   player-to-player Nex transfers. Nex 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.
 
@@ -67,10 +91,10 @@ once and build the compliant version. There is no escalation path.
 | 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. |
+| Gacha, banner, pull, summon | A **deterministic unlock**: the character costs a fixed price, or unlocks at a stated number of runs. Nex 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. |
+| 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 Nex**. It becomes a card game. Sell cosmetics — table felt, card backs — for Nex. |
+| Coinflip, double-or-nothing, wager my Nex | 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. |
@@ -94,36 +118,71 @@ Nine checks. Each one is answerable about your actual design.
    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. **A payment has one clear price and promised result.** `amountCoins` is a
-   positive whole number from 1 to 100000, further bounded by the platform
-   surface. Dynamic payments do not use the legacy catalog price grid.
+6. **A purchase has one clear price and promised result.** A store item's
+   price is on the server's grid (`genex shop list`), or Free. A dynamic
+   payment's `amountCoins` is a positive whole number of Nex from 1 to 100000,
+   further bounded by the platform surface, and needs no grid.
 7. **Every price shows real money next to it.** The platform confirmation
    shows the server-frozen `priceDisplayUsdCents`. If rendering a receipt or
-   catalog price in the game, render that value too; never invent an exchange
+   store price in the game, render that value too; never invent an exchange
    rate. A button can simply say “Unlock” and let Genex show the price.
-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.
+8. **One currency layer between money and goods.** Nex buys items. A per-game
+   earned currency (coins, gold, gems) buys per-game upgrades. They never
+   convert into each other.
 9. **Paid ownership survives a reinstall.** Receipts live on the server; the
    game recovers them on every boot and restores the promised state. A
    confirmation can expire; a paid receipt does not expire with it.
 
-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
+For a per-game earned currency (coins, gold, gems: earned by playing, never
+bought), 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.
 
-## Dynamic payment requests
+## Store items (the default)
 
-Requires `@genex-ai/embed-sdk` **>= 0.33.0**. Earlier versions, including
-`^0.32.0`, do not export these payment helpers. Update the game's dependency
-before wiring them, then rebuild and publish the game:
+Every fixed-price item is a Genex store item. `$genex-items` owns making one —
+its picture, its description, the draft the person puts on sale, items other
+games can use, and adding another creator's item. Its rules add to these; they
+never replace them.
 
 ```bash
-npm install @genex-ai/embed-sdk@latest
+npx genex shop list   # the price grid in Nex, and this game's items
+npx genex shop add "Iron Key" --price 100 --type durable --json
+npx genex shop test <sku-id>  # owner-only free entitlement; no Nex moves
 ```
 
-After `initEmbed()` and player identity are ready:
+List the item once it works in the game, without asking. When the Genex
+store is on, `genex shop add` makes a draft: `getShop()` leaves it out of the
+live game and `buy()` cannot sell it until the person puts it on sale. `--json`
+makes the Genex app show its **Put on sale** card; never put it on sale
+yourself. Before the game is published, items can be made all the same: they
+wait as local drafts and go up as drafts with `genex publish`; still, only the
+person puts one on sale. With the store off, the item is on sale at once:
+tell the person so.
+
+`getShop()` reads store items even for guests and preview builds;
+`buy({ skuId })` requests their platform confirmation. Prices follow the grid
+printed by `genex shop list`. Render `name`, `iconUrl`, `priceCoins` (the price
+in Nex) and `priceDisplayUsdCents`; use an image of the actual item for its
+icon. `genex shop set` edits a listing and `genex shop remove` retires it
+without removing a buyer's ownership.
+
+Re-list `getEntitlements({ excludeConsumed: true })` on boot. Branch on
+`skuType` (`consumable`/`durable`), never `type` (purchase/gift/test/free).
+For a consumable, await `consumeEntitlement(id)` BEFORE applying its effect
+and skip `alreadyConsumed: true`. This prevents repeated delivery but a crash
+between consume and save can lose that effect; do not promise atomic game-state
+delivery. A durable ownership unlock is never consumed: restore it from the
+entitlement on every boot. Dynamic receipts do not use this consumption API.
+
+## Dynamic payment requests (amounts decided in play)
+
+Only for an amount the run decides — a player-approved action whose price play
+sets, a top-up of a size the player picks. A fixed price is a store item
+(above). From `@genex-ai/embed-sdk`, after `initEmbed()` and player identity
+are ready:
 
 ```ts
 import { requestPayment, getPayment, getPayments } from '@genex-ai/embed-sdk';
@@ -134,7 +193,7 @@ const order = {
   orderId: 'unlock-iron-gate-run-42',
   title: 'Open the iron gate',
   description: 'Unlock the shortcut for this run.',
-  amountCoins: 75,
+  amountCoins: 75, // Nex, set by this run: the gate's toll grows with depth
 };
 
 buyButton.addEventListener('click', async () => {
@@ -152,15 +211,16 @@ buyButton.addEventListener('click', async () => {
 });
 ```
 
-No `genex shop add`, SKU id, catalog card or item icon is needed. A payment can
-buy a described game action, unlock or item. The hard rules above still apply.
-The game never supplies a recipient: the platform uses the game's own split.
-This API is for coin commerce; in-game LLM requests use their own funding and
-consent flow (`$genex-llm-in-games`), not a payment wrapped around a model call.
+A payment request needs no `genex shop add`, SKU id or item icon: it buys a
+described game action whose amount was decided in play. The hard rules above
+still apply. The game never supplies a recipient: the platform uses the game's
+own split. This API is for Nex commerce; in-game LLM requests use their own
+funding and consent flow (`$genex-llm-in-games`), not a payment wrapped around
+a model call.
 
 The server freezes `title`, `description`, `amountCoins` and the real-money
 value before Genex asks the player. **Creating a request neither debits nor
-reserves coin.** Only the player's explicit confirmation on the platform
+reserves Nex.** Only the player's explicit confirmation on the platform
 surface can move money. The game cannot draw, skin or confirm that sheet.
 
 An `orderId` belongs to this player in this game. The same id with the same
@@ -182,7 +242,7 @@ and `pending`. A timeout or uncertain response is `pending`: it is not proof of
 failure and not permission to apply the action or charge again. `canceled` is
 ordinary player choice; do not show an error for it.
 
-**Your game cannot read the player's coin balance, and no HUD should show one.**
+**Your game cannot read the player's Nex balance, and no HUD should show one.**
 The wallet spans the platform; let Genex show the balance and handle consent.
 Only fulfil a payment whose authoritative receipt says `succeeded`.
 
@@ -194,10 +254,10 @@ The surface depends on the shell (`$genex-threejs-embed-auth`,
   pointer lock before it asks. Treat payment like a pause; re-enter fullscreen
   and pointer lock from the player's next Resume click.
 - **The Genex app has no purchase surface yet.** `requestPayment()` fails
-  without opening a sheet; the legacy `buy()` resolves
+  without opening a sheet, and `buy()` resolves
   `failed` without opening anything too. When `getShell()` from `@genex-ai/embed-sdk` is `"app"`,
   hide payment buttons or make the shop browse-only; do not show a failure toast.
-- Local test mode has no wallet. Preview builds cannot spend real coin either.
+- Local test mode has no wallet. Preview builds cannot spend real Nex either.
   Verify layout and delivery with game-owned test fixtures; a real payment needs
   a published build, a signed-in player and explicit platform consent.
 
@@ -239,53 +299,20 @@ response and a canceled order. Also check concurrent fulfillment if the game
 permits multiple tabs; two read-modify-write saves are not a transaction.
 Do not make a real-money purchase automatically to test the feature.
 
-## Existing catalog items
-
-Catalog APIs remain supported for published games and items that need platform
-entitlements or resale. They are optional, not a prerequisite for dynamic
-payments:
-
-```bash
-npx genex shop add "Iron Key" --price 100 --type durable
-npx genex shop list
-npx genex shop test <sku-id>  # owner-only free entitlement; no coin moves
-```
-
-`getShop()` reads catalog items even for guests and preview builds;
-`buy({ skuId })` requests their platform confirmation. These prices must follow
-the grid printed by `genex shop list`. Render `name`, `iconUrl`, `priceCoins`
-and `priceDisplayUsdCents`; use an image of the actual item for its icon.
-`genex shop set` edits a listing and `genex shop remove` retires it without
-removing a buyer's ownership. When the Genex store is on, `genex shop add`
-makes a draft: `getShop()` leaves it out of the live game and `buy()` cannot
-sell it until the person puts it on sale. Add `--json` so the Genex app shows
-its **Put on sale** card, and never put it on sale yourself. Before the game
-is published, items can be made all the same: they wait as local drafts and go
-up as drafts with `genex publish`; still, only the person puts one on sale.
-
-Items for the Genex store — a picture, a description, a draft the person puts
-on sale, items other games can use, and adding another creator's item — are
-`$genex-items`. Its rules add to these; they never replace them.
-
-Re-list `getEntitlements({ excludeConsumed: true })` on boot. Branch on
-`skuType` (`consumable`/`durable`), never `type` (purchase/gift/test/free).
-For a consumable, await `consumeEntitlement(id)` BEFORE applying its effect
-and skip `alreadyConsumed: true`. This prevents repeated delivery but a crash
-between consume and save can lose that effect; do not promise atomic game-state
-delivery. A durable ownership unlock is never consumed: restore it from the
-entitlement on every boot. Dynamic receipts do not use this consumption API.
-
 ## Checklist
 
 - [ ] The game has a worthwhile loop before commerce
-- [ ] The saved order binds one stable id, exact terms and promised action
-- [ ] `requestPayment()` starts directly from a click/tap
-- [ ] Genex shows the frozen coin and real-money price and receives consent
+- [ ] Every fixed Nex price is a store item: built first, listed with
+      `genex shop add … --json` at a grid price, left for the person to put on sale
+- [ ] A dynamic payment carries only an amount decided in play; its saved order
+      binds one stable id, exact terms and promised action
+- [ ] `buy()` and `requestPayment()` start directly from a click/tap
+- [ ] Genex shows the frozen Nex and real-money price and receives consent
 - [ ] No payment buttons in the Genex app
 - [ ] Cancellation is silent; uncertain outcomes remain pending
-- [ ] Recovery reads receipts before applying any paid action
+- [ ] Recovery reads entitlements and receipts before applying any paid action
 - [ ] Fulfillment is idempotent, including reload and concurrent-tab cases
-- [ ] No paid randomness, coin wagering, donation prompt or pressure timer
+- [ ] No paid randomness, Nex wagering, donation prompt or pressure timer
 - [ ] Nothing sold is unreachable without paying
 
 ## Troubleshooting
@@ -314,8 +341,9 @@ a published build for an explicitly approved real purchase.
 **`surface_cap`** — the amount exceeds the server's limit for this confirmation
 surface. Do not split it into smaller hidden charges to bypass the limit.
 
-**`price_off_grid`** — this applies to legacy catalog SKUs only. Dynamic
-payments accept whole amounts subject to their own caps.
+**`price_off_grid`** — a store item's price is not on the grid. The refusal
+prints it (so does `genex shop list`); pick a price from it, or 0 for Free.
+Dynamic payments accept whole amounts subject to their own caps.
 
-**Everything coin-related 404s** — coin commerce is disabled on this stand.
-Build the rest and report the unavailable lane.
+**Everything Nex-related 404s** — Nex commerce is off on this stand. Build
+the rest and report the unavailable lane.