okengine 0.9.1 → 0.10.1

package/site/content/docs/providers/cockroachdb.mdx

@@ -0,0 +1,86 @@
+---
+title: "CockroachDB"
+description: "Distributed SQL — Cloud Connect dialog, verify-full + CA cert, CSL license, port 26257."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+CockroachDB speaks Postgres wire closely enough that `drivers.store.sql` stays
+`postgres`. Multi-region and distributed transactions are Cockroach's concern beneath
+that protocol.
+
+<Callout title="The one rule">
+  Use the Cloud Console **Connect** dialog and keep `sslmode=verify-full` with the downloaded CA —
+  `sslmode=require` alone is rejected for secure clusters.
+</Callout>
+
+## Find credentials (current console)
+
+1. Open [CockroachDB Cloud](https://cockroachlabs.cloud) → your **cluster**.
+2. Click **Connect** (cluster overview / top right).
+3. Open the **Connection string** tab (or **General connection string**).
+4. Expand **Download CA Cert** — run the provided command so `root.crt` lands in the
+   default Postgres cert directory (or note the path).
+5. Copy the `postgresql://…` string; paste the password when prompted (shown once for
+   new SQL users — reset under **SQL Users** if lost).
+
+```bash title="process env"
+DATABASE_URL=postgresql://user:password@….cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=/path/to/root.crt
+```
+
+Default SQL port is **26257**, not 5432.
+
+## Production guidance
+
+| Topic   | Guidance                                                                                |
+| ------- | --------------------------------------------------------------------------------------- |
+| TLS     | `verify-full` + `sslrootcert` — required for Cloud                                      |
+| Pooling | Prefer Cockroach's guidance / built-in limits; do not assume Neon-style `-pooler` hosts |
+| Regions | Configure survivability in the Console — opaque to the `postgres` driver                |
+
+CockroachDB Software License (since Nov 2024): Core open-source discontinued; free for
+orgs under $10M ARR with community support; paid tiers add dedicated support. Not OSI
+open source.
+
+## Real gotcha — CA cert path
+
+Copying the connection string without downloading the CA yields TLS verify failures
+even when the password is correct. The Connect dialog's download command and
+`sslrootcert=` must agree on the same file path in the environment that runs the app.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="certificate verify failed / SSL connection error">
+
+Missing or wrong `sslrootcert`. Re-download from **Connect → Download CA Cert**, point
+`sslrootcert` at that file, keep `sslmode=verify-full`. Using `require` without verify
+is not accepted for Cloud's default secure posture.
+
+</Accordion>
+<Accordion title="password authentication failed for user">
+
+Password is shown once at user creation. Reset under the cluster **SQL Users** page,
+then update `DATABASE_URL`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [YugabyteDB](/docs/providers/yugabytedb) — Apache 2.0 distributed alternative
+- [CockroachDB (self-hosted)](/docs/recipes/cockroachdb) — single-node Docker recipe
+- [Postgres (image)](/docs/recipes/postgres) — driver this backs
+- [Store · SQL](/docs/elements/store#sql) — schema workflows
+
+## Next
+
+<Cards>
+  <Card
+    title="YugabyteDB"
+    description="Apache-2.0 licensed alternative."
+    href="/docs/providers/yugabytedb"
+  />
+  <Card title="Neon" description="Serverless single-region option." href="/docs/providers/neon" />
+  <Card title="PgDog" description="Self-hosted pooling." href="/docs/recipes/pgdog" />
+</Cards>

package/site/content/docs/providers/digitalocean-caching.mdx

@@ -0,0 +1,88 @@
+---
+title: "DigitalOcean Managed Caching"
+description: "Valkey-backed DO Databases — Overview Connection Details, trusted sources, TLS-required high port."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+DigitalOcean's managed Redis offering moved to **Valkey** (Managed Caching) after Aiven
+stepped back from Redis. Wire protocol unchanged — `drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Databases → cluster → **Overview → Connection Details**. Copy the `rediss://` URI (public or
+  private). Add the client to **Trusted Sources** or you get connection refused.
+</Callout>
+
+## Find credentials (current control panel)
+
+1. [cloud.digitalocean.com/databases](https://cloud.digitalocean.com/databases) → click
+   the **Valkey / Caching** cluster.
+2. **Overview** → **Connection Details**:
+   - Toggle **Public network** vs **Private network** (VPC)
+   - Copy host, port, user, password, or the assembled connection string
+3. Password is hidden until you reveal/copy it in that panel.
+4. **Network Access** / trusted sources: add app Droplet, App Platform app, or VPC CIDR
+   (from Overview **VPC Network**) before connecting.
+
+```bash title="process env"
+REDIS_URL=rediss://default:PASSWORD@db-valkey-nyc1-….db.ondigitalocean.com:25061
+```
+
+Port is a **random high port** from Connection Details — not `6379`. TLS is required;
+there is no plaintext option.
+
+## Production guidance
+
+| Topic           | Guidance                                                                              |
+| --------------- | ------------------------------------------------------------------------------------- |
+| Engine          | **Valkey** on new clusters; older “Managed Redis” capped / unsupported past Redis 7.2 |
+| TLS             | Always — use `rediss://`                                                              |
+| Trusted sources | Hard firewall — missing entry ⇒ refused even with correct password                    |
+| VPC             | Prefer private connection string + VPC CIDR as a single trusted source                |
+
+Standalone **Upstash-on-DigitalOcean marketplace** listings are a different, deprecated
+product — not this Databases service.
+
+## Real gotcha — trusted sources
+
+Correct `REDIS_URL` from a laptop not in Trusted Sources fails with connection refused.
+Add your IP (or use a Droplet already allowed / VPC CIDR) under **Network Access**.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection refused (hostname)">
+
+Wrong port, or client IP not in trusted sources. Re-copy port from **Connection
+Details**; add the client under **Network Access → Trusted Sources**.
+
+</Accordion>
+<Accordion title="Connection refused (IP) on private hostname">
+
+Private URL used from outside the VPC. Switch to **Public network** details (and allow
+your IP), or run the app on a Droplet in the same VPC with the private URI.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Valkey (image)](/docs/recipes/valkey) — self-hosted peer
+- [Store · KV](/docs/elements/store#kv)
+- [Dragonfly Cloud](/docs/providers/dragonfly-cloud) — alternative managed KV
+
+## Next
+
+<Cards>
+  <Card
+    title="Dragonfly Cloud"
+    description="Another managed alternative."
+    href="/docs/providers/dragonfly-cloud"
+  />
+  <Card
+    title="Redis Cloud"
+    description="Vendor-native alternative."
+    href="/docs/providers/redis-cloud"
+  />
+  <Card title="Caddy" description="Local proxy pairing." href="/docs/recipes/caddy" />
+</Cards>

package/site/content/docs/providers/dragonfly-cloud.mdx

@@ -0,0 +1,82 @@
+---
+title: "Dragonfly Cloud"
+description: "Managed Dragonfly — data store row drawer, Redis-compatible Connection URI, TLS passkey, private network prod."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Dragonfly Cloud runs the same multi-threaded engine as the
+[Dragonfly image](/docs/recipes/dragonfly), with a managed endpoint.
+`drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Click the **data store row** to open the side drawer — copy the **Redis-compatible Connection
+  URI** (includes passkey). Paste it as `REDIS_URL`.
+</Callout>
+
+## Find credentials (current console)
+
+1. Open Dragonfly Cloud → **Data Stores**.
+2. Wait until **Status** is **Active**.
+3. Click the data store **row** (opens the configuration drawer).
+4. Copy:
+   - **Redis-compatible Connection URI** (e.g. `rediss://default:PASS@….dragonflydb.cloud:6385`)
+   - or host / port / `default` user / passkey separately
+5. Paste the URI into `REDIS_URL` unchanged when it already uses `rediss://`.
+
+```bash title="process env"
+REDIS_URL=rediss://default:PASSKEY@xxxxx.dragonflydb.cloud:6385
+```
+
+Smoke-check: `redis-cli -u "$REDIS_URL" PING`.
+
+## Production guidance
+
+| Topic           | Guidance                                                                     |
+| --------------- | ---------------------------------------------------------------------------- |
+| Public network  | TLS + passkey **on** by default — leave TLS enabled                          |
+| Private network | Recommended for production (peering) — passkey still required on public      |
+| HA              | Enable high availability in the data store settings before you need failover |
+| Driver          | Same `redis` driver as self-hosted Dragonfly                                 |
+| Port            | Drawer URI often uses **6385** (not 6379) — copy the URI wholesale           |
+
+Self-hosting comparison: the [Dragonfly image](/docs/recipes/dragonfly) needs
+`OKE_STORE_KV_PASSWORD` + `memlock`; Cloud replaces that with the drawer passkey.
+
+Do not reuse a self-hosted `REDIS_URL` without `rediss://` when the drawer shows TLS.
+
+## Real gotcha — connecting before Active
+
+The drawer is visible while the store is still provisioning; clients get connection
+errors until **Status = Active**. Wait for Active before wiring CI or app boot.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection refused / timeout while Status is not Active">
+
+Provisioning. Retry when the console shows **Active**. Do not rotate the passkey yet —
+confirm status first.
+
+</Accordion>
+<Accordion title="NOAUTH / WRONGPASS">
+
+URI missing the passkey, or passkey rotated in the drawer without updating env. Re-copy
+the Connection URI from the data store drawer after any rotation.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Dragonfly (image)](/docs/recipes/dragonfly) — self-hosted peer
+- [Store · KV](/docs/elements/store#kv)
+- [Upstash](/docs/providers/upstash) — serverless alternative
+
+## Next
+
+<Cards>
+  <Card title="Upstash" description="Serverless-friendly option." href="/docs/providers/upstash" />
+  <Card title="Redis Cloud" description="Vendor-native Redis." href="/docs/providers/redis-cloud" />
+  <Card title="YugabyteDB" description="Managed SQL-side pair." href="/docs/providers/yugabytedb" />
+</Cards>

package/site/content/docs/providers/elasticache.mdx

@@ -0,0 +1,92 @@
+---
+title: "Amazon ElastiCache"
+description: "AWS-managed Redis OSS or Valkey — Primary Endpoint, AUTH token, Redis OSS capped at 7.1, VPC-only."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+ElastiCache runs Redis OSS-compatible or Valkey engines inside your VPC. Both speak the
+same wire protocol — `drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Copy the **Primary Endpoint** (cluster mode disabled) from the ElastiCache console — not a replica
+  reader endpoint. Use `rediss://` when encryption in transit is on.
+</Callout>
+
+## Find credentials (current console)
+
+1. AWS Console → **ElastiCache** → **Valkey caches** or **Redis OSS caches**.
+2. Click the **cluster name** (not only the radio button).
+3. On the cluster detail page, copy:
+   - **Primary Endpoint** (+ port, usually `6379`) for cluster-mode **disabled**
+   - **Configuration Endpoint** for cluster-mode **enabled** (needs a cluster-aware
+     client — oke's single-URL driver expects non-cluster / primary)
+4. Auth: cluster **Connectivity** / **Auth token** (or Secrets Manager reference) —
+   set at creation or rotation; there is no “password eye” identical to Redis Cloud.
+5. Build `REDIS_URL` yourself:
+
+```bash title="process env"
+# Encryption in transit ON (default on many new clusters)
+REDIS_URL=rediss://:AUTH_TOKEN@my-cluster.xxxxx.ng.0001.use1.cache.amazonaws.com:6379
+
+# Transit encryption OFF
+# REDIS_URL=redis://:AUTH_TOKEN@my-cluster.xxxxx.ng.0001.use1.cache.amazonaws.com:6379
+```
+
+## Production guidance
+
+| Topic              | Guidance                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------- |
+| Networking         | **VPC-only** — app must share VPC, peering, or PrivateLink; no public hostname      |
+| Engine             | Redis OSS **or** Valkey — same `redis` driver                                       |
+| Cluster mode       | Prefer **disabled** + Primary Endpoint for oke's URL-shaped client                  |
+| Transit encryption | When enabled, scheme must be `rediss://`                                            |
+| AUTH               | Set at create/rotate — ElastiCache does not show a Redis-Cloud-style “eye” password |
+
+Reader endpoints exist for read scaling; oke's single `REDIS_URL` should target the
+**Primary Endpoint** so writes and Gate/Signal counters hit the primary.
+
+## Real gotcha — Redis OSS version cap
+
+ElastiCache **Redis OSS tops out at 7.1**. Versions **7.2+ are Valkey-only**. You can
+in-place upgrade Redis OSS → Valkey 7.2; planning a “Redis 7.2” engine on ElastiCache
+is a category error — pick Valkey or stay ≤7.1 on Redis OSS.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection timed out from laptop / CI">
+
+Expected — no public endpoint. Run the app in the VPC (ECS/EKS/EC2) or use a bastion /
+VPN. Security groups must allow the app SG → cache port.
+
+</Accordion>
+<Accordion title="WRONGPASS / NOAUTH after enabling AUTH">
+
+Token not embedded in `REDIS_URL`, or still using `redis://` against a TLS-required
+endpoint. Match scheme to **Encryption in-transit**, put the token after `rediss://:`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Redis (image)](/docs/recipes/redis) · [Valkey (image)](/docs/recipes/valkey)
+- [Memorystore](/docs/providers/memorystore) — GCP equivalent
+- [Store · KV](/docs/elements/store#kv)
+
+## Next
+
+<Cards>
+  <Card title="Memorystore" description="GCP's equivalent." href="/docs/providers/memorystore" />
+  <Card
+    title="Azure Cache for Redis"
+    description="Azure's equivalent."
+    href="/docs/providers/azure-redis"
+  />
+  <Card
+    title="Redis Cloud"
+    description="Vendor-neutral managed option."
+    href="/docs/providers/redis-cloud"
+  />
+</Cards>

package/site/content/docs/providers/index.mdx

@@ -0,0 +1,101 @@
+---
+title: "Providers"
+description: "Managed cloud SQL and Redis providers behind oke's postgres and redis drivers — dashboard click-paths, pooling, and gotchas."
+icon: "Cloud"
+source: "docs/spec/unified-theory.md"
+---
+
+Every provider below speaks a protocol oke already drives — Postgres wire or Redis wire.
+Hand the connection string to that driver; no new driver id, no Flow code changes.
+
+<Callout title="The one rule">
+  Vendor choice lives in a connection URL (`DATABASE_URL` / `REDIS_URL`) — never in
+  `drivers.store.sql` / `drivers.store.kv`, which only ever say `postgres` or `redis`.
+</Callout>
+
+## SQL providers
+
+Managed Postgres-wire databases — set `DATABASE_URL`, driver stays `postgres`.
+
+<Cards>
+  <Card
+    title="Neon"
+    description="Connect widget · pooled vs direct · cold start."
+    href="/docs/providers/neon"
+  />
+  <Card
+    title="Supabase"
+    description="Connect modes · :6543 vs :5432 · free pause."
+    href="/docs/providers/supabase"
+  />
+  <Card
+    title="CockroachDB"
+    description="Connect dialog · verify-full · CA cert."
+    href="/docs/providers/cockroachdb"
+  />
+  <Card
+    title="YugabyteDB"
+    description="YSQL on :5433 · Connect → Application."
+    href="/docs/providers/yugabytedb"
+  />
+</Cards>
+
+## Redis providers
+
+Managed Redis-wire caches — set `REDIS_URL`, driver stays `redis`.
+
+<Cards>
+  <Card
+    title="Redis Cloud"
+    description="Configuration tab · Connect wizard · rediss://"
+    href="/docs/providers/redis-cloud"
+  />
+  <Card
+    title="Amazon ElastiCache"
+    description="Primary Endpoint · Redis OSS ≤7.1."
+    href="/docs/providers/elasticache"
+  />
+  <Card
+    title="Google Memorystore"
+    description="Primary Endpoint IP · TLS on 6378."
+    href="/docs/providers/memorystore"
+  />
+  <Card
+    title="Azure Cache for Redis"
+    description="Access keys · TLS port 6380."
+    href="/docs/providers/azure-redis"
+  />
+  <Card
+    title="Upstash"
+    description="TCP rediss:// — not REST tokens."
+    href="/docs/providers/upstash"
+  />
+  <Card
+    title="Dragonfly Cloud"
+    description="Data store drawer · Connection URI."
+    href="/docs/providers/dragonfly-cloud"
+  />
+  <Card
+    title="DigitalOcean Managed Caching"
+    description="Connection Details · trusted sources."
+    href="/docs/providers/digitalocean-caching"
+  />
+</Cards>
+
+## Learn more
+
+- [Recipes](/docs/recipes) — self-hosted recipes for the same protocols
+- [Store](/docs/elements/store) — `sql` / `kv` facets
+- [Environment variables](/docs/reference/environment-variables) — URL precedence
+
+## Next
+
+<Cards>
+  <Card
+    title="Neon"
+    description="Start with a serverless SQL option."
+    href="/docs/providers/neon"
+  />
+  <Card title="Recipes" description="Run the same protocols yourself." href="/docs/recipes" />
+  <Card title="Store" description="The facets these drivers back." href="/docs/elements/store" />
+</Cards>

package/site/content/docs/providers/memorystore.mdx

@@ -0,0 +1,89 @@
+---
+title: "Google Cloud Memorystore"
+description: "GCP-managed Redis/Valkey — Instance details Primary Endpoint, AUTH string, TLS on 6378, VPC-only."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Memorystore for Redis (and the Valkey offering) is private-IP only inside your VPC.
+`drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Open the instance → **Connections** for **Primary Endpoint** + port; **Security** for the AUTH
+  string. There is no public hostname to paste.
+</Callout>
+
+## Find credentials (current console)
+
+1. Google Cloud Console → **Memorystore** → **Redis** (or Valkey) → click **Instance ID**.
+2. **Connections** section → copy **Primary Endpoint** (private IP) and **Port**
+   (usually `6379`).
+3. If AUTH is enabled: **Security** section → **AUTH string** (or
+   `gcloud redis instances get-auth-string INSTANCE --region=REGION`).
+4. If **in-transit encryption** is on: download the **TLS server certificate** from the
+   instance page; clients use port **6378** with that CA (not plain 6379).
+
+```bash title="process env"
+# AUTH on, transit encryption off (common default)
+REDIS_URL=redis://:AUTH_STRING@10.0.0.3:6379
+
+# Transit encryption on → port 6378 + rediss:// + CA configured in the client
+# REDIS_URL=rediss://:AUTH_STRING@10.0.0.3:6378
+```
+
+Cloud Run / Cloud Functions need a **Serverless VPC Access** connector on the same
+network.
+
+## Production guidance
+
+| Topic      | Guidance                                                                         |
+| ---------- | -------------------------------------------------------------------------------- |
+| Networking | Private IP only — never a public endpoint option                                 |
+| AUTH       | Optional but recommended; string is on the instance Security panel               |
+| TLS        | **Not** default — enable in-transit encryption explicitly; port becomes **6378** |
+| Tiers      | Basic vs Standard (replica) — pick before you need HA                            |
+
+## Real gotcha — TLS port flip
+
+Enabling in-transit encryption changes the client port to **6378** and requires the
+server CA. Leaving `REDIS_URL` on `:6379` after enabling TLS looks like a mysterious
+timeout — update port and scheme together.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection refused / timeout from Cloud Run">
+
+Missing Serverless VPC Access connector, or connector on the wrong VPC. Memorystore is
+unreachable from the public internet by design.
+
+</Accordion>
+<Accordion title="NOAUTH Authentication required">
+
+AUTH enabled but password omitted from `REDIS_URL`. Copy the AUTH string from
+**Security** and use `redis://:AUTH@ip:port`.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Redis (image)](/docs/recipes/redis) · [Valkey (image)](/docs/recipes/valkey)
+- [ElastiCache](/docs/providers/elasticache) — AWS equivalent
+- [Store · KV](/docs/elements/store#kv)
+
+## Next
+
+<Cards>
+  <Card title="ElastiCache" description="AWS's equivalent." href="/docs/providers/elasticache" />
+  <Card
+    title="Azure Cache for Redis"
+    description="Azure's equivalent."
+    href="/docs/providers/azure-redis"
+  />
+  <Card
+    title="Dragonfly Cloud"
+    description="Public TLS endpoint option."
+    href="/docs/providers/dragonfly-cloud"
+  />
+</Cards>

package/site/content/docs/providers/meta.json

@@ -0,0 +1,20 @@
+{
+  "title": "Providers",
+  "icon": "Cloud",
+  "pages": [
+    "index",
+    "---SQL providers---",
+    "neon",
+    "supabase",
+    "cockroachdb",
+    "yugabytedb",
+    "---Redis providers---",
+    "redis-cloud",
+    "elasticache",
+    "memorystore",
+    "azure-redis",
+    "upstash",
+    "dragonfly-cloud",
+    "digitalocean-caching"
+  ]
+}

package/site/content/docs/providers/neon.mdx

@@ -0,0 +1,115 @@
+---
+title: "Neon"
+description: "Serverless Postgres — Connect widget, pooled vs direct, scale-to-zero cold start, neon_superuser for pgvector."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+Neon separates storage from compute: branches are cheap copy-on-write metadata, and idle
+compute scales to zero. Wire protocol is plain Postgres — `drivers.store.sql` stays
+`postgres`.
+
+<Callout title="The one rule">
+  Copy the connection string from Neon's **Connect** widget. Prefer the pooled hostname for app
+  traffic and the direct hostname for migrations — never invent the `-pooler` suffix by hand.
+</Callout>
+
+## Find credentials (current console)
+
+1. Open [console.neon.tech](https://console.neon.tech) → your **project**.
+2. On the **Project Dashboard**, click **Connect**.
+3. In **Connect to your database**, pick **Branch**, **Compute**, **Database**, and
+   **Role**.
+4. Toggle **Connection pooling** **on** for the pooled string (hostname gains `-pooler`),
+   or **off** for the direct string.
+5. Copy the connection string into `DATABASE_URL` (add `?sslmode=require` if missing).
+
+```bash title="process env"
+# Runtime (pooled) — ep-….…-pooler.…neon.tech
+DATABASE_URL=postgresql://neondb_owner:…@ep-xxxx-pooler.region.aws.neon.tech/neondb?sslmode=require
+
+# Migrations / pg_dump / LISTEN — same host without -pooler
+# OKE_STORE_SQL_URL=postgresql://neondb_owner:…@ep-xxxx.region.aws.neon.tech/neondb?sslmode=require
+```
+
+No `images["store.sql"]` pin — Neon runs the server.
+
+## Pooled vs direct
+
+| Use                                                           | Which string              | Why                                                      |
+| ------------------------------------------------------------- | ------------------------- | -------------------------------------------------------- |
+| App / serverless / Drizzle runtime                            | **Pooled** (`-pooler`)    | PgBouncer transaction mode; up to 10k client connections |
+| `oke db migrate` / `pg_dump` / logical replication / `LISTEN` | **Direct** (no `-pooler`) | Session features break under transaction pooling         |
+
+Do **not** also put [PgDog](/docs/recipes/pgdog) in front of Neon — one pooler only.
+
+**Consequence:** seeding or migrations through the pooled URL often fail with prepared-statement
+errors; switch those jobs to the direct URL.
+
+## pgvector and roles
+
+`CREATE EXTENSION vector;` works on every plan — no add-on. Roles created in the Neon
+Console / CLI / API get `neon_superuser` membership and can install supported extensions.
+
+Roles you create only with raw SQL (`CREATE ROLE`) do **not** get `neon_superuser` — they
+hit permission errors on extension install. Create app roles in the Console (or grant
+deliberately) when you need `pgvector` setup from that role.
+
+## Free tier / production limits
+
+| Limit         | Free plan                                 |
+| ------------- | ----------------------------------------- |
+| Scale to zero | After **5 min** idle — **cannot disable** |
+| Compute       | **100 CU-hours** / project / month        |
+| Storage       | **0.5 GB** / project                      |
+| Autoscaling   | Up to 2 CU                                |
+
+Hitting CU-hours or storage **suspends compute** until the next billing period or an
+upgrade. Always-on production needs Launch/Scale with scale-to-zero disabled.
+
+## Real gotcha — cold start
+
+After scale-to-zero, the first query pays a wake-up (hundreds of ms to a few seconds).
+Health checks that expect sub-100ms on an idle Free project will flap. Paid plans can
+disable scale-to-zero; Free cannot.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="remaining connection slots are reserved / pooler wait timeout">
+
+Too many **direct** connections, or pooler server pool exhausted for your compute size.
+Move runtime traffic to the `-pooler` hostname; keep a small number of direct admin
+sessions. Neon reserves connections for the superuser account on each compute size.
+
+</Accordion>
+<Accordion title='permission denied to create extension "vector"'>
+
+The role is not a Console-created / `neon_superuser` member. Re-run as `neondb_owner` (or
+another Console role), or grant appropriately — raw SQL roles start with public-schema
+privileges only.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Postgres (image)](/docs/recipes/postgres) — self-hosted peer
+- [Store · Index](/docs/elements/store#index) — `pgvector` usage
+- [PgDog](/docs/recipes/pgdog) — when you self-host pooling instead
+
+## Next
+
+<Cards>
+  <Card
+    title="Supabase"
+    description="Another managed Postgres option."
+    href="/docs/providers/supabase"
+  />
+  <Card
+    title="CockroachDB"
+    description="Distributed SQL alternative."
+    href="/docs/providers/cockroachdb"
+  />
+  <Card title="PgDog" description="Self-hosted pooler comparison." href="/docs/recipes/pgdog" />
+</Cards>