okengine 0.18.5 → 0.19.1

package/site/content/docs/meta.json

@@ -4,17 +4,18 @@
   "pages": [
     "index",
     "---01 Understand---",
+    "understand",
+    "---02 Elements---",
     "elements",
-    "---02 Build---",
-    "get-started",
-    "ai",
-    "---03 Operate---",
-    "deployment",
-    "---04 Extend---",
+    "---03 Extend---",
     "plugins",
     "providers",
     "recipes",
+    "---04 Client---",
+    "client",
     "---05 Reference---",
-    "reference"
+    "reference",
+    "---06 AI Resources---",
+    "ai"
   ]
 }

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

@@ -71,7 +71,8 @@ const origins = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), origins.sync());
+const corsSyncClock = clock("cors.sync", { every: "30s" });
+on(corsSyncClock, origins.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(cors(origins));
 ```
 

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

@@ -18,6 +18,8 @@ export const app = oke({ name: "shop", env: "dev" }).plug(csrf());
 
 `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.
 
+When `gate.auth.cookies.enabled`, the server **soft-requires** this plugin: prod boots refuse without it; dev/test warn. Use `allowNoHeader: false` for cookie-only SPAs.
+
 ## How it decides
 
 <Steps>
@@ -73,7 +75,8 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), rules.sync());
+const csrfSyncClock = clock("csrf.sync", { every: "30s" });
+on(csrfSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(csrf(rules));
 ```
 

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

@@ -103,7 +103,8 @@ const headerConfig = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), headerConfig.sync());
+const headerSyncClock = clock("headers.sync", { every: "30s" });
+on(headerSyncClock, headerConfig.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(headers(headerConfig));
 ```
 

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -69,7 +69,8 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), rules.sync());
+const ipRulesSyncClock = clock("ip-allowlist.sync", { every: "30s" });
+on(ipRulesSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(ipAllowlist(rules));
 ```
 

package/site/content/docs/plugins/magic-link.mdx

@@ -63,6 +63,12 @@ const { data } = await api.auth.verifyMagicLink({ token });
 
 </Steps>
 
+<Callout type="info" title="Pre-account hijack defense">
+  Completing verify proves inbox ownership. An **unverified** email+password account parked on that
+  address is reclaimed (sessions revoked, hashes cleared, `emailVerified` set). Verified owners
+  re-auth only — no credential purge.
+</Callout>
+
 ## Options
 
 | Option           | Type                | Default                    | Meaning                                   |

package/site/content/docs/plugins/maintenance-mode.mdx

@@ -78,7 +78,8 @@ const maintenance = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), maintenance.sync());
+const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+on(maintenanceSyncClock, maintenance.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
 ```
 

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

@@ -173,7 +173,7 @@ via `POST /auth/oauth/{provider}/link`.
 
 - [Gate](/docs/elements/gate) — `gate.auth`
 - [Passkey](/docs/plugins/passkey) — phishing-resistant alternative
-- [Client](/docs/reference/client) — calling `/auth` from the browser
+- [Client · Auth](/docs/client/auth) — calling `/auth` from the browser
 
 ## Next
 

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

@@ -100,6 +100,12 @@ const { data } = await api.auth.verifyOtp({
 
 </Steps>
 
+<Callout type="info" title="Pre-account hijack defense (email)">
+  App-mode email verify proves inbox ownership. An **unverified** parked email+password account is
+  reclaimed (sessions revoked, hashes cleared, `emailVerified` set) before the OTP session. Verified
+  owners re-auth only.
+</Callout>
+
 ## Modes
 
 |                      | Provider mode                 | App mode                                      |
@@ -202,6 +208,7 @@ In `local` / `test` the `console` driver captures messages. Use
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
+- [Two-factor](/docs/plugins/two-factor) — email OTP / TOTP as a **second** factor after password (distinct from this primary `/auth/otp` sign-in)
 - [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
 - [Gate](/docs/elements/gate) — `gate.auth`
 
@@ -209,6 +216,10 @@ In `local` / `test` the `console` driver captures messages. Use
 
 <Cards>
   <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
-  <Card title="Two-factor" description="TOTP second factor." href="/docs/plugins/two-factor" />
+  <Card
+    title="Two-factor"
+    description="TOTP / email OTP second factor."
+    href="/docs/plugins/two-factor"
+  />
   <Card title="Channel" description="Delivery drivers and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -1,17 +1,17 @@
 ---
 title: "Passkey"
-description: "Official plugin — WebAuthn register and authenticate under /auth with signature and origin checks."
+description: "Official plugin — WebAuthn register and authenticate under /auth with UV, signCount, and ceremony session binding."
 icon: "FingerprintPattern"
 source: "docs/spec/unified-theory.md"
 ---
 
-`passkey()` adds register and authenticate Flows for WebAuthn credentials (`oke_passkeys`).
-Options return a challenge; register and authenticate verify `clientDataJSON` origin + challenge,
-`authenticatorData` rpId hash, and an ECDSA P-256 signature against the stored SPKI public key.
+`passkey()` adds register and authenticate Flows for WebAuthn credentials
+(`oke_passkeys`). Options return a challenge plus a ceremony `sessionId`;
+register/authenticate verify client data, authenticator data, and ECDSA P-256.
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(passkey())`. Registration needs a Bearer session; authenticate is
-  public. Post the full ceremony fields — presence of a stored credential alone never issues a
+  public. Echo the options `sessionId` with every ceremony — UV=false assertions never mint a
   session.
 </Callout>
 
@@ -42,15 +42,16 @@ Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take
 
 ```typescript
 const opts = await api.auth.passkeyRegisterOptions({});
-// opts.data: { challenge, rpId, userId }
+// opts.data: { challenge, sessionId, rpId, userId }
 
 await api.auth.passkeyRegister({
   credentialId: "...", // base64url
   publicKey: "...", // base64url SPKI (ECDSA P-256)
   userId: opts.data!.userId,
   challenge: opts.data!.challenge,
-  clientDataJSON: "...", // base64url JSON { type, challenge, origin }
-  authenticatorData: "...", // base64url
+  sessionId: opts.data!.sessionId,
+  clientDataJSON: "...", // base64url JSON { type: "webauthn.create", challenge, origin }
+  authenticatorData: "...", // base64url (UP|UV required)
   signature: "...", // base64url ECDSA over authData || SHA-256(clientDataJSON)
 });
 ```
@@ -67,19 +68,30 @@ const opts = await api.auth.passkeyAuthenticateOptions({});
 const { data } = await api.auth.passkeyAuthenticate({
   credentialId: "...",
   challenge: opts.data!.challenge,
-  clientDataJSON: "...",
+  sessionId: opts.data!.sessionId,
+  clientDataJSON: "...", // type must be "webauthn.get"
   authenticatorData: "...",
   signature: "...",
 });
 ```
 
 Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
-Challenges are single-use; wrong origin → `invalid_origin`; bad signature → `invalid_credentials`.
+Challenges are single-use and bound to `sessionId`; wrong origin → `invalid_origin`; UV
+missing → `user_not_verified`; cloned counter → `reregister_required`.
 
 </Step>
 
 </Steps>
 
+## Server checks
+
+| Check             | Behavior                                                                                                                |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Ceremony type     | `clientDataJSON.type` must be `webauthn.create` (register) or `webauthn.get` (authenticate)                             |
+| User verification | AuthenticatorData UV bit must be set — UV=false is always rejected                                                      |
+| Challenge binding | Challenge hash + `sessionId` must match; TTL ≤ 5 minutes; single-use                                                    |
+| Signature counter | Stored per credential; if stored ≠ 0 and incoming `signCount` ≤ stored → delete credential, warn, `reregister_required` |
+
 ## Options
 
 | Option       | Type                | Default                                    | Meaning                          |
@@ -101,8 +113,8 @@ Challenges are single-use; wrong origin → `invalid_origin`; bad signature →
 | `auth.passkeyAuthenticateOptions` | `POST /auth/passkey/authenticate/options` | `gate.public` + otp rate |
 | `auth.passkeyAuthenticate`        | `POST /auth/passkey/authenticate`         | `gate.public` + otp rate |
 
-**Consequence:** a stolen `credentialId` without the private key cannot mint a session. Set
-`origins` to your real app origins before production.
+**Consequence:** a stolen `credentialId` without the private key (and UV) cannot mint a session.
+Set `origins` to your real app origins before production.
 
 ## Troubleshooting
 
@@ -116,11 +128,23 @@ Sign in with another method first. `userId` in the body must match the Bearer se
 
 `clientDataJSON.origin` must be in `passkey({ origins })`. Default allows only localhost HTTP/S.
 
+</Accordion>
+<Accordion title="authenticate returns user_not_verified">
+
+AuthenticatorData UV bit was not set. Require user verification on the client
+(`userVerification: "required"`) — the server never accepts UV=false.
+
+</Accordion>
+<Accordion title="authenticate returns reregister_required">
+
+Signature counter did not increase (possible cloned authenticator). That credential was
+deleted — register a fresh passkey for the account.
+
 </Accordion>
 <Accordion title="authenticate returns invalid_credentials">
 
-Unknown `credentialId`, consumed/expired challenge, bad signature, or rpId hash mismatch.
-Re-run authenticate options for a fresh challenge, then sign with the enrolled private key.
+Unknown `credentialId`, wrong/expired/`sessionId` mismatch, bad signature, wrong ceremony
+type, or rpId hash mismatch. Re-run authenticate options for a fresh challenge + `sessionId`.
 
 </Accordion>
 </Accordions>
@@ -129,7 +153,7 @@ Re-run authenticate options for a fresh challenge, then sign with the enrolled p
 
 - [Two-factor](/docs/plugins/two-factor) — TOTP step-up
 - [Gate](/docs/elements/gate) — `gate.auth`
-- [Client](/docs/reference/client) — calling `/auth` from the browser
+- [Client · Auth](/docs/client/auth) — calling `/auth` from the browser
 
 ## Next
 

package/site/content/docs/plugins/two-factor.mdx

@@ -1,17 +1,18 @@
 ---
 title: "Two-factor"
-description: "Official plugin — TOTP enable, verify, and disable for an authenticated session."
+description: "Official plugin — method-locked TOTP or email OTP after first-factor sign-in, with step-up enrollment and method change."
 icon: "LockKeyhole"
 source: "docs/spec/unified-theory.md"
 ---
 
-`twoFactor()` adds RFC 6238 TOTP (HMAC-SHA1, 6 digits, 30s) after someone already has a session.
-Enable returns a secret, `otpauth://` URL, and recovery codes; verify mints a new session.
-TOTP codes are compared in constant time (±1 step window).
+`twoFactor()` adds a second factor after password (or username) sign-in: RFC 6238
+TOTP or email OTP. When 2FA is enabled, first-factor success withholds session
+tokens and returns a **method-locked** challenge.
 
 <Callout title="The one rule">
-  Enable `gate.auth`, then `.plug(twoFactor())`. Enable and disable need a Bearer session —
-  verify is public and takes `{ userId, code }` after password (or other) sign-in.
+  Enable `gate.auth`, then `.plug(twoFactor())`. Login challenges lock the configured method (`totp`
+  or `email_otp`). Mid-challenge QR enrollment returns `Forbidden`. Method change needs step-up
+  verify → provision → confirm.
 </Callout>
 
 ## Quick start
@@ -35,69 +36,124 @@ export const app = oke({
 </Step>
 
 <Step>
-### Enable (session required)
+### First-time enable (session required)
 
 Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take input only.
 
 ```typescript
 const { data } = await api.auth.twoFactorEnable({});
-// data.secret, data.otpauthUrl, data.recoveryCodes
+// data.secret, data.otpauthUrl, data.recoveryCodes, data.method === "totp"
 ```
 
-`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once; they are
-shown only here.
+`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once.
+Re-enrollment when 2FA is already enabled requires step-up first
+(`twoFactorStepUp`). An active login challenge → `Forbidden` / `active_2fa_challenge`.
 
 </Step>
 
 <Step>
-### Verify a code
+### Sign-in then verify
 
 ```typescript
-const { data } = await api.auth.twoFactorVerify({ userId, code: "123456" });
-// hybrid session tokens — recovery codes also accepted once each
+const signIn = await api.auth.signInUsername({ username, password });
+if ("twoFactorRequired" in signIn.data && signIn.data.twoFactorRequired) {
+  const { data } = await api.auth.twoFactorVerify({
+    challengeId: signIn.data.challengeId,
+    code: "123456",
+  });
+  // hybrid session tokens
+}
 ```
 
-`POST /auth/two-factor/verify`. Missing / disabled factor or bad code → `AuthFailed` /
-`invalid_credentials`. Disable: `api.auth.twoFactorDisable` (Bearer via `auth.getToken`).
+`POST /auth/two-factor/verify` takes `{ challengeId, code }` — not a bare
+`userId`. Missing challenge, method mismatch, or bad code → `AuthFailed` /
+`invalid_credentials`.
 
 </Step>
 
 </Steps>
 
+## Method lock
+
+When a login challenge is issued, the active method is recorded on the pending
+challenge. Until that challenge is consumed or expires:
+
+- Only codes for the **locked** method are accepted.
+- `twoFactorEnable`, `twoFactorChangeMethod`, `twoFactorConfirmChange`, and
+  `twoFactorDisable` return `Forbidden` with `active_2fa_challenge` if called
+  for that user (including with an older Bearer session).
+
+This closes the July–August 2026 method-switching bypass pattern (switch to
+TOTP enrollment mid email-OTP challenge without proving the current factor).
+
+## Step-up and method change
+
+1. `POST /auth/two-factor/step-up` — `{ code, purpose }` verifies the **current**
+   method and grants a short-lived step-up (`enroll` | `change` | `disable`).
+2. `POST /auth/two-factor/change-method` — `{ method, email? }` provisions the new
+   method in a pending state (TOTP QR or email OTP). Requires step-up.
+3. `POST /auth/two-factor/confirm-change` — `{ code }` activates the new method and
+   **immediately invalidates** the old secret / recovery codes.
+
+Disable also requires step-up when 2FA is already enabled.
+
 ## Options
 
-| Option     | Type             | Default    | Meaning                          |
-| ---------- | ---------------- | ---------- | -------------------------------- |
-| `secret`   | `string`         | active\*   | HMAC secret (\*from `gate.auth`) |
-| `sessions` | `SessionStore`   | active\*   | Session store                    |
-| `now`      | `() => number`   | `Date.now` | Injectable clock                 |
-| `factors`  | `TwoFactorStore` | new        | Per-user TOTP + recovery hashes  |
-| `issuer`   | `string`         | `"oke"`    | Label in `otpauth://` URLs       |
+| Option          | Type                    | Default    | Meaning                                      |
+| --------------- | ----------------------- | ---------- | -------------------------------------------- |
+| `secret`        | `string`                | active\*   | HMAC secret (\*from `gate.auth`)             |
+| `sessions`      | `SessionStore`          | active\*   | Session store                                |
+| `now`           | `() => number`          | `Date.now` | Injectable clock                             |
+| `factors`       | `TwoFactorStore`        | new        | Per-user method + TOTP / recovery            |
+| `issuer`        | `string`                | `"oke"`    | Label in `otpauth://` URLs                   |
+| `pending`       | `PendingTwoFactorStore` | active\*   | Login challenges                             |
+| `stepUp`        | `StepUpStore`           | active\*   | Privileged-op grants                         |
+| `verifications` | `VerificationStore`     | active\*   | Email OTP as second factor (`2fa:{userId}`)  |
+| `exposeDevOtp`  | `boolean`               | `false`    | Return `devOtp` on email_otp challenge paths |
 
 ## Surfaces
 
-| Flow                    | Path                            | Gate                     |
-| ----------------------- | ------------------------------- | ------------------------ |
-| `auth.twoFactorEnable`  | `POST /auth/two-factor/enable`  | session + bearer         |
-| `auth.twoFactorVerify`  | `POST /auth/two-factor/verify`  | `gate.public` + otp rate |
-| `auth.twoFactorDisable` | `POST /auth/two-factor/disable` | session + bearer         |
+| Flow                            | Path                                      | Gate                     |
+| ------------------------------- | ----------------------------------------- | ------------------------ |
+| `auth.twoFactorEnable`          | `POST /auth/two-factor/enable`            | session + bearer         |
+| `auth.twoFactorVerify`          | `POST /auth/two-factor/verify`            | `gate.public` + otp rate |
+| `auth.twoFactorStepUp`          | `POST /auth/two-factor/step-up`           | session + bearer         |
+| `auth.twoFactorChangeMethod`    | `POST /auth/two-factor/change-method`     | session + bearer         |
+| `auth.twoFactorConfirmChange`   | `POST /auth/two-factor/confirm-change`    | session + bearer         |
+| `auth.twoFactorRequestEmailOtp` | `POST /auth/two-factor/request-email-otp` | public + otp rate        |
+| `auth.twoFactorDisable`         | `POST /auth/two-factor/disable`           | session + bearer         |
 
-**Consequence:** verify issues a full session for `userId` — use it as the step after first-factor
-sign-in when the account has 2FA enabled.
+**Consequence:** email/password and username sign-in return
+`{ twoFactorRequired, challengeId, method, userId }` (no tokens) when the
+account has 2FA enabled. Complete login only via `twoFactorVerify`.
 
 ## Troubleshooting
 
 <Accordions>
+<Accordion title="twoFactorEnable returns Forbidden active_2fa_challenge">
+
+Finish or wait out the login 2FA challenge first. Enrollment is blocked while
+an unresolved challenge exists for that user.
+
+</Accordion>
+<Accordion title="twoFactorEnable returns Forbidden step_up_required">
+
+2FA is already enabled. Call `twoFactorStepUp` with a valid current-method code
+(`purpose: "enroll"`), then enable again.
+
+</Accordion>
 <Accordion title="twoFactorEnable returns AuthFailed unauthenticated">
 
-Wire a session into `createClient` (`auth.getToken` / `memorySession`) from email/password
-(or another method) first — enable is gated on Bearer.
+Wire a session into `createClient` (`auth.getToken` / `memorySession`) first —
+enable is gated on Bearer. First-time enroll must happen **before** 2FA is
+required on sign-in (or after a full session from a completed challenge).
 
 </Accordion>
 <Accordion title="verify always fails">
 
-Code must be six digits. Check clock skew (±1 window), and that you enrolled the `secret` from
-enable. A recovery code works once, then is consumed.
+Submit `{ challengeId, code }` from the sign-in challenge response. TOTP must be
+six digits (±1 window). Email OTP uses the code from the locked `email_otp`
+challenge. A recovery code works once for TOTP, then is consumed.
 
 </Accordion>
 </Accordions>
@@ -107,7 +163,8 @@ enable. A recovery code works once, then is consumed.
 - [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against
-- OTP over SMS or email instead of TOTP? See [OTP](/docs/plugins/otp) / [Magic link](/docs/plugins/magic-link)
+- Primary OTP sign-in (not a second factor)? See [OTP](/docs/plugins/otp) /
+  [Magic link](/docs/plugins/magic-link)
 
 ## Next
 

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

@@ -102,7 +102,7 @@ on purpose — do not treat it as "exists" in the UI.
 
 - [Gate](/docs/elements/gate) — `gate.auth` and posture
 - [Plugins](/docs/plugins) — all auth method plugins
-- [Client](/docs/reference/client) — `createClient` + `memorySession`
+- [Client · Auth](/docs/client/auth) — `createClient` + `memorySession`
 
 ## Next
 

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

@@ -81,7 +81,7 @@ Caddy has **no** service-discovery story for multiple `app` replicas. Once you r
 discovers replicas from Docker labels instead of a static `reverse_proxy` target.
 
 Also set `allowedHosts` to your public hostname before exposing the edge — see
-[Reverse proxy](/docs/deployment/reverse-proxy).
+[Security](/docs/reference/security).
 
 ## What the recipe configures
 
@@ -111,8 +111,8 @@ Expected with the local CA. Install Caddy's local root for that machine, or set
 
 ## Learn more
 
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx choice
-- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Traefik](/docs/recipes/traefik) — multi-replica discovery via Docker labels
+- [nginx](/docs/recipes/nginx) — static HTTP reverse proxy
 - [Security](/docs/reference/security) — `allowedHosts`
 
 ## Next

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