@cloudgrid-io/mcp 0.11.0 → 0.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "MCP server for CloudGrid. Three editions: a local stdio server (full toolset), a hosted web server (light, CLI-free toolset), and a public docs server (search_cloudgrid_documentation) over MCP Streamable HTTP.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "test:source": "node test/source-fetch.test.mjs",
     "test:app-with-data": "node test/app-with-data.test.mjs",
     "test:self-describing": "node test/self-describing.test.mjs",
+    "test:canonical-yaml": "node test/canonical-yaml.test.mjs",
     "test:content": "node test/content-handling.test.mjs",
     "test:self-healing": "node test/self-healing.test.mjs",
     "test:grid-picker": "node test/grid-picker.test.mjs",

package/src/corpus/capability-map.md

@@ -8,7 +8,10 @@ template by its `when:` triggers, adopt that template's `needs:`, then deploy:
 - **anything needing `needs:` → runtime** (async build, **local edition** only)
   via `gridctl_plug` on a linked folder.
 
-Fetch this doc any time with `gridctl_fetch("doc", "capability-map")`.
+Fetch this doc any time with `gridctl_fetch("doc", "capability-map")`. For the full
+cloudgrid.yaml schema (every field, the `needs:` injection table, the
+requires-vs-needs caveat, validation rules), fetch the companion reference:
+`gridctl_fetch("doc", "cloudgrid-yaml")`.
 
 ## The 6 templates
 
