BackTrackCo · vraspar · Feb 10, 2026 · Feb 5, 2026 · Feb 7, 2026 · Feb 7, 2026
diff --git a/contracts/conditions.mdx b/contracts/conditions.mdx
@@ -670,7 +670,7 @@ config.releaseCondition = businessHours.address;
   <Card title="Deploy an Operator" icon="rocket" href="/sdk/deploy-operator">
     Deploy operators with conditions using the SDK.
   </Card>
-  <Card title="Escrow Management" icon="lock" href="/sdk/client/escrow-management">
+  <Card title="Client SDK" icon="lock" href="/sdk/client/quickstart">
     Interact with freeze and escrow conditions via the Client SDK.
   </Card>
 </CardGroup>
diff --git a/docs.json b/docs.json
@@ -55,45 +55,24 @@
             ]
           },
           {
-            "group": "Client SDK",
+            "group": "Merchant",
             "pages": [
-              "sdk/client/quickstart",
-              "sdk/client/payment-queries",
-              "sdk/client/refund-operations",
-              "sdk/client/escrow-management",
-              "sdk/client/subscriptions"
-            ]
-          },
-          {
-            "group": "Merchant SDK",
-            "pages": [
-              "sdk/merchant/quickstart",
-              "sdk/merchant/payment-operations",
-              "sdk/merchant/refund-handling",
-              "sdk/merchant/subscriptions"
-            ]
-          },
-          {
-            "group": "Arbiter SDK",
-            "pages": [
-              "sdk/arbiter/quickstart",
-              "sdk/arbiter/decision-submission",
-              "sdk/arbiter/registry",
-              "sdk/arbiter/batch-operations",
-              "sdk/arbiter/ai-integration",
-              "sdk/arbiter/subscriptions"
+              "sdk/merchant/getting-started",
+              "sdk/helpers/refundable"
             ]
           },
           {
-            "group": "Resource Server",
+            "group": "Facilitator",
             "pages": [
-              "sdk/helpers/refundable"
+              "sdk/facilitator/getting-started"
             ]
           },
           {
-            "group": "Reference",
+            "group": "Coming Soon",
             "pages": [
-              "sdk/limitations"
+              "sdk/merchant/quickstart",
+              "sdk/client/quickstart",
+              "sdk/arbiter/quickstart"
             ]
           }
         ]

diff --git a/index.mdx b/index.mdx
@@ -44,11 +44,11 @@ sequenceDiagram
   <Card title="Clients (Payers)" icon="user" href="/sdk/client/quickstart">
     Request refunds, freeze suspicious payments, and track payment state.
   </Card>
-  <Card title="Merchants (Receivers)" icon="store" href="/sdk/merchant/quickstart">
+  <Card title="Merchants (Receivers)" icon="store" href="/sdk/examples">
     Release funds, process refunds, and manage escrow periods.
   </Card>
   <Card title="Arbiters" icon="gavel" href="/sdk/arbiter/quickstart">
-    Resolve disputes, approve/deny refund requests, and integrate AI decision-making.
+    Resolve disputes and approve/deny refund requests.
   </Card>
 </CardGroup>
 

diff --git a/roadmap.mdx b/roadmap.mdx
@@ -53,7 +53,7 @@ icon: "map"
 
 ### Phase 1: MVP Examples (Completed)
 
-- 7 examples (deploy-operator, merchant-server, merchant-cli, client-cli, arbiter-cli *(in progress)*, e2e-dispute, shared)
+- 8 examples (deploy-operator, facilitator, server-express, server-hono, merchant-cli, client-cli, arbiter-cli, shared)
 - Full e2e dispute resolution flow
 
 ### Phase 2: Core SDK (Completed)

diff --git a/sdk/arbiter/quickstart.mdx b/sdk/arbiter/quickstart.mdx
@@ -1,21 +1,21 @@
 ---
-title: "Arbiter Quickstart"
-description: "Get started with the X402r Arbiter SDK for dispute resolution"
+title: "Arbiter SDK"
+description: "Dispute resolution SDK for reviewing cases and making decisions (experimental)"
 icon: "rocket"
 ---
 
-The `@x402r/arbiter` package provides everything arbiters need to resolve disputes: reviewing cases, making decisions, executing refunds, and integrating AI for automated resolution.
+<Warning>
+The Arbiter SDK is experimental. The dispute resolution system design is actively evolving.
+</Warning>
 
