@cloudgrid-io/mcp 0.20.6 → 0.20.7

package/src/corpus/templates/simple-semantic-search/services/web/src/index.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// Simple semantic search — single-service reference for the CloudGrid managed vector
+// substrate (pgvector) + the platform embeddings endpoint.
+//
+// On startup it embeds the bundled document (one vector per passage)
+// via runtime.ai.embeddings and stores the vectors in the entity's own pgvector
+// schema. POST /search embeds the query and returns the nearest passages by
+// cosine distance. No keyword matching — relevance comes entirely from the
+// embeddings.
+
+const fs = require('fs');
+const path = require('path');
+const express = require('express');
+const { Client } = require('pg');
+const { runtime } = require('@cloudgrid-io/runtime');
+
+const PORT = process.env.PORT || 8080;
+const PGVECTOR_URL = process.env.VECTOR_PGVECTOR_URL || process.env.PGVECTOR_URL;
+
+// One passage per non-empty paragraph in the article.
+function loadChunks() {
+  const raw = fs.readFileSync(path.join(__dirname, 'document.txt'), 'utf8');
+  return raw
+    .split(/\n\s*\n/)
+    .map((p) => p.replace(/\s+/g, ' ').trim())
+    .filter((p) => p.length > 0);
+}
+
+// Format a JS number[] as a pgvector literal: '[0.1,0.2,...]'.
+function toVectorLiteral(values) {
+  return '[' + values.join(',') + ']';
+}
+
+let seeded = false;
+let seedError = null;
+let chunkCount = 0;
+let embeddingDim = 0;
+
+async function connect() {
+  if (!PGVECTOR_URL) {
+    throw new Error('VECTOR_PGVECTOR_URL is not set — the vector need did not provision');
+  }
+  const client = new Client({ connectionString: PGVECTOR_URL });
+  await client.connect();
+  return client;
+}
+
+// Idempotent seed: ensure the extension + table exist, sized to the embedding
+// model's actual output length, and populate the table once.
+async function seed() {
+  const chunks = loadChunks();
+  const client = await connect();
+  try {
+    await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+
+    // Size the column to the model's real output length — embed a probe first.
+    const probe = await runtime.ai.embeddings({ text: chunks[0] });
+    embeddingDim = probe.dim;
+    console.log(`[seed] embedding model=${probe.model} dim=${embeddingDim}`);
+
+    await client.query(
+      `CREATE TABLE IF NOT EXISTS chunks (
+         id integer PRIMARY KEY,
+         chunk text NOT NULL,
+         embedding vector(${embeddingDim}) NOT NULL
+       )`,
+    );
+
+    const { rows } = await client.query('SELECT count(*)::int AS n FROM chunks');
+    const existing = rows[0].n;
+    if (existing >= chunks.length) {
+      chunkCount = existing;
+      console.log(`[seed] already populated with ${existing} chunks — skipping embed`);
+      seeded = true;
+      return;
+    }
+
+    console.log(`[seed] embedding ${chunks.length} chunks`);
+    // Batch-embed every passage in input order.
+    const vectors = await runtime.ai.embeddings({ text: chunks });
+    for (let i = 0; i < chunks.length; i++) {
+      const literal = toVectorLiteral(vectors[i].values);
+      await client.query(
+        `INSERT INTO chunks (id, chunk, embedding)
+         VALUES ($1, $2, $3::vector)
+         ON CONFLICT (id) DO UPDATE SET chunk = EXCLUDED.chunk, embedding = EXCLUDED.embedding`,
+        [i, chunks[i], literal],
+      );
+      console.log(`[seed] inserted chunk ${i + 1}/${chunks.length}`);
+    }
+    chunkCount = chunks.length;
+    seeded = true;
+    console.log(`[seed] done — ${chunkCount} chunks stored`);
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+async function search(query, limit = 5) {
+  const q = await runtime.ai.embeddings({ text: query });
+  const literal = toVectorLiteral(q.values);
+  const client = await connect();
+  try {
+    const { rows } = await client.query(
+      `SELECT chunk, 1 - (embedding <=> $1::vector) AS score
+         FROM chunks
+         ORDER BY embedding <=> $1::vector
+         LIMIT $2`,
+      [literal, limit],
+    );
+    return rows.map((r) => ({ chunk: r.chunk, score: Number(r.score) }));
+  } finally {
+    await client.end().catch(() => {});
+  }
+}
+
+const app = express();
+app.use(express.json());
+
+app.get('/health', (_req, res) => {
+  // Return not-ready until the seed completes so the platform's readiness probe
+  // holds the pod out of traffic until search actually works.
+  if (seedError) return res.status(500).json({ status: 'seed_failed', error: seedError });
+  if (!seeded) return res.status(503).json({ status: 'seeding' });
+  res.json({ status: 'ok', chunks: chunkCount, dim: embeddingDim });
+});
+
+app.post('/search', async (req, res) => {
+  const query = req.body && typeof req.body.query === 'string' ? req.body.query.trim() : '';
+  if (!query) return res.status(400).json({ error: 'Provide a query string.' });
+  if (!seeded) return res.status(503).json({ error: 'The index is still loading. Try again shortly.' });
+  try {
+    const results = await search(query);
+    res.json({ query, results });
+  } catch (err) {
+    console.error('[search] failed', err);
+    res.status(500).json({ error: 'Search failed.' });
+  }
+});
+
+app.get('/', (_req, res) => {
+  res.type('html').send(PAGE);
+});
+
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Semantic search</title>
+<style>
+  :root { color-scheme: light; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: #1a1a1a; background: #fafafa; }
+  main { max-width: 680px; margin: 0 auto; padding: 48px 20px 80px; }
+  h1 { font-size: 24px; margin: 0 0 4px; }
+  p.lede { color: #555; margin: 0 0 28px; }
+  form { display: flex; gap: 8px; margin-bottom: 24px; }
+  input { flex: 1; padding: 12px 14px; font-size: 16px; border: 1px solid #ccc; border-radius: 8px; background: #fff; }
+  input:focus { outline: none; border-color: #888; }
+  button { padding: 12px 20px; font-size: 16px; border: none; border-radius: 8px; background: #1a1a1a; color: #fff; cursor: pointer; }
+  button:disabled { opacity: .5; cursor: default; }
+  .result { padding: 16px 0; border-top: 1px solid #eee; }
+  .result .score { font-size: 13px; color: #888; margin-bottom: 4px; font-variant-numeric: tabular-nums; }
+  .result .text { margin: 0; }
+  .status { color: #888; font-size: 14px; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Semantic search</h1>
+  <p class="lede">Search the document by meaning. Results are ranked by embedding similarity, not keyword match.</p>
+  <form id="f">
+    <input id="q" type="text" placeholder="Ask a question about the document" autocomplete="off" />
+    <button id="b" type="submit">Search</button>
+  </form>
+  <div id="out"></div>
+</main>
+<script>
+  var f = document.getElementById('f');
+  var q = document.getElementById('q');
+  var b = document.getElementById('b');
+  var out = document.getElementById('out');
+  f.addEventListener('submit', function (e) {
+    e.preventDefault();
+    var query = q.value.trim();
+    if (!query) return;
+    b.disabled = true;
+    out.innerHTML = '<p class="status">Searching.</p>';
+    fetch('/search', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query: query }),
+    })
+      .then(function (r) { return r.json(); })
+      .then(function (data) {
+        b.disabled = false;
+        if (!data.results || !data.results.length) {
+          out.innerHTML = '<p class="status">No results.</p>';
+          return;
+        }
+        out.innerHTML = data.results.map(function (r) {
+          return '<div class="result"><div class="score">score ' + r.score.toFixed(3) +
+            '</div><p class="text">' + r.chunk.replace(/</g, '&lt;') + '</p></div>';
+        }).join('');
+      })
+      .catch(function () {
+        b.disabled = false;
+        out.innerHTML = '<p class="status">Search failed. Try again.</p>';
+      });
+  });
+</script>
+</body>
+</html>`;
+
+app.listen(PORT, () => {
+  console.log(`simple-semantic-search listening on ${PORT}`);
+  // Seed in the background so the HTTP server binds immediately (the platform's
+  // startup probe wants the port open). /health reports seeding progress.
+  seed().catch((err) => {
+    seedError = String((err && err.message) || err);
+    console.error('[seed] FAILED', err);
+  });
+});

package/src/corpus/workflows/ai-app.md

@@ -4,7 +4,7 @@ when: chatbot, AI assistant, Q&A bot, conversational app, support bot, ask-me-an
 needs: ai, database
 deploy: runtime
 editions: local
-capabilities_note: AI chatbot — needs ai (the grid AI gateway) + a database (Mongo) for chat history. Next.js App Router app. Uses @cloudgrid-io/ai createClient().chat() with zero-config in-grid identity auth (no API key). Runtime app, async build, local edition only. Declare `needs: { ai: true, database: true }`. (RAG over your own docs needs `needs: { vector: pgvector }` — not yet available, platform issue #1545.)
+capabilities_note: AI chatbot — needs ai (the grid AI gateway) + a database (Mongo) for chat history. Next.js App Router app. Uses @cloudgrid-io/ai createClient().chat() with zero-config in-grid identity auth (no API key). Runtime app, async build, local edition only. Declare `needs: { ai: true, database: true }`. (RAG over your own docs needs `needs: { vector: pgvector }` — now available, #1545 shipped (verified live 2026-07-16); this template ships the plain chatbot without it.)
 summary: Build an AI chatbot on the grid — a Next.js app that calls @cloudgrid-io/ai createClient().chat({messages}) (zero-config in-grid auth, no key) and persists the conversation to grid-shared Mongo. Edition-gate first, scaffold, put the app under services/web/, declare needs:{ai:true,database:true}, read DATABASE_MONGODB_URL lazily, deploy async, poll to a live URL.
 ---
 
@@ -66,7 +66,7 @@ ai: true, database: true }`).
      ai: true
      database: true
    # For retrieval-augmented (RAG) over your own docs, add `needs: { vector:
-   # pgvector }` once platform issue #1545 ships — not yet available.
+   # pgvector }` — available now (#1545 shipped); this template does not use it.
    ```
    **Declare `needs: { ai: true, database: true }`** — the canonical shape. The
    deployer wires the AI gateway (in-grid identity) and provisions Mongo,
@@ -129,8 +129,9 @@ the SAME entity (`target_entity_id`) so it updates the same URL.
 
 If the user wants the bot to answer over **their own documents** (retrieval-
 augmented generation), that needs 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.
+That path is **now available** — #1545 shipped. The template itself is a plain
+chatbot; declaring `vector: pgvector` injects `VECTOR_PGVECTOR_URL`, and you
+build the retrieval code on top of it.
 
 Keep it honest: async build, local-edition only, AI auth and DB credentials
 provided by the grid.

package/src/corpus/workflows/ai-knowledge-base.md

@@ -5,8 +5,8 @@ needs: ai+database
 deploy: runtime
 editions: local
 kind: blueprint
-capabilities_note: "persistent RAG — needs ai + database. Runtime app, async build, local edition only. Declare needs:{ai:true, database:true}; the deployer injects AI_GATEWAY_URL (AI Gateway via @cloudgrid-io/ai — works today) and DATABASE_MONGODB_URL (+legacy MONGODB_URL). The ideal embedding store needs:{vector:pgvector} (VECTOR_PGVECTOR_URL) is PENDING platform issue #1545 — until it lands, store embeddings in a Mongo `chunks` collection and cosine-rank in-app."
-summary: "A BLUEPRINT for a retrieval-augmented 'ask my docs' knowledge base — ingest documents, chunk + embed them, retrieve the nearest chunks per question, and answer grounded with citations, on persistent Next.js + Mongo + the CloudGrid AI Gateway. This is not fill-in-the-blanks app code; it ships structure + cloudgrid.yaml. Fetch the template, read AGENTS.md for the file tree / collections / RAG loop / CloudGrid wiring (needs ai+database, the pgvector #1545 note), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
+capabilities_note: "persistent RAG — needs ai + database. Runtime app, async build, local edition only. Declare needs:{ai:true, database:true}; the deployer injects AI_GATEWAY_URL (AI Gateway via @cloudgrid-io/ai — works today) and DATABASE_MONGODB_URL (+legacy MONGODB_URL). The ideal embedding store needs:{vector:pgvector} (VECTOR_PGVECTOR_URL) is now AVAILABLE — #1545 shipped (verified live 2026-07-16) — but this blueprint still stores embeddings in a Mongo `chunks` collection and cosine-ranks in-app; declare vector:pgvector only if you also build the retrieval on pgvector."
+summary: "A BLUEPRINT for a retrieval-augmented 'ask my docs' knowledge base — ingest documents, chunk + embed them, retrieve the nearest chunks per question, and answer grounded with citations, on persistent Next.js + Mongo + the CloudGrid AI Gateway. This is not fill-in-the-blanks app code; it ships structure + cloudgrid.yaml. Fetch the template, read AGENTS.md for the file tree / collections / RAG loop / CloudGrid wiring (needs ai+database, the pgvector note — #1545 shipped), then BUILD the app under services/web/ following it, and deploy async to a live URL (local edition only)."
 ---
 
 # Workflow: ai-knowledge-base
@@ -26,10 +26,11 @@ app code. The recipe is: fetch it, **read `AGENTS.md`**, then **build** the app
 following it. Be honest that a runtime deploy is async and needs the local edition.
 
 > **Vector-store status:** the ideal embedding store is `needs: { vector: pgvector }`
-> (injects `VECTOR_PGVECTOR_URL`), but it is **PENDING platform issue #1545**. The
-> **`ai` part works today.** Until #1545 ships, store embeddings in a Mongo
-> `chunks` collection and cosine-rank in the app — the blueprint declares
-> `needs: { ai: true, database: true }` and keeps `vector: pgvector` commented.
+> (injects `VECTOR_PGVECTOR_URL`), and it is **now available** — #1545 shipped. The
+> **blueprint still stores embeddings in a Mongo `chunks` collection** and
+> cosine-ranks in the app; it declares `needs: { ai: true, database: true }` and
+> keeps `vector: pgvector` commented. Uncomment it only if you also build the
+> retrieval on pgvector.
 
 ## 1. Edition check FIRST (hard gate)
 
@@ -54,11 +55,11 @@ CLI.
 **`AGENTS.md` structure guide** — read it before writing anything. It defines:
 - the `services/web/` file tree (pages, `api/documents` + `api/ask` routes, `lib/`),
 - the Mongo collections (`documents`, `chunks`) + fields,
-- the CloudGrid injection table (needs ai+database + the pgvector #1545 note),
+- the CloudGrid injection table (needs ai+database + the pgvector note),
 - the ingest → retrieve → answer RAG loop, with lazy `lib/db.js` / `lib/ai.js` /
-  `lib/retrieve.js` (cosine top-k over Mongo embeddings until #1545),
+  `lib/retrieve.js` (cosine top-k over Mongo embeddings as shipped),
 - optional auth/payments wiring via `vault:`,
-- the deploy flow and the pgvector swap-in once #1545 lands.
+- the deploy flow and the pgvector swap-in (now available — #1545 shipped).
 
 There is no app code to copy — you generate it from the guide.
 
@@ -86,7 +87,9 @@ the filesystem path. **Declare `needs: { ai: true, database: true }`** (canonica
 key) and provisions Mongo, injecting `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).
-Leave `vector: pgvector` **commented** — it is PENDING #1545.
+Leave `vector: pgvector` **commented** unless you build the retrieval on pgvector
+— the need is available (#1545 shipped), but this blueprint's code uses Mongo
+embeddings.
 
 ## 5. Build the app following AGENTS.md
 
@@ -100,7 +103,7 @@ Generate the files under `services/web/` per the guide:
   `embedding` array, mark the `documents` doc `ready`.
 - **Retrieve** (`lib/retrieve.js`): embed the question, cosine-rank the Mongo
   `chunks`, return top-k `{ text, documentId, score }` — a pure function that swaps
-  cleanly to a pgvector query once #1545 lands.
+  cleanly to a pgvector query (now available — #1545 shipped).
 - **Answer** (`POST /api/ask`): retrieve top-k, prompt the model to answer ONLY
   from the provided context and to cite the chunks, `chat()` via the AI Gateway,
   return the answer plus source chunks so the UI shows **citations**.
@@ -132,6 +135,6 @@ response is `status: "building"`, NOT a live URL yet.
 Give the user the live app URL — the deliverable. To iterate, re-plug the SAME
 entity so it updates the same URL. Keep it honest: this is a blueprint you built
 from, the build is async, it is local-edition only, credentials are injected by the
-grid (AI Gateway + Mongo via `needs`), and the pgvector store is PENDING #1545 (so
-embeddings currently live in Mongo). Swap to pgvector when #1545 ships per
-`AGENTS.md` §7.
+grid (AI Gateway + Mongo via `needs`), and the blueprint stores embeddings in
+Mongo (the pgvector store is available — #1545 shipped — but the shipped code
+does not use it). To swap to pgvector, follow `AGENTS.md` §7.

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

@@ -4,8 +4,8 @@ when: "search over my documents / PDFs / notes / knowledge base, semantic search
 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. Two refresh paths: the manager 'Refresh now' endpoint AND a scheduled Python type:cron job (services/refresh, daily 03:00 UTC) that vendors the backend app/ modules and reuses indexing.run_sync — both degrade gracefully. 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), wire the web+backend+refresh services, set the embeddings + source + manager secrets, deploy async, poll to a live URL, then Refresh now (or wait for the daily cron) to index."
+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 — this template stores embeddings in the Mongo chunks collection and cosine-ranks in-app (vector:pgvector is now available, #1545 shipped, verified live 2026-07-16; the template code does not use it). Two refresh paths: the manager 'Refresh now' endpoint AND a scheduled Python type:cron job (services/refresh, daily 03:00 UTC) that vendors the backend app/ modules and reuses indexing.run_sync — both degrade gracefully. 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 — the template uses Mongo embeddings; #1545 shipped), wire the web+backend+refresh services, set the embeddings + source + manager secrets, deploy async, poll to a live URL, then Refresh now (or wait for the daily cron) to index."
 recipe: "edition-gate -> auth+grid -> grid_create_project -> 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"
 ---
 
@@ -88,9 +88,10 @@ 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. **The refresh cron IS active**
+**NO `needs: vector`** — this template stores embeddings in the Mongo `chunks`
+collection (a float array) and cosine-ranks in-app. (`vector: pgvector` is now
+available — **#1545** shipped — but the template code does not use it; declare it
+only if you also switch the search 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 indexes on demand. Both call
 the same `indexing.run_sync`. Because each service builds in an isolated container,
@@ -137,6 +138,7 @@ 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 runs both on demand (endpoint) and on a schedule
+local-edition only, Mongo is injected by `needs`, embeddings live in Mongo (the
+template does not use pgvector, though #1545 shipped and the need is available),
+and refresh runs both on demand (endpoint) and on a schedule
 (the `refresh` cron).

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

@@ -0,0 +1,64 @@
+---
+name: simple-semantic-search
+when: semantic search over a document / article / text, "search my doc by meaning", question-answering search box over content, embeddings search, vector search, similarity search, "find the passage that answers X" — a SINGLE document or small text set, one service. For a multi-service document portfolio with upload UI + refresh cron, use semantic-search instead.
+needs: vector, ai
+deploy: runtime
+editions: local
+capabilities_note: "vector search — needs: { vector: pgvector } (injects VECTOR_PGVECTOR_URL; #1545 shipped, verified live 2026-07-16) + ai: true (embeddings via @cloudgrid-io/runtime, no API key). Runtime app, async build, local edition only."
+summary: "One node service that embeds a document into the entity's own pgvector schema at startup and serves POST /search + a minimal UI — probe-sized vector column, idempotent background seed, /health 503-until-ready, cosine <=> ranking. grid init app --here, grid plug, live in ~3 minutes."
+---
+
+# Workflow: simple-semantic-search
+
+The user wants to search content by MEANING — "find where it talks about X",
+a question box over an article, notes, or docs. Keyword match is not enough;
+this is embeddings + a vector store. On CloudGrid that is one declared need,
+not infrastructure to run.
+
+## 1. Edition check FIRST (hard gate)
+
+A runtime app: needs the **local edition** (Claude Desktop / Claude Code) or
+the CLI. On the hosted edition, say persistence/vector isn't available there
+and offer a static alternative honestly.
+
+## 2. Fetch the template
+
+`grid_get_template({kind: "template", name: "simple-semantic-search"})` — it
+contains the full working source (proven by a live deploy), the cloudgrid.yaml,
+and the `.cloudgrid/link.json` explainer.
+
+## 3. Adapt
+
+- Drop the user's content into `services/web/src/document.txt` (plain text,
+  blank-line-separated passages). Everything else usually stays as-is.
+- Keep the three proven mechanics exactly: probe-sized `vector(dim)` column,
+  idempotent background seed with `/health` 503-until-ready, lazy
+  `VECTOR_PGVECTOR_URL` read (legacy `PGVECTOR_URL` fallback).
+- The manifest is two needs and one service:
+
+```yaml
+needs:
+  vector: pgvector
+  ai: true
+services:
+  web: { type: node, path: /, health: /health }
+```
+
+## 4. Deploy
+
+```bash
+grid init app <name> --here    # registers the entity, writes .cloudgrid/link.json
+grid plug                      # async build — live URL in ~2-3 minutes
+grid visibility set <slug> link
+```
+
+`.cloudgrid/link.json` (entity_id / org / slug binding) is WRITTEN BY THE CLI —
+never hand-author it. If the folder was copied from someone else's project,
+`rm -rf .cloudgrid` first so `grid plug` doesn't update THEIR app.
+
+## 5. Verify like it's real
+
+Open the live URL, ask a question whose answer is in the document, and check
+the top passage actually answers it (rules out keyword-only luck). `grid logs`
+shows the `[seed]` lines; `/health` returns `{status:"ok", chunks: N, dim: D}`
+when ready.