@@ -29,35 +32,35 @@ users/sessions, log in, or store submissions → it is persistent → `app-with-
 
 `needs:` is a MAP declaring infrastructure capabilities. Values are `true` or an
 engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
-`schedule` + `timezone`). See the cloudgrid.yaml reference §5, §12, §14.
+`schedule` + `timezone`). See the full cloudgrid.yaml reference §5–§6 via
+`gridctl_fetch("doc", "cloudgrid-yaml")`.
 
 | `needs:` key | Provides | Injected env var(s) | Status |
 |---|---|---|---|
-| `database: true` | MongoDB primary datastore | `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) | **Today via `requires: [mongodb]`** — `needs:` pending #1527 |
-| `cache: true` | Redis, LRU eviction | `CACHE_REDIS_URL` (+legacy `REDIS_URL`) | **Today via `requires: [redis]`** — `needs:` pending #1527 |
-| `kv: true` | Redis, no eviction | `KV_REDIS_URL` | Pending #1527 |
-| `queue: true` | Redis durable job queue | `QUEUE_REDIS_URL` | Pending #1527 |
-| `pubsub: true` | Redis pub/sub broadcast | `PUBSUB_REDIS_URL` | Pending #1527 |
-| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | Pending #1527 |
-| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | Pending #1527 |
-| `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Pending #1527 |
-| `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | **Today** (AI Gateway) |
+| `database: true` | MongoDB primary datastore | `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) | **Injects via `needs:`** |
+| `cache: true` | Redis, LRU eviction | `CACHE_REDIS_URL` (+legacy `REDIS_URL`) | **Injects via `needs:`** |
+| `kv: true` | Redis, no eviction | `KV_REDIS_URL` | Injects via `needs:` |
+| `queue: true` | Redis durable job queue | `QUEUE_REDIS_URL` | Injects via `needs:` |
+| `pubsub: true` | Redis pub/sub broadcast | `PUBSUB_REDIS_URL` | Injects via `needs:` |
+| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | **Injects via `needs:`** |
+| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | Injects via `needs:` |
+| `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Injects via `needs:` |
+| `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | Injects via `needs:` |
 | `type: cron` (service) | Scheduled job (`schedule`, `timezone`) | — | Service type, not a need |
 
-### Injection status — today vs pending #1527
+### Injection status
 
-- **Injects TODAY:** `database` and `cache` — but ONLY via the deprecated
-  `requires:` field (`requires: [mongodb]` → `MONGODB_URL`; `requires: [redis]`
-  → `REDIS_URL`). `needs:`-based provisioning does NOT inject anything on the
-  live deployer yet (bug #1527). `ai` (AI Gateway) is available today.
-- **Pending #1527:** `needs:`-based provisioning for everything — `vector`,
-  `queue`, `pubsub`, `kv`, `object_storage`, `disk`, and `needs: database` /
-  `needs: cache` once the deployer honors `needs:`.
+- **`needs:` injects the connection env vars today.** `needs: { database: true }`
+  → `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`); `needs: { cache: true }` →
+  `CACHE_REDIS_URL` (+legacy `REDIS_URL`); `needs: { vector: pgvector }` →
+  `VECTOR_PGVECTOR_URL`; and so on across the nine needs. Author `needs:`.
+  (*Historical note: the deployer once did not inject from `needs:` — platform
+  bug #1527, now fixed and verified live.*)
+- **`requires:` is the deprecated v1 alias.** Don't author new yaml with it.
 - **`needs:` and `requires:` cannot both be active** in one yaml — the validator
-  rejects the combination ("use one or the other"). So a DB template ships
-  `requires: [mongodb]` active with the canonical `needs: { database: true }`
-  shown only as a **comment** (and declared in the workflow frontmatter as
-  metadata), flipping to `needs:` when #1527 lands.
+  rejects the combination ("use one or the other"). So a DB template ships the
+  canonical `needs: { database: true }` active, with NO `requires:` (and declares
+  `needs: database` in the workflow frontmatter as metadata).
 
 ## How to choose
 

package/src/corpus/cloudgrid-yaml.md

@@ -0,0 +1,569 @@
+# cloudgrid.yaml reference — the full manifest schema for agents
+
+> **Canonical source:** `cloudgrid-yaml-reference.md` in the CloudGrid platform
+> repo. This is the agent-facing distribution
+> of that reference — practically complete, not a verbatim dump. **Keep in sync**
+> with the upstream: when the platform reference changes, update this doc.
+>
+> Fetch this doc any time with `gridctl_fetch("doc", "cloudgrid-yaml")`.
+> For matching an intent to a template, see the companion
+> `gridctl_fetch("doc", "capability-map")`.
+
+`cloudgrid.yaml` is the manifest at the **root of your project** that defines your
+entity (an app or an agent). It declares the services your entity runs, the
+infrastructure it needs, and how it behaves. `grid init` creates it; `grid plug`
+reads it to build and deploy.
+
+**Wiring a database or cache? Use `needs:`** — `needs: {database: true}` is
+canonical and the deployer injects the connection env vars from it. See §7 for the
+`needs:`-vs-`requires:` note. `requires:` is the deprecated v1 alias; don't author
+new yaml with it.
+
+---
+
+## 1. Minimal, real, deployable examples
+
+These are the shapes verified against live deploys. Copy one and adapt it.
+
+### Static site → deploys as an inspiration (instant)
+
+A single-file / static bundle. No `needs:`. Publishes instantly via
+`gridctl_drop`, works on any edition (hosted or local).
+
+```yaml
+name: landing-page
+services:
+  web:
+    type: static
+    path: /
+```
+
+### Node.js app
+
+Code lives under `services/web/` (`src/index.js` + `package.json`). Runtime deploy
+(async, local edition only).
+
+```yaml
+name: my-api
+services:
+  web:
+    type: node
+    path: /
+```
+
+### Next.js app
+
+```yaml
+name: my-dashboard
+services:
+  web:
+    type: nextjs
+    path: /
+```
+
+### Next.js + database — the canonical shape
+
+Declare the datastore with `needs: {database: true}`. The deployer provisions
+Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias) at
+dev-time and runtime. `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). See §7 for the details.
+
+This mirrors the live-verified `app-with-data` template exactly: app code under
+`services/web/`, and the app reads `process.env.DATABASE_MONGODB_URL` (falling
+back to the legacy `MONGODB_URL`) **lazily** (inside a getter, never at module top
+level — a top-level read fails `next build`).
+
+```yaml
+# 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.
+#
+# `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: my-app
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+### Agent — a cron job
+
+An agent is an app with `kind: agent` and an `agent:` block. Cron is a **service
+type**, not a need. `type: cron` requires a `schedule` and cannot have `path` or
+`port`.
+
+```yaml
+name: nightly-sync
+kind: agent
+agent:
+  purpose: Sync data from an external API every night
+services:
+  sync:
+    type: cron
+    schedule: "0 9 * * *"   # 9am daily
+    timezone: UTC
+```
+
+> A cron/agent that also needs a database declares it the canonical way:
+> `needs: {database: true}` (not the deprecated `requires:`).
+
+---
+
+## 2. Full annotated example (the kitchen sink)
+
+Every supported field, commented. **No real project uses all of these at once** —
+this is a reference, not a template. (The `needs:` block here is the canonical
+schema — the deployer injects the connection env vars from it; see §7.)
+
+```yaml
+# ─── Identity ───────────────────────────────────────────────────────
+name: my-app                        # Entity slug (required). 2-42 chars, lowercase + hyphens.
+description: Order processing API   # One-line summary (max 280 chars). Optional.
+icon: "📦"                          # Single emoji or short text (max 64 chars). Optional.
+kind: app                           # 'app' (default) or 'agent'. Optional.
+
+# ─── Networking ─────────────────────────────────────────────────────
+expose: true                        # Serve public HTTP traffic (default: true).
+                                    # Set to false for internal-only entities.
+custom_domains:                     # Additional FQDNs the entity serves on. Optional.
+  - orders.example.com
+
+# ─── Health probe (entity-level override) ───────────────────────────
+probe:                              # HTTP health probe override. Optional.
+  path: /healthz                    # Probe path (default: /).
+  expected: "<500"                  # Expected status: '<500' (default), '200', '2xx'.
+
+# ─── Deploy notifications ──────────────────────────────────────────
+notify: true                        # Slack notification on deploy failure (default: true).
+
+# ─── Scaling ────────────────────────────────────────────────────────
+scale: auto                         # 'auto' (default), 'alert', or integer 1-10.
+
+# ─── Infrastructure needs (v2, CANONICAL — the deployer injects from these) ─
+needs:
+  database: true                    # Mongo (org-tier). Injects DATABASE_MONGODB_URL.
+  cache: true                       # Redis with LRU eviction. Injects CACHE_REDIS_URL.
+  kv: true                          # Redis, no eviction. Injects KV_REDIS_URL.
+  queue: true                       # Redis for BullMQ etc. Injects QUEUE_REDIS_URL.
+  pubsub: true                      # Redis pub/sub. Injects PUBSUB_REDIS_URL.
+  vector: pgvector                  # pgvector. Injects VECTOR_PGVECTOR_URL.
+  object_storage: true              # GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET.
+  disk: true                        # Persistent filesystem at /data. Injects DISK_PATH.
+  ai: true                          # AI Gateway access. Injects AI_GATEWAY_URL.
+
+# ─── Inter-entity communication ────────────────────────────────────
+calls:                              # Entities this app calls (outbound grants).
+  - org:atomic/billing-api
+  - org:atomic/content-service
+
+callers:                            # Inbound caller policy.
+  policy: auto                      # 'auto' or 'manual' (default: 'manual').
+  scope: org                        # 'org', 'space', or 'explicit' (default: 'org').
+  fallback: deny                    # 'deny' or 'warn' (default: 'deny').
+
+# ─── Vault ──────────────────────────────────────────────────────────
+vault:                              # Map of ENV_VAR: vault_item_key. Optional.
+  STRIPE_KEY: stripe-live-key
+  SENDGRID_API_KEY: sendgrid-key
+
+# ─── Connectors and hooks ──────────────────────────────────────────
+connectors:
+  - id: team-slack
+    target: org                     # 'system' or 'org'
+    channel: "#deploys"
+
+hooks:                              # Outbound events. on ∈ release.published |
+  - on: deploy.failed               #   deploy.failed | feedback.received | entity.created
+    via: team-slack                 # Must match a connector id above.
+    template: "Deploy failed for {entity_name}: {error}"
+
+triggers:                           # Inbound events routed into your app.
+  - from: team-slack
+    event: message
+    channel: "#support"
+    route: /webhooks/slack          # Path in your app that receives the POST.
+
+# ─── Local development ─────────────────────────────────────────────
+dev:
+  snapshot:
+    mask:                           # Fields to redact in dev snapshots (collection.field).
+      - users.email
+      - users.phone
+
+# ─── Services ──────────────────────────────────────────────────────
+services:
+  web:
+    type: nextjs                    # 'node', 'nextjs', 'python', 'static', or 'cron'.
+    path: /                         # HTTP route prefix. false = internal-only.
+    port: 3000                      # Container port (default: 8080).
+    base_image: distroless          # 'alpine' or 'distroless' (nextjs only).
+    health:                         # Health probe config.
+      path: /api/health
+      expected: "200"
+    env:                            # Static env vars (not secrets).
+      LOG_LEVEL: info
+    depends_on:                     # Wait for these before starting.
+      - worker
+
+  worker:
+    type: node
+    path: false                     # No public URL — internal service.
+    source:
+      path: src/worker              # Custom source location (instead of services/worker/).
+    needs:                          # Per-service needs override (merged per-key).
+      queue: true                   # Adds queue (inherits database, cache from app-level).
+    persist:                        # Service-level persistence.
+      - name: scratch
+        path: /tmp/scratch
+        size: 500Mi
+
+  reports:
+    type: cron
+    schedule: "0 9 * * 1"           # Every Monday at 9am.
+    timezone: UTC                   # 'UTC', 'EST', or 'PST'.
+    run: job                        # 'job' (run code) or an HTTP URL.
+
+  frontend:
+    type: static
+    path: /app
+    build:                          # Build step for static sites.
+      command: npm run build
+      output: dist
+      env:
+        VITE_API_URL: https://api.example.com
+    node_version: "22"              # Node version for build: '18', '20', '22', '24'. STRING, not int.
+```
+
+---
+
+## 3. Top-level fields
+
+### Required
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Entity slug. 2-42 chars, lowercase alphanumeric + hyphens, starts/ends with a letter or digit. Becomes part of the public URL. |
+| `services` | map | One or more named service configs. See §4. |
+
+### Optional
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `description` | string | — | One-line summary, max 280 chars. Auto-generated by Grid Brain if unset. |
+| `icon` | string | — | Single emoji or short text, max 64 chars. |
+| `kind` | string | `app` | `app` or `agent` (an agent is an app with an `agent:` block). |
+| `expose` | boolean | `true` | Whether the entity serves public HTTP. `false` = internal-only. |
+| `custom_domains` | string[] | — | Additional FQDNs served. |
+| `probe` | object | — | Entity-level health probe override: `{ path, expected }`. |
+| `notify` | boolean | `true` | Slack notification on deploy failure. |
+| `scale` | string \| int | `auto` | `auto`, `alert`, or integer 1-10. |
+| `needs` | object | — | Infrastructure capabilities (canonical). See §5 + caveat box. |
+| `calls` | string[] | — | Entities this app calls outbound. |
+| `callers` | object | — | Inbound caller policy. |
+| `vault` | map | — | `ENV_VAR: vault_item_key` mappings. |
+| `connectors` / `hooks` / `triggers` | array | — | Connector refs, outbound event hooks, inbound trigger webhooks. |
+| `dev` | object | — | Local development config (`grid dev`). |
+| `agent` | object | — | Agent metadata (loosely typed: `purpose`, `schedule`, `trigger`). |
+| `auto_depends_on_private_requires` | boolean | `true` | Auto-inject private resources as service deps. |
+
+### Deprecated (still accepted)
+
+| Field | Replacement | Notes |
+|-------|-------------|-------|
+| `domain` | `custom_domains` | Single custom domain string. |
+| `network` | `expose` | `{ public: bool }`. |
+| `requires` | `needs` | v1 infra requirements. Deprecated — author `needs:` instead. **Cannot be mixed with `needs`** (the validator rejects the combination). |
+| `persist` (top-level) | `needs.disk` | v1 entity-level filesystem persistence. |
+
+---
+
+## 4. Services
+
+Each service is a named entry under `services:`. The name is the service identifier
+(same slug rules as the entity name). **By default, a service's code lives at
+`services/<service-name>/`** — `path:` is the URL mount, NOT the filesystem path. A
+service named `web` → the CLI looks for `services/web/`. (Override with `source.path`.)
+
+### Service types
+
+| Type | What it runs | Required files | Default port | `path`? |
+|------|-------------|----------------|--------------|---------|
+| `node` | Node.js server | `src/index.js` (or `.ts`), `package.json` | 8080 | yes |
+| `nextjs` | Next.js app (standalone output) | `next.config.*`, `package.json` | 8080 | yes |
+| `python` | Python server | `src/main.py`, `requirements.txt` | 8080 | yes |
+| `static` | Static files served by nginx (optional `build`) | `index.html` or build output | 8080 | yes |
+| `cron` | Scheduled job | `src/job.js` or `src/main.py` | none | **no** — needs `schedule`, no `path`/`port` |
+
+### Service fields
+
+| Field | Type | Required | Default | Applies to |
+|-------|------|----------|---------|-----------|
+| `type` | string | Yes | — | All |
+| `path` | string \| `false` | No | — | All except cron |
+| `port` | integer (1-65535) | No | 8080 | All except cron |
+| `lang` | string | No | — | node only (`javascript` \| `typescript`) |
+| `base_image` | string | No | `distroless` | nextjs only (`alpine` \| `distroless`) |
+| `source` | object | No | — | All — `{ path }`, default `services/<name>/`, `.` = project root |
+| `build` | object | No | — | static only — `{ command, output, env }` |
+| `node_version` | string | No | `"22"` | static build (`"18"`/`"20"`/`"22"`/`"24"` — STRING) |
+| `health` | bool \| string \| object | No | TCP | All except cron |
+| `env` | map (string values) | No | — | All (reserved names forbidden) |
+| `schedule` | string (cron) | Required for cron | — | cron only |
+| `run` | string | No | `job` | cron only (`job` or an HTTP URL) |
+| `timezone` | string | No | `UTC` | cron only (`UTC`/`EST`/`PST`) |
+| `depends_on` | string[] | No | — | All except cron (no self/circular, no cron) |
+| `persist` | bool \| array | No | — | All except cron |
+| `needs` | object | No | — | All (overrides/extends app-level per-key) |
+
+### `path` — HTTP routing
+
+`"/"` serves at root; `"/api"` under a prefix; `false` = internal only (no public
+URL); omitted = treated as `false` with a soft warning. **Only one service can
+claim `"/"`.**
+
+### `source` — custom source location
+
+```yaml
+source:
+  path: src/worker   # relative to project root; no leading /, no .., no globs
+```
+
+Use `.` for a flat layout where the service code lives at the project root:
+
+```yaml
+services:
+  web:
+    type: node
+    path: /
+    source:
+      path: .
+```
+
+### `build` — static site build step (static only)
+
+```yaml
+build:
+  command: npm run build       # required
+  output: dist                 # built output dir (default: dist)
+  env:
+    VITE_API_URL: https://api.example.com
+```
+
+### `health` — probe config
+
+Omitted / `false` → TCP probe. `true` → HTTP at `/health`. `"/healthz"` → HTTP at
+that path. `{ path, expected }` → HTTP with expected status
+(`healthy` (default, 2xx/3xx), `<500`, `200`, `2xx`).
+
+### `env` — static environment variables
+
+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
+`grid secrets set` for sensitive values.
+
+### Per-service `needs` override
+
+Merge is per-key — service values override app-level for that key; absent keys
+inherit:
+
+```yaml
+needs:            # App-level
+  database: true
+  cache: true
+  pubsub: true
+services:
+  worker:
+    type: node
+    path: false
+    needs:
+      queue: true      # Added
+      pubsub: false    # Overridden (opted out)
+    # Effective: database: true, cache: true, queue: true, pubsub: false
+```
+
+---
+
+## 5. Needs (infrastructure) — the nine needs
+
+The `needs:` block declares infrastructure capabilities; the platform provisions
+them and injects connection details as env vars. **Cron is NOT a need — it is a
+service type.**
+
+| Need | Provides | Injected env var(s) | Backing |
+|------|----------|---------------------|---------|
+| `database` | Primary datastore | `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`) | MongoDB |
+| `cache` | Key-value store, LRU eviction | `CACHE_REDIS_URL` (+legacy `REDIS_URL`) | Redis |
+| `kv` | Key-value store, no eviction | `KV_REDIS_URL` | Redis |
+| `queue` | Durable job queue substrate | `QUEUE_REDIS_URL` | Redis |
+| `pubsub` | Broadcast pub/sub | `PUBSUB_REDIS_URL` | Redis |
+| `vector` | Vector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | pgvector (Postgres) |
+| `object_storage` | Object/blob bucket | `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 |
+
+`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
+three run `noeviction` (durable data).
+
+### Usage forms
+
+```yaml
+needs:
+  database: true                                # Grid decides tier
+  database: pool                                # Shared Mongo (free)
+  database: dedicated                           # Entity-private Mongo
+  database: { tier: external, secret: MY_DB }   # Bring your own (value from vault)
+
+  cache: true                                   # Platform Redis
+  cache: { engine: external, secret: MY_REDIS } # Bring your own (same forms for kv/queue/pubsub)
+
+  vector: true                                  # Platform default engine
+  vector: pgvector                              # pgvector explicitly
+  vector: { engine: pgvector, dim: 1536 }       # With dimension hint
+
+  object_storage: true                          # Default size (100MB)
+  object_storage: { size: 10Gi }                # Custom size
+
+  disk: true                                    # 50MB at /data
+  disk: { size: 1Gi, mount: /var/data }         # Custom (forbidden mounts: /proc, /sys, /dev)
+
+  ai: true                                      # Enable AI Gateway (ai: false = disabled, default)
+```
+
+### Injected environment variables
+
+**Always injected** (do not set these yourself):
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Port your service should listen on (your `port:` or 8080). |
+| `APP_NAME` | Entity slug. |
+| `SERVICE_NAME` | Service name (the key under `services:`). |
+| `NODE_ENV` | `production` in deployed environments. |
+
+**Per `needs:` declaration:** as in the table above. Legacy aliases
+(`MONGODB_URL`, `REDIS_URL`, `PGVECTOR_URL`) are injected alongside the canonical
+names during the transition; new apps should read the canonical names
+(`DATABASE_MONGODB_URL`, etc.) with the legacy name as a fallback.
+
+### Persistence (disk)
+
+Two ways to declare filesystem persistence — use `needs.disk` (recommended) or
+service-level `persist:` (fine-grained). Do not mix the entity-level flag form and
+the service-level verbose array form.
+
+```yaml
+# Recommended:
+needs:
+  disk: { size: 1Gi, mount: /var/sqlite }
+
+# Fine-grained, per-service:
+services:
+  web:
+    type: node
+    path: /
+    persist:
+      - name: db
+        path: /data/sqlite
+        size: 1Gi
+```
+
+Persistence pins the service to 1 replica with a `Recreate` rollout strategy
+(single-writer constraint).
+
+---
+
+## 6. Validation rules (the ones agents trip on)
+
+The platform validates `cloudgrid.yaml` at plug time — strictly.
+
+1. **No `Dockerfile`.** Images are generated from `services.*.type`; a Dockerfile
+   is silently ignored.
+2. **No `org:` or `entity_id:` in the YAML.** Identity lives in
+   `.cloudgrid/link.json` (gitignored), not the manifest.
+3. **No mixing `requires:` and `needs:`.** Use one or the other — the validator
+   rejects the combination. Author `needs:` (canonical); `requires:` is the
+   deprecated v1 alias.
+4. **No mixed persistence forms.** Entity-level flag form and service-level
+   verbose array form cannot coexist.
+5. **Unknown fields are rejected** with a "did you mean?" suggestion.
+6. **Reserved env var names cannot be set** in `services.*.env` (see §4 `env`).
+7. **`port` must be an integer 1-65535** (not a float). Forbidden on `type: cron`.
+8. **`depends_on`:** no self-references, no circular dependencies, no references to
+   cron services.
+9. **`node_version` must be a string** (`"22"`, not `22`).
+10. **Cron services require `schedule`** and cannot have `path` or `port`.
+11. **Entity names** must match `^[a-z][a-z0-9-]*[a-z0-9]$` (2-42 chars) — no
+    leading/trailing hyphens.
+
+### File layout
+
+```
+my-app/
+├── cloudgrid.yaml
+├── .cloudgrid/link.json      # gitignored; local binding to the server-side entity
+├── services/
+│   ├── web/                  # service "web" → services/web/
+│   │   ├── package.json
+│   │   └── src/index.js
+│   └── worker/
+│       ├── package.json
+│       └── src/index.js
+└── .gitignore                # includes .cloudgrid/
+```
+
+Use `source.path: .` for a flat project where the code lives at the root.
+
+---
+
+## 7. `needs:` vs `requires:` — and the live deploy mechanics (READ THIS)
+
+Bake these into any yaml you author:
+
+- **`needs:` is canonical and it injects.** `needs: {database: true}` provisions
+  Mongo and injects the connection env vars — `DATABASE_MONGODB_URL` plus the
+  legacy `MONGODB_URL` alias. Likewise `cache: true` → `CACHE_REDIS_URL` (+legacy
+  `REDIS_URL`), `vector: pgvector` → `VECTOR_PGVECTOR_URL` (+legacy
+  `PGVECTOR_URL`), and so on across the nine needs (see §5). An app reading the
+  legacy names keeps working because the aliases are injected alongside.
+  (*Historical note: the deployer once did not inject from `needs:` — platform
+  issue #1527, now fixed and verified live. The old `requires:` workaround is
+  obsolete.*)
+- **`requires:` is the deprecated v1 alias** — `requires: [mongodb]` /
+  `requires: [redis]`. The CLI warns it's deprecated. **Don't author new yaml with
+  it**; use `needs:` instead.
+- **`needs:` and `requires:` together are HARD-REJECTED** by the validator ("use
+  one or the other"). So author **`needs:`-only** — never set both.
+- **Static single-file pages deploy as inspirations** via `gridctl_drop` — instant,
+  synchronous, works on the hosted edition and any client.
+- **A `cloudgrid.yaml` with `services:` makes it a runtime** — async build,
+  **local edition only** (Claude Desktop/Code or the CLI, not hosted). `plug`
+  returns `status: building`; poll status until live, then use the returned live
+  URL. Re-plug the same entity to update the same URL.
+- **Read injected env vars lazily** (inside a getter/handler), never at module top
+  level — a top-level read of `DATABASE_MONGODB_URL` fails `next build`, which
+  imports the module for route analysis before the grid injects the var.
+
+The canonical DB shape (mirrors the `app-with-data` template):
+
+```yaml
+name: my-app
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+---
+
+*This doc is the agent-facing distribution of the platform's canonical
+`cloudgrid-yaml-reference.md`. See also `gridctl_fetch("doc", "capability-map")`
+for matching a user intent to a template + the `needs:` injection status.*

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,19 +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: /
-# Canonical capability (metadata): this app needs a database.
-# When #1527 lands (deployer honors needs:), replace requires: with:
-#   needs:
-#     database: true
-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,32 +42,28 @@ 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: /
-# Canonical capability (metadata): this app needs a database.
-# When #1527 lands (deployer honors needs:), replace requires: with:
-#   needs:
-#     database: true
-requires:
-  - mongodb
+needs:
+  database: true
 ```
 
-> **Capability:** this template's canonical need is `database: true` (see the
-> commented block above and the capability-map). The deployed yaml keeps
-> `requires: [mongodb]` because only `requires:` injects `MONGODB_URL` today
-> (#1527); `needs:` and `requires:` cannot co-exist active in the same yaml, so
-> the canonical `needs:` is shown only as a comment until the deployer honors it.
+> **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
 
@@ -93,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) {
@@ -119,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();
 }
 ```
@@ -267,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/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.

package/src/corpus/workflows/app-with-data.md

@@ -4,8 +4,8 @@ when: to-do, task list, notes app, guestbook, CRUD app, form that SAVES/STORES s
 needs: database
 deploy: runtime
 editions: local
-capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Canonical need is `database: true` (metadata); the deployed yaml uses `requires: [mongodb]` until #1527 lands.
-summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.MONGODB_URL lazily, declare requires:[mongodb] (not needs:), deploy async, poll to a live URL.
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a real persistent Next.js + Mongo runtime app on the grid — edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
 ---
 
 # Workflow: app-with-data
@@ -48,7 +48,7 @@ the entity + `.cloudgrid/link.json` and writes a `cloudgrid.yaml` with an EMPTY
 `services: {}`. `plug` needs a linked directory, so run `init` FIRST.
 
 You then do two things: (a) write the app under **`services/web/`**, and (b) fill
-in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
+in `cloudgrid.yaml` to the shape below (`services.web` + `needs: { database: true }`).
 
 ## 4. Add the datastore + wire Mongo
 
@@ -63,27 +63,28 @@ in `cloudgrid.yaml` to the shape below (`services.web` + `requires: [mongodb]`).
      web:
        type: nextjs
        path: /
-   requires:
-     - mongodb        # alias: db
-     # - redis: private   # OPTIONAL — add only if the app needs Redis
+   needs:
+     database: true
+     # cache: true      # OPTIONAL — add only if the app needs Redis
    ```
