@cloudgrid-io/mcp 0.20.20 → 0.20.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.20",
+  "version": "0.20.22",
   "description": "Use CloudGrid via MCP to brainstorm, build, deploy, and improve apps, games, websites, dashboards, and tools and get a live URL - templates, recipes, managed databases and AI, instant single-page publish, and full-app deploys, for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server, over MCP.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "test:plug-output-schema": "node test/plug-output-schema.test.mjs",
     "test:zip-deploy": "node test/zip-deploy.test.mjs",
     "test:create-gates": "node test/create-gates.test.mjs",
+    "test:create-project-args": "node test/create-project-args.test.mjs",
     "test:mcpb-boot": "node test/mcpb-boot.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",

package/src/corpus/capability-map.md

@@ -159,7 +159,7 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 | `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | **Injects via `needs:`** (#1545 shipped, verified live 2026-07-16) |
 | `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | **GATED (#1678)** - rejected at plug-time; use `disk` or a BYO bucket via secret |
 | `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Injects via `needs:` |
-| `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | Injects via `needs:` |
+| `ai: true` | AI Gateway access | `RUNTIME_GATEWAY_URL` | Injects via `needs:` |
 | `type: cron` (service) | Scheduled job (`schedule`, `timezone`) | — | Service type, not a need |
 
 ### Injection status

package/src/corpus/cloudgrid-yaml.md

@@ -156,7 +156,7 @@ needs:
   vector: pgvector                  # pgvector. Injects VECTOR_PGVECTOR_URL. (#1545 shipped, verified live 2026-07-16.)
   object_storage: true              # GATED (platform #1678) - rejected at plug-time; use disk: or a BYO bucket via secret.
   disk: true                        # Persistent filesystem at /data. Injects DISK_PATH.
-  ai: true                          # AI Gateway access. Injects AI_GATEWAY_URL.
+  ai: true                          # AI Gateway access. Injects RUNTIME_GATEWAY_URL.
 
 # ─── Inter-entity communication ────────────────────────────────────
 calls:                              # Entities this app calls (outbound grants).
@@ -366,7 +366,7 @@ that path. `{ path, expected }` → HTTP with expected status
 
 String key-values injected at runtime (not build). **Reserved names (rejected):**
 `PORT`, `APP_NAME`, `SERVICE_NAME`, `NODE_ENV`, `MONGODB_URL`, `REDIS_URL`,
-`AI_GATEWAY_URL`, `N8N_WEBHOOK_URL`, and any key starting with `CLOUDGRID_`. Use
+`RUNTIME_GATEWAY_URL`, `N8N_WEBHOOK_URL`, and any key starting with `CLOUDGRID_`. Use
 `grid secrets set` for sensitive values.
 
 ### Per-service `needs` override
@@ -407,7 +407,7 @@ service type.**
 | `vector` | Vector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | pgvector (Postgres) |
 | `object_storage` | Object/blob bucket - **GATED (#1678)**: rejected at plug-time, use `disk` or a BYO bucket via secret | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | GCS |
 | `disk` | Persistent filesystem mount | `DISK_PATH` | PVC |
-| `ai` | AI Gateway access | `AI_GATEWAY_URL` | CloudGrid AI Gateway |
+| `ai` | AI Gateway access | `RUNTIME_GATEWAY_URL` | CloudGrid AI Gateway |
 
 `cache`, `kv`, `queue`, `pubsub` all share one physical Redis but each gets a
 distinct env var. `cache` runs `allkeys-lru` eviction (derived data); the other

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

@@ -1,7 +1,7 @@
 # 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
+travel trip planner. Same stack (Next.js App Router + `@cloudgrid-io/runtime` 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
@@ -11,8 +11,9 @@ 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
+mount); (2) the AI call is **zero-config — `runtime.ai.chat({ model, messages })`
+with no key** (the SDK reads `RUNTIME_GATEWAY_URL` and the in-grid identity
+itself); (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.
@@ -48,7 +49,7 @@ needs:
     "next": "^15.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@cloudgrid-io/ai": "^0.2.0",
+    "@cloudgrid-io/runtime": "^1.0.3",
     "mongodb": "^6.12.0"
   }
 }
@@ -87,21 +88,18 @@ export async function getDb() {
 ```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.
+// return the reply. Zero-config AI — @cloudgrid-io/runtime reads RUNTIME_GATEWAY_URL
+// (injected by the grid) itself and uses the in-grid identity — no key.
 import { NextResponse } from "next/server";
-import { createClient } from "@cloudgrid-io/ai";
+import { runtime } from "@cloudgrid-io/runtime";
 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.",
-};
+const SYSTEM =
+  "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");
@@ -119,12 +117,13 @@ export async function POST(request) {
   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 }],
+  // Ask the grid AI gateway: persona (system) + prior turns + the new user
+  // message. Chat expects a model and returns { text }.
+  const { text: reply } = await runtime.ai.chat({
+    model: "claude-haiku",
+    system: SYSTEM,
+    messages: [...context, { role: "user", content: text }],
   });
-  const reply = r.text ?? r.content ?? "";
 
   // Persist the exchange.
   const now = new Date();
@@ -229,8 +228,8 @@ export default function Chat({ initialHistory }) {
 - 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.
+  The AI call is zero-config — `runtime.ai.chat` with no key; the SDK reads
+  `RUNTIME_GATEWAY_URL` and the in-grid identity itself.
 - 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 }`

package/src/corpus/templates/_cloudgrid.yaml.reference

@@ -96,7 +96,7 @@ name: my-app
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -96,7 +96,7 @@ name: my-admin
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -1,7 +1,7 @@
 # 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
+the grid AI gateway (via `@cloudgrid-io/runtime`) for replies and persists the
 conversation to the grid-shared MongoDB, so history survives refresh and is
 shared across sessions.
 
@@ -10,8 +10,9 @@ shared across sessions.
 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
+- wires the **AI gateway** with the app's in-grid identity — `@cloudgrid-io/runtime`
+  reads the gateway URL from the injected `RUNTIME_GATEWAY_URL` itself, 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`).
@@ -19,15 +20,18 @@ declare `needs: { ai: true, database: true }`, and the grid:
 ### 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
+import { runtime } from "@cloudgrid-io/runtime";
+// Chat expects a model and returns { text }. No key, no baseURL.
+const { text: reply } = await runtime.ai.chat({
+  model: "claude-haiku",
+  messages: [{ role: "user", content: 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.
+`runtime.ai.chat` takes no key — the SDK reads `RUNTIME_GATEWAY_URL` (injected by
+the grid) and 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, and never reference
+the env var yourself.
 
 ### The database
 
@@ -71,18 +75,19 @@ update the same URL.
 
 ```
 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/package.json             # next, react, react-dom, @cloudgrid-io/runtime, 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
+services/web/app/api/chat/route.js    # POST: runtime.ai.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.
+  message ahead of the user message in the `runtime.ai.chat({ model, messages })`
+  call (or pass `system:` directly alongside `messages`).
 - 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`.

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

@@ -96,7 +96,7 @@ name: my-chatbot
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -1,7 +1,7 @@
 # Template: ai-app (Next.js AI chatbot + 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
+the grid AI gateway (via `@cloudgrid-io/runtime`) for replies and persists the
 conversation to the grid-shared MongoDB. History survives refresh and is shared
 across sessions.
 
@@ -11,11 +11,12 @@ across sessions.
    `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path. The
    service named `web` → the CLI looks for `services/web/`. Files at the root
    fail with `Error: Service directory not found: …/services/web`.
-2. **The AI call is zero-config — no API key.** `import { createClient } from
-   "@cloudgrid-io/ai"; const client = createClient();` auto-detects 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. Read the reply from `r.text` (fall back to
-   `r.content`).
+2. **The AI call is zero-config — no API key.** `import { runtime } from
+   "@cloudgrid-io/runtime"` then `runtime.ai.chat({ model, messages })`. The SDK
+   reads the gateway URL from `RUNTIME_GATEWAY_URL` (injected by the grid) itself,
+   so it only works inside a deployed grid app (or under `grid dev`). Do NOT pass
+   or set an API key, and never reference the env var yourself. Chat expects a
+   `model` and returns `{ text }`.
 3. **Read the DB connection string LAZILY (inside the getter), never at module
    top level.** The grid injects it as `DATABASE_MONGODB_URL` (plus the legacy
    `MONGODB_URL` alias) at dev + runtime; the app reads
@@ -36,12 +37,12 @@ Write these files into the scaffolded app folder — the app code goes under
 
 ```
 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/package.json             # next, react, react-dom, @cloudgrid-io/runtime, 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
+services/web/app/api/chat/route.js    # POST: runtime.ai.chat(...) -> persist -> reply; GET: history
 ```
 
 ## cloudgrid.yaml
@@ -78,7 +79,7 @@ needs:
     "next": "^15.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@cloudgrid-io/ai": "^0.2.0",
+    "@cloudgrid-io/runtime": "^1.0.3",
     "mongodb": "^6.12.0"
   }
 }
