okengine 0.11.1 → 0.12.0

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

@@ -25,6 +25,81 @@ name).
 
 The relational facet: tables, schema, and typed single-table sessions through `fx.store`.
 
+The Console SQL band opens a query console (`POST /console/store/sql`) for
+DML and DDL. ⌘Enter runs the current statement or selection; ⌘⇧Enter runs
+the whole script sequentially and stops on the first error.
+
+EXPLAIN / EXPLAIN ANALYZE wrap the current statement. A script with more
+than one result opens a tab per statement.
+
+The table grid can insert a row (`POST /console/store/edit` without `id`).
+Double-click a tab to rename; Save keeps named queries. Completions cover
+Manifest tables, columns, and keywords.
+
+Classified PII stays masked unless the toolbar **PII** control is on
+(`revealPii: true`, audited).
+
+**Gate** views the result as Operator (default, bypasses RLS), public, a
+selected user (via their matching policy), or a Manifest policy gate.
+`asGate` sets `oke.gate` on postgres / pglite for `current_setting('oke.gate', true)`.
+
+The SQL band **Schema** control opens a visualizer of Manifest tables and
+relations — declared `.references()` plus inferred `*_id` columns — not the
+query-console Schema rail.
+
+<Callout title="Query performance">
+  SQL **Performance** reads `pg_stat_statements` and live locks
+  (`QUERY /console/store/sql/stats` and `/locks`).
+
+Alpine needs preload plus `CREATE EXTENSION`. Index Advisor is opt-in on
+[Postgres](/docs/recipes/postgres#query-performance).
+
+KV **Performance** reads Redis-wire `INFO` / `COMMANDSTATS` / `SLOWLOG`
+(`QUERY /console/store/kv/stats`). In-process `memory` is unsupported.
+
+INFO is instance-wide (`StoreKvStatsServerWideGap`). SLOWLOG args collapse
+until reveal (`StoreKvStatsSlowlogArgsGap`). No hot-key table.
+
+</Callout>
+
+**Colorize** groups tables by prefix and FK family. Click a related table to
+dim the rest; click the canvas to show all again.
+
+Edges mark cardinality with icons (many-to-one, one-to-one, many-to-many,
+self). Cards and the query Schema rail mark primary (key), foreign (link),
+and unique (diamond) columns.
+
+Each SQL store also lists **Indexes**, **Functions**, **Triggers**,
+**Extensions**, and **RLS Policies**.
+
+Indexes, Functions, and Triggers use the same flat form as RLS Policies —
+paired fields, compact templates, and a pinned SQL editor — then run
+`CREATE INDEX` / `CREATE FUNCTION` / `CREATE TRIGGER`.
+
+**Advanced** unlocks the leftover Postgres knobs (`CONCURRENTLY` / `INCLUDE`,
+`SECURITY DEFINER` / `PARALLEL`, `CONSTRAINT` / `UPDATE OF`).
+
+Extensions list built-in contrib plus a **Library** (featured cards, search,
+category filter) for TimescaleDB, PostGIS, and `pg_cron`.
+
+Install reviews the `CREATE EXTENSION` SQL; **Advanced** can set `SCHEMA`,
+`VERSION`, and `CASCADE` (`pg_catalog` is refused).
+
+When a newer packaged version exists, the name chip shows **Upgrade**
+(`ALTER EXTENSION … UPDATE`). Names link to the project or Postgres docs.
+
+Each SQL table row shows whether Postgres RLS is on (emerald shield)
+or off (muted shield). KV, files, and index have no badge. Enabling
+RLS on create flips that shield.
+
+**RLS Policies** lists `pg_policies`. Create policy pins the SQL preview;
+**Templates** slides a flush library beside it (every `FOR` command, owner,
+`oke.gate`). Or edit `roles` / `USING` / `WITH CHECK` in the grid (`ALTER POLICY`).
+
+Create policy picks a Gate posture (Read / Write / Both), or **Policy &
+scope** for `gate.public`, `gate.policy`, and `gate.scope`. `TO public`
+stays on the SQL — those picks are not Postgres roles.
+
 ### Quick start
 
 <Steps>
@@ -115,24 +190,25 @@ const notesR = store.resource(db, notes, {
     filter: "all", // ?col=op.value — "all" | Column[] | "none"
     order: "all", // ?order=col.desc
   },
-  unit: "notes",
 });
 
