@wowok/agent-mcp 2.6.1 → 2.6.3

package/dist/schemas/project_operation.schema.json

@@ -30,17 +30,23 @@
             "delete_project",
             "assemble_context",
             "get_machine_graph",
+            "get_guard_graph",
             "generate_deployment_doc",
             "pre_evaluate_check",
             "verify_deployment",
             "clone_project_to_network",
-            "migrate_network"
+            "migrate_network",
+            "migrate_to_mainnet",
+            "plan_object_edit",
+            "apply_object_edit",
+            "patch_machine_nodes",
+            "patch_guard_tree"
           ],
           "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",
-          "description": "Project prefix (human-readable unique identifier). Used by create_version, build_graph, evaluate_project, etc. Takes precedence resolution: project_id > project (prefix)."
+          "description": "Project prefix (human-readable unique identifier). For create_project: OPTIONAL — if omitted, auto-derived from project_name (e.g. 'Twitch Service' → 'twitch_service'). For other actions (build_graph, evaluate_project, etc.): used to identify the project. Takes precedence resolution: project_id > project (prefix)."
         },
         "version": {
           "type": "string",
@@ -109,6 +115,7 @@
           "enum": [
             "general",
             "retail",
+            "retail_d2c",
             "service",
             "rental",
             "freelance",
@@ -117,7 +124,7 @@
             "subscription",
             "custom"
           ],
-          "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."
+          "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', 'retail_d2c' (Direct-to-Consumer, e.g., Shopify — Allocation escrow + 2 Guards), '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",
@@ -297,7 +304,7 @@
         },
         "refresh_before_eval": {
           "type": "boolean",
-          "description": "When true, evaluate_project refreshes object cache from chain before evaluating. Default false."
+          "description": "When true (DEFAULT), evaluate_project refreshes object cache from chain before evaluating. Set to false ONLY for read-only checks where staleness is acceptable (e.g., quick comparisons). BUG-P0-2 fix: previously defaulted to false, causing stale Machine node_count and other dynamic-field-derived fields to produce false findings (e.g., 'Machine has no nodes'). Now defaults to true — set refresh_before_eval=false explicitly to skip refresh."
         },
         "eval_score": {
           "type": "number",
@@ -355,6 +362,41 @@
             "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."
+        },
+        "object_kind": {
+          "type": "string",
+          "enum": [
+            "machine",
+            "guard"
+          ],
+          "description": "Object kind for plan_object_edit. 'machine' = Machine workflow directed graph (cycles allowed), 'guard' = Guard computation tree. Required when action='plan_object_edit'. Inferred from action for patch_machine_nodes (always 'machine') and patch_guard_tree (always 'guard')."
+        },
+        "edit_format": {
+          "type": "string",
+          "enum": [
+            "tree_outline",
+            "json"
+          ],
+          "description": "Format of the edited content for plan_object_edit. 'tree_outline' (default): the indented Markdown outline produced by get_machine_graph / get_guard_graph (human-editable). 'json': raw JSON (machine-readable, for programmatic edits). Both formats are bidirectional with the parse functions in knowledge/machine-render.ts / guard-render.ts."
+        },
+        "edited_content": {
+          "type": "string",
+          "description": "Edited content for plan_object_edit. Must be in the format specified by edit_format. For 'tree_outline': the full tree_outline string from get_machine_graph/get_guard_graph with user edits. For 'json': a JSON string matching the Machine/Guard schema. The content is parsed + validated + diffed against the current on-chain state."
+        },
+        "plan_id": {
+          "type": "string",
+          "description": "Plan ID returned by plan_object_edit. Required for apply_object_edit. The plan is short-lived (10-minute TTL) and stored in-memory."
+        },
+        "expected_hash": {
+          "type": "string",
+          "description": "Expected hash returned by plan_object_edit. Required for apply_object_edit. Used for optimistic concurrency control: if the on-chain state changed between plan and apply, the hash will mismatch and apply will refuse to proceed (stale edit protection)."
+        },
+        "patch_operations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Patch operations for patch_machine_nodes / patch_guard_tree. Each string is a single patch operation.\nMachine operations (13 total):\n  'add node <name>' | 'remove node <name>' | 'set description <node_name> <text...>'\n  'add edge <from> <to>' | 'remove edge <from> <to>' | 'set threshold <edge_from> <edge_to> <value>'\n  'add forward <edge_from> <edge_to> <forward_name>' | 'remove forward <edge_from> <edge_to> <forward_name>'\n  'set guard <edge_from> <edge_to> <forward_name> <guard_addr_or_name|none>'\n  'set permission <edge_from> <edge_to> <forward_name> <perm_index>'\n  'set operator <edge_from> <edge_to> <forward_name> <named_operator|none>'\n  'set weight <edge_from> <edge_to> <forward_name> <weight>'\n  'set retained_submission <edge_from> <edge_to> <forward_name> <comma_separated_indices|none>'\nGuard operations (8 total — see patch_guard_tree):\n  'add table <identifier> <name|none> <value_type> <b_submission> [json_value]'\n  'remove table <identifier>' | 'set table_value <identifier> [json_value|none]'\n  'set table_name <identifier> <name|none>' | 'set table_submission <identifier> <true|false>'\n  'set root <json_node>' | 'set rely <comma_separated_guard_addresses|none>'\nOperations are applied in order. Both patches are validated (validateMachine/validateGuard) before execution."
         }
       },
       "required": [

package/dist/schemas/query_toolkit.output.json

@@ -2819,10 +2819,10 @@
                                     "Signer"
                                   ],
                                   "additionalProperties": false,
