@cloudgrid-io/mcp 0.21.18 → 0.21.20

package/README.md

@@ -10,7 +10,7 @@ It ships in two editions from one codebase:
   wrappers) for web clients like claude.ai. See [REMOTE.md](REMOTE.md).
 
 The local edition wraps the `grid` CLI for authenticated operations (the CLI
-handles auth, org context, and error formatting) and calls the API directly for the
+handles auth, grid context, and error formatting) and calls the API directly for the
 plug, login, and visibility tools.
 
 ## CLI compatibility
@@ -231,7 +231,7 @@ block) and structured result data bypass the text scrubber.
 
 **No other data collection by this server.** The server does not track usage
 analytics or transmit data beyond the flows listed above and the authenticated
-CloudGrid API calls the individual tools make (e.g. `/orgs`, `/grids`,
+CloudGrid API calls the individual tools make (e.g. `/grids`,
 `/pickup`, `/deploys`, `/inspirations/{id}/source`). CLI-wrapping tools shell
 out to the CloudGrid `grid` CLI, which shares the same
 `~/.cloudgrid/credentials` file and does not send additional telemetry through

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.21.18",
+  "version": "0.21.20",
   "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": {
@@ -31,6 +31,8 @@
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
     "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:create-gates": "node test/create-gates.test.mjs",
+    "test:login-required-create": "node test/login-required-create.test.mjs",
+    "test:no-guest-publish-copy": "node test/no-guest-publish-copy.test.mjs",
     "test:plug-create-grid-choice": "node test/plug-create-grid-choice.test.mjs",
     "test:hello": "node test/hello.test.mjs",
     "test:grid-provisioning": "node test/grid-provisioning.test.mjs",
@@ -86,10 +88,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "express": "^4.22.2",
     "fflate": "^0.8.3",
-    "undici": "^8.10.0",
+    "undici": "^8.11.2",
     "zod": "^3.23.0"
   },
   "devDependencies": {
@@ -100,5 +102,11 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudgrid-io/mcp.git"
+  },
+  "//overrides-qs": "qs is held at 6.15.x by express and body-parser, which both declare ~6.15.1: a tilde range that excludes 6.16.0, so no lockfile refresh reaches the patched version. cloudgrid runs this same override in packages/api and functions/event-consumer through the identical pins. REMOVE once express/body-parser declare a range admitting >= 6.16.0: npm view body-parser dependencies.qs . See cloudgrid-io/cloudgrid#4346.",
+  "overrides": {
+    "proxy-addr": "^2.0.8",
+    "fast-uri": "^3.1.8",
+    "qs": "^6.16.0"
   }
 }

package/src/corpus/cli-reference.md

@@ -50,7 +50,7 @@ Verify: `grid --version` and `grid doctor`.
 
 ```
 grid login          # Google OAuth in the browser
-grid whoami         # confirm user + active org
+grid whoami         # confirm user + active grid
 grid plug           # build + deploy the current directory, prints the live URL
 grid open           # open it in the browser
 ```
@@ -72,7 +72,7 @@ grid logs --since 10m
 grid visibility set my-api link
 grid feedback
 
