@forgeax/game 0.2.0 → 0.2.2

package/README.md

@@ -22,17 +22,25 @@ externalizes it from the Game bundle.
 
 ## Install
 
-Configure one client (this can run from any empty directory):
+### New client setup
+
+Run this once per machine to add the ForgeaX MCP server to the selected agent client.
 
 ```bash
-npx -y -p @forgeax/game forgeax-game install --ide codex
-npx -y -p @forgeax/game forgeax-game init --game snake
+npx -y @forgeax/game install --ide codex,cursor,claude
 ```
 
-Configure several clients:
+For ZCode, use `--ide zcode`; this writes its native user configuration to
+`~/.zcode/cli/config.json` and can run from any directory:
 
 ```bash
-npx -y -p @forgeax/game forgeax-game install --ide codex,claude,cursor
+npx -y @forgeax/game install --ide zcode
+```
+
+Configure several clients in one pass:
+
+```bash
+npx -y @forgeax/game install --ide codex,claude,cursor,zcode
 ```
 
 Omitting `--ide` configures every supported client. User-scoped clients can be
@@ -41,7 +49,7 @@ when `install` runs inside the project. The original WorkBuddy name remains acce
 as an alias of the current CodeBuddy client:
 
 ```bash
-npx -y -p @forgeax/game forgeax-game install --ide trae,workbuddy
+npx -y @forgeax/game install --ide trae,workbuddy
 ```
 
 Before writing any config, the installer launches the exact command it intends to
@@ -49,6 +57,45 @@ store and completes a real `initialize` → `tools/list` → `resources/list` ha
 Existing config files are merged, and a changed file is backed up beside the original
 with the `.bak.latest` suffix.
 
+### Create a project
+
+Choose an empty directory and initialize a game there:
+
+```bash
+cd /path/to/empty-directory
+npx -y @forgeax/game init
+```
+
+`init` creates the ForgeaX project, installs the matching Engine SDK, and mounts the
+bundled Skills for every client that already has a ForgeaX MCP entry. Use
+`--game <slug>` to choose a game name or `--ide zcode` when initializing a project
+for ZCode specifically.
+
+> [!IMPORTANT]
+> `init` does not install the user-level MCP entry. A new machine must run
+> `install --ide zcode` once before `init`. A user who already has the `forgeax`
+> entry configured in ZCode can run `init` directly for each new project.
+
+### Refresh an existing project
+
+For a project that was initialized previously, use `update` instead of running the
+same `init` again:
+
+```bash
+cd /path/to/existing-forgeax-project
+npx -y @forgeax/game update
+```
+
+If the project has no game-development Skills yet, use:
+
+```bash
+npx -y @forgeax/game devkit install
+```
+
+After installing or refreshing ZCode Skills, open the project as a ZCode workspace,
+refresh Settings → Skills, and start a new session. Check Settings → MCP Servers or
+run `/mcp status` to confirm `forgeax` is connected.
+
 For local package development or offline use, pin the currently running executable:
 
 ```bash
@@ -60,12 +107,12 @@ bun src/main.ts install --ide codex --local
 | Command | Purpose |
 |:--|:--|
 | `install [--ide a,b] [--local]` | Verify the MCP launch command, then merge client configuration |
-| `init [--game <slug>]` | Create a project/game, install routing rules, and materialize the bundled Engine SDK |
+| `init [--game <slug>] [--ide ...]` | Create a project/game, install routing rules, and materialize the bundled Engine SDK |
 | `use <slug>` | Activate an existing game through the server |
 | `doctor` | Check Node, project binding, service tiers, and client configuration |
 | `devkit install` | Install the game-development Skill and host rules; use `forgeax-install` only when available |
 | `agents update` | Insert or refresh only the managed ForgeaX block in `AGENTS.md` |
-| `upgrade` | Verify the published launch command, refresh installed client entries, and update project routing rules |
+| `update [--ide ...]` | Verify the published launch command, refresh installed client entries, and update project routing rules |
 
 `init` can create the minimal `.forgeax/` instance and game in an ordinary empty
 directory. It also installs `.forgeax/engine-sdk/`, containing declarations, API
@@ -86,8 +133,6 @@ one-time actions on every turn.
 | `forgeax://status` | Resource | Preferred read-only project, service, and next-action status |
 | `forgeax_status_lite` | Tool | Status fallback for clients without MCP resource support |
 | `forgeax_run_current_game` | Tool | Build or reuse the active game's static preview, return its URL and health identity, and identify the runtime log file |
-| `forgeax_generate_image` | Tool | Text-to-image, or image-to-image with a local `image`; saves a PNG/JPG into the active game's `assets/` and returns its path |
-| `forgeax_generate_3d` | Tool | Text-to-3D (`prompt`) or image-to-3D (public https `image` URL); runs the async job to completion and saves a `.glb` into `assets/` |
 
 When this plugin cold-starts the managed Runtime, runtime output is written to:
 
@@ -113,33 +158,6 @@ The game SDK is available at `.forgeax/engine-sdk/`. Use its declaration files a
 `templates/game-default` or `templates/game-empty` before writing imports. If an API
 is absent, inspect `source/<package>/src/` instead of guessing.
 
