@wowok/skills 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/package.json +1 -1
  2. package/wowok-arbitrator/SKILL.md +192 -192
  3. package/wowok-guard/SKILL.md +189 -285
  4. package/wowok-machine/SKILL.md +167 -328
  5. package/wowok-order/SKILL.md +6 -6
  6. package/wowok-provider/SKILL.md +3 -1
  7. package/wowok-safety/SKILL.md +20 -2
  8. package/wowok-tools/SKILL.md +141 -536
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wowok/skills",
3
- "version": "1.1.2",
3
+ "version": "1.1.3",
4
4
  "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
package/wowok-arbitrator/SKILL.md CHANGED
@@ -1,279 +1,279 @@
1
1
  ---
2
2
  name: wowok-arbitrator
3
3
  description: |
4
- WoWok Arbitrator — the canonical skill for arbitration service providers
5
- to create Arbitration objects, handle dispute resolution, manage voting processes,
6
- and earn arbitration fees.
4
+ WoWok Arbitrator — build and operate on-chain arbitration services.
5
+ Create Arbitration objects, configure voting rules (open or guard-based weighted),
6
+ manage dispute cases through their full lifecycle, and earn fees from resolution.
7
7
 
8
- Covers: creating Arbitration objects, receiving Messenger communications,
9
- selecting and organizing voters, processing arbitration cases (Arb objects),
10
- distributing arbitration fees, and managing compensation funds.
11
-
12
- For customers placing orders, see wowok-order. For service providers, see wowok-provider.
8
+ Core value: achieve trust consensus between merchants and users through
9
+ transparent, fair, and efficient dispute resolution.
13
10
  when_to_use:
14
- - User wants to create an Arbitration service on WoWok
15
- - User wants to handle dispute resolution between customers and merchants
16
- - User wants to organize voting processes for arbitration cases
17
- - User wants to manage arbitration fees and compensation funds
18
- - User mentions "arbitration", "dispute resolution", "voting", "arbiter", "judge"
11
+ - User wants to create/configure an Arbitration service
12
+ - User needs to handle dispute cases and voting processes
13
+ - User wants to design voter eligibility and weight mechanisms
14
+ - User mentions "arbitration", "dispute", "voting", "arb", "judge"
19
15
  ---
20
16
 
21
17
  # WoWok Arbitrator Guide
22
18
 
23
- Create and operate arbitration services on WoWok as a trusted third-party dispute resolver.
19
+ Build trust through fair dispute resolution. Arbitration services enable neutral third parties to resolve conflicts between customers and merchants, earning fees while establishing on-chain reputation.
24
20
 
25
- > **Role**: Arbitrator (Dispute Resolution Service)
26
- > **Customer Perspective**: See [wowok-order](../wowok-order/SKILL.md) — Section 3: Arbitration Operations
27
- > **Service Provider Perspective**: See [wowok-provider](../wowok-provider/SKILL.md)
28
- > **Tools**: See [wowok-tools](../wowok-tools/SKILL.md)
21
+ > **Related Skills**: [wowok-order](../wowok-order/SKILL.md) (customer disputes), [wowok-provider](../wowok-provider/SKILL.md) (service arbitration config), [wowok-guard](../wowok-guard/SKILL.md) (voting_guard design), [wowok-messenger](../wowok-messenger/SKILL.md) (evidence exchange)
29
22
 
30
23
  ---
31
24
 
32
- ## Core Principle: Trusted Third-Party
25
+ ## Core Architecture
33
26
 
34
- Arbitration services provide **neutral dispute resolution** between customers and service providers. Trust is earned through:
27
+ ### Two-Layer Design
35
28
 
36
- - **Transparent processes**: Clear rules published in Arbitration object
37
- - **Fair voting**: Multi-party voting prevents unilateral decisions
38
- - **Timely resolution**: Defined deadlines prevent indefinite delays
39
- - **Enforceable outcomes**: Integration with Service's compensation fund
29
+ | Layer | Object | Purpose | Lifecycle |
30
+ |-------|--------|---------|-----------|
31
+ | **Service** | Arbitration | Rules, fees, voter configuration | Permanent |
32
+ | **Case** | Arb | Individual dispute with state machine | Per dispute |
40
33
 
