@wowok/skills 2.2.2 → 2.2.4

package/examples/MyShop/MyShop.md

@@ -8,7 +8,7 @@ A complete e-commerce example demonstrating how to build an online store using W
 
 > **Run the example in full every time (repeatable).** This example uses `replaceExistName: true` on all object creations — each run generates new objects with new addresses. If you skip build steps, operations may silently act on orphaned objects from previous runs, producing incorrect results. Old objects' configurations do not reflect the current document version.
 
-- **Execution order**: Part 1 (Merchant Setup, Steps 1–7) → Part 2 (Customer Flow, Steps 1–9). Run all build steps in sequence before testing any customer flow. Do not skip steps — each depends on objects created by prior steps.
+- **Execution order**: Part 1 (Merchant Setup, Steps 1–8) → Part 2 (Customer Flow, Steps 1–9). Run all build steps in sequence before testing any customer flow. Do not skip steps — each depends on objects created by prior steps.
 - **Prerequisites**: `myshop_merchant` with sufficient WOW for gas and order operations. All on-chain operations require `env.confirmed: true`.
 
 > **💡 Call Format**: All WoWok operations go through a single unified `wowok` tool. The AI calls `wowok({ tool: "<sub-tool>", data: {<params>} })`. If parameters don't match the schema, the response includes the correct schema for self-correction. See [Response Format](../../docs/response-format.md) for details.
@@ -426,6 +426,8 @@ Create a Contact object to enable encrypted communication between customers and
 }
 ```
 
+> **Note**: Enabling messenger now registers the account on the messenger server **immediately and synchronously** — each account registers itself (its own identity, its own keys). The result includes `registered: true` on success, or `registered: false` with `registerError` if the server is unreachable (the background refresh retries automatically every 60s). If the operation result shows `registered: false`, retry the enable operation before proceeding — otherwise the counterpart's first message will fail with "Recipient not registered".
+
 #### 4.2 Create After-Sales Contact Object
 
 **Prompt**: Create a Contact object named "myshop_aftersales_contact_v2" with permission "myshop_permission_v2" for after-sales support.
@@ -465,11 +467,53 @@ Create a Contact object to enable encrypted communication between customers and
 
 ---
 
-### Step 5: Create Guards for Fund Allocation
+### Step 5: Create Service (Store) DRAFT
+
+> **⚠️ Order matters — Service DRAFT must be created BEFORE the Guards.** The Guards in Step 6 reference the Service by name (`myshop_service_v2` as an Address table value). The SDK resolves the name to the on-chain address AT Guard creation time. If the Service does not exist yet, Guard creation aborts with:
+> ```
+> Error: invalid parameter:BCS serialization failed: ... failed to resolve string: myshop_service_v2. Address may not exist in local accounts or marks.
+> ```
+> Create the Service as an unpublished DRAFT here so the name resolves, then bind machine/allocators/sales and publish it in Step 7.
+
+**Prompt**: Create an unpublished Service DRAFT named "myshop_service_v2" (no `publish` field — it stays a DRAFT so Guards can reference it and the mutable fields can still be configured).
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "service",
+    "data": {
+      "object": {
+        "name": "myshop_service_v2",
+        "type_parameter": "0x2::wow::WOW",
+        "permission": "myshop_permission_v2",
+        "tags": ["ecommerce", "toys", "store"],
+        "onChain": false,
+        "replaceExistName": true
+      },
+      "description": "MyShop - Top quality toys for children",
+      "location": "Online Store"
+    },
+    "env": {
+      "account": "myshop_merchant",
+      "network": "mainnet",
+      "confirmed": true
+    }
+  }
+}
+```
+
+> **Note**: After publishing, `machine`, `order_allocators`, and `arbitrations` become **immutable**. Creating the draft first lets the Guards resolve the Service name while the Service is still configurable.
+
+---
+
+### Step 6: Create Guards for Fund Allocation
+
+Before publishing the Service, create Guards that validate fund allocation conditions. These Guards ensure funds are only released when specific conditions are met. The Guards reference the Service DRAFT by name (`myshop_service_v2`), which now resolves to the draft's on-chain address (the address does NOT change when the draft is later published).
 
-Before creating the Service, create Guards that validate fund allocation conditions. These Guards ensure funds are only released when specific conditions are met.
+> **Note**: Guard table item `name` must be ≤ 64 characters (`MAX_NAME_LENGTH`) and must NOT start with `0x`. Descriptive names with spaces/parentheses (e.g. `order_address (Order object submitted at runtime)`) exceed the limit and abort with `invalid parameter:table.name`. Use short identifiers like `order_address`.
 
