@cloudgrid-io/mcp 0.20.54 → 0.20.55

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.54",
+  "version": "0.20.55",
   "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": {
@@ -58,7 +58,8 @@
     "test:proxy": "node test/proxy.test.mjs",
     "test:system-ca": "node test/system-ca.test.mjs",
     "test:tool-titles-and-vocab": "node test/tool-titles-and-vocab.test.mjs",
-    "test:visibility-mapping": "node test/visibility-mapping.test.mjs"
+    "test:visibility-mapping": "node test/visibility-mapping.test.mjs",
+    "test:verb-distinction": "node test/verb-distinction.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",

package/src/corpus/playbook.md

@@ -39,7 +39,7 @@ Operating rules:
 15. Editing an existing thing from just its URL (a fresh chat, no prior context — e.g. "change the background to green here <url>"): call grid_get_app_source(url) first. It resolves the entity_id and returns the current HTML plus its kind, single_html, capabilities, and replug_handle — read those to pick the branch:
   - Single-HTML inspiration you can re-plug (single_html: true and capabilities.replug: true): edit the returned HTML and call grid_plug with target_entity_id (or grid+slug — the replug_handle) to update the SAME URL in place. This works on every edition, including hosted.
   - Multi-file app or agent (kind is app or agent, or single_html: false): do NOT try to edit it as one inline HTML file. Tell the user it is a multi-file <kind>, give them the entity_id and the source (source_download_url), and explain that rebuilding it needs the local edition (Claude Desktop/Code) or the CLI — the hosted server cannot rebuild a multi-file app.
-  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_pickup and edit the copy instead.
+  - Not yours (capabilities.replug: false, reason not_owner): do NOT attempt a re-plug. Offer to fork it into the user's own grid with grid_pickup and edit the copy instead. Three distinct verbs, do not conflate them: grid_pickup = make your OWN COPY (a fork, a NEW entity); grid_pull = continue the SAME entity in place (needs push access — you own it or are a collaborator); and "collab" = GET push access to that same entity, which is the CLI `grid collab <entity>` (grants permission only and fetches nothing — pull afterwards to get the code). Getting collaborator access has no MCP tool — it is CLI-only — so if the user asks to "collab", do NOT call grid_pickup; explain that granting access is the CLI `grid collab`, distinct from pickup's fork.
 16. Help CloudGrid QA. When you plug, 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 plug posts the QA log on that same call, so do NOT call grid_note after plugging — session_note is the narrative path. Use grid_note only BEFORE a plug, or in a session that ends without one. Everything here is recorded for quality review and never changes the plug.
 17. Auth check before an owned plug, with a guest fallback — ALWAYS ask first. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or the plug returns a create-time 401), do NOT silently fail, do NOT invent an auth flow, and NEVER pass anon: true on your own — ask them plainly: "Sign in and plug it to your grid, or plug it as a guest right now (live immediately at a guest link that expires in 7 days unless claimed)?" Only if they choose guest, re-call grid_plug with anon: true and surface the claim_url + owner_token. grid_plug enforces this server-side: the first unauthenticated create in a session returns needs_auth (the ask) even when anon: true was passed — relay it to the user and stop; do not answer it yourself. This is distinct from rule 7: rule 7 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 guest is a legitimate choice the USER makes.
 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`.

package/src/corpus/templates/_cloudgrid.yaml.reference

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-admin
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/ai-app/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-chatbot
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/ai-knowledge-base/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-knowledge-base
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: analytics-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-api-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/api-docs/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: api-docs
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/api-service/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-api
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/app-with-data/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/appointment-booking/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: appointment-booking
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/approval-workflow/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: approval-workflow
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: billing-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/blog-cms/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: blog-cms
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/booking-system/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: booking-system
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/calendar-scheduler/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-calendar
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: changelog
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -24,7 +24,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: company-website
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/course-platform/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: course-platform
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-crm
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: deck
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-directory
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/docs-site/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: docs-site
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-erp
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/event-board/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: event-board
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/expense-tracker/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: expense-tracker
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/feature-request-board/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: feature-request-board
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: financial-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: forum
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/hr-portal/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: hr-portal
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/internal-tools-portal/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: internal-tools-portal
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-inventory
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-invoices
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/job-board/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-jobs
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-board
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: landing-page
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: lms
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-marketplace
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/membership-site/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: membership-site
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: monitoring-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/multi-service/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/online-store/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: online-store
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: portfolio
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: product-catalog
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: product-launch
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/project-management/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-project-board
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/property-listings/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: property-listings
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/quiz-platform/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: quiz-platform
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: report
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/restaurant-reservations/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: restaurant-reservations
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: revenue-dashboard
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/saas-marketing/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: saas-marketing
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/semantic-search/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: semantic-search
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/simple-semantic-search/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: simple-semantic-search
 description: Semantic search over a bundled document, backed by pgvector.
 icon: "🔎"

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: status-page
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/subscription-management/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: subscription-management
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/task-manager/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-tasks
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/ticket-system/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: my-tickets
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/time-tracking/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: time-tracking
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/travel-booking/cloudgrid.yaml

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: travel-booking
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

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

@@ -19,7 +19,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: waitlist
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/corpus/templates/web-app/cloudgrid.yaml

@@ -25,7 +25,7 @@
 
 # Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
 # Must start and end with a letter or digit.
-# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
+# Becomes part of your public URL: <name>-<4hex>--<org>.cloudgrid.io
 name: web-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.

package/src/tools/deploy.js

@@ -334,13 +334,17 @@ const GUEST_ORG_SLUG = "guest";
 // path (create + edit, anon + authed) — flat-arch-aware per grid, matching the
 // host that actually serves. ALWAYS prefer `data.url` (see resolvePlugUrl);
 // this client-side derivation exists only for the rare response where `url`
-// came back empty (the server composes it best-effort). It mirrors the legacy
-// `entityUrl()` rules and is WRONG on flat-arch grids (which serve
-// `<slug>--<grid>.cloudgrid.io`), so it must never be the primary source:
+// came back empty (the server composes it best-effort). It mirrors the canonical
+// `entityUrl()` rules (the flat-only platform host), but only the server knows
+// the per-entity nuances (custom domains, guest-org placement), so it must never
+// be the primary source:
 //   - inspiration (HTML drops): path-based at the org apex
 //       https://<grid>.cloudgrid.io/<slug>
-//   - runtime (app/agent):      subdomain
-//       https://<slug>.<grid>.cloudgrid.io
+//   - runtime (app/agent):      flat platform host
+//       https://<slug>--<grid>.cloudgrid.io
+// The old nested `<slug>.<grid>.cloudgrid.io` host is retired — it falls outside
+// the single `*.cloudgrid.io` platform wildcard, so it has no cert and no ingress
+// (matches `composeFlatEntityHost`).
 // Anonymous drops are grid-less in the response (`grid: null`); they live under
 // the Guest Org, so the apex slug is the constant `guest`.
 function composePlugUrl(data) {
@@ -349,7 +353,7 @@ function composePlugUrl(data) {
   const grid = data?.grid || GUEST_ORG_SLUG;
   const kind = data?.detection?.kind;
   if (kind === "app" || kind === "agent") {
-    return `https://${slug}.${grid}.cloudgrid.io`;
+    return `https://${slug}--${grid}.cloudgrid.io`;
   }
   // inspiration (and any unknown/static kind) — path-based at the org apex.
   return `https://${grid}.cloudgrid.io/${slug}`;