41
- ---
34
+ **Separation of Powers**:
35
+ - **Arbitrator controls**: Who can vote, voting weights, final verdict (`indemnity`)
36
+ - **Customer controls**: Accept result or object, claim compensation timing
42
37
 
43
- ## The Arbitration Lifecycle
38
+ Neither party can force outcome unilaterally — the design forces collaboration toward consensus.
44
39
 
45
- ```
46
- ARBITRATION CREATION (one-time setup)
47
- ├── Create Arbitration object
48
- ├── Configure: fee structure, voting rules, compensation fund
49
- ├── Set up Contact (um) for Messenger communication
50
- └── Publish to make available for Services
51
-
52
- ARBITRATION CASE (Arb object) — per dispute
53
- ├── Customer initiates via arbitration.dispute (pays fee)
54
- ├── Customer submits evidence via Messenger (WTS files)
55
- ├── Arbitrator reviews evidence and organizes voting
56
- ├── Voters cast votes
57
- ├── Result determined and published
58
- ├── Customer claims compensation via order.arb_claim_compensation
59
- └── Arbitrator receives fee from Arbitration.balance
60
- ```
40
+ ### Arb State Machine
61
41
 
62
- ---
42
+ | State | Available Operations | Next State |
43
+ |-------|---------------------|------------|
44
+ | **(0) Principal_confirming** | Customer (via Order): `arb_confirm` | → (1) |
45
+ | **(1) Arbitrator_confirming** | Arbitrator: `confirm` → (2), `reset` → (0), feedback | → (2) or (0) |
46
+ | **(2) Voting** | Arbitrator: vote, set deadline, `arbitration` → (3), feedback | → (3) |
47
+ | **(3) Arbitrated** | Customer (via Order): `arb_objection` → (4), `arb_claim_compensation` → (5) | → (4) or (5) |
48
+ | **(4) Objectionable** | Arbitrator: `reset` → (0), feedback | → (0) |
49
+ | **(5) Finished** | Arbitrator: `withdraw` → (6) | → (6) |
50
+ | **(6) Withdrawn** | Terminal | — |
63
51
 
64
- ## Creating an Arbitration Service
52
+ **Key Flows**:
53
+ - **Standard**: (1) → confirm → (2) → arbitration → (3) → arb_claim_compensation → (5) → withdraw → (6)
54
+ - **With Revision**: (1) → reset → (0) → arb_confirm → (1) → confirm → (2) → ...
55
+ - **With Objection**: ... → (3) → arb_objection → (4) → reset → (0) → ...
65
56
 
66
- ### Step 1: Create Arbitration Object
57
+ ---
67
58
 
68
- **Operation**: `onchain_operations` with `operation_type: "arbitration"`.
59
+ ## Phase 1: Build Your Service
69
60
 
70
- **Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_arbitration" })`
61
+ ### Essential Configuration
71
62
 
72
- **Key Fields**:
73
- - `object`: Arbitration object name (CREATE) or ID (MODIFY)
74
- - `description`: Service description
75
- - `fee`: Arbitration fee per case (token amount)
76
- - Other configuration fields per schema
63
+ | Field | Purpose | Key Decision |
64
+ |-------|---------|--------------|
65
+ | `fee` | Revenue per case | Balance accessibility with sustainability |
66
+ | `voting_guard` | Who votes, with what weight | Open (centralized) vs Guard-based (decentralized) |
67
+ | `usage_guard` | Who can file disputes | Public vs invitation-only |
68
+ | `um` | Contact for evidence exchange | Messenger addresses for WTS verification |
77
69
 
78
- ### Step 2: Set Up Contact for Messenger
70
+ **Start paused** (`pause: true`). Configure everything before accepting disputes.
79
71
 
80
- Arbitration's `um` field references a Contact object with Messenger addresses.
72
+ ### Voting Modes
81
73
 
82
- **Create Contact**:
74
+ **1. Open Voting** (`voting_guard: []`)
75
+ - Arbitrator casts votes directly (weight = 1)
76
+ - Best for: Small trusted panels, centralized resolution
83
77
 