-                                  "description": "Current transaction signer ID"
+                                  "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                                 }
                               ],
-                              "description": "Recipient 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)."
+                              "description": "Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). Use 0 for Order owner in Service-integrated mode (Customer who created the Order). The identifier must match a Guard table entry with b_submission=true. If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). Use for known recipients (e.g., 'turo_host', or a Treasury object address). Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). RESOLVED AT EXECUTION TIME, not at config time. For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."
                             },
                             "sharing": {
                               "type": [
@@ -2873,7 +2873,7 @@
                             "type": "null"
                           }
                         ],
-                        "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)."
+                        "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> via allocator_add(): when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: total_rates = max - fix (instead of balance - fix)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort."
                       }
                     },
                     "required": [
@@ -4950,10 +4950,10 @@
                             "Signer"
                           ],
                           "additionalProperties": false,
-                          "description": "Current transaction signer ID"
+                          "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                         }
                       ],
-                      "description": "Recipient 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)."
+                      "description": "Recipient of this allocation. Three forms — each resolves the address at a DIFFERENT time:\n• { GuardIdentifier: u8 } — DYNAMIC address resolved from Passport at alloc() time (contract calls passport::submission_get). Use 0 for Order owner in Service-integrated mode (Customer who created the Order). The identifier must match a Guard table entry with b_submission=true. If Passport has no matching submission, contract aborts with E_VERIFY_FAILED. Use when the recipient address is not known at config time and must be supplied via Guard submission data.\n• { Entity: { name_or_address: '...' } } — FIXED address resolved via LocalMark at SDK build time (passed to contract as a literal address). Use for known recipients (e.g., 'turo_host', or a Treasury object address). Use when the recipient is a stable, known address (e.g., operator receives rent, platform fee to treasury).\n• 'Signer' — the transaction sender at the time of the alloc() call (tx_context::sender). RESOLVED AT EXECUTION TIME, not at config time. For refunds: the customer (Order owner) must call alloc_by_guard THEMSELVES so that tx_context::sender resolves to THEIR address — if the operator calls alloc_by_guard, the operator becomes the recipient (Signer = operator), NOT the customer. Use when the recipient is whoever submits the allocation transaction (e.g., customer receives refund)."
                     },
                     "sharing": {
                       "type": [
@@ -5007,7 +5007,7 @@
                     "type": "null"
                   }
                 ],
