okengine 0.7.0 → 0.9.0

package/site/content/docs/elements/store.mdx

@@ -239,6 +239,151 @@ not when emit rewrites `schema.generated.ts`.
 Opt out with `--no-db-push` or `db: { autoPush: false }`. Docker/prod **never**
 auto-apply DDL; a missing table fails as **OKE1101** (`oke db migrate`).
 
+#### Multiple environments
+
+Local can `oke db push` freely — safe to wipe and regenerate.
+
+Staging/prod accumulate versioned SQL under `drizzle/` (`oke db generate`).
+`oke db migrate` applies only unrecorded files in order — behind DBs catch up.
+
+| Environment    | Sync                                                           |
+| -------------- | -------------------------------------------------------------- |
+| Local          | `oke db push` (or auto-push from `oke dev`)                    |
+| Staging / prod | `oke db generate` → review files → `oke db migrate` on that DB |
+
+<Callout title="Connection pooling is infrastructure, not app code" type="info">
+  Bun.SQL defaults to **10** connections per process — fine per instance. Scale out and `N × pool`
+  can exceed Postgres `max_connections`. docker/prod puts **PgDog** in front; `DATABASE_URL` → port
+  `6432`. No app code changes.
+</Callout>
+
+**Why PgDog (not PgBouncer as the default).** Transaction pooling fixes the
+math; naive poolers can leak session state (`SET`, RLS vars, `LISTEN`/`NOTIFY`)
+across clients. PgDog re-applies those under transaction mode (PgBouncer is fine — not shipped).
+
+**Read replicas later, zero app changes.** Add `role = "replica"` in
+`pgdog.toml` later: `BEGIN READ ONLY` → replica, failover on promotion.
+Not wired this round — readiness only.
+
+#### Seeding
+
+`oke db seed` loads `defineSeed` from `src/seed/index.ts` — **never at boot**.
+Seed proves existence (bootstrap rows); it does not correct schema-adjacent data over time.
+
+<StoreSeeding />
+
+| env      | `essential` | `dev` | `prod` |
+| -------- | ----------- | ----- | ------ |
+| `local`  | yes         | yes   | no     |
+| `docker` | yes         | yes   | no     |
+| `test`   | yes         | no    | no     |
+| `prod`   | yes         | no    | yes    |
+
+`docker` is a laptop profile with prod-shaped drivers — still development, so `dev` runs.
+Outside `test`, exactly one of `dev` / `prod` runs with `essential`.
+
+**Simple form** — everything inline:
+
+```ts
+import { defineSeed, type Fx } from "okengine";
+import { db } from "../core";
+import { notes } from "../schema.decl";
+
+export default defineSeed({
+  essential: async (fx: Fx) => {
+    await fx
+      .store(db)
+      .upsert(
+        notes,
+        { id: "welcome" },
+        { id: "welcome", title: "Welcome", body: "…", createdAt: 1 },
+      );
+  },
+  dev: async (fx: Fx) => {
+    await fx
+      .store(db)
+      .upsert(
+        notes,
+        { id: "sample-ideas" },
+        { id: "sample-ideas", title: "Ideas", body: "…", createdAt: 2 },
+      );
+  },
+  // prod: async (fx) => { /* e.g. register a real external webhook URL */ },
+});
+```
+
+**Complex form** — one function per file, compose with arrays (order = run order):
+
+```ts
+import { defineSeed } from "okengine";
+import { seedWelcome } from "./essential/welcome";
+import { seedSamples } from "./dev/samples";
+import { seedWebhook } from "./prod/webhook";
+
+export default defineSeed({
+  essential: [seedWelcome],
+  dev: [seedSamples],
+  prod: [seedWebhook],
+});
+```
+
+| `upsert` outcome  | When                                       |
+| ----------------- | ------------------------------------------ |
+| `upserted`        | no row matched `matchOn` — insert          |
+| `already-existed` | match found; default leaves it alone       |
+| `changed`         | match found and `{ onExisting: "update" }` |
+
+Default upsert is **insert-if-missing**. Pass `{ onExisting: "update" }` only when this
+call should also rewrite other columns on a match — opt-in per call, never global.
+
+```ts
+// Safe bootstrap — second seed run leaves the row alone
+await fx.store(db).upsert(
+  notes,
+  { id: "welcome" },
+  {
+    id: "welcome",
+    title: "Welcome",
+    body: "Your Notes API is ready.",
+    createdAt: 1,
+  },
+);
+
+// Refresh copy on every seed — match stays; title/body are rewritten
+await fx.store(db).upsert(
+  notes,
+  { id: "welcome" },
+  {
+    id: "welcome",
+    title: "Welcome (updated)",
+    body: "New bootstrap copy.",
+    createdAt: 1,
+  },
+  { onExisting: "update" },
+);
+```
+
+**Consequence:** default keeps operator edits safe across re-seeds; `onExisting: "update"`
+is for seed-owned rows you intentionally overwrite. Schema-wide data fixes still belong in
+migrations, not seed.
+
+| Env               | Confirm                                               |
+| ----------------- | ----------------------------------------------------- |
+| `local` / `test`  | none                                                  |
+| `docker` / `prod` | print DB target; type the env name (`--force` for CI) |
+
+```bash
+oke db seed                 # resolve env like other oke db commands (.oke/mode)
+oke db seed --env docker    # explicit override
+oke db seed --env prod --force
+```
+
+<Callout title="Seed vs migrate">
+  Permanent reference-data corrections go through `oke db generate` → `migrate`, not repeated seed.
+  Optional `drizzle-seed` may be used inside a `dev` function body only — never as the seed system
+  backbone.
+</Callout>
+
 <Callout title="Escape hatch">
   Hand-written Drizzle in `src/schema.ts` stays supported — if there is nothing to emit, the emit
   step is skipped and your file is used as-is. Plugins may contribute **whole new tables**;
@@ -359,6 +504,8 @@ drivers: {
 },
 images: {
   "store.kv": "redis:8-alpine",
+  // or: "valkey/valkey:8-alpine"
+  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
 },
 ```
 
@@ -374,6 +521,22 @@ images: {
 
 Missing Redis URL fails boot loudly: `oke boot: redis driver needs REDIS_URL`.
 
+Driver id stays `redis` for every image below — same `REDIS_URL`, zero Flow changes.
+Redis is the default because it is the most mature and battle-tested; Valkey and
+Dragonfly are equally legitimate opt-in pins.
+
+| Image         | Pin                                           | Why pick it                       | License                                                                                                                                           |
+| ------------- | --------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Redis**     | `redis:8-alpine` (default)                    | Most mature / battle-tested       | RSALv2 / SSPLv1 / AGPLv3 (Redis ≥8) — service limits under RSAL/SSPL apply if you offer Redis as a managed service to third parties               |
+| **Valkey**    | `valkey/valkey:8-alpine`                      | BSD fork (Linux Foundation)       | BSD-3-Clause — permissive; no managed-service restriction                                                                                         |
+| **Dragonfly** | `docker.dragonflydb.io/dragonflydb/dragonfly` | Multi-threaded Redis-wire runtime | BSL 1.1 (converts to Apache 2.0 on a published change date) — free for self-hosting; restricts offering Dragonfly as a commercial managed service |
+
+<Callout title="Licenses bite managed-service resellers — read this once" type="warn">
+  RSAL, SSPL, and BSL service restrictions apply when you offer that specific datastore **as a
+  service** to third parties — not when you run it for your own app. Pick for your situation; OKE
+  does not pick a “safer” default for you.
+</Callout>
+
 <Callout title="Dry-run refuses KV writes">
   `set` and `delete` throw `DryRunWriteIsolationError` during dry-run — the runtime will not risk a
   double-write against a shared Redis. Reads (`get` / `list`) still run.
@@ -472,6 +635,8 @@ images: {
 
 `memory` is the test default. Local `fs` writes under a temp root when no binding `root` is set.
 
+**Known limit:** `fs` is single-host. Under horizontal scale each replica sees its own filesystem (silently inconsistent object views). Boot prints a one-shot warning when `drivers.store.files` is `fs`. Use `s3` for docker/prod (create-oke templates already do).
+
 <Callout title="Console can browse, not edit bytes">
   The [Console · Store](/docs/console/store) lists keys and can delete them. Direct edit is **KV +
   SQL only** — blob bodies are not patched from the Console.

package/site/content/docs/get-started/index.mdx

@@ -30,4 +30,9 @@ Learn the shape once, install on Bun, then write your first Flow from the standa
     description="Health Flow, typed client, Console proof."
     href="/docs/get-started/basic-usage"
   />
+  <Card
+    title="Deployment"
+    description="Compose, Swarm, Kubernetes, and reverse proxy."
+    href="/docs/deployment"
+  />
 </Cards>

package/site/content/docs/get-started/installation.mdx

@@ -60,17 +60,18 @@ bunx create-oke@latest my-app --yes
 ```
 
 Two Notes starters: **standard** (local-first) and **advanced** (docker-ready +
-files/digest/AI). On a TTY: pick a template, then **recommended defaults**,
-**customize** (choose **local** or **docker** first, walk that side’s facets,
-optionally customize the other; saved to `~/.oke/create-defaults.json`), or
-**reuse** when saved settings match that template. The project-name step rejects
-a path that already exists and is not empty.
-
-Non-TTY / `--yes` stay scriptable. Default pins: local SQLite · Docker/prod
-Postgres. `--sql postgres` pins SQL envs; `--ai` runs the AI model wizard
-**before** install. Scaffold writes `.oke/mode` from the primary side
-(recommended: standard → `local`, advanced → `docker`) so the first `oke dev`
-skips the mode prompt unless you delete that file or pass `--local` / `--docker`.
+files/digest/AI).
+
+On a TTY: pick a template, then **recommended defaults**, **customize** (local
+or docker first; saved to `~/.oke/create-defaults.json`), or **reuse** matching
+saved settings. Project name rejects a non-empty existing path.
+
+Non-TTY / `--yes` stay scriptable. Defaults: local SQLite · Docker/prod Postgres.
+`--sql postgres` pins SQL; `--ai` runs the model wizard before install.
+
+Scaffold writes `.oke/mode` (standard → `local`, advanced → `docker`) so the
+first `oke dev` skips the mode prompt unless you delete it or pass `--local` /
+`--docker`.
 
 </Step>
 
@@ -86,11 +87,12 @@ Four ports come up together (mnemonic: **O·K·E = 6·5·3**):
 
 <Surfaces />
 
-Open `http://localhost:6533`. On first boot, claim the Console with the
-**claim code** printed once in the `oke dev` log, then create the first
-operator. Password policy matches Gate auth: **≥ 12 characters, with a letter
-and a number.** After that, if the Console lists your flows, the install
-worked — **derived, not configured.**
+Open `http://localhost:6533`. Claim the Console with the **claim code** printed
+once in the `oke dev` log, then create the first operator.
+
+Password policy matches Gate auth: **≥ 12 characters, with a letter and a
+number.** If the Console lists your flows, the install worked — **derived, not
+configured.**
 
 </Step>
 

package/site/content/docs/index.mdx

@@ -32,6 +32,11 @@ on(orderPlaced, sendReceipt);
     href="/docs/plugins"
   />
   <Card title="Console" description="Manifest-derived operator panels." href="/docs/console" />
+  <Card
+    title="Deployment"
+    description="Compose, Swarm, Kubernetes, reverse proxy."
+    href="/docs/deployment"
+  />
   <Card
     title="Reference"
     description="Config, fx, env, errors, CLI, security."

package/site/content/docs/meta.json

@@ -1,5 +1,14 @@
 {
   "title": "Documentation",
   "icon": "BookOpen",
-  "pages": ["index", "get-started", "elements", "plugins", "console", "reference", "ai"]
+  "pages": [
+    "index",
+    "get-started",
+    "elements",
+    "plugins",
+    "console",
+    "deployment",
+    "reference",
+    "ai"
+  ]
 }

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

@@ -17,8 +17,7 @@ First-party plugins you `.plug()` onto an app. Each page is one export from `oke
     href="/docs/plugins/anonymous"
   />
   <Card title="Magic link" description="One-time email link." href="/docs/plugins/magic-link" />
-  <Card title="Email OTP" description="Six-digit email codes." href="/docs/plugins/email-otp" />
-  <Card title="Phone number" description="E.164 SMS OTP." href="/docs/plugins/phone-number" />
+  <Card title="OTP" description="SMS, WhatsApp, or email codes." href="/docs/plugins/otp" />
   <Card title="Two-factor" description="TOTP enable / verify." href="/docs/plugins/two-factor" />
   <Card title="Passkey" description="WebAuthn-shaped passkeys." href="/docs/plugins/passkey" />
 </Cards>

package/site/content/docs/plugins/magic-link.mdx

@@ -86,6 +86,48 @@ const { data } = await api.auth.verifyMagicLink({ token });
 **Consequence:** the plugin contributes the `auth-magic-link` Channel template and EN/AR
 catalog bodies (`{{link}}`, `{{token}}`). Override copy by merging your own catalog at boot.
 
+## Delivery drivers
+
+| `drivers.channel.email` | Delivery                                                          |
+| ----------------------- | ----------------------------------------------------------------- |
+| `console`               | Dev inbox (local/test default)                                    |
+| `smtp`                  | Any SMTP host — Mailpit under `oke dev --docker` (docker default) |
+| `resend` / `sndr`       | Hosted email APIs                                                 |
+| `taqnyat-mail`          | Taqnyat Mail API (additive option)                                |
+
+### Taqnyat Mail
+
+```typescript title="oke.config.ts"
+export default {
+  drivers: {
+    channel: {
+      email: { local: "console", docker: "smtp", test: "console", prod: "taqnyat-mail" },
+    },
+  },
+};
+```
+
+| Env                  | Meaning                                          |
+| -------------------- | ------------------------------------------------ |
+| `TAQNYAT_MAIL_TOKEN` | Taqnyat bearer token enabled for Email           |
+| `TAQNYAT_CAMPAIGN`   | Campaign name required by Taqnyat `mailSend.php` |
+
+The plugin needs no change — delivery stays Channel-mediated via `fx.send`. SMTP/Mailpit
+remains the default docker path; `taqnyat-mail` is strictly additive.
+
+## Live tests (opt-in)
+
+The Taqnyat live suite sends real email and burns real quota, so it is double-gated: it runs
+only when `OKE_EMAIL_LIVE=1` **and** the real credentials (`TAQNYAT_MAIL_TOKEN`,
+`TAQNYAT_CAMPAIGN`, plus `OKE_TEST_TAQNYAT_MAIL`) are all present.
+
+Credentials alone never send; without the flag the suite skips visibly — never a silent pass.
+
+```bash
+OKE_EMAIL_LIVE=1 TAQNYAT_MAIL_TOKEN=… TAQNYAT_CAMPAIGN=auth \
+  OKE_TEST_TAQNYAT_MAIL=you@example.com bun test src/plugins
+```
+
 ## Troubleshooting
 
 <Accordions>
@@ -105,14 +147,14 @@ unit tests without SMTP, set `exposeDevToken: true`.
 
 ## Learn more
 
-- [Email OTP](/docs/plugins/email-otp) — numeric code instead of a link
+- [OTP](/docs/plugins/otp) — numeric code instead of a link
 - [Gate](/docs/elements/gate) — `gate.auth`
 - [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
 
 ## Next
 
 <Cards>
-  <Card title="Email OTP" description="Six-digit email codes." href="/docs/plugins/email-otp" />
+  <Card title="OTP" description="SMS, WhatsApp, or email codes." href="/docs/plugins/otp" />
   <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
   <Card title="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -7,8 +7,7 @@
     "username",
     "anonymous",
     "magic-link",
-    "email-otp",
-    "phone-number",
+    "otp",
     "two-factor",
     "passkey",
     "---Security---",

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

@@ -0,0 +1,202 @@
+---
+title: "OTP"
+description: "Official plugin — one-time codes over SMS, WhatsApp, or email under /auth, with explicit Tier 1 or Tier 2 delivery."
+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.
+
+<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.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug Tier 2 (multi-channel)
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { otp } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(
+  otp({
+    tier: 2,
+    channels: ["sms", "whatsapp", "email"],
+    exposeDevOtp: true, // local DX only
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Request a code
+
+```typescript
+const { data } = await api.auth.requestOtp({
+  phone: "+15551234567",
+  email: "ali@example.com",
+});
+```
+
+`POST /auth/otp/request`. Prior active challenges for that principal are
+invalidated. Delivery follows `channels` order for addresses you pass.
+
+</Step>
+
+<Step>
+### Resend on another channel (Tier 2 only)
+
+```typescript
+const { data } = await api.auth.resendOtp({
+  phone: "+15551234567",
+  email: "ali@example.com",
+  channel: "email",
+});
+```
+
+Same code, same TTL. Default cooldown is 60 seconds. Tier 1 has no resend
+surface — the provider owns the code.
+
+</Step>
+
+<Step>
+### Verify
+
+```typescript
+const { data } = await api.auth.verifyOtp({
+  phone: "+15551234567",
+  otp,
+});
+```
+
+`POST /auth/otp/verify` — five failed attempts consume the challenge.
+
+</Step>
+
+</Steps>
+
+## Tiers
+
+|                      | Tier 1                        | Tier 2                                        |
+| -------------------- | ----------------------------- | --------------------------------------------- |
+| Config               | `otp({ tier: 1 })`            | `otp({ tier: 2, 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>
+
+### Tier 1 setup
+
+```typescript title="oke.config.ts"
+export default {
+  drivers: {
+    channel: {
+      sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
+    },
+  },
+};
+```
+
+Boot fails loudly if no SMS driver exposes `sendOtp` / `verifyOtp`. Switch to
+Tier 2, or bind a Verify-capable driver (for example `taqnyat`).
+
+### Tier 2 delivery
+
+| Concern         | Behavior                                                                                                                    |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| Storage         | SHA-256 hash for verify + sealed AES-GCM copy (HKDF `oke-otp-seal-v1`) for redelivery                                       |
+| Seal lifetime   | Wiped on verify, lockout, or TTL expiry — never left after the challenge dies                                               |
+| Challenge TTL   | Default 10 minutes (`ttlMs`)                                                                                                |
+| Resend cooldown | Default 60 seconds (`resendCooldownMs`) — separate from TTL                                                                 |
+| Auto failover   | On real provider send errors, sently `FallbackTransport` walks remaining media; Taqnyat WhatsApp may use `sendWithFailover` |
+| User resend     | Explicit `resend` with `channel` — not automatic                                                                            |
+
+Templates: `auth-otp-email`, `auth-otp-sms`, `auth-otp-whatsapp` (EN/AR,
+`{{otp}}`). SMS here is a plain message — not Taqnyat Verify.
+
+## 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                   |
+
+## 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 |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title='otp(): tier is required'>
+
+You omitted `tier`. Set `tier: 1` or `tier: 2` explicitly — OKE never infers
+which mechanism you meant.
+
+</Accordion>
+<Accordion title="Boot fails on Tier 1">
+
+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: [...] })`.
+
+</Accordion>
+<Accordion title="resend_cooldown">
+
+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)">
+
+In `local` / `test` the `console` driver captures messages. Use
+`exposeDevOtp: true` for unit tests without a real provider.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Magic link](/docs/plugins/magic-link) — link instead of a code
+- [Channel](/docs/elements/channel) — `fx.send`, drivers, Mailpit
+- [Gate](/docs/elements/gate) — `gate.auth`
+
+## Next
+
+<Cards>
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+  <Card title="Two-factor" description="TOTP second factor." href="/docs/plugins/two-factor" />
+  <Card title="Channel" description="Delivery drivers and Mailpit." href="/docs/elements/channel" />
+</Cards>

package/site/content/docs/plugins/two-factor.mdx

@@ -107,11 +107,12 @@ enable. A recovery code works once, then is consumed.
 - [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against
+- OTP over SMS or email instead of TOTP? See [OTP](/docs/plugins/otp) / [Magic link](/docs/plugins/magic-link)
 
 ## Next
 
 <Cards>
   <Card title="Passkey" description="WebAuthn register and assert." href="/docs/plugins/passkey" />
   <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
-  <Card title="Email OTP" description="Passwordless email codes." href="/docs/plugins/email-otp" />
+  <Card title="OTP" description="SMS, WhatsApp, or email codes." href="/docs/plugins/otp" />
 </Cards>

package/site/content/docs/reference/cli.md

@@ -28,11 +28,14 @@ oke schema generate              # core + plugin stubs → schema/oke.ts   (--ch
 oke db push                      # domain schema.ts → live local DB (dev; drizzle-kit)
 oke db generate                  # versioned SQL under drizzle/ (review)
 oke db migrate                   # apply migrations (explicit; never auto in prod)
+oke db seed                      # defineSeed (essential + env category); never at boot
+oke db seed --env prod --force   # CI: skip docker/prod confirmation prompt
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # docker/Dockerfile + docker/compose.<role>.yml · …
-oke docker --prod                # healthchecks, volumes, limits, secret refs, deploy.replicas
+oke docker                       # docker/Dockerfile + compose.yml + compose.<role>.yml + compose.all.yml · …
+                                 # opt-in images.proxy → Caddyfile (caddy) or Traefik labels + socket-proxy
+oke docker --prod                # + compose.prod.yml (HEALTHCHECK /_/ready, deploy, limits); folded into compose.all.yml
 oke docker clean                 # TTY: pick oke-dev-* stacks → down -v (containers, networks, volumes)
 oke docker clean --yes           # non-TTY: current project stack only
 oke docker clean --all --yes     # non-TTY: every oke-dev-* stack on this machine

package/site/content/docs/reference/configuration.mdx

@@ -26,7 +26,8 @@ drivers: {
     files: { local: "fs", docker: "s3", test: "memory", prod: "s3" },
   },
   signal: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
-  clock: { local: "memory", docker: "file", test: "frozen", prod: "file" },
+  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
+  journal: { local: "memory", docker: "postgres", test: "memory", prod: "postgres" },
   vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
   channel: {
     email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
@@ -42,9 +43,10 @@ drivers: {
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
 | `store.index`      | env driver map | `memory` · `pgvector` · `libsql` · `meilisearch`                             |
 | `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind  |
-| `clock`            | env driver map | `memory` · `file` · `frozen`                                                 |
+| `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                    |
+| `journal`          | env driver map | `memory` · `file` · `postgres`                                               |
 | `vault`            | env driver map | `env` · `openbao` · `memory` · `managed`                                     |
-| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr`                                       |
+| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                      |
 | `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                |
 | `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                       |
 | `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                |
@@ -73,16 +75,32 @@ Container image pins keyed by element role — vendor choice lives here, never i
 ```typescript
 images: {
   "store.sql": "postgres:18",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
   "store.kv": "redis:8",
+  // or: "valkey/valkey:8-alpine"
+  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
   "store.files": "rustfs/rustfs:1.0.0-beta.11",
   "channel.email": "axllent/mailpit:v1.22.3",
   vault: "openbao/openbao:2.6.1",
   ai: "ollama/ollama:latest",
+  // opt-in TLS edge — omit for the default (app publishes 6530):
+  // proxy: "caddy:2-alpine",   // simplest automatic HTTPS
+  // proxy: "traefik:v3.3",     // label auto-discovery for --scale app=N
 },
 ```
 
+When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog
+(`6432`) — wire-protocol transparent to Bun.SQL / Drizzle. See
+[Store · Multiple environments](/docs/elements/store#multiple-environments).
+
+For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays
+`redis`, same `REDIS_URL`. Image table + licenses: [Store · KV](/docs/elements/store#kv).
+
 For `ai`, the Ollama recipe pulls `OKE_AI_MODEL` (default `qwen3.5:9b` — a balanced local-dev starting point; override freely; on Apple Silicon prefer `qwen3.5:9b-mlx`) and writes `OKE_AI_URL`.
 
+For `proxy`, pin **either** Caddy or Traefik — never both. Opt-in only; see
+[Reverse proxy](/docs/deployment/reverse-proxy).
+
 ## i18n
 
 | Option    | Type       | Default | Meaning                                     |