-## Installation
+<Note>
+The `@x402r/arbiter` package is not yet published on npm. Install directly from the [GitHub repository](https://github.com/BackTrackCo/x402r-sdk).
+</Note>
 
-```bash
-npm install @x402r/arbiter @x402r/core viem
-```
+The `@x402r/arbiter` package provides methods for arbiters to resolve disputes: reviewing refund requests, approving or denying them, and executing refunds.
 
 ## Setup
 
-Create viem clients as described in [Installation](/sdk/installation), then:
-
 ```typescript
 import { X402rArbiter } from '@x402r/arbiter';
 import { getNetworkConfig } from '@x402r/core';
@@ -31,119 +31,33 @@ const arbiter = new X402rArbiter({
 });
 ```
 
-## Review Pending Cases
-
-Get refund requests awaiting your decision:
-
-```typescript
-// Get paginated refund requests for a receiver
-const { keys, total } = await arbiter.getPendingRefundRequests(
-  0n,   // offset
-  10n,  // count
-  '0xReceiverAddress...' // optional: defaults to wallet account
-);
-console.log(`${total} cases to review, showing first ${keys.length}`);
-
-// Review each case
-for (const key of keys) {
-  const request = await arbiter.getRefundRequestByKey(key);
-  console.log(`Amount: ${request.amount}, Status: ${request.status}`);
-}
-```
-
-## Make a Decision
+## Available Methods
 
-Approve or deny refund requests:
+The Arbiter SDK currently supports:
 
-```typescript
-// Approve a refund request
-const { txHash: approveTx } = await arbiter.approveRefundRequest(paymentInfo, 0n);
-console.log('Approved:', approveTx);
+- **`approveRefundRequest()`** — Approve a pending refund request
+- **`denyRefundRequest()`** — Deny a pending refund request
+- **`executeRefundInEscrow()`** — Execute an approved refund to transfer funds back
+- **`getPendingRefundRequests()`** — List refund requests awaiting decision
+- **`getRefundRequestByKey()`** — Get details of a specific refund request
+- **`registerArbiter()`** — Register in the on-chain ArbiterRegistry
+- **`isArbiterRegistered()`** — Check registration status
 
-// Deny a refund request
-const { txHash: denyTx } = await arbiter.denyRefundRequest(paymentInfo, 0n);
-console.log('Denied:', denyTx);
-```
+## Try It Now
 
-## Execute Approved Refunds
+The easiest way to try arbiter features is with the **arbiter-cli** example, which provides a command-line interface for all arbiter operations:
 
-After approving, execute the refund to transfer funds back to the payer:
-
-```typescript
-// Approve the request first
-await arbiter.approveRefundRequest(paymentInfo, 0n);
-
-// Execute the refund (defaults to paymentInfo.maxAmount if no amount specified)
-const { txHash } = await arbiter.executeRefundInEscrow(paymentInfo);
-console.log('Refund executed:', txHash);
-
-// Or specify a partial refund amount
-const { txHash: partialTx } = await arbiter.executeRefundInEscrow(
-  paymentInfo,
-  BigInt('500000') // partial amount
-);
-```
-
-## Batch Operations
-
-Process multiple cases efficiently:
-
-```typescript
-// Approve multiple refunds
-const results = await arbiter.batchApprove([
-  { paymentInfo: paymentInfo1, nonce: 0n },
-  { paymentInfo: paymentInfo2, nonce: 0n },
-]);
-console.log(`Approved ${results.length} refunds`);
-
-// Deny multiple refunds
-const denyResults = await arbiter.batchDeny([
-  { paymentInfo: paymentInfo3, nonce: 0n },
-]);
-```
-
-## Register as an Arbiter
-
-Register yourself in the on-chain ArbiterRegistry:
-
-```typescript
-// Register with your API endpoint
-const { txHash } = await arbiter.registerArbiter('https://arbiter.example.com/api/disputes');
-console.log('Registered:', txHash);
-
-// Check registration
-const isRegistered = await arbiter.isArbiterRegistered(account.address);
-console.log('Is registered:', isRegistered);
-```
-
-## Watch for New Cases
-
-Subscribe to incoming refund requests:
-
-```typescript
-const { unsubscribe } = arbiter.watchNewCases((event) => {
-  console.log('New case:', event);
-});
-
-// Watch for decisions (status updates)
-const { unsubscribe: unsubDecisions } = arbiter.watchDecisions((event) => {
-  console.log('Decision made:', event);
-});
-```
+<Card title="arbiter-cli" icon="terminal" href="https://github.com/BackTrackCo/x402r-sdk/tree/main/examples/dev-tools/arbiter-cli">
+  CLI tool for arbiters to review cases, make decisions, and manage registry.
+</Card>
 
 ## Next Steps
 
 <CardGroup cols={2}>
-  <Card title="Decision Submission" icon="gavel" href="/sdk/arbiter/decision-submission">
-    Learn all decision methods including executeRefundInEscrow.
-  </Card>
-  <Card title="Registry" icon="clipboard-list" href="/sdk/arbiter/registry">
-    Manage your arbiter registration and discover other arbiters.
-  </Card>
-  <Card title="Batch Operations" icon="layer-group" href="/sdk/arbiter/batch-operations">
-    Process multiple cases efficiently.
+  <Card title="Examples" icon="code" href="/sdk/examples">
+    See all working examples including the full payment flow.
   </Card>
-  <Card title="AI Integration" icon="robot" href="/sdk/arbiter/ai-integration">
-    Automate with AI hooks.
+  <Card title="Deploy Operator" icon="rocket" href="/sdk/deploy-operator">
+    Deploy a PaymentOperator with arbiter support.
   </Card>
 </CardGroup>