okengine 0.3.6 → 0.5.0

package/site/content/docs/elements/gate.mdx

@@ -1,15 +1,17 @@
 ---
 title: "Gate"
-description: "Permission to act — auth policies and rate limits attached to the trigger, evaluated before any effect runs, denied as typed errors."
+description: "Permission to act — policies, rate limits, and built-in auth on the HTTP trigger, evaluated before any effect runs."
 icon: "ShieldCheck"
 source: "docs/spec/unified-theory.md"
 ---
 
-Gate is how your app answers **"may this happen?"** before it happens: is this request from a verified member? has this IP exhausted its minute quota? Gates attach to the trigger — the pipeline evaluates them before a single store write, emit, or channel send runs.
+Gate answers **"may this happen?"** before it happens: is this a verified member? has this IP
+burned its minute quota? Attach gates to the HTTP trigger — the pipeline checks them before a
+store write, emit, or channel send runs.
 
 <Callout title="The one rule">
-  Permission sits **at the trigger**, and denial is a typed error value — never a thrown exception,
-  never an effect that runs halfway and rolls back.
+  Every HTTP trigger declares posture: attach a real gate, or attach `gate.public`. Omitting both
+  fails boot. Denial is a typed error value — never a thrown exception mid-`do`.
 </Callout>
 
 ## Quick start
@@ -17,50 +19,80 @@ Gate is how your app answers **"may this happen?"** before it happens: is this r
 <Steps>
 
 <Step>
-### Declare your gates
+### Declare policies and register the Gate bag
 
-Policies are named predicates; rate limits are declarative budgets. Both live once, app-wide:
+Policies are named predicates; rate limits are declarative budgets. Put the ones you reuse in
+`oke({ gate: { policies } })`:
 
 ```typescript title="src/gates.ts"
 import { gate } from "okengine";
 
-export const member = gate.policy("member", ({ auth }) => !!auth?.verified);
+export const member = gate.policy("member", ({ auth }) => !!auth.verified);
+
+export const canBook = gate.scope("booking:create");
 
 export const fair = gate.rate({
-  strategy: "sliding-window-counter", // the default — near-exact, no boundary bursts
   max: 60,
   per: "1m",
   keyBy: "ip",
 });
 ```
 
+`gate.scope(name)` is sugar for
+`gate.policy(name, ({ auth }) => auth.scopes.has(name))` — one string is both the policy id and
+the scope checked.
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { member, canBook, fair } from "./gates";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { policies: [member, canBook, fair] },
+});
+```
+
 </Step>
 
 <Step>
 ### Attach them to triggers
 
-`.gate(...)` composes in registration order — evaluated left to right, first denial wins:
+`.gate(...)` composes left to right — first denial wins. Public routes must say so explicitly:
 
 ```typescript title="src/flows/links/shorten.ts"
