@cloudgrid-io/mcp 0.13.0 → 0.14.0

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

@@ -1,20 +1,234 @@
-# 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.
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
 #
-# `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).
+# This file shows EVERY field the platform supports, with comments explaining
+# each one. It is a reference — no real project would use all of these at once.
+#
+# STANDARD: every CloudGrid template ships its cloudgrid.yaml in THIS full form.
+# Uncomment ONLY the fields the archetype needs (always: name + services; plus
+# needs: for runtime apps). Leave everything else commented. Comments are
+# ignored by the parser, so the file deploys to exactly the active fields.
+#
+# Only two fields are required: name and services. Everything else is optional.
+# Full docs: docs/cloudgrid-yaml-reference.md
+# ============================================================================
+
+
+# ─── IDENTITY ───────────────────────────────────────────────────────────────
+
+# Entity slug (REQUIRED). 2-42 chars, lowercase alphanumeric + hyphens.
+# Must start and end with a letter or digit.
+# Becomes part of your public URL: <name>-<4hex>.<org>.cloudgrid.io
 name: my-chatbot
+
+# One-line summary. Max 280 chars. If omitted, Grid Brain auto-generates one.
+# description: Order processing API for the e-commerce platform
+
+# Single emoji or short text shown as the entity icon. Max 64 chars.
+# icon: "📦"
+
+# Entity type: 'app' (default) or 'agent'. An agent is an app with an agent: block.
+# kind: app
+
+
+# ─── NETWORKING ─────────────────────────────────────────────────────────────
+
+# Whether this entity serves public HTTP traffic.
+# true = public URL + Ingress (default). false = internal only.
+# expose: true
+
+# Additional domain names this entity serves on (the platform URL is always active).
+# custom_domains:
+#   - orders.example.com
+#   - shop.example.com
+
+
+# ─── HEALTH PROBE (entity-level override) ──────────────────────────────────
+
+# Override the default health check for the entire entity.
+# probe:
+#   path: /healthz               # HTTP path to probe (default: /).
+#   expected: "<500"             # '<500' (default), '200', '2xx'.
+
+
+# ─── DEPLOY NOTIFICATIONS ──────────────────────────────────────────────────
+
+# Slack notification to the org's default channel on deploy failure.
+# true = notify (default), false = silent.
+# notify: true
+
+
+# ─── SCALING ────────────────────────────────────────────────────────────────
+
+# Replica scaling intent.
+#   'auto'  — platform decides from the grid tier (default).
+#   'alert' — single-replica, emit a SPOF warning at plug time.
+#   1-10    — explicit replica count, clamped to the grid max.
+# scale: auto
+
+
+# ─── INFRASTRUCTURE NEEDS ──────────────────────────────────────────────────
+#
+# Declare infrastructure; the platform provisions it and injects connection
+# details as env vars. Nine needs: database, cache, kv, queue, pubsub, vector,
+# object_storage, disk, ai. Simplest form is `true`.
+#
+# needs:
+#   # database — MongoDB. Injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
+#   #   true | pool | dedicated | { tier: external, secret: MY_DB }
+#   database: true
+#   # cache — Redis, LRU eviction (derived data). Injects CACHE_REDIS_URL (+ REDIS_URL).
+#   #   true | redis | { engine: external, secret: MY_REDIS_URL }
+#   cache: true
+#   # kv — Redis, no eviction (durable: flags, idempotency). Injects KV_REDIS_URL.
+#   kv: true
+#   # queue — Redis job-queue substrate (BullMQ). Injects QUEUE_REDIS_URL.
+#   queue: true
+#   # pubsub — Redis broadcast pub/sub. Injects PUBSUB_REDIS_URL.
+#   pubsub: true
+#   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
+#   #   true | pgvector | { engine: pgvector, dim: 1536 }
+#   vector: pgvector
+#   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
+#   #   true | { size: 10Gi }
+#   object_storage: true
+#   # disk — persistent FS mount (PVC). Injects DISK_PATH. Pins to 1 replica.
+#   #   true | { size: 1Gi, mount: /var/data }  (forbidden: /proc /sys /dev)
+#   disk: true
+#   # ai — AI Gateway via @cloudgrid-io/ai. Injects AI_GATEWAY_URL. true | false.
+#   ai: true
+
+
+# ─── INTER-ENTITY COMMUNICATION ────────────────────────────────────────────
+
+# Entities this app calls (outbound). Service-account token injected per pair.
+# calls:
+#   - org:atomic/billing-api
+
+# Inbound caller policy — who can call YOUR entity.
+# callers:
+#   policy: auto                 # 'auto' | 'manual' (default).
+#   scope: org                   # 'org' (default) | 'space' | 'explicit'.
+#   fallback: deny               # 'deny' (default) | 'warn'.
+#   # allowed_apps:              # required only when scope: explicit
+#   #   - org:atomic/frontend
+
+
+# ─── VAULT ──────────────────────────────────────────────────────────────────
+
+# Map org vault items to env vars. Keys UPPER_SNAKE_CASE; values = vault item keys.
+# vault:
+#   STRIPE_KEY: stripe-live-key
+#   SENDGRID_API_KEY: sendgrid-key
+
+
+# ─── CONNECTORS AND HOOKS ──────────────────────────────────────────────────
+
+# connectors:
+#   - id: team-slack
+#     target: org                # 'system' | 'org'.
+#     channel: "#deploys"
+# hooks:
+#   - on: deploy.failed          # release.published | deploy.failed | feedback.received | entity.created
+#     via: team-slack
+#     template: "Deploy failed for {entity_name}: {error}"
+#     channel: "#alerts"
+# triggers:
+#   - from: team-slack
+#     event: message
+#     channel: "#support"
+#     route: /webhooks/slack
+
+
+# ─── LOCAL DEVELOPMENT ──────────────────────────────────────────────────────
+
+# Config for `grid dev`. Redact fields in dev data snapshots.
+# dev:
+#   snapshot:
+#     mask:
+#       - users.email
+#       - users.phone
+
+
+# ─── AGENT METADATA ────────────────────────────────────────────────────────
+
+# An agent is an app with kind: agent (above) and an agent: block.
+# agent:
+#   purpose: Sync customer data from external CRM every night
+#   schedule: "0 2 * * *"
+#   trigger: webhook
+
+
+# ─── PRIVATE RESOURCE AUTO-DEPENDENCIES ────────────────────────────────────
+
+# When true (default), private resources are auto-injected as depends_on.
+# auto_depends_on_private_requires: true
+
+
+# ─── SERVICES (REQUIRED) ───────────────────────────────────────────────────
+#
+# At least one service is required. Key = service name (slug rules).
+# Types: node, nextjs, python, static, cron.
+#
 services:
   web:
