@wowok/agent-mcp 3.1.7 → 3.2.0

package/dist/schemas/onchain_operations_allocation.schema.json

@@ -150,7 +150,7 @@
                                   "type": "string"
                                 }
                               ],
-                              "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate': basis-points rate, 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
+                              "description": "Allocation value. SEMANTICS DEPEND ON `mode`:\n• mode='Amount': absolute amount in smallest unit (e.g., '750000000' for 0.75 WOW, '250000000' for 0.25 WOW). Allocated first; sum of Amount items cached as `fix`.\n• mode='Rate' (NET): basis-points rate off the post-fix base (balance - fix, or max - fix), 10000 = 100% (e.g., '7500' for 75%, '2500' for 25%). When no Surplus in same Allocator, sum MUST == 10000; when Surplus present, sum MUST <= 10000.\n• mode='RateGross': basis-points rate off the FULL pool (balance) or the `max` cap — the fixed Amount total is NOT subtracted, 10000 = 100%. sum MUST <= 10000 (and, with `max` set, fix×10000 + sum×max <= max×10000). Cannot be mixed with mode='Rate' in the same Allocator while a fixed Amount total is present.\n• mode='Surplus': IGNORED (contract forces to 0). Set to '0' for clarity. Receives remaining balance after Amount + Rate/RateGross allocations.\n⚠️ T1 LOSSY POINT (B-2): the value is PRE-CONFIGURED and STATIC. A continuous/conditional amount (e.g. 'pay exactly the assessed loss amount') CANNOT be expressed — there is no runtime formula field. Model variable payouts as (a) a fixed-tier Allocator list guarded by distinct Guards, or (b) an Amount with a `max` cap — both are finite configurations, not free-form formulas."
                             },
                             "mode": {
                               "anyOf": [
@@ -159,12 +159,13 @@
                                   "enum": [
                                     "Amount",
                                     "Rate",
-                                    "Surplus"
+                                    "Surplus",
+                                    "RateGross"
                                   ]
                                 },
                                 {}
                               ],
-                              "description": "Allocation mode — determines how the `sharing` field is interpreted. Three modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set). Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate items (proportional to balance-fix) → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits (requires sum == 10000 unless Surplus present). Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus', recommended) or number (0/1/2)."
+                              "description": "Allocation mode — determines how the `sharing` field is interpreted. Four modes can be used individually OR combined within a single Allocator; when combined, allocation order is strictly: Amount first, then Rate/RateGross, then Surplus. Understanding these modes allows modeling almost any fund distribution pattern.\n• Amount (0): `sharing` is a FIXED amount in smallest unit (e.g., '750000000' = 0.75 WOW). Allocated FIRST; sum of all Amount items is cached as `fix` by the contract. Validation: when no Rate and no Surplus items exist, sum of Amount items must be >= allocators.threshold (EAMOUNT_BELOW_THRESHOLD=12); when `max` is set, sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13).\n• Rate (1): `sharing` is a NET basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance - fix (or max - fix if `max` is set) — the cached fixed Amount total IS subtracted. Validation: when no Surplus items exist, sum of all Rate items must be EXACTLY 10000 (ERATE_NOT_10000=4); when Surplus items exist, sum of all Rate items must be <= 10000 (ERATE_EXCEEDS_10000=6).\n• RateGross (3): `sharing` is a GROSS basis-points rate (10000 = 100%). Allocated AFTER Amount; formula: allocated = (sharing × total_rates) / 10000, where total_rates = balance (the full pool) or the `max` cap when set — the fixed Amount total is NOT subtracted, so fixed Amount entries and percentage-of-total rates coexist exactly. Validation: sum of all RateGross items must be <= 10000 (ERATE_EXCEEDS_10000=6); when `max` is set, fix×10000 + sum(rate)×max <= max×10000 must hold (6); with no `max` and a fixed total > 0, sum of RateGross items must be < 10000 (6). RateGross cannot be mixed with NET Rate entries in the same Allocator while a fixed Amount total is present (EMIXED_RATE_BASES=17).\n• Surplus (2): `sharing` is IGNORED (contract forces it to 0). Allocated LAST; receives the remaining balance after Amount + Rate allocations. Validation: MAX ONE Surplus item per Allocator (EMULTIPLE_SURPLUS=5). When Surplus exists, Rate sum constraint relaxes from == 10000 to <= 10000.\nALLOCATION ORDER (strict): Amount items (fixed, cached as fix) → Rate/RateGross items → Surplus item (remaining).\nRECOMMENDATION: Use Amount mode for known fixed amounts (clearer, no sum constraint). Use Rate mode for proportional splits off the post-fix remainder (requires sum == 10000 unless Surplus present). Use RateGross mode for a percentage of the FULL pool/`max` that must coexist with fixed Amount entries. Use Surplus to capture remainder (e.g., platform fee + host gets rest). Accepts string ('Amount'/'Rate'/'Surplus'/'RateGross', recommended) or number (0/1/2/3)."
                             }
                           },
                           "required": [
@@ -173,12 +174,12 @@
                             "mode"
                           ],
                           "additionalProperties": false,