+import { on, flow, http, gate } from "okengine";
+import { member, canBook, fair } from "../../gates";
+
+export const health = on(
+  http.get("/health").gate(gate.public),
+  flow({
+    out: HealthOut,
+    do: () => ({ ok: true as const }),
+  }),
+);
+
 export const shorten = on(
-  http.post("/links").gate(member, fair),
+  http.post("/links").gate(member, canBook, fair),
   flow({
     in: NewLink,
     out: LinkCode,
     errors: { Taken },
     do: async ({ url, code }, fx) => {
-      /* runs only if both gates passed */
+      /* runs only if every gate passed */
     },
   }),
 );
 ```
 
+Do **not** put `gate.public` in `gate.policies` — attach it on the trigger only.
+
 </Step>
 
 <Step>
-### Denials are typed failures
+### See typed denials
 
-A denied request never reaches `do`. It returns one of three typed failures, like any entry in `errors: { … }`:
+A denied request never reaches `do`. It returns one of three typed failures:
 
 | Gate result                      | Typed failure                         |
 | -------------------------------- | ------------------------------------- |
@@ -72,32 +104,40 @@ A denied request never reaches `do`. It returns one of three typed failures, lik
 
 </Steps>
 
-## Two kinds of gates
+<GatePipeline />
 
-| Declaration                           | Question it answers                    | Evaluated against                  |
-| ------------------------------------- | -------------------------------------- | ---------------------------------- |
-| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)      | auth / operator / request metadata |
-| `gate.rate(options)`                  | Is there budget left for this subject? | an atomic counter on the kv driver |
+## `oke({ gate })` bag
 
-`gate.policy(name, check)` stays the terse form. Pass
-`{ check, description }` when you want a human title in the Console
-(falls back to the policy name).
+| Option          | Type                    | Default  | Meaning                                                         |
+| --------------- | ----------------------- | -------- | --------------------------------------------------------------- |
+| `policies`      | `GateDecl[]`            | `[]`     | Named policy / rate decls for the Gate runtime                  |
+| `auth`          | `GateAuthOptions`       | —        | Builtin hybrid sessions + `/auth/*` Flows (see below)           |
+| `rateLimit`     | `{ enabled?: boolean }` | see note | When auth is on, defaults `true` — stricter rates on auth paths |
+| `unguardedHttp` | `"deny"` \| `"allow"`   | `"deny"` | `"allow"` skips posture audit **only** when `env === "test"`    |
 
-### The policy context
+## Declarations
 
-The predicate receives everything it may decide with — nothing else:
+| Declaration                           | Question it answers                         | Evaluated against                  |
+| ------------------------------------- | ------------------------------------------- | ---------------------------------- |
+| `gate.policy(name, check \| options)` | Is this principal allowed? (ABAC)           | auth / operator / request metadata |
+| `gate.scope(name)`                    | Does `auth.scopes` contain this exact name? | `auth.scopes`                      |
+| `gate.public`                         | Intentionally unauthenticated surface       | always allows                      |
+| `gate.rate(options)`                  | Is there budget left for this subject?      | an atomic counter on the kv driver |
+
+Pass `{ check, description }` on `gate.policy` when you want a human title in the Console (falls
+back to the policy name). The name `"public"` is reserved — use `gate.public`, not
+`gate.policy("public", …)`.
+
+### Policy context
 
 | Field      | Contents                                                 |
 | ---------- | -------------------------------------------------------- |
 | `auth`     | User principal: `userId`, `scopes` (a `Set`), `verified` |
 | `operator` | Operator principal (Console plane): `id`                 |
-| `meta`     | Request metadata for keying decisions: `ip`, `userId`, … |
-
-```typescript
-export const admin = gate.policy("admin", ({ auth }) => auth.scopes.has("admin"));
-```
+| `meta`     | Request metadata for keying: `ip`, `userId`, …           |
 
-A policy name containing `:` is also a `Module:Action` permission — the same declaration feeds role-based access reviews in the Console.
+A policy name containing `:` is also a `Module:Action` permission for Console role reviews.
+Fine-grained authorization (`gate.scope`, roles) stays opt-in — attach it only where you need it.
 
 ### Rate options
 
@@ -107,7 +147,7 @@ A policy name containing `:` is also a `Module:Action` permission — the same d
 | `per`         | string       | — (**required**)           | Window / refill period (`"1m"`, `"60s"`, …)              |
 | `keyBy`       | string       | —                          | Subject dimension (`"ip"`, `"user"`, …)                  |
 | `strategy`    | RateStrategy | `"sliding-window-counter"` | Algorithm (below)                                        |
-| `overridable` | boolean      | `false`                    | Allow the Console to retune `max`/`per` live             |
+| `overridable` | boolean      | `false`                    | Catalog flag in Console (rate edit UI not shipped)       |
 | `description` | string       | —                          | Human title in the Console (falls back to the rate name) |
 
 | Strategy                 | Behavior                                               |
@@ -118,37 +158,139 @@ A policy name containing `:` is also a `Module:Action` permission — the same d
 | `token-bucket`           | Steady refill; permits saved-up bursts                 |
 | `leaky-bucket`           | Smooths output to a constant rate                      |
 
-All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory driver in tests.
+All five run as atomic Lua on the kv driver — correct under concurrency, identical on the memory
+driver in tests.
+
+## Auth posture at boot
+
+Every HTTP trigger must carry a gate or `gate.public`. Omitting both fails boot with
+`GateBootError` — message starts with `gate boot failed —` and lists every gap.
+
+```typescript
+on(http.get("/health").gate(gate.public), flow({/* … */}));
+on(http.post("/bookings").gate(member, canBook), flow({/* … */}));
+```
+
+**Consequence:** first `fetch` / `execute` auto-boots (`autoBoot` defaults to `true`).
+`oke({ autoBoot: false })` is a unit-test escape hatch only. A rate-only chain is declared
+posture but does **not** authenticate.
 
-## Identity comes from auth
+`gate: { unguardedHttp: "allow" }` skips the audit **only** when `env === "test"`.
+In `local` / `prod` / `docker` migrate with per-trigger `gate.public`.
 
-Gates don't log users in — they decide about principals that already exist. The built-in auth plugin (`okengine/auth`) provides the user plane: hybrid sessions, argon2id password hashing, roles, API keys, and invites, with zero-config defaults. Whatever it establishes lands on `fx.auth`, which is exactly what your policies read.
+## Built-in auth (`gate.auth`)
 
-## Every decision is recorded
+Enable hybrid sessions (Bearer access + revocable refresh). Auth HTTP surfaces are ordinary
+Bindings under `/auth` — same posture audit and pipeline as your app Flows:
 
-Pass **and** deny, every evaluation lands on the run's `gates` dimension in the telemetry trace. The Console (`:6533` → Gates) shows which gates fired on a request and their outcomes — an audit trail of permission decisions you never had to build. Rate gates declared `overridable: true` can also be retuned (`max`/`per`) from the Console without a redeploy; anything else rejects edits by design.
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { member, canBook } from "./gates";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: {
+    auth: {
+      emailAndPassword: { enabled: true },
+      session: { freshAgeMs: 24 * 60 * 60_000 },
+    },
+    policies: [member, canBook],
+  },
+});
+```
+
+| Surface                    | When                                   |
+| -------------------------- | -------------------------------------- |
+| `POST /auth/sign-up/email` | `emailAndPassword.enabled`             |
+| `POST /auth/sign-in/email` | `emailAndPassword.enabled`             |
+| `POST /auth/refresh`       | when `gate.auth` is set                |
+| `POST /auth/revoke`        | when `gate.auth` is set                |
+| `GET /auth/me`             | Bearer session (`auth.session` policy) |
+
+| Auth option                                 | Default   | Meaning                                                                        |
+| ------------------------------------------- | --------- | ------------------------------------------------------------------------------ |
+| `secret`                                    | minted\*  | HMAC for access tokens (\*`prod` requires you set it)                          |
+| `basePath`                                  | `"/auth"` | HTTP prefix for auth Flows                                                     |
+| `http`                                      | `true`    | `false` = secret/tables only (no `/auth/*` Bindings)                           |
+| `audience`                                  | `oke-app` | Audience stamped on access tokens                                              |
+| `emailAndPassword.enabled`                  | `false`   | Sign-up / sign-in email Flows                                                  |
+| `emailAndPassword.requireEmailVerification` | `false`   | Block sign-in until email is verified                                          |
+| `passwordPolicy`                            | secure\*  | `\*` minLength 12, letter + number; sign-up → `AuthFailed` / `password_policy` |
+| `breachCheck`                               | unset     | `(password) => Promise<boolean>` — `true` rejects as `password_breached`       |
+| `session.freshAgeMs`                        | 24h       | Window for step-up `auth.fresh` policy                                         |
+| `session.accessTtlMs` / `refreshTtlMs`      | 14m / 30d | Access / refresh lifetimes                                                     |
+| `session.idleTtlMs`                         | unset     | Opt-in: reject refresh when idle too long                                      |
+| `session.absoluteTtlMs`                     | unset     | Opt-in: hard cap from session creation                                         |
+| `session.singleSessionPerUser`              | `false`   | Opt-in: issuing a session revokes other families for that user                 |
+| `cookies.enabled`                           | `false`   | Opt-in HttpOnly cookie mirror (Bearer stays default)                           |
+| `secondaryStorage.enabled`                  | `false`   | Hot auth data in `store.kv` when configured                                    |
+| `user` / `session` / …                      | defaults  | `modelName` / `fields` / `additionalFields`                                    |
+
+HIBP via `createHibpBreachCheck` from `okengine/auth` (k-anonymity range API; requires
+`userAgent`; `onError` defaults to `"reject"` — fail closed while the check is enabled):
+
+```typescript
+import { createHibpBreachCheck } from "okengine/auth";
+
+gate: {
+  auth: {
+    emailAndPassword: { enabled: true },
+    breachCheck: createHibpBreachCheck({ userAgent: "shop/1.0" }),
+  },
+}
+```
+
+Customize tables, then run `oke schema generate` (supports `--check` in CI). Extra sign-in
+shapes: [Plugins](/docs/plugins) (username, magic link, OTP, TOTP, passkeys). Call auth from
+[createClient](/docs/reference/client) — one client, helpers in `okengine/client/auth`.
+
+## Identity and decisions
+
+Gates decide on principals that already exist. `gate.auth` issues hybrid sessions onto
+`fx.auth` (Console: `fx.operator`). Audit across `fx.call` uses read-only `fx.principal`
+(see [fx](/docs/reference/fx)).
+
+Pass **and** deny land on the run's `gates` dimension. Console (`:6533` → Gates) shows the
+chain. Rate `overridable` is a catalog flag only — Clock schedules are what the Console can
+edit live today.
 
 ## Troubleshooting
 
 <Accordions>
