okengine 0.19.9 → 0.21.0

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

@@ -24,8 +24,8 @@ writes.
 ### Scaffold an app
 
 ```bash
-bunx create-oke@latest notes --yes
-cd notes
+bunx create-oke@latest my-app --yes
+cd my-app
 ```
 
 </Step>
@@ -98,7 +98,7 @@ oke start               # production entry (Docker CMD)
 
 ```bash
 bunx create-oke@latest my-app --yes
-bunx create-oke@latest my-app -t advanced --locales ar --proxy caddy
+bunx create-oke@latest my-app -t shorter --locales ar --proxy caddy
 bunx create-oke@latest          # interactive (TTY only)
 ```
 
@@ -164,7 +164,7 @@ oke db search-backfill notes --batch 500
 
 | Flag                             | Meaning                                                   |
 | -------------------------------- | --------------------------------------------------------- |
-| `-t, --template <id>`            | `standard` (default) or `advanced`                        |
+| `-t, --template <id>`            | `blank` (default) · `shorter`                             |
 | `--sql <id>`                     | Store SQL dialect — only `postgres` (test stays `pglite`) |
 | `-y, --yes`                      | No prompts; defaults + bun install (no `oke dev`)         |
 | `--install` / `--no-install`     | Run or skip `bun install` after scaffold                  |
@@ -175,6 +175,9 @@ oke db search-backfill notes --batch 500
 | `--proxy <id>` / `--no-proxy`    | `none` · `caddy` · `traefik` · `nginx`                    |
 | `-h, --help`                     | Show help                                                 |
 
+`blank` is an empty app (`main.health` + Store/Vault). `shorter` is a URL shortener
+(`POST /links`, public `GET /:code`).
+
 ## Troubleshooting
 
 <Accordions>

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

@@ -151,7 +151,7 @@ images: {
   store: {
     sql: "postgres:18-alpine",
     kv: "redis:8-alpine",
-    files: "rustfs/rustfs:1.0.0-rc.5",
+    files: "rustfs/rustfs:1.0.0",
   },
   channel: { email: "axllent/mailpit:v1.31.1" },
   pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
@@ -212,13 +212,13 @@ Runs retention and redaction — **not** the same key as `drivers.runs`.
 
 Domain schema sync for `oke db push | generate | migrate` (Drizzle). Unrelated to `oke schema generate`.
 
-| Option      | Default                      | Meaning                                                                   |
-| ----------- | ---------------------------- | ------------------------------------------------------------------------- |
-| `autoPush`  | `true`                       | Auto-run `db push` on schema change under `oke dev`; forced off in `prod` |
-| `config`    | `"drizzle.config.ts"`        | Path to the drizzle-kit config                                            |
-| `declare`   | `"src/db/schema.decl.ts"`    | Abstract schema module (`store.schema.table` exports)                     |
-| `generated` | `"src/db/schema.drizzle.ts"` | Where `oke db` emits dialect Drizzle                                      |
-| `entry`     | `src/app.ts`                 | App entry for collecting plugin table contributions                       |
+| Option      | Default               | Meaning                                                                          |
+| ----------- | --------------------- | -------------------------------------------------------------------------------- |
+| `autoPush`  | `true`                | Auto-run `db push` on schema change under `oke dev`; forced off in `prod`        |
+| `config`    | `"drizzle.config.ts"` | Path to the drizzle-kit config                                                   |
+| `declare`   | auto                  | `schema.ts` (file) if present, else `schema/index.ts` (folder). Set to override. |
+| `generated` | auto                  | `src/db/drizzle/index.ts`. Set to override.                                      |
+| `entry`     | `src/app.ts`          | App entry for collecting plugin table contributions                              |
 
 ## topology
 

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

@@ -1,6 +1,6 @@
 ---
 title: "Errors"
-description: "OKE codes, gate denials, and subsystem errors — stable numeric codes with causes and fixes."
+description: "fx.fail helpers, built-in HTTP statuses, OKE codes, and subsystem errors — values vs thrown invariants."
 icon: "OctagonAlert"
 source: "docs/spec/unified-theory.md"
 ---
@@ -19,8 +19,8 @@ Codes are stable after the domain-range renumber — match them safely across up
 (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.
+  Switch on `error.code` (or a `match` named arm) for typed `data`. Use kind arms / `explain` for
+  chrome when the code is unknown. Catch `OKE####` only for thrown framework invariants.
 </Callout>
 
 ## Smallest Example
@@ -34,12 +34,11 @@ Codes are stable after the domain-range renumber — match them safely across up
 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 });
