@genex-ai/cli-demo 0.2.0 → 0.4.0

package/README.md

@@ -5,18 +5,29 @@ This is the `cli` app of the [genex monorepo](../../README.md).
 
 ```bash
 genex init <name>          # authorize + create the draft project
-genex publish              # push the built game + list it in the gallery
+genex preview              # build + push to the hosted draft URL (unlisted)
+genex publish              # build + push, then list the game in the gallery
 genex model "<prompt>"     # generate a 3D model  → assets/models/
 genex skybox "<prompt>"    # generate a 360° sky  → assets/skybox/
 genex sfx "<prompt>"       # generate a sound fx  → assets/sfx/
 genex texture "<prompt>"   # generate a texture   → assets/textures/
 ```
 
+> **Invoking it.** First-time setup runs via `npx @genex-ai/cli-demo@latest init`.
+> The scaffold then adds `@genex-ai/cli-demo` as a project dev dependency, so the
+> rest run as **`npx genex <cmd>`** from the project dir (resolving to this CLI,
+> never a different global `genex`). `genex <cmd>` works too if you install it
+> globally. The bare command forms below name the command; prefix with `npx` to run.
+
 `genex init` does four things:
 
-1. **Scaffolds your workspace** — copies the bundled templates (skills, agents,
-   commands) into `~/.claude`, *merging* into whatever is already there. Existing
-   files are **never overwritten**.
+1. **Installs the skills for your coding agents** — copies the bundled templates
+   into every agent it detects: Claude Code (`~/.claude`, full set incl.
+   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`.
 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;
@@ -27,11 +38,21 @@ genex texture "<prompt>"   # generate a texture   → assets/textures/
    `sshUrl`, urls) in `./.genex/project.json`. The game shows up in your
    dashboard's **My games** immediately.
 
-`genex publish` reads that metadata, pushes the built game to GitHub over the
-deploy key (best-effort — `index.html` must be at the repo root), then flips the
-project to **published** so it appears in the public gallery. `git push` (updates
-the live Pages site) and the gallery flag are independent; `--no-push` skips the
-push. Defaults: API `https://demo-api.glotech.world`, auth site
+`genex preview` and `genex publish` share a build-aware deploy core: each runs
+`npm run build` (when the project has a build script), then pushes the built
+`dist/` **as the repo root** over the deploy key — no copying files or swapping
+`index.html` by hand. A `.nojekyll` marker is written so GitHub Pages serves the
+bundle verbatim, and the deploy never stages `genex_key` (the private key can't
+leak). Pass `--no-build` to deploy whatever is already built.
+
+- **`genex preview`** pushes the current build to the project's hosted draft URL
+  (`https://<user>.github.io/<slug>/`) without listing it publicly — re-run it
+  after each change to update the shareable draft.
+- **`genex publish`** does the same deploy, then flips the project to
+  **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.
 
@@ -77,11 +98,12 @@ pnpm --filter @genex-ai/cli-demo start init
 Once published, end users run it with `npx`:
 
 ```bash
-npx @genex-ai/cli-demo init
+npx @genex-ai/cli-demo@latest init
 ```
 
-> Requires **Node ≥ 24** (the CLI is executed as TypeScript via Node's native
-> type stripping, matching the rest of the monorepo).
+> The published package ships a bundled `dist/` (built with tsup) and runs on
+> **Node ≥ 20**. Running from *source* in the monorepo needs **Node ≥ 24** (the
+> source is executed as TypeScript via Node's native type stripping).
 
 ## Usage
 
@@ -89,9 +111,10 @@ npx @genex-ai/cli-demo init
 genex init [options]
 
 Options
-  --dir <path>         Destination workspace (default: ~/.claude)
-  --env <path>         Path to the .env file to write (default: ./.env)
-  --auth-url <url>     Override the auth site (default: https://genex.dev)
+  --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)
   --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)
@@ -122,8 +145,8 @@ genex init --auth-url http://localhost:3000
 
 The auth site URL is a single configurable value:
 
-- **Default:** `https://genex.dev` (the `DEFAULT_AUTH_URL` constant in
-  [`src/config.ts`](src/config.ts)).
+- **Default:** `https://demo-web.glotech.world` (the `DEFAULT_AUTH_URL` constant
+  in [`src/config.ts`](src/config.ts)).
 - **Override at runtime:** set `GENEX_AUTH_URL`, or pass `--auth-url`.
 
 ```bash
@@ -168,8 +191,8 @@ The CLI uses a loopback-redirect flow (the same pattern as `gh auth login` and
    > the exact `state` it received. A missing or mismatched `state` is rejected
    > (CSRF protection).
 
-3. The CLI verifies `state`, writes `GENEX_TOKEN=<TOKEN>` to `.env`, and shows a
-   success page in the browser.
+3. The CLI verifies `state`, writes `GENEX_TOKEN=<TOKEN>` to `~/.genex/env`, and
+   shows a success page in the browser.
 
 If the browser can't be opened, the URL is printed and — when run in an
 interactive terminal — a pasted token is also accepted.
@@ -236,9 +259,9 @@ templates/              copied into ~/.claude by `genex init`
 
 ## Publishing
 
-The package ships its TypeScript source (no bundle); consumers run it on
-Node ≥ 24. The published tarball includes only `src/`, `templates/`, `README.md`,
-and `LICENSE` (see the `files` field in `package.json`).
+The package ships a bundled `dist/` (built with tsup via `prepack`); consumers
+run it on Node ≥ 20. The published tarball includes `dist/`, `templates/`,
+`README.md`, and `LICENSE` (see the `files` field in `package.json`).
 
 ```bash
 pnpm --filter @genex-ai/cli-demo publish --access public

package/dist/index.js

@@ -9,6 +9,7 @@ import { fileURLToPath as fileURLToPath2 } from "url";
 import path6 from "path";
 
 // src/config.ts
+import fs from "fs";
 import os from "os";
 import path from "path";
 import { fileURLToPath } from "url";
@@ -42,45 +43,77 @@ function getTemplatesDir() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   return path.resolve(here, "..", "templates");
 }
