@wowok/skills 3.0.4 → 3.1.1

package/wowok-arbitrator/SKILL.md

@@ -1,17 +1,10 @@
 ---
 name: wowok-arbitrator
-description: |
-  WoWok Arbitrator — build and operate on-chain arbitration services.
-  Create Arbitration objects, configure voting rules (open or guard-based weighted),
-  manage dispute cases through their full lifecycle, and earn fees from resolution.
-
-  Core value: achieve trust consensus between merchants and users through
-  transparent, fair, and efficient dispute resolution.
-when_to_use:
-  - User wants to create/configure an Arbitration service
-  - User needs to handle dispute cases and voting processes
-  - User wants to design voter eligibility and weight mechanisms
-  - User mentions "arbitration", "dispute", "voting", "arb", "judge"
+description: "WoWok Arbitrator — build and operate on-chain arbitration services. Create Arbitration objects, configure voting rules (open or guard-based weighted), manage dispute cases through their full lifecycle, and earn fees from resolution. Core value: achieve trust consensus between merchants and users through transparent, fair, and efficient dispute resolution. Use when: User wants to create/configure an Arbitration service; User needs to handle dispute cases and voting processes; User wants to design voter eligibility and weight mechanisms; User mentions \"arbitration\", \"dispute\", \"voting\", \"arb\", \"judge\"."
+metadata:
+  version: "2.0.0"
+  role: arbitrator
+  related: "wowok-order, wowok-messenger"
 ---
 
 # WoWok Arbitrator Guide

package/wowok-auditor/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-auditor
-description: |
-  WoWok pre-publish auditor — the static-analysis Skill that verifies
-  Guard completeness, Machine soundness, fund-flow safety, permission
-  consistency, and publish readiness BEFORE any irreversible publish
-  operation (Service publish, Machine publish, Allocator binding freeze).
-
-  This Skill is the knowledge base for the L4 Harness Verify Loop. It does
-  not mutate objects. It queries, exports, and rules — emitting a
-  pass/warn/fail audit report plus a publish decision.
-when_to_use:
-  - User is about to publish a Service, Machine, or lock an Allocator set
-  - User asks to "audit", "verify", "review", "check before publish"
-  - L4 Harness Verify Loop is invoked before an irreversible operation
-  - User mentions "fund flow", "refund path", "allocation sum", "guard completeness"
-  - User mentions "machine cycle", "unreachable state", "permission index conflict"
-  - User wants a pre-publish go/no-go decision
-  - A publish operation failed and root-cause analysis is needed
+description: "WoWok pre-publish auditor — the static-analysis Skill that verifies Guard completeness, Machine soundness, fund-flow safety, permission consistency, and publish readiness BEFORE any irreversible publish operation (Service publish, Machine publish, Allocator binding freeze). This Skill is the knowledge base for the L4 Harness Verify Loop. It does not mutate objects. It queries, exports, and rules — emitting a pass/warn/fail audit report plus a publish decision. Use when: User is about to publish a Service, Machine, or lock an Allocator set; User asks to \"audit\", \"verify\", \"review\", \"check before publish\"; L4 Harness Verify Loop is invoked before an irreversible operation; User mentions \"fund flow\", \"refund path\", \"allocation sum\", \"guard completeness\"; User mentions \"machine cycle\", \"unreachable state\", \"permission index conflict\"; User wants a pre-publish go/no-go decision; A publish operation failed and root-cause analysis is needed."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-planner, wowok-provider, wowok-machine"
 ---
 
 # WoWok Pre-Publish Auditor

