@genex-ai/cli-demo 0.23.0 → 0.25.0

package/README.md

@@ -28,8 +28,10 @@ genex controller <type>    # install a tuned character|car|drone controller →
    agents/ + commands/), Codex (`~/.codex/skills`), and Cursor
    (`~/.cursor/skills`). genex-owned skills (`genex-*`) are **always refreshed**
    to the package version so a stale copy can't linger; your own files are never
-   overwritten. Pick agents explicitly with `--agents claude,codex,cursor`, or a
-   single custom dir with `--dir`.
+   overwritten. After init, **every** `genex` command re-syncs them to the
+   installed CLI version automatically (printing `🔄 Genex skills updated to
+   X.Y.Z` when it does). Pick agents explicitly with `--agents
+   claude,codex,cursor`, or a single custom dir with `--dir`.
 2. **Authorizes you** — opens the Genex auth site (web) in your browser. If the
    browser can't open, it prints the URL to open manually.
 3. **Saves your token** — writes `GENEX_TOKEN` to `~/.genex/env` (per-user;

package/dist/index.js

@@ -1,12 +1,7 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync } from "fs";
-import path12 from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-
 // src/commands/init.ts
-import path7 from "path";
+import path8 from "path";
 
 // src/config.ts
 import fs from "fs";
@@ -43,6 +38,17 @@ function getTemplatesDir() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   return path.resolve(here, "..", "templates");
 }
+function getCliVersion() {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      fs.readFileSync(path.resolve(here, "..", "package.json"), "utf8")
+    );
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 var KNOWN_AGENTS = {
   claude: { label: "Claude Code", dirName: ".claude", full: true },
   codex: { label: "Codex", dirName: ".codex", full: false },
@@ -121,6 +127,172 @@ async function exists(p) {
   }
 }
 
