okengine 0.18.4 → 0.19.0

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

@@ -12,7 +12,7 @@ These recipes are real, working infrastructure choices behind the same two templ
 
 <Callout title="The one rule">
   Vendor choice lives in `images[…]` — never in `drivers.*`, which only ever say protocol ids
-  (`postgres`, `redis`, `s3`, `smtp`, `meilisearch`, `openai-compatible`, `ollama`, …).
+  (`postgres`, `redis`, `s3`, `smtp`, `meilisearch`, `openai-compatible`, …).
 </Callout>
 
 ## SQL
@@ -98,45 +98,35 @@ Opt-in via `images.proxy` — leave unset until you need an edge or `--scale app
   />
 </Cards>
 
-## AI (local / self-hosted)
+## AI
 
-Default local pin is **llama.cpp**. Ollama stays fully supported. vLLM / SGLang
-are production-tier self-host options — most apps still use a managed provider.
+Compose does not manage inference. Prefer [OpenRouter](/docs/recipes/openrouter)
+for zero-Docker `fx.ask`, or BYO any OpenAI-shaped `/v1` via `OKE_AI_URL` /
+`baseUrl` — see [Models](/docs/elements/ai/models).
 
-| Workload                         | Recipe                                         |
-| -------------------------------- | ---------------------------------------------- |
-| Single-user / dev (lightest)     | [llama.cpp](/docs/recipes/llama-cpp) (default) |
-| Local library UX                 | [Ollama](/docs/recipes/ollama)                 |
-| Multi-user GPU concurrency       | [vLLM](/docs/recipes/vllm)                     |
-| Structured / agent GPU workloads | [SGLang](/docs/recipes/sglang)                 |
-| Managed cloud                    | Anthropic / OpenAI / … (no `images.ai`)        |
-
-All four recipes **loopback-publish only** and pin explicit tags (never
-`latest`). Load models from curated registries — never arbitrary untrusted GGUF.
+| Workload                       | Where                                  |
+| ------------------------------ | -------------------------------------- |
+| Zero Docker / free cloud smoke | [OpenRouter](/docs/recipes/openrouter) |
+| BYO OpenAI-compatible `/v1`    | [Models](/docs/elements/ai/models)     |
+| Managed cloud (registry)       | [Models](/docs/elements/ai/models)     |
 
 <Cards>
   <Card
-    title="llama.cpp"
-    description="Default local AI — OpenAI /v1, lightest footprint."
-    href="/docs/recipes/llama-cpp"
-  />
-  <Card
-    title="Ollama"
-    description="Fully supported alternative — library pull UX."
-    href="/docs/recipes/ollama"
+    title="OpenRouter"
+    description="Zero Docker — openrouter/free + auto baseUrl."
+    href="/docs/recipes/openrouter"
   />
-  <Card title="vLLM" description="Self-hosted multi-user GPU serving." href="/docs/recipes/vllm" />
   <Card
-    title="SGLang"
-    description="Self-hosted structured / agent GPU serving."
-    href="/docs/recipes/sglang"
+    title="Models"
+    description="Registry providers + custom baseUrl / OKE_AI_URL."
+    href="/docs/elements/ai/models"
   />
 </Cards>
 
 ## Learn more
 
 - [Providers](/docs/providers) — managed cloud alternatives
-- [Docker](/docs/deployment/docker) — compose derivation, PgDog, reverse proxy
+- [Configuration](/docs/reference/configuration) — `images` roles and compose derivation
 - [Store](/docs/elements/store) — `sql` / `kv` / `files` / `index` facets
 
 ## Next
@@ -148,5 +138,5 @@ All four recipes **loopback-publish only** and pin explicit tags (never
     href="/docs/recipes/postgres"
   />
   <Card title="Providers" description="Managed cloud alternatives." href="/docs/providers" />
-  <Card title="Deployment" description="Compose, Swarm, or Kubernetes." href="/docs/deployment" />
+  <Card title="Caddy" description="Automatic HTTPS edge." href="/docs/recipes/caddy" />
 </Cards>

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

@@ -28,7 +28,7 @@ drivers: {
   },
 },
 images: {
-  channel: { email: "axllent/mailpit:v1.30.7" },
+  channel: { email: "axllent/mailpit:v1.31.1" },
 },
 ```
 

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

@@ -126,9 +126,9 @@ surfaces as `meilisearch index: unreachable at <url> — …`.
 
 <Cards>
   <Card
-    title="llama.cpp"
-    description="Default local AI for the same stack."
-    href="/docs/recipes/llama-cpp"
+    title="OpenRouter"
+    description="Zero Docker cloud AI for the same stack."
+    href="/docs/recipes/openrouter"
   />
   <Card
     title="Postgres"

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