+<Accordion title="Boot: gate boot failed — N HTTP trigger(s) missing auth posture">
+
+Empty `.gate(...)` chain. Attach a policy/rate gate, or `.gate(gate.public)`. First `fetch`
+auto-boots — do not rely on `gate.unguardedHttp: "allow"` outside `env: "test"`.
+
+</Accordion>
 <Accordion title="Can a policy read the request body?">
 
-No — and that is deliberate. Gates run before the flow, so they see only the policy context (`auth`, `operator`, `meta`). Body-dependent decisions belong inside `do`, expressed as typed `errors`.
+No. Gates run before the flow, so they see only `auth`, `operator`, and `meta`. Body-dependent
+decisions belong inside `do` as typed `errors`.
 
 </Accordion>
 <Accordion title="Logged-in users still get Forbidden">
 
-`Forbidden` means the request _was_ authenticated but a policy said no. The failure includes the gate name and reason — check whether your predicate requires `verified` or a scope the user lacks.
+`Forbidden` means authenticated but a policy said no. Check `verified` or a missing scope —
+the failure includes the gate name and reason.
 
 </Accordion>
-<Accordion title="Which keyBy should I use?">
+<Accordion title="Prod boot: gate.auth: secret is required">
 
-`"ip"` for public unauthenticated surfaces (sign-up, password reset), `"user"` for authenticated quotas. Keying an authenticated endpoint by IP punishes users behind shared NAT; keying a public endpoint by user is impossible.
+Set `gate.auth.secret` (or provide it before boot). Non-prod may mint a development secret.
 
 </Accordion>
