okengine 0.9.0 → 0.10.0

package/site/content/docs/plugins/otp.mdx

@@ -1,18 +1,30 @@
 ---
 title: "OTP"
-description: "Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit Tier 1 or Tier 2 delivery."
+description: "Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit provider or app mode."
 icon: "KeyRound"
 source: "docs/spec/unified-theory.md"
 ---
 
-`otp()` signs people in with a one-time code. You must set `tier` — there is no
-auto-detect. Tier 1 is provider-owned SMS Verify; Tier 2 is app-owned delivery
-across the channels you declare.
+`otp()` signs people in with a one-time code. You must set `mode` — there is no
+auto-detect. Provider mode is SMS Verify via the bound driver; app mode is
+app-owned delivery across the channels you declare.
 
 <Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(otp({ tier: 1 }))` or
-  `.plug(otp({ tier: 2, channels: [...] }))`. Never omit `tier`. Never log raw
-  OTPs.
+  Enable `gate.auth`, then `.plug(otp({ mode: "provider" }))` or
+  `.plug(otp({ mode: "app", channels: [...] }))`. Never omit `mode`. Never log
+  raw OTPs.
+</Callout>
+
+<Callout type="info" title="One otp() per app">
+  Provider and app mode cannot both be active — they claim the same fixed `/auth/otp/*` routes. Need
+  two OTP-like mechanisms? Combine `otp()` with a different plugin (e.g. `magicLink()`), not a
+  second `otp()`.
+</Callout>
+
+<Callout type="info" title="fx.sendOtp vs otp()">
+  `fx.sendOtp` / `fx.verifyOtp` are raw Channel capabilities — no `.plug()`. Direct use means you
+  build routes, sessions, rates, and storage yourself. `otp()` provider mode wraps that path; skip
+  it and call the raw methods in your own flow without losing the provider connection.
 </Callout>
 
 ## Quick start
@@ -20,7 +32,7 @@ across the channels you declare.
 <Steps>
 
 <Step>
-### Plug Tier 2 (multi-channel)
+### Plug app mode (multi-channel)
 
 ```typescript title="src/app.ts"
 import { oke } from "okengine";
@@ -32,7 +44,7 @@ export const app = oke({
   gate: { auth: {} },
 }).plug(
   otp({
-    tier: 2,
+    mode: "app",
     channels: ["sms", "whatsapp", "email"],
     exposeDevOtp: true, // local DX only
   }),
@@ -57,7 +69,7 @@ invalidated. Delivery follows `channels` order for addresses you pass.
 </Step>
 
 <Step>
-### Resend on another channel (Tier 2 only)
+### Resend on another channel (app mode only)
 
 ```typescript
 const { data } = await api.auth.resendOtp({
@@ -67,8 +79,8 @@ const { data } = await api.auth.resendOtp({
 });
 ```
 
-Same code, same TTL. Default cooldown is 60 seconds. Tier 1 has no resend
-surface — the provider owns the code.
+Same code, same TTL. Default cooldown is 60 seconds. Provider mode has no
+resend surface — the provider owns the code.
 
 </Step>
 
@@ -88,23 +100,23 @@ const { data } = await api.auth.verifyOtp({
 
 </Steps>
 
-## Tiers
+## Modes
 
-|                      | Tier 1                        | Tier 2                                        |
+|                      | Provider mode                 | App mode                                      |
 | -------------------- | ----------------------------- | --------------------------------------------- |
-| Config               | `otp({ tier: 1 })`            | `otp({ tier: 2, channels: [...] })`           |
+| Config               | `otp({ mode: "provider" })`   | `otp({ mode: "app", channels: [...] })`       |
 | Who owns the code    | Provider (Verify API)         | Your app                                      |
 | Delivery             | `fx.sendOtp` / `fx.verifyOtp` | `fx.deliverOtp` (Channel templates)           |
 | Channels             | SMS only                      | `sms` · `whatsapp` · `email` (declared order) |
 | Resend other channel | Impossible                    | `POST /auth/otp/resend`                       |
 | `exposeDevOtp`       | Forbidden                     | Optional (default off)                        |
 
-<Callout type="warn" title="Tier 1 limitation">
-  Resend-via-different-channel is impossible on Tier 1 — the code value is never visible to OKE. Use
-  Tier 2 when you need SMS → email fallback for the same code.
+<Callout type="warn" title="Provider mode limitation">
+  Resend-via-different-channel is impossible in provider mode — the code value is never visible to
+  OKE. Use app mode when you need SMS → email fallback for the same code.
 </Callout>
 
-### Tier 1 setup
+### Provider mode setup
 
 ```typescript title="oke.config.ts"
 export default {
@@ -117,9 +129,9 @@ export default {
 ```
 
 Boot fails loudly if no SMS driver exposes `sendOtp` / `verifyOtp`. Switch to
-Tier 2, or bind a Verify-capable driver (for example `taqnyat`).
+app mode, or bind a Verify-capable driver (for example `taqnyat`).
 
-### Tier 2 delivery
+### App mode delivery
 
 | Concern         | Behavior                                                                                                                    |
 | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
@@ -135,42 +147,42 @@ Templates: `auth-otp-email`, `auth-otp-sms`, `auth-otp-whatsapp` (EN/AR,
 
 ## Options
 
-| Option             | Type                             | Default                    | Meaning                           |
-| ------------------ | -------------------------------- | -------------------------- | --------------------------------- |
-| `tier`             | `1 \| 2`                         | required                   | Delivery mechanism — no auto      |
-| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required on Tier 2         | Build-time preferred order        |
-| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                |
-| `resendCooldownMs` | `number`                         | 60s                        | Tier 2 resend spacing             |
-| `exposeDevOtp`     | `boolean`                        | `false`                    | Tier 2 only — raw OTP in response |
-| `from`             | `string`                         | `OKE <no-reply@oke.local>` | Email template From               |
-| `secret`           | `string`                         | active\*                   | Auth secret (\*from `gate.auth`)  |
-| `sessions`         | `SessionStore`                   | active\*                   | Session store                     |
-| `identities`       | `IdentityStore`                  | new                        | Email → user                      |
-| `phones`           | `PhoneStore`                     | new                        | Phone → user                      |
-| `verifications`    | `VerificationStore`              | new                        | Challenge store                   |
+| Option             | Type                             | Default                    | Meaning                             |
+| ------------------ | -------------------------------- | -------------------------- | ----------------------------------- |
+| `mode`             | `"provider" \| "app"`            | required                   | Delivery mechanism — no auto        |
+| `channels`         | `("sms"\|"whatsapp"\|"email")[]` | required in app mode       | Build-time preferred order          |
+| `ttlMs`            | `number`                         | 10m                        | Challenge lifetime                  |
+| `resendCooldownMs` | `number`                         | 60s                        | App-mode resend spacing             |
+| `exposeDevOtp`     | `boolean`                        | `false`                    | App mode only — raw OTP in response |
+| `from`             | `string`                         | `OKE <no-reply@oke.local>` | Email template From                 |
+| `secret`           | `string`                         | active\*                   | Auth secret (\*from `gate.auth`)    |
+| `sessions`         | `SessionStore`                   | active\*                   | Session store                       |
+| `identities`       | `IdentityStore`                  | new                        | Email → user                        |
+| `phones`           | `PhoneStore`                     | new                        | Phone → user                        |
+| `verifications`    | `VerificationStore`              | new                        | Challenge store                     |
 
 ## Surfaces
 
-| Flow              | Path                     | Gate                     | Tier   |
-| ----------------- | ------------------------ | ------------------------ | ------ |
-| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | 1 + 2  |
-| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | 1 + 2  |
-| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | 2 only |
+| Flow              | Path                     | Gate                     | Mode          |
+| ----------------- | ------------------------ | ------------------------ | ------------- |
+| `auth.requestOtp` | `POST /auth/otp/request` | `gate.public` + otp rate | both          |
+| `auth.verifyOtp`  | `POST /auth/otp/verify`  | `gate.public` + otp rate | both          |
+| `auth.resendOtp`  | `POST /auth/otp/resend`  | `gate.public` + otp rate | app mode only |
 
 ## Troubleshooting
 
 <Accordions>
-<Accordion title='otp(): tier is required'>
+<Accordion title='otp(): mode is required'>
 
-You omitted `tier`. Set `tier: 1` or `tier: 2` explicitly — OKE never infers
-which mechanism you meant.
+You omitted `mode`. Set `mode: "provider"` or `mode: "app"` explicitly — OKE
+never infers which mechanism you meant.
 
 </Accordion>
-<Accordion title="Boot fails on Tier 1">
+<Accordion title="Boot fails in provider mode">
 
 No Verify-capable SMS driver is bound. Set `drivers.channel.sms` to `taqnyat`
 (or another driver with `sendOtp`/`verifyOtp`), or switch to
-`otp({ tier: 2, channels: [...] })`.
+`otp({ mode: "app", channels: [...] })`.
 
 </Accordion>
 <Accordion title="resend_cooldown">
@@ -179,7 +191,7 @@ Wait for `resendCooldownMs` (default 60s). The challenge TTL is unchanged —
 only delivery is rate-limited.
 
 </Accordion>
-<Accordion title="No email / SMS with the code (Tier 2)">
+<Accordion title="No email / SMS with the code (app mode)">
 
 In `local` / `test` the `console` driver captures messages. Use
 `exposeDevOtp: true` for unit tests without a real provider.
@@ -190,7 +202,7 @@ In `local` / `test` the `console` driver captures messages. Use
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
-- [Channel](/docs/elements/channel) — `fx.send`, drivers, Mailpit
+- [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
 - [Gate](/docs/elements/gate) — `gate.auth`
 
 ## Next

package/site/content/docs/providers/azure-redis.mdx

@@ -0,0 +1,85 @@
+---
+title: "Azure Cache for Redis"
+description: "Azure-managed Redis — Access keys blade, TLS port 6380 vs 6379, Basic tier no SLA."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Azure Cache for Redis spans Basic → Enterprise. New caches expect TLS.
+`drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Build `rediss://` from **Overview** hostname + **Access keys** primary key + SSL port **6380**. Do
+  not use 6379 unless you explicitly allowed non-TLS.
+</Callout>
+
+## Find credentials (current portal)
+
+1. Azure Portal → your **Azure Cache for Redis** resource.
+2. **Overview** → copy **Host name** (`….redis.cache.windows.net`).
+3. **Settings → Authentication** → **Access keys** tab (or **Overview → Show access
+   keys**) → copy **Primary** key.
+4. Ports: Overview link next to **Ports**, or docs defaults — **6380** TLS, **6379**
+   non-TLS (disabled by default on new caches).
+5. Enterprise tiers may use port **10000** — check Overview for that SKU.
+
+```bash title="process env"
+REDIS_URL=rediss://:PRIMARY_KEY@my-cache.redis.cache.windows.net:6380
+```
+
+Azure's “connection string” blade often shows StackExchange-style
+`host:6380,password=…,ssl=True` — translate that to `rediss://:password@host:6380` for
+oke.
+
+## Production guidance
+
+| Tier                 | Notes                                   |
+| -------------------- | --------------------------------------- |
+| Basic                | Shared, **no SLA** — not for production |
+| Standard             | Replicated                              |
+| Premium / Enterprise | Clustering, persistence, VNet           |
+
+Non-TLS: **Settings → Advanced settings → Allow access only via SSL = No** — avoid in
+production. Entra ID auth exists on newer tiers; oke's URL driver expects access-key
+auth in `REDIS_URL`.
+
+## Real gotcha — port 6380 vs 6379
+
+Using `redis://…:6379` against a TLS-only cache fails. New caches disable non-TLS;
+always start from **6380** + `rediss://` unless you intentionally opened 6379.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection reset / SSL errors on 6379">
+
+TLS-only cache. Switch to port **6380** and `rediss://`. Confirm Advanced settings still
+require SSL.
+
+</Accordion>
+<Accordion title="WRONGPASS invalid username-password pair">
+
+Primary key rotated or secondary key pasted by mistake. Re-copy **Primary** from
+**Authentication → Access keys** and update `REDIS_URL` (empty username, key as
+password).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Redis (image)](/docs/recipes/redis)
+- [ElastiCache](/docs/providers/elasticache) · [Memorystore](/docs/providers/memorystore)
+- [Store · KV](/docs/elements/store#kv)
+
+## Next
+
+<Cards>
+  <Card title="ElastiCache" description="AWS's equivalent." href="/docs/providers/elasticache" />
+  <Card title="Memorystore" description="GCP's equivalent." href="/docs/providers/memorystore" />
+  <Card
+    title="CockroachDB"
+    description="Managed SQL-side pair."
+    href="/docs/providers/cockroachdb"
+  />
+</Cards>

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>