@@ -630,8 +634,9 @@ export async function runReport(
 // grid_pull — continue/edit an existing entity IN PLACE (POST /entities/:id/pickup).
 // Like `git clone` of the SAME entity: your next grid_plug (target_entity_id)
 // updates it. Needs push access — you must OWN it or be a COLLABORATOR. A
-// view-only caller is told they can't edit/plug it (make a copy with grid_pickup,
-// or request collaborator access with the CLI `grid collab`). A claim_token also
+// view-only caller is told they can't edit/plug it (fork a copy with grid_pickup,
+// or GET collaborator push access with the CLI `grid collab` — grants permission
+// only, pull again once granted). A claim_token also
 // claims an anonymous drop into your account (ownership transfer).
 export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
   const token = await ctx.getToken();
@@ -724,8 +729,9 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
       return {
         text:
           `You don't have push access to this entity, so you can't edit or plug it. Two options: ` +
-          `make your own separate copy with grid_pickup, or ask the owner for collaborator access with the CLI ` +
-          `\`grid collab <entity>\` (rolling out soon) and pull again once granted.`,
+          `make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME ` +
+          `entity with the CLI \`grid collab <entity>\` — that grants permission only and fetches nothing, so ` +
+          `pull again once it is granted (if the owner gates access, \`grid collab\` becomes a request they approve).`,
         structured: { can_edit: false, owner_is_you: false, access: "view_only" },
       };
     }
