@wowok/agent-mcp 2.5.5 → 2.6.1

package/dist/schemas/onchain_operations.schema.json

@@ -805,7 +805,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": [
@@ -898,12 +898,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",
@@ -941,7 +941,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": [
@@ -950,7 +950,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...'}]"
                   }
@@ -962,7 +962,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": [
@@ -999,7 +999,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/data_gen_passport/properties/guard/anyOf/0",
@@ -1162,7 +1162,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/data_gen_proof/properties/env/properties/account",
@@ -1238,7 +1238,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",
@@ -1618,7 +1618,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": [
@@ -1711,12 +1711,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",
@@ -1754,7 +1754,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": [
@@ -1763,7 +1763,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...'}]"
               }
@@ -1775,7 +1775,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": [
@@ -1907,7 +1907,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": [
@@ -2071,11 +2071,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": [
@@ -2250,14 +2250,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"
@@ -2348,7 +2350,7 @@
                 "threshold": {
                   "$ref": "#/definitions/data_service/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",
@@ -2357,7 +2359,7 @@
                     "properties": {
                       "guard": {
                         "$ref": "#/definitions/data_service/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",
@@ -2393,7 +2395,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",
@@ -2410,23 +2412,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": [
@@ -2435,13 +2446,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_service/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": [
@@ -2452,7 +2463,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": [
@@ -2460,9 +2471,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": [
@@ -2470,7 +2481,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"
@@ -2615,7 +2626,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": [
@@ -2886,7 +2897,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": [
@@ -2946,38 +2957,46 @@
                                       "guard": {
                                         "anyOf": [
                                           {
-                                            "type": "object",
-                                            "properties": {
-                                              "guard": {
-                                                "type": "string",
-                                                "description": "Guard object ID"
-                                              },
-                                              "retained_submission": {
-                                                "anyOf": [
-                                                  {
-                                                    "type": "array",
-                                                    "items": {
-                                                      "$ref": "#/definitions/data_machine/properties/node/anyOf/0/anyOf/0/properties/nodes/items/properties/pairs/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/data_machine/properties/node/anyOf/0/anyOf/0/properties/nodes/items/properties/pairs/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": [
@@ -2987,7 +3006,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": [
@@ -3336,7 +3355,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",
@@ -3563,7 +3582,7 @@
                 "unhold",
                 "adminUnhold"
               ],
-              "description": "Operation type on the forward: 'next' = advance the forward (accomplish); 'hold' = set hold to block the forward; 'unhold' = self-unhold, release own hold (no 224 permission needed); 'adminUnhold' = force-release hold via 224 permission (PROGRESS_UNHOLD)."
+              "description": "Operation type on the forward (CANONICAL form — prefer this): 'next' = advance the forward (accomplish); 'hold' = set hold to block the forward; 'unhold' = self-unhold, release own hold (no 224 permission needed); 'adminUnhold' = force-release hold via 224 permission (PROGRESS_UNHOLD). LEGACY ALIAS: `hold: boolean` is auto-converted to `op` — `hold:true`→`op:'hold'`, `hold:false`→`op:'next'`. New code should use `op` directly."
             },
             "message": {
               "type": "string",
@@ -4519,7 +4538,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",
@@ -4689,7 +4708,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": [
@@ -5403,7 +5422,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",
@@ -5548,7 +5567,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",
@@ -6134,7 +6153,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": [
@@ -6264,7 +6283,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",
@@ -6281,7 +6300,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": [
@@ -6471,7 +6490,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": {
@@ -6481,7 +6500,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",
@@ -6529,7 +6548,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",
@@ -6546,23 +6565,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": [
@@ -6571,13 +6599,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_allocation/anyOf/0/properties/allocators/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": [
@@ -6588,7 +6616,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": [
@@ -6596,9 +6624,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": [
@@ -6606,7 +6634,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)."
             },
             "coin": {
               "anyOf": [
@@ -7212,7 +7240,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",
@@ -7308,7 +7336,7 @@
           "description": "Assign a name and optional tags to a new object. By default, names are stored LOCALLY (private) on your device. Set 'onChain: true' to create a PUBLIC on-chain identity visible to everyone. IMPORTANT: If the requested name is already taken, the operation will FAIL by default. Only set 'replaceExistName: true' when the user EXPLICITLY demands to forcefully claim the name."
         }
       ],
-      "description": "Name and optional tags for the new Guard object. Set 'onChain: true' to create a public on-chain identity. When using root.type='file', this field OVERRIDES namedNew in the file."
+      "description": "Name and optional tags for the new Guard object. Set 'onChain: true' to create a public on-chain identity. When using root.type='file', this field OVERRIDES namedNew in the file. CIRCULAR DEPENDENCY (DOC-01): When a Guard queries a Service that hasn't been created yet, use a LocalMark NAME (not address) in the query table — the name is resolved to an address at transaction build time. Workflow: (1) Create Service (Phase 1, no publish) → (2) Create Guard referencing Service by name → (3) Update Service.buy_guard = Guard address → (4) Publish Service."
     },
     "guard_description": {
       "anyOf": [
@@ -7630,7 +7658,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": [
@@ -7723,12 +7751,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."
               }
             },
             "required": [
@@ -7737,7 +7765,7 @@
               "value_type"
             ],
             "additionalProperties": false,
-            "description": "Guard table item"
+            "description": "Guard table item (INPUT/CREATION form). DO NOT include `object_type` field — it is query-output only and will be rejected here."
           }
         }
       ],
@@ -8406,14 +8434,14 @@
                       "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/data_personal/properties/referrer/anyOf/1/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"
                           },
                           {
                             "$ref": "#/definitions/data_personal/properties/referrer/anyOf/1"
                           }
                         ],
-                        "description": "Account or address lookup. Can be a simple string (recommended for AI) or full object with explicit local_mark_first control"
+                        "description": "Account or address lookup. Can be a simple string (recommended for AI) or full object with explicit local_mark_first control. String form auto-converts to { name_or_address: <string>, local_mark_first: true }."
                       },
                       "name": {
                         "$ref": "#/definitions/data_personal/properties/information/anyOf/1/properties/name/items"
@@ -8487,15 +8515,15 @@
                     {
                       "type": "array",
                       "items": {
-                        "type": "string"
+                        "$ref": "#/definitions/data_personal/properties/referrer/anyOf/1/properties/name_or_address"
                       },
-                      "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry"
+                      "description": "Array of account names, addresses, or mark names. Local marks are searched first for each entry. EXAMPLE: ['alice', '0x2...', 'bob']"
                     },
                     {
                       "$ref": "#/definitions/data_personal/properties/information/anyOf/0/properties/data/items/properties/value/anyOf/0/anyOf/5/anyOf/0"
                     }
                   ],
-                  "description": "Batch account or address lookup. Can be an array of strings (recommended for AI) or full object with explicit control"
+                  "description": "Batch account or address lookup. Can be an array of strings (recommended for AI) or full object with explicit control. Array form auto-converts to { entities: [...], check_all_founded: true }."
                 }
               },
               "required": [
@@ -8563,148 +8591,178 @@
       "additionalProperties": false
     },
     "data_payment": {
-      "type": "object",
-      "properties": {
-        "object": {
+      "anyOf": [
+        {
           "type": "object",
           "properties": {
-            "name": {
-              "type": "string",
-              "description": "The name of the object"
+            "object": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "description": "The name of the object"
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "The tags of the object"
+                },
+                "onChain": {
+                  "type": "boolean",
+                  "description": "CRITICAL: Whether to sync the name to the blockchain. DEFAULT (undefined/false): The name is stored LOCALLY ONLY on your device (PRIVATE). If set to true: The name is published ON-CHAIN and becomes PUBLICLY VISIBLE to everyone. Only set to true for displaying the relationships you are willing to make public on the chain."
+                },
+                "replaceExistName": {
+                  "type": "boolean",
+                  "description": "FORCE CLAIM: Set to true ONLY when the user explicitly expresses a STRONG INTENTION to forcefully take over an existing name (e.g., 'I must use this name', 'force rename', 'replace the existing one'). WARNING: This will UNBIND the name from its original object and rebind it to the new one, potentially breaking existing references. If not specified or false: the operation will FAIL with an error when the name is already in use (safe default behavior)."
+                },
+                "type_parameter": {
+                  "type": "string",
+                  "description": "Payment token type for this object (format: {address}::{module}::{struct}). e.g. '0x2::wow::WOW' (WOW, the default), '0x...::usdt::USDT' (USDT), '0x...::eth::ETH' (ETH). Defines which token this object accepts for payments. To discover all available tokens and their type tags, call wowok_buildin_info with info 'mainnet bridge tokens' and use the returned `wowTypeTag` value here.",
+                  "default": "0x2::wow::WOW"
+                }
+              },
+              "additionalProperties": false,
+              "description": "Create a new named object (with optional tags) and specify a token type for payments (e.g., WOW, USDT, ETH)."
             },
-            "tags": {
+            "revenue": {
               "type": "array",
               "items": {
-                "type": "string"
-              },
-              "description": "The tags of the object"
-            },
-            "onChain": {
-              "type": "boolean",
-              "description": "CRITICAL: Whether to sync the name to the blockchain. DEFAULT (undefined/false): The name is stored LOCALLY ONLY on your device (PRIVATE). If set to true: The name is published ON-CHAIN and becomes PUBLICLY VISIBLE to everyone. Only set to true for displaying the relationships you are willing to make public on the chain."
-            },
-            "replaceExistName": {
-              "type": "boolean",
-              "description": "FORCE CLAIM: Set to true ONLY when the user explicitly expresses a STRONG INTENTION to forcefully take over an existing name (e.g., 'I must use this name', 'force rename', 'replace the existing one'). WARNING: This will UNBIND the name from its original object and rebind it to the new one, potentially breaking existing references. If not specified or false: the operation will FAIL with an error when the name is already in use (safe default behavior)."
-            },
-            "type_parameter": {
-              "type": "string",
-              "description": "Payment token type for this object (format: {address}::{module}::{struct}). e.g. '0x2::wow::WOW' (WOW, the default), '0x...::usdt::USDT' (USDT), '0x...::eth::ETH' (ETH). Defines which token this object accepts for payments. To discover all available tokens and their type tags, call wowok_buildin_info with info 'mainnet bridge tokens' and use the returned `wowTypeTag` value here.",
-              "default": "0x2::wow::WOW"
-            }
-          },
-          "additionalProperties": false,
-          "description": "Create a new named object (with optional tags) and specify a token type for payments (e.g., WOW, USDT, ETH)."
-        },
-        "revenue": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "recipient": {
                 "type": "object",
                 "properties": {
-                  "name_or_address": {
-                    "type": "string",
-                    "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
-                  },
-                  "local_mark_first": {
-                    "type": "boolean",
-                    "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks"
-                  }
-                },
-                "additionalProperties": false,
-                "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account."
-              },
-              "amount": {
-                "anyOf": [
-                  {
+                  "recipient": {
                     "type": "object",
                     "properties": {
-                      "balance": {
-                        "type": [
-                          "number",
-                          "string"
-                        ],
-                        "description": "Balance type"
+                      "name_or_address": {
+                        "type": "string",
+                        "description": "Account/Object name or ID. If specifying an account, use empty string '' for the default account. If it starts with '0x', it will be treated as an ID. Otherwise, it will be treated as a name (max 64 bcs characters)."
+                      },
+                      "local_mark_first": {
+                        "type": "boolean",
+                        "description": "Whether to prioritize local marks, if true, prioritize local marks, otherwise prioritize global marks"
                       }
                     },
-                    "required": [
-                      "balance"
-                    ],
                     "additionalProperties": false,
-                    "description": "Specify an amount value."
+                    "description": "Account or address lookup object. Use this to specify which account to use for an operation. EXAMPLE: { name_or_address: 'testor2' } - looks up account by name; EXAMPLE: { name_or_address: '0x1234...' } - uses address directly; If name_or_address is empty string '', uses the default local account."
                   },
-                  {
-                    "type": "object",
-                    "properties": {
-                      "coin": {
-                        "type": "string",
-                        "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                  "amount": {
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "balance": {
+                            "type": [
+                              "number",
+                              "string"
+                            ],
+                            "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": [
+                          "balance"
+                        ],
+                        "additionalProperties": false,
+                        "description": "Specify an amount value."
+                      },
+                      {
+                        "type": "object",
+                        "properties": {
+                          "coin": {
+                            "type": "string",
+                            "description": "Coin object ID or name(local mark). Use a specified Coin object."
+                          }
+                        },
+                        "required": [
+                          "coin"
+                        ],
+                        "additionalProperties": false
                       }
-                    },
-                    "required": [
-                      "coin"
                     ],
-                    "additionalProperties": false
+                    "description": "Specify the amount to pay from the transaction account, or the Coin ID owned by the transaction account. Used for payment."
                   }
+                },
+                "required": [
+                  "recipient",
+                  "amount"
                 ],
-                "description": "Specify the amount to pay from the transaction account, or the Coin ID owned by the transaction account. Used for payment."
-              }
+                "additionalProperties": false,
+                "description": "Payment recipient and amount"
+              },
+              "description": "Array of payment recipients and amounts"
             },
-            "required": [
-              "recipient",
-              "amount"
-            ],
-            "additionalProperties": false,
-            "description": "Payment recipient and amount"
+            "info": {
+              "type": "object",
+              "properties": {
+                "for_object": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Payment for a specific object ID"
+                },
+                "for_guard": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Payment to satisfy verification of a Guard object"
+                },
+                "remark": {
+                  "type": "string",
+                  "description": "Payment record remark"
+                },
+                "index": {
+                  "type": [
+                    "number",
+                    "string"
+                  ],
+                  "description": "Payment record index"
+                }
+              },
+              "required": [
+                "remark",
+                "index"
+              ],
+              "additionalProperties": false,
+              "description": "Payment information"
+            }
           },
-          "description": "Array of payment recipients and amounts"
+          "required": [
+            "object",
+            "revenue",
+            "info"
+          ],
+          "additionalProperties": false,
+          "description": "Create a new Payment. USAGE: Set 'object' field with {name, type, ...} to create a named Payment. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. Payment is an immutable object - it can only be created, not modified. The 'object' field is CRITICAL and REQUIRED."
         },
-        "info": {
+        {
           "type": "object",
           "properties": {
-            "for_object": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "description": "Payment for a specific object ID"
+            "object": {
+              "$ref": "#/definitions/data_payment/anyOf/0/properties/revenue/items/properties/recipient/properties/name_or_address",
+              "description": "CoinWrapper object ID (0x...) or local name to unwrap. Find received CoinWrappers via query_toolkit with query_type='onchain_received'."
             },
-            "for_guard": {
-              "type": [
-                "string",
-                "null"
-              ],
-              "description": "Payment to satisfy verification of a Guard object"
+            "receive": {
+              "type": "boolean",
+              "const": true,
+              "description": "Set to true to activate receive mode. CoinWrapper objects ARE transferred to recipients via transfer::public_transfer (they arrive as owned objects), but they are NOT spendable coins. This mode unwraps a CoinWrapper into actual coins in your wallet via payment::unwrap_to_myself. The caller must be the CoinWrapper's owner (the recipient specified in the Allocation's revenue split)."
             },
-            "remark": {
+            "type_parameter": {
               "type": "string",
-              "description": "Payment record remark"
-            },
-            "index": {
-              "type": [
-                "number",
-                "string"
-              ],
-              "description": "Payment record index"
+              "description": "Coin type of the CoinWrapper, e.g. '0x2::wow::WOW'. Must match the type used when the Allocation created the Payment."
             }
           },
           "required": [
-            "remark",
-            "index"
+            "object",
+            "receive",
+            "type_parameter"
           ],
           "additionalProperties": false,
-          "description": "Payment information"
+          "description": "Receive mode: unwrap a CoinWrapper to the caller's wallet. Use after Allocation's alloc_by_guard creates a Payment with your address as a revenue recipient. The CoinWrapper holds your share — call this to convert it to actual coins in your wallet."
         }
-      },
-      "required": [
-        "object",
-        "revenue",
-        "info"
       ],
-      "additionalProperties": false,
-      "description": "On-chain Payment creation. USAGE: Set 'object' field with {name, type, ...} to create a named Payment. NOTE: 'name' goes INSIDE 'object', NOT at the data root level. Payment is an immutable object - it can only be created, not modified. The 'object' field is CRITICAL and REQUIRED."
+      "description": "On-chain Payment operations. TWO modes:\n(1) CREATE: Set 'object' with {name, type_parameter, ...}, 'revenue', and 'info' to create a new Payment.\n(2) RECEIVE: Set {object: '<coinwrapper_id_or_name>', receive: true, type_parameter: '0x2::wow::WOW'} to unwrap a CoinWrapper to your wallet.\nThe 'object' field is CRITICAL and REQUIRED in both modes. STRING for receive (CoinWrapper ID/name), OBJECT for create."
     },
     "data_demand": {
       "type": "object",
@@ -9050,7 +9108,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",
@@ -9197,7 +9255,7 @@
                 "unhold",
                 "adminUnhold"
               ],
-              "description": "Operation type on the forward: 'next' = advance the forward (accomplish); 'hold' = set hold to block the forward; 'unhold' = self-unhold, release own hold (no 224 permission needed); 'adminUnhold' = force-release hold via 224 permission (PROGRESS_UNHOLD)."
+              "description": "Operation type on the forward (CANONICAL form — prefer this): 'next' = advance the forward (accomplish); 'hold' = set hold to block the forward; 'unhold' = self-unhold, release own hold (no 224 permission needed); 'adminUnhold' = force-release hold via 224 permission (PROGRESS_UNHOLD). LEGACY ALIAS: `hold: boolean` is auto-converted to `op` — `hold:true`→`op:'hold'`, `hold:false`→`op:'next'`. New code should use `op` directly."
             },
             "message": {
               "type": "string",
@@ -9275,96 +9333,90 @@
           "description": "Specify the adjudicated Arb object to obtain order compensation."
         },
         "receive": {
-          "type": "object",
-          "properties": {
-            "result": {
-              "anyOf": [
-                {
-                  "type": "object",
-                  "properties": {
-                    "balance": {
-                      "type": [
-                        "number",
-                        "string"
-                      ],
-                      "description": "Balance type"
-                    },
-                    "token_type": {
-                      "type": "string",
-                      "description": "Asset type of Coin objects. Supports CoinWrapper<...> format for order receive operations."
-                    },
-                    "received": {
-                      "type": "array",
-                      "items": {
-                        "type": "object",
-                        "properties": {
-                          "id": {
-                            "type": "string",
-                            "description": "Received CoinWrapper object ID"
-                          },
-                          "balance": {
-                            "$ref": "#/definitions/data_order/properties/receive/properties/result/anyOf/0/properties/balance"
-                          },
-                          "payment": {
-                            "type": "string",
-                            "description": "Payment object ID"
-                          }
-                        },
-                        "required": [
-                          "id",
-                          "balance",
-                          "payment"
-                        ],
-                        "additionalProperties": false,
-                        "description": "Received CoinWrapper object record"
-                      },
-                      "description": "Received records of Coin objects"
-                    }
+          "anyOf": [
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Received object ID"
                   },
-                  "required": [
-                    "balance",
-                    "token_type",
-                    "received"
+                  "type": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Object type"
+                  },
+                  "content_raw": {
+                    "description": "Raw content data"
+                  }
+                },
+                "required": [
+                  "id",
+                  "type"
+                ],
+                "additionalProperties": false,
+                "description": "Received normal object record"
+              }
+            },
+            {
+              "type": "object",
+              "properties": {
+                "balance": {
+                  "type": [
+                    "number",
+                    "string"
                   ],
-                  "additionalProperties": false,
-                  "description": "Received record of Coin objects"
+                  "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",
+                  "description": "Asset type of Coin objects. Supports CoinWrapper<...> format for order receive operations."
+                },
+                "received": {
                   "type": "array",
                   "items": {
                     "type": "object",
                     "properties": {
                       "id": {
                         "type": "string",
-                        "minLength": 1,
-                        "description": "Received object ID"
+                        "description": "Received CoinWrapper object ID"
                       },
-                      "type": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Object type"
+                      "balance": {
+                        "$ref": "#/definitions/data_order/properties/receive/anyOf/1/properties/balance"
                       },
-                      "content_raw": {
-                        "description": "Raw content data"
+                      "payment": {
+                        "type": "string",
+                        "description": "Payment object ID"
                       }
                     },
                     "required": [
                       "id",
-                      "type"
+                      "balance",
+                      "payment"
                     ],
                     "additionalProperties": false,
-                    "description": "Received normal object record"
-                  }
+                    "description": "Received CoinWrapper object record"
+                  },
+                  "description": "Received records of Coin objects"
                 }
+              },
+              "required": [
+                "balance",
+                "token_type",
+                "received"
               ],
-              "description": "Received CoinWrapper object record or received other objects array"
+              "additionalProperties": false,
+              "description": "Received record of Coin objects"
+            },
+            {
+              "type": "string",
+              "const": "recently"
             }
-          },
-          "required": [
-            "result"
           ],
-          "additionalProperties": false,
-          "description": "Unwrap CoinWrapper objects or other objects received by the order and transfer them to the order owner"
+          "description": "Unwrap CoinWrapper objects or other objects received by the order and transfer them to the order owner. ACCEPTED FORMATS (consistent with `owner_receive` on other objects — see arbitration/contact/demand/machine/permission/repository/reward/service/treasury):\n• 'recently' (string) — auto-query and receive all recently received objects\n• ReceivedNormal[] (array) — explicit list of received objects: [{id, type, content_raw?}]\n• ReceivedBalance ({token_type, balance, received: [{id, balance, payment}]}) — received balance record\nDO NOT wrap in {result: ...} — pass directly (NOT {result: [...]})"
         },
         "transfer_to": {
           "$ref": "#/definitions/data_order/properties/agent/properties/entities/items",
@@ -9738,7 +9790,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": [
@@ -9831,12 +9883,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",
@@ -9874,7 +9926,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": [
@@ -9883,7 +9935,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...'}]"
                   }
@@ -9895,7 +9947,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": [
@@ -9932,7 +9984,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/data_gen_passport/properties/guard/anyOf/0",
@@ -10163,7 +10215,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/data_gen_proof/properties/env/properties/account",