@cloudgrid-io/mcp 0.12.0 → 0.14.0

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.

package/src/corpus/workflows/saas-marketing.md

@@ -0,0 +1,37 @@
+---
+name: saas-marketing
+when: SaaS marketing site, product marketing page, features and pricing page, multi-section product site with pricing tiers, testimonials, and FAQ. For a simpler single-message page, use landing-page instead.
+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 saas-marketing template, fill it with the user's product content, deploy it, and return the live share URL.
+---
+
+# Workflow: saas-marketing
+
+Detect the intent ("build me a SaaS marketing site / product page with pricing")
+and follow this recipe. This is the richer sibling of `landing-page` — reach for
+it when the request calls for pricing tiers, testimonials, and an FAQ, not just a
+hero. For a plain single-section landing page, use `landing-page`. Do not ask
+setup questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "saas-marketing")` to
+   load the self-contained HTML marketing site.
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The product name, tagline, and hero eyebrow/headline/subheadline.
+   - The call-to-action label and (optional) target.
+   - One block per feature (title + short description).
+   - The three pricing plans (name, price, period, feature list). The middle
+     plan is marked "Most popular".
+   - The testimonial quotes and the FAQ question/answer pairs.
+   - 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/status-page.md

@@ -0,0 +1,35 @@
+---
+name: status-page
+when: status page, service status, uptime page, incident history, is-it-down page, system status board. Display-only — status is baked into the page, no live monitoring.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, status baked into the page. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the status-page template, fill it with the user's components and incidents, deploy it, and return the live share URL.
+---
+
+# Workflow: status-page
+
+Detect the intent ("build me a status page / uptime page for X") and follow this
+recipe. This is a display-only static page — the status is baked into the markup,
+there is no live polling. Do not ask setup questions first; use sensible defaults
+and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "status-page")` to load
+   the self-contained HTML status page (overall banner, component list with
+   up/degraded/down pills, per-component uptime bars, incident history).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The overall banner text and its state class (`ok` / `degraded` / `down`).
+   - One row per component: name, a status pill, and the 90-day uptime bar. Mark
+     any non-ok bar segments with class `degraded` or `down`.
+   - The incident history entries: date, title, state, and a short note.
+   - 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/subscription-management.md

