okengine 0.9.1 → 0.10.1

package/AGENTS.md

@@ -55,7 +55,7 @@ A direct `node:` import (or any other side-channel I/O) in element or flow code
 
 | Port     | Surface              |
 | -------- | -------------------- |
-| **6530** | App                  |
+| **6530** | Backend              |
 | **6533** | Console              |
 | **6535** | MCP                  |
 | **6536** | Docs MCP (read-only) |

package/manifest.v1.schema.json

@@ -139,7 +139,15 @@
       "properties": {
         "reads": {
           "type": "array",
-          "items": { "$ref": "#/$defs/ResourceRef" },
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/ResourceRef" },
+              {
+                "const": "runs",
+                "description": "Runs wide-event store via fx.runs (observability read)."
+              }
+            ]
+          },
           "uniqueItems": true
         },
         "writes": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -99,8 +99,8 @@
     "arktype": "^2.2.3",
     "axe-core": "^4.12.1",
     "clsx": "^2.1.1",
-    "drizzle-kit": "^1.0.0-rc.4",
-    "drizzle-orm": "^1.0.0-rc.4",
+    "drizzle-kit": "1.0.0-rc.4",
+    "drizzle-orm": "1.0.0-rc.4",
     "drizzle-seed": "^0.3.1",
     "drizzle-zod": "^0.8.3",
     "gflows": "^1.2.1",

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

@@ -18,6 +18,10 @@ Answers: **wide events — one record per flow execution, queried by dimension**
     title="Wide events"
     description="Dimensions from effects — no manual instrumentation tax."
   />
+  <Card
+    title="Error patterns"
+    description="Failed runs in the lookback window, grouped by error code."
+  />
   <Card
     title="Outlier explanation"
     description="Compare all dimensions between slow and baseline populations."
@@ -32,6 +36,12 @@ Answers: **wide events — one record per flow execution, queried by dimension**
   />
 </Cards>
 
+Use **Since** (`5m` · `1h` · `24h` · all time) to bound the population. Error patterns count
+`error_code` occurrences in that window — the same store Traces and Overview read.
+
+Local replay: `oke replay --request-id <runId>` re-invokes from the stored input snapshot
+(dry-run when the ledger has `send` / `ask`).
+
 ## Catalog
 
 <Cards>

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

@@ -26,6 +26,10 @@ Answers: **one timeline across http → store → signal → durable steps**
   />
 </Cards>
 
+Chains use `WideEvent.parentId`: producers stamp it on `fx.emit` / `fx.call`;
+consumers record it on their run. Per-effect timing comes from the ledger
+(`timestamp` + `duration`) — not a second instrumentation API.
+
 ## Catalog
 
 <Cards>

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

@@ -171,65 +171,87 @@ There is deliberately **no production default**: `prod` must name a driver, whic
 
 ```bash title="Terminal"
 oke ai setup
+oke ai setup --provider llama-cpp --yes
 oke ai setup --provider ollama --yes
 ```
 
-Writes `drivers.ai`, `.env.local`, and `src/ai.ts`.
+Writes `drivers.ai`, commented AI overrides in `.env.local` (so they do not
+shadow `docker/.env.docker`), and `src/core/ai.ts`. Uncomment `.env.local`
+lines only for a host-managed AI endpoint.
 
-Ollama: short quiz (use case · speed/quality · vision) → detect installed models
-→ picks that fit your **machine tier** (~4GB OS/IDE headroom). Labels say
-**≈16GB-class**, not “download 16GB” — pull size is usually much smaller than RAM.
+**Recommended** defaults to llama.cpp (lightest local footprint). Customize
+offers llama.cpp · Ollama · vLLM · SGLang · cloud providers.
 
-Cloud: short chat list + **Other…** for any model id. **← Back** returns a step.
-`create-oke` runs the same model wizard **before** install when you enable AI
-(customize or `--ai`). Standalone `oke ai setup` remains for existing apps.
+llama.cpp and Ollama: machine banner → model tier / manual (Docker Hub `ai/` vs
+Ollama library). Cloud: API token → model.
 
-### Local Ollama
+`create-oke` customize offers **AI setup** (Recommended llama.cpp · Customize ·
+Off) before install; `--ai` forces the full model wizard.
 