@@ -118,11 +119,12 @@ export async function getDb() {
 // Chat API route: take the user's message, ask the grid AI gateway for a reply,
 // persist the exchange to Mongo, return the reply.
 //
-// The AI call uses @cloudgrid-io/ai with ZERO config — no API key. createClient()
-// auto-detects the in-grid identity, so it only works inside a deployed grid app
-// (or under `grid dev`). Do NOT pass a key.
+// The AI call uses @cloudgrid-io/runtime with ZERO config — no API key. The SDK
+// reads the gateway URL from RUNTIME_GATEWAY_URL (injected by the grid) itself,
+// so it only works inside a deployed grid app (or under `grid dev`). Do NOT set a
+// key or reference the env var yourself.
 import { NextResponse } from "next/server";
-import { createClient } from "@cloudgrid-io/ai";
+import { runtime } from "@cloudgrid-io/runtime";
 import { getDb } from "../../../lib/db.js";
 
 export const dynamic = "force-dynamic";
@@ -139,10 +141,12 @@ export async function POST(request) {
     return NextResponse.json({ error: "message is required" }, { status: 400 });
   }
 
-  // 1. Ask the grid AI gateway (zero-config in-grid identity — no key).
-  const client = createClient();
-  const r = await client.chat({ messages: [{ role: "user", content: text }] });
-  const reply = r.text ?? r.content ?? "";
+  // 1. Ask the grid AI gateway (zero-config in-grid identity — no key). Chat
+  //    expects a model; it returns { text }.
+  const { text: reply } = await runtime.ai.chat({
+    model: "claude-haiku",
+    messages: [{ role: "user", content: text }],
+  });
 
   // 2. Persist the exchange so the conversation survives refresh.
   const col = await messages();
@@ -248,7 +252,8 @@ export default function Chat({ initialHistory }) {
 ## Adapt it
 
 - Give the assistant a persona — pass a `{ role: "system", content: "…" }`
-  message ahead of the user message in `chat({ messages })`.
+  message ahead of the user message in `runtime.ai.chat({ model, messages })`
+  (or pass `system:` directly alongside `messages`).
 - Send prior turns as context by including the stored history in `messages`.
 - Change the `messages` collection / fields; add users, sessions, titles.
 - Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/ai-app/services/web/app/api/chat/route.js

@@ -1,11 +1,12 @@
 // Chat API route: takes the user's message, asks the grid AI gateway for a
 // reply, persists the exchange to Mongo, and returns the reply.
 //
-// The AI call uses @cloudgrid-io/ai with ZERO config — no API key. createClient()
-// auto-detects the in-grid identity, so it only works inside a deployed grid app
-// (or under `grid dev`). Do NOT pass a key.
+// The AI call uses @cloudgrid-io/runtime with ZERO config — no API key. The SDK
+// reads the gateway URL from RUNTIME_GATEWAY_URL (injected by the grid) all on
+// its own, so it only works inside a deployed grid app (or under `grid dev`). Do
+// NOT set a key or reference the env var yourself.
 import { NextResponse } from "next/server";
-import { createClient } from "@cloudgrid-io/ai";
+import { runtime } from "@cloudgrid-io/runtime";
 import { getDb } from "../../../lib/db.js";
 
 // Never cache — always generate/persist live.
@@ -24,10 +25,12 @@ export async function POST(request) {
     return NextResponse.json({ error: "message is required" }, { status: 400 });
   }
 
-  // 1. Ask the grid AI gateway (zero-config in-grid identity — no key).
-  const client = createClient();
-  const r = await client.chat({ messages: [{ role: "user", content: text }] });
-  const reply = r.text ?? r.content ?? "";
+  // 1. Ask the grid AI gateway (zero-config in-grid identity — no key). Chat
+  //    expects a model; it returns { text }.
+  const { text: reply } = await runtime.ai.chat({
+    model: "claude-haiku",
+    messages: [{ role: "user", content: text }],
+  });
 
   // 2. Persist the exchange so the conversation survives refresh.
   const col = await messages();

package/src/corpus/templates/ai-app/services/web/package.json

@@ -11,7 +11,7 @@
     "next": "^15.1.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@cloudgrid-io/ai": "^0.2.0",
+    "@cloudgrid-io/runtime": "^1.0.3",
     "mongodb": "^6.12.0"
   }
 }

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