-const mounted = on(http.resource("/notes", notesR.all()));
+const mounted = on(http.resource("/notes", notesR.all()).gate.public.live());
 ```
 
+`.gate(...)` / `.live()` chain like `http.get` — gates on every verb, live on list and get.
+
 The list endpoint's URL is the whole query language:
 
-| Param                               | Meaning                                             | Example                 |
-| ----------------------------------- | --------------------------------------------------- | ----------------------- |
-| `?cursor=` / `?offset=` / `?limit=` | paginate (keyset when `cursor` columns are set)     | `?limit=20&cursor=eyJ…` |
-| `?search=` (`?q=`)                  | substring match over `search` columns               | `?q=invoice`            |
-| `?col=op.value`                     | filter — ops `eq ne gt gte lt lte like ilike in is` | `?title=like.%draft%`   |
-| `?or=(…)` / `?and=(…)`              | grouped boolean filters                             | `?or=(a.eq.1,b.eq.2)`   |
-| `?order=`                           | sort                                                | `?order=createdAt.desc` |
-| `?select=`                          | project columns                                     | `?select=id,title`      |
+| Param                               | Meaning                                                   | Example                               |
+| ----------------------------------- | --------------------------------------------------------- | ------------------------------------- |
+| `?cursor=` / `?offset=` / `?limit=` | paginate (keyset when `cursor` columns are set)           | `?limit=20&cursor=eyJ…`               |
+| `?search=` (`?q=`)                  | substring match over `search` columns                     | `?q=invoice`                          |
+| `?col=op.value`                     | filter — `eq neq gt gte lt lte like ilike in is` + `not.` | `?title=like.*draft*`                 |
+| `?or=(…)` / `?and=(…)`              | grouped filters, nested `not.and` / `not.or`              | `?or=(a.eq.1,not.and(b.gt.2,c.lt.9))` |
+| `?order=`                           | sort (`col.desc`, comma-separated)                        | `?order=createdAt.desc`               |
+| `?select=`                          | project columns                                           | `?select=id,title`                    |
 
-Responses follow the Stripe-style envelope: `{ data, meta: { nextCursor, hasNextPage }, error }`. `create` answers **201**, `remove` answers **204**, and a missing row is a typed `NotFound` — never a crash.
+Responses follow the Stripe-style envelope: `{ data, meta, error }`. Clients page with `page.next()` or `for await (const page of api.notes.list({ limit: 20 }))` — `meta.next` / `meta.prev` are the next request (`{ cursor }`), not flags. `mode` is diagnostic. `create` answers **201**, `remove` answers **204**, and a missing row is a typed `NotFound` — never a crash.
 
 #### An admin table
 
@@ -158,9 +234,37 @@ list: { mode: "offset", filter: "none", limit: 20 },
 
 **Consequence:** a request that filters on a forbidden column — `?secret=eq.x` — fails with **422** and the exact message `unknown list param "secret"`. Filterable columns are a whitelist, never an accident.
 
+### Handwritten HTTP lists
+
+`store.resource` is the usual CRUD path. When you write the list Flow yourself, prefer the same Stripe envelope — `out` is the item array, pagination sits on `meta`:
+
+```typescript
+export const list = on(
+  http.get("/notes").gate.public,
+  flow("notes.list", {
+    out: z.array(Note),
+    do: async (input, fx) => {
+      const rows = await fx.store(db).select().from(notes);
+      return fx.json.withQuery(rows, input);
+    },
+  }),
+);
+```
+
+Zero-config: `?q=` searches every string field, extra keys auto-eq except path `id`, and PostgREST `?col=op.value` / `?order=` / `?select=` are open. Nested lists filter the parent in the load — `input.id` is not a column eq.
+
+<Callout title="Preferred, not required">
+  Any declared `out` is valid — `{ notes: […] }` still works. The array + `fx.json.withQuery`
+  shape matches `store.resource` and the typed client (`data` is the page, `meta` is the pager).
+</Callout>
+
+**Consequence:** returning `{ items, count }` from `do` nests as `{ data: { items, count }, error: null }` — the pager is no longer top-level `meta`.
+
+`fx.json.with({ data, meta })` stays for a page you already built. A third argument locks the surface or switches to keyset (`mode: "cursor"`, `cursor: ["createdAt", "id"]`).
+
 ### Querying by hand
 
-When `store.resource` is too conventional, `fx.store(db)` is the full single-table session:
+When the list is not conventional CRUD, `fx.store(db)` is the full single-table session:
 
 ```typescript
 // select — chain where / orderBy / limit / offset in any order