-   **Declare the datastore with `requires: [mongodb]` (NOT `needs:`)** — see the
-   yaml comment in the template. 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:`.
+   **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) at dev-time and
+   runtime. `requires:` is the deprecated v1 alias; don't author new yaml with it,
+   and never set `needs:` and `requires:` together (the validator rejects it).
 2. Fetch the template for the Mongo wiring + CRUD shape:
    `gridctl_fetch("template", "app-with-data")`. It is a minimal, real
    Next.js + `mongodb`-driver to-do app under `services/web/`: a lazy client in
    `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `todos`
    collection, and a page.
 3. Adapt it to the user's app (rename the collection, change the fields, adjust
-   the UI). **Read the database from `process.env.MONGODB_URL`** — the grid
-   injects that env var at dev-time and runtime. Never hardcode a connection
-   string; never commit a secret.
-   - **Put the DB connection behind a lazy getter — never read
-     `process.env.MONGODB_URL` at module top level, or `next build` fails** (the
-     module is imported for route analysis before the grid injects the var).
+   the UI). **Read the database from `process.env.DATABASE_MONGODB_URL`** (falling
+   back to the legacy `process.env.MONGODB_URL`) — the grid injects those env vars
+   at dev-time and runtime. Never hardcode a connection string; never commit a
+   secret.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails** (the module is imported
+     for route analysis before the grid injects the var).
    - (Optional) fetch `gridctl_fetch("example", "app-with-data")` for a slightly
      richer filled reference to imitate.
 
@@ -96,7 +97,9 @@ and sanity-check before deploying. Don't require it.
 
 - API keys / secrets → `gridctl_secrets`.
 - Non-secret config → `gridctl_env`.
-- Do **NOT** set `MONGODB_URL` or `REDIS_URL` yourself — the grid injects them.
+- Do **NOT** set the DB/cache connection vars yourself (`DATABASE_MONGODB_URL`,
+  `CACHE_REDIS_URL`, or their legacy `MONGODB_URL` / `REDIS_URL` aliases) — the
+  grid injects them.
 
 ## 7. Deploy (async)
 

package/src/tools.js

@@ -90,6 +90,7 @@ Operating rules:
 10. Publishing a heavy or local file: in the local edition use the path parameter so it is read from disk (no inline size limit); never base64-encode HTML and never pass a file path (or an @-prefixed path) as html. If a drop looks empty, use gridctl_source to check what was actually published, then re-plug with the real HTML/path and target_entity_id.
 11. Persistence check: if the user needs to SAVE data, share state across users/sessions, log in, or store submissions, that's a runtime app-with-data (Mongo-backed), NOT a static page — static templates keep state only in memory and lose it on refresh. Use the app-with-data workflow. This requires the LOCAL edition (Claude Desktop/Code or the CLI); on the hosted edition, tell the user persistence isn't available there and offer a static version.
 12. To choose what to build: match the request against the workflow when: triggers and the capability-map (gridctl_fetch({kind:"doc", name:"capability-map"})). Pick the template whose needs: matches what the app requires (persistence → database; scheduled → cron; etc.). Static (needs: none) deploys as an inspiration (instant, any edition); anything needing needs: is a runtime (async, local edition).
+13. Before writing a cloudgrid.yaml, fetch the reference: gridctl_fetch({kind:"doc", name:"cloudgrid-yaml"}) — it has the full schema, the needs: vocabulary, and the requires-vs-needs caveat (the deployer does not inject from needs: yet, so a database/cache today uses requires: [mongodb] / requires: [redis]).
 
 Deploy is edition-dependent: on the hosted MCP call the drop tool with the HTML; on local MCP / CLI write the file and run the plug tool. An HTML page deploys synchronously, so you get a URL right away.`;