@cloudgrid-io/mcp 0.20.6 → 0.20.8

package/README.md

@@ -15,10 +15,12 @@ drop, claim, and login tools.
 
 ## CLI compatibility
 
-MCP 0.8.0 is tested against CLI 0.12. The lazy-npx fallback pins
-`@cloudgrid-io/cli@~0.12` so a future CLI major with renamed verbs cannot
-silently break a released MCP. A CI drift guard (`npm run test:drift-guard`)
-asserts every wrapped verb exists in the CLI help.
+The MCP uses an installed CLI only when it meets the platform floor
+(`MIN_CLI_VERSION`, currently 0.15.2 - kept in lockstep with the API's live
+`cli_compat` floor, which rejects older CLIs with HTTP 426). Below the floor it
+skips the local/global CLI and lazily fetches `@cloudgrid-io/cli@latest` via
+npx instead. A CI drift guard (`npm run test:drift-guard`) asserts every
+wrapped verb exists in the CLI help.
 
 ### `GRID_AUTH_STALE` is out of scope
 
@@ -71,52 +73,59 @@ posted). `CLOUDGRID_QA_IDLE_MS` overrides the abandoned-idle window (default
 
 | Tool | Wraps | Notes |
 |---|---|---|
-| `grid_plug` | `POST /api/v2/plug` | The unified create/re-plug verb: create a new entity, or update the SAME entity in place with `target_entity_id` (same URL). Source via local `path` (local edition) or inline `artifact_files` (both). |
-| `grid_drop` | `POST /api/v2/plug` | Artifact drop. Anonymous, or owned if signed in. Re-drops in a session update the same drop in place; anonymous drops return an `entity_id` + `owner_token` re-plug/claim handle. |
-| `grid_claim` | `POST /api/v2/entities/:id/pickup` | Claim an anonymous drop into the signed-in account (the claim token IS the drop's owner token). Direct API. |
-| `grid_fork` | `POST /api/v2/runtimes/:id/fork` | Start a new entity from an existing runtime (lineage recorded). Needs sign-in. |
-| `grid_download` | `GET /api/v2/runtimes/:id/source` | Signed 15-minute source-bundle URLs. Needs sign-in. |
-| `grid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. Direct API. |
+| `grid_deploy` | `POST /api/v2/plug` | THE deploy/publish verb (CloudGrid calls it "plug"): create a new entity, or update the SAME entity in place with `target_entity_id` (same URL). Source via inline `html` (single page), local `path` (local edition), or inline `artifact_files` (both). Anonymous drops return an `entity_id` + `owner_token` re-plug/claim handle. |
+| `grid_claim_anonymous_deploy` | `POST /api/v2/entities/:id/pickup` | Claim an anonymous drop into the signed-in account (the claim token IS the drop's owner token). |
+| `grid_copy_app` | `POST /api/v2/runtimes/:id/fork` | Start a new entity from an existing runtime (lineage recorded). Needs sign-in. |
+| `grid_download_source` | `GET /api/v2/runtimes/:id/source` | Signed 15-minute source-bundle URLs. Needs sign-in. |
+| `grid_get_app_source` | `GET /api/v2/.../source` | Fetch a deployed entity's source (resolves entity_id from a URL). Read-only. |
+| `grid_login` | `GET /auth/login` | Start a CLI-free sign-in; returns a URL to open. |
 | `grid_login_status` | `GET /auth/status` | Finish the sign-in; saves the token to the shared CLI credentials. |
-| `grid_visibility` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. Direct API; also in the web edition. |
+| `grid_set_sharing` | `PATCH /api/v2/inspirations/<id>` | Change who can see a drop (private, space, authenticated, org, link). Needs sign-in. |
+| `grid_list_grids` | `GET /api/v2/orgs` | List the caller's grids. Read-only. |
+| `grid_start` | corpus | Orientation: the playbook + workflow index + live context. Call FIRST. Read-only. |
+| `grid_get_template` | corpus | Fetch a workflow / template / example / doc from the bundled corpus. Read-only. (`grid_fetch` is a kept deprecated alias.) |
+| `grid_note` / `grid_report` / `grid_feedback` | API | Session notes, consent-gated error reports, feedback feed. |
 
-`grid_drop`, `grid_claim`, `grid_visibility`, and the two
-`grid_login` tools do not wrap the CLI -- they call the API directly, so they
-also work in the web edition where no CLI exists. `grid_login` writes the same
-`~/.cloudgrid/credentials` the CLI uses, so the two share one identity.
+The direct-API tools call the platform without the CLI, so they also work in
+the web edition. `grid_login` writes the same `~/.cloudgrid/credentials` the
+CLI uses, so the two share one identity.
 
 ### CLI-wrapping tools (local edition only)
 
 | Tool | Wraps | Notes |
 |---|---|---|
-| `grid_init` | `grid init` | Register an app or agent; optionally seed a web service. |
-| `grid_logs` | `grid logs` | Snapshot of recent logs. Does not stream. Read-only. |
+| `grid_create_project` | `grid init` | Register an app or agent; optionally seed a web service. |
+| `grid_view_logs` | `grid logs` | Snapshot of recent logs. Does not stream. Read-only. (`grid_logs` is a kept deprecated alias.) |
 | `grid_share` | `grid visibility set` | Set visibility, default link. |
-| `grid_feedback` | `grid feedback list` | Read the org feedback feed. Read-only. |
-| `grid_whoami` | `grid whoami` | Show the signed-in user and active org. Read-only. |
-| `grid_use` | `grid use` | Switch the active org. |
+| `grid_whoami` | `grid whoami` | Show the signed-in user and active grid. Read-only. |
+| `grid_switch_grid` | `grid use` | Switch the active grid. |
 | `grid_logout` | `grid logout` | Sign out and clear local credentials. Destructive. |
-| `grid_status` | `grid status` | Org dashboard or entity detail. Read-only. |
+| `grid_status` | `grid status` | Grid dashboard or entity detail. Read-only. |
 | `grid_info` | `grid info` | Entity metadata. Read-only. |
 | `grid_get` | `grid get grids\|entities\|spaces` | List grids, entities, or spaces. Read-only. |
 | `grid_describe_grid` | `grid describe grid <slug>` | Grid detail. Read-only. |
-| `grid_pickup` | `grid pickup <name>` | Download an entity's source and bind the folder. |
+| `grid_edit_existing_app` | `grid pickup <name>` | Download an entity's source and bind the folder. |
 | `grid_rename` | `grid rename` | Rename an entity's display name. |
-| `grid_unplug` | `grid unplug` | Take an entity off the grid. Destructive; requires confirm. |
+| `grid_take_offline` | `grid unplug` | Take an entity off the grid. Destructive; requires confirm. |
 | `grid_delete` | `grid delete entity` | Archive an inspiration. Destructive; requires confirm. |
-| `grid_rollback` | `grid rollback` | Rollback to a previous version. |
-| `grid_versions` | `grid versions` | List published versions. Read-only. |
-| `grid_env` | `grid env` | Get, set, or list environment variables. |
-| `grid_secrets` | `grid secrets` | Set or list secret names. Never returns secret values. |
+| `grid_rollback_deploy` | `grid rollback` | Rollback to a previous version. |
+| `grid_list_versions` | `grid versions` | List published versions. Read-only. |
+| `grid_set_env` | `grid env` | Get, set, or list environment variables. |
+| `grid_set_secret` | `grid secrets` | Set or list secret names. Never returns secret values. |
 | `grid_scaffold` | `grid scaffold` | Generate starter files. |
-| `grid_doctor` | `grid doctor` | Run local diagnostics. Read-only. |
-| `grid_open` | `grid open --print` | Return the public URL. Does not open a browser. Read-only. |
+| `grid_diagnose` | `grid doctor` | Run local diagnostics. Read-only. |
+| `grid_get_url` | `grid open --print` | Return the public URL. Does not open a browser. Read-only. |
 
-`grid_share` and `grid_visibility` overlap on purpose: `grid_share`
-wraps the CLI and defaults to `link`; `grid_visibility` is direct API, takes an
+`grid_share` and `grid_set_sharing` overlap on purpose: `grid_share`
+wraps the CLI and defaults to `link`; `grid_set_sharing` is direct API, takes an
 explicit scope, and defaults its target to the session's last drop -- it is the one
 the web edition gets.
 
+37 tool names are advertised in total: 35 canonical + 2 kept deprecated
+aliases (`grid_fetch`, `grid_logs`). The 0.20.8 alias diet dropped the other 16
+legacy aliases. Per-tool internals (signature, sketch, behavior):
+[docs/TOOL-INTERNALS.md](docs/TOOL-INTERNALS.md).
+
 All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`,
 `openWorldHint`) for clients that support them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudgrid-io/mcp",
-  "version": "0.20.6",
+  "version": "0.20.8",
   "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": {
@@ -27,6 +27,7 @@
     "test:content": "node test/content-handling.test.mjs",
     "test:self-healing": "node test/self-healing.test.mjs",
     "test:grid-picker": "node test/grid-picker.test.mjs",
+    "test:plug-output-schema": "node test/plug-output-schema.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",

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/examples/docs-app/index.md

@@ -0,0 +1,113 @@
+# Example: docs-app — "Widgets SDK docs"
+
+A filled reference imitating the `docs-app` template: a multi-page documentation
+site for a fictional "Widgets SDK", built with [Astro Starlight](https://starlight.astro.build).
+It has sidebar navigation, client-side full-text search, and agent-readable
+`llms.txt` / `llms-full.txt` generated on every build.
+
+`docs-app` is the buildable sibling of `docs-site`. Use `docs-app` when the docs
+are more than one page and you will keep editing them; use `docs-site` for a
+quick single page baked into one HTML file (instant, works on the hosted MCP).
+
+**The proven rules for a docs-app:** (1) it is served at the entity **root**, so
+there is **no `base`** in `astro.config.mjs`; (2) `cloudgrid.yaml` declares a
+single `static` service with **`source: { path: . }`** (the project is at the
+folder root, not under `services/site/`) plus a **`build:` block** — the platform
+runs `npm run build` for you; (3) it is a multi-file **build**, so it deploys
+**async** (poll to the live URL) and needs the **local edition** (the hosted MCP
+cannot build it); (4) `llms.txt` / `llms-full.txt` are generated automatically at
+the site root by the `starlight-llms-txt` plugin — no extra work.
+
+## cloudgrid.yaml
+
+```yaml
+# Static site with a build step, served at the entity root. source.path: .
+# points the build at the project root; without it the build looks for
+# services/site/ and fails. No needs: — a docs site has no infrastructure.
+name: widgets-sdk-docs
+services:
+  site:
+    type: static
+    path: /
+    node_version: "22"
+    source:
+      path: .
+    build:
+      command: "npm run build"
+      output: "dist"
+```
+
+## package.json
+
+```json
+{
+  "name": "widgets-sdk-docs",
+  "type": "module",
+  "version": "0.1.0",
+  "scripts": { "dev": "astro dev", "build": "astro build", "preview": "astro preview" },
+  "dependencies": {
+    "@astrojs/starlight": "^0.41.3",
+    "astro": "^7.0.2",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": { "starlight-llms-txt": "^0.11.0" }
+}
+```
+
+## astro.config.mjs
+
+```js
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import starlightLlmsTxt from 'starlight-llms-txt';
+
+export default defineConfig({
+  site: 'https://example.com',
+  integrations: [
+    starlight({
+      plugins: [
+        starlightLlmsTxt({
+          projectName: 'Widgets SDK',
+          description: 'Build, style, and ship widgets. The official Widgets SDK docs.',
+        }),
+      ],
+      title: 'Widgets SDK',
+      sidebar: [
+        { label: 'Start here', items: [
+          { label: 'Introduction', slug: 'index' },
+          { label: 'Install', slug: 'guides/install' },
+        ] },
+        { label: 'Reference', items: [{ label: 'Widget API', slug: 'reference/widget-api' }] },
+      ],
+    }),
+  ],
+});
+```
+
+## src/content/docs/guides/install.md
+
+```md
+---
+title: Install
+description: Add the Widgets SDK to your project.
+---
+
+    npm install @widgets/sdk
+
+Then import a widget and render it:
+
+    import { Button } from '@widgets/sdk';
+```
+
+## Build + deploy
+
+```sh
+npm install
+npm run build      # local check; the platform also builds on plug
+grid plug          # async build → poll to the live URL
+```
+
+The live site serves at the entity root — pages at `/`, `/guides/install/`,
+`/reference/widget-api/`, and the agent docs at `/llms.txt` and `/llms-full.txt`.
+On a new deploy, ask the user what visibility they want and set it with
+`grid visibility`.

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).