-#### 5.1 Create Withdraw Guard (Merchant Withdrawal)
+#### 6.1 Create Withdraw Guard (Merchant Withdrawal)
 
 Create a Guard that validates the order's Progress has reached the "Completed" node. This Guard uses `convert_witness: "OrderProgress"` (TypeOrderProgress) to query the Order's associated Progress object.
 
@@ -493,28 +537,28 @@ Create a Guard that validates the order's Progress has reached the "Completed" n
           "identifier": 0,
           "b_submission": true,
           "value_type": "Address",
-          "name": "order_address (Order object submitted at runtime)"
+          "name": "order_address"
         },
         {
           "identifier": 1,
           "b_submission": false,
           "value_type": "String",
           "value": "Completed",
-          "name": "Expected Completed node name (case-sensitive)"
+          "name": "expected_node"
         },
         {
           "identifier": 2,
           "b_submission": false,
           "value_type": "Address",
           "value": "myshop_merchant",
-          "name": "Authorized merchant address (prevents fund theft by unauthorized callers)"
+          "name": "merchant_address"
         },
         {
           "identifier": 3,
           "b_submission": false,
           "value_type": "Address",
           "value": "myshop_service_v2",
-          "name": "Expected service address (prevents cross-service fund theft)"
+          "name": "service_address"
         }
       ],
       "root": {
@@ -594,7 +638,7 @@ Create a Guard that validates the order's Progress has reached the "Completed" n
 >
 > **Note**: The Guard `root` field directly specifies the GuardNode (e.g., `type: "logic_and"`), not wrapped in a `type: "node"` object.
 
-#### 5.2 Create Refund Guard (Customer Refund)
+#### 6.2 Create Refund Guard (Customer Refund)
 
 Create a Guard for customer refunds when order is cancelled.
 
@@ -618,21 +662,21 @@ Create a Guard for customer refunds when order is cancelled.
           "identifier": 0,
           "b_submission": true,
           "value_type": "Address",
-          "name": "order_address (Order object submitted at runtime)"
+          "name": "order_address"
         },
         {
           "identifier": 1,
           "b_submission": false,
           "value_type": "String",
           "value": "Cancelled",
-          "name": "Expected Cancelled node name (case-sensitive)"
+          "name": "expected_node"
         },
         {
           "identifier": 2,
           "b_submission": false,
           "value_type": "Address",
           "value": "myshop_service_v2",
-          "name": "Expected service address (prevents cross-service fund theft)"
+          "name": "service_address"
         }
       ],
       "root": {
@@ -717,13 +761,13 @@ Create a Guard for customer refunds when order is cancelled.
 
 ---
 
-### Step 6: Create Service (Store)
+### Step 7: Publish Service (Store)
 
-Create the Service object that represents your online store with products. This step binds all previously created components together.
+Bind all previously created components (machine, Guards, products, after-sales contact) to the Service DRAFT created in Step 5, then publish it. The Service address stays the same as the DRAFT, so the Guards' `service_address` table values remain valid.
 
-> **Important**: For Service creation, provide a complete configuration including machine, order_allocators with Guards, and products. The Service will be created and published in a single transaction.
+> **Important**: Provide a complete configuration including machine, order_allocators with Guards, and products. The Service is published in a single transaction. After publish, `machine`, `order_allocators`, and `arbitrations` become immutable.
 
-#### 6.1 Understanding Order Allocators
+#### 7.1 Understanding Order Allocators
 
 The `order_allocators` configuration defines how order payments are distributed:
 
@@ -747,9 +791,9 @@ The `order_allocators` configuration defines how order payments are distributed:
 
 > **Design Decision — Refund Recipient**: When using `{ "GuardIdentifier": 0 }` in the refund allocation, the refund is sent to the **Order object's on-chain address** (not the customer's wallet address). This is by design: the Order object acts as an escrow holding the refunded payment at its own address. The customer subsequently claims the refund from the Order object via a separate withdraw operation. This two-step design ensures the refund is traceable on-chain and tied to the specific order, providing better dispute resolution and audit trail.
 
-#### 6.2 Create and Publish Service
+#### 7.2 Publish Service (bind machine + allocators + sales + um)
 
