orangecheck · Xaxis · May 20, 2026 · May 20, 2026
diff --git a/src/pages/sdk/auth-client/README.mdx b/src/pages/sdk/auth-client/README.mdx
@@ -15,6 +15,7 @@ export const metadata = {
 - [OcAccount](interfaces/OcAccount.mdx)
 - [OcAccountChipProps](interfaces/OcAccountChipProps.mdx)
 - [OcAccountPillProps](interfaces/OcAccountPillProps.mdx)
+- [OcAccountSummary](interfaces/OcAccountSummary.mdx)
 - [OcAddressInputProps](interfaces/OcAddressInputProps.mdx)
 - [OcAuthConfig](interfaces/OcAuthConfig.mdx)
 - [OcLinkedIdentitiesProps](interfaces/OcLinkedIdentitiesProps.mdx)
@@ -34,6 +35,7 @@ export const metadata = {
 
 - [DisplayIdentityKind](type-aliases/DisplayIdentityKind.mdx)
 - [OcSessionStatus](type-aliases/OcSessionStatus.mdx)
+- [OcSignOutScope](type-aliases/OcSignOutScope.mdx)
 - [WebAuthnAssertionStatus](type-aliases/WebAuthnAssertionStatus.mdx)
 - [WebAuthnListStatus](type-aliases/WebAuthnListStatus.mdx)
 - [WebAuthnRegisterResult](type-aliases/WebAuthnRegisterResult.mdx)
@@ -50,6 +52,7 @@ export const metadata = {
 
 ## Functions
 
+- [buildAddAccountUrl](functions/buildAddAccountUrl.mdx)
 - [buildSignInUrl](functions/buildSignInUrl.mdx)
 - [fetchOcLinkedIdentities](functions/fetchOcLinkedIdentities.mdx)
 - [handleSudoRequired](functions/handleSudoRequired.mdx)

diff --git a/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx b/src/pages/sdk/auth-client/functions/OcSessionProvider.mdx
@@ -15,7 +15,7 @@ export const metadata = {
 function OcSessionProvider(__namedParameters: OcSessionProviderProps): ReactElement;
 ```
 
-Defined in: [provider.tsx:102](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L102)
+Defined in: [provider.tsx:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L148)
 
 Top-level provider that exposes the cross-subdomain oc_session to every
 component below it. Mount once, near the root of your tree.

diff --git a/src/pages/sdk/auth-client/functions/OcSignIn.mdx b/src/pages/sdk/auth-client/functions/OcSignIn.mdx
@@ -15,7 +15,7 @@ export const metadata = {
 function OcSignIn(__namedParameters: OcSignInProps): ReactElement;
 ```
 
-Defined in: [signin.tsx:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L148)
+Defined in: [signin.tsx:163](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L163)
 
 ## Parameters
 

diff --git a/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx b/src/pages/sdk/auth-client/functions/buildAddAccountUrl.mdx
@@ -0,0 +1,35 @@
+export const metadata = {
+    title: "Function: buildAddAccountUrl()",
+    description: "Auto-generated API reference for Function: buildAddAccountUrl(). Source: TypeScript types in oc-packages.",
+};
+
+[**@orangecheck/auth-client**](../README.mdx)
+
+***
+
+[@orangecheck/auth-client](../README.mdx) / buildAddAccountUrl
+
+# Function: buildAddAccountUrl()
+
+```ts
+function buildAddAccountUrl(cfg: Required<OcAuthConfig>, returnTo?: string): string;
+```
+
+Defined in: [types.ts:246](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L246)
+
+Multi-account · build the URL for the "add another account" entry
+point. Same as [buildSignInUrl](buildSignInUrl.mdx) but appends `?add=1` so the
+sign-in page knows to preserve the current roster (the new account
+is appended; the previously-active account stays signed in too and
+remains switch-target reachable).
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `cfg` | `Required`\&lt;[`OcAuthConfig`](../interfaces/OcAuthConfig.mdx)\> |
+| `returnTo?` | `string` |
+
+## Returns
+
+`string`
diff --git a/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx b/src/pages/sdk/auth-client/functions/buildSignInUrl.mdx
@@ -15,7 +15,7 @@ export const metadata = {
 function buildSignInUrl(cfg: Required<OcAuthConfig>, returnTo?: string): string;
 ```
 
-Defined in: [types.ts:171](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L171)
+Defined in: [types.ts:231](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L231)
 
 ## Parameters
 

diff --git a/src/pages/sdk/auth-client/functions/useOcSession.mdx b/src/pages/sdk/auth-client/functions/useOcSession.mdx
@@ -15,7 +15,7 @@ export const metadata = {
 function useOcSession(): OcSessionState;
 ```
 
-Defined in: [provider.tsx:216](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L216)
+Defined in: [provider.tsx:339](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L339)
 
 Access the current cross-subdomain oc_session. Must be called inside
 an `<OcSessionProvider>`.

diff --git a/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx b/src/pages/sdk/auth-client/functions/useOptionalOcSession.mdx
@@ -15,7 +15,7 @@ export const metadata = {
 function useOptionalOcSession(): OcSessionState | null;
 ```
 
-Defined in: [provider.tsx:231](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L231)
+Defined in: [provider.tsx:354](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/provider.tsx#L354)
 
 Non-throwing variant — returns `null` if called outside a provider.
 Useful for libraries that want to read the session *if it exists* but

diff --git a/src/pages/sdk/auth-client/interfaces/OcAccountSummary.mdx b/src/pages/sdk/auth-client/interfaces/OcAccountSummary.mdx
@@ -0,0 +1,34 @@
+export const metadata = {
+    title: "Interface: OcAccountSummary",
+    description: "Auto-generated API reference for Interface: OcAccountSummary. Source: TypeScript types in oc-packages.",
+};
+
+[**@orangecheck/auth-client**](../README.mdx)
+
+***
+
+[@orangecheck/auth-client](../README.mdx) / OcAccountSummary
+
+# Interface: OcAccountSummary
+
+Defined in: [types.ts:115](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L115)
+
+Multi-account roster · summary of another account this browser has
+signed into and can switch to without re-authenticating. Surfaced by
+`<OcAccountMenu>` in the `§ accounts` section. Returned by the auth
+host's `/api/auth/me` as `roster: [...]` (an empty array on single-
+account or pre-multi-account sessions).
+
+Sessions for peer accounts stay alive in the auth host's DB for the
+normal 30-day window; once expired, the peer falls out of the roster
+and the user must re-authenticate to bring it back in.
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| &lt;a id="property-didoc">&lt;/a> `didOc` | `string` | - | [types.ts:116](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L116) |
+| &lt;a id="property-displayidentity">&lt;/a> `displayIdentity` | [`DisplayIdentity`](DisplayIdentity.mdx) | - | [types.ts:119](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L119) |
+| &lt;a id="property-displayname">&lt;/a> `displayName` | `string` \| `null` | - | [types.ts:117](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L117) |
+| &lt;a id="property-lastseenat">&lt;/a> `lastSeenAt` | `string` \| `null` | ISO timestamp of the last verified request on this account's session row, or null if never touched. | [types.ts:122](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L122) |
+| &lt;a id="property-primarybtc">&lt;/a> `primaryBtc` | `string` \| `null` | - | [types.ts:118](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L118) |
diff --git a/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx b/src/pages/sdk/auth-client/interfaces/OcAuthConfig.mdx
@@ -11,13 +11,13 @@ export const metadata = {
 
 # Interface: OcAuthConfig
 
-Defined in: [types.ts:126](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L126)
+Defined in: [types.ts:186](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L186)
 
 ## Properties
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| &lt;a id="property-authorigin">&lt;/a> `authOrigin?` | `string` | Origin of the auth host — the subdomain that runs the sign-in UI, issues session cookies, and exposes `/api/auth/me` + `/api/auth/logout`. Defaults to `https://ochk.io`. Override in preview/dev. | [types.ts:133](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L133) |
-| &lt;a id="property-logoutpath">&lt;/a> `logoutPath?` | `string` | Path on the auth host to hit to clear the session cookie. Defaults to `/api/auth/logout`. Called with `credentials: 'include'` so the `.ochk.io` cookie is sent along. | [types.ts:157](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L157) |
-| &lt;a id="property-mepath">&lt;/a> `mePath?` | `string` | Local path (same origin as the current app) that exposes the crypto-verified session. If your app ships one at `/api/auth/me`, leave as default. Returns 200 `{ account }` or 401. | [types.ts:151](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L151) |
-| &lt;a id="property-signinpath">&lt;/a> `signInPath?` | `string` | Path on the auth host that accepts `?return_to=<url>` and drives the sign-in flow. The page offers two paths in-place: - email + OTP (default — federation-custodied wallet provisioned for the user; identity is `did:email:<sha256(email)>`) - BIP-322 wallet sign (paste address → in-page wallet sign; identity is the Bitcoin address itself) Defaults to `/signin`. | [types.ts:145](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L145) |
+| &lt;a id="property-authorigin">&lt;/a> `authOrigin?` | `string` | Origin of the auth host — the subdomain that runs the sign-in UI, issues session cookies, and exposes `/api/auth/me` + `/api/auth/logout`. Defaults to `https://ochk.io`. Override in preview/dev. | [types.ts:193](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L193) |
+| &lt;a id="property-logoutpath">&lt;/a> `logoutPath?` | `string` | Path on the auth host to hit to clear the session cookie. Defaults to `/api/auth/logout`. Called with `credentials: 'include'` so the `.ochk.io` cookie is sent along. | [types.ts:217](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L217) |
+| &lt;a id="property-mepath">&lt;/a> `mePath?` | `string` | Local path (same origin as the current app) that exposes the crypto-verified session. If your app ships one at `/api/auth/me`, leave as default. Returns 200 `{ account }` or 401. | [types.ts:211](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L211) |
+| &lt;a id="property-signinpath">&lt;/a> `signInPath?` | `string` | Path on the auth host that accepts `?return_to=<url>` and drives the sign-in flow. The page offers two paths in-place: - email + OTP (default — federation-custodied wallet provisioned for the user; identity is `did:email:<sha256(email)>`) - BIP-322 wallet sign (paste address → in-page wallet sign; identity is the Bitcoin address itself) Defaults to `/signin`. | [types.ts:205](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L205) |
diff --git a/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx b/src/pages/sdk/auth-client/interfaces/OcSessionState.mdx
@@ -11,16 +11,19 @@ export const metadata = {
 
 # Interface: OcSessionState
 
-Defined in: [types.ts:104](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L104)
+Defined in: [types.ts:137](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L137)
 
 ## Properties
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| &lt;a id="property-account">&lt;/a> `account` | [`OcAccount`](OcAccount.mdx) \| `null` | - | [types.ts:106](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L106) |
-| &lt;a id="property-error">&lt;/a> `error` | `Error` \| `null` | `null` while loading; an `Error` instance when `status === 'error'`. | [types.ts:108](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L108) |
-| &lt;a id="property-refresh">&lt;/a> `refresh` | () => `Promise`\&lt;`void`\> | Re-fetch the session. Useful after sign-in/sign-out happens elsewhere. | [types.ts:110](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L110) |
-| &lt;a id="property-setdisplayidentity">&lt;/a> `setDisplayIdentity` | (`kind`: `"email"` \| `"btc"` \| `"did"` \| `"nostr"`) => `Promise`\&lt;`void`\> | Promote a linked identity to be the account-badge label across every `.ochk.io` site. PATCHes the auth host, which re-mints the session cookie with the new `display_identity` claim, then `refresh()`es this session. Rejects if the chosen kind is not a verified identity on the account (`btc` / `email` / `nostr` must actually be linked; `did` is always valid). | [types.ts:121](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L121) |
-| &lt;a id="property-signinurl">&lt;/a> `signInUrl` | `string` | URL to navigate to for sign-in on the auth host. | [types.ts:123](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L123) |
-| &lt;a id="property-signout">&lt;/a> `signOut` | () => `Promise`\&lt;`void`\> | Trigger a sign-out. Resolves once the cookie has been cleared. | [types.ts:112](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L112) |
-| &lt;a id="property-status">&lt;/a> `status` | [`OcSessionStatus`](../type-aliases/OcSessionStatus.mdx) | - | [types.ts:105](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L105) |
+| &lt;a id="property-account">&lt;/a> `account` | [`OcAccount`](OcAccount.mdx) \| `null` | - | [types.ts:139](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L139) |
+| &lt;a id="property-addaccounturl">&lt;/a> `addAccountUrl` | (`returnTo?`: `string`) => `string` | Multi-account · open the sign-in flow in "add" mode — the new account joins the current browser's roster instead of replacing it. Returns the URL to navigate to (so callers can mount it in a popup or hard-navigate as they prefer); pass `returnTo` to route back to a specific page after the add completes. | [types.ts:172](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L172) |
+| &lt;a id="property-error">&lt;/a> `error` | `Error` \| `null` | `null` while loading; an `Error` instance when `status === 'error'`. | [types.ts:148](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L148) |
+| &lt;a id="property-refresh">&lt;/a> `refresh` | () => `Promise`\&lt;`void`\> | Re-fetch the session. Useful after sign-in/sign-out happens elsewhere. | [types.ts:150](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L150) |
+| &lt;a id="property-roster">&lt;/a> `roster` | [`OcAccountSummary`](OcAccountSummary.mdx)[] | Multi-account · other accounts the user has signed into in this browser. `[]` for single-account sessions and for tokens minted before multi-account shipped. The active account (`account` above) is NOT included — these are the *switch targets*. | [types.ts:146](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L146) |
+| &lt;a id="property-setdisplayidentity">&lt;/a> `setDisplayIdentity` | (`kind`: `"email"` \| `"btc"` \| `"did"` \| `"nostr"`) => `Promise`\&lt;`void`\> | Promote a linked identity to be the account-badge label across every `.ochk.io` site. PATCHes the auth host, which re-mints the session cookie with the new `display_identity` claim, then `refresh()`es this session. Rejects if the chosen kind is not a verified identity on the account (`btc` / `email` / `nostr` must actually be linked; `did` is always valid). | [types.ts:181](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L181) |
+| &lt;a id="property-signinurl">&lt;/a> `signInUrl` | `string` | URL to navigate to for sign-in on the auth host. | [types.ts:183](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L183) |
+| &lt;a id="property-signout">&lt;/a> `signOut` | (`opts?`: \&#123; `scope?`: [`OcSignOutScope`](../type-aliases/OcSignOutScope.mdx); \&#125;) => `Promise`\&lt;`void`\> | Trigger a sign-out. By default signs out of EVERY account in the roster (back-compat); pass `{ scope: 'current' }` to sign out of just the active account and stay logged into the next peer. | [types.ts:156](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L156) |
+| &lt;a id="property-status">&lt;/a> `status` | [`OcSessionStatus`](../type-aliases/OcSessionStatus.mdx) | - | [types.ts:138](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L138) |
+| &lt;a id="property-switchaccount">&lt;/a> `switchAccount` | (`didOc`: `string`) => `Promise`\&lt;`void`\> | Multi-account · flip the active session to a different account in the roster. Resolves once the new cookie has been set and the session has been re-fetched. Throws if the target `did_oc` isn't in the current roster (the user must add it via addAccount first) or if the auth host is unreachable. | [types.ts:164](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/types.ts#L164) |
diff --git a/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx b/src/pages/sdk/auth-client/interfaces/OcSignInProps.mdx
@@ -17,9 +17,10 @@ Defined in: [signin.tsx:42](https://github.com/orangecheck/oc-packages/blob/main
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
+| &lt;a id="property-add">&lt;/a> `add?` | `boolean` | Multi-account · when `true`, the sign-in is performed in "add" mode: the resulting session is appended to the browser's existing roster instead of replacing it. The previously-active account stays signed in and remains a switch target on the auth host. Off by default (back-compat). The component also reads `?add=1` from the URL search params and treats it the same — so the auth host's `/signin?add=1` entry point Just Works without any extra prop. The `add` flag is forwarded as a body field to the host's `/api/auth/signin` and `/api/auth/email-otp/verify`; if the host hasn't deployed the multi-account migration yet it silently ignores the field and the call falls back to ordinary signin. | [signin.tsx:119](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L119) |
 | &lt;a id="property-audience">&lt;/a> `audience` | `string` | Consumer-site audience URL passed as `expectedAudience` on the BIP-322 challenge. e.g. `'https://vault.ochk.io'`. Required — the challenge nonce is bound to this audience. | [signin.tsx:48](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L48) |
 | &lt;a id="property-authorigin">&lt;/a> `authOrigin?` | `string` | Override the auth host. Defaults to `'https://ochk.io'`. For preview / dev / staging only. | [signin.tsx:82](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L82) |
-| &lt;a id="property-classname">&lt;/a> `className?` | `string` | className for the outer container. | [signin.tsx:106](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L106) |
+| &lt;a id="property-classname">&lt;/a> `className?` | `string` | className for the outer container. | [signin.tsx:121](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L121) |
 | &lt;a id="property-initialpath">&lt;/a> `initialPath?` | `"wallet"` \| `"email"` | Initial visible tab on mobile. Defaults to `'wallet'`. On desktop both paths render side-by-side and this is ignored. | [signin.tsx:87](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L87) |
 | &lt;a id="property-linkprompt">&lt;/a> `linkPrompt?` | `boolean` | Whether to show the "also link my other identity" checkbox on the sign-in form. **On by default.** The checkbox is optional and unchecked by default; it is shown on both the wallet and email paths. If the user ticks it, the complementary identity's link ceremony (BIP-322 for a wallet, OTP for an email) runs inline immediately after a successful sign-in — before `onSuccess` / `returnTo`, so it composes with custom routing — because the sign-in just proved one credential and the link ceremony proves the second. Pass `linkPrompt={false}` to omit the checkbox. | [signin.tsx:104](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L104) |
 | &lt;a id="property-onsuccess">&lt;/a> `onSuccess?` | (`account`: [`OcAccount`](OcAccount.mdx), `token?`: `string`) => `void` | Override the default hard-navigation behavior. When provided, called with the account and the session JWT. The component will NOT navigate — the caller is responsible. Use for custom post-signin routing — e.g. /popup/signin postMessages `{ account, token }` to its opener so a cross-domain integrator (different eTLD+1 from .ochk.io, which the HttpOnly cookie can't reach) can verify the session via JWKS. | [signin.tsx:64](https://github.com/orangecheck/oc-packages/blob/main/auth-client/src/signin.tsx#L64) |