@wowok/skills 1.0.6 → 1.1.0

package/schemas/onchain_operations/repository.md

@@ -1,81 +1,70 @@
 # onchain_operations / repository
 
-Read/write database with consensus field + address as key, strongly-typed data as value.
+Define trusted data sources with typed policies, data read/write rules, and contribution incentives.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Repository uses `WithPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallRepository_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: WithPermissionObject
   object: WithPermissionObject;
   
-  description?: string;             // Repository description
+  description?: string;               // Repository description (max 4000 bcs chars)
   
-  // Policy rules (discriminated by op)
+  // Policy rules (discriminated union)
   policies?: {
     op: "add" | "set";
-    policy: PolicyRule[];
+    policy: PolicyRule[];             // Policy rule list
   } | {
     op: "remove";
-    policy: string[];               // Policy names to remove
+    policy: string[];                 // Policy rule names to remove
   } | {
     op: "clear";
   };
   
-  // Add data (discriminated union)
-  data_add?: {
-    name: string;
-    write_guard?: string;
-    data: SupportedValue;
-  } | {
-    name: string;
-    items: {
-      data: {
-        id: string | number;
-        data: SupportedValue;
-      }[];
-      write_guard?: string;
-    }[];
-  };
+  // Add data
+  data_add?: 
+    | {
+        name: string;                  // Data item name (must match PolicyRule)
+        write_guard?: NameOrAddress;   // Guard for write permissions
+        data: SupportedValue;          // Data value (ID = timestamp or signer)
+      }
+    | {
+        name: string;                  // Data item name
+        items: {
+          data: {
+            id: AccountOrMark_Address | number;  // Data item ID
+            data: SupportedValue;       // Data value
+          }[];
+          write_guard?: NameOrAddress;  // Guard for write permissions
+        }[];
+      };
   
-  // Remove data (discriminated union)
-  data_remove?: {
-    name: string;
-    write_guard?: string;
-  } | {
-    name: string;
-    items: {
-      id: (string | number)[];
-      write_guard?: string;
-    }[];
-  };
+  // Remove data
+  data_remove?: 
+    | {
+        name: string;                  // Data item name
+        write_guard?: NameOrAddress;   // Guard for verifying deletion permission
+      }
+    | {
+        name: string;
+        items: {
+          id: (AccountOrMark_Address | number)[]; // Data item IDs
+          write_guard?: NameOrAddress;  // Guard for verifying deletion permission
+        }[];
+      };
   
-  rewards?: ObjectsOp;              // Reward operations
+  rewards?: ObjectsOp;                 // Reward object list (contribution incentives)
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
-}
-```
-
-### PolicyRule
-
-```typescript
-PolicyWriteGuard {
-  guard: string;                       // Guard object ID
-  id_from_submission?: number;         // Guard table index for data ID (omit = user specifies)
-  data_from_submission?: number;       // Guard table index for data value (omit = user specifies)
-}
-
-PolicyRule {
-  name: string;                        // Policy rule name
-  description: string;                 // Policy rule description
-  write_guard: PolicyWriteGuard[];     // Guard list for write verification
-  quote_guard?: string | null;         // Guard for on-chain quote verification (null = no verification required)
-  id_from: 0 | 1 | 2 | "None" | "Clock" | "Signer" | "none" | "clock" | "signer";
-                                       // Data ID source: 0/None = user-specified, 1/Clock = timestamp, 2/Signer = signer ID
-  value_type: ValueType;               // Type of data value
+  um?: NameOrAddress | null;          // Contact object
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ValueType, ObjectsOp, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ObjectsOp, ReceivedObjectsOrRecently.  
+`PolicyRule` schema is defined in the MCP source at `src/schema/query/index.ts`.

package/schemas/onchain_operations/reward.md

@@ -1,40 +1,38 @@
 # onchain_operations / reward
 
-Create reward pools and set claim conditions by Guard verification.
+Create and manage token rewards with Guards and distribution rules.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Reward uses `TypedPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallReward_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: TypedPermissionObject
   object: TypedPermissionObject;
   