+      if (!row) return fx.fail.notFound({ id });
       return row;
     },
   }),
@@ -52,16 +51,163 @@ on(
 ### Handle it on the client
 
 ```typescript
-const { data, error } = await api.notes.get({ id });
-if (error?.code === "NotFound") {
-  // value — not a throw
-}
+import { match } from "okengine/client/explain";
+
+const result = await api.notes.get({ id });
+match(result, {
+  ok: (note) => render(note),
+  NotFound: () => showMissing(),
+  _: (e) => toast(e.message),
+});
 ```
 
 </Step>
 
 </Steps>
 
+## `fx.fail`
+
+Same function as `import { fail } from "okengine"`. Returns `{ data: null, error }` — it does **not**
+throw. Built-in codes need no `errors:` bag. Domain codes (`OutOfStock`, `FlightFull`, `Duplicate`)
+still go on the exposure:
+
+```typescript
+on(
+  http.post({
+    in: z.object({ sku: z.string() }),
+    errors: { OutOfStock: z.object({ available: z.number() }) },
+  }),
+  flow({
+    do: async ({ sku }, fx) => {
+      const available = 0;
+      if (available === 0) return fx.fail("OutOfStock", { available });
+      return { sku };
+    },
+  }),
+);
+```
+
+Optional `{ message }` overrides the catalog: `fx.fail("OutOfStock", data, { message })`.
+
+### Helpers
+
+| Call                                | Code                 | Status           | Payload                                                   |
+| ----------------------------------- | -------------------- | ---------------- | --------------------------------------------------------- |
+| `fx.fail.notFound(data?)`           | `NotFound`           | **404**          | `id?`, `key?`, …                                          |
+| `fx.fail.unauthorized(data?)`       | `Unauthorized`       | **401**          | `reason?`                                                 |
+| `fx.fail.forbidden(data?)`          | `Forbidden`          | **403**          | `gate?`, `reason?`                                        |
+| `fx.fail.conflict(data?)`           | `Conflict`           | **409**          | `constraint?`, `table?`, `column?`, `id?`                 |
+| `fx.fail.foreignKey(data?)`         | `ForeignKey`         | **409**          | `constraint?`, `table?`, `column?`                        |
+| `fx.fail.rateLimited(data?)`        | `RateLimited`        | **429**          | `retryAfterMs?`                                           |
+| `fx.fail.serviceUnavailable(data?)` | `ServiceUnavailable` | **503**          | `retryAfter?`                                             |
+| `fx.fail.database(data)`            | `DatabaseError`      | by `data.reason` | `reason`, `sqlstate?`, `constraint?`, `table?`, `column?` |
+| `fx.fail.internal(data?)`           | `InternalError`      | **500**          | `{}` — catalog message only                               |
+
+`DatabaseError` status: `not_null` / `check` / `invalid` / `too_long` / `out_of_range` → **422**,
+`retryable` → **503**, `unknown` / missing → **500**.
+
+Declare a built-in on `errors:` **only to tighten** the payload. Shorter keeps
+`NotFound: z.object({ code: z.string() })` because `{ code }` is not the built-in `{ id? }`.
+Declared schema wins on the Manifest and the typed client.
+
+The typed client always includes built-in codes. A declared key still wins.
+
+### HTTP status
+
+A bare `404` with body `Not Found` means **no route matched**. `fx.fail.notFound` is a JSON envelope
+at **404**. Clients distinguish by envelope, not status. Domain codes stay **400**.
+
+| Code                                             | Status      | Helper                                                 |
+| ------------------------------------------------ | ----------- | ------------------------------------------------------ |
+| `ValidationError`                                | `422`       | none — failed `in`, `do` never runs                    |
+| `Unauthorized`                                   | `401`       | `unauthorized` · also a gate denial                    |
+| `Forbidden`                                      | `403`       | `forbidden` · also a gate denial                       |
+| `NotFound`                                       | `404`       | `notFound`                                             |
+| `Conflict` / `ForeignKey`                        | `409`       | `conflict` / `foreignKey`                              |
+| `UnsupportedMediaType`                           | `415`       | none — QUERY `Content-Type` is not `application/json`  |
+| `RateLimited` / `AuthRateLimited`                | `429`       | `rateLimited` · `AuthRateLimited` has none             |
+| `InvalidQuery`                                   | `400`       | none — QUERY missing `Content-Type` or body isn't JSON |
+| `AuthFailed`                                     | `400`       | none — credentials / policy, not “no session”          |
+| `DatabaseError`                                  | by `reason` | `database`                                             |
+| `ServiceUnavailable`                             | `503`       | `serviceUnavailable`                                   |
+| `InternalError`                                  | `500`       | `internal` — never copies a thrown `message`           |
+| Domain (`OutOfStock`, `FlightFull`, `Duplicate`) | `400`       | `fx.fail("OutOfStock", data)`                          |
+
+### Client chrome
+
+`import { match, matchError, explain } from "okengine/client/explain"`. Do not switch on every
+code — a `create` can return store auto-map, gates, transport, and domain codes.
+
+| `kind`        | Codes                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------- |
+| `auth`        | `Unauthorized`, `AuthFailed`                                                           |
+| `permission`  | `Forbidden`                                                                            |
+| `missing`     | `NotFound`; `TransportError` with HTTP 404                                             |
+| `conflict`    | `Conflict`, `ForeignKey`                                                               |
+| `invalid`     | `ValidationError`, `InvalidQuery`, `UnsupportedMediaType`; `DatabaseError` 422 reasons |
+| `limited`     | `RateLimited`, `AuthRateLimited`                                                       |
+| `unavailable` | `ServiceUnavailable`; `DatabaseError` `retryable`; other `TransportError`              |
+| `failed`      | `InternalError`, unknown `DatabaseError`, domain codes                                 |
+
+```typescript
+match(result, {
+  ok: (data) => show(data),
+  FlightFull: (data) => offerWaitlist(data.seatsLeft),
+  auth: () => goSignIn(),
+  invalid: (e) => setForm(e.fields),
+  _: (e) => toast(e.message),
+});
+```
+
+Dispatch: `ok` → named code → kind → required `_`. `explain(error).fields` maps
+`ValidationError` issues to `{ email: "Required" }`. Full loop: [Calling](/docs/client/calling).
+
+`TransportError` always sets both `error.message` and `error.data.message` to the same string.
+Prefer `error.message` in UI code.
+
+### Store auto-map
+
+`fx.store` constraint and connection failures become typed `fail` values (same family as
+`ValidationError`). Public `data` is names only — never `message` / `detail` / `hint`.
+`get` returning `null` is **not** auto-`NotFound` — return `fx.fail.notFound` yourself.
+
+#### SQL auto-map
+
+| Signal                                                                | Result                                                                            |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Postgres `23505` / `23P01` · SQLite UNIQUE / PRIMARY KEY              | `Conflict` **409**                                                                |
+| Postgres `23503` / `23001` · SQLite FOREIGN KEY                       | `ForeignKey` **409**                                                              |
+| Postgres `23502` / `23514` · SQLite NOT NULL / CHECK                  | `DatabaseError` `not_null` / `check` **422**                                      |
+| Postgres `22P02` / `22007` / `22023` / `42804`                        | `DatabaseError` `invalid` **422**                                                 |
+| Postgres `22001`                                                      | `DatabaseError` `too_long` **422**                                                |
+| Postgres `22003` / `22008`                                            | `DatabaseError` `out_of_range` **422**                                            |
+| Postgres `40001` / `40P01` / `55P03` · SQLite BUSY                    | left thrown so `flow.retry` can run; after exhaust → `ServiceUnavailable` **503** |
+| `08xxx` / `53xxx` / `57P0x` / `57014` / `25P03` / connection / paused | `ServiceUnavailable` **503**                                                      |
+| `42P01` / `42703` with `domainDdl: "off"`                             | **OKE1110** (unchanged)                                                           |
+| other SQLSTATE                                                        | `DatabaseError` `unknown` **500**                                                 |
+
+#### KV auto-map
+
+Redis-wire `store.kv` only (not Gate / Signal clients). Memory KV does not throw these.
+
+| Signal                                                      | Result                                                                            |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| Connection / `CLUSTERDOWN` / `READONLY` / `OOM` / `MISCONF` | `ServiceUnavailable` **503**                                                      |
+| `BUSY` / `TRYAGAIN` / `LOADING`                             | left thrown so `flow.retry` can run; after exhaust → `ServiceUnavailable` **503** |
+| `WRONGTYPE` / `NOSCRIPT`                                    | unmapped — `InternalError` **500**                                                |
+
+#### Files auto-map
+
+`fs` and `s3` (`fx.store` files handle). Missing objects stay `null`.
+
+| Signal                                             | Result                                                                            |
+| -------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AccessDenied` / `EACCES` / `EPERM` / HTTP **403** | `Forbidden` **403**                                                               |
+| `fs` key starts with `/` or contains `..`          | `Forbidden` **403** (`reason: invalid_key`)                                       |
+| `NoSuchBucket` / `ENOSPC` / connection             | `ServiceUnavailable` **503**                                                      |
+| `SlowDown` / `EBUSY` / HTTP **429**                | left thrown so `flow.retry` can run; after exhaust → `ServiceUnavailable` **503** |
+| `NoSuchKey` (thrown)                               | unmapped — `InternalError` **500**                                                |
+
 ## Localized messages
 
 Typed failures and OKE codes ship English and Arabic ICU catalogs. Locale comes
@@ -78,35 +224,36 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 
 ## 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`                      |
-| `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                 |
-| `1070` | flow name duplicate    | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export  |
-| `1071` | once-signal multi-flow | Two different Flows bound to the same `signal.once`    | Use `signal.broadcast`, or bind only one Flow             |
-| `1072` | flow unnamed           | Signal / Clock consumer still has no `unit.export`     | Export from `flows/<unit>/` or pass a named `flow`        |
-| `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                          |
+| 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 `src/flows/index.ts` |
+| `1040` | HTTP path unresolved   | Pathless `http.get()` never received a file-tree stamp | Import `@/flows`, 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                       |
+| `1070` | flow name duplicate    | Two Flows share the same Manifest / `fx.call` name     | Give at least one an explicit `flow("…")` or tree export        |
+| `1071` | once-signal multi-flow | Two different Flows bound to the same `signal.once`    | Use `signal.broadcast`, or bind only one Flow                   |
+| `1072` | flow unnamed           | Signal / Clock consumer still has no `unit.export`     | Export from `flows/<unit>/` or pass a named `flow`              |
+| `1110` | schema missing         | Domain table absent in `prod` — no auto-DDL            | Run `oke db migrate` against this environment                   |
+| `1510` | vault secret missing   | Contract has no value in any resolution layer          | `oke vault set <name>`, `.env.local`, or a `dev:` fallback      |
+| `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 · 1008 · 1009 family exists for flows that declare effects explicitly. Most apps
@@ -116,7 +263,8 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 
 ## Gate denials (typed failures)
 
-Returned, not thrown — the request never reached `do`:
+Returned before `do` — not thrown. Same codes as `fx.fail.unauthorized` / `.forbidden` /
+`.rateLimited`:
 
 | Code           | When                                         | Payload                                                                                    |
 | -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
@@ -124,22 +272,13 @@ Returned, not thrown — the request never reached `do`:
 | `Forbidden`    | Policy denied, authenticated but not allowed | `gate`, `reason` (`tenant_required` · `not_member` · `unknown_scope` · `session_only` · …) |
 | `RateLimited`  | Rate gate budget exhausted                   | `retryAfterMs`                                                                             |
 
-## Framework validation failures
-
-| Code                   | When                                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `ValidationError`      | Input failed the `in` schema, or a list param isn't whitelisted (`unknown list param "x"`)                          |
-| `NotFound`             | A `store.resource` get/update/remove hit a missing row                                                              |
-| `InvalidQuery`         | QUERY missing `Content-Type` (`reason: missing_content_type`) or body isn't JSON (`inconsistent_content`) — **400** |
-| `UnsupportedMediaType` | QUERY `Content-Type` is present but not `application/json` — **415**, `Accept-Query` lists JSON                     |
-
 ## Subsystem errors
 
 Thrown by specific subsystems — each names its own cause:
 
 | Error                         | Thrown when                                                        | What to do                                                            |
 | ----------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
-| `VaultBootError`              | A vault contract has no value in any resolution layer              | Set the missing names — the error lists every gap                     |
+| `VaultBootError`              | A vault contract has no value in any resolution layer              | TTY **OKE1510** — set each listed name                                |
 | `VaultError` (`UNSUPPORTED`)  | Managed provider unknown                                           | Use an official id, built-in `vault`, or `env`                        |
 | `VaultSealed`                 | Console rotate-master while this process holds no master key       | Export `OKE_VAULT_MASTER_KEY` or run `oke vault unseal`               |
 | `VaultRotateBusy`             | Master-rotation lease held or a batch is already in flight         | Wait and continue, or resume with `oke vault rotate-master --new-key` |
@@ -167,7 +306,7 @@ Thrown by specific subsystems — each names its own cause:
 </Accordion>
 
 <Accordion title="OKE1040 pathless HTTP never stamped">
-  Import `@/flows/generated`, or pass an explicit path: `http.get("/users/:id")`.
+  Import `@/flows`, or pass an explicit path: `http.get("/users/:id")`.
 </Accordion>
 
 <Accordion title="OKE1041 method + path bound twice">
@@ -196,20 +335,55 @@ Thrown by specific subsystems — each names its own cause:
   membership, or rate budget. See [Gate](/docs/elements/gate).
 </Accordion>
 
+<Accordion title="Do I need errors: { NotFound }?">
+  No. Built-in codes are always on — `return fx.fail.notFound({ id })`. Put `errors:` only for
+  domain codes, or to tighten a built-in payload (`{ code }` instead of `{ id? }`).
+</Accordion>
+
+<Accordion title="Unique insert is 500 InternalError">
+  Unique / exclusion → `Conflict` **409**; missing FK → `ForeignKey` **409**; invalid →
+  `DatabaseError` **422**. Serialization (`40001` / `40P01`) stays thrown until retries exhaust,
+  then **503**. See [SQL auto-map](#sql-auto-map).
+</Accordion>
+
+<Accordion title="Redis down returns InternalError">
+  Connection / `CLUSTERDOWN` / `READONLY` map to `ServiceUnavailable` **503**. `BUSY` / `TRYAGAIN`
+  stay thrown until `flow.retry` exhausts, then **503**. `WRONGTYPE` stays `InternalError` — see [KV
+  auto-map](#kv-auto-map).
+</Accordion>
+
+<Accordion title="S3 AccessDenied / disk full is InternalError">
+  `AccessDenied` and `fs` path-escape keys → `Forbidden` **403**. `SlowDown` / `EBUSY` stay thrown
+  until retries exhaust, then **503**. `ENOSPC` / `NoSuchBucket` → **503**. Missing `get` is still
+  `null`, not `NotFound` — see [Files auto-map](#files-auto-map).
+</Accordion>
+
+<Accordion title="404 Not Found — route missing or domain miss?">
+  Bare body `Not Found` means no HTTP route. JSON `{ error: { code: "NotFound" } }` is
+  `fx.fail.notFound`. Clients distinguish by envelope.
+</Accordion>
+
+<Accordion title="InternalError leaked a stack / thrown message">
+  Unhandled throws use the catalog string only. The thrown `message` is not copied onto the
+  envelope. Expected misses belong in `fx.fail.notFound` or a domain `fx.fail("OutOfStock", data)`.
+</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)).
+  TTY title **OKE1510**. A vault contract has no value in any resolution layer. The printer lists
+  every gap — set the missing names ([Vault](/docs/elements/vault)).
 </Accordion>
 
 </Accordions>
 
 ## Learn more
 
+- [fx](/docs/reference/fx) — `fx.fail` helpers on the door
 - [i18n](/docs/reference/i18n) — catalogs, `fx.t`, locale matching
-- [Flow](/docs/elements/flow) — `fx.fail` and the response envelope
+- [Flow](/docs/elements/flow) — envelope and domain `errors:`
+- [HTTP](/docs/elements/flow/http) — response envelopes
+- [Calling](/docs/client/calling) — `match` / `explain` on the client
 - [Gate](/docs/elements/gate) — where the three denials come from
 - [CLI](/docs/reference/cli) — `oke db migrate` and friends
-- [fx](/docs/reference/fx) — how failures and effects surface
 
 ## Next
 
@@ -220,5 +394,5 @@ Thrown by specific subsystems — each names its own cause:
     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" />
+  <Card title="Client" description="match unknown errors in the browser." href="/docs/client" />
 </Cards>

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

@@ -141,7 +141,10 @@ on(
 | `fx.retry(fn, opts?)`                                                          | —                       | Exponential backoff + jitter (plain Promise)                                                       |
 | `fx.using(acq, rel, use)`                                                      | —                       | `release` runs once on settle or ambient abort                                                     |
 | `fx.signal`                                                                    | —                       | Ambient `AbortSignal` for the current branch                                                       |
-| `fx.fail(code, data, opts?)`                                                   | —                       | Typed failure value (`opts.message` overrides)                                                     |
+| `fx.fail(code, data, opts?)`                                                   | —                       | Domain failure value (`opts.message` overrides)                                                    |
+| `fx.fail.notFound(data?)`                                                      | —                       | Built-in `NotFound` — HTTP 404. No `errors:` bag required                                          |
+| `fx.fail.forbidden(data?)` / `.unauthorized` / `.conflict` / `.foreignKey`     | —                       | Built-in 403 / 401 / 409                                                                           |
+| `fx.fail.rateLimited` / `.serviceUnavailable` / `.database` / `.internal`      | —                       | Built-in 429 / 503 / DatabaseError / 500                                                           |
 | `fx.auth.createApiKey({ name, scopes, expiresIn?, ipAllowlist?, rateLimit? })` | `write` `auth:api-keys` | Secret once. Creator is live `userId` / `scopes`. Session only. `ipAllowlist` is IPs or hostnames. |
 | `fx.auth.listApiKeys()`                                                        | `read` `auth:api-keys`  | Keys this session minted                                                                           |
 | `fx.auth.revokeApiKey(id)`                                                     | `write` `auth:api-keys` | Owner only                                                                                         |
@@ -155,6 +158,8 @@ on(
 `fx.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization) and
 propagates `fx.tenant.id`. For audit/attribution only, read `fx.principal` — it propagates the
 originating identity without copying into `fx.auth`. Gates never consult `fx.principal`.
