@wowok/skills 1.0.6 → 1.1.0

package/schemas/onchain_operations/guard.md

@@ -2,135 +2,55 @@
 
 Create immutable programmable validation rules that return boolean results.
 
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Guard is **CREATE-only** and immutable. No `object` field — use `namedNew` for naming.
+
 ## Data Schema
 
 ```typescript
 CallGuard_Data {
-  namedNew?: NamedObject;           // Name for new Guard
-  description?: string;             // Guard description
+  namedNew?: NamedObject;             // Name for new Guard (optional naming)
+  description?: string;               // Guard description (max 4000 bcs chars)
   
-  // Data table definitions
+  // Data table definitions (uses GuardTableItemBaseSchema — no object_type field)
   table?: {
-    identifier: number;             // 0-255
-    b_submission: boolean;          // User submission required
-    value_type: ValueType;          // Expected type
-    value?: SupportedValue;         // Default value (if b_submission=false)
-    name?: string;                  // Description
+    identifier: number;               // 0-255
+    b_submission: boolean;            // User submission required
+    value_type: ValueType;            // Expected type
+    value?: SupportedValue;           // Default value (if b_submission=false)
+    name?: string;                    // Description (default: "")
   }[];
   
   // Rule tree root (required)
   root: {
     type: "node";
-    node: GuardNode;                // Direct node tree
+    node: GuardNode;                  // Direct node tree
   } | {
     type: "file";
-    file_path: string;              // Load from file
-    format?: "json" | "markdown";
+    file_path: string;                // Path to JSON or Markdown file
+    format?: "json" | "markdown";     // File format (default: "json")
   };
   
   // Dependent Guards
   rely?: {
-    guards: string[];
-    logic_or?: boolean;             // OR vs AND logic
+    guards: string[];                 // Dependent Guard object IDs
+    logic_or?: boolean;               // OR logic (default: AND)
   };
 }
-
-// GuardNode (recursive structure)
-//
-// The GuardNode is a recursive, strongly-typed computational tree.
-// Each node has a `type` field that discriminates its behavior.
-// Below are the major categories:
-//
-// Logic & Comparison:
-//   logic_and (nodes[], 2-8) → Bool: ALL must be true
-//   logic_or (nodes[], 2-8) → Bool: ANY must be true
-//   logic_not (node, 1) → Bool: Inverts boolean
-//   logic_equal (nodes[], 2-8) → Bool: Type+value equality
-//   logic_string_contains (nodes[], 2-8) → Bool: Substring (case-sensitive)
-//   logic_string_nocase_contains (nodes[], 2-8) → Bool: Substring (case-insensitive)
-//   logic_string_nocase_equal (nodes[], 2-8) → Bool: String equality (ci)
-//   logic_as_u256_equal (nodes[], 2-8) → Bool: Numeric equality
-//   logic_as_u256_greater (nodes[], 2-8) → Bool: First > all others
-//   logic_as_u256_lesser (nodes[], 2-8) → Bool: First < all others
-//   logic_as_u256_greater_or_equal (nodes[], 2-8) → Bool: First >= all others
-//   logic_as_u256_lesser_or_equal (nodes[], 2-8) → Bool: First <= all others
-//
-// Arithmetic (calc_*):
-//   calc_number_add (nodes[], 2-8) → U256: Sequential addition
-//   calc_number_subtract (nodes[], 2-8) → U256: Sequential subtraction
-//   calc_number_multiply (nodes[], 2-8) → U256: Sequential multiplication
-//   calc_number_divide (nodes[], 2-8) → U256: Sequential division
-//   calc_number_mod (nodes[], 2-8) → U256: Sequential modulo
-//   calc_string_length (node, 1) → U64: UTF-8 byte length
-//   calc_string_contains (nodes[], 2-8) → Bool: cs substring check
-//   calc_string_nocase_contains (nodes[], 2-8) → Bool: ci substring check
-//   calc_string_nocase_equal (nodes[], 2-8) → Bool: ci string equality
-//   calc_string_indexof (left+right+order) → U64: Find substring index
-//   calc_string_nocase_indexof (left+right+order) → U64: Find substring index (ci)
-//
-// Type Conversion (convert_*):
-//   convert_number_address (node, 1) → Address: Number → Address
-//   convert_address_number (node, 1) → U256: Address → Number
-//   convert_number_string (node, 1) → String: Number → String
-//   convert_string_number (node, 1) → U256: Parse string as number
-//   convert_safe_u8..convert_safe_u256 (node, 1) → U8..U256: Safe numeric cast
-//
-// Vector Operations (vec_*):
-//   vec_length (node, 1) → U64: Element count
-//   vec_contains_bool (nodes[], 2-8) → Bool: All values present
-//   vec_contains_address (nodes[], 2-8) → Bool: Address containment
-//   vec_contains_string (nodes[], 2-8) → Bool: String containment (cs)
-//   vec_contains_string_nocase (nodes[], 2-8) → Bool: String containment (ci)
-//   vec_contains_number (nodes[], 2-8) → Bool: Number containment
-//   vec_indexof_* (left+right+order) → U64: Find index in vector
-//
-// WoWok Object Query:
-//   query (query + object + parameters) → varies: Query on-chain data
-//   identifier (identifier 0-255) → varies: Read from Guard table
-//   value_type (node, 1) → U8: Get ValueType of child result
-//
-// Record Check Operations (record_*):
-//   record_check_recipient_order (...) → Bool: Order count by recipient
-//   record_check_recipient_progress (...) → Bool: Progress count by recipient
-//   record_check_recipient_reward (...) → Bool: Reward count by recipient
-//   record_check_treasury_history_item (...) → Bool: Treasury history
-//   record_check_progress_history_item (...) → Bool: Progress history
-//
-// For the complete canonical list of all 70+ types, see
-// the MCP source at `src/schema/query/index.ts` `GuardNodeSchema`.
-GuardNode = {
-  // Multi-operand nodes (2-8 children)
-  logic?: "and" | "or";
-  nodes: GuardNode[];
-} | {
-  // Single-operand nodes
-  logic?: "not";
-  node: GuardNode;
-} | {
-  // Query nodes
-  type: "query";
-  query: number | string;
-  object: {
-    identifier: number;
-    convert_witness?: number;
-  };
-  parameters: GuardNode[];
-} | {
-  // Context nodes
-  type: "context";
-  context: "Signer" | "Clock" | "Guard";
-} | {
-  // Identifier nodes
-  type: "identifier";
-  identifier: number;
-} | {
-  // Constant value nodes
-  type: "constant";
-  value_type: ValueType;
-  value: SupportedValue;
-}
 ```
 
