@wowok/agent-mcp 2.6.7 → 2.6.9

package/dist/customer/customer-advice.js

@@ -79,6 +79,7 @@ function buildReminderContext(puzzle, risk, overrides) {
         risk_level: risk.level,
         has_refund_path: wf?.has_refund_path,
         has_messenger: trust?.has_messenger,
+        customer_required: puzzle.service_basics.customer_required,
         ...overrides,
     };
 }

package/dist/customer/info-puzzle.js

@@ -14,6 +14,7 @@ export function assembleServiceBasics(serviceId, raw, wipVerified = false) {
         machine_id: raw.machine,
         buy_guard_id: raw.buy_guard,
         customer_required_count: raw.customer_required?.length ?? 0,
+        customer_required: (raw.customer_required ?? []).filter((x) => typeof x === "string"),
         arbitrations_count: raw.arbitrations?.length ?? 0,
         compensation_fund_balance: raw.compensation_fund?.balance ?? 0n,
         compensation_lock_duration: raw.compensation_lock_duration ?? 0,

package/dist/customer/reminder-system.d.ts

@@ -20,6 +20,7 @@ export interface ReminderContext {
     has_refund_path?: boolean;
     has_user_operable?: boolean;
     has_messenger?: boolean;
+    customer_required?: string[];
     ambiguous_guards?: string[];
     current_node?: string;
     expected_progress_hours?: number;

package/dist/customer/reminder-system.js

@@ -145,6 +145,26 @@ const REMINDER_RULES = [
         applies: (ctx) => ctx.has_messenger === false,
         dedup_key: "no_messenger",
     },
+    {
+        id: "preorder_customer_required_no_contact",
+        stage: "preorder",
+        priority: "required",
+        message: (ctx) => `🔴 This Service requires private information (${(ctx.customer_required ?? []).join(", ")}), ` +
+            `but it has NO Contact/Messenger channel configured. Your private information cannot be delivered securely ` +
+            `— do NOT order until the merchant binds a Contact (um) so the info can be sent end-to-end encrypted.`,
+        applies: (ctx) => (ctx.customer_required?.length ?? 0) > 0 && ctx.has_messenger === false,
+        dedup_key: "customer_required_no_contact",
+    },
+    {
+        id: "preorder_customer_required_send_info",
+        stage: "preorder",
+        priority: "recommended",
+        message: (ctx) => `🔐 After ordering you MUST send your private information (${(ctx.customer_required ?? []).join(", ")}) ` +
+            `to the merchant's Contact via end-to-end encrypted Messenger, and obtain a confirmation reply. ` +
+            `Your private information is encrypted end-to-end and never stored in plaintext by the service.`,
+        applies: (ctx) => (ctx.customer_required?.length ?? 0) > 0 && ctx.has_messenger === true,
+        dedup_key: "customer_required_send_info",
+    },
     {
         id: "in_progress_progress_stalled",
         stage: "in_progress",

package/dist/customer/types.d.ts

@@ -11,6 +11,7 @@ export interface ServiceBasics {
     machine_id?: string;
     buy_guard_id?: string;
     customer_required_count: number;
+    customer_required: string[];
     arbitrations_count: number;
     compensation_fund_balance: bigint;
     compensation_lock_duration: number;

package/dist/examples/{insurance-machine-create-publish.json → insurance-machine-create.json}

@@ -1,10 +1,10 @@
 {
-  "title": "Create and Publish Insurance Claim Machine (Start -> Complete)",
-  "description": "Create a two-node insurance claim workflow Machine and publish it in a single transaction: entry forward 'start_claim' into Start (permissionIndex 1000), and 'complete_claim' from Start into Complete (permissionIndex 1001) gated by the time-lock Guard insurance_complete_guard_v1.",
-  "tags": ["machine", "insurance", "claim", "workflow", "publish"],
+  "title": "Create Insurance Claim Machine DRAFT (Start -> Complete)",
+  "description": "Step 4 of the 12-step deploy plan: create the two-node insurance claim workflow Machine in DRAFT (unpublished): entry forward 'start_claim' into Start (permissionIndex 1000), and 'complete_claim' from Start into Complete (permissionIndex 1001) gated by the time-lock Guard insurance_complete_guard_v1. Publish is a separate later step (machine-publish.json).",
+  "tags": ["machine", "insurance", "claim", "workflow", "draft", "12-step"],
   "industry": "insurance",
   "operation_type": "machine",
-  "source": "docs/examples/Insurance — schema-validated, not chain-verified",
+  "source": "docs/examples/Insurance — adapted to the 12-step plan (DRAFT only, schema-validated)",
   "verified": false,
   "network": "testnet",
   "call": {
@@ -56,8 +56,7 @@
             ]
           }
         ]
-      },
-      "publish": true
+      }
     },
     "env": {
       "account": "insurance_provider_v1",
@@ -65,10 +64,11 @@
     }
   },
   "notes": [
-    "Insurance-claim Machine pattern: a minimal two-node Start -> Complete workflow where the completion forward is gated by a time-lock Guard. Demonstrates create-with-nodes + publish in ONE transaction (nodes become immutable after publish).",
-    "Schema check (call/machine.ts CallMachine_DataSchema): 'object' uses the OBJECT form of WithPermissionObjectSchema (NamedObjectWithPermissionSchema — name, permission, replaceExistName); node uses NodeSchema op='add' with nodes array; publish=true on NEW machine creation triggers the FIX-02 entry-forward refine — satisfied because the Start pair has prev_node='' with at least one forward (FIX-002 also requires the initial pair to have a non-empty forwards list).",
+    "12-STEP PLAN alignment: this is ONE step (Step 4 Machine DRAFT). Do NOT bundle publish:true here — publish is Step 6 (see machine-publish.json). The 12-step order is Service DRAFT → Machine (nodes/forwards) → Guard → bind Guards → Machine publish.",
+    "Insurance-claim Machine pattern: a minimal two-node Start -> Complete workflow where the completion forward is gated by a time-lock Guard. This creates the Machine in DRAFT (nodes remain editable until publish).",
+    "Schema check (call/machine.ts CallMachine_DataSchema): 'object' uses the OBJECT form of WithPermissionObjectSchema (NamedObjectWithPermissionSchema — name, permission, replaceExistName); node uses NodeSchema op='add' with nodes array; publish omitted → DRAFT. The FIX-02 entry-forward refine (applied at publish time) is satisfied because the Start pair has prev_node='' with at least one forward (FIX-002 also requires the initial pair to have a non-empty forwards list).",
     "Forward check (query/index.ts MachineForwardSchema): every forward provides permissionIndex (1000/1001) satisfying the one-of namedOperator/permissionIndex rule; the Complete forward uses the OBJECT guard form {guard: 'insurance_complete_guard_v1'} (MachineForwardGuardSchema; a plain string shorthand is also accepted via preprocess).",
-    "The referenced Guard (insurance_complete_guard_v1) and Permission (insurance_permission_v1, with indexes 1000/1001 granted to the operator) must exist before this call — see the sibling insurance-guard-claim-timelock example and the Insurance doc Steps 1/3.",
+    "The referenced Guard (insurance_complete_guard_v1) and Permission (insurance_permission_v1, with indexes 1000/1001 granted to the operator) must exist before publish — see the sibling insurance-guard-claim-timelock example and the Insurance doc Steps 1/3.",
     "PREREQUISITE for advancing claims: the Permission must grant index 1000 (start_claim) and 1001 (complete_claim) to the operating account, otherwise progress advancement aborts with MoveAbort code 7.",
     "Desensitization: doc payload already uses generic local-mark names only (insurance_provider_v1, insurance_machine_v1, insurance_permission_v1); no real personal data present, nothing replaced."
   ]

package/dist/examples/insurance-service-allocators.json

@@ -0,0 +1,55 @@
+{
+  "title": "Configure Order Allocators (Insurance, Entity-Sharing)",
+  "description": "Pre-publish Service configuration step (12-step plan: order_allocators). Update the unpublished insurance Service with two alternative order_allocators (Treasury collection and personal collection, first-match-wins) whose sharing recipients are FIXED Entity addresses — the fund-theft-safe pattern. Publish is a SEPARATE later step (Step 12) and is intentionally NOT bundled here.",
+  "tags": ["service", "insurance", "order_allocators", "entity-sharing", "12-step"],
+  "industry": "insurance",
+  "operation_type": "service",
+  "source": "docs/examples/Insurance — adapted to the 12-step plan (allocators only, schema-validated)",
+  "verified": false,
+  "network": "testnet",
+  "call": {
+    "tool": "onchain_operations",
+    "operation_type": "service",
+    "data": {
+      "object": "insurance_service_v1",
+      "order_allocators": {
+        "description": "Insurance order revenue allocation — 2 alternative merchant collection approaches (first-match-wins means only the first passing allocator executes)",
+        "threshold": 0,
+        "allocators": [
+          {
+            "guard": "insurance_withdraw_guard_treasury_v1",
+            "sharing": [
+              {
+                "who": { "Entity": { "name_or_address": "insurance_treasury_v1" } },
+                "sharing": 10000,
+                "mode": "Rate"
+              }
+            ]
+          },
+          {
+            "guard": "insurance_withdraw_guard_personal_v1",
+            "sharing": [
+              {
+                "who": { "Entity": { "name_or_address": "insurance_provider_v1" } },
+                "sharing": 10000,
+                "mode": "Rate"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    "env": {
+      "account": "insurance_provider_v1",
+      "network": "testnet"
+    }
+  },
+  "notes": [
+    "12-STEP PLAN alignment: this file is ONE step (Step 9 order_allocators). Do NOT bundle publish:true here — publish is Step 12. order_allocators is PERMANENTLY IMMUTABLE after publish (service.move E_ALREADY_PUBLISHED), so it MUST be set in this pre-publish step.",
+    "Fund-safety pattern: who = {Entity: {name_or_address: ...}} pins the recipient to a FIXED address (Treasury object or provider account) resolved via LocalMark at build time. Even if the withdraw Guard were bypassed, funds still flow to the fixed Entity — the caller cannot redirect them. NEVER use {Signer: 'signer'} for merchant collection.",
+    "first-match-wins: the TWO allocators illustrate 2 alternative collection designs (Treasury vs personal); only the FIRST allocator whose Guard passes executes. In production pick ONE and delete the other. Each allocator's Guard must be a UNIQUE Guard object.",
+    "Schema check (call/service.ts CallService_DataSchema + query/index.ts AllocatorsSchema/AllocatorSchema/AllocationSharingSchema/RecipientSchema): object is the STRING form (existing service); order_allocators = {description, threshold, allocators[]} with per-allocator {guard: NameOrAddress, sharing: [{who: {Entity: {name_or_address}}, sharing, mode}]}; mode 'Rate' with a single sharing of 10000 satisfies the Rate-sum == 10000 (basis points, 100%) rule with no Surplus item; threshold 0 allows any balance.",
+    "PREREQUISITES (created by separate calls, not shown): insurance_service_v1 (unpublished, with machine + sales), both withdraw Guards, and insurance_treasury_v1; Machine published. If this Service declares customer_required, it must also bind a Contact via um (hard linkage) — see the Contact step.",
+    "Desensitization: generic local-mark names only (insurance_service_v1, insurance_treasury_v1, insurance_provider_v1, insurance_withdraw_guard_*_v1); no real personal data present."
+  ]
+}

package/dist/examples/machine-publish.json

@@ -0,0 +1,30 @@
+{
+  "title": "Publish a Machine (Freeze Workflow)",
+  "description": "Step 6 of the 12-step deploy plan: publish an existing DRAFT Machine to make its nodes/forwards immutable. This is a single-concept operation — create the Machine in DRAFT first (see *-machine-create.json), then bind Guards to forwards, then publish. Replace 'my_machine' with your Machine's name.",
+  "tags": ["machine", "publish", "freeze", "immutable", "12-step"],
+  "industry": "general",
+  "operation_type": "machine",
+  "source": "12-step deploy plan (Step 6 Machine publish) — schema-validated",
+  "verified": false,
+  "network": "testnet",
+  "call": {
+    "tool": "onchain_operations",
+    "operation_type": "machine",
+    "data": {
+      "object": "my_machine",
+      "publish": true
+    },
+    "env": {
+      "account": "service_provider",
+      "network": "testnet",
+      "confirmed": true
+    }
+  },
+  "notes": [
+    "12-STEP PLAN alignment: this is ONE step (Step 6 Machine publish). Create the Machine in DRAFT first (Step 4), then create/bind Guards to forwards (Step 5), THEN publish here. Publishing is IRREVERSIBLE — nodes/pairs/forwards become permanently frozen.",
+    "object is the STRING form (existing DRAFT Machine name/ID). publish:true is the only data field needed — node/progress_new/description are NOT re-specified.",
+    "env.confirmed:true is REQUIRED (ConfirmGate) because publish is irreversible.",
+    "FIX-02: publish:true validates that the on-chain nodes contain at least one entry forward (prev_node=''), else the Machine would be stuck at Progress current=''.",
+    "Only a PUBLISHED Machine can be bound to a Service (service.machine asserts bPublished). Publish the Machine BEFORE the Service's machine-binding step."
+  ]
+}

package/dist/examples/rental-ziroom-service-create.json

@@ -1,11 +1,11 @@
 {
-  "title": "Create Service with 3-path Allocation (Ziroom Rental)",
-  "description": "Create a Service with machine, buy_guard, contact, and 3-path order_allocators (rent to operator / refund to customer signer / damage deduction to operator)",
-  "tags": ["service", "allocation", "rental", "order_allocators", "guard"],
+  "title": "Create Rental Service DRAFT (Ziroom)",
+  "description": "Step 3 of the 12-step deploy plan: create the Ziroom rental Service object in DRAFT (unpublished) with only its identity — name, permission, payment token type, description, and location. Machine binding, buy_guard, sales (WIP), order_allocators, Contact (um), and publish are each separate later steps and are intentionally NOT bundled here.",
+  "tags": ["service", "rental", "draft", "create", "12-step"],
   "industry": "rental",
   "operation_type": "service",
-  "source": "ziroom testnet deployment 2026-07-29 (repaired to current schema)",
-  "verified": true,
+  "source": "ziroom testnet deployment 2026-07-29 — adapted to the 12-step plan (DRAFT only, schema-validated)",
+  "verified": false,
   "network": "testnet",
   "call": {
     "tool": "onchain_operations",
@@ -18,58 +18,8 @@
         "permission": "ziroom_permission_v1",
         "type_parameter": "0x2::wow::WOW"
       },
-      "machine": "ziroom_machine_v1",
-      "buy_guard": "ziroom_buy_guard_v1",
-      "um": "ziroom_contact_v1",
-      "sales": {
-        "op": "add",
-        "sales": [
-          {
-            "name": "ziroom_apartment_v1",
-            "price": 2000000000,
-            "stock": 1,
-            "suspension": false,
-            "wip": "",
-            "wip_hash": ""
-          }
-        ]
-      },
-      "order_allocators": {
-        "description": "3-path allocation: rent to operator, refund to customer, damage deductions",
-        "threshold": 1000000000,
-        "allocators": [
-          {
-            "guard": "ziroom_buy_guard_v1",
-            "sharing": [
-              {
-                "who": { "Entity": { "name_or_address": "ziroom_operator" } },
-                "sharing": 1000000000,
-                "mode": "Amount"
-              }
-            ]
-          },
-          {
-            "guard": "ziroom_refund_guard_v1",
-            "sharing": [
-              {
-                "who": { "Signer": "signer" },
-                "sharing": 1000000000,
-                "mode": "Amount"
-              }
-            ]
-          },
-          {
-            "guard": "ziroom_damage_guard_v1",
-            "sharing": [
-              {
-                "who": { "Entity": { "name_or_address": "ziroom_operator" } },
-                "sharing": 1000000000,
-                "mode": "Amount"
-              }
-            ]
-          }
-        ]
-      }
+      "description": "Ziroom apartment rental service",
+      "location": "Beijing"
     },
     "env": {
       "network": "testnet",
@@ -78,12 +28,10 @@
     }
   },
   "notes": [
-    "order_allocators is PERMANENTLY IMMUTABLE after publish (service.move:503) — set it BEFORE publish=true.",
-    "Signer recipient means the tx sender at alloc() time — the customer must call alloc_by_guard THEMSELVES for refunds (if the operator calls it, the operator receives the funds).",
-    "Amount mode: fixed amount in smallest unit, not percentage. Use Rate mode (10000=100%) for proportional splits; Rate items must sum to exactly 10000 when no Surplus item exists.",
-    "sales is an op discriminated union: {op:'add'|'set', sales:[...]} or {op:'remove', sales_name:[...]} or {op:'clear'} — never a bare array.",
-    "permission and type_parameter live INSIDE 'object' (TypeNamedObjectWithPermissionSchema). wip/wip_hash empty strings skip verification (TESTING ONLY — production must use real WIP URLs).",
-    "machine must be PUBLISHED before binding here; buy_guard may use a LocalMark NAME to break the Guard↔Service circular dependency (Phase-1 create without publish, then publish in Phase 2).",
-    "Entity recipient shown as local mark name 'ziroom_operator' (desensitization repair 2026-07-30): the original deployment used the operator's raw 0x address; Entity resolves names via LocalMark to a FIXED static address, so the name form is equivalent and recommended."
+    "12-STEP PLAN alignment: this file is ONE step (Step 3 Service DRAFT). The full order is Account → Permission → Service DRAFT → Machine → Guard → Machine publish → Sales(WIP) → Treasury(optional) → order_allocators → Contact(um) → Arbitration → Service publish. Do NOT bundle machine/buy_guard/um/sales/order_allocators into the create call.",
+    "object uses the OBJECT form of TypeNamedObjectWithPermissionSchema: name/permission/type_parameter go INSIDE object; description and location are top-level Service fields. No publish:true here — the Service stays unpublished until Step 12.",
+    "Rental is a PHYSICAL-goods scenario and SHOULD declare customer_required (name/phone/shipping_address/id_number for deposit-backed rental). Per the SDK-enforced HARD LINKAGE, customer_required must be set TOGETHER with a Contact bound as um — the buyer's private info is delivered only through the Contact's end-to-end encrypted Messenger. Therefore customer_required is NOT set in this DRAFT; it is set together with um in the Contact step (create the Contact, then bind um + customer_required in one update).",
+    "permission references the pre-created ziroom_permission_v1 (Step 2); type_parameter '0x2::wow::WOW' sets the payment token (WOW, 9 decimals).",
+    "machine, order_allocators, and arbitrations become immutable after publish — set them in their own pre-publish steps, not here."
   ]
 }

package/dist/examples/retail-myshop-service-create.json

@@ -1,12 +1,12 @@
 {
-  "title": "Create Retail Service with 2-path Allocation (MyShop E-Commerce)",
-  "description": "Simple e-commerce Service with machine, withdraw/refund guards, contact, and toy products. 2-path order_allocators: merchant withdraw after completion, customer refund after cancellation.",
-  "tags": ["service", "allocation", "retail", "ecommerce", "guard", "order_allocators"],
+  "title": "Create Retail Service DRAFT (MyShop E-Commerce)",
+  "description": "Step 3 of the 12-step deploy plan: create the MyShop retail Service object in DRAFT (unpublished) with only its identity — name, permission, payment token type, description, and location. Machine binding, sales (WIP), order_allocators, Contact (um), and publish are each separate later steps and are intentionally NOT bundled here.",
+  "tags": ["service", "retail", "ecommerce", "draft", "create", "12-step"],
   "industry": "retail",
   "operation_type": "service",
-  "source": "myshop mainnet deployment 2026-07-29",
-  "verified": true,
-  "network": "mainnet",
+  "source": "myshop deployment walkthrough (docs/examples/MyShop) — adapted to the 12-step plan + testnet (DRAFT only, schema-validated)",
+  "verified": false,
+  "network": "testnet",
   "call": {
     "tool": "onchain_operations",
     "operation_type": "service",
@@ -20,69 +20,19 @@
         "replaceExistName": true
       },
       "description": "MyShop - Top quality toys for children",
-      "location": "Online Store",
-      "machine": "myshop_machine_v2",
-      "order_allocators": {
-        "description": "Order revenue allocation - merchant withdraw after completion",
-        "threshold": 0,
-        "allocators": [
-          {
-            "guard": "myshop_withdraw_guard_v2",
-            "sharing": [
-              {
-                "who": { "Signer": "signer" },
-                "sharing": 10000,
-                "mode": "Rate"
-              }
-            ]
-          },
-          {
-            "guard": "myshop_refund_guard_v2",
-            "sharing": [
-              {
-                "who": { "GuardIdentifier": 0 },
-                "sharing": 10000,
-                "mode": "Rate"
-              }
-            ]
-          }
-        ]
-      },
-      "sales": {
-        "op": "add",
-        "sales": [
-          {
-            "name": "Play Purse Set 35PCS",
-            "price": 50000000,
-            "stock": 100,
-            "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
-            "wip_hash": ""
-          },
-          {
-            "name": "Tree House Building Set",
-            "price": 30000000,
-            "stock": 75,
-            "suspension": false,
-            "wip": "https://wowok.net/test/three_body.wip",
-            "wip_hash": ""
-          }
-        ]
-      },
-      "um": "myshop_aftersales_contact_v2",
-      "publish": true
+      "location": "Online Store"
     },
     "env": {
       "account": "myshop_merchant",
-      "network": "mainnet",
-      "confirmed": true
+      "network": "testnet",
+      "no_cache": true
     }
   },
   "notes": [
-    "order_allocators is PERMANENTLY IMMUTABLE after publish (service.move:503)",
-    "Withdraw allocator uses Signer recipient — safe ONLY because withdraw_guard binds Signer to myshop_merchant",
-    "Refund allocator uses GuardIdentifier 0 (Order object address) as escrow — customer claims separately",
-    "Rate mode uses 0-10000 scale (10000 = 100%)",
-    "Machine, order_allocators, and arbitrations become immutable after publish"
+    "12-STEP PLAN alignment: this file is ONE step (Step 3 Service DRAFT). The full order is Account → Permission → Service DRAFT → Machine → Guard → Machine publish → Sales(WIP) → Treasury(optional) → order_allocators → Contact(um) → Arbitration → Service publish. Do NOT bundle machine/sales/order_allocators/um/publish into the create call.",
+    "object uses the OBJECT form of TypeNamedObjectWithPermissionSchema: name/permission/type_parameter go INSIDE object; description and location are top-level Service fields. No publish:true here — the Service stays unpublished until Step 12.",
+    "Physical-goods services SHOULD declare customer_required (e.g. name/phone/shipping_address) so the buyer's delivery info is captured. Per the SDK-enforced HARD LINKAGE, customer_required must be set TOGETHER with a Contact bound as um (the private info is delivered only through the Contact's end-to-end encrypted Messenger). Therefore customer_required is NOT set in this DRAFT — it is set together with um in the Contact step (see retail-myshop-contact-create.json, then bind um + customer_required in one update).",
+    "permission references the pre-created myshop_permission_v2 (Step 2); type_parameter '0x2::wow::WOW' sets the payment token (WOW, 9 decimals). onChain:false keeps the local name private (not published on-chain).",
+    "machine, order_allocators, and arbitrations become immutable after publish — set them in their own pre-publish steps, not here."
   ]
 }

package/dist/examples/retail-myshop-service-customer-required.json

@@ -0,0 +1,31 @@
+{
+  "title": "Bind Contact (um) + customer_required Together (MyShop Retail)",
+  "description": "Contact step (12-step plan): set the Service's customer_required labels and bind its Contact (um) in ONE operation. The SDK enforces the HARD LINKAGE — customer_required without um is rejected, because the buyer's private information (name/phone/shipping_address) is delivered only through the Contact's end-to-end encrypted Messenger.",
+  "tags": ["service", "customer_required", "um", "contact", "messenger", "retail", "hard-linkage", "12-step"],
+  "industry": "retail",
+  "operation_type": "service",
+  "source": "adapted to the 12-step plan + SDK customer_required⟶um hard linkage (schema-validated)",
+  "verified": false,
+  "network": "testnet",
+  "call": {
+    "tool": "onchain_operations",
+    "operation_type": "service",
+    "data": {
+      "object": "myshop_service_v2",
+      "customer_required": ["name", "phone", "shipping_address"],
+      "um": "myshop_aftersales_contact_v2"
+    },
+    "env": {
+      "account": "myshop_merchant",
+      "network": "testnet",
+      "no_cache": true
+    }
+  },
+  "notes": [
+    "HARD LINKAGE (SDK-enforced, service.ts checkCustomerRequiredNeedsUm): customer_required and um MUST be set together. The buyer's private info is delivered via end-to-end encrypted Messenger, which routes to the Contact bound as um — without um there is no channel and the SDK rejects the call with InvalidParam.",
+    "object is the STRING form (existing unpublished service); customer_required is an array of info labels (NotEmptyNameSchema); um is the Contact name/ID created in the Contact step (see retail-myshop-contact-create.json).",
+    "ORDER FLOW: after a customer places an order on this Service, they MUST send each customer_required field to this Contact's Messenger (messenger_operation → send_message) and obtain an explicit confirmation reply; the resulting Contact ID or WTS Proof can be recorded on the Order via OrderNewSchema.order_required_info.",
+    "customer_required and um remain MUTABLE after publish (L3 in the immutability matrix), but for physical goods set them BEFORE publish so customers get the right flow from day one.",
+    "The referenced Contact (myshop_aftersales_contact_v2) must exist and have an ims[] entry pointing at the merchant's Messenger account (account name, not messenger name)."
+  ]
+}

package/dist/examples/threebody-machine-create.json

@@ -1,10 +1,10 @@
 {
-  "title": "Create Signature-Approval Machine with Permission-Gated Forwards (ThreeBody Signature)",
-  "description": "Two-node signing workflow 'Book Delivered -> Signature Completed'. Each forward is gated by its own permissionIndex (1000/1001), so only accounts granted that index in the Permission object can advance that stage. Extendable to M-of-N multi-signature gates by adding weighted forwards and raising pair threshold.",
-  "tags": ["machine", "multisig", "signature", "approval-gate", "permissionIndex", "publish"],
+  "title": "Create Signature-Approval Machine DRAFT (ThreeBody Signature)",
+  "description": "Step 4 of the 12-step deploy plan: create the two-node signing workflow 'Book Delivered -> Signature Completed' in DRAFT (unpublished). Each forward is gated by its own permissionIndex (1000/1001), so only accounts granted that index in the Permission object can advance that stage. Publish is a separate later step (machine-publish.json) — do NOT bundle publish here.",
+  "tags": ["machine", "multisig", "signature", "approval-gate", "permissionIndex", "draft", "12-step"],
   "industry": "general",
   "operation_type": "machine",
-  "source": "docs/examples/ThreeBody_Signature — schema-validated, not chain-verified",
+  "source": "docs/examples/ThreeBody_Signature — adapted to the 12-step plan (DRAFT only, schema-validated)",
   "verified": false,
   "network": "testnet",
   "call": {
@@ -53,20 +53,19 @@
             ]
           }
         ]
-      },
-      "publish": true
+      }
     },
     "env": {
       "account": "signer_author",
-      "network": "testnet",
-      "confirmed": true
+      "network": "testnet"
     }
   },
   "notes": [
+    "12-STEP PLAN alignment: this is ONE step (Step 4 Machine DRAFT). Do NOT bundle publish:true here — publish is Step 6 (see machine-publish.json). The 12-step order is Service DRAFT → Machine (nodes/forwards) → Guard → bind Guards → Machine publish.",
     "Shapes verified against MachineNodeSchema / MachineNodePairSchema / MachineForwardSchema (schema/query/index.ts) + CallMachine_DataSchema (schema/call/machine.ts). Forwards use camelCase permissionIndex (namedOperator is the alternative); the schema-level one-of refine requires namedOperator OR permissionIndex on every forward.",
-    "Entry-forward invariants satisfied: pair with prev_node='' has >=1 forward (FIX-002), and publish:true on a NEW machine requires an entry forward (FIX-02 refine) — 'Confirm Delivery' covers both.",
+    "Entry-forward invariant satisfied: pair with prev_node='' has >=1 forward (FIX-002). The FIX-02 publish-time entry-forward refine will also pass when this DRAFT is later published — 'Confirm Delivery' covers both.",
     "Threshold semantics: pair 1 threshold 0 is exempt (single-forward pair — one signature advances). Pair 2 threshold 1 equals the summed weight of its single forward. MULTI-SIG EXTENSION: add more forwards {permissionIndex or namedOperator, weight} to the pair and set threshold > 1 — the node only advances once accumulated signature weight >= threshold (e.g. 2-of-3 approvers).",
-    "publish: true IRREVERSIBLY locks nodes/pairs/forwards — env.confirmed: true required (ConfirmGate).",
+    "This is a DRAFT (no publish:true). Once published, nodes/pairs/forwards become irreversibly locked and env.confirmed:true is required at publish time.",
     "DESENSITIZED: doc account 'three_body_author' -> 'signer_author'; objects renamed to local marks 'threebody_machine' / 'threebody_permission'."
   ]
 }

