@wowok/skills 2.2.3 → 3.0.0

package/examples/Insurance/Insurance.md

@@ -314,10 +314,10 @@ clock > progress.current_time + 10000
 
 **Guard Table**:
 
-| identifier | b_submission | value_type | value | Purpose |
-|------------|-------------|-----------|-------|---------|
-| 0 | **true** | Address | (submitted at runtime) | Order ID submitted at runtime, converted to Progress via convert_witness |
-| 1 | false | U64 | 10000 | Time-lock duration in ms (10 seconds for testing) |
+| identifier | b_submission | value_type | value | name | Purpose |
+|------------|-------------|-----------|-------|------|---------|
+| 0 | **true** | Address | (submitted at runtime) | Order ID (submitted at runtime) | Order ID submitted at runtime, converted to Progress via convert_witness |
+| 1 | false | U64 | 10000 | lock_duration_ms | Time-lock duration in ms (10 seconds for testing) |
 
 > **Important**: `10000` ms (10 seconds) is for testing only. In production, set to a reasonable duration (e.g., 8 hours = 28800000 ms).
 
@@ -1107,7 +1107,78 @@ Fill in the `value` field with the Order ID (or Order name) and resubmit. The `s
 > - Replace `0xfb8bed2f...` with the actual `insurance_withdraw_guard_treasury_v1` address from your Phase 1 response.
 > - The `value` field accepts either an on-chain object ID or a named object reference (e.g., `"test_insurance_order_v1"`).
 > - The `sharing` configuration (`{"Entity": "insurance_treasury_v1"}` at 100% Rate) determines where funds flow. Funds go to the fixed Treasury address regardless of who calls the allocation — this is the safe Entity-sharing pattern that prevents fund theft.
-> - After a successful withdrawal, the Allocation `balance` becomes `0` and a Payment object is created as an immutable record.
+> - After a successful withdrawal, the Allocation `balance` becomes `0`, a Payment object is created as an immutable record, and the recipient receives the funds as a **CoinWrapper** object (owned but NOT yet spendable). Complete Step 12 to unwrap it into spendable balance.
+
+---
+
+## Step 12: Receive Funds (Unwrap CoinWrapper — Single Action)
+
+After `alloc_by_guard` distributes funds, each recipient receives a `CoinWrapper<T>` object — owned but not spendable. **The tool auto-unwraps in ONE action**: no need to query CoinWrapper IDs first, and no need to specify the coin type — received CoinWrappers are auto-enumerated and their inner token type (`CoinWrapper<T>`) is auto-derived on-chain.
+
+Choose the variant matching the recipient (Treasury approach → 12.1; personal approach → 12.2).
+
+### 12.1 Treasury Recipient (Approach 1)
+
+**Prompt**: Receive recently arrived funds into "insurance_treasury_v1".
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "treasury",
+    "data": {
+      "object": "insurance_treasury_v1",
+      "receive": "recently"
+    },
+    "env": {
+      "account": "insurance_provider_v1",
+      "network": "testnet"
+    }
+  }
+}
+```
+
+> **How it works**: `receive: "recently"` auto-queries every `CoinWrapper` received by the Treasury and deposits them into the Treasury balance in a single transaction. The Treasury's token type (`0x2::wow::WOW`) must match the CoinWrapper's inner type (validated automatically).
+
+### 12.2 Personal Recipient (Approach 2)
+
+**Prompt**: Unwrap all CoinWrappers owned by "insurance_provider_v1" into spendable balance.
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "payment",
+    "data": {
+      "receive": true
+    },
+    "env": {
+      "account": "insurance_provider_v1",
+      "network": "testnet"
+    }
+  }
+}
+```
+
+> **How it works (AUTO-RECEIVE)**: with `receive: true` and `object` omitted, the tool unwraps **every** CoinWrapper currently owned by the caller via `payment::unwrap_to_myself` in a single transaction, deleting the wrappers and transferring the underlying coins to the caller. The coin type is auto-derived from each wrapper's own on-chain type — `type_parameter` is only needed if auto-derivation fails.
+>
+> **Optional — unwrap a specific wrapper only**: pass `"object": "<coinwrapper_id_or_name>"` instead of omitting it.
+
+### Verify Funds Received
+
+```json
+{
+  "tool": "query_toolkit",
+  "data": {
+    "query_type": "account_balance",
+    "name_or_address": "insurance_treasury_v1",
+    "network": "testnet",
+    "no_cache": true
+  }
+}
+```
+
+The Treasury (or personal) balance should now include the withdrawn `100000000` MIST (0.1 WOW). For the personal approach, query `"insurance_provider_v1"` instead.
 
 ---
 
@@ -1171,3 +1242,4 @@ Published Machine nodes are immutable (`MoveAbort code: 3`). Create a new Machin
 - [ ] Step 10.2: Advance progress Initial -> Start
 - [ ] Step 10.3: Advance progress Start -> Complete with submission (wait 10s after Step 10.2)
 - [ ] Step 11: Withdraw funds via Allocation (alloc_by_guard with Treasury or personal withdraw guard)
+- [ ] Step 12: Receive funds (Treasury: `receive: "recently"` / Personal: `payment {receive: true}`) and verify balance

package/examples/MyShop/MyShop.md

@@ -426,6 +426,8 @@ Create a Contact object to enable encrypted communication between customers and
 }
 ```
 
