okengine 0.3.5 → 0.4.3

package/AGENTS.md

@@ -92,3 +92,9 @@ Engine: Bun `>=1.3`.
 | Manifest | `manifest.v1.schema.json`            |
 
 **If the documentation is silent, stop and ask.**
+
+## After every implementation
+
+Before claiming work done: run [`.agents/skills/oke-ship`](.agents/skills/oke-ship/SKILL.md) — append notes to `changelog.md` under `## Unreleased` (never under a shipped `## v…` section), and update site docs via [`.agents/skills/oke-docs`](.agents/skills/oke-docs/SKILL.md) for any user-facing surface. Version bump is separate: `bun run bump` promotes Unreleased into the next `## vX.Y.Z`.
+
+Dependency bumps (one package, one `package.json`, or all): [`.agents/skills/oke-deps`](.agents/skills/oke-deps/SKILL.md).

package/manifest.v1.schema.json

@@ -321,6 +321,10 @@
           "type": "string",
           "enum": ["once", "broadcast", "live"]
         },
+        "description": {
+          "description": "Optional human description; consumers fall back to the signal map key.",
+          "type": "string"
+        },
         "retries": { "type": "integer", "minimum": 0 },
         "deadLetter": { "type": "boolean" },
         "schema": { "$ref": "#/$defs/JsonSchema" },
@@ -354,6 +358,10 @@
           ]
         },
         "sqlName": { "type": "string", "minLength": 1 },
+        "description": {
+          "description": "Optional human description; consumers fall back to the column map key.",
+          "type": "string"
+        },
         "pii": { "type": "boolean" },
         "sensitive": { "type": "boolean" },
         "retain": { "type": "string", "minLength": 1 },
@@ -408,6 +416,10 @@
           "type": "string",
           "enum": ["sql", "kv", "files", "index"]
         },
+        "description": {
+          "description": "Optional human description; consumers fall back to the store map key.",
+          "type": "string"
+        },
         "tables": {
           "type": "object",
           "propertyNames": { "type": "string", "minLength": 1 },
@@ -451,7 +463,11 @@
         "cron": { "type": "string", "minLength": 1 },
         "every": { "type": "string", "minLength": 1 },
         "timezone": { "type": "string", "minLength": 1 },
-        "overridable": { "type": "boolean" }
+        "overridable": { "type": "boolean" },
+        "description": {
+          "description": "Optional human description; consumers fall back to the clock map key.",
+          "type": "string"
+        }
       }
     },
     "Gate": {
@@ -485,6 +501,10 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "uniqueItems": true
+        },
+        "description": {
+          "description": "Optional human description; consumers fall back to the gate map key.",
+          "type": "string"
         }
       }
     },
@@ -502,6 +522,10 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "description": {
+          "description": "Optional human description; consumers fall back to the channel map key.",
+          "type": "string"
+        },
         "medium": {
           "type": "string",
           "enum": ["email", "sms", "whatsapp", "push", "any"]
@@ -580,6 +604,18 @@
         }
       }
     },
+    "PluginTable": {
+      "description": "Optional metadata for a plugin-contributed table.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "plane": { "type": "string", "minLength": 1 },
+        "description": {
+          "description": "Optional human description; consumers fall back to the table name.",
+          "type": "string"
+        }
+      }
+    },
     "Plugin": {
       "type": "object",
       "additionalProperties": false,
@@ -600,6 +636,12 @@
           "type": "array",
           "items": { "type": "string", "minLength": 1 },
           "uniqueItems": true
+        },
+        "tables": {
+          "description": "Optional metadata for table:* contributions.",
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "$ref": "#/$defs/PluginTable" }
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.3.5",
+  "version": "0.4.3",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -56,7 +56,7 @@
     "prepack": "bun run build",
     "bench": "bun test ./src/runtime/cold-start.bench.ts src/client/budget.test.ts src/console/budget.test.ts src/kernel/budget.test.ts src/kernel/routing-budget.test.ts src/runs/bench.test.ts",
     "budgets": "bun src/release/publish.ts",