package/wowok-collaborator/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-collaborator
-description: |
-  WoWok Collaborator — the canonical skill for process collaborators who execute
-  workflow forwards on behalf of a merchant: internal staff (permission entities)
-  and external operators (named operators).
-
-  Covers permission-index and named-operator routing, guard-gated evidence
-  submission, and reputation protection. The collaborator carries PROCESS
-  responsibility (no direct settlement stake) — the goal is to keep the workflow
-  flowing and avoid stall blame.
-
-  For the merchant who owns the Service, see wowok-provider. For the supplier who
-  presents to Demands, see wowok-supplier.
-when_to_use:
-  - User is an operator/employee executing workflow steps (permission index)
-  - User is an external named operator advancing a Machine forward
-  - User wants to submit guard evidence (proof/repository) for a forward
-  - User mentions "collaborator", "operator", "permission index", "named operator", "execute forward"
+description: "WoWok Collaborator — the canonical skill for process collaborators who execute workflow forwards on behalf of a merchant: internal staff (permission entities) and external operators (named operators). Covers permission-index and named-operator routing, guard-gated evidence submission, and reputation protection. The collaborator carries PROCESS responsibility (no direct settlement stake) — the goal is to keep the workflow flowing and avoid stall blame. For the merchant who owns the Service, see wowok-provider. For the supplier who presents to Demands, see wowok-supplier. Use when: User is an operator/employee executing workflow steps (permission index); User is an external named operator advancing a Machine forward; User wants to submit guard evidence (proof/repository) for a forward; User mentions \"collaborator\", \"operator\", \"permission index\", \"named operator\", \"execute forward\"."
+metadata:
+  version: "2.0.0"
+  role: collaborator
+  related: "wowok-provider, wowok-machine, wowok-messenger"
 ---
 
 # WoWok Collaborator Guide

package/wowok-governance/SKILL.md

@@ -1,30 +1,10 @@
 ---
 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
+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. Use when: 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\"."
+metadata:
+  version: "1.0.0"
+  role: shared
+  related: "wowok-provider, wowok-market, wowok-messenger"
 ---
 
 # WoWok Governance Guide
@@ -41,7 +21,7 @@ The following content has been pushed down to the MCP knowledge layer and is app
 | 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 |
+| Treasury/Permission/Personal object schema | `schema_query` action='get' name='treasury'/'permission'/'personal' | 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 |
 
@@ -59,9 +39,9 @@ Inventory → Decide → Execute → Audit. Governance objects are LIVE: a permi
 
 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).
+- **Indexes**: role indexes are numeric IDs (custom indexes start at 1000 — built-ins are reserved). Naming one for readability is a `remark {op:'set', index, remark}` write, not a "create index" call.
+- **Grants** (`table` field): assign with `add perm by index` (one index → many entities) or `add perm by entity` (one entity → many indexes); `set` variants REPLACE the existing list. `admin {op:'add'|'remove'|'set'}` controls admins; entity-level hygiene uses `del`/`swap`/`replace`/`copy`. A mis-assigned grant takes effect immediately. Exact op shapes: `schema_query` action='get' name='permission'.
+- **Entity table**: review-first — read the current Permission via `query_toolkit` query_type='onchain_objects' before mutating.
 - **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:
@@ -109,7 +89,7 @@ Governance goals close the loop through three channels:
 
 ## Quick Reference
 
-- Permission: indexes → role assignment → entity table; audit via permission_perm + address_profile.
+- Permission: index remarks → grants (`add perm by index`/`by entity`) → 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-machine/SKILL.md

@@ -1,23 +1,10 @@
 ---
 name: wowok-machine
-description: |
-  WoWok Machine Workflow Design — the canonical skill for designing, building,
-  and operating automated workflow templates (Machines) on WoWok. Machines are
-  directed graphs that define how orders progress through stages, who can
-  advance them, and what conditions must be met at each step.
-
-  Covers Machine architecture (Nodes, Pairs, Forwards, Guards, Thresholds),
-  lifecycle management (create, configure, publish, pause), node operations
-  (add, exchange, rename, granular forward/prior-node manipulation),
-  Progress integration, cross-Machine supply chain composition via Guard verification, privacy-preserving
-  consensus patterns, and export/import workflows via machineNode2file.
-when_to_use:
-  - User wants to create or modify a Machine workflow
-  - User asks about workflow steps, state transitions, or progress
-  - User needs to design order processing pipelines
-  - User mentions "machine", "workflow", "progress", "state machine", "pipeline"
-  - User wants to export Machine nodes to a file or import from a file
-  - User needs to understand threshold mechanics, forward permissions, or guard bindings
+description: "WoWok Machine Workflow Design — design, build and operate workflow templates (Machines): directed graphs that define how orders progress through stages, who can advance them, and what conditions must be met at each step. Covers Nodes/Pairs/Forwards/Guards/Thresholds, lifecycle (create, configure, publish, pause), node and forward operations, Progress integration, cross-Machine supply chains via Guard verification, and machineNode2file import/export. Use when: User wants to create or modify a Machine workflow; User asks about workflow steps, state transitions, or progress; User needs to design order processing pipelines; User mentions \"machine\", \"workflow\", \"progress\", \"state machine\", \"pipeline\"; User wants to export/import Machine nodes via a file; User needs threshold mechanics, forward permissions, or guard bindings."
+metadata:
+  version: "2.0.0"
+  role: provider
+  related: "wowok-provider"
 ---
 
 # WoWok Machine Workflow Design

