@cloudgrid-io/mcp 0.20.54 → 0.20.56

package/README.md

@@ -84,7 +84,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 <!-- gen:tools -->
 ## Tools
 
-36 tools registered (14 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
+37 tools registered (15 shared across both editions, 22 local-only). No deprecated aliases. MIN_CLI_VERSION: 0.15.26.
 
 ### Direct-API tools (both editions)
 
@@ -92,6 +92,7 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 |---|---|---|
 | `grid_pickup` | API | 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. |
 | `grid_pull` | API | Pull an app to continue/edit it IN PLACE — like `git clone` of the SAME entity: your next grid_plug (with its target_... |
+| `grid_collab` | API | Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, no... |
 | `grid_create_grid` | API | Create a new grid (workspace) for the signed-in user — they become its admin. |
 | `grid_note` | API | Optionally leave a one-paragraph summary of what you built this session and why. |
 | `grid_plug` | API | Plug an app, website, game, or single HTML page into CloudGrid — the live runtime that runs it and provides its infra... |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.54",
+  "version": "0.20.56",
   "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,9 @@
     "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",
+    "test:collab": "node test/collab.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. If the user wants their OWN copy, offer to fork it into their grid with grid_pickup and edit the copy. If the user wants to COLLABORATE on the SAME entity, use grid_collab. 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); grid_collab = GET push access to that same entity (grants permission only and fetches nothing — run grid_pull afterwards to get the code, and if the owner gates access grid_collab sends them a request to approve). So if the user asks to "collab", do NOT call grid_pickup; call 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 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 grid_collab (the CLI equivalent is \`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 grid_collab (CLI equivalent: \`grid collab ${slug}\`) — it grants permission only and fetches nothing, so pull again once granted.`;
     canEdit = false;
   }
   const lines = [head];
@@ -774,6 +780,161 @@ export async function runPull(ctx, { claim_token, claim_url, entity_id }) {
 }
 
 
+// grid_collab — GET PUSH ACCESS to the SAME live entity you do NOT own (issue
+// #253). This is the third adopt/access verb, distinct from the other two:
+//   grid_pickup = make your OWN COPY (a fork: new entity, forked_from lineage)
+//   grid_pull   = continue an entity you ALREADY have access to (fetch the code)
+//   grid_collab = grant yourself push access to someone else's SAME entity
+//                 (permission only — fetches nothing; run grid_pull afterwards)
+//
+// Mirrors the CLI reference (packages/cli/src/commands/collab.ts). It records the
+// grant server-side via the CANONICAL join path POST /api/v2/entities/:id/collab
+// — the SAME entity, NOT a fork. The fork route is POST /runtimes/:id/remix
+// (runPickup); collab never touches it, so a collab can never silently become a
+// pickup (the #242 defect). On a POLICY denial (NOT_ALLOWLISTED / PICKUP_DISABLED
+// — the owner gated who may join) it does NOT dead-end on the 403: it turns the
+// denial into a REQUEST the owner approves, via POST /:id/collab-requests, exactly
+// as the CLI does (collab.ts:129). Other 403s (NOT_A_GRID_MEMBER / FORBIDDEN_ROLE)
+// are grid-boundary problems, not policy denials, so they are surfaced, never
+// converted to a request. Pure authenticated API calls, no CLI or filesystem —
+// so, like grid_pickup / grid_pull, it ships on BOTH editions.
+export async function runCollab(ctx, { entity_id, grid } = {}) {
+  const token = await ctx.getToken();
+  if (!token) {
+    throw new Error("You are not signed in. Run grid_login first, then collab.");
+  }
+  const target = entity_id;
+  if (!target) {
+    throw new Error("`entity_id` is required (a canonical UUID or <grid-slug>/<entity-slug>).");
+  }
+
+  const orgSlug = grid || (await ctx.getActiveGrid());
+  const headers = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+  if (orgSlug) {
+    // Grid-native header + X-CloudGrid-Org alias (same slug) during the soak, so
+    // a bare-slug target resolves in the intended grid (mirrors runPull).
+    headers["X-CloudGrid-Grid"] = orgSlug;
+    headers["X-CloudGrid-Org"] = orgSlug;
+  }
+
+  const collabUrl = `${API_BASE}/api/v2/entities/${encodeURIComponent(target)}/collab`;
+  let res;
+  try {
+    res = await fetch(collabUrl, { method: "POST", headers, body: JSON.stringify({}) });
+  } 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 || null;
+    // ── Policy denial → REQUEST ACCESS (the whole point of the tool). Scoped to
+    // the two policy codes ONLY: a grid-boundary 403 (NOT_A_GRID_MEMBER /
+    // FORBIDDEN_ROLE) is a different problem and must NOT spam the owner. ──────
+    if (res.status === 403 && (code === "NOT_ALLOWLISTED" || code === "PICKUP_DISABLED")) {
+      return await requestCollabAccess(ctx, target, headers);
+    }
+    if (res.status === 404 || code === "RUNTIME_NOT_FOUND" || code === "NOT_FOUND" || (typeof code === "string" && code.endsWith("_NOT_FOUND"))) {
+      throw new Error(`No entity matched '${target}'. Check the id or grid/slug (a canonical UUID or <grid-slug>/<entity-slug>).`);
+    }
+    if (res.status === 403 && code === "NOT_A_GRID_MEMBER") {
+      throw new Error(data?.error?.message || `You're not a member of the grid that owns '${target}'. Ask its owner to invite you to the grid first, then collab.`);
+    }
+    if (res.status === 403 && code === "FORBIDDEN_ROLE") {
+      throw new Error(data?.error?.message || `Collaborating on '${target}' needs builder or admin role in its grid.`);
+    }
+    if (res.status === 400 && code === "NOT_A_RUNTIME") {
+      throw new Error(data?.error?.message || `'${target}' is an Inspiration, not an app or agent — it has no collaborators. Fork it with grid_pickup instead.`);
+    }
+    const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+    throw new Error(`Collab failed (HTTP ${res.status}): ${msg}`);
+  }
+
+  // ── Grant recorded on the SAME entity (permission only — no code fetched) ────
+  // Interpret the unified §4 pickup contract, exactly as runPull does, but frame
+  // it as an access grant and point at grid_pull for the code (founder split
+  // 2026-07-23: collab = permission, pull = code).
+  const slug = data?.slug || target;
+  const where = data?.grid ? ` in ${data.grid}` : "";
+  const ownerIsYou = data?.owner?.is_you === true;
+  const canReplug = data?.capabilities?.replug === true;
+  let head, canEdit;
+  if (ownerIsYou) {
+    head = `${slug}${where} is yours — nothing to grant. Use grid_pull to get the code, then grid_plug (target_entity_id) to update it.`;
+    canEdit = true;
+  } else if (canReplug) {
+    head = `You're now a collaborator on ${slug}${where} — you have PUSH ACCESS to the SAME entity (not a copy). This granted permission only; use grid_pull to get the code, then 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 the grant did not give you push access. Make your own separate copy (a fork) with grid_pickup instead.`;
+    canEdit = false;
+  }
+  const lines = [head];
+  if (data?.url) lines.push(`URL: ${data.url}`);
+  return {
+    text: lines.join("\n"),
+    structured: {
+      ...(data?.entity_id ? { entity_id: data.entity_id } : {}),
+      ...(slug ? { slug } : {}),
+      grid: data?.grid ?? null,
+      ...(data?.url ? { url: data.url } : {}),
+      owner_is_you: ownerIsYou,
+      can_edit: canEdit,
+      access_requested: false,
+      request_pending: false,
+    },
+  };
+}
+
+// Turn a policy 403 into a request: POST /:id/collab-requests and tell the user
+// what happens next (mirrors CLI collab-requests.ts requestCollabAccess). A
+// request IS a success outcome, so this returns a normal result, never throws for
+// the expected 409s (a pending ask, or an access race the owner just opened).
+async function requestCollabAccess(ctx, target, headers) {
+  const url = `${API_BASE}/api/v2/entities/${encodeURIComponent(target)}/collab-requests`;
+  let res;
+  try {
+    res = await fetch(url, { method: "POST", headers, body: JSON.stringify({}) });
+  } 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 */ }
+  const code = data?.error?.code || null;
+
+  if (res.ok) {
+    return {
+      text:
+        `The owner gates who can collaborate on '${target}', so I asked them for push access on your behalf. ` +
+        `They've been notified — once they approve, run grid_collab again to join, then grid_pull to get the code.`,
+      structured: { access_requested: true, request_pending: true, owner_is_you: false, can_edit: false },
+    };
+  }
+  if (res.status === 409 && code === "COLLAB_REQUEST_EXISTS") {
+    return {
+      text: `You already asked for access to '${target}'. The owner hasn't decided yet — you'll be able to join once they approve.`,
+      structured: { access_requested: true, request_pending: true, owner_is_you: false, can_edit: false },
+    };
+  }
+  if (res.status === 409 && code === "COLLAB_ALREADY_ALLOWED") {
+    // Race: the owner opened access between the join 403 and this request.
+    return {
+      text: `You already have access to '${target}'. Run grid_collab again to join, then grid_pull to get the code.`,
+      structured: { access_requested: false, request_pending: false, owner_is_you: false, can_edit: false },
+    };
+  }
+  const msg = data?.error?.message || data?.message || raw || `HTTP ${res.status}`;
+  throw new Error(`Couldn't request access to '${target}' (HTTP ${res.status}): ${msg}`);
+}
+
+
 // ── grid_plug — the unified create/re-plug verb (spec v2 §3) ──────────────
 
 // Total upload budget mirrors the server's multipart cap (100 MB).