+> **Note**: Enabling messenger now registers the account on the messenger server **immediately and synchronously** — each account registers itself (its own identity, its own keys). The result includes `registered: true` on success, or `registered: false` with `registerError` if the server is unreachable (the background refresh retries automatically every 60s). If the operation result shows `registered: false`, retry the enable operation before proceeding — otherwise the counterpart's first message will fail with "Recipient not registered".
+
 #### 4.2 Create After-Sales Contact Object
 
 **Prompt**: Create a Contact object named "myshop_aftersales_contact_v2" with permission "myshop_permission_v2" for after-sales support.
@@ -1086,6 +1088,8 @@ After creating the order, the customer sends their shipping address and contact
 }
 ```
 
+> **Note**: Same as merchant enable (Step 4.1): registration on the messenger server happens synchronously with the enable. Each party must enable messenger **in its own environment with its own account** — one side can never register the other.
+
 #### 2.1.2 Customer Sends Shipping Information
 
 **Prompt**: Customer "myshop_customer" sends shipping address and contact information to merchant "myshop_merchant" via encrypted messenger.

package/package.json

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

package/wowok-arbitrator/SKILL.md

@@ -42,7 +42,7 @@ These four principles govern every arbitration build/handle step. They mirror th
 
 1. **Review-first**: State (a) what the AI understood about the arbitration, (b) the dependency order to build, 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. **Reuse / Customize / Discover (三选一)**: For every component (Permission, Voting/Usage Guards, Contact), surface all three avenues — reuse an existing object, customize a new one, or discover from other projects / the system.
+3. **Reuse / Customize / Discover (choose one of three)**: For every component (Permission, Voting/Usage Guards, Contact), surface all three avenues — reuse an existing object, customize a new one, or discover from other projects / the system.
 4. **Default-config disclosure**: Disclose a new object's default config + important info + caveats BEFORE the user decides. No silent defaults.
 
 ---

package/wowok-onboard/SKILL.md

@@ -53,7 +53,7 @@ These four principles govern EVERY round. They are non-negotiable and replace th
 
 1. **Review-first**: Before the first user choice, the AI MUST output a review that states (a) its understanding of the user's task, (b) the dependency-chain overview, and (c) the interaction contract. Only AFTER this review is the first choice presented.
 2. **User-driven**: Every round is driven by an explicit user decision. The AI provides a `recommend` option but NEVER auto-advances. The user may pause at any important round to ask questions.
-3. **Reuse / Customize / Discover (三选一)**: For every component (Permission, Machine, Guard, Contact, Treasury, Arbitration, etc.), the AI MUST present three avenues — **reuse an existing object** (with its benefit), **customize a new object** (with its sub-task ability), or **discover an object** from other projects / the system. All three are mandatory to surface.
+3. **Reuse / Customize / Discover (choose one of three)**: For every component (Permission, Machine, Guard, Contact, Treasury, Arbitration, etc.), the AI MUST present three avenues — **reuse an existing object** (with its benefit), **customize a new object** (with its sub-task ability), or **discover an object** from other projects / the system. All three are mandatory to surface.
 4. **Default-config disclosure**: Before creating any new object, the AI MUST disclose the default configuration and important information (purpose, key settings, caveats), then let the user decide. No silent defaults.
 
 ---
@@ -230,8 +230,8 @@ Each round below lists: **Semantic meaning**, **Core elements to confirm**, **De
 - **Core elements to confirm**:
   - **Test account**: which account places the order — default is the **service-creation account**, but the user may choose another account to simulate a buyer.
   - **Advance path**: at each node, the user chooses which next node to advance to.
-- **Per-node disclosure (before each advance)**: the MCP injects `semantic.workflow_guidance` (on query_toolkit Progress results: `_workflow_guidance` / `_workflow_guidance_text`) listing **ALL** reachable next nodes with their operator (`namedOperator=""` → order holder / `permissionIndex` → role / named operator), forward, weight, guard, business meaning, and a K3-framed recommendation (gains/risks/consistency). Relay this full list to the user (who can act, with which permission/account), then let the user choose — **AI 推荐、人决策** (K3 P3).
-- **After each advance**: relay `semantic.workflow_receipt` — which account did what, whether the node migrated; if it did NOT migrate and threshold > 0, report threshold / accumulated weight / remaining / who must act next (K3 G4 阈值配合).
+- **Per-node disclosure (before each advance)**: the MCP injects `semantic.workflow_guidance` (on query_toolkit Progress results: `_workflow_guidance` / `_workflow_guidance_text`) listing **ALL** reachable next nodes with their operator (`namedOperator=""` → order holder / `permissionIndex` → role / named operator), forward, weight, guard, business meaning, and a K3-framed recommendation (gains/risks/consistency). Relay this full list to the user (who can act, with which permission/account), then let the user choose — **AI recommends, human decides** (K3 P3).
+- **After each advance**: relay `semantic.workflow_receipt` — which account did what, whether the node migrated; if it did NOT migrate and threshold > 0, report threshold / accumulated weight / remaining / who must act next (K3 G4 threshold coordination).
 - **Default config**: test account = service-creation account.
 - **Reuse / Customize / Discover**: n/a (verification).
 - **Dependencies**: Service published (R11) — `order_new` requires `bPublished=true`.

package/wowok-order/SKILL.md

@@ -3,9 +3,9 @@ name: wowok-order
 description: |
   WoWok Buyer Guide — TWO lifecycles in one skill:
 
-  1. PROSPECT (潜在用户尽调, pre-purchase): E1-E11 due diligence + consensus
+  1. PROSPECT (prospect due diligence, pre-purchase): E1-E11 due diligence + consensus
      building + trust-score synthesis, ending in a buy/no-buy decision.
-  2. CUSTOMER (已下单履约, post-order): order creation, progress advancement,
+  2. CUSTOMER (in-order fulfillment, post-order): order creation, progress advancement,
      fund management, and arbitration.
 
   For suppliers presenting to Demands, see wowok-supplier. For process
@@ -32,8 +32,8 @@ when_to_use:
 
 | Lifecycle | Role | Phases | Ends with |
 |-----------|------|--------|-----------|
-| **Prospect** (潜在用户尽调) | You have NOT ordered yet | Phase 1 (E1-E11) + Phase 2 | buy / no-buy decision |
-| **Customer** (已下单履约) | You are the Order `builder` | Phase 3-6 + Fund Management | funds withdrawn / dispute resolved |
+| **Prospect** (prospect due diligence) | You have NOT ordered yet | Phase 1 (E1-E11) + Phase 2 | buy / no-buy decision |
+| **Customer** (in-order fulfillment) | You are the Order `builder` | Phase 3-6 + Fund Management | funds withdrawn / dispute resolved |
 
 The prospect lifecycle is served primarily by MCP `trust_score` (`depth: "preorder"`) and the plug-in `evaluation_operation` — this skill keeps the dialogue flow. The customer lifecycle is on-chain (Order/Progress/Allocation/Arb).
 

package/wowok-output/SKILL.md

@@ -14,23 +14,55 @@ always: true
 
 # Address Display Rules
 
-## Override Condition
+## Environment split (read first)
 
-If user explicitly requests full/long addresses (e.g., "show full addresses", "do not abbreviate"),
-this skill's shortening rules are DISABLED — display complete 66-character addresses.
+Address rendering differs by environment — pick the correct mode:
 
-## Client Rendering (authoritative)
+| Environment | Default display | Full address |
+|---|---|---|
+| **WoWok client** (rich renderer available) | Full address — the client converts it into an address chip (name, DEFAULT badge, type icon, popup) | Always |
+| **Other AI clients** (plain MCP clients, markdown only) | Name when resolved, otherwise SHORTID; DEFAULT marker on the default account | ONLY when the user explicitly asks |
+
+Rules that hold in BOTH environments:
+- **NEVER truncate with `…`** (e.g. `0x00f6…a5839` is FORBIDDEN). It is neither a valid full address nor a valid SHORTID — it cannot be resolved, copied, or acted on. The only compact form allowed is the SHORTID transform defined below.
+- The full 66-character address is ALWAYS present in the tool results injected into your context — nothing is lost when you display a name/SHORTID; you can produce the full address on request.
+
+## Inside the WoWok client (rich rendering — authoritative)
+
+The client renders EVERY complete `0x`-prefixed address in your reply
+automatically as the canonical address chip — local name, DEFAULT badge,
+first-byte object-type icon, and hover popup (Explorer / Analyze / AI / copy).
+
+Therefore:
+- Write the full address in prose OR in inline code — both become chips.
+- Do NOT attach names, labels, short ids, or parentheses to an address (no `(default)`, no `Name 0x<full-address>`); the client resolves and renders name/type/DEFAULT state itself.
 
-Inside the WoWok client, AI replies render every `0x…` address AUTOMATICALLY as
-the canonical address pill — local name (if any), system short id, auto-resolved
-object-type icon, and hover actions (copy / message / AI / on-chain query).
-Therefore: **write full `0x`-prefixed addresses in replies**; the client does the
-display formatting. The text rules below apply only to plain-text contexts
-where the client renderer is unavailable (CLI, raw logs).
+## Other AI clients (generic MCP clients — plain markdown, no custom renderer)
 
-## Short Address Format
+External clients render standard markdown only (no popup, no chips). Default to
+a CONCISE display — full 66-char addresses are noisy and are not shown unless
+asked:
 
-**MUST APPLY TO ALL ADDRESSES AND OBJECT IDs** (0x prefix + up to 64 hex chars).
+- **Named** (account name or local_mark resolved via `local_names` / tool
+  results): show the NAME ONLY, e.g. `alice_wallet`. Never append an id.
+- **Unnamed**: show the SHORTID (format below), e.g. `10EF-A11`.
+- **Default account** (the on-chain default account, which has an empty name):
+  mark it as `(default)`, e.g. `(default) 10EF-A11`.
+- In tables: name or SHORTID in the cell; the full address is omitted by default.
+- **Full address on request**: when the user explicitly asks to see full /
+  detailed / complete addresses ("show the full address", "give me the complete
+  address", "copyable address"), output the COMPLETE `0x` + 64 hex chars
+  wrapped in inline code so it is one-click copyable in any markdown client.
+  When a name is known, put name + full address together:
+  **alice_wallet** `0xFULLADDRESS`.
+
+## User override
+
+- Other clients, "show full / long / complete addresses" → output the full inline-code address for that reply.
+- Other clients, "use short / compact" → SHORTID (already the default for unnamed addresses).
+- WoWok client: always full addresses regardless — the chip renderer handles display.
+
+## SHORTID format
 
 System-wide rule (identical to the client's `formatAddress`):
 1. Remove the `0x` prefix → hex string
@@ -40,28 +72,25 @@ System-wide rule (identical to the client's `formatAddress`):
 5. Empty / missing → `--`
 
 **Examples**:
-| Full Address | Short ID | Rule |
+| Full Address | SHORTID | Rule |
 |---|---|---|
 | `0xa1d421902a3e5f2e4da7590e8f243712b3b3479d1a07c48c2de543184fc97a33` | `A1D4-A33` | first 4 + `-` + last 3 |
 | `0x10ef0000000000000000000000000000000000000000000000000000000cda11` | `10EF-A11` | first 4 + `-` + last 3 |
 | `0x2` | `2` | ≤7 chars, as-is |
 
-## Resolution Priority & Display Format
+## Resolution priority
 
 **Query Tool**: `query_toolkit` with `query_type: "local_names"`
 
 Returns: `{ account?: string, local_mark?: string, address: string }`
 
-### Display Format Rules (STRICT — mirrors the client's `displayLabelOf`)
-
-| Condition | Display Format | Example |
-|-----------|----------------|---------|
-| **Named** (account or local_mark resolved) | `{name}` only — NEVER append the short id | `alice_wallet` |
-| **Unnamed** | `{SHORTID}` | `10EF-A11` |
-
-- A named object shows ONLY its name — no parentheses, no short id after it.
-- When both an account name and a local_mark exist, prefer the local_mark
-  (object names) for objects and the account name for user addresses.
+- Named (account or local_mark resolved): display the name ONLY (WoWok client
+  renders the name chip itself; other clients show the name).
+- Unnamed: WoWok client → full address (chip); other clients → SHORTID.
+- The account with an empty name that is the on-chain default → other clients
+  tag it `(default)`; the WoWok client adds its DEFAULT badge automatically.
+- When both an account name and a local_mark exist, prefer local_mark (object
+  names) for objects and the account name for user addresses.
 
 ---
 
@@ -107,11 +136,12 @@ Supported query types with `_money_display`:
 ```
 | # | Time | Sender | Service | Amount | Order |
 |---|------|--------|---------|--------|-------|