-    "gate": "bun test src/cli/doc-staleness.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
+    "gate": "bun test src/cli/doc-staleness.test.ts src/cli/competitor-mention-removal.test.ts src/drivers/vault-driver-removal.test.ts src/kernel/errors.registry.test.ts src/upgrade/codemods.test.ts",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
     "ci": "bun scripts/ci.ts",
@@ -66,10 +66,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@duckdb/node-api": "^1.5.5-r.1",
+    "@duckdb/node-api": "^1.5.5-r.2",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "oxc-parser": "^0.141.0",
+    "oxc-parser": "^0.142.0",
     "sently": "^0.8.0"
   },
   "devDependencies": {
@@ -78,17 +78,20 @@
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/state": "^6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
-    "@codemirror/view": "^6.43.6",
-    "@oxc-project/types": "^0.141.0",
-    "@playwright/test": "^1.62.0",
+    "@codemirror/view": "^6.43.7",
+    "@electric-sql/pglite": "^0.5.4",
+    "@electric-sql/pglite-pgvector": "^0.0.5",
+    "@libsql/client": "^0.17.4",
+    "@oxc-project/types": "^0.142.0",
+    "@playwright/test": "^1.62.1",
     "@sinclair/typebox": "^0.34.52",
     "@tailwindcss/vite": "^4.3.3",
     "@tanstack/react-query": "^5.101.4",
     "@tanstack/react-router": "^1.170.18",
     "@types/bun": "latest",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
     "arktype": "^2.2.3",
     "axe-core": "^4.12.1",
     "clsx": "^2.1.1",
@@ -102,22 +105,34 @@
     "oxfmt": "^0.61.0",
     "oxlint": "^1.76.0",
     "oxlint-tsgolint": "^7.0.2001",
-    "playwright": "^1.62.0",
+    "playwright": "^1.62.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "typescript": "^7.0.2",
     "valibot": "^1.4.2",
-    "vite": "^8.1.5",
+    "vite": "^8.2.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
+    "@electric-sql/pglite": ">=0.5.0",
+    "@electric-sql/pglite-pgvector": ">=0.0.5",
+    "@libsql/client": ">=0.15.0",
     "drizzle-kit": ">=1.0.0-rc.0",
     "drizzle-orm": ">=1.0.0-rc.0",
     "drizzle-seed": ">=0.3.0",
     "zod": ">=3.23.0"
   },
   "peerDependenciesMeta": {
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "@electric-sql/pglite-pgvector": {
+      "optional": true
+    },
+    "@libsql/client": {
+      "optional": true
+    },
     "drizzle-kit": {
       "optional": true
     },

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

@@ -7,13 +7,15 @@ source: "docs/spec/unified-theory.md"
 
 Tools alone don't make a good operator — an agent also needs to know the _vocabulary_: what a Flow is, why `fx` is the only door, which driver ids are legal. OKE ships that knowledge as contracts and skills that agents load automatically, so sessions start aligned instead of drifting and getting corrected.
 
-## The three layers
+## The layers
 
 | Layer              | Path                       | Loaded when                                       | Teaches                                                               |
 | ------------------ | -------------------------- | ------------------------------------------------- | --------------------------------------------------------------------- |
 | **Agent contract** | `AGENTS.md` (repo root)    | Every agent session, automatically                | The one law, eight elements, ten exports, the fx rule, ports, budgets |
 | **Element skill**  | `.agents/skills/oke/`      | Building or changing an okengine app              | The element contract in depth — declaration patterns per element      |
 | **Docs skill**     | `.agents/skills/oke-docs/` | Writing or editing docs under `site/content/docs` | The documentation information-architecture standard and its gates     |
+| **Ship skill**     | `.agents/skills/oke-ship/` | After any implementation, before claiming done    | Changelog under `## Unreleased` + docs sync via `oke-docs`            |
+| **Deps skill**     | `.agents/skills/oke-deps/` | Updating `package.json` dependencies              | Scoped bumps, Bun install, pins (Drizzle RC, fumadocs alias, …)       |
 
 ## AGENTS.md — the root contract
 
@@ -21,14 +23,16 @@ Every OKE app's repo carries an `AGENTS.md` that agents (Cursor, Claude Code, an
 
 ## Skills — installable know-how
 
-Skills are `SKILL.md` packages an agent loads when the work matches their description. The two OKE ships:
+Skills are `SKILL.md` packages an agent loads when the work matches their description. OKE ships:
 
-| Skill      | Use it for                          | Inside                                                    |
-| ---------- | ----------------------------------- | --------------------------------------------------------- |
-| `oke`      | App work — flows, elements, drivers | The agent contract, element patterns, the fx invariants   |
-| `oke-docs` | Docs work — new pages, rewrites     | The page skeleton, verification sources, the density gate |
+| Skill      | Use it for                                   | Inside                                                                    |
+| ---------- | -------------------------------------------- | ------------------------------------------------------------------------- |
+| `oke`      | App work — flows, elements, drivers          | The agent contract, element patterns, the fx invariants                   |
+| `oke-docs` | Docs work — new pages, rewrites              | The page skeleton, verification sources, the density gate                 |
+| `oke-ship` | Closing an implementation — changelog + docs | Append under `## Unreleased`; `bun run bump` promotes it into `## vX.Y.Z` |
+| `oke-deps` | Dependency updates — one package or all      | Scope map, `ncu` + Bun, reject downgrades / protect RC and aliases        |
 
-Both live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe.
+All live in the repo under `.agents/skills/`, so they travel with the code and stay versioned with what they describe.
 
 ## How contracts compose with MCP
 

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

@@ -14,6 +14,10 @@ Answers: **secret contracts, who can read each, rotation due**
 ## What this panel shows
 
 <Cards>
+  <Card
+    title="Contracts"
+    description="Optional description as the human title; technical key stays visible."
+  />
   <Card
     title="Fingerprints"
     description="Salted hash per environment — rotation and drift without exposure."

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

@@ -86,6 +86,8 @@ export const triage = smart.prompt("ticket-triage", {
 | `evals`      | string                | Path to a `.jsonl` eval set, regression-gated via `oke eval`   |
 | `budget`     | object                | `maxCostPerCall` — cost is a first-class dimension             |
 
+<AiGuardrails />
+
 ## Agents with real guardrails
 
 An agent's tools are your flows — each carrying its own gates, effects, and typed errors, so the agent can never do anything a flow couldn't:

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

@@ -71,13 +71,16 @@ Locally the `console` driver captures mail into an inbox instead of sending; in
 | `binder.template(name, opts)`  | Typed template bound to that medium             |
 | `channel.template(name, opts)` | Medium-agnostic template (one body, any medium) |
 
-| Template option | Type                  | Meaning                                           |
-| --------------- | --------------------- | ------------------------------------------------- |
-| `schema`        | zod / Standard Schema | The data the template may reference — typed sends |
-| `locales`       | string[]              | Languages this template is rendered in            |
+| Template option | Type                  | Meaning                                                    |
+| --------------- | --------------------- | ---------------------------------------------------------- |
+| `description`   | string                | Human title in the Console (falls back to the template id) |
+| `schema`        | zod / Standard Schema | The data the template may reference — typed sends          |
+| `locales`       | string[]              | Languages this template is rendered in                     |
 
 ## The human physics
 
+<ChannelPhysics />
+
 ### Consent is checked before sending
 
 Opt-out is first-class: a subject who opted out of a medium is **suppressed** — the send resolves without contacting the provider, and the receipt says so. You never hand-roll "did they unsubscribe?" checks.

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

@@ -83,10 +83,7 @@ do: async (input, fx) => {
 
 ## Two kinds of schedules
 
-| Declaration         | Shows in Console | Cron + timezone | Runtime-editable   | Use for                           |
-| ------------------- | ---------------- | --------------- | ------------------ | --------------------------------- |
-| `every("1h")`       | no               | no              | no                 | Simple fixed intervals            |
-| `clock(name, opts)` | yes              | yes             | when `overridable` | Business schedules operators tune |
+<ClockSchedules />
 
 Both are triggers consumed with the same `on(trigger, flow)` — the flow underneath does not know the difference.
 
@@ -98,6 +95,7 @@ Both are triggers consumed with the same `on(trigger, flow)` — the flow undern
 | `every`       | string  | —       | Fixed interval: `"30s"` · `"10m"` · `"1h"` · `"7d"`          |
 | `timezone`    | string  | `"UTC"` | IANA timezone for cron evaluation                            |
 | `overridable` | boolean | `false` | Allow the Console to edit / pause the schedule               |
+| `description` | string  | —       | Human title in the Console (falls back to the clock name)    |
 
 ## Sleeping inside a flow
 

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

@@ -77,6 +77,7 @@ curl -X POST localhost:6530/orders -d '{"sku":"SKU-1","qty":2}' -H 'content-type
 | `in`     | Input contract — validated before `do` runs; bad input is a 422 |
 | `out`    | Output contract — the return value is checked against it        |
 | `errors` | Typed failures — **returned** with `fx.fail`, never thrown      |
+| `retry`  | Optional whole-`do` backoff on thrown errors (same journal)     |
 | `do`     | The work — every read, write, emit, and call goes through `fx`  |
 
 Failures are values, not exceptions:
@@ -95,13 +96,7 @@ Every response follows one envelope — success `{ data, error: null }`, failure
 
 ## The five triggers
 
-| Trigger                      | Starts when                  | Replaces           |
-| ---------------------------- | ---------------------------- | ------------------ |
-| `http.post("/orders")`       | a request arrives            | endpoint · handler |
-| `orderPlaced` (a signal)     | another flow emits           | queue consumer     |
-| `every("1h")`                | time passes                  | cron job           |
-| `db.table(orders).changed()` | a row changes                | CDC pipeline       |
-| — none                       | another flow calls `fx.call` | "private" helper   |
+<FlowTriggers />
 
 ### http — a request arrives
 
@@ -191,10 +186,12 @@ Everything a flow may touch, on one object:
 | `fx.ask(prompt, input)`                 | ask             | Call a versioned AI prompt                   |
 | `fx.run(agent, input)`                  | ask             | Run a bounded agent                          |
 | `fx.call(flow, input)`                  | call            | Invoke another flow                          |
-| `fx.vault(contract)`                    | read            | Read a secret (redacted from logs)           |
+| `fx.vault(contract)`                    | read            | Read a secret (`Redacted`; logs masked)      |
 | `fx.clock.now()` / `.sleep(…)`          | —               | Injected time / durable sleep                |
 | `fx.cache.get/set`                      | —               | Shared cache with effect-aware invalidation  |
 | `fx.step(name, fn)`                     | —               | Named durable step — never re-runs on replay |
+| `fx.all` / `fx.race` / `fx.retry`       | —               | Structured concurrency + backoff retry       |
+| `fx.signal`                             | —               | Ambient `AbortSignal` for the current branch |
 | `fx.id()` · `fx.log` · `fx.t`           | —               | UUIDs, redacting logger, i18n                |
 | `fx.auth` · `fx.operator` · `fx.tenant` | —               | Who is calling (user / operator / tenant)    |
 
@@ -215,18 +212,20 @@ export const chargeOrder = flow({
   out: z.boolean(),
   do: async ({ orderId }, fx) => {
     const intent = await fx.step("create-intent", () =>
-      stripe(fx.vault(stripeKey)).create(orderId),
+      stripe(fx.vault(stripeKey).reveal()).create(orderId),
     );
 
     await fx.clock.sleep("verify-window", "2m"); // survives restart and deploy
 
-    return fx.step("confirm", () => stripe(fx.vault(stripeKey)).confirm(intent));
+    return fx.step("confirm", () => stripe(fx.vault(stripeKey).reveal()).confirm(intent));
   },
 });
 ```
 
 **Consequence:** kill the process between the two steps and the run **resumes at `confirm`** — completed steps replay from the journal, so the card is not charged twice. This is verified by the engine's own test suite: after resume, `create-intent` has run exactly once.
 
+For flaky sub-steps, wrap the work in `fx.retry` **inside** `fx.step` so a completed charge is never retried on resume. Coarse whole-body retry is also available as `flow({ retry: { retries, delay, backoff, jitter } })` and reuses the same journal session.
+
 ## Composition is just calls
 
 Wiring is values flowing between flows — declared in code, never configured in a dashboard:
@@ -251,6 +250,16 @@ That bypasses the effect graph: the Manifest can't see the call, cache keys miss
 
 `fx.fail(code, data)` for expected outcomes — anything in `errors`. A throw is a crash: the run fails with a 500-shaped error and no typed code for the client. Expected failures are values so clients can switch on `error.code`.
 
+</Accordion>
+<Accordion title="Promise.all left orphan work running after one branch failed">
+
+Use `fx.all` (or `fx.race`) with thunks. The first rejection aborts siblings through `fx.signal`. Bare `Promise.all` / `Promise.race` do not cancel losers.
+
+</Accordion>
+<Accordion title="Durable flow retried a completed charge">
+
+Put `fx.retry` **inside** `fx.step`, not around it. Completed steps replay from the journal and never re-run. `flow({ retry })` is for coarse whole-body retries on the same session.
+
 </Accordion>
 <Accordion title="How do I share logic between flows — a private function?">
 

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

@@ -72,12 +72,18 @@ A denied request never reaches `do`. It returns one of three typed failures, lik
 
 </Steps>
 
+<GatePipeline />
+
 ## Two kinds of gates
 
-| Declaration                | Question it answers                    | Evaluated against                  |
-| -------------------------- | -------------------------------------- | ---------------------------------- |
-| `gate.policy(name, check)` | Is this principal allowed? (ABAC)      | auth / operator / request metadata |
-| `gate.rate(options)`       | Is there budget left for this subject? | an atomic counter on the kv driver |
+| Declaration                           | Question it answers                    | Evaluated against                  |
+| ------------------------------------- | -------------------------------------- | ---------------------------------- |
+| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)      | auth / operator / request metadata |
+| `gate.rate(options)`                  | Is there budget left for this subject? | an atomic counter on the kv driver |
+
+`gate.policy(name, check)` stays the terse form. Pass
+`{ check, description }` when you want a human title in the Console
+(falls back to the policy name).
 
 ### The policy context
 
@@ -97,13 +103,14 @@ A policy name containing `:` is also a `Module:Action` permission — the same d
 
 ### Rate options
 
-| Option        | Type         | Default                    | Meaning                                      |
-| ------------- | ------------ | -------------------------- | -------------------------------------------- |
-| `max`         | number       | — (**required**)           | Takes allowed within `per`                   |
-| `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)  |
-| `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)      |
-| `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                            |
-| `overridable` | boolean      | `false`                    | Allow the Console to retune `max`/`per` live |
+| Option        | Type         | Default                    | Meaning                                                  |
+| ------------- | ------------ | -------------------------- | -------------------------------------------------------- |
+| `max`         | number       | — (**required**)           | Takes allowed within `per`                               |
+| `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)              |
+| `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)                  |
+| `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                                        |
+| `overridable` | boolean      | `false`                    | Allow the Console to retune `max`/`per` live             |
+| `description` | string       | —                          | Human title in the Console (falls back to the rate name) |
 
 | Strategy                 | Behavior                                               |
 | ------------------------ | ------------------------------------------------------ |

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

@@ -76,23 +76,20 @@ That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handl
 
 ## The three delivery physics
 
-| `delivery`    | Semantics                                              | Use for                                                    |
-| ------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
-| `"once"`      | Queue: competing consumers, retries, dead-letter queue | Jobs that must happen exactly once — emails, payments sync |
-| `"broadcast"` | Pub/sub: **every** subscriber receives a copy          | Cache invalidation, cross-service events                   |
-| `"live"`      | Stream: client-subscribable and replayable             | Live feeds, dashboards, progress updates                   |
+<SignalDelivery />
 
 The declaration is identical in shape for all three — switching physics later is a one-word change, not a migration to another library.
 
 ### Options
 
-| Option       | Type                              | Default          | Meaning                                                        |
-| ------------ | --------------------------------- | ---------------- | -------------------------------------------------------------- |
-| `delivery`   | `"once" \| "broadcast" \| "live"` | — (**required**) | Delivery physics                                               |
-| `schema`     | zod / Standard Schema             | —                | Payload contract; typed emits and Manifest docs                |
-| `retries`    | number                            | `3`              | Max delivery attempts before dead-letter (`once`)              |
-| `deadLetter` | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                |
-| `optional`   | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check) |
+| Option        | Type                              | Default          | Meaning                                                        |
+| ------------- | --------------------------------- | ---------------- | -------------------------------------------------------------- |
+| `delivery`    | `"once" \| "broadcast" \| "live"` | — (**required**) | Delivery physics                                               |
+| `description` | string                            | —                | Human title in the Console (falls back to the signal name)     |
+| `schema`      | zod / Standard Schema             | —                | Payload contract; typed emits and Manifest docs                |
+| `retries`     | number                            | `3`              | Max delivery attempts before dead-letter (`once`)              |
+| `deadLetter`  | boolean                           | `true`           | Preserve exhausted messages in the DLQ (`once`)                |
+| `optional`    | boolean                           | `false`          | Allow emitting while nobody subscribes (skip the orphan check) |
 
 ## When delivery fails
 

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

@@ -90,17 +90,18 @@ export const createNote = on(
 
 Pick the facet that matches the physics of your data. Each declaration is one line; the runtime handle shows what flows can do with it.
 
-| Facet                     | Declares          | Best for                              | `fx.store(…)` handle                                   |
-| ------------------------- | ----------------- | ------------------------------------- | ------------------------------------------------------ |
-| `store.sql(name, opts)`   | a SQL database    | domain tables, relations, constraints | `select` · `insert` · `update` · `delete` · `findById` |
-| `store.kv(name)`          | a key-value space | cache, sessions, rate limits          | `get` · `set(key, value, ttl?)` · `delete` · `list`    |
-| `store.files(name)`       | a blob bucket     | uploads, exports, attachments         | `put` · `get` · `delete` · `list(prefix?)`             |
-| `store.index(name, opts)` | a vector index    | semantic search / RAG (`dims`)        | `upsert` · `search(vector, topK?)` · `delete`          |
+<StoreFacets />
+
+Every facet accepts optional `description` — a human title in the Console
+(falls back to the store name). `store.index` also takes `dims`.
 
 ```typescript
-export const cache = store.kv("sessions");
+export const cache = store.kv("sessions", { description: "Session cache" });
 export const uploads = store.files("attachments");
-export const embeddings = store.index("docs", { dims: 1536 });
+export const embeddings = store.index("docs", {
+  dims: 1536,
+  description: "Document embeddings",
+});
 ```
 
 ## CRUD without boilerplate — `store.resource`
@@ -175,6 +176,7 @@ The recommended path: declare tables ORM-agnostically, then let `oke db` emit re
 | `.default(v)` · `.defaultFn(id \| now)`      | defaults                                        |
 | `.pii()` · `.sensitive()` · `.retain("30d")` | privacy classification                          |
 | `.as("sql_name")`                            | override the automatic `camelCase → snake_case` |
+| `.describe("…")`                             | human title in the Console (falls back to key)  |
 | `.references(() => col, { onDelete })`       | foreign key                                     |
 
 ### Foreign keys and relations
@@ -242,6 +244,65 @@ drivers: {
 
 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                                             |
+| -------- | -------------------------------------------------------- | ------------ | ------------------------------------------------------ |
+| `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>
+
+A SQL-backed index 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" },
+  },
+},
+```
+
+| `store.index` id | Shares connection from     | Real ANN via                         |
+| ---------------- | -------------------------- | ------------------------------------ |
+| `memory`         | — (in-process, default)    | —                                    |
+| `pgvector`       | `postgres` or `pglite` sql | HNSW + `cosineDistance`              |
+| `libsql`         | `libsql` sql               | `libsql_vector_idx` + `vector_top_k` |
+
+**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 `memory`.
+
+### Full-text search — `meilisearch` (opt-in)
+
+`meilisearch` is a fourth `store.index` backend, opt-in only — `memory` stays the default. It is a genuinely different capability from the vector ANN drivers: typo-tolerant, faceted full-text relevance, not cosine similarity. The two models are kept apart by a **discriminated union** on `driverId`, so TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at runtime:
+
+| `driverId`                       | `upsert`              | `search`                                 | `score` means               |
+| -------------------------------- | --------------------- | ---------------------------------------- | --------------------------- |
+| `memory` / `pgvector` / `libsql` | `(id, vector, meta?)` | `search(vector, topK?)` → `IndexHit[]`   | cosine similarity           |
+| `meilisearch`                    | `(id, document)`      | `search(q, opts?)` → `{ hits, facets? }` | relevance (`_rankingScore`) |
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    index: { local: "meilisearch", docker: "meilisearch", prod: "meilisearch" },
+  },
+},
+images: {
+  "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`.
+- **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`.
+
 ## Privacy built in
 
 Columns tagged `.pii()` or `.sensitive()` are masked at the store boundary — flows, logs, and the Console see a mask, not the value. Revealing cleartext PII requires an explicit `pii:reveal` gate on the flow, so access is a permission, not a convention.

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

@@ -55,7 +55,9 @@ 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`:
+Flows read secrets through `fx.vault` — never through `process.env`. `fx.vault` returns 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:
 
 ```typescript title="src/flows/billing/charge.ts"
 export const charge = on(
@@ -64,14 +66,17 @@ export const charge = on(
     in: ChargeInput,
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {
-      const key = fx.vault(stripeKey); // cleartext, inside this flow only
-      const intent = await stripe(key).create(input);
+      const key = fx.vault(stripeKey); // Redacted — safe to pass to fx.log
+      const intent = await stripe(key.reveal()).create(input);
       return { id: intent.id };
     },
   }),
 );
 ```
 
