@genex-ai/cli-demo 0.25.0 → 0.27.0

package/README.md

@@ -36,20 +36,20 @@ genex controller <type>    # install a tuned character|car|drone controller →
    browser can't open, it prints the URL to open manually.
 3. **Saves your token** — writes `GENEX_TOKEN` to `~/.genex/env` (per-user;
    reused across projects).
-4. **Creates the draft project** — generates a per-project SSH deploy key
-   (`genex_key`, gitignored automatically), registers its public half with a new
-   repo via `POST /api/projects`, and stores the project metadata (id, slug,
-   `sshUrl`, urls) in `./.genex/project.json`. The game shows up in your
-   dashboard's **My games** immediately.
+4. **Creates the draft project** — `POST /api/projects` provisions a managed
+   Forgejo repo (one per user; no SSH key) and stores the project metadata (id,
+   slug, `cloneUrl`, urls) in `./.genex/project.json`. Source pushes to that repo
+   over HTTPS with a per-push token minted by the API (see below), so it works
+   from any device with a Genex login. The game shows up in your dashboard's
+   **My games** immediately.
 
 `genex link <slug>` is the recovery counterpart of step 4 for a game that
 already exists: run it inside a fresh clone of the game's source repo (or any
-folder that lost its link) and it re-authorizes if needed, reuses or generates
-`genex_key`, registers the public half via `POST /api/projects/:id/deploy-key`
-(keys are added, never replaced), and rewrites `./.genex/project.json` — after
-which `preview`/`publish` update the **same** live game. It never creates a
-project; the dashboard's "Continue building" flow uses it when the original
-folder can't be found.
+folder that lost its link) and it re-authorizes if needed and rewrites
+`./.genex/project.json` — nothing to register, since source pushes authorize per
+push over HTTPS. After it, `preview`/`publish` update the **same** live game. It
+never creates a project; the dashboard's "Continue building" flow uses it when
+the original folder can't be found.
 
 `genex preview` and `genex publish` share a build-aware deploy core: each runs
 `npm run build` (when the project has a build script), then uploads the built

package/dist/index.js

