vybekiit 0.7.33 → 0.7.35

package/dist/global-skills/mongodb-search-and-ai/scripts/quickstart_complete.py

@@ -0,0 +1,386 @@
+#!/usr/bin/env python3
+# /// script
+# dependencies = [
+#   "pymongo>=4.6.0",
+# ]
+# ///
+
+# MongoDB Search Quickstart — Complete Script
+# ─────────────────────────────────────────────────────────────
+# Written for the Atlas `sample_mflix.movies` sample collection. The
+# schema is hard-coded throughout: the `plot`, `genres`, and `title`
+# fields, the index definitions, and the sample query text.
+#
+# The connection string comes from the environment: set MONGODB_URI, or
+# MDB_MCP_CONNECTION_STRING, which the MongoDB MCP server already uses.
+#
+# To run against your own data, change the two values below AND
+# update the index definitions, `$project` stages, and query strings
+# to match your own field names.
+
+DB_NAME = "sample_mflix"
+COLLECTION_NAME = "movies"
+
+# Index names. The walkthrough uses these defaults, but creates `<name>_2` when
+# the default is already taken by an incompatible definition. If that happened,
+# set the matching constant to the name it created, so this script reuses that
+# index instead of stopping on the conflicting one.
+SEMANTIC_INDEX_NAME = "quickstart_semantic"
+TEXT_INDEX_NAME = "quickstart_text"
+AUTOCOMPLETE_INDEX_NAME = "quickstart_autocomplete"
+
+INDEX_WAIT_TIMEOUT_SECONDS = 600
+
+# ─────────────────────────────────────────────────────────────
+
+import os
+import time
+from pymongo import MongoClient
+from pymongo.operations import SearchIndexModel
+
+CONNECTION_STRING = (os.environ.get("MONGODB_URI")
+                     or os.environ.get("MDB_MCP_CONNECTION_STRING"))
+
+if not CONNECTION_STRING:
+    raise SystemExit("\n  ERROR: no connection string. Set MONGODB_URI (or"
+                     " MDB_MCP_CONNECTION_STRING) to your cluster's SRV"
+                     " string, then rerun.")
+
+client = MongoClient(CONNECTION_STRING)
+db = client[DB_NAME]
+collection = db[COLLECTION_NAME]
+
+def fail(message):
+    print(f"\n  ERROR: {message}")
+    client.close()
+    raise SystemExit(1)
+
+def wait_for_index(name):
+    print(f"  Waiting for index '{name}' to be ready...", end="", flush=True)
+    deadline = time.monotonic() + INDEX_WAIT_TIMEOUT_SECONDS
+    while True:
+        indexes = list(collection.list_search_indexes(name))
+        if not indexes:
+            fail(f"Index '{name}' does not exist.")
+        status = indexes[0].get("status")
+        if status == "READY":
+            print(" ready.")
+            return
+        if status == "STALE":
+            fail(f"Index '{name}' is stale because embedding sync is paused. "
+                 "Free disk space, wait for READY, then rerun.")
+        if status == "FAILED":
+            fail(f"Index '{name}' failed to build. Check the tier index cap"
+                 " (3 on Free, 10 on Flex) and the index definition.")
+        if time.monotonic() > deadline:
+            fail(f"Index '{name}' is still '{status}' after"
+                 f" {INDEX_WAIT_TIMEOUT_SECONDS}s. Check its status in Atlas,"
+                 " then rerun.")
+        print(".", end="", flush=True)
+        time.sleep(5)
+
+def covers(expected, actual):
+    # True when `actual` contains everything `expected` asks for. Atlas adds
+    # its own defaults to a stored definition, so an exact match is too strict.
+    if isinstance(expected, dict):
+        # A field can be stored as a list of types (a multi-type field), which
+        # still satisfies a single expected type.
+        if isinstance(actual, list):
+            return any(covers(expected, candidate) for candidate in actual)
+        return (isinstance(actual, dict)
+                and all(k in actual and covers(v, actual[k])
+                        for k, v in expected.items()))
+    if isinstance(expected, list):
+        return (isinstance(actual, list)
+                and all(any(covers(item, candidate) for candidate in actual)
+                        for item in expected))
+    return expected == actual
+
+def check_definition(name, expected):
+    indexes = list(collection.list_search_indexes(name))
+    if not indexes:
+        fail(f"Index '{name}' does not exist.")
+    actual = indexes[0].get("latestDefinition", {})
+    if not covers(expected, actual):
+        fail(f"An index named '{name}' already exists, but its definition does"
+             " not match the one this script needs, so the queries below would"
+             " fail. An index created by another route (for example the MCP"
+             " walkthrough) can omit fields this script queries. Drop"
+             f" '{name}' in Atlas and rerun, or point the matching"
+             " *_INDEX_NAME constant at the top of this script at a name that"
+             f" is free or already correct.\n  Existing definition: {actual}")
+
+def ensure_index(model, name, definition):
+    try:
+        collection.create_search_index(model)
+    except Exception as e:
+        if "already exists" not in str(e):
+            fail(f"Could not create index '{name}': {e}")
+        print("  Index already exists — checking its definition.")
+        check_definition(name, definition)
+    wait_for_index(name)
+
+def print_results(results, fields=["title", "plot"]):
+    for i, doc in enumerate(results, 1):
+        print(f"\n  {i}. {doc.get('title', 'N/A')}")
+        if "score" in doc:
+            print(f"     Score: {round(doc['score'], 3)}")
+        if "plot" in fields and doc.get("plot"):
+            print(f"     Plot:  {doc['plot'][:120]}...")
+        if "genres" in doc:
+            print(f"     Genres: {doc.get('genres', [])}")
+
+# ─────────────────────────────────────────────────────────────
+# 1. CREATE AUTO EMBEDDING INDEX (Semantic Search)
+# ─────────────────────────────────────────────────────────────
+print("\n── SEMANTIC SEARCH (Auto Embedding) ──────────────────")
+print("Creating autoEmbed index on 'plot' field...")
+
+semantic_definition = {
+    "fields": [
+        {
+            "type": "autoEmbed",
+            "modality": "text",
+            "path": "plot",
+            "model": "voyage-4"
+        },
+        {
+            "type": "filter",
+            "path": "genres"
+        }
+    ]
+}
+
+ensure_index(
+    SearchIndexModel(
+        definition=semantic_definition,
+        name=SEMANTIC_INDEX_NAME,
+        type="vectorSearch"
+    ),
+    SEMANTIC_INDEX_NAME,
+    semantic_definition
+)
+
+# Run semantic query
+print("\nQuery: 'a story about growing up'")
+results = list(collection.aggregate([
+    {
+        "$vectorSearch": {
+            "index": SEMANTIC_INDEX_NAME,
+            "path": "plot",
+            "query": "a story about growing up",
+            "numCandidates": 100,
+            "limit": 3
+        }
+    },
+    {
+        "$project": {
+            "_id": 0,
+            "title": 1,
+            "plot": 1,
+            "score": { "$meta": "vectorSearchScore" }
+        }
+    }
+]))
+print_results(results)
+
+# Run filtered semantic query
+print("\nFiltered query: 'a story about growing up' + Drama only")
+results = list(collection.aggregate([
+    {
+        "$vectorSearch": {
+            "index": SEMANTIC_INDEX_NAME,
+            "path": "plot",
+            "query": "a story about growing up",
+            "filter": { "genres": { "$eq": "Drama" } },
+            "numCandidates": 150,
+            "limit": 3
+        }
+    },
+    {
+        "$project": {
+            "_id": 0,
+            "title": 1,
+            "genres": 1,
+            "score": { "$meta": "vectorSearchScore" }
+        }
+    }
+]))
+print_results(results, fields=["title", "genres"])
+
+# ─────────────────────────────────────────────────────────────
+# 2. CREATE TEXT SEARCH INDEX (Keyword Search)
+# ─────────────────────────────────────────────────────────────
+print("\n── KEYWORD SEARCH (Atlas Search) ─────────────────────")
+print("Creating text search index on 'title', 'plot', 'genres'...")
+
+text_definition = {
+    "mappings": {
+        "dynamic": False,
+        "fields": {
+            "title": { "type": "string" },
+            "plot": { "type": "string" },
+            "genres": { "type": "token" }
+        }
+    }
+}
+
+ensure_index(
+    SearchIndexModel(
+        definition=text_definition,
+        name=TEXT_INDEX_NAME
+    ),
+    TEXT_INDEX_NAME,
+    text_definition
+)
+
+# Run keyword query
+print("\nKeyword query: 'space adventure'")
+results = list(collection.aggregate([
+    {
+        "$search": {
+            "index": TEXT_INDEX_NAME,
+            "text": {
+                "query": "space adventure",
+                "path": ["title", "plot"]
+            }
+        }
+    },
+    {
+        "$project": {
+            "_id": 0,
+            "title": 1,
+            "plot": 1,
+            "score": { "$meta": "searchScore" }
+        }
+    },
+    { "$limit": 3 }
+]))
+print_results(results)
+
+# Run fuzzy query
+print("\nFuzzy query: 'sapce adventre' (intentional typos)")
+results = list(collection.aggregate([
+    {
+        "$search": {
+            "index": TEXT_INDEX_NAME,
+            "text": {
+                "query": "sapce adventre",
+                "path": ["title", "plot"],
+                "fuzzy": { "maxEdits": 1 }
+            }
+        }
+    },
+    {
+        "$project": {
+            "_id": 0,
+            "title": 1,
+            "score": { "$meta": "searchScore" }
+        }
+    },
+    { "$limit": 3 }
+]))
+print_results(results, fields=["title"])
+
+# Autocomplete needs 'title' typed as autocomplete, which the text index does
+# not provide. Use a dedicated index, matching the walkthrough's MCP route.
+print("\nCreating autocomplete index on 'title'...")
+
+autocomplete_definition = {
+    "mappings": {
+        "dynamic": False,
+        "fields": {
+            "title": { "type": "autocomplete", "tokenization": "edgeGram" }
+        }
+    }
+}
+
+ensure_index(
+    SearchIndexModel(
+        definition=autocomplete_definition,
+        name=AUTOCOMPLETE_INDEX_NAME
+    ),
+    AUTOCOMPLETE_INDEX_NAME,
+    autocomplete_definition
+)
+
+# Run autocomplete
+print("\nAutocomplete query: 'inc'")
+results = list(collection.aggregate([
+    {
+        "$search": {
+            "index": AUTOCOMPLETE_INDEX_NAME,
+            "autocomplete": { "query": "inc", "path": "title" }
+        }
+    },
+    { "$project": { "_id": 0, "title": 1 } },
+    { "$limit": 5 }
+]))
+for doc in results:
+    print(f"  - {doc['title']}")
+
+# ─────────────────────────────────────────────────────────────
+# 3. HYBRID SEARCH ($rankFusion)
+# ─────────────────────────────────────────────────────────────
+print("\n── HYBRID SEARCH ($rankFusion) ───────────────────────")
+print("Query: 'a story about growing up' (semantic 70% + keyword 30%)")
+
+try:
+    results = list(collection.aggregate([
+        {
+            "$rankFusion": {
+                "input": {
+                    "pipelines": {
+                        "semanticPipeline": [
+                            {
+                                "$vectorSearch": {
+                                    "index": SEMANTIC_INDEX_NAME,
+                                    "path": "plot",
+                                    "query": "a story about growing up",
+                                    "numCandidates": 100,
+                                    "limit": 20
+                                }
+                            }
+                        ],
+                        "keywordPipeline": [
+                            {
+                                "$search": {
+                                    "index": TEXT_INDEX_NAME,
+                                    "text": {
+                                        "query": "coming of age",
+                                        "path": "plot"
+                                    }
+                                }
+                            },
+                            { "$limit": 20 }
+                        ]
+                    }
+                },
+                "combination": {
+                    "weights": {
+                        "semanticPipeline": 0.7,
+                        "keywordPipeline": 0.3
+                    }
+                }
+            }
+        },
+        { "$project": { "_id": 0, "title": 1, "plot": 1 } },
+        { "$limit": 5 }
+    ]))
+    print_results(results)
+except Exception as e:
+    message = str(e)
+    if "Unrecognized pipeline stage name: '$rankFusion'" in message:
+        print("  $rankFusion requires MongoDB 8.0+. This cluster does not"
+              " support it, so hybrid search was skipped.")
+    else:
+        fail(f"Hybrid search query failed: {message}")
+
+print("\n── Done! ─────────────────────────────────────────────")
+print("This script targets the sample_mflix.movies schema. To use your")
+print("own data, set MONGODB_URI (or MDB_MCP_CONNECTION_STRING), then")
+print("change DB_NAME and COLLECTION_NAME at the top and adjust the")
+print("index definitions, $project stages, and query strings to match")
+print("your own field names.")
+
+client.close()

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

@@ -2,16 +2,17 @@
 name: neon
 description: >-
   Overview of Neon, a complete set of cloud backend primitives around Lakebase
-  Postgres: Auth, Object Storage, Functions, and the AI Gateway. Start here to
+  Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to
   choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or
   MCP server, and follow the branch-first workflow. Use when building an app or
   backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child
   skill neon-postgres wins for an existing DATABASE_URL, SQL, schema, inspect,
   or search. Child skill neon-auth wins for login, users, sessions, identity
-  routing, and Managed Better Auth setup. Also use for object storage, S3, buckets, serverless functions,
-  function triggers, cron, AI gateway, LLM calls, logs, Loki, Grafana,
-  observability, postgres, database, backend, Claimable Neon, neon.new, or a
-  no-signup database.
+  routing, and Managed Better Auth setup. Child skill neon-realtime wins for
+  live queries in reactive apps and agents. Also use for object storage, S3,
+  buckets, serverless functions, function triggers, cron, AI gateway, LLM calls,
+  realtime, logs, Loki, Grafana, observability,
+  postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.
 metadata:
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon
 disable-model-invocation: true
@@ -19,7 +20,7 @@ disable-model-invocation: true
 
 # Neon
 
-Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless.
+Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, an AI Gateway, and Realtime live queries, all instant, branchable, and serverless.
 
 **Lakebase Postgres** is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use "Neon" for the brand and for this access path — not as a name for the database.
 