@@ -232,9 +336,9 @@ 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` 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.drizzle.ts`.
+`oke dev` auto-pushes on schema _inputs_ (`schema.decl.ts`, hand-written `schema.ts`,
+`app.ts` plugin tables, `drizzle.config.ts`) — not when emit rewrites `schema.drizzle.ts`.
+A `schema.decl.ts` error prints `schema.decl.ts has an error — …` (red ●) and keeps running.
 
 Opt out with `--no-db-push` or `db: { autoPush: false }`. `prod` **never**
 auto-applies DDL; a missing table fails as **OKE1101** (`oke db migrate`).
@@ -267,8 +371,8 @@ Not wired this round — readiness only.
 
 #### Seeding
 
-`oke db seed` loads `defineSeed` from `src/seed/index.ts` — **never at boot**.
-Seed proves existence (bootstrap rows); it does not correct schema-adjacent data over time.
+`oke db seed` loads `defineSeed` from `src/db/seed/index.ts` — **never at boot**.
+`name` is this app's seed (template or example). The prompt and `.oke/state.json` key off it.
 
 <StoreSeeding />
 
@@ -288,6 +392,8 @@ import { db } from "../core";
 import { notes } from "../schema.decl";
 
 export default defineSeed({
+  name: "notes",
+  description: "Welcome + sample notes",
   essential: async (fx: Fx) => {
     await fx
       .store(db)
@@ -319,6 +425,8 @@ import { seedSamples } from "./dev/samples";
 import { seedWebhook } from "./prod/webhook";
 
 export default defineSeed({
+  name: "notes",
+  description: "Welcome + sample notes",
   essential: [seedWelcome],
   dev: [seedSamples],
   prod: [seedWebhook],
@@ -419,6 +527,12 @@ SQL-backed index driver `pgvector` shares this facet's connection — see [Advan
 The key-value facet: short-lived cache and session data behind `fx.store`. One namespace per
 declaration; drivers swap `memory` ↔ `redis` per environment.
 
+The Console KV band opens a query console for `list`, `get`, `set`, `delete`, and `ttl`.
+Prettify rewrites commands to call form and indents `set` JSON.
+
+The same band’s **Performance** control opens engine telemetry on the `redis`
+driver. In-process `memory` is unsupported (`KvStatsUnsupported`).
+
 ### Quick start
 
 <Steps>
@@ -452,17 +566,19 @@ do: async ({ userId, data }, fx) => {
 
 ### Handle API
 
-| Call                    | Effect  | Returns    | Notes                                     |
-| ----------------------- | ------- | ---------- | ----------------------------------------- |
-| `get(key)`              | `read`  | `unknown`  | Missing keys resolve per driver           |
-| `set(key, value, ttl?)` | `write` | `void`     | Values should be JSON-serializable        |
-| `delete(key)`           | `write` | `boolean`  | Whether a key was removed                 |
-| `list(prefix?)`         | `read`  | `string[]` | Prefix filter; powers the Console browser |
+| Call                    | Effect  | Returns          | Notes                                                                    |
+| ----------------------- | ------- | ---------------- | ------------------------------------------------------------------------ |
+| `get(key)`              | `read`  | `unknown`        | Missing keys resolve per driver                                          |
+| `set(key, value, ttl?)` | `write` | `void`           | Values should be JSON-serializable                                       |
+| `delete(key)`           | `write` | `boolean`        | Whether a key was removed                                                |
+| `list(prefix?)`         | `read`  | `string[]`       | Prefix filter; Console browse shows TTL and size                         |
+| `ttlMs(key)`            | `read`  | `number \| null` | Remaining expiry; `null` when the key has none. Console command is `ttl` |
 
 ### TTL
 
 Optional third argument on `set` is a duration string: `(\d+)(ms|s|m|h|d)` — e.g. `"30m"`, `"1h"`,
-`"5000ms"`. Same call — opposite physics under each driver:
+`"5000ms"`. Same call — opposite physics under each driver. Console KV browse edits that TTL
+(empty clears expiry) and can add a key through the same `set` path.
 
 <StoreKvTtl />
 
@@ -542,7 +658,8 @@ Dragonfly are equally legitimate opt-in pins.
 <StoreFacetMark facet="files" />
 
 The blob facet: opaque objects (`Uint8Array` or string) on the same handle as the optional image
-pipeline. Drivers swap `fs` ↔ `s3` (plus `memory` for tests).
+pipeline. Drivers swap `fs` ↔ `s3` (plus `memory` for tests). The Console Files band is a folder
+browser — upload, download, delete — not a signed-URL mint.
 
 ### Quick start
 
@@ -579,12 +696,12 @@ do: async ({ key, body }, fx) => {
 
 ### Blob CRUD — `put` / `get` / `delete` / `list`
 
-| Call             | Effect  | Returns              | Notes                                |
-| ---------------- | ------- | -------------------- | ------------------------------------ |
-| `put(key, data)` | `write` | `void`               | `data` is `Uint8Array` or `string`   |
-| `get(key)`       | `read`  | `Uint8Array \| null` | Missing key → `null`                 |
-| `delete(key)`    | `write` | `boolean`            | Whether an object was removed        |
-| `list(prefix?)`  | `read`  | `string[]`           | Prefix filter; Console browse source |
+| Call             | Effect  | Returns              | Notes                                        |
+| ---------------- | ------- | -------------------- | -------------------------------------------- |
+| `put(key, data)` | `write` | `void`               | `data` is `Uint8Array` or `string`           |
+| `get(key)`       | `read`  | `Uint8Array \| null` | Missing key → `null`                         |
+| `delete(key)`    | `write` | `boolean`            | Whether an object was removed                |
+| `list(prefix?)`  | `read`  | `string[]`           | Prefix filter; Console folder browser source |
 
 ```typescript
 const files = fx.store(uploads);
@@ -598,11 +715,12 @@ await files.delete("docs/readme.txt");
 
 Keys are opaque strings the driver stores as-is. Prefer path-like prefixes (`photos/`, `exports/`).
 
-| Helper / rule               | Meaning                                                                  |
-| --------------------------- | ------------------------------------------------------------------------ |
-| `contentAddressedKey(data)` | From `okengine/store` — stable sha256 hex of the bytes (dedupe-friendly) |
-| Leading `/` or `..`         | Rejected by the `fs` driver (`Invalid object key`)                       |
-| Non-ASCII keys              | Console warns `non_ascii_key` — may break S3 signed URLs                 |
+| Helper / rule                      | Meaning                                                                                                                                                  |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `contentAddressedKey(data)`        | From `okengine/store` — stable sha256 hex of the bytes (dedupe-friendly)                                                                                 |
+| `safeFileObjectKey(name, prefix?)` | URL-safe ASCII key (`file-a1b2c3d4.pdf`). Keep the original name in the catalog.                                                                         |
+| Leading `/` or `..`                | Rejected by the `fs` driver (`Invalid object key`)                                                                                                       |
+| Non-ASCII keys                     | Console warns `non_ascii_key`. Console puts rewrite the key and store `originalName` in `.oke/catalog.json` (and `file_objects` when that table exists). |
 
 ### Per-environment Files drivers
 
@@ -613,7 +731,7 @@ drivers: {
   },
 },
 images: {
-  store: { files: "rustfs/rustfs:1.0.0-beta.11" },
+  store: { files: "rustfs/rustfs:1.0.0-rc.2" },
 },
 ```
 
@@ -632,9 +750,9 @@ images: {
 
 **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
-  not patched.
+<Callout title="Console Files is a folder browser">
+  Inspect the **bucket**. Click a file to preview in a sheet. Uploads use a URL-safe key; the
+  original name lives in the object catalog. Bytes live on `memory`, `fs`, or `s3`.
 </Callout>
 
 ### Images — `image` / `putImage`
@@ -732,11 +850,17 @@ One declaration shape — two search physics. The handle is a **discriminated un
 
 <StoreIndexModes />
 
-| Call (both)  | Effect  | Returns       |
-| ------------ | ------- | ------------- |
-| `upsert(…)`  | `write` | `void`        |
-| `search(…)`  | `read`  | hits / result |
-| `delete(id)` | `write` | `boolean`     |
+| Call (both)    | Effect  | Returns               |
+| -------------- | ------- | --------------------- |
+| `upsert(…)`    | `write` | `void`                |
+| `search(…)`    | `read`  | hits / result         |
+| `list(limit?)` | `read`  | documents (id + meta) |
+| `delete(id)`   | `write` | `boolean`             |
+
+<Callout title="Console Index is a search box">
+  Type a phrase to find documents by id and stored meta. A comma-separated vector still runs an ANN
+  probe. Meilisearch uses full-text `q`.
+</Callout>
 
 TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at
 runtime.
@@ -787,7 +911,7 @@ drivers: {
   },
 },
 images: {
-  store: { index: "getmeili/meilisearch:v1.37" },
+  store: { index: "getmeili/meilisearch:v1.53" },
 },
 ```
 
@@ -860,6 +984,12 @@ same PII masking — see the Callout under [Querying by hand](#querying-by-hand)
 ## Troubleshooting
 
 <Accordions>
+<Accordion title="Unable to resolve table name from value">
+
+A `store.schema.table` column named `name` used to shadow the SQL table name.
+Inserts and selects now resolve it from the declaration. Keep the `name` column.
+
+</Accordion>
 <Accordion title="OKE1101 — missing table in prod">
 
 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`.
@@ -879,6 +1009,11 @@ 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="List data is { items, count } instead of an array">
+
+Success already wraps `{ data, error: null }`. Returning a page object from `do` nests the pager inside `data`. Prefer `out: z.array(Item)` and `return fx.json.withQuery(rows, input)`. Any other declared `out` is still valid.
+
 </Accordion>
 <Accordion title="KV TTL never expires in tests">
 
@@ -899,6 +1034,16 @@ The vector length must match `store.index(…, { dims })` (runtime default `3` i
 
 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>
+<Accordion title="Console warns Non-ASCII object key">
+
+`fx.store(files).put` stores the key as-is. Console uploads mint an ASCII key and keep the original name in `.oke/catalog.json`. Re-upload to rewrite an existing object.
+
+</Accordion>
+<Accordion title="oke dev skipped the seed prompt">
+
+`.oke/state.json` stores `seededAt` plus this app's `defineSeed({ name })` — notes vs keel are different ids. A new name re-asks. Clear those keys to prompt again.
+
 </Accordion>
 </Accordions>
 

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

@@ -93,16 +93,44 @@ Call `.reveal()` once at the provider boundary that needs the credential.
 
 ## Two kinds of contracts
 
-| Declaration                         | Sensitive? | Console shows    | Use for                     |
-| ----------------------------------- | ---------- | ---------------- | --------------------------- |
-| `vault.secret("STRIPE_KEY", …)`     | yes        | fingerprint only | API keys, tokens, passwords |
-| `vault.config("PUBLIC_APP_URL", …)` | no         | cleartext value  | Public URLs, feature flags  |
+| Declaration                         | Sensitive? | Console shows                       | Use for                     |
+| ----------------------------------- | ---------- | ----------------------------------- | --------------------------- |
+| `vault.secret("STRIPE_KEY", …)`     | yes        | fingerprint only                    | API keys, tokens, passwords |
+| `vault.config("PUBLIC_APP_URL", …)` | no         | **Config** band, value in the clear | Public URLs, feature flags  |
 
 `vault(name, …)` is shorthand for `vault.secret(name, …)`.
 
+<Callout title="Config is the one place for non-secret variables">
+  `vault.config()` is the contract the Console **Config** band lists and edits. Declare it once; set
+  the value from Console, `oke vault set`, or the resolution chain. Do not use `vault.env` for
+  values you want to see or change on `/vault`.
+</Callout>
+
+```typescript title="src/vault.ts"
+export const publicAppUrl = vault.config("PUBLIC_APP_URL", {
+  description: "Public site origin",
+  dev: "http://127.0.0.1:6530",
+});
+```
+
+```bash title=".env.local"
+PUBLIC_APP_URL=https://app.example.com
+```
+
+```typescript title="src/flows/site/render.ts"
+do: async (_input, fx) => {
+  const origin = (await fx.vault.get(publicAppUrl)).reveal();
+  return { canonical: `${origin}/` };
+},
+```
+
+**Consequence:** `/vault` lists this under **Config** in the clear. `fx.vault.get` still
+returns `Redacted` — `.reveal()` is the read. `vault.env("PUBLIC_APP_URL")` never appears
+on that page.
+
 ### 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.
+`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 appears in the Console, never gets a fingerprint, and never gets redacted.
 
 | Call                             | Returns               | On a missing value                     |
 | -------------------------------- | --------------------- | -------------------------------------- |
@@ -116,13 +144,13 @@ Every name passed to `vault.env.required` is registered, so boot reports missing
 
 ### Contract options
 
-| Option        | Type                  | Meaning                                                                  |
-| ------------- | --------------------- | ------------------------------------------------------------------------ |
-| `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) |
-| `sensitive`   | boolean               | Override the default (`true` for secrets, `false` for config)            |
+| Option        | Type                  | Meaning                                                                                                                                          |
+| ------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | string                | Human title in boot-gap listings and the Console (falls back to the key)                                                                         |
+| `rotate`      | string                | Cadence (`"90d"`) or `"never"` when the secret must not rotate. Omit is the same as `"never"`. Console shows `no rotate` and skips `is:overdue`. |
+| `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)                                                                         |
+| `sensitive`   | boolean               | Override the default (`true` for secrets, `false` for config)                                                                                    |
 
 ### Zero-setup Compose fallback
 
@@ -136,7 +164,8 @@ export const dbUrl = vault.secret("DATABASE_URL", {
 
 ## Where values come from
 
-At boot, each contract is resolved through this chain — **first hit wins**:
+At boot, each contract is resolved through this chain — **first hit wins**.
+A value already in the vault / managed backend wins over a leftover env pin.
 
 <VaultResolution />
 
@@ -154,21 +183,65 @@ VaultBootError: 1 secret(s) missing:
 
 ## Setting and rotating values
 
-| 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                         |
+| 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 (exclusive lease) |
+| `oke vault audit` / `audit verify` / `audit purge` | Hash-chained audit (serialized appends; 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 (atomic write + end marker; separate backup KEK)             |
 
 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.
+The **Console** (`:6533`) **Vault** page (`/vault`) groups **Secrets** and
+**Config**. Secrets are write-only: a salted fingerprint (`sha256:…`), never
+the cleartext. Config rows show the value — that is `vault.config()`.
+
+Add (`+`) creates a contract from Console as well as from source. Those rows
+show `console` until you declare the same name in the Manifest.
+
+Search matches name, description, fingerprint, reader, and winner. Operators
+AND together. `/` focuses the field.
+
+| Token                                                  | Matches                         |
+| ------------------------------------------------------ | ------------------------------- |
+| `is:unset` / `is:set` / `is:healthy`                   | Value present or not            |
+| `is:blast` / `is:shared` / `is:dormant` / `is:overdue` | Posture                         |
+| `kind:secret` / `kind:config`                          | Contract kind                   |
+| `from:.env.local`                                      | Resolution winner               |
+| `reader:payments` / `fp:sha256`                        | Flow id / fingerprint           |
+| `has:readers` / `has:rotate`                           | Declared readers or rotate hint |
+
+The empty pane is a posture board (unset, blast, shared, dormant, overdue).
+Rotate shows **blast radius** — in-flight durable runs that will wake holding
+the new value.
+
+Verify, rotate-master, fingerprint export, and CLI copy live in the security
+sheet.
+
+| Action               | Confirm                      | HTTP                                                                       |
+| -------------------- | ---------------------------- | -------------------------------------------------------------------------- |
+| Add a contract       | review dialog                | `POST /console/vault/create` — lists as `console` until declared in source |
+| Set / rotate a value | reason + review dialog       | `POST /console/vault/set` · `/rotate`                                      |
+| Rotate master key    | `ROTATE_MASTER` + reason ≥ 3 | `POST /console/vault/rotate-master` — one batch; `remaining` is honest     |
+| Verify audit chain   | session only                 | `GET /console/vault/audit/verify` → `{ ok, brokenAt, reason, row }`        |
+
+Master rotation is process-global: any operator in the same Console process may
+continue. Overlapping batches return `VaultRotateBusy`. A generated master key
+is shown once and never logged.
+
+Backup stays on the CLI (`oke vault backup` / `restore`). The Console never
+accepts a master key in the HTTP body — unseal via `OKE_VAULT_MASTER_KEY`.
+
+<Callout title="Builtin concurrency (rotate / audit / backup)">
+  `rotate-master` uses SKIP LOCKED + lease TTL (one holder; crashed holders reclaim). Audit appends
+  under a transactional row lock. Backups use temp → fsync → rename with end marker + checksum —
+  restore rejects incomplete files before decrypt.
+</Callout>
 
 <Callout title="Builtin master keys and expired rows">
   Resolve the master key with `--key -` (stdin), `OKE_VAULT_MASTER_KEY`, or a hidden TTY prompt —
@@ -185,7 +258,7 @@ The **Console** (`:6533`) can also set and rotate values, but it is **write-only
 ## Per-environment drivers
 
 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):
+App boot and the Console share the same chain: **backend first**, then env files:
 
 ```typescript title="oke.config.ts"
 drivers: {
@@ -199,37 +272,48 @@ drivers: {
 
 Defaults are `env` / `memory` / `vault`. create-oke templates pin the built-in store for prod.
 
-| 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                              |
+| 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` | Official SM (`OKE_VAULT_PROVIDER`) or platform-injected env | Cloud SM / Fly / Railway / K8s     |
+| `memory`  | in-process map                                              | Tests                              |
 
 ### Threat model (honest)
 
 Built-in Vault protects a **database dump** (ciphertext + wrapped DEKs). It does **not** equal a separate process-isolated vault:
 
-| 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      |
+| Threat                                        | Built-in `vault`                   | Managed 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    |
 
-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.
+For production built-in stores, set `vault.encryption.masterKey` to a KMS source (optional peer
+`@aws-sdk/client-kms`) or use `managed` with a provider below. `oke doctor` warns when prod would
+take the master key from the environment.
 
 ## Managed providers (official)
 
-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.
+Set `drivers.vault` to `"managed"` and `OKE_VAULT_PROVIDER` to an id below. Omit the provider when
+the platform already injects secrets as env vars (Fly, Railway, Kubernetes).
+
+| Provider            | `OKE_VAULT_PROVIDER`  | Connection                                                                        | Optional peer                                 |
+| ------------------- | --------------------- | --------------------------------------------------------------------------------- | --------------------------------------------- |
+| AWS Secrets Manager | `aws-secrets-manager` | `OKE_VAULT_REGION`, `OKE_VAULT_MOUNT` (name prefix)                               | `@aws-sdk/client-secrets-manager`             |
+| Azure Key Vault     | `azure-key-vault`     | `OKE_VAULT_URL` (vault URI), `OKE_VAULT_MOUNT` (prefix)                           | `@azure/keyvault-secrets` + `@azure/identity` |
+| GCP Secret Manager  | `gcp-secret-manager`  | `OKE_VAULT_MOUNT` (`project` or `project/prefix`)                                 | `@google-cloud/secret-manager`                |
+| Doppler             | `doppler`             | `OKE_VAULT_TOKEN`; `OKE_VAULT_MOUNT` as `project/config` for personal tokens      | —                                             |
+| 1Password Connect   | `1password`           | `OKE_VAULT_URL` (Connect host), `OKE_VAULT_TOKEN`, `OKE_VAULT_MOUNT` (vault name) | —                                             |
+
+AWS, Azure, and GCP use that cloud's default credential chain. Azure names allow only letters,
+numbers, and hyphens — OKE maps `_` in the contract name to `-` on the wire.
 
 ## Community / plugin
 
-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`.
+OpenBao and HashiCorp Vault are not shipped in core. Implement a community adapter for the
+`managed` driver surface, or keep using built-in `vault` / `env`.
 
 ## Troubleshooting
 
@@ -240,12 +324,21 @@ A contract has no value in any layer of the chain. Fix by providing it in exactl
 
 - locally: add `NAME=value` to `.env.local` (or run `oke vault set NAME value`)
 - 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`)
+- CI / hosting: set a real environment variable (or the managed provider when `managed`)
+
+</Accordion>
+<Accordion title="Does the keel example put secrets in Vault?">
+
+Yes — this example only (prod posture). `oke db seed` (dev) writes the keel
+stubs and copies minted stack URLs into the built-in store. `.env.local` keeps
+`OKE_VAULT_MASTER_KEY` and `PORT`; other apps leave Vault empty.
 
 </Accordion>
 <Accordion title="How do I rotate a key safely?">
 
-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.
+Set the new value (`oke vault set` or the Console). The Console shows blast
+radius before you rotate, and `is:overdue` when a secret is past its
+`rotate: "90d"` hint. `rotate: "never"` (or omit `rotate`) shows `no rotate`.
 
 </Accordion>
 <Accordion title="How do I pass the builtin master key without shell history?">