@cloudgrid-io/mcp 0.17.0 → 0.19.0

package/src/tools.js

@@ -3,7 +3,7 @@
 // Two editions register from here:
 //   - local (stdio): full toolset, including the CLI-wrapping tools. Identity
 //     comes from ~/.cloudgrid/credentials.
-//   - web (HTTP, hosted): the light, CLI-free toolset (drop, claim, login).
+//   - web (HTTP, hosted): the light, CLI-free toolset (plug, claim, login).
 //     Identity is a per-session token held in memory.
 //
 // The difference is injected as a `ctx` object, so the tool logic is written once.
@@ -44,6 +44,14 @@ const ANON_HTML_MAX_BYTES = 2_000_000;
 const AUTHED_HTML_MAX_BYTES = 25_000_000;
 const CONSOLE_URL = "https://console.cloudgrid.io/";
 
+const VISIBILITY_LABELS = {
+  private: "Only you",
+  org: "Your org",
+  authenticated: "Anyone signed in",
+  space: "A space",
+  link: "Anyone with the link",
+};
+
 // ── Widget resources (ChatGPT Apps SDK, web edition only) ────────────────────
 // The Apps-SDK UI widgets (openai/outputTemplate → a ui:// html resource) render
 // as a broken black frame in ChatGPT today, hiding the plain-text result. Gate
@@ -64,14 +72,6 @@ const WIDGET_CSP = {
   resourceDomains: ["https://*.cloudgrid.io"],
 };
 
-const VISIBILITY_LABELS = {
-  private: "Only you",
-  org: "Your org",
-  authenticated: "Anyone signed in",
-  space: "A space",
-  link: "Anyone with the link",
-};
-
 function ok(text) {
   return { content: [{ type: "text", text }] };
 }
@@ -94,14 +94,18 @@ Operating rules:
 6. If a signed-in publish fails with a server error, do not fall back to anonymous publishing (it burns the anonymous quota and downgrades ownership); surface the error, use the CLI fallback if offered, or ask the user.
 7. When signed in and the user has more than one grid, do not assume a target — the publish tools will ask; relay the choice to the user and pass the chosen grid.
 8. When a build/deploy fails unexpectedly, offer to report it to the CloudGrid team — only with the user's explicit consent (ask first). Send just the error + the failed request by default (call grid_report), and never send the whole conversation unless the user agrees (include_conversation). Respect privacy.
-9. To modify an existing drop when you don't already have its HTML in context, first call grid_source to fetch the current HTML, apply your change, then call grid_drop/grid_plug with target_entity_id (the drop's entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
-10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use grid_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
+9. To modify an existing page when you don't already have its HTML in context, first call grid_source to fetch the current HTML, apply your change, then call grid_plug with target_entity_id (the entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
+10. Publishing a single HTML page: pass it inline as grid_plug's html parameter (a full self-contained document). For a heavy or image-heavy page in the local edition, pass the path parameter instead so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a page looks empty, use grid_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
 11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
-12. To choose what to build: match the request against the workflow when: triggers and the capability-map (grid_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Static (needs: none) deploys as an inspiration (instant, any edition); anything needing needs: is a runtime (async, local edition).
+12. To choose what to build: match the request against the workflow when: triggers and the capability-map (grid_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Classify the ARTIFACT to pick the deploy: ONE self-contained HTML page (a single file — CSS+JS inline, images/fonts as data: URIs; that is the normal hosted output) → an inspiration — instant, ANY edition, deploy via grid_plug with the inline html param. Only genuinely SEPARATE files/folders (a real assets/ dir, separate .css/.js files, multiple pages, a SPA build) — OR anything needing needs: (data/server/LLM/cron) → a runtime app — grid_plug on a linked folder with a cloudgrid.yaml, local edition only, async build.
 13. Before writing a cloudgrid.yaml, fetch the reference: grid_fetch({kind:"doc", name:"cloudgrid-yaml"}) — it has the full schema and the needs: vocabulary. Declare infrastructure with needs: (the deployer injects from it): needs: { database: true } → Mongo (DATABASE_MONGODB_URL); needs: { cache: true } → Redis; scheduled work → a service of type: cron (Python or Node). Use needs: OR requires:, never both — declaring both is rejected.
 14. Databases — CloudGrid supports both, so never tell the user to self-host. Managed: needs: { database: true } provisions Mongo and injects DATABASE_MONGODB_URL. Bring-your-own (they already run Postgres / MySQL / MongoDB / Supabase / Neon / PlanetScale / etc.): needs: { database: { tier: external, secret: MY_DB } } plus grid secrets set MY_DB=<connection-string> — the connection string lives in env SECRETS, never committed. If asked "what databases does CloudGrid support?": all of them — the managed CloudGrid database out of the box, or bring your own via keys — ask which they want.
+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_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.
 
-Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;
+Deploy is via grid_plug on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI). A single HTML page deploys synchronously as an inspiration, so you get a URL right away.`;
 
 // The corpus subdirectories that grid_fetch serves, keyed by `kind`. Each
 // lives in its own subtree of src/corpus/ (populated by scripts/snapshot-corpus.mjs
@@ -710,9 +714,9 @@ async function fetchUserOrgs(token) {
   }
 }
 
-// ── Shared grid disambiguation (grid_drop + grid_plug) ──────────────────
-// The stateless "which grid?" ask, used identically by both publish verbs so
-// they never drift. Given the caller's token and a supplied grid, it decides:
+// ── 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 }
 //   - >1 grid and none supplied           → { picker } (a ready-to-return result)
 //   - exactly one grid                    → { single: annotatedOrg } — the caller
@@ -771,31 +775,6 @@ export async function resolveGridOrAsk(ctx, { token, suppliedGrid, edition }, de
   return { proceed: true };
 }
 
-// After an authenticated web drop, upgrade visibility to "link" so the artifact
-// is shareable and its preview renders without a sign-in wall. Best-effort — a
-// failure here does not fail the drop; the user can always call grid_visibility.
-async function upgradeVisibilityToLink(ctx, entityId, orgSlug) {
-  const token = await ctx.getToken();
-  if (!token || !entityId) return false;
-  try {
-    const hdrs = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
-    // Send the grid-native header; keep X-CloudGrid-Org in parallel (same value)
-    // during the org→grid soak. Never send conflicting values → 400 GRID_HEADER_CONFLICT.
-    if (orgSlug) {
-      hdrs["X-CloudGrid-Grid"] = orgSlug;
-      hdrs["X-CloudGrid-Org"] = orgSlug;
-    }
-    const res = await fetch(`${API_BASE}/api/v2/inspirations/${encodeURIComponent(entityId)}`, {
-      method: "PATCH",
-      headers: hdrs,
-      body: JSON.stringify({ visibility: "link" }),
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
 // ── Direct-API tools (both editions) ───────────────────────────────────────────
 function looksLikeFullHtml(s) {
   const head = s.replace(/^/, "").trimStart().slice(0, 256).toLowerCase();
@@ -846,6 +825,55 @@ 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_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
+// a file-path-looking or non-HTML input so a path/base64 blob is never published
+// as page content. The auth-aware inline size cap is enforced later in runPlug
+// (it depends on the anon-vs-authed wire).
+function htmlToArtifact(html, filename) {
+  if (typeof html !== "string" || html.length === 0) {
+    throw new Error("`html` must be the complete HTML document as a string.");
+  }
+  // Strip an invented `@`-prefix shorthand, then reject a bare file path — the
+  // inline html path takes HTML CONTENT, not a path (use `path` for a file).
+  let candidate = html.startsWith("@") ? html.slice(1) : html;
+  if (!looksLikeFullHtml(candidate) && looksLikePath(candidate)) {
+    throw new Error(
+      `This looks like a file path (\`${candidate.trim()}\`), not HTML. Pass the raw HTML inline as ` +
+        "`html`, or pass the file/folder via `path` — do not pass a path as `html`.",
+    );
+  }
+  // Rescue a base64-of-HTML blob passed as `html` (real user repro): decode it
+  // rather than publishing a wall of base64 text.
+  const { html: resolved } = decodeIfBase64Html(candidate);
+  let content = resolved;
+  if (!looksLikeFullHtml(content)) {
+    const stripped = content.replace(/\s+/g, "");
+    const looksBase64 =
+      stripped.length >= 64 && stripped.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(stripped);
+    const isShortFragment = Buffer.byteLength(content, "utf8") <= 8192;
+    const hasTag = /<[a-z][\s\S]*>/i.test(content);
+    if (isShortFragment && (hasTag || (!looksBase64 && !looksLikePath(content)))) {
+      // Legit "share this snippet" — wrap a small text/markup fragment into a
+      // full document (preserve the old drop's friendly behavior).
+      content =
+        `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8">` +
+        `<title>Shared on CloudGrid</title></head>\n<body>\n${content}\n</body>\n</html>\n`;
+    } else {
+      // Large, or base64 that failed to decode to HTML, or a bare file path:
+      // refuse instead of silently publishing garbage.
+      const kind = looksBase64 ? "base64" : looksLikePath(content) ? "a file path" : "raw data";
+      throw new Error(
+        `This doesn't look like an HTML document (it looks like ${kind}). Pass the raw HTML as \`html\`, ` +
+          "or in the local edition pass `path` to the .html file — do NOT base64-encode it.",
+      );
+    }
+  }
+  return { path: filename || "index.html", buffer: Buffer.from(content, "utf8"), type: "text/html" };
+}
+
 // Anonymous drops are owned by the platform Guest Org, whose slug is the apex
 // the public URL hangs off (https://guest.cloudgrid.io/<slug>).
 const GUEST_ORG_SLUG = "guest";