+Controlled `return fx.fail(...)` returns a `FlowFailure` value; an unhandled `throw` rethrows
+(never silent `undefined`). The same rules apply to `app.call`.
 
 ## Concurrency and retry
 
@@ -211,7 +216,8 @@ const rows = await fx.using(
 | `fx.send(template, { to?, data?, via?, … })` | `send`  | `via` orders fallback; `locale` / `profileLocale` / `acceptLanguage` feed the locale chain |
 
 Omit locale opts and the send uses `fx.locale`. Dry runs record _would have fired_ and never
-contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Channel](/docs/elements/channel)).
+contact a provider. Bodies live on `.template({ catalog })` (`{{field}}`, not ICU — see
+[Channel](/docs/elements/channel)).
 
 ## Outbound HTTP
 
@@ -255,13 +261,13 @@ host tooltip).
 
 ## Clock
 
-| Signature                         | Notes                                                               |
-| --------------------------------- | ------------------------------------------------------------------- |
-| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"                         |
-| `fx.clock.ago(duration)`          | Instant before now (`"30d"` → now − 30 days)                        |
-| `fx.clock.fromNow(duration)`      | Instant after now (`"14d"` → now + 14 days)                         |
-| `fx.clock.duration(duration)`     | Span in ms — offset a stored instant (`createdAt + duration("7d")`) |
-| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise               |
+| Signature                         | Notes                                                                                                                         |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `fx.clock.now()`                  | Epoch-ms, injectable — the only legal "now"; pass into SQL timestamps as-is (store coerces numbers and ISO strings to `Date`) |
+| `fx.clock.ago(duration)`          | Instant before now (`"30d"` → now − 30 days)                                                                                  |
+| `fx.clock.fromNow(duration)`      | Instant after now (`"14d"` → now + 14 days)                                                                                   |
+| `fx.clock.duration(duration)`     | Span in ms — offset a stored instant (`createdAt + duration("7d")`)                                                           |
+| `fx.clock.sleep(label, duration)` | Durable sleep in `durable` flows; immediate otherwise                                                                         |
 
 Durations: `"200ms"` · `"30s"` · `"2m"` · `"1h"` · `"7d"`. A `"d"` is 86_400_000 ms, not a calendar day. Unknown strings parse as `0`.
 
