@homie-rocks/studio 0.12.1 → 0.13.0

package/README.md

@@ -19,6 +19,7 @@ npx homie-studio deploy --plan                         # what deploy will create
 npx homie-studio deploy                                # the studio's own Cloudflare
 npx homie-studio publish                               # the homie.rocks directory
 npx homie-studio stats                                 # the studio's own numbers, for its owner
+npx homie-studio office                                 # who is playing now, in every live room (the back office)
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
@@ -72,8 +73,8 @@ site. A game made with Homie's arcade controls that knocks for a Homie box (`/__
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.12.1 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.12.1 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.13.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.13.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -139,10 +140,70 @@ npx homie-studio stats share on                         # tell the directory "pl
 Each key is minted on the owner's computer; only its SHA-256 goes into D1, through the
 studio's own Cloudflare login. `worker/stats.mjs` says exactly what is counted.
 
+## The back office: run your live games
+
+The owner sees and runs the studio's live games from `/_studio/office`, a private page
+that refreshes itself: every live room of every game (players, bots, the round, how long
+it has been up) and who is in it (each seat's handle, its device, whether it hosts, the
+browser it came from; signed-in players once a studio has player accounts). From there,
+and from a small Owner button in the owner's own play page (nobody else's page carries
+it):
+
+- **Kick** a player: they get a polite notice and cannot come back to that room for the
+  minutes the owner chose (their seat, their browser, their account; their network only
+  when asked, since a household shares one).
+- **Mute** a player: their chat and emotes reach nobody (the `say`, `chat` and `emote`
+  events; a game hides the rest with `net.isMuted(seat)`).
+- **Announce** one line to a room, a game or the whole studio: every player sees it as a
+  banner, and a game can show it its own way (`net.on('announce')`).
+- **Close** a room: everyone is sent out with a thank-you; nobody gets in until it opens.
+- Per game: **players per room**, the **launch state** (`private`: only the owner;
+  `invite`: an invite-only beta, where each invite link or code lets a browser in;
+  `public`: anyone, listed), and **remixable** (publish or withdraw the game's source).
+  A game that is not public is in no list and not in the directory manifest, so the
+  directory drops it the next time it reads the studio. A new game is private from its
+  first deploy with `"launch": "private"` in its game.json.
+
+```sh
+npx homie-studio office link                            # a one-time link that signs the owner's browser in
+npx homie-studio office link --to /crown-thief/play     # ... onto a private game, on the owner's phone
+npx homie-studio office                                 # every live room and who is in it, now
+npx homie-studio office announce "Double gems this round!" --game crown-thief
+npx homie-studio office invite crown-thief --label "Sam" --uses 1
+npx homie-studio office launch crown-thief invite       # asks: the owner confirms with one tap
+npx homie-studio office kick crown-thief pub-3 2        # asks: seat 2 of Room 3
+npx homie-studio office key                             # a key for the Homie MCP's owner tools
+```
+
+Going private or invite-only never cuts a round short: each live room finishes its current round with a notice to
+the players, then everyone the new state leaves out is sent out with a thank-you (the owner, and in a beta the
+invited, play on). Mute drops a player's `say…`, `chat…` and `emote…` events, so a game that sends its chat and
+emotes under those kinds needs nothing more (`netplay/NETPLAY.md` section 15). Kicking a whole network address is in
+the studio's API (`address: true`) and deliberately not in the office. A Preview (a branch's own unlisted address, with
+no D1) enforces no launch state and has no office.
+
+**Privacy.** The site still sets no cookie on a visitor to count or follow them. Two things are kept for the back
+office, both functional: a random room key in the play page's own storage (what a kick holds; it says nothing about
+who the player is), and, for an invited player of an invite-only beta only, their pass to that game: an HttpOnly
+cookie for that game's pages alone, for 90 days. D1 keeps only a hash of each pass.
+
+**Only the owner.** The owner's browser is signed in with the same one-time link as the
+stats (an HttpOnly session no page or game can read; games run in a sandboxed, opaque
+frame). An office key (minted with the studio's own Cloudflare login) lets the owner's AI
+look, announce and invite at once; a kick, a mute, a closed room or a launch change is only
+**asked** for, and the owner confirms it with one tap in their own browser. No key can
+confirm. The Worker signs each control with the studio's own secret and the room verifies
+it before it acts (`netplay/NETPLAY.md` section 15). Everything is in the studio's own
+Worker and D1 (migration `0003_studio_office.sql`); homie.rocks stores none of it.
+
+With player accounts (0.12.0), a signed-in player's play page names their account in its room ticket (an invited
+player's names the invite and the account), so the office shows them by name and a kick holds the account on every
+device; the owner's own passkey account (`homie-studio players owner`) counts as the owner.
+
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.12.1 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.13.0 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 

package/bin/homie-studio.mjs

@@ -40,6 +40,19 @@
  *   homie-studio players                  (player accounts and guests with saves: counts, never a passkey or an email)
  *   homie-studio players owner [--revoke] (a one-time link that marks the owner's own player account as the owner's)
  *
+ *   homie-studio office [--url <site>]    the back office: every live room of every game and who is in it, now
+ *   homie-studio office link [--to <path>]   a one-time link that signs the owner's browser in (the office; or
+ *                                          --to /<game>/play: a private game on the owner's own phone)
+ *   homie-studio office key [--hours 1]   a key for the Homie MCP's owner tools (studio_office, room_kick, ...)
+ *   homie-studio office announce "<text>" [--game <id>] [--room <code>] [--seconds 30]
+ *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
+ *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
+ *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
+ *                                         (kick, close and launch are ASKED for: the owner confirms each with one
+ *                                          tap in their own browser, from the link this prints)
+ *   homie-studio office revoke            (every office key, play ticket and pending ask ends)
+ *
  *   homie-studio progress start [<id>] [--what game|song|video] [--title "<what this build does>"]
  *                                        [--budget <dollars>] [--unit usd|credits] [--share]
  *                                         (a progress feed for one build; --share shows it in the Claude app
@@ -98,12 +111,13 @@ import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
-import { ensureMigrations, newStudio } from '../lib/scaffold.mjs';
+import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
 import { playersOwner, playersShow } from '../lib/players.mjs';
+import { officeAnnounce, officeClose, officeInvite, officeKey, officeKick, officeLaunch, officeLines, officeLink, officeRevoke, officeShow } from '../lib/office.mjs';
 import { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, recordChange, startProgress } from '../lib/progress.mjs';
 import { formatStatus, setupStatus } from '../lib/doctor.mjs';
 import { codexTarget, newCodex, writeCodexPage } from '../lib/codex.mjs';
@@ -112,7 +126,7 @@ import { restartWithProxy } from '../lib/net.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -232,6 +246,28 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'office':
+      lines.push(...officeLines(result));
+      break;
+    case 'office link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'office key':
+      lines.push(`Office key (until ${result.expiresAt}): ${result.key}`, result.use);
+      break;
+    case 'office announce':
+    case 'office revoke':
+      lines.push(result.message);
+      break;
+    case 'office invite':
+      for (const i of result.invites) lines.push(`Invite ${i.code}${i.label ? ` (${i.label})` : ''}, ${i.maxUses ? `${i.maxUses} use${i.maxUses === 1 ? '' : 's'}` : 'any number of uses'}: ${i.link}`);
+      if (result.note) lines.push(result.note);
+      break;
+    case 'office launch':
+    case 'office kick':
+    case 'office close':
+      lines.push(result.asked ? `Asked: ${result.what}` : result.message, ...(result.asked ? [`Owner's one-tap link (until the ask ends, 15 min): ${result.link}`, result.use] : []));
+      break;
     case 'setup status':
       lines.push(formatStatus(result));
       break;
@@ -408,6 +444,18 @@ async function main() {
   if (cmd === 'stats' && sub === 'revoke') return statsRevoke(root, { url: flags.get('url') });
   if (cmd === 'stats' && sub === 'share') return statsShare(root, positional[2]);
   if (cmd === 'stats' && !sub) return statsShow(root, { url: flags.get('url'), range: flags.get('range'), game: flags.get('game'), song: flags.get('song'), video: flags.get('video') });
+  if (cmd === 'office') {
+    const url = flags.get('url');
+    if (!sub) return officeShow(root, { url });
+    if (sub === 'link') return officeLink(root, { url, to: flags.get('to') });
+    if (sub === 'key') return officeKey(root, { url, hours: flags.get('hours') });
+    if (sub === 'announce') return officeAnnounce(root, positional.slice(2).join(' '), { url, game: flags.get('game'), room: flags.get('room'), seconds: flags.get('seconds') });
+    if (sub === 'invite') return officeInvite(root, positional[2], { url, label: flags.get('label'), uses: flags.get('uses'), count: flags.get('count'), days: flags.get('days') });
+    if (sub === 'launch') return officeLaunch(root, positional[2], positional[3], { url, remixable: flags.get('remixable'), max: flags.get('max') });
+    if (sub === 'kick') return officeKick(root, positional[2], positional[3], positional.slice(4).join(' ') || undefined, { url, minutes: flags.get('minutes') });
+    if (sub === 'close') return officeClose(root, positional[2], positional[3], { url, minutes: flags.get('minutes'), reopen: flags.has('reopen') });
+    if (sub === 'revoke') return officeRevoke(root, { url });
+  }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);
@@ -577,7 +625,7 @@ async function dev(root) {
   if (!bin) return { ok: false, command: 'dev', why: 'run npm install in the studio first' };
   const studio = readStudio(root);
   const env = { ...process.env, WRANGLER_SEND_METRICS: 'false', CI: '1' };
-  for (const added of ensureMigrations(root)) log(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats'})`);
+  for (const added of ensureMigrations(root)) log(`added ${added} (${migrationWord(added)})`);
   await new Promise((done) => {
     const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
     m.on('close', done);

package/lib/build.mjs

@@ -223,6 +223,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       // game.json "saves": true — player accounts and cloud saves (saves/SAVES.md): the play shell answers the game's
       // saves calls, and the site's nav and the game's landing offer a player account.
       ...(g.saves === true || (g.saves && typeof g.saves === 'object') ? { saves: true } : {}),
+      // game.json `"launch": "private" | "invite"`: the game's launch state until its owner sets one live (the office).
+      ...(g.launch === 'private' || g.launch === 'invite' ? { launch: g.launch } : {}),
       landing: landingOf(g, join(dist, 'games', g.id), { videos: media.videos, songs: media.songs, log }),
     };
   });

package/lib/cloudflare.mjs

@@ -23,7 +23,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { build } from './build.mjs';
 import { repoOf } from './repo.mjs';
-import { ensureLocalIgnored, ensureMigrations, wranglerConfig } from './scaffold.mjs';
+import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
 import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -193,7 +193,7 @@ export async function deploy(root, { log = () => {}, homie } = {}) {
   if (!r2) step('no storage (R2): the studio needs none to run; `homie-studio storage add` adds it for large media');
 
   writeFileSync(configPath(root), wranglerConfig({ worker: cf.worker, name: studio.name, d1: cf.d1, d1Id: db.uuid, r2, layout: layoutOf(root) }));
-  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own stats: counts, never tracks'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const migrate = w(['d1', 'migrations', 'apply', cf.d1, '--remote']);
   if (migrate.code !== 0) return refuse(`D1 migrations failed: ${migrate.out.trim().split('\n').slice(-4).join(' ')}`, migrate.out);
   step('D1 migrations applied');
@@ -293,7 +293,7 @@ export async function ciDeploy(root, { log = () => {} } = {}) {
   const step = (what) => { steps.push({ what }); log(what); };
   const refuse = (why, out) => ({ ok: false, command: 'deploy', ci: true, ...(explainCloudflare(out) ?? { why }), steps });
   if (!existsSync(join(root, 'site', 'dist', 'games.json'))) return { ok: false, command: 'deploy', ci: true, why: 'nothing is built: the build command is `npm run build` (homie-studio build), and it runs before this', steps };
-  for (const added of ensureMigrations(root)) step(`added ${added} (${/players/.test(added) ? 'player accounts and cloud saves' : 'the studio\'s own counters'})`);
+  for (const added of ensureMigrations(root)) step(`added ${added} (${migrationWord(added)})`);
   const apply = () => w(['d1', 'migrations', 'apply', names.binding, '--remote']);
   let migrate = apply();
   const first = migrate.code !== 0 && /not found|could(?:n't| not) find|does not exist|no database|database_id/i.test(migrate.out);

package/lib/office.mjs

@@ -0,0 +1,172 @@
+/**
+ * `homie-studio office` — the studio's back office from the studio folder (worker/office.mjs says what it is).
+ *
+ *   homie-studio office [--url <site>]                 every live room of every game and who is in it, now
+ *   homie-studio office link [--to <path>]             a one-time link that signs the owner's browser in (the office,
+ *                                                      or --to /<game>/play: a private game on the owner's phone)
+ *   homie-studio office key [--hours 1]                an office key for the Homie MCP's owner tools (studio_office,
+ *                                                      room_kick, room_announce, room_close, game_launch_state)
+ *   homie-studio office announce "<text>" [--game <id>] [--room <code>] [--seconds 30]
+ *   homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>]
+ *   homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]
+ *   homie-studio office kick <game> <room> <seat number | name> [--minutes 10]
+ *   homie-studio office close <game> <room> [--minutes 10] [--reopen]
+ *   homie-studio office revoke                         every office key ends; every play ticket and pending ask too
+ *
+ * THE PROOF OF OWNERSHIP IS THE STUDIO'S OWN CLOUDFLARE LOGIN, as for the stats: a key is minted here and only its
+ * SHA-256 goes into the studio's D1. Looking, announcing and inviting happen at once. Kick, mute, closing a room and
+ * a game's launch state, remix switch or room size are only ASKED for here: the answer is a one-time sign-in link
+ * that opens the ask in the owner's own browser, where one tap does it (the AI that ran this cannot).
+ */
+import { readStudio } from './studio.mjs';
+import { runner } from './cloudflare.mjs';
+import { drop, loopback, mint, siteOf } from './stats.mjs';
+
+const HOUR = 3600_000;
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+/** Call the studio's office API with a key that lives ten minutes and is dropped as soon as the answer is in. */
+async function withKey(root, url, fn) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first, or give --url http://127.0.0.1:8787 for `npm run dev`' };
+  const local = loopback(site);
+  const k = mint(root, studio, 'office', 10 * 60_000, { local });
+  if (!k.ok) return { ok: false, why: /no such table: stats_keys/.test(k.why) ? k.why : k.why };
+  try {
+    const call = async (path, body = null) => {
+      const res = await fetch(`${site}${path}`, {
+        method: body ? 'POST' : 'GET',
+        headers: { authorization: `Bearer ${k.key}`, accept: 'application/json', ...(body ? { 'content-type': 'application/json' } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(20_000),
+      });
+      const out = await res.json().catch(() => ({ ok: false, message: `${site}${path} answered ${res.status}` }));
+      return { status: res.status, ...out };
+    };
+    return await fn(call, { studio, site, local });
+  } catch (error) {
+    return { ok: false, why: `could not reach ${site}: ${error.message}` };
+  } finally { drop(root, studio, k.hash, { local }); }
+}
+
+/** A one-time sign-in link for the owner's browser that lands on `to` (30 minutes). */
+function signinTo(root, url, to) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, why: 'this studio has no live site yet: `npm run deploy` first' };
+  const k = mint(root, studio, 'signin', 30 * 60_000, { local: loopback(site) });
+  if (!k.ok) return k;
+  return { ok: true, site, link: `${site}/_studio/signin?k=${k.key}${to && to !== '/_studio/stats' ? `&to=${encodeURIComponent(to)}` : ''}`, expiresAt: k.expiresAt };
+}
+
+const askedFor = (root, url, r, command) => {
+  if (!r.ok) return { ok: false, command, why: r.message ?? r.why ?? `the studio said ${r.error ?? r.status}` };
+  if (r.needs !== 'owner' || !r.ask) return { ok: true, command, done: true, result: r, message: r.what ? `Done: ${r.what}` : 'Done.' };
+  const link = signinTo(root, url, `/_studio/confirm/${r.ask.id}`);
+  return {
+    ok: true, command, asked: true, ask: r.ask, what: r.ask.what,
+    link: link.ok ? link.link : r.ask.confirm,
+    use: `Waiting for the owner: ${r.ask.what} Give the owner this link to open in their own browser: it signs that browser in (once, within 30 minutes) and shows the ask with one button. It lasts 15 minutes; nothing happens unless the owner taps.`,
+  };
+};
+
+export async function officeShow(root, { url } = {}) {
+  const r = await withKey(root, url, (call) => call('/_studio/api/office'));
+  if (!r.ok) return { ok: false, command: 'office', why: r.why ?? r.message ?? 'the office did not answer' };
+  return { command: 'office', ...r, ok: true };
+}
+
+export function officeLink(root, { url, to } = {}) {
+  const target = to && /^\/[A-Za-z0-9_/-]{1,80}$/.test(String(to)) ? String(to) : '/_studio/office';
+  const r = signinTo(root, url, target);
+  if (!r.ok) return { ok: false, command: 'office link', why: r.why };
+  return {
+    ...r, command: 'office link', to: target,
+    use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, and keeps that browser signed in as the owner for 30 days (the office, the stats, and the owner\'s tools inside their own games). It is theirs alone; do not post it anywhere.',
+  };
+}
+
+export function officeKey(root, { url, hours } = {}) {
+  const { studio, site } = siteOf(root, url);
+  if (!site) return { ok: false, command: 'office key', why: 'this studio has no live site yet: `npm run deploy` first' };
+  const h = Math.max(1, Math.min(24 * 30, Math.floor(Number(hours) || 1)));
+  const k = mint(root, studio, 'office', h * HOUR, { local: loopback(site) });
+  if (!k.ok) return { ok: false, command: 'office key', why: k.why };
+  return {
+    ok: true, command: 'office key', site, key: k.key, expiresAt: k.expiresAt, hours: h,
+    use: `Pass { "site": "${site}", "key": "<this key>" } to the Homie MCP's owner tools (studio_office, room_announce, room_kick, room_close, game_launch_state). With it the AI sees the live rooms, announces and makes invites; a kick, a closed room or a launch state change is only asked for, and the owner confirms it with one tap. It also reads the stats (studio_stats). It ends at ${k.expiresAt}; \`homie-studio office revoke\` ends it sooner. Never paste it anywhere else.`,
+  };
+}
+
+export async function officeAnnounce(root, text, { url, game, room, seconds } = {}) {
+  if (!String(text ?? '').trim()) return { ok: false, command: 'office announce', why: 'usage: homie-studio office announce "<text>" [--game <id>] [--room <code>]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/announce', { text, ...(game ? { game } : {}), ...(room ? { room } : {}), ...(seconds ? { seconds: Number(seconds) } : {}) }));
+  return r.ok ? { ok: true, command: 'office announce', ...r, message: `Announced to ${r.people ?? 0} people in ${r.rooms ?? 0} room(s).` } : { ok: false, command: 'office announce', why: r.message ?? r.why };
+}
+
+export async function officeInvite(root, game, { url, label, uses, count, days } = {}) {
+  if (!GAME.test(String(game ?? ''))) return { ok: false, command: 'office invite', why: 'usage: homie-studio office invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/invites', {
+    game, ...(label ? { label } : {}), uses: uses === 'any' ? 'any' : uses ? Number(uses) : 1, ...(count ? { count: Number(count) } : {}), ...(days ? { days: Number(days) } : {}),
+  }));
+  if (!r.ok) return { ok: false, command: 'office invite', why: r.message ?? r.why };
+  return { ok: true, command: 'office invite', game, launch: r.launch, invites: r.invites, note: r.launch === 'invite' ? null : `${game} is ${r.launch} now: invites let people in once it is an invite-only beta (homie-studio office launch ${game} invite).` };
+}
+
+export async function officeLaunch(root, game, state, { url, remixable, max } = {}) {
+  if (!GAME.test(String(game ?? '')) || (state !== undefined && state !== null && !['private', 'invite', 'public'].includes(state))) {
+    return { ok: false, command: 'office launch', why: 'usage: homie-studio office launch <game> private|invite|public [--remixable on|off] [--max <n>|game]' };
+  }
+  const body = { game, ...(state ? { launch: state } : {}), ...(remixable !== undefined ? { remix: remixable === 'on' || remixable === true } : {}), ...(max !== undefined ? { maxPlayers: max === 'game' ? null : Number(max) } : {}) };
+  const r = await withKey(root, url, (call) => call('/_studio/api/game', body));
+  return askedFor(root, url, r, 'office launch');
+}
+
+export async function officeKick(root, game, room, who, { url, minutes } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room || who === undefined) return { ok: false, command: 'office kick', why: 'usage: homie-studio office kick <game> <room> <seat number | name> [--minutes 10]' };
+  const r = await withKey(root, url, async (call) => {
+    const office = await call('/_studio/api/office');
+    const g = (office.games ?? []).find((x) => x.id === game);
+    const rm = (g?.rooms ?? []).find((x) => x.room === room || x.label.toLowerCase() === String(room).toLowerCase());
+    if (!rm) return { ok: false, message: `nobody is in ${room} of ${game} now (homie-studio office lists the rooms)` };
+    const seat = /^\d+$/.test(String(who)) ? Number(who) - 1 : null;
+    const c = rm.clients.find((x) => (seat !== null && x.seat === seat) || String(x.name).toLowerCase() === String(who).toLowerCase());
+    if (!c) return { ok: false, message: `no "${who}" in ${rm.label} (seats are numbered from 1)` };
+    return call('/_studio/api/kick', { game, room: rm.room, id: c.id, minutes: Number(minutes) || 10 });
+  });
+  return askedFor(root, url, r, 'office kick');
+}
+
+export async function officeClose(root, game, room, { url, minutes, reopen } = {}) {
+  if (!GAME.test(String(game ?? '')) || !room) return { ok: false, command: 'office close', why: 'usage: homie-studio office close <game> <room> [--minutes 10] [--reopen]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/close', { game, room, minutes: Number(minutes) || 10, reopen: Boolean(reopen) }));
+  return askedFor(root, url, r, 'office close');
+}
+
+/** Every office key ends, and the office secret is made anew: every play ticket and every signed control ends with it. */
+export function officeRevoke(root, { url } = {}) {
+  const { studio, site } = siteOf(root, url);
+  const local = site ? loopback(site) : false;
+  const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
+  const res = w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', "DELETE FROM stats_keys WHERE kind = 'office'; DELETE FROM meta WHERE key = 'office_key'; UPDATE office_asks SET state = 'expired' WHERE state = 'pending';"]);
+  return res.code === 0
+    ? { ok: true, command: 'office revoke', site, message: 'Every office key has ended, and every play ticket and pending ask with it (a browser let into a private or invite-only game gets a new ticket the next time it opens the game). Invite passes and the owner\'s signed-in browsers stay; `homie-studio stats revoke` ends those sessions.' }
+    : { ok: false, command: 'office revoke', why: res.out.trim().split('\n').slice(-3).join(' ') };
+}
+
+/** One line per room for a person (the CLI's print). */
+export function officeLines(r) {
+  const lines = [`${r.studio}: ${r.playing ? `${r.playing} playing now` : 'nobody playing right now'} (${r.site})`];
+  const now = r.now ?? Date.now();
+  const mins = (ms) => `${Math.max(0, Math.round(ms / 60000))} min`;
+  for (const g of r.games ?? []) {
+    lines.push(`  ${g.name} (${g.id}): ${g.launch}${g.launch === 'public' ? '' : ' (not listed)'}, ${g.remix ? 'remixable' : 'source closed'}, rooms of ${g.maxPlayers}${g.maxSet ? ` (the game's own: ${g.seats})` : ''}`);
+    for (const i of (g.invites ?? []).filter((x) => x.open)) lines.push(`    invite ${i.code}${i.label ? ` (${i.label})` : ''}: ${i.uses}${i.maxUses ? ` of ${i.maxUses}` : ''} used · ${i.link}`);
+    if (!g.rooms.length) lines.push('    no live rooms');
+    for (const rm of g.rooms) {
+      const round = rm.round ? `round ${rm.round.n} ${rm.round.phase}` : 'no round';
+      lines.push(`    ${rm.label}${rm.public ? '' : ' (named)'}: ${rm.players}/${rm.max} players, ${rm.bots} bots, ${round}, up ${rm.openedAt ? mins(now - rm.openedAt) : '?'}${rm.closedUntil ? `, CLOSED for ${mins(rm.closedUntil - now)}` : ''}`);
+      for (const c of rm.clients) lines.push(`      ${c.seat !== null ? `seat ${c.seat + 1}` : 'watching'}: ${c.name} · ${c.device}${c.role === 'host' ? ' · host' : ''} · ${c.as}${c.muted ? ' · muted' : ''} · here ${mins(now - c.joinedAt)}`);
+      for (const b of rm.bans ?? []) lines.push(`      kicked: ${b.name} (back in ${mins(b.until - now)})`);
+    }
+  }
+  return lines;
+}

package/lib/scaffold.mjs

@@ -25,6 +25,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { STUDIO_VERSION, packageSpec } from './version.mjs';
 import { STATS_MIGRATION, STATS_MIGRATION_FILE } from '../worker/stats.mjs';
 import { PLAYERS_MIGRATION, PLAYERS_MIGRATION_FILE } from '../worker/players.mjs';
+import { OFFICE_MIGRATION, OFFICE_MIGRATION_FILE } from '../worker/office-schema.mjs';
 import { themeFile } from './site.mjs';
 import { PACKAGE_ROOT } from './studio.mjs';
 
@@ -222,6 +223,28 @@ studio's pinned copy, never a registry lookup of the bare name.
   Cloudflare, Chrome, ffmpeg, GitHub, ElevenLabs, fal), what each unlocks, and the exact fix. Optional ones never
   block anything.
 
+## Running live games (the back office)
+
+- The owner runs the studio's live games from \`/_studio/office\` (\`npx --no-install homie-studio office link\` gives
+  the owner a one-time sign-in link): every live room of every game, who is in it (handles; accounts once players
+  sign in), bots, the round and uptime, refreshing by itself; Kick (that player cannot come back to that room for
+  the minutes chosen), Mute (their chat and emotes reach nobody), Announce (one line every player sees), Close a
+  room; and per game: launch state, Remixable, players per room and invites.
+- **Launch states:** \`private\` (only the owner, signed in; \`office link --to /<id>/play\` signs the owner's phone
+  in), \`invite\` (an invite-only beta: \`office invite <id>\` makes invite links and codes, each for one browser or
+  as many as \`--uses\` says), \`public\` (the default; listed). A game that is not public is in no list and not in
+  the directory manifest, so the directory drops it the next time it reads the studio. A new game stays private
+  from its first deploy with \`"launch": "private"\` in its game.json. **Remixable** publishes or withdraws its source.
+- The owner is recognised in their own games: signed in, their play page has a small Owner button (tap a player:
+  Mute, Kick; Announce). Nobody else's page has it.
+- **From the AI:** \`npx --no-install homie-studio office\` lists who is playing now; \`office announce "<text>"\` and
+  \`office invite <id>\` happen at once; \`office kick\`, \`office close\` and \`office launch\` only ASK, and print a
+  one-time link that opens the ask in the owner's own browser, where one tap does it. An ask is not done until the
+  owner tapped. \`office key\` gives a key for the Homie MCP's owner tools (\`studio_office\`, \`room_announce\`,
+  \`room_kick\`, \`room_close\`, \`game_launch_state\`), which ask the same way; never paste a key anywhere else.
+- A game can listen (\`NETPLAY.md\` section 15): \`net.on('announce', …)\`, \`net.isMuted(seat)\` to hide a muted
+  player's chat, and \`net.pickPlayer(seat)\` when a player is clicked (the owner's page opens their card).
+
 ## Rules
 
 - Keys stay in the providers' own logins (Wrangler, ElevenLabs, fal) or the OS
@@ -397,6 +420,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     'site/migrations/0001_studio.sql': MIGRATION,
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
     [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
+    [`site/migrations/${OFFICE_MIGRATION_FILE}`]: OFFICE_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
@@ -466,6 +490,18 @@ export function ensureStatsMigration(root) {
   return `site/migrations/${STATS_MIGRATION_FILE}`;
 }
 
+/**
+ * A studio made before 0.13.0 has no back-office migration (worker/office.mjs): add it, so the next
+ * `d1 migrations apply` makes its tables. Returns the file it wrote, or null when it was there.
+ */
+export function ensureOfficeMigration(root) {
+  const file = join(root, 'site', 'migrations', OFFICE_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, OFFICE_MIGRATION);
+  return `site/migrations/${OFFICE_MIGRATION_FILE}`;
+}
+
 /**
  * A studio made before 0.12.0 has no players migration (player accounts and cloud saves, saves/SAVES.md): add it,
  * so the next `d1 migrations apply` makes the tables. Returns the file it wrote, or null when it was there.
@@ -480,7 +516,12 @@ export function ensurePlayersMigration(root) {
 
 /** Every migration the template owns that this studio lacks, added: the files written (deploy and dev say so). */
 export function ensureMigrations(root) {
-  return [ensureStatsMigration(root), ensurePlayersMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root)].filter(Boolean);
+}
+
+/** What a migration file the template added is for, in a few words (deploy and dev say it). */
+export function migrationWord(file) {
+  return /players/.test(file) ? 'player accounts and cloud saves' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/stats.mjs

@@ -48,7 +48,7 @@ export function mint(root, studio, kind, ttlMs, { local }) {
   return { ok: true, key, hash, expiresAt: new Date(now + ttlMs).toISOString() };
 }
 
-function drop(root, studio, hash, { local }) {
+export function drop(root, studio, hash, { local }) {
   const w = runner(root, studio.cloudflare?.accountId && !local ? { CLOUDFLARE_ACCOUNT_ID: studio.cloudflare.accountId } : {});
   w(['d1', 'execute', studio.cloudflare.d1, local ? '--local' : '--remote', '--command', `DELETE FROM stats_keys WHERE hash = '${hash}';`]);
 }

package/lib/template-history.json

@@ -247,6 +247,31 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.13.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "games/README.md": "5e5e942baa7e0372",
+    "music/README.md": "b8a828de9311bd28",
+    "videos/README.md": "70614388cbb203c7",
+    "posts/README.md": "37841aae476bd540",
+    "site/README.md": "ca131cd0472464fb",
+    "site/src/worker.mjs": "ca3f1630f2420ad3"
+   },
+   "sections": {
+    "AGENTS.md": {
+     "(intro)": "214aa46eb3a895d5",
+     "## Layout": "f14d641159480e6c",
+     "## Commands (all through the pinned CLI in node_modules)": "3a3d3bef7e8d1a50",
+     "## The site": "7d3525ba39b7f262",
+     "## Making games": "63069b31c87a2aa2",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }

package/lib/upgrade.mjs

@@ -170,11 +170,14 @@ export function upgradePlan(root, { history = readHistory() } = {}) {
     }
     const have = sections(mine);
     const tsecs = sections(want);
+    const adding = new Set();
     for (const [k, t] of tsecs.entries()) {
       const at = have.find((s) => s.heading === t.heading);
       if (!at) {
-        // After the nearest template section before it that the studio has; else before the first one after it.
-        const before = tsecs.slice(0, k).reverse().find((p) => have.some((s) => s.heading === p.heading));
+        // After the nearest template section before it that the studio has (or that this plan adds just before it, so
+        // two new sections in a row keep the template's order); else before the first one after it.
+        const before = tsecs.slice(0, k).reverse().find((p) => have.some((s) => s.heading === p.heading) || adding.has(p.heading));
+        adding.add(t.heading);
         const after = before ? null : tsecs.slice(k + 1).find((p) => have.some((s) => s.heading === p.heading));
         changes.push({ file: rel, kind: 'add-section', section: t.heading, what: `new section ${t.heading === INTRO ? 'intro' : `"${t.heading}"`}`, after: before?.heading ?? null, before: after?.heading ?? null, text: t.text });
         continue;