@wowok/skills 1.0.6 → 1.1.0

package/schemas/onchain_operations/_index.md

@@ -1,6 +1,12 @@
 # onchain_operations / Index
 
-16 discriminated operation types. Each links to its schema file. Common types (CallEnv, SubmissionCall, Recipient, NamedObject, CoinParam, ValueTypes, etc.) are in [_common.md](./_common.md).
+> **Structure**: [Operation Table](#operation-table) · [CREATE vs MODIFY](#create-vs-modify-pattern) · [Top-Level Structure](#top-level-structure) · [Guard Submission](#guard-submission-mechanism) · [Field Execution Order](#field-execution-order) · [Value Types](#value-types)
+>
+> Common schemas (CallEnv, SubmissionCall, sub-schemas like NamedObject, CoinParam, Recipient, etc.) are in [_common.md](./_common.md).
+
+## Operation Table
+
+16 discriminated operation types. Each links to its schema file.
 
 | operation_type | File | Description |
 |---|---|---|
@@ -19,4 +25,172 @@
 | `payment` | [payment.md](./payment.md) | Irreversible coin transfers to wallets |
 | `demand` | [demand.md](./demand.md) | Service request postings with reward pools |
 | `order` | [order.md](./order.md) | Order lifecycle: progress, arbitration, refunds, ownership |
-| `gen_passport` | [gen_passport.md](./gen_passport.md) | Immutable verified credentials after Guard validation |
+| `gen_passport` | [gen_passport.md](./gen_passport.md) | Immutable verified credentials after Guard validation |
+
+---
+
+## CREATE vs MODIFY Pattern
+
+All on-chain object operations use a **unified discriminated pattern** for CREATE vs MODIFY:
+
+```typescript
+// CREATE: object is an object with configuration
+object: {
+  name?: string;           // Optional name for the new object
+  tags?: string[];         // Optional tags
+  onChain?: boolean;       // Whether to register name on-chain (public)
+  replaceExistName?: boolean;  // Force claim existing name
+  permission?: DescriptionObject;  // Permission (string or new object)
+  type_parameter?: string; // Token type (e.g., "0x2::wow::WOW")
+}
+
+// MODIFY: object is a string referencing existing object
+object: "<object_name_or_id>"  // Existing object name (local mark) or on-chain ID
+```
+
+### Key Rule
+
+| Format | Meaning | Example |
+|--------|---------|---------|
+| **String** | Reference EXISTING object | `object: "my-service"` or `object: "0x1234..."` |
+| **Object** | CREATE NEW object | `object: { name: "my-service", permission: "..." }` |
+
+### Type Mapping
+
+| Type | Used By | CREATE Shape | MODIFY Shape |
+|------|---------|--------------|--------------|
+| `TypedPermissionObject` | `service`, `arbitration`, `treasury`, `reward` | `{ name?, tags?, onChain?, replaceExistName?, type_parameter, permission? }` | `string` |
+| `WithPermissionObject` | `machine`, `repository`, `demand`, `contact` | `{ name?, tags?, onChain?, replaceExistName?, permission? }` | `string` |
+| `TypedDescriptionObject` | *(not directly used by operations)* | `{ name?, tags?, onChain?, replaceExistName?, type_parameter }` | `string` |
+| `TypeNamedObject` | `allocation` (CREATE), `payment` | `{ name?, tags?, onChain?, replaceExistName?, type_parameter? }` | N/A |
+| `DescriptionObject` | `permission` field of other types | `{ name?, tags?, onChain?, replaceExistName?, description? }` | `string` |
+| `NormalObject` | `permission` | `{ name?, tags?, onChain?, replaceExistName? }` | `string` |
+| `NamedObject` | `namedNew*`, `guard.namedNew` | `{ name?, tags?, onChain?, replaceExistName? }` | N/A |
+
+### Guard Exception
+
+`guard` operation is **CREATE-only** and immutable. Guards cannot be modified after creation. Create new Guard to update logic.
+
+---
+
+## Top-Level Structure
+
+Most operations follow this standard wrapper:
+
+```typescript
+OnchainOperations {
+  operation_type: string;     // One of 16 types
+  data: object;               // Type-specific data (required)
+  env?: CallEnv;              // Optional environment
+  submission?: SubmissionCall; // Optional Guard submission data
+}
+```
+
+### Exceptions
+
+| Operation | Structure | Notes |
+|-----------|-----------|-------|
+| `gen_passport` | `{ guard, info?, env? }` | FLAT — no `data` wrapper, no `submission` |
+| `guard` | `{ data, env? }` | No `submission` field |
+| `payment` | `{ data, env? }` | No `submission` field |
+| `personal` | `{ data, env? }` | No `submission` field |
+
+---
+
+## Guard Submission Mechanism
+
+When calling `onchain_operations`, the tool returns one of the following:
+
+- **Direct Result**: The operation completes immediately. Returns a transaction result, data, or error. No additional steps needed.
+- **Submission Required**: Returns `type: "submission"` — the operation triggered a Guard requiring user-provided data. A second call is needed to complete it.
+
+### Direct Result Pattern
+
+Most operations return a direct result when no Guard submission is required:
+
+```
+onchain_operations({ operation_type: "<type>", data: { ... } })
+→ Returns transaction result or error directly
+```
+
+### Submission Required Pattern
+
+When the operation triggers a Guard whose table contains entries with **`b_submission: true`**, the tool does **not** return a transaction result immediately. Instead, it returns a **`type: "submission"`** response containing the Guard's data requirements.
+
+This is the **only scenario** where a second call is required to complete an operation.
+
+**Two-Step Flow**:
+
+```
+Step 1 — Initial Call
+├── onchain_operations (e.g., service, machine, progress, order, etc.)
+└── Response: { type: "submission", ... }
+    ├── guard: [{ object, impack }] — Guards requiring verification
+    └── submission: [{ guard, submission: [{ identifier, value_type, value?, name }] }]
+        ↑ You ONLY fill the `value` field. Do NOT modify other fields.
+
+Step 2 — Re-submit with Completed Data
+├── Same operation data (unchanged)
+└── Add top-level `submission` field:
+    {
+      "type": "submission",
+      "guard": [{ "object": "guard_name", "impack": true }],
+      "submission": [{
+        "guard": "guard_name",
+        "submission": [
+          { "identifier": 0, "value_type": "String", "value": "your_data_here" }
+        ]
+      }]
+    }
+```
+
+**Critical Rules**:
+- **Only fill `value`**: The template has `identifier`, `value_type`, `name` pre-filled. You ONLY supply the `value` field matching the `value_type`. Never modify `identifier`, `value_type`, or `name`.
+- **Value type matching**: `value_type` indicates the expected type (`String`, `Address`, `U64`, `Bool`, etc.). The `value` must match exactly.
+- **Impack flag**: `impack: true` means this Guard's result affects the final outcome. All `impack=true` Guards must pass for the operation to proceed.
+- **All fields required**: Fill every entry in the `submission` array. Incomplete submission data causes a validation error.
+- **Do not change other fields**: The `data` and `env` portions of the original call must remain identical.
+
+**Common Submission Scenarios**:
+- **Merkle Root proof**: `value_type: "String"`, value = hex string.
+- **Progress/Order address**: `value_type: "Address"`, value = object name or ID.
+
+---
+
+## Field Execution Order
+
+**Rule**: Schema field order determines execution order, regardless of JSON field order.
+
+**AI Guidelines**:
+1. Check schema field order against user's intended operation sequence
+2. If schema order conflicts with intent, split into multiple sequential calls
+3. When uncertain, use incremental steps rather than single batch operation
+4. Between incremental steps, verify the previous modification landed on-chain: use `query_toolkit({ query_type: "onchain_objects", objects: ["<name>"], no_cache: true })` to confirm the object's updated state before proceeding to the next call
+
+---
+
+## Value Types
+
+All Guard `value_type` fields and `GuardTableItem.value_type` use these types:
+
+| Type | ID | Description |
+|------|-----|-------------|
+| Bool | 0 | Boolean true/false |
+| Address | 1 | Object or account address |
+| String | 2 | UTF-8 string |
+| U8 | 3 | 8-bit unsigned integer |
+| U16 | 4 | 16-bit unsigned integer |
+| U32 | 5 | 32-bit unsigned integer |
+| U64 | 6 | 64-bit unsigned integer |
+| U128 | 7 | 128-bit unsigned integer |
+| U256 | 8 | 256-bit unsigned integer |
+| VecBool | 9 | Vector of booleans |
+| VecAddress | 10 | Vector of addresses |
+| VecString | 11 | Vector of strings |
+| VecU8 | 12 | Vector of U8 |
+| VecU16 | 13 | Vector of U16 |
+| VecU32 | 14 | Vector of U32 |
+| VecU64 | 15 | Vector of U64 |
+| VecU128 | 16 | Vector of U128 |
+| VecU256 | 17 | Vector of U256 |
+| VecVecU8 | 18 | Vector of VecU8 |

package/schemas/onchain_operations/allocation.md

@@ -1,50 +1,28 @@
 # onchain_operations / allocation
 
-Create distribution plans to auto-distribute funds to multiple recipients.
+Define token distribution plans with payment scheduling and Guard-triggered distribution.
+
+> **Schema**: `CallAllocation_Data` is a **union** of two variants — CREATE or OPERATE.
 
 ## Data Schema
 
 ```typescript
-// Allocation has TWO modes — discriminated by object format
-
-// MODE 1: Create a new Allocation with allocators
-CallAllocation_Create {
-  object: {
-    name?: string;                 // Object name
-    tags?: string[];               // Tags
-    onChain?: boolean;             // Public on-chain name
-    replaceExistName?: boolean;    // Force claim name
-    type_parameter?: string;       // Token type (default: "0x2::wow::WOW")
-  };
-  allocators: {
-    description: string;           // Allocator list description
-    threshold: number;             // Trigger threshold
-    allocators: {
-      guard: string;               // Guard object ID — allocation triggers on verify
-      sharing: {
-        who: Recipient;            // Recipient specification
-        sharing: number;           // Amount or rate
-        mode: "Amount" | "Rate" | "Surplus";
-      }[];
-      fix?: number;                // Fixed amount per recipient
-      max?: number | null;         // Maximum allocation amount
-    }[];
-  };
-  coin: CoinParam;                 // Initial funding
-  payment_info: {
-    remark?: string;
-    index?: number;
-  };
-}
-
-// MODE 2: Operate existing Allocation
-CallAllocation_Operate {
-  object: string;                  // Allocation object ID or name (required)
-  received_coins?: ReceivedBalanceOrRecently; // Unwrap CoinWrapper
-  alloc_by_guard?: string;         // Verify Guard and trigger allocation
-}
+CallAllocation_Data = 
+  // CREATE: Create a new Allocation object
+  | {
+      object: TypeNamedObject;         // CREATE with {name, type_parameter?}
+      allocators: Allocators;          // Fund allocator rules
+      coin: CoinParam;                 // Asset to allocate
+      payment_info: PaymentInfo;       // Payment record info
+    }
+  // OPERATE: Operate on existing Allocation object
+  | {
+      object: NameOrAddress;                  // Allocation object ID or name
+      received_coins?: ReceivedBalanceOrRecently;  // Unwrap received CoinWrappers into pending balance
+      alloc_by_guard?: NameOrAddress;    // Verify Guard and execute fund allocation
+    };
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, CoinParam, Recipient, ReceivedBalanceOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypeNamedObject, Allocators, CoinParam, PaymentInfo, ReceivedBalanceOrRecently.

package/schemas/onchain_operations/arbitration.md

@@ -1,95 +1,106 @@
 # onchain_operations / arbitration
 
-Access a transparent on-chain arbitration system for resolving order conflicts.
+Create arbitration rules for dispute resolution.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Arbitration uses `TypedPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallArbitration_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: TypedPermissionObject
   object: TypedPermissionObject;
   
-  // Create new Arb for order
+  // Create new Arb object for an order
   dispute?: {
-    order: string;                  // Order ID
-    description?: string;
-    proposition: string[];          // Dispute propositions
-    fee: CoinParam;                 // Arbitration fee
-    namedArb?: NamedObject;         // Name for new Arb
+    order: NameOrAddress;                // Order ID or name
+    description?: string;                // Dispute description (max 4000 bcs chars)
+    proposition: string[];               // List of dispute propositions (each max 256 bcs chars)
+    fee: CoinParam;                      // Dispute processing fee
+    namedArb?: NamedObject;              // Name for newly created arbitration object
   };
   
-  description?: string;             // Institution description
-  location?: string;                // Arbitration location
-  fee?: number;                     // Arbitration fee
-  pause?: boolean;                  // Pause arbitration
+  description?: string;                  // Introduction of the Arbitration object (max 4000 bcs chars)
+  location?: string;                     // Arbitration location (max 256 bcs chars)
+  fee?: string | number;                 // Arbitration fee
+  pause?: boolean;                       // Whether to pause arbitration
   
-  // Confirm user's materials
+  // Confirm materials submitted for arbitration
   confirm?: {
-    arb: string;                    // Arb object ID
-    voting_deadline: number | null;
+    arb: NameOrAddress;                  // Arb object ID or name
+    voting_deadline: number | null;      // Voting deadline
   };
   
-  // Modify voting deadline
+  // Change voting deadline
   voting_deadline_change?: {
-    arb: string;
-    voting_deadline: number | null;
+    arb: NameOrAddress;                  // Arb object ID or name
+    voting_deadline: number | null;      // New voting deadline
   };
   
   // Vote on propositions
   vote?: {
-    arb: string;
-    votes: number[];                // Supported proposition indices
-    voting_guard?: string;          // Guard for voting
+    arb: NameOrAddress;                  // Arb object ID or name
+    votes: number[];                     // Vote values (per proposition, 0-255)
+    voting_guard?: NameOrAddress;        // Voting Guard object ID or name
   };
   
-  // Arbitration feedback
+  // Provide arbitration feedback
   feedback?: {
-    arb: string;
-    feedback: string;
+    arb: NameOrAddress;                  // Arb object ID or name
+    feedback: string;                    // Arbitration feedback (max 4000 bcs chars)
   };
   
-  // Final arbitration result
+  // Provide definitive arbitration result
   arbitration?: {
-    arb: string;
-    feedback: string;
-    indemnity: number;              // Compensation amount
+    arb: NameOrAddress;                  // Arb object ID or name
+    feedback: string;                    // Arbitration feedback (max 4000 bcs chars)
+    indemnity: number;                   // Indemnity amount (int >= 0)
   };
   
-  // Request resubmission
+  // User applies to resubmit materials and restart arbitration
   reset?: {
-    arb: string;
-    feedback: string;
+    arb: NameOrAddress;                  // Arb object ID or name
+    feedback: string;                    // Arbitration feedback (max 4000 bcs chars)
   };
   
-  // Withdraw arbitration fee
+  // Withdraw arbitration fees
   arb_withdraw?: {
-    arb: string;
+    arb: NameOrAddress;                  // Arb object ID or name
   };
   
-  // Distribute fees
+  // Distribute withdrawn arbitration fees
   fees_transfer?: {
-    to: { allocation: string } | { treasury: string };
-    payment_remark: string;
-    payment_index: number;
-    newPayment?: NamedObject;
-  };
-  
-  usage_guard?: string | null;      // Guard for applying
-  
-  // Guard for voting
-  voting_guard?: {
-    op: "add" | "set" | "remove" | "clear";
-    guards?: {
-      guard: string;
-      service_identifier?: number;
-    }[];
+    to: 
+      | { allocation: NameOrAddress }     // Transfer to Allocation object
+      | { treasury: NameOrAddress };      // Transfer to Treasury object
+    payment_remark: string;              // Payment remark (max 64 bcs chars)
+    payment_index: number;               // Payment index (int >= 0)
+    newPayment?: NamedObject;            // Name for new payment object
   };
   
+  usage_guard?: NameOrAddress | null;    // Guard for verifying when users apply
+  voting_guard?: VotingGuardAction;      // Guard for verifying during voting
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: NameOrAddress | null;            // Contact object
 }
