@cloudgrid-io/mcp 0.13.0 → 0.15.0

package/src/corpus/workflows/property-listings.md

@@ -0,0 +1,101 @@
+---
+name: property-listings
+when: property listings, real estate site, rentals/homes listings — a persistent site that stores and browses properties by location and price. 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 property listings site on the grid — a `properties` collection (title, price:number, location, beds:number, description) with a card grid, a location/price filter, a detail view, and an admin add form. 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: property-listings
+
+The user wants a real-estate / property listings site that **remembers** its
+properties — listings that 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 `properties` domain
+(title, price:number, location, beds:number, description) rendered as a card grid
+with a location/price filter, a per-property detail view, and an admin add form.
+
+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-listings
+   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", "property-listings")`. It is a minimal, real
+   Next.js + `mongodb`-driver listings site under `services/web/`: a lazy client
+   in `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a
+   `properties` collection (GET supports `?location=` and `?maxPrice=` filters), a
+   server-component page that reads + filters, and a client card grid with a
+   detail view and admin add 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.**
+
+## 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.

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

@@ -0,0 +1,105 @@
+---
+name: quiz-platform
+when: quiz, quiz platform, trivia, assessment, questionnaire — a persistent app that stores questions and lets people take a scored quiz, with an admin form to add questions. 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 quiz/trivia platform on the grid — a `questions` collection ({ prompt, options: string[], answerIndex: number }) with a take-quiz UI that computes a score and an admin add-question form. 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: quiz-platform
+
+The user wants a quiz / trivia / assessment app that **remembers** its questions
+— a quiz whose question bank survives refresh and is 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 `questions` domain
+(`{ prompt: string, options: string[], answerIndex: number }`): a take-quiz UI
+that lets a visitor pick one option per question and submit for a computed score,
+plus an admin form that adds new questions.
+
+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-quiz
+   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", "quiz-platform")`. It is a minimal, real Next.js +
+   `mongodb`-driver quiz platform under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a
+   `questions` collection, a server-component page that reads the collection, and
+   a client component (`quiz.js`) that runs the take-quiz UI (score computed by
+   comparing each chosen option index against the question's `answerIndex`) and
+   an admin add-question 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 route handlers `export const dynamic = "force-dynamic"` so questions
+     are always read/written live.
+
+## 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 quiz 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/restaurant-reservations.md

@@ -0,0 +1,123 @@
+---
+name: restaurant-reservations
+when: "restaurant website with reservations, table booking, restaurant site — a public Next.js site with menu content and a persistent reservations/table-booking collection backed by Mongo. Runtime app → local edition. This is a BLUEPRINT: read AGENTS.md for the structure, then build the app."
+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). Third-party secrets (Stripe deposit, email) go through the `vault:` block. A confirmation-reminder cron service is DESIGNED but NOT deployable yet (platform issue #1543)."
+summary: "BLUEPRINT for a restaurant website with online reservations — a public Next.js + Mongo site (menu content + a reservations / table-booking collection) on the grid. It is structure + cloudgrid.yaml, not runnable code: fetch the template, READ AGENTS.md for the file tree, the menu/reservations/tables collections, and the CloudGrid wiring (DATABASE_MONGODB_URL injection, vault: for Stripe/email secrets, optional auth, deploy/poll), then build the app under services/web/ following it. needs:{database:true} (not requires:). Async runtime deploy, local edition only. Cron reminders are designed but PENDING #1543."
+---
+
+# Workflow: restaurant-reservations
+
+The user wants a **restaurant website with online reservations** — a public site
+with menu content and a booking form (optionally table booking) whose
+reservations **persist** and are shared across sessions. That is a **runtime app**
+backed by the grid's shared Mongo, not a static page.
+
+**This is a BLUEPRINT.** The template does NOT contain app code — it ships a
+`cloudgrid.yaml` and an `AGENTS.md` structure guide. The recipe is: fetch it,
+**read `AGENTS.md`**, then build the app under `services/web/` following that
+structure (the proven `app-with-data` shape, with a `reservations` domain).
+
+Be honest that a runtime deploy is async (not instant like a static drop), that
+it needs the local edition, and that the confirmation-reminder **cron** service
+is designed but **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 menu page** (no bookings) instead, and STOP the runtime path.
+- **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", "restaurant-reservations")`. This is a **blueprint**,
+so the deliverable is `cloudgrid.yaml` + `AGENTS.md`, not app code.
+
+**Read `AGENTS.md` before building.** It defines:
+- the file tree (`services/web/{app/, lib/, api routes, package.json}`, optional
+  Stripe checkout + webhook routes, optional staff auth, a `services/reminder/`
+  cron job),
+- the Mongo collections + fields (`menu`, `reservations`, `tables`),
+- how CloudGrid injects the DB (`DATABASE_MONGODB_URL` / legacy `MONGODB_URL`) and
+  vault secrets, how to wire Stripe/auth, deploy steps, and the cron shape.
+
+## 4. Scaffold + fill
+
+1. `gridctl_init` an app `<name>` — creates the entity + `.cloudgrid/link.json`
+   and a `cloudgrid.yaml` with an EMPTY `services: {}`. Run `init` FIRST (plug
+   needs a linked directory).
+2. Write the app under **`services/web/`** (`path:` is the URL mount, NOT the
+   filesystem path), following `AGENTS.md`.
+3. Set `cloudgrid.yaml` to the blueprint's active fields:
+   ```yaml
+   name: my-restaurant
+   vault:
+     STRIPE_KEY: stripe-live-key      # only if taking a deposit
+     SENDGRID_API_KEY: sendgrid-key   # confirmation / reminder email
+   services:
+     web:
+       type: nextjs
+       path: /
+   needs:
+     database: true
+   ```
+   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).
+4. **Read the DB from `process.env.DATABASE_MONGODB_URL`** (legacy `MONGODB_URL`
+   fallback) behind a **lazy getter** — never at module top level, or `next build`
+   fails. Third-party keys come from the vault-injected env vars
+   (`process.env.STRIPE_KEY`, `process.env.SENDGRID_API_KEY`).
+
+## 5. Config / secrets
+
+- Secret values (Stripe, SendGrid, auth) → `gridctl_secrets` (the `vault:` block
+  maps them to env vars). Non-secret config (publishable keys, flags) →
+  `gridctl_env`.
+- Do **NOT** set the DB vars yourself (`DATABASE_MONGODB_URL` / `MONGODB_URL`) —
+  the grid injects them.
+
+## 6. (Optional) Run locally
+
+`grid dev` runs Next.js with `DATABASE_MONGODB_URL` and vault vars injected
+against dev Mongo. Seed the `menu` collection, test a booking. Don't require it.
+
+## 7. Deploy (async)
+
+Deploy `services/web/` with `gridctl_plug`. 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.
+- Only once live, return the deployed app URL (NOT the build/log link).
+- If Stripe deposits are on, register the live `/api/webhooks/stripe` URL in the
+  Stripe dashboard.
+
+## 8. Cron reminders — PENDING #1543
+
+The design includes a daily cron job that emails reminders to next-day bookings
+(a `reminder:` cron service reading the same injected `DATABASE_MONGODB_URL` +
+`SENDGRID_API_KEY`). **Cron deploy is not yet available (platform issue #1543)** —
+keep the `reminder:` cron block **commented** in `cloudgrid.yaml`; an active cron
+service will be rejected at plug until #1543 lands. Build the rest now; enable
+cron once it ships. See `AGENTS.md` §7 for the intended shape and interim
+workaround.
+
+## 9. 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: blueprint you built out,
+async build, local-edition only, DB + secrets injected by the grid, cron pending.

package/src/corpus/workflows/revenue-dashboard.md

@@ -0,0 +1,102 @@
+---
+name: revenue-dashboard
+when: revenue dashboard, sales dashboard, MRR/revenue view — a persistent app that records sales and shows total revenue, a per-product breakdown, and recent activity. 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 revenue dashboard on the grid — a `sales` collection (product, amount:number, at) rendered as a total-revenue figure, a per-product breakdown, and a recent-sales table with an add form. 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: revenue-dashboard
+
+The user wants a revenue / sales dashboard that **remembers** its sales — a view
+whose numbers 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 `sales` domain
+(`product`, `amount` as a number, `at` timestamp) and a dashboard view: a total
+revenue figure, a per-product breakdown, a recent-sales table, and an add form.
+
+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-revenue-dashboard
+   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", "revenue-dashboard")`. It is a minimal, real
+   Next.js + `mongodb`-driver dashboard under `services/web/`: a lazy client in
+   `services/web/lib/db.js`, an App-Router GET/POST/DELETE route on a `sales`
+   collection, a server-component page that computes the total + per-product
+   breakdown + recent table, and a client add-sale 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.**
+   - Sales documents are `{ product: string, amount: number, at: Date }`; keep
+     `amount` numeric so the total and breakdown sums are correct.
+
+## 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.

package/src/corpus/workflows/semantic-search.md

@@ -0,0 +1,133 @@
+---
+name: semantic-search
+when: "search over my documents / PDFs / notes / knowledge base, semantic search, document search, find across my files, searchable archive. Needs a database → runtime → local edition."
+needs: database
+deploy: runtime
+editions: local
+capabilities_note: "Document search — needs a database (Mongo) for the documents + chunks collections. Two services: a React (Vite) static frontend at / and a FastAPI backend at /backend. Hybrid search = Mongo $text (lexical) + in-app NumPy cosine over chunk embedding arrays (semantic) + metadata filters, blended to the document level. Runtime app, async build, local edition only. Declare needs:{database:true}. NO needs:vector — pgvector runtime role-grant is blocked (#1545), so embeddings live in the Mongo chunks collection and are cosine-ranked in-app. NO active cron — a Python type:cron refresh is blocked (#1585); ship the manager 'Refresh now' endpoint. Health is green with no secrets; startup ensure_indexes() so $text never 500s on an empty catalog. Pluggable source (dropbox|local|url) + embeddings (OpenAI-compatible) each behind one config point, all secrets from env."
+summary: "Build a document-search app on the grid — index a folder of PDFs/DOCX/TXT/MD, then search by keyword + meaning + metadata, with a grounded answer mode and manager admin. React static frontend at / + FastAPI backend at /backend, backed by grid-shared Mongo. Edition-gate first, scaffold, put the code under services/web/ + services/backend/, declare needs:{database:true} (NO vector #1545, NO active cron #1585), set the embeddings + source + manager secrets, deploy async, poll to a live URL, then Refresh now to index."
+recipe: "edition-gate -> auth+grid -> gridctl_init -> fetch template + read AGENTS.md -> put code under services/web + services/backend, set cloudgrid.yaml active fields -> grid secrets set (embeddings + source + MANAGER_PASSWORD_HASH) -> optional grid dev -> grid plug (async, poll) -> Refresh now to index -> return live URL"
+---
+
+# Workflow: semantic-search
+
+The user wants to **search over their own documents** — a searchable archive of
+PDFs / DOCX / notes / a knowledge base, by keyword *and* by meaning, not just a
+static page. That is a **persistent runtime app**: a React (Vite) static frontend
+at `/` and a FastAPI backend at `/backend`, backed by the grid-shared Mongo. The
+backend indexes a document source into `documents` + `chunks` collections and
+serves **hybrid search** — Mongo `$text` (lexical) + in-app NumPy cosine over the
+chunk embedding arrays (semantic) + metadata filters, blended and aggregated to
+the document level with a best-passage highlight.
+
+This template ships **real, runnable code** — fetch it, read `AGENTS.md`, adapt
+the metadata naming to the user's domain, wire secrets, deploy. Be honest that a
+runtime deploy is async and needs the local edition.
+
+## 1. Edition check FIRST (hard gate)
+
+A document-search app is a built + deployed multi-service 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. Say so plainly, offer a
+  static explainer 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. Scaffold
+
+`gridctl_init` an app `<name>` FIRST — it creates the entity +
+`.cloudgrid/link.json` and a starter `cloudgrid.yaml` with empty `services: {}`
+(`plug` needs a linked directory).
+
+## 4. Fetch the template and READ AGENTS.md
+
+`gridctl_fetch("template", "semantic-search")`. Read **`AGENTS.md`** before
+writing anything — it defines the file tree, the `documents` + `chunks`
+collections + fields, the Mongo injection, the pluggable source adapter, the
+embeddings config point, the secrets, the deploy flow, and the four baked-in
+learnings you must NOT regress (health-without-secrets, startup index, `$text`
+guard, no vector / no cron).
+
+## 5. Put the code under services/ and fill cloudgrid.yaml
+
+**Every service's code MUST live under `services/<name>/`** — `path:` is the URL
+mount, NOT the filesystem path (`web` → `services/web/`, `backend` →
+`services/backend/`). Set `cloudgrid.yaml` to the template's active fields:
+
+```yaml
+name: my-search
+services:
+  web:
+    type: static
+    path: /
+    build:
+      command: npm run build
+      output: dist
+    node_version: "22"
+  backend:
+    type: python
+    path: /backend
+needs:
+  database: true
+```
+
+**Declare `needs: { database: true }`** — the deployer provisions Mongo and
+injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`), read lazily in
+`app/db.py`. `requires:` is the deprecated v1 alias; never author it and never set
+`needs:` and `requires:` together (the validator rejects the combination).
+
+**NO `needs: vector`** — the pgvector runtime role-grant is blocked on platform
+issue **#1545**, so this template stores embeddings in the Mongo `chunks`
+collection (a float array) and cosine-ranks in-app. **NO active cron** — a Python
+`type: cron` refresh is blocked on **#1585**; the cron service stays commented and
+the manager "Refresh now" endpoint does the indexing.
+
+## 6. Configure the source + embeddings (one config point each)
+
+- **Source** — `SOURCE_TYPE` selects the adapter (`dropbox` default | `local` |
+  `url`). Set it plus that adapter's secrets:
+  - dropbox: `DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET`, `DROPBOX_REFRESH_TOKEN`,
+    optional `DROPBOX_FOLDER_PATH`.
+  - local: `LOCAL_SOURCE_PATH` (or add `needs: { disk: true }` → `DISK_PATH`).
+  - url: `URL_SOURCE_MANIFEST` (newline/comma-separated URLs).
+- **Embeddings** — `EMBEDDINGS_API_KEY` (OpenAI by default;
+  `EMBEDDINGS_BASE_URL` / `EMBEDDINGS_MODEL` to point elsewhere).
+- **Manager** — `MANAGER_PASSWORD_HASH` = sha256 hex of the manager password.
+
+Store all of these with `grid secrets set KEY=VALUE` (never commit them; the app
+reads them lazily inside functions, never at import). Non-secret public config →
+`gridctl_env`. Do NOT set `DATABASE_MONGODB_URL` yourself — the grid injects it.
+
+The app starts and passes `GET /backend/health` with **none** of these set;
+search/indexing degrade to a clear "not indexed / missing secret" state.
+
+## 7. (Optional) Run locally
+
+Mention the user can `grid dev` to run locally against the injected dev Mongo
+before deploying. Don't require it.
+
+## 8. 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).
+
+## 9. Index + iterate
+
+Sign in as manager and hit **"Refresh now"** (Settings) to index the source into
+Mongo, then search. 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 ships real code you adapt, the build is async and
+local-edition only, Mongo is injected by `needs`, embeddings live in Mongo (no
+pgvector until #1545), and refresh is a manual endpoint until the cron unblocks
+(#1585).