okengine 0.18.5 → 0.19.0

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>

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

@@ -1,38 +1,89 @@
 ---
 title: "fx"
-description: "The complete fx surface — every call a flow can make, its signature, and the effect it records."
+description: "The complete fx surface — every call a Flow can make, its signature, and the effect it records."
 icon: "Braces"
+source: "docs/spec/unified-theory.md"
 ---
 
-`fx` is the second argument of every `do` — the single door to the world. This page is the whole surface; each entry notes the **effect it records**, which is what feeds the Manifest, caching, and capability checks.
+`fx` is the second argument of every `do` — the single door to the world. This page is the
+whole surface; each entry notes the **effect it records**, which feeds the Manifest, caching,
+and capability checks.
+
+<Callout title="The one rule">
+  All world access goes through `fx`. No `node:` I/O, no raw `fetch` for side effects (use
+  `fx.fetch` instead), no `Date.now()` — clocks, stores, channels, vault, AI, and outbound HTTP only
+  through this object.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Use `fx` inside `do`
+
+```typescript title="src/flows/notes/create.ts"
+import { on, flow, http } from "okengine";
+import { z } from "zod";
+import { db, notes } from "@/schema";
+
+export const create = on(
+  http.post(),
+  flow({
+    in: z.object({ title: z.string().min(1) }),
+    do: async ({ title }, fx) => {
+      const id = fx.id();
+      await fx.store(db).insert(notes).values({ id, title });
+      return fx.json.create({ id, title });
+    },
+  }),
+);
+```
+
+</Step>
+
+<Step>
+### Type extracted helpers as `Fx`
 
 ```typescript
-flow("orders.example", {
-  do: async (input, fx) => {
-    // everything below, on this one object
-  },
-});
+import type { Fx } from "okengine";
+
+async function loadNote(id: string, fx: Fx) {
+  return fx.store(db).findById(notes, id);
+}
 ```
 
-<Callout title="Extracted helpers">
-  Type a helper's `fx` parameter as `Fx` (`import type {Fx} from "okengine"`). A narrower structural
-  type will not match `store()` overloads. See [Flow](/docs/elements/flow).
-</Callout>
+A narrower structural type will not match `store()` overloads. See [Flow](/docs/elements/flow).
+
+</Step>
+
+</Steps>
+
+## What the effects ledger powers
+
+| Derived behavior       | From                                   |
+| ---------------------- | -------------------------------------- |
+| Cache invalidation     | Inferred / ledgered `reads` · `writes` |
+| Live queries / CDC     | Store `writes` observed as row events  |
+| Least-privilege tokens | Effect matrices on Flows               |
+| Deterministic tests    | Injectable clock · store · channel     |
+| Runs observability     | Wide events per invocation (`fx.runs`) |
 
 ## Stores
 
-| Signature                                                           | Records      | Returns                                                                                     |
-| ------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
-| `fx.store(sqlDecl).select().from(t)…`                               | `read`       | inferred rows (`where` · `orderBy` · `limit` · `offset` chainable)                          |
-| `fx.store(sqlDecl).insert(t).values(v)`                             | `write`      | `Promise<void>`                                                                             |
-| `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`      | `Promise<void>`                                                                             |
-| `fx.store(sqlDecl).delete(t).where(…)`                              | `write`      | `Promise<void>`                                                                             |
-| `fx.store(sqlDecl).findById(t, id)`                                 | `read`       | row \| undefined                                                                            |
-| `fx.store(kv).get / set(key, value, ttl?) / delete / list(prefix?)` | read / write | per op                                                                                      |
-| `fx.store(files).put / get / delete / list(prefix?)`                | read / write | per op                                                                                      |
-| `fx.store(files).image(key\|bytes).…`                               | read / write | Bun.Image chain; terminals gate (see [Store](/docs/elements/store#images--image--putimage)) |
-| `fx.store(files).putImage(key, data, opts?)`                        | `write`      | original + variants (+ optional LQIP)                                                       |
-| `fx.store(index).upsert / search(vector, topK?) / delete`           | read / write | per op                                                                                      |
+| Signature                                                           | Records                    | Returns                                                                                     |
+| ------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- |
+| `fx.store(sqlDecl).select().from(t)…`                               | `read`                     | inferred rows (`where` · `orderBy` · `limit` · `offset` chainable)                          |
+| `fx.store(sqlDecl).insert(t).values(v)`                             | `write`                    | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).update(t).set(v).where(…)`                       | `write`                    | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).delete(t).where(…)`                              | `write`                    | `Promise<void>`                                                                             |
+| `fx.store(sqlDecl).findById(t, id)`                                 | `read`                     | row \| undefined                                                                            |
+| `fx.store(sqlDecl).search(table, { query, fuse?, rerank?, … })`     | `read` (+ `ask` if rerank) | `{ data, meta }` hybrid BM25 ± LSH — see [Search](/docs/elements/store/search)              |
+| `fx.store(kv).get / set(key, value, ttl?) / delete / list(prefix?)` | read / write               | per op                                                                                      |
+| `fx.store(files).put / get / delete / list(prefix?)`                | read / write               | per op                                                                                      |
+| `fx.store(files).image(key\|bytes).…`                               | read / write               | Bun.Image chain; terminals gate (see [Store](/docs/elements/store#images--image--putimage)) |
+| `fx.store(files).putImage(key, data, opts?)`                        | `write`                    | original + variants (+ optional LQIP)                                                       |
+| `fx.store(index).upsert / search(vector, topK?) / delete`           | read / write               | per op                                                                                      |
 
 See [Store](/docs/elements/store) for the query-builder surface.
 
@@ -40,7 +91,7 @@ See [Store](/docs/elements/store) for the query-builder surface.
 
 | Signature                             | Records                | Notes                                                                                                                                                                                                     |
 | ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1042** (orphan) or **OKE1043** (schema) |
+| `fx.emit(signal, payload?, { key? })` | `emit`                 | Commits the signal outbox when the call resolves; optional `key` serializes `once` per key; stamps producer run id as `parentRunId` for trace chains; throws **OKE1240** (orphan) or **OKE1250** (schema) |
 | `fx.deadLetters(signal)`              | `read` `signal:<name>` | Dead-lettered messages for that signal. Payload typed from `SignalDecl<T>`. Page with `fx.json.withQuery`. Cross-signal throws **OKE1001**.                                                               |
 | `fx.live(signal, { match? })`         | `read` `signal:<name>` | Live tape as SSE. Returns `JsonStreamResult` (object chunks, `id:` on the wire). Cross-signal throws **OKE1001**. Do not wrap with `fx.json.stream`.                                                      |
 
@@ -56,8 +107,10 @@ Declare `effects: { reads: ["runs"] }`. Powers native SLO checkers (Clock + Chan
 | `fx.runs.checkSlo(flow, slo, windowMs?)` | `read` `runs` | Availability / latency breaches                                                          |
 
 ```typescript
+const sloCheckClock = clock("ops.slo-check", { every: "5m" });
+
 on(
-  every("5m"),
+  sloCheckClock,
   flow("ops.slo-check", {
     effects: { reads: ["runs"], sends: ["slo-alert"] },
     do: async (_, fx) => {
@@ -159,6 +212,18 @@ const rows = await fx.using(
 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)).
 
+## Outbound HTTP
+
+| Signature              | Records                     | Notes                                                                     |
+| ---------------------- | --------------------------- | ------------------------------------------------------------------------- |
+| `fx.fetch(url, init?)` | `fetch` on the URL hostname | Always stamps `EffectEntry.external` with `{ host, kind: "third-party" }` |
+
+Declare hosts in `effects.fetches` (e.g. `["api.stripe.com"]`). Prefer `fx.step`; use
+`fx.retry` only when the remote API is safe to repeat. Dry runs never hit the network.
+
+Use this for third-party REST outside Channel / AI / Store — not as a substitute for those
+elements.
+
 ## AI
 
 | Signature                                             | Records                   | Returns                                                                                                  |
@@ -170,6 +235,10 @@ contact a provider. Channel bodies use `{{field}}` catalogs — not ICU (see [Ch
 
 AI calls are nondeterministic: journaling is forced on and auto-cache disabled around them. `tools` are Flow refs — each model tool call goes through `fx.call` (same capability and Runs path).
 
+Driver-reported `EffectEntry.external` marks cloud providers as `third-party` and
+self-hosted / `provider: "local"` as `infrastructure` (Console waterfall dashed egress +
+host tooltip).
+
 ## Vault
 
 | Signature                          | Records  | Returns / notes                                                                                    |
@@ -232,54 +301,9 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 | `fx.locale`                                | Active locale (`Accept-Language` matched to `i18n.locales`) |
 | `fx.id()`                                  | OKID — 21-char native id from `okengine/okid`               |
 
-See [OKID](/docs/reference/okid) for generation options and the entropy model.
-
-`fx.t` uses [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/)
-(FormatJS): `{name}`, plurals, `select` / `selectordinal`, rich-text tags.
-Full syntax and escaping: [i18n · ICU](/docs/reference/i18n#icu-messageformat).
-
-Register catalogs with `defineLocale` before boot (nested trees → dot keys). Augment
-`Register` so keys autocomplete and typos fail at compile time:
-
-```typescript
-import { defineLocale, defineMessages, type MessagesFor } from "okengine/i18n";
-
-export const en = defineMessages({
-  greeting: "Hello, {name}",
-  items: "{count, plural, one {# item} other {# items}}",
-  place: "You finished {place, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}!",
-  status: "{status, select, online {Online} offline {Offline} other {Unknown}}",
-  cta: "Read <docs>the docs</docs>",
-});
-defineLocale("en", en);
-
-defineLocale("ar", {
-  greeting: "مرحباً، {name}",
-  items: "{count, plural, zero {لا عناصر} one {عنصر واحد} other {# عناصر}}",
-  place: "أنهيت في المرتبة {place, selectordinal, other {#}}!",
-  status: "{status, select, online {متصل} offline {غير متصل} other {غير معروف}}",
-  cta: "اقرأ <docs>التوثيق</docs>",
-} satisfies MessagesFor<typeof en>);
-
-declare module "okengine" {
-  interface Register {
-    messages: typeof en;
-  }
-}
-```
-
-```typescript
-fx.t("greeting", { name: input.name });
-fx.t("items", { count: 3 });
-fx.t("cta", { docs: (chunks) => `<a href="/docs">${chunks.join("")}</a>` });
-```
-
-Supported locales and the fallback come from `oke.config.ts` `i18n`.
-`create-oke` scaffolds English and Arabic locale modules already wired this way.
-
-Built-in `errors.*` / `oke.*` catalogs localize `fx.fail` messages and thrown
-`OkeError` cause/fix the same way — full i18n guide:
-[i18n](/docs/reference/i18n), [Errors](/docs/reference/errors).
+Catalogs, ICU syntax, and `Register` augmentation live on [i18n](/docs/reference/i18n).
+Id options: [OKID](/docs/reference/okid). Localized `fx.fail` / `OkeError` catalogs:
+[Errors](/docs/reference/errors).
 
 ## Principals
 
@@ -302,9 +326,49 @@ to the key — see [Gate](/docs/elements/gate#api-keys).
   export for existing Grafana/Datadog stacks is additive and never required.
 </Callout>
 
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="OKE1001–1007 / 1008 / 1009 undeclared effect">
+  An explicit `effects` block drifted from what `do` touches. Add the missing ledger entry (`reads`
+  · `writes` · `emits` · `sends` · `asks` · `embeds` · `secrets` · `calls` · `fetches`), or drop the
+  block so inference covers the Flow ([Errors](/docs/reference/errors)).
+</Accordion>
+
+<Accordion title="OKE1240 orphan emit">
+  `fx.emit` with zero subscribers and `optional: false`. Add `on(signal, …)` or declare the signal
+  `optional: true`.
+</Accordion>
+
+<Accordion title="OKE1250 signal schema">
+  Emit payload failed the signal's `schema`. Pass a matching payload or remove the schema.
+</Accordion>
+
+<Accordion title="Cross-signal fx.live / fx.deadLetters">
+  Reading another signal's tape throws **OKE1001**. Declare
+  `effects.reads: ["signal:<name>"]` for that name.
+</Accordion>
+
+<Accordion title="Helper fx type errors on store()">
+  Type the parameter as `Fx` from `okengine`, not a hand-rolled structural type.
+</Accordion>
+
+</Accordions>
+
 ## Learn more
 
 - [Flow](/docs/elements/flow) — why `fx` is the only door
 - [Channel](/docs/elements/channel) — `fx.send`, consent, locale chain, `{{field}}` catalogs
+- [i18n](/docs/reference/i18n) — `fx.t`, catalogs, locale matching
 - [Errors](/docs/reference/errors) — what `fx.fail` produces
 - [Configuration](/docs/reference/configuration) — drivers and the `i18n` block
+- [OKID](/docs/reference/okid) — `fx.id()` options
+
+## Next
+
+<Cards>
+  <Card title="Flow" description="Triggers, effects, and durability." href="/docs/elements/flow" />
+  <Card title="Errors" description="OKE codes and failure values." href="/docs/reference/errors" />
+  <Card title="Client" description="Call Flows with the same envelope." href="/docs/client" />
+</Cards>

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

@@ -1,6 +1,6 @@
 ---
 title: "Reference"
-description: "Lookup pages — config, fx, i18n, client, env vars, errors, plugins API, CLI, and Console security."
+description: "Lookup pages — CLI, config, fx, errors, security, and plugins."
 icon: "BookMarked"
 source: "docs/spec/unified-theory.md"
 ---
@@ -10,41 +10,33 @@ Dense tables and command lists. Reach for these when you already know what you a
 ## Pages
 
 <Cards>
+  <Card title="CLI" description="oke and create-oke commands." href="/docs/reference/cli" />
   <Card
     title="Configuration"
     description="Every option in oke.config.ts."
     href="/docs/reference/configuration"
   />
-  <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
-  <Card
-    title="i18n"
-    description="ICU catalogs, fx.t, typed keys, locale matching."
-    href="/docs/reference/i18n"
-  />
-  <Card
-    title="Client"
-    description="Typed createClient — REST, RPC, envelope helpers."
-    href="/docs/reference/client"
-  />
   <Card
     title="Environment Variables"
     description="Every variable OKE reads."
     href="/docs/reference/environment-variables"
   />
+  <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
   <Card title="Errors" description="OKE codes, denials, fixes." href="/docs/reference/errors" />
   <Card
-    title="Plugins"
-    description="Plugin API — hooks, schemas, identity."
-    href="/docs/reference/plugins"
+    title="Security"
+    description="Host, Origin, planes, MCP posture."
+    href="/docs/reference/security"
   />
   <Card
-    title="CLI Reference"
-    description="oke and create-oke commands."
-    href="/docs/reference/cli"
+    title="i18n"
+    description="ICU catalogs, fx.t, typed keys, locale matching."
+    href="/docs/reference/i18n"
   />
   <Card
-    title="Security"
-    description="Console Host, Origin, MCP posture."
-    href="/docs/reference/security"
+    title="Plugins"
+    description="Plugin API — hooks, schemas, identity."
+    href="/docs/reference/plugins"
   />
+  <Card title="OKID" description="Native id generator." href="/docs/reference/okid" />
 </Cards>

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

@@ -3,15 +3,14 @@
   "icon": "BookMarked",
   "pages": [
     "index",
+    "cli",
     "configuration",
-    "fx",
-    "i18n",
-    "client",
     "environment-variables",
+    "fx",
     "errors",
-    "plugins",
-    "cli",
     "security",
+    "i18n",
+    "plugins",
     "okid"
   ]
 }