-**Prompt**: Create and publish a Service named "myshop_service_v2" with machine "myshop_machine_v2", order allocation using Guards, after-sales contact, and toy products.
+**Prompt**: Publish the Service DRAFT "myshop_service_v2" (created in Step 5) by binding machine "myshop_machine_v2", order allocation using the Guards, after-sales contact, and toy products. Note `object` is now a STRING reference to the existing draft, and `publish: true` is set.
 
 ```json
 {
@@ -757,16 +801,7 @@ The `order_allocators` configuration defines how order payments are distributed:
   "data": {
     "operation_type": "service",
     "data": {
-      "object": {
-        "name": "myshop_service_v2",
-        "type_parameter": "0x2::wow::WOW",
-        "permission": "myshop_permission_v2",
-        "tags": ["ecommerce", "toys", "store"],
-        "onChain": false,
-        "replaceExistName": true
-      },
-      "description": "MyShop - Top quality toys for children",
-      "location": "Online Store",
+      "object": "myshop_service_v2",
       "machine": "myshop_machine_v2",
       "order_allocators": {
         "description": "Order revenue allocation - merchant withdraw after completion",
@@ -802,7 +837,7 @@ The `order_allocators` configuration defines how order payments are distributed:
             "price": 50000000,
             "stock": 100,
             "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
+            "wip": "https://raw.githubusercontent.com/wowok-ai/docs/main/wip-examples/three_body.wip",
             "wip_hash": ""
           },
           {
@@ -810,7 +845,7 @@ The `order_allocators` configuration defines how order payments are distributed:
             "price": 50000000,
             "stock": 50,
             "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
+            "wip": "https://raw.githubusercontent.com/wowok-ai/docs/main/wip-examples/three_body.wip",
             "wip_hash": ""
           },
           {
@@ -818,7 +853,7 @@ The `order_allocators` configuration defines how order payments are distributed:
             "price": 30000000,
             "stock": 75,
             "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
+            "wip": "https://raw.githubusercontent.com/wowok-ai/docs/main/wip-examples/three_body.wip",
             "wip_hash": ""
           }
         ]
@@ -842,7 +877,7 @@ The `order_allocators` configuration defines how order payments are distributed:
 
 ---
 
-### Step 7: Update Product Pricing (Optional)
+### Step 8: Update Product Pricing (Optional)
 
 To offer promotional pricing, update product prices using the `sales` operation with `op: "set"`:
 
@@ -863,7 +898,7 @@ To offer promotional pricing, update product prices using the `sales` operation
             "price": 40000000,
             "stock": 100,
             "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
+            "wip": "https://raw.githubusercontent.com/wowok-ai/docs/main/wip-examples/three_body.wip",
             "wip_hash": ""
           }
         ]
@@ -963,7 +998,7 @@ Customer creates an order by purchasing products from the Service.
             {
               "name": "Play Purse Set 35PCS",
               "stock": 1,
-              "wip_hash": "03c18561efa8faf4d75480eb1f732c4a46ffde95599e92eca06167785fc07a5b"
+              "wip_hash": "<wip_hash captured from Step 1 query>"
             }
           ],
           "total_pay": {
@@ -1053,6 +1088,8 @@ After creating the order, the customer sends their shipping address and contact
 }
 ```
 
+> **Note**: Same as merchant enable (Step 4.1): registration on the messenger server happens synchronously with the enable. Each party must enable messenger **in its own environment with its own account** — one side can never register the other.
+
 #### 2.1.2 Customer Sends Shipping Information
 
 **Prompt**: Customer "myshop_customer" sends shipping address and contact information to merchant "myshop_merchant" via encrypted messenger.
@@ -1691,7 +1728,7 @@ Create a new order for testing the arbitration flow (if you don't have one alrea
             {
               "name": "Tree House Building Set",
               "stock": 1,
-              "wip_hash": "03c18561efa8faf4d75480eb1f732c4a46ffde95599e92eca06167785fc07a5b"
+              "wip_hash": "<wip_hash captured from Step 1 query>"
             }
           ],
           "total_pay": {"balance": 30000000}

package/examples/ThreeBody_Signature/ThreeBody_Signature.md

@@ -18,7 +18,7 @@ This example sets `env.confirmed: true` on irreversible operations (e.g., `publi
 1. **Phase 1 — Preview**: Call the tool **without** `env.confirmed`. The server returns `{ status: "pending_confirmation", confirmation_text: "..." }` containing the full operation summary, risk assessment, and irreversible-action warnings.
 2. **Phase 2 — Confirm**: Review `confirmation_text` with the user. Only after explicit user approval, call the tool again **with** `env.confirmed: true` to actually execute the on-chain transaction.
 
-> Skipping Phase 1 means the user never sees the risk summary before gas is spent. Always preview first, then confirm. This is especially critical for the two `publish: true` steps in this doc: the Machine publish (**Step 3**), which irreversibly locks the workflow definition (`nodes`/`pairs`/`forwards`), and the Service publish (**Step 10**), which irreversibly locks the `machine` and `order_allocators` fields.
+> Skipping Phase 1 means the user never sees the risk summary before gas is spent. Always preview first, then confirm. This is especially critical for the two `publish: true` steps in this doc: the Machine publish (**Step 3**), which irreversibly locks the workflow definition (`nodes`/`pairs`/`forwards`), and the Service publish (**Step 11**), which irreversibly locks the `machine` and `order_allocators` fields.
 
 > **💡 Call Format**: All WoWok operations go through a single unified `wowok` tool. The AI calls `wowok({ tool: "<sub-tool>", data: {<params>} })`. If parameters don't match the schema, the response includes the correct schema for self-correction. See [Response Format](../../docs/response-format.md) for details.
 >
@@ -719,7 +719,70 @@ Create a Treasury object to aggregate signature service revenue (public funds fo
 
 ---
 
-## Step 8: Create Allocator Guard
+## Step 8: Create Contact Object (Customer-Service Channel)
+
+Create a Contact object to serve as the Service's encrypted customer-service channel. **Whenever `customer_required` is set (e.g. phone/email/shipping address), a Contact MUST be bound via the `um` field** — the customer's private information is delivered exclusively through end-to-end encrypted Messenger, which routes messages to the Contact bound as `um`. Without `um`, there is no channel to receive the customer's privacy-sensitive input and the SDK blocks the call with an invalid parameter error. The Contact uses the same Permission as the Service (`three_body_permission`) for unified governance.
+
+**Request**:
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "contact",
+    "data": {
+      "object": {
+        "name": "three_body_contact",
+        "permission": "three_body_permission",
+        "replaceExistName": true
+      },
+      "description": "Contact for Three-Body signature service customer info — end-to-end encrypted Messenger channel for delivery of phone/email/shipping_address collected via customer_required."
+    },
+    "env": {
+      "account": "three_body_author",
+      "network": "testnet",
+      "confirmed": true
+    }
+  }
+}
+```
+
+> **Why a Contact is required with customer_required (SDK-enforced hard linkage)**:
+> - `customer_required` tells the order flow which private-info labels to collect from the buyer (phone, email, shipping_address, etc.)
+> - Those labels are delivered to the merchant ONLY through the end-to-end encrypted Messenger protocol
+> - Messenger routes messages to the Service's bound Contact object (the `um` field)
+> - Without `um`, the collected private information would be silently dropped — there is no other delivery path
+> - The SDK's `checkCustomerRequiredNeedsUm()` validator in `service.ts` (L1226) runs on EVERY service operation that touches `customer_required` AND on `publish: true`, so the constraint cannot be bypassed by splitting into two calls
+
+> **Important**: `env.confirmed: true` is required because `replaceExistName: true` triggers a confirmation prompt.
+
+**Expected Result**:
+```json
+{
+  "result": {
+    "status": "success",
+    "data": {
+      "result": {
+        "type": "transaction",
+        "objectChanges": [
+          {
+            "type": "Contact",
+            "type_raw": "0x2::contact::Contact",
+            "object": "0x...",
+            "version": "...",
+            "owner": {"Shared": {"initial_shared_version": "..."}},
+            "change": "created"
+          }
+        ]
+      }
+    }
+  },
+  "schema": null
+}
+```
+
+---
+
+## Step 9: Create Allocator Guard
 
 Create a dedicated Guard for the order allocator that verifies the order belongs to this service. This is a **Level 3 scene-combined** Guard: no Signer binding is needed because the allocator uses `sharing.who=Entity(three_body_treasury)` — funds always flow to the fixed Treasury regardless of who triggers the allocation.
 
@@ -819,9 +882,9 @@ order.service == three_body_signature_service
 
 ---
 
-## Step 9: Configure Order Allocators
+## Step 10: Configure Order Allocators
 
-Set up fund allocation: 100% to the author's Treasury upon order completion.
+Set up fund allocation: 100% to the author's Treasury upon order completion. Also bind the Contact (Step 8) as `um` to enable the `customer_required` private-info delivery channel — the SDK blocks `customer_required` without a matching `um` (see Step 8 for the rationale).
 
 **Request**:
 ```json
@@ -849,7 +912,8 @@ Set up fund allocation: 100% to the author's Treasury upon order completion.
           }
         ]
       },
-      "customer_required": ["phone", "email", "shipping_address"]
+      "customer_required": ["phone", "email", "shipping_address"],
+      "um": "three_body_contact"
     },
     "env": {
       "account": "three_body_author",
@@ -860,9 +924,10 @@ Set up fund allocation: 100% to the author's Treasury upon order completion.
 ```
 
 > **⚠️ Risk Elimination — Why this configuration is safe**:
-> - **R-C3-05 (Cross-service theft)**: Eliminated by `three_body_allocator_guard` (Step 8), which verifies `order.service == three_body_signature_service` before allocation proceeds.
+> - **R-C3-05 (Cross-service theft)**: Eliminated by `three_body_allocator_guard` (Step 9), which verifies `order.service == three_body_signature_service` before allocation proceeds.
 > - **R-C3-06 (Fund theft via Signer)**: Eliminated by `sharing.who = {"Entity": {"name_or_address": "three_body_treasury"}}` — funds always flow to the fixed Treasury address regardless of who triggers the allocation. An attacker cannot redirect funds to themselves even if they somehow bypass the Guard.
 > - **Previous unsafe pattern (DO NOT USE)**: The original design used `guard: "three_body_buy_guard"` (no `order.service` check) with `sharing.who = {"Signer": "signer"}` — this allowed anyone to trigger allocation of any order's funds to themselves.
+> - **SDK-enforced constraint (customer_required ⟶ um)**: `"customer_required"` is set alongside `"um": "three_body_contact"` in the SAME call. The SDK validator `checkCustomerRequiredNeedsUm()` in `service.ts` L1226 also runs on publish (L314), so splitting into two calls (e.g. `customer_required` now, `um` later) would still fail at publish time — they are both required before the Service goes live.
 
 **Expected Result**:
 ```json
@@ -891,7 +956,7 @@ Set up fund allocation: 100% to the author's Treasury upon order completion.
 
 ---
 
-## Step 10: Add Sales and Publish Service
+## Step 11: Add Sales and Publish Service
 
 Add sales items and publish the service to make it available for orders.
 
@@ -956,7 +1021,7 @@ Add sales items and publish the service to make it available for orders.
 
 ---
 
-## Step 11: Unpause Service
+## Step 12: Unpause Service
 
 Unpause the service to allow order creation.
 
@@ -1005,7 +1070,7 @@ Unpause the service to allow order creation.
 
 ---
 
-## Step 12: Verify Service Configuration
+## Step 13: Verify Service Configuration
 
 Query the service to verify all configurations.
 
@@ -1080,7 +1145,7 @@ Query the service to verify all configurations.
                 ]
               },
               "rewards": [],
-              "um": null,
+              "um": "0x...",
               "permission": "0x...",
               "cache_expire": 1234567890,
               "query_name": "three_body_signature_service"
@@ -1095,9 +1160,10 @@ Query the service to verify all configurations.
 ```
 
 > **Field Reference**:
-> - **`buy_guard`**, **`machine`**, **`permission`**: Return **on-chain object IDs** (not names). The on-chain data stores raw object IDs; resolving them back to local mark names requires a separate reverse lookup that is not performed by `onchain_objects` queries.
+> - **`buy_guard`**, **`machine`**, **`permission`**, **`um`**: Return **on-chain object IDs** (not names). The on-chain data stores raw object IDs; resolving them back to local mark names requires a separate reverse lookup that is not performed by `onchain_objects` queries.
 > - **`query_name`**: The original name string passed in the query request (here, `"three_body_signature_service"`). This is automatically populated by the SDK from the input `objects` array, so you can identify which queried name corresponds to which returned object.
-> - **`order_allocators.allocators[].guard`**: Returns the on-chain object ID of `three_body_allocator_guard` (created in Step 8). This Guard verifies `order.service == three_body_signature_service` (R-C3-05 protection).
+> - **`um`**: The on-chain object ID of `three_body_contact` (created in Step 8). The SDK validator `checkCustomerRequiredNeedsUm()` requires this whenever `customer_required` is non-empty — without a Contact the Service has no encrypted channel to receive customer private info.
+> - **`order_allocators.allocators[].guard`**: Returns the on-chain object ID of `three_body_allocator_guard` (created in Step 9). This Guard verifies `order.service == three_body_signature_service` (R-C3-05 protection).
 > - **`order_allocators.allocators[].sharing[].who`**: `{"Entity": "0x..."}` indicates funds flow to the fixed Treasury object (`three_body_treasury` from Step 7). The address is the Treasury's on-chain object ID. This eliminates R-C3-06 (fund theft via Signer) because the recipient is fixed regardless of caller.
 > - **`order_allocators.allocators[].sharing[].mode`**: `1` is the numeric enum for `Rate` mode (input accepts the string `"Rate"`, output returns the numeric `1`).
 > - **`order_allocators.allocators[].fix`** and **`max`**: Additional fields returned on-chain (default `"0"` and `null` respectively) that are not part of the input schema but are present in the on-chain data structure.
@@ -1154,7 +1220,7 @@ The author (`three_body_author`) should be able to purchase the service.
 }
 ```
 
-> **Amount Format**: `"888WOW"` is the display format — the Fund Processing Layer converts it to `888000000000` smallest units (WOW has 9 decimals) before submission. The raw integer `888000000000` is equally valid. The order pays exactly the sale price set in Step 10.
+> **Amount Format**: `"888WOW"` is the display format — the Fund Processing Layer converts it to `888000000000` smallest units (WOW has 9 decimals) before submission. The raw integer `888000000000` is equally valid. The order pays exactly the sale price set in Step 11.
 
 **Expected Result**:
 ```json