-  claim?: string;                   // Guard object ID for claiming
-  description?: string;             // Reward description
-  coin_add?: CoinParam;             // Add funds
-  receive?: ReceivedBalanceOrRecently; // Unwrap CoinWrapper
-  
-  // Add reward Guards (each specifies a claim condition)
-  guard_add?: {
-    guard: string;                  // Guard object ID to verify
-    recipient: Recipient;           // Who receives reward
-    amount: {                       // Amount (discriminated union)
-      type: "GuardU64Identifier";
-      value: number;                // Identifier 0-255 in Guard table
-    } | {
-      type: "Fixed";
-      value: number;                // Fixed amount
-    };
-    expiration_time?: number;       // Expiration timestamp (ms)
-    store_from_id?: number | null;  // Guard table storage identifier
-  }[];
-  
-  guard_remove_expired?: boolean;   // Remove expired Guards
-  guard_expiration_time?: number | null; // Lock adding new Guards until this time (ms)
+  claim?: NameOrAddress;                  // Guard object ID — verify Guard to trigger reward distribution
+  
+  description?: string;                    // Reward description (max 4000 bcs chars)
+  
+  coin_add?: CoinParam;                    // Add amount to Reward object
+  
+  // Unwrap received CoinWrappers and store in pending balance
+  receive?: ReceivedBalanceOrRecently;
+  
+  guard_add?: RewardGuard[];               // Add Guard to Reward object
+  
+  guard_remove_expired?: boolean;          // Whether to remove expired Guards
+  
+  guard_expiration_time?: number | null;   // Expiration time (ms, >= 1) — blocks new Guard additions until expired
+  
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: NameOrAddress | null;              // Contact object
 }
+```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently, Recipient.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, RewardGuard, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/service.md

@@ -2,103 +2,77 @@
 
 Create and manage product/service listings with transparent promises, bind workflow templates, set pricing, issue discount coupons.
 
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Service uses `TypedPermissionObject`: object shape = CREATE, string = MODIFY.
+
 ## Data Schema
 
 ```typescript
 CallService_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: TypedPermissionObject
   object: TypedPermissionObject;
   
   // Create new order (customer purchase)
   order_new?: {
     buy: {
       items: {
-        name: string;        // Product name
-        stock: number;       // Quantity
-        wip_hash: string;    // WIP file hash
+        name: string;              // Product name (max 256 bcs chars)
+        stock: string | number;    // Quantity
+        wip_hash: string;          // WIP file hash
       }[];
-      total_pay: CoinParam;  // Payment amount
-      discount?: string;     // Discount object ID
-      payment_remark?: string;
-      payment_index?: number;
+      total_pay: CoinParam;        // Payment amount
+      discount?: string;           // Discount object ID
+      payment_remark?: string;     // Payment remark
+      payment_index?: number;      // Payment index
     };
     agents?: ManyAccountOrMark_Address;  // Order agents
-    order_required_info?: string;        // Contact or WTS proof
+    order_required_info?: string;        // Contact object ID or WTS Proof
     transfer?: AccountOrMark_Address;    // New order owner
     namedNewOrder?: NamedObject;         // Name for new Order
     namedNewAllocation?: NamedObject;    // Name for new Allocation
     namedNewProgress?: NamedObject;      // Name for new Progress
   };
   
-  description?: string;      // Service description
-  location?: string;         // Service location
+  description?: string;              // Service description (max 4000 bcs chars)
+  location?: string;                 // Service location (max 256 bcs chars)
   
   // Sales operations (discriminated union)
   sales?: {
     op: "add" | "set";
-    sales: {                       // Array of sale items (REQUIRED)
-      name: string;                // Product name
-      price: number;               // Price
-      stock: number;               // Stock quantity
-      suspension: boolean;         // Whether suspended
-      wip: string;                 // WIP file URL
-      wip_hash: string;            // WIP hash
-    }[];
+    sales: ServiceSale[];            // Array of sale items (REQUIRED for add/set)
   } | {
     op: "remove";
-    sales_name: string[];          // Sale names to remove (REQUIRED)
+    sales_name: string[];            // Sale names to remove (REQUIRED) (each max 256 bcs chars)
   } | {
     op: "clear";
   };
   