-`ollama` is a local-model driver — any pulled model works. Pin `drivers.ai`;
-optionally pin `images.ai` for compose. Native `complete`, `stream`, and
-`embed` (`POST /api/embeddings`) — no OpenAI shim required for local RAG.
+### Local inference (decision matrix)
+
+| Workload                         | Image recipe / driver                                      |
+| -------------------------------- | ---------------------------------------------------------- |
+| Single-user / dev (default)      | [llama.cpp](/docs/recipes/llama-cpp) + `openai-compatible` |
+| Local library UX                 | [Ollama](/docs/recipes/ollama) + `ollama`                  |
+| Multi-user GPU concurrency       | [vLLM](/docs/recipes/vllm) + `openai-compatible`           |
+| Structured / agent GPU workloads | [SGLang](/docs/recipes/sglang) + `openai-compatible`       |
+| Managed cloud                    | `anthropic` / `openai-compatible` / … (no `images.ai`)     |
+
+All local recipes **loopback-publish only**, pin explicit tags (never
+`latest`), and require curated model sources — never arbitrary untrusted GGUF
+(2026 GGUF-parser CVEs).
+
+### Default local: llama.cpp
 
 ```typescript title="oke.config.ts"
 import { defineConfig } from "okengine/config";
 
 export default defineConfig({
   drivers: {
-    ai: { local: "ollama", docker: "ollama", prod: "anthropic" },
+    ai: { local: "openai-compatible", docker: "openai-compatible", prod: "anthropic" },
   },
   images: {
-    ai: "ollama/ollama:latest",
+    ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // ≥ b8146; never :latest
   },
 });
 ```
 
