okengine 0.3.6 → 0.5.0

package/site/content/docs/plugins/two-factor.mdx

@@ -0,0 +1,116 @@
+---
+title: "Two-factor"
+description: "Official plugin — TOTP enable, verify, and disable for an authenticated session."
+icon: "LockKeyhole"
+source: "docs/spec/unified-theory.md"
+---
+
+`twoFactor()` adds RFC 6238 TOTP (HMAC-SHA1, 6 digits, 30s) after someone already has a session.
+Enable returns a secret, `otpauth://` URL, and recovery codes; verify mints a new session.
+
+<Callout title="The one rule">
+  Enable `gate.auth`, then `.plug(twoFactor())`. Enable and disable need a Bearer session —
+  verify is public and takes `{ userId, code }` after password (or other) sign-in.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { twoFactor } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(twoFactor());
+```
+
+</Step>
+
+<Step>
+### Enable (session required)
+
+Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take input only.
+
+```typescript
+const { data } = await api.auth.twoFactorEnable({});
+// data.secret, data.otpauthUrl, data.recoveryCodes
+```
+
+`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once; they are
+shown only here.
+
+</Step>
+
+<Step>
+### Verify a code
+
+```typescript
+const { data } = await api.auth.twoFactorVerify({ userId, code: "123456" });
+// hybrid session tokens — recovery codes also accepted once each
+```
+
+`POST /auth/two-factor/verify`. Missing / disabled factor or bad code → `AuthFailed` /
+`invalid_credentials`. Disable: `api.auth.twoFactorDisable` (Bearer via `auth.getToken`).
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option     | Type             | Default    | Meaning                          |
+| ---------- | ---------------- | ---------- | -------------------------------- |
+| `secret`   | `string`         | active\*   | HMAC secret (\*from `gate.auth`) |
+| `sessions` | `SessionStore`   | active\*   | Session store                    |
+| `now`      | `() => number`   | `Date.now` | Injectable clock                 |
+| `factors`  | `TwoFactorStore` | new        | Per-user TOTP + recovery hashes  |
+| `issuer`   | `string`         | `"oke"`    | Label in `otpauth://` URLs       |
+
+## Surfaces
+
+| Flow                    | Path                            | Gate                     |
+| ----------------------- | ------------------------------- | ------------------------ |
+| `auth.twoFactorEnable`  | `POST /auth/two-factor/enable`  | session + bearer         |
+| `auth.twoFactorVerify`  | `POST /auth/two-factor/verify`  | `gate.public` + otp rate |
+| `auth.twoFactorDisable` | `POST /auth/two-factor/disable` | session + bearer         |
+
+**Consequence:** verify issues a full session for `userId` — use it as the step after first-factor
+sign-in when the account has 2FA enabled.
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="twoFactorEnable returns AuthFailed unauthenticated">
+
+Wire a session into `createClient` (`auth.getToken` / `memorySession`) from email/password
+(or another method) first — enable is gated on Bearer.
+
+</Accordion>
+<Accordion title="verify always fails">
+
+Code must be six digits. Check clock skew (±1 window), and that you enrolled the `secret` from
+enable. A recovery code works once, then is consumed.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Passkey](/docs/plugins/passkey) — WebAuthn-shaped register / authenticate
+- [Gate](/docs/elements/gate) — session + policies
+- [Username](/docs/plugins/username) — first factor to enroll against
+
+## Next
+
+<Cards>
+  <Card title="Passkey" description="WebAuthn register and assert." href="/docs/plugins/passkey" />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Email OTP" description="Passwordless email codes." href="/docs/plugins/email-otp" />
+</Cards>

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