@@ -0,0 +1,141 @@
+---
+name: subscription-management
+when: "subscription management, manage subscriptions, self-serve plans/billing"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus Stripe subscription secrets. Runtime app, async build, local edition only. Declare needs { database: true } (deployer injects DATABASE_MONGODB_URL / legacy MONGODB_URL) and a vault block mapping STRIPE_KEY / STRIPE_WEBHOOK_SECRET to env vars. This is a BLUEPRINT — read AGENTS.md for the structure, then build."
+summary: "Build a self-serve subscription-management app on the grid — a Next.js app where a signed-in customer views their current plan, changes/upgrades/downgrades or cancels it, and manages billing via the Stripe Billing Portal, with a Stripe webhook syncing local state and grid-shared Mongo (customers + subscriptions collections). This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + CloudGrid wiring (needs database true, vault for Stripe secrets), build the app under services/web/, deploy async, poll to a live URL."
+---
+
+# Workflow: subscription-management
+
+The user wants self-serve subscription management: a signed-in customer sees
+their current plan, upgrades/downgrades or cancels it, and manages billing (card,
+invoices, receipts) — with the app's state staying in sync with Stripe. That is a
+**persistent runtime app** — a Next.js app backed by the grid's shared Mongo,
+with Stripe subscription updates, the Stripe Billing Portal, and a webhook that
+keeps local subscription state authoritative.
+
+This is the **manage-what-you-already-have** surface. If the user actually wants
+the sign-up + paywall + gated-content acquisition flow, that is the
+`membership-site` workflow instead — the two share the same Stripe + Mongo wiring.
+
+This is a **blueprint**, not a fill-in template. There is no finished app to
+copy — there is a `cloudgrid.yaml` and a structure guide (`AGENTS.md`). Read the
+guide, then build the app following it. 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 subscription-management 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 pricing/plans page** 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. Read the blueprint
+
+Fetch the template and read its structure guide — this is the core of the
+workflow:
+
+- `gridctl_fetch("template", "subscription-management")` — the `cloudgrid.yaml` +
+  **`AGENTS.md`**. AGENTS.md has the file tree, the Mongo collections
+  (`customers`, `subscriptions`), the CloudGrid injection table, and the Stripe
+  change-plan / cancel / billing-portal / webhook wiring. **Read it fully before
+  building.**
+- `gridctl_fetch("template", "app-with-data")` — the proven Next.js + Mongo
+  shape this blueprint extends (lazy db client in `lib/db.js`, App-Router
+  GET/POST route). Imitate its wiring.
+
+## 4. 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 write the app under **`services/web/`** and
+set `cloudgrid.yaml` to the active shape below.
+
+## 5. Build the app following AGENTS.md
+
+Build the file tree from AGENTS.md under `services/web/`: the lazy Mongo client,
+the lazy Stripe client, the plan catalog (`lib/plans.js`), the auth middleware,
+the subscription (change-plan) + cancel + billing-portal + webhook API routes,
+and the `/account` dashboard. Adapt the plans and document fields to the user.
+Key non-negotiables:
+
+- **App code under `services/web/`** — `path:` is the URL mount, NOT the
+  filesystem path. Root files fail with `Service directory not found`.
+- **Read the DB LAZILY** from `process.env.DATABASE_MONGODB_URL` (legacy
+  `process.env.MONGODB_URL` fallback) inside the getter — never at module top
+  level, or `next build` fails.
+- **Read secrets LAZILY** too — `process.env.STRIPE_KEY`,
+  `STRIPE_WEBHOOK_SECRET` — inside getters, never top-level.
+- **The webhook is the source of truth.** The change-plan and cancel APIs call
+  Stripe; do NOT write plan/status to Mongo there — let `/api/webhook` reconcile
+  the `subscriptions` collection so Stripe and Mongo never diverge. Read
+  plan/status server-side from Mongo; validate requested plans against
+  `lib/plans.js` (never accept an arbitrary price id from the client).
+- **Tie every action to the signed-in user** — resolve `userRef` server-side and
+  only ever act on that user's `stripeCustomerId`.
+
+`cloudgrid.yaml` active shape:
+
+```yaml
+name: my-subscription-management
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+```
+
+**Declare the datastore with `needs: { database: true }`** — the canonical
+shape. `requires:` is the deprecated v1 alias; don't author new yaml with it, and
+never set `needs:` and `requires:` together (the validator rejects it).
+
+## 6. Config / secrets
+
+- Stripe secrets → `gridctl_secrets` (set the vault items `stripe-live-key` and
+  `stripe-webhook-secret` that the `vault:` block maps from). The deployer
+  injects each as its env var at runtime and under `grid dev`. Add
+  `auth-provider-key` too if you use an auth SDK.
+- Non-secret config (Stripe publishable key `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`,
+  price ids, auth publishable key) → `gridctl_env` / `services.web.env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 7. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and vault secrets before deploying. Don't require it.
+
+## 8. 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.
+- Once live, register the `/api/webhook` URL as the Stripe webhook endpoint,
+  copy the signing secret into the `stripe-webhook-secret` vault item, configure
+  the Billing Portal in the Stripe dashboard, and re-plug. Return the deployed
+  app URL (NOT the build/log link).
+
+## 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: async build, local-edition
+only, DB injected by the grid, secrets injected from the vault.

package/src/corpus/workflows/task-manager.md

@@ -0,0 +1,101 @@
+---
+name: task-manager
+when: task manager, to-do app (richer than the app-with-data starter), task list with due dates/priorities, complete-toggle + filter — a persistent task app that sticks across refresh. 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 task manager on the grid — a `tasks` collection (title, done, due, priority) with a complete-toggle, active/done filter, add/delete. Richer than the bare app-with-data to-do. 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: task-manager
+
+The user wants a task manager richer than the bare `app-with-data` to-do starter
+— tasks with due dates and priorities, a complete-toggle, and an active/done
+filter, all of which **stick** across 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 `tasks` domain (title,
+done, due, priority of low/medium/high). (For the bare-minimum in-memory to-do,
+use `app-with-data` instead.)
+
+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-tasks
+   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", "task-manager")`. It is a minimal, real Next.js +
+   `mongodb`-driver task manager under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH/DELETE route on a
+   `tasks` collection (PATCH toggles done), a server-component page, and a client
+   list with an active/done filter.
+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/ticket-system.md

@@ -0,0 +1,101 @@
+---
+name: ticket-system
+when: ticket system, support tickets, helpdesk, issue tracker, support queue — a persistent app that stores tickets (subject, requester, status, priority, body) with status changes. 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 support ticket queue on the grid — a `tickets` collection (subject, requester, status open/pending/closed, priority, body) with add / status-change / 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: ticket-system
+
+The user wants a tickets app that **remembers** its
+records — 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 a `tickets` domain
+(subject, requester, status of open/pending/closed, priority, body) and a table view with add, per-row status changes, and delete.
+
+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-tickets
+   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). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "ticket-system")`. 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/PATCH (status)/DELETE route on a `tickets` collection, a
+   server-component page, and a client component.
+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.