@cloudgrid-io/mcp 0.10.0 → 0.11.2

package/src/corpus/examples/app-with-data/index.md

@@ -2,32 +2,34 @@
 
 A filled reference imitating the `app-with-data` template: a persistent team
 task board. Same stack (Next.js App Router + the `mongodb` driver, grid-shared
-Mongo via `process.env.MONGODB_URL`), slightly richer than the bare todo
-template — tasks have an `assignee` and a `status` (todo / doing / done), and
-the API supports updating status via PATCH.
+Mongo via `process.env.DATABASE_MONGODB_URL`), slightly richer than the bare
+todo template — tasks have an `assignee` and a `status` (todo / doing / done),
+and the API supports updating status via PATCH.
 
 Data persists in the grid-shared Mongo, so the whole team sees the same board
 across sessions and refresh.
 
 **Same three 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) `MONGODB_URL` is read **lazily inside the `getDb` getter**, never at
-module top level (a top-level read fails `next build`); (3) the datastore is
-declared with **`requires: [mongodb]`, not `needs:`** — the deployer only
-injects `MONGODB_URL` from `requires:`.
+mount); (2) the DB connection string is read **lazily inside the `getDb`
+getter**, never at module top level (a top-level read fails `next build`); (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). Don't use the deprecated `requires:` alias.
 
 ## cloudgrid.yaml
 
 ```yaml
-# NOTE: use `requires:` (NOT `needs:`). The deployer only injects MONGODB_URL
-# from `requires:`; `needs:` builds fine but injects NO DB connection (500s).
+# `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).
 name: team-task-board
 services:
   web:
     type: nextjs
     path: /
-requires:
-  - mongodb
+needs:
+  database: true
 ```
 
 ## services/web/package.json
@@ -50,16 +52,18 @@ requires:
 ## services/web/lib/db.js
 
 ```js
-// Cached Mongo client. MONGODB_URL is injected by the grid (dev + runtime).
-// Resolve it LAZILY inside the getter — a top-level read fails `next build`.
+// Cached Mongo client. The grid injects DATABASE_MONGODB_URL (plus the legacy
+// MONGODB_URL alias) at dev + runtime. Read the canonical var first, fall back to
+// the legacy alias. Resolve it LAZILY inside the getter — a top-level read fails
+// `next build`.
 import { MongoClient } from "mongodb";
 
 function clientPromise() {
-  const uri = process.env.MONGODB_URL;
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
   if (!uri) {
     throw new Error(
-      "MONGODB_URL is not set. The grid injects it — run `grid dev` locally or " +
-        "deploy with `grid plug`. Do not set it by hand.",
+      "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) {
@@ -244,8 +248,9 @@ export default function Board({ initialTasks }) {
 
 - 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 (`requires: [mongodb]` — not `needs:`; the
-  deployer only injects `MONGODB_URL` from `requires:`). Add `redis: private`
-  only for caching/sessions/pubsub you actually use.
+- 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 `cache: true` to `needs:` only for
+  caching/sessions/pubsub you actually use.
 - All app code lives under `services/web/`; the connection is read lazily inside
   `getDb`, never at module top level.

package/src/corpus/templates/app-with-data/README.md

@@ -7,23 +7,26 @@ page whose state is in memory only.
 ## How the grid gives you a database
 
 You do **not** provision a database or set a connection string. In
-`cloudgrid.yaml` you declare `requires: [mongodb]`, and the grid:
+`cloudgrid.yaml` you declare `needs: { database: true }`, and the grid:
 
 - provisions shared Mongo for the app, and
-- injects the connection string as the **`MONGODB_URL`** environment variable —
-  at dev-time (`grid dev`) and at runtime (after `grid plug`).
-
-The app reads it via `process.env.MONGODB_URL` in `services/web/lib/db.js` —
-**lazily, inside the `getDb` getter, 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. (If you also declare `redis: private`, the grid injects `REDIS_URL` the
-same way.)
-
-> **Use `requires:` (NOT `needs:`).** The CLI warns `requires:` is deprecated,
-> but the deployer currently only injects `MONGODB_URL` from `requires:` —
-> migrating to `needs:` builds fine but injects NO DB connection (every request
-> 500s). Keep `requires:` until CloudGrid's deployer honors `needs:`.
+- 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 app reads it via `process.env.DATABASE_MONGODB_URL` (with a legacy
+`process.env.MONGODB_URL` fallback) in `services/web/lib/db.js` — **lazily,
+inside the `getDb` getter, 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. (If you also
+declare `cache: true`, the grid injects `CACHE_REDIS_URL` — and the legacy
+`REDIS_URL` alias — the same way.)
+
+> **Declare `needs: { database: true }` (the canonical shape).** The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias). `requires:` is the deprecated v1 alias — don't author new
+> yaml with it, and never set `needs:` and `requires:` together (the validator
+> rejects the combination).
 
 ## Service layout
 
@@ -36,7 +39,7 @@ App code lives under **`services/web/`**, not the template root. `path:` in
 
 ```bash
 npm install
-grid dev          # runs Next.js with MONGODB_URL injected against dev Mongo
+grid dev          # runs Next.js with DATABASE_MONGODB_URL injected against dev Mongo
 ```
 
 ## Deploy
@@ -52,9 +55,9 @@ to update the same URL.
 ## File tree
 
 ```
-cloudgrid.yaml                        # name + services.web (nextjs) + requires: [mongodb]
+cloudgrid.yaml                        # name + services.web (nextjs) + needs: { database: true }
 services/web/package.json             # next, react, react-dom, mongodb driver only
-services/web/lib/db.js                # lazy Mongo client from process.env.MONGODB_URL
+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 todos from Mongo
 services/web/app/todo-form.js         # client form: POST/DELETE via the API
@@ -67,4 +70,4 @@ services/web/app/api/todos/route.js   # GET (list) / POST (add) / DELETE (remove
   `services/web/app/page.js` (e.g. `submissions`, `tasks`, `entries`).
 - Change the document fields (add owners, timestamps, statuses).
 - Add more routes/collections as the app grows.
-- Add `redis: private` to `requires` only if you actually need Redis.
+- Add `cache: true` to `needs:` only if you actually need Redis.

package/src/corpus/templates/app-with-data/cloudgrid.yaml

@@ -1,15 +1,15 @@
-# Rename this app. The grid injects MONGODB_URL (and REDIS_URL if you add a cache)
-# as environment variables at runtime — do NOT set them yourself, and never commit
-# a connection string or secret.
+# Rename this app. The grid injects the DB connection string (and a Redis URL if
+# you add a cache) as environment variables at runtime — do NOT set them
+# yourself, and never commit a connection string or secret.
 #
-# NOTE: use `requires:` (NOT `needs:`). The CLI warns that `requires:` is deprecated,
-# but the deployer currently only injects MONGODB_URL from `requires:` — migrating to
-# `needs:` builds fine but injects NO database connection (every request 500s).
-# Keep `requires:` until CloudGrid's deployer honors `needs:`.
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
 name: my-app
 services:
   web:
     type: nextjs
     path: /
-requires:
-  - mongodb
+needs:
+  database: true

package/src/corpus/templates/app-with-data/index.md

@@ -9,17 +9,19 @@ so it survives refresh and is shared across sessions — unlike a static page.
    root.** `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
    The service named `web` → the CLI looks for `services/web/`. App files at the
    root fail with `Error: Service directory not found: …/services/web`.
-2. **Read `MONGODB_URL` LAZILY (inside the getter), never at module top level.**
-   The grid injects the DB connection string as the `MONGODB_URL` environment
-   variable at dev-time and runtime; the app reads `process.env.MONGODB_URL`
-   inside `getDb`. A top-level `const uri = process.env.MONGODB_URL; if (!uri)
+2. **Read the DB connection string LAZILY (inside the getter), never at module
+   top level.** The grid injects it as the `DATABASE_MONGODB_URL` environment
+   variable (plus the legacy `MONGODB_URL` alias) at dev-time and runtime; the
+   app reads `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL` inside
+   `getDb`. A top-level `const uri = process.env.DATABASE_MONGODB_URL; if (!uri)
    throw` fails `next build` (the module is imported for route analysis before
    the grid injects the var). Never hardcode a connection string; never commit a
    secret.
-3. **Declare the datastore with `requires: [mongodb]` — NOT `needs:`.** The CLI
-   warns `requires:` is deprecated, but the deployer only injects `MONGODB_URL`
-   from `requires:`; `needs:` builds fine but injects NO DB connection (every
-   request 500s). Keep `requires:` until the deployer honors `needs:`.
+3. **Declare the datastore with `needs: { database: true }`.** This is the
+   canonical shape — the deployer provisions Mongo and injects
+   `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). `requires:` is
+   the deprecated v1 alias; don't author new yaml with it, and never set `needs:`
+   and `requires:` together (the validator rejects the combination).
 
 Write these files into the scaffolded app folder — the app code goes under
 `services/web/` — adapt the collection/fields to the user's app, then `grid dev`
@@ -28,9 +30,9 @@ Write these files into the scaffolded app folder — the app code goes under
 ## File tree
 
 ```
-cloudgrid.yaml                          # name + services.web (nextjs) + requires: [mongodb]
+cloudgrid.yaml                          # name + services.web (nextjs) + needs: { database: true }
 services/web/package.json               # next, react, react-dom, mongodb driver only
-services/web/lib/db.js                  # lazy Mongo client from process.env.MONGODB_URL
+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 todos from Mongo
 services/web/app/todo-form.js           # client form: POST/DELETE via the API
@@ -40,23 +42,29 @@ services/web/app/api/todos/route.js     # GET (list) / POST (add) / DELETE (remo
 ## cloudgrid.yaml
 
 ```yaml
-# Rename this app. The grid injects MONGODB_URL (and REDIS_URL if you add a cache)
-# as environment variables at runtime — do NOT set them yourself, and never commit
-# a connection string or secret.
+# Rename this app. The grid injects the DB connection string (and a Redis URL if
+# you add a cache) as environment variables at runtime — do NOT set them
+# yourself, and never commit a connection string or secret.
 #
-# NOTE: use `requires:` (NOT `needs:`). The CLI warns that `requires:` is deprecated,
-# but the deployer currently only injects MONGODB_URL from `requires:` — migrating to
-# `needs:` builds fine but injects NO database connection (every request 500s).
-# Keep `requires:` until CloudGrid's deployer honors `needs:`.
+# `needs: { database: true }` is the canonical, recommended shape. The deployer
+# provisions Mongo and injects DATABASE_MONGODB_URL (plus the legacy MONGODB_URL
+# alias). `requires:` is the deprecated v1 alias — don't author new yaml with it,
+# and never set `needs:` and `requires:` together (the validator rejects it).
 name: my-app
 services:
   web:
     type: nextjs
     path: /
-requires:
-  - mongodb
+needs:
+  database: true
 ```
 
+> **Capability:** this template's need is `database: true`. The deployer
+> provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+> `MONGODB_URL` alias), so an app reading either var works. `requires:` is the
+> deprecated v1 alias — don't mix it with `needs:` (the validator rejects the
+> combination). See the capability-map for the full injection table.
+
 ## services/web/package.json
 
 ```json
@@ -83,22 +91,23 @@ requires:
 ```js
 // Cached MongoDB client for the App Router.
 //
-// The grid injects the connection string as the MONGODB_URL environment variable
-// at runtime (after `grid plug`) and under `grid dev` locally. Never hardcode a
-// connection string here and never commit a secret.
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at runtime (after `grid plug`) and
+// under `grid dev` locally. Read the canonical var first, fall back to the legacy
+// alias. Never hardcode a connection string here and never commit a secret.
 //
 // The env var and client are resolved LAZILY (inside getDb), never at module top
 // level — otherwise `next build` throws when it imports this module for route
-// analysis, before the grid injects MONGODB_URL.
+// analysis, before the grid injects the var.
 import { MongoClient } from "mongodb";
 
 function clientPromise() {
-  const uri = process.env.MONGODB_URL;
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
   if (!uri) {
     throw new Error(
-      "MONGODB_URL is not set. The grid injects it automatically — run this app " +
-        "with `grid dev` locally, or deploy it with `grid plug` (the grid injects " +
-        "MONGODB_URL at runtime). Do not set it by hand.",
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this app with `grid dev` locally, or deploy it with `grid plug` (the grid " +
+        "injects the DB connection string at runtime). Do not set it by hand.",
     );
   }
   if (!globalThis.__mongoClientPromise) {
@@ -109,7 +118,7 @@ function clientPromise() {
 
 export async function getDb() {
   const client = await clientPromise();
-  // The default DB comes from the MONGODB_URL path segment the grid injects.
+  // The default DB comes from the connection-string path segment the grid injects.
   return client.db();
 }
 ```
@@ -257,5 +266,5 @@ export async function DELETE(request) {
 
 - Rename the `todos` collection to your data (`submissions`, `tasks`, `entries`).
 - Change the document fields; add owners/timestamps/statuses.
-- Add `redis: private` to `requires` only if you actually need Redis.
+- Add `cache: true` to `needs:` only if you actually need Redis.
 - Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).

package/src/corpus/templates/app-with-data/services/web/lib/db.js

@@ -1,21 +1,22 @@
 // Cached MongoDB client for the App Router.
 //
-// The grid injects the connection string as the MONGODB_URL environment variable
-// at runtime (after `grid plug`) and under `grid dev` locally. Never hardcode a
-// connection string here and never commit a secret.
+// The grid injects the connection string as the DATABASE_MONGODB_URL environment
+// variable (plus the legacy MONGODB_URL alias) at dev-time (`grid dev`) and
+// runtime (after `grid plug`). Read the canonical var first, fall back to the
+// legacy alias. Never hardcode a connection string here and never commit a secret.
 //
 // The env var and client are resolved LAZILY (inside getDb), never at module top
 // level — otherwise `next build` throws when it imports this module for route
-// analysis, before the grid injects MONGODB_URL.
+// analysis, before the grid injects the var.
 import { MongoClient } from "mongodb";
 
 function clientPromise() {
-  const uri = process.env.MONGODB_URL;
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
   if (!uri) {
     throw new Error(
-      "MONGODB_URL is not set. The grid injects it automatically — run this app " +
-        "with `grid dev` locally, or deploy it with `grid plug` (the grid injects " +
-        "MONGODB_URL at runtime). Do not set it by hand.",
+      "DATABASE_MONGODB_URL is not set. The grid injects it automatically — run " +
+        "this app with `grid dev` locally, or deploy it with `grid plug` (the grid " +
+        "injects the DB connection string at runtime). Do not set it by hand.",
     );
   }
   if (!globalThis.__mongoClientPromise) {
@@ -26,6 +27,6 @@ function clientPromise() {
 
 export async function getDb() {
   const client = await clientPromise();
-  // The default DB comes from the MONGODB_URL path segment the grid injects.
+  // The default DB comes from the connection-string path segment the grid injects.
   return client.db();
 }

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

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/dashboard/index.md

@@ -0,0 +1,30 @@
+# Template: dashboard (static)
+
+A single self-contained HTML dashboard. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "dashboard")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: dashboard
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/deck/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/deck/index.md

@@ -0,0 +1,30 @@
+# Template: deck (static)
+
+A single self-contained HTML deck. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "deck")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: deck
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/landing-page/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/landing-page/index.md

@@ -0,0 +1,30 @@
+# Template: landing-page (static)
+
+A single self-contained HTML landing-page. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "landing-page")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: landing-page
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/templates/report/cloudgrid.yaml

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /

package/src/corpus/templates/report/index.md

@@ -0,0 +1,30 @@
+# Template: report (static)
+
+A single self-contained HTML report. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "report")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: report
+services:
+  web:
+    type: static
+    path: /
+```

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

@@ -0,0 +1,10 @@
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /

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

@@ -0,0 +1,30 @@
+# Template: web-app (static)
+
+A single self-contained HTML web-app. **No infrastructure** — no database, no backend,
+no `needs:`. State (if any) lives only in memory and is lost on refresh.
+
+## How it deploys
+
+To publish this page, use **`gridctl_drop`** (or `gridctl_plug` with the inline
+HTML): it deploys as an **inspiration** — instant, and works on the **hosted**
+edition (Claude Web) as well as local. The reference `cloudgrid.yaml` in this
+directory (`type: static`) is ONLY for plugging the page as an OWNED static
+runtime (async, local edition only); the fast path is `gridctl_drop`.
+
+The fillable HTML is the real template — fetch it with
+`gridctl_fetch("template", "web-app")` and fill in the user's content.
+
+## cloudgrid.yaml (reference only)
+
+```yaml
+# static — deploys as an inspiration (instant, works on hosted) via gridctl_drop;
+# this yaml is only for plugging it as an OWNED static runtime (async, local
+# edition only). To publish the page, prefer gridctl_drop, not grid plug.
+#
+# needs: {}  # none — static, no infrastructure
+name: web-app
+services:
+  web:
+    type: static
+    path: /
+```

package/src/corpus/troubleshooting/persistent-apps.md

@@ -1,7 +1,7 @@
 ---
 name: persistent-apps
-when: A persistent (Mongo-backed) app misbehaves — data doesn't survive refresh, MONGODB_URL is undefined, a runtime deploy seems stuck, or it won't build on hosted.
-summary: Symptom, cause, and fix for the common app-with-data (runtime Mongo app) problems — in-memory vs persistent, injected MONGODB_URL, async deploys, and the hosted-edition gate.
+when: A persistent (Mongo-backed) app misbehaves — data doesn't survive refresh, DATABASE_MONGODB_URL is undefined, a runtime deploy seems stuck, or it won't build on hosted.
+summary: Symptom, cause, and fix for the common app-with-data (runtime Mongo app) problems — in-memory vs persistent, injected DATABASE_MONGODB_URL (+legacy MONGODB_URL), async deploys, and the hosted-edition gate.
 ---
 
 # Troubleshooting: persistent apps (app-with-data)
@@ -12,11 +12,11 @@ Match the symptom to the row, apply the fix, and stop.
 | --- | --- | --- |
 | Data doesn't persist / resets on refresh | You built a static inspiration (in-memory / localStorage), not a runtime app | Use the `app-with-data` workflow: a real Next.js + Mongo runtime that reads `process.env.MONGODB_URL`. Static templates keep state only in memory. |
 | `Error: Service directory not found: …/services/web` | App code lives at the repo/template root, not under the service folder | App code must live under `services/<name>/` (e.g. `services/web/`). `path:` in `cloudgrid.yaml` is the URL mount, NOT the filesystem path — the service name is the folder the CLI looks for. |
-| `next build` fails / MONGODB_URL error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.MONGODB_URL` LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
-| App builds + deploys but every request 500s with `MONGODB_URL not set` | You used `needs:` in `cloudgrid.yaml`; the deployer doesn't inject the DB from `needs:` yet | Switch to `requires: [mongodb]`. The CLI warns `requires:` is deprecated, but the deployer only injects `MONGODB_URL` from `requires:` (platform bug flagged to Gilad). Keep `requires:` until `needs:` is honored. |
-| `MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `MONGODB_URL` at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
+| `next build` fails / DB connection error at build time | The DB env var is read at module top level; `next build` imports the module for route analysis before the grid injects the var | Read `process.env.DATABASE_MONGODB_URL` (with a legacy `MONGODB_URL` fallback) LAZILY inside the getter (e.g. inside `getDb`), never at module load. Moving the check into the function lets the build pass. |
+| App builds + deploys but every request 500s with `DATABASE_MONGODB_URL not set` | The datastore isn't declared, or you declared the deprecated `requires:` instead of `needs:` | Declare `needs: { database: true }` in `cloudgrid.yaml`. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). Never set `needs:` and `requires:` together (the validator rejects it). |
+| `DATABASE_MONGODB_URL is undefined` (or the db.js guard throws) | The env var isn't present because you're not running under the grid | Run locally with `grid dev`, or deploy with `grid plug` — the grid injects `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) at dev-time and runtime. Do NOT set it yourself and never hardcode a connection string. |
 | Deploy seems stuck / no URL returned | Runtime deploys are asynchronous | `plug` returns `status: building`, not a URL. Poll `gridctl_status` (or the poll_url) until the app is live, then return the live URL. Don't treat the build/log link as the deliverable. |
 | It won't build on the hosted edition | Hosted MCP is inline-only — it can't run the CLI or folder-plug | Runtime apps need the LOCAL edition (Claude Desktop/Code) or the CLI. On hosted, tell the user persistence isn't available there and offer a static version instead. |
-| Redis not available | `redis` wasn't declared | Add `redis: private` to `requires` in `cloudgrid.yaml`; the grid then injects `REDIS_URL`. Only add it if the app actually needs Redis. |
+| Redis not available | `cache` wasn't declared | Add `cache: true` to `needs:` in `cloudgrid.yaml`; the grid then injects `CACHE_REDIS_URL` (plus the legacy `REDIS_URL` alias). Only add it if the app actually needs Redis. |
 
 See the `app-with-data` workflow for the full recipe.