@homie-rocks/studio 0.31.0 → 0.31.1

package/CHANGELOG.md

@@ -17,9 +17,41 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.31.1] - 2026-10-06
+
+**Plugin 0.32.1** · [#53](https://github.com/homie-rocks/homie/pull/53)
+
+Fixes from two creators' notes on 0.31.0: Homie's holds run in Grok, `publish --before` publishes nothing, a page that loses its room is never stuck, a missing setting is never a silent zero, and a part's preview fits a phone.
+
+### Added
+
+- `@homie-rocks/camera/heading.js` (camera 0.2.1): `headingFrom({ zero: '+x', toward: '+z' })` converts your game's own heading into the camera's and back, and `headingOfVector(dx, dz)` does it from a forward vector. The package now says plainly which way its heading points (yaw 0 faces +Z, a positive yaw turns toward +X, in radians), with a picture in the README and in the types. In development the follow camera warns once when the subject keeps travelling one way while its heading says another, and names the adapter; mark reversing frames with `reversing: true`, or turn it off with `followState({ headingCheck: false })`.
+- `net.prefs.number`, `net.prefs.boolean` and `net.prefs.string` read a setting with your fallback for a missing key, a null, a wrong type or a read before the prefs arrived, and say so once in the console. `net.prefs.set` refuses a `NaN` or anything else that would be kept as `null`.
+- `createRoom({ fallback })`, seat or solo: `'solo'` plays a private round with bots until the room has a body for the player, `'spectate'` watches, and `room.standing` says where the player stands. NETPLAY.md section 28 is the recipe, and the late-join checklist has the slow-boot, mid-round join.
+- A shared part can say the shape of its preview: `"aspect": "4:3"` and, for phones, `"phoneAspect": "3:4"` in `preview` (whole numbers 1 to 32, no flatter than 3:1, no taller than 1:2; 16:9 if you say nothing). Every part preview has an "Open the preview" link that shows it in a tab of its own.
+- On a custom domain, a deploy and its plan warn before anything goes live when another site's catch-all or wildcard route covers your studio's address: leave that route alone, and add the one line shown (or `deploy --own-route`). When the routes cannot be read, it says so rather than saying all is well.
+
+### Fixed
+
+- **Homie's holds run in Grok once you trust the plugin.** 0.30.2 said Grok runs no plugin's hooks. That was wrong: Grok takes a plugin's hooks from its main manifest, ours named none there, and Grok was loading the Claude Code file instead and finding nothing. A secret is also now really taken out of what the AI reads in Grok (it was only being flagged beside the output). `setup status --client grok` says whether the holds ran and how to turn them on.
+- **`publish --before` publishes nothing.** It asks the directory whether you are listed and how many publishes are left today. In 0.31.0 the command line ignored the flag and published.
+- Commands that change something outside your computer (deploy, publish, storage, the office and others) stop at a flag they do not know, before anything is sent. `deploy --dry-run` was one such flag: it used to deploy.
+- A page that loses its room no longer shows "Reconnecting…" for ever: after 20 seconds (`reconnectMaxMs`) it plays on its own with bots, says so, and rejoins when the room answers. The line over the game says what is true: "Reconnecting…" only to a page that was connected, and a full room is said in words with a way to another room.
+- A player who is seated while every body is taken gets one as soon as a body frees up or the next round starts, instead of watching for the rest of the visit.
+- A browser that freezes for a few seconds while a heavy game boots no longer drops its connection when it wakes.
+- A part's preview is no longer cut off on a phone: a narrow frame is at least 320 px tall instead of about 197.
+- The 3D starters say which of their angles a camera can take as it stands and which needs converting.
+
+### Upgrade notes
+
+- Grok: install or reinstall the plugin with trust, `grok plugin install homie-rocks/homie#plugins/homie --trust`. From then on a deploy, a Cloudflare change and a paid call are held for your "proceed", as in Codex.
+- A studio that pins 0.31.0 still publishes on `publish --before` from its own command line until it upgrades.
+- If your game reads settings with `net.prefs.get`, move numbers to `net.prefs.number(key, fallback)`: a `null` kept by an older build is now read as nothing kept.
+- `@homie-rocks/camera` is 0.2.1.
+
 ## [0.31.0] - 2026-10-06
 
-**Plugin 0.32.0** · [#50](https://github.com/homie-rocks/homie/pull/50)
+**Plugin 0.32.0** · [#50](https://github.com/homie-rocks/homie/pull/50) · [release-2026-10-06-studio-0.31.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-06-studio-0.31.0)
 
 Fixes from two creators' logs of building real studios: games now build on each other by sharing parts (remix is retired), a slow 3D game keeps its host, local play stays local, and synthesized bass plays at its written pitch.
 

package/README.md

@@ -496,8 +496,8 @@ this toolkit alone (`new`, `deploy`, `publish`), and the connector row says so.
   an address or a command; the command itself is never read out.
 - **Homie's holds**: whether the plugin's hooks ran in this app in the last ten minutes, from the dated mark
   they leave in `.cache/homie-studio/holds/` of the home folder. Off means nothing is held: Codex runs no plugin's hooks
-  until the person trusts them in `/hooks`, and the row says so; Grok Build 1.0.41 runs no plugin's hooks at all, so
-  there the row is off until a Grok that does.
+  until the person trusts them in `/hooks`, and Grok Build runs them once the plugin is trusted
+  (`grok plugin install … --trust`); the row says which.
 
 `homie-studio demo` answers without a network too (0.30.2): where it cannot reach the arcade it names the arcade's
 standing first pick, with `reached: false`.
@@ -659,10 +659,14 @@ as `cloudflare.domain` and is what the directory claim, `publish`, `check` and `
 
 **Routes.** `deploy` writes `wrangler.jsonc` again each time, and keeps the routes that are the studio's own exactly
 as they were written: a custom domain (`{ "pattern": "play.example.com", "custom_domain": true }`) and an exact-host
-route (`{ "pattern": "play.example.com/*", "zone_name": "example.com" }`). A zone's other routes are never listed,
-changed or removed. When the zone already has a wildcard route on another Worker (`*example.com/*`), that Worker
-answers the studio's hostname first; the deploy notices that its own domain answers as something else and prints the
-exact-host route to add, once. A wildcard or catch-all route (`*/*`) in the studio's own config would hand every
+route (`{ "pattern": "play.example.com/*", "zone_name": "example.com" }`). A zone's other routes are never
+changed or removed. On a custom domain, `deploy` and `deploy --plan` read the domain's Worker routes first (two GETs
+with the sign-in Wrangler already has) and warn, before anything is deployed, when another Worker's catch-all (`*/*`)
+or wildcard (`*example.com/*`) covers the studio's hostname: that route answers the hostname before the studio does,
+it belongs to another site on the domain, and it must not be edited or removed. The warning gives the one safe fix,
+the studio's own exact-host route, as the exact line; `deploy --own-route` adds that line and nothing else, only when
+the read showed it is needed. Routes that could not be read are said as unmeasured, never as fine; after the deploy,
+a domain that answers as something else still gets the route to add. A wildcard or catch-all route (`*/*`) in the studio's own config would hand every
 hostname of the zone to the studio's Worker, so `deploy` refuses it before it asks Cloudflare anything; a studio that
 really owns the whole zone says so in studio.json (`"cloudflare": { "allowWildcardRoutes": true }`).
 

package/bin/homie-studio.mjs

@@ -87,9 +87,17 @@
  *                                         One deploy of a studio at a time (a lock in .studio/); it says which games changed
  *                                         with each one's content hash, keeps the studio's own custom-domain and exact-host
  *                                         routes in wrangler.jsonc, and never deploys a wildcard or catch-all route.
+ *                                         On a custom domain, the plan and the deploy read the domain's Worker routes and
+ *                                         warn when another site's catch-all or wildcard covers the studio's hostname
+ *                                         (never edit or remove that route). --own-route adds the studio's own
+ *                                         exact-host route, the one safe fix, when that read shows it is needed.
  *                                         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                  (the directory's beta has a daily cap: it says how many publishes are left)
+ *   homie-studio publish [--before]       (the directory's beta has a daily cap: it says how many publishes are left)
+ *                                         --before publishes NOTHING: it asks the directory (a read) whether the site
+ *                                         is listed and how many publishes are left today, and says the parts' licences.
+ *                                         A command that changes something outside this computer (deploy, publish,
+ *                                         storage add, the office, …) stops at a flag it does not know: nothing is sent.
  *   homie-studio storage add              (large media only: an R2 bucket; needs R2 turned on for the account)
  *   homie-studio media list               (every song and video page, where each file is served from, what moves to R2)
  *   homie-studio media move [<file>...] [--dry-run] [--verify]
@@ -287,11 +295,11 @@ import { basename, join, relative, resolve } from 'node:path';
 import { build } from '../lib/build.mjs';
 import { PREVIEW_PORT, previewServer } from '../lib/preview.mjs';
 import { check } from '../lib/check.mjs';
-import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin } from '../lib/cloudflare.mjs';
+import { ciDeploy, deploy, deployPlan, mediaMove, storageAdd, whoami, wranglerBin, zonePlan } from '../lib/cloudflare.mjs';
 import { setupAttach } from '../lib/setup.mjs';
 import { chromeArgs, findChrome, installChrome, noChrome } from '../lib/chrome.mjs';
 import { deployWords } from '../lib/deploy-state.mjs';
-import { publish } from '../lib/directory.mjs';
+import { publish, publishBefore } from '../lib/directory.mjs';
 import { look } from '../lib/look.mjs';
 import { importPort, planPort } from '../lib/port.mjs';
 import { portCheck } from '../lib/port-check.mjs';
@@ -333,7 +341,7 @@ import { trailerCommand, trailerLines } from '../lib/trailer.mjs';
 
 const argv = process.argv.slice(2);
 const flags = new Map();
-const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite'];
+const BOOL_FLAGS = ['off', 'revoke', 'json', 'yes', 'detach', 'no-install', 'plan', 'stop', 'share', 'apply', 'diff', 'template', 'ci', 'fresh', 'install', 'remove', 'replace', 'artifact', 'open', 'reopen', 'kids', 'remote-ai', 'dry-run', 'verify', 'maps', 'profile', 'hands-on', 'automatic', 'unlock', 'confirm', 'no-library', 'no-validate', 'rigged', 'no-rig', 'supporter', 'managed', 'live', 'send', 'accept-tos', 'quiet', 'no-local-ai', 'timestamps', 'overwrite', 'own-route', 'before'];
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
@@ -459,11 +467,15 @@ function print(result) {
         ...result.cloudflare.map((r) => `  ${r.kind}${r.name ? ` ${r.name}` : ''}: ${r.what} [${r.state}${r.plan ? `; ${r.plan}` : ''}]`), '',
         `Cost: ${result.cost}`, `Sign-in: ${result.login}`, `Address: ${result.address}`,
         `The directory (${result.directory.site}) stores: ${result.directory.stores}`, result.never,
+        ...(result.zone?.warning ? ['', `Warning: ${result.zone.warning}`] : result.zone?.why ? ['', result.zone.why] : []),
         ...(result.parts && partsPlanLines(result.parts).length ? ['', ...partsPlanLines(result.parts)] : []));
       break;
     case 'storage add':
       lines.push(result.already ? `Storage is already added: R2 bucket ${result.bucket}.` : `Storage added: R2 bucket ${result.bucket}.`, 'Next:', ...result.next.map((n) => `  ${n}`));
       break;
+    case 'publish before':
+      lines.push(...result.lines);
+      break;
     case 'publish':
       lines.push(`Listed in the directory: ${result.studioPage ?? result.directory}`, ...(result.games ?? []).map((g) => `  ${g.name}: ${g.play}`), ...(result.publishes?.line ? [result.publishes.line] : []),
         // The parts in what was listed, in the deploy plan's own lines (lib/parts-build.mjs).
@@ -743,6 +755,52 @@ function print(result) {
   process.stdout.write(`${lines.join('\n')}\n`);
 }
 
+/*
+ * A COMMAND THAT CHANGES SOMETHING OUTSIDE THIS COMPUTER NEVER RUNS WITH A FLAG IT DOES NOT KNOW. The parser above
+ * keeps every `--word`, and a command reads the ones it knows: `publish --before` (a flag the MCP tool had and this
+ * command did not) was read as plain `publish`, and listed the studio while its caller believed it was a preflight.
+ * So each command below names every flag it takes, and anything else stops it before anything is sent: a typo, a
+ * flag of another command, or one from a newer toolkit's notes. The key is the command and its sub-command, else
+ * the command alone. Commands that only read, or only change files in this folder, are not in this table.
+ */
+const OUTWARD_FLAGS = {
+  publish: ['homie', 'site', 'before'],
+  deploy: ['plan', 'ci', 'homie', 'own-route'],
+  'storage add': [],
+  'media put': ['as'],
+  'media move': ['dry-run', 'plan', 'verify'],
+  'setup attach': ['homie', 'client'],
+  handoff: ['homie', 'client'],
+  'players owner': ['url', 'revoke'],
+  'stats key': ['url', 'hours'], 'stats link': ['url'], 'stats revoke': ['url'], 'stats share': [],
+  'office link': ['url', 'to'], 'office key': ['url', 'hours'], 'office announce': ['url', 'game', 'room', 'seconds'],
+  'office invite': ['url', 'label', 'uses', 'count', 'days', 'server'], 'office launch': ['url', 'max'],
+  'office kick': ['url', 'minutes'], 'office mute': ['url', 'minutes', 'off'], 'office close': ['url', 'minutes', 'reopen'], 'office revoke': ['url'],
+  'lounge mod': ['url', 'remove'], 'lounge remove': ['url', 'all'],
+  'chat remove': ['url', 'all'], 'chat budget': ['url'],
+  'servers close': ['url', 'reopen'], 'servers level': ['url'], 'servers member': ['url', 'role', 'remove'],
+  'shop connect': ['url', 'managed', 'live'], 'shop disconnect': ['url'], 'shop refund': ['url', 'reason', 'note'], 'shop statements': ['url', 'period', 'send'],
+  'agents pass': ['url', 'label', 'server', 'hands', 'role', 'days'], 'agents revoke': ['url'], 'agents brain': ['url', 'budget', 'remove'],
+  'agents sit': ['url', 'server', 'pass', 'label', 'brain'],
+};
+/** Every command takes these: how it answers, never what it does. */
+const ANY_COMMAND = ['json', 'help', 'version'];
+
+/** The refusal for a flag an outward-writing command does not take, or null. Nothing has run when this is asked. */
+function unknownFlags(words, given) {
+  const [cmd, sub] = words;
+  const key = sub !== undefined && OUTWARD_FLAGS[`${cmd} ${sub}`] ? `${cmd} ${sub}` : OUTWARD_FLAGS[cmd] ? cmd : null;
+  if (!key) return null;
+  const takes = OUTWARD_FLAGS[key];
+  const strange = [...given.keys()].filter((k) => !takes.includes(k) && !ANY_COMMAND.includes(k));
+  if (!strange.length) return null;
+  const named = strange.map((k) => `--${k}`).join(', ');
+  return {
+    ok: false, command: key, needs: 'flag', flags: strange, takes: takes.map((k) => `--${k}`),
+    why: `homie-studio ${key} does not take ${named}, so it did not run: nothing was sent or changed. It changes something outside this computer, and a flag it does not know is never guessed at. It takes: ${takes.length ? takes.map((k) => `--${k}`).join(', ') : 'no flags of its own'} (and --json).`,
+  };
+}
+
 async function main() {
   const [cmd, sub] = positional;
   if (!cmd || cmd === 'help' || flags.has('help')) {
@@ -751,6 +809,8 @@ async function main() {
     return { ok: true, command: 'help' };
   }
   if (cmd === 'version' || flags.has('version')) return { ok: true, command: 'version', version: STUDIO_VERSION };
+  const strange = unknownFlags(positional, flags);
+  if (strange) return strange;
   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() };
   // The floor's built-in words need no studio: anyone can read what a studio's chat always holds.
@@ -870,16 +930,21 @@ async function main() {
     const only = flags.get('only') ? String(flags.get('only')).split(',').filter((d) => ['computer', 'phone', 'sideways'].includes(d)) : undefined;
     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), parts: partsPublishReport(root) };
+  if (cmd === 'deploy' && flags.has('plan')) {
+    // On a custom domain the plan also reads the domain's Worker routes (lib/routes.mjs): a read, nothing changes.
+    const zone = await zonePlan(root);
+    return { ...deployPlan(root), parts: partsPublishReport(root), ...(zone ? { zone } : {}) };
+  }
   // 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 === 'deploy') return tracked(root, 'deploy', () => deploy(root, { log, homie: flags.get('homie'), ownRoute: flags.has('own-route') }), 'deploy');
   if (cmd === 'storage' && sub === 'add') return storageAdd(root, { log });
   if (cmd === 'storage') {
     const cf = readStudio(root).cloudflare ?? {};
     const has = Boolean(cf.r2 && (cf.created ?? []).includes(`r2:${cf.r2}`));
     return { ok: true, command: 'storage', storage: has ? { kind: 'r2', bucket: cf.r2 } : null, why: has ? undefined : 'no storage yet: the studio runs without it; `homie-studio storage add` adds an R2 bucket for large media (Cloudflare asks for a payment method before R2 works)' };
   }
+  if (cmd === 'publish' && flags.has('before')) return publishBefore(root, { homie: flags.get('homie'), site: flags.get('site'), log: () => {} });
   if (cmd === 'publish') return publish(root, { homie: flags.get('homie'), site: flags.get('site'), log });
   if (cmd === 'players' && sub === 'owner') return playersOwner(root, { url: flags.get('url'), revoke: flags.has('revoke') });
   if (cmd === 'players' && !sub) return playersShow(root, { url: flags.get('url') });

package/lib/cloudflare.mjs

@@ -19,21 +19,28 @@
  * It REFUSES to touch a Worker, database or bucket of that name that this
  * studio did not create (studio.json `cloudflare.created` is the record), so it
  * can never overwrite someone's existing site. `deploy --plan` says all of this
- * before anything happens and calls nothing.
+ * before anything happens and changes nothing.
+ *
+ * A studio on a CUSTOM DOMAIN shares that domain with whatever else its owner
+ * runs there. The plan and the deploy read the domain's Worker routes (a read,
+ * with Wrangler's own sign-in) and warn when another site's catch-all or
+ * wildcard covers the studio's hostname: that route is never the studio's to
+ * edit or remove (lib/routes.mjs, zoneCheck below).
  */
 import { spawn, spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { cloudflareAuth } from './brain-probe.mjs';
 import { build } from './build.mjs';
 import { builtGames, compareDeploy, deployWords, lastDeploy, lastDeployRecord, lockDeploy, recordDeploy } from './deploy-state.mjs';
 import { listedHere, publish } from './directory.mjs';
 import { MAX_ASSET_BYTES, R2_COST, mediaPlan, r2OverOf, recordMove, sha256File, sizeOf } from './media.mjs';
 import { whyFailed } from './net.mjs';
 import { repoOf } from './repo.mjs';
-import { keptRoutes, readConfig, shadowedDomain, wideRouteRefusal } from './routes.mjs';
+import { keptRoutes, readConfig, readZoneRoutes, routesOf, shadowedDomain, wideRouteRefusal, zoneFinding } from './routes.mjs';
 import { ensureLocalIgnored, ensureMigrations, migrationWord, wranglerConfig } from './scaffold.mjs';
-import { LOCAL_STATE, configPath, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
+import { LOCAL_STATE, configPath, domainOrigin, isWorkersDev, layoutOf, readLocal, readStudio, siteUrl, workerDir, writeLocal, writeStudio } from './studio.mjs';
 import { projectsCloudflareEnv } from './projects-env.mjs';
 
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -106,6 +113,54 @@ export function explainCloudflare(out, accountId = null) {
   return null;
 }
 
+/** The studio's custom hostname ("play.example.com"), or null for a studio on its workers.dev address. */
+export function customHost(studio) {
+  const cf = studio?.cloudflare ?? {};
+  const origin = domainOrigin(cf.domain) ?? (cf.url && !isWorkersDev(cf.url) ? domainOrigin(cf.url) : null);
+  return origin ? new URL(origin).hostname : null;
+}
+
+/**
+ * For a studio on a custom domain: what the domain's other Worker routes mean for it (lib/routes.mjs zoneFinding),
+ * read from Cloudflare with the sign-in Wrangler already has (lib/brain-probe.mjs cloudflareAuth: a token in the
+ * environment, else `wrangler auth token`). Null for a studio with no custom domain, which is asked nothing. It
+ * only reads; a list that cannot be read comes back as state 'unmeasured' with the reason. `config` stands in for
+ * wrangler.jsonc (a deploy that is about to add a route), `fetchFn` for the network in tests.
+ */
+export async function zoneCheck(root, { studio = readStudio(root), config = readConfig(root), accountId = null, fetchFn = null } = {}) {
+  const hostname = customHost(studio);
+  if (!hostname) return null;
+  const worker = studio.cloudflare?.worker ?? null;
+  // The toolkit's own tests (HOMIE_STUDIO_WARM=0) with no stand-in network ask nobody, as readLiveSite does.
+  if (!fetchFn && process.env.HOMIE_STUDIO_WARM === '0') return zoneFinding({ hostname, worker, config, zone: { read: false, why: 'not asked' } });
+  const bin = wranglerBin(root);
+  let headers = null;
+  try {
+    const w = bin ? runner(root, accountId ? { CLOUDFLARE_ACCOUNT_ID: accountId } : {}) : null;
+    headers = await cloudflareAuth({
+      env: { ...process.env, ...projectsCloudflareEnv(root) }, bin, cwd: root,
+      exec: async (_bin, args) => { const r = w(args, { cwd: root }); return { code: r.code, stdout: r.stdout }; },
+    });
+  } catch { headers = null; }
+  const zone = await readZoneRoutes({ hostname, config, headers, ...(fetchFn ? { fetchFn } : {}) });
+  return zoneFinding({ hostname, worker, config, zone });
+}
+
+/** A zone finding as a deploy's result and its plan carry it: the state, the routes that are not the studio's, the one line. */
+function zoneView(z) {
+  return {
+    state: z.state, host: z.host, domain: z.zone, foreign: z.foreign.map((r) => ({ pattern: r.pattern, worker: r.script, kind: r.kind })),
+    ...(z.state === 'foreign' || z.state === 'unmeasured' ? { route: z.route, line: z.line } : {}),
+    ...(z.warning ? { warning: z.warning } : {}), ...(z.why ? { why: z.why } : {}),
+  };
+}
+
+/** `deploy --plan` for a studio on a custom domain: the plan, and what the domain's other routes mean for it. */
+export async function zonePlan(root, opts = {}) {
+  const z = await zoneCheck(root, opts);
+  return z ? zoneView(z) : null;
+}
+
 /** What `deploy` will create and what it costs, from studio.json alone. It calls nothing. */
 export function deployPlan(root) {
   const studio = readStudio(root);
@@ -150,7 +205,7 @@ export async function deploy(root, opts = {}) {
   try { return await deployLocked(root, opts); } finally { process.off('exit', onExit); lock.release(); }
 }
 
-async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}) {
+async function deployLocked(root, { log = () => {}, homie, fetchFn = null, ownRoute = false } = {}) {
   const studio = readStudio(root);
   const cf = { r2: null, created: [], ...studio.cloudflare };
   const created = new Set(cf.created ?? []);
@@ -159,7 +214,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   // studio's own routes exactly as its owner wrote them.
   const wide = wideRouteRefusal(readConfig(root), studio);
   if (wide) return { ok: false, command: 'deploy', ...wide };
-  const routes = keptRoutes(root, studio);
+  let routes = keptRoutes(root, studio);
   const who = whoami(root);
   if (!who) {
     if (cf.auth === 'stripe-projects') {
@@ -186,6 +241,25 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   };
   const steps = [];
   const step = (what, extra = {}) => { steps.push({ what, ...extra }); log(what); };
+  const notes = [];
+
+  // A studio on a custom domain: is another site's catch-all or wildcard route on the same domain covering its
+  // hostname? Read (never written) and said before Wrangler changes anything: the repair that suggests itself,
+  // editing or removing that route, takes the other site down (lib/routes.mjs). `--own-route` adds the one line
+  // that is the studio's to add, and only when the domain's routes were read and show it is needed.
+  let zone = await zoneCheck(root, { studio, accountId, fetchFn });
+  if (zone) {
+    if (ownRoute && zone.state === 'foreign') {
+      routes = [...(routes ?? []), zone.route];
+      step(`added the studio's own exact-host route to "routes" in wrangler.jsonc: ${zone.line}. It covers ${zone.host} only, and every deploy keeps it; the other site's route was not touched.`, { route: zone.route });
+      const config = readConfig(root) ?? {};
+      zone = await zoneCheck(root, { studio, accountId, fetchFn, config: { ...config, routes: [...routesOf(config), zone.route] } });
+    } else if (ownRoute) {
+      step(`--own-route added nothing: ${zone.state === 'unmeasured' ? 'the domain\'s routes could not be read, so the domain\'s name in Cloudflare is not known for sure' : zone.state === 'taken' ? `${zone.host} is routed to another Worker, which only the person can change` : zone.state === 'own-route' ? 'the studio\'s own exact-host route is already there' : `no other route covers ${zone.host}`}.`);
+    }
+    if (zone.warning) { notes.push(zone.warning); step(`warning: ${zone.warning}`, { needs: 'cloudflare-routes', ...(zone.state === 'foreign' ? { route: zone.route } : {}) }); }
+    else if (zone.why) step(zone.why);
+  } else if (ownRoute) step('--own-route added nothing: this studio has no custom domain (studio.json cloudflare.domain).');
 
   // The first deploy says what it is about to create, and what it costs, before it creates anything: the person
   // reads it in the transcript whether or not the AI repeated it.
@@ -290,7 +364,6 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
   const directory = homie || studio.homie?.directory || 'https://homie.rocks';
   recordDeploy(root, builtNow);
   let claim = null;
-  const notes = [];
   if (url) {
     const read = await readLiveSite(url, fetchFn ? { fetchFn } : {});
     claim = read.claim;
@@ -340,6 +413,7 @@ async function deployLocked(root, { log = () => {}, homie, fetchFn = null } = {}
     games: b.catalogue.map((id) => { const g = delta.games.find((x) => x.id === id); return { id, page: url ? `${url}/${id}/` : null, play: url ? `${url}/${id}/play` : null, hash: g?.hash ?? null, change: delta.first ? 'first deploy from this computer' : g?.change ?? null }; }),
     ...(delta.removed.length ? { removed: delta.removed } : {}),
     ...(routes ? { routes: routes.map((r) => r.pattern) } : {}),
+    ...(zone ? { zone: zoneView(zone) } : {}),
     ...(notes.length ? { notes } : {}),
     ...(reread ? { reread } : {}),
     songs: b.songs.map((slug) => ({ slug, page: url ? `${url}/music/${slug}/` : null })),

package/lib/directory.mjs

@@ -16,10 +16,11 @@ import { partsPlanLines, partsPublishReport } from './parts-build.mjs';
  * `publishesLeft`, or those inside `quota` / `limits` / `rateLimit`), or the standard rate-limit headers
  * (`ratelimit-remaining`, `x-ratelimit-remaining`, `retry-after`). What it finds is said after every publish.
  *
- * Before a publish there is nothing to ask (the directory has no "how many are left" call this toolkit knows), so
- * the toolkit says what THIS COMPUTER knows: how many it has sent today (UTC, the day the cap counts in), and
- * what the directory said was left after the last one. That is a floor, never a promise: a publish from another
- * computer or from the Homie connector is not counted here.
+ * Before a publish, `publishBefore` asks the directory itself, with a read (GET /api/studio/publish?site=<origin>
+ * answers { ok, site, listed, limit, remaining, resetsAt } and changes nothing). When the directory cannot be
+ * reached, or is one that has no such read, it says so plainly and falls back to what THIS COMPUTER knows: how many
+ * it has sent today (UTC, the day the cap counts in), and what the directory said was left after the last one. That
+ * is a floor, never a promise: a publish from another computer or from the Homie connector is not counted here.
  */
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : typeof v === 'string' && /^\d+$/.test(v.trim()) ? Number(v) : null);
 const first = (...values) => { for (const v of values) { const n = num(v); if (n !== null) return n; } return null; };
@@ -82,16 +83,67 @@ export function partsForListing(root) {
   return { ...report, games, ok: games.every((g) => g.ok) && !report.why };
 }
 
-export async function publish(root, { homie, site, log = () => {}, fetchFn } = {}) {
-  const studio = readStudio(root);
-  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
-  const url = site || siteUrl(root, studio);
-  // Licences first: a public game may ship only assets with a licence record that allows it.
+/** The asset licence problems that stop a listing: a public game may ship only assets with a licence record that allows it. */
+function licenceRefusals(root) {
   const refused = [];
   for (const g of listGames(root)) {
     if (g.launch === 'private' || g.launch === 'invite') continue;
     for (const p of licenceProblems(root, g.id, readManifest(root, g.id))) if (p.level === 'refuse') refused.push({ game: g.id, ...p });
   }
+  return refused;
+}
+
+/**
+ * `homie-studio publish --before` and the studio_publish tool's `before: true`, one code path: what a publish would
+ * meet, and NOTHING is published. It sends one GET (the directory's own read-only count for this site), never a
+ * POST, and writes no file, not even this computer's count. { ok: true, published: false, listed, publishes: {
+ * remaining, limit, resetsAt, sentToday, from: 'directory' | 'this computer', line }, parts?, refused? }, and
+ * `unreached: { why }` when the directory could not be asked. `ok` says the preflight ran, never that a publish
+ * would go through.
+ */
+export async function publishBefore(root, { homie, site, log = () => {}, fetchFn } = {}) {
+  const studio = readStudio(root);
+  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const url = site || siteUrl(root, studio);
+  const refused = licenceRefusals(root);
+  const parts = partsForListing(root);
+  const local = publishesSoFar(root);
+  const mine = `this computer has sent ${local.sent} publish${local.sent === 1 ? '' : 'es'} today (UTC)${local.remaining !== null ? `, and the directory said ${local.remaining === 0 ? 'none were' : `${local.remaining} ${local.remaining === 1 ? 'was' : 'were'}`} left after the last one${local.limit !== null ? ` (of ${local.limit} a day)` : ''}` : ''}; a publish from another computer or from the Homie connector is not counted here`;
+  let origin = null;
+  try { origin = url ? new URL(url).origin : null; } catch { origin = null; }
+  let asked = null;
+  if (origin) asked = await request(`${directory}/api/studio/publish?site=${encodeURIComponent(origin)}`, { method: 'GET', headers: { accept: 'application/json' } }, { timeout: 15_000, ...(fetchFn ? { fetchFn } : {}) });
+  const q = asked?.ok ? quotaOf(asked.body, asked.headers) : null;
+  const counted = Boolean(q && q.remaining !== null);
+  const listed = asked?.ok && typeof asked.body?.listed === 'boolean' ? asked.body.listed : null;
+  const why = !origin ? null : asked.ok ? 'it answered without a count' : String(asked.body?.message ?? asked.why ?? 'no answer').split('\n')[0];
+  const line = !origin
+    ? 'Not published. This studio has no live site yet, so there is nothing to list: put it online first (npm run deploy).'
+    : counted
+      ? `Not published. The directory says: this site is ${listed === true ? 'listed' : listed === false ? 'not listed yet' : 'known to it or not, it did not say'}; ${quotaLine(q).replace(/^P/, 'p')}`
+      : `Not published. The directory could not be asked how many publishes are left (${why}), so this is only what this computer knows: ${mine}.`;
+  const lines = [
+    line,
+    ...(refused.length ? [`A publish now would be refused: ${refused.length} asset licence problem${refused.length === 1 ? '' : 's'} (${refused.slice(0, 6).map((p) => `${p.game}/${p.asset}: ${p.problem}`).join('; ')}${refused.length > 6 ? '; …' : ''}). homie-studio assets check <id> says how to fix each.`] : []),
+    ...partsPlanLines(parts, { at: 'publish' }),
+  ];
+  for (const l of lines) log(l);
+  return {
+    ok: true, command: 'publish before', published: false, directory, site: url ?? null, listed,
+    publishes: { remaining: counted ? q.remaining : local.remaining, limit: (counted ? q.limit : null) ?? local.limit, resetsAt: q?.resetsAt ?? null, sentToday: local.sent, from: counted ? 'directory' : 'this computer', line },
+    ...(origin && !counted ? { unreached: { why, ...(asked.status !== undefined ? { status: asked.status } : {}) } } : {}),
+    ...(refused.length ? { refused } : {}),
+    ...(parts.games.length || parts.sharing.length || parts.why ? { parts } : {}),
+    lines,
+  };
+}
+
+export async function publish(root, { homie, site, log = () => {}, fetchFn } = {}) {
+  const studio = readStudio(root);
+  const directory = (homie || studio.homie?.directory || 'https://homie.rocks').replace(/\/+$/, '');
+  const url = site || siteUrl(root, studio);
+  // Licences first: a public game may ship only assets with a licence record that allows it.
+  const refused = licenceRefusals(root);
   if (refused.length) return { ok: false, command: 'publish', refused, why: `not listed: ${refused.length} asset licence problem${refused.length === 1 ? '' : 's'}:\n${refused.map((p) => `  ${p.game}/${p.asset}: ${p.problem}${p.fix ? ` (${p.fix})` : ''}`).join('\n')}\nhomie-studio assets check <id> says the same; fix them, deploy, then publish again.` };
   if (!url) return { ok: false, command: 'publish', why: 'this studio has no live site yet: run `npm run deploy` first' };
   // Parts from other studios in the games about to be listed: their licences and credits, and plainly when two

package/lib/doctor.mjs

@@ -11,8 +11,8 @@
  *                                  homie in its own config, the row says so: that name is the plugin's connector's
  *   Homie's holds      in Codex and Grok Build only: whether the plugin's hooks ran just now (they leave a dated
  *                                  mark, hooks/codex.mjs), so a session where nothing is held says so, and how to turn
- *                                  them on (Codex: trust them in /hooks; Grok Build 1.0.41 runs no plugin's hooks, so
- *                                  there the row is off until a Grok that runs them). The app is the one the AI names
+ *                                  them on (Codex: trust them in /hooks; Grok Build: trust the plugin, which
+ *                                  `grok plugin install … --trust` does). The app is the one the AI names
  *                                  (--client codex|grok) or its environment shows
  *   Cloudflare         to go online: signed in, and the account's email verified (Cloudflare checks that at the
  *                                  first deploy; a deploy that went through proves it)
@@ -271,26 +271,27 @@ export async function setupStatus({
     });
   }
 
-  // Homie's holds, in Codex and Grok Build: Codex runs the plugin's hooks only once the person has trusted them, Grok
-  // Build 1.0.41 was seen to run no plugin's hooks at all, and neither app says so. The hooks leave a dated mark at
-  // every message and tool call; a fresh one means they are on. Off in Grok is Grok's doing, so it is said as that.
+  // Homie's holds, in Codex and Grok Build: each app runs a plugin's hooks only once the person has trusted them
+  // (Codex in /hooks, Grok by trusting the plugin), and neither says so when it skips them. The hooks leave a dated
+  // mark at every message and tool call; a fresh one means they are on. (0.30.2 said Grok runs no plugin's hooks.
+  // It does: the plugin's root manifest named no hooks file, so Grok loaded the Claude Code mod's and found none.)
   if (app === 'codex' || app === 'grok') {
     const name = APPS[app].name;
     const seen = holdsMark(app, { env, now: nowMs });
     const on = Boolean(seen && seen.ageMs <= HOLDS_FRESH_MS);
     rows.push({
-      // Off in Codex is the person's to fix now (trust the hooks); off in Grok is nothing they can fix.
-      id: 'holds', label: 'Homie\'s holds', need: 'recommended', state: on ? 'ok' : app === 'codex' ? 'act' : 'optional', on, app,
+      // Off is the person's to fix now, in either app: trust the hooks.
+      id: 'holds', label: 'Homie\'s holds', need: 'recommended', state: on ? 'ok' : 'act', on, app,
       detail: on ? `on: Homie's hooks ran in ${name} ${ago(seen.ageMs)} ago`
         : seen ? `off: Homie's hooks last ran in ${name} ${ago(seen.ageMs)} ago, and not for this session's calls`
-          : app === 'grok' ? 'off: Grok Build runs no plugin\'s hooks yet (1.0.41), so nothing is held in Grok' : `off: Homie's hooks have not run in ${name} on this computer`,
+          : `off: Homie's hooks have not run in ${name} on this computer`,
       ...(seen ? { seen: { at: new Date(seen.at).toISOString(), event: seen.event } } : {}),
       unlocks: 'a wait for your own "proceed <code>" before a production deploy, an edit to a file the studio protects, a Cloudflare change outside the deploy, a paid call past the budget and a model download; and secrets taken out of what your AI reads',
       fix: on ? null : {
         who: 'person',
         say: app === 'codex'
           ? 'In Codex, open /hooks and trust Homie\'s three hooks: Codex runs no plugin\'s hooks until you do. Then run this again. Until then nothing is held, so your AI asks you before each of those itself.'
-          : 'Nothing to do on your side: Grok Build 1.0.41 runs no plugin\'s hooks (none are registered in its headless and agent sessions, from any plugin; checked 2026-10-04), so Homie\'s holds are off in Grok. Nothing is held and no secret is taken out of what your AI reads, so your AI asks you before each of those itself. This row turns on by itself when a Grok that runs them leaves the hooks\' mark.',
+          : 'Grok runs a plugin\'s hooks only once the plugin is trusted, and only from a Homie plugin new enough to name them for Grok. Install it again with trust (grok plugin install homie-rocks/homie#plugins/homie --trust), start a new session (/hooks lists Homie\'s three), then run this again. Until then nothing is held, so your AI asks you before each of those itself.',
       },
     });
   }