@@ -10,7 +10,7 @@ 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 }`).
+CloudGrid's **AI Gateway** (`@cloudgrid-io/runtime`, 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`), and it
@@ -32,10 +32,10 @@ URL mount, NOT the filesystem path. Files at the repo root fail with
 ```
 cloudgrid.yaml                              # name + services.web(nextjs,/) + needs:{ai:true, database:true}
 services/web/
-  package.json                              # next, react, react-dom, mongodb, @cloudgrid-io/ai
+  package.json                              # next, react, react-dom, mongodb, @cloudgrid-io/runtime
   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()
+    ai.js                                   # @cloudgrid-io/runtime AI (auto-reads RUNTIME_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/
@@ -86,13 +86,13 @@ 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`) |
+| AI Gateway | `needs: { ai: true }` | `RUNTIME_GATEWAY_URL` | `lib/ai.js` (via `@cloudgrid-io/runtime`) |
 | Vector store (available — #1545 shipped) | `needs: { vector: pgvector }` | `VECTOR_PGVECTOR_URL` (+ legacy `PGVECTOR_URL`) | `lib/retrieve.js` — not used by this blueprint (Section 7 for the swap) |
 | 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
+`RUNTIME_GATEWAY_URL` and `@cloudgrid-io/runtime` 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.
@@ -114,23 +114,20 @@ export async function getDb() {
 ```
 
 ```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)
+// lib/ai.js — CloudGrid runtime AI. No API key and no baseURL: the SDK reads
+// RUNTIME_GATEWAY_URL (injected by needs:{ai:true}) and the in-grid identity
+// itself. Never reference the env var or pass a key.
+import { runtime } from "@cloudgrid-io/runtime";
+// embed one or many strings -> an aligned array of vectors (indexing + 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);
+  const input = Array.isArray(texts) ? texts : [texts];
+  const vec = await runtime.ai.embeddings({ text: input }); // batch -> vec.values aligned to input order
+  return vec.values; // number[][]; vec also carries .model, .dim, .tokens
 }
