@homie-rocks/studio 0.14.4 → 0.16.0

package/README.md

@@ -20,6 +20,7 @@ npx homie-studio deploy                                # the studio's own Cloudf
 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 servers                                # each game's servers: humans-only, hybrid AI seats, beginner guides
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
@@ -80,7 +81,7 @@ its D1; nothing is stored by hand. studio.json `homie.directory: false` keeps a
 
 Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
 featured game, live rooms, the latest posts), Games, Music, Videos, Rooms (every public room playing now,
-joinable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
+joinable and watchable) and Posts (`posts/*.md`, with Atom and JSON feeds). A section with nothing in it has no tab, and its
 page answers 404. Every game gets a landing at `/<game>/`: a full-bleed hero from its own footage or art, the
 pitch, a big Play button into a public room, how to play on a phone, a computer and a TV (with the join code),
 live rooms, credits (the original and its licence for a port; "Remix of <game> by <studio>", linked, for a
@@ -97,13 +98,20 @@ game's landing still. Every HTML answer is `no-transform`, and the site's pages
 site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
 `not-a-homie`, at the site's root as under the game.
 
+Anyone can **watch** a live room from any player's view at `/<game>/watch?room=<room>` (a Watch button sits beside
+Join on every room): the game itself, drawn by the watcher's own browser as a watcher that never takes a seat,
+with a strip of the players to switch between (a tap, keys 1-9, Auto, the whole room). A game draws the followed
+player's camera and HUD from `net.viewSeat` (Gem Rush and Ember Vale do; a game that does not is watched as its
+overview), and game.json `"watch": "overview"` or `false` keeps hidden hands hidden. Private and invite-only games
+are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
+
 ## Upgrading a studio
 
 A studio pins one version, so nothing changes until it asks. To take a newer one:
 
 ```sh
-npx -y @homie-rocks/studio@0.14.4 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.14.4 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.16.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.16.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -225,16 +233,45 @@ look, announce and invite at once; a kick, a mute, a closed room or a launch cha
 **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.
+Worker and D1 (migration `0005_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.
 
+## Servers and AI seats
+
+A game's **servers** (0.16.0) are named, lasting pools of rooms with their own rules; strangers are matched only
+inside one server, and every game's public rooms are its Quick play server, so nothing old changes:
+
+```sh
+npx homie-studio servers new night-rush "Night Shift" --policy hybrid --ai 2      # 2 AI companions in every room
+npx homie-studio servers new night-rush "People Only" --policy humans-only        # no AI of any kind
+npx homie-studio servers new night-rush "First Light" --policy beginner --guides 2 --kids
+npx homie-studio servers                                                           # every server, live, and builds that predate them
+npx homie-studio agents pass night-rush --label Claude                             # an AI's way into a seat (shown once)
+```
+
+- **Policies:** open (an AI with a pass may sit, always marked AI), humans-only (the site and the room refuse
+  every AI; the game's bots are off), hybrid (the top N seats of every room are AI companions), beginner (new
+  accounts, AI guides, quick lines only; `--kids`: handles only, gentle AI). **Doors:** open, accounts (a passkey
+  account) or invite (`office invite <id> --server <server>`).
+- **AI is always marked AI**, by the room's relay, not the game: every agent is named "<label> · AI", and the
+  relay rewrites a host's roster and results so a game cannot hide one.
+- **The skill dial:** 1 Rookie to 5 Maxed (`{ reactionMs, aimNoise, aggression, positioning }`). The party votes it
+  on a card in the play page (the middle vote wins); `net.skillOf(slot)` is what a bot reads (`NETPLAY.md` section
+  17), and `BotBrain` reads it with a rebuild. In the starters, Gem Rush's Rookie bots collect far fewer gems than
+  its Maxed ones.
+- **Asks:** making a server, a widening change, a pass and a room's level happen at once; narrowing one
+  (humans-only, a stricter door), closing it, removing a member, and the first time AI guides may talk are asked
+  for, and the owner confirms with one tap.
+- Everything is in the studio's own Worker and D1 (migration `0006_studio_servers.sql`). The site's side is in
+  [site/SITE.md](site/SITE.md); the room's in [netplay/NETPLAY.md](netplay/NETPLAY.md) section 17.
+
 ## Setup status
 
 ```sh
-npx -y @homie-rocks/studio@0.14.4 setup status --connector yes   # before a studio exists
+npx -y @homie-rocks/studio@0.16.0 setup status --connector yes   # before a studio exists
 npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
 ```
 
