@genex-ai/cli-demo 0.43.0 → 0.45.0-dev.61

package/README.md

@@ -69,9 +69,12 @@ built.
   **published** so it appears in the public gallery. The deploy and the gallery
   flag are independent; `--no-push` flips the flag only.
 
-Defaults: API `https://demo-api.glotech.world`, auth site
-`https://demo-web.glotech.world` — override with `--api-url` / `--auth-url` (or
-`GENEX_API_URL` / `GENEX_AUTH_URL`) for local dev.
+Defaults: API `https://api.genex.games`, auth site
+`https://genex.games` — override with `--api-url` / `--auth-url` (or
+`GENEX_API_URL` / `GENEX_AUTH_URL`) for local dev. Those are the `@latest`
+(prod) channel's defaults; the `@dev` dist-tag ships the same CLI built for the
+dev stand (`api-dev` / `dev` / `relay-dev` `.genex.games`) — the channel is
+baked at build time via `GENEX_CLI_CHANNEL` (see `src/config.ts`).
 
 ## Generating assets
 
@@ -135,7 +138,7 @@ Options
   --agents <list>      Agents to install for: claude,codex,cursor (default: auto-detect)
   --dir <path>         Single destination workspace (overrides --agents)
   --env <path>         Token env file (default: ~/.genex/env)