+
+// Voting guard operations (discriminated union)
+VotingGuardAction = 
+  | {
+      op: "add" | "set";
+      guards: VotingGuard[];             // Array of voting guard configs
+    }
+  | {
+      op: "remove";
+      guards: NameOrAddress[];             // Guard IDs or names to remove
+    }
+  | {
+      op: "clear";
+    };
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, NamedObject, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, NamedObject, VotingGuard, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/contact.md

@@ -1,28 +1,32 @@
 # onchain_operations / contact
 
-Manage on-chain instant messaging contact profiles.
+Create Contact objects linking social signals to on-chain rewards.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Contact uses `WithPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallContact_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: WithPermissionObject
   object: WithPermissionObject;
   
-  my_status?: string;               // Status message
-  description?: string;             // Contact description
-  location?: string;                // Location
+  my_status?: string;                    // Set your status message in this contact list (max 64 bcs chars)
+  description?: string;                  // Contact object description or public information (max 4000 bcs chars)
+  location?: string;                     // Physical or virtual location information (max 256 bcs chars)
   
-  // IM contact list (discriminated union)
+  // IM contact list operations (discriminated union)
   ims?: {
     op: "add" | "set";
-    im: {                           // Contact entries
-      at: string;                   // IM address
-      description?: string;         // Optional note
+    im: {
+      at: NameOrAddress;                 // Contact address or name for IM
+      description?: string;              // Optional description (max 256 bcs chars)
     }[];
   } | {
     op: "remove";
-    im: string[];                   // Addresses/names to remove
+    im: NameOrAddress[];                 // Contact addresses or names to remove
   } | {
     op: "clear";
   };
@@ -33,4 +37,4 @@ CallContact_Data {
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, WithPermissionObject, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/demand.md

@@ -1,52 +1,53 @@
 # onchain_operations / demand
 
-Post service requests with reward pools on-chain.
+Create and manage Demand objects for service procurement with Guard validation.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Demand uses `WithPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallDemand_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: WithPermissionObject
   object: WithPermissionObject;
   