@@ -411,7 +448,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/port.mjs` | `port plan` (reads a game and grades the port) and `port import`. |
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`. |
-| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
+| `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/<game>/watch` watches a live room from any player's view (NETPLAY.md section 16); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site or from storage at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
 | `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |
 | `lib/media.mjs`, `media/MEDIA.md` | The `music/` and `videos/` manifests: which entries get a page, and where each file's bytes come from (the site itself up to 25 MiB a file, the studio's storage, or a link). `media list` shows it; `media put` uploads a file to storage and records its key. |

package/bin/homie-studio.mjs

@@ -51,7 +51,7 @@
  *                                          --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 invite <game> [--label "<who>"] [--uses 1|<n>|any] [--count 1] [--days <n>] [--server <id>]
  *   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]
@@ -59,6 +59,22 @@
  *                                          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 servers [--game <id>]    every server of every game (worker/servers.mjs): its policy, door, the AI's
+ *                                          level, live rooms and AI, members, and builds that predate servers
+ *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>]
+ *                                        [--kids] [--door open|accounts|invite] [--level 1-5] [--level-max 1-5]
+ *                                        [--speech game|lines|off] [--bots fill|off] [--rooms <n>] [--listed on|off]
+ *   homie-studio servers set <game> <server> [the same flags]
+ *   homie-studio servers close <game> <server> [--reopen]
+ *   homie-studio servers level <game> <room> <1-5>   (the AI's level in one room: Rookie, Steady, Fair, Strong, Maxed)
+ *   homie-studio servers member <game> <server> <player> --role member|mentor|mod | --remove
+ *   homie-studio agents pass <game|any> --label "<Name>" [--server <id>] [--hands self|host] [--days 7]
+ *                                         (an AI's way into a seat, always marked AI; the pass is shown once)
+ *   homie-studio agents passes [<game>]   homie-studio agents revoke <pass id>
+ *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key
+ *                                         (a narrowing change, closing a server, removing a member and the first
+ *                                          time AI guides may talk are ASKED for, like office kick)
+ *
  *   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
@@ -129,6 +145,7 @@ 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 { agentsBrain, agentsPass, agentsPasses, agentsRevoke, serversClose, serversLevel, serversLines, serversList, serversMember, serversNew, serversSet } from '../lib/servers.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';
@@ -140,7 +157,7 @@ import { formatHandoff, handoff } from '../lib/handoff.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', 'reopen'];
+const BOOL_FLAGS = ['revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -277,6 +294,27 @@ function print(result) {
       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 'servers':
+      lines.push(...serversLines(result));
+      break;
+    case 'servers new':
+      lines.push(result.message, ...(result.notes ?? []).map((n) => `  ${n}`));
+      break;
+    case 'servers level':
+    case 'agents revoke':
+      lines.push(result.message);
+      break;
+    case 'agents pass':
+      lines.push(`${result.pass.name} (pass ${result.pass.id}, ${result.pass.role}, hands ${result.pass.hands}${result.pass.server ? `, ${result.pass.server} only` : ''}):`, `  ${result.secret}`, result.use);
+      break;
+    case 'agents passes':
+      for (const p of result.passes) lines.push(`${p.id}  ${p.name}  ${p.role}, hands ${p.hands}${p.game ? `, ${p.game}` : ''}${p.server ? `/${p.server}` : ''}${p.live ? '' : p.revoked ? '  (revoked)' : '  (ended)'}`);
+      if (!result.passes.length) lines.push('No agent passes yet: homie-studio agents pass <game> --label "<Name>"');
+      break;
+    case 'servers set':
+    case 'servers close':
+    case 'servers member':
+    case 'agents brain':
     case 'office launch':
     case 'office kick':
     case 'office close':
@@ -477,12 +515,30 @@ async function main() {
     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 === 'invite') return officeInvite(root, positional[2], { url, label: flags.get('label'), uses: flags.get('uses'), count: flags.get('count'), days: flags.get('days'), server: flags.get('server') });
     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 === 'servers') {
+    const url = flags.get('url');
+    if (!sub || sub === 'list') return serversList(root, { url, game: flags.get('game') });
+    if (sub === 'new') return serversNew(root, positional[2], positional.slice(3).join(' ') || flags.get('name'), flags, { url });
+    if (sub === 'set') return serversSet(root, positional[2], positional[3], flags, { url });
+    if (sub === 'close') return serversClose(root, positional[2], positional[3], { url, reopen: flags.has('reopen') });
+    if (sub === 'level') return serversLevel(root, positional[2], positional[3], positional[4], { url });
+    if (sub === 'member') return serversMember(root, positional[2], positional[3], positional[4], { url, role: flags.get('role'), remove: flags.has('remove') });
+    return { ok: false, command: 'servers', why: `unknown: servers ${sub} (list, new, set, close, level, member)` };
+  }
+  if (cmd === 'agents') {
+    const url = flags.get('url');
+    if (sub === 'pass') return agentsPass(root, positional[2], { url, label: flags.get('label'), server: flags.get('server'), hands: flags.get('hands'), role: flags.get('role'), days: flags.get('days') });
+    if (sub === 'passes') return agentsPasses(root, positional[2], { url });
+    if (sub === 'revoke') return agentsRevoke(root, positional[2], { url });
+    if (sub === 'brain') return agentsBrain(root, positional[2], positional[3], positional[4], { url });
+    return { ok: false, command: 'agents', why: `unknown: agents ${sub ?? ''} (pass, passes, revoke, brain)` };
+  }
   if (cmd === 'media' && sub === 'put') return mediaPut(root, positional[2], flags.get('as'));
   if (cmd === 'media' && sub === 'list') {
     const studio = readStudio(root);

package/lib/build.mjs

@@ -34,6 +34,7 @@ import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
 import { SEAT_MAX } from '../worker/seats.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { licenseOf, remixRow } from '../worker/license.mjs';
+import { SERVER_LIMITS, serverOf } from '../worker/servers.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
@@ -126,6 +127,44 @@ function readJson(path) {
  * A game's netplay manifest: game.json's `netplay` block, over a `netplay.json` beside game.json or in the game's
  * built output (a ported Vite game ships public/netplay.json), over nothing.
  */
+/**
+ * Which netplay revision a game's build speaks (0.16.0): the helper writes `homie-netplay-rev:<n>` into every
+ * bundle (netplay/netplay.ts NETPLAY_MARK). A build without it is revision 5 or older: it plays on every server, but
+ * reserved AI seats stay empty and its bots do not read the dial, and the office says so. Null when nothing says.
+ */
+export function netplayRevOf(out) {
+  const files = [];
+  const walk = (dir, depth) => {
+    if (depth > 3 || !existsSync(dir)) return;
+    for (const name of readdirSync(dir)) {
+      const f = join(dir, name);
+      let st;
+      try { st = statSync(f); } catch { continue; }
+      if (st.isDirectory()) { if (!['node_modules', '_landing'].includes(name)) walk(f, depth + 1); } else if (/\.m?js$/.test(name) && st.size < 16 * 1024 * 1024) files.push(f);
+    }
+  };
+  walk(out, 0);
+  let rev = null;
+  for (const f of files.slice(0, 200)) {
+    const m = /homie-netplay-rev:(\d{1,3})/.exec(readFileSync(f, 'utf8'));
+    if (m) rev = Math.max(rev ?? 0, Number(m[1]));
+  }
+  return rev;
+}
+
+/** game.json "servers": the seeds a game ships with (worker/servers.mjs; a D1 row of the same id wins). */
+function serverSeeds(g, log) {
+  if (!Array.isArray(g.servers)) return [];
+  const out = [];
+  for (const raw of g.servers.slice(0, SERVER_LIMITS.perGame)) {
+    const s = serverOf({ ...raw, id: raw?.id ?? String(raw?.name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 20) }, { from: 'game.json' });
+    if (!s || (s.id === 'public' && raw?.policy === undefined)) { log(`warning: games/${g.id}/game.json: a server needs an id (or a name) and a policy; skipped`); continue; }
+    const { from, createdAt, updatedAt, ...seed } = s;
+    out.push(seed);
+  }
+  return out;
+}
+
 export function netplayOf(g, out = null) {
   const file = readJson(join(g.dir, 'netplay.json')) ?? (out ? readJson(join(out, 'netplay.json')) : null) ?? {};
   return { ...(file && typeof file === 'object' ? file : {}), ...(g.netplay && typeof g.netplay === 'object' ? g.netplay : {}) };
@@ -221,6 +260,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
     // The seats come from the game's netplay manifest (NETPLAY.md §3): what the Worker gives every room of it.
     const net = netplayOf(g, join(dist, 'games', g.id));
     const { min, max } = seatsFor(g, net);
+    const seeds = serverSeeds(g, log);
     return {
       id: g.id, name: g.name ?? g.id, blurb: g.blurb ?? '', players: { min, max },
       roundSeconds: g.roundSeconds ?? net.roundSeconds ?? null, movement: net.movement ?? null, cover: g.cover ?? null,
@@ -230,6 +270,14 @@ export async function build(root, { only = null, log = () => {} } = {}) {
       ...(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 } : {}),
+      // game.json `"watch"` (NETPLAY.md section 16): watchers see any player's view (the default), only the whole room
+      // ("overview": hidden hands or roles), or nothing (false: no watch door).
+      ...(g.watch === 'overview' ? { watch: 'overview' } : g.watch === false || g.watch === 'off' ? { watch: 'off' } : {}),
+      // Servers (0.16.0): the seeds game.json ships, the netplay revision its build speaks (the office warns when it
+      // predates servers), and game.json "agents": { "vote": "game" | false } (the game draws its own vote card, or none).
+      ...(seeds.length ? { servers: seeds } : {}),
+      netplayRev: netplayRevOf(join(dist, 'games', g.id)),
+      ...(g.agents && typeof g.agents === 'object' && (g.agents.vote === 'game' || g.agents.vote === false) ? { agents: { vote: g.agents.vote } } : {}),
       // Its source licence (worker/license.mjs), and, for a remix, what it is a remix of (shown on its landing).
       license: licenseOf(g.license),
       ...(remixRow(g.remixOf) ? { remixOf: remixRow(g.remixOf) } : {}),

package/lib/office.mjs

@@ -26,7 +26,7 @@ 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) {
+export 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);
@@ -57,7 +57,7 @@ function signinTo(root, url, to) {
   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) => {
+export 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}`);
@@ -102,13 +102,14 @@ export async function officeAnnounce(root, text, { url, game, room, 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]' };
+export async function officeInvite(root, game, { url, label, uses, count, days, server } = {}) {
+  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] [--server <id>]' };
   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) } : {}),
