@wowok/agent-mcp 2.6.0 → 2.6.1

package/dist/schemas/onchain_operations_reward.schema.json

@@ -119,7 +119,7 @@
                     "number",
                     "string"
                   ],
-                  "description": "Balance type"
+                  "description": "A coin/balance amount in the smallest on-chain unit (u64). Accepts a JS number OR a numeric string. PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — JS numbers lose precision above 2^53. UNIT: this is the smallest unit, NOT the display unit. For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. For custom tokens: use the token's native smallest unit (decimals from coin metadata). Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                 }
               },
               "required": [
@@ -249,7 +249,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",
@@ -266,7 +266,7 @@
                     "description": "Current transaction signer ID"
                   }
                 ],
-                "description": "Recipient ID"
+                "description": "Recipient ID. Three forms:\n  - {GuardIdentifier: u8}  — resolved from Passport at allocation time\n  - {Entity: {name_or_address: 'mark_name'}}  — static address via LocalMark (recommended)\n  - {Signer: 'signer'}  — transaction sender (e.g. self-refund)"
               },
               "amount": {
                 "anyOf": [
@@ -434,7 +434,7 @@
             "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."
         },
         "referrer": {
           "$ref": "#/definitions/env/properties/account",
@@ -814,7 +814,7 @@
                           "description": "vecvecu8"
                         }
                       ],
-                      "description": "Type of the value"
+                      "description": "Type of the value stored in `value`. One of: Bool(0), Address(1), String(2), U8(3), U16(4), U32(5), U64(6), U128(7), U256(8), VecBool(9), VecAddress(10), VecString(11), VecU8(12), VecU16(13), VecU32(14), VecU64(15), VecU128(16), VecU256(17), VecVecU8(18). When value_type=Address (1), the `value` field accepts a hex address string, a LocalMark name, or an AccountOrMark_Address object — see `value` field description for details."
                     },
                     "value": {
                       "anyOf": [
@@ -907,12 +907,12 @@
                           }
                         }
                       ],
-                      "description": "The actual value data"
+                      "description": "The actual value data. Format depends on `value_type`:\n• Bool: true/false (boolean)\n• Address (CRITICAL — string 'Address' is NOT a placeholder): a hex address (e.g. '0x1234...'), a LocalMark name (e.g. 'my-service' — resolved to address at evaluation time), an AccountOrMark_Address object (e.g. {name_or_address:'my-service'}), or system shorthand ('0xaaa' = EntityLinker, '0xaab' = EntityRegistrar). The literal string 'Address' itself is INVALID — it would be treated as a non-existent LocalMark name and fail. Example: value='0x2::wow::WOW<address>' or value='my-permission'.\n• String: any string\n• U8/U16/U32/U64/U128/U256: number or numeric string (e.g. 42 or '42')\n• Vec* types: arrays of the corresponding element type\nREQUIRED when b_submission=false. OPTIONAL when b_submission=true (value is supplied at evaluation time by user submission)."
                     },
                     "name": {
                       "type": "string",
                       "default": "",
-                      "description": "Name or description of this data"
+                      "description": "Data name identifier. MAX 64 BCS characters (Chinese chars count as 3-4 BCS bytes each). Use short identifiers like 'order_id', 'delivery_node'. Put longer descriptions in the Guard's 'description' field, NOT here."
                     },
                     "object_type": {
                       "type": "string",
@@ -950,7 +950,7 @@
                         "TableItem_AddressMark",
                         "TableItem_EntityRegistrar"
                       ],
-                      "description": "Object type when value_type is Address and represents a specific object"
+                      "description": "OUTPUT-ONLY (query side): Object type when value_type is Address and represents a specific object. Auto-derived by the system — DO NOT set this field at Guard creation."
                     }
                   },
                   "required": [
@@ -959,7 +959,7 @@
                     "value_type"
                   ],
                   "additionalProperties": false,
-                  "description": "Guard table item"
+                  "description": "Guard table item (QUERY/OUTPUT form — includes auto-derived object_type field)"
                 },
                 "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
               }
@@ -971,7 +971,7 @@
             "additionalProperties": false,
             "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
           },
-          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
+          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission. PLACEMENT: this `submission` field is at the SAME level as `data` and `env` in the operation input — NOT inside `data.data`. Example structure: {tool:'onchain_operations', data:{operation_type:'order', data:{object:'my_order', progress:{...}}}, submission:{type:'submission', guard:[...], submission:[...]}}"
         }
       },
       "required": [

package/dist/schemas/onchain_operations_service.schema.json

@@ -147,7 +147,7 @@
                             "number",
                             "string"
                           ],
