@cloudgrid-io/mcp 0.11.2 → 0.13.0

package/src/corpus/workflows/ai-app.md

@@ -0,0 +1,136 @@
+---
+name: ai-app
+when: chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-anything, an app that talks to an LLM / generates text with AI. Needs AI + a database → runtime → local edition.
+needs: ai, database
+deploy: runtime
+editions: local
+capabilities_note: AI chatbot — needs ai (the grid AI gateway) + a database (Mongo) for chat history. Next.js App Router app. Uses @cloudgrid-io/ai createClient().chat() with zero-config in-grid identity auth (no API key). Runtime app, async build, local edition only. Declare `needs: { ai: true, database: true }`. (RAG over your own docs needs `needs: { vector: pgvector }` — not yet available, platform issue #1545.)
+summary: Build an AI chatbot on the grid — a Next.js app that calls @cloudgrid-io/ai createClient().chat({messages}) (zero-config in-grid auth, no key) and persists the conversation to grid-shared Mongo. Edition-gate first, scaffold, put the app under services/web/, declare needs:{ai:true,database:true}, read DATABASE_MONGODB_URL lazily, deploy async, poll to a live URL.
+---
+
+# Workflow: ai-app
+
+The user wants an app that **talks to an LLM** — a chatbot, an AI assistant, a
+Q&A/support bot, an ask-me-anything. It calls the grid's AI gateway to generate
+replies and **remembers the conversation** in the grid-shared Mongo. So it needs
+two capabilities: `ai` (the gateway) and `database` (chat history). That makes it
+a **runtime app**, not a static page.
+
+Follow this recipe. Be honest that a runtime deploy is async and needs the local
+edition.
+
+## 1. Edition check FIRST (hard gate)
+
+An AI chatbot is a built + deployed container. It requires the **local edition**
+(Claude Desktop / Claude Code) or the CLI, because the grid must run the CLI and
+folder-plug your project.
+
+- **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:
+  "An AI chatbot needs the local edition (Claude Desktop/Code) or the CloudGrid
+  CLI; the hosted edition can only publish static pages." STOP the runtime path
+  here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+Persistent apps are owned entities.
+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.
+
+You then do two things: (a) write the app under **`services/web/`**, and (b) fill
+in `cloudgrid.yaml` to the shape below (`services.web` type `nextjs` + `needs: {
+ai: true, database: true }`).
+
+## 4. Wire the AI gateway + Mongo
+
+1. Set `cloudgrid.yaml` to declare the `web` service and the capabilities it
+   needs. **App code MUST live under `services/<name>/`** — `path:` is the URL
+   mount, NOT the filesystem path. A service named `web` → the CLI looks for
+   `services/web/`; files at the repo root fail with
+   `Error: Service directory not found: …/services/web`.
+   ```yaml
+   name: my-chatbot
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     ai: true
+     database: true
+   # For retrieval-augmented (RAG) over your own docs, add `needs: { vector:
+   # pgvector }` once platform issue #1545 ships — not yet available.
+   ```
+   **Declare `needs: { ai: true, database: true }`** — the canonical shape. The
+   deployer wires the AI gateway (in-grid identity) and provisions Mongo,
+   injecting `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at
+   dev-time and runtime. `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 chat wiring:
+   `gridctl_fetch("template", "ai-app")`. It is a minimal Next.js App Router chat
+   app under `services/web/`: a chat page, an API route
+   (`app/api/chat/route.js`, `export const dynamic = "force-dynamic"`) that reads
+   the user message, calls the AI gateway, persists the exchange to Mongo, and
+   returns the reply.
+3. **Call the AI gateway with `@cloudgrid-io/ai`** — zero config, no API key:
+   ```js
+   import { createClient } from "@cloudgrid-io/ai";
+   const client = createClient();                    // zero-arg, no key
+   const r = await client.chat({ messages: [{ role: "user", content: text }] });
+   const reply = r.text ?? r.content;                // reply text
+   ```
+   The SDK auto-detects the in-grid identity — **do NOT set an API key.** It only
+   works inside a deployed grid app (or under `grid dev`).
+4. **Persist the exchange to Mongo** — read `process.env.DATABASE_MONGODB_URL`
+   (falling back to the legacy `process.env.MONGODB_URL`) **lazily inside the
+   getter, never at module top level**, or `next build` fails (the module is
+   imported for route analysis before the grid injects the var). Store the user
+   message and the assistant reply so the conversation survives refresh. Never
+   hardcode a connection string; never commit a secret.
+   - (Optional) fetch `gridctl_fetch("example", "ai-app")` for a richer filled
+     reference (a themed assistant) to imitate.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally — the AI gateway and Mongo
+are wired in dev too — and send a test message before deploying. Don't require it.
+
+## 6. Config
+
+- Extra API keys / secrets (only if the app needs its own) → `gridctl_secrets`.
+- Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection var yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) and do **NOT** set an AI key — the grid injects the DB var and
+  the AI SDK auto-detects the in-grid identity.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"` with a `poll_url` / entity, 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 URL (the app URL, NOT the build/log
+  link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live chatbot URL — that is the deliverable. To iterate, re-plug
+the SAME entity (`target_entity_id`) so it updates the same URL.
+
+## Note on RAG / retrieval
+
+If the user wants the bot to answer over **their own documents** (retrieval-
+augmented generation), that needs a vector store (`needs: { vector: pgvector }`).
+That path is **not yet available** — platform issue #1545. Ship the plain
+chatbot now; add retrieval once the vector need is unblocked.
+
+Keep it honest: async build, local-edition only, AI auth and DB credentials
+provided by the grid.

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

@@ -0,0 +1,36 @@
+---
+name: api-docs
+when: API documentation, API reference, endpoint docs, REST API docs, method/params/response reference. For prose developer guides or a knowledge base, use docs-site instead.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the api-docs template, fill it with the user's endpoints, deploy it, and return the live share URL.
+---
+
+# Workflow: api-docs
+
+Detect the intent ("build me API docs / a REST API reference for X") and follow
+this recipe. For prose guides or a general docs site, use `docs-site`; use this
+one when the content is an endpoint reference. Do not ask setup questions first;
+use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "api-docs")` to load
+   the self-contained HTML API reference (sidebar endpoint list, method badges,
+   params tables, request/response code blocks, client-side filter).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The API name, base URL, and auth note.
+   - One section per endpoint: method badge (GET/POST/PUT/DELETE), path,
+     description, a params table, and request/response example blocks.
+   - The sidebar links jump to each endpoint anchor; keep ids matching.
+   - The code blocks are plain `<pre><code>` — no external highlighter or CDN.
+   - 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/api-service.md

@@ -0,0 +1,118 @@
+---
+name: api-service
+when: REST API, backend for X, API endpoint(s), CRUD API, JSON API, webhook receiver, a backend/service that stores data and isn't a full web UI. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent backend service — needs a database (Mongo). A plain Node HTTP service (type: node), not a web UI. 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 real REST/JSON API on the grid — a Node HTTP service backed by grid-shared Mongo. Edition-gate first, scaffold, put the service under services/api/, read process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: api-service
+
+The user wants a **backend API**, not a full web UI — a REST/JSON service with
+endpoints, a resource it stores and returns (a `/items` CRUD API, a webhook
+receiver, a small backend for another app). It **saves data**, so it is a
+**runtime app** backed by the grid's shared Mongo. This is the plain-service
+sibling of `app-with-data`: no Next.js, no pages — just a Node HTTP server
+speaking JSON.
+
+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)
+
+An API service is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI, because the grid must run
+the CLI and folder-plug your project.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime
+  service — hosted is inline-only and can only publish static pages. Tell the
+  user plainly: "An API service needs the local edition (Claude Desktop/Code) or
+  the CloudGrid CLI; the hosted edition can only publish static pages." STOP the
+  runtime path here (there is no useful static fallback for a backend API).
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+Persistent services are owned entities.
+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.
+
+You then do two things: (a) write the service under **`services/api/`**, and (b)
+fill in `cloudgrid.yaml` to the shape below (`services.api` type `node` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml` to declare the `api` service and the store it needs.
+   **Service code MUST live under `services/<name>/`** — `path:` is the URL
+   mount, NOT the filesystem path. A service named `api` → the CLI looks for
+   `services/api/`; files at the repo root fail with
+   `Error: Service directory not found: …/services/api`.
+   ```yaml
+   name: my-api
+   services:
+     api:
+       type: node
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — this is the
+   canonical shape. The deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at dev-time and
+   runtime. `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 server + Mongo shape:
+   `gridctl_fetch("template", "api-service")`. It is a minimal Node `http`
+   server under `services/api/`: it listens on `process.env.PORT || 8080` and
+   serves a small REST resource (`/items` GET list / POST create / DELETE by id)
+   backed by Mongo.
+3. Adapt it to the user's API (rename the resource, change the fields, add
+   routes). **Read the database from `process.env.DATABASE_MONGODB_URL`** (falling
+   back to the legacy `process.env.MONGODB_URL`) — the grid injects those env
+   vars at dev-time and runtime. Never hardcode a connection string; never commit
+   a secret.
+   - **Read the connection string LAZILY inside the request handler / a getter —
+     never at module top level, or node startup crashes** before the grid has
+     injected the var.
+   - Return clear JSON errors (`{ "error": "…" }`) with the right status codes.
+   - (Optional) fetch `gridctl_fetch("example", "api-service")` for a slightly
+     richer filled reference to imitate.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+and hit the endpoints 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` alias) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"` with a `poll_url` / entity, 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 URL (the API base URL, NOT the
+  build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live API URL — that is the deliverable. Point out the endpoints
+(e.g. `GET /items`, `POST /items`). To iterate, re-plug the SAME entity
+(`target_entity_id`) so it updates the same URL.
+
+Keep it honest: async build, local-edition only, credentials injected by the grid.

package/src/corpus/workflows/changelog.md

@@ -0,0 +1,33 @@
+---
+name: changelog
+when: changelog, release notes, what's new, product updates page, version history. Reverse-chronological entries with added/fixed/changed/removed tags.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the changelog template, fill it with the user's release entries, deploy it, and return the live share URL.
+---
+
+# Workflow: changelog
+
+Detect the intent ("build me a changelog / release notes page for X") and follow
+this recipe. Do not ask setup questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "changelog")` to load
+   the self-contained HTML changelog (reverse-chronological versioned entries with
+   tagged change items).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The product name and a short intro line.
+   - One entry per release, newest first: version, date, and a list of changes.
+   - Each change item carries a tag — set its class to `added`, `fixed`,
+     `changed`, or `removed`.
+   - 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/crm.md

@@ -0,0 +1,101 @@
+---
+name: crm
+when: CRM, contacts, leads, sales pipeline, customer manager, deal tracker — a persistent app that stores and manages contacts/leads/customers by stage. 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 CRM on the grid — a `contacts` collection (name, email, company, stage, note) with add / restage / 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: crm
+
+The user wants a contact manager / sales pipeline that **remembers** its
+contacts — a CRM 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 a `contacts` domain
+(name, email, company, stage of lead/qualified/customer, note) and a table view
+with per-row stage changes.
+
+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-crm
+   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", "crm")`. It is a minimal, real Next.js +
+   `mongodb`-driver contact manager under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH/DELETE route on a
+   `contacts` collection, a server-component page, and a client 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.**
+   - (Optional) fetch `gridctl_fetch("example", "crm")` 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/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/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/portfolio.md

@@ -0,0 +1,35 @@
+---
+name: portfolio
+when: portfolio, personal site, freelancer site, my work, showcase, resume site, developer/designer portfolio with a projects grid, about, skills, and contact. For a plain single-section link-in-bio, landing-page also works.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the portfolio template, fill it with the user's projects and bio, deploy it, and return the live share URL.
+---
+
+# Workflow: portfolio
+
+Detect the intent ("build me a portfolio / personal site to show my work") and
+follow this recipe. Reach for this over `landing-page` when the request is about
+showcasing projects with an about, skills, and contact. Do not ask setup
+questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "portfolio")` to load
+   the self-contained HTML portfolio (hero, about, skills, projects grid,
+   contact).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The person's name, role/title, and short intro.
+   - The about paragraph and the skills (one pill each).
+   - One card per project: title, short description, tags, optional link.
+   - The contact links (email as a `mailto:`, plus optional profile links).
+   - 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/saas-marketing.md

@@ -0,0 +1,37 @@
+---
+name: saas-marketing
+when: SaaS marketing site, product marketing page, features and pricing page, multi-section product site with pricing tiers, testimonials, and FAQ. For a simpler single-message page, use landing-page instead.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the saas-marketing template, fill it with the user's product content, deploy it, and return the live share URL.
+---
+
+# Workflow: saas-marketing
+
+Detect the intent ("build me a SaaS marketing site / product page with pricing")
+and follow this recipe. This is the richer sibling of `landing-page` — reach for
+it when the request calls for pricing tiers, testimonials, and an FAQ, not just a
+hero. For a plain single-section landing page, use `landing-page`. Do not ask
+setup questions first; use sensible defaults and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "saas-marketing")` to
+   load the self-contained HTML marketing site.
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The product name, tagline, and hero eyebrow/headline/subheadline.
+   - The call-to-action label and (optional) target.
+   - One block per feature (title + short description).
+   - The three pricing plans (name, price, period, feature list). The middle
+     plan is marked "Most popular".
+   - The testimonial quotes and the FAQ question/answer pairs.
+   - 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.