@cloudgrid-io/mcp 0.20.31 → 0.20.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.31",
+  "version": "0.20.33",
   "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": {
@@ -54,13 +54,14 @@
     "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",
-    "test:proxy": "node test/proxy.test.mjs"
+    "test:proxy": "node test/proxy.test.mjs",
+    "test:system-ca": "node test/system-ca.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "express": "^4.22.2",
     "fflate": "^0.8.3",
-    "undici": "^8.7.0",
+    "undici": "^6.27.0",
     "zod": "^3.23.0"
   },
   "license": "Apache-2.0",

package/src/auth.js

@@ -13,6 +13,7 @@ import { randomUUID } from "node:crypto";
 import { mkdir, writeFile, chmod, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { isCertError } from "./system-ca.js";
 
 // Base for server-to-API calls. On a hosted deployment this is the in-cluster
 // service address (CLOUDGRID_API_URL), which is fast but NOT reachable by a browser.
@@ -41,6 +42,33 @@ export function buildLoginUrl(code) {
   return `${PUBLIC_API_BASE}/auth/login?code=${encodeURIComponent(code)}`;
 }
 
+const CERT_ERROR_GUIDANCE =
+  "TLS certificate validation failed. This machine has a TLS-inspecting " +
+  "proxy or a custom root CA that is not in the OS trust store. The MCP " +
+  "trusts the system certificate store automatically, so if you still see " +
+  "this error the intercepting CA's root certificate is not installed in " +
+  "your OS trust store.\n\n" +
+  "To resolve this:\n" +
+  "- Install the root CA into your OS trust store (macOS Keychain, Windows " +
+  "Certificate Manager, or /usr/local/share/ca-certificates on Linux), or\n" +
+  "- Set NODE_EXTRA_CA_CERTS=/path/to/root-ca.pem before launching the MCP, or\n" +
+  "- Use the hosted MCP connector: https://mcp-connected.cloudgrid.io/mcp";
+
+function throwCertError() {
+  const err = new Error(CERT_ERROR_GUIDANCE);
+  err.certError = true;
+  throw err;
+}
+
+export async function checkApiConnectivity() {
+  try {
+    await fetch(`${API_BASE}/auth/status?code=connectivity-probe`);
+  } catch (err) {
+    if (isCertError(err)) throwCertError();
+    throw err;
+  }
+}
+
 // One poll. Returns { status: 'not_started' | 'pending' | 'authenticated' | 'expired', jwt? }.
 // A 404 means the session for this code does not exist yet — the user has not
 // opened the sign-in URL — so it is reported as 'not_started', not an error.
@@ -49,6 +77,7 @@ export async function pollStatusOnce(code) {
   try {
     res = await fetch(`${API_BASE}/auth/status?code=${encodeURIComponent(code)}`);
   } catch (err) {
+    if (isCertError(err)) throwCertError();
     const cause = err?.cause?.code || err?.cause?.message || err?.cause || err.message;
     throw new Error(
       `Can't reach api.cloudgrid.io (${cause}). ` +

package/src/corpus/capability-map.md

@@ -4,14 +4,14 @@ This is the index an LLM uses to turn a user request into the right CloudGrid
 template, the way Superpowers matches a skill's `when:`. Match the request to a
 template by its `when:` triggers, adopt that template's `needs:`, then deploy:
 
-> **One deploy verb: `grid_deploy`.** Classify the artifact to pick the shape —
+> **One deploy verb: `grid_plug`.** Classify the artifact to pick the shape —
 > ONE self-contained HTML page (CSS+JS inline, images/fonts as data: URIs) →
 > **inspiration**; separate files/folders/assets or any `needs:` → **runtime app**.
 
 - **single self-contained HTML page → inspiration** (instant, any client / any
-  edition) via `grid_deploy` with the inline `html` param.
+  edition) via `grid_plug` with the inline `html` param.
 - **separate files/folders/assets, or anything needing `needs:` → runtime app**
-  (async build, **local edition** only) via `grid_deploy` on a linked folder.
+  (async build, **local edition** only) via `grid_plug` on a linked folder.
 
 Fetch this doc any time with `grid_get_template("doc", "capability-map")`. For the full
 cloudgrid.yaml schema (every field, the `needs:` injection table, the
@@ -188,9 +188,9 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
    RAG's ideal `vector: pgvector` now works - #1545 shipped; the shipped
    templates still store embeddings in Mongo until they are updated.)
 3. One self-contained HTML page (`needs: none`, assets inlined) → publish as an
-   inspiration with `grid_deploy` and the inline `html` param (instant, any
+   inspiration with `grid_plug` and the inline `html` param (instant, any
    edition). Separate files/folders/assets, or anything with a `needs:` →
-   runtime, local edition, `grid_deploy` a linked folder, then poll to a live URL.
+   runtime, local edition, `grid_plug` a linked folder, then poll to a live URL.
 
 ## FAQ
 

package/src/corpus/cloudgrid-yaml.md

@@ -29,7 +29,7 @@ These are the shapes verified against live deploys. Copy one and adapt it.
 ### Single HTML page → deploys as an inspiration (instant)
 
 One self-contained HTML page (CSS+JS inline, images/fonts as data: URIs). No
-`needs:`. Publishes instantly via `grid_deploy` with the inline `html` param,
+`needs:`. Publishes instantly via `grid_plug` with the inline `html` param,
 works on any edition (hosted or local).
 
 ```yaml
@@ -544,7 +544,7 @@ Bake these into any yaml you author:
   it**; use `needs:` instead.
 - **`needs:` and `requires:` together are HARD-REJECTED** by the validator ("use
   one or the other"). So author **`needs:`-only** — never set both.
-- **A single self-contained HTML page deploys as an inspiration** via `grid_deploy`
+- **A single self-contained HTML page deploys as an inspiration** via `grid_plug`
   with the inline `html` param — instant, synchronous, works on the hosted edition
   and any client.
 - **A `cloudgrid.yaml` with `services:` makes it a runtime** — async build,

package/src/corpus/cookbook.md

@@ -77,7 +77,7 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
 The response includes `url` (the live link — use it verbatim), `entity_id`,
 `owner_token` (keep both to update the page later), and `claim_url` (sign in
 before it expires to keep it). This is what the `cloudgrid:plug` skill and the
-`grid_deploy` MCP tool (inline `html` param) do for you. It is anonymous and serves
+`grid_plug` MCP tool (inline `html` param) do for you. It is anonymous and serves
 inspirations only; a full app needs the signed-in `plug` flow above.
 
 ## Update your drop in place

package/src/corpus/playbook.md

@@ -7,21 +7,23 @@ Operating rules:
 4. Always return the live share URL at the end — that is the deliverable. On a NEW deploy, then ASK the user who should be able to open it — private (only you), a space, your grid, anyone with the link, or anyone signed in — and set their choice with grid_visibility. Never pick the visibility silently. On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it.
 5. Brainstorm first (lightly) for a real app, then minimize questions. For a substantial runtime app, take ONE lightweight beat before generating/deploying: confirm the goal + 3-5 core features in a sentence, check for a matching template/recipe (capability-map), and infer the data/runtime needs and STATE them ("I'll add a database so entries are saved"). Keep it to a line or two; never ask a non-technical user infra questions they can't answer. A simple single page skips this and builds immediately. Otherwise use sensible defaults and build; don't front-load setup questions.
 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. For a NEW app, establish the grid UP FRONT — grid_start returns the grids; if there is more than one, ask "which grid should this go on?" before you start building, and carry that slug into grid_deploy. As a backstop, grid_deploy hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of deploying; a create with no auth and no anon returns needs_auth (sign-in vs anonymous) instead of silently publishing anonymously. Relay either ask to the user; never pick silently.
+7. When signed in and the user has more than one grid, do not assume a target. For a NEW app, establish the grid UP FRONT — grid_start returns the grids; if there is more than one, ask "which grid should this go on?" before you start building, and carry that slug into grid_plug. As a backstop, grid_plug hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of deploying; a create with no auth and no anon returns needs_auth (sign-in vs anonymous) instead of silently publishing anonymously. Relay either ask to the user; never pick silently.
 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 page when you don't already have its HTML in context, first call grid_get_app_source to fetch the current HTML, apply your change, then call grid_deploy 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_deploy'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_get_app_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_get_app_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_get_app_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_get_template({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_deploy 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_deploy on a linked folder with a cloudgrid.yaml, local edition only, async build.
+12. To choose what to build: match the request against the workflow when: triggers and the capability-map (grid_get_template({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_get_template({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_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_deploy with target_entity_id (or grid+slug — the replug_handle) to update the SAME URL in place. This works on every edition, including hosted.
+  - 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_copy_app and edit the copy instead.
-16. Help CloudGrid QA. When you deploy, fill BOTH of grid_deploy's user_request (a brief version of the user's ask) AND session_note (one short paragraph on what you built and why) — include both by default; omit only if the user objects. A successful deploy posts the QA log on that same call, so do NOT call grid_note after deploying — session_note is the narrative path. Use grid_note only BEFORE a deploy, or in a session that ends without one. Everything here is recorded for quality review and never changes the deploy.
+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_deploy 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.
+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.
+18. Using the CLI (runtime apps, `grid dev`, or any shell step): the verb is `grid`, but ALWAYS invoke it as `npx -y @cloudgrid-io/cli@latest <command>` — never a bare `grid` or `cloudgrid`. A `grid` already on the machine is usually a stale global that the API rejects on its version floor, so a bare command fails with a version error and wastes turns; `npx …@latest` needs no install and is always current. In a local edition, prefer the MCP `grid_*` tools — they resolve a current CLI for you — and drop to `npx …@latest` only for shell-only steps like `grid dev`.
+19. Deploying a runtime app (multi-file, or anything with `needs:`) from a terminal-capable edition (Claude Code, Cursor, or a plain terminal): make the CLI ready BEFORE you deploy, in ONE pass — do NOT run the plug first and then react to "command not found" / version errors. Sequence: `npx -y @cloudgrid-io/cli@latest whoami` (if not signed in, `npx -y @cloudgrid-io/cli@latest login` and wait for the user), optionally `npx -y @cloudgrid-io/cli@latest dev` to test locally (the AI gateway and `needs:` resources are tunnelled into dev), then `npx -y @cloudgrid-io/cli@latest plug --grid <slug>`. When you hand a hosted/web user the steps to finish a runtime build locally, give them these same `npx …@latest` commands (never a bare `cloudgrid`/`grid`) alongside their downloaded folder or .zip.
 
-Deploy is via grid_deploy on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI). A single HTML page deploys synchronously as an inspiration, so you get a URL right away. A user-supplied ZIP archive (local edition): pass its path directly as the path param — it is extracted and deployed as a static app; if the zip is assets-only (e.g. images for a gallery), generate the page and pass it as html alongside the zip path, and it becomes the index.html over the archive's files.
-When you deploy a folder that already has a cloudgrid.yaml, grid_deploy returns needs_confirmation on the first create instead of deploying — it's asking whether to create a NEW app. Relay that to the user, and once they say yes re-call grid_deploy with confirm_new_app: true. To update an existing app instead, pass its target_entity_id.
+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 — see rules 18–19: run the CLI as `npx -y @cloudgrid-io/cli@latest`, ready before the plug). A single HTML page deploys synchronously as an inspiration, so you get a URL right away. A user-supplied ZIP archive (local edition): pass its path directly as the path param — it is extracted and deployed as a static app; if the zip is assets-only (e.g. images for a gallery), generate the page and pass it as html alongside the zip path, and it becomes the index.html over the archive's files.
+When you deploy a folder that already has a cloudgrid.yaml, grid_plug returns needs_confirmation on the first create instead of deploying — it's asking whether to create a NEW app. Relay that to the user, and once they say yes re-call grid_plug with confirm_new_app: true. To update an existing app instead, pass its target_entity_id.

package/src/corpus/skill-plug.md

@@ -58,7 +58,7 @@ curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
   -F "artifact=@/path/to/index.html;type=text/html"
 ```
 
-The MCP `grid_deploy` tool does all of this for you: pass the page as its inline
+The MCP `grid_plug` tool does all of this for you: pass the page as its inline
 `html` param (it materializes one `index.html` and handles anon/claim/re-plug).
 
 ### Re-plug: update the same URL in place

package/src/corpus/templates/api-docs/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML API reference: a sidebar endpoint list, per-endpoint method badges (GET / POST / PUT / DELETE), a params table, and request / response examples in code blocks.
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/api-docs/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "api-docs")` and fill in the user's content.

package/src/corpus/templates/appointment-booking/AGENTS.md

@@ -175,7 +175,7 @@ you want client accounts.
    `vault:` block maps from). Non-secret config (auth publishable key, price ids)
    → `grid_set_env` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
    yourself — the grid injects it.
-5. `grid_deploy` to deploy. A runtime deploy is **ASYNC** — the first response
+5. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
    is `status: building`, not a live URL. Poll `grid_status` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    silent wait.
@@ -189,7 +189,7 @@ An appointment-booking app is a built + deployed runtime container, so it
 requires the **local edition** (Claude Desktop / Claude Code) or the CLI. The
 **hosted** edition (Claude Web / hosted MCP) is inline-only and can only publish
 static pages — it CANNOT build this app. On hosted, say so plainly and offer a
-static "book us" landing page (via `grid_deploy`) instead, then stop the runtime
+static "book us" landing page (via `grid_plug`) instead, then stop the runtime
 path.
 
 ## 7. Reminders (cron — PENDING platform issue #1543)

package/src/corpus/templates/appointment-booking/index.md

@@ -66,7 +66,7 @@ vault:
 ## Deploy (async, local edition)
 
 `grid_create_project` first (creates the entity + link.json), write the app under
-`services/web/`, set the vault secrets with `grid_set_secret`, `grid_deploy`
+`services/web/`, set the vault secrets with `grid_set_secret`, `grid_plug`
 (async — poll `grid_status` to a live URL). If taking deposits, register the
 `/api/webhook` URL in Stripe and re-plug. Re-plug the same entity to update the
 same URL.

package/src/corpus/templates/changelog/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML changelog / release-notes page: reverse-chronological versioned entries, each with a date and tagged change items (added / fixed / changed / removed).
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/changelog/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "changelog")` and fill in the user's content.

package/src/corpus/templates/company-website/README.md

@@ -10,10 +10,10 @@ wire it to your own email service or form endpoint if you want real submissions.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "company-website")` and fill in the user's content.

package/src/corpus/templates/company-website/cloudgrid.yaml

@@ -11,7 +11,7 @@
 # ignored by the parser, so the file deploys to exactly the active fields.
 #
 # company-website is a STATIC template (type: static, path: /) with no needs.
-# The fast path deploys the page as an INSPIRATION via grid_deploy (instant,
+# The fast path deploys the page as an INSPIRATION via grid_plug (instant,
 # works on hosted). This cloudgrid.yaml is the reference for plugging it as an
 # OWNED static runtime; the active fields are exactly: name + services.web.
 #

package/src/corpus/templates/company-website/index.md

@@ -6,10 +6,10 @@ Inline CSS + inline JS only (no external scripts, stylesheets, fonts, or CDNs).
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "company-website")` and fill in the user's content.

package/src/corpus/templates/dashboard/cloudgrid.yaml

@@ -16,7 +16,7 @@
 # THIS TEMPLATE (dashboard): a single self-contained static page. The active fields
 # are exactly name + services.web{type: static, path: /}; there are no needs.
 # This cloudgrid.yaml is the reference for plugging it as an OWNED static
-# runtime; the fast path is to deploy it as an INSPIRATION via grid_deploy
+# runtime; the fast path is to deploy it as an INSPIRATION via grid_plug
 # (instant, and works on the hosted edition too).
 # ============================================================================
 

package/src/corpus/templates/dashboard/index.md

@@ -5,10 +5,10 @@ no `needs:`. State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "dashboard")` and fill in the user's content.

package/src/corpus/templates/deck/cloudgrid.yaml

@@ -16,7 +16,7 @@
 # THIS TEMPLATE (deck): a single self-contained static page. The active fields
 # are exactly name + services.web{type: static, path: /}; there are no needs.
 # This cloudgrid.yaml is the reference for plugging it as an OWNED static
-# runtime; the fast path is to deploy it as an INSPIRATION via grid_deploy
+# runtime; the fast path is to deploy it as an INSPIRATION via grid_plug
 # (instant, and works on the hosted edition too).
 # ============================================================================
 

package/src/corpus/templates/deck/index.md

@@ -5,10 +5,10 @@ no `needs:`. State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "deck")` and fill in the user's content.

package/src/corpus/templates/docs-site/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML documentation site: a sidebar nav, a scrolling content column with headings and code blocks, and a client-side search box that filters the nav. No backend.
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/docs-site/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "docs-site")` and fill in the user's content.

package/src/corpus/templates/forum/AGENTS.md

@@ -179,7 +179,7 @@ A forum is a runtime (built + deployed container) app — **local edition**
 4. Set the auth secrets: `grid_set_secret` (or the org vault) for the provider
    keys. Do NOT set `DATABASE_MONGODB_URL` — the grid injects it.
 5. (Optional) `grid dev` to run locally against injected Mongo before shipping.
-6. `grid_deploy` to deploy. A runtime deploy is **ASYNC** — the first response
+6. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
    is `status: building`, not a live URL. Poll `grid_status` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    spinner.

package/src/corpus/templates/landing-page/cloudgrid.yaml

@@ -16,7 +16,7 @@
 # THIS TEMPLATE (landing-page): a single self-contained static page. The active fields
 # are exactly name + services.web{type: static, path: /}; there are no needs.
 # This cloudgrid.yaml is the reference for plugging it as an OWNED static
-# runtime; the fast path is to deploy it as an INSPIRATION via grid_deploy
+# runtime; the fast path is to deploy it as an INSPIRATION via grid_plug
 # (instant, and works on the hosted edition too).
 # ============================================================================
 

package/src/corpus/templates/landing-page/index.md

@@ -5,10 +5,10 @@ no `needs:`. State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "landing-page")` and fill in the user's content.

