vybekiit 0.4.0 → 0.6.0

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

@@ -0,0 +1,376 @@
+---
+name: neon-postgres
+description: >-
+  Guides and best practices for working with Neon Serverless Postgres.
+  Covers setup, connection methods, branching, autoscaling, scale-to-zero,
+  read replicas, connection pooling, Neon Auth, and the Neon CLI, MCP server,
+  REST API, TypeScript SDK, and Python SDK.
+  Use when users ask about "Neon setup", "connect to Neon", "Neon project",
+  "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP",
+  "Neon Auth", "@neondatabase/serverless", "@neondatabase/neon-js",
+  "scale to zero", "Neon autoscaling", "Neon read replica", or
+  "Neon connection pooling".
+---
+
+# Neon Serverless Postgres
+
+Guide the user through any Neon-related task: setup, connections, branching, and advanced features. Deliver a working Neon connection, a completed feature configuration, or a specific answer from the official Neon docs.
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
+
+## Neon Documentation
+
+The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
+
+### Fetching Docs as Markdown
+
+Any Neon doc page can be fetched as markdown in two ways:
+
+1. **Append `.md` to the URL** (simplest): https://neon.com/docs/introduction/branching.md
+2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
+
+Both return the same markdown content. Use whichever method your tools support.
+
+### Finding the Right Page
+
+The docs index lists every available page with its URL and a short description:
+
+```
+https://neon.com/docs/llms.txt
+```
+
+Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index: https://neon.com/docs/llms.txt. Don't guess URLs.
+
+## What Is Neon
+
+Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
+
+Link: https://neon.com/docs/introduction/architecture-overview.md
+
+## Getting Started
+
+Use this section when guiding a user through first-time Neon setup.
+
+### Check Status Quo
+
+Before starting setup, inspect the user's codebase and environment:
+
+- Existing database connection code
+- Existing Neon MCP server or Neon CLI configuration
+- Existence of a `.env` file and `DATABASE_URL` environment variable
+- Existing ORM (Prisma, Drizzle, TypeORM) configuration
+
+### Self-Driving Setup With Neon's CLI or MCP Server
+
+Offer to inspect existing connected Neon projects or create new ones using the Neon CLI or MCP server. If neither is set up yet, run init with the `--agent` flag. Use `npx -y` to skip the package install prompt. Auth is handled automatically. If the user is not logged in, it opens their browser for OAuth and waits for completion before proceeding.
+
+```bash
+npx -y neon@latest init --agent <agent-name>
+```
+
+Supported `--agent` values: `cursor`, `copilot`, `claude`, `claude-desktop`, `codex`, `opencode`, `cline`, `gemini-cli`, `goose`, `zed`.
+
+This installs the Neon extension (for Cursor/VS Code) or MCP server (for other agents), creates an API key, and adds the `neon-postgres` agent skill to the project.
+
+If `init` is not suitable, the individual steps can be run non-interactively:
+
+- **Extension:** `cursor --install-extension databricks.neon-local-connect`
+- **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
+
+### Setup Flow
+
+**1. Select Organization and Project**
+
+Use MCP server or CLI to list organizations and projects. Let the user select an existing project or create a new one.
+
+**2. Get Connection String**
+
+Use MCP server or CLI to get the connection string. Store it in `.env` as `DATABASE_URL`. Read the file first before modifying to avoid overwriting existing values.
+
+**3. Pick Connection Method & Driver**
+
+Refer to the connection methods guide to pick the correct driver based on deployment platform: https://neon.com/docs/connect/choose-connection.md
+
+**4. User Authentication with Neon Auth (if needed)**
+
+Skip for CLI tools, scripts, or apps without user accounts. If the app needs auth: use MCP server `provision_neon_auth` tool, then see the auth overview (https://neon.com/docs/auth/overview.md) for setup. For auth + database queries, see the JavaScript SDK reference (https://neon.com/docs/reference/javascript-sdk.md).
+
+**5. ORM Setup (optional)**
+
+Check for existing ORM (Prisma, Drizzle, TypeORM). If none, ask if they want one. For Drizzle integration, see https://neon.com/docs/guides/drizzle.md.
+
+**6. Schema Setup**
+
+- Check for existing migration files or ORM schemas
+- If none: offer to create an example schema or design one together
+
+### Resume Support
+
+If resuming setup, check what's already configured (MCP connection, `.env` with `DATABASE_URL`, dependencies, schema) and continue from the next incomplete step.
+
+### Security Reminders
+
+Remind users to use environment variables for credentials, never commit connection strings, and use least-privilege database roles.
+
+## Connection Methods & Drivers
+
+Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running).
+
+Link: https://neon.com/docs/connect/choose-connection.md
+
+### Recommended: Drizzle + the right driver for your runtime
+
+Always pair Neon with an ORM such as **Drizzle** for easy schema management and migrations. Pick the driver based on how the runtime treats your code:
+
+- **Long-running or shared-runtime environments → node-postgres (`pg`).** Neon Functions, and any host where the function runtime is shared across requests / runs on fluid compute (e.g. **Vercel** with Fluid compute), keep a module-scope process alive across many requests. Open a `pg` pool **once at module scope** and reuse it across requests.
+- **Fully isolated serverless (Lambda-style) → Neon's serverless driver (`@neondatabase/serverless`).** Hosts like **Netlify** spin up a fresh, isolated instance per request, so a persistent TCP pool can't be reused; the serverless driver queries over HTTP and is built for this.
+
+**Neon Functions / Vercel / fluid compute — Drizzle + node-postgres:**
+
+```typescript
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "./schema";
+
+// Created once at module scope; reused by every request the instance handles.
+const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
+const db = drizzle({ client: pool, schema });
+```
+
+On **Vercel** (Fluid compute) also attach the pool with `attachDatabasePool` from `@vercel/functions`, so the function runtime drains idle connections before an instance suspends:
+
+```typescript
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import { attachDatabasePool } from "@vercel/functions";
+import * as schema from "./schema";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+attachDatabasePool(pool); // let the Vercel runtime manage the pooled connections
+const db = drizzle({ client: pool, schema });
+```
+
+**Netlify and other fully-isolated serverless — Drizzle + Neon serverless driver:**
+
+```typescript
+import { drizzle } from "drizzle-orm/neon-http";
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+const db = drizzle({ client: sql });
+```
+
+### Serverless Driver
+
+Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
+
+Link: https://neon.com/docs/serverless/serverless-driver.md
+
+### Neon JS SDK
+
+Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
+
+Link: https://neon.com/docs/reference/javascript-sdk.md
+
+## Developer Tools
+
+Use this for local development enablement with `npx -y neon@latest init --agent <agent-name>`, VSCode extension setup, and Neon MCP server configuration.
+
+| Tool             | URL                                             |
+| ---------------- | ----------------------------------------------- |
+| CLI Init Command | https://neon.com/docs/reference/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
+
+Use this for terminal-first workflows, scripts, and CI/CD automation with `neon`.
+
+Link: https://neon.com/docs/reference/neon-cli.md
+
+## Neon Admin API
+
+The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications.
+
+### Neon REST API
+
+Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
+
+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`).
+
+Link: https://neon.com/docs/reference/typescript-sdk.md
+
+### Neon Python SDK
+
+Use this when implementing programmatic Neon management in Python with the `neon-api` package.
+
+Link: https://neon.com/docs/reference/python-sdk.md
+
+## Neon Auth
+
+Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
+
+Link: https://neon.com/docs/auth/overview.md
+
+Neon Auth is also embedded in the Neon JS SDK. Depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth alone. See https://neon.com/docs/connect/choose-connection.md for more details.
+
+## Neon Infrastructure as Code (`neon.ts`)
+
+`neon.ts` is Neon's branch config and infrastructure-as-code file: declare which services your branches have, get type-safe env vars, and program per-branch compute — all in TypeScript (see the `neon` skill for the full reference). Postgres always exists on every branch, so you never declare the database itself; what you codify here is the Postgres-adjacent surface — Neon Auth, the Data API, and per-branch compute settings (autoscaling and scale-to-zero).
+
+Add it with `@neon/config`:
+
+```bash
+npm i @neon/config
+```
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  auth: true, // Neon Auth (adds NEON_AUTH_* env vars)
+  dataApi: true, // Data API (adds NEON_DATA_API_URL); requires auth: true (or an external IdP)
+  // Postgres exists on every branch; tune its compute per branch:
+  branch: (branch) => {
+    if (branch.exists) return {}; // leave existing branches untouched
+    if (branch.isDefault) return { protected: true }; // prod keeps default compute
+    return {
+      ttl: "7d", // non-prod branches auto-expire (max 30d)
+      postgres: {
+        computeSettings: {
+          autoscalingLimitMinCu: 0.25, // scale to zero
+          autoscalingLimitMaxCu: 1, // keep dev/preview cheap
+          suspendTimeout: "5m",
+        },
+      },
+    };
+  },
+});
+```
+
+Reconcile the declaration from the CLI — the Neon equivalent of `terraform plan` / `apply`:
+
+```bash
+neon config status   # print the branch's live config
+neon config plan     # dry-run diff of what apply would change
+neon config apply    # provision the declared services / settings
+neon deploy          # alias for `neon config apply`
+```
+
+Because `neon checkout` applies the policy as it **creates** a branch, a fresh branch comes up with these compute settings (and Auth / Data API) already in place. Checking out an _existing_ branch never reconciles it — run `neon deploy` to apply changes.
+
+Since `neon.ts` is TypeScript, invalid combinations fail to compile with an actionable message: the Data API verifies requests with Neon Auth by default, so `dataApi: true` without `auth: true` is a type error (the fix — `auth: true`, or `authProvider: 'external'` with a `jwksUrl` — is in the message). See the `neon` skill's type-safe config note.
+
+Read the resulting env back, typed and validated against the policy, with `parseEnv` from `@neon/env`:
+
+```typescript
+import { parseEnv } from "@neon/env";
+import config from "./neon";
+
+const env = parseEnv(config);
+env.postgres.databaseUrl; // typed; enabling auth / dataApi above surfaces env.auth / env.dataApi
+```
+
+## Branching
+
+Use this when the user is planning isolated environments, schema migration testing, preview deployments, or branch lifecycle automation.
+
+Key points:
+
+- Branches are instant, copy-on-write clones (no full data copy).
+- Each branch has its own compute endpoint.
+- Use the neon CLI or MCP server to create, inspect, and compare branches.
+
+Link: https://neon.com/docs/introduction/branching.md
+
+For detailed branch creation workflows (normal vs schema-only branches, reset-from-parent, CLI/MCP selection), use the `neon-postgres-branches` skill if available
+
+Or fetch the full branching skill from the following URL:
+
+https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md
+
+If this skill is not installed you can use the following command to install it:
+
+```bash
+npx skills add neondatabase/agent-skills --skill neon-postgres-branches
+```
+
+## Autoscaling
+
+Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
+
+Link: https://neon.com/docs/introduction/autoscaling.md
+
+## Scale to Zero
+
+Use this when optimizing idle costs and discussing suspend/resume behavior, including cold-start trade-offs.
+
+Key points:
+
+- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled - launch & scale plan only)
+- First query after suspend typically has a cold-start penalty (around hundreds of ms)
+- Storage remains active while compute is suspended.
+
+Link: https://neon.com/docs/introduction/scale-to-zero.md
+
+## Instant Restore
+
+Use this when the user needs point-in-time recovery or wants to restore data state without traditional backup restore workflows.
+
+Key points:
+
+- History windows for instant restore depend on plan limits.
+- Users can create branches from historical points-in-time.
+- Time Travel queries can be used for historical inspection workflows.
+
+Link: https://neon.com/docs/introduction/branch-restore.md
+
+## Read Replicas
+
+Use this for read-heavy workloads where the user needs dedicated read-only compute without duplicating storage.
+
+Key points:
+
+- Replicas are read-only compute endpoints sharing the same storage.
+- Creation is fast and scaling is independent from primary compute.
+- Typical use cases: analytics, reporting, and read-heavy APIs.
+
+Link: https://neon.com/docs/introduction/read-replicas.md
+
+## Connection Pooling
+
+Use this when the user is in serverless or high-concurrency environments and needs safe, scalable Postgres connection management.
+
+Key points:
+
+- Neon pooling uses PgBouncer.
+- Add `-pooler` to endpoint hostnames to use pooled connections.
+- Pooling is especially important in serverless runtimes with bursty concurrency.
+
+Link: https://neon.com/docs/connect/connection-pooling.md
+
+## IP Allow Lists
+
+Use this when the user needs to restrict database access by trusted networks, IPs, or CIDR ranges.
+
+Link: https://neon.com/docs/introduction/ip-allow.md
+
+## Logical Replication
+
+Use this when integrating CDC pipelines, external Postgres sync, or replication-based data movement.
+
+Key points:
+
+- Neon supports native logical replication workflows.
+- Useful for replicating to/from external Postgres systems.
+
+Link: https://neon.com/docs/guides/logical-replication-guide.md

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

