@wowok/skills 3.2.0 → 3.2.1

package/wowok-messenger/SKILL.md

@@ -2,221 +2,99 @@
 name: wowok-messenger
 description: "WoWok Messenger — end-to-end encrypted communication for pre-order negotiation, evidence collection, and dispute resolution. Core features: send/receive encrypted messages, generate WTS evidence files, verify message authenticity, manage conversations with anti-spam controls, and integrate with arbitration workflows. Used by customers, service providers, and arbitrators for secure off-chain communication that creates tamper-proof audit trails. Use when: User needs to communicate with another party (buyer, seller, arbitrator); User wants to send encrypted messages for negotiation; User needs to generate WTS evidence files from conversations; User wants to verify message authenticity; User needs to manage conversation lists (friends, blacklist, guard); User mentions \"messenger\", \"message\", \"chat\", \"communication\", \"WTS\", \"evidence\"."
 metadata:
-  version: "2.0.0"
+  version: "2.1.0"
   role: shared
   related: "wowok-order, wowok-provider, wowok-arbitrator"
 ---
 
 # WoWok Messenger Guide
 
-End-to-end encrypted messaging with tamper-proof audit trails.
+End-to-end encrypted off-chain messaging with tamper-proof audit trails.
 
-> **Role**: Any WoWok participant
-> All 18 operations with full parameter types and constraints are in the MCP schema (`messenger_operation`) — query it via `schema_query` action='get' name='messenger_operation' before an unfamiliar call. This document focuses on **design decisions, timing, and cross-role strategy** not captured by the schema.
-> **Related Skills**: [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (WTS evidence in disputes), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-provider](../wowok-provider/SKILL.md) (service provider perspective)
-> Guard design patterns and safety rules live in the MCP knowledge layer — query via `schema_query` actions `get_guard_design_patterns` / `get_safety_rules`; the per-tool action/parameter reference lives there too (`get_tool_reference`).
+> **Role**: any WoWok participant.
+> All 18 operations and exact parameter constraints are authoritative in the MCP schema — `schema_query` action=`get` name=`messenger_operation` before an unfamiliar call. This file covers **timing, evidence discipline, and anti-spam strategy** the schema can't tell you.
+> Guard table design: `schema_query` actions `get_guard_design_patterns` / `get_safety_rules`.
+> Related: [wowok-arbitrator](../wowok-arbitrator/SKILL.md) · [wowok-order](../wowok-order/SKILL.md) · [wowok-provider](../wowok-provider/SKILL.md)
 
 ---
 
-## Core Concepts
+## Core concepts
 
-### Trust Model
-
-Messages are **off-chain**, end-to-end encrypted. The server cannot read content — ciphertext is opaque. The server provides **verifiable message ordering** via Falcon512 signatures on a Merkle tree. On-chain anchoring (`proof_message`) is optional.
-
-### Evidence Closure Principle
-
-> **A message becomes valid evidence ONLY when the recipient explicitly responds to or decrypts it.**
-
-- A message alone proves nothing about the recipient's awareness.
-- ARK confirmation (recipient-signed receipt) creates cryptographic proof of acknowledgment.
-- A reply is the strongest form of acknowledgment — it proves the recipient held the session key and acted on the message.
-- Arbitration requires **confirmed, reciprocated evidence** — never unilateral claims.
-
-### Sessions
-
-Every conversation between two addresses has a deterministic session. Messages are ordered by a monotonically increasing `leafIndex` starting from zero, establishing their absolute position. Both parties share the same session context.
+- **Trust model**: messages are off-chain and E2EE — the server stores opaque ciphertext. Ordering is verifiable: each message carries Merkle-tree data (`leafIndex` from 0, `prevRoot`/`newRoot`) with a server signature; identities use Falcon512 keys. On-chain anchoring (`proof_message`) is optional.
+- **Evidence closure**: a message proves nothing about the recipient until the recipient **responds or decrypts it**. ARK is the recipient-signed receipt (message status `read`); a reply is stronger — it proves the recipient held the session key and acted. Arbitration needs reciprocated evidence, never unilateral claims.
+- **Session**: one deterministic session per address pair, shared by both sides; `leafIndex` gives the absolute position of every message.
 
 ---
 
 ## Setup
 
-Before any communication:
-
-1. **Account must exist** → `account_operation` (gen)
-2. **Enable messenger** → `account_operation` (messenger), set `enabled: true`
-3. **Get your address** → `account_operation` (get) — share this address with your counterparties
+1. Account exists — `account_operation` (gen).
+2. Messenger enabled — `account_operation` `{messenger:{enabled:true, name_or_account}}`, or implicitly via `send_message`/`send_file` option `enable_messenger: true`.
+3. Share the account's address with counterparties (`account_operation` get).
 
-> Messenger must be enabled for message delivery. Without it, your account has no messenger endpoint and cannot receive messages. Account name is used for messenger identity lookup.
+Without an enabled endpoint the account cannot receive. The local SDK enforces a per-device messenger-account cap — do NOT hardcode the number (it is a versioned constant and layers may differ). When enabling throws `Maximum <N> messenger accounts allowed, current count: <M>` (W_ERROR InvalidParam), quote N/M from the error verbatim and offer to disable an unused account (`messenger:{enabled:false}`) to free a slot.
 
-### Account Limit
+### Contact object — the on-chain bridge
 
