@wowok/skills 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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/wowok-provider/SKILL.md

@@ -25,417 +25,242 @@ Build and operate commercial services on WoWok as a service provider.
 
 > **Role**: Service Provider (Merchant/Seller)  
 > **Prerequisites**: Understand CREATE vs MODIFY pattern — use `schema_query({ action: "get", name: "onchain_operations" })`  
-> **Customer Perspective**: See [wowok-order](../wowok-order/SKILL.md)  
-> **Arbitration**: See [wowok-arbitrator](../wowok-arbitrator/SKILL.md)  
-> **Machine Design**: See [wowok-machine](../wowok-machine/SKILL.md) for workflow details  
-> **Messenger**: See [wowok-messenger](../wowok-messenger/SKILL.md) for customer communication  
-> **Tools**: See [wowok-tools](../wowok-tools/SKILL.md)
+> **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-machine](../wowok-machine/SKILL.md) (workflow), [wowok-messenger](../wowok-messenger/SKILL.md) (communication)
 
 ---
 
-## Core Concepts
+## AI Decision Framework
 
-### Dependency-First Construction
+When user wants to create/publish a service, follow this **strict dependency order**:
 
-Commercial services MUST be built in strict dependency order. An object cannot reference another that does not yet exist.
-
-**Build Sequence**:
 ```
-Permission → Service (unpublished) → Machine (Nodes but unpublished) → Guards → Allocators → Reward/Arbitration → Publish Machine → Bind to Service → Publish Service
+STEP 1: Foundation (CREATE or REUSE)
+├── Permission — REUSE existing if available (strongly recommended)
+├── Service (unpublished) — CREATE new
+└── Machine (unpublished) — CREATE new or REUSE template
+
+STEP 2: Trust Layer (CREATE or REUSE)
+└── Guards — CREATE new or REUSE existing
+
+STEP 3: Business Logic (MODIFY)
+├── Machine — bind Guards to nodes
+├── Service — set Allocators
+├── Service — add Arbitrations (optional, REUSE existing Arb services)
+├── Service — add Compensation Fund (optional)
+└── Reward — incentive pools (optional)
+
+STEP 4: Publication
+├── Publish Machine → IMMUTABLE
+├── Bind Machine to Service
+└── Publish Service → machine/allocators LOCKED
+
+STEP 5: Post-Publish (MODIFY Service)
+├── description, location
+├── sales (products with WIP)
+├── customer_required
+└── um (REUSE existing Contact or CREATE new)
 ```
 
-**Immutability Rules**:
-| Object | When Immutable | Impact |
-|--------|---------------|--------|
-| **Guard** | After creation | CREATE-only, cannot modify |
-| **Machine** | After `publish: true` | Nodes locked, workflow frozen |
-| **Service** | After `publish: true` | `machine` and `order_allocators` locked |
-
-### CREATE vs MODIFY Pattern
+### Object Reuse (See [wowok-safety](../wowok-safety/SKILL.md))
 
-The unified pattern across all operations:
-- **Object shape** (`{ name?, ... }`) = **CREATE** new object
-- **String value** (`"<name>"`) = **MODIFY** existing object
+**General Rule**: Reuse existing objects when available. See wowok-safety for detailed reuse principles and CREATE vs MODIFY patterns.
 
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations" })`
-
-### Key Object Relationships
-
-```
-Service (merchant storefront)
-├── machine → Machine (workflow definition)
-├── order_allocators → Allocators (fund distribution rules)
-├── arbitrations → Arbitration[] (dispute resolution options)
-├── compensation_fund → Customer protection pool
-├── sales → SalesItem[] (products with WIP files)
-├── discount → Discount[] (coupons)
-├── rewards → Reward[] (order/user behavior incentives)
-└── um → Contact (customer service)
+**Provider-Specific Reuse Notes**:
+| Object | Reuse Strategy |
+|--------|----------------|
+| **Permission** | **Strongly recommended** — enables centralized permission control across all your services |
+| Machine | Reuse via `machineNode2file` export/import for similar workflows |
+| Contact (um) | Reuse existing customer service Contact |
+| Arbitration | Always reuse existing Arbitration services (customers choose from your approved list) |
 
-Order (created per purchase)
-├── builder → Customer (order owner)
-├── progress → Progress (workflow state)
-└── allocation → Allocation (fund distribution engine)
-```
+**Immutability Rules**:
+| Object | When Locked | Impact |
+|--------|-------------|--------|
+| Guard | After creation | Cannot modify |
+| Machine | After publish | Nodes frozen |
+| Service | After publish | machine, order_allocators frozen |
 
 ---
 
