okengine 0.11.1 → 0.12.0

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,11 +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`).
+**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
@@ -90,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>
 
@@ -107,6 +111,10 @@ 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` 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:
 
@@ -161,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">
@@ -177,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/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/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

package/site/content/docs/recipes/llama-cpp.mdx

@@ -26,7 +26,7 @@ drivers: {
   ai: { dev: "openai-compatible", test: "mock", prod: "openai-compatible" },
 },
 images: {
-  ai: "ghcr.io/ggml-org/llama.cpp:server-b10290", // never :latest
+  ai: "ghcr.io/ggml-org/llama.cpp:server-b10450", // never :latest
 },
 ```
 
@@ -39,14 +39,14 @@ for `granite3.3:2b`.
 <Step>
 ### Env written by the stack
 
-```bash title="docker/.env.docker"
+```bash title=".env.local"
 OKE_AI_URL=http://127.0.0.1:8080/v1
 OKE_AI_MODEL=granite3.3:2b
 ```
 
 `OKE_AI_MODEL` is a Docker Hub `ai/<id>` model. The recipe writes
-`docker/llama-entrypoint.py`, which Hub-pulls into the cache volume, then starts
-`llama-server -m <gguf> --alias <id>` (single-model).
+`.oke/llama-entrypoint.py` (generated, gitignored), Hub-pulls into the cache
+volume, then starts `llama-server -m <gguf> --alias <id>` (single-model).
 
 Never set `LLAMA_ARG_MODELS_PRESET` / `LLAMA_ARG_DOCKER_REPO` — those hang on
 b10290+. `oke dev` shows the model id and polls `/v1/models` until `ready`
@@ -93,13 +93,13 @@ Postgres/Redis, stricter on the published interface because of GGUF CVE risk.
 
 ## What the recipe configures
 
-| Field          | Value                                                           |
-| -------------- | --------------------------------------------------------------- |
-| Container port | `8080`                                                          |
-| Host publish   | `127.0.0.1:8080:8080`                                           |
-| Healthcheck    | `GET /health`, every 5s, 24 retries, 900s start                 |
-| Connection URL | `http://host:8080/v1`                                           |
-| Model load     | `llama-entrypoint.py` → Hub pull (incl. CNCF weights) then `-m` |
+| Field          | Value                                                        |
+| -------------- | ------------------------------------------------------------ |
+| Container port | `8080`                                                       |
+| Host publish   | `127.0.0.1:8080:8080`                                        |
+| Healthcheck    | `GET /health`, every 5s, 24 retries, 900s start              |
+| Connection URL | `http://host:8080/v1`                                        |
+| Model load     | `.oke/llama-entrypoint.py` → Hub pull (incl. CNCF) then `-m` |
 
 ## When to choose something else
 
@@ -126,7 +126,7 @@ First start Hub-pulls the curated `ai/` model into the named cache volume
 (see logs: `oke ai: ensuring…` / download %). Prefer `oke ai setup` tiers
 (Ultra Fast → `granite3.3:2b`) for smoke tests.
 
-Confirm `OKE_AI_MODEL` in `docker/.env.docker` (keep the `.env.local` hint commented so it does not shadow compose). Watch `oke
+Confirm `OKE_AI_MODEL` in `.env.local`. Watch `oke
 dev` until AI status is `ready`.
 
 If status stays `loading` on Compose that still uses `--models-preset`,

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

@@ -28,7 +28,7 @@ drivers: {
   },
 },
 images: {
-  channel: { email: "axllent/mailpit:v1.22.3" },
+  channel: { email: "axllent/mailpit:v1.30.7" },
 },
 ```
 
@@ -37,7 +37,7 @@ images: {
 <Step>
 ### Connect the smtp driver
 
-```bash title="docker/.env.docker (written by oke docker)"
+```bash title=".env.local (written by oke docker)"
 SMTP_URL=smtp://127.0.0.1:1025
 MAILPIT_UI_URL=http://127.0.0.1:8025
 ```
@@ -100,7 +100,7 @@ if SMTP still accepts mail.
 <Accordion title="oke boot: smtp driver needs SMTP_URL">
 
 The smtp binder refuses to start without `SMTP_URL` (or `OKE_CHANNEL_EMAIL_URL`). In
-under `oke dev` the error asks whether Compose wrote `docker/.env.docker`. Also rejects
+under `oke dev` the error asks whether Compose wrote `.env.local`. Also rejects
 non-`smtp://` schemes: `oke boot: SMTP_URL must use smtp://`.
 
 </Accordion>

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

@@ -28,7 +28,7 @@ drivers: {
   },
 },
 images: {
-  store: { index: "getmeili/meilisearch:v1.14" },
+  store: { index: "getmeili/meilisearch:v1.53" },
 },
 ```
 
@@ -37,7 +37,7 @@ images: {
 <Step>
 ### Keys written by oke docker
 
-```bash title="docker/.env.docker"
+```bash title=".env.local"
 OKE_STORE_INDEX_URL=http://127.0.0.1:7700
 OKE_STORE_INDEX_KEY=…          # also accepted as MEILI_MASTER_KEY
 ```
@@ -78,7 +78,7 @@ Writes wait on Meilisearch tasks before returning.
 **Backup means:** snapshot/restore that named volume (or Meilisearch dumps). Recreating
 the container **keeps** data if the volume remains; deleting the volume wipes every index.
 
-The master key is **not** inside the volume — it lives in `.env.docker` / secrets.
+The master key is **not** inside the volume — it lives in `.env.local` / secrets.
 Losing the key without a backup blocks admin API access even if data remains.
 
 ## Production note