package/lib/mcp-tools.mjs

@@ -31,7 +31,7 @@ import { repoFromUrl, studioRepo } from './repo.mjs';
 import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl } from './studio.mjs';
 import { runningDev } from './dev.mjs';
 import { deployWords } from './deploy-state.mjs';
-import { beforeLine, partsForListing, publishesSoFar } from './directory.mjs';
+import { partsForListing, publishBefore, publishesSoFar } from './directory.mjs';
 import { STUDIO_VERSION } from './version.mjs';
 import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
 import { pinnedVersion } from './upgrade.mjs';
@@ -1085,7 +1085,7 @@ export function toolDefs(ctx, avail = {}) {
     {
       name: 'studio_deploy', title: 'Put the studio online',
       description: 'Put the studio\'s site online on the studio\'s OWN Cloudflare account: one Worker, one D1 database and two Durable Objects, free plan, no payment method. Call it with plan: true first and tell the person in two or three lines what it creates and costs. If Cloudflare is not signed in, cloudflare_login opens it in their browser to approve once. Runs in the background with the build card.',
-      inputSchema: { type: 'object', properties: { plan: { type: 'boolean', description: 'Only say what it will create and what it costs; change nothing' }, ...STUDIO_ARG } },
+      inputSchema: { type: 'object', properties: { plan: { type: 'boolean', description: 'Only say what it will create and what it costs; change nothing' }, ownRoute: { type: 'boolean', description: 'Only after the plan or a deploy warned that another site\'s route on the studio\'s custom domain covers its hostname, and the person agreed: add the studio\'s own exact-host route (the one line the warning gives) and deploy. It never edits or removes any other route' }, ...STUDIO_ARG } },
       annotations: { title: 'Put the studio online', readOnlyHint: false, destructiveHint: false, openWorldHint: true }, _meta: ui(UI.build),
       run: async (a) => {
         const root = ctx.root(a.studio);
@@ -1095,10 +1095,10 @@ export function toolDefs(ctx, avail = {}) {
           if (!r.ended) return stillRunning(r.job, 'The deploy plan');
           if (r.job.code !== 0) return fail(whyOf(r.job));
           const p = r.result;
-          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
+          return ok([`What going online does for ${p.studio}:`, ...p.cloudflare.map((x) => `  ${x.kind}${x.name ? ` ${x.name}` : ''}: ${x.what} [${x.state}]`), `Cost: ${p.cost}`, `Sign-in: ${p.login}`, `The directory stores: ${p.directory?.stores ?? ''}`, ...(p.parts ? partsPlanLines(p.parts) : []), ...(p.zone?.warning ? [`Warning (say this to the person as it is): ${p.zone.warning}`] : p.zone?.why ? [p.zone.why] : []), 'The card on screen shows this plan (nothing is made yet): tell the person its gist in two or three lines, then go on.'].join('\n'), { kind: 'deploy-plan', ...p });
         }
         const studio = readStudio(root);
-        return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy'] }] });
+        return startRun(ctx, root, { kind: 'deploy', game: null, title: `${studio.name}: online`, steps: [{ label: 'deploy', args: ['deploy', ...(a.ownRoute === true ? ['--own-route'] : [])] }] });
       },
     },
     {
@@ -1119,18 +1119,22 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_publish', title: 'List the studio in the Homie directory',
-      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta). The beta also caps how many times a studio may publish in a day: the answer says how many are left when the directory gives the number, and before: true only says what this computer knows (how many it has sent today, what the directory last said was left) without publishing.',
-      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), before: { type: 'boolean', description: 'Only say how many publishes this computer has sent today and what the directory last said was left; publish nothing' }, ...STUDIO_ARG } },
+      description: 'List a deployed studio\'s games, songs and videos in the homie.rocks directory, with their Play links (at most 12 games per studio in the beta). The beta also caps how many times a studio may publish in a day: the answer says how many are left when the directory gives the number, and before: true publishes nothing: it asks the directory how many are left and whether the site is listed (a read), and says so plainly when the directory cannot be reached.',
+      inputSchema: { type: 'object', properties: { site: str('Optional: the live site address (default: the one deploy got)'), before: { type: 'boolean', description: 'Publish nothing: ask the directory (a read) whether this site is listed and how many publishes are left today, and say the parts\' licence lines. When the directory cannot be reached it says so, with what this computer has sent today' }, ...STUDIO_ARG } },
       annotations: { title: 'List in the directory', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
       run: async (a) => {
         const root = ctx.root(a.studio);
-        // What this computer knows of the day's cap, before anything is sent (lib/directory.mjs).
-        const soFar = beforeLine(publishesSoFar(root));
         // The parts in the games a listing shows, in the deploy plan's own lines (licences, credits, and plainly when
         // two cannot be combined): said before the studio is listed, and again with the answer.
         const partsNow = partsForListing(root);
         const partsSaid = partsPlanLines(partsNow, { at: 'publish' });
-        if (a.before === true) return ok([`${soFar.replace(/^Publishing to the directory: /, 'Not published. ')} A publish from another computer or from the Homie connector is not counted here.`, ...partsSaid].join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...(partsSaid.length ? { parts: partsNow } : {}) });
+        // before: true is `publish --before`, the same function the terminal runs (lib/directory.mjs publishBefore):
+        // the directory's read-only count for this site, the parts' lines, and nothing published. Run here, by THIS
+        // toolkit, never handed to the studio's pinned one: a 0.31.0 toolkit reads `publish --before` as `publish`.
+        if (a.before === true) {
+          const b = await publishBefore(root, { site: a.site ? String(a.site) : undefined });
+          return ok(b.lines.join('\n'), { kind: 'publish-count', ...publishesSoFar(root), ...b });
+        }
         const r = await cli(ctx, root, 'publish', ['publish', ...(a.site ? ['--site', String(a.site)] : [])]);
         if (!r.ended) return stillRunning(r.job, 'Listing');
         if (r.job.code !== 0) return fail(`Not listed: ${whyOf(r.job)}`, r.result?.publishes ? { kind: 'publish', ok: false, needs: r.result.needs ?? null, publishes: r.result.publishes } : undefined);