@xgamesfun/xcore 0.2.0 → 0.3.0

package/README.md

@@ -31,6 +31,7 @@ xcore add multiplayer ./my-game            # rooms players share (Godot's own mu
 xcore backend use custom ./my-game --url https://api.my-game.example   # only if it calls a backend you run
 xcore loot add ./my-game                   # only if it gets an economy (a Solana economy on loot)
 xcore add vouchers ./my-game               # its server pays results it checked from a grant, with its own key
+xcore review ./my-game                     # the security review: what a cheater gets (--live once published)
 xcore login && xcore publish ./my-game
 xcore embed add https://mygame.com ./my-game     # your own site may show it (an <iframe>)
 xcore domain add play.mygame.com ./my-game       # Creator or Scale: it plays at your own domain
@@ -191,6 +192,7 @@ has behind it, so the whole game runs before it is published:
 | `http://127.0.0.1:8787/game/` | the published files (it runs `page.build` first, unless `--no-build`), with the play host's headers                                                                                                                                                                                                                                                                                                                |
 | `/game/api/*`                 | the game's `server/` under workerd, the runtime xgames.fun runs it on: Durable Objects with their storage kept, WebSockets, `env.GF`, the game's database (a local D1 in `.gamesfun/dev/d1/`, its migrations applied), and its secrets from `.dev.vars`. A change under `server/` or to `.dev.vars` reloads it. Miniflare (with workerd, about 140 MB) is installed once, the first time a game with a server runs |
 | `/platform/v1/*`              | sign-in, saves and leaderboards: `gamesfun.js` signs in a local player (each tab its own, so two tabs play a room together), and `env.GF.verifyPlayer` accepts its token. Saves and scores are kept in `.gamesfun/dev-platform.json`, never published                                                                                                                                                              |
+| `/platform/v1/live`           | the game's live settings (`gf.live`, below): its announcement, config and maintenance, from `.gamesfun/live.json` (read again on each request, never published). With maintenance on there, the game's pages show the holding page and its `api/` and `/platform/v1/*` answer `503` with code `maintenance`, as hosted                                                                                             |
 | `http://127.0.0.1:8788/`      | the game's public project files (`env.GF.files`, `xcore files`), kept in `.gamesfun/dev/files/`: another origin, as `<slug>.xgamesusercontent.com` is to the published game                                                                                                                                                                                                                                        |
 | `/loot/v1/rpc`                | the economy's Solana devnet RPC: xgames.fun's shared relay (what a published page talks to unless the game brings its own: `xcore add rpc`), or your own with `XSOLANA_RPC_URL` in `.env` (its URL is never shown; a call the shared relay would refuse is said in the terminal). The economy's calls answer once it is live on devnet (`xcore loot approve`)                                                      |
 
