@wowok/skills 3.0.3 → 3.0.4

package/examples/MyShop_Advanced/MyShop_Advanced.md

@@ -2764,6 +2764,12 @@ If customer doesn't return within 10 days, merchant can mark as Return Fail.
 
 ## Part 4: Fund Allocation
 
+> **IMPORTANT — Per-order Allocation**: Every order created via `service order_new` gets its **own** `Allocation` object (the Service-level `myshop_allocation_v2` is only the allocator **template** — it holds no funds). The order's escrow lives at the address in the Order's `allocation` field. `alloc_by_guard` MUST target that **per-order Allocation**, not the service-level one — otherwise the transaction aborts with `Insufficient balance` (abort code 7 in `allocation::alloc`).
+>
+> Resolve it from the Order object: query `myshop_order_v2` → read its `allocation` field (e.g. `0x1db0a7c9...`) → use that address as `object` below.
+>
+> **CoinWrapper claim (auto since SDK 2026-09)**: `alloc_by_guard` pays each recipient a `CoinWrapper` object (contract-side escrow, `payment::transfer_multi_imp`). The SDK **auto-claims the wrappers this tx created for the signer** (`payment::unwrap_to_myself`) right after the alloc commits — for the Signer-recipient refund case the tokens land directly in the caller's wallet in one logical operation. Manual claim (`operation_type: "payment"` `{object: "<coinwrapper_id>", receive: true}`) is only needed for legacy/historical wrappers or wrappers received from another party's transaction. Object recipients (Order escrow / Treasury) claim through their own receive entries (`order receive` / `treasury receive`) as before.
+
 ### Merchant Wins (Order Complete, Wonderful, Return Fail)
 
 When order reaches Order Complete, Wonderful, or Return Fail, merchant can withdraw funds.
@@ -2776,7 +2782,7 @@ When order reaches Order Complete, Wonderful, or Return Fail, merchant can withd
   "data": {
     "operation_type": "allocation",
     "data": {
-      "object": "myshop_allocation_v2",
+      "object": "<order_allocation_address — from myshop_order_v2.allocation>",
       "alloc_by_guard": "service_merchant_win_v2"
     },
     "env": {
@@ -2822,7 +2828,7 @@ When order reaches Lost or Return Complete, customer can withdraw funds.
   "data": {
     "operation_type": "allocation",
     "data": {
-      "object": "myshop_allocation_v2",
+      "object": "<order_allocation_address — from myshop_order_v2.allocation>",
       "alloc_by_guard": "service_customer_win_v2"
     },
     "env": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "WoWok AI Skills for Claude and other AI assistants - Dialogue orchestration layer on top of the WoWok MCP server (rules/reference knowledge is served by MCP directly since v2.0.0)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,8 @@
     "wowok-onboard/",
     "wowok-planner/",
     "wowok-auditor/",
+    "wowok-governance/",
+    "wowok-market/",
     "examples/",
     "scripts/install.js",
     "README.md",

package/scripts/install.js

@@ -41,6 +41,7 @@ const SKILL_DIRS = [
   'wowok-supplier',
   'wowok-collaborator',
   'wowok-market',
+  'wowok-governance',
 ];
 
 /**

package/wowok-governance/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wowok-governance
+description: |
+  WoWok Governance — the canonical skill for on-chain permission, data, and
+  financial governance: the account that OWNS the objects keeps them healthy
+  after setup.
+
+  Covers Permission lifecycle (indexes, role assignment, entity table, admin
+  transfer), Treasury/Allocation fund stewardship (deposit/withdraw, history
+  audit, unclaimed payments), and Personal data boundaries (public identity,
+  profile records). Governance is a continuous loop — inventory, decide,
+  execute, audit — not a one-time setup.
+
+  For building services, see wowok-provider. For market operations, see
+  wowok-market.
+when_to_use:
+  - User wants to manage who can operate their objects (permission indexes, entity table)
+  - User wants to deposit/withdraw treasury funds or audit fund history
+  - User has unclaimed payments or wants to check claimable balances
+  - User wants to update their public on-chain profile or personal data
+  - User mentions "permission", "treasury", "governance", "manage assets", "audit funds"
+role: shared
+loading: on-demand
+related:
+  - wowok-provider
+  - wowok-market
+  - wowok-messenger
+---
+
+# WoWok Governance Guide
+
+> **Role**: Object owner/admin — the account that carries administrative responsibility for Permission, Treasury, and Personal objects
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (service build), [wowok-market](../wowok-market/SKILL.md) (market ops), [wowok-messenger](../wowok-messenger/SKILL.md) (contact)
+
+---
+
+## MCP Knowledge Layer
+
+The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill does NOT duplicate it:
+
+| Content | Access via (MCP action) | Applied Via |
+|---------|--------------------------|-------------|
+| Permission safety rules (owner/admin/entity hierarchy) | `schema_query` action='get_safety_rules' | `onchain_operations` permission |
+| Treasury/Permission/Personal object schema | `schema_query` action='get_schema' | governance operations |
+| Unclaimed-payment detection | `keeper_operation` (payment_unclaimed scan) | monitor loop |
+| Fund-flow event meanings (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) | event semantic registry | audit & monitor |
+
+This Skill keeps the governance **conversation flow** — what to inventory, what to decide, what to execute, and how to audit.
+
+---
+
+## Governance Is a Loop, Not a Setup
+
+Inventory → Decide → Execute → Audit. Governance objects are LIVE: a permission change takes effect on the next call, a withdraw is irreversible, a personal profile record is permanently public. Every change deserves an audit pass after execution.
+
+---
+
+## Domain 1: Permission Governance
+
+A Permission object defines WHO can perform WHICH operations on your business objects (Service / Machine / Treasury …).
+
+- **Indexes** (`permission.index_create`): create named role indexes (e.g. operator=1, finance=2) before assigning.
+- **Role assignment** (`permission.role_assign`): bind indexes onto target objects — a mis-assigned role grants unintended operational authority immediately.
+- **Entity table**: add/remove addresses per index. Review-first: list current entities before mutating (`query_objects` on the Permission object).
+- **Audit**: `query_toolkit` query_type='onchain_table_item_permission_perm' checks what a specific address may do; query_type='address_profile' shows an address's permission memberships across all objects.
+
+Rules of thumb:
+- One Permission per business object family; reuse named indexes, don't proliferate unnamed ones.
+- Removing an entity is immediate — the next operation by that address fails with "Permission denied" (abort code 5).
+- Admin transfer is a high-trust operation: the new admin controls the whole table.
+
+---
+
+## Domain 2: Financial Governance
+
+Fund stewardship across Treasury / Allocation / Reward / Payment.
+
+- **Treasury**: deposit joins coins in (a Payment receipt is minted); withdraw splits balance out — irreversible, and when an `external_guard` is set the guard must validate first. `query_toolkit` query_type='onchain_table_item_treasury_history' audits every flow (op 0 Withdraw / 1 Deposit / 2 Receive) with amount + guard + timestamp.
+- **Allocation**: runs distribute pool funds per sharing mode (Amount / Rate ‰ / Surplus). Review allocator guards periodically — a stale guard blocks legitimate distributions.
+- **Unclaimed payments**: recipients hold frozen CoinWrappers until they unwrap. The keeper `payment_unclaimed` scan owns this reminder surface — run `keeper_operation` to list claimable payments and nudge recipients via Messenger. NewPaymentEvent is deliberately NOT push-bridged, to avoid duplicate reminders (P2-4 channel split).
+- **Reward pools**: RewardFundEvent in / RewardClaimEvent out; a dry pool blocks claims — watch balances before announcing campaigns.
+
+---
+
+## Domain 3: Data Governance
+
+- **Personal profile** (`personal` operations): your public on-chain identity. Everything here is PERMANENTLY PUBLIC — never anchor private data. Review-first: show the current record before every mutation.
+- **Entity info**: description/info updates re-emit NewEntityEvent — counterparties' cached profiles refresh; keep descriptions accurate.
+- **Repository data**: contribution/usage policies are designed at Repository level (see wowok-provider); governance audits consumption through the event stream.
+
+---
+
+## Monitor Loop
+
+Governance goals close the loop through three channels:
+
+- **Push**: fund-flow events (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) become goal-bound suggestions via SuggestionBridge.
+- **Pull**: keeper scans (payment_unclaimed, balance thresholds) repeat reminders until resolved.
+- **Audit**: after every governance write, re-query the object and confirm the post-state matches the intent.
+
+---
+
+## Core Interaction Principles
+
+1. **Review-first**: always show current state + the exact delta before executing.
+2. **User-driven**: surface options, never auto-execute — withdraw and admin transfer are irreversible.
+3. **Disclose irreversibility**: say it explicitly for withdraw, admin transfer, and any personal-data write.
+4. **Audit after**: every governance write ends with a re-query confirmation.
+
+## Quick Reference
+
+- Permission: indexes → role assignment → entity table; audit via permission_perm + address_profile.
+- Treasury: deposit/withdraw + history audit; external_guard gates withdrawals.
+- Unclaimed payments: keeper scan owns reminders; recipients unwrap CoinWrappers.
+- Personal data: permanently public — review before every write.

package/wowok-market/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: wowok-market
+description: |
+  WoWok Market — the canonical skill for market discovery and operations. It
+  covers the "matchmaking + operations" layer (K3 13/14/15): how a demand finds
+  candidate services, how a merchant picks a trustworthy arbitrator, how the
+  account's on-chain attention is surfaced, and how the market is measured and
+  governed.
+
+  Covers match_discover / discover_services / discover_demands (discovery),
+  arbitration_score (trust selection), account_events (attention), market_metrics
+  (supply/demand/trust), anti_cheat (governance), market_operations (journey
+  funnel / referral / CRM), and category match rules.
+
+  For the merchant who owns a Service, see wowok-provider. For the customer
+  placing an order, see wowok-order. For the arbitrator, see wowok-arbitrator.
+when_to_use:
+  - User wants to discover services for an intent ("find a plumber in Shanghai")
+  - Merchant wants to discover open Demands to present to
+  - Merchant wants to pick/compare arbitrators (arbitration_score)
+  - User wants their on-chain attention items surfaced (account_events)
+  - User wants market metrics / anti-cheat signals / journey funnel / referral / CRM
+  - User mentions "market", "match", "discover", "matchmaking", "operations", "funnel", "referral", "customer relationship"
+---
+
+# WoWok Market Guide
+
+> **Role**: Market discovery & operations (matchmaking + Observe layer)
+> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (merchant), [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (arbitrator), [wowok-supplier](../wowok-supplier/SKILL.md) (demand presenter)
+
+---
+
+## MCP Knowledge Layer
+
+The matching/routing/aggregation logic is pushed down to MCP and applied automatically — this Skill does NOT duplicate it. All market actions live under `evaluation_operation`:
+
+| Capability | MCP action | Purpose |
+|------------|------------|---------|
+| Service discovery (intent → candidates) | `match_discover` / `discover_services` | enumerate + location gate + 6-dim score |
+| Demand discovery (merchant → open demand) | `discover_demands` | enumerate shared Demands |
+| Arbitrator trust selection | `arbitration_score` | dual-perspective trust/fairness |
+| Account attention | `account_events` | unread messenger / collectible / arbitrable |
+| Market metrics | `market_metrics` | supply / demand / trust counts |
+| Anti-cheat | `anti_cheat` | fake order / fake review / shell merchant |
+| Operational aggregation | `market_operations` | journey funnel / referral / CRM |
+
+This Skill keeps the **market conversation flow** — discover → compare → trust → act → measure. The MCP layer handles enumeration, scoring, and chain-derived aggregation.
+
+---
+
+## Core Interaction Principles
+
+1. **Review-first**: State (a) what the AI understood, (b) the decision order, and (c) the interaction contract — before the first choice.
+2. **User-driven**: Every step is an explicit user decision; the AI provides a `recommend` but never auto-advances.
+3. **Neutrality**: the AI surfaces trade-offs and scores, never chooses the branch for the user.
+
+---
+
+## Phase 1: Discover (intent → candidates)
+
+**Demand side** — `evaluation_operation` action=`match_discover`:
+- Provide `description` + `location` (+ optional `budget`, `required_capabilities`, `category`).
+- Returns location-gated, 6-dimension-scored services + recommendation reasons.
+- `category` (e.g. `life_service` / `retail`) applies hard-constraint filtering + weight re-anchoring (K3 15 §3).
+
+**Merchant side** — `evaluation_operation` action=`discover_demands`:
+- Enumerate open Demands (optional `location` filter).
+- A Demand carries rewards (incentive pointers); read the Reward objects by id for amounts.
+
+---
+
+## Phase 2: Compare & Trust
+
+- **Compare**: the `match_discover` result already surfaces per-service scores + reasons. Surface the top-N side-by-side; highlight differences, never force a single pick.
+- **Arbitrator trust**: `evaluation_operation` action=`arbitration_score` with the Arbitration `object` (history auto-fetched via `query_arbs`). Returns `trust` + `fairness` + `combined`. Use it when a merchant chooses which Arbitration to bind, or a customer judges a Service's arbitration guarantee.
+
+---
+
+## Phase 3: Act
+
+- **Attention**: `evaluation_operation` action=`account_events` with the account — surfaces actionable items (unread messages, collectible payments, demand presented). Let the user act on each, never auto-act.
+- **Discovery → order**: hand off to [wowok-order](../wowok-order/SKILL.md) for due diligence + order placement once the user picks a service.
+
+---
+
+## Phase 4: Measure & Govern
+
+- **Metrics**: `evaluation_operation` action=`market_metrics` → active services / open demands / disputes / supply-demand ratio.
+- **Anti-cheat**: `evaluation_operation` action=`anti_cheat` with a Service's orders/reviews/object-stack → returns negative-factor signals (fake order / fake review / shell merchant).
+- **Operations**: `evaluation_operation` action=`market_operations` with `op` = `journey_funnel` / `referral_attribution` / `customer_relationship`.
+
+---
+
+## Design Principles
+
+- **Events signal opportunities only**: chain events are emitted only for participatable/profitable opportunities (K3 13 §6.7) — not for create/pause/noise.
+- **Read the object for authority**: event previews (description ≤260 chars, reward addresses) are routing hints; amounts and authoritative state are read from the object by id.
+- **No fabricated matching**: always run the MCP enumeration/scoring; never invent candidates or scores.