-  // Recommend Service to Demand
+  // Recommend a Service to the Demand
   present?: {
-    recommend: string;             // Recommendation text
-    by_guard?: string;             // Guard to verify through
-    service?: string;              // Service ID or name
+    recommend: string;                   // Recommendation description (max 4000 bcs chars)
+    by_guard?: NameOrAddress;            // Guard ID — pass verification via Guard
+    service?: NameOrAddress;             // Service ID or name to present
   };
   
-  description?: string;             // Demand description
-  location?: string;                // Demand location
+  description?: string;                  // Demand description (max 4000 bcs chars)
+  location?: string;                     // Service location (max 256 bcs chars)
+  
+  rewards?: ObjectsOp;                   // Reward information
   
-  rewards?: ObjectsOp;              // Reward operations
+  // User feedback
+  feedback?: {
+    who: AccountOrMark_Address;          // User being rated
+    acceptance_score?: number;           // Acceptance score (0-255)
+    feedback?: string;                   // Feedback content (max 4000 bcs chars)
+  }[];
   
-  // Service Guard list (discriminated union)
+  // Validation Guards (discriminated union)
   guards?: {
     op: "add" | "set";
-    guard: {
-      guard: string;               // Guard object ID
-      service_identifier?: number | null; // Service identifier in Guard
-    }[];
+    guard: ServiceGuard[];               // Guard configs to add/set
   } | {
     op: "remove";
-    guard: string[];               // Guard IDs/names to remove
+    guard: NameOrAddress[];              // Guard IDs or names to remove
   } | {
     op: "clear";
   };
   
