@cloudgrid-io/mcp 0.13.0 → 0.14.0

package/src/corpus/workflows/blog-cms.md

@@ -0,0 +1,104 @@
+---
+name: blog-cms
+when: blog, CMS, content site with posts, publishing platform, articles — a persistent app that stores and publishes posts (title, body, tags, published flag). Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo blog / CMS on the grid — a `posts` collection (title, slug, body, tags, published, createdAt) with a public list, a single-post page, and an admin create/delete screen. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: blog-cms
+
+The user wants a blog, content site, or CMS that **remembers** its posts — a
+publishing platform whose articles survive refresh and are shared across
+sessions. That is a **runtime app** backed by the grid's shared Mongo, not a
+static page. It is the same proven shape as `app-with-data`, with a `posts`
+domain (title, slug, body, tags, published, createdAt): a public post list, a
+single-post page at `/posts/[slug]`, and an admin screen to create and delete
+posts (drafts stay off the public list).
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-blog
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "blog-cms")`. It is a minimal, real Next.js +
+   `mongodb`-driver blog under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `posts`
+   collection, a server-component list page, a single-post page at
+   `app/posts/[slug]/page.js`, and an admin server page + client form.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+   - **Keep DB-reading pages and the API route `export const dynamic =
+     "force-dynamic"`** so they read/write live data instead of being
+     statically prerendered at build.
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live blog URL — that is the deliverable. To iterate, re-plug
+the SAME entity so it updates the same URL. Keep it honest: async build,
+local-edition only, credentials injected by the grid.

package/src/corpus/workflows/booking-system.md

@@ -0,0 +1,116 @@
+---
+name: booking-system
+when: booking system, reservations, appointment booking, scheduling — a persistent app where users reserve time slots / appointments that survive refresh and are shared across sessions. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo). Runtime app, async build, local edition only. BLUEPRINT — ships structure + cloudgrid.yaml, not app code; read AGENTS.md and build. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Payment/auth secrets via the `vault:` block → env vars. Reminder cron is NOT yet deployable (platform issue #1543)."
+summary: "Build a persistent Next.js + Mongo appointment / reservation booking system on the grid — `services`, `availabilityRules`, `bookings` collections with slot-availability logic, Stripe checkout, an auth provider, and a (pending) reminder cron. This is a BLUEPRINT: fetch it, read AGENTS.md for the file tree + data model + CloudGrid wiring, then build the app under services/web/. Edition-gate first, scaffold, declare needs:{database:true} (not requires:), map secrets via vault:, deploy async, poll to a live URL."
+---
+
+# Workflow: booking-system
+
+The user wants a booking / reservations / appointment-scheduling app that
+**remembers** its bookings — reservations that survive refresh and are shared
+across sessions. That is a **runtime app** backed by the grid's shared Mongo, not
+a static page. The proven runtime shape is the same as `app-with-data` (Next.js +
+lazy Mongo client under `services/web/`), with a booking domain (bookable
+`services`, `availabilityRules`, and `bookings` with slot-overlap protection),
+Stripe checkout for paid appointments, an auth provider for accounts, and a
+scheduled reminder job.
+
+**This is a BLUEPRINT.** It does NOT ship prewritten app code — it ships the
+annotated `cloudgrid.yaml` and an `AGENTS.md` structure guide (file tree, Mongo
+data model, and CloudGrid wiring). Fetch it, **read `AGENTS.md`**, then build the
+app under `services/web/` following it.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop), that it needs the local edition, and that the reminder **cron
+service is not yet deployable** (platform issue #1543).
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly,
+  offer a **static preview** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Read the blueprint, then scaffold
+
+1. Fetch the blueprint: `gridctl_fetch("template", "booking-system")`. **Read its
+   `AGENTS.md`** — it is the structure guide (file tree under `services/web/`, the
+   `services` / `availabilityRules` / `bookings` collections + the double-booking
+   guard, how CloudGrid injects the DB and vault secrets, how to wire Stripe +
+   auth, and the reminder-cron design).
+2. `gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+   and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a
+   linked directory, so run `init` FIRST.
+
+## 4. Build the app + set cloudgrid.yaml
+
+1. Build the files under **`services/web/`** per the AGENTS.md file tree. **App
+   code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT the
+   filesystem path.
+2. Set `cloudgrid.yaml` to the blueprint shape:
+   ```yaml
+   name: my-booking
+   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
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+3. **Read every injected var lazily** (inside a getter), never at module top level
+   — `process.env.DATABASE_MONGODB_URL || process.env.MONGODB_URL`, and the vault
+   secrets (`STRIPE_KEY`, etc.) the same way. A top-level read fails `next build`.
+4. **Keep the reminder cron COMMENTED.** cron deploy is PENDING platform issue
+   #1543 — `plug` rejects a `type: cron` service. Ship `web` alone; use the
+   stopgap in AGENTS.md §7 for reminders until #1543 lands.
+
+## 5. Config (secrets)
+
+- Payment/auth secrets → add the vault items with `gridctl_secrets` (e.g.
+  `stripe-live-key`, `stripe-webhook-secret`, `auth-provider-key`) BEFORE plug so
+  the `vault:` mappings resolve. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 6. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo +
+vault env vars before deploying. Good for testing slot/availability logic. Don't
+require it.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid, and the reminder cron pending #1543.

package/src/corpus/workflows/calendar-scheduler.md

@@ -0,0 +1,134 @@
+---
+name: calendar-scheduler
+when: "calendar scheduler, team calendar, scheduling app, meeting scheduler"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical needs:{database:true}; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Scheduled reminders want a type:cron service — BLOCKED on platform issue #1543 (documented, not yet deployable). Optional auth/payments/reminder secrets map through a vault: block (AUTH_PROVIDER_KEY / STRIPE_KEY / SENDGRID_API_KEY) with grid secrets set."
+summary: "A BLUEPRINT for a calendar / scheduling app — events, availability slots, timezones + recurrence, optional bookings, on persistent Next.js + Mongo. This is not fill-in-the-blanks app code; it ships structure + cloudgrid.yaml. Fetch the template, read AGENTS.md for the file tree / collections / CloudGrid wiring (needs + optional vault) + the cron reminder shape (blocked on #1543), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
+---
+
+# Workflow: calendar-scheduler
+
+The user wants a calendar / scheduling app — a **team calendar**, a **meeting
+scheduler**, or a booking-style **scheduling app**. That is a **persistent runtime
+app** (Next.js + the grid's shared Mongo) whose domain is **events and
+availability**: events on a calendar, bookable time slots, timezones, recurrence,
+and (eventually) scheduled reminders. It is the `app-with-data` / `crm` shape with
+a time/availability domain.
+
+**This is a BLUEPRINT.** Unlike a fill-in-the-blanks template, it ships
+*structure* — a `cloudgrid.yaml` and an `AGENTS.md` structure guide — not finished
+app code. The recipe is: fetch it, **read `AGENTS.md`**, then **build** the app
+following it. Be honest that a runtime deploy is async and needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A calendar scheduler is a built + deployed container (Next.js + Mongo). It
+requires the **local edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly,
+  offer a **static calendar mockup** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Fetch the blueprint and READ AGENTS.md
+
+`gridctl_fetch("template", "calendar-scheduler")`. The deliverable is the
+**`AGENTS.md` structure guide** — read it before writing anything. It defines:
+- the `services/web/` file tree (calendar page, event + booking routes, `lib/`),
+- the Mongo collections (`events`, `availability`, optional `bookings`) + fields,
+- the CloudGrid injection table (needs + optional vault + AI gateway),
+- the optional auth (Clerk/Auth0 + `ownerId`) and payments (Stripe Checkout +
+  signed webhook) layers,
+- the intended **cron reminder** service shape — **BLOCKED on platform issue
+  #1543** (documented, not yet deployable),
+- the deploy flow.
+
+There is no app code to copy — you generate it from the guide.
+
+## 4. Scaffold + fill cloudgrid.yaml
+
+`gridctl_init` an app `<name>` FIRST (creates the entity + `.cloudgrid/link.json`
+and a starter `cloudgrid.yaml` with empty `services:{}`; `plug` needs a linked
+directory). Then put the app under **`services/web/`** and set `cloudgrid.yaml` to
+the blueprint's active fields:
+
+```yaml
+name: my-calendar
+services:
+  web:
+    type: nextjs
+    path: /
+needs:
+  database: true
+```
+
+**App code MUST live under `services/<name>/`** — `path:` is the URL mount, NOT
+the filesystem path. **Declare `needs: { database: true }`** (canonical) — the
+deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (+ legacy
+`MONGODB_URL`). `requires:` is the deprecated v1 alias; never author it and never
+set `needs:` and `requires:` together (the validator rejects the combination).
+Add a `vault:` entry only when you actually layer in auth / payments / reminders.
+
+## 5. Build the app following AGENTS.md
+
+Generate the files under `services/web/` per the guide:
+- **Lazy getter** for Mongo — read `process.env.DATABASE_MONGODB_URL` (legacy
+  `MONGODB_URL` fallback) **inside** a getter, never at module top level (a
+  top-level read fails `next build`). Same lazy pattern for any Stripe/auth client.
+- **Store all times as UTC `Date` in Mongo**; convert at the edges. Keep timezone
+  / recurrence / overlap logic in a pure `lib/time.js` (expand RRULEs at read
+  time — do not store every instance).
+- Range-query events for the visible window (`startAt < end && endAt > start`);
+  index `{ ownerId: 1, startAt: 1 }`.
+- (Optional) auth: init an SDK in `lib/auth.js` from `AUTH_PROVIDER_KEY`, stamp
+  `ownerId` on writes, gate write APIs in `middleware.js`, keep the public
+  `book/[slug]` page open.
+- (Optional) payments: Stripe Checkout for paid bookings + a signature-verified
+  webhook (read the RAW body before verifying).
+
+## 6. Scheduled reminders (cron) — BLOCKED on #1543
+
+Reminders want a second service of `type: cron` (scan due reminders every few
+minutes, send mail/SMS). **Cron deploy is a PENDING platform issue (#1543)** — do
+NOT uncomment the cron `reminders` service in `cloudgrid.yaml` yet; it will not
+schedule. Ship the HTTP app now and add cron once #1543 lands. If the user needs
+reminders sooner, use the interim workaround in AGENTS.md §5 (an external
+scheduler hitting an authenticated `POST /api/cron/reminders` route on `web`).
+
+## 7. Config / secrets
+
+- Map any secrets in the `vault:` block, then **store the values**:
+  `grid secrets set auth-provider-key …`, `grid secrets set stripe-live-key sk_live_…`,
+  `grid secrets set sendgrid-key SG.…`. Non-secret public config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 8. (Optional) Run locally
+
+Mention the user can `grid dev` to run locally against the injected dev Mongo (+
+secrets) before deploying. Don't require it.
+
+## 9. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 10. Return the live URL + iterate
+
+Give the user the live app URL — the deliverable. To iterate, re-plug the SAME
+entity so it updates the same URL. Keep it honest: this is a blueprint you built
+from, the build is async, it is local-edition only, Mongo is injected via `needs`,
+optional secrets via `vault` + `grid secrets set`, and scheduled reminders wait on
+platform issue #1543.

package/src/corpus/workflows/company-website.md

@@ -0,0 +1,46 @@
+---
+name: company-website
+when: company website, business site, corporate site, about-us site, small-business homepage
+needs: none
+deploy: inspiration
+editions: all
+capabilities_note: static — no infrastructure. Publishes as an inspiration (instant, works on hosted) via gridctl_drop.
+summary: Fetch the company-website template, fill it with the user's content across hero/about/services/team/contact, deploy it, and return the live share URL.
+---
+
+# Workflow: company-website
+
+Detect the intent ("build me a company website / business site / about-us page
+for X") and follow this recipe. Do not ask setup questions first; use sensible
+defaults from what the user tells you and build.
+
+1. **Fetch the template.** Call `gridctl_fetch("template", "company-website")` to
+   load the self-contained multi-section HTML company site.
+2. **(Optional) Fetch the example.** Call `gridctl_fetch("example", "company-website")`
+   to see a filled site as a reference for tone and structure.
+3. **Fill the template.** Replace the `{{PLACEHOLDER}}` tokens with the user's
+   content, section by section:
+   - **Identity + hero:** company name, tagline, headline, subheadline, and the
+     two call-to-action labels.
+   - **About:** headline, two short paragraphs, and four stat number/label pairs.
+   - **Services:** one card per offering — a single-emoji icon, title, and short
+     description. Duplicate a `.card` block between the `SERVICES_START` /
+     `SERVICES_END` comments to add more.
+   - **Team:** one member per person — avatar initials, name, role, short bio.
+     Duplicate a `.member` block between `TEAM_START` / `TEAM_END` to add more.
+   - **Contact:** headline, subheadline, email, phone, address, hours.
+   - Keep it a single self-contained HTML file. Do not add external scripts,
+     stylesheets, fonts, or large embedded media. Recolor via the `:root` CSS
+     variables (`--accent`, `--bg`, `--fg`) if the user has brand colors.
+4. **Deploy.** Deploy the filled HTML:
+   - Hosted MCP edition: call the drop tool with the HTML.
+   - Local MCP / CLI edition: write the HTML to a file and run `gridctl plug`.
+   A company website is an inspiration and deploys synchronously, so you get a
+   URL right away.
+5. **Return the live share URL.** Give the user the URL that serves the page.
+   For revisions, re-deploy with the entity id from the first deploy — it updates
+   the same share URL, so the user iterates on one link.
+
+Keep the whole flow tight: fetch, fill, deploy, share. The contact form is
+client-side only; mention the user can wire it to their own email service or
+form endpoint if they want real submissions.

package/src/corpus/workflows/course-platform.md

@@ -0,0 +1,126 @@
+---
+name: course-platform
+when: "course platform, sell online courses, teachable-style"
+needs: database
+deploy: runtime
+editions: local
+kind: blueprint
+capabilities_note: "persistent — needs a database (Mongo) plus auth + Stripe payments (vault-injected secrets). Runtime app, async build, local edition only. Declare the canonical needs:{database:true}; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL). Secrets (STRIPE_KEY, STRIPE_WEBHOOK_SECRET, AUTH_PROVIDER_KEY) come from the vault: block."
+summary: "Build a Teachable-style course platform on the grid — sell online courses, gate lessons behind a Stripe purchase, track per-student progress. This is a BLUEPRINT — the template ships the correct cloudgrid.yaml + an AGENTS.md structure guide (file tree, Mongo collections courses/lessons/enrollments/progress, env/vault wiring, auth + Stripe checkout/webhook routes, async deploy). Read AGENTS.md, then build the app under services/web/ following it. Edition-gate first, scaffold, wire DATABASE_MONGODB_URL and vault secrets lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL."
+---
+
+# Workflow: course-platform
+
+The user wants a Teachable-style course platform: sell online courses, gate
+lessons behind a Stripe purchase, and track each student's lesson progress. That
+is a **persistent runtime app** — Next.js + the grid's shared Mongo, with auth
+and payments — not a static page.
+
+**This is a blueprint.** The template does NOT ship runnable app code. It ships
+the correct `cloudgrid.yaml` and an `AGENTS.md` structure guide. Your job is to
+**read `AGENTS.md`, then build the app under `services/web/` following it.**
+
+Be honest that a runtime deploy is async (not instant like a static drop) and
+that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A course platform is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user plainly,
+  offer a **static course landing page** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Read the blueprint
+
+Fetch the structure guide: `gridctl_fetch("template", "course-platform")`. It
+contains AGENTS.md — the CloudGrid-specific spec you must follow:
+
+- the file tree under `services/web/` (catalog page, course detail, gated lesson
+  player, dashboard, and the API routes: courses, enrollments, progress, checkout,
+  Stripe webhook),
+- the Mongo collections + fields (`courses`, `lessons`, `enrollments`,
+  `progress`) and the access rule (a lesson is viewable if `isFreePreview` OR an
+  `enrollments` doc exists — enforced on the server),
+- how CloudGrid injects the DB URL and the vault secrets,
+- how to wire auth (a provider SDK like Clerk/Auth0) and Stripe (checkout +
+  webhook routes),
+- the async deploy steps.
+
+## 4. Scaffold + fill cloudgrid.yaml
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. Run `init` FIRST —
+`plug` needs a linked directory. Then set `cloudgrid.yaml` to the shape below and
+write the app under **`services/web/`** (`path: /` is the URL mount, NOT the
+filesystem path).
+
+```yaml
+name: my-courses
+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
+```
+
+**Declare the datastore with `needs: { database: true }`** — the canonical shape.
+The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus the legacy
+`MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't author new
+yaml with it, and never set `needs:` and `requires:` together (the validator
+rejects it).
+
+## 5. Build the app (following AGENTS.md)
+
+Build the Next.js app under `services/web/` per the guide. Critical CloudGrid
+rules:
+
+- **Read every injected var LAZILY, inside a getter — never at module top level**,
+  or `next build` fails. That covers `process.env.DATABASE_MONGODB_URL` (legacy
+  `MONGODB_URL` fallback) in `lib/db.js`, and the vault secrets `STRIPE_KEY` /
+  `STRIPE_WEBHOOK_SECRET` in `lib/stripe.js` and `AUTH_PROVIDER_KEY` in
+  `lib/auth.js`.
+- **Access is granted by the Stripe webhook**, not the checkout redirect: on
+  `checkout.session.completed`, create the `enrollments` doc. Verify the webhook
+  signature with `STRIPE_WEBHOOK_SECRET` against the RAW body.
+- **Gate the lesson player on the server** — check enrollment (or free preview),
+  never rely on hiding UI.
+
+## 6. Config (secrets + env)
+
+- Secrets → `gridctl_secrets`: `grid secrets set stripe-live-key`,
+  `grid secrets set stripe-webhook-secret`, `grid secrets set auth-provider-key`.
+  The `vault:` block injects them as `STRIPE_KEY`, `STRIPE_WEBHOOK_SECRET`,
+  `AUTH_PROVIDER_KEY`.
+- Non-secret config (e.g. the auth **publishable** key) → `gridctl_env`.
+- Do **NOT** set the DB vars yourself (`DATABASE_MONGODB_URL` / legacy
+  `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Wire Stripe + return the live URL
+
+Register the Stripe webhook to `https://<live-url>/api/webhooks/stripe` in the
+Stripe dashboard, and set its signing secret into the `stripe-webhook-secret`
+vault item. Give the user the live app URL — that is the deliverable. To iterate,
+re-plug the SAME entity so it updates the same URL. Keep it honest: async build,
+local-edition only, credentials injected by the grid.

package/src/corpus/workflows/directory.md

@@ -0,0 +1,101 @@
+---
+name: directory
+when: directory, business directory, member directory, listings directory — a persistent app that stores and shows searchable/filterable listings. Needs a database → runtime → local edition.
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: persistent — needs a database (Mongo). Runtime app, async build, local edition only. Declare the canonical `needs: { database: true }`; the deployer injects DATABASE_MONGODB_URL (+legacy MONGODB_URL).
+summary: Build a persistent Next.js + Mongo directory on the grid — an `entries` collection (name, category, url, description) with a searchable/filterable list plus add / delete. Edition-gate first, scaffold, put the app under services/web/, wire process.env.DATABASE_MONGODB_URL (legacy MONGODB_URL fallback) lazily, declare needs:{database:true} (not requires:), deploy async, poll to a live URL.
+---
+
+# Workflow: directory
+
+The user wants a **directory** — a searchable, filterable list of listings that
+**remembers** its entries: a business directory, member directory, or listings
+directory whose records survive refresh and are shared across sessions. That is
+a **runtime app** backed by the grid's shared Mongo, not a static page. It is the
+same proven shape as `app-with-data`, with an `entries` domain (name, category,
+url, description) and a list view with live search + category filtering and
+per-row delete.
+
+Follow this recipe. Be honest that a runtime deploy is async (not instant like a
+static drop) and that it needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A persistent app is a built + deployed container. It requires the **local
+edition** (Claude Desktop / Claude Code) or the CLI.
+
+- **Hosted edition (Claude Web / hosted MCP):** you CANNOT build a runtime app —
+  hosted is inline-only and can only publish static pages. Tell the user
+  plainly, offer a **static version** instead, and STOP the runtime path here.
+- **Local edition:** continue.
+
+## 2. Auth + grid
+
+1. Ensure signed in: `gridctl_login_status`; if not, `gridctl_login`.
+2. A grid is required. Respect the grid picker: if the user has more than one
+   grid, ask which to use; do not assume a target.
+
+## 3. Scaffold
+
+`gridctl_init` an app `<name>`. `init` creates the entity + `.cloudgrid/link.json`
+and writes a `cloudgrid.yaml` with an EMPTY `services: {}`. `plug` needs a linked
+directory, so run `init` FIRST. Then (a) write the app under **`services/web/`**,
+and (b) fill `cloudgrid.yaml` to the shape below (`services.web` + `needs:
+{ database: true }`).
+
+## 4. Add the datastore + wire Mongo
+
+1. Set `cloudgrid.yaml`. **App code MUST live under `services/<name>/`** —
+   `path:` is the URL mount, NOT the filesystem path.
+   ```yaml
+   name: my-directory
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   **Declare the datastore with `needs: { database: true }`** — the canonical
+   shape. The deployer provisions Mongo and injects `DATABASE_MONGODB_URL` (plus
+   the legacy `MONGODB_URL` alias). `requires:` is the deprecated v1 alias; don't
+   author new yaml with it, and never set `needs:` and `requires:` together (the
+   validator rejects it).
+2. Fetch the template for the Mongo wiring + CRUD shape:
+   `gridctl_fetch("template", "directory")`. It is a minimal, real Next.js +
+   `mongodb`-driver directory under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on an
+   `entries` collection, a server-component page, and a client list with search +
+   category filter.
+3. Adapt it (rename the collection, change fields, adjust the UI). **Read the DB
+   from `process.env.DATABASE_MONGODB_URL`** (legacy `process.env.MONGODB_URL`
+   fallback) — the grid injects it at dev-time and runtime.
+   - **Put the DB connection behind a lazy getter — never read the connection
+     string at module top level, or `next build` fails.**
+
+## 5. (Optional) Run locally
+
+Mention that the user can `grid dev` to run locally against the injected Mongo
+before deploying. Don't require it.
+
+## 6. Config
+
+- API keys / secrets → `gridctl_secrets`. Non-secret config → `gridctl_env`.
+- Do **NOT** set the DB connection vars yourself (`DATABASE_MONGODB_URL` or the
+  legacy `MONGODB_URL`) — the grid injects them.
+
+## 7. Deploy (async)
+
+Deploy the folder with `gridctl_plug`. A **runtime deploy is ASYNC**: the first
+response is `status: "building"`, NOT a live URL yet.
+- Poll `gridctl_status` (or the returned poll_url) until the entity is live.
+- Surface a liveness signal while it builds — never a bare silent wait.
+- Only once it is live, return the deployed app URL (NOT the build/log link).
+
+## 8. Return the live URL + iterate
+
+Give the user the live app URL — that is the deliverable. To iterate, re-plug the
+SAME entity so it updates the same URL. Keep it honest: async build, local-edition
+only, credentials injected by the grid.