-```typescript title="src/ai.ts"
+```typescript title="src/core/ai.ts"
 export const smart = ai.model("smart", {
-  provider: "ollama",
-  model: "qwen3.5:9b", // balanced local-dev starting point — override freely
+  provider: "openai-compatible",
+  model: process.env.OKE_AI_MODEL ?? "smollm2", // Docker Hub ai/ id
 });
 ```
 
-- **Model:** set on `ai.model(…, { model })` or `OKE_AI_MODEL`. `qwen3.5:9b` ([Ollama library](https://ollama.com/library/qwen3.5); same as `qwen3.5:latest`) is a reasonable balanced starting point for local dev — not the only option. On Apple Silicon, prefer `qwen3.5:9b-mlx` for the MLX build.
-- **URL:** default `http://127.0.0.1:11434`. Override with `OKE_AI_URL` or `OLLAMA_HOST` (bare `host:port` is fine).
-- **Docker:** the image recipe pulls the configured model and writes `OKE_AI_URL` into `docker/.env.docker`.
-- **Fail-loud:** unreachable or unhealthy Ollama throws `OllamaUnavailableError` — never a silent mock fallback.
-- **PII:** `ollama` counts as on-premise for the build-time egress check (same as `mock`).
+- **URL:** `http://127.0.0.1:8080/v1` (recipe writes `OKE_AI_URL`).
+- **Model:** curated Docker Hub [`ai/`](https://hub.docker.com/u/ai) id via `OKE_AI_MODEL`.
+- **PII:** local OpenAI-compatible endpoints count as on-premise when they are not third-party cloud.
+
+### Ollama (fully supported alternative)
+
+Native `ollama` driver — `complete`, `stream`, `embed` without an OpenAI shim.
+Pin `ollama/ollama:0.32.6` or newer (≥ **0.17.1**). See
+[Ollama recipe](/docs/recipes/ollama).
 
 ### OpenAI-compatible endpoints (one driver)
 
-`openai-compatible` is the shared chat/completions client — OpenAI, Groq, Together, OpenRouter, vLLM, LM Studio, and Ollama’s `/v1` shim. You do **not** get a separate driver per vendor; only `baseUrl`, `apiKey`, `model`, and optional `headers` change.
+`openai-compatible` is the shared chat/completions client — OpenAI, Groq,
+Together, OpenRouter, llama.cpp, vLLM, SGLang, LM Studio, and Ollama’s `/v1`
+shim. Only `baseUrl`, `apiKey`, `model`, and optional `headers` change.
 
-| Target             | Typical `baseUrl`                     | Key                                                         |
-| ------------------ | ------------------------------------- | ----------------------------------------------------------- |
-| OpenAI             | `https://api.openai.com/v1` (default) | required (`OPENAI_API_KEY`)                                 |
-| Groq               | `https://api.groq.com/openai/v1`      | required                                                    |
-| Together           | `https://api.together.xyz/v1`         | required                                                    |
-| OpenRouter         | `https://openrouter.ai/api/v1`        | required; optional `HTTP-Referer` / `X-Title` via `headers` |
-| LM Studio / local  | e.g. `http://127.0.0.1:1234/v1`       | optional                                                    |
-| Ollama OpenAI shim | `http://127.0.0.1:11434/v1`           | optional                                                    |
+| Target              | Typical `baseUrl`                     | Key                                                         |
+| ------------------- | ------------------------------------- | ----------------------------------------------------------- |
+| OpenAI              | `https://api.openai.com/v1` (default) | required (`OPENAI_API_KEY`)                                 |
+| llama.cpp (default) | `http://127.0.0.1:8080/v1`            | optional                                                    |
+| vLLM / SGLang       | `http://127.0.0.1:8000/v1` / `:30000` | optional                                                    |
+| Groq                | `https://api.groq.com/openai/v1`      | required                                                    |
+| Together            | `https://api.together.xyz/v1`         | required                                                    |
+| OpenRouter          | `https://openrouter.ai/api/v1`        | required; optional `HTTP-Referer` / `X-Title` via `headers` |
+| LM Studio / local   | e.g. `http://127.0.0.1:1234/v1`       | optional                                                    |
+| Ollama OpenAI shim  | `http://127.0.0.1:11434/v1`           | optional                                                    |
 
-Prefer the native `ollama` driver for local Ollama (`/api/chat`). Point `openai-compatible` at Ollama `/v1` only when you need the OpenAI wire shape.
+Prefer the native `ollama` driver for local Ollama (`/api/chat`).
 
 **Consequence:** a missing key against the default OpenAI cloud base fails at open; a custom `baseUrl` may omit the key. HTTP errors always throw — never a silent mock fallback.
 
@@ -248,7 +270,7 @@ The one you declared. There is no fallback or guess — if `prod` has no AI driv
 </Accordion>
 <Accordion title="oke boot: ollama driver needs OKE_AI_URL">
 
-Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Locally, the default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers and that you have pulled the model you named (`ollama pull qwen3.5:9b`, or `qwen3.5:9b-mlx` on Apple Silicon, or your `OKE_AI_MODEL`). Prefer `oke ai setup` to wire driver, env, and `src/ai.ts` in one pass.
+Docker mode expects `OKE_AI_URL` from `docker/.env.docker` (written when `images.ai` is pinned). Keep `OKE_AI_*` in `.env.local` commented — an active `OKE_AI_URL` there wins and shadows the compose URL. Locally, the Ollama default is `http://127.0.0.1:11434`. If asks fail with `OllamaUnavailableError`, confirm the server answers at that URL and that the model is listed under `GET /api/tags` (boot pulls via `POST /api/pull` against the container — do not rely on a host `ollama pull`, which may talk to a different install). Prefer `oke ai setup` to wire driver, commented env overrides, and `src/core/ai.ts` in one pass.
 
 </Accordion>
 <Accordion title="A prompt edit made answers worse — how do I catch that pre-merge?">

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

@@ -81,11 +81,42 @@ Locally the `console` driver captures mail into an inbox instead of sending; in
 
 <ChannelPhysics />
 
-### Consent is checked before sending
+### Consent and hard-bounce suppression
 
-Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt status is `suppressed/opted-out`. You never hand-roll "did they unsubscribe?" checks.
+Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt status is `suppressed/opted-out`.
 
-**Known limit:** default suppression, consent, and receipt stores are **process-local memory**. Opt-out / hard-bounce / receipt on replica A is invisible to replica B. Boot prints a one-shot warning when those defaults are used. Inject shared stores for multi-instance, or run a single Channel consumer, until a durable driver ships.
+Hard bounces are protective too. After a provider outcome of `hard-bounce` is ingested, the address is auto-added to suppression; the **next** send to that address is blocked before any transport runs (`suppressed/prior-bounce`). Soft bounces and complaints do **not** auto-suppress.
+
+```typescript
+// After a provider webhook (or Console ingest):
+runtime.ingestOutcome({
+  messageId,
+  state: "hard-bounce",
+  to: user.email,
+  medium: "email",
+});
+// Next fx.send / runtime.send to that address → ok: false, driverId: "suppression"
+```
+
+**Known limit:** default suppression, consent, and receipt stores are **process-local memory**. Opt-out / hard-bounce / receipt on replica A is invisible to replica B. Boot prints a one-shot warning when those defaults are used.
+
+### Inject shared stores (multi-instance workaround)
+
+Until a durable driver ships, inject your own stores that implement the same surfaces — boot skips the process-local warn when both `suppression` and `receipts` are provided:
+
+```typescript
+import { createConsentStore, createReceiptLedger, createSuppressionStore } from "okengine";
+
+const consent = createConsentStore(); // or a wrapper over shared storage
+const suppression = createSuppressionStore({ consent });
+const receipts = createReceiptLedger();
+
+await app.boot({
+  channel: { suppression, receipts /* templates, catalog, drivers… */ },
+});
+```
+
+`consent` alone is wrapped into the default suppression store when `suppression` is omitted. Prefer passing `suppression` when you share bounce + opt-out state.
 
 ### Locale resolves, then the catalog
 
@@ -97,6 +128,20 @@ Locales come from `oke.config.ts` `i18n`. Catalog bodies use `{{field}}` — not
 ICU ([i18n](/docs/reference/i18n) / `fx.t` owns flow copy). Pass `locale` /
 `profileLocale` / `acceptLanguage` on `fx.send`, or omit them for `fx.locale`.
 
+```typescript
+// Catalog (template → locale → body)
+{
+  "order-confirmed": {
+    en: { subject: "Order {{orderId}}", text: "Hello {{name}}" },
+    ar: { subject: "طلب {{orderId}}", text: "مرحبًا {{name}}" },
+  },
+}
+// locale: "ar" + data { name: "علي", orderId: "ORD-42" }
+// → subject "طلب ORD-42", text "مرحبًا علي"
+```
+
+**Consequence:** `Accept-Language: ar-SA` does **not** match a catalog key named `ar`. Provide both keys, or send `locale: "ar"`.
+
 ### Fallback chains are same-medium
 
 `via` orders **driver ids** for the template's medium — first success wins,
@@ -108,12 +153,42 @@ await fx.send(orderConfirmed, {
   data: { name, orderId, total },
   via: ["smtp", "resend"],
 });
-// smtp fails → resend tried → receipt status "fallback" with both attempts
+// smtp provider-error → resend tried → receipt status "fallback"
 ```
 
-### Receipts for everything
+Permanent client errors do **not** advance the chain (invalid address, HTTP
+400/401/403) — the same distinction OTP cross-medium delivery uses. A provider
+timeout or 5xx does failover.
+
+### Receipt ledger
+
+Each send records attempts — driver, ok/error, timestamp, message id — so "did
+the user get it?" is a Console query. Dry run: kernel records a would-have-fired
+send and never opens a provider — no Channel receipt.
+
+| Status                            | Meaning                                       |
+| --------------------------------- | --------------------------------------------- |
+| `sent`                            | Delivered on the first successful driver      |
+| `fallback`                        | Earlier drivers failed; a later one succeeded |
+| `suppressed/opted-out`            | Consent blocked the send (no provider call)   |
+| `suppressed/prior-bounce`         | Prior hard bounce blocked the send            |
+| `blocked/invalid-address`         | Permanent client error (no useful failover)   |
+| `hard-bounce` / `soft-bounce` / … | Post-send outcomes via `ingestOutcome`        |
+
+### WhatsApp: template vs session (Known gap)
+
+WhatsApp Business allows free-form ("session") messages only inside a
+customer-initiated **24h** window; outside that window you must send a
+pre-approved **template**.
+
+OKE drivers choose payload shape by whether a template name is present on the
+message (`template` / `data.template` → template API; otherwise free text).
 
-Each send records its attempts — driver, ok/error, timestamp, message id — so "did the user actually get it?" is a Console query, not a guess. In a dry run, the kernel records a would-have-fired send and never opens a provider — no Channel receipt is written.
+There is **no** session-window clock or gate on the Channel runtime today.
+Sending free-form outside the window risks provider rejection or account
+action — handle that yourself until a real design ships.
+
+OTP WhatsApp paths often send free text via provider failover.
 
 ## Per-environment drivers
 
@@ -188,12 +263,22 @@ Nothing _should_ arrive — the `console` driver captures mail instead of sendin
 </Accordion>
 <Accordion title="A user says they stopped receiving messages">
 
-Check consent first: if they opted out, sends to them are suppressed by design. The Console shows the suppression on the receipt — it is a delivered-as-intended outcome, not a bug.
+Check consent first: if they opted out, sends to them are suppressed by design. After a hard bounce, later sends are `suppressed/prior-bounce` without contacting the provider. The Console shows the suppression on the receipt — it is a delivered-as-intended outcome, not a bug.
+
+</Accordion>
+<Accordion title="Opt-out on replica A, still sending on replica B">
+
+Default stores are process-local. Inject shared `suppression` + `receipts` on boot (see above), or run a single Channel consumer, until a durable driver ships.
+
+</Accordion>
+<Accordion title="Primary failed with invalid address and didn't try secondary">
+
+By design. Permanent client errors (invalid address, HTTP 400/401/403) do not failover — every provider would reject the same address. Provider outages and 5xx do advance the chain.
 
 </Accordion>
 <Accordion title="The Arabic version didn't render">
 
-The send still succeeds: the body falls back to your default locale, then `en`, when the catalog misses that exact key. Check that an Arabic entry exists under the same tag you send (`ar` vs `ar-SA`) and that the template lists it in `locales`.
+The send still succeeds: the body falls back to your default locale, then `en`, when the catalog misses that exact key. Check that an Arabic entry exists under the same tag you send (`ar` vs `ar-SA`) and that the template lists it in `locales`. Catalog interpolation is `{{field}}` only — ICU plurals live in [i18n](/docs/reference/i18n).
 
 </Accordion>
 <Accordion title="How do I ingest SNDR / Unifonic delivery webhooks?">
@@ -209,7 +294,9 @@ import {
 
 Verify the signature when the provider sends one, parse the body, then call
 `ingestOutcome` on your channel runtime with the bounce/complaint fields.
-Console reads the receipt ledger — never raw webhook JSON.
+
+Hard bounce auto-adds suppression. Console reads the receipt ledger — never
+raw webhook JSON.
 
 </Accordion>
 <Accordion title="How do I know which driver finally delivered?">
@@ -242,6 +329,7 @@ Confirm a visible OS notification titled `okengine webpush interop`.
 - [Console · Channels](/docs/console/channels) — receipts, attempts, suppression
 - [Environment Variables](/docs/reference/environment-variables) — Channel boot credentials
 - [Configuration](/docs/reference/configuration) — `drivers.channel.*` maps
+- [i18n](/docs/reference/i18n) — ICU / `fx.t` vs Channel `{{field}}` catalogs
 - [Signal](/docs/elements/signal) — machine-to-machine messaging, the other side of the line
 
 ## Next

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

@@ -194,6 +194,7 @@ They are not sharing one CronStore. In-memory leases are per process. Point ever
 ## Learn more
 
 - [Flow](/docs/elements/flow) — `on(trigger, flow)` and the `fx` surface
+- [fx · Runs](/docs/reference/fx#runs-observability-read) — native SLO checkers via `on(every(…))` + `fx.runs`
 - [Console · Clock](/docs/console/clock) — health numbers, pause / edit / wake early
 - [Signal](/docs/elements/signal) — reacting to events instead of time
 

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

@@ -71,14 +71,15 @@ curl -X POST localhost:6530/orders -d '{"sku":"SKU-1","qty":2}' -H 'content-type
 
 ## Anatomy of a Flow
 
-| Part     | Role                                                            |
-| -------- | --------------------------------------------------------------- |
-| trigger  | What starts the flow — `http`, a signal, `every`, a row change  |
-| `in`     | Input contract — validated before `do` runs; bad input is a 422 |
-| `out`    | Output contract — the return value is checked against it        |
-| `errors` | Typed failures — **returned** with `fx.fail`, never thrown      |
-| `retry`  | Optional whole-`do` backoff on thrown errors (same journal)     |
-| `do`     | The work — every read, write, emit, and call goes through `fx`  |
+| Part         | Role                                                            |
+| ------------ | --------------------------------------------------------------- |
+| trigger      | What starts the flow — `http`, a signal, `every`, a row change  |
+| `in`         | Input contract — validated before `do` runs; bad input is a 422 |
+| `out`        | Output contract — the return value is checked against it        |
+| `errors`     | Typed failures — **returned** with `fx.fail`, never thrown      |
+| `retry`      | Optional whole-`do` backoff on thrown errors (same journal)     |
+| `do`         | The work — every read, write, emit, and call goes through `fx`  |
+| `compensate` | Durable only — undo phase after terminal failure (same journal) |
 
 Failures are values, not exceptions:
 
@@ -234,6 +235,34 @@ Replay is **at-least-once** for a step whose body never persisted (crash mid-ste
 
 For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow({ retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
 
+After a **terminal** failure (`fx.fail` or exhausted retries / uncaught throw), optional
+`compensate` runs under the same journal. Undo work must use **new** step names
+(`undo:…`) — never rewind forward steps:
+
+```typescript
+export const chargeOrder = flow({
+  durable: true,
+  in: OrderRef,
+  out: z.boolean(),
+  do: async ({ orderId }, fx) => {
+    await fx.step("reserve", () => reserve(orderId));
+    await fx.step("charge", () => charge(orderId));
+    return true;
+  },
+  compensate: async ({ input, completedSteps }, fx) => {
+    if (completedSteps.includes("charge")) {
+      await fx.step("undo:charge", () => refund(input.orderId));
+    }
+    if (completedSteps.includes("reserve")) {
+      await fx.step("undo:reserve", () => release(input.orderId));
+    }
+  },
+});
+```
+
+Thrown errors on the durable execute path commit the journal as `failed` (and land on Runs).
+`JournalSuspend` (sleep) is park, not failure — compensate does not run.
+
 ## Composition is just calls
 
 Wiring is values flowing between flows — declared in code, never configured in a dashboard:
@@ -268,6 +297,11 @@ Use `fx.all` (or `fx.race`) with thunks. The first rejection aborts siblings thr
 
 Put `fx.retry` **inside** `fx.step`, not around it. Completed steps replay from the journal and never re-run. `flow({ retry })` is for coarse whole-body retries on the same session.
 
+</Accordion>
+<Accordion title="When does compensate run?">
+
+Only after terminal failure for that journal attempt — not on sleep, not mid-retry, not on success. Undo bodies must be idempotent (`undo:*` steps resume like any other step). Irreversible effects (`send` / `ask`) need developer-declared undos or an explicit no-op.
+
 </Accordion>
 <Accordion title="How do I share logic between flows — a private function?">
 

package/site/content/docs/get-started/basic-usage.mdx

@@ -68,11 +68,15 @@ Adopted modules become namespaces on the client:
 import { oke } from "okengine";
 import * as main from "./flows/main";
 import * as notes from "./flows/notes";
+import { db } from "./core";
 
-export const app = oke({ name: "notes" }).adopt({ main, notes });
+export const app = oke({ name: "notes", stores: [db] }).adopt({ main, notes });
 export type App = typeof app;
 ```
 
+The scaffolded `src/app.ts` also registers secrets, signals, and channel
+templates in the same `oke({ … })` call — no post-construction mutation.
+
 ```typescript title="client"
 import { createClient } from "okengine/client";
 import type { App } from "./app";

package/site/content/docs/get-started/installation.mdx

@@ -60,11 +60,15 @@ bunx create-oke@latest my-app --yes
 ```
 
 Two Notes starters: **standard** (local-first) and **advanced** (docker-ready +
-files/digest/AI).
+files/digest/AI). Both ship a minimal GitHub Actions workflow (typecheck +
+`bun test` on push/PR) so the first push has working CI.
 
-On a TTY: pick a template, then **recommended defaults**, **customize** (local
-or docker first; saved to `~/.oke/create-defaults.json`), or **reuse** matching
-saved settings. Project name rejects a non-empty existing path.
+On a TTY: pick a template, then **recommended defaults**, **customize**, or
+**reuse** matching saved settings (saved to `~/.oke/create-defaults.json`).
+
+Customize asks local or docker first, walks facets (including `store.index` with
+`none`), then **AI setup** (Recommended / Customize / Off). Project name rejects
+a non-empty existing path.
 
 Non-TTY / `--yes` stay scriptable. Defaults: local SQLite · Docker/prod Postgres.
 `--sql postgres` pins SQL; `--ai` runs the model wizard before install.
@@ -88,7 +92,7 @@ Four ports come up together (mnemonic: **O·K·E = 6·5·3**):
 <Surfaces />
 
 Open `http://localhost:6533`. Claim the Console with the **claim code** printed
-once in the `oke dev` log, then create the first operator.
+once under the `oke dev` hero, then create the first operator.
 
 Password policy matches Gate auth: **≥ 12 characters, with a letter and a
 number.** If the Console lists your flows, the install worked — **derived, not

package/site/content/docs/meta.json

@@ -8,6 +8,8 @@
     "plugins",
     "console",
     "deployment",
