@wowok/skills 1.3.2 → 1.3.4

package/package.json

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

@@ -129,6 +129,8 @@ Customer dispute creates Arb directly at (1). State (0) entered only via `reset`
 
 **⚠️ Guard Immutability**: Once a Guard is created, its rules **cannot be modified**. If your `voting_guard` design is wrong, you must create a replacement Guard and reconfigure the Arbitration — wasteful but not fatal. Test with `gen_passport` before finalizing.
 
+**⚠️ Permission Isolation from Service** (CRITICAL for mainnet trust): The Arbitration's Permission object MUST be separate from the Service's Permission object. Sharing the same Permission — or having overlapping owner/admin addresses — breaks dispute fairness because the merchant can control arbitration operations (vote, confirm, execute rulings). For mainnet deployment, use a completely independent third-party Permission with a different owner and admin list. The evaluation engine deducts risk scores significantly for Permission overlap (-30 for same Permission, -20 for owner/admin overlap). Testnet may tolerate shared Permission for simplicity, but mainnet users should treat this as a critical trust factor.
+
 ### Voting Modes
 
 **1. Open Voting** (`voting_guard: []`)

package/wowok-machine/SKILL.md

@@ -249,6 +249,7 @@ Before `publish: true`, verify:
 - [ ] All Guards exist on-chain and tested (use `gen_passport`)
 - [ ] `namedOperator` vs `permissionIndex` correct per Forward
 - [ ] Every Forward has at least one of `namedOperator` or `permissionIndex`
+- [ ] **⚠ Permission indexes authorized** (P0): every `permissionIndex` used in forwards MUST have at least one entity granted in the Permission object. Call `permission.op="add perm by index"` for each custom index (≥1000) BEFORE publishing. Un-granted indexes = forward can NEVER execute = Progress permanently stuck. The MCP handler auto-checks this and warns on missing grants.
 - [ ] Terminal nodes mapped to Allocator entries for fund distribution
 - [ ] Tested end-to-end on testnet via a test Progress
 - [ ] Current state exported via `machineNode2file` as backup

package/wowok-provider/SKILL.md

@@ -137,7 +137,7 @@ STEP 3: Business Logic (MODIFY)
 │     Tool: "onchain_operations" (service) | Fields: order_allocators
 ├── Arbitrations (optional) — REUSE existing Arb services
 │     Tool: "onchain_operations" (service) | Fields: arbitrations.list
-├── Compensation Fund (optional): compensation_fund_add + setting_locked_time_add (default 30 days, configurable)
+├── Compensation Fund (optional): compensation_fund_add + setting_lock_duration_add (default 30 days, configurable)
 │     Tool: "onchain_operations" (service)
 └── Reward (optional) — incentive pools
 
@@ -154,7 +154,9 @@ STEP 4: Publication
       2. guard2file export Guards → review
       3. machineNode2file export Machine → review
       4. Allocator splits match user's stated model?
-      5. Warn: publish = immutable. Proceed?
+      5. Permission indexes: every permissionIndex in Machine forwards has entities granted? (call permission "add perm by index" for missing ones)
+      6. Arbitration Permission isolation: Arbitration uses a SEPARATE Permission object (not the Service's Permission)? Different owner/admin? (critical for mainnet trust)
+      7. Warn: publish = immutable. Proceed?
 
 STEP 5: Post-Publish (MODIFY Service — mutable after publish)
 ├── description, location
@@ -320,7 +322,7 @@ Attach: wowok({ tool: "onchain_operations", data: { operation_type: "service", .
 
 ### Compensation Fund (Optional but Recommended)
 
-- Add: `compensation_fund_add` | Lock: `setting_locked_time_add` (default 30 days = 2592000000ms, configurable via `setting_lock_duration_add`)
+- Add: `compensation_fund_add` | Lock: `setting_lock_duration_add` (default 30 days = 2592000000ms, configurable via `setting_lock_duration_add`)
 - **Withdraw**: Pause Service → Wait lock duration → `compensation_fund_receive`
 
 ---

package/wowok-safety/SKILL.md

@@ -166,6 +166,59 @@ Controls name collision behavior. **DISCOURAGED** — prefer versioned names (`_
 
 Use `Payment` objects for commercial transfers when possible — they offer Guard validation and purpose tracking beyond a simple `account_operation (transfer)`.
 
+### 5.3 Cross-Network Switching (testnet → mainnet)
+
+WoWok objects are network-specific — the same object name resolves to different addresses on testnet vs mainnet. The `local_mark` system manages this mapping automatically.
+
+**Prerequisites**:
+- testnet deployment verified (all objects created, order lifecycle tested)
+- Record all object names (query `local_mark_list` for the full list)
+- mainnet account has sufficient WOW balance (faucet is testnet-only; use `account_operation transfer` from a funded mainnet account)
+
+**Switching Steps**:
+1. Change `env.network` from `"testnet"` to `"mainnet"` in all MCP calls
+2. Re-create all objects on mainnet with `replaceExistName: true` (names stay the same, addresses change)
+3. Order matters — follow the dependency chain: Permission → Machine → Guards → Contact → Service → (Order/Progress/Allocation are created at purchase time)
+4. Verify each object creation succeeds and `local_mark` is updated
+5. Test the critical path: place a test order → advance Progress → verify Allocation
+
+**Key Mechanism**:
+```
+testnet:  local_mark["my_service"] = 0x867a...  (testnet address)
+mainnet:  local_mark["my_service"] = 0xdef0...  (mainnet address, auto-overwritten)
+```
+- All object references in Guard tables, Service bindings, and Machine forwards use NAMES (not addresses)
+- SDK's `GetObjectExisted()` resolves names to the current network's address at transaction build time
+- `replaceExistName: true` ensures the name mapping is overwritten for the new network
+
+**Important Notes**:
+- testnet objects remain on testnet (they don't disappear) — mainnet is a completely fresh deployment
+- Guard tables that reference other objects by NAME will auto-resolve to mainnet addresses
+- Service.order_allocators and Machine nodes are immutable after publish — verify design before mainnet publish
+- mainnet has no faucet — fund accounts via `account_operation` with `transfer` from an existing funded account
+
+### 5.4 Publish Pre-Check Checklist
+
+Before calling `publish: true` on a Service or Machine, verify:
+
+**Service Publish Checklist**:
+- [ ] `order_allocators` is set and design is verified (PERMANENTLY immutable after publish)
+- [ ] `machine` is bound and already published
+- [ ] `buy_guard` is bound (if purchase validation is needed)
+- [ ] `permission` is bound with all required indexes granted
+- [ ] If `compensation_fund > 0`: `arbitrations` MUST be bound (contract enforces: `E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND`)
+- [ ] All Guard names in `order_allocators` resolve correctly
+- [ ] All sharing amounts and recipient types (Entity/Signer/GuardIdentifier) are intended
+- [ ] Use `dry_run: true` first to simulate the publish transaction
+
+**Machine Publish Checklist**:
+- [ ] All nodes have at least one forward (except terminal nodes)
+- [ ] Each forward has `namedOperator` or `permissionIndex` (or both = OR semantic)
+- [ ] `namedOperator: ""` means OrderHolder (customer), NOT "anyone"
+- [ ] All `permissionIndex` values are granted in the bound Permission object
+- [ ] Entry node has `prev_node: ""` and `threshold: 0`
+- [ ] Terminal nodes have empty `pairs: []`
+
 ---
 
 ## 6. Query-First Pattern

package/wowok-tools/SKILL.md

@@ -151,7 +151,7 @@ Step 3: MODIFY reward { object: "reward_v1", guard_add: [...] } // bind guard
 
 | `operation_type` | Key Constraints (not in schema) |
 |-----------------|----------------------------------|
-| `service` | `machine` must be **published**. Allocators: array order = priority (first-Guard-wins). **Publish locks 3 fields (SDK-level)**: `machine`/`order_allocators`/`arbitrations` — MUST be set BEFORE `publish:true`. **buy_guard is MUTABLE after publish** (no SDK/Move lock). `setting_locked_time_add` is extendable. TIME-LOCKED (need pause + setting_lock_duration): `rewards` remove/clear. REMAIN MUTABLE: `sales`/`discount`/`description`/`location`/`pause`/`repositories`/`rewards`(add)/`compensation_fund_add`/`customer_required`/`um`/`buy_guard`. To change locked fields after publish, clone a new Service. |
+| `service` | `machine` must be **published**. Allocators: array order = priority (first-Guard-wins). **Publish locks 2 fields (L1 absolute)**: `machine`/`order_allocators` — MUST be set BEFORE `publish:true`. **TIME-LOCKED (L2, need pause + setting_lock_duration)**: `arbitrations` remove/clear, `rewards` remove/clear, `compensation_fund_withdraw`. **REMAIN MUTABLE (L3)**: `arbitrations`(add)/`rewards`(add)/`sales`/`discount`/`description`/`location`/`pause`/`repositories`/`compensation_fund_add`/`setting_lock_duration_add`/`customer_required`/`um`/`buy_guard`. To change L1-locked fields after publish, clone a new Service. |
 | `machine` | Nodes immutable after publish. Forward needs ≥1 of `namedOperator`/`permissionIndex` (both empty = SDK error). `""` = entry node. → [wowok-machine](../wowok-machine/SKILL.md) |
 | `progress` | CANONICAL form: `operate: {operation: {next_node_name, forward}, op: "next"\|"hold"\|"unhold"\|"adminUnhold", message?}`. LEGACY `hold: boolean` is auto-converted (`hold:true`→`op:'hold'`, `hold:false`→`op:'next'`). SDK auto-fetches Machine when resolving `object_address`. **⚠ Routing rule**: Use `progress.operate` ONLY for forwards with non-empty `namedOperator` or `permissionIndex`-only. For forwards with `namedOperator=""` (OrderHolder), use `order.progress` instead — direct `progress::next` aborts with Permission denied (code 5). |
 | `arbitration` | MAX 20 propositions, 520 voters. Verdict (2→3) **irreversible** — only customer can `order.arb_objection`. Non-Finished withdrawal = 30-day wait. → [wowok-arbitrator](../wowok-arbitrator/SKILL.md) |