+    # type (REQUIRED): node | nextjs | python | static | cron
     type: nextjs
+    # HTTP route: '/' | '/api' | false (internal) | omitted (=false + warning).
+    # Only one service per entity can claim '/'.
     path: /
+    # Container port (default 8080; read process.env.PORT). Not for cron.
+    # port: 3000
+    # nextjs only: base_image: distroless (default) | alpine
+    # base_image: distroless
+    # node only: lang: javascript (default) | typescript
+    # lang: typescript
+    # Custom source location (default services/<name>/). '.' = project root.
+    # source:
+    #   path: src/worker
+    # Health probe: false/omitted (TCP) | true (/health) | "/path" | {path,expected}
+    # health:
+    #   path: /api/health
+    #   expected: "200"
+    # Static runtime env vars (strings). Reserved: PORT, APP_NAME, SERVICE_NAME,
+    # NODE_ENV, MONGODB_URL, REDIS_URL, AI_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
+    # env:
+    #   LOG_LEVEL: info
+    # Sibling services/private resources that must be Ready first (no cron, no cycles).
+    # depends_on:
+    #   - worker
+    # Per-service needs override (merges with app-level needs).
+    # needs:
+    #   queue: true
+    # Static-only build step:
+    # build:
+    #   command: npm run build
+    #   output: dist
+    #   env:
+    #     VITE_API_URL: https://api.example.com
+    # node_version: "22"          # static build step: '18'|'20'|'22'|'24' (quoted)
+    # Cron-only: schedule (REQUIRED), timezone (UTC|EST|PST), run (job | https URL)
+    # schedule: "0 9 * * 1"
+    # timezone: UTC
+    # run: job
+    # Verbose per-service persistence (prefer needs.disk):
+    # persist:
+    #   - name: scratch
+    #     path: /tmp/scratch
+    #     size: 500Mi
+
+
+
 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.