-| 1 | {time} | {name-or-SHORTID} | {name-or-SHORTID} | {amount} | SHORTID |
+| 1 | {time} | {addr-cell} | {addr-cell} | {amount} | {addr-cell} |
 ```
 
-**Note**: `{name-or-SHORTID}` follows Display Format Rules above — name ONLY when
-resolved, otherwise the short id (no parentheses in either case).
+**Address cells follow the environment split above**:
+- WoWok client → the cell contains the full address (rendered as an address chip automatically).
+- Other clients → the cell contains the resolved name or the SHORTID (default account tagged `(default)`); full addresses only when the user explicitly asked for them.
 
 ## Event Type Fields
 
@@ -134,7 +164,7 @@ When user asks about field meanings:
 - **Sender**: Account that initiated the transaction
 - **Service**: Service object being ordered/interacted with
 - **Order Object**: Unique on-chain identifier for this order
-- **Short Address**: System-wide shortened id for quick visual identification — first 4 + `-` + last 3 hex chars, uppercase (see Short Address Format rules)
+- **Short Address (SHORTID)**: Compact display form (first 4 + `-` + last 3 hex chars, uppercase). Default for unnamed addresses in other AI clients; the WoWok client applies it automatically inside its address chips. Never hand-truncate with `…`.
 
 ## Amounts
 - **Raw**: Actual U64 integer stored on-chain
@@ -154,7 +184,10 @@ When user asks about field meanings:
 - [ ] Query `local_names` for resolution
 - [ ] Check for `_money_display` annotations in query results (primary amount source)
 - [ ] If `_money_display` absent, query `token_list` for manual amount formatting
-- [ ] Apply address format rules
+- [ ] Address display: WoWok client → full `0x`+64 hex addresses (auto chips);
+      other clients → resolved name, or SHORTID for unnamed / `(default)` for the
+      default account; full inline-code address only when the user asks
+- [ ] Never hand-truncate addresses with `…` — SHORTID is the only compact form
 - [ ] Apply amount format rules (use `_money_display` first; fallback to conservative)
 - [ ] Render final output
 

package/wowok-provider/SKILL.md

@@ -48,7 +48,7 @@ These four principles govern every service build/modify step. They mirror the wo
 
 1. **Review-first**: State (a) what the AI understood about the service, (b) the dependency order to build/modify, 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. The user may pause at any important step.
-3. **Reuse / Customize / Discover (三选一)**: For every component (Permission, Machine, Guard, Treasury, Contact, Arbitration, etc.), surface all three avenues — reuse an existing object (benefit), customize a new one (sub-task ability), or discover from other projects / the system.
+3. **Reuse / Customize / Discover (choose one of three)**: For every component (Permission, Machine, Guard, Treasury, Contact, Arbitration, etc.), surface all three avenues — reuse an existing object (benefit), customize a new one (sub-task ability), or discover from other projects / the system.
 4. **Default-config disclosure**: Disclose a new object's default config + important info + caveats BEFORE the user decides. No silent defaults.
 
 ---

package/wowok-supplier/SKILL.md

@@ -55,7 +55,7 @@ Your payment is a two-hop waterfall: main order escrow → allocation → your s
 
 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. **Reuse / Customize / Discover (三选一)**: For every component (service, passport, guard), surface reuse / customize / discover.
+3. **Reuse / Customize / Discover (choose one of three)**: For every component (service, passport, guard), surface reuse / customize / discover.
 4. **Default-config disclosure**: Disclose defaults + caveats BEFORE the user decides.
 
 ---