package/src/corpus/templates/membership-site/AGENTS.md

@@ -144,7 +144,7 @@ A user is a member when a `memberships` doc for their `authId` has
    `vault:` block maps from). Non-secret config (publishable auth key, price id)
    → `grid_set_env` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
    yourself — the grid injects it.
-5. `grid_deploy` to deploy. A runtime deploy is **ASYNC** — the first response
+5. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
    is `status: building`, not a live URL. Poll `grid_status` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    silent wait.
@@ -158,4 +158,4 @@ A membership site is a built + deployed runtime container, so it requires the
 **local edition** (Claude Desktop / Claude Code) or the CLI. The **hosted**
 edition (Claude Web / hosted MCP) is inline-only and can only publish static
 pages — it CANNOT build this app. On hosted, say so plainly and offer a static
-paywall-landing page (via `grid_deploy`) instead, then stop the runtime path.
+paywall-landing page (via `grid_plug`) instead, then stop the runtime path.

package/src/corpus/templates/membership-site/index.md

@@ -61,6 +61,6 @@ vault:
 ## Deploy (async, local edition)
 
 `grid_create_project` first (creates the entity + link.json), write the app under
-`services/web/`, set the vault secrets with `grid_set_secret`, `grid_deploy`
+`services/web/`, set the vault secrets with `grid_set_secret`, `grid_plug`
 (async — poll `grid_status` to a live URL), then register the `/api/webhook`
 URL in Stripe and re-plug. Re-plug the same entity to update the same URL.

