okengine 0.10.3 → 0.11.0

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

@@ -186,7 +186,7 @@ await fx.store(db).delete(notes).where(lt(notes.createdAt, cutoff));
 
 ### Schema — declare once, generate per dialect
 
-The recommended path: declare tables ORM-agnostically, then let `oke db` emit real Drizzle for the active dialect (`sqliteTable` locally, `pgTable` in docker/prod) into `src/schema.generated.ts`.
+The recommended path: declare tables ORM-agnostically, then let `oke db` emit real Drizzle (`pgTable` for Postgres / PGLite) into `src/db/schema.drizzle.ts`.
 
 | Field API                                    | Meaning                                         |
 | -------------------------------------------- | ----------------------------------------------- |
@@ -232,28 +232,28 @@ export const relations = store.schema.relations({ links, daily }, (r) => ({
 | `oke db generate` | Write versioned SQL under `drizzle/` for review                |
 | `oke db migrate`  | Apply those files — human or CI, **never** at boot             |
 
-`oke dev` (local) auto-pushes when you save a schema _input_ (`schema.decl.ts`,
+`oke dev` auto-pushes when you save a schema _input_ (`schema.decl.ts`,
 hand-written `schema.ts`, `app.ts` for plugin tables, or `drizzle.config.ts`) —
-not when emit rewrites `schema.generated.ts`.
+not when emit rewrites `schema.drizzle.ts`.
 
-Opt out with `--no-db-push` or `db: { autoPush: false }`. Docker/prod **never**
-auto-apply DDL; a missing table fails as **OKE1101** (`oke db migrate`).
+Opt out with `--no-db-push` or `db: { autoPush: false }`. `prod` **never**
+auto-applies DDL; a missing table fails as **OKE1101** (`oke db migrate`).
 
 #### Multiple environments
 
-Local can `oke db push` freely — safe to wipe and regenerate.
+`dev` can `oke db push` freely — safe to wipe and regenerate.
 
 Staging/prod accumulate versioned SQL under `drizzle/` (`oke db generate`).
 `oke db migrate` applies only unrecorded files in order — behind DBs catch up.
 
 | Environment    | Sync                                                           |
 | -------------- | -------------------------------------------------------------- |
-| Local          | `oke db push` (or auto-push from `oke dev`)                    |
+| `dev`          | `oke db push` (or auto-push from `oke dev`)                    |
 | Staging / prod | `oke db generate` → review files → `oke db migrate` on that DB |
 
 <Callout title="Connection pooling is infrastructure, not app code" type="info">
   Bun.SQL defaults to **10** connections per process — fine per instance. Scale out and `N × pool`
-  can exceed Postgres `max_connections`. docker/prod puts **PgDog** in front; `DATABASE_URL` → port
+  can exceed Postgres `max_connections`. `dev`/`prod` put **PgDog** in front; `DATABASE_URL` → port
   `6432`. No app code changes.
 </Callout>
 
@@ -272,15 +272,13 @@ Seed proves existence (bootstrap rows); it does not correct schema-adjacent data
 
 <StoreSeeding />
 
-| env      | `essential` | `dev` | `prod` |
-| -------- | ----------- | ----- | ------ |
-| `local`  | yes         | yes   | no     |
-| `docker` | yes         | yes   | no     |
-| `test`   | yes         | no    | no     |
-| `prod`   | yes         | no    | yes    |
+| env    | `essential` | `dev` | `prod` |
+| ------ | ----------- | ----- | ------ |
+| `dev`  | yes         | yes   | no     |
+| `test` | yes         | no    | no     |
+| `prod` | yes         | no    | yes    |
 
-`docker` is a laptop profile with prod-shaped drivers — still development, so `dev` runs.
-Outside `test`, exactly one of `dev` / `prod` runs with `essential`.
+Outside `test`, exactly one of seed-category `dev` / `prod` runs with `essential`.
 
 **Simple form** — everything inline:
 
@@ -367,14 +365,14 @@ await fx.store(db).upsert(
 is for seed-owned rows you intentionally overwrite. Schema-wide data fixes still belong in
 migrations, not seed.
 
-| Env               | Confirm                                               |
-| ----------------- | ----------------------------------------------------- |
-| `local` / `test`  | none                                                  |
-| `docker` / `prod` | print DB target; type the env name (`--force` for CI) |
+| Env            | Confirm                                               |
+| -------------- | ----------------------------------------------------- |
+| `test`         | none                                                  |
+| `dev` / `prod` | print DB target; type the env name (`--force` for CI) |
 
 ```bash
-oke db seed                 # resolve env like other oke db commands (.oke/mode)
-oke db seed --env docker    # explicit override
+oke db seed                 # resolve env like other oke db commands
+oke db seed --env dev       # explicit override
 oke db seed --env prod --force
 ```
 
@@ -394,27 +392,25 @@ oke db seed --env prod --force
 
 Same flow code, different backends — configured once in `oke.config.ts`:
 
-| Facet | Local    | Docker / prod | Runs as                                 |
-| ----- | -------- | ------------- | --------------------------------------- |
-| `sql` | `sqlite` | `postgres`    | file on disk → container + named volume |
+| Facet | `dev` / `prod` | `test`   | Runs as                                       |
+| ----- | -------------- | -------- | --------------------------------------------- |
+| `sql` | `postgres`     | `pglite` | Compose / deploy Postgres → in-process PGLite |
 
-Defaults: `sqlite` locally, `postgres` in docker/prod, `memory` in test. Container images come from the `images` map — change the vendor by changing the pin, never the driver id.
+Defaults: `postgres` for `dev`/`prod`, `pglite` for `test`. SQLite-family drivers (`sqlite`, `libsql`) are removed. Container images come from the `images` map — change the vendor by changing the pin, never the driver id.
 
 #### Opt-in SQL drivers
 
-Two more `store.sql` drivers cover specific parity needs. Both are optional peers — `bun add` them yourself; neither changes the `sqlite` local default.
+| Driver   | Install                                                  | Wire dialect | Choose for                                                |
+| -------- | -------------------------------------------------------- | ------------ | --------------------------------------------------------- |
+| `pglite` | `@electric-sql/pglite` + `@electric-sql/pglite-pgvector` | postgresql   | **required** for `store.sql.test`; also usable in-process |
 
-| Driver   | Install                                                  | Wire dialect | Choose for                                             |
-| -------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------ |
-| `libsql` | `@libsql/client`                                         | sqlite       | local vector search without Docker (`index: "libsql"`) |
-| `pglite` | `@electric-sql/pglite` + `@electric-sql/pglite-pgvector` | postgresql   | the real Postgres dialect + pgvector, in-process       |
-
-<Callout title="PGlite is not a latency play">
-  PGlite pays a one-time ~1 s WASM init, and warm CRUD is roughly 15× slower than `bun:sqlite`.
-  Choose it for dialect/pgvector parity with prod — never as a faster local default.
+<Callout title="PGlite is the test SQL driver">
+  `defineConfig` requires `drivers.store.sql.test` to be `pglite` when set. Use `oke test` (sets
+  `OKE_PGLITE_URL=memory://`). Choose PGLite for Postgres correctness in tests — not as a Compose
+  substitute for `oke dev`.
 </Callout>
 
-SQL-backed index drivers (`pgvector`, `libsql`) share this facet's connection — see [Advanced — composing facets together](#advanced--composing-facets-together).
+SQL-backed index driver `pgvector` shares this facet's connection — see [Advanced — composing facets together](#advanced--composing-facets-together).
 
 ## KV
 
@@ -470,8 +466,8 @@ Optional third argument on `set` is a duration string: `(\d+)(ms|s|m|h|d)` — e
 
 <StoreKvTtl />
 
-**Consequence:** a TTL you rely on in prod does nothing under the local `memory` driver. Test expiry
-against `redis` (docker) when lifetime matters.
+**Consequence:** a TTL you rely on in prod does nothing under the `test` `memory` driver. Exercise
+expiry against `redis` under `oke dev` when lifetime matters.
 
 ### Examples — what follows from each choice
 
@@ -498,25 +494,25 @@ your Flows and operator tools stay readable.
 ```typescript title="oke.config.ts"
 drivers: {
   store: {
-    kv: { local: "memory", docker: "redis", test: "memory", prod: "redis" },
+    kv: { dev: "redis", test: "memory", prod: "redis" },
   },
 },
 images: {
-  "store.kv": "redis:8-alpine",
+  store: { kv: "redis:8-alpine" },
   // or: "valkey/valkey:8-alpine"
   // or: "docker.dragonflydb.io/dragonflydb/dragonfly"
 },
 ```
 
-| Facet | Local    | Docker / prod | Runs as                |
-| ----- | -------- | ------------- | ---------------------- |
-| `kv`  | `memory` | `redis`       | in-process → container |
+| Facet | `dev` / `prod` | `test`   | Runs as                |
+| ----- | -------------- | -------- | ---------------------- |
+| `kv`  | `redis`        | `memory` | container → in-process |
 
 | Variable           | When                             |
 | ------------------ | -------------------------------- |
 | `REDIS_URL`        | Required for the `redis` driver  |
 | `OKE_STORE_KV_URL` | Override if `REDIS_URL` is unset |
-| `OKE_KV_DRIVER`    | Force a driver id (docker)       |
+| `OKE_KV_DRIVER`    | Force a driver id                |
 
 Missing Redis URL fails boot loudly: `oke boot: redis driver needs REDIS_URL`.
 
@@ -613,28 +609,28 @@ Keys are opaque strings the driver stores as-is. Prefer path-like prefixes (`pho
 ```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" },
 },
 ```
 
-| Facet   | Local | Docker / prod | Runs as                           |
-| ------- | ----- | ------------- | --------------------------------- |
-| `files` | `fs`  | `s3`          | project folder → RustFS container |
+| Facet   | `dev` / `prod` | `test`   | Runs as                  |
+| ------- | -------------- | -------- | ------------------------ |
+| `files` | `s3`           | `memory` | RustFS / S3 → in-process |
 
 | Variable                      | When                                   |
 | ----------------------------- | -------------------------------------- |
 | `S3_BUCKET`                   | Required bucket for the `s3` driver    |
 | `OKE_STORE_FILES_DB`          | Override bucket name                   |
 | `S3_ENDPOINT` · keys · region | S3-compatible endpoint and credentials |
-| `OKE_FILES_DRIVER`            | Force a driver id (docker)             |
+| `OKE_FILES_DRIVER`            | Force a driver id                      |
 
 `memory` is the test default. Local `fs` writes under a temp root when no binding `root` is set.
 
-**Known limit:** `fs` is single-host. Under horizontal scale each replica sees its own filesystem (silently inconsistent object views). Boot prints a one-shot warning when `drivers.store.files` is `fs`. Use `s3` for docker/prod (create-oke templates already do).
+**Known limit:** `fs` is single-host. Under horizontal scale each replica sees its own filesystem (silently inconsistent object views). Boot prints a one-shot warning when `drivers.store.files` is `fs`. Use `s3` for `dev`/`prod` (create-oke templates already do).
 
 <Callout title="Operator tools can browse, not edit bytes">
   Operator tools can list keys and delete them. Direct edit is **KV + SQL only** — blob bodies are
@@ -747,11 +743,10 @@ runtime.
 
 ### Vector ANN
 
-| `store.index` id | Shares connection from     | Real ANN via                         |
-| ---------------- | -------------------------- | ------------------------------------ |
-| `memory`         | — (in-process, default)    | Full scan cosine                     |
-| `pgvector`       | `postgres` or `pglite` sql | HNSW + `cosineDistance`              |
-| `libsql`         | `libsql` sql               | `libsql_vector_idx` + `vector_top_k` |
+| `store.index` id | Shares connection from     | Real ANN via            |
+| ---------------- | -------------------------- | ----------------------- |
+| `memory`         | — (in-process, default)    | Full scan cosine        |
+| `pgvector`       | `postgres` or `pglite` sql | HNSW + `cosineDistance` |
 
 **Consequence:** a configured SQL-backed index that cannot reach its engine — missing peer, missing
 `vector` extension, wrong sql driver — fails loudly at first use. It never silently falls back to
@@ -788,29 +783,27 @@ do: async ({ id, doc, q }, fx) => {
 ```typescript title="oke.config.ts"
 drivers: {
   store: {
-    index: { local: "meilisearch", docker: "meilisearch", prod: "meilisearch" },
+    index: { dev: "meilisearch", test: "memory", prod: "meilisearch" },
   },
 },
 images: {
-  "store.index": "getmeili/meilisearch:v1.37",
+  store: { index: "getmeili/meilisearch:v1.37" },
 },
 ```
 
-- **Local mode** needs the `meilisearch` binary on `PATH` (a documented prerequisite, like Docker for `--docker` — OKE never auto-downloads binaries). `oke dev` spawns it with a generated master key persisted under `.oke/meilisearch/` (`0700`/`0600`).
-- **Docker / prod** uses the image recipe; the app gets `OKE_STORE_INDEX_URL` + `OKE_STORE_INDEX_KEY` from Compose — a standalone HTTP service, never the shared `sqlUrl`.
+- **`oke dev` / prod** use the image recipe; the app gets `OKE_STORE_INDEX_URL` + `OKE_STORE_INDEX_KEY` from Compose — a standalone HTTP service, never the shared `sqlUrl`.
 - **Fail-loud:** a configured meilisearch that is unreachable or unhealthy throws `MeilisearchUnavailableError` — never a silent memory fallback.
 - **Not for vectors:** `ai.embed` / `fx.search` stay vector-only; pointing an embed `into` a meilisearch index fails loud (embeddings don't apply).
-- **Alpine caveat:** the raw glibc binary fails on Alpine/musl _hosts_; the official image is musl-clean. Install the binary for your platform (e.g. Homebrew / install script), or use `--docker`.
 
 ### Per-environment Index drivers
 
-Unlike KV/Files, an unset `drivers.store.index` map stays **`memory` in every environment** — there is no docker fallback to `pgvector`. Opt in explicitly:
+Unlike KV/Files, an unset `drivers.store.index` map stays **`memory` in every environment** — there is no automatic fallback to `pgvector`. Opt in explicitly:
 
 ```typescript title="oke.config.ts"
 drivers: {
   store: {
-    sql: { local: "libsql", docker: "postgres", prod: "postgres" },
-    index: { local: "libsql", docker: "pgvector", prod: "pgvector" },
+    sql: { dev: "postgres", test: "pglite", prod: "postgres" },
+    index: { dev: "pgvector", test: "memory", prod: "pgvector" },
   },
 },
 ```
@@ -831,25 +824,25 @@ target meilisearch.
 
 Facets are independent declarations. A Flow may touch several in one `do` — for example store a files key on a SQL row, or `upsert` into an index after a SQL write. There is no special sync API: `store.resource` `search:` is SQL substring match, not meilisearch.
 
-One real coupling: a SQL-backed index shares the sql facet's already-open connection, so configure the pair together:
+One real coupling: `pgvector` shares the sql facet's already-open connection, so configure the pair together:
 
 ```typescript title="oke.config.ts"
 drivers: {
   store: {
-    sql: { local: "libsql" },
-    index: { local: "libsql" },
+    sql: { dev: "postgres", test: "pglite", prod: "postgres" },
+    index: { dev: "pgvector", test: "memory", prod: "pgvector" },
   },
 },
 ```
 
-Same idea for `pgvector` with `postgres` or `pglite`. The full per-environment map looks like this:
+The full per-environment map looks like this:
 
 ```typescript title="oke.config.ts"
 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" },
+    sql:   { dev: "postgres", test: "pglite", prod: "postgres" },
+    kv:    { dev: "redis",    test: "memory", prod: "redis" },
+    files: { dev: "s3",       test: "memory", prod: "s3" },
   },
 },
 ```
@@ -867,9 +860,9 @@ same PII masking — see the Callout under [Querying by hand](#querying-by-hand)
 ## Troubleshooting
 
 <Accordions>
-<Accordion title="OKE1101 — missing table in docker or prod">
+<Accordion title="OKE1101 — missing table in prod">
 
-Schema DDL never runs automatically outside local dev. Run `oke db push` against the target database for a dev-style sync, or `oke db generate` + `oke db migrate` for reviewed, versioned migrations.
+Schema DDL never runs automatically in `prod`. Under `oke dev`, `db.autoPush` (default `true`) runs `oke db push`. For production use `oke db generate` + `oke db migrate`.
 
 </Accordion>
 <Accordion title="I need a join — with: is not supported">
@@ -887,14 +880,14 @@ You are on offset paging. Switch `list` to keyset by setting `cursor` columns wi
 `count: "exact"` runs `COUNT(*)` per page. Set `count: "none"` in the `list` options to skip it, or use keyset mode where totals are rarely needed.
 
 </Accordion>
-<Accordion title="KV TTL never expires locally">
+<Accordion title="KV TTL never expires in tests">
 
-The local default is `memory`, which ignores TTL on `set`. Run against `redis` (`oke dev --docker` or `drivers.store.kv.local: "redis"` with `REDIS_URL`) when you need real expiry.
+The `test` default is `memory`, which ignores TTL on `set`. Under `oke dev`, KV is `redis` by default — use that when you need real expiry.
 
 </Accordion>
 <Accordion title="oke boot: redis / meilisearch / S3 URL missing">
 
-Driver-backed facets fail boot when their URL is absent — Redis needs `REDIS_URL`, meilisearch needs `OKE_STORE_INDEX_URL`, S3 needs `S3_BUCKET`. Docker mode expects `oke dev -d` to write these into the compose env.
+Driver-backed facets fail boot when their URL is absent — Redis needs `REDIS_URL`, meilisearch needs `OKE_STORE_INDEX_URL`, S3 needs `S3_BUCKET`. `oke dev` writes these into the Compose env.
 
 </Accordion>
 <Accordion title="vector dims X !== index dims Y">
@@ -902,9 +895,9 @@ Driver-backed facets fail boot when their URL is absent — Redis needs `REDIS_U
 The vector length must match `store.index(…, { dims })` (runtime default `3` if unset). Align `dims` with your embedder, or fix the vector you pass to `upsert` / `search`.
 
 </Accordion>
-<Accordion title="Index stays on memory in docker">
+<Accordion title="Index stays on memory under oke dev">
 
-Unlike KV/Files, unset `drivers.store.index` does **not** promote to `pgvector` in docker — it stays `memory`. Set the map explicitly (and pair SQL for `pgvector` / `libsql`).
+Unlike KV/Files, unset `drivers.store.index` does **not** promote to `pgvector` in `dev` — it stays `memory`. Set the map explicitly (and pair SQL for `pgvector`).
 
 </Accordion>
 </Accordions>

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

@@ -55,7 +55,7 @@ oke vault set STRIPE_KEY sk_test_your_key_here
 <Step>
 ### Read it in a Flow
 
-Flows read secrets through `fx.vault` — never through `process.env`. `fx.vault` returns a
+Flows read secrets through `fx.vault.get` — never through `process.env`. It resolves to a
 `Redacted<string>`: printing, logging, or serializing it yields a placeholder, never the value.
 Call `.reveal()` once at the boundary that needs the real credential:
 
@@ -66,7 +66,7 @@ export const charge = on(
     in: ChargeInput,
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {
-      const key = fx.vault(stripeKey); // Redacted — safe to pass to fx.log
+      const key = await fx.vault.get(stripeKey); // Redacted — safe to pass to fx.log
       const intent = await stripe(key.reveal()).create(input);
       return { id: intent.id };
     },
@@ -87,9 +87,9 @@ That's the whole loop: declare → set → read. Everything below is what OKE gu
 
 <VaultRedacted />
 
-Pass the wrapper freely — `fx.log`, `String()`, and `JSON.stringify` all yield
-`[redacted]`. Call `.reveal()` once at the provider boundary that needs the
-credential.
+Pass the wrapper freely — `fx.log`, `String()`, `JSON.stringify`, and
+`console.log` / `util.inspect` all yield `[redacted]` (or a `Redacted<…>` label).
+Call `.reveal()` once at the provider boundary that needs the credential.
 
 ## Two kinds of contracts
 
@@ -100,6 +100,20 @@ credential.
 
 `vault(name, …)` is shorthand for `vault.secret(name, …)`.
 
+### Plain environment variables
+
+`vault.env` reads `process.env` synchronously for values that need no contract — a port, a feature flag, a log level. It never joins the resolution chain, never gets a fingerprint, and never gets redacted.
+
+| Call                             | Returns               | On a missing value                     |
+| -------------------------------- | --------------------- | -------------------------------------- |
+| `vault.env("LOG_LEVEL")`         | `string \| undefined` | `undefined` (empty counts as missing)  |
+| `vault.env.required("REGION")`   | `string`              | Throws, and boot lists it as a gap     |
+| `vault.env.int("PORT", 3000)`    | `number`              | The default; throws when none is given |
+| `vault.env.bool("DEBUG", false)` | `boolean`             | The default; throws when none is given |
+| `vault.env.json("FLAGS")`        | `T \| undefined`      | `undefined`; throws on malformed JSON  |
+
+Every name passed to `vault.env.required` is registered, so boot reports missing variables in the same `VaultBootError` as missing secrets — before it opens a database connection.
+
 ### Contract options
 
 | Option        | Type                  | Meaning                                                                  |
@@ -110,9 +124,9 @@ credential.
 | `dev`         | string                | Local-only fallback when no source provides a value (never used in prod) |
 | `sensitive`   | boolean               | Override the default (`true` for secrets, `false` for config)            |
 
-### Zero-setup local fallback
+### Zero-setup Compose fallback
 
-`dev: vault.fromDocker("store.sql")` resolves the connection URL that `oke dev --docker` generated for that role — no manual copying of Postgres URLs:
+`dev: vault.fromDocker("store.sql")` resolves the connection URL that `oke dev` generated for that role — no manual copying of Postgres URLs:
 
 ```typescript
 export const dbUrl = vault.secret("DATABASE_URL", {
@@ -140,85 +154,82 @@ VaultBootError: 1 secret(s) missing:
 
 ## Setting and rotating values
 
-| Command                    | What it does                                                     |
-| -------------------------- | ---------------------------------------------------------------- |
-| `oke vault set NAME value` | Write a value (OpenBao API in docker mode, `.env.local` locally) |
-| `oke vault list`           | List names present in the active store                           |
-| `oke vault import <file>`  | Bulk-import names from a dotenv file                             |
+| Command                                            | What it does                                                         |
+| -------------------------------------------------- | -------------------------------------------------------------------- |
+| `oke vault set NAME value`                         | Write a value to the env file (`.env.local` by default)              |
+| `oke vault list`                                   | List names present in the active store                               |
+| `oke vault import <file>`                          | Bulk-import names from a dotenv file                                 |
+| `oke vault init`                                   | Initialize the built-in encrypted store (prints the master key once) |
+| `oke vault status` / `seal` / `unseal`             | Built-in seal lifecycle                                              |
+| `oke vault rotate <path>` / `rotate-master`        | Re-encrypt a secret, or rewrap every DEK under a new master          |
+| `oke vault audit` / `audit verify` / `audit purge` | Hash-chained audit (no secret values)                                |
+| `oke vault purge-expired [--dry-run] [--before]`   | Hard-delete secret rows past `expires_at` (operator cleanup)         |
+| `oke vault backup` / `restore`                     | Encrypted backup under a separate backup KEK                         |
 
-In docker mode, `oke vault set` writes straight to the running OpenBao — no git commit, no rebuild, no restart of the vault.
+Flows can write too, through the same capability gate as reads: `fx.vault.set(path, value, { ttlMs?, metadata? })`, `fx.vault.rotate(path, value)`, `fx.vault.delete(path)`, plus `fx.vault.list(prefix?)` and `fx.vault.status()`. These need the encrypted-at-rest backend (`drivers.vault = "vault"`) and throw without it; `fx.vault.get` works on every app.
 
 The **Console** (`:6533`) can also set and rotate values, but it is **write-only**: it shows a salted fingerprint (`sha256:…`) per secret, never the cleartext. When you rotate a key there, the panel shows the **blast radius** — which in-flight durable runs will wake up with the new value.
 
+<Callout title="Builtin master keys and expired rows">
+  Resolve the master key with `--key -` (stdin), `OKE_VAULT_MASTER_KEY`, or a hidden TTY prompt —
+  never put keys on argv in shared shells (history risk). Expired rows stay until `oke vault
+  purge-expired` (use `--dry-run` first, or schedule via cron).
+</Callout>
+
 <Callout title="Secrets never reach logs">
-  `fx.vault` returns `Redacted` — `fx.log` shows `[redacted]`. A revealed string that still reaches
-  a log is scrubbed by the boot redactor to `[redacted:secret]`. Traces and the Console get
+  `fx.vault.get` returns `Redacted` — `fx.log` shows `[redacted]`. A revealed string that still
+  reaches a log is scrubbed by the boot redactor to `[redacted:secret]`. Traces and the Console get
   fingerprints, never cleartext.
 </Callout>
 
 ## Per-environment drivers
 
-Which backend holds your values depends on the mode — configured once in `oke.config.ts`.
+Which backend holds your values depends on the environment — configured once in `oke.config.ts`.
 App boot and the Console share the same resolution-chain builder (`env` layers → backend):
 
 ```typescript title="oke.config.ts"
-vault: {
-  local: "env",      // .env.local — zero ceremony
-  docker: "openbao", // real vault in the compose stack
-  test: "memory",    // seeded map — deterministic tests
-  prod: "openbao",   // real vault in production
+drivers: {
+  vault: {
+    dev: "env", // process env / .env.local
+    test: "memory",
+    prod: "vault", // built-in encrypted store (Postgres you already run)
+  },
 },
 ```
 
-| Driver    | Backend         | Best for                                   |
-| --------- | --------------- | ------------------------------------------ |
-| `env`     | `.env.local`    | Local loop — no infra at all               |
-| `openbao` | OpenBao (KV v2) | Docker + prod — durable, access-controlled |
-| `memory`  | in-process map  | Tests                                      |
-
-Other drivers (`managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
-
-## OpenBao in docker and prod
+Defaults are `env` / `memory` / `vault`. create-oke templates pin the built-in store for prod.
 
-When you run `oke dev --docker` (or bring up a `--prod` stack), OKE runs a real OpenBao container with durable Raft storage — not an in-memory dev server.
+| Driver    | Backend                                                             | Best for                           |
+| --------- | ------------------------------------------------------------------- | ---------------------------------- |
+| `env`     | process env                                                         | Local pins — no encryption at rest |
+| `vault`   | Postgres/PGlite envelope (AES-256-GCM)                              | Default prod — no extra container  |
+| `managed` | AWS Secrets Manager (`OKE_VAULT_PROVIDER`) or platform-injected env | Cloud SM / Fly / Railway / K8s     |
+| `memory`  | in-process map                                                      | Tests                              |
 
-<Steps>
-
-<Step>
-### First boot is automatic
+### Threat model (honest)
 
-OKE initializes OpenBao (Shamir 1-of-1), unseals it, writes a least-privilege policy that covers **only your declared secrets**, and mints an app token bound to that policy. You never run raw `bao` commands.
+Built-in Vault protects a **database dump** (ciphertext + wrapped DEKs). It does **not** equal a separate process-isolated vault:
 
-</Step>
+| Threat                                        | Built-in `vault`                   | Managed AWS SM / remote vault |
+| --------------------------------------------- | ---------------------------------- | ----------------------------- |
+| Postgres dump / backup leak                   | Protected (need master/KEK)        | Protected                     |
+| App RCE / memory dump                         | Game over (same process)           | Better if vault is isolated   |
+| Master key only in `.env` next to app secrets | Weak — use KMS auto-unseal in prod | Prefer non-exportable KEK     |
+| JS `Buffer.fill(0)` vs remote `mlock`         | Hygiene only — not claimed         | Stronger outside the app      |
 
-<Step>
-### Keys stay on the host
+For production built-in stores, set `vault.encryption.masterKey` to a KMS source (optional peer `@aws-sdk/client-kms`) or use `managed` + AWS Secrets Manager. `oke doctor` warns when prod would take the master key from the environment.
 
-The unseal key and root token are written to `.oke/openbao/` (mode `0600`, gitignored) — never into `docker/.env.docker`, never into YAML. Only the least-privilege app token lands in `.env.docker` as `OKE_VAULT_TOKEN`.
+## Managed providers (official)
 
-</Step>
+Official managed provider: **AWS Secrets Manager** — set `drivers.vault` to `"managed"` and
+`OKE_VAULT_PROVIDER=aws-secrets-manager` (optional peer `@aws-sdk/client-secrets-manager`).
+Omit the provider when the platform already injects secrets as env vars.
 
-<Step>
-### Restarts just work
+## Community / plugin
 
-On every later start OKE detects the sealed vault and unseals it with the host key. Secrets set before a container restart are still there after it — proven by an integration test, not assumed.
-
-</Step>
-
-</Steps>
-
-| File                      | Holds                     | Used by                          |
-| ------------------------- | ------------------------- | -------------------------------- |
-| `.oke/openbao/unseal.key` | The single unseal share   | `oke` (every start)              |
-| `.oke/openbao/root.token` | Root token                | `oke` (policy sync / token mint) |
-| `.oke/openbao/app.token`  | Least-privilege app token | the app + Console                |
-
-<Callout title="Single point of failure — read this once" type="warn">
-  Back up `.oke/openbao/unseal.key` to a separate safe location. Losing it means losing every secret
-  permanently, with no recovery.
-</Callout>
-
-This is by design: self-hosted single-node, Shamir 1-of-1, no cloud KMS. If OpenBao is initialized but the key is gone, boot fails with an explicit permanent-loss error — it never silently starts empty.
+OpenBao, HashiCorp Vault, Azure Key Vault, GCP Secret Manager, Doppler, and 1Password are not
+shipped in core. Implement a community adapter for the `managed` driver surface, or keep using
+built-in `vault` / `env`.
 
 ## Troubleshooting
 
@@ -228,30 +239,38 @@ This is by design: self-hosted single-node, Shamir 1-of-1, no cloud KMS. If Open
 A contract has no value in any layer of the chain. Fix by providing it in exactly one place:
 
 - locally: add `NAME=value` to `.env.local` (or run `oke vault set NAME value`)
-- docker mode: `oke vault set NAME value` writes to OpenBao directly
-- CI / hosting: set a real environment variable
+- built-in store: `oke vault init` then unseal, or set via Console (write-only)
+- CI / hosting: set a real environment variable (or AWS SM when `managed`)
 
 </Accordion>
-<Accordion title="OpenBao is sealed or unreachable in docker mode">
+<Accordion title="How do I rotate a key safely?">
 
-Re-run `oke dev --docker` — the bootstrap unseals with the host key on every start. If it reports the vault is initialized but `.oke/openbao/unseal.key` is missing, restore the key from your backup; the error is explicit because starting empty would look like "no secrets" instead of data loss.
+Set the new value (`oke vault set` or the Console). The Console's rotation view shows the blast radius — in-flight durable runs that will resume with the new value — before you commit. The `rotate: "90d"` hint on the contract drives the rotation-due signal.
 
 </Accordion>
-<Accordion title="Where is the root token?">
+<Accordion title="How do I pass the builtin master key without shell history?">
 
-`.oke/openbao/root.token`, mode `0600`, gitignored. It exists only for `oke` to sync policies and mint app tokens — the running app never sees it.
+Prefer `oke vault unseal --key -` and pipe the key on stdin, or omit `--key` on a
+TTY and type it at the hidden prompt. Avoid `--key <base64>` on shared hosts.
 
 </Accordion>
-<Accordion title="How do I rotate a key safely?">
+<Accordion title="Expired secrets still take space in Postgres">
 
-Set the new value (`oke vault set` or the Console). The Console's rotation view shows the blast radius — in-flight durable runs that will resume with the new value — before you commit. The `rotate: "90d"` hint on the contract drives the rotation-due signal.
+`expires_at` fails closed on read, but rows stay until you hard-delete them:
+
+```bash
+oke vault purge-expired --dry-run
+oke vault purge-expired
+```
+
+Schedule the live command with cron when you want automatic cleanup.
 
 </Accordion>
 </Accordions>
 
 ## Learn more
 
-- [Flow](/docs/elements/flow) — how `fx.vault` reads secrets inside `do`
+- [Flow](/docs/elements/flow) — how `fx.vault.get` reads secrets inside `do`
 - [CLI Reference](/docs/reference/cli) — `oke vault set` · `list` · `import`
 
 ## Next

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

@@ -39,7 +39,7 @@ digest Clock, and an AI summarize stub.
 The standard starter already exports a named health Flow:
 
 ```typescript title="flows/main"
-import { on, flow, http, gate } from "okengine";
+import { on, flow, http, gate } from "okengine/http";
 import { z } from "zod";
 
 export const health = on(
@@ -63,17 +63,17 @@ same Manifest.
 Adopted modules become namespaces on the client:
 
 ```typescript title="app"
-import { oke } from "okengine";
-import * as main from "./flows/main";
-import * as notes from "./flows/notes";
-import { db } from "./core";
+import "@/core";
 
-export const app = oke({ name: "notes", stores: [db] }).adopt({ main, notes });
+import { oke } from "okengine/http";
+import * as routes from "@/flows/generated";
+
+export const app = oke({ name: "notes" }).adopt(routes);
 export type App = typeof app;
 ```
 
-The scaffolded `src/app.ts` also registers secrets, signals, and channel
-templates in the same `oke({ … })` call — no post-construction mutation.
+`import "@/core"` loads stores, secrets, channels, and message catalogs
+(via `locales/index.ts`) so they auto-register before `oke()`.
 
 ```typescript title="client"
 import { createClient } from "okengine/client";