@wowok/agent-mcp 2.5.5 → 2.6.1

package/dist/schemas/project_operation.schema.json

@@ -28,9 +28,15 @@
             "refresh_objects",
             "get_object_diff",
             "delete_project",
-            "assemble_context"
+            "assemble_context",
+            "get_machine_graph",
+            "generate_deployment_doc",
+            "pre_evaluate_check",
+            "verify_deployment",
+            "clone_project_to_network",
+            "migrate_network"
           ],
-          "description": "Action to perform. Two categories:\n1. Project Entity + Evaluation (15, GLM6): list_projects, create_project, create_project_from_onchain, update_project, get_project_detail, add_object, remove_object, create_version, build_graph, get_graph, evaluate_project, save_evaluation, compare_projects, refresh_objects, get_object_diff. Projects are first-class entities with SQLite persistence, rigid project-object relationships, three-pathway graph construction, and a dual rule-based + LLM-assisted evaluation engine.\n2. Context Assembly (1): assemble_context (query on-chain object states + extract embedded history + optional events, and assemble a structured semantic context for LLM consumption). Required input: context_objects (array of object IDs/names). Optional: include_events (query recent state-transition events)."
+          "description": "Action to perform. Two categories:\n1. Project Entity + Evaluation (15, GLM6): list_projects, create_project, create_project_from_onchain, update_project, get_project_detail, add_object, remove_object, create_version, build_graph, get_graph, evaluate_project, save_evaluation, compare_projects, refresh_objects, get_object_diff. Projects are first-class entities with SQLite persistence, rigid project-object relationships, three-pathway graph construction, and a dual rule-based + LLM-assisted evaluation engine.\n2. Context Assembly (1): assemble_context (query on-chain object states + extract embedded history + optional events, and assemble a structured semantic context for LLM consumption). Required input: context_objects (array of object IDs/names). Optional: include_events (query recent state-transition events).\n3. Cross-Network Migration (FIX-012): clone_project_to_network (or its alias migrate_network) copies a source project's object metadata to a new project bound to target_network. The 5-step migration workflow: 1) call clone_project_to_network (or migrate_network) with target_network to copy metadata, 2) re-run onchain_operations with env.network=target_network to deploy objects on-chain, 3) re-register LocalMark names with the SAME names on the target network (FIX-011 cross-network consistency), 4) update_project to set service_address on the new project, 5) build_graph to construct the new project's relationship graph."
         },
         "project": {
           "type": "string",
@@ -111,7 +117,7 @@
             "subscription",
             "custom"
           ],
-          "description": "Industry tag for create_project. Drives template defaults."
+          "description": "Industry tag for create_project. Drives template defaults — when set (and not 'general'), the system auto-applies an industry blueprint with ~10 draft objects (Permission, Service, Machine, Guard, Treasury, Allocation, etc.) + graph edges, ready for deployment. Supported industries: 'general' (no template), 'retail', 'service', 'rental', 'freelance', 'education', 'travel', 'subscription', 'custom'. Each industry preset embeds risk constraints (e.g., 'freelance' does NOT require compensation_fund, while 'rental'/'travel' do). Example: project_industry='freelance' creates a freelance-style blueprint with setting_locked_time ≥ 7d. Set skip_templates=true to bypass template application."
         },
         "project_perspective": {
           "type": "string",
@@ -141,6 +147,10 @@
           ],
           "description": "Network the project is bound to. A Service deployed to different networks are different projects. Defaults to 'testnet'."
         },
+        "skip_templates": {
+          "type": "boolean",
+          "description": "When true, create_project skips applying the industry template (no draft:* blueprint objects). Use this when you want a clean project with no pre-filled blueprint objects — useful for custom architectures that do not match any industry mode, or to avoid draft objects appearing in build_graph / evaluate_project before deployment. Defaults to false (templates applied)."
+        },
         "project_id": {
           "type": "string",
           "description": "Project UUID for update_project / get_project_detail / add_object / remove_object / create_version / build_graph / evaluate_project / refresh_objects. Takes precedence over 'project' (prefix) when both are given."
@@ -155,9 +165,17 @@
           ],
           "description": "New status for update_project. 'active' projects are live, 'archived' are read-only."
         },
