@cloudgrid-io/mcp 0.12.0 → 0.13.0

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

@@ -0,0 +1,102 @@
+---
+name: admin-dashboard
+when: admin dashboard, admin panel, back-office, CRUD admin, manage records — a persistent admin over one or two Mongo collections with a metrics header + management 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 admin panel on the grid — a couple of resource collections (e.g. users, orders) with a metrics header (counts + revenue) and a management 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: admin-dashboard
+
+The user wants an admin panel / back-office to **manage records** — a couple of
+resources (e.g. users and orders) with a metrics header (counts, revenue) and a
+management table (add / delete), all persisted across refresh and shared across
+sessions. That is a **runtime app** backed by the grid's shared Mongo, not a
+static dashboard page. It is the same proven shape as `app-with-data`, generalised
+over one or two Mongo collections. (For a display-only metrics page with baked-in
+data, use the static `dashboard` template instead.)
+
+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-admin
+   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", "admin-dashboard")`. It is a minimal, real Next.js
+   + `mongodb`-driver admin panel under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, two App-Router GET/POST/DELETE routes (`users` and
+   `orders`), a server-component page that computes a metrics header, and a
+   reusable client management table.
+3. Adapt it (rename or replace the resource collections, change fields, adjust
+   the metrics). **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/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/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.

package/src/corpus/workflows/status-page.md

@@ -0,0 +1,35 @@
+---
+name: status-page
+when: status page, service status, uptime page, incident history, is-it-down page, system status board. Display-only — status is baked into the page, no live monitoring.
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure, status baked into the page. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the status-page template, fill it with the user's components and incidents, deploy it, and return the live share URL.
+---
+
+# Workflow: status-page
+
+Detect the intent ("build me a status page / uptime page for X") and follow this
+recipe. This is a display-only static page — the status is baked into the markup,
+there is no live polling. Do not ask setup questions first; use sensible defaults
+and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "status-page")` to load
+   the self-contained HTML status page (overall banner, component list with
+   up/degraded/down pills, per-component uptime bars, incident history).
+2. **Fill the template.** Replace the placeholders with the user's content:
+   - The overall banner text and its state class (`ok` / `degraded` / `down`).
+   - One row per component: name, a status pill, and the 90-day uptime bar. Mark
+     any non-ok bar segments with class `degraded` or `down`.
+   - The incident history entries: date, title, state, and a short note.
+   - 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/task-manager.md

@@ -0,0 +1,101 @@
+---
+name: task-manager
+when: task manager, to-do app (richer than the app-with-data starter), task list with due dates/priorities, complete-toggle + filter — a persistent task app that sticks 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 task manager on the grid — a `tasks` collection (title, done, due, priority) with a complete-toggle, active/done filter, add/delete. Richer than the bare app-with-data to-do. 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: task-manager
+
+The user wants a task manager richer than the bare `app-with-data` to-do starter
+— tasks with due dates and priorities, a complete-toggle, and an active/done
+filter, all of which **stick** across 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 `tasks` domain (title,
+done, due, priority of low/medium/high). (For the bare-minimum in-memory to-do,
+use `app-with-data` instead.)
+
+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-tasks
+   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", "task-manager")`. It is a minimal, real Next.js +
+   `mongodb`-driver task manager under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/PATCH/DELETE route on a
+   `tasks` collection (PATCH toggles done), a server-component page, and a client
+   list with an active/done filter.
+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.