+
+
+# ============================================================================
+# NOTES
+# - NOT here: org:/entity_id: (→ .cloudgrid/link.json), secrets (→ grid secrets set),
+#   Dockerfile (platform generates from services.*.type).
+# - Deploy: grid plug   |   Local with grid resources: grid dev
+# - Full reference: docs/cloudgrid-yaml-reference.md  |  CLI: docs/cli-reference.md
+# ============================================================================

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

@@ -47,15 +47,9 @@ services/web/app/api/chat/route.js    # POST: createClient().chat(...) -> persis
 ## cloudgrid.yaml
 
 ```yaml
-# 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.
+# On disk this file is the full-annotated reference (templates/_cloudgrid.yaml.reference) with EVERY
+# field present as a comment; only the fields below are uncommented, so it
+# deploys to exactly these active fields.
 name: my-chatbot
 services:
   web:
@@ -64,8 +58,6 @@ services:
 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.
 ```
 
 > **Capability:** this template's needs are `ai: true` (the grid AI gateway,

package/src/corpus/templates/ai-knowledge-base/AGENTS.md

@@ -0,0 +1,254 @@
+# AGENTS.md — ai-knowledge-base blueprint (structure guide)
+
+This is a **blueprint**, not a runnable app. It ships a `cloudgrid.yaml` and this
+guide so an agent can *build* a retrieval-augmented "ask my docs" knowledge base
+correctly on CloudGrid. There is no app code to copy — read this, generate the
+files, then deploy.
+
+An AI knowledge base is a persistent Next.js + Mongo runtime app (same base shape
+as `app-with-data` / `crm`) with a **RAG** loop layered on: ingest documents →
+chunk them → embed each chunk → store the vectors → at query time embed the
+question, retrieve the nearest chunks, and ask the model to answer grounded in
+them (with citations). Both the embedding and the answer step run through
+CloudGrid's **AI Gateway** (`@cloudgrid-io/ai`, injected via `needs: { ai: true }`).
+
+> **Vector-store status (read this first):** the ideal store for embeddings is
+> `needs: vector` (pgvector on Postgres, injecting `VECTOR_PGVECTOR_URL`), but it
+> is **PENDING platform issue #1545** and not yet provisioned. The **`ai` part
+> works today.** Until #1545 ships, store embeddings in **Mongo** (a `chunks`
+> collection with an `embedding: number[]` field) and compute cosine similarity in
+> the app. This blueprint's `cloudgrid.yaml` therefore declares
+> `needs: { ai: true, database: true }` and keeps `vector: pgvector` commented.
+> Section 7 describes the drop-in swap once #1545 lands.
+
+---
+
+## 1. File tree
+
+App code MUST live under `services/web/` — `path: /` in `cloudgrid.yaml` is the
+URL mount, NOT the filesystem path. Files at the repo root fail with
+`Error: Service directory not found: …/services/web`.
+
+```
+cloudgrid.yaml                              # name + services.web(nextjs,/) + needs:{ai:true, database:true}
+services/web/
+  package.json                              # next, react, react-dom, mongodb, @cloudgrid-io/ai
+  lib/
+    db.js                                   # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
+    ai.js                                   # lazy @cloudgrid-io/ai client from AI_GATEWAY_URL — embed() + chat()
+    chunk.js                                # pure fn: splitIntoChunks(text) -> string[] (e.g. ~800-token windows, overlap)
+    retrieve.js                             # embed query -> cosine-rank chunks in Mongo -> top-k with scores
+  app/
+    layout.js                               # root layout + inline CSS
+    page.js                                 # server component: doc list + upload form + ask box
+    documents/[id]/page.js                  # a document's chunks / indexing status
+    ask-box.js                              # client component: POST a question, stream/show the grounded answer + citations
+    api/
+      documents/route.js                    # GET list docs / POST ingest (chunk -> embed -> store) / DELETE (doc + its chunks)
+      ask/route.js                          # POST { question } -> retrieve top-k chunks -> chat() grounded answer + sources
+```
+
+Keep it minimal and real; grow routes/collections as needed. Reuse the
+`app-with-data` App-Router GET/POST/DELETE route shape for the CRUD parts.
+
+---
+
+## 2. Mongo collections + fields
+
+The grid provisions one MongoDB database (`needs: { database: true }`). Suggested
+collections (`_id` is the Mongo ObjectId on every doc):
+
+**`documents`** — a source document the user added
+- `title` (string)
+- `source` (string — filename, URL, or "pasted")
+- `status` (string: `indexing` | `ready` | `failed`)
+- `chunkCount` (number — how many chunks it produced)
+- `createdAt` (Date)
+
+**`chunks`** — one embeddable slice of a document (the retrieval unit)
+- `documentId` (ObjectId ref → documents)
+- `text` (string — the chunk content, returned as a citation)
+- `ordinal` (number — chunk order within the doc)
+- `embedding` (number[] — the embedding vector; e.g. length 1536)
+- `createdAt` (Date)
+
+Until issue #1545 lands, `chunks.embedding` lives in Mongo and you rank in the
+app (Section 3). When pgvector ships, the vectors move to Postgres and `chunks`
+keeps only the text + a foreign key (Section 7).
+
+---
+
+## 3. How CloudGrid injects things
+
+You never provision infra or set connection strings by hand. Declared inputs are
+injected as env vars at `grid dev` (local) and at runtime (after `grid plug`):
+
+| What | Declared in cloudgrid.yaml | Injected env var(s) | Read in code |
+|------|----------------------------|---------------------|--------------|
+| MongoDB | `needs: { database: true }` | `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`) | `lib/db.js` |
+| AI Gateway | `needs: { ai: true }` | `AI_GATEWAY_URL` | `lib/ai.js` (via `@cloudgrid-io/ai`) |
+| Vector store (PENDING #1545) | `needs: { vector: pgvector }` | `VECTOR_PGVECTOR_URL` (+ legacy `PGVECTOR_URL`) | `lib/retrieve.js` — not yet available |
+| Auth key (optional) | `vault: { AUTH_PROVIDER_KEY: auth-provider-key }` | `AUTH_PROVIDER_KEY` | `lib/auth.js` |
+| Stripe key (optional) | `vault: { STRIPE_KEY: stripe-live-key }` | `STRIPE_KEY` | `lib/stripe.js` |
+
+The **AI Gateway needs no API key** — `needs: { ai: true }` injects
+`AI_GATEWAY_URL` and `@cloudgrid-io/ai` routes through it. The `vault:` block only
+**maps** an org vault item key → an env var name; store the real value once with
+`grid secrets set <vault-item-key> <value>`. Never commit a secret; never hardcode
+a connection string.
+
+**Read injected values LAZILY inside a getter, never at module top level** — a
+top-level `const uri = process.env.DATABASE_MONGODB_URL` fails `next build` (the
+module is imported for route analysis before the grid injects the var). Same rule
+for the AI client.
+
+```js
+// lib/db.js — same proven shape as app-with-data
+import { MongoClient } from "mongodb";
+export async function getDb() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) throw new Error("DATABASE_MONGODB_URL not set — run via `grid dev` / `grid plug`.");
+  globalThis.__mongo ??= new MongoClient(uri).connect();
+  return (await globalThis.__mongo).db();
+}
+```
+
+```js
+// lib/ai.js — lazy AI Gateway client (no API key; the gateway URL is injected)
+import { createClient } from "@cloudgrid-io/ai";
+function ai() {
+  const url = process.env.AI_GATEWAY_URL;
+  if (!url) throw new Error("AI_GATEWAY_URL not set — declare needs:{ai:true} and run via `grid dev`/`grid plug`.");
+  globalThis.__ai ??= createClient({ baseURL: url });
+  return globalThis.__ai;
+}
+// embed one or many strings -> vectors (used for both indexing and queries)
+export async function embed(texts) {
+  const res = await ai().embeddings.create({ input: Array.isArray(texts) ? texts : [texts] });
+  return res.data.map((d) => d.embedding);
+}
+// grounded chat answer
+export async function chat(messages) {
+  const res = await ai().chat.completions.create({ messages });
+  return res.choices[0].message.content;
+}
+```
+
+---
+
+## 4. The RAG loop (build this)
+
+### Ingest (`POST /api/documents`)
+1. Accept a title + raw text (or a fetched URL's text).
+2. `splitIntoChunks(text)` in `lib/chunk.js` — a pure function producing ~800-token
+   windows with a small overlap so context isn't cut mid-idea.
+3. Insert a `documents` doc with `status: "indexing"`.
+4. `embed(chunkTexts)` (batch) via `lib/ai.js`, then insert one `chunks` doc per
+   chunk with its `embedding`, `text`, `ordinal`, and `documentId`.
+5. Update the document to `status: "ready"`, `chunkCount: n`.
+
+### Retrieve (`lib/retrieve.js`)
+1. `embed(question)` -> query vector.
+2. Until pgvector (#1545): load candidate `chunks`, compute cosine similarity in
+   the app, keep the top-k (e.g. k=5). Keep it a pure, testable ranking function
+   so it swaps cleanly to a pgvector query later.
+
+```js
+// lib/retrieve.js — cosine top-k over Mongo-stored embeddings (pre-#1545)
+import { getDb } from "./db.js";
+import { embed } from "./ai.js";
+const dot = (a, b) => a.reduce((s, x, i) => s + x * b[i], 0);
+const norm = (a) => Math.sqrt(dot(a, a));
+const cosine = (a, b) => dot(a, b) / (norm(a) * norm(b) || 1);
+export async function retrieve(question, k = 5) {
+  const [q] = await embed(question);
+  const db = await getDb();
+  const chunks = await db.collection("chunks").find({}).toArray();
+  return chunks
+    .map((c) => ({ text: c.text, documentId: c.documentId, score: cosine(q, c.embedding) }))
+    .sort((a, b) => b.score - a.score)
+    .slice(0, k);
+}
+```
+
+### Answer (`POST /api/ask`)
+1. `retrieve(question)` -> top-k chunks.
+2. Build a system prompt: *"Answer ONLY from the provided context; if it isn't
+   there, say you don't know. Cite the chunks you used."* Put the retrieved chunk
+   texts (with ids) in the context.
+3. `chat([...])` via `lib/ai.js`; return the answer plus the source chunks so the
+   UI can render **citations**. Grounding + citations are the point — never let the
+   model answer from parametric memory alone.
+
+---
+
+## 5. Wiring optional auth / payments
+
+Not needed for a personal KB, but common when the KB is internal or paid:
+
+- **Auth (gate the chat UI):** add an auth SDK (`@clerk/nextjs` or
+  `@auth0/nextjs-auth0`) to `package.json`, uncomment the `vault:` block mapping
+  `AUTH_PROVIDER_KEY`, init it in `lib/auth.js` from `process.env.AUTH_PROVIDER_KEY`,
+  and protect `/` + `/api/*` in `middleware.js`. Store the value with
+  `grid secrets set auth-provider-key …`; set any non-secret public key via
+  `grid env`.
+- **Payments (charge for access):** add `stripe` to `package.json`, uncomment the
+  `vault:` block mapping `STRIPE_KEY`, add a lazy `lib/stripe.js` reading
+  `process.env.STRIPE_KEY`, a Checkout route, and a signature-verified
+  `api/webhooks/stripe/route.js`. Store `grid secrets set stripe-live-key sk_live_…`.
+
+Both keys ride the CloudGrid **vault** — the yaml maps the vault item to an env
+var, and `grid secrets set` stores the real value. Never inline a key.
+
+---
+
+## 6. Deploy steps
+
+Runtime app → **local edition** only (Claude Desktop / Claude Code / CLI); the
+hosted edition cannot build a runtime container. Order matters — `plug` needs a
+linked directory, so `init` first.
+
+1. `grid init` (or `gridctl_init`) an app `<name>` — creates the entity +
+   `.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services:{}`.
+2. Fill: put the app under `services/web/` and set `cloudgrid.yaml` to this
+   blueprint's active fields (`services.web` nextjs `/`, `needs:{ai:true,
+   database:true}`).
+3. (If you added auth/payments) store the vault secrets with `grid secrets set`;
+   non-secret public config → `grid env`. The AI Gateway and Mongo need no secrets
+   — they are injected by `needs`.
+4. (Optional) `grid dev` to run locally against the injected dev Mongo + AI Gateway.
+5. `grid plug` to deploy. A runtime deploy is **ASYNC** — the first response is
+   `status: building`, not a live URL. Poll `grid status` (surface a liveness
+   signal, never a bare wait) until Ready.
+6. Once live, return the app URL. Re-plug the same entity to update the same URL.
+
+---
+
+## 7. When pgvector (#1545) lands — the swap
+
+Once `needs: vector` is available, migrate off the in-app cosine ranking:
+
+1. Uncomment `vector: pgvector` in `cloudgrid.yaml`'s `needs:` block (dim 1536 to
+   match your embedding model). The grid then injects `VECTOR_PGVECTOR_URL` (+
+   legacy `PGVECTOR_URL`).
+2. Store each chunk's embedding in a pgvector `vector` column instead of the Mongo
+   `chunks.embedding` array; keep the chunk `text` either in Postgres or as a
+   Mongo row keyed by the same id.
+3. Rewrite `lib/retrieve.js` to run an ORDER-BY-distance query
+   (`ORDER BY embedding <=> $queryVec LIMIT k`) against `VECTOR_PGVECTOR_URL`
+   instead of loading all chunks and ranking in JS. Because `retrieve()` is already
+   a single function returning `{ text, documentId, score }[]`, `POST /api/ask`
+   and the UI don't change.
+
+Read the pgvector URL with the same lazy-getter discipline (never at module top
+level).
+
+---
+
+## 8. Edition note
+
+Because this is a built + deployed container (Next.js + Mongo + AI Gateway), it
+requires the **local edition** (Claude Desktop / Claude Code) or the CLI. The
+hosted edition (Claude Web / hosted MCP) is inline-only and can only publish
+static pages — offer a static explainer page there, but the real knowledge base
+must be built and plugged from the local edition.

package/src/corpus/templates/ai-knowledge-base/README.md

@@ -0,0 +1,28 @@
+# ai-knowledge-base template — RAG "ask my docs" blueprint
+
+A blueprint for a retrieval-augmented knowledge-base chatbot on CloudGrid: a
+persistent Next.js + Mongo app that ingests documents, chunks and embeds them,
+and answers questions grounded in the retrieved chunks (with citations) — the
+`app-with-data` runtime shape with a RAG loop layered on. Embeddings and answers
+run through CloudGrid's AI Gateway (`@cloudgrid-io/ai`, injected via
+`needs: { ai: true }` — works today); the ideal vector store `needs: vector`
+(pgvector) is **PENDING platform issue #1545**, so embeddings live in Mongo and
+similarity is computed in-app until it ships. Because RAG involves choices
+(chunking, embedding model, retrieval), this template ships the **structure and
+`cloudgrid.yaml`, not finished app code** — adapt it and build.
+
+> **This is a blueprint: structure + cloudgrid.yaml, adapt and build.** Read
+> `AGENTS.md` for the file tree, Mongo collections, CloudGrid injection table
+> (needs + AI Gateway + the pgvector #1545 note), the RAG loop, optional
+> auth/payments wiring, and the deploy flow — then generate the app under
+> `services/web/` and `grid plug` it (runtime, local edition, async — poll to a
+> live URL).
+
+## Files
+
+- `cloudgrid.yaml` — active fields: `name`, `services.web` (nextjs, `/`), and
+  `needs: { ai: true, database: true }`. `vector: pgvector` is present but
+  commented (PENDING #1545); the optional `vault:` block (auth/payments) is
+  commented too.
+- `AGENTS.md` — the structure guide (read this first).
+- `index.md` — the fetch-bundle summary + cloudgrid.yaml.