@cloudgrid-io/mcp 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.12.0",
+  "version": "0.13.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,16 +13,27 @@ 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 19 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 |
 | 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 |
 | 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 |
 
@@ -32,6 +43,14 @@ 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`, and `admin-dashboard`
+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 five.
+
 ## Held / pending platform (not yet buildable)
 
 Two more archetypes are designed but blocked on platform work — the LLM should

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.

package/src/corpus/templates/admin-dashboard/README.md

@@ -0,0 +1,75 @@
+# admin-dashboard template — persistent Next.js + Mongo admin panel
+
+A real, deployable back-office. It manages two generic resources (`users` and
+`orders`) in the grid-shared MongoDB, so records survive refresh and are shared
+across users/sessions. Same proven shape as `app-with-data`, adapted to a
+metrics header (counts + revenue) over a couple of collections plus a management
+table with add/delete.
+
+## How the grid gives you a database
+
+You do **not** provision a database or set a connection string. In
+`cloudgrid.yaml` you declare `needs: { database: true }`, and the grid:
+
+- provisions shared Mongo for the app, and
+- injects the connection string as the **`DATABASE_MONGODB_URL`** environment
+  variable (plus the legacy `MONGODB_URL` alias) — at dev-time (`grid dev`) and
+  at runtime (after `grid plug`).
+
+The app reads it via `process.env.DATABASE_MONGODB_URL` (with a legacy
+`process.env.MONGODB_URL` fallback) in `services/web/lib/db.js` — **lazily,
+inside the `getDb` getter, never at module top level** (a top-level read fails
+`next build`, which imports the module for route analysis before the grid injects
+the var). Never hardcode a connection string; never commit a secret.
+
+> **Declare `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 the combination).
+
+## Service layout
+
+App code lives under **`services/web/`**, not the template root. `path:` in
+`cloudgrid.yaml` is the URL mount, not the filesystem path — the service named
+`web` means the CLI looks for `services/web/`. Files at the root fail with
+`Error: Service directory not found: …/services/web`.
+
+## Run locally
+
+```bash
+npm install
+grid dev          # runs Next.js with DATABASE_MONGODB_URL injected against dev Mongo
+```
+
+## Deploy
+
+```bash
+grid plug         # builds + deploys the folder (async — poll status until live)
+```
+
+A runtime deploy is asynchronous: `plug` returns `status: building`; poll status
+until the app is live, then use the returned live URL. Re-plug the same entity
+to update the same URL.
+
+## File tree
+
+```
+cloudgrid.yaml                          # name + services.web (nextjs) + needs: { database: true }
+services/web/package.json               # next, react, react-dom, mongodb driver only
+services/web/lib/db.js                  # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
+services/web/app/layout.js              # root layout + inline CSS
+services/web/app/page.js                # server component: reads users + orders, computes metrics
+services/web/app/resource-table.js      # generic client table (POST add / DELETE remove), reused per resource
+services/web/app/api/users/route.js     # GET / POST / DELETE on the users collection
+services/web/app/api/orders/route.js    # GET / POST / DELETE on the orders collection
+```
+
+## Adapt it
+
+- Rename or replace the `users` / `orders` collections and their routes with
+  your own resources.
+- Add or change fields by editing the `columns` config passed to `ResourceTable`
+  in `services/web/app/page.js` and the matching route's document shape.
+- Add PATCH (edit) or extra metrics as the panel grows.
+- Add `cache: true` to `needs:` only if you actually need Redis.

package/src/corpus/templates/admin-dashboard/cloudgrid.yaml

@@ -0,0 +1,15 @@
+# Rename this app. The grid injects the DB connection string as an environment
+# variable at runtime — do NOT set it yourself, and never commit a connection
+# string or secret.
+#
+# `needs: { database: true }` is the canonical, recommended 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).
+name: my-admin
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true