-  repositories?: ObjectsOp;  // Repository operations
-  rewards?: ObjectsOp;       // Reward operations
-  arbitrations?: ObjectsOp;  // Arbitration operations
-  machine?: string | null;   // Machine object ID
+  repositories?: ObjectsOp;          // Repository operations
+  rewards?: ObjectsOp;               // Reward operations
+  arbitrations?: ObjectsOp;          // Arbitration operations
+  machine?: NameOrAddress | null;    // Machine object ID
   
   // Discount coupon
-  discount?: {
-    name: string;
-    discount_type: 0 | 1;  // 0 = RATES (percentage), 1 = FIXED (fixed amount)
-    discount_value: number;
-    benchmark?: number;
-    time_ms_start?: number;
-    time_ms_end?: number;
-    count?: number;
-    recipient: ManyAccountOrMark_Address;
-    transferable?: boolean;
-  };
+  discount?: Discount;
   
-  discount_destroy?: string[];  // Discount IDs to destroy
-  customer_required?: string[]; // Required info (phone, email, etc.)
+  discount_destroy?: NameOrAddress[];  // Discount IDs to destroy
+  customer_required?: NotEmptyName[];  // Required info names (non-empty strings)
   
   // Order fund allocators
-  order_allocators?: {
-    description: string;
-    threshold: number;
-    allocators: {
-      guard: string;         // Guard object ID
-      sharing: {
-        who: Recipient;      // Recipient specification
-        sharing: number;     // Amount or rate
-        mode: "Amount" | "Rate" | "Surplus";
-      }[];
-      fix?: number;          // Fixed amount
-      max?: number;          // Maximum amount
-    }[];
-  } | null;
+  order_allocators?: Allocators | null;
   
-  buy_guard?: string | null;     // Purchase Guard
-  compensation_fund_add?: CoinParam;
-  setting_locked_time_add?: number;
+  buy_guard?: NameOrAddress | null;    // Purchase Guard ID or name
+  compensation_fund_add?: CoinParam; // Compensation fund
+  setting_locked_time_add?: number;  // Additional lock time (ms), extends 30-day default
   compensation_fund_receive?: ReceivedBalanceOrRecently;
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;            // Contact object
-  pause?: boolean;               // Pause new orders
-  publish?: boolean;             // Publish service (immutable)
+  um?: NameOrAddress | null;         // Contact object ID or name
+  pause?: boolean;                   // Pause new orders
+  publish?: boolean;                 // Publish service (immutable after)
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, ObjectsOp, CoinParam, NamedObject, AccountOrMark_Address, ManyAccountOrMark_Address, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently, Recipient.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, NamedObject, CoinParam, ObjectsOp, ServiceSale, Discount, Allocators, AccountOrMark_Address, ManyAccountOrMark_Address, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/treasury.md

@@ -1,74 +1,68 @@
 # onchain_operations / treasury
 