+        "target_network": {
+          "type": "string",
+          "enum": [
+            "testnet",
+            "mainnet"
+          ],
+          "description": "Target network for clone_project_to_network (or its alias migrate_network). The source project's objects are copied to a new project bound to this network. The new project's prefix is '<source_prefix>_<target_network>' to avoid collision. See the action description for the full 5-step migration workflow (FIX-012)."
+        },
         "object_address": {
           "type": "string",
-          "description": "On-chain object address (0x...) for add_object / remove_object. For add_object, alternatively use object_name to resolve via LocalMark."
+          "description": "On-chain object address (0x followed by 32-64 hex chars) for add_object / remove_object. Also accepts the internal 'draft:<name>' sentinel used by create_project for blueprint objects not yet on-chain. For add_object, alternatively use object_name_add to resolve via LocalMark. H-06 fix: invalid formats are rejected at the handler level with a descriptive error."
         },
         "object_name_add": {
           "type": "string",
@@ -248,6 +266,12 @@
           "maximum": 5,
           "description": "Max recursion depth for Pathway 1 (internal reference derivation) in build_graph. Default 3."
         },
+        "depth": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5,
+          "description": "Alias for max_depth (build_graph). When both are set, max_depth takes precedence. Default 3."
+        },
         "enable_registrar": {
           "type": "boolean",
           "description": "Enable Pathway 2 (Registrar inbound query) in build_graph. Default true."
@@ -256,6 +280,10 @@
           "type": "boolean",
           "description": "Enable Pathway 3 (potential relationship detection) in build_graph. Default false."
         },
+        "async_mode": {
+          "type": "boolean",
+          "description": "When true, build_graph / evaluate_project runs in the background and returns { task_id } immediately. Poll query_task_status(task_id) to check progress and retrieve the result. Default false (synchronous). Use async_mode=true for large projects with enable_potential=true where build may take >10s."
+        },
         "evaluation_type": {
           "type": "string",
           "enum": [
@@ -306,6 +334,27 @@
         "diff_to_time": {
           "type": "integer",
           "description": "End timestamp (ms) for get_object_diff."
+        },
+        "network": {
+          "type": "string",
+          "enum": [
+            "testnet",
+            "mainnet"
+          ],
+          "description": "Target network for generate_deployment_doc. Required when action='generate_deployment_doc'."
+        },
+        "save": {
+          "type": "boolean",
+          "description": "When true (default), persist the generated MD to SQLite project_documents table for generate_deployment_doc."
+        },
+        "detail_level": {
+          "type": "string",
+          "enum": [
+            "summary",
+            "detailed",
+            "full"
+          ],
+          "description": "P2-03: Deployment document detail level (only for generate_deployment_doc). 'summary' (default): object name + type + key bindings (machine, permission, buy_guard, order_allocators). 'detailed': adds sale list, arbitration list, reward list. 'full': complete fields including stock, price, wip_hash, all config. Use 'summary' for quick review; request 'detailed' or 'full' only when deeper inspection is needed."
         }
       },
       "required": [

package/dist/schemas/query_toolkit.output.json

@@ -535,7 +535,7 @@
           "address"
         ],
         "additionalProperties": false,
-        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain."
+        "description": "LOCAL PRIVATE: Local mark data structure for storing address names and tags privately on your device. This data is NEVER published to the blockchain. CROSS-NETWORK ISOLATION (DOC-02): LocalMark names are scoped per network — the same name 'my-service' can map to different addresses on testnet vs mainnet. When switching networks (e.g., testnet→mainnet deployment), re-create marks with the same names pointing to the new mainnet addresses. This enables name-based object references that work identically across networks without code changes."
       },
       "description": "Local mark list"
     },
@@ -572,12 +572,13 @@
             "type": "number",
             "description": "Timestamp when account was last updated"
           },
-          "m": {
-            "type": [
-              "string",
-              "null"
-            ],
-            "description": "Messenger name, indicates this account has messenger enabled"
+          "messenger": {
+            "type": "boolean",
+            "description": "Whether messenger is enabled for this account"
+          },
+          "suspendedName": {
+            "type": "string",
+            "description": "Name before suspension (set by suspend, cleared by resume)"
           }
         },
         "required": [
@@ -2647,11 +2648,11 @@
               },
               "wip": {
                 "type": "string",
-                "description": "HTTP URL of wip file"
+                "description": "WIP file URL. EMPTY string \"\" skips verification (TESTING ONLY). Production MUST use a real HTTP URL pointing to a .wip file generated by the wip_file tool. Example: \"https://cdn.example.com/products/phone_v1.wip\""
               },
               "wip_hash": {
                 "type": "string",
-                "description": "Hash of WIP. If EMPTY string, the hash within wip will be automatically used; else, the consistency of the hash within wip will be verified with the provided hash."
+                "description": "WIP file hash (hex string). EMPTY string \"\" skips hash comparison (TESTING ONLY). Production: fill with the hash you saw when viewing the product, to prevent merchant replacing the WIP file before order."
               }
             },
             "required": [
@@ -2715,7 +2716,7 @@
             "number",
             "string"
           ],
-          "description": "Compensation fund pool for arbitration results. Order users can receive compensation from this fund based on arbitration results."
+          "description": "Compensation fund BALANCE (NOT a Treasury address). This field reports the total amount of funds currently held in the Service's compensation pool. To ADD funds, use `service.compensation_fund_add`. To RECEIVE funds (as order owner after arbitration), use `service.compensation_fund_receive`. P2-03 clarification: this is a balance value (e.g. {balance: '1000000000', token_type: '0x2::wow::WOW'}), NOT the Treasury object address. The Treasury address (if bound) is queried separately via the Service's `repositories` or `order_allocators` configuration."
         },
         "paused_time": {
           "type": [
@@ -2746,7 +2747,7 @@
                     "number",
                     "string"
                   ],
-                  "description": "Threshold. If defined, fund allocation will be triggered when amount in Allocation object reaches this threshold.",
+                  "description": "Minimum balance required for allocation to fire. When the Allocation object's balance < threshold, allocation aborts with EINSUFFICIENT_BALANCE=7. Also: when an Allocator has only Amount items (no Rate, no Surplus), the sum of Amount items must be >= threshold (EAMOUNT_BELOW_THRESHOLD=12). Set to 0 (default) to allow any balance.",
                   "default": 0
                 },
                 "allocators": {
@@ -2756,7 +2757,7 @@
                     "properties": {
                       "guard": {
                         "type": "string",
-                        "description": "Guard object ID. If Guard verification passes, fund allocation will start automatically."
+                        "description": "Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."
                       },
                       "sharing": {
                         "type": "array",
@@ -2804,7 +2805,7 @@
                                     "Entity"
                                   ],
                                   "additionalProperties": false,
-                                  "description": "Determined ID"
+                                  "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                                 },
                                 {
                                   "type": "object",
@@ -2821,23 +2822,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": [
@@ -2846,13 +2856,13 @@
                             "mode"
                           ],
                           "additionalProperties": false,
-                          "description": "Fund allocation item"
+                          "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last."
                         },
-                        "description": "Fund allocation item list. Each item represents a recipient and their corresponding reward allocation value."
+                        "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate + Surplus) within the same Allocator. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
                       },
                       "fix": {
                         "$ref": "#/definitions/object_service/properties/order_allocators/anyOf/0/properties/threshold",
-                        "description": "Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."
+                        "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract during `allocator_add` — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation."
                       },
                       "max": {
                         "anyOf": [
@@ -2863,7 +2873,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": [
@@ -2871,9 +2881,9 @@
                       "sharing"
                     ],
                     "additionalProperties": false,
-                    "description": "Fund allocator"
+                    "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus."
                   },
-                  "description": "Fund allocator list. Each fund allocator represents a fund allocation strategy."
+                  "description": "Fund allocator list. Each allocator is evaluated in order; the FIRST allocator whose Guard passes wins. This enables mutually exclusive allocation paths (e.g., 3 allocators for 3 forward paths: refund / damage-deduct / arbitrate)."
                 }
               },
               "required": [
@@ -2881,7 +2891,7 @@
                 "allocators"
               ],
               "additionalProperties": false,
-              "description": "Fund allocator list"
+              "description": "Fund allocator list — the top-level allocation configuration attached to an Order. Contains a threshold and a list of Allocators. When funds arrive at the Order, the first Allocator whose Guard passes executes its sharing[] in strict order: Amount → Rate → Surplus. MULTI-TIER ALLOCATION (DOC-04): Each Order binds ONE Allocators template (set on Service.order_allocators before publish). For multi-tier distribution (e.g., customer→agency→suppliers), use a two-phase approach: (1) Tier-1 Allocators on the customer's Order (allocates to agency + refund fund); (2) Tier-2 Allocators on a NEW Order created by the agency (allocates agency's received funds to suppliers). Each tier's Rate-mode sharing[] must independently sum to 10000 (or <= 10000 with Surplus)."
             },
             {
               "type": "null"
@@ -4878,7 +4888,7 @@
             "properties": {
               "guard": {
                 "type": "string",
-                "description": "Guard object ID. If Guard verification passes, fund allocation will start automatically."
+                "description": "Guard object ID or name. If Guard verification passes (via Passport), fund allocation for THIS Allocator fires. Each Allocator in an Allocators list can have a different Guard — the first Allocator whose Guard returns true wins. This enables mutually exclusive allocation paths (e.g., refund Guard on 'return_approved' node vs damage Guard on 'damage_confirmed' node)."
               },
               "sharing": {
                 "type": "array",
@@ -4926,7 +4936,7 @@
                             "Entity"
                           ],
                           "additionalProperties": false,
-                          "description": "Determined ID"
+                          "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                         },
                         {
                           "type": "object",
@@ -4943,23 +4953,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": [
@@ -4968,16 +4987,16 @@
                     "mode"
                   ],
                   "additionalProperties": false,
-                  "description": "Fund allocation item"
+                  "description": "Fund allocation item — one recipient's share of the Allocation balance. The `sharing` value's meaning depends on `mode` (see AllocationModeSchema). Multiple items in the same Allocator are evaluated together: Amount items first, Rate items second, Surplus last."
                 },
-                "description": "Fund allocation item list. Each item represents a recipient and their corresponding reward allocation value."
+                "description": "Fund allocation item list. Each item specifies a recipient (who), a value (sharing), and a mode. Items can mix modes (Amount + Rate + Surplus) within the same Allocator. ALLOCATION ORDER: Amount items first (cached as fix) → Rate items (proportional to balance - fix) → Surplus item (remaining). CONSTRAINTS: max ONE Surplus item per Allocator; Rate sum must == 10000 (no Surplus) or <= 10000 (with Surplus); Amount sum must >= threshold (no Rate and no Surplus) and <= max (if max set)."
               },
               "fix": {
                 "type": [
                   "number",
                   "string"
                 ],
-                "description": "Fixed allocation amount. If specified, all recipients will receive the fixed allocation amount."
+                "description": "OUTPUT-ONLY (query result). Cached sum of all Amount-mode `sharing` values in this Allocator. Computed by the contract during `allocator_add` — DO NOT set this field at creation. Used internally to compute `total_rates = balance - fix` for Rate allocation."
               },
               "max": {
                 "anyOf": [
@@ -4988,7 +5007,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": [
@@ -4996,7 +5015,7 @@
               "sharing"
             ],
             "additionalProperties": false,
-            "description": "Fund allocator"
+            "description": "Fund allocator — a complete allocation strategy triggered by a Guard. Contains a sharing[] array where items can mix Amount/Rate/Surplus modes. When the Guard passes, the contract allocates funds in strict order: Amount → Rate → Surplus."
           },
           "description": "Fund allocation object allocator list"
         },
@@ -5314,7 +5333,7 @@
                       "Entity"
                     ],
                     "additionalProperties": false,
-                    "description": "Determined ID"
+                    "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                   },
                   {
                     "type": "object",
@@ -5331,7 +5350,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": [
@@ -5365,7 +5384,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": [
@@ -6351,7 +6370,7 @@
                       "Entity"
                     ],
                     "additionalProperties": false,