-<Accordion title="The Console won't retune my rate limit">
+<Accordion title="Sign-up returns AuthFailed password_policy">
 
-The gate was declared without `overridable: true`. Add it and redeploy — live retuning is opt-in per gate so a mistyped change cannot silently open a floodgate.
+Default policy requires length ≥ 12 plus a letter and a number. Short passwords like `"123"`
+are rejected — not accepted silently. Tighten or loosen via `gate.auth.passwordPolicy`.
+
+</Accordion>
+<Accordion title="Which keyBy should I use?">
+
+`"ip"` for public surfaces (sign-up, password reset), `"user"` for authenticated quotas.
+Keying an authenticated endpoint by IP punishes shared NAT.
 
 </Accordion>
 </Accordions>
@@ -156,18 +298,17 @@ The gate was declared without `overridable: true`. Add it and redeploy — live
 ## Learn more
 
 - [Flow](/docs/elements/flow) — the trigger pipeline gates plug into
-- [Console · Gates](/docs/console/gates) — decision audit and live retuning
-- [Vault](/docs/elements/vault) — the credentials your policies protect
+- [fx](/docs/reference/fx) — `fx.auth`, `fx.operator`, `fx.principal`
+- [Client](/docs/reference/client) — Bearer `createClient` + `okengine/client/auth`
+- [Plugins](/docs/plugins) — username, magic link, OTP, TOTP, passkeys
+- [Console · Gates](/docs/console/gates) — decision audit and posture
+- [Vault](/docs/elements/vault) — credentials your policies protect
 
 ## Next
 
 <Cards>
   <Card title="Vault" description="Continue to Vault." href="/docs/elements/vault" />
-  <Card
-    title="Introduction"
-    description="Eight elements overview."
-    href="/docs/get-started/introduction"
-  />
+  <Card title="Plugins" description="Sign-in method plugins under /auth." href="/docs/plugins" />
   <Card
     title="Console"
     description="Panels derived from the Manifest."

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

