@cloudgrid-io/mcp 0.13.0 → 0.14.0

package/src/corpus/workflows/project-management.md

@@ -0,0 +1,106 @@
+---
+name: project-management
+when: "project management, projects and tasks tracker, team project board — a persistent app that tracks projects and their tasks on a status board. Needs a database → runtime → local edition."
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo project management app on the grid — a `projects` collection (name) plus a `tasks` collection (projectId, title, status todo/doing/done, assignee) with a project list and a per-project task board. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: project-management
+
+The user wants a project & task tracker — a team project board that **remembers**
+its projects and tasks so they survive refresh and are shared across sessions.
+That is a **runtime app** backed by the grid's shared Mongo, not a static page.
+It is the same proven shape as `app-with-data`, with two collections:
+
+- **projects** — `{ name }`
+- **tasks** — `{ projectId, title, status: todo | doing | done, assignee }`
+
+The UI is a project list plus a per-project task board with three status columns
+(to do / doing / done); cards move between columns and carry an optional assignee.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-project-board
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "project-management")`. It is a minimal, real
+   Next.js + `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `projects`
+   collection, a GET/POST/PATCH/DELETE route on a `tasks` collection, a
+   server-component page, and a client board component.
+3. Adapt it (rename the collections, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - Every route file exports `const dynamic = "force-dynamic"` so data is never
+     cached.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (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).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/property-listings.md

@@ -0,0 +1,101 @@
+---
+name: property-listings
+when: property listings, real estate site, rentals/homes listings — a persistent site that stores and browses properties by location and price. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo property listings site on the grid — a `properties` collection (title, price:number, location, beds:number, description) with a card grid, a location/price filter, a detail view, and an admin add form. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: property-listings
+
+The user wants a real-estate / property listings site that **remembers** its
+properties — listings that survive refresh and are shared across sessions. That
+is a **runtime app** backed by the grid's shared Mongo, not a static page. It is
+the same proven shape as `app-with-data`, with a `properties` domain
+(title, price:number, location, beds:number, description) rendered as a card grid
+with a location/price filter, a per-property detail view, and an admin add form.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-listings
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "property-listings")`. It is a minimal, real
+   Next.js + `mongodb`-driver listings site under `services/web/`: a lazy client
+   in `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a
+   `properties` collection (GET supports `?location=` and `?maxPrice=` filters), a
+   server-component page that reads + filters, and a client card grid with a
+   detail view and admin add form.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (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).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/quiz-platform.md

@@ -0,0 +1,105 @@
+---
+name: quiz-platform
+when: quiz, quiz platform, trivia, assessment, questionnaire — a persistent app that stores questions and lets people take a scored quiz, with an admin form to add questions. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo quiz/trivia platform on the grid — a `questions` collection ({ prompt, options: string[], answerIndex: number }) with a take-quiz UI that computes a score and an admin add-question form. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: quiz-platform
+
+The user wants a quiz / trivia / assessment app that **remembers** its questions
+— a quiz whose question bank survives refresh and is shared across sessions.
+That is a **runtime app** backed by the grid's shared Mongo, not a static page.
+It is the same proven shape as `app-with-data`, with a `questions` domain
+(`{ prompt: string, options: string[], answerIndex: number }`): a take-quiz UI
+that lets a visitor pick one option per question and submit for a computed score,
+plus an admin form that adds new questions.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-quiz
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "quiz-platform")`. It is a minimal, real Next.js +
+   `mongodb`-driver quiz platform under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a
+   `questions` collection, a server-component page that reads the collection, and
+   a client component (`quiz.js`) that runs the take-quiz UI (score computed by
+   comparing each chosen option index against the question's `answerIndex`) and
+   an admin add-question form.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - Keep route handlers `export const dynamic = "force-dynamic"` so questions
+     are always read/written live.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (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).
+
+## 8. Return the live URL + iterate
+
+Give the user the live quiz URL — that is the deliverable. To iterate, re-plug
+the SAME entity so it updates the same URL. Keep it honest: async build,
+local-edition only, credentials injected by the grid.

package/src/corpus/workflows/restaurant-reservations.md

@@ -0,0 +1,123 @@
+---
+name: restaurant-reservations
+when: "restaurant website with reservations, table booking, restaurant site — a public Next.js site with menu content and a persistent reservations/table-booking collection backed by Mongo. Runtime app → local edition. This is a BLUEPRINT: read AGENTS.md for the structure, then build the app."
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Third-party secrets (Stripe deposit, email) go through the `vault:` block. A confirmation-reminder cron service is DESIGNED but NOT deployable yet (platform issue #1543)."
+summary: "BLUEPRINT for a restaurant website with online reservations — a public Next.js + Mongo site (menu content + a reservations / table-booking collection) on the grid. It is structure + cloudgrid.yaml, not runnable code: fetch the template, READ AGENTS.md for the file tree, the menu/reservations/tables collections, and the CloudGrid wiring (DATABASE_MONGODB_URL injection, vault: for Stripe/email secrets, optional auth, deploy/poll), then build the app under services/web/ following it. needs:{database:true} (not requires:). Async runtime deploy, local edition only. Cron reminders are designed but PENDING #1543."
+---
+
+# Workflow: restaurant-reservations
+
+The user wants a **restaurant website with online reservations** — a public site
+with menu content and a booking form (optionally table booking) whose
+reservations **persist** and are shared across sessions. That is a **runtime app**
+backed by the grid's shared Mongo, not a static page.
+
+**This is a BLUEPRINT.** The template does NOT contain app code — it ships a
+`cloudgrid.yaml` and an `AGENTS.md` structure guide. The recipe is: fetch it,
+**read `AGENTS.md`**, then build the app under `services/web/` following that
+structure (the proven `app-with-data` shape, with a `reservations` domain).
+
+Be honest that a runtime deploy is async (not instant like a static drop), that
+it needs the local edition, and that the confirmation-reminder **cron** service
+is designed but **not yet deployable** (platform issue #1543).
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly,
+  offer a **static menu page** (no bookings) instead, and STOP the runtime path.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Fetch the blueprint and READ AGENTS.md
+
+`gridctl_fetch("template", "restaurant-reservations")`. This is a **blueprint**,
+so the deliverable is `cloudgrid.yaml` + `AGENTS.md`, not app code.
+
+**Read `AGENTS.md` before building.** It defines:
+- the file tree (`services/web/{app/, lib/, api routes, package.json}`, optional
+  Stripe checkout + webhook routes, optional staff auth, a `services/reminder/`
+  cron job),
+- the Mongo collections + fields (`menu`, `reservations`, `tables`),
+- how CloudGrid injects the DB (`DATABASE_MONGODB_URL` / legacy `MONGODB_URL`) and
+  vault secrets, how to wire Stripe/auth, deploy steps, and the cron shape.
+
+## 4. Scaffold + fill
+
+1. `gridctl_init` an app `<name>` — creates the entity + `.cloudgrid/link.json`
+   and a `cloudgrid.yaml` with an EMPTY `services: {}`. Run `init` FIRST (plug
+   needs a linked directory).
+2. Write the app under **`services/web/`** (`path:` is the URL mount, NOT the
+   filesystem path), following `AGENTS.md`.
+3. Set `cloudgrid.yaml` to the blueprint's active fields:
+   ```yaml
+   name: my-restaurant
+   vault:
+     STRIPE_KEY: stripe-live-key      # only if taking a deposit
+     SENDGRID_API_KEY: sendgrid-key   # confirmation / reminder email
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   Declare `needs: { database: true }` (canonical) — the deployer provisions Mongo
+   and injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`). `requires:` is the
+   deprecated v1 alias; never author it and never set `needs:` and `requires:`
+   together (the validator rejects the combination).
+4. **Read the DB from `process.env.DATABASE_MONGODB_URL`** (legacy `MONGODB_URL`
+   fallback) behind a **lazy getter** — never at module top level, or `next build`
+   fails. Third-party keys come from the vault-injected env vars
+   (`process.env.STRIPE_KEY`, `process.env.SENDGRID_API_KEY`).
+
+## 5. Config / secrets
+
+- Secret values (Stripe, SendGrid, auth) → `gridctl_secrets` (the `vault:` block
+  maps them to env vars). Non-secret config (publishable keys, flags) →
+  `gridctl_env`.
+- Do **NOT** set the DB vars yourself (`DATABASE_MONGODB_URL` / `MONGODB_URL`) —
+  the grid injects them.
+
+## 6. (Optional) Run locally
+
+`grid dev` runs Next.js with `DATABASE_MONGODB_URL` and vault vars injected
+against dev Mongo. Seed the `menu` collection, test a booking. Don't require it.
+
+## 7. Deploy (async)
+
+Deploy `services/web/` with `gridctl_plug`. A **runtime deploy is ASYNC**: the
+first response is `status: building`, NOT a live URL.
+- Poll `gridctl_status` (or the returned poll URL) until live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once live, return the deployed app URL (NOT the build/log link).
+- If Stripe deposits are on, register the live `/api/webhooks/stripe` URL in the
+  Stripe dashboard.
+
+## 8. Cron reminders — PENDING #1543
+
+The design includes a daily cron job that emails reminders to next-day bookings
+(a `reminder:` cron service reading the same injected `DATABASE_MONGODB_URL` +
+`SENDGRID_API_KEY`). **Cron deploy is not yet available (platform issue #1543)** —
+keep the `reminder:` cron block **commented** in `cloudgrid.yaml`; an active cron
+service will be rejected at plug until #1543 lands. Build the rest now; enable
+cron once it ships. See `AGENTS.md` §7 for the intended shape and interim
+workaround.
+
+## 9. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: blueprint you built out,
+async build, local-edition only, DB + secrets injected by the grid, cron pending.

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

@@ -0,0 +1,102 @@
+---
+name: revenue-dashboard
+when: revenue dashboard, sales dashboard, MRR/revenue view — a persistent app that records sales and shows total revenue, a per-product breakdown, and recent activity. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo revenue dashboard on the grid — a `sales` collection (product, amount:number, at) rendered as a total-revenue figure, a per-product breakdown, and a recent-sales table with an add form. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: revenue-dashboard
+
+The user wants a revenue / sales dashboard that **remembers** its sales — a view
+whose numbers survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `sales` domain
+(`product`, `amount` as a number, `at` timestamp) and a dashboard view: a total
+revenue figure, a per-product breakdown, a recent-sales table, and an add form.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-revenue-dashboard
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "revenue-dashboard")`. It is a minimal, real
+   Next.js + `mongodb`-driver dashboard under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `sales`
+   collection, a server-component page that computes the total + per-product
+   breakdown + recent table, and a client add-sale form.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - Sales documents are `{ product: string, amount: number, at: Date }`; keep
+     `amount` numeric so the total and breakdown sums are correct.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (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).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.