-## Phase 1: Service Design (Commercial Intent)
-
-Design your service offering before building. This phase defines what customers see and how orders flow.
-
-### 1.1 Product Promise (WIP Files)
-
-WIP (Witness Immutable Promise) files are **immutable product commitments** — your on-chain promise to customers.
-
-**Creating WIP Files**:
-
-**Tool**: `wip_file` with `type: "generate"` operation.
-
-**Schema Reference**: `schema_query({ action: "get", name: "wip_file" })`
-
-**Key Parameters**:
-- `options.markdown_text`: Product description in markdown format
-- `options.images`: Array of image sources for product visuals
-- `outputPath`: Output file path for generated WIP file
-
-**Attaching to Service**:
-
-**Operation**: `onchain_operations` with `operation_type: "service"`.
-
-**Key Fields**:
-- `sales.op`: Operation type ("add", "set", "remove")
-- `sales.sales`: Array of sales items, each with:
-  - `name`: Product name
-  - `price`: Price in token units
-  - `stock`: Available quantity
-  - `wip`: URL to WIP file (your official site, GitHub, etc.)
-  - `wip_hash`: SHA256 hash of WIP file for verification (default: `""`, uses hash embedded in WIP file unless explicitly set for verification)
-
-**Why WIP Matters**:
-- **Immutable commitment**: Hashed and signed on-chain
-- **Arbitration evidence**: Disputes resolved against your WIP claims
-- **Customer trust**: Transparent specifications reduce uncertainty
-- **Legal protection**: Tamper-proof record of promises
-
-### 1.2 Service Workflow (Machine Design)
-
-Machine defines your **service process** — from order creation to completion. Design from a **commercial intent** perspective, not technical implementation.
-
-**Key Design Questions**:
-1. **Service stages**: What are the key milestones? (e.g., confirmed → processing → shipped → delivered)
-2. **Validation points**: Where do you need customer confirmation or external verification?
-3. **Branching paths**: What happens on success vs. failure? (e.g., on-time vs. late delivery)
-4. **Fund release triggers**: At which nodes and how to allocate order funds?
-
-**Integration with Allocators**:
-- Each terminal node should map to an allocator strategy
-- Guards determine which allocator executes
-- Design Machine and Allocators together for coherent fund flow
-
-> **Implementation**: See [wowok-machine](../wowok-machine/SKILL.md) for node definition syntax, Guard conditions, and Forward configurations.
-
-### 1.3 Fund Distribution Strategy (Allocators)
-
-Allocators define **who gets what** under different outcomes. Design these alongside your Machine workflow.
-
-**Allocator + Machine Integration**:
-```
-"delivered" → "order_complete" (threshold: 1)
-└── Forward: "customer_signed" (weight: 1)
-└── Allocator: "completed" → 95% merchant, 5% platform
-
-"delivered" → "package_lost" (threshold: 2)
-├── Forward: "customer_reports_lost" (weight: 1)
-├── Forward: "merchant_confirms_lost" (weight: 1)
-└── Allocator: "package_lost" → 100% to order (buyer can withdraw)
-
-Note: Arbitration is an independent action that can be triggered at any time.
-```
-
-**Allocation Modes** (3 types, executed in order):
-1. **Amount**: Fixed allocation amount (U64) for each recipient
-2. **Rate**: Percentage in basis points (10000 = 100%, 500 = 5%)
-   - If no Surplus defined, sum of all Rates must equal 10000 (100%)
-3. **Surplus**: Receives remaining funds (maximum one per allocator)
-
-**How Allocation Executes**:
-- When an allocator Guard returns `true`, funds are distributed immediately per that allocator's `sharing` rules. If multiple Guards may evaluate to `true`, query and compare their validation logic and `sharing` rules to determine the most favorable outcome for your interests.
-
-**Query Guard Logic**: Use `query_toolkit` with `query_type: "onchain_objects"` to query Guard objects by ID or name. Retrieve detailed validation logic including required node conditions, evidence submissions, and permission checks.
-
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_service" })` — look for `order_allocators` field
+## Service Build Checklist
+
+Use this checklist when guiding users through service creation:
+
+| Phase | Step | Required | Tool/Operation | Key Fields |
+|-------|------|----------|----------------|------------|
+| 1 | Permission | ✅ | `onchain_operations` (permission) | name, type_parameter |
+| 1 | Service (unpublished) | ✅ | `onchain_operations` (service) | object: {name, type_parameter, permission} |
+| 1 | Machine (unpublished) | ✅ | `onchain_operations` (machine) | nodes, pairs, forwards |
+| 2 | Guards | ✅ | `onchain_operations` (guard) | logic, instructions |
+| 3 | Machine + Guards | ✅ | `onchain_operations` (machine) | bind guards to forwards |
+| 3 | Allocators | ✅ | `onchain_operations` (service) | order_allocators |
+| 3 | Arbitrations | ❌ | `onchain_operations` (service) | arbitrations.list |
+| 3 | Compensation Fund | ❌ | `onchain_operations` (service) | compensation_fund_add, setting_locked_time_add |
+| 4 | Publish Machine | ✅ | `onchain_operations` (machine) | publish: true |
+| 4 | Bind Machine | ✅ | `onchain_operations` (service) | machine: "<machine_id>" |
+| 4 | Publish Service | ✅ | `onchain_operations` (service) | publish: true |
+| 5 | Description/Location | ❌ | `onchain_operations` (service) | description, location |
+| 5 | Sales Products | ❌ | `onchain_operations` (service) | sales.sales[] |
+| 5 | Customer Required | ❌ | `onchain_operations` (service) | customer_required[], um |
+
+**Critical Rules**:
+1. **Reuse First**: Always ask if user has existing Permission/Machine/Guard/Contact to reuse
+2. If `customer_required` is set → `um` (Contact) **MUST** be set
+3. Physical goods **MUST** have WIP files
+4. `wip_hash` default `""` (uses embedded hash)
 
 ---
 
