okengine 0.18.4 → 0.19.0

package/site/content/docs/index.mdx

@@ -5,74 +5,122 @@ icon: "BookOpen"
 source: "docs/spec/unified-theory.md"
 ---
 
-Welcome to the okengine handbook. The backend model stays small; operational surfaces are derived from it instead of maintained separately.
+Welcome to the OKEngine handbook. Keep the model small; let the backend grow without growing the mental model.
 
-<Callout title="The one law">
+<Callout title="The Law">
   Every backend behavior is a Flow: `on(Trigger) → Effects`. One species; triggers are typed values.
 </Callout>
 
 ```ts
-on(http.post("/bookings"), createBooking);
-on(every("10m"), expireStale);
+on(http.post(), createBooking); // path + name from the file tree
+on(expireStaleClock, expireStale);
 on(orderPlaced, sendReceipt);
 ```
 
-## Understand OKE (Core Model)
+## 01 Understand
+
+Master the mental model before exploring features:
 
 <Cards>
   <Card
-    title="Why OKE"
-    description="From forty tools to one species — the problem, the law, and the Manifest contract."
-    href="/docs/get-started/why"
+    title="The Problem"
+    description="Three unrelated features that hit the exact same wall, and the timeline that shows why."
+    href="/docs/understand/the-problem"
   />
   <Card
-    title="Elements"
-    description="The eight closed core elements: Flow, Signal, Store, Clock, Gate, Vault, Channel, AI."
-    href="/docs/elements"
+    title="The Model"
+    description="The one rule that removes the disagreement between systems — stated plainly, in two parts."
+    href="/docs/understand/the-model"
+  />
+  <Card
+    title="The Vocabulary"
+    description="The eight things the door recognizes — what each one replaces, and why nothing else made the cut."
+    href="/docs/understand/the-vocabulary"
   />
   <Card
-    title="Introduction"
-    description="The one law, eight elements, and one contract."
-    href="/docs/get-started/introduction"
+    title="The Anatomy"
+    description="The five pieces behind on(trigger, flow) — on, trigger, flow, do, and fx — explained one at a time."
+    href="/docs/understand/the-anatomy"
+  />
+  <Card
+    title="Try It"
+    description="From an empty folder to a Flow running in the Console — one sitting, minimal detour."
+    href="/docs/ai/try-it"
   />
 </Cards>
 
-## Build with OKE (Surfaces & Infrastructure)
+## 02 Elements
+
+Deep primitives and execution law:
 
 <Cards>
   <Card
-    title="Get Started"
-    description="Installation, basic usage, project structure, and testing."
-    href="/docs/get-started"
+    title="Elements"
+    description="Flow, Signal, Store, Clock, Gate, Vault, Channel, AI."
+    href="/docs/elements"
+  />
+  <Card
+    title="Reference"
+    description="CLI, configuration, fx, errors, security, and plugins."
+    href="/docs/reference"
+  />
+  <Card
+    title="AI Resources"
+    description="Runtime MCP (:6535), docs MCP (:6536), agent skills, and machine-readable docs."
+    href="/docs/ai"
   />
+</Cards>
+
+## 03 Extend
+
+Connect to infrastructure and extend the model:
+
+<Cards>
   <Card
     title="Plugins"
-    description="22 official extensions — authentication, OAuth, security, ops, performance."
+    description="Official extensions that add capabilities without creating a ninth element."
     href="/docs/plugins"
   />
   <Card
     title="Providers"
-    description="12 managed cloud infrastructure options behind protocol-named drivers."
+    description="Managed cloud infrastructure behind protocol-named drivers."
     href="/docs/providers"
   />
   <Card
     title="Recipes"
-    description="20 self-hosted infrastructure recipes via Docker compose."
+    description="Self-hosted Docker compose recipes for SQL, KV, search, and local AI."
     href="/docs/recipes"
   />
+</Cards>
+
+## 04 Client
+
+Call your Flows from a browser, CLI, or another service — typed, zero separate codegen:
+
+<Cards>
   <Card