-                          "description": "Balance type"
+                          "description": "A coin/balance amount in the smallest on-chain unit (u64). Accepts a JS number OR a numeric string. PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — JS numbers lose precision above 2^53. UNIT: this is the smallest unit, NOT the display unit. For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. For custom tokens: use the token's native smallest unit (decimals from coin metadata). Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                         }
                       },
                       "required": [
@@ -311,11 +311,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": [
@@ -490,14 +490,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"
@@ -588,7 +590,7 @@
                 "threshold": {
                   "$ref": "#/definitions/data/properties/order_new/properties/buy/properties/total_pay/anyOf/0/properties/balance",
                   "default": 0,
-                  "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."
                 },
                 "allocators": {
                   "type": "array",
@@ -597,7 +599,7 @@
                     "properties": {
                       "guard": {
                         "$ref": "#/definitions/data/properties/object/anyOf/0",
-                        "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",
@@ -633,7 +635,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",
@@ -650,23 +652,32 @@
                                   "description": "Current transaction signer ID"
                                 }
                               ],
-                              "description": "Recipient ID"
+                              "description": "Recipient of this allocation. Three forms:\n• { GuardIdentifier: u8 } — resolved from Passport at allocation time. 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.\n• { Entity: { name_or_address: '...' } } — static address resolved via LocalMark. Use for known recipients (e.g., 'turo_host', or a Treasury object address).\n• 'Signer' — the transaction sender (tx_context::sender). Use when the recipient is the current signer (e.g., self-refund scenarios)."
                             },
                             "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": [
@@ -675,13 +686,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/data/properties/order_new/properties/buy/properties/total_pay/anyOf/0/properties/balance",
-                        "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": [
@@ -692,7 +703,7 @@
                             "type": "null"
                           }
                         ],
-                        "description": "Maximum allocation amount. If specified, allocation amount cannot exceed maximum allocation amount."
+                        "description": "Maximum allocation cap (optional). Has THREE effects:\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)."
                       }
                     },
                     "required": [
@@ -700,9 +711,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": [
@@ -710,7 +721,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"
@@ -855,7 +866,7 @@
         },
         "publish": {
           "type": "boolean",
-          "description": "Whether to publish the Service. After publishing, customers can place orders; at the same time, service commitments such as machine, order_allocators, arbitrations, etc. will be immutable."
+          "description": "Whether to publish the Service. After publishing, customers can place orders. BUG-04 fix (v2.2 — verified against Move source service.move + SDK service.ts):\n  SDK-LOCKED after publish (checkNotPublished — cannot modify, must clone new Service):\n    • machine          (permanently locked — workflow template)\n    • order_allocators (permanently locked — fund distribution rules)\n    • arbitrations     (permanently locked at SDK level — dispute resolution objects)\n  TIME-LOCKED after publish (modifiable only after pause + setting_lock_duration elapsed):\n    • rewards remove/clear  (assert_not_published — time-based lock)\n  REMAIN MUTABLE after publish (no SDK check, no Move check):\n    • buy_guard            (CAN be modified after publish — purchase eligibility guard)\n    • setting_locked_time_add (CAN be extended — only increases, never decreases)\n    • sales, discount, description, location, pause, repositories,\n    • compensation_fund_add, customer_required, um (Contact), rewards add\nThese 3 SDK-LOCKED fields (machine/order_allocators/arbitrations) MUST be set BEFORE publish=true.\n\nSCHEMA-03 / P0-01 fix — DEPLOYMENT WORKFLOW (two-phase, avoids circular dependency):\n  Phase 1 — CREATE (no publish): object={name:'my-service', type_parameter, permission} + machine + order_allocators + arbitrations.\n    NOTE: buy_guard can use a LocalMark NAME (not address) to break the Guard→Service circular dependency.\n    The name is resolved to an address at transaction build time.\n  Phase 2 — PUBLISH: object='my-service' (string ref) + publish=true.\n    All SDK-LOCKED fields must be set in Phase 1; Phase 2 only flips the publish flag.\n  Post-publish updates: buy_guard, sales, description, repositories (add), rewards (add), etc."
         }
       },
       "required": [
@@ -890,7 +901,7 @@
             "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."
         },
         "referrer": {
           "$ref": "#/definitions/env/properties/account",
@@ -1270,7 +1281,7 @@
                           "description": "vecvecu8"
                         }
                       ],
-                      "description": "Type of the value"
+                      "description": "Type of the value stored in `value`. One of: Bool(0), Address(1), String(2), U8(3), U16(4), U32(5), U64(6), U128(7), U256(8), VecBool(9), VecAddress(10), VecString(11), VecU8(12), VecU16(13), VecU32(14), VecU64(15), VecU128(16), VecU256(17), VecVecU8(18). When value_type=Address (1), the `value` field accepts a hex address string, a LocalMark name, or an AccountOrMark_Address object — see `value` field description for details."
                     },
                     "value": {
                       "anyOf": [
@@ -1363,12 +1374,12 @@
                           }
                         }
                       ],
-                      "description": "The actual value data"
+                      "description": "The actual value data. Format depends on `value_type`:\n• Bool: true/false (boolean)\n• Address (CRITICAL — string 'Address' is NOT a placeholder): a hex address (e.g. '0x1234...'), a LocalMark name (e.g. 'my-service' — resolved to address at evaluation time), an AccountOrMark_Address object (e.g. {name_or_address:'my-service'}), or system shorthand ('0xaaa' = EntityLinker, '0xaab' = EntityRegistrar). The literal string 'Address' itself is INVALID — it would be treated as a non-existent LocalMark name and fail. Example: value='0x2::wow::WOW<address>' or value='my-permission'.\n• String: any string\n• U8/U16/U32/U64/U128/U256: number or numeric string (e.g. 42 or '42')\n• Vec* types: arrays of the corresponding element type\nREQUIRED when b_submission=false. OPTIONAL when b_submission=true (value is supplied at evaluation time by user submission)."
                     },
                     "name": {
                       "type": "string",
                       "default": "",
-                      "description": "Name or description of this data"
+                      "description": "Data name identifier. MAX 64 BCS characters (Chinese chars count as 3-4 BCS bytes each). Use short identifiers like 'order_id', 'delivery_node'. Put longer descriptions in the Guard's 'description' field, NOT here."
                     },
                     "object_type": {
                       "type": "string",
@@ -1406,7 +1417,7 @@
                         "TableItem_AddressMark",
                         "TableItem_EntityRegistrar"
                       ],
-                      "description": "Object type when value_type is Address and represents a specific object"
+                      "description": "OUTPUT-ONLY (query side): Object type when value_type is Address and represents a specific object. Auto-derived by the system — DO NOT set this field at Guard creation."
                     }
                   },
                   "required": [
@@ -1415,7 +1426,7 @@
                     "value_type"
                   ],
                   "additionalProperties": false,
-                  "description": "Guard table item"
+                  "description": "Guard table item (QUERY/OUTPUT form — includes auto-derived object_type field)"
                 },
                 "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
               }
@@ -1427,7 +1438,7 @@
             "additionalProperties": false,
             "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
           },
-          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
+          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission. PLACEMENT: this `submission` field is at the SAME level as `data` and `env` in the operation input — NOT inside `data.data`. Example structure: {tool:'onchain_operations', data:{operation_type:'order', data:{object:'my_order', progress:{...}}}, submission:{type:'submission', guard:[...], submission:[...]}}"
         }
       },
       "required": [

package/dist/schemas/onchain_operations_treasury.schema.json

@@ -115,7 +115,7 @@
                     "number",
                     "string"
                   ],
-                  "description": "Balance type"
+                  "description": "A coin/balance amount in the smallest on-chain unit (u64). Accepts a JS number OR a numeric string. PRECISION RULE: for values exceeding 2^53 (e.g. token amounts with 18 decimals), ALWAYS pass a numeric STRING (e.g. \"1000000000000000000\") to preserve precision — JS numbers lose precision above 2^53. UNIT: this is the smallest unit, NOT the display unit. For SUI: 1 SUI = 10^9 MIST, so 10 SUI = 10000000000. For custom tokens: use the token's native smallest unit (decimals from coin metadata). Examples: 10000000000 (10 SUI), \"1000000000000000000\" (1 token with 18 decimals), 500 (500 units of a token with 0 decimals). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                 },
                 "token_type": {
                   "type": "string",
@@ -634,7 +634,7 @@
             "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."
         },
         "referrer": {
           "$ref": "#/definitions/env/properties/account",
@@ -1014,7 +1014,7 @@
                           "description": "vecvecu8"
                         }
                       ],
-                      "description": "Type of the value"
+                      "description": "Type of the value stored in `value`. One of: Bool(0), Address(1), String(2), U8(3), U16(4), U32(5), U64(6), U128(7), U256(8), VecBool(9), VecAddress(10), VecString(11), VecU8(12), VecU16(13), VecU32(14), VecU64(15), VecU128(16), VecU256(17), VecVecU8(18). When value_type=Address (1), the `value` field accepts a hex address string, a LocalMark name, or an AccountOrMark_Address object — see `value` field description for details."
                     },
                     "value": {
                       "anyOf": [
@@ -1107,12 +1107,12 @@
                           }
                         }
                       ],
