@indiegems/gem-web-sdk 7.9.1 → 8.1.0

package/docs/changelog.md

@@ -16,6 +16,51 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 8.1.0
+
+Upgrading from 8.0.0. Impact: required.
+
+### Rebuild
+
+- The list of messages a frame sends to its parent, the FrameMessage type and the GemCapability type each gained a portrait borders member. Recompiling is enough for most games. If your code handles every FrameMessage or GemCapability member exhaustively, add a case for the new one so it keeps compiling.
+
+### New capability
+
+- A game can now ask whether a rewarded placement could pay right now, before it draws its reward button, by calling AdsApi.rewardedStatus with the placement. The answer is a RewardedStatus saying whether the placement is declared, whether it is grantable now, how many grants remain today, when it is next eligible, whether the held limit is reached, and when the allowance resets. Times are in epoch milliseconds. The call never rejects. A failed read, a missing play token or a bad placement resolves as not declared and not grantable, and the read gives up after ten seconds. A placement only counts as grantable when the Arcade you run in supports ads. Failures are reported once per kind through your error handler.
+- A game can now choose which border image from its store page the Arcade paints beside it in portrait by calling Gem.showPortraitBorders with the image's name. The name is a plain string of at most 40 characters, and one that fails the store page's naming rule is refused whole with a console warning. The choice is held until the bridge connects, sent at most once a second with the latest choice winning, and not resent if it matches what was last posted. If the Arcade does not advertise the portraitBorders capability, nothing is sent and nothing is raised.
+- If you embed a game in your own frame, GemFrame.showPortraitBorders lets you send the same border choice, or clear it. It sends only while connected and only to a parent that advertised the portraitBorders capability, and it applies the same name rule as the game side.
+- If you host games, you can now pass onPortraitBorders in your host options to receive the border name a game chose. The new GemPortraitBorders message carries it, and validateGemPortraitBorders checks a message you receive. The host re-checks the name on receipt and drops one that no store page could declare before your callback sees it.
+
+## 8.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 7.9.1. Impact: required.
+
+### Must change
+
+- BucketConfig changed its signature.
+- FRAME_TO_PARENT changed its signature.
+- FrameMessage changed its signature.
+- GemCapability changed its signature.
+
+### New capability
+
+- FriendChallenge was added.
+- FriendChallengesPage was added.
+- FriendsApi.inbox was added.
+- FriendsApi.launchedChallenge was added.
+- FriendsApi.markAnswered was added.
+- FriendsApiDependencies.launchedChallengeId was added.
+- ListFriendChallengesOptions was added.
+- Gem.vibration was added.
+- GemFrame.requestVibrate was added.
+- VibrationApi was added.
+- GemVibrate was added.
+- HostCallbacks.onVibrate was added.
+- HostOptions.onVibrate was added.
+- validateGemVibrate was added.
+
 ## 7.9.1
 
 Upgrading from 7.9.0. Impact: none.

package/docs/cross-promotion.md

@@ -13,8 +13,8 @@ const { outcome } = await gem.ads.requestAd({
 startNextLevel();
 ```
 
-That is the whole surface. The rest of this page is the four things a game gets wrong when nobody
-tells it.
+That is the whole surface, apart from one read that tells a rewarded button whether it could pay
+(§3). The rest of this page is the four things a game gets wrong when nobody tells it.
 
 ## 1. The answer is usually no, and no is ordinary
 
@@ -80,6 +80,36 @@ your player is already sitting in, and it is the whole of what changes on the da
 rebuild. [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the
 general form of this.
 
+**Whether a rewarded button could pay right now.** A rewarded placement is a button the player
+presses, so you need to know whether to draw it. `gem.ads.rewardedStatus(placement)` reads one
+placement's state from **your own** `rewarded_placements` config — its daily cap, cooldown and
+`max_held` — applied to this player's use of it:
+
+```js
+const status = await gem.ads.rewardedStatus('run-banked');
+bankButton.disabled = !status.grantable;
+```
+
+| field | what it says |
+|---|---|
+| `declared` | the config promoted to the channel being played names this placement |
+| `grantable` | pressing the button could pay right now — **not** that an ad will play |
+| `remainingToday` | grants left today under the daily cap; absent when the placement has none |
+| `nextEligibleAt` | when a running cooldown ends, in epoch milliseconds; absent when none runs |
+| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first |
+| `resetsAt` | when today's count resets, the next 00:00 UTC, in epoch milliseconds |
+
+**`grantable` is not a promise.** A player can press a `grantable` button and get `no_ad`, for
+reasons your game is not told. Read that `no_ad` like any other (§1) — never guess a reason — and
+re-read your inventory whatever the ask settled as. The status grants nothing and reserves
+nothing.
+
+It never rejects, like the rest of `gem.ads`. Without a play token, when the read fails or takes
+longer than ten seconds, or for a placement outside the grammar below, it answers not declared and
+not grantable with no `resetsAt`, and the reason goes to your `onError` handler. It is a read of
+the platform, so call it when you draw the button — on a results or death screen — and not every
+frame, and draw the rest of the screen first rather than holding it on the answer.
+
 ## 4. The Arcade pauses your game for you
 
 While a panel is up, your game is paused the same way it is paused when a player switches tabs —
@@ -130,6 +160,12 @@ schedule that does not depend on which branch produced it, so there is nothing i
 read either. (`shown` is not held back — how long that one takes is how long your player spent
 looking at a panel.)
 
+The one thing you can read is your own economy, and never from the answer:
+`gem.ads.rewardedStatus` reports **your own declared** rewarded caps as the platform holds them —
+the platform can hold a placement's daily cap below what you declared, never above — so you can
+tell when a rewarded `no_ad` was your own cap. It never reports anything about the player, the
+platform's spacing between offers, or any limit that spans games.
+
 ## If you do nothing
 
 Nothing happens. A game that never calls `gem.ads.requestAd` is never interrupted, and the call is

package/docs/friends.md

@@ -11,9 +11,10 @@ for (const friend of page.friends) {
 }
 ```
 
-That read, and one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
-confirms with the player and sends itself — are the whole surface. The boundary around them is the
-thing to understand before you design against it.
+That read, one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
+confirms with the player and sends itself — and [reading the challenges the player
+received](#reading-the-challenges-a-player-received) in your game are the whole surface. The
+boundary around them is the thing to understand before you design against it.
 
 ## What the read is, and is not
 
@@ -31,7 +32,8 @@ Everything else about the friend graph stays on the Arcade, by design:
   platform screens with the player's own account credential — a game frame holds a play token,
   and a play token cannot touch the graph. Sending a [friend challenge](#friend-challenges) does
   not touch it either: your game asks, and the Arcade sends only after the player confirms in its
-  own sheet.
+  own sheet. The one write a play token has is marking one of the player's own friend challenges
+  answered (`gem.friends.markAnswered`), which records that they played it and tells nobody.
 - **No states.** Pending requests, blocks and relationship history do not appear. An accepted
   friend appears; everyone else does not exist on this surface.
 - **No presence, no invites.** Nothing here says who is online or delivers an invite — an invite
@@ -174,15 +176,88 @@ existing `instanceof GemApiError` handling keeps working:
 
 ### When a challenge launches your game
 
-The friend's tap opens your game with the challenge's params in its launch query, read exactly as
-[your own launch keys](getting-started.md#linking-to-your-game) are: the param keys are
-launch-query keys, and every value arrived in a link, so validate it the same way. The Arcade adds
-one key of its own, `gemChallenge`, which is the platform's, not yours: never parse it. The SDK
-method that reads it ships in a later release.
+The friend's tap opens your game with the challenge's params in its launch query, and with one key
+of the platform's own, `gemChallenge`. **Do not read either from the URL to find the challenge.**
+Ask the SDK:
+
+```js
+const challenge = await gem.friends.launchedChallenge();
+if (challenge?.template === 'beat_code_jar') {
+  // Check every param before it does anything, as you would a launch key: the template
+  // constrained it when it was sent, but your config may have changed since.
+  const jar = typeof challenge.params.jar === 'string' && /^[A-Z0-9]{7}$/.test(challenge.params.jar)
+    ? challenge.params.jar
+    : null;
+  if (jar) {
+    startJar(jar, {
+      from: challenge.from, // who sent it, from the platform's records
+      replay: challenge.answeredAt !== undefined, // already played once
+    });
+  }
+}
+```
+
+`launchedChallenge()` reads `gemChallenge` once, when `createGem` runs — so cleaning your URL
+with `history.replaceState` afterwards changes nothing — and looks the challenge up on the
+platform. The order matters the other way too: call `createGem` before you clean the URL, or
+leave `gemChallenge` in place, because a key removed before `createGem` runs is never seen and
+`launchedChallenge()` resolves `null` with no error. You get the sender as a [friend row](#what-the-read-is-and-is-not), the template key and
+the params exactly as they were sent.
+
+It **resolves `null`**, never rejects, for every launch that is not this player's challenge in
+this game: no `gemChallenge` key, a value that is not a challenge id, a link naming someone
+else's challenge, one from another game or channel, and every guest launch. Treat `null` as an
+ordinary launch. Only a real failure — the platform unreachable, a context with no player —
+rejects.
+
+**Never put a name in a param, and never read one out.** A param key like `by=`, `from=` or
+`name=` is forbidden: the sender is `challenge.from`, resolved by the platform, and a name in a
+param is one nobody checked — your game would render whatever the sending client put there.
 
 **A relaunch replays the same challenge.** When the player presses Play again in the Arcade, it
-reuses the launch query, so the same params arrive again. Make answering a challenge idempotent:
-a second run of the same challenge is a replay, not a new one.
+reuses the launch query, so the same challenge comes back. Tell a replay from a first attempt by
+`answeredAt`, and make answering idempotent.
+
+### Marking a challenge answered
+
+When the attempt the challenge asked for is over — won or lost — mark it:
+
+```js
+await gem.friends.markAnswered(challenge.id);
+```
+
+It is idempotent: a challenge keeps the first time it was answered, and a second call changes
+nothing. It tells the sender nothing — there are no read receipts — so it is your game's own
+record, read back as `answeredAt` on every later read. It rejects `not_found` for an id that is
+not one of this player's challenges in this game and channel (one answer for unknown and
+someone else's), and `invalid`, before anything is sent, for a value that cannot be a challenge
+id at all.
+
+### Reading the challenges a player received
+
+`gem.friends.inbox()` lists the friend challenges this player holds **in this game, on this
+channel**, in every state:
+
+```js
+let page = await gem.friends.inbox();
+renderChallenges(page.challenges);
+while (page.nextCursor) {
+  page = await gem.friends.inbox({ cursor: page.nextCursor });
+  renderChallenges(page.challenges);
+}
+```
+
+- **Answered challenges are included, and sort last**; within each part, newest first. Filter on
+  `answeredAt` if you only want the open ones.
+- **A guest's page is empty**, not a refusal — a guest is never sent a challenge. Build the screen
+  for the empty state first.
+- **Paged like the friends list**: default 50, at most 200, an opaque cursor passed back verbatim.
+  A player holds at most 200 friend challenges across every game, so one max-size page is all of
+  them.
+- `openedAt` is when the player pressed Play on it in the Arcade. There is no "seen" time: that is
+  the Arcade's, not your game's.
+
+For the challenge this launch carried, use `launchedChallenge()` rather than searching the inbox.
 
 ## Inspecting a player: game profiles
 

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "7.9.1"
+  "@indiegems/gem-web-sdk": "8.1.0"
 }
 ```
 
@@ -342,8 +342,11 @@ That is the whole contract for your own keys. The bridge carries no launch messa
 has no API for them: the arcade does the forwarding, so a build you published on any SDK version
 gets it without a code change. The one key that is not yours is the platform's `gemChallenge`
 (below), which belongs to [friend challenges](friends.md#friend-challenges): never define it, and
-never parse it yourself. The SDK will read it for you, and that is the only launch key it will
-ever read: the method ships in a later release, and until then a game has nothing to do with it.
+never parse it yourself. The SDK reads it for you — `gem.friends.launchedChallenge()` answers the
+challenge it names, or `null` — and that is the only launch key it will ever read. It is read once,
+when `createGem` runs, so cleaning your URL afterwards does not lose it. Call `createGem` before
+you clean the URL, or leave `gemChallenge` in place: a key removed before `createGem` runs is never
+seen, and `launchedChallenge()` then resolves `null` with no error.
 
 What reaches the frame:
 
@@ -352,7 +355,8 @@ What reaches the frame:
   only keys the arcade keeps for itself; it never interprets yours:
   - Store and play-page switches: `play`, `channel`, `purchase`, and `build`, which pins one
     of your own builds when you play it from your Builds page.
-  - Platform switches: `devtools`, `devLocale`.
+  - Platform switches: `devtools`, `devLocale`, and `gem_test_ads`, the mode of the arcade's
+    rewarded TEST ads.
   - The arcade's own sign-in return marker: `social`.
   - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
     (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),
@@ -365,9 +369,10 @@ What reaches the frame:
   letter, so the arcade keeps that space for itself.
 
 - **One platform key.** `gemChallenge` does reach the frame — the arcade adds it when a player
-  opens a friend challenge — but it is the platform's, not yours. Do not define a key of that
-  name, and treat every key beginning with `gem` as reserved: a friend-challenge template refuses
-  a param named that way.
+  opens a friend challenge — but it is the platform's, not yours: read the challenge with
+  `gem.friends.launchedChallenge()`, never from the URL. Do not define a key of that name, and
+  treat every key beginning with `gem` as reserved: a friend-challenge template refuses a param
+  named that way.
 - **Bounded.** At most 16 parameters. A key is a letter followed by up to 63 letters, digits,
   `_` or `-`. A value is at most 512 characters with no control or format characters. An entry
   that breaks a rule is dropped on its own; the rest of the link still arrives.

package/docs/manifest.json

@@ -8,8 +8,8 @@
   "documents": [
     {
       "file": "achievements.md",
-      "sha256": "e67bc5d0e6abd9ff842be46fa82bf5117fce74b2eb9d28a3954919ddc8a11c73",
-      "updated": "2026-10-02T23:09:37Z"
+      "sha256": "adc8bfaa769fbb283a53de1190ed85cdf4c1c9753e8cf78335b4595e98f8fad4",
+      "updated": "2026-10-06T22:14:30Z"
     },
     {
       "file": "analytics.md",
@@ -33,13 +33,13 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "8a2e021addc2980433e722ba6ca2c7f5fa81cb8eac921e0bda28e44e3484d09d",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "f13808374edf0988e0aef58b857c82298702a67d450962522a532b4827b74c91",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "cross-promotion.md",
-      "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
-      "updated": "2026-09-29T17:32:40Z"
+      "sha256": "289cb4826a56b4e7423160e4187af65f4167c80218c2792ca0c01fbd977ecfec",
+      "updated": "2026-10-06T18:49:36Z"
     },
     {
       "file": "daily-challenges.md",
@@ -58,8 +58,8 @@
     },
     {
       "file": "friends.md",
-      "sha256": "1c0a427a4e86d4c0e48faad9a80bdef9d528a60485b5aadee18d7759d9051e63",
-      "updated": "2026-10-01T16:38:53Z"
+      "sha256": "002e6f61050cd188baa0b9b056c9ceaccd96e653361e0c28646baa5632e525df",
+      "updated": "2026-10-06T16:37:15Z"
     },
     {
       "file": "game-economy-tutorial.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "3c38e5b14c78b70b107d5e5b5499fa9340975d602642a8eb91f2dd969d1b605b",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "222dcf81a2ed6d8fc8ffc37d5f7ef146dcf80c4b76f84fd9b8dd53ea1cbce23b",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,33 +113,38 @@
     },
     {
       "file": "saving-player-progress.md",
-      "sha256": "e556b9ef033b0ae611a7d136da3422c8145367939848eda193ab2674087c884f",
-      "updated": "2026-10-01T18:37:21Z"
+      "sha256": "08778cccc7d7a9a26a005a070bb2cc98784752ebec9dfce9873ef3d4e674e1e0",
+      "updated": "2026-10-05T16:53:25Z"
     },
     {
       "file": "server-bundles.md",
-      "sha256": "13f5846ad8ee3d27e83916b8d95b4d3fdfcbeb85f94e095cc0c04e14dc2577b2",
-      "updated": "2026-10-05T17:22:40Z"
+      "sha256": "ffc7ec338f3436f73b16f8ba92a54de93e55bd5e9adbe562647e27b4867e4619",
+      "updated": "2026-10-07T16:20:42Z"
     },
     {
       "file": "serverless-functions-js.md",
-      "sha256": "86b0f9f0b742a662ebb78b1538cbbc399309725faf22f46f613b63b5e0864082",
-      "updated": "2026-10-02T17:17:29Z"
+      "sha256": "8d5bda66dfebd93e80fe97b2f09c0651c26dc83b16827bdae7aa25f198f89e0b",
+      "updated": "2026-10-03T00:26:43Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "c830daf736713744909700bf93ff5ba139b8b5d8ad3c2b4e057ca813fc6179f7",
-      "updated": "2026-10-02T18:52:17Z"
+      "sha256": "1edaa60a8aaf20499f24d661f169790cacfdb11c26529735a93e5b7b996e5432",
+      "updated": "2026-10-03T00:26:43Z"
     },
     {
       "file": "trading-and-gifting.md",
       "sha256": "d7ee3c85540ab8aae29988c16a76bee3ba03cc66b10d2faaf5cd7210a80a0544",
       "updated": "2026-08-26T03:27:49Z"
     },
+    {
+      "file": "vibration.md",
+      "sha256": "3608da64abcef207cf0875f9d32f3aed88d4fb23512bc70d0a9684a570263a44",
+      "updated": "2026-10-06T17:36:25Z"
+    },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "f44c1fd73678b1b569c59bc94bb55cfa2bdb957d798f5985ea5b3024865ed4a6",
-      "updated": "2026-10-04T19:51:47Z"
+      "sha256": "3d3ed15c93368a03b11c0e4e1924797e2638aff5be264a799a259ee065d2dbfc",
+      "updated": "2026-10-06T23:08:59Z"
     }
   ]
 }

package/docs/saving-player-progress.md

@@ -436,6 +436,47 @@ game, and a key you experiment with on `dev` cannot break a shipped build.
 | a difficulty, a control scheme, a level counter | `gem.me.settings` — a string per key | yes |
 | a volume, a quality preset, a dismissed tip | `gem.deviceSettings` — one object per device | **no** |
 
+## Starting over as a new player while you test
+
+Testing a first launch, a tutorial or a new player's economy means getting your own account
+back to nothing on your game. Do not write code for it. A throwaway serverless function, or a
+reset button you mean to remove later, is the workaround this replaces. gemctl does it, on
+`dev` or `test`, for the account you are signed in as:
+
+```bash
+gemctl support reset --player me --channel dev --reason "fresh tutorial run"
+```
+
+`--channel test` works the same way. `--reason` is required and is kept on the audit record, so
+say why in a few words, with no personal data or tokens. Run it from your project's directory,
+or add `--game <game-id>`.
+
+The order matters, and two of the steps are the ones people skip:
+
+1. **Close the game first.** A running game still holds the old state, and its next autosave
+   writes it straight back over the reset.
+2. **Run the reset.**
+3. **Clear the site data of the page the game runs in, with the game still closed.** That is
+   the Arcade, or the page `gemctl serve` opened, not the game's own origin. `gem.deviceSettings`
+   lives in that page's storage on this device, and no reset reaches it. Skip this and the old
+   volume, quality and dismissed tips come back. Clearing the Arcade's site data also signs you
+   out of it and clears the device settings of every game you have played there on this device;
+   the page `gemctl serve` opened holds only the game you are serving.
+4. **Reopen the game.** It should see what a new player sees: `null` from
+   `gem.me.saves.get`, an empty `gem.me.settings.list()`, and `null` device settings.
+
+The reset clears this player's state **in this game, on that one channel**: saves,
+`gem.me.settings`, inventory and progressions, and the rest of what the game keeps for them.
+It does not touch your other channels, your other games, achievements, or your Gems and
+Tickets. Your purchases and what you paid stay on record, but an item a purchase delivered on
+that channel is cleared with the rest, and the answer lists those purchases.
+`gemctl support reset --help` has the full list, and the answer names whatever it left alone.
+
+**It never runs on `release`.** gemctl refuses before sending anything, and so does the
+platform. It is a tool for testing your own game, not something a game ships. A "New game" or
+"Reset progress" button for players is game code: it overwrites or clears the player's slots
+with `gem.me.saves` and their keys with `gem.me.settings`, as described above.
+
 ## What the platform already does with these, so you do not
 
 **A player's erasure covers their saves.** When an account is erased the stored payloads go with

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v7.9.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v7.9.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v8.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/serverless-functions-js.md

@@ -33,8 +33,9 @@ message and the stack go to the platform's log for the invocation, never to the
 `handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
 
 **`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
-`error`); `console.log` and every other method log at `info`. As with a component's `log`, nothing
-reads it back to you: the invocation id is what you quote about one call.
+`error`); `console.log` and every other method log at `info`. As with a component's `log`,
+`gemctl function logs` reads it back for a call on `dev`, and a call on `test` or `release` keeps
+no line.
 
 ## 2. Writing one
 

package/docs/serverless-functions.md

@@ -81,7 +81,7 @@ everything a function can reach:
 | `call-api`      | One request to the platform API, made **as your game's server**: a method, a `/v1/` path and a JSON body, and nothing else |
 | `download-link` | A save's contents, fetched from the download link the save's record carries                                                |
 | `upload-link`   | A save's new contents, sent to the upload link the platform issued for them                                                |
-| `log`           | A line kept on the platform under this call's invocation id, cut at 1 KiB                                                  |
+| `log`           | A line kept 24 hours under this call's invocation id, on `dev` only, cut at 1 KiB                                          |
 | `random-bytes`  | Randomness. The function has no other source                                                                               |
 | `now-ms`        | Unix time in milliseconds. The function has no other clock                                                                 |
 
@@ -120,9 +120,9 @@ Anything that changes several players at once — settling a match, trading betw
 granting a whole room its rewards — is your **game server's** job, or the job of a function your
 server calls, which is not bound to a player.
 
-**`log` is not a debugger.** What it writes stays on the platform under the call's invocation id,
-and no command reads it back to you. The invocation id is what you quote when you ask the platform
-team about one call.
+**`gemctl function logs` reads back what `log` wrote** (section 7), with a line saying how each
+call ended — but only for a call on `dev`, and only for 24 hours. A call on `test` or `release`
+keeps no line, so to see what a tester or a player hit, make the same call on `dev`.
 
 **A function cannot call a function.** `call-api` to `/v1/functions/invoke` is refused with
 `function_cannot_invoke`.
@@ -732,8 +732,10 @@ It reports:
 - `function_message`: your `Err` text, on a `function_error`;
 - `reason`: on a `function_failed`, which limit or fault ended the call;
 - `round_trip_ms`: measured by gemctl, from sending the call to the last byte back;
-- `invocation_id`: what the platform files the call under. **Keep it.** It is the only handle on
-  the platform's side of one call, including whatever the function passed to `log`.
+- `invocation_id`: what the platform files the call under. **Keep it.** It is what you pass to
+  `--invocation-id` to read that call's lines, and what you quote when you report the call;
+- `logs`: on a `test` or `release` call that reached your function, that it left no log lines. A
+  `dev` call that reached it prints the `gemctl function logs` command that reads its lines instead.
 
 Anything but `returned` exits 1.
 
@@ -744,6 +746,48 @@ If the call is refused before anything is invoked, the problem is your sign-in:
 be a developer on the game, `test` needs a grant on it, and `release` needs a game your account may
 play.
 
+### Reading what it logged
+
+`gemctl function logs` reads what your function wrote with `log`, newest first, with one closing
+line per call saying how it ended.
+
+```bash
+gemctl function logs --invocation-id <invocation-id>   # one call: what it logged, how it ended
+gemctl function logs --outcome error                   # every call whose handle returned Err
+gemctl function logs --level warn                      # what your function warned about
+```
+
+⚠️ **Only a call on `dev` leaves lines.** A call on `test` or `release` leaves none, so there is
+no channel to choose and nothing here shows what a tester or a player hit. Make the same call on
+`dev`, with the input that failed, and read that.
+
+Each row is one of two kinds, and both carry the call's `invocation_id` and its `caller`, `player`
+or `game_server`:
+
+- **A line your function logged**: its `level` and its `message`.
+- **The closing line**: `outcome` is `ok`, `error`, `timeout`, `cpu_exceeded` or `failed`, with the
+  call's `wall_ms` and `cpu_ms`. On `error`, `message` is your `Err` text. On `failed`, `reason`
+  says what ended the call, and when your own code trapped, `message` is the trap's message.
+
+Newest first means a call's closing line comes before what it logged. **A call's logging is
+capped**: once it reaches its per-call log limit, that `log` call and every later one go
+unrecorded, and the closing line's `dropped_log_lines` says how many. A log that stops part-way
+with a nonzero count means your function logged too much, not that it went quiet.
+
+`--invocation-id`, `--level` (`debug`, `info`, `warn` or `error`) and `--outcome` narrow the page.
+`--level` picks what your function logged and `--outcome` picks closing lines, so the two cannot be
+combined: to see everything a failed call logged, pass its invocation id. The window is the last 24
+hours unless `--start-ns` and `--end-ns` (Unix nanoseconds) narrow it, and a full page ends with a
+hint carrying `--cursor` for the next, older one. There is no follow mode.
+
+**An empty page does not prove your function was not called.** Lines take a few seconds to arrive
+and are kept for 24 hours. A call the platform refused before your function ran leaves none — a bad
+credential, a malformed request, a channel serving nothing, a full pool, a component that could not
+be downloaded — and its `invoke` answer is its only record.
+
+Every `message` was written by your function's code, and any member of your game's team can read
+it. Log ids, not anything personal about a player.
+
 ## 8. When a call is refused
 
 Every answer from a call that reached your function carries an invocation id: success,
@@ -766,7 +810,9 @@ the last column: it is `true` exactly where this table says to retry.
 | `403 forbidden`                                            | The call carried an account sign-in rather than a game-scoped or game-server token                        | Call from your game or its server, or through `gemctl function invoke` |
 
 A `trap` is a panic, an `unreachable`, an out-of-bounds access or a stack overflow, and no stack
-trace comes back with it. The other three reasons are the limits in section 2.
+trace comes back with it. On `dev`, the call's closing line in `gemctl function logs` carries the
+trap's message when your own code trapped (section 7). The other three reasons are the limits in
+section 2.
 
 Publishing has its own refusals, and nothing is stored when one happens: