okengine 0.20.0 → 0.21.1

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

@@ -344,12 +344,11 @@ export const get = on(
   http.get({
     in: z.object({ id: z.string() }),
     out: z.object({ id: z.string(), title: z.string() }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id }, fx) => {
       const [note] = await fx.store(db).select().from(notes).where(eq(notes.id, id));
-      if (!note) return fx.fail("NotFound", { id });
+      if (!note) return fx.fail.notFound({ id });
       return note;
     },
   }),
@@ -404,7 +403,6 @@ export const update = on(
       id: z.string(),
       title: z.string().min(1).optional(),
     }),
-    errors: { NotFound: z.object({ id: z.string() }) },
   }),
   flow({
     do: async ({ id, title }, fx) => {
@@ -412,7 +410,7 @@ export const update = on(
         await fx.store(db).update(notes).set({ title }).where(eq(notes.id, id));
       }
       const row = await fx.store(db).findById(notes, id);
-      if (!row) return fx.fail("NotFound", { id });
+      if (!row) return fx.fail.notFound({ id });
       return row;
     },
   }),
@@ -591,7 +589,7 @@ The URL id segment is always `:id`. Update is **PATCH**, not PUT.
 | `out`      | Schema    | _(required)_                     | Item shape (get / list / update return)                                  |
 | `update`   | Schema    | `in`                             | Patch fields. Wire body is `{ id, …patch }`                              |
 | `idSchema` | Schema    | `update`/`in` + `{ id: string }` | Replaces the update Flow `in` when set (include the id key)              |
-| `errors`   | error map | `{ NotFound }`                   | Typed failures on get / update / remove                                  |
+| `errors`   | error map | —                                | Extra domain codes. Built-in `NotFound` is always on                     |
 | `id`       | column    | table PK                         | Column bound to `:id`                                                    |
 | `list`     | object    | see List Options                 | List query grammar (`GET /notes`)                                        |
 | `breaking` | `boolean` | `false`                          | Marks the five Flows `breaking: true` (handwritten → resource migration) |
@@ -917,6 +915,11 @@ export default defineConfig({
   `oke db migrate` in that environment.
 </Accordion>
 
+<Accordion title="Unique insert is 500 InternalError">
+  Unique / exclusion maps to `Conflict` **409**; missing FK to `ForeignKey` **409**. See [Errors ·
+  SQL auto-map](/docs/reference/errors#sql-auto-map).
+</Accordion>
+
 <Accordion title="update().set().where(): condition required">
   Updates and deletes without a `where` are rejected (`delete().where(): condition required`). Pass
   a Drizzle condition or equality map — or use `delete(table, id)` for PK deletes.
@@ -976,7 +979,7 @@ export default defineConfig({
 - [HTTP · Resources](/docs/elements/flow/http#resources) — mount, live SSE, verb table
 - [Consumers · CDC](/docs/elements/flow/consumers#cdc) — `db.table(…).changed()`
 - [fx](/docs/reference/fx) — `fx.store` session
-- [Errors](/docs/reference/errors) — OKE1110 · OKE1041
+- [Errors](/docs/reference/errors) — OKE1110 · OKE1041 · SQL auto-map
 
 ## Next
 

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

@@ -196,13 +196,16 @@ Order (Console labels match these source ids):
 3. **`.env.local`** — local overrides (gitignored)
 4. **dev-fallback** — `dev:` on the contract (dev boot only)
 
-Miss every layer → `VaultBootError` listing **all** gaps in one pass (including
-`vault.env.required` names):
+Miss every layer → `VaultBootError` (TTY title **OKE1510**) listing **all** gaps in one pass
+(including `vault.env.required` names):
 
 ```text
-vault boot failed — 2 missing secret(s):
-  - STRIPE_KEY: Payments gateway key
-  - DATABASE_URL: Primary SQL URL
+◇  OKE1510
+│  2 secrets have no value in any resolution layer.
+│  - STRIPE_KEY
+│  - DATABASE_URL
+│  → Set each name (`oke vault set <name>`, or `.env.local`).
+│  https://oke.omqkhafi.dev/e/1510
 ```
 
 **Consequence:** fix every listed name before traffic — boot does not take a half-configured app.
@@ -297,9 +300,9 @@ Managed provider ids: `aws-secrets-manager` · `azure-key-vault` · `gcp-secret-
 <Accordions>
 
 <Accordion title="VaultBootError — N missing secret(s)">
-  Cause: `vault boot failed — N missing secret(s):` with every gap listed. On a TTY, `oke dev`
-  prompts each into `.env.local`; otherwise use `oke vault set` / env / managed, or a `dev:`
-  fallback. `vault.env.required` joins the same list.
+  TTY title **OKE1510**. Cause: N secrets have no value in any resolution layer, with every gap
+  listed. On a TTY, `oke dev` prompts each into `.env.local`; otherwise use `oke vault set` / env /
+  managed, or a `dev:` fallback. `vault.env.required` joins the same list.
 </Accordion>
 
 <Accordion title='vault: secret "…" is not loaded'>

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

@@ -209,9 +209,12 @@ capability check.
 Missing non-tenant contracts fail boot with every hole listed once:
 
 ```text
-vault boot failed — 2 missing secret(s):
-  - STRIPE_KEY: Stripe secret API key
-  - APP_WEBHOOK_SECRET: HMAC secret for outbound webhooks
+◇  OKE1510
+│  2 secrets have no value in any resolution layer.
+│  - STRIPE_KEY
+│  - APP_WEBHOOK_SECRET
+│  → Set each name (`oke vault set <name>`, or `.env.local`).
+│  https://oke.omqkhafi.dev/e/1510
 ```
 
 Fill gaps with:

package/site/content/docs/index.mdx

@@ -29,7 +29,7 @@ Master the mental model before exploring features:
   />
   <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"
   />
 </Cards>

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

@@ -27,7 +27,7 @@ drivers: {
   },
 },
 images: {
-  store: { files: "rustfs/rustfs:1.0.0-rc.5" },
+  store: { files: "rustfs/rustfs:1.0.0" },
 },
 ```
 

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",

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
@@ -100,6 +246,7 @@ string. Custom app codes stay message-less until registered. Full catalogs:
 | `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              |
@@ -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` |
@@ -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
 

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