@@ -752,7 +758,7 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
     head = `You have collaborator push access to ${slug}${where} — your next grid_plug (target_entity_id) updates the SHARED entity; the team sees the new version and can roll it back.`;
     canEdit = true;
   } else {
-    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own copy with grid_pickup, or request collaborator access with the CLI \`grid collab ${slug}\` (rolling out soon), then pull again.`;
+    head = `You can view ${slug}${where} but do NOT have push access — you can't edit or plug it. Make your own separate copy (a fork) with grid_pickup, or GET collaborator push access to the SAME entity with the CLI \`grid collab ${slug}\` (it grants permission only and fetches nothing — pull again once granted).`;
     canEdit = false;
   }
   const lines = [head];

package/src/tools/register.js

@@ -132,7 +132,7 @@ export function registerTools(server, ctx) {
     "grid_pickup",
     {
       title: "Copy an app into your grid",
-      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
+      description: "Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. This is a FORK, not a \"collab\": it never grants you access to anyone else's live entity. Getting PUSH ACCESS to the SAME entity is a different operation — the CLI command `grid collab <entity>` — so do NOT reach for grid_pickup when the user asks to collab. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.",
       inputSchema: {
         entity_id: z.string().describe("The source app to copy: a canonical UUID or <grid-slug>/<entity-slug>."),
         grid: z.string().optional().describe("Grid to create your copy in. Required only when you belong to more than one grid."),
@@ -172,7 +172,7 @@ export function registerTools(server, ctx) {
     "grid_pull",
     {
       title: "Pull an app to edit in place",
-      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so and tell the user they can make their own copy with grid_pickup, or request collaborator access with the CLI `grid collab <entity>` (rolling out soon). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
+      description: "Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so, and offer the two real options: (1) make your own separate copy (a fork) with grid_pickup, or (2) GET push access to the SAME entity with the CLI command `grid collab <entity>` — \"collab\" is a distinct access-control operation that grants permission only and fetches nothing, so once it is granted you run grid_pull again to get the code (and if the owner gates access, `grid collab` becomes a request they approve). Passing an anonymous drop's `claim_token` claims it into your account. Requires sign-in. Calls the API directly (both editions).",
       inputSchema: {
         entity_id: z.string().optional().describe("The entity id to pull. Defaults to this session's last anonymous drop."),
         claim_token: z.string().optional().describe("Anonymous drop only: its owner token — claims that drop into your account (ownership transfer)."),
@@ -1206,11 +1206,13 @@ export function registerTools(server, ctx) {
   // source + cloudgrid.yaml and links the folder, so the next `grid plug` updates
   // the SAME entity in place. Wraps `grid pull` (NOT `grid pickup` — pickup now
   // makes a separate copy). Push access required; a view-only entity can't be
-  // pulled — use grid_pickup to copy it, or `grid collab` to request access.
+  // pulled — use grid_pickup to fork a copy, or the CLI `grid collab` to GET
+  // push access to the same entity (grants permission only — pull again once
+  // granted). `grid collab` is CLI-only; there is no grid_collab MCP tool.
   regTool(
     "grid_edit_existing_app",
     "Pull app source to edit locally",
-    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy instead, use grid_pickup.",
+    "Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next `grid plug` updates it IN PLACE. Requires push access (owner or collaborator). Wraps `grid pull`. To make your own separate copy (a fork) instead, use grid_pickup. To GET push access to an entity you can currently only view, that is a different operation — the CLI `grid collab <entity>`, which grants permission only; run the pull again once it is granted.",
     {
       name: z.string().describe("Entity slug or id to pull."),
       target_dir: z.string().optional().describe("Directory to pull into (relative to cwd). Defaults to the entity name."),