@cloudgrid-io/mcp 0.12.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {

package/src/corpus/capability-map.md

@@ -13,18 +13,50 @@ cloudgrid.yaml schema (every field, the `needs:` injection table, the
 requires-vs-needs caveat, validation rules), fetch the companion reference:
 `gridctl_fetch("doc", "cloudgrid-yaml")`.
 
-## The 8 templates
+## The 58 templates
 
 | Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
 |---|---|---|---|---|
-| landing page, marketing/product/hero page, coming-soon, waitlist, pricing, portfolio, link-in-bio, event page | `landing-page` | none | inspiration (instant) | all |
+| landing page, marketing/product/hero page, coming-soon, link-in-bio, event page — a single-section page | `landing-page` | none | inspiration (instant) | all |
+| SaaS marketing site, product marketing page, features + pricing page — multi-section with pricing tiers, testimonials, FAQ | `saas-marketing` | none | inspiration (instant) | all |
+| documentation site, docs, developer docs, guide, manual, knowledge base — prose docs with sidebar + search | `docs-site` | none | inspiration (instant) | all |
+| API documentation, API reference, endpoint docs, REST API docs — method badges, params tables, request/response examples | `api-docs` | none | inspiration (instant) | all |
+| status page, service status, uptime page, incident history, is-it-down page — display-only, status baked in | `status-page` | none | inspiration (instant) | all |
+| changelog, release notes, what's new, product updates, version history | `changelog` | none | inspiration (instant) | all |
+| portfolio, personal site, freelancer site, my work, showcase — projects grid + about + skills + contact | `portfolio` | none | inspiration (instant) | all |
+| waitlist, coming soon, early access, join the list, launch page — email capture form (form is static; storing signups needs a runtime crud-app) | `waitlist` | none | inspiration (instant) | all |
 | calculator, converter, generator, timer, quiz, interactive tool, mini-app, widget — computed client-side, no saved data | `web-app` | none | inspiration (instant) | all |
 | dashboard, metrics, KPIs, stats page, status board, charts, analytics view — display-only, static data baked in | `dashboard` | none | inspiration (instant) | all |
 | report, one-pager, summary, brief, whitepaper, case study, formatted document | `report` | none | inspiration (instant) | all |
 | slides, deck, pitch, presentation, slideshow | `presentation` (dir: `deck`) | none | inspiration (instant) | all |
+| product launch page, launch announcement, new product page, "we just launched" | `product-launch` | none | inspiration (instant) | all |
+| company website, business site, corporate site, about-us site, small-business homepage | `company-website` | none | inspiration (instant) | all |
 | to-do, task list, notes app, guestbook, CRUD app, a form that SAVES/STORES submissions, anything that PERSISTS data or shares state across users/sessions, sign-in/accounts | `app-with-data` | `database: true` | runtime (async, poll) | local |
+| CRM, contacts, leads, sales pipeline, customer manager, deal tracker | `crm` | `database: true` | runtime (async, poll) | local |
+| kanban board, task board, trello-style board, workflow columns | `kanban` | `database: true` | runtime (async, poll) | local |
+| task manager, to-do app (richer than the app-with-data starter), task list with due dates/priorities | `task-manager` | `database: true` | runtime (async, poll) | local |
+| admin dashboard, admin panel, back-office, CRUD admin, manage records | `admin-dashboard` | `database: true` | runtime (async, poll) | local |
+| invoice system, invoicing, billing invoices, send invoices, invoice tracker | `invoice` | `database: true` | runtime (async, poll) | local |
+| inventory management, stock tracker, warehouse, product stock, SKU manager | `inventory` | `database: true` | runtime (async, poll) | local |
+| job board, careers page, job listings, hiring board, open roles | `job-board` | `database: true` | runtime (async, poll) | local |
+| ticket system, support tickets, helpdesk, issue tracker, support queue | `ticket-system` | `database: true` | runtime (async, poll) | local |
 | 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 | `api-service` | `database: true` | runtime (async, poll) | local |
 | chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-anything, an app that talks to an LLM / generates text with AI | `ai-app` | `ai: true, database: true` | runtime (async, poll) | local |
+| blog, CMS, content site with posts, publishing platform, articles | `blog-cms` | `database: true` | runtime (async, poll) | local |
+| product catalog, product listings, catalog site, browse products (no checkout) | `product-catalog` | `database: true` | runtime (async, poll) | local |
+| analytics dashboard, usage analytics, metrics from stored events | `analytics-dashboard` | `database: true` | runtime (async, poll) | local |
+| monitoring dashboard, service health board, uptime/incident monitor (data-backed) | `monitoring-dashboard` | `database: true` | runtime (async, poll) | local |
+| financial dashboard, finance metrics, P&L, cashflow board | `financial-dashboard` | `database: true` | runtime (async, poll) | local |
+| expense tracker, spending log, budget tracker, expense report | `expense-tracker` | `database: true` | runtime (async, poll) | local |
+| time tracking, timesheet, hours logger, billable hours | `time-tracking` | `database: true` | runtime (async, poll) | local |
+| event board, events listing, community events, meetup board | `event-board` | `database: true` | runtime (async, poll) | local |
+| directory, business directory, member directory, listings directory | `directory` | `database: true` | runtime (async, poll) | local |
+| quiz, quiz platform, trivia, assessment, questionnaire | `quiz-platform` | `database: true` | runtime (async, poll) | local |
+| API dashboard, API usage dashboard, API requests monitor | `api-dashboard` | `database: true` | runtime (async, poll) | local |
+| feature request board, feedback board, roadmap voting, idea board | `feature-request-board` | `database: true` | runtime (async, poll) | local |
+| revenue dashboard, sales dashboard, MRR/revenue view | `revenue-dashboard` | `database: true` | runtime (async, poll) | local |
+| property listings, real estate site, rentals/homes listings | `property-listings` | `database: true` | runtime (async, poll) | local |
+| project management, projects and tasks tracker, team project board | `project-management` | `database: true` | runtime (async, poll) | local |
 
 **Rule of thumb:** if the app must SAVE/remember data, share state across
 users/sessions, log in, or store submissions → it is persistent → runtime, local
@@ -32,6 +64,15 @@ edition. Pick by shape: a full web UI → `app-with-data`; a plain backend/JSON
 (no UI) → `api-service`; an app that talks to an LLM → `ai-app` (adds `ai:`).
 Otherwise a static template deploys instantly anywhere.
 
+**The DB-CRUD family.** `crm`, `kanban`, `task-manager`, `admin-dashboard`,
+`invoice`, `inventory`, `job-board`, and `ticket-system` all share the exact
+`app-with-data` shape (nextjs + `needs: { database: true }`, app under
+`services/web/`, lazy Mongo getter, force-dynamic App-Router routes) — they
+differ only by domain schema + UI. Match the request to the closest one by its
+`when:`; if it is a bare to-do or generic "save this data" with no specific
+domain, use `app-with-data` (the minimal reference). Deploy path is identical for
+all of them.
+
 ## Held / pending platform (not yet buildable)
 
 Two more archetypes are designed but blocked on platform work — the LLM should
@@ -42,6 +83,45 @@ know they are coming but must NOT author them yet:
 | scheduled task, cron job, "run every day/hour", periodic worker | a `type: cron` service (`schedule`, `timezone`) | **HELD** — platform issue #1543 (cron entities crash the online-check). Do not build. |
 | RAG chatbot, "answer over my own docs", semantic search, retrieval-augmented Q&A | `ai-app` + `needs: { vector: pgvector }` | **HELD** — platform issue #1545 (pgvector crashes the deploy). Ship the plain `ai-app` (no vector) for now. |
 
+## Blueprints (structure + cloudgrid.yaml; adapt the app — some pending platform support)
+
+A **blueprint** is a heavier archetype that ships **structure + a correct
+`cloudgrid.yaml` + an `AGENTS.md`** rather than fill-in-the-blanks app code
+(`kind: blueprint` in the workflow frontmatter). Fetch the workflow, fetch the
+template, **read its `AGENTS.md`** for the file tree / collections / CloudGrid
+wiring (DB injection, `vault:` secrets for auth + Stripe, deploy), then BUILD the
+app under `services/web/` following it. All are persistent Next.js + Mongo →
+runtime, async build, **local edition only**. Auth/payment secrets map through a
+`vault:` block → env vars (never `requires:`).
+
+| Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
+|---|---|---|---|---|
+| online store, e-commerce store, shop with checkout, sell products online | `online-store` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| marketplace, multi-vendor platform, two-sided marketplace | `marketplace` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| HR portal, employee portal, HR management, leave/PTO system | `hr-portal` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| ERP, enterprise resource planning, integrated multi-module business system | `erp` | `database: true` (+ auth/Stripe via `vault:`) | runtime (async, poll) | local |
+| forum, discussion board, community forum, threaded discussions | `forum` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| membership site, paid community, subscriber content, gated content | `membership-site` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| course platform, sell online courses, Teachable-style | `course-platform` | `database: true` (+ Stripe/auth via `vault:`) | runtime (async, poll) | local |
+| LMS, learning management system, training platform | `lms` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| subscription management, manage subscriptions, self-serve plans/billing | `subscription-management` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| billing dashboard, invoicing and payments dashboard, SaaS billing | `billing-dashboard` | `database: true` (+ Stripe via `vault:`) | runtime (async, poll) | local |
+| internal tools portal, admin tools hub, back-office portal | `internal-tools-portal` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| approval workflow, request approvals, multi-step approval system | `approval-workflow` | `database: true` (+ auth via `vault:`) | runtime (async, poll) | local |
+| booking system, reservations, appointment booking, scheduling | `booking-system` | `database: true` (+ Stripe/auth via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| calendar scheduler, team calendar, scheduling app, meeting scheduler | `calendar-scheduler` | `database: true` (+ optional auth/Stripe via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| appointment booking, clinic/salon booking, appointment scheduler | `appointment-booking` | `database: true` (+ auth/Stripe via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| restaurant website with reservations, table booking, restaurant site | `restaurant-reservations` | `database: true` (+ Stripe/email via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| travel booking portal, trip booking, flights/hotels booking, travel reservations | `travel-booking` | `database: true` (+ Stripe/auth via `vault:`); reminder **cron pending #1543** | runtime (async, poll) | local |
+| RAG, ask my docs, knowledge base chatbot, retrieval-augmented search over documents | `ai-knowledge-base` | `ai: true, database: true`; ideal `vector: pgvector` **pending #1545** (store embeddings in Mongo + cosine-rank until it lands) | runtime (async, poll) | local |
+
+The booking family (`booking-system`, `calendar-scheduler`, `appointment-booking`,
+`restaurant-reservations`, `travel-booking`) is fully buildable today **minus**
+the reminder cron — a `type: cron` service is HELD on platform issue **#1543**, so
+ship without it. `ai-knowledge-base` builds today on the AI Gateway + Mongo; its
+ideal `needs: { vector: pgvector }` embedding store is HELD on **#1545**, so store
+chunks in Mongo and cosine-rank in-app until it lands.
+
 ## The full `needs:` vocabulary (the whole menu)
 
 `needs:` is a MAP declaring infrastructure capabilities. Values are `true` or an

package/src/corpus/examples/crm/index.md

@@ -0,0 +1,273 @@
+# Example: crm — "Sales Pipeline CRM"
+
+A filled reference imitating the `crm` template: a persistent sales-pipeline CRM.
+Same stack (Next.js App Router + the `mongodb` driver, grid-shared Mongo via
+`process.env.DATABASE_MONGODB_URL`). Contacts have a `name`, `email`, `company`,
+a `stage` (lead / qualified / customer) and a `note`; the table lets you add a
+contact, change its stage inline, and delete it.
+
+Data persists in the grid-shared Mongo, so the whole team sees the same pipeline
+across sessions and refresh.
+
+**Same three proven rules as the template:** (1) app code lives under
+**`services/web/`** (the service name, NOT the repo root — `path:` is the URL
+mount); (2) the DB connection string is read **lazily inside the `getDb`
+getter**, never at module top level (a top-level read fails `next build`); (3)
+the datastore is declared with the canonical **`needs: { database: true }`** —
+the deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+`MONGODB_URL` alias). Don't use the deprecated `requires:` alias.
+
+## cloudgrid.yaml
+
+```yaml
+# `needs: { database: true }` is canonical: the deployer provisions Mongo and
+# injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias). `requires:`
+# is the deprecated v1 alias — don't mix the two (the validator rejects it).
+name: sales-pipeline-crm
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+## services/web/package.json
+
+```json
+{
+  "name": "sales-pipeline-crm",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": { "dev": "next dev", "build": "next build", "start": "next start" },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/web/lib/db.js
+
+```js
+// Cached Mongo client. The grid injects DATABASE_MONGODB_URL (plus the legacy
+// MONGODB_URL alias) at dev + runtime. Read the canonical var first, fall back to
+// the legacy alias. Resolve it LAZILY inside the getter — a top-level read fails
+// `next build`.
+import { MongoClient } from "mongodb";
+
+function clientPromise() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it — run `grid dev` " +
+        "locally or deploy with `grid plug`. Do not set it by hand.",
+    );
+  }
+  if (!globalThis.__mongoClientPromise) {
+    globalThis.__mongoClientPromise = new MongoClient(uri).connect();
+  }
+  return globalThis.__mongoClientPromise;
+}
+
+export async function getDb() {
+  return (await clientPromise()).db();
+}
+```
+
+## services/web/app/api/contacts/route.js
+
+```js
+import { NextResponse } from "next/server";
+import { ObjectId } from "mongodb";
+import { getDb } from "../../../lib/db.js";
+
+export const dynamic = "force-dynamic";
+
+const STAGES = ["lead", "qualified", "customer"];
+
+async function contacts() {
+  return (await getDb()).collection("contacts");
+}
+
+function shape(c) {
+  return {
+    id: c._id.toString(),
+    name: c.name || "",
+    email: c.email || "",
+    company: c.company || "",
+    stage: STAGES.includes(c.stage) ? c.stage : "lead",
+    note: c.note || "",
+  };
+}
+
+// GET /api/contacts — list the pipeline.
+export async function GET() {
+  const col = await contacts();
+  const items = await col.find({}).sort({ createdAt: -1 }).toArray();
+  return NextResponse.json(items.map(shape));
+}
+
+// POST /api/contacts — add a contact. Body: { name, email, company, note }.
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const name = typeof body.name === "string" ? body.name.trim() : "";
+  if (!name) return NextResponse.json({ error: "name is required" }, { status: 400 });
+  const doc = {
+    name,
+    email: typeof body.email === "string" ? body.email.trim() : "",
+    company: typeof body.company === "string" ? body.company.trim() : "",
+    stage: "lead",
+    note: typeof body.note === "string" ? body.note.trim() : "",
+    createdAt: new Date(),
+  };
+  const col = await contacts();
+  const res = await col.insertOne(doc);
+  return NextResponse.json({ id: res.insertedId.toString(), ...doc }, { status: 201 });
+}
+
+// PATCH /api/contacts — move a contact along the pipeline. Body: { id, stage }.
+export async function PATCH(request) {
+  const body = await request.json().catch(() => ({}));
+  const { id, stage } = body;
+  if (!id || !ObjectId.isValid(id) || !STAGES.includes(stage)) {
+    return NextResponse.json({ error: "valid id and stage required" }, { status: 400 });
+  }
+  const col = await contacts();
+  await col.updateOne({ _id: new ObjectId(id) }, { $set: { stage } });
+  return NextResponse.json({ ok: true });
+}
+
+// DELETE /api/contacts?id=<id>
+export async function DELETE(request) {
+  const id = new URL(request.url).searchParams.get("id");
+  if (!id || !ObjectId.isValid(id)) {
+    return NextResponse.json({ error: "valid id is required" }, { status: 400 });
+  }
+  const col = await contacts();
+  await col.deleteOne({ _id: new ObjectId(id) });
+  return NextResponse.json({ ok: true });
+}
+```
+
+## services/web/app/page.js
+
+```js
+import { getDb } from "../lib/db.js";
+import ContactManager from "./contact-manager.js";
+
+export const dynamic = "force-dynamic";
+
+const STAGES = ["lead", "qualified", "customer"];
+
+async function listContacts() {
+  const items = await (await getDb())
+    .collection("contacts")
+    .find({})
+    .sort({ createdAt: -1 })
+    .toArray();
+  return items.map((c) => ({
+    id: c._id.toString(),
+    name: c.name || "",
+    email: c.email || "",
+    company: c.company || "",
+    stage: STAGES.includes(c.stage) ? c.stage : "lead",
+    note: c.note || "",
+  }));
+}
+
+export default async function Page() {
+  const contacts = await listContacts();
+  return (
+    <main>
+      <h1>Sales Pipeline</h1>
+      <p className="hint">Shared across the team — persisted in grid Mongo.</p>
+      <ContactManager initialContacts={contacts} />
+    </main>
+  );
+}
+```
+
+## services/web/app/contact-manager.js
+
+```js
+"use client";
+import { useState } from "react";
+
+const STAGES = ["lead", "qualified", "customer"];
+const LABELS = { lead: "Lead", qualified: "Qualified", customer: "Customer" };
+
+export default function ContactManager({ initialContacts }) {
+  const [contacts, setContacts] = useState(initialContacts);
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [company, setCompany] = useState("");
+
+  async function add(e) {
+    e.preventDefault();
+    if (!name.trim()) return;
+    const res = await fetch("/api/contacts", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name, email, company }),
+    });
+    if (res.ok) { setContacts((p) => [await res.json(), ...p]); setName(""); setEmail(""); setCompany(""); }
+  }
+
+  async function setStage(id, stage) {
+    const res = await fetch("/api/contacts", {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id, stage }),
+    });
+    if (res.ok) setContacts((p) => p.map((c) => (c.id === id ? { ...c, stage } : c)));
+  }
+
+  async function remove(id) {
+    const res = await fetch(`/api/contacts?id=${encodeURIComponent(id)}`, { method: "DELETE" });
+    if (res.ok) setContacts((p) => p.filter((c) => c.id !== id));
+  }
+
+  return (
+    <div>
+      <form onSubmit={add} className="row">
+        <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Name" />
+        <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
+        <input value={company} onChange={(e) => setCompany(e.target.value)} placeholder="Company" />
+        <button type="submit">Add</button>
+      </form>
+      <table>
+        <thead>
+          <tr><th>Name</th><th>Email</th><th>Company</th><th>Stage</th><th></th></tr>
+        </thead>
+        <tbody>
+          {contacts.map((c) => (
+            <tr key={c.id}>
+              <td>{c.name}</td>
+              <td>{c.email}</td>
+              <td>{c.company}</td>
+              <td>
+                <select value={c.stage} onChange={(e) => setStage(c.id, e.target.value)}>
+                  {STAGES.map((s) => <option key={s} value={s}>{LABELS[s]}</option>)}
+                </select>
+              </td>
+              <td><button type="button" onClick={() => remove(c.id)}>Delete</button></td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- Deploy the same way as the template: `grid dev` locally, `grid plug` to deploy
+  (async — poll status to a live URL). Re-plug the same entity to keep one URL.
+- The only store this needs is Mongo (`needs: { database: true }`). Add
+  `cache: true` to `needs:` only for caching/sessions you actually use.
+- All app code lives under `services/web/`; the connection is read lazily inside
+  `getDb`, never at module top level.

package/src/corpus/examples/kanban/index.md

@@ -0,0 +1,256 @@
+# Example: kanban — "Workflow Board"
+
+A filled reference imitating the `kanban` template: a persistent trello-style
+board. Same stack (Next.js App Router + the `mongodb` driver, grid-shared Mongo
+via `process.env.DATABASE_MONGODB_URL`). Cards have a `title`, a `column` (todo /
+doing / done) and an `order`; you add a card to the first column, move it between
+columns, and delete it.
+
+Data persists in the grid-shared Mongo, so the whole team sees the same board
+across sessions and refresh.
+
+**Same three proven rules as the template:** (1) app code lives under
+**`services/web/`** (the service name, NOT the repo root — `path:` is the URL
+mount); (2) the DB connection string is read **lazily inside the `getDb`
+getter**, never at module top level (a top-level read fails `next build`); (3)
+the datastore is declared with the canonical **`needs: { database: true }`** —
+the deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+`MONGODB_URL` alias). Don't use the deprecated `requires:` alias.
+
+## cloudgrid.yaml
+
+```yaml
+# `needs: { database: true }` is canonical: the deployer provisions Mongo and
+# injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias). `requires:`
+# is the deprecated v1 alias — don't mix the two (the validator rejects it).
+name: workflow-board
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+## services/web/package.json
+
+```json
+{
+  "name": "workflow-board",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": { "dev": "next dev", "build": "next build", "start": "next start" },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/web/lib/db.js
+
+```js
+// Cached Mongo client. The grid injects DATABASE_MONGODB_URL (plus the legacy
+// MONGODB_URL alias) at dev + runtime. Read the canonical var first, fall back to
+// the legacy alias. Resolve it LAZILY inside the getter — a top-level read fails
+// `next build`.
+import { MongoClient } from "mongodb";
+
+function clientPromise() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "DATABASE_MONGODB_URL is not set. The grid injects it — run `grid dev` " +
+        "locally or deploy with `grid plug`. Do not set it by hand.",
+    );
+  }
+  if (!globalThis.__mongoClientPromise) {
+    globalThis.__mongoClientPromise = new MongoClient(uri).connect();
+  }
+  return globalThis.__mongoClientPromise;
+}
+
+export async function getDb() {
+  return (await clientPromise()).db();
+}
+```
+
+## services/web/app/api/cards/route.js
+
+```js
+import { NextResponse } from "next/server";
+import { ObjectId } from "mongodb";
+import { getDb } from "../../../lib/db.js";
+
+export const dynamic = "force-dynamic";
+
+const COLUMNS = ["todo", "doing", "done"];
+
+async function cards() {
+  return (await getDb()).collection("cards");
+}
+
+function shape(c) {
+  return {
+    id: c._id.toString(),
+    title: c.title || "",
+    column: COLUMNS.includes(c.column) ? c.column : "todo",
+    order: typeof c.order === "number" ? c.order : 0,
+  };
+}
+
+// GET /api/cards — list the board, ordered.
+export async function GET() {
+  const col = await cards();
+  const items = await col.find({}).sort({ order: 1, createdAt: 1 }).toArray();
+  return NextResponse.json(items.map(shape));
+}
+
+// POST /api/cards — add a card to the first column. Body: { title }.
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const title = typeof body.title === "string" ? body.title.trim() : "";
+  if (!title) return NextResponse.json({ error: "title is required" }, { status: 400 });
+  const doc = { title, column: "todo", order: Date.now(), createdAt: new Date() };
+  const col = await cards();
+  const res = await col.insertOne(doc);
+  return NextResponse.json({ id: res.insertedId.toString(), ...doc }, { status: 201 });
+}
+
+// PATCH /api/cards — move a card to another column. Body: { id, column }.
+export async function PATCH(request) {
+  const body = await request.json().catch(() => ({}));
+  const { id, column } = body;
+  if (!id || !ObjectId.isValid(id) || !COLUMNS.includes(column)) {
+    return NextResponse.json({ error: "valid id and column required" }, { status: 400 });
+  }
+  const col = await cards();
+  await col.updateOne({ _id: new ObjectId(id) }, { $set: { column } });
+  return NextResponse.json({ ok: true });
+}
+
+// DELETE /api/cards?id=<id>
+export async function DELETE(request) {
+  const id = new URL(request.url).searchParams.get("id");
+  if (!id || !ObjectId.isValid(id)) {
+    return NextResponse.json({ error: "valid id is required" }, { status: 400 });
+  }
+  const col = await cards();
+  await col.deleteOne({ _id: new ObjectId(id) });
+  return NextResponse.json({ ok: true });
+}
+```
+
+## services/web/app/page.js
+
+```js
+import { getDb } from "../lib/db.js";
+import Board from "./board.js";
+
+export const dynamic = "force-dynamic";
+
+const COLUMNS = ["todo", "doing", "done"];
+
+async function listCards() {
+  const items = await (await getDb())
+    .collection("cards")
+    .find({})
+    .sort({ order: 1, createdAt: 1 })
+    .toArray();
+  return items.map((c) => ({
+    id: c._id.toString(),
+    title: c.title || "",
+    column: COLUMNS.includes(c.column) ? c.column : "todo",
+    order: typeof c.order === "number" ? c.order : 0,
+  }));
+}
+
+export default async function Page() {
+  const cards = await listCards();
+  return (
+    <main>
+      <h1>Workflow Board</h1>
+      <p className="hint">Shared across the team — persisted in grid Mongo.</p>
+      <Board initialCards={cards} />
+    </main>
+  );
+}
+```
+
+## services/web/app/board.js
+
+```js
+"use client";
+import { useState } from "react";
+
+const COLUMNS = ["todo", "doing", "done"];
+const LABELS = { todo: "To do", doing: "Doing", done: "Done" };
+
+export default function Board({ initialCards }) {
+  const [cards, setCards] = useState(initialCards);
+  const [title, setTitle] = useState("");
+
+  async function add(e) {
+    e.preventDefault();
+    if (!title.trim()) return;
+    const res = await fetch("/api/cards", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ title }),
+    });
+    if (res.ok) { setCards((p) => [...p, await res.json()]); setTitle(""); }
+  }
+
+  async function move(id, column) {
+    const res = await fetch("/api/cards", {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id, column }),
+    });
+    if (res.ok) setCards((p) => p.map((c) => (c.id === id ? { ...c, column } : c)));
+  }
+
+  async function remove(id) {
+    const res = await fetch(`/api/cards?id=${encodeURIComponent(id)}`, { method: "DELETE" });
+    if (res.ok) setCards((p) => p.filter((c) => c.id !== id));
+  }
+
+  return (
+    <div>
+      <form onSubmit={add} className="row">
+        <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Add a card…" />
+        <button type="submit">Add</button>
+      </form>
+      <div className="board">
+        {COLUMNS.map((column) => (
+          <section key={column}>
+            <h2>{LABELS[column]}</h2>
+            {cards.filter((c) => c.column === column).map((c) => (
+              <article key={c.id} className="card">
+                <span className="title">{c.title}</span>
+                <div className="moves">
+                  {COLUMNS.filter((o) => o !== column).map((o) => (
+                    <button key={o} type="button" onClick={() => move(c.id, o)}>→ {LABELS[o]}</button>
+                  ))}
+                  <button type="button" onClick={() => remove(c.id)}>Delete</button>
+                </div>
+              </article>
+            ))}
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Notes
+
+- Deploy the same way as the template: `grid dev` locally, `grid plug` to deploy
+  (async — poll status to a live URL). Re-plug the same entity to keep one URL.
+- The only store this needs is Mongo (`needs: { database: true }`). Add
+  `cache: true` to `needs:` only for caching/sessions you actually use.
+- All app code lives under `services/web/`; the connection is read lazily inside
+  `getDb`, never at module top level.