package/dist/examples/threebody-service-allocators.json

@@ -1,6 +1,6 @@
 {
   "title": "Configure Order Allocators with Entity-Treasury Recipient (ThreeBody Signature)",
-  "description": "Pre-publish Service configuration: 100% of completed-order funds route to the fixed Treasury object via an allocator Guard that verifies order.service == this service. Entity(treasury) recipient makes the fund flow caller-independent (no Signer binding needed). Also sets customer_required contact fields.",
+  "description": "Pre-publish Service configuration step (12-step plan: order_allocators): 100% of completed-order funds route to the fixed Treasury object via an allocator Guard that verifies order.service == this service. Entity(treasury) recipient makes the fund flow caller-independent (no Signer binding needed).",
   "tags": ["service", "order_allocators", "treasury-first", "allocation", "guard", "signature"],
   "industry": "general",
   "operation_type": "service",
@@ -29,8 +29,7 @@
             ]
           }
         ]
-      },
-      "customer_required": ["phone", "email", "shipping_address"]
+      }
     },
     "env": {
       "account": "signer_author",
@@ -43,7 +42,7 @@
     "Rate mode: sharing 10000 = 100% (basis points); Rate items in one allocator must sum to 10000 when no Surplus item exists. threshold 0 allows allocation of any balance.",
     "ORDER_ALLOCATORS IS PERMANENTLY IMMUTABLE AFTER PUBLISH (service.move:503) — this call must run BEFORE publish:true; the Service must also be unpublished when the machine field was bound earlier.",
     "Prerequisite objects (created by separate calls, not shown): 'threebody_signature_service' (service, unpublished), 'threebody_allocator_guard' (guard: logic_equal[query order.service, identifier(service)]), 'threebody_treasury' (treasury sharing this service's permission).",
-    "customer_required entries validated against NotEmptyNameSchema (non-empty, <=64 bcs chars).",
+    "HARD LINKAGE: if this Service also declares customer_required (private info the buyer must send), it MUST set customer_required TOGETHER with a Contact bound via `um` (same operation, in a pre-publish step) — the SDK rejects customer_required without um because the buyer's private info is delivered only through the Contact's end-to-end encrypted Messenger.",
     "DESENSITIZED: doc account 'three_body_author' -> 'signer_author'; objects renamed to local marks ('threebody_signature_service', 'threebody_treasury', 'threebody_allocator_guard')."
   ]
 }