-# Switch org, list what's on the grid
+# Switch grid, list what's on the grid
 grid use atomic
 grid grid
 ```
@@ -81,19 +81,19 @@ grid grid
 
 | Command | Purpose |
 |---|---|
-| `login` / `logout` / `whoami` | Sign in (Google OAuth), sign out, show user + active org |
-| `use [slug]` | Set or show the active org |
+| `login` / `logout` / `whoami` | Sign in (Google OAuth), sign out, show user + active grid |
+| `use [slug]` | Set or show the active grid |
 | `new <name>` | Scaffold a new app or agent project (`--type`, `--needs`, `--agent`, `--dir`); the entity is created on first `plug` |
 | `plug [target]` | Build + deploy (or redeploy); first plug auto-creates the entity from `cloudgrid.yaml`; prints the live URL |
 | `dev` | Run the linked entity locally with grid-injected resources |
-| `status [name]` | Org dashboard, entity detail, or a deploy snapshot |
+| `status [name]` | Grid dashboard, entity detail, or a deploy snapshot |
 | `logs [name]` | Stream entity logs |
 | `open [name]` | Open the entity URL in the browser |
 | `info [name]` / `builds [name]` | Entity metadata; recent deploys |
 | `visibility set <slug> <mode>` | private \| grid \| link — or the axes: `--inside <private\|spaces\|grid> --outside <none\|link\|public>` (+ `--require-signin`, `--space <slug>`) |
 | `rollback` / `versions` | Roll back to a prior deploy; list/tag minted versions |
 | `env` / `secrets` | Manage runtime env vars and secrets (secret values are never printed) |
-| `grid` / `list` | List what's on your hub / org |
+| `grid` / `list` | List what's on your hub / grid |
 | `rename` / `delete` / `unplug` | Rename, archive, take off the grid |
 | `collab` / `pull` / `pickup` | Grant push access (`collab`), continue in place (`pull`), or fork a copy (`pickup`) |
 | `feedback [message]` | Send feedback to the CloudGrid team |
@@ -111,7 +111,7 @@ Global:
 - `-h, --help` — help for any command
 
 Common per-command:
-- `--org <slug>` — pick/override the org
+- `--grid <slug>` — pick/override the grid
 - `--json` — machine-readable output (where supported)
 - `--no-clipboard` / `--no-notify` — suppress clipboard copy / OS notification on `plug`
 - `--since <dur>` / `--tail <n>` — `logs` window
@@ -135,7 +135,7 @@ rm -rf ~/.cloudgrid                  # remove stored credentials + config
 ## Troubleshooting
 
 - **`grid: command not found`** — ensure the npm global bin (or Homebrew bin) is on `$PATH`; re-run the installer.
-- **Auth errors / 401** — `grid login` again; check `grid whoami` shows the expected org, switch with `grid use <org>`.
+- **Auth errors / 401** — `grid login` again; check `grid whoami` shows the expected grid, switch with `grid use <grid>`.
 - **Deploy fails** — run `grid doctor`; check `grid logs` and `grid status <name>` for the trace.
 
 ## Support

package/src/corpus/cloudgrid-yaml.md

@@ -148,7 +148,7 @@ scale: auto                         # 'auto' (default), 'alert', or integer 1-10
 
 # ─── Infrastructure needs (v2, CANONICAL — the deployer injects from these) ─
 needs:
-  database: true                    # Mongo (org-tier). Injects DATABASE_MONGODB_URL.
+  database: true                    # Mongo (grid-tier). Injects DATABASE_MONGODB_URL.
   cache: true                       # Redis with LRU eviction. Injects CACHE_REDIS_URL.
   kv: true                          # Redis, no eviction. Injects KV_REDIS_URL.
   queue: true                       # Redis for BullMQ etc. Injects QUEUE_REDIS_URL.
@@ -160,12 +160,12 @@ needs:
 
 # ─── Inter-entity communication ────────────────────────────────────
 calls:                              # Entities this app calls (outbound grants).
-  - org:atomic/billing-api
-  - org:atomic/content-service
+  - atomic/billing-api              # <grid-slug>/<app-slug>, a bare slug, or an entity id.
+  - atomic/content-service
 
 callers:                            # Inbound caller policy.
   policy: auto                      # 'auto' or 'manual' (default: 'manual').
-  scope: org                        # 'org', 'space', or 'explicit' (default: 'org').
+  scope: org                        # 'org' (the whole grid), 'space', or 'explicit' (default: 'org').
   fallback: deny                    # 'deny' or 'warn' (default: 'deny').
 
 # ─── Vault ──────────────────────────────────────────────────────────
@@ -176,7 +176,7 @@ vault:                              # Map of ENV_VAR: vault_item_key. Optional.
 # ─── Connectors and hooks ──────────────────────────────────────────
 connectors:
   - id: team-slack
-    target: org                     # 'system' or 'org'
+    target: org                     # 'system' or 'org' (your grid)
     channel: "#deploys"
 
 hooks:                              # Outbound events. on ∈ release.published |

package/src/corpus/cookbook.md

@@ -105,6 +105,6 @@ the drop's expiry. Editing an archived or expired drop returns 409
 
 ## Notes
 
-- Every command uses the active org and linked entity when you omit the name. Run
+- Every command uses the active grid and linked entity when you omit the name. Run
   `grid whoami` to see the active context.
 - These skills wrap the CLI. Anything the CLI can do, a skill can drive.

package/src/corpus/playbook.md

@@ -28,8 +28,8 @@ Operating rules:
 
    On a re-plug/edit of an existing entity, leave its current visibility as-is unless the user asks to change it.
 6. Brainstorm first (lightly) for a real app, then minimize questions. For a substantial runtime app, take ONE lightweight beat before generating/plugging: confirm the goal + 3-5 core features in a sentence, check for a matching template/recipe (capability-map), and infer the data/runtime needs and STATE them ("I'll add a database so entries are saved"). Keep it to a line or two; never ask a non-technical user infra questions they can't answer. A simple single page skips this and builds immediately. Otherwise use sensible defaults and build; don't front-load setup questions.
-7. If a signed-in publish fails with a server error, do not fall back to anonymous publishing (it burns the anonymous quota and downgrades ownership); surface the error, use the CLI fallback if offered, or ask the user.
-8. When signed in and the user has more than one grid, do not assume a target. For a NEW app, establish the grid UP FRONT — grid_start returns the grids; if there is more than one, ask "which grid should this go on?" before you start building, and carry that slug into grid_plug. As a backstop, grid_plug hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of plugging; a create with no auth and no anon returns needs_auth (sign-in vs anonymous) instead of silently publishing anonymously. Relay either ask to the user; never pick silently.
+7. If a signed-in publish fails with a server error, surface the error, use the CLI fallback if offered, or ask the user. There is no anonymous fallback — a create without sign-in publishes nothing.
+8. When signed in, establish the grid UP FRONT for a NEW app — grid_start returns the grids. If there are NONE, do rule 3b before you start building: suggest a slug, confirm it, call grid_create_grid, and carry that slug into grid_plug (no wait needed — grid_plug holds until the grid is ready). If there is more than one, do not assume a target: ask "which grid should this go on?" before you start building, and carry that slug into grid_plug. As a backstop, grid_plug hard-gates this: an authed create with >1 grid and no chosen grid returns needs_grid (the picker) instead of plugging; a create with no auth returns needs_auth (sign in with grid_login) and publishes nothing. Relay either ask to the user; never pick silently.
 9. When a build/plug fails unexpectedly, offer to report it to the CloudGrid team — only with the user's explicit consent (ask first). Send just the error + the failed request by default (call grid_report), and never send the whole conversation unless the user agrees (include_conversation). Respect privacy.
 10. To modify an existing page when you don't already have its HTML in context, first call grid_get_app_source to fetch the current HTML, apply your change, then call grid_plug with target_entity_id (the entity_id) to update the SAME URL in place. Do not ask the user to paste the HTML back.
 11. Publishing a single HTML page: pass it inline as grid_plug's html parameter (a full self-contained document). For a heavy or image-heavy page in the local edition, pass the path parameter instead so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a page looks empty, use grid_get_app_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
@@ -41,7 +41,7 @@ Operating rules:
   - 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. 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.
+17. Sign in before a new plug — there is no guest option. grid_start reports signed_in. If the user wants to publish and is NOT signed in (or a create returns needs_auth or a 401), do NOT silently fail and do NOT invent an auth flow: tell them plainly that publishing needs a CloudGrid account so the page belongs to them, call grid_login, and once they finish, re-call grid_plug. Do NOT offer a guest or sign-in-free publish — a signed-out create returns needs_auth and publishes nothing, even with anon: true, so never pass anon: true. Two paths still work for an anonymous drop made earlier: re-plug it in place with target_entity_id plus its owner_token (no sign-in needed), or, once signed in, claim it into their grid with grid_pull and its claim_token.
 18. Using the CLI (runtime apps, `grid dev`, or any shell step): the verb is `grid`, but ALWAYS invoke it as `npx -y @cloudgrid-io/cli@latest <command>` — never a bare `grid` or `cloudgrid`. A `grid` already on the machine is usually a stale global that the API rejects on its version floor, so a bare command fails with a version error and wastes turns; `npx …@latest` needs no install and is always current. In a local edition, prefer the MCP `grid_*` tools — they resolve a current CLI for you — and drop to `npx …@latest` only for shell-only steps like `grid dev`.
 19. Plugging a runtime app (multi-file, or anything with `needs:`) from a terminal-capable edition (Claude Code, Cursor, or a plain terminal): make the CLI ready BEFORE you plug, in ONE pass — do NOT run the plug first and then react to "command not found" / version errors. Sequence: `npx -y @cloudgrid-io/cli@latest whoami` (if not signed in, `npx -y @cloudgrid-io/cli@latest login` and wait for the user), optionally `npx -y @cloudgrid-io/cli@latest dev` to test locally (the AI gateway and `needs:` resources are tunnelled into dev), then `npx -y @cloudgrid-io/cli@latest plug --grid <slug>`. When you hand a hosted/web user the steps to finish a runtime build locally, give them these same `npx …@latest` commands (never a bare `cloudgrid`/`grid`) alongside their downloaded folder or .zip. If you CANNOT run shell commands yourself (a hosted edition, or a client with no terminal), do not skip local testing silently and never imply you tested it — tell the user plainly: "You can test this locally first by running `npx -y @cloudgrid-io/cli@latest dev` in your terminal." Then plug when they are ready. There is no MCP tool that runs `grid dev`: it is a long-running server you stop with Ctrl-C, so it only works in a real terminal.
 

package/src/corpus/skill-brain.md

@@ -39,7 +39,7 @@ when the user wants to see the result now.
 
 Other flags:
 
-- `--org <slug>` — target an entity in another org.
+- `--grid <slug>` — target an entity in another grid.
 - `--json` — machine-readable output.
 
 ## Reading the output

package/src/corpus/skill-claim.md

@@ -44,10 +44,10 @@ URL path; the claim token goes in the body:
 
 ```
 JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