-### Asset generation (LiteLLM)
-
-`forgeax_generate_image` and `forgeax_generate_3d` produce art and 3D assets through a
-LiteLLM gateway and save them into the active game's `assets/` directory, returning the
-project-relative path to reference from game code. Configure via environment:
-
-| Variable | Required | Default |
-|:--|:-:|:--|
-| `FORGEAX_LITELLM_API_KEY` | yes | — (secret; never commit it) |
-| `FORGEAX_LITELLM_BASE_URL` | no | the shared ForgeaX gateway |
-| `FORGEAX_GEN_IMAGE_MODEL` | no | `gemini-3-pro-image` |
-| `FORGEAX_GEN_3D_TEXT_MODEL` | no | `tripo-3d-text` |
-| `FORGEAX_GEN_3D_IMAGE_MODEL` | no | `tripo-3d-image` |
-| `FORGEAX_COS_BUCKET` / `FORGEAX_COS_REGION` | for local image-to-3D | — |
-| `FORGEAX_COS_SECRET_ID` / `FORGEAX_COS_SECRET_KEY` | for local image-to-3D | — (secret; never commit) |
-
-- **Text-to-image / image-to-image**: `forgeax_generate_image({ prompt, image? })`. A
-  local `image` path switches to editing that image with the prompt.
-- **Text-to-3D**: `forgeax_generate_3d({ prompt })` — submits, polls to completion
-  (~1–2 min), and downloads the `.glb`.
-- **Image-to-3D**: `forgeax_generate_3d({ image })`. `image` is a **public https URL**,
-  or a **local file path** when COS is configured — the file is uploaded to the COS
-  bucket and passed to the backend as a short-lived presigned URL (the private bucket
-  stays private; the URL expires within the hour). This makes the "generate a concept
-  image, then turn it into a mesh" flow work end to end. Without COS, only a public URL
-  is accepted, because the 3D endpoint rejects local paths and inline base64.
-
 ## Supported clients
 
 | Client ID | Config path | Scope |
@@ -151,6 +169,7 @@ project-relative path to reference from game code. Configure via environment:
 | `codebuddy` / `workbuddy` | `~/.codebuddy/.mcp.json` | User |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` | User |
 | `vscode` | `<project>/.vscode/mcp.json` | Project |
+| `zcode` | `~/.zcode/cli/config.json` | User |
 | `opencode` | `~/.config/opencode/opencode.json` | User |
 
 > [!NOTE]
@@ -162,6 +181,10 @@ project-relative path to reference from game code. Configure via environment:
 > OpenCode 1.17.9: `opencode mcp list` starts this package and reports
 > `forgeax connected`. If a future client release changes the schema, `doctor`
 > will still report whether the configured entry matches what this package writes.
+>
+> ZCode uses its native `mcp.servers.<name>` user configuration rather than the
+> `.agents/mcp.json` fallback. Project Skills are installed under `.zcode/skills`;
+> start a new ZCode session and run `/mcp status` after installation.
 
 ## Game development Skill
 
@@ -178,7 +201,7 @@ project, `install`, `init`, and `upgrade` refresh it automatically. It can also
 installed explicitly:
 
 ```bash
-npx -y -p @forgeax/game forgeax-game devkit install
+npx -y @forgeax/game devkit install
 ```
 
 When the project already has a `.forgeax-harness/install-manifest.json`, the command

package/dist/main.js

@@ -248,7 +248,7 @@ function runStdioServer(spec) {
 }
 
 // src/mcp/forgeax-server.ts
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync6 } from "node:fs";
 
 // src/status/collect.ts
 import { readFileSync as readFileSync4 } from "node:fs";
@@ -664,14 +664,6 @@ reasoning and game-code edits; the plugin owns ForgeaX Runtime lifecycle and fee
 - Reading runtime errors or engine logs: read the file path returned in
   \`runtime_logs.local_file\` with your own file-reading tool. Log tailing is
   deliberately not an MCP tool — the log is a file, so read it like one.
-- Generating art or 3D assets ("make a sprite", "I need a texture", "generate a
-  model of…"): call \`forgeax_generate_image\` (text-to-image, or image-to-image
-  with a local \`image\`) or \`forgeax_generate_3d\` (text-to-3D via \`prompt\`,
-  image-to-3D via \`image\`). Both save into the active game's \`assets/\` directory
-  and return the project-relative path to reference from code. Image-to-3D accepts a
-  public https URL, or a local file path when COS is configured (it is uploaded and
-  passed as a short-lived presigned URL). They need \`FORGEAX_LITELLM_API_KEY\` (and
-  \`FORGEAX_COS_*\` for local-file image-to-3D) in the environment.
 - Creating a game, switching the active game, installing or upgrading the plugin:
   these are one-time operations and are CLI subcommands, not MCP tools. Run
   \`npx -y -p @forgeax/game forgeax-game <init|use|doctor|devkit|upgrade>\`.
@@ -686,27 +678,17 @@ running, and running it.`;
 var PLUGIN_SKILL_ID = "forgeax-game";
 var ENGINE_SKILL_PREFIX = "forgeax-engine-";
 var DEVKIT_VERSION = 2;
