@indiegems/gem-web-sdk 7.4.0 → 7.4.1

package/docs/daily-challenges.md

@@ -0,0 +1,530 @@
+# Daily challenges
+
+Games do not have to have dailies. This is a capability, not an obligation — but if your game has
+something a player could finish today and finish again tomorrow, the platform can hold that state,
+count the streak, put a marker on your game's card in the arcade so a player scanning the catalog
+sees there is something waiting in it, and — if you want it to — **pay the player for finishing**.
+
+**A daily challenge is a progression.** Not a new kind of object, not its own config section:
+a progression that repeats on a known period and asks to be shown. Everything you already know
+about progressions applies, including rewards, and
+[inventory-and-catalogs.md](inventory-and-catalogs.md) is still where progressions are explained.
+
+> **Not friend challenges.** A daily challenge is one every player gets from your game. A player
+> sending one friend a challenge from your game — "beat my score" — is a different feature with a
+> different name, and [friends.md](friends.md#friend-challenges) covers it. Players see the words
+> "Friend challenges" for that one, never a bare "Challenges", which already heads the Arcade's
+> section for dailies.
+
+## 1. Is this the mechanism you want
+
+| You want                                                | Use                                  | Because                                        |
+| ------------------------------------------------------- | ------------------------------------ | ---------------------------------------------- |
+| "Clear 10 piles today", shown in the arcade, streaked   | `daily` + `platform_display: challenge` | yesterday survives; a missed day is not a zero |
+| The same, and it pays the player                        | the same, plus rewards ([section 5](#5-paying-for-a-challenge)) | a challenge pays like any other progression |
+| A season track, a battle pass                           | an ordinary progression              | it accumulates; it does not reset              |
+| An internal counter you do not want shown               | `daily`, no `platform_display`        | the platform stores it and displays nothing    |
+
+There is no longer a choice to make between "a challenge" and "a progression that pays". **Every
+progression keeps the same state and the same reward machinery whatever its schedule.** The
+schedule decides when its value resets; `platform_display: challenge` decides whether the arcade
+shows it, keeps a per-period history for it and counts a streak from it. The two are independent.
+
+> If you have read an older version of this page, or a config with three extra `cron` progressions
+> beside a challenge to carry its rewards: that workaround is obsolete, and the refusals that
+> forced it are gone. Declare the rewards on the challenge.
+
+## 2. Declare it in your game config
+
+Two fields on an ordinary progression:
+
+```yaml
+progressions:
+  - id: 4f2a9c71-3e8b-4d15-9a62-7c0e5b1d8f43
+    slug: clear-ten-piles
+    display_name: 'Clear ten piles'
+    description: 'Clear ten piles in a single run.'
+    config:
+      completion_threshold: 10
+      reset_schedule: { type: daily } # daily | weekly | monthly
+      platform_display: challenge # none (the default) | challenge
+```
+
+`reset_schedule` is the whole of the scheduling — there is no cron expression to write. A day runs
+from **each player's own midnight** to the next, a week from their Monday, a month from their 1st.
+`platform_display: challenge` is what makes it the arcade's business rather than only yours; the
+default is `none`, and a progression on a daily schedule that says nothing appears on no platform
+surface at all.
+
+Two optional keys on the schedule move that boundary, and most games need neither:
+
+```yaml
+reset_schedule: { type: daily, boundary: UTC, reset_time: '04:00' }
+```
+
+- **`boundary`** — `local`, the default, is each player's own time zone. An IANA zone name such as
+  `UTC` or `Asia/Tokyo` puts every player on that one calendar instead, so everybody's day turns
+  over at the same instant: what a daily leaderboard, or a server that works out "today" for
+  itself, needs.
+- **`reset_time`** — the clock time, `HH:MM` in that zone, at which a period begins. The default is
+  `00:00`; `'04:00'` lets a late-night player finish the day they started. Quote it: some YAML
+  parsers read an unquoted `04:00` as a number.
+
+Changing only these two is not a change of schedule, so the upload does not refuse it
+([section 7](#7-an-id-is-permanent-and-so-is-its-schedule)).
+
+`completion_threshold` is the target. `client_writable` decides who may report it, and
+[section 4](#4-who-may-report-it) is where that choice actually matters.
+
+**Upload the config the way you upload any other.** A challenge is not promoted differently and
+does not need a new build to reach players.
+
+## 3. Report progress from your game
+
+The write is the ordinary progression write. Your game already knows how to make it:
+
+```js
+await gem.me.mutations.addProgression('clear-ten-piles', 1); // a counter
+await gem.me.mutations.maxProgression('best-depth-today', 7); // a record
+```
+
+`addProgression` accumulates and `maxProgression` keeps the best, exactly as they do for any other
+progression. The platform routes the write to the current period on its own — your game does not
+name a period, compute one, or pass a date — and the ordinary progression read returns what you
+wrote:
+
+```js
+await gem.me.mutations.addProgression('clear-ten-piles', 10);
+const row = await gem.me.progressions.get('clear-ten-piles');
+// { currentValue: 10, isCompleted: true, completionCount: 1 }
+```
+
+**The value you read is this period's, and it resets when the period does** — without your game
+doing anything, and whether or not the player plays. A read taken after the boundary reports zero
+for a player who has not started today, so do not cache the value across `periodEndsAt`
+([section 6](#6-a-period-is-the-players-own-day-the-platform-says-where-it-ends-and-it-picks-the-subject)).
+
+`completionCount` is the exception: it counts completions over the progression's whole life, so it
+is how many days the player has finished this challenge, not how many times today.
+
+## 4. Who may report it
+
+`client_writable` decides whether the browser may make that write or whether it must come from your
+game's server or your serverless function.
+
+A browser credential is public. A `client_writable` challenge is therefore **forgeable**: a player
+can complete today's challenge without playing. For a challenge that only moves a marker and a
+streak, that is an acceptable trade and the platform accepts it.
+
+⚠️ **A progression that carries `platform_grants` may not be `client_writable`, and the upload
+refuses the combination.** The platform grants on your game SERVER's or serverless FUNCTION's
+say-so, never a browser's. So a challenge that pays platform currency is server- or
+function-reported, necessarily. A function pays only from a progression that opts in
+(`function_may_grant: true`), only the player who called it, and once per call — Gems included,
+so a daily that pays Gems needs no dedicated server
+([serverless-functions.md](serverless-functions.md#paying-the-player-who-called)).
+
+**Choose server-reported when the challenge is a claim about skill you intend to stand behind** — a
+leaderboard-adjacent "beat this in under a minute" — and client-reported when it is a nudge to play.
+If your game has no server, a serverless function can report it: the game calls the function when
+the player finishes, and the function checks the claim and writes the progression. A `daily` reset
+with an `on_complete` mapping is also what makes the function pay once per day, whatever the input
+says. For a challenge that pays nothing, client-reported is a reasonable place to be.
+
+## 5. Paying for a challenge
+
+A challenge pays exactly as any other progression does, through the same two fields:
+
+- **`rewards_on_complete`** — operations run in your game's own inventory each time the challenge
+  is completed: your currency, an item, an unlock.
+- **`platform_grants`** — a mapping onto a **platform** currency, which the platform mints into the
+  player's arcade balance.
+
+A worked daily that pays fifteen Gems and a hundred of your own currency:
+
+```yaml
+progressions:
+  - id: 4f2a9c71-3e8b-4d15-9a62-7c0e5b1d8f43
+    slug: clear-ten-piles
+    display_name: 'Clear ten piles'
+    config:
+      completion_threshold: 10
+      reset_schedule: { type: daily }
+      platform_display: challenge
+      client_writable: false # required by platform_grants, and the default
+      rewards_on_complete:
+        - type: currency_grant # your game's own currency, by id
+          currency_id: 7b1d6c2e-5a4f-4e3b-9c8d-2f1e0a9b8c7d
+          amount: 100
+      platform_grants:
+        - mode: on_complete
+          amount: 15
+          target: { platform_currency_slug: GEMS }
+```
+
+It pays **once per completion**, and the period is what makes the next completion possible: finish
+today, get paid; finish again tomorrow, get paid again; finish twice today, paid once. Your game
+server can deliberately re-arm a completion — a `progressionSet` below the threshold, or a
+`progressionReset` — and the next completion pays again. That is by design and it is your game's
+decision; the platform's own ceilings are what bound it.
+
+Four things to know before you ship one:
+
+- **The platform sets the caps; your game sets only `amount`.** Every cap on a platform currency
+  is the platform's, set per currency: what one firing may grant, what one game may grant a player
+  per window, and what all games together may grant a player per day of their own calendar (the
+  **daily maximum**) — and a player's Boost raises them for that player. A firing
+  that would go over is **trimmed to what is left**, for every platform currency: a player 50 short
+  of the daily maximum who finishes a daily granting 200 is granted 50, and once the day is spent a
+  firing grants 0. The receipt reads `clamped`, names the ceiling (`platform_max_per_window`), and
+  its `granted` is what actually landed. When the player reaches the daily maximum, **the arcade
+  tells them** — in its own chrome, with when more arrives — and that notice is never relayed into
+  your game. To show the player how much more they can earn today, and when more arrives, read
+  `gem.platform.earnAllowance.get()`
+  ([Showing how much more a player can earn](inventory-and-catalogs.md#showing-how-much-more-a-player-can-earn))
+  rather than finding out from a `clamped` receipt — for display only, never to decide whether to
+  grant. The numbers are
+  platform policy and can change without a release of this SDK; `gemctl platform config` shows
+  the current ones. A `max_per_window` (or the older `max_per_entity`) on a mapping is accepted,
+  ignored, and warned about with `platform_grant_max_per_window_ignored`, so leave it out.
+- **Platform grants fire on every channel — `dev`, `test` and `release` — from a game server or
+  a serverless function.** On `dev` and `test` that includes a server you run yourself with a
+  developer-minted token (what `gemctl serve` hands a local server), so a Gems-paying daily can be
+  tested end to end on your own machine; a developer-minted token never reaches `release`. A
+  function the player called pays on every channel too, that player only, from an opted-in
+  progression. The receipt reads `fired` or `clamped` the same on every
+  channel.
+- **There is one wallet, so a test payout is real.** Gems paid while you test on `dev` land in the
+  player's real balance and spend the same per-window allowance, and the same platform ceilings, a
+  released game spends. Nothing resets that allowance. It is kept per player, per currency and per
+  game, so once you exhaust it, wait for the window to turn over or test with another account.
+- **The allowance runs on the player's own days, and a daily counts on its own date.** The allowance's
+  day is a date on the player's own calendar, in the time zone the platform holds for them
+  (UTC when it holds none), and it refills at their midnight. Against your game's cap, a daily's
+  grant counts on the daily's own date, wherever in the player's day it fires, and any other
+  grant — a weekly's, a monthly's, a cron's — on the date the player is on when it fires. Against
+  the daily maximum, every grant counts on the date the player is on when it lands. So the
+  allowance refills when the daily resets for a daily on the player's own calendar with the default
+  `reset_time`; with a later `reset_time`, or a `boundary` that fixes one zone, the card's "resets
+  in" is not in general when the allowance refills. Each date's allowance is spent once, whatever
+  the player does to their time zone.
+
+**When a completion pays a platform currency, show it where it happened.** The arcade draws the
+player's Gems and Tickets in its own chrome, and without a cue a payout lands there silently, in a
+corner the player is not looking at. At the moment your game shows the challenge complete, call
+`gem.cueReward` with the currency that paid (`GEMS` or `ARCADE_TICKETS`) and the centre of its icon
+beside the payout on your completion screen, and the payout flies from there into the wallet:
+[inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).
+**If it returns `false`, do nothing** — no celebration of your own, no counter, no flight;
+platform-currency display belongs to the arcade, and a game not connected to it shows no
+platform-currency amount at all.
+
+**Cue every payout the same way, at the daily maximum too.** Do not predict a payout's outcome from
+anything you hold. To show the player how much more your game can still pay today, read
+[the earn allowance](inventory-and-catalogs.md#showing-how-much-more-a-player-can-earn) — display
+only, never a gate: grant anyway and let the receipt say what landed. When a payout is trimmed or
+pays nothing because the maximum is reached, the arcade lands what did fit and shows the player
+that the daily max is reached and when more arrives; the notice is the player's and is never relayed
+into your game. To draw the currency on your completion screen, use the platform's art — the icon
+beside the amount, the hero only when the currency is the subject of a reward presentation:
+[brand-art.md](brand-art.md). Which currencies your daily may pay is `gemctl platform config`'s
+answer, and what each is for is [arcade-economy.md](arcade-economy.md).
+
+## 5a. Use `daily`, `weekly` or `monthly`. Avoid cron for a challenge.
+
+`daily`, `weekly` and `monthly` are **calendar periods** — a day, a week from Monday, a month from
+the 1st — on each player's own calendar unless you fix a zone ([section 2](#2-declare-it-in-your-game-config)).
+The upload stores the expressions `0 0 * * *`, `0 0 * * 1` and `0 0 1 * *` as those named kinds. A
+progression may also carry any other cron expression, and a challenge may too, but for a challenge
+you almost certainly do not want to:
+
+|                              | `daily` / `weekly` / `monthly`               | a custom cron                            |
+| ---------------------------- | --------------------------------------------- | ---------------------------------------- |
+| Whose clock                  | the player's own, or the zone you fix         | one UTC clock for every player           |
+| Storefront marker, My Games  | yes                                           | yes                                      |
+| Rewards, platform grants     | yes                                           | yes                                      |
+| The platform-wide **streak** | yes                                           | **no** — a streak of its own, on your store page |
+| The player's history calendar| yes                                           | no                                       |
+| Label in the arcade          | localised in every language the arcade speaks | generic                                  |
+| Period length                | a day, a week, a month                        | must be between **1 and 31 days**        |
+
+A streak spans games, which only works when every game agrees on what the player's "today" is. A
+custom cron period is yours alone and cannot be compared with anything, so a cron challenge is
+**game-local**: it shows progress, pays and keeps its own streak, and it never joins the
+platform-wide streak or a history.
+
+**If you wrote `0 0 * * *`, write `daily`.** The upload stores it as `daily` either way — which puts
+it on each player's own calendar, not on UTC midnight. Reach for a custom cron only when the period
+genuinely cannot be a day, a week or a month — and expect the arcade to say less about it.
+
+All displayed cron challenges in one game must share one expression: they share one calendar on the
+card, and two expressions would count each other's challenges in the fraction.
+
+## 6. A period is the player's own day, the platform says where it ends, and it picks the subject
+
+**A daily is a date, and each player reaches it at their own reset.** With the default `boundary`,
+a player's day runs from midnight to midnight in the time zone the platform holds for them; a
+player it holds no zone for is on UTC. A config that fixes a zone puts everybody on that one
+calendar ([section 2](#2-declare-it-in-your-game-config)).
+
+Two consequences, and the second is the one that breaks code:
+
+- **Never derive the boundary from a clock.** The zone the platform holds for a player need not be
+  the device's, and a challenge may fix a zone or a reset time your game does not know. Ask the
+  platform where the current period ends; a game that computed it disagrees with the platform about
+  which day the player's progress lands in.
+- ⚠️ **Key a period on `periodLocalDate`, or on `seed` for a cron challenge — never on
+  `periodStartAt`.** Two players on the same date, playing the same board, have different start
+  instants when their zones differ, so a start instant used as a key splits one day's board into
+  many. Key on `periodLocalDate ?? seed`.
+
+### The one call that answers both
+
+```js
+const challenges = await gem.challenges.list();
+const today = challenges.find((c) => c.slug === 'clear-ten-piles');
+
+if (today?.seed) {
+  startBoard(boardFromSeed(today.seed)); // everyone playing today gets this board
+  scheduleRefresh(today.periodEndsAt); // Unix seconds — when this seed expires
+}
+```
+
+Find yours by `slug` or `id` rather than by position: a game that adds a weekly later gets a second
+entry, and `list()[0]` quietly becomes whichever one sorts first.
+
+`gem.challenges.list()` returns every challenge your config declares, for the period running now:
+
+| Field                           | What it is                                                            |
+| ------------------------------- | --------------------------------------------------------------------- |
+| `id`                            | the progression's id from your config — permanent, and what to key on |
+| `slug`                          | your slug, when you declared one                                      |
+| `window`                        | `daily`, `weekly`, `monthly` or `cron` — and the platform may add one |
+| `periodLocalDate`               | the period's date, `YYYY-MM-DD` — the day, the Monday, the 1st; absent for a cron challenge |
+| `periodStartAt`, `periodEndsAt` | this player's period bounds, in Unix seconds                          |
+| `boundary`, `resetTime`         | the calendar the challenge runs on — `local` or a zone name — and the `HH:MM` a period begins at |
+| `seed`                          | the subject selector for this challenge in this period                |
+| `data`, `dataHash`              | content your studio stored for this period, when it stored some — [below](#pre-generated-content-the-board-itself) |
+
+It carries **no progress and no streak**, but it is the player's own: a `local` challenge's bounds
+follow that player's time zone. Players on the same `periodLocalDate` get the same `seed` and the
+same content.
+
+⚠️ **Cache it per player, and the channel is part of the key.** The answer comes from the config
+assigned to _your caller's channel_, and a test channel can declare challenges the live one does
+not. A cache keyed on the game alone will hand your unreleased challenge's id and slug to live
+players. The key is `(game, channel, player, periodsBack)` and it is valid until `periodEndsAt` —
+never across channels, and never across players. That holds even though a challenge's `seed` and
+stored content are the same on every channel that shows it: _which_ challenges are in the list, and
+how each is declared, is the channel's config, and that is what the channel in the key protects.
+
+⚠️ **Do not send `periodStartAt` or `periodEndsAt` to other players.** For a `local` challenge they
+imply the player's UTC offset, which the platform never shows another player. Send
+`periodLocalDate`.
+
+**A counter challenge does not need this call.** "Clear 10 piles" is fully described by your config:
+declare it, report progress, done. This is for a challenge with a **subject** — "clear _today's_
+board" — which needs the two things a browser cannot produce.
+
+### The seed: one board for everybody
+
+`seed` is a short lowercase hex string. Feed it to your own generator and every player on that
+date gets the same puzzle, board, word or level — each when their own day begins:
+
+```js
+function boardFromSeed(seed) {
+  const rng = mulberry32(parseInt(seed.slice(0, 8), 16)); // your PRNG, your rules
+  return shuffle(DECK, rng);
+}
+```
+
+Four things to know, and the last one is a security property:
+
+- **It is a string on purpose.** JavaScript numbers are doubles, so parsing a 64-bit seed as one
+  loses its low bits and two clients rounding differently end up on different boards. Slice the
+  hex, or parse as much of it as your generator needs — do not `Number()` the whole thing.
+- **It expires at `periodEndsAt`, and the next period's is different.** That instant is the
+  platform's answer to "when does this stop being today" for this player; read again after it
+  rather than computing the next boundary. Clamp any timer you build from it — `Math.max(60_000, …)` — so a boundary your
+  game could not read becomes a slow retry rather than a tight loop.
+- **The same challenge has the same seed in every channel.** The channel is not part of what the
+  platform derives it from, so your dev channel shows you the live channel's board. Convenient for
+  testing; do not build channel-specific boards on it. Stored content is shared the same way —
+  [below](#pre-generated-content-the-board-itself).
+- **Treat the length as opaque** — take a prefix, never assume one. And an **empty** `seed` means
+  the platform sent something the SDK would not pass on: it is falsy, so `if (today?.seed)` is the
+  guard, and a challenge missing its period is left out of the list entirely rather than handed to
+  you with a made-up boundary.
+- **Past periods are one argument away.** `gem.challenges.list({ periodsBack: 1 })` is the previous
+  period, counted **per window** — so `1` is yesterday for a daily and last week for a weekly, not
+  "one day ago" for both. It reaches 400 periods back, which is what an "all my past boards" screen
+  or a reconciliation pass needs.
+- **Past periods are counted in the zone the player has now.** `periodsBack: 1` is the date before
+  this one; its bounds are computed in the player's current zone, so do not compare them with
+  bounds read before the player moved zones. Its `periodLocalDate` is still the date to key on.
+- ⚠️ **Comparing `periodEndsAt` against the device clock is the one place that clock still
+  matters** — and a wrong one costs you little: you read late and show yesterday's subject a while
+  longer. It cannot file a player's progress in the wrong period, because the platform decides that
+  from when the write arrives, not from anything your game sends.
+- ⚠️ **The seed is NOT a secret.** It is derived from public inputs and is entirely predictable —
+  its job is _agreement_, not secrecy. Anyone can compute the next one. Never authorize anything
+  with it, never use it where something must be unguessable, and remember that a player's client
+  holds it: if knowing today's board in advance would break your game, the subject has to come from
+  your own server instead.
+
+### Pre-generated content: the board itself
+
+A seed says _which_ board; your game still has to build it. When building it is expensive — a
+puzzle that must be proven solvable, say — or when your boards are hand-authored and you would
+rather not ship a new build for each one, your studio can **generate each period's content ahead of
+time and store it on the platform**. The platform then hands it to your game beside the seed:
+
+```js
+const today = (await gem.challenges.list()).find((c) => c.slug === 'daily-drop');
+
+const board = parseBoard(today?.data) ?? boardFromPool(today?.seed); // content first, then the fallback
+startBoard(board);
+```
+
+`data` is a string of up to 4,096 bytes — usually JSON — that your producer uploaded for this
+challenge and period. `dataHash` is 16 lowercase hex identifying it. The producer is your
+studio's CI job, a cron job, an agent or a developer running `gemctl challenges data push`; it is
+never your game, and a player or server token cannot write content.
+
+⚠️ **Content is not per channel.** It is stored once for the challenge and period, and served on
+**every channel whose assigned config displays that challenge** — and on no other. There is no
+separate `dev` copy to test and then promote: promoting a config that displays the challenge is
+what puts its content in front of that channel's players. So content you push to try out on `dev`
+is served on `release` as soon as the `release` config displays the same challenge id. To trial
+different content before release, declare the trial on `dev` under a **different challenge id**.
+What stays per channel is the player's standing — progress, streaks and completions — so a playtest
+on `dev` never touches anyone's `release` progress. (A platform payout is another matter: there is
+one wallet — [section 5](#5-paying-for-a-challenge).)
+
+Five rules:
+
+- ⚠️ **`data` may be absent, and your game must keep working when it is.** It is omitted — never
+  `''` — for any period your producer did not fill, and a producer's runway can run out. Keep the
+  seed path or a bundled pool as the fallback, and treat content you cannot parse as absent.
+- **It becomes readable when its period begins, not before.** A date's content is served to each
+  player from their own reset on that date; nothing your game can call returns it early. Past periods keep their content —
+  `list({ periodsBack: 1 })` returns yesterday's — for 400 days. Further back than that you get the
+  period and seed with no content, which for a weekly is about 57 periods and for a monthly about 13.
+- ⚠️ **It is not authority.** Every player in the period receives the same bytes, so content must
+  never hold anything a verifier relies on being secret — a puzzle's solution stays on your server.
+  The same rule as the seed, for the same reason.
+- ⚠️ **It must never hold personal data.** The platform stores it as an opaque string and cannot
+  check what is inside.
+- **The platform never parses it.** Its shape is your game's contract with itself. Version it
+  inside the payload if it will ever change.
+
+**Send `dataHash` and `periodLocalDate` with every result** your server checks — or `seed` for a cron
+challenge, which has no date. Your studio can correct the content of a period that is already
+running, and a client that read it before the correction keeps the old content for up to an hour;
+the hash is how your server tells which board a result was played on.
+
+#### Verifying a result against the content
+
+A server bundle reads the same list for a named player — `gem.challenges.list({ playerId })` — and
+checks a submitted result against the entry the client says it played:
+
+1. Read the current period and the one before it **for the player who sent the result**:
+   `gem.challenges.list({ playerId })` and `gem.challenges.list({ playerId, periodsBack: 1 })`. The
+   second is what accepts a result played just before the period rolled over. The player is
+   required because your server holds no player of its own: a read that names nobody is answered in
+   UTC, which is not the player's own period for a `local` challenge — a player east of UTC is
+   already on a date the UTC read has not reached. The player must play your game or be in it now;
+   anyone else is refused with `not_found`.
+2. Find that challenge in either read whose `periodLocalDate` (or, for a cron challenge, `seed`) and
+   `dataHash` both match what the client sent. **No match is a rejection** — never fall back to
+   validating against whichever board is current, which would score a player against content they
+   never saw.
+3. Validate the result against that entry's `data`.
+
+Never match on `periodStartAt`: it is the player's own instant, not the period's identity.
+
+## 7. An id is permanent, and so is its schedule
+
+A challenge's id is carried on every player's history for a long time, with nothing pointing back at
+your config to explain it. **Reusing an id for a different challenge silently merges two challenges
+into one history** and makes every number computed from it unexplainable — not wrong in a way that
+shows, just quietly meaningless.
+
+- **A new challenge gets a new id.** Always.
+- **To rename what the player sees, change `display_name`.** That is free and is not part of the
+  challenge's identity.
+- **Changing a progression's `reset_schedule` is refused at upload**, for the same reason: a daily
+  that becomes a weekly would carry its old id into a history that then describes two different
+  things. A different period means a new progression. (Rewriting `0 0 * * *` as `daily` is not a
+  change — they are the same schedule.)
+- **Changing `boundary` or `reset_time` is allowed**, and keeps the id and the history, but it
+  moves every player's current period at the instant you promote it. A player moved back to an
+  earlier date loses nothing. A player moved **forward** onto the next date loses the one they were
+  on if they had not finished it, and their streak with it. So promote the change when nobody's
+  date moves forward: a switch from `UTC` to `local` between 00:00 and 09:59 UTC, as close to 00:00
+  as you can, and from `local` to `UTC` between 12:00 and 23:59 UTC, as close to 12:00 as you can.
+
+## 8. Retuning the target mid-period is safe
+
+`completion_threshold` is snapshotted onto each player's row at their first progress in a period.
+Raising it later cannot un-complete a period a player already finished, and cannot rewrite a
+historical percentage.
+
+**Lowering it mid-period is safe too, and has a consequence worth knowing:** a player who already
+started that period keeps the target they started with. Two players in the same period can be
+working toward different numbers, and every platform surface shows each player their own. That is
+deliberate — the alternative rewrites history — but it will generate a support question the first
+time two friends compare.
+
+## 9. Streaks
+
+The platform counts consecutive periods in which a player completed **at least one** displayed
+challenge — in any game, not only yours — and keeps a longest-ever alongside the current one. Your
+game declares nothing to get this; it follows from the challenge.
+
+Three things to know before you build a mechanic on it:
+
+- **One completion is a day.** A player who finishes three of your challenges advances their streak
+  once, the same as a player who finishes one. A streak measures days the player showed up, not how
+  much a game offered.
+- **A streak is the platform's, and it is shown on platform surfaces.** Your game reports progress
+  and does not read the streak back — see below.
+- **Whether a player's streak is shown at all can depend on who they are.** Some players do not see
+  streak surfaces. Do not design a mechanic whose fairness depends on every player seeing one.
+
+Challenges on a custom cron are game-local: each keeps a streak of its own, shown on your game's
+store page, and none advances the platform-wide one ([section 5a](#5a-use-daily-weekly-or-monthly-avoid-cron-for-a-challenge)).
+
+**A streak counts the player's own days**, whatever calendar a challenge's period runs on: a
+challenge that fixes `boundary: UTC` still advances the streak on the day it is completed in the
+player's own time zone.
+
+## 10. What your game can read back
+
+**What the challenge IS — yes.** `gem.challenges.list()` gives you the period's date, its
+boundaries and the seed, for every challenge your config declares (section 6). That read carries no
+progress; its bounds are the player's own, and it is cheap, so you may call it freely. Your game
+server reads the same list for one player with `gem.challenges.list({ playerId })`
+([verifying a result](#verifying-a-result-against-the-content)).
+
+**How the player is doing in THIS period — yes**, through the ordinary progression read
+(section 3): `currentValue` and `isCompleted` are this period's, and reset with it.
+
+**Their per-period history and their streak — no.** There is no history read and no streak read in
+the SDK. The arcade is what displays those — the marker on your game's card, and the player's own
+progress, history and streak on platform surfaces. Your game does not have to render any of it.
+
+## 11. When an upload is refused
+
+| What you get                                       | What happened                                                   | What to do                                                          |
+| -------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `platform_grants: a mapped progression must not be client_writable` | you gave a paying challenge `client_writable: true` | report it from your game server or a serverless function, or drop the platform grant |
+| `platform_display: challenge requires a reset_schedule` | you asked to display a progression that never resets       | add `daily`, `weekly` or `monthly`                                   |
+| `needs a period of at least one day` / `at most 31 days` | a displayed challenge on a cron outside the bounds         | prefer `daily`, `weekly` or `monthly`                                |
+| `cron expression never fires`                      | an expression naming a date that does not exist (`0 0 30 2 *`)  | fix the expression                                                   |
+| `reset_schedule changed from … to …`               | you changed a live progression's period                         | use a NEW progression; `display_name` is what renames one            |
+| warning `platform_grant_max_per_window_ignored` (or `platform_grant_cap_uses_retired_max_per_entity`) | a mapping declares `max_per_window` (or `max_per_entity`) | nothing is refused and the upload succeeds; remove the key, because the platform sets the caps |
+
+Every refusal names the field and the reason. **Read the error rather than a list written down
+here** — the platform is what decides these, and this table is only as current as the day it was
+written.