@cloudgrid-io/mcp 0.12.0 → 0.14.0

package/src/corpus/workflows/online-store.md

@@ -0,0 +1,114 @@
+---
+name: online-store
+when: online store, e-commerce store, shop with checkout, sell products online
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: persistent + payments — needs a database (Mongo) and Stripe. Runtime app, async build, local edition only. This is a BLUEPRINT — read the template's AGENTS.md for the structure, then build the app. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). The Stripe key comes from the vault: block → STRIPE_KEY.
+summary: Build a persistent Next.js + Mongo + Stripe online store on the grid — storefront, cart, /api/checkout Stripe session, signature-verified Stripe webhook, orders in Mongo. This is a BLUEPRINT: edition-gate first, scaffold, fetch the template and read AGENTS.md for the file tree + wiring, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL lazily and STRIPE_KEY from the vault, declare needs:{database:true} (not requires:), deploy async, poll to a live URL, register the webhook in Stripe.
+---
+
+# Workflow: online-store
+
+The user wants to **sell products online** — a storefront with a cart and real
+checkout. That is a **runtime app** backed by the grid's shared Mongo (`products`
++ `orders`) plus **Stripe** for payments: a `/api/checkout` route that creates a
+Stripe Checkout Session and a signature-verified webhook that confirms payment
+and records the order. Not a static page — it must remember products and orders.
+
+**This is a BLUEPRINT.** The template ships the structure + `cloudgrid.yaml`, not
+finished app code. The build shape is proven `app-with-data` (Next.js App Router,
+lazy Mongo, app under `services/web/`) plus a second collection and Stripe wiring.
+Be honest that a runtime deploy is async (not instant) and needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent store 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. Say so plainly, offer
+  a **static storefront preview** 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.
+
+## 4. Fetch the blueprint and read AGENTS.md
+
+This is a blueprint — the structure guide is the deliverable, not copy-paste code.
+
+1. `gridctl_fetch("template", "online-store")`.
+2. **Read `AGENTS.md`** in the fetched template. It has: the file tree (app under
+   `services/web/`), the Mongo collections (`products`, `orders`) and their
+   fields, how the grid injects Mongo (`DATABASE_MONGODB_URL`) and the Stripe key
+   (the `vault:` block → `STRIPE_KEY`), the checkout + webhook wiring, and the
+   deploy steps. Build the app following it.
+3. Set `cloudgrid.yaml` to the shape below. **App code MUST live under
+   `services/web/`** — `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-store
+   vault:
+     STRIPE_KEY: stripe-live-key
+   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; never
+   set `needs:` and `requires:` together (the validator rejects it).
+
+## 5. Build the app (following AGENTS.md)
+
+- **Read the DB from `process.env.DATABASE_MONGODB_URL`** (legacy `MONGODB_URL`
+  fallback) inside a **lazy getter** — never at module top level, or `next build`
+  fails. Never hardcode a connection string.
+- **Read the Stripe key from `process.env.STRIPE_KEY`** (injected by the `vault:`
+  block) lazily. Build Stripe line items from the server-side `products`
+  collection — never trust prices sent by the browser.
+- The **webhook** reads the RAW request body (`await request.text()`), verifies
+  the Stripe signature, and upserts the `orders` doc by `stripeSessionId`
+  (idempotent), setting `status: "paid"` from the verified event.
+- (Optional) `grid dev` to run locally against the injected Mongo + a Stripe test
+  key before deploying.
+
+## 6. Config
+
+- Stripe secrets → the vault: `gridctl_secrets` to set `stripe-live-key` (and a
+  `stripe-webhook-secret` if you map one). The `vault:` block turns them into env
+  vars. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` /
+  `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. Wire the Stripe webhook + return the live URL
+
+1. Register `<live-url>/api/webhook` as a webhook endpoint in the Stripe
+   dashboard, copy its `whsec_…` secret into the vault, and re-`gridctl_plug` the
+   SAME entity if you changed the `vault:` mapping (same URL).
+2. Give the user the live store URL — that is the deliverable. To iterate, re-plug
+   the SAME entity so it updates the same URL.
+
+Keep it honest: blueprint (build from AGENTS.md), async build, local-edition only,
+Mongo + Stripe credentials injected by the grid / vault.

package/src/corpus/workflows/portfolio.md

@@ -0,0 +1,35 @@
+---
+name: portfolio
+when: portfolio, personal site, freelancer site, my work, showcase, resume site, developer/designer portfolio with a projects grid, about, skills, and contact. For a plain single-section link-in-bio, landing-page also works.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the portfolio template, fill it with the user's projects and bio, deploy it, and return the live share URL.
+---
+
+# Workflow: portfolio
+
+Detect the intent ("build me a portfolio / personal site to show my work") and
+follow this recipe. Reach for this over `landing-page` when the request is about
+showcasing projects with an about, skills, and contact. Do not ask setup
+questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "portfolio")` to load
+   the self-contained HTML portfolio (hero, about, skills, projects grid,
+   contact).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The person's name, role/title, and short intro.
+   - The about paragraph and the skills (one pill each).
+   - One card per project: title, short description, tags, optional link.
+   - The contact links (email as a `mailto:`, plus optional profile links).
+   - Keep it a single self-contained HTML file. Do not add external scripts,
+     stylesheets, fonts, or large embedded media.
+3. **Deploy.** Deploy the filled HTML:
+   - Hosted MCP edition: call the drop tool with the HTML.
+   - Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+   It is an inspiration and deploys synchronously, so you get a URL right away.
+4. **Return the live share URL.** For revisions, re-deploy with the entity id
+   from the first deploy — it updates the same share URL.
+
+Keep the whole flow tight: fetch, fill, deploy, share.