@@ -36,11 +37,12 @@ Neon bundles several backend primitives for building apps and agents that all br
 - **Object Storage** — S3-compatible object storage that branches with your projects.
 - **Functions** — Neon's compute offering: long-running serverless functions that run close to your database, for WebSocket servers, long agent HTTP streams, APIs, and server-sent event servers. A Function Trigger POSTs to a function on a cron.
 - **AI Gateway** — One API for frontier and open-source models, supporting the chat completions API and the responses API, powered by Databricks Unity AI Gateway.
+- **Realtime** (beta) — Makes any SQL query live. Subscribe in realtime to Lakebase Postgres and build reactive apps and agents with type-safe live queries and optimistic mutations.
 - **Data API** — Optional PostgREST-compatible HTTP interface. Use it only when the app already uses PostgREST or a Supabase database client, or is migrating that client. New apps query Postgres from Functions or existing handlers. There is no `neon-data-api` skill; configuration is `dataApi` in `neon.ts` (see [Type-safe config](#type-safe-config-invalid-setups-dont-compile) when you have chosen it).
 
 ### Region availability
 
-Object Storage, Functions, and AI Gateway are currently available on projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.
+Object Storage, Functions, AI Gateway, and Realtime are currently available on projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Before guiding a user through any of these services, confirm they are working in one of these regions. If not, they will need to create a new project in a supported region.
 
 ## Architecture: How to Use Neon
 
@@ -64,7 +66,7 @@ Functions have public HTTPS URLs. Verify a JWT or API key at the top of the hand
 
 Inspect the repo before provisioning.
 
-1. Map requested capabilities: login, files, HTTP APIs, LLM calls, SQL.
+1. Map requested capabilities: login, files, HTTP APIs, LLM calls, live data, SQL.
 2. Reuse what is already there: a supplied `DATABASE_URL`, an existing ORM or driver, Better Auth, Clerk or another auth provider, S3 or another object store, an existing `.neon` / `neon.ts`, an existing Data API or PostgREST client.
 3. Select Neon primitives for capabilities that are still undecided.
 4. Provision only when infrastructure is missing: `neon init` / `neon link` / Claimable, then `neon.ts`, then `neon deploy`.
@@ -82,7 +84,8 @@ New projects are created in AWS regions. Prefer pooled `DATABASE_URL` for applic
 | Existing Better Auth, Clerk, Supabase Auth, or another working IdP | Keep it. `neon-auth` only if they ask to migrate |
 | User asked to migrate from Supabase Auth | `neon-auth` (Managed Better Auth; keep `SupabaseAuthAdapter()` call shapes) |
 | Files, uploads, blobs (no existing object store) | Object Storage |
-| HTTP APIs, cron, WebSocket, SSE, long-running agents | Functions querying Postgres |
+| HTTP APIs, cron, custom WebSocket or SSE push, long-running agents | Functions querying Postgres |
+| Live queries for realtime, reactive apps and agents; optimistic mutations | `neon-realtime` (`preview.realtime` in `neon.ts`). Not available on Claimable projects until claimed |
 | LLM calls | AI Gateway |
 | SQL, schema, inspect, search | `neon-postgres` |
 | Existing PostgREST / Supabase database client | Data API (`dataApi` in `neon.ts`) |
@@ -125,6 +128,7 @@ The skills below live in the [`neondatabase/agent-skills`](https://github.com/ne
 | `neon-object-storage`            | Storing and serving files (uploads, images, blobs), including branching them with the database.                                                                                      |
 | `neon-functions`                 | Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers, and Function Triggers (cron and object-storage).                                     |
 | `neon-ai-gateway`                | Calling an LLM or routing across model providers with one credential, including discovering the branch's servable models at runtime via the OpenAI-compatible `/v1/models` endpoint. |
+| `neon-realtime`                  | Realtime makes any SQL query live, for realtime, reactive apps and agents: enabling Realtime, sealing queries, React and TanStack DB bindings, SSR, and optimistic mutations.      |
 | `neon-postgres-egress-optimizer` | Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase.                                                                                          |
 
 There is no `neon-data-api` skill. Configure `dataApi` in `neon.ts` only for PostgREST / Supabase database-client compatibility or a migration that already depends on it.
@@ -328,7 +332,7 @@ export default defineConfig({
 
 ### Provision services with neon config
 
-Every project ships with Lakebase Postgres; `neon.ts` also declares Auth, Functions, buckets, and the AI Gateway. Data API is a compatibility toggle, not part of a default backend:
+Every project ships with Lakebase Postgres; `neon.ts` also declares Auth, Functions, buckets, and the AI Gateway. Realtime is declared under `preview`. Data API is a compatibility toggle, not part of a default backend:
 
 ```typescript
 // neon.ts
@@ -337,6 +341,7 @@ export default defineConfig({
   functions: {},
   buckets: {},
   aiGateway: true, // see the neon-ai-gateway skill
+  preview: { realtime: true }, // see the neon-realtime skill
 });
 ```
 

package/dist/global-skills/neon/references/claimable-neon.md

@@ -38,6 +38,8 @@ export default defineConfig({
 neon claim create --service auth --service data-api --env-pull
 ```
 
+The project is created in `aws-us-east-2` unless you pass `--region-id` (for example `neon claim create --region-id aws-eu-central-1`). Pick the region closest to where the app runs. A project's region cannot change after create.
+
 `neon claim create` reads `neon.ts` when it is present. It writes provisioned vars to an existing `.env`, otherwise `.env.local`, and gitignores that file. If `.env` or `.env.local` already has a `DATABASE_URL` (or other Neon-managed keys), pass `--file <path>` or `--no-env-pull`. The identity assertion is the pre-claim credential.
 
 Before claim, Postgres is always granted; Auth and the Data API are granted when requested. Functions, Object Storage, and AI Gateway come back with `granted: false` and `reason: "requires_claim"`. The CLI prints those as `denied_capabilities`. Report what you were given. Do not retry or strip them.

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

@@ -11,11 +11,10 @@ description: >-
   a cron or an object-storage event that POSTs to a function. Triggers include
   "serverless function", "deploy an API", "long-running function",
   "streaming agent", "SSE server", "WebSocket server", "webhook handler",
-  "MCP server", "cron", "function trigger", "scheduled function", "cron job",
-  "object storage trigger", "on upload", "run code next to my database",
-  "function that won't time out", "function logs", "Neon Functions",
-  "Neon Compute", "DDoS protection", "rate limiting", and
-  "production hardening".
+  "MCP server", "cron", "scheduled function", "object storage trigger",
+  "on upload", "function that won't time out", "function logs",
+  "Neon Functions", "Neon Compute", "DDoS protection", "rate limiting", and
+  "production hardening". For live UIs over database rows, use neon-realtime.
 metadata:
   parent: neon
   source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-functions
@@ -453,13 +452,15 @@ beat.unref?.();
 
 The client skips these when handling messages. There is no protocol-level shortcut here: the standard `WebSocket` from `upgradeWebSocket` has no `ping()`, and a browser can't send ping frames from JavaScript, so an application-level message is the only keepalive a browser client can use. (A Node `ws` client can send ping frames, and the server auto-replies with a pong, but a browser can't.)
 
-### Keeping clients in sync across isolates (do not skip this)
+### Fan-out across isolates (do not skip this)
 
 Under load the runtime runs **several isolates in parallel, each with its own copy of module state** — so each isolate has its own `clients` set. Broadcasting only to that local set means a client on isolate A never sees an event produced on isolate B, and the feed silently fractures. It's easy to miss: `neon dev` runs a single process (one isolate), so in-process broadcast always _looks_ fine locally but breaks in production, where concurrent connections spread across many isolates.
 
+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. Using Realtime does not prevent your database from scaling to zero. The strategies below are for push that doesn't come from database rows (presence, typing, LLM streams), and the fallback where Realtime isn't available, such as on Claimable projects until they're claimed.
+
 Module state doesn't survive eviction anyway, so **Postgres is the shared source of truth**. Pick a fan-out strategy. In every snippet below, `pool` is a pooled `pg` client and `clients` is this isolate's `Set` of live connections.
 
-**1. Poll Postgres — the default, and the only option that keeps Scale to Zero.** Each isolate re-reads the shared state (or rows past a cursor) on a short interval and pushes changes to its own clients. One query per isolate per tick (not per client), and none when the isolate has no clients — so an idle compute still suspends.
+**1. Poll Postgres — the default, and it keeps Scale to Zero.** Each isolate re-reads the shared state (or rows past a cursor) on a short interval and pushes changes to its own clients. One query per isolate per tick (not per client), and none when the isolate has no clients — so an idle compute still suspends.
 
 ```typescript
 let lastId = "0"; // bigint id, so a string
@@ -496,7 +497,7 @@ pool
   .finally(() => setInterval(poll, 1000).unref?.());
 ```
 
-- **Latency:** up to the interval (~1s) — fine for counters, chat, and dashboards.
+- **Latency:** up to the interval (~1s).
 - **Scaling:** database load grows with the number of live isolates, not clients. Keep the cursor on an indexed `serial`/`bigserial` PK and the interval sane.
 - **Scale to Zero:** ✅ preserved — polling stops when no clients are connected, so the compute suspends on its normal timer.
 - **Ordering:** `WHERE id > cursor` can skip a row that commits out of sequence: a transaction that took a lower id but commits after a higher one is already behind the cursor, so the poll never returns it. For a broadcast feed occasional loss is usually fine; when you need every row, use `LISTEN`/`NOTIFY` or poll by `created_at` with a small overlap window and dedupe by id.
@@ -540,7 +541,7 @@ function broadcast(event: unknown) {
 
 **3. External pub/sub (e.g. [Upstash](https://upstash.com) Redis) — best at scale.** For high fan-out, sub-second latency at large connection counts, or multi-region, publish/subscribe through a dedicated broker. Highest throughput, and it doesn't touch Postgres or block Scale to Zero — at the cost of another service to run.
 
-**Rule of thumb:** start with **polling** (works with Scale to Zero, no extra infra); switch to `LISTEN`/`NOTIFY` only on always-on compute that needs sub-second latency; move to Redis when fan-out outgrows Postgres.
+**Rule of thumb:** for database rows, use **Neon Realtime**. Otherwise start with **polling** (works with Scale to Zero, no extra infra); switch to `LISTEN`/`NOTIFY` only on always-on compute that needs sub-second latency; move to Redis when fan-out outgrows Postgres.
 
 ### Client must reconnect
 
@@ -570,7 +571,7 @@ async function connect() {
 connect();
 ```
 
-Together — `upgradeWebSocket` inside `fetch`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete realtime chat backend on a single function.
+Together — `upgradeWebSocket` inside `fetch`, JWT auth over `?token=`, cross-isolate fan-out, and client backoff — these compose into a complete WebSocket 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).
 
 ## Server-Sent Events (SSE)
 
@@ -606,7 +607,7 @@ export default {
 };
 ```
 
-The same rules as WebSockets apply. **Heartbeat:** a stream stays open only while bytes flow — Neon's window is 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)) but proxies are usually far stricter, so emit a `: ping\n\n` comment every ~25–30s (shown above) to keep idle streams from being dropped. Keep state in Postgres, and fan out across isolates using one of the [sync strategies](#keeping-clients-in-sync-across-isolates-do-not-skip-this) (hold a `Set` of stream controllers and `enqueue` to each). `EventSource` is GET-only and can't set headers, so authenticate with a `?token=` query param or cookie, exactly like the WebSocket case. [references/sse.md](https://neon.com/docs/ai/skills/neon-functions/references/sse.md) has the full pattern — Hono variant, cross-isolate fan-out, wire format, client, and caveats.
+The same rules as WebSockets apply. **Heartbeat:** a stream stays open only while bytes flow — Neon's window is 15 minutes ([Timeouts and Runtime Limits](#timeouts-and-runtime-limits)) but proxies are usually far stricter, so emit a `: ping\n\n` comment every ~25–30s (shown above) to keep idle streams from being dropped. Keep state in Postgres, and fan out across isolates using one of the [fan-out strategies](#fan-out-across-isolates-do-not-skip-this) (hold a `Set` of stream controllers and `enqueue` to each). `EventSource` is GET-only and can't set headers, so authenticate with a `?token=` query param or cookie, exactly like the WebSocket case. [references/sse.md](https://neon.com/docs/ai/skills/neon-functions/references/sse.md) has the full pattern — Hono variant, cross-isolate fan-out, wire format, client, and caveats.
 
 ## Function Triggers
 

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