okengine 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -73,7 +73,7 @@
     "ajv-formats": "^3.0.1",
     "intl-messageformat": "^11.2.13",
     "oxc-parser": "^0.142.0",
-    "sently": "1.0.0"
+    "sently": "1.2.0"
   },
   "devDependencies": {
     "@base-ui/react": "^1.6.0",

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

@@ -132,23 +132,34 @@ images: {
 },
 ```
 
-| Driver     | Medium   | Behavior                                                            |
-| ---------- | -------- | ------------------------------------------------------------------- |
-| `console`  | any      | Captures into a readable inbox — local + tests                      |
-| `smtp`     | email    | Real SMTP — Mailpit in docker, your provider in prod                |
-| `resend`   | email    | Resend HTTP API (`RESEND_API_KEY`)                                  |
-| `sndr`     | email    | SNDR HTTP API (`SNDR_API_KEY`)                                      |
-| `taqnyat`  | sms      | Taqnyat SMS (`TAQNYAT_BEARER_TOKEN` + `TAQNYAT_SENDER`)             |
-| `msegat`   | sms      | Msegat SMS (`MSEGAT_USERNAME` + `MSEGAT_API_KEY` + `MSEGAT_SENDER`) |
-| `unifonic` | sms      | Unifonic el.cloud SMS (`UNIFONIC_APPSID`)                           |
-| `wa-cloud` | whatsapp | Meta WhatsApp Cloud API                                             |
-| `webpush`  | push     | Web Push + VAPID (`createPushSender` → `WebPushTransport`)          |
-| `fcm`      | push     | Firebase Cloud Messaging HTTP v1                                    |
+| Driver         | Medium   | Behavior                                                            |
+| -------------- | -------- | ------------------------------------------------------------------- |
+| `console`      | any      | Captures into a readable inbox — local + tests                      |
+| `smtp`         | email    | Real SMTP — Mailpit in docker, your provider in prod                |
+| `resend`       | email    | Resend HTTP API (`RESEND_API_KEY`)                                  |
+| `sndr`         | email    | SNDR HTTP API (`SNDR_API_KEY`)                                      |
+| `taqnyat-mail` | email    | Taqnyat Mail API (`TAQNYAT_MAIL_TOKEN` + `TAQNYAT_CAMPAIGN`)        |
+| `taqnyat`      | sms      | Taqnyat SMS (`TAQNYAT_BEARER_TOKEN` + `TAQNYAT_SENDER`)             |
+| `msegat`       | sms      | Msegat SMS (`MSEGAT_USERNAME` + `MSEGAT_API_KEY` + `MSEGAT_SENDER`) |
+| `unifonic`     | sms      | Unifonic el.cloud SMS (`UNIFONIC_APPSID`)                           |
+| `wa-cloud`     | whatsapp | Meta WhatsApp Cloud API                                             |
+| `webpush`      | push     | Web Push + VAPID (`createPushSender` → `WebPushTransport`)          |
+| `fcm`          | push     | Firebase Cloud Messaging HTTP v1                                    |
 
 Email fallback uses ordered email transports; SMS with multiple SMS drivers uses
 the same failover path. Credentials for boot-opened drivers are listed under
 [Environment Variables](/docs/reference/environment-variables).
 
+### Provider-managed OTP
+
+Flows can also send a provider-generated SMS code with `fx.sendOtp({ to, requestId, lang? })`
+and check it with `fx.verifyOtp({ to, requestId, code })` — Taqnyat's Verify API. Both are
+capability-gated `send` effects and dry-run safe.
+
+They dispatch only when the bound SMS driver supports Verify (`taqnyat`); any other SMS
+driver fails loudly instead of silently falling back to a self-generated code. The
+[Phone number](/docs/plugins/phone-number) plugin uses this path automatically.
+
 `webpush` needs VAPID keys — open it yourself and include it in
 `BootOptions.channel.drivers` (boot does not open push from env):
 

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

@@ -73,7 +73,7 @@ export const sendDaily = on(
 ```typescript
 do: async (input, fx) => {
   const now = fx.clock.now(); // epoch-ms, injectable
-  await fx.clock.sleep("wait-for-payment", "7d"); // durable — survives restarts
+  await fx.clock.sleep("wait-for-payment", "7d"); // durable — survives restarts on a shared journal
 };
 ```
 
@@ -103,13 +103,13 @@ difference.
 <ClockSleep />
 
 `fx.clock.sleep(label, duration)` is a **durable** sleep: in a `durable: true` flow the wake time is
-journaled, so the flow resumes after restarts and deploys instead of losing its place. The `label`
-names the step in the journal — it is what the Console shows when you inspect a sleeping run.
+journaled — with a shared journal (`drivers.journal: "postgres"`) the flow resumes after restarts and
+deploys; the `memory` default resumes within the same process only. The `label` names the step — the Console shows it on sleeping runs.
 
 In a non-durable flow the same call resolves immediately, so code reads identically in tests.
 
-Completed journal steps never re-run on resume — a process killed mid-flow continues at the next
-unfinished step.
+Completed journal steps never re-run on resume — with a shared journal, a process killed mid-flow is
+reclaimed after its lease expires and continues at the next unfinished step.
 
 ## What the runtime guarantees
 
@@ -123,8 +123,8 @@ unfinished step.
 | DST detection      | Ambiguous local times get a Console warning — schedules are not rewritten or blocked               |
 
 **Leader election needs a shared store.** The default in-memory CronStore is per process. Multi-replica
-exclusivity only holds when every instance opens the same durable CronStore (file-backed store is
-available for that; a Postgres cron driver is not wired yet).
+exclusivity holds when every instance opens the same durable CronStore — `postgres` (SKIP LOCKED +
+lease reclaim, docker/prod default) or `file` (shared volume, single-host / local).
 
 **Catch-up example:** an hourly clock down for five hours reports `missedRuns: 5` and
 `catchUp: "one"`, then a single tick runs the handler once.
@@ -141,15 +141,16 @@ Detection attaches `dstAmbiguity` on the cron row and the Console shows it. `oke
 
 ```typescript title="oke.config.ts"
 drivers: {
-  clock: { local: "memory", docker: "file", test: "frozen", prod: "file" },
+  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
 },
 ```
 
-| Driver   | Behavior                                                                                 |
-| -------- | ---------------------------------------------------------------------------------------- |
-| `memory` | In-process CronStore + timers — single process; lost on exit                             |
-| `file`   | On-disk CronStore (`.oke/crons.json`) — multi-process leader election on a shared volume |
-| `frozen` | Deterministic test clock — time advances only when the test says so                      |
+| Driver     | Behavior                                                                                       |
+| ---------- | ---------------------------------------------------------------------------------------------- |
+| `memory`   | In-process CronStore + timers — single process; lost on exit                                   |
+| `postgres` | Postgres CronStore (`oke_crons`) — multi-host leader election via SKIP LOCKED + lease reclaim  |
+| `file`     | On-disk CronStore (`.oke/crons.json`) — multi-process on a shared volume (local / single-host) |
+| `frozen`   | Deterministic test clock — time advances only when the test says so                            |
 
 `frozen` is why the no-`Date.now()` rule pays off: tests inject time travel through `fx.clock` and every flow obeys it automatically.
 
@@ -179,12 +180,13 @@ The clock was declared without `overridable: true`. Add it and redeploy — the
 </Accordion>
 <Accordion title="How do I run something once, later — not recurring?">
 
-Emit it from inside a flow with `fx.clock.sleep(label, duration)` before the work, in a `durable: true` flow. The sleep survives restarts, so "remind me in 7 days" is one line, not a cron row.
+Emit it from inside a flow with `fx.clock.sleep(label, duration)` before the work, in a `durable: true` flow. The sleep survives restarts on a shared journal, so "remind me in 7 days" is one line, not a cron row.
 
 </Accordion>
 <Accordion title="Two replicas both ran my cron">
 
-They are not sharing one CronStore. In-memory leases are per process. Point every replica at the same durable cron store, or run a single scheduler instance until the Postgres clock driver ships.
+They are not sharing one CronStore. In-memory leases are per process. Point every replica at the same
+`postgres` CronStore (`DATABASE_URL`), or use `file` on a shared volume for single-host multi-process.
 
 </Accordion>
 </Accordions>

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

@@ -219,14 +219,18 @@ export const chargeOrder = flow({
       stripe(fx.vault(stripeKey).reveal()).create(orderId),
     );
 
-    await fx.clock.sleep("verify-window", "2m"); // survives restart and deploy
+    await fx.clock.sleep("verify-window", "2m"); // journals wakeAt in a durable flow
 
     return fx.step("confirm", () => stripe(fx.vault(stripeKey).reveal()).confirm(intent));
   },
 });
 ```
 
-**Consequence:** kill the process between the two steps and the run **resumes at `confirm`** — completed steps replay from the journal, so the card is not charged twice. This is verified by the engine's own test suite: after resume, `create-intent` has run exactly once.
+**Consequence:** completed steps replay from the journal — on resume, `create-intent` does not re-run, so the card is not charged twice.
+
+**Crash recovery needs a shared journal.** Set `drivers.journal: "postgres"` (the docker/prod template default) and every run persists in `oke_journal_runs` under a per-run lease: boot scans for orphaned `running` / due `sleeping` runs and resumes them, and the lease lets exactly one instance execute a run at a time. The default `memory` journal is per process — replay holds for that process only.
+
+Replay is **at-least-once** for a step whose body never persisted (crash mid-step, lease overrun): that step re-runs on reclaim, so keep step bodies short or internally idempotent. A client transport retry starts a _new_ run with a fresh `runId` — request-level idempotency is an application concern, not the journal's.
 
 For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow({ retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
 

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

@@ -239,6 +239,137 @@ 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 |
+
+#### 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**;

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/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>

package/site/content/docs/plugins/phone-number.mdx

@@ -1,16 +1,18 @@
 ---
 title: "Phone number"
-description: "Official plugin — E.164 phone OTP request and verify under /auth."
+description: "Official plugin — E.164 phone OTP request and verify under /auth, with provider-managed delivery via Taqnyat Verify."
 icon: "Smartphone"
 source: "docs/spec/unified-theory.md"
 ---
 
-`phoneNumber()` signs people in with a phone number in E.164 form (`+15551234567`). Codes are
-6 digits, hashed, 10 minutes, 5 attempts — same security shape as email OTP.
+`phoneNumber()` signs people in with a phone number in E.164 form (`+15551234567`). Delivery
+has two shapes: provider-managed OTP through Taqnyat Verify when an SMS driver is bound, or a
+local hashed code (10 minutes, 5 attempts) you deliver yourself.
 
 <Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(phoneNumber())`. Reject non-E.164 numbers. SMS Channel delivery is
-  not wired yet — use `exposeDevOtp` locally. Prefer stronger methods when phone is the only factor.
+  Enable `gate.auth`, then `.plug(phoneNumber())`. For real SMS set `drivers.channel.sms` to
+  `taqnyat` — the plugin uses Taqnyat's Verify API, never a self-generated code. Use `exposeDevOtp`
+  only when no SMS driver is bound.
 </Callout>
 
 ## Quick start
@@ -40,7 +42,8 @@ export const app = oke({
 const { data, error } = await api.auth.requestPhoneOtp({ phone: "+15551234567" });
 ```
 
-`POST /auth/phone/request`. Invalid E.164 → `AuthFailed` / `invalid_phone`.
+`POST /auth/phone/request`. Invalid E.164 → `AuthFailed` / `invalid_phone`. Optional `lang:
+"en" | "ar"` picks the OTP message language on the Taqnyat path.
 
 </Step>
 
@@ -60,16 +63,51 @@ const { data } = await api.auth.verifyPhoneOtp({
 
 </Steps>
 
+## Delivery
+
+| Bound SMS driver     | Request behavior                                           | Verify behavior                |
+| -------------------- | ---------------------------------------------------------- | ------------------------------ |
+| `taqnyat`            | Taqnyat Verify `sendOtp` (provider generates the code)     | Taqnyat Verify `verifyOtp`     |
+| none                 | Local 6-digit code, hashed at rest (`exposeDevOtp` for DX) | Local hash compare, 5 attempts |
+| any other SMS driver | Fails loudly — provider-managed OTP unsupported            | —                              |
+
+**Consequence:** the request response never contains `devOtp` on the Taqnyat path — the code
+exists only inside the SMS Taqnyat sends.
+
+### Taqnyat Verify
+
+```typescript title="oke.config.ts"
+export default {
+  drivers: {
+    channel: {
+      sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
+    },
+  },
+};
+```
+
+| Env                    | Meaning                                      |
+| ---------------------- | -------------------------------------------- |
+| `TAQNYAT_BEARER_TOKEN` | Taqnyat bearer token (`TAQNYAT_TOKEN` alias) |
+| `TAQNYAT_SENDER`       | Pre-approved sender id                       |
+
+Request stores a provider challenge (`taqnyat:<requestId>`, 10m TTL, 5 attempts) and calls
+`fx.sendOtp`; verify replays the same `requestId` with the code through `fx.verifyOtp`. Both
+are capability-gated `send` effects — dry-run records them without contacting Taqnyat.
+
+An SMS driver without Verify support (for example a generic SMS sender) makes the request fail
+with a clear error: use `exposeDevOtp` locally or switch `drivers.channel.sms` to `taqnyat`.
+
 ## Options
 
-| Option          | Type                | Default  | Meaning                                 |
-| --------------- | ------------------- | -------- | --------------------------------------- |
-| `secret`        | `string`            | active\* | HMAC secret (\*from `gate.auth`)        |
-| `sessions`      | `SessionStore`      | active\* | Session store                           |
-| `ttlMs`         | `number`            | 10m      | Challenge lifetime                      |
-| `exposeDevOtp`  | `boolean`           | `false`  | Include raw OTP in the request response |
-| `phones`        | `PhoneStore`        | new      | Phone → userId map                      |
-| `verifications` | `VerificationStore` | new      | Challenge store                         |
+| Option          | Type                | Default  | Meaning                                                   |
+| --------------- | ------------------- | -------- | --------------------------------------------------------- |
+| `secret`        | `string`            | active\* | HMAC secret (\*from `gate.auth`)                          |
+| `sessions`      | `SessionStore`      | active\* | Session store                                             |
+| `ttlMs`         | `number`            | 10m      | Challenge lifetime                                        |
+| `exposeDevOtp`  | `boolean`           | `false`  | Include raw OTP in the request response (local path only) |
+| `phones`        | `PhoneStore`        | new      | Phone → userId map                                        |
+| `verifications` | `VerificationStore` | new      | Challenge store                                           |
 
 ## Surfaces
 
@@ -80,6 +118,21 @@ const { data } = await api.auth.verifyPhoneOtp({
 
 E.164 pattern: `^\+[1-9]\d{7,14}$`.
 
+## Live tests (opt-in)
+
+The Taqnyat live suite sends real SMS and burns real quota, so it is double-gated: it runs only when
+`OKE_SMS_LIVE=1` **and** the real credentials (`TAQNYAT_TOKEN`, `TAQNYAT_SENDER`, plus
+`OKE_TEST_TAQNYAT_PHONE` — `TAQNYAT_TO` also accepted) are all present. Credentials alone never send.
+
+The suite sends exactly one SMS and never asks for the code.
+
+```bash
+OKE_SMS_LIVE=1 TAQNYAT_TOKEN=… TAQNYAT_SENDER=YourBrand \
+  OKE_TEST_TAQNYAT_PHONE=+9665xxxxxxxx bun test src/plugins
+```
+
+Without the flag the suite skips visibly — never a silent pass.
+
 ## Troubleshooting
 
 <Accordions>
@@ -88,10 +141,18 @@ E.164 pattern: `^\+[1-9]\d{7,14}$`.
 Number must start with `+` and a non-zero country digit, then 7–14 more digits. No spaces or
 dashes.
 
+</Accordion>
+<Accordion title="SMS driver does not support provider-managed OTP">
+
+The configured `drivers.channel.sms` driver has no Verify API. Either switch to `taqnyat` or
+remove the SMS driver so the local hashed path (`exposeDevOtp`) is used.
+
 </Accordion>
 <Accordion title="No SMS arrived">
 
-v1 does not send SMS. Use `exposeDevOtp` in local/test, or deliver via your own Channel Flow.
+On the local path no SMS is sent by design — use `exposeDevOtp`, or bind `taqnyat` with valid
+`TAQNYAT_*` credentials. On the Taqnyat path check the sender id is pre-approved and the
+number is E.164.
 
 </Accordion>
 </Accordions>
@@ -99,8 +160,8 @@ v1 does not send SMS. Use `exposeDevOtp` in local/test, or deliver via your own
 ## Learn more
 
 - [Email OTP](/docs/plugins/email-otp) — email variant of the same OTP rules
-- [Gate](/docs/elements/gate) — `gate.auth`
-- [Channel](/docs/elements/channel) — when you wire SMS yourself
+- [Magic link](/docs/plugins/magic-link) — one-time email link sign-in
+- [Channel](/docs/elements/channel) — SMS / email drivers and delivery
 
 ## Next
 

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

@@ -107,6 +107,7 @@ 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 [Phone number](/docs/plugins/phone-number) / [Magic link](/docs/plugins/magic-link)
 
 ## Next
 

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

@@ -28,6 +28,8 @@ 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
 

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`                                                |

package/site/content/docs/reference/environment-variables.mdx

@@ -13,14 +13,14 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## SQL store
 
-| Variable            | Used for                                             | Default when unset              |
-| ------------------- | ---------------------------------------------------- | ------------------------------- |
-| `DATABASE_URL`      | Postgres connection (`postgres` driver, drizzle-kit) | `postgres://localhost:5432/oke` |
-| `OKE_STORE_SQL_URL` | Explicit SQL URL override                            | —                               |
-| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                   | `.oke/app.sqlite`               |
-| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)            | `.oke/app.libsql`               |
-| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)     | `.oke/pgdata`                   |
-| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                      | config map                      |
+| Variable            | Used for                                                                      | Default when unset              |
+| ------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
+| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal drivers, drizzle-kit) | `postgres://localhost:5432/oke` |
+| `OKE_STORE_SQL_URL` | Explicit SQL URL override                                                     | —                               |
+| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                                            | `.oke/app.sqlite`               |
+| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)                                     | `.oke/app.libsql`               |
+| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)                              | `.oke/pgdata`                   |
+| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                               | config map                      |
 
 ## Index store
 
@@ -74,6 +74,8 @@ Read when `drivers.channel.email` resolves to that driver id.
 | `RESEND_API_KEY`        | `resend` API key                                 |
 | `SNDR_API_KEY`          | `sndr` API key                                   |
 | `SNDR_BASE_URL`         | Optional SNDR API origin (default `api.sndr.sh`) |
+| `TAQNYAT_MAIL_TOKEN`    | `taqnyat-mail` bearer token (Email-enabled)      |
+| `TAQNYAT_CAMPAIGN`      | `taqnyat-mail` campaign name                     |
 
 ## Channel (SMS) — boot binder
 
@@ -94,6 +96,16 @@ Read when `drivers.channel.sms` resolves to that driver id (`console` opens noth
 WhatsApp (`wa-cloud`) and push (`webpush` / `fcm`) are not opened from env at
 boot — pass them on `BootOptions.channel.drivers` with their open options.
 
+## Live test gates (opt-in)
+
+Provider-quota-burning live suites are double-gated: the medium flag **plus** that
+provider's real credentials — credentials alone never send.
+
+| Variable         | Used for                                                  |
+| ---------------- | --------------------------------------------------------- |
+| `OKE_SMS_LIVE`   | `=1` allows live SMS provider tests (e.g. Taqnyat OTP)    |
+| `OKE_EMAIL_LIVE` | `=1` allows live email provider tests (e.g. Taqnyat Mail) |
+
 ## AI providers
 
 | Variable              | Used for                                                                                                                                  | Default when unset                |