package/src/corpus/templates/portfolio/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML personal / freelancer portfolio: a hero intro, an about section, a skills list, a projects grid, and a contact section.
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/portfolio/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "portfolio")` and fill in the user's content.

package/src/corpus/templates/product-launch/README.md

@@ -34,12 +34,12 @@ A one-page launch announcement with:
 ## How it deploys
 
 Deploys as an **inspiration** — instant, and works on the **hosted** edition
-(Claude Web) as well as local. Use **`grid_deploy`** with the inline `html`: you get a live share URL right away. Re-dropping the same entity
+(Claude Web) as well as local. Use **`grid_plug`** with the inline `html`: you get a live share URL right away. Re-dropping the same entity
 updates the same URL, so the user iterates on one link.
 
 The reference `cloudgrid.yaml` in this directory (`type: static`) is ONLY for
 plugging the page as an OWNED static runtime (async, local edition only); the
-fast path is `grid_deploy`.
+fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "product-launch")` and fill in the user's content.

package/src/corpus/templates/product-launch/cloudgrid.yaml

@@ -17,7 +17,7 @@
 # active fields are exactly name + services.web{type: static, path: /}; there
 # are no needs. This cloudgrid.yaml is the reference for plugging the page as an
 # OWNED static runtime; the fast path is to deploy it as an INSPIRATION via
