okengine 0.6.1 → 0.8.0

package/AGENTS.md

@@ -78,9 +78,9 @@ A regression fails the build. Claims we cannot measure, we do not make.
 Published packages:
 
 - `okengine` — framework. Subpath exports: `.`, `./client`, `./test`, `./config`, `./auth`, `./plugins`, `./drivers/*`. `"sideEffects": false`. CLI binary: `oke`.
-- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships one standard starter from `packages/create-oke/template`.
+- `create-oke` — scaffold CLI (`bunx create-oke@latest <name>`). Lives in `packages/create-oke` and ships Notes starters from `packages/create-oke/templates/{standard,advanced}`.
 
-Engine: Bun `>=1.3`.
+Engine: Bun `>=1.3.14`.
 
 ## Documentation authority
 

package/README.md

@@ -13,66 +13,12 @@
 </p>
 
 <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>
+  <a href="https://www.npmjs.com/package/okengine"><img alt="npm" src="https://shieldcn.dev/npm/okengine.svg?size=sm&variant=outline" /></a>
+  <a href="https://jsr.io/@omqkhafi/okengine"><img alt="JSR" src="https://shieldcn.dev/jsr/@omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="MIT" src="https://shieldcn.dev/npm/license/okengine.svg?size=sm&variant=outline" /></a>
+  <a href="https://bun.sh"><img alt="Bun >=1.3.14" src="https://shieldcn.dev/badge/Bun-%3E%3D1.3.14.svg?logo=bun&size=sm&variant=outline" /></a>
+  <a href="https://github.com/omqkhafi/okengine/actions"><img alt="CI" src="https://shieldcn.dev/github/ci/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
+  <a href="https://github.com/omqkhafi/okengine/commits"><img alt="last commit" src="https://shieldcn.dev/github/last-commit/omqkhafi/okengine.svg?size=sm&variant=outline" /></a>
 </p>
 
 <p align="center">
@@ -82,7 +28,7 @@
 <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://oke.omqkhafi.dev/llms.txt"><code>llms.txt</code></a> ·
   <a href="https://www.npmjs.com/package/create-oke"><code>create-oke</code></a>
 </p>
 
@@ -93,10 +39,13 @@
 
 ## Install
 
+Requires [Bun](https://bun.sh) `>=1.3.14`.
+
 ```bash
+bunx create-oke@latest my-app                      # scaffold (recommended)
 bun add okengine                                   # framework + `oke` CLI
+bun install -g okengine                            # global `oke` on PATH
 bunx jsr add @omqkhafi/okengine                    # JSR — library API only
-bunx create-oke@latest my-app                      # scaffold
 ```
 
 ## Quick start
@@ -117,139 +66,82 @@ oke dev
 
 Mnemonic: **O·K·E = 6·5·3**.
 
-Every backend behavior is a Flow: `on(Trigger) → Effects`. World access goes through `fx`.
+The starter already exports a health Flow — change it and save; App and Console update from the same Manifest:
 
-Store apps sync schema with `oke db push|generate|migrate` (local `oke dev`
-auto-pushes). Prefer `store.schema.table` + `field.*` or keep a
-hand-written Drizzle `schema.ts`.
+```typescript
+import { on, flow, http, gate } from "okengine";
+import { z } from "zod";
+
+export const health = on(
+  http.get("/health").gate(gate.public),
+  flow({
+    out: z.object({ ok: z.literal(true) }),
+    do: () => ({ ok: true as const }),
+  }),
+);
+```
 
-### Resource Flow
+Call it with a typed client (contracts inferred — no separate codegen):
 
 ```typescript
-import { on, http, store } from "okengine";
-import { createInsertSchema, createSelectSchema } from "drizzle-zod";
-import { db } from "../../core";
-import { notes as notesTable } from "../../schema";
-
-// Contracts derived from the schema — one source of truth.
-const NewNote = createInsertSchema(notesTable, { title: (s) => s.min(1).max(120) }).omit({
-  id: true,
-  createdAt: true,
-});
-const Note = createSelectSchema(notesTable);
-
-// One declarative resource: list (cursor + search + filters + order +
-// select), create (201), get / update / remove with typed NotFound.
-const notesR = store.resource(db, notesTable, {
-  in: NewNote,
-  out: Note,
-  update: NewNote.partial(),
-  list: {
-    cursor: [notesTable.createdAt, notesTable.id],
-    direction: "desc",
-    limit: 20,
-    maxLimit: 100,
-    search: [notesTable.title],
-    filter: "all",
-    order: "all",
-  },
-  unit: "notes",
-  breaking: true,
-});
-
-// Mount all five verbs: list/create on /notes, get/update/remove on /notes/:id.
-// `on(http.resource(...))` returns the ops bag; spread it into named exports
-// so `adopt({ notes })` registers each flow under the unit.
-const mounted = on(http.resource("/notes", notesR.all()));
-
-export const list = mounted.list;
-export const create = mounted.create;
-export const get = mounted.get;
-export const update = mounted.update;
-export const remove = mounted.remove;
+import { createClient } from "okengine/client";
+import type { App } from "./app";
+
+const api = createClient<App>("http://localhost:6530");
+const { data, error } = await api.main.health({});
 ```
 
 Full walkthrough: [Basic usage](https://oke.omqkhafi.dev/docs/get-started/basic-usage).
 
-## Charts
+## One law
 
-<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>
+Every backend behavior is a Flow: `on(Trigger) → Effects`. Endpoints, jobs, consumers, and webhooks are the same species — only the trigger changes.
 
-<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>
+```typescript
+import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
+```
 
-<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>
+That is the entire public vocabulary. World access goes through `fx` — effects are inferred, so the Manifest can derive the typed client, Console, and MCP without a second source of truth.
 
-<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>
+| Element     | Essence                       |
+| ----------- | ----------------------------- |
+| **Flow**    | behavior                      |
+| **Signal**  | data in motion                |
+| **Store**   | data at rest                  |
+| **Clock**   | time                          |
+| **Gate**    | permission to act             |
+| **Vault**   | protected knowledge           |
+| **Channel** | reaching humans               |
+| **AI**      | reaching machine intelligence |
+
+Theory: [Introduction](https://oke.omqkhafi.dev/docs/get-started/introduction) · [Elements](https://oke.omqkhafi.dev/docs/elements) · [Why OKE](https://oke.omqkhafi.dev/docs/get-started/why).
+
+## Next
+
+| Want…                       | Go to                                                                  |
+| --------------------------- | ---------------------------------------------------------------------- |
+| Scaffold details & modes    | [Installation](https://oke.omqkhafi.dev/docs/get-started/installation) |
+| Declarative CRUD            | [`store.resource`](https://oke.omqkhafi.dev/docs/elements/store)       |
+| Auth, rate limits, sessions | [Gate](https://oke.omqkhafi.dev/docs/elements/gate)                    |
+| Queues & live events        | [Signal](https://oke.omqkhafi.dev/docs/elements/signal)                |
+| Email / SMS / push          | [Channel](https://oke.omqkhafi.dev/docs/elements/channel)              |
+| `oke` commands              | [CLI](https://oke.omqkhafi.dev/docs/reference/cli)                     |
+
+Store apps sync schema with `oke db push|generate|migrate` (local `oke dev` auto-pushes). Prefer `store.schema.table` + `field.*`, or keep a hand-written Drizzle `schema.ts`.
 
 ## Documentation
 
-Everything beyond this page lives in the site handbook:
+| Resource     | Link                                                           |
+| ------------ | -------------------------------------------------------------- |
+| Docs site    | [oke.omqkhafi.dev](https://oke.omqkhafi.dev)                   |
+| Get started  | [/docs/get-started](https://oke.omqkhafi.dev/docs/get-started) |
+| Handbook     | [/docs](https://oke.omqkhafi.dev/docs)                         |
+| Changelog    | [/changelog](https://oke.omqkhafi.dev/changelog)               |
+| Agents index | [/llms.txt](https://oke.omqkhafi.dev/llms.txt)                 |
+| Manifest     | [`manifest.v1.schema.json`](manifest.v1.schema.json)           |
+| Budgets      | [`BUDGETS.md`](BUDGETS.md)                                     |
+| Contributing | [`CONTRIBUTING.md`](CONTRIBUTING.md)                           |
 
-| Resource      | Link                                                               |
-| ------------- | ------------------------------------------------------------------ |
-| Docs site     | [oke.omqkhafi.dev](https://oke.omqkhafi.dev)                       |
-| Handbook      | [/docs](https://oke.omqkhafi.dev/docs)                             |
-| Changelog     | [/changelog](https://oke.omqkhafi.dev/changelog)                   |
-| Agents index  | [/llms.txt](https://oke.omqkhafi.dev/llms.txt)                     |
-| CLI reference | [/docs/reference/cli](https://oke.omqkhafi.dev/docs/reference/cli) |
-| Manifest      | [`manifest.v1.schema.json`](manifest.v1.schema.json)               |
-| Budgets       | [`BUDGETS.md`](BUDGETS.md)                                         |
-| Contributing  | [`CONTRIBUTING.md`](CONTRIBUTING.md)                               |
+## License
 
-Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine). MIT.
+Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine). [MIT](https://opensource.org/licenses/MIT).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.6.1",
+  "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",
@@ -150,6 +150,6 @@
     }
   },
   "engines": {
-    "bun": ">=1.3"
+    "bun": ">=1.3.14"
   }
 }

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

@@ -14,15 +14,35 @@ Answers: **upcoming crons, sleeping durable flows, journal**
 ## What this panel shows
 
 <Cards>
+  <Card title="Schedules" description="Drift, overdue, missed runs · catch-up one, lease holder." />
+  <Card title="Pending wakes" description="Every sleeping durable flow and when it wakes." />
   <Card
-    title="Schedules"
-    description="Recurring crons with drift, overdue, catch-up, lease holder."
+    title="DST warnings"
+    description="Gap or overlap badge — detect only, no schedule rewrite."
   />
-  <Card title="Pending wakes" description="Every sleeping durable flow and when it wakes." />
-  <Card title="DST warnings" description="Only when the schedule falls in an ambiguous window." />
-  <Card title="Actions" description="Run now, wake early, pause, edit when overridable." />
+  <Card title="Actions" description="Run now, wake early, pause; edit when overridable." />
 </Cards>
 
+## Health numbers
+
+Each cron row projects four numbers plus the lease holder:
+
+| Field           | Meaning                                                           |
+| --------------- | ----------------------------------------------------------------- |
+| Drift           | How far the last run sat from the expected slot                   |
+| Overdue         | Whether the schedule is past due                                  |
+| Missed + policy | Slot count while down · always catch-up `"one"` (one fire, not N) |
+| Lease           | Which instance holds the leader lease (empty when none)           |
+
+## Actions
+
+| Action        | When                                                                   |
+| ------------- | ---------------------------------------------------------------------- |
+| Pause         | Any cron — not gated by `overridable`                                  |
+| Edit schedule | Only when the declaration has `overridable: true`; else loud refuse    |
+| Wake early    | Sleeping durable run — advances `wakeAt` and can resume the journal    |
+| Run now       | Still requires the leader lease across replicas that share a CronStore |
+
 ## Catalog
 
 <Cards>

package/site/content/docs/console/signals.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Signals"
-description: "Queue depth, in-flight, DLQ, live monitors."
+description: "Queue depth, in-flight, DLQ, live monitors, orphaned config."
 icon: "Radio"
 source: "docs/spec/console.md"
 ---
 
-Answers: **queue depth, in-flight, DLQ, live monitors**
+Answers: **queue depth, in-flight, DLQ, live monitors, orphaned config**
 
 <Callout title="Governing rule">
   One list grouped by delivery physics — not three tabs that re-split the element.
@@ -14,15 +14,24 @@ Answers: **queue depth, in-flight, DLQ, live monitors**
 ## What this panel shows
 
 <Cards>
-  <Card title="once" description="Pending, in-flight, DLQ, retry policy." />
+  <Card title="once" description="Pending, in-flight (leased), DLQ, retry policy." />
   <Card title="broadcast" description="Per-subscriber lag and targeted replay." />
-  <Card title="live" description="Connection count, throughput, payload monitor." />
+  <Card
+    title="live"
+    description="Connection count, throughput, newest-50 payload monitor (full history still retained)."
+  />
   <Card
     title="DLQ repair"
     description="Schema form, typed errors, causal chain, dry-run bulk replay."
   />
+  <Card
+    title="Orphaned"
+    description="Config still listed after the declaration left code — messages kept; dry-run refused."
+  />
 </Cards>
 
+Dry-run is refused for orphaned signals and for signals with no Manifest consumer — unknown handler shapes are not invoked unsafely. Restore the `signal(…)` declaration (and a consumer) before replaying DLQ rows. Lease / at-least-once physics live on [Signal](/docs/elements/signal).
+
 ## Catalog
 
 <Cards>

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

@@ -77,6 +77,8 @@ export const triage = smart.prompt("ticket-triage", {
 | `ai.embed(name, opts)`     | Embedding pipeline into a `store.index` (searched via `fx.search`) |
 | `ai.agent(name, opts)`     | Bounded agent whose tools are **your own flows**                   |
 
+<AiBlocks />
+
 ### Prompt options
 
 | Option       | Type                  | Meaning                                                        |
@@ -86,6 +88,10 @@ export const triage = smart.prompt("ticket-triage", {
 | `evals`      | string                | Path to a `.jsonl` eval set, regression-gated via `oke eval`   |
 | `budget`     | object                | `maxCostPerCall` — cost is a first-class dimension             |
 
+## Declared guardrails
+
+Cost, egress, and model choice are contracts — not runtime hope. Each guardrail is declared up front; violating one fails the build or the run.
+
 <AiGuardrails />
 
 ## Tools are flows (same `fx.call` path)
@@ -136,6 +142,8 @@ Use `keyBy: "ip"` on public unauthenticated AI edges. Cost caps stay on prompt/a
 
 At build time, OKE checks which fields each `fx.ask` sends against your store classifications. If a PII field (`.pii()` in your schema) would reach a third-party model, the build fails:
 
+<AiPiiEgress />
+
 ```text
 build failed: flow "ticket-triage" sends pii field(s) [email] to a third-party model without allowPii
 ```
@@ -159,9 +167,28 @@ 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.
 
+### Setup wizard
+
+```bash title="Terminal"
+oke ai setup
+oke ai setup --provider ollama --yes
+```
+
+Writes `drivers.ai`, `.env.local`, and `src/ai.ts`.
+
+Ollama: short quiz (use case · speed/quality · vision) → detect installed models
+→ picks that fit your **machine tier** (~4GB OS/IDE headroom). Labels say
+**≈16GB-class**, not “download 16GB” — pull size is usually much smaller than RAM.
+
+Cloud: short chat list + **Other…** for any model id. **← Back** returns a step.
+`create-oke` runs the same model wizard **before** install when you enable AI
+(customize or `--ai`). Standalone `oke ai setup` remains for existing apps.
+
 ### 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.
+`ollama` is a local-model driver — any pulled model works. Pin `drivers.ai`;
+optionally pin `images.ai` for compose. Native `complete`, `stream`, and
+`embed` (`POST /api/embeddings`) — no OpenAI shim required for local RAG.
 
 ```typescript title="oke.config.ts"
 import { defineConfig } from "okengine/config";
@@ -221,7 +248,7 @@ The one you declared. There is no fallback or guess — if `prod` has no AI driv
 </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`).
+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`). Prefer `oke ai setup` to wire driver, env, and `src/ai.ts` in one pass.
 
 </Accordion>
 <Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">

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

@@ -5,7 +5,7 @@ icon: "Mail"
 source: "docs/spec/unified-theory.md"
 ---
 
-Channel is how your app **reaches humans**: the order-confirmation email, the OTP text, the WhatsApp notification. Reaching a person is not the same problem as moving data between machines — it needs consent (did they opt out?), locale (which language?), receipts (did it land?), and fallback (email failed, try SMS). Those physics are built into the element, so every flow gets them for free.
+Channel is how your app **reaches humans**: the order-confirmation email, the OTP text, the WhatsApp notification. Reaching a person is not the same problem as moving data between machines — it needs consent (did they opt out?), locale (which language?), receipts (did it land?), and fallback (first driver failed, try the next). Those physics are built into the element, so every flow gets them for free.
 
 <Callout title="The one rule">
   Sends go through `fx.send` and declared templates — never through a raw SMTP or provider client
@@ -83,29 +83,35 @@ Locally the `console` driver captures mail into an inbox instead of sending; in
 
 ### Consent is checked before sending
 
-Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt says so. You never hand-roll "did they unsubscribe?" checks.
+Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt status is `suppressed/opted-out`. You never hand-roll "did they unsubscribe?" checks.
 
-### Locale resolves through a chain
+### Locale resolves, then the catalog
 
-Templates render per recipient locale, falling back through your configured chain
-(`ar` → default `en`) instead of failing when a translation is missing.
+`fx.send` picks a locale: explicit `locale` → `profileLocale` → first
+`Accept-Language` tag → `defaultLocale`. The body is the catalog entry for
+that exact key, else the default locale, else `en`.
 
 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
+### Fallback chains are same-medium
 
-`via` orders the mediums to try — first success wins, and **every** attempt is recorded:
+`via` orders **driver ids** for the template's medium — first success wins,
+and **every** attempt is recorded:
 
 ```typescript
-await fx.send(otpCode, { to: user.phone, data: { code }, via: [sms, wa] });
-// sms fails → whatsapp tried → receipt status "fallback" with both attempts
+await fx.send(orderConfirmed, {
+  to: user.email,
+  data: { name, orderId, total },
+  via: ["smtp", "resend"],
+});
+// smtp fails → resend tried → receipt status "fallback" with both attempts
 ```
 
 ### Receipts for everything
 
-Each send records its attempts — driver, ok/error, timestamp, message id — so "did the user actually get it?" is a Console query, not a guess. In a dry run, sends are recorded as _would have fired_ and never contact a real provider.
+Each send records its attempts — driver, ok/error, timestamp, message id — so "did the user actually get it?" is a Console query, not a guess. In a dry run, the kernel records a would-have-fired send and never opens a provider — no Channel receipt is written.
 
 ## Per-environment drivers
 
@@ -126,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):
 
@@ -171,7 +188,7 @@ Check consent first: if they opted out, sends to them are suppressed by design.
 </Accordion>
 <Accordion title="The Arabic version didn't render">
 
-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.
+The send still succeeds: the body falls back to your default locale, then `en`, when the catalog misses that exact key. Check that an Arabic entry exists under the same tag you send (`ar` vs `ar-SA`) and that the template lists it in `locales`.
 
 </Accordion>
 <Accordion title="How do I ingest SNDR / Unifonic delivery webhooks?">
@@ -190,9 +207,9 @@ Verify the signature when the provider sends one, parse the body, then call
 Console reads the receipt ledger — never raw webhook JSON.
 
 </Accordion>
-<Accordion title="How do I know which medium finally delivered?">
+<Accordion title="How do I know which driver 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.
+The receipt keeps every attempt in order with its outcome. A send that succeeded on a later driver 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?">