@cloudgrid-io/mcp 0.12.0 → 0.14.0

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

@@ -0,0 +1,35 @@
+---
+name: docs-site
+when: documentation site, docs, developer docs, guide, manual, knowledge base, help center (static, content baked in). For an interactive API endpoint reference, use api-docs instead.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, content baked into the page. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the docs-site template, fill it with the user's documentation, deploy it, and return the live share URL.
+---
+
+# Workflow: docs-site
+
+Detect the intent ("build me a docs site / documentation for X") and follow this
+recipe. For a REST API endpoint reference specifically, use `api-docs`. Do not
+ask setup questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "docs-site")` to load
+   the self-contained HTML docs layout (sidebar nav, content column, code blocks,
+   client-side search box).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The project/doc name and the sidebar section links.
+   - One content section per topic (heading + prose + optional code block). Keep
+     each section id matching its sidebar anchor.
+   - The code blocks are plain `<pre><code>` — no external highlighter or CDN.
+   - Leave the inline search script as-is; it filters the sidebar client-side.
+   - Keep it a single self-contained HTML file. Do not add external scripts,
+     stylesheets, fonts, or large embedded media.
+3. **Deploy.** Deploy the filled HTML:
+   - Hosted MCP edition: call the drop tool with the HTML.
+   - Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+   It is an inspiration and deploys synchronously, so you get a URL right away.
+4. **Return the live share URL.** For revisions, re-deploy with the entity id
+   from the first deploy — it updates the same share URL.
+
+Keep the whole flow tight: fetch, fill, deploy, share.

package/src/corpus/workflows/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.

package/src/corpus/workflows/expense-tracker.md

@@ -0,0 +1,102 @@
+---
+name: expense-tracker
+when: expense tracker, spending log, budget tracker, expense report — a persistent app that logs expenses (description, amount, category, date), lists them, and totals by category. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo expense tracker on the grid — an `expenses` collection (description, amount:number, category, date) with add / delete, a table view, and totals by category. 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: expense-tracker
+
+The user wants an expense tracker / spending log / budget tracker that
+**remembers** its expenses — records that survive refresh and are shared across
+sessions. That is a **runtime app** backed by the grid's shared Mongo, not a
+static page. It is the same proven shape as `app-with-data`, with an `expenses`
+domain (`description`, `amount` as a number, `category`, `date`), a table view,
+and totals by category (plus a grand total).
+
+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-expenses
+   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", "expense-tracker")`. It is a minimal, real Next.js +
+   `mongodb`-driver expense tracker under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an `expenses`
+   collection, a server-component page, and a client form with a table + totals
+   by category.
+3. Adapt it (adjust the category list, change fields, tweak 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.**
+   - Store `amount` as a number and keep `date` as an ISO `YYYY-MM-DD` string so
+     totals and sorting stay simple.
+
+## 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/feature-request-board.md

@@ -0,0 +1,105 @@
+---
+name: feature-request-board
+when: feature request board, feedback board, roadmap voting, idea board — a persistent app where users add requests and upvote them, each with a status. 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 feature request board on the grid — a `requests` collection (title, description, votes:number, status of open/planned/done) with list / upvote (atomic increment) / add. 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: feature-request-board
+
+The user wants a feature request / feedback board — a page where people add
+requests, **upvote** the ones they care about, and each request carries a status
+(open / planned / done). Votes and requests must **persist** and be shared across
+users, so this 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 (title, description, votes:number, status) and a voting board view.
+
+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 (a voting board whose state lives
+  in memory only, lost on refresh), 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", "feature-request-board")`. 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
+   `requests` collection (PATCH does an atomic `$inc` upvote), a server-component
+   page, and a client voting board.
+3. Adapt it (rename the collection, change fields, adjust the UI). The domain is
+   `requests { title, description, votes:number, status(open/planned/done) }`
+   with list (votes desc) + upvote (increment) + add. **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 vote increment atomic on the server (`$inc`), so concurrent upvotes
+     don't clobber each other.
+
+## 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/financial-dashboard.md

@@ -0,0 +1,103 @@
+---
+name: financial-dashboard
+when: financial dashboard, finance metrics, P&L, cashflow board — a persistent app that tracks income/expense entries by account and shows income/expense/net totals with a 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 financial dashboard on the grid — an `entries` collection (account, amount:number, type income/expense, at) with income/expense/net totals + table + 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: financial-dashboard
+
+The user wants a financial dashboard / P&L / cashflow board that **remembers**
+its numbers — income and expense entries 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 (account, amount:number, type of income/expense, at) and a
+dashboard view: income / expense / net totals above a table with add 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-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", "financial-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 `entries`
+   collection, a server-component page that computes income/expense/net totals,
+   and a client board (totals cards + table + add form).
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - Keep the API route `export const dynamic = "force-dynamic"` so it always
+     reads/writes live data.
+
+## 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.