okengine 0.3.4 → 0.3.6

package/AGENTS.md

@@ -92,3 +92,7 @@ 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`.

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.4",
+  "version": "0.3.6",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "repository": {
@@ -59,7 +59,6 @@
     "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",
     "dev": "bun run --cwd site dev",
     "site:build": "bun run --cwd site build",
-    "ci:workflow": "bun scripts/ci.ts --workflow",
     "ci": "bun scripts/ci.ts",
     "bump": "bun run scripts/bump-version.ts",
     "release": "bun run scripts/publish.ts",
@@ -80,6 +79,9 @@
     "@codemirror/state": "^6.7.1",
     "@codemirror/theme-one-dark": "^6.1.3",
     "@codemirror/view": "^6.43.6",
+    "@electric-sql/pglite": "^0.5.4",
+    "@electric-sql/pglite-pgvector": "^0.0.5",
+    "@libsql/client": "^0.17.4",
     "@oxc-project/types": "^0.141.0",
     "@playwright/test": "^1.62.0",
     "@sinclair/typebox": "^0.34.52",
@@ -113,12 +115,24 @@
     "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,14 @@ 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 four 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 the current version + docs sync via `oke-docs`        |
 
 ## AGENTS.md — the root contract
 
@@ -21,14 +22,15 @@ 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. The three 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` |
 
-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/channel.mdx

@@ -71,10 +71,11 @@ 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
 

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

@@ -98,6 +98,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:
@@ -195,6 +196,8 @@ Everything a flow may touch, on one object:
 | `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)    |
 
@@ -227,6 +230,8 @@ export const chargeOrder = flow({
 
 **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 +256,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

@@ -74,10 +74,14 @@ A denied request never reaches `do`. It returns one of three typed failures, lik
 
 ## 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 +101,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

@@ -86,13 +86,14 @@ The declaration is identical in shape for all three — switching physics later
 
 ### 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,23 @@ 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`          |