-Create and manage treasury for team funds with deposit/withdrawal rules.
+Create secure shared pools for managing deposits, withdrawals, and fund allocation scheduling.
+
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Treasury uses `TypedPermissionObject`: object shape = CREATE, string = MODIFY.
 
 ## Data Schema
 
 ```typescript
 CallTreasury_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: TypedPermissionObject
   object: TypedPermissionObject;
   
-  description?: string;             // Treasury description
-  receive?: ReceivedBalanceOrRecently; // Receive CoinWrapper
+  description?: string;                     // Treasury description (max 4000 bcs chars)
+  
+  // Unwrap and deposit received CoinWrappers
+  receive?: ReceivedBalanceOrRecently;
   
-  // Deposit funds
+  // Deposit to Treasury
   deposit?: {
-    coin: CoinParam;
-    by_external_deposit_guard?: string;
-    payment_info: {
-      remark?: string;
-      index?: number;
-    };
-    namedNewPayment?: NamedObject;
+    coin: CoinParam;                        // Asset to deposit
+    by_external_deposit_guard?: string;     // Deposit via Guard verification (not Permission)
+    payment_info: PaymentInfo;
+    namedNewPayment?: NamedObject;          // Name for new Payment object
   };
   
-  // Withdraw funds
+  // Withdraw from Treasury
   withdraw?: {
-    amount: { fixed: number } | { by_external_withdraw_guard: string };
-    recipient: AccountOrMark_Address;
-    payment_info: {
-      remark?: string;
-      index?: number;
-    };
-    namedNewPayment?: NamedObject;
+    amount: 
+      | { fixed: string | number }          // Fixed amount (Permission-based)
+      | { by_external_withdraw_guard: string }; // Guard-based (amount from Guard index)
+    recipient: AccountOrMark_Address;       // Recipient ID or account
+    payment_info: PaymentInfo;
+    namedNewPayment?: NamedObject;          // Name for new Payment object
   };
   
-  // External deposit Guards (discriminated union)
+  // External deposit Guard operations
   external_deposit_guard?: {
     op: "add" | "set";
-    guards: {                      // Array of Guard configs (REQUIRED for add/set)
-      guard: string;               // Guard object ID or name
-      identifier?: number | null;  // Guard table index for deposit amount limit (null = unlimited)
-      store_from_id?: number | null; // Guard table index for record storage
-    }[];
+    guards: AmountFromDepositGuard[];       // Deposit Guard list
   } | {
     op: "remove";
-    guards: string[];              // Guard IDs/names to remove (REQUIRED)
+    guards: NameOrAddress[];                // Guard IDs or names to remove
   } | {
     op: "clear";
   };
   
-  // External withdraw Guards (discriminated union)
+  // External withdraw Guard operations
   external_withdraw_guard?: {
     op: "add" | "set";
-    guards: {                      // Array of Guard configs (REQUIRED for add/set)
-      guard: string;               // Guard object ID or name
-      identifier?: number | null;  // Guard table index for withdrawal amount limit (null = unlimited)
-      store_from_id?: number | null; // Guard table index for record storage
-    }[];
+    guards: AmountFromWithdrawGuard[];      // Withdraw Guard list
   } | {
     op: "remove";
-    guards: string[];              // Guard IDs/names to remove (REQUIRED)
+    guards: NameOrAddress[];                // Guard IDs or names to remove
   } | {
     op: "clear";
   };
   
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: NamedObject | null;                  // Contact object ({ name?, tags?, onChain?, replaceExistName? })
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, NamedObject, AccountOrMark_Address, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, TypedPermissionObject, CoinParam, NamedObject, PaymentInfo, AccountOrMark_Address, AmountFromDepositGuard, AmountFromWithdrawGuard, ReceivedBalanceOrRecently, ReceivedObjectsOrRecently.

package/schemas/schema-messenger_operation.md

@@ -8,7 +8,7 @@
 
 ```typescript
 MessengerOperation {
-  operation: string;            // One of 15 operation types (see below)
+  operation: string;            // One of 16 operation types (see below)
   // Operation-specific fields
   ...
 }

package/schemas/schema-query_toolkit.md

@@ -2,7 +2,7 @@
 
 > WOWOK data query toolkit: Query local naming info (accounts, names, Object IDs), and query on-chain WOWOK objects, received tokens, user profile, etc.
 >
