@genex-ai/cli-demo 1.36.8 → 1.36.9-dev.915

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

@@ -115,15 +115,7 @@ currency without touching balance.
 
 ## Dynamic payment requests
 
-Requires `@genex-ai/embed-sdk` **>= 0.33.0**. Earlier versions, including
-`^0.32.0`, do not export these payment helpers. Update the game's dependency
-before wiring them, then rebuild and publish the game:
-
-```bash
-npm install @genex-ai/embed-sdk@latest
-```
-
-After `initEmbed()` and player identity are ready:
+From `@genex-ai/embed-sdk`, after `initEmbed()` and player identity are ready:
 
 ```ts
 import { requestPayment, getPayment, getPayments } from '@genex-ai/embed-sdk';

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -469,8 +469,9 @@ Rules:
   `[::1]` — not https, not a LAN IP), the page is not inside an iframe, and
   `@genex-ai/embed-sdk` is 0.5.0+ (older: apply the pending platform update).
 - **Multiplayer `connect()` fails in local test mode** — by design: no relay
-  credential exists there. Validate multiplayer on the hosted draft (the
-  owner's session) or the published game, and say plainly when it wasn't.
+  credential exists there. Validate multiplayer on the preview link (it plays in
+  rooms of its own; a normal and a private window are two players), and say
+  plainly when it wasn't.
 - **Multiplayer join rejected with 401** — the join ran before
   `waitForPlayer()` resolved, without `auth: () => getColyseusAuth()`, or with a
   stale cached token on reconnect (read it fresh each call).

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -33,23 +33,42 @@ example, the shared-object/ball code, rotation, and host usage. Read
 calling multiplayer done, run the mandatory
 [netcode feel gate](references/genex-netcode-feel-checklist.md).
 
+## Testing multiplayer: on the preview link, with two different players
+
+**A preview build is multiplayer in rooms of its own.** `npx genex preview` (the
+`preview--<slug>` address) plays in rooms the relay keeps apart from the live game: testers on the
+preview link meet each other and never meet real players, and a published game's players never see
+an untested build. Anyone with the preview link can join, as a guest or signed in, even before the
+game is published. You do nothing for this: the game always passes its plain slug; the relay picks
+the room.
+
+- **Test it on the preview, as two DIFFERENT players:** the preview link is the `preview--<slug>`
+  address `npx genex preview` prints on its "Live" line (the dashboard's draft page is the owner's
+  only). Open it in a normal window and an incognito window (the incognito one plays as a guest),
+  or send it to a friend.
+  Two tabs on one account are ONE seat: the newer tab takes it (close code 4409).
+- Until two players have played it, tell the user multiplayer is built but not yet verified, give
+  them the preview link and say exactly that: open it in a normal and an incognito window.
+- Nobody can save or buy on a preview, the owner included. Test progression saves and purchases
+  after publishing.
+
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.16.0
+npm i @genex-ai/multiplayer@^0.17.0
 ```
 
-> Pin `@^0.16.0` (not a bare `npm i`, and not an older range): automatic TURN — the thing that
+> Pin `@^0.17.0` (not a bare `npm i`, and not an older range): 0.17 speaks the relay's current
+> wire protocol, and the relay **refuses every older SDK** — a game built on 0.16 or earlier
+> cannot join a room at all (its joins fail with `unsupported protocol`). 0.17 also added a
+> relay-stamped per-game player id (`p.uid`), relay-assigned teams for the `open` preset
+> (`p.team`) and the `room:open` event. Earlier floors still hold: automatic TURN — the thing that
 > lets players behind symmetric NAT or carrier CGNAT be heard at all — landed in 0.16, mesh voice
-> in 0.15, room text chat in 0.14, host-only `setRoomOpen()` in 0.13; cross-region invites can
-> select the inviter's exact relay with the optional `url` override since 0.11; unowned object
-> writes warn instead of failing silently, live connected-player presence, supplier-form
-> `connect()` auth and regional relay selection (`getColyseusUrls()` + `urls`) landed in 0.10;
-> confirmed object controls, snaps, host-tick teardown, and reconnect rebasing in 0.9. An older
-> resolve does not have those — and because this package is still `0.x`, a caret range is
-> minor-locked, so `^0.12.0` would resolve to 0.12.x and give you no voice at all.
-
-This skill targets `@genex-ai/multiplayer` **≥ 0.16.0** (`objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
+> in 0.15, room text chat in 0.14, host-only `setRoomOpen()` in 0.13. Because this package is
+> still `0.x`, a caret range is minor-locked, so `^0.16.0` would resolve to 0.16.x and never join.
+
+This skill targets `@genex-ai/multiplayer` **≥ 0.17.0** (relay protocol 3, `p.uid`/`p.team` and
+`room:open` since 0.17; `objects`/`host` since 0.4; verified per-player `avatarUrl` since 0.12;
 room text chat via `room.chat` since 0.14; mesh voice via `room.voice` since 0.15;
 automatic TURN (voice connects behind symmetric NAT with no configuration) since 0.16;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
@@ -132,6 +151,8 @@ mm.on("matched", () => syncSession());
 mm.on("matchStart", () => syncSession()); // duel/arena/teams only
 mm.on("matchEnded", (result) => showResult(result)); // duel/arena/teams only
 mm.on("error", (e) => showQueueError(e)); // after SDK retries; fix, then mm.retry()
+// 4409 = opened in another tab/device, 4401 = signed out: the handle stops, never requeues.
+mm.on("disconnect", () => showMenu("This game is open somewhere else.")); // mm.retry() only on a click
 
 // Every frame AND a low-rate timer: the handle swaps in a new Session after
 // seating, terminal drop/requeue, and the next match.
@@ -330,8 +351,9 @@ halves of this rule are non-negotiable:
    is never written (host bug, host left), every player is stuck on the waiting screen forever.
    A ready-check or countdown is fine as an ADDITION layered on top of `status === 'playing'`
    (host writes it to `shared` so it survives host migration), never as a replacement for it.
-2. **Verify it for real before calling multiplayer done**: open the game in two browser windows
-   (one regular + one incognito, so they're two players), join with both, and watch the waiting
+2. **Verify it for real before calling multiplayer done**: on the preview link (see "Testing
+   multiplayer"), open it in two browser windows (one regular + one incognito, so they're two
+   players), join with both, and watch the waiting
    screen disappear on BOTH the moment the count reaches `minPlayers` (with
    `minPlayers: 2, maxPlayers: 2`: the instant the second player joins). If it doesn't close on
    both, the lobby is broken — fix it; do not ship a waiting room you haven't watched close.
@@ -669,7 +691,8 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   - `ids()` — all object ids seen.
 - `room.isHost` / `room.host` — you are (or who is) the elected authority. Use to pick the single
   writer of `shared` scores/rounds and the single simulator of host-owned objects. Settles within
-  the first patch after connect — read in your loop / react to `on('host')`, not once.
+  the first patch after connect — read in your loop / react to `on('host')`, not once. `isHost` is
+  false while reconnecting (until the fresh snapshot lands), so gating a write on it is safe.
   `room.host === undefined` before that patch means **authority is not ready**:
   do not start host-owned simulation and do not synthesize an "acting host" from
   a locally sorted roster. Clients can briefly observe different rosters, so
@@ -930,11 +953,11 @@ function awardOnce(scorerUid: string, name: string, marker: `__${string}`, seq:
 ```
 
 **Key scores by a STABLE identity, never the session id.** A session id dies on every reload —
-the points orphan into a duplicate row and the player's color changes. Publish a short `uid` in
-each player's state (from the embed identity: `const { user } = await waitForPlayer()`,
-`uid = user.id` — stable for signed-in players AND guests; see `$genex-threejs-embed-auth`), and
-key `scores`/colors/`isMe` by that uid. When an event only carries a session id, map it via
-`room.players.get(sid)?.stateRaw.uid`.
+the points orphan into a duplicate row and the player's color changes. The relay stamps every
+player with `uid` — their stable id **in this game**, the same across reloads, never their account
+id — so key `scores`/colors/`isMe` by it. When an event only carries a session id, map it via
+`room.players.get(sid)?.uid`. Never publish the account id (`user.id`) in player state yourself:
+every peer reads it.
 
 For host-simulated NPCs, the host claims and drives each enemy as an `object`; when the host
 leaves, its enemies are reassigned to the new host, which reads their `stateRaw` and keeps
