vybekiit 0.7.26 → 0.7.27

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

@@ -22,12 +22,12 @@ metadata:
 If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
 
 ```bash
-npx skills add neondatabase/agent-skills --skill neon
+neon skills -s neon -y
 ```
 
 # Neon Object Storage
 
-This is a public beta feature and only available in `us-east-2`.
+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.
 
@@ -53,7 +53,7 @@ If the files in question ship with the app itself — HTML, JS bundles, CSS, the
 
 ## Availability
 
-Check this precondition before setting anything up: Neon Object Storage is a public beta feature available in the `us-east-2` region. Confirm the user's Neon project is in `us-east-2` before proceeding.
+Check this precondition before setting anything up: Neon Object Storage is currently available in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Confirm the user's Neon project is in one of these regions before proceeding. Region coverage: https://neon.com/docs/get-started/backend-overview.md
 
 ## Architecture: Where Object Storage Fits
 
@@ -64,18 +64,16 @@ Neon (Object Storage included) is **backend primitives, not full-stack app hosti
 
 ## Setup
 
-Object storage is part of the `neon.ts` infrastructure-as-code config (see the `neon` skill for the branch-first workflow, `link`/`checkout`, and `neon.ts` basics). Declare buckets under `preview.buckets`, keyed by bucket name:
+Object storage is part of the `neon.ts` infrastructure-as-code config (see the `neon` skill for the branch-first workflow, `link`/`checkout`, and `neon.ts` basics). Declare buckets under `buckets`, keyed by bucket name:
 
 ```typescript
 // neon.ts
 import { defineConfig } from "@neon/config/v1";
 
 export default defineConfig({
-  preview: {
-    buckets: {
-      images: {}, // private by default
-      "public-assets": { access: "public_read" },
-    },
+  buckets: {
+    images: {}, // private by default
+    "public-assets": { access: "public_read" },
   },
 });
 ```
@@ -88,7 +86,7 @@ neon deploy   # alias for `neon config apply`
 
 ## Neon Infrastructure as Code (`neon.ts`)
 
-The `preview.buckets` block above is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares your buckets alongside every other service the branch should have (see the `neon` skill for the full reference). Reconcile the declaration against a branch the Terraform way:
+The `buckets` block above is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares your buckets alongside every other service the branch should have (see the `neon` skill for the full reference). Reconcile the declaration against a branch the Terraform way:
 
 ```bash
 neon config status   # print the branch's live config (which buckets exist)
@@ -100,7 +98,7 @@ Buckets are **branch-scoped**: when a `neon.ts` is present, `neon checkout` appl
 
 ## Environment Variables
 
-When `preview.buckets` is declared, Neon injects **AWS-standard** S3 env vars so the AWS SDKs work from the environment with zero extra config. Inside a deployed Neon Function these are injected automatically; locally, pull them onto disk (or inject them at runtime) via the CLI:
+When `buckets` is declared, Neon injects **AWS-standard** S3 env vars so the AWS SDKs work from the environment with zero extra config. Inside a deployed Neon Function these are injected automatically; locally, pull them onto disk (or inject them at runtime) via the CLI:
 
 ```bash
 neon env pull            # writes the branch's vars into .env (or .env.local)
@@ -218,6 +216,7 @@ The Neon documentation is the source of truth and Object Storage is evolving rap
 
 ## Further Reading
 
+- https://neon.com/docs/get-started/backend-overview.md
 - https://neon.com/docs/storage/overview.md
 - https://neon.com/docs/storage/get-started.md
 - https://neon.com/docs/storage/buckets.md

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

@@ -1,16 +1,15 @@
 ---
 name: neon-postgres
 description: >-
-  Guides and best practices for working with Lakebase Postgres, the database
-  behind Neon. Covers setup, connection methods and drivers, pooled vs direct
-  connections, branching, schema migrations, autoscaling, scale-to-zero, instant
-  restore, read replicas, connection pooling, IP allow lists, and logical
-  replication.
-  Use when users ask about "Lakebase Postgres", "Neon setup", "connect to Neon",
-  "Neon project", "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP",
-  "Neon Auth", "@neondatabase/serverless", "@neondatabase/neon-js",
-  "scale to zero", "Neon autoscaling", "Neon read replica",
-  "Neon connection pooling", or "schema migrations".
+  Guides and best practices for working with Lakebase Postgres on Neon:
+  connections, pooled vs direct, schema migrations, branching, autoscaling,
+  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
+  "@neondatabase/serverless", "@neondatabase/neon-js", "neon inspect db",
+  "semantic search", "vector search", "full-text search", "BM25", or
+  "hybrid search".
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres
@@ -21,7 +20,7 @@ metadata:
 If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
 
 ```bash
-npx skills add neondatabase/agent-skills --skill neon
+neon skills -s neon -y
 ```
 
 # Lakebase Postgres
