@cloudgrid-io/mcp 0.20.12 → 0.20.14

package/README.md

@@ -94,7 +94,7 @@ CLI uses, so the two share one identity.
 
 | Tool | Wraps | Notes |
 |---|---|---|
-| `grid_create_project` | `grid init` | Register an app or agent; optionally seed a web service. |
+| `grid_create_project` | `grid new` | Scaffold an app or agent project; optionally seed a web service. |
 | `grid_view_logs` | `grid logs` | Snapshot of recent logs. Does not stream. Read-only. (`grid_logs` is a kept deprecated alias.) |
 | `grid_share` | `grid visibility set` | Set visibility, default link. |
 | `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. Read-only. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.12",
+  "version": "0.20.14",
   "description": "Use CloudGrid via MCP to brainstorm, build, deploy, and improve apps, games, websites, dashboards, and tools and get a live URL - templates, recipes, managed databases and AI, instant single-page publish, and full-app deploys, for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server, over MCP.",
   "type": "module",
   "bin": {

package/src/corpus/cli-reference.md

@@ -61,7 +61,7 @@ No account needed to try a one-off share: `grid plug ./index.html` drops a publi
 
 ```
 # Scaffold and deploy a Node app
-grid init app my-api --type node
+grid new my-api --type node --dir my-api
 cd my-api && grid plug
 
 # Deploy the current directory and tail its logs
@@ -83,8 +83,8 @@ grid grid
 |---|---|
 | `login` / `logout` / `whoami` | Sign in (Google OAuth), sign out, show user + active org |
 | `use [slug]` | Set or show the active org |
-| `init <kind> <name>` | Register a new app or agent |
-| `plug [target]` | Build + deploy (or redeploy); prints the live URL |
+| `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 |
 | `logs [name]` | Stream entity logs |
@@ -101,7 +101,7 @@ grid grid
 | `doctor` | Diagnostic checks (Node, Docker, API reachability, auth) |
 | `completion <shell>` | Shell completion script |
 
-Run `cloudgrid <command> --help` for the full flag set of any command.
+Run `grid <command> --help` for the full flag set of any command.
 
 ## Flags
 

package/src/corpus/cloudgrid-yaml.md

@@ -11,8 +11,9 @@
 
 `cloudgrid.yaml` is the manifest at the **root of your project** that defines your
 entity (an app or an agent). It declares the services your entity runs, the
-infrastructure it needs, and how it behaves. `grid init` creates it; `grid plug`
-reads it to build and deploy.
+infrastructure it needs, and how it behaves. `grid new` scaffolds it; `grid plug`
+reads it to build and deploy (the first plug in an unlinked directory also
+registers the entity from it, honoring its `name:`).
 
 **Wiring a database or cache? Use `needs:`** — `needs: {database: true}` is
 canonical and the deployer injects the connection env vars from it. See §7 for the

package/src/corpus/cookbook.md

@@ -20,14 +20,15 @@ init  ->  plug  ->  logs  ->  share  ->  feedback
 
 ### 1. Scaffold
 
-Register a new app and seed a static web service:
+Scaffold a new app in the current directory and seed a static web service:
 
 ```
-grid init app my-thing --type static
+grid new my-thing --type static
 ```
 
-`--type` accepts `node`, `nextjs`, `python`, or `static`. For an agent, use
-`grid init agent my-thing`.
+`--type` accepts `node`, `nextjs`, `python`, or `static`; `--dir <path>` targets a
+different folder. For an agent, use `grid new my-thing --agent`. Scaffolding is
+local-only — the entity is created on the first `grid plug`.
 
 ### 2. Deploy
 
@@ -37,6 +38,8 @@ From the project directory, deploy it:
 grid plug
 ```
 
+The first plug auto-creates the entity from `cloudgrid.yaml` (honoring its
+`name:`) and writes `.cloudgrid/link.json`.
 `grid plug` also takes a path or a URL. It builds and deploys, then prints the
 live URL. This usually takes about 30 seconds.
 

package/src/corpus/skill-init.md

@@ -3,16 +3,18 @@ version: 0.2.0
 name: init
 description: |
   Scaffold a new CloudGrid app or agent. Use when the user wants to start a new