84
- **Operation**: `onchain_operations` with `operation_type: "contact"`.
78
+ **2. Guard-Based Voting** (`voting_guard: [{guard, vote_weight}, ...]`)
79
+ - Voters authenticate via Passport + Guard
80
+ - Weight determined by `vote_weight` rule:
81
+ - `FixedValue(u32)`: Equal weight for all qualified voters
82
+ - `GuardIdentifier(u8)`: Dynamic weight from credential (e.g., reputation score, token balance)
83
+ - Max 50 guards — enables tiered voting (experts + community, token-holders + NFT-holders)
85
84
 
86
- **Key Fields**:
87
- - `object`: Contact object name (CREATE) or ID (MODIFY)
88
- - `description`: Contact purpose description
89
- - `ims`: Array of IM addresses with:
90
- - `name`: Identifier for this IM endpoint
91
- - `at`: Messenger address
85
+ **Voting Flow**: Voter selects a voting guard → System verifies voter's Passport against that guard → Calculates weight based on guard's rule → Applies weight to selected propositions. One vote per voter per case.
92
86
 
93
- **Link Contact to Arbitration**:
87
+ ---
94
88
 
95
- **Operation**: `onchain_operations` with `operation_type: "arbitration"`.
89
+ ## Phase 2: Handle Cases
96
90
 
97
- **Key Field**:
98
- - `um`: Contact object ID or name to link
91
+ ### Case Lifecycle
99
92
 
100
- ### Step 3: Configure Compensation Fund (Optional)
93
+ **1. Arrival** (`dispute` by customer)
94
+ - Arb created in state (1)
95
+ - Fee locked in `arb.fee`
96
+ - Customer's propositions recorded
101
97
 
102
- Services can link to your Arbitration and contribute to compensation fund.
98
+ **2. Review** — Two paths:
103
99
 
104
- **Flow**:
105
- ```
106
- Service.compensation_fund → Holds tokens for arbitration payouts
107
- When customer wins arbitration → Funds transferred to customer's Order
108
- ```
100
+ | Path | Condition | Action | Result |
101
+ |------|-----------|--------|--------|
102
+ | **Proceed** | Propositions clear, evidence sufficient | `confirm` + `voting_deadline` | → Voting (2) |
103
+ | **Revise** | Ambiguous claims, insufficient evidence | `reset` + feedback | → Principal_confirming (0) |
109
104
 
110
- ---
111
-
112
- ## Handling Arbitration Cases
105
+ **Best Practice**: Use `reset` proactively. A revision cycle is faster than a flawed arbitration followed by objection.
113
106
 
114
- ### Receiving Evidence via Messenger
107
+ **3. Voting** (state 2)
108
+ - Votes accumulate on propositions
109
+ - Voters can change votes (old votes replaced)
110
+ - Max 520 voters per case
115
111
 
116
- Customers submit evidence through encrypted Messenger communication.
112
+ **4. Finalization** (`arbitration` operation)
113
+ - Sets `feedback` (reasoned decision)
114
+ - Sets `indemnity` (compensation amount, 0 = provider wins)
115
+ - Requires deadline passed (if set)
116
+ - → Arbitrated (3)
117
117
 
118
- **Process**:
119
- 1. Customer queries Arbitration's Contact object (`arbitration.um`)
120
- 2. Customer extracts IMS addresses from `contact.ims[]`
121
- 3. Customer sends WTS files via Messenger
122
- 4. Arbitrator receives and verifies WTS authenticity
118
+ **5. Resolution** — Customer chooses (via Order operations):
123
119
 
124
- **WTS Verification**:
120
+ | Choice | Action | Result |
121
+ |--------|--------|--------|
122
+ | **Accept** | `arb_claim_compensation` | → Finished (5), fee withdrawable |
123
+ | **Object** | `arb_objection` | → Objectionable (4) |
125
124
 
126
- **Tool**: `messenger_operation` with `verify_wts` operation.
125
+ **6. Objection Handling**
126
+ - Only action: `reset` → back to (0) for revision
127
+ - Forces collaborative resolution — no override mechanism
127
128
 
