@wowok/skills 1.3.2 → 1.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "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-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) |