@wowok/skills 1.0.6 → 1.1.1

package/wowok-safety/SKILL.md

@@ -1,98 +1,49 @@
----
+---
 name: wowok-safety
 description: |
-  WoWok safety and authorization protocol — ensures AI always obtains user
-  confirmation before executing irreversible on-chain operations. Covers
-  amount verification, publish confirmation, critical operation warnings,
-  and the mandatory two-phase submission pattern.
-  
-  This skill is AUTOMATICALLY triggered before any on-chain write operation.
-  It ensures the AI never executes transactions without explicit user approval.
+  WoWok operational safety and best practices — ensures AI follows correct
+  conventions for security, transaction confirmation, object building workflow,
+  and common mistake prevention.
+
+  This skill is AUTOMATICALLY triggered before any on-chain operation.
 when_to_use:
-  - AI is about to execute an onchain_operations call with submission
-  - AI is about to publish a Service or Machine
+  - AI is about to execute an on-chain write operation
   - AI is about to transfer funds or modify financial parameters
-  - AI is about to delete or irreversibly modify on-chain objects
-  - User mentions "confirm", "approve", "safe", "warning"
+  - AI is about to publish a Service or Machine
+  - AI is building multiple interdependent objects
+  - User mentions "confirm", "approve", "safe", "warning", "best practice"
 always: true
 ---
 
-# WoWok Safety & Authorization Protocol
-
-## Core Safety Principle
-
-**NEVER execute an on-chain write without explicit user confirmation.**
-
-WoWok operations involve real blockchain transactions with real economic consequences. The AI MUST always:
-1. Preview what will happen (dry run)
-2. Present the preview clearly to the user
-3. Wait for explicit confirmation
-4. Only then execute
-
-## Mandatory Two-Phase Pattern
-
-### Phase 1: Dry Run (ALWAYS first)
-
-```
-onchain_operations({
-  operation_type: "<type>",
-  data: { op: "<action>", ... }
-  // NO submission field → dry run only
-})
-```
-
-The dry run validates parameters, checks permissions, and returns a preview of what will happen. **No state is changed.**
-
-### Phase 2: Execute (ONLY after user confirms)
-
-```
-onchain_operations({
-  operation_type: "<type>",
-  data: { op: "<action>", ... },
-  submission: {
-    sender: "<account_name>",
-    gas_budget: "<amount>"
-  }
-})
-```
+# WoWok Safety & Best Practices
 
-## Critical Operations Requiring Extra Confirmation
+## 1. Core Principles
 
-### 🔴 HIGH RISK: Financial Operations
+### 1.1 Security & Safety
 
-These operations involve real token transfers and MUST be double-confirmed:
+- **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).
 
-| Operation | Risk | Extra Confirmation Required |
-|-----------|------|---------------------------|
-| `payment` (send coins) | Direct fund transfer | ✅ Show amount, recipient, token type |
-| `treasury` (deposit/withdraw) | Team fund changes | ✅ Show amount, operation type |
-| `reward` (create/modify) | Incentive pool changes | ✅ Show reward rules, amounts |
-| `allocation` (create/modify) | Auto-distribution rules | ✅ Show split percentages, recipients |
-| `order` (create/confirm) | Order with payment | ✅ Show price, service, parties |
+### 1.2 LOCAL vs ON-CHAIN
 
-### 🟡 MEDIUM RISK: Structural Operations
+| Type | Tools | Gas | Confirmation |
+|------|-------|-----|--------------|
+| **LOCAL ONLY** | `account_operation`, `local_mark_operation`, `local_info_operation` | None | Not needed |
+| **ON-CHAIN** | `onchain_operations`, `messenger_operation` (some ops), `wip_file` (sign) | Yes | Required |
+| **QUERY** | `query_toolkit`, `onchain_table_data`, `onchain_events`, `guard2file`, `machineNode2file` | Read-only | Not needed |
+| **ENCRYPTED** | `messenger_operation` (watch/send messages) | Local encryption | Not needed |
 
-These modify system structure and should be confirmed:
+### 1.3 Default Account
 
-| Operation | Risk | Confirmation Required |
-|-----------|------|----------------------|
-| `service` (publish) | Makes service public | ✅ Confirm publish intent |
-| `machine` (publish) | Makes workflow public | ✅ Confirm publish intent |
-| `guard` (create/modify) | Changes validation rules | ✅ Show Guard logic summary |
-| `permission` (modify) | Changes access control | ✅ Show permission changes |
+Empty string `""` means the default account. Always use `""` when the user does not specify an account.
 
-### 🟢 LOW RISK: Read-Only Operations
+---
 
-These are always safe and need no confirmation:
-- All `query_toolkit` operations
-- All `onchain_table_data` operations
-- `wowok_buildin_info`
-- `documents_and_learn`
-- `guard2file`, `machineNode2file` (export only)
+## 2. Transaction Confirmation Protocol
 
-## Confirmation Template
+**Core rule**: NEVER execute an on-chain write without explicit user confirmation.
 
-When presenting a dry-run result for confirmation, ALWAYS use this format:
+### 2.1 Confirmation Template
 
 ```
 📋 **Operation Preview**
@@ -102,280 +53,226 @@ When presenting a dry-run result for confirmation, ALWAYS use this format:
 | Operation | {operation_type} — {op} |
 | Object | {object_name} |
 | Network | {network} |
-| Gas Budget | {estimated_gas} |
+| Account | {account} |
 
 ⚠️ **This will {describe_what_will_happen}**
 
 Proceed with execution?
 ```
 
-## Amount Verification Rules
+### 2.2 Amount Verification
+
+- Always display amounts with token symbol (e.g., "10 WOW" not "10000000000").
+- Query token decimals first if unsure.
 
-When an operation involves token amounts:
+**Tool**: `query_toolkit` with `query_type: "token_list"`.
 
