@cloudgrid-io/mcp 0.13.0 → 0.14.0

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

@@ -0,0 +1,104 @@
+---
+name: analytics-dashboard
+when: analytics dashboard, usage analytics, metrics from stored events — a persistent app that records events and shows counts/sums plus a recent-events table. 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 analytics dashboard on the grid — an `events` collection ({ type, value:number, at:date }) with counts/sums metric cards, a recent-events table, and a POST to record events. 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: analytics-dashboard
+
+The user wants a usage-analytics dashboard that **remembers** its data — it
+records **events** and shows aggregate metrics (counts/sums) plus a recent-events
+table, and the 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 an `events` domain
+(`{ type, value:number, at:date }`) and a dashboard view: summary cards
+(total count, total value, distinct types, top type) + a recent table, with a
+form that POSTs a new event.
+
+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-analytics
+   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 + aggregation shape:
+   `gridctl_fetch("template", "analytics-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 an `events`
+   collection, a server-component page that reads the collection and computes
+   counts/sums, and a client form + recent-events table.
+3. Adapt it (rename the collection, change fields, add aggregations). **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 page and API route `export const dynamic = "force-dynamic"` so the
+     metrics 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 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/api-dashboard.md

@@ -0,0 +1,102 @@
+---
+name: api-dashboard
+when: API dashboard, API usage dashboard, API requests monitor — a persistent app that logs API requests and shows count / avg latency / error-rate metrics with a recent-requests table. 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 API dashboard on the grid — a `requests` collection (endpoint, status:number, ms:number, at) with a metrics header (count, avg ms, error rate), a record form, and a recent-requests table. 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: api-dashboard
+
+The user wants an API usage dashboard that **remembers** its request log — a
+monitor whose recorded requests 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 `requests` domain
+(`endpoint`, `status:number`, `ms:number`, `at`), a metrics header (request
+count, average latency, error rate), a record form, and a recent-requests table
+with 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-api-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", "api-dashboard")`. It is a minimal, real Next.js +
+   `mongodb`-driver request monitor under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `requests`
+   collection, a server-component page that reads the log, and a client dashboard
+   that derives the metrics header (count, avg ms, error rate) and renders the
+   record form + recent table.
+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/appointment-booking.md

@@ -0,0 +1,143 @@
+---
+name: appointment-booking
+when: "appointment booking, clinic/salon booking, appointment scheduler"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus auth and optional Stripe deposit 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 AUTH_PROVIDER_KEY (and optionally STRIPE_KEY / STRIPE_WEBHOOK_SECRET) to env vars. This is a BLUEPRINT — read AGENTS.md for the structure, then build. A reminder cron service is designed but cron deploy is PENDING platform issue #1543 (not yet deployable)."
+summary: "Build an appointment / clinic / salon booking app on the grid — a Next.js app where a business defines providers and bookable services, publishes availability, and clients book an open slot, with auth so a provider owns their calendar, optional Stripe deposits, and grid-shared Mongo (providers, services, availability, appointments). This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + slot/anti-double-booking rules + CloudGrid wiring (needs database true, vault for auth/Stripe secrets), build the app under services/web/, deploy async, poll to a live URL. Scheduled reminders are designed but PENDING platform issue #1543."
+---
+
+# Workflow: appointment-booking
+
+The user wants an appointment scheduler — a clinic/salon/consultant booking app:
+a business defines providers and bookable services, publishes availability, and
+clients book an open time slot that no one else can take. That is a **persistent
+runtime app** — a Next.js app backed by the grid's shared Mongo, with auth so a
+provider owns their calendar and optional Stripe deposits.
+
+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 booking 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 "book us" 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 template and read its structure guide — this is the core of the
+workflow:
+
+- `gridctl_fetch("template", "appointment-booking")` — the `cloudgrid.yaml` +
+  **`AGENTS.md`**. AGENTS.md has the file tree, the Mongo collections
+  (`providers`, `services`, `availability`, `appointments`), the slot-computation
+  and anti-double-booking rules, the CloudGrid injection table, and the auth +
+  Stripe 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 slot-computation helper, the auth middleware, the providers/services/
+availability/appointments API routes, the public booking pages, the gated
+provider dashboard, and (optionally) the Stripe deposit checkout + webhook. Adapt
+the providers, services, and availability rules 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.AUTH_PROVIDER_KEY`,
+  `STRIPE_KEY`, `STRIPE_WEBHOOK_SECRET` — inside getters, never top-level.
+- **No double-booking.** `appointments` is the source of truth for "taken".
+  Compute open slots as availability minus booked, re-check availability at write
+  time (never trust the client's slot), and guard the insert with a partial
+  unique index on `{ providerId, startAt }` for active statuses.
+
+`cloudgrid.yaml` active shape:
+
+```yaml
+name: my-appointment-booking
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  AUTH_PROVIDER_KEY: auth-provider-key
+  STRIPE_KEY: stripe-live-key                  # only if taking deposits
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret # only if taking deposits
+```
+
+**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
+
+- Auth + Stripe secrets → `gridctl_secrets` (set the vault items `auth-provider-key`,
+  and if taking deposits `stripe-live-key`, `stripe-webhook-secret`, that the
+  `vault:` block maps from). The deployer injects each as its env var at runtime
+  and under `grid dev`.
+- Non-secret config (auth publishable key `NEXT_PUBLIC_...`, Stripe price ids) →
+  `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. Reminders (cron) — PENDING platform issue #1543
+
+The design wants a scheduled reminder job (notify clients ~24h before their
+appointment, stamp `reminderSentAt` so each is reminded once). AGENTS.md § 7
+documents the intended `reminders` cron service shape. **Cron deploy is a PENDING
+platform issue (#1543) and is NOT yet deployable** — keep that service COMMENTED
+in `cloudgrid.yaml`. Ship the booking app without automated reminders (or trigger
+them manually / from an external scheduler) and tell the user plainly; do not
+claim reminders are live.
+
+## 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.
+- If taking deposits, once live register the `/api/webhook` URL as the Stripe
+  webhook endpoint, copy the signing secret into the `stripe-webhook-secret`
+  vault item, and re-plug. Return the deployed app URL (NOT the build/log link).
+
+## 10. 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, and reminders
+pending cron (#1543).

package/src/corpus/workflows/approval-workflow.md

@@ -0,0 +1,124 @@
+---
+name: approval-workflow
+when: approval workflow, request approvals, multi-step approval system — a persistent app where requests advance through an ordered chain of approver roles (approve/reject/delegate) with an audit log. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: BLUEPRINT — structure + cloudgrid.yaml, not shipped app code. Persistent Next.js + Mongo. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Auth-provider roles + optional payments wired via a `vault:` secret block → env vars. Runtime app, async build, local edition only.
+summary: Build a multi-step approval system on the grid — requests advance through an ordered chain of approval steps decided by assigned roles (approve/reject/delegate), with an append-only audit log and approver notifications. This is a BLUEPRINT: read AGENTS.md for the file tree, Mongo collections (users/requests/steps/audit), the state machine, and CloudGrid wiring (DB injection, vault: secrets, deploy), then build the Next.js + Mongo app under services/web/ following it. Edition-gate first, scaffold, declare needs:{database:true}, wire auth via a vault: secret, deploy async, poll to a live URL.
+---
+
+# Workflow: approval-workflow
+
+The user wants a **multi-step approval system**: a requester submits a request,
+it advances through an ordered chain of approval steps, each step is decided
+(approve / reject / delegate) by an assigned approver role, every action is
+recorded in an audit log, and approvers are notified as their step activates.
+That is a **persistent runtime app** backed by the grid's shared Mongo, with a
+state machine, auth-provider roles, and notifications — the same proven shape as
+`app-with-data`, extended.
+
+**This is a BLUEPRINT.** The template ships the *structure* (an `AGENTS.md`
+guide + a `cloudgrid.yaml`), not runnable app code. The recipe is: read the
+blueprint, 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 persistent approval 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 the approval UI 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 blueprint and read it before building:
+`gridctl_fetch("template", "approval-workflow")`. Its **`AGENTS.md`** is the
+structure guide — the file tree (under `services/web/`), the Mongo collections
+(`users`, `requests`, `steps`, `audit`), the **state machine** (how a request
+advances / is decided across its ordered steps), how CloudGrid injects the DB
+and secrets, how to wire auth roles (and optional payments), and the deploy
+steps. Also fetch the concrete CRUD shape to adapt from:
+`gridctl_fetch("template", "app-with-data")` (lazy `lib/db.js`, App Router
+route, server page).
+
+## 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) write the app under **`services/web/`**
+following `AGENTS.md`, and (b) fill `cloudgrid.yaml` to the shape below.
+
+## 5. Build the app + 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-approvals
+   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 the combination).
+2. Build the collections + state machine from `AGENTS.md`. **Read the DB from
+   `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) inside a **lazy getter — never at module top level**, or
+   `next build` fails.
+3. Keep the state machine (advance / decide across steps) in one module so the
+   API routes and the UI agree on legal transitions; guard every transition
+   server-side and never trust the client about which step is active.
+
+## 6. Wire auth roles (and optional payments) via `vault:`
+
+Approvals need to know who you are and their role. Add an auth-provider SDK
+(Clerk / Auth0), gate routes in `middleware.js`, and read the user + `role` in
+`lib/auth.js`. The provider secret is injected the CloudGrid-correct way — via
+the **`vault:` block** in `cloudgrid.yaml` mapping a vault item to an env var:
+
+```yaml
+vault:
+  AUTH_PROVIDER_KEY: auth-provider-secret-key   # → process.env.AUTH_PROVIDER_KEY
+  # STRIPE_KEY: stripe-live-key                  # only if an approved request charges
+```
+
+Store the real value with `grid secrets set` (mapped by `vault:`); non-secret
+config → `grid env`. Do **NOT** hardcode keys and do **NOT** set
+`DATABASE_MONGODB_URL`/`MONGODB_URL` yourself — the grid injects the DB vars.
+
+## 7. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+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, re-plug the
+SAME entity so it updates the same URL. Keep it honest: this is a blueprint you
+built out, an async runtime build, local-edition only, credentials injected by
+the grid.

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

@@ -0,0 +1,120 @@
+---
+name: billing-dashboard
+when: billing dashboard, invoicing and payments dashboard, SaaS billing
+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 SaaS billing dashboard on the grid — customers, invoices, charges, usage metering, a revenue view (MRR/outstanding), /api/checkout Stripe session to collect invoices, and a signature-verified Stripe webhook that marks invoices paid and records charges. 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, store money as integer cents, declare needs:{database:true} (not requires:), deploy async, poll to a live URL, register the webhook in Stripe.
+---
+
+# Workflow: billing-dashboard
+
+The user wants a **billing / invoicing / payments dashboard** for a SaaS — a place
+to track customers, issue and collect invoices, record charges, meter usage, and
+see revenue (MRR, outstanding, recent invoices). That is a **runtime app** backed
+by the grid's shared Mongo (`customers`, `invoices`, `charges`, `usage_events`)
+plus **Stripe** for payments: a `/api/checkout` route that creates a Stripe
+Checkout Session to collect an invoice, and a signature-verified webhook that marks
+it paid and records the charge. Not a static page — it must remember billing state.
+
+**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 the billing collections 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 billing dashboard 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 revenue-view 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. 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", "billing-dashboard")`.
+2. **Read `AGENTS.md`** in the fetched template. It has: the file tree (app under
+   `services/web/`), the Mongo collections (`customers`, `invoices`, `charges`,
+   `usage_events`) and their fields, how the grid injects Mongo
+   (`DATABASE_MONGODB_URL`) and the Stripe key (the `vault:` block → `STRIPE_KEY`),
+   the checkout + webhook + usage 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-billing
+   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. **Store all money as integer cents.** Compute invoice totals
+  server-side from the stored line items — never trust an amount sent by the browser.
+- The **webhook** reads the RAW request body (`await request.text()`), verifies the
+  Stripe signature, marks the invoice `paid`, and upserts a `charges` doc by the
+  Stripe payment id (idempotent) with the authoritative total from the verified event.
+- Meter usage via `/api/usage` into `usage_events`; the revenue view aggregates
+  `charges` (revenue), `invoices` (outstanding), and `usage_events` per period.
+- (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 dashboard 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.