okengine 0.10.2 → 0.11.0

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

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

@@ -4,7 +4,7 @@ description: "Every environment variable OKE reads — connection URLs, driver o
 icon: "Terminal"
 ---
 
-OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. In docker mode these are written for you into `docker/.env.docker`; this page is the full map.
+OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `docker/.env.docker`; this page is the full map.
 
 <Callout title="Precedence">
   For anything with both an `OKE_*` variable and a conventional one (like `DATABASE_URL`), the
@@ -13,15 +13,15 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## SQL store
 
-| Variable            | Used for                                                                                                                                        | Default when unset              |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
-| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal drivers, drizzle-kit). When PgDog is in the stack, this points at the pooler (`:6432`). | `postgres://localhost:5432/oke` |
-| `OKE_STORE_SQL_URL` | Direct SQL URL (Postgres host, even when PgDog fronts the app)                                                                                  | —                               |
-| `OKE_PGDOG_URL`     | PgDog pooler URL (same value as `DATABASE_URL` when both are present)                                                                           | —                               |
-| `OKE_SQLITE_URL`    | SQLite file path (`sqlite` driver)                                                                                                              | `.oke/app.sqlite`               |
-| `OKE_LIBSQL_URL`    | libSQL URL or file path (`libsql` driver)                                                                                                       | `.oke/app.libsql`               |
-| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver)                                                                                                | `.oke/pgdata`                   |
-| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                                                                                                 | config map                      |
+| Variable            | Used for                                                                                                                                                                                                                                                          | Default when unset                        |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `DATABASE_URL`      | Postgres connection (`postgres` store / clock / journal / Console operator plane, drizzle-kit). App tables stay in `public`; Console operators/sessions use schema `oke_console` on the same database. When PgDog is pinned, this points at the pooler (`:6432`). | `postgres://localhost:5432/oke`           |
+| `OKE_STORE_SQL_URL` | Direct SQL URL (Postgres host, even when PgDog fronts the app). Also used by Console when `DATABASE_URL` is unset.                                                                                                                                                | —                                         |
+| `OKE_PGDOG_URL`     | PgDog pooler URL (same value as `DATABASE_URL` when both are present)                                                                                                                                                                                             | —                                         |
+| `OKE_PGLITE_URL`    | PGlite data dir or `memory://` (`pglite` driver; required for `store.sql.test`)                                                                                                                                                                                   | `memory://` in `test`; else `.oke/pgdata` |
+| `OKE_SQL_DRIVER`    | Force the sql driver id at boot                                                                                                                                                                                                                                   | config map                                |
+
+`oke test` sets `OKE_PGLITE_URL=memory://` when unset. The `sqlite` driver and `OKE_SQLITE_URL` are removed.
 
 ## Index store
 
@@ -52,15 +52,19 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 | `OKE_STORE_FILES_DB`   | Explicit files location override | —                  |
 | `OKE_FILES_DRIVER`     | Force the files driver id        | config map         |
 
-## Vault (OpenBao)
+## Vault
 
-Written by the first-boot bootstrap; you normally only set these when pointing at an external vault.
+Built-in store uses `OKE_VAULT_MASTER_KEY` (or `--key` / stdin on CLI). Managed AWS Secrets Manager
+uses the provider + region vars below.
 
-| Variable          | Used for                    | Default when unset |
-| ----------------- | --------------------------- | ------------------ |
-| `OKE_VAULT_URL`   | OpenBao base URL            | —                  |
-| `OKE_VAULT_TOKEN` | App token (least-privilege) | —                  |
-| `OKE_VAULT_MOUNT` | KV v2 mount path            | `"secret"`         |
+| Variable               | Used for                                     | Default when unset    |
+| ---------------------- | -------------------------------------------- | --------------------- |
+| `OKE_VAULT_PROVIDER`   | Managed backend (`aws-secrets-manager`)      | — (platform-injected) |
+| `OKE_VAULT_REGION`     | Cloud region for AWS Secrets Manager         | —                     |
+| `OKE_VAULT_MOUNT`      | Secret-name prefix for AWS SM (`oke/prod/`)  | —                     |
+| `OKE_VAULT_MASTER_KEY` | Built-in vault master key (base64)           | —                     |
+| `OKE_VAULT_URL`        | Optional remote URL for community adapters   | —                     |
+| `OKE_VAULT_TOKEN`      | Optional remote token for community adapters | —                     |
 
 ## Channel (email) — boot binder
 
@@ -115,24 +119,28 @@ provider's real credentials — credentials alone never send.
 | `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_DRIVER`       | Force the AI driver id (honoured under Compose / `oke dev`)                                             | 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_MODEL`        | Default model id — Docker Hub `ai/` for llama.cpp; Ollama library tag for ollama; HF id for vLLM/SGLang | `granite3.3:2b` (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
 
-| Variable              | Used for                                                      |
-| --------------------- | ------------------------------------------------------------- |
-| `OKE_DOCKER`          | `"1"` marks docker mode (set by the CLI, not by you)          |
-| `OKE_DB_AUTO_PUSH`    | Overrides `db.autoPush` at boot                               |
-| `OKE_DRIZZLE_DIALECT` | `"sqlite"` \| `"postgresql"` for generated drizzle config     |
-| `OKE_DEV_REQUEST_LOG` | `"1"` logs requests during `oke dev` (set by the CLI)         |
-| `OKE_CONSOLE_SECRET`  | Console session secret — set explicitly in production         |
-| `PORT`                | App port in production containers (default `6530`)            |
-| `NODE_ENV`            | `"production"` switches the Console to its production posture |
+| Variable              | Used for                                                                                   |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| `OKE_DOCKER`          | `"1"` marks Compose / `oke dev` posture (set by the CLI)                                   |
+| `OKE_DB_AUTO_PUSH`    | Overrides `db.autoPush` at boot                                                            |
+| `OKE_DRIZZLE_DIALECT` | `"postgresql"` for drizzle-kit overlays (templates hardcode it)                            |
+| `OKE_DEV_REQUEST_LOG` | `"1"` logs requests during `oke dev` (set by the CLI)                                      |
+| `OKE_CONSOLE_SECRET`  | Console session signing secret — set explicitly in production (else `.oke/console.secret`) |
+| `PORT`                | App port in production containers (default `6530`)                                         |
+| `NODE_ENV`            | `"production"` switches the Console to its production posture                              |
+
+Console operator rows are **not** stored in `.oke/console.sqlite`. With `DATABASE_URL` (or
+`OKE_STORE_SQL_URL`) they live in Postgres schema `oke_console`. Without a Postgres URL,
+Console uses PGlite under `.oke/console-pg` for local reopen durability.
 
 ## Learn more