@cloudgrid-io/mcp 0.20.37 → 0.20.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.37",
+  "version": "0.20.39",
   "description": "MCP access to CloudGrid — the live runtime environment where the user's apps run WITH the infrastructure they need out of the box: managed MongoDB, Redis (cache/queues/pub-sub), a pgvector store, persistent disk, and built-in AI with no API keys, in any language or stack, no Docker or Kubernetes to manage. Brainstorm, build, plug, and improve apps, games, dashboards, and tools; instant single-page publishes and full runtime-app deploys with a live URL — for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server.",
   "type": "module",
   "bin": {
@@ -50,7 +50,6 @@
     "snapshot:corpus": "node scripts/snapshot-corpus.mjs",
     "build:mcpb": "node scripts/build-mcpb.mjs",
     "test:widgets": "node test/apps-widgets.test.mjs",
-    "test:fork": "node test/fork.test.mjs",
     "test:set-sharing": "node test/set-sharing.test.mjs",
     "test:check-deploy": "node test/check-deploy.test.mjs",
     "test:staleness": "node test/staleness.test.mjs",

package/src/corpus/playbook.md

@@ -18,7 +18,7 @@ Operating rules:
 15. Editing an existing thing from just its URL (a fresh chat, no prior context — e.g. "change the background to green here <url>"): call grid_get_app_source(url) first. It resolves the entity_id and returns the current HTML plus its kind, single_html, capabilities, and replug_handle — read those to pick the branch:
   - Single-HTML inspiration you can re-plug (single_html: true and capabilities.replug: true): edit the returned HTML and call grid_plug with target_entity_id (or grid+slug — the replug_handle) to update the SAME URL in place. This works on every edition, including hosted.
   - Multi-file app or agent (kind is app or agent, or single_html: false): do NOT try to edit it as one inline HTML file. Tell the user it is a multi-file <kind>, give them the entity_id and the source (source_download_url), and explain that rebuilding it needs the local edition (Claude Desktop/Code) or the CLI — the hosted server cannot rebuild a multi-file app.
-  - 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_fork and edit the copy instead.
+  - 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_pickup and edit the copy instead.
 16. Help CloudGrid QA. When you deploy, fill BOTH of grid_plug'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.
 
 17. Auth check before an owned deploy, with an anonymous fallback. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or the deploy returns a create-time 401), do NOT silently fail and do NOT invent an auth flow — ask them plainly: "Sign in to publish to your grid, or I can publish it anonymously right now (it goes live immediately with a claim link so you can save it to your account later)?" If they choose anonymous, re-call grid_plug with anon: true and surface the claim_url + owner_token. This is distinct from rule 6: rule 6 forbids the anon fallback on a SERVER error (5xx) for a signed-in user (it burns quota and downgrades ownership); THIS rule is about not being authenticated at all, where anonymous is a legitimate, offered choice.

package/src/tools/deploy.js

@@ -1,4 +1,4 @@
-// Direct-API tool internals: grid_deploy (runPlug), grid, claim, report, fork,
+// Direct-API tool internals: grid_plug (runPlug), pull, pickup, report,
 // download, visibility, and source retrieval.
 // Extracted verbatim from src/tools.js (refactor: split tools.js into modules).
 
@@ -51,7 +51,7 @@ export async function fetchUserOrgs(token) {
   }
 }
 
-// ── Shared grid disambiguation (grid_deploy) ──────────────────
+// ── Shared grid disambiguation (grid_plug) ──────────────────
 // The stateless "which grid?" ask on an authed create. Given the caller's token
 // and a supplied grid, it decides:
 //   - supplied grid matches a membership  → { proceed: true, grid }
@@ -83,7 +83,7 @@ export async function resolveGridOrAsk(ctx, { token, suppliedGrid, edition }, de
       if (a.render_ready !== b.render_ready) return b.render_ready ? 1 : -1;
       return 0;
     });
-    const lines = ["Which grid should this be published to?"];
+    const lines = ["Which grid should this be plugged into?"];
     for (const o of annotated) {
       const tags = [];
       if (o.is_active) tags.push("your active grid");
@@ -162,7 +162,7 @@ function looksLikePath(s) {
   return /^(~|\.{0,2}\/|[A-Za-z]:[\\/]|\/)/.test(t) || /\.[A-Za-z0-9]{1,8}$/.test(t);
 }
 
-// Normalize an inline `html` string — grid_deploy's ergonomic single-file publish
+// Normalize an inline `html` string — grid_plug's ergonomic single-file publish
 // path — into ONE index.html artifact, reusing the same hardening the old drop
 // verb used (decodeIfBase64Html, the @-path/file-path rejection, the base64
 // guard, and the small-fragment wrap). Returns { path, buffer, type }. Throws on
@@ -512,7 +512,13 @@ export async function runReport(
   });
 }
 