-  // Feedback on presenters (array — multiple feedback entries)
-  feedback?: {
-    who: AccountOrMark_Address;    // Presenter's account
-    acceptance_score?: number;     // 0-255 acceptance score
-    feedback?: string;             // Feedback content
-  }[];
-  
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: NameOrAddress | null;           // Contact object
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ObjectsOp, AccountOrMark_Address, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ObjectsOp, ServiceGuard, AccountOrMark_Address, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/gen_passport.md

@@ -1,43 +1,23 @@
 # onchain_operations / gen_passport
 
-Create immutable verified credentials after Guard validation passes.
+Generate Verified Passport Object: Create immutable verified credentials (passport).
 
-> **IMPORTANT**: Unlike other onchain operations, `gen_passport` uses a FLAT input structure — fields `guard`, `info`, `env` are directly at the top level, NOT nested under a `data` wrapper.
+> **Structure Exception**: `gen_passport` has a **FLAT** structure — no `data` wrapper, no `submission` field.
 
-## Input Schema
+## Schema
 
 ```typescript
-CallGenPassport_Input {
-  guard: string | string[];         // Guard object ID(s) to verify. Can be a single guard or an array of guards.
-  info?: SubmissionCall;            // Optional submission data
-  env?: CallEnv;                    // Optional environment configuration
-}
-```
-
-## Features
-
-- **Single Guard**: Pass a single guard ID or name as a string
-- **Multiple Guards**: Pass an array of guard IDs or names to verify multiple guards at once
-- **Name Resolution**: Supports both guard addresses and LocalMark names
-
-## Examples
-
-### Single Guard
-```typescript
-{
-  guard: "my-guard-name",  // or "0x1234567890abcdef..."
-  env: { network: "testnet" }
-}
-```
-
-### Multiple Guards
-```typescript
-{
-  guard: ["guard-1", "guard-2", "0x1234567890abcdef..."],
-  env: { network: "testnet" }
+GenPassport {
+  // Guard verification
+  guard: NameOrAddress | NameOrAddress[];  // Guard object ID(s) to verify and embed
+  
+  // Optional submission data during Guard verification
+  info?: SubmissionCall;              // Submission data for Guards requiring user input
+  
+  env?: CallEnv;                      // Optional execution environment
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall.