@genex-ai/cli-demo 1.36.5 → 1.36.6-dev.862

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 coin 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

@@ -234,6 +234,22 @@ 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.
 
+Where that surface is depends on the shell the game is in
+(`$genex-threejs-embed-auth`, `references/shells.md`), and two of them change
+what the game does:
+
+- **On the game's Genex page the sheet is drawn by the page, above the game.**
+  To show it, the page leaves fullscreen first, and the SDK lets go of the
+  pointer lock before it asks (`@genex-ai/embed-sdk` 0.32.0+; a build on an
+  older SDK keeps the cursor captured until the player presses Escape). Treat
+  a purchase like a pause: re-enter fullscreen and re-lock the pointer from
+  the player's next Resume click, never by yourself.
+- **The Genex app has no purchase surface yet.** There `buy()` resolves
+  `failed` without opening anything. That is the app, not an error: when
+  `getShell()` from `@genex-ai/embed-sdk` is `"app"`, show the shop as
+  browse-only or leave the buy buttons out, and never show a failure message
+  for it.
+
 ### Delivering
 
 ```ts
@@ -295,6 +311,8 @@ your own earnings. Use the test grant instead.
 - [ ] 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
+- [ ] In the Genex app (`getShell() === "app"`) the buy buttons are hidden or
+      the shop is browse-only — never a failure message
 - [ ] `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
@@ -338,3 +356,11 @@ 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.
+
+**`buy()` returns `failed` inside the Genex app** — the app has no purchase
+surface yet, so nothing opens. Not a bug to chase: hide the buy buttons there
+(`getShell() === "app"`).
+
+**The game dropped out of fullscreen when the shop's confirmation opened** — by
+design on the game's Genex page: the confirmation is the page's, and the page
+has to be visible to show it. Re-enter from the player's next click.

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

@@ -114,9 +114,9 @@ grants the permission.
    "click to resume" button.
 5. Always-visible state: reticle while locked; real cursor + "click to
    aim/resume" cue while unlocked. The cue is also the validation hook.
-6. If the lock request is rejected (a third-party page embedding the game
-   without `allow="pointer-lock"`), the mode falls back to drag-orbit — show
-   "Drag to look" instead. Never a dead game.
+6. If the lock request is rejected (a sandboxed embed without the
+   `allow-pointer-lock` sandbox token), the mode falls back to drag-orbit —
+   show "Drag to look" instead. Never a dead game.
 7. Gate firing/actions on `followCam.aimState === "locked"` — the click that
    acquires the lock (and any drag in the fallback) must not also shoot.
 8. Do NOT exit the lock between rounds, respawns, or cutscenes — only for real

package/templates/skills/genex-threejs-character-controller/references/wiring.md

@@ -178,8 +178,8 @@ Want a custom HUD? Read `onAimChange: ({ state }) => …` yourself instead of th
   eye-height target fed to `moveTo`, `avatar.visible = false`, and
   `controller.setLockForward(true)`.
 - **Touch / rejected lock:** touch never locks (the mode reports `"off"`); a
-  third-party embed without `allow="pointer-lock"` goes `"unavailable"` and
-  drag-orbit stays as the fallback — never a dead camera.
+  sandboxed embed without the `allow-pointer-lock` sandbox token goes
+  `"unavailable"` and drag-orbit stays as the fallback — never a dead camera.
 
 The bucket rule (mandatory / recommended / never) and the full lock lifecycle
 contract live in `$genex-threejs-camera-direction`.