okengine 0.11.2 → 0.13.0

package/site/content/docs/reference/cli.md

@@ -18,6 +18,7 @@ oke --help                       # command list (also what bare `oke` prints whe
 oke dev                          # watch · hot reload · Console :6533 · app :6530 · MCP :6535 · docs MCP :6536
                                  #   → always Docker Compose under docker/ + host Bun
                                  #   → client types + domain schema push on save
+                                 #   → Console UI hot-reloads from source (okengine checkout; no bun run build)
 oke dev --no-db-push             #     opt out of auto oke db push on schema input save
 oke dev -d store.sql,signal      #     optional role filter (still Compose; requires Docker)
 oke test                         # bun test with PGLite posture (NODE_ENV=test, OKE_PGLITE_URL=memory://)
@@ -26,13 +27,28 @@ oke mode                         # removed — prints error; use oke dev (Compos
 
 oke start                        # runs exactly what production runs (this is the Docker CMD)
 oke doctor                       # verify secrets, ports, drivers, tenancy, schema drift
+oke console claim-code           # print setup claim code from .oke/claim-code (after Console boot)
+                                 #   → `bun run dev:console` boots kernel + Vite with a fixed
+                                 #     operator (`dev@oke.dev` / `Okengine123!`) — Sign in (prefilled)
+                                 #   → `bun run dev:console:seed` same + keel PM (all 8 elements) + ~80 traces
+                                 #     + 500+ tasks + full CRUD / custom HTTP (GET·POST·PUT·PATCH·DELETE·HEAD·QUERY)
+                                 #     + app Gate auth / oke_* system tables
+                                 #     (form/github→tasks.create→notify chain, work-management
+                                 #     SQL/KV/files/index; `oke_console` is Console operators);
+                                 #     click Traces row → highlight chain on the radial hub;
+                                 #     click a unit / element disc → 1-hop neighborhood + filter runs;
+                                 #     Replay → waterfall playhead + chain pulse on the graph)
+                                 #   → `bun run dev:console:fresh` / `:fresh:seed` — claim from scratch
+                                 #     (no fixed operator; claim code printed in the boot log)
+                                 #   → after `bun run test:console:setup`, open the HTML report:
+                                 #     `bun run test:console:setup:report` (trace + screenshots + video)
 oke stack                        # preview resolved images/tags/ports — writes nothing
 
 oke schema generate              # core + plugin stubs → .oke/schema/oke.ts (--check in CI)
 oke db push                      # domain schema.ts → live DB (dev; drizzle-kit)
 oke db generate                  # versioned SQL under drizzle/ (review)
 oke db migrate                   # apply migrations (explicit; never auto in prod)
-oke db seed                      # defineSeed (essential + env category); never at boot
+oke db seed                      # this app's defineSeed (name + essential + env); never at boot
 oke db seed --env prod --force   # CI: skip prod confirmation prompt
 oke db studio                    # drizzle-kit Studio (long-running)
 oke vault set STRIPE_KEY         # also: list · import .env · key rotate
@@ -59,7 +75,21 @@ oke upgrade                      # run codemods for a breaking change, print the
 
 `oke replay` loads a Runs WideEvent by id and re-enters the Flow with stored
 input. Defaults to dry-run when the ledger has `send` / `ask` (pass `--live`
-to override). Needs a build that persisted `WideEvent.input`.
+to override). Needs a build that persisted `WideEvent.input`. Console Traces
+Replay (`POST /console/traces/replay`) uses the same `runReplay` path.
+
+`oke dev` request lines print the WideEvent / run id after the timestamp.
+Paste it into Traces or `oke replay --request-id`.
+
+`oke dev` bridges host-app WideEvents into Console Traces: the CLI starts
+Console first, mints a loopback ingest secret, and sets `OKE_RUNS_INGEST_URL` /
+`OKE_RUNS_INGEST_SECRET` on the host child so every recorded run POSTs to
+`POST /console/runs/ingest`. Console appends into its own runs store (live
+`feedRun` → PII-masked `projectRun` for `GET /console/runs` and
+`/console/live`). `listRuns` also reads host Parquet at `.oke/runs`, so
+Traces survive a Console restart. Production recording stays opt-in —
+`oke start` does not enable the bridge; set `oke({ runs })` or
+`drivers.runs` explicitly. `oke replay` reads the same `.oke/runs` tree.
 
 In development, app, Console, MCP, and docs MCP prefer the canonical ports and move upward
 when occupied. Docker infrastructure uses stable per-project offsets in disjoint ranges for
@@ -86,8 +116,8 @@ yellow pending/loading · red error · dim idle. Compose health keeps polling
 (`docker compose ps -a`); AI ● tracks model phase while the AI container is up.
 Boot does not wait for the model to become ready. A successful session writes
 `.oke/dev.json` (pid · ports · startedAt) and clears it on stop. Durable local
-markers live in `.oke/state.json` (e.g. `seededAt` after the one-shot seed
-prompt) — not in the session lock. Console session signing uses
+markers live in `.oke/state.json` (`seededAt` + `seed` after the one-shot
+prompt for this app's `defineSeed({ name })`) — not in the session lock. Console session signing uses
 `.oke/console.secret` (or `OKE_CONSOLE_SECRET`); that is not a Vault secret.
 
 On a TTY, Ink keyboard controls stay active after boot (`useInput` — same
@@ -125,8 +155,10 @@ On a TTY: pick **standard** or **advanced**, then recommended defaults or
 customize. Customize walks **Docker-first** facets once (including `store.index`
 with a `none` opt-out), then **AI setup**: Recommended (llama.cpp) · Customize ·
 Off. Writes user-global `~/.oke/create-defaults.json` (reuse only when `template`
-matches). Extra locales and PgDog answers are persisted on every TTY run — not
-only after customize. Non-TTY / `--yes` / explicit `--template` never prompt.
+matches). Recommended / customize also ask locales, PgDog, and reverse proxy
+(Caddy / Traefik / nginx / No); **reuse** applies the saved answers without
+re-asking. Flags: `--locales`, `--pgdog` / `--no-pgdog`, `--proxy` /
+`--no-proxy`. Non-TTY / `--yes` / explicit `--template` never prompt.
 
 ### Additional commands
 
@@ -136,6 +168,7 @@ oke doctor --json                # -j  JSON on stdout; hints on stderr (agents /
 oke stack --json                 # -j
 oke images list                  # recipe · image · tag · digest · size (--json|-j)
 oke gates list                   # Module:Action catalogue (--json|-j)
+oke console claim-code           # first-admin claim from .oke/claim-code (--json|-j)
 oke ai setup --provider llama-cpp --yes  # default local AI
 oke ai setup --provider ollama --yes     # fully supported alternative
 # TTY: llama.cpp / Ollama → banner · tiers · manual; vLLM / SGLang / cloud → model
@@ -155,34 +188,34 @@ oke completion fish | source
 
 Long form is canonical in docs; short form is convenience only. Shared letters follow git’s pattern (different meanings on different subcommands — e.g. `-c` is `--check` on `schema generate`, `--config` on `stack` / `docker` / `images`).
 
-| Long                 | Short | Where                                          |
-| -------------------- | ----- | ---------------------------------------------- |
-| `--docker`           | `-d`  | `dev` (optional Compose **role filter**)       |
-| `--no-db-push`       |       | `dev`                                          |
-| `--prod`             | `-p`  | `docker`                                       |
-| `--yes`              | `-y`  | `docker clean`                                 |
-| `--all`              |       | `docker clean`                                 |
-| `--port`             | `-p`  | `start`                                        |
-| `--check`            | `-c`  | `schema generate`                              |
-| `--config`           | `-c`  | `stack`, `docker`, `images`, `db *` (drizzle)  |
-| `--apply`            | `-a`  | `upgrade`                                      |
-| `--at`               | `-a`  | `branch`                                       |
-| `--after`            | `-a`  | `doctor --diff`                                |
-| `--target`           | `-t`  | `build`                                        |
-| `--diff`             |       | `doctor`                                       |
-| `--json`             | `-j`  | `doctor`, `stack`, `images list`, `gates list` |
-| `--manifest`         | `-m`  | most Manifest readers                          |
-| `--entry`            | `-e`  | `dev`, `start`, `build`, `replay`              |
-| `--request-id`       | `-r`  | `replay`                                       |
-| `--dry-run`          |       | `replay`                                       |
-| `--live`             |       | `replay`                                       |
-| `--out` / `--outdir` | `-o`  | writers                                        |
-| `--subject`          | `-s`  | `privacy erase`                                |
-| `--before`           | `-b`  | `doctor --diff`                                |
-| `--base`             | `-B`  | `doctor --diff`                                |
-| `--env`              |       | `db *` (`dev` \| `test` \| `prod`)             |
-| `--force`            |       | `db seed`                                      |
-| `--local` / `-l`     |       | **removed** on `dev` (use `oke test`)          |
+| Long                 | Short | Where                                                                |
+| -------------------- | ----- | -------------------------------------------------------------------- |
+| `--docker`           | `-d`  | `dev` (optional Compose **role filter**)                             |
+| `--no-db-push`       |       | `dev`                                                                |
+| `--prod`             | `-p`  | `docker`                                                             |
+| `--yes`              | `-y`  | `docker clean`                                                       |
+| `--all`              |       | `docker clean`                                                       |
+| `--port`             | `-p`  | `start`                                                              |
+| `--check`            | `-c`  | `schema generate`                                                    |
+| `--config`           | `-c`  | `stack`, `docker`, `images`, `db *` (drizzle)                        |
+| `--apply`            | `-a`  | `upgrade`                                                            |
+| `--at`               | `-a`  | `branch`                                                             |
+| `--after`            | `-a`  | `doctor --diff`                                                      |
+| `--target`           | `-t`  | `build`                                                              |
+| `--diff`             |       | `doctor`                                                             |
+| `--json`             | `-j`  | `doctor`, `stack`, `images list`, `gates list`, `console claim-code` |
+| `--manifest`         | `-m`  | most Manifest readers                                                |
+| `--entry`            | `-e`  | `dev`, `start`, `build`, `replay`                                    |
+| `--request-id`       | `-r`  | `replay`                                                             |
+| `--dry-run`          |       | `replay`                                                             |
+| `--live`             |       | `replay`                                                             |
+| `--out` / `--outdir` | `-o`  | writers                                                              |
+| `--subject`          | `-s`  | `privacy erase`                                                      |
+| `--before`           | `-b`  | `doctor --diff`                                                      |
+| `--base`             | `-B`  | `doctor --diff`                                                      |
+| `--env`              |       | `db *` (`dev` \| `test` \| `prod`)                                   |
+| `--force`            |       | `db seed`                                                            |
+| `--local` / `-l`     |       | **removed** on `dev` (use `oke test`)                                |
 
 ### Exit codes
 

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

@@ -79,6 +79,9 @@ With the starter, that is `GET /health` on port **6530** when `$routes` are wire
 `oke dev` regenerates `oke-client.d.ts` from `GET /_oke/client.json`. A separate frontend repo
 runs `oke client add <url>` (default out: `oke-client.d.ts`).
 
+create-oke starters ship `web/`: Vite owns `index.html` and proxies `/notes` ·
+`/health` · `/_oke` to the app. Use `createClient("")` so the browser stays same-origin.
+
 ```bash
 oke client add http://localhost:6530
 oke client add https://api.example.com --out ./types/oke-client.d.ts
@@ -104,11 +107,11 @@ oke client add https://api.example.com --out ./types/oke-client.d.ts
 
 ## REST vs RPC
 
-| Situation                                          | Request                                                                                                  |
-| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| HTTP trigger with method + path on `$routes`       | That method and path (`:id` filled from input; leftover fields → query on GET/HEAD, JSON body otherwise) |
-| Adopted flow with no HTTP trigger                  | `POST {base}/_oke/{unit}/{flow}` with JSON body                                                          |
-| Incomplete proxy path (`api.notes()` with no flow) | Result error: `Incomplete path: api.notes(…)`                                                            |
+| Situation                                          | Request                                                                                                                                                        |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| HTTP trigger with method + path on `$routes`       | That method and path (`:id` filled from input; leftover fields → query on GET/HEAD, JSON body otherwise). QUERY always sends JSON (`{}` when only path params) |
+| Adopted flow with no HTTP trigger                  | `POST {base}/_oke/{unit}/{flow}` with JSON body                                                                                                                |
+| Incomplete proxy path (`api.notes()` with no flow) | Result error: `Incomplete path: api.notes(…)`                                                                                                                  |
 
 ```typescript
 // REST — createClient(app, url) saw method/path from on(http.get("/notes/:id"), …)
@@ -223,16 +226,32 @@ core today: cookie jars or plugin `.client()` decorations. Browser apps: also se
 Mount a resource, adopt the returned ops, then call the five Flows like any other:
 
 ```typescript
-const notesR = store.resource(db, notes, {/* in, out, list, unit: "notes" */});
-const mounted = on(http.resource("/notes", notesR.all()));
+const notesR = store.resource(db, notes, {/* in, out, list */});
+const mounted = on(http.resource("/notes", notesR.all()).gate.public.live());
 // .adopt({ notes: mounted }) →
-await api.notes.list({ limit: 20 }); // GET /notes?limit=20 — meta may carry nextCursor
+const page = await api.notes.list({ limit: 20 });
+const more = await page.next();
+for await (const page of api.notes.list({ limit: 20 })) page.data;
 await api.notes.get({ id }); // GET /notes/:id — NotFound when missing
 await api.notes.remove({ id }); // DELETE → 204, data undefined
 ```
 
-See [Store](/docs/elements/store) for the list query language and schemas. Auth posture for HTTP
-triggers is covered under [Gate](/docs/elements/gate).
+`meta.next` / `meta.prev` are `{ cursor }` bags — spread them, or use `page.next()`. TanStack
+`useInfiniteQuery` takes the bag, not the methods:
+
+```typescript
+useInfiniteQuery({
+  queryKey: ["notes", q],
+  queryFn: ({ pageParam }) => api.notes.list({ limit: 20, q, ...pageParam }),
+  initialPageParam: {} as { cursor?: string },
+  getNextPageParam: (last) => last.meta.next ?? undefined,
+  getPreviousPageParam: (last) => last.meta.prev ?? undefined,
+});
+```
+
+See [Store](/docs/elements/store) for the list query language and schemas. Handwritten lists use
+`fx.json.withQuery(rows, input)` for the same envelope. Auth posture for HTTP triggers is
+covered under [Gate](/docs/elements/gate).
 
 ### Signal and live queries
 
@@ -242,16 +261,16 @@ Flow that returns the current state.
 
 ## Exports
 
-| Export                                       | Kind      | Role                                              |
-| -------------------------------------------- | --------- | ------------------------------------------------- |
-| `createClient`                               | function  | Typed proxy `api.unit.flow(input?)`               |
-| `flattenRoutes`                              | function  | `$routes` → flat `unit.flow` REST table           |
-| `createTransport`                            | function  | Low-level HTTP transport (timeout / retry / auth) |
-| `isOk` / `isFail`                            | function  | Envelope predicates                               |
-| `isErrorCode` / `isTransportError`           | function  | Error narrowing                                   |
-| `Client`, `ClientOptions`, `ClientResult`, … | types     | Contracts and options                             |
-| `Register`                                   | interface | Module-augmentation slot for ambient App types    |
-| `AppOf`                                      | type      | Brand a bare route map as an App                  |
+| Export                                    | Kind      | Role                                               |
+| ----------------------------------------- | --------- | -------------------------------------------------- |
+| `createClient`                            | function  | Typed proxy `api.unit.flow(input?)`                |
+| `flattenRoutes`                           | function  | `$routes` → flat `unit.flow` REST table            |
+| `createTransport`                         | function  | Low-level HTTP transport (timeout / retry / auth)  |
+| `isOk` / `isFail`                         | function  | Envelope predicates                                |
+| `isErrorCode` / `isTransportError`        | function  | Error narrowing                                    |
+| `Client`, `ClientCall`, `ClientResult`, … | types     | Contracts, `page.next()` / `for await` of `list()` |
+| `Register`                                | interface | Module-augmentation slot for ambient App types     |
+| `AppOf`                                   | type      | Brand a bare route map as an App                   |
 
 Budget: the `./client` export stays under the measured client-runtime cap (hard gate in CI).
 

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

@@ -97,28 +97,29 @@ Built-in defaults (`DRIVER_DEFAULTS`) when a key is omitted:
 | `vault`         | `env`      | `memory`  | `vault`    |
 | `channel.email` | `smtp`     | `console` | `smtp`     |
 | `channel.sms`   | — (opt-in) | —         | —          |
+| `runs`          | `files`    | `memory`  | `files`    |
 
 `store.index`, `channel.whatsapp` / `push`, and `ai` have no single three-env default table — set them explicitly when you need them. create-oke templates pin `vault.dev: "vault"` (built-in) because the default `dev` driver is `env`.
 
 ## Driver keys and ids
 
-| Key                | Shape          | Driver ids                                                                   |
-| ------------------ | -------------- | ---------------------------------------------------------------------------- |
-| `store.sql`        | env driver map | `postgres` · `pglite` · `memory`                                             |
-| `store.kv`         | env driver map | `memory` · `redis`                                                           |
-| `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector` · `meilisearch`                                        |
-| `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind  |
-| `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                    |
-| `journal`          | env driver map | `memory` · `file` · `postgres`                                               |
-| `vault`            | env driver map | `env` · `vault` · `memory` · `managed`                                       |
-| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                      |
-| `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                |
-| `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                       |
-| `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                |
-| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama` |
-| `runs`             | env driver map | runs-store driver (distinct from top-level `runs`)                           |
-| `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred              |
+| Key                | Shape          | Driver ids                                                                       |
+| ------------------ | -------------- | -------------------------------------------------------------------------------- |
+| `store.sql`        | env driver map | `postgres` · `pglite` · `memory`                                                 |
+| `store.kv`         | env driver map | `memory` · `redis`                                                               |
+| `store.files`      | env driver map | `memory` · `fs` · `s3`                                                           |
+| `store.index`      | env driver map | `memory` · `pgvector` · `meilisearch`                                            |
+| `signal`           | env driver map | `memory` · `redis` (boot); `postgres` · `nats` fail loud until clients bind      |
+| `clock`            | env driver map | `memory` · `postgres` · `file` · `frozen`                                        |
+| `journal`          | env driver map | `memory` · `file` · `postgres`                                                   |
+| `vault`            | env driver map | `env` · `vault` · `memory` · `managed`                                           |
+| `channel.email`    | env driver map | `console` · `smtp` · `resend` · `sndr` · `taqnyat-mail`                          |
+| `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                    |
+| `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                           |
+| `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                    |
+| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`     |
+| `runs`             | env driver map | `memory` · `files` (Parquet + DuckDB at `.oke/runs`) · `postgres` · `clickhouse` |
+| `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred                  |
 
 ### Safety rules
 
@@ -150,18 +151,20 @@ images: {
   store: {
     sql: "postgres:18-alpine",
     kv: "redis:8-alpine",
-    files: "rustfs/rustfs:1.0.0-beta.11",
+    files: "rustfs/rustfs:1.0.0-rc.2",
   },
-  channel: { email: "axllent/mailpit:v1.22.3" },
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
-  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10290",
+  channel: { email: "axllent/mailpit:v1.30.7" },
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53",
+  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10450",
   // proxy: "caddy:2-alpine",
 },
 ```
 
 Omitted image keys mean no container for that role. When both `store.sql` and `pgdog` are pinned, `DATABASE_URL` points at PgDog — see [Store](/docs/elements/store#multiple-environments).
 
-For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`. For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
+For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
+`{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
+For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
 
 ## i18n
 
@@ -195,9 +198,10 @@ privacy: {},
 
 Runs retention and redaction — **not** the same key as `drivers.runs`.
 
-| Option   | Type                     | Meaning                                               |
-| -------- | ------------------------ | ----------------------------------------------------- |
-| `redact` | `Record<string, string>` | Field → retention duration; presence turns privacy on |
+| Option   | Type                     | Meaning                                                                    |
+| -------- | ------------------------ | -------------------------------------------------------------------------- |
+| `keep`   | `string` \| `"forever"`  | Delete Parquet partitions older than this (`7d` in `dev`, `30d` in `prod`) |
+| `redact` | `Record<string, string>` | Field → retention duration; presence turns privacy on                      |
 
 ## db
 
@@ -252,6 +256,11 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
   `postgres` / `pglite`. `oke mode` was removed — `oke dev` always starts Docker Compose.
 </Accordion>
 
+<Accordion title="Runs DuckDB / Parquet queries requires @duckdb/node-api">
+  The `files` driver needs `@duckdb/node-api`. create-oke templates add it. Install with `bun add
+  @duckdb/node-api` if an older app is missing the peer.
+</Accordion>
+
 </Accordions>
 
 ## Learn more

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

@@ -4,7 +4,7 @@ description: "Every environment variable OKE reads — connection URLs, driver o
 icon: "Terminal"
 ---
 
-OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `docker/.env.docker`; this page is the full map.
+OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `.env.local`; this page is the full map.
 
 <Callout title="Precedence">
   For anything with both an `OKE_*` variable and a conventional one (like `DATABASE_URL`), the
@@ -33,11 +33,11 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## KV store
 
-| Variable           | Used for                 | Default when unset |
-| ------------------ | ------------------------ | ------------------ |
-| `REDIS_URL`        | Redis connection         | driver default     |
-| `OKE_STORE_KV_URL` | Explicit KV URL override | —                  |
-| `OKE_KV_DRIVER`    | Force the kv driver id   | config map         |
+| Variable           | Used for                       | Default when unset |
+| ------------------ | ------------------------------ | ------------------ |
+| `REDIS_URL`        | Cache Redis connection         | driver default     |
+| `OKE_STORE_KV_URL` | Explicit cache KV URL override | —                  |
+| `OKE_KV_DRIVER`    | Force the kv driver id         | config map         |
 
 ## Files store
 
@@ -54,17 +54,17 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## Vault
 
-Built-in store uses `OKE_VAULT_MASTER_KEY` (or `--key` / stdin on CLI). Managed AWS Secrets Manager
-uses the provider + region vars below.
+Built-in store uses `OKE_VAULT_MASTER_KEY` (or `--key` / stdin on CLI). Managed providers use the
+vars below — see [Vault](/docs/elements/vault) for which each id needs.
 
-| Variable               | Used for                                     | Default when unset    |
-| ---------------------- | -------------------------------------------- | --------------------- |
-| `OKE_VAULT_PROVIDER`   | Managed backend (`aws-secrets-manager`)      | — (platform-injected) |
-| `OKE_VAULT_REGION`     | Cloud region for AWS Secrets Manager         | —                     |
-| `OKE_VAULT_MOUNT`      | Secret-name prefix for AWS SM (`oke/prod/`)  | —                     |
-| `OKE_VAULT_MASTER_KEY` | Built-in vault master key (base64)           | —                     |
-| `OKE_VAULT_URL`        | Optional remote URL for community adapters   | —                     |
-| `OKE_VAULT_TOKEN`      | Optional remote token for community adapters | —                     |
+| Variable               | Used for                                                                                                     | Default when unset    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- |
+| `OKE_VAULT_PROVIDER`   | Managed backend (`aws-secrets-manager` · `azure-key-vault` · `gcp-secret-manager` · `doppler` · `1password`) | — (platform-injected) |
+| `OKE_VAULT_REGION`     | Cloud region (AWS Secrets Manager; GCP user-managed replication)                                             | —                     |
+| `OKE_VAULT_MOUNT`      | Scope: AWS/Azure prefix, GCP `project[/prefix]`, Doppler `project/config`, 1Password vault name              | —                     |
+| `OKE_VAULT_MASTER_KEY` | Built-in vault master key (base64)                                                                           | —                     |
+| `OKE_VAULT_URL`        | Azure Key Vault URI, 1Password Connect host, optional Doppler origin                                         | —                     |
+| `OKE_VAULT_TOKEN`      | Doppler service/personal token, 1Password Connect token                                                      | —                     |
 
 ## Channel (email) — boot binder
 
@@ -128,15 +128,18 @@ provider's real credentials — credentials alone never send.
 
 ## Framework behavior
 
-| Variable              | Used for                                                                                                              |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `OKE_DOCKER`          | `"1"` marks Compose / `oke dev` posture (set by the CLI)                                                              |
-| `OKE_DB_AUTO_PUSH`    | Overrides `db.autoPush` at boot                                                                                       |
-| `OKE_DRIZZLE_DIALECT` | `"postgresql"` for drizzle-kit overlays (templates hardcode it)                                                       |
-| `OKE_DEV_REQUEST_LOG` | `"1"` logs requests during `oke dev` (set by the CLI)                                                                 |
-| `OKE_CONSOLE_SECRET`  | Console operator-session signing secret (HMAC) — set in production; else `.oke/console.secret`. Not a Vault contract. |
-| `PORT`                | App port in production containers (default `6530`)                                                                    |
-| `NODE_ENV`            | `"production"` switches the Console to its production posture                                                         |
+| Variable                 | Used for                                                                                                              |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `OKE_DOCKER`             | `"1"` marks Compose / `oke dev` posture (set by the CLI)                                                              |
+| `OKE_DB_AUTO_PUSH`       | Overrides `db.autoPush` at boot                                                                                       |
+| `OKE_DRIZZLE_DIALECT`    | `"postgresql"` for drizzle-kit overlays (templates hardcode it)                                                       |
+| `OKE_DEV_REQUEST_LOG`    | `"1"` logs requests during `oke dev` (set by the CLI) — surface, flow, status, timestamp, run id                      |
+| `OKE_CONSOLE_SECRET`     | Console operator-session signing secret (HMAC) — set in production; else `.oke/console.secret`. Not a Vault contract. |
+| `OKE_CONSOLE_AUTH_STORE` | `"1"` lists the operator-plane `oke_console` schema in Store browse (read-only). Hidden by default.                   |
+| `OKE_RUNS_INGEST_URL`    | Host → Console WideEvent ingest URL (`oke dev` sets this on the app child). Enables a memory runs store + push.       |
+| `OKE_RUNS_INGEST_SECRET` | Shared secret for `POST /console/runs/ingest` (`x-oke-runs-ingest` header). Minted by `oke dev`; never return events. |
+| `PORT`                   | App port in production containers (default `6530`)                                                                    |
+| `NODE_ENV`               | `"production"` switches the Console to its production posture                                                         |
 
 Console operator rows are **not** stored in `.oke/console.sqlite`. With `DATABASE_URL` (or
 `OKE_STORE_SQL_URL`) they live in Postgres schema `oke_console`. Without a Postgres URL,

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

@@ -60,31 +60,36 @@ Returned, not thrown — the request never reached `do`:
 
 ## Framework validation failures
 
-| Code              | When                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------ |
-| `ValidationError` | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`) |
-| `NotFound`        | A `store.resource` get/update/remove hit a missing row                                     |
+| Code                   | When                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ValidationError`      | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`)                          |
+| `NotFound`             | A `store.resource` get/update/remove hit a missing row                                                              |
+| `InvalidQuery`         | QUERY missing `Content-Type` (`reason: missing_content_type`) or body isn't JSON (`inconsistent_content`) — **400** |
+| `UnsupportedMediaType` | QUERY `Content-Type` is present but not `application/json` — **415**, `Accept-Query` lists JSON                     |
 
 ## Subsystem errors
 
 Thrown by specific subsystems — each names its own cause:
 
-| Error                         | Thrown when                                                        | What to do                                             |
-| ----------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------ |
-| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap      |
-| `VaultError` (`UNSUPPORTED`)  | Managed provider unknown or not implemented in core                | Use `aws-secrets-manager`, built-in `vault`, or `env`  |
-| `AiPiiBuildError`             | Build: a flow sends PII fields to a third-party model              | Drop the fields or add `allowPii: true` — fields named |
-| `AiSchemaValidationError`     | A model response failed the prompt's `out` schema                  | Fix the prompt or the schema — response didn't conform |
-| `ScheduleNotOverridableError` | Console tried to edit a clock declared without `overridable: true` | Declare it overridable and redeploy                    |
-| `ClockResourceNotFoundError`  | Console action targeted an unknown clock name                      | Check the name against your `clock()` declarations     |
-| `DryRunWriteIsolationError`   | A write attempted inside a dry run                                 | Dry runs never write — use a real run                  |
-| `ManifestValidationError`     | The compiled Manifest failed schema validation                     | Re-run the build; the error names the offending entry  |
-| `CrossPlaneError`             | A user-plane token was used on the operator plane (or vice versa)  | Use the correct principal for the plane                |
-| `AttenuationError`            | A token was used beyond its attenuated scope                       | Re-issue with the needed scope                         |
-| `SessionError`                | Session token invalid, expired, or malformed                       | Re-authenticate                                        |
-| `OperatorError`               | Operator-plane operation failed its checks                         | Error message names the failed check                   |
-| `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                   |
-| `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                              |
+| Error                         | Thrown when                                                        | What to do                                                            |
+| ----------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap                     |
+| `VaultError` (`UNSUPPORTED`)  | Managed provider unknown                                           | Use an official id, built-in `vault`, or `env`                        |
+| `VaultSealed`                 | Console rotate-master while this process holds no master key       | Export `OKE_VAULT_MASTER_KEY` or run `oke vault unseal`               |
+| `VaultRotateBusy`             | Master-rotation lease held or a batch is already in flight         | Wait and continue, or resume with `oke vault rotate-master --new-key` |
+| `VaultUnsupported`            | Console vault action on a non-builtin backend or missing SQL       | Use `drivers.vault = "vault"` and set `DATABASE_URL`                  |
+| `AiPiiBuildError`             | Build: a flow sends PII fields to a third-party model              | Drop the fields or add `allowPii: true` — fields named                |
+| `AiSchemaValidationError`     | A model response failed the prompt's `out` schema                  | Fix the prompt or the schema — response didn't conform                |
+| `ScheduleNotOverridableError` | Console tried to edit a clock declared without `overridable: true` | Declare it overridable and redeploy                                   |
+| `ClockResourceNotFoundError`  | Console action targeted an unknown clock name                      | Check the name against your `clock()` declarations                    |
+| `DryRunWriteIsolationError`   | A write attempted inside a dry run                                 | Dry runs never write — use a real run                                 |
+| `ManifestValidationError`     | The compiled Manifest failed schema validation                     | Re-run the build; the error names the offending entry                 |
+| `CrossPlaneError`             | A user-plane token was used on the operator plane (or vice versa)  | Use the correct principal for the plane                               |
+| `AttenuationError`            | A token was used beyond its attenuated scope                       | Re-issue with the needed scope                                        |
+| `SessionError`                | Session token invalid, expired, or malformed                       | Re-authenticate                                                       |
+| `OperatorError`               | Operator-plane operation failed its checks                         | Error message names the failed check                                  |
+| `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                                  |
+| `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                                             |
 
 ## Learn more
 

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