-## Phase 2: Trust Mechanisms (Customer Confidence)
-
-Configure mechanisms that assure customers they can trust your service.
+## Key Concepts
 
-### 2.1 Compensation Fund (compensation_fund)
+### Service Object Relationships
 
-A **dedicated pool** that pays customers if arbitration rules in their favor. Demonstrates your commitment to fair resolution.
-
-**Setting Up Compensation Fund**:
-
-**Operation**: `onchain_operations` with `operation_type: "service"`.
-
-**Key Fields**:
-- `compensation_fund_add`: Add funds to compensation pool (BalanceType)
-- `setting_locked_time_add`: Lock duration in milliseconds (minimum 30 days = 2592000000ms)
-
-**Merchant Commitment (Constraint)**:
 ```
-Merchant withdrawal constraints from compensation_fund:
-1. Pause Service (stop accepting new orders)
-2. Wait compensation_lock_duration (≥30 days)
-3. Then can withdraw remaining funds via compensation_fund_receive
+Service (merchant storefront)
+├── machine → Machine (workflow)
+├── order_allocators → Fund distribution rules
+├── arbitrations → Dispute resolution (optional)
+├── compensation_fund → Customer protection (optional)
+├── sales → Products with WIP files
+├── rewards → Incentive pools (optional)
+└── um → Contact (customer service)
 
-This commitment ensures existing orders can still claim compensation during the lock period.
+Order (per purchase)
+├── builder → Customer
+├── progress → Workflow state
+└── allocation → Fund distribution engine
 ```
 
