@cloudgrid-io/mcp 0.20.45 → 0.20.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.45",
+  "version": "0.20.47",
   "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": {
@@ -43,6 +43,7 @@
     "smoke:redrop": "node test/smoke-redrop.mjs",
     "smoke:oauth": "node test/smoke-oauth.mjs",
     "test:auth": "node test/auth.test.mjs",
+    "test:auth-strictness": "node test/auth-strictness.test.mjs",
     "test:win-cli": "node test/windows-cli-resolution.test.mjs",
     "test:electron-env": "node test/electron-spawn-env.test.mjs",
     "smoke:docs": "node test/smoke-docs.mjs",

package/src/auth.js

@@ -94,14 +94,28 @@ export async function pollStatusOnce(code) {
   return res.json();
 }
 
-// Read the stored credentials, or null if absent/unreadable. Same file the CLI
-// writes, so an MCP can reuse a CLI login (and vice versa).
+// Read the stored credentials, or null if absent/unreadable/expired. Same file
+// the CLI writes, so an MCP can reuse a CLI login (and vice versa).
+// Returns { jwt, email, ... } when valid, null otherwise.
 export async function readCredentials() {
+  const result = await readCredentialsStatus();
+  if (result.expired || !result.creds) return null;
+  return result.creds;
+}
+
+// Like readCredentials, but distinguishes "expired" from "absent" so callers
+// (grid_start) can surface a targeted message.
+export async function readCredentialsStatus() {
   try {
     const creds = JSON.parse(await readFile(credentialsPath(), "utf8"));
-    return creds && creds.jwt ? creds : null;
+    if (!creds || !creds.jwt) return { creds: null, expired: false };
+    const claims = decodeJwt(creds.jwt);
+    if (claims.exp && claims.exp * 1000 <= Date.now()) {
+      return { creds: null, expired: true };
+    }
+    return { creds, expired: false };
   } catch {
-    return null;
+    return { creds: null, expired: false };
   }
 }
 

package/src/corpus/playbook.md

@@ -29,12 +29,12 @@ Operating rules:
 Plug is via grid_plug on every edition: for a single HTML page pass it inline as the html param (works on the hosted MCP too); for a multi-file app write the files and pass a folder path (local MCP / CLI — see rules 18–19: run the CLI as `npx -y @cloudgrid-io/cli@latest`, ready before the plug). A single HTML page plugs synchronously as an inspiration, so you get a URL right away. A user-supplied ZIP archive (local edition): pass its path directly as the path param — it is extracted and plugged as a static app; if the zip is assets-only (e.g. images for a gallery), generate the page and pass it as html alongside the zip path, and it becomes the index.html over the archive's files.
 When you plug a folder that already has a cloudgrid.yaml, grid_plug returns needs_confirmation on the first create instead of plugging — it's asking whether to create a NEW app. Relay that to the user, and once they say yes re-call grid_plug with confirm_new_app: true. To update an existing app instead, pass its target_entity_id.
 
-After a plug: a single HTML page plugs synchronously — the URL is live immediately. A runtime app (folder-based, anything with needs:) builds asynchronously: grid_plug returns status "building". When that happens, call grid_check_deploy every ~15 seconds until it reports "success" or "failed". Do NOT tell the user the app is live until grid_check_deploy confirms success. If it reports "failed", read the build log with grid_view_logs, fix the cause, and re-plug.
+After a plug: a single HTML page plugs synchronously — the URL is live immediately. A runtime app (folder-based, anything with needs:) builds asynchronously: grid_plug returns status "building". When that happens, call grid_check_deploy every ~15 seconds until it reports "success" or "failed". Do NOT tell the user the app is live until grid_check_deploy confirms success. If it reports "failed", read the build log with `grid logs`, fix the cause, and re-plug.
 
 Iteration: when the user asks for changes to something already plugged, edit the source and re-call grid_plug with the same target_entity_id to update in place — the URL stays the same. For a single-HTML page, fetch the current HTML with grid_get_app_source, apply the change, and re-plug inline. For a runtime app, edit the files in the folder and re-plug; the build is async, so poll grid_check_deploy the same way as on the first plug.
 
 When something goes wrong:
-- Build failed or app returning errors: call grid_view_logs to read the build or runtime log. Fix the cause and re-plug.
-- Need to see what is running: call grid_status for the current state of an entity (build status, URL, services, needs).
-- Bad plug, need to revert: call grid_rollback_deploy to roll back to the previous working version.
-- Check what was plugged before: call grid_list_versions to see the version history of an entity.
+- Build failed or app returning errors: run `grid logs` to read the build or runtime log. Fix the cause and re-plug.
+- Need to see what is running: run `grid status` for the current state of an entity (build status, URL, services, needs).
+- Bad plug, need to revert: run `grid rollback` to roll back to the previous working version.
+- Check what was plugged before: run `grid versions` to see the version history of an entity.

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

@@ -211,7 +211,7 @@ hosted edition cannot build a runtime container.
 2. The first `grid plug` auto-creates the entity from the manifest (honors its
    `name:`) and writes `.cloudgrid/link.json`. To register without deploying —
    e.g. to set secrets first — use `grid plug --no-deploy` (the
-   `grid_create_project` MCP tool does the same).
+   `grid new` CLI command does the same).
 3. (If you added auth/payments) store the vault secrets with `grid secrets set`;
    non-secret public config → `grid env`. The AI Gateway and Mongo need no secrets
    — they are injected by `needs`.

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