package/wowok-market/SKILL.md

@@ -1,26 +1,10 @@
 ---
 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"
+description: "WoWok Market — market discovery and operations (the matchmaking layer): 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, arbitration_score (trust selection), account_events (attention), market_metrics, anti_cheat, market_operations (journey funnel / referral / CRM) and category match rules. Use when: User wants to discover services for an intent (\"find a plumber in Shanghai\"); Merchant wants to find open Demands to present to; Merchant wants to pick or compare arbitrators; User wants their on-chain attention items surfaced; User wants market metrics, anti-cheat signals, journey funnel, referral or CRM; User mentions \"market\", \"match\", \"discover\", \"matchmaking\", \"funnel\", \"referral\"."
+metadata:
+  version: "1.0.0"
+  role: shared
+  related: "wowok-provider, wowok-order, wowok-arbitrator"
 ---
 
 # WoWok Market Guide

package/wowok-messenger/SKILL.md

@@ -1,23 +1,10 @@
 ---
 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.
-when_to_use:
-  - 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"
-always: false
+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"
+  role: shared
+  related: "wowok-order, wowok-provider, wowok-arbitrator"
 ---
 
 # WoWok Messenger Guide
@@ -25,9 +12,9 @@ always: false
 End-to-end encrypted messaging with tamper-proof audit trails.
 
 > **Role**: Any WoWok participant
-> All 17 operations with full parameter types and constraints are in the MCP schema (`messenger_operation`). This document focuses on **design decisions and strategy** not captured by the schema.
+> 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 now live in the MCP knowledge layer — query via `schema_query` actions `get_guard_design_patterns` / `get_safety_rules`.
+> 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`).
 
 ---
 
@@ -64,15 +51,15 @@ Before any communication:
 
 ### Account Limit
 
-A single device supports up to 1000 messenger accounts. Exceeding this returns "Maximum 1000 messenger accounts allowed". Use `account_operation → messenger { enabled: false }` to disable unused accounts.
+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 an existing Contact if you serve multiple Services with the same support channel.
+**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.
 
-**Lifecycle**: Contact is mutable (unlike Proof/Guard). IM mutations (`onchain_operations` contact with `ims: {op:'add'|'set'|'remove'|'clear', im:[...]}`) require permission index 453 (CONTACT_IM). No events emitted on IM mutations — poll `ims[]` field. If Contact is bound to `Permission.um`, clear that binding (permission op: `um: null`) BEFORE deleting the Contact (else dangling pointer). Full field constraints: MCP `schema_query` action='get' name='contact'.
+**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'.
 
 ---
 
@@ -86,19 +73,31 @@ Two approaches, depending on need:
 
 - **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`.
+- **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 boundary for attachments**: Attachment messages (those with `zipMetadata`) never expose their base64 payload in `watch_messages` / `watch_conversations` / `pull_messages` / `search_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).
 
 **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 Messages
 
-Plain text via `send_message`; files (WTS, WIP, ZIP) via `send_file`.
+Plain text via `send_message`; files and media (images, audio, video, voice, documents, WTS/WIP evidence) via `send_file`.
 
 **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`.
 
-**ZIP file attachments**: Use `send_file` for file delivery. Recipients extract via `extract_zip_messages`. The file is encrypted end-to-end; `zipMetadata` tracks download status locally.
+**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
 
@@ -151,21 +150,11 @@ The optimal configuration depends on your role and openness needs:
 
 ### 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.
+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).
 
-**Common Guard designs for messenger**:
+**`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.
 
-| Guard Type | What It Verifies | Example Use |
-|------------|-----------------|-------------|
-| Token-gated | Sender holds a specific token/NFT | Premium customer community |
-| Reputation | Sender's `personal` profile has ≥N likes | Verified reputation threshold |
-| Order-based | Sender has an active order on your Service | Only current customers can message |
-| Passport-based | Sender holds a valid passport from a trusted issuer | Whitelist of partner organizations |
-| Payment | Sender has made a minimum payment | Paid consultation access |
-
-**`passportValiditySeconds` trade-off**: Short (60s) = higher security, re-verification per message. Long (7 days) = better UX, one passport covers a week. Match to your Guard's use case: payment-based guards can use longer durations; order-status guards should use shorter durations (order state changes).
-
-**Multiple guards**: Different guards can serve different purposes. A provider might use: (1) order-based guard for existing customers, (2) token-gated guard for premium access — both listed, either suffices for message delivery.
+**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
 
@@ -179,16 +168,9 @@ The Guard list is where anti-spam becomes programmable. A Guard validates that a
 
 ### Strategy: Filtering Messages by Source
 
-`watch_messages` supports `listFilterMode` to segment your inbox by relationship type:
-
-- `friends` — only messages from your friends list
-- `guard` — only messages from guard-verified senders
-- `stranger` — only messages from unknown senders (highest priority for review)
-- `any` — all messages (default)
-
-Combine with `customListFilter` for fine-grained include/exclude logic.
+`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).
 
-**Practical use**: A service provider checking their inbox can first scan `listFilterMode: "friends"` for known-customer messages (low risk), then `listFilterMode: "stranger"` for new-customer inquiries (need attention).
+**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.
 
 ---
 
@@ -200,7 +182,7 @@ A WTS file is a **tamper-proof, self-verifying export** of a continuous conversa
 
 ### The Workflow
 
-When a dispute requires evidence: (1) `generate_wts` → export messages by time/messageId/seqIndex range; (2) `sign_wts` → add your Falcon512 signature (both parties can sign); (3) `verify_wts` → validate hash chain, continuity, and all signatures; (4) `wts2html` → (optional) convert to human-readable HTML; (5) `send_file` → submit signed WTS to the arbitrator via messenger.
+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.
 
@@ -220,7 +202,7 @@ When a dispute requires evidence: (1) `generate_wts` → export messages by time
 
 ## Messenger Across Roles
 