-ORG=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
+GRID=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
 # ENTITY_ID from the drop response; TOKEN from claim_url's ?token=...
 curl -sS -X POST "https://api.cloudgrid.io/api/v2/entities/$ENTITY_ID/pickup" \
-  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
+  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Grid: $GRID" \
   -H "Content-Type: application/json" \
   -d "{\"claim_token\":\"$TOKEN\"}"
 ```

package/src/corpus/skill-feedback.md

@@ -3,7 +3,7 @@ version: 0.2.0
 name: feedback
 description: |
   Read the CloudGrid feedback feed. Use when the user wants to see feedback, check
-  what people said, review reactions, or read recent feedback events for their org.
+  what people said, review reactions, or read recent feedback events for their grid.
   Wraps grid feedback list.
 argument-hint: "[--since 7d]"
 allowed-tools: Bash
@@ -11,7 +11,7 @@ allowed-tools: Bash
 
 # CloudGrid Feedback
 
-List recent feedback events for the active org. Wraps `grid feedback list`.
+List recent feedback events for the active grid. Wraps `grid feedback list`.
 
 ## Step 0 — Bootstrap
 
@@ -31,15 +31,15 @@ List recent feedback events for the active org. Wraps `grid feedback list`.
 grid feedback list
 ```
 
-The feed is scoped to the active org. It is not filtered by entity. Useful flags:
+The feed is scoped to the active grid. It is not filtered by entity. Useful flags:
 
 - `--since <duration>` — only events newer than this, for example `24h`, `7d`.
 - `--limit <n>` — number of events. Default 50, max 200.
-- `--org <slug>` — read another org's feed (where you have access).
+- `--grid <slug>` — read another grid's feed (where you have access).
 
 ## Reading the output
 
-Each event has a time, an id, an org, and a message. Group or summarize by theme
+Each event has a time, an id, a grid, and a message. Group or summarize by theme
 when there are many. Surface the ones that look like bugs or blockers first.
 
 ## Note: reading vs sending

package/src/corpus/skill-plug.md

@@ -5,7 +5,7 @@ description: |
   Deploy or share a creation on CloudGrid and get a public URL. Use when the user
   wants to ship, deploy, publish, share, send a friend a link, or go live — a
   single HTML page or a full app. One self-contained HTML page publishes instantly
-  as an inspiration (any edition, no login needed); a multi-file app deploys from a
+  as an inspiration (any edition; sign-in required); a multi-file app deploys from a
   directory or URL. Wraps grid plug.
 argument-hint: "[path-or-url]"
 allowed-tools: Bash
@@ -20,7 +20,7 @@ Deploy or share a creation and get a public URL. This is the one deploy/share ve
 
 - **ONE self-contained HTML page** (a single file — CSS+JS inline, images/fonts as
   data: URIs; the normal hosted output) → an **inspiration**: instant, works on
-  **any edition**, no login required. See "Share a single HTML page" below.
+  **any edition**; publishing needs sign-in. See "Share a single HTML page" below.
 - **Anything more** — separate files/folders, a real `assets/` dir, separate
   `.css`/`.js`, multiple pages, a SPA build — **or** any data/server/LLM/cron need
   → a **runtime app**: `grid plug` on a linked folder, **local edition only**,
@@ -28,46 +28,38 @@ Deploy or share a creation and get a public URL. This is the one deploy/share ve
 
 ## Share a single HTML page (the fast path)
 
-No account and no CLI needed — that is the point: anyone can publish a page. Write
-the page to a single self-contained HTML file (a full document starting with
-`<!doctype html>` or `<html>`; wrap a fragment in a minimal document). HTML is
-capped at 2 MB for anonymous publishes. Then POST it to the unified plug endpoint:
+No CLI needed, but publishing needs a CloudGrid account so the page belongs to the
+user. If they are not signed in, run the `cloudgrid:login` skill first — there is no
+guest or sign-in-free publish. Write the page to a single self-contained HTML file
+(a full document starting with `<!doctype html>` or `<html>`; wrap a fragment in a
+minimal document). Then POST it to the unified plug endpoint with your credentials:
 
 ```
+JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
+GRID=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
 curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
+  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Grid: $GRID" \
   -F "artifact=@/path/to/index.html;type=text/html"
 ```
 
-The response is JSON (HTTP 201 anonymous). Read these fields:
+Read these fields from the JSON response:
 
 - `url` — the live link, composed by the server. Use it verbatim; never compose a
   URL from the slug yourself.
 - `entity_id` — the durable handle for updating this page later (see re-plug below).
-- `owner_token` — a JWT proving you made this page. It authorizes an anonymous
-  re-plug and doubles as the claim token; its lifetime matches the expiry (default
-  7 days). Persist it with `entity_id` and `url`.
-- `claim_url` / `claim_message` — the link + nudge to sign in and keep it past expiry.
-
-Signed in, publish into your own grid instead (owned, no claim needed):
-
-```
-JWT=$(jq -r .jwt ~/.cloudgrid/credentials 2>/dev/null)
-ORG=$(grep -E '^\s*active_org_slug:' ~/.cloudgrid/config.yaml | awk '{print $2}')
-curl -sS -X POST https://api.cloudgrid.io/api/v2/plug \
-  -H "Authorization: Bearer $JWT" -H "X-CloudGrid-Org: $ORG" \
-  -F "artifact=@/path/to/index.html;type=text/html"
-```
 
 The MCP `grid_plug` tool does all of this for you: pass the page as its inline
-`html` param (it materializes one `index.html` and handles anon/claim/re-plug).
+`html` param (it materializes one `index.html` and handles re-plug). Signed out, it
+returns `needs_auth` and publishes nothing — call `grid_login`, then re-call it.
 
 ### Re-plug: update the same URL in place
 
 `/api/v2/plug` is a unified create-or-update endpoint. The switch is the
 `target_entity_id` form field: absent → create (new URL); present → update the
-SAME entity (same slug, same URL, new content). Anonymously, prove ownership with
-the `owner_token`; signed in, use your normal auth headers. Every anonymous edit
-REFRESHES the `owner_token` (store the newest) and resets the expiry. Editing an
+SAME entity (same slug, same URL, new content). Signed in, use your normal auth
+headers. A page dropped anonymously before sign-in was required is edited with its
+`owner_token` instead; every such edit REFRESHES the `owner_token` (store the
+newest) and resets the expiry. Editing an
 archived/expired page returns **409 `EDIT_REJECTED`** — it never silently creates.
 
 Print the `url` on its own line so it can be copied in one go. A single page is an
@@ -107,8 +99,8 @@ Other shapes:
 - **A URL as an inspiration:** `grid plug https://example.com`
 - **Bind to an existing entity first:** `grid plug --existing <entity-id>`
 
-If this is the user's first deploy in the org, the CLI may ask which org to use.
-Pass `--org <slug>` to skip that prompt.
+If this is the user's first deploy in the grid, the CLI may ask which grid to use.
+Pass `--grid <slug>` to skip that prompt.
 
 ## After plug
 

package/src/corpus/skills-readme.md

@@ -57,24 +57,24 @@ needs, build, plug it in, tail logs, share, read feedback. Everything here is fr
 
    Claude Desktop, claude.ai, ChatGPT, and every route in one place: [USAGE.md](USAGE.md).
 
-## Share something in one step, no login
+## Share something in one step
 
 ```
 /cloudgrid:plug index.html
 ```
 
 `cloudgrid:plug` publishes a single HTML page (or deploys a full app) and hands
-back a public URL. For a single page: no account, no CLI — the link lasts 7 days,
-and you can sign in later to keep it.
+back a public URL. For a single page no CLI is needed; publishing needs a CloudGrid
+account, so sign in first with `/cloudgrid:login`.
 
 ## Skills
 
 | Skill | Invoke | What it does |
 |---|---|---|
 | `login` | `/cloudgrid:login` | Sign in to CloudGrid, with or without the CLI. |
-| `claim` | `/cloudgrid:claim` | Claim an anonymous drop into your account after signing in. |
+| `claim` | `/cloudgrid:claim` | Claim an anonymous drop made earlier into your account after signing in. |
 | `init` | `/cloudgrid:init` | Scaffold a new app or agent. |
-| `plug` | `/cloudgrid:plug` | Share a single HTML page (login optional) or deploy a directory/URL. Get a public URL. |
+| `plug` | `/cloudgrid:plug` | Share a single HTML page or deploy a directory/URL (sign-in required). Get a public URL. |
 | `logs` | `/cloudgrid:logs` | Tail logs for an entity. |
 | `share` | `/cloudgrid:share` | Make an entity shareable and print its URL. |
 | `feedback` | `/cloudgrid:feedback` | Read the feedback feed. |

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>--<grid>.cloudgrid.io
 name: my-app
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
@@ -54,7 +54,7 @@ name: my-app
 
 # ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
 
-# Slack notification to the org's default channel on deploy failure.
+# Slack notification to the grid's default channel on deploy failure.
 # true = notify (default), false = silent.
 # notify: true
 
@@ -104,20 +104,20 @@ name: my-app
 
 # Entities this app calls (outbound). Service-account token injected per pair.
 # calls:
-#   - org:atomic/billing-api
+#   - atomic/billing-api
 
 # Inbound caller policy — who can call YOUR entity.
 # callers:
 #   policy: auto                 # 'auto' | 'manual' (default).
-#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   scope: org                   # 'org' (the whole grid; default) | 'space' | 'explicit'.
 #   fallback: deny               # 'deny' (default) | 'warn'.
 #   # allowed_apps:              # required only when scope: explicit
-#   #   - org:atomic/frontend
+#   #   - atomic/frontend
 
 
 # ─── VAULT ──────────────────────────────────────────────────────────────────
 
-# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# Map grid vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
 # vault:
 #   STRIPE_KEY: stripe-live-key
 #   SENDGRID_API_KEY: sendgrid-key
@@ -127,7 +127,7 @@ name: my-app
 
 # connectors:
 #   - id: team-slack
-#     target: org                # 'system' | 'org'.
+#     target: org                # 'system' | 'org' (your grid).
 #     channel: "#deploys"
 # hooks:
 #   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created

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>--<grid>.cloudgrid.io
 name: my-admin
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
@@ -54,7 +54,7 @@ name: my-admin
 
 # ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
 
-# Slack notification to the org's default channel on deploy failure.
+# Slack notification to the grid's default channel on deploy failure.
 # true = notify (default), false = silent.
 # notify: true
 
@@ -104,20 +104,20 @@ name: my-admin
 
 # Entities this app calls (outbound). Service-account token injected per pair.
 # calls:
-#   - org:atomic/billing-api
+#   - atomic/billing-api
 
 # Inbound caller policy — who can call YOUR entity.
 # callers:
 #   policy: auto                 # 'auto' | 'manual' (default).
-#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   scope: org                   # 'org' (the whole grid; default) | 'space' | 'explicit'.
 #   fallback: deny               # 'deny' (default) | 'warn'.
 #   # allowed_apps:              # required only when scope: explicit
-#   #   - org:atomic/frontend
+#   #   - atomic/frontend
 
 
 # ─── VAULT ──────────────────────────────────────────────────────────────────
 
-# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# Map grid vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
 # vault:
 #   STRIPE_KEY: stripe-live-key
 #   SENDGRID_API_KEY: sendgrid-key
@@ -127,7 +127,7 @@ name: my-admin
 
 # connectors:
 #   - id: team-slack
-#     target: org                # 'system' | 'org'.
+#     target: org                # 'system' | 'org' (your grid).
 #     channel: "#deploys"
 # hooks:
 #   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created

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>--<grid>.cloudgrid.io
 name: my-chatbot
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
@@ -54,7 +54,7 @@ name: my-chatbot
 
 # ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
 
-# Slack notification to the org's default channel on deploy failure.
+# Slack notification to the grid's default channel on deploy failure.
 # true = notify (default), false = silent.
 # notify: true
 
@@ -104,20 +104,20 @@ name: my-chatbot
 
 # Entities this app calls (outbound). Service-account token injected per pair.
 # calls:
-#   - org:atomic/billing-api
+#   - atomic/billing-api
 
 # Inbound caller policy — who can call YOUR entity.
 # callers:
 #   policy: auto                 # 'auto' | 'manual' (default).
-#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   scope: org                   # 'org' (the whole grid; default) | 'space' | 'explicit'.
 #   fallback: deny               # 'deny' (default) | 'warn'.
 #   # allowed_apps:              # required only when scope: explicit
-#   #   - org:atomic/frontend
+#   #   - atomic/frontend
 
 
 # ─── VAULT ──────────────────────────────────────────────────────────────────
 
-# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# Map grid vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
 # vault:
 #   STRIPE_KEY: stripe-live-key
 #   SENDGRID_API_KEY: sendgrid-key
@@ -127,7 +127,7 @@ name: my-chatbot
 
 # connectors:
 #   - id: team-slack
-#     target: org                # 'system' | 'org'.
+#     target: org                # 'system' | 'org' (your grid).
 #     channel: "#deploys"
 # hooks:
 #   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created

package/src/corpus/templates/ai-knowledge-base/AGENTS.md

@@ -93,7 +93,7 @@ injected as env vars at `grid dev` (local) and at runtime (after `grid plug`):
 
 The **AI Gateway needs no API key** — `needs: { ai: true }` injects
 `RUNTIME_GATEWAY_URL` and `@cloudgrid-io/runtime` routes through it. The `vault:` block only
-**maps** an org vault item key → an env var name; store the real value once with
+**maps** a grid vault item key → an env var name; store the real value once with
 `grid secrets set <vault-item-key> <value>`. Never commit a secret; never hardcode
 a connection string.
 

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>--<grid>.cloudgrid.io
 name: my-knowledge-base
 
 # One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
@@ -54,7 +54,7 @@ name: my-knowledge-base
 
 # ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
 
-# Slack notification to the org's default channel on deploy failure.
+# Slack notification to the grid's default channel on deploy failure.
 # true = notify (default), false = silent.
 # notify: true
 
@@ -111,20 +111,20 @@ needs:
 
 # Entities this app calls (outbound). Service-account token injected per pair.
 # calls:
-#   - org:atomic/billing-api
+#   - atomic/billing-api
 
 # Inbound caller policy — who can call YOUR entity.
 # callers:
 #   policy: auto                 # 'auto' | 'manual' (default).
-#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   scope: org                   # 'org' (the whole grid; default) | 'space' | 'explicit'.
 #   fallback: deny               # 'deny' (default) | 'warn'.
 #   # allowed_apps:              # required only when scope: explicit
-#   #   - org:atomic/frontend
+#   #   - atomic/frontend
 
 
 # ─── VAULT ──────────────────────────────────────────────────────────────────
 
-# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# Map grid vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
 # This RAG blueprint needs NO secret by default — the AI Gateway is injected via
 # `needs: { ai: true }` (no API key to manage). Uncomment a vault block ONLY if
 # you add auth (gate the chat UI) or payments. Store the value once with
@@ -138,7 +138,7 @@ needs:
 
 # connectors:
 #   - id: team-slack
-#     target: org                # 'system' | 'org'.
+#     target: org                # 'system' | 'org' (your grid).
 #     channel: "#deploys"
 # hooks:
 #   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created