+| 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, opts?)`    | a key-value space | cache, sessions, rate limits          | `get` · `set(key, value, ttl?)` · `delete` · `list`    |
+| `store.files(name, opts?)` | 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`          |
+
+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 +181,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 +249,39 @@ 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`.
+
 ## 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

@@ -91,7 +91,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) |

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -46,8 +46,8 @@ A client whose IP is not on the list receives `403` with a typed denial:
 <Callout type="error">
   Standard reverse proxies **append** to `X-Forwarded-For` — left-side hops are attacker-controlled.
   The plugin trusts the hop `trustedProxyDepth` from the **right** (default `1` = last hop). Set
-  this to your real proxy count; wrong depth bypasses the allowlist — topology-dependent, not
-  drop-in.
+  this to your real proxy count — wrong depth bypasses the allowlist (topology-dependent, not
+  drop-in).
 </Callout>
 
 ## Notes

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

@@ -36,10 +36,10 @@ drivers: {
 
 | Key                | Shape          | Driver ids (verified)                                                        |
 | ------------------ | -------------- | ---------------------------------------------------------------------------- |
-| `store.sql`        | env driver map | `sqlite` · `postgres` · `memory`                                             |
+| `store.sql`        | env driver map | `sqlite` · `postgres` · `libsql` · `pglite` · `memory`                       |
 | `store.kv`         | env driver map | `memory` · `redis`                                                           |
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector`                                                        |
+| `store.index`      | env driver map | `memory` · `pgvector` · `libsql`                                             |
 | `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
 | `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
 | `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |

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

@@ -18,8 +18,16 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 | `DATABASE_URL`      | Postgres connection (`postgres` driver, drizzle-kit) | `postgres://localhost:5432/oke` |
 | `OKE_STORE_SQL_URL` | Explicit SQL URL override                            | —                               |
 | `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                      |
 
+## Index store
+
+| Variable           | Used for                  | Default when unset |
+| ------------------ | ------------------------- | ------------------ |
+| `OKE_INDEX_DRIVER` | Force the index driver id | config map         |
+
 ## KV store
 
 | Variable           | Used for                 | Default when unset |

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

@@ -41,8 +41,48 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | ---------------------------- | ------- | ----------------------------------------------------- |
 | `fx.call(flow, input?)`      | `call`  | The callee's `out` — runs through the same pipeline   |
 | `fx.step(name, fn)`          | —       | Durable step: replays from the journal, never re-runs |
+| `fx.all([...thunks])`        | —       | Parallel; first rejection aborts siblings             |
+| `fx.race([...thunks])`       | —       | First settle wins; losers aborted                     |
+| `fx.retry(fn, opts?)`        | —       | Exponential backoff + jitter (plain Promise)          |
+| `fx.signal`                  | —       | Ambient `AbortSignal` for the current branch          |
 | `fx.fail(code, data, opts?)` | —       | Typed failure value (`opts.message` overrides)        |
 
+## Concurrency and retry
+
+Pass **thunks** to `all` / `race` — not already-started Promises — so each branch gets an abort scope before work begins.
+
+```typescript
+const [user, stock] = await fx.all([
+  () => fx.store(db).findById(users, input.userId),
+  () => fx.store(db).findById(inventory, input.sku),
+]);
+
+const charge = await fx.step("charge", () =>
+  fx.retry(() => fx.call(stripeCharge, { amount: input.total }), {
+    retries: 3,
+    delay: "100ms",
+    backoff: 2,
+    jitter: true,
+  }),
+);
+```
+
+| `fx.retry` option | Default | Meaning                                      |
+| ----------------- | ------- | -------------------------------------------- |
+| `retries`         | `0`     | Extra attempts after the first               |
+| `delay`           | `50`    | Initial backoff — ms number or `"100ms"`     |
+| `backoff`         | `2`     | Multiplier after each retry                  |
+| `jitter`          | `true`  | Full jitter on the delay (thundering-herd)   |
+| `when`            | thrown  | Predicate; skips `AbortError` and sleep park |
+
+<Callout title="Cooperative cancel">
+  Losing branches see `fx.signal` abort. Drivers that do not yet honor the signal may still finish
+  in the background — check `fx.signal.aborted` in long user work, and prefer `fx.all` over bare
+  `Promise.all`.
+</Callout>
+
+**Consequence:** put `fx.retry` inside `fx.step` on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is `flow({ retry: { … } })` on the same journal session.
+
 ## Channel
 
 | Signature                                 | Records | Notes                                                               |

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

@@ -64,22 +64,22 @@ Plugin flows appear in the Manifest, plugin tables land in `schema.generated.ts`
 
 Every method below exists on both the fluent definition and the boot-time builder the registry records:
 
-| Method                           | Contributes                                         |
-| -------------------------------- | --------------------------------------------------- |
-| `.flow(def)`                     | An ordinary flow — Manifest, Console, client types  |
-| `.hook(stage, fn)`               | A per-request intercept at one pipeline stage       |
-| `.edge(fn)`                      | A handler for HTTP requests that match **no** flow  |
-| `.decorate(key, value)`          | A typed context decoration, visible to flows        |
-| `.element({ kind, name })`       | An element contribution (e.g. `store.sql` facet)    |
-| `.driver(id, impl)`              | A protocol-named driver for an existing element     |
-| `.image(role, recipe)`           | An image recipe for a docker role                   |
-| `.table(name, columns, options)` | A whole DB table, merged into the generated schema  |
-| `.errors(map)`                   | Typed errors flows can fail with                    |
-| `.client(name, ext)`             | A typed client extension                            |
-| `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)       |
-| `.cli(name, handler)`            | An `oke <name>` CLI command                         |
-| `.config(schema)`                | A config schema; values live on the plugin identity |
-| `.needs(dep)`                    | A declared dependency (e.g. `"store.kv"`)           |
+| Method                           | Contributes                                                                                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------- |
+| `.flow(def)`                     | An ordinary flow — Manifest, Console, client types                                            |
+| `.hook(stage, fn)`               | A per-request intercept at one pipeline stage                                                 |
+| `.edge(fn)`                      | A handler for HTTP requests that match **no** flow                                            |
+| `.decorate(key, value)`          | A typed context decoration, visible to flows                                                  |
+| `.element({ kind, name })`       | An element contribution (e.g. `store.sql` facet)                                              |
+| `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
+| `.image(role, recipe)`           | An image recipe for a docker role                                                             |
+| `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
+| `.errors(map)`                   | Typed errors flows can fail with                                                              |
+| `.client(name, ext)`             | A typed client extension                                                                      |
+| `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)                                                 |
+| `.cli(name, handler)`            | An `oke <name>` CLI command                                                                   |
+| `.config(schema)`                | A config schema; values live on the plugin identity                                           |
+| `.needs(dep)`                    | A declared dependency (e.g. `"store.kv"`)                                                     |
 
 New infrastructure is a **driver** for an existing element, never a ninth element — plugins follow the same law.
 
@@ -194,11 +194,11 @@ A plugin may declare **its own tables** with `field.*` columns, merged into the
 plugin("billing", { version: "2.1.0" }).table(
   "invoices",
   { id: field.text().primaryKey().defaultFn(id) },
-  { plane: "user" },
+  { plane: "user", description: "Customer invoices" },
 );
 ```
 
-Extending an existing **app-owned** table with plugin columns is not supported in v1 — contribute a separate table and reference the app's by key. The optional `plane` metadata (`"operator" | "user" | "shared"`) keeps data-plane isolation intact for privacy tooling.
+Extending an existing **app-owned** table with plugin columns is not supported in v1 — contribute a separate table and reference the app's by key. The optional `plane` metadata (`"operator" | "user" | "shared"`) keeps data-plane isolation intact for privacy tooling. Optional `description` is a human title in the Console (falls back to the table name).
 
 ## Identity, config, and dependencies