-                "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)."
+                "description": "Maximum allocation cap (OPTIONAL — omit the field or set to null to disable the cap; do NOT set to 0 as that means a cap of zero). Passed through to the contract as Option<u64> via allocator_add(): when null/omitted the contract treats it as `none` (no cap); when set, the contract enforces it. Has THREE effects when set:\n1. Construction: sum of Amount items must be <= max (EAMOUNT_EXCEEDS_MAX=13)\n2. Rate execution: total_rates = max - fix (instead of balance - fix)\n3. Surplus execution: surplus_amount = max - alloced_amount (instead of balance - alloced_amount)\nUse when you want to cap total allocation regardless of Order balance (e.g., cap payout to declared amount). SDK pre-validates Amount sum <= max at build time to give actionable error messages before on-chain abort."
               }
             },
             "required": [
@@ -5347,10 +5347,10 @@
                       "Signer"
                     ],
                     "additionalProperties": false,
-                    "description": "Current transaction signer ID"
+                    "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                   }
                 ],
-                "description": "Recipient ID. 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)"
+                "description": "Recipient ID. Three forms:\n  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)"
               },
               "amount": {
                 "anyOf": [
@@ -5384,7 +5384,7 @@
                           "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."
+                        "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
                       }
                     },
                     "required": [
@@ -6384,17 +6384,17 @@
                       "Signer"
                     ],
                     "additionalProperties": false,
-                    "description": "Current transaction signer ID"
+                    "description": "Current transaction signer (tx_context::sender) at the time of the alloc() call. For refunds, the Order owner must call alloc_by_guard themselves to receive the funds."
                   }
                 ],
-                "description": "Recipient ID. 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)"
+                "description": "Recipient ID. Three forms:\n  - {GuardIdentifier: u8}  — DYNAMIC address resolved from Passport at alloc() time\n  - {Entity: {name_or_address: 'mark_name'}}  — FIXED static address via LocalMark (recommended)\n  - {Signer: 'signer'}  — transaction sender at alloc() time (e.g. self-refund; customer must call alloc_by_guard themselves)"
               },
               "amount": {
                 "type": [
                   "number",
                   "string"
                 ],
-                "description": "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."
+                "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
               }
             },
             "required": [
@@ -8445,7 +8445,7 @@
                 "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."
+              "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
             },
             {
               "type": "null"
@@ -13142,7 +13142,7 @@
                       "additionalProperties": false,
                       "description": "Forward in Machine object"
                     },