@@ -102,7 +102,7 @@ clients racing for the same slot cannot both win.
     STRIPE_KEY: stripe-live-key                  # only if you take deposits
     STRIPE_WEBHOOK_SECRET: stripe-webhook-secret # only if you take deposits
   ```
-  Set the vault items ONCE with `grid_set_secret` (or `grid secrets set`), then
+  Set the vault items ONCE with `grid secrets set` (or `grid secrets set`), then
   the deployer injects each as the named env var (`process.env.AUTH_PROVIDER_KEY`,
   `process.env.STRIPE_KEY`, …) at runtime and under `grid dev`. Do NOT commit
   keys; do NOT set secrets in `services.web.env` (that block is for non-secret
@@ -163,20 +163,20 @@ you want client accounts.
 
 1. `grid_login_status` → `grid_login` if needed. Respect the grid picker
    (ask which grid if the user has more than one).
-2. `grid_create_project` an app `<name>` — it scaffolds the project folder and
+2. `grid new <name>` — it scaffolds the project folder and
    a `cloudgrid.yaml` with empty `services: {}`. No server entity exists yet —
    the first plug auto-creates it from the manifest (honoring its `name:`) and
    writes `.cloudgrid/link.json`.
 3. Write the app under `services/web/` and set `cloudgrid.yaml` to the active
    shape: `name` + `services.web{type: nextjs, path: /}` + `needs:{database:true}`
    + the `vault:` block. (Leave the `reminders` cron service COMMENTED — see §7.)
-4. Set the secrets: `grid_set_secret` for `auth-provider-key` (and, if taking
+4. Set the secrets: `grid secrets set` for `auth-provider-key` (and, if taking
    deposits, `stripe-live-key`, `stripe-webhook-secret` — the vault item keys the
    `vault:` block maps from). Non-secret config (auth publishable key, price ids)
-   → `grid_set_env` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
+   → `grid env set` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
    yourself — the grid injects it.
 5. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
-   is `status: building`, not a live URL. Poll `grid_status` (or the returned
+   is `status: building`, not a live URL. Poll `grid_check_deploy` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    silent wait.
 6. If taking deposits, once live add the `/api/webhook` URL as the Stripe webhook

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

@@ -26,7 +26,7 @@ Local edition only.
    the getter, never at module top level (top-level read fails `next build`).
 4. **Secrets via the `vault:` block** → env vars. `AUTH_PROVIDER_KEY` (and, for
    deposits, `STRIPE_KEY` / `STRIPE_WEBHOOK_SECRET`) map to vault items; set them
-   with `grid_set_secret`, and the deployer injects them at runtime. Read lazily;
+   with `grid secrets set`, and the deployer injects them at runtime. Read lazily;
    do not commit keys or put secrets in `services.web.env`.
 5. **No double-booking.** `appointments` is the source of truth for "taken";
    compute open slots as availability minus booked, re-check at write time, and
@@ -65,8 +65,8 @@ vault:
 
 ## Deploy (async, local edition)
 
-`grid_create_project` first (creates the entity + link.json), write the app under
-`services/web/`, set the vault secrets with `grid_set_secret`, `grid_plug`
-(async — poll `grid_status` to a live URL). If taking deposits, register the
+`grid new` first (creates the entity + link.json), write the app under
+`services/web/`, set the vault secrets with `grid secrets set`, `grid_plug`
+(async — poll `grid_check_deploy` to a live URL). If taking deposits, register the
 `/api/webhook` URL in Stripe and re-plug. Re-plug the same entity to update the
 same URL.

package/src/corpus/templates/approval-workflow/AGENTS.md

@@ -146,7 +146,7 @@ routes and the UI agree on what is legal.
 
 ## 6. Deploy steps
 
-1. `grid_create_project` an app `<name>` — scaffolds the project folder and a
+1. `grid new <name>` — scaffolds the project folder and a
    `cloudgrid.yaml` with an empty `services: {}`. No server entity exists yet —
    the first `grid plug` auto-creates it from the manifest (honoring its
    `name:`) and writes `.cloudgrid/link.json`.

package/src/corpus/templates/calendar-scheduler/AGENTS.md

@@ -205,7 +205,7 @@ hosted edition cannot build a runtime container.
 2. The first `grid plug` auto-creates the entity from the manifest (honors its
    `name:`) and writes `.cloudgrid/link.json`. To register without deploying —
    e.g. to set secrets first — use `grid plug --no-deploy` (the
-   `grid_create_project` MCP tool does the same).
+   `grid new` CLI command does the same).
 3. (If you mapped vault items) store the values:
    `grid secrets set <vault-item-key> <value>`. Non-secret public config → `grid env`.
    Do NOT set `DATABASE_MONGODB_URL` / `MONGODB_URL` yourself — the grid injects them.

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

@@ -104,7 +104,7 @@ dev` and runtime.
   injects that vault item as `process.env.ENV_VAR`. This blueprint maps
   `AUTH_PROVIDER_SECRET_KEY` and `AUTH_PROVIDER_PUBLISHABLE_KEY`. Rename the env
   keys to whatever the provider SDK expects (see §4) and set the vault items with
-  `grid_set_secret` / the org vault — do not commit keys.
+  `grid secrets set` / the org vault — do not commit keys.
 - **AI (optional)** — if you add `needs: { ai: true }` (e.g. auto-moderation or
   summarize-thread), the grid injects **`RUNTIME_GATEWAY_URL`**; call it via
   `@cloudgrid-io/runtime`. Not required for the base forum.
@@ -169,18 +169,18 @@ A forum is a runtime (built + deployed container) app — **local edition**
 
 1. `grid_login_status` → `grid_login` if needed. Respect the grid picker
    (ask which grid if the user has more than one).
-2. `grid_create_project` an app `<name>` — scaffolds the project folder and a
+2. `grid new <name>` — scaffolds the project folder and a
    `cloudgrid.yaml` with empty `services: {}`. No server entity exists yet — the
    first plug auto-creates it from the manifest (honoring its `name:`) and
    writes `.cloudgrid/link.json`.
 3. Write the app under `services/web/` per §1, then fill `cloudgrid.yaml` to the
    active shape: `name`, `services.web { type: nextjs, path: / }`, `needs:
    { database: true }`, and the `vault:` mappings for the auth keys.
-4. Set the auth secrets: `grid_set_secret` (or the org vault) for the provider
+4. Set the auth secrets: `grid secrets set` (or the org vault) for the provider
    keys. Do NOT set `DATABASE_MONGODB_URL` — the grid injects it.
 5. (Optional) `grid dev` to run locally against injected Mongo before shipping.
 6. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
-   is `status: building`, not a live URL. Poll `grid_status` (or the returned
+   is `status: building`, not a live URL. Poll `grid_check_deploy` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    spinner.
 7. Only once live, return the deployed app URL. Re-plug the SAME entity to update

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

@@ -185,7 +185,7 @@ hosted edition cannot build a runtime container.
    the `vault:` block).
 2. `grid plug --no-deploy` — registers the entity from the manifest (honors its
    `name:`) and writes `.cloudgrid/link.json`, without building yet (the
-   `grid_create_project` MCP tool does the same).
+   `grid new` CLI command does the same).
 3. Store the secrets the vault block maps:
    `grid secrets set stripe-live-key sk_live_…`,
    `grid secrets set stripe-webhook-secret whsec_…`,

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

@@ -78,7 +78,7 @@ A user is a member when a `memberships` doc for their `authId` has
     STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
     AUTH_PROVIDER_KEY: auth-provider-key
   ```
-  Set the vault items ONCE with `grid_set_secret` (or `grid secrets set`), then
+  Set the vault items ONCE with `grid secrets set` (or `grid secrets set`), then
   the deployer injects each as the named env var (`process.env.STRIPE_KEY`, etc.)
   at runtime and under `grid dev`. Do NOT commit keys; do NOT set them in
   `services.web.env` (that block is for non-secret config only). Read them
@@ -132,20 +132,20 @@ A user is a member when a `memberships` doc for their `authId` has
 
 1. `grid_login_status` → `grid_login` if needed. Respect the grid picker
    (ask which grid if the user has more than one).
-2. `grid_create_project` an app `<name>` — it scaffolds the project folder and
+2. `grid new <name>` — it scaffolds the project folder and
    a `cloudgrid.yaml` with empty `services: {}`. No server entity exists yet —
    the first plug auto-creates it from the manifest (honoring its `name:`) and
    writes `.cloudgrid/link.json`.
 3. Write the app under `services/web/` and set `cloudgrid.yaml` to the active
    shape: `name` + `services.web{type: nextjs, path: /}` + `needs:{database:true}`
    + the `vault:` block.
-4. Set the secrets: `grid_set_secret` for `stripe-live-key`,
+4. Set the secrets: `grid secrets set` for `stripe-live-key`,
    `stripe-webhook-secret`, `auth-provider-key` (the vault item keys the
    `vault:` block maps from). Non-secret config (publishable auth key, price id)
-   → `grid_set_env` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
+   → `grid env set` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
    yourself — the grid injects it.
 5. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
-   is `status: building`, not a live URL. Poll `grid_status` (or the returned
+   is `status: building`, not a live URL. Poll `grid_check_deploy` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    silent wait.
 6. Once live, add the `/api/webhook` URL as the Stripe webhook endpoint and copy

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

@@ -24,7 +24,7 @@ edition only.
    the getter, never at module top level (top-level read fails `next build`).
 4. **Secrets via the `vault:` block** → env vars. `STRIPE_KEY`,
    `STRIPE_WEBHOOK_SECRET`, `AUTH_PROVIDER_KEY` map to vault items; set them with
-   `grid_set_secret`, and the deployer injects them at runtime. Read lazily; do
+   `grid secrets set`, and the deployer injects them at runtime. Read lazily; do
    not commit keys or put secrets in `services.web.env`.
 5. **Gate server-side.** Auth answers "who are you"; the `memberships`
    collection answers "have you paid". `app/members/layout.js` checks membership
@@ -60,7 +60,7 @@ vault:
 
 ## Deploy (async, local edition)
 
-`grid_create_project` first (creates the entity + link.json), write the app under
-`services/web/`, set the vault secrets with `grid_set_secret`, `grid_plug`
-(async — poll `grid_status` to a live URL), then register the `/api/webhook`
+`grid new` first (creates the entity + link.json), write the app under
+`services/web/`, set the vault secrets with `grid secrets set`, `grid_plug`
+(async — poll `grid_check_deploy` to a live URL), then register the `/api/webhook`
 URL in Stripe and re-plug. Re-plug the same entity to update the same URL.

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

@@ -115,9 +115,9 @@ You never provision infra or set connection strings by hand. Declare intent in
   `STRIPE_KEY: stripe-live-key`, `SENDGRID_API_KEY: sendgrid-key`,
   `AUTH_PROVIDER_KEY: auth-provider-secret`. The platform reads the named item
   from the org vault and injects it as that env var at runtime. Store the actual
-  secret value with `grid_set_secret` (or the org vault UI) — never commit it. In
+  secret value with `grid secrets set` (or the org vault UI) — never commit it. In
   code read `process.env.STRIPE_KEY`, `process.env.SENDGRID_API_KEY`, etc. Vault
-  is the CloudGrid-correct path for third-party keys; `grid_set_env` is for
+  is the CloudGrid-correct path for third-party keys; `grid env set` is for
   non-secret config only.
 
 - **AI (optional).** If you add AI (e.g. menu-copy generation, natural-language
@@ -154,7 +154,7 @@ Reserved env var names you must NOT set: `PORT`, `APP_NAME`, `SERVICE_NAME`,
    provider; leave `/`, `/reserve`, `/api/menu`, `/api/reservations` (POST),
    `/api/webhooks/stripe` public.
 3. Initialize the SDK from `process.env.AUTH_PROVIDER_KEY` (+ any public
-   publishable key via `grid_set_env`). The public booking flow needs no login.
+   publishable key via `grid env set`). The public booking flow needs no login.
 
 Keep the public reservation POST open; only staff read/mutate endpoints
 (`GET /api/reservations`, `PATCH/DELETE /api/reservations/[id]`, `/staff/*`) sit
@@ -169,19 +169,19 @@ build is **asynchronous**.
 
 1. `grid_login_status` (→ `grid_login` if needed). Pick the grid if the
    user has more than one.
-2. `grid_create_project` an app `<name>` — scaffolds the project folder and a
+2. `grid new <name>` — scaffolds the project folder and a
    `cloudgrid.yaml` with empty `services: {}`. No server entity exists yet — the
    first plug auto-creates it from the manifest (honoring its `name:`) and
    writes `.cloudgrid/link.json`.
 3. **Fill** — write the app under `services/web/`, then set `cloudgrid.yaml` to
    this blueprint's active fields: `name`, `services.web { type: nextjs, path: / }`,
    `needs: { database: true }`, and the `vault:` mappings you actually use.
-4. Store secrets: `grid_set_secret` for the vault item values (Stripe/SendGrid/
-   auth). Non-secret config (publishable keys, feature flags) → `grid_set_env`.
+4. Store secrets: `grid secrets set` for the vault item values (Stripe/SendGrid/
+   auth). Non-secret config (publishable keys, feature flags) → `grid env set`.
 5. (Optional) `grid dev` — runs Next.js locally with `DATABASE_MONGODB_URL` and
    vault vars injected against dev Mongo. Seed `menu`, test a booking.
 6. `grid_plug` — builds + deploys `services/web/`. **Async**: the first
-   response is `status: building`, not a URL. Poll `grid_status` (or the
+   response is `status: building`, not a URL. Poll `grid_check_deploy` (or the
    returned poll URL) until live; surface a liveness signal while it builds
    (never a bare silent wait). Only then return the **live app URL** (not the
    build/log link).

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

@@ -20,7 +20,7 @@ app under `services/web/` following it — the proven `app-with-data` shape with
    `MONGODB_URL` fallback — the grid injects it; never hardcode, never commit.
 3. **Third-party secrets go through the `vault:` block** (Stripe `STRIPE_KEY`,
    email `SENDGRID_API_KEY`, optional `AUTH_PROVIDER_KEY`) → injected env vars;
-   store values with `grid_set_secret`.
+   store values with `grid secrets set`.
 4. **Declare `needs: { database: true }`** (canonical) — never mix `needs:` and
    `requires:`.
 5. **Cron reminder service is documented but NOT deployable yet** (platform issue

package/src/corpus/templates/subscription-management/AGENTS.md

@@ -89,7 +89,7 @@ client for plan/status — read this (kept current by the webhook).
     STRIPE_KEY: stripe-live-key
     STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
   ```
-  Set the vault items ONCE with `grid_set_secret` (or `grid secrets set`), then
+  Set the vault items ONCE with `grid secrets set` (or `grid secrets set`), then
   the deployer injects each as the named env var (`process.env.STRIPE_KEY`, etc.)
   at runtime and under `grid dev`. Do NOT commit keys; do NOT set them in
   `services.web.env` (that block is for non-secret config only). Read them lazily
@@ -160,21 +160,21 @@ known user — otherwise anyone could change anyone's plan.
 
 1. `grid_login_status` → `grid_login` if needed. Respect the grid picker
    (ask which grid if the user has more than one).
-2. `grid_create_project` an app `<name>` — it scaffolds the project folder and
+2. `grid new <name>` — it scaffolds the project folder and
    a `cloudgrid.yaml` with empty `services: {}`. No server entity exists yet —
    the first plug auto-creates it from the manifest (honoring its `name:`) and
    writes `.cloudgrid/link.json`.
 3. Write the app under `services/web/` and set `cloudgrid.yaml` to the active
    shape: `name` + `services.web{type: nextjs, path: /}` + `needs:{database:true}`
    + the `vault:` block.
-4. Set the secrets: `grid_set_secret` for `stripe-live-key`,
+4. Set the secrets: `grid secrets set` for `stripe-live-key`,
    `stripe-webhook-secret` (and `auth-provider-key` if you use an auth SDK) — the
    vault item keys the `vault:` block maps from. Non-secret config (Stripe
-   publishable key, price ids, auth publishable key) → `grid_set_env` /
+   publishable key, price ids, auth publishable key) → `grid env set` /
    `services.web.env`. Do NOT set `DATABASE_MONGODB_URL` yourself — the grid
    injects it.
 5. `grid_plug` to deploy. A runtime deploy is **ASYNC** — the first response
-   is `status: building`, not a live URL. Poll `grid_status` (or the returned
+   is `status: building`, not a live URL. Poll `grid_check_deploy` (or the returned
    poll_url) until live; surface a liveness signal while it builds, never a bare
    silent wait.
 6. Once live, add the `/api/webhook` URL as the Stripe webhook endpoint, copy

package/src/corpus/templates/subscription-management/index.md

@@ -30,7 +30,7 @@ wiring.
    `DATABASE_MONGODB_URL` (legacy `MONGODB_URL` fallback). Read it LAZILY inside
    the getter, never at module top level (top-level read fails `next build`).
 4. **Secrets via the `vault:` block** → env vars. `STRIPE_KEY` and
-   `STRIPE_WEBHOOK_SECRET` map to vault items; set them with `grid_set_secret`,
+   `STRIPE_WEBHOOK_SECRET` map to vault items; set them with `grid secrets set`,
    and the deployer injects them at runtime. Read lazily; do not commit keys or
    put secrets in `services.web.env` (publishable key + price ids go there).
 5. **The webhook is the source of truth.** Change-plan / cancel APIs call Stripe;
@@ -66,8 +66,8 @@ vault:
 
 ## Deploy (async, local edition)
 
-`grid_create_project` first (creates the entity + link.json), write the app under
-`services/web/`, set the vault secrets with `grid_set_secret`, `grid_plug`
-(async — poll `grid_status` to a live URL), then register the `/api/webhook`
+`grid new` first (creates the entity + link.json), write the app under
+`services/web/`, set the vault secrets with `grid secrets set`, `grid_plug`
+(async — poll `grid_check_deploy` to a live URL), then register the `/api/webhook`
 URL in Stripe, configure the Billing Portal, and re-plug. Re-plug the same entity
 to update the same URL.

package/src/corpus/troubleshooting/persistent-apps.md

@@ -15,7 +15,7 @@ Match the symptom to the row, apply the fix, and stop.
 | `next build` fails / DB connection error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.DATABASE_MONGODB_URL` (with a legacy `MONGODB_URL` fallback) LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
 | App builds + deploys but every request 500s with `DATABASE_MONGODB_URL not set` | The datastore isn't declared, or you declared the deprecated `requires:` instead of `needs:` | Declare `needs: { database: true }` in `cloudgrid.yaml`. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). Never set `needs:` and `requires:` together (the validator rejects it). |
 | `DATABASE_MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
-| Deploy seems stuck / no URL returned | Runtime deploys are asynchronous | `plug` returns `status: building`, not a URL. Poll `grid_status` (or the poll_url) until the app is live, then return the live URL. Don't treat the build/log link as the deliverable. |
+| Deploy seems stuck / no URL returned | Runtime deploys are asynchronous | `plug` returns `status: building`, not a URL. Poll `grid_check_deploy` (or the poll_url) until the app is live, then return the live URL. Don't treat the build/log link as the deliverable. |
 | It won't build on the hosted edition | Hosted MCP is inline-only — it can't run the CLI or folder-plug | Runtime apps need the LOCAL edition (Claude Desktop/Code) or the CLI. On hosted, tell the user persistence isn't available there and offer a static version instead. |
 | Redis not available | `cache` wasn't declared | Add `cache: true` to `needs:` in `cloudgrid.yaml`; the grid then injects `CACHE_REDIS_URL` (plus the legacy `REDIS_URL` alias). Only add it if the app actually needs Redis. |
 

package/src/corpus/workflows/admin-dashboard.md

@@ -39,7 +39,7 @@ edition** (Claude Desktop / Claude Code) or the CLI.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 Then (a) write the app under **`services/web/`**,
@@ -84,7 +84,7 @@ before deploying. Don't require it.
 
 ## 6. Config
 
-- API keys / secrets → `grid_set_secret`. Non-secret config → `grid_set_env`.
+- API keys / secrets → `grid secrets set`. Non-secret config → `grid env set`.
 - Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
   legacy `MONGODB_URL`) — the grid injects them.
 
@@ -92,7 +92,7 @@ before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"`, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed app URL (NOT the build/log link).
 

package/src/corpus/workflows/ai-app.md

@@ -41,7 +41,7 @@ Persistent apps are owned entities.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder, a
+`grid new <name>`. It scaffolds the project folder, a
 `cloudgrid.yaml`, and a starter `web` service. No server entity exists yet — the
 first `grid plug` auto-creates it from the manifest (honoring its `name:`) and
 writes `.cloudgrid/link.json`.
@@ -117,8 +117,8 @@ are wired in dev too — and send a test message before deploying. Don't require
 
 ## 6. Config
 
-- Extra API keys / secrets (only if the app needs its own) → `grid_set_secret`.
-- Non-secret config → `grid_set_env`.
+- Extra API keys / secrets (only if the app needs its own) → `grid secrets set`.
+- Non-secret config → `grid env set`.
 - Do **NOT** set the DB connection var yourself (`DATABASE_MONGODB_URL` / legacy
   `MONGODB_URL`) and do **NOT** set an AI key — the grid injects the DB var and
   the AI SDK auto-detects the in-grid identity.
@@ -127,7 +127,7 @@ are wired in dev too — and send a test message before deploying. Don't require
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed URL (the app URL, NOT the build/log
   link).

package/src/corpus/workflows/ai-knowledge-base.md

@@ -65,7 +65,7 @@ There is no app code to copy — you generate it from the guide.
 
 ## 4. Scaffold + fill cloudgrid.yaml
 
-`grid_create_project` an app `<name>` — it scaffolds the project folder and a
+`grid new <name>` — it scaffolds the project folder and a
 starter `cloudgrid.yaml` with empty `services:{}` (no server entity yet; the
 first `grid plug` auto-creates it from the manifest, honoring its `name:`, and
 writes `.cloudgrid/link.json`). Then put the app under **`services/web/`** and
@@ -120,7 +120,7 @@ Generate the files under `services/web/` per the guide:
   yourself; the grid injects them.
 - Only if you add auth/payments: map the secret in the `vault:` block
   (`AUTH_PROVIDER_KEY` and/or `STRIPE_KEY`) and store the value with
-  `grid secrets set <vault-item-key> …`. Non-secret public config → `grid_set_env`.
+  `grid secrets set <vault-item-key> …`. Non-secret public config → `grid env set`.
 
 ## 7. (Optional) Run locally
 
@@ -131,7 +131,7 @@ Gateway before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"`, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed app URL (NOT the build/log link).
 

package/src/corpus/workflows/analytics-dashboard.md

@@ -40,7 +40,7 @@ edition** (Claude Desktop / Claude Code) or the CLI.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 Then (a) write the app under **`services/web/`**,
@@ -86,7 +86,7 @@ before deploying. Don't require it.
 
 ## 6. Config
 
-- API keys / secrets → `grid_set_secret`. Non-secret config → `grid_set_env`.
+- API keys / secrets → `grid secrets set`. Non-secret config → `grid env set`.
 - Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
   legacy `MONGODB_URL`) — the grid injects them.
 
@@ -94,7 +94,7 @@ before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"`, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed app URL (NOT the build/log link).
 

package/src/corpus/workflows/api-dashboard.md

@@ -39,7 +39,7 @@ edition** (Claude Desktop / Claude Code) or the CLI.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 Then (a) write the app under **`services/web/`**,
@@ -84,7 +84,7 @@ before deploying. Don't require it.
 
 ## 6. Config
 
-- API keys / secrets → `grid_set_secret`. Non-secret config → `grid_set_env`.
+- API keys / secrets → `grid secrets set`. Non-secret config → `grid env set`.
 - Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
   legacy `MONGODB_URL`) — the grid injects them.
 
@@ -92,7 +92,7 @@ before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"`, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed app URL (NOT the build/log link).
 

package/src/corpus/workflows/api-service.md

@@ -42,7 +42,7 @@ Persistent services are owned entities.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 
@@ -95,8 +95,8 @@ and hit the endpoints before deploying. Don't require it.
 
 ## 6. Config
 
-- API keys / secrets → `grid_set_secret`.
-- Non-secret config → `grid_set_env`.
+- API keys / secrets → `grid secrets set`.
+- Non-secret config → `grid env set`.
 - Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL`, or the
   legacy `MONGODB_URL` alias) — the grid injects them.
 
@@ -104,7 +104,7 @@ and hit the endpoints before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - Only once it is live, return the deployed URL (the API base URL, NOT the
   build/log link).

package/src/corpus/workflows/app-with-data.md

@@ -43,7 +43,7 @@ Persistent apps are owned entities.
 
 ## 3. Scaffold
 
-`grid_create_project` an app `<name>` (the default `--type` is fine). It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>` (the default `--type` is fine). It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 
@@ -95,8 +95,8 @@ and sanity-check before deploying. Don't require it.
 
 ## 6. Config
 
-- API keys / secrets → `grid_set_secret`.
-- Non-secret config → `grid_set_env`.
+- API keys / secrets → `grid secrets set`.
+- Non-secret config → `grid env set`.
 - Do **NOT** set the DB/cache connection vars yourself (`DATABASE_MONGODB_URL`,
   `CACHE_REDIS_URL`, or their legacy `MONGODB_URL` / `REDIS_URL` aliases) — the
   grid injects them.
@@ -105,7 +105,7 @@ and sanity-check before deploying. Don't require it.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"` with a `poll_url` / entity, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — keep the user informed, never a
   bare silent wait.
 - Only once it is live, return the deployed URL (the app URL, NOT the build/log

package/src/corpus/workflows/appointment-booking.md

@@ -54,7 +54,7 @@ workflow:
 
 ## 4. Scaffold
 
-`grid_create_project` an app `<name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
+`grid new <name>`. It scaffolds the project folder and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. No server entity exists yet — the first `grid plug` auto-creates
 it from the manifest (honoring its `name:`) and writes `.cloudgrid/link.json`.
 Then write the app under **`services/web/`** and
@@ -102,12 +102,12 @@ never set `needs:` and `requires:` together (the validator rejects it).
 
 ## 6. Config / secrets
 
-- Auth + Stripe secrets → `grid_set_secret` (set the vault items `auth-provider-key`,
+- Auth + Stripe secrets → `grid secrets set` (set the vault items `auth-provider-key`,
   and if taking deposits `stripe-live-key`, `stripe-webhook-secret`, that the
   `vault:` block maps from). The deployer injects each as its env var at runtime
   and under `grid dev`.
 - Non-secret config (auth publishable key `NEXT_PUBLIC_...`, Stripe price ids) →
-  `grid_set_env` / `services.web.env`.
+  `grid env set` / `services.web.env`.
 - Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
   `MONGODB_URL`) — the grid injects them.
 
@@ -130,7 +130,7 @@ claim reminders are live.
 
 Deploy the folder with `grid_plug`. A **runtime deploy is ASYNC**: the first
 response is `status: "building"`, NOT a live URL yet.
-- Poll `grid_status` (or the returned poll_url) until the entity is live.
+- Poll `grid_check_deploy` (or the returned poll_url) until the entity is live.
 - Surface a liveness signal while it builds — never a bare silent wait.
 - If taking deposits, once live register the `/api/webhook` URL as the Stripe
   webhook endpoint, copy the signing secret into the `stripe-webhook-secret`