-function getClaudeDir(override) {
-  if (override) return path.resolve(override);
-  return path.join(os.homedir(), ".claude");
+var KNOWN_AGENTS = {
+  claude: { label: "Claude Code", dirName: ".claude", full: true },
+  codex: { label: "Codex", dirName: ".codex", full: false },
+  cursor: { label: "Cursor", dirName: ".cursor", full: false }
+};
+var KNOWN_AGENT_IDS = Object.keys(KNOWN_AGENTS);
+function resolveAgentTargets(opts = {}) {
+  if (opts.dir) {
+    return [{ id: "custom", label: "workspace", baseDir: path.resolve(opts.dir), full: true }];
+  }
+  const home = os.homedir();
+  let ids;
+  if (opts.agents && opts.agents.length > 0) {
+    ids = opts.agents.filter((id) => KNOWN_AGENTS[id]);
+  } else {
+    ids = KNOWN_AGENT_IDS.filter((id) => isDir(path.join(home, KNOWN_AGENTS[id].dirName)));
+    if (ids.length === 0) ids = ["claude"];
+  }
+  return ids.map((id) => {
+    const def = KNOWN_AGENTS[id];
+    return { id, label: def.label, baseDir: path.join(home, def.dirName), full: def.full };
+  });
+}
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
 }
 
 // src/lib/copy-templates.ts
-import fs from "fs/promises";
+import fs2 from "fs/promises";
 import path2 from "path";