@@ -0,0 +1,45 @@
+---
+title: "Elements"
+description: "The eight irreducible parts of an OKE backend — Flow through AI, one page each."
+icon: "Boxes"
+source: "docs/spec/unified-theory.md"
+---
+
+Every backend concern collapses to one of these eight. Pick the element you need.
+
+## Pages
+
+<Cards>
+  <Card title="Flow" description="Behavior — on(Trigger) → Effects." href="/docs/elements/flow" />
+  <Card
+    title="Signal"
+    description="Data in motion — queues, pub/sub, streams."
+    href="/docs/elements/signal"
+  />
+  <Card
+    title="Store"
+    description="Data at rest — sql, kv, files, index."
+    href="/docs/elements/store"
+  />
+  <Card
+    title="Clock"
+    description="Time — schedules, intervals, durable sleeps."
+    href="/docs/elements/clock"
+  />
+  <Card
+    title="Gate"
+    description="Permission to act — auth and rate limits."
+    href="/docs/elements/gate"
+  />
+  <Card
+    title="Vault"
+    description="Protected knowledge — secrets and keys."
+    href="/docs/elements/vault"
+  />
+  <Card
+    title="Channel"
+    description="Reaching humans — email, SMS, push."
+    href="/docs/elements/channel"
+  />
+  <Card title="AI" description="Reaching machine intelligence." href="/docs/elements/ai" />
+</Cards>

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

@@ -1,5 +1,5 @@
 {
   "title": "Elements",
   "icon": "Boxes",
-  "pages": ["flow", "signal", "store", "clock", "gate", "vault", "channel", "ai"]
+  "pages": ["index", "flow", "signal", "store", "clock", "gate", "vault", "channel", "ai"]
 }

package/site/content/docs/elements/signal.mdx

@@ -76,11 +76,7 @@ That's the loop: declare → `fx.emit` → `on(signal, flow)`. The runtime handl
 
 ## The three delivery physics
 
-| `delivery`    | Semantics                                              | Use for                                                    |
-| ------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
-| `"once"`      | Queue: competing consumers, retries, dead-letter queue | Jobs that must happen exactly once — emails, payments sync |
-| `"broadcast"` | Pub/sub: **every** subscriber receives a copy          | Cache invalidation, cross-service events                   |
-| `"live"`      | Stream: client-subscribable and replayable             | Live feeds, dashboards, progress updates                   |
+<SignalDelivery />
 
 The declaration is identical in shape for all three — switching physics later is a one-word change, not a migration to another library.
 

package/site/content/docs/elements/store.mdx