-**Customer**: Pre-order inquiry (`send_message` to provider) → submit required info (`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).
+**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).
 
 **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).
 

package/wowok-onboard/SKILL.md

@@ -1,27 +1,10 @@
 ---
 name: wowok-onboard
-description: |
-  WoWok First-Touch Onboarding — guides a NEW user (vague first prompt) to their
-  first published Service through a business-first dialogue: a Review opening
-  followed by AT MOST 8 mandatory business questions (never technical field
-  prompts), then a dependency-aware auto-build with reuse/customize/discover for
-  the technical components. Every business decision (industry, network, location,
-  payment token, pricing, workflow, fund distribution, arbitration) is framed in
-  terms of who-wins-what and why — not which field to fill.
-
-  Use when a new user says "I want to open a shop", "I want to sell something",
-  "how do I start", or has no published Service yet. Produces a complete merchant
-  capability stack: Permission + Service (published) + Machine (published) +
-  Progress (bound) + Guards + Allocation + Contact + Arbitration, verified by a
-  user-driven test order.
-
-  Not for existing merchants tuning operations — hand off to wowok-provider.
-when_to_use:
-  - 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 on the current account
-  - User completed account creation and asks "what's next"
-  - User resumes an interrupted onboarding (read checkpoint state)
+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"
+  role: shared
+  related: "wowok-provider, wowok-machine"
 ---
 
 # WoWok First-Touch Onboarding

package/wowok-order/SKILL.md

@@ -1,23 +1,10 @@
 ---
 name: wowok-order
-description: |
-  WoWok Buyer Guide — TWO lifecycles in one skill:
-
-  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 (in-order fulfillment, post-order): order creation, progress advancement,
-     fund management, and arbitration.
-
-  For suppliers presenting to Demands, see wowok-supplier. For process
-  operators executing workflow forwards, see wowok-collaborator.
-when_to_use:
-  - User is a potential buyer evaluating a service BEFORE purchasing (prospect)
-  - User is a customer/buyer placing or managing orders (customer)
-  - User wants to evaluate services, WIP, guards, allocations, arbitration
-  - User needs to communicate with sellers via Messenger
-  - User asks about order progress, payments, or refunds
-  - User wants to file disputes or arbitration claims
-  - User mentions "buy", "order", "purchase", "refund", "dispute", "arbitration", "due diligence"
+description: "WoWok Buyer Guide — TWO lifecycles in one skill: 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 (in-order fulfillment, post-order): order creation, progress advancement, fund management, and arbitration. For suppliers presenting to Demands, see wowok-supplier. For process operators executing workflow forwards, see wowok-collaborator. Use when: User is a potential buyer evaluating a service BEFORE purchasing (prospect); User is a customer/buyer placing or managing orders (customer); User wants to evaluate services, WIP, guards, allocations, arbitration; User needs to communicate with sellers via Messenger; User asks about order progress, payments, or refunds; User wants to file disputes or arbitration claims; User mentions \"buy\", \"order\", \"purchase\", \"refund\", \"dispute\", \"arbitration\", \"due diligence\"."
+metadata:
+  version: "2.0.0"
+  role: customer
+  related: "wowok-provider, wowok-arbitrator, wowok-messenger"
 ---
 
 # WoWok Buyer Guide
@@ -189,7 +176,7 @@ Foundation = immutable on-chain rules (Phase 1). Messenger = encrypted, self-ver
 
 ### 2.1 Send Privacy Info
 
-Contact `ims[]` from E8. Send E10 info via `messenger_operation` → `send_message`. **Messenger only — never on-chain.** Explicit user confirmation per item. After sending, persist any newly-provided value via `local_info_operation` `add` (so future orders auto-fill).
+Contact `ims[]` from E8. Send E10 info via `messenger_operation` → `send_required_info` (LocalInfo field names assembled in one E2E message), or `send_message` for free-form text. **Messenger only — never on-chain.** Explicit user confirmation per item. After sending, persist any newly-provided value via `local_info_operation` `add` (so future orders auto-fill).
 
 ### 2.2 Negotiate
 

package/wowok-output/SKILL.md

@@ -1,15 +1,10 @@
 ---
 name: wowok-output
-description: |
-  WoWok output processing and display — post-processes all WoWok tool responses
-  for human-readable presentation. Handles address resolution, name mapping,
-  amount formatting, and data visualization.
-when_to_use:
-  - AI has received response from any WoWok MCP tool
-  - Response contains addresses requiring name resolution
-  - Response contains amounts requiring human-readable formatting
-  - User queries on-chain data (events, objects, tables)
-always: true
+description: "WoWok output processing and display — post-processes all WoWok tool responses for human-readable presentation. Handles address resolution, name mapping, amount formatting, and data visualization. Use when: AI has received response from any WoWok MCP tool; Response contains addresses requiring name resolution; Response contains amounts requiring human-readable formatting; User queries on-chain data (events, objects, tables)."
+metadata:
+  version: "2.0.0"
+  role: shared
+  loading: always
 ---
 
 # Address Display Rules

package/wowok-planner/SKILL.md

@@ -1,24 +1,10 @@
 ---
 name: wowok-planner
-description: |
-  WoWok Planning Skill — the main planning component of the L4 Harness Plan Loop.
-  Converts user natural-language intent into an executable Object Dependency Graph
-  (ODG) and a phased execution plan. Deterministic-first: rule tables and scenario
-  templates drive planning; the LLM only clarifies intent and translates responses.
-
-  Use when a user says "I want to build...", "plan a service", "help me set up X",
-  or when the L4 Harness opens a new planning cycle. Produces an ODG JSON document
-  consumed by the Harness execution loop, with checkpoints between phases.
-
-  Not for direct execution — hand off to wowok-onboard or wowok-provider for
-  step-by-step MCP orchestration once the ODG is confirmed.
-when_to_use:
-  - User describes a new service intent and needs a build plan
-  - L4 Harness opens a Plan Loop cycle (fresh task)
-  - User asks "what do I need to create to support X"
-  - User wants to reuse existing objects for a new service
-  - User asks for a dependency graph or execution phases
-  - User resumes an interrupted planning session (read ODG checkpoint)
+description: "WoWok Planning Skill — the planning component of the L4 Harness Plan Loop. Converts natural-language intent into an executable Object Dependency Graph (ODG) plus a phased plan. Deterministic-first: rule tables and scenario templates drive planning; the LLM only clarifies intent. Produces an ODG consumed by the Harness execution loop, with checkpoints between phases. Not for direct execution — hand off to wowok-onboard or wowok-provider once the ODG is confirmed. Use when: User describes a new service intent and needs a build plan; the Harness opens a Plan Loop cycle; User asks \"what do I need to create to support X\"; User wants to reuse existing objects for a new service; User asks for a dependency graph or execution phases; User resumes an interrupted planning session."
+metadata:
+  version: "2.0.0"
+  role: shared
+  related: "wowok-onboard, wowok-auditor, wowok-provider"
 ---
 
 # WoWok Planning Skill
@@ -106,4 +92,4 @@ Each object has: `id`, `type`, `status` (planned/created/published), `reversible
 5. **Contact (customer service)** is configured before Service publish — `Service.um → Contact → ims[]`, with the local account enabled as messenger and anti-spam set.
 6. **Arbitration is third-party and before publish** — `arbitration.permission != service.permission` (`E_ARBITRATION_PERMISSION_CONFLICT`); `compensation_fund > 0` requires non-empty `arbitrations` (`E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND`).
 
-These rules are the single source of truth for the dependency chain; the phase list above is their concrete serialization. Hand-off to `wowok-onboard` (Review opening + 12 rounds) follows this same chain.
+These rules are the single source of truth for the dependency chain; the phase list above is their concrete serialization. Hand-off to `wowok-onboard` (Review opening + at most 8 business questions) follows this same chain.

package/wowok-provider/SKILL.md

@@ -1,22 +1,10 @@
 ---
 name: wowok-provider
-description: |
-  WoWok Service Provider — the canonical skill for service providers (merchants, sellers)
-  to build, operate, and manage commercial services on WoWok.
-
-  Covers service design (WIP products, Machine workflows, Allocator strategies),
-  trust mechanisms (compensation funds, arbitration), customer attraction
-  (discounts, rewards, supply chain promises), and order fulfillment.
-
-  For customers placing orders, see wowok-order. For arbitrators, see wowok-arbitrator.
-when_to_use:
-  - User is a service provider/merchant/seller on WoWok
-  - User wants to create a commercial service/marketplace
-  - User wants to design workflow (Machine) for order processing
-  - User wants to set up fund distribution strategies (Allocators)
-  - User wants to configure trust mechanisms (compensation, arbitration)
-  - User wants to handle order fulfillment and customer service
-  - User mentions "create service", "merchant", "seller", "provider", "workflow design", "compensation", "arbitration"
+description: "WoWok Service Provider — the canonical skill for service providers (merchants, sellers) to build, operate, and manage commercial services on WoWok. Covers service design (WIP products, Machine workflows, Allocator strategies), trust mechanisms (compensation funds, arbitration), customer attraction (discounts, rewards, supply chain promises), and order fulfillment. For customers placing orders, see wowok-order. For arbitrators, see wowok-arbitrator. Use when: User is a service provider/merchant/seller on WoWok; User wants to create a commercial service/marketplace; User wants to design workflow (Machine) for order processing; User wants to set up fund distribution strategies (Allocators); User wants to configure trust mechanisms (compensation, arbitration); User wants to handle order fulfillment and customer service; User mentions \"create service\", \"merchant\", \"seller\", \"provider\", \"workflow design\", \"compensation\", \"arbitration\"."
+metadata:
+  version: "2.0.0"
+  role: provider
+  related: "wowok-machine, wowok-messenger"
 ---
 
 # WoWok Service Provider Guide
@@ -120,7 +108,7 @@ Once R1-R7 confirmed, execute in strict order. Sub-tools are invoked via `wowok(
 
 **STEP 5 — Revenue (order_allocators + Treasury)**: `onchain_operations` service order_allocators (L1-locked). Mode: amount / rate (bps sum=10000) / surplus. Recipient: `{Entity}` / `{GuardIdentifier}` / `{Signer}`. Personal → Permission owner (Entity); Org → Treasury (`Treasury.receive` index 253). Offer new/select Treasury (query onchain_objects type=treasury).
 
-**STEP 6 — Customer Service (Contact + Messenger)**: `onchain_operations` contact (ims) + `account_operation` messenger (`enabled: true`). Contact mutable; `im_add`/`im_remove` need permission index 453 (CONTACT_IM). Anti-spam profiles: Open / Guarded / Closed / Defensive. Bind `onchain_operations` service `um` (if customer_required).
+**STEP 6 — Customer Service (Contact + Messenger)**: `onchain_operations` contact (`ims` with op `add`/`set`/`remove`/`clear`) + `account_operation` messenger (`enabled: true`). Contact mutable; IM mutations need permission index 453 (CONTACT_IM) and emit no events. Anti-spam profiles: Open / Guarded / Closed / Defensive. Bind `onchain_operations` service `um` (if customer_required).
 
 **STEP 7 — Trust (Arbitration + compensation_fund)**: REUSE third-party Arbitration (MUST NOT share Service's Permission — E_ARBITRATION_PERMISSION_CONFLICT 33; don't create your own). `compensation_fund_add` (internal Balance<T>, not Treasury); fund>0 requires non-empty arbitrations (E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND 25); withdraw needs bPaused + lock elapsed.
 

package/wowok-supplier/SKILL.md

@@ -1,21 +1,10 @@
 ---
 name: wowok-supplier
-description: |
-  WoWok Supplier — the canonical skill for suppliers (sub-order providers) who
-  present their service to a Demand and fulfill the resulting sub-order.
-
-  Covers demand discovery, service presentation (open or passport-gated),
-  sub-order fulfillment via Progress, and settlement collection. The supplier
-  is a PEER role with a two-sided position: deliver (to get paid) + collect
-  (from the upstream merchant).
-
-  For the merchant who owns the main Service, see wowok-provider. For the
-  process operators executing the workflow, see wowok-collaborator.
-when_to_use:
-  - User wants to present their service to a Demand (open RFP or gated call)
-  - User is a sub-order provider / supplier fulfilling part of a transaction
-  - User wants to collect settlement from an upstream merchant
-  - User mentions "supplier", "sub-order", "demand", "present service", "RFP", "fulfill sub-order"
+description: "WoWok Supplier — the canonical skill for suppliers (sub-order providers) who present their service to a Demand and fulfill the resulting sub-order. Covers demand discovery, service presentation (open or passport-gated), sub-order fulfillment via Progress, and settlement collection. The supplier is a PEER role with a two-sided position: deliver (to get paid) + collect (from the upstream merchant). For the merchant who owns the main Service, see wowok-provider. For the process operators executing the workflow, see wowok-collaborator. Use when: User wants to present their service to a Demand (open RFP or gated call); User is a sub-order provider / supplier fulfilling part of a transaction; User wants to collect settlement from an upstream merchant; User mentions \"supplier\", \"sub-order\", \"demand\", \"present service\", \"RFP\", \"fulfill sub-order\"."
+metadata:
+  version: "2.0.0"
+  role: supplier
+  related: "wowok-provider, wowok-machine, wowok-messenger"
 ---
 
 # WoWok Supplier Guide