-# grid_deploy (instant, and works on the hosted edition too).
+# grid_plug (instant, and works on the hosted edition too).
 # ============================================================================
 
 

package/src/corpus/templates/product-launch/index.md

@@ -8,10 +8,10 @@ client-side.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "product-launch")` and fill in the user's content

package/src/corpus/templates/report/cloudgrid.yaml

@@ -16,7 +16,7 @@
 # THIS TEMPLATE (report): a single self-contained static page. The active fields
 # are exactly name + services.web{type: static, path: /}; there are no needs.
 # This cloudgrid.yaml is the reference for plugging it as an OWNED static
-# runtime; the fast path is to deploy it as an INSPIRATION via grid_deploy
+# runtime; the fast path is to deploy it as an INSPIRATION via grid_plug
 # (instant, and works on the hosted edition too).
 # ============================================================================
 

package/src/corpus/templates/report/index.md

@@ -5,10 +5,10 @@ no `needs:`. State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "report")` and fill in the user's content.

package/src/corpus/templates/restaurant-reservations/AGENTS.md

@@ -180,7 +180,7 @@ build is **asynchronous**.
    auth). Non-secret config (publishable keys, feature flags) → `grid_set_env`.
 5. (Optional) `grid dev` — runs Next.js locally with `DATABASE_MONGODB_URL` and
    vault vars injected against dev Mongo. Seed `menu`, test a booking.