+    "recipes",
+    "providers",
     "reference",
     "ai"
   ]

package/site/content/docs/providers/azure-redis.mdx

@@ -0,0 +1,85 @@
+---
+title: "Azure Cache for Redis"
+description: "Azure-managed Redis — Access keys blade, TLS port 6380 vs 6379, Basic tier no SLA."
+icon: "Zap"
+source: "docs/spec/unified-theory.md"
+---
+
+Azure Cache for Redis spans Basic → Enterprise. New caches expect TLS.
+`drivers.store.kv` stays `redis`.
+
+<Callout title="The one rule">
+  Build `rediss://` from **Overview** hostname + **Access keys** primary key + SSL port **6380**. Do
+  not use 6379 unless you explicitly allowed non-TLS.
+</Callout>
+
+## Find credentials (current portal)
+
+1. Azure Portal → your **Azure Cache for Redis** resource.
+2. **Overview** → copy **Host name** (`….redis.cache.windows.net`).
+3. **Settings → Authentication** → **Access keys** tab (or **Overview → Show access
+   keys**) → copy **Primary** key.
+4. Ports: Overview link next to **Ports**, or docs defaults — **6380** TLS, **6379**
+   non-TLS (disabled by default on new caches).
+5. Enterprise tiers may use port **10000** — check Overview for that SKU.
+
+```bash title="process env"
+REDIS_URL=rediss://:PRIMARY_KEY@my-cache.redis.cache.windows.net:6380
+```
+
+Azure's “connection string” blade often shows StackExchange-style
+`host:6380,password=…,ssl=True` — translate that to `rediss://:password@host:6380` for
+oke.
+
+## Production guidance
+
+| Tier                 | Notes                                   |
+| -------------------- | --------------------------------------- |
+| Basic                | Shared, **no SLA** — not for production |
+| Standard             | Replicated                              |
+| Premium / Enterprise | Clustering, persistence, VNet           |
+
+Non-TLS: **Settings → Advanced settings → Allow access only via SSL = No** — avoid in
+production. Entra ID auth exists on newer tiers; oke's URL driver expects access-key
+auth in `REDIS_URL`.
+
+## Real gotcha — port 6380 vs 6379
+
+Using `redis://…:6379` against a TLS-only cache fails. New caches disable non-TLS;
+always start from **6380** + `rediss://` unless you intentionally opened 6379.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="Connection reset / SSL errors on 6379">
+
+TLS-only cache. Switch to port **6380** and `rediss://`. Confirm Advanced settings still
+require SSL.
+
+</Accordion>
+<Accordion title="WRONGPASS invalid username-password pair">
+
+Primary key rotated or secondary key pasted by mistake. Re-copy **Primary** from
+**Authentication → Access keys** and update `REDIS_URL` (empty username, key as
+password).
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Redis (image)](/docs/recipes/redis)
+- [ElastiCache](/docs/providers/elasticache) · [Memorystore](/docs/providers/memorystore)
+- [Store · KV](/docs/elements/store#kv)
+
+## Next
+
+<Cards>
+  <Card title="ElastiCache" description="AWS's equivalent." href="/docs/providers/elasticache" />
+  <Card title="Memorystore" description="GCP's equivalent." href="/docs/providers/memorystore" />
+  <Card
+    title="CockroachDB"
+    description="Managed SQL-side pair."
+    href="/docs/providers/cockroachdb"
+  />
+</Cards>