vybekiit 0.7.26 → 0.7.27

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

@@ -0,0 +1,12 @@
+# Auth
+
+Login identity lives in the `neon-auth` skill: choose Managed Better Auth, keep existing Better Auth or another IdP, or point at self-managed Better Auth when a required feature is outside Managed support.
+
+Fetch https://neon.com/docs/ai/skills/neon-auth/SKILL.md
+
+Until the released CLI catalog includes `neon-auth`, do not run `neon skills -s neon-auth` (unknown names fail). If the neon.com URL is unpublished, fetch https://github.com/neondatabase/agent-skills/blob/main/skills/neon-auth/SKILL.md
+
+Implementation:
+
+- Managed setup: https://neon.com/docs/ai/skills/neon-auth/references/managed-auth.md
+- Self-managed pointer (not a second tutorial): https://neon.com/docs/ai/skills/neon-auth/references/self-managed.md

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

@@ -10,8 +10,8 @@ Use this after the neon skill account check found no account.
 
 1. Install the CLI: `npm i -g neon@latest`
 2. If `neon claim --help` does not list `create`, skip to [If neon claim is missing](#if-neon-claim-is-missing).
-3. Write a `neon.ts` that declares the services you need, or skip the file and pass `--service` on create. Postgres is always requested.
-4. Create the project: `neon claim create --env-pull` (add `--service data-api --service auth` if there is no `neon.ts`)
+3. Write a `neon.ts` that declares the services you need, or skip the file and pass `--service` on create. Postgres is always requested. Request Auth when login is needed. Request `data-api` only for PostgREST / Supabase database-client compatibility.
+4. Create the project: `neon claim create --env-pull` (add `--service auth` if there is no `neon.ts` and login is requested)
 5. If create did not write env, pull it: `neon env pull`
 6. Use the `neon-postgres` skill for connections, schemas, and queries. Install it if it is missing: `neon skills -s neon-postgres`
 
@@ -22,17 +22,22 @@ npm i -g neon@latest
 neon claim --help
 ```
 
-If that help lists `create` and you need Auth or the Data API, `npm i @neon/config` and write `neon.ts`. Then `neon claim create --env-pull`.
+If that help lists `create` and you need Auth, `npm i @neon/config` and write `neon.ts`. Then `neon claim create --env-pull`.
 
 ```typescript
 import { defineConfig } from "@neon/config/v1";
 
 export default defineConfig({
   auth: true,
-  dataApi: true,
 });
 ```
 
+`claim create --service` accepts `postgres`, `auth`, `data-api`, `functions`, `object-storage`, and `ai-gateway`. `init --services` accepts the same names except `postgres` (every branch has it). Selecting `data-api` on init also declares Auth. Compatibility-only:
+
+```bash
+neon claim create --service auth --service data-api --env-pull
+```
+
 `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.
@@ -49,16 +54,7 @@ Continuing to Neon starts a transfer with a new 15-minute window and leaves the
 
 When `reconciled` is true, the pre-claim `DATABASE_URL` no longer works. Auth and Data API URLs stay if they were granted. The human signs in with `neon auth`. Then the agent runs `neon link` and `neon env pull` to write the new `DATABASE_URL`. `neon link` discovers the project after that sign-in.
 
-Auth and the Data API stay off unless requested at create or enabled later. On the unclaimed project, `neon.ts` plus `neon deploy` enables them. After claim, the same config talks to Neon directly. An external JWKS is only accepted after claim. Data API with the default auth provider requires Auth:
-
-```typescript
-import { defineConfig } from "@neon/config/v1";
-
-export default defineConfig({
-  auth: true,
-  dataApi: true,
-});
-```
+Auth stays off unless requested at create or enabled later. Request the Data API only for PostgREST / Supabase database-client compatibility. On the unclaimed project, `neon.ts` plus `neon deploy` enables requested services. After claim, the same config talks to Neon directly. An external JWKS is only accepted after claim. Data API with the default auth provider requires Auth.
 
 ```bash
 neon deploy

package/dist/global-skills/neon/references/function-triggers.md

@@ -0,0 +1,53 @@
+# Function Triggers (CLI, MCP, REST)
+
+A Function Trigger is a branch-scoped rule that POSTs to a Neon Function on a cron (`type: "schedule"`) or when an object is created in a bucket (`type: "storage_object_created"`). Same regions as Functions (`aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`).
+
+**Prefer `neon.ts`.** Declare a `triggers` map. The record key is the trigger name. `neon deploy` applies triggers after the functions they target. Names must be unique among every trigger visible on the branch. Triggers that exist remotely but are omitted from `neon.ts` are left alone; delete with `neon triggers delete`.
+
+```typescript
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  functions: {
+    ingest: { name: "Object ingest", source: "src/index.ts" },
+    cron: { name: "Cron", source: "src/cron.ts" },
+  },
+  buckets: { assets: { access: "public_read" } },
+  triggers: {
+    "on-upload": {
+      type: "storage_object_created",
+      function: "ingest",
+      bucket: "assets",
+      prefix: "logos/",
+      functionPath: "/object",
+    },
+    "every-minute": {
+      type: "schedule",
+      function: "cron",
+      cron: "* * * * *",
+      functionPath: "/cron",
+    },
+  },
+});
+```
+
+Needs Neon CLI 4.21 or newer (`@neon/config` 1.7.0).
+
+**CLI** when you are not applying `neon.ts`, or to list, enable, disable, or delete. `create` takes `--cron` or `--bucket`, not both:
+
+```bash
+neon triggers create --function-slug cron --name hourly --cron '0 * * * *' --function-path /cron
+neon triggers create --function-slug ingest --name on-upload --bucket assets --prefix 'logos/' --function-path /object
+neon triggers list
+neon triggers update <id> --branch <branch> --cron '*/30 * * * *'
+neon triggers update <id> --branch <branch> --bucket assets --prefix 'incoming/'
+neon triggers enable <id> --branch <branch>
+neon triggers disable <id> --branch <branch>
+neon triggers delete <id> --branch <branch>
+```
+
+Inspect a trigger with `neon triggers list --output json`. Pass `--branch` on get/update/enable/disable/delete: without it the CLI resolves the trigger id as a branch name. Inherited triggers (created on a parent branch) show `Inherited true` on the child and start disabled. `neon deploy` of a `neon.ts` that declares the same trigger enables that copy; omit it to leave the inherited trigger disabled.
+
+**MCP backup** (Neon MCP server, `?category=functions`): `list_triggers`, `get_trigger`, `create_trigger`, `update_trigger`, `delete_trigger`. `create_trigger` takes `project_id`, `branch_id` (a `br-…` id, not a name), and `body` with `"type": "schedule"`, `function_slug`, `name`, and `schedule: { cron }`. REST if neither CLI nor MCP is available: `POST /projects/{project_id}/branches/{branch_id}/triggers`. Schedule body matches MCP. Storage body uses `"type": "storage_object_created"` and `storage_object_created: { bucket_name, prefix }`. CLI reference: https://neon.com/docs/cli/triggers.md.
+
+Authenticate a trigger delivery with `parseTriggerDelivery` from `@neon/functions` (≥ 0.11.0). `parseTrigger` / `parseTriggerInvocation` stay schedule-only. Full type table, payload, and Hono example: the `neon-functions` skill, `references/function-triggers.md`.

package/dist/global-skills/neon/references/logs-loki.md

@@ -0,0 +1,61 @@
+# Logs: CLI, Loki, and SDK pagination
+
+Neon exposes branch-scoped logs. **Today they cover Neon Functions and Object Storage only.** Postgres computes and the AI Gateway are coming; until then, neither emits records. Logs are available in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. A branch that can't serve logs at all answers `404` with `reason: telemetry_not_enabled` (the message says whether it's the wrong region or a branch not collecting telemetry yet), versus a `200` empty result when the branch is enabled but has no records in the window; an unknown branch answers `reason: branch_not_found`.
+
+Use Neon CLI 3.1 or newer first. **Decide which branch you are querying.** Without `--branch`, the CLI uses the branch pinned in `.neon`, or the project's default branch when the workspace isn't linked. A deployed function or bucket usually lives on a different branch than the one checked out for development, so an empty result is more often the wrong branch than a missing log.
+
+```bash
+neon logs query --since 1h
+neon logs query --branch production --source function --minimum-severity error --since 6h
+neon logs query --source storage --since 1h --output json
+neon logs fields
+neon logs field-values service_name --since 1h
+```
+
+`--source` accepts `function`, `storage`, and `pg_endpoint`, but only `function` and `storage` return records today — `pg_endpoint` is accepted and comes back empty until Postgres logs ship. The window defaults to 1h on `query` and 6h on `field-values`, and cannot exceed 7d on either. If Neon reports `--minimum-severity` as unsupported on a branch, use `--severity-text` instead (an exact, case-sensitive match, e.g. `ERROR`); severities vary by source, so confirm what a branch carries with `neon logs field-values severity_text`. Run `neon logs --help` for the full filter and pagination interface.
+
+`--logql` replaces the structured filters with a raw stream selector or line filter. Its stream label is `entity_type`, not `source`:
+
+```bash
+neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"'
+```
+
+If the CLI is unavailable, fall back to the Neon MCP server's read-only `query_logs`, `list_log_fields`, and `list_log_field_values` tools.
+
+## Loki-compatible read API
+
+For direct HTTP reads, authenticate with `Authorization: Bearer <NEON_API_KEY>` and use this branch-scoped base URL:
+
+```text
+https://console.neon.tech/telemetry/v1/projects/{projectId}/branches/{branchId}/loki
+```
+
+The available endpoints are:
+
+- `GET /api/v1/query_range`
+- `GET /api/v1/labels`
+- `GET /api/v1/label/{name}/values`
+
+This is a read-only Loki-compatible subset, not a push endpoint or complete Loki deployment. `query_range` supports LogQL stream selectors and line filters, plus `since` or `start`/`end`, `limit`, and `direction`; it does not support aggregations, parsers, or formatting stages.
+
+The paths above are the ones to call directly. A Loki client that builds its own paths — a Grafana data source appends `/loki/api/v1` to whatever URL it is given — may need a different root, so confirm the data-source URL against the Neon docs rather than pasting this base.
+
+In TypeScript applications, use `@neon/sdk`. Project and branch are positional, and `query` returns a lazy paginated iterable rather than a promise:
+
+```typescript
+for await (const record of neon.logs.query(projectId, branchId, {
+  since: "1h",
+  source: "function",
+})) {
+  console.log(record.timestamp, record.severity_text, record.message);
+}
+
+const { data: fields } = await neon.logs.fields(projectId, branchId);
+const { data: serviceNames } = await neon.logs.fieldValues(
+  projectId,
+  branchId,
+  "service_name",
+);
+```
+
+`query`'s iterator always throws on error, but `fields` and `fieldValues` follow the client's `throwOnError`, which defaults to `false` and hands back `{ data, error }`. `fieldValues` resolves to the whole response, not a bare array: read `serviceNames.values`, and treat them as an arbitrary subset whenever `serviceNames.is_truncated` is true.

package/dist/global-skills/neon/references/parse-env.md

@@ -0,0 +1,32 @@
+# Type-safe env vars with parseEnv
+
+`@neon/env`'s `parseEnv` takes your `neon.ts` config object and returns a parsed, typed env object, validated against the services you declared. The shape of `env` follows your config, and missing variables are flagged with clear errors.
+
+```bash
+npm i @neon/env
+```
+
+```typescript
+import { parseEnv } from "@neon/env";
+import config from "./neon";
+
+const env = parseEnv(config);
+
+console.log(env.postgres.databaseUrl);
+console.log(env.auth.baseUrl);
+```
+
+By default `parseEnv` requires _every_ variable your config implies. When one of your apps only uses a subset, for example when you need to read `DATABASE_URL` but never the unpooled URL, pass an array of env-var keys to require and validate only those. The keys are typesafe: autocomplete only offers variables your config enables, and the returned shape is narrowed to exactly what you selected (so unselected variables are neither enforced nor present).
+
+```typescript
+import { parseEnv } from "@neon/env";
+import config from "./neon";
+
+// Only DATABASE_URL is required and returned; DATABASE_URL_UNPOOLED is not enforced.
+const { postgres } = parseEnv(config, ["DATABASE_URL"]);
+console.log(postgres.databaseUrl);
+
+// Selecting across services — only these keys are validated.
+const env = parseEnv(config, ["DATABASE_URL", "NEON_AUTH_BASE_URL"]);
+console.log(env.postgres.databaseUrl, env.auth.baseUrl);
+```

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

@@ -0,0 +1,7 @@
+# @neon/sdk
+
+`@neon/sdk` is the official TypeScript client for the [Neon API](https://neon.com/docs/reference/api-reference.md): **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 it to manage Neon resources programmatically: creating projects, branches, and snapshots for dev scripts, CI/CD automations, and platforms building on top of Neon.
+
+Log query pagination lives in [logs-loki.md](https://neon.com/docs/ai/skills/neon/references/logs-loki.md).

package/dist/global-skills/neon-ai-gateway/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 AI Gateway
 
-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`.
 
 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 many providers (Anthropic, OpenAI, Google, Meta, and more), all hosted and powered by Databricks. The catalog shifts over time, so treat `/v1/models` and the [models.dev Neon page](https://models.dev/providers/neon) as the source of truth rather than a fixed provider list. Your existing OpenAI/Anthropic/Gemini SDK works by changing only the base URL.
 
@@ -55,29 +55,27 @@ If the user already has a deep, single-provider integration and no interest in N
 
 Check these preconditions before setting anything up:
 
-The AI Gateway is a public beta feature available in the `us-east-2` region. Foundation model access requires a paid Neon plan. Confirm the user's project is in `us-east-2`.
+The AI Gateway is currently available in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`. Foundation model access requires a paid Neon plan. Confirm the user's project is in one of these regions.
 
 ### 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:
+The AI Gateway is credential-gated rather than a provisioning step, but two plan 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 below) rather than assuming the full catalog.
+- **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 `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 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 below) 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.
 
 ## Setup
 
