@cloudgrid-io/mcp 0.20.5 → 0.20.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Use CloudGrid via MCP to brainstorm, build, deploy, and improve apps, games, websites, dashboards, and tools and get a live URL - templates, recipes, managed databases and AI, instant single-page publish, and full-app deploys, for developers and non-technical users. Three editions: local stdio (full toolset), hosted web (light, CLI-free), and a public docs-search server, over MCP.",
   "type": "module",
   "bin": {
@@ -29,6 +29,7 @@
     "test:grid-picker": "node test/grid-picker.test.mjs",
     "test:plug-timeout": "node test/plug-timeout.test.mjs",
     "test:manifest-confirm": "node test/manifest-confirm.test.mjs",
+    "test:qa-courier": "node test/qa-courier.test.mjs",
     "test:drift-guard": "node test/drift-guard.mjs",
     "smoke:drop": "node test/smoke-drop.mjs",
     "smoke:login": "node test/smoke-login.mjs",

package/src/corpus/capability-map.md

@@ -18,7 +18,7 @@ cloudgrid.yaml schema (every field, the `needs:` injection table, the
 requires-vs-needs caveat, validation rules), fetch the companion reference:
 `grid_get_template("doc", "cloudgrid-yaml")`.
 
-## The 60 templates
+## The 61 templates
 
 | Intent (match on `when:`) | Template | `needs:` | Deploy | Edition |
 |---|---|---|---|---|
@@ -63,7 +63,8 @@ requires-vs-needs caveat, validation rules), fetch the companion reference:
 | revenue dashboard, sales dashboard, MRR/revenue view | `revenue-dashboard` | `database: true` | runtime (async, poll) | local |
 | property listings, real estate site, rentals/homes listings | `property-listings` | `database: true` | runtime (async, poll) | local |
 | project management, projects and tasks tracker, team project board | `project-management` | `database: true` | runtime (async, poll) | local |
-| search over my documents / PDFs / notes / knowledge base, semantic search, document search, find across my files, searchable archive | `semantic-search` | `database: true` (NO `vector` #1545; active daily refresh cron) | runtime (async, poll) | local |
+| semantic search over a document / article / text, search-by-meaning box, question-answering search over content, embeddings / vector / similarity search — ONE document or small text set, one service | `simple-semantic-search` | `vector: pgvector, ai: true` (native pgvector, verified live 2026-07-16) | runtime (async, poll) | local |
+| search over my documents / PDFs / notes / knowledge base with upload UI and scheduled refresh, document search portfolio, searchable archive (multi-service) | `semantic-search` | `database: true` (template uses Mongo embeddings; `vector: pgvector` now available, #1545 shipped; active daily refresh cron) | runtime (async, poll) | local |
 
 **Rule of thumb:** if the app must SAVE/remember data, share state across
 users/sessions, log in, or store submissions → it is persistent → runtime, local
@@ -86,8 +87,10 @@ real runnable code in a different shape from the Next.js family: a React (Vite)
 **static** frontend at `/` plus a **Python FastAPI** backend at `/backend`, on the
 same grid-shared Mongo (`needs: { database: true }`). Hybrid search = Mongo
 `$text` + in-app NumPy cosine over embedding arrays + metadata filters. It stores
-embeddings in the Mongo `chunks` collection (NO `needs: vector` — pgvector is
-blocked on **#1545**) and refreshes via a manager endpoint (NO active cron — a
+embeddings in the Mongo `chunks` collection (the template does not declare
+`needs: vector`; `vector: pgvector` is now available — **#1545** shipped, verified
+live 2026-07-16 — but the template code still ranks in-app) and refreshes via a
+manager endpoint (NO active cron — a
 Python `type: cron` is blocked on **#1585**). Read its `AGENTS.md` for the source
 adapter (dropbox/local/url) + embeddings wiring and the health-without-secrets /
 startup-index patterns.
@@ -97,7 +100,7 @@ startup-index patterns.
 | Intent | Would need | Status |
 |---|---|---|
 | scheduled task, cron job, "run every day/hour", periodic worker | a `type: cron` service (`schedule`, `timezone`) | **SUPPORTED** on CLI 0.14.0 — Python and Node `type: cron` services validate, deploy, and fire (platform #1585 fixed). See the semantic-search `refresh` cron for a working Python-job example. |
-| RAG chatbot, "answer over my own docs", semantic search, retrieval-augmented Q&A | `ai-app` + `needs: { vector: pgvector }` | **HELD** — platform issue #1545 (pgvector crashes the deploy). Ship the plain `ai-app` (no vector) for now. |
+| RAG chatbot, "answer over my own docs", semantic search, retrieval-augmented Q&A | `ai-app` + `needs: { vector: pgvector }` | AVAILABLE — #1545 shipped (verified live 2026-07-16). `vector: pgvector` deploys and injects `VECTOR_PGVECTOR_URL`; the shipped template still stores embeddings in Mongo until updated. |
 
 ## Blueprints (structure + cloudgrid.yaml; adapt the app — some pending platform support)
 
@@ -129,14 +132,15 @@ runtime, async build, **local edition only**. Auth/payment secrets map through a
 | appointment booking, clinic/salon booking, appointment scheduler | `appointment-booking` | `database: true` (+ auth/Stripe via `vault:`); reminder cron supported (Python/Node `type: cron`, 0.14.0) | runtime (async, poll) | local |
 | restaurant website with reservations, table booking, restaurant site | `restaurant-reservations` | `database: true` (+ Stripe/email via `vault:`); reminder cron supported (Python/Node `type: cron`, 0.14.0) | runtime (async, poll) | local |
 | travel booking portal, trip booking, flights/hotels booking, travel reservations | `travel-booking` | `database: true` (+ Stripe/auth via `vault:`); reminder cron supported (Python/Node `type: cron`, 0.14.0) | runtime (async, poll) | local |
-| RAG, ask my docs, knowledge base chatbot, retrieval-augmented search over documents | `ai-knowledge-base` | `ai: true, database: true`; ideal `vector: pgvector` **pending #1545** (store embeddings in Mongo + cosine-rank until it lands) | runtime (async, poll) | local |
+| RAG, ask my docs, knowledge base chatbot, retrieval-augmented search over documents | `ai-knowledge-base` | `ai: true, database: true`; ideal `vector: pgvector` now AVAILABLE (#1545 shipped; the shipped blueprint still uses Mongo embeddings until updated) | runtime (async, poll) | local |
 
 The booking family (`booking-system`, `calendar-scheduler`, `appointment-booking`,
 `restaurant-reservations`, `travel-booking`) is fully buildable today, **including**
 the reminder cron — Python and Node `type: cron` services work on CLI 0.14.0
 (platform #1585 fixed). `ai-knowledge-base` builds today on the AI Gateway + Mongo; its
-ideal `needs: { vector: pgvector }` embedding store is HELD on **#1545**, so store
-chunks in Mongo and cosine-rank in-app until it lands.
+ideal `needs: { vector: pgvector }` embedding store is now AVAILABLE (**#1545**
+shipped, verified live 2026-07-16) — the shipped blueprint still stores chunks in
+Mongo and cosine-ranks in-app until it is updated to pgvector.
 
 ## The full `needs:` vocabulary (the whole menu)
 
@@ -152,8 +156,8 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 | `kv: true` | Redis, no eviction | `KV_REDIS_URL` | Injects via `needs:` |
 | `queue: true` | Redis durable job queue | `QUEUE_REDIS_URL` | Injects via `needs:` |
 | `pubsub: true` | Redis pub/sub broadcast | `PUBSUB_REDIS_URL` | Injects via `needs:` |
-| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | **Injects via `needs:`** |
-| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | Injects via `needs:` |
+| `vector: pgvector` | pgvector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | **Injects via `needs:`** (#1545 shipped, verified live 2026-07-16) |
+| `object_storage: true` | GCS bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | **GATED (#1678)** - rejected at plug-time; use `disk` or a BYO bucket via secret |
 | `disk: true` | Persistent filesystem at `/data` | `DISK_PATH` | Injects via `needs:` |
 | `ai: true` | AI Gateway access | `AI_GATEWAY_URL` | Injects via `needs:` |
 | `type: cron` (service) | Scheduled job (`schedule`, `timezone`) | — | Service type, not a need |
@@ -162,8 +166,11 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 
 - **`needs:` injects the connection env vars today.** `needs: { database: true }`
   → `DATABASE_MONGODB_URL` (+legacy `MONGODB_URL`); `needs: { cache: true }` →
-  `CACHE_REDIS_URL` (+legacy `REDIS_URL`); `needs: { vector: pgvector }` →
-  `VECTOR_PGVECTOR_URL`; and so on across the nine needs. Author `needs:`.
+  `CACHE_REDIS_URL` (+legacy `REDIS_URL`); `needs: { queue: true }` →
+  `QUEUE_REDIS_URL`; and so on across the durable needs. Author `needs:`.
+  `vector: pgvector` → `VECTOR_PGVECTOR_URL` is now AVAILABLE (#1545 shipped,
+  verified live 2026-07-16). (**GATED, do NOT author yet:** `object_storage`
+  #1678 - rejected at plug-time, use `disk` or a BYO bucket via secret.)
   (*Historical note: the deployer once did not inject from `needs:` — platform
   bug #1527, now fixed and verified live.*)
 - **`requires:` is the deprecated v1 alias.** Don't author new yaml with it.
@@ -178,7 +185,8 @@ engine hint. Cron is NOT a need — it is a **service type** (`type: cron` with
 2. Adopt that template's `needs:`. Persistence → `database` (`app-with-data` or
    `api-service`); talks to an LLM → `ai: true` + `database` (`ai-app`); scheduled
    work → a `type: cron` service (Python/Node, supported on 0.14.0). (Held for now:
-   RAG's ideal `vector: pgvector`, #1545 — store embeddings in Mongo until it lands.)
+   RAG's ideal `vector: pgvector` now works - #1545 shipped; the shipped
+   templates still store embeddings in Mongo until they are updated.)
 3. One self-contained HTML page (`needs: none`, assets inlined) → publish as an
    inspiration with `grid_deploy` and the inline `html` param (instant, any
    edition). Separate files/folders/assets, or anything with a `needs:` →

package/src/corpus/cloudgrid-yaml.md

@@ -152,8 +152,8 @@ needs:
   kv: true                          # Redis, no eviction. Injects KV_REDIS_URL.
   queue: true                       # Redis for BullMQ etc. Injects QUEUE_REDIS_URL.
   pubsub: true                      # Redis pub/sub. Injects PUBSUB_REDIS_URL.
-  vector: pgvector                  # pgvector. Injects VECTOR_PGVECTOR_URL.
-  object_storage: true              # GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET.
+  vector: pgvector                  # pgvector. Injects VECTOR_PGVECTOR_URL. (#1545 shipped, verified live 2026-07-16.)
+  object_storage: true              # GATED (platform #1678) - rejected at plug-time; use disk: or a BYO bucket via secret.
   disk: true                        # Persistent filesystem at /data. Injects DISK_PATH.
   ai: true                          # AI Gateway access. Injects AI_GATEWAY_URL.
 
@@ -404,7 +404,7 @@ service type.**
 | `queue` | Durable job queue substrate | `QUEUE_REDIS_URL` | Redis |
 | `pubsub` | Broadcast pub/sub | `PUBSUB_REDIS_URL` | Redis |
 | `vector` | Vector embeddings DB | `VECTOR_PGVECTOR_URL` (+legacy `PGVECTOR_URL`) | pgvector (Postgres) |
-| `object_storage` | Object/blob bucket | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | GCS |
+| `object_storage` | Object/blob bucket - **GATED (#1678)**: rejected at plug-time, use `disk` or a BYO bucket via secret | `OBJECT_STORAGE_GCS_BUCKET`, `OBJECT_STORAGE_GCS_REGION` | GCS |
 | `disk` | Persistent filesystem mount | `DISK_PATH` | PVC |
 | `ai` | AI Gateway access | `AI_GATEWAY_URL` | CloudGrid AI Gateway |
 
@@ -424,10 +424,12 @@ needs:
   cache: true                                   # Platform Redis
   cache: { engine: external, secret: MY_REDIS } # Bring your own (same forms for kv/queue/pubsub)
 
+  # vector - AVAILABLE (#1545 shipped, verified live 2026-07-16):
   vector: true                                  # Platform default engine
   vector: pgvector                              # pgvector explicitly
   vector: { engine: pgvector, dim: 1536 }       # With dimension hint
 
+  # object_storage - GATED (#1678), rejected at plug-time; use disk: or a BYO bucket:
   object_storage: true                          # Default size (100MB)
   object_storage: { size: 10Gi }                # Custom size
 

package/src/corpus/examples/ai-app/index.md

@@ -32,8 +32,8 @@ services:
 needs:
   ai: true
   database: true
-# RAG over your own docs needs `needs: { vector: pgvector }` — not yet available
-# (platform issue #1545).
+# RAG over your own docs needs `needs: { vector: pgvector }` — available now,
+# #1545 shipped (verified live 2026-07-16). This example does not use it.
 ```
 
 ## services/web/package.json
@@ -234,4 +234,5 @@ export default function Chat({ initialHistory }) {
 - All app code lives under `services/web/`; the connection is read lazily inside
   `getDb`, never at module top level.
 - To answer over your own documents (RAG) you'd add `needs: { vector: pgvector }`
-  — not yet available (platform issue #1545).
+  — available now (#1545 shipped); this example ships without it, so you'd also
+  write the retrieval code.

package/src/corpus/templates/ai-app/README.md

@@ -87,9 +87,9 @@ services/web/app/api/chat/route.js    # POST: createClient().chat(...) -> persis
 - Change the `messages` collection / fields; add users, sessions, titles.
 - Restyle the chat UI in `layout.js` / `chat.js`.
 
-## RAG / retrieval (not yet)
+## RAG / retrieval (not included)
 
 To answer over **your own documents** (retrieval-augmented generation) you need a
-vector store — `needs: { vector: pgvector }`. That path is **not yet available**
-(platform issue #1545). Ship the plain chatbot now; add retrieval once the vector
-need is unblocked.
+vector store — `needs: { vector: pgvector }`. That need is **now available** —
+#1545 shipped (verified live 2026-07-16) — but this template is a plain chatbot:
+declare the need and build the retrieval code on top if you want RAG.

package/src/corpus/templates/ai-app/index.md

@@ -253,9 +253,9 @@ export default function Chat({ initialHistory }) {
 - Change the `messages` collection / fields; add users, sessions, titles.
 - Run `grid dev` to test locally, `grid plug` to deploy (async — poll to live).
 
-## RAG / retrieval (not yet)
+## RAG / retrieval (not included)
 
 To answer over **your own documents** (retrieval-augmented generation) you need a
-vector store — `needs: { vector: pgvector }`. That path is **not yet available**
-(platform issue #1545). Ship the plain chatbot now; add retrieval once the vector
-need is unblocked.
+vector store — `needs: { vector: pgvector }`. That need is **now available** —
+#1545 shipped (verified live 2026-07-16) — but this template is a plain chatbot:
+declare the need and build the retrieval code on top if you want RAG.

package/src/corpus/templates/ai-knowledge-base/AGENTS.md

@@ -13,13 +13,13 @@ them (with citations). Both the embedding and the answer step run through
 CloudGrid's **AI Gateway** (`@cloudgrid-io/ai`, injected via `needs: { ai: true }`).
 
 > **Vector-store status (read this first):** the ideal store for embeddings is
-> `needs: vector` (pgvector on Postgres, injecting `VECTOR_PGVECTOR_URL`), but it
-> is **PENDING platform issue #1545** and not yet provisioned. The **`ai` part
-> works today.** Until #1545 ships, store embeddings in **Mongo** (a `chunks`
-> collection with an `embedding: number[]` field) and compute cosine similarity in
-> the app. This blueprint's `cloudgrid.yaml` therefore declares
-> `needs: { ai: true, database: true }` and keeps `vector: pgvector` commented.
-> Section 7 describes the drop-in swap once #1545 lands.
+> `needs: vector` (pgvector on Postgres, injecting `VECTOR_PGVECTOR_URL`), and it
+> is **now available** — #1545 shipped (verified live 2026-07-16). This blueprint
+> still stores embeddings in **Mongo** (a `chunks` collection with an
+> `embedding: number[]` field) and computes cosine similarity in the app; its
+> `cloudgrid.yaml` declares `needs: { ai: true, database: true }` and keeps
+> `vector: pgvector` commented. Uncomment it only if you also build the retrieval
+> on pgvector — Section 7 describes the drop-in swap.
 
 ---
 
@@ -72,9 +72,9 @@ collections (`_id` is the Mongo ObjectId on every doc):
 - `embedding` (number[] — the embedding vector; e.g. length 1536)
 - `createdAt` (Date)
 
-Until issue #1545 lands, `chunks.embedding` lives in Mongo and you rank in the
-app (Section 3). When pgvector ships, the vectors move to Postgres and `chunks`
-keeps only the text + a foreign key (Section 7).
+As shipped, `chunks.embedding` lives in Mongo and you rank in the app
+(Section 3). If you swap to pgvector (available — #1545 shipped), the vectors
+move to Postgres and `chunks` keeps only the text + a foreign key (Section 7).
 
 ---
 
@@ -87,7 +87,7 @@ injected as env vars at `grid dev` (local) and at runtime (after `grid plug`):
 |------|----------------------------|---------------------|--------------|
 | MongoDB | `needs: { database: true }` | `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`) | `lib/db.js` |
 | AI Gateway | `needs: { ai: true }` | `AI_GATEWAY_URL` | `lib/ai.js` (via `@cloudgrid-io/ai`) |
-| Vector store (PENDING #1545) | `needs: { vector: pgvector }` | `VECTOR_PGVECTOR_URL` (+ legacy `PGVECTOR_URL`) | `lib/retrieve.js` — not yet available |
+| Vector store (available — #1545 shipped) | `needs: { vector: pgvector }` | `VECTOR_PGVECTOR_URL` (+ legacy `PGVECTOR_URL`) | `lib/retrieve.js` — not used by this blueprint (Section 7 for the swap) |
 | Auth key (optional) | `vault: { AUTH_PROVIDER_KEY: auth-provider-key }` | `AUTH_PROVIDER_KEY` | `lib/auth.js` |
 | Stripe key (optional) | `vault: { STRIPE_KEY: stripe-live-key }` | `STRIPE_KEY` | `lib/stripe.js` |
 
@@ -149,12 +149,12 @@ export async function chat(messages) {
 
 ### Retrieve (`lib/retrieve.js`)
 1. `embed(question)` -> query vector.
-2. Until pgvector (#1545): load candidate `chunks`, compute cosine similarity in
-   the app, keep the top-k (e.g. k=5). Keep it a pure, testable ranking function
-   so it swaps cleanly to a pgvector query later.
+2. As shipped (Mongo embeddings): load candidate `chunks`, compute cosine
+   similarity in the app, keep the top-k (e.g. k=5). Keep it a pure, testable
+   ranking function so it swaps cleanly to a pgvector query later.
 
 ```js
-// lib/retrieve.js — cosine top-k over Mongo-stored embeddings (pre-#1545)
+// lib/retrieve.js — cosine top-k over Mongo-stored embeddings (as shipped)
 import { getDb } from "./db.js";
 import { embed } from "./ai.js";
 const dot = (a, b) => a.reduce((s, x, i) => s + x * b[i], 0);
@@ -224,9 +224,9 @@ linked directory, so `init` first.
 
 ---
 
-## 7. When pgvector (#1545) lands — the swap
+## 7. The swap to pgvector (now available — #1545 shipped)
 
-Once `needs: vector` is available, migrate off the in-app cosine ranking:
+`needs: vector` is available; to migrate off the in-app cosine ranking:
 
 1. Uncomment `vector: pgvector` in `cloudgrid.yaml`'s `needs:` block (dim 1536 to
    match your embedding model). The grid then injects `VECTOR_PGVECTOR_URL` (+

package/src/corpus/templates/ai-knowledge-base/README.md

@@ -6,14 +6,14 @@ and answers questions grounded in the retrieved chunks (with citations) — the
 `app-with-data` runtime shape with a RAG loop layered on. Embeddings and answers
 run through CloudGrid's AI Gateway (`@cloudgrid-io/ai`, injected via
 `needs: { ai: true }` — works today); the ideal vector store `needs: vector`
-(pgvector) is **PENDING platform issue #1545**, so embeddings live in Mongo and
-similarity is computed in-app until it ships. Because RAG involves choices
+(pgvector) is **now available** — #1545 shipped (verified live 2026-07-16) — but
+this blueprint stores embeddings in Mongo and computes similarity in-app. Because RAG involves choices
 (chunking, embedding model, retrieval), this template ships the **structure and
 `cloudgrid.yaml`, not finished app code** — adapt it and build.
 
 > **This is a blueprint: structure + cloudgrid.yaml, adapt and build.** Read
 > `AGENTS.md` for the file tree, Mongo collections, CloudGrid injection table
-> (needs + AI Gateway + the pgvector #1545 note), the RAG loop, optional
+> (needs + AI Gateway + the pgvector note), the RAG loop, optional
 > auth/payments wiring, and the deploy flow — then generate the app under
 > `services/web/` and `grid plug` it (runtime, local edition, async — poll to a
 > live URL).
@@ -22,7 +22,8 @@ similarity is computed in-app until it ships. Because RAG involves choices
 
 - `cloudgrid.yaml` — active fields: `name`, `services.web` (nextjs, `/`), and
   `needs: { ai: true, database: true }`. `vector: pgvector` is present but
-  commented (PENDING #1545); the optional `vault:` block (auth/payments) is
+  commented (available now, #1545 shipped — this blueprint uses Mongo
+  embeddings); the optional `vault:` block (auth/payments) is
   commented too.
 - `AGENTS.md` — the structure guide (read this first).
 - `index.md` — the fetch-bundle summary + cloudgrid.yaml.

package/src/corpus/templates/ai-knowledge-base/cloudgrid.yaml

@@ -89,10 +89,11 @@ needs:
 #   pubsub: true
 #   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
 #   #   true | pgvector | { engine: pgvector, dim: 1536 }
-#   # NOTE: `needs: vector` (pgvector) is the intended store for RAG embeddings but
-#   # is PENDING platform issue #1545 — not yet provisioned. Until it ships, store
-#   # embeddings in Mongo (a `chunks` collection with an `embedding: number[]` field)
-#   # and do cosine similarity in the app. Flip this on once #1545 lands.
+#   # NOTE: `needs: vector` (pgvector) is the intended store for RAG embeddings and
+#   # is available now (#1545 shipped). This template still stores embeddings in
+#   # Mongo (a `chunks` collection with an `embedding: number[]` field) and does
+#   # cosine similarity in the app — uncomment `vector: pgvector` only if you also
+#   # switch the retrieval code to pgvector.
 #   vector: pgvector
 #   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
 #   #   true | { size: 10Gi }

package/src/corpus/templates/ai-knowledge-base/index.md

@@ -13,7 +13,7 @@ the app following it.
 
 - **Structure guide:** `grid_get_template("template", "ai-knowledge-base")` → read
   **`AGENTS.md`** (file tree, Mongo collections, CloudGrid injection table, the
-  RAG loop, the pgvector #1545 note, optional auth/payments, deploy steps).
+  RAG loop, the pgvector note, optional auth/payments, deploy steps).
 
 **Key rules (same runtime discipline as `app-with-data`):**
 
@@ -29,10 +29,11 @@ the app following it.
    model's parametric memory alone. Keep chunking/retrieval as pure functions.
 
 **Vector store:** `needs: vector` (pgvector, injecting `VECTOR_PGVECTOR_URL`) is
-the intended embedding store but is **PENDING platform issue #1545**. The `ai`
-part works today — until #1545 ships, store embeddings in a Mongo `chunks`
-collection and rank by cosine similarity in the app; swap to a pgvector
-ORDER-BY-distance query when it lands (see `AGENTS.md` §7).
+the intended embedding store and is **now available** — #1545 shipped (verified
+live 2026-07-16). This blueprint still stores embeddings in a Mongo `chunks`
+collection and ranks by cosine similarity in the app; to use pgvector instead,
+uncomment the need and swap to a pgvector ORDER-BY-distance query (see
+`AGENTS.md` §7).
 
 Runtime app → **local edition** only (async build, poll to a live URL).
 
@@ -42,7 +43,8 @@ Runtime app → **local edition** only (async build, poll to a live URL).
 # 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. `vector: pgvector` is present but kept
-# COMMENTED (PENDING #1545).
+# COMMENTED (available now — #1545 shipped — but this blueprint uses Mongo
+# embeddings; uncomment only if you also build the retrieval on pgvector).
 name: my-knowledge-base
 services:
   web:
@@ -56,15 +58,16 @@ needs:
 > **Capability:** `needs: { database: true }` → the deployer provisions Mongo and
 > injects `DATABASE_MONGODB_URL` (plus legacy `MONGODB_URL`). `needs: { ai: true }`
 > → injects `AI_GATEWAY_URL`; `@cloudgrid-io/ai` routes embeddings + chat through
-> it with no API key to manage. `needs: { vector: pgvector }` (would inject
-> `VECTOR_PGVECTOR_URL`) is PENDING #1545. See the capability-map for the full
+> it with no API key to manage. `needs: { vector: pgvector }` (injects
+> `VECTOR_PGVECTOR_URL`) is available (#1545 shipped) but not declared here —
+> this blueprint uses Mongo embeddings. See the capability-map for the full
 > injection table.
 
 ## Structure guide
 
 The real content of this blueprint is **`AGENTS.md`** — fetch the template bundle
 and read it. It covers the `services/web/` file tree, the `documents` / `chunks`
-collections, the CloudGrid injection table (needs + AI Gateway + the #1545 note),
+collections, the CloudGrid injection table (needs + AI Gateway + the pgvector note),
 the ingest → retrieve → answer RAG loop with lazy `lib/db.js` / `lib/ai.js` /
 `lib/retrieve.js`, optional auth/payments via `vault:`, and the
 `grid init → fill → grid plug → poll` deploy flow.
@@ -75,7 +78,8 @@ the ingest → retrieve → answer RAG loop with lazy `lib/db.js` / `lib/ai.js`
   `lib/ai.js`; tune retrieval `k`.
 - Add auth (uncomment `vault: { AUTH_PROVIDER_KEY }`) to gate the KB, or payments
   (`vault: { STRIPE_KEY }`) to charge for access.
-- When pgvector #1545 lands, uncomment `needs: { vector: pgvector }` and swap
-  `lib/retrieve.js` to an ORDER-BY-distance query (`AGENTS.md` §7).
+- To move to pgvector (now available — #1545 shipped), uncomment
+  `needs: { vector: pgvector }` and swap `lib/retrieve.js` to an
+  ORDER-BY-distance query (`AGENTS.md` §7).
 - Build under `services/web/`, then `grid dev` (local) / `grid plug` (async — poll
   to a live URL).

package/src/corpus/templates/semantic-search/AGENTS.md

@@ -77,12 +77,12 @@ os.environ.get("MONGODB_URL")` inside `get_client()`, never at module top level.
 `requires:` together (the validator rejects the combination).
 
 **No `needs: vector`.** The ideal embedding store is pgvector
-(`needs: { vector: pgvector }` → `VECTOR_PGVECTOR_URL`), but the runtime
-role-grant is **blocked on platform issue #1545**. Until it lands, embeddings live
-in the Mongo `chunks.embedding` float array and are cosine-ranked in-app
-(`search.py::_cosine`). When #1545 ships, move the vectors to pgvector and replace
-the in-app cosine block with an `ORDER BY embedding <=> $q LIMIT k` query — the
-rest of the pipeline is unchanged.
+(`needs: { vector: pgvector }` → `VECTOR_PGVECTOR_URL`), and it is **now
+available** — #1545 shipped (verified live 2026-07-16). This template still keeps
+embeddings in the Mongo `chunks.embedding` float array and cosine-ranks in-app
+(`search.py::_cosine`). To swap, move the vectors to pgvector and replace the
+in-app cosine block with an `ORDER BY embedding <=> $q LIMIT k` query — the rest
+of the pipeline is unchanged.
 
 ---
 
@@ -155,9 +155,9 @@ to store the same way. Non-secret public config can also go via `grid env`.
    source or embeddings are unconfigured. `GET /backend/status` reports capability
    **booleans** (`source_configured`, `embeddings_configured`, …), never secret
    values.
-4. **No `needs: vector`.** `needs:` is `database` only — pgvector's runtime
-   role-grant is still blocked (#1545). (The scheduled cron refresh IS active — see
-   §8.)
+4. **No `needs: vector`.** `needs:` is `database` only — the pgvector need is
+   available (#1545 shipped), but this template's code uses Mongo embeddings (§3
+   for the swap). (The scheduled cron refresh IS active — see §8.)
 
 ---
 

package/src/corpus/templates/semantic-search/README.md

@@ -17,9 +17,10 @@ aggregated to the document level with a best-passage highlight.
 | `backend` | `python` (FastAPI) | `/backend` | `services/backend/src/main.py` |
 
 `needs: { database: true }` → CloudGrid injects `DATABASE_MONGODB_URL` (fallback
-`MONGODB_URL`). **No `needs: vector`** — pgvector runtime role-grant is blocked
-(platform #1545), so embeddings live in the Mongo `chunks` collection and are
-cosine-ranked in-app. Refresh runs two ways: the manager "Refresh now" endpoint
+`MONGODB_URL`). **No `needs: vector`** — the need is available now (#1545
+shipped, verified live 2026-07-16), but this template stores embeddings in the
+Mongo `chunks` collection and cosine-ranks in-app; declare `vector: pgvector`
+only if you also switch the code to pgvector. Refresh runs two ways: the manager "Refresh now" endpoint
 (on demand) and an active Python `type: cron` job (`services/refresh/`, daily 03:00
 UTC) — both call the same `indexing.run_sync` (see AGENTS.md §8).
 

package/src/corpus/templates/semantic-search/cloudgrid.yaml

@@ -89,9 +89,9 @@ name: semantic-search
 #   pubsub: true
 #   # vector — pgvector on Postgres. Injects VECTOR_PGVECTOR_URL (+ PGVECTOR_URL).
 #   #   true | pgvector | { engine: pgvector, dim: 1536 }
-#   #   NOT USED HERE — pgvector runtime role-grant is blocked (platform #1545).
-#   #   This template stores embeddings in the Mongo `chunks` collection and
-#   #   cosine-ranks in-app instead. Swap to `vector: pgvector` once #1545 lands.
+#   #   NOT USED HERE — available now (#1545 shipped). This template stores
+#   #   embeddings in the Mongo `chunks` collection and cosine-ranks in-app.
+#   #   Uncomment `vector: pgvector` only if you also switch the code to pgvector.
 #   vector: pgvector
 #   # object_storage — GCS bucket. Injects OBJECT_STORAGE_GCS_BUCKET, _GCS_REGION.
 #   #   true | { size: 10Gi }
@@ -204,8 +204,9 @@ services:
     timezone: UTC
     run: job                    # batch job — runs services/refresh/src/main.py once
 # CloudGrid managed Mongo → injects DATABASE_MONGODB_URL (+ legacy MONGODB_URL).
-# NO `needs: vector` — pgvector runtime role-grant is still blocked (#1545);
-# embeddings live in the Mongo `chunks` collection and are cosine-ranked in-app.
+# NO `needs: vector` — available now (#1545 shipped), but this template stores
+# embeddings in the Mongo `chunks` collection and cosine-ranks in-app;
+# uncomment `vector: pgvector` only if you also switch the code to pgvector.
 needs:
   database: true
 

package/src/corpus/templates/semantic-search/index.md

@@ -24,9 +24,11 @@ level with a best-passage highlight.
    `$text` index exists at boot — `$text` returns `[]` on an empty catalog rather
    than raising `IndexNotFound` (a 500). The `$text` query is also guarded in
    `except OperationFailure` as belt-and-suspenders.
-5. **No `needs: vector`** — pgvector runtime role-grant is blocked (#1545), so
-   embeddings live in the Mongo `chunks` collection (a float array) and are
-   cosine-ranked in-app. **The refresh cron IS active** — a Python `type: cron`,
+5. **No `needs: vector`** — the need is available now (#1545 shipped, verified
+   live 2026-07-16), but this
+   template stores embeddings in the Mongo `chunks` collection (a float array)
+   and cosine-ranks in-app; declare `vector: pgvector` only if you also switch
+   the code to pgvector. **The refresh cron IS active** — a Python `type: cron`,
    `run: job` service (`services/refresh/`) reindexes daily at 03:00 UTC, and the
    manager "Refresh now" endpoint reindexes on demand; both call the same
    `indexing.run_sync` (the cron vendors the backend `app/` modules — see AGENTS.md §8).
@@ -86,7 +88,8 @@ needs:
 
 > **Capability:** the need is `database: true` — the deployer provisions Mongo and
 > injects `DATABASE_MONGODB_URL` (+ legacy `MONGODB_URL`). NO `needs: vector`
-> (#1545). Three services: `web` (static), `backend` (python), `refresh` (cron).
+> (available, #1545 shipped — this template uses Mongo embeddings). Three
+> services: `web` (static), `backend` (python), `refresh` (cron).
 > `requires:` is the deprecated v1 alias — don't mix it with `needs:`.
 
 ## Configure + deploy

package/src/corpus/templates/simple-semantic-search/README.md

@@ -0,0 +1,20 @@
+# simple-semantic-search
+
+Semantic search over a document in one node service, on the CloudGrid managed
+vector substrate. `needs: { vector: pgvector }` provisions pgvector and injects
+`VECTOR_PGVECTOR_URL`; `needs: { ai: true }` gives embeddings through
+`@cloudgrid-io/runtime` with no API key. On startup the service embeds
+`document.txt` (one vector per paragraph) into a `chunks` table sized from a
+probe embedding, then `POST /search` embeds the query and returns the nearest
+passages by cosine distance. `/health` returns 503 until the seed finishes, so
+the platform holds the pod out of traffic until search works.
+
+Proven by a real end-to-end deploy (live in under 3 minutes, 2026-07-16).
+
+- Deploy: `grid init app <name> --here`, then `grid plug`.
+- The CLI writes `.cloudgrid/link.json` (folder ↔ entity binding) — never
+  hand-author it; `rm -rf .cloudgrid` + re-init to take a copied folder as your
+  own app.
+- Replace `services/web/src/document.txt` with the content to index.
+- For a multi-service search portfolio (upload UI + refresh cron), use the
+  `semantic-search` blueprint instead.