-  --auth-url <url>     Override the auth site (default: https://demo-web.glotech.world)
+  --auth-url <url>     Override the auth site (default: https://genex.games)
   --no-auth            Only scaffold templates; skip authorization
   --force              Overwrite existing files (default: never overwrite)
   --timeout <seconds>  How long to wait for the auth redirect (default: 300)
@@ -166,7 +169,7 @@ genex init --auth-url http://localhost:3000
 
 The auth site URL is a single configurable value:
 
-- **Default:** `https://demo-web.glotech.world` (the `DEFAULT_AUTH_URL` constant
+- **Default:** `https://genex.games` (the `DEFAULT_AUTH_URL` constant
   in [`src/config.ts`](src/config.ts)).
 - **Override at runtime:** set `GENEX_AUTH_URL`, or pass `--auth-url`.
 
@@ -174,6 +177,11 @@ The auth site URL is a single configurable value:
 GENEX_AUTH_URL=https://staging.genex.dev genex init
 ```
 
+The token env file path is configurable the same way: `--env <path>` per
+command, or `GENEX_ENV_FILE=<path>` for a whole session (an explicit `--env`
+still wins). Useful for running as a second account — a curator or a test
+runner — without touching the default `~/.genex/env`.
+
 To control which browser is launched, set `GENEX_BROWSER` (or the conventional
 `BROWSER`) to an opener command. It's parsed like a shell command, so arguments
 work and paths containing spaces should be quoted:

package/dist/index.js

@@ -8,9 +8,10 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
-var DEFAULT_AUTH_URL = "https://demo-web.glotech.world";
-var DEFAULT_API_URL = "https://demo-api.glotech.world";
-var DEFAULT_COLYSEUS_URL = "wss://demo-colyseus.glotech.world";
+var RAW_CHANNEL = "dev";
+var CLI_CHANNEL = RAW_CHANNEL === "dev" ? "dev" : "latest";
+var DEFAULT_AUTH_URL = CLI_CHANNEL === "dev" ? "https://dev.genex.games" : "https://genex.games";
+var DEFAULT_API_URL = CLI_CHANNEL === "dev" ? "https://api-dev.genex.games" : "https://api.genex.games";
 var DEFAULT_ANIMS_BASE = "https://cdn.genex.technology/anims/ual1/v1/";
 var ANIMS_BASE_ENV = "GENEX_ANIMS_BASE";
 function getAnimsBase(override) {
@@ -23,7 +24,7 @@ function getAnimsCacheDir() {
 var ENV_TOKEN_KEY = "GENEX_TOKEN";
 var AUTH_URL_ENV = "GENEX_AUTH_URL";
 var API_URL_ENV = "GENEX_API_URL";
-var COLYSEUS_URL_ENV = "GENEX_COLYSEUS_URL";
+var ENV_FILE_ENV = "GENEX_ENV_FILE";
 function getAuthUrl(override) {
   const raw = override || process.env[AUTH_URL_ENV] || DEFAULT_AUTH_URL;
   return raw.replace(/\/+$/, "");
@@ -32,15 +33,13 @@ function getApiUrl(override) {
   const raw = override || process.env[API_URL_ENV] || DEFAULT_API_URL;
   return raw.replace(/\/+$/, "");
 }
-function getColyseusUrl(override) {
-  const raw = override || process.env[COLYSEUS_URL_ENV] || DEFAULT_COLYSEUS_URL;
-  return raw.replace(/\/+$/, "");
-}
 function getGenexDir() {
   return path.join(os.homedir(), ".genex");
 }
 function getGenexEnvPath(override) {
   if (override) return path.resolve(override);
+  const fromEnv = process.env[ENV_FILE_ENV];
+  if (fromEnv) return path.resolve(fromEnv);
   return path.join(getGenexDir(), "env");
 }
 function getTemplatesDir() {
@@ -162,7 +161,7 @@ if (sentryEnabled) {
     // release aligns with the AG-757 `x-genex-cli-version` telemetry stream so
     // the two correlate; environment is prod unless pointed at a non-default API.
     release: `@genex-ai/cli-demo@${getCliVersion()}`,
-    environment: getApiUrl() === DEFAULT_API_URL ? "production" : "development",
+    environment: CLI_CHANNEL === "dev" ? "development" : getApiUrl() === DEFAULT_API_URL ? "production" : "development",
     // A short-lived CLI has no meaningful tracing workload — errors only.
     tracesSampleRate: 0,
     // No IP / user auto-collection (opposite of the server apps' `userInfo: true`).
@@ -385,6 +384,7 @@ async function reportUpdateNudges(check, log, cwd = process.cwd()) {
     const lines = [];
     let whatsNew = null;
     for (const pkg of PUBLISHED_PACKAGES) {
+      if (pkg.name === "@genex-ai/cli-demo" && CLI_CHANNEL === "dev") continue;
       const latest = cache.latest[pkg.name];
       if (!latest) continue;
       const installed = pkg.name === "@genex-ai/cli-demo" ? getCliVersion() : await installedPackageVersion(cwd, pkg.name);
@@ -670,7 +670,7 @@ var c = {
 // src/lib/api.ts
 var CLI_VERSION_HEADER = "x-genex-cli-version";
 function formatUpdateRequired(body) {
-  const action = body.action ?? "npm i -D @genex-ai/cli-demo@latest";
+  const action = body.action ?? `npm i -D @genex-ai/cli-demo@${CLI_CHANNEL}`;
   const message = body.message ?? `Genex CLI ${body.clientVersion ?? getCliVersion()} is below the minimum supported version${body.minVersion ? ` ${body.minVersion}` : ""}.`;
   return [`${c.red("\u2717")} ${message}`, `  Update now \u2014 run: ${action}  (then re-run this command)`];
 }
@@ -766,7 +766,7 @@ async function fetchSignedInEmail(apiUrl, token) {
 // src/lib/project.ts
 import crypto2 from "crypto";
 async function createDraftProject(opts) {
-  const { apiUrl, token, colyseusUrl, dashboardUrl, log } = opts;
+  const { apiUrl, token, dashboardUrl, log } = opts;
   log.step("Creating your project\u2026");
   const names = [opts.name, `${opts.name}-${randomSuffix()}`];
   for (let i = 0; i < names.length; i++) {
@@ -817,7 +817,6 @@ async function createDraftProject(opts) {
       slug: project.slug,
       cloneUrl: project.cloneUrl,
       apiUrl,
-      colyseusUrl,
       playUrl: project.playUrl ?? void 0,
       status: "draft",
       // Derived client-side from the auth/web origin the CLI just authorized
@@ -946,7 +945,7 @@ async function writeUserToken(token, envPath) {
 async function readUserToken(envPath) {
   const fromGenex = await readTokenFromFile(getGenexEnvPath(envPath));
   if (fromGenex) return fromGenex;
-  if (!envPath) {
+  if (!envPath && !process.env[ENV_FILE_ENV]) {
     return readTokenFromFile(path6.join(process.cwd(), ".env"));
   }
   return null;
@@ -1000,7 +999,6 @@ function renderGenexConfig() {
 export const GENEX = {
   slug: import.meta.env.VITE_GENEX_SLUG as string,
   apiUrl: (import.meta.env.VITE_GENEX_API_URL as string | undefined) ?? "${DEFAULT_API_URL}",
-  colyseusUrl: (import.meta.env.VITE_GENEX_COLYSEUS_URL as string | undefined) ?? "${DEFAULT_COLYSEUS_URL}",
   dashboardOrigins: ((import.meta.env.VITE_GENEX_DASHBOARD_ORIGINS as string | undefined) ?? "${DEFAULT_DASHBOARD_ORIGIN}").split(","),
 } as const;
 `;
@@ -1014,9 +1012,6 @@ function renderDevOverrides(meta) {
   const dashboardOrigins = meta.dashboardOrigins?.join(",") ?? DEFAULT_DASHBOARD_ORIGIN;
   const overrides = [];
   if (meta.apiUrl !== DEFAULT_API_URL) overrides.push(`VITE_GENEX_API_URL=${meta.apiUrl}`);
-  if (meta.colyseusUrl !== DEFAULT_COLYSEUS_URL) {
-    overrides.push(`VITE_GENEX_COLYSEUS_URL=${meta.colyseusUrl}`);
-  }
   if (dashboardOrigins !== DEFAULT_DASHBOARD_ORIGIN) {
     overrides.push(`VITE_GENEX_DASHBOARD_ORIGINS=${dashboardOrigins}`);
   }
@@ -1121,7 +1116,6 @@ async function runInit(opts) {
   }
   await writeGitignore(process.cwd(), log);
   const apiUrl = getApiUrl(opts.apiUrl);
-  const colyseusUrl = getColyseusUrl(opts.colyseusUrl);
   const signedInEmail = await fetchSignedInEmail(apiUrl, token);
   if (signedInEmail) log.plain(`  signed in as ${c.cyan(signedInEmail)}`);
   const projectName = opts.name?.trim() || path8.basename(process.cwd());
@@ -1132,7 +1126,6 @@ async function runInit(opts) {
     repoUrl: opts.repo?.trim() || void 0,
     private: opts.private,
     remixedFromSlug: opts.remixedFrom?.trim() || void 0,
-    colyseusUrl,
     dashboardUrl: authBaseUrl,
     log
   });
@@ -1196,7 +1189,6 @@ async function runLink(opts) {
     slug: project.slug,
     cloneUrl: project.cloneUrl ?? "",
     apiUrl,
-    colyseusUrl: getColyseusUrl(opts.colyseusUrl),
     playUrl: project.playUrl ?? void 0,
     status: project.status ?? "draft",
     dashboardOrigins: [new URL(authBaseUrl).origin]
@@ -2743,7 +2735,6 @@ ${c.bold("Options for `init`")}
   --env <path>         Token env file (default: ~/.genex/env).
   --auth-url <url>     Override the auth site (default: ${DEFAULT_AUTH_URL}).
   --api-url <url>      Override the API base URL (default: ${DEFAULT_API_URL}).
-  --colyseus-url <url> Override the multiplayer URL (stored in project metadata).
   --no-auth            Only scaffold templates; skip authorization.
   --force              Overwrite existing files (default: never overwrite).
   --timeout <seconds>  How long to wait for the auth redirect (default: 300).
@@ -2754,7 +2745,6 @@ ${c.bold("Options for `link`")}
   --env <path>         Token env file (default: ~/.genex/env).
   --auth-url <url>     Override the auth site (used only if sign-in is needed).
   --api-url <url>      Override the API base URL.
-  --colyseus-url <url> Override the multiplayer URL (stored in project metadata).
   --timeout <seconds>  How long to wait for the auth redirect (default: 300).
 
 ${c.bold("Options for `preview` / `publish`")}
@@ -2788,7 +2778,6 @@ ${c.bold("Global")}
 ${c.bold("Environment")}
   GENEX_AUTH_URL       Overrides the default auth site URL.
   GENEX_API_URL        Overrides the default API base URL.
-  GENEX_COLYSEUS_URL   Overrides the default multiplayer URL.
   GENEX_BROWSER        Command used to open the browser (falls back to BROWSER).
   GENEX_TELEMETRY      Set to 0 to disable anonymous crash reporting (Sentry).
   DO_NOT_TRACK         Standard opt-out; any value disables crash reporting.
@@ -2826,7 +2815,6 @@ function parseArgs(argv) {
     "--env",
     "--auth-url",
     "--api-url",
-    "--colyseus-url",
     "--agents",
     "--name",
     "--repo",
@@ -2941,9 +2929,6 @@ function applyValueFlag(options, flag, value) {
     case "--api-url":
       options.apiUrl = value;
       break;
-    case "--colyseus-url":
-      options.colyseusUrl = value;
-      break;
     case "--agents":
       options.agents = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.43.0",
+  "version": "0.45.0-dev.61",
   "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-ai-image/SKILL.md

@@ -172,7 +172,7 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
 - **Decal is an opaque rectangle** — the image has no alpha. Regenerate with

package/templates/skills/genex-ai-model/SKILL.md

@@ -58,8 +58,10 @@ side — reads as broken at a glance.
 - **Verify it, don't assume it.** Orientation **is** visible in a still — in your
   self-check screenshot confirm the hero faces its travel direction AND that NPCs driven
   by chase/aim code face their target (an enemy rotated 90° from its victim is this
-  pipeline's most common visible bug). If you can't capture real gameplay (a draft's
-  sign-in gate is up), say so plainly instead of skipping the check silently.
+  pipeline's most common visible bug). On an unpublished draft, capture real gameplay in
+  local test mode (`?genex_local_test=1` on the dev server — the embed-auth skill's
+  "Self-testing a draft" section); if you still can't capture gameplay, say so plainly
+  instead of skipping the check silently.
 
 ## Load it into the scene
 
@@ -105,7 +107,7 @@ scene is a ghost: players and objects pass straight through it.
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this model generation. Tell the user the facts the CLI printed: their balance, this
   generation's cost, and when their credits refill. Then offer to continue the build

package/templates/skills/genex-ai-sfx/SKILL.md

@@ -72,7 +72,7 @@ Reuse one loaded `buffer` across many plays; create a fresh `Audio`/`PositionalA
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this sound generation. Tell the user the facts the CLI printed: their balance, this
   generation's cost, and when their credits refill. Then offer to continue the build

package/templates/skills/genex-ai-skybox/SKILL.md

@@ -76,7 +76,7 @@ scene.background = texture; // keep the raw texture for the visible sky
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this skybox generation. Tell the user the facts the CLI printed: their balance, this
   generation's cost, and when their credits refill. Then offer to continue the build

package/templates/skills/genex-ai-texture/SKILL.md

@@ -81,7 +81,7 @@ scene.add(ground);
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Out of credits" (`insufficient_credits`)** — the account has no credits left for
   this texture generation. Tell the user the facts the CLI printed: their balance,
   this generation's cost, and when their credits refill. Then offer to continue the

package/templates/skills/genex-ai-video/SKILL.md

@@ -138,7 +138,7 @@ See `$genex-threejs-multiplayer` for the `shared` channel rules and the room API
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@dev init` first (it writes your `GENEX_TOKEN`).
 - **"Prompt rejected"** — the provider's content-safety filter blocked the prompt.
   This is non-retryable; retrying the same wording fails again. Rewrite the prompt.
 - **Nothing plays / black surface** — the first `video.play()` must run inside a user

package/templates/skills/genex-explore/SKILL.md

@@ -43,7 +43,7 @@ Add `--json` for machine-readable output.
 **As a NEW game (start from the whole project):**
 
 1. `git clone <clone URL from the output> <name>` — pick a short one-word name.
-2. `cd <name>`, then `npx @genex-ai/cli-demo@latest init <name>` — never use
+2. `cd <name>`, then `npx @genex-ai/cli-demo@dev init <name>` — never use
    `--force`. This creates your own project; the original is untouched.
 3. `npm install`, keep `base: './'` in `vite.config`, then build your changes
    and ship with `npx genex preview`.

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

@@ -122,7 +122,7 @@ and re-link the clone to the same live game:
 ```bash
 git clone <the game's repo url> my-game && cd my-game
 npm install
-npx @genex-ai/cli-demo@latest link <slug>   # slug = the name in the play URL
+npx @genex-ai/cli-demo@dev link <slug>   # slug = the name in the play URL
 ```
 
 `link` never creates a project: it signs in if needed (the browser opens once)
@@ -145,7 +145,7 @@ Safe to run any time — genex-owned skills are refreshed to the latest version,
 and your own files are never touched:
 
 ```bash
-npx @genex-ai/cli-demo@latest init
+npx @genex-ai/cli-demo@dev init
 ```
 
 Use `--force` only if you intentionally want your own existing files overwritten

package/templates/skills/genex-threejs-embed-auth/SKILL.md

@@ -23,6 +23,9 @@ for both, using the SDK's token. The SDK handles every context with one
   zero clicks; everyone else arrives as a guest with a small dismissible
   "sign in to save progress" popover (rendered by the SDK — don't build your
   own). Nobody ever hits a login wall on a published game.
+- **Local test mode (your own self-testing):** `?genex_local_test=1` on the
+  local dev server boots a credential-less local session — see "Self-testing
+  a draft" below.
 
 While identity is resolving (or blocked) the SDK shows its own full-screen
 overlay over the game, so never build a separate "connecting" screen for auth.
@@ -102,7 +105,7 @@ boot-path gate; `waitForAuth()` guards saves only.
 - `getAuthState()` → `"pending" | "authenticated" | "guest" | "blocked"` —
   synchronous.
 - `getUser()` → `{ id, name, image? } | null` — non-null once authenticated OR
-  guest. Guest ids are prefixed `guest:`.
+  guest. Guest ids are prefixed `guest:` (local test mode: `local:test`).
 - `getEmbedToken()` → `string | undefined` — the raw token, for the RARE
   advanced case of calling the Genex API by hand. The state/leaderboard
   helpers below attach it automatically — prefer them; never hand-roll fetch
@@ -138,7 +141,8 @@ session is blocked):
 - `getLeaderboard({ board?, limit?, order? }?)` → `Promise<{ items, me }>` —
   top entries (verified display names — never trust client-side name input
   for this) + the signed-in player's own `{ rank, score }`. Works for guests
-  too (`me: null`). `limit` caps at 100 server-side.
+  too (`me: null`). `limit` caps at 100 server-side. Local test mode resolves
+  `{ items: [], me: null }` locally.
 
 Server write limits (per player, per minute): **60 player-saves, 120
 world-saves, 30 score submits**. A debounced ~1/sec checkpoint never gets near
@@ -256,34 +260,63 @@ SDK's own top-right "sign in to save progress" popover. The return trip
 carries a one-time pass (or an inert guest marker) in the URL that the SDK
 consumes and removes immediately. Unpublished drafts are the exception:
 strangers can't play them, so a draft link shows the SDK's sign-in gate
-instead. Don't code around any of this: no `?`/`#` URL params of yours will
-be affected, and `isEmbedded()` / the return-trip handling are internal SDK
-concerns.
+instead (for self-testing, see local test mode below). Don't code around any
+of this: no `?`/`#` URL params of yours will be affected, and `isEmbedded()`
+/ the return-trip handling are internal SDK concerns.
 
-### Validating a draft (read before self-testing)
+### Self-testing a draft: local test mode
 
 An unpublished draft shows the sign-in gate to any browser that isn't signed
 in as the owner — **including your own test browser** (Playwright, headless
-Chrome). The game still boots behind the overlay: console logs, DOM snapshots,
-and key events all work — but every screenshot shows the gate, not the game,
-and a gate capture is NOT visual evidence.
-
-- Validate what the gate can't hide: a clean console, the canvas booting, the
-  HUD present in a DOM snapshot, controls registering.
-- Pointer lock can't be acquired headlessly either (`requestPointerLock` throws
-  in headless Chromium): for aim games validate the unlocked "click to aim" cue
-  and the wiring, not the lock itself (see `$genex-threejs-visual-validation`
-  step 6).
-- Do NOT work around the gate: don't dig through the SDK's internals for
-  undocumented URL fragments, and don't drive the user's own signed-in
-  browser.
-- For the visual pass on a draft, the owner IS the QA loop — not a fallback:
-  push `genex preview` at each playable milestone and hand it off plainly
-  ("check the draft — you can now X; ping me if something feels off"), then
-  keep building while they look. Their run-around catches exactly what the
-  gate hides from you: facing, proportions, feel. Once the game is
-  **published**, any fresh browser gets in as a guest, so your own test
-  browser works again for full visual validation.
+Chrome) — and the hosted draft URL applies the same identity rule. The one
+supported way to see and play the game yourself is **local test mode**: open
+the local dev server with the explicit opt-in marker —
+
+```
+http://localhost:5173/?genex_local_test=1
+```
+
+(any port; append with `&` if the URL already has a query). On an exact http
+loopback origin (`localhost`, `127.0.0.1`, `[::1]`) the SDK skips the
+identity flow entirely and boots a guest-like session: no redirect, no
+overlay, `waitForPlayer()` resolves with the unmistakable local identity
+`{ id: "local:test", name: "Local Tester" }`, and the console prints a
+"local test mode" notice. Requires `@genex-ai/embed-sdk` 0.5.0+ — on an older
+project the marker does nothing; apply the pending platform update first (any
+`genex` command prints the update nudge and how to apply it), then retry.
+
+**It validates:** rendering, camera, controls, HUD, game feel, and real
+gameplay screenshots — everything local.
+
+**It does NOT validate** (nothing online exists in this mode; no credential
+is ever minted): real sign-in (`waitForAuth()` stays pending, exactly like a
+guest), saves (they queue in memory), leaderboards (`getLeaderboard()`
+resolves `{ items: [], me: null }` locally), score submits, and multiplayer
+(`getColyseusAuth()` is `undefined`, so `connect()` fails at the relay —
+expected in this mode, not a bug to chase).
+
+Rules:
+
+- **Label the evidence** in your handoff: "validated in local test mode —
+  auth, saves, and multiplayer not exercised." Presenting a local-test
+  capture as full validation is an over-claim.
+- Pointer lock still can't be acquired headlessly (`requestPointerLock`
+  throws in headless Chromium): for aim games validate the unlocked "click
+  to aim" cue and the wiring, not the lock itself (see
+  `$genex-threejs-visual-validation` step 6).
+- The marker is inert on any hosted URL, on https, and inside any iframe —
+  local test mode cannot open the hosted draft; hosted draft access stays
+  owner-only. Do NOT work around that gate: no undocumented URL fragments,
+  no auth mocks, and never drive the user's own signed-in browser.
+- Opening localhost WITHOUT the marker keeps the normal real-auth flow (the
+  identity bounce) — that's for testing real sign-in, not for self-testing.
+- The owner's draft run-through stays a required beat, not a fallback: push
+  `genex preview` at each playable milestone and hand it off plainly ("check
+  the draft — you can now X; ping me if something feels off"), then keep
+  building while they look. Hosted QA catches what local test mode can't:
+  real identity, saves, multiplayer, feel. Once the game is **published**,
+  any fresh browser gets in as a guest, so full visual validation also works
+  without the marker.
 
 ## Checklist
 
@@ -304,6 +337,8 @@ and a gate capture is NOT visual evidence.
 - [ ] No token value is ever logged or sent to analytics.
 - [ ] No custom sign-in prompt, guest badge, or auth overlay — the SDK popover/
       overlay and the dashboard own all of that UX.
+- [ ] Self-test evidence captured in local test mode is labeled as such in the
+      handoff ("local test mode — auth, saves, and multiplayer not exercised").
 
 ## Troubleshooting
 
@@ -316,7 +351,15 @@ and a gate capture is NOT visual evidence.
 - **State is `"blocked"` / `waitForPlayer()` rejects** — an unpublished draft
   opened by a non-owner, or auth infrastructure was unreachable. The SDK
   overlay (or the dashboard, when embedded) shows the sign-in prompt; the game
-  just stays paused behind it. Don't retry in a loop.
+  just stays paused behind it. Don't retry in a loop. Self-testing a draft
+  locally? Use local test mode (`?genex_local_test=1`) instead.
+- **Local test mode doesn't activate** — check all four: the value is exactly
+  `genex_local_test=1`, the origin is http loopback (`localhost`/`127.0.0.1`/
+  `[::1]` — not https, not a LAN IP), the page is not inside an iframe, and
+  `@genex-ai/embed-sdk` is 0.5.0+ (older: apply the pending platform update).
+- **Multiplayer `connect()` fails in local test mode** — by design: no relay
+  credential exists there. Validate multiplayer on the hosted draft (the
+  owner's session) or the published game, and say plainly when it wasn't.
 - **Multiplayer join rejected with 401** — `connect()` ran before
   `waitForPlayer()` resolved, without `auth: getColyseusAuth()!`, or with a
   stale cached token on reconnect (read it fresh each call).

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

@@ -34,17 +34,17 @@ example, the shared-object/ball code, rotation, and host usage. Read
 ## Install
 
 ```bash
-npm i @genex-ai/multiplayer@^0.9.0
+npm i @genex-ai/multiplayer@^0.10.0
 ```
 
-> Pin `@^0.9.0` (not a bare `npm i`): confirmed object controls, discontinuity snaps, host-tick
-> teardown, and reconnect rebasing landed in 0.9. An older resolve does not have
-> `room.objects.claimConfirmed` or `room.me.snap`.
+> Pin `@^0.10.0` (not a bare `npm i`): regional relay selection (`getColyseusUrls()` + `urls`)
+> landed in 0.10; confirmed object controls, snaps, host-tick teardown, and reconnect rebasing
+> in 0.9. An older resolve does not have those.
 
-This skill targets `@genex-ai/multiplayer` **≥ 0.9.0** (`objects`/`host` since 0.4;
+This skill targets `@genex-ai/multiplayer` **≥ 0.10.0** (`objects`/`host` since 0.4;
 `matchmake()` since 0.5; private lobbies since 0.7; auto-reconnect + `inputs`/`onHostTick`
 since 0.8; soft ownership handoff since 0.8.4; confirmed controls, snap epochs, and host-tick
-lifecycle guarantees since 0.9).
+lifecycle guarantees since 0.9; regional relay selection via `getColyseusUrls()` since 0.10).
 
 ## Trust model (say it plainly in your game's copy)
 
@@ -68,7 +68,7 @@ HUD from `mm.matchmaking` (its `status`, `queue.position`, `players`/`opponents`
 // requeue) over a session, and embed tokens rotate (~10 min). A function is read fresh each (re)join;
 // a static object goes stale and gets rejected mid-session.
 await waitForPlayer();  // identity gate first (guest OR signed-in) — same rule as connect()
-const mm = await matchmake<MyState>({ url, room: slug, auth: () => getColyseusAuth() });
+const mm = await matchmake<MyState>({ urls, room: slug, auth: () => getColyseusAuth() });
 mm.on('matched', () => {/* session is live — start the game */});
 // each frame: if (mm.session) renderGame(mm.session); else renderSearchingHud(mm.matchmaking);
 mm.on('matchEnded', ({ winnerId, scores, draw }) => {/* result screen */});
@@ -182,10 +182,10 @@ and friends join it; the lobby is persistent (rounds replay, nobody is evicted):
 
 ```ts
 import { createPrivate, joinPrivate } from "@genex-ai/multiplayer";
-const lobby = await createPrivate<MyState>({ url, room: slug, auth: () => getColyseusAuth() });  // live NOW
+const lobby = await createPrivate<MyState>({ urls, room: slug, auth: () => getColyseusAuth() });  // live NOW
 showCode(lobby.code);                                                   // share this
 // a friend, elsewhere:
-const lobby = await joinPrivate<MyState>(code, { url, room: slug, auth: () => getColyseusAuth() });
+const lobby = await joinPrivate<MyState>(code, { urls, room: slug, auth: () => getColyseusAuth() });
 // same handle API as matchmake(): lobby.session, lobby.matchmaking, eliminated()/score()/finish(), cancel()
 ```
 
@@ -202,13 +202,13 @@ pending for guests and would keep them out of multiplayer forever:
 
 ```ts
 import { connect } from "@genex-ai/multiplayer";
-import { waitForPlayer, getColyseusAuth } from "@genex-ai/embed-sdk";
+import { waitForPlayer, getColyseusAuth, getColyseusUrls } from "@genex-ai/embed-sdk";
 
 type State = { x: number; z: number; q: number[] };  // YOUR per-player state (rotation as quaternion)
 
 const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — rejects only if blocked
 const room = await connect<State>({
-  url: GENEX.colyseusUrl,     // e.g. "wss://demo-colyseus.glotech.world" — see config wiring below
+  urls: getColyseusUrls(),    // regional relays for this session (server-owned); SDK joins the fastest
   room: GENEX.slug,           // the project slug — everyone with this id shares a room
   name: user.name,            // display name — the server prefers the verified identity's name
   auth: getColyseusAuth()!,   // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.
@@ -451,7 +451,11 @@ from any still capture whether movement feels smooth.** Don't try — it leads t
 
 1. **Trust the SDK's smoothing.** Draw `state` directly; don't add your own.
 2. **Verify it *runs*:** two clients, distinct meshes, both move, no console errors, each sees the
-   other (and the ball, if any). That's all a capture can prove.
+   other (and the ball, if any). That's all a capture can prove. Local test mode (the embed-auth
+   skill's `?genex_local_test=1`) can NOT do this: it mints no relay credential, so `connect()`
+   fails there by design and two local-test tabs never see each other — run the two-client check
+   on the published game (or have the owner open their draft), and if multiplayer wasn't
+   exercised, say exactly that in your handoff instead of implying it was.
 3. **Then say plainly:** *"Multiplayer smoothness depends on your network and can only be felt by a
    person — open it in two tabs or with a friend and tell me how it feels."* Stop there.
 
@@ -479,7 +483,7 @@ it; never hardcode a URL or edit the file:
 
 ```ts
 import { GENEX } from "./genex.config";
-// GENEX.slug / GENEX.colyseusUrl / GENEX.apiUrl / GENEX.dashboardOrigins
+// GENEX.slug / GENEX.apiUrl / GENEX.dashboardOrigins
 ```
 
 See the `genex-threejs-embed-auth` skill's "Config wiring" section for the full
@@ -527,7 +531,7 @@ host-driven saving works as long as ANY account is in the room.
 
 ## Checklist
 
-- [ ] `npm i @genex-ai/multiplayer@^0.9.0` (confirmed controls, snap epochs, reconnect-safe host ticks); config wired into the build.
+- [ ] `npm i @genex-ai/multiplayer@^0.10.0` (confirmed controls, snap epochs, reconnect-safe host ticks); 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`.
 - [ ] Pushable/ownable objects (ball, box, prop) use claim-on-touch + a Rapier proxy (the soft handoff glides the handoff); only a genuine simultaneous tug-of-war (sumo) uses the host-authoritative pattern. See host-physics.md.

package/templates/skills/genex-threejs-multiplayer/references/realtime-patterns.md

@@ -27,7 +27,7 @@ type S = { x: number; z: number; q: number[]; hp: number };
 
 const { user } = await waitForPlayer();  // player gate (guest OR signed-in) — never waitForAuth()
 const room = await connect<S>({
-  url: GENEX.colyseusUrl,
+  urls: getColyseusUrls(),
   room: GENEX.slug,
   name: user.name,
   auth: getColyseusAuth()!,  // REQUIRED — tokenless joins are rejected. Read fresh each connect; NEVER log it.

package/templates/skills/genex-threejs-visual-validation/SKILL.md

@@ -25,18 +25,26 @@ evidence, temporal checks, budgets, and explicit rejection criteria.
 ## Interaction smoke check (the game fast path)
 
 For plain game tasks — nothing from the procedural/visual-system pack loaded —
-this is the whole acceptance gate, and it is also the minimum for every game:
+this is the whole acceptance gate, and it is also the *ceiling*: a smoke check,
+not a certification. Run it ONCE per milestone to catch obvious breakage, fix
+what's clearly broken, and hand the feel/polish judgment to the player — don't
+loop re-testing the same build, and don't try to exercise every button and edge
+case yourself. The player deciding "does it feel right?" is faster and truer
+than you clicking everything twice.
 
 1. Load the page in a real browser; the canvas renders (no black screen, no
-   console errors).
+   console errors). For an unpublished draft, open the dev server in local
+   test mode — `http://localhost:5173/?genex_local_test=1` (the embed-auth
+   skill's "Self-testing a draft" section) — so you see the game, not the
+   sign-in gate.
 2. Press each documented control once (keys, pointer); assert a **visible
    response** to every one — the player moves, the camera turns, the button
    fires.
 3. Capture one screenshot of live gameplay — of the **game**, not a sign-in
    gate or loading screen. A capture of the SDK's "Sign in to play" overlay is
-   NOT gameplay evidence; if a draft's gate blocks the view, say so plainly
-   (see the embed-auth skill's "Validating a draft" note) instead of passing
-   the capture off as validation.
+   NOT gameplay evidence. Evidence captured in local test mode must be labeled
+   as such in the handoff ("local test mode — auth, saves, and multiplayer not
+   exercised"); presenting it as full validation is an over-claim.
 4. In that screenshot, check oriented models: the hero faces its travel
    direction, and NPCs driven by chase/aim code face their target. A model
    rotated 90° reads as broken — `$genex-ai-model` has the one-time facing

package/templates/skills/genex-updates/SKILL.md

@@ -38,7 +38,7 @@ update, so update immediately.)
 Run exactly the command the nudge printed, from the game project root:
 
 ```bash
-npm i -D @genex-ai/cli-demo@latest   # the genex CLI (a dev dependency)
+npm i -D @genex-ai/cli-demo@dev   # the genex CLI (a dev dependency)
 npm i @genex-ai/embed-sdk@latest     # identity/saves SDK (ships inside the game)
 npm i @genex-ai/multiplayer@latest   # multiplayer SDK (only if the game uses it)
 ```