-                    "description": "Determined ID"
+                    "description": "Static address resolved via LocalMark. Format: {Entity: {name_or_address: 'mark_name'}} — NOTE: Entity is an OBJECT with name_or_address field, NOT a bare string."
                   },
                   {
                     "type": "object",
@@ -6368,14 +6387,14 @@
                     "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": {
                 "type": [
                   "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": [
@@ -8405,14 +8424,16 @@
         "discount_type": {
           "anyOf": [
             {
-              "type": "number",
-              "const": 0,
-              "description": "Rate discount type"
+              "type": "string",
+              "enum": [
+                "RATES",
+                "FIXED"
+              ]
             },
             {
-              "type": "number",
-              "const": 1,
-              "description": "Fixed discount type"
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 1
             }
           ],
           "description": "Discount type. If rate(0), discount is based on proportion of product amount (e.g., 1000 means 10% discount); if fixed(1), discount is based on fixed value of product amount (e.g., 100 means 100 yuan discount)."
@@ -8424,7 +8445,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."
             },
             {
               "type": "null"
@@ -13012,7 +13033,7 @@
                 "properties": {
                   "prev_node": {
                     "type": "string",
-                    "description": "Previous node name"
+                    "description": "Previous node name. Empty string '' means initial entry node (the first node in the workflow)."
                   },
                   "threshold": {
                     "type": [
@@ -13072,38 +13093,46 @@
                         "guard": {
                           "anyOf": [
                             {
-                              "type": "object",
-                              "properties": {
-                                "guard": {
-                                  "type": "string",
-                                  "description": "Guard object ID"
-                                },
-                                "retained_submission": {
-                                  "anyOf": [
-                                    {
-                                      "type": "array",
-                                      "items": {
-                                        "$ref": "#/definitions/query_result_onchain_table_item_machine_node/anyOf/0/properties/value/items/properties/threshold"
-                                      }
+                              "anyOf": [
+                                {
+                                  "type": "object",
+                                  "properties": {
+                                    "guard": {
+                                      "type": "string",
+                                      "description": "Guard object name or address (string). Example: 'my_attendance_guard' or '0x1234...'"
                                     },
-                                    {
-                                      "type": "null"
+                                    "retained_submission": {
+                                      "anyOf": [
+                                        {
+                                          "type": "array",
+                                          "items": {
+                                            "$ref": "#/definitions/query_result_onchain_table_item_machine_node/anyOf/0/properties/value/items/properties/threshold"
+                                          }
+                                        },
+                                        {
+                                          "type": "null"
+                                        }
+                                      ],
+                                      "description": "Data submitted by user during Guard object verification"
                                     }
+                                  },
+                                  "required": [
+                                    "guard"
                                   ],
-                                  "description": "Data submitted by user during Guard object verification"
+                                  "additionalProperties": false,
+                                  "description": "OBJECT form: {guard: '<guard_name_or_address>', retained_submission?: number[]}. Use this form when you need to pass retained_submission data alongside the Guard reference."
+                                },
+                                {
+                                  "type": "string",
+                                  "description": "STRING form (shorthand): the Guard object's name or address as a plain string. Auto-wrapped to {guard: <string>} at runtime. Use this when you only need to reference a Guard without retained_submission."
                                 }
-                              },
-                              "required": [
-                                "guard"
-                              ],
-                              "additionalProperties": false,
-                              "description": "Record of Guard object in MachineForwardGuard object"
+                              ]
                             },
                             {
                               "type": "null"
                             }
                           ],
-                          "description": "Guard object ID, if defined, Guard verification must also pass to complete Forward (e.g., completed promised supply chain sub-order)."
+                          "description": "Guard reference for this forward. Accepts TWO formats:\n• STRING (preferred): \"my_guard_name\" — the Guard's name or address as a plain string.\n• OBJECT (only when retained_submission is needed): {guard: \"my_guard_name\", retained_submission: [1,2,3]}.\nFOLLOW THE SCHEMA FIELD STRUCTURE: A Guard reference is fundamentally a STRING (the Guard object's name or address). Provide a string when you only need to reference a Guard — do NOT wrap a bare string in an object structure. The OBJECT form {guard: \"...\", retained_submission: [...]} exists ONLY to carry additional `retained_submission` data alongside the string reference; inside the object, the `guard` field is STILL a string. In short: string-in for a string reference, object-in only when you need to pass extra data.\nCOGNITIVE PRINCIPLE: Guard validation ALWAYS occurs BEFORE the forward operation. A Guard that queries state of the SAME Progress object this forward operates on (e.g. progress.current) will see the PRE-transition value (source node), NOT the target node. If the Guard checks progress.current == target_node, it will ALWAYS FAIL. Querying a DIFFERENT Progress object (cross-machine) is safe and reasonable — that progress is not modified by this forward. For target-node verification after transition, bind the Guard to the Allocator instead (allocation.alloc runs AFTER the state transition completes)."
                         }
                       },
                       "required": [
@@ -13113,7 +13142,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": [
@@ -14172,7 +14201,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",