-  project, create a new entity, set up a new app or agent, or seed a web service
-  (node, nextjs, python, or static) before deploying. Wraps grid init.
-argument-hint: "[app|agent] [name]"
+  project, set up a new app or agent, or seed a web service
+  (node, nextjs, python, or static) before deploying. Wraps grid new.
+argument-hint: "[name] [--agent]"
 allowed-tools: Bash
 ---
 
 # CloudGrid Init
 
-Register a new app or agent in the active org and, optionally, seed a web service
-to deploy. Wraps `grid init`. After this, `cloudgrid:plug` deploys it.
+Scaffold a new app or agent project and, optionally, seed a web service to
+deploy. Wraps `grid new`. Scaffolding is local-only — no server entity exists
+until the first `grid plug`, which auto-creates it from `cloudgrid.yaml`. After
+this, `cloudgrid:plug` deploys it.
 
 ## Step 0 — Bootstrap
 
@@ -32,40 +34,42 @@ to deploy. Wraps `grid init`. After this, `cloudgrid:plug` deploys it.
 You need two things: the kind and the name.
 
 - **Kind:** `app` or `agent`. Default to `app` unless the user describes an agent
-  (something that acts on its own, calls tools, or runs on a schedule).
+  (something that acts on its own, calls tools, or runs on a schedule). For an
+  agent, pass `--agent` (an app with an `agent:` block is an agent).
 - **Name:** a slug, 3 to 40 lowercase letters, numbers, or hyphens. If the user
   gives a title, derive a slug from it. Confirm the slug before running.
 
 Optional, only if the user implies them:
 
 - `--type` to seed a web service: `node`, `nextjs`, `python`, or `static`.
-- `--dir` to scaffold somewhere other than `./<name>`.
-- `--description` for a one-line description.
+- `--dir <path>` to scaffold somewhere other than the current directory.
+- `--needs <list>` to pre-declare resources (e.g. `database,cache`).
 
 ## Usage
 
-Register an app and seed a static site:
+Scaffold an app in the current directory and seed a static site:
 
 ```
-grid init app my-thing --type static
+grid new my-thing --type static
 ```
 
-Register an agent:
+Scaffold an agent:
 
 ```
-grid init agent my-helper
+grid new my-helper --agent
 ```
 
-Register without seeding any files (you will add your own):
+Scaffold without seeding any files (you will add your own):
 
 ```
-grid init app my-thing
+grid new my-thing
 ```
 
-## After init
+## After scaffolding
 
-Tell the user the entity is registered and what is next: `cd` into the directory
-(if seeded) and run `grid plug` to deploy. Hand off to `cloudgrid:plug`.
+Tell the user the project is set up and what is next: run `grid plug` to deploy —
+the first plug creates the entity from `cloudgrid.yaml` and takes it live. Hand
+off to `cloudgrid:plug`.
 
 ## References
 

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

@@ -205,14 +205,15 @@ var, and `grid secrets set` stores the real value. Never inline a key.
 ## 6. Deploy steps
 
 Runtime app → **local edition** only (Claude Desktop / Claude Code / CLI); the
-hosted edition cannot build a runtime container. Order matters — `plug` needs a
-linked directory, so `init` first.
+hosted edition cannot build a runtime container.
 