@@ -908,430 +936,6 @@ export function resolvePlugUrl(data) {
   return composePlugUrl(data);
 }
 
-export async function runDrop(
-  ctx,
-  { html, path: filePath, filename, anonymous, org, grid, fresh, entity_id, owner_token },
-  deps = {},
-) {
-  // `grid` is an accepted alias for `org` (Gilad's org→grid rename); `org` still works.
-  const targetGrid = org ?? grid;
-  // The `deps` seam (readFile/exists) exists ONLY so the content-handling
-  // regression tests can drive the `path` / `@`-path routes offline. Production
-  // always calls this with no deps.
-  const { readFile: readFileImpl = readFile, fsExists = existsSync } = deps;
-
-  // Defensive: the web edition schema excludes `path`, but if a model still
-  // passes one (e.g. from a cached tool description), reject early with a
-  // clear explanation.
-  if (ctx.edition === "web" && filePath) {
-    throw new Error(
-      "The hosted server cannot read local files — pass the full document as `html` instead of a `path`.",
-    );
-  }
-
-  // An agent may pass an `@`-prefixed path (invented `@/home/claude/...`
-  // shorthand) or a bare filesystem path as `html`. Normalise: strip a leading
-  // `@`, and in the local edition promote a path-looking `html` to the `path`
-  // route (read from disk) when the file exists. On the hosted server there is
-  // no disk, so a path-looking `html` is a clear error.
-  let effectivePath = filePath;
-  let htmlInput = typeof html === "string" ? html : undefined;
-  if (!effectivePath && typeof htmlInput === "string") {
-    let candidate = htmlInput;
-    if (candidate.startsWith("@")) candidate = candidate.slice(1);
-    if (!looksLikeFullHtml(candidate) && looksLikePath(candidate)) {
-      if (ctx.edition === "web") {
-        throw new Error(
-          `This looks like a file path (\`${candidate.trim()}\`), but the hosted server cannot read local ` +
-            `files — pass the raw HTML inline as \`html\`.`,
-        );
-      }
-      const resolvedPath = candidate.trim();
-      if (fsExists(resolvedPath)) {
-        effectivePath = resolvedPath;
-        htmlInput = undefined;
-      } else {
-        throw new Error(
-          `The path \`${resolvedPath}\` does not exist. Pass a valid \`path\` to the .html file, or pass ` +
-            `the raw HTML inline as \`html\` (do not base64-encode it, and there is no artifact_files parameter).`,
-        );
-      }
-    } else if (candidate !== htmlInput) {
-      // Leading `@` on genuine inline content — strip it and keep the content.
-      htmlInput = candidate;
-    }
-  }
-
-  let bytes;
-  let name;
-  let type;
-  // Anonymous drops are inline-capped hard; signed-in drops get a larger cap.
-  // The cap is enforced AFTER auth is resolved (see below), so only inline
-  // routes flag themselves here — `path` (local, read from disk) is uncapped.
-  let enforceInlineCap = false;
-
-  if (effectivePath) {
-    const raw = await readFileImpl(effectivePath);
-    const asText = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw);
-    const { html: decoded, wasBase64 } = decodeIfBase64Html(asText);
-    const lowerName = String(effectivePath).toLowerCase();
-    const nameIsHtml = lowerName.endsWith(".html") || lowerName.endsWith(".htm");
-    if (wasBase64) {
-      // A base64 `.txt` (or similar) that decoded to real HTML → publish the
-      // decoded HTML as text/html under an index.html name.
-      bytes = Buffer.from(decoded, "utf8");
-      type = "text/html";
-      name = filename || (nameIsHtml ? basename(effectivePath) : "index.html");
-    } else {
-      bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
-      // Content-type sniff (fix #4): serve HTML as text/html so it renders as a
-      // page instead of downloading as a blob.
-      if (looksLikeFullHtml(asText) || nameIsHtml) {
-        type = "text/html";
-        name = filename || (nameIsHtml ? basename(effectivePath) : "index.html");
-      } else {
-        type = "application/octet-stream";
-        name = filename || basename(effectivePath);
-      }
-    }
-  } else if (typeof htmlInput === "string" && htmlInput.length > 0) {
-    // Rescue a base64-of-HTML blob passed as `html` (real user repro).
-    const { html: resolved } = decodeIfBase64Html(htmlInput);
-    let content = resolved;
-    if (!looksLikeFullHtml(content)) {
-      const stripped = content.replace(/\s+/g, "");
-      const looksBase64 =
-        stripped.length >= 64 && stripped.length % 4 === 0 && /^[A-Za-z0-9+/]+={0,2}$/.test(stripped);
-      const isShortFragment = Buffer.byteLength(content, "utf8") <= 8192;
-      const hasTag = /<[a-z][\s\S]*>/i.test(content);
-      if (isShortFragment && (hasTag || (!looksBase64 && !looksLikePath(content)))) {
-        // Legit "share this snippet" — wrap a small text/markup fragment into a
-        // full document (preserve existing friendly behavior).
-        content =
-          `<!doctype html>\n<html lang="en">\n<head><meta charset="utf-8">` +
-          `<title>Shared on CloudGrid</title></head>\n<body>\n${content}\n</body>\n</html>\n`;
-      } else {
-        // Large, or base64 that failed to decode to HTML, or a bare file path:
-        // refuse instead of silently publishing garbage.
-        const kind = looksBase64
-          ? "base64"
-          : looksLikePath(content)
-            ? "a file path"
-            : "raw data";
-        throw new Error(
-          `This doesn't look like an HTML document (it looks like ${kind}). Pass the raw HTML as \`html\`, ` +
-            `or in the local edition pass \`path\` to the .html file — do NOT base64-encode it. ` +
-            `There is no artifact_files parameter.`,
-        );
-      }
-    }
-    bytes = Buffer.from(content, "utf8");
-    name = filename || "index.html";
-    type = "text/html";
-    enforceInlineCap = true;
-  } else {
-    throw new Error("Provide either `html` (inline content) or `path` (a local file).");
-  }
-
-  // The caller's authed identity (unless they force an anonymous drop).
-  let authToken = null;
-  let orgSlug = null;
-  if (anonymous !== true) {
-    authToken = await ctx.getToken();
-    if (authToken) {
-      orgSlug = targetGrid || (await ctx.getActiveGrid());
-    }
-  }
-
-  // ── Re-plug targeting (unified plug contract / spec v2) ──────
-  // A `target_entity_id` on the wire UPDATES THAT SAME ENTITY in place — same
-  // entity_id, same slug, same URL, deploy history preserved. Absent → create.
-  // The session remembers the last drop, so a re-drop updates it by default;
-  // `fresh: true` forces a create; an explicit `entity_id` targets any earlier
-  // drop (the durable re-plug handle a stateless caller persisted).
-  if (fresh === true && entity_id) {
-    throw new Error("`fresh: true` forces a new drop — do not pass `entity_id` with it.");
-  }
-  const sessionDrop = ctx.state.lastDrop;
-  let targetId = null;
-  let ownerToken = typeof owner_token === "string" && owner_token.length > 0 ? owner_token : null;
-  if (fresh !== true) {
-    targetId = entity_id || sessionDrop?.entity_id || null;
-    // An anon-minted drop is edited with its OWNER TOKEN (a bearer capability,
-    // the anon owner-token contract). Recover it from session state when not passed.
-    if (targetId && !ownerToken) {
-      if (sessionDrop?.entity_id === targetId && sessionDrop.owner_token) {
-        ownerToken = sessionDrop.owner_token;
-      } else if (ctx.state.lastAnonClaim?.entity_id === targetId && ctx.state.lastAnonClaim.token) {
-        ownerToken = ctx.state.lastAnonClaim.token;
-      }
-    }
-  }
-
-  // Pick the edit wire. An anon-owned (Guest-Grid, unclaimed) drop is edited via
-  // the owner-token wire EVEN IF the caller is signed in — the entity still lives
-  // in the Guest Grid, so an authed edit of it would 404. An authed edit targets
-  // an entity the caller owns in their grid.
-  let mode = "create"; // "create" | "authed-edit" | "anon-edit"
-  if (targetId) {
-    if (ownerToken) {
-      mode = "anon-edit";
-    } else if (authToken) {
-      mode = "authed-edit";
-    } else if (entity_id) {
-      throw new Error(
-        "Re-plugging a drop anonymously needs its owner_token (returned when it was created). " +
-          "Pass owner_token, sign in if you own it, or pass fresh: true to publish a new drop.",
-      );
-    } else {
-      // Session target, but no way to authorize an edit — fall back to create.
-      targetId = null;
-    }
-  }
-  const isAnonymousWire = mode === "anon-edit" || !authToken;
-
-  // Auth-aware inline size cap (relocated here — auth is only known now). Anon
-  // inline drops stay capped at 2MB; signed-in inline drops get the larger
-  // AUTHED cap. `path` (read from disk) is uncapped and does not set the flag.
-  if (enforceInlineCap) {
-    if (isAnonymousWire) {
-      if (bytes.byteLength > ANON_HTML_MAX_BYTES) {
-        throw new Error(
-          `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Anonymous drops are capped at 2 MB. ` +
-            `Trim it, or sign in to publish larger.`,
-        );
-      }
-    } else if (bytes.byteLength > AUTHED_HTML_MAX_BYTES) {
-      throw new Error(
-        `This HTML is ${(bytes.byteLength / 1e6).toFixed(2)} MB. Inline drops are capped at ` +
-          `${(AUTHED_HTML_MAX_BYTES / 1e6).toFixed(0)} MB. In the local edition pass \`path\` to the ` +
-          `.html file (read from disk — no inline size limit) instead of pasting it inline.`,
-      );
-    }
-  }
-
-  const headers = {};
-  if (!isAnonymousWire) {
-    headers["Authorization"] = `Bearer ${authToken}`;
-    // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
-    if (orgSlug) {
-      headers["X-CloudGrid-Grid"] = orgSlug;
-      headers["X-CloudGrid-Org"] = orgSlug;
-    }
-  }
-
-  // Hosted server: attach the trusted-server credential on EVERY anonymous call
-  // (creates AND owner-token edits — anon edits consume the same daily anon cap,
-  // re-keyed per end user). Falls back gracefully server-side if absent. Only
-  // the web edition sets ctx.trustedServer.
-  if (isAnonymousWire && ctx.trustedServer?.secret && ctx.trustedServer?.endUserId) {
-    headers["X-CloudGrid-Trusted-Server-Auth"] = ctx.trustedServer.secret;
-    headers["X-CloudGrid-Trusted-Server-End-User"] = ctx.trustedServer.endUserId;
-  }
-
-  // Ownership continuity: replay the platform's anon-session cookie across drops in
-  // this session, so cookie-class callers can redrop (and claim) what they dropped.
-  if (isAnonymousWire && ctx.state.anonCookie) {
-    headers["Cookie"] = ctx.state.anonCookie;
-  }
-
-  const form = new FormData();
-  // The artifact part name is unchanged from `/drop/auto` (`artifact`); the plug
-  // create path — and the inspiration edit paths — treat every
-  // non-`cloudgrid.yaml` part as raw artifact bytes.
-  form.append("artifact", new Blob([bytes], { type }), name);
-  if (mode !== "create") {
-    form.append("target_entity_id", targetId);
-  }
-  if (mode === "anon-edit") {
-    // Anon owner-token contract: ownership is proven by HOLDING the token (a form
-    // field, NOT an Authorization header). The response re-mints it.
-    form.append("owner_token", ownerToken);
-  }
-  if (mode === "authed-edit") {
-    // The authed update path requires a `cloudgrid.yaml` part on the wire
-    // (materializePlugTarball). An inspiration edit ignores its content, so an
-    // empty part satisfies the contract without changing the entity's config.
-    form.append("cloudgrid.yaml", new Blob([""], { type: "text/plain" }), "cloudgrid.yaml");
-  }
-  // `/plug` resolves the authed org from the `X-CloudGrid-Org` header (set
-  // above), not a form field — so `org_slug` is no longer sent.
-
-  let res;
-  try {
-    res = await fetch(`${API_BASE}/api/v2/plug`, { method: "POST", headers, body: form });
-  } catch (err) {
-    throw new Error(`Could not reach CloudGrid at ${API_BASE}: ${err.message}`);
-  }
-
-  const raw = await res.text();
-  let data = null;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    /* handled below */
-  }
-  if (!res.ok) {
-    const code = data?.error?.code;
-    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
-    const hint = data?.error?.details?.[0]?.hint;
-    const isEdit = mode !== "create";
-    // Self-heal rung: a signed-in CREATE that hits the known 400 SCOPE_INVALID
-    // platform bug is retried through the bundled CLI — LOCAL edition only,
-    // create only, never anonymous. (Mirrors runPlug.)
-    if (
-      res.status === 400 &&
-      code === "SCOPE_INVALID" &&
-      ctx.edition === "local" &&
-      mode === "create" &&
-      !isAnonymousWire &&
-      authToken
-    ) {
-      return plugViaCliFallback(ctx, [{ path: name, buffer: bytes }], deps);
-    }
-    // An explicit edit NEVER silently creates — surface the reason clearly.
-    if (isEdit && res.status === 409) {
-      throw new Error(
-        `Re-plug rejected (HTTP 409): ${msg} ` +
-          "The drop can no longer be edited in place (expired, archived, claimed, or a deploy is running). " +
-          "Pass fresh: true to publish a new drop instead.",
-      );
-    }
-    if (mode === "anon-edit" && res.status === 401) {
-      throw new Error(
-        `Re-plug rejected (HTTP 401): ${msg} ` +
-          "The owner_token did not authorize this entity (wrong entity, expired with the drop, or already claimed). " +
-          "Pass fresh: true to publish a new drop instead.",
-      );
-    }
-    // Known-code guidance (SCOPE_INVALID on web, 429 anon cap, etc.); unknown
-    // codes pass through as the bare error line, unchanged.
-    const guidance = errorGuidance({
-      status: res.status,
-      code,
-      edition: ctx.edition,
-      isEdit,
-      isAnon: isAnonymousWire,
-      signedIn: Boolean(authToken),
-    });
-    const baseLine = `Drop failed (HTTP ${res.status}): ${msg}${hint ? ` ${hint}` : ""}`;
-    throw new Error(guidance ? `${baseLine} — ${guidance}` : baseLine);
-  }
-
-  // Persist the platform's anon-session cookie for ownership continuity (so a
-  // cookie-class caller can claim — via pickup — what it dropped).
-  const setCookies = res.headers.getSetCookie
-    ? res.headers.getSetCookie()
-    : [res.headers.get("set-cookie")].filter(Boolean);
-  const anonCookie = (setCookies || [])
-    .map((c) => (c || "").split(";")[0])
-    .find((c) => c.startsWith("cg_anon_session="));
-  if (anonCookie) ctx.state.anonCookie = anonCookie;
-
-  // The server composes the canonical URL; compose client-side only as
-  // a fallback when it came back empty.
-  const url = resolvePlugUrl(data);
-  const isEdit = mode !== "create";
-
-  // The anon owner token: the create response mints it; every anon edit
-  // RE-MINTS it to the reset TTL (replace the stored one — the freshest token
-  // is the one that lives as long as the drop). Same JWT the claim uses.
-  let freshOwnerToken = typeof data.owner_token === "string" && data.owner_token.length > 0
-    ? data.owner_token
-    : null;
-  if (!freshOwnerToken && data.claim_url) {
-    try {
-      freshOwnerToken = new URL(data.claim_url).searchParams.get("token");
-    } catch {
-      freshOwnerToken = null;
-    }
-  }
-
-  // Remember the drop for session continuity — any caller class. The
-  // `{entity_id, owner_token}` pair is the stateless anon re-plug handle.
-  if (data.entity_id || url) {
-    ctx.state.lastDrop = {
-      entity_id: data.entity_id ?? ctx.state.lastDrop?.entity_id ?? null,
-      url: url ?? ctx.state.lastDrop?.url ?? null,
-      owner_token: isAnonymousWire
-        ? (freshOwnerToken ?? (mode === "anon-edit" ? ownerToken : null))
-        : null,
-    };
-  }
-
-  // Authenticated wire (create or in-place edit): the entity is owned by the caller.
-  if (!isAnonymousWire) {
-    ctx.state.lastAnonClaim = null;
-    const structured = {
-      url,
-      status: isEdit ? "updated" : "created",
-      owned_by: "authenticated",
-      ...(data.entity_id ? { entity_id: data.entity_id } : {}),
-    };
-    const lines = [];
-    if (isEdit) {
-      lines.push(`Updated in place: ${url}`);
-      lines.push("Same link, new content. The expiry timer was reset.");
-    } else if (ctx.edition === "web") {
-      lines.push(`Your app is live: ${url}`);
-    } else {
-      lines.push(`Published to your org: ${url}`, "Owned by you.");
-    }
-    if (ctx.edition === "web" && !isEdit) {
-      // Default authed web CREATES to "link" visibility so the URL is shareable
-      // and the console thumbnail renders without a sign-in wall. An edit keeps
-      // the entity's existing visibility untouched.
-      if (data.entity_id) {
-        await upgradeVisibilityToLink(ctx, data.entity_id, orgSlug);
-      }
-      lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
-      const vis = "link";
-      lines.push(`Visible to: ${VISIBILITY_LABELS[vis]}. Want to restrict access? I can set it to only you or your org.`);
-      structured.console_url = CONSOLE_URL;
-      structured.current_visibility = vis;
-      structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
-    }
-    return { text: lines.join("\n"), structured };
-  }
-
-  // Anonymous wire — Guest-Grid inspiration (create 201, or owner-token edit).
-  // The response carries the reward fields (`claim_url` + `claim_message`), the
-  // real `entity_id`, and the OWNER TOKEN — the bearer capability that
-  // authorizes BOTH a later anonymous re-plug and the claim (pickup-by-id).
-  if (data.claim_url || data.entity_id) {
-    ctx.state.lastAnonClaim = {
-      token: freshOwnerToken,
-      entity_id: data.entity_id ?? ctx.state.lastAnonClaim?.entity_id ?? null,
-      url,
-    };
-  }
-  const lines = [];
-  if (isEdit) {
-    lines.push(`Updated in place: ${url}`);
-    lines.push("Same link, new content. The expiry timer (and owner_token) were refreshed.");
-  } else {
-    lines.push(ctx.edition === "web" ? `Your app is live: ${url}` : `Live: ${url}`);
-  }
-  if (data.claim_message) {
-    lines.push(data.claim_message);
-  } else if (data.claim_url) {
-    lines.push("Sign in, then run grid_claim to keep it past the expiry window.");
-  }
-  if (data.entity_id && freshOwnerToken) {
-    lines.push(
-      `Re-plug handle (persist to update or claim this drop in a later session): entity_id=${data.entity_id}`,
-    );
-  }
-  return {
-    text: lines.join("\n"),
-    structured: {
-      url,
-      status: isEdit ? "updated" : "created",
-      ...(data.entity_id ? { entity_id: data.entity_id } : {}),
-      ...(freshOwnerToken ? { owner_token: freshOwnerToken } : {}),
-    },
-  };
-}
 
 // ── Consent-gated error reporting (Task 34 / 0.8.1) ──────────────────────────
 // Key names that look like they carry a secret. Mirrors the server's