-                    "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."
+                    "description": "Forward list — operations to ENTER THIS NODE from prev_node. SEMANTIC CLARIFICATION: forwards describe INCOMING transitions (how to ARRIVE at this node), NOT outgoing transitions. Think of each forward as an 'entry door' to this node. Example: pair {prev_node:'A', forwards:[{name:'Go'}]} means 'use Go to advance FROM A TO THIS NODE'. For initial node (prev_node=''), forwards are operations to enter this node from the start state. DIAGRAM: A --[Go]--> B means the pair belongs to node B (destination), with prev_node='A'. WARNING: forwards belong to the DESTINATION node's pair, NOT the source node. Placing a forward on the wrong pair will cause Progress to get stuck."
                   }
                 },
                 "required": [
@@ -14201,7 +14201,7 @@
                 "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."
+              "description": "A coin/balance amount. Accepts three formats: (1) DISPLAY FORMAT with token symbol: \"2.5WOW\", \"10USDC\", \"0.05SUI\" — auto-converted to smallest units via the Fund Processing Layer (token precision resolved from official registry → cache → on-chain). The symbol MUST match the token's type_parameter. (2) SMALLEST UNIT (numeric string): \"10000000000\" — used as-is, no conversion. (3) SMALLEST UNIT (number): 10000000000 — used as-is (loses precision above 2^53). PRECISION RULE: for values exceeding 2^53, ALWAYS use format (1) or (2) — JS numbers lose precision. Default token: WOW (9 decimals, 1 WOW = 10^9 MIST). For custom tokens: use display format with the token's symbol, or pass smallest units directly. MONEY CONFIRMATION: all monetary fields trigger user confirmation via the Fund Processing Layer. If multiple tokens share a symbol (ambiguity), specify the full type string in type_parameter. Examples: \"2.5WOW\" (display → 2500000000), 10000000000 (number, smallest unit), \"50000000000\" (string, smallest unit). Used for: Service.sale.price, Service.compensation_fund_add balance, Treasury.deposit, Arbitration.fee, Reward.amount, stock quantities."
             },
             "token_type": {
               "type": "string",

package/dist/schemas/query_toolkit.schema.json

@@ -252,7 +252,7 @@
             },
             "name_or_address": {
               "type": "string",
-              "description": "Account name or address. Use empty string '' for the default account. Defaults to '' if omitted."
+              "description": "Account name or address to query. Examples: \"my_account\", \"0xabc123...\", or \"\" for the default account. NOTE: This field is NOT named 'filter' — use 'name_or_address' directly. Defaults to '' (default account) if omitted."
             },
             "balance": {
               "type": "boolean",
@@ -281,7 +281,7 @@
             },
             "token_type": {
               "type": "string",
-              "description": "Token type to query; defaults to 0x2::wow::WOW (platform token)"
+              "description": "Token type in Move format: 0x<package>::<module>::<struct>. Examples: \"0x2::wow::WOW\" (default, 9 decimals), \"0x2::sui::SUI\" (9 decimals). For custom tokens, use the full type string from the token's coin metadata. The Fund Processing Layer resolves precision from the official registry → cache → on-chain."
             },
             "network": {
               "type": "string",
@@ -297,7 +297,7 @@
             "query_type"
           ],
           "additionalProperties": false,
-          "description": "Query an account's coin balance OR paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Returns: { address, balance? | coin? }"
+          "description": "Query an account's coin balance OR paginated coin objects. PARAMETERS: Use 'name_or_address' to specify the account (NOT 'filter'). Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Use token_type to query non-default tokens (format: 0x<package>::<module>::<struct>). Returns: { address, balance? | coin? }"
         },
         {
           "type": "object",

package/dist/schemas/schema_query.output.json

@@ -43,6 +43,69 @@
               },
               "description": "List of schema summaries (list/search/list_operations)."
             },
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "type": "string",
+                    "description": "Example file name (e.g. 'rental-ziroom-service-create.json')."
+                  },
+                  "title": {
+                    "type": "string",
+                    "description": "Human-readable title from the example metadata."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Longer description from the example metadata."
+                  },
+                  "tags": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Tags from the example metadata."
+                  },
+                  "industry": {
+                    "type": "string",
+                    "description": "Industry category (e.g. 'rental', 'retail', 'general')."
+                  },
+                  "operation_type": {
+                    "type": "string",
+                    "description": "Operation type (e.g. 'service', 'machine', 'guard', 'permission')."
+                  },
+                  "verified": {
+                    "type": "boolean",
+                    "description": "Whether the example is marked as verified."
+                  },
+                  "score": {
+                    "type": "number",
+                    "description": "Relevance score — number of fields that matched the query (0-5)."
+                  },
+                  "matched_fields": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "List of fields that matched the query."
+                  }
+                },
+                "required": [
+                  "file",
+                  "title",
+                  "description",
+                  "tags",
+                  "industry",
+                  "operation_type",
+                  "verified",
+                  "score",
+                  "matched_fields"
+                ],
+                "additionalProperties": false
+              },
+              "description": "List of matching examples (search_examples)."
+            },
             {
               "type": "object",
               "additionalProperties": {},
@@ -53,7 +116,7 @@
               "description": "No data — lookup failed or returned nothing, or data was written to output_file."
             }
           ],
