@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/templates/marketplace/AGENTS.md

@@ -0,0 +1,208 @@
+# AGENTS.md — marketplace 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 two-sided marketplace correctly on CloudGrid.
+There is no app code to copy — read this, generate the files, then deploy.
+
+A marketplace is a persistent Next.js + Mongo runtime app (same base shape as
+`app-with-data` / `crm`) with three extra concerns layered on: **seller auth
+with roles**, **Stripe Connect payouts**, and **commission logic**. All three are
+wired through CloudGrid's injection mechanisms (needs / vault), never hardcoded.
+
+---
+
+## 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} + vault (Stripe + auth)
+services/web/
+  package.json                              # next, react, react-dom, mongodb, stripe, + auth SDK (@clerk/nextjs or @auth0/nextjs-auth0)
+  middleware.js                             # auth middleware: protect /dashboard + /api/seller/* ; attach role
+  lib/
+    db.js                                   # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) — see rule below
+    auth.js                                 # provider SDK init; getCurrentUser(); requireRole('seller'|'admin')
+    stripe.js                               # lazy Stripe client from process.env.STRIPE_KEY (from vault)
+    commission.js                           # pure fn: splitOrder(amount) -> { platformFee, sellerPayout } (e.g. 10% take rate)
+  app/
+    layout.js                              # root layout + auth provider wrapper
+    page.js                                 # public storefront: listing grid across all vendors
+    listings/[id]/page.js                  # public listing detail + "Buy" (starts Checkout)
+    dashboard/page.js                       # seller dashboard (role-gated): my listings + payout status
+    dashboard/listings/new/page.js         # seller: create/edit a listing
+    api/
+      vendors/route.js                     # GET list vendors / POST become-a-seller (creates Connect account link)
+      listings/route.js                    # GET (public list) / POST (seller create) / PATCH / DELETE (owner only)
+      orders/route.js                      # GET my orders / POST create order -> Stripe Checkout session
+      checkout/route.js                    # POST -> Stripe Checkout session with application_fee + transfer_data.destination
+      webhooks/stripe/route.js             # POST Stripe webhook: verify signature, mark order paid, record payout
+      connect/route.js                     # POST -> Stripe Connect onboarding/account link for a seller
+```
+
+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.
+
+---
+
+## 2. Mongo collections + fields
+
+The grid provisions one MongoDB database (`needs: { database: true }`). Suggested
+collections (`_id` is the Mongo ObjectId on every doc):
+
+**`vendors`** — a seller account
+- `userId` (string, from auth provider — the owner)
+- `displayName` (string)
+- `stripeAccountId` (string — the Stripe Connect `acct_…`, set after onboarding)
+- `payoutsEnabled` (bool — mirror of Connect `charges_enabled`/`payouts_enabled`)
+- `createdAt` (Date)
+
+**`listings`** — a product/service offered by a vendor
+- `vendorId` (ObjectId ref → vendors, OR the vendor's `userId`)
+- `title` (string), `description` (string)
+- `priceCents` (number — store money as integer cents, never floats)
+- `currency` (string, e.g. `"usd"`)
+- `status` (string: `draft` | `active` | `sold`)
+- `createdAt` (Date)
+
+**`orders`** — a buyer purchasing a listing
+- `listingId` (ObjectId ref → listings)
+- `vendorId` (ObjectId ref → vendors)
+- `buyerUserId` (string, from auth provider)
+- `amountCents` (number), `platformFeeCents` (number), `sellerPayoutCents` (number)
+- `status` (string: `pending` | `paid` | `refunded`)
+- `stripeCheckoutSessionId` (string), `stripePaymentIntentId` (string)
+- `createdAt` (Date)
+
+Roles are carried by the auth provider (a `role` claim/metadata:
+`buyer` | `seller` | `admin`), NOT a separate collection — read it via the SDK.
+
+---
+
+## 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` |
+| Stripe secret key | `vault: { STRIPE_KEY: stripe-live-key }` | `STRIPE_KEY` | `lib/stripe.js` |
+| Stripe webhook secret | `vault: { STRIPE_WEBHOOK_SECRET: stripe-webhook-secret }` | `STRIPE_WEBHOOK_SECRET` | `api/webhooks/stripe/route.js` |
+| Auth provider server key | `vault: { AUTH_PROVIDER_KEY: auth-provider-key }` | `AUTH_PROVIDER_KEY` | `lib/auth.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 stripe-live-key sk_live_…`). Never commit a secret; never
+hardcode a connection string.
+
+**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 pattern for the Stripe client in `lib/stripe.js`.
+
+```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();
+}
+```
+
+```js
+// lib/stripe.js — lazy, reads the vault-injected STRIPE_KEY
+import Stripe from "stripe";
+export function stripe() {
+  const key = process.env.STRIPE_KEY;
+  if (!key) throw new Error("STRIPE_KEY not set — map it in cloudgrid.yaml `vault:` and `grid secrets set`.");
+  globalThis.__stripe ??= new Stripe(key, { apiVersion: "2024-06-20" });
+  return globalThis.__stripe;
+}
+```
+
+---
+
+## 4. Wiring auth (roles) + payments (Stripe Connect)
+
+### Seller auth with roles
+- Pick a provider SDK: **Clerk** (`@clerk/nextjs`) or **Auth0**
+  (`@auth0/nextjs-auth0`). Add it to `package.json`.
+- Initialize it in `lib/auth.js` using `process.env.AUTH_PROVIDER_KEY` (from the
+  vault block). Some providers also need a public key — set non-secret public
+  values via `grid env` (they are not secrets), secrets via `grid secrets set`.
+- Store a `role` (`buyer` | `seller` | `admin`) in the provider's user
+  metadata/claims. Expose `getCurrentUser()` and `requireRole(role)` helpers.
+- In `middleware.js`, protect `/dashboard/**` and `/api/seller/**` (and any
+  seller-only route): redirect anonymous users to sign-in, and 403 users whose
+  role is not `seller`/`admin`.
+
+### Stripe Connect payouts + commission
+- **Onboarding:** `POST /api/connect` creates a Stripe Connect *Express* account
+  for the seller (`stripe().accounts.create({ type: 'express' })`), stores
+  `stripeAccountId` on the `vendors` doc, and returns an `accountLinks.create`
+  onboarding URL. Refresh `payoutsEnabled` from the account's
+  `charges_enabled`/`payouts_enabled`.
+- **Checkout with commission:** `POST /api/checkout` creates a Checkout Session
+  for the listing where the platform takes a fee and the rest routes to the
+  seller's connected account:
+  ```js
+  const { platformFeeCents } = splitOrder(amountCents); // lib/commission.js, e.g. 10% take rate
+  await stripe().checkout.sessions.create({
+    mode: "payment",
+    line_items: [{ price_data: { currency, product_data: { name: listing.title },
+      unit_amount: amountCents }, quantity: 1 }],
+    payment_intent_data: {
+      application_fee_amount: platformFeeCents,
+      transfer_data: { destination: vendor.stripeAccountId },
+    },
+    success_url, cancel_url,
+  });
+  ```
+  Create the `orders` doc as `pending` here with the split amounts.
+- **Webhook:** `POST /api/webhooks/stripe` verifies the signature with
+  `stripe().webhooks.constructEvent(rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET)`
+  and on `checkout.session.completed` marks the matching order `paid` and records
+  the payout. Read the RAW request body (do not JSON-parse before verifying).
+- **Commission is a pure function** in `lib/commission.js` — keep the take-rate in
+  one place so it is testable and auditable:
+  `splitOrder(amountCents) => { platformFeeCents, sellerPayoutCents }`.
+
+---
+
+## 5. 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}`,
+   the `vault:` block).
+3. Store the secrets the vault block maps:
+   `grid secrets set stripe-live-key sk_live_…`,
+   `grid secrets set stripe-webhook-secret whsec_…`,
+   `grid secrets set auth-provider-key …`. Non-secret public config → `grid env`.
+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. Point the Stripe webhook endpoint at
+   `<live-url>/api/webhooks/stripe`. Re-plug the same entity to update the same URL.
+
+---
+
+## 6. Edition note
+
+Because this is a built + deployed container (Next.js + Mongo + Stripe), 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 storefront mockup there, but the real marketplace
+must be built and plugged from the local edition.

package/src/corpus/templates/marketplace/README.md

@@ -0,0 +1,22 @@
+# marketplace template — two-sided marketplace blueprint
+
+A blueprint for a multi-vendor / two-sided marketplace on CloudGrid: a persistent
+Next.js + Mongo app (`vendors`, `listings`, `orders`) with seller auth + roles,
+Stripe Connect payouts, and commission logic — the `app-with-data` runtime shape
+with auth and payments layered on. Because a real marketplace involves choices
+(which auth provider, take-rate, listing schema), 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 + vault), auth + Stripe Connect wiring, 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 }`, and a `vault:` block mapping `STRIPE_KEY`,
+  `STRIPE_WEBHOOK_SECRET`, and `AUTH_PROVIDER_KEY`.
+- `AGENTS.md` — the structure guide (read this first).
+- `index.md` — the fetch-bundle summary + cloudgrid.yaml.

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

@@ -0,0 +1,233 @@
+# ============================================================================
+# 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-marketplace
+
+# 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.
+# Marketplace payments + seller auth: inject the Stripe secret key (used for
+# Stripe Connect payouts + Checkout) and the Stripe webhook signing secret, plus
+# the auth-provider server key (Clerk/Auth0). Store the values with
+# `grid secrets set <vault-item-key> …` — the template only maps them to env vars.
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-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
+
+
+# ============================================================================
+# 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
+# ============================================================================

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

@@ -0,0 +1,76 @@
+# Template: marketplace (blueprint — persistent Next.js + Mongo + Stripe Connect)
+
+A **blueprint** for a two-sided / multi-vendor marketplace: vendors, listings,
+orders, seller auth with roles, Stripe Connect payouts, and commission logic. It
+is the persistent Next.js + Mongo runtime shape (same base as `app-with-data` /
+`crm`) with auth + payments layered on. This template ships **structure, not app
+code** — read the structure guide, then build the app following it.
+
+**This is a blueprint (tier C):** the deliverable is `cloudgrid.yaml` +
+`AGENTS.md`. Fetch the bundle, read `AGENTS.md`, then generate the files under
+`services/web/` and deploy.
+
+- **Structure guide:** `gridctl_fetch("template", "marketplace")` → read
+  **`AGENTS.md`** (file tree, Mongo collections, CloudGrid injection table, auth +
+  Stripe Connect wiring, deploy steps, edition note).
+
+**Key rules (same runtime discipline as `app-with-data`):**
+
+1. **App code MUST live under `services/web/`, not the repo root.** `path: /` in
+   `cloudgrid.yaml` is the URL mount, NOT the filesystem path.
+2. **Read injected connection strings/keys LAZILY (inside a getter), never at
+   module top level** — a top-level read fails `next build`. The grid injects
+   `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`); vault injects `STRIPE_KEY`,
+   `STRIPE_WEBHOOK_SECRET`, `AUTH_PROVIDER_KEY`.
+3. **Declare the datastore with `needs: { database: true }`** (canonical shape),
+   and map secrets with the `vault:` block. Never author `requires:`, and never
+   set `needs:` and `requires:` together (the validator rejects the combination).
+4. **Store money as integer cents; keep the commission take-rate as a pure
+   function** (`lib/commission.js`) so the platform-fee/seller-payout split is
+   testable.
+
+Runtime app → **local edition** only (async build, poll to a live URL).
+
+## 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.
+name: my-marketplace
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+  AUTH_PROVIDER_KEY: auth-provider-key
+```
+
+> **Capability:** `needs: { database: true }` → the deployer provisions Mongo and
+> injects `DATABASE_MONGODB_URL` (plus legacy `MONGODB_URL`). The `vault:` block
+> maps org vault items → env vars (`STRIPE_KEY` for Stripe Connect payouts +
+> Checkout, `STRIPE_WEBHOOK_SECRET` for webhook verification, `AUTH_PROVIDER_KEY`
+> for the seller-auth SDK) — store the real values with `grid secrets set`. See
+> the capability-map for the full injection table.
+
+## Structure guide
+
+The real content of this blueprint is **`AGENTS.md`** — fetch the template bundle
+and read it. It covers the `services/web/` file tree, the `vendors` / `listings` /
+`orders` collections, the CloudGrid injection table (needs + vault + AI gateway),
+how to wire auth (Clerk/Auth0 + roles) and payments (Stripe Connect onboarding,
+Checkout with `application_fee` + `transfer_data.destination`, and the signed
+webhook), and the `grid init → fill → secrets set → grid plug → poll` deploy flow.
+
+## Adapt it
+
+- Choose your auth provider SDK (Clerk or Auth0) and set the `role` claim.
+- Set your commission take-rate in `lib/commission.js`.
+- Add `needs: { ai: true }` (injects `AI_GATEWAY_URL`) only if you add AI features
+  like listing generation or search.
+- Build under `services/web/`, then `grid dev` (local) / `grid plug` (async — poll
+  to a live URL). Point the Stripe webhook at `<live-url>/api/webhooks/stripe`.