-A single device supports up to 20 messenger accounts (`MAX_MESSENGER_ACCOUNTS`). Exceeding this returns "Maximum 20 messenger accounts allowed, current count: N". Use `account_operation → messenger { enabled: false }` to disable unused accounts.
-
-### Contact Object (On-Chain Bridge)
-
-The on-chain **Contact** object (`operation_type: "contact"`) is the bridge between a Service and Messenger: `Service.um` → Contact → `ims[]` (Messenger endpoint addresses). Customers query the Contact's `ims[]` to find where to send messages.
-
-**When to create**: before Service publish, when `customer_required` is set (Service.um must point to a Contact). Reuse one Contact across multiple Services sharing the same support channel.
-
-**Timing/gotchas (the mutable-object discipline)**: Contact stays mutable (unlike Proof/Guard); IM mutations require built-in permission index 453 (CONTACT_IM) and emit no events — re-poll `ims[]` after changing it. Before deleting a Contact bound as `Service.um`, clear the binding first or you leave a dangling pointer. Op shapes, limits, and field constraints are authoritative in the schema — `schema_query` action='get' name='contact'.
+`Service.um`/`Arbitration.um` → a Contact → its `ims[]` endpoint addresses. Parties read `ims[]` to find where to send. IM mutations use built-in permission index **453 (CONTACT_IM)**, emit **no events** (re-poll after changes), and the Contact stays mutable (unlike Proof/Guard). Clear the `um` binding before deleting a bound Contact — schema: `onchain_operations_contact`.
 
 ---
 
-## Daily Communication
-
-The user's daily loop — these are the operations they will return to repeatedly.
-
-### Check Inbox
-
-Two approaches, depending on need:
+## Daily loop
 
-- **Quick glance** — `watch_conversations` with `unreadOnly: true` lists all conversations with unread messages, sorted by activity. Each conversation shows a preview of the last messages.
-- **Deep dive** — `watch_messages` with a specific `peerAddress` to view the full conversation with a particular counterparty. Supports keyword search, time-range filtering, direction filter, and status filter.
-- **Server sync** — `pull_messages` fetches the latest messages from the server into local storage (optional `limit` caps batch size). Use this first when the local view looks stale (e.g. after downtime or on a new device session), then read via `watch_conversations` / `watch_messages`. Pass `allAccounts: true` (or `accounts: [...]`, optional `concurrency`, default 5) to fan out across every messenger-enabled account in one call — the result is one entry per account `{account, pulled, messages, error?}` with per-account failure isolation.
+**Read.** `watch_conversations` (`unreadOnly`, previews, sort) for the inbox; `watch_messages` with `peerAddress` for one thread (keyword/direction/status/time/relationship filters, pagination). `pull_messages` syncs from server first when local data looks stale (new device, downtime); `allAccounts:true` fans out bounded concurrency (default 5) with one `{account, pulled, messages, error?}` entry per account. Reads auto-mark viewed — pass `skipAutoMarkViewed:true` to peek.
 
-**Read boundary for attachments**: Attachment messages (those with `zipMetadata`) never expose their base64 payload in `watch_messages` / `watch_conversations` / `pull_messages` output — `plaintext` is omitted and a byte-free `attachment` descriptor is attached instead (`kind`: image/video/audio/voice/file/wts/wip, `fileName`, `mimeType`, `size`, optional `caption`/`durationMs`/`width`/`height`). This prevents multi-megabyte base64 blobs from flooding every read. Bytes are fetched on demand only (see Save Attachments below). Keyword search is a `watch_messages` filter (`keyword`, plus `direction` / `status` / `startTime`-`endTime` filters) — there is no separate search operation.
+**Attachment read boundary.** Messages with `zipMetadata` never include payload bytes in any read op — only a byte-free `attachment` descriptor (`kind` image/video/audio/voice/file/wts/wip, `fileName`, `mimeType`, `size`, optional `caption`/media dims). Fetch bytes on demand with `save_attachment {messageId, outputDir?, saveAs?}` — sha256-verified before extraction, returns the absolute path, original filename restored.
 
