@capxul/sdk-react 0.2.0-alpha.4 → 0.2.0-alpha.5

package/package.json

@@ -1,92 +1,54 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "0.2.0-alpha.4",
-  "description": "React provider + hooks for the @capxul/sdk headless client.",
-  "license": "UNLICENSED",
-  "private": false,
-  "type": "module",
-  "homepage": "https://capxul.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Xelmar-tech/Capxul.git",
-    "directory": "packages/sdk-react"
-  },
-  "bugs": {
-    "url": "https://github.com/Xelmar-tech/Capxul/issues"
-  },
-  "author": "Capxul (Xelmar Tech Ltd.)",
-  "keywords": [
-    "capxul",
-    "sdk",
-    "react",
-    "hooks",
-    "stablecoin",
-    "payments",
-    "typescript"
+  "version": "0.2.0-alpha.5",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
   ],
+  "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    },
-    "./proof": {
-      "types": "./dist/proof/index.d.ts",
-      "import": "./dist/proof/index.js",
-      "require": "./dist/proof/index.cjs"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "0.2.0-alpha.4"
-  },
-  "peerDependencies": {
-    "@tanstack/react-query": "^5",
-    "@xstate/react": "^5",
-    "convex": ">=1.0.0",
-    "react": ">=18.2.0 <20",
-    "viem": ">=2.0.0"
+    "@capxul/config": "0.0.0",
+    "@capxul/sdk": "0.2.0-alpha.5",
+    "@capxul/types": "0.0.0"
   },
   "devDependencies": {
-    "@tanstack/react-query": "^5",
+    "@tanstack/react-query": "^5.66.9",
+    "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
-    "@xstate/react": "^5",
-    "@types/node": "^22.15.3",
-    "@types/react": "19.2.2",
-    "@types/react-dom": "19.2.3",
-    "jsdom": "^29.0.1",
-    "react": "19.2.5",
-    "react-dom": "19.2.5",
-    "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
-    "typescript": "5.9.2",
-    "viem": "2.47.10",
-    "vitest": "^4.1.2",
-    "@repo/config": "0.0.0",
-    "@repo/observability": "0.0.0",
-    "@repo/platform-kernel": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@types/jsdom": "^28.0.3",
+    "@types/react": "^19.2.15",
+    "@types/react-test-renderer": "^19.1.0",
+    "@vitest/coverage-v8": "4.1.7",
+    "ink": "^7.0.3",
+    "ink-testing-library": "^4.0.0",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-test-renderer": "^19.2.6",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.23"
   },
-  "scripts": {
-    "build": "tsup",
-    "check-types": "tsc --noEmit",
-    "proof:contract": "vitest run ops/proof/sdk-contract.test.ts",
-    "proof:drift": "vitest run ops/proof/reset-contract-drift.test.ts",
-    "proof:evidence": "tsx ops/proof/evidence-cli.ts",
-    "proof:plan": "tsx ops/proof/plan-cli.ts",
-    "proof:react-headless": "vitest run ops/proof/react-headless.test.tsx",
-    "test": "vitest run",
-    "test:types": "vitest run --typecheck"
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.66.9",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
   },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts"
+  "scripts": {
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint -c ../../.oxlintrc.json . --deny-warnings",
+    "build": "vp pack",
+    "_vp-tasks-allowed": "vp-allowed: `test` + `test:coverage` are vp tasks in vite.config.ts so vitest self-writes don't bust cache (#205).",
+    "test:e2e": "vp test run --config vitest.e2e.config.ts"
+  }
 }

package/CHANGELOG.md