-export async function runClaim(ctx, { claim_token, claim_url, entity_id }) {
+// grid_pull — continue/edit an existing entity IN PLACE (POST /entities/:id/pickup).
+// Like `git clone` of the SAME entity: your next grid_plug (target_entity_id)
+// updates it. Needs push access — you must OWN it or be a COLLABORATOR. A
+// view-only caller is told they can't edit/plug it (make a copy with grid_pickup,
+// or request collaborator access with the CLI `grid collab`). A claim_token also
+// claims an anonymous drop into your account (ownership transfer).
+export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   const token = await ctx.getToken();
   if (!token) {
     throw new Error("You are not signed in. Run grid_login first, then claim.");
@@ -593,35 +599,67 @@ export async function runClaim(ctx, { claim_token, claim_url, entity_id }) {
     if (res.status === 409) {
       ctx.state.lastAnonClaim = null;
       return {
-        text: "Nothing to claim — it was already claimed.",
-        structured: { claimed: 0, urls: [] },
+        text: "Already yours — nothing to pull.",
+        structured: { owner_is_you: true, can_edit: true },
+      };
+    }
+    const code = data?.error?.code || null;
+    // No push access → not an error to throw; tell the user their options.
+    if (res.status === 403 || code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED" || code === "FORBIDDEN_ROLE") {
+      return {
+        text:
+          `You don't have push access to this entity, so you can't edit or plug it. Two options: ` +
+          `make your own separate copy with grid_pickup, or ask the owner for collaborator access with the CLI ` +
+          `\`grid collab <entity>\` (rolling out soon) and pull again once granted.`,
+        structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
-    throw new Error(`Claim failed (HTTP ${res.status}): ${msg}`);
+    throw new Error(`Pull failed (HTTP ${res.status}): ${msg}`);
   }
 
   ctx.state.lastAnonClaim = null;
-  // The entity is authed-owned now — the anon owner token is dead weight (a
-  // claimed drop can no longer be edited anonymously). Future re-drops of it
-  // must ride the authed wire.
+  // A claimed anon drop is authed-owned now — its anon owner token is dead weight.
   if (ctx.state.lastDrop?.entity_id === targetId) {
     ctx.state.lastDrop.owner_token = null;
   }
   const url = data?.url || data?.redirect_url || ctx.state.lastDrop?.url || null;
-  const lines = ["Claimed 1, now yours:"];
-  lines.push(`${url ?? ""}${data?.new_expires_at ? ` (expires ${data.new_expires_at})` : ""}`.trim());
+  const slug = data?.slug || targetId;
+  const where = data?.grid ? ` in ${data.grid}` : "";
+  // A claim_token transfers ownership to you; otherwise read the pickup contract.
+  const ownerIsYou = data?.owner?.is_you === true || Boolean(claimToken);
+  const canReplug = data?.capabilities?.replug === true;
+  let head, canEdit;
+  if (ownerIsYou) {
+    head = `${slug}${where} is yours — your next grid_plug (with target_entity_id) updates it in place.`;
+    canEdit = true;
+  } else if (canReplug) {
+    head = `You have collaborator push access to ${slug}${where} — your next grid_plug (target_entity_id) updates the SHARED entity; the team sees the new version and can roll it back.`;
+    canEdit = true;
+  } else {
+    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own copy with grid_pickup, or request collaborator access with the CLI \`grid collab ${slug}\` (rolling out soon), then pull again.`;
+    canEdit = false;
+  }
+  const lines = [head];
+  if (url) lines.push(`URL: ${url}`);
+  if (canEdit && data?.entity_id) {
+    lines.push(`Re-plug handle: entity_id=${data.entity_id} — pass it as grid_plug's target_entity_id to update in place.`);
+  }
   return {
     text: lines.join("\n"),
     structured: {
-      claimed: 1,
-      urls: url ? [url] : [],
+      ...(data?.entity_id ? { entity_id: data.entity_id } : {}),
+      ...(slug ? { slug } : {}),
+      grid: data?.grid ?? null,
+      ...(url ? { url } : {}),
+      owner_is_you: ownerIsYou,
+      can_edit: canEdit,
     },
   };
 }
 
 
-// ── grid_deploy — the unified create/re-plug verb (spec v2 §3) ──────────────
+// ── grid_plug — the unified create/re-plug verb (spec v2 §3) ──────────────
 
 // Total upload budget mirrors the server's multipart cap (100 MB).
 const PLUG_MAX_TOTAL_BYTES = 100 * 1024 * 1024;
@@ -749,7 +787,7 @@ async function expandZipToProject(zipPath, inlineHtml) {
   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), " +
+      "The zip already contains a cloudgrid.yaml project — plug it as-is (drop the `html` param), " +
         "or re-plug the entity and edit its files instead.",
     );
   }
@@ -857,7 +895,7 @@ async function plugZipProjectViaCli(ctx, { projectDir, name }, input, deps = {})
   const url = parseCliPlugUrl(stdout);
   if (!url) {
     throw new Error(
-      `The zip project deployed via the CLI but no live URL was found in its output.\n${stdout.slice(0, 500)}`,
+      `The zip project was plugged via the CLI but no live URL was found in its output.\n${stdout.slice(0, 500)}`,
     );
   }
   return {
@@ -958,16 +996,16 @@ export function errorGuidance({ status, code, edition, isEdit, isAnon, signedIn
   }
   // 409 EDIT_REJECTED — an in-place re-plug the server won't take.
   if (status === 409) {
-    return "The entity cannot be updated right now (a deploy is in progress, or it is archived/expired/claimed). An explicit re-plug never silently creates; retry later, or omit target_entity_id to create a new entity.";
+    return "The entity cannot be updated right now (a plug is in progress, or it is archived/expired/claimed). An explicit re-plug never silently creates; retry later, or omit target_entity_id to create a new entity.";
   }
   // 401 on an edit — the credential didn't authorize this entity.
   if (status === 401) {
     return isEdit
       ? "That did not authorize this entity (wrong entity, expired, or already claimed). Sign in if you own it (grid_login), pass its owner_token for an anonymously-created drop, or omit target_entity_id to create a new entity."
-      : "Not signed in. Ask the user: sign in (grid_login) to publish to their grid, OR publish anonymously now (re-call grid_deploy with anon: true) - it goes live immediately with a claim_url + owner_token to claim into their account later. Do not silently fail; offer both.";
+      : "Not signed in. Ask the user: sign in (grid_login) to publish to their grid, OR publish anonymously now (re-call grid_plug with anon: true) - it goes live immediately with a claim_url + owner_token to claim into their account later. Do not silently fail; offer both.";
   }
   if (status === 403) {
-    return "You lack the role to plug this target. To re-plug someone else's entity, pick it up first (grid_edit_existing_app / grid_claim_anonymous_deploy).";
+    return "You lack the role to plug this target. To re-plug someone else's entity, pull it first (grid_pull), or make your own copy (grid_pickup).";
   }
   // ── Consent-gated report offer (Task 34) ──────────────────────────────────
   // GENUINE bugs only: a build/deploy failure, any 5xx, INTERNAL_ERROR, or an
@@ -1114,11 +1152,11 @@ export async function runPlug(ctx, input, deps = {}) {
     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.",
+          "(grid_edit_existing_app) and re-plug the folder, or plug 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.");
+      throw new Error("A zip plug creates a static app and needs sign-in — it cannot be anonymous.");
     }
     const expanded = await expandZipToProject(srcPath, hasHtml ? html : null);
     if (expanded.singleHtml) {
@@ -1333,9 +1371,9 @@ export async function runPlug(ctx, input, deps = {}) {
   } catch (err) {
     if (err?.name === "AbortError" || err?.name === "TimeoutError") {
       throw new Error(
-        `The deploy request timed out after ${Math.round(uploadTimeoutMs / 1000)}s. ` +
-          `The build may still be running on CloudGrid — check the deploy status ` +
-          `(poll_url / grid_status, or your grid) before deploying again, so you don't create a duplicate.`,
+        `The plug request timed out after ${Math.round(uploadTimeoutMs / 1000)}s. ` +
+          `The build may still be running on CloudGrid — check the build status ` +
+          `(poll_url / grid_status, or your grid) before plugging again, so you don't create a duplicate.`,
       );
     }
     throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
@@ -1520,7 +1558,7 @@ export async function runPlug(ctx, input, deps = {}) {
         : "npx -y @cloudgrid-io/cli plug";
       cliSteer =
         "Heads-up: this went in INLINE. For a multi-file app the disk-based CLI is more reliable (lockfiles/binaries can't truncate), but it must run where the CLI is already signed in — a terminal or Claude Code that has done `grid login` once. Do NOT try `grid login` inside a chat sandbox: its login poll is long-lived and the sandbox is ephemeral, so it won't stick. " +
-        `If you had to leave any files out to make this inline deploy safe, tell the user — offer the complete deploy from Claude Code or a terminal (\`${replug}\`), or confirm they accept the reduced version. Do not drop files silently.`;
+        `If you had to leave any files out to make this inline plug safe, tell the user — offer the complete plug from Claude Code or a terminal (\`${replug}\`), or confirm they accept the reduced version. Do not drop files silently.`;
     }
   }
 
@@ -1528,8 +1566,8 @@ export async function runPlug(ctx, input, deps = {}) {
   if (isBuilding) {
     lines.push(
       isEdit
-        ? `Building (async): ${url} — the update is deploying, not live yet.`
-        : `Building (async): ${url} — the deploy is in progress, not live yet.`,
+        ? `Building (async): ${url} — the update is plugging, not live yet.`
+        : `Building (async): ${url} — the plug is in progress, not live yet.`,
     );
     // Point at a tool that exists on THIS edition. grid_status is CLI-wrapping,
     // local-only — telling a hosted (ChatGPT/claude.ai) model to "run
@@ -1546,7 +1584,7 @@ export async function runPlug(ctx, input, deps = {}) {
     lines.push(`Updated in place: ${url}`);
   } else if (isInspirationCreate) {
     // Authed inspiration create — owned by the caller. Wording mirrors the drop verb.
-    lines.push(ctx.edition === "web" ? `Your app is live: ${url}` : `Published to your grid: ${url}`);
+    lines.push(ctx.edition === "web" ? `Your app is live: ${url}` : `Plugged into your grid: ${url}`);
     if (ctx.edition !== "web") lines.push("Owned by you.");
   } else {
     lines.push(`Live: ${url}`);
@@ -1622,7 +1660,7 @@ async function authedApiCall(ctx, { method, pathName, body, verb }) {
     const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
     const codeStr = data?.error?.code || null;
     const err = new Error(`${verb} failed (HTTP ${res.status}${codeStr ? ` ${codeStr}` : ""}): ${msg}`);
-    // Expose the structured status/code so callers can branch (e.g. runFork's
+    // Expose the structured status/code so callers can branch (e.g. runPickup's
     // NOT_A_RUNTIME → inspiration-route fallback). Additive: existing callers
     // only read `.message`.
     err.status = res.status;
@@ -1632,63 +1670,13 @@ async function authedApiCall(ctx, { method, pathName, body, verb }) {
   return data;
 }
 
-// Fork: start a NEW entity from an existing source, copy-on-write with lineage.
-// Kind-aware (one fork verb, mirrors the CLI `fork` command): the caller may
-// not know the source's kind, so try the runtime route first and, when the
-// server reports the target is an inspiration (`400 NOT_A_RUNTIME`, emitted by
-// requireEntityAccess before the runtime handler runs), retry the inspiration
-// route. The inspiration remix lands in the caller's active grid, so no
-// `into_org_slug`; `source_version_id` has no meaning for inspirations.
-export async function runFork(ctx, { id, into_org_slug, name, source_version_id }) {
-  let data;
-  try {
-    data = await authedApiCall(ctx, {
-      method: "POST",
-      pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/fork`,
-      body: {
-        ...(into_org_slug ? { into_org_slug } : {}),
-        ...(name ? { name } : {}),
-        ...(source_version_id ? { source_version_id } : {}),
-      },
-      verb: "Fork",
-    });
-  } catch (err) {
-    if (err && err.code === "NOT_A_RUNTIME") {
-      data = await authedApiCall(ctx, {
-        method: "POST",
-        pathName: `/api/v2/inspirations/${encodeURIComponent(id)}/fork`,
-        body: { ...(name ? { name } : {}) },
-        verb: "Fork",
-      });
-    } else {
-      throw err;
-    }
-  }
-  const gridSlug = data?.grid_slug ?? data?.org?.slug ?? null;
-  const lines = [
-    `Forked: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}`,
-    `Lineage: forked_from=${data?.forked_from ?? "?"}${data?.forked_from_version_id ? ` @ ${data.forked_from_version_id}` : ""}`,
-  ];
-  return {
-    text: lines.join("\n"),
-    structured: {
-      entity_id: data?.entity_id ?? null,
-      name: data?.name ?? null,
-      kind: data?.kind ?? null,
-      grid_slug: gridSlug,
-      forked_from: data?.forked_from ?? null,
-      forked_from_version_id: data?.forked_from_version_id ?? null,
-      current_version_id: data?.current_version_id ?? null,
-    },
-  };
-}
-
-// Remix: cross-grid "make my own copy". Unlike fork (same-grid, byte-carrying),
-// remix mints a NEW entity in ANY grid the caller can build in, keeps lineage
-// back to the source, and strips the source's secrets/connection credentials —
-// the remixer supplies their own before plugging. Hits POST
-// /api/v2/runtimes/:id/remix.
-export async function runRemix(ctx, { id, into_org_slug, name, source_version_id }) {
+// grid_pickup — "make your own copy" (like a git fork). Mints a NEW entity in a
+// grid you can build in, keeps lineage back to the source, and strips the
+// source's secrets/connection credentials — you set your own before plugging.
+// Plugging your copy creates/updates YOUR entity; the original is untouched.
+// Hits POST /api/v2/runtimes/:id/remix (the copy route). Mirrors the CLI's
+// `grid pickup`. To edit the ORIGINAL in place, that's grid_pull, not this.
+export async function runPickup(ctx, { id, into_org_slug, name, source_version_id }) {
   const data = await authedApiCall(ctx, {
     method: "POST",
     pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/remix`,
@@ -1697,12 +1685,13 @@ export async function runRemix(ctx, { id, into_org_slug, name, source_version_id
       ...(name ? { name } : {}),
       ...(source_version_id ? { source_version_id } : {}),
     },
-    verb: "Remix",
+    verb: "Pickup",
   });
   const gridSlug = data?.grid_slug ?? data?.org?.slug ?? null;
   const lines = [
-    `Remixed: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}`,
-    `Lineage: forked_from=${data?.forked_from ?? "?"}. Secrets were not copied — set your own before you plug.`,
+    `Picked up a copy: ${data?.name ?? id} (entity_id=${data?.entity_id ?? "?"})${gridSlug ? ` in grid ${gridSlug}` : ""}.`,
+    "This is a NEW entity — plug it (with this entity_id as target_entity_id) to create/update YOUR copy; the original is untouched.",
+    `Lineage kept (forked_from=${data?.forked_from ?? "?"}). The source's secrets were NOT copied — set your own before you plug.`,
   ];
   return {
     text: lines.join("\n"),
@@ -1718,30 +1707,6 @@ export async function runRemix(ctx, { id, into_org_slug, name, source_version_id
   };
 }
 
-// Download: signed, time-limited (15-minute) source-bundle URLs. No entity is
-// created and no registry state changes.
-export async function runDownload(ctx, { id, version }) {
-  const qs = version ? `?version=${encodeURIComponent(version)}` : "";
-  const data = await authedApiCall(ctx, {
-    method: "GET",
-    pathName: `/api/v2/runtimes/${encodeURIComponent(id)}/source${qs}`,
-    verb: "Download",
-  });
-  const services = data?.services && typeof data.services === "object" ? data.services : {};
-  const lines = [`Source bundle URLs for ${data?.name ?? id} (valid ~15 minutes):`];
-  for (const [svc, u] of Object.entries(services)) lines.push(`  ${svc}: ${u}`);
-  if (Object.keys(services).length === 0) lines.push("  (no services returned)");
-  return {
-    text: lines.join("\n"),
-    structured: {
-      entity_id: data?.entity_id ?? null,
-      name: data?.name ?? null,
-      services,
-      domain: data?.domain ?? null,
-    },
-  };
-}
-
 // Change an entity's visibility — inspiration OR runtime app/agent. Authed,
 // direct API — works on the hosted edition where the CLI-wrapping share tool is
 // unavailable. Kind-aware routing (see below). Defaults to the drop made in this
@@ -1805,7 +1770,7 @@ export async function runVisibility(ctx, { target, visibility, kind, org }) {
   // Route order. `space` is inspiration-only; a known runtime kind goes straight
   // to the entities route; a known inspiration goes straight to the inspiration
   // route; an unknown kind tries the runtime route first and falls back to the
-  // inspiration route on a not-found (mirrors runFork).
+  // inspiration route on a not-found (mirrors runPickup).
   let order;
   if (vis === "space") order = ["inspiration"];
   else if (isRuntimeKind) order = ["runtime"];
@@ -1975,7 +1940,7 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   });
   if (!target) {
     throw new Error(
-      "No build to check. Pass poll_url from a grid_deploy result, or deploy something first in this session. (Instant inspiration deploys are live on return and have no build to poll.)",
+      "No build to check. Pass poll_url from a grid_plug result, or plug something first in this session. (Instant inspiration plugs are live on return and have no build to poll.)",
     );
   }
   const verdict = await fetchDeployTrace(ctx, { pollUrl: target, grid: gridSlug });
@@ -1988,7 +1953,7 @@ export async function runCheckDeploy(ctx, { poll_url, grid } = {}) {
   }
   if (verdict.status === "failed") {
     return {
-      text: `The build FAILED: ${verdict.error || "no reason reported"}. The URL is not live — do not give it to the user as working. Fix the app (or re-deploy) and try again.` +
+      text: `The build FAILED: ${verdict.error || "no reason reported"}. The URL is not live — do not give it to the user as working. Fix the app (or re-plug) and try again.` +
         formatFailureDetail(verdict),
       structured: {
         status: "failed",
@@ -2087,7 +2052,7 @@ async function readInspirationSourceViaApi(ctx, { entityId, slug, grid }) {
 
 // Resolve a public URL / grid+slug to a REAL entity_id (+ edition metadata) via
 // the deployed pickup contract (POST /api/v2/entities/:target/pickup — the same
-// endpoint runClaim uses). Used by runSource when a bare URL arrives with no
+// endpoint runPull uses). Used by runSource when a bare URL arrives with no
 // session entity_id (a fresh chat): the contract returns
 //   { entity_id, slug, grid, kind, single_html, capabilities, replug_handle,
 //     source_download_url, ... }

package/src/tools/register.js

@@ -20,11 +20,9 @@ import {
   resolveGridOrAsk,
   detectSourceManifest,
   runReport,
-  runClaim,
+  runPull,
   runPlug,
-  runFork,
-  runRemix,
-  runDownload,
+  runPickup,
   runVisibility,
   runSource,
   runCheckDeploy,
@@ -106,7 +104,7 @@ export function registerTools(server, ctx) {
     }));
 
     server.registerResource("cloudgrid-org-picker", GRID_PICKER_URI, {
-      description: "Grid picker card — lets the user choose which grid to publish into.",
+      description: "Grid picker card — lets the user choose which grid to plug into.",
       mimeType: "text/html;profile=mcp-app",
     }, async () => ({
       contents: [{
@@ -120,28 +118,68 @@ export function registerTools(server, ctx) {
 
   // ── Direct-API tools (both editions) ──────────────────────────────────────
 
-  // Pickup — both editions. Adopts an entity into the signed-in account's active
-  // grid (ownership transfer via POST /api/v2/entities/:id/pickup). Pass an
-  // anonymous drop's owner token as `claim_token` to take over something you
-  // dropped anonymously — that path replaces the old standalone "claim" verb.
+  // ── Copy / adopt verbs (both editions) — mirror the CLI: ──────────────────
+  //   grid_pickup = make YOUR OWN COPY (git-fork style) → POST /runtimes/:id/remix
+  //   grid_pull   = continue/edit the SAME entity in place (push access needed)
+  //                 → POST /entities/:id/pickup
+  // (The CLI verbs `download`, `fork`, `remix`, `link` were retired; no MCP tool
+  // targets them.)
+
+  // grid_pickup — make your own copy of any app you can see.
   reg(
     "grid_pickup",
     {
-      description: "Pick up (adopt) an entity into the signed-in account's active grid — an ownership transfer, keeping the same public URL. Use it to take over an entity you have access to, or to keep an anonymous drop you created: pass the drop's `claim_token` and it becomes owned and stops expiring on the anonymous schedule. Requires sign-in (grid_login). Calls the API directly, so it works on every edition. (This is the direct-API adopt; on the local edition grid_edit_existing_app additionally downloads the source and links the folder for editing.)",
+      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
+      inputSchema: {
+        id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
+        into_org_slug: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
+        name: z.string().optional().describe("Slug for your copy. Omit to derive one from the source."),
+        source_version_id: z.string().optional().describe("Copy an older version instead of HEAD, e.g. v_a1b2c3d."),
+      },
+      outputSchema: {
+        entity_id: z.string().nullable().describe("Your copy's entity id — pass as grid_plug's target_entity_id to update it."),
+        name: z.string().nullable().describe("Your copy's slug."),
+        kind: z.string().nullable().describe("app | agent."),
+        grid_slug: z.string().nullable().describe("The grid your copy landed in."),
+        forked_from: z.string().nullable().describe("Source entity_id (lineage)."),
+        forked_from_version_id: z.string().nullable().describe("Source version, when a specific one was copied."),
+        current_version_id: z.string().nullable().describe("Your copy'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 runPickup(ctx, input));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
+  // grid_pull — continue/edit the SAME entity in place (push access required).
+  reg(
+    "grid_pull",
+    {
+      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so and tell the user they can make their own copy with grid_pickup, or request collaborator access with the CLI `grid collab <entity>` (rolling out soon). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
-        entity_id: z.string().optional().describe("The entity id to pick up. Defaults to this session's last anonymous drop."),
-        claim_token: z.string().optional().describe("For an anonymous drop: its owner token (the owner_token in the drop result, also embedded in claim_url). Passing it takes over that drop."),
-        claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url from the drop result; the token is read from it."),
+        entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
+        claim_token: z.string().optional().describe("Anonymous drop only: its owner token — claims that drop into your account (ownership transfer)."),
+        claim_url: z.string().optional().describe("Alternative to claim_token for an anonymous drop — the claim_url; the token is read from it."),
       },
       outputSchema: {
-        claimed: z.number().describe("Number of entities picked up."),
-        urls: z.array(z.string()).describe("Public URLs of the picked-up entities."),
+        entity_id: z.string().optional().describe("The entity you pulled."),
+        slug: z.string().optional().describe("Its slug."),
+        grid: z.string().nullable().optional().describe("Its grid."),
+        url: z.string().optional().describe("Its public URL."),
+        owner_is_you: z.boolean().optional().describe("True if you own it."),
+        can_edit: z.boolean().optional().describe("True if you can plug/update it (owner or collaborator). False = view-only."),
       },
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     },
     async (input) => {
       try {
-        return okResult(await runClaim(ctx, input || {}));
+        return okResult(await runPull(ctx, input || {}));
       } catch (err) {
         return fail(err.message);
       }
@@ -156,7 +194,7 @@ export function registerTools(server, ctx) {
   // 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_plug's session_note instead. Recorded for CloudGrid QA. No side effects.",
+    "Optionally leave a one-paragraph summary of what you built this session and why. Call it BEFORE a plug, or in a session that ends without one — a successful plug has already posted the QA log, so pass grid_plug'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) => {
@@ -191,7 +229,7 @@ export function registerTools(server, ctx) {
           path: z.string().optional().describe(
             "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 " +
+            "always skipped). A .zip is extracted and plugged: with its own cloudgrid.yaml it plugs " +
             "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 " +
@@ -213,7 +251,7 @@ export function registerTools(server, ctx) {
       "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). " +
+      "Present → RE-PLUG: update this exact entity in place (same entity_id, slug, URL, plug 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.",
     ),
@@ -241,7 +279,7 @@ export function registerTools(server, ctx) {
       "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. " +
+      "Set true to confirm plugging 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_plug returns needs_confirmation " +
       "so you can ask the user first (or use target_entity_id to re-plug an existing entity).",
     ),
@@ -250,7 +288,7 @@ export function registerTools(server, ctx) {
       "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.",
+      "One short paragraph on what you built and why. Recorded for CloudGrid QA alongside the plug.",
     ),
   };
 
@@ -432,111 +470,6 @@ export function registerTools(server, ctx) {
   // "publish"/"ship"/"make live" live in grid_plug's description, so
   // deploy-intent routing lands there without a second listed name.
 
-  // ── grid_fork / grid_remix / grid_download — direct-API copy/source verbs ──────
-  // fork = same-grid byte-carrying copy; remix = cross-grid copy with secrets
-  // stripped; download = signed source-bundle URLs. All direct-API (both editions).
-  reg(
-    "grid_fork",
-    {
-      description:
-        "Fork an entity: start a NEW entity from an existing one (copy-on-write, lineage recorded), carrying " +
-        "the source bytes. Lands in the source's home grid by default; cross-grid only for system templates " +
-        "or forkable:'public' sources — for a general cross-grid copy use grid_remix instead. 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 entity: 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_remix",
-    {
-      description:
-        "Remix an app: make your own copy of any app you can SEE (link/public/authenticated, or a grid you " +
-        "belong to) into ANY grid you can build in — cross-grid is allowed. Mints a NEW entity with lineage " +
-        "back to the source, WITHOUT the source's secrets or connection credentials (set your own before you " +
-        "plug). Distinct from grid_fork, which is same-grid and byte-carrying. Requires sign-in. Calls POST " +
-        "/api/v2/runtimes/:id/remix.",
-      inputSchema: {
-        id: z.string().describe("The source app: a canonical UUID or <grid-slug>/<entity-slug>."),
-        into_org_slug: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
-        name: z.string().optional().describe("Slug for your copy. Omit to derive one from the source."),
-        source_version_id: z.string().optional().describe("Remix an older version instead of HEAD, e.g. v_a1b2c3d."),
-      },
-      outputSchema: {
-        entity_id: z.string().nullable().describe("Your copy's entity id."),
-        name: z.string().nullable().describe("Your copy's slug."),
-        kind: z.string().nullable().describe("app | agent."),
-        grid_slug: z.string().nullable().describe("The grid your copy 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 remixed."),
-        current_version_id: z.string().nullable().describe("Your copy'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 runRemix(ctx, input));
-      } catch (err) {
-        return fail(err.message);
-      }
-    },
-  );
-
-  reg(
-    "grid_download",
-    {
-      description:
-        "Download an entity's source: the bundle last deployed for a runtime, as one signed, time-limited " +
-        "(15-minute) read URL per service tarball. No entity is created and no registry state changes (unlike " +
-        "grid_pickup/grid_fork/grid_remix, which adopt or copy). 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(
@@ -550,9 +483,9 @@ export function registerTools(server, ctx) {
         "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 (signed tarball URLs). Reads the HTML from the API server-side; " +
-        "read-only, creates nothing.",
+        "edition/CLI), or offer a copy (grid_pickup) when it isn't yours. For a multi-file or runtime " +
+        "(app/agent) source, use source_download_url, or grid_pull to get the files and link the folder. " +
+        "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."),
@@ -1130,23 +1063,27 @@ export function registerTools(server, ctx) {
     cliTool(({ grid }) => ["describe", "grid", grid, "--json"]),
   );
 
+  // Local (CLI-wrapping) counterpart of the direct-API grid_pull: downloads the
+  // source + cloudgrid.yaml and links the folder, so the next `grid plug` updates
+  // the SAME entity in place. Wraps `grid pull` (NOT `grid pickup` — pickup now
+  // makes a separate copy). Push access required; a view-only entity can't be
+  // pulled — use grid_pickup to copy it, or `grid collab` to request access.
   regTool(
     "grid_edit_existing_app",
-    "Download an entity's source + cloudgrid.yaml and link the folder to it. Overwrites with --force. Wraps `grid pickup`.",
+    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy instead, use 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."),
+      name: z.string().describe("Entity slug or id to pull."),
+      target_dir: z.string().optional().describe("Directory to pull 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."),
+      version: z.string().optional().describe("Pull an older version's source instead of HEAD."),
+      force: z.boolean().optional().describe("Pull 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];
+      const args = ["pull", 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");

package/src/tools.js

@@ -33,7 +33,8 @@ export {
   parseCliPlugUrl,
   plugViaCliFallback,
   runPlug,
-  runFork,
+  runPickup,
+  runPull,
   runSource,
   runVisibility,
   runCheckDeploy,

package/src/widgets/org-picker.html

@@ -44,7 +44,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
     var html =
       '<div class="card">' +
         '<div class="title">Choose a grid</div>' +
-        '<div class="subtitle">Which grid should this be published to?</div>' +
+        '<div class="subtitle">Which grid should this be plugged into?</div>' +
         '<div class="orgs">';
     for (var i = 0; i < items.length; i++) {
       var org = items[i];
@@ -66,7 +66,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
           var all = document.querySelectorAll(".org-btn");
           for (var k = 0; k < all.length; k++) all[k].classList.add("loading");
           var statusEl = document.getElementById("status");
-          if (statusEl) statusEl.textContent = "Publishing\u2026";
+          if (statusEl) statusEl.textContent = "Plugging\u2026";
           if (!window.openai || !window.openai.callTool) return;
           var input = (window.openai && window.openai.toolInput) || {};
           var args = {};
@@ -79,7 +79,7 @@ body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;b
             // The host will render the new result with the live-result card.
           }).catch(function () {
             for (var m = 0; m < all.length; m++) all[m].classList.remove("loading");
-            if (statusEl) statusEl.textContent = "Failed to publish";
+            if (statusEl) statusEl.textContent = "Failed to plug";
           });
         });
       })(buttons[j]);