-1. `grid init` (or `grid_create_project`) an app `<name>` — creates the entity +
-   `.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services:{}`.
-2. Fill: put the app under `services/web/` and set `cloudgrid.yaml` to this
+1. Put the app under `services/web/` and set `cloudgrid.yaml` to this
    blueprint's active fields (`services.web` nextjs `/`, `needs:{ai:true,
    database:true}`).
+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).
 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/ai-knowledge-base/index.md

@@ -70,7 +70,8 @@ and read it. It covers the `services/web/` file tree, the `documents` / `chunks`
 collections, the CloudGrid injection table (needs + AI Gateway + the pgvector note),
 the ingest → retrieve → answer RAG loop with lazy `lib/db.js` / `lib/ai.js` /
 `lib/retrieve.js`, optional auth/payments via `vault:`, and the
-`grid init → fill → grid plug → poll` deploy flow.
+`write files → grid plug → poll` deploy flow (the first plug auto-creates the
+entity from `cloudgrid.yaml`).
 
 ## Adapt it
 

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

@@ -163,9 +163,10 @@ 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>` FIRST — it creates the entity, writes
-   `.cloudgrid/link.json`, and a `cloudgrid.yaml` with empty `services: {}`.
-   `plug` needs a linked directory.
+2. `grid_create_project` an app `<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.)

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

@@ -146,9 +146,10 @@ routes and the UI agree on what is legal.
 
 ## 6. Deploy steps
 
-1. `grid_create_project` an app `<name>` — creates the entity, `.cloudgrid/link.json`,
-   and a `cloudgrid.yaml` with an empty `services: {}`. Run `init` FIRST because
-   `plug` needs a linked directory.
+1. `grid_create_project` an app `<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`.
 2. Fill `cloudgrid.yaml` to this blueprint's shape (copy this template's file):
    `services.web { type: nextjs, path: / }` + `needs: { database: true }` +
    (uncomment) the `vault:` block for `AUTH_PROVIDER_KEY`.

package/src/corpus/templates/billing-dashboard/AGENTS.md

@@ -160,12 +160,11 @@ publicly.
 
 ## 5. Deploy steps
 
-1. `grid init` an app `<name>` (creates the entity + `.cloudgrid/link.json`, writes
-   a `cloudgrid.yaml` with empty `services: {}`). Run this FIRST — `plug` needs a
-   linked directory.
-2. Write the app under `services/web/` and set `cloudgrid.yaml` to the shape in this
+1. Write the app under `services/web/` and set `cloudgrid.yaml` to the shape in this
    template (name + `services.web` nextjs + `needs: { database: true }` + the
    `vault: { STRIPE_KEY: stripe-live-key }` block).
+2. `grid plug --no-deploy` — registers the entity from the manifest (honors its
+   `name:`) and writes `.cloudgrid/link.json`, without building yet.
 3. `grid secrets set stripe-live-key` (and `stripe-webhook-secret` once you map it)
    so the vault items the `vault:` block references exist. Do NOT set
    `DATABASE_MONGODB_URL` yourself — the grid injects it.

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

@@ -82,6 +82,7 @@ needs:
 
 Fetch `grid_get_template("template", "billing-dashboard")` and read **`AGENTS.md`** — it
 has the checkout + webhook + usage wiring, the vault/secret setup, and the deploy
-steps (`grid init` → write under `services/web/` → `grid secrets set` → `grid plug`,
-async → poll to a live URL → register the webhook endpoint in Stripe). Adapt the
+steps (write under `services/web/` → `grid plug --no-deploy` → `grid secrets set` →
+`grid plug`, async → poll to a live URL → register the webhook endpoint in Stripe).
+Adapt the
 collections, fields, and UI to the user's billing model.

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

@@ -136,12 +136,11 @@ webhook signing secret as `STRIPE_WEBHOOK_SECRET`; read both lazily in
 
 ## 5. Deploy steps
 
-1. `grid init` — scaffolds the entity + `.cloudgrid/link.json`; writes a
-   `cloudgrid.yaml` with an empty `services: {}`. Run this FIRST (plug needs a
-   linked directory).
-2. Fill it in: build the files under `services/web/` and set `cloudgrid.yaml` to
+1. Build the files under `services/web/` and set `cloudgrid.yaml` to
    this template's shape (`services.web` nextjs + `needs: { database: true }` +
    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.
 3. `grid secrets set stripe-live-key <sk_live_…>` and the other vault items, so
    the `vault:` mappings resolve at deploy.
 4. (Optional) `grid dev` — runs Next.js locally with `DATABASE_MONGODB_URL` and

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

@@ -68,8 +68,8 @@ The heart of this blueprint. Read it before building. It covers:
 4. **Auth + payments wiring** — provider SDK from `AUTH_PROVIDER_KEY`; Stripe
    checkout + signature-verified webhook from `STRIPE_KEY` /
    `STRIPE_WEBHOOK_SECRET`.
-5. **Deploy steps** — `grid init` → fill → `grid secrets set` → `grid plug` →
-   poll to live.
+5. **Deploy steps** — write the files → `grid plug --no-deploy` →
+   `grid secrets set` → `grid plug` → poll to live.
 6. **Edition note** — runtime app → local edition only (hosted is static-only).
 7. **Reminder cron** — intended shape + the platform-issue-#1543 PENDING note and
    stopgap.

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

@@ -197,14 +197,15 @@ guarded by a shared secret from the vault), instead of a `type: cron` service.
 ## 6. Deploy steps
 
 Runtime app → **local edition** only (Claude Desktop / Claude Code / CLI); the
-hosted edition cannot build a runtime container. Order matters — `plug` needs a
-linked directory, so `init` first.
+hosted edition cannot build a runtime container.
 
-1. `grid init` (or `grid_create_project`) an app `<name>` — creates the entity +
-   `.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services:{}`.
-2. Fill: put the app under `services/web/` and set `cloudgrid.yaml` to this
+1. Put the app under `services/web/` and set `cloudgrid.yaml` to this
    blueprint's active fields (`services.web` nextjs `/`, `needs:{database:true}`).
    Uncomment a `vault:` entry only if you added auth / payments / reminders.
+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).
 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/calendar-scheduler/index.md

@@ -66,7 +66,8 @@ and read it. It covers the `services/web/` file tree, the `events` / `availabili
 / `bookings` collections, the CloudGrid injection table (needs + optional vault +
 AI gateway), how to wire optional auth (Clerk/Auth0 + `ownerId`) and payments
 (Stripe Checkout + signed webhook), the intended cron reminder job shape (blocked
-on #1543), and the `grid init → fill → secrets set → grid plug → poll` deploy flow.
+on #1543), and the `write files → grid plug --no-deploy → secrets set → grid plug
+→ poll` deploy flow.
 
 ## Adapt it
 

package/src/corpus/templates/course-platform/AGENTS.md

@@ -132,12 +132,11 @@ Use a hosted auth provider SDK (e.g. Clerk or Auth0) rather than rolling your ow
 
 A runtime deploy is **asynchronous** and requires the **local edition** (§6).
 
-1. **`grid init`** an app named `course-platform`. `init` creates the entity +
-   `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an empty
-   `services: {}`. Run it FIRST — `plug` needs a linked directory.
-2. **Fill** — replace the generated `cloudgrid.yaml` with the one in this template
+1. **Write the manifest + app** — use the `cloudgrid.yaml` from this template
    (name + vault + `services.web` nextjs + `needs: { database: true }`), and write
    the app under `services/web/` per the tree above.
+2. **`grid plug --no-deploy`** — registers the entity from the manifest (honors
+   `name: course-platform`) and writes `.cloudgrid/link.json`, without building yet.
 3. **Set secrets** — `grid secrets set stripe-live-key`,
    `grid secrets set stripe-webhook-secret`, `grid secrets set auth-provider-key`.
    Set non-secret client config with `grid env` (e.g. the auth publishable key).

package/src/corpus/templates/course-platform/index.md

@@ -65,6 +65,7 @@ needs:
 ## Build it
 
 Read `AGENTS.md` for the full file tree, collection fields, env/vault wiring, auth
-+ Stripe route contracts, and deploy steps. Then scaffold (`grid init`), write the
-app under `services/web/`, set secrets (`grid secrets set …`), and `grid plug`
-(async — poll to a live URL). Re-plug the same entity to iterate.
++ Stripe route contracts, and deploy steps. Then write the app under
+`services/web/`, register it (`grid plug --no-deploy`), set secrets
+(`grid secrets set …`), and `grid plug` (async — poll to a live URL). Re-plug the
+same entity to iterate.

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

@@ -93,12 +93,11 @@ Add indexes as the data grows (e.g. `items.sku` unique, `orders.status`).
 
 ## 5. Deploy (runtime, async)
 
-1. `grid init` an app `<name>` — creates the entity + `.cloudgrid/link.json` and
-   a `cloudgrid.yaml` with empty `services: {}`. Run init FIRST (plug needs a
-   linked dir).
-2. Fill `cloudgrid.yaml` to this blueprint's shape (services.web nextjs + path:/,
+1. Set `cloudgrid.yaml` to this blueprint's shape (services.web nextjs + path:/,
    `needs: { database: true }`, and the `vault:` mappings), and build the app under
    `services/web/`.