-var HOST_SKILL_MOUNTS = {
-  codex: ".agents/skills",
-  claude: ".claude/skills",
-  cursor: ".cursor/skills",
-  trae: ".trae/skills",
-  codebuddy: ".codebuddy/skills",
-  workbuddy: ".codebuddy/skills",
-  windsurf: ".codeium/windsurf/skills",
-  vscode: ".vscode/skills",
-  opencode: ".config/opencode/skills"
-};
-var HOST_RULE_MOUNTS = {
-  codex: ".agents/rules",
-  claude: ".claude/rules",
-  cursor: ".cursor/rules",
-  trae: ".trae/rules",
-  codebuddy: ".codebuddy/rules",
-  workbuddy: ".codebuddy/rules",
-  windsurf: ".codeium/windsurf/rules",
-  vscode: ".vscode/rules",
-  opencode: ".config/opencode/rules"
+var HOST_MOUNTS = {
+  codex: { skills: ".agents/skills", rules: ".agents/rules" },
+  claude: { skills: ".claude/skills", rules: ".claude/rules" },
+  cursor: { skills: ".cursor/skills", rules: ".cursor/rules" },
+  trae: { skills: ".trae/skills", rules: ".trae/rules" },
+  codebuddy: { skills: ".codebuddy/skills", rules: ".codebuddy/rules" },
+  workbuddy: { skills: ".codebuddy/skills", rules: ".codebuddy/rules" },
+  windsurf: { skills: ".codeium/windsurf/skills", rules: ".codeium/windsurf/rules" },
+  vscode: { skills: ".vscode/skills", rules: ".vscode/rules" },
+  zcode: { skills: ".zcode/skills" },
+  opencode: { skills: ".config/opencode/skills", rules: ".config/opencode/rules" }
 };
 function skillRoots() {
   const here = dirname3(fileURLToPath(import.meta.url));
@@ -790,24 +772,27 @@ function writeTextIfChanged(path, content) {
   return true;
 }
 function selectedHostIds(clients) {
-  return [...new Set(clients.map((id) => id === "workbuddy" ? "codebuddy" : id))].filter((id) => HOST_SKILL_MOUNTS[id]);
+  return [...new Set(clients.map((id) => id === "workbuddy" ? "codebuddy" : id))].filter((id) => HOST_MOUNTS[id]);
 }
 function hostSkillDirs(projectRoot) {
-  return [...new Set(Object.values(HOST_SKILL_MOUNTS))].map((mount) => join3(projectRoot, mount));
+  return [...new Set(Object.values(HOST_MOUNTS).map((mount) => mount.skills))].map((mount) => join3(projectRoot, mount));
 }
 function installHostDevKit(projectRoot, clients, skills = bundledSkills()) {
   const skillPaths = [];
   const rulePaths = [];
   let changed = false;
   for (const id of selectedHostIds(clients)) {
-    const skillsDir = join3(projectRoot, HOST_SKILL_MOUNTS[id]);
+    const mount = HOST_MOUNTS[id];
+    const skillsDir = join3(projectRoot, mount.skills);
     for (const skill of skills) {
       changed = copySkill(skill.path, join3(skillsDir, skill.id)) || changed;
     }
-    const rulePath = join3(projectRoot, HOST_RULE_MOUNTS[id], `${PLUGIN_SKILL_ID}.md`);
-    changed = writeTextIfChanged(rulePath, ROUTING_TEXT) || changed;
     skillPaths.push(skillsDir);
-    rulePaths.push(rulePath);
+    if (mount.rules) {
+      const rulePath = join3(projectRoot, mount.rules, `${PLUGIN_SKILL_ID}.md`);
+      changed = writeTextIfChanged(rulePath, ROUTING_TEXT) || changed;
+      rulePaths.push(rulePath);
+    }
   }
   const skillIds = skills.map((skill) => skill.id);
   const noun = skillPaths.length === 1 ? "host" : "hosts";
@@ -896,7 +881,7 @@ function removeDevKit(projectRoot) {
   const owned = new Set(bundledSkills().map((skill) => skill.id));
   const removed = [];
   let skillCount = 0;
-  for (const mount of new Set(Object.values(HOST_SKILL_MOUNTS))) {
+  for (const mount of new Set(Object.values(HOST_MOUNTS).map((entry) => entry.skills))) {
     const dir = join3(projectRoot, mount);
     let entries;
     try {
@@ -914,7 +899,8 @@ function removeDevKit(projectRoot) {
     }
     removed.push(dir);
   }
-  for (const mount of new Set(Object.values(HOST_RULE_MOUNTS))) {
+  const ruleMounts = Object.values(HOST_MOUNTS).flatMap((entry) => entry.rules ? [entry.rules] : []);
+  for (const mount of new Set(ruleMounts)) {
     for (const suffix of [".md", ".md.bak.latest"]) {
       rmSync(join3(projectRoot, mount, `${PLUGIN_SKILL_ID}${suffix}`), { force: true });
     }
@@ -1666,432 +1652,11 @@ function resolveSlug(root, requested) {
   return { slug, dir };
 }
 
-// src/gen/generate.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync7, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename, extname, join as join7, relative as relative3 } from "node:path";
-
-// src/gen/config.ts
-var DEFAULT_LITELLM_BASE_URL = "http://21.214.33.175:4000";
-var DEFAULT_MODELS = {
-  textToImage: "gemini-3-pro-image",
-  textTo3d: "tripo-3d-text",
-  imageTo3d: "tripo-3d-image"
-};
-function env(name) {
-  const value = process.env[name]?.trim();
-  return value ? value : undefined;
-}
-function resolveLiteLlmConfig() {
-  const baseUrl = (env("FORGEAX_LITELLM_BASE_URL") ?? DEFAULT_LITELLM_BASE_URL).replace(/\/+$/, "");
-  const apiKey = env("FORGEAX_LITELLM_API_KEY");
-  if (!apiKey) {
-    throw new Error("FORGEAX_LITELLM_API_KEY is not set. Export the LiteLLM key so the asset tools can reach the gateway, e.g. `export FORGEAX_LITELLM_API_KEY=sk-...`.");
-  }
-  return {
-    baseUrl,
-    apiKey,
-    models: {
-      textToImage: env("FORGEAX_GEN_IMAGE_MODEL") ?? DEFAULT_MODELS.textToImage,
-      textTo3d: env("FORGEAX_GEN_3D_TEXT_MODEL") ?? DEFAULT_MODELS.textTo3d,
-      imageTo3d: env("FORGEAX_GEN_3D_IMAGE_MODEL") ?? DEFAULT_MODELS.imageTo3d
-    }
-  };
-}
-
-// src/gen/cos.ts
-import { createHash as createHash2, createHmac } from "node:crypto";
-var DEFAULT_EXPIRES_SEC = 3600;
-var SKEW_SEC = 60;
-function env2(name) {
-  const value = process.env[name]?.trim();
-  return value ? value : undefined;
-}
-function resolveCosConfig() {
-  const bucket = env2("FORGEAX_COS_BUCKET");
-  const region = env2("FORGEAX_COS_REGION");
-  const secretId = env2("FORGEAX_COS_SECRET_ID");
-  const secretKey = env2("FORGEAX_COS_SECRET_KEY");
-  if (!bucket || !region || !secretId || !secretKey)
-    return;
-  return { bucket, region, secretId, secretKey };
-}
-function cosHost(cfg) {
-  return `${cfg.bucket}.cos.${cfg.region}.myqcloud.com`;
-}
-function rfc3986(value) {
-  return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
-}
-function formatKv(map) {
-  const lowered = {};
-  for (const [k, v] of Object.entries(map))
-    lowered[k.toLowerCase()] = v;
-  const keys = Object.keys(lowered).sort();
-  return {
-    serialized: keys.map((k) => `${rfc3986(k)}=${rfc3986(lowered[k])}`).join("&"),
-    keyList: keys.map((k) => rfc3986(k)).join(";")
-  };
-}
-function buildAuthorization(cfg, opts) {
-  const start = opts.nowSec - SKEW_SEC;
-  const end = opts.nowSec + (opts.expiresSec ?? DEFAULT_EXPIRES_SEC);
-  const signTime = `${start};${end}`;
-  const signKey = createHmac("sha1", cfg.secretKey).update(signTime).digest("hex");
-  const { serialized: paramStr, keyList: paramList } = formatKv(opts.params ?? {});
-  const { serialized: headerStr, keyList: headerList } = formatKv(opts.headers ?? {});
-  const httpString = `${opts.method.toLowerCase()}
-${opts.pathname}
-${paramStr}
-${headerStr}
-`;
-  const httpStringSha1 = createHash2("sha1").update(httpString).digest("hex");
-  const stringToSign = `sha1
-${signTime}
-${httpStringSha1}
-`;
-  const signature = createHmac("sha1", signKey).update(stringToSign).digest("hex");
-  return [
-    "q-sign-algorithm=sha1",
-    `q-ak=${cfg.secretId}`,
-    `q-sign-time=${signTime}`,
-    `q-key-time=${signTime}`,
-    `q-header-list=${headerList}`,
-    `q-url-param-list=${paramList}`,
-    `q-signature=${signature}`
-  ].join("&");
-}
-function presignGetUrl(cfg, key, expiresSec = DEFAULT_EXPIRES_SEC, nowSec = Math.floor(Date.now() / 1000)) {
-  const pathname = key.startsWith("/") ? key : `/${key}`;
-  const auth = buildAuthorization(cfg, { method: "get", pathname, nowSec, expiresSec });
-  return `https://${cosHost(cfg)}${pathname}?${auth}`;
-}
-async function uploadObject(cfg, key, bytes, contentType) {
-  const host = cosHost(cfg);
-  const pathname = key.startsWith("/") ? key : `/${key}`;
-  const auth = buildAuthorization(cfg, {
-    method: "put",
-    pathname,
-    headers: { host },
-    nowSec: Math.floor(Date.now() / 1000),
-    expiresSec: 600
-  });
-  const ctrl = new AbortController;
-  const timer = setTimeout(() => ctrl.abort(), 60000);
-  try {
-    const res = await fetch(`https://${host}${pathname}`, {
-      method: "PUT",
-      headers: { authorization: auth, "content-type": contentType },
-      body: bytes,
-      signal: ctrl.signal
-    });
-    if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      throw new Error(`COS upload of ${key} failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 400)}` : ""}`);
-    }
-  } finally {
-    clearTimeout(timer);
-  }
-}
-async function uploadAndPresign(cfg, key, bytes, contentType, expiresSec = DEFAULT_EXPIRES_SEC) {
-  await uploadObject(cfg, key, bytes, contentType);
-  return presignGetUrl(cfg, key, expiresSec);
-}
-
-// src/gen/litellm.ts
-var TASK_TIMEOUT_MS = 420000;
-var POLL_INTERVAL_MS = 3000;
-var REQUEST_TIMEOUT_MS = 60000;
-function authHeaders(cfg) {
-  return { authorization: `Bearer ${cfg.apiKey}` };
-}
-async function request(url, init, timeoutMs = REQUEST_TIMEOUT_MS) {
-  const ctrl = new AbortController;
-  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, { ...init, signal: ctrl.signal });
-    if (!res.ok) {
-      const body = await res.text().catch(() => "");
-      throw new Error(`LiteLLM ${init.method ?? "GET"} ${url} failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 600)}` : ""}`);
-    }
-    return res;
-  } catch (err) {
-    if (err instanceof Error && err.name === "AbortError") {
-      throw new Error(`LiteLLM request timed out after ${timeoutMs}ms: ${url}`);
-    }
-    throw err;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function decodeImagePayload(item) {
-  if (!item)
-    return {};
-  const b64 = typeof item.b64_json === "string" ? item.b64_json : undefined;
-  const url = typeof item.url === "string" ? item.url : undefined;
-  return { b64, url };
-}
-function sniffImageExt(bytes) {
-  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255)
-    return "jpg";
-  return "png";
-}
-async function materializeImage(payload) {
-  if (payload.b64) {
-    const bytes = new Uint8Array(Buffer.from(payload.b64, "base64"));
-    return { bytes, ext: sniffImageExt(bytes) };
-  }
-  if (payload.url) {
-    const res = await request(payload.url, { method: "GET" });
-    const bytes = new Uint8Array(await res.arrayBuffer());
-    return { bytes, ext: sniffImageExt(bytes) };
-  }
-  throw new Error("LiteLLM image response contained neither b64_json nor url.");
-}
-async function generateImage(cfg, opts) {
-  const res = await request(`${cfg.baseUrl}/v1/images/generations`, {
-    method: "POST",
-    headers: { ...authHeaders(cfg), "content-type": "application/json" },
-    body: JSON.stringify({ model: opts.model, prompt: opts.prompt, n: 1, ...opts.size ? { size: opts.size } : {} })
-  });
-  const json = await res.json();
-  return materializeImage(decodeImagePayload(json.data?.[0]));
-}
-async function editImage(cfg, opts) {
-  const form = new FormData;
-  form.set("model", opts.model);
-  form.set("prompt", opts.prompt);
-  form.set("n", "1");
-  form.set("image", new Blob([opts.image]), opts.filename);
-  const res = await request(`${cfg.baseUrl}/v1/images/edits`, {
-    method: "POST",
-    headers: authHeaders(cfg),
-    body: form
-  });
-  const json = await res.json();
-  return materializeImage(decodeImagePayload(json.data?.[0]));
-}
-async function submit3dTask(cfg, body) {
-  const res = await request(`${cfg.baseUrl}/v1/3d/generations`, {
-    method: "POST",
-    headers: { ...authHeaders(cfg), "content-type": "application/json" },
-    body: JSON.stringify(body)
-  });
-  const json = await res.json();
-  if (!json.id)
-    throw new Error(`LiteLLM 3D submit returned no task id: ${JSON.stringify(json).slice(0, 400)}`);
-  return json.id;
-}
-async function poll3dTask(cfg, id, onProgress) {
-  const deadline = Date.now() + TASK_TIMEOUT_MS;
-  for (;; ) {
-    const res = await request(`${cfg.baseUrl}/v1/3d/tasks/${encodeURIComponent(id)}`, {
-      method: "GET",
-      headers: authHeaders(cfg)
-    });
-    const state = await res.json();
-    if (typeof state.progress === "number")
-      onProgress?.(state.progress);
-    const status = state.status?.toLowerCase();
-    if (status === "succeeded" || status === "success" || status === "completed")
-      return state;
-    if (status === "failed" || status === "error" || status === "cancelled") {
-      throw new Error(`LiteLLM 3D task ${id} ${state.status}${state.error ? `: ${JSON.stringify(state.error).slice(0, 300)}` : ""}`);
-    }
-    if (Date.now() > deadline) {
-      throw new Error(`LiteLLM 3D task ${id} did not finish within ${TASK_TIMEOUT_MS / 1000}s (last status: ${state.status}).`);
-    }
-    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-  }
-}
-async function downloadMesh(state) {
-  const assets = (state.data ?? []).map((d) => ({
-    url: typeof d.url === "string" ? d.url : undefined,
-    type: typeof d.type === "string" ? d.type : "",
-    format: typeof d.format === "string" ? d.format : ""
-  }));
-  const mesh = assets.find((a) => a.url && (a.type === "mesh" || /\.(glb|gltf|obj|fbx|usdz)/i.test(a.url ?? ""))) ?? assets.find((a) => a.url);
-  if (!mesh?.url)
-    throw new Error(`LiteLLM 3D task ${state.id} completed with no downloadable mesh asset.`);
-  const res = await request(mesh.url, { method: "GET" });
-  const bytes = new Uint8Array(await res.arrayBuffer());
-  const ext = mesh.format || (mesh.url.match(/\.([a-z0-9]+)(?:\?|$)/i)?.[1] ?? "glb").toLowerCase();
-  return { bytes, ext, assetType: mesh.type || "mesh" };
-}
-async function generate3dFromText(cfg, opts) {
-  const id = await submit3dTask(cfg, { model: opts.model, prompt: opts.prompt });
-  return downloadMesh(await poll3dTask(cfg, id, opts.onProgress));
-}
-async function generate3dFromImageUrl(cfg, opts) {
-  const id = await submit3dTask(cfg, { model: opts.model, image_url: opts.imageUrl, ...opts.prompt ? { prompt: opts.prompt } : {} });
-  return downloadMesh(await poll3dTask(cfg, id, opts.onProgress));
-}
-
-// src/gen/generate.ts
-function assetsDirFor(cwd, explicitGame) {
-  const binding = resolveProject(cwd);
-  if (!binding.root) {
-    throw new Error(`No ForgeaX project found from ${binding.searchedFrom}. Run \`forgeax-game init --game <slug>\` in the workspace first, or pass \`game\`/\`target_dir\`.`);
-  }
-  const slug = explicitGame?.trim() || activeGame(binding.root);
-  if (!slug) {
-    const games = listGames(binding.root);
-    throw new Error(`No active game to save the asset into.${games.length ? ` Pass one of: ${games.join(", ")}` : " Create one with `forgeax-game init --game <slug>`."}`);
-  }
-  const dir = gameDir(binding.root, slug);
-  if (!dir)
-    throw new Error(`Game ${JSON.stringify(slug)} not found in this project.`);
-  const assets = join7(dir, "assets");
-  mkdirSync7(assets, { recursive: true });
-  return { dir: assets, root: binding.root, slug };
-}
-function safeStem(preferred, fallback) {
-  const source = (preferred ?? fallback).toLowerCase();
-  const stem = source.replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48);
-  return stem || "asset";
-}
-function uniquePath(dir, stem, ext) {
-  let candidate = join7(dir, `${stem}.${ext}`);
-  for (let i = 1;existsSync4(candidate); i += 1)
-    candidate = join7(dir, `${stem}-${i}.${ext}`);
-  return candidate;
-}
-function logProgress(label) {
-  let last = -1;
-  return (pct) => {
-    const step = Math.floor(pct / 10);
-    if (step !== last) {
-      last = step;
-      process.stderr.write(`[forgeax] ${label}: ${pct}%
-`);
-    }
-  };
-}
-var GAME_PROPERTY = {
-  game: {
-    type: "string",
-    description: "Game slug to save the asset into. Defaults to the active game."
-  },
-  target_dir: {
-    type: "string",
-    description: "Directory to resolve the ForgeaX project from. Defaults to the server working directory."
-  },
-  name: {
-    type: "string",
-    description: "Base file name for the saved asset (without extension). Defaults to a slug of the prompt."
-  }
-};
-var GENERATE_IMAGE_SCHEMA = {
-  type: "object",
-  properties: {
-    prompt: { type: "string", description: "What to draw. Required for both text-to-image and editing an input image." },
-    image: {
-      type: "string",
-      description: "Optional local image path to edit (image-to-image). When set, the prompt describes the desired change."
-    },
-    model: { type: "string", description: "Override the image model. Defaults to the configured text-to-image model." },
-    ...GAME_PROPERTY
-  },
-  required: ["prompt"],
-  additionalProperties: false
-};
-var GENERATE_3D_SCHEMA = {
-  type: "object",
-  properties: {
-    prompt: { type: "string", description: "Text description for text-to-3D. Provide this or `image`." },
-    image: {
-      type: "string",
-      description: "Image for image-to-3D: a public https URL, or a local file path when COS is configured (FORGEAX_COS_*) — local files are uploaded to COS and passed as a short-lived presigned URL. Without COS, only a public URL works."
-    },
-    model: { type: "string", description: "Override the 3D model. Defaults to the configured text/image-to-3D model." },
-    ...GAME_PROPERTY
-  },
-  additionalProperties: false
-};
-var HTTP_URL_RE = /^https?:\/\//i;
-async function generateImageTool(args, cwd) {
-  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
-  if (!prompt)
-    throw new Error("`prompt` is required.");
-  const cfg = resolveLiteLlmConfig();
-  const targetDir = typeof args.target_dir === "string" ? args.target_dir : cwd;
-  const { dir, root, slug } = assetsDirFor(targetDir, typeof args.game === "string" ? args.game : undefined);
-  const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.textToImage;
-  let result;
-  let mode;
-  const inputImage = typeof args.image === "string" ? args.image.trim() : "";
-  if (inputImage) {
-    if (HTTP_URL_RE.test(inputImage)) {
-      throw new Error("Image-to-image expects a LOCAL image path, not a URL. Download it first, then pass the path.");
-    }
-    if (!existsSync4(inputImage))
-      throw new Error(`Input image not found: ${inputImage}`);
-    const bytes = new Uint8Array(readFileSync6(inputImage));
-    result = await editImage(cfg, { model, prompt, image: bytes, filename: basename(inputImage) });
-    mode = "image-to-image";
-  } else {
-    result = await generateImage(cfg, { model, prompt });
-    mode = "text-to-image";
-  }
-  const stem = safeStem(typeof args.name === "string" ? args.name : undefined, prompt);
-  const outPath = uniquePath(dir, stem, result.ext);
-  writeFileSync4(outPath, result.bytes);
-  const rel = relative3(root, outPath);
-  return `Saved ${mode} asset to \`${rel}\` (game: ${slug}, model: ${model}, ${result.bytes.length} bytes). Reference it from game code by this path.`;
-}
-function imageContentType(path) {
-  const ext = extname(path).toLowerCase();
-  if (ext === ".jpg" || ext === ".jpeg")
-    return "image/jpeg";
-  if (ext === ".webp")
-    return "image/webp";
-  return "image/png";
-}
-async function resolveImageUrlFor3d(image, slug) {
-  if (HTTP_URL_RE.test(image))
-    return image;
-  if (!existsSync4(image))
-    throw new Error(`Input image not found: ${image}`);
-  const cos = resolveCosConfig();
-  if (!cos) {
-    throw new Error("Image-to-3D from a local file needs COS configured (FORGEAX_COS_BUCKET/REGION/SECRET_ID/SECRET_KEY) so the image can be hosted for the backend to fetch. Alternatively pass a public https URL.");
-  }
-  const bytes = new Uint8Array(readFileSync6(image));
-  const stem = safeStem(basename(image, extname(image)), "input");
-  const ext = (extname(image).replace(".", "") || "png").toLowerCase();
-  const key = `forgeax/${slug}/${stem}-${Date.now()}.${ext}`;
-  return uploadAndPresign(cos, key, bytes, imageContentType(image));
-}
-async function generate3dTool(args, cwd) {
-  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
-  const image = typeof args.image === "string" ? args.image.trim() : "";
-  if (!prompt && !image)
-    throw new Error("Provide `prompt` (text-to-3D) or `image` (image-to-3D).");
-  const cfg = resolveLiteLlmConfig();
-  const targetDir = typeof args.target_dir === "string" ? args.target_dir : cwd;
-  const { dir, root, slug } = assetsDirFor(targetDir, typeof args.game === "string" ? args.game : undefined);
-  let result;
-  let mode;
-  if (image) {
-    const imageUrl = await resolveImageUrlFor3d(image, slug);
-    const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.imageTo3d;
-    result = await generate3dFromImageUrl(cfg, { model, imageUrl, prompt: prompt || undefined, onProgress: logProgress("image-to-3D") });
-    mode = "image-to-3D";
-  } else {
-    const model = typeof args.model === "string" && args.model.trim() ? args.model.trim() : cfg.models.textTo3d;
-    result = await generate3dFromText(cfg, { model, prompt, onProgress: logProgress("text-to-3D") });
-    mode = "text-to-3D";
-  }
-  const stem = safeStem(typeof args.name === "string" ? args.name : undefined, prompt || "model");
-  const outPath = uniquePath(dir, stem, result.ext);
-  writeFileSync4(outPath, result.bytes);
-  const rel = relative3(root, outPath);
-  return `Saved ${mode} ${result.assetType} to \`${rel}\` (game: ${slug}, ${result.bytes.length} bytes). Reference it from game code by this path.`;
-}
-
 // src/mcp/forgeax-server.ts
 function packageVersion() {
-  for (const relative4 of ["../package.json", "../../package.json"]) {
+  for (const relative3 of ["../package.json", "../../package.json"]) {
     try {
-      const version = JSON.parse(readFileSync7(new URL(relative4, import.meta.url), "utf8")).version;
+      const version = JSON.parse(readFileSync6(new URL(relative3, import.meta.url), "utf8")).version;
       if (version)
         return version;
     } catch {}
@@ -2133,30 +1698,18 @@ function createForgeaxMcpServer() {
         description: 'Build, preview, reload, or verify the active game. One call covers what the user means by "run it", "let me see it", "reload", or "does it work": it installs the selected Runtime when needed, builds or reuses a static preview, returns a preview URL to open, and reports the Runtime log file. Read an available `runtime_logs.local_file` with your own file tool — log tailing is intentionally not a tool. Call this after a requested game change, not for ordinary edits the user has not asked to see.',
         inputSchema: RUN_TOOL_SCHEMA,
         run: async (args, ctx) => runCurrentGame(args, ctx.cwd)
-      },
-      {
-        name: "forgeax_generate_image",
-        description: "Generate a game image asset from a text prompt (text-to-image), or edit a local image when `image` is set (image-to-image). Saves the PNG/JPG into the active game's `assets/` directory and returns its project-relative path to reference from game code. Backed by the ForgeaX LiteLLM gateway; requires FORGEAX_LITELLM_API_KEY. Use when the user asks for a sprite, texture, icon, background, or concept art.",
-        inputSchema: GENERATE_IMAGE_SCHEMA,
-        run: async (args, ctx) => generateImageTool(args, ctx.cwd)
-      },
-      {
-        name: "forgeax_generate_3d",
-        description: "Generate a 3D model (.glb) for the game. Provide `prompt` for text-to-3D, or `image` for image-to-3D — a public https URL, or a local file path when COS is configured (the file is uploaded and passed as a short-lived presigned URL). Runs the async generation to completion (~1–2 min) and saves the mesh into the active game's `assets/` directory, returning its project-relative path. Backed by the ForgeaX LiteLLM gateway; requires FORGEAX_LITELLM_API_KEY (and FORGEAX_COS_* for local-file image-to-3D).",
-        inputSchema: GENERATE_3D_SCHEMA,
-        run: async (args, ctx) => generate3dTool(args, ctx.cwd)
       }
     ]
   };
 }
 
 // src/cli/dispatch.ts
-import { existsSync as existsSync6, readFileSync as readFileSync9, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "node:fs";
-import { basename as basename2, join as join9 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync8, rmSync as rmSync2, writeFileSync as writeFileSync5 } from "node:fs";
+import { basename, join as join8 } from "node:path";
 
 // src/install/clients.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join8, resolve as resolve4 } from "node:path";
+import { join as join7, resolve as resolve4 } from "node:path";
 var HOME = homedir3();
 var CLIENTS = [
   {
@@ -2164,7 +1717,7 @@ var CLIENTS = [
     label: "Codex CLI",
     format: "toml",
     scope: "user",
-    path: () => join8(HOME, ".codex", "config.toml"),
+    path: () => join7(HOME, ".codex", "config.toml"),
     commandShape: "split",
     postInstallNote: "Restart Codex, then run /mcp to confirm the server is connected."
   },
@@ -2173,7 +1726,7 @@ var CLIENTS = [
     label: "Claude Code",
     format: "json",
     scope: "user",
-    path: () => join8(HOME, ".claude.json"),
+    path: () => join7(HOME, ".claude.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Restart Claude Code, then run /mcp to confirm the server is connected."
@@ -2183,7 +1736,7 @@ var CLIENTS = [
     label: "Cursor",
     format: "json",
     scope: "user",
-    path: () => join8(HOME, ".cursor", "mcp.json"),
+    path: () => join7(HOME, ".cursor", "mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Cursor, then check Settings > MCP."
@@ -2193,7 +1746,7 @@ var CLIENTS = [
     label: "Trae (project)",
     format: "json",
     scope: "project",
-    path: (projectRoot) => join8(projectRoot, ".trae", "mcp.json"),
+    path: (projectRoot) => join7(projectRoot, ".trae", "mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Trae, then check the project MCP server list."
@@ -2204,7 +1757,7 @@ var CLIENTS = [
     label: "CodeBuddy / WorkBuddy",
     format: "json",
     scope: "user",
-    path: () => join8(HOME, ".codebuddy", ".mcp.json"),
+    path: () => join7(HOME, ".codebuddy", ".mcp.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Restart CodeBuddy or WorkBuddy, then run /mcp to confirm the server is connected."
@@ -2214,7 +1767,7 @@ var CLIENTS = [
     label: "Windsurf",
     format: "json",
     scope: "user",
-    path: () => join8(HOME, ".codeium", "windsurf", "mcp_config.json"),
+    path: () => join7(HOME, ".codeium", "windsurf", "mcp_config.json"),
     serverMapKey: ["mcpServers"],
     commandShape: "split",
     postInstallNote: "Reload Windsurf to pick up the new server."
@@ -2224,17 +1777,27 @@ var CLIENTS = [
     label: "VS Code (workspace)",
     format: "json",
     scope: "project",
-    path: (projectRoot) => join8(projectRoot, ".vscode", "mcp.json"),
+    path: (projectRoot) => join7(projectRoot, ".vscode", "mcp.json"),
     serverMapKey: ["servers"],
     commandShape: "split",
     postInstallNote: 'Open .vscode/mcp.json and click Start, or run "MCP: List Servers".'
   },
+  {
+    id: "zcode",
+    label: "ZCode",
+    format: "json",
+    scope: "user",
+    path: () => join7(HOME, ".zcode", "cli", "config.json"),
+    serverMapKey: ["mcp", "servers"],
+    commandShape: "split",
+    postInstallNote: "Start a new ZCode session, then run /mcp status to confirm the server is connected."
+  },
   {
     id: "opencode",
     label: "OpenCode",
     format: "json",
     scope: "user",
-    path: () => join8(HOME, ".config", "opencode", "opencode.json"),
+    path: () => join7(HOME, ".config", "opencode", "opencode.json"),
     serverMapKey: ["mcp"],
     commandShape: "argv",
     extraEntryFields: { type: "local", enabled: true },
@@ -2258,7 +1821,7 @@ function launchSpec(mode) {
 }
 
 // src/install/write-config.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync5, mkdirSync as mkdirSync8, readFileSync as readFileSync8, writeFileSync as writeFileSync5 } from "node:fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync4, mkdirSync as mkdirSync7, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
 import { dirname as dirname4 } from "node:path";
 
 // src/install/toml-section.ts
@@ -2468,11 +2031,11 @@ function mergeTomlConfig(existing, entry) {
 }
 function inspectConfig(spec, projectRoot, launch) {
   const path = spec.path(projectRoot);
-  if (!existsSync5(path))
+  if (!existsSync4(path))
     return { path, state: "missing" };
   let existing;
   try {
-    existing = readFileSync8(path, "utf8");
+    existing = readFileSync7(path, "utf8");
     if (spec.format === "toml") {
       const header = `mcp_servers.${SERVER_KEY}`;
       if (!hasTomlTable(existing, header)) {
@@ -2517,25 +2080,25 @@ function inspectConfig(spec, projectRoot, launch) {
 }
 function applyConfig(spec, projectRoot, launch) {
   const path = spec.path(projectRoot);
-  const existing = existsSync5(path) ? readFileSync8(path, "utf8") : undefined;
+  const existing = existsSync4(path) ? readFileSync7(path, "utf8") : undefined;
   const entry = buildEntry(spec, launch);
   const merged = spec.format === "toml" ? mergeTomlConfig(existing, entry) : mergeJsonConfig(existing, spec, entry);
   if (!merged.changed)
     return { path, changed: false };
-  mkdirSync8(dirname4(path), { recursive: true });
+  mkdirSync7(dirname4(path), { recursive: true });
   let backup;
   if (existing !== undefined) {
     backup = `${path}.bak.latest`;
     copyFileSync2(path, backup);
   }
-  writeFileSync5(path, merged.content);
+  writeFileSync4(path, merged.content);
   return { path, changed: true, ...backup ? { backup } : {} };
 }
 function removeConfig(spec, projectRoot) {
   const path = spec.path(projectRoot);
-  if (!existsSync5(path))
+  if (!existsSync4(path))
     return { path, changed: false };
-  const existing = readFileSync8(path, "utf8");
+  const existing = readFileSync7(path, "utf8");
   let content;
   if (spec.format === "toml") {
     content = removeTomlTable(existing, `mcp_servers.${SERVER_KEY}`);
@@ -2563,7 +2126,7 @@ function removeConfig(spec, projectRoot) {
     return { path, changed: false };
   const backup = `${path}.bak.latest`;
   copyFileSync2(path, backup);
-  writeFileSync5(path, content);
+  writeFileSync4(path, content);
   return { path, changed: true, backup };
 }
 
@@ -2714,7 +2277,7 @@ import {
 var HELP = `ForgeaX game development plugin
 
 Usage:
-  forgeax-game install [--ide codex,claude,cursor,trae,opencode,workbuddy] [--local]
+  forgeax-game install [--ide ${CLIENT_CHOICES.join(",")}] [--local]
   forgeax-game uninstall [--ide ...] [--purge]
   forgeax-game init [--game <slug>] [--ide ...]
   forgeax-game use <slug>
@@ -2767,23 +2330,23 @@ function requireProject() {
   return project.root;
 }
 function updateAgentsFile(root) {
-  const path = join9(root, "AGENTS.md");
-  const existing = existsSync6(path) ? readFileSync9(path, "utf8") : undefined;
+  const path = join8(root, "AGENTS.md");
+  const existing = existsSync5(path) ? readFileSync8(path, "utf8") : undefined;
   const content = upsertBlock(existing, ROUTING_TEXT);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync6(path, content);
+  writeFileSync5(path, content);
   return { path, changed: true };
 }
 function removeAgentsBlock(root) {
-  const path = join9(root, "AGENTS.md");
-  if (!existsSync6(path))
+  const path = join8(root, "AGENTS.md");
+  if (!existsSync5(path))
     return { path, changed: false };
-  const existing = readFileSync9(path, "utf8");
+  const existing = readFileSync8(path, "utf8");
   const content = removeBlock(existing);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync6(path, content);
+  writeFileSync5(path, content);
   return { path, changed: true };
 }
 async function apiPost(path, body) {
@@ -2862,7 +2425,7 @@ async function installCommand(args) {
   return failures === 0 ? 0 : 1;
 }
 function defaultSlug(root) {
-  const raw = basename2(root).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  const raw = basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
   return SLUG_RE.test(raw) ? raw : "my-game";
 }
 var INIT_USAGE = "usage: forgeax-game init [--game <slug>] [--ide codex,claude,cursor,...]";
@@ -3018,7 +2581,7 @@ async function uninstallCommand(args) {
     const agents = removeAgentsBlock(root);
     process.stdout.write(`${agents.changed ? "REMOVED" : "ABSENT "} routing block: ${agents.path}
 `);
-    process.stdout.write(`KEPT    your games and project metadata: ${join9(root, ".forgeax")}
+    process.stdout.write(`KEPT    your games and project metadata: ${join8(root, ".forgeax")}
 `);
   } else {
     process.stdout.write(`INFO  no ForgeaX project bound; only client configuration was touched.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@forgeax/game",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
-  "description": "@forgeax/game \u2014 ForgeaX game development as a plugin for MCP-capable agent CLIs (Codex, Claude Code, Cursor, Trae, OpenCode, WorkBuddy). Single binary, dual mode: no args = stdio MCP server, subcommand = CLI.",
+  "description": "@forgeax/game \u2014 ForgeaX game development as a plugin for MCP-capable agent CLIs (Codex, Claude Code, Cursor, Trae, ZCode, OpenCode, WorkBuddy). Single binary, dual mode: no args = stdio MCP server, subcommand = CLI.",
   "main": "./dist/main.js",
   "bin": {
     "forgeax-game": "dist/main.js"