@genex-ai/cli-demo 1.36.0 → 1.36.1-dev.776

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-tool-llm/SKILL.md

@@ -13,11 +13,12 @@ model has to run for the player.
 ## What the platform does
 
 A game hosted on Genex can call a language model from inside the running game
-and get back text or JSON. **The player pays and the player approves**: coins
-from their Genex wallet, or their own Claude / ChatGPT subscription, chosen on
-an approval sheet Genex draws that the game cannot render, skin or bypass.
-Either one call at a time, or one standing budget the player approves once and
-the game then spends against without another popup. The game holds no provider
+and get back text or JSON. **The player pays and the player approves**: credits
+from their Genex account, billed as each call is used and never past the
+per-call ceiling the game declares, or their own Claude / ChatGPT subscription,
+chosen on an approval sheet Genex draws that the game cannot render, skin or
+bypass. Either one call at a time, or one standing budget the player approves
+once and the game then spends against without another popup. The game holds no provider
 key, sees no credential, and never talks to a model vendor.
 
 That is the whole reason this is a platform feature and not something you wire
@@ -40,9 +41,9 @@ Any of these means a model at PLAY time, however it is phrased:
 Say this and stop:
 
 > A model running while people play is built into the Genex platform — the
-> player pays, with Genex coins or their own Claude/ChatGPT subscription, and
-> approves it on a Genex sheet; your game just calls `generate()`. Want it
-> that way?
+> player pays, with their Genex credits or their own Claude/ChatGPT
+> subscription, and approves it on a Genex sheet; your game just calls
+> `generate()`. Want it that way?
 
 Wait for the answer. Do not start building either version first, and do not
 expand the offer into a pitch — one line, one question.
@@ -64,7 +65,8 @@ expand the offer into a pitch — one line, one question.
    ask before you do if you have not already.
 3. Load `$genex-llm-in-games` — it arrives with the conversion and owns the
    build: the SDK surface, one-time calls versus a standing budget, measuring
-   the price before the game declares it, and honest handling of every refusal.
+   the per-call ceiling before the game declares it, and honest handling of
+   every refusal.
 
 **The game has to be a static browser build.** A hosted game is files served
 from the edge; there is no server of yours inside it. So the familiar pattern —

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

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