-**Design note**: By default, retrieving messages auto-marks them as viewed (`viewedAt` timestamp). Set `skipAutoMarkViewed: true` if you want to peek without marking read.
+**Send.** Text via `send_message` (≤10240 bytes); files/media/evidence via `send_file {filePath}` as an E2EE attachment envelope (encrypted `.wowok-manifest.json` + payload; server sees only `zipMetadata` — transport name/size/sha256/class; media uncompressed, docs/evidence deflated). Options include `kind` (set `voice` explicitly — webm can't be told apart from video), `caption` (E2EE), and `replyTo:{messageId}` for quote-reply (id must exist locally).
 
-### Send Messages
+**First contact with a stranger = exactly one message.** Say who you are, why, and what you need. If delivery is rejected, the error carries `guardList`: get a passport from one of those Guards (`onchain_operations` `gen_passport`) and resend with `options.guardAddress` + `passportAddress` + `network` (Guard messages are a separate data system per network). When the recipient REPLIES, you are auto-added to **their** friends list and messaging opens up.
 
-Plain text via `send_message`; files and media (images, audio, video, voice, documents, WTS/WIP evidence) via `send_file`.
+**Structured sends.**
+- `send_required_info {fields:['phone',…]}` assembles a merchant's `customer_required` LocalInfo fields into one E2EE message (omit `fields` = all; explicit `content` overrides); result reports `sent_fields`. Never send without per-item user confirmation.
+- Evidence-bearing acts inside an active Goal (`send_file` WTS/evidence, `proof_message`) take `goal_id` so they land on the Goal's TaskProcess stream.
 
-**First-time contact with a stranger**: You get exactly one message. Make it count — include who you are, why you're contacting them, and what you need. After the recipient replies, you're auto-added to their friends list and can message freely.
-
-**Guard-protected recipients**: If the recipient has disabled stranger messages, the rejection response includes their `guard_list`. Obtain a passport from one of those guards (`gen_passport` via `onchain_operations`), then resend with `guardAddress` + `passportAddress`.
-
-**Attachments (envelope v2)**: `send_file` transports the file as an E2EE attachment envelope — a zip container with an encrypted `.wowok-manifest.json` (original file name, MIME, kind, caption, media metadata) plus a `payload/<original-name>` entry. The server only sees the unchanged `zipMetadata` (transport file name + size + sha256 + wts/wip/zip class); media (jpg/mp4/webm/…) is stored uncompressed, documents and evidence are deflated. Options: `kind` (media type is auto-inferred from extension; pass `kind: "voice"` explicitly for voice messages — webm cannot be distinguished from video automatically), `mimeType`, `caption` (E2EE, invisible to the server), `durationMs`/`width`/`height`. Old single-entry zips without a manifest remain readable forever (extension/type inference).
-
-**Structured sends**:
-- `send_required_info` — the dedicated path for a Service's `customer_required` fields: pass LocalInfo field names (`fields: ['phone','shipping_address']`) and the op assembles `field: value` lines in one E2E message (explicit `content` overrides; missing fields must be added first via `local_info_operation`). Prefer it over hand-formatting `send_message` — the result also reports `sent_fields`. Never send without the user's per-item confirmation.
-- Quote-reply: pass `options.replyTo: {messageId}` (same conversation; the id must exist in local storage) instead of hand-quoting text.
-- Goal-linked acts: when an evidence-bearing act belongs to an active Goal (e.g. submitting a WTS/evidence file via `send_file`, or anchoring via `proof_message`), stamp `goal_id` so it is recorded as communication evidence on the goal's TaskProcess — omit it for ordinary chatter.
-
-### Save Attachments
-
-- `save_attachment` with `{account?, messageId, outputDir?, saveAs?}` — decode the attachment and persist the **original file** (transport `.zip` suffix stripped; wts/wip keep their extension). Defaults to `<workspace>/attachments`; filename collisions get a ` (1)` suffix; returns the absolute path. The zip blob is sha256-verified against `zipMetadata.fileHash` before extraction. This is the replacement for the retired `extract_zip_messages` — to verify an incoming WTS, save it first, then call `verify_wts` on the returned path.
-- Desktop clients additionally have an in-memory read bridge for inline media rendering (no temp files); AI flows use `save_attachment`.
-
-### Mark as Read
-
-- `mark_conversation_as_viewed` — mark an entire conversation thread as read
-- `mark_messages_as_viewed` — mark specific messages by ID
-
-### Manage Contacts
-
-Three independently managed lists. Schema covers all operations — here are the design choices:
-
-| List | Design Intent |
-|------|---------------|
-| **Friends** | Mutual trust — added automatically when you reply to a stranger, or manually. Friends bypass all spam checks. |
-| **Blacklist** | Permanent block — the address can never message you. |
-| **Guard list** | Verified strangers — addresses holding a valid passport from any listed Guard can message you. Each entry pairs a Guard object ID with a validity duration (`passportValiditySeconds`: 10s to 10 years). |
-
-> **"Friends" are local, not on-chain.** The friends list lives in the Messenger layer (`friendslist` op — server-side, per account) and gates message delivery only. The on-chain carrier is the Contact object's `ims[]` — owner-managed endpoints (permission 453, no request-accept flow). The two NEVER sync: replying to a stranger auto-adds them to YOUR local friends list; it does not touch any Contact. If a business flow needs an on-chain "friend" relationship, that is a contract-level feature request, not a messenger setting.
+**Mark read.** `mark_conversation_as_viewed` (whole thread) or `mark_messages_as_viewed` (1–1000 ids).
 
 ---
 
-## Anti-Spam Strategy
-
-The four-layer protection model evaluates every incoming message: Blacklist (reject) → Friends List (accept) → Guard Verification (accept if passport valid) → Stranger Rules (one-message limit).
-
-This section covers **how to configure these layers intelligently** for different user profiles — configuration combinations, not just field descriptions.
+## Lists & anti-spam
 
-### Stranger Rules
+Three independent **local, per-account** lists (never on-chain, never synced to any Contact):
 
-Messages from non-friend, non-guard-verified addresses are subject to a **one-message limit**:
+| List | Ops | Intent |
+|---|---|---|
+| friends | add/remove/clear/get/exist | Mutual trust; auto-added when you reply to a stranger; friends bypass every gate |
+| blacklist | add/remove/clear/get/exist | Hard block |
+| guard | add/remove/get (max 10 entries) | Holder of a valid passport from a listed Guard may pass; entry `{guard, passportValiditySeconds}` = 10s…10y |
 
-- Stranger sends one message. If the recipient replies, the stranger becomes a friend and messaging is unrestricted.
-- If the recipient does not reply within the cool-down window, the stranger may retry with one new message.
-- `allowStrangerMessages: false` disables stranger messages entirely.
+Delivery evaluates, in order: **blacklist (reject) → friends (accept) → guard passport (accept if valid) → stranger rule**. `settings {op:set, allowStrangerMessages, maxInboxSize}` toggles strangers entirely; the rejection error tells the sender what applies. The stranger window/retry timing is **server policy** — surface the server's rejection message rather than assuming a fixed cooldown; to stop repeat contact, blacklist the address.
 
-### Strategy: Choosing Your Protection Profile
+`watch_messages` segments by relationship: `listFilterMode: friends|guard|stranger|any` (+ `customListFilter` include/exclude). Multiple guards are OR-ed — any one passing passport grants delivery. Match `passportValiditySeconds` to data volatility (payment gates tolerate days; order-state gates should be short) and test every guard with `gen_passport` before publishing it.
 
-The optimal configuration depends on your role and openness needs:
-
-| Profile | Settings | Who Should Use |
-|---------|----------|----------------|
-| **Open** | `allowStrangerMessages: true`, no guard list, empty blacklist | Public-facing services, open marketplaces |
-| **Guarded** | `allowStrangerMessages: false`, guard list with 1-3 guards, friends list for known contacts | Service providers who want verified strangers only; customers discoverable by specific criteria |
-| **Closed** | `allowStrangerMessages: false`, no guard list, friends-only | Private negotiations, internal team communication |
-| **Defensive** | `allowStrangerMessages: true`, substantial blacklist | Users receiving harassment from specific addresses; open but monitoring |
-
-**How to help the user choose**: Ask:
-1. "Do you want strangers to be able to contact you at all?" → determines `allowStrangerMessages`
-2. "If yes, should anyone be able to, or only those who meet certain criteria?" → determines Guard list need
-3. "Are there specific addresses you want to block entirely?" → determines Blacklist use
-
-### Strategy: Guard List Design
-
-The Guard list is where anti-spam becomes programmable. A Guard validates that a stranger **meets a verifiable condition** before allowing their message through (token/reputation/order/passport/payment gates — the design catalog with table shapes and query instructions lives in the MCP knowledge layer: `schema_query` action='get_guard_design_patterns'; do not re-derive Guard logic here).
-
-**`passportValiditySeconds` trade-off**: Short (e.g. 60s) = higher security, re-verification per message. Long (e.g. 7 days) = better UX, one passport covers a week. Match to data volatility: payment-based guards tolerate longer durations; order-state guards should stay short (order state changes). Bounds (10s–10y) and the max-10 list size are enforced by the schema.
-
-**Multiple guards**: listed guards are alternatives, not conjunctions — a passport from ANY one passes delivery. Use them to open different audience doors (e.g. one for existing customers, one for token holders).
-
-### Strategy: Troubleshooting Anti-Spam Issues
-
-| Symptom | Diagnosis | Solution |
-|---------|-----------|----------|
-| "My message was rejected" | Recipient has `allowStrangerMessages: false` and you're not their friend | Check rejection response for `guard_list` → obtain passport → resend with `guardAddress`+`passportAddress` |
-| "I'm getting too much spam" | `allowStrangerMessages: true` with no filtering | Switch to Guarded profile: set `allowStrangerMessages: false`, add at least one Guard to guard list |
-| "A legitimate customer can't reach me" | Guard requirements too strict, or their passport expired | Lower Guard requirements, extend `passportValiditySeconds`, or add them to friends list manually |
-| "Stranger keeps spamming after cool-down" | Working as designed — one retry per cool-down | Add to blacklist |
-| "I disabled strangers but my friend can't message" | They may not actually be in your friends list | Use `friendslist` → `exist` to verify; add manually if needed |
-
-### Strategy: Filtering Messages by Source
-
-`watch_messages` segments the inbox by relationship via `listFilterMode` (`friends` / `guard` / `stranger` / `any`, default any; `customListFilter` adds include/exclude lists — exact semantics in the schema).
-
-**Operational rhythm**: a service provider triaging inbox first scans `friends` (known customers, low risk), then `stranger` (new inquiries need attention); guard-verified traffic is checked last.
-
----
-
-## Evidence (WTS)
-
-### Concept
-
-A WTS file is a **tamper-proof, self-verifying export** of a continuous conversation. Every message is cryptographically chained; any gap or modification breaks the chain. Participant signatures add non-repudiation.
-
-### The Workflow
-
-When a dispute requires evidence: (1) `generate_wts` → export messages by time/messageId/seqIndex range — each WTS file is written **together with a human-readable HTML companion** (`htmlFiles`; no separate conversion needed); (2) `sign_wts` → add your Falcon512 signature (both parties can sign); (3) `verify_wts` → validate hash chain, continuity, and all signatures; (4) `wts2html` → only if you need a custom theme/title or a standalone re-render (it always writes files); (5) `send_file` → submit the signed WTS to the arbitrator via messenger (stamp the active goal's `goal_id`).
-
-> **Key design decision**: Include the **full conversation** when generating WTS for arbitration — not just favorable messages. The arbitrator needs to see who said what, who acknowledged what, and the exact sequence. Selective exports undermine your credibility.
-
-### On-Chain Proof (Optional)
-
-`proof_message` anchors a message to the blockchain, creating an immutable timestamp proving the message existed before that point. Anyone can independently verify against this on-chain record.
-
-### When to Generate WTS
-
-- **Disputes only** — normal conversations are preserved server-side. WTS is evidence preparation, not archiving.
-- **When the other party disputes a fact** — the WTS proves what was actually said and acknowledged.
-- **When arbitration requires evidence submission** — signed WTS is the standard evidence format.
-
-> Before filing a dispute, pre-screen your evidence collection via `evaluation_operation` action `evidence_review` (list mode): it partitions items into usable/manual/rejected and yields `proof_candidates` to reference in the dispute description (the human picks — nothing attaches automatically). Arbitrator-side flow: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
+> Advisory profiles (NOT system states, just setting combinations): **Open** = strangers on, no guards, public-facing; **Guarded** = strangers off + 1–3 guards, verified-only; **Closed** = strangers off, no guards, friends-only; **Blocklist mode** = strangers on + a maintained blacklist. Choose by asking: may strangers reach you at all → if yes, anyone or guard-verified → anyone to hard-block. Always leave at least one inbound path.
 
 ---
 
-## Messenger Across Roles
+## Evidence: WTS
 
-**Customer**: Pre-order inquiry (`send_message` to provider) → submit required info (`send_required_info` over the `customer_required` fields) → track progress (`watch_messages`) → raise dispute (`generate_wts` + `sign_wts` + `send_file` to arbitrator). Full workflow: [wowok-order](../wowok-order/SKILL.md).
+WTS = tamper-proof, self-verifying export of a continuous conversation: messages are hash-chained (any gap/edit breaks verification), signatures give non-repudiation.
 
-**Service Provider**: Monitor inquiries (`watch_conversations` with `unreadOnly` or `listFilterMode: "stranger"`) → respond to customers (reply auto-adds to friends) → request customer info → document agreements (creates evidence trail) → dispute defense (`generate_wts` + `sign_wts` + `send_file`). Full workflow: [wowok-provider](../wowok-provider/SKILL.md).
+Workflow: `generate_wts {myAccount, peerAccount, range?}` (range by time/messageId/seqIndex; writes the `.wts` **and** a human-readable HTML companion — `htmlFiles`) → `sign_wts` (Falcon512; both parties may sign) → `verify_wts {wtsFilePath}` (`hashValid`, `signatureValid`, per-signer detail) → `wts2html` only for a custom theme/re-render (always writes files) → `send_file` to the arbitrator (stamp `goal_id`). To verify an incoming WTS, `save_attachment` it first, then `verify_wts` on the path.
 
-**Arbitrator**: Receive evidence (`watch_messages`/`watch_conversations`) → verify evidence (`verify_wts`) → communicate with parties (`send_message` for clarifications) → sign attestation (`sign_wts` on verified evidence). Full workflow: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
+- Export the **full conversation**, not favorable excerpts — selective exports destroy credibility.
+- `proof_message {messageId, network}` anchors a message on-chain and returns `proofAddress` — a Proof object Guards can consume (`proof.signer`/`proof.time`), proving existence-before-time.
+- WTS is dispute preparation, not routine archiving. Before filing, pre-sort with `evaluation_operation` action=`evidence_review` (usable/manual/rejected + `proof_candidates`; the human selects; nothing auto-attaches).
 
----
+## Cross-role quick map
 
-## Common Pitfalls
+- **Customer**: inquire → `send_required_info` → track inbox → on dispute, full-range WTS, sign, send to arbitrator (see [wowok-order](../wowok-order/SKILL.md)).
+- **Provider/merchant**: triage `stranger` inbox, reply (auto-friends), document agreements, defend with WTS (see [wowok-provider](../wowok-provider/SKILL.md)).
+- **Arbitrator**: receive, `save_attachment` + `verify_wts` every piece, clarify via `send_message`, treat unverified material as non-evidence (see [wowok-arbitrator](../wowok-arbitrator/SKILL.md)).
 
-- **One-message limit trap**: Sending a vague first message to a stranger wastes your only chance. Make the first message complete and actionable.
-- **Disabled messenger**: Without messenger enabled, your account has no endpoint — counterparties cannot find or message you.
-- **WTS range too narrow**: Selecting only favorable messages undermines evidence credibility. Include the full conversation.
-- **Guard list without strategy**: Adding a Guard to your list without testing it (`gen_passport`) means you don't know what conditions strangers must meet — you may be blocking legitimate contacts.
-- **`allowStrangerMessages: false` with no guard list and no friends**: Nobody can contact you. Always ensure at least one inbound path exists.
-- **Stale passports**: `passportValiditySeconds` too short causes frequent re-verification failures. Match duration to your Guard's data volatility.
+## Pitfalls
 
----
+- Vague first message to a stranger wastes the only shot; a `friendslist exist` check answers "why can't my friend reach me".
+- Strangers off + no guards + empty friends = nobody inbound.
+- Guards are immutable from creation — untested guard-list entries block legitimate contacts; expired passports show as guard rejection, not friend failure.
+- Never treat on-chain Contact `ims[]` and the local friends list as the same system.

package/wowok-onboard/SKILL.md

@@ -2,167 +2,93 @@
 name: wowok-onboard
 description: "WoWok First-Touch Onboarding — guides a NEW user from a vague first prompt to their first published Service: a Review opening, then AT MOST 8 mandatory business questions (never technical field prompts), then a dependency-aware auto-build (reuse / customize / discover). Every decision (industry, network, location, token, pricing, workflow, fund distribution, arbitration) is framed as who-wins-what and why. Produces Permission + Service + Machine + Progress + Guards + Allocation + Contact + Arbitration, verified by a test order. Not for existing merchants tuning operations — use wowok-provider. Use when: User is new to WoWok and wants to set up a service; User says \"open a shop\", \"create a service\", \"start selling\", \"onboard\"; User has no published Service yet; User asks \"what's next\" after account creation; User resumes an interrupted onboarding."
 metadata:
-  version: "2.0.0"
+  version: "2.1.0"
   role: shared
   related: "wowok-provider, wowok-machine"
 ---
 
 # WoWok First-Touch Onboarding
 
-Guides a new merchant from zero to first published Service in a **Review opening + AT MOST 8 mandatory business questions** (not 12 technical rounds). The AI speaks in **business / commercial terms** — it explains what each choice means for the merchant and the buyer (interests, causality, risk), and NEVER asks the user to fill a technical field. The MCP layer owns the technical defaults; this Skill owns the **business dialogue rhythm** and the **dependency-aware build order**.
+Take a new merchant from zero to first published Service via a **Review opening + AT MOST 8 mandatory business questions**. Speak business/commercial language — what each choice means for merchant and buyer (interests, causality, risk) — NEVER "set field X". The MCP owns technical defaults; this skill owns the **dialogue rhythm** and **dependency-aware build order**.
 
-> **Related Skills**: [wowok-provider](../wowok-provider/SKILL.md) (post-onboard operations), [wowok-machine](../wowok-machine/SKILL.md) (workflow design), [wowok-messenger](../wowok-messenger/SKILL.md) (customer-service Contact), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (third-party Arbitration)
+> Related: [wowok-provider](../wowok-provider/SKILL.md) (post-onboard ops) · [wowok-machine](../wowok-machine/SKILL.md) · [wowok-messenger](../wowok-messenger/SKILL.md) · [wowok-arbitrator](../wowok-arbitrator/SKILL.md)
 
 ---
 
-## MCP Knowledge Layer
+## What the MCP already handles (don't duplicate)
 
-The following content is pushed down to the MCP layer and applied automatically — this Skill does NOT duplicate it:
-
-| Content | Access via (MCP action) | Applied via |
-|---------|--------------------------|-------------|
-| Industry modes + expert description guidance | `industry_pack_operation` action='list_modes' / 'recommend_industry' (each mode now returns `location_sensitivity`, `trust_selling_points`, `build_notes`) | Q1 (industry) + Q5 (description optimization) |
-| Cross-network build detection + mainnet migration checklist | `query_toolkit` query_type='migration_preflight' | Q2 (testnet vs mainnet) |
-| Testnet faucet / mainnet bridge / airdrop / payment-token guidance | `wowok_buildin_info` info='funding guidance' / 'mainnet bridge tokens' | Q2 + Q4 |
-| Third-party arbitrator discovery | `onchain_events` type='ArbitrationEvent' (dedupe by `object`) | Q8 (arbitration) |
-| Safety rules (immutability, confirmation, object reuse) | `schema_query` action='get_safety_rules' | pre-publish + `goal_operation` action='aggregate_risks' |
-| Guard / Machine / Arbitration / Treasury design rules | `schema_query` action='get_guard_design_patterns' | build + `aggregate_risks` |
-| Common mistakes (field/unit/workflow pitfalls) | `wowok_buildin_info` info='common mistakes' | tool calls (proactive warnings) |
-| Deployment checklist (publish readiness) | `goal_operation` action='aggregate_risks' (findings carry CRITICAL/WARN severity) + wowok-auditor pre-publish gates | before service/machine publish |
-| Multi-round memory (decisions / feedback / problems) | `goal_operation` (Goal) + TaskProcess streams | every confirmation / user objection |
-
-This Skill keeps the **business dialogue flow**, the **≤8-question gate**, and the **dependency-aware build order**. The user's intent is recorded as a Goal (`goal_operation` action='create'); actual on-chain objects are created via `onchain_operations` in dependency order.
+| Content | Access |
+|---|---|
+| Industry modes, recommendation, expert description guidance | `industry_pack_operation` `list_modes` / `recommend_industry` (items carry `location_sensitivity`, `trust_selling_points`, `build_notes`; full modes also carry `machine_shape`, `key_risk`, allocator/guards) |
+| Cross-network build detection + migration checklist | `query_toolkit` query_type=`migration_preflight` (`account` required; direction defaults testnet→mainnet) |
+| Faucet / bridge / airdrop / payment-token guidance | `wowok_buildin_info` info=`funding guidance` / `mainnet bridge tokens` (quote the served token list + `wowTypeTag`, never hardcode) |
+| Third-party arbiters | `onchain_events` type=`ArbitrationEvent` (dedupe by `object`; shortlist by location/fee) |
+| Field/unit/workflow pitfalls | `wowok_buildin_info` info=`common mistakes` |
+| Safety + Guard/Machine/Arbitration design rules | `schema_query` `get_safety_rules` / `get_guard_design_patterns` |
+| Publish readiness (CRITICAL/WARN findings) | `goal_operation` action=`aggregate_risks` |
+| Multi-round memory (decisions/feedback) | `goal_operation` (Goal + TaskProcess streams) |
 
 ---
 
-## Core Interaction Principles (non-negotiable)
+## Non-negotiable interaction rules
 
-1. **Business-first language (最重要的原则)**: Explain every choice as "what it means for you and for your customer" — role interests, incentives, cause-and-effect, risk. NEVER phrase a question as "set field X / pass parameter Y". Translate technical defaults into business consequences and surface them as recommendations the user can accept or override.
-2. **Review-first**: Before the first question, output a review stating (a) understanding of the business, (b) the dependency-chain overview (abridged, business-framed), (c) the interaction contract, (d) the free-testnet / no-money-at-risk reassurance.
-3. **User-driven + ≤8 mandatory questions**: There are AT MOST 8 business questions. Everything else is an AUTO technical step with a `recommend` default — the AI discloses the default and lets the user confirm or object, but never forces a new question beyond the 8.
-4. **Reuse / Customize / Discover**: For every technical component (Permission, Machine, Guard, Contact, Treasury, Arbitration, Reward, Repository), surface three avenues — reuse an existing object, customize a new one, or discover from the system.
-5. **Confirm + remember**: Every business decision (workflow, fund distribution, description, arbitration) is CONFIRMED by the user before acting. User objections/questions are recorded in the process memory (`decisions` / `feedback` streams) — the onboarding is multi-round, not linear.
-6. **Default-config disclosure**: Before creating anything, disclose the default configuration and its business meaning; no silent defaults.
+1. **Business-first**: every question is "what this means for you and your customer", never a technical field prompt. Translate defaults into consequences; offer them as recommendations.
+2. **Review-first**: before Q1 output (a) restated understanding of the business, (b) abridged build journey with intervention points, (c) the contract — ≤8 questions, recommendations wait for confirmation, pause/object/revisit always allowed, reuse/customize/discover on every component, (d) testnet reassurance — free faucet, zero money at risk; mainnet needs gas only.
+3. **≤8 mandatory questions**; everything else is an auto step with a disclosed `recommend` default — confirm or object, never a 9th question.
+4. **Reuse / customize / discover** for Permission, Progress, Machine, Guards, Contact, Allocation, Arbitration, Reward, Repository.
+5. **Confirm and remember** every business decision (Goal process streams); onboarding is multi-round.
+6. **No silent defaults**: disclose configuration + business meaning before creating.
 
 ---
 
-## Dependency Chain (Authoritative ODG)
-
-The technical build order (hidden from the user as a field list; surfaced as business consequences):
+## Dependency chain (build order)
 
 ```
-Account + network (testnet free first)
- └─ Permission (who is allowed to operate — reuse strongly recommended)
-     ├─ Service DRAFT (brand identity — editable until publish)
-     ├─ Machine nodes/forwards (business workflow) + Guards (what must be proven at each step)
-     │    └─ PUBLISH Machine (immutable)
-     └─ Service Phase 1: bind machine + buy_guard + sales + order_allocators
-          ├─ Sales (products + WIP URL/hash) · order_allocators (who gets paid, on what condition)
-          ├─ Contact (customer-service inbox) · Arbitration (independent dispute judge)
-          └─ audit → PUBLISH Service (L1-locked) → TEST ORDER
+Account + network (testnet first)
+└─ Permission            (operators; reuse strongly recommended)
+   ├─ Service DRAFT      (brand identity; editable until publish)
+   ├─ Progress ledger    (per-node accomplishment schema the Machine binds)
+   ├─ Machine nodes/forwards + node Guards → PUBLISH Machine (immutable)
+   └─ Service bind: machine + buy_guard + sales + order_allocators
+        ├─ Sales (products + WIP URL/hash) · Allocators (who gets paid, when)
+        ├─ Contact (support inbox) · Arbitration (independent judge)
+        └─ aggregate_risks → PUBLISH Service → TEST ORDER
 ```
 
-**Irreversibility (translated to the user as "decide now, can't change later"):**
-- `machine`, `order_allocators`, `arbitrations` are **L1-locked after publish** — set them before publishing.
-- `compensation_fund > 0` requires a bound Arbitration; the Arbitration must be independent of the Service's own control (otherwise the merchant is both player and referee).
-- Machine nodes/forwards and Guard logic are immutable after the Machine is published.
+**Irreversibility to translate as "decide now"**:
+- After Service publish, `machine` and `order_allocators` are **L1 permanent locks**.
+- `arbitrations` / rewards are **L2 time-locks**: you may still ADD after publish; remove/clear requires pause + the lock duration to elapse.
+- Machine nodes/forwards and each Guard are immutable once the Machine is published.
+- `compensation_fund > 0` requires a bound Arbitration — independent of the Service's controllers (same Permission aborts 33).
 
 ---
 
-## Review Opening Protocol (before Q1)
-
-When a new user expresses a vague intent, output this review FIRST (in business language), then ask the first question:
-
-1. **Understanding** — restate what the user sells, to whom, and the rough business model.
-2. **Journey overview** — show (abridged, non-technical) what will be built and where the user can intervene.
-3. **Interaction contract** — state: at most 8 business questions; AI gives a `recommend` and waits; the user may pause/object/revisit at any time; every component offers reuse/customize/discover.
-4. **Reassurance (first-use anxiety)** — testnet is completely free (faucet, no money at risk); mainnet needs gas only; you can practice before going live.
-
-> ⚠️ No user-choice interaction happens before this review is complete.
-
----
-
-## The 8 Mandatory Business Questions
-
-Ask these in order; stop at 8. Frame each in business terms. Every question maps to MCP lookups that return business-grade defaults (never raw technical tables to the user).
-
-### Q1 — What do you sell, and to whom? (industry alignment)
-
-- **Business meaning**: Your business type determines the trust mechanism (how a buyer feels safe paying you), the workflow (how an order progresses), and the money split. It is the single most consequential choice.
-- **MCP**: `industry_pack_operation` action='recommend_industry' with `intent`=<business description text> (→ top-3 modes), or action='list_modes'. Each mode returns `location_sensitivity`, `trust_selling_points`, and `build_notes` — surface these as "here is what buyers in your industry worry about, and what a trustworthy shop emphasizes".
-- **Output to user**: the recommended industry + "buyers in this industry mainly worry about: …", in plain language.
-
-### Q2 — Practice on testnet first, or go straight to mainnet?
-
-- **Business meaning**: Testnet is a free sandbox (faucet, zero money at risk) for you to try everything; mainnet is real money and needs gas. Strongly recommend testnet first.
-- **Existing-build detection (migration)**: call `query_toolkit` query_type='migration_preflight' with `account` (required); `source_network` / `target_network` are optional and default to testnet → mainnet (the resolved direction is echoed back in the result). If the account already built on testnet, switch to the **mainnet customization guide** — re-confirm payment token / location / arbitration (the checklist is returned by the same query), rather than re-asking everything.
-- **Reassurance**: testnet is free; mainnet gas can be obtained via bridge/airdrop (`wowok_buildin_info` info='funding guidance').
-
-### Q3 — Where do you serve? (service area / location)
+## The 8 questions (ask in order, business-framed)
 
-- **Business meaning**: For non-shipping services (in-person, local, digital-at-a-location) the service area is the purchase gate — a buyer must be able to tell "can this merchant serve me?". For shipping services it is the delivery region. This is important; do not skip.
-- **MCP**: the chosen mode's `location_sensitivity` — `strict`/`near` = must set a correct service area (non-mailing); `logistics` = delivery region (mailing).
+**Q1 — What do you sell, to whom?** Determines trust mechanism, workflow, split. `recommend_industry {intent}` → top-3 modes; surface each mode's `trust_selling_points`/`build_notes` as "what buyers in this industry worry about". Builtin modes (8): `freelance` `rental` `education` `travel` `subscription` `retail` `retail_d2c` `general`; mid-onboarding tweaks use `derive_user_mode` / `evolve_user_mode`.
 
-### Q4 — Which currency do you accept? (payment token)
+**Q2 — Testnet practice or mainnet now?** Recommend testnet. Run `migration_preflight` — if the account already built on testnet, switch to the migration checklist (re-confirm token/location/arbitration/WIP/gas), don't re-ask.
 
-- **Business meaning**: On testnet everything settles in WOW (free). On mainnet you may accept stablecoins (USDT/USDC) to reduce price-volatility disputes, or ETH/WBTC; WOW itself is the gas token. This is the "should I change the payment token when going live" decision.
-- **MCP**: `wowok_buildin_info` info='funding guidance' (testnet=WOW) + info='mainnet bridge tokens' (the authoritative bridge-token set with each `wowTypeTag` is served by MCP — quote that list, do not hardcode it here).
+**Q3 — Where do you serve?** Purchase gate for local/in-person, delivery region for shipping. Use the mode's `location_sensitivity`: `strict` = location must match demand area; `near` = digital/global, location is a service region; `logistics` = delivery region.
 
-### Q5 — What are your products, prices, and descriptions? (sales + WIP)
+**Q4 — Which currency?** Testnet settles WOW (free); mainnet may use USDT/USDC/ETH/WBTC to cut volatility — quote the served bridge-token list, not a hardcoded one.
 
-- **Business meaning**: What the buyer pays for, how much, and what the deliverable actually is. The description is your storefront copy — the AI should propose **industry-expert optimizations** (from `trust_selling_points` + `build_notes` + `key_risk`) and get the user's confirmation.
-- **WIP**: if a product needs an immutable deliverable description (a "what you will get" file), it MUST be deployed to a public URL — on-chain stores only URL + hash. Recommend deploying it; on testnet it can be skipped (`wip: ""`), on mainnet strongly recommend.
-- **Confirm**: show the optimized description + prices and ask the user to confirm or adjust.
+**Q5 — Products, prices, descriptions?** Propose expert-optimized storefront copy from `trust_selling_points` + `build_notes` + `key_risk`; confirm prices. WIP: an immutable deliverable spec lives at a public URL — on-chain stores URL + hash only; skippable on testnet, strongly recommended on mainnet.
 
-### Q6 — How does an order progress to completion? (workflow)
+**Q6 — How does an order progress?** Present the mode's `machine_shape` as a plain-language paid→delivered→confirmed flow (who proves what — e.g. buyer confirms receipt). Explicit confirmation/objection recorded. Nodes stay business states — no refund/dispute terminals (R-M1-11).
 
-- **Business meaning**: From paid → delivered → confirmed, who is responsible at each step and what must be proven (e.g. "buyer confirms receipt, not the seller"). This is the core of a trustworthy shop.
-- **MCP**: the mode's `machine_shape` (business states) — present as a plain-language flow, disclose the default, let the user accept or propose changes.
-- **Confirm + remember**: the AI MUST present a plain-language flow description and get explicit confirmation (or the user's objection/question), recorded in memory. Multi-round is expected.
+**Q7 — How and when is money released?** Present the mode allocator default in business terms (e.g. merchant 97% + processor 3%; full refund on cancellation), including the cancellation path. Explicit confirmation; this is L1-locked at publish.
 
-### Q7 — How and when does money get released? (fund distribution)
-
-- **Business meaning**: Who receives the money and on what condition (e.g. funds released only after delivery confirmation). This is the revenue model and is frozen once live — decide carefully.
-- **MCP**: the mode's allocator default (e.g. merchant 97% + processor 3%; full refund on cancellation). Present the split in business terms, disclose the default, let the user confirm or change.
-- **Confirm + remember**: explicit confirmation required (including "who gets paid when an order is cancelled/refunded"), recorded in memory.
-
-### Q8 — Who judges a dispute? (arbitration)
-
-- **Business meaning**: When you and a customer disagree, an INDEPENDENT third party must judge — it cannot be the seller, or buyers won't trust you. On testnet you may skip it; on mainnet it is strongly recommended.
-- **MCP**: discover independent arbiters via `onchain_events` type='ArbitrationEvent' (dedupe by `object`, shortlist by location/fee/description). Never create your own Arbitration for your own Service (conflict of interest).
-- **Confirm**: recommend a third-party arbiter (or skip on testnet), get confirmation.
-
----
-
-## After the 8 Questions — Auto-Build (reuse / customize / discover)
-
-With the 8 business decisions captured, build the objects in dependency order. These are NOT new forced questions — the AI discloses each default and lets the user confirm or object:
-
-- **Permission** — reuse an existing one (strongly recommended; single control surface), else create.
-- **Service draft** — created from Q1/Q3/Q5 answers; brand name confirmed once.
-- **Machine + Guards** — built from the Q6 workflow; nodes/forwards/guards disclosed, R-M1-11 compliant (business states only, no `refunded`/`disputed` terminals).
-- **Sales** — from Q5 (products + WIP URL/hash).
-- **order_allocators** — from Q7 (fund split), L1-locked.
-- **Contact** — reuse/create the customer-service inbox (mutable; anti-spam policy disclosed).
-- **Arbitration** — from Q8 (independent third party; compensation fund if configured).
-- **Optional**: Reward (loyalty/discounts), supply-chain promises, Repository — offered as opt-in, never forced.
-
-Run `goal_operation` action='aggregate_risks' before publish; fix ALL CRITICAL findings, then publish and run a user-driven test order (per-node disclosure: AI recommends the next step, the user decides).
+**Q8 — Who judges disputes?** An INDEPENDENT third party — never the seller's own controllers. Discover via `ArbitrationEvent`; bind by reference. Skippable on testnet; strongly recommended mainnet.
 
 ---
 
-## Industry Selection Guide
+## Auto-build & finish
 
-Call `industry_pack_operation` action='list_modes' (8 builtin modes: `freelance` / `rental` / `education` / `travel` / `subscription` / `retail` / `retail_d2c` / `general`). If unsure, call action='recommend_industry' with `intent` set to the business description text. Each mode now returns `location_sensitivity`, `trust_selling_points`, and `build_notes` — use these for Q3 (location) and Q5 (description optimization). Mid-onboarding iteration: action='derive_user_mode' / 'evolve_user_mode'.
-
----
+With the 8 decisions captured, create in dependency order (each default disclosed, not a new question): Permission (reuse) → Service draft → Progress ledger → Machine + Guards (R-M1-11) → publish Machine → sales/WIP → order_allocators → Contact (support IMs; anti-spam disclosed) → Arbitration binding (+ compensation fund if chosen). Reward / supply-chain promises / Repository are opt-in offers.
 
-## Deployment Checklist
-
-Before declaring onboarding complete, run `goal_operation` action='aggregate_risks' — MCP auto-checks machine binding, order_allocators, buy_guard, arbitration isolation, R-M1-11 compliance, and the rest of publish readiness, returning findings with CRITICAL/WARN severity. Fix ALL CRITICAL findings, then verify remaining hard gates via `query_toolkit` (onchain_objects). The authoritative checklist is served by MCP — do not re-derive it here.
-
----
+Then: `aggregate_risks` → fix ALL CRITICAL findings → publish Service → run a **user-driven test order** (AI recommends the next per-node step, user decides). Remaining hard gates via `query_toolkit` query_type=`onchain_objects`; the authoritative checklist is MCP-served — don't re-derive it.
 
-## Common Errors
+## Errors
 
-Known field-name / unit / workflow pitfalls are served by `wowok_buildin_info` info='common mistakes' (filter by `operation` or `category`). Error-code guidance (`E_ARBITRATION_PERMISSION_CONFLICT` 33, `E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND` 25, R-M1-11 refund routing) appears above plus MCP `schema_query` action='get_safety_rules' / 'get_guard_design_patterns'. Consult those instead of a duplicated table.
+Pitfalls and error-code guidance (`E_ARBITRATION_PERMISSION_CONFLICT` 33, `E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND` 25, R-M1-11 refund routing) come from `common mistakes` / `get_safety_rules` / `get_guard_design_patterns` — consult them rather than keeping a duplicated table.