okengine 0.21.1 → 0.23.0

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/email.mdx

@@ -178,7 +178,7 @@ drivers: {
   },
 },
 images: {
-  channel: { email: "axllent/mailpit:v1.31.1" },
+  channel: { email: "axllent/mailpit:v1.31.2" },
 },
 ```
 

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

@@ -281,7 +281,7 @@ export default defineConfig({
     },
   },
   images: {
-    channel: { email: "axllent/mailpit:v1.31.1" },
+    channel: { email: "axllent/mailpit:v1.31.2" },
   },
 });
 ```

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

@@ -58,7 +58,7 @@ Response:
 <Callout title="Omit path and name">
   Tree default: `http.get()` and `flow({ do })` — no path or name strings. The
   file stamps both. Pass either only for
-  [control](/docs/elements/flow/routing#when-to-omit--when-to-pass).
+  [control](/docs/understand/routing#when-to-omit--when-to-pass).
 </Callout>
 
 ## Progressive Patterns
@@ -180,7 +180,7 @@ export const deleteAccount = on(
 ## Path Conventions
 
 **Default — omit the path.** Tree files stamp the URL from disk (`http.get()`).
-Pass a path only for [control](/docs/elements/flow/routing#when-to-omit--when-to-pass).
+Pass a path only for [control](/docs/understand/routing#when-to-omit--when-to-pass).
 
 **Control — explicit path** — pass the URL template when the folder should not own the route:
 
@@ -197,7 +197,7 @@ import { on, flow, http } from "okengine";
 export const get = on(http.get(), flow({ do: async ({ id }) => ({ id }) }));
 ```
 
-Full file-tree rules: [Routing](/docs/elements/flow/routing).
+Full file-tree rules: [Routing](/docs/understand/routing).
 
 ## Request Parsing
 
@@ -268,7 +268,7 @@ export const create = on(
 ## HTTP Methods
 
 Each verb binds with `on(http.<method>(), flow({…}))`. Omit the path on tree
-files; pass one only for [control](/docs/elements/flow/routing#when-to-omit--when-to-pass).
+files; pass one only for [control](/docs/understand/routing#when-to-omit--when-to-pass).
 
 <Tabs items={["GET", "POST", "PUT", "PATCH", "DELETE", "QUERY", "HEAD", "OPTIONS"]}>
 

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

@@ -61,7 +61,7 @@ Response:
 <Callout title="Omit path and name">
   Tree default: `http.get()` + `flow({ do })` — no path or name strings. Pass
   either only for
-  [control](/docs/elements/flow/routing#when-to-omit--when-to-pass).
+  [control](/docs/understand/routing#when-to-omit--when-to-pass).
 </Callout>
 
 <Callout title="Call-only Flows">
@@ -200,7 +200,7 @@ const { chargeId } = await fx.call(chargeCard, { amount: 50 });
   <Card
     title="Routing"
     description="File-tree stamps for HTTP paths, Flow names, and client units."
-    href="/docs/elements/flow/routing"
+    href="/docs/understand/routing"
   />
   <Card
     title="Consumers"
@@ -592,7 +592,7 @@ Default is `true` once `gate.auth.tenant` is on.
 
 - [The Architecture](/docs/understand/the-architecture) — `on`, trigger, `flow`, `do`, `fx`
 - [HTTP](/docs/elements/flow/http) — verbs, envelopes, resources, live SSE
-- [Routing](/docs/elements/flow/routing) — file-tree stamps, barrels, OKE1030 · OKE1040–1045
+- [Routing](/docs/understand/routing) — file-tree stamps, barrels, OKE1030 · OKE1040–1045
 - [Consumers](/docs/elements/flow/consumers) — Signal / Clock / CDC
 - [Workflows](/docs/elements/flow/workflows) — `durable: true` + `fx.step`
 - [fx](/docs/reference/fx) — every method inside `do`

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

@@ -1,5 +1,5 @@
 {
   "title": "Flow",
   "icon": "Workflow",
-  "pages": ["index", "http", "routing", "consumers", "workflows"]
+  "pages": ["index", "http", "consumers", "workflows"]
 }

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/gate/tenancy.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Tenancy"
 description: "Opt into gate.auth.tenant so requests resolve fx.tenant.id from claim, header, or subdomain."
-icon: "Building2"
+icon: "Building"
 source: "docs/spec/unified-theory.md"
 ---
 

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

@@ -226,7 +226,7 @@ export default defineConfig({
   images: {
     store: {
       sql: "postgres:18-alpine",
-      kv: "redis:8-alpine",
+      kv: "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
       files: "rustfs/rustfs:1.0.0",
     },
   },

package/site/content/docs/elements/store/kv.mdx

@@ -544,11 +544,11 @@ writes (`set` · `delete`). Declare the same refs when you hand-write
 
 ## Drivers
 
-| Driver                                       | Runs as                          | Best for                           |
-| -------------------------------------------- | -------------------------------- | ---------------------------------- |
-| `redis`                                      | Docker Redis / Valkey-compatible | Dev + prod default                 |
-| `memory`                                     | Process map                      | Test default                       |
-| Durable (`postgres` / `pglite` via `oke_kv`) | Shared SQL URL                   | Namespaces that must outlive Redis |
+| Driver                                       | Runs as                           | Best for                           |
+| -------------------------------------------- | --------------------------------- | ---------------------------------- |
+| `redis`                                      | Dragonfly by default (Redis-wire) | Dev + prod default                 |
+| `memory`                                     | Process map                       | Test default                       |
+| Durable (`postgres` / `pglite` via `oke_kv`) | Shared SQL URL                    | Namespaces that must outlive Redis |
 
 Defaults: `redis` / `memory` / `redis` (dev / test / prod). Pin overrides in
 `oke.config.ts`; image pins stay under `images.store.kv` — the driver id stays

package/site/content/docs/elements/vault/rotation.mdx

@@ -209,10 +209,25 @@ Builtin encrypted store:
 
 `--url` overrides the SQL URL (`DATABASE_URL` / `OKE_STORE_SQL_URL`).
 
+## Audit sinks
+
+| `vault.audit.sink` | Recorded as                       | `oke vault audit`   |
+| ------------------ | --------------------------------- | ------------------- |
+| `db` (default)     | SQL hash chain                    | list, verify, purge |
+| `stdout`           | One secret-free JSON line         | Refused             |
+| `webhook`          | POST of that JSON to `webhookUrl` | Refused             |
+
+`webhookUrl` must be an absolute `http:` or `https:` URL. The POST uses `redirect: "error"` and a 5 second timeout. A failed delivery does not undo the vault write. `audit.enabled: false` records nothing. The body never contains a secret value.
+
 ## Troubleshooting
 
 <Accordions>
 
+<Accordion title="audit verify requires audit.sink db">
+  `stdout` and `webhook` sinks are not a local hash chain. `oke vault audit` (list, verify, purge)
+  throws `UNSUPPORTED`. Use `sink: "db"` when you need `verify`.
+</Accordion>
+
 <Accordion title="oke vault: no such secret">
   Rotate/get targeted a path that was never set. `oke vault list` (or Console) for live paths;
   remember per-tenant storage uses `{tenantId}/{name}`.