okengine 0.11.2 → 0.13.0

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 />
 
@@ -168,14 +197,50 @@ VaultBootError: 1 secret(s) missing:
 
 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 the same SKIP LOCKED + lease-expiry physics as Clock and Signal: one holder
-  at a time; a crashed holder is reclaimed after the lease TTL. Audit rows append under a
-  transactional row lock so the hash chain stays verifiable under concurrent writers. Backups are
-  written via temp → fsync → rename and carry an end marker + checksum — restore rejects incomplete
-  files before decrypt.
+  `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">
@@ -193,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: {
@@ -207,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
 
@@ -248,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?">

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

@@ -24,11 +24,18 @@ Write your first Flow, call it from a typed client, and prove it with
 bunx create-oke@latest my-app
 cd my-app
 oke dev
+bun run web
 ```
 
 Use `--template advanced` for the same Notes domain with files attach, a daily
 digest Clock, and an AI summarize stub.
 
+To exercise Docker with a larger domain, run `examples/keel` from the okengine
+repo (`bun run dev:keel`) — not a create-oke template.
+
+Open **6530** in a browser to read the envelope in a code block. The right rail
+lists HTTP routes — static GET paths are links. `curl` still gets `{ data, error }`.
+
 <Surfaces />
 
 </Step>
@@ -43,7 +50,7 @@ import { on, flow, http, gate } from "okengine/http";
 import { z } from "zod";
 
 export const health = on(
-  http.get("/health").gate(gate.public),
+  http.get("/health").gate.public,
   flow("main.health", {
     out: z.object({ ok: z.literal(true) }),
     do: () => ({ ok: true as const }),
@@ -51,7 +58,7 @@ export const health = on(
 );
 ```
 
-Named flows show up as `main.health` (not `flow_1`) in `oke dev` logs.
+Named flows show up as `main.health` (not `flow_1`) in `oke dev` logs, with the run id after the timestamp.
 Change the route or output and save — App and Console update together from the
 same Manifest.
 
@@ -83,9 +90,10 @@ const api = createClient<App>("http://localhost:6530");
 const { data, error } = await api.main.health({});
 ```
 
-`data` and `error` are inferred from the Flow contracts — no separate client
-schema. Bearer: `auth: { getToken, refresh }` (`okengine/client/auth` helpers;
-`useSession` in `okengine/client-react`). Full options: [Client](/docs/reference/client).
+`data` and `error` are inferred from the Flow contracts.
+
+The starter `web/` app uses `createClient("")` so Vite proxies `/notes` and
+`/health` to the app. Bearer: `auth: { getToken, refresh }`. See [Client](/docs/reference/client).
 
 </Step>
 
@@ -144,7 +152,7 @@ bun test
 ## Learn more
 
 - [Flow](/docs/elements/flow) — triggers, contracts, effects, and composition
-- [Store](/docs/elements/store) — SQL, KV, files, index
+- [Store](/docs/elements/store) — SQL, KV, files, index, and the preferred list envelope
 - [fx](/docs/reference/fx) — the full effect surface
 
 ## Next

package/site/content/docs/get-started/installation.mdx

@@ -63,12 +63,15 @@ bunx create-oke@latest my-app --yes
 ```
 
 Two Notes starters: **standard** and **advanced** (adds `store.index` + optional AI).
-Both are Docker-first (`dev`/`prod` share production protocols; `test` uses PGLite /
-memory). Both ship a minimal GitHub Actions workflow (typecheck + `bun test`).
+Both are Docker-first; `test` uses PGLite / memory.
+
+The okengine repo also ships `examples/keel` — a work-management app, not a template.
+Run it with `bun run dev:keel` against Compose (Postgres, PgDog, Redis, RustFS, Mailpit,
+Meilisearch, llama.cpp). Wipe with `bun run dev:keel:reset`.
 
 On a TTY: pick a template, then **recommended defaults**, **customize**, or
-**reuse** matching saved settings (`~/.oke/create-defaults.json`). Extra locales
-and PgDog answers are saved into that file on every TTY run (not only customize).
+**reuse** (`~/.oke/create-defaults.json`). Reuse applies saved locales / PgDog /
+proxy without re-asking; recommended and customize ask and persist those answers.
 
 Customize walks Docker-first facets (including `store.index` with `none`), then
 **AI setup** (Recommended / Customize / Off). Project name rejects a non-empty
@@ -91,12 +94,12 @@ Four ports come up together (mnemonic: **O·K·E = 6·5·3**):
 
 <Surfaces />
 
-Open `http://localhost:6533`. Claim the Console with the **claim code** printed
-once under the `oke dev` hero, then create the first operator.
+Open `http://localhost:6533`. Paste the **claim code** from the `oke dev` board
+(or `oke console claim-code`). Password: **≥ 12** with upper, lower, number, and
+special, or **Generate** (copies it).
 
-Password policy matches Gate auth: **≥ 12 characters, with a letter and a
-number.** If the Console lists your flows, the install worked — **derived, not
-configured.**
+Flows listed means the install worked — **derived, not configured.**
+`bun run web` starts the Vite Notes UI (proxies Flows to the app).
 
 </Step>
 
@@ -108,10 +111,9 @@ configured.**
 stays in sync. Opt out with `oke dev --no-db-push` or
 `db: { autoPush: false }` in `oke.config.ts`.
 
-A broken `schema.decl.ts` (bad table / relation definition) prints a red ●
-`schema.decl.ts has an error — …` line and keeps the session up — it is never
-framed as a quiet `skipped`. Environmental gaps (no `oke.config.ts` / no
-images yet) still soft-skip.
+A broken `schema.decl.ts` prints a red ● `schema.decl.ts has an error — …` and
+keeps the session up — never a quiet `skipped`. Missing `oke.config.ts` / images
+still soft-skip.
 
 For production, generate and apply migrations deliberately — never automatic on
 boot:
@@ -167,9 +169,9 @@ See [Migrating environments](/docs/reference/migrating-environments).
 </Accordion>
 
 <Accordion title="Create first operator fails (password / claim code)">
-  Use a password with at least 12 characters, including a letter and a number. Copy the claim code
-  from the current `oke dev` boot log (it expires in 30 minutes; restart mint a new one). The form
-  and the request log now show the reason — not a bare `TransportError` / `500`.
+  Password: ≥ 12 with upper, lower, number, and special — or **Generate**. Copy the claim code from
+  the `oke dev` board (30 min TTL) or `oke console claim-code`. The form never gets the code over
+  HTTP; the log shows the reason, not a bare `500`.
 </Accordion>
 
 <Accordion title="Database out of sync after editing schema">
@@ -183,6 +185,12 @@ See [Migrating environments](/docs/reference/migrating-environments).
   leftover containers, networks, and volumes.
 </Accordion>
 
+<Accordion title="Want a clean keel stack?">
+  Stop `bun run dev:keel`, then `bun run dev:keel:reset`. That wipes Compose, `.oke/`, and writes
+  `.env.local` from `.env.example`. Next `dev:keel` regenerates stack keys; seed copies them into
+  the built-in vault.
+</Accordion>
+
 </Accordions>
 
 ## Learn more

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

@@ -5,7 +5,7 @@ icon: "Globe"
 source: "src/plugins/cors.ts"
 ---
 
-`cors()` decides which websites may call your app from a browser. It answers preflight `OPTIONS` requests itself — even for paths bound to other methods, which would otherwise 404 before any middleware could run — and stamps `Access-Control-*` headers on matched responses.
+`cors()` decides which websites may call your app from a browser. It answers preflight `OPTIONS` requests itself — even for paths bound to other methods, which would otherwise 405 or 404 before any middleware could run — and stamps `Access-Control-*` headers on matched responses.
 
 ## Quick start
 
@@ -27,14 +27,14 @@ Browsers on `https://app.example.com` can now call every flow; every other origi
 
 ## Options
 
-| Option           | Type                          | Default                                                | Does                                                                      |
-| ---------------- | ----------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------- |
-| `origin`         | `"*"` · `string` · `string[]` | none (closed)                                          | Origins allowed cross-origin; lists are exact matches                     |
-| `methods`        | `string[]`                    | GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS     | Methods answered on preflight                                             |
-| `allowedHeaders` | `string[]`                    | reflect the request's `Access-Control-Request-Headers` | `Access-Control-Allow-Headers` on preflight                               |
-| `exposedHeaders` | `string[]`                    | omit                                                   | `Access-Control-Expose-Headers` on actual responses                       |
-| `credentials`    | `boolean`                     | `false`                                                | Send `Access-Control-Allow-Credentials`; requires an explicit origin list |
-| `maxAge`         | `number`                      | omit                                                   | `Access-Control-Max-Age` seconds on preflight                             |
+| Option           | Type                          | Default                                                    | Does                                                                      |
+| ---------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `origin`         | `"*"` · `string` · `string[]` | none (closed)                                              | Origins allowed cross-origin; lists are exact matches                     |
+| `methods`        | `string[]`                    | GET · HEAD · POST · PUT · PATCH · DELETE · OPTIONS · QUERY | Methods answered on preflight                                             |
+| `allowedHeaders` | `string[]`                    | reflect the request's `Access-Control-Request-Headers`     | `Access-Control-Allow-Headers` on preflight                               |
+| `exposedHeaders` | `string[]`                    | omit                                                       | `Access-Control-Expose-Headers` on actual responses                       |
+| `credentials`    | `boolean`                     | `false`                                                    | Send `Access-Control-Allow-Credentials`; requires an explicit origin list |
+| `maxAge`         | `number`                      | omit                                                       | `Access-Control-Max-Age` seconds on preflight                             |
 
 ```typescript
 .plug(cors({

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

@@ -16,7 +16,7 @@ import { csrf } from "okengine/plugins";
 export const app = oke({ name: "shop", env: "dev" }).plug(csrf());
 ```
 
-`GET`/`HEAD`/`OPTIONS` always pass. A `POST` with `Sec-Fetch-Site: cross-site` now gets the gate element's typed `Forbidden` — unless its `Origin` is yours or allow-listed.
+`GET`/`HEAD`/`OPTIONS`/`QUERY` always pass. A `POST` with `Sec-Fetch-Site: cross-site` now gets the gate element's typed `Forbidden` — unless its `Origin` is yours or allow-listed.
 
 ## How it decides
 

package/site/content/docs/providers/cockroachdb.mdx

@@ -42,6 +42,19 @@ CockroachDB Software License (since Nov 2024): Core open-source discontinued; fr
 orgs under $10M ARR with community support; paid tiers add dedicated support. Not OSI
 open source.
 
+## Query performance
+
+<Callout title="Unsupported">
+  CockroachDB does not expose `pg_stat_statements`. Store → **Performance** returns
+  `PgStatStatementsUnsupported`. oke does not shim `statement_statistics`.
+</Callout>
+
+| Step    | What you do                                      |
+| ------- | ------------------------------------------------ |
+| Preload | Not applicable                                   |
+| Create  | Not applicable                                   |
+| Console | Structured unavailable — use Cockroach's console |
+
 ## Real gotcha — CA cert path
 
 Copying the connection string without downloading the CA yields TLS verify failures

package/site/content/docs/providers/index.mdx

@@ -43,6 +43,7 @@ Managed Postgres-wire databases — set `DATABASE_URL`, driver stays `postgres`.
 ## Redis providers
 
 Managed Redis-wire caches — set `REDIS_URL`, driver stays `redis`.
+`{ durable: true }` KV lives in your SQL database, not a second Redis.
 
 <Cards>
   <Card

package/site/content/docs/providers/neon.mdx

@@ -67,6 +67,22 @@ deliberately) when you need `pgvector` setup from that role.
 Hitting CU-hours or storage **suspends compute** until the next billing period or an
 upgrade. Always-on production needs Launch/Scale with scale-to-zero disabled.
 
+## Query performance
+
+<Callout title="Create the extension — do not set command">
+  Neon already preloads `pg_stat_statements`. `CREATE EXTENSION` is enough. There is no oke
+  `command` overlay and no `online_advisor` shim.
+</Callout>
+
+| Step    | What you do                                         |
+| ------- | --------------------------------------------------- |
+| Preload | Neon compute (already on)                           |
+| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Console | Store → SQL band → **Performance**                  |
+
+Scale-to-zero **wipes** statement stats when compute sleeps. Index Advisor is
+not in the default Neon catalog — Performance shows a CTA, not a failing Enable.
+
 ## Real gotcha — cold start
 
 After scale-to-zero, the first query pays a wake-up (hundreds of ms to a few seconds).
@@ -82,6 +98,12 @@ Too many **direct** connections, or pooler server pool exhausted for your comput
 Move runtime traffic to the `-pooler` hostname; keep a small number of direct admin
 sessions. Neon reserves connections for the superuser account on each compute size.
 
+</Accordion>
+<Accordion title="Performance KPIs reset after idle">
+
+Free (and any scale-to-zero) compute drops `pg_stat_statements` memory when the
+endpoint sleeps. Re-run traffic after wake — this is not a Console bug.
+
 </Accordion>
 <Accordion title='permission denied to create extension "vector"'>
 

package/site/content/docs/providers/supabase.mdx

@@ -53,6 +53,23 @@ not support prepared statements — turn them off in the client if you see relat
 **IPv6 gotcha:** Direct (and dedicated pooler) are IPv6 unless you buy the IPv4 add-on.
 IPv4-only app hosts must use the shared pooler hostnames.
 
+## Query performance
+
+<Callout title="Use the direct port for engine views">
+  `pg_stat_statements` is preloaded. Create the extension, then open Store → **Performance** on the
+  **direct** `:5432` URL — not the transaction pooler.
+</Callout>
+
+| Step    | What you do                                         |
+| ------- | --------------------------------------------------- |
+| Preload | Platform (already on)                               |
+| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Locks   | Direct `db.[ref].supabase.co:5432`                  |
+| Advisor | Dashboard **Database → Extensions** or `CASCADE`    |
+
+Transaction pooler (`:6543`) is fine for app traffic. Live lock pairs and
+advisor DDL need a session on the database host.
+
 ## pgvector
 
 Available on every plan. Enable from the dashboard **Database → Extensions** (or

package/site/content/docs/providers/yugabytedb.mdx

@@ -45,6 +45,21 @@ No Neon-style pooled hostname toggle — connection limits and load balancing ar
 cluster/VPC topology concerns. Smart drivers want a peered VPC; otherwise they probe
 unreachable nodes first and add latency.
 
+## Query performance
+
+<Callout title="Already preloaded">
+  YSQL exposes `pg_stat_statements` without an oke `command`. Create the extension, then open Store
+  → **Performance**.
+</Callout>
+
+| Step    | What you do                                         |
+| ------- | --------------------------------------------------- |
+| Preload | Yugabyte (already on)                               |
+| Create  | `CREATE EXTENSION IF NOT EXISTS pg_stat_statements` |
+| Advisor | Not in the default catalog — CTA only               |
+
+Do not invent a Postgres `command` overlay for Aeon or the Docker recipe.
+
 ## Real gotcha — wrong API tab
 
 Copying **YCQL** parameters (port **9042**) into `DATABASE_URL` fails immediately —

package/site/content/docs/recipes/caddy.mdx

@@ -31,7 +31,7 @@ images: {
 <Step>
 ### Set the public hostname
 
-```bash title="docker/.env.docker"
+```bash title=".env.local"
 OKE_PROXY_HOST=app.example.com
 ```
 
@@ -111,7 +111,7 @@ Expected with the local CA. Install Caddy's local root for that machine, or set
 
 ## Learn more
 
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy vs Traefik rationale
+- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx choice
 - [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
 - [Security](/docs/reference/security) — `allowedHosts`
 
@@ -119,10 +119,10 @@ Expected with the local CA. Install Caddy's local root for that machine, or set
 
 <Cards>
   <Card title="Traefik" description="Multi-replica alternative." href="/docs/recipes/traefik" />
+  <Card title="nginx" description="Static HTTP reverse proxy." href="/docs/recipes/nginx" />
   <Card
     title="PgDog"
     description="Pool Postgres behind the same stack."
     href="/docs/recipes/pgdog"
   />
-  <Card title="Redis" description="The default store.kv image." href="/docs/recipes/redis" />
 </Cards>

package/site/content/docs/recipes/cockroachdb.mdx

@@ -88,13 +88,19 @@ not multi-region HA. For managed multi-region, use the
 | Command        | `start-single-node --accept-sql-without-tls` |
 | Healthcheck    | `GET /health?ready=1` on `:8080`             |
 | Connection URL | `postgres://…?sslmode=require`               |
+| Stats          | `pg_stat_statements` unsupported             |
+
+## Query performance
+
+Store → **Performance** returns `PgStatStatementsUnsupported`. oke does not shim
+Cockroach `statement_statistics`.
 
 ## Troubleshooting
 
 <Accordions>
 <Accordion title="oke boot: postgres driver needs DATABASE_URL">
 
-Re-run `oke dev` so the stack writes `docker/.env.docker`, or export
+Re-run `oke dev` so the stack writes `.env.local`, or export
 `DATABASE_URL` yourself when pointing at a remote Cockroach host.
 
 </Accordion>
@@ -102,7 +108,7 @@ Re-run `oke dev` so the stack writes `docker/.env.docker`, or export
 
 First boot can take longer than Postgres. Check
 `docker compose … logs store-sql` for SQL ready. Empty `${OKE_STORE_SQL_PASSWORD}`
-in `.env.docker` leaves the init user broken — regenerate the stack env.
+in `.env.local` leaves the init user broken — regenerate the stack env.
 
 </Accordion>
 </Accordions>

package/site/content/docs/recipes/dragonfly.mdx

@@ -66,9 +66,10 @@ If the host forbids unlimited memlock, the container may fail to start.
 
 ## Data and backup
 
-No named volume — ephemeral by default, same as Redis/Valkey. **Backup means:** do not
-treat this container as durable storage until you add a volume and Dragonfly persistence
-settings; rebuild from SQL/files, or use [Dragonfly Cloud](/docs/providers/dragonfly-cloud).
+The default `store.kv` recipe declares **no named volume** — ephemeral, same as Redis/Valkey.
+
+Keys that must survive go on `{ durable: true }` — a JSONB table on your SQL database.
+Dragonfly snapshots are not involved. See [Store · Durable KV](/docs/elements/store#durable-kv).
 
 ## Production note
 

package/site/content/docs/recipes/index.mdx

@@ -63,7 +63,7 @@ Driver id stays `redis` for every image below.
 
 ## Proxy
 
-Opt-in via `images.proxy` — leave unset until you need HTTPS or `--scale app=N`.
+Opt-in via `images.proxy` — leave unset until you need an edge or `--scale app=N`.
 
 <Cards>
   <Card title="Caddy" description="Automatic-HTTPS, single instance." href="/docs/recipes/caddy" />
@@ -72,6 +72,11 @@ Opt-in via `images.proxy` — leave unset until you need HTTPS or `--scale app=N
     description="Docker-label discovery + socket-proxy."
     href="/docs/recipes/traefik"
   />
+  <Card
+    title="nginx"
+    description="Static nginx.conf reverse proxy (HTTP)."
+    href="/docs/recipes/nginx"
+  />
 </Cards>
 
 ## Services