@@ -1873,6 +1477,32 @@ export async function plugViaCliFallback(ctx, artifacts, deps = {}) {
   }
 }
 
+// After an authenticated WEB inspiration create, upgrade visibility to "link" so
+// the page is shareable and its preview renders without a sign-in wall — the
+// whole point of the hosted "share a link with a friend" flow. Best-effort: a
+// failure here never fails the publish (the user can always call grid_visibility).
+async function upgradeVisibilityToLink(ctx, entityId, orgSlug) {
+  const token = await ctx.getToken();
+  if (!token || !entityId) return false;
+  try {
+    const hdrs = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
+    // Grid-native header + X-CloudGrid-Org alias (same value) during the soak.
+    // Never send conflicting values → 400 GRID_HEADER_CONFLICT.
+    if (orgSlug) {
+      hdrs["X-CloudGrid-Grid"] = orgSlug;
+      hdrs["X-CloudGrid-Org"] = orgSlug;
+    }
+    const res = await fetch(`${API_BASE}/api/v2/inspirations/${encodeURIComponent(entityId)}`, {
+      method: "PATCH",
+      headers: hdrs,
+      body: JSON.stringify({ visibility: "link" }),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The unified create/re-plug verb (spec v2 §3). Two intents on one tool, keyed
  * by `target_entity_id`:
@@ -1889,27 +1519,46 @@ export async function runPlug(ctx, input, deps = {}) {
   const {
     path: srcPath,
     artifact_files,
+    html,
+    filename,
     cloudgrid_yaml,
     target_entity_id,
     grid,
+    slug,
     hints,
     anon,
     owner_token,
   } = input || {};
 
-  // ── Source: path XOR artifact_files ────────────────────────────────────────
-  if (srcPath && Array.isArray(artifact_files) && artifact_files.length > 0) {
-    throw new Error("Pass either `path` or `artifact_files`, not both.");
+  // ── Source: exactly one of html | artifact_files | path ─────────────────────
+  const hasHtml = typeof html === "string" && html.length > 0;
+  const hasArtifacts = Array.isArray(artifact_files) && artifact_files.length > 0;
+  const hasPath = Boolean(srcPath);
+  if ((hasHtml ? 1 : 0) + (hasArtifacts ? 1 : 0) + (hasPath ? 1 : 0) > 1) {
+    throw new Error(
+      "Pass exactly one source: `html` (a single inline HTML document), `artifact_files` " +
+        "(multiple inline files), or `path` (a local file/folder).",
+    );
   }
-  if (ctx.edition === "web" && srcPath) {
+  if (ctx.edition === "web" && hasPath) {
     throw new Error(
-      "The hosted server cannot read local files — pass the source inline via `artifact_files`.",
+      "The hosted server cannot read local files — pass the source inline via `html` or `artifact_files`.",
     );
   }
   let artifacts;
-  if (srcPath) {
+  // Set on the single-file `html` path so the auth-aware inline size cap can be
+  // enforced once the anon-vs-authed wire is known (see below).
+  let inlineHtmlBytes = null;
+  if (hasHtml) {
+    // The ergonomic single-file publish path (the old drop verb): one self-
+    // contained HTML document → one index.html artifact, with the shared
+    // hardening (base64 rescue, @-path/file-path rejection, fragment wrap).
+    const art = htmlToArtifact(html, filename);
+    inlineHtmlBytes = art.buffer.byteLength;
+    artifacts = [art];
+  } else if (hasPath) {
     artifacts = collectPathArtifacts(srcPath);
-  } else if (Array.isArray(artifact_files) && artifact_files.length > 0) {
+  } else if (hasArtifacts) {
     let total = 0;
     artifacts = artifact_files.map((f) => {
       if (!f || typeof f.path !== "string" || typeof f.content !== "string") {
@@ -1925,12 +1574,25 @@ export async function runPlug(ctx, input, deps = {}) {
   } else {
     throw new Error(
       ctx.edition === "web"
-        ? "Provide the source via `artifact_files`."
-        : "Provide the source via `path` (a local file or folder) or `artifact_files`.",
+        ? "Provide the source via `html` (a single inline HTML document) or `artifact_files`."
+        : "Provide the source via `html` (a single inline HTML document), `path` (a local file " +
+          "or folder), or `artifact_files`.",
     );
   }
 
-  const isEdit = typeof target_entity_id === "string" && target_entity_id.length > 0;
+  // grid+slug re-plug handle (the pickup contract's `replug_handle`): when no
+  // explicit target_entity_id was given but a grid+slug pair is, resolve it to
+  // an existing entity_id and re-plug that in place. A slug that does NOT resolve
+  // to an existing entity → targetEntityId stays empty → this is a CREATE (no
+  // false-positive re-plug). target_entity_id remains the primary/documented
+  // handle. Best-effort resolve (pickup contract); never fetches the public URL.
+  let targetEntityId = target_entity_id;
+  if ((typeof targetEntityId !== "string" || targetEntityId.length === 0) && grid && slug) {
+    const resolved = await resolveEntityViaPickup(ctx, { target: slug, grid });
+    if (resolved?.entity_id) targetEntityId = resolved.entity_id;
+  }
+
+  const isEdit = typeof targetEntityId === "string" && targetEntityId.length > 0;
 
   // An inspiration edit content-versions the FIRST uploaded artifact — when a
   // multi-file folder rides a re-plug, put the primary entry first so the edit
@@ -1950,10 +1612,10 @@ export async function runPlug(ctx, input, deps = {}) {
   if (isEdit && !ownerToken) {
     // Recover the owner token from session state when re-plugging the drop this
     // session made anonymously.
-    if (ctx.state.lastDrop?.entity_id === target_entity_id && ctx.state.lastDrop.owner_token) {
+    if (ctx.state.lastDrop?.entity_id === targetEntityId && ctx.state.lastDrop.owner_token) {
       ownerToken = ctx.state.lastDrop.owner_token;
     } else if (
-      ctx.state.lastAnonClaim?.entity_id === target_entity_id &&
+      ctx.state.lastAnonClaim?.entity_id === targetEntityId &&
       ctx.state.lastAnonClaim.token
     ) {
       ownerToken = ctx.state.lastAnonClaim.token;
@@ -1970,7 +1632,30 @@ export async function runPlug(ctx, input, deps = {}) {
     );
   }
 
+  // Auth-aware inline size cap for the single-file `html` path (the old drop
+  // cap). Anonymous inline pages stay capped at 2 MB; signed-in inline pages get
+  // the larger AUTHED cap. `path` (read from disk) and `artifact_files` are
+  // bounded by PLUG_MAX_TOTAL_BYTES instead, so they never set inlineHtmlBytes.
+  if (inlineHtmlBytes != null) {
+    if (useAnonWire) {
+      if (inlineHtmlBytes > ANON_HTML_MAX_BYTES) {
+        throw new Error(
+          `This HTML is ${(inlineHtmlBytes / 1e6).toFixed(2)} MB. Anonymous drops are capped at 2 MB. ` +
+            "Trim it, or sign in to publish larger.",
+        );
+      }
+    } else if (inlineHtmlBytes > AUTHED_HTML_MAX_BYTES) {
+      throw new Error(
+        `This HTML is ${(inlineHtmlBytes / 1e6).toFixed(2)} MB. Inline drops are capped at ` +
+          `${(AUTHED_HTML_MAX_BYTES / 1e6).toFixed(0)} MB. In the local edition pass \`path\` to the ` +
+          ".html file (read from disk — no inline size limit) instead of pasting it inline.",
+      );
+    }
+  }
+
   const headers = {};
+  // The authed target grid — also reused for the post-create visibility upgrade.
+  let orgSlug = null;
   if (!useAnonWire && authToken) {
     headers["Authorization"] = `Bearer ${authToken}`;
     // On create, `grid` picks where the entity lands. On re-plug the entity's
@@ -1978,7 +1663,7 @@ export async function runPlug(ctx, input, deps = {}) {
     // the caller's membership from this header and requires it to MATCH the
     // entity's grid, so pass `grid` here too when the target lives outside the
     // active grid.
-    const orgSlug = grid || (await ctx.getActiveGrid());
+    orgSlug = grid || (await ctx.getActiveGrid());
     // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
     if (orgSlug) {
       headers["X-CloudGrid-Grid"] = orgSlug;
@@ -2012,10 +1697,13 @@ export async function runPlug(ctx, input, deps = {}) {
   // ── Wire assembly ───────────────────────────────────────────────────────────
   const form = new FormData();
   for (const a of artifacts) {
-    form.append("artifact", new Blob([a.buffer], { type: "application/octet-stream" }), a.path);
+    // Folder-walk / artifact_files parts ride as octet-stream (server sniffs by
+    // name); the single-file `html` path carries text/html so a bare inline page
+    // renders instead of downloading (the old drop behavior).
+    form.append("artifact", new Blob([a.buffer], { type: a.type || "application/octet-stream" }), a.path);
   }
   if (isEdit) {
-    form.append("target_entity_id", target_entity_id);
+    form.append("target_entity_id", targetEntityId);
     if (useAnonWire) {
       form.append("owner_token", ownerToken);
     } else {
@@ -2086,7 +1774,7 @@ export async function runPlug(ctx, input, deps = {}) {
     throw new Error(plugErrorMessage(res.status, code, msg, flags));
   }
 
-  // Anon-session cookie continuity (mirrors runDrop).
+  // Anon-session cookie continuity.
   const setCookies = res.headers.getSetCookie
     ? res.headers.getSetCookie()
     : [res.headers.get("set-cookie")].filter(Boolean);
@@ -2107,7 +1795,7 @@ export async function runPlug(ctx, input, deps = {}) {
     }
   }
 
-  // Session continuity — the same state runDrop keeps.
+  // Session continuity — remember the last plug for re-plug handles.
   if (data.entity_id || url) {
     ctx.state.lastDrop = {
       entity_id: data.entity_id ?? null,
@@ -2146,6 +1834,20 @@ export async function runPlug(ctx, input, deps = {}) {
   // the terminal states get the live wording; anything still building points at
   // the poll_url and grid_status.
   const isBuilding = data.status === "building" || Boolean(data.poll_url);
+
+  // An authed CREATE of an INSPIRATION (the single-file `html` path, or a server-
+  // detected inspiration — NOT a runtime app/agent, NOT a build in flight, NOT an
+  // anon guest drop). This is the case that (on the hosted edition) must be made
+  // link-visible so the shared URL renders without a sign-in wall.
+  const detectedKind = data.detection?.kind;
+  const isInspirationCreate =
+    !isEdit &&
+    !useAnonWire &&
+    !isBuilding &&
+    detectedKind !== "app" &&
+    detectedKind !== "agent" &&
+    (inlineHtmlBytes != null || detectedKind === "inspiration");
+
   const lines = [];
   if (isBuilding) {
     lines.push(
@@ -2158,8 +1860,14 @@ export async function runPlug(ctx, input, deps = {}) {
         ? `Poll ${data.poll_url} or run grid_status until it is ready (trace ${data.trace_id ?? "n/a"}). Do not report it as live until then.`
         : "Run grid_status until it is ready. Do not report it as live until then.",
     );
+  } else if (isEdit) {
+    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 org: ${url}`);
+    if (ctx.edition !== "web") lines.push("Owned by you.");
   } else {
-    lines.push(isEdit ? `Updated in place: ${url}` : `Live: ${url}`);
+    lines.push(`Live: ${url}`);
   }
   if (data.entity_id) {
     lines.push(
@@ -2170,6 +1878,22 @@ export async function runPlug(ctx, input, deps = {}) {
   if (isEdit && useAnonWire) {
     lines.push("The owner_token was re-minted for the reset expiry — replace the stored one.");
   }
+
+  // Hosted "share a link with a friend": a signed-in WEB inspiration create is
+  // upgraded to "link" visibility so its preview renders without a sign-in wall.
+  // Scoped EXACTLY to web + create + inspiration — never runtime apps/agents,
+  // edits, anon drops, or the local edition (which stays owned/org-scoped).
+  if (isInspirationCreate && ctx.edition === "web" && data.entity_id) {
+    await upgradeVisibilityToLink(ctx, data.entity_id, orgSlug);
+    const vis = "link";
+    structured.console_url = CONSOLE_URL;
+    structured.current_visibility = vis;
+    structured.visibility_options = Object.entries(VISIBILITY_LABELS).map(([v, l]) => ({ value: v, label: l }));
+    lines.push(`See and manage all your apps in your grid: ${CONSOLE_URL}`);
+    lines.push(
+      `Visible to: ${VISIBILITY_LABELS[vis]}. Want to restrict access? I can set it to only you or your org.`,
+    );
+  }
   return { text: lines.join("\n"), structured };
 }
 
@@ -2331,8 +2055,10 @@ function isCloudgridHost(hostname) {
 }
 
 // Shape an HTML string into the grid_source result (shared by the API-read
-// and the public-fetch paths). Caps the body at SOURCE_MAX_BYTES.
-function shapeSourceResult(sourceUrl, entityId, htmlStr) {
+// and the public-fetch paths). Caps the body at SOURCE_MAX_BYTES. `extra` carries
+// optional edition metadata resolved from the pickup contract (kind, single_html,
+// capabilities, replug_handle, source_download_url) — merged into structured.
+function shapeSourceResult(sourceUrl, entityId, htmlStr, extra = {}) {
   const buf = Buffer.from(htmlStr, "utf-8");
   const totalBytes = buf.length;
   const truncated = totalBytes > SOURCE_MAX_BYTES;
@@ -2348,7 +2074,7 @@ function shapeSourceResult(sourceUrl, entityId, htmlStr) {
   lines.push("", html);
   return {
     text: lines.join("\n"),
-    structured: { url: sourceUrl, entity_id: entityId ?? null, bytes: totalBytes, truncated, html },
+    structured: { url: sourceUrl, entity_id: entityId ?? null, bytes: totalBytes, truncated, html, ...extra },
   };
 }
 
@@ -2384,6 +2110,50 @@ async function readInspirationSourceViaApi(ctx, { entityId, slug, grid }) {
   return null;
 }
 
+// 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
+// session entity_id (a fresh chat): the contract returns
+//   { entity_id, slug, grid, kind, single_html, capabilities, replug_handle,
+//     source_download_url, ... }
+// so the agent can re-plug the SAME entity in place. This is a metadata resolve
+// (no claim_token in the body → no ownership transfer). Best-effort: returns null
+// on any failure so the caller falls back to today's behavior — and NEVER fetches
+// the public *.cloudgrid.io URL (the hosted pod cannot egress to it).
+async function resolveEntityViaPickup(ctx, { target, url, grid }) {
+  const pathSeg = target || url;
+  if (!pathSeg) return null;
+  let token = null;
+  try { token = await ctx.getToken(); } catch { /* anonymous is fine */ }
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+  // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak.
+  if (grid) {
+    headers["X-CloudGrid-Grid"] = grid;
+    headers["X-CloudGrid-Org"] = grid;
+  }
+  if (ctx.state.anonCookie) headers["Cookie"] = ctx.state.anonCookie;
+  try {
+    const res = await fetch(
+      `${API_BASE}/api/v2/entities/${encodeURIComponent(pathSeg)}/pickup`,
+      {
+        method: "POST",
+        headers,
+        // Send the URL as a resolution key too (the contract accepts id, slug, or
+        // a {url} body). NO claim_token → resolve only, never a claim.
+        body: JSON.stringify(url ? { url } : {}),
+        signal: AbortSignal.timeout(15_000),
+      },
+    );
+    if (!res.ok) return null;
+    const data = await res.json().catch(() => null);
+    if (data && typeof data.entity_id === "string" && data.entity_id.length > 0) return data;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
 // Fetch a drop's/inspiration's current deployed HTML inline as text so an agent
 // that lost the content can edit it and re-plug in place. Resolves the fetch URL
 // (explicit url → session lastDrop → composed grid+slug), then reads the HTML
@@ -2422,19 +2192,40 @@ export async function runSource(ctx, { entity_id, url, grid, slug } = {}) {
   }
 
   const resolvedUrl = parsed.toString();
-  const eid = entity_id ?? (last && (!entity_id || last.entity_id === entity_id) ? last.entity_id : null);
+  let eid = entity_id ?? (last && (!entity_id || last.entity_id === entity_id) ? last.entity_id : null);
 
-  // ── API-first (reachable) ────────────────────────────────────────────────
-  // Read the HTML from the API server-side rather than fetching the public URL.
-  // The hosted MCP pod can reach the API but NOT the public *.cloudgrid.io
-  // ingress ("fetch failed") — this is the fix for hosted edit-in-place. Derive
-  // the grid/slug hint from the inspiration path URL (`grid.cloudgrid.io/slug`).
+  // Derive the grid/slug hint from the inspiration path URL (`grid.cloudgrid.io/slug`).
   const host = parsed.hostname;
   const gridHint = grid ?? (host.endsWith(".cloudgrid.io") && !host.includes("--") && host.split(".").length === 3
     ? host.split(".")[0] : null);
   const slugHint = slug ?? (parsed.pathname.replace(/^\/+/, "").split("/")[0] || null);
+
+  // ── URL → entity_id (fresh chat, no session) via the pickup contract ──────
+  // When a bare URL/slug arrived with no known entity_id, resolve a REAL
+  // entity_id (+ edition metadata) so the agent can re-plug in place. Best-
+  // effort: a failure falls back to today's behavior (never regress the read),
+  // and we NEVER fetch the public URL for resolution.
+  let extra = {};
+  if (!eid) {
+    const pickup = await resolveEntityViaPickup(ctx, { target: slugHint, url: resolvedUrl, grid: gridHint });
+    if (pickup?.entity_id) {
+      eid = pickup.entity_id;
+      extra = {
+        ...(pickup.kind ? { kind: pickup.kind } : {}),
+        ...(typeof pickup.single_html === "boolean" ? { single_html: pickup.single_html } : {}),
+        ...(pickup.capabilities ? { capabilities: pickup.capabilities } : {}),
+        ...(pickup.replug_handle ? { replug_handle: pickup.replug_handle } : {}),
+        ...(pickup.source_download_url ? { source_download_url: pickup.source_download_url } : {}),
+      };
+    }
+  }
+
+  // ── API-first (reachable) ────────────────────────────────────────────────
+  // Read the HTML from the API server-side rather than fetching the public URL.
+  // The hosted MCP pod can reach the API but NOT the public *.cloudgrid.io
+  // ingress ("fetch failed") — this is the fix for hosted edit-in-place.
   const apiHtml = await readInspirationSourceViaApi(ctx, { entityId: eid, slug: slugHint, grid: gridHint });
-  if (apiHtml != null) return shapeSourceResult(resolvedUrl, eid, apiHtml);
+  if (apiHtml != null) return shapeSourceResult(resolvedUrl, eid, apiHtml, extra);
 
   // ── Fallback: direct public fetch ────────────────────────────────────────
   // Local edition has normal egress; last resort on hosted (e.g. a runtime app
@@ -2470,7 +2261,7 @@ export async function runSource(ctx, { entity_id, url, grid, slug } = {}) {
   }
 
   const buf = Buffer.from(await res.arrayBuffer());
-  return shapeSourceResult(resolvedUrl, eid, buf.toString("utf-8"));
+  return shapeSourceResult(resolvedUrl, eid, buf.toString("utf-8"), extra);
 }
 
 // ── Registration ───────────────────────────────────────────────────────────────
@@ -2521,144 +2312,6 @@ export function registerTools(server, ctx) {
 
   // ── Direct-API tools (both editions) ──────────────────────────────────────
 
-  // Drop — both editions, but the input schema is edition-aware: the web
-  // edition removes `path` (the cloud server cannot read local files) and
-  // strengthens `html` so the model always pastes the full document inline.
-  const dropReplugParams = {
-    fresh: z.boolean().optional().describe("Force a brand-new drop (new URL) even if you already dropped in this session. Default: a re-drop updates the session's drop in place — same URL, new content."),
-    entity_id: z.string().optional().describe("Re-plug a SPECIFIC entity by id (the durable handle a previous drop returned) — updates it in place, same URL. Defaults to this session's last drop."),
-    owner_token: z.string().optional().describe("The owner token of an anonymously-created drop (returned when it was created; refreshed on every anonymous edit). Needed to re-plug or claim it from a new session."),
-  };
-  const dropInputSchema = ctx.edition === "web"
-    ? {
-        html: z.string().optional().describe(
-          "The COMPLETE HTML document to publish — paste the full file contents here (not a path). " +
-          "For a game, include all HTML/CSS/JS inline so it runs standalone. " +
-          "A fragment is wrapped into a full document automatically.",
-        ),
-        filename: z.string().optional().describe("Filename to present. Defaults to index.html for inline HTML."),
-        anonymous: z.boolean().optional().describe("Force an anonymous drop even if the user is signed in."),
-        grid: z.string().optional().describe("Leave unset; the tool will ask the user which grid to publish into. Only set this after the user picks from the list the tool returns."),
-        org: z.string().optional().describe("Deprecated alias for `grid` (kept for compatibility). Prefer `grid`."),
-        ...dropReplugParams,
-      }
-    : {
-        html: z.string().optional().describe("Inline HTML to publish (a small fragment is wrapped into a full document). Pass the RAW HTML — do NOT base64-encode it, and do NOT pass an `@`-prefixed path or a file path here. For a large or image-heavy document, use `path` instead."),
-        path: z.string().optional().describe("Path to a local .html file to upload instead of inline HTML — read from disk with no inline size limit. Preferred for large or image-heavy documents. There is no `artifact_files` parameter."),
-        filename: z.string().optional().describe("Filename to present. Defaults to index.html for inline HTML."),
-        anonymous: z.boolean().optional().describe("Force an anonymous drop even if the user is signed in."),
-        grid: z.string().optional().describe("Leave unset; the tool will ask the user which grid to publish into. Only set this after the user picks from the list the tool returns."),
-        org: z.string().optional().describe("Deprecated alias for `grid` (kept for compatibility). Prefer `grid`."),
-        ...dropReplugParams,
-      };
-
-  reg(
-    "grid_drop",
-    {
-      description: "Publish an HTML page or file to CloudGrid and get a public shareable URL. Use when the user wants to share, publish, send, or 'deploy' an artifact, or wants a link to send a friend. Re-drops in the same session UPDATE THE SAME entity in place — same link, new content, expiry reset (pass fresh: true to force a new drop, or entity_id to target a specific earlier drop). If signed in, it publishes into the user's grid as an owned inspiration; if not, it drops anonymously into the Guest Grid, claimable later — the result includes an entity_id + owner_token to persist as the re-plug/claim handle for later sessions. Drops expire per the platform default (7 days) unless claimed/owned; every in-place edit resets the timer. If you want to edit an existing drop but no longer have its HTML, call grid_source first to retrieve it, then re-plug with target_entity_id. For a large or image-heavy document in the local edition, pass `path` to the .html file (read from disk — no inline size limit); do NOT base64-encode the content and do NOT pass an `@`-prefixed path or a file path as `html`. There is no `artifact_files` parameter. Calls POST /api/v2/plug directly.",
-      inputSchema: dropInputSchema,
-      outputSchema: {
-        url: z.string().optional().describe("The public URL of the drop (stable across re-drops of the same entity)."),
-        status: z.enum(["created", "updated", "unchanged"]).optional().describe("What happened to the drop."),
-        entity_id: z.string().optional().describe("The entity's durable id — pass back as entity_id to update it in place later."),
-        owner_token: z.string().optional().describe("Anonymous drops only: the bearer owner token for later re-plug/claim. Refreshed on every anonymous edit — always persist the newest one."),
-        owned_by: z.string().optional().describe("Ownership class, e.g. 'authenticated'."),
-        expires_at: z.string().optional().describe("Expiry timestamp, if any."),
-        console_url: z.string().optional().describe("URL to manage all apps in the grid."),
-        current_visibility: z.string().optional().describe("Current visibility of the drop."),
-        visibility_options: z.array(z.object({
-          value: z.string().describe("Visibility value to pass to grid_visibility."),
-          label: z.string().describe("Human-readable label."),
-        })).optional().describe("Available visibility levels."),
-        needs_grid: z.boolean().optional().describe("True when the user must choose a grid before dropping."),
-        needs_org: z.boolean().optional().describe("Deprecated alias of needs_grid (kept so the org-picker widget keeps working)."),
-        grids: z.array(z.object({
-          slug: z.string().describe("Grid slug to pass as the grid parameter."),
-          name: z.string().describe("Human-readable grid name."),
-          role: z.string().describe("User's role in the grid."),
-          is_active: z.boolean().optional().describe("True if this is the user's currently active grid."),
-        })).optional().describe("The user's grids, when a grid choice is needed."),
-        orgs: z.array(z.object({
-          slug: z.string().describe("Grid slug to pass as the grid parameter."),
-          name: z.string().describe("Human-readable grid name."),
-          role: z.string().describe("User's role in the grid."),
-          is_active: z.boolean().optional().describe("True if this is the user's currently active grid."),
-        })).optional().describe("Deprecated alias of grids (kept so the org-picker widget keeps working)."),
-        needs_sign_in: z.boolean().optional().describe("True when sign-in is needed before dropping."),
-        login_url: z.string().optional().describe("Sign-in URL when authentication is needed."),
-      },
-      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,
-        },
-      } : {}),
-    },
-    async (input) => {
-      try {
-        // Web edition: reject `path` early — the hosted server cannot read
-        // local files. The schema already omits it, but a model with a
-        // cached tool description might still send one.
-        if (ctx.edition === "web" && input?.path) {
-          return fail(
-            "The hosted server cannot read local files — pass the full document as `html` instead of a `path`.",
-          );
-        }
-
-        // Web edition: sign-in guidance when unauthenticated.
-        if (ctx.edition === "web" && input?.anonymous !== true) {
-          const token = await ctx.getToken();
-          if (!token) {
-            const url = buildLoginUrl(newLoginCode());
-            return okResult({
-              text: `Sign in to publish to your org.\n${url}`,
-              structured: { needs_sign_in: true, login_url: url },
-            });
-          }
-        }
-
-        // Stateless grid disambiguation — both editions, when authenticated.
-        // No dependency on prior-call state so it works even when the client
-        // reconnects on every tool call (ChatGPT Apps SDK behaviour). `grid` is
-        // accepted as an alias for `org` (Gilad's rename); `org` still works.
-        if (input?.anonymous !== true) {
-          const token = await ctx.getToken();
-          if (token) {
-            const suppliedGrid = input?.grid || input?.org;
-            const decision = await resolveGridOrAsk(ctx, {
-              token,
-              suppliedGrid,
-              edition: ctx.edition,
-            });
-            if (decision.picker) {
-              return okResult(decision.picker);
-            }
-            if (decision.single) {
-              if (!decision.single.render_ready) {
-                // Single grid but not set up — tell the agent so it can warn
-                // the user and offer anonymous drop as fallback. (drop-specific:
-                // drop blocks here; plug proceeds with a warning.)
-                const annotated = [{ ...decision.single, render_ready: false }];
-                return okResult({
-                  text: `Your only grid "${decision.single.slug}" isn't fully set up yet — pages published there may not load. You can drop anonymously (set anonymous: true) or wait until provisioning completes, then re-run.`,
-                  structured: { needs_grid: true, needs_org: true, grid_not_ready: true, org_not_ready: true, grids: annotated, orgs: annotated },
-                });
-              }
-              input = { ...(input || {}), org: decision.single.slug };
-            } else if (decision.grid) {
-              // Supplied grid matched — normalize onto `org` for runDrop.
-              input = { ...(input || {}), org: decision.grid };
-            }
-          }
-        }
-        return okResult(await runDrop(ctx, input || {}));
-      } catch (err) {
-        return fail(err.message);
-      }
-    },
-  );
-
   // Claim — both editions.
   reg(
     "grid_claim",
@@ -2689,13 +2342,21 @@ export function registerTools(server, ctx) {
   // CLI-wrapping grid_plug: 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 artifact_files.",
+            "Mutually exclusive with `html` and `artifact_files`.",
           ),
         }),
     artifact_files: z.array(z.object({
@@ -2703,8 +2364,10 @@ export function registerTools(server, ctx) {
       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 (an HTML deck, a one-file app)." +
-      (ctx.edition === "web" ? "" : " Prefer `path` on the local edition."),
+      "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. " +
@@ -2720,6 +2383,12 @@ export function registerTools(server, ctx) {
       "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."),
@@ -2738,17 +2407,22 @@ export function registerTools(server, ctx) {
     "grid_plug",
     {
       description:
-        "Surface a creation onto the grid — the unified create/re-plug verb (POST /api/v2/plug). " +
+        "Deploy or share a creation on CloudGrid and get a public URL — the ONE create/re-plug verb " +
+        "(POST /api/v2/plug). Use it whenever the user wants to share, publish, send, ship, 'deploy', go " +
+        "live, or get a link to send a friend — for a single HTML page OR a full app. " +
+        "Sources (pass exactly one): `html` — a single self-contained HTML page (the fast path: instant, any " +
+        "edition, anonymous+claimable or into your grid when signed in); " +
+        (ctx.edition === "web"
+          ? "or `artifact_files` — a multi-file app inline. "
+          : "`path` — a local folder/file (a multi-file app); or `artifact_files` — inline files. ") +
         "No target_entity_id → CREATE a new entity (inspiration/app/agent, auto-detected or hinted); " +
-        "with target_entity_id → RE-PLUG: update the SAME entity in place — same entity_id, same URL, same " +
+        "with target_entity_id (or grid+slug — the replug_handle, when you hold only those) → RE-PLUG: " +
+        "update the SAME entity in place — same entity_id, same URL, same " +
         "deploy history, expiry reset. The returned entity_id + url are the durable re-plug handle; persist " +
-        "them (plus owner_token for anonymous drops) to update the entity in later sessions. " +
-        (ctx.edition === "web"
-          ? "Pass the source inline via artifact_files."
-          : "Pass the source as a local `path` (folder or file) or inline via artifact_files.") +
-        " Note: in-place re-plug currently supports inspirations (HTML/static drops); to rebuild a deployed " +
-        "app/agent, use the CloudGrid CLI (`cloudgrid plug`) in its linked folder." +
-        " If you want to edit an existing drop but no longer have its HTML, call grid_source first to " +
+        "them (plus owner_token for anonymous pages) to update the entity in later sessions. " +
+        "Note: in-place re-plug currently supports inspirations (HTML/static pages); to rebuild a deployed " +
+        "app/agent, use the CloudGrid CLI (`cloudgrid plug`) in its linked folder. " +
+        "If you want to edit an existing page but no longer have its HTML, call grid_source first to " +
         "retrieve it, then re-plug with target_entity_id.",
       inputSchema: plugInputSchema,
       outputSchema: {
@@ -2761,12 +2435,24 @@ export function registerTools(server, ctx) {
         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_visibility."),
+          label: z.string().describe("Human-readable label."),
+        })).optional().describe("Web authed inspiration create: available visibility levels."),
       },
       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,
+        },
+      } : {}),
     },
     async (input) => {
       try {
-        // Grid-picker parity with grid_drop: a signed-in user with >1 grid is
+        // 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
@@ -2881,10 +2567,14 @@ export function registerTools(server, ctx) {
       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 drop you made earlier). Defaults to this session's last drop; otherwise pass the public " +
-        "url (or grid+slug). Works for single-document HTML drops/inspirations (the common case). For " +
-        "multi-file or runtime (app/agent) deploys, use grid_download (signed tarball URLs) instead. " +
-        "Fetches the public *.cloudgrid.io URL server-side; read-only, creates nothing.",
+        "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 (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."),
@@ -2897,6 +2587,19 @@ export function registerTools(server, ctx) {
         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_plug'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 },
     },
@@ -3174,7 +2877,7 @@ export function registerTools(server, ctx) {
           .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_drop."),
+            tool: z.string().optional().describe("The CloudGrid tool that failed, e.g. grid_plug."),
             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."),