-                      "description": "The actual value data"
+                      "description": "The actual value data. Format depends on `value_type`:\n• Bool: true/false (boolean)\n• Address (CRITICAL — string 'Address' is NOT a placeholder): a hex address (e.g. '0x1234...'), a LocalMark name (e.g. 'my-service' — resolved to address at evaluation time), an AccountOrMark_Address object (e.g. {name_or_address:'my-service'}), or system shorthand ('0xaaa' = EntityLinker, '0xaab' = EntityRegistrar). The literal string 'Address' itself is INVALID — it would be treated as a non-existent LocalMark name and fail. Example: value='0x2::wow::WOW<address>' or value='my-permission'.\n• String: any string\n• U8/U16/U32/U64/U128/U256: number or numeric string (e.g. 42 or '42')\n• Vec* types: arrays of the corresponding element type\nREQUIRED when b_submission=false. OPTIONAL when b_submission=true (value is supplied at evaluation time by user submission)."
                     },
                     "name": {
                       "type": "string",
                       "default": "",
-                      "description": "Name or description of this data"
+                      "description": "Data name identifier. MAX 64 BCS characters (Chinese chars count as 3-4 BCS bytes each). Use short identifiers like 'order_id', 'delivery_node'. Put longer descriptions in the Guard's 'description' field, NOT here."
                     },
                     "object_type": {
                       "type": "string",
@@ -1150,7 +1150,7 @@
                         "TableItem_AddressMark",
                         "TableItem_EntityRegistrar"
                       ],
-                      "description": "Object type when value_type is Address and represents a specific object"
+                      "description": "OUTPUT-ONLY (query side): Object type when value_type is Address and represents a specific object. Auto-derived by the system — DO NOT set this field at Guard creation."
                     }
                   },
                   "required": [
@@ -1159,7 +1159,7 @@
                     "value_type"
                   ],
                   "additionalProperties": false,
-                  "description": "Guard table item"
+                  "description": "Guard table item (QUERY/OUTPUT form — includes auto-derived object_type field)"
                 },
                 "description": "User-submitted data matching the Guard's required fields. Relation: structure must match the Guard table's column definitions. Example: [{field:'delivery_proof', value:'Qm...'}]"
               }
@@ -1171,7 +1171,7 @@
             "additionalProperties": false,
             "description": "One Guard's submission data: the Guard to verify plus the user-provided data that satisfies its requirements."
           },
-          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission."
+          "description": "User-submitted data for each Guard. Relation: one entry per Guard in the guard array; fill submission fields and resubmit via call_with_submission. PLACEMENT: this `submission` field is at the SAME level as `data` and `env` in the operation input — NOT inside `data.data`. Example structure: {tool:'onchain_operations', data:{operation_type:'order', data:{object:'my_order', progress:{...}}}, submission:{type:'submission', guard:[...], submission:[...]}}"
         }
       },
       "required": [

package/dist/schemas/onchain_table_data.output.json

@@ -1582,7 +1582,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": [
@@ -1642,38 +1642,46 @@
                                     "guard": {
                                       "anyOf": [
                                         {
-                                          "type": "object",
-                                          "properties": {
-                                            "guard": {
-                                              "type": "string",
-                                              "description": "Guard object ID"
-                                            },
-                                            "retained_submission": {
-                                              "anyOf": [
-                                                {
-                                                  "type": "array",
-                                                  "items": {
-                                                    "$ref": "#/definitions/onchain_table_data/properties/result/anyOf/8/properties/result/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/onchain_table_data/properties/result/anyOf/8/properties/result/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": [
@@ -1683,7 +1691,7 @@
                                   "additionalProperties": false,
                                   "description": "Forward in Machine object"
                                 },
-                                "description": "Forward list"
+                                "description": "Forward list — operations to ENTER THIS NODE from prev_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. 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": [

package/dist/schemas/onchain_table_data.schema.json

@@ -45,7 +45,7 @@
                     "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": [
@@ -99,7 +99,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -139,7 +139,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -174,7 +174,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -208,7 +208,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -248,7 +248,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -293,7 +293,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -334,7 +334,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -366,7 +366,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -401,7 +401,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -442,7 +442,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [
@@ -507,7 +507,7 @@
                 },
                 "network": {
                   "$ref": "#/definitions/onchain_table_data/anyOf/0/anyOf/0/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": [