@@ -30,15 +29,21 @@ Lakebase Postgres is the database at the core of Neon. It runs on the lakebase a
 
 It is the same database whether you reach it through Neon or through Databricks; this skill covers the Neon access path.
 
+Login, users, sessions, and `@neondatabase/auth` belong in `neon-auth`.
+
 ## Setup Flow
 
 ### 1. Select the organization and project
 
-Use the CLI (default) or MCP server to list organizations and projects. Let the user select an existing project or create a new one. Check the `.neon` file for an existing linked project or branch.
+If a `DATABASE_URL` is already supplied (prompt, environment, or repo) or a `.neon` file points at a project, use it. Do not list organizations or create a second project for schema work.
+
+Otherwise use the CLI (default) or MCP server to list organizations and projects. Let the user select an existing project or create a new one.
 
 ### 2. Get the connection string
 
-Use the CLI (default), `neon env pull`, or the MCP server to get the connection string. Store it in `.env` as `DATABASE_URL`. Read the file first before modifying it, to avoid overwriting existing values.
+If a `DATABASE_URL` is already supplied, use it. Do not fetch another through the CLI or MCP.
+
+Otherwise use the CLI (default), `neon env pull`, or the MCP server to get the connection string. Store it in `.env` as `DATABASE_URL`. Read the file first before modifying it, to avoid overwriting existing values.
 
 #### When to use pooled vs direct connections
 
@@ -54,11 +59,10 @@ Use the CLI (default), `neon env pull`, or the MCP server to get the connection
 
 ### 3. Pick the connection method and driver
 
-Always pair Neon with an ORM such as **Drizzle** for easy schema management and migrations. Refer to the connection methods guide to pick the correct driver based on how the runtime treats your code: https://neon.com/docs/connect/choose-connection.md.
+Preserve the existing ORM and driver. For new TypeScript schema work with no established choice, Drizzle is a suggestion: https://neon.com/docs/guides/drizzle.md. Refer to the connection methods guide to pick the correct driver based on how the runtime treats your code: https://neon.com/docs/connect/choose-connection.md.
 
-Recommendations:
+Driver notes:
 
-- Drizzle as ORM (see https://neon.com/docs/guides/drizzle.md)
 - On Vercel, use `node-postgres` (`npm install pg`) with Vercel Fluid compute and `import { attachDatabasePool } from "@vercel/functions";`
 - On Cloudflare, use `node-postgres` with Cloudflare Hyperdrive
 - On Neon Functions, use `node-postgres`, as the functions are long-running and reuse the pool across requests.
@@ -85,7 +89,7 @@ Link: https://neon.com/docs/introduction/branching.md
 For detailed branch creation workflows (normal vs schema-only branches, reset-from-parent, CLI/MCP selection), use the `neon-postgres-branches` skill. If it isn't installed, fetch it from https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md or install it with:
 
 ```bash
-npx skills add neondatabase/agent-skills --skill neon-postgres-branches
+neon skills -s neon-postgres-branches -y
 ```
 
 ## Migrations
@@ -94,6 +98,90 @@ Test a migration on a branch of production, against production-like data, before
 
 Use a **direct (non-pooled)** connection string when you run the migration, not a pooled one. `neon connection-string` returns the direct string by default; make sure the hostname does not include the `-pooler` suffix.
 
+## Troubleshooting and Neon-Specific Performance
+
+Use Neon's predefined, read-only diagnostics before writing catalog queries by hand. The Neon CLI `neon inspect db` subcommands and the Neon MCP server's `inspect_database` tool run the same checks.
+
+This section covers Neon-specific diagnostic tools, compute cache behavior, and platform signals. When the evidence points to generic Postgres work such as rewriting a query, choosing an index, changing a schema, or interpreting plan nodes, load the [`postgres-best-practices`](https://github.com/neondatabase/postgres-skills/tree/main/skills/postgres-best-practices) skill and carry the diagnostic evidence into that workflow.
+
+Docs:
+
+- CLI: https://neon.com/docs/cli/inspect.md
+- Query performance: https://neon.com/docs/postgresql/query-performance.md
+- `pg_stat_statements`: https://neon.com/docs/extensions/pg_stat_statements.md
+- Neon Local File Cache: https://neon.com/docs/extensions/neon.md
+
+### Choose CLI or MCP
+
+Prefer the Neon CLI when terminal access and authentication are available:
+
+```bash
+neon inspect db <check>
+```
+
+The CLI resolves the project and branch from the current Neon context. Use `--project-id`, `--branch`, and `--database-name` to override it. Omit `--database-name` to inspect every database on the branch. Use `--db-url` only when inspecting a Postgres database directly instead of resolving it through the Neon API.
+
+When using Neon MCP, call `inspect_database` with `projectId` and one `check`. Pass `branchId`, `databaseName`, or `computeId` only when needed. Omit `databaseName` to inspect all databases on the branch. Increase `limit` only when the result says it was truncated.
+
+### Pick the Diagnostic
+
+| Symptom or question                            | Checks                               |
+| ---------------------------------------------- | ------------------------------------ |
+| Which relations consume storage?               | `table-sizes`, `index-sizes`         |
+| Is an index unused or a table scanned heavily? | `unused-indexes`, `seq-scans`        |
+| What has run for 5+ minutes or holds locks?    | `long-running-queries`, `locks`      |
+| Which queries consume the most total time?     | `outliers`                           |
+| Which queries run most often?                  | `calls`                              |
+| Does the active data fit in compute cache?     | `lfc-hit-rate`, `working-set`        |
+| Is autovacuum behind or is space wasted?       | `vacuum-stats`, `bloat`              |
+| Is logical replication healthy?                | `replication-slots`, `subscriptions` |
+
+Do not confuse these checks:
+
+- `long-running-queries` reports statements running **right now** for more than five minutes.
+- `outliers` ranks the top queries by cumulative execution time since statistics were reset. It does not rank by mean latency.
+- `calls` ranks by execution count over the same statistics history.
+
+`outliers` and `calls` require `pg_stat_statements`. `lfc-hit-rate` and `working-set` require the `neon` extension. If a check reports a missing extension, ask before running the suggested `CREATE EXTENSION` statement because installing an extension modifies the database.
+
+### Interpret Results Safely
+
+- Treat `unused-indexes` as a candidate list, not permission to drop indexes. Confirm the observation window, constraints, and workload before removal.
+- A sequential scan can be correct for a small table or a query reading much of a table. Check table size, selectivity, and the query plan before adding an index.
+- `bloat` is a statistical estimate. Confirm the impact and plan locks or maintenance before `VACUUM FULL`, `REINDEX`, or similar remediation.
+- Cache and Postgres statistics reset when compute restarts, including scale-to-zero suspension. Run a representative workload before interpreting fresh `lfc-hit-rate`, `working-set`, `vacuum-stats`, or `pg_stat_statements` results.
+- Compute-wide checks (`lfc-hit-rate`, `working-set`, and `replication-slots`) run once even when inspecting every database.
+- One failing database can fail an all-databases inspection; retry the relevant check with an explicit `databaseName` to isolate it.
+
+### Inspect Neon Cache Behavior Per Query
+
+Standard `EXPLAIN (ANALYZE, BUFFERS)` reports Postgres shared-buffer activity, but it does not show Neon's Local File Cache (LFC) or page prefetching. For a safe read-only query, add Neon's `FILECACHE` and `PREFETCH` options:
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, PREFETCH, FILECACHE)
+SELECT ...;
+```
+
+- `File cache: hits` counts pages found in the compute's LFC.
+- `File cache: misses` counts pages not found in the LFC and fetched from database storage.
+- `Prefetch: hits`, `misses`, `expired`, and `duplicates` show how effectively Neon fetched pages before the executor requested them.
+
+`FILECACHE` and `PREFETCH` provide metrics for this query and do not require the `neon` extension. By contrast, `neon inspect db lfc-hit-rate` and `working-set` provide compute-wide statistics and do require the extension.
+
+The MCP `explain_sql_statement` tool can produce a standard plan but does not expose `FILECACHE` or `PREFETCH` options. To collect those Neon-specific metrics through MCP, use `run_sql` with the explicit, read-only `EXPLAIN` statement above.
+
+Because `ANALYZE` executes the statement, use it only when execution is safe; do not run it autonomously for mutating SQL. Compare cold- and warm-cache runs carefully because the first execution can populate the cache and materially change later results.
+
+### Performance Workflow
+
+1. Reproduce the symptom and note its time window.
+2. Run the smallest relevant `inspect` checks from the table above.
+3. Identify a specific query before changing schema or compute. Use MCP `explain_sql_statement` for a standard plan, or the Neon-specific `EXPLAIN` above when LFC or prefetch behavior matters.
+4. If the bottleneck is query shape, indexing, schema, locking, or vacuum behavior, load `postgres-best-practices` and carry forward the inspection results and query plan. Keep Neon compute, cache, connection, and platform decisions in this skill.
+5. Re-run the same check and workload to verify the change.
+
+Use MCP `list_slow_queries` instead of `inspect_database` when the user specifically needs queries ranked by average execution time with a custom threshold and limit. Outside the explicit `EXPLAIN` case above, use `run_sql` only for read-only diagnostic SQL when the predefined checks do not answer the question.
+
 ## Autoscaling
 
 Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
@@ -165,6 +253,21 @@ Key points:
 
 Link: https://neon.com/docs/guides/logical-replication-guide.md
 
+## Lakebase Search
+
+Use Lakebase Search for semantic, full-text, and hybrid search:
+
+- For semantic search, 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).
+
+Links:
+
+- [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started)
+- [`lakebase_vector` reference](https://neon.com/docs/extensions/lakebase-vector)
+- [`lakebase_text` reference](https://neon.com/docs/extensions/lakebase-text)
+
 ## Gotchas
 
 ### Pooled vs direct connections: use the direct URL for migrations, dumps, and replication

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

@@ -0,0 +1,99 @@
+# Full-Text Search with BM25 Ranking
+
+Use `lakebase_text` for BM25 relevance ranking with PostgreSQL's standard `tsvector` type. The `lakebase_bm25` index adds corpus-aware ranking and top-K pushdown.
+
+Lakebase Search requires Postgres 16 or later. Enable the extension before creating the index:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS lakebase_text;
+```
+
+`lakebase_text` has no extension dependency. It relies on a preloaded library that Neon enables by default; if the project customized its preloaded-library list, confirm the library remains enabled.
+
+## Prepare and Index Text
+
+Prefer a stored generated `tsvector` when search text comes from stable table columns:
+
+```sql
+CREATE TABLE documents (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  title text NOT NULL,
+  body text NOT NULL,
+  body_tsv tsvector GENERATED ALWAYS AS
+    (to_tsvector('english', body)) STORED
+);
+```
+
+Create the index after the initial corpus has been inserted so build-time corpus statistics are meaningful. BM25 scoring is tuned by two storage parameters set at index-build time:
+
+- `k1` controls term-frequency saturation (default `1.2`, range `1.2`–`2.0`): higher values let repeated terms keep adding relevance.
+
+- `b` controls document-length normalization (default `0.75`, range `0.0`–`1.0`): higher values penalize longer documents more.
+
+Both can only be set in the `WITH` clause, and updating them rebuilds the index:
+
+```sql
+CREATE INDEX documents_body_bm25 ON documents
+  USING lakebase_bm25 (body_tsv)
+  WITH (k1 = 1.2, b = 0.75);
+```
+
+After a large bulk load, run `VACUUM` to refresh the statistics used by BM25 scoring.
+
+## Query and Interpret Scores
+
+`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
+ORDER BY score
+LIMIT $2;
+```
+
+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
+
+`lakebase_bm25.default_limit` controls how many rows the index returns before PostgreSQL applies the SQL `LIMIT`. Its default is `1000`; setting it close to the requested top-K avoids unnecessary scoring.
+
+## Use Prefilter Selectively
+
+Enable prefilter when a `WHERE` condition is strict or unpredictable and cheap to evaluate. It lets the index prune rows before BM25 scoring. A loose or expensive filter can be slower with prefilter enabled.
+
+```sql
+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
+ORDER BY score
+LIMIT $2;
+COMMIT;
+```
+
+## Set Parameters at Build Time or Per Query
+
+Several BM25 parameters can be set in two places. As an index storage parameter in the `CREATE INDEX` `WITH` clause, a value is fed into the index as its build-time default. As a session GUC via `SET` (or `SET LOCAL`), it applies per query and takes precedence over the stored default when both are present.
+
+- `default_limit` and `prefilter` exist in both forms: set an index default that fits the common case, then override it per query with a GUC without rebuilding.
+- `k1` (default `1.2`) and `b` (default `0.75`) are storage parameters only. There is no GUC for them.
+- `enable_scan` (default `on`) is a GUC only.
+
+The examples use `SET LOCAL` so each override is scoped to its own transaction, which is required behind a connection pool or stateless driver.
+
+Source: [`lakebase_text` documentation](https://neon.com/docs/extensions/lakebase-text).

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

@@ -0,0 +1,90 @@
+# Hybrid Search
+
+Use hybrid search when either semantic similarity or exact vocabulary can identify a relevant document. Lakebase Search does not provide a built-in hybrid function: run vector and BM25 retrieval separately, then combine their results with a fusion strategy suited to the workload.
+
+Lakebase Search requires Postgres 16 or later. Hybrid search uses both extensions:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
+CREATE EXTENSION IF NOT EXISTS lakebase_text;
+```
+
+`lakebase_vector` installs `pgvector` through `CASCADE`; `lakebase_text` has no extension dependency. Both rely on preloaded libraries that Neon enables by default. If the project customized its preloaded-library list, confirm both libraries remain enabled.
+
+Prepare a table with both vector and text-search columns:
+
+```sql
+CREATE TABLE documents (
+  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+  title text NOT NULL,
+  body text NOT NULL,
+  embedding vector(1536),
+  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.
+
+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.
+
+Reciprocal Rank Fusion (RRF) is the approach in the Lakebase Search get-started guide and a useful default because it combines ranks instead of incomparable raw distances and scores. It is not the only option: weighted rank fusion, normalized score fusion, or a reranker may fit applications with different relevance signals.
+
+## RRF Example
+
+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`:
+
+```sql
+WITH vector_ranked AS (
+  SELECT id, RANK() OVER (ORDER BY distance) AS rank
+  FROM (
+    SELECT id, embedding <=> $1::vector AS distance
+    FROM documents
+    ORDER BY distance
+    FETCH FIRST 40 ROWS WITH TIES
+  ) AS vector_candidates
+),
+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
+  ) AS keyword_candidates
+)
+SELECT
+  d.id,
+  d.title,
+  COALESCE(1.0 / (60 + v.rank), 0) +
+    COALESCE(1.0 / (60 + k.rank), 0) AS rrf_score
+FROM documents AS d
+LEFT JOIN vector_ranked AS v ON v.id = d.id
+LEFT JOIN keyword_ranked AS k ON k.id = d.id
+WHERE v.id IS NOT NULL OR k.id IS NOT NULL
+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.
+
+`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.
+
+## 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.
+- 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.
+- Apply the same access-control and tenant filters to both candidate CTEs. If BM25 filters are strict and cheap, evaluate whether `lakebase_bm25.prefilter` improves the filtered query.
+
+Source: [Lakebase Search get-started guide][lakebase-search-guide].
+
+[lakebase-search-guide]: https://neon.com/docs/ai/lakebase-search-get-started#combine-results-with-hybrid-search

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

@@ -0,0 +1,172 @@
+# Managing Lakebase Search with Drizzle
+
+When the user wants Lakebase Search managed through Drizzle, treat the SQL in [Vector Search](vector-search.md), [Full-Text Search](full-text-search.md), and [Hybrid Search](hybrid-search.md) as the source of truth and apply it as below. Use Drizzle for all schema and migration management unless the user says otherwise.
+
+Requires `drizzle-orm` 0.36+ and `drizzle-kit` 0.27+: the schema below returns its indexes as an array from the `pgTable` extra-config callback. Those versions also include generated-column support for the `tsvector` column, the custom-method `.using(...).op(...)` index API for `lakebase_ann`, the `vector` column type, and the `cosineDistance` helper.
+
+Contents:
+
+- [Config](#config): `drizzle.config.ts` and the migration connection
+- [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
+- [Query](#query): vector, BM25, and hybrid reads
+- [Tune Per Query](#tune-per-query): per-query GUCs
+
+Rules:
+
+- Express everything Drizzle can in `schema.ts`: the columns, the generated `tsvector`, and the `lakebase_ann` index. Only `CREATE EXTENSION` and the post-seed `lakebase_bm25` index need custom migrations.
+- Use `drizzle-kit generate` then `migrate`. Never run `drizzle-kit push` (it reconciles the database to `schema.ts`, so it drops the post-seed `lakebase_bm25` index and any other object not declared there)
+- Run every migration over the direct (unpooled) connection.
+- The extension must exist before the `vector` column and the `lakebase_ann` index that depend on it.
+
+## Config
+
+`drizzle-kit generate` and `migrate` read `drizzle.config.ts`. Point `dbCredentials.url` at the **direct (unpooled)** connection string:
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from "drizzle-kit";
+
+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 },
+});
+```
+
+## Extensions
+
+Drizzle cannot express `CREATE EXTENSION`, and the `vector` column and `lakebase_ann` index below depend on `lakebase_vector`, so generate a custom migration for the extensions **first** so it runs before the schema migration:
+
+```bash
+npx drizzle-kit generate --custom --name=lakebase_extensions
+```
+
+```sql
+-- drizzle/0000_lakebase_extensions.sql
+CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
+CREATE EXTENSION IF NOT EXISTS lakebase_text;
+```
+
+## Schema
+
+The columns, the generated `tsvector`, and the `lakebase_ann` index all go in `schema.ts`. `tsvector` has no built-in Drizzle type, so define it using the `customType`:
+
+```typescript
+// src/schema.ts
+import { pgTable, bigint, text, vector, index, customType } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+const tsvector = customType<{ data: string }>({
+  dataType() {
+    return "tsvector";
+  },
+});
+
+export const documents = pgTable(
+  "documents",
+  {
+    id: bigint("id", { mode: "number" }).generatedByDefaultAsIdentity().primaryKey(),
+    title: text("title").notNull(),
+    body: text("body").notNull(),
+    embedding: vector("embedding", { dimensions: 1536 }),
+    bodyTsv: tsvector("body_tsv").generatedAlwaysAs(
+      sql`to_tsvector('english', "body")`,
+    ),
+  },
+  (table) => [
+    index("documents_embedding_ann").using(
+      "lakebase_ann",
+      table.embedding.op("vector_cosine_ops"),
+    ),
+  ],
+);
+```
+
+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:
+
+```bash
+npx drizzle-kit generate --name=lakebase_search
+npx drizzle-kit migrate
+```
+
+## BM25 Index
+
+Keep the `lakebase_bm25` index out of `schema.ts`. It must be built only after the initial corpus is loaded, so its build-time statistics are meaningful (see [Full-text search](full-text-search.md)) — a schema migration would build it against an empty table. Add it in a later custom migration that runs after seeding:
+
+```bash
+npx drizzle-kit generate --custom --name=bm25_index
+```
+
+```sql
+-- drizzle/NNNN_bm25_index.sql, applied after the corpus is seeded
+CREATE INDEX documents_body_bm25 ON documents USING lakebase_bm25 (body_tsv);
+```
+
+## 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`:
+
+```typescript
+import { cosineDistance } from "drizzle-orm";
+import { documents } from "./schema";
+
+// queryEmbedding: number[] from the same model used for stored documents
+const distance = cosineDistance(documents.embedding, queryEmbedding);
+
+const rows = await db
+  .select({ id: documents.id, title: documents.title, distance })
+  .from(documents)
+  .orderBy(distance)
+  .limit(k);
+```
+
+BM25 has no Drizzle helper: `<@>` and `to_bm25query` require raw SQL. Reference the generated column by its `body_tsv` name. Bind user input as parameters through the `sql` template:
+
+```typescript
+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
+  ORDER BY score
+  LIMIT ${k}
+`);
+```
+
+Run the [hybrid search](hybrid-search.md) RRF query the same way: raw SQL through `db.execute`.
+
+## Tune Per Query
+
+Per-query GUCs (`lakebase_ann.probes`, `lakebase_ann.epsilon`, `lakebase_bm25.default_limit`, `lakebase_bm25.prefilter`) must be set with `SET LOCAL` inside a transaction so they apply to the same pooled connection as the query:
+
+```typescript
+import { cosineDistance, sql } from "drizzle-orm";
+import { documents } from "./schema";
+
+const distance = cosineDistance(documents.embedding, queryEmbedding);
+
+const rows = await db.transaction(async (tx) => {
+  // SET LOCAL scopes the GUC to this transaction's connection; do not hoist it out.
+  // Keep probes at 'auto' unless an IVF `lists` layout exists: a numeric value must
+  // match the `lists` shape or it errors ("need 0 probes ..."). See vector-search.md.
+  await tx.execute(sql`SET LOCAL lakebase_ann.probes = 'auto'`);
+  return tx
+    .select({ id: documents.id, title: documents.title, distance })
+    .from(documents)
+    .orderBy(distance)
+    .limit(k);
+});
+```
+
+Sources:
+
+- [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)