@cloudgrid-io/mcp 0.20.8 → 0.20.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.8",
+  "version": "0.20.10",
   "description": "Use CloudGrid via MCP to brainstorm, build, deploy, and improve apps, games, websites, dashboards, and tools and get a live URL - templates, recipes, managed databases and AI, instant single-page publish, and full-app deploys, for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server, over MCP.",
   "type": "module",
   "bin": {
@@ -28,6 +28,7 @@
     "test:self-healing": "node test/self-healing.test.mjs",
     "test:grid-picker": "node test/grid-picker.test.mjs",
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
+    "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",
     "test:qa-courier": "node test/qa-courier.test.mjs",
@@ -51,6 +52,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "express": "^4.22.2",
+    "fflate": "^0.8.3",
     "zod": "^3.23.0"
   },
   "license": "Apache-2.0",

package/src/playbook.js

@@ -30,7 +30,7 @@ Operating rules:
   - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_copy_app and edit the copy instead.
 16. Help CloudGrid QA. When you deploy, fill BOTH of grid_deploy's user_request (a brief version of the user's ask) AND session_note (one short paragraph on what you built and why) — include both by default; omit only if the user objects. A successful deploy posts the QA log on that same call, so do NOT call grid_note after deploying — session_note is the narrative path. Use grid_note only BEFORE a deploy, or in a session that ends without one. Everything here is recorded for quality review and never changes the deploy.
 
-Deploy is via grid_deploy on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI). A single HTML page deploys synchronously as an inspiration, so you get a URL right away.
+Deploy is via grid_deploy on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI). A single HTML page deploys synchronously as an inspiration, so you get a URL right away. A user-supplied ZIP archive (local edition): pass its path directly as the path param — it is extracted and deployed as a static app; if the zip is assets-only (e.g. images for a gallery), generate the page and pass it as html alongside the zip path, and it becomes the index.html over the archive's files.
 When you deploy a folder that already has a cloudgrid.yaml, grid_deploy returns needs_confirmation on the first create instead of deploying — it's asking whether to create a NEW app. Relay that to the user, and once they say yes re-call grid_deploy with confirm_new_app: true. To update an existing app instead, pass its target_entity_id.`;
 
 // The corpus subdirectories that grid_get_template serves, keyed by `kind`. Each

package/src/tools/cli.js

@@ -307,11 +307,19 @@ export async function runCloudgrid(args, opts = {}, deps = {}) {
   let runtimeHint = null;
 
   const extract = (err) => {
-    const detail = [err && err.stdout, err && err.stderr, err && err.message]
+    let detail = [err && err.stdout, err && err.stderr, err && err.message]
       .filter(Boolean)
       .join("\n")
       .trim();
-    return new Error(detail || "cloudgrid command failed");
+    // Voice rule (founder directive: the verb is `grid`, only): exec errors
+    // embed the raw invocation (a cloudgrid binary path, the cli-shim, or an
+    // npx spec). Normalize the displayed command to `grid <verb>` so the model
+    // never learns and repeats a deprecated verb from an error message.
+    detail = detail.replace(
+      /Command failed:[^\n]*?(?= (?:init|plug|logs|status|info|get|describe|pickup|rename|unplug|delete|rollback|versions|env|secrets|scaffold|doctor|open|use|whoami|logout|visibility|feedback|login|dev|recipes|hooks|--)\b)/g,
+      "Command failed: grid",
+    );
+    return new Error(detail || "grid command failed");
   };
 
   // 1. Bundled CLI — own node_modules only, version-gated. Runs via

package/src/tools/deploy.js

@@ -673,6 +673,191 @@ function loadIgnoreMatchers(rootDir) {
     patterns.some((p) => (!p.dirOnly || isDir) && p.re.test(relPath));
 }
 
+// ── Zip deploys (local edition) ──────────────────────────────────────────────
+// "Build me a gallery site with the attached images (zip)" — the local server
+// CAN open archives even though the model cannot. `path` accepts a .zip: it is
+// extracted to a temp dir and deployed. Because the platform's multi-file
+// INSPIRATION create currently persists only the primary HTML (see the
+// inline-create issue filed 2026-07-17), a multi-file zip is ALWAYS shaped as
+// a static RUNTIME project — a synthesized cloudgrid.yaml (type: static) with
+// the files under services/web/ — which the server builds and serves fully.
+// A zip that ships its own cloudgrid.yaml is deployed as-is.
+//
+// `html` is allowed TOGETHER with a zip path (the one source combo): it becomes
+// services/web/index.html, so an agent on a no-filesystem client can generate
+// the page inline while the archive supplies the assets.
+
+function isZipPath(srcPath) {
+  const abs = resolve(srcPath);
+  if (!existsSync(abs) || !statSync(abs).isFile()) return false;
+  if (/\.zip$/i.test(abs)) return true;
+  // Magic sniff so "photos.ZIP.download"-style names still work.
+  try {
+    const fd = readFileSync(abs);
+    return fd.length >= 4 && fd[0] === 0x50 && fd[1] === 0x4b && fd[2] === 0x03 && fd[3] === 0x04;
+  } catch {
+    return false;
+  }
+}
+
+// Extract a zip safely and return the directory to deploy. Throws on traversal.
+async function expandZipToProject(zipPath, inlineHtml) {
+  const { unzipSync } = await import("fflate");
+  const raw = readFileSync(resolve(zipPath));
+  if (raw.byteLength > PLUG_MAX_TOTAL_BYTES) {
+    throw new Error("The zip exceeds the 100MB plug limit. Trim it or split the content.");
+  }
+  let entries;
+  try {
+    entries = unzipSync(new Uint8Array(raw));
+  } catch (err) {
+    throw new Error(`Could not read the zip archive: ${err.message}`);
+  }
+  // Sanitize: reject traversal, skip macOS metadata + always-skip dirs.
+  const files = [];
+  for (const [name, data] of Object.entries(entries)) {
+    if (name.endsWith("/")) continue; // directory entry
+    const norm = name.replace(/\\/g, "/");
+    if (norm.startsWith("/") || /^[A-Za-z]:/.test(norm) || norm.split("/").includes("..")) {
+      throw new Error(`Refusing zip entry outside the archive root: ${name}`);
+    }
+    const parts = norm.split("/");
+    if (parts.includes("__MACOSX") || parts.some((p) => PLUG_ALWAYS_SKIP.has(p))) continue;
+    files.push({ path: norm, data });
+  }
+  if (files.length === 0) throw new Error("The zip contains no deployable files.");
+  if (files.length > PLUG_MAX_FILES) {
+    throw new Error(`The zip has more than ${PLUG_MAX_FILES} files — too large to plug.`);
+  }
+  // Strip a single common root folder (the usual zip-of-a-folder shape) — but
+  // ONLY when stripping surfaces an index.html or cloudgrid.yaml at the root.
+  // An assets-only archive like img/a.png shares a common root too, and
+  // flattening it would break the page's relative img/ references.
+  const firstSeg = files[0].path.split("/")[0];
+  const singleRoot =
+    files.every((f) => f.path.split("/")[0] === firstSeg) && files.every((f) => f.path.includes("/"));
+  if (singleRoot) {
+    const stripped = files.map((f) => f.path.slice(firstSeg.length + 1));
+    if (stripped.some((p) => /^index\.html?$/i.test(p) || p === "cloudgrid.yaml")) {
+      files.forEach((f, i) => { f.path = stripped[i]; });
+      if (files.some((f) => !f.path)) throw new Error("Unexpected zip layout (empty path after root strip).");
+    }
+  }
+
+  const hasManifest = files.some((f) => f.path === "cloudgrid.yaml");
+  const hasIndex = files.some((f) => /^index\.html?$/i.test(f.path));
+  const hasInlineHtml = typeof inlineHtml === "string" && inlineHtml.length > 0;
+  if (hasInlineHtml && hasManifest) {
+    throw new Error(
+      "The zip already contains a cloudgrid.yaml project — deploy it as-is (drop the `html` param), " +
+        "or re-plug the entity and edit its files instead.",
+    );
+  }
+  if (hasInlineHtml && hasIndex) {
+    throw new Error(
+      "The zip already has an index.html — pass either the zip alone, or `html` with a zip of assets only.",
+    );
+  }
+  if (!hasManifest && !hasIndex && !hasInlineHtml) {
+    throw new Error(
+      "The zip has no index.html and no cloudgrid.yaml. Generate the page first and pass it as `html` " +
+        "alongside the zip (the archive then supplies the assets), or add an index.html to the archive.",
+    );
+  }
+
+  // A zip that is JUST one HTML page (no manifest, no assets) rides the
+  // instant single-file inspiration path instead of a runtime build.
+  if (!hasManifest && !hasInlineHtml && files.length === 1 && /^index\.html?$/i.test(files[0].path)) {
+    return { singleHtml: Buffer.from(files[0].data).toString("utf8") };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), "cloudgrid-zip-"));
+  const writeAll = async (base) => {
+    for (const f of files) {
+      const dest = resolve(join(base, f.path));
+      if (dest !== base && !dest.startsWith(base + sep)) {
+        throw new Error(`Refusing to write zip entry outside the temp dir: ${f.path}`);
+      }
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, f.data);
+    }
+  };
+
+  if (hasManifest) {
+    // The archive is already a CloudGrid project — deploy verbatim.
+    await writeAll(resolve(dir));
+    return { projectDir: dir, name: null };
+  }
+
+  // Synthesize a static-runtime wrapper: name from the archive, files under
+  // services/web/. (Static RUNTIME, not inspiration, so every file survives.)
+  const rawName = basename(resolve(zipPath)).replace(/\.zip$/i, "");
+  const slugged = rawName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 42);
+  const name = slugged.length >= 2 && /^[a-z0-9]/.test(slugged) ? slugged : "zip-site";
+  const webDir = resolve(join(dir, "services", "web"));
+  await mkdir(webDir, { recursive: true });
+  await writeAll(webDir);
+  if (hasInlineHtml) {
+    const art = htmlToArtifact(inlineHtml);
+    await writeFile(join(webDir, "index.html"), art.buffer);
+  }
+  await writeFile(
+    join(dir, "cloudgrid.yaml"),
+    `name: ${name}\ndescription: Deployed from ${basename(zipPath)}.\nservices:\n  web:\n    type: static\n    path: /\n`,
+  );
+  return { projectDir: dir, name };
+}
+
+// Deploy an extracted zip PROJECT through the CLI (`grid init --here` +
+// `grid plug`). The direct-API inline wire cannot be used here: verified live
+// 2026-07-17, it drops secondary files on inspiration creates AND never starts
+// the build for runtime creates from path-mode ("charged, not yet live" —
+// entities drop-df1f / drop-e86d). The CLI plug path builds correctly (every
+// runtime this week shipped through it), so zip projects ride it.
+async function plugZipProjectViaCli(ctx, { projectDir, name }, input, deps = {}) {
+  const { cliRun = runCloudgrid } = deps;
+  const grid = input?.grid || (await ctx.getActiveGrid?.()) || null;
+  const manifestPath = join(projectDir, "cloudgrid.yaml");
+  const manifestBody = readFileSync(manifestPath, "utf8");
+  const yamlName =
+    name ||
+    (() => {
+      const m = /^name:\s*(.+?)\s*$/m.exec(manifestBody);
+      return m ? m[1].replace(/^["']|["']$/g, "") : "zip-site";
+    })();
+  // `grid init --here` refuses a dir that already has a cloudgrid.yaml, and it
+  // is also the step that mints the real slug (name + 4-hex suffix). So: stash
+  // the manifest, init bare, then restore it with the assigned slug as name:.
+  await rm(manifestPath, { force: true });
+  const initArgs = ["init", "app", yamlName, "--here", ...(grid ? ["--grid", grid] : [])];
+  const initOut = String((await cliRun(initArgs, { cwd: projectDir })) || "");
+  let assignedSlug = /Slug:\s+(\S+)/.exec(initOut)?.[1] ?? null;
+  if (!assignedSlug) {
+    try {
+      assignedSlug = JSON.parse(readFileSync(join(projectDir, ".cloudgrid", "link.json"), "utf8")).entity_slug;
+    } catch {
+      assignedSlug = yamlName;
+    }
+  }
+  await writeFile(manifestPath, manifestBody.replace(/^name:.*$/m, `name: ${assignedSlug}`));
+  const stdout = await cliRun(
+    ["plug", "--no-progress", "--no-clipboard", "--no-notify"],
+    { cwd: projectDir },
+  );
+  const url = parseCliPlugUrl(String(stdout || ""));
+  if (!url) {
+    throw new Error(
+      `The zip project deployed via the CLI but no live URL was found in its output.\n${String(stdout || "").slice(0, 500)}`,
+    );
+  }
+  return {
+    text:
+      `Live: ${url}\n` +
+      "(Deployed from the zip archive as a static app via the bundled CloudGrid CLI.)",
+    structured: { url, status: "created", via: "zip-cli" },
+  };
+}
+
 // Walk a local folder into `[{path, buffer}]` artifacts (repo-relative paths),
 // honoring .gitignore/.cloudgridignore at the root plus the always-skip set.
 // A single file becomes one artifact named by its basename.
@@ -893,13 +1078,20 @@ export async function runPlug(ctx, input, deps = {}) {
   } = input || {};
 
   // ── Source: exactly one of html | artifact_files | path ─────────────────────
-  const hasHtml = typeof html === "string" && html.length > 0;
+  // One allowed combo: `html` + a `path` that is a ZIP archive — the html
+  // becomes index.html and the archive supplies the assets (the Desktop
+  // "gallery from a zip" flow, where the model can generate a page but cannot
+  // write files).
+  let hasHtml = typeof html === "string" && html.length > 0;
   const hasArtifacts = Array.isArray(artifact_files) && artifact_files.length > 0;
-  const hasPath = Boolean(srcPath);
-  if ((hasHtml ? 1 : 0) + (hasArtifacts ? 1 : 0) + (hasPath ? 1 : 0) > 1) {
+  let hasPath = Boolean(srcPath);
+  let effectivePath = srcPath;
+  const zipSource = hasPath && ctx.edition !== "web" && isZipPath(srcPath);
+  if ((hasHtml ? 1 : 0) + (hasArtifacts ? 1 : 0) + (hasPath ? 1 : 0) > 1 && !(zipSource && hasHtml && !hasArtifacts)) {
     throw new Error(
       "Pass exactly one source: `html` (a single inline HTML document), `artifact_files` " +
-        "(multiple inline files), or `path` (a local file/folder).",
+        "(multiple inline files), or `path` (a local file/folder/zip). Exception: `html` " +
+        "may accompany a .zip `path` — it becomes the index.html over the archive's assets.",
     );
   }
   if (ctx.edition === "web" && hasPath) {
@@ -907,6 +1099,28 @@ export async function runPlug(ctx, input, deps = {}) {
       "The hosted server cannot read local files — pass the source inline via `html` or `artifact_files`.",
     );
   }
+  let zipSingleHtml = null;
+  if (zipSource) {
+    if (target_entity_id || (slug && grid)) {
+      throw new Error(
+        "Re-plugging an existing entity from a zip is not supported yet — pick up the app " +
+          "(grid_edit_existing_app) and re-plug the folder, or deploy the zip as a new entity.",
+      );
+    }
+    if (anon) {
+      throw new Error("A zip deploy creates a static app and needs sign-in — it cannot be anonymous.");
+    }
+    const expanded = await expandZipToProject(srcPath, hasHtml ? html : null);
+    if (expanded.singleHtml) {
+      // One-page archive → instant inspiration via the proven html wire.
+      zipSingleHtml = expanded.singleHtml;
+      hasPath = false;
+      hasHtml = true;
+    } else {
+      // Multi-file / project archive → CLI deploy (see plugZipProjectViaCli).
+      return plugZipProjectViaCli(ctx, expanded, input, deps);
+    }
+  }
   let artifacts;
   // Set on the single-file `html` path so the auth-aware inline size cap can be
   // enforced once the anon-vs-authed wire is known (see below).
@@ -915,11 +1129,11 @@ export async function runPlug(ctx, input, deps = {}) {
     // The ergonomic single-file publish path (the old drop verb): one self-
     // contained HTML document → one index.html artifact, with the shared
     // hardening (base64 rescue, @-path/file-path rejection, fragment wrap).
-    const art = htmlToArtifact(html, filename);
+    const art = htmlToArtifact(zipSingleHtml ?? html, filename);
     inlineHtmlBytes = art.buffer.byteLength;
     artifacts = [art];
   } else if (hasPath) {
-    artifacts = collectPathArtifacts(srcPath);
+    artifacts = collectPathArtifacts(effectivePath);
   } else if (hasArtifacts) {
     let total = 0;
     artifacts = artifact_files.map((f) => {

package/src/tools/register.js

@@ -181,9 +181,13 @@ export function registerTools(server, ctx) {
       ? {}
       : {
           path: z.string().optional().describe(
-            "Local edition: path to the entity folder (or a single file) to upload. A folder is read " +
-            "recursively, honoring .gitignore/.cloudgridignore (plus .git/node_modules always skipped). " +
-            "Mutually exclusive with `html` and `artifact_files`.",
+            "Local edition: path to the entity folder, a single file, or a .zip ARCHIVE to upload. " +
+            "A folder is read recursively, honoring .gitignore/.cloudgridignore (plus .git/node_modules " +
+            "always skipped). A .zip is extracted and deployed: with its own cloudgrid.yaml it deploys " +
+            "as that project; otherwise it becomes a static app (all files served). Use this for " +
+            "\"deploy this zip\" / \"gallery from these zipped images\" requests. Mutually exclusive with " +
+            "`html` and `artifact_files` — EXCEPT `html` + a .zip of assets: the html becomes index.html " +
+            "over the archive's files (generate the page, let the zip supply the images).",
           ),
         }),
     artifact_files: z.array(z.object({
@@ -838,7 +842,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_create_project",
-    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `cloudgrid init`.",
+    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `grid init`.",
     {
       kind: z.enum(["app", "agent"]).describe("Entity kind."),
       name: z.string().describe("Slug: 3-40 lowercase alphanumerics and hyphens."),
@@ -866,7 +870,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_view_logs",
-    "Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps `cloudgrid logs`.",
+    "Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps `grid logs`.",
     {
       name: z.string().optional().describe("Entity name. Omit to use the entity linked to the current directory."),
       tail: z.number().int().positive().optional().describe("Number of recent lines. Default 100."),
@@ -884,7 +888,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_share",
-    "Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps `cloudgrid visibility set`.",
+    "Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps `grid visibility set`.",
     {
       name: z.string().describe("Entity slug."),
       mode: z.enum(["link", "private", "authenticated", "grid"]).optional().describe("Visibility mode. Default link."),
@@ -895,7 +899,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_feedback",
-    "List recent feedback events for the active org. Read-only. Wraps `cloudgrid feedback list`.",
+    "List recent feedback events for the active org. Read-only. Wraps `grid feedback list`.",
     {
       since: z.string().optional().describe("Only events newer than this, e.g. 24h, 7d."),
       limit: z.number().int().positive().max(200).optional().describe("Number of events. Default 50, max 200."),
@@ -916,7 +920,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_whoami",
-    "Show the signed-in user and active org. Wraps `cloudgrid whoami`.",
+    "Show the signed-in user and active org. Wraps `grid whoami`.",
     {},
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(() => ["whoami"]),
@@ -924,7 +928,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_switch_grid",
-    "Switch the active org. Wraps `cloudgrid use`.",
+    "Switch the active org. Wraps `grid use`.",
     { org: z.string().describe("Org slug to switch to.") },
     { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     cliTool(({ org }) => ["use", org]),
@@ -932,7 +936,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_logout",
-    "Sign out and clear local credentials. Wraps `cloudgrid logout`.",
+    "Sign out and clear local credentials. Wraps `grid logout`.",
     {},
     { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     cliTool(() => ["logout"]),
@@ -940,7 +944,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_status",
-    "Org dashboard, entity detail, or deploy snapshot. Wraps `cloudgrid status`.",
+    "Org dashboard, entity detail, or deploy snapshot. Wraps `grid status`.",
     { name: z.string().optional().describe("Entity name or trace id. Omit for the org dashboard.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => (name ? ["status", name] : ["status"])),
@@ -948,7 +952,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_info",
-    "Show metadata for a CloudGrid entity. Wraps `cloudgrid info`.",
+    "Show metadata for a CloudGrid entity. Wraps `grid info`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => {
@@ -959,13 +963,13 @@ export function registerTools(server, ctx) {
   );
 
   // grid_get is the single canonical lister for grids, entities, and spaces
-  // (wraps `cloudgrid get <resource> --json`). It replaces the former
+  // (wraps `grid get <resource> --json`). It replaces the former
   // cloudgrid_grid (which wrapped only `get entities`) — retired here so there is
   // exactly one way to list entities. resource="entities" reproduces the old
   // cloudgrid_grid behaviour with `grid` mapping to the CLI's `--grid` flag.
   regTool(
     "grid_get",
-    "List CloudGrid grids, entities, or spaces. Wraps `cloudgrid get <grids|entities|spaces> --json`.",
+    "List CloudGrid grids, entities, or spaces. Wraps `grid get <grids|entities|spaces> --json`.",
     {
       resource: z.enum(["grids", "entities", "spaces"]).describe("What to list: grids, entities, or spaces."),
       grid: z.string().optional().describe("Grid slug (entities/spaces only). Omit for the active grid."),
@@ -992,7 +996,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_describe_grid",
-    "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `cloudgrid describe grid <slug> --json`.",
+    "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `grid describe grid <slug> --json`.",
     { grid: z.string().describe("Grid slug to describe.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
@@ -1000,7 +1004,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_edit_existing_app",
-    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `cloudgrid pickup`.",
+    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `grid pickup`.",
     {
       name: z.string().describe("Entity slug or id to pick up."),
       target_dir: z.string().optional().describe("Directory to pick up into (relative to cwd). Defaults to the entity name."),
@@ -1025,7 +1029,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_rename",
-    "Rename a CloudGrid entity's display name (slug stays the same). Wraps `cloudgrid rename`.",
+    "Rename a CloudGrid entity's display name (slug stays the same). Wraps `grid rename`.",
     {
       name: z.string().describe("Entity slug."),
       new_name: z.string().describe("New display name."),
@@ -1036,7 +1040,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_take_offline",
-    "Take an entity off the grid. Destructive. Wraps `cloudgrid unplug`.",
+    "Take an entity off the grid. Destructive. Wraps `grid unplug`.",
     {
       name: z.string().describe("Entity slug to take down (required)."),
       confirm: z.literal(true).describe("Must be true to proceed."),
@@ -1047,7 +1051,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_delete",
-    "Archive a CloudGrid inspiration. Destructive. Wraps `cloudgrid delete entity`.",
+    "Archive a CloudGrid inspiration. Destructive. Wraps `grid delete entity`.",
     {
       name: z.string().describe("Entity slug to delete (required)."),
       confirm: z.literal(true).describe("Must be true to proceed."),
@@ -1058,7 +1062,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_rollback_deploy",
-    "Rollback an entity to a previous version. Wraps `cloudgrid rollback`.",
+    "Rollback an entity to a previous version. Wraps `grid rollback`.",
     {
       name: z.string().describe("Entity slug."),
       to: z.string().optional().describe("Target version tag or id. Omit to roll back one version."),
@@ -1073,7 +1077,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_list_versions",
-    "List published versions for an entity. Wraps `cloudgrid versions`.",
+    "List published versions for an entity. Wraps `grid versions`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => {
@@ -1085,7 +1089,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_set_env",
-    "Manage environment variables for an entity. Wraps `cloudgrid env`.",
+    "Manage environment variables for an entity. Wraps `grid env`.",
     {
       action: z.enum(["get", "set", "list"]).describe("get, set, or list."),
       name: z.string().describe("Entity slug."),
@@ -1109,7 +1113,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_set_secret",
-    "Set or list secret names for an entity. Never returns secret values. Wraps `cloudgrid secrets`.",
+    "Set or list secret names for an entity. Never returns secret values. Wraps `grid secrets`.",
     {
       action: z.enum(["set", "list"]).describe("set or list (names only)."),
       name: z.string().describe("Entity slug."),
@@ -1129,7 +1133,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_scaffold",
-    "Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps `cloudgrid scaffold`.",
+    "Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps `grid scaffold`.",
     {
       cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
     },
@@ -1139,7 +1143,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_diagnose",
-    "Run CloudGrid diagnostics on the local environment. Wraps `cloudgrid doctor`.",
+    "Run CloudGrid diagnostics on the local environment. Wraps `grid doctor`.",
     {},
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(() => ["doctor"]),
@@ -1147,7 +1151,7 @@ export function registerTools(server, ctx) {
 
   regTool(
     "grid_get_url",
-    "Return the public URL for an entity. Does not open a browser. Wraps `cloudgrid open --print`.",
+    "Return the public URL for an entity. Does not open a browser. Wraps `grid open --print`.",
     { name: z.string().optional().describe("Entity name. Omit for the entity linked to the current directory.") },
     { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
     cliTool(({ name }) => {