+2. `grid plug --no-deploy` — registers the entity from the manifest (honors its
+   `name:`) and writes `.cloudgrid/link.json`, without building yet.
 3. Put real secret values in the org vault so the `vault:` mappings resolve; set
    any publishable/front-end config via `grid env`.
 4. `grid plug` to deploy. A runtime deploy is **async** — the first response is

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

@@ -14,4 +14,5 @@ app on solid rails instead of guessing at the platform wiring.
 > (active fields: `name` + `services.web` nextjs at `path: /` + `needs:
 > { database: true }` + a `vault:` block for auth/Stripe keys), then build the
 > app under `services/web/` following the guide. Deploy is runtime + async
-> (`grid init` → fill → `grid plug` → poll to live); local edition only.
+> (write the files → `grid plug` → poll to live; the first plug auto-creates the
+> entity from `cloudgrid.yaml`); local edition only.

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

@@ -169,9 +169,10 @@ 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>` — creates the entity + `.cloudgrid/link.json`
-   and a `cloudgrid.yaml` with empty `services: {}`. Run `init` FIRST (`plug`
-   needs a linked dir).
+2. `grid_create_project` an app `<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.

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

@@ -7,6 +7,7 @@ auth via a hosted provider (Clerk / Auth0) whose keys come from the org vault.
 This is a **blueprint**: it ships the structure and the `cloudgrid.yaml`, not
 runnable app code — read `AGENTS.md` for the file tree, Mongo schema, CloudGrid
 wiring (DATABASE_MONGODB_URL, vault→env secrets), auth/moderation, and the
