@onceworlds/cli 0.2.1 → 0.4.0

package/README.md

@@ -9,8 +9,9 @@ players) with no server code.
 Deploys run from GitHub Actions: GitHub vouches for the repo, so there are no API
 keys. The easiest setup is to import the repo at https://onceworlds.com/dashboard/new,
 which adds `onceworlds.json` and `.github/workflows/onceworlds.yml` for you (that
-workflow also builds with npm, pnpm, yarn or bun when there's a build script). By
-hand, the minimum is:
+workflow also builds with npm, pnpm, yarn or bun when there's a build script). To write
+the same files into a folder before it is on GitHub, run `npx @onceworlds/cli init` there.
+By hand, the minimum is:
 
 ```yaml
 name: Deploy to Onceworlds
@@ -33,12 +34,13 @@ jobs:
 
 Pushes to the production branch (`main` unless you change it in the dashboard or
 `onceworlds.json`) go live at `onceworlds.com/play/<slug>`; other branches get a
-preview URL in the job log. Log in to https://onceworlds.com with the GitHub
-account that owns the repo (or any member of its organization) before the first
-deploy. If a deploy fails, the dashboard shows why.
+preview URL in the job log. Log in to https://onceworlds.com with a GitHub
+account that has write access to the repo before the first deploy. Install the
+Onceworlds GitHub App on that repo to use the dashboard and open the game while
+private. If a deploy fails, the dashboard shows why.
 
-New games start private: only the repo's owner (or its organization's members)
-can play them. To share one, open it in the dashboard and pick Unlisted (anyone
+New games start private: only accounts with write access to the repo can play
+them. To share one, open it in the dashboard and pick Unlisted (anyone
 with the link) or Public (also listed on Onceworlds).
 
 ## Project file
@@ -62,18 +64,38 @@ with the link) or Public (also listed on Onceworlds).
 `index.html`. `productionBranch` (default `main`) picks the branch that goes live;
 the dashboard can change it too, and the file wins again only when this value changes.
 
-The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
+`controls` (`[{ "keys": ["W", "A", "S", "D"], "action": "Move" }]`, up to 12) and `help` (up to 400
+characters) fill "How to play" in the platform menu. The rest fills in the game page: `genre`, a square `icon` (at least 128×128),
 16:9 `thumbnails` (at least 480 wide; the first is the cover) and `badges` (`id`,
-`name`, `description` and an optional square `icon`). Images are PNG, JPEG, WebP
+`name`, `description` and an optional square `icon`). A game page holds at most 5
+thumbnails and videos together, and a game at most 50 badges. Images are PNG, JPEG, WebP
 or GIF up to 5 MB, with paths relative to `onceworlds.json`. Live deploys apply
 these fields only when they change, so edits made in the dashboard last until then.
 
+Make the art before the first deploy: players see the icon and thumbnails before the game, and a game
+without them gets a plain colored placeholder. The icon is a simple, wordless 512×512 square; the thumbnails
+are three to five 1280×720 pictures of the game being played, the best one first (it is the cover). Capture them
+from the running game and commit them under `store/`. `onceworlds doctor` says which fields are missing.
+
 ## Commands
 
+- `onceworlds init [dir]` sets a game folder up, with the files the dashboard's import commits. It writes
+  `onceworlds.json` (the link and name come from `package.json`'s name or the folder's; `dir` is your build's
+  output folder when `package.json` has a build script, else `.` or the folder with your `index.html`),
+  `.github/workflows/onceworlds.yml`, and the guide for AI coding tools as `AGENTS.md` with a `CLAUDE.md` that
+  imports it (next to a `AGENTS.md` of your own it writes `ONCEWORLDS.md` and adds a pointer to yours). It never
+  overwrites a file you have: `--force` replaces only what init writes, never your own `AGENTS.md` or `CLAUDE.md`.
+  Then commit, push, and import the repo at https://onceworlds.com/dashboard/new.
 - `onceworlds deploy [dir]` uploads only the files that changed and publishes the game
   (the workflow runs it). It lists every file it skipped because Onceworlds can't serve it.
 - `onceworlds dev [dir]` deploys to a local Onceworlds platform (for platform development)
-  and redeploys on every save.
+  and redeploys on every save. `--players 3` also prints links for players 2 and 3 (`?player=N`): on a
+  local platform each is another player, so one person can fill a lobby.
+- `onceworlds doctor [dir]` looks through the game's files for what games often ship with: no viewport
+  tag, text fields under 16px (Safari zooms the page when one is focused), `confirm()` and other dialogs
+  (blocked in the game frame), localStorage (gone on reload), and, for games with rooms, `Date.now()` for
+  shared time and no use of the platform's lobby. It only suggests: nothing in it stops a deploy
+  (`--strict` exits with an error on likely bugs, for CI).
 
 Games talk to the platform through the injected `window.onceworlds` SDK. The
 starter template's `AGENTS.md` documents it for AI coding tools.

package/dist/cli.js

@@ -1,28 +1,230 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { execFileSync } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { createHash } from "node:crypto";
 import { watch } from "node:fs";
-import { readdir, readFile } from "node:fs/promises";
-import { join, resolve, sep } from "node:path";
+import { readdir as readdir2, readFile as readFile2, stat as stat2 } from "node:fs/promises";
+import { join as join2, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 
+// src/doctor.ts
+var ROOM_MAX_PLAYERS = 30;
+var MINIFIED_LINE = 400;
+var lineOf = (text, index) => text.slice(0, index).split("\n").length;
+function looksMinified(text) {
+  const lines = text.split("\n");
+  return text.length > 2e4 && text.length / lines.length > MINIFIED_LINE;
+}
+function cssIn(file) {
+  if (/\.css$/i.test(file.path)) return [{ css: file.text, offset: 0 }];
+  if (!/\.html?$/i.test(file.path)) return [];
+  const blocks = [];
+  for (const match of file.text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) blocks.push({ css: match[1], offset: (match.index ?? 0) + match[0].indexOf(match[1]) });
+  return blocks;
+}
+function smallFields(file) {
+  const found = [];
+  for (const { css, offset } of cssIn(file)) {
+    for (const rule of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+      const selector = rule[1];
+      if (!/(^|[\s,>+~(])(input|textarea|select)\b/i.test(selector) && !/\.[\w-]*(input|field|textbox)\b/i.test(selector)) continue;
+      if (/type\s*=\s*["']?(range|checkbox|radio|color|button|submit|file)/i.test(selector)) continue;
+      const size = /(?:^|[;\s])font-size\s*:\s*(\d+(?:\.\d+)?)px/i.exec(rule[2]) ?? /(?:^|[;\s])font\s*:\s*[^;]*?\b(\d+(?:\.\d+)?)px/i.exec(rule[2]);
+      if (!size || Number(size[1]) >= 16) continue;
+      const at = offset + (rule.index ?? 0) + rule[0].indexOf(size[0]);
+      found.push({
+        file: file.path,
+        line: lineOf(file.text, at),
+        level: "warn",
+        id: "field-size",
+        message: `A text field at ${size[1]}px: Safari on iPhone and iPad zooms the whole page when it's focused. Use at least 16px.`
+      });
+    }
+  }
+  return found;
+}
+var LINE_RULES = [
+  {
+    id: "dialogs",
+    level: "warn",
+    test: /(?<![\w$])(?:window\s*\.\s*)?(alert|confirm|prompt)\s*\(/,
+    // `confirm() {` (a method), `function prompt(`, `.confirm(` on some object of the game's own.
+    except: /(?<![\w$])(alert|confirm|prompt)\s*\([^()]*\)\s*\{|function\s+(alert|confirm|prompt)\b|(?<!window)\.\s*(alert|confirm|prompt)\s*\(/,
+    message: "alert(), confirm() and prompt() are blocked in the game frame (confirm() answers false at once). Draw your own message or dialog."
+  },
+  {
+    id: "fullscreen",
+    level: "note",
+    test: /\.(webkitR|r)equestFullscreen\s*\(/,
+    message: "Use onceworlds.ui.requestFullscreen(): the platform keeps its menu and chat available in fullscreen, and handles iPhone."
+  },
+  {
+    id: "storage",
+    level: "note",
+    test: /\b(localStorage|sessionStorage)\b|document\.cookie/,
+    message: "localStorage, sessionStorage and cookies are kept in memory in the game frame and are gone on reload (fine for caches and a fallback outside the platform). Use onceworlds.save.set/get for progress and settings that should stay."
+  }
+];
+function checkListing(config, file = "onceworlds.json") {
+  const found = [];
+  const note = (id, message) => found.push({ file, line: 1, level: "note", id, message });
+  const filled = (value) => typeof value === "string" && value.trim() !== "";
+  if (!filled(config.icon)) {
+    note("listing-icon", `No "icon": the game's card shows a plain colored placeholder. Add a square image (512\xD7512, simple, no words), like "icon": "store/icon.png".`);
+  }
+  if (!Array.isArray(config.thumbnails) || config.thumbnails.length === 0) {
+    note("listing-thumbnails", 'No "thumbnails": the game page and its card have no cover. Add 3-5 16:9 pictures (1280\xD7720) of the game being played; the first is the cover.');
+  }
+  if (!filled(config.genre)) note("listing-genre", `No "genre": players can't find the game under a Discover genre. Pick one of the genres in AGENTS.md.`);
+  const noControls = !Array.isArray(config.controls) || config.controls.length === 0;
+  if (noControls && !filled(config.help)) {
+    note("listing-help", `No "controls" or "help": the menu's How to play is empty. List every key or button the game uses and a line on how to win.`);
+  }
+  return found;
+}
+function checkGame(files) {
+  const found = [];
+  const code = files.filter((f) => /\.(html?|m?js|css)$/i.test(f.path));
+  const index = code.find((f) => f.path === "index.html");
+  if (index && !/<meta[^>]+name\s*=\s*["']viewport["']/i.test(index.text)) {
+    found.push({
+      file: index.path,
+      line: 1,
+      level: "warn",
+      id: "viewport",
+      message: 'No viewport meta tag: phones show the page zoomed out. Add <meta name="viewport" content="width=device-width, initial-scale=1">.'
+    });
+  }
+  for (const file of code) {
+    found.push(...smallFields(file));
+    if (looksMinified(file.text) || /\.css$/i.test(file.path)) continue;
+    const lines = file.text.split("\n");
+    for (const rule of LINE_RULES) {
+      const first = lines.findIndex((line) => !/^\s*(\/\/|\*|\/\*)/.test(line) && rule.test.test(line) && !rule.except?.test(line));
+      if (first !== -1) found.push({ file: file.path, line: first + 1, level: rule.level, id: rule.id, message: rule.message });
+    }
+  }
+  const all = code.map((f) => f.text).join("\n");
+  if (/\brooms\s*\.\s*join\s*\(/.test(all)) {
+    const host = code.find((f) => /\brooms\s*\.\s*join\s*\(/.test(f.text));
+    const at = lineOf(host.text, host.text.search(/\brooms\s*\.\s*join\s*\(/));
+    if (!/\b(lobby\s*:|startMatch|matchstart|setReady|minPlayers)/.test(all)) {
+      found.push({
+        file: host.path,
+        line: at,
+        level: "note",
+        id: "matches",
+        message: `This joins a room but doesn't use the platform's lobby or match lifecycle. That's right for a world people drop in and out of; a game with rounds gets ready-up, a countdown, spectators and pausing from rooms.join({ lobby: 'card' }) (see AGENTS.md, "Matches").`
+      });
+    }
+    if (/\bDate\s*\.\s*now\s*\(/.test(all) && !/\bonceworlds\s*\.\s*now\s*\(|\bow\s*\.\s*now\s*\(|\bmatchNow\s*\(/.test(all)) {
+      found.push({
+        file: host.path,
+        line: at,
+        level: "note",
+        id: "clock",
+        message: "Time from Date.now() differs between players' devices. Use onceworlds.now() for anything players share, and room.matchNow() for a match's deadlines."
+      });
+    }
+  }
+  const size = /\bmaxPlayers\s*:\s*(\d+)\b/g;
+  for (const file of code) {
+    for (const match of file.text.matchAll(size)) {
+      if (Number(match[1]) <= ROOM_MAX_PLAYERS) continue;
+      found.push({
+        file: file.path,
+        line: lineOf(file.text, match.index ?? 0),
+        level: "note",
+        id: "room-size",
+        message: `A room seats at most ${ROOM_MAX_PLAYERS} players: maxPlayers: ${match[1]} gives ${ROOM_MAX_PLAYERS}. The bigger the room, the less each player may send (room.budget), so a full room stays smooth.`
+      });
+      break;
+    }
+  }
+  const keyboardKeys = /\b(ArrowLeft|ArrowRight|ArrowUp|ArrowDown|KeyW|KeyA|KeyS|KeyD)\b|\.key\s*={2,3}\s*['"](?:w|a|s|d|ArrowLeft|ArrowRight|ArrowUp|ArrowDown)['"]|case\s+['"](?:w|a|s|d|ArrowLeft|ArrowRight|ArrowUp|ArrowDown)['"]|keys\s*\.\s*has\s*\(\s*['"](?:w|a|s|d|arrowleft|arrowright|arrowup|arrowdown)['"]/;
+  const keyboard = keyboardKeys.test(all);
+  if (keyboard && !/\bcontrols\s*\??\.\s*(?:set|stick|touch|pressed)\b|\b(?:set|sync)Controls\s*\(/i.test(all)) {
+    const touchable = /\b(pointerdown|touchstart|mousedown|click)\b/.test(all);
+    const file = code.find((f) => keyboardKeys.test(f.text));
+    found.push({
+      file: file.path,
+      line: lineOf(file.text, file.text.search(keyboardKeys)),
+      level: touchable ? "note" : "warn",
+      id: "touch-controls",
+      message: touchable ? "Steered by keys, with no on-screen controls: phones show none. Ask for the platform's with onceworlds.controls.set({ stick: 'wasd' }) (see AGENTS.md, phones and tablets)." : "Steered by keys, and nothing responds to touch: on a phone the game can't be played. Ask for the platform's on-screen controls with onceworlds.controls.set({ stick: 'wasd', buttons: [...] })."
+    });
+  }
+  if (/\bdevicePixelRatio\b/.test(all) && !/\bsettings\s*\.\s*pixelRatio\b/.test(all)) {
+    const file = code.find((f) => /\bdevicePixelRatio\b/.test(f.text));
+    found.push({
+      file: file.path,
+      line: lineOf(file.text, file.text.search(/\bdevicePixelRatio\b/)),
+      level: "note",
+      id: "pixel-ratio",
+      message: "Size canvases with onceworlds.settings.pixelRatio(2): it caps the resolution and follows the player's Graphics setting, so tablets and older phones keep their frame rate."
+    });
+  }
+  return found.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+
+// src/init.ts
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
 // ../protocol/src/index.ts
 var OIDC_AUDIENCE = "onceworlds";
 var LIMITS = {
   roomMaxPlayersDefault: 16,
-  roomMaxPlayersCap: 50,
+  /**
+   * The most players a room seats. A room is one Durable Object that copies every update a player sends to everyone else, so
+   * what it costs grows with the square of its players: 30 is where a room stays well inside what one object serves.
+   */
+  roomMaxPlayersCap: 30,
   teamsMax: 8,
   messageBytes: 16 * 1024,
   presenceBytes: 1024,
   stateKeyLength: 64,
   stateValueBytes: 16 * 1024,
   stateKeys: 256,
+  /** Private values (room.setPrivate): keys per player, one value, and all of a player's together. */
+  privateKeys: 16,
+  privateValueBytes: 4 * 1024,
+  privateBytesPerPlayer: 8 * 1024,
+  /** The most messages a second one player may send a room (a room with more players gives each less: see roomBudget). */
   messagesPerSecond: 60,
-  /** Bytes one player may send to a room per second, on average (bursts up to 4x). */
+  messagesPerSecondMin: 10,
+  /** Bytes one player may send to a room per second, on average (bursts up to 4x): the most, in a small room. */
   roomBytesPerSecond: 128 * 1024,
+  roomBytesPerSecondMin: 16 * 1024,
+  /** The most presence updates a second one player may send. */
   presenceHz: 20,
+  presenceHzMin: 5,
+  /**
+   * What a room takes in from all its players together each second, presence included (a Durable Object serves about 1000
+   * requests a second, and each update is then sent on to everyone else), and the bytes. Each player's share is this divided
+   * by the room's capacity, up to the per-player maximums above: rooms of up to 11 players get all of them.
+   */
+  roomMessagesPerSecond: 900,
+  roomBytesPerSecondTotal: 2 * 1024 * 1024,
+  /** A match's countdown before play begins, unless the room is set up otherwise (rooms.join({ countdown })). */
+  matchCountdownMs: 3e3,
+  matchCountdownMaxMs: 1e4,
+  /** A public lobby where half the players are ready waits this long for the rest before starting without them. */
+  matchIdleMs: 45e3,
+  /** A match that has waited this long for its players (paused, too few connected) is over. */
+  matchAbandonMs: 12e4,
+  /** A player who hasn't touched the game (pointer, keys, touch, gamepad) this long is idle (room.on('idle')). */
+  idleAfterMs: 3e4,
+  /** A running match whose connected players have all been idle this long is over: nobody is playing. */
+  idleAbandonMs: 5 * 6e4,
+  /**
+   * Rated matches two accounts on opposite sides may play against each other in one game's ladder per UTC day: past it,
+   * their matches aren't rated, so two accounts that keep getting matched in a quiet game can't farm wins.
+   */
+  rankedPairMatchesPerDay: 5,
   chatLength: 200,
   chatIntervalMs: 750,
   chatHistory: 50,
@@ -34,12 +236,24 @@ var LIMITS = {
   guestSaveBytesPerGame: 128 * 1024,
   deployFiles: 2e3,
   deployFileBytes: 25 * 1024 * 1024,
+  /** HTML files (.html, .htm) get the SDK injected as they're served (streamed: only the first bytes are read for it), so they're held to less than other files. */
+  deployHtmlBytes: 10 * 1024 * 1024,
+  /** Characters in a deployed file's path. */
+  deployPathLength: 200,
   deployTotalBytes: 100 * 1024 * 1024,
   envVars: 50,
   envValueBytes: 4 * 1024,
+  /** All of a game's public variables together, as injected into its pages. */
+  envTotalBytes: 16 * 1024,
+  /** Proxied request bodies: routes that take a file (audio to transcribe, an image to edit). */
   proxyRequestBytes: 1024 * 1024,
+  /** Proxied JSON bodies for text, embeddings and image generation. */
+  proxyTextRequestBytes: 256 * 1024,
+  /** Proxied text-to-speech bodies (priced per character). */
+  proxySpeechRequestBytes: 16 * 1024,
   proxyResponseBytes: 10 * 1024 * 1024,
-  proxyMaxOutputTokens: 8192,
+  /** Output tokens per proxied text call: a request asking for more is lowered to this, one that doesn't say gets it. */
+  proxyMaxOutputTokens: 4096,
   proxyCallsPerDay: 2e3,
   proxyCallsPerDayMax: 1e5,
   proxyCallsPerPlayerPerDay: 100,
@@ -48,13 +262,35 @@ var LIMITS = {
   proxyMediaCallsPerDayMax: 1e4,
   proxyMediaCallsPerPlayerPerDay: 20,
   proxyMediaCallsPerNetworkPerDay: 25,
+  /**
+   * Daily units: each proxied call's estimated tokens (request bytes / 3 plus its output
+   * cap) times its model's weight. Per game (the creator can set up to the max), per
+   * signed-in player, per guest, and per guests' network.
+   */
+  proxyUnitsPerDay: 2e6,
+  proxyUnitsPerDayMax: 1e8,
+  proxyUnitsPerPlayerPerDay: 25e4,
+  proxyUnitsPerGuestPerDay: 1e5,
+  proxyUnitsPerNetworkPerDay: 5e5,
   errorReportsPerPage: 10,
   gameNameLength: 60,
   gameDescriptionLength: 1e3,
-  galleryItems: 10,
+  galleryItems: 5,
   mediaImageBytes: 5 * 1024 * 1024,
   mediaVideoBytes: 30 * 1024 * 1024,
-  badgesPerGame: 100,
+  /** GIFs are served as they are (never resized), so they're small: at most this many bytes and pixels a side. */
+  mediaGifBytes: 1024 * 1024,
+  mediaGifSide: 512,
+  /** Media an account uploads in the dashboard (or a repo owner's deploys add to game pages) in any 24 hours. */
+  mediaUploadsPerDay: 200,
+  mediaBytesPerDay: 500 * 1024 * 1024,
+  badgesPerGame: 50,
+  /** The menu's "How to play": up to this many controls (each with a few keys and a short action), and a few lines of help. */
+  controlHints: 12,
+  controlHintKeys: 4,
+  controlKeyLength: 12,
+  controlActionLength: 40,
+  helpLength: 400,
   badgeNameLength: 50,
   badgeDescriptionLength: 200,
   leaderboardsPerGame: 25,
@@ -62,20 +298,41 @@ var LIMITS = {
   gamesPerOwner: 50,
   /** New games per creator in any rolling 24-hour period. Redeploys do not count. */
   gamesCreatedPerCreatorPerDay: 3,
+  /** An account made with just a username (no email, Google or GitHub) can publish a new game by upload once it is this old. */
+  uploadAccountAgeMs: 7 * 24 * 60 * 6e4,
   deploysPerOwnerPerDay: 100,
   /** Finished versions retained per game, including its live version. */
   deploymentsKeptPerGame: 10,
   deployBytesPerOwnerPerDay: 2 * 1024 * 1024 * 1024,
+  /** Files listed by all of a repo owner's deploys in any 24 hours (each is a record to keep and clean up). */
+  deployEntriesPerOwnerPerDay: 1e5,
   bioLength: 500,
+  /** Settings > Download my data: rows from any one table, the characters of saves, and how often an account may ask. */
+  exportRows: 2e3,
+  exportSaveChars: 4 * 1024 * 1024,
+  exportEveryMs: 60 * 6e4,
   friendsMax: 200,
+  /** Requests one player has sent that are still waiting. */
   friendRequestsMax: 100,
+  /** Requests waiting for one player: more wait until they answer some. */
+  friendRequestsIncomingMax: 50,
+  /** New friend requests an account sends in 24 hours (asking again after cancelling counts again)... */
+  friendRequestsPerDay: 20,
+  /** ...and all accounts under a week old on one network (IPv4 address, or IPv6 /48) together: a bot farm's accounts share one, a school's established ones are not counted. */
+  friendRequestsPerNetworkPerDay: 120,
+  /** Friend requests that reach a player's devices (push) in a day, at most one every 10 minutes. */
+  friendRequestPushesPerDay: 5,
   passwordMinLength: 8,
   passwordMaxLength: 72,
   /** Account creation attempts, with or without email, per network (IP, or IPv6 /64) in 24 hours. */
   signupsPerNetworkPerDay: 100,
+  /** The same per wide network (an IPv6 /48); an IPv4 address with a proof of work may go on to this too. */
+  signupsPerWidePerDay: 300,
   /** New guest players per network per day (each one can hold saves). */
   guestsPerNetworkPerDay: 300,
-  /** Visits a game gets per network (IP, or IPv6 /64) per day: a script can't pump the count. */
+  /** The same per wide network (an IPv6 /48); an IPv4 address with a proof of work may go on to this too. */
+  guestsPerWidePerDay: 1500,
+  /** Visits a game gets per network (IPv4 address, or IPv6 /48) per day: a script can't pump the count. */
   visitsPerNetworkPerDay: 10,
   /** Seconds of visible play before a play counts as a visit. */
   visitSeconds: 10,
@@ -95,7 +352,11 @@ var LIMITS = {
   conversationsListed: 50,
   notificationsListed: 50,
   /** Friends one game invite can go to. */
-  invitesPerRequest: 10
+  invitesPerRequest: 10,
+  /** How long an invite can be joined: it's for now. (It's over sooner when the sender leaves the server it points at, or you're already there.) */
+  inviteLiveMs: 30 * 6e4,
+  /** How long an invite to a party can be answered. */
+  partyInviteMs: 60 * 6e4
 };
 var CONTENT_TYPES = {
   html: "text/html; charset=utf-8",
@@ -163,7 +424,7 @@ function contentTypeFor(path) {
   return CONTENT_TYPES[extensionOf(path)];
 }
 function isValidDeployPath(path) {
-  if (path.length === 0 || path.length > 512) return false;
+  if (path.length === 0 || path.length > LIMITS.deployPathLength) return false;
   if (path.startsWith("/") || path.includes("\\")) return false;
   if (/[\u0000-\u001f\u007f]/.test(path)) return false;
   for (const segment of path.split("/")) {
@@ -173,10 +434,213 @@ function isValidDeployPath(path) {
 }
 var SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
 var RESERVED_SLUGS = /* @__PURE__ */ new Set(["www", "api", "play", "admin", "static", "assets", "docs", "status"]);
+var NEW_GAME_RESERVED_SLUGS = /* @__PURE__ */ new Set([
+  "star-party",
+  "login",
+  "log-in",
+  "logon",
+  "logout",
+  "signin",
+  "sign-in",
+  "signup",
+  "sign-up",
+  "register",
+  "auth",
+  "oauth",
+  "sso",
+  "verify",
+  "verified",
+  "verification",
+  "support",
+  "help",
+  "helpdesk",
+  "contact",
+  "official",
+  "staff",
+  "team",
+  "moderator",
+  "moderators",
+  "mod",
+  "mods",
+  "security",
+  "account",
+  "accounts",
+  "password",
+  "passwords",
+  "reset",
+  "billing",
+  "payment",
+  "payments",
+  "robux",
+  "vbucks",
+  "v-bucks",
+  "nitro",
+  "gift",
+  "gifts",
+  "giftcard",
+  "free",
+  "settings",
+  "dashboard",
+  "discover",
+  "games",
+  "users",
+  "friends",
+  "notifications",
+  "terms",
+  "privacy",
+  "changelog",
+  "create",
+  "guide",
+  "about",
+  "blog",
+  "news",
+  "mail",
+  "email"
+]);
+var NEW_GAME_RESERVED_PREFIXES = ["onceworlds", "admin", "free-"];
+var SLUG_AUTH_WORDS = /* @__PURE__ */ new Set(["login", "logon", "signin", "signon", "signup", "verify", "verification", "password", "passwords", "billing"]);
+var BRANDS = ["onceworlds", "roblox", "robux", "vbucks", "fortnite", "minecraft", "xbox", "playstation", "nintendo"];
+var LOOKALIKES = {
+  "0": "o",
+  "3": "e",
+  "4": "a",
+  "5": "s",
+  "7": "t",
+  "8": "b",
+  "@": "a",
+  "$": "s",
+  "|": "l",
+  "!": "i",
+  "\u0430": "a",
+  "\u0432": "b",
+  "\u0435": "e",
+  "\u043A": "k",
+  "\u043C": "m",
+  "\u043D": "h",
+  "\u043E": "o",
+  "\u0440": "p",
+  "\u0441": "c",
+  "\u0442": "t",
+  "\u0443": "y",
+  "\u0445": "x",
+  "\u0455": "s",
+  "\u0456": "i",
+  "\u0458": "j",
+  "\u04CF": "l",
+  "\u0501": "d",
+  "\u051D": "w",
+  "\u03B1": "a",
+  "\u03B2": "b",
+  "\u03B5": "e",
+  "\u03B9": "i",
+  "\u03BA": "k",
+  "\u03BD": "v",
+  "\u03BF": "o",
+  "\u03C1": "p",
+  "\u03C4": "t",
+  "\u03C5": "u",
+  "\u03C7": "x",
+  "\u03C9": "w"
+};
 function isValidSlug(slug) {
   return SLUG_RE.test(slug) && !slug.includes("--") && !RESERVED_SLUGS.has(slug);
 }
+function isReservedSlug(slug, newGame = true) {
+  if (RESERVED_SLUGS.has(slug)) return true;
+  if (!newGame) return false;
+  if (NEW_GAME_RESERVED_SLUGS.has(slug) || NEW_GAME_RESERVED_PREFIXES.some((prefix) => slug.startsWith(prefix))) return true;
+  if (!SLUG_RE.test(slug)) return false;
+  const parts = slug.split("-");
+  if (parts.some((part, i) => SLUG_AUTH_WORDS.has(part) || SLUG_AUTH_WORDS.has(part + (parts[i + 1] ?? "")))) return true;
+  return hasBrand(slug);
+}
+function foldedWords(text) {
+  const base = text.normalize("NFKD").toLowerCase().replace(/[\u0300-\u036f]/g, "");
+  const variants = [];
+  for (const one of ["l", "i"]) {
+    const mapped = [...base].map((c) => c === "1" ? one : LOOKALIKES[c] ?? c);
+    const words = mapped.map((c) => /[a-z]/.test(c) ? c : /[0-9]/.test(c) ? "" : " ").join("").split(" ").filter(Boolean);
+    variants.push(words, words.map((w) => w.replace(/vv/g, "w")));
+  }
+  return variants;
+}
+function hasBrand(text) {
+  for (const words of foldedWords(text)) {
+    if (words.some((word) => BRANDS.some((brand) => word.includes(brand)))) return true;
+    for (let i = 0; i < words.length; i++) {
+      let joined = words[i];
+      for (let j = i + 1; j < words.length && joined.length < 16; j++) {
+        joined += words[j];
+        if (BRANDS.includes(joined)) return true;
+      }
+    }
+  }
+  return false;
+}
 var DEFAULT_PRODUCTION_BRANCH = "main";
+function deployWorkflow() {
+  return `name: Deploy to Onceworlds
+
+# Branches only: tags don't deploy.
+on:
+  push:
+    branches: ['**']
+
+# A newer push to the same branch replaces a deploy still running.
+concurrency:
+  group: onceworlds-\${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write # lets the Onceworlds CLI prove which repo is deploying; no API keys needed
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # The build never needs the repo's GitHub token, so it isn't left in .git/config.
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 22
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        if: hashFiles('bun.lock', 'bun.lockb') != ''
+
+      # Only if package.json has a build script, with the package manager its lockfile belongs to.
+      - name: Build
+        run: |
+          if [ ! -f package.json ] || [ "$(npm pkg get scripts.build)" = "{}" ]; then
+            exit 0
+          elif [ -f pnpm-lock.yaml ]; then
+            corepack enable
+            pnpm install --frozen-lockfile
+            pnpm run build
+          elif [ -f yarn.lock ]; then
+            corepack enable
+            yarn install
+            yarn run build
+          elif [ -f bun.lock ] || [ -f bun.lockb ]; then
+            bun install
+            bun run build
+          elif [ -f package-lock.json ]; then
+            npm ci
+            npm run build
+          else
+            npm install
+            npm run build
+          fi
+
+      # Pushes to the production branch (set in the dashboard or onceworlds.json,
+      # default "main") go live; other branches get a preview URL in the job log.
+      - name: Deploy
+        run: npx --yes @onceworlds/cli@0 deploy
+`;
+}
 var BADGE_KEY_RE = /^[a-z0-9](?:[a-z0-9-]{0,38}[a-z0-9])?$/;
 var GENRES = [
   "Action",
@@ -196,6 +660,30 @@ var GENRES = [
   "Party",
   "Other"
 ];
+var tidy = (text) => text.replace(/[\u0000-\u001f\u007f]/g, " ").replace(/\s+/g, " ").trim();
+function checkGuide(controls, help) {
+  const hints = [];
+  if (controls !== void 0 && controls !== null) {
+    if (!Array.isArray(controls)) throw new Error('"controls" must be a list, like [{ "keys": ["W", "A", "S", "D"], "action": "Move" }]');
+    if (controls.length > LIMITS.controlHints) throw new Error(`"controls" can have at most ${LIMITS.controlHints} items`);
+    controls.forEach((item, i) => {
+      const { keys, action } = item ?? {};
+      const name = `controls[${i}]`;
+      if (!Array.isArray(keys) || keys.length === 0 || keys.length > LIMITS.controlHintKeys) {
+        throw new Error(`${name}.keys must be 1-${LIMITS.controlHintKeys} keys or buttons, like ["Space"]`);
+      }
+      const cleaned = keys.map((k) => typeof k === "string" ? tidy(k) : "");
+      if (cleaned.some((k) => !k || k.length > LIMITS.controlKeyLength)) throw new Error(`${name}.keys are short names (at most ${LIMITS.controlKeyLength} characters), like "Space" or "Left click"`);
+      const text2 = typeof action === "string" ? tidy(action) : "";
+      if (!text2 || text2.length > LIMITS.controlActionLength) throw new Error(`${name}.action is what the keys do, in at most ${LIMITS.controlActionLength} characters`);
+      hints.push({ keys: cleaned, action: text2 });
+    });
+  }
+  if (help !== void 0 && help !== null && typeof help !== "string") throw new Error('"help" must be text');
+  const text = typeof help === "string" ? help.replace(/[\u0000-\u0009\u000b-\u001f\u007f]/g, " ").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim() : "";
+  if (text.length > LIMITS.helpLength) throw new Error(`"help" can be at most ${LIMITS.helpLength} characters`);
+  return { controls: hints, help: text };
+}
 var MAX_IMAGE_SIDE = 4096;
 function imageInfo(bytes) {
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
@@ -253,16 +741,149 @@ function imageSizeProblem(slot, width, height) {
   return null;
 }
 
+// src/init.ts
+var OUTPUT_DIRS = ["dist", "build", "out", "public", "web", "www", "export"];
+var WORKFLOW_PATH = ".github/workflows/onceworlds.yml";
+async function init(dir, options) {
+  const log = options.log ?? console.log;
+  const { force } = options;
+  const at = (path) => join(dir, path);
+  const read = (path) => readFile(at(path), "utf8").catch(() => null);
+  const exists = (path) => stat(at(path)).then(() => true, () => false);
+  const lines = [];
+  let kept = false;
+  const put = async (path, content, label = path) => {
+    try {
+      await mkdir(dirname(at(path)), { recursive: true });
+      await writeFile(at(path), content, { flag: force ? "w" : "wx" });
+      lines.push(`  wrote  ${label}`);
+    } catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      lines.push(`  kept   ${path} (it exists already)`);
+      kept = true;
+    }
+  };
+  const append = async (path, existing, line, label) => {
+    await writeFile(at(path), `${existing.trimEnd()}
+
+${line}
+`);
+    lines.push(`  wrote  ${label}`);
+  };
+  const pkg = await readPackage(dir);
+  const source = typeof pkg?.name === "string" && pkg.name.replace(/^@[^/]+\//, "") || basename(dir);
+  const fromName = slugFrom(source);
+  const slug = fromName ?? `game-${randomBytes(3).toString("hex")}`;
+  const found = await findDir(pkg, exists);
+  const branch = defaultBranch(dir);
+  const config = { slug, name: titleFrom(source), description: "", dir: found.dir, ...branch ? { productionBranch: branch } : {} };
+  await put("onceworlds.json", `${JSON.stringify(config, null, 2)}
+`, `onceworlds.json (link "${slug}", publishing "${found.dir}")`);
+  const present = await findWorkflow(dir);
+  if (present && present !== WORKFLOW_PATH) lines.push(`  kept   ${present} (it already deploys with the Onceworlds CLI)`);
+  else await put(WORKFLOW_PATH, deployWorkflow());
+  const guide = await fetchGuide(options.fetch ?? fetch, options.api, (line) => lines.push(line));
+  const agents = await read("AGENTS.md");
+  const separate = agents !== null && !/^# Onceworlds\b/.test(agents);
+  const guidePath = separate ? "ONCEWORLDS.md" : "AGENTS.md";
+  if (guide !== null) await put(guidePath, guide);
+  if (guide !== null || await exists(guidePath)) {
+    if (separate && !agents.includes("ONCEWORLDS.md")) {
+      await append("AGENTS.md", agents, "## Onceworlds\n\nThis game is published on Onceworlds. Read ONCEWORLDS.md for the platform rules and SDK.", "AGENTS.md (a pointer to ONCEWORLDS.md)");
+    }
+    const claude = await read("CLAUDE.md");
+    if (claude === null) await put("CLAUDE.md", `@${guidePath}
+`);
+    else if (!claude.includes(guidePath)) await append("CLAUDE.md", claude, `@${guidePath}`, `CLAUDE.md (a pointer to ${guidePath})`);
+  }
+  for (const line of lines) log(line);
+  if (fromName === null) log(`  note   "${source}" can't be a game's link, so the link is ${slug}. Change slug in onceworlds.json.`);
+  if (found.note) log(`  note   ${found.note}`);
+  if (kept) log("  note   --force replaces the files init writes. Your own AGENTS.md and CLAUDE.md are never replaced.");
+  log(`
+Next:
+  1. Check onceworlds.json: "slug" is your game's link (onceworlds.com/play/<slug>) and "name" is its title.
+  2. Commit these files and push the repo to GitHub.
+  3. Open ${options.api}/dashboard/new, import the repo, and every push publishes your game.`);
+}
+async function readPackage(dir) {
+  try {
+    const parsed = JSON.parse(await readFile(join(dir, "package.json"), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function slugFrom(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+  return isValidSlug(slug) && !isReservedSlug(slug) ? slug : null;
+}
+function titleFrom(name) {
+  const title = name.replace(/[-_.]+/g, " ").trim().replace(/\s+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+  return (title || "My Game").slice(0, LIMITS.gameNameLength);
+}
+async function findDir(pkg, exists) {
+  if (typeof pkg?.scripts?.build === "string") {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    const out = deps.next ? "out" : deps["react-scripts"] || deps["@sveltejs/kit"] ? "build" : "dist";
+    return { dir: out, note: `"dir" is ${out}, where the build script is expected to write the game. Change it in onceworlds.json if yours writes elsewhere.` };
+  }
+  if (await exists("index.html")) return { dir: "." };
+  for (const name of OUTPUT_DIRS) if (await exists(`${name}/index.html`)) return { dir: name };
+  return { dir: ".", note: `No index.html here yet. Set "dir" in onceworlds.json to the folder that has your game's index.html.` };
+}
+function defaultBranch(dir) {
+  const git = (args) => {
+    try {
+      return execFileSync("git", args, { cwd: dir, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null;
+    } catch {
+      return null;
+    }
+  };
+  return git(["symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD"])?.replace(/^origin\//, "") ?? git(["symbolic-ref", "-q", "--short", "HEAD"]);
+}
+async function findWorkflow(dir) {
+  const folder = join(dir, ".github/workflows");
+  const names = await readdir(folder).catch(() => []);
+  for (const name of names.filter((n) => /\.ya?ml$/.test(n)).slice(0, 20)) {
+    if ((await readFile(join(folder, name), "utf8").catch(() => "")).includes("@onceworlds/cli")) return `.github/workflows/${name}`;
+  }
+  return null;
+}
+async function fetchGuide(fetcher, api, warn) {
+  const url = `${api}/agents.md`;
+  let problem;
+  try {
+    const res = await fetcher(url, { signal: AbortSignal.timeout(1e4) });
+    const text = res.ok ? await res.text() : "";
+    if (text.trim()) return text;
+    problem = res.ok ? "it is empty" : `${res.status}`;
+  } catch (err) {
+    problem = err instanceof Error ? err.message : String(err);
+  }
+  warn(`  ! Skipped AGENTS.md and CLAUDE.md: could not fetch ${url} (${problem}). Run init again when it works.`);
+  return null;
+}
+
 // src/index.ts
 var PRODUCTION_API = "https://onceworlds.com";
 var LOCAL_API = "http://localhost:8787";
 var USAGE = `Usage:
+  onceworlds init [project-dir]     Set a game folder up for Onceworlds: writes onceworlds.json, the GitHub workflow
+                                    that publishes every push, and AGENTS.md and CLAUDE.md for AI coding tools
   onceworlds deploy [project-dir]   Upload the game and publish it (to ${PRODUCTION_API})
   onceworlds dev [project-dir]      Deploy to a local platform (${LOCAL_API}), then redeploy on every change
+  onceworlds doctor [project-dir]   Look for what games often ship with: no viewport tag, small text fields,
+                                    localStorage, dialogs, Date.now() for shared time, keys with no touch
+                                    controls, a missing icon, thumbnails or How to play (suggestions only)
 
 Options:
   --api <url>     Platform URL (default: $ONCEWORLDS_API, else the ones above)
   --token <t>     Local platform's deploy token (default: "dev")
+  --players <n>   dev: also print links for players 2 to n, to play a multiplayer game with yourself
+  --strict        doctor: exit with an error when it finds a likely bug (not for notes)
+  --force         init: replace onceworlds.json, the workflow and the guide when they exist already
+                  (never your own AGENTS.md or CLAUDE.md)
 
 Deploys to onceworlds.com run from GitHub Actions: the repo's Onceworlds
 workflow runs this on every push, and GitHub vouches for the repo.
@@ -277,7 +898,14 @@ var QUIET_EXTENSIONS = /* @__PURE__ */ new Set(["md", "ts", "tsx", "jsx", "lock"
 async function main() {
   const { values, positionals } = parseArgs({
     allowPositionals: true,
-    options: { api: { type: "string" }, token: { type: "string" }, help: { type: "boolean", short: "h" } }
+    options: {
+      api: { type: "string" },
+      token: { type: "string" },
+      players: { type: "string" },
+      strict: { type: "boolean" },
+      force: { type: "boolean" },
+      help: { type: "boolean", short: "h" }
+    }
   });
   const [command, projectArg] = positionals;
   if (values.help || !command || command === "help") {
@@ -286,10 +914,17 @@ async function main() {
   }
   const projectDir = resolve(projectArg ?? ".");
   const api = (values.api ?? process.env.ONCEWORLDS_API ?? (command === "dev" ? LOCAL_API : PRODUCTION_API)).replace(/\/+$/, "");
-  if (command === "deploy") {
+  if (command === "init") {
+    if (!(await stat2(projectDir).catch(() => null))?.isDirectory()) throw new CliError(`${projectDir} isn't a folder.`);
+    await init(projectDir, { api, force: values.force === true });
+  } else if (command === "deploy") {
     await deploy(projectDir, api, values.token);
   } else if (command === "dev") {
-    await dev(projectDir, api, values.token);
+    const players = Number(values.players ?? 1);
+    if (!Number.isInteger(players) || players < 1 || players > 9) throw new CliError("--players is a number from 1 to 9.");
+    await dev(projectDir, api, values.token, players);
+  } else if (command === "doctor") {
+    await doctor(projectDir, values.strict === true);
   } else {
     throw new CliError(`Unknown command "${command}".
 
@@ -307,6 +942,12 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
   if (!files.some((f) => f.path === "index.html")) {
     throw new CliError(`No index.html in ${root}. Set "dir" in onceworlds.json to the folder that contains it.`);
   }
+  if (!quiet) {
+    const findings = [...checkGame(await readSources(files)), ...checkListing(config)];
+    for (const f of findings.filter((x) => x.level === "warn")) console.warn(`  ! ${f.file}:${f.line}  ${f.message}`);
+    const notes = findings.filter((x) => x.level === "note").length;
+    if (notes > 0) console.log(`  ${notes} suggestion${notes === 1 ? "" : "s"} for this game: run "npx @onceworlds/cli doctor" to see them.`);
+  }
   const total = files.reduce((sum, f) => sum + f.size, 0);
   if (total > LIMITS.deployTotalBytes) throw new CliError(`Game is ${formatBytes(total)}; the limit is ${formatBytes(LIMITS.deployTotalBytes)}.`);
   const { store, images } = await loadStore(projectDir, config);
@@ -329,7 +970,7 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
     console.log(`  \u2191 uploading ${uploads.length} changed file(s), ${formatBytes(uploads.reduce((s, f) => s + f.size, 0))}`);
   }
   await runPool(uploads, 6, async (file) => {
-    const body = await readFile(file.abs);
+    const body = await readFile2(file.abs);
     await send("PUT", `${api}/api/deploy/${start.deploymentId}/blobs/${file.hash}`, start.uploadToken, body);
   });
   const result = await send("POST", `${api}/api/deploy/${start.deploymentId}/finalize`, start.uploadToken, {});
@@ -341,15 +982,16 @@ async function deploy(projectDir, api, tokenArg, quiet = false) {
   }
   return result;
 }
-async function dev(projectDir, api, tokenArg) {
+async function dev(projectDir, api, tokenArg, players = 1) {
   const config = await loadConfig(projectDir);
   const root = resolve(projectDir, config.dir ?? ".");
   const first = await deploy(projectDir, api, tokenArg);
   console.log(`
-  Play (reloads on every change): ${first.playUrl}?watch
-  Watching ${root}. Press Ctrl+C to stop.
+  Play (reloads on every change): ${first.playUrl}?watch`);
+  for (let n = 2; n <= players; n++) console.log(`  Player ${n}: ${first.playUrl}?player=${n}&watch`);
+  console.log(`  Watching ${root}. Press Ctrl+C to stop.
 `);
-  const projectSignature = async () => signature((await collectFiles(root)).files) + await readFile(join(projectDir, "onceworlds.json"), "utf8").catch(() => "");
+  const projectSignature = async () => signature((await collectFiles(root)).files) + await readFile2(join2(projectDir, "onceworlds.json"), "utf8").catch(() => "");
   let lastSignature = await projectSignature();
   let timer;
   let running = false;
@@ -388,11 +1030,36 @@ async function dev(projectDir, api, tokenArg) {
   await new Promise(() => {
   });
 }
+async function readSources(files) {
+  const sources = [];
+  for (const file of files) {
+    if (!/\.(html?|m?js|css)$/i.test(file.path) || file.size > 15e5) continue;
+    sources.push({ path: file.path, text: await readFile2(file.abs, "utf8") });
+  }
+  return sources;
+}
+async function doctor(projectDir, strict) {
+  const config = await loadConfig(projectDir);
+  const root = resolve(projectDir, config.dir ?? ".");
+  const { files } = await collectFiles(root);
+  const sources = await readSources(files);
+  const findings = [...checkGame(sources), ...checkListing(config)];
+  console.log(`Checked ${sources.length} file${sources.length === 1 ? "" : "s"} in ${root}.`);
+  if (findings.length === 0) {
+    console.log("Nothing to suggest.");
+    return;
+  }
+  for (const f of findings) console.log(`  ${f.level === "warn" ? "!" : "\xB7"} ${f.file}:${f.line}  ${f.message}`);
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  console.log(`
+${warnings} likely problem${warnings === 1 ? "" : "s"}, ${findings.length - warnings} note${findings.length - warnings === 1 ? "" : "s"}. Nothing here stops a deploy.`);
+  if (strict && warnings > 0) process.exitCode = 1;
+}
 async function loadConfig(projectDir) {
-  const file = join(projectDir, "onceworlds.json");
+  const file = join2(projectDir, "onceworlds.json");
   let config;
   try {
-    config = JSON.parse(await readFile(file, "utf8"));
+    config = JSON.parse(await readFile2(file, "utf8"));
   } catch (err) {
     const missing = err.code === "ENOENT";
     throw new CliError(missing ? `No onceworlds.json in ${projectDir}.
@@ -413,7 +1080,7 @@ async function loadStore(projectDir, config) {
     if (!abs.startsWith(projectDir + sep)) throw new CliError(`"${field}" in onceworlds.json (${value}) must be inside the project folder.`);
     let data;
     try {
-      data = await readFile(abs);
+      data = await readFile2(abs);
     } catch {
       throw new CliError(`"${field}" in onceworlds.json: ${value} doesn't exist.`);
     }
@@ -460,7 +1127,16 @@ async function loadStore(projectDir, config) {
     const badgeIcon = b.icon === void 0 ? null : await image(b.icon, "badge", `${field}.icon`);
     badges.push({ key, name, description, icon: badgeIcon });
   }
-  return { store: { genre, icon, thumbnails, badges }, images: [...images.values()] };
+  let guide;
+  try {
+    guide = checkGuide(config.controls, config.help);
+  } catch (err) {
+    throw new CliError(`${err.message} in onceworlds.json.`);
+  }
+  const store = { genre, icon, thumbnails, badges };
+  if (guide.controls.length > 0) store.controls = guide.controls;
+  if (guide.help) store.help = guide.help;
+  return { store, images: [...images.values()] };
 }
 async function collectFiles(root) {
   const files = [];
@@ -468,13 +1144,13 @@ async function collectFiles(root) {
   async function walk(dir, prefix) {
     let entries;
     try {
-      entries = await readdir(dir, { withFileTypes: true });
+      entries = await readdir2(dir, { withFileTypes: true });
     } catch {
       throw new CliError(`Cannot read ${dir}. Check "dir" in onceworlds.json.`);
     }
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
       if (entry.name.startsWith(".") || QUIET_SKIPS.has(entry.name)) continue;
-      const abs = join(dir, entry.name);
+      const abs = join2(dir, entry.name);
       const path = prefix + entry.name;
       if (entry.isDirectory()) {
         await walk(abs, `${path}/`);
@@ -483,7 +1159,7 @@ async function collectFiles(root) {
           if (!QUIET_EXTENSIONS.has(extensionOf(path))) skipped.push(path);
           continue;
         }
-        const data = await readFile(abs);
+        const data = await readFile2(abs);
         if (data.byteLength > LIMITS.deployFileBytes) {
           throw new CliError(`${path} is ${formatBytes(data.byteLength)}; files can be at most ${formatBytes(LIMITS.deployFileBytes)}.`);
         }
@@ -501,7 +1177,7 @@ function signature(files) {
 function gitInfo(cwd) {
   const run = (args) => {
     try {
-      return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || void 0;
+      return execFileSync2("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || void 0;
     } catch {
       return void 0;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onceworlds/cli",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Deploy games to Onceworlds.",
   "homepage": "https://onceworlds.com",
   "type": "module",