@@ -1435,7 +1501,7 @@ The author completes the signature.
 
 ### Fund Allocation: Release the 888 WOW Payment to the Treasury
 
-Once the Progress reaches the final node (`Signature Completed`), the order is fulfilled and the 888 WOW payment held by `three_body_allocation` can be distributed. The Service's `order_allocators` (Step 9) routes 100% to `three_body_treasury` when `three_body_allocator_guard` (Step 8) verifies `order.service == three_body_signature_service`.
+Once the Progress reaches the final node (`Signature Completed`), the order is fulfilled and the 888 WOW payment held by `three_body_allocation` can be distributed. The Service's `order_allocators` (Step 10) routes 100% to `three_body_treasury` when `three_body_allocator_guard` (Step 9) verifies `order.service == three_body_signature_service`.
 
 #### (a) Trigger the Allocation (`alloc_by_guard`)
 
@@ -1690,6 +1756,7 @@ This example demonstrates:
 | Machine | three_body_machine |
 | Service | three_body_signature_service |
 | Treasury | three_body_treasury |
+| Contact (um) | three_body_contact (required for customer_required — SDK-enforced customer_required ⟶ um linkage) |
 | Allocator Guard | three_body_allocator_guard (Level 3 scene-combined, R-C3-05/R-C3-06 safe) |
 | Order | three_body_order |
 | Allocation | three_body_allocation |
