okengine 0.22.0 → 0.23.1

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

@@ -0,0 +1,373 @@
+---
+title: "Events"
+description: "Stream an agent run to a chat UI as AG-UI events over server-sent events."
+icon: "Radio"
+source: "docs/spec/unified-theory.md"
+---
+
+An agent stream is the same tool loop as `fx.run`, delivered while the model is still working. A support chat shows tokens, tool calls, and a finish reason as server-sent events.
+
+Return `fx.json.stream` from the HTTP Flow. Parse the frames with `okengine/client/agent`.
+
+<Callout title="The one rule">
+  `return fx.json.stream(fx.run(agent, input, { stream: true }))`. `stream` is the third argument.
+  `fx.stream` yields plain text from a model, not these events.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare the agent
+
+```typescript title="src/core/ai.ts"
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+});
+
+export const support = ai.agent("support", {
+  model: smart,
+  tools: ["orders.get"],
+  maxSteps: 4,
+});
+```
+
+</Step>
+
+<Step>
+### Stream it from HTTP
+
+```typescript title="src/flows/support/assist.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { support } from "@/core/ai";
+
+export const assist = on(
+  http.post({ in: z.object({ message: z.string().min(1) }) }).public(),
+  flow({
+    do: ({ message }, fx) => fx.json.stream(fx.run(support, { message }, { stream: true })),
+  }),
+);
+```
+
+The response is `text/event-stream`. Pass your own `threadId` when the chat already has one. The default is a unique id. It is not a per-process counter.
+
+</Step>
+
+<Step>
+### Read the frames
+
+```bash
+curl -N -X POST http://localhost:6530/support/assist \
+  -H "content-type: application/json" \
+  -d '{"message":"Where is order 14?"}'
+```
+
+Each `data:` line is one JSON event. A text reply with no tool call looks like this (ids vary):
+
+```text
+data: {"type":"RUN_STARTED","threadId":"agent-run-1","runId":"agent-run-1"}
+
+data: {"type":"STEP_STARTED","stepName":"step-1"}
+
+data: {"type":"TEXT_MESSAGE_START","messageId":"m-1","role":"assistant"}
+
+data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m-1","delta":"Order 14 is open."}
+
+data: {"type":"TEXT_MESSAGE_END","messageId":"m-1"}
+
+data: {"type":"STEP_FINISHED","stepName":"step-1"}
+
+data: {"type":"RUN_FINISHED","threadId":"agent-run-1","runId":"agent-run-1","result":{"cost":0.01,"stopReason":"completed","output":"Order 14 is open."},"usage":[{"inputTokens":3,"outputTokens":2}]}
+
+data: [DONE]
+```
+
+`usage` is present only when the model reported token counts. `cost` and `stopReason` are on `result`, not on `usage`.
+
+</Step>
+
+<Step>
+### Parse with the client
+
+```typescript
+import { readAgentEvents } from "okengine/client/agent";
+
+const response = await fetch("http://localhost:6530/support/assist", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ message: "Where is order 14?" }),
+});
+
+for await (const event of readAgentEvents(response)) {
+  if (event.type === "TEXT_MESSAGE_CONTENT") process.stdout.write(event.delta);
+}
+```
+
+Import `okengine/client/agent`. That module stays off `okengine/client`.
+
+</Step>
+
+</Steps>
+
+## Event reference
+
+Core names match AG-UI. Subagent notices are `CUSTOM`, not extra types.
+
+| Type                   | Fields                                               | When it fires                                                                                                                           |
+| ---------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `RUN_STARTED`          | `threadId`, `runId`                                  | The run begins. `threadId` is the option you passed, or the run id.                                                                     |
+| `STEP_STARTED`         | `stepName`                                           | A step starts. `maxSteps` counts tool calls, not model calls. Names are `step-1`, `step-2`, …                                           |
+| `TEXT_MESSAGE_START`   | `messageId`, `role`                                  | Assistant text is about to arrive. `role` is `assistant`. Empty text is skipped.                                                        |
+| `TEXT_MESSAGE_CONTENT` | `messageId`, `delta`                                 | One piece of assistant text. A streaming driver emits one frame per delta. A driver without `stream` emits the whole turn in one frame. |
+| `TEXT_MESSAGE_END`     | `messageId`                                          | That text message is complete.                                                                                                          |
+| `TOOL_CALL_START`      | `toolCallId`, `toolCallName`, `parentMessageId?`     | The model named a tool. `parentMessageId` is set when that step emitted assistant text.                                                 |
+| `TOOL_CALL_ARGS`       | `toolCallId`, `delta`                                | One piece of the tool arguments. Streaming drivers emit each args delta. A driver without `stream` emits one JSON string.               |
+| `TOOL_CALL_END`        | `toolCallId`                                         | Arguments are complete. The tool has not run yet.                                                                                       |
+| `TOOL_CALL_RESULT`     | `messageId`, `toolCallId`, `content`, `role`         | The tool returned. `role` is `tool`. `content` is a string.                                                                             |
+| `STEP_FINISHED`        | `stepName`                                           | That model step is done, including its tool calls.                                                                                      |
+| `RUN_FINISHED`         | `threadId`, `runId`, `result?`, `usage?`, `outcome?` | The loop stopped, or a tool is waiting for approval.                                                                                    |
+| `RUN_ERROR`            | `message`, `code?`                                   | The run failed and did not finish. `code` is the error name when it is not `Error`.                                                     |
+| `CUSTOM`               | `name`, `value`                                      | A nested agent started, finished, or failed.                                                                                            |
+
+`RUN_FINISHED.result` is `{ cost, stopReason, output }`. `cost` is the sum of model-reported spend for this run. `output` is the last tool result. A text reply with no tool call may be the raw provider payload, not the assistant string.
+
+`RUN_FINISHED.usage` is a one-element array, `{ inputTokens?, outputTokens? }`, and only when those numbers came from the model. Counts are never invented.
+
+`messageId` values are `m-1`, `m-2`, … inside the run. A missing provider tool-call id becomes `agent:step:index`.
+
+## Tool approval
+
+A tool with `approval` and `gate` parks a durable Flow. The stream emits `RUN_FINISHED` with `outcome.type` `"interrupt"`, then `data: [DONE]`, then the response ends. The browser does not stay open. The approval id is base64url of `runId.toolCallId`, so it carries the durable Flow run id.
+
+```json
+{
+  "type": "RUN_FINISHED",
+  "threadId": "agent-run-1",
+  "runId": "agent-run-1",
+  "outcome": {
+    "type": "interrupt",
+    "interrupts": [
+      {
+        "id": "VjFTdEdYUjhfWjVqZEhpNkItbXlULmNhbGxfMQ",
+        "reason": "approval",
+        "payload": { "tool": "refund", "args": { "amount": 10 } }
+      }
+    ]
+  }
+}
+```
+
+`id` is base64url of `<durable Flow run id>.<tool call id>`. The example decodes to `V1StGXR8_Z5jdHi6B-myT.call_1`. `V1StGXR8_Z5jdHi6B-myT` is the journal run id, not `agent-run-1`. `runId` on the frame is the agent stream id.
+
+Show `payload.tool` and `payload.args`. Keep `id`. That id is the only handle for the decision.
+
+Resolve it from a Flow, or from the built-in routes. The routes are public so the request can arrive. The tool's gate is checked on the call. A denying gate is 403. A missing id, or a tenant that does not match the park, is 404.
+
+```typescript
+await fx.agent.approve(id, { args: { amount: 4 } });
+await fx.agent.deny(id, { reason: "over the limit" });
+```
+
+```bash
+curl -X POST http://localhost:6530/agent/approvals/approve \
+  -H "content-type: application/json" \
+  -d '{"id":"VjFTdEdYUjhfWjVqZEhpNkItbXlULmNhbGxfMQ","args":{"amount":4}}'
+```
+
+```bash
+curl -X POST http://localhost:6530/agent/approvals/deny \
+  -H "content-type: application/json" \
+  -d '{"id":"VjFTdEdYUjhfWjVqZEhpNkItbXlULmNhbGxfMQ","reason":"over the limit"}'
+```
+
+`args` replaces the tool input. `reason` is what the model sees after a deny. The first decision wins. The default wait is `24h`, then the tool is denied with reason `timeout`.
+
+| Outcome          | HTTP                                                                                                                     | What you do                  |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
+| `{ ok: true }`   | 200 `{ "data": { "ok": true }, "error": null }`                                                                          | The journal sleep wakes now. |
+| Already resolved | 409 `Conflict`. No `Retry-After`. Message: `That value is already in use.`                                               | Stop. Do not retry.          |
+| Lease held       | 409 `JournalLeaseBusy` with `Retry-After`. Message: `This run is locked by another worker. Retry after the given delay.` | Retry after the delay.       |
+
+Approving or denying does not continue this SSE response. Follow the run to see the rest.
+
+## Follow a run
+
+`GET /agent/runs/:runId/events` is `text/event-stream`. Each frame has an `id`. Send that id as `Last-Event-ID` to resume without gaps or duplicates. The route checks the same gate and tenant as the Flow that started the run. Another tenant, or a gate that denies the caller, is rejected.
+
+An approval interrupt does not end this follow. The stream stays open through the interrupt and continues to the terminal `RUN_FINISHED`. The first run stream still closes after the interrupt. Disconnect, then resume with the last id you received.
+
+The run stream yields every token. The follow log coalesces text and argument deltas (about every 100 ms or 1 KB, including a timer) and stores structural events one by one. The instance that holds the journal lease is the only writer. It reads the highest seq before it appends, and a repeated seq is an error. Followers read `seq` greater than the last id, not the whole run.
+
+The log keeps 5,000 rows per run. Past that, deltas stop and one `CUSTOM` event named `oke.events.truncated` is stored. Structural events, approval interrupts, `RUN_FINISHED`, and `RUN_ERROR` are still stored. Earlier rows stay, so a follower can resume and seq numbers do not skip. A finished run's events are deleted after 24 hours. An unfinished run older than 7 days is closed with `RUN_ERROR` and deleted. The scheduler reads the store, not the process that opened the run. One instance claims the journal lease before it closes that run. The log is stored on the journal driver and keyed by the agent run id. `flow.retry` keeps that id. A follower must be the starting principal or an operator, and must pass every gate on the Flow.
+
+The file journal is single-process. It is not for large logs. Use the Postgres journal driver in production.
+
+A stored row on the live run stream carries `id:` set to that row's seq. Resume with `Last-Event-ID` so text you already showed is not sent again.
+
+```typescript
+import { approve, deny, readAgentEvents } from "okengine/client/agent";
+
+for await (const event of readAgentEvents(`http://localhost:6530/agent/runs/${runId}/events`)) {
+  if (event.type === "RUN_FINISHED" && event.outcome?.type === "interrupt") {
+    await approve("http://localhost:6530/agent/approvals/approve", event.outcome.interrupts[0]!.id);
+  }
+}
+```
+
+`approve` and `deny` retry `JournalLeaseBusy` and throw `Conflict` when the decision is already stored. `useAgentRun` from `okengine/client-react` sends the message, keeps the text so far, and follows once after an interrupt. Approve and deny do not open a second follow.
+
+## Patterns
+
+<Tabs items={["One message", "History", "Thread id", "Subagents"]}>
+
+<Tab value="One message">
+
+A string and `{ message }` are the same turn. Passing both throws `fx.run: pass message or messages, not both`.
+
+```typescript
+return fx.json.stream(fx.run(support, "Where is order 14?", { stream: true }));
+```
+
+</Tab>
+
+<Tab value="History">
+
+`messages` is the prior thread. Roles are `system`, `user`, `assistant`, and `tool`.
+
+```typescript
+return fx.json.stream(
+  fx.run(
+    support,
+    {
+      messages: [
+        { role: "user", content: "Where is order 14?" },
+        { role: "assistant", content: "Looking it up." },
+        { role: "user", content: "Refund it." },
+      ],
+    },
+    { stream: true },
+  ),
+);
+```
+
+</Tab>
+
+<Tab value="Thread id">
+
+Pass `threadId` when the chat already has one. The default is a unique id.
+
+```typescript
+return fx.json.stream(fx.run(support, { message }, { stream: true, threadId: chatId }));
+```
+
+`RUN_STARTED` and `RUN_FINISHED` both carry that `threadId`.
+
+`mock`, `anthropic`, and `openai-compatible` stream tokens and tool-call arguments. `bedrock` and `vertex` are reserved driver ids: boot throws before a call. `fx.stream` uses the same `stream` method, so it works on Anthropic too.
+
+</Tab>
+
+<Tab value="Subagents">
+
+A tool that names another agent emits `CUSTOM` on the parent stream. `okengine/client/agent` also returns typed names.
+
+| `CUSTOM.name`           | Parsed `type`       | `value`                      |
+| ----------------------- | ------------------- | ---------------------------- |
+| `oke.subagent.started`  | `subagent.started`  | `runId`, `parentToolCallId?` |
+| `oke.subagent.finished` | `subagent.finished` | `runId`, `parentToolCallId?` |
+| `oke.subagent.error`    | `subagent.error`    | `runId`, `parentToolCallId?` |
+
+Any other `CUSTOM` name stays `CUSTOM`. Nesting stops at `maxDepth` (default 3).
+
+</Tab>
+
+</Tabs>
+
+## Text stream or event stream
+
+| Call                                                     | What each SSE `data:` frame is                 |
+| -------------------------------------------------------- | ---------------------------------------------- |
+| `fx.json.stream(fx.stream(model, { prompt }))`           | A JSON string of plain text (`"Hel"`, `"lo"`). |
+| `fx.json.stream(fx.run(agent, input, { stream: true }))` | One AG-UI event object.                        |
+
+`fx.stream` is the model text iterator. `fx.json.stream` is the SSE carrier. Agent UIs use the second row.
+
+## Abort and stop reasons
+
+Disconnecting the HTTP client aborts the in-flight model call. The run records `stopReason` `aborted`. If the frame is still written, it is `RUN_ERROR` with `code` `AbortError`. `message` may be the provider's abort text, not only `aborted`.
+
+`result.stopReason` on a normal `RUN_FINISHED`:
+
+| `stopReason` | Meaning                                                                                    |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| `completed`  | The model stopped calling tools. A gate denial fed back to the model stays `completed`.    |
+| `max_steps`  | The loop hit `maxSteps` (default 6).                                                       |
+| `budget`     | Spend reached `budget.maxCostPerRun`. The trail so far is the output. This does not throw. |
+
+`denied` (unknown tool) and `aborted` arrive as `RUN_ERROR`, not as `result.stopReason`. A thrown tool ends with `RUN_FINISHED` and `result.stopReason` `"error"`, then `data: [DONE]`. The same close follows an approval interrupt: the final frame, then `[DONE]`, then the body ends.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='ai: flow "support.assist" must set durable: true to run agent "support"'>
+  The tool has `approval`, and the Flow is not durable. The message names that Flow: `ai: flow
+  "support.assist" must set durable: true to run agent "support"`. Set `durable: true`. A false
+  `approval` predicate does not park.
+</Accordion>
+
+<Accordion title='RUN_ERROR: ai: model requested unknown tool "refund"'>
+  The model called a tool that is not on `ai.agent({tools})`. `code` is `AgentLoopHalt`. Add the
+  Flow name to `tools`, or stop offering it in the prompt.
+</Accordion>
+
+<Accordion title="RUN_FINISHED stopReason is budget">
+  `result.stopReason` is `budget` and `result.cost` is the spend so far. Raise
+  `budget.maxCostPerRun`, or treat the partial `output` as the reply. A prompt's `maxCostPerCall` is
+  different: `fx.ask` throws `ai: prompt "…" exceeded maxCostPerCall …` (`AiBudgetExceededError`).
+</Accordion>
+
+<Accordion title="The client disconnected">
+  The model call aborts. You may see `RUN_ERROR` with message `aborted` and code `AbortError`, or
+  only a closed socket. The recorded `stopReason` is `aborted`.
+</Accordion>
+
+<Accordion title="A frame is not one of the core types">
+  `readAgentEvents` yields `CUSTOM` unchanged when `name` is not `oke.subagent.started`,
+  `oke.subagent.finished`, or `oke.subagent.error`. Those three become `subagent.started`,
+  `subagent.finished`, and `subagent.error`. An object with no `type` is skipped. `data: [DONE]` is
+  skipped. The iterator ends when the body ends, not because of that line.
+</Accordion>
+
+<Accordion title="Conflict or JournalLeaseBusy">
+  A second approve or deny after the decision is stored is `Conflict`. Do not retry it. A lost race
+  while another worker holds the run is `JournalLeaseBusy` with `Retry-After`. Retry only that code.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Agents](/docs/elements/ai/agents) — `fx.run`, tools, `maxSteps`, and approval
+- [Prompts](/docs/elements/ai/prompts) — tool-less `fx.ask` still throws on `maxCostPerCall`
+- [MCP](/docs/elements/ai/mcp) — external tools in the same loop
+
+## Next
+
+<Cards>
+  <Card
+    title="Agents"
+    description="Bounded tool loops with fx.run."
+    href="/docs/elements/ai/agents"
+  />
+  <Card
+    title="Decisions"
+    description="One calibrated choice, with a person when it cannot auto."
+    href="/docs/elements/ai/decide"
+  />
+  <Card title="AI" description="Models, prompts, agents, and decisions." href="/docs/elements/ai" />
+</Cards>

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

@@ -279,6 +279,11 @@ Compose does not pin inference — BYO URL + keys, or [OpenRouter](/docs/recipes
 
 <Accordions>
 
+<Accordion title="The same input called the model again">
+  Outside a durable Flow, `fx.ask` always reaches the model. Replay lives only on that run's
+  journal.
+</Accordion>
+
 <Accordion title='ai: unknown prompt "…"'>
   `fx.ask` named a prompt that was never minted with `model.prompt`, or the declaring module was not
   imported before `oke()`.
@@ -295,8 +300,8 @@ Compose does not pin inference — BYO URL + keys, or [OpenRouter](/docs/recipes
 </Accordion>
 
 <Accordion title="AiBudgetExceededError">
-  Cause: `ai: prompt "…" exceeded maxCostPerCall N` or `ai: agent "…" exceeded maxCostPerRun N`.
-  Raise the budget or shrink the work.
+  Cause: `ai: prompt "…" exceeded maxCostPerCall N`. A tool-less `fx.ask` throws
+  `AiBudgetExceededError`. `fx.run` returns the partial result when the agent budget is spent.
 </Accordion>
 
 <Accordion title="build failed: … without allowPii">
@@ -316,9 +321,10 @@ Compose does not pin inference — BYO URL + keys, or [OpenRouter](/docs/recipes
 - [Models](/docs/elements/ai/models) — provider registry and `baseUrl` rules
 - [Prompts](/docs/elements/ai/prompts) — `via`, budgets, versions, evals
 - [Agents](/docs/elements/ai/agents) — `fx.run`, tools, `maxSteps`
+- [Decisions](/docs/elements/ai/decide) — `fx.decide`, `how`, and the lockfile
 - [MCP](/docs/elements/ai/mcp) — inbound `mcp.tool` and outbound `ai.mcpServer`
 - [OpenRouter](/docs/recipes/openrouter) — zero-Docker cloud path
-- [fx](/docs/reference/fx) — `fx.ask` / `fx.run` / `fx.embed`
+- [fx](/docs/reference/fx) — `fx.ask` / `fx.run` / `fx.decide` / `fx.embed`
 - [Errors](/docs/reference/errors) — OKE1005 · OKE1009
 
 ## Next

package/site/content/docs/elements/ai/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "AI",
   "icon": "Sparkles",
-  "pages": ["index", "models", "prompts", "agents", "mcp"]
+  "pages": ["index", "models", "prompts", "agents", "decide", "events", "mcp"]
 }

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

@@ -128,8 +128,9 @@ smart.prompt("ticket-triage", {
 });
 ```
 
