okengine 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -71,6 +71,7 @@
     "@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"
   },

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
 

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>

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

@@ -76,9 +76,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 +94,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

@@ -72,11 +72,16 @@ Written by the first-boot bootstrap; you normally only set these when pointing a
 
 ## 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