@@ -1739,7 +1806,8 @@ Each node transition requires the author's confirmation, ensuring accountability
    - Service (unpublished)
    - Guards (Buy Guard for purchase control; Allocator Guard needs Service address for `order.service` verification)
    - Treasury (uses same Permission as Service for unified governance)
-   - Configure Service (add machine, buy_guard, order_allocators with allocator guard + Entity(Treasury))
+   - Contact (um) — REQUIRED before setting customer_required (SDK-enforced: customer_required ⟶ um hard linkage; validator also re-runs at publish time)
+   - Configure Service (add machine, buy_guard, order_allocators with allocator guard + Entity(Treasury); set customer_required **together with** um in the same or prior call)
    - Publish Service (LAST - once published, many changes are blocked)
 
 3. **Treasury-First Fund Flow**: Always route merchant revenue through a Treasury object using `sharing.who = {"Entity": {"name_or_address": "treasury_name"}}` instead of `{"Signer": "signer"}`. This eliminates R-C3-06 (critical fund theft via Signer) because funds flow to a fixed recipient regardless of who triggers the allocation. Combined with an allocator Guard that verifies `order.service == this_service` (R-C3-05 protection), the fund allocation becomes inherently safe.
@@ -1751,8 +1819,13 @@ Each node transition requires the author's confirmation, ensuring accountability
 
 5. **Use `no_cache: true` for Sequential Operations**: When performing multiple operations on the same object in sequence (especially Progress workflow advancement), always set `no_cache: true` in the `env` to ensure the SDK reads the latest on-chain state.
 
-6. **Query Toolkit is Your Best Friend**: Use queries constantly to verify objects exist, check configurations, debug issues, and confirm state changes.
+6. **customer_required ⟶ um (Contact) Hard Linkage (SDK-enforced)**: Whenever you set `customer_required` (e.g. `["phone", "email", "shipping_address"]`), you MUST also bind a Contact object via `um` in the SAME or a prior Service call. The SDK's `checkCustomerRequiredNeedsUm()` validator in `ts-sdk/packages/wowok/src/w/call/service.ts` (L1226) runs at TWO points:
+   - When `customer_required` is present in the current operation `data` (immediate block, L307)
+   - When `publish: true` is set (re-verifies against the accumulated Service state, L314)
+   This means splitting the two calls (set `customer_required` first, add `um` later) is NOT safe — the publish-time re-check would still block. Always create the Contact first, then set both `customer_required` and `um` together.
+
+7. **Query Toolkit is Your Best Friend**: Use queries constantly to verify objects exist, check configurations, debug issues, and confirm state changes.
 
-7. **Object IDs vs Names in Responses**: On-chain query responses return **object IDs** (e.g., `0x8202...`) for cross-object references like `buy_guard`, `machine`, `permission`. The `query_name` field in the response echoes back the original query input name. To resolve object IDs back to local mark names, use `query_toolkit` with `query_type: "local_names"`.
+8. **Object IDs vs Names in Responses**: On-chain query responses return **object IDs** (e.g., `0x8202...`) for cross-object references like `buy_guard`, `machine`, `permission`, `um`. The `query_name` field in the response echoes back the original query input name. To resolve object IDs back to local mark names, use `query_toolkit` with `query_type: "local_names"`.
 