-// grounded chat answer
-export async function chat(messages) {
-  const res = await ai().chat.completions.create({ messages });
-  return res.choices[0].message.content;
+// grounded chat answer -> string. Chat expects a model and returns { text }.
+export async function chat({ system, messages }) {
+  const { text } = await runtime.ai.chat({ model: "claude-haiku", system, messages });
+  return text;
 }
 ```
 
@@ -176,7 +173,8 @@ export async function retrieve(question, k = 5) {
 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
+3. `chat({ system, messages })` via `lib/ai.js` (the grounding instruction is the
+   `system`); 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.
 

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

@@ -4,7 +4,7 @@ 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
+run through CloudGrid's AI Gateway (`@cloudgrid-io/runtime`, injected via
 `needs: { ai: true }` — works today); the ideal vector store `needs: vector`
 (pgvector) is **now available** — #1545 shipped (verified live 2026-07-16) — but
 this blueprint stores embeddings in Mongo and computes similarity in-app. Because RAG involves choices

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

@@ -101,7 +101,7 @@ needs:
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
   # Powers embeddings (for indexing docs + queries) and chat completions (the
   # answer step). Works today.
   ai: true
@@ -203,7 +203,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -21,7 +21,7 @@ the app following it.
    `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.
+   (+ legacy `MONGODB_URL`) for Mongo and `RUNTIME_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).
@@ -57,7 +57,7 @@ needs:
 
 > **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
+> → injects `RUNTIME_GATEWAY_URL`; `@cloudgrid-io/runtime` routes embeddings + chat through
 > it with no API key to manage. `needs: { vector: pgvector }` (injects
 > `VECTOR_PGVECTOR_URL`) is available (#1545 shipped) but not declared here —
 > this blueprint uses Mongo embeddings. See the capability-map for the full

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

@@ -96,7 +96,7 @@ name: analytics-dashboard
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

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

@@ -96,7 +96,7 @@ name: my-api-dashboard
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

package/src/corpus/templates/api-docs/cloudgrid.yaml

@@ -96,7 +96,7 @@ name: api-docs
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).

package/src/corpus/templates/api-service/cloudgrid.yaml

@@ -96,7 +96,7 @@ name: my-api
 #   # 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 — AI Gateway via @cloudgrid-io/runtime. Injects RUNTIME_GATEWAY_URL. true | false.
 #   ai: true
 
 
@@ -192,7 +192,7 @@ services:
     #   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_*.
+    # NODE_ENV, MONGODB_URL, REDIS_URL, RUNTIME_GATEWAY_URL, N8N_WEBHOOK_URL, CLOUDGRID_*.
     # env:
     #   LOG_LEVEL: info
     # Sibling services/private resources that must be Ready first (no cron, no cycles).