+`fx.log` masks any `Redacted` found in the logged data (nested included). A revealed string that
+still reaches `fx.log` is scrubbed by the boot redactor as before.
+
 </Step>
 
 </Steps>
@@ -91,7 +96,7 @@ That's the whole loop: declare → set → read. Everything below is what OKE gu
 
 | Option        | Type                  | Meaning                                                                  |
 | ------------- | --------------------- | ------------------------------------------------------------------------ |
-| `description` | string                | Shown in boot-gap listings and the Console                               |
+| `description` | string                | Human title in boot-gap listings and the Console (falls back to the key) |
 | `rotate`      | string                | Rotation hint (`"90d"`) — drives the rotation-due signal in the Console  |
 | `schema`      | zod / Standard Schema | Validated at boot; a bad value fails boot like a missing one             |
 | `dev`         | string                | Local-only fallback when no source provides a value (never used in prod) |
@@ -111,13 +116,7 @@ export const dbUrl = vault.secret("DATABASE_URL", {
 
 At boot, each contract is resolved through this chain — **first hit wins**:
 
-| #   | Source               | Typical content                                   |
-| --- | -------------------- | ------------------------------------------------- |
-| 1   | `process.env`        | Real environment (CI, hosting platform)           |
-| 2   | `.env.local`         | Your machine's local overrides (gitignored)       |
-| 3   | `docker/.env.docker` | Generated compose stack credentials               |
-| 4   | vault driver         | OpenBao in docker/prod mode                       |
-| 5   | `dev` fallback       | The `dev:` option on the contract (never in prod) |
+<VaultResolution />
 
 If every layer misses a contract, boot **fails** before any request is served:
 
@@ -167,7 +166,7 @@ vault: {
 | `openbao` | OpenBao (KV v2) | Docker + prod — durable, access-controlled |
 | `memory`  | in-process map  | Tests                                      |
 
-Other drivers (`infisical`, `managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
+Other drivers (`managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
 
 ## OpenBao in docker and prod