128
- **Key Field**:
129
- - `wtsFilePath`: Path to received WTS file
129
+ **7. Fee Withdrawal**
130
+ - From Finished: Immediate
131
+ - From Arbitrated/Objectionable: 30-day wait (protects customer rights)
130
132
 
131
- **Schema Reference**: `schema_query({ action: "get", name: "messenger_operation" })`
133
+ ---
132
134
 
133
- ### Arb Object Lifecycle
135
+ ## Phase 3: Business Model
134
136
 
135
- Arb objects progress through states as the arbitration proceeds:
137
+ ### Revenue Flow
136
138
 
137
- | State | Description | Next Action |
138
- |-------|-------------|-------------|
139
- | `Principal_confirming` | Initial state, principal (customer) confirming claim | Customer submits evidence |
140
- | `Arbitrator_confirming` | Arbitrator reviewing evidence | Arbitrator organizes voting |
141
- | `Voting` | Voting in progress | Voters cast votes |
142
- | `Arbitrated` | Voting complete, result determined | Either party can object |
143
- | `Objectionable` | Objection period open | Opposing party can file objection |
144
- | `Finished` | Arbitration complete, result final | Customer can claim compensation |
145
- | `Withdrawn` | Arbitration withdrawn | No further action |
139
+ ```
140
+ Customer pays fee
141
+ │
142
+ ▼
143
+ Arb.fee (locked per case)
144
+ │
145
+ │ arb_withdraw()
146
+ ▼
147
+ Arbitration.balance
148
+ │
149
+ ├──→ Allocation (revenue sharing)
150
+ └──→ Treasury (controlled withdrawal)
151
+ ```
146
152
 
147
- ### Organizing Voting
153
+ ### Compensation System
148
154
 
149
- **Selecting Voters**:
150
- - Define voter eligibility criteria (reputation, stake, expertise)
151
- - Invite qualified voters to participate
152
- - Set voting deadline (`arb.voting_deadline`)
155
+ Arbitrator sets `indemnity` → Customer claims via `order.arb_claim_compensation` → Funds transfer from `service.compensation_fund` to Order.
153
156
 
154
- **Voting Process**:
155
- ```
156
- Arb.proposition[] → List of claims/proposals
157
- Arb.voted[] → Voting records
158
- Voters evaluate evidence and vote on propositions
159
- ```
157
+ **Key Principle**: Arbitrator decides amount, provider's fund pays it. This aligns incentives — providers have reason to avoid disputes, arbitrators have reason to be fair.
160
158
 
161
- **Determining Outcome**:
162
- - Count votes per proposition
163
- - Apply voting rules (simple majority, supermajority, etc.)
164
- - Set `arb.indemnity` with compensation amount if customer wins
165
- - Transition to `Arbitrated` state
159
+ > See [wowok-order](../wowok-order/SKILL.md) for customer-side arbitration operations.
166
160
 
167
161
  ---
168
162
 
169
- ## Arbitration Fees & Revenue
170
-
171
- ### Fee Structure
163
+ ## Integration Patterns
172
164
 
173
- **Arbitration Fee** (`arbitration.fee`):
174
- - Paid by customer when initiating dispute (`arbitration.dispute`)
175
- - Stored in `arbitration.balance`
176
- - Covers arbitrator's operational costs
165
+ ### Evidence Workflow (Messenger)
177
166
 
178
- **Fee Distribution**:
179
- ```
180
- Customer pays fee ──→ Arbitration.balance
181
- │
182
- ├──→ Arbitrator (platform/revenue)
183
- └──→ Voters (if voter incentives configured)
184
- ```
167
+ 1. Customer queries Arbitration's `um` → gets Messenger addresses
168
+ 2. Customer sends WTS evidence files (encrypted, off-chain)
169
+ 3. Arbitrator verifies WTS authenticity (`messenger_operation` with `verify_wts`)
170
+ 4. Only verified evidence considered valid
185
171
 
186
- ### Extracting Fees
172
+ **Why WTS**: Cryptographically proves communication history without on-chain exposure.
187
173
 
