@cloudgrid-io/mcp 0.12.0 → 0.14.0

package/src/corpus/workflows/kanban.md

@@ -0,0 +1,102 @@
+---
+name: kanban
+when: kanban board, task board, trello-style board, workflow columns — a persistent board whose cards move between columns and stick 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 kanban board on the grid — a `cards` collection (title, column, order) with three columns and move-between-columns + 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: kanban
+
+The user wants a kanban / trello-style board that **remembers** its cards — cards
+that move between columns and survive refresh, 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 `cards` domain (title, column of
+todo/doing/done, order) and three columns with move-between-columns.
+
+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-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", "kanban")`. It is a minimal, real Next.js +
+   `mongodb`-driver board under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH/DELETE route on a
+   `cards` collection (PATCH moves a card between columns), a server-component
+   page, and a client board.
+3. Adapt it (rename the collection, change the columns/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.**
+   - (Optional) fetch `gridctl_fetch("example", "kanban")` for a richer filled
+     reference to imitate.
+
+## 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/lms.md

@@ -0,0 +1,113 @@
+---
+name: lms
+when: "LMS, learning management system, training platform"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus role-based auth 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 to an env var (add STRIPE_KEY / STRIPE_WEBHOOK_SECRET only for paid courses). This is a BLUEPRINT — read AGENTS.md for the structure, then build."
+summary: "Build a learning management system on the grid — a Next.js app with instructor/student role-based auth, courses organized into modules + lessons, student enrollment + per-lesson progress, and an assignment-submission + instructor-grading loop, backed by grid-shared Mongo. This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + CloudGrid wiring (needs database true, vault for the auth secret), build the app under services/web/, deploy async, poll to a live URL."
+---
+
+# Workflow: lms
+
+The user wants a learning management system / training platform: instructors
+publish **courses** organized into **modules** and **lessons**, **students**
+enroll and work through them, and instructors **grade** submissions and track each
+student's **progress**. Role-based auth (instructor vs. student) is the spine —
+that is what separates an LMS from a plain content site. It is a persistent
+**runtime app** backed by the grid's shared Mongo, 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` and 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 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 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 and read it before writing anything:
+`gridctl_fetch("template", "lms")`. `AGENTS.md` is the CloudGrid-specific spec for
+this app — the file tree under `services/web/`, the Mongo collections
+(users/courses/modules/lessons/assignments/enrollments/progress/submissions/grades),
+how the grid injects Mongo + the vault auth secret, the instructor/student role
+gates + grading loop, and the async deploy. Do not expect the app code to exist;
+you build it from the guide.
+
+## 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/`**
+per the AGENTS.md tree, and (b) fill `cloudgrid.yaml` to the shape below.
+
+## 5. cloudgrid.yaml + wiring
+
+Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** — `path:` is
+the URL mount, NOT the filesystem path.
+
+```yaml
+name: my-lms
+vault:
+  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; never
+  author new yaml with it, and never set `needs:` and `requires:` together (the
+  validator rejects it).
+- **Read injected vars LAZILY inside getters, never at module top level** — the DB
+  URL in `lib/db.js` and `AUTH_PROVIDER_KEY` in `lib/auth.js`. A top-level read
+  fails `next build`.
+- **Enforce the instructor/student role gates on the server** (page + API route),
+  not just in the UI — only instructors create courses/lessons and post grades;
+  students submit work and read their own grades/progress. See AGENTS.md §2/§4.
+- (Optional) add `STRIPE_KEY`/`STRIPE_WEBHOOK_SECRET` to `vault:` and a checkout +
+  webhook route only if courses are sold rather than freely enrollable.
+
+## 6. Config
+
+- Secrets → `gridctl_secrets` (e.g. `grid secrets set auth-provider-key`;
+  `stripe-live-key`/`stripe-webhook-secret` only for paid courses). Non-secret
+  config → `gridctl_env` (e.g. the auth publishable key).
+- 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. (If you added Stripe, register the webhook
+to the live URL after the first deploy.)

package/src/corpus/workflows/marketplace.md

@@ -0,0 +1,123 @@
+---
+name: marketplace
+when: "marketplace, multi-vendor platform, two-sided marketplace"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) and payment/auth secrets. Runtime app, async build, local edition only. Declare the canonical needs:{database:true}; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Map Stripe + auth secrets with a vault: block (STRIPE_KEY / STRIPE_WEBHOOK_SECRET / AUTH_PROVIDER_KEY) and grid secrets set the values."
+summary: "A BLUEPRINT for a two-sided / multi-vendor marketplace — vendors, listings, orders, seller auth with roles, Stripe Connect payouts, and commission logic 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 + vault), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
+---
+
+# Workflow: marketplace
+
+The user wants a two-sided / multi-vendor marketplace — many vendors listing
+products, buyers ordering, the platform taking a commission and paying sellers
+out. That is a **persistent runtime app** (Next.js + the grid's shared Mongo) with
+three layered concerns: **seller auth with roles**, **Stripe Connect payouts**,
+and **commission logic**. It is the `app-with-data` shape plus auth + payments.
+
+**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 marketplace is a built + deployed container (Next.js + Mongo + Stripe). 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 storefront 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", "marketplace")`. The deliverable is the **`AGENTS.md`
+structure guide** — read it before writing anything. It defines:
+- the `services/web/` file tree (pages, API routes, `lib/`),
+- the Mongo collections (`vendors`, `listings`, `orders`) + fields,
+- the CloudGrid injection table (needs + vault + AI gateway),
+- how to wire auth (Clerk/Auth0 + a `role` claim) and payments (Stripe Connect
+  onboarding, Checkout with `application_fee` + `transfer_data.destination`, and a
+  signature-verified webhook),
+- 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-marketplace
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-key
+```
+
+**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).
+
+## 5. Build the app following AGENTS.md
+
+Generate the files under `services/web/` per the guide:
+- **Lazy getters** for injected values — read `process.env.DATABASE_MONGODB_URL`
+  (legacy `MONGODB_URL` fallback) and `process.env.STRIPE_KEY` **inside** a getter,
+  never at module top level (a top-level read fails `next build`).
+- Auth SDK (Clerk/Auth0) in `lib/auth.js` from `AUTH_PROVIDER_KEY`; role-gate the
+  seller dashboard + seller API routes in `middleware.js`.
+- Stripe Connect: onboarding account links, Checkout with the platform fee routed
+  via `application_fee_amount` + `transfer_data.destination`, and a webhook that
+  verifies the signature with `STRIPE_WEBHOOK_SECRET` before marking orders paid.
+- Commission as a pure function (`lib/commission.js`); store money as integer cents.
+
+## 6. Config / secrets
+
+- Map secrets in the `vault:` block (done above), then **store the values**:
+  `grid secrets set stripe-live-key sk_live_…`,
+  `grid secrets set stripe-webhook-secret whsec_…`,
+  `grid secrets set auth-provider-key …`. Non-secret public config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 7. (Optional) Run locally
+
+Mention the user can `grid dev` to run locally against the injected dev Mongo +
+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.
+- 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 — the deliverable. Point the Stripe webhook
+endpoint at `<live-url>/api/webhooks/stripe`. 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, and credentials are injected by the
+grid (Mongo via `needs`, Stripe/auth via `vault` + `grid secrets set`).

package/src/corpus/workflows/membership-site.md

@@ -0,0 +1,128 @@
+---
+name: membership-site
+when: "membership site, paid community, subscriber content, gated content"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus auth + 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 / AUTH_PROVIDER_KEY to env vars. This is a BLUEPRINT — read AGENTS.md for the structure, then build."
+summary: "Build a paid membership site on the grid — a Next.js app with user auth, Stripe subscription checkout, gated /members/* routes that check membership status, and grid-shared Mongo (users + memberships collections). This is a BLUEPRINT: fetch the template, read AGENTS.md for the file tree + CloudGrid wiring (needs database true, vault for Stripe/auth secrets), build the app under services/web/, deploy async, poll to a live URL."
+---
+
+# Workflow: membership-site
+
+The user wants a paid membership site / subscriber community: visitors sign up,
+subscribe via Stripe, and only paying members reach the gated content. That is a
+**persistent runtime app** — a Next.js app backed by the grid's shared Mongo,
+with auth and Stripe subscriptions, gated routes that check membership status.
+
+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 membership site 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 paywall-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", "membership-site")` — the `cloudgrid.yaml` +
+  **`AGENTS.md`**. AGENTS.md has the file tree, the Mongo collections
+  (`users`, `memberships`), 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 lazy Stripe client, the auth middleware, the checkout + webhook + me API
+routes, the gated `/members/*` layout, and the pricing + landing pages. Adapt the
+plans, content, 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`, `AUTH_PROVIDER_KEY` — inside getters, never top-level.
+- **Gate server-side.** The `memberships` collection is the source of truth for
+  "have you paid"; `app/members/layout.js` checks it server-side and redirects
+  non-members to `/pricing`. The Stripe webhook writes membership status.
+
+`cloudgrid.yaml` active shape:
+
+```yaml
+name: my-membership-site
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-key
+```
+
+**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 + auth secrets → `gridctl_secrets` (set the vault items `stripe-live-key`,
+  `stripe-webhook-secret`, `auth-provider-key` 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 id) →
+  `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, 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/monitoring-dashboard.md

@@ -0,0 +1,104 @@
+---
+name: monitoring-dashboard
+when: monitoring dashboard, service health board, uptime/incident monitor (data-backed) — a persistent app that records health checks per service and shows current status + history. 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 monitoring dashboard on the grid — a `checks` collection (service, status up/degraded/down, latencyMs, at) with a current-status grid + recent history and a POST-a-check 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: monitoring-dashboard
+
+The user wants a monitoring dashboard / service health board / uptime monitor
+that **remembers** its health checks — a board whose data survives refresh and is
+shared across sessions. That is a **runtime app** backed by the grid's shared
+Mongo, not a static page. It is the same proven shape as `app-with-data`, with a
+`checks` domain (`service`, `status` of up/degraded/down, `latencyMs`, `at`), a
+current-status grid (latest check per service) and a recent-history table, plus a
+form that POSTs a new check.
+
+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-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", "monitoring-dashboard")`. It is a minimal, real
+   Next.js + `mongodb`-driver health board under `services/web/`: a lazy client
+   in `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `checks`
+   collection, a server-component page that derives the status grid, and a client
+   component with the record-check form + status grid + history 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.**
+   - The `checks` route validates `status` against `up`/`degraded`/`down` and
+     `latencyMs` as an optional non-negative number; the status grid is the
+     latest check per service.
+
+## 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.