@@ -41,12 +41,12 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Channel) without a parallel metrics API.
 
-| Signature                                | Records       | Returns                                       |
-| ---------------------------------------- | ------------- | --------------------------------------------- |
-| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory)        |
-| `fx.runs.all()`                          | `read` `runs` | All wide events                               |
-| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m) |
-| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches               |
+| Signature                                | Records       | Returns                                                                                  |
+| ---------------------------------------- | ------------- | ---------------------------------------------------------------------------------------- |
+| `fx.runs.query(sql)`                     | `read` `runs` | SQL rows (`FROM runs` on files/memory). Unrestricted Flow SQL — not the Console sandbox. |
+| `fx.runs.all()`                          | `read` `runs` | All wide events                                                                          |
+| `fx.runs.window(flow, windowMs?)`        | `read` `runs` | Rolling P50/P95/P99 + error rate (default 5m)                                            |
+| `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches                                                          |
 
 ```typescript
 on(
@@ -178,6 +178,12 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`.
 
 ## Cache
 
+Read-only flows cache automatically from inferred or ledgered `reads` — no
+`fx.cache` call and no `cache:` default on the flow. Writes invalidate those
+keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
+
+`fx.cache` is the manual (tier-3) surface:
+
 | Signature                              | Notes                                     |
 | -------------------------------------- | ----------------------------------------- |
 | `fx.cache.get(key)`                    | Value or `undefined`                      |
@@ -186,12 +192,13 @@ Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`.
 
 ## Responses
 
-| Helper                         | Status | Body                           |
-| ------------------------------ | ------ | ------------------------------ |
-| `fx.json.ok(value, { meta? })` | 200    | `{ data, meta?, error: null }` |
-| `fx.json.create(value)`        | 201    | `{ data, error: null }`        |
-| `fx.json.empty()`              | 204    | no body                        |
-| `fx.json.with(data, meta)`     | 200    | paginated envelope             |
+| Helper                                    | Status | Body                                                        |
+| ----------------------------------------- | ------ | ----------------------------------------------------------- |
+| `fx.json.ok(value, { meta? })`            | 200    | `{ data, meta?, error: null }`                              |
+| `fx.json.create(value)`                   | 201    | `{ data, error: null }`                                     |
+| `fx.json.empty()`                         | 204    | no body                                                     |
+| `fx.json.with(page)` / `with(data, meta)` | 200    | `{ data, meta, error: null }` — already-built pager         |
+| `fx.json.withQuery(rows, input, spec?)`   | 200    | In-memory list page — zero-config `q` / auto-eq / PostgREST |
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control.
 

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

@@ -110,14 +110,14 @@ At `onResponse`, `ctx.response` holds the **final serialized HTTP response** —
 
 ## Edge handlers answer unmatched requests
 
-Hooks only ever see requests a flow owns — an `OPTIONS` preflight for a path bound to `GET` matches nothing and would 404 untouched. `.edge(fn)` closes that gap: handlers run in install order when the router finds no flow, the first returned `Response` answers, and `undefined` passes to the next handler, then the plain 404:
+Hooks only ever see requests a flow owns — an `OPTIONS` preflight for a path bound to `GET` matches nothing and would 405 untouched. `.edge(fn)` closes that gap: handlers run in install order when the router finds no flow, the first returned `Response` answers, and `undefined` passes to the next handler, then **405** if the path exists for other methods, else 404:
 
 ```typescript
 plugin("cors", { version: "1.0.0" }).edge((request, info) => {
   if (info.method === "OPTIONS" && request.headers.has("origin")) {
     return new Response(null, { status: 204, headers: preflightHeaders(request) });
   }
-  return undefined; // not mine — let someone else answer, else 404
+  return undefined; // not mine — let someone else answer, else 405/404
 });
 ```