@cloudgrid-io/mcp 0.12.0 → 0.14.0

package/src/corpus/templates/booking-system/index.md

@@ -0,0 +1,86 @@
+# Template: booking-system (BLUEPRINT — Next.js + Mongo reservations)
+
+A blueprint for an appointment / reservation booking system. Data lives in
+grid-shared MongoDB so bookings survive refresh and are shared across sessions —
+a runtime app, not a static page. This bundle ships the annotated `cloudgrid.yaml`
+and the `AGENTS.md` structure guide, NOT prewritten app code.
+
+**This is a blueprint: structure + cloudgrid.yaml, adapt and build.** Fetch it,
+read `AGENTS.md`, then build the app under `services/web/` following the file
+tree and data model there. The proven runtime shape is the same as
+`app-with-data` (lazy Mongo client under `services/web/`).
+
+**Key rules:**
+
+1. **Service code MUST live under `services/<name>/`, not the repo root.** `path:`
+   in `cloudgrid.yaml` is the URL mount, NOT the filesystem path. The service
+   named `web` → the CLI looks for `services/web/`. Root files fail with
+   `Error: Service directory not found: …/services/web`.
+2. **Read injected vars LAZILY (inside getters), never at module top level.** The
+   grid injects `DATABASE_MONGODB_URL` (legacy `MONGODB_URL` alias) from
+   `needs: { database: true }`, and the `vault:` secrets (`STRIPE_KEY`,
+   `STRIPE_WEBHOOK_SECRET`, `AUTH_PROVIDER_KEY`) as env vars. A top-level read
+   fails `next build`. Never hardcode a key; never commit a secret.
+3. **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. `requires:` is the deprecated v1 alias; don't author new yaml with it,
+   and never set `needs:` and `requires:` together (the validator rejects it).
+4. **Payment/auth secrets go through the `vault:` block**, resolved to env vars
+   at deploy — add the vault items with `grid secrets set` before plug.
+5. **The reminder cron service is NOT yet deployable** (platform issue #1543).
+   Keep the `reminders:` cron COMMENTED and ship `web` alone; see `AGENTS.md` §7.
+
+## cloudgrid.yaml
+
+```yaml
+# On disk this file is the full-annotated reference (templates/_cloudgrid.yaml.reference) with EVERY
+# field present as a comment; only the fields below are uncommented, so it
+# deploys to exactly these active fields. (A commented `reminders:` cron service
+# shows the intended — not-yet-deployable — shape; see AGENTS.md §7.)
+name: booking-system
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-key
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+> **Capability:** need is `database: true` — the deployer provisions Mongo and
+> injects `DATABASE_MONGODB_URL` (plus the legacy `MONGODB_URL` alias). Secrets
+> come from the `vault:` block as env vars. See the capability-map for the full
+> injection table.
+
+## AGENTS.md — the structure guide
+
+The heart of this blueprint. Read it before building. It covers:
+
+1. **File tree** — `services/web/{app/, lib/, api routes, package.json}` with a
+   booking flow, availability + Stripe + auth libs, and the API routes
+   (services / availability / bookings / Stripe webhook).
+2. **Mongo collections + fields** — `services`, `availabilityRules`, `bookings`,
+   plus the overlap-check + unique-index rule that prevents double-booking.
+3. **CloudGrid injection** — `DATABASE_MONGODB_URL` for Mongo, `vault:` → env
+   vars for secrets, `AI_GATEWAY_URL` for ai.
+4. **Auth + payments wiring** — provider SDK from `AUTH_PROVIDER_KEY`; Stripe
+   checkout + signature-verified webhook from `STRIPE_KEY` /
+   `STRIPE_WEBHOOK_SECRET`.
+5. **Deploy steps** — `grid init` → fill → `grid secrets set` → `grid plug` →
+   poll to live.
+6. **Edition note** — runtime app → local edition only (hosted is static-only).
+7. **Reminder cron** — intended shape + the platform-issue-#1543 PENDING note and
+   stopgap.
+
+## Adapt it
+
+- Rename `services` / `bookings` collections and fields to your domain (rooms,
+  tables, resources, classes).
+- Swap the auth provider (Clerk / Auth0 / …) and payment flow (or drop Stripe for
+  free bookings — skip checkout, mark `confirmed`).
+- Add `needs: { cache: true }` only if you actually need Redis (e.g. slot-hold
+  locks).
+- Wire the reminder cron once platform issue #1543 lands; until then use the
+  stopgap in `AGENTS.md` §7.

package/src/corpus/templates/calendar-scheduler/AGENTS.md

@@ -0,0 +1,226 @@
+# AGENTS.md — calendar-scheduler blueprint (structure guide)
+
+This is a **blueprint**, not a runnable app. It ships a `cloudgrid.yaml` and this
+guide so an agent can *build* a calendar / scheduling app correctly on CloudGrid.
+There is no app code to copy — read this, generate the files, then deploy.
+
+A calendar scheduler is a persistent Next.js + Mongo runtime app (same base shape
+as `app-with-data` / `crm`) whose domain is **events and availability**: users
+create events on a calendar, define bookable time slots, and (optionally) let
+others book them. Its distinguishing concern is **time** — timezones, recurrence,
+overlap detection, and **scheduled reminders**. Reminders want a `cron` service;
+that shape is documented in §5, but cron deploy is **BLOCKED on platform issue
+#1543** — build the HTTP app now, add cron once #1543 ships.
+
+---
+
+## 1. File tree
+
+App code MUST live under `services/web/` — `path: /` in `cloudgrid.yaml` is the
+URL mount, NOT the filesystem path. Files at the repo root fail with
+`Error: Service directory not found: …/services/web`.
+
+```
+cloudgrid.yaml                              # name + services.web(nextjs,/) + needs:{database:true} (+ optional vault, + optional cron — see §5)
+services/web/
+  package.json                              # next, react, react-dom, mongodb  (+ optional: auth SDK, stripe, a date lib like luxon/date-fns-tz)
+  lib/
+    db.js                                   # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) — see §3 rule
+    time.js                                 # pure time helpers: toUTC/fromUTC, expandRecurrence(), slotsForDay(), overlaps(a,b)
+    auth.js                                 # (optional) provider SDK init from AUTH_PROVIDER_KEY; getCurrentUser()
+  app/
+    layout.js                               # root layout + inline CSS (+ auth provider wrapper if used)
+    page.js                                 # server component: month/week calendar grid, reads events from Mongo
+    events/[id]/page.js                     # event detail / edit
+    book/[slug]/page.js                     # (optional) public booking page for a shareable availability link
+    api/
+      events/route.js                       # GET (range query ?from&to) / POST (create) — App-Router CRUD
+      events/[id]/route.js                  # GET one / PATCH (reschedule/edit) / DELETE
+      availability/route.js                 # GET open slots for a day/range (derives from availability - bookings)
+      bookings/route.js                     # (optional) POST to book a slot -> creates an event, guards double-booking
+  middleware.js                             # (optional) gate /events/** + write APIs behind auth
+services/reminders/                         # (optional, BLOCKED #1543) cron job: scan due reminders, send mail/SMS — see §5
+  job.js
+  package.json
+```
+
+Keep it minimal and real; grow routes/collections as needed. Reuse the
+`app-with-data` App-Router GET/POST/PATCH/DELETE route shape for the CRUD parts.
+Store all times as **UTC `Date`** in Mongo; convert at the edges in `lib/time.js`.
+
+---
+
+## 2. Mongo collections + fields
+
+The grid provisions one MongoDB database (`needs: { database: true }`). Suggested
+collections (`_id` is the Mongo ObjectId on every doc):
+
+**`events`** — a scheduled item on the calendar
+- `ownerId` (string, from auth provider — omit if single-user/no auth)
+- `title` (string), `description` (string)
+- `startAt` (Date, UTC), `endAt` (Date, UTC)
+- `timezone` (string, IANA e.g. `"America/New_York"` — the zone the user entered it in)
+- `allDay` (bool)
+- `recurrence` (string | null — an RRULE, e.g. `"FREQ=WEEKLY;BYDAY=MO,WE"`; expand at read time in `lib/time.js`, do not store every instance)
+- `attendees` (array of `{ email, status: "invited"|"accepted"|"declined" }`)
+- `reminderMinutes` (number | null — minutes-before to notify; drives the cron job)
+- `reminderSentAt` (Date | null — set by the reminder job to avoid double-send)
+- `createdAt` (Date)
+
+**`availability`** — recurring bookable windows (for the scheduling/booking use)
+- `ownerId` (string)
+- `weekday` (number 0–6) or `date` (Date) for one-off windows
+- `startMinute` (number, minutes from midnight in `timezone`), `endMinute` (number)
+- `slotMinutes` (number — slot length, e.g. 30), `timezone` (string, IANA)
+- `bufferMinutes` (number — gap between bookings)
+
+**`bookings`** — (optional) an external booking against an availability window
+- `ownerId` (string — whose calendar), `slotStartAt` (Date, UTC), `slotEndAt` (Date, UTC)
+- `bookerName` (string), `bookerEmail` (string), `note` (string)
+- `eventId` (ObjectId ref → events — the event row this booking created)
+- `status` (string: `confirmed` | `cancelled`)
+- `createdAt` (Date)
+
+Index for the calendar range query and overlap checks:
+`db.collection("events").createIndex({ ownerId: 1, startAt: 1 })` and a query on
+`{ startAt: { $lt: rangeEnd }, endAt: { $gt: rangeStart } }` for the visible window.
+
+---
+
+## 3. How CloudGrid injects things
+
+You never provision infra or set connection strings by hand. Declared inputs are
+injected as env vars at `grid dev` (local) and at runtime (after `grid plug`):
+
+| What | Declared in cloudgrid.yaml | Injected env var(s) | Read in code |
+|------|----------------------------|---------------------|--------------|
+| MongoDB | `needs: { database: true }` | `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`) | `lib/db.js` |
+| Auth provider key (optional) | `vault: { AUTH_PROVIDER_KEY: auth-provider-key }` | `AUTH_PROVIDER_KEY` | `lib/auth.js` |
+| Stripe secret (optional, paid booking) | `vault: { STRIPE_KEY: stripe-live-key }` | `STRIPE_KEY` | `lib/stripe.js` |
+| Stripe webhook secret (optional) | `vault: { STRIPE_WEBHOOK_SECRET: stripe-webhook-secret }` | `STRIPE_WEBHOOK_SECRET` | `api/webhooks/stripe/route.js` |
+| Email/SMS key (optional, reminders) | `vault: { SENDGRID_API_KEY: sendgrid-key }` | `SENDGRID_API_KEY` | reminder job / `lib/notify.js` |
+| AI (optional) | `needs: { ai: true }` | `AI_GATEWAY_URL` | via `@cloudgrid-io/ai` |
+
+The `vault:` block only **maps** an org vault item key → an env var name. You must
+store the real value once with `grid secrets set <vault-item-key> <value>` (e.g.
+`grid secrets set sendgrid-key SG.xxx`). Non-secret public config (a public auth
+key, a base URL) → `grid env`. Never commit a secret; never hardcode a connection
+string. The base template ships with `needs: { database: true }` only — the vault
+block stays commented until you actually add auth / payments / reminders.
+
+**DB read rule (critical):** read the Mongo URL LAZILY inside a getter, never at
+module top level — a top-level `const uri = process.env.DATABASE_MONGODB_URL`
+fails `next build` (the module is imported for route analysis before the grid
+injects the var). Same lazy pattern for any Stripe / provider client.
+
+```js
+// lib/db.js — same proven shape as app-with-data
+import { MongoClient } from "mongodb";
+export async function getDb() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) throw new Error("DATABASE_MONGODB_URL not set — run via `grid dev` / `grid plug`.");
+  globalThis.__mongo ??= new MongoClient(uri).connect();
+  return (await globalThis.__mongo).db();
+}
+```
+
+---
+
+## 4. Wiring auth + payments (optional layers)
+
+Both are optional — a personal single-user calendar needs neither. Add them only
+when the use demands it, and always through the vault → env-var mechanism above.
+
+### Auth (multi-user calendars, invites, per-user availability)
+- Pick a provider SDK: **Clerk** (`@clerk/nextjs`) or **Auth0**
+  (`@auth0/nextjs-auth0`). Add it to `package.json`.
+- Initialize it in `lib/auth.js` from `process.env.AUTH_PROVIDER_KEY` (vault). A
+  public key (if the provider needs one client-side) is non-secret → `grid env`.
+- Stamp `ownerId` on every `events` / `availability` / `bookings` write with the
+  signed-in user id, and filter reads by it.
+- In `middleware.js`, gate the write APIs and the owner's dashboard; leave the
+  public `book/[slug]` page + the read side of `availability` open so external
+  people can book without an account.
+
+### Payments (paid bookings / deposits — the booking-SaaS shape)
+- Add `stripe` to `package.json`; init a lazy client in `lib/stripe.js` from
+  `process.env.STRIPE_KEY` (vault). Map `STRIPE_KEY` and `STRIPE_WEBHOOK_SECRET`
+  in the `vault:` block.
+- On booking a paid slot, create a Stripe **Checkout Session** (`mode: "payment"`)
+  and create the `bookings`/`events` doc as `pending`.
+- Add `api/webhooks/stripe/route.js`: verify the signature with
+  `stripe().webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET)`
+  (read the RAW body — do NOT JSON-parse before verifying) and on
+  `checkout.session.completed` mark the booking `confirmed`. Point the Stripe
+  dashboard webhook at `<live-url>/api/webhooks/stripe`.
+
+---
+
+## 5. Scheduled reminders (cron) — INTENDED SHAPE, BLOCKED on #1543
+
+A calendar scheduler wants scheduled work: every few minutes, find events whose
+reminder is due and send an email/SMS. On CloudGrid that is a **second service of
+`type: cron`** in the same entity, sharing the app-level Mongo.
+
+**PLATFORM STATUS — NOT YET DEPLOYABLE.** Cron deploy is a **PENDING platform
+issue (#1543)**. Do NOT uncomment the cron service in `cloudgrid.yaml` yet;
+plugging it today will not schedule the job. Ship the HTTP app now; add the cron
+service once #1543 lands. Until then, this is the intended shape only.
+
+Intended `cloudgrid.yaml` addition (currently commented in the shipped file):
+
+```yaml
+services:
+  web:
+    type: nextjs
+    path: /
+  reminders:            # BLOCKED #1543 — do not uncomment until it ships
+    type: cron
+    schedule: "*/15 * * * *"   # every 15 min
+    timezone: UTC              # UTC | EST | PST
+    run: job                   # run the container's default job (or an https URL)
+```
+
+Intended job (`services/reminders/job.js`): reads `DATABASE_MONGODB_URL` the same
+lazy way, queries
+`events` where `reminderMinutes != null`, `reminderSentAt == null`, and
+`startAt <= now + reminderMinutes`, sends via the mail/SMS provider (its key mapped
+in `vault:`), then sets `reminderSentAt` so it never double-sends. A cron service
+has NO `path` (no HTTP route) and shares the app-level `needs.database`.
+
+Interim workaround until #1543: trigger reminders from an external scheduler
+hitting an authenticated HTTP route on `web` (e.g. `POST /api/cron/reminders`
+guarded by a shared secret from the vault), instead of a `type: cron` service.
+
+---
+
+## 6. Deploy steps
+
+Runtime app → **local edition** only (Claude Desktop / Claude Code / CLI); the
+hosted edition cannot build a runtime container. Order matters — `plug` needs a
+linked directory, so `init` first.
+
+1. `grid init` (or `gridctl_init`) an app `<name>` — creates the entity +
+   `.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services:{}`.
+2. Fill: put the app under `services/web/` and set `cloudgrid.yaml` to this
+   blueprint's active fields (`services.web` nextjs `/`, `needs:{database:true}`).
+   Uncomment a `vault:` entry only if you added auth / payments / reminders.
+3. (If you mapped vault items) store the values:
+   `grid secrets set <vault-item-key> <value>`. Non-secret public config → `grid env`.
+   Do NOT set `DATABASE_MONGODB_URL` / `MONGODB_URL` yourself — the grid injects them.
+4. (Optional) `grid dev` to run locally against the injected dev Mongo (+ secrets).
+5. `grid plug` to deploy. A runtime deploy is **ASYNC** — the first response is
+   `status: building`, not a live URL. Poll `grid status` (surface a liveness
+   signal, never a bare wait) until Ready.
+6. Once live, return the app URL. Re-plug the same entity to update the same URL.
+   (Do NOT add the cron `reminders` service until #1543 ships — see §5.)
+
+---
+
+## 7. Edition note
+
+Because this is a built + deployed container (Next.js + Mongo), it requires the
+**local edition** (Claude Desktop / Claude Code) or the CLI. The hosted edition
+(Claude Web / hosted MCP) is inline-only and can only publish static pages —
+offer a static calendar mockup there, but the real scheduler must be built and
+plugged from the local edition.

package/src/corpus/templates/calendar-scheduler/README.md

@@ -0,0 +1,25 @@
+# calendar-scheduler template — calendar / scheduling app blueprint
+
+A blueprint for a calendar scheduler on CloudGrid: a persistent Next.js + Mongo
+app whose domain is events and availability (`events`, `availability`, optional
+`bookings`) — create events on a calendar, define bookable slots, handle
+timezones and recurrence, and (once platform issue #1543 ships) fire scheduled
+reminders from a `cron` service. Because a real scheduler involves choices (auth
+or single-user, paid bookings or not, which date library), this template ships
+the **structure and `cloudgrid.yaml`, not finished app code** — you adapt it and build.
+
+> **This is a blueprint: structure + cloudgrid.yaml, adapt and build.** Read
+> `AGENTS.md` for the file tree, Mongo collections, CloudGrid injection table
+> (needs + optional vault), the optional auth/payments layers, the intended cron
+> reminder shape (BLOCKED on #1543), and the deploy flow — then generate the app
+> under `services/web/` and `grid plug` it (runtime, local edition, async — poll
+> to a live URL).
+
+## Files
+
+- `cloudgrid.yaml` — active fields: `name`, `services.web` (nextjs, `/`),
+  `needs: { database: true }`. Includes a COMMENTED cron `reminders` service
+  (intended shape; not yet deployable — platform issue #1543) and a commented
+  `vault:` block for optional auth / payments / reminder-provider secrets.
+- `AGENTS.md` — the structure guide (read this first).
+- `index.md` — the fetch-bundle summary + cloudgrid.yaml.

package/src/corpus/templates/calendar-scheduler/cloudgrid.yaml

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