-8. **Information Injection in Transaction Responses**: Mutation/creation operations return ALL objects affected by the transaction (including side effects like `TableItem_EntityLinker` and `TableItem_ProgressHistory`), not just the primary target. This is a deliberate design for transparency. The return order reflects the transaction's execution order.
+9. **Information Injection in Transaction Responses**: Mutation/creation operations return ALL objects affected by the transaction (including side effects like `TableItem_EntityLinker` and `TableItem_ProgressHistory`), not just the primary target. This is a deliberate design for transparency. The return order reflects the transaction's execution order.

package/examples/Travel/Travel.md

@@ -225,7 +225,7 @@ Day 5: 1783900800000 (2026-07-13T00:00:00.000Z)
           {
             "name": "Condition",
             "description": "Weather condition policy for activity dates",
-            "write_guard": [],
+            "write_guard": [{ "guard": "weather_write_guard" }],
             "id_from": "None",
             "value_type": "String"
           }
@@ -243,6 +243,8 @@ Day 5: 1783900800000 (2026-07-13T00:00:00.000Z)
 ```
 
 > **Note**: `onChain: true` is required here because `weather_repo` is created by the `weather_provider` account, but its name will be referenced in the Guard table (Step 3.1) by the `travel_provider` account. Without `onChain: true`, the name is stored locally only on `weather_provider`'s device and cannot be resolved by `travel_provider`. When `onChain: true` is set, the name is published on-chain and becomes publicly visible, allowing cross-account name resolution.
+>
+> The `write_guard` in the "Condition" policy points to `weather_write_guard` (created above). Because `id_from: "None"` lets the writer choose data ids, the contract mandates a Guard to authorize writes. `data_add` in Step 0.4 needs no Guard submission — the Guard is always-true with no submission fields.
 
 ### 0.4 Add Weather Data
 
@@ -1117,11 +1119,7 @@ Configure the travel service (created unpublished in Step 2.5) with all bindings
   "data": {
     "operation_type": "service",
     "data": {
-      "object": {
-        "name": "travel_service",
-        "permission": "travel_permission",
-        "replaceExistName": true
-      },
+      "object": "travel_service",
       "description": "Iceland travel service: Blue Lagoon SPA + Glacier Ice Scooting.",
       "machine": "travel_machine",
       "sales": {
@@ -1200,6 +1198,8 @@ Configure the travel service (created unpublished in Step 2.5) with all bindings
 }
 ```
 
+> **Note**: `object` uses a plain string reference (`"travel_service"`) so this call **configures the draft Service created in Step 2.5**. Passing a full object definition block (`{name, permission, replaceExistName}`) here would create a brand-new Service object instead — orders and allocator Guard bindings pointing at the old draft would then fail validation.
+
 **order_allocators Field Reference**:
 
 | Field | Type | Description |
@@ -1542,21 +1542,17 @@ The allocation Guard requires the Order ID as a submission (identifier: 0). Quer
 
 ```json
 {
-  "tool": "onchain_operations",
+  "tool": "query_toolkit",
   "data": {
-    "operation_type": "progress",
-    "data": {
-      "object": "alice_travel_progress"
-    },
-    "env": {
-      "network": "testnet",
-      "no_cache": true
-    }
+    "query_type": "onchain_objects",
+    "objects": ["alice_travel_progress"],
+    "network": "testnet",
+    "no_cache": true
   }
 }
 ```
 
-> **Note**: The response includes a `task` field containing the Order object ID. Copy this value for the allocation submission.
+> **Note**: Use `query_toolkit` (not `onchain_operations`) for read-only lookups — queries consume no gas and never mutate state. The response includes a `task` field containing the Order object ID. Copy this value for the allocation submission.
 
 ### 8.2 Execute Allocation (Merchant Victory Path)
 
@@ -1669,16 +1665,12 @@ After allocation, query the Allocation and Payment objects to verify the fund di
 
 ```json
 {
-  "tool": "onchain_operations",
+  "tool": "query_toolkit",
   "data": {
-    "operation_type": "allocation",
-    "data": {
-      "object": "alice_travel_allocation"
-    },
-    "env": {
-      "network": "testnet",
-      "no_cache": true
-    }
+    "query_type": "onchain_objects",
+    "objects": ["alice_travel_allocation"],
+    "network": "testnet",
+    "no_cache": true
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "WoWok AI Skills for Claude and other AI assistants - Dialogue orchestration layer on top of the WoWok MCP server (rules/reference knowledge is served by MCP directly since v2.0.0)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/install.js

@@ -25,7 +25,7 @@ const { execSync } = require('child_process');
  * into the MCP knowledge layer and are served by the MCP server directly:
  *   - wowok-safety   → schema_query action='get_safety_rules'
  *   - wowok-tools    → schema_query action='get_tool_reference'
- *   - wowok-scenario → project_operation recommend_industry / create_project
+ *   - wowok-scenario → industry_pack_operation recommend_industry / list_modes
  *   - wowok-guard    → schema_query action='get_guard_design_patterns'
  */
 const SKILL_DIRS = [
@@ -59,7 +59,7 @@ const LEGACY_SKILL_DIRS = [
 const SKILL_MIGRATION_MAP = {
   'wowok-safety': "MCP schema_query action='get_safety_rules'",
   'wowok-tools': "MCP schema_query action='get_tool_reference'",
-  'wowok-scenario': "MCP project_operation action='recommend_industry' / 'create_project'",
+  'wowok-scenario': "MCP industry_pack_operation action='recommend_industry' / 'list_modes'",
   'wowok-guard': "MCP schema_query action='get_guard_design_patterns'",
 };
 

package/wowok-arbitrator/SKILL.md

@@ -28,9 +28,9 @@ The following content has been pushed down to the MCP knowledge layer and is app
 
 | Content | Access via (MCP action) | Applied Via |
 |---------|--------------------------|-------------|
-| Guard design rules (structural layers, data source classification, voting_guard table design) | `schema_query` action='get_guard_design_patterns' | `project_operation.evaluate_project` |
-| Safety rules (confirmation levels, immutability, object reuse) | `schema_query` action='get_safety_rules' | Pre-publish checks + `project_operation.evaluate_project` |
-| Arbitration-specific risks | auto-applied | `project_operation.evaluate_project` |
+| Guard design rules (structural layers, data source classification, voting_guard table design) | `schema_query` action='get_guard_design_patterns' | `goal_operation` action='aggregate_risks' |
+| Safety rules (confirmation levels, immutability, object reuse) | `schema_query` action='get_safety_rules' | Pre-publish checks + `goal_operation` action='aggregate_risks' |
+| Arbitration-specific risks | auto-applied | `goal_operation` action='aggregate_risks' |
 
 This Skill keeps the arbitration **conversation flow**, **evidence collection** scripts, and **dispute resolution** guidance — the MCP layer handles the rule evaluation.
 
@@ -42,7 +42,7 @@ These four principles govern every arbitration build/handle step. They mirror th
 
 1. **Review-first**: State (a) what the AI understood about the arbitration, (b) the dependency order to build, and (c) the interaction contract — before the first choice.
 2. **User-driven**: Every step is an explicit user decision; the AI provides a `recommend` but never auto-advances.
-3. **Reuse / Customize / Discover (三选一)**: For every component (Permission, Voting/Usage Guards, Contact), surface all three avenues — reuse an existing object, customize a new one, or discover from other projects / the system.
+3. **Reuse / Customize / Discover (choose one of three)**: For every component (Permission, Voting/Usage Guards, Contact), surface all three avenues — reuse an existing object, customize a new one, or discover from other projects / the system.
 4. **Default-config disclosure**: Disclose a new object's default config + important info + caveats BEFORE the user decides. No silent defaults.
 
 ---

package/wowok-auditor/SKILL.md

@@ -38,9 +38,9 @@ The following content has been pushed down to the MCP knowledge layer and is app
 
 | Content | Access via (MCP action) | Applied Via |
 |---------|--------------------------|-------------|
-| Safety rules (confirmation levels, immutability rules, object reuse rules) | `schema_query` action='get_safety_rules' | Pre-publish checks + `project_operation.evaluate_project` |
-| Machine-executable audit rules | auto-applied (not queryable) | `project_operation.evaluate_project` |
-| Guard completeness / Machine soundness / fund-flow risks | auto-applied (not queryable) | `project_operation.evaluate_project` |
+| Safety rules (confirmation levels, immutability rules, object reuse rules) | `schema_query` action='get_safety_rules' | Pre-publish checks + `goal_operation` action='aggregate_risks' |
+| Machine-executable audit rules | auto-applied (not queryable) | `goal_operation` action='aggregate_risks' |
+| Guard completeness / Machine soundness / fund-flow risks | auto-applied (not queryable) | `goal_operation` action='aggregate_risks' |
 
 This Skill keeps the **audit flow**, the **4 audit dimensions** (Guard completeness, Machine soundness, fund flow, publish readiness), and the **checklist structure** as the human-readable knowledge base for the L4 Harness Verify Loop. The MCP layer runs the machine-executable rule evaluation.