@homie-rocks/studio 0.32.0 → 0.32.1

package/CHANGELOG.md

@@ -17,9 +17,36 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.32.1] - 2026-10-07
+
+**Plugin 0.33.1** · [#55](https://github.com/homie-rocks/homie/pull/55)
+
+A standalone game can be put on your own iPhone or iPad with one command, and the guide says what has now been run on a real phone and corrects what an older site means for a copy.
+
+### Added
+
+- **`homie-studio standalone run <game> --for ios --device`** builds the game for the one iPhone or iPad plugged in to your Mac, signs it for your Apple team, installs it over the cable, starts it, and then looks for it among the phone's running programs. It says the game is running only when it found it there. In chat it is `game_standalone` with `device: true`.
+- **`--device` is your yes to what that changes outside your computer.** It adds the phone to your Apple team's list of development devices (a team may register a limited number a year, and a device stays on the list until the membership year renews) and lets Xcode make a development profile for the app. The app is signed for that phone only: a build to try, never one for the store.
+- Every way it can stop is an answer with what to do: no phone connected, more than one (it lists them by model and builds nothing), Developer Mode off (on the phone: Settings, Privacy & Security, Developer Mode; the phone restarts), a phone that does not trust the Mac, a locked phone (it waits a minute for you to unlock it), no Apple account signed in to Xcode, a team with no registered phone, a build that failed. It never says or returns the phone's id, its name or your team's id.
+- The team is `HOMIE_APPLE_TEAM`, else the one team among your keychain's development identities; it says which it used. With none, or more than one, it stops and asks for `HOMIE_APPLE_TEAM`.
+- `setup status` and `standalone plan` have a row for a phone to try a build on: which model is connected and whether its Developer Mode is on, or "could not check".
+
+### Fixed
+
+- **What an older site means for a copy was said too broadly.** Only **Quick play** needs your live site on 0.32.0 or later: it asks the site which room to join, and an older site does not let an app read the answer. A room made in the app or joined by its code connects through an older site too. We saw that against a site on 0.31.0; it is not promised for every older version. The plan, the build, the chat tool, the skill and the guide now say this.
+
+### Changed
+
+- The guide's "What has been run and what has not" now has what was run on 2026-10-07: an iOS build on a real iPhone, signed for a development team and installed over the cable, playing offline with its bots, and an online private room from that phone through a studio's live site. The new command built, signed and installed a game on that iPhone; the phone was locked, so its last two steps (starting the game and finding it running) have been run against stand-ins only. Still never run: anything under Steam, Developer ID signing and notarization, the iOS archive for the App Store, the GitHub workflow, the Windows and Linux builds started on any computer, a real Android phone, and Quick play online from a phone.
+
+### Upgrade notes
+
+- A run on a phone needs a Mac with Xcode signed in to your Apple account, and the phone unlocked, trusting the Mac, with Developer Mode on.
+- There is no `--device` for an Android phone yet: `standalone run <game> --for android` hands over to Capacitor, which asks which phone or emulator. That has been run on an emulator only.
+
 ## [0.32.0] - 2026-10-06
 
-**Plugin 0.33.0** · [#54](https://github.com/homie-rocks/homie/pull/54)
+**Plugin 0.33.0** · [#54](https://github.com/homie-rocks/homie/pull/54) · [release-2026-10-06-studio-0.32.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-06-studio-0.32.0)
 
 A game can now be an app of its own: a desktop app for macOS, Windows and Linux and a phone app for iOS and Android, the same web game in a thin shell that still plays through your studio's own site.
 
@@ -46,7 +73,7 @@ A game can now be an app of its own: a desktop app for macOS, Windows and Linux
 
 ### Upgrade notes
 
-- **Upgrade and deploy before a standalone copy can find rooms.** A copy talks to your live site, and only a site deployed with 0.32.0 or later answers it. Until then every copy plays offline.
+- **Upgrade and deploy before Quick play can find a room in a standalone copy.** Quick play asks your live site which room to join, and only a site deployed with 0.32.0 or later lets an app read the answer. Until then Quick play is offline with the game's bots. (Corrected in 0.32.1: a room made or joined by its code connects through an older site too.)
 - The address of your site is built into every copy and cannot be changed in a copy that has shipped. Put the studio on its own domain before you ship: a workers.dev address belongs to the Cloudflare account.
 - Before you ship, name the game's revision in `game.json` (`"netplay": { "version": "1" }`) and raise it with every change an older copy cannot play with. Older copies then keep playing with each other, and say "Update <Name> to play online with everyone." when they meet a newer one.
 - In an app the game's code is trusted with everything the app's page has, and on phones with Capacitor's native bridge. That is fine for your own code; do not load scripts from the network in a game you ship as an app.

package/README.md

@@ -823,12 +823,19 @@ every other target says "built, not started on this computer".
 
 **What the standalone game does not have (v1):** player accounts and sign-in, cloud saves (saves stay on the
 device and are lost when the app is uninstalled), the shop, room chat, watching and the big screen, servers
-other than the public one, automatic updates, and a signed Windows build. A studio must be on 0.32.0 or later
-**and deployed** before a copy can find rooms.
+other than the public one, automatic updates, and a signed Windows build. For Quick play to find a room, a
+studio must be on 0.32.0 or later **and deployed**; a room made or joined by its code works with an older site
+too (seen against 0.31.0, not promised for every older version).
+
+**On your own iPhone or iPad:** `standalone run <id> --for ios --device` builds the game for the one phone
+plugged in, signs it for your Apple team, installs it over the cable, starts it and looks for it among the
+phone's running programs. `--device` is your yes to what it changes: it adds the phone to your Apple team's list
+of development devices.
 
 **What has not been run:** the Windows and Linux builds have never been started; nothing has been started by
 Steam (its overlay, which Electron apps often do not show, included); a Developer ID signature, notarization and
-the iOS archive have never been made; nothing has run on a real phone. The guide lists it all.
+the iOS archive have never been made; nothing has run on a real Android phone, and Quick play has not been seen
+online from a phone. The guide lists it all.
 
 ## How it feels: the Game Lab (`homie-studio lab`)
 

package/bin/homie-studio.mjs

@@ -295,6 +295,13 @@
  *                                          id, and an unsigned release is said as UNSIGNED and is not a success); run:
  *                                          the built copy, here; steam: Steam's build file; ci: a GitHub workflow that
  *                                          builds all five. Nothing is ever uploaded to Steam or a store
+ *   homie-studio standalone run <game> --for ios --device
+ *                                         the game on the ONE iPhone or iPad plugged in to this Mac: built, signed for
+ *                                          your Apple team (HOMIE_APPLE_TEAM, else the keychain's only one), installed
+ *                                          over the cable, started, and then looked for among the phone's running
+ *                                          programs. --device is your yes to what it changes outside this computer: it
+ *                                          adds the phone to your Apple team's list of development devices. A phone with
+ *                                          Developer Mode off, locked, or not trusting this Mac is said with its fix
  *
  *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
  *   homie-studio statusline --install [--project <folder>]
@@ -361,7 +368,7 @@ import { standaloneDeployNotes } from '../lib/standalone.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release'];
+const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before', 'release', 'device'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -806,6 +813,8 @@ const OUTWARD_FLAGS = {
   'shop connect': ['url', 'managed', 'live'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send'],
   'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
   'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+  // With --device it adds a phone to the person's Apple team and installs on it: a flag it does not know stops it.
+  'standalone run': ['for', 'device', 'site'],
 };
 /** Every command takes these: how it answers, never what it does. */
 const ANY_COMMAND = ['json', 'help', 'version'];

package/lib/standalone-cli.mjs

@@ -9,6 +9,10 @@
  *   standalone build <game> [--for …] [--release] [--site <address>] [--build <n>]
  *       builds the game for the web, then every target this computer can make; one it cannot is skipped with why.
  *   standalone run <game> [--for ios|android]      the built copy, started here (none: this computer's desktop app)
+ *   standalone run <game> --for ios --device       built for the one iPhone or iPad plugged in, signed for the person's
+ *       Apple team (HOMIE_APPLE_TEAM, else the keychain's only one), installed over the cable, started, and then looked
+ *       for among the phone's running programs. --device is the yes to what it changes: the phone is added to the Apple
+ *       team's list of development devices.
  *   standalone steam <game>                        Steam's build files from game.json's numbers; uploads nothing
  *   standalone ci <game>                           .github/workflows/standalone.yml: every target on GitHub's machines
  *
@@ -35,7 +39,9 @@ export async function standaloneCommand(root, sub, positional, flags, { log = ()
   switch (sub ?? 'plan') {
     case 'plan': return told(await standalonePlan(root, id, opts));
     case 'build': return told(await standaloneBuild(root, id, opts));
-    case 'run': return standaloneRun(root, id, { for: flags.has('for') ? flags.get('for') : null });
+    // --device: onto the one iPhone or iPad that is plugged in. It is the person's yes to what that changes outside
+    // this computer (DEVICE_ADDS), and the result carries its own words like a build's.
+    case 'run': { const r = await standaloneRun(root, id, { for: flags.has('for') ? flags.get('for') : null, device: flags.has('device'), site: str('site'), log, ...on }); return r?.device ? { ...r, say: standaloneLines(r) } : r; }
     case 'steam': return standaloneSteam(root, id);
     case 'ci': return standaloneCi(root, id);
     default: return { ok: false, command: 'standalone', why: `"${sub}" is not a standalone command: ${STANDALONE_VERBS.join(', ')}` };
@@ -52,8 +58,30 @@ export function missingLines(missing) {
   return ['What the standalone game does not have (v1):', ...missing.map((m) => `  - ${m.what}: ${m.why}.`)];
 }
 
+/** A run on a real phone: what happened, in the order a person needs it, with what it changed outside this computer. */
+function deviceLines(r) {
+  const L = [];
+  const on = r.phone?.model ? `the ${r.phone.model}` : 'the phone';
+  if (r.ok) {
+    L.push(`${r.name} is on ${on} and running: it was built, installed over the cable, started, and then found among the phone's running programs.`,
+      `  Signed for ${r.team.from === 'HOMIE_APPLE_TEAM' ? 'the team HOMIE_APPLE_TEAM names' : r.team.from}, as ${r.appId}${r.appIdFrom === 'derived' ? ' (a made-up id for trying a build)' : ''}.`,
+      `  ${r.adds}`, ...r.notes.map((n) => `  ${n}`));
+  } else {
+    L.push(`NOT on ${r.phone?.model ? on : 'a phone'}: ${r.why}.`);
+    if (r.fix) L.push(`  ${r.fix}`);
+    if (r.installed) L.push(`  The game IS installed on ${on}; it was not seen running.`);
+    else if (r.built) L.push('  The app was built and signed; it is not on the phone.');
+    // What it may already have changed outside this computer, said even when the rest did not work.
+    if (r.team && r.built) L.push('  The build was signed: the phone is on your Apple team\'s list of development devices now, if it was not before.');
+    else if (r.team && r.stage === 'build-failed') L.push('  The build stopped before the app was made; it may have added the phone to your Apple team\'s list of development devices on the way.');
+  }
+  for (const w of r.warnings ?? []) L.push(`Warning: ${w}`);
+  return L;
+}
+
 export function standaloneLines(r) {
   const L = [];
+  if (r.command === 'standalone run' && r.device) return deviceLines(r);
   // A refusal with something to do about it (a release with no id yet, Steam with no numbers) still says it all.
   if (r.ok === false && !r.targets && !r.rows) { L.push(r.why ?? 'failed'); if (r.instead) L.push('', r.instead); return L; }
   switch (r.command) {
@@ -89,7 +117,7 @@ export function standaloneLines(r) {
       break;
     }
     case 'standalone run':
-      L.push(`${r.game} (${r.target}) ended.`);
+      if (r.device) L.push(...deviceLines(r)); else L.push(`${r.game} (${r.target}) ended.`);
       break;
     case 'standalone steam':
       L.push(`Steam's build file for app ${r.app}: ${r.dir}/${r.wrote.join(', ')} (each depot is that system's release build, out/<system>/release/).`,

package/lib/standalone-tools.mjs

@@ -11,20 +11,25 @@
  * Nothing is ever uploaded to Steam or a store from here, and no signing key is taken in chat: a release reads the
  * environment only. What the standalone game does not have is said to the person as it is, every time.
  */
+import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { SAY_MISSING, standaloneLines } from './standalone-cli.mjs';
-import { STANDALONE_SINCE, standalonePlan, toolkitNote } from './standalone.mjs';
+import { compareVersions } from './changelog.mjs';
+import { DEVICE_ADDS, STANDALONE_SINCE, standalonePlan, toolkitNote } from './standalone.mjs';
+import { pinnedVersion } from './upgrade.mjs';
 import { TARGETS } from './standalone-files.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
 export { SAY_MISSING };
+/** The first toolkit with `standalone run --device`. */
+export const DEVICE_SINCE = '0.32.1';
 
 export function standaloneToolDefs(ctx, h) {
   const { ok, fail, cli, stillRunning, whyOf, needsInstall, str, STUDIO_ARG } = h;
   return [
     {
       name: 'game_standalone', title: 'Make a standalone game',
-      description: `Make one of the studio's games into an app of its own: a desktop app for macOS, Windows and Linux (the kind of build Steam accepts for upload) and a phone app for iOS and Android (the files the App Store and Google Play accept for upload; each store's review, fees and rules are its own, and nothing here makes an app pass). It is the same web build of the game in a thin shell (Electron on computers, Capacitor on phones); multiplayer still goes through the studio's own deployed site, and with no connection the game plays offline with its bots. Use it when the person asks for a Steam build, a desktop app, a download, an iPhone or Android app, or "a standalone version". ALWAYS call it with plan: true first and tell the person what it says: which targets this computer can build and what the others need, the address that gets built into every copy, and what a standalone copy does NOT have in this version (no player accounts, no cloud saves: saves stay on the device and are lost when the app is uninstalled, no shop, no chat). Then, when they say go, call it again without plan: it builds as a background job that takes minutes (the first build downloads the wrapper tools into the studio's .studio/ folder): it answers with a job, and studio_job { "job": … } gives the result in words when it is done; read that result to the person, including its list of what the standalone game does not have. A target whose tool is missing on this computer is skipped with its fix and the others still build; only the desktop build for this computer's own system is started once to see that the game loads, and every other build says "built, not started on this computer". It never uploads anything and never signs with a key from the chat: a release (release: true) signs from environment variables the person sets themselves, needs the app's id written in game.json first (the tool gives the exact lines), and says UNSIGNED when it could not sign. The studio must be on @homie-rocks/studio ${STANDALONE_SINCE} or later AND deployed before a copy can find rooms.`,
+      description: `Make one of the studio's games into an app of its own: a desktop app for macOS, Windows and Linux (the kind of build Steam accepts for upload) and a phone app for iOS and Android (the files the App Store and Google Play accept for upload; each store's review, fees and rules are its own, and nothing here makes an app pass). It is the same web build of the game in a thin shell (Electron on computers, Capacitor on phones); multiplayer still goes through the studio's own deployed site, and with no connection the game plays offline with its bots. Use it when the person asks for a Steam build, a desktop app, a download, an iPhone or Android app, or "a standalone version". ALWAYS call it with plan: true first and tell the person what it says: which targets this computer can build and what the others need, the address that gets built into every copy, and what a standalone copy does NOT have in this version (no player accounts, no cloud saves: saves stay on the device and are lost when the app is uninstalled, no shop, no chat). Then, when they say go, call it again without plan: it builds as a background job that takes minutes (the first build downloads the wrapper tools into the studio's .studio/ folder): it answers with a job, and studio_job { "job": … } gives the result in words when it is done; read that result to the person, including its list of what the standalone game does not have. A target whose tool is missing on this computer is skipped with its fix and the others still build; only the desktop build for this computer's own system is started once to see that the game loads, and every other build says "built, not started on this computer". It never uploads anything and never signs with a key from the chat: a release (release: true) signs from environment variables the person sets themselves, needs the app's id written in game.json first (the tool gives the exact lines), and says UNSIGNED when it could not sign. In a copy, Quick play finds a room only when the studio's live site is on @homie-rocks/studio ${STANDALONE_SINCE} or later AND deployed since; a room made or joined by its code works with an older site too (seen against 0.31.0, not promised for every older version). ON THE PERSON'S OWN iPHONE OR iPAD: device: true builds the game for the one phone plugged in to this Mac, signs it for their Apple team, installs it over the cable, starts it, and then looks for it among the phone's running programs (it says "running" only when it is there). ${DEVICE_ADDS} So call it with device: true only after the person said yes to that, in those words; it needs a Mac with Xcode signed in to their Apple account, the phone unlocked and trusting the Mac, and Developer Mode on (Settings, Privacy & Security, Developer Mode; the phone restarts). It is a background job too. There is no such run for an Android phone in this version.`,
       inputSchema: {
         type: 'object',
         properties: {
@@ -32,6 +37,7 @@ export function standaloneToolDefs(ctx, h) {
           for: { type: 'array', items: { type: 'string', enum: [...TARGETS] }, description: 'Which to build (default: every one this computer can make)' },
           plan: { type: 'boolean', description: 'Only say what would be built and what is missing; build nothing, install nothing. Do this first' },
           release: { type: 'boolean', description: 'A build for a store or Steam: needs "standalone.appId" in the game\'s game.json, and signs from the environment. Only when the person asked for a release' },
+          device: { type: 'boolean', description: 'Put the game on the one iPhone or iPad plugged in to this Mac and start it. It adds the phone to the person\'s Apple team\'s list of development devices: only after they said yes to that' },
           ...STUDIO_ARG,
         },
         required: ['game'],
@@ -50,6 +56,18 @@ export function standaloneToolDefs(ctx, h) {
         }
         const need = needsInstall(ctx, root);
         if (need) return need;
+        if (a.device === true) {
+          // The run on a phone arrived in 0.32.1: a studio whose own toolkit is older has no such flag (and would
+          // read the words as a different command), so this toolkit's runs.
+          let pinned = null;
+          try { const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']); } catch { pinned = null; }
+          const ours = pinned && compareVersions(pinned, DEVICE_SINCE) < 0;
+          const r = await cli(ctx, root, `standalone run ${game} on a phone`, ['standalone', 'run', game, '--for', 'ios', '--device'], ours ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {});
+          if (!r.ended) return stillRunning(r.job, `Putting ${game} on the phone (it takes minutes the first time; its last lines say where it is)`);
+          if (!r.result?.device) return fail(`Not on the phone: ${whyOf(r.job)}`, r.result ? { kind: 'standalone-device', ...r.result } : undefined);
+          const text = (r.result.say ?? standaloneLines(r.result)).join('\n');
+          return r.result.ok ? ok(text, { kind: 'standalone-device', ...r.result }) : fail(text, { kind: 'standalone-device', ...r.result });
+        }
         const args = ['standalone', 'build', game, ...(only ? ['--for', only] : []), ...(a.release === true ? ['--release'] : [])];
         const r = await cli(ctx, root, `standalone build ${game}`, args, old ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {});
         // The words are in the result itself (`say`), so studio_job says them too when the build outlasts this call.

package/lib/standalone.mjs

@@ -24,8 +24,9 @@
  * "built, not started on this computer". A release that could not be signed is said as UNSIGNED and is not `ok`.
  */
 import { spawn } from 'node:child_process';
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { X509Certificate } from 'node:crypto';
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, relative } from 'node:path';
 import { build as buildSite, uiOf } from './build.mjs';
 import { compareVersions } from './changelog.mjs';
@@ -222,6 +223,20 @@ export async function standaloneRows({ platform = process.platform, exec = runTo
       fix: mac && team ? null : { who: 'person', open: 'https://developer.apple.com/account#MembershipDetailsCard', say: `With an Apple Developer membership: sign in to it in Xcode (Settings, Accounts), and put your team id (ten letters and digits, on that page) in HOMIE_APPLE_TEAM. ${ENV_HOW}` },
     });
   }
+  // A phone for trying a build on (standalone run --for ios --device): what Xcode's own device list says is
+  // connected now, by model, and whether its Developer Mode is on. Nothing is asked of the phone itself.
+  if (mac) {
+    const found = await phones({ exec, env });
+    const here = found.ok ? found.phones.filter((p) => p.here) : [];
+    const ready = here.filter((p) => p.trusted && p.developerMode === true);
+    const one = (p) => `${p.model}${!p.trusted ? ', which does not trust this Mac yet' : p.developerMode === true ? ', Developer Mode on' : p.developerMode === false ? ', Developer Mode OFF' : ', Developer Mode not known'}`;
+    rows.push({
+      id: 'standalone-phone', label: 'A phone for trying a build', need: 'optional', state: !found.ok ? 'unknown' : ready.length === 1 && here.length === 1 ? 'ok' : 'optional',
+      detail: !found.ok ? `could not check (${found.why})` : here.length ? `connected: ${here.map(one).join('; ')}${here.length > 1 ? ' (a run takes one phone: unplug the others)' : ''}` : 'no iPhone or iPad is connected now',
+      unlocks: 'the game on your own iPhone or iPad, over the cable (standalone run <game> --for ios --device): it adds the phone to your Apple team\'s device list',
+      fix: !found.ok || (ready.length === 1 && here.length === 1) ? null : !here.length ? { who: 'person', say: 'Plug the phone in with a cable, unlock it, and tap Trust if it asks about this computer.' } : here.some((p) => !p.trusted) ? { who: 'person', say: deviceTrouble('not paired').fix } : here.some((p) => p.developerMode !== true) ? { who: 'person', say: deviceTrouble('Developer Mode disabled').fix } : { who: 'person', say: 'Unplug all but the one phone to try the game on.' },
+    });
+  }
   // steamcmd: only to upload, which a person does.
   {
     const r = await exec(platform === 'win32' ? 'where' : 'which', ['steamcmd'], { timeout: 5000 });
@@ -292,7 +307,7 @@ export function toolkitNote(root) {
   try { pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); } catch { return null; }
   const pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']);
   if (!pinned || compareVersions(pinned, STANDALONE_SINCE) >= 0) return null;
-  return `This studio pins @homie-rocks/studio ${pinned}, from before standalone copies (${STANDALONE_SINCE}): its live site cannot answer a standalone copy, so every copy plays OFFLINE until the studio is upgraded to ${STANDALONE_SINCE} or later AND deployed again.`;
+  return `This studio pins @homie-rocks/studio ${pinned}, from before standalone copies (${STANDALONE_SINCE}): its live site does not let a standalone copy read which room to join, so in a copy Quick play is OFFLINE until the studio is upgraded to ${STANDALONE_SINCE} or later AND deployed again. A room made or joined by its code still connects (seen against 0.31.0, not promised for every older version).`;
 }
 
 /** Everything a plan and a build both need to know, read once. */
@@ -366,7 +381,7 @@ export async function standalonePlan(root, id, opts = {}) {
     icon: { from: s.icon.from, note: s.icon.note }, steam: s.meta.steam,
     dir: relative(root, s.dir), targets, rows: s.rows, warnings: s.warnings, missing: MISSING, pins: STANDALONE_PINS,
     ...(s.note ? { toolkitNote: s.note } : {}),
-    needs: `The live site must run @homie-rocks/studio ${STANDALONE_SINCE} or later for a copy to find rooms (upgrade the studio, then deploy). This plan did not ask the site which version it runs.`,
+    needs: `Quick play finds a room only when the live site runs @homie-rocks/studio ${STANDALONE_SINCE} or later (upgrade the studio, then deploy). A room made or joined by its code works with an older site too (seen against 0.31.0, not promised for every older version). This plan did not ask the site which version it runs.`,
     ...(refused ? { why: refused.why, instead: refused.instead, needsField: 'appId' } : {}),
   };
 }
@@ -560,15 +575,22 @@ async function capProject(s, platform, { say }) {
 const patch = (file, fn) => { if (!existsSync(file)) return false; const before = readFileSync(file, 'utf8'); const after = fn(before); if (after !== before) writeFileSync(file, after); return true; };
 const freshOut = (s, target) => { const out = join(s.dir, 'out', target, s.kind); rmSync(out, { recursive: true, force: true }); mkdirSync(out, { recursive: true }); return out; };
 
-async function buildIos(s, { say }) {
+/** The iOS project with this build's web folder in it, ready for xcodebuild: { ok, notes, project } or { ok: false, why }. */
+async function iosProject(s, { say }) {
   const p = await capProject(s, 'ios', { say });
-  if (!p.ok) return { state: 'failed', why: p.why };
+  if (!p.ok) return { ok: false, why: p.why };
   const notes = [...p.notes];
   if (!patch(join(s.dir, 'ios', 'App', 'App', 'Info.plist'), (t) => patchInfoPlist(t, s.meta.orientation))) notes.push('Info.plist was not where Capacitor puts it: the way the game is held was not set');
   const sync = await tool(s, 'cap', ['sync', 'ios'], { env: p.env, timeout: 15 * 60_000 });
-  if (sync.code !== 0) return { state: 'failed', why: `cap sync ios failed: ${tail(sync)}` };
+  if (sync.code !== 0) return { ok: false, why: `cap sync ios failed: ${tail(sync)}` };
   const app = join(s.dir, 'ios', 'App');
-  const project = existsSync(join(app, 'App.xcworkspace')) ? ['-workspace', join(app, 'App.xcworkspace')] : ['-project', join(app, 'App.xcodeproj')];
+  return { ok: true, notes, project: existsSync(join(app, 'App.xcworkspace')) ? ['-workspace', join(app, 'App.xcworkspace')] : ['-project', join(app, 'App.xcodeproj')] };
+}
+
+async function buildIos(s, { say }) {
+  const p = await iosProject(s, { say });
+  if (!p.ok) return { state: 'failed', why: p.why };
+  const { notes, project } = p;
   const derived = join(s.dir, 'ios', 'build');
   const version = [`MARKETING_VERSION=${s.meta.version}`, `CURRENT_PROJECT_VERSION=${s.meta.build}`];
   const env = toolEnv(s.env);
@@ -753,9 +775,18 @@ export async function standaloneBuild(root, id, opts = {}) {
 /* ------------------------------------------------------------------ run, steam, ci, deploy */
 
 /** `standalone run <game> [--for mac|windows|linux|ios|android]`: the copy that was built, started here. */
-export async function standaloneRun(root, id, { for: said = null, platform = process.platform, env = process.env, exec = runTool, home = homedir() } = {}) {
+export async function standaloneRun(root, id, opts = {}) {
+  const { for: said = null, platform = process.platform, env = process.env, exec = runTool, home = homedir(), device = false } = opts;
   const g = gameOf(root, id);
   if (g.why) return { ok: false, command: 'standalone run', why: g.why };
+  // --device: onto the one phone that is plugged in (runOnPhone). It is the person's yes to what that changes.
+  if (device) {
+    const asked = targetsOf(said ?? 'ios');
+    if (asked.why || asked.targets.length !== 1) return { ok: false, command: 'standalone run', why: asked.why ?? '--device takes one target: --for ios' };
+    if (asked.targets[0] === 'android') return { ok: false, command: 'standalone run', why: '--device is for an iPhone or iPad in this version. For an Android phone, leave --device out: `standalone run <game> --for android` hands over to Capacitor, which lists the phones and emulators it finds over adb and asks which one. That has been run on an emulator, never on a real Android phone.' };
+    if (asked.targets[0] !== 'ios') return { ok: false, command: 'standalone run', why: `--device puts the game on a phone: --for ios. A ${asked.targets[0]} build runs on a computer (leave --device out).` };
+    return runOnPhone(root, id, opts);
+  }
   const dir = standaloneDir(root, g.game.id);
   const host = { darwin: 'mac', win32: 'windows', linux: 'linux' }[platform] ?? 'linux';
   const t = targetsOf(said ?? host);
@@ -865,4 +896,179 @@ export function standaloneDeployNotes(root) {
   return notes;
 }
 
+/* ------------------------------------------------------------------ a real iPhone or iPad */
+
+/** What `--device` changes outside this computer, said before it happens, in the result, in the tool and in the skill. */
+export const DEVICE_ADDS = 'This adds the phone to your Apple team\'s list of development devices (a team may register a limited number a year, and a device stays on the list until the membership year renews) and lets Xcode make a development profile for this app. Apple signs the app for that phone only: it is a build to try, never one for the store.';
+
+/** A devicectl command whose answer is a JSON file: { r, json } (json null when it wrote none). */
+async function jsonOf(s, args, { timeout = 60_000 } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'standalone-device-'));
+  const file = join(dir, 'out.json');
+  const r = await s.exec('xcrun', ['devicectl', ...args, '--json-output', file], { env: toolEnv(s.env), timeout });
+  let json = null;
+  try { json = JSON.parse(readFileSync(file, 'utf8')); } catch { json = null; }
+  rmSync(dir, { recursive: true, force: true });
+  return { r, json };
+}
+
+/**
+ * The iPhones and iPads this Mac knows, as Xcode's own devicectl lists them: { ok, phones: [{ id, udid, model,
+ * trusted, here, developerMode }] } or { ok: false, why }. `here`: plugged in or on the network now. An id never
+ * leaves this module in a result or a line: a person is told a phone by its model.
+ */
+export async function phones({ exec = runTool, env = process.env } = {}) {
+  const { r, json } = await jsonOf({ exec, env }, ['list', 'devices']);
+  const list = json?.result?.devices;
+  if (r.code !== 0 || !Array.isArray(list)) return { ok: false, why: r.code === 127 ? 'xcrun is not here (Xcode is not installed)' : `Xcode's device list did not answer (${tail(r, 2) || `code ${r.code}`})` };
+  return {
+    ok: true,
+    phones: list.filter((d) => d?.hardwareProperties?.reality === 'physical' && ['iPhone', 'iPad'].includes(d?.hardwareProperties?.deviceType)).map((d) => ({
+      id: String(d.identifier ?? ''), udid: String(d.hardwareProperties.udid ?? ''), model: String(d.hardwareProperties.marketingName ?? d.hardwareProperties.deviceType),
+      trusted: d.connectionProperties?.pairingState === 'paired', here: ['connected', 'disconnected'].includes(d.connectionProperties?.tunnelState),
+      developerMode: d.deviceProperties?.developerModeStatus === 'enabled' ? true : d.deviceProperties?.developerModeStatus === 'disabled' ? false : null,
+    })),
+  };
+}
+
+const TEAM_ID = /^[A-Z0-9]{10}$/;
+/**
+ * The Apple team a build to try is signed for: HOMIE_APPLE_TEAM, else the ONE team among the keychain's development
+ * identities. An identity's name carries a person's id, not the team's: the team is in its certificate (the OU of
+ * its subject), which is read here and nothing else of it is kept. { team, from } or { team: null, why, teams }.
+ */
+export async function appleTeam({ env = process.env, exec = runTool } = {}) {
+  const said = String(env.HOMIE_APPLE_TEAM ?? '').trim();
+  if (said) return TEAM_ID.test(said) ? { team: said, from: 'HOMIE_APPLE_TEAM' } : { team: null, teams: 0, why: 'HOMIE_APPLE_TEAM is set and is not a team id (ten capital letters and digits, on your Apple Developer account\'s Membership page)' };
+  const ids = await exec('security', ['find-identity', '-v', '-p', 'codesigning'], { timeout: 10_000 });
+  if (ids.code !== 0) return { team: null, teams: 0, why: 'could not check the keychain for a development identity (the security tool did not answer)' };
+  const hashes = new Set(ids.stdout.split('\n').filter((l) => /"(Apple Development|iPhone Developer): /.test(l)).map((l) => /\b([0-9A-F]{40})\b/.exec(l)?.[1]).filter(Boolean));
+  if (!hashes.size) return { team: null, teams: 0, why: 'the keychain has no Apple Development identity: sign in to your Apple account in Xcode (Settings, Accounts), which makes one' };
+  const certs = await exec('security', ['find-certificate', '-a', '-p'], { timeout: 20_000 });
+  const teams = new Set();
+  for (const pem of certs.stdout.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g) ?? []) {
+    try {
+      const c = new X509Certificate(pem);
+      if (!hashes.has(c.fingerprint.replace(/:/g, ''))) continue;
+      const ou = /^OU=([A-Z0-9]{10})$/m.exec(c.subject)?.[1];
+      if (ou) teams.add(ou);
+    } catch { /* not a certificate this reads */ }
+  }
+  if (teams.size === 1) return { team: [...teams][0], from: 'the one Apple team among the keychain\'s development identities' };
+  return { team: null, teams: teams.size, why: teams.size ? `the keychain has development identities of ${teams.size} Apple teams, and which one is yours to say` : 'the team of the keychain\'s development identity could not be read' };
+}
+
+/**
+ * What stopped xcodebuild, devicectl or the phone, in the words a person can act on: { stage, why, fix } or null
+ * when the text is none of the things met so far (the caller then says the tool's own last lines).
+ */
+export function deviceTrouble(text) {
+  const t = String(text ?? '');
+  if (/Developer Mode disabled|enable Developer Mode|developer mode is (?:not enabled|disabled)/i.test(t)) return { stage: 'developer-mode', why: 'Developer Mode is off on the phone, so it takes no build to try', fix: 'On the phone: Settings, Privacy & Security, Developer Mode, turn it on. The phone restarts, then asks once more to turn it on: say yes, unlock it, and run this again. (The switch appears only after the phone has been plugged in to a Mac with Xcode.)' };
+  if (/No Accounts?:|No Account for Team|Add a new account in Accounts settings|not signed in|requires? (?:a|an) (?:development team|Apple ID)/i.test(t)) return { stage: 'no-account', why: 'Xcode is not signed in to an Apple account of that team, so nothing can sign the app', fix: 'Open Xcode, Settings, Accounts, add your Apple account (a free one can put a game on your own phone for a week; a Developer membership for longer), then run this again.' };
+  if (/has no devices from which to generate a provisioning profile|No profiles for '[^']*' were found/i.test(t)) return { stage: 'no-devices', why: 'your Apple team has no registered phone to make a development profile for, and Apple did not register this one', fix: 'Unlock the phone, keep it plugged in and run this again: it registers the phone. If it says the same, open the project once in Xcode (ios/App/App.xcodeproj in the standalone folder), pick the phone and press Run: Xcode registers it and says what stands in the way.' };
+  if (/device (?:is|was) (?:passcode )?locked|is locked|Unlock .* to Continue|could not be unlocked|because the device was not, or could not be, unlocked/i.test(t)) return { stage: 'locked', why: 'the phone is locked', fix: 'Unlock the phone, keep it awake and run this again.' };
+  if (/not paired|is not trusted|Trust This Computer|pairing/i.test(t)) return { stage: 'not-trusted', why: 'the phone does not trust this Mac yet', fix: 'Unlock the phone, plug it in and tap Trust when it asks about this computer (it asks for the passcode), then run this again.' };
+  if (/Timed out waiting for all destinations|Unable to find a (?:destination|device) matching/i.test(t)) return { stage: 'not-ready', why: 'Xcode waited for the phone and it never became ready', fix: 'Unlock the phone, keep it plugged in and awake, and run this again. If Xcode has never seen this phone, open Xcode once with it plugged in (Window, Devices and Simulators) and let it finish preparing the phone.' };
+  return null;
+}
+
+/**
+ * `standalone run <game> --for ios --device`: the game built for the ONE iPhone or iPad that is plugged in, signed
+ * for the person's own Apple team, installed over the cable and started, and then LOOKED FOR among the phone's
+ * running programs: "started" is said only when it is there. Every way it can stop is an answer with what to do.
+ * Nothing of the phone or the team is in the result but the phone's model and where the team's id was found.
+ */
+async function runOnPhone(root, id, opts = {}) {
+  const say = opts.log ?? (() => {});
+  const command = 'standalone run';
+  const stop = (stage, why, extra = {}) => ({ ok: false, command, target: 'ios', device: true, stage, why, ...extra });
+  if ((opts.platform ?? process.platform) !== 'darwin') return stop('not-a-mac', 'a game goes onto an iPhone from a Mac with Xcode');
+  const s = await survey(root, id, { ...opts, for: 'ios', release: false });
+  if (s.why) return stop('game', s.why);
+  const g = gate('ios', s);
+  if (g) return stop('xcode', g.why, { game: s.game.id, row: g.row?.id ?? null, fix: g.row?.fix?.say ?? null });
+  const base = { game: s.game.id, name: s.meta.name, appId: s.meta.appId, appIdFrom: s.meta.appIdFrom, site: s.where.url || null, warnings: s.warnings, adds: DEVICE_ADDS };
+  // The phone: exactly one, trusted, here, with Developer Mode on.
+  const found = await phones(s);
+  if (!found.ok) return stop('could-not-check', `could not look for a phone: ${found.why}`, base);
+  const here = found.phones.filter((p) => p.here);
+  if (!here.length) {
+    const known = found.phones.length;
+    return stop('no-phone', known ? `no iPhone or iPad is connected now (this Mac knows ${known}: ${found.phones.map((p) => p.model).join(', ')})` : 'no iPhone or iPad is connected to this Mac', { ...base, fix: 'Plug the phone in with a cable, unlock it, and tap Trust if it asks about this computer. Then run this again.' });
+  }
+  if (here.length > 1) return stop('several', `${here.length} phones are connected (${here.map((p) => p.model).join(', ')}), and this puts the game on one`, { ...base, phones: here.map((p) => ({ model: p.model })), fix: 'Unplug all but the one to try the game on (and turn Wi-Fi off on the others, or they stay connected over the network), then run this again.' });
+  const phone = here[0];
+  const device = { model: phone.model };
+  if (!phone.trusted) return stop('not-trusted', `the ${phone.model} does not trust this Mac yet`, { ...base, phone: device, fix: deviceTrouble('not paired').fix });
+  if (phone.developerMode === false) { const t = deviceTrouble('Developer Mode disabled'); return stop(t.stage, `Developer Mode is off on the ${phone.model}, so it takes no build to try`, { ...base, phone: device, fix: t.fix }); }
+  // The team: said, or the keychain's only one. Where it came from is said; the id is not.
+  const signer = await appleTeam(s);
+  if (!signer.team) return stop('no-team', `no Apple team to sign for: ${signer.why}`, { ...base, phone: device, fix: `Put your team id in HOMIE_APPLE_TEAM (ten capital letters and digits, on your Apple Developer account's Membership page). ${ENV_HOW}` });
+  say(`for the ${phone.model}, signed for ${signer.from === 'HOMIE_APPLE_TEAM' ? 'the team HOMIE_APPLE_TEAM names' : signer.from}`);
+  say(DEVICE_ADDS);
+  const on = { ...base, phone: device, team: { from: signer.from } };
+  // The game, built as the site builds it, in the same project a simulator build uses.
+  if (opts.buildSite !== false) {
+    say(`building ${s.game.id} for the web (the same build the site serves)`);
+    try { await (opts.buildSite ?? buildSite)(root, { only: s.game.id, log: say }); } catch (error) { return stop('build-failed', `the game did not build: ${String(error?.message ?? error)}`, on); }
+  }
+  const tools = await installTools(s, { say });
+  if (!tools.ok) return stop('build-failed', tools.why, on);
+  await writeIcons(s.dir, s.icon, { name: s.meta.name, colours: uiOf(s.game) });
+  try { webBundle(root, s.game, s.dir, { meta: s.meta, target: 'ios', site: s.where.url }); } catch (error) { return stop('build-failed', String(error?.message ?? error).split('\n')[0], on); }
+  const p = await iosProject(s, { say });
+  if (!p.ok) return stop('build-failed', p.why, on);
+  const derived = join(s.dir, 'ios', 'build-device');
+  say('xcodebuild: a Debug build for the phone, signed by Xcode for your team (the first one registers the phone and makes its profile)');
+  const b = await s.exec('xcodebuild', [...p.project, '-scheme', 'App', '-configuration', 'Debug', '-destination', `id=${phone.udid}`, '-derivedDataPath', derived, `MARKETING_VERSION=${s.meta.version}`, `CURRENT_PROJECT_VERSION=${s.meta.build}`, `DEVELOPMENT_TEAM=${signer.team}`, 'CODE_SIGN_STYLE=Automatic', '-allowProvisioningUpdates', '-allowProvisioningDeviceRegistration', 'build'], { cwd: s.dir, env: toolEnv(s.env), timeout: 40 * 60_000 });
+  const app = join(derived, 'Build', 'Products', 'Debug-iphoneos', 'App.app');
+  // What a tool printed may name the phone or the team: only its meaning, or its last lines with both taken out, is said.
+  const hush = (text) => String(text).split(phone.udid).join('<the phone>').split(phone.id).join('<the phone>').split(signer.team).join('<your team>');
+  if (b.code !== 0 || !existsSync(app)) {
+    const t = deviceTrouble(`${b.stdout}\n${b.stderr}`);
+    return t ? stop(t.stage, t.why, { ...on, fix: t.fix }) : stop('build-failed', `xcodebuild did not finish: ${hush(tail(b, 12))}`, on);
+  }
+  say(`installing it on the ${phone.model}`);
+  const i = await jsonOf(s, ['device', 'install', 'app', '--device', phone.id, app], { timeout: 10 * 60_000 });
+  if (i.r.code !== 0) {
+    const t = deviceTrouble(`${i.r.stdout}\n${i.r.stderr}`);
+    return t ? stop(t.stage, t.why, { ...on, built: true, fix: t.fix }) : stop('install-failed', `the app was built and the phone did not take it: ${hush(tail(i.r, 6))}`, { ...on, built: true });
+  }
+  // Where the phone put it, from the phone's own list of apps: every Capacitor app's program has the same name, so
+  // a running one is told from another game's by where it is installed.
+  const apps = await jsonOf(s, ['device', 'info', 'apps', '--device', phone.id], { timeout: 60_000 });
+  const listed = (apps.json?.result?.apps ?? []).find((x) => x?.bundleIdentifier === s.meta.appId);
+  if (apps.r.code === 0 && Array.isArray(apps.json?.result?.apps) && !listed) return stop('install-failed', 'the phone said it took the app, and the app is not in the phone\'s list of apps', { ...on, built: true });
+  const where = String(listed?.url ?? i.json?.result?.installedApplications?.[0]?.installationURL ?? '');
+  // A locked phone starts nothing. It is asked for now, and waited for a minute, rather than failing at the last step.
+  const wait = opts.wait ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const locked = async () => (await jsonOf(s, ['device', 'info', 'lockState', '--device', phone.id], { timeout: 30_000 })).json?.result?.passcodeRequired === true;
+  if (await locked()) {
+    say(`The ${phone.model} is locked: unlock it now (waiting up to a minute).`);
+    for (let t = 0; t < (opts.unlockMs ?? 60_000); t += 3000) { await wait(3000); if (!(await locked())) break; }
+  }
+  say('starting it');
+  const l = await jsonOf(s, ['device', 'process', 'launch', '--device', phone.id, '--terminate-existing', s.meta.appId], { timeout: 2 * 60_000 });
+  if (l.r.code !== 0) {
+    const t = deviceTrouble(`${l.r.stdout}\n${l.r.stderr}`);
+    return stop(t?.stage === 'locked' ? 'locked' : 'not-started', t?.stage === 'locked' ? 'the game is on the phone, and the phone is locked, so it was not started' : `the game is on the phone and did not start: ${hush(tail(l.r, 6))}`, { ...on, built: true, installed: true, fix: `Unlock the phone and tap ${s.meta.name} on its home screen.` });
+  }
+  const pid = Number(l.json?.result?.process?.processIdentifier);
+  // Read back: the game is among the phone's running programs a few seconds later, or it is not said to be running.
+  await wait(4000);
+  const ps = await jsonOf(s, ['device', 'info', 'processes', '--device', phone.id], { timeout: 60_000 });
+  const list = ps.json?.result?.runningProcesses;
+  if (ps.r.code !== 0 || !Array.isArray(list)) return stop('not-confirmed', 'the game was installed and asked to start, and the phone\'s running programs could not be read to see it', { ...on, built: true, installed: true, fix: `Look at the phone: ${s.meta.name} should be on its screen.` });
+  const running = list.some((x) => (Number.isFinite(pid) && Number(x?.processIdentifier) === pid) || (where && String(x?.executable ?? '').startsWith(where)));
+  if (!running) return stop('not-running', 'the game was installed and started, and four seconds later it was not among the phone\'s running programs: it closed, or crashed, as it opened', { ...on, built: true, installed: true, fix: `Tap ${s.meta.name} on the phone; if it closes again, open Xcode, Window, Devices and Simulators, the phone, and read its crash log.` });
+  return {
+    ok: true, command, target: 'ios', device: true, stage: 'started', ...on, built: true, installed: true, running: true,
+    notes: [
+      'a development build signed for this phone only: it stops opening when its profile ends (a week with a free Apple account, a year with a Developer membership), and it is not a build for the store',
+      s.where.url ? `Quick play finds a room only when ${s.where.url} runs @homie-rocks/studio ${STANDALONE_SINCE} or later; a room made or joined by its code works with an older site too` : 'this copy has no address built in: it plays offline with its bots',
+    ],
+  };
+}
+
 export { MISSING, TARGETS };

package/lib/template-history.json

@@ -1692,6 +1692,46 @@
      }
     }
    }
+  },
+  "0.32.1": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "29337e2ace95b2e7",
+    "games/README.md": "5ad32fe80c61f117",
+    "music/README.md": "a3dc042dadd39df8",
+    "videos/README.md": "16babc3437d5545b",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "732894273a32dc3f",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "8baf49e4291e7e88",
+     "## Commands (all through the pinned CLI in node_modules)": "29a04ed3d956610a",
+     "## The site": "0cb8dd9a6f8a0096",
+     "## Making games": "2da7fa74c8884834",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Art direction and models": "a48fff7bf0a5f2fc",
+     "## Running live games (the back office)": "51ebf2ab756f6e4d",
+     "## Servers and AI seats": "98d08705087a33ec",
+     "## Selling things (the shop)": "b04b0a2b25f524f2",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "2e6b29afb85dcf7e",
+     "## Telling Homie": "80b46fdd9e578db8",
+     "## Beta": "9d02638207a26e73"
+    }
+   },
+   "named": {
+    "Homie Arcade": {
+     "sections": {
+      "AGENTS.md": {
+       "## Commands (all through the pinned CLI in node_modules)": "5d1c068adda1116b"
+      }
+     }
+    }
+   }
   }
  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homie-rocks/studio",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "description": "A studio for games, music and video on its own Cloudflare: scaffold, multiplayer starters on the netplay contract, a port toolkit that makes existing single-player web games multiplayer, the site Worker with public rooms (Table/Lobby Durable Objects and D1, all on the free Workers plan, no payment method), a site with the hub's sections (Home, Games, Music, Videos, Rooms, Posts with feeds) in the studio's own look, an epic landing page for every game, big songs and videos in the studio's own R2 once it has storage (uploaded, checked by SHA-256, served at the same addresses), deploy, and the homie.rocks directory.",
   "type": "module",
   "license": "Apache-2.0",

package/standalone/STANDALONE.md

@@ -24,6 +24,7 @@ npx --no-install homie-studio standalone plan <game>      # what would be built,
 npx --no-install homie-studio standalone build <game>     # every target this computer can make
 npx --no-install homie-studio standalone build <game> --for mac,windows
 npx --no-install homie-studio standalone run <game>       # the built desktop copy, here (--for ios | android)
+npx --no-install homie-studio standalone run <game> --for ios --device   # onto the iPhone or iPad plugged in
 npx --no-install homie-studio standalone steam <game>     # Steam's build file; uploads nothing
 npx --no-install homie-studio standalone ci <game>        # a GitHub workflow that builds all five
 ```
@@ -55,7 +56,8 @@ Say this to whoever will ship it, before they do.
 
 ## What has been run and what has not
 
-This is version 1, and it says what it knows. As of 2026-10-06, by the people who wrote it, on one Mac:
+This is version 1, and it says what it knows. By the people who wrote it, on one Mac and one iPhone; each line
+was true on 2026-10-06 unless it says another day:
 
 **Run and seen:**
 
@@ -70,6 +72,16 @@ This is version 1, and it says what it knows. As of 2026-10-06, by the people wh
   environment), and the bundle carries that key's certificate.
 - The Windows build's program carries the game's icon and its name; the Linux build is a Linux program. Both
   were made on the Mac.
+- **On a real iPhone (2026-10-07).** A 3D game's iOS build was signed for a development team, installed over
+  the cable and started by hand, with the same three tools `standalone run --for ios --device` now runs. It
+  loaded and played offline with its bots.
+- **Online from that phone (2026-10-07).** A private room made in the app, joined from another device by its
+  invite link, connected through a studio's live Worker. That site was on 0.31.0, from before standalone copies.
+- **`standalone run --for ios --device` itself (2026-10-07).** It found the phone, read the team from the
+  keychain, built and signed the app for the phone and installed it; the phone's own list of apps had it. The
+  phone was locked, so the command waited a minute, said so, and stopped with "the game is on the phone, and
+  the phone is locked". Its last two steps, starting the game and finding it among the phone's running programs,
+  have been run against stand-ins only.
 
 **Never run:**
 
@@ -84,18 +96,29 @@ This is version 1, and it says what it knows. As of 2026-10-06, by the people wh
   checks the result (`codesign --verify`, `xcrun stapler validate`); it says "notarized" only when the second
   agrees. That path has not been run with a real identity. Opening a notarized app on another Mac was not tried.
 - **The iOS archive and its `.ipa`.** It needs Xcode signed in to an Apple account of your team; it was not run.
-- **Anything on a real phone**, and a phone build that plays online.
+- **Quick play online from a phone.** The one site a phone build has met was older than 0.32.0, where an app
+  cannot read the Lobby's answer: Quick play was offline there, as it should be.
+- **A real Android phone.** The Android build has run in the emulator only. `standalone run --for android` hands
+  over to Capacitor, which asks which phone or emulator; `--device` is for an iPhone or iPad.
+- **`run --device` starting a game on an unlocked phone**, and each of its answers for a phone that is not
+  ready (Developer Mode off, not trusted, no Apple account in Xcode), other than against stand-ins. The words
+  it matches for those are the ones Xcode printed on 2026-10-07.
 - **The GitHub workflow.** It is checked as text. Read the first run's log.
 - **A copy meeting a deployed site**, and an old copy meeting a newer site, outside the tests.
 - **Building from Windows or Linux.**
 
 When one of these fails for you, that is news to us: tell Homie.
 
-## Before a copy can find rooms
+## Before Quick play can find a room
 
-Your studio must be on `@homie-rocks/studio` 0.32.0 or later **and deployed**. The app's page is not served by
-your site, so it is another origin to your Worker; 0.32.0 is the first Worker that lets an app read the Lobby's
-answer. A copy pointed at an older site plays offline.
+For **Quick play**, your studio must be on `@homie-rocks/studio` 0.32.0 or later **and deployed**. The app's
+page is not served by your site, so it is another origin to your Worker; 0.32.0 is the first Worker that lets an
+app read the Lobby's answer, which is how Quick play learns which room to join. With an older site, Quick play
+is offline with the game's bots.
+
+**A room made or joined by its code does not need that.** The room's own socket never asked where a page came
+from, so "New private room" and "Join a room" connect through an older site too. That has been seen against a
+site on 0.31.0; it is not promised for every older version.
 
 The site's address is **built into every copy** (`--site <address>`, else `HOMIE_STANDALONE_SITE`, else the
 address your last deploy from this computer got). A copy that has shipped keeps it for good, so put the studio
@@ -107,6 +130,38 @@ connection for that in the app, exactly as on the web: bundle what the game must
 `index.html` carries a Content-Security-Policy that forbids inline scripts never hears the shell (a copy adds
 one inline script to that page) and plays offline only; the plan warns when it sees one.
 
+## On your own iPhone or iPad
+
+```sh
+npx --no-install homie-studio standalone run <game> --for ios --device
+```
+
+builds the game for the **one** iPhone or iPad plugged in to this Mac, signs it for your Apple team, installs it
+over the cable, starts it, and then looks for it among the phone's running programs. It says the game is running
+only when it found it there.
+
+**`--device` is your yes to what this changes outside your computer:** it adds the phone to your Apple team's
+list of development devices (a team may register a limited number a year, and a device stays on the list until
+the membership year renews) and lets Xcode make a development profile for the app. The app is signed for that
+phone only. It is a build to try, never one for the store, and it stops opening when its profile ends (a week
+with a free Apple account, a year with a Developer membership).
+
+What it needs, and what it says when one is missing:
+
+- **A Mac with Xcode, signed in to your Apple account** (Xcode, Settings, Accounts). Not signed in: it says so.
+- **Your team.** `HOMIE_APPLE_TEAM`, else the one team among the keychain's development identities (it says
+  which it used, never an identity's name). None, or more than one: it stops and asks for `HOMIE_APPLE_TEAM`.
+- **One phone, plugged in, unlocked, trusting this Mac.** None, or several: it says which models it sees and
+  builds nothing. Locked: it waits a minute for you to unlock it. Not trusted: unlock it and tap Trust.
+- **Developer Mode on**: on the phone, Settings, Privacy & Security, Developer Mode. The phone restarts and asks
+  once more. The switch appears only after the phone has been plugged in to a Mac with Xcode.
+
+Nothing it prints or returns names the phone, its id or your team's id: a phone is said by its model.
+
+For an Android phone there is no `--device` yet: `standalone run <game> --for android` hands over to Capacitor,
+with the JDK and SDK the build uses, and Capacitor asks which phone or emulator. That has been run on an
+emulator, never on a real Android phone.
+
 ## Versions: an old copy and a new site
 
 Name the game's revision in `game.json` (`"netplay": { "version": "1" }`, NETPLAY.md section 23) before you

package/worker/version.mjs

@@ -1,2 +1,2 @@
 /** The @homie-rocks/studio version this Worker code is (package.json's; a test keeps them equal). Cache-busts /_homie/site.js. */
-export const STUDIO_VERSION_TAG = '0.32.0';
+export const STUDIO_VERSION_TAG = '0.32.1';