-**Customer-Facing Benefits**:
-- Display `compensation_fund` balance in service listing
-- Higher balance + longer lock = more confidence for high-value orders
-- Shows merchant has "skin in the game" for fair resolution
-- Customers can claim compensation via arbitration — see [wowok-order](../wowok-order/SKILL.md) for customer arbitration process
-
-### 2.2 Arbitration Configuration
-
-Configure which arbitration services can resolve disputes for your orders.
-
-**Operation**: `onchain_operations` with `operation_type: "service"`.
-
-**Key Fields**:
-- `arbitrations.op`: Operation type ("add", "set", "remove")
-- `arbitrations.list`: Array of Arbitration object IDs/names
-
-**Why Multiple Arbitrations**:
-- Customers evaluate on-chain data to choose the most trusted Arbitration from your approved list
-- Different arbitrations may specialize (e.g., product quality vs. service delivery)
+### WIP Files (Witness Immutable Promise)
 
----
-
-## Phase 3: Build & Publish
-
-Execute the dependency-first build process.
-
-### 3.1 4-Phase Build Process
+**Purpose**: Immutable product commitment for arbitration evidence.
 
+**Creating WIP**:
 ```
-PHASE 1 — Foundation
-├── 1. Permission (CREATE)
-├── 2. Service (CREATE, unpublished) — define basic info
-└── 3. Machine (CREATE, unpublished) — define ALL nodes and transitions
-
-PHASE 2 — Trust Layer
-└── 4. Guards (CREATE) — schema_query({ action: "get", name: "onchain_operations_guard" }) — validate Reward claims, Allocator conditions, Machine node transitions, etc. Create all Guards needed for your workflow.
-
-PHASE 3 — Business Logic
-├── 5. Machine Node Guards (MODIFY Machine) — bind Guards to Machine node forwards for workflow validation at each operation
-├── 6. Allocators (MODIFY Service) — fund distribution rules
-├── 7. Rewards (CREATE/MODIFY Service) — optional incentive pools
-├── 8. Arbitrations (MODIFY Service) — dispute resolution options
-└── 9. Compensation Fund (MODIFY Service) — add funds
-
-PHASE 4 — Publication
-├── 10. Publish Machine — nodes become IMMUTABLE
-├── 11. Bind Machine to Service — MODIFY Service.machine
-└── 12. Publish Service — everything LOCKED
+Tool: wip_file
+type: "generate"
+options.markdown_text: Product description
+options.images: Product visuals
+outputPath: Output file path
 ```
 
-### 3.2 Pre-Build Discovery
-
-Query existing resources to avoid collisions:
-
-**Tools**:
-- `query_toolkit` with `query_type: "account_list"` — list account objects
-- `query_toolkit` with `query_type: "local_mark_list"` — list local marks
-- `query_toolkit` with `query_type: "onchain_objects"` — query specific objects
-
-### 3.3 Reuse Existing Templates
-
-Export from proven services instead of building from scratch:
-
-**Tools**:
-- `machineNode2file` — export Machine nodes to JSON file for editing
-- `guard2file` — export Guard rules to JSON file for editing
-
-**Schema References**:
-- `schema_query({ action: "get", name: "machineNode2file" })`
-- `schema_query({ action: "get", name: "guard2file" })`
-
----
-
-## Phase 4: Customer Attraction & Incentives
-
-Optional mechanisms to attract and retain customers.
-
-### 4.1 Discount Coupons
-
-Issue promotional discounts to attract new customers or reward loyal ones (AI: query `schema_query` for `onchain_operations_service` to view `discount` field definitions).
-**Operation**: `onchain_operations` with `operation_type: "service"`.
-
-### 4.2 Review & Reward Incentives
-
-Encourage post-order feedback and engagement.
-
-**Design Pattern — Review Incentive**:
+**Attaching to Service**:
 ```
-Machine Workflow:
-"order_completed" → "like" (threshold: 1)
-└── Forward: "positive_feedback" (weight: 1)
-
-"order_completed" → "suggest" (threshold: 1)
-└── Forward: "negative_feedback" (weight: 1)
+Operation: onchain_operations (service)
+sales.op: "add"
+sales.sales: [{
+  name: Product name
+  price: Token amount
+  stock: Quantity
+  wip: URL to WIP file
+  wip_hash: "" (default, uses embedded hash)
+}]
 ```
 
-**Creating Reward Pool**:
-
-**Operation**: `onchain_operations` with `operation_type: "reward"`.
-
-**Example Configuration**:
+### Allocators + Machine Integration
 
-Create 2 Guards that check if Progress reached "like" node, then bind to Reward with different amounts:
+Design together for coherent fund flow:
 
 ```
-Guard 1: "reward_like_200k"
-└── Condition: progress.current_node == "like"
-
-Guard 2: "reward_suggest_100k"  
-└── Condition: progress.current_node == "suggest"
-
-Reward Configuration:
-├── Guard: "reward_like_200k"
-│   └── Amount: 200000
-│
-└── Guard: "reward_suggest_100k"
-    └── Amount: 100000
-```
-
-> **Note**: Reward is an optional advanced feature. See `schema_query({ action: "get", name: "onchain_operations_reward" })` for full configuration.
-
-### 4.3 Supply Chain Promises (Sub-Orders)
-
-Demonstrate quality by committing to purchase from trusted suppliers.
+Example: Delivery workflow
+"delivered" → "order_complete" (threshold: 1)
+└── Forward: "customer_signed"
+└── Allocator: 95% merchant, 5% platform
 
-**Use Case — Travel Service**:
-```
-Travel Service promises:
-"We only book 5-star hotels from trusted hotel groups"
-
-Machine Implementation:
-├── "Book Hotel" Node
-│   └── forward_to_order_create: {
-│       service: "trusted-hotel-group-service",
-│       // Creates sub-order on hotel service
-│   }
-│
-└── Guard: "hotel_booking_confirmed"
-    └── Validates sub-order created and confirmed
+"delivered" → "package_lost" (threshold: 2)
+├── Forward: "customer_reports_lost"
+├── Forward: "merchant_confirms_lost"
+└── Allocator: 100% to order (buyer withdraws)
 ```
 
-**Benefits**:
-- **Transparency & Quality assurance**: Commits you to vetted suppliers
-- **Trust building**: "We use X brand" becomes verifiable on-chain
-
-**Prerequisites**:
-- Supplier Service must be published first
-- Your Machine references their Service ID
+**Allocation Modes** (execute in order):
+1. **Amount**: Fixed U64 per recipient
+2. **Rate**: Basis points (10000 = 100%)
+3. **Surplus**: Receives remainder (max 1 per allocator)
 
 ---
 
-## Phase 5: Order Fulfillment
+## Phase Details
 
-Handle active orders through workflow progression.
+### Phase 1: Foundation
 
-### 5.1 Progress Operations
+Create base objects. Service starts unpublished.
 
-Advance orders through your Machine workflow via the Progress object.
+**Pre-Build Discovery**:
+- `query_toolkit` (account_list) — list accounts
+- `query_toolkit` (local_mark_list) — list marks
+- `query_toolkit` (onchain_objects) — query existing
 
-**Key Principle**:
-| Object | Purpose | Operation Target |
-|--------|---------|------------------|
-| **Order** | Fund escrow, ownership | Read-only for workflow |
-| **Progress** | Workflow state, node execution | **Operate via this** |
+**Reuse Templates**:
+- `machineNode2file` — export Machine for editing
+- `guard2file` — export Guard for editing
 
-**Two-Phase Operation** (recommended):
+### Phase 2: Trust Layer
 
-**Operation**: `onchain_operations` with `operation_type: "progress"`.
+Create all Guards needed for workflow validation.
 