-                          "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last."
+                          "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate/RateGross items second, Surplus last."
                         },
-                        "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
+                        "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate/RateGross + Surplus) within the same Allocator. RECIPIENT SEMANTICS: the Guard constrains what each submission slot may be; a recipient's safety follows from the sufficiency of those constraints (run the recipient constraint audit). Canonical order pattern: recipient = the single submitted Order — funds land at that object and are receivable only by its owner. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix; RateGross proportional to the full pool) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; NET Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); RateGross sum must <= 10000 (never mixed with NET Rate while a fixed total is present); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
                       },
                       "fix": {
-                        "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation.",
+                        "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract when the allocator is added — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for NET Rate allocation (RateGross ignores fix and uses the full pool/`max`).",
                         "anyOf": [
                           {
                             "type": "number"
@@ -189,7 +190,7 @@
                         ]
                       },
                       "max": {
-                        "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: total_rates = max - fix (instead of balance - fix)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
+                        "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> when the allocator is added: when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: NET Rate total_rates = max - fix; RateGross total_rates = max (fix NOT subtracted)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort.",
                         "anyOf": [
                           {
                             "anyOf": [
@@ -213,7 +214,7 @@
                       "sharing"
                     ],
                     "additionalProperties": false,
-                    "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus."
+                    "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/RateGross/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate/RateGross → Surplus."
                   },
                   "description": "Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."
                 }
@@ -224,7 +225,7 @@
                 "allocators"
               ],
               "additionalProperties": false,
-              "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus)."
+              "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate/RateGross → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's NET Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus); RateGross-mode sharing[] must sum to <= 10000."
             },
             "coin": {
               "anyOf": [
@@ -254,7 +255,7 @@
                   "properties": {
                     "coin": {
                       "type": "string",
-                      "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                      "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                     }
                   },
                   "required": [

package/dist/schemas/onchain_operations_arbitration.schema.json

@@ -141,7 +141,7 @@
                   "properties": {
                     "coin": {
                       "type": "string",
-                      "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                      "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                     }
                   },
                   "required": [
@@ -195,7 +195,7 @@
           "type": "string"
         },
         "fee": {
-          "description": "Arbitration fee.",
+          "description": "Arbitration filing fee. FORMAT: a direct amount value — NOT wrapped in {balance: ...} (that CoinParam shape is only for dispute.fee, which pays a coin object). Accepted: smallest-unit number or string (e.g. 50000000 = 0.05 WOW at 9 decimals), or display format with the token symbol (e.g. \"0.05WOW\") — the Fund Processing Layer converts it using the Arbitration object's own token decimals. Default 0 on creation: disputes are then free (the filer's coin is fully refunded on filing) and the arbitrator earns no per-case fee.",
           "anyOf": [
             {
               "type": "number"
@@ -215,7 +215,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "voting_deadline": {
               "default": 0,
@@ -244,7 +244,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "voting_deadline": {
               "anyOf": [
@@ -270,7 +270,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "votes": {
               "type": "array",
@@ -282,7 +282,7 @@
               "description": "Proposition INDICES (0-based, u8) the voter agrees with — e.g. [0] votes for the first proposition. Re-voting REPLACES the voter's previous vote (old weight removed, new applied). Out-of-range index aborts with E_PROPOSITION_NOT_FOUND."
             },
             "voting_guard": {
-              "description": "Optional Voting Guard for weighted voting. THREE PATHS are supported by the SDK and Move contract: (1) voting_guard PROVIDED → Guard-weighted vote (Guard verifies voter + determines vote weight via VoteWeight config); (2) voting_guard OMITTED but other guards trigger passport creation (e.g. env.permission_guard or usage_guard) → permission-only vote via passport; (3) voting_guard OMITTED and no passport context → vote (plain permission-only vote, no Guard). The Guard (when provided) must be in the Arbitration's voting_guard list.",
+              "description": "Voting Guard for WEIGHTED voting. DECISION RULE (contract-enforced):\n(A) Arbitration HAS a non-empty voting_guard list → plain vote is REJECTED on-chain with E_VOTING_GUARD_USED (abort 2). You MUST provide this field set to ONE guard from the Arbitration's voting_guard list, and fill its submission: when the guard's vote_weight is {GuardIdentifier: pos}, the number you submit at that table position IS the vote weight; when it is {FixedValue: v}, no submission is needed (weight is fixed). The SDK then routes the call through the Guard-weighted vote path via a Passport. Omitting this field on such an Arbitration now fails fast pre-call with the list of valid guards.\n(B) Arbitration has NO voting_guard → omit this field; the SDK uses plain vote (weight 1, permission-gated), or the passport-gated vote path when other guards require it.\nBOTH (B) paths still assert ARBITRATION_VOTE=358 on-chain (the SDK now pre-checks 358 and fails fast with 'Missing permissions 358'). An empty voting_guard means EQUAL WEIGHT (1 person 1 vote), NOT permissionless — there is no permission-free vote entry. For genuinely open voting, configure a public voting_guard (op=\"set\") and vote via path (A): the weighted passport path authorizes by the guard and does NOT require 358.\nThe Guard (when provided) MUST be in the Arbitration's voting_guard list — an unlisted guard aborts with E_VOTING_GUARD_NOT_FOUND.",
               "type": "string"
             }
           },
@@ -298,7 +298,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "feedback": {
               "type": "string",
@@ -317,7 +317,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "feedback": {
               "type": "string",
@@ -342,7 +342,7 @@
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             },
             "feedback": {
               "type": "string",
@@ -356,12 +356,12 @@
           "additionalProperties": false
         },
         "arb_withdraw": {
-          "description": "Withdraw arbitration fees from the Arb object (arbitrator). Immediately from state 5 (Finished); from state 3 only after 30 days from the ruling time (no objection filed — silence = acceptance); rejected in states 0/1/2. State 4 (Objectionable) can NEVER withdraw (protocol 141): a contested case keeps its fee escrowed until the customer closes the objection cycle — reset → order.arb_confirm → new ruling → unchallenged (or accepted via finish).",
+          "description": "Withdraw arbitration fees from the Arb object (arbitrator). Immediately from state 5 (Finished); from state 3 only after 30 days from the ruling time (no objection filed — silence = acceptance); rejected in states 0/1/2. State 4 (Objectionable) can NEVER withdraw (protocol 141): a contested case keeps its fee escrowed until the customer closes the objection cycle — reset → order.arb_confirm → new ruling → unchallenged (or accepted via finish). ⚠️ TWO-STAGE FEE CASH-OUT (verified on testnet): this call does NOT pay the arbitrator's wallet — it moves the case fee into the Arbitration (Registration) object's own balance pool. To actually receive the money: fees_transfer (to a treasury or allocation) → treasury receive: \"recently\" (permission 253) → treasury withdraw → recipient payment receive. A successful arb_withdraw with no wallet balance change is EXPECTED, not a failure.",
           "type": "object",
           "properties": {
             "arb": {
               "type": "string",
-              "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+              "description": "Arb CASE object — the single dispute case created by `dispute` (the object you may have named via `namedArb`). NOT the arbitrator registration object: that one goes in the ROOT `object` field, while every case-scoped operation (confirm / voting_deadline_change / vote / feedback / arbitration / reset / arb_withdraw) addresses the case through THIS field. Accepts the Arb's 0x address or its LocalMark name."
             }
           },
           "required": [
@@ -412,7 +412,7 @@
               "type": "integer",
               "minimum": 0,
               "maximum": 9007199254740991,
-              "description": "Payment index."
+              "description": "0-based index of the fee payment inside the Arb case's fees table (query the Arb case with onchain_operations type 'q' / onchain_table_data to list its fees and their indices). REQUIRED — without it the transfer cannot name which fee record to move."
             },
             "newPayment": {
               "description": "Name for the newly created payment object.",
@@ -706,7 +706,7 @@
         "object"
       ],
       "additionalProperties": false,
-      "description": "On-chain Arbitration operations. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create an Arbitration. NOTE:'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. ⚠️ PERMISSION RULE (contract-enforced): the Arbitration's permission MUST be DIFFERENT from the permission of any Service it will be bound to — binding an Arbitration that SHARES the Service's Permission aborts with E_ARBITRATION_PERMISSION_CONFLICT (error 33). Always create a DEDICATED Permission object for each Arbitration. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation."
+      "description": "On-chain Arbitration operations. TWO OBJECT KINDS — do not confuse them (§5.9): the ROOT 'object' field is the Arbitration (arbitrator REGISTRATION) object; the Arb (single CASE) created by 'dispute' is addressed via each case operation's 'arb' field. USAGE: (1) CREATE NEW: Set 'object' field with OBJECT format {name, type_parameter, permission, ...} to create an Arbitration. NOTE:'name' goes INSIDE 'object', NOT at the data root level. 'permission' can be a new Permission object or reference an existing one - check 'object' field description for details. ⚠️ PERMISSION RULE (contract-enforced): the Arbitration's permission MUST be DIFFERENT from the permission of any Service it will be bound to — binding an Arbitration that SHARES the Service's Permission aborts with E_ARBITRATION_PERMISSION_CONFLICT (error 33). Always create a DEDICATED Permission object for each Arbitration. (2) OPERATE EXISTING: Set 'object' field with STRING format (object ID or name). The 'object' field is CRITICAL and REQUIRED in both cases. STRING for existing, OBJECT for new creation."
     },
     "env": {
       "type": "object",

package/dist/schemas/onchain_operations_machine.schema.json

@@ -362,6 +362,17 @@
                             "type": "string",
                             "description": "Node name. ⚠️ T1 LOSSY POINT (B-1): do NOT name a node 'refund'/'refunded'/'deposit_refunded'/'deposit_deducted'/'disputed'/'cancelled' to model fund return or dispute — funds MUST move through the Allocation waterfall (order_allocators), NOT through Machine terminal nodes (R-M1-11). A node named 'refund' is a semantic lie: reaching it does not move funds by itself. Model refund as a refund-to-Order Allocator slot (a { Signer } or Order-owner recipient), and model dispute as the bound Arbitration, not a Machine node."
                           },
+                          "role": {
+                            "description": "OPTIONAL business role tag for display layers and template reuse (E-9). SESSION METADATA ONLY — the on-chain node struct carries name+pairs, so this is NOT stored on-chain; the MCP echoes it back as a NODE ROLES constraint warning and seed templates annotate it. Semantics: draft = pre-start cancellable, active = work in progress, delivered = work submitted awaiting acceptance, final = settlement endpoint (advancing here should trigger the Allocation fund release), cancelled = refund endpoint (advancing here should trigger the refund Allocator).",
+                            "type": "string",
+                            "enum": [
+                              "draft",
+                              "active",
+                              "delivered",
+                              "final",
+                              "cancelled"
+                            ]
+                          },
                           "pairs": {
                             "type": "array",
                             "items": {
@@ -393,7 +404,7 @@
                                         "description": "Forward name"
                                       },
                                       "namedOperator": {
-                                        "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                        "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                         "anyOf": [
                                           {
                                             "type": "string"
@@ -538,6 +549,17 @@
                             "type": "string",
                             "description": "Node name. ⚠️ T1 LOSSY POINT (B-1): do NOT name a node 'refund'/'refunded'/'deposit_refunded'/'deposit_deducted'/'disputed'/'cancelled' to model fund return or dispute — funds MUST move through the Allocation waterfall (order_allocators), NOT through Machine terminal nodes (R-M1-11). A node named 'refund' is a semantic lie: reaching it does not move funds by itself. Model refund as a refund-to-Order Allocator slot (a { Signer } or Order-owner recipient), and model dispute as the bound Arbitration, not a Machine node."
                           },
+                          "role": {
+                            "description": "OPTIONAL business role tag for display layers and template reuse (E-9). SESSION METADATA ONLY — the on-chain node struct carries name+pairs, so this is NOT stored on-chain; the MCP echoes it back as a NODE ROLES constraint warning and seed templates annotate it. Semantics: draft = pre-start cancellable, active = work in progress, delivered = work submitted awaiting acceptance, final = settlement endpoint (advancing here should trigger the Allocation fund release), cancelled = refund endpoint (advancing here should trigger the refund Allocator).",
+                            "type": "string",
+                            "enum": [
+                              "draft",
+                              "active",
+                              "delivered",
+                              "final",
+                              "cancelled"
+                            ]
+                          },
                           "pairs": {
                             "type": "array",
                             "items": {
@@ -569,7 +591,7 @@
                                         "description": "Forward name"
                                       },
                                       "namedOperator": {
-                                        "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                        "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                         "anyOf": [
                                           {
                                             "type": "string"
@@ -852,7 +874,7 @@
                                   "description": "Forward name"
                                 },
                                 "namedOperator": {
-                                  "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders).",
+                                  "description": "Forward operation permission 1: Namespace (one of the two must be specified); recommended if Progress object operators are different (e.g., different delivery personnel for different orders). SPECIAL CASE: an EMPTY string ('') on an order-bound forward resolves to the ORDER PAYER — the buyer of the order can advance it (progress::IsNamedOperator treats an empty name + order as the order's own operator). Use '' for buyer-side actions (delivery confirmation, review, return request, pre-ship cancel) instead of binding a merchant-only permission index, which aborts E_PERMISSION_DENIED for the buyer.",
                                   "anyOf": [
                                     {
                                       "type": "string"
@@ -1031,7 +1053,7 @@
               "properties": {
                 "json_or_markdown_file": {
                   "type": "string",
-                  "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing workflow states and transitions:\n- name: Node identifier\n- pairs: Array of {prior_node, forwards, threshold} defining connections\n- forwards: Operations available from this node\n- threshold: Required weight to advance\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
+                  "description": "Path to a JSON or Markdown file containing node array for COMPLETE REPLACEMENT of all nodes.\n\n**File Format Requirements:**\n- Must contain a JSON ARRAY of node objects: [{\"name\": \"...\", \"pairs\": [...]}, {...}]\n- NOT an operation object with \"op\" field (use NodeSchema for operations)\n- Supports JSON or Markdown (with ```json code blocks)\n\n**Node Structure:**\nEach node is a directed graph element representing workflow states and transitions:\n- name: Node identifier\n- role: (optional) business role tag for display layers — one of draft/active/delivered/final/cancelled. SESSION METADATA ONLY (not stored on-chain; echoed back as a NODE ROLES warning)\n- pairs: Array of {prior_node, forwards, threshold} defining connections\n- forwards: Operations available from this node\n- threshold: Required weight to advance\n\n**Behavior:**\n- COMPLETELY REPLACES all existing nodes (equivalent to \"set\" with bReplace=true)\n- Auto-detects format based on file content\n- If parsing fails, error includes line number and column information"
                 }
               },
               "required": [
@@ -1046,7 +1068,7 @@
           "type": "boolean"
         },
         "publish": {
-          "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable.",
+          "description": "Whether to publish the object. After the object is published, new Progress objects can be generated; and node settings will no longer be changeable. ⚠️ Before publishing, enumerate the graph STOP NODES (nodes with no outgoing Pair) plus every waiting state (review window, handover, open dispute) and verify each has a defined fund exit in the Service order_allocators — withdrawal (release) AND refund. Machine + Allocator are immutable after publish (IMMUT-001); an uncovered stop node strands funds permanently (rule R-M5-03, checklist pattern.fund_flow_stop_node_coverage).",
           "type": "boolean"
         },
         "owner_receive": {

package/dist/schemas/onchain_operations_order.schema.json

@@ -51,7 +51,7 @@
           "additionalProperties": false
         },
         "required_info": {
-          "description": "Contact object ID (recipient) or WTS Proof object (delivery proof) that information has been delivered via Wowok Messenger.",
+          "description": "Credential recorded on the order: the merchant's IM user address resolved from the Service's Contact (zero cost) or a WTS Proof object id (on-chain delivery proof embedding that IM address and timestamp; costs gas). The information itself is delivered via Wowok Messenger.",
           "anyOf": [
             {
               "type": "string",

package/dist/schemas/onchain_operations_payment.schema.json

@@ -96,7 +96,7 @@
                         "properties": {
                           "coin": {
                             "type": "string",
-                            "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                            "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                           }
                         },
                         "required": [
@@ -195,7 +195,7 @@
             "receive"
           ],
           "additionalProperties": false,
-          "description": "Receive mode: unwrap a CoinWrapper to the caller's wallet. Use after Allocation's alloc_by_guard creates a Payment with your address as a revenue recipient. The CoinWrapper holds your share — call this to convert it to actual coins in your wallet. Provide 'object' to unwrap a specific CoinWrapper, or OMIT it to auto-unwrap every CoinWrapper owned by the caller."
+          "description": "Receive mode: unwrap a CoinWrapper to the caller's wallet. Use after Allocation's alloc_by_guard creates a Payment with your address as a revenue recipient. The CoinWrapper holds your share — call this to convert it to actual coins in your wallet. Provide 'object' to unwrap a specific CoinWrapper, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. AUTO-CLAIM: when the allocation SIGNER and the recipient are the SAME account, the share is credited directly during settlement and NO CoinWrapper is created — a 'no CoinWrapper found' result in that case means the funds already arrived (verify via account_balance), it is NOT a failure."
         }
       ],
       "description": "On-chain Payment operations. TWO modes:\n(1) CREATE: Set 'object' with {name, type_parameter, ...}, 'revenue', and 'info' to create a new Payment.\n(2) RECEIVE: Set {receive: true} to unwrap CoinWrappers to your wallet. Provide 'object' (<coinwrapper_id_or_name>) to unwrap a specific one, or OMIT it to auto-unwrap every CoinWrapper owned by the caller. type_parameter optional — auto-derived from the CoinWrapper's type."

package/dist/schemas/onchain_operations_reward.schema.json

@@ -131,7 +131,7 @@
               "properties": {
                 "coin": {
                   "type": "string",
-                  "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                  "description": "Coin object ID or name(local mark). WHOLE-COIN TRANSFER: the ENTIRE Coin object is moved to the recipient — the 'amount' is NOT taken from it (testnet lesson: passing your main gas coin transfers its full balance, leaving you unable to pay for anything). Use only for coins whose whole balance is exactly what you intend to send; prefer {balance: <smallest-unit number>} for partial amounts."
                 }
               },
               "required": [