@@ -0,0 +1,117 @@
+---
+title: "Username"
+description: "Official plugin — username + password sign-up and sign-in under /auth, plugged onto gate.auth."
+icon: "UserRound"
+source: "docs/spec/unified-theory.md"
+---
+
+`username()` lets people register and sign in with a username instead of email. It adds two public
+Flows under `/auth` and contributes the `oke_usernames` table.
+
+<Callout title="The one rule">
+  Enable `gate.auth` first, then `.plug(username())`. The plugin `.needs("auth")` and joins the HTTP
+  router via Bindings — not registry metadata alone.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Plug it
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import { username } from "okengine/plugins";
+
+export const app = oke({
+  name: "shop",
+  env: "local",
+  gate: { auth: {} },
+}).plug(username());
+```
+
+</Step>
+
+<Step>
+### Sign up
+
+```typescript
+const { data, error } = await api.auth.signUpUsername({
+  username: "ali",
+  password: "CorrectHorse1",
+});
+```
+
+`POST /auth/sign-up/username` — usernames are normalized to lowercase; allowed pattern
+`[a-z0-9._-]{3,64}`.
+
+</Step>
+
+<Step>
+### Sign in
+
+```typescript
+const { data } = await api.auth.signInUsername({
+  username: "ali",
+  password: "CorrectHorse1",
+});
+// data: accessToken, refreshToken, accessExpiresAt, userId
+```
+
+Unknown username and bad password both return `AuthFailed` with
+`reason: "invalid_credentials"` (enumeration-safe).
+
+</Step>
+
+</Steps>
+
+## Options
+
+| Option      | Type            | Default    | Meaning                                                     |
+| ----------- | --------------- | ---------- | ----------------------------------------------------------- |
+| `secret`    | `string`        | active\*   | HMAC secret (\*from `gate.auth` when plugged after `oke()`) |
+| `sessions`  | `SessionStore`  | active\*   | Session store shared with Gate auth                         |
+| `now`       | `() => number`  | `Date.now` | Injectable clock                                            |
+| `usernames` | `UsernameStore` | new map    | Shared in-memory credential store                           |
+
+## Surfaces
+
+| Flow                  | Path                          | Gate                         |
+| --------------------- | ----------------------------- | ---------------------------- |
+| `auth.signUpUsername` | `POST /auth/sign-up/username` | `gate.public` + sign-up rate |
+| `auth.signInUsername` | `POST /auth/sign-in/username` | `gate.public` + sign-in rate |
+
+## Troubleshooting
+
+<Accordions>
+<Accordion title="plugin boot failed — needs &quot;auth&quot;">
+
+Set `oke({ gate: { auth: { … } } })` before `.plug(username())`.
+
+</Accordion>
+<Accordion title="AuthFailed invalid_credentials on sign-up">
+
+Username taken, or it fails the `[a-z0-9._-]{3,64}` pattern after lowercasing. Same error shape
+on purpose — do not treat it as "exists" in the UI.
+
+</Accordion>
+</Accordions>
+
+## Learn more
+
+- [Gate](/docs/elements/gate) — `gate.auth` and posture
+- [Plugins](/docs/plugins) — all auth method plugins
+- [Client](/docs/reference/client) — `createClient` + `memorySession`
+
+## Next
+
+<Cards>
+  <Card
+    title="Anonymous"
+    description="Session without a password."
+    href="/docs/plugins/anonymous"
+  />
+  <Card title="Gate" description="Builtin auth and policies." href="/docs/elements/gate" />
+  <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
+</Cards>

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

@@ -0,0 +1,331 @@
+---
+title: "Client"
+description: "Typed caller for your flows — createClient from okengine/client, zero codegen, errors as values."
+icon: "MonitorSmartphone"
+source: "docs/spec/unified-theory.md"
+---
+
+`okengine/client` is how a browser, CLI, or another service calls your app's flows. Adopt the unit, take `typeof app`, and `api.notes.get({ id })` is fully typed — same contracts the server already has, no separate schema project.
+
+<Callout title="The one rule">
+  Treat every call as a result envelope: `{ data, error }`. Flow failures are values you switch on
+  (`error.code`); they are never thrown. Only transport / protocol problems use
+  `code: "TransportError"`.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Adopt flows and export `App`
+
+```typescript title="src/app.ts"
+import { oke } from "okengine";
+import * as main from "./flows/main";
+
+export const app = oke({ name: "standard" }).adopt({ main });
+export type App = typeof app;
+```
+
+</Step>
+
+<Step>
+### Create the client
+
+Same repo — pass the app value so HTTP triggers hit REST (method + path from adopt):
+
+```typescript title="client"
+import { createClient } from "okengine/client";
+import { app } from "./app";
+
+const api = createClient(app, "http://localhost:6530");
+```
+
+Or type-only with `createClient<App>(url)` and pass `$routes: app.$routes` when you want REST
+instead of RPC.
+
+</Step>
+
+<Step>
+### Call a flow and narrow the result
+
+```typescript
+const { data, error } = await api.main.health();
+
+if (error) {
+  // TransportError or a declared flow code
+  return;
+}
+
+// data inferred from the flow's `out`
+console.log(data.ok);
+```
+
+With the starter, that is `GET /health` on port **6530** when `$routes` are wired.
+
+</Step>
+
+</Steps>
+
+## `createClient` forms
+
+| Form                            | Types from                             | Wire                                             |
+| ------------------------------- | -------------------------------------- | ------------------------------------------------ |
+| `createClient(app, url, opts?)` | `typeof app`                           | REST from `app.$routes`; untriggered flows → RPC |
+| `createClient<App>(url, opts?)` | Explicit `App` type                    | RPC unless `opts.$routes` or `opts.routes`       |
+| `createClient(url, opts?)`      | Ambient `Register` (`oke-client.d.ts`) | Same — pass routes for REST                      |
+
+`oke dev` regenerates `oke-client.d.ts` from `GET /_oke/client.json`. A separate frontend repo
+runs `oke client add <url>` (default out: `oke-client.d.ts`).
+
+```bash
+oke client add http://localhost:6530
+oke client add https://api.example.com --out ./types/oke-client.d.ts
+```
+
+## Options
+
+| Option          | Type                                           | Default            | Meaning                                                        |
+| --------------- | ---------------------------------------------- | ------------------ | -------------------------------------------------------------- |
+| `fetch`         | `(input, init?) => Promise<Response>`          | `globalThis.fetch` | Inject a fetch implementation                                  |
+| `headers`       | `Record<string, string>` \| pairs \| `() => …` | —                  | Static headers, or a getter per request                        |
+| `timeout`       | `number` (ms)                                  | —                  | Abort after this many milliseconds                             |
+| `retry.retries` | `number`                                       | `0`                | Extra attempts after the first (network / 5xx)                 |
+| `retry.delay`   | `number` (ms)                                  | `50`               | Initial backoff delay                                          |
+| `retry.backoff` | `number`                                       | `2`                | Multiplier after each retry                                    |
+| `auth.getToken` | `() => string \| null \| …`                    | —                  | Bearer access token (or null)                                  |
+| `auth.refresh`  | `() => Promise<string \| null \| …>`           | —                  | Runs once on HTTP 401, then the request retries                |
+| `$routes`       | `ClientRouteMap`                               | —                  | Runtime map from `app.$routes` (REST when method+path present) |
+| `routes`        | `Record<"unit.flow", { method, path }>`        | —                  | Flat REST table; wins over flattening `$routes`                |
+
+**Consequence:** `createClient<App>(url)` alone types the proxy but still posts
+`POST /_oke/{unit}/{flow}` until you pass the app value, `$routes`, or `routes`.
+
+## REST vs RPC
+
+| Situation                                          | Request                                                                                                  |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| HTTP trigger with method + path on `$routes`       | That method and path (`:id` filled from input; leftover fields → query on GET/HEAD, JSON body otherwise) |
+| Adopted flow with no HTTP trigger                  | `POST {base}/_oke/{unit}/{flow}` with JSON body                                                          |
+| Incomplete proxy path (`api.notes()` with no flow) | Result error: `Incomplete path: api.notes(…)`                                                            |
+
+```typescript
+// REST — createClient(app, url) saw method/path from on(http.get("/notes/:id"), …)
+await api.notes.get({ id: "n_1" }); // GET /notes/n_1
+
+// RPC — untriggered flow named notes.stats
+await api.notes.stats({ id: "n_1" }); // POST /_oke/notes/stats
+```
+
+## Result envelope and helpers
+
+Success may include optional top-level `meta` (for example pagination). Declared flow errors and
+transport failures share the failure arm:
+
+```typescript
+import { isOk, isFail, isErrorCode, isTransportError } from "okengine/client";
+
+const result = await api.bookings.create({ flightId: "SK1", seats: 9 });
+
+if (isOk(result)) {
+  result.data.id;
+} else if (result.error.code === "FlightFull") {
+  result.error.data.seatsLeft; // narrowed
+} else if (isTransportError(result.error)) {
+  result.error.data.message;
+}
+
+isFail(result); // true when error !== null
+isErrorCode(result.error, "FlightFull"); // type predicate helper
+```
+
+Prefer `error?.code === "FlightFull"` for inference; use `isErrorCode` in shared helpers.
+
+## Auth on the client
+
+One client: `createClient`. With `gate.auth`, the app exposes `/auth/*` Flows
+(sign-in, refresh, me). Helpers under `okengine/client/auth` store tokens — they are
+**not** a second factory.
+
+```typescript
+import { createClient } from "okengine/client";
+import { memorySession } from "okengine/client/auth";
+import { app } from "./app";
+
+const session = memorySession();
+
+const api = createClient(app, "http://localhost:6530", {
+  auth: {
+    getToken: () => session.getToken(),
+    refresh: () => session.refresh(api),
+  },
+});
+
+const { data } = await api.auth.signInEmail({ email, password });
+if (data) session.set(data);
+```
+
+React: `useSession(api, session)` from `okengine/client-react`.
+
+| Step                   | What happens                                                     |
+| ---------------------- | ---------------------------------------------------------------- |
+| Every request          | `getToken()` → `Authorization: Bearer …` when a token is present |
+| HTTP **401**           | `refresh()` runs **once**, then the same call retries            |
+| HTTP **403** / **429** | No refresh — decode the failure envelope as usual                |
+
+**Consequence:** `refresh` must mutate whatever `getToken` reads. Returning a new string alone does
+nothing if storage was not updated.
+
+After a gated call, switch on the denial codes (values, not throws):
+
+| Code           | HTTP | `error.data`       | Typical fix                                                  |
+| -------------- | ---- | ------------------ | ------------------------------------------------------------ |
+| `Unauthorized` | 401  | `{}`               | Sign in, or let `auth.refresh` run; re-login if still denied |
+| `Forbidden`    | 403  | `{ gate, reason }` | Wrong scopes / policy — show denied                          |
+| `RateLimited`  | 429  | `{ retryAfterMs }` | Wait `retryAfterMs` before retrying                          |
+
+These gate codes are **not** listed in each Flow’s `errors` map — they can appear on any gated
+route.
+
+A 401 with no `{ data, error }` body becomes `TransportError` with `data.status: 401`.
+
+| Helper                      | Package                 | Role                                             |
+| --------------------------- | ----------------------- | ------------------------------------------------ |
+| `memorySession`             | `okengine/client/auth`  | In-memory access/refresh bag for `auth.getToken` |
+| `AUTH_ERROR_CODES`          | `okengine/client/auth`  | Common auth Flow / gate codes                    |
+| `useSession(api, session?)` | `okengine/client-react` | React status + `auth.me`                         |
+
+Core `okengine/client` stays under the size budget — helpers are separate exports. Not in
+core today: cookie jars or plugin `.client()` decorations. Browser apps: also see
+[CORS](/docs/plugins/cors) and [CSRF](/docs/plugins/csrf).
+
+## Elements from the client
+
+<Callout title="Flows only">
+  The client calls **Flows**. Every other element runs on the server through `fx`. You reach its
+  outcome by calling a Flow that uses it — or by handling a gate denial on that call.
+</Callout>
+
+| Element                           | On the client | How                                                                                     |
+| --------------------------------- | ------------- | --------------------------------------------------------------------------------------- |
+| [Flow](/docs/elements/flow)       | Direct        | `api.unit.flow(input)` — the only public surface                                        |
+| [Gate](/docs/elements/gate)       | Indirect      | Bearer via `auth`; denials as `Unauthorized` / `Forbidden` / `RateLimited`              |
+| [Store](/docs/elements/store)     | Via Flows     | `fx.store` inside Flows; `store.resource` + `on(http.resource…)` → five Flows you adopt |
+| [Signal](/docs/elements/signal)   | Via Flows     | Emit/consume server-side; no subscribe API on `okengine/client` yet                     |
+| [Clock](/docs/elements/clock)     | Via Flows     | Schedules fire on the server — the client never ticks a clock                           |
+| [Vault](/docs/elements/vault)     | Via Flows     | Secrets stay server-side; never ship them to the browser package                        |
+| [Channel](/docs/elements/channel) | Via Flows     | `fx.send` in a Flow — the client does not send email/SMS/push                           |
+| [AI](/docs/elements/ai)           | Via Flows     | `fx.ask` / `fx.run` inside a Flow; the client gets that Flow’s `out`                    |
+
+### Store resources
+
+Mount a resource, adopt the returned ops, then call the five Flows like any other:
+
+```typescript
+const notesR = store.resource(db, notes, {/* in, out, list, unit: "notes" */});
+const mounted = on(http.resource("/notes", notesR.all()));
+// .adopt({ notes: mounted }) →
+await api.notes.list({ limit: 20 }); // GET /notes?limit=20 — meta may carry nextCursor
+await api.notes.get({ id }); // GET /notes/:id — NotFound when missing
+await api.notes.remove({ id }); // DELETE → 204, data undefined
+```
+
+See [Store](/docs/elements/store) for the list query language and schemas. Auth posture for HTTP
+triggers is covered under [Gate](/docs/elements/gate).
+
+### Signal and live queries
+
+`delivery: "live"` and `http.get(…).live()` are Manifest / driver flags today. `okengine/client`
+does **not** expose WebSocket, SSE, or `api.*.subscribe`. Until that ships, poll or call an HTTP
+Flow that returns the current state.
+
+## Exports
+
+| Export                                       | Kind      | Role                                              |
+| -------------------------------------------- | --------- | ------------------------------------------------- |
+| `createClient`                               | function  | Typed proxy `api.unit.flow(input?)`               |
+| `flattenRoutes`                              | function  | `$routes` → flat `unit.flow` REST table           |
+| `createTransport`                            | function  | Low-level HTTP transport (timeout / retry / auth) |
+| `isOk` / `isFail`                            | function  | Envelope predicates                               |
+| `isErrorCode` / `isTransportError`           | function  | Error narrowing                                   |
+| `Client`, `ClientOptions`, `ClientResult`, … | types     | Contracts and options                             |
+| `Register`                                   | interface | Module-augmentation slot for ambient App types    |
+| `AppOf`                                      | type      | Brand a bare route map as an App                  |
+
+Budget: the `./client` export stays under the measured client-runtime cap (hard gate in CI).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="api.main.health is not a function / type error">
+
+Confirm the flow is `export`ed from the module you `.adopt({ main })`, and that `createClient` is
+typed with that `App` (or ambient `Register` after `oke-client.d.ts` regenerates). Restart
+`oke dev` after renaming exports.
+
+</Accordion>
+
+<Accordion title="Calls hit /_oke/… instead of my HTTP path">
+
+Types alone do not choose REST. Pass `createClient(app, url)`, or
+`createClient(url, { $routes: app.$routes })`, or an explicit `routes` map.
+
+</Accordion>
+
+<Accordion title='error.code is "TransportError"'>
+
+Network failure, abort (`timeout`), non-JSON body, empty error response, or HTTP status without a
+`{ data, error }` envelope. Declared flow codes (`NotFound`, `FlightFull`, …) never use this code.
+Message text lives in `error.data.message`; HTTP status may appear as `error.data.status`.
+
+</Accordion>
+
+<Accordion title="401 loops or refresh never sticks">
+
+`auth.refresh` runs once per call on HTTP 401. It must update the store `getToken` reads — the
+return value is ignored. With `gate.auth`, `POST /auth/refresh` is built in; `memorySession.refresh(api)`
+calls `api.auth.refresh({ refreshToken })`. Re-login when rotation fails or no refresh token remains.
+
+</Accordion>
+
+<Accordion title="Failed to fetch …/_oke/client.json">
+
+`oke client add` needs a running app that serves the descriptor. Start the app (`oke dev` /
+`oke start`), check the URL, then retry. Usage when the URL is missing:
+`Usage: oke client add <url> [--out oke-client.d.ts]`.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Basic usage](/docs/get-started/basic-usage) — adopt → client → test loop
+- [Gate](/docs/elements/gate) — policies, `gate.public`, denials
+- [Store](/docs/elements/store) — `store.resource` and list query language
+- [Flow](/docs/elements/flow) — `in` / `out` / `errors` and `fx.fail`
+- [Errors](/docs/reference/errors) — framework codes vs failure values
+- [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) — browser callers
+- [CLI Reference](/docs/reference/cli) — `oke client add`, `oke dev`
+
+## Next
+
+<Cards>
+  <Card
+    title="Gate"
+    description="Auth policies and rate limits before any effect."
+    href="/docs/elements/gate"
+  />
+  <Card
+    title="Store"
+    description="Resources that become five typed client Flows."
+    href="/docs/elements/store"
+  />
+  <Card
+    title="Errors"
+    description="OKE codes, denials, and failure values."
+    href="/docs/reference/errors"
+  />
+</Cards>

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

@@ -39,7 +39,7 @@ drivers: {
 | `store.sql`        | env driver map | `sqlite` · `postgres` · `libsql` · `pglite` · `memory`                       |
 | `store.kv`         | env driver map | `memory` · `redis`                                                           |
 | `store.files`      | env driver map | `memory` · `fs` · `s3`                                                       |
-| `store.index`      | env driver map | `memory` · `pgvector` · `libsql`                                             |
+| `store.index`      | env driver map | `memory` · `pgvector` · `libsql` · `meilisearch`                             |
 | `signal`           | env driver map | `memory` · `postgres` · `redis` · `nats`                                     |
 | `clock`            | env driver map | `memory` · `postgres` · `frozen`                                             |
 | `vault`            | env driver map | `dotenv` · `openbao` · `memory`                                              |

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

@@ -24,9 +24,11 @@ OKE reads environment variables at boot for connection detail and secrets — ne
 
 ## Index store
 
-| Variable           | Used for                  | Default when unset |
-| ------------------ | ------------------------- | ------------------ |
-| `OKE_INDEX_DRIVER` | Force the index driver id | config map         |
+| Variable              | Used for                                            | Default when unset |
+| --------------------- | --------------------------------------------------- | ------------------ |
+| `OKE_INDEX_DRIVER`    | Force the index driver id                           | config map         |
+| `OKE_STORE_INDEX_URL` | Meilisearch base URL (`meilisearch` driver)         | —                  |
+| `OKE_STORE_INDEX_KEY` | Meilisearch API / master key (`meilisearch` driver) | `MEILI_MASTER_KEY` |
 
 ## KV store
 

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

@@ -44,9 +44,14 @@ See [Store](/docs/elements/store) for the query-builder surface.
 | `fx.all([...thunks])`        | —       | Parallel; first rejection aborts siblings             |
 | `fx.race([...thunks])`       | —       | First settle wins; losers aborted                     |
 | `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.call` starts the callee with an **empty** `fx.auth` (fail-closed for authorization). For
+audit/attribution only, read `fx.principal` — it propagates the originating identity without
+copying into `fx.auth`. Gates never consult `fx.principal`.
+
 ## Concurrency and retry
 
 Pass **thunks** to `all` / `race` — not already-started Promises — so each branch gets an abort scope before work begins.
@@ -81,6 +86,18 @@ const charge = await fx.step("charge", () =>
   `Promise.all`.
 </Callout>
 
+`fx.using(acquire, release, use)` scopes a process-local resource to one attempt: `release` runs
+exactly once when `use` settles **or** when the ambient signal aborts (a sibling `fx.race` winner,
+a failing `fx.all` sibling). It is not journaled — do not hold handles across durable park/resume.
+
+```typescript
+const rows = await fx.using(
+  () => pool.acquire(),
+  (conn) => conn.release(),
+  (conn) => conn.query("select …"),
+);
+```
+
 **Consequence:** put `fx.retry` inside `fx.step` on durable flows so a completed charge never re-runs on resume. Coarse whole-body retry is `flow({ retry: { … } })` on the same journal session.
 
 ## Channel
@@ -102,9 +119,9 @@ AI calls are nondeterministic: journaling is forced on and auto-cache disabled a
 
 ## Vault
 
-| Signature            | Records | Returns / notes                                                         |
-| -------------------- | ------- | ----------------------------------------------------------------------- |
-| `fx.vault(contract)` | `read`  | Cleartext, inside this flow only — registered with the redactor at boot |
+| Signature            | Records | Returns / notes                                                                           |
+| -------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `fx.vault(contract)` | `read`  | `Redacted<string>` — prints/logs as a placeholder; `.reveal()` at the credential boundary |
 
 ## Clock
 
@@ -144,11 +161,22 @@ Returning a plain value instead answers 200 with `{ data: value, error: null }`
 
 ## Principals
 
-| Property      | Shape                                                                 |
-| ------------- | --------------------------------------------------------------------- |
-| `fx.auth`     | `{ userId: string \| null, scopes: Set<string>, verified?: boolean }` |
-| `fx.operator` | `{ id: string \| null }` — Console plane                              |
-| `fx.tenant`   | `{ id: string \| null }` — active tenant                              |
+| Property       | Shape                                                                     |
+| -------------- | ------------------------------------------------------------------------- |
+| `fx.auth`      | `{ userId: string \| null, scopes: Set<string>, verified?: boolean }`     |
+| `fx.operator`  | `{ id: string \| null }` — Console plane                                  |
+| `fx.principal` | Read-only origin: `userId`, `operatorId`, `scopes`, `verified?`, `plane?` |
+| `fx.tenant`    | `{ id: string \| null }` — active tenant                                  |
+
+**Consequence:** use `fx.auth` / gates for authorization; use `fx.principal` only when a callee
+must log who started the call chain.
+
+## Not on `fx`
+
+<Callout title="No fx.metric">
+  Investigated and declined. [Runs](/docs/console/runs) already own per-invocation observability as
+  wide events; a parallel counter/gauge API would be a second instrumentation path without a sink.
+</Callout>
 
 ## Learn more