@@ -217,6 +219,14 @@ each, 16 a player), leaderboards (submit, top, the player's own), the game's dat
 (`api`). Every call answers `{data, error, status}` and none throws, so a game plays on as a guest wherever xgames.fun is
 not there.
 
+**Full screen.** Most players meet a game in a post on X or on a phone, where it shows in a small frame first; `xcore
+adopt` warns when a game has no way to go full screen. A button that calls `GamesFun.fullscreen()` from the click
+(`await GamesFun.fullscreen()` in Godot; `Screen.fullScreen` in Unity) does it wherever the game is: in xgames.fun's
+play page the page around the game goes full screen (or fills the screen in an app's own browser, X's among them), on
+its own link the browser does, and in a frame that allows none (a post on X on a computer) the game opens in a tab of
+its own. It answers `{on, how: 'page' | 'browser' | 'tab' | 'none'}` (`none`: an iPhone's Safari, which has no full
+screen for a page); pressed again it comes back, and `GamesFun.onFullscreen(on => …)` follows every change.
+
 **A leaderboard is the player's own word until the server takes it.** A signed-in player submits their own scores
 from the page, so anyone can submit any score for themselves from the browser's console. A game with its own server
 makes a board nobody can write that way: `env.GF.scores.setup('ranked', {writer: 'server'})` (or a pattern for boards
@@ -246,6 +256,59 @@ published origin and under a folder alike), `init` is `fetch`'s (an object `body
 player's token goes with it as `Authorization: Bearer …`, which the server checks with `env.GF.verifyPlayer` before
 it trusts who is asking. It answers `{data, error, status}` like every other call.
 
+### Live: an announcement, a remote config and maintenance, with no republish (`gf.live`)
+
+On xgames.fun/console, a game's **Live** tab sets three things its players get within about 35 seconds, with no
+republish (xgames.fun's play edge answers them itself from one cached record a game):
+
+- **an announcement**: a short line of plain text (280 characters), `info` or `warning`, with an optional start and end;
+- **a remote config**: a small JSON object (8 KB) the game reads at run time: a difficulty, an event on or off. The
+  console keeps its last 10 versions and reverts with a click;
+- **maintenance**: the game paused with a message. Players who open it get a plain holding page from xgames.fun instead
+  of the game, its server's `api/*` (WebSockets too) and the page's saves and leaderboards answer `503` with code
+  `maintenance` (the server's code does not run), and turning it off brings the game back within about 35 seconds (up
+  to a minute). What is already running (an open WebSocket, an alarm) is not stopped.
+
+`gamesfun.js` (1.5.0) reads them:
+
+```js
+const { data: live } = await GamesFun.live.get(); // {announcement, config, version, maintenance}
+const hard = live.config.difficulty === 'hard';
+GamesFun.live.onChange(live => applyEvent(live.config.event)); // asked again every minute while the page is in view
+await GamesFun.live.refresh(); // ask now
+```
+
+`get()` answers what it knows if that is under a minute old, else asks; like every call it answers
+`{data, error, status}` and never throws (unreachable: the last value, else nothing live). `announcement` is null
+outside its start and end, `config` is `{}` when none is set, `maintenance` is null or `{message, since}`.
+
+**The banner.** By default `gamesfun.js` shows the announcement in a small closable line at the top of the page (each
+announcement until the player closes it), and a pause that starts while the game is open (any call answering
+`maintenance` shows it at once). A game that shows them its own way turns it off with `data-live-banner="off"` on its
+`<script src="gamesfun.js">`, `globalThis.GAMESFUN_LIVE_BANNER = false` before it loads, or
+`GamesFun.live.banner(false)` before the page has loaded. Without the banner and without `onChange`, nothing is asked
+until the game calls `get()`.
+
+**On this machine** nothing is live on a plain local server; under `xcore dev`, `.gamesfun/live.json` stands in for the
+console (read again on every request):
+
+```json
+{
+  "announcement": {
+    "text": "Double XP all weekend!",
+    "level": "info",
+    "startsAt": null,
+    "endsAt": "2026-11-12T00:00:00Z"
+  },
+  "config": { "difficulty": "hard", "event": true },
+  "maintenance": null
+}
+```
+
+`"maintenance": {"message": "Back at 7pm"}` (or `true`) pauses the game as hosted. Times are ms or ISO text; what the
+console would refuse (a config over 8 KB or not an object, an announcement over 280 characters) is said in the
+terminal. Godot and Unity reach `gf.live` only through their JavaScript bridge for now.
+
 ### A database of its own: `xcore add database`
 
 `xcore add database <folder>` adds sign-in, and a database the game owns: **one D1 database** (SQLite) a game, made on
@@ -460,6 +523,29 @@ only to players signed in with X (`VOUCHERS.payOnly`). A grant names up to three
 pay the same grant while you move from one to the other.
 [docs/SERVER.md](docs/SERVER.md), "Paying a result", has both, side by side.
 
+### Review: `xcore review`
+
+A game that pays is read the way a cheater reads it before players are paid. `xcore review <folder>` writes
+`evidence/review-N/review.md` and `review.json`, prints what it found, and exits 1 on any high finding:
+
+- **The economy**: `@xgamesfun/solana`'s own review (`xcore loot review`): each route that pays, what it trusts, its
+  ceiling, and the trade-offs in words. An installed version without it says so in one line, and the rest goes on.
+- **The server**: `PAY.check` still the template (it pays nothing) or one that pays from the request alone (it never
+  reads `env`, so nothing the server keeps); `VOUCHERS.payOnly` against the grants (`'any'` with `perPerson`, whose
+  claims fail; `'any'` on a grant worth farming); a voucher key and the grants that name it; `trust` on every grant a
+  voucher pays; `.dev.vars` in git or in the published folder; a seed or key in the page's files; the test key in a
+  grant; every `api/` route the code names.
+- **Live** (`--live`, after publishing; `--live <origin>` for another, such as `xcore dev`'s
+  `http://127.0.0.1:<port>/game/`): each of those routes asked with no sign-in and with a forged one, GET and POST (a
+  route that pays gets an empty body: nothing it sends can spend or sign); `api/vouchers/key` against the grants' keys;
+  the published economy's `live` against the folder's.
+
+Each grant a voucher pays says how much its server checks before signing: `"trust": "decides"`, `"replays"` or
+`"bounds"` (docs/SERVER.md, "How much your server can check"; the field needs the `@xgamesfun/solana` that has
+`review`: 0.25.0 refuses it). `review.md` ends with the trade-offs for the person: for each paid route, its level,
+what a cheater gets, and what the stronger level would cost. `xcore publish` says when a game that pays through
+vouchers changed since its last review (it never refuses for it).
+
 ## 5. Publish
 
 `xcore login` signs this computer in (your browser signs in to xgames.fun and hands it a publish token for 30
@@ -523,24 +609,28 @@ games. `GAMESFUN_STUDIO=<origin>` publishes to another xgames.fun (a Studio on y
 
 ### Its plan: `xcore plan`
 
-Hosting the page is free. What the game's server, saves and scores may use is the game's plan:
+Every game sits in a **slot**. Everyone gets **2 free slots**, whose games run on Free; any more games need a **paid
+slot** ($15 for 30 days), whose game runs on Creator. A new game is refused while both free slots are taken: archive one
+you no longer need (on your console, xgames.fun/console; unpublish it first) or move one to a paid slot. Archived games
+free their slot unless their link is still live. What the game's server, saves and scores may use is its plan:
 
-|                      | Free                                                               | Creator                                                   | Scale                   |
-| -------------------- | ------------------------------------------------------------------ | --------------------------------------------------------- | ----------------------- |
-| For                  | every game, by default                                             | a game in one of your paid game slots (per game, a month) | granted by xgames.fun   |
-| Server               | 50 ms of CPU a request; 600 requests a minute, 120 from one player | 200 ms; 6,000 a minute, 600 from one player               | 1,000 ms; 30,000, 1,200 |
-| Saves and scores     | 10 MB of saves; 8 boards of 10,000 entries                         | 1 GB; 16 boards of 1,000,000                              | 10 GB; 16 of 1,000,000  |
-| Use included a month | $1                                                                 | $10 a slot, shared by your Creator games                  | as granted              |
-| Sites that embed it  | 3 (`xcore embed`)                                                  | 10                                                        | 25                      |
-| Domains of your own  | none                                                               | 1 (`xcore domain`)                                        | 5                       |
+|                      | Free                                                               | Creator                                              | Scale                   |
+| -------------------- | ------------------------------------------------------------------ | ---------------------------------------------------- | ----------------------- |
+| For                  | a game in one of your 2 free slots                                 | a game in one of your paid slots (per game, a month) | granted by xgames.fun   |
+| Server               | 50 ms of CPU a request; 600 requests a minute, 120 from one player | 200 ms; 6,000 a minute, 600 from one player          | 1,000 ms; 30,000, 1,200 |
+| Saves and scores     | 10 MB of saves; 8 boards of 10,000 entries                         | 1 GB; 16 boards of 1,000,000                         | 10 GB; 16 of 1,000,000  |
+| Use included a month | $1                                                                 | $10 a slot, shared by your Creator games             | as granted              |
+| Sites that embed it  | 3 (`xcore embed`)                                                  | 10                                                   | 25                      |
+| Domains of your own  | none                                                               | 1 (`xcore domain`)                                   | 5                       |
 
 Past what is included, a game is **capped** until the month ends: its server answers at most 60 requests a minute (20
-from one player) and saves and scores slow down, but nothing is lost and the game keeps working. Slots are $15 for 30
-days, prepaid in SOL or USDC in xgames.fun Studio (Plans; no automatic renewal, 7 days' grace after the period ends).
+from one player) and saves and scores slow down, but nothing is lost and the game keeps working. Paid slots are $15 for
+30 days, prepaid in SOL or USDC on xgames.fun (your console → Plans; no automatic renewal, 7 days' grace after the period
+ends; when they end, their games go back to free slots and nothing is taken down).
 Usage credit, bought the same way, lets Creator games go past what their slots include, at twice what xgames.fun pays,
-instead of slowing down. A slot moves between your games at any time
+instead of slowing down. A paid slot moves between your games at any time
 (`xcore plan deactivate <one>`, `xcore plan activate <another>`) without changing the bill. `xcore plan [folder]`
-shows a game's plan, its limits and this month's use; `--all` your slots and every game. A game's server sees a 429
+shows a game's plan, its limits and this month's use; `--all` your free and paid slots and every game. A game's server sees a 429
 with `scope` (`"player"` or `"game"`) and `plan` when it goes past a rate.
 
 ### Your own site and your own domain: `xcore embed`, `xcore domain`
@@ -575,7 +665,7 @@ A game made with xcore 0.1.0 that has `server/database.js` (`xcore add database`
 without one needs none: the D1 database, `xcore db` and `xcore files` are new.
 
 1. **Run `xcore add database` again.** It brings `server/database.js` up to date (your `RULES` and `LIMITS` are
-   kept), with `gamesfun.js` (1.4.0) and the Godot or Unity glue, and lists each `dataOf(env)` call in `server/` that
+   kept), with `gamesfun.js` (1.6.0) and the Godot or Unity glue, and lists each `dataOf(env)` call in `server/` that
    needs an owner (step 3) as `file:line` with its change; `xcore publish` lists them again until each names its
    owner. On its first start the new `database.js` moves the documents to a table keyed by collection, owner and id,
    each under its owner. After that, do not roll the game back to a version with 0.1.0's `database.js`: its writes

package/commands/loot.mjs

@@ -9,10 +9,11 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { guard, parse, printJson } from '../lib/cli.mjs';
 import { resolveGame, shown } from '../lib/games.mjs';
-import { ECONOMY_FILE, solanaCommand } from '../lib/economy.mjs';
+import { ECONOMY_FILE, solanaCommand, solanaHas } from '../lib/economy.mjs';
 import { addLoot } from '../lib/publish/adopt.mjs';
 import { solanaRpc } from '../lib/solana-rpc.mjs';
 import { CMD } from '../lib/command.mjs';
+import { NO_REVIEW } from '../lib/review.mjs';
 
 const usage = `Usage: xcore loot <command> [options]
 
@@ -21,6 +22,8 @@ A game's economy on loot, one shared Solana program (devnet only until it is aud
   xcore loot add [game]            where the game's economy (${ECONOMY_FILE}) and its page client (gf/loot/) go, and the
                                    copy once the economy is there (a brought game: the folder its build copies as it is)
   xcore loot check|simulate|cost|explain [file]   refusals and warnings; where the money goes; what it costs; in words
+  xcore loot review [file]         what a cheater gets from each route that pays, and the trade-offs in words (xcore
+                                   review adds the game's server and, with --live, the published game)
   xcore loot approve [file]        in a game's folder: put its economy live, approved in your own wallet
   xcore loot help                  everything else xsolana does (its help says \`xsolana <command>\`: run each as
                                    \`xcore loot <command>\`)
@@ -35,7 +38,7 @@ copy: never edit it; publish brings it up to date). A brought game with a build
 copies as it is (gamesfun.json page.static), so every build carries them. It prints the next steps.`;
 
 /** xsolana's commands that read an economy file ([file], default xsolana.json). */
-const ON_FILE = new Set(['check', 'simulate', 'cost', 'explain', 'publish', 'status', 'approve']);
+const ON_FILE = new Set(['check', 'simulate', 'cost', 'explain', 'review', 'publish', 'status', 'approve']);
 
 export default {
   name: 'loot',
@@ -70,6 +73,11 @@ export default {
       );
       return 1;
     }
+    // an installed package from before `review`: what to do, instead of its help
+    if (args[0] === 'review' && !solanaHas('review')) {
+      console.error(`xcore: ${NO_REVIEW}.`);
+      return 1;
+    }
     // a game made before the file was named xsolana.json keeps loot.json: given to the command when it names no file
     const named = args.slice(1).some(a => a.endsWith('.json'));
     let rest =
@@ -99,9 +107,10 @@ export default {
 };
 
 /** xsolana's commands a person runs as `xcore loot <command>`. */
-const COMMANDS = 'guide|examples|check|simulate|cost|explain|publish|approve|status|connect|mcp|tool|version|help';
+const COMMANDS =
+  'guide|examples|check|simulate|cost|explain|review|publish|approve|status|connect|mcp|tool|version|help';
 /** Its tools an agent calls (xsolana_check …) that are also a command here. */
-const TOOLS = 'guide|examples|check|simulate|cost|explain|publish|status';
+const TOOLS = 'guide|examples|check|simulate|cost|explain|review|publish|status';
 
 /**
  * xsolana's text as xcore's: its pinned npx forms and its `xsolana <command>` become `xcore loot <command>`, and the

package/commands/plan.mjs

@@ -12,17 +12,18 @@ const usage = `Usage: xcore plan [dir] [--json]
 What a game's backend may use on xgames.fun (its server, saves and scores), and what it used this month.
   Free       every game, by default: a small server (50 ms of CPU a request, 600 requests a minute) and $1 of use a
              month; past that its server is capped (slow) until the month ends
-  Creator    a game in one of your paid game slots: 200 ms a request, 6,000 requests a minute, 1 GB of saves, and
-             $10 of use a month per slot, shared by your Creator games
+  Creator    a game in one of your paid slots: 200 ms a request, 6,000 requests a minute, 1 GB of saves, and
+             $10 of use a month per paid slot, shared by your Creator games
   Scale      granted by xgames.fun for a game that needs more
 Every plan lets sites of yours embed the game (Free 3, Creator 10, Scale 25: ${CMD} embed); Creator and Scale serve
 it on domains of your own (1 and 5: ${CMD} domain).
-A slot is $15 for 30 days, prepaid in SOL or USDC on xgames.fun (Studio → Plans; no automatic renewal), and moves
-between your games at any time without changing the bill. Usage credit, bought the same way, lets Creator games go
-past what their slots include (at twice what xgames.fun pays) instead of slowing down.
-  activate     put this folder's game in a free slot
-  deactivate   take it out (it goes back to Free and the slot is free for another game)
-  --all        your slots and every game's plan`;
+Every game sits in a slot. Everyone gets 2 free slots, whose games run on Free; any more games need a paid slot,
+$15 for 30 days, prepaid in SOL or USDC on xgames.fun (your console → Plans; no automatic renewal), whose game runs on
+Creator. A paid slot moves between your games at any time without changing the bill. Usage credit, bought the same way,
+lets Creator games go past what their slots include (at twice what xgames.fun pays) instead of slowing down.
+  activate     move this folder's game to a paid slot (its free slot opens for another game)
+  deactivate   move it back to a free slot (one must be open; its paid slot opens for another game)
+  --all        your free and paid slots and every game's plan`;
 
 export default {
   name: 'plan',
@@ -57,7 +58,9 @@ export default {
       const r = await setActive(dir, verb === 'activate').catch(e => {
         if (e?.status === 409)
           throw new Error(
-            `${e.message} Free one with ${CMD} plan deactivate <another game>, or buy a slot on xgames.fun (Studio → Plans, in SOL or USDC).`,
+            e.code === 'no-free-slot'
+              ? `${e.message} Archive a game you no longer need on your console (xgames.fun/console), or move another game to a paid slot.`
+              : `${e.message} Open one with ${CMD} plan deactivate <another game>, or buy a paid slot on xgames.fun (your console → Plans, in SOL or USDC).`,
           );
         return plain(e);
       });
@@ -66,11 +69,11 @@ export default {
         const what =
           verb === 'activate'
             ? r.changed
-              ? 'In a slot: Creator from its next request.'
-              : 'Already in a slot.'
+              ? 'In a paid slot: Creator from its next request; its free slot is open for another game.'
+              : 'Already in a paid slot.'
             : r.changed
-              ? 'Out of its slot: Free from its next request, and the slot is free.'
-              : 'It was not in a slot.';
+              ? 'Back in a free slot: Free from its next request, and its paid slot is open for another game.'
+              : 'It was not in a paid slot.';
         console.log(`${what}\n${describeGame(r)}`);
       }
       return 0;

package/commands/publish.mjs

@@ -8,6 +8,7 @@ import { studioOrigin } from '../lib/publish/client.mjs';
 import { gate } from '../lib/publish/gate.mjs';
 import { buildFailure, pageRoots, runBuild } from '../lib/publish/page.mjs';
 import { CMD } from '../lib/command.mjs';
+import { reviewNudge } from '../lib/review.mjs';
 
 const usage = `Usage: xcore publish [dir] [--draft] [--new] [--title <name>] [--status] [--check [--verify [--port <n>]]] [--json]
 
@@ -68,6 +69,9 @@ export function publishCommand({
         );
         const dir = await resolveGame(positionals[0]);
         const origin = studioOrigin();
+        // a game that pays results through vouchers, changed since its last security review: one line, never a refusal
+        const nudge = values.status || values.json ? null : reviewNudge(dir);
+        if (nudge) console.error(nudge);
         if (values.status) {
           const s = await publishStatus(dir, { origin });
           if (values.json) printJson(s);
@@ -132,6 +136,16 @@ export function publishCommand({
           newGame: values.new,
           title: values.title ?? null,
           progress: values.json ? () => {} : l => console.error(l),
+        }).catch(e => {
+          // A new game needs one of the account's 2 free slots (xgames.fun's words say so); name the commands that free one.
+          if (e?.code === 'no-free-slot')
+            throw Object.assign(
+              new Error(
+                `${e.message}\n  ${CMD} plan activate <another game's folder>   moves that game to a paid slot\n  ${CMD} plan --all   your slots and games; archive one on ${origin}/console`,
+              ),
+              { status: e.status, code: e.code },
+            );
+          throw e;
         });
         if (values.json) printJson(r);
         else

package/commands/review.mjs

@@ -0,0 +1,106 @@
+// `xcore review [game] [--live [origin]]`: the security review of a brought game (../lib/review.mjs): its economy by
+// @xgamesfun/solana's own review, its server and page by this package's reading, and with --live the published game
+// asked as a stranger. The record goes in <game>/evidence/review-N/; any high finding exits 1.
+import { guard, parse, printJson, UsageError } from '../lib/cli.mjs';
+import { resolveGame, shown } from '../lib/games.mjs';
+import { readLinks } from '../lib/publish/index.mjs';
+import { studioOrigin } from '../lib/publish/client.mjs';
+import { CMD } from '../lib/command.mjs';
+
+const usage = `Usage: xcore review [game] [--live [origin]] [--out <dir>] [--json]
+
+The security review of a game, read as a cheater would: what a script gets without playing, and what to fix first.
+  the economy  @xgamesfun/solana's own review of the economy file (each route that pays: what it trusts, its ceiling,
+               its findings, the trade-offs in words), when the installed one has it
+  the server   PAY.check written or still the template, or paying from the request alone; VOUCHERS.payOnly against
+               the grants; the voucher key and the grants that name it; "trust" on every grant a voucher pays;
+               .dev.vars in git or in the published folder; a seed or key in the page's files; every api/ route
+  --live       the published game asked as a stranger: each api/ route with no sign-in and with a forged one (GET
+               and POST; a route that pays gets an empty body, so nothing it sends can spend or sign);
+               api/vouchers/key against the grants' keys; the published economy's "live" against this folder's.
+               The origin defaults to the game's link from its last publish; under ${CMD} dev, give its address
+               (--live http://127.0.0.1:<port>/game/).
+  --out <dir>  where the record goes (default: <game>/evidence/review-N/: review.md and review.json)
+  --json       the record as JSON
+review.md ends with the trade-offs for the person: for each route that pays, how the server checks it (decides,
+replays or bounds), what a cheater gets, and what the stronger level would cost. Any high finding exits 1.
+docs/SERVER.md, "How much your server can check", is the guide.`;
+
+/** --live takes an origin or nothing: `--live`, `--live <http…>`, `--live=<http…>`. → {args without it, live} */
+export function liveFlag(args) {
+  const rest = [];
+  let live = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--live') {
+      live = true;
+      if (/^https?:\/\//i.test(args[i + 1] ?? '')) live = args[++i];
+    } else if (a.startsWith('--live=')) live = a.slice('--live='.length) || true;
+    else rest.push(a);
+  }
+  return { rest, live };
+}
+
+export default {
+  name: 'review',
+  summary: 'the security review: what a cheater gets from its economy and server, with --live the published game',
+  usage,
+  run: args =>
+    guard(async () => {
+      const { rest, live } = liveFlag(args);
+      const { values, positionals } = parse(rest, { out: { type: 'string' } }, usage);
+      const dir = await resolveGame(positionals[0]);
+      let base = null,
+        liveWhy = `not asked for (${CMD} review --live)`;
+      if (typeof live === 'string') {
+        try {
+          base = new URL(live).href;
+        } catch {
+          throw new UsageError(`--live takes an address (https://… or http://127.0.0.1:<port>/game/)\n\n${usage}`);
+        }
+      } else if (live) {
+        const known = (await readLinks(dir))[studioOrigin()];
+        base = known?.gameUrl ?? null;
+        if (!base) {
+          liveWhy = `${shown(dir)} has no published link here: publish it, or run ${CMD} dev and give its address (--live http://127.0.0.1:<port>/game/)`;
+          if (!values.json) console.error(`Not asked live: ${liveWhy}.`);
+        }
+      }
+      const { reviewGame } = await import('../lib/review.mjs');
+      if (base && !values.json) console.error(`Asking ${base} as a stranger (no sign-in, and a forged one)…`);
+      const r = await reviewGame(dir, { live: base, liveWhy, out: values.out ?? null });
+      if (values.json) printJson(r);
+      else console.log(summary(r, shown(dir)));
+      return r.ok ? 0 : 1;
+    }, args),
+};
+
+/** What the command prints: the verdict, each finding, and where the record and the trade-offs are. */
+function summary(r, where) {
+  const c = r.counts;
+  const lines = [
+    `review: ${r.ok ? 'PASS' : 'FAIL'} ${c.high} high, ${c.medium} medium, ${c.low} low, ${c.info} info · evidence ${shown(r.outDir)}`,
+  ];
+  for (const f of r.findings) {
+    lines.push(`  ${f.severity.padEnd(6)} ${f.id}${f.route ? ` (${f.route})` : ''}: ${f.message}`);
+    if (f.fix && f.severity !== 'info') lines.push(`         fix: ${f.fix}`);
+  }
+  lines.push(
+    r.economy.file
+      ? r.economy.available
+        ? `economy: ${r.economy.file}, ${r.economy.routes.length} routes reviewed by @xgamesfun/solana ${r.economy.version}`
+        : `economy: ${r.economy.file} not reviewed: ${r.economy.why}`
+      : `economy: ${where} has none`,
+    `server: ${r.server.routes.length} api/ routes named${r.server.facts.vouchers ? `; PAY.check ${r.server.facts.pay === 'template' ? 'is still the template' : r.server.facts.pay}, payOnly ${r.server.facts.payOnly ?? '?'}` : ''}`,
+    r.live ? `live: ${r.live.base}, ${r.live.probes.length} requests` : `live: ${r.liveWhy}`,
+  );
+  for (const t of r.tradeoffs)
+    lines.push(
+      `paid route ${t.route}: ${t.trust ? `${t.trust}${t.declared ? '' : ' (read so by the economy review; not declared)'}` : 'trust not declared'}`,
+    );
+  if (r.tradeoffs.length)
+    lines.push(
+      `For the person: ${shown(r.outDir)}/review.md ends with each paid route's level, what a cheater gets and what the stronger level costs. Tell them, and let them choose.`,
+    );
+  return lines.join('\n');
+}

package/docs/SERVER.md

@@ -153,14 +153,14 @@ version talking to the other (a version number in the first message is enough to
 
 Every call answers `{ok: true, …}` or `{ok: false, code, why}` (`why` is words a game may show); none throws.
 
-| Call                                                                                                                                                                                                | Answer                                                                                                                                                                                                                                   |
-| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GF.verifyPlayer(token)`                                                                                                                                                                            | `{ok, sub, wallet, x, lvl, exp}`: who the player is, from the sign-in token the page sends (no display name: show `x.handle` when they signed in with X, else a name the page sends, cleaned)                                            |
-| `GF.saves.get(player, key = 'main')`, `.put(player, key, value)`, `.delete(player, key)`, `.list(player)`                                                                                           | a player's saves: any JSON value, 64 KB each, 16 a player                                                                                                                                                                                |
-| `GF.scores.submit(board, player, score, {name, order, writer})`, `.setup(board, {order, writer})`, `.top(board, {limit, offset})`, `.best(board, player)`, `.remove(board, player)`, `.drop(board)` | leaderboards: a player's best is kept; `order` `"high"` (default) or `"low"`; `writer: "server"`: only the server writes the board (or every board a pattern names: `daily-*`, `*`); `drop`: the board gone, its place among the 16 free |
-| `GF.loot.report({round, endedAt, winners})`, `GF.loot.status()`                                                                                                                                     | a result that pays prizes by place: xgames.fun's keeper signs it with the game's host key (set up by the owner in Studio); for amounts your server works out, your own key (below, "Paying a result")                                    |
-| `GF.info()`                                                                                                                                                                                         | `{ok, contract, gameId, slug}`                                                                                                                                                                                                           |
-| `GF.files.put(path, body, {type, public, length})`, `.get(path)`, `.head(path)`, `.list({prefix, after})`, `.delete(path)`, `.usage()`                                                              | the game's project files (below, "Project files"): replays, levels, content packs; public ones on the files site                                                                                                                         |
+| Call                                                                                                                                                                                                | Answer                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GF.verifyPlayer(token)`                                                                                                                                                                            | `{ok, sub, wallet, x, lvl, exp, banned}`: who the player is, from the sign-in token the page sends (no display name: show `x.handle` when they signed in with X, else a name the page sends, cleaned). `banned`: the creator's ban from the console (`{kind: 'ban' \| 'hide', until}`, or null; always null in `xcore dev`). A token made before a ban still verifies for its hour, so refuse `kind: 'ban'` yourself |
+| `GF.saves.get(player, key = 'main')`, `.put(player, key, value)`, `.delete(player, key)`, `.list(player)`                                                                                           | a player's saves: any JSON value, 64 KB each, 16 a player                                                                                                                                                                                                                                                                                                                                                            |
+| `GF.scores.submit(board, player, score, {name, order, writer})`, `.setup(board, {order, writer})`, `.top(board, {limit, offset})`, `.best(board, player)`, `.remove(board, player)`, `.drop(board)` | leaderboards: a player's best is kept; `order` `"high"` (default) or `"low"`; `writer: "server"`: only the server writes the board (or every board a pattern names: `daily-*`, `*`); `drop`: the board gone, its place among the 16 free                                                                                                                                                                             |
+| `GF.loot.report({round, endedAt, winners})`, `GF.loot.status()`                                                                                                                                     | a result that pays prizes by place: xgames.fun's keeper signs it with the game's host key (set up by the owner in Studio); for amounts your server works out, your own key (below, "Paying a result")                                                                                                                                                                                                                |
+| `GF.info()`                                                                                                                                                                                         | `{ok, contract, gameId, slug}`                                                                                                                                                                                                                                                                                                                                                                                       |
+| `GF.files.put(path, body, {type, public, length})`, `.get(path)`, `.head(path)`, `.list({prefix, after})`, `.delete(path)`, `.usage()`                                                              | the game's project files (below, "Project files"): replays, levels, content packs; public ones on the files site                                                                                                                                                                                                                                                                                                     |
 
 `player` is the game's own word for a player; normally `verifyPlayer`'s `sub`, so nobody can write another player's.
 The page writes the same saves and boards for its own signed-in player (`/platform/v1/*`), so a board is the player's
@@ -284,6 +284,17 @@ A result is worth paying only as far as the server can tell it happened. Stronge
   milliseconds must not add up). A script that plays at human speed still gets through: this limits what a cheater
   earns, it does not stop one.
 
+Say which one in the grant: `"trust": "decides"`, `"replays"` or `"bounds"` on every grant a voucher pays (what the
+server holding its key checks before it signs, as `PAY.check` really does it; it needs the `@xgamesfun/solana` that has
+`xcore loot review`, since 0.25.0 refuses the field). `xcore review` then reads the economy and the server as a cheater
+would: what a script gets from each paid route without playing, a `PAY.check` that pays from the request alone, a
+`payOnly` that lets one person claim from every wallet they make, and, with `--live`, each `api/` route asked with no
+sign-in and with a forged one. Its `review.md` ends with the trade-offs to tell the person. The full guide, with
+Solana's own exploit checklist, is `@xgamesfun/solana`'s skill reference
+`skills/xsolana-economy/references/trust-and-cheating.md`; in short: a bounded result pays a script that waits and
+reports, a replayed one pays the best run a script can find (unless randomness is revealed as the run goes), a decided
+one pays what a bot that plays well wins.
+
 Even a result the server decided is worth what a good bot can earn: a bot that plays well wins what a player who
 plays well wins. Pay a bounded or replayed result only what you would accept losing to a patient script (small
 amounts, capped a day), and keep entry fees and prize pools for results the server decided and chance (the oracle).
@@ -293,8 +304,9 @@ Tell players which one your game is.
 cap that counts players or wallets multiplies with each one a person makes. What helps:
 
 - **A person, not a wallet.** For rewards worth farming, pay only players signed in with X (`VOUCHERS.payOnly = 'x'`
-  in `server/vouchers.js`), count your caps per X account, and give the grant `perPerson` (the voucher carries a
-  hash of the player's X account).
+  in `server/vouchers.js`), or with X or Google (`'account'`: a Google account is easier to make than an X one, so it
+  stops less farming), count your caps per account, and give the grant `perPerson` (the voucher carries a hash of the
+  player's X account, or `g:<Google id>` for a Google account with no X).
 - **Totals.** Give every grant a `perDay` total in `xsolana.json`, so the most it pays a day is known whoever claims.
 - **Holding something.** Gate a reward on an NFT the game sells (a pass, a creature): each identity then costs money.
 - **Proven wallets.** Pay, and grant perks to, only a wallet the player proved is theirs: the one they signed in
@@ -378,7 +390,8 @@ voucher code into `server/gf-loot/` (bundled with the server, never a public fil
    the result's own id, any text, used once; amount: base units, or `'grant'` for the grant's own amount, always
    named so a forgotten amount never pays the most) or `{why}` to refuse. Until you write it, nothing is paid. Count a
    player's daily total in `PAY.paid` (it runs once a round, after its voucher is signed; again only if it threw), not in `check`.
-4. Who is paid: set `VOUCHERS.payOnly` to `'x'` for rewards worth farming (above, "Who gets paid"); the grant's
+   Then give the grant its `trust` (what that check does: `decides`, `replays` or `bounds`) and run `xcore review`.
+4. Who is paid: set `VOUCHERS.payOnly` to `'x'` or `'account'` for rewards worth farming (above, "Who gets paid"); the grant's
    `perDay` total caps the rest.
 5. `xcore loot approve` (the grant's change goes live), then `xcore publish`. `api/vouchers/key` answers the live
    key's address once the secret is set; until then the server pays nothing.
@@ -608,3 +621,10 @@ my-vault: 278 files, 10.0 MB, nothing refused. Left out: .gamesfun/, .gitignore,
 
 Hosted, the game's server answers at `https://<slug>-play.xgames.fun/api/…`. A blocked or over-limit server answers
 `{error, message}` with 451, 429, 404, 503 or 502 instead of the server's own answer.
+
+While the game's owner has it **paused for maintenance** (xgames.fun/console, the Live tab; README "Live"), xgames.fun
+answers its `api/*` itself with `503 {ok: false, code: 'maintenance', why, since}` and `retry-after: 60`, WebSocket
+upgrades included: the server's code does not run for a new request. What already runs keeps running (an open
+WebSocket, a Durable Object's alarm, the `env.GF` calls they make); a server that should stop those reads the game's
+`GET /platform/v1/live` (`maintenance` is `{message, since}` while paused). `xcore dev` does the same from
+`.gamesfun/live.json`.

package/lib/add.mjs

@@ -603,6 +603,7 @@ export async function addVouchers(dir) {
         ? []
         : [`${where} has no grant yet: add one that pays results (xsolana_examples "rewards for a score").`]),
       'Write PAY.check at the top of server/vouchers.js: what your server checks before a result pays (docs/SERVER.md, "How much your server can check"), and PAY.paid to count what was paid. Until then nothing is paid. Every wallet is a new player and a wallet sign-in is free: for rewards worth farming set VOUCHERS.payOnly to \'x\' (players signed in with X) and give the grant a perDay total.',
+      `Say in each grant that pays results how much PAY.check really checks: "trust": "decides", "replays" or "bounds" (once the installed @xgamesfun/solana takes it: the one with ${CMD} loot review). Then ${CMD} review: what a cheater gets from each paid route, and what to fix before publishing; tell the person, and let them choose the level.`,
       `The page links its wallet once (await gf.loot.link(): the wallet signs that it is this player's; a wallet sign-in needs none), then asks and claims: const r = await gf.api('vouchers/pay', {method: 'POST', body: {runId}}); then await gf.loot.call('claimGrant', '<grant>', {voucher: r.data.voucher}). A voucher pays only a wallet the player proved. Your server's own code (a room that decided a match) pays with voucherFor(env, {grant, wallet: await walletOf(env, player), round}) from './vouchers.js'.`,
       `Each pay is one request to the game's server and one read of the grant through the relay (or your own RPC: ${CMD} add rpc); publish keeps server/gf-loot/ at the installed @xgamesfun/solana, so the vouchers follow loot when xcore does.`,
     ],