okengine 0.9.0 → 0.10.0

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

@@ -0,0 +1,106 @@
+---
+title: "vLLM"
+description: "Production-tier self-hosted inference — OpenAI-compatible GPU serving when you run inference yourself."
+icon: "Cpu"
+source: "docs/spec/unified-theory.md"
+---
+
+vLLM is for **multi-user / production concurrency on real GPU hardware** when
+you choose to self-host inference instead of a managed provider. Driver id stays
+`openai-compatible`. Most apps should prefer Anthropic / OpenAI / … in prod.
+
+<Callout title="The one rule">
+  Pin an explicit image tag (never `latest`), publish only on loopback, and treat this as “I run
+  production inference myself” — not the default create path.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin driver + image
+
+```typescript title="oke.config.ts"
+drivers: {
+  ai: { docker: "openai-compatible", prod: "openai-compatible", test: "mock" },
+},
+images: {
+  ai: "vllm/vllm-openai:v0.26.0", // never :latest
+},
+```
+
+Or `oke ai setup --provider vllm --yes`.
+
+</Step>
+
+<Step>
+### Env + GPU
+
+```bash title="docker/.env.docker"
+OKE_AI_URL=http://127.0.0.1:8000/v1
+OKE_AI_MODEL=Qwen/Qwen3-0.6B
+```
+
+The recipe sets `ipc: host` and an NVIDIA device reservation. Host needs the
+NVIDIA Container Toolkit.
+
+</Step>
+
+<Step>
+### Decide deliberately
+
+| Path                                 | When                                         |
+| ------------------------------------ | -------------------------------------------- |
+| Managed provider                     | Default for most production apps             |
+| **vLLM** (this recipe)               | Self-hosted multi-user GPU serving           |
+| [SGLang](/docs/recipes/sglang)       | Self-hosted structured / agent GPU workloads |
+| [llama.cpp](/docs/recipes/llama-cpp) | Single-user / dev (default local)            |
+
+</Step>
+
+</Steps>
+
+## Security
+
+| Control      | Requirement                                   |
+| ------------ | --------------------------------------------- |
+| Host publish | `127.0.0.1:8000:8000` only — never `0.0.0.0`  |
+| Image pin    | Explicit version tag — never `latest`         |
+| Model source | Trusted Hugging Face repos / your own weights |
+
+## What the recipe configures
+
+| Field          | Value                                                 |
+| -------------- | ----------------------------------------------------- |
+| Container port | `8000`                                                |
+| Host publish   | `127.0.0.1:8000:8000`                                 |
+| `ipc`          | `host`                                                |
+| GPU            | `deploy.resources.reservations.devices` (nvidia, all) |
+| Healthcheck    | `GET /health`, long start period for model load       |
+| Connection URL | `http://host:8000/v1`                                 |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="GPU not visible / container exits">
+
+Install the NVIDIA Container Toolkit on the host. CPU-only hosts should use
+[llama.cpp](/docs/recipes/llama-cpp) or [Ollama](/docs/recipes/ollama) instead.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [llama.cpp](/docs/recipes/llama-cpp) — default local AI
+- [SGLang](/docs/recipes/sglang) — structured / agent GPU path
+- [AI](/docs/elements/ai) — drivers and `fx.ask`
+
+## Next
+
+<Cards>
+  <Card title="SGLang" description="Agent / structured GPU serving." href="/docs/recipes/sglang" />
+  <Card title="llama.cpp" description="Default local AI." href="/docs/recipes/llama-cpp" />
+  <Card title="AI" description="Prompts and guardrails." href="/docs/elements/ai" />
+</Cards>

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