-`grid init → fill → grid plug → poll` deploy flow, then adapt and build the app.
+`write files → grid plug → poll` deploy flow (the first plug auto-creates the
+entity from `cloudgrid.yaml`), then adapt and build the app.
 
 See `AGENTS.md` for the full structure guide.

package/src/corpus/templates/hr-portal/AGENTS.md

@@ -147,12 +147,11 @@ specifics:
 
 A runtime deploy is **async** and needs the **local edition** (see below).
 
-1. **`grid init`** an app named `hr-portal` — creates the entity +
-   `.cloudgrid/link.json` and a `cloudgrid.yaml` with an empty `services: {}`.
-   Run `init` FIRST (`plug` needs a linked directory).
-2. **Fill** the code under `services/web/` and set `cloudgrid.yaml` to the active
-   shape: `name` + `services.web { type: nextjs, path: / }` + `needs:
+1. **Write** the code under `services/web/` and set `cloudgrid.yaml` to the active
+   shape: `name: hr-portal` + `services.web { type: nextjs, path: / }` + `needs:
    { database: true }` + the `vault:` auth-key map.
+2. **`grid plug --no-deploy`** — registers the entity from the manifest (honors
+   its `name:`) and writes `.cloudgrid/link.json`, without building yet.
 3. **Create the vault items** the `vault:` block references (the auth provider's
    secret + publishable keys). `grid secrets` / vault UI — never commit them.
 4. **(Optional) `grid dev`** to run locally against the injected dev Mongo + the

package/src/corpus/templates/hr-portal/README.md

@@ -10,5 +10,6 @@ users — not a static page.
 **This is a blueprint: structure + cloudgrid.yaml, not filled app code.** Read
 `AGENTS.md` for the full structure guide — the `services/web/` file tree, the
 Mongo collections, how CloudGrid injects the DB (`DATABASE_MONGODB_URL`) and the
-vault-backed auth keys, how to wire auth roles, and the `grid init → fill → grid
-plug → poll` deploy flow — then adapt it and build the app following it.
+vault-backed auth keys, how to wire auth roles, and the `write files → grid plug
+→ poll` deploy flow (the first plug auto-creates the entity from
+`cloudgrid.yaml`) — then adapt it and build the app following it.

package/src/corpus/templates/hr-portal/index.md

@@ -30,7 +30,8 @@ Runtime app → **local edition only**, async deploy (poll to a live URL).
 
 Fetch this blueprint with `grid_get_template("template", "hr-portal")`. It returns
 `cloudgrid.yaml`, `AGENTS.md` (the structure guide), and this README — no app
-code. Follow `AGENTS.md` to build, then `grid init → fill → grid plug → poll`.
+code. Follow `AGENTS.md` to build, then `grid plug → poll` (the first plug
+auto-creates the entity from `cloudgrid.yaml`).
 
 ## cloudgrid.yaml
 

package/src/corpus/templates/internal-tools-portal/AGENTS.md

@@ -173,12 +173,11 @@ middleware (Stripe calls it unauthenticated; verify the Stripe signature instead
 
 A runtime deploy is **async** and needs the **local edition** (see below).
 
-1. **`grid init`** an app named `internal-tools-portal` — creates the entity +
-   `.cloudgrid/link.json` and a `cloudgrid.yaml` with an empty `services: {}`.
-   Run `init` FIRST (`plug` needs a linked directory).
-2. **Fill** the code under `services/web/` and set `cloudgrid.yaml` to the active
-   shape: `name` + `services.web { type: nextjs, path: / }` + `needs:
-   { database: true }` + the `vault:` auth-key map.
+1. **Write** the code under `services/web/` and set `cloudgrid.yaml` to the active
+   shape: `name: internal-tools-portal` + `services.web { type: nextjs, path: / }`
+   + `needs: { database: true }` + the `vault:` auth-key map.
+2. **`grid plug --no-deploy`** — registers the entity from the manifest (honors
+   its `name:`) and writes `.cloudgrid/link.json`, without building yet.
 3. **Create the vault items** the `vault:` block references (the auth provider's
    secret + publishable keys, plus any per-tool API secrets). `grid secrets` /
    vault UI — never commit them.

package/src/corpus/templates/internal-tools-portal/README.md

@@ -13,5 +13,5 @@ survive refresh and be shared across the team — not a static page.
 Mongo collections, how CloudGrid injects the DB (`DATABASE_MONGODB_URL`) and the
 vault-backed auth keys, how to wire staff-only auth + RBAC (roles on the `staff`
 record, server-side checks per tool, the tool registry in `lib/tools.js`), and the
-`grid init → fill → grid plug → poll` deploy flow — then adapt it and build the app
-following it.
+`write files → grid plug → poll` deploy flow (the first plug auto-creates the
+entity from `cloudgrid.yaml`) — then adapt it and build the app following it.

package/src/corpus/templates/internal-tools-portal/index.md

@@ -36,7 +36,8 @@ Runtime app → **local edition only**, async deploy (poll to a live URL).
 
 Fetch this blueprint with `grid_get_template("template", "internal-tools-portal")`. It
 returns `cloudgrid.yaml`, `AGENTS.md` (the structure guide), and this README — no
-app code. Follow `AGENTS.md` to build, then `grid init → fill → grid plug → poll`.
+app code. Follow `AGENTS.md` to build, then `grid plug → poll` (the first plug
+auto-creates the entity from `cloudgrid.yaml`).
 
 ## cloudgrid.yaml
 

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

@@ -165,12 +165,11 @@ and a `vault:` mapping for `STRIPE_KEY` + `STRIPE_WEBHOOK_SECRET`:
 
 A runtime deploy is **asynchronous** and requires the **local edition** (§6).
 
-1. **`grid init`** an app named `lms`. `init` creates the entity +
-   `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an empty
-   `services: {}`. Run it FIRST — `plug` needs a linked directory.
-2. **Fill** — replace the generated `cloudgrid.yaml` with the one in this template
+1. **Write the manifest + app** — use the `cloudgrid.yaml` from this template
    (name + vault + `services.web` nextjs + `needs: { database: true }`), and write
    the app under `services/web/` per the tree above.
