@wowok/skills 1.1.0 → 1.1.2

package/wowok-order/SKILL.md

@@ -1,533 +1,445 @@
 ---
 name: wowok-order
 description: |
-  WoWok order lifecycle management — covers the complete order flow from
-  creation through payment, progress tracking, completion, and dispute
-  resolution. Includes order splitting (Allocation), incentive distribution
-  (Reward), and arbitration patterns.
+  WoWok Customer Guide — complete order lifecycle for buyers: service evaluation,
+  consensus building, order creation, progress tracking, and dispute resolution.
   
-  Use this skill when managing orders, setting up payment flows, configuring
-  order splitting, or handling disputes.
+  Covers the full buyer journey: pre-purchase due diligence based on on-chain objects, consensus establishment with Messenger as off-chain
+  but self-verifiable evidence supplement, order operations, progress advancement
+  with game theory, and arbitration when needed.
 when_to_use:
-  - User wants to create or manage orders
-  - User asks about order lifecycle, payment, or progress
-  - User needs to set up order splitting (allocation) or incentives (reward)
-  - User mentions "order", "payment", "allocation", "reward", "arbitration", "dispute"
-  - User wants to understand how money flows in WoWok
+  - User is a customer/buyer placing or managing orders
+  - User wants to evaluate services before purchasing
+  - User needs to communicate with sellers via Messenger
+  - User asks about order progress, payments, or refunds
+  - User wants to file disputes or arbitration claims
+  - User mentions "buy", "order", "purchase", "refund", "dispute", "arbitration"
 ---
 
-# WoWok Order Lifecycle Management
+# WoWok Customer Guide
 
-## Runtime Objects Overview
+Complete guide for buyers on WoWok — from service discovery to order completion.
 
-After a Service is published (see [wowok-build](../wowok-build/SKILL.md)), users interact with it creating runtime objects:
+> **Role**: Customer (Buyer/Order Holder)  
+> **Provider Guide**: See [wowok-provider](../wowok-provider/SKILL.md)  
+> **Arbitration Guide**: See [wowok-arbitrator](../wowok-arbitrator/SKILL.md)  
+> **Messenger**: See [wowok-messenger](../wowok-messenger/SKILL.md) for encrypted communication  
+> **Tools**: See [wowok-tools](../wowok-tools/SKILL.md)
 
-| Object | Created By | Purpose |
-|--------|-----------|---------|
-| **Order** | User purchase | Order management and escrow |
-| **Progress** | Order creation | Workflow state tracking |
-| **Allocation** | Order completion | Fund distribution per consensus |
-| **Arb(s)** | Dispute request | Arbitration for compensation |
+---
 
-```
-User Purchase
-     ↓
-Service ──→ Order ──→ Progress ──→ Allocation
-              ↓           ↓
-         Payment    Node Transitions
-         (escrow)   (Guard validated)
-                        ↓
-                   Completion
-                        ↓
-              Fund Distribution
-```
+## Core Concepts
 
-## Order Lifecycle Overview
+### Order Lifecycle Objects
 
-```
-Demand → Order → Payment → Progress → Completion
-                                  ↓
-                            Arbitration (disputes)
-```
+When you purchase from a Service, three runtime objects are created:
 
-## Component Relationships
+| Object | Purpose | Key Points |
+|--------|---------|------------|
+| **Order** | Fund escrow & ownership | You are the `builder` (owner). Agents can help operate but **only you can withdraw funds**. |
+| **Progress** | Workflow state tracking | Tracks which Machine node you're at. Advanced via Order operations. |
+| **Allocation** | Fund distribution engine | Executes the winning allocator strategy when reaching exit nodes. |
 
-```
-Service (marketplace)
-  ├── Machine (workflow template)
-  ├── Allocation (order splitting rules)
-  ├── Reward (incentive pool)
-  └── Treasury (team fund)
-
-Order (instance)
-  ├── references Service
-  ├── references Machine (for workflow)
-  ├── Payment (funds transfer)
-  └── Progress (workflow tracking)
-```
+### Allocators vs Allocation
 