package/src/tools/register.js

@@ -21,6 +21,7 @@ import {
   detectSourceManifest,
   runReport,
   runPull,
+  runCollab,
   runPlug,
   runPickup,
   runCreateGrid,
@@ -132,7 +133,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 grid_collab tool (or the CLI `grid collab <entity>`) — so do NOT reach for grid_pickup when the user asks to collab; reach for grid_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 +173,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 grid_collab (or the CLI `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)."),
@@ -197,6 +198,42 @@ export function registerTools(server, ctx) {
     },
   );
 
+  // grid_collab — GET PUSH ACCESS to the SAME live entity you do NOT own (#253).
+  // The THIRD adopt/access verb, distinct from grid_pickup (fork) and grid_pull
+  // (continue). Pure API (POST /entities/:id/collab; a policy 403 → a request via
+  // POST /:id/collab-requests), no CLI or filesystem — so it ships on BOTH
+  // editions, exactly like grid_pickup/grid_pull. Registered BEFORE the
+  // edition!=="local" gate for that reason.
+  reg(
+    "grid_collab",
+    {
+      title: "Get push access to an app you don't own",
+      description: "Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy. This grants PERMISSION ONLY and fetches nothing: after it succeeds, run grid_pull to get the code, then grid_plug (with its target_entity_id) updates the SHARED entity in place (the team sees the new version and can roll it back). This is NOT a fork — it never mints a new entity and never carries forked_from lineage; if you want your OWN separate copy instead, that is grid_pickup. If the owner GATES who may join, this does NOT dead-end: it sends the owner a request for access on your behalf, and once they approve you run grid_collab again to join. Use this — not grid_pickup — whenever the user asks to \"collab\" on, \"join\", or \"get push/write access to\" an app they don't own. Requires sign-in. Calls the API directly (both editions).",
+      inputSchema: {
+        entity_id: z.string().describe("The app to get push access to: a canonical UUID or <grid-slug>/<entity-slug>."),
+        grid: z.string().optional().describe("Grid to resolve a bare slug in. Required only when a bare slug is ambiguous across grids you belong to."),
+      },
+      outputSchema: {
+        entity_id: z.string().optional().describe("The SAME entity you now collaborate on — pass it to grid_pull, then to grid_plug as target_entity_id. Never a new/forked entity."),
+        slug: z.string().optional().describe("Its slug."),
+        grid: z.string().nullable().optional().describe("Its grid."),
+        url: z.string().optional().describe("Its public URL."),
+        owner_is_you: z.boolean().optional().describe("True if you already own it (nothing to grant)."),
+        can_edit: z.boolean().optional().describe("True once you have push access (owner or collaborator). False = still view-only."),
+        access_requested: z.boolean().optional().describe("True when the owner gates access and a request was sent on your behalf."),
+        request_pending: z.boolean().optional().describe("True when a request is awaiting the owner's decision — join with grid_collab again once approved."),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        return okResult(await runCollab(ctx, input || {}));
+      } catch (err) {
+        return fail(err.message);
+      }
+    },
+  );
+
   // grid_create_grid — create a grid for the signed-in user (POST /api/v2/grids,
   // the same call as the CLI `grid create grid <slug>`). Exists so a first-time
   // user with NO grid is never sent to the console: grid_plug returns
@@ -1206,11 +1243,12 @@ 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 grid_collab to GET push access
+  // to the same entity (grants permission only — pull again once granted).
   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 — grid_collab (CLI equivalent: `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."),

package/src/tools.js

@@ -35,6 +35,7 @@ export {
   runPlug,
   runPickup,
   runPull,
+  runCollab,
   runCreateGrid,
   scanInlineSecrets,
   secretBlockMessage,