@cloudgrid-io/mcp 0.11.2 → 0.12.0

package/src/corpus/templates/api-service/index.md

@@ -0,0 +1,225 @@
+# Template: api-service (Node HTTP + Mongo REST API)
+
+A minimal but real, deployable backend API. A plain Node `http` server (no web
+UI, no framework) serving a small REST resource (`/items`) backed by the
+grid-shared MongoDB. Data survives refresh and is shared across sessions. This is
+the plain-service sibling of `app-with-data` — use it when the user wants a
+backend/API, not a full web app.
+
+**Key rules (all proven by a real end-to-end deploy):**
+
+1. **Service code MUST live under `services/<name>/`, not the repo/template
+   root.** `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
+   The service named `api` → the CLI looks for `services/api/`. Files at the root
+   fail with `Error: Service directory not found: …/services/api`.
+2. **Read the DB connection string LAZILY (inside the getter), never at module
+   top level.** The grid injects it as the `DATABASE_MONGODB_URL` environment
+   variable (plus the legacy `MONGODB_URL` alias) at dev-time and runtime; the
+   service reads `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`
+   inside `getClient`. A top-level `const uri = process.env.DATABASE_MONGODB_URL;
+   if (!uri) throw` crashes node startup before the grid injects the var. Never
+   hardcode a connection string; never commit a secret.
+3. **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). `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).
+4. **Listen on `process.env.PORT || 8080`.** The grid injects `PORT`; the `8080`
+   default is for local runs.
+
+Write these files into the scaffolded app folder — the service code goes under
+`services/api/` — adapt the resource/fields to the user's API, then `grid dev`
+(local) / `grid plug` (deploy, async — poll to a live URL).
+
+## File tree
+
+```
+cloudgrid.yaml                 # name + services.api (node) + needs: { database: true }
+services/api/package.json      # type: module, main src/index.js, mongodb driver only
+services/api/src/index.js      # Node http server on PORT||8080; /items GET/POST/DELETE on Mongo
+```
+
+## cloudgrid.yaml
+
+```yaml
+# Rename this service. 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).
+#
+# This is a plain Node HTTP service (type: node), not a web UI. Service code lives
+# under services/api/ — `path:` is the URL mount, not the filesystem path.
+name: my-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true
+```
+
+> **Capability:** this template's need is `database: true`. The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias), so a service reading either var works. `requires:` is the
+> deprecated v1 alias — don't mix it with `needs:` (the validator rejects the
+> combination). See the capability-map for the full injection table.
+
+## services/api/package.json
+
+```json
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/api/src/index.js
+
+```js
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL alias) at
+// dev + runtime. The env var and Mongo client are resolved LAZILY (inside
+// getClient), never at module top level — a top-level read throws at node
+// startup, before the grid injects the var, and crashes the service. Never
+// hardcode a connection string; never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  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 automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug`. Do " +
+        "not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  return client.db().collection("items");
+}
+
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy();
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null);
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});
+```
+
+## Adapt it
+
+- Rename the `items` collection in `services/api/src/index.js` to your resource
+  (`notes`, `orders`, `events`).
+- Change the document fields; add validation, owners, timestamps, statuses.
+- Add more routes/resources as the API grows.
+- Return clear JSON errors (`{ "error": … }`) with the right status codes.
+- Add more `needs:` (e.g. `cache: true`) only if you actually use them.
+- Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/api-service/services/api/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "mongodb": "^6.12.0"
+  }
+}

package/src/corpus/templates/api-service/services/api/src/index.js

@@ -0,0 +1,132 @@
+// A minimal REST/JSON API backed by grid-shared Mongo.
+//
+// Endpoints (resource: `items`):
+//   GET    /items      -> list items (newest first)
+//   POST   /items      -> create an item; body { "text": string }
+//   DELETE /items?id=…  -> remove an item by id
+//   GET    /           -> tiny service banner + endpoint list
+//
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at dev-time (`grid dev`) and
+// runtime (after `grid plug`). Read the canonical var first, fall back to the
+// legacy alias.
+//
+// The env var and Mongo client are resolved LAZILY (inside getDb), never at
+// module top level — a top-level read throws at node startup, before the grid
+// has injected the var, and crashes the service. Never hardcode a connection
+// string here and never commit a secret.
+import { createServer } from "node:http";
+import { MongoClient, ObjectId } from "mongodb";
+
+let clientPromise;
+
+function getClient() {
+  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 automatically — run " +
+        "this service with `grid dev` locally, or deploy it with `grid plug` (the " +
+        "grid injects the DB connection string at runtime). Do not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function items() {
+  const client = await getClient();
+  // The default DB comes from the connection-string path segment the grid injects.
+  return client.db().collection("items");
+}
+
+// ── Small JSON helpers ───────────────────────────────────────────────────────
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = "";
+    req.on("data", (chunk) => {
+      data += chunk;
+      if (data.length > 1_000_000) req.destroy(); // basic guard
+    });
+    req.on("end", () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve(null); // signal invalid JSON
+      }
+    });
+    req.on("error", () => resolve(null));
+  });
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const { pathname } = url;
+
+  if (pathname === "/" && req.method === "GET") {
+    return sendJson(res, 200, {
+      service: "my-api",
+      endpoints: ["GET /items", "POST /items", "DELETE /items?id=<id>"],
+    });
+  }
+
+  if (pathname === "/items") {
+    const col = await items();
+
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ createdAt: -1 }).toArray();
+      return sendJson(
+        res,
+        200,
+        list.map((it) => ({ id: it._id.toString(), text: it.text, createdAt: it.createdAt })),
+      );
+    }
+
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const text = typeof body.text === "string" ? body.text.trim() : "";
+      if (!text) return sendJson(res, 400, { error: "text is required" });
+      const doc = { text, createdAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, { id: insertedId.toString(), ...doc });
+    }
+
+    if (req.method === "DELETE") {
+      const id = url.searchParams.get("id");
+      if (!id || !ObjectId.isValid(id)) {
+        return sendJson(res, 400, { error: "a valid id query param is required" });
+      }
+      const { deletedCount } = await col.deleteOne({ _id: new ObjectId(id) });
+      if (deletedCount === 0) return sendJson(res, 404, { error: "item not found" });
+      return sendJson(res, 200, { ok: true });
+    }
+
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  return sendJson(res, 404, { error: "not found" });
+}
+
+const server = createServer((req, res) => {
+  handle(req, res).catch((err) => {
+    // Never leak internals or a connection string in the response.
+    console.error(err);
+    if (!res.headersSent) sendJson(res, 500, { error: "internal server error" });
+  });
+});
+
+// The grid injects PORT; default to 8080 for local runs.
+const port = process.env.PORT || 8080;
+server.listen(port, () => {
+  console.log(`api-service listening on :${port}`);
+});

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