-The gateway is part of `neon.ts` (see the `neon` skill for the branch-first workflow and `neon.ts` basics). Enable it under `preview.aiGateway`:
+The gateway is part of `neon.ts` (see the `neon` skill for the branch-first workflow and `neon.ts` basics). Enable it with `aiGateway`:
 
 ```typescript
 // neon.ts
 import { defineConfig } from "@neon/config/v1";
 
 export default defineConfig({
-  preview: {
-    aiGateway: true,
-  },
+  aiGateway: true,
 });
 ```
 
@@ -87,7 +85,7 @@ neon deploy   # provisions the gateway on the linked branch
 
 ## Neon Infrastructure as Code (`neon.ts`)
 
-The `preview.aiGateway` toggle above is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares the gateway alongside every other branch service, in version control (see the `neon` skill for the full reference). Reconcile it against a branch the Terraform way:
+The `aiGateway` toggle above is part of `neon.ts`, Neon's infrastructure-as-code file — one TypeScript file declares the gateway alongside every other branch service, in version control (see the `neon` skill for the full reference). Reconcile it against a branch the Terraform way:
 
 ```bash
 neon config status   # print the branch's live config (is the gateway on?)
@@ -99,7 +97,7 @@ The gateway is **branch-scoped**: each branch gets its own gateway host. When a
 
 ## Environment Variables
 
-When `preview.aiGateway` is enabled, Neon injects the gateway credentials as **Neon-branded** env vars. Inside a deployed Neon Function these are injected automatically; locally, `neon env pull` writes them to `.env`/`.env.local` (or use `neon-env run -- <cmd>` to inject at runtime without a file):
+When `aiGateway` is enabled, Neon injects the gateway credentials as **Neon-branded** env vars. Inside a deployed Neon Function these are injected automatically; locally, `neon env pull` writes them to `.env`/`.env.local` (or use `neon-env run -- <cmd>` to inject at runtime without a file):
 
 | Variable                   | Meaning                                                                                                                             |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
@@ -177,11 +175,11 @@ const { text } = await generateText({
 });
 ```
 