-1. **Always display the amount with token symbol** (not just raw number)
-2. **Query token decimals first** if unsure about precision
-   ```
-   query_toolkit({ query_type: "token_list" })
-   ```
-3. **Show both the raw amount and the human-readable amount**
-4. **For allocations**: Show each recipient's percentage and estimated amount
-5. **For rewards**: Show total pool size and distribution rules
+- **Amounts in operations are ALWAYS submitted as U64 integers**. If the user specifies "2 WOW", do NOT submit the string "2 WOW". Instead, calculate and submit `2000000000` (2 × 10^9, where 9 is WOW's decimals).
+- **Never assume token decimals**. If the token's decimals cannot be queried, HALT the amount submission and alert the user. Do not proceed with hardcoded or guessed precision.
+- Show both raw and human-readable amounts when clarifying with users.
 
-## Publish Confirmation
+### 2.3 Publish Confirmation
 
-Publishing a Service or Machine makes it publicly accessible. Before publishing:
+Before publishing a Service or Machine:
 
-1. **Verify all Guards are correct** — export with `guard2file` and review
-2. **Verify all Machine nodes** — export with `machineNode2file` and review
-3. **Test with dry runs** — simulate operations against the unpublished objects
-4. **Confirm the publish intent** — publishing is irreversible in practice
+1. **Export and review**:
+   - Use `guard2file` to export Guard definitions
+   - Use `machineNode2file` to export Machine nodes
+
+2. **Verify logic**: Confirm Guards and Machine nodes match user intent
+
+3. **Warn about immutability**: Once published, many fields become locked
 
 ```
 ⚠️ PUBLISH CONFIRMATION REQUIRED
 
 You are about to publish:
-- Service: {name} ({id})
+- {Service|Machine}: {name}
 - This will make it publicly accessible on-chain
-- Guard rules: {summary}
-- Machine workflow: {summary} (if applicable)
+- After publish: {list what becomes immutable}
 
 This action cannot be easily undone. Proceed?
 ```
 
-## Account Safety
+---
 
-- **Never create accounts without user request** — `account_operation` with `op: "generate"`
-- **Never share private keys or sensitive data** — these are local-only
-- **Always confirm which account is being used** as the sender for transactions
-- **Check account balance** before operations that require gas
+## 3. Common Mistakes to Avoid
 
-## What the AI MUST Do
+| Mistake | Why It Happens | Prevention |
+|---------|---------------|------------|
+| **Forgetting no_cache** | Cache lag in dependency chain | Set `env.no_cache: true` on all operations when building multiple objects |
+| **Missing permission indices** | Machine forwards reference non-existent indices | Verify Permission object has required indices before creating Machine |
 
-1. ✅ Always dry-run first, show preview
-2. ✅ Always get explicit confirmation before executing
-3. ✅ Always show amounts with token symbols
-4. ✅ Always warn before publishing
-5. ✅ Always confirm the sender account
-6. ✅ Always check for sufficient gas balance
+---
 
-## What the AI MUST NOT Do
+## 4. Naming Conventions
 
-1. ❌ Never execute on-chain writes without user confirmation
-2. ❌ Never skip the dry-run phase
-3. ❌ Never hide or obscure financial amounts
-4. ❌ Never publish without explicit user request
-5. ❌ Never use a different account than what the user specified
-6. ❌ Never proceed if the dry run shows errors
+When users request complex systems without naming, propose this scheme:
 
-## Real-World Safety Patterns (from tested examples)
+```
+<projectPrefix>_<type>_<purpose>_<version>
+```
 
-### Pattern 1: Dry-Run Before Every Structural Change
+| Part | Example | Purpose |
+|------|---------|---------|
+| Project prefix | `shopFunny_` | Prevents cross-project collisions |
+| Type prefix | `machine_`, `guard_`, `service_` | Clarifies object type |
+| Purpose suffix | `serviceWithdraw` | Describes function |
+| Version suffix | `_v2` | Enables iteration |
 
-**From [Insurance](../examples/Insurance/Insurance.md), [Travel](../examples/Travel/Travel.md), [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md)**
+- Always provide `tags` on object creation for filtering and management
+- Use short address form (`0x1234...def`); use names as primary identifiers
 
-Every structural operation in the tested examples follows this exact two-phase pattern:
+### 4.1 `replaceExistName` Flag
 
-```
-// Phase 1: Validate (no submission → no state change)
-onchain_operations({
-  operation_type: "<type>",
-  data: { ... },
-  env: { account: "<name>", network: "testnet" }
-})
-→ Review the returned preview. Check: object IDs, guard logic, amounts.
-
-// Phase 2: Execute (only after user confirms)
-onchain_operations({
-  operation_type: "<type>",
-  data: { ... },
-  env: { account: "<name>", network: "testnet" },
-  submission: { sender: "<name>", gas_budget: "10000000" }
-})
-```
+Controls name collision behavior:
 
-### Pattern 2: Guard Logic Verification Before Deployment
+| Value | Effect |
+|-------|--------|
+| `false` (default) | Throws error if name is in use — safe default |
+| `true` | Steals name from existing object; old object becomes unnamed |
 
-**From [Insurance](../examples/Insurance/Insurance.md) — Time-Lock Guard**
+- Use `true` during development to reuse fixed names without cleanup
+- Default to `false` in production to prevent accidental name hijacking
+- Prefer versioned names (`_v1`, `_v2`) over `replaceExistName` for production
 
-Before deploying a Guard that controls fund release (Payment, Allocation, Reward), ALWAYS:
+### 4.2 Address Display Rules
 
-1. Export the Guard for human review:
-   ```
-   guard2file({ guard: "insurance_complete_guard_v1", file_path: "./guard_review.json", format: "json" })
-   ```
-2. Test the Guard logic with `gen_passport`:
-   ```
-   onchain_operations({
-     operation_type: "gen_passport",
-     data: { guard: "insurance_complete_guard_v1" },
-     info: { name: "guard_test", b_submission: true }
-   })
-   ```
-   This submits runtime values to the Guard and returns pass/fail — without any state change.
+When displaying an address (0x prefix + 64 hex characters) to the user:
 
-**From [Travel](../examples/Travel/Travel.md) — Weather Check Guard**
+1. **Query local mark first**:
 
-The Travel example demonstrates guard testing with specific runtime values:
-- The Guard queries `weather_repo_v2` for a given date
-- Test with `gen_passport`, submitting a timestamp that maps to "sunny" → should pass
-- Test with a timestamp that maps to "rainy" → should fail
-- This validates the Guard BEFORE it protects real funds in an Allocation
+**Tool**: `query_toolkit` with `query_type: "local_mark_list"` and filter by address.
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md) — Service Guard Testing**
+2. **Display format**:
+   - If local mark exists: `{name} ({short_address})`
+   - If no local mark: `{first8}...{last3}` (e.g., `0x3a2f8e1...8c1`)
 
-Service-level Guards (`service_merchant_win_v2`, `service_customer_win_v2`) control fund allocation. Before binding these to `order_allocators`:
-1. Export each Guard with `guard2file`
-2. Test with `gen_passport`, submitting mock order progress data
-3. Verify: correct node → pass, wrong node → fail
-4. Only then bind to Service's `order_allocators`
+3. **Short address format**: Include `0x` prefix, take first 8 chars + `...` + last 3 chars
 
-### Pattern 3: Publish-Immutability Checklist
+---
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md) — Build Order Rationale**
+## 5. Network & Token Defaults
 
-Before any publish operation, verify this checklist:
+| Parameter | Default Value | Notes |
+|-----------|---------------|-------|
+| Network | `testnet` | Override via `env.network` |
+| Token | `0x2::wow::WOW` | 9 decimals (1 WOW = 1_000_000_000) |
 
-```
-PUBLISH CHECKLIST
-├─ Machine publish:
-│  ├─ ✅ All nodes defined and reviewed (machineNode2file)
-│  ├─ ✅ All forward guards created and tested (gen_passport)
-│  ├─ ✅ Permission indexes assigned to correct accounts
-│  └─ ⚠️  After publish: nodes become IMMUTABLE
-│
-├─ Service publish:
-│  ├─ ✅ Machine bound to Service (machine field set)
-│  ├─ ✅ Allocation rules finalized (order_allocators)
-│  ├─ ✅ Sales/products defined (sales)
-│  ├─ ✅ Guards tested (buy_guard, sell_guard)
-│  └─ ⚠️  After publish: machine + allocation LOCKED
-│
-└─ Reward (post-publish):
-   └─ ✅ Can be added after Service publish (not locked)
-```
+### 5.1 Multi-Token Support & Amount Formats
 
-### Pattern 4: Multi-Provider Coordination Safety
+- **Multi-Token**: All operations support custom `token_type`. ALWAYS query precision via `query_toolkit` with `query_type: "token_list"` first. Never assume decimals.
+- **Amount Formats**:
+  - With unit: `"2WOW"`, `"10.5USDT"` — auto-converted using token precision.
+  - Plain number: internal unit (e.g., `1000000000` = 1 WOW). Always clarify with users when displaying plain numbers.
+- **U64 integers**: Amounts in operations are ALWAYS submitted as U64 integers. If the user specifies "2 WOW", do NOT submit the string "2 WOW" — calculate and submit `2000000000` (2 × 10^9).
+- **Never assume token decimals**: If the token's decimals cannot be queried, HALT the amount submission and alert the user.
 
-**From [Travel](../examples/Travel/Travel.md) — Two-Provider System**
+### 5.2 Payment Objects for Commercial Transfers
 
-When building a system that spans multiple accounts/providers:
+Use `Payment` objects for commercial transfers when possible — they offer Guard validation and purpose tracking beyond a simple `account_operation (transfer)`.
 
-1. **Each provider uses their own account** for operations on their own objects
-   - `weather_provider_v1` creates and manages `weather_repo_v2`
-   - `travel_provider_v1` creates and manages `travel_service_v1`
+---
 
-2. **Cross-provider references use names, not raw addresses**
-   - The weather check Guard references `"weather_repo_v2"` by name
-   - The MCP server resolves names to addresses automatically
+## 6. Query-First Pattern
 
-3. **Data providers build their objects BEFORE consumers**
-   - Weather Repository + data exists before the Guard that queries it
-   - Insurance Service exists before Travel creates sub-orders on it
+- **Query before mutate**: Always query current state before modifications.
 
-### Pattern 5: Amount Verification for Financial Operations
+**Tool**: `query_toolkit` with appropriate filters.
 
-**From all examples — Payment, Order, Allocation operations**
+- **Pagination**: All on-chain list queries (events, tables, received) support `cursor`/`limit`. Loop for large datasets.
+- **Cache control**: Use `no_cache: true` for time-sensitive reads.
 