package/src/corpus/workflows/product-catalog.md

@@ -0,0 +1,105 @@
+---
+name: product-catalog
+when: product catalog, product listings, catalog site, browse products (no checkout) — a persistent app that stores products and lets visitors browse them by category. 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). No checkout / payments.
+summary: Build a persistent Next.js + Mongo product catalog on the grid — a `products` collection (name, price, category, description, inStock) with a grid view, category filter, and admin add / delete. 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: product-catalog
+
+The user wants a product catalog / product-listings site that **remembers** its
+products — a catalog whose records 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 `products`
+domain (name, price, category, description, inStock) rendered as a grid with a
+category filter and an admin add/delete section.
+
+This is browse-only — **no checkout, no cart, no payments**. If the user wants to
+sell (cart, checkout, Stripe), that is a different, larger build; say so.
+
+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-catalog
+   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", "product-catalog")`. It is a minimal, real
+   Next.js + `mongodb`-driver catalog under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `products`
+   collection, a server-component page, and a client grid with a category filter
+   and an admin add/delete 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 the API route `export const dynamic = "force-dynamic"` so listings are
+     always 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 catalog 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, browse-only (no checkout).

package/src/corpus/workflows/product-launch.md

@@ -0,0 +1,43 @@
+---
+name: product-launch
+when: product launch page, launch announcement, new product page, we just launched.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the product-launch template, fill it with the user's product/launch content, deploy it, and return the live share URL.
+---
+
+# Workflow: product-launch
+
+Detect the intent ("build a launch page / announcement for our new product X")
+and follow this recipe. Do not ask setup questions first; use sensible defaults
+and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "product-launch")` to
+   load the self-contained HTML launch-page template (hero + product image,
+   countdown, features, launch offer, social proof).
+2. **(Optional) Fetch the example.** Call `gridctl_fetch("example", "product-launch")`
+   to see a filled launch page as a reference for tone and structure.
+3. **Fill the template.** Replace the placeholders with the user's content:
+   - Product name, hero headline, subhead, launch badge, and CTA label/target.
+   - The **countdown target**: set `{{LAUNCH_DATETIME_ISO}}` to an ISO 8601
+     instant (e.g. `2026-09-01T09:00:00Z`). If unset/invalid it falls back to
+     +14 days.
+   - One block per key feature (title + short description).
+   - The launch offer (price, was-price, fine print, offer CTA).
+   - Social-proof stats and testimonials.
+   - Swap the hero product image (the inline `<svg>` in `.shot`) for a real
+     screenshot **only** as inline SVG or a `data:` URI. Keep it a single
+     self-contained HTML file — no external scripts, stylesheets, fonts, CDNs,
+     or large embedded media.
+4. **Deploy.** Deploy the filled HTML:
+   - Hosted MCP edition: call the drop tool with the HTML.
+   - Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+   A launch page is an inspiration and deploys synchronously, so you get a URL
+   right away.
+5. **Return the live share URL.** Give the user the URL that serves the page.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
+
+Keep the whole flow tight: fetch, fill, deploy, share.

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.