@damiangilgonzalez/harness 1.3.7

package/skills/n8n/references/auth-and-selfhost.md

@@ -0,0 +1,62 @@
+# n8n auth, self-host vs cloud, and pointing n8n-mcp
+
+## Get an API key
+
+1. In n8n, open **Settings → n8n API**.
+2. **Create an API key.** Prefer a **scoped** key — pick only the resource scopes the automation needs
+   (e.g. `workflow:read`, `workflow:create`, `workflow:execute`, `execution:read`). An unscoped key can
+   do everything the user can, including delete.
+3. Copy it once (it is shown once) and store it as `N8N_API_KEY`. Rotate by deleting + recreating.
+
+Every REST call carries it as a header: `X-N8N-API-KEY: <key>`. It is NOT a bearer token and NOT in
+the query string.
+
+```bash
+export N8N_API_KEY="n8n_api_..."
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # host root; append /api/v1 for REST
+```
+
+## Self-host vs cloud — what actually differs
+
+| | Self-host | Cloud (`*.app.n8n.cloud`) |
+|---|---|---|
+| API base | `{host}/api/v1` (e.g. `http://localhost:5678/api/v1`) | `https://<tenant>.app.n8n.cloud/api/v1` |
+| API surface | **identical** | **identical** |
+| Interactive Swagger | **Yes** at `/api/v1/docs` | **No** — work from docs.n8n.io |
+| Where data lives | your infra | n8n's | 
+| Enabling the API | on by default; can be toggled via `N8N_PUBLIC_API_DISABLED=true` | always on |
+| Base URL override | `WEBHOOK_URL` / `N8N_HOST`/`N8N_PROTOCOL`/`N8N_PORT` shape the host + webhook URLs | fixed |
+
+The only thing that changes between environments is the host and (self-host) the Swagger page.
+Scripts written against one work against the other by swapping `N8N_API_URL`.
+
+Webhook URLs on self-host derive from `WEBHOOK_URL` (or host/protocol/port). If your production webhook
+URLs look wrong (localhost behind a proxy), that env var is usually why.
+
+## Pointing n8n-mcp at your instance
+
+`n8n-mcp` reads the **same two env vars** for its management tier:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud
+N8N_API_KEY=n8n_api_...
+```
+
+Ways to run it:
+
+- **Hosted** — `dashboard.n8n-mcp.com`: add an instance (URL + key), get an MCP endpoint. Fastest trial;
+  free tier caps daily tool calls.
+- **Local (npx)** — run the `n8n-mcp` package and register it in your MCP client's config
+  (Claude Code / Claude Desktop / Cursor / Windsurf), passing the two env vars.
+- **Docker** — the repo ships an image; inject the env vars.
+
+Node-knowledge tools work with **no** auth; only the management tools need the two vars. Confirm the
+link with `n8n_health_check` — it reports reachability and which features (e.g. the `/execute`
+endpoint) the target instance supports.
+
+## Governance quick-set
+
+- **Scope the key** at creation (least privilege) — see above.
+- **`DISABLED_TOOLS`** on n8n-mcp to gate destructive tools — see `n8n-mcp-tools.md`.
+- **Never** commit `N8N_API_KEY` or inline node-credential secrets in a workflow payload; reference
+  credentials from the n8n credential store by id/name.

package/skills/n8n/references/n8n-mcp-tools.md

@@ -0,0 +1,84 @@
+# n8n-mcp — tool reference & governance
+
+`n8n-mcp` (github.com/czlonkowski/n8n-mcp, ~22k★, the de-facto community standard) is an MCP server
+that gives an agent two things: **offline knowledge** of n8n's node/expression catalogue, and
+**management** of a live instance via its REST API. Distinct from n8n's own first-party built-in MCP
+node, which lets a *workflow* act as an MCP server/client — that is not this.
+
+Tool names and counts move; **verify against the running server's tool list** (or
+`dashboard.n8n-mcp.com` / the repo docs) before relying on any one name.
+
+## Two tiers, two auth requirements
+
+| Tier | Needs auth? | Purpose |
+|---|---|---|
+| **Node-knowledge tools** | **No** | Search/describe nodes, get property essentials, validate a node's config, browse templates — all offline. Safe to expose broadly. |
+| **Management tools** | **Yes** — `N8N_API_URL` + `N8N_API_KEY` | CRUD/validate/test/run/inspect a real instance. These are the ones governance applies to. |
+
+Set the same two env vars the REST API uses:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud   # host root, whole value
+N8N_API_KEY=n8n_api_...
+```
+
+Without them the server still runs — you just get the node-knowledge tier only.
+
+## Node-knowledge tools (no auth)
+
+- `search_nodes`, `list_nodes`, `list_ai_tools` — find the right node.
+- `get_node_essentials`, `get_node_info`, `get_node_documentation` — properties & docs for a node type.
+- `validate_node_operation`, `validate_node_minimal` — check a single node's config before you wire it.
+- `search_templates`, `get_template` — reuse community workflow templates.
+
+Use these to author node JSON correctly instead of guessing `typeVersion`/property shapes.
+
+## Management tools (need `N8N_API_URL` + `N8N_API_KEY`)
+
+| Tool | Does |
+|---|---|
+| `n8n_create_workflow` | Create from a full workflow object. |
+| `n8n_get_workflow` | Fetch one workflow (export before delete/replace). |
+| `n8n_list_workflows` | List/filter workflows. |
+| `n8n_update_full_workflow` | Replace the whole workflow (like REST `PUT`). |
+| `n8n_update_partial_workflow` | **Atomic ordered batch of targeted edits** — if any op fails, nothing is saved. Prefer this for edits. |
+| `n8n_delete_workflow` | **Hard delete.** Export first. |
+| `n8n_validate_workflow` | Structural/connection/expression validation of a workflow object. |
+| `n8n_autofix_workflow` | Repair common errors and return fixed JSON. |
+| `n8n_test_workflow` | Trigger a run for testing. |
+| `n8n_executions` | List/inspect execution runs. |
+| `n8n_workflow_versions` | Version history of a workflow. |
+| `n8n_deploy_template` | Deploy a catalogue template to the instance. |
+| `n8n_manage_credentials` | Create/manage credentials (secrets not readable back). |
+| `n8n_manage_datatable` | Manage n8n data tables. |
+| `n8n_health_check` | Confirm API reachability + which features the instance supports. |
+| `n8n_audit_instance` | Security audit (built-in audit API + deep workflow scan). |
+
+**Note on activate/deactivate:** n8n-mcp intentionally does not surface these as tools (activation has
+live side effects). Flip a workflow live with the REST `POST /workflows/{id}/activate` endpoint (see
+`rest-api-cheatsheet.md`) or the UI. Verify the current tool list in case this changes.
+
+## Governance — `DISABLED_TOOLS`
+
+For agent-facing deployments, disable destructive/write tools with a comma-separated env var:
+
+```bash
+# read-only agent: no create/replace/delete/autofix/test/template/credential/datatable writes
+DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable
+```
+
+Layer it with a **scoped API key** (grant only `workflow:read`/`execution:read` for a monitoring
+agent) so a disabled tool can't be worked around and the key itself can't mutate. Two independent
+locks: the tool gate and the key scope.
+
+## Sketch: agent-driven deploy
+
+```
+search_nodes / get_node_essentials     → get the exact node property shapes
+n8n_validate_workflow { workflow }      → catch structural errors offline
+n8n_autofix_workflow  { workflow }      → auto-repair, re-validate
+n8n_create_workflow   { name, nodes, connections, settings }  → capture returned id
+n8n_test_workflow     { id }            → confirm it runs
+# then activate via REST /workflows/{id}/activate (no MCP tool for it)
+n8n_executions        { workflowId: id } → confirm the live run
+```

