@cloudgrid-io/mcp 0.12.0 → 0.14.0

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.

package/src/corpus/templates/ai-knowledge-base/cloudgrid.yaml

@@ -0,0 +1,238 @@
+# ============================================================================
+# cloudgrid.yaml — Complete Example
+# ============================================================================
+#
+# 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-knowledge-base
+
+# 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 }
+#   # NOTE: `needs: vector` (pgvector) is the intended store for RAG embeddings but
+#   # is PENDING platform issue #1545 — not yet provisioned. Until it ships, store
+#   # embeddings in Mongo (a `chunks` collection with an `embedding: number[]` field)
+#   # and do cosine similarity in the app. Flip this on once #1545 lands.
+#   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.
+  # Powers embeddings (for indexing docs + queries) and chat completions (the
+  # answer step). Works today.
+  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.
+# This RAG blueprint needs NO secret by default — the AI Gateway is injected via
+# `needs: { ai: true }` (no API key to manage). Uncomment a vault block ONLY if
+# you add auth (gate the chat UI) or payments. Store the value once with
+# `grid secrets set <vault-item-key> …`; the block only maps it to an env var.
+# vault:
+#   AUTH_PROVIDER_KEY: auth-provider-key    # if you gate the KB behind Clerk/Auth0
+#   STRIPE_KEY: stripe-live-key             # if you charge for access
+
+
+# ─── 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
+
+
+# ============================================================================
+# 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-knowledge-base/index.md

@@ -0,0 +1,81 @@
+# Template: ai-knowledge-base (blueprint — RAG "ask my docs" on Next.js + Mongo + AI Gateway)
+
+A **blueprint** for a retrieval-augmented knowledge base / "ask my docs" chatbot:
+ingest documents, chunk + embed them, and answer questions grounded in the
+retrieved chunks with citations. It is the persistent Next.js + Mongo runtime
+shape (same base as `app-with-data` / `crm`) with a RAG loop layered on. This
+template ships **structure, not app code** — read the structure guide, then build
+the app following it.
+
+**This is a blueprint (tier D):** the deliverable is `cloudgrid.yaml` +
+`AGENTS.md`. Fetch the bundle, read `AGENTS.md`, then generate the files under
+`services/web/` and deploy.
+
+- **Structure guide:** `gridctl_fetch("template", "ai-knowledge-base")` → read
+  **`AGENTS.md`** (file tree, Mongo collections, CloudGrid injection table, the
+  RAG loop, the pgvector #1545 note, optional auth/payments, deploy steps).
+
+**Key rules (same runtime discipline as `app-with-data`):**
+
+1. **App code MUST live under `services/web/`, not the repo root.** `path: /` in
+   `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
+2. **Read injected values LAZILY (inside a getter), never at module top level** —
+   a top-level read fails `next build`. The grid injects `DATABASE_MONGODB_URL`
+   (+ legacy `MONGODB_URL`) for Mongo and `AI_GATEWAY_URL` for the AI Gateway.
+3. **Declare `needs: { ai: true, database: true }`** (canonical shape). Never
+   author `requires:`, and never set `needs:` and `requires:` together (the
+   validator rejects the combination).
+4. **Ground answers in retrieved chunks + cite them** — never answer from the
+   model's parametric memory alone. Keep chunking/retrieval as pure functions.
+
+**Vector store:** `needs: vector` (pgvector, injecting `VECTOR_PGVECTOR_URL`) is
+the intended embedding store but is **PENDING platform issue #1545**. The `ai`
+part works today — until #1545 ships, store embeddings in a Mongo `chunks`
+collection and rank by cosine similarity in the app; swap to a pgvector
+ORDER-BY-distance query when it lands (see `AGENTS.md` §7).
+
+Runtime app → **local edition** only (async build, poll to a live URL).
+
+## cloudgrid.yaml
+
+```yaml
+# 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. `vector: pgvector` is present but kept
+# COMMENTED (PENDING #1545).
+name: my-knowledge-base
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  ai: true
+  database: true
+```
+
+> **Capability:** `needs: { database: true }` → the deployer provisions Mongo and
+> injects `DATABASE_MONGODB_URL` (plus legacy `MONGODB_URL`). `needs: { ai: true }`
+> → injects `AI_GATEWAY_URL`; `@cloudgrid-io/ai` routes embeddings + chat through
+> it with no API key to manage. `needs: { vector: pgvector }` (would inject
+> `VECTOR_PGVECTOR_URL`) is PENDING #1545. See the capability-map for the full
+> injection table.
+
+## Structure guide
+
+The real content of this blueprint is **`AGENTS.md`** — fetch the template bundle
+and read it. It covers the `services/web/` file tree, the `documents` / `chunks`
+collections, the CloudGrid injection table (needs + AI Gateway + the #1545 note),
+the ingest → retrieve → answer RAG loop with lazy `lib/db.js` / `lib/ai.js` /
+`lib/retrieve.js`, optional auth/payments via `vault:`, and the
+`grid init → fill → grid plug → poll` deploy flow.
+
+## Adapt it
+
+- Pick your chunking window/overlap and embedding model in `lib/chunk.js` /
+  `lib/ai.js`; tune retrieval `k`.
+- Add auth (uncomment `vault: { AUTH_PROVIDER_KEY }`) to gate the KB, or payments
+  (`vault: { STRIPE_KEY }`) to charge for access.
+- When pgvector #1545 lands, uncomment `needs: { vector: pgvector }` and swap
+  `lib/retrieve.js` to an ORDER-BY-distance query (`AGENTS.md` §7).
+- Build under `services/web/`, then `grid dev` (local) / `grid plug` (async — poll
+  to a live URL).