-**Step 1: Lock permission** (Prevents race conditions):
-- `object`: Progress object ID (from Order.progress)
-- `operate.operation`: Target node operation (e.g., `{ Next: "shipped" }`)
-- `operate.hold`: `true` to lock permission
+### Phase 3: Business Logic
 
-**Step 2: Complete off-chain work, then submit**:
-- Same operation with `hold: false` to release lock and submit
+**Compensation Fund** (optional but recommended):
+- `compensation_fund_add`: Add funds
+- `setting_locked_time_add`: Lock duration (min 30 days = 2592000000ms)
 
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_progress" })`
+**Merchant Withdrawal Constraints**:
+1. Pause Service
+2. Wait lock duration
+3. Withdraw via `compensation_fund_receive`
 
-### 5.2 Voluntary Compensation
+**Arbitration** (optional):
+- Without it: Lower setup, but customers bear full dispute risk
+- With it: Customer trust ↑, dispute resolution available
 
-Proactively compensate for service failures to maintain relationships.
+### Phase 4: Publication
 
-**Scenario — Late Delivery**:
-```
-Machine Design:
-├── "Shipping" Node
-│   ├── Forward: "On Time" (normal)
-│   └── Forward: "Late" (penalty trigger)
-│
-└── Guard "late_penalty"
-    ├── IF delivery_time > promised + grace_period
-    ├── THEN require Payment from merchant to Order
-    └── Validate: Payment ≥ configured_penalty
-```
+**Order Matters**: Publish Machine → Bind → Publish Service
 
-**Payment Flow**:
-```
-Merchant or Participant Wallet
-    ├──→ Payment (penalty) ──→ Customer's Order
-    │                              └──→ Customer extracts via receive()
-    └──→ Guard validates before workflow continues
-```
+After publish: machine, order_allocators are **LOCKED**
 
-**Benefits**:
-- Retains customers through proactive accountability
-- Avoids escalation to arbitration
-- Differentiates your service with guarantees
+### Phase 5: Post-Publish Configuration
 
-### 5.3 Customer Service
+These can be updated after publication:
 
-Handle inquiries and issues via Messenger.
+| Field | Purpose | Required |
+|-------|---------|----------|
+| description | Service description | ❌ |
+| location | Service area | ❌ |
+| sales | Products with WIP | ❌ (but needed to sell) |
+| customer_required | Required customer info | ❌ |
+| um | Contact for customer service | ❌ (REQUIRED if customer_required set) |
 
-**Setup**:
+**Customer Required + Contact Rule**:
 ```
-Service.um → Contact.object_id
-Contact.ims[] → Your customer service addresses
+If customer_required: ["phone", "address"]
+Then um: "<contact_id>"  ← MUST be set
 ```
 
-**Best Practices**:
-- Respond promptly to build trust
-- Document all agreements (generates WTS evidence)
-- Confirm understanding explicitly (ARK signature required for evidence)
-- Proactively communicate delays
+**Contact Setup**:
+1. Create Contact object
+2. Set `um` to Contact ID
+3. Customers use Messenger to provide info securely
 
-> **AI reminder**: When fulfilling an order, the AI should proactively check whether the Service's `customer_required` fields (phone, email, delivery address, etc.) have been provided by the customer. If any are missing, prompt the provider to request them from the customer via Messenger using `messenger_operation` with `send_message`.
+---
 
-> **Full Guide**: See [wowok-messenger](../wowok-messenger/SKILL.md) for messaging, WTS generation, and evidence management.
+## Order Fulfillment
 
----
+### Progress Operations
+
+| Object | Purpose | Target |
+|--------|---------|--------|
+| Order | Fund escrow | Read-only |
+| Progress | Workflow state | **Operate this** |
 
-## Best Practices & Common Pitfalls
+**Two-Phase Pattern**:
+1. Lock: `hold: true` (prevents race conditions)
+2. Submit: `hold: false` (after off-chain work)
 
-### Design Principles
+### Customer Service
 
-| Do | Don't |
-|----|-------|
-| Design Machine + Allocators together | Design workflow without considering fund flow |
-| Provide generous compensation_fund | Skip compensation fund for high-value services |
-| Use clear, verifiable Guard conditions | Create ambiguous validation logic |
-| Test on testnet first, then mainnet | Publish to mainnet without testing |
-| Document WIP thoroughly | Make vague product promises |
+**AI Reminder**: When fulfilling orders, check if `customer_required` fields are provided. If missing, prompt provider to request via Messenger.
 
 ---
 
@@ -443,13 +268,20 @@ Contact.ims[] → Your customer service addresses
 
 ### Essential Schemas
 
-| Purpose | Schema Name |
-|---------|-------------|
-| Service operations | `onchain_operations_service` |
-| Machine operations | `onchain_operations_machine` |
-| Guard operations | `onchain_operations_guard` |
-| WIP file generation | `wip_file` |
-| Messenger operations | `messenger_operation` |
-| Query toolkit | `query_toolkit` |
+| Purpose | Schema |
+|---------|--------|
+| Service ops | `onchain_operations_service` |
+| Machine ops | `onchain_operations_machine` |
+| Guard ops | `onchain_operations_guard` |
+| Progress ops | `onchain_operations_progress` |
+| WIP generation | `wip_file` |
+| Messenger | `messenger_operation` |
+| Query | `query_toolkit` |
+
+### Common Operations
 
 **Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
+
+**Export Templates**:
+- `machineNode2file` — Machine → JSON
+- `guard2file` — Guard → JSON

package/wowok-safety/SKILL.md

@@ -19,7 +19,30 @@ always: true
 
 ## 1. Core Principles
 
-### 1.1 Security & Safety
+### 1.1 Object Reuse Principle (General Best Practice)
+
+**ALWAYS prefer reusing existing objects over creating new ones** — this enables centralized permission control and reduces management overhead.
+
+| Object Type | Reuse Strategy | Why |
+|-------------|----------------|-----|
+| **Permission** | **Strongly recommended** — ask user for existing Permission name/ID | Centralized permission control across all services |
+| Machine | Reuse if workflow fits | Save design time for similar processes |
+| Guards | Reuse if validation logic matches | Avoid redundant rules |
+| Contact | Reuse existing customer service Contact | Single point of management |
+| Arbitration | Always reuse existing Arbitration services | Customers choose from established arbiters |
+
+**How to Reuse**:
+- Ask user: *"Do you have an existing object you'd like to reuse? Provide the name or ID."*
+- Use string value `"<name_or_id>"` to reference existing objects
+- Use object shape `{ name?, ... }` only when creating new
+
+**CREATE vs MODIFY Pattern**:
+| Format | Meaning | Use When |
+|--------|---------|----------|
+| String `"<name>"` or `"<0x...>"` | **REUSE** existing | Object already exists |
+| Object `{ name?, ... }` | **CREATE** new | Need new object |
+
+### 1.2 Security & Safety
 
 - **Hot Wallet Usage**: WoWok never exposes private keys. Treat it as a spending account for transfers, receipts, and commerce. Flag large transactions for explicit user confirmation.
 - **Amount-Sensitive Operations**: Any token transfer, payment, or reward distribution MUST be verbally confirmed with the user before execution. Use `Payment` objects for commercial transfers when possible (they offer Guard validation and purpose tracking).

package/wowok-tools/SKILL.md

@@ -42,9 +42,11 @@ Quick reference for WoWok MCP tools — patterns, pitfalls, and troubleshooting.
 
 ### CREATE vs MODIFY Pattern
 
+See [wowok-safety](../wowok-safety/SKILL.md) for complete object reuse principles.
+
 | Format | Meaning | Example |
 |--------|---------|---------|
-| **String** | Reference EXISTING | `"my-service"` or `"0x1234..."` |
+| **String** | Reference EXISTING (reuse) | `"my-service"` or `"0x1234..."` |
 | **Object** | CREATE NEW | `{ name: "my-service", permission: "..." }` |
 
 ---