@wowok/agent-mcp 2.6.0 → 2.6.3

package/dist/schemas/query_toolkit.output.json

@@ -535,7 +535,7 @@
           "address"
         ],
         "additionalProperties": false,
-        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain."
+        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain. CROSS-NETWORK ISOLATION (DOC-02): LocalMark names are scoped per network — the same name 'my-service' can map to different addresses on testnet vs mainnet. When switching networks (e.g., testnet→mainnet deployment), re-create marks with the same names pointing to the new mainnet addresses. This enables name-based object references that work identically across networks without code changes."
       },
       "description": "Local mark list"
     },
@@ -2648,11 +2648,11 @@
               },
               "wip": {
                 "type": "string",
-                "description": "HTTP URL of wip file"
+                "description": "WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. Example: \"https://cdn.example.com/products/phone_v1.wip\""
               },
               "wip_hash": {
                 "type": "string",
-                "description": "Hash of WIP. If EMPTY string, the hash within wip will be automatically used; else, the consistency of the hash within wip will be verified with the provided hash."
+                "description": "WIP file hash (hex string). EMPTY string \"\" skips hash comparison (TESTING ONLY). Production: fill with the hash you saw when viewing the product, to prevent merchant replacing the WIP file before order."
               }
             },
             "required": [
@@ -2716,7 +2716,7 @@
             "number",
             "string"
           ],
-          "description": "Compensation fund pool for arbitration results. Order users can receive compensation from this fund based on arbitration results."
+          "description": "Compensation fund BALANCE (NOT a Treasury address). This field reports the total amount of funds currently held in the Service's compensation pool. To ADD funds, use `service.compensation_fund_add`. To RECEIVE funds (as order owner after arbitration), use `service.compensation_fund_receive`. P2-03 clarification: this is a balance value (e.g. {balance: '1000000000', token_type: '0x2::wow::WOW'}), NOT the Treasury object address. The Treasury address (if bound) is queried separately via the Service's `repositories` or `order_allocators` configuration."
         },
         "paused_time": {
           "type": [
@@ -2747,7 +2747,7 @@
                     "number",
                     "string"
                   ],
-                  "description": "Threshold. If defined, fund allocation will be triggered when amount in Allocation object reaches this threshold.",
+                  "description": "Minimum balance required for allocation to fire. When the Allocation object's balance < threshold, allocation aborts with EINSUFFICIENT_BALANCE=7. Also: when an Allocator has only Amount items (no Rate, no Surplus), the sum of Amount items must be >= threshold (EAMOUNT_BELOW_THRESHOLD=12). Set to 0 (default) to allow any balance.",
                   "default": 0
                 },
                 "allocators": {
@@ -2757,7 +2757,7 @@
                     "properties": {
                       "guard": {
                         "type": "string",
-                        "description": "Guard object ID. If Guard verification passes, fund allocation will start automatically."
+                        "description": "Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."
                       },
                       "sharing": {
                         "type": "array",
@@ -2805,7 +2805,7 @@
                                     "Entity"
                                   ],
                                   "additionalProperties": false,
-                                  "description": "Determined ID"
+                                  "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                                 },
                                 {
                                   "type": "object",
@@ -2819,26 +2819,35 @@
                                     "Signer"
                                   ],
                                   "additionalProperties": false,
-                                  "description": "Current transaction signer ID"
+                                  "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                                 }
                               ],
-                              "description": "Recipient ID"
+                              "description": "Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). Use 0 for Order owner in Service-integrated mode (Customer who created the Order). The identifier must match a Guard table entry with b_submission=true. If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). Use for known recipients (e.g., 'turo_host', or a Treasury object address). Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). RESOLVED AT EXECUTION TIME, not at config time. For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."
                             },
                             "sharing": {
                               "type": [
                                 "number",
                                 "string"
                               ],
-                              "description": "Reward allocation value"
+                              "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."
                             },
                             "mode": {
-                              "type": "string",
-                              "enum": [
-                                "Amount",
-                                "Rate",
-                                "Surplus"
+                              "anyOf": [
+                                {
+                                  "type": "string",
+                                  "enum": [
+                                    "Amount",
+                                    "Rate",
+                                    "Surplus"
+                                  ]
+                                },
+                                {
+                                  "type": "integer",
+                                  "minimum": 0,
+                                  "maximum": 2
+                                }
                               ],
-                              "description": "Reward allocation mode"
+                              "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)."
                             }
                           },
                           "required": [
@@ -2847,13 +2856,13 @@
                             "mode"
                           ],
                           "additionalProperties": false,
-                          "description": "Fund allocation item"
+                          "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 list. Each item represents a recipient and their corresponding reward allocation value."
+                        "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. 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)."
                       },
                       "fix": {
                         "$ref": "#/definitions/object_service/properties/order_allocators/anyOf/0/properties/threshold",
-                        "description": "Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."
+                        "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract during `allocator_add` — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation."
                       },
                       "max": {
                         "anyOf": [
@@ -2864,7 +2873,7 @@
                             "type": "null"
                           }
                         ],
-                        "description": "Maximum allocation amount. If specified, allocation amount cannot exceed maximum allocation amount."
+                        "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> via allocator_add(): 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."
                       }
                     },
                     "required": [
@@ -2872,9 +2881,9 @@
                       "sharing"
                     ],
                     "additionalProperties": false,
-                    "description": "Fund allocator"
+                    "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 list. Each fund allocator represents a fund allocation strategy."
+                  "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)."
                 }
               },
               "required": [
@@ -2882,7 +2891,7 @@
                 "allocators"
               ],
               "additionalProperties": false,
-              "description": "Fund allocator list"
+              "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)."
             },
             {
               "type": "null"
@@ -4879,7 +4888,7 @@
             "properties": {
               "guard": {
                 "type": "string",
-                "description": "Guard object ID. If Guard verification passes, fund allocation will start automatically."
+                "description": "Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."
               },
               "sharing": {
                 "type": "array",
@@ -4927,7 +4936,7 @@
                             "Entity"
                           ],
                           "additionalProperties": false,
-                          "description": "Determined ID"
+                          "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                         },
                         {
                           "type": "object",
@@ -4941,26 +4950,35 @@
                             "Signer"
                           ],
                           "additionalProperties": false,
-                          "description": "Current transaction signer ID"
+                          "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                         }
                       ],
-                      "description": "Recipient ID"
+                      "description": "Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). Use 0 for Order owner in Service-integrated mode (Customer who created the Order). The identifier must match a Guard table entry with b_submission=true. If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). Use for known recipients (e.g., 'turo_host', or a Treasury object address). Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). RESOLVED AT EXECUTION TIME, not at config time. For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."
                     },
                     "sharing": {
                       "type": [
                         "number",
                         "string"
                       ],
-                      "description": "Reward allocation value"
+                      "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."
                     },
                     "mode": {
-                      "type": "string",
-                      "enum": [
-                        "Amount",
-                        "Rate",
-                        "Surplus"
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "enum": [
+                            "Amount",
+                            "Rate",
+                            "Surplus"
+                          ]
+                        },
+                        {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 2
+                        }
                       ],
-                      "description": "Reward allocation mode"
+                      "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)."
                     }
                   },
                   "required": [
@@ -4969,16 +4987,16 @@
                     "mode"
                   ],
                   "additionalProperties": false,
-                  "description": "Fund allocation item"
+                  "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 list. Each item represents a recipient and their corresponding reward allocation value."
+                "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. 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)."
               },
               "fix": {
                 "type": [
                   "number",
                   "string"
                 ],
-                "description": "Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."
+                "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract during `allocator_add` — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation."
               },
               "max": {
                 "anyOf": [
@@ -4989,7 +5007,7 @@
                     "type": "null"
                   }
                 ],
-                "description": "Maximum allocation amount. If specified, allocation amount cannot exceed maximum allocation amount."
+                "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> via allocator_add(): 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."
               }
             },
             "required": [
@@ -4997,7 +5015,7 @@
               "sharing"
             ],
             "additionalProperties": false,
-            "description": "Fund allocator"
+            "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 allocation object allocator list"
         },
@@ -5315,7 +5333,7 @@
                       "Entity"
                     ],
                     "additionalProperties": false,
-                    "description": "Determined ID"
+                    "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                   },
                   {
                     "type": "object",
@@ -5329,10 +5347,10 @@
                       "Signer"
                     ],
                     "additionalProperties": false,
-                    "description": "Current transaction signer ID"
+                    "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                   }
                 ],
-                "description": "Recipient ID"
+                "description": "Recipient ID. Three forms:\n  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)"
               },
               "amount": {
                 "anyOf": [
@@ -5366,7 +5384,7 @@
                           "number",
                           "string"
                         ],
-                        "description": "Balance type"
+                        "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                       }
                     },
                     "required": [
@@ -6352,7 +6370,7 @@
                       "Entity"
                     ],
                     "additionalProperties": false,
-                    "description": "Determined ID"
+                    "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                   },
                   {
                     "type": "object",
@@ -6366,17 +6384,17 @@
                       "Signer"
                     ],
                     "additionalProperties": false,
-                    "description": "Current transaction signer ID"
+                    "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                   }
                 ],
-                "description": "Recipient ID"
+                "description": "Recipient ID. Three forms:\n  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)"
               },
               "amount": {
                 "type": [
                   "number",
                   "string"
                 ],
-                "description": "Balance type"
+                "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
               }
             },
             "required": [
@@ -8406,14 +8424,16 @@
         "discount_type": {
           "anyOf": [
             {
-              "type": "number",
-              "const": 0,
-              "description": "Rate discount type"
+              "type": "string",
+              "enum": [
+                "RATES",
+                "FIXED"
+              ]
             },
             {
-              "type": "number",
-              "const": 1,
-              "description": "Fixed discount type"
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1
             }
           ],
           "description": "Discount type. If rate(0), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount)."
@@ -8425,7 +8445,7 @@
                 "number",
                 "string"
               ],
-              "description": "Balance type"
+              "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
             },
             {
               "type": "null"
@@ -13013,7 +13033,7 @@
                 "properties": {
                   "prev_node": {
                     "type": "string",
-                    "description": "Previous node name"
+                    "description": "Previous node name. Empty string '' means initial entry node (the first node in the workflow)."
                   },
                   "threshold": {
                     "type": [
@@ -13073,38 +13093,46 @@
                         "guard": {
                           "anyOf": [
                             {
-                              "type": "object",
-                              "properties": {
-                                "guard": {
-                                  "type": "string",
-                                  "description": "Guard object ID"
-                                },
-                                "retained_submission": {
-                                  "anyOf": [
-                                    {
-                                      "type": "array",
-                                      "items": {
-                                        "$ref": "#/definitions/query_result_onchain_table_item_machine_node/anyOf/0/properties/value/items/properties/threshold"
-                                      }
+                              "anyOf": [
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "guard": {
+                                      "type": "string",
+                                      "description": "Guard object name or address (string). Example: 'my_attendance_guard' or '0x1234...'"
                                     },
-                                    {
-                                      "type": "null"
+                                    "retained_submission": {
+                                      "anyOf": [
+                                        {
+                                          "type": "array",
+                                          "items": {
+                                            "$ref": "#/definitions/query_result_onchain_table_item_machine_node/anyOf/0/properties/value/items/properties/threshold"
+                                          }
+                                        },
+                                        {
+                                          "type": "null"
+                                        }
+                                      ],
+                                      "description": "Data submitted by user during Guard object verification"
                                     }
+                                  },
+                                  "required": [
+                                    "guard"
                                   ],
-                                  "description": "Data submitted by user during Guard object verification"
+                                  "additionalProperties": false,
+                                  "description": "OBJECT form: {guard: '<guard_name_or_address>', retained_submission?: number[]}. Use this form when you need to pass retained_submission data alongside the Guard reference."
+                                },
+                                {
+                                  "type": "string",
+                                  "description": "STRING form (shorthand): the Guard object's name or address as a plain string. Auto-wrapped to {guard: <string>} at runtime. Use this when you only need to reference a Guard without retained_submission."
                                 }
-                              },
-                              "required": [
-                                "guard"
-                              ],
-                              "additionalProperties": false,
-                              "description": "Record of Guard object in MachineForwardGuard object"
+                              ]
                             },
                             {
                               "type": "null"
                             }
                           ],
-                          "description": "Guard object ID, if defined, Guard verification must also pass to complete Forward (e.g., completed promised supply chain sub-order)."
+                          "description": "Guard reference for this forward. Accepts TWO formats:\n• STRING (preferred): \"my_guard_name\" — the Guard's name or address as a plain string.\n• OBJECT (only when retained_submission is needed): {guard: \"my_guard_name\", retained_submission: [1,2,3]}.\nFOLLOW THE SCHEMA FIELD STRUCTURE: A Guard reference is fundamentally a STRING (the Guard object's name or address). Provide a string when you only need to reference a Guard — do NOT wrap a bare string in an object structure. The OBJECT form {guard: \"...\", retained_submission: [...]} exists ONLY to carry additional `retained_submission` data alongside the string reference; inside the object, the `guard` field is STILL a string. In short: string-in for a string reference, object-in only when you need to pass extra data.\nCOGNITIVE PRINCIPLE: Guard validation ALWAYS occurs BEFORE the forward operation. A Guard that queries state of the SAME Progress object this forward operates on (e.g. progress.current) will see the PRE-transition value (source node), NOT the target node. If the Guard checks progress.current == target_node, it will ALWAYS FAIL. Querying a DIFFERENT Progress object (cross-machine) is safe and reasonable — that progress is not modified by this forward. For target-node verification after transition, bind the Guard to the Allocator instead (allocation.alloc runs AFTER the state transition completes)."
                         }
                       },
                       "required": [
@@ -13114,7 +13142,7 @@
                       "additionalProperties": false,
                       "description": "Forward in Machine object"
                     },
-                    "description": "Forward list"
+                    "description": "Forward list — operations to ENTER THIS NODE from prev_node. SEMANTIC CLARIFICATION: forwards describe INCOMING transitions (how to ARRIVE at this node), NOT outgoing transitions. Think of each forward as an 'entry door' to this node. Example: pair {prev_node:'A', forwards:[{name:'Go'}]} means 'use Go to advance FROM A TO THIS NODE'. For initial node (prev_node=''), forwards are operations to enter this node from the start state. DIAGRAM: A --[Go]--> B means the pair belongs to node B (destination), with prev_node='A'. WARNING: forwards belong to the DESTINATION node's pair, NOT the source node. Placing a forward on the wrong pair will cause Progress to get stuck."
                   }
                 },
                 "required": [
@@ -14173,7 +14201,7 @@
                 "number",
                 "string"
               ],
-              "description": "Balance type"
+              "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
             },
             "token_type": {
               "type": "string",

package/dist/schemas/query_toolkit.schema.json

@@ -252,7 +252,7 @@
             },
             "name_or_address": {
               "type": "string",
-              "description": "Account name or address. Use empty string '' for the default account. Defaults to '' if omitted."
+              "description": "Account name or address to query. Examples: \"my_account\", \"0xabc123...\", or \"\" for the default account. NOTE: This field is NOT named 'filter' — use 'name_or_address' directly. Defaults to '' (default account) if omitted."
             },
             "balance": {
               "type": "boolean",
@@ -281,7 +281,7 @@
             },
             "token_type": {
               "type": "string",
-              "description": "Token type to query; defaults to 0x2::wow::WOW (platform token)"
+              "description": "Token type in Move format: 0x<package>::<module>::<struct>. Examples: \"0x2::wow::WOW\" (default, 9 decimals), \"0x2::sui::SUI\" (9 decimals). For custom tokens, use the full type string from the token's coin metadata. The Fund Processing Layer resolves precision from the official registry → cache → on-chain."
             },
             "network": {
               "type": "string",
@@ -290,14 +290,14 @@
                 "testnet",
                 "mainnet"
               ],
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
             "query_type"
           ],
           "additionalProperties": false,
-          "description": "Query an account's coin balance OR paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Returns: { address, balance? | coin? }"
+          "description": "Query an account's coin balance OR paginated coin objects. PARAMETERS: Use 'name_or_address' to specify the account (NOT 'filter'). Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Use token_type to query non-default tokens (format: 0x<package>::<module>::<struct>). Returns: { address, balance? | coin? }"
         },
         {
           "type": "object",
@@ -338,7 +338,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
@@ -367,7 +367,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
@@ -387,8 +387,8 @@
             "name_or_address": {
               "anyOf": [
                 {
-                  "type": "string",
-                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x1234...' - uses address directly"
+                  "$ref": "#/definitions/query_toolkit/anyOf/4/properties/name_or_address",
+                  "description": "Account name, address (0x...), or mark name. When using string format, local marks are searched first. EXAMPLE: 'alice' - searches local marks first, then global; EXAMPLE: '0x2...' (64 hex chars) - uses address directly; EXAMPLE: '' - uses the default local account"
                 },
                 {
                   "type": "object",
@@ -443,7 +443,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
@@ -470,7 +470,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
@@ -519,7 +519,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [
@@ -575,7 +575,7 @@
             },
             "network": {
               "$ref": "#/definitions/query_toolkit/anyOf/4/properties/network",
-              "description": "Network entrypoint: Specifies which network the operation occurs on"
+              "description": "Network entrypoint: Specifies which network the operation occurs on. FIX-010 cross-network note: LocalMark names are scoped per network (testnet marks are invisible on mainnet and vice versa). When migrating from testnet to mainnet, recreate all objects on mainnet and re-register LocalMark names with the SAME names to keep name-based references working across networks. Use project_operation action='clone_project_to_network' to clone the project blueprint to the target network, then re-run onchain_operations with env.network=target_network to deploy."
             }
           },
           "required": [