-          "description": "Response data — array of schema summaries for list-like actions, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."
+          "description": "Response data — array of schema summaries for list-like actions, array of example results for search_examples, JSON Schema object for get/get_output/get_field, Guard template data for get_guard_templates, null on failure or when output_file is used."
         },
         "message": {
           "type": "string",

package/dist/schemas/schema_query.schema.json

@@ -17,9 +17,10 @@
             "search",
             "list_operations",
             "get_guard_templates",
-            "get_field"
+            "get_field",
+            "search_examples"
           ],
-          "description": "Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices)."
+          "description": "Action to perform: 'list' (all schemas), 'get' (specific input schema), 'get_output' (tool output schema), 'get_field' (field-path query e.g. field_path='data.node'), 'search' (by keyword), 'list_operations' (on-chain operations), 'get_guard_templates' (Guard creation templates + best practices), 'search_examples' (search verified example files by keyword — matches title, description, tags, operation_type, industry)."
         },
         "name": {
           "type": "string",

package/dist/schemas/wowok_buildin_info.output.json

@@ -69,19 +69,23 @@
                     "properties": {
                       "index": {
                         "type": "number",
-                        "description": "Permission index"
+                        "description": "Permission index (e.g. 315 for service.compensation_fund_deposit)"
                       },
                       "name": {
                         "type": "string",
-                        "description": "Name"
+                        "description": "Permission name (e.g. \"service.compensation_fund_deposit\")"
                       },
                       "description": {
                         "type": "string",
-                        "description": "Description"
+                        "description": "Description of what this permission allows"
                       },
                       "object_type": {
                         "type": "string",
-                        "description": "Object type"
+                        "description": "Object type this permission belongs to (e.g. \"Service\", \"Arbitration\")"
+                      },
+                      "operation": {
+                        "type": "string",
+                        "description": "The SDK/MCP operation field name that triggers this permission check (e.g. \"compensation_fund_add\", \"publish\", \"pause\"). Undefined for permissions with no direct Call*_Data field (e.g. \"*.new\" permissions). Use this to answer: \"What permission does operation X require?\" by filtering with {operation: \"compensation_fund_add\"}."
                       }
                     },
                     "required": [
@@ -91,9 +95,78 @@
                       "object_type"
                     ],
                     "additionalProperties": false,
-                    "description": "Permission info type"
+                    "description": "Permission info type — includes the operation field name that maps to this permission, so AI can look up required permissions by operation name."
+                  },
+                  "description": "Built-in permissions result. Each item includes an optional \"operation\" field mapping to the SDK/MCP field name that triggers this permission."
+                }
+              },
+              "required": [
+                "info",
+                "result"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "object",
+              "properties": {
+                "info": {
+                  "type": "string",
+                  "const": "common mistakes"
+                },
+                "result": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "object_type": {
+                        "type": "string",
+                        "description": "The object type this mistake applies to (e.g. \"Service\", \"Arbitration\")"
+                      },
+                      "operation": {
+                        "type": "string",
+                        "description": "The operation field name this mistake applies to (e.g. \"compensation_fund_add\", \"voting_deadline\")"
+                      },
+                      "category": {
+                        "type": "string",
+                        "enum": [
+                          "field_name",
+                          "unit",
+                          "value_range",
+                          "workflow",
+                          "timing"
+                        ],
+                        "description": "Category of the mistake: field_name (wrong field name), unit (wrong unit like seconds vs ms), value_range (wrong expected value), workflow (wrong operation order), timing (wrong time constraint)"
+                      },
+                      "mistake": {
+                        "type": "string",
+                        "description": "Short description of the mistake"
+                      },
+                      "correct_usage": {
+                        "type": "string",
+                        "description": "The correct usage pattern"
+                      },
+                      "wrong_example": {
+                        "type": "string",
+                        "description": "Example of the wrong usage"
+                      },
+                      "correct_example": {
+                        "type": "string",
+                        "description": "Example of the correct usage"
+                      }
+                    },
+                    "required": [
+                      "object_type",
+                      "operation",
+                      "category",
+                      "mistake",
+                      "correct_usage",
+                      "wrong_example",
+                      "correct_example"
+                    ],
+                    "additionalProperties": false,
+                    "description": "A known common mistake for an on-chain operation. Use this to proactively warn users before they submit a transaction."
                   },
-                  "description": "Built-in permissions result"
+                  "description": "Common mistakes result. Each item documents a known pitfall (wrong field name, wrong unit, wrong workflow order, etc.) with wrong/correct examples."
                 }
               },
               "required": [
@@ -486,12 +559,12 @@
                       "parameters": {
                         "type": "array",
                         "items": {
-                          "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/2/properties/result/items/properties/returnType"
+                          "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/3/properties/result/items/properties/returnType"
                         },
                         "description": "Parameters for guard query"
                       },
                       "return": {
-                        "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/2/properties/result/items/properties/returnType",
+                        "$ref": "#/definitions/wowok_buildin_info/properties/result/anyOf/3/properties/result/items/properties/returnType",
                         "description": "Return type for guard query"
                       },
                       "parameters_description": {

package/dist/schemas/wowok_buildin_info.schema.json

@@ -80,17 +80,61 @@
                 "description": {
                   "type": "string",
                   "description": "Description filter"
+                },
+                "operation": {
+                  "type": "string",
+                  "description": "Filter by SDK/MCP operation field name (e.g. \"compensation_fund_add\"). Returns only permissions triggered by this operation. Use this to answer: \"What permission does operation X require?\""
+                }
+              },
+              "additionalProperties": false,
+              "description": "Filter for built-in permissions. Use operation:\"compensation_fund_add\" to find which permission a specific operation requires."
+            }
+          },
+          "required": [
+            "info"
+          ],
+          "additionalProperties": false,
+          "description": "Built-in permissions query. Each permission includes an optional \"operation\" field that maps to the SDK/MCP Call*_Data field name triggering it. Use this to answer: \"What permission does operation X require?\" — e.g. filter operation:\"compensation_fund_add\" returns permission index 315 (service.compensation_fund_deposit)."
+        },
+        {
+          "type": "object",
+          "properties": {
+            "info": {
+              "type": "string",
+              "const": "common mistakes"
+            },
+            "filter": {
+              "type": "object",
+              "properties": {
+                "object_type": {
+                  "type": "string",
+                  "description": "Filter by object type (e.g. \"Service\")"
+                },
+                "operation": {
+                  "type": "string",
+                  "description": "Filter by operation field name (e.g. \"compensation_fund_add\")"
+                },
+                "category": {
+                  "type": "string",
+                  "enum": [
+                    "field_name",
+                    "unit",
+                    "value_range",
+                    "workflow",
+                    "timing"
+                  ],
+                  "description": "Filter by category (e.g. \"field_name\" for field-name mistakes, \"unit\" for unit mistakes)"
                 }
               },
               "additionalProperties": false,
-              "description": "Filter for built-in permissions"
+              "description": "Filter for common mistakes. Use operation:\"compensation_fund_add\" to find mistakes for a specific operation, or category:\"field_name\" for all field-name mistakes."
             }
           },
           "required": [
             "info"
           ],
           "additionalProperties": false,
-          "description": "Built-in permissions query"
+          "description": "Common mistakes query. Returns known field-name, unit, value-range, workflow, and timing pitfalls for on-chain operations. Use this to proactively warn users before submitting a transaction. Example: query operation:\"compensation_fund_add\" to learn about the {amount} vs {balance} field name mistake."
         },
         {
           "type": "object",