-## Order Creation
+- **Allocators** (Service level): Multiple distribution strategies defined by seller, each with a Guard condition
+- **Allocation** (Order level): Auto-created execution engine that evaluates all allocator Guards and runs the strategy whose Guard returns `true`
 
-```
-onchain_operations({
-  operation_type: "order",
-  data: {
-    op: "create",
-    service: "<service_name_or_id>",
-    machine: "<machine_name_or_id>",
-    buyer: "<buyer_address>",
-    seller: "<seller_address>",
-    price: "<amount>",
-    token_type: "<token_type>",
-    ...
-  }
-})
-```
+**When Allocation Executes**:
+- Allocation evaluates **whenever the Progress reaches a node** that triggers fund distribution
+- **Any node** (not just exit nodes) can be configured to trigger Allocation evaluation
+- The winning allocator is the one whose Guard validates `true` for the current state
+- Guards can check: Progress node, time elapsed, signatures, or any on-chain data
 
-## Payment Flow
+**Consensus Principle**: Allocators and their Guard conditions are immutable and transparent. Both parties see the same rules, but choose different paths based on their interests.
 
-### Direct Payment
-```
-onchain_operations({
-  operation_type: "payment",
-  data: {
-    op: "send",
-    from: "<sender_account>",
-    to: "<recipient_address>",
-    amount: "<amount>",
-    token_type: "<token_type>"
-  }
-})
-```
+---
 
-### Payment via Order
-Orders can hold funds in escrow. Payment is released when order progresses through the Machine workflow.
+## Phase 1: Service Evaluation (Pre-Purchase)
 
-## Order Splitting (Allocation)
+Thoroughly investigate before committing funds.
 
-Allocation defines how order payments are automatically split among multiple recipients.
+### 1.1 Query Service Configuration
 
-### Create Allocation
-```
-onchain_operations({
-  operation_type: "allocation",
-  data: {
-    op: "create",
-    name: "<allocation_name>",
-    service: "<service_id>",
-    rules: [
-      {
-        recipient: "<address_or_guard>",
-        share: <percentage_or_fixed>,
-        discount_type: "RATES"  // or "FIXED"
-      }
-    ]
-  }
-})
-```
+**Tool**: Use `query_toolkit` with `onchain_objects` query type to retrieve Service configuration.
 
-### Discount Types
-| Type | Description |
-|------|-------------|
-| `RATES` | Percentage-based split (e.g., 30% = 30/100) |
-| `FIXED` | Fixed amount split |
+**Schema Reference**: `schema_query({ action: "get", name: "query_toolkit" })`
 
-### Common Allocation Patterns
+**Key Fields to Analyze**:
 
-**Pattern 1: Platform Fee**
-```
-rules: [
-  { recipient: "<platform_address>", share: 5, discount_type: "RATES" },
-  { recipient: "<seller_address>", share: 95, discount_type: "RATES" }
-]
-```
+| Field | What to Check | Risk Signals |
+|-------|---------------|--------------|
+| `sales` | Pricing, stock, WIP files | No `wip_hash` = unverified product claims |
+| `machine` | Workflow complexity | Overly complex = higher dispute risk |
+| `allocators` | Fund distribution rules | Unfair splits = reconsider purchase |
+| `arbitrations` | Available dispute resolution | None available = higher risk |
+| `compensation_fund` | Arbitration payout capacity | Low balance = limited recourse |
 
-**Pattern 2: Multi-Party Split**
-```
-rules: [
-  { recipient: "<platform>", share: 3, discount_type: "RATES" },
-  { recipient: "<seller>", share: 70, discount_type: "RATES" },
-  { recipient: "<affiliate>", share: 27, discount_type: "RATES" }
-]
-```
+**WIP File Verification**:
+- `wip`: URL to product description/images
+- `wip_hash`: Integrity hash (if empty, auto-verified; if provided, must match)
+- **This is the seller's immutable commitment on-chain** — serves as arbitration evidence
 
-## Incentive Distribution (Reward)
+### 1.2 Evaluate Service Reputation
 
-Reward defines incentive pools that distribute tokens based on Guard-validated conditions.
+Query the Service's EntityLinker for community endorsement data.
 
-### Create Reward
-```
-onchain_operations({
-  operation_type: "reward",
-  data: {
-    op: "create",
-    name: "<reward_name>",
-    service: "<service_id>",
-    ...
-  }
-})
-```
+**Tool**: `query_toolkit` with `onchain_table_item_entity_linker` query type.
 
-### Reward Claim Flow
-1. User meets Reward conditions (validated by Guard)
-2. User claims reward → `onchain_table_data` query `onchain_table_item_reward_record`
-3. Tokens are distributed from the Reward pool
+**Key Metrics to Calculate**:
 
-## Treasury Management
+| Metric | How to Calculate | Good Sign |
+|--------|------------------|-----------|
+| **Completion Rate** | % orders reaching terminal nodes | >90% |
+| **Arbitration Rate** | % orders with non-empty `dispute` | <5% |
+| **Avg Resolution Time** | Time from creation to completion | Short |
+| **Repeat Customer Rate** | % builders appearing multiple times | High |
+| **Community Sentiment** | likes vs dislikes in EntityLinker | Positive |
 
-Treasury is a team fund for a Service.
+---
 
-### Deposit to Treasury
-```
-onchain_operations({
-  operation_type: "treasury",
-  data: {
-    op: "deposit",
-    service: "<service_id>",
-    amount: "<amount>",
-    token_type: "<token_type>"
-  }
-})
-```
+## Phase 2: Consensus Building (CRITICAL)
 
-### Withdraw from Treasury
-```
-onchain_operations({
-  operation_type: "treasury",
-  data: {
-    op: "withdraw",
-    service: "<service_id>",
-    amount: "<amount>",
-    token_type: "<token_type>",
-    recipient: "<address>"
-  }
-})
-```
+Establish mutual understanding with seller BEFORE purchasing. Consensus is built on **immutable on-chain data** (Guard, Machine, Allocators), with Messenger serving as **off-chain but self-verifiable evidence supplement**.
 
-### Query Treasury History
-```
-onchain_table_data({
-  query_type: "onchain_table_item_treasury_history",
-  parent: "<treasury_id>",
-  address: "<payment_id>"
-})
-```
+### Consensus Layers
 
-## Arbitration (Dispute Resolution)
+| Layer | Source | Immutability | Purpose |
+|-------|--------|--------------|---------|
+| **On-Chain Foundation** | Service.machine, order_allocators, Guards | Immutable after publish | Transparent rules both parties agree to |
+| **Off-Chain Supplement** | Messenger WTS files | Self-verifiable via signatures | Clarification, negotiation, evidence |
 
-When orders have disputes, Arbitration provides resolution.
+> **Core Principle**: On-chain data (Machine workflow, Allocator rules, Guard conditions) forms the **immutable consensus foundation**. Messenger communication provides **clarification and evidence** but cannot override on-chain rules.
 
-### Create Arbitration
-```
-onchain_operations({
-  operation_type: "arbitration",
-  data: {
-    op: "create",
-    name: "<arbitration_name>",
-    ...
-  }
-})
-```
+> **Full Messenger Guide**: See [wowok-messenger](../wowok-messenger/SKILL.md) for complete messaging operations, WTS evidence generation, and list management.
 
-### Watch Arbitration Events
-```
-onchain_events({
-  type: "arbitration",
-  cursor: null,
-  limit: 20
-})
-```
+### 2.1 Verify On-Chain Consensus First
 
-## Demand (Service Requests)
+Before contacting seller, thoroughly understand the immutable rules:
 
-Demand allows users to request services.
+**Tool**: `query_toolkit` with `onchain_objects` query type to retrieve Service data.
 
-### Create Demand
-```
-onchain_operations({
-  operation_type: "demand",
-  data: {
-    op: "create",
-    service: "<service_id>",
-    description: "<request_description>",
-    ...
-  }
-})
-```
+**Key On-Chain Consensus Elements**:
+- **Machine**: Workflow nodes and transitions — defines how order progresses
+- **Allocators**: Fund distribution strategies — defines who gets what under which conditions
+- **Guards**: Validation logic — determines which allocator executes
+- **Arbitrations**: Available dispute resolution services
 
-### Query Demand Presenters
-```
-onchain_table_data({
-  query_type: "onchain_table_item_demand_presenter",
-  parent: "<demand_id>",
-  address: "<presenter_address>"
-})
-```
+### 2.2 Get Service Contact
 
-## Complete Order Flow Example
+**Steps**:
+1. Query Service object to extract `um` field (Contact object ID)
+2. Query Contact object to retrieve `ims[]` array (Messenger addresses)
 
-### 1. Service Setup (done once)
-```
-Permission → Guard → Service → Machine → Allocation → Reward
-```
+**Tool**: `query_toolkit` with `onchain_objects` query type.
 
-### 2. Order Creation (per transaction)
-```
-1. Buyer creates Order referencing Service + Machine
-2. Buyer sends Payment to Order (escrow)
-3. Seller advances Progress through Machine nodes
-4. On completion, Allocation splits payment automatically
-5. Reward distributes incentives if conditions met
-```
+### 2.3 Send Encrypted Messages
 
-### 3. Dispute Resolution (if needed)
-```
-1. Either party initiates Arbitration
-2. Arbiter reviews evidence
-3. Arbiter resolves → funds released per resolution
-```
+Use Messenger to clarify on-chain rules and negotiate specifics.
 
-## Querying Order State
+**Tool**: `messenger_operation` with `send_message` operation.
 
-### Check Order Object
-```
-query_toolkit({
-  query_type: "onchain_objects",
-  objects: ["<order_name_or_id>"]
-})
-```
+**Schema Reference**: `schema_query({ action: "get", name: "messenger_operation" })`
 
-### Check Order Progress
-```
-onchain_table_data({
-  query_type: "onchain_table",
-  parent: "<progress_id>"
-})
-```
+**Evidence Closure Principle**: Messages only become valid evidence when the recipient **explicitly confirms** (ARK signature). One-sided claims are not evidence.
 
-### Check Received Payments
-```
-query_toolkit({
-  query_type: "onchain_received",
-  name_or_address: "<object_id>"
-})
-```
+**Why Messenger Matters** (as consensus supplement):
+- ✅ End-to-end encrypted (NOT on-chain) — privacy for negotiations
+- ✅ Creates tamper-proof audit trail (WTS files) — see [wowok-messenger](../wowok-messenger/SKILL.md) for WTS generation
+- ✅ Clarifies on-chain rules without modifying them
+- ✅ Generates arbitration evidence for off-chain commitments
 
-## Common Order Errors
+**AI Should Proactively Suggest Clarifying**:
+- Exact deliverables and acceptance criteria
+- Timeline and milestones
+- Edge case handling
+- Refund/cancellation terms
+- Delivery logistics (address, phone)
+- Custom requirements
 
-| Error | Cause | Fix |
-|-------|-------|-----|
-| "service not found" | Service doesn't exist | Create Service first |
-| "machine not found" | Machine doesn't exist | Create Machine first |
-| "insufficient balance" | Not enough tokens | Check balance with account_balance |
-| "allocation failed" | Invalid split rules | Check total shares = 100% |
-| "progress blocked" | Guard condition not met | Check forward Guard logic |
-| "arbitration not found" | No Arbiter configured | Create Arbitration object |
+**Request Explicit Confirmation**: Ensure the seller responds and confirms understanding before proceeding. Unconfirmed messages have limited evidentiary value.
 
-## Real-World Order Flows (from tested examples)
+---
 
-### Allocation Patterns
+## Phase 3: Order Creation
 
-**From [Insurance](../examples/Insurance/Insurance.md) — Single-Recipient Allocation**
+Once consensus is reached, create the order through Service operation.
 
-The Insurance service uses a single allocator with 100% going to the signer who completes the claim:
+### 3.1 Key Parameters
 
-```
-order_allocators: {
-  description: "Insurance order revenue allocation",
-  threshold: 0,
-  allocators: [{
-    guard: "insurance_withdraw_guard_v1",
-    sharing: [{ who: { Signer: "signer" }, sharing: 10000, mode: "Rate" }]
-  }]
-}
-```
+**Operation**: `onchain_operations` with `operation_type: "service"`
 
-`sharing: 10000` in `mode: "Rate"` = 100% (basis points: 10000 = 100%).
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_service" })`
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md) — Multi-Recipient Allocation**
+**Key Parameters**:
 
-Dual-allocation pattern: one allocator for merchant-winning scenarios, one for customer-winning scenarios:
+| Parameter | Purpose | Notes |
+|-----------|---------|-------|
+| `buy.items` | Products to purchase | Reference `Service.sales` |
+| `buy.total_pay` | Payment budget | **Excess automatically refunded** |
+| `buy.discount` | Coupon object ID | Optional — see 3.1.1 below |
+| `agents` | Delegated operators | Can operate order but **CANNOT withdraw funds** |
 
-```
-order_allocators: {
-  description: "Order fund allocation",
-  threshold: 0,
-  allocators: [
-    {
-      guard: "service_merchant_win_v2",
-      sharing: [{ who: { Signer: "signer" }, sharing: 10000, mode: "Rate" }]
-    },
-    {
-      guard: "service_customer_win_v2",
-      sharing: [{ who: { Signer: "signer" }, sharing: 10000, mode: "Rate" }]
-    }
-  ]
+#### 3.1.1 Using Discount Coupons
+
+When creating an order via the `buy` operation, you can apply a discount coupon by including the `discount` field with the coupon name/ID.
+
+**Finding Available Discounts**:
+
+Discount coupons are separate objects that you receive (usually transferred from Service marketing campaigns or other users). To find discounts applicable to the current Service:
+
+**Step 1: Query all Discount objects you own**
+
+Use `query_toolkit` with `onchain_received` query type to get all Discount objects:
+
+```json
+{
+  "query_type": "onchain_received",
+  "name_or_address": "your_account_name",
+  "type": "0x2::service::Discount", // Discount type on-chain
+  "cursor": null,
+  "limit": 50
 }
 ```
 
-Each allocator's Guard validates the order's current node — if the node is "Order Complete", "Wonderful", or "Return Fail", the merchant's allocator fires. If "Lost" or "Return Complete", the customer's allocator fires.
+This returns `ReceivedNormal[]` where each item's `content_raw` contains Discount fields:
+- `name`: Discount name
+- `discount_type`: "rate" (percentage) or "fixed" (absolute amount)
+- `benchmark`: Minimum order amount required
+- `off`: Discount value (e.g., 1000 for 10% if rate, or 100 for 100 units if fixed)
+- `time_start` / `time_end`: Validity period
+- `service`: Parent Service object ID (which Service this discount belongs to)
+- `transferable`: Whether it can be transferred to others
 
-### Order Creation Patterns
+**Step 2: Filter discounts for the current Service**
 
-**From [Insurance](../examples/Insurance/Insurance.md) — Order via Service**
+Each Discount has a `service` field indicating which Service it can be used with. Filter the received Discount objects by comparing each Discount's `service` field with the target Service object ID you're purchasing from. Only Discounts where `service` matches the target Service can be applied to that Service.
 
-Orders can be created directly through the Service's `order_new` field:
+**Step 3: Validate discount applicability**
 
-```
-onchain_operations({
-  operation_type: "service",
-  data: {
-    object: "insurance_service_v1",
-    order_new: {
-      buy: {
-        items: [{ name: "Outdoor Accident Insurance", stock: 1, wip_hash: "" }],
-        total_pay: { balance: 100000000 }
-      },
-      namedNewOrder: { name: "test_insurance_order_v1", replaceExistName: true }
+Before using a discount, verify:
+1. **Time validity**: `time_start` ≤ current_time ≤ `time_end`
+2. **Minimum amount**: Order total ≥ `benchmark`
+3. **Service match**: Discount's `service` field matches the Service being purchased
+
+**Step 4: Apply discount in order creation**
+
+Include the selected Discount object ID in the `buy.discount` field:
+
+```json
+{
+  "operation_type": "service",
+  "data": {
+    "buy": {
+      "items": [...],
+      "total_pay": "10000",
+      "discount": "discount_object_id_here"
     }
   }
-})
+}
 ```
 
-**From [Travel](../examples/Travel/Travel.md) — Order via Service with Discount**
+**Discount Calculation**:
+- If `discount_type` is "rate": Discount = `total_pay` × (`off` / 10000)
+- If `discount_type` is "fixed": Discount = min(`off`, `total_pay`)
+- Final payment = `total_pay` - Discount
 
-Orders can include discounts for time-limited promotions:
+| `namedNewOrder` | Local name for Order | Recommended for easy reference |
+| `namedNewProgress` | Local name for Progress | Recommended |
+| `namedNewAllocation` | Local name for Allocation | Recommended |
 
-```
-order_new: {
-  buy: {
-    items: [{ name: "Iceland Adventure", stock: 1 }],
-    total_pay: { balance: 200000000 }
-  },
-  namedNewOrder: { name: "alice_travel_order_v1" }
-}
-```
+### 3.2 Private Information Handling
 
-### Reward Patterns
+If Service requires private info (`customer_required`):
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md) — Multi-Condition Rewards**
+1. **NEVER put on-chain** — send via Messenger
+2. Include order ID in the message
+3. Confirm receipt with seller
 
-Rewards can be added AFTER Service publish. Each reward uses a Guard to verify claim conditions:
+**Tool**: `messenger_operation` with `send_message` operation.
 
-```
-onchain_operations({
-  operation_type: "reward",
-  data: {
-    object: { name: "myshop_reward_v2", permission: "myshop_permission_v2", replaceExistName: true },
-    description: "Reward pool for MyShop Advanced",
-    coin_add: { balance: 100000000 },
-    guard_add: [
-      {
-        guard: "reward_wonderful_v2",
-        recipient: { Signer: "signer" },
-        amount: { type: "Fixed", value: 10000 },
-        expiration_time: null
-      },
-      {
-        guard: "reward_lost_v2",
-        recipient: { Signer: "signer" },
-        amount: { type: "Fixed", value: 20000 },
-        expiration_time: null
-      },
-      {
-        guard: "reward_shipping_timeout_v2",
-        recipient: { Signer: "signer" },
-        amount: { type: "Fixed", value: 30000 },
-        expiration_time: null
-      }
-    ]
-  }
-})
-```
+### 3.3 Post-Creation Notification
+
+**Mandatory**: Notify Service customer service via Messenger with order ID and submitted info reference.
+
+---
+
+## Phase 4: Order Operations
+
+All operations use `operation_type: "order"`.
+
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_order" })`
+
+### 4.1 Permission Hierarchy
+
+| Role | Can Do | Cannot Do |
+|------|--------|-----------|
+| **Builder** (You) | Everything + withdraw funds | — |
+| **Agents** | Operate progress, arbitration, cancel | **Withdraw funds** |
+
+> **Critical**: You maintain ultimate financial control. Agents assist but cannot access funds.
 
-Each guard checks the order's current node:
-- `reward_wonderful_v2`: order at "Wonderful" node → 10000 reward
-- `reward_lost_v2`: order at "Lost" node → 20000 compensation
-- `reward_shipping_timeout_v2`: order at "Shipping" node > 2 days → 30000 compensation
+### 4.2 Progress Advancement
 
-### Progress Advancement Patterns
+**Key Rule**: As the order holder (builder), you advance progress **through the Order object**.
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md) — Progress with Submitted Data**
+The Machine workflow defines who can operate each forward transition:
+- **Order-operable forwards**: `namedOperator === ""` — you can execute via `order.progress`
+- **Permission-operable forwards**: Require specific namespace permission — typically for Service Provider or collaborators
 
-When advancing through a node that requires Guard validation with submitted data:
+**Steps**:
+1. Query Order object to get `progress` (Progress ID) and `machine` (Machine ID)
+2. Query Progress object to get `current_node`
+3. Query Machine table to find valid transitions from current node
+
+**Tools**: 
+- `query_toolkit` with `onchain_objects` query type
+- `query_toolkit` with `onchain_table` query type
+
+> **Note**: Service Providers or their collaborators may operate other forwards directly via Progress if the Machine design grants them permission. The Machine consensus is immutable — both parties operate within the same transparent rules.
+
+### 4.3 Path Selection & Game Theory
+
+**Core Principle**: Same transparent rules, different optimal paths based on interests.
+
+**Example Scenario**:
 
 ```
-onchain_operations({
-  operation_type: "progress",
-  data: {
-    object: "<progress_id>",
-    order: "<order_name>",
-    node: { name: "Shipping", forward: 0 },
-    pairs: [{ name: "prev_node", value: "Order Confirmed" }]
-  }
-})
+Current Node: "delivery_pending"
+├── Path A → "delivery_confirmed"
+│   ├── Guard: buyer signs receipt
+│   └── Allocation: 95% seller, 5% platform
+│
+├── Path B → "dispute_filed"
+│   ├── Guard: arbitration requested
+│   └── Allocation: funds frozen
+│
+└── Path C → "return_initiated"
+    ├── Guard: within return window
+    └── Allocation: 90% refund, 10% fee
 ```
 
-For the Shipping node (which requires a Merkle root Guard), the Guard's `table` expects a submitted Merkle root string. The `pairs` field carries the runtime data the Guard validates.
+**AI Decision Framework**:
+
+1. **Query all valid paths** from current node
+2. **Evaluate Guard conditions** for each path
+3. **Assess Allocation impact** (query `service.order_allocators`)
+4. **Present options** with consequences:
+
+| Path | Guard Required | Financial Outcome | Best For |
+|------|----------------|-------------------|----------|
+| A | Sign receipt | Pay seller 95% | Satisfied customer |
+| B | Request arbitration | Frozen | Disputed order |
+| C | Return in window | 90% refund | Unsatisfied customer |
+
+**AI Guidance**:
+- Always present ALL available paths
+- Explain Guard requirements
+- Map to Allocation consequences
+- Recommend based on user's goals and evidence
+
+---
+
+## Phase 5: Arbitration (When Needed)
+
+When disputes cannot be resolved directly, use third-party Arbitration.
+
+### 5.1 Arbitration Process
+
+| Step | Operation | Key Points |
+|------|-----------|------------|
+| 1 | `arbitration.dispute` | Create Arb object, **pay fee separately** (NOT from Order) |
+| 2 | Generate WTS | Export Messenger history as tamper-proof evidence |
+| 3 | Send evidence | Via Messenger to Arbitration's contact (encrypted) |
+| 4 | `order.arb_confirm` | Signal "all evidence submitted" |
+| 5 | Wait for voting | Arbitration organizes voters |
+| 6 | `order.arb_objection` | (Optional) Object to unfavorable result |
+| 7 | `order.arb_claim_compensation` | Claim payout from `service.compensation_fund` |
 
-### Arbitration Patterns
+**Schema References**:
+- `schema_query({ action: "get", name: "onchain_operations_arbitration" })`
+- `schema_query({ action: "get", name: "onchain_operations_order" })`
+- `schema_query({ action: "get", name: "messenger_operation" })`
 
-**From [Travel](../examples/Travel/Travel.md) — Pre-Service Arbitration**
+### 5.2 Key Rules
 
-Arbitration can be created before the Service and bound during Service creation/update:
+- **Multiple Arb Objects**: Can arbitrate on multiple services simultaneously
+- **One Compensation**: Only ONE claim per Order (choose best result)
+- **Time Sensitivity**: Long arbitration may exceed order deadlines — discuss timelines pre-purchase
+- **Evidence Privacy**: WTS files verify authenticity via `messenger_operation` with `verify_wts` operation
+
+### 5.3 Arb Object Lifecycle
 
 ```
-// Create Arbitration independently:
-onchain_operations({
-  operation_type: "arbitration",
-  data: {
-    object: { name: "travel_arbitration_v1", permission: "travel_permission_v1" },
-    description: "Arbitration for Iceland travel service disputes"
-  }
-})
-
-// Bind during Service update:
-onchain_operations({
-  operation_type: "service",
-  data: {
-    object: "travel_service_v1",
-    arbitrations: { op: "add", objects: ["travel_arbitration_v1"] }
-  }
-})
+Principal_confirming → Arbitrator_confirming → Voting → Arbitrated → Objectionable → Finished/Withdrawn
 ```
 
-### Sub-Order (Supply Chain) Patterns
+---
 
-**From [Travel](../examples/Travel/Travel.md) — Insurance Sub-Order**
+## Fund Management
 
-The Travel workflow creates a sub-order on the Insurance Service as part of its Machine progression. The "Buy Insurance" node's forward includes `forward_to_order_create` which automatically creates an order on the insurance service when the travel order reaches that node.
+### Receiving Funds (`order.receive`)
 
-The Insurance Service must already be deployed and published before the Travel Service creates sub-orders on it. See [wowok-build](../wowok-build/SKILL.md) Pattern C: Repository-Linked for the build order.
+Extract funds sent to Order (compensation, penalties, rewards) to your wallet.
 
-### Order Lifecycle Summary (from tested examples)
+**Operation**: `onchain_operations` with `operation_type: "order"` and `receive` field.
 
-```
-1. SERVICE SETUP (one-time)
-   Permission → Guard(s) → Machine → Service (with allocation) → Publish
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_order" })`
 
-2. ORDER CREATION (per transaction)
-   onchain_operations(operation_type: "service", data: { object, order_new: { buy: { items, total_pay } } })
+**Sources**:
+- Arbitration compensation (from `service.compensation_fund`)
+- Service penalties (late delivery, quality issues)
+- Collaboration payments
+- Direct transfers
 
-3. PROGRESS ADVANCEMENT (multi-step)
-   onchain_operations(operation_type: "progress", data: { object, order, node: { name, forward } })
+**Who Can Execute**: Builder and agents (but only builder receives).
 
-4. FUND DISTRIBUTION (automatic on completion)
-   Allocation fires → Payment split per allocator Guards
+### Ownership Transfer (`order.transfer_to`)
 
-5. REWARD CLAIMS (on trigger nodes)
-   Reward Guard validates → tokens distributed to claimant
+Transfer order ownership to new address. Requires builder permission.
 
-6. DISPUTE RESOLUTION (if needed)
-   Arbitration → arb_confirm/arb_objection → resolution
-```
+**Operation**: `onchain_operations` with `operation_type: "order"` and `transfer_to` field.
 
 ---
 
-## Payments & Refunds Rules
+## Quick Reference
+
+### Essential Schemas
+
+| Purpose | Schema Name |
+|---------|-------------|
+| Service operations (purchase) | `onchain_operations_service` |
+| Order operations (progress, arbitration, receive) | `onchain_operations_order` |
+| Arbitration operations (dispute) | `onchain_operations_arbitration` |
+| Messenger (encrypted communication) | `messenger_operation` |
+| Query toolkit (object data, tables) | `query_toolkit` |
+
+**Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
+
+### Common Workflows
+
+**Evaluate → Communicate → Purchase → Track → Complete/Dispute**
+
+1. Query Service → Check sales, machine, allocators, arbitrations
+2. Messenger contact → Clarify terms, save WTS
+3. Service operation → Create order with named objects
+4. Order operations → Advance progress, choose paths
+5. Receive funds or arbitration → Extract to wallet
+
+---
 
-- **Service purchase**: Always pay through `Service`. Name the generated `Order`, `Progress`, and `Allocation` via `namedNew*` fields for easy management.
-- **Order operations**: All order user operations MUST go through the `Order` object — do not operate on `Progress` directly for order-related actions.
-- **Refunds/withdrawals**: Users satisfy `Allocation` Guard conditions to withdraw instantly.
-- **Arbitration claims**: Compensation payouts go through `Order`.
-- **Alternative payments**: `account_operation (transfer)` for direct wallet-to-wallet, or `onchain_operations (payment)` for commercial features (purpose tracking, Guard validation).
+## Safety Checklist
+
+Before purchasing:
+- [ ] Verified WIP file and product claims
+- [ ] Reviewed allocators (fair distribution?)
+- [ ] Checked available arbitrations
+- [ ] Established Messenger contact with seller
+- [ ] Clarified deliverables, timeline, refund policy
+- [ ] Saved conversation as WTS evidence
+
+Before advancing progress:
+- [ ] Understand ALL available paths
+- [ ] Know Guard requirements for chosen path
+- [ ] Aware of Allocation consequences
+- [ ] Have required evidence/proof ready