@@ -0,0 +1,135 @@
+---
+title: "YugabyteDB"
+description: "Self-hosted single-node YSQL — YSQL_* env, port 5433, driver stays postgres."
+icon: "Database"
+source: "docs/spec/unified-theory.md"
+---
+
+YugabyteDB's **YSQL** API speaks Postgres wire. Pin `yugabytedb/yugabyte` as
+`store.sql` and `oke docker` derives a single-node `yugabyted` service —
+credentials, healthcheck, and `DATABASE_URL`. Driver id stays `postgres`.
+
+<Callout title="The one rule">
+  Use the YSQL API only — never treat YCQL as `store.sql`. Vendor choice lives in
+  `images["store.sql"]`; host maps `:5432` → container `:5433`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the image
+
+```typescript title="oke.config.ts"
+images: {
+  "store.sql": "yugabytedb/yugabyte:2025.1.0.0-b100", // pin a real tag
+},
+```
+
+</Step>
+
+<Step>
+### Bring the stack up
+
+```bash
+oke dev --docker
+```
+
+`oke docker` injects `YSQL_USER` / `YSQL_PASSWORD` / `YSQL_DB` from `OKE_STORE_SQL_*`
+(password presence turns authentication on), runs
+`bin/yugabyted start --background=false`, and publishes YSQL on host `:5432`.
+
+</Step>
+
+<Step>
+### Connect
+
+```bash
+echo "$DATABASE_URL"
+# postgres://oke:…@127.0.0.1:5432/oke
+```
+
+First healthy state is slower than plain Postgres — the healthcheck allows a long
+start period.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                 | Who sets it            | Meaning                          |
+| ------------------------ | ---------------------- | -------------------------------- |
+| `OKE_STORE_SQL_USER`     | `oke docker` → compose | → `YSQL_USER`                    |
+| `OKE_STORE_SQL_PASSWORD` | `oke docker` → compose | → `YSQL_PASSWORD` (enables auth) |
+| `OKE_STORE_SQL_DB`       | `oke docker` → compose | → `YSQL_DB`                      |
+| `DATABASE_URL`           | stack env for the app  | Host `:5432` → container `:5433` |
+
+## Data and backup
+
+| Path                     | What lives there                                     |
+| ------------------------ | ---------------------------------------------------- |
+| `/home/yugabyte/yb_data` | Named volume `store-sql-data` — `yugabyted` base dir |
+
+**Backup means:** volume backup of `store-sql-data`, or Yugabyte's backup tooling.
+Losing that volume loses the universe data.
+
+## Production note
+
+Single-node `yugabyted` is for local and small self-hosted use. For managed Aeon
+clusters, use the [YugabyteDB provider](/docs/providers/yugabytedb). Pin a concrete
+tag; the image is large and cold-start is slower than Postgres.
+
+## What the recipe configures
+
+| Field          | Value                                                 |
+| -------------- | ----------------------------------------------------- |
+| Container port | `5433` (host publishes `5432`)                        |
+| Command        | `bin/yugabyted start --base_dir=… --background=false` |
+| Healthcheck    | `ysqlsh … SELECT 1` (90s `start_period`)              |
+| Connection URL | `postgres://user:pass@host:5432/db`                   |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="store-sql unhealthy for a long time">
+
+Yugabyte cold-start is slow. Wait through the healthcheck `start_period`, then read
+`docker compose … logs store-sql`.
+
+macOS AirPlay on `:7000` can conflict with Yugabyte's master UI — stop AirPlay
+Receiver or remap that port in `compose.override.yml` if you need the UI.
+
+</Accordion>
+<Accordion title="password authentication failed">
+
+`YSQL_PASSWORD` must match `DATABASE_URL`. Regenerate `docker/.env.docker` with
+`oke dev --docker`. Auth is off only when `YSQL_PASSWORD` is unset — this recipe
+always sets it.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [YugabyteDB (provider)](/docs/providers/yugabytedb) — managed Aeon Connect flow
+- [CockroachDB](/docs/recipes/cockroachdb) — self-hosted distributed peer
+- [Postgres](/docs/recipes/postgres) — default SQL recipe
+- [Store · SQL](/docs/elements/store#sql) — schema workflows
+
+## Next
+
+<Cards>
+  <Card
+    title="YugabyteDB Aeon"
+    description="Managed cloud alternative."
+    href="/docs/providers/yugabytedb"
+  />
+  <Card
+    title="CockroachDB"
+    description="Self-hosted Cockroach recipe."
+    href="/docs/recipes/cockroachdb"
+  />
+  <Card title="Postgres" description="The default store.sql image." href="/docs/recipes/postgres" />
+</Cards>

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

@@ -45,14 +45,44 @@ oke build --target edge          # < 15 kB kernel profile
 oke eval                         # run prompt eval sets; fails CI on regression
 oke ai setup                     # configure AI driver + models (TTY wizard or flags)
 oke branch prod --at "yesterday" # fork journaled state into a sandbox
+oke replay --request-id <id>     # re-invoke a past Flow from a Runs WideEvent (dry-run if send/ask)
 oke privacy erase --subject <id> # crypto-shredding: deletes the key, not the terabytes
 oke upgrade                      # run codemods for a breaking change, print the diff
 ```
 
+`oke replay` loads a Runs WideEvent by id and re-enters the Flow with stored
+input. Defaults to dry-run when the ledger has `send` / `ask` (pass `--live`
+to override). Needs a build that persisted `WideEvent.input`.
+
 In development, app, Console, MCP, and docs MCP prefer the canonical ports and move upward
 when occupied. Docker infrastructure uses stable per-project offsets in disjoint ranges for
 each built-in service, preventing one service's offset port from overlapping another's.
 
+`oke dev` boot chrome prints immediately (wordmark + Starting + profile), then
+streams background work (compose up, vault, per-service health, AI probe) in a
+live progress pane — no blank multi-second wait. That pane clears before the
+elements + Docker board. Status ● is green ready · yellow pending/loading ·
+red error · dim idle. Compose health keeps polling (`docker compose ps -a`)
+so ● updates live if you stop a container; AI ● tracks model phase while the
+AI container is up. Boot does not wait for the model to become ready.
+
+On a TTY with `-d`, keyboard controls stay active under Logs. Status ● for
+compose/AI live on the board **above** Logs (not as log lines). Press `c` to
+clear the log pane and reprint the latest board. `l` / `?` also refresh first
+so the services/help panel is not mixed into request logs.
+
+| Key                          | Action                              |
+| ---------------------------- | ----------------------------------- |
+| `?`                          | help                                |
+| `c`                          | refresh — clear logs, show latest ● |
+| `q`                          | quit `oke dev`                      |
+| `l`                          | list docker services                |
+| `u` / `x`                    | compose up / stop (whole stack)     |
+| `1`–`9` then `u` / `x` / `r` | start / stop / restart one service  |
+
+Compose stays quiet unless it fails. Process-local boot notices print once under
+the hero (not once per process).
+
 ### create-oke
 
 ```bash
@@ -66,9 +96,11 @@ bunx create-oke@latest my-app --no-ai
 
 On a TTY: pick **standard** or **advanced**, then recommended defaults or
 customize. Customize asks **local** or **docker** first, walks facets for that
-side only, then whether to customize the other (defaults if no). Writes
-user-global `~/.oke/create-defaults.json` (reuse only when `template` matches).
-Scaffold writes `.oke/mode` from the primary side. Non-TTY / `--yes` / explicit
+side only (including `store.index` with a `none` opt-out — no separate enable
+prompt), then whether to customize the other (defaults if no). **AI setup**
+offers Recommended (llama.cpp) · Customize · Off. Writes user-global
+`~/.oke/create-defaults.json` (reuse only when `template` matches). Scaffold
+writes `.oke/mode` from the primary side. Non-TTY / `--yes` / explicit
 `--template` never prompt.
 
 ### Additional commands
@@ -79,8 +111,9 @@ oke doctor --json                # -j  JSON on stdout; hints on stderr (agents /
 oke stack --json                 # -j
 oke images list                  # recipe · image · tag · digest · size (--json|-j)
 oke gates list                   # Module:Action catalogue (--json|-j)
-oke ai setup --provider ollama --yes   # non-interactive AI config
-# TTY Ollama: needs quiz → RAM-tier panel → recommend / installed / manual (+ ← Back)
+oke ai setup --provider llama-cpp --yes  # default local AI
+oke ai setup --provider ollama --yes     # fully supported alternative
+# TTY: llama.cpp / Ollama → banner · tiers · manual; vLLM / SGLang / cloud → model
 ```
 
 ### Shell completion
@@ -115,7 +148,10 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 | `--diff`             |       | `doctor`                                       |
 | `--json`             | `-j`  | `doctor`, `stack`, `images list`, `gates list` |
 | `--manifest`         | `-m`  | most Manifest readers                          |
-| `--entry`            | `-e`  | `dev`, `start`, `build`                        |
+| `--entry`            | `-e`  | `dev`, `start`, `build`, `replay`              |
+| `--request-id`       | `-r`  | `replay`                                       |
+| `--dry-run`          |       | `replay`                                       |
+| `--live`             |       | `replay`                                       |
 | `--out` / `--outdir` | `-o`  | writers                                        |
 | `--subject`          | `-s`  | `privacy erase`                                |
 | `--before`           | `-b`  | `doctor --diff`                                |

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

@@ -82,7 +82,7 @@ images: {
   "store.files": "rustfs/rustfs:1.0.0-beta.11",
   "channel.email": "axllent/mailpit:v1.22.3",
   vault: "openbao/openbao:2.6.1",
-  ai: "ollama/ollama:latest",
+  ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // default; or ollama/ollama:0.32.6
   // opt-in TLS edge — omit for the default (app publishes 6530):
   // proxy: "caddy:2-alpine",   // simplest automatic HTTPS
   // proxy: "traefik:v3.3",     // label auto-discovery for --scale app=N
@@ -96,7 +96,9 @@ When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog
 For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays
 `redis`, same `REDIS_URL`. Image table + licenses: [Store · KV](/docs/elements/store#kv).
 
-For `ai`, the Ollama recipe pulls `OKE_AI_MODEL` (default `qwen3.5:9b` — a balanced local-dev starting point; override freely; on Apple Silicon prefer `qwen3.5:9b-mlx`) and writes `OKE_AI_URL`.
+For `ai`, default is [llama.cpp](/docs/recipes/llama-cpp) (`OKE_AI_URL` →
+`/v1`, curated Docker Hub `ai/` model). Ollama / vLLM / SGLang are explicit
+alternatives — see [Recipes · AI](/docs/recipes#ai-local--self-hosted).
 
 For `proxy`, pin **either** Caddy or Traefik — never both. Opt-in only; see
 [Reverse proxy](/docs/deployment/reverse-proxy).
@@ -165,7 +167,7 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 | Option    | Default | Surface |
 | --------- | ------- | ------- |
-| `app`     | `6530`  | App     |
+| `app`     | `6530`  | Backend |
 | `console` | `6533`  | Console |
 | `mcp`     | `6535`  | MCP     |
 

package/site/content/docs/reference/environment-variables.mdx

@@ -109,18 +109,18 @@ provider's real credentials — credentials alone never send.
 
 ## AI providers
 
-| Variable              | Used for                                                                                                                                  | Default when unset                |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                                                             | —                                 |
-| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                                                   | —                                 |
-| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                                                     | —                                 |
-| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                                                              | OpenAI cloud                      |
-| `OKE_AI_DRIVER`       | Force the AI driver id (honoured in docker mode)                                                                                          | config map                        |
-| `OKE_AI_URL`          | Ollama (or openai-compatible) base URL                                                                                                    | `http://127.0.0.1:11434` (ollama) |
-| `OKE_AI_MODEL`        | Default model for `ollama` (any pulled model; `qwen3.5:9b` is a balanced local-dev starting point; on Apple Silicon try `qwen3.5:9b-mlx`) | `qwen3.5:9b`                      |
-| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                                                  | —                                 |
-| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                                                              | —                                 |
-| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                                                     | —                                 |
+| Variable              | Used for                                                                                                | Default when unset                                                         |
+| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                           | —                                                                          |
+| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                 | —                                                                          |
+| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                   | —                                                                          |
+| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                            | OpenAI cloud                                                               |
+| `OKE_AI_DRIVER`       | Force the AI driver id (honoured in docker mode)                                                        | config map                                                                 |
+| `OKE_AI_URL`          | Local / openai-compatible base URL                                                                      | `http://127.0.0.1:8080/v1` (llama.cpp) · `http://127.0.0.1:11434` (ollama) |
+| `OKE_AI_MODEL`        | Default model id — Docker Hub `ai/` for llama.cpp; Ollama library tag for ollama; HF id for vLLM/SGLang | `smollm2` (llama.cpp) / `qwen3.5:9b` (ollama)                              |
+| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                | —                                                                          |
+| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                            | —                                                                          |
+| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                   | —                                                                          |
 
 ## Framework behavior
 

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

@@ -33,9 +33,42 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 ## Signals
 
-| Signature                             | Records | Notes                                                                                                                                           |
-| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fx.emit(signal, payload?, { key? })` | `emit`  | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; throws **OKE1042** (orphan) or **OKE1043** (schema) |
+| Signature                             | Records | Notes                                                                                                                                                                                                     |
+| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fx.emit(signal, payload?, { key? })` | `emit`  | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
+
+## Runs (observability read)
+
+Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Channel) without a parallel metrics API.
+
+| Signature                                | Records       | Returns                                       |
+| ---------------------------------------- | ------------- | --------------------------------------------- |
+| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory)        |
+| `fx.runs.all()`                          | `read` `runs` | All wide events                               |
+| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m) |
+| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches               |
+
+```typescript
+on(
+  every("5m"),
+  flow({
+    name: "ops.slo-check",
+    effects: { reads: ["runs"], sends: ["slo-alert"] },
+    do: async (_, fx) => {
+      const breaches = await fx.runs.checkSlo(
+        "checkout.create",
+        { availability: "99.9%", latency: { p95: "200ms" } },
+        5 * 60_000,
+      );
+      if (breaches.length === 0) return;
+      await fx.send(sloAlert, {
+        to: "oncall@example.com",
+        data: { flow: "checkout.create", count: breaches.length },
+      });
+    },
+  }),
+);
+```
 
 ## Flows
 