-    title="Reference"
-    description="Configuration, fx ledger, environment variables, errors, client, and security."
-    href="/docs/reference"
+    title="Overview"
+    description="createClient, envelopes as values, and how Client relates to the eight elements."
+    href="/docs/client"
   />
   <Card
-    title="AI Resources & MCP"
-    description="Runtime MCP (:6535), docs MCP (:6536), skills, and /llms.txt."
-    href="/docs/ai"
+    title="Calling"
+    description="REST vs RPC, options, result helpers, resources, and remote types."
+    href="/docs/client/calling"
+  />
+  <Card
+    title="Auth"
+    description="Bearer sessions, refresh once on 401, and gate denials as values."
+    href="/docs/client/auth"
+  />
+  <Card
+    title="Live"
+    description="api.live SSE, resume, and live resource queries."
+    href="/docs/client/live"
   />
   <Card
-    title="Deployment"
-    description="Docker, Swarm, Kubernetes, and reverse proxy deployment."
-    href="/docs/deployment"
+    title="React"
+    description="useSession, useLive, and useLiveQuery from okengine/client-react."
+    href="/docs/client/react"
   />
 </Cards>

package/site/content/docs/meta.json

@@ -3,16 +3,19 @@
   "icon": "BookOpen",
   "pages": [
     "index",
-    "---Understand OKE---",
+    "---01 Understand---",
+    "understand",
+    "---02 Elements---",
     "elements",
-    "---Build with OKE---",
-    "get-started",
-    "ai",
-    "deployment",
-    "reference",
+    "---03 Extend---",
     "plugins",
-    "---Drivers---",
     "providers",
-    "recipes"
+    "recipes",
+    "---04 Client---",
+    "client",
+    "---05 Reference---",
+    "reference",
+    "---06 AI Resources---",
+    "ai"
   ]
 }

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

