okengine 0.10.3 → 0.11.1

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

@@ -5,7 +5,7 @@ icon: "Database"
 source: "docs/spec/unified-theory.md"
 ---
 
-Postgres is the default `store.sql` image in docker and prod. `oke docker` matches
+Postgres is the default `store.sql` image in `dev` and `prod`. `oke docker` matches
 any image whose reference contains `postgres` or `pgvector` (after more specific
 recipes), then derives env, healthcheck, and connection URL.
 
@@ -33,7 +33,7 @@ images: {
 ### Bring the stack up
 
 ```bash
-oke dev --docker
+oke dev
 ```
 
 `oke docker` writes `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` into
@@ -105,7 +105,7 @@ Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exha
 <Accordion title="oke boot: postgres driver needs DATABASE_URL">
 
 The `postgres` driver fails boot when neither `DATABASE_URL` nor `OKE_STORE_SQL_URL` is
-set. Re-run `oke dev --docker` so the stack writes `docker/.env.docker`, or export
+set. Re-run `oke dev` so the stack writes `docker/.env.docker`, or export
 `DATABASE_URL` yourself when pointing at a managed host.
 
 </Accordion>

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

@@ -5,7 +5,7 @@ icon: "Zap"
 source: "docs/spec/unified-theory.md"
 ---
 
-Redis is the default `store.kv` image in docker and prod. `oke docker` matches image
+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.
 
@@ -99,7 +99,7 @@ Multi-replica Gate rate counters and Signal need a **shared** Redis URL — an i
 <Accordion title="oke boot: redis driver needs REDIS_URL">
 
 Missing `REDIS_URL` fails boot loudly — never a silent fallback to `memory`. Re-run
-`oke dev --docker` or export `REDIS_URL` when using a managed host. In docker mode the
+`oke dev` or export `REDIS_URL` when using a managed host. Under Compose the
 message asks whether `oke dev -d` wrote `docker/.env.docker`.
 
 </Accordion>

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

@@ -5,9 +5,8 @@ icon: "HardDrive"
 source: "docs/spec/unified-theory.md"
 ---
 
-RustFS is the default docker `store.files` image — an Apache-2.0 S3-compatible object
-store (MinIO alternative). Driver id stays `s3`; Bun binds `Bun.S3Client` against the
-endpoint.
+RustFS is the default `oke dev` / prod `store.files` image — an Apache-2.0 S3-compatible
+object store. Driver id stays `s3`; Bun binds `Bun.S3Client` against the endpoint.
 
 <Callout title="The one rule">
   Protocol name is `s3` — vendor choice is the image pin (`rustfs/rustfs:…`) plus `S3_ENDPOINT`.
@@ -24,11 +23,11 @@ endpoint.
 ```typescript title="oke.config.ts"
 drivers: {
   store: {
-    files: { local: "fs", docker: "s3", test: "memory", prod: "s3" },
+    files: { dev: "s3", test: "memory", prod: "s3" },
   },
 },
 images: {
-  "store.files": "rustfs/rustfs:1.0.0-beta.11",
+  store: { files: "rustfs/rustfs:1.0.0-beta.11" },
 },
 ```
 
@@ -116,7 +115,7 @@ the recipe enables the console for local ops.
 <Accordion title="oke boot: redis / meilisearch / S3 URL missing — S3_BUCKET">
 
 Files on the `s3` driver need `S3_BUCKET` (or `OKE_STORE_FILES_DB`). Without it the
-facet cannot open. Re-run `oke dev --docker` so stack env fills `S3_*`, or export them
+facet cannot open. Re-run `oke dev` so stack env fills `S3_*`, or export them
 for a managed bucket.
 
 </Accordion>
@@ -143,6 +142,10 @@ running service; confirm health at `/health` before debugging client signatures.
     description="SMTP catcher for the same stack."
     href="/docs/recipes/mailpit"
   />
-  <Card title="OpenBao" description="Vault for secrets." href="/docs/recipes/openbao" />
+  <Card
+    title="Vault"
+    description="Secrets and built-in encrypted store."
+    href="/docs/elements/vault"
+  />
   <Card title="Store" description="Files facet details." href="/docs/elements/store" />
 </Cards>

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

@@ -23,7 +23,7 @@ production apps. For general multi-user serving, prefer [vLLM](/docs/recipes/vll
 
 ```typescript title="oke.config.ts"
 drivers: {
-  ai: { docker: "openai-compatible", prod: "openai-compatible", test: "mock" },
+  ai: { dev: "openai-compatible", test: "mock", prod: "openai-compatible" },
 },
 images: {
   ai: "lmsysorg/sglang:v0.5.16-runtime", // never :latest

package/site/content/docs/recipes/supabase-docker.mdx

@@ -44,7 +44,7 @@ refs from `OKE_STORE_SQL_*`. Driver id stays `postgres`.
 ```typescript
 drivers: {
   store: {
-    index: { local: "memory", docker: "pgvector", prod: "pgvector" },
+    index: { test: "memory", prod: "pgvector" },
   },
 },
 ```

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

@@ -33,7 +33,7 @@ images: {
 ### Bring the stack up
 
 ```bash
-oke dev --docker
+oke dev
 ```
 
 Same credential contract as [Postgres](/docs/recipes/postgres):
@@ -104,7 +104,7 @@ re-derive, then `CREATE EXTENSION timescaledb`.
 </Accordion>
 <Accordion title="oke boot: postgres driver needs DATABASE_URL">
 
-Same as Postgres — re-run `oke dev --docker` or export `DATABASE_URL` for a remote
+Same as Postgres — re-run `oke dev` or export `DATABASE_URL` for a remote
 host.
 
 </Accordion>

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

@@ -90,7 +90,7 @@ see [DigitalOcean Managed Caching](/docs/providers/digitalocean-caching).
 <Accordion title="oke boot: redis driver needs REDIS_URL">
 
 Same loud failure as Redis — the driver id is still `redis`. Export `REDIS_URL` or let
-`oke dev --docker` write it.
+`oke dev` write it.
 
 </Accordion>
 <Accordion title="Healthcheck uses redis-cli and fails">

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

@@ -23,7 +23,7 @@ you choose to self-host inference instead of a managed provider. Driver id stays
 
 ```typescript title="oke.config.ts"
 drivers: {
-  ai: { docker: "openai-compatible", prod: "openai-compatible", test: "mock" },
+  ai: { dev: "openai-compatible", test: "mock", prod: "openai-compatible" },
 },
 images: {
   ai: "vllm/vllm-openai:v0.26.0", // never :latest

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

@@ -33,7 +33,7 @@ images: {
 ### Bring the stack up
 
 ```bash
-oke dev --docker
+oke dev
 ```
 
 `oke docker` injects `YSQL_USER` / `YSQL_PASSWORD` / `YSQL_DB` from `OKE_STORE_SQL_*`
@@ -105,7 +105,7 @@ Receiver or remap that port in `compose.override.yml` if you need the UI.
 <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
+`oke dev`. Auth is off only when `YSQL_PASSWORD` is unset — this recipe
 always sets it.
 
 </Accordion>

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

@@ -11,34 +11,41 @@ source: "docs/cli.md"
 bun add okengine                 # ONE package (project)
 bun install -g okengine          # global `oke` on PATH
 
+oke                              # interactive TUI (TTY) — Dashboard · Dev · Database · Docker · Navigator
+oke --tui                        # force TUI even when other args were passed
+oke --help                       # command list (also what bare `oke` prints when non-TTY / CI)
+
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535 · docs MCP :6536
-                                 #   → client types + domain schema push on save (local)
-oke dev --local                  # -l  session-only local (in-memory; never writes .oke/mode)
+                                 #   → always Docker Compose under docker/ + host Bun
+                                 #   → client types + domain schema push on save
 oke dev --no-db-push             #     opt out of auto oke db push on schema input save
-oke dev --docker                 # -d  infra compose under docker/ (no app container; host Bun)
-                                 #     Ctrl-C / close terminal → docker compose stop (volumes kept)
-oke dev -d store.sql,signal      #     partial: only these roles get real backends
-oke mode local|docker            # get/set default oke dev mode (saved in .oke/mode)
+oke dev -d store.sql,signal      #     optional role filter (still Compose; requires Docker)
+oke test                         # bun test with PGLite posture (NODE_ENV=test, OKE_PGLITE_URL=memory://)
+                                 #   → does not start Docker Compose
+oke mode                         # removed — prints error; use oke dev (Compose) / oke test (PGLite)
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
 oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
 oke stack                        # preview resolved images/tags/ports — writes nothing
 
-oke schema generate              # core + plugin stubs → schema/oke.ts   (--check in CI)
-oke db push                      # domain schema.ts → live local DB (dev; drizzle-kit)
+oke schema generate              # core + plugin stubs → .oke/schema/oke.ts (--check in CI)
+oke db push                      # domain schema.ts → live DB (dev; drizzle-kit)
 oke db generate                  # versioned SQL under drizzle/ (review)
 oke db migrate                   # apply migrations (explicit; never auto in prod)
 oke db seed                      # defineSeed (essential + env category); never at boot
-oke db seed --env prod --force   # CI: skip docker/prod confirmation prompt
+oke db seed --env prod --force   # CI: skip prod confirmation prompt
+oke db studio                    # drizzle-kit Studio (long-running)
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
 oke client add <url>             # types for a separate frontend repo
 
-oke docker                       # docker/Dockerfile + compose.yml + compose.<role>.yml + compose.all.yml · …
-                                 # opt-in images.proxy → Caddyfile (caddy) or Traefik labels + socket-proxy
-oke docker --prod                # + compose.prod.yml (HEALTHCHECK /_/ready, deploy, limits); folded into compose.all.yml
-oke docker clean                 # TTY: pick oke-dev-* stacks → down -v (containers, networks, volumes)
-oke docker clean --yes           # non-TTY: current project stack only
-oke docker clean --all --yes     # non-TTY: every oke-dev-* stack on this machine
+oke docker                       # docker/Dockerfile + docker-compose.yml (prod-grade; 4 CPU / 8 GiB budget)
+oke docker --split               # layered compose.yml + compose.<role>.yml + compose.prod.yml
+oke docker --stack               # docker-stack.yml for docker stack deploy
+oke docker --cpus 8 --memory 16  # override host budget used for deploy.resources
+oke docker --no-prod             # skip readiness / deploy / resource budget
+oke docker clean                 # TTY: pick oke-dev-* projects → down -v (containers, networks, volumes)
+oke docker clean --yes           # non-TTY: current project only
+oke docker clean --all --yes     # non-TTY: every oke-dev-* project on this machine
 oke images pin                   # tags → digests in oke.images.lock
 
 oke build --target edge          # < 15 kB kernel profile
@@ -58,20 +65,31 @@ In development, app, Console, MCP, and docs MCP prefer the canonical ports and m
 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) — it already
-lists every service, so refresh is enough to see the stack; there is no
-separate services panel. Press `r` to clear the log pane and reprint the
-latest board. `?` also refreshes first so the help panel is not mixed into
-request logs.
+Bare `oke` on a TTY opens an Ink interactive shell (optional deps `ink` +
+`react`). The viewport is cleared before render so boot logs never sit above the
+frame. Chrome matches `oke dev`: green OKE wordmark on Dashboard, green active
+tabs, cyan focus rows. Panels cover live ports (App / Console / MCP / Docs MCP),
+Dev start/stop/attach with live logs, Database action cards (including Studio),
+Docker compose status, and a Manifest navigator. **Tab** / **←→** (on the tab
+strip) switch panels; **↑↓** navigate inside a panel; **Esc** returns to the tab
+strip, then confirms quit when a managed `oke dev` is running; **1–5** jump
+panels from any focus. Press `/` for the **command palette** (Tab autofill,
+Enter runs `oke …`; status shows in the global footer). If `oke dev` is already
+running, the TUI shows **Connected** via `.oke/dev.json` + port probes and will
+not spawn a second stack. Non-TTY / CI keeps the classic help listing
+(`EXIT_USAGE`).
+
+`oke dev` always starts Compose (requires a running Docker daemon). Boot chrome
+prints immediately (wordmark + Starting + profile), then streams background work
+(compose up, vault, per-service health, AI probe). Status ● is green ready ·
+yellow pending/loading · red error · dim idle. Compose health keeps polling
+(`docker compose ps -a`); AI ● tracks model phase while the AI container is up.
+Boot does not wait for the model to become ready. A successful session writes
+`.oke/dev.json` (pid · ports · startedAt) and clears it on stop.
+
+On a TTY, Ink keyboard controls stay active after boot (`useInput` — same
+shortcuts as before). Press `r` to clear the log pane and reprint the latest
+board.
 
 | Key       | Action                              |
 | --------- | ----------------------------------- |
@@ -83,6 +101,12 @@ request logs.
 Compose stays quiet unless it fails. Process-local boot notices print once under
 the hero (not once per process).
 
+`oke test` sets `NODE_ENV=test` and `OKE_PGLITE_URL=memory://` when unset, checks
+that `@electric-sql/pglite` resolves, then forwards argv to `bun test`.
+
+`oke mode` and `oke dev --local` / `-l` are removed — they exit with an error.
+See [Migrating environments](/docs/reference/migrating-environments).
+
 ### create-oke
 
 ```bash
@@ -95,13 +119,10 @@ 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 (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.
+customize. Customize walks **Docker-first** facets once (including `store.index`
+with a `none` opt-out), then **AI setup**: Recommended (llama.cpp) · Customize ·
+Off. Writes user-global `~/.oke/create-defaults.json` (reuse only when `template`
+matches). Non-TTY / `--yes` / explicit `--template` never prompt.
 
 ### Additional commands
 
@@ -132,8 +153,7 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 
 | Long                 | Short | Where                                          |
 | -------------------- | ----- | ---------------------------------------------- |
-| `--local`            | `-l`  | `dev`                                          |
-| `--docker`           | `-d`  | `dev`                                          |
+| `--docker`           | `-d`  | `dev` (optional Compose **role filter**)       |
 | `--no-db-push`       |       | `dev`                                          |
 | `--prod`             | `-p`  | `docker`                                       |
 | `--yes`              | `-y`  | `docker clean`                                 |
@@ -156,6 +176,9 @@ Long form is canonical in docs; short form is convenience only. Shared letters f
 | `--subject`          | `-s`  | `privacy erase`                                |
 | `--before`           | `-b`  | `doctor --diff`                                |
 | `--base`             | `-B`  | `doctor --diff`                                |
+| `--env`              |       | `db *` (`dev` \| `test` \| `prod`)             |
+| `--force`            |       | `db seed`                                      |
+| `--local` / `-l`     |       | **removed** on `dev` (use `oke test`)          |
 
 ### Exit codes
 

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

@@ -1,10 +1,10 @@
 ---
 title: "Configuration"
-description: "Every option in oke.config.ts — drivers per environment, images, i18n, tenancy, privacy, db sync, topology, ports, and console."
+description: "Every option in oke.config.ts — three environments (dev · test · prod), drivers, images, i18n, tenancy, privacy, db sync, topology, ports, and console."
 icon: "Settings2"
 ---
 
-Complete reference for `oke.config.ts`. Every option below is verified against `defineConfig`; the four environment keys everywhere are `local` · `docker` · `test` · `prod`.
+Complete reference for `oke.config.ts`. Options below match `defineConfig`. Driver maps use three keys: **dev** · **test** · **prod**.
 
 ```typescript title="oke.config.ts"
 import { defineConfig } from "okengine/config";
@@ -14,38 +14,104 @@ export default defineConfig({
 });
 ```
 
-## drivers
+<Callout title="Philosophy">
+  We test on what we deploy. Local development runs the same stack as production via Docker. Tests
+  use PGLite for speed without sacrificing Postgres correctness.
+</Callout>
 
-Which backend each element talks to, per environment. A value is either a driver id string or a rich object:
+## Environments
+
+| Key    | When                       | Typical backends                                      |
+| ------ | -------------------------- | ----------------------------------------------------- |
+| `dev`  | `oke dev` (Docker Compose) | Same protocols as prod (Postgres, Redis, S3, SMTP, …) |
+| `test` | `oke test` / `bun test`    | PGLite for SQL; memory / frozen / console elsewhere   |
+| `prod` | Production deploy          | Shared durable backends                               |
+
+Missing `dev` pins fill from `prod` (`fillDevFromProd`). Only `dev` / `test` / `prod` keys are
+valid — see [Migrating environments](/docs/reference/migrating-environments) if you still have
+`local` / `docker` maps.
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin drivers for three envs
+
+Pin **only the env keys that differ** from the built-in defaults — omitted keys
+keep `DRIVER_DEFAULTS`. create-oke templates ship that sparse shape:
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    // Default vault.dev is "env"; pin the built-in store for Docker-first apps.
+    vault: { dev: "vault" },
+  },
+});
+```
+
+</Step>
+
+<Step>
+### Or use a string shorthand
+
+A bare string (or `{ driver, … }` object) expands to all three envs:
 
 ```typescript
 drivers: {
-  store: {
-    sql: { local: "sqlite", docker: "postgres", test: "memory", prod: "postgres" },
-    kv: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
-    files: { local: "fs", docker: "s3", test: "memory", prod: "s3" },
-  },
-  signal: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
-  clock: { local: "memory", docker: "postgres", test: "frozen", prod: "postgres" },
-  journal: { local: "memory", docker: "postgres", test: "memory", prod: "postgres" },
-  vault: { local: "env", docker: "openbao", test: "memory", prod: "openbao" },
-  channel: {
-    email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
-    sms: { local: "console", docker: "taqnyat", test: "console", prod: "taqnyat" },
-  },
+  signal: "redis", // → { dev: "redis", test: "redis", prod: "redis" }
 },
 ```
 
-| Key                | Shape          | Driver ids (verified)                                                        |
+Prefer an explicit `{ dev, test, prod }` map (or a partial override) when test
+should differ from the default for that driver.
+
+</Step>
+
+<Step>
+### Run and test
+
+```bash title="Terminal"
+oke dev    # Docker Compose + host Bun · drivers.dev
+oke test   # bun test · NODE_ENV=test · OKE_PGLITE_URL=memory://
+```
+
+</Step>
+
+</Steps>
+
+## Default driver maps
+
+Built-in defaults (`DRIVER_DEFAULTS`) when a key is omitted:
+
+| Map             | `dev`      | `test`    | `prod`     |
+| --------------- | ---------- | --------- | ---------- |
+| `store.sql`     | `postgres` | `pglite`  | `postgres` |
+| `store.kv`      | `redis`    | `memory`  | `redis`    |
+| `store.files`   | `s3`       | `memory`  | `s3`       |
+| `signal`        | `redis`    | `memory`  | `redis`    |
+| `clock`         | `postgres` | `frozen`  | `postgres` |
+| `journal`       | `postgres` | `memory`  | `postgres` |
+| `vault`         | `env`      | `memory`  | `vault`    |
+| `channel.email` | `smtp`     | `console` | `smtp`     |
+| `channel.sms`   | — (opt-in) | —         | —          |
+
+`store.index`, `channel.whatsapp` / `push`, and `ai` have no single three-env default table — set them explicitly when you need them. create-oke templates pin `vault.dev: "vault"` (built-in) because the default `dev` driver is `env`.
+
+## Driver keys and ids
+
+| Key                | Shape          | Driver ids                                                                   |
 | ------------------ | -------------- | ---------------------------------------------------------------------------- |
-| `store.sql`        | env driver map | `sqlite` · `postgres` · `libsql` · `pglite` · `memory`                       |
+| `store.sql`        | env driver map | `postgres` · `pglite` · `memory`                                             |
 | `store.kv`         | env driver map | `memory` · `redis`                                                           |
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector` · `libsql` · `meilisearch`                             |
+| `store.index`      | env driver map | `memory` · `pgvector` · `meilisearch`                                        |
 | `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind  |
 | `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                    |
 | `journal`          | env driver map | `memory` · `file` · `postgres`                                               |
-| `vault`            | env driver map | `env` · `openbao` · `memory` · `managed`                                     |
+| `vault`            | env driver map | `env` · `vault` · `memory` · `managed`                                       |
 | `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                      |
 | `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                |
 | `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                       |
@@ -54,7 +120,14 @@ drivers: {
 | `runs`             | env driver map | runs-store driver (distinct from top-level `runs`)                           |
 | `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred              |
 
-When `docker` is omitted it inherits the `prod` driver. The rich object form adds connection detail:
+### Safety rules
+
+`defineConfig` rejects unsafe pins:
+
+- **`sqlite` is removed** — use `postgres` (dev/prod) or `pglite` (test).
+- **`drivers.store.sql.test` must be `pglite`** when set — real Postgres semantics in tests.
+
+### Rich driver objects
 
 ```typescript
 sql: {
@@ -70,59 +143,41 @@ sql: {
 
 ## images
 
-Container image pins keyed by element role — vendor choice lives here, never in driver ids:
+Nested pins by element role — vendor choice lives here, never in driver ids:
 
 ```typescript
 images: {
-  "store.sql": "postgres:18",
+  store: {
+    sql: "postgres:18-alpine",
+    kv: "redis:8-alpine",
+    files: "rustfs/rustfs:1.0.0-beta.11",
+  },
+  channel: { email: "axllent/mailpit:v1.22.3" },
   pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
-  "store.kv": "redis:8",
-  // or: "valkey/valkey:8-alpine"
-  // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
-  "store.files": "rustfs/rustfs:1.0.0-beta.11",
-  "channel.email": "axllent/mailpit:v1.22.3",
-  vault: "openbao/openbao:2.6.1",
-  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
+  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10290",
+  // proxy: "caddy:2-alpine",
 },
 ```
 
-When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog
-(`6432`) — wire-protocol transparent to Bun.SQL / Drizzle. See
-[Store · Multiple environments](/docs/elements/store#multiple-environments).
-
-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`, 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).
+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 `proxy`, pin **either** Caddy or Traefik — never both. Opt-in only; see
-[Reverse proxy](/docs/deployment/reverse-proxy).
+For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`. For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
 
 ## i18n
 
-| Option    | Type       | Default | Meaning                                     |
-| --------- | ---------- | ------- | ------------------------------------------- |
-| `locales` | `string[]` | —       | Supported locales                           |
-| `default` | string     | —       | Fallback locale (channel templates, `fx.t`) |
-| `dir`     | record     | —       | Per-locale direction: `"ltr"` \| `"rtl"`    |
+| Option    | Type       | Default               | Meaning                                     |
+| --------- | ---------- | --------------------- | ------------------------------------------- |
+| `locales` | `string[]` | `["en"]` when omitted | Supported locales                           |
+| `default` | string     | `"en"` when omitted   | Fallback locale (channel templates, `fx.t`) |
+| `dir`     | record     | —                     | Per-locale direction: `"ltr"` \| `"rtl"`    |
 
 ```typescript
-i18n: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } },
+i18n: { locales: ["en"], default: "en" },
+// or with Arabic: { locales: ["en", "ar"], default: "en", dir: { ar: "rtl" } }
 ```
 
-`fx.t` catalogs are ICU strings from `defineLocale` / `defineMessages` — see
-[i18n](/docs/reference/i18n). Built-ins also cover failure `error.message` and
-OKE cause/fix; Channel templates keep separate `locales` + `{{field}}` bodies.
-
 ## tenancy
 
-Multi-tenant isolation policy.
-
 | Option      | Type                              | Meaning                                  |
 | ----------- | --------------------------------- | ---------------------------------------- |
 | `isolation` | `"row" \| "schema" \| "database"` | How tenants are separated in the store   |
@@ -130,7 +185,7 @@ Multi-tenant isolation policy.
 
 ## privacy
 
-Presence of this block turns the CORE privacy tooling on in the Console — masking, classification surfaces. It is not a `.plug()` call.
+Presence of this block turns CORE privacy tooling on in the Console — not a `.plug()` call.
 
 ```typescript
 privacy: {},
@@ -138,7 +193,7 @@ privacy: {},
 
 ## runs
 
-Runs retention and redaction at the config surface — **not** the same key as `drivers.runs`.
+Runs retention and redaction — **not** the same key as `drivers.runs`.
 
 | Option   | Type                     | Meaning                                               |
 | -------- | ------------------------ | ----------------------------------------------------- |
@@ -148,13 +203,13 @@ Runs retention and redaction at the config surface — **not** the same key as `
 
 Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated to `oke schema generate`.
 
-| Option      | Default                     | Meaning                                                                                                           |
-| ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `autoPush`  | `true` (local only)         | Auto-run `db push` when schema inputs change in `oke dev` (not on emit of `generated`); forced off in docker/prod |
-| `config`    | `"drizzle.config.ts"`       | Path to the drizzle-kit config                                                                                    |
-| `declare`   | `"src/schema.decl.ts"`      | Abstract schema module (`store.schema.table` exports)                                                             |
-| `generated` | `"src/schema.generated.ts"` | Where `oke db` emits dialect Drizzle                                                                              |
-| `entry`     | `src/app.ts`                | App entry for collecting plugin table contributions                                                               |
+| Option      | Default                      | Meaning                                                                   |
+| ----------- | ---------------------------- | ------------------------------------------------------------------------- |
+| `autoPush`  | `true`                       | Auto-run `db push` on schema change under `oke dev`; forced off in `prod` |
+| `config`    | `"drizzle.config.ts"`        | Path to the drizzle-kit config                                            |
+| `declare`   | `"src/db/schema.decl.ts"`    | Abstract schema module (`store.schema.table` exports)                     |
+| `generated` | `"src/db/schema.drizzle.ts"` | Where `oke db` emits dialect Drizzle                                      |
+| `entry`     | `src/app.ts`                 | App entry for collecting plugin table contributions                       |
 
 ## topology
 
@@ -173,15 +228,35 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 ## console
 
-Production Console exposure.
-
 | Option         | Type                                 | Default | Meaning                   |
 | -------------- | ------------------------------------ | ------- | ------------------------- |
 | `prod.enabled` | boolean                              | —       | Serve the Console in prod |
 | `prod.auth`    | `"required" \| "optional" \| "none"` | —       | Access requirement        |
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title='oke.config: … uses removed driver "sqlite"'>
+  The `sqlite` driver is gone. Pin `postgres` for `dev`/`prod` and `pglite` for `test`. Edit the
+  file by hand — see [Migrating environments](/docs/reference/migrating-environments).
+</Accordion>
+
+<Accordion title='drivers.store.sql.test must be "pglite"'>
+  Tests use PGLite so SQL semantics match Postgres. Set `test: "pglite"` (or omit the key and keep
+  the default). Do not use `memory` or `postgres` for `store.sql.test`.
+</Accordion>
+
+<Accordion title='CLI error: "local" / "sqlite" is no longer valid'>
+  There is no soft-compat. Rename env keys to `dev` / `test` / `prod` and replace `sqlite` with
+  `postgres` / `pglite`. `oke mode` was removed — `oke dev` always starts Docker Compose.
+</Accordion>
+
+</Accordions>
+
 ## Learn more
 
-- [CLI Reference](/docs/reference/cli) — `oke dev` · `oke db` · `oke docker`
+- [Migrating environments](/docs/reference/migrating-environments) — four-key maps → `dev`/`test`/`prod`
+- [CLI Reference](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
 - [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
 - [Store](/docs/elements/store) — what the store drivers back