@indiegems/gem-web-sdk 7.9.0 → 8.0.0

package/docs/changelog.md

@@ -16,6 +16,105 @@ 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.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.
+
+Nothing in this release asks anything of a game.
+
+## 7.9.0
+
+Upgrading from 7.8.1. Impact: required.
+
+### Must change
+
+- A link your game shares can no longer carry a parameter named build. The Arcade now reads that key for itself and removes it before your game starts, so the share request refuses it with a TypeError that names the key. Rename the parameter if your game shares one by that name.
+
+### Rebuild
+
+- GemCapability gained gameMenu, and the bridge's message lists and unions in both directions gained the two new menu messages. A switch that assumes it knows every GemCapability value must handle the new one. Other code that compiles today keeps compiling.
+
+### New capability
+
+- gem.setMenu adds to the Arcade's menu, the one control the Arcade keeps over a game in its top right corner. Give onSettings and the menu gains a settings entry that opens your own settings screen, and give items for up to four entries of your own, each with an id, a label you have already translated and an onSelect handler. Each call is the whole answer and replaces the last, so call it again when the entries change. It returns true when the Arcade was told. After awaitBridge has settled, draw a settings button of your own only when it returns false. The Arcade pauses your game while its menu is open and resumes it before your handler runs.
+
+## 7.8.1
+
+Upgrading from 7.8.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 7.8.0
+
+Upgrading from 7.7.0. Impact: recommended.
+
+### May stop
+
+- The SDK now stops accidental text selection, the long-press copy menu and the tap highlight across your game's document, so a game can drop its own rules for that. Your own style rules always win, and inputs, text areas and editable content stay typeable and selectable. Text a player could select and copy before no longer is, unless your own styles make it selectable. Pass selectableText as true to createGem only if your game is mostly text a player should be able to copy.
+
+### New capability
+
+- A room says whether it is self-hosted in selfHosted: its dedicated server runs on the machine of the player who created it, as it does in the Gem editor. The SDK asks for such a room on your behalf where the embedder hosts locally, and there is no option for a game to set. It is false on every room a player in the Arcade is in.
+
+## 7.7.0
+
+Upgrading from 7.6.0. Impact: required.
+
+### Must change
+
+- In the server API types, occurred_at on a leaderboard row and on an entity leaderboard row is now optional and may be null. Code that assumes it is always a number must handle it missing. LeaderboardResponse and EntityLeaderboardResponse are now written as the shared LeaderboardPeriodFields joined with their own fields, so every field they had is still there.
+
+### Rebuild
+
+- Server API unions gained values. OrderSource has earning_reset, and InventoryChange has a new earning_limits_reset change. A switch that assumes it knows every OrderSource value or every InventoryChange type must handle the new one. Other code that compiles today keeps compiling.
+- The server API reads getLeaderboard and getEntityLeaderboard accept three more options, periods_back, period and player_id, and the option types GetLeaderboardOptions and EntityLeaderboardOptions now extend the new PeriodOptions. Code that compiles today keeps compiling.
+
+### New capability
+
+- gem.leaderboards can read a board scoped to one period of a challenge, such as today's board or this week's. Every read takes periodsBack, where 0 is the current period and 1 is the one before, or period, the id of a period from an earlier result. Name at most one of them. A result from such a board carries period, which says which period it is, when it opens and closes, and whether it is final. A serverless function or a dedicated server passes playerId so the board answers for that player's own day. On a board that is not scoped to periods, both selectors are refused rather than ignored.
+
+## 7.6.0
+
+Upgrading from 7.5.0. Impact: required.
+
+### Must change
+
+- createGem now throws GemUnframedError when the page is opened on its own instead of inside a frame. Before, such a game constructed and then waited for a bridge that never came, with no player, no saves and no config. Run your game where it is framed and handed an identity: the Arcade, the Gem editor or the Gem dev host. A game that is only ever played there changes nothing. When the framing page is not one the game allows, the refusal is now final: awaitBridge, awaitIdentity, awaitPlayer and awaitCohorts answer at once instead of timing out.
+
+### New capability
+
+- A serverless function written in JavaScript can use the SDK through a new function entry of the package. createGem there returns the same platform-backed calls a browser game makes, bound to the player who called the function. Nothing is retried, a conditional save is refused before it is sent, and gem.functions and gem.gameConfig throw because a function has neither. This entry is in the package only.
+
 ## 7.5.0
 
 Upgrading from 7.4.2. Impact: required.

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.0"
+  "@indiegems/gem-web-sdk": "8.0.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:
 
@@ -365,9 +368,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

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "3398bf6f55c503520167dc9cfbee06da7f0552125a4b2050d7e508096c8e256f",
-      "updated": "2026-10-02T21:36:48Z"
+      "sha256": "37bae4170e89587ee8c498891fa2dac008f09fb01fcfbcf87b1310340d2cfc62",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "file": "cross-promotion.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": "63a367fdcf79abee6a7978057cb1b7065f0365cd6fa5a895cbd2b18f76d29701",
-      "updated": "2026-10-03T22:38:04Z"
+      "sha256": "77ce7b2223d18267ac3ca2f49e09481752539f2674910e2cb12832825c945000",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "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": "419a1587827f494f638f331571a6385f4de080efb062e83656a9d2c50ee3473b",
-      "updated": "2026-10-03T22:38:04Z"
+      "sha256": "49f51b37e969b6120d2df6cf6d2f33d2856c1602fd7504a7b308a9ea21c9b502",
+      "updated": "2026-10-06T19:43:21Z"
     },
     {
       "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": "e5d0e2622077d4e41d1f1786c834e6280356f525146193285d062c4209ac33bd",
-      "updated": "2026-10-03T22:11:20Z"
+      "sha256": "436a8b61c46a3de6c7d5db65293bdcd17426412742dffd21f976bf87d1418d88",
+      "updated": "2026-10-06T17:36:25Z"
     }
   ]
 }

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.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v7.9.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v8.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v8.0.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: