okengine 0.22.0 → 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/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/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/recipes/dragonfly.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Dragonfly"
-description: "Multi-threaded Redis-wire runtime — OKE_STORE_KV_PASSWORD, memlock ulimit, no maxmemory-policy flag."
+description: "Default store.kv image — multi-threaded Redis-wire runtime, memlock ulimit, OKE_STORE_KV_PASSWORD."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Dragonfly is a multi-threaded, memory-efficient reimplementation of the Redis protocol —
-same `redis://` wire format, different engine. Slots behind the same `redis` driver with
-zero Flow changes.
+Dragonfly is the default `store.kv` image in `dev` and `prod`: a multi-threaded Redis-protocol engine.
+Same `redis://` wire format and the same `redis` driver, so Flows do not change.
+Pin Redis or Valkey when you want those engines instead.
 
 <Callout title="The one rule">
   Driver id stays `redis`. Dragonfly is an image choice — every KV call through `fx.store` behaves
@@ -23,7 +23,7 @@ zero Flow changes.
 
 ```typescript title="oke.config.ts"
 images: {
-  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly",
+  "store.kv": "docker.dragonflydb.io/dragonflydb/dragonfly:v2.0.0",
 },
 ```
 

package/site/content/docs/recipes/index.mdx

@@ -51,15 +51,15 @@ Driver id stays `redis` for every image below.
 
 <Cards>
   <Card
-    title="Redis"
-    description="Default store.kv — requirepass + maxmemory."
-    href="/docs/recipes/redis"
+    title="Dragonfly"
+    description="Default store.kv — multi-threaded Redis-wire runtime."
+    href="/docs/recipes/dragonfly"
   />
   <Card title="Valkey" description="BSD-licensed Redis-wire fork." href="/docs/recipes/valkey" />
   <Card
-    title="Dragonfly"
-    description="Multi-threaded Redis-wire runtime."
-    href="/docs/recipes/dragonfly"
+    title="Redis"
+    description="Opt-in Redis Open Source — requirepass + maxmemory."
+    href="/docs/recipes/redis"
   />
 </Cards>
 

package/site/content/docs/recipes/postgres.mdx

@@ -106,11 +106,11 @@ Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exha
   Recreate `store-sql` after a recipe change — the data volume can stay.
 </Callout>
 
-| Step    | What you do                                                       |
-| ------- | ----------------------------------------------------------------- |
-| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements` |
-| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements`               |
-| Console | Store → SQL band → **Performance**                                |
+| Step    | What you do                                                            |
+| ------- | ---------------------------------------------------------------------- |
+| Preload | Recipe already sets `shared_preload_libraries=pg_stat_statements`      |
+| Create  | `oke db push` runs `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Console | Store → SQL band → **Performance**                                     |
 
 Default `postgres:18-alpine` does **not** ship `hypopg` / `index_advisor`. Pin the
 opt-in image when you want Suggest indexes:
@@ -137,8 +137,8 @@ set. Re-run `oke dev` so the stack writes `.env.local`, or export
 <Accordion title="PgStatStatementsNotPreloaded">
 
 The Console Performance view needs the library preloaded **and** the extension
-created. Recreate `store-sql` so the new `command` applies, then run
-`CREATE EXTENSION IF NOT EXISTS pg_stat_statements`.
+created. Recreate `store-sql` so the new `command` applies, then run `oke db push`
+(or open Performance again — it creates the extension when preload is already on).
 
 Existing clusters that started before this recipe change keep the old
 postmaster flags until recreate.
@@ -167,5 +167,9 @@ Postgres refusing auth.
 <Cards>
   <Card title="PgDog" description="Add pooling in front of Postgres." href="/docs/recipes/pgdog" />
   <Card title="Neon" description="A managed alternative." href="/docs/providers/neon" />
-  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
+  <Card
+    title="Dragonfly"
+    description="The default store.kv image."
+    href="/docs/recipes/dragonfly"
+  />
 </Cards>

package/site/content/docs/recipes/redis.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Redis"
-description: "Default store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
+description: "Opt-in store.kv image — OKE_STORE_KV_PASSWORD, maxmemory policy, ephemeral data, REDIS_URL."
 icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Redis is the default `store.kv` image in `dev` and `prod`. `oke docker` matches image
-references containing `redis` or `keydb` and derives a password-required server — no
-unauthenticated instance.
+Redis is an opt-in `store.kv` image. The default pin is [Dragonfly](/docs/recipes/dragonfly).
+`oke docker` matches image references containing `redis` or `keydb` and derives a
+password-required server — no unauthenticated instance.
 
 <Callout title="The one rule">
   The driver id stays `redis` for every Redis-wire image — Redis, Valkey, Dragonfly, or a managed

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

@@ -134,7 +134,8 @@ Override app / console / mcp listen ports in `oke.config.ts` `ports` — see
 | `docker`     | Derive compose · clean leftover stacks                       | `--prod\|-p`, `--out`, `--config`, `--manifest`; sub `clean`                                                                                              |
 | `images`     | List / pin digests                                           | `list` · `pin`                                                                                                                                            |
 | `build`      | Tree-shaken bundle                                           | `--target\|-t bun\|node\|edge`, `--entry`, `--outdir`                                                                                                     |
-| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`                                                                                                                                              |
+| `eval`       | Prompt eval sets (CI gate)                                   | `--manifest`, `--certify` (decision seed certificate; prompt evals stay as they are)                                                                      |
+| `decide`     | Write a decision lockfile from the operator candidate        | `promote <name>` (`--origin`, `--lock`)                                                                                                                   |
 | `ai`         | Configure AI driver + models                                 | `setup` (`--provider`, `--chat`, `--vision`, `--embed`, `--yes`)                                                                                          |
 | `branch`     | Fork journaled state                                         | `<name>`, `--at\|-a`                                                                                                                                      |
 | `replay`     | Re-invoke a past Flow from Runs                              | `--request-id\|-r`, `--entry`, `--dry-run`, `--live`                                                                                                      |

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

@@ -136,11 +136,13 @@ sql: {
 },
 ```
 
-| Field      | Type              | Meaning                                     |
-| ---------- | ----------------- | ------------------------------------------- |
-| `url`      | connection string | Overrides the env-var resolution            |
-| `pool`     | `{ max?, min? }`  | SQL pool sizing                             |
-| `replicas` | `string[]`        | Read-only routing targets (read flows only) |
+| Field      | Type              | Meaning                                                                           |
+| ---------- | ----------------- | --------------------------------------------------------------------------------- |
+| `url`      | connection string | Overrides the env-var resolution                                                  |
+| `pool`     | `{ max?, min? }`  | `max` is the Bun.SQL pool size. Unset keeps 8. `min` is accepted and not applied  |
+| `replicas` | `string[]`        | Read-only flows use these URLs. Each replica opens its own pool at the same `max` |
+
+A store `max` of 20 does not share a pool another part of the process already opened at 8. Writes stay on the primary.
 
 ## images
 
@@ -150,7 +152,7 @@ Nested pins by element role — vendor choice lives here, never in driver ids:
 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",
   },
   channel: { email: "axllent/mailpit:v1.31.2" },
@@ -161,7 +163,7 @@ images: {
 
 Omitted image keys mean no container for that role. When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog — see [Store](/docs/elements/store#multiple-environments).
 
-For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
+For `store.kv`, pin Dragonfly (default), Redis, or Valkey — driver id stays `redis`.
 `{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
 
 Compose does not manage AI inference — [OpenRouter](/docs/recipes/openrouter) or BYO