@@ -985,10 +1008,11 @@ from any still capture whether movement feels smooth.** Don't try — it leads t
    other (and the ball, if any). That's all a capture can prove. Local test mode (what the dev
    server boots into — the embed-auth skill) can NOT do this: it mints no relay credential, so `connect()`
    fails there by design and two local-test tabs never see each other — run the two-client check
-   on the published game (or have the owner open their draft), and if multiplayer wasn't
-   exercised, say exactly that in your handoff instead of implying it was.
+   on the preview link (see "Testing multiplayer"), and if multiplayer wasn't exercised, say
+   exactly that in your handoff instead of implying it was.
 3. **Then say plainly:** *"Multiplayer smoothness depends on your network and can only be felt by a
-   person — open it in two tabs or with a friend and tell me how it feels."* Stop there.
+   person — open the preview link in a normal and a private window, or send it to a friend, and
+   tell me how it feels."* Stop there.
 
 ### When the human reports a problem, match the symptom (don't guess)
 
@@ -1062,7 +1086,7 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.16.0` (automatic TURN, mesh voice, room text chat, connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks, unowned-write warnings, cross-region exact-relay overrides); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.17.0` (the only range the relay accepts; per-game `p.uid`, automatic TURN, mesh voice, room text chat, connected presence, supplier auth, confirmed controls, snap epochs, reconnect-safe host ticks, unowned-write warnings, cross-region exact-relay overrides); config wired into the build.
 - [ ] The plan names one net model, the player-experience reason, start/quorum, late-join/backfill,
       and below-quorum/end behavior. The agent inferred it unless the experience was genuinely ambiguous.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
@@ -1081,7 +1105,7 @@ host-driven saving works as long as ANY account is in the room.
       dedupe keys, the victim applies its own damage, respawn publishes via `me.snap`, and
       projectiles are hard-capped objects removed with `removeConfirmed`.
 - [ ] Host score writes are exactly-once (marker in the same `shared` write) and keyed by the
-      stable embed `uid`, never the session id.
+      relay-stamped `p.uid`, never the session id.
 - [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: () => getColyseusAuth()` (the relay rejects tokenless joins —

package/templates/skills/genex-threejs-multiplayer/references/genex-netcode-feel-checklist.md

@@ -44,8 +44,9 @@ suite for the game.
 
 ## One focused proof with two distinct identities
 
-Use regular + incognito guest identities, two accounts/devices, or ask the user to perform the exact
-sequence. Two tabs sharing one identity are one enforced seat.
+Run it on the preview link (`npx genex preview`): a preview plays in rooms of its own, apart from
+the live game. Use regular + incognito guest identities, two accounts/devices, or ask the user to
+perform the exact sequence. Two tabs sharing one identity are one enforced seat.
 
 1. Enter online using real clicks. Then press Space/Enter/the main action using real key input; confirm
    focus did not re-trigger Play/Leave and both sessions remain live.

package/templates/skills/genex-threejs-multiplayer/references/genre-recipes.md

@@ -169,7 +169,7 @@ SKILL.md is the assignment story, verbatim. Everything else is Recipe 1/2 mechan
 
 | Thing | Channel | Authority |
 | --- | --- | --- |
-| Each player's avatar (+ `uid`, hp, `life`) | `me.set` / `players` | each player |
+| Each player's avatar (hp, `life`; the relay stamps `uid`) | `me.set` / `players` | each player |
 | The team map (`id → red/blue`) | `shared` (`"teams"`) | the **host** — the SKILL.md reconciler, every tick |
 | Team scores | `shared` (exactly-once marker — SKILL.md host section) | `room.isHost` |
 | Attacks / defeats | `send` (Recipe 2 rules verbatim) | attacker / victim |

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)
 ```