package/dist/examples/travel-machine-create.json

@@ -1,10 +1,10 @@
 {
-  "title": "Create and Publish Multi-Segment Travel Machine with Forward Guards",
-  "description": "Create a 5-node Iceland travel workflow Machine (entry -> Buy Insurance -> SPA -> Ice Scooting -> Complete/Cancel) and publish it in one transaction. Three forwards are gated by Guards: weather oracle check (go_ice_scooting), time-lock (complete_trip), and always-pass cancel (cancel_trip). Each forward uses a distinct permissionIndex.",
-  "tags": ["machine", "travel", "workflow", "forward-guard", "publish", "multi-node"],
+  "title": "Create Multi-Segment Travel Machine DRAFT with Forward Guards",
+  "description": "Step 4 of the 12-step deploy plan: create a 5-node Iceland travel workflow Machine in DRAFT (unpublished): (init) -> Buy Insurance -> SPA -> Ice Scooting -> Complete/Cancel. Three forwards are gated by Guards: weather oracle check (go_ice_scooting), time-lock (complete_trip), and always-pass cancel (cancel_trip). Publish is a separate later step (machine-publish.json).",
+  "tags": ["machine", "travel", "workflow", "forward-guard", "multi-node", "draft", "12-step"],
   "industry": "travel",
   "operation_type": "machine",
-  "source": "docs/examples/Travel — schema-validated, not chain-verified",
+  "source": "docs/examples/Travel — adapted to the 12-step plan (DRAFT only, schema-validated)",
   "verified": false,
   "network": "testnet",
   "call": {
@@ -114,23 +114,22 @@
             ]
           }
         ]
-      },
-      "publish": true
+      }
     },
     "env": {
       "account": "travel_provider",
       "network": "testnet",
-      "no_cache": true,
-      "confirmed": true
+      "no_cache": true
     }
   },
   "notes": [
+    "12-STEP PLAN alignment: this is ONE step (Step 4 Machine DRAFT). Do NOT bundle publish:true here — publish is Step 6 (see machine-publish.json). The 12-step order is Service DRAFT → Machine (nodes/forwards) → Guard → bind Guards → Machine publish.",
     "Multi-segment workflow pattern: 5 nodes form a linear chain with a terminal fork — Ice Scooting has TWO outgoing paths (complete_trip -> Complete, cancel_trip -> Cancel), each guarded differently. Demonstrates per-forward Guard binding (Forward.guard) combined with per-forward permissionIndex, the canonical way to put conditional gates on workflow transitions.",
-    "Schema check (call/machine.ts CallMachine_DataSchema, strict): 'object' uses the OBJECT form of WithPermissionObjectSchema (NamedObjectWithPermissionSchema — name, permission, replaceExistName); node uses NodeSchema op='add' with bReplace:true + nodes array; publish=true on NEW machine creation triggers the FIX-02 entry-forward refine — satisfied because the 'Buy Insurance' pair has prev_node='' with a non-empty forwards list (FIX-002).",
+    "Schema check (call/machine.ts CallMachine_DataSchema, strict): 'object' uses the OBJECT form of WithPermissionObjectSchema (NamedObjectWithPermissionSchema — name, permission, replaceExistName); node uses NodeSchema op='add' with bReplace:true + nodes array; publish omitted → DRAFT. The FIX-02 entry-forward refine (applied at publish time) is satisfied because the 'Buy Insurance' pair has prev_node='' with a non-empty forwards list (FIX-002).",
     "Pair/forward semantics (query/index.ts MachineNodePairSchema): forwards describe INCOMING transitions — the forward in a node's pair (prev_node='X') is the action that advances Progress FROM X INTO this node. Field is 'prev_node' (NOT 'prior_node' — that name only appears in the separate 'add forward'/'remove forward' ops). threshold is per-pair; weight sums across the pair's forwards must reach threshold to advance.",
     "Forward check (query/index.ts MachineForwardSchema, strict — only name/namedOperator/permissionIndex/weight/guard allowed): every forward provides permissionIndex (1000-1004), satisfying the one-of namedOperator/permissionIndex refine (namedOperator:'' is the order-owner wildcard alternative). Guarded forwards use the OBJECT guard form {guard: '<name>', retained_submission: []} (MachineForwardGuardSchema); a plain string shorthand 'guard': '<name>' is also accepted via preprocess when no retained_submission is needed.",
     "Guard evaluation order: Forward.guard verifies BEFORE the transition executes, so a forward Guard querying THIS progress's progress.current sees the SOURCE node, not the target. Here weather_check_guard queries an external Repository (safe) and travel_complete_guard queries time-lock data (safe); neither checks progress.current == target, which would always fail.",
-    "publish:true is IRREVERSIBLE and freezes the node set — nodes cannot be changed after publish, and only published Machines can bind to a Service (service.machine). Guards referenced by name (weather_check_guard, travel_complete_guard, travel_cancel_guard) and the Permission (travel_permission, with indexes 1000-1004 granted to the operator) must exist BEFORE this call — see the sibling travel-guard-weather-oracle / travel-guard-time-lock examples and Travel doc Steps 1/3.",
+    "This is a DRAFT (no publish:true). Once published, nodes are irreversibly frozen and env.confirmed:true is required at publish time. Only published Machines can bind to a Service (service.machine). Guards referenced by name (weather_check_guard, travel_complete_guard, travel_cancel_guard) and the Permission (travel_permission, with indexes 1000-1004 granted to the operator) must exist BEFORE publish — see the sibling travel-guard-weather-oracle / travel-guard-time-lock examples and Travel doc Steps 1/3.",
     "Desensitization: doc payload already uses generic local-mark names only (travel_provider, travel_machine, travel_permission, guard names); no real personal data, phone numbers, or raw 0x object addresses present — nothing replaced."
   ]
 }