@@ -293,6 +299,8 @@ keys. Use `cache: false` to opt out, or `cache: "30s"` for a TTL.
 
 Returning a plain value instead answers 200 with `{ data: value, error: null }` — the helpers exist for status and `meta` control. Pass `fx.stream(...)` into `fx.json.stream` to reach the HTTP client token-by-token.
 
+When `out` is set, success values are projected onto it (`fx.json.create(row)`, `return row`, `fx.json.withQuery(rows, input)`). Date timestamps and temporal epoch-ms (`*At` / `*_at` / `at`) become ISO-8601 and extra keys strip. A parse miss is not a client error.
+
 ## Logging, i18n, ids
 
 | Signature                                  | Notes                                                       |
@@ -355,6 +363,11 @@ to the key — see [Gate](/docs/elements/gate#api-keys).
   Type the parameter as `Fx` from `okengine`, not a hand-rolled structural type.
 </Accordion>
 
+<Accordion title="I mapped Date columns to ISO by hand">
+  Declared `out` projects success values. `fx.json.create(row)`, `return row`, and
+  `fx.json.withQuery(rows, input)` are enough — extra columns strip. A miss is not a client error.
+</Accordion>
+
 </Accordions>
 
 ## Learn more

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

@@ -257,8 +257,8 @@ until registered. Full tables: [Errors](/docs/reference/errors).
 
 ## Channel catalogs are separate
 
-`fx.send` templates use `{{field}}` bodies and their own `locales` list — not
-ICU. Omit `locale` / `profileLocale` / `acceptLanguage` on `fx.send` and the
+`fx.send` interpolates `{{field}}` from `.template({ catalog })` — not ICU, not
+`fx.t`. Omit `locale` / `profileLocale` / `acceptLanguage` on `fx.send` and the
 send uses `fx.locale`. Details: [Channel](/docs/elements/channel).
 
 ## Troubleshooting
@@ -280,8 +280,8 @@ the app (proxies sometimes strip it).
 </Accordion>
 <Accordion title="Email body is still English while fx.t is Arabic">
 
-Channel catalogs are separate `{{field}}` strings. Add an `ar` body on the
-template / plugin catalog; `fx.t` does not translate Channel templates.
+Channel catalogs are separate `{{field}}` strings. Add an `ar` key on
+`.template({ catalog })`; `fx.t` does not translate Channel templates.
 
 </Accordion>
 <Accordion title="TypeScript rejects a key that exists at runtime">

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

@@ -54,7 +54,7 @@ export const app = oke({ name: "shop", env: "dev" }).plug(audit);
 <Step>
 ### Everything derives as usual
 
-Plugin flows appear in the Manifest, plugin tables land in `schema.drizzle.ts` on the next `oke db push`, plugin panels show up in the Console. No extra wiring — a contribution is ordinary OKE, just authored elsewhere.
+Plugin flows appear in the Manifest, plugin tables land in `src/db/drizzle/` on the next `oke db push`, plugin panels show up in the Console. No extra wiring — a contribution is ordinary OKE, just authored elsewhere.
 
 </Step>
 
@@ -76,8 +76,8 @@ Every method below exists on both the fluent definition and the boot-time builde
 | `.clock(decl)`                   | A named clock schedule — merged into boot clocks                                              |
 | `.signal(decl)`                  | A signal declaration — merged into boot signals                                               |
 | `.gate(decl)`                    | A gate declaration — merged into boot gates                                                   |
-| `.channelTemplate(decl)`         | A channel template — merged into boot channel templates                                       |
-| `.channelCatalog(catalog)`       | Template body catalog entries — merged into boot channel catalog (`{{field}}` interpolation)  |
+| `.channelTemplate(decl)`         | `channel.<medium>().template(…)` — `catalog` on the decl drains into boot                     |
+| `.channelCatalog(catalog)`       | Overlay bodies after `.template({ catalog })` (`{{field}}`); later locale wins                |
 | `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
 | `.image(role, recipe)`           | An image recipe for a docker role                                                             |
 | `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
@@ -226,7 +226,7 @@ Extending an existing **app-owned** table with plugin columns is not supported i
     two configurations of one plugin would silently diverge. Pass identical config, or rename one
     instance.
   </Accordion>
-  <Accordion title="My plugin table is missing from schema.drizzle.ts">
+  <Accordion title="My plugin table is missing from drizzle/">
     The CLI reads table contributions from the live app entry. Make sure the plugin is actually
     `.plug()`ed in `src/app.ts` (or `db.entry` if overridden), then re-run `oke db push`.
   </Accordion>

package/site/content/docs/understand/the-architecture.mdx

@@ -248,12 +248,12 @@ The Elements section walks through each element in depth — this is just enough
 
 ## Where this goes next
 
-You now hold the whole model: the drift, the rule, the eight elements, the five-piece anatomy. Don't read more — run it. From an empty folder to this exact signup Flow answering a real request, in one sitting:
+You now hold the whole model: the drift, the rule, the eight elements, the five-piece anatomy. Don't read more — run it. From an empty folder to `GET` and `POST /users` answering a real request:
 
 <Cards>
   <Card
     title="Try It"
-    description="From an empty folder to a Flow running in the Console — one sitting, minimal detour."
+    description="Scaffold, see the files, add GET and POST /users, save a row — then email if you want."
     href="/docs/understand/try-it"
   />
   <Card