okengine 0.5.1 → 0.6.1

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

@@ -5,12 +5,13 @@ icon: "Link2"
 source: "docs/spec/unified-theory.md"
 ---
 
-`magicLink()` issues a hashed, single-use token (default 10 minutes). Verify exchanges it for a
-hybrid session and creates the user on first success.
+`magicLink()` issues a hashed, single-use token (default 10 minutes). Request sends the link
+via Channel (`auth-magic-link`); verify exchanges it for a hybrid session and creates the user
+on first success.
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(magicLink())`. Tokens are hashed at rest — never log the raw link.
-  Channel email delivery is not wired yet; use `exposeDevToken` locally.
+  Delivery goes through `fx.send`; use `exposeDevToken` only for local DX without SMTP.
 </Callout>
 
 ## Quick start
@@ -28,7 +29,7 @@ export const app = oke({
   name: "shop",
   env: "local",
   gate: { auth: {} },
-}).plug(magicLink({ exposeDevToken: true }));
+}).plug(magicLink({ baseUrl: "http://127.0.0.1:6530" }));
 ```
 
 </Step>
@@ -38,10 +39,12 @@ export const app = oke({
 
 ```typescript
 const { data } = await api.auth.requestMagicLink({ email: "ali@example.com" });
-// data.ok === true; data.devToken only when exposeDevToken
+// data.ok === true; Channel delivers auth-magic-link
+// data.devToken only when exposeDevToken
 ```
 
-`POST /auth/magic-link/request`.
+`POST /auth/magic-link/request`. Locally the `console` driver captures mail; with
+`oke dev --docker`, Mailpit receives the real SMTP message.
 
 </Step>
 
@@ -49,7 +52,7 @@ const { data } = await api.auth.requestMagicLink({ email: "ali@example.com" });
 ### Verify
 
 ```typescript
-const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
+const { data } = await api.auth.verifyMagicLink({ token });
 // session tokens + userId
 ```
 
@@ -62,14 +65,16 @@ const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
 
 ## Options
 
-| Option           | Type                | Default  | Meaning                                   |
-| ---------------- | ------------------- | -------- | ----------------------------------------- |
-| `secret`         | `string`            | active\* | HMAC secret (\*from `gate.auth`)          |
-| `sessions`       | `SessionStore`      | active\* | Session store                             |
-| `ttlMs`          | `number`            | 10m      | Challenge lifetime                        |
-| `exposeDevToken` | `boolean`           | `false`  | Include raw token 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                        |
+| `baseUrl`        | `string`            | `OKE_APP_URL` or `:6530`   | Origin used to build the magic link       |
+| `from`           | `string`            | `OKE <no-reply@oke.local>` | Template From address                     |
+| `exposeDevToken` | `boolean`           | `false`                    | Include raw token in the request response |
+| `identities`     | `IdentityStore`     | new                        | Email → user map                          |
+| `verifications`  | `VerificationStore` | new                        | Challenge store                           |
 
 ## Surfaces
 
@@ -78,8 +83,8 @@ const { data } = await api.auth.verifyMagicLink({ token: data!.devToken! });
 | `auth.requestMagicLink` | `POST /auth/magic-link/request` | `gate.public` + otp rate |
 | `auth.verifyMagicLink`  | `POST /auth/magic-link/verify`  | `gate.public` + otp rate |
 
-**Consequence:** until Channel delivery ships, production apps must send the link themselves
-(or keep `exposeDevToken` off and never log tokens).
+**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.
 
 ## Troubleshooting
 
@@ -91,8 +96,9 @@ Token expired (default 10m), already used, or mistyped. Request a new link.
 </Accordion>
 <Accordion title="No email arrived">
 
-v1 does not send mail. Use `exposeDevToken` in local/test, or deliver `devToken` / your own
-link via a Channel Flow you own.
+In `local` / `test` the `console` driver captures mail into the inbox — nothing hits a mailbox.
+Run `oke dev --docker` and open Mailpit (`MAILPIT_UI_URL`) to see the rendered message. For
+unit tests without SMTP, set `exposeDevToken: true`.
 
 </Accordion>
 </Accordions>
@@ -101,12 +107,12 @@ link via a Channel Flow you own.
 
 - [Email OTP](/docs/plugins/email-otp) — numeric code instead of a link
 - [Gate](/docs/elements/gate) — `gate.auth`
-- [Channel](/docs/elements/channel) — when you wire delivery yourself
+- [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="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
-  <Card title="Username" description="Password sign-in." href="/docs/plugins/username" />
+  <Card title="Channel" description="Email delivery and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -30,6 +30,7 @@ drivers: {
   vault: { local: "dotenv", docker: "openbao", test: "memory", prod: "openbao" },
   channel: {
     email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+    sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
   },
 },
 ```
@@ -43,10 +44,10 @@ drivers: {
 | `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
 | `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
 | `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |
-| `channel.email`    | env driver map | `console` · `smtp` · `resend`                                                |
-| `channel.sms`      | env driver map | `console` · `unifonic`                                                       |
-| `channel.whatsapp` | env driver map | medium declared; drivers added per provider                                  |
-| `channel.push`     | env driver map | medium declared; drivers added per provider                                  |
+| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr`                                       |
+| `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`                                                |
 | `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama` |
 | `runs`             | env driver map | runs-store driver (distinct from top-level `runs`)                           |
 | `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred              |
@@ -76,9 +77,12 @@ images: {
   "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",
 },
 ```
 
+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`.
+
 ## i18n
 
 | Option    | Type       | Default | Meaning                                     |
@@ -91,6 +95,10 @@ images: {
 i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
 ```
 
+`fx.t` catalogs are ICU strings from `defineLocale` / `defineMessages` — see
+[i18n](/docs/reference/i18n). Built-ins also cover failure `error.message` and
+OKE cause/fix; Channel templates keep separate `locales` + `{{field}}` bodies.
+
 ## tenancy
 
 Multi-tenant isolation policy.

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

@@ -61,22 +61,51 @@ Written by the first-boot bootstrap; you normally only set these when pointing a
 | `OKE_VAULT_TOKEN` | App token (least-privilege) | —                  |
 | `OKE_VAULT_MOUNT` | KV v2 mount path            | `"secret"`         |
 
-## Channel (email)
-
-| Variable                | Used for                                  |
-| ----------------------- | ----------------------------------------- |
-| `SMTP_URL`              | Full SMTP connection string (`smtp://…`)  |
-| `SMTP_USER`             | Overrides the user embedded in `SMTP_URL` |
-| `SMTP_PASSWORD`         | Overrides the password in `SMTP_URL`      |
-| `OKE_CHANNEL_EMAIL_URL` | OKE-specific alternative to `SMTP_URL`    |
+## Channel (email) — boot binder
+
+Read when `drivers.channel.email` resolves to that driver id.
+
+| Variable                | Used for                                         |
+| ----------------------- | ------------------------------------------------ |
+| `SMTP_URL`              | `smtp` — full SMTP URL (`smtp://…`)              |
+| `SMTP_USER`             | Overrides the user embedded in `SMTP_URL`        |
+| `SMTP_PASSWORD`         | Overrides the password in `SMTP_URL`             |
+| `OKE_CHANNEL_EMAIL_URL` | Alternative to `SMTP_URL`                        |
+| `RESEND_API_KEY`        | `resend` API key                                 |
+| `SNDR_API_KEY`          | `sndr` API key                                   |
+| `SNDR_BASE_URL`         | Optional SNDR API origin (default `api.sndr.sh`) |
+
+## Channel (SMS) — boot binder
+
+Read when `drivers.channel.sms` resolves to that driver id (`console` opens nothing).
+
+| Variable               | Used for                         |
+| ---------------------- | -------------------------------- |
+| `TAQNYAT_BEARER_TOKEN` | `taqnyat` bearer token           |
+| `TAQNYAT_TOKEN`        | Alias for `TAQNYAT_BEARER_TOKEN` |
+| `TAQNYAT_SENDER`       | Taqnyat pre-approved sender id   |
+| `MSEGAT_USERNAME`      | `msegat` account username        |
+| `MSEGAT_API_KEY`       | `msegat` API key                 |
+| `MSEGAT_SENDER`        | Msegat pre-approved sender id    |
+| `UNIFONIC_APPSID`      | `unifonic` AppSid                |
+| `UNIFONIC_APP_SID`     | Alias for `UNIFONIC_APPSID`      |
+| `UNIFONIC_SENDER`      | Unifonic SenderID (optional)     |
+
+WhatsApp (`wa-cloud`) and push (`webpush` / `fcm`) are not opened from env at
+boot — pass them on `BootOptions.channel.drivers` with their open options.
 
 ## AI providers
 
-| Variable            | Used for                                |
-| ------------------- | --------------------------------------- |
-| `ANTHROPIC_API_KEY` | `anthropic` driver credential           |
-| `ANTHROPIC_MODEL`   | Model override for the anthropic driver |
-| `OPENAI_API_KEY`    | `openai-compatible` driver credential   |
+| Variable            | Used for                                                                                                                                  | Default when unset                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| `ANTHROPIC_API_KEY` | `anthropic` driver credential                                                                                                             | —                                 |
+| `ANTHROPIC_MODEL`   | Model override for the anthropic driver                                                                                                   | —                                 |
+| `OPENAI_API_KEY`    | `openai-compatible` driver credential                                                                                                     | —                                 |
+| `OPENAI_BASE_URL`   | `openai-compatible` base URL                                                                                                              | OpenAI cloud                      |
+| `OKE_AI_DRIVER`     | Force the AI driver id (honoured in docker mode)                                                                                          | config map                        |
+| `OKE_AI_URL`        | Ollama (or openai-compatible) base URL                                                                                                    | `http://127.0.0.1:11434` (ollama) |
+| `OKE_AI_MODEL`      | Default model for `ollama` (any pulled model; `qwen3.5:9b` is a balanced local-dev starting point; on Apple Silicon try `qwen3.5:9b-mlx`) | `qwen3.5:9b`                      |
+| `OLLAMA_HOST`       | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                                                     | —                                 |
 
 ## Framework behavior
 

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

@@ -14,6 +14,19 @@ OKE1101  domain table not found — migrations have not been applied.
 
 Codes are permanent once published — you can match on them safely across upgrades.
 
+## Localized messages
+
+Typed failures and OKE codes ship English and Arabic ICU catalogs. Locale comes
+from `Accept-Language` (matched to `i18n.locales`); fallback is `i18n.default`.
+
+| Surface            | Keys                                       | How it appears                           |
+| ------------------ | ------------------------------------------ | ---------------------------------------- |
+| `fx.fail` / `fail` | `errors.{code}` · `errors.{code}.{reason}` | Optional `error.message` on the envelope |
+| Thrown `OkeError`  | `oke.{code}.cause` · `oke.{code}.fix`      | Cause + fix lines in the thrown message  |
+
+Override via `defineLocale`. Pass `fail(code, data, { message })` for a custom
+string. Custom app codes stay message-less until registered.
+
 ## OKE numeric codes
 
 | Code   | Name              | Cause                                            | Fix                                             |
@@ -75,6 +88,7 @@ Thrown by specific subsystems — each names its own cause:
 
 ## Learn more
 
+- [i18n](/docs/reference/i18n) — catalogs, `fx.t`, locale matching
 - [Flow](/docs/elements/flow) — `fx.fail` and the response envelope
 - [Gate](/docs/elements/gate) — where the three denials come from
 - [CLI Reference](/docs/reference/cli) — `oke db migrate` and friends

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

@@ -102,20 +102,23 @@ const rows = await fx.using(
 
 ## Channel
 
-| Signature                                 | Records | Notes                                                               |
-| ----------------------------------------- | ------- | ------------------------------------------------------------------- |
-| `fx.send(template, { to?, data?, via? })` | `send`  | `via` orders the fallback chain; dry runs record _would have fired_ |
+| Signature                                    | Records | Notes                                                                                      |
+| -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| `fx.send(template, { to?, data?, via?, … })` | `send`  | `via` orders fallback; `locale` / `profileLocale` / `acceptLanguage` feed the locale chain |
+
+Omit locale opts and the send uses `fx.locale`. Dry runs record _would have fired_ and never
+contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Channel](/docs/elements/channel)).
 
 ## AI
 
-| Signature                              | Records | Returns                                     |
-| -------------------------------------- | ------- | ------------------------------------------- |
-| `fx.ask(prompt, input?, { via? })`     | `ask`   | Object validated against the prompt's `out` |
-| `fx.run(agent, input?)`                | `ask`   | Agent result                                |
-| `fx.stream(model, { prompt?, data? })` | `ask`   | `AsyncIterable<string>` of chunks           |
-| `fx.search(embed, query, { topK? })`   | `read`  | Matches from the index/embed                |
+| Signature                                             | Records                   | Returns                                                                       |
+| ----------------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------- |
+| `fx.ask(prompt, input?, { via?, tools?, maxSteps? })` | `ask` (+ `call` per tool) | Object validated against the prompt's `out`                                   |
+| `fx.run(agent, input?)`                               | `ask`                     | Agent result                                                                  |
+| `fx.stream(model, { prompt?, data? })`                | `ask`                     | `AsyncIterable<string>` — real driver stream; cancels via ambient `fx.signal` |
+| `fx.search(embed, query, { topK? })`                  | `read`                    | Matches from the index/embed                                                  |
 
-AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them.
+AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 
 ## Vault
 
@@ -153,11 +156,59 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 
 ## Logging, i18n, ids
 
-| Signature                                  | Notes                                    |
-| ------------------------------------------ | ---------------------------------------- |
-| `fx.log.debug/info/warn/error(msg, data?)` | Redacting — secrets print as `***`       |
-| `fx.t(key, params?)`                       | Localized message from the `i18n` config |
-| `fx.id()`                                  | UUID — the only legal id generator       |
+| Signature                                  | Notes                                                       |
+| ------------------------------------------ | ----------------------------------------------------------- |
+| `fx.log.debug/info/warn/error(msg, data?)` | Redacting — secrets print as `***`                          |
+| `fx.t(key, values?)`                       | ICU MessageFormat — active locale → `i18n.default` → key    |
+| `fx.locale`                                | Active locale (`Accept-Language` matched to `i18n.locales`) |
+| `fx.id()`                                  | UUID — the only legal id generator                          |
+
+`fx.t` uses [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
+(FormatJS): `{name}`, plurals, `select` / `selectordinal`, rich-text tags.
+Full syntax and escaping: [i18n · ICU](/docs/reference/i18n#icu-messageformat).
+
+Register catalogs with `defineLocale` before boot (nested trees → dot keys). Augment
+`Register` so keys autocomplete and typos fail at compile time:
+
+```typescript
+import { defineLocale, defineMessages, type MessagesFor } from "okengine";
+
+export const en = defineMessages({
+  greeting: "Hello, {name}",
+  items: "{count, plural, one {# item} other {# items}}",
+  place: "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!",
+  status: "{status, select, online {Online} offline {Offline} other {Unknown}}",
+  cta: "Read <docs>the docs</docs>",
+});
+defineLocale("en", en);
+
+defineLocale("ar", {
+  greeting: "مرحباً، {name}",
+  items: "{count, plural, zero {لا عناصر} one {عنصر واحد} other {# عناصر}}",
+  place: "أنهيت في المرتبة {place, selectordinal, other {#}}!",
+  status: "{status, select, online {متصل} offline {غير متصل} other {غير معروف}}",
+  cta: "اقرأ <docs>التوثيق</docs>",
+} satisfies MessagesFor<typeof en>);
+
+declare module "okengine" {
+  interface Register {
+    messages: typeof en;
+  }
+}
+```
+
+```typescript
+fx.t("greeting", { name: input.name });
+fx.t("items", { count: 3 });
+fx.t("cta", { docs: (chunks) => `<a href="/docs">${chunks.join("")}</a>` });
+```
+
+Supported locales and the fallback come from `oke.config.ts` `i18n`.
+`create-oke` scaffolds English and Arabic locale modules already wired this way.
+
+Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
+`OkeError` cause/fix the same way — full i18n guide:
+[i18n](/docs/reference/i18n), [Errors](/docs/reference/errors).
 
 ## Principals
 
@@ -181,5 +232,6 @@ must log who started the call chain.
 ## Learn more
 
 - [Flow](/docs/elements/flow) — why `fx` is the only door
+- [Channel](/docs/elements/channel) — `fx.send`, consent, locale chain, `{{field}}` catalogs
 - [Errors](/docs/reference/errors) — what `fx.fail` produces
-- [Configuration](/docs/reference/configuration) — the drivers behind these calls
+- [Configuration](/docs/reference/configuration) — drivers and the `i18n` block