@wowok/skills 1.0.6 → 1.1.0

package/README.md

@@ -15,7 +15,7 @@ WoWok Skills provide structured guidance for AI assistants to effectively use Wo
 Each skill is a `SKILL.md` file with YAML frontmatter. Claude Code discovers them from `~/.claude/skills/` at session start:
 
 ```
-npm install -g wowok-skills
+npm install -g @wowok/skills
        │
        └── postinstall ──→ Copies 6 SKILL.md to ~/.claude/skills/wowok-*/
                             AI discovers them on next session ✅
@@ -39,7 +39,7 @@ Setup WoWok Agent (MCP Server) in your Claude Code MCP configuration:
   "mcpServers": {
     "wowok": {
       "command": "npx",
-      "args": ["-y", "wowok_agent"]
+      "args": ["-y", "@wowok/agent-mcp"]
     }
   }
 }
@@ -50,7 +50,7 @@ See [WoWok Agent](https://github.com/wowok-ai/agent) for more details.
 ### 2. Install (Personal)
 
 ```bash
-npm install -g wowok-skills
+npm install -g @wowok/skills
 ```
 
 This automatically installs all 6 skills to `~/.claude/skills/`. They will be available in your next Claude Code session.
@@ -58,7 +58,7 @@ This automatically installs all 6 skills to `~/.claude/skills/`. They will be av
 ### 3. Install (Project — Team Sharing)
 
 ```bash
-npm install -g wowok-skills
+npm install -g @wowok/skills
 cd your-project
 wowok-skills init
 ```
@@ -74,7 +74,7 @@ This copies skills to `.claude/skills/` in your project. Commit to git for team
 rm -rf ~/.claude/skills/wowok-guard
 
 # Re-enable it:
-npm install -g wowok-skills
+npm install -g @wowok/skills
 ```
 
 ### Check What's Installed
@@ -87,14 +87,14 @@ wowok-skills get wowok-build
 ### Update
 
 ```bash
-npm update -g wowok-skills
+npm update -g @wowok/skills
 ```
 
 ### Uninstall
 
 ```bash
 # Remove from personal scope:
-npm uninstall -g wowok-skills
+npm uninstall -g @wowok/skills
 
 # Remove from project scope:
 cd your-project
@@ -110,12 +110,12 @@ wowok-skills uninit
 | `wowok-skills init` | Project | Install skills to `.claude/skills/` |
 | `wowok-skills uninit` | Project | Remove skills from `.claude/skills/` |
 
-> **Note**: `init` / `uninit` require `wowok-skills` to be globally installed first.
+> **Note**: `init` / `uninit` require `@wowok/skills` to be globally installed first.
 
 ## Programmatic API
 
 ```typescript
-import { getSkills, getSkillByName } from 'wowok-skills';
+import { getSkills, getSkillByName } from '@wowok/skills';
 
 const skills = getSkills();
 const buildSkill = getSkillByName('wowok-build');
@@ -134,7 +134,7 @@ const buildSkill = getSkillByName('wowok-build');
 
 ## Related Projects
 
-- **WoWok Agent (MCP Server)**: [https://github.com/wowok-ai/agent](https://github.com/wowok-ai/agent) — npm: `wowok_agent`
+- **WoWok Agent (MCP Server)**: [https://github.com/wowok-ai/agent](https://github.com/wowok-ai/agent) — npm: `@wowok/agent-mcp`
 - **WoWok Documentation**: [https://github.com/wowok-ai/docs](https://github.com/wowok-ai/docs)
 
 ## Development
@@ -152,5 +152,5 @@ Apache-2.0
 ## Links
 
 - GitHub: [https://github.com/wowok-ai/skills](https://github.com/wowok-ai/skills)
-- npm: [https://www.npmjs.com/package/wowok-skills](https://www.npmjs.com/package/wowok-skills)
+- npm: [https://www.npmjs.com/package/@wowok/skills](https://www.npmjs.com/package/@wowok/skills)
 - X: [https://x.com/Wowok_Ai](https://x.com/Wowok_Ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/schemas/onchain_operations/_common.md

@@ -1,31 +1,9 @@
-# onchain_operations / Common Types
+# onchain_operations / Common Schemas
 
-Shared types referenced by all `onchain_operations` operation types.
+Shared type definitions referenced by all `onchain_operations` operation types. For design principles, execution rules, Guard submission workflow, and Value Types, see [_index.md](./_index.md).
 
 ---
 
-## 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 |
-
 ## CallEnv
 
 ```typescript
@@ -65,32 +43,27 @@ SubmissionCall {
 
 ## Common Sub-Schemas
 
-### TypedPermissionObject
+### NamedObject
 
 ```typescript
-TypedPermissionObject = 
-  | string                          // Object ID or name (existing)
-  | {
-      name?: string;                // Name for new object
-      tags?: string[];              // Tags for discoverability
-      onChain?: boolean;            // Register name on-chain
-      replaceExistName?: boolean;   // Force claim existing name
-      type_parameter: string;       // Token type parameter (default: "0x2::wow::WOW")
-      permission?: DescriptionObject;  // Permission for the new object
-    };
+NamedObject {
+  name?: string;            // Object name (max 64 bcs chars, must not start with '0x')
+  tags?: string[];           // Tags for discoverability
+  onChain?: boolean;         // Register name on-chain (public)
+  replaceExistName?: boolean; // Force claim existing name
+}
 ```
 
-### WithPermissionObject
+### NormalObject
 
 ```typescript
-WithPermissionObject = 
+NormalObject = 
   | string                           // Existing object ID or name
   | {
       name?: string;
       tags?: string[];
       onChain?: boolean;
       replaceExistName?: boolean;
-      permission?: DescriptionObject;
     };
 ```
 
@@ -108,28 +81,61 @@ DescriptionObject =
     };
 ```
 
-### NormalObject
+### TypeNamedObject
 
 ```typescript
-NormalObject = 
+TypeNamedObject = 
   | string                           // Existing object ID or name
   | {
       name?: string;
       tags?: string[];
       onChain?: boolean;
       replaceExistName?: boolean;
+      type_parameter?: string;           // Token type (default: "0x2::wow::WOW")
     };
 ```
 
-### NamedObject
+### WithPermissionObject
 
 ```typescript
-NamedObject {
-  name?: string;
-  tags?: string[];
-  onChain?: boolean;
-  replaceExistName?: boolean;
-}
+WithPermissionObject = 
+  | string                           // Existing object ID or name
+  | {
+      name?: string;
+      tags?: string[];
+      onChain?: boolean;
+      replaceExistName?: boolean;
+      permission?: DescriptionObject;
+    };
+```
+
+### TypedPermissionObject
+
+```typescript
+TypedPermissionObject = 
+  | string                          // Object ID or name (existing)
+  | {
+      name?: string;                // Name for new object
+      tags?: string[];              // Tags for discoverability
+      onChain?: boolean;            // Register name on-chain
+      replaceExistName?: boolean;   // Force claim existing name
+      type_parameter: string;       // Token type parameter (default: "0x2::wow::WOW")
+      permission?: DescriptionObject;  // Permission for the new object
+    };
+```
+
+### TypedDescriptionObject
+
+```typescript
+TypedDescriptionObject = 
+  | string                           // Existing object ID or name
+  | {
+      name?: string;
+      tags?: string[];
+      onChain?: boolean;
+      replaceExistName?: boolean;
+      type_parameter?: string;           // Token type (default: "0x2::wow::WOW")
+    };
 ```
 
 ### CoinParam
@@ -143,30 +149,209 @@ CoinParam =
 ### ObjectsOp
 
 ```typescript
-ObjectsOp = {
-  op: "add" | "set" | "remove";
-  objects: string[];
-} | {
-  op: "clear";
-};
+ObjectsOp = 
+  | {
+      op: "add" | "set";
+      objects: string[];             // List of object IDs or names
+    }
+  | {
+      op: "remove";
+      objects: string[];             // List of object IDs or names to remove
+    }
+  | {
+      op: "clear";
+    };
 ```
 
 ### AccountOrMark_Address
 
 ```typescript
-AccountOrMark_Address = {
-  name_or_address?: string;
-  local_mark_first?: boolean;
-};
+AccountOrMark_Address {
+  name_or_address?: string;       // Account name, address (0x...), or mark name
+  local_mark_first?: boolean;     // Prioritize local marks first
+}
 ```
 
 ### ManyAccountOrMark_Address
 
 ```typescript
-ManyAccountOrMark_Address = {
-  entities: AccountOrMark_Address[];
-  check_all_founded?: boolean;
-};
+ManyAccountOrMark_Address {
+  entities: AccountOrMark_Address[];  // Batch of account/address lookups
+  check_all_founded?: boolean;        // Abort if any ID not found
+}
+```
+
+### GuardTableItem
+
+```typescript
+GuardTableItem {
+  identifier: number;             // 0-255
+  b_submission: boolean;          // Whether user submission is required
+  value_type: ValueType;          // Expected type
+  value?: SupportedValue;         // Default value (if b_submission=false)
+  name: string;                   // Description (default: "")
+}
+
+// Note: GuardTableItem may also include:
+//   object_type?: ObjectType;    // Object type when value is Address
+```
+
+### Recipient
+
+```typescript
+Recipient = 
+  | { GuardIdentifier: number }           // Get recipient from Guard table index
+  | { Entity: AccountOrMark_Address }     // Explicit entity ID
+  | { Signer: "signer" };                 // Current transaction signer
+```
+
+### Amount
+
+```typescript
+Amount = 
+  | {
+      type: "GuardU64Identifier";
+      value: number;              // Guard table identifier (0-255) for u64 amount
+    }
+  | {
+      type: "Fixed";
+      value: string | number;     // Fixed amount value
+    };
+```
+
+### PaymentInfo
+
+```typescript
+PaymentInfo {
+  for_object?: string | null;     // Payment for a specific object ID
+  for_guard?: string | null;      // Payment to satisfy Guard verification
+  remark: string;                 // Payment record remark
+  index: string | number;         // Payment record index
+}
+```
+
+### ServiceSale
+
+```typescript
+ServiceSale {
+  name: string;                   // Product or service name (max 256 bcs chars)
+  price: string | number;         // Price
+  stock: string | number;         // Stock quantity
+  suspension: boolean;            // Whether suspended
+  wip: string;                    // HTTP URL of WIP file
+  wip_hash: string;               // WIP file hash (empty = auto-use WIP hash)
+}
+```
+
+### ServiceBuyItem
+
+```typescript
+ServiceBuyItem {
+  name: string;                   // Product or service name (max 256 bcs chars)
+  stock: string | number;         // Quantity to purchase
+  wip_hash: string;               // WIP file hash of the item
+}
+```
+
+### Discount
+
+```typescript
+Discount {
+  name: string;                       // Discount name
+  discount_type: 0 | 1;               // 0 = RATES (percentage), 1 = FIXED
+  discount_value: string | number;    // Discount value
+  benchmark?: number | string;        // Minimum amount for discount to apply
+  time_ms_start?: number;             // Start time (milliseconds)
+  time_ms_end?: number;               // End time (milliseconds)
+  count?: number;                     // Usage count limit
+  recipient: ManyAccountOrMark_Address; // Recipient specification
+  transferable?: boolean;             // Whether recipient can transfer
+}
+```
+
+### ServiceGuard
+
+```typescript
+ServiceGuard {
+  guard: string;                                  // Guard object ID
+  service_identifier?: number | null;              // Guard table identifier for service (0-255)
+}
+```
+
+### RewardGuard
+
+```typescript
+RewardGuard {
+  guard: string;                              // Guard object ID or name
+  recipient: Recipient;                       // Who receives the reward
+  amount: Amount;                             // Reward amount
+  expiration_time?: number;                   // Expiration time (ms, >= 1 ms)
+  store_from_id?: number | null;              // Guard table index for record storage (0-255)
+}
+```
+
+### AmountFromDepositGuard
+
+```typescript
+AmountFromDepositGuard {
+  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
+}
+```
+
+### AmountFromWithdrawGuard
+
+```typescript
+AmountFromWithdrawGuard {
+  guard: string;                      // Guard object ID or name
+  identifier: number;                 // Guard table index for withdrawable amount
+  store_from_id?: number | null;      // Guard table index for record storage
+}
+```
+
+### VotingGuard / VoteWeight
+
+```typescript
+VoteWeight = 
+  | { GuardIdentifier: number }           // Voting weight from Guard table index
+  | { FixedValue: number };               // Fixed voting weight (0-65535)
+
+VotingGuard {
+  guard: string;                    // Voting Guard object ID
+  vote_weight: VoteWeight;          // Voting weight configuration
+}
+```
+
+### AllocationSharing
+
+```typescript
+AllocationSharing {
+  who: Recipient;                   // Recipient specification
+  sharing: string | number;         // Allocation amount or rate
+  mode: "Amount" | "Rate" | "Surplus"; // Allocation mode
+}
+```
+
+### Allocator
+
+```typescript
+Allocator {
+  guard: string;                        // Guard object ID — allocation triggers on verify
+  sharing: AllocationSharing[];         // Fund allocation items
+  fix?: string | number;                // Fixed amount per recipient
+  max?: string | number | null;         // Maximum allocation amount
+}
+```
+
+### Allocators
+
+```typescript
+Allocators {
+  description: string;              // Allocator list description (max 4000 bcs chars)
+  threshold: string | number;       // Trigger threshold
+  allocators: Allocator[];          // Fund allocator list
+}
 ```
 
 ### ReceivedBalanceOrRecently
@@ -175,11 +360,11 @@ ManyAccountOrMark_Address = {
 ReceivedBalanceOrRecently = 
   | {
       balance: string | number;  // Balance amount
-      token_type: string;        // Token type
-      received: {                // Unwrapped coin objects
-        id: string;              // CoinWrapper object ID
+      token_type: string;        // Token type (e.g., "CoinWrapper<0x2::wow::WOW>")
+      received: {
+        id: string;              // Received CoinWrapper object ID
         balance: string | number; // Amount
-        payment: string;         // Info string, usually the payment object ID @any
+        payment: string;         // Payment object ID
       }[];
     }
   | "recently";                  // Shortcut: automatically unwrap most recently received CoinWrapper
@@ -194,43 +379,28 @@ ReceivedObjectsOrRecently =
       type: string;              // Object type
       content_raw?: any;         // Raw content (optional)
     }[]
-  | ReceivedBalanceOrRecently;   // Or: empty/clear then receive CoinWrapper objects
+  | {
+      balance: string | number;
+      token_type: string;
+      received: { id: string; balance: string | number; payment: string; }[];
+    }
+  | "recently";
 ```
 
----
-
-## Value 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 |
-
----
-
-### Recipient
-Used by `service` (order allocators), `reward` (guard recipients), and `allocation` (who field).
+### QueryReceivedResult
 
 ```typescript
-Recipient =
-  | { GuardIdentifier: number }
-  | { Entity: AccountOrMark_Address }
-  | { Signer: "signer" }
+QueryReceivedResult {
+  result: 
+    | {
+        balance: string | number;
+        token_type: string;
+        received: { id: string; balance: string | number; payment: string; }[];
+      }
+    | {
+        id: string;
+        type: string;
+        content_raw?: any;
+      }[];
+}
 ```