@genex-ai/cli-demo 1.36.16 → 1.36.17-dev.1046

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "1.36.16",
+  "version": "1.36.17-dev.1046",
   "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-cover/SKILL.md

@@ -272,7 +272,7 @@ from it instead of from scratch; a game kept as it is records nothing.
 | Shape | Landscape 16:9, at least 320×180; shoot 1920×1080 (any 16:9 from 1280×720 up). Anything else is centre-cropped to 16:9. |
 | File | PNG preferred; JPEG and WebP too, recognised by their bytes, not the name. At most 8 MB — over that, a high-quality JPEG. |
 | Stored | 1280×720 WebP plus a JPEG sibling, EXIF-rotated, transparency flattened onto black. A smaller frame is scaled up and goes soft. |
-| Gate | Rec.709 luma of the encoded pixels (0–1) on a 160×90 downscale of the centre 16:9. **Too dark**: mean below 0.12, or more than 85% of samples below 0.10. **Flat**: luma spread (std) below 0.04. A plainly lit scene reads about 0.4–0.6. The gate catches broken frames only; passing it says nothing about beauty. |
+| Gate | Rec.709 luma of the encoded pixels (0–1) on a 160×90 downscale of the centre 16:9. **Too dark**: mean below 0.11, or more than 85% of samples below 0.10. **Flat**: luma spread (std) below 0.04. A plainly lit scene reads about 0.4–0.6. The gate catches broken frames only; passing it says nothing about beauty. |
 | Who wins | The owner > you > a frame from the owner's own play > a build-session screenshot > the game's menu art > a remix's inherited cover > old AI art — decided by the credential the frame arrives with, never by anything you send. You replace your own pick and every automatic one, never the owner's; their own upload is never gated. |
 | Limits | 10 upload starts and 20 commits an hour per account, for all its agents together. |
 

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

@@ -158,7 +158,7 @@ vendored code from memory of another engine.
 | 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 Nex (Genex's currency, bought with real money) or for real money with no currency named: a shop, an item catalog, boosts, cosmetics, "make it earn"; a fixed Nex price is a store item. Coins, gold or gems are the game's own earned currency, not this row. Also any request for a loot box, gacha, wager, casino mechanic or donation prompt, which that skill refuses and replaces | `$genex-monetization` |
 | an item for the Genex store — sell a sword, a skin or a pet for Nex with its picture and description, "other games can use it too" — or another creator's shared item added to this game (`npx genex items add <id>`). Build the item first, list it with `npx genex shop add … --json` without asking; the person puts it on sale | `$genex-items` (with `$genex-monetization`) |
-| the game calls a language model AT RUNTIME on the player's money: NPCs that answer in their own words, dialogue or quests written per save, a judge reading what the player typed — one-time calls, or a standing budget the player approves once. Check the lane with `npx genex llm models` before designing it in | `$genex-llm-in-games` |
+| the game calls a language model AT RUNTIME on the player's credits, billed as used under a per-call ceiling the game benchmarks with `npx genex llm bench`: NPCs that answer in their own words, dialogue or quests written per save, a judge reading what the player typed — one-time calls, or a standing budget the player approves once. Check the lane with `npx genex llm models` before designing it in | `$genex-llm-in-games` |
 | 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

@@ -161,7 +161,7 @@ downloads the game too, binary assets and all:
 
 ```bash
 mkdir my-game && cd my-game
-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
 npm install
 ```
 
@@ -225,7 +225,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-llm-in-games/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: genex-llm-in-games
-description: Call a language model from inside a running game — an NPC that answers in its own words, a quest written for this save, a judge that reads what the player typed. The PLAYER pays and approves, on a Genex surface the game cannot forge. Covers the two modes (a popup per call, or one standing budget then many silent calls), benchmarking the price before declaring it, the receiver pattern, and honest handling of every refusal.
+description: Call a language model from inside a running game — an NPC that answers in its own words, a quest written for this save, a judge that reads what the player typed. The PLAYER pays and approves, on a Genex surface the game cannot forge. Covers the two modes (a popup per call, or one standing budget then many silent calls), benchmarking the per-call ceiling before declaring it, the receiver pattern, and honest handling of every refusal.
 ---
 
 # Genex LLM in Games
@@ -8,10 +8,11 @@ description: Call a language model from inside a running game — an NPC that an
 A Genex game can call a language model **while the player is playing** and get
 back text or JSON. Nothing else: no images, no code execution, no tools.
 
-**The player pays, and the player approves.** Funding is coin from their Genex
-wallet or their own Claude / ChatGPT plan, chosen on a Genex-drawn surface your
-game cannot render, skin or bypass. The game holds no provider key, sees no
-credential, and never talks to a model vendor.
+**The player pays, and the player approves.** Funding is their Genex credits —
+billed as used, never past the per-call ceiling your game declares — or their
+own Claude / ChatGPT plan, chosen on a Genex-drawn surface your game cannot
+render, skin or bypass. The game holds no provider key, sees no credential, and
+never talks to a model vendor.
 
 Two modes. Picking the wrong one is the most expensive mistake on this lane:
 
@@ -25,6 +26,23 @@ Two modes. Picking the wrong one is the most expensive mistake on this lane:
 A popup per NPC turn is not a feature, it is an interruption. More than a call
 or two per session means a grant.
 
+**Deciding, not writing? Use the judge.** When the game needs to KNOW something
+— is this NPC lying, which of five moods is the player in, how threatening is
+the scene on a scale — and not to produce words, ask the grant's classifier with
+`judge()` instead of asking `generate()` for a label. It answers typed questions
+(`choice`, `score`, `noul`) with calibrated probabilities in about a third of a
+second, writes no prose and cannot drift out of your options. It is grant-only
+and billed as used: each call is a small fraction of a credit and accrues on the
+budget, so a check every turn is affordable where a generate every turn is not.
+`generate()` for words, `judge()` for decisions; a feature often wants both —
+the judge picks the branch, generate writes the line.
+
+**Words the player watches appear? Stream them.** Dialogue, narration, an NPC's
+reply in a speech bubble: under a grant, `generateStream()` is the same call as
+`generate({ grantId })`, but the text arrives while the model writes it instead
+of all at once after it. Keep `generate()` for answers the game only uses whole
+(a quest object, a list of decisions) — nobody watches those being written.
+
 ## Step 0 — is the lane live on this stand?
 
 ```bash
@@ -61,15 +79,33 @@ identity must be resolved first — `$genex-threejs-embed-auth`.
   rest only if the player asks. Each row carries `label`, `vendor`,
   `contextLength`, `personalPlan` and `structuredOutputs`; render `label`
   verbatim, so the name on screen is the model that gets billed.
-- `generate({ modelId, prompt, outputFormat, schema?, estimateCoins,
+- `generate({ modelId, prompt, outputFormat, schema?, maxCredits,
   allowExternal?, idempotencyKey?, grantId?, timeoutMs? })` →
   `{ status, generationId, output, source, error }` plus billing fields
-  (`billingStatus`, `reservedCoins`, `chargedCoins`, their display-USD twins).
-- `requestSpendGrant({ models, perCallMaxCoins, perCallEstimateCoins,
-  disclosure: { periodLabel, estimatedCallsPerPeriod, estimatedCoinsPerPeriod },
-  maxConcurrent?, maxCallsPerMinute?, allowExternal?, idempotencyKey? })` →
+  (`billingStatus`, `maxCredits`, `reservedCredits`, `chargedCredits`, their
+  display-USD twins). `maxCredits` is the call's CEILING, never a price.
+- `requestSpendGrant({ models, perCallMaxCredits, perCallEstimateCredits?,
+  disclosure: { periodLabel, estimatedCallsPerPeriod, estimatedCreditsPerPeriod },
+  maxConcurrent?, maxCallsPerMinute?, allowExternal?, judge?: { enabled,
+  estimatedCallsPerPeriod }, idempotencyKey? })` →
   `{ status, grantId, … the limits the player approved }`; status is `active` |
-  `canceled` | `expired` | `failed` | `pending`.
+  `canceled` | `expired` | `failed` | `pending`. `perCallEstimateCredits` is the
+  honest per-call figure the disclosure is built on; left out, it is the
+  ceiling.
+- `judge({ grantId, state, questions, idempotencyKey?, timeoutMs? })` →
+  `{ status, generationId, answers, error, billing }` — the grant's classifier,
+  answered in the same response. `questions` is 1–64 named `choice`
+  (`{ instructions, criteria: { option: description } }`), `score`
+  (`{ instructions, criteria: [levels, lowest first] }`) or `noul`
+  (`{ instructions }`); each answer has its question's type, and `noul` is a
+  probability — pick your own threshold. Needs a budget requested with `judge`.
+- `generateStream({ …the generate() options, grantId, onDelta?(text, soFar),
+  onPartialField?(name, partialText), signal? })` → the same result as
+  `generate()`. Grant-only. `onDelta` hands over each piece and all the text so
+  far; for `outputFormat: 'json'`, `onPartialField` reports the schema's FIRST
+  top-level string property as far as it is written — put the spoken line first
+  in the schema. `signal` stops the reading, never the call (it still finishes
+  and is charged).
 - `getSpendGrant(grantId)` — live state and counters; the ONE source for an
   in-game budget readout.
 - `stopSpendGrant(grantId)` — the game's own stop door. Prospective: no further
@@ -77,13 +113,22 @@ identity must be resolved first — `$genex-threejs-embed-auth`.
 - `waitForGeneration(id)` / `getGeneration(id)` — re-attach to a call already
   started, including after a reload.
 - `generationErrorMessage(code)` — one player-facing sentence for an error code.
+- `requestWorkflow(…)` — a registered workflow's own door, unchanged: keep
+  sending what that workflow's offerings ask for.
+
+The credit names arrived in `@genex-ai/embed-sdk` 0.27.0. On `generate()`,
+`generateStream()` and `requestSpendGrant()` the coin spellings —
+`estimateCoins`, `perCallMaxCoins`, `perCallEstimateCoins` and
+`disclosure.estimatedCoinsPerPeriod` — are deprecated: still accepted, and read
+as the same numbers in credits. Write the credit names in anything new, and
+rename them when you touch old code.
 
 ```ts
 askButton.addEventListener('click', async () => {   // a real click
   const res = await generate({                      // FIRST statement, no await before it
     modelId, outputFormat: 'json', schema: ANSWER_SCHEMA,
     prompt: askPrompt(npc, playerLine),
-    estimateCoins: NPC_CALL_PRICE,                  // benchmarked — see below
+    maxCredits: NPC_CALL_MAX,                       // benchmarked — see below
     idempotencyKey: `npc:${npc.id}:${turnId}`,
   });
   applyGeneration(res);                             // the one writer — see below
@@ -103,40 +148,55 @@ test mode it is `local_test_unsupported`. Neither is a fault in the game. When
 point out and play the authored fallback; never show it as an error. Which
 shell draws what is in `$genex-threejs-embed-auth` (`references/shells.md`).
 
-## `estimateCoins` is a price, not an estimate
+## `maxCredits` is a ceiling, not a price
 
-You declare it; the platform charges it. Declare 5 and 5 is charged — on a
-success, a failure, a cancel, and when the model stops at its budget. Only an
-attempt with no model work at all costs nothing. A number picked by feel is
-money taken from your players for nothing, or a call that cannot fund itself.
+The player is billed **as used**: the call's real provider cost plus the
+platform fee, in credits. A one-time call is captured rounded UP to a whole
+credit when it settles; a call under a budget adds its exact fraction to the
+budget, and the player's credits move one whole credit at a time. A failed or
+canceled attempt is billed the work the model did; one with no model work at
+all costs nothing.
+
+So the game declares no price. It declares a per-call **ceiling** — `maxCredits`
+on `generate()`, `perCallMaxCredits` on a budget — and no call is ever billed
+past it. The ceiling has a second job: **it also decides how long the answer
+may be**, because each call's room to answer is funded from it. A number picked
+by feel either cuts answers off or asks the player to approve far more than a
+call ever costs.
 
 **Benchmark, then declare:**
 
 ```bash
 npx genex llm bench "<the real prompt, with a real example filled in>" \
-  --schema ./answer.schema.json --samples 3 --max-coins <n> --user-approved
+  --schema ./answer.schema.json --samples 3 --max-credits <n> --user-approved
 ```
 
-It runs on **your own coins**, on the development lane, and prints what each
-sample actually charged plus the recommendation to declare: p95 of the charged
-coins with the server's own recommended headroom already applied. Declare that
-printed number. Never guess it, never work it out from a vendor's price list,
-never add a margin of your own. For a standing budget the run prints a second
-line, `Grant perCallMaxCoins`, and that one is `perCallMaxCoins` — declare it
-verbatim as well rather than deriving a ceiling from `max`, which lands under
-the price and makes `requestSpendGrant()` refuse before it reaches the network. Full procedure — reading p50/p95, turning the
-loop into disclosure numbers, re-benchmarking after a prompt change — is in
-[references/pricing.md](references/pricing.md).
-
-**The declared price also decides how long the answer may be.** Each call's
-room to answer is funded from the price it declares, so a price that covers
-what an answer cost can still cut it off. The bench's recommendation already
-leaves that room — always declare what it prints, never the bare charged
-number. A sample cut off at your `--max-coins` is not a sample: re-run with a
-higher one. When the bench says the answer is longer than one call on this
-stand may produce, ask for a shorter answer.
-
-Only samples that **succeeded and settled** are priced from. A sample the
+It runs on **your own credits**, on the development lane, and prints what each
+sample really cost and was charged, then the numbers to declare:
+
+- `Declare maxCredits` — the p95 real cost with the platform fee and the
+  server's own recommended headroom applied, never below the room the answer's
+  length needs. That is `maxCredits` on every call of this prompt.
+- `Grant perCallMaxCredits` — the same over the worst sample. That is a
+  budget's `perCallMaxCredits`; declare it verbatim rather than deriving a
+  ceiling from the charged `max`, which carries neither the headroom nor the
+  answer's length and gets the budget's calls refused.
+- `Per-call estimate: about … credits per call` and
+  `Grant perCallEstimateCredits` — the measured average, fee included, and that
+  average rounded up to a whole credit: the honest figures a budget's disclosure
+  is built on.
+
+Declare the printed numbers. Never guess them, never work them out from a
+vendor's price list, never add a margin of your own. Full procedure — reading
+p50/p95, turning the loop into disclosure numbers, re-benchmarking after a
+prompt change — is in [references/pricing.md](references/pricing.md).
+
+A sample cut off at your `--max-credits` is not a sample: re-run with a higher
+one. When the bench says the answer is longer than one call on this stand may
+produce, ask for a shorter answer. `--max-coins` is the old name of
+`--max-credits` and still works, with a line saying so.
+
+Only samples that **succeeded and settled** are measured. A sample the
 provider refused at its door (`provider_http_<status>`) ran no inference and
 cost nothing; the bench prints the code, the provider's own message and, for a
 401 or 403, that this is the stand's provider configuration refusing the model
@@ -176,12 +236,12 @@ same object — a schema that passed the bench passes the game.
 ```ts
 const grant = await requestSpendGrant({          // inside the click handler
   models: [modelId],
-  perCallMaxCoins: NPC_CALL_CEILING,
-  perCallEstimateCoins: NPC_CALL_PRICE,
+  perCallMaxCredits: NPC_GRANT_MAX,              // the bench's "Grant perCallMaxCredits"
+  perCallEstimateCredits: NPC_CALL_ESTIMATE,     // its "Grant perCallEstimateCredits"
   disclosure: {
     periodLabel: 'minute',
     estimatedCallsPerPeriod: 10,                 // 5 NPCs, one decision each per 30s
-    estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE,
+    estimatedCreditsPerPeriod: Math.ceil(10 * NPC_CALL_AVERAGE),  // calls × the measured average
   },
   maxConcurrent: 2,
   maxCallsPerMinute: 30,
@@ -193,8 +253,45 @@ await savePlayerState({ ...state, grantId: grant.grantId });
 **The disclosure is computed from this game's own loop, never wished for.** Five
 NPCs deciding once every thirty seconds is ten calls a minute — write that
 arithmetic into `DESIGN.md` beside the feature. The player sees your estimate
-attributed to the game, beside the platform's own worst case; an estimate that
-is transparently low is a grant that dies mid-session.
+attributed to the game, beside the platform's own worst case built from
+`perCallMaxCredits`; an estimate that is transparently low is a grant that dies
+mid-session. Each call under the budget still declares its own `maxCredits`,
+and it may not be above the budget's `perCallMaxCredits`:
+
+```
+perCallEstimateCredits  ≤  perCallMaxCredits  ≤  the limit the player approves
+maxCredits on each call  ≤  perCallMaxCredits
+```
+
+**Using the judge too?** Add `judge: { enabled: true, estimatedCallsPerPeriod }`
+to the same request — the checks you really expect per `periodLabel`, from the
+same loop arithmetic. The sheet tells the player the game also uses a fast
+classifier billed as used, with the platform's own worst case beside your count.
+A judge-only feature passes `models: []`. A budget with the judge is paid from
+the player's credits only, and judge calls share the budget's `maxConcurrent` and
+`maxCallsPerMinute`: batch questions into one call (up to 64) rather than one
+call per question.
+
+**Streaming a reply under the budget:**
+
+```ts
+const res = await generateStream({
+  grantId, modelId, outputFormat: 'json', schema: LINE_SCHEMA,   // `line` is its first property
+  prompt: npcPrompt(npc, playerLine), maxCredits: NPC_CALL_MAX,
+  idempotencyKey: `npc:${npc.id}:${turnId}`,
+  onPartialField: (_name, soFar) => npc.bubble.show(soFar),     // provisional
+});
+applyGeneration(res);                                            // the answer is THIS
+```
+
+The pieces are provisional: a call can still fail after text has shown (the
+model broke off, the JSON missed the schema), so the bubble shows them and
+`applyGeneration` decides what the game keeps — the same one writer as always.
+Ceiling, benchmark and receipt are `generate()`'s: a started stream is billed the
+work it did even when the player walks away mid-sentence. A stream holds one
+of the budget's `maxConcurrent` slots until it has settled. Sometimes the reply
+arrives whole — a busy stand, a retried call, a budget on the player's own plan —
+and `onDelta` then gets the whole text once; the game needs no second path.
 
 **Then keep the burn low, because you wrote the loop:** batch those five NPCs
 into ONE call returning five decisions, cache a decision until the situation
@@ -209,10 +306,10 @@ Grant endings are ordinary game states with in-fiction copy, never an error toas
 | `grant_stopped` | the player pressed Stop | accept silently, keep playing |
 | `grant_expired` | 24h passed, or the session ended | as stopped; re-request on the next deliberate click |
 | `waiting_for_plan` | their own plan is rate-limited | wait out the stated time — not a failure, and there is no paid fallback |
-| `grant_insufficient_funds` | the wallet cannot fund the next call | pause the thinking NPCs, say it once, stay playable |
+| `grant_insufficient_funds` | the player's credits ran out before the next call | pause the thinking NPCs, say it once, stay playable |
 
-Draw the readout from `getSpendGrant(grantId)` — calls made, coins settled, what
-remains — never from a counter the game keeps itself. A finished grant may be
+Draw the readout from `getSpendGrant(grantId)` — calls made, credits settled,
+what remains — never from a counter the game keeps itself. A finished grant may be
 re-requested, but only from a **fresh deliberate click**: a silent auto-renew is
 the exact shape a standing approval exists to prevent.
 
@@ -240,18 +337,18 @@ function applyGeneration(res) {     // THE only place output becomes game state
   `modelProvenance: 'unverified'` because it is user-supplied — check it exactly
   as you would check typed player input.
 
-## Errors land on the player's wallet
+## Errors land on the player's credits
 
 There is no compensation lane, so this is all work you do before the call:
 
-- **Validate inputs first** — a malformed prompt is still charged.
+- **Validate inputs first** — a malformed prompt is still billed.
 - **Always set `schema` for `outputFormat: 'json'`** — unschema'd JSON is the
   commonest way a call is charged and the result is unusable. Write it in the
   accepted dialect above; a refused schema is `invalid_schema` and costs
   nothing, but it is a feature that never runs.
-- **Keep prompts short.** Long context is the price.
+- **Keep prompts short.** Long context is most of the bill.
 - **Never loop `generate()` without a grant**, and never retry in a loop — each
-  attempt is a separate charge.
+  attempt is a separate charge, and a one-time call is at least one whole credit.
 - **Map every code through `generationErrorMessage(code)`** into in-fiction
   copy. A player should never read a raw error code inside your game.
 - **`status: 'unknown'` is not a failure.** It means the charge is not known
@@ -260,12 +357,12 @@ There is no compensation lane, so this is all work you do before the call:
 
 ## What the Genex side already does — do not rebuild it
 
-The approval sheet shows the model, the prompt, the price and the terms; the
+The approval sheet shows the model, the prompt, the ceiling and the terms; the
 game renders no price sheet. **Subscription funding is chosen only there** —
 never add a "Your plan" row to the game's model picker, because a game cannot
 offer a funding source. When the player's own watcher is online the personal-plan
 answer arrives by itself and the game just waits, exactly as it waits for a
-coin-funded call. The Genex dashboard header shows progress, active grants with
+credit-funded call. The Genex dashboard header shows progress, active grants with
 their spend, and a Stop; a Stop pressed there reaches the game as `grant_stopped`.
 
 ## Never
@@ -276,7 +373,8 @@ their spend, and a Stop; a Stop pressed there reaches the game as `grant_stopped
   on your machine, never something a shipped build does.
 - **Never hand-roll fetch to the runtime API** — the SDK owns the approval
   handshake, and a hand-rolled call cannot obtain one.
-- **Never hardcode a price, a model id, a stand URL, or a margin.**
+- **Never hardcode a ceiling the bench did not print, a model id, a stand URL,
+  or a margin.**
 - **Never let the model be an authority over money, items or rewards**
   (`$genex-monetization` owns what may move a wallet).
 
@@ -288,12 +386,15 @@ These are source contracts, not a claim that every stand runs this lane —
 - [ ] `npx genex llm models` was run and its verdict is in the handoff
 - [ ] Model ids come from `getGenerationModels()`, never from source
 - [ ] The picker offers the featured set, labelled with the server's own `label`
-- [ ] `estimateCoins` is the figure `npx genex llm bench` printed, verbatim — never the bare charged number
+- [ ] `maxCredits` — and a budget's `perCallMaxCredits` / `perCallEstimateCredits` — are the figures `npx genex llm bench` printed, verbatim — never a charged number
+- [ ] No coin spelling (`estimateCoins`, `perCallMaxCoins`, `estimatedCoinsPerPeriod`) in new code
 - [ ] The schema uses only the accepted dialect (no `$ref`, `pattern`, `format`, `anyOf`, `default`)
 - [ ] A bench refused as `generation_limit` was answered with `npx genex llm status`, never a retry
 - [ ] `generate()` / `requestSpendGrant()` is the first statement of a click handler
 - [ ] A repeated-call feature uses a grant; a one-off uses `generate()`
-- [ ] Disclosure numbers derive from the real loop and are written in `DESIGN.md`
+- [ ] A decision (a label, a yes/no, a level) is a `judge()` question under the grant, not a `generate()` asked for a word
+- [ ] Dialogue the player watches appear uses `generateStream()` under the grant; the resolved result, not the pieces, goes to `applyGeneration()`
+- [ ] Disclosure numbers derive from the real loop and the bench's measured average, and are written in `DESIGN.md`
 - [ ] Calls are batched and cached; nothing fires on an invisible timer
 - [ ] Every grant-ending code has in-fiction copy and a playable fallback
 - [ ] In the Genex app (`getShell() === "app"`) the feature's entry point is left out and the authored fallback plays
@@ -312,18 +413,50 @@ Nothing to fix in the game: ship the fallback and say so.
 **Nothing opens when the player clicks** — an `await` ran before `generate()`
 and the gesture was lost. Move the call to the first line of the handler.
 
-**`player_wallet_required`** — ONE code for the two early dead ends: the lane
-refuses a guest and a PREVIEW build on the same line. `waitForPlayer()` tells
-them apart. `guest: true` — guests play but hold no wallet, so show the feature
-as sign-in-to-use rather than hiding it (`$genex-threejs-embed-auth`). Signed
-in and still refused — this is a `genex preview` draft, which never spends:
-check the layout there, and the call itself only after `genex promote`. The
-SDK's stock sentence for this code is "Sign in to Genex to use this", which is
-right for the guest and wrong on a draft, so write the in-fiction line per
-cause rather than showing it for both.
-
-**`grant_price_unreasonable`** — the declared per-call price is far above what
-that prompt can cost on that model. Re-benchmark and declare what it prints.
+**`player_wallet_required`** — ONE code for the two early dead ends: a guest on
+any build, and anyone but the game's OWNER on a `genex preview` test build.
+`waitForPlayer()` tells them apart. `guest: true` — guests play but have no
+credits to spend, so show the feature as sign-in-to-use rather than hiding it
+(`$genex-threejs-embed-auth`). Signed in and still refused on a test build —
+that account does not own the game. Open the preview signed in as the owner and
+the call works there, before any player sees it: the same sheet, the same
+terms, billed to the owner's own credits or plan, marked "test build" on Genex.
+Everyone else can use it after `genex promote`. The SDK's stock sentence for
+this code covers both causes; an in-fiction line per cause reads better.
+
+**`grant_price_unreasonable`** — a call under the budget declared a `maxCredits`
+above the budget's `perCallMaxCredits` (or a judge call's worst case is above
+it). Declare the bench's `Declare maxCredits` on each call and its
+`Grant perCallMaxCredits` on the budget — the second is never below the first.
+
+**`insufficient_credits`** — the player's credits cannot cover this one-time
+call's ceiling. Say it once in-fiction, keep the authored fallback, and never
+retry in a loop; the Genex sheet already offers them a top-up. From
+`npx genex llm bench` it is YOUR balance: the bench prints what it can spend.
+
+**`credits_unverified`** — the player's Genex email is not verified, and credits
+pay only for a verified account. Show the feature as verify-to-use rather than
+hiding it; nothing was charged.
+
+**`generation_paused`** — the platform has paused paid generation for now. Not
+the game's fault and not the player's: keep the authored fallback, try again
+on a later deliberate click, never in a loop.
+
+**`judge_not_enabled`** — the budget was approved without the judge. Request a
+new one with `judge` from the next deliberate click; never auto-renew.
+**`judge_requires_grant`** — the judge's model was sent to `generate()` with no
+budget; the judge is grant-only and is called with `judge()`.
+**`judge_requires_credits`** — a judge call under a budget that is not paid
+from the player's credits (their own plan cannot pay the judge). Request the
+budget with `judge` and let it be credit-funded; keep the authored branch.
+**`judge_period_limit`** — the checks reached the ceiling the player approved for
+the period (your own `estimatedCallsPerPeriod` at the largest size): wait, and
+if it keeps happening your declared rate is too low — fix the loop or the
+estimate, never retry in a tight loop.
+
+**`stream_requires_grant`** — `generateStream()` was called without a
+`grantId`. Streaming is grant-only: a one-time call waits on the player's
+approval popup, so use `generate()` for it.
 
 **`generation_limit`** — three ad-hoc calls are already in flight for this
 account, or recently stopped with their bill still pending; a pending call
@@ -340,9 +473,9 @@ stand's provider configuration refusing the model — tell the operator, and
 build nothing around it in the game.
 
 **`provider_token_limit`** — the answer was cut off: the model ran out of room
-before it finished, and the attempt is still charged. The declared price is too
-low for the answer's length — re-benchmark and declare what the bench prints,
-never the bare charged number — or the answer is longer than one call on this
+before it finished, and the attempt is still billed. The declared `maxCredits`
+is too low for the answer's length — re-benchmark and declare what the bench
+prints, never a charged number — or the answer is longer than one call on this
 stand may produce, and the fix is a shorter answer (fewer fields, shorter
 strings, a length the prompt states).
 
@@ -354,13 +487,17 @@ the subset above; `description` and `title` are allowed.
 **`grant_concurrency` / `grant_rate_limited`** — the game calls faster than the
 grant's own limits. Batch and cache; do not raise the limits to hide it.
 
+**`payer_busy`** — the player's account was busy on Genex for a moment and
+nothing was charged or started. Retry once after a short pause, from the same
+action; it is not a refusal.
+
 **`grant_not_active`** — the saved `grantId` is finished. Clear the stored id
 and re-request from a fresh click.
 
 **`external_request_active`** — that player already has one personal-plan
-request running. Wait for it; never fall back to charging coin instead.
+request running. Wait for it; never fall back to charging credits instead.
 
-**The call is charged but the result is unusable** — `outputFormat: 'json'`
+**The call is billed but the result is unusable** — `outputFormat: 'json'`
 without a `schema`. Add one; the charge already happened.
 
 **A reload lost the answer** — `generationId` was not saved before the await, or