package/skills/n8n/references/rest-api-cheatsheet.md

@@ -0,0 +1,94 @@
+# n8n public REST API — cheat sheet
+
+Base URL: `{host}/api/v1`. Auth header on every call: `X-N8N-API-KEY: $N8N_API_KEY`.
+Same surface on self-host and `*.app.n8n.cloud`. Self-host has interactive Swagger at
+`{host}/api/v1/docs`; cloud does not. Verify shapes at author time — n8n ships often.
+
+Set once:
+
+```bash
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # or http://localhost:5678
+export N8N_API_KEY="n8n_api_..."
+auth=(-H "X-N8N-API-KEY: $N8N_API_KEY")
+```
+
+## Workflows
+
+| Verb & path | What it does | Notes |
+|---|---|---|
+| `POST /workflows` | Create | Body needs `name, nodes, connections, settings`. `active` + `tags` in the body are **ignored** (read-only). Returns the new object incl. `id`. |
+| `GET /workflows/{id}` | Get one | The full exportable JSON. Use to back up before delete/replace. |
+| `GET /workflows` | List | Query: `limit` (default ~100), `cursor`, `active=true|false`, `tags`, `name`, `projectId`. Paginate with the returned `nextCursor`. |
+| `PUT /workflows/{id}` | **Full replace** | Send the WHOLE object; omitted fields are dropped. GET → mutate → PUT. |
+| `DELETE /workflows/{id}` | **Hard delete** | No trash, no undo. Export first. |
+| `POST /workflows/{id}/activate` | Activate | The ONLY way to go live — the body `active` flag never does it. |
+| `POST /workflows/{id}/deactivate` | Deactivate | Same, in reverse. |
+| `POST /workflows/{id}/execute` | Run by id | **Recent (PR #20234); older instances 404.** Runs `executeManually`; **accepts no custom input** — needs `workflow:execute` scope. |
+| `PUT /workflows/{id}/tags` | Set tags | Tags are managed here, not in the create/update body. |
+| `PUT /workflows/{id}/transfer` | Move to a project | Enterprise/projects. |
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" "${auth[@]}" \
+  -H "Content-Type: application/json" -d @workflow.json
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50&active=true" "${auth[@]}"
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}" > backup-$ID.json
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate" "${auth[@]}"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute"  "${auth[@]}"
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}"
+```
+
+Paginate:
+
+```bash
+cursor=""
+while :; do
+  page=$(curl -sS "$N8N_API_URL/api/v1/workflows?limit=100&cursor=$cursor" "${auth[@]}")
+  echo "$page" | jq -r '.data[].id'
+  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
+  [ -z "$cursor" ] && break
+done
+```
+
+## Executions
+
+| Verb & path | What it does |
+|---|---|
+| `GET /executions` | List runs. Query: `workflowId`, `status` (`success|error|waiting`), `limit`, `cursor`, `includeData=true`. |
+| `GET /executions/{id}` | One run; `?includeData=true` for the full item data. |
+| `DELETE /executions/{id}` | Delete a run's stored data. |
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&status=error&limit=20" "${auth[@]}"
+```
+
+## Triggering a run WITH input
+
+`/execute` takes no body data. To pass runtime params, the workflow's trigger must be a **Webhook**
+node; POST to its URL:
+
+- Test URL (only while the editor's "Listen for test event" is armed): `{host}/webhook-test/<path>`
+- Production URL (only once the workflow is active): `{host}/webhook/<path>`
+
+```bash
+curl -sS -X POST "$N8N_HOST/webhook/my-path" -H "Content-Type: application/json" -d '{"orderId":123}'
+```
+
+## Other resources
+
+- `GET/POST/DELETE /credentials` — create/delete credentials and `GET /credentials/schema/{type}` for
+  the field shape. **You cannot read secrets back.** Reference existing creds from a workflow by id/name.
+- `GET/POST/PUT/DELETE /tags`, `/projects`, `/variables`, `/users` (admin), `/source-control/pull`,
+  `/audit` (instance security audit).
+
+## API-key scopes (least privilege)
+
+Create a **scoped** key in Settings → n8n API. Scopes are grouped by resource, e.g. `workflow:read`,
+`workflow:create`, `workflow:update`, `workflow:delete`, `workflow:execute`, `execution:read`,
+`credential:create`, `tag:*`. Grant only what a given automation needs — e.g. a read-only dashboard
+key gets `workflow:read` + `execution:read` and nothing that can mutate or run.
+
+## Error responses
+
+`401` bad/missing key · `403` key lacks the scope · `404` no such id (or `/execute` on an instance
+too old to have it) · `400` malformed body (e.g. missing `connections`) · `500` server-side (often a
+node the instance doesn't have installed).

package/skills/neon/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: neon
+description: "Use when you have picked Neon (serverless Postgres) and need to connect correctly from a serverless or edge runtime, wire database branching into dev, preview and CI, or stop being burned by scale-to-zero cold starts and pooler limits — including choosing HTTP versus WebSocket connections and pooled versus direct endpoints for migrations. NOT generic Postgres schema, index, EXPLAIN, RLS or migration-engine work (that is `postgresdb`)."
+tags: [neon, postgres, serverless, database, branching, edge]
+recommends: [postgresdb, drizzle-orm, prisma-orm, vercel]
+origin: risco
+---
+
+# Neon — serverless Postgres as a platform
+
+Neon is Postgres with three platform features the engine doesn't have: a **serverless driver** that
+talks over HTTP/WebSocket (so you can query from edge runtimes), **built-in connection pooling**, and
+**copy-on-write branching** that makes a fork of production data appear instantly. This skill owns
+that platform layer. The Postgres *engine* underneath — schema, indexes, EXPLAIN, RLS, zero-downtime
+DDL — is identical to any Postgres 16 and belongs to `../postgresdb/SKILL.md`. Don't re-derive engine
+craft here; connect correctly and branch correctly.
+
+## When to use / When NOT to use
+
+**When to use:**
+
+- Code imports `@neondatabase/serverless`, or `DATABASE_URL` points at `*.neon.tech` / `*.aws.neon.tech`.
+- Connecting from Vercel (Edge/Node), Cloudflare Workers, AWS Lambda, or any serverless/edge function — choosing HTTP `neon()` vs WebSocket `Pool`.
+- Setting up branching: dev branch off production, a branch per PR in CI, `neonctl` usage, the Neon + Vercel preview integration.
+- Neon-specific symptoms: cold start after scale-to-zero, "too many connections" despite being serverless, pooled-vs-direct string confusion, autoscaling CU sizing/cost.
+- Picking the connection string for migrations (direct) vs app queries (pooled).
+
+**When NOT to use — route to the sibling:**
+
+- Schema design, index choice, EXPLAIN/ANALYZE, query tuning, RLS, VACUUM, partitioning, expand-contract migrations → `../postgresdb/SKILL.md`. Neon adds nothing to the engine; defer.
+- Drizzle schema/migrations → `../drizzle-orm/SKILL.md`; Prisma → `prisma-orm`. Neon supplies only the *driver adapter* line.
+- A different managed Postgres/BaaS: Supabase (auth + storage + realtime) → `supabase`; PlanetScale → `planetscale`; Turso/libSQL → `sqlite-turso`.
+- Where to deploy the app talking to Neon → `../vercel/SKILL.md` / `cloudflare` / `railway`.
+- Backup/PITR strategy as a discipline → `backups` (Neon branch-as-restore is mentioned here, not owned).
+
+## Non-negotiables
+
+1. A WebSocket `Pool`/`Client` is **created and closed inside one request handler** — never at module scope in a serverless function. Module scope = a connection that outlives the invocation and leaks.
+2. **App queries use the pooled string** (host contains `-pooler`). **Migrations / DDL / advisory locks / session features use the direct string** (no `-pooler`). Mixing them is the #1 Neon foot-gun.
+3. The HTTP `neon()` driver **always** uses the pooled endpoint — don't hand it a direct string and expect session state.
+4. HTTP `neon()` has **no interactive transactions**. Need `BEGIN ... COMMIT` across round-trips? Use `sql.transaction([...])` (batched, non-interactive) or a WebSocket `Pool`.
+5. On Node.js ≤ 21 you **must** set `neonConfig.webSocketConstructor = ws` before opening a Pool/Client. Node 22+ and edge runtimes have a global `WebSocket`; don't set it there.
+6. Pin the driver: `@neondatabase/serverless` is at **v1.1.0** (npm latest, 2026-04-17). It is a drop-in replacement for `pg`.
+
+## Pick your connection method
+
+Keyed by runtime and what the query needs. Pick the lightest transport that satisfies the need.
+
+| You need | Use | Why |
+| --- | --- | --- |
+| One independent read/write per request (edge, Lambda, RSC) | HTTP `neon()` | Single fetch round-trip (~3 round trips vs ~8 for TCP setup); no connection to manage or leak. |
+| Several queries that must be atomic, no logic between them | `sql.transaction([q1, q2])` over HTTP | One round-trip, real transaction, still no socket lifecycle. |
+| Interactive transaction — read a row, branch in app code, then write | WebSocket `Pool` (open+close in handler) | HTTP can't hold `BEGIN` open; WebSocket keeps the session alive within the request. |
+| Full `pg`-API compatibility (cursors, LISTEN/NOTIFY, COPY) | WebSocket `Client`/`Pool` | HTTP is one-shot; node-postgres semantics need the socket. |
+| Migrations / DDL / `pg_advisory_lock` / session GUCs | direct (non-`-pooler`) string with `pg` or WebSocket `Client` | PgBouncer transaction-pooling breaks session-level state. |
+
+If you're behind Drizzle or Prisma, you don't call these directly — you pass the driver to the
+adapter. See the ORM pointers below.
+
+## Connection strings: pooled vs direct
+
+Neon gives every branch two connection strings that differ in **one** thing: the host of the pooled
+one contains `-pooler`.
+
+```text
+pooled:  postgresql://user:pass@ep-cool-name-123456-pooler.us-east-2.aws.neon.tech/db?sslmode=require
+direct:  postgresql://user:pass@ep-cool-name-123456.us-east-2.aws.neon.tech/db?sslmode=require
+```
+
+| Use case | String | Reason |
+| --- | --- | --- |
+| App runtime (queries from your functions) | **pooled** (`-pooler`) | PgBouncer fans many short-lived serverless invocations onto a small pool; up to 10,000 concurrent client connections per project. |
+| HTTP `neon()` driver | **pooled** (it forces it regardless) | The HTTP path is stateless; pooling is the right model. |
+| Migrations, DDL, schema introspection | **direct** | Transaction pooling drops session state; advisory locks and prepared statements need a stable session. |
+| `psql` interactive / debugging | **direct** | You want one real session, not a pooled handle. |
+
+Bad → Good for a typical setup:
+
+```bash
+# Bad: one string everywhere — migrations sporadically fail under PgBouncer.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"
+
+# Good: split them. App uses the pooled one; the migration tool uses DIRECT.
+DATABASE_URL="postgresql://...-pooler.../db?sslmode=require"          # app runtime
+DIRECT_URL="postgresql://....../db?sslmode=require"                    # migrations/DDL
+```
+
+## Serverless driver patterns
+
+All examples assume `@neondatabase/serverless@1.1.0`.
+
+HTTP one-shot — the default for edge/serverless reads and writes:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!); // pooled endpoint, no socket to manage
+export async function getUser(id: string) {
+  const [row] = await sql`select id, email from users where id = ${id}`;
+  return row; // parameterized; ${id} is bound, not interpolated
+}
+```
+
+Batched atomic writes over HTTP — atomicity without a WebSocket and without interactivity:
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+await sql.transaction([
+  sql`insert into orders (id, total) values (${id}, ${total})`,
+  sql`update inventory set qty = qty - 1 where sku = ${sku}`,
+]); // one round-trip, both succeed or both roll back
+```
+
+Interactive transaction — WebSocket `Pool`, opened **and closed inside the handler**:
+
+```ts
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws"; // Node ≤21 only; omit on edge / Node 22+
+
+neonConfig.webSocketConstructor = ws; // required on Node ≤21; do NOT set on edge runtimes
+
+export async function transfer(from: string, to: string, cents: number) {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // inside the handler
+  const client = await pool.connect();
+  try {
+    await client.query("begin");
+    const { rows } = await client.query("select balance from accounts where id=$1 for update", [from]);
+    if (rows[0].balance < cents) throw new Error("insufficient");
+    await client.query("update accounts set balance=balance-$1 where id=$2", [cents, from]);
+    await client.query("update accounts set balance=balance+$1 where id=$2", [cents, to]);
+    await client.query("commit");
+  } catch (e) {
+    await client.query("rollback");
+    throw e;
+  } finally {
+    client.release();
+    await pool.end(); // close before the function returns — no leaked connection
+  }
+}
+```
+
+Edge runtime (Vercel Edge, Cloudflare Workers): use HTTP `neon()`; the global `WebSocket` exists, so a
+`Pool` works without `ws`, but prefer HTTP unless you truly need an interactive transaction.
+
+ORM adapters — you wire the driver, the ORM owns the query API:
+
+- Drizzle: pass `neon()`/`Pool` into `drizzle-orm/neon-http` or `neon-serverless` → `../drizzle-orm/SKILL.md`.
+- Prisma: use the `@prisma/adapter-neon` driver adapter → `prisma-orm`.
+
+## Branching for dev / preview / CI
+
+A Neon branch is **copy-on-write**: created instantly with no data copied, it forks production at a
+point in time, gets its own compute endpoint, and scales to zero independently. That makes a branch a
+cheap, isolated, full-data environment — not a backup substitute (test the restore).
+
+| Situation | Do | Why |
+| --- | --- | --- |
+| Per-developer or per-PR isolated data | **branch off production** | Instant, real prod-shaped data, separate endpoint, auto scale-to-zero → near-free idle. |
+| A genuinely separate product/tenant with its own billing & limits | **new project** | Branches share the project's quotas and pooled-connection ceiling. |
+| Throwaway query you can run against staging | **same branch** | Don't manufacture a branch for a one-off SELECT. |
+
+`neonctl` (alias `neon`) drives create/connect/teardown:
+
+```bash
+neonctl branches create --name pr-$PR_NUMBER --parent main
+neonctl connection-string pr-$PR_NUMBER --pooled   # feed to the preview app
+neonctl branches delete pr-$PR_NUMBER              # on PR merge/close
+```
+
+**Vercel preview integration:** with the Neon + Vercel integration, each preview deployment gets its
+own branch forked from production, auto-deleted when the PR merges or closes — zero CI code. If you're
+not on Vercel, replicate it in CI: create branch on PR open → run migrations (direct string) → seed →
+expose the pooled connection string to the app → delete on PR close. Full GitHub Actions workflow,
+`neonctl` reference, and the Neon API endpoints: [branching-ci](references/branching-ci.md).
+
+**Branch-as-restore (PITR):** to recover, branch from an earlier point in time and either read from it
+or promote it. It's a fast undo, not a tested backup discipline — own that in `backups`.
+
+## Autoscaling & scale-to-zero
+
+Each branch's compute endpoint **autoscales** between a min and max CU (vCPU/RAM) on its own, with no
+noisy neighbors across branches. Idle compute **scales to zero** after **5 minutes** of inactivity
+(default), then resumes on the next connection with a millisecond-to-sub-second cold start.
+
+Cost mental model: non-prod branches sit at zero almost always, so a dozen PR branches cost close to
+nothing. The cold start is the price.
+
+Prod endpoint sizing checklist:
+
+- [ ] Set a sane **min/max CU** for the prod branch — not maxed "just in case" (you pay for the max headroom you actually use).
+- [ ] Latency-sensitive prod with sparse traffic? **Disable scale-to-zero** or set **min CU > 0** so there's no cold start in p99.
+- [ ] Treat the cold start as real: warm the connection on deploy, or accept it on non-prod and account for it in latency SLOs.
+- [ ] Keep non-prod branches on scale-to-zero — that's where the near-free economics come from.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `new Pool(...)` at module scope in a serverless function | Connection outlives the invocation; you exhaust the pool → "too many connections". | Create and `await pool.end()` inside the handler, or use HTTP `neon()`. |
+| Pooled (`-pooler`) string for migrations/DDL | PgBouncer transaction-pooling drops session state; advisory locks/prepared statements fail intermittently. | Use the **direct** string for migrations; pooled only for app runtime. |
+| Direct (non-`-pooler`) string as the app `DATABASE_URL` | No pooling → serverless concurrency exhausts raw connections fast. | App runtime always uses the **pooled** string. |
+| Expecting `BEGIN`/interactive txns from HTTP `neon()` | HTTP is one-shot, stateless — there's no open session to hold a transaction. | `sql.transaction([...])` for batched atomicity, or a WebSocket `Pool` for interactive. |
+| Opening a `Pool` without `neonConfig.webSocketConstructor = ws` on Node ≤21 | No global `WebSocket` → the connection silently fails. | Set `webSocketConstructor = ws` on Node ≤21; omit on edge / Node 22+. |
+| Ignoring scale-to-zero in p99 latency | First request after 5 min idle pays the resume cold start; users see a slow request. | Disable scale-to-zero or set min CU > 0 on latency-sensitive prod. |
+| One shared branch for all PRs | PRs clobber each other's data; no isolation. | One branch per PR, deleted on close. |
+| Treating a branch as a backup without testing restore | Branches share project quotas and aren't an exercised recovery path. | Verify branch-as-restore; own real backup strategy in `backups`. |
+| Maxing CU "to be safe" | You pay for headroom you don't use; autoscaling already handles spikes. | Set a realistic min/max; let autoscaling expand. |
+| Doing schema/index design in this skill | Engine craft is identical to any Postgres; duplicating it drifts. | Defer to `../postgresdb/SKILL.md`. |
+
+## Cross-references
+
+- Engine craft (schema, indexes, EXPLAIN, RLS, zero-downtime DDL): `../postgresdb/SKILL.md`.
+- Next.js App Router data layer that calls Neon: `../nextjs/SKILL.md`.
+- ORM query APIs over the Neon driver: `../drizzle-orm/SKILL.md`, `prisma-orm`.
+- Deployment targets: `../vercel/SKILL.md`, `cloudflare`, `railway`. Backups discipline: `backups`.
+- Other managed DBs (route away): `supabase`, `planetscale`, `sqlite-turso`.

package/skills/neon/evals/README.md

@@ -0,0 +1,11 @@
+# Evals for the `neon` skill
+
+These cases are routing and trigger checks, not executed code. Run them by reading each prompt and
+confirming the behavior: every `should_trigger` prompt should make an agent load and apply this skill
+(including the non-obvious "too many connections" / cold-start phrasings and the Spanish/Catalan
+ones); every `should_not_trigger` prompt should route to the named sibling (`postgresdb`,
+`drizzle-orm`, `supabase`, `vercel`, `backups`) instead of firing here. The `capability` case is a
+rubric: have an agent answer the Neon-wiring scenario and grade the response against each
+`must_include` item — pooled-vs-direct strings, HTTP vs WebSocket choice, Pool lifecycle inside the
+handler, atomic-operation handling, per-PR branching with teardown, and deferring engine craft to
+postgresdb. No network or database is required.

package/skills/neon/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: neon
+
+should_trigger:
+  - prompt: "Connecting to Neon from a Cloudflare Worker — should I use neon() or Pool?"
+    why: Core driver/transport decision for an edge runtime; the heart of this skill.
+  - prompt: "Set up a database branch per pull request so previews get isolated data."
+    why: Per-PR copy-on-write branching workflow, Neon's signature platform feature.
+  - prompt: "I keep getting 'too many connections' from my Vercel function hitting Neon."
+    why: Non-obvious foot-gun — pooled endpoint and module-scope Pool leak, not an engine issue.
+  - prompt: "The first request after the app's been idle a while is super slow against our Neon DB."
+    why: Non-obvious symptom phrasing for scale-to-zero cold start (5-min idle resume).
+  - prompt: "Conexión serverless a Postgres en Neon: ¿qué connection string uso para las migraciones?"
+    why: Spanish; pooled-vs-direct rule (migrations need the direct, non -pooler string).
+  - prompt: "Vull una branca de base de dades per cada PR amb neonctl i que s'esborri al tancar."
+    why: Catalan; per-PR branching with neonctl and teardown — directly in scope.
+
+should_not_trigger:
+  - prompt: "Design the schema and pick indexes for my orders table in Postgres."
+    route_to: postgresdb
+    why: Engine craft — provider-agnostic schema and indexing, identical on any Postgres 16.
+  - prompt: "Write the Drizzle schema and a migration for my Neon DB."
+    route_to: drizzle-orm
+    why: ORM authoring; Neon only supplies the driver adapter line, not the query/schema API.
+  - prompt: "Set up auth and storage with realtime subscriptions for my app."
+    route_to: supabase
+    why: Different BaaS owning auth/storage/realtime, not the Neon serverless-Postgres layer.
+  - prompt: "Deploy my Next.js app to Vercel with preview deployments."
+    route_to: vercel
+    why: Deployment target and platform config, not the database connection or branching.
+  - prompt: "Plan a backup and point-in-time recovery strategy for production."
+    route_to: backups
+    why: Backup discipline; Neon's branch-as-restore is mentioned but the strategy belongs to backups.
+
+capability:
+  - scenario: >
+      Wire a Next.js app deployed on Vercel to Neon. The agent must choose connection strings,
+      pick the right driver per access pattern, handle a multi-step atomic operation safely from a
+      serverless function, and outline per-PR branch isolation in CI.
+    must_include:
+      - Uses the pooled (-pooler) string for app runtime and the direct (non -pooler) string for migrations.
+      - HTTP neon() for one-shot read paths (edge/serverless, single round-trip).
+      - WebSocket Pool created AND closed inside the request handler, never at module scope.
+      - Uses sql.transaction([...]) or a WebSocket Pool for the multi-step atomic operation, not HTTP single statements expecting interactivity.
+      - Per-PR branch via neonctl or the Neon API with teardown on PR close.
+      - Defers schema and index design to postgresdb rather than redoing engine craft.

package/skills/neon/references/branching-ci.md

@@ -0,0 +1,86 @@
+# Per-PR Neon branching in CI
+
+Replicate the Neon + Vercel preview integration anywhere: create an isolated, full-data branch when a
+PR opens, migrate and seed it, hand the pooled connection string to the preview app, and delete the
+branch when the PR closes. A branch is copy-on-write (instant, no data copied) and scales to zero, so
+even a dozen open PRs cost almost nothing.
+
+## `neonctl` command reference
+
+`neonctl` (alias `neon`) is the official CLI. Authenticate in CI with `NEON_API_KEY`.
+
+| Command | Purpose |
+| --- | --- |
+| `neonctl branches create --name <n> --parent main` | Fork a new branch from production at the current point in time. |
+| `neonctl connection-string <branch> --pooled` | Print the **pooled** (`-pooler`) string for the app runtime. |
+| `neonctl connection-string <branch>` | Print the **direct** string for migrations/DDL. |
+| `neonctl branches list` | List branches (find a stale one to delete). |
+| `neonctl branches delete <branch>` | Tear the branch down on PR close. |
+
+## GitHub Actions: create on open, delete on close
+
+```yaml
+name: neon-pr-branch
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+env:
+  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+  NEON_PROJECT_ID: ${{ vars.NEON_PROJECT_ID }}
+
+jobs:
+  create_and_migrate:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm i -g neonctl
+      - name: Create branch
+        run: neonctl branches create --name pr-${{ github.event.number }} --parent main --project-id "$NEON_PROJECT_ID"
+      - name: Resolve strings
+        id: db
+        run: |
+          DIRECT=$(neonctl connection-string pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID")
+          POOLED=$(neonctl connection-string pr-${{ github.event.number }} --pooled --project-id "$NEON_PROJECT_ID")
+          echo "::add-mask::$DIRECT"; echo "::add-mask::$POOLED"
+          echo "direct=$DIRECT" >> "$GITHUB_OUTPUT"
+          echo "pooled=$POOLED" >> "$GITHUB_OUTPUT"
+      - name: Migrate + seed (DIRECT string — DDL needs a real session)
+        env:
+          DATABASE_URL: ${{ steps.db.outputs.direct }}
+        run: |
+          npm ci
+          npm run db:migrate
+          npm run db:seed
+      # Hand steps.db.outputs.pooled to the preview deploy as the app DATABASE_URL.
+
+  delete:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - run: npm i -g neonctl
+      - run: neonctl branches delete pr-${{ github.event.number }} --project-id "$NEON_PROJECT_ID"
+```
+
+Rules that keep this honest:
+
+- Migrations and seed run against the **direct** string — PgBouncer transaction-pooling breaks DDL and advisory locks.
+- The preview app gets the **pooled** (`-pooler`) string — serverless concurrency needs the pool.
+- The `closed` event covers both merge and abandon, so branches never accumulate.
+
+## Neon API (if you can't use the CLI)
+
+Same flow over REST with a bearer `NEON_API_KEY`:
+
+| Step | Endpoint |
+| --- | --- |
+| Create branch | `POST /api/v2/projects/{project_id}/branches` |
+| Get branch endpoints / connection URI | `GET /api/v2/projects/{project_id}/branches/{branch_id}/endpoints` |
+| Delete branch | `DELETE /api/v2/projects/{project_id}/branches/{branch_id}` |
+
+Pass `endpoints[].pooler_enabled` / request the pooled URI for the app, the plain URI for migrations.
+Engine-level migration mechanics (expand-contract, `CONCURRENTLY`, batched backfill) are not Neon's —
+see `../../postgresdb/SKILL.md`.