@cloudgrid-io/mcp 0.13.0 → 0.14.0

package/src/corpus/workflows/hr-portal.md

@@ -0,0 +1,115 @@
+---
+name: hr-portal
+when: HR portal, employee portal, HR management, leave/PTO system — a persistent app where employees submit leave/PTO requests and admins approve them, with employee/admin auth. Needs a database + auth provider → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: persistent — needs a database (Mongo) + a provider SDK auth (Clerk/Auth0) 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 the auth keys. This is a BLUEPRINT — no app code ships; read AGENTS.md for the structure, then build.
+summary: Build a persistent Next.js + Mongo HR/employee portal on the grid with employee/admin auth (Clerk/Auth0, keys from vault:) and a leave/PTO request + approval flow — `employees` + `leaveRequests` collections. 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 keys (never requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: hr-portal
+
+The user wants an HR / employee portal — employees submit leave/PTO requests,
+admins approve or reject them, gated by employee/admin auth. HR records and leave
+requests must **remember** across refresh and be shared across users, so this is
+a **persistent runtime app** backed by the grid's shared Mongo with a provider
+SDK for auth — not a static page.
+
+This is a **blueprint**. No app code ships. Fetch the template, **read its
+`AGENTS.md` for the structure** (file tree, `employees` + `leaveRequests`
+collections, CloudGrid wiring for DB + vault-backed auth keys, deploy flow), then
+build the app following it.
+
+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, auth-gated 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** 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", "hr-portal")`. 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, how CloudGrid injects the DB and vault-backed auth keys, how
+to wire employee/admin auth, and the deploy steps.
+
+## 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 under `services/web/` per `AGENTS.md` — the
+   `employees` + `leaveRequests` collections, the leave-request + approval flow,
+   the employee dashboard + admin queue, and the auth wiring (provider in the
+   layout, middleware gate, server-side role checks).
+   **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-hr-portal
+   services:
+     web:
+       type: nextjs
+       path: /
+   vault:
+     AUTH_PROVIDER_SECRET_KEY: auth-provider-secret-key
+     AUTH_PROVIDER_PUBLISHABLE_KEY: auth-provider-publishable-key
+   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). 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 keys come from the `vault:` block, not committed env files.** The
+   `vault:` map injects the provider's secret + publishable keys as env vars at
+   build + runtime.
+
+## 6. Config
+
+- Create the vault items the `vault:` block references (the auth provider's
+  secret + publishable keys) — `gridctl_secrets` / vault UI. Never commit them.
+- 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. (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, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, DB + auth credentials injected by the grid / vault.

package/src/corpus/workflows/internal-tools-portal.md

@@ -0,0 +1,125 @@
+---
+name: internal-tools-portal
+when: internal tools portal, admin tools hub, back-office portal — a persistent app hosting several internal tools behind staff-only auth, with RBAC where each tool is its own route. Needs a database + auth provider → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: persistent — needs a database (Mongo) + a provider SDK auth (Clerk/Auth0) with keys from the vault, RBAC on staff records. Runtime app, async build, local edition only. Declare `needs: { database: true }` (deployer injects DATABASE_MONGODB_URL / legacy MONGODB_URL) and a `vault:` block for the auth keys. This is a BLUEPRINT — no app code ships; read AGENTS.md for the structure, then build.
+summary: Build a persistent Next.js + Mongo internal tools portal on the grid with staff-only auth (Clerk/Auth0, keys from vault:), RBAC, and each internal tool as its own route — `staff` + `toolData` + `auditLog` collections. This is a BLUEPRINT: fetch it, read AGENTS.md for the file tree + CloudGrid wiring (DATABASE_MONGODB_URL, vault keys, tool registry, deploy), then build the app under services/web/. Edition-gate first, scaffold, declare needs:{database:true} + vault: auth keys (never requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: internal-tools-portal
+
+The user wants an internal tools portal / admin tools hub / back-office portal —
+several internal tools (feature flags, refund console, data lookups, ops actions)
+living behind **staff-only auth** in one place, with **role-based access control**
+where **each tool is its own route**. Staff records, tool data, and the audit
+trail must **remember** across refresh and be shared across the team, so this is a
+**persistent runtime app** backed by the grid's shared Mongo with a provider SDK
+for auth — not a static page.
+
+This is a **blueprint**. No app code ships. Fetch the template, **read its
+`AGENTS.md` for the structure** (file tree, `staff` + `toolData` + `auditLog`
+collections, the `lib/tools.js` tool registry, CloudGrid wiring for DB +
+vault-backed auth keys, RBAC, deploy flow), then build the app following it.
+
+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, auth-gated 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** 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", "internal-tools-portal")`. 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, the tool registry, how CloudGrid injects
+the DB and vault-backed auth keys, how to wire staff-only auth + RBAC, and the
+deploy steps.
+
+## 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 under `services/web/` per `AGENTS.md` — the
+   `staff` + `toolData` + `auditLog` collections, the tool registry in
+   `lib/tools.js`, the hub (`app/page.js`) that shows only the tools the signed-in
+   staffer's roles allow, each tool as its own route (`app/tools/[tool]/`), the
+   admin user/role management, and the auth wiring (provider in the layout,
+   staff-only middleware gate, server-side role checks per tool + mutation).
+   **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-internal-tools-portal
+   services:
+     web:
+       type: nextjs
+       path: /
+   vault:
+     AUTH_PROVIDER_SECRET_KEY: auth-provider-secret-key
+     AUTH_PROVIDER_PUBLISHABLE_KEY: auth-provider-publishable-key
+   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). 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 keys come from the `vault:` block, not committed env files.** The
+   `vault:` map injects the provider's secret + publishable keys as env vars at
+   build + runtime. A tool that calls a third-party API adds one more `vault:`
+   line per secret.
+4. **RBAC is server-side.** Roles live on the `staff` Mongo record; the hub
+   hiding a card is UX only. Every tool page + API re-checks `requireRole`
+   server-side and appends mutations to `auditLog`.
+
+## 6. Config
+
+- Create the vault items the `vault:` block references (the auth provider's
+  secret + publishable keys, plus any per-tool API secrets) — `gridctl_secrets` /
+  vault UI. Never commit them.
+- 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. (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, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, DB + auth credentials injected by the grid / vault.

package/src/corpus/workflows/inventory.md

@@ -0,0 +1,101 @@
+---
+name: inventory
+when: inventory management, stock tracker, warehouse, product stock, SKU manager — a persistent app that stores items (sku, name, qty, location, reorder_at) with quantity adjustments and a low-stock flag. 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 inventory / stock tracker on the grid — an `items` collection (sku, name, qty, location, reorder_at) with add / adjust-qty / delete and a low-stock flag. 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: inventory
+
+The user wants a items app that **remembers** its
+records — they survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `items` domain
+(sku, name, qty, location, reorder_at) and a table view with add, per-row quantity adjustments (+/-), delete, and a low-stock flag.
+
+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-inventory
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "inventory")`. It is a minimal, real Next.js +
+   `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH (adjust qty)/DELETE route on an `items` collection, a
+   server-component page, and a client component.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

package/src/corpus/workflows/invoice.md

@@ -0,0 +1,101 @@
+---
+name: invoice
+when: invoice system, invoicing, billing invoices, send invoices, invoice tracker — a persistent app that stores and manages invoices (number, client, amount, status, due) with add / mark-paid / delete. 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 invoice tracker on the grid — an `invoices` collection (number, client, amount, status draft/sent/paid, due) with add / mark-paid / 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: invoice
+
+The user wants a invoices app that **remembers** its
+records — they survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `invoices` domain
+(number, client, amount, status of draft/sent/paid, due date) and a table view with add, per-row status changes (mark sent / paid), 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-invoices
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "invoice")`. It is a minimal, real Next.js +
+   `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH/DELETE route on an `invoices` collection, a
+   server-component page, and a client component.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

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

@@ -0,0 +1,101 @@
+---
+name: job-board
+when: job board, careers page, job listings, hiring board, open roles — a persistent app that stores job postings (title, company, location, type, url) with a public list and post / delete. 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 job board on the grid — a `jobs` collection (title, company, location, type, url) with a public list and post / 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: job-board
+
+The user wants a job board app that **remembers** its
+records — they survive refresh and are shared across sessions. That is a
+**runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with a `jobs` domain
+(title, company, location, type, url) and a public list with post 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-jobs
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it). The template ships this file in the **full-annotated
+   reference form** — every field present as a comment, only `name`,
+   `services.web`, and `needs.database` uncommented — so it deploys to exactly
+   those active fields.
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "job-board")`. It is a minimal, real Next.js +
+   `mongodb`-driver app under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `jobs` collection, a
+   server-component page, and a client component.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.

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.)