+2. **`grid plug --no-deploy`** — registers the entity from the manifest (honors
+   `name: lms`) and writes `.cloudgrid/link.json`, without building yet.
 3. **Set secrets** — `grid secrets set auth-provider-key` (and, if selling courses,
    `grid secrets set stripe-live-key` + `grid secrets set stripe-webhook-secret`).
    Set non-secret client config with `grid env` (e.g. the auth publishable key).

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

@@ -73,7 +73,7 @@ needs:
 ## Build it
 
 Read `AGENTS.md` for the full file tree, collection fields, env/vault wiring, the
-instructor/student role gates + grading loop, and deploy steps. Then scaffold
-(`grid init`), write the app under `services/web/`, set secrets
+instructor/student role gates + grading loop, and deploy steps. Then write the
+app under `services/web/`, register it (`grid plug --no-deploy`), set secrets
 (`grid secrets set auth-provider-key`), and `grid plug` (async — poll to a live
 URL). Re-plug the same entity to iterate.

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

@@ -178,14 +178,14 @@ export function stripe() {
 ## 5. Deploy steps
 
 Runtime app → **local edition** only (Claude Desktop / Claude Code / CLI); the
-hosted edition cannot build a runtime container. Order matters — `plug` needs a
-linked directory, so `init` first.
+hosted edition cannot build a runtime container.
 
-1. `grid init` (or `grid_create_project`) an app `<name>` — creates the entity +
-   `.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services:{}`.
-2. Fill: put the app under `services/web/` and set `cloudgrid.yaml` to this
+1. Put the app under `services/web/` and set `cloudgrid.yaml` to this
    blueprint's active fields (`services.web` nextjs `/`, `needs:{database:true}`,
    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).
 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/marketplace/index.md

@@ -64,7 +64,8 @@ and read it. It covers the `services/web/` file tree, the `vendors` / `listings`
 `orders` collections, the CloudGrid injection table (needs + vault + AI gateway),
 how to wire auth (Clerk/Auth0 + roles) and payments (Stripe Connect onboarding,
 Checkout with `application_fee` + `transfer_data.destination`, and the signed
-webhook), and the `grid init → fill → secrets set → grid plug → poll` deploy flow.
+webhook), and the `write files → grid plug --no-deploy → secrets set → grid plug
+→ poll` deploy flow.
 
 ## Adapt it
 

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

@@ -132,9 +132,10 @@ 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>` FIRST — it creates the entity, writes
-   `.cloudgrid/link.json`, and a `cloudgrid.yaml` with empty `services: {}`.
-   `plug` needs a linked directory.
+2. `grid_create_project` an app `<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.

package/src/corpus/templates/online-store/AGENTS.md

@@ -117,12 +117,11 @@ middleware. Not required for a basic store; add it only if the user wants logins
 
 ## 5. Deploy steps
 
-1. `grid init` an app `<name>` (creates the entity + `.cloudgrid/link.json`,
-   writes a `cloudgrid.yaml` with empty `services: {}`). Run this FIRST — `plug`
-   needs a linked directory.
-2. Write the app under `services/web/` and set `cloudgrid.yaml` to the shape in
+1. Write the app under `services/web/` and set `cloudgrid.yaml` to the shape in
    this template (name + `services.web` nextjs + `needs: { database: true }` +
    the `vault: { STRIPE_KEY: stripe-live-key }` block).
+2. `grid plug --no-deploy` — registers the entity from the manifest (honors its
+   `name:`) and writes `.cloudgrid/link.json`, without building yet.
 3. `grid secrets set stripe-live-key` (and the webhook secret) so the vault items
    the `vault:` block references exist. Do NOT set `DATABASE_MONGODB_URL` yourself.
 4. (Optional) `grid dev` to run locally against the injected Mongo + your Stripe

package/src/corpus/templates/online-store/index.md

@@ -76,6 +76,7 @@ needs:
 
 Fetch `grid_get_template("template", "online-store")` and read **`AGENTS.md`** — it
 has the checkout + webhook wiring, the vault/secret setup, and the deploy steps
-(`grid init` → write under `services/web/` → `grid secrets set` → `grid plug`,
-async → poll to a live URL → register the webhook endpoint in Stripe). Adapt the
+(write under `services/web/` → `grid plug --no-deploy` → `grid secrets set` →
+`grid plug`, async → poll to a live URL → register the webhook endpoint in Stripe).
+Adapt the
 catalog, fields, and UI to the user's store.

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

@@ -169,9 +169,10 @@ 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>` — creates the entity + `.cloudgrid/link.json`
-   and a `cloudgrid.yaml` with empty `services: {}`. Run `init` FIRST (plug needs
-   a linked dir).
+2. `grid_create_project` an app `<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.