-> **LOCAL** (device-only, never on-chain): `local_mark_list` | `account_list` | `local_info_list` | `token_list` | `account_balance`
+> **LOCAL** (device-only, never on-chain): `local_mark_list` | `account_list` | `local_info_list` | `local_names` | `token_list` | `account_balance`
 >
 > **ONCHAIN** (blockchain): `onchain_personal_profile` | `onchain_objects` | `onchain_received`
 >
@@ -17,9 +17,9 @@
 ```typescript
 // Discriminated union by query_type — exactly ONE query per call
 QueryToolkit = {
-  query_type: "local_mark_list" | "account_list" | "local_info_list" | "token_list" |
-              "account_balance" | "onchain_personal_profile" | "onchain_objects" |
-              "onchain_received";
+  query_type: "local_mark_list" | "account_list" | "local_info_list" | "local_names" |
+              "token_list" | "account_balance" | "onchain_personal_profile" |
+              "onchain_objects" | "onchain_received";
   // ... query-specific parameters (see below)
 }
 ```
@@ -150,7 +150,29 @@ InfoData {
 
 ---
 
-### 4. token_list
+### 4. local_names
+
+Batch reverse lookup — query local names by a list of addresses.
+
+```typescript
+{
+  query_type: "local_names";
+  addresses: string[];          // Array of account addresses (0x...) to look up
+}
+```
+
+**Result**: `{ address: string; name?: string }[]`
+
+```typescript
+{
+  address: string;              // The queried address
+  name?: string;                // Local name assigned to this address, undefined if none
+}
+```
+
+---
+
+### 5. token_list
 
 Query cached token metadata — symbol, decimals, icon URL, description.
 
@@ -161,12 +183,9 @@ Query cached token metadata — symbol, decimals, icon URL, description.
 }
 
 TokenDataFilter {
+  alias_or_name?: string;       // Filter by alias or name (max 64 bcs characters)
+  symbol?: string;              // Filter by symbol
   type?: string;                // Filter by token type (e.g., "0x2::wow::WOW")
-  alias?: string;               // Filter by alias
-  name?: string;                // Filter by name (fuzzy)
-  symbol?: string;              // Filter by symbol (fuzzy)
-  decimals?: number;            // Filter by decimals
-  iconUrl?: string;             // Filter by icon URL
 }
 ```
 
@@ -179,14 +198,15 @@ TokenTypeInfo {
   name: string;
   symbol: string;
   decimals: number;
-  iconUrl?: string;
-  description?: string;
+  description: string;          // Token description (required)
+  iconUrl?: string | null;      // URL for the token logo (may be null)
+  id?: string | null;           // Object ID for the CoinMetadata object (may be null)
 }
 ```
 
 ---
 
-### 5. account_balance
+### 6. account_balance
 
 Query an account's coin balance OR paginated coin objects.
 
@@ -242,7 +262,7 @@ CoinStruct {
 
 ---
 
-### 6. onchain_personal_profile
+### 7. onchain_personal_profile
 
 Query any user's PUBLIC on-chain profile — social links, reputation, personal info, voting history, referrer.
 
@@ -290,7 +310,7 @@ PersonalVote {
 
 ---
 
-### 7. onchain_objects
+### 8. onchain_objects
 
 Batch query on-chain WOWOK objects by ID — supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more.
 
@@ -318,7 +338,7 @@ ObjectBase {
 
 ---
 
-### 8. onchain_received
+### 9. onchain_received
 
 Query objects (payments, tokens, NFTs) received by an on-chain object.
 
@@ -368,7 +388,7 @@ WatchQueryOperationsResult {
 }
 ```
 
-The output schema validates all 8 query types with their specific return types. Each query's `result` field is strictly typed:
+The output schema validates all 9 query types with their specific return types. Each query's `result` field is strictly typed:
 - Local queries return arrays (`MarkData[]`, `AccountData[]`, `InfoData[]`, `TokenTypeInfo[]`)
 - `account_balance` returns `{ address, balance? | coin? }`
 - Onchain queries return `ObjectType | undefined` or `{ objects: ObjectBase[] }`