@@ -1,304 +0,0 @@
-# @capxul/sdk-react
-
-## 0.2.0-alpha.4
-
-### Minor Changes
-
-- b6c1f94: Complete the auth dogfooding epic around the canonical auth surface.
-
-  The SDK now carries the guarded OTP proof path, bootstrap continuation states,
-  canonical auth service behavior, and final funnel proof support needed for
-  first-run auth dogfooding. The React SDK aligns its auth hooks and provider
-  state with that canonical flow, including signout cleanup, bootstrap-required
-  continuations, and funnel telemetry integration.
-
-### Patch Changes
-
-- 50d3c55: Bundle the internal Safe derivation package into the SDK artifact instead of
-  publishing it as a runtime dependency, and add a packaging guard that fails when
-  publishable packages leak private `@repo/*` runtime dependencies.
-- Updated dependencies [b6c1f94]
-- Updated dependencies [50d3c55]
-  - @capxul/sdk@0.2.0-alpha.4
-
-## 0.2.0-alpha.3
-
-### Patch Changes
-
-- Updated dependencies [5b99a9b]
-  - @capxul/sdk@0.2.0-alpha.3
-
-## 0.2.0-alpha.2
-
-### Minor Changes
-
-- 995383f: Epic 660: Unified auth surface
-  - Introduces AuthService promise-based auth API replacing the imperative capxul.auth.\* tuple interface
-  - Adds SignerProvisioner for deterministic Safe v1.4.1 address derivation from viem signers
-  - Adds useAuth() React hook with reactive state + promise-based methods
-  - Deprecates useAuthFlow and useAuthBootstrapFlow in favor of useAuth()
-  - Migrates reference CLI auth commands (send-otp, verify-otp, signout) to useAuth()
-  - Migrates test surfaces: walkthroughs, type tests, e2e harness signup, lazy-dx provider
-  - Adds @repo/safe-derive workspace package for Safe address derivation utilities
-  - Aligns CapxulConfig.data to \_data with internal SDK transport ownership (Epic 652)
-  - Pins esbuild to 0.25.12 to fix binary-version skew in fresh worktrees
-
-- 2ef4ee3: Reshape the organizations members surface around a single Membership entity
-  with a status lifecycle (`pending | active | revoked | expired`).
-  - Replaces the prior invitation/membership split (which produced a phantom
-    `MemberInvitation` type that never compiled) with a single `Member` type
-    exposing `status`, `email`, `acceptedAt`, `expiresAt`, and `resentCount`.
-  - New methods on `organizations.members.*`: `accept(token)`, `revoke(memberId)`,
-    `resend(memberId)`. `invite()` now returns a `MemberInviteResponse`
-    containing the raw invite token (returned once).
-  - Auto-accepts pending invitations on first sign-in for the matching email
-    via a BetterAuth post-signup hook.
-  - Nightly Convex cron expires overdue pending invitations.
-
-  Public type changes:
-  - Removed: `MemberInvitation` (was never exported; type didn't compile).
-  - Added: `MembershipStatus`, `MemberInviteResponse`.
-  - Updated: `Member` shape — see SDK reference for the full delta.
-
-  React hooks:
-  - New: `useAcceptInvitation`, `useRevokeMember`, `useResendInvitation`.
-  - Updated: `useInviteMember` returns `MemberInviteResponse` (was returning a
-    type that didn't exist).
-
-  Reference CLI:
-  - New commands: `org members invite`, `org members list`, `org members retrieve`,
-    `org members accept`, `org members updateRole`, `org members revoke`,
-    `org members remove`, `org members resend`.
-
-- c7146bf: **Transport ownership (#656):** The SDK now owns construction of the
-  authenticated `ConvexHttpClient`. Consumers no longer wire `data` manually
-  or provide `auth.createDataClient`. After `verifyOtp` exchanges a Convex
-  JWT, the SDK builds the default data client internally via
-  `createDefaultDataClient` and stores it on `config._data`.
-  - `CapxulConfig.data` renamed to `_data` (internal test seam).
-  - `CapxulAuthConfig.createDataClient` removed from public types.
-  - `convex` moved from `peerDependencies` to `dependencies`.
-
-### Patch Changes
-
-- d252aa7: Widen the published React peer dependency to `>=18.2.0 <20` so React 18 consumers, including the Ink reference proof app, can install the alpha SDK without peer conflicts.
-- Updated dependencies [995383f]
-- Updated dependencies [2ef4ee3]
-- Updated dependencies [c7146bf]
-  - @capxul/sdk@0.2.0-alpha.2
-
-## 0.2.0-alpha.1
-
-### Minor Changes
-
-- **Transport ownership (#656):** Remove the `auth.createDataClient`
-  callback from `CapxulProvider`. The React provider now passes its
-  singleton data client via `CapxulConfig._data` and lets the SDK own
-  runtime construction after OTP verification.
-
-### Patch Changes
-
-- Updated dependencies
-  - @capxul/sdk@0.2.0-alpha.1
-
-## 0.1.0-alpha.12
-
-### Minor Changes
-
-- Publish the post-alpha.11 SDK and React SDK surface: funds v1 sub-account
-  runtime coverage, React hook wiring, payments list support, and the latest
-  generated Convex API snapshots used by current alpha consumers.
-
-  Note: alpha.10 and alpha.11 were intermediate runner artifacts from the
-  prior release pipeline (manual `package.json` bumps that were never folded
-  back into the repo). alpha.12 reconciles `package.json`, the changesets
-  state, and npm to a single consistent version.
-
-### Patch Changes
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.12
-
-## 0.1.0-alpha.9
-
-### Minor Changes
-
-- Add the canonical auth bootstrap flow.
-
-  `verifyOtp()` now resolves a verified email session into either an
-  `existing_member` identity or a `bootstrap_required` continuation. New and
-  incomplete members continue through `completeBootstrap()`, which validates a
-  server-issued bootstrap token, claims the username, provisions the account/Safe
-  through the backend bootstrap path, and returns the authenticated product
-  identity. The React SDK adds `useAuthBootstrapFlow()` as the typed first-run
-  flow wrapper.
-
-### Patch Changes
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.9
-
-## 0.1.0-alpha.8
-
-### Minor Changes
-
-- 3af04a9: Public `<CapxulProvider>` now wires authenticated Convex reads end-to-end (#487, closes #484).
-
-  The `build-time-urls` arm of `BrowserCapxulConfig` now causes the provider to internally instantiate a `ConvexReactClient`, wrap it as a `CapxulDataClient`, and feed it as `config.data` into `createCapxulClient`. The existing `auth.createDataClient` callback is wired to the same singleton so a `verifyOtp` call refreshes the data client's auth header without churning the WebSocket. The provider also wraps `client.auth.signOut` so the data client survives sign-out — post-signout reads return typed backend `NOT_AUTHENTICATED` instead of the SDK's `NOT_IMPLEMENTED` stub (closes the #474 friction as a side-effect).
-
-  New optional `sessionStore?: AuthSessionStore` prop lets browser apps opt into `localStorage`-backed persistence and Node consumers (CLIs, e2e harnesses) opt into file-backed persistence. Defaults to in-memory.
-
-  This closes the architectural gap that made the React hook surface (`useMe`, `useAccount`, `useSafe`, ...) impossible to exercise end-to-end through the public provider — previously `config.data` was never populated, so every authenticated read short-circuited to `NOT_IMPLEMENTED`. The Ink reference CLI (`apps/reference-cli/`) is rebuilt on top of the public provider as proof: 17/17 agent-driver assertions pass against live alpha-3 Convex, including a dev-OTP authenticated round-trip that mints a real session via `AUTH_DEV_OTP=00000` and exercises three distinct hook end-states (`NOT_AUTHENTICATED`, `PROFILE_NOT_FOUND`, post-signout `NOT_AUTHENTICATED`).
-
-- 57203a4: Withdrawals v1 W2 (#465) — public surface tightening + org-scope create
-  - `WithdrawalsCreateInput.destination` no longer accepts `kind`. The
-    backend now resolves the `external_account` row by FK and infers
-    the kind + rail server-side. Anything that doesn't route to
-    `chain_wallet` (or is chain_wallet but non-EVM in slice 1) returns
-    `VERIFICATION_REQUIRED` with `details.rail` + `details.currentKind`.
-  - `organizations.withdrawals.create` is now a real mutation (no
-    longer a `NOT_IMPLEMENTED` stub). Returns the `processing` row
-    only — Safe + Zodiac submission orchestration ships in W3+.
-  - `Errors.verificationRequired({ rail, currentKind })` factory
-    added; the `VERIFICATION_REQUIRED` code now broadens to cover
-    both KYC tier gates and unsupported withdrawal rails.
-
-  **Migration:** Remove `destination.kind` from any
-  `capxul.withdrawals.create({ destination: { kind, externalAccountId } })`
-  call sites. Pass only `externalAccountId`.
-
-### Patch Changes
-
-- Updated dependencies [57203a4]
-  - @capxul/sdk@0.1.0-alpha.8
-
-## 0.1.0-alpha.4
-
-### Minor Changes
-
-- Post-alpha hardening — WAVE 1 + WAVE 2 cumulative
-
-  **WAVE 1 (merged 2026-05-03 12:44Z):**
-  - S2 story 1: wire onboarding readback hooks (#469) — `me.update`, `accounts.retrieve`, `accounts.update`, `useAccount`, `useSafe`
-  - S3 phase 1: Ink reference CLI scaffold + `auth+me` end-to-end against live alpha-3 Convex (#470). Stickiness gate (D3) fired.
-  - S5: split `CapxulProvider` into public single-input `BrowserCapxulConfig` + test-only `CapxulTestProvider` from `@capxul/sdk-react/proof` (#473). Q1 lock honored. 7 type-level provider-shape guards including `@ts-expect-error` against test-provider leaking to public barrel.
-
-  **WAVE 2 (merged 2026-05-03 12:54-13:16Z):**
-  - S3 phase 2: per-domain CLI commands closing #458 (#476) — `account retrieve/update`, `safe retrieve`, `payment retrieve`, `withdrawal retrieve/list`. 12/12 agent-driver tests pass.
-  - S2 story 2: `capxul.tokenTransfers.*` non-canonical SDK namespace (#479) — Option A per #477 (canon-aligned `transfers.*` shape deferred to alpha.5+ pending backend canon work). New `useTokenTransfers` + `useTokenTransfer` hooks; new `getByTxLogIndex` backend query. Hook proof matrix length unchanged at 41 (non-canonical hooks deliberately excluded).
-
-  **S1 (#456) closed no-op** — alpha publish infrastructure (tsup, lazy-DX, transport state machine, npm metadata, READMEs, CHANGELOG, changesets, OIDC release workflow) physically merged into `api-first` via PRs #449-#452 earlier the same day; the slice merge produced 0 file changes per clean-room probe.
-
-  **Friction issues filed for alpha.4+ polish:**
-  - #474 — `me.get` returns `NOT_IMPLEMENTED` when `config.data` is undefined; should be `NOT_AUTHENTICATED`.
-  - #475 — `@capxul/sdk/headless` slim entry point excludes xstate flow machines + brand constructors (1.6 MB → much smaller).
-  - #477 / #478 — `transfers.*` / `balanceLedger.*` / `treasury` canon-shape alignment with indexer feed.
-  - #471 — Vercel-capxul-web preview-deploy systemic failure on api-first base (separate from epic).
-
-### Patch Changes
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.4
-
-## 0.1.0-alpha.3
-
-### Patch Changes
-
-- Re-export `tryCatch` from `@capxul/sdk`.
-
-  `tryCatch` is referenced in `packages/sdk/README.md` (live on npm at
-  `0.1.0-alpha.2`) and in `.claude/rules/sdk.md` as the canonical
-  async-error helper for SDK operations:
-
-  ```ts
-  import { tryCatch } from "@capxul/sdk";
-
-  const [err, payment] = await tryCatch(capxul.payments.create({ ... }));
-  ```
-
-  The helper lives at `@repo/observability/try-catch.ts` and is bundled
-  into the SDK dist via tsup `noExternal`, but it was never re-exported
-  from `packages/sdk/src/index.ts`. Consumers following the README example
-  hit `Module '"@capxul/sdk"' has no exported member 'tryCatch'.` at
-  import time.
-
-  Caught during alpha.2 spike-install verification (REVIEW.html, "What's
-  not proven" row 6). One-line public-export addition; no runtime change.
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.3
-
-## 0.1.0-alpha.2
-
-### Patch Changes
-
-- Add `convex` as a peer dependency.
-
-  `@capxul/sdk`'s bundled `_generated/api` snapshot calls
-  `anyApi` / `componentsGeneric` from `convex/server` at runtime — they
-  are not just types — and tsup correctly externalizes `convex` /
-  `convex/server` / `convex/react` so the consumer's own Convex install
-  is reused. The peer was missing from the published manifest, so
-  `require('@capxul/sdk')` failed with `Cannot find module 'convex/server'`
-  in any spike that hadn't already installed `convex`.
-
-  `@capxul/sdk-react` mirrors the peer because its bundle re-exports
-  flow-machine constructors from `@capxul/sdk` and may transitively
-  pull in the same module.
-
-  Caught during alpha.1 spike-install verification.
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.2
-
-## 0.1.0-alpha.1
-
-### Patch Changes
-
-- Move workspace `@repo/*` packages from `dependencies` to
-  `devDependencies` so the published `package.json` doesn't list them
-  as runtime deps. The tsup pipeline bundles every `@repo/*` import
-  inline (`noExternal`), so the published code has zero references to
-  those packages — but until now the published `package.json` still
-  declared them, and `npm install @capxul/sdk@0.1.0-alpha.0` failed
-  trying to resolve `@repo/api-contract@0.0.0` etc. on the public
-  registry.
-
-  `@capxul/sdk-react` keeps `@capxul/sdk` as a runtime dep — that one
-  is published.
-
-  No public surface changes. Pure publish-metadata correction caught
-  during alpha.0 spike-install verification.
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.1
-
-Changelog managed by [changesets](https://github.com/changesets/changesets) —
-see `.changeset/README.md` for the operator workflow.
-
-## 0.1.0-alpha.0
-
-### Minor Changes
-
-- Initial alpha publish.
-
-  `@capxul/sdk` ships the headless TypeScript client for Capxul's
-  `/v1/*` HTTP contract — auth, me, accounts, payments, organizations,
-  withdrawals, documents, and three XState v5 flow machines. Errors
-  are typed `CapxulError` instances with narrowed `code` unions per
-  method; `tryCatch` returns the canonical `[error, data]` tuple.
-
-  `@capxul/sdk-react` ships the React provider and hooks. The lazy-DX
-  `<CapxulProvider publishableKey="cap_pk_…">` mounts synchronously
-  and bootstraps runtime URLs through `/v1/client/bootstrap` on the
-  first SDK call. `useCapxulStatus()` exposes the canonical 5-state
-  transport lifecycle through `useSyncExternalStore`. Read hooks
-  return the canonical `QueryResult<T>` three-state discriminated
-  union (loading / data / error) — never throws on "still loading".
-
-  See each package's `README.md` for the public surface.
-
-### Patch Changes
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.0

package/LICENSE

@@ -1,44 +0,0 @@
-Copyright (c) 2026 Xelmar Tech Ltd. ("Capxul"). All rights reserved.
-
-This software ("@capxul/sdk-react", the "Software") is proprietary to
-Capxul. The Software is licensed, not sold, and is made available
-solely to registered Capxul customers under the Capxul Terms of
-Service or a separate written commercial agreement between Capxul and
-the licensee.
-
-Two-layer trust
----------------
-Capxul's value-bearing on-chain logic — Safe v1.4.1, ERC-4337 modules,
-and any contract that custodies, transfers, or signs over user funds —
-is open source under permissive licenses and is published in a
-separate, auditable repository. See:
-
-  https://github.com/Xelmar-tech/Capxul
-
-The orchestration layer in this package — React provider, hooks,
-state-machine wiring, integration glue, and any code that translates
-customer intent into transactions or routes data between subsystems —
-is the proprietary product of Capxul and is governed by this license.
-
-Customers of the Capxul platform may use this Software solely:
-  (a) to access Capxul's hosted services they have contracted for,
-  (b) within the scope of their active subscription or trial, and
-  (c) in accordance with the Capxul Terms of Service.
-
-Without limiting the foregoing, you may NOT:
-  (i)   redistribute, sublicense, sell, lease, or rent the Software,
-  (ii)  reverse-engineer, decompile, or disassemble the Software,
-        except to the limited extent applicable mandatory law
-        permits, and
-  (iii) remove or alter copyright, trademark, or other proprietary
-        notices in the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
-OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT
-SHALL CAPXUL OR ITS AFFILIATES BE LIABLE FOR ANY CLAIM, DAMAGES, OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
-ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-Contact: legal@capxul.com

package/README.md

@@ -1,187 +0,0 @@
-# @capxul/sdk-react
-
-React provider + hooks for Capxul. Wraps [`@capxul/sdk`](https://www.npmjs.com/package/@capxul/sdk)
-in a synchronously-mounting provider with lazy bootstrap and a
-discriminated-union return shape on every read hook.
-
-> **Alpha — `0.x` is pre-release.** APIs can change between alpha
-> versions. Pin to an exact version and read the changelog before
-> upgrading.
-
-## Install
-
-```bash
-pnpm add @capxul/sdk @capxul/sdk-react react @tanstack/react-query
-# or: npm install @capxul/sdk @capxul/sdk-react react @tanstack/react-query
-```
-
-Peer requirements:
-
-- React `>= 19.0.0`
-- `@tanstack/react-query` `^5`
-- `@xstate/react` `^5` (only if you use the flow hooks)
-
-## Two-layer trust
-
-This package is the **orchestration** half of Capxul's two-layer
-architecture. Funds are custodied by audited, open-source Safe v1.4.1
-contracts published in the [Capxul GitHub repo](https://github.com/Xelmar-tech/Capxul/tree/main/packages/contracts).
-The React glue here is proprietary — see [`LICENSE`](./LICENSE).
-
-## Quickstart
-
-Wrap your app once with `CapxulProvider`. Pass a publishable key
-(`cap_pk_live_…` / `cap_pk_test_…`). The provider mounts synchronously
-— no Suspense gate, no async-mount stall — and lazily bootstraps the
-runtime URLs from `/v1/client/bootstrap` on the first SDK call:
-
-```tsx
-import { CapxulProvider } from "@capxul/sdk-react";
-
-export default function RootLayout({ children }) {
-  return (
-    <CapxulProvider
-      config={{
-        mode: "publishable-key",
-        publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
-      }}
-    >
-      {children}
-    </CapxulProvider>
-  );
-}
-```
-
-Inside the tree, read identity with `useMe()`. The hook collapses the
-multi-step lifecycle (not-bootstrapped, bootstrapping, no-session,
-no-data, live) into three states the consumer cares about:
-
-```tsx
-import { useMe } from "@capxul/sdk-react";
-
-function Header() {
-  const me = useMe();
-
-  if (me.isPending) return <span>Loading…</span>;
-  if (me.isError) return <span>Couldn't load profile.</span>;
-  return <span>Hi, {me.data.username}</span>;
-}
-```
-
-Drive an OTP sign-in flow with `useAuth()` — the canonical React auth
-wrapper over `AuthService`:
-
-```tsx
-import { useAuth } from "@capxul/sdk-react";
-
-function SignIn() {
-  const auth = useAuth();
-
-  if (auth.state === "idle") {
-    return (
-      <button onClick={() => auth.signIn("alice@example.com")}>
-        Send code
-      </button>
-    );
-  }
-  // … handle "sendingOtp", "awaitingOtp", "bootstrapping", "authenticated"
-}
-```
-
-## Lifecycle observability — `useCapxulStatus()`
-
-Need a status indicator or a gate UI? Subscribe to the underlying
-transport state machine:
-
-```tsx
-import { useCapxulStatus } from "@capxul/sdk-react";
-
-function Banner() {
-  const status = useCapxulStatus();
-
-  switch (status.status) {
-    case "idle": // no network call yet
-    case "bootstrapping": // /v1/client/bootstrap in flight
-      return <Spinner />;
-    case "ready": // bootstrapped, no session
-    case "authenticated": // bootstrapped + session live
-      return null;
-    case "error":
-      return <ErrorBanner error={status.error} />;
-  }
-}
-```
-
-`useCapxulStatus()` is a thin
-[`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore)
-subscription against the transport singleton — only the components
-that actually call it re-render when state changes. The provider
-itself never re-renders.
-
-## Publishable-key proof status
-
-The publishable-key path is runtime-proven where the repo can run it
-without secrets:
-
-| Surface              | Runtime proof                                                                                                             | Expected safe signal                                                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Provider + `useMe()` | `corepack pnpm --filter @capxul/sdk-react check-types` plus the headless proof tests under `packages/sdk-react/ops/proof` | provider reaches `useCapxulStatus().status === "ready"` after one bootstrap request                       |
-| Reference CLI mock   | `corepack pnpm --filter @capxul/reference-cli build && node apps/reference-cli/dist/cli.js bootstrap probe --mock --json` | `ok:true`, `mode:"publishable-key"`, `bootstrapRequests:1`, `authRequests:1`, `keyLengthClass:"provided"` |
-| Reference CLI live   | same command without `--mock`, with `CAPXUL_REF_PUBLISHABLE_KEY` and optional `CAPXUL_REF_BOOTSTRAP_URL` set locally      | success only when the key/origin/runtime are valid; otherwise sanitized SDK error JSON                    |
-
-Do not paste or commit publishable keys, session tokens, Convex JWTs,
-cookies, or provider payloads. Proof output reports only
-`keyLengthClass`.
-
-## Hooks catalogue
-
-| Surface                | Hook                                                                                                                                                                                |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Imperative client      | `useCapxul()`                                                                                                                                                                       |
-| Identity               | `useMe`, `useAccount`                                                                                                                                                               |
-| Organizations          | `useOrganization`, `useOrganizations`, `useMember`, `useMembers`                                                                                                                    |
-| Payments               | `usePayment`, `usePayments`, `useOrgPayments`                                                                                                                                       |
-| Transfers              | `useTransfer`, `useTransfers`, `useOrgTransfers`                                                                                                                                    |
-| Withdrawals            | `useWithdrawal`, `useWithdrawals`, `useOrgWithdrawals`                                                                                                                              |
-| Documents              | `useDocument`, `useDocuments`, `useOrgDocuments`                                                                                                                                    |
-| Sub-accounts / virtual | `useSubAccount`, `useSubAccounts`, `useVirtualAccount`, `useVirtualAccounts`, `useVirtualCard`, `useVirtualCards`                                                                   |
-| Settings               | `useApiKey`, `useApiKeys`, `useWebhookEndpoint`, `useWebhookEndpoints`, `useWebhookEvent`, `useExternalAccount`, `useExternalAccounts`, `useBalanceLedgerEntry`, `useBalanceLedger` |
-| KYC / KYB              | `useKycProfile`                                                                                                                                                                     |
-| Treasury               | `useTreasury`, `useSafe`                                                                                                                                                            |
-| Operations             | `useOperation` (correlation join key per CANON.md §3.3)                                                                                                                             |
-| Lifecycle              | `useCapxulStatus`                                                                                                                                                                   |
-| Flows                  | `useOnboardingFlow`, `useProvisioningFlow`                                                                                                                                          |
-
-Most "not-yet-implemented" verticals return a `QueryResult<T>` in the
-`error` state with `code: "NOT_IMPLEMENTED"` — they compile, render
-without crashing, and surface a clear runtime signal.
-
-## Three-state read shape (`QueryResult<T>`)
-
-Read hooks return a discriminated union:
-
-```ts
-type QueryResult<T> =
-  | { readonly status: "loading" }
-  | { readonly status: "data"; readonly data: T }
-  | { readonly status: "error"; readonly error: CapxulError };
-```
-
-Hooks **never throw** for a "still loading" condition. Pattern-match
-on `status`. (`useMe()` is the first hook migrated to TanStack Query
-— it returns `UseQueryResult<Account, CapxulError>` for now; the
-remaining hooks lift to that shape over time.)
-
-## Server / CLI consumers
-
-`@capxul/sdk-react` is browser-only. For server, CLI, and harness
-code, build a `CapxulClient` directly with `createCapxulClient` from
-`@capxul/sdk` — no provider, no React. See that package's README.
-
-## License
-
-Proprietary — see [`LICENSE`](./LICENSE). The orchestration code in
-this package is governed by the Capxul Terms of Service. The
-value-bearing custody contracts are open source.
-
-Contact: [legal@capxul.com](mailto:legal@capxul.com)