vybekiit 0.6.1 → 0.7.0

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

@@ -16,7 +16,7 @@ description: >-
 
 # Neon AI Gateway
 
-This is a preview feature and only available in `us-east-2`. The Neon AI Gateway is the LLM inference layer built into your Neon branch: one API and one Neon credential give you access to frontier and open-source models from Anthropic, OpenAI, Google, Meta, Alibaba, DeepSeek, and Databricks — powered by Databricks. Your existing OpenAI/Anthropic/Gemini SDK works by changing only the base URL.
+This is a public beta feature and only available in `us-east-2`. The Neon AI Gateway is the LLM inference layer built into your Neon branch: one API and one Neon credential give you access to frontier and open-source models from Anthropic, OpenAI, Google, Meta, Alibaba, DeepSeek, and Databricks — powered by Databricks. Your existing OpenAI/Anthropic/Gemini SDK works by changing only the base URL.
 
 Use this skill to help the user send model calls through the gateway, wire it into the AI SDK or Mastra, and switch providers without rewiring code. Deliver a working inference request, a configured agent, or a precise answer from the official Neon docs.
 
@@ -215,9 +215,75 @@ Use a model's catalog ID directly in the `model` field — e.g. `claude-sonnet-4
 - **models.dev Neon provider page: https://models.dev/providers/neon** — the canonical, always-current list of the Neon provider's model IDs and their underlying models. The machine-readable catalog is at https://models.dev/api.json (the `neon` key).
 - **Models doc:** see Further reading.
 
+## List available models at runtime (`/v1/models`)
+
+The gateway also exposes the model catalog **live from your own branch endpoint**, so an app or agent can discover exactly which models this branch serves without hard-coding the list. It is an OpenAI-compatible list endpoint, served **only on the unified dialect** (`/v1`):
+
+```bash
+curl "$NEON_AI_GATEWAY_BASE_URL/v1/models" \
+  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"
+```
+
+- `GET ${NEON_AI_GATEWAY_BASE_URL}/v1/models` → **200**
+- `GET ${NEON_AI_GATEWAY_BASE_URL}/openai/v1/models` → **404** (not served on the Responses dialect — use `/v1`)
+
+**Getting the credentials for the request.** Both values come from the same branch-scoped Neon credential the gateway uses everywhere else — you never manage a provider key:
+
+- **Provision via `neon.ts` (recommended).** Enable `preview.aiGateway` in `neon.ts` and run `neon deploy` (or `neon config apply`). Provisioning, `neon link`, and `neon checkout` pull `NEON_AI_GATEWAY_TOKEN` + `NEON_AI_GATEWAY_BASE_URL` into your local `.env.local`; inside a deployed Neon Function they're injected automatically. See **Setup** and **Environment variables** above.
+- **Pull into the environment via CLI.** On a branch that already has the gateway enabled, `neon env pull` writes the two vars to `.env`/`.env.local`, or `neon-env run -- <cmd>` injects them at runtime without a file.
+- **Provision via the Console UI.** Enable the AI Gateway on the branch in the Neon Console and copy the branch's gateway base URL and a Neon credential (token) from the project's connection/credentials view.
+
+Any Neon credential (`nt_live_...`) valid for the branch works as the bearer token; `NEON_AI_GATEWAY_BASE_URL` is the bare branch host (no path).
+
+**Response shape** — OpenAI/OpenRouter-compatible list:
+
+```jsonc
+{
+  "object": "list",
+  "data": [
+    {
+      "id": "claude-sonnet-4-6",              // catalog model ID — use directly in the `model` field
+      "canonical_slug": "claude-sonnet-4-6",
+      "name": "Claude Sonnet 4.6",            // human-readable display name
+      "object": "model",
+      "owned_by": "anthropic",                // anthropic | openai | google | meta | alibaba | databricks
+      "created": 0,
+      "enabled": true,
+      "context_length": null,
+      "architecture": {
+        "modality": "text->text",
+        "input_modalities": ["text"],
+        "output_modalities": ["text"],
+        "tokenizer": "Claude",                // Claude | Gemini | GPT | "" (empty for open-source)
+        "instruct_type": null
+      },
+      "top_provider": {
+        "is_moderated": false,
+        "context_length": null,
+        "max_completion_tokens": null
+      },
+      "pricing": null,
+      "per_request_limits": null
+    }
+    // ... one entry per model in the branch's catalog
+  ]
+}
+```
+
+> Note: `context_length`, `pricing`, and `per_request_limits` are currently `null` and `created` is `0` for every entry — for context windows, pricing, and capabilities use the models.dev catalog above. Use `/v1/models` when you need the live, branch-scoped list of servable model IDs (e.g. to populate a model picker or validate a `model` before a request).
+
 ## Availability
 
-The AI Gateway is a preview (early access) feature available only on new projects in the `us-east-2` region; it can't be enabled on existing projects. Foundation model access requires a paid Neon plan. Confirm the user's project is a new project in `us-east-2`. If the user does not yet have access, point them to the private beta sign-up: https://neon.com/blog/were-building-backends#access
+The AI Gateway is a public beta feature available only on new projects in the `us-east-2` region; it can't be enabled on existing projects. Foundation model access requires a paid Neon plan. Confirm the user's project is a new project in `us-east-2`.
+
+### Enabling the gateway: plan and model-catalog gating
+
+The AI Gateway is credential-gated rather than a provisioning step, but two plan/beta limits gate it — one blocks provisioning, the other only trims the catalog — and the CLI surfaces each:
+
+- **Free plan → provisioning is blocked.** `neon config apply` / `deploy` and `neon checkout` **refuse** to enable the gateway on a Free plan (the gateway can't serve requests there), with a friendly "upgrade to a paid plan, or remove `preview.aiGateway`" error. A dry-run `neon config plan` and `neon env pull` don't provision, so they only **warn**. So: to use the gateway the project's account must be on a paid Neon plan.
+- **Paid plan with a reduced model catalog.** On a paid plan the gateway provisions and serves, but during the beta an account can start with a trimmed catalog — some flagship models (e.g. Anthropic Opus, OpenAI Codex / `*-pro`) are missing from `GET /v1/models`. This is expected; `neon env pull` (and the env pull bundled into `apply` / `deploy` / `checkout`) warns and links the user to their branch's AI Gateway page in the Neon Console (`https://console.neon.tech/app/projects/<project-id>/branches/<branch-id>/ai-gateway`) to request access to more models. Verify what's actually available for the branch by reading `/v1/models` (see the models section above) rather than assuming the full catalog.
+
+When helping a user debug "the gateway isn't working" or "a model is missing", use `/v1/models` plus the account's plan to distinguish these two cases — a Free plan blocks provisioning entirely, while a reduced catalog on a paid plan just needs a model-access request.
 
 ## Neon Documentation
 

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

@@ -15,7 +15,7 @@ description: >-
 
 # Neon Functions
 
-This is a preview feature and only available in `us-east-2`. Neon Functions are long-running Node.js HTTP handlers deployed onto a Neon branch. Each function gets a public HTTPS URL, runs in the same region as your database, and — if the branch has Postgres — gets `DATABASE_URL` injected automatically. You deploy and manage them through the same Neon CLI, `neon.ts`, and API you already use.
+This is a public beta feature and only available in `us-east-2`. Neon Functions are long-running Node.js HTTP handlers deployed onto a Neon branch. Each function gets a public HTTPS URL, runs in the same region as your database, and — if the branch has Postgres — gets `DATABASE_URL` injected automatically. You deploy and manage them through the same Neon CLI, `neon.ts`, and API you already use.
 
 Use this skill to help the user define, run locally, deploy, and manage functions next to their database. Deliver a deployed function with its invocation URL, a working local `neon dev` loop, or a precise answer from the official Neon docs.
 
@@ -247,7 +247,7 @@ export default {
 
 **Hono variant.** If you only need Hono for the HTTP side and are happy driving `ws` yourself, just swap `fetch` in the simple example for `app.fetch` and keep the raw `upgrade` — Hono serves routing/middleware, `ws` serves the socket.
 
-To instead declare WebSocket routes _inside_ the Hono app — `app.get("/ws", upgradeWebSocket(...))` with the standard `onOpen`/`onMessage`/`onClose` lifecycle — you need an adapter that bridges Hono's `upgradeWebSocket()` helper to Neon's `upgrade(req, socket, head)`. Hono ships adapters for Cloudflare/Deno/Bun/Node, but **none for Neon**, and the Node one (`@hono/node-ws`) is deprecated and assumes it owns the HTTP server. [references/hono-websockets.md](references/hono-websockets.md) has a small self-contained `createNeonWebSocket(app)` adapter to copy in — it depends only on `hono` and `ws` (no deprecated package; adapted from `@hono/node-ws`, MIT) and returns a ready-to-export `{ fetch, upgrade }` handler. Usage is idiomatic Hono, and because the handshake routes through `app.request`, **auth is just normal route middleware**:
+To instead declare WebSocket routes _inside_ the Hono app — `app.get("/ws", upgradeWebSocket(...))` with the standard `onOpen`/`onMessage`/`onClose` lifecycle — you need an adapter that bridges Hono's `upgradeWebSocket()` helper to Neon's `upgrade(req, socket, head)`. Hono ships adapters for Cloudflare/Deno/Bun/Node, but **none for Neon**, and the Node one (`@hono/node-ws`) is deprecated and assumes it owns the HTTP server. [references/hono-websockets.md](https://neon.com/docs/ai/skills/neon-functions/references/hono-websockets.md) has a small self-contained `createNeonWebSocket(app)` adapter to copy in — it depends only on `hono` and `ws` (no deprecated package; adapted from `@hono/node-ws`, MIT) and returns a ready-to-export `{ fetch, upgrade }` handler. Usage is idiomatic Hono, and because the handshake routes through `app.request`, **auth is just normal route middleware**:
 
 ```typescript
 // src/index.ts
@@ -390,7 +390,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](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 [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.
 
 ## MCP servers
 
@@ -404,11 +404,11 @@ app.all("/mcp", async (c) => {
 });
 ```
 
-Because the function's URL is public, **authenticate before connecting the transport** — [Better Auth](https://better-auth.com) covers both OAuth (its MCP plugin makes your app the authorization server so third-party clients self-authorize per the MCP spec) and a simpler API-key / session-JWT check for your own callers. [references/mcp.md](references/mcp.md) has the full pattern — server with Postgres-backed tools via Drizzle, both Better Auth auth options, and testing with `mcporter` / `add-mcp`.
+Because the function's URL is public, **authenticate before connecting the transport** — [Better Auth](https://better-auth.com) covers both OAuth (its MCP plugin makes your app the authorization server so third-party clients self-authorize per the MCP spec) and a simpler API-key / session-JWT check for your own callers. [references/mcp.md](https://neon.com/docs/ai/skills/neon-functions/references/mcp.md) has the full pattern — server with Postgres-backed tools via Drizzle, both Better Auth auth options, and testing with `mcporter` / `add-mcp`.
 
 ## Integrations and observability
 
-A function is a long-lived Node.js process running a web-standard request/response handler, so standard Node integration SDKs work unchanged — initialize them once at module load, gated on an env var so local dev and unconfigured branches stay a no-op, and pass secrets via `--env` or `neon.ts` `env`. For wiring up **Sentry** error monitoring across the HTTP framework, the function runtime, and an agent's own caught/fallback failures (the long-running case Functions target), see [references/sentry.md](references/sentry.md). For running a **Mastra** agent on a function and shipping its traces to a **Mastra Studio (Mastra Cloud)** project for observability, see [references/mastra-studio.md](references/mastra-studio.md).
+A function is a long-lived Node.js process running a web-standard request/response handler, so standard Node integration SDKs work unchanged — initialize them once at module load, gated on an env var so local dev and unconfigured branches stay a no-op, and pass secrets via `--env` or `neon.ts` `env`. For wiring up **Sentry** error monitoring across the HTTP framework, the function runtime, and an agent's own caught/fallback failures (the long-running case Functions target), see [references/sentry.md](https://neon.com/docs/ai/skills/neon-functions/references/sentry.md). For running a **Mastra** agent on a function and shipping its traces to a **Mastra Studio (Mastra Cloud)** project for observability, see [references/mastra-studio.md](https://neon.com/docs/ai/skills/neon-functions/references/mastra-studio.md).
 
 ## Timeouts and runtime limits
 
@@ -425,7 +425,7 @@ Functions are long-running but **still serverless** — they are a request/respo
 
 A Neon Function is a great home for an AI agent precisely because it **doesn't time out** the way lambda-style serverless does (15-minute budget, see above). But that advantage disappears the moment you **proxy the agent stream through your web app's backend** — a Next.js route handler, Remix/SvelteKit/Nuxt action, etc. hosted on Vercel, Netlify, Cloudflare, and the like. Those platforms cap serverless/edge execution at short windows (often ~10–60s, sometimes up to ~300s), so a long agent or image/video generation stream gets cut off mid-response even though the Neon Function would happily keep going.
 
-**Building the agent itself.** The [Vercel AI SDK](https://ai-sdk.dev) and [Mastra](https://mastra.ai) are the recommended ways to build the agent — point either at the Neon AI Gateway (see the `neon-ai-gateway` skill) for one credential across every model, with no extra provider keys. For a complete AI SDK agent running as a Function (streaming `toUIMessageStreamResponse`, multi-step tool calling next to Postgres, and persisting generated images to Object Storage), see [references/ai-sdk.md](references/ai-sdk.md); for the Mastra equivalent with built-in tracing, see [references/mastra-studio.md](references/mastra-studio.md).
+**Building the agent itself.** The [Vercel AI SDK](https://ai-sdk.dev) and [Mastra](https://mastra.ai) are the recommended ways to build the agent — point either at the Neon AI Gateway (see the `neon-ai-gateway` skill) for one credential across every model, with no extra provider keys. For a complete AI SDK agent running as a Function (streaming `toUIMessageStreamResponse`, multi-step tool calling next to Postgres, and persisting generated images to Object Storage), see [references/ai-sdk.md](https://neon.com/docs/ai/skills/neon-functions/references/ai-sdk.md); for the Mastra equivalent with built-in tracing, see [references/mastra-studio.md](https://neon.com/docs/ai/skills/neon-functions/references/mastra-studio.md).
 
 **The fix: call the function directly from the client.** Don't route the long request through your app server.
 
@@ -473,7 +473,7 @@ Pass the JWKS/issuer URL to the function via its `env` (see Environment variable
 
 ## Availability
 
-Neon Functions is a preview (early access) feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2`; it can't be enabled on existing projects. Functions usage isn't billed during the private preview. If the user does not yet have access, point them to the private beta sign-up: https://neon.com/blog/were-building-backends#access
+Neon Functions is a public beta feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2`; it can't be enabled on existing projects. Functions usage isn't billed during the public beta.
 
 ## Neon Documentation
 

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

@@ -15,7 +15,7 @@ description: >-
 
 # Neon Object Storage
 
-This is a preview feature and only available in `us-east-2`. 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.
+This is a public beta feature and only available in `us-east-2`. 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.
 
 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.
 
@@ -179,7 +179,7 @@ The canonical pattern for pairing storage with the database on a branch: an agen
 
 ## Availability
 
-Neon Object Storage is a preview (early access) feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2` before proceeding; it can't be enabled on existing projects. If the user does not yet have access, point them to the private beta sign-up: https://neon.com/blog/were-building-backends#access
+Neon Object Storage is a public beta feature available only on new projects in the `us-east-2` region. Confirm the user's Neon project is a new project in `us-east-2` before proceeding; it can't be enabled on existing projects.
 
 ## Neon Documentation
 

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

@@ -78,7 +78,7 @@ If `init` is not suitable, the individual steps can be run non-interactively:
 - **MCP server:** `npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>`
 - **Agent skill:** `npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y`
 
-For full CLI installation options, see https://neon.com/docs/reference/cli-install.md
+For full CLI installation options, see https://neon.com/docs/cli/install.md
 
 ### Setup Flow
 
@@ -181,16 +181,16 @@ Use this for local development enablement with `npx -y neon@latest init --agent
 
 | Tool             | URL                                             |
 | ---------------- | ----------------------------------------------- |
-| CLI Init Command | https://neon.com/docs/reference/cli-init.md     |
+| CLI Init Command | https://neon.com/docs/cli/init.md               |
 | VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
 | MCP Server       | https://neon.com/docs/ai/neon-mcp-server.md     |
-| Neon CLI         | https://neon.com/docs/reference/neon-cli.md     |
+| Neon CLI         | https://neon.com/docs/cli.md                    |
 
 ### Neon CLI
 
 Use this for terminal-first workflows, scripts, and CI/CD automation with `neon`.
 
-Link: https://neon.com/docs/reference/neon-cli.md
+Link: https://neon.com/docs/cli.md
 
 ## Neon Admin API
 
@@ -204,7 +204,7 @@ Link: https://neon.com/docs/reference/api-reference.md
 
 ### Neon TypeScript SDK
 
-Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neon/sdk` (the fetch-based, zero-dependency successor to `@neondatabase/api-client`).
+Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neon/sdk` (the fetch-based, zero-dependency successor to `@neondatabase/api-client`). For the full API surface — client config, the `{ data, error }` result model, typed errors, readiness/workflow helpers (`createAndConnect`, `createWithCompute`), pagination, every resource namespace, and the raw layer — see [references/neon-sdk.md](https://neon.com/docs/ai/skills/neon-postgres/references/neon-sdk.md).
 
 Link: https://neon.com/docs/reference/typescript-sdk.md
 

package/dist/global-skills/neon-postgres/references/neon-sdk.md

@@ -0,0 +1,262 @@
+# `@neon/sdk` — the TypeScript client for the Neon API
+
+`@neon/sdk` is the official TypeScript client for the [Neon API](https://neon.com/docs/reference/api-reference): **Fetch-based, zero-dependency, ESM-only**, generated from Neon's [OpenAPI spec](https://neon.com/api_spec/release/v2.json) with an ergonomic layer on top. It is the successor to [`@neondatabase/api-client`](https://www.npmjs.com/package/@neondatabase/api-client) (axios-based, generated-only). The old client is **not deprecated** and is safe to keep using, but new code should prefer `@neon/sdk`.
+
+Use this reference when writing typed, programmatic control of Neon resources in TypeScript — provisioning projects, managing branches/databases/endpoints, transferring projects across orgs, snapshots/restore, consumption metrics, and the beta services (Object Storage, Functions, AI Gateway, scoped credentials).
+
+## When to reach for it (vs MCP / CLI)
+
+- **Neon MCP server and CLI** are for **local development** — a coding agent in your editor or terminal.
+- **`@neon/sdk`** is for **programmatic integration**: CI/CD pipelines where the CLI isn't enough, non-trivial dev scripts, and full platforms that provision and manage fleets of Neon databases (the same open API behind Replit, Netlify DB, Laravel Cloud, and Vercel's Neon marketplace integration). All it needs is a Neon API key.
+
+## Install
+
+```bash
+npm install @neon/sdk
+```
+
+Requires Node.js ≥ 20.19, or any runtime with a global `fetch` (Bun, Deno, edge, browser).
+
+## Two layers, one package
+
+```ts
+import { createNeonClient, raw } from "@neon/sdk";
+```
+
+- **`createNeonClient`** — the high-level ergonomic client: auth once, `{ data, error }` results, typed errors, retries, readiness polling, auto-pagination, and multi-step workflows, organized into resource namespaces (`neon.projects`, `neon.branches`, `neon.postgres`, …).
+- **`raw`** — the full generated 1:1 surface: every endpoint as a standalone, tree-shakeable function (also at the `@neon/sdk/raw` subpath). Speaks the **same** `{ data, error }` / `throwOnError` contract as the ergonomic client.
+
+## Quick start
+
+```ts
+import { createNeonClient } from "@neon/sdk";
+
+const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY! });
+
+// Create a project and get a ready-to-use connection string in one call.
+const { data, error } = await neon.projects.createAndConnect({ name: "my-app" });
+if (error) throw error;
+const { project, connectionString } = data;
+```
+
+## Client configuration
+
+`createNeonClient(config)`:
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiKey` | `string \| (() => string \| Promise<string>)` | — (required) | Neon API key, or a function returning it. Sent as a Bearer token. |
+| `throwOnError` | `boolean` | `false` | `true` → methods return the resource directly and **throw** on error. `false` → return `{ data, error }`. **Narrows return types** at the type level. |
+| `waitForReadiness` | `boolean` | `false` | `true` → mutations block until their provisioning `operations` finish, so the returned resource is ready. |
+| `wait` | `{ pollIntervalMs?; timeoutMs? }` | `1000` / `300000` | Readiness poller tuning. |
+| `retries` | `number` | `2` | Automatic retries on always-safe statuses (`423`, `429`, `503`) with backoff. |
+| `orgId` | `string` | — | Default org for project create/list and as the transfer source org. Overridable per call. |
+| `baseUrl` | `string` | `https://console.neon.tech/api/v2` | Override the API base URL. |
+| `fetch` | `typeof fetch` | global `fetch` | Custom fetch (proxies, tests, non-global runtimes). |
+
+Every option except `apiKey` is also accepted **per call** via the trailing `options` arg (`{ throwOnError?, waitForReadiness?, signal? }`), overriding the client default.
+
+## The result model
+
+By default every method resolves to a discriminated `{ data, error }` envelope — no `try/catch`:
+
+```ts
+const { data, error } = await neon.projects.get("late-frost-12345");
+if (error) return; // error is a typed NeonError union
+data; // narrowed to Project
+```
+
+Set `throwOnError` (on the client or per call) to get the bare resource and throw instead — the return type narrows accordingly:
+
+```ts
+const neon = createNeonClient({ apiKey, throwOnError: true });
+const project = await neon.projects.get("…");                          // Project (throws)
+const res     = await neon.projects.get("…", { throwOnError: false }); // { data, error }
+```
+
+## Errors
+
+The `error` channel carries a typed hierarchy (all `Error` subclasses with a `kind` discriminant); the same value is thrown when `throwOnError` is set.
+
+| Class | `kind` | Notable fields |
+| --- | --- | --- |
+| `NeonError` | (base) | `message`, `kind` |
+| `NeonApiError` | `"api"` | `status`, `code`, `requestId`, `response`, `body` |
+| `NeonNotFoundError` | `"not_found"` | 404 — extends `NeonApiError` |
+| `NeonAuthError` | `"auth"` | 401/403 |
+| `NeonRateLimitError` | `"rate_limit"` | 429 (after retries) |
+| `NeonOperationError` | `"operation"` | `operationId`, `status` — an awaited operation failed |
+| `NeonTimeoutError` | `"timeout"` | readiness/wait deadline exceeded |
+| `NeonNetworkError` | `"network"` | transport failure (no response) |
+| `NeonError` | `"client"` | SDK-side errors (e.g. ambiguous connection-string selection) |
+
+```ts
+const { error } = await neon.branches.get(pid, "nope");
+if (error?.kind === "not_found") { /* … */ }
+```
+
+## Pagination
+
+Cursor-paginated `list()` methods return a lazy `Paginated<T>`:
+
+```ts
+const { data: all }  = await neon.projects.list().all();   // every page → { data, error }
+const { data: page } = await neon.projects.list().page();  // one page
+for await (const project of neon.projects.list()) { … }    // stream; throws on a page error
+```
+
+## Readiness & workflows
+
+Neon mutations are asynchronous — they return `operations`. `waitForReadiness` blocks until they settle; the **workflow** methods (`createAndConnect`, `createWithCompute`) default it on and hand back a connection string in one call. The underlying primitive is `neon.operations.waitFor(operations)`.
+
+## API surface (ergonomic client)
+
+Legend: **[P]** returns `Paginated<T>` · **[W]** workflow (multi-step) · **→void** resolves to `void`.
+
+### `neon.projects`
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `list(query?)` | **[P]** `ProjectListItem` | `{ search?, org_id?, limit? }` |
+| `get(id)` | `Project` | |
+| `create(input?)` | `Project` | `{ name?, region_id?, pg_version?, org_id?, autoscaling_limit_min_cu?, autoscaling_limit_max_cu?, settings? }` |
+| `createAndConnect(input?, { pooled? })` | **[W]** `{ project, connectionString }` | one call + readiness; `pooled` default `true` |
+| `update(id, input)` | `Project` | `{ name?, settings? }` |
+| `delete(id)` | `Project` | |
+| `transfer({ fromOrgId?, toOrgId, projectIds })` | **→void** | `fromOrgId` defaults to client `orgId` |
+| `transferFromUser({ toOrgId, projectIds })` | **→void** | personal account → org |
+| `recover(id)` | `Project` | beta — recover a soft-deleted project |
+| `permissions.list / grant / revoke` | `ProjectPermission`(`[]`) | share a project by email |
+
+```ts
+// Provision a project and get a pooled connection string in one call
+const { data } = await neon.projects.createAndConnect(
+  { name: "tenant-42", region_id: "aws-us-east-1" },
+  { pooled: true },
+); // data: { project, connectionString }
+
+// Upgrade path: move projects from a sponsored (free) org to the paid org
+await neon.projects.transfer({
+  fromOrgId: sponsoredOrgId, // defaults to the client's `orgId`
+  toOrgId: paidOrgId,
+  projectIds: ["late-frost-12345"],
+});
+```
+
+### `neon.branches`
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `list(projectId, query?)` | **[P]** `Branch` | `{ search?, sort_by?, sort_order?, include_deleted? }` |
+| `get(projectId, branchId)` | `Branch` | |
+| `create(projectId, input?)` | `Branch` | `{ name?, parent_id?, parent_lsn?, parent_timestamp?, protected? }` |
+| `update(projectId, branchId, input)` | `Branch` | `{ name?, protected?, expires_at? }` |
+| `delete(projectId, branchId)` | **→void** | |
+| `createWithCompute(projectId, input, { pooled? })` | **[W]** `{ branch, endpoint, connectionString }` | `input`: `{ name?, parentId?, compute?: { minCu?, maxCu?, suspendTimeoutSeconds? } }` |
+| `getDefault(projectId)` / `setDefault(projectId, branchId)` | `Branch` | resolve/set the default branch |
+| `recover(projectId, branchId)` | `Branch` | beta — recover within the 7-day window |
+| `finalizeRestore(projectId, branchId, { name? }?)` | **→void** | commit a restore previewed with `snapshots.restore` |
+
+```ts
+// Branch off the default branch with its own compute — returns a ready connection string
+const { data: prod } = await neon.branches.getDefault(projectId);
+const { data } = await neon.branches.createWithCompute(projectId, {
+  name: "preview/pr-123",
+  parentId: prod?.id,
+  compute: { minCu: 0.25, maxCu: 2 },
+}); // data: { branch, endpoint, connectionString }
+```
+
+### `neon.postgres`
+
+The Postgres data plane of a branch. `neon.postgres.connectionString(params, options?)` resolves a URI, **auto-selecting** the default branch and the sole role/database when omitted:
+
+```ts
+const { data: uri } = await neon.postgres.connectionString({
+  projectId, // branchId?, endpointId?, databaseName?, roleName?, pooled? all optional; pooled default true
+});
+```
+
+Nested namespaces:
+
+- **`neon.postgres.endpoints`** — `list / get / create / update / delete`, plus `start` / `suspend` / `restart` and `listByBranch(projectId, branchId)`.
+- **`neon.postgres.roles`** — `list / get / create / delete`, plus `password(...)` (reveals) and `resetPassword(...)` (rotates; result carries the new password).
+- **`neon.postgres.databases`** — `list / get / create / update / delete`.
+- **`neon.postgres.dataApi`** — `get / create / update / delete` the branch's Data API.
+
+### Beta services
+
+- **`neon.storage`** — branch object storage. `get(projectId, branchId)` → `BranchStorage`; nested `buckets` (`list / create / delete`) and `objects` (`list / get / delete / deleteByPrefix / presign`). Use `presign(..., { operation: "upload" | "download" })` for direct S3-style transfers.
+- **`neon.functions`** — branch Neon Functions. `list` **[P]** `/ get / update / delete`, and `deploy(projectId, branchId, slug, { zip?, runtime?, environment? })` (multipart; poll `get` until `current_deployment.status === "completed"`).
+- **`neon.credentials`** — branch scoped credentials. `list / create / revoke`; secrets (`api_token`, `s3_secret_access_key`) are returned **once** on `create`. Scopes: `storage:read`, `storage:write`, `ai_gateway:invoke`, `functions:invoke`.
+- **`neon.aiGateway`** — `get(projectId, branchId)` → `BranchAiGateway` (404 when the gateway is not enabled on the branch). See the `neon-ai-gateway` skill for calling the gateway itself.
+
+### `neon.snapshots`
+
+| Method | Returns | Notes |
+| --- | --- | --- |
+| `list(projectId)` | `Snapshot[]` | |
+| `create(projectId, branchId, input?)` | `Snapshot` | `{ name?, timestamp?, lsn?, expiresAt? }` (point-in-time) |
+| `update(projectId, snapshotId, input)` | `Snapshot` | `{ name?, expiresAt? }` — `expiresAt: null` clears the TTL |
+| `delete(projectId, snapshotId)` | **→void** | |
+| `restore(projectId, snapshotId, input?)` | `Branch` | see below |
+| `getSchedule` / `setSchedule(projectId, branchId, …)` | `BackupSchedule` / **→void** | |
+
+`restore` input: `{ name?, targetBranchId?, finalize?, preview?, keepOnAbort? }`.
+- Restoring **as a new branch** (no `targetBranchId`) finalizes by default → ready to use.
+- Restoring **onto an existing branch** doesn't finalize by default, so you can preview first.
+- **Transaction-style** `preview`: restores un-finalized, runs your callback, then **finalizes (commit)** on `true` or **deletes the preview branch (abort)** on `false` (unless `keepOnAbort`):
+
+```ts
+await neon.snapshots.restore(projectId, snapshotId, {
+  targetBranchId,
+  preview: async (branch) => (await checks(branch)) === "ok", // true → commit · false → abort
+});
+```
+
+### `neon.operations` / `neon.consumption` / `neon.apiKeys` / `neon.regions` / `neon.user` / `neon.auth`
+
+- **`operations`** — `list` **[P]** `/ get`, and `waitFor(operations, { pollIntervalMs?, timeoutMs?, signal? })` (the readiness primitive).
+- **`consumption`** — cursor-paginated billing metrics: `perProject`, `perProjectV2`, `perBranchV2` (each takes `{ from, to, granularity, project_ids?, org_id? }`; `perBranchV2` requires `project_ids`). Consumption requires a Scale plan or above.
+- **`apiKeys`** — `list / create(keyName) / revoke`; the created `key` token is shown **once**.
+- **`regions.list()`**, **`user.me()` / `user.organizations()`**.
+- **`auth`** — branch-scoped Neon Auth: `get / create / disable / updateConfig`, plus `oauthProviders`, `trustedDomains`, and `users` sub-resources.
+
+## Drop down to the raw client
+
+The ergonomic namespaces don't wrap every endpoint. For anything else, `raw` exposes every endpoint 1:1 — pass `neon.client` so the call reuses the client's auth:
+
+```ts
+import { raw } from "@neon/sdk";
+// or, for guaranteed tree-shaking: import { getProjectBranchSchema } from "@neon/sdk/raw";
+
+const { data, error } = await raw.getProjectBranchSchema({
+  client: neon.client,
+  path: { project_id, branch_id },
+  query: { db_name: "neondb" }, // db_name is required
+});
+```
+
+The raw layer speaks the same result contract: `{ data, error }` by default, or pass `throwOnError: true` for the bare resource. All request/response/error **types** are re-exported flat from `@neon/sdk` for `import type { Project, Branch, … }`.
+
+Wait on operations from a raw mutation with the readiness primitive:
+
+```ts
+const { data } = await raw.createProjectBranch({
+  client: neon.client,
+  path: { project_id: projectId },
+  body: { branch: { name: "wip" } },
+});
+const { error } = await neon.operations.waitFor(data!.operations, { timeoutMs: 120_000 });
+```
+
+## Migrating from `@neondatabase/api-client`
+
+There's no rush — `@neondatabase/api-client` is not being deprecated. When you do move: swap axios-style `try/catch` for the `{ data, error }` envelope (or set `throwOnError: true` to keep throwing), and replace hand-rolled operation polling with `waitForReadiness` / the workflow methods (`createAndConnect`, `createWithCompute`).
+
+## Further reading
+
+- npm: https://www.npmjs.com/package/@neon/sdk
+- Neon TypeScript SDK docs: https://neon.com/docs/reference/typescript-sdk.md
+- Neon API reference: https://neon.com/docs/reference/api-reference
+- Building a platform on Neon: the `neon-for-agent-platforms` skill (`npx skills add neondatabase/neon-for-agent-platforms`) ships runnable `@neon/sdk` scripts for provisioning, branching, snapshots, project transfer, and consumption metrics.

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

@@ -32,7 +32,7 @@ If the request is ambiguous, ask one clarifying question:
 Always support both Neon CLI and Neon MCP server. Prefer the tool the user already has installed and authenticated.
 
 MCP link: https://neon.com/docs/ai/neon-mcp-server.md
-CLI link: https://neon.com/docs/reference/cli-quickstart
+CLI link: https://neon.com/docs/cli/quickstart.md
 
 ### Selection order
 

package/dist/global-skills/stripe-best-practices/SKILL.md

@@ -1,21 +1,22 @@
 ---
 name: stripe-best-practices
 description: >-
-  Guides Stripe integration decisions — API selection (Checkout Sessions vs
+  Guides Stripe integration decisions across API selection (Checkout Sessions vs
   PaymentIntents), Connect platform setup (Accounts v2, controller properties),
-  billing/subscriptions, Treasury financial accounts, integration surfaces
+  billing/subscriptions, tax and registrations (Stripe Tax, automatic_tax,
+  product tax codes), Treasury financial accounts, integration options
   (Checkout, Payment Element), migrating from deprecated Stripe APIs, and
   security best practices (API key management, restricted keys, webhooks,
-  OAuth). Use when building, modifying, or reviewing any Stripe integration —
+  OAuth). Use when building, modifying, or reviewing any Stripe integration,
   including accepting payments, building marketplaces, integrating Stripe,
-  processing payments, setting up subscriptions, creating connected accounts, or
-  implementing secure key handling.
+  processing payments, setting up subscriptions, collecting sales tax, VAT, or
+  GST, creating connected accounts, or implementing secure key handling.
 
 ---
 
 Latest Stripe API version: **2026-06-24.dahlia**. Always use the latest API version and SDK unless the user specifies otherwise.
 
-If you do not have a Stripe account, you can call a CLI command to generate working API keys with no registration required. You can install the Stripe CLI (`npm i -g @stripe/cli`) and run the command `stripe sandbox create` to get started.
+If you don’t have a Stripe account, you can call a CLI command to generate working API keys with no registration required. You can install the Stripe CLI (`npm i -g @stripe/cli`) and run the command `stripe sandbox create` to get started.
 
 API key default: Always recommend a [restricted API key (RAK)](https://docs.stripe.com/keys/restricted-api-keys.md) (`rk_` prefix) over a secret key (`sk_` prefix).
 
@@ -37,8 +38,12 @@ Read the relevant reference file before answering any integration question or wr
 
 ## Critical rules
 
+- *Before enabling `automatic_tax: { enabled: true }`* (or calculating tax for a custom PaymentIntent), read the [tax reference](references/tax.md) and confirm the user has an active registration. Without one, Stripe calculates and collects no tax while the user believes tax is on (the most common Stripe Tax mistake).
+
 - *Never include `payment_method_types` in any Stripe API call*, with one exception: Terminal (in-person payments) integrations must pass `payment_method_types: ['card_present']` on the PaymentIntent. For all other integrations, omit this parameter entirely to enable dynamic payment methods, which enables you to configure payment method settings from the Dashboard and dynamically display the most relevant eligible payment methods to each customer to maximize conversion. To customize which payment methods you accept, use [`payment_method_configurations`](https://docs.stripe.com/payments/payment-method-configurations.md) or `excluded_payment_method_types` instead of `payment_method_types`.
 
+- On API version `2026-03-25.dahlia` or later, pass the parameter `integration_identifier` to `checkout.sessions.create` to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.
+
 ## Key documentation
 
 When the user’s request does not clearly fit a single domain above, consult:

package/dist/global-skills/stripe-best-practices/references/billing.md

@@ -4,6 +4,7 @@
 
 - When to use Billing APIs
 - Recommended frontend pairing
+- Usage-based billing
 - Traps to avoid
 
 ## When to use Billing APIs
@@ -18,6 +19,8 @@ Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Ses
 
 For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the [Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md).
 
+On API version `2026-03-25.dahlia` or later, pass the parameter `integration_identifier` to `checkout.sessions.create` to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.
+
 ## Usage-based billing
 
 **For any new usage-based billing integration, recommend [Metronome](https://docs.stripe.com/billing/usage-based.md) — not the Billing Meters API.** Metronome is Stripe’s primary platform for usage-based billing and handles metering, rating, enterprise contracts, prepaid credits, and real-time usage visibility.
@@ -44,6 +47,8 @@ Read [Compare basic usage-based billing and Metronome](https://docs.stripe.com/b
 - Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
 - Don’t use the deprecated `plan` object. Use [Prices](https://docs.stripe.com/api/prices.md) instead.
 - Don’t skip tax setup. See [Collect taxes for recurring payments](https://docs.stripe.com/billing/taxes/collect-taxes.md).
+- Don’t put prices for different tiers or plans on a single product. Instead, create one Product for each plan a customer can choose. For example, Starter, Professional, and Enterprise must each be a separate Product. Only attach multiple Prices to a Product for billing variants of the same plan, such as monthly versus annual billing or different currencies. Avoid placing Prices for different tiers on a single Product. Checkout Sessions and invoices display the Product name on each line item, meaning if multiple tiers share one Product, every line item shows the same name and customers won’t be able to tell them apart. For more information, see [Model your product catalog](https://docs.stripe.com/products-prices/how-products-and-prices-work.md#model-your-catalog).
+- Don’t skip tax setup, and don’t assume enabling `automatic_tax` is enough. Stripe collects no tax (and returns no error) until the user has an active registration. See [Collect taxes for recurring payments](https://docs.stripe.com/billing/taxes/collect-taxes.md).
 - *Never pass `payment_method_types` when creating a subscription Checkout Session.* Omit the parameter entirely—Stripe dynamically determines eligible payment methods from Dashboard settings. Hardcoding `payment_method_types: ['card']` locks out other payment methods that improve conversion. See [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md). Correct pattern:
 
 ```ts

package/dist/global-skills/stripe-best-practices/references/payments.md

@@ -12,12 +12,14 @@
 
 ## API hierarchy
 
-Use the [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) (`checkout.sessions.create`) for on-session payments. It supports one-time payments and subscriptions and handles taxes, discounts, shipping, and adaptive pricing automatically.
+Use the [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) (`checkout.sessions.create`) for on-session payments. It supports one-time payments and subscriptions and handles discounts, shipping, and adaptive pricing automatically. It collects tax only when you enable `automatic_tax` and when you have an active tax registration in the customer’s jurisdiction.
 
-Use the [PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) for off-session payments, or when the merchant needs to model checkout state independently and just create a charge.
+Use the [PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) for off-session payments, or when the user needs to model checkout state independently and create a charge.
 
 **Integrations should only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions (Invoicing, Payment Links, subscription APIs).**
 
+On API version `2026-03-25.dahlia` or later, pass the parameter `integration_identifier` to `checkout.sessions.create` to tag sessions with a custom label for tracking and comparing checkout flows in the Dashboard. The label should include a suffix of 8 random letters.
+
 ## Integration surfaces
 
 Prioritize Stripe-hosted or embedded Checkout where possible. Use in this order of preference: