okengine 0.18.5 → 0.19.1

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

@@ -1,38 +1,90 @@
 ---
 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({
+    in: z.object({ title: z.string().min(1) }),
+  }),
+  flow({
+    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 +92,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 +108,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 +213,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 +236,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 +302,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 +327,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"
   ]
 }

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

@@ -1,6 +1,6 @@
 ---
 title: "OKID"
-description: "OKE's native id generator — compact, URL-safe, cryptographically random ids from okengine/okid, with an opt-in time-sortable and alphabet-controlled variant."
+description: "OKE's native id generator — compact, URL-safe, cryptographically random ids from okengine/okid, with opt-in prefix, time-sortable, and alphabet-controlled variants."
 icon: "Hash"
 source: "docs/spec/unified-theory.md"
 ---
@@ -31,6 +31,7 @@ import { okid } from "okengine/okid";
 ```typescript
 const userId = okid();
 const requestId = okid(16);
+const typedId = okid({ prefix: "usr_" });
 const eventKey = okid({ sortable: true });
 const inviteCode = okid({ lookAlikes: false, uppercase: false });
 ```
@@ -55,21 +56,23 @@ The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
 
 ## Reference
 
-| Call                                               | Result                                    | Notes                                   |
-| -------------------------------------------------- | ----------------------------------------- | --------------------------------------- |
-| `okid()`                                           | 21-char URL-safe id, 126 bits of entropy  | 64-char alphabet, `a-zA-Z0-9-_`         |
-| `okid(length)`                                     | id of exactly `length` characters         | integer between 8 and 128               |
-| `okid({ length })`                                 | options form, id of `length`              | default 21                              |
-| `okid({ sortable })`                               | time-prefixed id, 8 prefix + `length − 8` | lexicographic order ≈ creation order    |
-| `okid({ numbers, lowercase, uppercase, symbols })` | charset control                           | each group defaults to on               |
-| `okid({ lookAlikes })`                             | confusable-char control                   | `lookAlikes: false` drops `1lI0Oouv5Ss` |
+| Call                                               | Result                                   | Notes                                   |
+| -------------------------------------------------- | ---------------------------------------- | --------------------------------------- |
+| `okid()`                                           | 21-char URL-safe id, 126 bits of entropy | 64-char alphabet, `a-zA-Z0-9-_`         |
+| `okid(length)`                                     | id of exactly `length` characters        | integer between 8 and 128               |
+| `okid({ length })`                                 | options form, body of `length`           | default 21                              |
+| `okid({ prefix })`                                 | `prefix` + body                          | body length unchanged; see Options      |
+| `okid({ sortable })`                               | time-prefixed body, 8 + `length − 8`     | lexicographic order ≈ creation order    |
+| `okid({ numbers, lowercase, uppercase, symbols })` | charset control                          | each group defaults to on               |
+| `okid({ lookAlikes })`                             | confusable-char control                  | `lookAlikes: false` drops `1lI0Oouv5Ss` |
 
 ### Options
 
 | Option       | Type      | Default | Meaning                                                     |
 | ------------ | --------- | ------- | ----------------------------------------------------------- |
-| `length`     | `number`  | `21`    | total id length in characters, between 8 and 128            |
-| `sortable`   | `boolean` | `false` | prefix an 8-char epoch-ms timestamp so sorting follows time |
+| `length`     | `number`  | `21`    | generated body length (8–128); does not include `prefix`    |
+| `prefix`     | `string`  | `""`    | fixed label prepended to the body (e.g. `"usr_"`, `"evt_"`) |
+| `sortable`   | `boolean` | `false` | prefix the body with an 8-char epoch-ms timestamp           |
 | `numbers`    | `boolean` | `true`  | include `0-9`                                               |
 | `lowercase`  | `boolean` | `true`  | include `a-z`                                               |
 | `uppercase`  | `boolean` | `true`  | include `A-Z`                                               |
@@ -83,10 +86,11 @@ The same 21-character id lands in your SQL primary keys, KV keys, and trace ids.
 | `OKID_ALPHABET`            | `a-zA-Z0-9-_`                             | default, Base64URL order         |
 | `OKID_SORTABLE_ALPHABET`   | alphabet sorted by code unit (same chars) | used by the sortable encoder     |
 | `OKID_LOOKALIKE_CHARS`     | `1lI0Oouv5Ss`                             | dropped when `lookAlikes: false` |
-| `OKID_DEFAULT_LENGTH`      | `21`                                      | default length                   |
-| `OKID_MIN_LENGTH`          | `8`                                       | shortest non-sortable length     |
-| `OKID_MAX_LENGTH`          | `128`                                     | longest length                   |
-| `OKID_SORTABLE_MIN_LENGTH` | `16`                                      | shortest sortable length (8+8)   |
+| `OKID_DEFAULT_LENGTH`      | `21`                                      | default body length              |
+| `OKID_MIN_LENGTH`          | `8`                                       | shortest non-sortable body       |
+| `OKID_MAX_LENGTH`          | `128`                                     | longest body                     |
+| `OKID_SORTABLE_MIN_LENGTH` | `16`                                      | shortest sortable body (8+8)     |
+| `OKID_MAX_PREFIX_LENGTH`   | `32`                                      | longest semantic `prefix`        |
 
 ## Collision resistance
 
@@ -94,6 +98,12 @@ Every character is drawn uniformly from the alphabet with `crypto.getRandomValue
 
 **Consequence:** two ids minted at the same millisecond are still distinct — the timestamp prefix never replaces entropy, it prefixes it.
 
+## Semantic prefixes
+
+`prefix` is a fixed label (`"usr_"`, `"evt_"`, `"inst-"`) prepended to the generated body. Characters must belong to `OKID_ALPHABET` (max 32). `length` stays the body size; the returned string is `prefix + body`.
+
+**Consequence:** `okid({ prefix: "usr_", sortable: true })` yields `usr_` + 8-char timestamp + random tail — the label sorts first, then time.
+
 ## Sortable ids
 
 `sortable: true` prepends 48 bits of `Date.now()` encoded in exactly 8 characters, in an alphabet whose sort order matches time order. Sorting a batch of these ids reproduces the creation order across milliseconds.
@@ -108,7 +118,7 @@ Turning groups off shrinks the alphabet. With a non-power-of-two alphabet, OKID
 
 ## Under the hood
 
-The generator is a pure function: no counters, no process or machine fingerprint, no shared mutable state. It is safe to call concurrently from any number of workers, and every id uses only the bytes it needs — no hidden timestamp, no hidden prefix.
+The generator is a pure function: no counters, no process or machine fingerprint, no shared mutable state. It is safe to call concurrently from any number of workers, and every body uses only the bytes it needs — no hidden timestamp unless `sortable` is on.
 
 ## Troubleshooting
 
@@ -122,6 +132,13 @@ Passing `numbers: false, lowercase: false, uppercase: false, symbols: false` at
 
 `okid(0)`, `okid(-1)`, `okid(7)`, `okid(129)`, and non-integer lengths throw a `RangeError`. Sortable ids have a higher floor: passing a sortable length below 16 throws. Keep lengths between 8 and 128 (16–128 for sortable).
 
+</Accordion>
+<Accordion title="I get a RangeError for a prefix">
+
+Characters outside `OKID_ALPHABET` (for example `usr:` or a space) throw
+`okid: prefix contains invalid character … — use characters from OKID_ALPHABET`.
+A prefix longer than 32 throws `okid: prefix length … exceeds max 32` — stick to `A-Za-z0-9-_`.
+
 </Accordion>
 <Accordion title="My ids are not sortable by the alphabet order I expected">
 
@@ -130,8 +147,16 @@ The default alphabet order is not lexicographic; `_` sorts between uppercase and
 </Accordion>
 </Accordions>
 
-## References
+## Learn more
 
 - [Store](/docs/elements/store) — `defaultFn(id)` in table declarations delegates to `okid()`
 - [fx](/docs/reference/fx) — `fx.id()` in the runtime uses `okid()`
 - [Clock](/docs/elements/clock) — process `instanceId` (`inst-<okid>`) is an OKID
+
+## Next
+
+<Cards>
+  <Card title="fx" description="fx.id() in Flows." href="/docs/reference/fx" />
+  <Card title="Store" description="defaultFn(id) on columns." href="/docs/elements/store" />
+  <Card title="Client" description="Ids round-trip on typed routes." href="/docs/client" />
+</Cards>

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

@@ -82,7 +82,7 @@ Every method below exists on both the fluent definition and the boot-time builde
 | `.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) |
 | `.errors(map)`                   | Typed errors flows can fail with                                                              |
-| `.client(name, ext)`             | A typed client extension (reserved seam — not yet merged into `createClient`)                 |
+| `.client(name, ext)`             | Reserved plugin seam — prefer `createAuthClient` method helpers for auth                      |
 | `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)                                                 |
 | `.cli(name, handler)`            | An `oke <name>` CLI command                                                                   |
 | `.config(schema)`                | A config schema; values live on the plugin identity                                           |
@@ -133,7 +133,7 @@ Plugin options are static by default — changing them means a redeploy. Every o
 ### Declare the source and its sync flow
 
 ```typescript title="src/app.ts"
-import { every, oke, on, store } from "okengine";
+import { clock, oke, on, store } from "okengine";
 import { configSource, maintenanceMode } from "okengine/plugins";
 
 const db = store.sql("app");
@@ -146,7 +146,8 @@ const maintenance = configSource({
   kv: cache, // read-through cache (optional)
 });
 
-on(every("30s"), maintenance.sync()); // one clock flow refreshes the box
+const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+on(maintenanceSyncClock, maintenance.sync()); // one clock flow refreshes the box
 
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
 ```