okengine 0.5.1 → 0.6.1

package/README.md

@@ -1,21 +1,90 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="site/public/logo/OKE-W.svg" />
-    <img alt="OKE" src="site/public/logo/OKE-B.svg" width="220" />
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-W.svg&theme=zinc&size=banner&mode=dark&font=geist&align=left"
+    />
+    <img
+      alt="okengine — One law. Eight elements. Ten exports."
+      src="https://shieldcn.dev/header/grid.svg?title=okengine&subtitle=One+law.+Eight+elements.+Ten+exports.&logo=https://raw.githubusercontent.com/omqkhafi/okengine/main/site/public/logo/OKE-B.svg&theme=zinc&size=banner&mode=light&font=geist&align=left"
+      width="750"
+    />
   </picture>
 </p>
 
-# okengine
-
-_"Stop gluing APIs, jobs, and queues into one backend. One law collapses them — client, Console, and infra come free. Yours to host."_
+<p align="center">
+  <a href="https://www.npmjs.com/package/okengine">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="npm" src="https://shieldcn.dev/npm/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://jsr.io/@omqkhafi/okengine">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/jsr/@omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="JSR" src="https://shieldcn.dev/jsr/@omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://www.npmjs.com/package/create-oke">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/create-oke.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="create-oke" src="https://shieldcn.dev/npm/create-oke.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://www.npmjs.com/package/okengine">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/npm/types/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="types" src="https://shieldcn.dev/npm/types/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/license/omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="MIT" src="https://shieldcn.dev/github/license/omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://bun.sh">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/Bun-%3E%3D1.3.svg?logo=bun&variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="Bun >=1.3" src="https://shieldcn.dev/badge/Bun-%3E%3D1.3.svg?logo=bun&variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://github.com/omqkhafi/okengine/releases">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/release/omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="release" src="https://shieldcn.dev/github/release/omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://github.com/omqkhafi/okengine/stargazers">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/stars/omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="stars" src="https://shieldcn.dev/github/stars/omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://github.com/omqkhafi/okengine/actions">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/ci/omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="CI" src="https://shieldcn.dev/github/ci/omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+  <a href="https://github.com/omqkhafi/okengine/commits">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/github/last-commit/omqkhafi/okengine.svg?variant=outline&mode=dark&size=sm&theme=zinc&font=geist" />
+      <img alt="last commit" src="https://shieldcn.dev/github/last-commit/omqkhafi/okengine.svg?variant=outline&mode=light&size=sm&theme=zinc&font=geist" />
+    </picture>
+  </a>
+</p>
 
-[![npm](https://img.shields.io/npm/v/okengine.svg)](https://www.npmjs.com/package/okengine)
-[![JSR](https://jsr.io/badges/@omqkhafi/okengine)](https://jsr.io/@omqkhafi/okengine)
-[![npm](https://img.shields.io/npm/v/create-oke.svg)](https://www.npmjs.com/package/create-oke)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![Bun >=1.3](https://img.shields.io/badge/Bun-%3E%3D1.3-black.svg)](https://bun.sh)
+<p align="center">
+  <em>Stop gluing APIs, jobs, and queues into one backend. One law collapses them — client, Console, and infra come free. Yours to host.</em>
+</p>
 
-**Docs:** [oke.omqkhafi.dev](https://oke.omqkhafi.dev) · **Handbook:** [/docs](https://oke.omqkhafi.dev/docs) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke)
+<p align="center">
+  <a href="https://oke.omqkhafi.dev"><strong>Docs</strong></a> ·
+  <a href="https://oke.omqkhafi.dev/docs"><strong>Handbook</strong></a> ·
+  <code>oke</code> CLI ·
+  <a href="https://www.npmjs.com/package/create-oke"><code>create-oke</code></a>
+</p>
 
 > [!WARNING]
 > **Early development (`v0.x`) — not production-ready.**
@@ -27,13 +96,13 @@ _"Stop gluing APIs, jobs, and queues into one backend. One law collapses them
 ```bash
 bun add okengine                                   # framework + `oke` CLI
 bunx jsr add @omqkhafi/okengine                    # JSR — library API only
-bunx create-oke@latest my-app --template hello     # scaffold
+bunx create-oke@latest my-app                      # scaffold
 ```
 
 ## Quick start
 
 ```bash
-bunx create-oke@latest my-app --template hello
+bunx create-oke@latest my-app
 cd my-app
 oke dev
 # or: oke mode docker && oke dev   # compose infra · app on host Bun
@@ -102,6 +171,72 @@ export const remove = mounted.remove;
 
 Full walkthrough: [Basic usage](https://oke.omqkhafi.dev/docs/get-started/basic-usage).
 
+## Charts
+
+<p align="center">
+  <a href="https://github.com/omqkhafi/okengine/issues">
+    <picture>
+      <source
+        media="(prefers-color-scheme: dark)"
+        srcset="https://shieldcn.dev/chart/github/issues/omqkhafi/okengine.svg?theme=zinc&font=geist&mode=dark"
+      />
+      <img
+        alt="GitHub issues over time"
+        src="https://shieldcn.dev/chart/github/issues/omqkhafi/okengine.svg?theme=zinc&font=geist&mode=light"
+        width="750"
+      />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/omqkhafi">
+    <picture>
+      <source
+        media="(prefers-color-scheme: dark)"
+        srcset="https://shieldcn.dev/chart/github/commits/omqkhafi.svg?theme=zinc&font=geist&mode=dark"
+      />
+      <img
+        alt="Lifetime commit history"
+        src="https://shieldcn.dev/chart/github/commits/omqkhafi.svg?theme=zinc&font=geist&mode=light"
+        width="750"
+      />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/okengine">
+    <picture>
+      <source
+        media="(prefers-color-scheme: dark)"
+        srcset="https://shieldcn.dev/chart/npm/okengine.svg?theme=zinc&font=geist&mode=dark"
+      />
+      <img
+        alt="okengine npm downloads"
+        src="https://shieldcn.dev/chart/npm/okengine.svg?theme=zinc&font=geist&mode=light"
+        width="750"
+      />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/create-oke">
+    <picture>
+      <source
+        media="(prefers-color-scheme: dark)"
+        srcset="https://shieldcn.dev/chart/npm/create-oke.svg?theme=zinc&font=geist&mode=dark"
+      />
+      <img
+        alt="create-oke npm downloads"
+        src="https://shieldcn.dev/chart/npm/create-oke.svg?theme=zinc&font=geist&mode=light"
+        width="750"
+      />
+    </picture>
+  </a>
+</p>
+
 ## Documentation
 
 Everything beyond this page lives in the site handbook:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -58,7 +58,7 @@
     "prepack": "bun run build",
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate": "bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
+    "gate": "PUBLISH_GATE=1 bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts scripts/publish.gate.test.ts",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
     "ci": "bun scripts/ci.ts",
@@ -71,8 +71,9 @@
     "@duckdb/node-api": "^1.5.5-r.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "intl-messageformat": "^11.2.13",
     "oxc-parser": "^0.142.0",
-    "sently": "^0.8.0"
+    "sently": "1.0.0"
   },
   "devDependencies": {
     "@base-ui/react": "^1.6.0",

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

@@ -88,6 +88,17 @@ export const triage = smart.prompt("ticket-triage", {
 
 <AiGuardrails />
 
+## Tools are flows (same `fx.call` path)
+
+Offer flows as tools on a one-shot ask — each model-initiated call goes through the host flow’s `fx.call`, so capability, Manifest `calls`, and Runs stay honest. No silent extra authority for the model:
+
+```typescript
+const result = await fx.ask(triage, input, {
+  tools: [getBooking, refundBooking],
+  maxSteps: 6,
+});
+```
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:
@@ -101,7 +112,25 @@ export const support = ai.agent("support", {
 });
 ```
 
-`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise.
+`maxSteps` bounds the loop; `budget.maxCostPerRun` bounds the spend. Both are declared, so "the agent ran away" is a violated contract, not a surprise. `fx.run(support, { message })` uses the same tool loop and the same `fx.call` dispatch as `fx.ask(…, { tools })`.
+
+## Rate limits via Gate
+
+AI calls are expensive — reuse `gate.rate`, don’t invent a parallel budget. Presets: `aiRateGate("ask" | "agent" | "embed")` (defaults 20 / 10 / 60 per minute, `keyBy: "user"`). Attach on the HTTP trigger:
+
+```typescript
+on(http.post("/triage").gate(member, aiRateGate("ask")), triageFlow);
+```
+
+Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/agent `budget` decls.
+
+## Secrets stay out of prompts
+
+`Redacted` values (e.g. from `fx.vault`) stringify to `[redacted]` in provider-facing messages — the same placeholder as logs. Never cleartext to a model.
+
+## Streaming
+
+`fx.stream(model, { prompt })` yields real provider tokens (Ollama NDJSON, OpenAI-compatible SSE). Cancel by aborting the ambient signal — the same one `fx.all` / `fx.race` already use. Drivers without `stream` fail loud (no stub echo).
 
 ## PII cannot leak by accident
 
@@ -130,6 +159,53 @@ Because `fx.ask` is nondeterministic, the runtime adjusts around it: journaling
 
 There is deliberately **no production default**: `prod` must name a driver, which keeps the model choice visible in `oke.config.ts` where review can see it.
 
+### Local Ollama
+
+`ollama` is a local-model driver — any model you have pulled works. Pin it in `drivers.ai`; optionally pin `images.ai` for compose.
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    ai: { local: "ollama", docker: "ollama", prod: "anthropic" },
+  },
+  images: {
+    ai: "ollama/ollama:latest",
+  },
+});
+```
+
+```typescript title="src/ai.ts"
+export const smart = ai.model("smart", {
+  provider: "ollama",
+  model: "qwen3.5:9b", // balanced local-dev starting point — override freely
+});
+```
+
+- **Model:** set on `ai.model(…, { model })` or `OKE_AI_MODEL`. `qwen3.5:9b` ([Ollama library](https://ollama.com/library/qwen3.5); same as `qwen3.5:latest`) is a reasonable balanced starting point for local dev — not the only option. On Apple Silicon, prefer `qwen3.5:9b-mlx` for the MLX build.
+- **URL:** default `http://127.0.0.1:11434`. Override with `OKE_AI_URL` or `OLLAMA_HOST` (bare `host:port` is fine).
+- **Docker:** the image recipe pulls the configured model and writes `OKE_AI_URL` into `docker/.env.docker`.
+- **Fail-loud:** unreachable or unhealthy Ollama throws `OllamaUnavailableError` — never a silent mock fallback.
+- **PII:** `ollama` counts as on-premise for the build-time egress check (same as `mock`).
+
+### OpenAI-compatible endpoints (one driver)
+
+`openai-compatible` is the shared chat/completions client — OpenAI, Groq, Together, OpenRouter, vLLM, LM Studio, and Ollama’s `/v1` shim. You do **not** get a separate driver per vendor; only `baseUrl`, `apiKey`, `model`, and optional `headers` change.
+
+| Target             | Typical `baseUrl`                     | Key                                                         |
+| ------------------ | ------------------------------------- | ----------------------------------------------------------- |
+| OpenAI             | `https://api.openai.com/v1` (default) | required (`OPENAI_API_KEY`)                                 |
+| Groq               | `https://api.groq.com/openai/v1`      | required                                                    |
+| Together           | `https://api.together.xyz/v1`         | required                                                    |
+| OpenRouter         | `https://openrouter.ai/api/v1`        | required; optional `HTTP-Referer` / `X-Title` via `headers` |
+| LM Studio / local  | e.g. `http://127.0.0.1:1234/v1`       | optional                                                    |
+| Ollama OpenAI shim | `http://127.0.0.1:11434/v1`           | optional                                                    |
+
+Prefer the native `ollama` driver for local Ollama (`/api/chat`). Point `openai-compatible` at Ollama `/v1` only when you need the OpenAI wire shape.
+
+**Consequence:** a missing key against the default OpenAI cloud base fails at open; a custom `baseUrl` may omit the key. HTTP errors always throw — never a silent mock fallback.
+
 ## Troubleshooting
 
 <Accordions>
@@ -142,6 +218,11 @@ A flow sends a classified PII field to a third-party model. Either stop sending
 
 The one you declared. There is no fallback or guess — if `prod` has no AI driver configured, that's a configuration gap to fix, not a silent default.
 
+</Accordion>
+<Accordion title="oke boot: ollama driver needs OKE_AI_URL">
+
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Locally, the default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers and that you have pulled the model you named (`ollama pull qwen3.5:9b`, or `qwen3.5:9b-mlx` on Apple Silicon, or your `OKE_AI_MODEL`).
+
 </Accordion>
 <Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">
 

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

@@ -87,7 +87,12 @@ Opt-out is first-class: a subject who opted out of a medium is **suppressed**
 
 ### Locale resolves through a chain
 
-Templates render per recipient locale, falling back through your configured chain (`ar` → default `en`) instead of failing when a translation is missing. Locales and the default come from the `i18n` block in `oke.config.ts`.
+Templates render per recipient locale, falling back through your configured chain
+(`ar` → default `en`) instead of failing when a translation is missing.
+
+Locales come from `oke.config.ts` `i18n`. Catalog bodies use `{{field}}` — not
+ICU ([i18n](/docs/reference/i18n) / `fx.t` owns flow copy). Pass `locale` /
+`profileLocale` / `acceptLanguage` on `fx.send`, or omit them for `fx.locale`.
 
 ### Fallback chains are explicit
 
@@ -104,23 +109,52 @@ Each send records its attempts — driver, ok/error, timestamp, message id — s
 
 ## Per-environment drivers
 
+Boot opens the email driver from `drivers.channel.email`, and appends an SMS
+driver when `drivers.channel.sms` is set (other than `console`). WhatsApp and
+push drivers are passed via `BootOptions.channel.drivers` when you need them.
+
 ```typescript title="oke.config.ts"
 drivers: {
   channel: {
     email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+    // optional — omit until you need SMS at boot
+    sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
   },
 },
 images: {
-  "channel.email": "axllent/mailpit:v1.22.3", // SMTP catcher for the docker stack
+  "channel.email": "axllent/mailpit:v1.22.3",
 },
 ```
 
-| 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 API                                           |
-| `unifonic` | sms    | Unifonic SMS API                                     |
+| 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                                    |
+
+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).
+
+`webpush` needs VAPID keys — open it yourself and include it in
+`BootOptions.channel.drivers` (boot does not open push from env):
+
+```typescript
+import { openWebPushChannel } from "okengine/drivers/channel-webpush";
+
+openWebPushChannel({
+  vapidPublicKey: process.env.VAPID_PUBLIC_KEY!,
+  vapidPrivateKey: process.env.VAPID_PRIVATE_KEY!,
+  vapidSubject: process.env.VAPID_SUBJECT,
+});
+```
 
 ## Troubleshooting
 
@@ -139,11 +173,44 @@ Check consent first: if they opted out, sends to them are suppressed by design.
 
 Locale resolution falls back through the chain to your default locale when a translation is missing — the send still succeeds with the fallback body. Check that the template declares `locales: ["en", "ar"]` and that the Arabic body exists in the catalog.
 
+</Accordion>
+<Accordion title="How do I ingest SNDR / Unifonic delivery webhooks?">
+
+```typescript
+import {
+  parseSndrWebhook,
+  verifySndrSignature,
+  parseUnifonicWebhook,
+  toDeliveryEvent,
+} from "okengine/channel";
+```
+
+Verify the signature when the provider sends one, parse the body, then call
+`ingestOutcome` on your channel runtime with the bounce/complaint fields.
+Console reads the receipt ledger — never raw webhook JSON.
+
 </Accordion>
 <Accordion title="How do I know which medium finally delivered?">
 
 The receipt keeps every attempt in order with its outcome. A send that succeeded on a later medium reports status `fallback` — you can see the full chain in Console → Channels.
 
+</Accordion>
+<Accordion title="How do I verify Web Push against a real browser?">
+
+Subscribe in a real browser with sently’s `examples/webpush-interop` page
+(paste the same `VAPID_PUBLIC_KEY`), copy the `PushSubscription` JSON, then:
+
+```sh
+export VAPID_PUBLIC_KEY='…'
+export VAPID_PRIVATE_KEY='…'
+bun scripts/webpush-interop.ts /tmp/push-sub.json
+```
+
+That path is Channel → `webpush` → sently `createPushSender` →
+`WebPushTransport`, and it prints the push-service HTTP response.
+
+Confirm a visible OS notification titled `okengine webpush interop`.
+
 </Accordion>
 </Accordions>
 
@@ -151,6 +218,8 @@ The receipt keeps every attempt in order with its outcome. A send that succeeded
 
 - [Flow](/docs/elements/flow) — `fx.send` inside `do`
 - [Console · Channels](/docs/console/channels) — receipts, attempts, suppression
+- [Environment Variables](/docs/reference/environment-variables) — Channel boot credentials
+- [Configuration](/docs/reference/configuration) — `drivers.channel.*` maps
 - [Signal](/docs/elements/signal) — machine-to-machine messaging, the other side of the line
 
 ## Next

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

@@ -92,7 +92,9 @@ do: async (input, fx) => {
 };
 ```
 
-Every response follows one envelope — success `{ data, error: null }`, failure `{ data: null, error: { code, data } }` — so clients handle outcomes by `error.code`, not by parsing status text.
+Every response follows one envelope — success `{ data, error: null }`, failure
+`{ data: null, error: { code, data, message? } }` — clients switch on `error.code`.
+Built-in codes attach a localized `message` ([Errors](/docs/reference/errors)); custom codes stay message-less unless registered or `{ message }` is passed.
 
 ## The five triggers
 
@@ -178,22 +180,22 @@ const order = await fx.call(getOrder, { id: orderId }); // from any other flow
 
 Everything a flow may touch, on one object:
 
-| Surface                                 | Effect recorded | What it does                                 |
-| --------------------------------------- | --------------- | -------------------------------------------- |
-| `fx.store(db).select/insert/…`          | read / write    | SQL, KV, files, index sessions               |
-| `fx.emit(signal, payload)`              | emit            | Publish a signal (transactional with writes) |
-| `fx.send(template, opts)`               | send            | Reach a human (email · SMS · …)              |
-| `fx.ask(prompt, input)`                 | ask             | Call a versioned AI prompt                   |
-| `fx.run(agent, input)`                  | ask             | Run a bounded agent                          |
-| `fx.call(flow, input)`                  | call            | Invoke another flow                          |
-| `fx.vault(contract)`                    | read            | Read a secret (`Redacted`; logs masked)      |
-| `fx.clock.now()` / `.sleep(…)`          | —               | Injected time / durable sleep                |
-| `fx.cache.get/set`                      | —               | Shared cache with effect-aware invalidation  |
-| `fx.step(name, fn)`                     | —               | Named durable step — never re-runs on replay |
-| `fx.all` / `fx.race` / `fx.retry`       | —               | Structured concurrency + backoff retry       |
-| `fx.signal`                             | —               | Ambient `AbortSignal` for the current branch |
-| `fx.id()` · `fx.log` · `fx.t`           | —               | UUIDs, redacting logger, i18n                |
-| `fx.auth` · `fx.operator` · `fx.tenant` | —               | Who is calling (user / operator / tenant)    |
+| Surface                                     | Effect recorded | What it does                                 |
+| ------------------------------------------- | --------------- | -------------------------------------------- |
+| `fx.store(db).select/insert/…`              | read / write    | SQL, KV, files, index sessions               |
+| `fx.emit(signal, payload)`                  | emit            | Publish a signal (transactional with writes) |
+| `fx.send(template, opts)`                   | send            | Reach a human (email · SMS · …)              |
+| `fx.ask(prompt, input)`                     | ask             | Call a versioned AI prompt                   |
+| `fx.run(agent, input)`                      | ask             | Run a bounded agent                          |
+| `fx.call(flow, input)`                      | call            | Invoke another flow                          |
+| `fx.vault(contract)`                        | read            | Read a secret (`Redacted`; logs masked)      |
+| `fx.clock.now()` / `.sleep(…)`              | —               | Injected time / durable sleep                |
+| `fx.cache.get/set`                          | —               | Shared cache with effect-aware invalidation  |
+| `fx.step(name, fn)`                         | —               | Named durable step — never re-runs on replay |
+| `fx.all` / `fx.race` / `fx.retry`           | —               | Structured concurrency + backoff retry       |
+| `fx.signal`                                 | —               | Ambient `AbortSignal` for the current branch |
+| `fx.id()` · `fx.log` · `fx.t` · `fx.locale` | —               | UUIDs, redacting logger, ICU i18n            |
+| `fx.auth` · `fx.operator` · `fx.tenant`     | —               | Who is calling (user / operator / tenant)    |
 
 <Callout title="Why this strictness pays off">
   Effects are inferred from `fx` usage, so the Manifest knows exactly which flows read `orders` or
@@ -275,6 +277,7 @@ Only that run fails — the schedule keeps firing and the process does not exit.
 
 ## Learn more
 
+- [fx](/docs/reference/fx) — full `fx` surface, including ICU `fx.t` / `fx.locale`
 - [Signal](/docs/elements/signal) — delivery physics (`once` · `broadcast` · `live`)
 - [Clock](/docs/elements/clock) — schedules and durable sleep
 - [Console · Flows](/docs/console/flows) — the Manifest-derived panel

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

@@ -5,12 +5,13 @@ icon: "MailCheck"
 source: "docs/spec/unified-theory.md"
 ---
 
-`emailOtp()` stores a hashed 6-digit code (default 10 minutes, 5 attempts). Verify creates the
-user on first success and returns hybrid session tokens.
+`emailOtp()` stores a hashed 6-digit code (default 10 minutes, 5 attempts). Request sends the
+code via Channel (`auth-email-otp`); verify creates the user on first success and returns hybrid
+session tokens.
 
 <Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(emailOtp())`. Never log raw OTPs. Channel email delivery is not
-  wired yet — use `exposeDevOtp` locally.
+  Enable `gate.auth`, then `.plug(emailOtp())`. Never log raw OTPs. Delivery goes through `fx.send`;
+  use `exposeDevOtp` only for local DX without SMTP.
 </Callout>
 
 ## Quick start
@@ -28,7 +29,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(emailOtp({ exposeDevOtp: true }));
+}).plug(emailOtp());
 ```
 
 </Step>
@@ -38,7 +39,7 @@ export const app = oke({
 
 ```typescript
 const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
-// data.devOtp when exposeDevOtp
+// Channel delivers auth-email-otp; data.devOtp only when exposeDevOtp
 ```
 
 `POST /auth/email-otp/request` — prior active codes for that email are invalidated.
@@ -51,7 +52,7 @@ const { data } = await api.auth.requestEmailOtp({ email: "ali@example.com" });
 ```typescript
 const { data } = await api.auth.verifyEmailOtp({
   email: "ali@example.com",
-  otp: data!.devOtp!,
+  otp,
 });
 ```
 
@@ -64,14 +65,15 @@ const { data } = await api.auth.verifyEmailOtp({
 
 ## 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 |
-| `identities`    | `IdentityStore`     | new      | Email → user 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                      |
+| `from`          | `string`            | `OKE <no-reply@oke.local>` | Template From address                   |
+| `exposeDevOtp`  | `boolean`           | `false`                    | Include raw OTP in the request response |
+| `identities`    | `IdentityStore`     | new                        | Email → user map                        |
+| `verifications` | `VerificationStore` | new                        | Challenge store                         |
 
 ## Surfaces
 
@@ -80,13 +82,16 @@ const { data } = await api.auth.verifyEmailOtp({
 | `auth.requestEmailOtp` | `POST /auth/email-otp/request` | `gate.public` + otp rate |
 | `auth.verifyEmailOtp`  | `POST /auth/email-otp/verify`  | `gate.public` + otp rate |
 
+**Consequence:** the plugin contributes the `auth-email-otp` Channel template and EN/AR
+catalog bodies (`{{otp}}`). Override copy by merging your own catalog at boot.
+
 ## Troubleshooting
 
 <Accordions>
 <Accordion title="No email with the code">
 
-v1 does not send mail. Use `exposeDevOtp` in local/test, or send the code via your own Channel
-Flow.
+In `local` / `test` the `console` driver captures mail — open the inbox, or run
+`oke dev --docker` and check Mailpit. For unit tests without SMTP, set `exposeDevOtp: true`.
 
 </Accordion>
 <Accordion title="AuthFailed after a few tries">
@@ -99,7 +104,8 @@ Five failed attempts consume the challenge. Request a new OTP.
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
-- [Phone number](/docs/plugins/phone-number) — SMS OTP (E.164)
+- [Phone number](/docs/plugins/phone-number) — SMS OTP (E.164; delivery deferred)
+- [Channel](/docs/elements/channel) — `fx.send`, Mailpit, consents
 - [Gate](/docs/elements/gate) — `gate.auth`
 
 ## Next
@@ -107,5 +113,5 @@ Five failed attempts consume the challenge. Request a new OTP.
 <Cards>
   <Card title="Phone number" description="E.164 SMS OTP." href="/docs/plugins/phone-number" />
   <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
-  <Card title="Two-factor" description="TOTP step-up." href="/docs/plugins/two-factor" />
+  <Card title="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
 </Cards>