-`maxCostPerRun` on a prompt budget is reserved for multi-step asks; agents use
-`budget.maxCostPerRun` on `ai.agent`.
+A tool-less ask still throws `AiBudgetExceededError` at `maxCostPerCall`. An agent run
+returns the partial result when `budget.maxCostPerRun` is spent. `repair: 1` sends one
+follow-up of the original messages plus the mismatch; it counts toward the cap and is its own journal entry.
 
 </Tab>
 
@@ -161,6 +162,7 @@ Default `maxSteps` is `6`. Tool names also stamp `effects.calls`.
 | `version` | `number`                              | —                | Pin with `fx.ask("name@N")`                                     |
 | `evals`   | `string`                              | —                | Path for `oke eval` JSONL                                       |
 | `budget`  | `{ maxCostPerCall?, maxCostPerRun? }` | —                | Cost contracts                                                  |
+| `repair`  | `0` \| `1`                            | `0`              | One schema-mismatch follow-up; counts toward `maxCostPerCall`   |
 | `via`     | `string[]`                            | `[parent model]` | Recovery chain of logical names                                 |
 | `timeout` | `"30s"` \| ms                         | —                | Ask deadline (not a cost budget)                                |
 | `in`      | Schema                                | —                | Declared / Manifest / doctor — **not** runtime-validated on ask |

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

@@ -247,7 +247,7 @@ overrides). Manifest stays free of copy.
 | Method                     | Capability / `sends` | Meaning                                     |
 | -------------------------- | -------------------- | ------------------------------------------- |
 | `fx.send(template, opts?)` | template name        | Deliver through the medium’s driver chain   |
-| `fx.sendOtp(opts)`         | `"sms-otp"`          | Provider-managed SMS OTP (Taqnyat Verify)   |
+| `fx.sendOtp(opts)`         | `"sms-otp"`          | Provider-managed SMS OTP.                   |
 | `fx.verifyOtp(opts)`       | `"sms-otp"`          | Check a provider OTP code                   |
 | `fx.deliverOtp(opts)`      | `"auth-otp"`         | App-owned OTP across email / SMS / WhatsApp |
 
@@ -351,9 +351,9 @@ Env knobs: [Environment variables](/docs/reference/environment-variables). Local
 </Accordion>
 
 <Accordion title="Process-local suppression / receipts warning">
-  Boot warns: `Channel suppression/consent/receipts default to process-local memory…` Opt-out on one
-  instance is invisible to others until you inject shared stores or run a single Channel consumer.
-  See [Receipts](/docs/elements/channel/receipts).
+  Boot warns: `Channel suppression/consent/receipts default to process-local memory…` That is
+  `test`, or a boot with no `DATABASE_URL`. Otherwise consent, suppression, and receipts are the
+  Postgres ledger. See [Receipts](/docs/elements/channel/receipts).
 </Accordion>
 
 </Accordions>

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

@@ -1,21 +1,23 @@
 ---
 title: "Receipts"
-description: "Delivery ledger, seven-state outcomes, consent opt-out, and hard-bounce suppression — process-local by default."
+description: "Delivery ledger, seven-state outcomes, consent opt-out, and hard-bounce suppression."
 icon: "ReceiptText"
 source: "docs/spec/unified-theory.md"
 ---
 
 Every Channel send records a **receipt** — success (`sent` / `fallback`), suppression, or a
 classified failure. Provider bounces and complaints update that ledger through normalized
-outcomes. There is no `oke_receipts` SQL table and no `fx.channel.getReceipt` helper.
+outcomes. There is no `fx.channel.getReceipt` helper. Outside `test`, boot stores consent,
+suppression, and receipts in Postgres (`oke_channel_consent`, `oke_channel_bounce`,
+`oke_channel_receipt`) when `DATABASE_URL` is set. `test` stays in memory.
 
 For operators watching deliverability — Console projects the ledger; Flows only see send
 results via `fx.send`’s `{ ok: true }` gate.
 
 <Callout title="The one rule">
-  Consent and prior hard bounces suppress **before** any driver runs. Default suppression / consent
-  / receipts stores are **process-local memory** — inject shared stores for multi-instance, or run a
-  single Channel consumer, until a durable driver ships.
+  Consent and prior hard bounces suppress **before** any driver runs. With `DATABASE_URL` outside
+  `test`, those rows are shared across instances. `test`, and any boot without a SQL URL, keep
+  process-local memory and still warn.
 </Callout>
 
 ## Smallest Example

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

@@ -7,7 +7,8 @@ source: "docs/spec/unified-theory.md"
 
 SMS (`channel.sms`) delivers short text and provider-managed one-time codes. Pin an SMS driver
 (no default in any env), declare templates for app-owned messages, or call `fx.sendOtp` when the
-vendor owns the code.
+vendor owns the code. `fx.sendOtp` and `fx.verifyOtp` stay on `fx`. The `mena` plugin opens the
+same providers when you want that packaging.
 
 For developers verifying phones — choose raw Channel OTP vs the [`otp`](/docs/plugins/otp) plugin.
 

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

@@ -220,17 +220,17 @@ Second argument to `flow(name, options)` — or the only argument to a nameless
 Invoke contracts (`in` / `out` / `errors` / `breaking`) belong on the exposure — see
 [Contracts](#contracts) below.
 
-| Option         | Type                                   | Default                   | Meaning                                                                         |
-| -------------- | -------------------------------------- | ------------------------- | ------------------------------------------------------------------------------- |
-| `do`           | `(input, fx) => output \| FlowFailure` | _(required)_              | Handler. Missing `do` throws `flow() expected an options bag with a do handler` |
-| `durable`      | `boolean`                              | `false`                   | Journal `fx.step` / sleep / gated `fx` calls                                    |
-| `retry`        | `FxRetryOptions`                       | omitted                   | Whole-`do` retry on throw (same journal when durable)                           |
-| `cache`        | `boolean \| string`                    | omitted (auto)            | Read-only Flows cache automatically; `false` opts out; `"30s"` adds TTL         |
-| `compensate`   | `(ctx, fx) => unknown`                 | omitted                   | After LIFO `{ undo }`, before the run commits `failed`                          |
-| `plane`        | `"user" \| "operator"`                 | `"user"`                  | Operator bypasses RLS; user must not `fx.call` operator                         |
-| `effects`      | `Effects`                              | inferred                  | Capability token — write this only when inference cannot see the body           |
-| `slo`          | `{ availability?, latency? }`          | omitted                   | Manifest metadata (Console / docs)                                              |
-| `tenantScoped` | `boolean`                              | `true` when tenancy is on | `false` skips tenant-role scope union                                           |
+| Option         | Type                                   | Default                   | Meaning                                                                                                          |
+| -------------- | -------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `do`           | `(input, fx) => output \| FlowFailure` | _(required)_              | Handler. Missing `do` throws `flow() expected an options bag with a do handler`                                  |
+| `durable`      | `boolean`                              | `false`                   | Journal `fx.step` / sleep / gated `fx` calls                                                                     |
+| `retry`        | `FxRetryOptions`                       | omitted                   | Whole-`do` retry on throw (same journal when durable)                                                            |
+| `cache`        | `boolean \| string`                    | omitted (on when pure)    | Pure store reads cache; `false` disables; `"30s"` sets a TTL; app `cache: { auto: false }` turns the default off |
+| `compensate`   | `(ctx, fx) => unknown`                 | omitted                   | After LIFO `{ undo }`, before the run commits `failed`                                                           |
+| `plane`        | `"user" \| "operator"`                 | `"user"`                  | Operator bypasses RLS; user must not `fx.call` operator                                                          |
+| `effects`      | `Effects`                              | inferred                  | Capability token — write this only when inference cannot see the body                                            |
+| `slo`          | `{ availability?, latency? }`          | omitted                   | Manifest metadata (Console / docs)                                                                               |
+| `tenantScoped` | `boolean`                              | `true` when tenancy is on | `false` skips tenant-role scope union                                                                            |
 
 **Consequence:** `durable: true` disables automatic read-cache for that Flow.
 
@@ -438,12 +438,12 @@ durable Flow, or split with `fx.emit`. See [Workflows](/docs/elements/flow/workf
 
 <Tab value="Cache">
 
-Read-only Flows (Store `reads`, no `writes`, no `asks`, not durable) cache automatically.
-No `cache:` option required. Mutations and `durable: true` stay uncached:
+A pure store-read Flow caches on its own. A send, emit, fetch, vault read, ask,
+decide, or `fx.call` is never cached. The key includes the flow, the input, the
+user, the tenant, the locale, and the caller's scopes and membership roles.
 
 ```typescript
 flow("catalog.get", {
-  cache: "30s",
   do: async ({ id }, fx) => {
     const [row] = await fx.store(db).select().from(products).where(eq(products.id, id));
     return row;
@@ -451,7 +451,10 @@ flow("catalog.get", {
 });
 ```
 
-`cache: false` opts out. A duration string adds TTL on top of write invalidation.
+`cache: false` always disables. A duration string adds TTL on top of write
+invalidation. `oke({ cache: { auto: false } })` turns the default off; a Flow
+can still set `cache: true` or `"30s"`. Cross-instance invalidation and writes
+that skip `fx` are not covered.
 
 </Tab>
 
@@ -570,9 +573,10 @@ Default is `true` once `gate.auth.tenant` is on.
 </Accordion>
 
 <Accordion title="Read-only Flow never cache-hits">
-  Auto-cache needs Store `reads`, no `writes`, no `asks`, and `durable` off. Empty effect sets stay
-  uncached. Opt in with a duration (`cache: "30s"`) only after a real read is inferred — or pass
-  `cache: false` to disable.
+  A pure Store read caches unless the Flow sets `cache: false` or the app sets
+  `cache: { auto: false }`. A send, emit, fetch, secret, ask, decide, call, or write
+  is never cached, and `durable: true` is never cached. The key includes tenant,
+  locale, scopes, and roles, so a hit for one caller is a miss for another.
 </Accordion>
 
 <Accordion title='cross-plane call: user flow "…" calls operator flow "…"'>

package/site/content/docs/elements/gate/auth.mdx

@@ -103,8 +103,11 @@ export const app = oke({
 });
 ```
 
-In production, set `gate.auth.secret` (or `OKE_AUTH_SECRET`). Omitting it in `prod` throws:
+In production, set `gate.auth.secret` (or `OKE_AUTH_SECRET`). Omitting both in `prod` throws:
 `gate.auth: secret is required in production (set gate.auth.secret or OKE_AUTH_SECRET)`.
+When `gate.auth.secret` is omitted, the process uses `OKE_AUTH_SECRET`. `oke dev` writes one
+value into `.env.local` and passes it to Console and the app, so a Bearer API key created
+in Console verifies on the app.
 
 Forged, expired, or revoked access tokens map to typed `Unauthorized` — they never become a
 principal.

package/site/content/docs/elements/signal/index.mdx

@@ -331,11 +331,11 @@ Omit `key` for a pure competing pool with no ordering.
 Protocol ids: `memory` · `redis` · `postgres` · `nats`. Defaults (when `oke.config.ts` omits
 `drivers.signal`):
 
-| Env    | Default  | Boot today                                                              |
-| ------ | -------- | ----------------------------------------------------------------------- |
-| `dev`  | `redis`  | Emit relays to Redis; consume / live / drain use a process-local outbox |
-| `test` | `memory` | In-process bus                                                          |
-| `prod` | `redis`  | Same redis honesty as `dev`                                             |
+| Env    | Default  | Boot today                                                                       |
+| ------ | -------- | -------------------------------------------------------------------------------- |
+| `dev`  | `redis`  | Emit relays to Redis. `once` consume is a consumer group (`XREADGROUP` / `XACK`) |
+| `test` | `memory` | In-process bus                                                                   |
+| `prod` | `redis`  | Same redis path as `dev`                                                         |
 
 ```typescript title="oke.config.ts"
 export default defineConfig({
@@ -345,8 +345,10 @@ export default defineConfig({
 });
 ```
 
-`postgres` and `nats` fail loud at boot until a native bind ships — never silently fall back to
-`memory`. Prefer `memory` for tests; pin `redis` when Compose provides Redis.
+`postgres` binds Bun.SQL and the scheduler polls `drain` (`FOR UPDATE SKIP LOCKED`). Bun.SQL has no
+`LISTEN` / `NOTIFY`. `nats` still fails loud at boot — never silently fall back to `memory`. Prefer
+`memory` for tests; pin `redis` when Compose provides Redis. Live history stays on the emitting
+process; `once` is the competing path.
 
 ## Troubleshooting
 
@@ -383,15 +385,14 @@ export default defineConfig({
   consumers](#competing-consumers-once-vs-broadcast).
 </Accordion>
 
-<Accordion title='oke boot: signal driver "postgres" / "nats"'>
-  Those ids are reserved but not bound for production yet. Use `"memory"` or `"redis"`, or inject a
-  custom `elements.signal` runtime.
+<Accordion title='oke boot: signal driver "postgres" needs DATABASE_URL'>
+  `drivers.signal` is `postgres` and neither `DATABASE_URL` nor `OKE_STORE_SQL_URL` is set. Boot
+  polls `drain` on that connection. There is no `LISTEN` / `NOTIFY` requirement.
 </Accordion>
 
-<Accordion title="redis Signal — process-local consume">
-  Boot warns that redis emit relays to Redis while consume / live / drain stay process-local.
-  Multi-instance competing consumers need a shared durable outbox path (or a single consumer
-  instance) until Redis Streams consume ships.
+<Accordion title='oke boot: signal driver "nats"'>
+  `nats` has no production client yet. Use `"memory"`, `"redis"`, or `"postgres"`, or inject a
+  custom `elements.signal` runtime.
 </Accordion>
 
 </Accordions>