+function isGenexManaged(rel) {
+  return rel.split(path2.sep).some((seg) => seg.startsWith("genex"));
+}
 async function copyTemplates(srcDir, destDir, opts = {}) {
-  const result = { copied: [], skipped: [] };
+  const result = { copied: [], updated: [], skipped: [] };
   await walk(srcDir, srcDir, destDir, opts, result);
   return result;
 }
 async function walk(rootSrc, src, dest, opts, result) {
-  const entries = await fs.readdir(src, { withFileTypes: true });
+  const entries = await fs2.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path2.join(src, entry.name);
     const destPath = path2.join(dest, entry.name);
     const rel = path2.relative(rootSrc, srcPath);
     if (entry.isDirectory()) {
-      await fs.mkdir(destPath, { recursive: true });
+      await fs2.mkdir(destPath, { recursive: true });
       await walk(rootSrc, srcPath, destPath, opts, result);
       continue;
     }
     if (!entry.isFile()) {
       continue;
     }
-    if (!opts.force && await exists(destPath)) {
+    const present = await exists(destPath);
+    const mayOverwrite = opts.force || isGenexManaged(rel);
+    if (present && !mayOverwrite) {
       result.skipped.push(rel);
       continue;
     }
-    await fs.mkdir(path2.dirname(destPath), { recursive: true });
-    await fs.copyFile(srcPath, destPath);
+    await fs2.mkdir(path2.dirname(destPath), { recursive: true });
+    await fs2.copyFile(srcPath, destPath);
     result.copied.push(rel);
+    if (present) result.updated.push(rel);
   }
 }
 async function exists(p) {
   try {
-    await fs.access(p);
+    await fs2.access(p);
     return true;
   } catch {
     return false;
@@ -396,7 +429,7 @@ async function createDraftProject(opts) {
       return null;
     }
     log.success(`Created project ${c.cyan(project.slug)}.`);
-    if (project.playUrl) log.dim(`  play (after publish): ${project.playUrl}`);
+    if (project.playUrl) log.dim(`  play (after preview/publish): ${project.playUrl}`);
     log.dim(`  dashboard: ${dashboardUrl}/dashboard`);
     return {
       id: project.id,
@@ -416,7 +449,7 @@ function randomSuffix() {
 }
 
 // src/lib/ssh.ts
-import fs2 from "fs/promises";
+import fs3 from "fs/promises";
 import path3 from "path";
 import { spawn as spawn2 } from "child_process";
 var KEY_NAME = "genex_key";
@@ -424,7 +457,7 @@ async function generateSshKeypair(dir, log) {
   const keyPath = path3.join(dir, KEY_NAME);
   const pubPath = `${keyPath}.pub`;
   try {
-    const existing = (await fs2.readFile(pubPath, "utf8")).trim();
+    const existing = (await fs3.readFile(pubPath, "utf8")).trim();
     if (existing) {
       log.dim(`Reusing existing deploy key (${KEY_NAME}).`);
       return { publicKey: existing };
@@ -435,12 +468,12 @@ async function generateSshKeypair(dir, log) {
   const ok = await runSshKeygen(keyPath, log);
   if (!ok) return null;
   try {
-    const pub = (await fs2.readFile(pubPath, "utf8")).trim();
+    const pub = (await fs3.readFile(pubPath, "utf8")).trim();
     if (!pub) {
       log.warn("ssh-keygen produced no public key.");
       return null;
     }
-    await fs2.chmod(keyPath, 384).catch(() => {
+    await fs3.chmod(keyPath, 384).catch(() => {
     });
     return { publicKey: pub };
   } catch (err) {
@@ -473,7 +506,7 @@ async function writeGitignore(dir, log) {
   const file = path3.join(dir, ".gitignore");
   let content = "";
   try {
-    content = await fs2.readFile(file, "utf8");
+    content = await fs3.readFile(file, "utf8");
   } catch {
   }
   const present = new Set(content.split("\n").map((l) => l.trim()));
@@ -483,23 +516,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 fs2.writeFile(file, next);
+  await fs3.writeFile(file, next);
   log.dim(`Updated .gitignore (${toAdd.join(", ")}).`);
 }
 
 // src/lib/store.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import path5 from "path";
 
 // src/lib/env.ts
-import fs3 from "fs/promises";
+import fs4 from "fs/promises";
 import path4 from "path";
 import { spawn as spawn3 } from "child_process";
 async function writeEnvVar(envPath, key, value) {
   let content = "";
   let existed = false;
   try {
-    content = await fs3.readFile(envPath, "utf8");
+    content = await fs4.readFile(envPath, "utf8");
     existed = true;
   } catch {
   }
@@ -519,14 +552,14 @@ async function writeEnvVar(envPath, key, value) {
     next = prefix + assignment + "\n";
     mode = existed ? "appended" : "created";
   }
-  await fs3.mkdir(path4.dirname(envPath), { recursive: true });
-  await fs3.writeFile(envPath, next, { mode: 384 });
+  await fs4.mkdir(path4.dirname(envPath), { recursive: true });
+  await fs4.writeFile(envPath, next, { mode: 384 });
   await restrictFilePermissions(envPath);
   return { mode, path: envPath };
 }
 async function restrictFilePermissions(filePath) {
   if (process.platform !== "win32") {
-    await fs3.chmod(filePath, 384).catch(() => {
+    await fs4.chmod(filePath, 384).catch(() => {
     });
     return;
   }
@@ -575,7 +608,7 @@ async function readUserToken(envPath) {
 async function readTokenFromFile(file) {
   let content;
   try {
-    content = await fs4.readFile(file, "utf8");
+    content = await fs5.readFile(file, "utf8");
   } catch {
     return null;
   }
@@ -591,7 +624,7 @@ function stripQuotes(v) {
 }
 async function readProject(cwd = process.cwd()) {
   try {
-    const raw = await fs4.readFile(getProjectMetadataPath(cwd), "utf8");
+    const raw = await fs5.readFile(getProjectMetadataPath(cwd), "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -599,9 +632,9 @@ async function readProject(cwd = process.cwd()) {
 }
 async function writeProject(meta, cwd = process.cwd()) {
   const file = getProjectMetadataPath(cwd);
-  await fs4.mkdir(path5.dirname(file), { recursive: true });
-  await fs4.writeFile(file, JSON.stringify(meta, null, 2) + "\n", { mode: 384 });
-  await fs4.chmod(file, 384).catch(() => {
+  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(() => {
   });
   return { path: file };
 }
@@ -631,24 +664,24 @@ async function runInit(opts) {
   log.plain(c.bold("genex init"));
   log.plain("");
   const templatesDir = getTemplatesDir();
-  const claudeDir = getClaudeDir(opts.dir);
-  log.step(`Setting up your workspace at ${c.cyan(claudeDir)}`);
-  const { copied, skipped } = await copyTemplates(templatesDir, claudeDir, {
-    force: opts.force
-  });
-  if (copied.length > 0) {
-    log.success(`Added ${copied.length} file${copied.length === 1 ? "" : "s"}.`);
-    for (const f of copied) log.dim(`  + ${f}`);
-  }
-  if (skipped.length > 0) {
-    log.info(
-      `Left ${skipped.length} existing file${skipped.length === 1 ? "" : "s"} untouched.`
-    );
-    for (const f of skipped) log.dim(`  = ${f}`);
-  }
-  if (copied.length === 0 && skipped.length === 0) {
-    log.info("No template files to install.");
+  const targets = resolveAgentTargets({ dir: opts.dir, agents: opts.agents });
+  log.step(
+    `Installing Genex skills for: ${targets.map((t) => c.cyan(t.label)).join(", ")}`
+  );
+  let totalNew = 0;
+  let totalUpdated = 0;
+  for (const t of targets) {
+    const src = t.full ? templatesDir : path6.join(templatesDir, "skills");
+    const dest = t.full ? t.baseDir : path6.join(t.baseDir, "skills");
+    const { copied, updated } = await copyTemplates(src, dest, { force: opts.force });
+    const added = copied.length - updated.length;
+    totalNew += added;
+    totalUpdated += updated.length;
+    log.dim(`  ${t.label}: ${added} added, ${updated.length} refreshed \u2192 ${dest}`);
   }
+  log.success(
+    `Skills ready (${totalNew} added, ${totalUpdated} refreshed across ${targets.length} agent${targets.length === 1 ? "" : "s"}).`
+  );
   log.plain("");
   if (opts.noAuth) {
     log.info("Skipping authorization (--no-auth).");
@@ -701,9 +734,10 @@ async function runInit(opts) {
   log.success("All set. \u{1F680}");
 }
 
-// src/commands/publish.ts
+// src/lib/deploy.ts
 import { spawn as spawn4 } from "child_process";
-import fs5 from "fs/promises";
+import fs6 from "fs/promises";
+import os2 from "os";
 import path7 from "path";
 function run(cmd, args, env) {
   return new Promise((resolve) => {
@@ -722,6 +756,113 @@ function run(cmd, args, env) {
     child.on("close", (code2) => resolve({ code: code2 ?? -1, out, err }));
   });
 }
+async function deployGame(sshUrl, opts, log) {
+  const cwd = process.cwd();
+  if (!opts.noBuild && await hasBuildScript(cwd)) {
+    log.step("Building the production bundle\u2026");
+    const built = await run("npm", ["run", "build"]);
+    if (built.code !== 0) {
+      log.error("Build failed \u2014 your game was NOT deployed.");
+      const tail = (built.err || built.out).trim().split("\n").slice(-12).join("\n");
+      if (tail) log.dim(tail);
+      return false;
+    }
+    log.success("Built.");
+  }
+  const distDir = path7.join(cwd, "dist");
+  const siteDir = await isDir2(distDir) ? distDir : cwd;
+  if (siteDir === cwd) {
+    await writeGitignore(cwd, log);
+  }
+  const rel = path7.relative(cwd, siteDir) || ".";
+  try {
+    await fs6.access(path7.join(siteDir, "index.html"));
+  } catch {
+    log.warn(`No index.html in ${rel} \u2014 GitHub Pages needs one to serve the game.`);
+  }
+  await warnIfAbsolutePaths(siteDir, log);
+  await fs6.writeFile(path7.join(siteDir, ".nojekyll"), "");
+  const keyPath = path7.resolve(cwd, KEY_NAME);
+  if (!await fileExists(keyPath)) {
+    log.warn(`No deploy key (${KEY_NAME}) here \u2014 run \`genex init\` in this folder first.`);
+    return false;
+  }
+  const gitDir = await fs6.mkdtemp(path7.join(os2.tmpdir(), "genex-deploy-"));
+  const gitEnv = { GIT_DIR: gitDir, GIT_WORK_TREE: siteDir };
+  try {
+    if ((await run("git", ["init", "-q"], gitEnv)).code !== 0) {
+      log.warn("git init failed \u2014 the game was not pushed.");
+      return false;
+    }
+    await run("git", ["add", "-A"], gitEnv);
+    const tracked = await run("git", ["ls-files"], gitEnv);
+    if (/(^|\/)genex_key(\.pub)?$/m.test(tracked.out)) {
+      log.error(`Refusing to deploy: ${KEY_NAME} is staged. Add it to .gitignore and retry.`);
+      return false;
+    }
+    const commit = await run(
+      "git",
+      ["-c", "user.email=agent@genex.local", "-c", "user.name=genex", "commit", "-q", "-m", "build"],
+      gitEnv
+    );
+    if (commit.code !== 0 && !/nothing to commit/i.test(commit.out + commit.err)) {
+      log.warn("Nothing to commit \u2014 the build produced no files.");
+      return false;
+    }
+    log.step("Pushing your game over SSH\u2026");
+    const push = await run("git", ["push", "-q", sshUrl, "+HEAD:main"], {
+      ...gitEnv,
+      GIT_SSH_COMMAND: `ssh -i ${keyPath} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
+    });
+    if (push.code === 0) {
+      log.success("Pushed.");
+      return true;
+    }
+    log.warn("git push failed \u2014 your live game was NOT updated.");
+    const tail = push.err.trim().split("\n").slice(-2).join(" ");
+    if (tail) log.dim(`  ${tail}`);
+    return false;
+  } finally {
+    await fs6.rm(gitDir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function hasBuildScript(cwd) {
+  try {
+    const pkg = JSON.parse(await fs6.readFile(path7.join(cwd, "package.json"), "utf8"));
+    return Boolean(pkg.scripts?.build);
+  } catch {
+    return false;
+  }
+}
+async function isDir2(p) {
+  try {
+    return (await fs6.stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function fileExists(p) {
+  try {
+    await fs6.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function warnIfAbsolutePaths(siteDir, log) {
+  let html;
+  try {
+    html = await fs6.readFile(path7.join(siteDir, "index.html"), "utf8");
+  } catch {
+    return;
+  }
+  if (/(?:src|href)="\/(?!\/)/.test(html)) {
+    log.warn("Built index.html uses absolute paths \u2014 set `base: './'` in vite.config so assets load under the Pages subpath.");
+  }
+}
+
+// src/commands/publish.ts
 async function runPublish(opts) {
   const log = createLogger({ quiet: opts.quiet });
   log.plain(c.bold("genex publish"));
@@ -741,11 +882,11 @@ async function runPublish(opts) {
   const apiUrl = getApiUrl(opts.apiUrl ?? meta.apiUrl);
   let pushed = null;
   if (opts.noPush) {
-    log.info("Skipping git push (--no-push).");
+    log.info("Skipping build + git push (--no-push).");
   } else {
-    pushed = await pushGame(meta.sshUrl, log);
+    pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
   }
-  log.step("Publishing to the gallery\u2026");
+  log.step("Listing it in the gallery\u2026");
   let res;
   try {
     const body = {};
@@ -771,7 +912,7 @@ async function runPublish(opts) {
     log.warn(
       "Listed in the gallery, but the game wasn't pushed \u2014 the play URL won't work until the push succeeds."
     );
-    log.dim("  Fix the push error above and re-run `genex publish`.");
+    log.dim("  Fix the error above and re-run `genex publish`.");
   } else {
     log.success("Published. \u{1F389}");
   }
@@ -780,44 +921,37 @@ async function runPublish(opts) {
     if (pushed === true) log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push.)");
   }
 }
-async function pushGame(sshUrl, log) {
-  try {
-    await fs5.access(path7.join(process.cwd(), "index.html"));
-  } catch {
-    log.warn("No index.html at the project root \u2014 GitHub Pages needs one to serve the game.");
-  }
-  const isRepo = (await run("git", ["rev-parse", "--git-dir"])).code === 0;
-  if (!isRepo) {
-    log.step("Initializing git\u2026");
-    if ((await run("git", ["init"])).code !== 0) {
-      log.warn("git init failed \u2014 the game was not pushed (use `genex publish --no-push` to silence).");
-      return false;
-    }
+
+// src/commands/preview.ts
+async function runPreview(opts) {
+  const log = createLogger({ quiet: opts.quiet });
+  log.plain(c.bold("genex preview"));
+  log.plain("");
+  const meta = await readProject();
+  if (!meta) {
+    log.error("No genex project here. Run `genex init` in this directory first.");
+    process.exitCode = 1;
+    return;
   }
-  await run("git", ["add", "-A"]);
-  const commit = await run("git", ["commit", "-m", "build"]);
-  if (commit.code !== 0 && !/nothing to commit/i.test(commit.out + commit.err)) {
-    log.dim("  (no new commit to push)");
+  const pushed = await deployGame(meta.sshUrl, { noBuild: opts.noBuild }, log);
+  log.plain("");
+  if (!pushed) {
+    log.warn("Preview not updated \u2014 see the error above.");
+    process.exitCode = 1;
+    return;
   }
-  log.step("Pushing your game over SSH\u2026");
-  const push = await run("git", ["push", sshUrl, "+HEAD:main"], {
-    GIT_SSH_COMMAND: `ssh -i ./${KEY_NAME} -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new`
-  });
-  if (push.code === 0) {
-    log.success("Pushed to main.");
-    return true;
+  log.success("Preview deployed. \u{1F310}");
+  if (meta.playUrl) {
+    log.dim(`  ${meta.playUrl}`);
+    log.dim("  (GitHub Pages rebuilds ~30\u201390s after a push; it stays an unlisted draft until you publish.)");
   }
-  log.warn("git push failed \u2014 your live game was NOT updated.");
-  const tail = push.err.trim().split("\n").slice(-2).join(" ");
-  if (tail) log.dim(`  ${tail}`);
-  return false;
 }
 
 // src/commands/generate.ts
 import path9 from "path";
 
 // src/lib/assets.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import path8 from "path";
 function slugify(input) {
   const s = input.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 50).replace(/-+$/g, "");
@@ -827,8 +961,8 @@ async function downloadToFile(url, dest, headers) {
   const res = await fetch(url, { headers });
   if (!res.ok) throw new Error(`download failed (HTTP ${res.status}) for ${url}`);
   const buf = Buffer.from(await res.arrayBuffer());
-  await fs6.mkdir(path8.dirname(dest), { recursive: true });
-  await fs6.writeFile(dest, buf);
+  await fs7.mkdir(path8.dirname(dest), { recursive: true });
+  await fs7.writeFile(dest, buf);
   return buf.byteLength;
 }
 
@@ -981,7 +1115,8 @@ var HELP = `${c.bold("genex")} \u2014 set up your ~/.claude workspace, authorize
 
 ${c.bold("Usage")}
   genex init [<name>] [options]      Scaffold + authorize + create the draft project.
-  genex publish [options]            Push the built game and list it in the gallery.
+  genex preview [options]            Build + push to the hosted draft URL (unlisted).
+  genex publish [options]            Build + push, then list the game in the gallery.
   genex model "<prompt>" [options]   Generate a 3D model (GLB) into ./assets/models.
   genex skybox "<prompt>" [options]  Generate a skybox (equirect) into ./assets/skybox.
   genex sfx "<prompt>" [options]     Generate a sound effect (mp3) into ./assets/sfx.
@@ -997,7 +1132,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.
-  --dir <path>         Destination workspace (default: ~/.claude).
+  --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).
   --auth-url <url>     Override the auth site (default: ${DEFAULT_AUTH_URL}).
   --api-url <url>      Override the API base URL (default: ${DEFAULT_API_URL}).
@@ -1006,11 +1142,12 @@ ${c.bold("Options for `init`")}
   --force              Overwrite existing files (default: never overwrite).
   --timeout <seconds>  How long to wait for the auth redirect (default: 300).
 
-${c.bold("Options for `publish`")}
-  --no-push            Skip the git push; only flip the gallery flag.
-  --title <title>      Gallery title.
-  --description <text> Gallery description.
-  --api-url <url>      Override the API base URL.
+${c.bold("Options for `preview` / `publish`")}
+  --no-build           Skip the build step; deploy whatever is already built.
+  --no-push            (publish) Skip build + push; only flip the gallery flag.
+  --title <title>      (publish) Gallery title.
+  --description <text> (publish) Gallery description.
+  --api-url <url>      (publish) Override the API base URL.
   --env <path>         Token env file (default: ~/.genex/env).
 
 ${c.bold("Global")}
@@ -1027,6 +1164,7 @@ ${c.bold("Environment")}
 ${c.bold("Examples")}
   genex init my-game
   genex init my-game --api-url http://localhost:3000 --auth-url http://localhost:5173
+  genex preview
   genex publish
   genex publish --no-push --title "My Game"
   genex model "weathered wooden barrel with iron bands"
@@ -1047,6 +1185,7 @@ function parseArgs(argv) {
     "--auth-url",
     "--api-url",
     "--colyseus-url",
+    "--agents",
     "--name",
     "--title",
     "--description",
@@ -1072,6 +1211,9 @@ function parseArgs(argv) {
       case "--no-push":
         parsed.options.noPush = true;
         break;
+      case "--no-build":
+        parsed.options.noBuild = true;
+        break;
       case "--no-wait":
         parsed.options.noWait = true;
         break;
@@ -1126,6 +1268,9 @@ function applyValueFlag(options, flag, value) {
     case "--colyseus-url":
       options.colyseusUrl = value;
       break;
+    case "--agents":
+      options.agents = value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+      break;
     case "--name":
       options.name = value;
       break;
@@ -1188,6 +1333,9 @@ async function main() {
     case "init":
       await runInit(parsed.options);
       break;
+    case "preview":
+      await runPreview(parsed.options);
+      break;
     case "publish":
       await runPublish(parsed.options);
       break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/cli-demo",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Set up your ~/.claude workspace, authorize, create a game project, generate AI assets, and publish (genex CLI).",
   "type": "module",
   "bin": {
@@ -15,6 +15,14 @@
   "engines": {
     "node": ">=20"
   },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "pnpm build",
+    "start": "node src/index.ts",
+    "dev": "node --watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts"
+  },
   "keywords": [
     "cli",
     "claude",
@@ -38,12 +46,5 @@
   "bugs": {
     "url": "https://github.com/me-ai-org/genex-demo/issues"
   },
-  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme",
-  "scripts": {
-    "build": "tsup",
-    "start": "node src/index.ts",
-    "dev": "node --watch src/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --test test/*.test.ts"
-  }
-}
+  "homepage": "https://github.com/me-ai-org/genex-demo/tree/main/apps/cli#readme"
+}

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-model
-description: Generate a real 3D model (GLB mesh) from a text prompt with `genex model`, then load it into the Three.js scene. Use when the user wants a specific prop, item, character, vehicle, building, or any concrete object as an actual mesh ("add a wooden barrel", "I need a spaceship", "generate a sword") rather than a procedurally-coded shape.
+description: Generate a real 3D model (GLB mesh) from a text prompt with `npx genex model`, then load it into the Three.js scene. Use when the user wants a specific prop, item, character, vehicle, building, or any concrete object as an actual mesh ("add a wooden barrel", "I need a spaceship", "generate a sword") rather than a procedurally-coded shape.
 ---
 
 # Genex AI · Model
@@ -9,7 +9,7 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
 
 ## When to use this vs. procedural geometry
 
-- **Use `genex model`** for a specific, recognizable object — a barrel, a chair, a
+- **Use `npx genex model`** for a specific, recognizable object — a barrel, a chair, a
   sword, a spaceship, an animal. You get a real textured mesh.
 - **Use `$genex-threejs-procedural-geometry`** for parametric/abstract shapes,
   terrain, or anything you want to generate in code (infinite variations, no files).
@@ -17,7 +17,7 @@ Turn a text prompt into a real, game-ready **GLB** and drop it into the project.
 ## Run
 
 ```bash
-genex model "<prompt>"
+npx genex model "<prompt>"
 ```
 
 Write a specific prompt — "weathered wooden barrel with rusted iron bands" beats
@@ -28,7 +28,7 @@ assets/models/<slug>.glb
 ```
 
 `<slug>` is derived from the prompt (e.g. `weathered-wooden-barrel.glb`). The file
-is **committed by `genex publish`**, so it ships inside your published game.
+is **committed by `npx genex publish`**, so it ships inside your published game.
 
 ## Load it into the scene
 
@@ -55,7 +55,7 @@ To place many copies, `model.clone()` per instance. For animated GLBs, drive
   (`/assets/...`) — GitHub Pages serves the game at a subpath.
 - Set `base: "./"` in `vite.config.ts` before `npm run build` (see the scaffold
   prompt's publish step).
-- Commit the `assets/` folder — `genex publish` pushes it with the game.
+- Commit the `assets/` folder — `npx genex publish` pushes it with the game.
 
 ## Options
 
@@ -65,6 +65,6 @@ To place many copies, `model.clone()` per instance. For animated GLBs, drive
 
 ## Troubleshooting
 
-- **"Not authorized"** — run `genex init` first (it writes your `GENEX_TOKEN`).
+- **"Not authorized"** — run `npx @genex-ai/cli-demo@latest init` first (it writes your `GENEX_TOKEN`).
 - **The mesh looks low-detail / wrong** — make the prompt more specific
   (materials, style, parts) and regenerate; each run is a fresh asset.

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-sfx
-description: Generate a real sound effect (mp3) from a text prompt with `genex sfx`, then play it in Three.js (positional or global audio). Use when the user wants a specific sound — a gunshot, footstep, pickup chime, explosion, engine hum, UI click, whoosh — triggered on a game event.
+description: Generate a real sound effect (mp3) from a text prompt with `npx genex sfx`, then play it in Three.js (positional or global audio). Use when the user wants a specific sound — a gunshot, footstep, pickup chime, explosion, engine hum, UI click, whoosh — triggered on a game event.
 ---
 
 # Genex AI · SFX
@@ -10,8 +10,8 @@ Turn a prompt into a real **mp3** sound effect and wire it to a game event.
 ## Run
 
 ```bash
-genex sfx "<prompt>"
-genex sfx "punchy laser zap, short and dry" --duration 2
+npx genex sfx "<prompt>"
+npx genex sfx "punchy laser zap, short and dry" --duration 2
 ```
 
 `--duration <sec>` (0.5–22) sets a target length; omit it to let the model pick.
@@ -21,7 +21,7 @@ Blocks until ready, then saves:
 assets/sfx/<slug>.mp3
 ```
 
-Committed by `genex publish`, so it ships with your game.
+Committed by `npx genex publish`, so it ships with your game.
 
 ## Play it in Three.js
 

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-skybox
-description: Generate a real 360° skybox (equirectangular panorama) from a text prompt with `genex skybox`, then load it as the scene background + environment lighting in Three.js. Use when the user wants a specific photoreal/painted sky or backdrop ("sunset over the ocean", "alien purple nebula", "foggy pine forest") as an image, rather than a procedural/shader sky.
+description: Generate a real 360° skybox (equirectangular panorama) from a text prompt with `npx genex skybox`, then load it as the scene background + environment lighting in Three.js. Use when the user wants a specific photoreal/painted sky or backdrop ("sunset over the ocean", "alien purple nebula", "foggy pine forest") as an image, rather than a procedural/shader sky.
 ---
 
 # Genex AI · Skybox
@@ -10,7 +10,7 @@ also lights it (image-based lighting).
 
 ## When to use this vs. a procedural sky
 
-- **Use `genex skybox`** for a specific, recognizable sky/backdrop you can
+- **Use `npx genex skybox`** for a specific, recognizable sky/backdrop you can
   describe — "golden hour over misty mountains", "stormy alien sky", "city at
   night". You get a real image.
 - **Use `$genex-threejs-atmosphere-aerial-perspective`** (or
@@ -20,7 +20,7 @@ also lights it (image-based lighting).
 ## Run
 
 ```bash
-genex skybox "<prompt>"
+npx genex skybox "<prompt>"
 ```
 
 Blocks until ready, then saves:
@@ -29,7 +29,7 @@ Blocks until ready, then saves:
 assets/skybox/<slug>.jpg
 ```
 
-The JPG is **committed by `genex publish`**, so it ships with your game.
+The JPG is **committed by `npx genex publish`**, so it ships with your game.
 
 ## Load it as background + environment
 
@@ -63,7 +63,7 @@ texture.dispose; // (dispose the PMREM source later if you stop using it)
 
 - Use the **relative** path `./assets/skybox/...` (GitHub Pages serves at a subpath).
 - `base: "./"` in `vite.config.ts` before `npm run build`.
-- Commit `assets/` — `genex publish` pushes it with the game.
+- Commit `assets/` — `npx genex publish` pushes it with the game.
 
 ## Troubleshooting
 

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

@@ -1,6 +1,6 @@
 ---
 name: genex-ai-texture
-description: Generate a real photoreal surface texture (PBR base-color image) from a text prompt with `genex texture`, then apply it as a tiling material on meshes or terrain in Three.js. Use `--terrain` for seamless ground. Use when the user wants a specific photoreal material on a surface ("rusty metal floor", "mossy cobblestone path", "grassy terrain") rather than a procedural/shader material.
+description: Generate a real photoreal surface texture (PBR base-color image) from a text prompt with `npx genex texture`, then apply it as a tiling material on meshes or terrain in Three.js. Use `--terrain` for seamless ground. Use when the user wants a specific photoreal material on a surface ("rusty metal floor", "mossy cobblestone path", "grassy terrain") rather than a procedural/shader material.
 ---
 
 # Genex AI · Texture
@@ -10,7 +10,7 @@ material on a primitive, a mesh, or terrain.
 
 ## When to use this vs. procedural materials
 
-- **Use `genex texture`** for a specific photoreal surface you can describe —
+- **Use `npx genex texture`** for a specific photoreal surface you can describe —
   "weathered Roman cobblestone", "cracked desert clay", "oak planks". You get a
   real raster image.
 - **Use `$genex-threejs-procedural-materials`** for stylized/abstract or
@@ -20,8 +20,8 @@ material on a primitive, a mesh, or terrain.
 ## Run
 
 ```bash
-genex texture "<prompt>"
-genex texture "lush green grass" --terrain    # seamless tiling for ground/terrain
+npx genex texture "<prompt>"
+npx genex texture "lush green grass" --terrain    # seamless tiling for ground/terrain
 ```
 
 Blocks until ready, then saves:
@@ -30,7 +30,7 @@ Blocks until ready, then saves:
 assets/textures/<slug>/basecolor.<ext>
 ```
 
-Committed by `genex publish`, so it ships with your game.
+Committed by `npx genex publish`, so it ships with your game.
 
 > **Scope:** v1 generates the **base-color (albedo)** map only. Normal / roughness
 > / AO are a planned follow-up — for now set sensible `roughness`/`metalness`

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

@@ -11,11 +11,15 @@ architecture, and team-ready workflows.
 
 ## What got installed
 
-Everything under `~/.claude`:
+`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).
 
-- **skills/** - reusable Genex skills for 3D browser-game work.
-- **agents/** - example subagent definitions.
-- **commands/** - example slash commands.
+- **skills/** - reusable Genex skills for 3D browser-game work (all agents).
+- **agents/** - example subagent definitions (Claude Code).
+- **commands/** - example slash commands (Claude Code).
 
 Start with `$genex-threejs-skill-router` for broad game or graphics requests.
 It routes the agent to focused skills for cameras, procedural geometry,
@@ -27,12 +31,15 @@ Beyond procedural code, Genex can generate **real, AI-made assets** from a promp
 and drop them into `./assets/` (committed when you publish):
 
 ```bash
-genex model "weathered wooden barrel"      # a 3D mesh (GLB)
-genex skybox "golden hour over mountains"  # a 360° sky + lighting
-genex sfx "punchy laser zap" --duration 2  # a sound effect (mp3)
-genex texture "mossy cobblestone" --terrain # a tiling surface texture
+npx genex model "weathered wooden barrel"      # a 3D mesh (GLB)
+npx genex skybox "golden hour over mountains"  # a 360° sky + lighting
+npx genex sfx "punchy laser zap" --duration 2  # a sound effect (mp3)
+npx genex texture "mossy cobblestone" --terrain # a tiling surface texture
 ```
 
+(Run them inside your project — the `@genex-ai/cli-demo` dev dependency makes
+`npx genex` resolve to the right CLI.)
+
 Each has a focused skill with the exact loader code — `$genex-ai-model`,
 `$genex-ai-skybox`, `$genex-ai-sfx`, `$genex-ai-texture`.
 
@@ -43,7 +50,7 @@ Your existing files were left untouched. `genex init` only adds what is missing.
 Safe to run any time; it never overwrites your files:
 
 ```bash
-npx genex init
+npx @genex-ai/cli-demo@latest init
 ```
 
 Use `--force` only if you intentionally want to overwrite installed templates
@@ -51,6 +58,6 @@ with the latest versions.
 
 ## Authorization
 
-`genex init` opens the auth site, then writes a `GENEX_TOKEN` into your
-project's `.env`. If the browser doesn't open, copy the printed URL into a
-browser manually to finish authorizing.
+`genex init` opens the auth site, then saves your token to `~/.genex/env`
+(reused across projects). If the browser doesn't open, copy the printed URL into
+a browser manually to finish authorizing.

package/templates/skills/genex-threejs-skill-router/SKILL.md

@@ -37,23 +37,25 @@ map, execution order, and acceptance gate.
 | render-target ownership, pass ordering, depth/normal/history signals | `$genex-threejs-image-pipeline` |
 | fixed-view captures, seed sweeps, browser and GPU evidence | `$genex-threejs-visual-validation` |
 
-## Real (AI-generated) assets — `genex` commands
+## Real (AI-generated) assets — `npx genex` commands
 
 When the user wants a **specific, recognizable asset** (a named object, a described
 sky, a particular sound or surface) rather than something authored in code, generate
-it with a `genex` command. Each drops a real file into `./assets/` (committed by
-`genex publish`), and its skill has the exact Three.js loader code.
+it with an `npx genex` command (run inside the project, where the `@genex-ai/cli-demo`
+dev dependency makes `genex` resolve to the right CLI). Each drops a real file into
+`./assets/` (committed by `npx genex publish`), and its skill has the exact Three.js
+loader code.
 
 | Work needed | Generate with | Skill |
 | --- | --- | --- |
-| a specific prop / item / character / vehicle as a real mesh | `genex model "<prompt>"` | `$genex-ai-model` |
-| a described 360° sky / backdrop + image-based lighting | `genex skybox "<prompt>"` | `$genex-ai-skybox` |
-| a specific sound effect tied to an event | `genex sfx "<prompt>"` | `$genex-ai-sfx` |
-| a photoreal surface/material on a mesh or terrain | `genex texture "<prompt>" [--terrain]` | `$genex-ai-texture` |
+| a specific prop / item / character / vehicle as a real mesh | `npx genex model "<prompt>"` | `$genex-ai-model` |
+| a described 360° sky / backdrop + image-based lighting | `npx genex skybox "<prompt>"` | `$genex-ai-skybox` |
+| a specific sound effect tied to an event | `npx genex sfx "<prompt>"` | `$genex-ai-sfx` |
+| a photoreal surface/material on a mesh or terrain | `npx genex texture "<prompt>" [--terrain]` | `$genex-ai-texture` |
 
 Prefer the **procedural** skills above for abstract/parametric/animated systems
 (geometry, materials, sky, water, VFX) — no files, infinite variation. Prefer the
-**`genex` generators** for concrete, describable, photoreal assets. They complement
+**`npx genex` generators** for concrete, describable, photoreal assets. They complement
 each other.
 
 ## Routing rules