+// src/lib/updates.ts
+import fs3 from "fs/promises";
+import path3 from "path";
+function parseSemver(v) {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function isNewerVersion(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return false;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i];
+  }
+  return false;
+}
+var SKILLS_VERSION_MARKER = "genex-skills-version.json";
+async function readSkillsMarker(skillsDir) {
+  try {
+    const raw = await fs3.readFile(path3.join(skillsDir, SKILLS_VERSION_MARKER), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed.version === "string" ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+async function writeSkillsMarker(skillsDir, version = getCliVersion()) {
+  await fs3.mkdir(skillsDir, { recursive: true });
+  await fs3.writeFile(
+    path3.join(skillsDir, SKILLS_VERSION_MARKER),
+    JSON.stringify({ version, syncedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n"
+  );
+}
+async function hasGenexSkills(skillsDir) {
+  try {
+    const entries = await fs3.readdir(skillsDir);
+    return entries.some((name) => name.startsWith("genex-"));
+  } catch {
+    return false;
+  }
+}
+async function syncSkillsForTarget(target, templatesDir = getTemplatesDir(), version = getCliVersion()) {
+  const skillsDir = path3.join(target.baseDir, "skills");
+  if (!await hasGenexSkills(skillsDir)) return false;
+  if (await readSkillsMarker(skillsDir) === version) return false;
+  const src = target.full ? templatesDir : path3.join(templatesDir, "skills");
+  const dest = target.full ? target.baseDir : skillsDir;
+  await copyTemplates(src, dest, { exclude: ["controllers"] });
+  await writeSkillsMarker(skillsDir, version);
+  return true;
+}
+async function syncSkills(log) {
+  try {
+    const version = getCliVersion();
+    const templatesDir = getTemplatesDir();
+    let refreshed = false;
+    for (const target of resolveAgentTargets()) {
+      try {
+        refreshed = await syncSkillsForTarget(target, templatesDir, version) || refreshed;
+      } catch {
+      }
+    }
+    if (refreshed) log.plain(`\u{1F504} Genex skills updated to ${version}`);
+  } catch {
+  }
+}
+var PUBLISHED_PACKAGES = [
+  { name: "@genex-ai/cli-demo", label: "CLI", install: "npm i -D @genex-ai/cli-demo@latest" },
+  { name: "@genex-ai/embed-sdk", label: "embed SDK", install: "npm i @genex-ai/embed-sdk@latest" },
+  {
+    name: "@genex-ai/multiplayer",
+    label: "multiplayer SDK",
+    install: "npm i @genex-ai/multiplayer@latest"
+  }
+];
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var REGISTRY_TIMEOUT_MS = 1500;
+function getUpdateCachePath() {
+  return path3.join(getGenexDir(), "update-check.json");
+}
+function isCacheFresh(cache, nowMs) {
+  const at = Date.parse(cache.checkedAt);
+  return Number.isFinite(at) && nowMs - at < CHECK_INTERVAL_MS;
+}
+async function readUpdateCache() {
+  try {
+    const raw = await fs3.readFile(getUpdateCachePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.checkedAt !== "string" || typeof parsed.latest !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+async function fetchLatestFromRegistry(name) {
+  try {
+    const res = await fetch(
+      `https://registry.npmjs.org/-/package/${encodeURIComponent(name)}/dist-tags`,
+      { signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS) }
+    );
+    if (!res.ok) return null;
+    const tags = await res.json();
+    return typeof tags.latest === "string" && parseSemver(tags.latest) ? tags.latest : null;
+  } catch {
+    return null;
+  }
+}
+function startUpdateCheck() {
+  return (async () => {
+    try {
+      const cached = await readUpdateCache();
+      if (cached && isCacheFresh(cached, Date.now())) return cached;
+      const latest = { ...cached?.latest ?? {} };
+      const results = await Promise.allSettled(
+        PUBLISHED_PACKAGES.map((p) => fetchLatestFromRegistry(p.name))
+      );
+      results.forEach((r, i) => {
+        if (r.status === "fulfilled" && r.value) latest[PUBLISHED_PACKAGES[i].name] = r.value;
+      });
+      const next = { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), latest };
+      await fs3.mkdir(getGenexDir(), { recursive: true });
+      await fs3.writeFile(getUpdateCachePath(), JSON.stringify(next, null, 2) + "\n");
+      return next;
+    } catch {
+      return null;
+    }
+  })();
+}
+async function installedPackageVersion(cwd, name) {
+  try {
+    const raw = await fs3.readFile(path3.join(cwd, "node_modules", name, "package.json"), "utf8");
+    const pkg = JSON.parse(raw);
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+function formatNudge(label, latest, installed, install) {
+  return `\u2B06 Genex ${label} ${latest} available (installed ${installed}) \u2014 run: ${install}`;
+}
+async function reportUpdateNudges(check, log, cwd = process.cwd()) {
+  try {
+    const cache = await check;
+    if (!cache) return;
+    const lines = [];
+    let whatsNew = null;
+    for (const pkg of PUBLISHED_PACKAGES) {
+      const latest = cache.latest[pkg.name];
+      if (!latest) continue;
+      const installed = pkg.name === "@genex-ai/cli-demo" ? getCliVersion() : await installedPackageVersion(cwd, pkg.name);
+      if (!installed) continue;
+      if (isNewerVersion(latest, installed)) {
+        lines.push(formatNudge(pkg.label, latest, installed, pkg.install));
+        whatsNew ??= `https://www.npmjs.com/package/${pkg.name}`;
+      }
+    }
+    if (lines.length === 0) return;
+    for (const line of lines) log.plain(line);
+    log.dim(
+      `  Apply at a safe moment (never mid-task) \u2014 see the genex-updates skill. What's new: ${whatsNew}`
+    );
+  } catch {
+  }
+}
+
 // src/lib/auth.ts
 import http from "http";
 import crypto from "crypto";
@@ -388,6 +560,29 @@ var c = {
   gray: code(90, 39)
 };
 
+// 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 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)`];
+}
+async function apiFetch(url, init = {}) {
+  const headers = new Headers(init.headers);
+  if (!headers.has(CLI_VERSION_HEADER)) headers.set(CLI_VERSION_HEADER, getCliVersion());
+  const res = await fetch(url, { ...init, headers });
+  if (res.status === 426) {
+    try {
+      const body = await res.clone().json();
+      if (body?.error === "cli_update_required") {
+        for (const line of formatUpdateRequired(body)) process.stderr.write(line + "\n");
+      }
+    } catch {
+    }
+  }
+  return res;
+}
+
 // src/lib/project.ts
 async function createDraftProject(opts) {
   const { apiUrl, token, deployKey, colyseusUrl, dashboardUrl, log } = opts;
@@ -397,7 +592,7 @@ async function createDraftProject(opts) {
     const name = names[i];
     let res;
     try {
-      res = await fetch(`${apiUrl}/api/projects`, {
+      res = await apiFetch(`${apiUrl}/api/projects`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
@@ -453,15 +648,15 @@ function randomSuffix() {
 }
 
 // src/lib/ssh.ts
-import fs3 from "fs/promises";
-import path3 from "path";
+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 = path3.join(dir, KEY_NAME);
+  const keyPath = path4.join(dir, KEY_NAME);
   const pubPath = `${keyPath}.pub`;
   try {
-    const existing = (await fs3.readFile(pubPath, "utf8")).trim();
+    const existing = (await fs4.readFile(pubPath, "utf8")).trim();
     if (existing) {
       log.dim(`Reusing existing deploy key (${KEY_NAME}).`);
       return { publicKey: existing };
@@ -472,12 +667,12 @@ async function generateSshKeypair(dir, log) {
   const ok = await runSshKeygen(keyPath, log);
   if (!ok) return null;
   try {
-    const pub = (await fs3.readFile(pubPath, "utf8")).trim();
+    const pub = (await fs4.readFile(pubPath, "utf8")).trim();
     if (!pub) {
       log.warn("ssh-keygen produced no public key.");
       return null;
     }
-    await fs3.chmod(keyPath, 384).catch(() => {
+    await fs4.chmod(keyPath, 384).catch(() => {
     });
     return { publicKey: pub };
   } catch (err) {
@@ -507,10 +702,10 @@ function runSshKeygen(keyPath, log) {
   });
 }
 async function writeGitignore(dir, log) {
-  const file = path3.join(dir, ".gitignore");
+  const file = path4.join(dir, ".gitignore");
   let content = "";
   try {
-    content = await fs3.readFile(file, "utf8");
+    content = await fs4.readFile(file, "utf8");
   } catch {
   }
   const present = new Set(content.split("\n").map((l) => l.trim()));
@@ -520,23 +715,23 @@ async function writeGitignore(dir, log) {
   if (next.length > 0 && !next.endsWith("\n")) next += "\n";
   if (!content.trim()) next += "# genex (deploy key + local metadata \u2014 never publish)\n";
   next += toAdd.join("\n") + "\n";
-  await fs3.writeFile(file, next);
+  await fs4.writeFile(file, next);
   log.dim(`Updated .gitignore (${toAdd.join(", ")}).`);
 }
 
 // src/lib/store.ts
-import fs5 from "fs/promises";
-import path5 from "path";
+import fs6 from "fs/promises";
+import path6 from "path";
 
 // src/lib/env.ts
-import fs4 from "fs/promises";
-import path4 from "path";
+import fs5 from "fs/promises";
+import path5 from "path";
 import { spawn as spawn3 } from "child_process";
 async function writeEnvVar(envPath, key, value) {
   let content = "";
   let existed = false;
   try {
-    content = await fs4.readFile(envPath, "utf8");
+    content = await fs5.readFile(envPath, "utf8");
     existed = true;
   } catch {
   }
@@ -556,14 +751,14 @@ async function writeEnvVar(envPath, key, value) {
     next = prefix + assignment + "\n";
     mode = existed ? "appended" : "created";
   }
-  await fs4.mkdir(path4.dirname(envPath), { recursive: true });
-  await fs4.writeFile(envPath, next, { mode: 384 });
+  await fs5.mkdir(path5.dirname(envPath), { recursive: true });
+  await fs5.writeFile(envPath, next, { mode: 384 });
   await restrictFilePermissions(envPath);
   return { mode, path: envPath };
 }
 async function restrictFilePermissions(filePath) {
   if (process.platform !== "win32") {
-    await fs4.chmod(filePath, 384).catch(() => {
+    await fs5.chmod(filePath, 384).catch(() => {
     });
     return;
   }
@@ -595,7 +790,7 @@ function escapeRegExp(s) {
 
 // src/lib/store.ts
 function getProjectMetadataPath(cwd = process.cwd()) {
-  return path5.join(cwd, ".genex", "project.json");
+  return path6.join(cwd, ".genex", "project.json");
 }
 async function writeUserToken(token, envPath) {
   const { path: written } = await writeEnvVar(getGenexEnvPath(envPath), ENV_TOKEN_KEY, token);
@@ -605,14 +800,14 @@ async function readUserToken(envPath) {
   const fromGenex = await readTokenFromFile(getGenexEnvPath(envPath));
   if (fromGenex) return fromGenex;
   if (!envPath) {
-    return readTokenFromFile(path5.join(process.cwd(), ".env"));
+    return readTokenFromFile(path6.join(process.cwd(), ".env"));
   }
   return null;
 }
 async function readTokenFromFile(file) {
   let content;
   try {
-    content = await fs5.readFile(file, "utf8");
+    content = await fs6.readFile(file, "utf8");
   } catch {
     return null;
   }
@@ -628,7 +823,7 @@ function stripQuotes(v) {
 }
 async function readProject(cwd = process.cwd()) {
   try {
-    const raw = await fs5.readFile(getProjectMetadataPath(cwd), "utf8");
+    const raw = await fs6.readFile(getProjectMetadataPath(cwd), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -636,16 +831,16 @@ async function readProject(cwd = process.cwd()) {
 }
 async function writeProject(meta, cwd = process.cwd()) {
   const file = getProjectMetadataPath(cwd);
-  await fs5.mkdir(path5.dirname(file), { recursive: true });
-  await fs5.writeFile(file, JSON.stringify(meta, null, 2) + "\n", { mode: 384 });
-  await fs5.chmod(file, 384).catch(() => {
+  await fs6.mkdir(path6.dirname(file), { recursive: true });
+  await fs6.writeFile(file, JSON.stringify(meta, null, 2) + "\n", { mode: 384 });
+  await fs6.chmod(file, 384).catch(() => {
   });
   return { path: file };
 }
 
 // src/lib/game-config.ts
-import fs6 from "fs/promises";
-import path6 from "path";
+import fs7 from "fs/promises";
+import path7 from "path";
 var DEFAULT_DASHBOARD_ORIGIN = new URL(DEFAULT_AUTH_URL).origin;
 function renderGenexConfig() {
   return `// src/genex.config.ts \u2014 written by \`genex init\`. DO NOT hardcode URLs here.
@@ -686,7 +881,7 @@ ${overrides.join("\n")}
 }
 async function writeIfAbsent(file, content, log) {
   try {
-    await fs6.writeFile(file, content, { flag: "wx" });
+    await fs7.writeFile(file, content, { flag: "wx" });
     log.dim(`  wrote ${c.cyan(file)}`);
     return true;
   } catch (err) {
@@ -698,12 +893,12 @@ async function writeIfAbsent(file, content, log) {
   }
 }
 async function writeGameConfigFiles(meta, log, cwd = process.cwd()) {
-  await fs6.mkdir(path6.join(cwd, "src"), { recursive: true });
-  await writeIfAbsent(path6.join(cwd, "src", "genex.config.ts"), renderGenexConfig(), log);
-  await writeIfAbsent(path6.join(cwd, ".env"), renderSlugEnv(meta.slug), log);
+  await fs7.mkdir(path7.join(cwd, "src"), { recursive: true });
+  await writeIfAbsent(path7.join(cwd, "src", "genex.config.ts"), renderGenexConfig(), log);
+  await writeIfAbsent(path7.join(cwd, ".env"), renderSlugEnv(meta.slug), log);
   const overrides = renderDevOverrides(meta);
   if (overrides) {
-    await writeIfAbsent(path6.join(cwd, ".env.development.local"), overrides, log);
+    await writeIfAbsent(path7.join(cwd, ".env.development.local"), overrides, log);
   }
 }
 
@@ -739,12 +934,13 @@ async function runInit(opts) {
   let totalNew = 0;
   let totalUpdated = 0;
   for (const t of targets) {
-    const src = t.full ? templatesDir : path7.join(templatesDir, "skills");
-    const dest = t.full ? t.baseDir : path7.join(t.baseDir, "skills");
+    const src = t.full ? templatesDir : path8.join(templatesDir, "skills");
+    const dest = t.full ? t.baseDir : path8.join(t.baseDir, "skills");
     const { copied, updated } = await copyTemplates(src, dest, {
       force: opts.force,
       exclude: ["controllers"]
     });
+    await writeSkillsMarker(path8.join(t.baseDir, "skills"));
     const added = copied.length - updated.length;
     totalNew += added;
     totalUpdated += updated.length;
@@ -787,7 +983,7 @@ async function runInit(opts) {
   }
   const apiUrl = getApiUrl(opts.apiUrl);
   const colyseusUrl = getColyseusUrl(opts.colyseusUrl);
-  const projectName = opts.name?.trim() || path7.basename(process.cwd());
+  const projectName = opts.name?.trim() || path8.basename(process.cwd());
   const meta = await createDraftProject({
     apiUrl,
     token,
@@ -807,8 +1003,8 @@ async function runInit(opts) {
 }
 
 // src/commands/link.ts
-import fs7 from "fs/promises";
-import path8 from "path";
+import fs8 from "fs/promises";
+import path9 from "path";
 async function runLink(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex link"));
@@ -879,29 +1075,29 @@ async function runLink(opts) {
   if (project.playUrl) log.dim(`  play URL: ${project.playUrl}`);
 }
 async function ensureSlugEnv(slug, log, cwd = process.cwd()) {
-  const file = path8.join(cwd, ".env");
+  const file = path9.join(cwd, ".env");
   let content;
   try {
-    content = await fs7.readFile(file, "utf8");
+    content = await fs8.readFile(file, "utf8");
   } catch {
     return;
   }
   const re = /^(\s*VITE_GENEX_SLUG=)(.*)$/m;
   const m = content.match(re);
   if (!m) {
-    await fs7.appendFile(file, `${content.endsWith("\n") ? "" : "\n"}VITE_GENEX_SLUG=${slug}
+    await fs8.appendFile(file, `${content.endsWith("\n") ? "" : "\n"}VITE_GENEX_SLUG=${slug}
 `);
     log.dim(`  added VITE_GENEX_SLUG=${slug} to .env`);
     return;
   }
   if (m[2].trim() === slug) return;
-  await fs7.writeFile(file, content.replace(re, `$1${slug}`));
+  await fs8.writeFile(file, content.replace(re, `$1${slug}`));
   log.dim(`  updated .env: VITE_GENEX_SLUG=${slug} (was ${m[2].trim()})`);
 }
 async function fetchOwnProject(apiUrl, token, slug, log) {
   let res;
   try {
-    res = await fetch(`${apiUrl}/api/projects/by-slug/${encodeURIComponent(slug)}`, {
+    res = await apiFetch(`${apiUrl}/api/projects/by-slug/${encodeURIComponent(slug)}`, {
       headers: { Authorization: `Bearer ${token}` }
     });
   } catch (err) {
@@ -933,7 +1129,7 @@ async function fetchOwnProject(apiUrl, token, slug, log) {
 }
 async function listOwnSlugs(apiUrl, token, log) {
   try {
-    const res = await fetch(`${apiUrl}/api/projects`, {
+    const res = await apiFetch(`${apiUrl}/api/projects`, {
       headers: { Authorization: `Bearer ${token}` }
     });
     if (!res.ok) return;
@@ -950,7 +1146,7 @@ async function listOwnSlugs(apiUrl, token, log) {
 async function registerDeployKey(apiUrl, token, projectId, deployKey, log) {
   let res;
   try {
-    res = await fetch(`${apiUrl}/api/projects/${projectId}/deploy-key`, {
+    res = await apiFetch(`${apiUrl}/api/projects/${projectId}/deploy-key`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
@@ -982,9 +1178,9 @@ async function registerDeployKey(apiUrl, token, projectId, deployKey, log) {
 // src/lib/deploy.ts
 import { spawn as spawn4 } from "child_process";
 import crypto3 from "crypto";
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import os2 from "os";
-import path9 from "path";
+import path10 from "path";
 function run(cmd, args, env) {
   return new Promise((resolve) => {
     let child;
@@ -1016,9 +1212,9 @@ async function deployGame(ctx, opts, log) {
     }
     log.success("Built.");
   }
-  const distDir = path9.join(cwd, "dist");
+  const distDir = path10.join(cwd, "dist");
   const siteDir = await isDir2(distDir) ? distDir : cwd;
-  const rel = path9.relative(cwd, siteDir) || ".";
+  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))) {
@@ -1057,7 +1253,7 @@ async function deployGame(ctx, opts, log) {
     log.error("Couldn't upload your game \u2014 please try again.");
     return false;
   }
-  const keyPath = path9.resolve(cwd, KEY_NAME);
+  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;
@@ -1071,7 +1267,7 @@ async function deployGame(ctx, opts, log) {
 }
 async function hasBuildScript(cwd) {
   try {
-    const pkg = JSON.parse(await fs8.readFile(path9.join(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(await fs9.readFile(path10.join(cwd, "package.json"), "utf8"));
     return Boolean(pkg.scripts?.build);
   } catch {
     return false;
@@ -1080,12 +1276,12 @@ async function hasBuildScript(cwd) {
 async function collectFiles(root) {
   const out = [];
   const walk2 = async (dir, prefix) => {
-    for (const e of await fs8.readdir(dir, { withFileTypes: true })) {
+    for (const e of await fs9.readdir(dir, { withFileTypes: true })) {
       const relPath = prefix ? `${prefix}/${e.name}` : e.name;
       if (e.isDirectory()) {
-        if (!EXCLUDE_DIRS.has(e.name)) await walk2(path9.join(dir, e.name), relPath);
+        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`) {
-        out.push({ relPath, bytes: await fs8.readFile(path9.join(dir, e.name)) });
+        out.push({ relPath, bytes: await fs9.readFile(path10.join(dir, e.name)) });
       }
     }
   };
@@ -1104,7 +1300,7 @@ function contentCommit(files) {
 async function getUploadToken(ctx, commit, log) {
   let res;
   try {
-    res = await fetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/upload-token`, {
+    res = await apiFetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/upload-token`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${ctx.token}` },
       body: JSON.stringify({ commit })
@@ -1151,7 +1347,7 @@ async function uploadAll(uploadUrl, uploadToken, files, log) {
 async function callPublish(ctx, commit, opts, log) {
   let res;
   try {
-    res = await fetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/publish`, {
+    res = await apiFetch(`${ctx.apiUrl}/api/games/${ctx.projectId}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${ctx.token}` },
       // Detections ride every go-live (preview AND publish): matchmaking is
@@ -1181,7 +1377,7 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
     log.error("Couldn't save your game's source \u2014 please try again.");
     return false;
   };
-  const gitDir = await fs8.mkdtemp(path9.join(os2.tmpdir(), "genex-source-"));
+  const gitDir = await fs9.mkdtemp(path10.join(os2.tmpdir(), "genex-source-"));
   const base = { GIT_DIR: gitDir };
   const ident = {
     GIT_AUTHOR_NAME: "genex",
@@ -1191,11 +1387,11 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
   };
   try {
     if ((await run("git", ["init", "-q"], base)).code !== 0) return failed();
-    await fs8.writeFile(
-      path9.join(gitDir, "info", "exclude"),
+    await fs9.writeFile(
+      path10.join(gitDir, "info", "exclude"),
       ["node_modules/", "dist/", ".git/", KEY_NAME, `${KEY_NAME}.pub`, ".genex/", ""].join("\n")
     );
-    const env = { ...base, GIT_WORK_TREE: cwd, GIT_INDEX_FILE: path9.join(gitDir, "index-source") };
+    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)) {
@@ -1219,20 +1415,20 @@ async function pushSource(cwd, sshUrl, keyPath, log) {
   } catch {
     return failed();
   } finally {
-    await fs8.rm(gitDir, { recursive: true, force: true }).catch(() => {
+    await fs9.rm(gitDir, { recursive: true, force: true }).catch(() => {
     });
   }
 }
 async function isDir2(p) {
   try {
-    return (await fs8.stat(p)).isDirectory();
+    return (await fs9.stat(p)).isDirectory();
   } catch {
     return false;
   }
 }
 async function fileExists(p) {
   try {
-    await fs8.access(p);
+    await fs9.access(p);
     return true;
   } catch {
     return false;
@@ -1266,11 +1462,11 @@ async function waitUntilLive(playUrl, fingerprint, timeoutMs, log) {
 }
 
 // src/lib/detect-features.ts
-import fs9 from "fs/promises";
-import path10 from "path";
+import fs10 from "fs/promises";
+import path11 from "path";
 async function detectEmbedSdkVersion(cwd = process.cwd()) {
   try {
-    const raw = await fs9.readFile(path10.join(cwd, "package.json"), "utf8");
+    const raw = await fs10.readFile(path11.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     const version = pkg.dependencies?.["@genex-ai/embed-sdk"] ?? pkg.devDependencies?.["@genex-ai/embed-sdk"];
     return typeof version === "string" && version ? version : null;
@@ -1280,7 +1476,7 @@ async function detectEmbedSdkVersion(cwd = process.cwd()) {
 }
 async function detectMultiplayer(cwd = process.cwd()) {
   try {
-    const raw = await fs9.readFile(path10.join(cwd, "package.json"), "utf8");
+    const raw = await fs10.readFile(path11.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(raw);
     return Boolean(
       pkg.dependencies?.["@genex-ai/multiplayer"] ?? pkg.devDependencies?.["@genex-ai/multiplayer"]
@@ -1292,7 +1488,7 @@ async function detectMultiplayer(cwd = process.cwd()) {
 async function detectMatchmaking(log, cwd = process.cwd()) {
   let pkg;
   try {
-    pkg = JSON.parse(await fs9.readFile(path10.join(cwd, "package.json"), "utf8"));
+    pkg = JSON.parse(await fs10.readFile(path11.join(cwd, "package.json"), "utf8"));
   } catch (err) {
     log.dim(`  (skipping matchmaking \u2014 couldn't read package.json: ${String(err)})`);
     return null;
@@ -1309,10 +1505,10 @@ async function detectMatchmaking(log, cwd = process.cwd()) {
 }
 var GAME_STATE_CALLS = /savePlayerState|saveWorldState|submitScore/;
 async function detectGameStateUsage(cwd = process.cwd()) {
-  const srcDir = path10.join(cwd, "src");
+  const srcDir = path11.join(cwd, "src");
   let entries;
   try {
-    entries = await fs9.readdir(srcDir, { recursive: true });
+    entries = await fs10.readdir(srcDir, { recursive: true });
   } catch {
     return false;
   }
@@ -1320,7 +1516,7 @@ async function detectGameStateUsage(cwd = process.cwd()) {
     if (rel.includes("node_modules")) continue;
     if (!/\.(ts|js|mts|mjs|tsx|jsx)$/.test(rel)) continue;
     try {
-      const content = await fs9.readFile(path10.join(srcDir, rel), "utf8");
+      const content = await fs10.readFile(path11.join(srcDir, rel), "utf8");
       if (GAME_STATE_CALLS.test(content)) return true;
     } catch {
     }
@@ -1406,7 +1602,7 @@ async function runPublish(opts) {
     body.multiplayer = detections.multiplayer;
     body.matchmaking = detections.matchmaking ?? null;
     body.gameStateUsed = detections.gameStateUsed;
-    res = await fetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
+    res = await apiFetch(`${apiUrl}/api/projects/${meta.id}/publish`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
       body: JSON.stringify(body)
@@ -1533,7 +1729,7 @@ async function runGenerate(kind, opts) {
   log.plain("");
   let id;
   try {
-    const res = await fetch(`${apiUrl}/api/generations`, {
+    const res = await apiFetch(`${apiUrl}/api/generations`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
       body: JSON.stringify({ kind, prompt, options })
@@ -1599,7 +1795,7 @@ async function waitViaSSE(apiUrl, token, id, onProgress, deadline) {
     try {
       let res;
       try {
-        res = await fetch(`${apiUrl}/api/generations/${id}/events`, {
+        res = await apiFetch(`${apiUrl}/api/generations/${id}/events`, {
           headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream" },
           signal: abort.signal
         });
@@ -1646,7 +1842,7 @@ async function poll(apiUrl, token, id, onProgress) {
   let last = -1;
   while (Date.now() < deadline) {
     try {
-      const res = await fetch(`${apiUrl}/api/generations/${id}`, {
+      const res = await apiFetch(`${apiUrl}/api/generations/${id}`, {
         headers: { Authorization: `Bearer ${token}` }
       });
       if (res.ok) {
@@ -1668,7 +1864,7 @@ async function poll(apiUrl, token, id, onProgress) {
 function printHint(kind, files, log) {
   const url = files[0]?.url ?? "";
   const hint = {
-    model: `Load with GLTFLoader from the URL and add it to the scene \u2014 see the genex-ai-model skill. url = "${url}"`,
+    model: `Meshopt-compressed GLB \u2014 wire the decoder once (loader.setMeshoptDecoder(MeshoptDecoder)), then load with GLTFLoader from the URL \u2014 see the genex-ai-model skill. url = "${url}"`,
     skybox: `Load as an equirectangular texture \u2192 scene.background + scene.environment \u2014 see genex-ai-skybox. url = "${url}"`,
     sfx: `Load with AudioLoader into a THREE.PositionalAudio (camera needs an AudioListener) \u2014 see genex-ai-sfx. url = "${url}"`,
     texture: `Load each map with TextureLoader (RepeatWrapping) into a MeshStandardMaterial \u2014 see genex-ai-texture. Use the URLs above by role.`
@@ -1678,8 +1874,8 @@ function printHint(kind, files, log) {
 }
 
 // src/commands/controller.ts
-import fs10 from "fs/promises";
-import path11 from "path";
+import fs11 from "fs/promises";
+import path12 from "path";
 var CONTROLLER_KINDS = ["character", "car", "drone"];
 var SHARED = [
   "shared/math.ts",
@@ -1758,8 +1954,8 @@ var CONTROLLER_FILE_SETS = {
     ]
   }
 };
-var CODE_DEST = path11.join("src", "controllers");
-var ASSETS_DEST = path11.join("public", "assets");
+var CODE_DEST = path12.join("src", "controllers");
+var ASSETS_DEST = path12.join("public", "assets");
 async function runController(opts) {
   const log = createLogger({ quiet: opts.quiet });
   const kind = opts.kind?.trim();
@@ -1772,31 +1968,31 @@ async function runController(opts) {
     process.exitCode = 1;
     return;
   }
-  const srcDir = path11.join(getTemplatesDir(), "controllers");
+  const srcDir = path12.join(getTemplatesDir(), "controllers");
   const root = opts.cwd ?? process.cwd();
   const set = CONTROLLER_FILE_SETS[kind];
   log.plain(c.bold(`genex controller ${kind}`));
   log.plain("");
-  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path11.sep)}`);
+  log.step(`Installing the ${kind} controller into ${c.cyan(CODE_DEST + path12.sep)}`);
   const plan = [
-    ...set.code.map((rel) => ({ from: rel, rel: path11.join(CODE_DEST, rel) })),
+    ...set.code.map((rel) => ({ from: rel, rel: path12.join(CODE_DEST, rel) })),
     ...set.assets.map((rel) => ({
       from: rel,
-      rel: path11.join(ASSETS_DEST, path11.basename(rel))
+      rel: path12.join(ASSETS_DEST, path12.basename(rel))
     }))
   ];
   let copied = 0;
   let skipped = 0;
   try {
     for (const file of plan) {
-      const dest = path11.join(root, file.rel);
+      const dest = path12.join(root, file.rel);
       if (!opts.force && await exists2(dest)) {
         skipped++;
         log.dim(`  skipped ${file.rel} (exists \u2014 use --force to overwrite)`);
         continue;
       }
-      await fs10.mkdir(path11.dirname(dest), { recursive: true });
-      await fs10.copyFile(path11.join(srcDir, file.from), dest);
+      await fs11.mkdir(path12.dirname(dest), { recursive: true });
+      await fs11.copyFile(path12.join(srcDir, file.from), dest);
       copied++;
       log.dim(`  ${file.rel}`);
     }
@@ -1828,11 +2024,11 @@ async function runController(opts) {
 }
 async function installOwnerAvatar(args) {
   const { root, srcDir, apiUrl, token, log } = args;
-  const dest = path11.join(root, ASSETS_DEST, "avatar.vrm");
-  await fs10.mkdir(path11.dirname(dest), { recursive: true });
+  const dest = path12.join(root, ASSETS_DEST, "avatar.vrm");
+  await fs11.mkdir(path12.dirname(dest), { recursive: true });
   if (token) {
     try {
-      const res = await fetch(`${apiUrl}/api/avatars/me`, {
+      const res = await apiFetch(`${apiUrl}/api/avatars/me`, {
         headers: { Authorization: `Bearer ${token}` }
       });
       if (res.ok) {
@@ -1841,7 +2037,7 @@ async function installOwnerAvatar(args) {
           const vrmRes = await fetch(me.vrmUrl);
           if (vrmRes.ok) {
             const buf = Buffer.from(await vrmRes.arrayBuffer());
-            await fs10.writeFile(dest, buf);
+            await fs11.writeFile(dest, buf);
             log.dim(`  public/assets/avatar.vrm (your avatar \u2014 ${(buf.length / 1e6).toFixed(1)} MB)`);
             return;
           }
@@ -1852,14 +2048,14 @@ async function installOwnerAvatar(args) {
       log.dim("  avatar fetch failed (offline?); using the bundled default.");
     }
   }
-  await fs10.copyFile(path11.join(srcDir, "assets", "default-avatar.vrm"), dest);
+  await fs11.copyFile(path12.join(srcDir, "assets", "default-avatar.vrm"), dest);
   log.dim(
     token ? "  public/assets/avatar.vrm (bundled default)" : "  public/assets/avatar.vrm (bundled default \u2014 sign in and re-run for your own)"
   );
 }
 async function exists2(p) {
   try {
-    await fs10.access(p);
+    await fs11.access(p);
     return true;
   } catch {
     return false;
@@ -1873,7 +2069,7 @@ async function runExplore(opts) {
   const apiUrl = getApiUrl(opts.apiUrl);
   let res;
   try {
-    res = await fetch(`${apiUrl}/api/gallery/search-corpus?curated=1`);
+    res = await apiFetch(`${apiUrl}/api/gallery/search-corpus?curated=1`);
   } catch {
     log.error("Couldn't reach Genex \u2014 please try again.");
     process.exitCode = 1;
@@ -1933,17 +2129,6 @@ function rank(items, query) {
 
 // src/index.ts
 var GEN_KINDS = /* @__PURE__ */ new Set(["model", "skybox", "sfx", "texture"]);
-function getVersion() {
-  try {
-    const here = path12.dirname(fileURLToPath2(import.meta.url));
-    const pkg = JSON.parse(
-      readFileSync(path12.resolve(here, "..", "package.json"), "utf8")
-    );
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
 var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize, and publish 3D games.
 
 ${c.bold("Usage")}
@@ -2206,43 +2391,50 @@ async function main() {
     return;
   }
   if (parsed.version) {
-    log.plain(getVersion());
+    log.plain(getCliVersion());
     return;
   }
   if (parsed.help || parsed.command === void 0) {
     log.plain(HELP);
     return;
   }
-  if (GEN_KINDS.has(parsed.command)) {
-    await runGenerate(parsed.command, {
-      ...parsed.options,
-      prompt: parsed.options.name
-    });
-    return;
-  }
-  switch (parsed.command) {
-    case "init":
-      await runInit(parsed.options);
-      break;
-    case "link":
-      await runLink(parsed.options);
-      break;
-    case "controller":
-      await runController({ ...parsed.options, kind: parsed.options.name });
-      break;
-    case "preview":
-      await runPreview(parsed.options);
-      break;
-    case "publish":
-      await runPublish(parsed.options);
-      break;
-    case "explore":
-      await runExplore({ ...parsed.options, query: parsed.options.name });
-      break;
-    default:
-      log.error(`Unknown command: ${parsed.command}`);
-      log.plain(`Run ${c.cyan("genex --help")} for usage.`);
-      process.exitCode = 1;
+  const updateLog = createLogger({ quiet: parsed.options.quiet });
+  if (parsed.command !== "init") await syncSkills(updateLog);
+  const updateCheck = startUpdateCheck();
+  try {
+    if (GEN_KINDS.has(parsed.command)) {
+      await runGenerate(parsed.command, {
+        ...parsed.options,
+        prompt: parsed.options.name
+      });
+      return;
+    }
+    switch (parsed.command) {
+      case "init":
+        await runInit(parsed.options);
+        break;
+      case "link":
+        await runLink(parsed.options);
+        break;
+      case "controller":
+        await runController({ ...parsed.options, kind: parsed.options.name });
+        break;
+      case "preview":
+        await runPreview(parsed.options);
+        break;
+      case "publish":
+        await runPublish(parsed.options);
+        break;
+      case "explore":
+        await runExplore({ ...parsed.options, query: parsed.options.name });
+        break;
+      default:
+        log.error(`Unknown command: ${parsed.command}`);
+        log.plain(`Run ${c.cyan("genex --help")} for usage.`);
+        process.exitCode = 1;
+    }
+  } finally {
+    await reportUpdateNudges(updateCheck, updateLog);
   }
 }
 main().catch((err) => {

package/package.json

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

package/templates/README.md

@@ -8,9 +8,9 @@ for making 3D games in the browser.
 Genex is built around agent superpowers for browser games: Three.js skills,
 one-click publishing, multiplayer-ready architecture, and team workflows.
 
-Files whose names start with `genex-` are managed by Genex: re-running
-`genex init` refreshes them to the latest version. Anything you add yourself is
-never touched.
+Files whose names start with `genex-` are managed by Genex: every `genex`
+command keeps them in sync with the installed CLI version automatically
+(re-running `genex init` does too). Anything you add yourself is never touched.
 
 - `skills/` - reusable Genex skills for 3D game creation.
 - `agents/` - example subagent definitions.

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

@@ -63,13 +63,18 @@ side — reads as broken at a glance.
 
 ## Load it into the scene
 
-Use Three.js `GLTFLoader` with the URL the command printed (R2 sends the right CORS
-headers, so cross-origin loading just works):
+Generated model GLBs are **meshopt-compressed** on the Genex servers before
+storage (same visuals, several times smaller — faster loads on every play).
+Wire the decoder once — it's harmless for uncompressed files — then use
+Three.js `GLTFLoader` with the URL the command printed (R2 sends the right
+CORS headers, so cross-origin loading just works):
 
 ```ts
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
 
 const loader = new GLTFLoader();
+loader.setMeshoptDecoder(MeshoptDecoder); // required for genex model GLBs
 // the URL `npx genex model` printed:
 const MODEL_URL = "https://assets.genex.technology/generations/<id>/model-glb";
 const gltf = await loader.loadAsync(MODEL_URL);

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

@@ -13,9 +13,9 @@ architecture, and team-ready workflows.
 
 `genex init` installs the Genex skills into **every coding agent it detects** —
 Claude Code (`~/.claude`), Codex (`~/.codex`), and Cursor (`~/.cursor`) — so the
-same skills are available whichever agent you build with. Re-running `init`
-always refreshes the genex-owned skills to the latest version (your own files
-are never touched).
+same skills are available whichever agent you build with. After that, every
+`genex` command keeps the genex-owned skills in sync with the installed CLI
+automatically (re-running `init` does too); your own files are never touched.
 
 - **skills/** - reusable Genex skills for 3D browser-game work (all agents).
 - **agents/** - example subagent definitions (Claude Code).
@@ -110,6 +110,13 @@ 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`).
 
+## Staying up to date
+
+Genex commands print an update nudge when a newer package exists
+(`⬆ Genex … available — run: …`). Follow `$genex-updates`: apply the printed
+command at a safe moment (never mid-task), then tell the user what changed.
+Skills need no action — they sync automatically on every `genex` command.
+
 ## Re-running setup
 
 Safe to run any time — genex-owned skills are refreshed to the latest version,

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

@@ -273,10 +273,13 @@ and a gate capture is NOT visual evidence.
 - 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, hand it off plainly: "open your draft page
-  and tell me what you see" — the owner's view is the real check. Once the
-  game is **published**, any fresh browser gets in as a guest, so your own
-  test browser works again for full visual validation.
+- 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.
 
 ## Checklist
 

package/templates/skills/genex-threejs-vehicle-controllers/references/car.md

@@ -96,21 +96,32 @@ treat the player as drivable ground.
 ## Custom generated bodies (`npx genex model`)
 
 A generated GLB works as the visual chassis — add it under `car.chassisObject`
-exactly like `carBodyMesh` above. Two rules keep it looking right:
-
-- **Generate the body WITHOUT wheels** — prompt it explicitly, e.g.
-  `npx genex model "red sports car body, no wheels"`. Wheels are code-driven:
-  each `ShapeCastWheel` steers, bounces, and spins whatever sits in
-  `wheel.modelObject`, so wheels baked into the body mesh stand frozen while
-  the invisible real wheels do the work — it reads as a broken car.
-- **Wheel-less is a valid look.** The suspension shapecasts need no wheel
-  visuals at all: a body with empty `modelObject`s sits and drives correctly.
-  Add per-corner wheel meshes (the cylinder in the wiring above, or a small
-  generated wheel model) only when you want wheels visible.
-
-Scale and center the GLB to hug the chassis colliders, and mind the
-+Z-forward convention when orienting it. Collider strategy for GLBs lives in
-`$genex-threejs-physics-rapier`.
+exactly like `carBodyMesh` above. Generated car models arrive as ONE mesh with
+the wheels baked in (prompting "no wheels" does not reliably remove them) —
+that is the expected input. Three rules make it read right:
+
+- **Never add visible wheel meshes to a generated body.** Leave every
+  `wheel.modelObject` empty — the suspension shapecasts drive the body
+  correctly with no wheel visuals, and code wheels next to the baked-in ones
+  read as a six-wheeled monster truck. The baked wheels simply don't spin;
+  at game speed that's the accepted look. (The cylinder wheels in the wiring
+  above are for hand-built box-chassis cars only.)
+- **Fit the invisible wheels to the body, not the body to the preset.**
+  Scale the GLB by LENGTH toward the preset's footprint (body length ≈
+  wheelbase + 1.5 m; race-grip/muscle-drift wheelbase is 3.0 m, track
+  1.7 m) — never a min-axis bounding-box fit, which shrinks the body and
+  strands the wheel slots outside its silhouette. Then move the wheel slots
+  to the model's own wheel arches (from its bounding box: axles at roughly
+  ±0.33 × body length on z, x at ±(half width − 0.1)) and set
+  `rayShapeR`/`wheelModelRadius` so the body STANDS on the road — baked
+  tires touching the ground, nothing floating.
+- **Verify the facing before anything else.** +Z must be the nose:
+  generation regularly comes back rotated 180° (the classic "car drives
+  backward" bug) — apply the one-time yaw wrapper from `$genex-ai-model`,
+  then confirm in your smoke test that the NOSE leads under forward input.
+
+Center the GLB over the chassis colliders. Collider strategy for GLBs lives
+in `$genex-threejs-physics-rapier`.
 
 ## Presets and provenance
 

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

@@ -41,6 +41,12 @@ this is the whole acceptance gate, and it is also the minimum for every game:
    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
    fix.
+5. Vehicles get one extra pass: drive forward once and confirm the NOSE
+   leads (a 180° body is this bug's favorite disguise), and check the body
+   stands ON the road with its wheels inside the silhouette — a body
+   floating above detached wheels means the model was box-fit against the
+   preset's wheelbase (the vehicle skill's "Custom generated bodies" rules
+   fix it).
 
 Everything deeper (baselines, seed sweeps, mosaics, budgets) belongs to
 visual-system work — the sequence above.

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

@@ -0,0 +1,66 @@
+---
+name: genex-updates
+description: Apply Genex platform updates safely. Use when a genex command prints an update nudge ("⬆ Genex … available — run: …"), a skills-refresh line ("🔄 Genex skills updated"), or an update-required refusal (HTTP 426, cli_update_required), or when the user asks about updating Genex packages.
+---
+
+# Genex Updates — apply platform updates at safe moments
+
+Genex ships improvements continuously. The `genex` CLI tells you when something
+is stale; you (the agent) apply the update at the right moment and tell the
+user what happened. The user never manages versions themselves.
+
+## The three signals in `genex` output
+
+| Line | Meaning | What you do |
+| -- | -- | -- |
+| `🔄 Genex skills updated to X.Y.Z` | Skills were auto-refreshed to match the installed CLI. | Nothing — informational. Skills stay in sync on their own. |
+| `⬆ Genex <package> X.Y.Z available (installed A.B.C) — run: <command>` | A newer npm package exists. | Run the printed command at a **safe moment** (below), then tell the user. |
+| `✗ … below the minimum supported version … Update now — run: <command>` | The API refuses this CLI version (HTTP 426, `cli_update_required`). | Run the printed command **now**, then re-run the refused genex command. |
+
+## Safe moments — when to apply a nudge
+
+Update when nothing is in flight:
+
+- at the start of a session, before you begin the user's task;
+- between tasks, after the current change is finished and working;
+- right before a `genex preview`/`publish` you have **not** started yet.
+
+Never mid-task: not during a build or deploy, not halfway through a code
+change, not while the user is waiting for something else. A nudge is a
+suggestion — if now is not a safe moment, finish first; the nudge reappears on
+the next command. (The 426 refusal is the exception: nothing works until you
+update, so update immediately.)
+
+## How to apply
+
+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 @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)
+```
+
+Skills refresh automatically on the next `genex` command after a CLI update —
+no extra step. Then tell the user in one short line what changed and why it
+matters, e.g. "I also updated Genex to 0.22 — skills and SDK refreshed." For
+what's new, check the package page: https://www.npmjs.com/package/@genex-ai/cli-demo
+
+## Hard rules
+
+- **Never touch game code as part of an update.** Everything in the game's
+  `src/` — including vendored controller code in `src/controllers/` — is
+  user-owned and may carry customizations. Updates never overwrite it. If a
+  newer controller exists you may *mention* that `genex controller <type>
+  --force` re-vendors it, but run that only when the user explicitly opts in
+  (it overwrites their changes).
+- **Never update silently.** `npm i …@latest` changes `package.json` — that is
+  the sanctioned path, but always say in chat that you did it.
+- **Never downgrade**, and never pin to an old version to "fix" an error —
+  report the error instead.
+- **Verify after updating**: the game should still build/run. If it does not,
+  say exactly what broke rather than quietly reverting.
+- If `npm i` fails (offline, registry down), say so and continue on the
+  current version — everything keeps working, and the nudge will reappear.
+- A published game is never affected by any of this: its live bundle is frozen
+  and keeps working regardless of local package versions.