@homie-rocks/studio 0.9.0 → 0.11.0

package/README.md

@@ -10,7 +10,7 @@ Most people never run this by hand: the Homie plugin for Claude Code and Codex d
 and the person approves Cloudflare once in their browser.
 
 ```sh
-npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio new ./night-owls --name "Night Owls"
+npx -y @homie-rocks/studio new ./night-owls --name "Night Owls"
 cd night-owls && npm install
 npx homie-studio game new crown-thief --from gem-rush --name "Crown Thief"
 npx homie-studio dev                                   # the whole site locally
@@ -22,6 +22,32 @@ npx homie-studio stats                                 # the studio's own number
 npx homie-studio upgrade                               # what a newer template adds to this studio (--apply to take it)
 ```
 
+## From GitHub, with Cloudflare's own CI (Workers Builds, Previews, Deploy to Cloudflare)
+
+A studio keeps `wrangler.jsonc` at its root (a studio made before 0.10.0 keeps `site/wrangler.jsonc`, and every
+command still finds it), so Cloudflare's Workers Builds can build and deploy it from its GitHub repository with no
+computer involved:
+
+| Workers Builds runs | On | What happens |
+| --- | --- | --- |
+| `npm run build` | every push | `homie-studio build`: the site, with the commit it is built from |
+| `npm run deploy` | the production branch | In Workers Builds (`WORKERS_CI=1`), `homie-studio deploy` only applies the D1 migrations (by binding name) and deploys: the Worker and database are Cloudflare's to make, so it creates and refuses nothing. The first deploy creates the database as it goes. |
+| `npx wrangler preview` | every other branch | A **Preview**: its own URL, and its own Durable Object namespace, so a branch's public rooms never meet production's. A Preview has no D1: it counts nothing into the studio's stats and never claims itself in the directory. |
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/homie-rocks/homie/tree/main/template)
+
+The button copies the public template (`template/` in this repository, exactly what `homie-studio new --template`
+writes) into the person's GitHub, makes the Worker, the D1 database and the rooms on their Cloudflare account,
+and connects Workers Builds. The site plays its first game (Gem Rush) the moment it is up, and its Home has a
+**Connect to Claude** band: one tap links it to the Claude chat that set it up (the Homie MCP tool `studio_setup`).
+In the Claude Code session that works in the repository, `homie-studio setup attach <hs_…>` then gives the studio
+the name chosen in the chat and removes the band.
+
+**The site claims itself in the directory.** The homie.rocks directory lists a studio only when its site serves
+the claim the directory handed out for that address. From 0.10.0 the site asks for it the first time its
+`/.well-known/homie-studio.json` is read (by `studio_publish`, or by `deploy` reading it once) and keeps it in
+its D1; nothing is stored by hand. studio.json `homie.directory: false` keeps a studio out.
+
 ## The site: the hub's shape, and a landing for every game
 
 Every studio site has the same sections as homie.rocks, in the studio's own look (`site/theme.json`): Home (the
@@ -46,8 +72,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 --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade          # the plan; changes nothing
-npx -y --package=https://homie.rocks/npm/homie-studio-0.9.0.tgz homie-studio upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@0.11.0 upgrade          # the plan; changes nothing
+npx -y @homie-rocks/studio@0.11.0 upgrade --apply  # after the person agrees
 npm install && npm run build
 ```
 
@@ -87,6 +113,60 @@ 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.
 
+## Setup status
+
+```sh
+npx -y @homie-rocks/studio@0.11.0 setup status --connector yes   # before a studio exists
+npx homie-studio setup status                                    # in a studio (also: homie-studio doctor)
+```
+
+One checklist of what this computer and the person's accounts have for a studio: Node.js, the Homie
+connector (the AI says whether its Homie tools are there; the directory is reached), Cloudflare (signed in
+with the studio's own Wrangler, and the account's email verified: a deploy that went through proves it, a
+deploy refused for it is remembered), Chrome for the checks, ffmpeg, and the optional GitHub, ElevenLabs and
+fal (and, in Claude Code, the status line). Each row is green, missing or "do this now", says what it
+unlocks, and gives the exact fix: a command the AI runs or a page the person taps. It only reads, answers in
+seconds, and never prints a key, a token or an account's name. A studio the Claude app's setup card made
+(`setup attach`) counts as connected to Cloudflare and GitHub there. `--json` gives the rows.
+
+## The Game Codex
+
+`games/<id>/CODEX.md` is a game's plan: Markdown with a small frontmatter for its look (palette, fonts, a
+cover, pixel art) and a few conventions that become cards (`### Name` with a picture, `` `M-01` `` id and tag
+chips, an italic subtitle and `**Key:** value` stats), tables, checklists, a dated decision log and open
+questions (`lib/codex.mjs` has the whole format).
+
+```sh
+npx homie-studio codex new crown-thief          # every section, in the studio's colours
+npx homie-studio codex crown-thief --open       # .studio/codex/crown-thief.html, in the browser
+npx homie-studio codex crown-thief --artifact   # one self-contained page to publish as a Claude artifact
+npx homie-studio codex link crown-thief         # a one-time link to the site's private copy
+```
+
+The page has a tab per section and a **Build status** tab from the game's progress feed; the local copy
+redraws itself whenever the feed changes and refreshes in the browser while a build runs. `npm run build`
+puts each game's codex on the site at `/_studio/codex/<id>/`, served only to the studio's owner (the same
+one-time sign-in as the stats page), never listed or indexed. Text is escaped and the page runs only its own
+script (the site allows it by its hash); pictures and fonts come only from inside the studio and are
+embedded, so it loads nothing but Google Fonts. CODEX.md is never in a game's remix source or among a
+static game's served files.
+
+## The Claude Code status line
+
+```sh
+npx homie-studio statusline --install    # .claude/settings.local.json: this person, this studio
+npx homie-studio statusline --install --project ..   # Claude Code started in the folder above the studio
+npx homie-studio statusline --remove
+```
+
+One line under the prompt, from the current build's feed: `▶ Crown Thief · Checks ▰▰▰▰▰▰▱▱▱▱ 62% · 3/5 checks
+· $0.40 of $2.00`; the studio's name, dimmed, when nothing runs; a finished build's result for ten minutes.
+Claude Code runs `bin/statusline.mjs` with the session as JSON on stdin (it reads only the studio's progress
+files, in about 40 ms) and, with the 5 s `refreshInterval` it sets, keeps it moving while a long check runs.
+It never replaces a status line the person already has (`--replace` puts this one in for this studio only).
+Plugins cannot set a status line, so it is always the person's yes. Codex CLI's status line takes only its
+own built-in items, so there the codex page is the progress view.
+
 ## A build the person can watch (the progress feed)
 
 A build of a game, song or video can keep a small progress feed, so the person follows it
@@ -108,6 +188,27 @@ check green ends the build. The AI marks what only it knows with `progress stage
 one runs, a shared feed asks whether Stop was pressed; a stopped command closes its
 browsers and says so, and nothing already built or deployed is undone.
 
