@genex-ai/cli-demo 1.36.0-dev.773 → 1.36.0

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

@@ -1,28 +1,16 @@
 # Calibrate, then declare
 
-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.
+`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.
 
 ## 1. Freeze the prompt first
 
@@ -34,7 +22,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
-billed for an unusable result.
+charged for an unusable result.
 
 ## 2. Run the benchmark
 
@@ -45,105 +33,89 @@ 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-credits <n> --user-approved
+  --max-coins <n> --user-approved
 ```
 
-- 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
+- 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
   call. That is the same shape as every other spend approval in the CLI: you
-  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.
+  state the ceiling for this run, out loud, once.
 - `--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. A file from before credits is reprinted as history, with a
-  request to re-run.
+  anything again.
 
 ## 3. Read the output
 
-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
+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
 learns nothing.
 
 A sample the model had to stop writing (`provider_token_limit`) was cut off at
-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
+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
 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?".
+  you ask "can the game afford this loop?" — multiply it by the calls per
+  minute you are about to disclose.
 - **p95** is what a bad-but-normal call costs: a long answer, a model that
-  reasons its way around. It is what the **ceiling** has to cover, because a
-  ceiling below it cuts the unlucky calls off.
+  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.
 - **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.
 
-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:
+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:
 
 ```ts
-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
+const NPC_CALL_PRICE = <the recommended figure>;    // from `npx genex llm bench`, <date>
+const NPC_CALL_CEILING = <the printed ceiling>;     // same run — grants only
 ```
 
-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.
+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.
 
-The invariants, which the SDK and the server both enforce:
+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:
 
 ```
-perCallEstimateCredits  ≤  perCallMaxCredits  ≤  the limit the player approves
-maxCredits on each call  ≤  perCallMaxCredits
+perCallEstimateCoins  ≤  perCallMaxCoins  ≤  the limit the player approves
 ```
 
-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.
+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.
 
 ## 4. Turn the game's loop into the disclosure
 
@@ -157,39 +129,27 @@ 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. **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.
+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.
 
 ```ts
-perCallMaxCredits: NPC_GRANT_MAX,
-perCallEstimateCredits: NPC_CALL_ESTIMATE,
 disclosure: {
   periodLabel: 'minute',
   estimatedCallsPerPeriod: 10,
-  estimatedCreditsPerPeriod: Math.ceil(10 * NPC_CALL_AVERAGE),
+  estimatedCoinsPerPeriod: 10 * NPC_CALL_PRICE,
 }
 ```
 
 The player sees this attributed to your game — "the game estimates about …" —
-beside the platform's own worst case computed from `perCallMaxCredits`. The two
+beside the platform's own worst case computed from `perCallMaxCoins`. 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 tuning can.** Five NPCs
+**Batching changes this arithmetic more than any price tuning can.** Five NPCs
 answered by one call that returns five decisions is two calls a minute, not ten,
-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.
+and one benchmarked price for the batched prompt replaces five of the unbatched
+one. Do that before you reach for a cheaper model.
 
 ## Worked example
 
@@ -200,21 +160,20 @@ 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-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.
+   --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.
 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 average.
+   minute at the batched price.
 7. Re-run steps 1–4 whenever the prompt, the schema or the model changes. A
-   prompt edit changes the ceiling; treat it like one.
+   prompt edit is a price change; 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 cost.
+game — a different prompt has a different price.

package/templates/skills/genex-tool-llm/SKILL.md

@@ -13,12 +13,11 @@ 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**: 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
+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
 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
@@ -41,9 +40,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 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?
+> 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?
 
 Wait for the answer. Do not start building either version first, and do not
 expand the offer into a pitch — one line, one question.
@@ -65,8 +64,7 @@ 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 per-call ceiling before the game declares it, and honest handling of
-   every refusal.
+   the price 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@dev   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@latest   # 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)
 ```