@@ -0,0 +1,281 @@
+---
+name: neon-postgres-branches
+description: >-
+  Choose and create the right Neon branch type for testing and development.
+  Use when users ask about Neon branching, migration testing with real data,
+  isolated test environments, schema-only branch workflows for sensitive data,
+  or branch creation via Neon CLI or Neon MCP. Triggers include "Neon branch",
+  "test migrations safely", "branch production data", "schema-only branch",
+  "reset branch" and "sensitive data testing".
+---
+
+# Neon Postgres Branching
+
+The outcome of this skill should be a created Neon branch (or a clear, actionable next step if creation cannot proceed).
+Choose the correct branch type, then execute branch creation via MCP or CLI.
+
+- **Normal branch** for realistic migration and query testing with real data.
+- **Schema-only branch (Beta)** for sensitive data workflows where structure is needed without copying rows.
+
+## Branch Type Decision
+
+Use this decision rule first:
+
+1. If the user wants to test complex migrations, performance, or behavior against production-like data, choose a **normal branch**.
+2. If the user needs to avoid copying sensitive data, choose a **schema-only branch**.
+
+If the request is ambiguous, ask one clarifying question:
+"Do you need realistic data for testing, or only schema structure because the data is sensitive?"
+
+## Tool Selection: CLI or MCP
+
+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
+
+### Selection order
+
+1. Check MCP first in MCP-enabled environments:
+   - If Neon MCP tools are available and authenticated (for example, listing projects works), use MCP.
+2. If MCP is unavailable or not authenticated, check CLI:
+   - Run `neon --version` to confirm CLI is installed.
+   - Run `neon projects list` to confirm auth/context.
+3. If CLI is missing, direct installation via quickstart.
+4. If CLI is installed but not authenticated, guide the user through `neon auth` (or API key auth), then continue.
+5. If both MCP and CLI paths are unsuccessful, use the Neon REST API:
+   - https://neon.com/docs/guides/branching-neon-api.md
+
+### MCP branch flow
+
+1. Choose normal vs schema-only based on data sensitivity and migration-testing goals.
+2. Use branch tools (for example, `create_branch`) to create the branch.
+3. Validate with read tools (for example, `describe_branch`).
+4. For migration workflows, prefer branch-based migration flows before applying to main.
+
+## Create a Normal Branch (Preferred for Real-Data Migration Testing)
+
+Use this when the user needs realistic testing conditions.
+Real production-like data can expose edge cases your seed or data migration scripts miss, which helps catch migration issues before going live.
+
+Link: https://neon.com/docs/introduction/branching.md
+
+### Steps
+
+1. Use MCP if already available/authenticated; otherwise verify CLI with `neon --version`.
+2. Ensure project context is set (`neon set-context --project-id <your-project-id>`) or include `--project-id` on commands.
+3. Create branch:
+
+```bash
+neon branches create \
+  --name <branch-name> \
+  --parent <parent-branch-id-or-name> \
+  --expires-at 2026-12-15T18:02:16Z
+```
+
+4. Optionally fetch a connection string for the new branch:
+
+```bash
+neon connection-string <branch-name>
+```
+
+## Create a Schema-Only Branch (Beta, Sensitive Data)
+
+Use this when users must not copy production rows into the test branch.
+
+Link: https://neon.com/docs/guides/branching-schema-only.md
+
+### Steps
+
+1. Use MCP if already available/authenticated; otherwise verify CLI with `neon --version`.
+2. Create schema-only branch:
+
+```bash
+neon branches create \
+  --name <schema-only-branch-name> \
+  --parent <parent-branch-id-or-name> \
+  --schema-only \
+  --expires-at 2026-12-15T18:02:16Z
+```
+
+If multiple projects exist, include:
+
+```bash
+neon branches create \
+  --name <schema-only-branch-name> \
+  --parent <parent-branch-id-or-name> \
+  --schema-only \
+  --project-id <your-project-id> \
+  --expires-at 2026-12-15T18:02:16Z
+```
+
+### Beta Support Guidance (Mandatory)
+
+Schema-only branching is in Beta. If users report unexpected behavior, errors, or missing capabilities:
+
+1. Ask them to share feedback in the Neon Console:
+   - https://console.neon.tech/app/projects?modal=feedback
+2. Recommend opening a support conversation in the Neon Discord:
+   - https://discord.gg/92vNTzKDGp
+
+## Reset from parent
+
+Use this when a child branch has drifted and the user wants a clean refresh from the parent branch's latest schema and data.
+
+Link: https://neon.com/docs/guides/reset-from-parent.md
+
+### What it does
+
+- Fully replaces the child branch schema and data with the parent's latest state.
+- Does not merge; local changes on the child branch are lost.
+- Keeps the same connection details, but active connections are briefly interrupted during reset.
+
+### When to recommend it
+
+- Development or staging branch is too far behind production.
+- User wants to start a new feature from a clean parent-aligned state.
+- Team wants to refresh staging from production for consistent testing baselines.
+
+### Hard constraints and blockers
+
+- Only child branches can be reset (root branches and schema-only root branches cannot be reset from parent).
+- If the target branch has children, reset is blocked until those child branches are removed.
+- After a parent branch is restored from snapshot, reset-from-parent may be unavailable for up to 24 hours.
+- Reset-from-parent always uses the current parent state; use Instant restore for point-in-time recovery needs.
+
+### CLI usage
+
+```bash
+neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
+```
+
+If project context is not already set, include project ID:
+
+```bash
+neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
+```
+
+`--preserve-under-name` keeps the pre-reset state as a backup branch for rollback, but adds one extra branch to clean up later.
+
+Optional context setup to avoid repeating `--project-id`:
+
+```bash
+neon set-context --project-id <project-id>
+```
+
+### Console and API usage
+
+- **Console:** Open the target child branch, then select **Reset from parent** from **Actions**.
+- **API:** Use the restore endpoint for the branch and set `source_branch_id` to the parent branch ID.
+
+## Notes and Caveats
+
+- Schema-only branches are for structure-only cloning and sensitive/compliant data controls.
+- Schema-only branches are independent root branches (no parent branch and no shared history), so reset-from-parent does not apply.
+- For migration testing that depends on real-world row shapes, volumes, and edge cases, prefer normal branches.
+- Root branch allowances and per-branch storage limits can cap how many schema-only branches users can create.
+- If a user is unsure, default recommendation is:
+  - **Normal branch** for migration validation.
+  - **Schema-only branch** for compliance and privacy constraints.
+
+## Useful Workflow Patterns
+
+If the user asks for process recommendations (not just a single command), suggest these:
+
+- **One branch per PR:** Create branch when PR opens, delete when merged/closed, keep migration tests isolated.
+- **One branch per test run:** Create branch at pipeline start, run migrations/tests, delete at end for deterministic CI.
+- **One branch per developer:** Isolated dev environments with production-like shape; avoid team collisions on shared test data.
+- **PII-aware branching:** If production has sensitive data, derive dev/PR branches from an anonymized branch or use schema-only branches.
+- **Ephemeral lifecycle hygiene:** Set branch expiration and automate cleanup so old branches do not accumulate avoidable storage/history cost.
+
+### Post-creation environment update prompt
+
+After branch creation, ask whether the user wants to update local environment credentials to point at the new branch.
+
+- Ask: "Do you want me to update your `.env` `DATABASE_URL` to this new branch connection string?"
+- If yes, write the new branch connection string to the requested env file/key.
+- If no, leave credentials unchanged and share the connection string for manual use.
+- Never overwrite an existing env key without explicit confirmation.
+
+## Neon Infrastructure as Code (`neon.ts`)
+
+Beyond creating branches imperatively (CLI / MCP / API above), you can **program what configuration new branches receive** declaratively in `neon.ts` — Neon's infrastructure-as-code file (see the `neon` skill for the full reference). The `branch` property is a function of the branch being evaluated that returns its settings, so every branch born from your project gets a consistent lifecycle and compute profile without per-branch flags.
+
+```bash
+npm i @neon/config
+```
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  branch: (branch) => {
+    if (branch.exists) return {}; // never reconcile existing branches
+    if (branch.isDefault) return { protected: true };
+    if (branch.name.startsWith("preview/") || branch.name.startsWith("dev")) {
+      return {
+        parent: "main",
+        ttl: "7d", // ephemeral: auto-expire 7 days after creation (max 30d)
+        postgres: {
+          computeSettings: {
+            autoscalingLimitMinCu: 0.25, // scale to zero
+            autoscalingLimitMaxCu: 1, // keep throwaway branches cheap
+            suspendTimeout: "5m",
+          },
+        },
+      };
+    }
+    return {};
+  },
+});
+```
+
+The closure receives a read-only descriptor of the target branch — `name`, `exists`, `isDefault`, `parentId`, and more — and returns the tuning to apply: `parent`, `ttl` (auto-expiry), `protected`, and `postgres.computeSettings`. This is the declarative complement to the **Ephemeral lifecycle hygiene** and per-PR / per-test patterns above: instead of remembering `--expires-at` on every `neon branches create`, the TTL and compute profile live in version control and apply to every matching branch.
+
+Because `neon checkout` applies this policy when it **creates** a branch, a fresh `preview/*` or `dev-*` branch comes up already expiring and scaled-to-zero. Checking out an _existing_ branch doesn't reconcile it — run `neon deploy` (alias for `neon config apply`) to apply changes to a branch that already exists.
+
+## Branching in CI/CD
+
+Common CI/CD use cases for Neon branches:
+
+- **Per-PR preview deployments:** Branch on PR open, deploy the preview against it, delete on close. Each PR gets an isolated database branch. Injecting the branch's `DATABASE_URL` into the deployed app is hosting-provider-specific — see [preview-branches-with-cloudflare](https://github.com/neondatabase/preview-branches-with-cloudflare), [preview-branches-with-vercel](https://github.com/neondatabase/preview-branches-with-vercel), or [preview-branches-with-fly](https://github.com/neondatabase/preview-branches-with-fly) for tested patterns.
+- **Migration testing in CI:** Run risky schema changes against a branch with production-like data before merge.
+- **Schema diff visibility:** Use the [schema-diff GitHub Action](https://github.com/marketplace/actions/neon-schema-diff-github-action) to auto-comment a DB-layer diff on the PR.
+
+## Examples
+
+### Example 1: Migration testing with realistic data
+
+**User input:** "I need to test a risky migration against production-like data."
+
+**Agent output shape:**
+
+1. Recommend a normal branch and explain why.
+2. Share docs link: https://neon.com/docs/introduction/branching
+3. Check the available/authenticated tool path first (MCP, otherwise CLI with `neon --version`).
+4. Provide commands:
+   - `neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z`
+   - `neon connection-string migration-test`
+
+### Example 2: Sensitive data development workflow
+
+**User input:** "We cannot copy production data because of compliance."
+
+**Agent output shape:**
+
+1. Recommend schema-only branch and explain why.
+2. Share docs link: https://neon.com/docs/guides/branching-schema-only
+3. Check the available/authenticated tool path first (MCP, otherwise CLI with `neon --version`).
+4. Provide command:
+   - `neon branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z`
+5. Mention Beta support path:
+   - https://console.neon.tech/app/projects?modal=feedback
+   - https://discord.gg/92vNTzKDGp
+
+## Further reading
+
+- https://neon.com/docs/guides/branch-expiration.md
+- https://neon.com/docs/guides/neon-github-integration.md
+- https://neon.com/docs/ai/neon-mcp-server.md
+- https://neon.com/branching