@cloudgrid-io/mcp 0.20.6 → 0.20.8

package/src/tools/register.js

@@ -0,0 +1,1165 @@
+// Tool registration: registerTools(server, ctx) wires every tool onto the MCP
+// server for the current edition.
+// Extracted verbatim from src/tools.js (refactor: split tools.js into modules).
+
+import { z } from "zod";
+import { newLoginCode, buildLoginUrl, pollStatusOnce } from "../auth.js";
+import { PLAYBOOK, fetchCorpus, listWorkflows } from "../playbook.js";
+import {
+  APPS_WIDGETS_ENABLED,
+  LIVE_RESULT_URI,
+  GRID_PICKER_URI,
+  LIVE_RESULT_HTML,
+  GRID_PICKER_HTML,
+  WIDGET_CSP,
+} from "./constants.js";
+import { fail, okResult } from "./util.js";
+import { cliTool, tryOpenBrowser } from "./cli.js";
+import {
+  fetchUserOrgs,
+  resolveGridOrAsk,
+  detectSourceManifest,
+  runReport,
+  runClaim,
+  runPlug,
+  runFork,
+  runDownload,
+  runVisibility,
+  runSource,
+} from "./deploy.js";
+
+// ── Registration ───────────────────────────────────────────────────────────────
+// Registers the tools onto `server`. ctx.edition decides whether the CLI-wrapping
+// tools are included (they need a local machine).
+export function registerTools(server, ctx) {
+  // ── Tool naming: grid_* only ───────────────────────────────────────────
+  // Every tool is registered under its `grid_*` name only. The legacy
+  // deprecated `cloudgrid_*` aliases were removed in 0.10.0 — they doubled the
+  // connector tool list and de-duplicated poorly in permission UIs. Clients
+  // enumerate tools dynamically, so discovery is unaffected. `reg` wraps the
+  // object-config `server.registerTool`; `regTool` wraps the positional
+  // `server.tool` shorthand.
+  // Capture shim: route every tool call through the QA session logger when one
+  // is attached (ctx.logger). Fire-and-forget, fully guarded — NEVER blocks or
+  // fails the tool call (2026-07-13 incident rule). No logger → zero overhead.
+  const withCapture = (name, handler) => async (input) => {
+    const started = Date.now();
+    try {
+      const result = await handler(input);
+      try { ctx.logger?.recordCall(name, input, result, Date.now() - started); } catch { /* never */ }
+      return result;
+    } catch (err) {
+      // A thrown handler must record as an ERROR — the old finally-based capture
+      // saw result=undefined and mis-recorded it as "ok". Synthesize an error
+      // result, then rethrow so the tool contract is unchanged.
+      try { ctx.logger?.recordCall(name, input, { isError: true }, Date.now() - started); } catch { /* never */ }
+      throw err;
+    }
+  };
+
+  // Every primary tool records its shape here so a deprecated alias can be
+  // registered under an OLD name with the same handler + schema but a
+  // redirect-only, keyword-free description (so the model never mis-selects it).
+  const registered = {};
+  const reg = (name, config, handler) => {
+    registered[name] = { kind: "reg", config, handler };
+    server.registerTool(name, config, withCapture(name, handler));
+  };
+
+  const regTool = (name, description, schema, annotations, handler) => {
+    registered[name] = { kind: "tool", description, schema, annotations, handler };
+    server.tool(name, description, schema, annotations, withCapture(name, handler));
+  };
+
+  // Register OLD tool names as deprecated aliases of their new (clearer) names.
+  // Same handler/schema; description is redirect-only so it never wins selection.
+  // Skips silently if the primary isn't registered in this edition (e.g. a
+  // CLI-only tool on the web edition).
+  const registerAlias = (oldName, newName) => {
+    const r = registered[newName];
+    if (!r) return;
+    const redirect = `Deprecated alias of ${newName}. Always call ${newName} instead; this name is kept for backward compatibility.`;
+    if (r.kind === "reg") {
+      server.registerTool(oldName, { ...r.config, description: redirect }, withCapture(oldName, r.handler));
+    } else {
+      server.tool(oldName, redirect, r.schema, r.annotations, withCapture(oldName, r.handler));
+    }
+  };
+
+  // ── Widget resources (web edition, ChatGPT Apps SDK) ──────────────────────
+  if (ctx.edition === "web") {
+    server.registerResource("cloudgrid-live-result", LIVE_RESULT_URI, {
+      description: "Live result card after a CloudGrid drop — shows URL, grid link, and visibility controls.",
+      mimeType: "text/html;profile=mcp-app",
+    }, async () => ({
+      contents: [{
+        uri: LIVE_RESULT_URI,
+        mimeType: "text/html;profile=mcp-app",
+        text: LIVE_RESULT_HTML,
+        _meta: { ui: { csp: WIDGET_CSP } },
+      }],
+    }));
+
+    server.registerResource("cloudgrid-org-picker", GRID_PICKER_URI, {
+      description: "Org picker card — lets the user choose which organization to publish into.",
+      mimeType: "text/html;profile=mcp-app",
+    }, async () => ({
+      contents: [{
+        uri: GRID_PICKER_URI,
+        mimeType: "text/html;profile=mcp-app",
+        text: GRID_PICKER_HTML,
+        _meta: { ui: { csp: WIDGET_CSP } },
+      }],
+    }));
+  }
+
+  // ── Direct-API tools (both editions) ──────────────────────────────────────
+
+  // Claim — both editions.
+  reg(
+    "grid_claim_anonymous_deploy",
+    {
+      description: "Claim an anonymous drop into the signed-in account, so it becomes owned and stops expiring on the anonymous schedule. Use after the user signs in to keep something they dropped anonymously. The public URL does not change. The claim token IS the drop's owner_token (one bearer capability for both edit and claim — anonymous edits refresh it, so always use the newest). Requires sign-in (grid_login). Calls the API directly.",
+      inputSchema: {
+        claim_token: z.string().optional().describe("The claim/owner token from an anonymous drop (owner_token in the drop result; also embedded in claim_url)."),
+        claim_url: z.string().optional().describe("The claim_url from an anonymous drop; the token is read from it."),
+        entity_id: z.string().optional().describe("The entity id of the anonymous drop to claim. Defaults to this session's last anonymous drop."),
+      },
+      outputSchema: {
+        claimed: z.number().describe("Number of drops claimed."),
+        urls: z.array(z.string()).describe("URLs of the claimed drops."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runClaim(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // grid_note — the optional session-end self-report. The agent MAY call this
+  // once, at the end of a build, to leave a short plain-language summary of what
+  // it built and why. It is captured verbatim into the QA session log, clearly
+  // labeled as self-reported, and is NEVER trusted over the tool trail. It has
+  // no side effects and returns immediately. Absent a logger it is a harmless
+  // acknowledgement.
+  regTool(
+    "grid_note",
+    "Optionally leave a one-paragraph summary of what you built this session and why. Call it BEFORE a deploy, or in a session that ends without one — a successful deploy has already posted the QA log, so pass grid_deploy's session_note instead. Recorded for CloudGrid QA. No side effects.",
+    { summary: z.string().describe("A short plain-language summary of what was built and why.") },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    async (input) => {
+      try { ctx.logger?.setNarrative(input?.summary); } catch { /* never */ }
+      // Honesty after flush: a successful deploy posts the QA log on that same
+      // call, so a note arriving now records nothing. Say so rather than lie.
+      if (ctx.logger?.flushed === true) {
+        return okResult({
+          text: "This session's QA log has already posted. Pass session_note on your next grid_deploy instead.",
+        });
+      }
+      return okResult({ text: "Noted." });
+    },
+  );
+
+  // ── grid_deploy — the unified create/re-plug verb (spec v2 §3) ────────────
+  // Direct-API on BOTH editions (POST /api/v2/plug). Replaces the former
+  // CLI-wrapping grid_deploy: create and re-plug are one verb, keyed by
+  // target_entity_id, and work identically on the hosted transport.
+  const plugInputSchema = {
+    html: z.string().optional().describe(
+      "A single self-contained HTML document to publish as an inspiration — the fast single-file path. " +
+      "Pass the COMPLETE raw HTML inline (CSS+JS inline, images/fonts as data: URIs); a small fragment is " +
+      "wrapped into a full document. Do NOT base64-encode it, and do NOT pass an `@`-prefixed path or a " +
+      "file path here. Mutually exclusive with `path` and `artifact_files`. Materialized as one index.html " +
+      "and published instantly on any edition, anonymously (claimable) or into your grid when signed in.",
+    ),
+    filename: z.string().optional().describe("Filename for the single-file `html` path. Defaults to index.html."),
+    ...(ctx.edition === "web"
+      ? {}
+      : {
+          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`.",
+          ),
+        }),
+    artifact_files: z.array(z.object({
+      path: z.string().describe("Repo-relative path, e.g. index.html or services/web/index.js."),
+      content: z.string().describe("File content. Base64 when encoding is base64, otherwise UTF-8 text."),
+      encoding: z.enum(["utf8", "base64"]).optional().describe("Content encoding. Default utf8."),
+    })).optional().describe(
+      "The source inline, one entry per file — for hosted/no-filesystem transports (a multi-file app). " +
+      "For a single HTML page prefer `html`." +
+      (ctx.edition === "web" ? "" : " Prefer `path` on the local edition.") +
+      " Mutually exclusive with `html` and `path`.",
+    ),
+    cloudgrid_yaml: z.string().optional().describe(
+      "Inline cloudgrid.yaml (the entity manifest). Optional — server auto-detection applies when omitted. " +
+      "On re-plug, a name: change is a warning only; it never renames the entity or moves the URL.",
+    ),
+    target_entity_id: z.string().optional().describe(
+      "Present → RE-PLUG: update this exact entity in place (same entity_id, slug, URL, deploy history). " +
+      "Absent → CREATE a new entity. This is the durable handle a previous plug returned — persist it. " +
+      "Re-plugging an anonymously-created drop needs its owner_token instead of sign-in.",
+    ),
+    grid: z.string().optional().describe(
+      "On create: the grid slug to plug into (omit to use the caller's active grid). On re-plug the entity " +
+      "never moves grids, but pass its home grid here when it differs from your active grid (the API " +
+      "checks your membership in the entity's grid). Anonymous → always the Guest grid.",
+    ),
+    slug: z.string().optional().describe(
+      "Alternative RE-PLUG handle: paired with `grid`, resolves to an existing entity (the pickup " +
+      "contract's replug_handle) and updates it in place — for a client that holds only grid+slug, not the " +
+      "raw entity_id. target_entity_id takes precedence. A grid+slug that does NOT resolve to an existing " +
+      "entity is treated as a CREATE (never a false-positive re-plug).",
+    ),
+    hints: z.object({
+      kind: z.enum(["inspiration", "app", "agent"]).optional().describe("Force the detected kind; omit to let the server auto-detect."),
+      yaml: z.string().optional().describe("An inline cloudgrid.yaml override used as a detection hint."),
+    }).optional().describe("Classification hints for the CREATE path (not entity targeting — that's target_entity_id)."),
+    anon: z.boolean().optional().describe(
+      "Create an anonymous Guest-Grid drop (no auth). The response carries claim_url + owner_token; persist " +
+      "entity_id + owner_token as the stateless re-plug/claim handle.",
+    ),
+    owner_token: z.string().optional().describe(
+      "The owner token of an anonymously-created drop — authorizes an anonymous re-plug (with " +
+      "target_entity_id). Re-minted on every anonymous edit; always persist the newest one from the result.",
+    ),
+    confirm_new_app: z.boolean().optional().describe(
+      "Set true to confirm deploying a source that already contains a cloudgrid.yaml as a NEW runtime app. " +
+      "On a create, if the source has a cloudgrid.yaml and this is not set, grid_deploy returns needs_confirmation " +
+      "so you can ask the user first (or use target_entity_id to re-plug an existing entity).",
+    ),
+    user_request: z.string().optional().describe(
+      "A brief version of the user's request that led to this deploy. Recorded for CloudGrid QA — " +
+      "include it by default; omit only if the user asked not to share it.",
+    ),
+    session_note: z.string().optional().describe(
+      "One short paragraph on what you built and why. Recorded for CloudGrid QA alongside the deploy.",
+    ),
+  };
+
+  // grid_deploy is the create/re-plug verb (renamed from the former `plug` tool;
+  // the deprecated alias was removed once the corpus migrated to grid_deploy).
+  // MCP-tool name only — the CLI verb `grid plug` is unchanged.
+  const plugConfig = {
+      description:
+        "Deploy an app, website, game, or single HTML page to CloudGrid and get a live public URL. " +
+        "Use for any request to deploy, publish, host, ship, launch, go live, or share a working link — " +
+        "a single HTML page OR a full app. Without target_entity_id: CREATE a new entity with a new URL. " +
+        "With target_entity_id (or grid+slug): UPDATE the existing deployment IN PLACE, keeping the same URL — " +
+        "this is the only deploy/publish tool, so do not look for a separate 'update' or 'redeploy' tool. " +
+        "Sources (pass exactly one): `html` — a single self-contained HTML page (instant, any edition)" +
+        (ctx.edition === "web"
+          ? " or `artifact_files` — a multi-file app inline. "
+          : ", `path` — a local folder/file, or `artifact_files` — inline files. ") +
+        "If you need to edit a page but don't have its HTML, call grid_get_app_source first, then deploy with " +
+        "target_entity_id. (CloudGrid calls this operation 'plug'.)",
+      inputSchema: plugInputSchema,
+      outputSchema: {
+        entity_id: z.string().optional().describe("Globally unique — pass back as target_entity_id to re-plug."),
+        slug: z.string().optional().describe("Grid-scoped slug."),
+        grid: z.string().nullable().optional().describe("Home grid slug; null for an anonymous Guest-Grid drop."),
+        url: z.string().optional().describe("Canonical serving URL (stable across re-plugs; server-composed, flat-arch-aware)."),
+        poll_url: z.string().optional().describe("Deploy status path while building (runtimes only)."),
+        status: z.string().optional().describe("live | building | created | updated …"),
+        claim_url: z.string().optional().describe("Anon create only: sign-in link to claim ownership."),
+        claim_message: z.string().optional().describe("Anon create only: the claim nudge to relay."),
+        owner_token: z.string().optional().describe("Anonymous drops: the bearer owner token (re-plug + claim). Re-minted on every anonymous edit — persist the newest."),
+        console_url: z.string().optional().describe("Web authed inspiration create: URL to manage all apps in the grid."),
+        current_visibility: z.string().optional().describe("Web authed inspiration create: the visibility set after publish (link)."),
+        visibility_options: z.array(z.object({
+          value: z.string().describe("Visibility value to pass to grid_set_sharing."),
+          label: z.string().describe("Human-readable label."),
+        })).optional().describe("Web authed inspiration create: available visibility levels."),
+        // grid_deploy has ONE outputSchema but THREE response modes; the SDK renders
+        // this schema with additionalProperties:false and the client rejects any
+        // undeclared key (MCP -32602). Declare the two non-deploy-result modes so
+        // they validate: (1) the grid-picker "which grid?" ask (resolveGridOrAsk),
+        // and (2) the signed-in CLI-fallback recovery.
+        needs_grid: z.boolean().optional().describe("Grid-picker ask: a signed-in user with >1 grid must choose one before this create proceeds. Pass the chosen slug back in `grid`."),
+        needs_org: z.boolean().optional().describe("Alias of needs_grid (legacy org-picker widget)."),
+        grids: z.array(z.object({
+          slug: z.string(),
+          name: z.string(),
+          role: z.string(),
+          render_ready: z.boolean(),
+          is_active: z.boolean(),
+        })).optional().describe("Grid-picker ask: the grids to choose from."),
+        orgs: z.array(z.object({
+          slug: z.string(),
+          name: z.string(),
+          role: z.string(),
+          render_ready: z.boolean(),
+          is_active: z.boolean(),
+        })).optional().describe("Alias of grids (legacy org-picker widget)."),
+        via: z.string().optional().describe("Recovery marker: 'cli-fallback' when a signed-in create was published through the bundled CloudGrid CLI."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+      ...(ctx.edition === "web" && APPS_WIDGETS_ENABLED ? {
+        _meta: {
+          ui: { resourceUri: LIVE_RESULT_URI, csp: WIDGET_CSP },
+          "openai/outputTemplate": LIVE_RESULT_URI,
+        },
+      } : {}),
+  };
+  const plugHandler = async (input) => {
+      try {
+        // QA courier capture: lift the model-supplied user_request + session_note
+        // into the session logger FIRST — before the manifest/grid gates — so even
+        // a call that short-circuits into a picker/confirm still records them.
+        try {
+          if (input?.user_request) ctx.logger?.setUserRequest(input.user_request);
+          if (input?.session_note) ctx.logger?.setNarrative(input.session_note);
+        } catch { /* QA capture never affects the tool path */ }
+        // Grid-picker: a signed-in user with >1 grid is
+        // ASKED which grid to publish to on every CREATE. Only for authed creates
+        // (no target_entity_id, not anon). Edits NEVER ask — the grid is fixed by
+        // the entity. Anon proceeds as a Guest-Grid drop. Explicit valid grid
+        // proceeds. A single grid proceeds (with a warning if it isn't set up yet).
+        const isEdit =
+          typeof input?.target_entity_id === "string" && input.target_entity_id.length > 0;
+        // A grid+slug pair is a probable re-plug handle (the replug_handle,
+        // resolved inside runPlug) — treat it like an edit for the confirm gate.
+        const isReplugHandle = Boolean(input?.grid && input?.slug);
+        // Manifest-aware confirm: a CREATE whose source already carries a
+        // cloudgrid.yaml is a pre-configured runtime app. Don't silently
+        // auto-create — ask once. (Skip when re-plugging, or when confirmed.)
+        if (!isEdit && !isReplugHandle && input?.confirm_new_app !== true) {
+          const manifest = detectSourceManifest(input);
+          if (manifest) {
+            const svc = manifest.services?.length
+              ? ` (services: ${manifest.services.join(", ")}${manifest.needs?.length ? `; needs: ${manifest.needs.join(", ")}` : ""})`
+              : "";
+            return okResult({
+              text:
+                `This folder is a CloudGrid runtime app — it already has a cloudgrid.yaml` +
+                (manifest.name ? ` for "${manifest.name}"` : "") + `${svc}. ` +
+                `Deploy it as a NEW app on the grid? If yes, re-call grid_deploy with confirm_new_app: true. ` +
+                `To update an existing app instead, pass its target_entity_id.`,
+              structured: {
+                needs_confirmation: true,
+                manifest_detected: true,
+                manifest: { name: manifest.name, services: manifest.services, needs: manifest.needs },
+              },
+            });
+          }
+        }
+        if (input?.anon !== true && !isEdit) {
+          const token = await ctx.getToken();
+          if (token) {
+            const decision = await resolveGridOrAsk(ctx, {
+              token,
+              suppliedGrid: input?.grid,
+              edition: ctx.edition,
+            });
+            if (decision.picker) {
+              // Do NOT silently default to the active grid — surface the ask.
+              return okResult(decision.picker);
+            }
+            if (decision.single) {
+              // Proceed into the single grid; warn (don't block) if not set up yet.
+              input = { ...(input || {}), grid: decision.single.slug };
+              if (decision.single.render_ready === false) {
+                const res = await runPlug(ctx, input || {});
+                return okResult({
+                  ...res,
+                  text:
+                    `Warning: your only grid "${decision.single.slug}" isn't fully set up yet — the page may not load until provisioning completes.\n` +
+                    res.text,
+                });
+              }
+            } else if (decision.grid) {
+              input = { ...(input || {}), grid: decision.grid };
+            }
+          }
+        }
+        const res = await runPlug(ctx, input || {});
+        return okResult(res);
+      } catch (err) {
+        return fail(err.message);
+      }
+  };
+  reg("grid_deploy", plugConfig, plugHandler);
+
+  // ── grid_copy_app / grid_download_source — direct-API verbs (spec v2 §5–6) ──────
+  reg(
+    "grid_copy_app",
+    {
+      description:
+        "Start a NEW entity from an existing runtime (copy-on-write, lineage recorded). Lands in the " +
+        "source's home grid by default; cross-grid only for system templates or forkable:'public' sources. " +
+        "Requires sign-in. Kind-aware: forks a runtime (app/agent) OR an inspiration — " +
+        "tries POST /api/v2/runtimes/:id/fork and falls back to /api/v2/inspirations/:id/fork.",
+      inputSchema: {
+        id: z.string().describe("The source runtime: a canonical UUID or <grid-slug>/<entity-slug>."),
+        into_org_slug: z.string().optional().describe("Destination grid slug. Required only when you belong to more than one grid."),
+        name: z.string().optional().describe("Slug for the new entity. Omit to derive one from the source."),
+        source_version_id: z.string().optional().describe("Fork an older version instead of HEAD, e.g. v_a1b2c3d."),
+      },
+      outputSchema: {
+        entity_id: z.string().nullable().describe("The new entity's id."),
+        name: z.string().nullable().describe("The new entity's slug."),
+        kind: z.string().nullable().describe("app | agent | inspiration."),
+        grid_slug: z.string().nullable().describe("The grid the fork landed in."),
+        forked_from: z.string().nullable().describe("Source entity_id."),
+        forked_from_version_id: z.string().nullable().describe("Source version, when a specific one was forked."),
+        current_version_id: z.string().nullable().describe("The fork's current version id."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+        return okResult(await runFork(ctx, input));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  reg(
+    "grid_download_source",
+    {
+      description:
+        "Fetch the source bundle last deployed for a runtime: one signed, time-limited (15-minute) read URL " +
+        "per service tarball. No entity is created and no registry state changes. Requires sign-in. Calls " +
+        "GET /api/v2/runtimes/:id/source directly.",
+      inputSchema: {
+        id: z.string().describe("The runtime to download: a canonical UUID or <grid-slug>/<entity-slug>."),
+        version: z.string().optional().describe("Download an older version's bundle instead of HEAD, e.g. v_a1b2c3d."),
+      },
+      outputSchema: {
+        entity_id: z.string().nullable().describe("The runtime's entity id."),
+        name: z.string().nullable().describe("The runtime's slug."),
+        services: z.record(z.string()).describe("Service name → signed read URL (valid ~15 minutes)."),
+        domain: z.string().nullable().optional().describe("The runtime's domain, if any."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        if (!input?.id) return fail("`id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+        return okResult(await runDownload(ctx, input));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // Source — both editions. Fetches a drop's current deployed HTML inline so an
+  // agent that lost the content can edit it and re-plug in place.
+  reg(
+    "grid_get_app_source",
+    {
+      description:
+        "Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and " +
+        "re-plug the SAME URL when you no longer have its source in context (e.g. the user asks to 'change the " +
+        "color' of a page — even in a fresh chat with only its URL). Defaults to this session's last drop; " +
+        "otherwise pass the public url (or grid+slug). Given just a URL with no session, it resolves the " +
+        "entity_id via the pickup contract and also returns the entity's kind, single_html, capabilities " +
+        "(replug/fork), and replug_handle — read those to decide whether to edit in place (single-HTML + " +
+        "capabilities.replug), fall back for a multi-file app/agent (use source_download_url + the local " +
+        "edition/CLI), or offer a fork when it isn't yours. For multi-file or runtime (app/agent) source " +
+        "bundles, use grid_download_source (signed tarball URLs). Reads the HTML from the API server-side; " +
+        "read-only, creates nothing.",
+      inputSchema: {
+        entity_id: z.string().optional().describe("The drop's durable id. Defaults to this session's last drop."),
+        url: z.string().optional().describe("The public URL of the drop (e.g. https://<grid>.cloudgrid.io/<slug>). Defaults to this session's last drop URL."),
+        grid: z.string().optional().describe("Grid slug — used only to construct the URL when neither url nor session state is available."),
+        slug: z.string().optional().describe("Entity slug — used with grid to construct the URL when neither url nor session state is available."),
+      },
+      outputSchema: {
+        url: z.string().describe("The URL that was fetched."),
+        entity_id: z.string().nullable().describe("The drop's entity id (echoed from input/session, if known)."),
+        bytes: z.number().describe("Total size of the live document in bytes."),
+        truncated: z.boolean().describe("True if the body exceeded 1.5MB and was cut — the drop may be multi-file."),
+        html: z.string().describe("The current deployed HTML (truncated to 1.5MB when oversized)."),
+        kind: z.string().optional().describe("Resolved via the pickup contract: inspiration | app | agent."),
+        single_html: z.boolean().optional().describe("Resolved via the pickup contract: true when this is a single editable HTML document (edit-in-place); false → multi-file."),
+        capabilities: z.object({
+          replug: z.boolean().describe("Whether the caller may re-plug (write) this entity in place."),
+          fork: z.boolean().optional().describe("Whether the caller may fork it."),
+          reason: z.string().optional().describe("Why an action is unavailable, e.g. not_owner."),
+        }).optional().describe("Resolved via the pickup contract: what the caller may do with this entity."),
+        replug_handle: z.object({
+          target_entity_id: z.string().optional().describe("Pass as grid_deploy's target_entity_id to re-plug in place."),
+          grid: z.string().optional().describe("The entity's home grid slug."),
+          slug: z.string().optional().describe("The entity's grid-scoped slug."),
+        }).optional().describe("Resolved via the pickup contract: the durable re-plug handle."),
+        source_download_url: z.string().optional().describe("Resolved via the pickup contract: the source-download route (used for the multi-file fallback message)."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runSource(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // Login — both editions. Local opens a browser and saves to the credentials
+  // file; web returns the URL and saves to the session.
+  reg(
+    "grid_login",
+    {
+      description: "Start a CLI-free CloudGrid sign-in. Use when the user wants to log in, sign in, or authenticate, or to claim an anonymous drop. Returns a URL to open in the browser; then call grid_login_status to finish. Uses CloudGrid's existing OAuth.",
+      inputSchema: {},
+      outputSchema: {
+        login_url: z.string().describe("URL to open in a browser to complete sign-in."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async () => {
+      const code = newLoginCode();
+      ctx.state.pendingLoginCode = code;
+      const url = buildLoginUrl(code);
+      if (ctx.canOpenBrowser) tryOpenBrowser(url);
+      return {
+        content: [{ type: "text", text:
+          `To sign in, open this URL in your browser and finish with Google:\n${url}\n\n` +
+          `After you complete it, run grid_login_status to finish signing in.`,
+        }],
+        structuredContent: { login_url: url },
+      };
+    },
+  );
+
+  reg(
+    "grid_login_status",
+    {
+      description: "Finish a sign-in started by grid_login. Polls once: if you have completed the browser sign-in, it saves your session; otherwise it tells you to finish and try again.",
+      inputSchema: {
+        code: z.string().optional().describe("The sign-in code. Defaults to the most recent grid_login."),
+      },
+      outputSchema: {
+        status: z.enum(["authenticated", "pending"]).describe("Current sign-in state."),
+        email: z.string().optional().describe("Signed-in email, when authenticated."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      const code = input?.code || ctx.state.pendingLoginCode;
+      if (!code) return fail("No sign-in is in progress. Run grid_login first.");
+      let status;
+      try {
+        status = await pollStatusOnce(code);
+      } catch (err) {
+        return fail(err.message);
+      }
+      if (status.status === "authenticated" && status.jwt) {
+        let info;
+        try {
+          info = await ctx.saveToken(status.jwt);
+        } catch (err) {
+          return fail(`Signed in, but could not save credentials: ${err.message}`);
+        }
+        ctx.state.pendingLoginCode = null;
+        const who = info?.email ? ` as ${info.email}` : "";
+        return {
+          content: [{ type: "text", text: `Signed in${who}. ${ctx.savedLocationNote()}` }],
+          structuredContent: { status: "authenticated", ...(info?.email ? { email: info.email } : {}) },
+        };
+      }
+      if (status.status === "pending" || status.status === "not_started") {
+        return {
+          content: [{ type: "text", text:
+            "Still waiting for you to finish signing in. Open the URL from grid_login " +
+            "in your browser, complete it with Google, then run grid_login_status again.",
+          }],
+          structuredContent: { status: "pending" },
+        };
+      }
+      return fail("The sign-in window expired (5 minutes). Run grid_login to start again.");
+    },
+  );
+
+  reg(
+    "grid_set_sharing",
+    {
+      description: "Change who can see a CloudGrid inspiration: private, space, authenticated, org, or link (anyone with the URL). Use when the user wants to make a drop private, restrict who sees it, or open it up — including right after a drop, with no target id needed. Defaults to the drop made in this session. Requires sign-in. Calls the API directly.",
+      inputSchema: {
+        visibility: z.enum(["private", "space", "authenticated", "org", "link"]).describe("The new scope."),
+        target: z.string().optional().describe("Entity id. Defaults to this session's last drop."),
+        org: z.string().optional().describe("Org of the entity. Defaults to the active org."),
+      },
+      outputSchema: {
+        visibility: z.string().describe("The visibility that was set."),
+        url: z.string().optional().describe("URL of the entity, if returned."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runVisibility(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // Org listing — both editions.
+  reg(
+    "grid_list_grids",
+    {
+      description: "List the signed-in user's grids, each with slug, name, role, and provisioning status. A grid that is still provisioning (render_ready false) may not serve pages yet — prefer a ready grid, and if the user insists on a not-ready one, warn them that pages may not load. Requires sign-in.",
+      inputSchema: {},
+      outputSchema: {
+        orgs: z.array(z.object({
+          slug: z.string().describe("Org slug."),
+          name: z.string().describe("Human-readable org name."),
+          role: z.string().describe("User's role in the org."),
+          is_active: z.boolean().optional().describe("True if this is the user's currently active org."),
+          render_ready: z.boolean().describe("True if the org's DNS and TLS are provisioned and pages will load. False means the org is still being set up."),
+        })).describe("The user's org memberships."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async () => {
+      const token = await ctx.getToken();
+      if (!token) {
+        return fail("You are not signed in. Run grid_login first.");
+      }
+      const grids = await fetchUserOrgs(token);
+      if (grids.length === 0) {
+        // Structured output stays `orgs` (its declared schema); user text says grid.
+        return okResult({ text: "No grids found.", structured: { orgs: [] } });
+      }
+      const activeGrid = await ctx.getActiveGrid();
+      const annotated = grids.map((o) => ({
+        ...o,
+        is_active: o.slug === activeGrid,
+      }));
+      // Sort: active grid first, then ready grids, then not-ready grids.
+      annotated.sort((a, b) => {
+        if (a.is_active !== b.is_active) return b.is_active ? 1 : -1;
+        if (a.render_ready !== b.render_ready) return b.render_ready ? 1 : -1;
+        return 0;
+      });
+      const lines = annotated.map((o) => {
+        const tags = [];
+        if (o.is_active) tags.push("your active grid");
+        if (!o.render_ready) tags.push("not set up yet");
+        const suffix = tags.length ? ` (${tags.join(", ")})` : "";
+        return `${o.slug} — ${o.name} (${o.role})${suffix}`;
+      });
+      const readyCount = annotated.filter((o) => o.render_ready).length;
+      if (readyCount === 0 && annotated.length > 0) {
+        lines.push("\nNone of your grids are fully set up yet. You can use an anonymous drop as a fallback, or wait until provisioning completes.");
+      }
+      // Structured output stays `orgs` (its declared schema); user text says grid.
+      return okResult({ text: lines.join("\n"), structured: { orgs: annotated } });
+    },
+  );
+
+  // ── Agent Core orientation tools (authed editions: local + web) ───────────
+  // These serve the delivery ladder's Orient + Load rungs. They are registered
+  // before the local-only cutoff below, so BOTH the local and web (hosted-auth)
+  // editions expose them. The anon docs edition (src/docs.js) does NOT call
+  // registerTools, so it never gets them (spec F3).
+
+  reg(
+    "grid_start",
+    {
+      description:
+        "Orient before building with CloudGrid. Call this FIRST when the user wants to build, create, make, deploy, publish, or generate something. Returns the CloudGrid playbook (operating rules + golden path) and the index of available workflows (presentation, …). After this, match the user's intent to a workflow and call grid_get_template to load it.",
+      inputSchema: {},
+      outputSchema: {
+        playbook: z.string().describe("The operating rules and golden path for building with CloudGrid."),
+        workflows: z
+          .array(
+            z.object({
+              name: z.string().describe("Workflow name to pass to grid_get_template."),
+              when: z.string().describe("When to use this workflow."),
+              summary: z.string().describe("What the workflow does."),
+            }),
+          )
+          .describe("Available workflows."),
+        context: z
+          .object({
+            active_grid: z.string().nullable().describe("The user's active grid/org slug, or null."),
+            signed_in: z.boolean().describe("Whether the current session is signed in."),
+          })
+          .optional()
+          .describe("Live context from the current session."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async () => {
+      const workflows = listWorkflows();
+      let signedIn = false;
+      let activeGrid = null;
+      try {
+        signedIn = Boolean(await ctx.getToken());
+      } catch {
+        signedIn = false;
+      }
+      try {
+        activeGrid = (await ctx.getActiveGrid()) ?? null;
+      } catch {
+        activeGrid = null;
+      }
+      const structured = {
+        playbook: PLAYBOOK,
+        workflows,
+        context: { active_grid: activeGrid, signed_in: signedIn },
+      };
+      const wfLines = workflows.length
+        ? workflows.map((w) => `  - ${w.name}: ${w.when || w.summary}`).join("\n")
+        : "  (none available)";
+      const text =
+        `${PLAYBOOK}\n\nAvailable workflows:\n${wfLines}\n\n` +
+        `Next: match the intent to a workflow and call grid_get_template({kind:"workflow", name}).`;
+      return okResult({ text, structured });
+    },
+  );
+
+  reg(
+    "grid_get_template",
+    {
+      description:
+        "Load a specific CloudGrid workflow, template, example, rule, or doc by name — deterministic retrieval from the bundled corpus (complements the fuzzy search_cloudgrid_documentation). Use after grid_start to pull the exact recipe/template you need, e.g. grid_get_template({kind:\"workflow\", name:\"presentation\"}) then grid_get_template({kind:\"template\", name:\"deck\"}).",
+      inputSchema: {
+        kind: z
+          .enum(["workflow", "template", "example", "rule", "troubleshooting", "doc"])
+          .describe("What to fetch."),
+        name: z.string().describe("The entry name, e.g. 'presentation' or 'deck'."),
+      },
+      outputSchema: {
+        name: z.string().describe("The requested name."),
+        kind: z.string().describe("The requested kind."),
+        content: z.string().describe("The full content of the corpus entry."),
+      },
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      const kind = input?.kind;
+      const name = input?.name;
+      if (!kind || !name) return fail("Both `kind` and `name` are required.");
+      const content = fetchCorpus(kind, name);
+      if (content == null) {
+        return fail(
+          `No ${kind} named "${name}" in the corpus. Call grid_start to see available workflows.`,
+        );
+      }
+      return okResult({ text: content, structured: { name, kind, content } });
+    },
+  );
+
+  // ── Consent-gated error reporting (Task 34) ───────────────────────────────
+  // Both editions. The agent calls this ONLY after the user explicitly agrees
+  // to report a genuine failure (the errorGuidance offer + the PLAYBOOK rule
+  // gate on consent). Posts the error + failed-request context to the CloudGrid
+  // team; the full conversation is never sent unless include_conversation is
+  // explicitly set true (which the agent only does on an explicit yes).
+  reg(
+    "grid_report",
+    {
+      description:
+        "Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. When a build/deploy or platform call fails unexpectedly, ASK the user first; call this only after they say yes. Send a short `message` (what failed) plus `context` (the tool, inputs, grid, original request, error code/detail). By default it does NOT include the conversation — set include_conversation:true ONLY if the user explicitly agreed to send the chat. Obvious secrets in context are scrubbed before sending. Never sends anything the user didn't agree to.",
+      inputSchema: {
+        message: z
+          .string()
+          .describe("Short summary of what failed (required). Do not paste the whole conversation here."),
+        context: z
+          .object({
+            tool: z.string().optional().describe("The CloudGrid tool that failed, e.g. grid_deploy."),
+            inputs: z.any().optional().describe("The failing inputs (e.g. the HTML/args). Keep it minimal; secrets are scrubbed."),
+            grid: z.string().optional().describe("The grid/org slug involved, if any."),
+            original_request: z.string().optional().describe("What the user asked for, in one line."),
+            error_code: z.string().optional().describe("The server error code, e.g. INTERNAL_ERROR."),
+            error_detail: z.string().optional().describe("The error message / detail surfaced to the agent."),
+          })
+          .partial()
+          .optional()
+          .describe("The failed-request context. Secret-looking values are scrubbed client-side and again server-side."),
+        include_conversation: z
+          .boolean()
+          .optional()
+          .describe("Default false. Set true ONLY if the user explicitly agreed to include the full conversation."),
+        category: z
+          .string()
+          .optional()
+          .describe("Optional category, e.g. the failing tool name (\"deploy\"). Defaults to \"mcp\"."),
+        trace_id: z
+          .string()
+          .optional()
+          .describe("The server's trace/deploy id from the failed response, if any (helps support pivot to the trace)."),
+        failed_step: z
+          .string()
+          .optional()
+          .describe("The server-side pipeline step that failed, if known."),
+        http_status: z
+          .number()
+          .optional()
+          .describe("The HTTP status of the final failed request, if applicable."),
+      },
+      outputSchema: {
+        status: z
+          .enum(["recorded", "rate_limited", "unauthorized", "error", "skipped", "disabled"])
+          .describe("Outcome of the report."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return await runReport(ctx, {
+          message: input?.message,
+          context: input?.context,
+          include_conversation: input?.include_conversation === true,
+          category: input?.category,
+          trace_id: input?.trace_id,
+          failed_step: input?.failed_step,
+          http_status: input?.http_status,
+        });
+      } catch (err) {
+        // Belt-and-suspenders: never throw noisily out of a report attempt.
+        return okResult({
+          text: "Couldn't send the report to the CloudGrid team right now. You can try again later.",
+          structured: { status: "error" },
+        });
+      }
+    },
+  );
+
+  // ── Kept alias (both editions): grid_fetch has real muscle memory in saved
+  //    prompts and older docs. Every other legacy alias was dropped in 0.20.8 -
+  //    16 alias schemas were pure ListTools context weight on every session.
+  registerAlias("grid_fetch", "grid_get_template");
+
+  if (ctx.edition !== "local") return; // web edition stops here — no CLI tools
+
+  // ── CLI-wrapping tools (local edition only) ───────────────────────────────
+
+  regTool(
+    "grid_create_project",
+    "Register a new CloudGrid app or agent, optionally seeding a web service. Wraps `cloudgrid init`.",
+    {
+      kind: z.enum(["app", "agent"]).describe("Entity kind."),
+      name: z.string().describe("Slug: 3-40 lowercase alphanumerics and hyphens."),
+      type: z.enum(["node", "nextjs", "python", "static"]).optional().describe("Seed a web service of this type."),
+      description: z.string().optional().describe("Initial one-line description."),
+      dir: z.string().optional().describe("Target directory. Defaults to ./<name>."),
+      org: z.string().optional().describe("Override the active org for this init."),
+      cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ kind, name, type, description, dir, org }) => {
+      const args = ["init", kind, name];
+      if (type) args.push("--type", type);
+      if (description) args.push("--description", description);
+      if (dir) args.push("--dir", dir);
+      // CLI 0.12 dropped `--org` in favour of `--grid` (same slug).
+      if (org) args.push("--grid", org);
+      return args;
+    }, { cwdParam: true }),
+  );
+
+  // NOTE: grid_deploy is no longer CLI-wrapping — the unified direct-API verb
+  // (create + re-plug via POST /api/v2/plug) is registered above for BOTH
+  // editions, per spec v2 §3.
+
+  regTool(
+    "grid_view_logs",
+    "Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps `cloudgrid 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."),
+      since: z.string().optional().describe("Only logs newer than this, e.g. 5m, 1h, 2d."),
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(({ name, tail, since }) => {
+      const args = ["logs"];
+      if (name) args.push(name);
+      args.push("--tail", String(tail ?? 100));
+      if (since) args.push("--since", since);
+      return args;
+    }),
+  );
+
+  regTool(
+    "grid_share",
+    "Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps `cloudgrid visibility set`.",
+    {
+      name: z.string().describe("Entity slug."),
+      mode: z.enum(["link", "private", "authenticated", "grid"]).optional().describe("Visibility mode. Default link."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ name, mode }) => ["visibility", "set", name, mode ?? "link"]),
+  );
+
+  regTool(
+    "grid_feedback",
+    "List recent feedback events for the active org. Read-only. Wraps `cloudgrid 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."),
+      org: z.string().optional().describe("Read another org's feed where you have access."),
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(({ since, limit, org }) => {
+      const args = ["feedback", "list"];
+      if (since) args.push("--since", since);
+      if (limit) args.push("--limit", String(limit));
+      // CLI 0.12 dropped `--org` in favour of `--grid` (same slug).
+      if (org) args.push("--grid", org);
+      return args;
+    }),
+  );
+
+  // ── New CLI-wrapping tools (local edition only) ───────────────────────────
+
+  regTool(
+    "grid_whoami",
+    "Show the signed-in user and active org. Wraps `cloudgrid whoami`.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(() => ["whoami"]),
+  );
+
+  regTool(
+    "grid_switch_grid",
+    "Switch the active org. Wraps `cloudgrid use`.",
+    { org: z.string().describe("Org slug to switch to.") },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ org }) => ["use", org]),
+  );
+
+  regTool(
+    "grid_logout",
+    "Sign out and clear local credentials. Wraps `cloudgrid logout`.",
+    {},
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(() => ["logout"]),
+  );
+
+  regTool(
+    "grid_status",
+    "Org dashboard, entity detail, or deploy snapshot. Wraps `cloudgrid 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"])),
+  );
+
+  regTool(
+    "grid_info",
+    "Show metadata for a CloudGrid entity. Wraps `cloudgrid 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 }) => {
+      const args = ["info"];
+      if (name) args.push(name);
+      return args;
+    }),
+  );
+
+  // grid_get is the single canonical lister for grids, entities, and spaces
+  // (wraps `cloudgrid 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`.",
+    {
+      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."),
+      kind: z.enum(["app", "agent", "inspiration"]).optional().describe("Filter by kind (entities only)."),
+      status: z.enum(["charged", "live", "dark", "archived"]).optional().describe("Filter by status (entities only)."),
+      space: z.string().optional().describe("Only entities scoped to this space slug (entities only)."),
+      archived: z.boolean().optional().describe("Include archived entities (entities only)."),
+    },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(({ resource, grid, kind, status, space, archived }) => {
+      const args = ["get", resource];
+      // --grid applies to entities and spaces; grids has no such flag.
+      if (grid && resource !== "grids") args.push("--grid", grid);
+      if (resource === "entities") {
+        if (kind) args.push("--kind", kind);
+        if (status) args.push("--status", status);
+        if (space) args.push("--space", space);
+        if (archived) args.push("--archived");
+      }
+      args.push("--json");
+      return args;
+    }),
+  );
+
+  regTool(
+    "grid_describe_grid",
+    "Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps `cloudgrid describe grid <slug> --json`.",
+    { grid: z.string().describe("Grid slug to describe.") },
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
+  );
+
+  regTool(
+    "grid_edit_existing_app",
+    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `cloudgrid 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."),
+      grid: z.string().optional().describe("Grid to resolve the entity in. Defaults to the active grid."),
+      version: z.string().optional().describe("Pick up an older version's source instead of HEAD."),
+      force: z.boolean().optional().describe("Pick up into a non-empty directory."),
+      no_bind: z.boolean().optional().describe("Download source only — skip cloudgrid.yaml and the link."),
+      cwd: z.string().optional().describe("Working directory the CLI runs in. The download lands here; pass an explicit, writable directory."),
+    },
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(({ name, target_dir, grid, version, force, no_bind }) => {
+      const args = ["pickup", name];
+      if (target_dir) args.push(target_dir);
+      // CLI 0.12's pickup exposes `--grid <slug>` (was legacy `--org`).
+      if (grid) args.push("--grid", grid);
+      if (version) args.push("--version", version);
+      if (force) args.push("--force");
+      if (no_bind) args.push("--no-bind");
+      return args;
+    }, { cwdParam: true }),
+  );
+
+  regTool(
+    "grid_rename",
+    "Rename a CloudGrid entity's display name (slug stays the same). Wraps `cloudgrid rename`.",
+    {
+      name: z.string().describe("Entity slug."),
+      new_name: z.string().describe("New display name."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ name, new_name }) => ["rename", name, new_name]),
+  );
+
+  regTool(
+    "grid_take_offline",
+    "Take an entity off the grid. Destructive. Wraps `cloudgrid unplug`.",
+    {
+      name: z.string().describe("Entity slug to take down (required)."),
+      confirm: z.literal(true).describe("Must be true to proceed."),
+    },
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(({ name }) => ["unplug", name, "--skip-confirm"]),
+  );
+
+  regTool(
+    "grid_delete",
+    "Archive a CloudGrid inspiration. Destructive. Wraps `cloudgrid delete entity`.",
+    {
+      name: z.string().describe("Entity slug to delete (required)."),
+      confirm: z.literal(true).describe("Must be true to proceed."),
+    },
+    { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    cliTool(({ name }) => ["delete", "entity", name, "--yes"]),
+  );
+
+  regTool(
+    "grid_rollback_deploy",
+    "Rollback an entity to a previous version. Wraps `cloudgrid rollback`.",
+    {
+      name: z.string().describe("Entity slug."),
+      to: z.string().optional().describe("Target version tag or id. Omit to roll back one version."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ name, to }) => {
+      const args = ["rollback", name, "--yes"];
+      if (to) args.push("--to", to);
+      return args;
+    }),
+  );
+
+  regTool(
+    "grid_list_versions",
+    "List published versions for an entity. Wraps `cloudgrid 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 }) => {
+      const args = ["versions"];
+      if (name) args.push(name);
+      return args;
+    }),
+  );
+
+  regTool(
+    "grid_set_env",
+    "Manage environment variables for an entity. Wraps `cloudgrid env`.",
+    {
+      action: z.enum(["get", "set", "list"]).describe("get, set, or list."),
+      name: z.string().describe("Entity slug."),
+      key: z.string().optional().describe("Variable name. Required for get and set."),
+      value: z.string().optional().describe("Variable value. Required for set."),
+      cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ action, name, key, value }) => {
+      if (action === "set") {
+        if (!key || value === undefined) throw new Error("key and value are required for set");
+        return ["env", "set", name, `${key}=${value}`];
+      }
+      if (action === "get") {
+        if (!key) throw new Error("key is required for get");
+        return ["env", "get", key, name];
+      }
+      return ["env", "list", name];
+    }, { cwdParam: true }),
+  );
+
+  regTool(
+    "grid_set_secret",
+    "Set or list secret names for an entity. Never returns secret values. Wraps `cloudgrid secrets`.",
+    {
+      action: z.enum(["set", "list"]).describe("set or list (names only)."),
+      name: z.string().describe("Entity slug."),
+      key: z.string().optional().describe("Secret name. Required for set."),
+      value: z.string().optional().describe("Secret value. Required for set."),
+      cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(({ action, name, key, value }) => {
+      if (action === "set") {
+        if (!key || value === undefined) throw new Error("key and value are required for set");
+        return ["secrets", "set", name, `${key}=${value}`];
+      }
+      return ["secrets", "list", name];
+    }, { cwdParam: true }),
+  );
+
+  regTool(
+    "grid_scaffold",
+    "Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps `cloudgrid scaffold`.",
+    {
+      cwd: z.string().optional().describe("Working directory. The CLI runs in this directory. Defaults to the MCP server's working directory."),
+    },
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    cliTool(() => ["scaffold"], { cwdParam: true }),
+  );
+
+  regTool(
+    "grid_diagnose",
+    "Run CloudGrid diagnostics on the local environment. Wraps `cloudgrid doctor`.",
+    {},
+    { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+    cliTool(() => ["doctor"]),
+  );
+
+  regTool(
+    "grid_get_url",
+    "Return the public URL for an entity. Does not open a browser. Wraps `cloudgrid 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 }) => {
+      const args = ["open", "--print"];
+      if (name) args.push(name);
+      return args;
+    }),
+  );
+
+  // ── Deprecated aliases (tool-name cleanup): OLD CLI-tool names kept callable
+  //    (local edition) as redirect-only aliases of their new, clearer names.
+  // Kept alias (local): grid_logs - muscle memory. The other legacy CLI-tool
+  // aliases were dropped in 0.20.8 (see CHANGELOG).
+  registerAlias("grid_logs", "grid_view_logs");
+}