+## Guard Root Notes
+
+- **`root.type === "node"`**: Build the Guard computational tree directly inline using `node: GuardNode`
+- **`root.type === "file"`**: Load the Guard definition from a JSON or Markdown file. The file can define `namedNew`, `description`, `table`, `root`, `rely`. Any fields defined in the schema will **OVERRIDE** the corresponding fields in the file.
+
+## GuardNode (recursive, lazy-evaluated)
+
+The GuardNode is a recursive, strongly-typed computational tree with 70+ node types.
+Each node has a `type` field that discriminates its behavior.
+
+For the complete canonical list of all GuardNode types, see the MCP source at `src/schema/query/index.ts` `GuardNodeSchema`.
+
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, NamedObject.
+See [_common.md](./_common.md) for shared types: CallEnv, NamedObject.

package/schemas/onchain_operations/machine.md

@@ -2,69 +2,88 @@
 
 Design and deploy automated workflow templates (Machines) that define how services are delivered.
 
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Machine uses `WithPermissionObject`: object shape = CREATE, string = MODIFY.
+
 ## Data Schema
 
 ```typescript
 CallMachine_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: WithPermissionObject
   object: WithPermissionObject;
   
   // Generate new Progress
   progress_new?: {
-    task?: string | null;           // Task ID
-    repository?: ObjectsOp;         // Repository list
-    progress_namedOperator?: {      // Manage namespace operators
+    task?: string | null;             // Task ID bound to Progress
+    repository?: ObjectsOp;           // Repository list
+    progress_namedOperator?: {        // Manage namespace operators
       op: "add" | "set" | "remove";
-      name: string;
+      name: string;                   // Namespace name (non-empty)
       operators: ManyAccountOrMark_Address;
     };
-    namedNew?: NamedObject;         // Name for new Progress
+    namedNew?: NamedObject;           // Name for new Progress
   };
   
-  description?: string;             // Machine description
-  repository?: ObjectsOp;           // Consensus repositories
+  description?: string;               // Machine description
+  repository?: ObjectsOp;             // Consensus repositories
   
   // Node operations - TWO MODES (mutually exclusive)
   node?: 
     // Mode 1: Incremental operations
     | {
         op: "add" | "set";
-        nodes: MachineNode[];
-        bReplace?: boolean;
+        nodes: MachineNode[];         // Node array
+        bReplace?: boolean;           // Whether to replace existing
       }
-    | { op: "remove"; nodes: string[] }
+    | { op: "remove"; nodes: string[] }       // Node names to delete
     | { op: "clear" }
-    | { op: "exchange"; node_one: string; node_other: string }
-    | { op: "rename"; node_name_old: string; node_name_new: string }
-    | { op: "remove prior node"; pairs: NodeRemovePriorNodeData[] }
-    | { op: "add forward"; data: NodeAddForwardData[] }
-    | { op: "remove forward"; data: NodeRemoveForwardData[] }
+    | { op: "exchange"; node_one: string; node_other: string } // Swap two nodes
+    | { op: "rename"; node_name_old: string; node_name_new: string } // Rename node
+    | { op: "remove prior node"; pairs: { prior_node_name: string[]; node_name: string; }[] } // Delete prev→next pairs
+    | { op: "add forward"; data: {
+        prior_node_name: string;      // Previous node name
+        node_name: string;            // Next node name
+        forward: {
+          name: string;               // Operation name
+          namedOperator?: string | null;     // Per-Progress namespace operator (null or empty "" = order permission)
+          permissionIndex?: number | null;   // Shared permission index
+          weight: number;             // Forward weight (0-65535)
+        }[];
+        threshold?: number | null;    // Weight threshold (int >= 0)
+      }[] }
+    | { op: "remove forward"; data: {
+        prior_node_name: string;
+        node_name: string;
+        forward_name: string[];       // Operation names to delete
+      }[] }
     // Mode 2: Complete replacement from file
     | { json_or_markdown_file: string };
   
-  pause?: boolean;                  // Pause new Progress
-  publish?: boolean;                // Publish (nodes immutable)
+  pause?: boolean;                    // Pause new Progress
+  publish?: boolean;                  // Publish (nodes immutable after)
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: NameOrAddress | null;          // Contact object
 }
 
-// MachineNode definition
+// MachineNode definition (referenced by node operations)
+// For the canonical MachineNodeNodeSchema, see MCP source at src/schema/query
 MachineNode {
-  name: string;                     // Node name (initial is "")
+  name: string;                       // Node name
   pairs: {
-    prior_node: string;             // Previous node ("" for entry)
+    prior_node: string;               // Previous node name ("" for entry)
     forwards: {
-      name: string;                 // Forward name
-      namedOperator?: string;       // Per-Progress namespace
-      permissionIndex?: number;     // Shared permission index
-      weight: number;               // Forward weight
-      guard?: string;               // Optional Guard
+      name: string;                   // Forward name
+      namedOperator?: string;         // Per-Progress namespace
+      permissionIndex?: number;       // Shared permission index
+      weight: number;                 // Forward weight
+      guard?: MachineForwardGuard;    // { guard: string; retained_submission?: number[] }
     }[];
-    threshold?: number;             // Weight threshold
+    threshold?: number;               // Weight threshold (null = any single forward triggers)
   }[];
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, ObjectsOp, NamedObject, ManyAccountOrMark_Address, ReceivedObjectsOrRecently.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, WithPermissionObject, NamedObject, ObjectsOp, ManyAccountOrMark_Address, ReceivedObjectsOrRecently.

package/schemas/onchain_operations/order.md

@@ -1,57 +1,56 @@
 # onchain_operations / order
 
-Manage the order lifecycle, including arbitration, progress advancement, refunds, and setting agents.
+Track and manage service delivery lifecycle — progress, arbitration, compensation.
+
+> **Note**: Order is **MODIFY-only**.
 
 ## Data Schema
 
 ```typescript
 CallOrder_Data {
-  object: string;                   // Order ID or name (required)
+  object: NameOrAddress;                 // Order object ID or name (required)
   
-  // Manage agents
-  agents?: ManyAccountOrMark_Address;
+  agents?: ManyAccountOrMark_Address;   // Order agents (operate, but cannot receive funds)
   
-  // Set required info (Contact or WTS)
-  required_info?: string | null;
+  required_info?: NameOrAddress | null; // Contact object ID (recipient) or WTS Proof (delivery proof)
   
-  // Advance progress
+  // Advance order progress workflow
   progress?: {
     operation: {
-      next_node_name: string;
-      forward: string;
+      next_node_name: string;           // Target node name (max 64 bcs chars)
+      forward: string;                  // Forward (operation) name (max 64 bcs chars)
     };
-    hold?: boolean;
-    adminUnhold?: boolean;
-    message?: string;
+    hold?: boolean;                     // Lock operation permission
+    adminUnhold?: boolean;              // Allow admin to force unlock
+    message?: string;                   // Operation note
   };
   
-  // Submit compensation request
+  // Submit compensation request and apply for arbitration
   arb_confirm?: {
-    arb: string;                    // Arb object ID
-    confirm: boolean;               // Confirm materials valid
-    description?: string;
-    proposition?: string[];         // Compensation claims
+    arb: NameOrAddress;                 // Arb object ID or name
+    confirm: boolean;                   // Confirm arbitration materials are valid
+    description?: string;               // Message description for compensation (max 4000 bcs chars)
+    proposition?: string[];             // Compensation claims (each max 256 bcs chars)
   };
   
-  // Appeal arbitration result
+  // Oppose and appeal arbitration result
   arb_objection?: {
-    arb: string;
-    objection: string;              // Appeal reason
+    arb: NameOrAddress;                 // Arb object ID or name
+    objection: string;                  // Reason for objection (max 4000 bcs chars)
   };
   
-  // Claim compensation
+  // Claim order compensation from adjudicated Arb
   arb_claim_compensation?: {
-    arb: string;
+    arb: NameOrAddress;                 // Arb object ID or name
   };
   
-  // Receive funds/objects
+  // Unwrap received CoinWrappers/objects and transfer to owner
   receive?: QueryReceivedResult;
   
-  // Transfer order ownership
-  transfer_to?: AccountOrMark_Address;
+  transfer_to?: AccountOrMark_Address;  // Transfer order ownership
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, AccountOrMark_Address, ManyAccountOrMark_Address.
+See [_common.md](./_common.md) for shared types: CallEnv, SubmissionCall, ManyAccountOrMark_Address, AccountOrMark_Address, QueryReceivedResult.

package/schemas/onchain_operations/payment.md

@@ -1,32 +1,24 @@
 # onchain_operations / payment
 
-Send instant, irreversible coin transfers to any wallet address.
+Token payment (transfer) operations with detailed remarks.
+
+> **Note**: Payment is **CREATE-only** — it issues immutable payment records. No `submission` field.
 
 ## Data Schema
 
 ```typescript
 CallPayment_Data {
-  // Object reference — create new only (Payment is immutable)
-  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")
-  };
+  object: TypeNamedObject;             // CREATE new payment object with {name, type_parameter?}
   
-  revenue: {                       // Array of payment recipients
-    recipient: AccountOrMark_Address; // Who receives payment
-    amount: CoinParam;             // Payment amount
+  revenue: {
+    recipient: AccountOrMark_Address;  // Payment recipient
+    amount: CoinParam;                 // Payment amount
   }[];
   
-  info: {                          // Payment metadata
-    remark?: string;               // Payment remark
-    index?: number;                // Payment index
-  };
+  info: PaymentInfo;                   // Payment record info
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, CoinParam, AccountOrMark_Address.
+See [_common.md](./_common.md) for shared types: CallEnv, TypeNamedObject, CoinParam, PaymentInfo, AccountOrMark_Address.

package/schemas/onchain_operations/permission.md

@@ -2,24 +2,42 @@
 
 Define who can perform which operations on WoWok objects.
 
+> **CREATE vs MODIFY**: See [_common.md](./_common.md) for the unified pattern.  
+> Permission uses `NormalObject`: object shape = CREATE, string = MODIFY.
+
 ## Data Schema
 
 ```typescript
 CallPermission_Data {
   // Object reference - string (existing) or object (create new)
+  // See _common.md: NormalObject
   object?: NormalObject;
   
-  description?: string;             // Permission description
+  description?: string;               // Permission description (max 4000 bcs chars)
   
-  // Permission table operations
+  // Remark operations (discriminated union)
+  remark?: {
+    op: "set";
+    index: number;                    // Permission index (REQUIRED)
+    remark: string;                   // Permission remark (REQUIRED)
+  } | {
+    op: "remove";
+    index: number;                    // Permission index (REQUIRED)
+  } | {
+    op: "clear";
+  };
+  
+  // Permission table operations (discriminated union)
   table?: {
+    // Permission-centric: assign ONE permission to MANY entities
     op: "add perm by index" | "set perm by index" | "remove perm by index";
-    index: number;                  // Permission index
+    index: number;                    // Permission index
     entity: ManyAccountOrMark_Address;
   } | {
+    // Entity-centric: assign MANY permissions to ONE entity
     op: "add perm by entity" | "set perm by entity" | "remove perm by entity";
     entity: AccountOrMark_Address;
-    index: number[];
+    index: number[];                  // Permission indices
   };
   
   // Advanced entity operations (requires admin)
@@ -32,23 +50,16 @@ CallPermission_Data {
     entity: AccountOrMark_Address;
   };
   
-  // Admin management (builder only)
+  // Admin management (builder/owner only)
   admin?: {
     op: "add" | "remove" | "set";
     addresses: ManyAccountOrMark_Address;
   };
   
-  // Remark operations
-  remark?: {
-    op: "set" | "remove" | "clear";
-    index?: number;
-    remark?: string;
-  };
-  
-  apply?: string[];                 // Objects to apply permission to
-  builder?: AccountOrMark_Address;  // Set/transfer ownership
+  apply?: NameOrAddress[];            // Object IDs to apply permission to
+  builder?: AccountOrMark_Address;    // Set/transfer ownership
   owner_receive?: ReceivedObjectsOrRecently;
-  um?: string | null;               // Contact object
+  um?: string | null;                 // Contact object
 }
 ```
 

package/schemas/onchain_operations/personal.md

@@ -1,59 +1,58 @@
 # onchain_operations / personal
 
-Establish and manage your on-chain public identity. **CRITICAL: Everything here is PERMANENTLY PUBLIC on the blockchain!**
+Manage your personal on-chain account profile and identity marks.
+
+> **Note**: Personal has no `submission` field. There is only one Personal object per account, created automatically on first use.
 
 ## Data Schema
 
 ```typescript
 CallPersonal_Data {
-  description?: string;             // Public description
+  description?: string;                 // Personal description (max 4000 bcs chars)
   
-  referrer?: string | AccountOrMark_Address | null; // Referrer for joining network
+  referrer?: NameOrAddress | null;    // Referrer ID for joining network
   
-  // PUBLIC on-chain personal info (discriminated union)
+  // Public personal info records (discriminated union)
   information?: {
     op: "add";
-    data: {                        // Records to add
-      name: string;                // Record name (social handle, URL, etc.)
-      value_type: ValueType;       // Value type
-      value: SupportedValue;       // Value
-    }[];
+    data: RecordsInEntity[];            // Records to add (PUBLIC: social handles, URLs — NEVER private data)
   } | {
     op: "remove";
-    name: string[];                // Record names to remove
+    name: string[];                     // Record names to remove
   } | {
     op: "clear";
   };
   
-  // PUBLIC on-chain identity mark (discriminated union)
+  // Public on-chain identity mark (discriminated union)
   mark?: {
     op: "add";
     data: {
-      address: string;             // Address to mark
-      name?: string;               // Mark name
-      tags?: string[];             // Tags
+      address: string;                  // Address
+      name?: string;                    // Name (optional)
+      tags?: string[];                  // Tags (optional)
     }[];
   } | {
     op: "remove";
     data: {
-      address: string;
-      tags?: string[];
+      address: string;                  // Address
+      tags?: string[];                  // Tags to remove
     }[];
   } | {
     op: "clear";
-    address: ManyAccountOrMark_Address;
+    address: ManyAccountOrMark_Address; // Addresses to clear
   } | {
-    op: "transfer";                // Transfer mark to another address
-    to: AccountOrMark_Address;
+    op: "transfer";
+    to: string;                         // Transfer mark to another address
   } | {
-    op: "replace";                 // Replace with new mark object
-    new_mark_object: string;
+    op: "replace";
+    new_mark_object: string;            // Replace with new mark object ID
   } | {
-    op: "destroy";                 // Permanently destroy mark
+    op: "destroy";                     // Permanently destroy identity mark
   };
 }
 ```
 
 ---
 
-See [_common.md](./_common.md) for shared types: CallEnv, AccountOrMark_Address, ManyAccountOrMark_Address.
+See [_common.md](./_common.md) for shared types: CallEnv, AccountOrMark_Address, ManyAccountOrMark_Address.  
+`RecordsInEntity` schema is defined in the MCP source at `src/schema/query/index.ts`.

package/schemas/onchain_operations/progress.md

@@ -2,30 +2,33 @@
 
 Track and manage active workflows in real-time.
 
+> **Note**: Progress is **MODIFY-only** — Progress objects are created via `machine.progress_new`, not directly.
+
 ## Data Schema
 
 ```typescript
 CallProgress_Data {
-  object: string;                   // Progress ID or name (required)
-  task?: string | null;             // Target task ID
-  repository?: ObjectsOp;           // Context repositories
+  object: NameOrAddress;              // Progress ID or name (required) — MODIFY only
+  
+  task?: NameOrAddress;                 // Task ID (cannot be changed after setting)
+  repository?: ObjectsOp;             // Context repositories
   
   // Manage namespace operators
   progress_namedOperator?: {
     op: "add" | "set" | "remove";
-    name: string;
+    name: string;                     // Namespace name (non-empty, max 64 bcs chars)
     operators: ManyAccountOrMark_Address;
   };
   
   // Advance workflow
   operate?: {
     operation: {
-      next_node_name: string;       // Target node
-      forward: string;              // Forward name
+      next_node_name: string;         // Target node name (max 64 bcs chars)
+      forward: string;                // Forward (operation) name (max 64 bcs chars)
     };
-    hold?: boolean;                 // Lock permission
-    adminUnhold?: boolean;          // Allow admin unlock
-    message?: string;               // Operation note
+    hold?: boolean;                   // Lock operation permission
+    adminUnhold?: boolean;            // Allow admin to force unlock
+    message?: string;                 // Operation note
   };
 }
 ```