-All financial operations in the tested examples follow these conventions:
+---
 
-| Operation | Amount Format | Verification |
-|-----------|--------------|-------------|
-| `service.sales[].price` | Raw integer (smallest unit) | Verify with: `wowok_buildin_info({ info_type: "token_list" })` |
-| `order.buy.total_pay.balance` | Raw integer | Confirm matches sales price × quantity |
-| `reward.coin_add` | Raw integer | Confirm pool size against expected payouts |
-| `allocation.sharing[].sharing` | Integer (Rate mode: basis points) | 10000 = 100%, 500 = 5% |
+## 7. Name Resolution & Display
 
-**From [Insurance](../examples/Insurance/Insurance.md):**
-```
-sales: [{ name: "Outdoor Accident Insurance", price: 100000000, stock: 1000 }]
-// 100000000 = 1 WOW (if 1 WOW = 10^8 smallest units)
-```
+### 7.1 Name Resolution Priority
+
+| Priority | Source | Display Format | Example |
+|----------|--------|----------------|---------|
+| 1 (Highest) | `local_mark_operation` | `{local_mark_name} (localmark)` | `my_service (localmark)` |
+| 2 | `account_operation` (account name) | `{account_name}` | `alice_wallet` |
+| 3 (Fallback) | None / Unnamed | `{first6}...{last3}` | `0x3a2f...8c1` |
+
+### 7.2 Address Resolution & Display Format
+
+**Resolve addresses to names** via `query_toolkit`:
+
+**Tool**: `query_toolkit` with `query_type: "local_names"` and `addresses` array parameter.
+
+- Each address must be a valid WOW ID: `0x` prefix + **64 hex characters**.
+- Returns resolved account name and/or local mark name for each address.
+- Name priority follows [7.1](#71-name-resolution-priority): `local_mark` > `account`.
+
+**Address truncation** (for display):
 
-**From [MyShop Advanced](../examples/MyShop_Advanced/MyShop_Advanced.md):**
 ```
-order_allocators.allocators[].sharing: { sharing: 10000, mode: "Rate" }
-// 10000 in Rate mode = 100% allocation
+{first_6_chars}...{last_3_chars}
 ```
 
-### Pattern 6: no_cache After Creation
+- Include the `0x` prefix in the character count.
+- Use exactly **three dots** (`...`) as the separator.
+- Example: `0x3a2f...8c1`
 
-**From [MyShop Advanced Test Results](../examples/MyShop_Advanced/MyShop_Advanced_MerchantSystem_TestResults.md)**
+**Combined display**: human-readable name + truncated address in parentheses.
 
-When querying an object immediately after creating it, always use `no_cache: true`:
+| Name Source | Display Format | Example |
+|-------------|----------------|---------|
+| local_mark | `{local_mark} ({first6}...{last3})` | `my_service (0x3a2f...8c1)` |
+| account | `{account_name} ({first6}...{last3})` | `alice_wallet (0x3a2f...8c1)` |
+| none (fallback) | `{first6}...{last3}` | `0x3a2f...8c1` |
 
-```
-// After creating a Permission:
-onchain_operations({ operation_type: "permission", data: { object: { name: "myshop_permission_v2", ... } }, env: { ... } })
+---
 
-// Query it — must bypass cache:
-query_toolkit({ query_type: "onchain_objects", objects: ["myshop_permission_v2"], no_cache: true })
-```
+## 8. Error Patterns
 
-Without `no_cache: true`, the query may return stale data (object not found), causing the AI to incorrectly conclude the creation failed.
+| Error | Likely Cause |
+|-------|-------------|
+| Guard validation failure | After re-submitting with `submission`, Guard logic evaluated to false. Review Guard's rule tree via `guard2file` and submitted data values. |
+| File parsing failure | `machineNode2file` or `guard2file` output format error. Check file format and schema compliance. |
+| Cache stale reads | Sequential operations fail unexpectedly (e.g., "object not found" when just created). Retry with `env.no_cache: true`. |
+| Permission denied | Operating account lacks the required Permission index. Check the object's Permission configuration. |
 
-### Pattern 7: replaceExistName for Development Iterations
+---
 
-**From all examples — object naming convention**
+## 9. Testing & Validation Workflow
 
-During development, when iterating on object designs, use `replaceExistName: true` to overwrite previous versions:
+1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions and Guard instructions
 
-```
-data: {
-  object: { name: "myshop_permission_v2", replaceExistName: true, ... }
-}
-```
+**Tool**: `wowok_buildin_info` with `info_type: "permissions"` or `info_type: "guard_instructions"`.
 
-⚠️ **Safety note**: `replaceExistName: true` destroys the previous object with that name. Only use during development. In production, use versioned names (`_v1`, `_v2`, `_v3`).
+2. **Export & Review**: Before publishing, use `guard2file` and `machineNode2file` to export and review definitions
 
-### Pattern 8: Machine Creation Order — Nodes First, Then Publish
+3. **Incremental Testing**: Build objects step-by-step, verifying each step
 
-**From [Insurance](../examples/Insurance/Insurance.md) — Key Discovery**
+4. **Final Validation**: Test all Guard conditions and Machine transitions before publishing
 
-The Insurance example documents a critical finding: Machine nodes must be added during creation (same transaction) before publishing. Adding nodes in separate transactions after creation may not persist correctly.
+5. **Publish**: Only after thorough testing, publish Service and Machine
 
-✅ **Correct** (single transaction):
-```
-onchain_operations({
-  operation_type: "machine",
-  data: {
-    object: { name: "insurance_machine_v1", permission: "..." },
-    node: { op: "add", nodes: [...] },  // nodes in same call
-    publish: true                        // publish in same call
-  }
-})
-```
+---
 
-❌ **Incorrect** (separate transactions):
-```
-// Step 1: Create machine (no nodes)
-onchain_operations({ operation_type: "machine", data: { object: {...} } })
-// Step 2: Add nodes (may not persist)
-onchain_operations({ operation_type: "machine", data: { object: "...", node: { op: "add", nodes: [...] } } })
-// Step 3: Publish
-onchain_operations({ operation_type: "machine", data: { object: "...", publish: true } })
-```
+## 10. Incremental Object Building
 
-## Safety Decision Tree for On-Chain Operations
+For complex objects with many fields (Service, Machine), use **incremental building** instead of creating everything in one call:
 
-```
-About to execute onchain_operations?
-├─ Is this a READ operation? (query_toolkit, onchain_table_data, etc.)
-│  └─ ✅ SAFE — proceed without confirmation
-│
-├─ Is this a WRITE operation? (onchain_operations with submission)
-│  ├─ Does it involve money? (payment, reward, treasury, allocation)
-│  │  └─ 🔴 HIGH RISK — must show amounts + token type + recipient + get double confirmation
-│  │
-│  ├─ Does it publish something? (service.publish, machine.publish)
-│  │  └─ 🟡 MEDIUM RISK — must show what will be locked + get confirmation
-│  │
-│  ├─ Does it modify guards/permissions? (guard, permission)
-│  │  └─ 🟡 MEDIUM RISK — must explain what access changes + get confirmation
-│  │
-│  └─ Is it a structural change? (service.update, machine.node)
-│     └─ 🟢 LOW-MEDIUM — show what changes + get confirmation
-│
-└─ Is this a DRY RUN? (no submission field)
-   └─ ✅ SAFE — no state change, but still review the preview for errors
-```
+- Each step can be verified before proceeding
+- Errors are isolated to specific fields
+- Easier to retry failed steps without re-executing successful ones
+- Better user feedback at each stage
+
+---
+
+## Schema Reference
+
+| Purpose | Schema Name |
+|---------|-------------|
+| Query toolkit | `query_toolkit` |
+| Token list | `query_toolkit` with `query_type: "token_list"` |
+| Guard export | `guard2file` |
+| Machine export | `machineNode2file` |
+| Build-in info | `wowok_buildin_info` |
+
+**Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
+
+**Related Skills**: [wowok-tools](../wowok-tools/SKILL.md) | [wowok-guard](../wowok-guard/SKILL.md) | [wowok-machine](../wowok-machine/SKILL.md)