@@ -90,12 +90,7 @@ export const createNote = on(
 
 Pick the facet that matches the physics of your data. Each declaration is one line; the runtime handle shows what flows can do with it.
 
-| Facet                      | Declares          | Best for                              | `fx.store(…)` handle                                   |
-| -------------------------- | ----------------- | ------------------------------------- | ------------------------------------------------------ |
-| `store.sql(name, opts)`    | a SQL database    | domain tables, relations, constraints | `select` · `insert` · `update` · `delete` · `findById` |
-| `store.kv(name, opts?)`    | a key-value space | cache, sessions, rate limits          | `get` · `set(key, value, ttl?)` · `delete` · `list`    |
-| `store.files(name, opts?)` | a blob bucket     | uploads, exports, attachments         | `put` · `get` · `delete` · `list(prefix?)`             |
-| `store.index(name, opts)`  | a vector index    | semantic search / RAG (`dims`)        | `upsert` · `search(vector, topK?)` · `delete`          |
+<StoreFacets />
 
 Every facet accepts optional `description` — a human title in the Console
 (falls back to the store name). `store.index` also takes `dims`.
@@ -282,6 +277,32 @@ drivers: {
 
 **Consequence:** a configured SQL-backed index that cannot reach its engine — missing peer, missing `vector` extension, wrong sql driver — fails loudly at first use. It never silently falls back to `memory`.
 
+### Full-text search — `meilisearch` (opt-in)
+
+`meilisearch` is a fourth `store.index` backend, opt-in only — `memory` stays the default. It is a genuinely different capability from the vector ANN drivers: typo-tolerant, faceted full-text relevance, not cosine similarity. The two models are kept apart by a **discriminated union** on `driverId`, so TypeScript rejects a vector query against a text index (and vice versa) at compile time — never at runtime:
+
+| `driverId`                       | `upsert`              | `search`                                 | `score` means               |
+| -------------------------------- | --------------------- | ---------------------------------------- | --------------------------- |
+| `memory` / `pgvector` / `libsql` | `(id, vector, meta?)` | `search(vector, topK?)` → `IndexHit[]`   | cosine similarity           |
+| `meilisearch`                    | `(id, document)`      | `search(q, opts?)` → `{ hits, facets? }` | relevance (`_rankingScore`) |
+
+```typescript title="oke.config.ts"
+drivers: {
+  store: {
+    index: { local: "meilisearch", docker: "meilisearch", prod: "meilisearch" },
+  },
+},
+images: {
+  "store.index": "getmeili/meilisearch:v1.37",
+},
+```
+
+- **Local mode** needs the `meilisearch` binary on `PATH` (a documented prerequisite, like Docker for `--docker` — OKE never auto-downloads binaries). `oke dev` spawns it with a generated master key persisted under `.oke/meilisearch/` (`0700`/`0600`).
+- **Docker / prod** uses the image recipe; the app gets `OKE_STORE_INDEX_URL` + `OKE_STORE_INDEX_KEY` from Compose — a standalone HTTP service, never the shared `sqlUrl`.
+- **Fail-loud:** a configured meilisearch that is unreachable or unhealthy throws `MeilisearchUnavailableError` — never a silent memory fallback.
+- **Not for vectors:** `ai.embed` / `fx.search` stay vector-only; pointing an embed `into` a meilisearch index fails loud (embeddings don't apply).
+- **Alpine caveat:** the raw glibc binary fails on Alpine/musl _hosts_; the official image is musl-clean. Install the binary for your platform (e.g. Homebrew / install script), or use `--docker`.
+
 ## Privacy built in
 
 Columns tagged `.pii()` or `.sensitive()` are masked at the store boundary — flows, logs, and the Console see a mask, not the value. Revealing cleartext PII requires an explicit `pii:reveal` gate on the flow, so access is a permission, not a convention.

package/site/content/docs/elements/vault.mdx

@@ -55,7 +55,9 @@ oke vault set STRIPE_KEY sk_test_your_key_here
 <Step>
 ### Read it in a Flow
 
-Flows read secrets through `fx.vault` — never through `process.env`:
+Flows read secrets through `fx.vault` — never through `process.env`. `fx.vault` returns a
+`Redacted<string>`: printing, logging, or serializing it yields a placeholder, never the value.
+Call `.reveal()` once at the boundary that needs the real credential:
 
 ```typescript title="src/flows/billing/charge.ts"
 export const charge = on(
@@ -64,14 +66,17 @@ export const charge = on(
     in: ChargeInput,
     out: z.object({ id: z.string() }),
     do: async (input, fx) => {
-      const key = fx.vault(stripeKey); // cleartext, inside this flow only
-      const intent = await stripe(key).create(input);
+      const key = fx.vault(stripeKey); // Redacted — safe to pass to fx.log
+      const intent = await stripe(key.reveal()).create(input);
       return { id: intent.id };
     },
   }),
 );
 ```
 
+`fx.log` masks any `Redacted` found in the logged data (nested included). A revealed string that
+still reaches `fx.log` is scrubbed by the boot redactor as before.
+
 </Step>
 
 </Steps>
@@ -111,13 +116,7 @@ export const dbUrl = vault.secret("DATABASE_URL", {
 
 At boot, each contract is resolved through this chain — **first hit wins**:
 
-| #   | Source               | Typical content                                   |
-| --- | -------------------- | ------------------------------------------------- |
-| 1   | `process.env`        | Real environment (CI, hosting platform)           |
-| 2   | `.env.local`         | Your machine's local overrides (gitignored)       |
-| 3   | `docker/.env.docker` | Generated compose stack credentials               |
-| 4   | vault driver         | OpenBao in docker/prod mode                       |
-| 5   | `dev` fallback       | The `dev:` option on the contract (never in prod) |
+<VaultResolution />
 
 If every layer misses a contract, boot **fails** before any request is served:
 
@@ -167,7 +166,7 @@ vault: {
 | `openbao` | OpenBao (KV v2) | Docker + prod — durable, access-controlled |
 | `memory`  | in-process map  | Tests                                      |
 
-Other drivers (`infisical`, `managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
+Other drivers (`managed`) implement the same `VaultDriver` interface — adding one is a driver exercise, not an architecture change.
 
 ## OpenBao in docker and prod