+**From the Claude app.** The chat can open the build first (the Homie MCP tool `build_open`, or the "Build it"
+card on a make, port or remix) and hand the work to a Claude Code session with a prefilled prompt. The session
+takes the build once, with no key in the prompt, and the card follows it; the change goes out as a pull request
+the person merges with one tap:
+
+```sh
+npx homie-studio progress attach hb_…                  # this session takes the build the chat opened (once)
+npx homie-studio progress change "Crowns spawn twice as often"   # its mark, in changes/, committed with the change
+git switch -c faster-crowns && git add -A && git commit -m "Faster crowns" && git push -u origin HEAD
+gh pr create --fill                                     # then:
+npx homie-studio progress pr --url https://github.com/<owner>/<repo>/pull/<n>
+```
+
+Workers Builds deploys the branch as a Preview; the card's **Publish** opens the pull request in GitHub, where the
+person's merge is the approval; Workers Builds deploys `main`, and the card says **Live** when the live site's
+manifest lists the change's mark (`homie-studio build` lists the newest marks from `changes/`).
+
+A Claude Code cloud session's default network ("Trusted") does not reach homie.rocks; the toolkit says so, and
+names the setting (the environment's Network access: Custom, add homie.rocks), instead of "did not answer". The
+build goes on with its local feed.
+
 The feed is `.studio/progress/<build>.json` (git-ignored). With `--share` the studio's
 directory (studio.json `homie.directory`, homie.rocks by default) keeps a copy for 24
 hours so the Claude app can show it: the feed only (plain bounded text, pictures under
@@ -121,6 +222,14 @@ feed every command behaves exactly as before. `lib/progress.mjs` has the whole f
 names the Cloudflare account, often after its owner. A custom domain goes in studio.json
 as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `stats` use.
 
+## Checks on a computer without a GPU
+
+`check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud
+session, GitHub Actions, a container) `npx homie-studio chrome install` puts Chrome for Testing in
+the home folder's `.cache/homie-studio` (from storage.googleapis.com, which a cloud session's default network reaches), and WebGL
+renders with SwiftShader. `check` reports how fast each browser drew the game and on what renderer; on SwiftShader
+it says the frame rate is not a person's, and judges only seats, rooms and rounds.
+
 ## No payment method needed
 
 `deploy` creates only what Cloudflare's free Workers plan gives a new account with no
@@ -157,9 +266,11 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `bin/homie-studio.mjs` | The CLI. |
 | `lib/scaffold.mjs` | `new`: the studio monorepo, only into a new or empty folder, every file listed. |
 | `lib/build.mjs` | `build`: games bundled with esbuild into `site/dist`, `games.json`, each game's shared `source.json`. |
-| `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations, the directory claim; refuses resources it did not create. `storage add`: the optional R2 bucket. |
-| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. |
+| `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket. |
+| `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
+| `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
+| `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |
 | `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`. |
@@ -171,9 +282,10 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `starters/gem-rush/` | The reference multiplayer starter. |
 
 Versions are immutable: a published version never changes, so a studio that pinned one
-never changes by surprise. A change ships as a new `version`, on the npm registry as
-`@homie-rocks/studio` and as a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`
-(which is what `homie-studio new` pins).
+never changes by surprise. A change ships as a new `version` on the npm registry as
+`@homie-rocks/studio`, which is what `homie-studio new` pins (the exact version; package-lock.json keeps its
+integrity). The registry is what Workers Builds and a Claude Code cloud session reach by default. Older studios
+pinned a tarball at `https://homie.rocks/npm/homie-studio-<version>.tgz`, which stays.
 
 ## Beta
 

package/bin/homie-studio.mjs

@@ -4,7 +4,8 @@
  * put its site on the studio's own Cloudflare (free plan, no payment method), and
  * list its games in the homie.rocks directory.
  *
- *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install]
+ *   homie-studio new <folder> --name "<Studio Name>" [--homie <directory url>] [--no-install] [--template]
+ *                                         (--template: the public "Deploy to Cloudflare" template: a first game and a Connect band)
  *   homie-studio starters
  *   homie-studio game new <id> [--from gem-rush] [--name "<Game Name>"]
  *   homie-studio game remix <source.json url> --id <new id>
@@ -12,12 +13,16 @@
  *   homie-studio build [<id>]
  *   homie-studio dev [--port 8787]        (--stop: stop exactly this studio's dev server, nothing else)
  *   homie-studio check <id> [--url <site>] [--shots <dir>]
+ *   homie-studio chrome [install] [--fresh]  (which Chrome the checks use; on Linux, `install` fetches Chrome for Testing;
+ *                                          --fresh fetches it even when the machine has a Chrome)
  *   homie-studio look [<path>...] [--url <site>] [--shots <dir>] [--only computer,phone,sideways]
  *                                         (the site's pages on a computer and a phone, as pictures, with what is wrong)
  *   homie-studio port plan <game folder>
  *   homie-studio port import <game folder> --id <id> [--name "<Name>"] [--mode static|bundle|command]
  *   homie-studio port check <id> [--url <site>] [--only owner-desk,owner-phone,owner-iphone,round,life,tv] [--shots <dir>]
  *   homie-studio deploy [--plan]          (--plan: what it will create on Cloudflare and what it costs; changes nothing)
+ *                                         In Cloudflare's Workers Builds (WORKERS_CI=1, or --ci) it only applies the D1
+ *                                         migrations and deploys: the Worker and database are the Deploy button's.
  *   homie-studio publish
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
  *   homie-studio media put <file> [--as <key>]
@@ -46,11 +51,36 @@
  *   homie-studio progress log "<one line>"
  *   homie-studio progress stop            (ask the running build to stop at its next safe point)
  *   homie-studio progress end passed|failed|stopped [--note "<one line>"]
+ *   homie-studio progress attach <hb_…>   (the build the Claude app opened with build_open: this session takes it, once)
+ *   homie-studio progress change "<what the change does>"   (its mark in changes/, committed with the change)
+ *   homie-studio progress pr --url <pull request> [--state open|merged|closed] [--files n --additions n --deletions n]
+ *                                         [--preview <Preview URL>]   (the card's Publish opens it for the person's merge)
  *   homie-studio progress show [<build>]
  *                                         While a feed is open, build, check, port check and deploy report
  *                                         into it (stage, each check going green, a preview picture) and stop
  *                                         when asked. Without one, nothing changes.
  *
+ *   homie-studio setup attach <hs_…>      (this repository is the studio the Claude app's setup card is making: say so, once,
+ *                                          learn its live address, and give a template copy its real name)
+ *   homie-studio setup status [--connector yes|no]   (also: homie-studio doctor)
+ *                                         what this computer and the person's accounts have for a studio: Node, the Homie
+ *                                         connector, Cloudflare (signed in, email verified), Chrome, ffmpeg, GitHub,
+ *                                         ElevenLabs, fal; green, missing or "do this now", what each unlocks and its
+ *                                         exact fix. Read-only and safe any time, inside a studio or before one exists.
+ *
+ *   homie-studio codex new <id>           games/<id>/CODEX.md: the Game Codex, every section, in the game's colours
+ *   homie-studio codex <id> [--artifact] [--open]
+ *                                         the codex as a page in the game's own look (.studio/codex/<id>.html; it redraws
+ *                                         itself as the build's progress changes); --artifact: a copy to publish as a
+ *                                         Claude artifact; --open: open it in this computer's browser
+ *   homie-studio codex link <id>          a one-time link to the codex on the live site (a private page for the owner)
+ *
+ *   homie-studio statusline               the current build in one line (what Claude Code's status line shows)
+ *   homie-studio statusline --install [--project <folder>]
+ *                                         turn it on in Claude Code for this studio (.claude/settings.local.json);
+ *                                         --project: the folder Claude Code was started in, when that is above the
+ *                                         studio; --remove turns it off; --replace when another status line is set
+ *
  * Every command prints a few lines for a person; --json prints the result.
  */
 import { spawn, spawnSync } from 'node:child_process';
@@ -58,7 +88,9 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, wr
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { check } from '../lib/check.mjs';
-import { deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { setupAttach } from '../lib/setup.mjs';
+import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { publish } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
@@ -66,14 +98,17 @@ import { portCheck } from '../lib/port-check.mjs';
 import { recordUpload, resolveMedia, typeOf } from '../lib/media.mjs';
 import { ensureStatsMigration, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
-import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters } from '../lib/studio.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 { Feed, currentFeed, currentId, flushProgress, publicFeed, readFeed, startProgress } from '../lib/progress.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';
+import { installStatusLine, statusLine } from '../lib/statusline.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff'];
+const BOOL_FLAGS = ['json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -114,6 +149,7 @@ function print(result) {
       for (const m of result.mediaSkipped ?? []) lines.push(`  left out: ${m.kind}/${m.item}${m.file ? ` ${m.file}` : ''}: ${m.why}`);
       for (const m of result.postsSkipped ?? []) lines.push(`  left out: posts/${m.post}: ${m.why}`);
       for (const m of result.siteSkipped ?? []) lines.push(`  left out: ${m.what}: ${m.why}`);
+      if (result.codexes?.length) lines.push(`Game Codex (the owner's private pages; codex link <id> opens one): ${result.codexes.map((x) => `/_studio/codex/${x}/`).join(', ')}`);
       break;
     case 'media list':
       for (const kind of ['music', 'videos']) {
@@ -123,10 +159,14 @@ function print(result) {
       }
       break;
     case 'deploy':
+      if (result.ci) {
+        lines.push(`Live: ${result.url ?? '(Wrangler printed no address)'}${result.commit ? ` (commit ${result.commit.slice(0, 7)}${result.branch ? ` on ${result.branch}` : ''})` : ''}`, ...result.steps.map((x) => `  ${x.what}`), ...result.games.map((g) => `  ${g.id}: ${g.play}`));
+        break;
+      }
       lines.push(`Live: ${result.url}`, ...(result.workersDev && result.workersDev !== result.url ? [`  also at ${result.workersDev}`] : []),
         ...(result.local ? [`  (the workers.dev address names your Cloudflare account, so it is kept in ${result.local} on this computer, never in studio.json)`] : []),
         ...result.games.map((g) => `  ${g.id}: ${g.play}`), ...(result.songs ?? []).map((m) => `  song ${m.slug}: ${m.page}`), ...(result.videos ?? []).map((m) => `  video ${m.slug}: ${m.page}`), '', `Cloudflare: Worker ${result.worker}, D1 ${result.d1}, Durable Objects Table + Lobby${result.r2 ? `, R2 ${result.r2}` : ' (no storage: none needed; `homie-studio storage add` adds it for large media)'}. All on the free Workers plan${result.r2 ? ' plus R2' : ''}.`,
-        result.claim ? 'Directory claim stored: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the directory did not answer); publish will try again.');
+        result.claim ? 'The site claimed itself in the directory: list the games with the Homie MCP tool studio_publish, or: npx --no-install homie-studio publish' : 'No directory claim yet (the site claims itself when the directory first reads it; publish does).');
       break;
     case 'deploy plan':
       lines.push(`What \`npm run deploy\` does for ${result.studio}, on the Cloudflare account the person approves:`, '',
@@ -179,6 +219,31 @@ function print(result) {
     case 'stats share':
       lines.push(result.message);
       break;
+    case 'setup status':
+      lines.push(formatStatus(result));
+      break;
+    case 'codex':
+      lines.push(`The Game Codex for ${result.title}: ${result.file}${result.opened ? ' (opened in the browser)' : ''}`,
+        `  tabs: ${result.sections.map((x) => x.title).join(' · ')} · Build status${result.build ? ` (${result.build.state}, ${result.build.percent}%)` : ''}`,
+        ...(result.missing.length ? [`  not decided yet: ${result.missing.join(', ')}`] : ['  every section has something in it']),
+        `  open questions: ${result.openQuestions}`,
+        ...result.warnings.map((w) => `  warning: ${w}`),
+        result.mode === 'artifact' ? '  publish this file as an artifact where your app can (Claude: the Artifact tool); it is one self-contained page' : '  on the site, for the owner only, after the next deploy: npx --no-install homie-studio codex link ' + result.id);
+      break;
+    case 'codex new':
+      lines.push(`Wrote ${result.file}.`, ...result.next.map((n) => `  next: ${n}`));
+      break;
+    case 'codex link':
+      lines.push(`One-time link (until ${result.expiresAt}): ${result.link}`, result.use);
+      break;
+    case 'statusline install':
+    case 'statusline remove':
+      lines.push(result.message);
+      break;
+    case 'setup attach':
+      lines.push(result.message, ...(result.site ? [`  live site: ${result.site}`] : []), ...(result.renamed?.length ? ['  changed (commit these on a branch):', ...result.renamed.map((f) => `    ${f}`)] : []), ...(result.next ?? []).map((n) => `  next: ${n}`));
+      break;
+    case 'progress attach':
     case 'progress start':
       lines.push(`Build ${result.build}: ${result.title} (${result.stages.join(' → ')})${result.budget !== null ? `, budget ${result.unit === 'usd' ? `$${result.budget.toFixed(2)}` : `${result.budget} credits`}` : ''}`,
         `  feed: ${result.file}`,
@@ -230,9 +295,15 @@ function print(result) {
       if (result.next?.length) lines.push('', 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
     }
+    case 'chrome':
+    case 'chrome install':
+      lines.push(result.already || result.command === 'chrome' ? `Chrome: ${result.chrome}` : `Installed Chrome for Testing ${result.buildId}: ${result.chrome}`);
+      break;
     case 'check':
       lines.push(`PASS: two fresh browsers in room ${result.room} finished round ${result.round.n} (${result.round.humans} humans, ${result.round.bots} bots) in ${Math.round(result.totalMs / 1000)} s.`,
-        ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`));
+        ...result.seats.map((s) => `  ${s.browser}: seat ${s.seat} (${s.role}), seated in ${(s.seatedMs / 1000).toFixed(1)} s`),
+        ...(result.frames ?? []).map((f) => `  ${f.browser} drew ${f.fps ?? '?'} fps${f.renderer ? ` on ${f.renderer}` : ''}`),
+        ...(result.software ? [`  ${result.software}`] : []));
       break;
     default:
       lines.push(JSON.stringify(result, null, 2));
@@ -248,12 +319,24 @@ async function main() {
     return { ok: true, command: 'help' };
   }
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
-  if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install') });
+  if (cmd === 'new') return newStudio(positional[1], { name: flags.get('name'), homie: flags.get('homie'), slug: flags.get('slug'), install: !flags.has('no-install'), template: flags.has('template') });
   if (cmd === 'starters') return { ok: true, command: 'starters', starters: starters() };
 
   if (cmd === 'port' && sub === 'plan') return planPort(positional[2] ?? '.');
+  if (cmd === 'chrome' && sub === 'install') return installChrome({ log, fresh: flags.has('fresh') });
+  if (cmd === 'chrome') { const chrome = findChrome(); return chrome ? { ok: true, command: 'chrome', chrome, args: chromeArgs() } : { ok: false, command: 'chrome', why: noChrome() }; }
+  if ((cmd === 'setup' && sub === 'status') || cmd === 'doctor') return setupStatus({ connector: flags.get('connector') ?? null, homie: flags.get('homie') ?? null });
+  if (cmd === 'statusline' && !flags.has('install') && !flags.has('remove')) {
+    const line = statusLine({ columns: Number(process.env.COLUMNS) || 100, color: !process.env.NO_COLOR && !asJson && process.stdout.isTTY });
+    if (asJson) return { ok: true, command: 'statusline', line };
+    if (line) process.stdout.write(`${line}\n`);
+    return { ok: true, command: 'help' };
+  }
   const root = requireStudio();
+  if (cmd === 'statusline') return installStatusLine(root, { remove: flags.has('remove'), replace: flags.has('replace'), project: flags.get('project') ?? null });
+  if (cmd === 'codex') return codexCommand(root, sub);
   if (cmd === 'progress') return progressCommand(root, sub);
+  if (cmd === 'setup' && sub === 'attach') return setupAttach(root, positional[2], { homie: flags.get('homie') });
   if (cmd === 'port' && sub === 'import') return importPort(root, positional[2], flags.get('id'), { name: flags.get('name'), mode: flags.get('mode') });
   if (cmd === 'port' && sub === 'check') {
     const game = positional[2] ?? listGames(root)[0]?.id;
@@ -295,6 +378,8 @@ async function main() {
     return look({ url, paths, shots: flags.get('shots') ? resolve(flags.get('shots')) : join(root, '.studio', 'look'), devices: only, log });
   }
   if (cmd === 'deploy' && flags.has('plan')) return deployPlan(root);
+  // Cloudflare's Workers Builds runs `npm run deploy` with WORKERS_CI=1 (and its own token for this one account).
+  if (cmd === 'deploy' && (process.env.WORKERS_CI === '1' || flags.has('ci'))) return tracked(root, 'deploy', () => ciDeploy(root, { log }), 'deploy');
   if (cmd === 'deploy') return tracked(root, 'deploy', () => deploy(root, { log, homie: flags.get('homie') }), 'deploy');
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
   if (cmd === 'storage') {
@@ -318,6 +403,28 @@ async function main() {
   return { ok: false, command: cmd, why: `unknown command "${[cmd, sub].filter(Boolean).join(' ')}" (homie-studio help)` };
 }
 
+/** `homie-studio codex …` (lib/codex.mjs): the Game Codex of one game. */
+function codexCommand(root, sub) {
+  const games = listGames(root);
+  if (sub === 'new') return newCodex(root, positional[2] ?? (games.length === 1 ? games[0].id : undefined));
+  if (sub === 'link') {
+    const id = positional[2] ?? (games.length === 1 ? games[0].id : null);
+    if (!id || !games.some((g) => g.id === id)) return { ok: false, command: 'codex link', why: 'name the game: homie-studio codex link <id>' };
+    const r = statsLink(root, { url: flags.get('url') });
+    if (!r.ok) return { ...r, command: 'codex link' };
+    return { ...r, command: 'codex link', link: `${r.link}&to=${encodeURIComponent(codexTarget(id))}`, use: 'Give this link to the studio\'s owner to open in their own browser: it works once, within 30 minutes, opens the codex, and keeps that browser signed in to the studio\'s private pages (the codex and the stats) for 30 days. Do not post it anywhere.' };
+  }
+  const id = sub ?? (games.length === 1 ? games[0].id : null);
+  if (!id) return { ok: false, command: 'codex', why: `name the game: homie-studio codex <id> (${games.map((g) => g.id).join(', ') || 'no games yet'})` };
+  let r;
+  try { r = writeCodexPage(root, id, { mode: flags.has('artifact') ? 'artifact' : 'file' }); } catch (error) { return { ok: false, command: 'codex', why: error.message }; }
+  if (flags.has('open')) {
+    const opener = process.platform === 'darwin' ? ['open', [r.path]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', r.path]] : ['xdg-open', [r.path]];
+    r.opened = spawnSync(opener[0], opener[1], { stdio: 'ignore', timeout: 10_000 }).status === 0;
+  }
+  return r;
+}
+
 /*
  * THE PROGRESS FEED (lib/progress.mjs). A command that is a stage of the open build (build, check, port check,
  * deploy) says so: the stage runs, then is done or failed with one line; a check's steps go green as they pass; a
@@ -372,6 +479,12 @@ async function progressCommand(root, sub) {
       budget: flags.get('budget'), unit: flags.get('unit'), share: flags.has('share'), directory: flags.get('homie'),
     });
   }
+  if (sub === 'attach') {
+    return startProgress(root, {
+      attach: arg ?? null, what: flags.get('what') ?? 'game', id: flags.get('id') ?? null, title: flags.get('title'),
+      budget: flags.get('budget'), unit: flags.get('unit'), directory: flags.get('homie'),
+    });
+  }
   if (sub === 'show') {
     const id = arg ?? currentId(root) ?? flags.get('build');
     const doc = readFeed(root, id);
@@ -400,8 +513,10 @@ async function progressCommand(root, sub) {
       }
       case 'log': feed.log(positional.slice(2).join(' ')); return done('logged');
       case 'stop': feed.stop('local'); return done('stop asked: the running command stops at its next safe point');
+      case 'change': { const c = recordChange(root, id, positional.slice(2).join(' ') || flags.get('title')); return { ...done(`change recorded: commit ${c.file} with the change`), file: c.file, mark: c.mark }; }
+      case 'pr': feed.pr({ url: flags.get('url'), state: flags.get('state') ?? 'open', title: flags.get('title'), branch: flags.get('branch'), files: flags.get('files'), additions: flags.get('additions'), deletions: flags.get('deletions'), preview: flags.get('preview'), site: siteUrl(root) }); return done(`pull request on the card: ${feed.doc.change.url}`);
       case 'end': feed.end(arg, note); return done(`ended: ${arg}`);
-      default: return { ok: false, command: 'progress', why: `unknown: progress ${sub ?? ''} (start, stage, check, preview, spend, shot, song, log, stop, end, show)` };
+      default: return { ok: false, command: 'progress', why: `unknown: progress ${sub ?? ''} (start, attach, stage, check, preview, spend, shot, song, log, change, pr, stop, end, show)` };
     }
   } catch (error) { return { ok: false, command: 'progress', why: error instanceof Error ? error.message : String(error) }; }
 }
@@ -411,7 +526,7 @@ async function progressCommand(root, sub) {
  * and `dev --stop` stops exactly those two (each checked to still be a process of this studio's folder), so an AI
  * never has to reach for `pkill -f "wrangler dev"`, which stops every project's dev server on the machine.
  */
-const devFile = (root) => join(root, 'site', '.wrangler', 'homie-dev.json');
+const devFile = (root) => join(workerDir(root), '.wrangler', 'homie-dev.json');
 function processOfStudio(pid, root, kind) {
   if (!Number.isInteger(pid) || pid <= 1 || pid === process.pid) return false;
   try { process.kill(pid, 0); } catch { return false; }
@@ -450,11 +565,11 @@ async function dev(root) {
   const added = ensureStatsMigration(root);
   if (added) log(`added ${added} (the studio's own stats)`);
   await new Promise((done) => {
-    const m = spawn(bin, ['d1', 'migrations', 'apply', studio.cloudflare.d1, '--local'], { cwd: join(root, 'site'), env, stdio: ['ignore', 'ignore', 'inherit'] });
+    const m = spawn(bin, ['d1', 'migrations', 'apply', 'DB', '--local'], { cwd: workerDir(root), env, stdio: ['ignore', 'ignore', 'inherit'] });
     m.on('close', done);
   });
   log(`Local site: http://127.0.0.1:${port}/  (each game: http://127.0.0.1:${port}/<id>/play — open it in two browsers)`);
-  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: join(root, 'site'), env, stdio: 'inherit' });
+  const child = spawn(bin, ['dev', '--local', '--ip', '127.0.0.1', '--port', port], { cwd: workerDir(root), env, stdio: 'inherit' });
   mkdirSync(dirname(devFile(root)), { recursive: true });
   writeFileSync(devFile(root), `${JSON.stringify({ pid: process.pid, child: child.pid, port: Number(port), at: new Date().toISOString() })}\n`);
   log(`Stop it with: npx --no-install homie-studio dev --stop   (this studio's dev server only)`);
@@ -477,7 +592,7 @@ function mediaPut(root, file, as) {
   const key = as ?? (/^(music|videos)\//.test(rel) && !rel.includes('..') ? rel : `${folder}/${basename(file)}`);
   const bin = wranglerBin(root);
   return new Promise((done) => {
-    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: join(root, 'site'), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
+    const p = spawn(bin, ['r2', 'object', 'put', `${r2}/${key}`, '--file', resolve(file), '--content-type', typeOf(file), '--remote'], { cwd: workerDir(root), env: { ...process.env, CI: '1' }, stdio: ['ignore', 'ignore', 'inherit'] });
     p.on('close', (code) => {
       if (code !== 0) return done({ ok: false, command: 'media put', why: 'wrangler r2 object put failed' });
       // The manifest is committed: it names the file by its path on the site, never the workers.dev address.

package/bin/statusline.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * The Claude Code status line for a Homie studio (lib/statusline.mjs). Claude Code runs it with the session as
+ * JSON on stdin and shows what it prints; it must be quick and must never fail loudly, so it reads only the
+ * studio's own progress files and prints nothing at all when anything goes wrong.
+ *
+ *   echo '{"workspace":{"current_dir":"."}}' | node node_modules/@homie-rocks/studio/bin/statusline.mjs
+ */
+import { statusLine } from '../lib/statusline.mjs';
+
+let input = '';
+let printed = false;
+function print() {
+  if (printed) return;
+  printed = true;
+  let dirs = [process.cwd()];
+  try {
+    const session = JSON.parse(input || '{}');
+    dirs = [session?.workspace?.current_dir, session?.workspace?.project_dir, session?.cwd, process.cwd()].filter((d) => typeof d === 'string' && d);
+  } catch { /* no session: this folder */ }
+  // `--studio <folder>`: set up in the folder above the studio, the setting names the studio.
+  const named = process.argv.indexOf('--studio');
+  if (named > 0 && process.argv[named + 1]) dirs.push(process.argv[named + 1]);
+  try {
+    const columns = Number(process.env.COLUMNS) || 100;
+    const color = !process.env.NO_COLOR;
+    for (const dir of dirs) {
+      const line = statusLine({ dir, columns, color });
+      if (line) { process.stdout.write(`${line}\n`); break; }
+    }
+  } catch { /* quiet: a status line never shows a stack */ }
+  // A caller that never closes stdin must not keep this process alive.
+  if (!process.stdin.isTTY) process.stdin.destroy();
+}
+if (process.stdin.isTTY) print();
+else {
+  const timer = setTimeout(print, 400);
+  process.stdin.on('data', (d) => { input += d; });
+  process.stdin.on('end', () => { clearTimeout(timer); print(); });
+  process.stdin.on('error', () => { clearTimeout(timer); print(); });
+}

package/lib/build.mjs

@@ -10,6 +10,8 @@
  *                                          posts/*.md and the studio's site/ folder (site/SITE.md)
  *   site/dist/games/<id>/_landing/...      what the game's landing shows (hero footage, its cover, licence texts)
  *   site/dist/_site/                       posts.json (the posts' HTML), the studio's own pages (site/pages)
+ *   site/dist/_studio/codex/<id>/          each game's Game Codex (games/<id>/CODEX.md, lib/codex.mjs): served only to
+ *                                          the studio's owner (worker/stats-page.mjs), never listed or indexed
  *   site/dist/<file>                       site/public, as it is (fonts, a logo, hero footage)
  *   site/dist/music/..., site/dist/videos/...   media files the site serves itself (R2 keys are served from R2)
  *
@@ -25,6 +27,7 @@ import { spawnSync } from 'node:child_process';
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
+import { buildCodexPages } from './codex.mjs';
 import { buildMedia } from './media.mjs';
 import { buildSiteFiles, landingOf, readPosts, readTheme } from './site.mjs';
 import { PACKAGE_ROOT, listGames, readStudio } from './studio.mjs';
@@ -33,7 +36,7 @@ import { STUDIO_VERSION } from './version.mjs';
 
 const SOURCE_SKIP = new Set(['node_modules', 'dist', '.git', '.wrangler', '.port']);
 /** Never copied into a static game's served folder. */
-const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md']);
+const STATIC_SKIP = new Set(['node_modules', '.git', '.wrangler', '.port', '.DS_Store', 'game.json', 'PORT.md', 'CODEX.md']);
 const LOADERS = { '.png': 'file', '.jpg': 'file', '.jpeg': 'file', '.gif': 'file', '.webp': 'file', '.mp3': 'file', '.ogg': 'file', '.wav': 'file', '.m4a': 'file', '.glb': 'file', '.gltf': 'file', '.bin': 'file', '.hdr': 'file', '.svg': 'file', '.json': 'json', '.woff2': 'file', '.ttf': 'file' };
 
 /** The port toolkit as one classic script (window.HomiePort), for static games. Built once per build. */
@@ -67,7 +70,7 @@ export function sourceOf(dir, id) {
   let total = 0;
   const walk = (rel) => {
     for (const entry of readdirSync(join(dir, rel), { withFileTypes: true })) {
-      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name)) continue;
+      if (entry.name.startsWith('.') || SOURCE_SKIP.has(entry.name) || (!rel && entry.name === 'CODEX.md')) continue;
       const path = rel ? `${rel}/${entry.name}` : entry.name;
       if (entry.isDirectory()) walk(path);
       else if (TEXT.test(entry.name)) {
@@ -82,6 +85,34 @@ export function sourceOf(dir, id) {
   return { v: 1, kind: 'homie-game-source', id, files };
 }
 
+/*
+ * WHAT THIS BUILD IS, for the site's manifest: the commit and branch (Cloudflare's Workers Builds names them in
+ * WORKERS_CI_COMMIT_SHA and WORKERS_CI_BRANCH; elsewhere git is asked), when it was built, and the marks of the
+ * newest changes in changes/ (lib/progress.mjs recordChange), so the Claude app's card can tell when a merged pull
+ * request is live. Nothing here names a person or an account.
+ */
+export function buildInfo(root) {
+  const git = (args) => { try { const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 5000 }); return r.status === 0 ? r.stdout.trim() : null; } catch { return null; } };
+  const commit = /^[a-f0-9]{40}$/.test(process.env.WORKERS_CI_COMMIT_SHA ?? '') ? process.env.WORKERS_CI_COMMIT_SHA : git(['rev-parse', 'HEAD']);
+  const branch = String(process.env.WORKERS_CI_BRANCH || git(['rev-parse', '--abbrev-ref', 'HEAD']) || '').slice(0, 100) || null;
+  const marks = [];
+  const dir = join(root, 'changes');
+  if (existsSync(dir)) {
+    for (const name of readdirSync(dir).filter((n) => n.endsWith('.json'))) {
+      const c = readJson(join(dir, name));
+      if (c && /^[a-f0-9]{16}$/.test(String(c.change)) && !Number.isNaN(Date.parse(c.at))) marks.push({ mark: c.change, at: c.at });
+    }
+  }
+  marks.sort((a, b) => b.at.localeCompare(a.at));
+  return {
+    commit: /^[a-f0-9]{40}$/.test(String(commit)) ? commit : null,
+    branch: branch && /^[A-Za-z0-9._/-]+$/.test(branch) && branch !== 'HEAD' ? branch : null,
+    at: new Date().toISOString(),
+    ci: process.env.WORKERS_CI === '1' ? 'workers-builds' : null,
+    changes: [...new Set(marks.map((m) => m.mark))].slice(0, 50),
+  };
+}
+
 function readJson(path) {
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
 }
@@ -194,6 +225,8 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   });
   const { posts, skipped: postsSkipped } = readPosts(root, { games: rows, songs: media.songs, videos: media.videos, log });
   const site = buildSiteFiles(root, dist, { gameIds: rows.map((g) => g.id), log });
+  // Each game's Game Codex (games/<id>/CODEX.md), as the owner's private page at /_studio/codex/<id>/ (never listed).
+  const codexes = buildCodexPages(root, dist, games.map((g) => g.id), { log });
   mkdirSync(join(dist, '_site'), { recursive: true });
   writeFileSync(join(dist, '_site', 'posts.json'), `${JSON.stringify({ v: 1, posts })}\n`);
   const s = studio.site && typeof studio.site === 'object' ? studio.site : {};
@@ -207,9 +240,16 @@ export async function build(root, { only = null, log = () => {} } = {}) {
         ...(Array.isArray(s.frameAncestors) ? { frameAncestors: s.frameAncestors.filter((o) => /^https:\/\/[a-z0-9.-]+(?::\d+)?$/i.test(String(o))).slice(0, 8) } : {}),
       },
       // studio.json `stats.share`: the site tells the directory two numbers for the hub (played this week).
-      ...(studio.stats?.share === true ? { stats: { share: true }, directory: studio.homie?.directory ?? 'https://homie.rocks' } : {}),
+      ...(studio.stats?.share === true ? { stats: { share: true } } : {}),
       // studio.json `"rooms": { "share": false }`: the manifest names no rooms, so the hub shows none of this studio's.
       ...(studio.rooms?.share === false ? { rooms: { share: false } } : {}),
+      // The directory the live site claims itself in (0.10.0); studio.json `homie.directory: false` keeps it out.
+      // HOMIE_DIRECTORY (a build variable) points one build at another directory, such as a staging one.
+      directory: /^https:\/\/[a-z0-9.-]+$/i.test(process.env.HOMIE_DIRECTORY ?? '') ? process.env.HOMIE_DIRECTORY
+        : studio.homie?.directory === false || studio.homie?.directory === null ? null : String(studio.homie?.directory ?? 'https://homie.rocks'),
+      // A copy of the public template that nobody has named yet shows the name typed in Cloudflare's form.
+      ...(studio.template === true ? { template: true } : {}),
+      build: buildInfo(root),
     },
     games: rows,
     songs: media.songs,
@@ -222,7 +262,7 @@ export async function build(root, { only = null, log = () => {} } = {}) {
   return {
     ok: true, command: 'build', dist, games: built, catalogue: catalogue.games.map((g) => g.id),
     songs: catalogue.songs.map((e) => e.slug), videos: catalogue.videos.map((e) => e.slug), mediaSkipped: media.skipped,
-    posts: posts.map((p) => p.slug), postsSkipped, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
+    posts: posts.map((p) => p.slug), postsSkipped, codexes, pages: site.pages, partials: Object.keys(site.partials), public: site.public.length, siteSkipped: site.skipped,
     landings: rows.map((g) => ({ id: g.id, hero: g.landing.hero.wide || g.landing.hero.tall ? 'footage' : g.landing.hero.wideImage ? 'art' : 'colours', credits: Boolean(g.landing.credits.original || g.landing.credits.people.length), source: g.landing.source })),
   };
 }