-For a full AI SDK agent deployed as a Neon Function (streaming, tool calling, image generation, persistence), see the `neon-functions` skill's `references/ai-sdk.md`.
+For a full AI SDK agent deployed as a Neon Function (streaming, tool calling, image generation, persistence), see the `neon-functions` skill's [references/ai-sdk.md](https://neon.com/docs/ai/skills/neon-functions/references/ai-sdk.md).
 
 ## Build Agents with Mastra (Recommended)
 
-[Mastra](https://mastra.ai) is the recommended framework when you want batteries-included agents — built-in memory, tools, workflows, and tracing — with the model still pointed at the gateway. With `@mastra/core` 1.47+, use a `neon/<model>` magic string; Mastra reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` from the environment (injected by `neon deploy` when `preview.aiGateway` is enabled). Use `parseEnv` only for other declared services (e.g. `env.postgres.databaseUrl` for `@mastra/pg` memory):
+[Mastra](https://mastra.ai) is the recommended framework when you want batteries-included agents — built-in memory, tools, workflows, and tracing — with the model still pointed at the gateway. With `@mastra/core` 1.47+, use a `neon/<model>` magic string; Mastra reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` from the environment (injected by `neon deploy` when `aiGateway` is enabled). Use `parseEnv` only for other declared services (e.g. `env.postgres.databaseUrl` for `@mastra/pg` memory):
 
 ```typescript
 import { Agent } from "@mastra/core/agent";
@@ -255,8 +253,8 @@ curl "$NEON_AI_GATEWAY_BASE_URL/v1/models" \
 
 **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.** `neon env pull` writes the two vars to `.env`/`.env.local`, or `neon-env run -- <cmd>` injects them at runtime without a file — but only when `neon.ts` declares `preview.aiGateway`; the vars are never pulled off branch state alone.
+- **Provision via `neon.ts` (recommended).** Enable `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.** `neon env pull` writes the two vars to `.env`/`.env.local`, or `neon-env run -- <cmd>` injects them at runtime without a file — but only when `neon.ts` declares `aiGateway`; the vars are never pulled off branch state alone.
 - **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).

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

@@ -0,0 +1,155 @@
+---
+name: neon-auth
+description: >-
+  Add authentication to a new app. Use for "add auth", "add login", Neon Auth
+  (Managed Better Auth), identity routing, sign-up, sign-in, password reset,
+  email OTP, magic links, organizations, phone OTP, OAuth, passkeys, MFA,
+  trusted domains, invalid domain, and @neondatabase/auth. No existing identity:
+  default to Managed Better Auth. Keep working Better Auth, Clerk, Supabase
+  Auth, or another IdP. User asked to migrate from Supabase Auth: Managed
+  Better Auth. A required plugin outside Managed support: self-managed Better
+  Auth on a Neon Function or the existing app host. Also use for auth APIs in
+  @neondatabase/neon-js.
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-auth
+---
+
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
+
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+neon skills -s neon -y
+```
+
+# Neon Auth
+
+Neon Auth is Managed Better Auth: users, sessions, and auth config live in the `neon_auth` schema on the branch's Lakebase Postgres, and auth state branches with the database. The client API is the Better Auth method set (`signIn.email`, `signIn.social`, `getSession`) through `@neondatabase/auth`. That wrapper is not a drop-in for bare `better-auth/client`: it pins the plugin list and adds Neon-specific OAuth verifier, iframe popup, and JWT handling. Stay on the wrapper while Auth is managed.
+
+This skill chooses identity, then implements Managed Better Auth. It does not replace a working auth server in order to use Postgres, Functions, Object Storage, or the AI Gateway.
+
+## When to Use
+
+Inspect existing identity and the required login features before provisioning. A supplied `DATABASE_URL` is not a reason to change identity. Adding a Neon Function is not a reason to change identity.
+
+| Situation | What to do |
+| --- | --- |
+| No existing auth | Default to Managed Better Auth. [Managed setup](#managed-setup), then [references/managed-auth.md](references/managed-auth.md). |
+| Needs a feature Managed does not offer | Self-managed Better Auth on the existing app host (Vercel or similar) or a Neon Function. Keep Lakebase Postgres. Confirm the **installed** Better Auth version documents that exact flow before recommending the move. If support stays unresolved, keep the current identity. [references/self-managed.md](references/self-managed.md). |
+| Already has Better Auth | Keep it. It works with the other Neon primitives. Migrate to Managed only if the user asks. |
+| User asked to migrate from Supabase Auth | Managed Better Auth. [Supabase Auth](#supabase-auth). Moving only Postgres or adding a Function keeps Supabase Auth. |
+| Clerk, Auth.js, Supabase Auth, or another working IdP | Keep it unless the user asks to migrate. |
+
+Google, GitHub, and Vercel social OAuth are offered on Managed Auth. They are not a reason to leave Managed Auth. Other OAuth providers, generic OAuth, MFA, passkeys, API keys, MCP OAuth, SSO, custom plugins, hooks, and custom JWT claims are the [plugin matrix](#plugin-support) check.
+
+Before enabling Managed Auth, confirm the project is on AWS and does not use IP Allow or Private Networking. Leave those protections in place.
+
+Configure supported Managed plugins through Neon (Console, API, or `neon neon-auth`), not by passing `plugins` into `@neondatabase/auth`. Enabling `auth: true` is not implementing login.
+
+## What It Does
+
+- **Managed identity in Postgres** — users and sessions in `neon_auth`, queryable with SQL, compatible with RLS.
+- **Auth emails without an app mailer** — verification, email OTP, magic links, and password reset. Getting started uses shared SMTP (`auth@mail.myneon.app`). You do not add Resend or SendGrid to implement login. Production needs custom SMTP: https://neon.com/docs/auth/production-checklist.md
+- **Branches with the database** — each branch has its own Auth URL and isolated auth state.
+- **Better Auth client methods via the Neon SDK** — `@neondatabase/auth` (auth only) or `@neondatabase/neon-js/auth` (combined SDK). Optional UI: `@neondatabase/auth-ui`.
+- **Fixed plugin set** — the Managed client does not accept a `plugins` option. See [plugin support](#plugin-support).
+
+## Availability
+
+Managed Better Auth is generally available. AWS regions only. It cannot be enabled on a project with IP Allow or Private Networking.
+
+Organization is separately Partial / Beta. Hosting self-managed Better Auth in a Neon Function follows Functions availability and claim rules; use the `neon-functions` skill for that host. An unclaimed project that can enable Auth still cannot use Functions until claim.
+
+## Managed setup
+
+Merge Auth into the existing `neon.ts`. Do not replace other fields:
+
+```typescript
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  auth: true,
+});
+```
+
+```bash
+neon deploy
+neon neon-auth status
+```
+
+If Function env in that config reads `process.env`, use `neon deploy --env <file>` as the parent skill describes. The manual service command is `neon neon-auth enable`; do not run both enable and deploy as redundant required steps when `neon.ts` already declares `auth: true`.
+
+Then implement login: [references/managed-auth.md](references/managed-auth.md).
+
+Claimable projects: follow the parent Claimable path, then `auth: true` and `neon deploy` when login is requested and no existing provider should be preserved.
+
+## Supabase Auth
+
+When the user asked to migrate login from Supabase Auth, recommend Managed Better Auth and follow https://neon.com/docs/auth/migrate/from-supabase.md. Moving only Postgres or adding a Function is not that request: keep Supabase Auth.
+
+`SupabaseAuthAdapter()` keeps method shapes such as `signInWithPassword` and `signInWithOAuth`. Those calls are not interchangeable with default Better Auth examples (`signIn.email`). Keep an existing adapter caller on that API.
+
+Inventory the auth methods and database calls actually used:
+
+- Password hashes cannot transfer. Users create new accounts or sign in with OAuth.
+- Do not promise unchanged user IDs, sessions, or account linking. Plan application foreign keys with the owner.
+- `updateUser()` cannot change email or password on Managed Auth. Email verification needs application UI (codes work on shared SMTP; links need custom SMTP).
+- The migration guide lists Supabase phone/SMS/WhatsApp, SAML, and Web3 as unsupported on Managed Auth. Confirm the **installed** Better Auth version if the user still needs that exact flow; if support stays unresolved, keep Supabase Auth and stop the auth cutover. That page's "no phone auth" claim is about Supabase phone sign-in, not the constrained Managed Phone Number plugin (existing users link a number).
+- `@supabase/supabase-js` used only for Auth does not justify enabling the Data API. Keep Data API only for existing PostgREST / Supabase database-client queries.
+
+## Verification
+
+Managed path: sign-up, sign-in, sign-out, session restoration after reload, and protected access, including error and loading states. Exercise email verification (code on shared SMTP) when it is on. Report any flow that remains unverified.
+
+A required plugin on the self-managed path is verified in that app's Better Auth setup, not as a Managed flow.
+
+## Plugin support
+
+Checked 2026-09-17 against https://neon.com/docs/auth/guides/plugins.md, https://neon.com/docs/auth/roadmap.md, and the `@neondatabase/auth` client plugin list. Re-fetch those pages if this skill may be stale. An unlisted upstream plugin needs a live check; do not treat absence from this table as a dated roadmap item.
+
+"Not exposed" means the Managed SDK/UI contract. It is not a claim that every raw server request was tested.
+
+| Feature | Managed Auth | Boundary |
+| --- | --- | --- |
+| Email/password | Supported | `signUp.email`, `signIn.email` |
+| Social OAuth (Google, GitHub, Vercel) | Supported | `signIn.social`. Shared Google credentials are for development; production and GitHub/Vercel need your own OAuth apps. https://neon.com/docs/auth/guides/setup-oauth.md |
+| Admin | Supported | Admin session required. Plugin customization is on the roadmap. |
+| Email OTP | Supported | Managed delivery. `emailOtp.sendVerificationOtp`, `signIn.emailOtp`. |
+| Magic Link | Supported | Enable on the branch (off by default). `signIn.magicLink`. |
+| Organization | Partial, Beta | Members, invitations, owner/admin/member. No Teams, server hooks, custom roles/permissions, or dynamic access control. Emailed invitations: [managed-auth.md](references/managed-auth.md#organization-invitations). |
+| JWT | Supported | EdDSA (Ed25519), 15-minute expiry, no custom claims. Default client: `.token()` then `data.token`. `SupabaseAuthAdapter()`: `getSession()` then `data.session.access_token` (no `.token()`). |
+| Open API | Supported | Server routes `/reference` and `/open-api/generate-schema`. |
+| Phone Number | Supported with constraints | Browser client: existing users link a number, then sign in; no phone-first signup; own SMS webhook; custom UI. Next.js `auth.handler()` forwards the catch-all path, including phone OTP. A missing `auth.phoneNumber` server method is a missing typed helper, not a proxy rejection. https://neon.com/docs/auth/guides/plugins/phone-number.md |
+| MFA / Two-Factor | Roadmap | Unavailable on Managed Auth. If required: [self-managed.md](references/self-managed.md), after confirming the installed Better Auth version. |
+| Passkey, API Key, Generic OAuth, One Tap, Multi Session | Not exposed by Managed SDK/UI | If required: [self-managed.md](references/self-managed.md). Generic OAuth is not Google/GitHub/Vercel social sign-in. |
+| MCP / OAuth Provider | Not Managed Auth | Third-party MCP clients self-authorizing against your server. Keep existing login. See `neon-functions` [references/mcp.md](https://neon.com/docs/ai/skills/neon-functions/references/mcp.md). |
+| SSO / SAML | Not listed or exposed | If required: [self-managed.md](references/self-managed.md), after confirming the installed Better Auth version. |
+
+The default Managed client method is `getAnonymousToken()`. That JWT is a Neon anonymous Data API token. It is not Better Auth's Anonymous-account plugin (`signIn.anonymous`). `anonymousTokenClient()` is the SDK plugin factory, not a method on the public client. Do not call it, and do not call `getAnonymousToken()` on `SupabaseAuthAdapter()`.
+
+Trusted domains and webhooks are Neon settings, not installable Better Auth plugins.
+
+## Trusted domains
+
+Auth redirects only to origins on its allowlist. `invalid domain` means the app origin is missing. Include the scheme, omit a trailing slash, register production and preview origins before pointing users at them, and target the correct branch:
+
+```bash
+neon neon-auth domain add https://app.example.com
+neon neon-auth domain list
+neon neon-auth domain delete https://old.example.com
+```
+
+Localhost ports are pre-approved by default. An existing project can have that off: `neon neon-auth domain allow-localhost get|enable|disable`. Docs: https://neon.com/docs/auth/guides/configure-domains.md
+
+OAuth provider redirect is `{NEON_AUTH_BASE_URL}/callback/{provider}` (the Auth URL includes its path). `callbackURL` on `signIn.social` is the later app landing origin and must be trusted.
+
+The Managed SDK handles iframe OAuth popup and `neon_auth_session_verifier`. Keep the wrapper, callback route, and middleware. Do not reimplement that flow, and do not promise third-party cookies in every browser.
+
+## Functions and Data API
+
+A Function authenticates whoever already signs the user in. Do not switch identity to call a Function. Verify the token in the `neon-functions` skill and https://neon.com/docs/compute/functions/authentication.md.
+
+Managed Auth: injected `NEON_AUTH_JWKS_URL`, issuer from `NEON_AUTH_BASE_URL`. Token: default client `.token()` then `data.token`; `SupabaseAuthAdapter()` `getSession()` then `data.session.access_token`. A valid token is not permission to read another user's rows. Sign-out ends the browser session; do not claim it immediately revokes an already-issued JWT.
+
+Data API identity: [references/managed-auth.md](references/managed-auth.md). New apps query Postgres from Functions or existing handlers, not the Data API.