@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/templates/monitoring-dashboard/services/web/app/check-form.js

@@ -0,0 +1,124 @@
+"use client";
+
+// Small client component: renders the current-status grid + recent history and
+// posts new checks to /api/checks. Recomputes the per-service grid on the client
+// after each POST so the board updates without a full refresh.
+import { useState } from "react";
+
+const STATUSES = ["up", "degraded", "down"];
+
+function computeServices(checks) {
+  const seen = new Map();
+  for (const c of checks) {
+    if (!seen.has(c.service)) seen.set(c.service, c);
+  }
+  return [...seen.values()].sort((a, b) => a.service.localeCompare(b.service));
+}
+
+function fmt(at) {
+  const d = new Date(at);
+  return isNaN(d) ? at : d.toLocaleString();
+}
+
+export default function CheckForm({ initialChecks, initialServices }) {
+  const [checks, setChecks] = useState(initialChecks);
+  const [services, setServices] = useState(initialServices);
+  const [service, setService] = useState("");
+  const [status, setStatus] = useState("up");
+  const [latency, setLatency] = useState("");
+  const [busy, setBusy] = useState(false);
+
+  async function add(e) {
+    e.preventDefault();
+    const name = service.trim();
+    if (!name) return;
+    setBusy(true);
+    const res = await fetch("/api/checks", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        service: name,
+        status,
+        latencyMs: latency === "" ? undefined : Number(latency),
+      }),
+    });
+    if (res.ok) {
+      const check = await res.json();
+      const next = [check, ...checks];
+      setChecks(next);
+      setServices(computeServices(next));
+      setService("");
+      setLatency("");
+    }
+    setBusy(false);
+  }
+
+  return (
+    <div>
+      <form onSubmit={add} className="row">
+        <input
+          className="service"
+          value={service}
+          onChange={(e) => setService(e.target.value)}
+          placeholder="Service name (e.g. api, web, db)…"
+          aria-label="Service name"
+        />
+        <select value={status} onChange={(e) => setStatus(e.target.value)} aria-label="Status">
+          {STATUSES.map((s) => (
+            <option key={s} value={s}>{s}</option>
+          ))}
+        </select>
+        <input
+          className="latency"
+          type="number"
+          min="0"
+          value={latency}
+          onChange={(e) => setLatency(e.target.value)}
+          placeholder="Latency ms"
+          aria-label="Latency in milliseconds"
+        />
+        <button type="submit" disabled={busy}>Record check</button>
+      </form>
+
+      <h2>Current status</h2>
+      <div className="grid">
+        {services.length === 0 && <div className="empty">No services checked yet.</div>}
+        {services.map((s) => (
+          <div className="card" key={s.service}>
+            <div className="name">{s.service}</div>
+            <div><span className={`badge ${s.status}`}>{s.status}</span></div>
+            <div className="meta">
+              {typeof s.latencyMs === "number" ? `${s.latencyMs} ms · ` : ""}
+              {fmt(s.at)}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <h2>Recent history</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>Service</th>
+            <th>Status</th>
+            <th>Latency</th>
+            <th>At</th>
+          </tr>
+        </thead>
+        <tbody>
+          {checks.length === 0 && (
+            <tr><td className="empty" colSpan={4}>No checks recorded yet.</td></tr>
+          )}
+          {checks.map((c) => (
+            <tr key={c.id}>
+              <td>{c.service}</td>
+              <td><span className={`badge ${c.status}`}>{c.status}</span></td>
+              <td>{typeof c.latencyMs === "number" ? `${c.latencyMs} ms` : "—"}</td>
+              <td>{fmt(c.at)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/corpus/templates/monitoring-dashboard/services/web/app/layout.js

@@ -0,0 +1,44 @@
+// Root layout + plain inline CSS (no external CDNs, fonts, or stylesheets).
+export const metadata = {
+  title: "Monitoring Dashboard",
+  description: "A service health board on CloudGrid, backed by grid-shared Mongo.",
+};
+
+const css = `
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font-family: system-ui, -apple-system, sans-serif; line-height: 1.5; }
+  main { max-width: 52rem; margin: 3rem auto; padding: 0 1.25rem; }
+  h1 { margin: 0 0 .25rem; }
+  h2 { margin: 2rem 0 .75rem; font-size: 1.1rem; }
+  .hint { margin: 0 0 1.5rem; opacity: .7; font-size: .9rem; }
+  form.row { display: flex; flex-wrap: wrap; gap: .5rem; margin-bottom: 1rem; align-items: center; }
+  input, select { padding: .5rem .75rem; border: 1px solid #8886; border-radius: .5rem; font: inherit; }
+  input.service { flex: 1; min-width: 10rem; }
+  input.latency { width: 8rem; }
+  button { padding: .5rem .9rem; border: 1px solid #8886; border-radius: .5rem; background: #6663; font: inherit; cursor: pointer; }
+  button:disabled { opacity: .5; cursor: default; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(11rem, 1fr)); gap: .75rem; }
+  .card { border: 1px solid #8884; border-radius: .6rem; padding: .8rem .9rem; }
+  .card .name { font-weight: 600; }
+  .card .meta { font-size: .85rem; opacity: .7; margin-top: .2rem; }
+  .badge { display: inline-block; padding: .1rem .5rem; border-radius: 1rem; font-size: .75rem; font-weight: 600; text-transform: uppercase; letter-spacing: .03em; }
+  .badge.up { background: #1f8f4922; color: #1f8f49; }
+  .badge.degraded { background: #b9770022; color: #b97700; }
+  .badge.down { background: #c0392b22; color: #c0392b; }
+  table { width: 100%; border-collapse: collapse; font-size: .9rem; }
+  th, td { text-align: left; padding: .45rem .5rem; border-bottom: 1px solid #8883; }
+  th { font-size: .8rem; text-transform: uppercase; letter-spacing: .03em; opacity: .7; }
+  .empty { opacity: .6; }
+`;
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <head>
+        <style dangerouslySetInnerHTML={{ __html: css }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/src/corpus/templates/monitoring-dashboard/services/web/app/page.js

@@ -0,0 +1,49 @@
+// Home page: a server component reads the checks straight from Mongo, derives a
+// current-status grid (latest check per service) plus a recent history, and a
+// small client form posts new checks via the API route. Data persists across
+// refresh and across users because it lives in the grid-shared Mongo, not memory.
+import { getDb } from "../lib/db.js";
+import CheckForm from "./check-form.js";
+
+export const dynamic = "force-dynamic";
+
+async function listChecks() {
+  const db = await getDb();
+  const items = await db
+    .collection("checks")
+    .find({})
+    .sort({ at: -1 })
+    .limit(200)
+    .toArray();
+  return items.map((c) => ({
+    id: c._id.toString(),
+    service: c.service,
+    status: c.status,
+    latencyMs: c.latencyMs,
+    at: (c.at instanceof Date ? c.at : new Date(c.at)).toISOString(),
+  }));
+}
+
+// Latest check per service = the current status grid.
+function currentStatus(checks) {
+  const seen = new Map();
+  for (const c of checks) {
+    if (!seen.has(c.service)) seen.set(c.service, c);
+  }
+  return [...seen.values()].sort((a, b) => a.service.localeCompare(b.service));
+}
+
+export default async function Page() {
+  const checks = await listChecks();
+  const services = currentStatus(checks);
+  return (
+    <main>
+      <h1>Monitoring Dashboard</h1>
+      <p className="hint">
+        Service health from the grid-shared Mongo — status grid + recent history,
+        survives refresh.
+      </p>
+      <CheckForm initialChecks={checks} initialServices={services} />
+    </main>
+  );
+}

package/src/corpus/templates/monitoring-dashboard/services/web/lib/db.js

@@ -0,0 +1,32 @@
+// Cached MongoDB client for the App Router.
+//
+// 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 the var.
+import { MongoClient } from "mongodb";
+
+function clientPromise() {
+  const uri = process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL;
+  if (!uri) {
+    throw new Error(
+      "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) {
+    globalThis.__mongoClientPromise = new MongoClient(uri).connect();
+  }
+  return globalThis.__mongoClientPromise;
+}
+
+export async function getDb() {
+  const client = await clientPromise();
+  // The default DB comes from the connection-string path segment the grid injects.
+  return client.db();
+}

package/src/corpus/templates/monitoring-dashboard/services/web/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "monitoring-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "mongodb": "^6.12.0"
+  }
+}

package/src/corpus/templates/online-store/AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md — online-store (blueprint)
+
+This is a **blueprint**, not runnable app code. It tells an agent exactly how to
+build a working e-commerce store on CloudGrid: a Next.js storefront with a cart,
+Stripe checkout, a Stripe webhook that confirms payment, and orders persisted in
+the grid-shared Mongo. Read this whole file, then write the files under
+`services/web/` following the tree and wiring rules below.
+
+The proven shape to imitate is `app-with-data` (Next.js App Router + `mongodb`
+driver, lazy DB getter, app under `services/web/`). This blueprint adds a second
+collection (`orders`), Stripe checkout, and a webhook.
+
+## 1. File tree
+
+App code MUST live under `services/web/` — `path: /` in `cloudgrid.yaml` is the
+URL mount, NOT the filesystem path. A service named `web` means the CLI looks for
+`services/web/`; files at the project root fail with
+`Error: Service directory not found: …/services/web`.
+
+```
+cloudgrid.yaml                                  # name + services.web (nextjs) + needs:{database:true} + vault:{STRIPE_KEY}
+services/web/package.json                       # next, react, react-dom, mongodb, stripe
+services/web/lib/db.js                          # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
+services/web/lib/stripe.js                      # lazy Stripe client from process.env.STRIPE_KEY (injected by the vault: block)
+services/web/lib/products.js                    # product catalog source (seed array, or read the products collection)
+services/web/app/layout.js                      # root layout + inline CSS
+services/web/app/page.js                        # storefront: server component, lists products from Mongo
+services/web/app/cart.js                        # "use client" cart UI (localStorage), "Checkout" button
+services/web/app/success/page.js                # post-checkout confirmation (reads ?session_id, shows the order)
+services/web/app/api/checkout/route.js          # POST: create a Stripe Checkout Session from the cart, return its URL
+services/web/app/api/webhook/route.js           # POST: Stripe webhook — verify signature, persist the paid order
+services/web/app/api/products/route.js          # GET (list) / POST (add) — optional admin CRUD for the catalog
+```
+
+## 2. Mongo collections + fields
+
+The grid provisions one Mongo database (`needs: { database: true }`). Use two
+collections:
+
+**`products`**
+- `_id`         — ObjectId
+- `name`        — string
+- `description` — string
+- `priceCents`  — integer (store money in the smallest unit — cents — never floats)
+- `currency`    — string, e.g. `"usd"`
+- `image`       — string URL (optional)
+- `active`      — boolean (hide without deleting)
+
+**`orders`**
+- `_id`               — ObjectId
+- `stripeSessionId`   — string (Checkout Session id; unique — use it for idempotency)
+- `items`             — array of `{ productId, name, priceCents, quantity }`
+- `amountTotalCents`  — integer (authoritative total from the Stripe event, not the client)
+- `currency`          — string
+- `email`             — string (customer email from Stripe)
+- `status`            — string: `"pending"` → `"paid"` (set to paid ONLY by the webhook)
+- `createdAt`         — Date
+
+Never trust prices sent by the browser. The checkout route builds line items from
+the server-side `products` catalog; the webhook records the total from the
+verified Stripe event.
+
+## 3. How CloudGrid injects things (do NOT hardcode any of this)
+
+- **Mongo:** declare `needs: { database: true }`. The platform provisions Mongo
+  and injects the connection string as **`DATABASE_MONGODB_URL`** (plus the legacy
+  **`MONGODB_URL`** alias) at dev-time (`grid dev`) and at runtime (after
+  `grid plug`). Read it as `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`
+  **lazily inside a 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.
+- **Stripe secret:** put it in the vault, not in code. The `vault:` block in
+  `cloudgrid.yaml` maps the vault item `stripe-live-key` to the env var
+  **`STRIPE_KEY`**. Set the vault item once with `grid secrets set stripe-live-key`
+  (paste the `sk_live_…` / `sk_test_…` key); the platform injects it as
+  `process.env.STRIPE_KEY`. Read it lazily in `services/web/lib/stripe.js`.
+- **Stripe webhook signing secret:** the `whsec_…` value Stripe gives you for the
+  webhook endpoint. Add it to the vault too and map it in the `vault:` block, e.g.
+  `STRIPE_WEBHOOK_SECRET: stripe-webhook-secret`, then verify events with
+  `stripe.webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET)`.
+- **Public base URL:** Stripe Checkout needs absolute `success_url` /`cancel_url`.
+  Derive them from the incoming request (`new URL(request.url).origin`) rather than
+  hardcoding the live host, so it works in `grid dev` and after `grid plug`.
+- **AI (only if you add it):** declare `needs: { ai: true }` and the platform
+  injects `AI_GATEWAY_URL`; call it via `@cloudgrid-io/ai`. Not required for a store.
+
+## 4. Wiring payments (Stripe) — and optional auth
+
+**Checkout route (`app/api/checkout/route.js`):**
+1. Read the cart (array of `{ productId, quantity }`) from the POST body.
+2. Load each product from the server-side `products` collection — never trust the
+   client's prices.
+3. Build Stripe `line_items` with `price_data` from the DB (`unit_amount:
+   priceCents`, `currency`).
+4. `stripe.checkout.sessions.create({ mode: "payment", line_items,
+   success_url: origin + "/success?session_id={CHECKOUT_SESSION_ID}",
+   cancel_url: origin + "/" })`.
+5. Return `{ url: session.url }`; the client redirects to it.
+
+**Webhook route (`app/api/webhook/route.js`):**
+1. Read the **raw** body (in the App Router: `await request.text()` — do NOT
+   `request.json()`; signature verification needs the exact bytes).
+2. Verify with `stripe.webhooks.constructEvent(rawBody,
+   request.headers.get("stripe-signature"), process.env.STRIPE_WEBHOOK_SECRET)`.
+3. On `checkout.session.completed`, upsert the `orders` doc by `stripeSessionId`
+   (idempotent — Stripe may retry), set `status: "paid"`, `amountTotalCents =
+   event.data.object.amount_total`, and the customer email.
+4. Return `200` fast; return `400` if verification fails.
+   Register the endpoint URL (`<live-url>/api/webhook`) in the Stripe dashboard and
+   copy its `whsec_…` secret into the vault.
+
+**Optional auth (accounts / order history):** add a provider SDK (Clerk, Auth0,
+or NextAuth). Put its keys in the vault and map them in the `vault:` block, e.g.
+`AUTH_PROVIDER_KEY: clerk-secret-key` (and any publishable key), read them from
+`process.env`, and gate the account/order-history pages behind the provider's
+middleware. Not required for a basic store; add it only if the user wants logins.
+
+## 5. Deploy steps
+
+1. `grid init` an app `<name>` (creates the entity + `.cloudgrid/link.json`,
+   writes a `cloudgrid.yaml` with empty `services: {}`). Run this FIRST — `plug`
+   needs a linked directory.
+2. Write the app under `services/web/` and set `cloudgrid.yaml` to the shape in
+   this template (name + `services.web` nextjs + `needs: { database: true }` +
+   the `vault: { STRIPE_KEY: stripe-live-key }` block).
+3. `grid secrets set stripe-live-key` (and the webhook secret) so the vault items
+   the `vault:` block references exist. Do NOT set `DATABASE_MONGODB_URL` yourself.
+4. (Optional) `grid dev` to run locally against the injected Mongo + your Stripe
+   test key before deploying.
+5. `grid plug` to build + deploy. A runtime deploy is **async**: `plug` returns
+   `status: building`. Poll `grid status` until the entity is live; surface a
+   liveness signal, never a bare silent wait. Only then return the live app URL.
+6. Register `<live-url>/api/webhook` in the Stripe dashboard, copy its `whsec_…`
+   into the vault, and re-`grid plug` the SAME entity (same URL) if you changed the
+   `vault:` mapping.
+
+## 6. Edition note
+
+This is a **runtime app** (a built + deployed container), so it needs the **local
+edition** (Claude Desktop / Claude Code) or the CloudGrid CLI. The hosted edition
+(Claude Web / hosted MCP) is inline-only and can publish only static pages — it
+cannot build this store. If you are on hosted, offer a static storefront preview
+instead and stop the runtime path.
+
+## 7. Self-check before you call it done
+
+- App code is under `services/web/`, not the root.
+- DB and Stripe clients are read LAZILY inside getters, never at module top level.
+- Prices come from the server-side catalog; the webhook records the Stripe total.
+- The webhook reads the raw body and verifies the signature.
+- `cloudgrid.yaml` active fields are exactly: `name`, `services.web {type:nextjs,
+  path:/}`, `needs: { database: true }`, and the `vault:` block for `STRIPE_KEY`.
+- No secret or connection string is committed anywhere.

package/src/corpus/templates/online-store/README.md

@@ -0,0 +1,16 @@
+# online-store template — e-commerce blueprint (Next.js + Mongo + Stripe)
+
+A **blueprint** for a real online store on CloudGrid: a Next.js storefront with a
+cart, Stripe Checkout, a signature-verified Stripe webhook that confirms payment,
+and `products` + `orders` persisted in the grid-shared Mongo — the same proven
+`services/web/` + lazy-Mongo shape as `app-with-data`, plus payments. It exists
+because "sell products online" is a common ask that needs a database *and* a
+payment provider wired the CloudGrid-correct way (Mongo via `needs`, the Stripe
+key via the `vault:` block → `STRIPE_KEY`), and getting that wiring right is the
+hard part.
+
+**This is a blueprint: structure + `cloudgrid.yaml`, not finished app code.** Read
+`AGENTS.md` for the file tree, the Mongo collections/fields, how the grid injects
+Mongo (`DATABASE_MONGODB_URL`) and the Stripe secret (`vault:` → `STRIPE_KEY`), the
+checkout + webhook wiring, and the deploy steps — then build the app under
+`services/web/`, adapting the catalog and UI to the user's store.

package/src/corpus/templates/online-store/cloudgrid.yaml

@@ -0,0 +1,234 @@
+# ============================================================================
+# 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: online-store
+
+# 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.
+# Stripe secret key for the checkout + webhook routes. Set the vault item once
+# (`grid secrets set stripe-live-key`); the platform injects it as STRIPE_KEY.
+vault:
+  STRIPE_KEY: stripe-live-key
+#   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
+
+
+needs:
+  database: true
+
+
+# ============================================================================
+# 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
+# ============================================================================