188
- Arbitrators can extract accumulated fees.
174
+ ### Guard Relationships
189
175
 
190
- **Query Balance**:
176
+ | Guard | Purpose | Effect |
177
+ |-------|---------|--------|
178
+ | `usage_guard` | Access control | Must satisfy to file dispute |
179
+ | `voting_guard` | Authentication + weight | Must satisfy to vote; weight from rule |
191
180
 
192
- **Tool**: `query_toolkit` with `onchain_objects` query type.
181
+ **Design Principle**: `usage_guard` = yes/no gate; `voting_guard` = credential-verified weighted participation.
193
182
 
194
- **Extract Field**: `arbitration.balance`
183
+ ### Service Provider Integration
195
184
 
196
- **Withdrawal Operation**:
185
+ Providers list approved Arbitrations in their Service. Customers choose from this list when disputes arise.
197
186
 
198
- **Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_arbitration" })` — look for withdrawal/receive fields
187
+ **Trust Flywheel**: Fair arbitrators get listed by more providers → more cases → more revenue → stronger reputation → more provider listings.
199
188
 
200
189
  ---
201
190
 
202
- ## Integration with Services
191
+ ## Design Principles
203
192
 
204
- ### Services Linking to Arbitration
193
+ ### Fairness Mechanisms
205
194
 
206
- Services configure which Arbitrations they support:
195
+ 1. **Separated Powers**: Arbitrator cannot force acceptance; customer cannot force ruling
196
+ 2. **Revision Cycles**: `reset` enables correction without penalty
197
+ 3. **Objection Rights**: Customer always retains right to contest
198
+ 4. **Transparent Rules**: All voting logic on-chain, verifiable
199
+ 5. **Timed Withdrawal**: 30-day wait protects customer claim rights
207
200
 
208
- ```
209
- Service.arbitrations: ["<arbitration_id_1>", "<arbitration_id_2>"]
210
- Service.compensation_fund: "<token_balance>"
211
- ```
201
+ ### Efficiency Mechanisms
212
202
 
213
- When customer creates Arb object on linked Arbitration:
214
- - Arb automatically associated with Order
215
- - Service's compensation fund available for payouts
216
- - Arbitration fee paid to Arbitration.balance
203
+ 1. **State Machine**: Clear progression, no ambiguity about next steps
204
+ 2. **Weighted Voting**: Credential-based influence reduces voter spam
205
+ 3. **Deadline Enforcement**: Optional time-boxing prevents indefinite delays
206
+ 4. **Fee Incentive**: Arbitrator earns per case, motivated to resolve
217
207
 
218
- ### Compensation Flow
208
+ ### Trust Building
219
209
 
220
- ```
221
- Customer wins arbitration
222
- │
223
- ├──→ Arb.indemnity set with compensation amount
224
- │
225
- ├──→ Customer calls order.arb_claim_compensation
226
- │
227
- ├──→ Funds transferred from Service.compensation_fund to Order
228
- │
229
- └──→ Customer extracts via Order.receive()
230
- ```
210
+ 1. **On-Chain Reputation**: Past rulings (`feedback`) are public and permanent
211
+ 2. **Consistent Standards**: Apply uniform criteria across similar cases
212
+ 3. **Reasoned Decisions**: Detailed `arbitration.feedback` explains logic
213
+ 4. **Professional Response**: Monitor Messenger, verify WTS promptly
231
214
 
232
215
  ---
233
216
 
234
- ## Best Practices
217
+ ## Quick Reference
235
218
 
236
- ### Building Trust
219
+ ### Essential Operations
237
220
 
238
- 1. **Clear Rules**: Publish detailed arbitration rules and fee structure
239
- 2. **Fair Process**: Ensure transparent evidence review and voting
240
- 3. **Timely Resolution**: Set and enforce reasonable deadlines
241
- 4. **Professional Communication**: Respond promptly via Messenger
242
- 5. **Consistent Standards**: Apply uniform criteria across cases
221
+ | Operation | State | Purpose |
222
+ |-----------|-------|---------|
223
+ | `confirm` | (1)→(2) | Start voting, set deadline |
224
+ | `reset` | (1)→(0), (4)→(0) | Request revision |
225
+ | `vote` | (2) | Cast weighted votes |
226
+ | `arbitration` | (2)→(3) | Finalize with indemnity |
227
+ | `arb_withdraw` | (5), (3), (4) | Extract fee to balance |
243
228
 
244
- ### Evidence Handling
229
+ ### Common Workflows
245
230
 
246
- 1. **Verify WTS**: Always verify WTS file authenticity before evaluation
247
- 2. **Document Review**: Maintain records of evidence evaluation
248
- 3. **Privacy Protection**: Keep evidence confidential (Messenger-only)
249
- 4. **Chain of Custody**: Track evidence submission timestamps
231
+ **Standard Resolution**:
232
+ ```
233
+ Dispute → Review → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
234
+ ```
250
235
 
251
- ### Fee Management
236
+ **With Revision**:
237
+ ```
238
+ Dispute → Reset → arb_confirm → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
239
+ ```
252
240
 
253
- 1. **Competitive Pricing**: Set fees that balance accessibility and sustainability
254
- 2. **Transparent Costs**: Clearly communicate fee structure upfront
255
- 3. **Fair Distribution**: Compensate voters fairly if using distributed voting
256
- 4. **Regular Withdrawals**: Extract fees periodically to manage treasury
241
+ **With Objection**:
242
+ ```
243
+ Dispute → Confirm → Vote → Finalize → arb_objection → Reset → arb_confirm → Confirm → Vote → Finalize → arb_claim_compensation → Withdraw
244
+ ```
257
245
 
258
- ---
246
+ ### Critical Constraints
259
247
 
260
- ## Schema Reference
248
+ - Max 20 propositions per case
249
+ - Max 520 voters per case
250
+ - Max 50 voting guards per Arbitration
251
+ - 30-day withdrawal wait for non-finished cases
261
252
 
262
- Use `schema_query` tool to get complete JSON schemas:
253
+ ### Schema Access
263
254
 
264
- | Purpose | Schema Name |
265
- |---------|-------------|
266
- | List all schemas | `schema_query({ action: "list" })` |
267
- | Arbitration operations | `onchain_operations_arbitration` |
268
- | Order arbitration operations | `onchain_operations_order` |
269
- | Messenger for evidence | `messenger_operation` |
255
+ ```javascript
256
+ schema_query({ action: "get", name: "onchain_operations_arbitration" })
257
+ schema_query({ action: "get", name: "onchain_operations_order" })
258
+ schema_query({ action: "get", name: "messenger_operation" })
259
+ ```
270
260
 
271
- **Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
261
+ ---
272
262
 
273
- **Key Object Schemas** (via `query_toolkit`):
274
- - `ObjectArbitrationSchema`: Arbitration object structure
275
- - `ObjectArbSchema`: Arb case object structure
276
- - `ArbStatusSchema`: Arb lifecycle states
277
- - `ContactSchema`: Messenger contact setup
263
+ ## Best Practices
278
264
 
279
- **Tools**: `query_toolkit` | `messenger_operation` | [all_tools](../wowok-tools/SKILL.md)
265
+ 1. **Configure before unpause**: Fee, contact, voting rules ready first
266
+ 2. **Reset proactively**: Unclear case? Send back immediately
267
+ 3. **Verify all evidence**: Use `verify_wts` before evaluating
268
+ 4. **Write detailed feedback**: Your on-chain reputation
269
+ 5. **Set fair indemnity**: Proportional to order value and dispute nature
270
+ 6. **Test guards first**: Use `gen_passport` to verify voting_guard logic
271
+ 7. **Monitor compensation funds**: Warn if provider fund insufficient for indemnity
272
+
273
+ ### Common Pitfalls
274
+
275
+ - **Paused Arbitration**: Silently rejects disputes — remember to unpause
276
+ - **Past deadline**: Set future timestamps only
277
+ - **Empty reset feedback**: Explain why revision needed
278
+ - **Early withdrawal**: Wait for Finished state or 30-day timer
279
+ - **Unverified evidence**: Always verify WTS before using