@cloudgrid-io/mcp 0.11.2 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.11.2",
+  "version": "0.12.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": {
@@ -20,6 +20,7 @@
     "test:error-reporting": "node test/error-reporting.test.mjs",
     "test:source": "node test/source-fetch.test.mjs",
     "test:app-with-data": "node test/app-with-data.test.mjs",
+    "test:archetypes": "node test/archetypes.test.mjs",
     "test:self-describing": "node test/self-describing.test.mjs",
     "test:canonical-yaml": "node test/canonical-yaml.test.mjs",
     "test:content": "node test/content-handling.test.mjs",

package/src/corpus/capability-map.md

@@ -13,7 +13,7 @@ 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 6 templates
+## The 8 templates
 
 | Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
 |---|---|---|---|---|
@@ -23,10 +23,24 @@ requires-vs-needs caveat, validation rules), fetch the companion reference:
 | 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 |
+| 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 |
 
 **Rule of thumb:** if the app must SAVE/remember data, share state across
-users/sessions, log in, or store submissions → it is persistent → `app-with-data`
-(runtime, local edition). Otherwise a static template deploys instantly anywhere.
+users/sessions, log in, or store submissions → it is persistent → runtime, local
+edition. Pick by shape: a full web UI → `app-with-data`; a plain backend/JSON API
+(no UI) → `api-service`; an app that talks to an LLM → `ai-app` (adds `ai:`).
+Otherwise a static template deploys instantly anywhere.
+
+## Held / pending platform (not yet buildable)
+
+Two more archetypes are designed but blocked on platform work — the LLM should
+know they are coming but must NOT author them yet:
+
+| Intent | Would need | Status |
+|---|---|---|
+| 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. |
 
 ## The full `needs:` vocabulary (the whole menu)
 
@@ -65,8 +79,9 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 ## How to choose
 
 1. Read the request; match it against the workflow `when:` triggers above.
-2. Adopt that template's `needs:`. Persistence → `database`. (Future: scheduled →
-   `cron` service; semantic search / RAG → `vector` + `ai`.)
+2. Adopt that template's `needs:`. Persistence → `database` (`app-with-data` or
+   `api-service`); talks to an LLM → `ai: true` + `database` (`ai-app`). (Held for
+   now: scheduled → a `cron` service, #1543; RAG → `vector: pgvector`, #1545.)
 3. Static (`needs: none`) → publish as an inspiration with `gridctl_drop`
    (instant, any edition). Anything with a `needs:` → runtime, local edition,
    `gridctl_plug` a linked folder, then poll to a live URL.

package/src/corpus/examples/ai-app/index.md

@@ -0,0 +1,237 @@
+# Example: ai-app — "Trip Planner Bot"
+
+A filled reference imitating the `ai-app` template: a themed AI assistant — a
+travel trip planner. Same stack (Next.js App Router + `@cloudgrid-io/ai` for the
+grid AI gateway + the `mongodb` driver for chat history), slightly richer than
+the bare chatbot: it gives the assistant a **persona** via a `system` message and
+sends the **prior conversation** as context, so replies stay on-theme and
+coherent across turns.
+
+Data persists in the grid-shared Mongo, so the conversation survives refresh.
+
+**Same four 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 AI call is **zero-config — `createClient()` with no key** (it
+uses the in-grid identity); (3) the DB connection string is read **lazily inside
+the `getDb` getter**, never at module top level (a top-level read fails `next
+build`); (4) the datastore is declared with the canonical **`needs: { ai: true,
+database: true }`**. Don't use the deprecated `requires:` alias.
+
+## cloudgrid.yaml
+
+```yaml
+# `needs: { ai: true, database: true }` is canonical: the deployer wires the AI
+# gateway (in-grid identity — no key) and provisions Mongo, injecting
+# 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: trip-planner-bot
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  ai: true
+  database: true
+# RAG over your own docs needs `needs: { vector: pgvector }` — not yet available
+# (platform issue #1545).
+```
+
+## services/web/package.json
+
+```json
+{
+  "name": "trip-planner-bot",
+  "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",
+    "@cloudgrid-io/ai": "^0.2.0",
+    "mongodb": "^6.12.0"
+  }
+}
+```
+
+## services/web/lib/db.js
+
+```js
+// Cached Mongo client for the chat history. The grid injects DATABASE_MONGODB_URL
+// (plus the legacy MONGODB_URL alias) at dev + runtime. Resolve it LAZILY inside
+// the getter — a top-level read fails `next build`. Never hardcode a connection
+// string; never commit a secret.
+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/chat/route.js
+
+```js
+// Trip-planner chat route: give the assistant a persona, send the prior
+// conversation as context, ask the grid AI gateway, persist the exchange,
+// return the reply. Zero-config AI — createClient() with no key uses the in-grid
+// identity.
+import { NextResponse } from "next/server";
+import { createClient } from "@cloudgrid-io/ai";
+import { getDb } from "../../../lib/db.js";
+
+export const dynamic = "force-dynamic";
+
+const SYSTEM = {
+  role: "system",
+  content:
+    "You are Trip Planner Bot, a concise, friendly travel assistant. Suggest " +
+    "itineraries, budgets, and practical tips. Ask a clarifying question when the " +
+    "destination or dates are unclear.",
+};
+
+async function messages() {
+  return (await getDb()).collection("messages");
+}
+
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const text = typeof body.message === "string" ? body.message.trim() : "";
+  if (!text) return NextResponse.json({ error: "message is required" }, { status: 400 });
+
+  const col = await messages();
+
+  // Load recent history for context (last 20 turns), oldest first.
+  const prior = await col.find({}).sort({ createdAt: -1 }).limit(20).toArray();
+  prior.reverse();
+  const context = prior.map((m) => ({ role: m.role, content: m.content }));
+
+  // Ask the grid AI gateway: persona + prior turns + the new user message.
+  const client = createClient();
+  const r = await client.chat({
+    messages: [SYSTEM, ...context, { role: "user", content: text }],
+  });
+  const reply = r.text ?? r.content ?? "";
+
+  // Persist the exchange.
+  const now = new Date();
+  await col.insertMany([
+    { role: "user", content: text, createdAt: now },
+    { role: "assistant", content: reply, createdAt: new Date(now.getTime() + 1) },
+  ]);
+
+  return NextResponse.json({ reply });
+}
+
+export async function GET() {
+  const col = await messages();
+  const history = await col.find({}).sort({ createdAt: 1 }).toArray();
+  return NextResponse.json(
+    history.map((m) => ({ id: m._id.toString(), role: m.role, content: m.content })),
+  );
+}
+```
+
+## services/web/app/page.js
+
+```js
+import { getDb } from "../lib/db.js";
+import Chat from "./chat.js";
+
+export const dynamic = "force-dynamic";
+
+async function listHistory() {
+  const items = await (await getDb())
+    .collection("messages")
+    .find({})
+    .sort({ createdAt: 1 })
+    .toArray();
+  return items.map((m) => ({ id: m._id.toString(), role: m.role, content: m.content }));
+}
+
+export default async function Page() {
+  const history = await listHistory();
+  return (
+    <main>
+      <h1>Trip Planner Bot</h1>
+      <p className="hint">Ask about a destination — powered by the grid AI gateway, saved to Mongo.</p>
+      <Chat initialHistory={history} />
+    </main>
+  );
+}
+```
+
+## services/web/app/chat.js
+
+```js
+"use client";
+import { useState } from "react";
+
+export default function Chat({ initialHistory }) {
+  const [history, setHistory] = useState(initialHistory);
+  const [text, setText] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function send(e) {
+    e.preventDefault();
+    const value = text.trim();
+    if (!value || busy) return;
+    setBusy(true);
+    setHistory((p) => [...p, { id: `local-${Date.now()}`, role: "user", content: value }]);
+    setText("");
+    const res = await fetch("/api/chat", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ message: value }),
+    });
+    if (res.ok) {
+      const { reply } = await res.json();
+      setHistory((p) => [...p, { id: `local-${Date.now()}-a`, role: "assistant", content: reply }]);
+    }
+    setBusy(false);
+  }
+
+  return (
+    <div>
+      <ul className="log">
+        {history.length === 0 && <li className="empty">Where do you want to go?</li>}
+        {history.map((m) => (
+          <li key={m.id} className={m.role}>
+            <span className="who">{m.role === "user" ? "You" : "Trip Planner"}</span>
+            <span className="msg">{m.content}</span>
+          </li>
+        ))}
+      </ul>
+      <form onSubmit={send} className="row">
+        <input value={text} onChange={(e) => setText(e.target.value)} placeholder="e.g. 4 days in Lisbon on a budget" disabled={busy} />
+        <button type="submit" disabled={busy}>{busy ? "…" : "Send"}</button>
+      </form>
+    </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 needs are Mongo + the AI gateway (`needs: { ai: true, database: true }`).
+  The AI call is zero-config — `createClient()` with no key uses the in-grid
+  identity.
+- All app code lives under `services/web/`; the connection is read lazily inside
+  `getDb`, never at module top level.
+- To answer over your own documents (RAG) you'd add `needs: { vector: pgvector }`
+  — not yet available (platform issue #1545).

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

@@ -0,0 +1,190 @@
+# Example: api-service — "Notes API"
+
+A filled reference imitating the `api-service` template: a small REST/JSON
+backend for notes. Same stack (a plain Node `http` server + the `mongodb`
+driver, grid-shared Mongo via `process.env.DATABASE_MONGODB_URL`), slightly
+richer than the bare items template — notes have a `title` and a `body`, and the
+API supports fetching a single note and updating it via PUT.
+
+Data persists in the grid-shared Mongo, so every caller sees the same notes
+across sessions and refresh.
+
+**Same four proven rules as the template:** (1) service code lives under
+**`services/api/`** (the service name, NOT the repo root — `path:` is the URL
+mount); (2) the DB connection string is read **lazily inside the `getClient`
+getter**, never at module top level (a top-level read crashes node startup); (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); (4) the server listens on **`process.env.PORT || 8080`**.
+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).
+# Plain Node HTTP service; code lives under services/api/.
+name: notes-api
+services:
+  api:
+    type: node
+    path: /
+needs:
+  database: true
+```
+
+## 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
+// Notes REST API backed by grid-shared Mongo.
+//   GET    /notes        -> list notes (newest first)
+//   POST   /notes        -> create a note; body { title, body }
+//   GET    /notes/:id    -> fetch one note
+//   PUT    /notes/:id    -> update a note; body { title?, body? }
+//   DELETE /notes/:id    -> remove a note
+//
+// 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 crashes node startup
+// before the grid injects the var. Never hardcode a connection string or 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 — run `grid dev` " +
+        "locally or deploy with `grid plug`. Do not set it by hand.",
+    );
+  }
+  if (!clientPromise) clientPromise = new MongoClient(uri).connect();
+  return clientPromise;
+}
+
+async function notes() {
+  return (await getClient()).db().collection("notes");
+}
+
+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", (c) => {
+      data += c;
+      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));
+  });
+}
+
+function shape(n) {
+  return { id: n._id.toString(), title: n.title, body: n.body, updatedAt: n.updatedAt };
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url, "http://localhost");
+  const parts = url.pathname.split("/").filter(Boolean); // ["notes"] or ["notes", "<id>"]
+  const col = await notes();
+
+  if (parts[0] !== "notes") return sendJson(res, 404, { error: "not found" });
+
+  // Collection: /notes
+  if (parts.length === 1) {
+    if (req.method === "GET") {
+      const list = await col.find({}).sort({ updatedAt: -1 }).toArray();
+      return sendJson(res, 200, list.map(shape));
+    }
+    if (req.method === "POST") {
+      const body = await readBody(req);
+      if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+      const title = typeof body.title === "string" ? body.title.trim() : "";
+      if (!title) return sendJson(res, 400, { error: "title is required" });
+      const doc = { title, body: typeof body.body === "string" ? body.body : "", updatedAt: new Date() };
+      const { insertedId } = await col.insertOne(doc);
+      return sendJson(res, 201, shape({ _id: insertedId, ...doc }));
+    }
+    return sendJson(res, 405, { error: "method not allowed" });
+  }
+
+  // Item: /notes/:id
+  const id = parts[1];
+  if (!ObjectId.isValid(id)) return sendJson(res, 400, { error: "invalid id" });
+  const _id = new ObjectId(id);
+
+  if (req.method === "GET") {
+    const note = await col.findOne({ _id });
+    if (!note) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, shape(note));
+  }
+  if (req.method === "PUT") {
+    const body = await readBody(req);
+    if (body === null) return sendJson(res, 400, { error: "invalid JSON body" });
+    const $set = { updatedAt: new Date() };
+    if (typeof body.title === "string") $set.title = body.title.trim();
+    if (typeof body.body === "string") $set.body = body.body;
+    const r = await col.findOneAndUpdate({ _id }, { $set }, { returnDocument: "after" });
+    if (!r) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, shape(r));
+  }
+  if (req.method === "DELETE") {
+    const { deletedCount } = await col.deleteOne({ _id });
+    if (deletedCount === 0) return sendJson(res, 404, { error: "note not found" });
+    return sendJson(res, 200, { ok: true });
+  }
+  return sendJson(res, 405, { error: "method not allowed" });
+}
+
+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(`notes-api listening on :${port}`));
+```
+
+## 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 }` — the deployer
+  provisions Mongo and injects `DATABASE_MONGODB_URL`, plus the legacy
+  `MONGODB_URL` alias). Add more `needs:` only for infra you actually use.
+- All service code lives under `services/api/`; the connection is read lazily
+  inside `getClient`, never at module top level; the server listens on
+  `process.env.PORT || 8080`.

package/src/corpus/templates/ai-app/README.md

@@ -0,0 +1,95 @@
+# ai-app template — AI chatbot on Next.js + the grid AI gateway + Mongo
+
+A minimal but real, deployable AI chatbot. A Next.js App Router app that calls
+the grid AI gateway (via `@cloudgrid-io/ai`) for replies and persists the
+conversation to the grid-shared MongoDB, so history survives refresh and is
+shared across sessions.
+
+## How the grid gives you AI + a database
+
+You do **not** set an API key or provision a database. In `cloudgrid.yaml` you
+declare `needs: { ai: true, database: true }`, and the grid:
+
+- wires the **AI gateway** with the app's in-grid identity — `@cloudgrid-io/ai`
+  `createClient()` auto-detects it, so there is **no API key to set**; and
+- provisions shared Mongo 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 AI call
+
+```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
+```
+
+`createClient()` takes no key — it uses the in-grid identity, so it only works
+inside a deployed grid app (or under `grid dev`). Do **not** pass or set an API
+key.
+
+### The database
+
+The app reads `process.env.DATABASE_MONGODB_URL` (with a legacy
+`process.env.MONGODB_URL` fallback) inside `getDb` in
+`services/web/lib/db.js` — **lazily, 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: { ai: true, database: true }` (the canonical shape).** The
+> deployer wires the AI gateway and provisions Mongo, injecting
+> `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
+cd services/web && npm install && cd -
+grid dev          # runs Next.js with the AI gateway + DATABASE_MONGODB_URL wired
+```
+
+## 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: { ai: true, database: true }
+services/web/package.json             # next, react, react-dom, @cloudgrid-io/ai, mongodb
+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 chat history from Mongo
+services/web/app/chat.js              # client component: sends messages, renders the log
+services/web/app/api/chat/route.js    # POST: createClient().chat(...) -> persist -> reply; GET: history
+```
+
+## Adapt it
+
+- Give the assistant a persona — pass a `{ role: "system", content: "…" }`
+  message ahead of the user message in the `chat({ messages })` call.
+- Send prior turns as context by including the stored history in `messages`.
+- Change the `messages` collection / fields; add users, sessions, titles.
+- Restyle the chat UI in `layout.js` / `chat.js`.
+
+## RAG / retrieval (not yet)
+
+To answer over **your own documents** (retrieval-augmented generation) you need 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.

package/src/corpus/templates/ai-app/cloudgrid.yaml

@@ -0,0 +1,20 @@
+# Rename this chatbot. The grid wires the AI gateway (in-grid identity — no API
+# key) and injects the DB connection string as an environment variable at
+# runtime. Do NOT set an AI key, do NOT set the DB var yourself, and never commit
+# a connection string or secret.
+#
+# `needs: { ai: true, database: true }` is the canonical shape. The deployer
+# wires the AI gateway and provisions Mongo, injecting 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-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.