@@ -104,7 +104,7 @@ not FTS. See [Store · Index](/docs/elements/store#index).
 <Accordion title="oke boot: meilisearch index needs OKE_STORE_INDEX_URL">
 
 No silent memory fallback. Re-run `oke dev` or export `OKE_STORE_INDEX_URL`.
-Docker-mode wording asks whether `docker/.env.docker` was written.
+Docker-mode wording asks whether `.env.local` was written.
 
 </Accordion>
 <Accordion title="meilisearch index: GET/POST … failed (403) — or master key errors">

package/site/content/docs/recipes/meta.json

@@ -16,6 +16,7 @@
     "---Proxy---",
     "caddy",
     "traefik",
+    "nginx",
     "---Services---",
     "pgdog",
     "rustfs",

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

@@ -0,0 +1,117 @@
+---
+title: "nginx"
+description: "Static reverse proxy via a generated nginx.conf — HTTP on :80 when you bring your own TLS edge."
+icon: "Lock"
+source: "docs/spec/unified-theory.md"
+---
+
+nginx is the classic static reverse proxy — a generated `nginx.conf` forwards to
+`app:6530` on the compose network. Right choice when TLS already terminates elsewhere
+(Cloudflare, ALB, another edge) or you want a hand-edited config.
+
+<Callout title="The one rule">
+  Leave `images.proxy` unset until you need an edge in front of the app. Pin nginx for a static HTTP
+  proxy; prefer [Caddy](/docs/recipes/caddy) or [Traefik](/docs/recipes/traefik) when you want
+  automatic HTTPS in the same stack.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pin the proxy
+
+```typescript title="oke.config.ts"
+images: {
+  proxy: "nginx:1.31-alpine",
+},
+```
+
+`create-oke` offers **nginx** in **Add a reverse proxy…?** (or `--proxy nginx`).
+
+</Step>
+
+<Step>
+### Include the proxy layer
+
+```bash
+docker compose -f docker-compose.yml up -d
+```
+
+Generated `nginx.conf`: `upstream oke_app { server app:6530; }` with
+`proxy_pass http://oke_app` on `:80`. The app host port (`6530`) is unpublished —
+traffic enters through the proxy.
+
+</Step>
+
+<Step>
+### Put TLS in front (optional)
+
+Point Cloudflare / an ALB / another terminator at host `:80`, or switch the pin to
+Caddy / Traefik when you want ACME inside Compose.
+
+</Step>
+
+</Steps>
+
+## Required env
+
+| Variable                | Required?  | Meaning                                                                     |
+| ----------------------- | ---------- | --------------------------------------------------------------------------- |
+| `OKE_PROXY_HOST`        | Optional   | Documented for the proxy role; nginx listens on any `Host` (`_`)            |
+| `allowedHosts` (config) | Production | Must include the public hostname — see [Security](/docs/reference/security) |
+
+## Data and backup
+
+| Volume / bind | Path                                        | What it stores        |
+| ------------- | ------------------------------------------- | --------------------- |
+| Bind mount    | `./nginx.conf` → `/etc/nginx/nginx.conf:ro` | Generated site config |
+
+**Backup means:** the `nginx.conf` is regenerated by `oke docker`. Keep overrides in
+`compose.override.yml` or a replaced file if you customize routing.
+
+## Production note
+
+nginx here is **HTTP-only** on port 80 — no ACME, no Docker service discovery. For
+automatic HTTPS use [Caddy](/docs/recipes/caddy). For `--scale app=N` use
+[Traefik](/docs/recipes/traefik).
+
+**Consequence:** `OKE_PROXY_URL` is `http://…` for this recipe (Caddy / Traefik use
+`https://…`).
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="App still publishes 6530">
+
+You still have `6530:6530` on `app`. Confirm `images.proxy` is set and
+`oke docker` regenerated compose so the app host bind was omitted.
+
+</Accordion>
+<Accordion title="502 Bad Gateway from nginx">
+
+The upstream is `app:6530` on the `oke` network. Confirm the app service is healthy
+and shares that network. Override `nginx.conf` only after checking the generated
+upstream block.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [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`
+
+## Next
+
+<Cards>
+  <Card title="Caddy" description="Automatic HTTPS alternative." href="/docs/recipes/caddy" />
+  <Card title="Traefik" description="Multi-replica alternative." href="/docs/recipes/traefik" />
+  <Card
+    title="PgDog"
+    description="Pool Postgres behind the same stack."
+    href="/docs/recipes/pgdog"
+  />
+</Cards>

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

@@ -26,7 +26,7 @@ drivers: {
   ai: { dev: "ollama", test: "mock", prod: "ollama" }, // or set prod deliberately
 },
 images: {
-  ai: "ollama/ollama:0.32.6", // never :latest — floor 0.17.1 (CVE-2026-7482)
+  ai: "ollama/ollama:0.32.13", // never :latest — floor 0.17.1 (CVE-2026-7482)
 },
 ```
 
@@ -37,7 +37,7 @@ Or run `oke ai setup --provider ollama --yes`.
 <Step>
 ### Env written by the stack
 
-```bash title="docker/.env.docker"
+```bash title=".env.local"
 OKE_AI_URL=http://127.0.0.1:11434
 OKE_AI_MODEL=qwen3.5:9b
 ```
@@ -114,7 +114,7 @@ PII egress rules treat `ollama` as local — see [AI · PII](/docs/elements/ai).
 <Accordions>
 <Accordion title="oke boot: ollama driver needs OKE_AI_URL">
 
-Docker mode expects `OKE_AI_URL` from `docker/.env.docker` when `images.ai` is pinned.
+Docker mode expects `OKE_AI_URL` from `.env.local` when `images.ai` is pinned.
 Locally the default is `http://127.0.0.1:11434`. Prefer `oke ai setup` to wire everything
 in one pass.
 

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

@@ -26,7 +26,7 @@ create-oke asks **Add PgDog connection pooling…?** (or pass `--pgdog`). Manual
 ```typescript title="oke.config.ts"
 images: {
   "store.sql": "postgres:18-alpine",
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.51",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53",
 },
 ```