-6. `grid_deploy` — builds + deploys `services/web/`. **Async**: the first
+6. `grid_plug` — builds + deploys `services/web/`. **Async**: the first
    response is `status: building`, not a URL. Poll `grid_status` (or the
    returned poll URL) until live; surface a liveness signal while it builds
    (never a bare silent wait). Only then return the **live app URL** (not the

package/src/corpus/templates/saas-marketing/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML SaaS marketing site (hero, features, pricing tiers, testimonials, FAQ, and a closing call to action). Richer than the landing-page template.
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/saas-marketing/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "saas-marketing")` and fill in the user's content.

package/src/corpus/templates/status-page/README.md

@@ -3,7 +3,7 @@
 A single self-contained HTML service status page: an overall banner, a component list with up / degraded / down pills, per-component uptime bars, and an incident history log. Status is baked into the page.
 
 Static inspiration — a single self-contained `index.html` (inline CSS and JS,
-no external CDNs). It deploys instantly via `grid_deploy` and works on every
+no external CDNs). It deploys instantly via `grid_plug` and works on every
 CloudGrid edition, including hosted.
 
 ## Fill it in

package/src/corpus/templates/status-page/index.md

@@ -5,10 +5,10 @@ State (if any) lives only in memory and is lost on refresh.
 
 ## How it deploys
 
-To publish this page, use **`grid_deploy`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
+To publish this page, use **`grid_plug`** with the inline `html`: it deploys as an **inspiration** — instant, and works on the **hosted**
 edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
 directory (`type: static`) is ONLY for plugging the page as an OWNED static
-runtime (async, local edition only); the fast path is `grid_deploy`.
+runtime (async, local edition only); the fast path is `grid_plug`.
 
 The fillable HTML is the real template — fetch it with
 `grid_get_template("template", "status-page")` and fill in the user's content.