@@ -585,7 +585,7 @@ async function apiFetch(url, init = {}) {
 
 // src/lib/project.ts
 async function createDraftProject(opts) {
-  const { apiUrl, token, deployKey, colyseusUrl, dashboardUrl, log } = opts;
+  const { apiUrl, token, colyseusUrl, dashboardUrl, log } = opts;
   log.step("Creating your project\u2026");
   const names = [opts.name, `${opts.name}-${randomSuffix()}`];
   for (let i = 0; i < names.length; i++) {
@@ -598,7 +598,7 @@ async function createDraftProject(opts) {
           "Content-Type": "application/json",
           Authorization: `Bearer ${token}`
         },
-        body: JSON.stringify({ name, deployKey })
+        body: JSON.stringify(opts.repoUrl ? { name, repoUrl: opts.repoUrl } : { name })
       });
     } catch (err) {
       log.warn(`Couldn't reach the API at ${apiUrl} to create the project.`);
@@ -610,17 +610,13 @@ async function createDraftProject(opts) {
       log.warn("Not authorized to create the project (token rejected).");
       return null;
     }
-    if (res.status === 400) {
-      log.warn("The API rejected the deploy key (must be an OpenSSH public key).");
-      return null;
-    }
     if (!res.ok) {
       log.warn(`Couldn't create the project (HTTP ${res.status}).`);
       return null;
     }
     const data = await res.json().catch(() => null);
     const project = data?.project;
-    if (!project || !data?.sshUrl) {
+    if (!project || !project.cloneUrl) {
       log.warn("Project created, but the API response was unexpected.");
       return null;
     }
@@ -630,7 +626,7 @@ async function createDraftProject(opts) {
     return {
       id: project.id,
       slug: project.slug,
-      sshUrl: data.sshUrl,
+      cloneUrl: project.cloneUrl,
       apiUrl,
       colyseusUrl,
       playUrl: project.playUrl ?? void 0,
@@ -650,57 +646,6 @@ function randomSuffix() {
 // src/lib/ssh.ts
 import fs4 from "fs/promises";
 import path4 from "path";
-import { spawn as spawn2 } from "child_process";
-var KEY_NAME = "genex_key";
-async function generateSshKeypair(dir, log) {
-  const keyPath = path4.join(dir, KEY_NAME);
-  const pubPath = `${keyPath}.pub`;
-  try {
-    const existing = (await fs4.readFile(pubPath, "utf8")).trim();
-    if (existing) {
-      log.dim(`Reusing existing deploy key (${KEY_NAME}).`);
-      return { publicKey: existing };
-    }
-  } catch {
-  }
-  log.step("Generating a deploy key\u2026");
-  const ok = await runSshKeygen(keyPath, log);
-  if (!ok) return null;
-  try {
-    const pub = (await fs4.readFile(pubPath, "utf8")).trim();
-    if (!pub) {
-      log.warn("ssh-keygen produced no public key.");
-      return null;
-    }
-    await fs4.chmod(keyPath, 384).catch(() => {
-    });
-    return { publicKey: pub };
-  } catch (err) {
-    log.warn(`Couldn't read the generated public key: ${String(err)}`);
-    return null;
-  }
-}
-function runSshKeygen(keyPath, log) {
-  return new Promise((resolve) => {
-    let child;
-    try {
-      child = spawn2(
-        "ssh-keygen",
-        ["-t", "ed25519", "-f", keyPath, "-N", "", "-C", "genex-agent"],
-        { stdio: "ignore" }
-      );
-    } catch {
-      log.warn("ssh-keygen not found \u2014 install OpenSSH (ssh-keygen) and re-run.");
-      resolve(false);
-      return;
-    }
-    child.on("error", () => {
-      log.warn("ssh-keygen not found \u2014 install OpenSSH (ssh-keygen) and re-run.");
-      resolve(false);
-    });
-    child.on("close", (code2) => resolve(code2 === 0));
-  });
-}
 async function writeGitignore(dir, log) {
   const file = path4.join(dir, ".gitignore");
   let content = "";
@@ -709,11 +654,11 @@ async function writeGitignore(dir, log) {
   } catch {
   }
   const present = new Set(content.split("\n").map((l) => l.trim()));
-  const toAdd = [KEY_NAME, `${KEY_NAME}.pub`, ".genex/"].filter((e) => !present.has(e));
+  const toAdd = [".genex/", ".env", ".env.*", "!.env.example"].filter((e) => !present.has(e));
   if (toAdd.length === 0) return;
   let next = content;
   if (next.length > 0 && !next.endsWith("\n")) next += "\n";
-  if (!content.trim()) next += "# genex (deploy key + local metadata \u2014 never publish)\n";
+  if (!content.trim()) next += "# genex local metadata + secrets \u2014 never publish\n";
   next += toAdd.join("\n") + "\n";
   await fs4.writeFile(file, next);
   log.dim(`Updated .gitignore (${toAdd.join(", ")}).`);
@@ -726,7 +671,7 @@ import path6 from "path";
 // src/lib/env.ts
 import fs5 from "fs/promises";
 import path5 from "path";
-import { spawn as spawn3 } from "child_process";
+import { spawn as spawn2 } from "child_process";
 async function writeEnvVar(envPath, key, value) {
   let content = "";
   let existed = false;
@@ -766,7 +711,7 @@ async function restrictFilePermissions(filePath) {
   if (!user) return;
   await new Promise((resolve) => {
     try {
-      const child = spawn3(
+      const child = spawn2(
         "icacls",
         [filePath, "/inheritance:r", "/grant:r", `${user}:F`],
         { stdio: "ignore" }
@@ -971,16 +916,7 @@ async function runInit(opts) {
   const { path: tokenPath } = await writeUserToken(token, opts.envPath);
   log.success(`Saved your token to ${c.cyan(tokenPath)} (${ENV_TOKEN_KEY}).`);
   log.plain("");
-  const key = await generateSshKeypair(process.cwd(), log);
   await writeGitignore(process.cwd(), log);
-  if (!key) {
-    log.warn(
-      "Skipping project creation \u2014 no deploy key. Install ssh-keygen (OpenSSH) and re-run `genex init`."
-    );
-    log.plain("");
-    log.success("Workspace ready (no project created yet).");
-    return;
-  }
   const apiUrl = getApiUrl(opts.apiUrl);
   const colyseusUrl = getColyseusUrl(opts.colyseusUrl);
   const projectName = opts.name?.trim() || path8.basename(process.cwd());
@@ -988,16 +924,20 @@ async function runInit(opts) {
     apiUrl,
     token,
     name: projectName,
-    deployKey: key.publicKey,
+    repoUrl: opts.repo?.trim() || void 0,
     colyseusUrl,
     dashboardUrl: authBaseUrl,
     log
   });
-  if (meta) {
-    const { path: metaPath } = await writeProject(meta);
-    log.dim(`  saved ${c.cyan(metaPath)}`);
-    await writeGameConfigFiles(meta, log);
+  if (!meta) {
+    log.plain("");
+    log.warn("Setup finished, but creating your game failed \u2014 fix the error above and re-run `genex init`.");
+    process.exitCode = 1;
+    return;
   }
+  const { path: metaPath } = await writeProject(meta);
+  log.dim(`  saved ${c.cyan(metaPath)}`);
+  await writeGameConfigFiles(meta, log);
   log.plain("");
   log.success("All set. \u{1F680}");
 }
@@ -1041,23 +981,11 @@ async function runLink(opts) {
     process.exitCode = 1;
     return;
   }
-  const key = await generateSshKeypair(process.cwd(), log);
-  if (!key) {
-    log.error("No deploy key \u2014 install ssh-keygen (OpenSSH) and re-run `genex link`.");
-    process.exitCode = 1;
-    return;
-  }
   await writeGitignore(process.cwd(), log);
-  log.step("Registering this folder's deploy key\u2026");
-  const linked = await registerDeployKey(apiUrl, token, project.id, key.publicKey, log);
-  if (!linked) {
-    process.exitCode = 1;
-    return;
-  }
   const meta = {
     id: project.id,
     slug: project.slug,
-    sshUrl: linked.sshUrl,
+    cloneUrl: project.cloneUrl ?? "",
     apiUrl,
     colyseusUrl: getColyseusUrl(opts.colyseusUrl),
     playUrl: project.playUrl ?? void 0,
@@ -1143,40 +1071,9 @@ async function listOwnSlugs(apiUrl, token, log) {
   } catch {
   }
 }
-async function registerDeployKey(apiUrl, token, projectId, deployKey, log) {
-  let res;
-  try {
-    res = await apiFetch(`${apiUrl}/api/projects/${projectId}/deploy-key`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`
-      },
-      body: JSON.stringify({ deployKey })
-    });
-  } catch (err) {
-    log.error(`Couldn't reach the API at ${apiUrl}.`);
-    log.dim(`  ${String(err)}`);
-    return null;
-  }
-  if (res.status === 429) {
-    log.error("Rate limited \u2014 too many link attempts. Try again in a bit.");
-    return null;
-  }
-  if (!res.ok) {
-    log.error(`Couldn't register the deploy key (HTTP ${res.status}).`);
-    return null;
-  }
-  const data = await res.json().catch(() => null);
-  if (!data?.sshUrl) {
-    log.error("Unexpected API response while registering the deploy key.");
-    return null;
-  }
-  return { sshUrl: data.sshUrl };
-}
 
 // src/lib/deploy.ts
-import { spawn as spawn4 } from "child_process";
+import { spawn as spawn3 } from "child_process";
 import crypto3 from "crypto";
 import fs9 from "fs/promises";
 import os2 from "os";
@@ -1185,7 +1082,7 @@ function run(cmd, args, env) {
   return new Promise((resolve) => {
     let child;
     try {
-      child = spawn4(cmd, args, { env: env ? { ...process.env, ...env } : process.env });
+      child = spawn3(cmd, args, { env: env ? { ...process.env, ...env } : process.env });
     } catch {
       resolve({ code: -1, out: "", err: `${cmd} not found` });
       return;
@@ -1199,6 +1096,9 @@ function run(cmd, args, env) {
   });
 }
 var EXCLUDE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".genex", "dist"]);
+function isSecretEnvFile(name) {
+  return name === ".env" || name.startsWith(".env.") && name !== ".env.example";
+}
 async function deployGame(ctx, opts, log) {
   const cwd = process.cwd();
   if (!opts.noBuild && await hasBuildScript(cwd)) {
@@ -1217,10 +1117,6 @@ async function deployGame(ctx, opts, log) {
   const rel = path10.relative(cwd, siteDir) || ".";
   if (siteDir === cwd) await writeGitignore(cwd, log);
   const files = await collectFiles(siteDir);
-  if (files.some((f) => /(^|\/)genex_key(\.pub)?$/.test(f.relPath))) {
-    log.error(`Refusing to deploy: ${KEY_NAME} is in ${rel}. Add it to .gitignore and retry.`);
-    return false;
-  }
   if (files.length === 0) {
     log.warn("Nothing to deploy \u2014 the build produced no files.");
     return false;
@@ -1253,12 +1149,7 @@ async function deployGame(ctx, opts, log) {
     log.error("Couldn't upload your game \u2014 please try again.");
     return false;
   }
-  const keyPath = path10.resolve(cwd, KEY_NAME);
-  if (!await fileExists(keyPath)) {
-    log.error(`No deploy key (${KEY_NAME}) here \u2014 run \`genex init\` in this folder first.`);
-    return false;
-  }
-  if (!await pushSource(cwd, ctx.sshUrl, keyPath, log)) return false;
+  if (!await pushSource(cwd, ctx, log)) return false;
   log.step("Publishing\u2026");
   if (!await callPublish(ctx, commit, opts, log)) return false;
   const index = files.find((f) => f.relPath === "index.html");
@@ -1280,7 +1171,7 @@ async function collectFiles(root) {
       const relPath = prefix ? `${prefix}/${e.name}` : e.name;
       if (e.isDirectory()) {
         if (!EXCLUDE_DIRS.has(e.name)) await walk2(path10.join(dir, e.name), relPath);
-      } else if (e.isFile() && e.name !== KEY_NAME && e.name !== `${KEY_NAME}.pub`) {
+      } else if (e.isFile() && !isSecretEnvFile(e.name)) {
         out.push({ relPath, bytes: await fs9.readFile(path10.join(dir, e.name)) });
       }
     }
@@ -1371,8 +1262,11 @@ async function callPublish(ctx, commit, opts, log) {
   }
   return true;
 }
-async function pushSource(cwd, sshUrl, keyPath, log) {
+async function pushSource(cwd, ctx, log) {
   const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+  const target = await fetchPushUrl(ctx, log);
+  if (!target) return false;
+  const { pushUrl, managed } = target;
   const failed = () => {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
@@ -1389,29 +1283,27 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
     if ((await run("git", ["init", "-q"], base)).code !== 0) return failed();
     await fs9.writeFile(
       path10.join(gitDir, "info", "exclude"),
-      ["node_modules/", "dist/", ".git/", KEY_NAME, `${KEY_NAME}.pub`, ".genex/", ""].join("\n")
+      // .env* are secrets — never publish them; `!` keeps the non-secret template.
+      ["node_modules/", "dist/", ".git/", ".genex/", ".env", ".env.*", "!.env.example", ""].join("\n")
     );
     const env = { ...base, GIT_WORK_TREE: cwd, GIT_INDEX_FILE: path10.join(gitDir, "index-source") };
     await run("git", ["add", "-A"], env);
-    const tracked = await run("git", ["ls-files"], env);
-    if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) {
-      log.error(`Refusing to publish: ${KEY_NAME} is in your project. Add it to .gitignore and retry.`);
-      return false;
-    }
-    const tree = tracked.out.trim() ? (await run("git", ["write-tree"], env)).out.trim() : "";
+    const tree = (await run("git", ["ls-files"], env)).out.trim() ? (await run("git", ["write-tree"], env)).out.trim() : "";
     if (!tree || tree === EMPTY_TREE) {
       log.error("Nothing to publish \u2014 the project has no files.");
       return false;
     }
     const commit = (await run("git", ["commit-tree", tree, "-m", "source"], { ...base, ...ident })).out.trim();
     await run("git", ["update-ref", "refs/heads/main", commit], base);
-    const push = await run("git", ["push", "-q", sshUrl, "+refs/heads/main:main"], {
-      ...base,
-      // Quote the key path: git splits GIT_SSH_COMMAND shell-like, so a folder with a
-      // space would otherwise break the `-i` argument.
-      GIT_SSH_COMMAND: `ssh -i "${keyPath}" -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
-    });
-    return push.code === 0 ? true : failed();
+    const push = await run("git", ["push", "-q", pushUrl, "+refs/heads/main:main"], base);
+    if (push.code === 0) return true;
+    if (!managed) {
+      log.error(
+        "Couldn't push to your repo. Check that you have push access (SSH key or git credentials) and that the repo exists."
+      );
+      return false;
+    }
+    return failed();
   } catch {
     return failed();
   } finally {
@@ -1419,17 +1311,35 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
     });
   }
 }
-async function isDir2(p) {
+async function fetchPushUrl(ctx, log) {
+  let res;
   try {
-    return (await fs9.stat(p)).isDirectory();
-  } catch {
-    return false;
+    res = await apiFetch(`${ctx.apiUrl}/api/projects/${ctx.projectId}/push-token`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${ctx.token}` }
+    });
+  } catch (err) {
+    log.error(`Couldn't reach the API to authorize the source push: ${String(err)}`);
+    return null;
   }
+  if (res.status === 401) {
+    log.error("Not authorized \u2014 your token may have expired. Re-run `genex init`.");
+    return null;
+  }
+  if (!res.ok) {
+    log.error(`Couldn't authorize the source push (HTTP ${res.status}).`);
+    return null;
+  }
+  const data = await res.json().catch(() => null);
+  if (!data?.pushUrl) {
+    log.error("The API didn't return a push URL.");
+    return null;
+  }
+  return { pushUrl: data.pushUrl, managed: data.managed !== false };
 }
-async function fileExists(p) {
+async function isDir2(p) {
   try {
-    await fs9.access(p);
-    return true;
+    return (await fs9.stat(p)).isDirectory();
   } catch {
     return false;
   }
@@ -1571,7 +1481,7 @@ async function runPublish(opts) {
   advisoryNudges(log, detections);
   if (!opts.noPush) {
     const ok = await deployGame(
-      { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
+      { projectId: meta.id, apiUrl, token },
       {
         noBuild: opts.noBuild,
         matchmaking: detections.matchmaking,
@@ -1643,7 +1553,7 @@ async function runPreview(opts) {
   advisoryNudges(log, detections);
   const apiUrl = getApiUrl(meta.apiUrl);
   const ok = await deployGame(
-    { projectId: meta.id, sshUrl: meta.sshUrl, apiUrl, token },
+    { projectId: meta.id, apiUrl, token },
     // Detections reach the server on every preview too: matchmaking so a draft's
     // declared preset doesn't silently run the default (null clears a removed
     // config), embedSdkVersion/multiplayer so the dashboard's Publish button can
@@ -2158,6 +2068,8 @@ ${c.bold("Options for the generators (`model` `skybox` `sfx` `texture`)")}
 ${c.bold("Options for `init`")}
   <name>               Project name (positional; default: current directory name).
   --name <name>        Same as the positional name.
+  --repo <url>         Host the source in your own git repo (https/ssh) instead of a managed one;
+                       preview/publish push there with your git credentials.
   --agents <list>      Agents to install skills for (claude,codex,cursor; default: auto-detect).
   --dir <path>         Single destination workspace (overrides --agents).
   --env <path>         Token env file (default: ~/.genex/env).
@@ -2239,6 +2151,7 @@ function parseArgs(argv) {
     "--colyseus-url",
     "--agents",
     "--name",
+    "--repo",
     "--title",
     "--description",
     "--categories",
@@ -2338,6 +2251,9 @@ function applyValueFlag(options, flag, value) {
     case "--name":
       options.name = value;
       break;
+    case "--repo":
+      options.repo = value;
+      break;
     case "--title":
       options.title = value;
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {

package/templates/skills/genex-getting-started/SKILL.md

@@ -92,8 +92,8 @@ refreshes the genex-owned ones.
 
 ## Reconnecting an existing game (`genex link`)
 
-Each game's connection to its live page is folder-local (`.genex/project.json`
-+ the `genex_key` deploy key). If that folder is gone — deleted, or the game
+Each game's connection to its live page is folder-local (`.genex/project.json`).
+If that folder is gone — deleted, or the game
 was built on another machine — **don't run `init` to "recover" it**: that
 creates a brand-new game at a new URL. Instead, clone the game's source repo
 and re-link the clone to the same live game:
@@ -104,8 +104,9 @@ npm install
 npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
 ```
 
-`link` never creates a project: it signs in if needed (the browser opens once),
-registers a fresh deploy key for this folder, and rewrites the local link.
+`link` never creates a project: it signs in if needed (the browser opens once)
+and rewrites the local link (source pushes authorize over HTTPS, so there's no
+key to set up — it works from any machine).
 After it, `npx genex preview` / `npx genex publish` update the **same live
 game** — plays, likes, and comments stay. It also fixes a folder whose
 authorization went stale ("Not authorized" from `preview`/`publish`).

package/templates/skills/genex-threejs-multiplayer/SKILL.md

@@ -34,9 +34,12 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer
+npm i @genex-ai/multiplayer@^0.8.0
 ```
 
+> Pin `@^0.8.0` (not a bare `npm i`): `inputs`/`onHostTick`, auto-reconnect, and the `reconnecting`
+> events this skill relies on landed in 0.8. An older resolve would throw `room.onHostTick is not a function` at runtime.
+
 This skill targets `@genex-ai/multiplayer` **≥ 0.8.0** (`objects`/`host` since 0.4; `matchmake()` since 0.5; presets + `score()`/`finish()` since 0.6; `createPrivate()`/`joinPrivate()` since 0.7; matchmake auto-retry + `retry()` since 0.7.1; auto-reconnect + `inputs`/`onHostTick` since 0.8).
 
 ## Trust model (say it plainly in your game's copy)
@@ -148,6 +151,7 @@ room.on("reconnecting", ({ attempt }) => showOverlay(`Reconnecting… (${attempt
 room.on("reconnected", () => hideOverlay());
 room.on("disconnect", (code) => {
   // Terminal: server restart, revoked session, or the link never came back.
+  if (code === 4409) flushSaves(); // replaced by this player's OTHER tab/device — flush now
   // To play again, read a FRESH token and connect() anew — never reuse the old auth object.
   showMenu("Connection lost");
 });
@@ -160,7 +164,9 @@ glide on; don't tear the scene down. A deliberate `room.leave()` never auto-reco
 **One seat per player (enforced server-side):** joining the same game again — a second tab,
 another device, or a page reload — instantly evicts the previous session (it gets
 `disconnect`, code 4409). You never need to handle "the same player twice" and a reload
-never leaves a ghost avatar behind.
+never leaves a ghost avatar behind. If the evicted tab was the host and holds unsaved world
+state, flush it in the `disconnect` handler (code 4409, above): that tab is still alive, so an
+async `saveWorldState` completes — otherwise a debounced save in flight is lost.
 
 ## Which channel for which data
 
@@ -187,7 +193,10 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
   `{ id, name, state, stateRaw }`: `state` is auto-smoothed (remotes) / live (you); `stateRaw` is
   the raw latest (hit-tests, discrete values).
 - `room.objects` — shared objects nobody owns until claimed (a ball, an NPC):
-  - `claim(id)` — take ownership (last claim wins; call on kick/contact).
+  - `claim(id)` — take ownership (last claim wins; call on kick/contact). Claiming is optimistic:
+    you own it locally the instant you call it, but if another player claimed the same tick the
+    server's last-claim-wins verdict can revoke you — a `set()` you sent before losing the race is
+    dropped. For contested objects, keep publishing while `isMine` stays true, not just once.
   - `set(id, state)` — publish it (only lands while you own it; full flat object each call).
   - `get(id)` → `{ id, owner, isMine, state, stateRaw }` or `undefined`. `state` is auto-smoothed
     (or live if `isMine`); `stateRaw` is the raw latest.
@@ -212,6 +221,24 @@ fights (many writers). A ball on `objects` glides and has one owner. That's the
 - `room.onHostTick(hz, cb)` — run a fixed simulation tick only while you are the host
   (auto-starts/stops across host migration). Returns a disposer.
 
+## Your message budget (every publish is one relay message)
+
+Every `me.set`, `objects.set`, `objects.claim`, `send`, and `inputs.send` costs **one relay
+message**, and the relay caps each connection at **~120 messages/second sustained** (drops
+above that — you'll see a console warning "the relay dropped N of your messages"). The
+budget math that matters:
+
+- Your own state (`me.set`) at 15 Hz + ONE driven/owned moving object at 15 Hz = 30/s. Fine.
+- The pattern that blows the budget: **republishing IDLE objects every tick.** A host that
+  owns several parked vehicles/props must NOT `objects.set` each of them at full tick rate —
+  publish an object **when it changed**, plus a low-rate keepalive (~1–2 Hz) so late joiners
+  converge. Unchanged pose ⇒ no message.
+- If you see the drop warning, count your sends-per-tick: streams × tick-rate must stay well
+  under 120/s with headroom for claims and events.
+- Over budget, the relay spreads the loss across ALL your streams (everything gets choppy at
+  once) rather than freezing one — so a single stuttering object is your cue to check the whole
+  budget, not just that object. The warning is the signal; don't design at the edge of the cap.
+
 ## The loop you must build (input → local → tick → render)
 
 1. **Input mutates a local object only** (`me.x += …`). Never network on keypress.
@@ -259,7 +286,10 @@ details are in [references/realtime-patterns.md](references/realtime-patterns.md
 ## Host authority (scores, rounds, enemies)
 
 One client is the `host`. Let *only* the host write agreed state and simulate shared enemies, so
-there's a single source of truth:
+there's a single source of truth. **But: a host is only the authority for objects it OWNS.**
+If another player owns/drives an object (their claim landed), the host renders it from the
+stream like everyone else — a host branch that pins "its" objects to a local pose without
+checking `owner`/`isMine` shows every other player's driving as a frozen object:
 
 ```ts
 if (room.isHost) room.shared.set("round", nextRound);   // only the host advances the round
@@ -364,10 +394,12 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer` (≥ 0.8.0 — auto-reconnect, `inputs`, `onHostTick`); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.8.0` (auto-reconnect, `inputs`, `onHostTick` — pin `^0.8.0`, a bare install can resolve older); config wired into the build.
 - [ ] `reconnecting`/`reconnected`/`disconnect` render an overlay (don't tear the scene down).
 - [ ] Numbers rounded (~2 decimals) before `me.set`/`objects.set`.
 - [ ] Contested (sustained-contact) objects use the host-physics pattern, not claim-on-touch.
+- [ ] Idle/unchanged objects republish at ≤2 Hz keepalive, never every tick (message budget).
+- [ ] Host renders objects OWNED BY OTHERS from the stream (authority follows ownership).
 - [ ] `connect()` runs AFTER `await waitForPlayer()` (never `waitForAuth()` — guests would
       hang) and passes `auth: getColyseusAuth()!` (the relay rejects tokenless joins —
       see `genex-threejs-embed-auth`).

package/templates/skills/genex-threejs-multiplayer/references/host-physics.md

@@ -81,29 +81,53 @@ The `genex controller` controllers are **local-only physics** — each player si
 OWN rig (self-authoritative, zero latency). Networking them is publish-and-playback, never
 remote simulation:
 
+The vendored controllers expose their pose as `currPos` (a `THREE.Vector3`) and `currQuat` (a
+`THREE.Quaternion`) — **not** `.position` / `.quaternion` — plus boolean state getters. Character
+animation is driven by **five booleans**, not a single enum; publish the booleans and let remotes
+reconstruct the animation. There is **no** `rig.animState`, no `remoteAnimator.play(...)`, and no
+vehicle `wheelSpinPhase` getter.
+
 ```ts
-// You: after your controller's update, on the fixed tick (~15Hz)
+// You: after your controller's update(), on the fixed tick (~15Hz).
+const p = character.currPos;   // THREE.Vector3   (Vehicle/Drone: same getters)
+const q = character.currQuat;  // THREE.Quaternion
 room.me.set({
-  x: r2(rig.position.x), y: r2(rig.position.y), z: r2(rig.position.z),
-  q: rig.quaternion.toArray().map(r2),      // quaternion — never a scalar yaw
-  anim: rig.animState,                       // discrete → remotes read via stateRaw
-  // vehicle extras: steer: r2(steerAngle), wheel: r2(wheelSpinPhase)
+  x: r2(p.x), y: r2(p.y), z: r2(p.z),
+  q: [r2(q.x), r2(q.y), r2(q.z), r2(q.w)],   // quaternion array — never a scalar yaw
+  // character animation = 5 booleans (the CharacterController exposes each as a getter):
+  g: character.isOnGround, f: character.isFalling, m: character.isMoving,
+  r: character.runActive,  j: character.jumpActive,
 });
 
-// Remote players: drive a VISUAL-ONLY rig from smoothed state — no Rapier body, no
-// controller instance for remotes. Wheels/limbs animate from the published params.
-const p = room.players.get(id)!;
-remoteMesh.position.set(p.state.x, p.state.y, p.state.z);
-remoteMesh.quaternion.fromArray(p.state.q);
-remoteAnimator.play(p.stateRaw.anim);        // discrete values from stateRaw
+// Remote players: a VISUAL-ONLY avatar — NO Rapier body, NO controller instance for remotes.
+// Position/rotation from smoothed state; animation from the synced flags via the avatar's own
+// update(flags, dt). The character-controller skill's animations reference owns the flag set.
+const pl = room.players.get(id)!;
+remoteAvatar.group.position.set(pl.state.x, pl.state.y, pl.state.z);
+remoteAvatar.group.quaternion.fromArray(pl.state.q);
+const raw = pl.stateRaw; // discrete flags: read RAW, never smoothed
+remoteAvatar.update(
+  { isOnGround: !!raw.g, isFalling: !!raw.f, isMoving: !!raw.m, runActive: !!raw.r, jumpActive: !!raw.j },
+  dt,
+);
 ```
 
 What to publish per controller:
 
-- **character**: `x/y/z`, `q`, `anim` (state-machine id), optionally `speed` for blend trees.
-- **vehicle**: body `x/y/z` + `q`, `steer` angle, a `wheel` spin phase (remotes spin wheels
-  procedurally — never sync per-wheel transforms).
-- **drone**: `x/y/z`, `q`, rotor throttle if the visual needs it.
+- **character**: `currPos` → `x/y/z`, `currQuat` → `q`, and the five booleans above
+  (`isOnGround`/`isFalling`/`isMoving`/`runActive`/`jumpActive`). Remotes rebuild the animation
+  with `avatar.update(flags, dt)` — see the `genex-threejs-character-controller` animations
+  reference for the flag set (single source of truth; don't invent a `play(anim)` call).
+- **vehicle**: body `currPos` → `x/y/z` + `currQuat` → `q`. For visible steering, publish the
+  front wheel's `car.wheels.get(frontWheelId)?.steerAngle`; spin the wheels on remotes
+  procedurally from the body's speed (position delta) — there is no spin-phase getter, and you
+  never sync per-wheel transforms.
+- **drone**: `currPos` → `x/y/z`, `currQuat` → `q`, and `drone.hoverThrottle` if the rotor visual
+  needs it. Remote rotor spin is procedural, like vehicle wheels.
+
+> Remote **visuals** for vehicle wheels / drone rotors are author-built (a spinning mesh you drive
+> from synced speed/throttle) — the controllers build those internally from a live Rapier body,
+> which remotes don't have. Only the body pose + the flags/params above come over the wire.
 
 Player-vs-player physical contact (bumping cars) stays approximate at this tier — each
 client is authoritative over itself, so contacts are cosmetic. If a game's core loop IS