@@ -71,7 +71,8 @@ const origins = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), origins.sync());
+const corsSyncClock = clock("cors.sync", { every: "30s" });
+on(corsSyncClock, origins.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(cors(origins));
 ```
 

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

@@ -18,6 +18,8 @@ export const app = oke({ name: "shop", env: "dev" }).plug(csrf());
 
 `GET`/`HEAD`/`OPTIONS`/`QUERY` always pass. A `POST` with `Sec-Fetch-Site: cross-site` now gets the gate element's typed `Forbidden` — unless its `Origin` is yours or allow-listed.
 
+When `gate.auth.cookies.enabled`, the server **soft-requires** this plugin: prod boots refuse without it; dev/test warn. Use `allowNoHeader: false` for cookie-only SPAs.
+
 ## How it decides
 
 <Steps>
@@ -73,7 +75,8 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), rules.sync());
+const csrfSyncClock = clock("csrf.sync", { every: "30s" });
+on(csrfSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(csrf(rules));
 ```
 

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

@@ -103,7 +103,8 @@ const headerConfig = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), headerConfig.sync());
+const headerSyncClock = clock("headers.sync", { every: "30s" });
+on(headerSyncClock, headerConfig.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(headers(headerConfig));
 ```
 

package/site/content/docs/plugins/ip-allowlist.mdx

@@ -69,7 +69,8 @@ const rules = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), rules.sync());
+const ipRulesSyncClock = clock("ip-allowlist.sync", { every: "30s" });
+on(ipRulesSyncClock, rules.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(ipAllowlist(rules));
 ```
 

package/site/content/docs/plugins/magic-link.mdx

@@ -63,6 +63,12 @@ const { data } = await api.auth.verifyMagicLink({ token });
 
 </Steps>
 
+<Callout type="info" title="Pre-account hijack defense">
+  Completing verify proves inbox ownership. An **unverified** email+password account parked on that
+  address is reclaimed (sessions revoked, hashes cleared, `emailVerified` set). Verified owners
+  re-auth only — no credential purge.
+</Callout>
+
 ## Options
 
 | Option           | Type                | Default                    | Meaning                                   |

package/site/content/docs/plugins/maintenance-mode.mdx

@@ -78,7 +78,8 @@ const maintenance = configSource({
   db: { store: db },
   kv: cache,
 });
-on(every("30s"), maintenance.sync());
+const maintenanceSyncClock = clock("maintenance.sync", { every: "30s" });
+on(maintenanceSyncClock, maintenance.sync());
 export const app = oke({ name: "shop", env: "dev" }).plug(maintenanceMode(maintenance));
 ```
 

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

@@ -173,7 +173,7 @@ via `POST /auth/oauth/{provider}/link`.
 
 - [Gate](/docs/elements/gate) — `gate.auth`
 - [Passkey](/docs/plugins/passkey) — phishing-resistant alternative
-- [Client](/docs/reference/client) — calling `/auth` from the browser
+- [Client · Auth](/docs/client/auth) — calling `/auth` from the browser
 
 ## Next
 

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

@@ -100,6 +100,12 @@ const { data } = await api.auth.verifyOtp({
 
 </Steps>
 
+<Callout type="info" title="Pre-account hijack defense (email)">
+  App-mode email verify proves inbox ownership. An **unverified** parked email+password account is
+  reclaimed (sessions revoked, hashes cleared, `emailVerified` set) before the OTP session. Verified
+  owners re-auth only.
+</Callout>
+
 ## Modes
 
 |                      | Provider mode                 | App mode                                      |
@@ -202,6 +208,7 @@ In `local` / `test` the `console` driver captures messages. Use
 ## Learn more
 
 - [Magic link](/docs/plugins/magic-link) — link instead of a code
+- [Two-factor](/docs/plugins/two-factor) — email OTP / TOTP as a **second** factor after password (distinct from this primary `/auth/otp` sign-in)
 - [Channel](/docs/elements/channel) — `fx.send`, `fx.sendOtp`, drivers, Mailpit
 - [Gate](/docs/elements/gate) — `gate.auth`
 
@@ -209,6 +216,10 @@ In `local` / `test` the `console` driver captures messages. Use
 
 <Cards>
   <Card title="Magic link" description="Email link sign-in." href="/docs/plugins/magic-link" />
-  <Card title="Two-factor" description="TOTP second factor." href="/docs/plugins/two-factor" />
+  <Card
+    title="Two-factor"
+    description="TOTP / email OTP second factor."
+    href="/docs/plugins/two-factor"
+  />
   <Card title="Channel" description="Delivery drivers and Mailpit." href="/docs/elements/channel" />
 </Cards>

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

@@ -1,17 +1,17 @@
 ---
 title: "Passkey"
-description: "Official plugin — WebAuthn register and authenticate under /auth with signature and origin checks."
+description: "Official plugin — WebAuthn register and authenticate under /auth with UV, signCount, and ceremony session binding."
 icon: "FingerprintPattern"
 source: "docs/spec/unified-theory.md"
 ---
 
-`passkey()` adds register and authenticate Flows for WebAuthn credentials (`oke_passkeys`).
-Options return a challenge; register and authenticate verify `clientDataJSON` origin + challenge,
-`authenticatorData` rpId hash, and an ECDSA P-256 signature against the stored SPKI public key.
+`passkey()` adds register and authenticate Flows for WebAuthn credentials
+(`oke_passkeys`). Options return a challenge plus a ceremony `sessionId`;
+register/authenticate verify client data, authenticator data, and ECDSA P-256.
 
 <Callout title="The one rule">
   Enable `gate.auth`, then `.plug(passkey())`. Registration needs a Bearer session; authenticate is
-  public. Post the full ceremony fields — presence of a stored credential alone never issues a
+  public. Echo the options `sessionId` with every ceremony — UV=false assertions never mint a
   session.
 </Callout>
 
@@ -42,15 +42,16 @@ Wire Bearer on `createClient` (`auth.getToken` / `memorySession`) — calls take
 
 ```typescript
 const opts = await api.auth.passkeyRegisterOptions({});
-// opts.data: { challenge, rpId, userId }
+// opts.data: { challenge, sessionId, rpId, userId }
 
 await api.auth.passkeyRegister({
   credentialId: "...", // base64url
   publicKey: "...", // base64url SPKI (ECDSA P-256)
   userId: opts.data!.userId,
   challenge: opts.data!.challenge,
-  clientDataJSON: "...", // base64url JSON { type, challenge, origin }
-  authenticatorData: "...", // base64url
+  sessionId: opts.data!.sessionId,
+  clientDataJSON: "...", // base64url JSON { type: "webauthn.create", challenge, origin }
+  authenticatorData: "...", // base64url (UP|UV required)
   signature: "...", // base64url ECDSA over authData || SHA-256(clientDataJSON)
 });
 ```
@@ -67,19 +68,30 @@ const opts = await api.auth.passkeyAuthenticateOptions({});
 const { data } = await api.auth.passkeyAuthenticate({
   credentialId: "...",
   challenge: opts.data!.challenge,
-  clientDataJSON: "...",
+  sessionId: opts.data!.sessionId,
+  clientDataJSON: "...", // type must be "webauthn.get"
   authenticatorData: "...",
   signature: "...",
 });
 ```
 
 Paths: `POST /auth/passkey/authenticate/options`, `POST /auth/passkey/authenticate`.
-Challenges are single-use; wrong origin → `invalid_origin`; bad signature → `invalid_credentials`.
+Challenges are single-use and bound to `sessionId`; wrong origin → `invalid_origin`; UV
+missing → `user_not_verified`; cloned counter → `reregister_required`.
 
 </Step>
 
 </Steps>
 
+## Server checks
+
+| Check             | Behavior                                                                                                                |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Ceremony type     | `clientDataJSON.type` must be `webauthn.create` (register) or `webauthn.get` (authenticate)                             |
+| User verification | AuthenticatorData UV bit must be set — UV=false is always rejected                                                      |
+| Challenge binding | Challenge hash + `sessionId` must match; TTL ≤ 5 minutes; single-use                                                    |
+| Signature counter | Stored per credential; if stored ≠ 0 and incoming `signCount` ≤ stored → delete credential, warn, `reregister_required` |
+
 ## Options
 
 | Option       | Type                | Default                                    | Meaning                          |
@@ -101,8 +113,8 @@ Challenges are single-use; wrong origin → `invalid_origin`; bad signature →
 | `auth.passkeyAuthenticateOptions` | `POST /auth/passkey/authenticate/options` | `gate.public` + otp rate |
 | `auth.passkeyAuthenticate`        | `POST /auth/passkey/authenticate`         | `gate.public` + otp rate |
 
-**Consequence:** a stolen `credentialId` without the private key cannot mint a session. Set
-`origins` to your real app origins before production.
+**Consequence:** a stolen `credentialId` without the private key (and UV) cannot mint a session.
+Set `origins` to your real app origins before production.
 
 ## Troubleshooting
 
@@ -116,11 +128,23 @@ Sign in with another method first. `userId` in the body must match the Bearer se
 
 `clientDataJSON.origin` must be in `passkey({ origins })`. Default allows only localhost HTTP/S.
 
+</Accordion>
+<Accordion title="authenticate returns user_not_verified">
+
+AuthenticatorData UV bit was not set. Require user verification on the client
+(`userVerification: "required"`) — the server never accepts UV=false.
+
+</Accordion>
+<Accordion title="authenticate returns reregister_required">
+
+Signature counter did not increase (possible cloned authenticator). That credential was
+deleted — register a fresh passkey for the account.
+
 </Accordion>
 <Accordion title="authenticate returns invalid_credentials">
 
-Unknown `credentialId`, consumed/expired challenge, bad signature, or rpId hash mismatch.
-Re-run authenticate options for a fresh challenge, then sign with the enrolled private key.
+Unknown `credentialId`, wrong/expired/`sessionId` mismatch, bad signature, wrong ceremony
+type, or rpId hash mismatch. Re-run authenticate options for a fresh challenge + `sessionId`.
 
 </Accordion>
 </Accordions>
@@ -129,7 +153,7 @@ Re-run authenticate options for a fresh challenge, then sign with the enrolled p
 
 - [Two-factor](/docs/plugins/two-factor) — TOTP step-up
 - [Gate](/docs/elements/gate) — `gate.auth`
-- [Client](/docs/reference/client) — calling `/auth` from the browser
+- [Client · Auth](/docs/client/auth) — calling `/auth` from the browser
 
 ## Next
 

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

@@ -1,17 +1,18 @@
 ---
 title: "Two-factor"
-description: "Official plugin — TOTP enable, verify, and disable for an authenticated session."
+description: "Official plugin — method-locked TOTP or email OTP after first-factor sign-in, with step-up enrollment and method change."
 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.
-TOTP codes are compared in constant time (±1 step window).
+`twoFactor()` adds a second factor after password (or username) sign-in: RFC 6238
+TOTP or email OTP. When 2FA is enabled, first-factor success withholds session
+tokens and returns a **method-locked** challenge.
 
 <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.
+  Enable `gate.auth`, then `.plug(twoFactor())`. Login challenges lock the configured method (`totp`
+  or `email_otp`). Mid-challenge QR enrollment returns `Forbidden`. Method change needs step-up
+  verify → provision → confirm.
 </Callout>
 
 ## Quick start
@@ -35,69 +36,124 @@ export const app = oke({
 </Step>
 
 <Step>
-### Enable (session required)
+### First-time 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
+// data.secret, data.otpauthUrl, data.recoveryCodes, data.method === "totp"
 ```
 
-`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once; they are
-shown only here.
+`POST /auth/two-factor/enable` — writes `oke_two_factor`. Store recovery codes once.
+Re-enrollment when 2FA is already enabled requires step-up first
+(`twoFactorStepUp`). An active login challenge → `Forbidden` / `active_2fa_challenge`.
 
 </Step>
 
 <Step>
-### Verify a code
+### Sign-in then verify
 
 ```typescript
-const { data } = await api.auth.twoFactorVerify({ userId, code: "123456" });
-// hybrid session tokens — recovery codes also accepted once each
+const signIn = await api.auth.signInUsername({ username, password });
+if ("twoFactorRequired" in signIn.data && signIn.data.twoFactorRequired) {
+  const { data } = await api.auth.twoFactorVerify({
+    challengeId: signIn.data.challengeId,
+    code: "123456",
+  });
+  // hybrid session tokens
+}
 ```
 
-`POST /auth/two-factor/verify`. Missing / disabled factor or bad code → `AuthFailed` /
-`invalid_credentials`. Disable: `api.auth.twoFactorDisable` (Bearer via `auth.getToken`).
+`POST /auth/two-factor/verify` takes `{ challengeId, code }` — not a bare
+`userId`. Missing challenge, method mismatch, or bad code → `AuthFailed` /
+`invalid_credentials`.
 
 </Step>
 
 </Steps>
 
+## Method lock
+
+When a login challenge is issued, the active method is recorded on the pending
+challenge. Until that challenge is consumed or expires:
+
+- Only codes for the **locked** method are accepted.
+- `twoFactorEnable`, `twoFactorChangeMethod`, `twoFactorConfirmChange`, and
+  `twoFactorDisable` return `Forbidden` with `active_2fa_challenge` if called
+  for that user (including with an older Bearer session).
+
+This closes the July–August 2026 method-switching bypass pattern (switch to
+TOTP enrollment mid email-OTP challenge without proving the current factor).
+
+## Step-up and method change
+
+1. `POST /auth/two-factor/step-up` — `{ code, purpose }` verifies the **current**
+   method and grants a short-lived step-up (`enroll` | `change` | `disable`).
+2. `POST /auth/two-factor/change-method` — `{ method, email? }` provisions the new
+   method in a pending state (TOTP QR or email OTP). Requires step-up.
+3. `POST /auth/two-factor/confirm-change` — `{ code }` activates the new method and
+   **immediately invalidates** the old secret / recovery codes.
+
+Disable also requires step-up when 2FA is already enabled.
+
 ## 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       |
+| 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 method + TOTP / recovery            |
+| `issuer`        | `string`                | `"oke"`    | Label in `otpauth://` URLs                   |
+| `pending`       | `PendingTwoFactorStore` | active\*   | Login challenges                             |
+| `stepUp`        | `StepUpStore`           | active\*   | Privileged-op grants                         |
+| `verifications` | `VerificationStore`     | active\*   | Email OTP as second factor (`2fa:{userId}`)  |
+| `exposeDevOtp`  | `boolean`               | `false`    | Return `devOtp` on email_otp challenge paths |
 
 ## 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         |
+| Flow                            | Path                                      | Gate                     |
+| ------------------------------- | ----------------------------------------- | ------------------------ |
+| `auth.twoFactorEnable`          | `POST /auth/two-factor/enable`            | session + bearer         |
+| `auth.twoFactorVerify`          | `POST /auth/two-factor/verify`            | `gate.public` + otp rate |
+| `auth.twoFactorStepUp`          | `POST /auth/two-factor/step-up`           | session + bearer         |
+| `auth.twoFactorChangeMethod`    | `POST /auth/two-factor/change-method`     | session + bearer         |
+| `auth.twoFactorConfirmChange`   | `POST /auth/two-factor/confirm-change`    | session + bearer         |
+| `auth.twoFactorRequestEmailOtp` | `POST /auth/two-factor/request-email-otp` | 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.
+**Consequence:** email/password and username sign-in return
+`{ twoFactorRequired, challengeId, method, userId }` (no tokens) when the
+account has 2FA enabled. Complete login only via `twoFactorVerify`.
 
 ## Troubleshooting
 
 <Accordions>
+<Accordion title="twoFactorEnable returns Forbidden active_2fa_challenge">
+
+Finish or wait out the login 2FA challenge first. Enrollment is blocked while
+an unresolved challenge exists for that user.
+
+</Accordion>
+<Accordion title="twoFactorEnable returns Forbidden step_up_required">
+
+2FA is already enabled. Call `twoFactorStepUp` with a valid current-method code
+(`purpose: "enroll"`), then enable again.
+
+</Accordion>
 <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.
+Wire a session into `createClient` (`auth.getToken` / `memorySession`) first —
+enable is gated on Bearer. First-time enroll must happen **before** 2FA is
+required on sign-in (or after a full session from a completed challenge).
 
 </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.
+Submit `{ challengeId, code }` from the sign-in challenge response. TOTP must be
+six digits (±1 window). Email OTP uses the code from the locked `email_otp`
+challenge. A recovery code works once for TOTP, then is consumed.
 
 </Accordion>
 </Accordions>
@@ -107,7 +163,8 @@ enable. A recovery code works once, then is consumed.
 - [Passkey](/docs/plugins/passkey) — WebAuthn register / authenticate
 - [Gate](/docs/elements/gate) — session + policies
 - [Username](/docs/plugins/username) — first factor to enroll against
-- OTP over SMS or email instead of TOTP? See [OTP](/docs/plugins/otp) / [Magic link](/docs/plugins/magic-link)
+- Primary OTP sign-in (not a second factor)? See [OTP](/docs/plugins/otp) /
+  [Magic link](/docs/plugins/magic-link)
 
 ## Next
 

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

@@ -102,7 +102,7 @@ on purpose — do not treat it as "exists" in the UI.
 
 - [Gate](/docs/elements/gate) — `gate.auth` and posture
 - [Plugins](/docs/plugins) — all auth method plugins
-- [Client](/docs/reference/client) — `createClient` + `memorySession`
+- [Client · Auth](/docs/client/auth) — `createClient` + `memorySession`
 
 ## Next
 

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

@@ -81,7 +81,7 @@ Caddy has **no** service-discovery story for multiple `app` replicas. Once you r
 discovers replicas from Docker labels instead of a static `reverse_proxy` target.
 
 Also set `allowedHosts` to your public hostname before exposing the edge — see
-[Reverse proxy](/docs/deployment/reverse-proxy).
+[Security](/docs/reference/security).
 
 ## What the recipe configures
 
@@ -111,8 +111,8 @@ Expected with the local CA. Install Caddy's local root for that machine, or set
 
 ## Learn more
 
-- [Reverse proxy](/docs/deployment/reverse-proxy) — Caddy / Traefik / nginx choice
-- [Docker · Reverse proxy](/docs/deployment/docker#reverse-proxy) — compose layer order
+- [Traefik](/docs/recipes/traefik) — multi-replica discovery via Docker labels
+- [nginx](/docs/recipes/nginx) — static HTTP reverse proxy
 - [Security](/docs/reference/security) — `allowedHosts`
 
 ## Next