@@ -228,7 +261,8 @@ must log who started the call chain.
 
 <Callout title="No fx.metric">
   Investigated and declined. [Runs](/docs/console/runs) already own per-invocation observability as
-  wide events; a parallel counter/gauge API would be a second instrumentation path without a sink.
+  wide events. Native alerting is `fx.runs` + Clock + Channel — not a second counter/gauge API.
+  Optional OTLP export for existing Grafana/Datadog stacks is additive and never required.
 </Callout>
 
 ## Learn more

package/src/auth/otp-capability.ts

@@ -1,5 +1,5 @@
 /**
- * Fail-loud capability checks for the otp() plugin (Tier 1 / Tier 2).
+ * Fail-loud capability checks for the otp() plugin (provider / app mode).
  */
 
 import type { ChannelDriver, SmsOtpTransport } from "../drivers/channel-types.ts";
@@ -8,12 +8,12 @@ import type { OtpChannel } from "./verification.ts";
 /** Config snapshot stored on the otp plugin for boot-time assertion. */
 export interface OtpPluginConfig {
   readonly method: "otp";
-  readonly tier: 1 | 2;
+  readonly mode: "provider" | "app";
   readonly channels?: readonly OtpChannel[];
 }
 
 /**
- * Whether an SMS transport exposes provider-managed OTP (structural).
+ * Whether an SMS transport exposes provider OTP via Verify (structural).
  *
  * @param t - Candidate transport
  */
@@ -58,38 +58,38 @@ export function driverCoversMedium(drivers: readonly ChannelDriver[], medium: Ot
 }
 
 /**
- * Assert Tier 1: a Verify-capable SMS driver must be bound.
+ * Assert provider mode: a Verify-capable SMS driver must be bound.
  *
  * @param drivers - Bound channel drivers
  */
-export function assertOtpTier1Capability(drivers: readonly ChannelDriver[]): void {
+export function assertOtpProviderModeCapability(drivers: readonly ChannelDriver[]): void {
   if (findOtpSmsDriver(drivers)) return;
   const sms = drivers.filter((d) => d.smsTransport);
   if (sms.length === 0) {
     throw new Error(
-      'otp({ tier: 1 }): no SMS driver with sendOtp/verifyOtp bound — set drivers.channel.sms to a Verify-capable driver (e.g. "taqnyat"), or switch to otp({ tier: 2, channels: [...] })',
+      'otp({ mode: "provider" }): no SMS driver with sendOtp/verifyOtp bound — set drivers.channel.sms to a Verify-capable driver (e.g. "taqnyat"), or switch to otp({ mode: "app", channels: [...] })',
     );
   }
   const id = sms[0]?.id ?? "unknown";
   throw new Error(
-    `otp({ tier: 1 }): SMS driver "${id}" does not support provider-managed OTP — bind a Verify-capable driver (e.g. taqnyat), or switch to otp({ tier: 2, channels: [...] })`,
+    `otp({ mode: "provider" }): SMS driver "${id}" does not support provider OTP — bind a Verify-capable driver (e.g. taqnyat), or switch to otp({ mode: "app", channels: [...] })`,
   );
 }
 
 /**
- * Assert Tier 2: every declared channel has a deliverable driver.
+ * Assert app mode: every declared channel has a deliverable driver.
  *
  * @param drivers - Bound channel drivers
  * @param channels - Declared channel order
  */
-export function assertOtpTier2Channels(
+export function assertOtpAppModeChannels(
   drivers: readonly ChannelDriver[],
   channels: readonly OtpChannel[],
 ): void {
   for (const ch of channels) {
     if (!driverCoversMedium(drivers, ch)) {
       throw new Error(
-        `otp({ tier: 2 }): no channel driver covers "${ch}" — configure drivers.channel.${ch === "email" ? "email" : ch === "sms" ? "sms" : "whatsapp"}`,
+        `otp({ mode: "app" }): no channel driver covers "${ch}" — configure drivers.channel.${ch === "email" ? "email" : ch === "sms" ? "sms" : "whatsapp"}`,
       );
     }
   }
@@ -108,12 +108,12 @@ export function assertOtpPluginCapability(
   if (!config || typeof config !== "object") return;
   const c = config as Partial<OtpPluginConfig>;
   if (c.method !== "otp") return;
-  if (c.tier === 1) {
-    assertOtpTier1Capability(drivers);
+  if (c.mode === "provider") {
+    assertOtpProviderModeCapability(drivers);
     return;
   }
-  if (c.tier === 2) {
+  if (c.mode === "app") {
     const channels = c.channels ?? [];
-    assertOtpTier2Channels(drivers, channels);
+    assertOtpAppModeChannels(drivers, channels);
   }
 }

package/src/cli/ai-setup/ai-setup.test.ts

@@ -13,13 +13,14 @@ import { parseAiSetupArgs } from "./index.ts";
 
 describe("catalog", () => {
   test("recommendChatModel respects RAM tiers", () => {
-    expect(recommendChatModel(8).id).toBe("gemma4:e4b");
+    expect(recommendChatModel(8).ramGb).toBeLessThanOrEqual(8);
     expect(recommendChatModel(16).ramGb).toBeLessThanOrEqual(16);
     expect(recommendChatModel(null).recommended).toBe(true);
   });
 
   test("cloud providers ship short curated chat lists + recommended", () => {
     expect(cloudChatModels("openai").length).toBeGreaterThan(0);
+    expect(cloudChatModels("openai").length).toBeLessThanOrEqual(10);
     expect(cloudChatModels("anthropic").some((m) => m.recommended)).toBe(true);
     expect(recommendCloudChat("openai")).toBe("gpt-4o-mini");
     expect(recommendCloudChat("anthropic")).toContain("claude");
@@ -58,11 +59,15 @@ describe("apply", () => {
 });
 `;
     const next = upsertAiDrivers(src, "ollama");
-    expect(next).toMatch(/^ {4}ai:\s*\{/m);
-    expect(next).toContain('local: "ollama"');
-    const channel = next.match(/^ {4}channel:\s*\{[\s\S]*?\n {4}\},?\n/m)?.[0] ?? "";
-    expect(channel).toContain("email:");
-    expect(channel).not.toContain("ai:");
+    const body = next
+      .replace(/^import\s+[\s\S]*?from\s+["'][^"']+["'];?\s*/m, "")
+      .replace(/export\s+default\s+/, "return ");
+    const config = new Function("defineConfig", body)(<T>(c: T): T => c) as {
+      drivers?: { ai?: unknown; channel?: { ai?: unknown; email?: unknown } };
+    };
+    expect(config.drivers?.ai).toMatchObject({ local: "ollama", docker: "ollama" });
+    expect(config.drivers?.channel?.ai).toBeUndefined();
+    expect(config.drivers?.channel?.email).toBeDefined();
   });
 
   test("upsertEnv uncomment / set", () => {
@@ -70,6 +75,18 @@ describe("apply", () => {
     expect(upsertEnv(env, "OKE_AI_DRIVER", "ollama")).toContain("OKE_AI_DRIVER=ollama");
   });
 
+  test("upsertEnv comment keeps stack keys as overrides", () => {
+    const env = `# OKE_AI_DRIVER=mock\nOKE_AI_URL=http://x\n`;
+    const next = upsertEnv(env, "OKE_AI_URL", "http://127.0.0.1:8080/v1", { comment: true });
+    expect(next).toContain("# OKE_AI_URL=http://127.0.0.1:8080/v1");
+    expect(next).not.toMatch(/^OKE_AI_URL=/m);
+  });
+
+  test("upsertEnv writes API token when provided", () => {
+    const env = `# OKE_AI_DRIVER=mock\n`;
+    expect(upsertEnv(env, "OPENAI_API_KEY", "sk-test")).toContain("OPENAI_API_KEY=sk-test");
+  });
+
   test("renderAiTs includes vision + embed", () => {
     const ts = renderAiTs({
       driver: "ollama",
@@ -82,7 +99,7 @@ describe("apply", () => {
     expect(ts).toContain("docsEmbed");
   });
 
-  test("applyAiSetup writes config, env, ai.ts", () => {
+  test("applyAiSetup writes config, env, core/ai.ts", () => {
     const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-"));
     try {
       writeFileSync(
@@ -119,14 +136,17 @@ export default defineConfig({
 
       const config = readFileSync(join(dir, "oke.config.ts"), "utf8");
       expect(config).toContain('local: "ollama"');
-      expect(config).toContain('ai: "ollama/ollama:latest"');
+      expect(config).toContain('ai: "ollama/ollama:0.32.6"');
       const env = readFileSync(join(dir, ".env.local"), "utf8");
-      expect(env).toContain("OKE_AI_DRIVER=ollama");
-      expect(env).toContain("OKE_AI_MODEL=gemma4:e4b");
-      const aiTs = readFileSync(join(dir, "src", "ai.ts"), "utf8");
+      expect(env).toContain("# OKE_AI_DRIVER=ollama");
+      expect(env).toMatch(/^OKE_AI_MODEL=gemma4:e4b$/m);
+      expect(env).not.toMatch(/^#\s*OKE_AI_MODEL=gemma4:e4b$/m);
+      expect(env).toContain("# OKE_AI_URL=http://127.0.0.1:11434");
+      expect(env).not.toMatch(/^OKE_AI_URL=/m);
+      const aiTs = readFileSync(join(dir, "src", "core", "ai.ts"), "utf8");
       expect(aiTs).toContain("smart");
       const app = readFileSync(join(dir, "src", "app.ts"), "utf8");
-      expect(app).toContain('import "./ai"');
+      expect(app).toContain('import "./core/ai"');
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }