vybekiit 0.7.32 → 0.7.34

package/dist/global-skills/neon-functions/references/sse.md

@@ -79,7 +79,7 @@ export default app;
 
 ## Push to every client, across isolates
 
-The fan-out rule is identical to WebSockets ([Keeping clients in sync across isolates](../SKILL.md#keeping-clients-in-sync-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers and pick a strategy there — **poll Postgres** by default (keeps Scale to Zero), or `LISTEN`/`NOTIFY` (shown below) for lowest latency on always-on compute. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
+If the data is database rows (live dashboards, feeds, chat over stored messages), use Neon Realtime (the `neon-realtime` skill) instead of hand-rolling fan-out. Otherwise, the fan-out rule is identical to WebSockets ([Fan-out across isolates](../SKILL.md#fan-out-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers and pick a strategy there — **poll Postgres** by default (keeps Scale to Zero), or `LISTEN`/`NOTIFY` (shown below) for lowest latency on always-on compute. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
 
 ```typescript
 import { attachDatabasePool } from "@neon/functions";
@@ -160,4 +160,4 @@ source.onerror = () => {
 - **CORS.** A SPA hits the function cross-origin, so set `Access-Control-Allow-Origin`. `EventSource` sends no credentials by default, so `*` is fine for public streams.
 - **One-way only.** SSE is server → client. For client → server, the browser makes normal `fetch`/`POST` calls (often to the same function); reach for [WebSockets](../SKILL.md#websocket-servers) only when you need bidirectional, low-latency frames.
 
-Together — a Hono `fetch` SSE endpoint, cross-isolate fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete realtime backend on a single function.
+Together — a Hono `fetch` SSE endpoint, cross-isolate fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete push backend on a single function, for push that doesn't come from database rows (presence, typing, LLM streams) or where Realtime isn't available. For persisted chat, feeds, and other live UIs over database rows, use Neon Realtime (the `neon-realtime` skill).

package/dist/global-skills/neon-object-storage/SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: neon-object-storage
 description: >-
-  S3-compatible object storage that branches with your Neon project, so files
-  and the database stay in sync across every branch. Use when a user wants
+  S3-compatible object storage that branches with your database, so each
+  branch gets its own copy of the files and the rows that point at them.
+  Use when a user wants
   object storage, a bucket, blob/file storage, or somewhere to put uploads,
   images, documents, avatars, or user-generated files for their app or agent —
   especially when they already use (or are setting up) Lakebase Postgres and don't
@@ -30,7 +31,7 @@ neon skills -s neon -y
 
 Currently available in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`.
 
-Neon Object Storage is S3-compatible object storage that branches with your projects: every branch gets its own isolated storage state, so files and database rows stay in sync across dev, preview, staging, and production.
+Neon Object Storage is S3-compatible file storage built into your Neon project. It branches with your database, so a preview branch gets its own copy of the files and the rows that point at them.
 
 Use this skill to help the user store and serve files that branch alongside their database. Deliver a working bucket and upload/download flow, a branch-aware S3 client wired to the injected env vars, or a precise answer from the official Neon docs.
 
@@ -39,7 +40,7 @@ Use this skill to help the user store and serve files that branch alongside thei
 Reach for Neon Object Storage for the files an app and its users produce — uploads, attachments, avatars, images, documents, generated assets, backups. It is the default place to put them when the app is already on Neon:
 
 - **They already use Lakebase Postgres and don't want a second provider.** One backend, one bill, one CLI, one set of branches — instead of standing up and wiring a separate AWS S3 / R2 / Supabase Storage account. The same Neon credential that backs the database backs storage.
-- **Files must stay in sync with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
+- **Files must branch with the database across environments.** Storage branches _together with_ your Postgres data. Fork a branch and the child instantly inherits the parent's buckets and objects at that point in time — copy-on-write, so no data is duplicated. This is what makes agent, dev, preview, and test environments seamless: a preview branch gets a consistent snapshot of _both_ the rows and the files they reference, and writes on the child never touch the parent.
 - **They want safe, throwaway environments.** Upload, overwrite, and delete files in a preview/CI branch without any risk to production data, then drop the branch.
 - **They want standard S3 tooling.** It's built on S3 semantics and speaks the S3 API, so the AWS SDKs, `boto3`, the AWS CLI, and presigned URLs all work — reliable and familiar, with no proprietary client.
 

package/dist/global-skills/neon-postgres/SKILL.md

@@ -6,7 +6,8 @@ description: >-
   scale-to-zero, instant restore, read replicas, IP allow lists, logical
   replication, and Lakebase Search. Use when the work is an existing
   DATABASE_URL, SQL, schema, inspect, or search. New backends, Auth, files,
-  Functions, and LLM calls go to the parent `neon` skill. Also use for
+  Functions, and LLM calls go to the parent `neon` skill. Live queries, reactive
+  UIs, and realtime data go to `neon-realtime`. Also use for
   "@neondatabase/serverless", "@neondatabase/neon-js", "neon inspect db",
   "semantic search", "vector search", "full-text search", "BM25", or
   "hybrid search".
@@ -32,6 +33,8 @@ It is the same database whether you reach it through Neon or through Databricks;
 
 Login, users, sessions, and `@neondatabase/auth` belong in `neon-auth`.
 
+Live queries, reactive UIs, and realtime data belong in `neon-realtime`.
+
 ## Setup Flow
 
 ### 1. Select the organization and project
@@ -258,7 +261,7 @@ Link: https://neon.com/docs/guides/logical-replication-guide.md
 
 Use Lakebase Search for semantic, full-text, and hybrid search:
 
-- For semantic search, read [Vector search](references/vector-search.md).
+- For semantic search, including generating embeddings with the Neon AI Gateway, read [Vector search](references/vector-search.md).
 - For full-text search with BM25 ranking, read [Full-text search](references/full-text-search.md).
 - For combining semantic and lexical results, read [Hybrid search](references/hybrid-search.md).
 - For managing any of the above through Drizzle ORM, read [Managing Lakebase Search with Drizzle](references/lakebase-search-drizzle.md).

package/dist/global-skills/neon-postgres/references/full-text-search.md

@@ -45,18 +45,24 @@ After a large bulk load, run `VACUUM` to refresh the statistics used by BM25 sco
 `to_bm25query` binds the query `tsvector` to the BM25 index whose corpus statistics should be used. The `<@>` operator returns a negative BM25 score, so lower (more negative) values are more relevant and must sort ascending:
 
 ```sql
-SELECT
-  id,
-  title,
-  body_tsv <@> to_bm25query(
-    to_tsvector('english', $1),
-    'documents_body_bm25'::regclass
-  ) AS score
-FROM documents
+SELECT id, title, score
+FROM (
+  SELECT
+    id,
+    title,
+    body_tsv <@> to_bm25query(
+      to_tsvector('english', $1),
+      'documents_body_bm25'::regclass
+    ) AS score
+  FROM documents
+) AS keyword_scored
+WHERE score < 0
 ORDER BY score
 LIMIT $2;
 ```
 
+Scalar BM25 scoring returns zero for documents containing none of the query terms. Filter `score < 0` before `ORDER BY` and `LIMIT` so keyword results exclude non-matches under both sequential and index plans. Partial query-term matches remain eligible.
+
 Use the same text-search configuration for document and query vectors. Select a language-specific or custom configuration that matches the corpus.
 
 ## Set the Candidate Limit
@@ -72,15 +78,19 @@ BEGIN;
 SET LOCAL lakebase_bm25.default_limit = 20;
 SET LOCAL lakebase_bm25.prefilter = on;
 
-SELECT
-  id,
-  title,
-  body_tsv <@> to_bm25query(
-    to_tsvector('english', $1),
-    'documents_body_bm25'::regclass
-  ) AS score
-FROM documents
-WHERE id % 1000 = 0
+SELECT id, title, score
+FROM (
+  SELECT
+    id,
+    title,
+    body_tsv <@> to_bm25query(
+      to_tsvector('english', $1),
+      'documents_body_bm25'::regclass
+    ) AS score
+  FROM documents
+  WHERE id % 1000 = 0
+) AS keyword_scored
+WHERE score < 0
 ORDER BY score
 LIMIT $2;
 COMMIT;

package/dist/global-skills/neon-postgres/references/hybrid-search.md

@@ -18,13 +18,13 @@ CREATE TABLE documents (
   id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
   title text NOT NULL,
   body text NOT NULL,
-  embedding vector(1536),
+  embedding vector(1024),
   body_tsv tsvector GENERATED ALWAYS AS
     (to_tsvector('english', body)) STORED
 );
 ```
 
-Replace `1536` with the embedding model's dimension. Use the same model and preprocessing for stored-document and query embeddings, and choose a PostgreSQL text-search configuration appropriate for the corpus.
+The 1024-dimensional column is an example. Set it to the output dimension of your selected embedding model. Generate document embeddings in batches and embed each query with the same model and dimensions; [Vector search](vector-search.md#prepare-embeddings) shows the AI Gateway calls. Follow any model-specific query instructions, while keeping the original query text for BM25. Choose a PostgreSQL text-search configuration appropriate for the corpus.
 
 Create and validate each retriever independently before combining them. Follow [Vector search](vector-search.md) and [Full-text search](full-text-search.md) for their indexes, query operators, and tuning.
 
@@ -34,7 +34,7 @@ Reciprocal Rank Fusion (RRF) is the approach in the Lakebase Search get-started
 
 For rank `r` and constant `k`, each retriever contributes `1 / (k + r)`. The documented starting point uses 40 candidates per retriever and `k = 60`; tune both for the corpus and workload.
 
-Bind the query embedding as `$1`, query text as `$2`, and final result count as `$3`:
+Embed the query text through the same gateway model used for the stored documents, then bind that vector as `$1`, the original query text as `$2`, and the final result count as `$3`:
 
 ```sql
 WITH vector_ranked AS (
@@ -49,15 +49,19 @@ WITH vector_ranked AS (
 keyword_ranked AS (
   SELECT id, RANK() OVER (ORDER BY score) AS rank
   FROM (
-    SELECT
-      id,
-      body_tsv <@> to_bm25query(
-        to_tsvector('english', $2),
-        'documents_body_bm25'::regclass
-      ) AS score
-    FROM documents
-    ORDER BY score
-    FETCH FIRST 40 ROWS WITH TIES
+    SELECT id, score
+    FROM (
+      SELECT
+        id,
+        body_tsv <@> to_bm25query(
+          to_tsvector('english', $2),
+          'documents_body_bm25'::regclass
+        ) AS score
+      FROM documents
+    ) AS keyword_scored
+    WHERE score < 0
+    ORDER BY score, id
+    LIMIT 40
   ) AS keyword_candidates
 )
 SELECT
@@ -73,13 +77,13 @@ ORDER BY rrf_score DESC, d.id
 LIMIT $3;
 ```
 
-`RANK()` gives tied retrieval scores the same rank. Sort by `rrf_score` descending and use the stable ID as a final tie-breaker.
+`score < 0` excludes BM25 non-matches. Many matching documents can share a BM25 score, so `WITH TIES` could admit a large group at the cutoff. `ORDER BY score, id LIMIT 40` keeps keyword candidates bounded and breaks boundary ties by ID. `RANK()` uses score alone so retained ties receive equal ranks.
 
-`FETCH FIRST ... ROWS WITH TIES` keeps every candidate tied at the cutoff, so `RANK()` receives the complete boundary tie group. The candidate set can therefore exceed 40 rows. `lakebase_bm25.default_limit` defaults to `1000`; increase it only when the BM25 candidate set needs to exceed that value.
+Vector retrieval preserves cutoff ties and can exceed 40 candidates. `lakebase_bm25.default_limit` defaults to `1000`; the SQL limit bounds keyword rows entering fusion, not total scoring work.
 
 ## Adapt the Hybrid Search
 
-- Retrieve more candidates from each source than the final result count; otherwise one retriever can dominate before fusion has enough overlap. Keep `lakebase_bm25.default_limit` above the BM25 candidate target and allow room for boundary ties.
+- Retrieve more candidates from each source than the final result count; otherwise one retriever can dominate before fusion has enough overlap. Keep `lakebase_bm25.default_limit` at least as large as the BM25 candidate target.
 - Keep each retriever's operator and index configuration correct independently before tuning RRF.
 - Tune candidate counts and the RRF constant with judged or behavioral relevance data, plus latency measurements.
 - Add weights only when product evidence shows one retriever should contribute more. Weight the reciprocal-rank contributions, not the raw vector distance and negative BM25 score.

package/dist/global-skills/neon-postgres/references/lakebase-search-drizzle.md

@@ -10,6 +10,7 @@ Contents:
 - [Extensions](#extensions): custom migration required to create extensions (Drizzle can't)
 - [Schema](#schema): columns, generated `tsvector`, and the ANN index
 - [BM25 Index](#bm25-index): created after the corpus is seeded
+- [Generate and Store Embeddings](#generate-and-store-embeddings): call the AI Gateway and insert vectors with Drizzle
 - [Query](#query): vector, BM25, and hybrid reads
 - [Tune Per Query](#tune-per-query): per-query GUCs
 
@@ -22,18 +23,22 @@ Rules:
 
 ## Config
 
-`drizzle-kit generate` and `migrate` read `drizzle.config.ts`. Point `dbCredentials.url` at the **direct (unpooled)** connection string:
+`drizzle-kit generate` and `migrate` read `drizzle.config.ts`. If the connection string is in `.env`, install `dotenv` (`npm install dotenv`) and load it here. Point `dbCredentials.url` at the **direct (unpooled)** connection string:
 
 ```typescript
 // drizzle.config.ts
+import "dotenv/config";
 import { defineConfig } from "drizzle-kit";
 
+const databaseUrl = process.env.DATABASE_URL_UNPOOLED;
+if (!databaseUrl) throw new Error("Missing DATABASE_URL_UNPOOLED");
+
 export default defineConfig({
   schema: "./src/schema.ts",
   out: "./drizzle",
   dialect: "postgresql",
   // Direct (unpooled) URL. Neon exposes it as DATABASE_URL_UNPOOLED.
-  dbCredentials: { url: process.env.DATABASE_URL_UNPOOLED },
+  dbCredentials: { url: databaseUrl },
 });
 ```
 
@@ -57,7 +62,14 @@ The columns, the generated `tsvector`, and the `lakebase_ann` index all go in `s
 
 ```typescript
 // src/schema.ts
-import { pgTable, bigint, text, vector, index, customType } from "drizzle-orm/pg-core";
+import {
+  pgTable,
+  bigint,
+  text,
+  vector,
+  index,
+  customType,
+} from "drizzle-orm/pg-core";
 import { sql } from "drizzle-orm";
 
 const tsvector = customType<{ data: string }>({
@@ -69,10 +81,12 @@ const tsvector = customType<{ data: string }>({
 export const documents = pgTable(
   "documents",
   {
-    id: bigint("id", { mode: "number" }).generatedByDefaultAsIdentity().primaryKey(),
+    id: bigint("id", { mode: "number" })
+      .generatedByDefaultAsIdentity()
+      .primaryKey(),
     title: text("title").notNull(),
     body: text("body").notNull(),
-    embedding: vector("embedding", { dimensions: 1536 }),
+    embedding: vector("embedding", { dimensions: 1024 }),
     bodyTsv: tsvector("body_tsv").generatedAlwaysAs(
       sql`to_tsvector('english', "body")`,
     ),
@@ -86,7 +100,7 @@ export const documents = pgTable(
 );
 ```
 
-Set the dimension to match your embedding model. Postgres maintains `body_tsv`, so never write it from the app. Generate and apply the migration after the extensions migration above:
+The 1024-dimensional column is an example; set it to the output dimension of your selected embedding model. Use the same model and dimensions for stored documents and queries. Postgres maintains `body_tsv`, so never write it from the app. Generate and apply the migration after the extensions migration above:
 
 ```bash
 npx drizzle-kit generate --name=lakebase_search
@@ -106,6 +120,66 @@ npx drizzle-kit generate --custom --name=bm25_index
 CREATE INDEX documents_body_bm25 ON documents USING lakebase_bm25 (body_tsv);
 ```
 
+## Generate and Store Embeddings
+
+Use the [Vercel AI SDK](https://ai-sdk.dev) (`ai`, 6+) with Neon's `@neon/ai-sdk-provider` 1.0.0+. Follow the [gateway setup](vector-search.md#prepare-embeddings), then install the packages with `npm install @neon/ai-sdk-provider ai dotenv`:
+
+```typescript
+import "dotenv/config";
+import { neon } from "@neon/ai-sdk-provider";
+import { embed, embedMany } from "ai";
+
+const embeddingModel = neon.embeddingModel("qwen3-embedding-0-6b");
+const providerOptions = { neon: { dimensions: 1024 } };
+// Qwen3 query prompt adapted for Neon documentation search; documents stay unprefixed.
+const queryPrompt =
+  "Instruct: Given a question about Neon, retrieve documentation passages that answer the question\nQuery: ";
+```
+
+Generate a document vector, then insert it with Drizzle:
+
+```typescript
+const { embedding } = await embed({
+  model: embeddingModel,
+  value: body,
+  providerOptions,
+});
+await db.insert(documents).values({
+  title,
+  body,
+  embedding,
+});
+```
+
+For bulk imports, skip blank rows and embed/insert one batch at a time:
+
+```typescript
+const batchSize = 64;
+const nonBlankRows = rows.filter((row) => row && row.body.trim().length > 0);
+
+for (let offset = 0; offset < nonBlankRows.length; offset += batchSize) {
+  const batch = nonBlankRows.slice(offset, offset + batchSize);
+  const { embeddings: vectors } = await embedMany({
+    model: embeddingModel,
+    values: batch.map((row) => row.body),
+    providerOptions,
+    maxParallelCalls: 1,
+  });
+  await db.insert(documents).values(
+    batch.map((row, index) => {
+      const embedding = vectors[index];
+      if (!embedding)
+        throw new Error(`Missing embedding for batch row ${index}`);
+      return { ...row, embedding };
+    }),
+  );
+}
+```
+
+`embedMany` splits embedding requests using the provider's per-request input limit. This loop also bounds database inserts and memory; tune `batchSize` for your workload. Chunk long documents before embedding. Earlier batches stay committed if a later batch fails.
+
+Apply `queryPrompt` only to queries, keeping the original text for BM25. Use the same model and dimensions for documents and queries; re-embed documents when switching models.
+
 ## Query
 
 Use the query builder with Drizzle's `cosineDistance` helper for vector search. It emits the `<=>` operator, so keep the index on `vector_cosine_ops`:
@@ -114,7 +188,11 @@ Use the query builder with Drizzle's `cosineDistance` helper for vector search.
 import { cosineDistance } from "drizzle-orm";
 import { documents } from "./schema";
 
-// queryEmbedding: number[] from the same model used for stored documents
+const { embedding: queryEmbedding } = await embed({
+  model: embeddingModel,
+  value: `${queryPrompt}${queryText}`,
+  providerOptions,
+});
 const distance = cosineDistance(documents.embedding, queryEmbedding);
 
 const rows = await db
@@ -130,17 +208,23 @@ BM25 has no Drizzle helper: `<@>` and `to_bm25query` require raw SQL. Reference
 import { sql } from "drizzle-orm";
 
 const rows = await db.execute(sql`
-  SELECT id, title,
-    body_tsv <@> to_bm25query(
-      to_tsvector('english', ${queryText}),
-      'documents_body_bm25'::regclass
-    ) AS score
-  FROM documents
+  SELECT id, title, score
+  FROM (
+    SELECT id, title,
+      body_tsv <@> to_bm25query(
+        to_tsvector('english', ${queryText}),
+        'documents_body_bm25'::regclass
+      ) AS score
+    FROM documents
+  ) AS keyword_scored
+  WHERE score < 0
   ORDER BY score
   LIMIT ${k}
 `);
 ```
 
+Filter `score < 0` before the candidate cutoff: scalar BM25 scoring returns zero for non-matches, which must not become keyword hits. Partial query-term matches remain eligible.
+
 Run the [hybrid search](hybrid-search.md) RRF query the same way: raw SQL through `db.execute`.
 
 ## Tune Per Query
@@ -168,5 +252,6 @@ const rows = await db.transaction(async (tx) => {
 
 Sources:
 
+- [AI Gateway embeddings](https://neon.com/docs/ai-gateway/embeddings)
 - [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started)
-- [Schema migration with Lakebase Postgres and Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations)
+- [Schema migration with Lakebase Postgres and Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations)

package/dist/global-skills/neon-postgres/references/vector-search.md

@@ -5,7 +5,7 @@ Use `lakebase_vector` for approximate nearest-neighbor retrieval over embeddings
 ## Contents
 
 - [Create the extension](#create-the-extension) — enable `lakebase_vector` and its `pgvector` dependency
-- [Prepare embeddings](#prepare-embeddings) — define the vector column and keep embedding dimensions consistent
+- [Prepare embeddings](#prepare-embeddings) — generate vectors with the AI Gateway and match the column dimension
 - [Build the index](#build-the-index) — match the distance metric, operator class, and query operator
 - [Tune the index](#tune-the-index) — configure index-build options and concurrent index management
 - [Query](#query) — rank by vector distance or filter by a similarity radius
@@ -24,28 +24,111 @@ CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
 
 ## Prepare Embeddings
 
-Use any embedding provider whose vector dimensions and distance metric match the schema and index:
+Neon's [AI Gateway embeddings endpoint](https://neon.com/docs/ai-gateway/embeddings) is an OpenAI-compatible way to generate vectors for Lakebase Search. This table uses 1024 dimensions as an example; set the column dimension to the output of the model and any `dimensions` parameter you choose:
 
 ```sql
 CREATE TABLE documents (
   id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
   title text NOT NULL,
   body text NOT NULL,
-  embedding vector(1536)
+  embedding vector(1024)
 );
 ```
 
-Replace `1536` with the embedding model's dimension. Generate stored-document and query embeddings with the same model and preprocessing. Keep embedding generation outside SQL unless the architecture already provides an in-database embedding function.
+Enable the AI Gateway on the branch and get `NEON_AI_GATEWAY_TOKEN` and the bare-host `NEON_AI_GATEWAY_BASE_URL`:
+
+- With `neon.ts`, declare `aiGateway: true`, run `neon deploy`, then run `neon env pull --file .env`.
+- Without `neon.ts`, run `neon env pull --service ai-gateway --file .env` from a directory linked to the intended project and branch. This requests the gateway variables explicitly and skips other services.
+- Alternatively, get both values from the Neon Console. Neon Functions receive them automatically.
+
+### AI SDK (Recommended)
+
+For TypeScript apps, use Neon's `@neon/ai-sdk-provider` 1.0.0+ with the [Vercel AI SDK](https://ai-sdk.dev) (`ai`, 6+) (`npm install @neon/ai-sdk-provider ai dotenv`). The provider reads `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` directly and sends embedding requests to `/v1/embeddings`. Load `.env` in a standalone app; Neon Functions inject the variables automatically.
+
+```typescript
+import "dotenv/config";
+import { neon } from "@neon/ai-sdk-provider";
+import { embed, embedMany } from "ai";
+
+const embeddingModel = neon.embeddingModel("qwen3-embedding-0-6b");
+const providerOptions = { neon: { dimensions: 1024 } };
+// Qwen3 query prompt adapted for Neon documentation search; documents stay unprefixed.
+const queryPrompt =
+  "Instruct: Given a question about Neon, retrieve documentation passages that answer the question\nQuery: ";
+
+const { embeddings: documentEmbeddings } = await embedMany({
+  model: embeddingModel,
+  values: documentBodies, // non-empty document batch; store vectors by input index
+  providerOptions,
+  maxParallelCalls: 1,
+});
+const { embedding: queryEmbedding } = await embed({
+  model: embeddingModel,
+  value: `${queryPrompt}${queryText}`,
+  providerOptions,
+}); // bind to $1 below
+```
+
+Skip empty imports before calling `embedMany`. It returns vectors in input order and splits requests according to the provider's item limit. For large imports, also split document text within the endpoint's token limits and keep database writes bounded.
+
+For Neon documentation search, the example adapts the task instruction in Qwen3's stored `query` prompt from [config_sentence_transformers.json](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B/blob/main/config_sentence_transformers.json). Its `document` prompt is empty, so document text stays unprefixed. Neither SDK applies SentenceTransformers prompts automatically. Keep the original `queryText` for BM25, and use the selected model's own prompt conventions if you switch models.
+
+### OpenAI SDK Alternative
+
+For an existing OpenAI SDK integration, install `openai` and `dotenv` (`npm install openai dotenv`) and configure the client explicitly:
+
+```typescript
+import "dotenv/config";
+import OpenAI from "openai";
+
+const apiKey = process.env.NEON_AI_GATEWAY_TOKEN;
+const gatewayBaseUrl = process.env.NEON_AI_GATEWAY_BASE_URL;
+if (!apiKey || !gatewayBaseUrl) {
+  throw new Error("Missing Neon AI Gateway credentials");
+}
+
+const client = new OpenAI({
+  apiKey,
+  baseURL: `${gatewayBaseUrl}/v1`,
+});
+
+async function embedBatch(inputs: string[]): Promise<number[][]> {
+  if (inputs.length === 0) return [];
+  const response = await client.embeddings.create({
+    model: "qwen3-embedding-0-6b",
+    input: inputs,
+    dimensions: 1024,
+    encoding_format: "float",
+  });
+  const vectors: number[][] = [];
+  for (const item of response.data) vectors[item.index] = item.embedding;
+  return inputs.map((_, index) => {
+    const embedding = vectors[index];
+    if (!embedding) throw new Error(`Missing embedding for input ${index}`);
+    return embedding;
+  });
+}
+
+const documentEmbeddings = await embedBatch(documentBodies);
+const [queryEmbedding] = await embedBatch([`${queryPrompt}${queryText}`]);
+if (!queryEmbedding) throw new Error("Missing query embedding");
+```
+
+Use the same `queryPrompt` defined above, only for query inputs. Keep each batch within the endpoint's input and rate limits, and pair each vector with its source row using the response `index`. The [OpenAI JavaScript SDK v6](https://github.com/openai/openai-node/blob/v6.0.0/src/resources/embeddings.ts) defaults to requesting base64 and decodes the response as base64. If a compatible endpoint returns float arrays instead, that decoder can silently turn them into zeros. Pass `encoding_format: "float"` explicitly for the AI Gateway; the SDK then returns the float arrays directly. Base64 can reduce response size when an endpoint actually returns base64, but do not assume that format for this gateway.
+
+Use the same model and output dimensions for stored documents and queries. Follow the model's input conventions: some models recommend a query instruction while document text remains unprefixed. If the model supports shorter vectors, compare retrieval quality, storage, and latency before changing dimensions; set the column and both embedding requests to the chosen size. Switching models requires re-embedding the corpus; changing dimensions also requires migrating the vector column and index. Generate embeddings in the application, outside SQL, unless the architecture already provides an in-database embedding function. Other embedding providers are also valid when their output matches the schema and index.
 
 ## Build the Index
 
 Choose the operator class and query operator as a matched pair:
 
-| Metric | Common use | Operator class | Distance operator |
-| --- | --- | --- | --- |
-| Cosine | Most text embeddings | `vector_cosine_ops` | `<=>` |
-| L2 / Euclidean | Absolute distance matters; vectors do not need normalization | `vector_l2_ops` | `<->` |
-| Inner product | Unit-normalized vectors; matches cosine for unit vectors | `vector_ip_ops` | `<#>` |
+| Metric         | Common use                                                   | Operator class      | Distance operator |
+| -------------- | ------------------------------------------------------------ | ------------------- | ----------------- |
+| Cosine         | Most text embeddings                                         | `vector_cosine_ops` | `<=>`             |
+| L2 / Euclidean | Absolute distance matters; vectors do not need normalization | `vector_l2_ops`     | `<->`             |
+| Inner product  | Unit-normalized vectors; matches cosine for unit vectors     | `vector_ip_ops`     | `<#>`             |
+
+Choose the metric recommended for the selected model, and keep its index operator class and query operator aligned. The [Qwen3 Embedding model card](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B) demonstrates cosine similarity and normalized dot product for retrieval. For unit-normalized vectors, cosine, inner product, and L2 have the same exact ranking; approximate indexes can still differ in recall and latency, so benchmark on your corpus.
 
 ```sql
 CREATE INDEX documents_embedding_ann ON documents
@@ -79,7 +162,7 @@ For a large table, use `CREATE INDEX CONCURRENTLY` to avoid locking out writes w
 
 ## Query
 
-Generate the query embedding with the same model and preprocessing used for stored documents, then bind it as a parameter:
+Generate the query embedding with the same model and dimensions used for stored documents, following the model's query-input conventions (using the Qwen3 query prompt shown above), then bind it as a parameter:
 
 ```sql
 SELECT id, title, embedding <=> $1::vector AS distance