@@ -23,9 +23,6 @@
     "mailpit",
     "meilisearch",
     "---AI---",
-    "llama-cpp",
-    "ollama",
-    "vllm",
-    "sglang"
+    "openrouter"
   ]
 }

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

@@ -100,8 +100,8 @@ upstream block.
 
 ## Learn more
 
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx choice
-- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Caddy](/docs/recipes/caddy) — automatic HTTPS alternative
+- [Traefik](/docs/recipes/traefik) — multi-replica discovery via Docker labels
 - [Security](/docs/reference/security) — `allowedHosts`
 
 ## Next

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

@@ -0,0 +1,283 @@
+---
+title: "OpenRouter"
+description: "Cloud path for fx.ask — provider openrouter auto-resolves base URL; router aliases pick free, auto, coding, fusion, and latest models."
+icon: "Globe"
+source: "docs/spec/unified-theory.md"
+---
+
+OpenRouter is the simplest way to call a real model from OKE: no Docker, no
+Python, no local weights. Set `provider: "openrouter"` and an API key —
+`baseUrl` resolves from the verified registry.
+
+<Callout title="The one rule">
+  Use a dedicated OpenRouter API key on the binding (`apiKey`), prefer the stable `openrouter/free`
+  router alias for zero-cost smoke tests, and keep other providers on their own `ai.model` +
+  `apiKey` so keys never collide.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Declare the cloud binding
+
+```typescript
+import { ai } from "okengine";
+
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const triage = smart.prompt("triage");
+```
+
+`baseUrl` becomes `https://openrouter.ai/api/v1` automatically. Pass an explicit
+`baseUrl` only to point at a proxy or mirror.
+
+</Step>
+
+<Step>
+### Ask from a flow
+
+```typescript title="src/flows/main/ask.ts"
+import { on, flow, http } from "okengine";
+
+export const ask = on(
+  http.post(),
+  flow({ asks: ["triage"] }, async (fx, input) => {
+    return await fx.ask("triage", input);
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Optional setup via CLI
+
+create-oke **Recommended** / Customize / Reuse and `oke ai setup --provider openrouter`
+pick `openrouter/free`, write `OPENROUTER_API_KEY` to `.env.local` + `vault.secret` (no
+`dev:` stub). Missing key → `oke dev` asks again ([openrouter.ai](https://openrouter.ai)).
+
+</Step>
+
+</Steps>
+
+## Router aliases
+
+OpenRouter **routers** are model slugs that pick (or compose) upstream models for
+you. Pass the slug as `model` on `ai.model` — same as any other OpenRouter id.
+
+| Slug                                                                                           | What it does                                          | Cost                            |
+| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------- |
+| [`openrouter/free`](https://openrouter.ai/docs/guides/routing/routers/free-router)             | Random free model that supports your request features | Free                            |
+| [`openrouter/auto`](https://openrouter.ai/docs/guides/routing/routers/auto-router)             | Market-based pick by task type + cost tier            | Selected model rate             |
+| [`openrouter/pareto-code`](https://openrouter.ai/docs/guides/routing/routers/pareto-router)    | Strong coding model by `min_coding_score`             | Selected model rate             |
+| [`openrouter/fusion`](https://openrouter.ai/docs/guides/routing/routers/fusion-router)         | Multi-model panel + analyst deliberation              | ~4–5× one completion            |
+| [`openrouter/bodybuilder`](https://openrouter.ai/docs/guides/routing/routers/body-builder)     | NL → parallel request bodies (you run them)           | Builder free; executions billed |
+| [`~author/family-latest`](https://openrouter.ai/docs/guides/routing/routers/latest-resolution) | Newest concrete version in a family                   | Target model rate               |
+
+**Consequence:** the response `model` field is the concrete upstream that answered —
+log it for auditability.
+
+Router plugin knobs (`cost_tier`, `allowed_models`, `min_coding_score`, fusion
+panel) live on OpenRouter’s request `plugins` / account Routing defaults; OKE
+passes the `model` slug through the openai-compatible driver.
+
+### Free Models Router — `openrouter/free`
+
+Ideal for smoke tests, demos, and learning. The router filters free models for
+capabilities your request needs (vision, tools, structured outputs), then picks
+one at random.
+
+```typescript
+export const smoke = ai.model("smoke", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+| Detail           | Behavior                                         |
+| ---------------- | ------------------------------------------------ |
+| Selection        | Random among eligible free models                |
+| Pin a free model | Use `author/model:free` instead of the router    |
+| Limits           | Lower rate limits; availability and latency vary |
+
+Official guide:
+[Free Models Router](https://openrouter.ai/docs/guides/routing/routers/free-router).
+
+### Auto Router — `openrouter/auto`
+
+Classifies the prompt (~30 task types), ranks by community spend share over a
+trailing 7-day window, then applies your cost band and fallbacks.
+
+```typescript
+export const smart = ai.model("smart", {
+  provider: "openrouter",
+  model: "openrouter/auto",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+| Detail       | Behavior                                                      |
+| ------------ | ------------------------------------------------------------- |
+| Early track  | `openrouter/auto-beta` (plugin id `auto-beta-router`)         |
+| Cost bands   | `low` · `medium` · `high` · `xhigh` · `max` (default ≈ `low`) |
+| Allow / deny | Wildcard patterns via `allowed_models` / `excluded_models`    |
+| Sessions     | Prefers the prior model while it stays a top candidate        |
+| Pricing      | No router fee — pay the selected model                        |
+
+Official guide:
+[Auto Router](https://openrouter.ai/docs/guides/routing/routers/auto-router).
+
+### Pareto Router — `openrouter/pareto-code`
+
+Coding-only. You set a minimum coding score (`0`–`1`); the router maps it to a
+tier and picks the cheapest (or fastest with `:nitro`) eligible model.
+
+```typescript
+export const coder = ai.model("coder", {
+  provider: "openrouter",
+  model: "openrouter/pareto-code",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+| `min_coding_score`             | Tier                          |
+| ------------------------------ | ----------------------------- |
+| `>= 0.66` (default if omitted) | high — top of AA coding field |
+| `>= 0.33`, `< 0.66`            | medium                        |
+| `< 0.33`                       | low                           |
+
+Within the tier: cheapest available (+ same-tier fallbacks on provider errors).
+Use `session_id` for multi-turn stickiness. Official guide:
+[Pareto Router](https://openrouter.ai/docs/guides/routing/routers/pareto-router).
+
+### Fusion Router — `openrouter/fusion`
+
+A panel of models answers in parallel; an analyst returns structured consensus /
+contradictions / gaps; your outer model writes the final answer.
+
+```typescript
+export const deliberate = ai.model("deliberate", {
+  provider: "openrouter",
+  model: "openrouter/fusion",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+| Detail        | Behavior                                                        |
+| ------------- | --------------------------------------------------------------- |
+| Fast preset   | `openrouter/fusion-flash` (`general-fast` panel)                |
+| Default panel | Quality: Claude Opus / GPT / Gemini latest aliases              |
+| Cost          | N panel + 1 analyst + outer — expect ~4–5× with 3 models        |
+| Force fusion  | OpenRouter `tool_choice: "required"` (model decides by default) |
+
+Official guide:
+[Fusion Router](https://openrouter.ai/docs/guides/routing/routers/fusion-router).
+
+### Body Builder — `openrouter/bodybuilder`
+
+Describe a multi-model job in natural language. The response is JSON
+`{ requests: [...] }` — generate is free; you execute each body yourself.
+Useful for A/B checks, not a single `fx.ask` answer.
+
+```typescript
+export const builder = ai.model("builder", {
+  provider: "openrouter",
+  model: "openrouter/bodybuilder",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+Official guide:
+[Body Builder](https://openrouter.ai/docs/guides/routing/routers/body-builder).
+
+### Latest resolution — `~author/family-latest`
+
+Stable family alias that always retargets to the newest visible model in that
+family. Response `model` reports the concrete slug.
+
+```typescript
+export const opus = ai.model("opus", {
+  provider: "openrouter",
+  model: "~anthropic/claude-opus-latest",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+| Detail           | Behavior                                                  |
+| ---------------- | --------------------------------------------------------- |
+| Reproducibility  | Pin a concrete slug (e.g. `anthropic/claude-opus-4.8`)    |
+| Reasoning params | Unsupported `none` / disabled may remap on `~latest` only |
+| Pricing          | Listed as the current target’s rates                      |
+
+Official guide:
+[Latest Model Resolution](https://openrouter.ai/docs/guides/routing/routers/latest-resolution).
+
+## Multi-provider projects
+
+```typescript
+export const viaOr = ai.model("via-or", {
+  provider: "openrouter",
+  model: "openrouter/free",
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export const viaGroq = ai.model("via-groq", {
+  provider: "groq",
+  model: "llama-3.1-8b-instant",
+  apiKey: process.env.GROQ_API_KEY,
+});
+```
+
+Each binding keeps its own `apiKey` and auto-resolved `baseUrl`. No shared
+process-wide token.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="401 / invalid API key">
+
+Pass `apiKey` on the binding (or the env your setup wrote). OpenRouter does not
+accept an OpenAI key against its base URL.
+
+</Accordion>
+<Accordion title="Unknown provider error">
+
+Typos fail loud: unknown names require an explicit `baseUrl`. Known names are
+listed on [Models](/docs/elements/ai/models).
+
+</Accordion>
+<Accordion title="Free router feels flaky or rate-limited">
+
+`openrouter/free` picks randomly among eligible free models — availability and
+limits change. Pin `author/model:free` or move to `openrouter/auto` / a paid id
+for stable prod paths.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Models](/docs/elements/ai/models) — verified providers, limited compatibility, BYO `/v1`
+- [AI](/docs/elements/ai) — prompts and `fx.ask`
+- [OpenRouter routers](https://openrouter.ai/docs/guides/routing/routers/auto-router) — Auto, Free, Pareto, Fusion, Body Builder, Latest
+
+Any OpenAI-compatible `/v1` endpoint works via custom `baseUrl` / `OKE_AI_URL`
+on an `openai-compatible` binding — see Models.
+
+## Next
+
+<Cards>
+  <Card
+    title="Models"
+    description="Provider registry + custom URL."
+    href="/docs/elements/ai/models"
+  />
+  <Card title="AI" description="Prompts and guardrails." href="/docs/elements/ai" />
+</Cards>

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.53",
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
 },
 ```
 
@@ -99,7 +99,7 @@ not wired into the generated stack yet.
 | -------------- | ------------------------------------------------------- |
 | Container port | `6432`                                                  |
 | `dependsOn`    | `store-sql` healthy                                     |
-| Healthcheck    | `pg_isready -h 127.0.0.1 -p 6432`, every 5s, 12 retries |
+| Healthcheck    | `pg_isready -h 127.0.0.1 -p 6432`, every 2s, 20 retries |
 | Connection URL | `postgres://user:pass@host:6432/db`                     |
 
 ## Troubleshooting
@@ -123,9 +123,9 @@ Postgres), keep `DATABASE_URL` on the pooler for app traffic.
 
 ## Learn more
 
-- [Docker · PgDog pooling](/docs/deployment/docker#pgdog-pooling) — compose `-f` layer order
 - [Postgres](/docs/recipes/postgres) — the backend PgDog fronts
 - [Store · SQL](/docs/elements/store#sql) — “Connection pooling is infrastructure”
+- [Configuration](/docs/reference/configuration) — `images.pgdog` and compose layers
 
 ## Next
 

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

@@ -85,8 +85,7 @@ The recipe does **not** declare a named compose volume. Persistence rides the im
 ## Production note
 
 For multi-replica apps, keep SQL on a shared Postgres — Clock CronStore and durable
-journal need one backend. See [Clock](/docs/elements/clock#what-the-runtime-guarantees) ·
-[Docker](/docs/deployment/docker#share-backing-services).
+journal need one backend. See [Clock](/docs/elements/clock#what-the-runtime-guarantees).
 
 Scale out with [PgDog](/docs/recipes/pgdog) so `N × Bun.SQL pool` does not exhaust
 `max_connections`. Do not also stack a managed provider's pooler on the same URL.

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

@@ -27,7 +27,7 @@ drivers: {
   },
 },
 images: {
-  store: { files: "rustfs/rustfs:1.0.0-rc.2" },
+  store: { files: "rustfs/rustfs:1.0.0-rc.5" },
 },
 ```
 
@@ -132,7 +132,7 @@ running service; confirm health at `/health` before debugging client signatures.
 
 - [Store · Files](/docs/elements/store#files) — facet API and drivers
 - [Environment variables](/docs/reference/environment-variables) — full `S3_*` map
-- [Installation](/docs/get-started/installation) — docker env cheat sheet
+- [Recipes](/docs/recipes) — docker env cheat sheet
 
 ## Next
 

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

@@ -78,7 +78,7 @@ durable state.
 
 Security posture is intentional: Traefik talks to `tcp://socket-proxy:2375` with a
 filtered API (`CONTAINERS`, `EVENTS`, `PING`, `VERSION`, `NETWORKS` only). Never mount
-raw `docker.sock` on Traefik — see [Reverse proxy](/docs/deployment/reverse-proxy).
+raw `docker.sock` on Traefik — keep the socket-proxy companion in front.
 
 HTTP entrypoint redirects to `websecure`. For a single instance with no scale plans,
 [Caddy](/docs/recipes/caddy) is simpler (no labels, no companion).
@@ -122,8 +122,8 @@ re-issuing repeatedly.
 
 ## Learn more
 
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Docker-socket-proxy security rationale
-- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Caddy](/docs/recipes/caddy) — simpler single-instance HTTPS edge
+- [nginx](/docs/recipes/nginx) — static HTTP reverse proxy
 - [Security](/docs/reference/security) — `allowedHosts`
 
 ## Next