@cloudgrid-io/mcp 0.13.0 → 0.14.0

package/src/corpus/templates/appointment-booking/AGENTS.md

@@ -0,0 +1,223 @@
+# AGENTS.md — appointment-booking (BLUEPRINT)
+
+This is a **blueprint**, not runnable code. It tells an agent how to build an
+appointment / clinic / salon booking app correctly on CloudGrid: a Next.js app
+where a business defines providers and services, publishes bookable time slots,
+and clients book an appointment against an available slot — with auth so a
+provider owns their calendar, optional Stripe deposits, and grid-shared Mongo
+for persistence. Read this whole file, then build the app under `services/web/`
+following the structure below. Do not skip the CloudGrid wiring rules — they are
+what make it deploy.
+
+The proven persistent shape is `app-with-data` (Next.js + Mongo). This blueprint
+extends it with auth, availability/slot logic, and optional Stripe deposits.
+Fetch that template for the Mongo lazy-client and App-Router API pattern:
+`gridctl_fetch("template", "app-with-data")`.
+
+## 1. File tree
+
+Build exactly this layout. **App code MUST live under `services/web/`** — the
+service is named `web`, so the CLI looks for `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: (auth + optional Stripe)
+services/web/package.json                      # next, react, react-dom, mongodb, + auth SDK (e.g. @clerk/nextjs); stripe only if deposits
+services/web/middleware.js                     # auth middleware: protects /dashboard/* + provider APIs — anon → sign-in
+services/web/lib/db.js                         # lazy Mongo client from DATABASE_MONGODB_URL (legacy MONGODB_URL fallback)
+services/web/lib/stripe.js                     # (optional) lazy Stripe client from process.env.STRIPE_KEY (never top-level)
+services/web/lib/slots.js                      # availability math: expand a provider's rules into concrete open slots, minus booked
+services/web/app/layout.js                     # root layout (+ auth provider wrapper if the SDK needs one)
+services/web/app/page.js                       # public: list providers/services to book
+services/web/app/book/[providerId]/page.js     # public: pick a service + an open slot for one provider
+services/web/app/dashboard/layout.js           # gate: server-side require signed-in provider; redirect anon → sign-in
+services/web/app/dashboard/page.js             # provider view: their services, availability rules, upcoming appointments
+services/web/app/api/providers/route.js        # GET list providers (public) / POST create provider (auth: owner)
+services/web/app/api/services/route.js         # GET services for a provider / POST create a bookable service (auth)
+services/web/app/api/availability/route.js     # GET open slots for provider+date (computed) / POST set availability rules (auth)
+services/web/app/api/appointments/route.js     # POST book a slot (public/client) / GET a provider's appointments (auth)
+services/web/app/api/appointments/[id]/route.js# PATCH reschedule/cancel / DELETE (auth or booking token)
+services/web/app/api/checkout/route.js         # (optional) POST: Stripe Checkout for a booking deposit → return url
+services/web/app/api/webhook/route.js          # (optional) POST: Stripe webhook — mark appointment deposit paid
+services/reminders/                            # (INTENDED cron job — PENDING #1543, see §7) reminder sender; not deployable yet
+```
+
+## 2. Mongo collections + fields
+
+The grid provisions Mongo from `needs: { database: true }`. Use four core
+collections. Booking correctness lives here — a slot is bookable only if no
+active `appointments` doc already occupies that provider + start time.
+
+**`providers`** — a bookable person/resource (doctor, stylist, room).
+- `_id` (ObjectId)
+- `ownerId` (string, indexed) — the auth provider's user id (Clerk/Auth0 `sub`) that owns this calendar
+- `name` (string), `bio` (string), `timezone` (string, e.g. `"America/New_York"`)
+- `createdAt` (Date)
+
+**`services`** — a bookable offering (a "30-min consult", "haircut").
+- `_id` (ObjectId)
+- `providerId` (ObjectId, indexed)
+- `name` (string), `durationMinutes` (number), `priceCents` (number, 0 = free)
+- `depositCents` (number, 0 = no deposit) — drives the optional Stripe flow
+- `active` (boolean)
+
+**`availability`** — a provider's recurring open hours (the rules slots expand from).
+- `_id` (ObjectId)
+- `providerId` (ObjectId, indexed)
+- `weekday` (number 0–6) — or store explicit date ranges if you prefer one-off availability
+- `startMinute` (number, minutes past midnight in the provider's tz), `endMinute` (number)
+- `slotMinutes` (number) — granularity to chop the window into
+
+**`appointments`** — a booked slot. This is the source of truth for "taken".
+- `_id` (ObjectId)
+- `providerId` (ObjectId, indexed), `serviceId` (ObjectId)
+- `startAt` (Date, UTC, indexed), `endAt` (Date, UTC)
+- `clientName` (string), `clientEmail` (string), `clientPhone` (string)
+- `status` (string) — `"pending" | "confirmed" | "cancelled" | "completed"`
+- `depositStatus` (string) — `"none" | "required" | "paid"` (drives Stripe gating)
+- `stripeSessionId` (string, optional), `reminderSentAt` (Date, optional — the cron sets this)
+- `createdAt` (Date)
+
+**Prevent double-booking.** Put a unique index on
+`appointments { providerId, startAt }` for `status ∈ {pending, confirmed}` (a
+partial unique index) and insert the booking inside a guarded write — so two
+clients racing for the same slot cannot both win.
+
+## 3. How CloudGrid injects everything (the wiring that matters)
+
+- **Mongo** — declared by `needs: { database: true }`. The deployer provisions
+  shared Mongo and injects the connection string as **`DATABASE_MONGODB_URL`**
+  (plus the legacy **`MONGODB_URL`** alias) at runtime and under `grid dev`.
+  Read `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL` **LAZILY,
+  inside the getter** in `lib/db.js` — never at module top level, or `next build`
+  fails when it imports the module for route analysis before the grid injects
+  the var. Never hardcode a connection string. Never set `needs:` and `requires:`
+  together — `requires:` is the deprecated v1 alias.
+- **Secrets (auth + optional Stripe) → env vars via the `vault:` block.** In
+  `cloudgrid.yaml` the `vault:` block maps each env var to a vault item key:
+  ```yaml
+  vault:
+    AUTH_PROVIDER_KEY: auth-provider-key
+    STRIPE_KEY: stripe-live-key                  # only if you take deposits
+    STRIPE_WEBHOOK_SECRET: stripe-webhook-secret # only if you take deposits
+  ```
+  Set the vault items ONCE with `gridctl_secrets` (or `grid secrets set`), then
+  the deployer injects each as the named env var (`process.env.AUTH_PROVIDER_KEY`,
+  `process.env.STRIPE_KEY`, …) at runtime and under `grid dev`. Do NOT commit
+  keys; do NOT set secrets in `services.web.env` (that block is for non-secret
+  config only). Read them LAZILY inside `lib/stripe.js` and the auth setup — same
+  rule as the DB.
+- **Public auth keys** — SDKs like Clerk also need a *publishable* key on the
+  client (`NEXT_PUBLIC_...`). Publishable keys are not secret; put them in the
+  non-secret `services.web.env` block (or as a build-time env), NOT the vault.
+- **AI (optional)** — if you add AI features (e.g. natural-language "book me next
+  Tuesday afternoon"), declare `needs: { ai: true }` and call the gateway at
+  `process.env.AI_GATEWAY_URL` via `@cloudgrid-io/ai`. Not required for this
+  blueprint.
+
+## 4. Wiring auth + payments
+
+**Auth (provider SDK, e.g. Clerk or Auth0).** Auth is for the *business side* —
+providers sign in to manage their calendar and see their appointments. Clients
+booking a public slot need not sign in (identify them by `clientEmail`), unless
+you want client accounts.
+1. Add the SDK to `services/web/package.json` (e.g. `@clerk/nextjs`).
+2. Server key from the vault (`process.env.AUTH_PROVIDER_KEY`); publishable key
+   from `services.web.env` as `NEXT_PUBLIC_...`.
+3. Wrap the app in the provider in `app/layout.js`.
+4. `services/web/middleware.js` protects `/dashboard/*` and the write/owner
+   endpoints (`POST /api/providers`, `/api/services`, `/api/availability`,
+   `GET /api/appointments`). The public booking routes (`GET /api/providers`,
+   `GET /api/availability`, `POST /api/appointments`) stay open. Every provider
+   API must scope its query by the signed-in `ownerId` — never trust a
+   `providerId` from the body for owner actions without checking ownership.
+
+**Slot computation (`lib/slots.js`).** This is the heart of correctness:
+1. For a provider + date, load their `availability` rules for that weekday and
+   the provider's `timezone`; chop each open window into `slotMinutes` candidate
+   starts, in the provider's local time, converted to UTC.
+2. Load `appointments` for that provider on that date with
+   `status ∈ {pending, confirmed}`; subtract any candidate whose `[startAt,endAt)`
+   overlaps a booked one (respect each service's `durationMinutes`).
+3. Return the remaining open slots. `GET /api/availability` returns these;
+   `POST /api/appointments` re-checks availability at write time (never trust the
+   client's slot) and inserts under the partial unique index from §2.
+
+**Payments (optional Stripe deposit).** Only if a service has `depositCents > 0`.
+1. Add `stripe` to `package.json`. Build a lazy Stripe client in `lib/stripe.js`
+   reading `process.env.STRIPE_KEY` inside the getter.
+2. **Checkout** — on booking a deposit-required service, `app/api/checkout/route.js`
+   (POST) creates a Stripe Checkout Session (`mode: "payment"`, amount =
+   `depositCents`), stashes the `appointmentId` in `metadata`, sets `success_url`
+   /`cancel_url`, returns `session.url`; the booking is written `status: "pending"`,
+   `depositStatus: "required"`, and the client is redirected to pay.
+3. **Webhook** — `app/api/webhook/route.js` (POST) verifies the signature with
+   `process.env.STRIPE_WEBHOOK_SECRET` (read the RAW request body — do not
+   JSON-parse before verifying). On `checkout.session.completed`, set the
+   appointment `depositStatus: "paid"`, `status: "confirmed"`. Register this
+   route's public URL as the webhook endpoint in the Stripe dashboard after
+   deploy. If a service has no deposit, book straight to `status: "confirmed"`.
+
+## 5. Deploy steps
+
+1. `gridctl_login_status` → `gridctl_login` if needed. Respect the grid picker
+   (ask which grid if the user has more than one).
+2. `gridctl_init` an app `<name>` FIRST — it creates the entity, writes
+   `.cloudgrid/link.json`, and a `cloudgrid.yaml` with empty `services: {}`.
+   `plug` needs a linked directory.
+3. Write the app under `services/web/` and set `cloudgrid.yaml` to the active
+   shape: `name` + `services.web{type: nextjs, path: /}` + `needs:{database:true}`
+   + the `vault:` block. (Leave the `reminders` cron service COMMENTED — see §7.)
+4. Set the secrets: `gridctl_secrets` for `auth-provider-key` (and, if taking
+   deposits, `stripe-live-key`, `stripe-webhook-secret` — the vault item keys the
+   `vault:` block maps from). Non-secret config (auth publishable key, price ids)
+   → `gridctl_env` / `services.web.env`. Do NOT set `DATABASE_MONGODB_URL`
+   yourself — the grid injects it.
+5. `gridctl_plug` to deploy. A runtime deploy is **ASYNC** — the first response
+   is `status: building`, not a live URL. Poll `gridctl_status` (or the returned
+   poll_url) until live; surface a liveness signal while it builds, never a bare
+   silent wait.
+6. If taking deposits, once live add the `/api/webhook` URL as the Stripe webhook
+   endpoint, copy the signing secret into the `stripe-webhook-secret` vault item,
+   then re-plug. Return the live app URL (not the build/log link).
+
+## 6. Edition note
+
+An appointment-booking app is a built + deployed runtime container, so 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 — it CANNOT build this app. On hosted, say so plainly and offer a
+static "book us" landing page (via `gridctl_drop`) instead, then stop the runtime
+path.
+
+## 7. Reminders (cron — PENDING platform issue #1543)
+
+The design wants a **scheduled reminder job**: on a fixed interval, find
+appointments entering the reminder window (e.g. starting in ~24h) that have not
+had a reminder sent, notify the client (email/SMS via a provider key from the
+vault), and stamp `reminderSentAt` so each appointment is reminded once.
+
+The **intended** cron service shape (already present, COMMENTED, in
+`cloudgrid.yaml`):
+
+```yaml
+services:
+  reminders:
+    type: cron
+    schedule: "*/15 * * * *"   # every 15 min
+    timezone: UTC
+    run: job                    # runs services/reminders/ as a one-shot job per tick
+```
+
+The cron job would live under `services/reminders/` (its own entry that opens the
+same Mongo via the injected `DATABASE_MONGODB_URL`, queries due appointments,
+sends, and stamps `reminderSentAt`). It inherits the app-level `needs: database`
+and can read a notification provider key from the `vault:` block.
+
+**IMPORTANT: cron deploy is currently a PENDING platform issue (#1543) and is NOT
+yet deployable.** Keep the `reminders` service COMMENTED in `cloudgrid.yaml` —
+uncommenting it today will not deploy. Until cron ships, either (a) ship the
+booking app without reminders, or (b) trigger reminders manually / from an
+external scheduler hitting an authenticated `/api/appointments` reminder
+endpoint. Document this limitation to the user; do not claim reminders are live.

package/src/corpus/templates/appointment-booking/README.md

@@ -0,0 +1,16 @@
+# appointment-booking template — BLUEPRINT (Next.js + auth + Mongo, optional Stripe)
+
+An appointment / clinic / salon booking app: a business defines providers and
+bookable services, publishes availability, and clients book an open time slot —
+with auth so a provider owns their calendar, optional Stripe deposits, and
+grid-shared Mongo (`providers`, `services`, `availability`, `appointments`) as
+the source of truth for what is booked. It exists because scheduling is
+correctness-sensitive (no double-booking, availability minus taken slots), so it
+ships as a **blueprint: the structure + the cloudgrid.yaml — adapt and build**,
+not finished code. Read `AGENTS.md` for the file tree, Mongo collections, the
+slot-computation and anti-double-booking rules, and the CloudGrid wiring
+(`needs: { database: true }` → `DATABASE_MONGODB_URL`; auth/Stripe secrets via
+the `vault:` block → env vars), then build the app under `services/web/` and
+deploy (async — poll to a live URL; local edition only). A scheduled reminder
+cron service is designed but its deploy is **PENDING platform issue #1543** — see
+AGENTS.md § 7.

package/src/corpus/templates/appointment-booking/cloudgrid.yaml

@@ -0,0 +1,250 @@
+# ============================================================================
+# 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: appointment-booking
+
+# 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.
+# Auth (so providers/clients own bookings) and optional deposit payments need
+# secrets injected as env vars — this is the CloudGrid-correct way. Set each
+# vault item once (grid secrets set), then the deployer injects it as the named
+# env var at runtime and under `grid dev`. Read them LAZILY, never top-level.
+vault:
+  AUTH_PROVIDER_KEY: auth-provider-key         # auth SDK server key (e.g. Clerk secret / Auth0 client secret)
+  STRIPE_KEY: stripe-live-key                  # Stripe secret key — optional booking deposits / prepayment
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret # verifies Stripe webhook signatures (deposit confirmation)
+
+
+# ─── 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
+
+  # ── INTENDED cron service — appointment reminders (NOT YET DEPLOYABLE) ──
+  # This design wants a scheduled job to send reminders for upcoming
+  # appointments (e.g. "24h before"). The shape below is the intended cron
+  # service. Cron deploy is a PENDING platform issue (#1543) — leave this
+  # COMMENTED until cron ships; uncommenting it today will not deploy. See
+  # AGENTS.md § "Reminders (cron — PENDING #1543)" for the intended behaviour.
+  # reminders:
+  #   type: cron
+  #   schedule: "*/15 * * * *"     # every 15 min: find appts entering the reminder window
+  #   timezone: UTC
+  #   run: job                     # runs services/reminders/ as a one-shot job per tick
+  #   # Inherits app-level needs (database) + vault (for the notification provider key).
+
+
+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
+# ============================================================================

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

@@ -0,0 +1,72 @@
+# Template: appointment-booking (BLUEPRINT — Next.js + auth + Mongo, optional Stripe)
+
+An appointment / clinic / salon booking app. **Blueprint, not finished code**:
+it ships the `cloudgrid.yaml` and a structure guide (`AGENTS.md`) so an agent can
+build it correctly on CloudGrid — a Next.js app where a business defines
+providers and bookable services, publishes availability, and clients book an open
+slot, with auth so a provider owns their calendar, optional Stripe deposits, and
+grid-shared Mongo. Read `AGENTS.md`, build the app under `services/web/`, adapt
+the providers/services/slot rules, then deploy (async — poll to a live URL).
+Local edition only.
+
+**Fetch the bundle:**
+- `gridctl_fetch("template", "appointment-booking")` — this blueprint (`cloudgrid.yaml` + `AGENTS.md`).
+- `gridctl_fetch("template", "app-with-data")` — the proven Next.js + Mongo shape to extend (lazy db client, App-Router API).
+
+**Key rules:**
+
+1. **Blueprint — read `AGENTS.md` first.** It has the file tree, the Mongo
+   collections (`providers`, `services`, `availability`, `appointments`), the
+   slot-computation + anti-double-booking rules, the CloudGrid injection table,
+   and the auth + Stripe wiring. Build following it; do not invent structure.
+2. **App code MUST live under `services/web/`.** `path: /` is the URL mount, NOT
+   the filesystem path. Root files fail with `Service directory not found`.
+3. **Mongo via `needs:{database:true}`** → the grid injects
+   `DATABASE_MONGODB_URL` (legacy `MONGODB_URL` fallback). Read it LAZILY inside
+   the getter, never at module top level (top-level read fails `next build`).
+4. **Secrets via the `vault:` block** → env vars. `AUTH_PROVIDER_KEY` (and, for
+   deposits, `STRIPE_KEY` / `STRIPE_WEBHOOK_SECRET`) map to vault items; set them
+   with `gridctl_secrets`, and the deployer injects them at runtime. Read lazily;
+   do not commit keys or put secrets in `services.web.env`.
+5. **No double-booking.** `appointments` is the source of truth for "taken";
+   compute open slots as availability minus booked, re-check at write time, and
+   guard the insert with a partial unique index on `{ providerId, startAt }`.
+6. **Never set `needs:` and `requires:` together** — `requires:` is the
+   deprecated v1 alias.
+7. **Reminders (cron) are designed but PENDING platform issue #1543** — keep the
+   `reminders` cron service COMMENTED in `cloudgrid.yaml`; it is not yet
+   deployable. See AGENTS.md § 7.
+
+## cloudgrid.yaml (active fields)
+
+```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: appointment-booking
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+vault:
+  AUTH_PROVIDER_KEY: auth-provider-key
+  STRIPE_KEY: stripe-live-key
+  STRIPE_WEBHOOK_SECRET: stripe-webhook-secret
+```
+
+> **Capability:** `needs: { database: true }` → the deployer provisions Mongo and
+> injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`). The `vault:` block maps
+> auth/Stripe secrets to env vars — the CloudGrid-correct way to inject
+> credentials. `requires:` is the deprecated v1 alias; don't mix it with `needs:`.
+> A `reminders` cron service is designed (commented) but cron deploy is PENDING
+> #1543. See the capability-map for the full injection table.
+
+## Deploy (async, local edition)
+
+`gridctl_init` first (creates the entity + link.json), write the app under
+`services/web/`, set the vault secrets with `gridctl_secrets`, `gridctl_plug`
+(async — poll `gridctl_status` to a live URL). If taking deposits, register the
+`/api/webhook` URL in Stripe and re-plug. Re-plug the same entity to update the
+same URL.