okengine 0.18.5 → 0.19.1

package/site/content/docs/reference/configuration.mdx

@@ -2,6 +2,7 @@
 title: "Configuration"
 description: "Every option in oke.config.ts — three environments (dev · test · prod), drivers, images, i18n, tenancy, privacy, db sync, topology, ports, and console."
 icon: "Settings2"
+source: "docs/spec/unified-theory.md"
 ---
 
 Complete reference for `oke.config.ts`. Options below match `defineConfig`. Driver maps use three keys: **dev** · **test** · **prod**.
@@ -14,9 +15,9 @@ export default defineConfig({
 });
 ```
 
-<Callout title="Philosophy">
-  We test on what we deploy. Local development runs the same stack as production via Docker. Tests
-  use PGLite for speed without sacrificing Postgres correctness.
+<Callout title="The one rule">
+  Pin drivers and images in `oke.config.ts` for `dev` · `test` · `prod`. We test on what we deploy:
+  Docker-first local stack, PGLite for tests, same protocol ids in production.
 </Callout>
 
 ## Environments
@@ -116,7 +117,7 @@ Built-in defaults (`DRIVER_DEFAULTS`) when a key is omitted:
 | `channel.sms`      | env driver map | `console` · `taqnyat` · `msegat` · `unifonic`                                    |
 | `channel.whatsapp` | env driver map | `console` · `wa-cloud`                                                           |
 | `channel.push`     | env driver map | `console` · `webpush` · `fcm`                                                    |
-| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex` · `ollama`     |
+| `ai`               | env driver map | `mock` · `anthropic` · `openai-compatible` · `bedrock` · `vertex`                |
 | `runs`             | env driver map | `memory` · `files` (Parquet + DuckDB at `.oke/runs`) · `postgres` · `clickhouse` |
 | `prod`             | `string[]`     | flat protocol list for the Manifest — nested maps are preferred                  |
 
@@ -150,11 +151,10 @@ images: {
   store: {
     sql: "postgres:18-alpine",
     kv: "redis:8-alpine",
-    files: "rustfs/rustfs:1.0.0-rc.2",
+    files: "rustfs/rustfs:1.0.0-rc.5",
   },
-  channel: { email: "axllent/mailpit:v1.30.7" },
-  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.53",
-  // ai: "ghcr.io/ggml-org/llama.cpp:server-b10450",
+  channel: { email: "axllent/mailpit:v1.31.1" },
+  pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
   // proxy: "caddy:2-alpine",
 },
 ```
@@ -163,7 +163,10 @@ Omitted image keys mean no container for that role. When both `store.sql` and `p
 
 For `store.kv`, pin Redis (default), Valkey, or Dragonfly — driver id stays `redis`.
 `{ durable: true }` KV lives in SQL (`oke_kv` on `DATABASE_URL`), not a second Redis image.