+    game, ...(label ? { label } : {}), uses: uses === 'any' ? 'any' : uses ? Number(uses) : 1, ...(count ? { count: Number(count) } : {}), ...(days ? { days: Number(days) } : {}), ...(server ? { server } : {}),
   }));
   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).` };
+  // An invite to a server (its door "invite") works whatever the game's launch state; a game's own, in a beta only.
+  return { ok: true, command: 'office invite', game, launch: r.launch, invites: r.invites, note: server || 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 } = {}) {

package/lib/scaffold.mjs

@@ -27,6 +27,7 @@ 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 { SERVERS_MIGRATION, SERVERS_MIGRATION_FILE } from '../worker/servers.mjs';
 import { themeFile } from './site.mjs';
 
 export const COMPAT_DATE = '2026-06-01';
@@ -169,7 +170,7 @@ studio's pinned copy, never a registry lookup of the bare name.
 (\`node_modules/@homie-rocks/studio/site/SITE.md\` says all of it):
 
 - **Sections, like homie.rocks:** Home (the featured game, live rooms, latest posts), Games, Music, Videos,
-  Rooms (every public room playing now, joinable) and Posts. A section with nothing in it has no tab, and its
+  Rooms (every public room playing now, joinable and watchable) and Posts. A section with nothing in it has no tab, and its
   page is not found.
 - **A new studio goes live with its Home only:** its name and "First game coming soon", with what is on the way
   (games, posts, music and videos), until its first game, song or video is published. A post shows there at once.
@@ -200,6 +201,14 @@ studio's pinned copy, never a registry lookup of the bare name.
   scoreboard or a bar is there, move it in game.json \`"screen": { "share": … }\`: a corner or \`top-center\`, per
   device (\`desk\`, \`phone\`, \`sideways\`), with an \`x\` / \`y\` offset in pixels, and \`"label": false\` to keep it
   a small icon (\`node_modules/@homie-rocks/studio/site/SITE.md\`). Look at it on a phone and a computer.
+- **Watch any player.** Every live room can be watched at \`/<id>/watch?room=<room>\` (each room on the Rooms page
+  and the landing has a Watch button): the game itself, drawn by the watcher's own browser, which never takes a
+  seat, with a strip of the players to switch between (a tap, keys 1-9, A for Auto, O for the whole room). Point the
+  camera and the HUD at \`net.viewSeat\` (your own seat when playing; the followed player when watching; null: the
+  overview camera; \`room.viewBody()\` in a port), and call \`net.spotlight(seat)\` on a hit, a kill or a goal so
+  Auto cuts to it (\`NETPLAY.md\` section 16). A game that never reads \`viewSeat\` is watched as its overview. A
+  game with hidden hands or roles says game.json \`"watch": "overview"\` (the whole room only) or \`false\` (no
+  watch door); a private or invite-only game is watched only by those it lets in.
 - Change a game in small steps, build, and look at it (\`dev\`, then \`check\`).
 - A game's id is its URL (\`/<id>/\`); keep it once published.
 - **Remixing.** A public game shares its source at \`/games/<id>/source.json\`, with who made it (the studio, the
@@ -256,6 +265,30 @@ studio's pinned copy, never a registry lookup of the bare name.
 - 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).
 
+## Servers and AI seats
+
+- **A server** is a named, lasting pool of rooms for one game, with its own policy and door. Strangers are matched
+  only inside one server. Every game's \`pub-N\` rooms are its \`public\` server (Quick play), so old links keep
+  working. A server's page is \`/<id>/s/<server>/\`; its rooms are \`s-<server>-<n>\`; \`/<id>/servers/\` lists them.
+- **Policies:** \`open\` (anyone; an AI with an agent pass may sit, always marked AI), \`humans-only\` (no AI of any
+  kind; the game's bots are off unless \`--bots fill\`), \`hybrid\` (N seats in every room are AI companions),
+  \`beginner\` (accounts under 30 days, AI guides, quick lines only, optionally \`--kids\`: handles only, the AI's
+  level at most 3). **Doors:** \`open\`, \`accounts\` (a passkey account) or \`invite\` (\`office invite\` with
+  \`--server\`). AI is ALWAYS marked AI: every agent's name ends in " · AI", and the relay, not the game, enforces it.
+- \`npx --no-install homie-studio servers\` lists them; \`servers new <id> "<Name>" --policy hybrid --ai 2\` (or
+  \`--policy beginner --guides 2 [--kids]\`, \`--policy humans-only\`) makes one at once; \`servers set <id> <server>
+  --level-max 3 …\` changes one; \`servers close <id> <server>\`. A change that narrows who may come in (humans-only,
+  a stricter door) and closing one only ASK, with the owner's one-tap link, like \`office kick\`.
+- **The skill dial:** every room has a level, 1 Rookie, 2 Steady, 3 Fair, 4 Strong, 5 Maxed, each \`{ reactionMs,
+  aimNoise, aggression, positioning }\`. The party sets it by voting on a card in the play page (the middle vote
+  wins, capped by the server's ceiling). Make a game's bots honour it: \`net.skillOf(slot)\` in their step (the
+  snippet is in \`NETPLAY.md\` section 17; \`BotBrain\` from the port kit reads it with a rebuild), and declare
+  \`caps: ['skill', 'agents']\` in \`createNetplay\` (a game on \`createRoom\` has \`agents\` already). A build
+  from before 0.16.0 still plays on every server; the office says it predates servers until it is rebuilt.
+- **Agent passes:** \`npx --no-install homie-studio agents pass <id> --label Claude [--server <server>]\` gives an
+  AI its way into a seat (shown once; \`agents revoke <pass>\` ends it). It sits with \`POST /<id>/api/agent\`
+  (Bearer pass), only in a room with people in it, and never on a humans-only server.
+
 ## Continuing a build from the Claude app
 
 A Claude Code session started from the Claude app's card gets one short line, like
@@ -473,6 +506,7 @@ export { default, Table, Lobby } from '@homie-rocks/studio/worker';
     [`site/migrations/${STATS_MIGRATION_FILE}`]: STATS_MIGRATION,
     [`site/migrations/${PLAYERS_MIGRATION_FILE}`]: PLAYERS_MIGRATION,
     [`site/migrations/${OFFICE_MIGRATION_FILE}`]: OFFICE_MIGRATION,
+    [`site/migrations/${SERVERS_MIGRATION_FILE}`]: SERVERS_MIGRATION,
     'wrangler.jsonc': wranglerConfig({ worker, name, d1: studio.cloudflare.d1, r2: studio.cloudflare.r2, layout: 'root' }),
     '.claude/skills/.gitkeep': '',
   };
@@ -551,14 +585,27 @@ export function ensurePlayersMigration(root) {
   return `site/migrations/${PLAYERS_MIGRATION_FILE}`;
 }
 
+/**
+ * A studio made before 0.16.0 has no servers migration (worker/servers.mjs: servers, members, agent passes): add
+ * it, so the next `d1 migrations apply` makes its tables. It needs the office's (0005) before it: its last line
+ * gives office_invites a `server`. Returns the file it wrote, or null when it was there.
+ */
+export function ensureServersMigration(root) {
+  const file = join(root, 'site', 'migrations', SERVERS_MIGRATION_FILE);
+  if (existsSync(file)) return null;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, SERVERS_MIGRATION);
+  return `site/migrations/${SERVERS_MIGRATION_FILE}`;
+}
+
 /** 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), ensureOfficeMigration(root)].filter(Boolean);
+  return [ensureStatsMigration(root), ensurePlayersMigration(root), ensureOfficeMigration(root), ensureServersMigration(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';
+  return /players/.test(file) ? 'player accounts and cloud saves' : /servers/.test(file) ? 'servers and agent seats: room pools with their own rules, AI passes' : /office/.test(file) ? 'the back office: launch states, invites, the owner\'s controls' : 'the studio\'s own stats: counts, never tracks';
 }
 
 /**

package/lib/servers.mjs

@@ -0,0 +1,133 @@
+/**
+ * `homie-studio servers` and `homie-studio agents` — a studio's servers and agent seats from the studio folder
+ * (worker/servers.mjs and worker/agents.mjs say what they are; NETPLAY.md section 17 the contract).
+ *
+ *   homie-studio servers [list] [--game <id>]           every server of every game: policy, door, live rooms, AI, members
+ *   homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner
+ *                       [--ai <n>] [--guides <n>] [--kids] [--door open|accounts|invite] [--level 1-5] [--level-max 1-5]
+ *                       [--speech game|lines|off] [--bots fill|off] [--rooms <n>] [--seats <n>] [--beginner-days <n>]
+ *                       [--listed on|off] [--blurb "<one line>"] [--id <id>]
+ *   homie-studio servers set <game> <server> [the same flags]
+ *   homie-studio servers close <game> <server> [--reopen]
+ *   homie-studio servers level <game> <room> <1-5>      the owner sets one room's AI level now
+ *   homie-studio servers member <game> <server> <player> --role member|mentor|mod | --remove
+ *   homie-studio agents pass <game|any> --label "<Name>" [--server <id>] [--hands self|host] [--role party|guide|player] [--days 7]
+ *   homie-studio agents passes [<game>]                  every pass (never a secret)
+ *   homie-studio agents revoke <pass id>
+ *   homie-studio agents brain <game> <server> off|script|workers-ai|owner-key
+ *
+ * The proof of ownership is the studio's own Cloudflare login, as for the office: a ten-minute office key is minted
+ * and dropped around each call. Making a server, a widening change, a pass and a room's level happen at once. A
+ * change that narrows who may come in, closing a server, removing a member, and the first time AI guides may talk are
+ * only ASKED for: the answer is a one-time link that opens the ask in the owner's own browser (one tap does it).
+ */
+import { askedFor, withKey } from './office.mjs';
+
+const GAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const SERVER = /^[a-z0-9][a-z0-9-]{1,19}$/;
+const LEVELS = ['Rookie', 'Steady', 'Fair', 'Strong', 'Maxed'];
+
+/** The server fields the flags give (only the ones given), as the office API takes them. */
+export function serverFields(flags) {
+  const f = {};
+  const get = (k) => (flags.has(k) ? flags.get(k) : undefined);
+  const n = (k, as) => { const v = get(k); if (v !== undefined && v !== true) f[as] = Number(v); };
+  if (get('policy') !== undefined) f.policy = String(get('policy'));
+  n('ai', 'aiSeats'); n('ai-seats', 'aiSeats'); n('guides', 'guides'); n('level', 'level'); n('level-max', 'levelMax'); n('rooms', 'rooms');
+  n('beginner-days', 'beginnerDays');
+  if (get('beginner-level') !== undefined) f.beginnerLevel = get('beginner-level') === 'none' ? null : Number(get('beginner-level'));
+  if (get('seats') !== undefined) f.seats = get('seats') === 'game' ? null : Number(get('seats'));
+  if (get('kids') !== undefined) f.kids = get('kids') === true || get('kids') === 'on';
+  if (get('listed') !== undefined) f.listed = !(get('listed') === 'off' || get('listed') === 'no');
+  for (const k of ['door', 'speech', 'bots', 'blurb', 'id', 'name']) if (get(k) !== undefined && get(k) !== true) f[k] = String(get(k));
+  return f;
+}
+
+const levelWord = (n) => `${LEVELS[n - 1] ?? 'Fair'} (${n})`;
+
+export async function serversList(root, { url, game } = {}) {
+  const r = await withKey(root, url, (call) => call(`/_studio/api/servers${game ? `?game=${encodeURIComponent(game)}` : ''}`));
+  if (!r.ok) return { ok: false, command: 'servers', why: r.message ?? r.why ?? 'the studio did not answer' };
+  return { ok: true, command: 'servers', games: r.games ?? [], fillSpot: r.fillSpot ?? null };
+}
+
+export async function serversNew(root, game, name, flags, { url } = {}) {
+  if (!GAME.test(String(game ?? '')) || !String(name ?? '').trim()) return { ok: false, command: 'servers new', why: 'usage: homie-studio servers new <game> "<Name>" --policy open|humans-only|hybrid|beginner [--ai <n>] [--guides <n>] [--kids]' };
+  const body = { game, name, ...serverFields(flags) };
+  if (!body.policy) return { ok: false, command: 'servers new', why: 'say the policy: --policy open, humans-only, hybrid (with --ai <n>) or beginner (with --guides <n>)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/servers', body));
+  if (!r.ok) return { ok: false, command: 'servers new', why: r.message ?? r.why };
+  return { ok: true, command: 'servers new', game, server: r.server, notes: r.notes ?? [], message: `${r.server?.name} is open: ${r.server?.page}` };
+}
+
+export async function serversSet(root, game, server, flags, { url } = {}) {
+  if (!GAME.test(String(game ?? '')) || !(SERVER.test(String(server ?? '')) || server === 'public')) return { ok: false, command: 'servers set', why: 'usage: homie-studio servers set <game> <server> [--policy …] [--level-max 3] [--door accounts] …' };
+  const fields = serverFields(flags);
+  delete fields.id;
+  if (!Object.keys(fields).length) return { ok: false, command: 'servers set', why: 'say what to change: --name, --policy, --ai, --guides, --kids, --door, --level, --level-max, --speech, --bots, --rooms, --seats, --listed' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/servers/set', { game, server, ...fields }));
+  return askedFor(root, url, r, 'servers set');
+}
+
+export async function serversClose(root, game, server, { url, reopen } = {}) {
+  if (!GAME.test(String(game ?? '')) || !(SERVER.test(String(server ?? '')) || server === 'public')) return { ok: false, command: 'servers close', why: 'usage: homie-studio servers close <game> <server> [--reopen]' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/servers/close', { game, server, reopen: Boolean(reopen) }));
+  return askedFor(root, url, r, 'servers close');
+}
+
+export async function serversLevel(root, game, room, level, { url } = {}) {
+  const n = Math.floor(Number(level));
+  if (!GAME.test(String(game ?? '')) || !room || !(n >= 1 && n <= 5)) return { ok: false, command: 'servers level', why: 'usage: homie-studio servers level <game> <room> <1-5> (1 Rookie, 2 Steady, 3 Fair, 4 Strong, 5 Maxed)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/room-level', { game, room, level: n }));
+  return r.ok ? { ok: true, command: 'servers level', game, room, level: r.level, message: `The AI in ${room} plays at ${levelWord(r.level)} now.` } : { ok: false, command: 'servers level', why: r.message ?? r.why };
+}
+
+export async function serversMember(root, game, server, player, { url, role, remove } = {}) {
+  if (!GAME.test(String(game ?? '')) || !SERVER.test(String(server ?? '')) || !player) return { ok: false, command: 'servers member', why: 'usage: homie-studio servers member <game> <server> <player id> --role member|mentor|mod | --remove' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/servers/member', { game, server, player, ...(remove ? { remove: true } : { role: role ?? 'member' }) }));
+  return askedFor(root, url, r, 'servers member');
+}
+
+export async function agentsPass(root, game, { url, label, server, hands, role, days } = {}) {
+  if (!label || label === true) return { ok: false, command: 'agents pass', why: 'usage: homie-studio agents pass <game|any> --label "<Name>" [--server <id>] [--hands self|host] [--days 7]' };
+  const g = game && game !== 'any' ? game : null;
+  if (g && !GAME.test(g)) return { ok: false, command: 'agents pass', why: 'the game is one of this studio\'s game ids, or "any"' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/pass', { action: 'create', game: g, label, server: server ?? null, hands: hands ?? 'self', role: role ?? 'party', days: days === undefined ? 7 : days === 'never' ? null : Number(days) }));
+  if (!r.ok) return { ok: false, command: 'agents pass', why: r.message ?? r.why };
+  return {
+    ok: true, command: 'agents pass', pass: r.pass, secret: r.secret,
+    use: `${r.use} Keep the pass as a secret: never in a file of this repository, a chat or an issue.`,
+  };
+}
+
+export async function agentsPasses(root, game, { url } = {}) {
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/pass', { action: 'list', game: game ?? null }));
+  return r.ok ? { ok: true, command: 'agents passes', passes: r.passes ?? [] } : { ok: false, command: 'agents passes', why: r.message ?? r.why };
+}
+
+export async function agentsRevoke(root, id, { url } = {}) {
+  if (!/^[a-f0-9]{10}$/.test(String(id ?? ''))) return { ok: false, command: 'agents revoke', why: 'usage: homie-studio agents revoke <pass id> (agents passes lists them)' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/pass', { action: 'revoke', id }));
+  return r.ok ? { ok: true, command: 'agents revoke', revoked: id, left: r.left ?? 0, message: `Pass ${id} revoked${r.left ? `: its AI left ${r.left} room(s)` : ''}.` } : { ok: false, command: 'agents revoke', why: r.message ?? r.why };
+}
+
+export async function agentsBrain(root, game, server, mode, { url } = {}) {
+  if (!GAME.test(String(game ?? '')) || !server || !['off', 'script', 'workers-ai', 'owner-key'].includes(mode)) return { ok: false, command: 'agents brain', why: 'usage: homie-studio agents brain <game> <server> off|script|workers-ai|owner-key' };
+  const r = await withKey(root, url, (call) => call('/_studio/api/agents/brain', { game, server, mode }));
+  return askedFor(root, url, r, 'agents brain');
+}
+
+/** One line per server for a person (the CLI's print). */
+export function serversLines(r) {
+  const lines = [];
+  for (const g of r.games ?? []) {
+    lines.push(`${g.name} (${g.id})${g.build?.predates ? `: its build predates servers (netplay rev ${g.build.netplayRev ?? '5 or older'}); rebuild for AI seats and the dial` : ''}`);
+    for (const s of g.servers ?? []) {
+      const live = s.live ?? { rooms: 0, players: 0, ai: 0 };
+      lines.push(`  ${s.name} [${s.id}]: ${s.badge}${s.kids ? ', kids' : ''}, bots ${s.bots}, ${levelWord(s.level)} (ceiling ${LEVELS[s.levelMax - 1]}), door ${s.door}${s.state !== 'open' ? `, ${s.state.toUpperCase()}` : ''} · ${live.rooms ? `${live.rooms} room(s), ${live.players} playing, ${live.ai} AI` : 'no live rooms'}${s.members ? ` · ${s.members} members` : ''}`);
+    }
+    for (const p of (g.passes ?? []).filter((x) => x.live)) lines.push(`  pass ${p.id}: ${p.name} (${p.role}, hands ${p.hands}${p.server ? `, ${p.server} only` : ''})`);
+  }
+  if (r.fillSpot && !r.fillSpot.available) lines.push(`(${r.fillSpot.note})`);
+  return lines;
+}

package/lib/template-history.json

@@ -407,6 +407,61 @@
      "## Beta": "9d02638207a26e73"
     }
    }
+  },
+  "0.15.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "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)": "e579cd6ce3ce342a",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
+  },
+  "0.16.0": {
+   "files": {
+    "CLAUDE.md": "ddf2b2a0376202f6",
+    "README.md": "684b3cca8001673c",
+    "HANDOFF.md": "ce7a8fd91c6bbee2",
+    "games/README.md": "5ad32fe80c61f117",
+    "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)": "e579cd6ce3ce342a",
+     "## The site": "ab922bb6bde23293",
+     "## Making games": "a8a893eeada33bf5",
+     "## The Game Codex and progress": "0738ef719cef3a4c",
+     "## Running live games (the back office)": "f0566f07cff04113",
+     "## Servers and AI seats": "961ac5e8ccc2a548",
+     "## Continuing a build from the Claude app": "0d68081e924ca419",
+     "## Rules": "969318425c99f5a5",
+     "## Beta": "9d02638207a26e73"
+    }
+   }
   }
  }
 }