@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/workflows/calendar-scheduler.md

@@ -0,0 +1,134 @@
+---
+name: calendar-scheduler
+when: "calendar scheduler, team calendar, scheduling app, meeting scheduler"
+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). Scheduled reminders want a type:cron service — BLOCKED on platform issue #1543 (documented, not yet deployable). Optional auth/payments/reminder secrets map through a vault: block (AUTH_PROVIDER_KEY / STRIPE_KEY / SENDGRID_API_KEY) with grid secrets set."
+summary: "A BLUEPRINT for a calendar / scheduling app — events, availability slots, timezones + recurrence, optional bookings, on persistent Next.js + Mongo. This is not fill-in-the-blanks app code; it ships structure + cloudgrid.yaml. Fetch the template, read AGENTS.md for the file tree / collections / CloudGrid wiring (needs + optional vault) + the cron reminder shape (blocked on #1543), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
+---
+
+# Workflow: calendar-scheduler
+
+The user wants a calendar / scheduling app — a **team calendar**, a **meeting
+scheduler**, or a booking-style **scheduling app**. That is a **persistent runtime
+app** (Next.js + the grid's shared Mongo) whose domain is **events and
+availability**: events on a calendar, bookable time slots, timezones, recurrence,
+and (eventually) scheduled reminders. It is the `app-with-data` / `crm` shape with
+a time/availability domain.
+
+**This is a BLUEPRINT.** Unlike a fill-in-the-blanks template, it ships
+*structure* — a `cloudgrid.yaml` and an `AGENTS.md` structure guide — not finished
+app code. The recipe is: fetch it, **read `AGENTS.md`**, then **build** the app
+following it. Be honest that a runtime deploy is async and needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A calendar scheduler is a built + deployed container (Next.js + Mongo). 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 calendar mockup** 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. Fetch the blueprint and READ AGENTS.md
+
+`gridctl_fetch("template", "calendar-scheduler")`. The deliverable is the
+**`AGENTS.md` structure guide** — read it before writing anything. It defines:
+- the `services/web/` file tree (calendar page, event + booking routes, `lib/`),
+- the Mongo collections (`events`, `availability`, optional `bookings`) + fields,
+- the CloudGrid injection table (needs + optional vault + AI gateway),
+- the optional auth (Clerk/Auth0 + `ownerId`) and payments (Stripe Checkout +
+  signed webhook) layers,
+- the intended **cron reminder** service shape — **BLOCKED on platform issue
+  #1543** (documented, not yet deployable),
+- the deploy flow.
+
+There is no app code to copy — you generate it from the guide.
+
+## 4. Scaffold + fill cloudgrid.yaml
+
+`gridctl_init` an app `<name>` FIRST (creates the entity + `.cloudgrid/link.json`
+and a starter `cloudgrid.yaml` with empty `services:{}`; `plug` needs a linked
+directory). Then put the app under **`services/web/`** and set `cloudgrid.yaml` to
+the blueprint's active fields:
+
+```yaml
+name: my-calendar
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+**App code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT
+the filesystem path. **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).
+Add a `vault:` entry only when you actually layer in auth / payments / reminders.
+
+## 5. Build the app following AGENTS.md
+
+Generate the files under `services/web/` per the guide:
+- **Lazy getter** for Mongo — read `process.env.DATABASE_MONGODB_URL` (legacy
+  `MONGODB_URL` fallback) **inside** a getter, never at module top level (a
+  top-level read fails `next build`). Same lazy pattern for any Stripe/auth client.
+- **Store all times as UTC `Date` in Mongo**; convert at the edges. Keep timezone
+  / recurrence / overlap logic in a pure `lib/time.js` (expand RRULEs at read
+  time — do not store every instance).
+- Range-query events for the visible window (`startAt < end && endAt > start`);
+  index `{ ownerId: 1, startAt: 1 }`.
+- (Optional) auth: init an SDK in `lib/auth.js` from `AUTH_PROVIDER_KEY`, stamp
+  `ownerId` on writes, gate write APIs in `middleware.js`, keep the public
+  `book/[slug]` page open.
+- (Optional) payments: Stripe Checkout for paid bookings + a signature-verified
+  webhook (read the RAW body before verifying).
+
+## 6. Scheduled reminders (cron) — BLOCKED on #1543
+
+Reminders want a second service of `type: cron` (scan due reminders every few
+minutes, send mail/SMS). **Cron deploy is a PENDING platform issue (#1543)** — do
+NOT uncomment the cron `reminders` service in `cloudgrid.yaml` yet; it will not
+schedule. Ship the HTTP app now and add cron once #1543 lands. If the user needs
+reminders sooner, use the interim workaround in AGENTS.md §5 (an external
+scheduler hitting an authenticated `POST /api/cron/reminders` route on `web`).
+
+## 7. Config / secrets
+
+- Map any secrets in the `vault:` block, then **store the values**:
+  `grid secrets set auth-provider-key …`, `grid secrets set stripe-live-key sk_live_…`,
+  `grid secrets set sendgrid-key SG.…`. Non-secret public config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 8. (Optional) Run locally
+
+Mention the user can `grid dev` to run locally against the injected dev Mongo (+
+secrets) before deploying. Don't require it.
+
+## 9. 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).
+
+## 10. Return the live URL + iterate
+
+Give the user the live app URL — the deliverable. To iterate, re-plug the SAME
+entity so it updates the same URL. Keep it honest: this is a blueprint you built
+from, the build is async, it is local-edition only, Mongo is injected via `needs`,
+optional secrets via `vault` + `grid secrets set`, and scheduled reminders wait on
+platform issue #1543.

package/src/corpus/workflows/company-website.md

@@ -0,0 +1,46 @@
+---
+name: company-website
+when: company website, business site, corporate site, about-us site, small-business homepage
+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 company-website template, fill it with the user's content across hero/about/services/team/contact, deploy it, and return the live share URL.
+---
+
+# Workflow: company-website
+
+Detect the intent ("build me a company website / business site / about-us page
+for X") and follow this recipe. Do not ask setup questions first; use sensible
+defaults from what the user tells you and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "company-website")` to
+   load the self-contained multi-section HTML company site.
+2. **(Optional) Fetch the example.** Call `gridctl_fetch("example", "company-website")`
+   to see a filled site as a reference for tone and structure.
+3. **Fill the template.** Replace the `{{PLACEHOLDER}}` tokens with the user's
+   content, section by section:
+   - **Identity + hero:** company name, tagline, headline, subheadline, and the
+     two call-to-action labels.
+   - **About:** headline, two short paragraphs, and four stat number/label pairs.
+   - **Services:** one card per offering — a single-emoji icon, title, and short
+     description. Duplicate a `.card` block between the `SERVICES_START` /
+     `SERVICES_END` comments to add more.
+   - **Team:** one member per person — avatar initials, name, role, short bio.
+     Duplicate a `.member` block between `TEAM_START` / `TEAM_END` to add more.
+   - **Contact:** headline, subheadline, email, phone, address, hours.
+   - Keep it a single self-contained HTML file. Do not add external scripts,
+     stylesheets, fonts, or large embedded media. Recolor via the `:root` CSS
+     variables (`--accent`, `--bg`, `--fg`) if the user has brand colors.
+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 company website 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. The contact form is
+client-side only; mention the user can wire it to their own email service or
+form endpoint if they want real submissions.

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

@@ -0,0 +1,126 @@
+---
+name: course-platform
+when: "course platform, sell online courses, teachable-style"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus auth + Stripe payments (vault-injected secrets). Runtime app, async build, local edition only. Declare the canonical needs:{database:true}; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Secrets (STRIPE_KEY, STRIPE_WEBHOOK_SECRET, AUTH_PROVIDER_KEY) come from the vault: block."
+summary: "Build a Teachable-style course platform on the grid — sell online courses, gate lessons behind a Stripe purchase, track per-student progress. This is a BLUEPRINT — the template ships the correct cloudgrid.yaml + an AGENTS.md structure guide (file tree, Mongo collections courses/lessons/enrollments/progress, env/vault wiring, auth + Stripe checkout/webhook routes, async deploy). Read AGENTS.md, then build the app under services/web/ following it. Edition-gate first, scaffold, wire DATABASE_MONGODB_URL and vault secrets lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL."
+---
+
+# Workflow: course-platform
+
+The user wants a Teachable-style course platform: sell online courses, gate
+lessons behind a Stripe purchase, and track each student's lesson progress. That
+is a **persistent runtime app** — Next.js + the grid's shared Mongo, with auth
+and payments — not a static page.
+
+**This is a blueprint.** The template does NOT ship runnable app code. It ships
+the correct `cloudgrid.yaml` and an `AGENTS.md` structure guide. Your job is to
+**read `AGENTS.md`, then build the app under `services/web/` 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 course platform 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 course landing 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 structure guide: `gridctl_fetch("template", "course-platform")`. It
+contains AGENTS.md — the CloudGrid-specific spec you must follow:
+
+- the file tree under `services/web/` (catalog page, course detail, gated lesson
+  player, dashboard, and the API routes: courses, enrollments, progress, checkout,
+  Stripe webhook),
+- the Mongo collections + fields (`courses`, `lessons`, `enrollments`,
+  `progress`) and the access rule (a lesson is viewable if `isFreePreview` OR an
+  `enrollments` doc exists — enforced on the server),
+- how CloudGrid injects the DB URL and the vault secrets,
+- how to wire auth (a provider SDK like Clerk/Auth0) and Stripe (checkout +
+  webhook routes),
+- the async deploy steps.
+
+## 4. Scaffold + fill cloudgrid.yaml
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. Run `init` FIRST —
+`plug` needs a linked directory. Then set `cloudgrid.yaml` to the shape below and
+write the app under **`services/web/`** (`path: /` is the URL mount, NOT the
+filesystem path).
+
+```yaml
+name: my-courses
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-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; don't author new
+yaml with it, and never set `needs:` and `requires:` together (the validator
+rejects it).
+
+## 5. Build the app (following AGENTS.md)
+
+Build the Next.js app under `services/web/` per the guide. Critical CloudGrid
+rules:
+
+- **Read every injected var LAZILY, inside a getter — never at module top level**,
+  or `next build` fails. That covers `process.env.DATABASE_MONGODB_URL` (legacy
+  `MONGODB_URL` fallback) in `lib/db.js`, and the vault secrets `STRIPE_KEY` /
+  `STRIPE_WEBHOOK_SECRET` in `lib/stripe.js` and `AUTH_PROVIDER_KEY` in
+  `lib/auth.js`.
+- **Access is granted by the Stripe webhook**, not the checkout redirect: on
+  `checkout.session.completed`, create the `enrollments` doc. Verify the webhook
+  signature with `STRIPE_WEBHOOK_SECRET` against the RAW body.
+- **Gate the lesson player on the server** — check enrollment (or free preview),
+  never rely on hiding UI.
+
+## 6. Config (secrets + env)
+
+- Secrets → `gridctl_secrets`: `grid secrets set stripe-live-key`,
+  `grid secrets set stripe-webhook-secret`, `grid secrets set auth-provider-key`.
+  The `vault:` block injects them as `STRIPE_KEY`, `STRIPE_WEBHOOK_SECRET`,
+  `AUTH_PROVIDER_KEY`.
+- Non-secret config (e.g. the auth **publishable** key) → `gridctl_env`.
+- Do **NOT** set the DB vars yourself (`DATABASE_MONGODB_URL` / 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. Wire Stripe + return the live URL
+
+Register the Stripe webhook to `https://<live-url>/api/webhooks/stripe` in the
+Stripe dashboard, and set its signing secret into the `stripe-webhook-secret`
+vault item. 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/directory.md

@@ -0,0 +1,101 @@
+---
+name: directory
+when: directory, business directory, member directory, listings directory — a persistent app that stores and shows searchable/filterable listings. 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 directory on the grid — an `entries` collection (name, category, url, description) with a searchable/filterable list plus 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: directory
+
+The user wants a **directory** — a searchable, filterable list of listings that
+**remembers** its entries: a business directory, member directory, or listings
+directory 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 an `entries` domain (name, category,
+url, description) and a list view with live search + category filtering and
+per-row 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-directory
+   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", "directory")`. It is a minimal, real Next.js +
+   `mongodb`-driver directory under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an
+   `entries` collection, a server-component page, and a client list with search +
+   category 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/erp.md

@@ -0,0 +1,125 @@
+---
+name: erp
+when: ERP, enterprise resource planning, integrated business system — a large, persistent multi-module app (inventory + orders + finance + HR) with auth/RBAC, backed by a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: persistent + large/multi-module — needs a database (Mongo) plus a provider SDK auth (Clerk/Auth0) and Stripe billing, with keys from the vault. Runtime app, async build, local edition only. Declare `needs: { database: true }` (deployer injects DATABASE_MONGODB_URL / legacy MONGODB_URL) and a `vault:` block for auth + Stripe keys. This is a BLUEPRINT — no app code ships; read AGENTS.md for the structure, then build.
+summary: Build a persistent Next.js + Mongo ERP on the grid — inventory + orders + finance + HR modules in one App-Router service, with auth/RBAC (Clerk/Auth0, keys from vault:) and Stripe billing (STRIPE_KEY from vault:). Collections: items, orders, invoices, payments, employees. This is a BLUEPRINT: fetch it, read AGENTS.md for the file tree + CloudGrid wiring (DATABASE_MONGODB_URL, vault keys, deploy), then build the app under services/web/. Edition-gate first, scaffold, declare needs:{database:true} + vault: auth/Stripe keys (never requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: erp
+
+The user wants an ERP / integrated business system — inventory, orders, finance,
+and HR in one place, with authentication and role-based access (RBAC). Every
+module's records must **remember** across refresh and be shared across users, so
+this is a **large, persistent runtime app** backed by the grid's shared Mongo,
+with a provider SDK for auth and Stripe for the finance module — not a static
+page.
+
+This is a **blueprint**, and it is large and multi-module. No app code ships.
+Fetch the template, **read its `AGENTS.md` for the structure** (file tree, the
+per-module Mongo collections — `items` / `orders` / `invoices` / `payments` /
+`employees` — CloudGrid wiring for DB + vault-backed auth and Stripe keys, and
+the deploy flow), then build the app following it.
+
+Follow this recipe. Be honest that this is a big build, 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, auth-gated multi-module 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 mock** of one screen 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. Fetch the blueprint + read AGENTS.md
+
+`gridctl_fetch("template", "erp")`. It returns `cloudgrid.yaml`, `AGENTS.md` (the
+structure guide), and the README — **no app code**. Read `AGENTS.md` end to end
+before writing anything: it defines the `services/web/` file tree, the Mongo
+collections + fields per module, how CloudGrid injects the DB and the
+vault-backed auth + Stripe keys, how to wire auth/RBAC and the Stripe
+checkout/webhook flow, and the deploy steps. Because this is large, agree with
+the user on which modules to build first (e.g. inventory + orders) rather than
+all four at once.
+
+## 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 (a) build the app under **`services/web/`**
+following `AGENTS.md`, and (b) fill `cloudgrid.yaml` to the shape below.
+
+## 5. Build the app + set cloudgrid.yaml
+
+1. Build the Next.js App-Router app under `services/web/` per `AGENTS.md` — one
+   `web` service hosting each module as its own API-route group + UI page
+   (`inventory`, `orders`, `finance`, `hr`), the collections, auth middleware,
+   `lib/db.js` (lazy Mongo), `lib/auth.js` (session + `requireRole`), and
+   `lib/stripe.js` (lazy Stripe). **App code MUST live under `services/<name>/`**
+   — `path:` is the URL mount, NOT the filesystem path.
+2. Set `cloudgrid.yaml` to the active shape:
+   ```yaml
+   name: my-erp
+   vault:
+     AUTH_PROVIDER_KEY: auth-provider-secret   # Clerk/Auth0 backend key (RBAC)
+     STRIPE_KEY: stripe-live-key               # Stripe secret key (finance module)
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions ONE Mongo (model each module as a collection in
+   it) and injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias).
+   Read it **lazily inside a getter**, never at module top level (a top-level read
+   fails `next build`). `requires:` is the deprecated v1 alias; don't author new
+   yaml with it, and never set `needs:` and `requires:` together (the validator
+   rejects it).
+3. **Auth + Stripe keys come from the `vault:` block, not committed env files.**
+   The `vault:` map injects `AUTH_PROVIDER_KEY` and `STRIPE_KEY` as env vars at
+   build + runtime. (Add `ai: true` to `needs:` only if a module — e.g. demand
+   forecasting — actually uses the AI gateway.)
+
+## 6. Config
+
+- Create the vault items the `vault:` block references (the auth provider's
+  backend key and the Stripe secret key) — `gridctl_secrets` / vault UI. Never
+  commit them. Publishable/front-end auth keys → `gridctl_env`.
+- Register the deployed `/api/finance/webhook` URL as the Stripe webhook endpoint
+  once the app is live.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  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 +
+vault env vars 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.
+- Only once it is live, 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 (add the
+remaining modules, refine RBAC, wire more of finance), re-plug the SAME entity so
+it updates the same URL. Keep it honest: large build, async deploy, local-edition
+only, DB + auth + Stripe credentials injected by the grid / vault.

package/src/corpus/workflows/event-board.md

@@ -0,0 +1,102 @@
+---
+name: event-board
+when: event board, events listing, community events, meetup board — a persistent app that lists upcoming events (title, date, location, description) with add/delete, sorted by date. 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 event board on the grid — an `events` collection (title, date, location, description) shown as an upcoming list sorted by date, with 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: event-board
+
+The user wants a community event board / events listing that **remembers** its
+events — a board whose entries 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 an `events` domain
+(title, date, location, description) shown as an upcoming list sorted by date
+ascending (soonest first), with add 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-event-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", "event-board")`. It is a minimal, real Next.js +
+   `mongodb`-driver event board under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an `events`
+   collection, a server-component page that reads events sorted by date, and a
+   client form + upcoming list.
+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.**
+   - The upcoming board sorts by `date` ascending both server-side (`.sort({ date:
+     1 })`) and client-side after each add.
+
+## 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.