@buildbase/sdk 0.0.88 → 0.0.90

package/AGENTS.md

@@ -33,6 +33,8 @@ Cloud `serverUrl` is `https://api.console.buildbase.app`; a self-hosted stack us
 
 In an existing Next.js, Vite or Express app: `npm install @buildbase/sdk && npx buildbase init --org-id <24 hex>`. It writes the provider, the auth routes, a webhook route that switches on `payment.failed`, and `.env.example` / `.env.local` placeholders (secrets always empty), wraps the root layout, and is idempotent: a second run says "already configured" and changes nothing. Non-interactive runs need `--framework` for an empty directory and `--org-id` always. Secrets are never flags.
 
+Moving users in from Clerk, Auth0, Firebase or Supabase: `npx buildbase import --from <source> <file> [--passwords <file>] [--overwrite] [--dry-run]` with `BUILDBASE_API_TOKEN` and `BUILDBASE_SERVER_URL`, as for `content pull`. It converts the vendor's own export and posts batches of 500 to `POST /api/users/import`. Firebase's hash parameters are flags; pass the signer key as `BUILDBASE_FIREBASE_SIGNER_KEY` rather than `--signer-key` to keep it out of shell history. Vendor steps: `docs/USER-IMPORT.md`.
+
 ## Client setup (React)
 
 ```tsx
@@ -91,7 +93,7 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 - **Factory:** `BuildBase` (also default export) → `{ auth, workspace, subscription, usage, credits, plans, invoices, users, features, settings, notification, permissions, withSession, client }`.
 - **API classes:** `BaseApi` (extend for custom APIs), `AuthApi`, `UserApi`, `WorkspaceApi`, `SettingsApi`, `PushApi`.
 - **Webhook verification (runtime-agnostic — Node, edge, Deno, Bun, browsers):** `verifyWebhookSignature`, `parseWebhookEvent`. Verify against the **raw** request body (`await req.text()`), not the parsed JSON. Headers: `x-buildbase-signature` (`sha256=` HMAC over `{timestamp}.{body}`), `x-buildbase-timestamp` (Unix seconds), `x-buildbase-event`.
-- **Webhook events:** `WEBHOOK_EVENTS` (112 `domain.action` names), `WEBHOOK_EVENTS_BY_CATEGORY`, `WebhookEventName`, `isWebhookEvent(name)`, vendored from the platform catalog. A failed payment is `payment.failed`, with `workspaceId, subscriptionId, invoiceId, dunningState, amount, currency, failedAt, nextRetryAt`. Full list: https://docs.buildbase.app/webhooks/overview. Never invent an event name; narrow with `isWebhookEvent` instead.
+- **Webhook events:** `WEBHOOK_EVENTS` (129 `domain.action` names; payload types `UserDeletionWebhookData`, `UserRegisteredWebhookData`), `WEBHOOK_EVENTS_BY_CATEGORY`, `WebhookEventName`, `isWebhookEvent(name)`, vendored from the platform catalog. A failed payment is `payment.failed`, with `workspaceId, subscriptionId, invoiceId, dunningState, amount, currency, failedAt, nextRetryAt`. Full list: https://docs.buildbase.app/webhooks/overview. Never invent an event name; narrow with `isWebhookEvent` instead.
 - **Agent readiness (framework-agnostic, returns plain `DiscoveryDocument`):** **App owns discovery content, platform owns auth.** All content — `llms.txt`, `robots.txt`, `sitemap`, `protectedResources` (RFC 9728), API catalog, skills — is defined locally in `AgentReadyConfig` and served with no platform round-trip. The platform bundle (`fetchAgentReadiness`, fail-soft/cached) supplies ONLY `{ enabled, authorizationServer }` (the OAuth AS pointer). Functions: `resolveAgentPath` (dispatch ALL agent paths — root docs + `.well-known/*`; prefer for new wiring), `resolveWellKnown` (`.well-known/*` only), `clearAgentReadinessCache`, `buildAgentCard`, `buildA2AAgentCard` (A2A card at `/.well-known/agent-card.json`; served by DEFAULT, derived from `site`+`skills`; `a2aCard: false` disables, object overrides), `buildProtectedResourceMetadata(path, config)` (local), `buildAgentSkillsIndex`, `buildSkillMd`, `buildSecurityTxt`, `buildLlmsTxt(config)` (from `config.llmsTxt`), `buildLlmsFullTxt` (from `config.llmsFullTxt`), `buildRobotsTxt`, `buildSitemap`, `buildApiCatalog`, `buildMcpServerCard`, `buildAuthMd`, `buildWebBotAuthDirectory` (JWKS at `/.well-known/http-message-signatures-directory` from `config.webBotAuth.keys`; opt-in), `buildDnsAidRecords` (suggested `_agents` DNS records — publish at your DNS provider, can't be served over HTTP), `buildDiscoveryLinkHeader`, `wantsMarkdown`/`negotiateMarkdown`, `sha256Digest`, `AI_BOT_USER_AGENTS`, `DISCOVERY_CACHE_TIMEOUT_MS`. `config.extraPaths` serves ANY literal document by exact path (commerce discovery: x402/UCP/ACP/MPP, `/openapi.json`, future `.well-known` docs) and takes precedence over built-ins. `config.cache` (a `DiscoveryCacheStore`: string `get`/`set`, optional `delete`) shares the platform fetches across replicas instead of caching per process; the default is process memory. Types: `AgentReadyConfig`, `AgentReadinessBundle`, `AgentSkill`, `DiscoveryCacheStore`, `ApiCatalogApi`, `A2ACardConfig`, `A2ACardSkill`, `DnsAidRecord`, `McpServerCard`, `RobotsConfig`, `RobotsPolicy`, `ContentSignals`, `SitemapUrl`, `DiscoveryDocument`.
 - **OAuth2 app-bridge:** `handleAppTokenRequest`, `handleAppRevokeRequest` (one-call handlers), `bearerChallenge` (RFC 9728/6750 401; header values are quoted-string-escaped + CR/LF-stripped), `verifyAppTokenRequest`, `verifyAppRevokeRequest`, `verifyClientJwt`, `signClientJwt` (HS256 mint — symmetric counterpart of verify), `extractBearerToken`, `appTokenSuccess`, `appTokenFailure`, `AppBridgeError`. Types: `AppTokenRequestClaims`, `AppRevokeRequestClaims`, `AppTokenResult`, `AppTokenResponseBody`, `HandlerResult`, `VerifyClientJwtOptions`. `verifyClientJwt(token, secret, opts?: VerifyClientJwtOptions)` **requires a numeric `exp` by default** (`requireExp: false` to allow non-expiring tokens); optional `clockToleranceSec` / `issuer` / `audience`. **Presets** (also in core): `mintAgentToken` (the whole mint in one call — HS256 with the app's secret, `aud` from the grant's resource, encrypted `sid`) + `buildbaseAuth` (the whole verify) + `createSessionRefCrypto`. Security invariant: the platform relays the minted token but never sees the app secret — it can neither forge nor decode app tokens, and the BuildBase session is never stored and never plaintext in a token.
 - **Currency & pricing utils (pure):** `formatCents`, `formatOverageRate`, `formatOverageRateWithLabel`, `formatQuotaIncludedOverage`, `formatQuotaWithPrice`, `getCurrencySymbol`, `getCurrencyFlag`, `getQuotaUnitLabelFromName`, `getQuotaDisplayValue`, `CURRENCY_DISPLAY`, `CURRENCY_FLAG`, `PLAN_CURRENCY_CODES`, `PLAN_CURRENCY_OPTIONS`.
@@ -99,6 +101,7 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 - **Seat pricing:** `calculateBillableSeats`, `calculateSeatOverageCents`, `calculateTotalSubscriptionCents`, `getPerSeatPriceCents`, `getSeatPricing`.
 - **RBAC (pure):** `hasPermission`, `resolvePermissions`, `resolveMaxUsers`, `validateInvite`, `DEFAULT_ROLE_PERMISSIONS`, `Permission` (enum).
 - **URL / auth-intent / redirects:** `BB_PARAM`, `BBAction`, `BBScreen`, `BBStatus`, `createBBUrl`, `readBBParams`, `cleanBBParams`, `createCheckoutRedirectUrls`, `createCreditPurchaseRedirectUrls`, `safeRedirect`, `validateRedirectUrl`, `saveAuthIntent`, `consumeAuthIntent`, `clearAuthIntent`.
+- **Account (pure):** `isReauthRequired(error)` (a `403 reauth_required`: re-confirm with `useSaaSAuth().requireReverification`, never sign out), `isReadOnlySession(error)` (an owner's read-only session), `isImpersonationSignInLocked(error)` (a sign-in change refused while an owner is signed in as the user), `isValidUsername`, `normaliseUsername`, `connectWallet(chain, { api })` (injected `window.ethereum` / `window.solana`, then `WorkspaceApi.linkWallet`), `buildWalletMessage` (EIP-4361 from the nonce answer), `toChecksumAddress` (EIP-55), `WalletFlowError`, `WALLET_LINK_STATEMENT`.
 - **Context invalidation (call after server mutations to refetch client contexts):** `invalidateSubscription`, `invalidateQuotaUsage`, `invalidateCreditBalance`.
 - **Regional resolution (server-side, for apps hosting many orgs):** `resolveServerUrl({ orgId, centralUrl, apiKey, cache? })` asks central which cell an organisation lives in and caches the answer for central's own `max-age`; `clearResolvedServerUrl({ orgId, centralUrl, cache? })` forgets it, which is the documented recovery from a `421 misdirected_request`. Types: `RegionAnswer`, `ResolveServerUrlOptions`, `ResolveCacheStore`. Throws on failure rather than falling back to the default cell, because that fallback would send an EU organisation's request to the US. **Pass `apiKey`**: without it central answers the default cell for every id, known or not, on purpose (organisation ids are ObjectIds, so a distinguishable 404 would be an enumeration oracle).
 - **Events:** `EventEmitter`, `eventEmitter` (singleton), `SDKEvent` (enum).
@@ -111,7 +114,7 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
 ### `@buildbase/sdk/react` — client-only additions (core is re-exported here too)
 
 - **Providers:** `SaaSOSProvider` (root), `SubscriptionContextProvider`, `QuotaUsageContextProvider`, `CreditBalanceContextProvider`, `PushNotificationProvider`.
-- **State hooks:** `useSaaSAuth`, `useSaaSWorkspaces`, `useSaaSOs` (exposes `region` when the app passes it to `SaaSOSProvider`; informational, for badges and support tooling), `useSaaSSettings`, `useUserAttributes`, `useUserFeatures`, `useTranslation`, `usePermissions`, `useSeatStatus`, `useTrialStatus`, `useFullScreenLoader`, `useMyInvitations`, `useWorkspaceInvitations`, `useNotifications`.
+- **State hooks:** `useSaaSAuth` (incl. `requireReverification({ returnUrl?, factors?, maxAgeSeconds? })` for a `reauth_required` refusal), `useGuestUpgrade`, `useSaaSWorkspaces`, `useSaaSOs` (exposes `region` when the app passes it to `SaaSOSProvider`; informational, for badges and support tooling), `useSaaSSettings`, `useUserAttributes`, `useUserFeatures`, `useTranslation`, `usePermissions`, `useSeatStatus`, `useTrialStatus`, `useFullScreenLoader`, `useMyInvitations`, `useWorkspaceInvitations`, `useNotifications`.
 - **Upload hooks:** `useUpload(purpose)` (`{ upload, cancel, loading, error, failure, enabled, maxBytes, maxLabel }`; reads the org's upload settings, refuses a file over its limit before a request, `error` is translated into the active locale and `failure` is the reason; a new upload, `cancel()` or unmount aborts the one in flight), `useUploadsApi`.
 - **Subscription/billing hooks:** `usePublicPlans`, `useSubscription`, `useSubscriptionContext`, `useSubscriptionManagement`, `usePlanGroup`, `usePlanGroupVersions`, `usePublicPlanGroupVersion`, `useCreateCheckoutSession`, `useUpdateSubscription`, `useCancelSubscription`, `useResumeSubscription`, `useBillingPortal`, `useInvoices`, `useInvoice`.
 - **Quota hooks:** `useQuotaUsageContext`, `useRecordUsage`, `useQuotaUsageStatus`, `useAllQuotaUsage`, `useUsageLogs`.
@@ -126,7 +129,7 @@ Config also accepts: `timeout`, `maxRetries`, `debug`, `headers`, `onError(err,
   - Quota: `WhenQuotaAvailable`, `WhenQuotaExhausted`, `WhenQuotaOverage`, `WhenQuotaThreshold`
   - Credits: `WhenCreditsAvailable`, `WhenCreditsExhausted`, `WhenCreditsLow`
   - Invitations: `WhenPendingInvitations`
-- **UI components:** `WorkspaceSwitcher`, `PricingPage`, `CreditStorePage`, `CreditBalance`, `CreditActionsProvider`, `BetaForm`, `FullScreenLoader`, `PendingInvitations`, `NotificationBell`, `NotificationInbox`.
+- **UI components:** `WorkspaceSwitcher`, `PricingPage`, `CreditStorePage`, `CreditBalance`, `CreditActionsProvider`, `BetaForm`, `FullScreenLoader`, `PendingInvitations`, `NotificationBell`, `NotificationInbox`, `GuestUpgrade` (a guest's "Create your account"), `ImpersonationBanner` (the provider pins it while an owner views as the user; `ui.impersonationBanner: false` hides that one).
 - **Misc:** `SUPPORTED_LOCALES`, `SETTINGS_SCREENS`, `SettingsScreen`, `workspaceSettingsManager`.
 
 ### `@buildbase/sdk/data`
@@ -170,6 +173,7 @@ Expose a live MCP server (stateless Streamable HTTP; Node 18+/edge) with built-i
 - **Agent-readiness fetches are fail-soft** — a platform outage yields `{ enabled: false }`, never a 500. Don't add your own error handling expecting throws.
 - **New crypto is dependency-free pure JS** (`src/lib/sha256.ts`) so it behaves identically on browser/edge/Node — don't swap in Web Crypto / Node `crypto` without matching outputs.
 - **Prefer SDK hooks** (`useSaaS*`, `useSubscription*`, etc.) over `useAppSelector`/internal context so consumer code stays stable across internal refactors.
+- **Status colours have two theme tokens each.** `--destructive`, `--success`, `--warning` and `--info` are fills (buttons, tints, progress bars, borders); their text (`text-destructive` and so on) reads `--destructive-text`, `--success-text`, `--warning-text` and `--info-text`. When rebranding one, set both, in the light rule and the dark one (`docs/THEMING.md`).
 - **Pass `idempotencyKey` on `usage.record`, `usage.recordBatch` and `credits.consume`.** It is optional in the type and should be treated as required in anything that meters or spends. The SDK retries only idempotent requests, so a `POST` that fails mid-flight is not retried for you: the caller retries, and without a key the second attempt bills twice. Use a key derived from the unit of work (`gen-<requestId>`, `email-<messageId>`), not a fresh UUID per attempt. This matters more against a load-balanced API with several replicas than against one server, because a retry landing on a different replica is the normal case.
 - **`serverUrl` must be the organisation's REGIONAL URL.** Today every organisation is on the default cell, `https://api.console.buildbase.app`; an organisation in another region uses the URL central answers for it, never a guessed hostname. There is no auto-discovery in the client bundle and there will not be: resolving in the browser costs a round trip before the first API call on every page load. An app serving one organisation bakes the URL into the build; one serving many resolves per request on the server with `resolveServerUrl`. Sending an organisation's request to the wrong cell returns `421 misdirected_request` with the right `serverUrl`, never a silent cross-region read - treat it as the signal to re-resolve once.
 - **The MCP server card and protected-resource metadata advertise the regional endpoint.** `createAgentStack` derives both from `serverUrl`, so getting `serverUrl` right is the whole of it; there is nothing extra to configure per cell. An agent that discovered a US endpoint for an EU organisation would authenticate against the wrong cell and be refused by the audience check.

package/CHANGELOG.md

@@ -5,6 +5,521 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.90] - 2026-10-18
+
+### Added
+
+- **Change password on the Security screen.** New `WorkspaceApi.changePassword()` takes the
+  current and the new password and posts them to the tenant server's new
+  `POST /api/v1/public/profile/password`. The Security screen gains a Password section above
+  passkeys: both fields, a pending button, and the server's own sentence on a refusal (a wrong
+  current password, which counts toward the account's sign-in lockout, or a password found in a
+  known breach). On success every other session for the user ends and this one stays. Hide the
+  section with `ui.settings.security.password: false` for an app without password sign-in. New
+  strings under `security.*` in all eight locales. Needs a tenant server with
+  `POST /api/v1/public/profile/password`; an older server answers 404, which the section shows
+  as an error.
+- **Two-step sign-in on the Security screen.** Five new `WorkspaceApi` calls against the tenant
+  server's session routes under `/api/v1/public/mfa`: `getMfaStatus()`, `startTotpEnrollment()`,
+  `confirmTotpEnrollment(code)`, `disableTotp(code)` and `regenerateBackupCodes(code)`. The
+  Security screen gains a two-step sign-in section between Password and Passkeys. Setting it up
+  shows the QR code the server rendered (as an image, never as markup), the key in groups of four
+  for an app that cannot scan, and a field for the first code; the backup codes then appear once,
+  with a copy button, until the user presses Done. Once it is on, the section says how many backup
+  codes are left and offers New backup codes and Turn off, each of which asks for a current code
+  or a backup code first, because a wrong one counts toward the account's lockout. Turn off is not
+  offered while the app requires two-step sign-in, and the section says why instead. Every write
+  is a POST, so the client never retries one: a code works once, so replaying a request that went
+  through would only be refused. A refusal shows the server's own sentence, and the
+  error carries its `reason` as `code` (`MfaErrorCode`, listed in `docs/ERROR_CODES.md`). The
+  section hides itself while the organization has two-step sign-in off and against a server that
+  predates it, except right after a setup the server refused because it was turned off while the
+  screen was open: then it stays, with that sentence and no actions, so the user learns why. Hide
+  it outright with `ui.settings.security.twoStep: false`. New types `IMfaStatus`,
+  `ITotpEnrollment`, `IMfaBackupCodes`, `MfaEnforcement`, `MfaFactorType` and `MfaErrorCode`, and
+  new strings under `security.twoStep*` in all eight locales. Needs a tenant server with two-step
+  sign-in.
+- **Four webhook events from two-step sign-in.** The vendored catalog is refreshed from the
+  platform's and now holds 117 names, up from 113: `user.mfa_enrolled`, `user.mfa_disabled` and
+  `user.mfa_reset_by_admin` (an admin removed the second step for a lost device), plus
+  `auth.login_failed`, sent when a sign-in is refused for a wrong password or a wrong second-step
+  code. A failed sign-in names the user it was attempted against, and an unknown address sends
+  nothing. `isWebhookEvent` accepts all four and `WebhookEventName` includes them. Because the
+  platform declares `auth.login_failed` beside the user events, the `Auth` group in
+  `WEBHOOK_EVENTS_BY_CATEGORY` now comes second, straight after `User`, and starts with it.
+- **`useSaaSAuth().user.mfaEnabled`.** The profile now says whether the user has an authenticator
+  app set up, typed as `IUser.mfaEnabled`, and the session user carries it. It reads `false`
+  against a server that predates two-step sign-in. Turning two-step sign-in on or off on the
+  Security screen updates the session user in place, so an app's own "turn on two-step sign-in"
+  prompt goes away without a reload.
+- **Change email on the Profile screen.** Two new `WorkspaceApi` calls beside `changePassword`:
+  `requestEmailChange(newEmail)` posts to `POST /api/v1/public/profile/email`, which sends a
+  6-digit code to the new address and resolves with `retryAfter`, the seconds before another code
+  can be sent; `confirmEmailChange(code)` posts to `POST /api/v1/public/profile/email/confirm` and
+  resolves with the new `email`. The address changes only when the code is accepted; it is then
+  verified, the old address gets a notice, and every session stays signed in. The Profile screen
+  shows a Change action next to the email: the new address, then "We sent a code to ..." with a
+  field for the code, Resend (counting down from `retryAfter`) and Cancel. On success the field
+  shows the new address and `useSaaSAuth().user.email` updates in place. Both calls are POSTs and
+  never retried, since a replay would send a second code or spend one of the code's tries. Codes
+  are sent with spaces dropped. A refusal shows the server's own sentence, and the error carries
+  its `reason` as `code` (`EmailChangeErrorCode`: `email_unavailable`, `linked_social_account`,
+  `cooldown` with `retryAfter`, `disposable_email`, `invalid_code`, `code_expired`, listed in
+  `docs/ERROR_CODES.md`). An expired code is a 410, and does not sign the user out; any 401
+  still does. The profile gains `canChangeEmail` and `changeEmailBlockedBy` (typed on `IUser`,
+  and carried on the session user as `useSaaSAuth().user.canChangeEmail` and
+  `.changeEmailBlockedBy`): the change is offered only while `canChangeEmail` is true, and
+  otherwise the email is shown read-only, with one sentence when `changeEmailBlockedBy` says why. A server that
+  predates them reads as `canChangeEmail: false`, so the change is never offered against it. Hide it with
+  `ui.settings.profile.changeEmail: false`. New types `IEmailChangeRequest`,
+  `IEmailChangeResult`, `EmailChangeErrorCode` and `ChangeEmailBlockedBy`, and new strings under
+  `profile.changeEmail*` in all eight locales. Needs a tenant server that can change an email
+  with a code.
+- **`BaseApi`: a route's own 401.** `fetchResponse(path, init, options)` takes an optional
+  `IRequestOptions`; with `deferUnauthorized: true` a 401 is left to the caller instead of calling
+  `onUnauthorized`, and the new protected `notifyUnauthorized()` ends the session for a 401 that
+  turns out to be the session's after all. For a custom API class whose route answers 401 for a
+  refusal of its own; nothing changes for any existing call.
+- **Two webhook events for email changes and bot protection.** The vendored catalog is refreshed from the platform's and
+  now holds 119 names, up from 117: `user.email_changed`, sent when a user changes their email
+  with a code and carrying `actorId`, `userId`, `oldEmail` and `newEmail`, and
+  `auth.signup_challenged`, sent when bot protection refuses a sign-up or an emailed code or link
+  (it names the surface, never the address typed). `isWebhookEvent` accepts both and
+  `WebhookEventName` includes them. `user.email_changed` comes last in the `User` group and
+  `auth.signup_challenged` second in `Auth`, after `auth.login_failed`, as the platform declares
+  them.
+- **Connected accounts on the Security screen.** Three new `WorkspaceApi` calls against the tenant
+  server's session routes under `/api/v1/public/accounts`:
+  `getConnectedAccounts()` resolves the user's linked social sign-ins (`accounts`, each with
+  `canUnlink`), the ones the app offers that they have not linked (`available`, each with its
+  `methodId`), `signInWays` and `recentSignIn`; `linkAccount(methodId, redirect)` resolves the
+  `{ url }` to send the browser to; `unlinkAccount(id)` removes one. The Security screen gains a
+  Connected accounts section between two-step sign-in and passkeys: each linked account with its
+  icon, label and date, and Remove behind a confirmation; a Connect button per available provider,
+  which comes back to the same page with the Security screen open (`?bb=screen:security`), where
+  the outcome is shown once and the `linked`, `error` and `reason` parameters are taken off the URL
+  with `history.replaceState`, keeping the router's state. Remove is disabled, with the reason
+  beside it, on the only way the user can sign in. A remove refused with `reauth_required` says the
+  user must sign in again and offers Sign in again, which signs out, signs in and returns to the
+  Security screen. Refusals keep the server's sentence and carry `status` and the server's reason
+  as `code` (`ConnectedAccountErrorCode`: `reauth_required` 403, `last_sign_in_method` 409,
+  `already_linked` 409, `method_unavailable` 404, listed in `docs/ERROR_CODES.md`); none of them
+  signs the user out, only a real 401 does. Starting a link is a POST and never retried. Every
+  button shows progress, and the section loads behind the screen's one skeleton; it hides while
+  there is nothing to list or connect, against a server that predates it (404, not reported), and
+  with `ui.settings.security.connectedAccounts: false`. New types `IConnectedAccounts`,
+  `IConnectedAccount`, `IAvailableAccountProvider`, `IAccountLinkStart`,
+  `ConnectedAccountErrorCode` and `AccountLinkErrorReason`, `BBScreen.Security`, and new strings
+  under `security.connectedAccounts*` in all eight locales.
+- **`useSaaSAuth().user.externalId`.** The profile carries the user's id in the system they were
+  imported from, typed as `IUser.externalId`, and the session user has it when it is set.
+- **`buildbase import`.** `npx buildbase import --from clerk|auth0|firebase|supabase <file>` reads
+  the vendor's own user export (CSV, JSON or NDJSON, gzipped or not), converts each user to the
+  platform's import lines (email, verified status, name, the old id as `externalId`, a password
+  hash the platform can check, and Google, GitHub, Microsoft, Apple and LinkedIn sign-ins as links)
+  and posts them in batches of 500 as a multipart `file` upload to `POST /api/users/import`, with
+  `source` set to the vendor, using `BUILDBASE_API_TOKEN` and `BUILDBASE_SERVER_URL` as
+  `content pull` does. It prints the totals, the platform's notices once, every failed row and
+  every warning, numbered by the user's place in the export. Options: `--passwords <file>`
+  (Auth0's hash export from a support request, or Clerk's dashboard CSV beside Backend API JSON),
+  `--overwrite`, `--dry-run` (convert and print the first users with hashes redacted, send
+  nothing), `--server-url`, and for Firebase `--signer-key` (or `BUILDBASE_FIREBASE_SIGNER_KEY`),
+  `--salt-separator`, `--rounds` and `--mem-cost`. bcrypt, argon2id, argon2i, Django
+  pbkdf2_sha256 and Firebase scrypt hashes are imported, Clerk's `pbkdf2_sha256` and
+  `scrypt_firebase` digests rewritten into the platform's shapes; any other hasher imports that
+  user without a password, with a warning. A plaintext password is never sent: the record is
+  listed as failed with `plaintext_password`. Sign-ins with providers the platform does not have
+  are dropped with a warning. Each vendor's export steps are in the new `docs/USER-IMPORT.md`.
+- **Three webhook events for imports and connected accounts.** `user.imported` (carrying `actorId`, `userId`, `email`,
+  `name`, `externalId` and `source`, sent instead of `user.registered` for an imported user),
+  `user.account_linked` and `user.account_unlinked` (carrying `actorId`, `userId`, `provider` and
+  `accountId`). The vendored catalog holds 122 names, up from 119, with the three at the end of
+  the `User` group; `isWebhookEvent` accepts them and `WebhookEventName` includes them.
+- **Phone number on the Security screen.** Three new `WorkspaceApi` calls beside the change of
+  email: `addPhone(phone, channel?)` posts an E.164 number
+  to `POST /api/v1/public/profile/phone`, which sends a code to it and resolves with `retryAfter`;
+  `confirmPhone(code)` posts to `POST /api/v1/public/profile/phone/confirm` and resolves with the
+  number, now on the account and verified; `removePhone()` is `DELETE /api/v1/public/profile/phone`.
+  `channel` asks for WhatsApp or a voice call where the app offers them, and without it the code
+  is a text message. The Security screen gains a Phone number section between Password and two-step
+  sign-in: a country picker (every country with its calling code, named in the reader's language)
+  and the number as it is written there, or with a leading `+`; then "We sent a code to ..." with a
+  code field, Resend counting down from `retryAfter`, and Cancel. Once added, it shows the number
+  as verified or not, with Verify for one that came without proof (an import), Change, and Remove
+  behind a confirmation. Remove needs a recent sign-in: on `reauth_required` the section says so
+  and offers Sign in again, as connected accounts does. It is disabled, with the reason beside it,
+  while text message codes for two-step sign-in go to the number, and `last_sign_in_method` and
+  `mfa_sms_enrolled` are answered in the screen's own words; every other refusal shows the server's
+  sentence. The section loads behind the screen's one skeleton, hides against a server that
+  predates phone numbers, and hides with `ui.settings.security.phone: false`. Adding or removing a
+  number reloads the connected accounts, since a verified phone is a way to sign in.
+- **Text message codes for two-step sign-in.** `getMfaStatus()` now carries
+  `sms: { allowed, enrolled, phone? }` (the number masked, `+1 ••• ••• 0123`), typed as
+  `IMfaSmsStatus`, and `MfaFactorType` gains `sms`. Three new `WorkspaceApi` calls:
+  `startSmsEnrollment()` (`POST /api/v1/public/mfa/sms/enroll`) sends a code to the verified phone
+  and resolves with `retryAfter`; `confirmSmsEnrollment(code)` (`.../enroll/confirm`) turns it on
+  and resolves with backup codes when the server issues them; `disableSms()`
+  (`POST /api/v1/public/mfa/sms/disable`) turns it off. The two-step section offers Text message
+  beside the authenticator app while the app allows it, labelled as less secure than an
+  authenticator app. Turning it on needs a verified phone: the section says so and points to the
+  Phone number section when it knows there is none, and on `phone_required`. Then comes the code,
+  with Resend counting down. Turning it off sits behind a confirmation and needs a recent sign-in,
+  with Sign in again on `reauth_required`. Someone who has it on still sees it after the app stops
+  offering it, so they can turn it off. Neither factor offers Turn off while the app requires two-step
+  sign-in and it is the user's only second step. The authenticator app now shows as a row with Set
+  up when it is not set up, to sit beside the text message row. `useSaaSAuth().user.mfaEnabled` is
+  kept true while either factor is on.
+- **Phone refusals.** Every refusal from the six phone calls keeps the server's sentence and
+  carries `status` and the server's reason as `code` (`PhoneErrorCode`: `invalid_phone`,
+  `phone_unavailable`, `cooldown` with `retryAfter`, `rate_limited`, `number_refused`,
+  `sms_unavailable`, `invalid_code`, `code_expired`, `reauth_required`, `last_sign_in_method`,
+  `mfa_sms_enrolled`, `phone_required`, `factor_not_allowed`, listed in `docs/ERROR_CODES.md`).
+  None of them signs the user out: an expired code is a 410 and a stale session's refusal a 403.
+  Only a real 401 does. The POSTs are never retried, since a replay would send a second text or
+  spend one of the code's tries. Codes are sent with spaces dropped. New types `PhoneChannel`,
+  `IPhoneCodeSent`, `IPhoneConfirmed`, `ISmsEnrollmentResult`, `IMfaSmsStatus` and
+  `PhoneErrorCode`, and new strings under `security.phone*` and `security.twoStepSms*` in all
+  eight locales.
+- **`useSaaSAuth().user.phone` and `.phoneVerified`.** The profile carries the user's phone as
+  E.164 and whether it was verified, typed on `IUser`; the session user has both while there is a
+  number, and the Security screen keeps them current when the user adds, verifies or removes it.
+- **Four webhook events for phone numbers and phone codes.** `user.phone_added` (`actorId`, `userId`, `phone`,
+  `verified`; on a phone sign-up, from the profile, or on an import), `user.phone_verified` and
+  `user.phone_removed` (`actorId`, `userId`, `phone`) close the `User` group, and
+  `auth.sms_budget_exceeded` (`level` of `warning` or `stopped`, `sent`, `dailyCap`, `alertAt`; at
+  most once a day each, as phone codes near or reach the app's daily cap) follows
+  `auth.signup_challenged` in `Auth`. The vendored catalog holds 126 names, up from 122;
+  `isWebhookEvent` accepts the four and `WebhookEventName` includes them.
+- **`buildbase import` carries phone numbers.** Each line gains `phone` (E.164) and
+  `phoneVerified` where the export has them: Clerk's Backend API `phone_numbers[]` (the primary
+  one, verified when its `verification.status` is `verified`), Clerk's CSV
+  `primary_phone_number`, `verified_phone_numbers` and `unverified_phone_numbers`, Auth0's
+  `phone_number` and `phone_verified`, Firebase's `phoneNumber` (verified, since Firebase sets it
+  through phone sign-in), and Supabase's `phone` (stored without its `+`, which is added back) and
+  `phone_confirmed_at`. A value that is not E.164 is left out with an `invalid_phone` warning and
+  the user is imported without it; the server does the same, with a warning, for a number already
+  on another account. `docs/USER-IMPORT.md` has the field list per vendor, and the Auth0 export job
+  and the Supabase query now ask for the phone fields.
+- **Confirm it's you before a sensitive change.** Any session route may now answer
+  `403 reauth_required` with `maxAgeSeconds` and, when it wants the second step too,
+  `factors: ['mfa']`; the SDK error carries both. New `useSaaSAuth().requireReverification({
+returnUrl?, factors?, maxAgeSeconds? })` sends the person to the hosted sign-in page through
+  `WorkspaceApi.startReverification({ returnUrl, factors })` (`POST /api/v1/public/session/reverify`)
+  and back to `returnUrl` (default: this page) with the same session, now recent: no new session
+  and no code. The server takes a return URL only when it is one of the auth client's redirect
+  URLs, so when it refuses the page with `invalid_return_url` the SDK comes back through the
+  registered `auth.redirectUrl` and continues to the page, as it does after signing in. With
+  `maxAgeSeconds` it resolves `'recent'` without leaving when the session already is. The provider
+  takes `?reverified=1` off the URL without a reload. Every Security section that offered Sign in
+  again on `reauth_required` now offers **Confirm it's you**, says once on the way back that the
+  change can go ahead, and falls back to signing out and in only where the session cannot be
+  re-confirmed (never for a guest). `useSaaSAuth().session` carries `authTime`, `amr` and
+  `impersonation` from the profile. New pure helpers `isReauthRequired(error)` and
+  `isReadOnlySession(error)`.
+- **Delete my account.** `WorkspaceApi.requestAccountDeletion()` (`POST /api/v1/public/account/delete`)
+  resolves `{ deleteAfter, deleted }`: the account is deleted after the app's grace period, every
+  other session ends now, and an app with no grace period deletes at once (`deleted: true`).
+  `cancelAccountDeletion()` (`POST /account/delete/cancel`) resolves `{ cancelled }`. Refusals:
+  `reauth_required` and `owns_workspaces` (409, carrying `workspaces: [{ id, name }]`). The Security
+  screen ends with a **Delete account** section behind a typed confirmation (the word in the
+  reader's language, or `DELETE`); its warning names the app's grace period, or says the account
+  goes at once, from `AuthApi.getAccountDeletionGraceDays(orgId)` (the public auth config); it names
+  the workspaces that block it, offers Confirm it's you, signs out when the account went at once,
+  and while a deletion is scheduled shows its date with **Cancel deletion**. `IUser.deleteAfter` and `useSaaSAuth().user.deleteAfter` carry the date.
+  Hide the section with `ui.settings.security.deleteAccount: false`.
+- **An app owner viewing as a user.** The profile carries `impersonation: { actorName, readOnly,
+expiresAt }` while an owner is signed in as the person from the console. The provider pins
+  `<ImpersonationBanner />` to the bottom of the window for as long as it lasts ("You are viewing
+  as Ada. Grace signed in as this person, read-only until 3:15 PM.", with Exit); hide it with
+  `ui.impersonationBanner: false` and place it yourself with `fixed={false}`. Every change in a
+  read-only session is refused with `403 read_only_session`, whose sentence the screens show; the
+  Profile save and the passkey actions now show a refusal instead of only reporting it.
+- **Usernames.** `WorkspaceApi.setUsername(username)` (`PUT /api/v1/public/profile/username`)
+  resolves the stored name and `removeUsername()` is the `DELETE`; refusals `invalid_username`,
+  `username_taken`, `usernames_off` and `username_required`. `AuthApi.getUsernamePolicy(orgId)`
+  reads `username: { enabled, required }` from the public auth config. The Profile screen shows a
+  Username field while the app has them on or the user has one, checked first by the server's own
+  rules (`isValidUsername`, `normaliseUsername`: 3 to 30 of `a-z 0-9 _ . -`, letter or digit at
+  both ends, no `..`, no reserved word), with Remove unless the app requires one. Hide it with
+  `ui.settings.profile.username: false`. `useSaaSAuth().user.username` carries it.
+- **Guests who create an account.** A guest has `isAnonymous: true`; `useSaaSAuth().user` reads
+  their placeholder `@anonymous.invalid` address as an empty `email`, so it is never shown or sent
+  to tracking. `WorkspaceApi.requestGuestUpgrade({ email, name?, password? })`
+  (`POST /api/v1/public/guest/upgrade`) mails a 6-digit code and resolves `retryAfter`;
+  `confirmGuestUpgrade(code)` (`/guest/upgrade/confirm`) resolves the profile, the same user id now
+  a real account. New `useGuestUpgrade()` hook and `<GuestUpgrade />` component ("Create your
+  account": the address, an optional name and password, then the code with Resend counting down);
+  `useSaaSAuth().user` is the account as soon as the code is accepted. For a guest, the Profile
+  screen shows it in place of the email, and the Security screen in place of the password, phone,
+  two-step and passkey sections; Connect a wallet is not offered to a guest.
+- **Wallets in connected accounts.** `getConnectedAccounts()` rows may be `ethereum` or `solana`
+  wallets with their short address as `detail`, and the view carries `wallet: { ethereumChainIds,
+solana }` while the app offers wallet sign-in. `WorkspaceApi.requestWalletNonce(chain)` and
+  `linkWallet({ chain, message, signature })` (`POST /api/v1/public/accounts/wallet/nonce` and
+  `/accounts/wallet`) connect one; `nonce_expired` is a 401 that does not sign the user out. New
+  dependency-free `connectWallet(chain, { api })` drives an injected wallet (EIP-1193
+  `window.ethereum`, moving it to a network the app takes; Phantom-style `window.solana`) and
+  `buildWalletMessage()` lays out the EIP-4361 message from the nonce answer's `domain`, `uri`,
+  `nonce` and `issuedAt`, with the EIP-55 address (`toChecksumAddress`, on a pure keccak-256).
+  The Security screen offers **Connect an Ethereum wallet** and **Connect a Solana wallet**, says
+  in its own words when the wallet stopped it (`WalletFlowError`: none in the browser, cancelled,
+  busy, wrong network), and shows wallets with their address. Hide only that with
+  `ui.settings.security.wallets: false`.
+- **The sign-in page in the app's language.** `signIn()` sends `locale` to
+  `POST /api/v1/auth/request` (the new `auth.locale`, else the provider's `locale`, narrowed to the
+  eight), so the hosted page opens in it; with neither it is left out and the page goes by the
+  person's own choice and browser. Dropped, like the tracking fields, for a server that refuses it.
+- **Custom claims, device code and three webhook events.** `IUser.claims` and
+  `useSaaSAuth().user.claims` carry the owner's custom claims (`{}` when none);
+  `AppTokenRequestClaims` gains `claims` and `grantType: 'device_code'`. `user.deletion_scheduled`,
+  `user.deletion_cancelled` and `user.deleted` close the `User` group: 129 names, up from 126. New
+  payload types `UserDeletionWebhookData` (`userId`, `by: 'self' | 'admin' | 'guest_expired'`,
+  `deleteAfter`) and `UserRegisteredWebhookData` (with `fromGuest`). Strings for all of the above
+  in all eight locales; `EmailChangeErrorCode` gains `guest_account`.
+- **A scheduled account deletion shows on every settings screen.** While
+  `useSaaSAuth().user.deleteAfter` is set, the workspace settings dialog says "Your account will
+  be deleted on {date}." at the top of every screen, outside the screen's own scroll, with
+  **Cancel deletion**. Until now the date showed only at the foot of the Security screen. Cancel
+  posts to `POST /api/v1/public/account/delete/cancel`, shows progress on the button, then says
+  the account will not be deleted; a refusal, such as `read_only_session` while an app owner views
+  the account read-only, keeps the notice and shows the server's sentence under it. The date comes
+  from the session, so the notice makes no request, and is formatted with `ui.formats.date` (long
+  by default), as in the Delete account section. The Security screen keeps its date in the session
+  too, so a deletion scheduled or cancelled in either place shows in the other at once, and
+  opening the Security screen brings the session's date up to date with the profile. Hidden with
+  the section by `ui.settings.security.deleteAccount: false`. New string
+  `security.deleteAccountNotice` in all eight locales.
+- **`StatusBanner` `actionProgress`.** Shows the action button as pending, with a spinner, and
+  disables it while true.
+- **Plain-language help on the Account, Security and Devices screens.** A small "?" beside a
+  title or label opens a short note on a tap, a click or the keyboard (never on hover alone), and
+  Escape closes only the note. It explains two-step sign-in and authenticator apps, backup codes,
+  passkeys, the password rules, the phone number, connected accounts, "Confirm it's you", the
+  account deletion grace period, the email address and each device and session action, using
+  only the methods the app offers. `SectionHeader` gains a `help` slot. New strings under `help.*`
+  in all eight locales (written by a non-native speaker in es, fr, de, ja, zh, hi and ar; they
+  need a native check). The help button is internal and not exported.
+- **Sign-in changes locked while an owner is signed in as the user.** The server now refuses a
+  change to how the person signs in (email, phone, username, password, second step, passkeys,
+  linked accounts, guest upgrade) during any session opened from the console as them, read-only
+  or not, with 403 `impersonation_sign_in_locked` and the sentence "You are signed in as this
+  person from the console, so how they sign in can't be changed here." `SessionRefusalCode`
+  gains the code, new pure helper `isImpersonationSignInLocked(error)` (core and `/react`) beside
+  `isReadOnlySession`, and `docs/ERROR_CODES.md` lists it. The screens show the server's sentence,
+  as they do for `read_only_session`, and never ask to confirm it's you or sign out over it. In a
+  full-access session `ImpersonationBanner` adds a line under "Changes are saved to their account":
+  "How they sign in can't be changed." New string `security.impersonationSignInLocked` in all eight
+  locales (written by a non-native speaker in es, fr, de, ja, zh, hi and ar; they need a native
+  check).
+- ⚠️ **Passkey refusals carry their reason (behaviour change).** `renamePasskey()` and
+  `deletePasskey()` now carry the server's `reason` as `code`, as the other sign-in changes do,
+  so `isReadOnlySession`, `isReauthRequired` and `isImpersonationSignInLocked` recognise a
+  refused passkey change; they had only the sentence and `status`. Like those, a refusal is no
+  longer passed to the `onError` config callback.
+
+### Changed
+
+- **The Password section knows who has no password.** `IUser` gains `passwordSet` and
+  `passwordSignIn` from `GET /api/v1/public/profile`. Someone who signed up through a provider, a
+  wallet, or a code or link is no longer asked for a current password they never had: the section
+  says they sign in without one and, where the app offers password sign-in, to sign out and use
+  Forgot password? on the sign-in page. Where it does not, the section is left out. Against a
+  server without the fields the form stays, with a hint that now covers codes and links too.
+  `changePassword()` carries the server's `reason` as `code` (new `PasswordChangeErrorCode`:
+  `password_not_set`, `invalid`, `locked`); on `password_not_set` the form goes and the server's
+  sentence stays.
+- **Two-step sign-in while the app has it off.** An authenticator app the user set up stays in
+  view, with Remove, instead of the whole section disappearing; nothing new is offered, and New
+  backup codes is not, since nothing asks for them while it is off. One set up before the app
+  stopped allowing authenticator apps stays in view too.
+- **Copy.** No em-dashes in any catalog string, nor in the agent card, `llms.txt` and `robots.txt`
+  bodies or the MCP tool errors. Banner titles read Done and Something went wrong;
+  `errors.unauthorized` says the session has ended. The passkey hint says when the sign-in page
+  actually offers one. The account-deletion refusal names what clears the way (remove the other
+  members and cancel the subscription, or delete the workspace) instead of a handover nothing can
+  do, and takes `count`. The general deletion warning gives the range (at once, or up to 30 days).
+  The username rule says letters a to z.
+- **The lockout sentence.** On a `locked` 429 from `changePassword()` the server now says "Too
+  many failed attempts. Wait up to 15 minutes and try again, or reset your password." The SDK
+  shows it as sent and goes by `code`, never by the words, so nothing else changes. The docs for
+  `locked` now say a password reset lifts it, as the window passing does.
+- **`buildbase import` names LinkedIn in the caveat.** LinkedIn's OpenID Connect user id is
+  scoped to the app, as Microsoft's is to the app registration and Apple's to the team, so an
+  export with a LinkedIn sign-in now gets a note that an imported LinkedIn link matches only the
+  same LinkedIn app. `PER_REGISTRATION_NOTES` gains `linkedIn`, word for word the tenant server's
+  new `notices` sentence; a dry run prints it, and a run that sends prints the server's. Against
+  an older server a sending run prints no LinkedIn note, since the server's notices replace the
+  command's own.
+- ⚠️ **`StatusBanner` `message` takes a node.** `StatusBannerProps['message']` is now
+  `React.ReactNode` (was `string`), so a message can carry its own semantics, such as the code
+  cooldown's `role="timer"`. Passing a string works as before; code that reads the prop's type as
+  `string` needs widening.
+
+### Fixed
+
+- **A failed account link always says why, and leaves the address clean.** Coming back from
+  connecting a provider on the Security screen, the server sends `?error=...&reason=...`, and the
+  screen knew four reasons. The tenant server's social callback sends eight more on that path:
+  `no_verified_email` (a provider account with no verified address, as GitHub's can be), and for a
+  guest, who becomes the account they connect, `email_unverified`, `email_unavailable`,
+  `disposable_email`, `signup_closed`, `signup_restricted`, `waitlist_required` and `not_a_guest`.
+  For those the screen said nothing and `error` and `reason` stayed on the URL. Each now shows its
+  own sentence in the user's language and the parameters come off the URL without a reload.
+  ⚠️ Type change: `AccountLinkErrorReason` gains the eight reasons, so an exhaustive `switch` or
+  `Record<AccountLinkErrorReason, ...>` over it needs the new members. New strings
+  `security.connectedAccountsNoVerifiedEmail`, `connectedAccountsEmailUnverified`,
+  `connectedAccountsEmailUnavailable`, `connectedAccountsDisposableEmail`,
+  `connectedAccountsSignupClosed`, `connectedAccountsSignupRestricted`,
+  `connectedAccountsWaitlistRequired` and `connectedAccountsNotAGuest` in all eight locales
+  (written by a model in es, fr, de, ja, zh, hi and ar, for a native reader to check).
+- **A guest refused two-step sign-in is told so in their language.** The tenant server refuses a
+  guest's authenticator app and text message codes with `guest_account` (409). `MfaErrorCode`
+  gains `guest_account` (⚠️ type change, as above), and the two-step section shows
+  `security.twoStepGuest` ("Create your account before setting up two-step sign-in.", all eight
+  locales, model-written outside English) instead of the server's English.
+- **"The server could not be reached" instead of the browser's English.** A call the API never
+  answered showed what the browser said ("Failed to fetch", "Load failed", "NetworkError when
+  attempting to fetch resource.") or the API layer's own English ("Failed to change password (502:
+  Bad Gateway)" for a proxy's error page), and `useGuestUpgrade` fell back to a hard-coded
+  "Request failed". The Security screen (password, two-step sign-in, passkeys, phone number,
+  connected accounts, deleting the account), Confirm it's you, the scheduled-deletion notice, the
+  account screen's email change, username and save, and the guest upgrade now say "The server
+  could not be reached. Check your connection and try again." (new `errors.unreachable`, all eight
+  locales, model-written outside English). The API layer marks such an error (a network failure, a
+  timeout, or a response that is not the API's JSON, which keeps its `status`) without changing
+  its shape; a refusal the server wrote keeps its sentence. `GuestUpgradeFailure` gains an
+  optional `unreachable: true`, and `useGuestUpgrade().error.message` is always a sentence to
+  show.
+- **The phone number field reads every keyboard's digits.** The Security screen's phone input
+  refused a number typed in Arabic-Indic, Devanagari or full-width digits, with a full-width plus,
+  or pasted with invisible direction marks (Android wraps a copied number in two; the screen's own
+  display of a number adds two more, so a number copied from the screen could not be pasted
+  back). `toE164` now reads those digits as ASCII and drops the invisible marks, as the server's
+  parser already does, before it composes the E.164 number. A letter, an extension or a second
+  plus is still refused.
+- **Disconnecting an agent asks first.** The Connected agents screen disconnected an agent on the
+  first press. It now asks, as removing a device does ("Disconnect Acme Assistant? It loses access
+  to your account at once. You can connect it again at any time.", Cancel / Disconnect), shows the
+  row as pending while it runs, and says "Acme Assistant was disconnected." once it is. New strings
+  `security.connectedAgentsConfirmTitle`, `connectedAgentsConfirmBody`, `connectedAgentsCancel`
+  and `connectedAgentsDisconnected` in all eight locales (written by a non-native speaker in es,
+  fr, de, ja, zh, hi and ar; they need a native check). `useConnectedAgents().revoke()` now
+  resolves `true` or `false` (was `void`), so a custom list can tell the outcome.
+- **A new authenticator app says "Added: today".** Right after set-up the two-step row said "Last
+  used: today": the screen stamped the last use with the set-up time, and the server stamps the
+  confirming code as a use too. The confirming code is no longer counted: the row says Added
+  until a code passes at least a minute after the set-up, then Last used.
+- **`buildbase` help and import output say one thing once.** `buildbase import --help` (and
+  `init --help`, `content pull --help`) prints that command's usage and options only, where it
+  printed all three commands'; a parse error shows the usage of the command it was for, and
+  `buildbase --help` is the overview. A record the import leaves out before sending (deleted
+  upstream, no email) is listed under "Not sent" in a real run as in a dry run, matching the
+  totals' "not sent", where the real run listed it under "Failed" with the server's refusals.
+  The Microsoft and Apple caveat is the platform's own sentences, one per provider present, in
+  a dry run as in a real run, where the dry run had a wording of its own.
+- **Confirm it's you no longer ends an owner's view as the user.** The server answers
+  `reverify_unavailable` to a re-confirm inside a session an app owner opened as the user from the
+  console, with a sentence that says to sign out and sign in again, and the Security screen did
+  exactly that, ending the owner's session as the user. It now stays signed in and says "You are
+  signed in as this person from the console, so you can't confirm it's them here. Only they can
+  make this change." New string `security.reauthImpersonating` in all eight locales (written by a
+  non-native speaker in es, fr, de, ja, zh, hi and ar; they need a native check).
+- **A failed profile load no longer shows a skeleton for ever.** The Account screen says the
+  profile could not be loaded, with Retry, and says the same after a failed Reset. New string
+  `profile.loadFailed` in all eight locales.
+- **Phone refusals in the Security screen's own words.** `sms_unavailable` said to try another way
+  to sign in, and `method_unavailable` to choose a text message; both now read as this screen
+  should. `PhoneErrorCode` gains `method_unavailable`.
+- **The phone country picker has an accessible name.** `CommandSelect` takes `aria-labelledby`
+  (read with the selected option) and `aria-label`.
+- **The Profile screen's pickers have accessible names.** Language, Country, Currency and
+  Timezone each name their combobox by the visible label above it, read with the selected option
+  ("Country, Germany"), where a screen reader heard only the value. `SelectCountry`,
+  `SelectCurrency`, `SelectLanguage` and `SelectTimeZone` pass `aria-labelledby` and `aria-label`
+  through to `CommandSelect`.
+- **"Add and verify a phone number first" goes once the phone is verified.** After Turn on for
+  text message codes with no verified phone, the two-step section kept saying so after the number
+  had been verified a few lines above. It now goes as soon as the phone number section changes
+  the phone; Turn on says it again if it still holds.
+- **One error at a time when changing the password.** A refusal from the server ("Current
+  password is incorrect.") stayed on screen beside a newer error of the form's own ("Use at least
+  8 characters."). It now goes as soon as either field is edited, or when the form's own check
+  finds something newer. A success stays.
+- **A code cooldown is a wait, not an error.** Asking for a code inside the server's resend
+  window, as when the number is changed right after adding it, showed "Something went wrong" over
+  the server's static "Wait 29 seconds before asking for another code." The phone number and
+  two-step sections now show a neutral notice that counts down ("A code was sent moments ago. You
+  can send another in 17 seconds."), inside `role="timer"` so a screen reader does not read out
+  every second, and goes at zero, when Send code (or Turn on) is offered again. New string
+  `security.phoneWait` in all eight locales.
+- **The confirm-it's-you banners say confirm it's you.** On an old sign-in, removing the phone,
+  turning off text message codes and removing a connected account said to sign in again, while
+  the only button is Confirm it's you and nobody is signed out. `security.phoneReauth`,
+  `security.twoStepSmsReauth` and `security.connectedAccountsReauth` now read as the delete
+  account banner does ("For your security, confirm it's you before removing your phone number."),
+  in all eight locales.
+- **Phone numbers grouped for reading.** A North American number (+1) shows as "+1 415 555 5829"
+  rather than "+1 4155555829": on the phone row, in the remove confirmation and in the sent and
+  verified messages. Other countries keep the national number in one block, since grouping them
+  needs libphonenumber's per-country rules, which the SDK does not carry. The number kept and sent
+  is still E.164.
+- **Contrast on the settings sidebar.** The group labels (Account, Workspace) and the workspace id
+  were `muted-foreground` on the `muted` sidebar, 4.3:1 with the default tokens, under the 4.5:1
+  small text needs. They are now `foreground` at 70% (7.5:1 light, 7.6:1 dark), so a theme still
+  recolours them; no token changed. `SidebarNavSection` labels change with them.
+- ⚠️ **Status colours reach WCAG AA in every use (visual change).** Each of `--destructive`,
+  `--success`, `--warning` and `--info` was both a fill and every text in its colour, and no single
+  value does every job. With the defaults, red text was 3.3:1 on the error banner and 3.8:1 on the
+  page, the label on a Delete button 3.6:1, red text in dark mode (Sign out) 2.0:1, and a red
+  progress bar or focus ring in dark mode 2.0:1 against the page (1.5:1 on the seat bar's muted
+  track). Success and warning text was 4.4:1 on their banners and 3.2:1 on the banner hint lines,
+  their hovered buttons 4.2:1, and the softer warning usage bar 2.6:1 against its track; info hint
+  lines were 3.9:1 (3.7:1 dark), info text on the dark sidebar 3.3:1 and a hovered info button in
+  dark mode 4.1:1. Small text needs 4.5:1; a bar, a focus ring or a state border 3:1.
+  - New text tones `--destructive-text` (light `0 72% 36%`, dark `0 91% 71%`), `--success-text`
+    (`142 72% 19%`, `142 69% 58%`), `--warning-text` (`26 90% 24%`, `38 92% 60%`) and
+    `--info-text` (`224 76% 38%`, `217 91% 78%`). `tailwind.config.js` points every
+    `text-<status>` at its tone; `bg-`, `border-` and `ring-<status>` stay on the fill.
+  - New fill defaults: light `--destructive` `0 72% 45%` (was `0 84.2% 60.2%`), `--success`
+    `142 72% 26%` (was `142 72% 29%`) and `--warning` `26 90% 33%` (was `26 90% 37%`); dark
+    `--destructive` `0 72% 47%` (was `0 62.8% 30.6%`; white text on it is 5.2:1) and `--info`
+    `217 91% 66%` (was `217 91% 60%`).
+  - The seat bar on the members screen is drawn as the usage bars are, on a 15% tint of its own
+    colour, and its card is no longer muted; the softer usage bar (75 to 90% used) is
+    `bg-warning/80` (was `/70`).
+  - What changes on screen: status text is darker in light mode (success and warning close to
+    the 800 and 900 shades), warning and info text lighter in dark mode, light success, warning
+    and red fills darker, and the dark red fill brighter.
+  - Now at least 4.7:1 for every status text use and every label on a fill (hovered too) and 3.4:1
+    for every bar, ring and state border, light and dark; the table is in `docs/THEMING.md`.
+  - A theme that sets only a fill keeps its fills, and its text takes the SDK's tone, which reads
+    at 4.5:1 on the tints of any colour within 30 degrees of the shipped hue that meets the fill's
+    own uses; set `--<status>-text` too, light and dark, for text in your own hue.
+    `src/styles/theme-contrast.test.ts` measures every use of every status colour on the built
+    CSS, light and dark, and sweeps those fills.
+- **The error boundary's fallback takes the SDK theme.** `SaaSOSProvider` renders it outside
+  every `.saas-os-ui` root, so it read the host page's own `--destructive`, in a shadcn app the
+  same red that fails as text. It now carries the class, gets the SDK's tokens and an app's
+  overrides of them, and colours its text with `--destructive-text`.
+- ⚠️ **`createWorkspace()` honours `ui.behavior.autoOpenPlanDialog: false` (behaviour change).**
+  It opened Plan & Billing on the new workspace 300 ms later whatever the app said:
+  `UIConfigProvider` sat inside `WorkspaceProvider`, so the workspace actions only ever saw an
+  empty config. `UIConfigProvider` now wraps `WorkspaceProvider` (the checkout and permission
+  config providers moved outside it too; neither reads it), and `createWorkspace()` opens
+  nothing when `autoOpenPlanDialog` is `false` or `ui.settings.sections.subscription` is `false`
+  (the dialog cannot show a hidden screen and fell back to Profile). With neither set it opens
+  Plan & Billing as before.
+
+## [0.0.89] - 2026-10-18
+
+### Added
+
+- `email.complained` in `WEBHOOK_EVENTS` (now 113 names): the platform fires it
+  when a recipient reports a message as spam. Before, a complaint arrived as
+  `email.bounced`; a handler that caught complaints there should switch on
+  `email.complained` too. The payload is the same as `email.bounced`
+  (`trackingCode`, `recipientEmail`, `emailHistoryId`, `audienceId`, `subject`).
+
 ## [0.0.88] - 2026-10-18
 
 ### Changed