-For `ai`, see [Recipes · AI](/docs/recipes#ai-local--self-hosted). For `proxy`, see [Reverse proxy](/docs/deployment/reverse-proxy).
+
+Compose does not manage AI inference — [OpenRouter](/docs/recipes/openrouter) or BYO
+`OKE_AI_URL` ([Models](/docs/elements/ai/models)). For `proxy`, see [Caddy](/docs/recipes/caddy),
+[Traefik](/docs/recipes/traefik), or [nginx](/docs/recipes/nginx).
 
 ## i18n
 
@@ -267,6 +270,23 @@ Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated t
 
 ## Learn more
 
-- [CLI Reference](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
+- [CLI](/docs/reference/cli) — `oke dev` · `oke test` · `oke db`
 - [Environment Variables](/docs/reference/environment-variables) — URL and secret resolution
 - [Store](/docs/elements/store) — what the store drivers back
+- [i18n](/docs/reference/i18n) — locale catalogs beyond the config block
+
+## Next
+
+<Cards>
+  <Card
+    title="Environment Variables"
+    description="URLs and secrets Compose writes."
+    href="/docs/reference/environment-variables"
+  />
+  <Card title="CLI" description="Commands that honor this config." href="/docs/reference/cli" />
+  <Card
+    title="Security"
+    description="Host, Origin, planes, and MCP ports."
+    href="/docs/reference/security"
+  />
+</Cards>

package/site/content/docs/reference/environment-variables.mdx

@@ -1,12 +1,51 @@
 ---
 title: "Environment Variables"
-description: "Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags, grouped by what they configure."
-icon: "Terminal"
+description: "Every environment variable OKE reads — connection URLs, driver overrides, secrets, and CLI flags."
+icon: "Variable"
+source: "docs/spec/unified-theory.md"
 ---
 
-OKE reads environment variables at boot for connection detail and secrets — never for behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these into `.env.local`; this page is the full map.
+OKE reads environment variables at boot for connection detail and secrets — never for
+behavior you could declare in `oke.config.ts`. Under `oke dev`, Compose writes these
+into `.env.local`; this page is the full map.
 
-<Callout title="Precedence">
+<Callout title="The one rule">
+  Put drivers, images, and locale lists in `oke.config.ts`. Use env vars for URLs, credentials, and
+  runtime posture the host injects — not for inventing new behavior.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Let Compose write the map
+
+```bash
+oke dev
+```
+
+Compose fills `.env.local` with `DATABASE_URL`, Redis, S3, and vault keys for the
+pinned images.
+
+</Step>
+
+<Step>
+### Override one URL when needed
+
+```bash
+export DATABASE_URL=postgres://user:pass@db:5432/oke
+```
+
+Conventional names win over `OKE_*` aliases, then built-in defaults.
+
+</Step>
+
+</Steps>
+
+## Precedence
+
+<Callout title="Resolution order">
   For anything with both an `OKE_*` variable and a conventional one (like `DATABASE_URL`), the
   conventional variable wins first, then the `OKE_*` form, then the built-in default.
 </Callout>
@@ -101,10 +140,11 @@ Read when `drivers.channel.sms` resolves to that driver id (`console` opens noth
 WhatsApp (`wa-cloud`) and push (`webpush` / `fcm`) are not opened from env at
 boot — pass them on `BootOptions.channel.drivers` with their open options.
 
-## Live test gates (opt-in)
+## Live test gates (opt-in, contributors)
 
-Provider-quota-burning live suites are double-gated: the medium flag **plus** that
-provider's real credentials — credentials alone never send.
+Provider-quota-burning live suites in the okengine repo are double-gated: the
+medium flag **plus** that provider's real credentials — credentials alone never
+send. App projects can ignore these.
 
 | Variable         | Used for                                                  |
 | ---------------- | --------------------------------------------------------- |
@@ -113,18 +153,17 @@ provider's real credentials — credentials alone never send.
 
 ## AI providers
 
-| Variable              | Used for                                                                                                | Default when unset                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                                           | —                                                                          |
-| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                                 | —                                                                          |
-| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                                   | —                                                                          |
-| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                                            | OpenAI cloud                                                               |
-| `OKE_AI_DRIVER`       | Force the AI driver id (honoured under Compose / `oke dev`)                                             | config map                                                                 |
-| `OKE_AI_URL`          | Local / openai-compatible base URL                                                                      | `http://127.0.0.1:8080/v1` (llama.cpp) · `http://127.0.0.1:11434` (ollama) |
-| `OKE_AI_MODEL`        | Default model id — Docker Hub `ai/` for llama.cpp; Ollama library tag for ollama; HF id for vLLM/SGLang | `granite3.3:2b` (llama.cpp) / `qwen3.5:9b` (ollama)                        |
-| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                                | —                                                                          |
-| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                                            | —                                                                          |
-| `OLLAMA_HOST`         | Alternate Ollama host (`host:port` or URL) when `OKE_AI_URL` is unset                                   | —                                                                          |
+| Variable              | Used for                                                                                | Default when unset |
+| --------------------- | --------------------------------------------------------------------------------------- | ------------------ |
+| `ANTHROPIC_API_KEY`   | `anthropic` driver credential                                                           | —                  |
+| `ANTHROPIC_MODEL`     | Model override for the anthropic driver                                                 | —                  |
+| `OPENAI_API_KEY`      | `openai-compatible` driver credential                                                   | —                  |
+| `OPENAI_BASE_URL`     | `openai-compatible` base URL                                                            | OpenAI cloud       |
+| `OKE_AI_DRIVER`       | Force the AI driver id (honoured under Compose / `oke dev`)                             | config map         |
+| `OKE_AI_URL`          | openai-compatible base URL (must end in `/v1`) — BYO; Compose does not manage inference | —                  |
+| `OKE_AI_MODEL`        | Default model id for openai-compatible / setup bindings                                 | —                  |
+| `OKE_AI_VISION_MODEL` | Vision model id written by `oke ai setup` (logical `ai.model("vision")`)                | —                  |
+| `OKE_AI_EMBED_MODEL`  | Embedding model id written by `oke ai setup`                                            | —                  |
 
 ## Framework behavior
 
@@ -145,8 +184,42 @@ Console operator rows are **not** stored in `.oke/console.sqlite`. With `DATABAS
 `OKE_STORE_SQL_URL`) they live in Postgres schema `oke_console`. Without a Postgres URL,
 Console uses PGlite under `.oke/console-pg` for local reopen durability.
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Compose did not write .env.local">
+  Run `oke dev` (not a bare `bun` entry) so Compose posture sets `OKE_DOCKER=1` and writes
+  connection URLs. Confirm `images` pins exist in [Configuration](/docs/reference/configuration).
+</Accordion>
+
+<Accordion title="Vault sealed / missing master key">
+  Built-in vault needs `OKE_VAULT_MASTER_KEY` (or `oke vault unseal`). See
+  [Vault](/docs/elements/vault).
+</Accordion>
+
+<Accordion title="Console operator store missing">
+  Operator rows need `DATABASE_URL` or `OKE_STORE_SQL_URL` (schema `oke_console`). Without Postgres,
+  Console uses PGlite under `.oke/console-pg`.
+</Accordion>
+
+</Accordions>
+
 ## Learn more
 
 - [Configuration](/docs/reference/configuration) — the declarative side of the same knobs
 - [Vault](/docs/elements/vault) — how `OKE_VAULT_*` gets minted on first boot
-- [CLI Reference](/docs/reference/cli) — which commands write these for you
+- [CLI](/docs/reference/cli) — which commands write these for you
+- [Security](/docs/reference/security) — `OKE_CONSOLE_SECRET`
+
+## Next
+
+<Cards>
+  <Card
+    title="Configuration"
+    description="Drivers and images in oke.config.ts."
+    href="/docs/reference/configuration"
+  />
+  <Card title="CLI" description="oke dev writes the env map." href="/docs/reference/cli" />
+  <Card title="Vault" description="Master key and managed providers." href="/docs/elements/vault" />
+</Cards>

package/site/content/docs/reference/errors.mdx

@@ -1,18 +1,66 @@
 ---
 title: "Errors"
-description: "Every error OKE produces — permanent OKE codes with fixes, gate denials, and subsystem errors, with what to do about each."
+description: "OKE codes, gate denials, and subsystem errors — stable numeric codes with causes and fixes."
 icon: "OctagonAlert"
+source: "docs/spec/unified-theory.md"
 ---
 
-OKE has two error families, and confusing them is the most common mistake: **failures are values** a flow returns (`{ data: null, error: { code, data } }` — clients switch on `error.code`), while **framework errors are thrown** for invariant violations and carry a permanent numeric code, a cause, and a fix.
+OKE has two error families: **failures are values** a Flow returns
+(`{ data: null, error: { code, data } }`), while **framework errors are thrown**
+for invariant violations (permanent numeric code + cause + fix).
 
 ```text
-OKE1101  domain table not found — migrations have not been applied.
+OKE1110  domain table not found — migrations have not been applied.
          → run `oke db migrate` against this environment.
-         https://oke.omqkhafi.dev/e/1101
+         https://oke.omqkhafi.dev/e/1110
 ```
 
-Codes are permanent once published — you can match on them safely across upgrades.
+Codes are stable after the domain-range renumber — match them safely across upgrades
+(see the Unreleased Breaking Changes mapping if you still have a pre-renumber note).
+
+<Callout title="The one rule">
+  Switch on `error.code` for Flow failures. Catch / match `OKE####` only for thrown framework
+  invariants. Do not treat a typed `NotFound` as an unhandled exception.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Return a typed failure
+
+```typescript
+on(
+  http.get({
+    in: z.object({ id: z.string() }),
+    errors: { NotFound: z.object({ id: z.string() }) },
+  }),
+  flow({
+    do: async ({ id }, fx) => {
+      const [row] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
+      if (!row) return fx.fail("NotFound", { id });
+      return row;
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Handle it on the client
+
+```typescript
+const { data, error } = await api.notes.get({ id });
+if (error?.code === "NotFound") {
+  // value — not a throw
+}
+```
+
+</Step>
+
+</Steps>
 
 ## Localized messages
 
@@ -25,34 +73,42 @@ from `Accept-Language` (matched to `i18n.locales`); fallback is `i18n.default`.
 | Thrown `OkeError`  | `oke.{code}.cause` · `oke.{code}.fix`      | Cause + fix lines in the thrown message  |
 
 Override via `defineLocale`. Pass `fail(code, data, { message })` for a custom
-string. Custom app codes stay message-less until registered.
+string. Custom app codes stay message-less until registered. Full catalogs:
+[i18n](/docs/reference/i18n).
 
 ## OKE numeric codes
 
-| Code   | Name                 | Cause                                             | Fix                                                  |
-| ------ | -------------------- | ------------------------------------------------- | ---------------------------------------------------- |
-| `1001` | undeclared read      | Flow reads a resource not in `effects.reads`      | Add it to the flow's `effects.reads`                 |
-| `1002` | undeclared write     | Flow writes a resource not in `effects.writes`    | Add it to the flow's `effects.writes`                |
-| `1003` | undeclared emit      | Flow emits a signal not in `effects.emits`        | Add it to the flow's `effects.emits`                 |
-| `1004` | undeclared send      | Flow sends a template not in `effects.sends`      | Add it to the flow's `effects.sends`                 |
-| `1005` | undeclared ask       | Flow asks a prompt not in `effects.asks`          | Add it to the flow's `effects.asks`                  |
-| `1006` | undeclared secret    | Flow reads a secret not in `effects.secrets`      | Add it to the flow's `effects.secrets`               |
-| `1007` | undeclared call      | Flow calls a flow not in `effects.calls`          | Add it to the flow's `effects.calls`                 |
-| `1011` | HTTP route clash     | Two HTTP flows share the same method + path       | Give each flow a unique method + path                |
-| `1012` | HTTP flow unnamed    | Adopted HTTP flow still has no `unit.export`      | Export from `flows/<unit>/` or pass a named `flow`   |
-| `1013` | live exposure dup    | Same signal, gates, and match on two GET routes   | Change the gate or path-param filter                 |
-| `1014` | live resume gap      | `Last-Event-ID` is not on the retained tape       | Reconnect without the cursor; remaining tape replays |
-| `1015` | tenant required      | Tenant-scoped op with no `fx.tenant.id`           | `switchTenant`, signed `tid`, or tenant header       |
-| `1016` | tenant not member    | Client-supplied tenant id is not a membership     | Pick from `listTenants` or add the user as a member  |
-| `1017` | tenant unknown scope | Tenant role used an invented or `console:*` scope | Use a declared application scope                     |
-| `1042` | orphan emit          | Emit with zero subscribers and `optional` false   | Add `on(signal, …)` or declare `optional: true`      |
-| `1043` | signal schema        | Emit payload failed the signal's `schema`         | Pass a payload that matches `schema`, or remove it   |
-| `1101` | schema missing       | Domain table absent in `prod` — no auto-DDL       | Run `oke db migrate` against this environment        |
+| Code   | Name                 | Cause                                                  | Fix                                                       |
+| ------ | -------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
+| `1001` | undeclared read      | Flow reads a resource not in `effects.reads`           | Add it to the flow's `effects.reads`                      |
+| `1002` | undeclared write     | Flow writes a resource not in `effects.writes`         | Add it to the flow's `effects.writes`                     |
+| `1003` | undeclared emit      | Flow emits a signal not in `effects.emits`             | Add it to the flow's `effects.emits`                      |
+| `1004` | undeclared send      | Flow sends a template not in `effects.sends`           | Add it to the flow's `effects.sends`                      |
+| `1005` | undeclared ask       | Flow asks a prompt not in `effects.asks`               | Add it to the flow's `effects.asks`                       |
+| `1006` | undeclared secret    | Flow reads a secret not in `effects.secrets`           | Add it to the flow's `effects.secrets`                    |
+| `1007` | undeclared call      | Flow calls a flow not in `effects.calls`               | Add it to the flow's `effects.calls`                      |
+| `1008` | undeclared fetch     | Flow fetches a host not in `effects.fetches`           | Add the hostname to the flow's `effects.fetches`          |
+| `1009` | undeclared embed     | Flow embeds with a model not in `effects.embeds`       | Add it to the flow's `effects.embeds`                     |
+| `1020` | no effects declared  | Flow has no `effects` and no Manifest to infer from    | Run `oke build` / `oke dev`, or declare effects           |
+| `1030` | adopt barrel stale   | A `src/flows/<unit>` folder was not adopted            | Run `oke dev` or `oke build` to regenerate `generated.ts` |
+| `1040` | HTTP path unresolved | Pathless `http.get()` never received a file-tree stamp | Import `@/flows/generated`, or pass `http.get("/…")`      |
+| `1041` | HTTP route clash     | Two HTTP flows share the same method + path            | Give each flow a unique method + path                     |
+| `1045` | HTTP flow unnamed    | Adopted HTTP flow still has no `unit.export`           | Export from `flows/<unit>/` or pass a named `flow`        |
+| `1050` | live exposure dup    | Same signal, gates, and match on two GET routes        | Change the gate or path-param filter                      |
+| `1060` | MCP tool duplicate   | Two MCP tool bindings share the same tool name         | Give each MCP tool exposure a unique name                 |
+| `1110` | schema missing       | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment             |
+| `1210` | live resume gap      | `Last-Event-ID` is not on the retained tape            | Reconnect without the cursor; remaining tape replays      |
+| `1240` | orphan emit          | Emit with zero subscribers and `optional` false        | Add `on(signal, …)` or declare `optional: true`           |
+| `1250` | signal schema        | Emit payload failed the signal's `schema`              | Pass a payload that matches `schema`, or remove it        |
+| `1605` | channel schema       | Send payload failed the template's `schema`            | Fix template `data` payload or the template `schema`      |
+| `1810` | tenant required      | Tenant-scoped op with no `fx.tenant.id`                | `switchTenant`, signed `tid`, or tenant header            |
+| `1820` | tenant not member    | Client-supplied tenant id is not a membership          | Pick from `listTenants` or add the user as a member       |
+| `1830` | tenant unknown scope | Tenant role used an invented or `console:*` scope      | Use a declared application scope                          |
 
 <Callout title="Effects are usually inferred">
-  The 1001–1007 family exists for flows that declare effects explicitly. Most apps never write an
-  `effects` block — inference covers them — so seeing one of these means an explicit declaration
-  drifted from the code.
+  The 1001–1007 · 1008 · 1009 family exists for flows that declare effects explicitly. Most apps
+  never write an `effects` block — inference covers them — so seeing one of these means an explicit
+  declaration drifted from the code.
 </Callout>
 
 ## Gate denials (typed failures)
@@ -98,9 +154,56 @@ Thrown by specific subsystems — each names its own cause:
 | `AccessGrantError`            | Console access grant rejected                                      | Re-request access with a valid grant                                  |
 | `UnsupportedPathError`        | A route path shape the router can't compile                        | Simplify the path pattern                                             |
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="I hit OKE1001–1009">
+  Explicit `effects` drifted from `do`. Add the missing ledger entry or remove the hand-written
+  `effects` block so inference covers the Flow.
+</Accordion>
+
+<Accordion title="OKE1040 pathless HTTP never stamped">
+  Import `@/flows/generated`, or pass an explicit path: `http.get("/users/:id")`.
+</Accordion>
+
+<Accordion title="OKE1041 method + path bound twice">
+  A resource mount and a handwritten route share the same method + path. Drop one binding.
+</Accordion>
+
+<Accordion title="OKE1110 in production">
+  Domain tables missing — prod has no auto-DDL. Run `oke db migrate` against that environment
+  ([CLI](/docs/reference/cli)).
+</Accordion>
+
+<Accordion title="Unauthorized / Forbidden / RateLimited">
+  These are gate denials returned as values before `do` runs — not thrown OKE codes. Fix the policy,
+  membership, or rate budget. See [Gate](/docs/elements/gate).
+</Accordion>
+
+<Accordion title="VaultBootError at startup">
+  A vault contract has no value in any resolution layer. The error lists every gap — set the missing
+  names ([Vault](/docs/elements/vault)).
+</Accordion>
+
+</Accordions>
+
 ## Learn more
 
 - [i18n](/docs/reference/i18n) — catalogs, `fx.t`, locale matching
 - [Flow](/docs/elements/flow) — `fx.fail` and the response envelope
 - [Gate](/docs/elements/gate) — where the three denials come from
-- [CLI Reference](/docs/reference/cli) — `oke db migrate` and friends
+- [CLI](/docs/reference/cli) — `oke db migrate` and friends
+- [fx](/docs/reference/fx) — how failures and effects surface
+
+## Next
+
+<Cards>
+  <Card title="fx" description="The door that records effects." href="/docs/reference/fx" />
+  <Card
+    title="Gate"
+    description="Where Unauthorized and Forbidden come from."
+    href="/docs/elements/gate"
+  />
+  <Card title="Client" description="Switch on error.code in the browser." href="/docs/client" />
+</Cards>