@wowok/skills 3.1.0 → 3.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/package.json +3 -2
  2. package/wowok-arbitrator/SKILL.md +10 -10
  3. package/wowok-auditor/SKILL.md +59 -72
  4. package/wowok-collaborator/SKILL.md +1 -1
  5. package/wowok-governance/SKILL.md +6 -6
  6. package/wowok-machine/SKILL.md +1 -1
  7. package/wowok-market/SKILL.md +2 -2
  8. package/wowok-messenger/SKILL.md +27 -32
  9. package/wowok-onboard/SKILL.md +11 -11
  10. package/wowok-order/SKILL.md +1 -1
  11. package/wowok-planner/SKILL.md +5 -5
  12. package/wowok-provider/SKILL.md +12 -12
  13. package/wowok-supplier/SKILL.md +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wowok/skills",
3
- "version": "3.1.0",
3
+ "version": "3.1.2",
4
4
  "description": "WoWok AI Skills for Claude Code, Codex, Cursor, Windsurf, Trae, CodeBuddy, Qoder, Roo Code, Cline, Kilo Code and GitHub Copilot - dialogue orchestration layer on top of the WoWok MCP server (rules/reference knowledge is served by MCP directly since v2.0.0)",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -33,7 +33,8 @@
33
33
  "postinstall": "node scripts/install.js",
34
34
  "audit:skills": "node scripts/validate-skills.mjs",
35
35
  "audit:length": "node scripts/check-skills-length.mjs",
36
- "check": "npm run build && npm run audit:skills && npm run audit:length"
36
+ "audit:drift": "node scripts/check-skill-mcp-drift.mjs",
37
+ "check": "npm run build && npm run audit:skills && npm run audit:length && npm run audit:drift"
37
38
  },
38
39
  "keywords": [
39
40
  "wowok",
package/wowok-arbitrator/SKILL.md CHANGED
@@ -59,18 +59,18 @@ User says "just make something up" → REFUSE and explain why each item matters.
59
59
 
60
60
  | # | Item | User Must Provide | Why Not Fabricate |
61
61
  |---|------|-------------------|--------------------|
62
- | **R1** | **Account** | Which account to operate from. Default `""` is fine. | Safe default exists |
63
- | **R2** | **Arbitration Name** | Service name. What kind of arbitration? | Your brand and reputation on-chain |
64
- | **R3** | **Fee** | How much per case? (e.g. "10 WOW per dispute") | IS your revenue model — you cannot guess pricing |
65
- | **R4** | **Voting Guard(s)** | Who votes and with what weight? Open voting (centralized) or Guard-based (decentralized)? | ⛔ Guards are **immutable after creation** — wrong design = create replacement Guard |
66
- | **R5** | **Usage Guard** | Who can file disputes? Public or restricted? | Controls your case volume and quality |
67
- | **R6** | **Contact (um)** | Messenger Contact name/ID for evidence exchange | Without this, customers cannot submit evidence — service is broken |
62
+ | **1** | **Account** | Which account to operate from. Default `""` is fine. | Safe default exists |
63
+ | **2** | **Arbitration Name** | Service name. What kind of arbitration? | Your brand and reputation on-chain |
64
+ | **3** | **Fee** | How much per case? (e.g. "10 WOW per dispute") | IS your revenue model — you cannot guess pricing |
65
+ | **4** | **Voting Guard(s)** | Who votes and with what weight? Open voting (centralized) or Guard-based (decentralized)? | ⛔ Guards are **immutable after creation** — wrong design = create replacement Guard |
66
+ | **5** | **Usage Guard** | Who can file disputes? Public or restricted? | Controls your case volume and quality |
67
+ | **6** | **Contact (um)** | Messenger Contact name/ID for evidence exchange | Without this, customers cannot submit evidence — service is broken |
68
68
 
69
69
  ### Information Collection Protocol
70
70
 
71
- Present checklist R1-R6 to user. Each item: "Reuse or create new? Provide details." Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]. ⛔ GATE: ALL R1-R6 must be [confirmed] before any on-chain action — NOT confirmed → STOP. Ask. Do NOT suggest creating arbitration.
71
+ Present checklist Steps 1-6 to user. Each item: "Reuse or create new? Provide details." Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]. ⛔ GATE: ALL Steps 1-6 must be [confirmed] before any on-chain action — NOT confirmed → STOP. Ask. Do NOT suggest creating arbitration.
72
72
 
73
- All subsequent on-chain operations use R1 (Account) as `env.account`.
73
+ All subsequent on-chain operations use Step 1 (Account) as `env.account`.
74
74
 
75
75
  ### Anti-Fabrication Rules (HARD Constraints)
76
76
 
@@ -176,7 +176,7 @@ Customer pays fee → locked in `Arb.fee` per case → `arb_withdraw()` transfer
176
176
 
177
177
  Arbitrator sets `indemnity` → Customer claims via `order.arb_claim_compensation` → Funds transfer from `service.compensation_fund` to Order.
178
178
 
179
- > **Note**: The compensation payout comes from the **provider's** compensation_fund, not the arbitrator's funds. Customers should assess the provider's fund balance before purchase — this is covered in [wowok-order](../wowok-order/SKILL.md) Phase 1.1.
179
+ > **Note**: The compensation payout comes from the **provider's** compensation_fund, not the arbitrator's funds. Customers should assess the provider's fund balance before purchase — this is covered in [wowok-order](../wowok-order/SKILL.md) E7 (Compensation Fund).
180
180
 
181
181
  ---
182
182
 
@@ -233,6 +233,6 @@ Providers list approved Arbitrations in their Service. Customers choose from thi
233
233
 
234
234
  ### Common Pitfalls
235
235
 
236
- Served by `wowok_buildin_info` action='common mistakes' + MCP `schema_query` action='get_safety_rules'. Key ones: paused Arbitration rejects disputes silently (verify `pause: false`); wrong Guard design is immutable (test with `gen_passport` first); non-finished withdrawal has a 30-day lock; always `verify_wts` before ruling.
236
+ Served by `wowok_buildin_info` info='common mistakes' + MCP `schema_query` action='get_safety_rules'. Key ones: paused Arbitration rejects disputes silently (verify `pause: false`); wrong Guard design is immutable (test with `gen_passport` first); non-finished withdrawal has a 30-day lock; always `verify_wts` before ruling.
237
237
 
238
238
  ---
package/wowok-auditor/SKILL.md CHANGED
@@ -1,105 +1,92 @@
1
1
  ---
2
2
  name: wowok-auditor
3
- 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."
3
+ 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 orchestration guide for the L4 Harness Verify Loop. It does not mutate objects. It triggers the MCP risk engine, gathers evidence, and presents a pass/warn/fail 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."
4
4
  metadata:
5
- version: "2.0.0"
5
+ version: "2.1.0"
6
6
  role: shared
7
7
  related: "wowok-planner, wowok-provider, wowok-machine"
8
8
  ---
9
9
 
10
10
  # WoWok Pre-Publish Auditor
11
11
 
12
- Static-analysis rules that gate every irreversible publish. The auditor never
13
- writes on-chain; it queries (`query_toolkit`, `onchain_events`), exports
14
- (`guard2file`, `machineNode2file`), evaluates rule tables, and emits a
15
- pass / warn / fail report. A FAIL blocks the publish in R10.
12
+ Read-only orchestration for the gate that precedes every irreversible publish.
13
+ The auditor never writes on-chain; it triggers the MCP risk engine, gathers
14
+ evidence, and presents a go / no-go decision. (R10 in MCP dialogue rounds is
15
+ the canonical **verify** round — a FAIL blocks publish there.)
16
16
 
17
- > **Role**: Auditor (read-only). The pre-write safety gate now lives in the MCP knowledge layer (`schema_query` action='get_safety_rules'), applied on every write; this auditor runs only on publish.
18
- > **Layer**: L3 Skill, knowledge base for L4 Verify Loop.
17
+ > **Role**: Auditor (read-only). Pre-write safety rules live in the MCP knowledge layer (`schema_query` action='get_safety_rules') and are applied on every write; this auditor drives the comprehensive pre-publish aggregation.
18
+ > **Layer**: L3 Skill, orchestration guide for the L4 Verify Loop.
19
19
  > **Related Skills**: [wowok-machine](../wowok-machine/SKILL.md) (Machine design), [wowok-onboard](../wowok-onboard/SKILL.md) (publish flow).
20
20
 
21
21
  ---
22
22
 
23
- ## MCP Knowledge Layer
23
+ ## What Lives Where (single source of truth)
24
24
 
25
- The following content has been pushed down to the MCP knowledge layer and is applied automatically — this Skill no longer duplicates it:
25
+ The machine-executable rules are NOT duplicated in this Skill — they evolve in MCP and this file would drift:
26
26
 
27
- | Content | Access via (MCP action) | Applied Via |
28
- |---------|--------------------------|-------------|
29
- | Safety rules (confirmation levels, immutability rules, object reuse rules) | `schema_query` action='get_safety_rules' | Pre-publish checks + `goal_operation` action='aggregate_risks' |
30
- | Machine-executable audit rules | auto-applied (not queryable) | `goal_operation` action='aggregate_risks' |
31
- | Guard completeness / Machine soundness / fund-flow risks | auto-applied (not queryable) | `goal_operation` action='aggregate_risks' |
27
+ | Content | Source (MCP) |
28
+ |---------|--------------|
29
+ | Safety rules (confirmation levels, immutability, object reuse) | `schema_query` action='get_safety_rules' |
30
+ | Guard completeness, Machine soundness, fund-flow safety, permission consistency, publish readiness | `goal_operation` action='aggregate_risks' (auto-applied) |
32
31
 
33
- This Skill keeps the **audit flow**, the **4 audit dimensions** (Guard completeness, Machine soundness, fund flow, publish readiness), and the **checklist structure** as the human-readable knowledge base for the L4 Harness Verify Loop. The MCP layer runs the machine-executable rule evaluation.
32
+ This Skill keeps only **when to run the audit, how to call it, and how to read the verdict**.
34
33
 
35
34
  ---
36
35
 
37
- ## Core Principles
36
+ ## When to Run
38
37
 
39
- 1. **Read-only**: The auditor never calls `onchain_operations` with `submission`. It only queries and exports. Mutations belong to the Skill being audited.
40
- 2. **Rule-driven**: Every check is a row in a rule table (GUARD_COMPLETENESS_RULES, MACHINE_SOUNDNESS_RULES, FUND_FLOW_RULES, PUBLISH_READINESS_RULES). Adding a check = adding a row, not editing control flow.
41
- 3. **FAIL blocks, WARN asks**: A FAIL verdict blocks R10 publish until fixed. A WARN verdict proceeds after explicit user acknowledgement. PASS is silent.
42
- 4. **Blast-radius first**: Before reporting, classify each issue by irreversibility — a Guard logic bug post-publish is permanent; an untested Guard is recoverable.
43
- 5. **Semantic-aware**: Use the `semantic` field returned by recent operations (`semantic.created`, `semantic.modified`, `semantic.released`, `semantic.events`) to cross-check that the intended roles were actually created/modified/released.
44
- 6. **Tiered**: A Tier-1 audit (single Service + single Guard) skips Machine soundness if no Machine is bound. Tier-3 runs every rule including cross-Machine dependency chains.
38
+ Run an audit immediately before any irreversible operation:
39
+
40
+ 1. **Service publish** — machine bound + published, allocators locked, arbitration/compensation invariants, buy_guard, contact, permission indices.
41
+ 2. **Machine publish** — nodes/pairs/forwards become immutable afterward.
42
+ 3. **Allocator-set freeze** (`order_allocators` bind) — fund-flow paths lock with the Service.
43
+ 4. **Post-failure root-cause analysis** — a publish/assert failed (e.g. `E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND`, `E_ARBITRATION_PERMISSION_CONFLICT`); re-run to identify every remaining blocker, not just the one that aborted.
44
+
45
+ Scope adapts to blast radius: a single Service with no Machine skips machine checks automatically; a stack with cross-Machine supply chains runs the full chain. The engine derives applicable checks from the objects — do not hand-pick rules.
45
46
 
46
47
  ---
47
48
 
48
- ## Audit Rule Tables
49
+ ## How to Run
49
50
 
50
- ### GUARD_COMPLETENESS_RULES
51
+ ```
52
+ goal_operation action='aggregate_risks'
53
+ intent=<business intent text> # or pass 'puzzles' through from analyze_intent
54
+ planned_objects=[{object_type,is_new,name?}]
55
+ planned_operations=[{object_type,trigger:'create'|'publish',name?}]
56
+ severity_threshold='HIGH' # default HIGH
57
+ user_confirmed_high_risks=[...] # IDs acknowledged in a prior round
58
+ ```
51
59
 
52
- | Operation Type | Fund Flow? | Guard Required? | Audit Action |
53
- |---|---|---|---|
54
- | payment (negative amount) | Yes | Yes | FAIL if no Guard bound |
55
- | treasury deposit | Yes | Recommended | WARN if no Guard |
56
- | allocation execute | Yes | Yes | FAIL if no Guard |
57
- | service publish | No | No | PASS |
58
- | machine publish | No | No | PASS |
59
- | order create | Yes (escrow) | Yes | FAIL if no Guard on refund path |
60
- | progress forward (no fund) | No | Optional | PASS (skip) |
61
- | progress forward (fund release) | Yes | Yes | FAIL if no Guard on forward |
62
- | reward claim | Yes | Yes | FAIL if no Guard |
63
- | repository write | No | Recommended | WARN if no Guard |
60
+ Evidence-gathering (all read-only, done BEFORE presenting the verdict):
64
61
 
65
- ### MACHINE_SOUNDNESS_RULES
62
+ - `guard2file` / `machineNode2file` — export immutable backups of what is about to be published.
63
+ - `query_toolkit` (`onchain_objects`, table items) — verify current on-chain state (`bPublished`, balances, bound objects).
64
+ - `onchain_events` — confirm the state transitions claimed by recent operations.
65
+ - Use the `semantic` field of recent operation results (`semantic.created` / `.modified` / `.released` / `.events`) to cross-check that intended roles/objects were actually produced.
66
66
 
67
- | Check | Pass Condition | Fail Action |
68
- |---|---|---|
69
- | Acyclicity | No cycles in state graph | FAIL: cycle detected |
70
- | Single entry | Exactly one node with no inbound Pair | FAIL: multiple/zero entries |
71
- | Terminal reachability | All terminals reachable from entry | FAIL: unreachable terminal |
72
- | No dead-end non-terminals | Every non-terminal node has an outgoing Forward | FAIL: dead-end node |
73
- | No orphan non-entries | Every non-entry node has an incoming Pair | FAIL: orphaned node |
74
- | Forward permissions | Each forward has `permissionIndex` ≥ 1000 OR `namedOperator` set (or both) | WARN: missing permission; FAIL if neither |
75
- | Guard bindings | Each forward with fund flow has a Guard bound | FAIL: unguarded fund flow |
76
- | Threshold achievability | Each Pair's threshold is reachable by its Forwards' weights | WARN: dead branch (competing Pair always wins) |
77
-
78
- ### FUND_FLOW_RULES
79
-
80
- | Check | Pass Condition | Fail Action |
81
- |---|---|---|
82
- | Refund path exists | Every payment path has a corresponding refund path | FAIL: no refund path |
83
- | Allocation sum | Each Allocator's `sharing` array sums to 10000 (100%) | FAIL: allocation doesn't sum to 100% |
84
- | Treasury balance | Treasury has sufficient balance for pending allocations | WARN: low balance |
85
- | Gas coin separation | Gas coins (WOW) are not mixed with business tokens in allocations | WARN: gas coin in allocation |
86
- | Recipient type | Refund path uses `Entity`/`Signer` for known parties, `GuardIdentifier` for dynamic | WARN: ambiguous recipient |
87
- | Escrow symmetry | Order escrow amount equals sum of all Allocation paths from that order | FAIL: escrow mismatch |
67
+ Never call `onchain_operations` with `submission` from this role — fixes belong to the Skill being audited.
68
+
69
+ ---
88
70
 
89
- ### PUBLISH_READINESS_RULES
71
+ ## How to Read the Verdict
90
72
 
91
- | Check | Pass Condition | Fail Action |
73
+ `aggregate_risks` returns a blocking **status** plus per-finding severity (CRITICAL / HIGH / MEDIUM / LOW / INFO):
74
+
75
+ | Status | Meaning | Auditor action |
92
76
  |---|---|---|
93
- | Service unpublished | `bPublished === false` | PASS: ready to publish |
94
- | Machine published | Machine is published (if bound to Service) | FAIL: publish Machine first |
95
- | Guards tested | All Guards have a passing `gen_passport` test on record | WARN: untested Guard |
96
- | Permission configured | Permission object exists with correct indices for every Forward | FAIL: no Permission |
97
- | Allocators configured | `order_allocators` non-empty and each Allocator audited | FAIL: no Allocators |
98
- | User confirmation | User has explicitly confirmed publish intent | FAIL: no confirmation |
99
- | Compensation fund present | `compensation_fund` funded (recommended for trust) | WARN: empty fund |
100
- | Compensation fund invariant | If `compensation_fund > 0` then `arbitrations` MUST be non-empty (per service.move:494-496 `assert!(vector::length(&self.arbitrations) > 0, E_ARBITRATION_NOT_SET_WITH_COMPENSATION_FUND)`) | FAIL: funded but no Arbitration bound |
101
- | order_allocators immutability | `order_allocators` set BEFORE publish (service.move:503 `assert!(!self.bPublished)`) — cannot be modified post-publish | FAIL: attempt to modify after publish |
102
- | machine immutability | `machine` bound BEFORE publish (service.move:633 `assert!(!self.bPublished)`) — cannot be modified post-publish | FAIL: attempt to modify after publish |
103
- | Backup export | `machineNode2file` + `guard2file` backups persisted | WARN: no backup |
77
+ | `RISK_PASSED` | No risk at/above threshold | Go — present the go decision |
78
+ | `RISK_BLOCKED` | CRITICAL present, or unacknowledged risk ≥ threshold (default HIGH) | No-go — list every blocker with its object + fix; do not publish |
79
+ | `RISK_PENDING_CONFIRM` | Only acknowledged-able HIGH risks remain | Explain each HIGH risk in business terms; proceed only after explicit user confirmation, then re-run with the risk IDs in `user_confirmed_high_risks` |
80
+ | `RISK_CANCELLED` | The risk session was cancelled | Treat as no-go until re-audited |
81
+
82
+ Presentation rules:
83
+
84
+ 1. **FAIL blocks, WARN asks, PASS is silent.** CRITICAL/blocked findings are hard stops fixed by the owning Skill; MEDIUM/LOW are surfaced as advisories.
85
+ 2. **Blast-radius first**: order findings by irreversibility — a post-publish Guard logic bug is permanent; an untested Guard or missing backup is recoverable.
86
+ 3. Report grouped by the four coverage dimensions — **Guard completeness, Machine soundness, fund flow, publish readiness** — and state explicitly which objects were in scope. The individual checks inside each dimension are whatever MCP currently evaluates; quote the finding text returned, never a local rule list.
104
87
 
105
88
  ---
89
+
90
+ ## Audit Report Contract
91
+
92
+ The user-facing report contains: scope (objects/operations audited), findings grouped by dimension with severity, the blocking status, required fixes vs acknowledged risks, and a final one-line decision: **GO / NO-GO / CONFIRM-THEN-GO**. It contains no transaction itself — the audited Skill performs the mutation after GO.
package/wowok-collaborator/SKILL.md CHANGED
@@ -50,7 +50,7 @@ Two sub-kinds (derived on-chain, never asserted):
50
50
 
51
51
  ## What You Can Execute Now
52
52
 
53
- Run `query_toolkit` query_type='participation_radar' with your account + the order's Progress. It returns:
53
+ Run `query_toolkit` query_type='participation_radar' with `radar_account` (your account) and `radar_targets: [{ progress: <the order's Progress object>, order: <the Order, optional but recommended> }]` (1–20 targets). It returns:
54
54
 
55
55
  - `operable` — forwards YOU can execute right now (permission / named-operator path).
56
56
  - `waiting_on` — what the workflow waits on from other roles.
package/wowok-governance/SKILL.md CHANGED
@@ -21,7 +21,7 @@ The following content has been pushed down to the MCP knowledge layer and is app
21
21
  | Content | Access via (MCP action) | Applied Via |
22
22
  |---------|--------------------------|-------------|
23
23
  | Permission safety rules (owner/admin/entity hierarchy) | `schema_query` action='get_safety_rules' | `onchain_operations` permission |
24
- | Treasury/Permission/Personal object schema | `schema_query` action='get_schema' | governance operations |
24
+ | Treasury/Permission/Personal object schema | `schema_query` action='get' name='treasury'/'permission'/'personal' | governance operations |
25
25
  | Unclaimed-payment detection | `keeper_operation` (payment_unclaimed scan) | monitor loop |
26
26
  | Fund-flow event meanings (TreasuryEvent / AllocationEvent / RewardClaimEvent / RewardFundEvent) | event semantic registry | audit & monitor |
27
27
 
@@ -39,9 +39,9 @@ Inventory → Decide → Execute → Audit. Governance objects are LIVE: a permi
39
39
 
40
40
  A Permission object defines WHO can perform WHICH operations on your business objects (Service / Machine / Treasury …).
41
41
 
42
- - **Indexes** (`permission.index_create`): create named role indexes (e.g. operator=1, finance=2) before assigning.
43
- - **Role assignment** (`permission.role_assign`): bind indexes onto target objects — a mis-assigned role grants unintended operational authority immediately.
44
- - **Entity table**: add/remove addresses per index. Review-first: list current entities before mutating (`query_objects` on the Permission object).
42
+ - **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.
43
+ - **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'.
44
+ - **Entity table**: review-first — read the current Permission via `query_toolkit` query_type='onchain_objects' before mutating.
45
45
  - **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.
46
46
 
47
47
  Rules of thumb:
@@ -56,7 +56,7 @@ Rules of thumb:
56
56
  Fund stewardship across Treasury / Allocation / Reward / Payment.
57
57
 
58
58
  - **Treasury**: deposit joins coins in (a Payment receipt is minted); withdraw splits balance out — irreversible, and when an `external_guard` is set the guard must validate first. `query_toolkit` query_type='onchain_table_item_treasury_history' audits every flow (op 0 Withdraw / 1 Deposit / 2 Receive) with amount + guard + timestamp.
59
- - **Allocation**: runs distribute pool funds per sharing mode (Amount / Rate ‰ / Surplus). Review allocator guards periodically — a stale guard blocks legitimate distributions.
59
+ - **Allocation**: runs distribute pool funds per sharing mode (Amount / Rate in bps — base 10000 = 100% / Surplus). Review allocator guards periodically — a stale guard blocks legitimate distributions.
60
60
  - **Unclaimed payments**: recipients hold frozen CoinWrappers until they unwrap. The keeper `payment_unclaimed` scan owns this reminder surface — run `keeper_operation` to list claimable payments and nudge recipients via Messenger. NewPaymentEvent is deliberately NOT push-bridged, to avoid duplicate reminders (P2-4 channel split).
61
61
  - **Reward pools**: RewardFundEvent in / RewardClaimEvent out; a dry pool blocks claims — watch balances before announcing campaigns.
62
62
 
@@ -89,7 +89,7 @@ Governance goals close the loop through three channels:
89
89
 
90
90
  ## Quick Reference
91
91
 
92
- - Permission: indexes → role assignment → entity table; audit via permission_perm + address_profile.
92
+ - Permission: index remarks → grants (`add perm by index`/`by entity`) → audit via permission_perm + address_profile.
93
93
  - Treasury: deposit/withdraw + history audit; external_guard gates withdrawals.
94
94
  - Unclaimed payments: keeper scan owns reminders; recipients unwrap CoinWrappers.
95
95
  - Personal data: permanently public — review before every write.
package/wowok-machine/SKILL.md CHANGED
@@ -41,7 +41,7 @@ This Skill keeps the **workflow conversation guidance**, **business flow design
41
41
 
42
42
  ## Machine Architecture
43
43
 
44
- **Machine** → **Nodes** → **Pairs** (`prev_node` ["" = entry, multiple allowed], `threshold` [required total forward weight to advance]) → **Forwards** (`name`, `weight`, `permissionIndex` | `namedOperator` [who can execute], `guard` [optional condition]).
44
+ **Machine** → **Nodes** → **Pairs** (`prev_node` ["" = the single entry pair — pair keys are unique on chain (`E_DUPLICATE_NODE_PREV`); its `forwards` vector may carry multiple forwards to different first nodes], `threshold` [required total forward weight to advance]) → **Forwards** (`name`, `weight`, `permissionIndex` | `namedOperator` [who can execute], `guard` [optional condition]).
45
45
 
46
46
  > All field types, limits, and valid values are in the MCP schema (`onchain_operations_machine`). This document focuses on design decisions **not captured** by the schema.
47
47
 
package/wowok-market/SKILL.md CHANGED
@@ -56,7 +56,7 @@ This Skill keeps the **market conversation flow** — discover → compare → t
56
56
  ## Phase 2: Compare & Trust
57
57
 
58
58
  - **Compare**: the `match_discover` result already surfaces per-service scores + reasons. Surface the top-N side-by-side; highlight differences, never force a single pick.
59
- - **Arbitrator trust**: `evaluation_operation` action=`arbitration_score` with the Arbitration `object` (history auto-fetched via `query_arbs`). Returns `trust` + `fairness` + `combined`. Use it when a merchant chooses which Arbitration to bind, or a customer judges a Service's arbitration guarantee.
59
+ - **Arbitrator trust**: `evaluation_operation` action=`arbitration_score` with the Arbitration `object` — the Arb case history is auto-fetched on-chain when omitted (pass `context_network` for the right network). Returns `trust` + `fairness` + `combined`. Use it when a merchant chooses which Arbitration to bind, or a customer judges a Service's arbitration guarantee.
60
60
 
61
61
  ---
62
62
 
@@ -71,7 +71,7 @@ This Skill keeps the **market conversation flow** — discover → compare → t
71
71
 
72
72
  - **Metrics**: `evaluation_operation` action=`market_metrics` → active services / open demands / disputes / supply-demand ratio.
73
73
  - **Anti-cheat**: `evaluation_operation` action=`anti_cheat` with a Service's orders/reviews/object-stack → returns negative-factor signals (fake order / fake review / shell merchant).
74
- - **Operations**: `evaluation_operation` action=`market_operations` with `op` = `journey_funnel` / `referral_attribution` / `customer_relationship`.
74
+ - **Operations**: `evaluation_operation` action=`market_operations` with `op` = `journey_funnel` / `referral_attribution` / `customer_relationship` / `dynamic_pricing`.
75
75
 
76
76
  ---
77
77
 
package/wowok-messenger/SKILL.md CHANGED
@@ -12,9 +12,9 @@ metadata:
12
12
  End-to-end encrypted messaging with tamper-proof audit trails.
13
13
 
14
14
  > **Role**: Any WoWok participant
15
- > 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.
15
+ > 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.
16
16
  > **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)
17
- > 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`.
17
+ > 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`).
18
18
 
19
19
  ---
20
20
 
@@ -51,15 +51,15 @@ Before any communication:
51
51
 
52
52
  ### Account Limit
53
53
 
54
- 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.
54
+ 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.
55
55
 
56
56
  ### Contact Object (On-Chain Bridge)
57
57
 
58
58
  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.
59
59
 
60
- **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.
60
+ **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.
61
61
 
62
- **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'.
62
+ **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'.
63
63
 
64
64
  ---
65
65
 
@@ -73,19 +73,31 @@ Two approaches, depending on need:
73
73
 
74
74
  - **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.
75
75
  - **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.
76
- - **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`.
76
+ - **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.
77
+
78
+ **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.
77
79
 
78
80
  **Design note**: By default, retrieving messages auto-marks them as viewed (`viewedAt` timestamp). Set `skipAutoMarkViewed: true` if you want to peek without marking read.
79
81
 
80
82
  ### Send Messages
81
83
 
82
- Plain text via `send_message`; files (WTS, WIP, ZIP) via `send_file`.
84
+ Plain text via `send_message`; files and media (images, audio, video, voice, documents, WTS/WIP evidence) via `send_file`.
83
85
 
84
86
  **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.
85
87
 
86
88
  **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`.
87
89
 
88
- **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.
90
+ **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).
91
+
92
+ **Structured sends**:
93
+ - `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.
94
+ - Quote-reply: pass `options.replyTo: {messageId}` (same conversation; the id must exist in local storage) instead of hand-quoting text.
95
+ - 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.
96
+
97
+ ### Save Attachments
98
+
99
+ - `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.
100
+ - Desktop clients additionally have an in-memory read bridge for inline media rendering (no temp files); AI flows use `save_attachment`.
89
101
 
90
102
  ### Mark as Read
91
103
 
@@ -138,21 +150,11 @@ The optimal configuration depends on your role and openness needs:
138
150
 
139
151
  ### Strategy: Guard List Design
140
152
 
141
- The Guard list is where anti-spam becomes programmable. A Guard validates that a stranger **meets a verifiable condition** before allowing their message through.
153
+ 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).
142
154
 
143
- **Common Guard designs for messenger**:
155
+ **`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.
144
156
 
145
- | Guard Type | What It Verifies | Example Use |
146
- |------------|-----------------|-------------|
147
- | Token-gated | Sender holds a specific token/NFT | Premium customer community |
148
- | Reputation | Sender's `personal` profile has ≥N likes | Verified reputation threshold |
149
- | Order-based | Sender has an active order on your Service | Only current customers can message |
150
- | Passport-based | Sender holds a valid passport from a trusted issuer | Whitelist of partner organizations |
151
- | Payment | Sender has made a minimum payment | Paid consultation access |
152
-
153
- **`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).
154
-
155
- **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.
157
+ **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).
156
158
 
157
159
  ### Strategy: Troubleshooting Anti-Spam Issues
158
160
 
@@ -166,16 +168,9 @@ The Guard list is where anti-spam becomes programmable. A Guard validates that a
166
168
 
167
169
  ### Strategy: Filtering Messages by Source
168
170
 
169
- `watch_messages` supports `listFilterMode` to segment your inbox by relationship type:
170
-
171
- - `friends` — only messages from your friends list
172
- - `guard` — only messages from guard-verified senders
173
- - `stranger` — only messages from unknown senders (highest priority for review)
174
- - `any` — all messages (default)
175
-
176
- Combine with `customListFilter` for fine-grained include/exclude logic.
171
+ `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).
177
172
 
178
- **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).
173
+ **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.
179
174
 
180
175
  ---
181
176
 
@@ -187,7 +182,7 @@ A WTS file is a **tamper-proof, self-verifying export** of a continuous conversa
187
182
 
188
183
  ### The Workflow
189
184
 
190
- 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.
185
+ 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`).
191
186
 
192
187
  > **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.
193
188
 
@@ -207,7 +202,7 @@ When a dispute requires evidence: (1) `generate_wts` → export messages by time
207
202
 
208
203
  ## Messenger Across Roles
209
204
 
210
- **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).
205
+ **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).
211
206
 
212
207
  **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).
213
208
 
package/wowok-onboard/SKILL.md CHANGED
@@ -23,12 +23,12 @@ The following content is pushed down to the MCP layer and applied automatically
23
23
  |---------|--------------------------|-------------|
24
24
  | 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) |
25
25
  | Cross-network build detection + mainnet migration checklist | `query_toolkit` query_type='migration_preflight' | Q2 (testnet vs mainnet) |
26
- | Testnet faucet / mainnet bridge / airdrop / payment-token guidance | `wowok_buildin_info` action='funding guidance' / 'mainnet bridge tokens' | Q2 + Q4 |
26
+ | Testnet faucet / mainnet bridge / airdrop / payment-token guidance | `wowok_buildin_info` info='funding guidance' / 'mainnet bridge tokens' | Q2 + Q4 |
27
27
  | Third-party arbitrator discovery | `onchain_events` type='ArbitrationEvent' (dedupe by `object`) | Q8 (arbitration) |
28
28
  | Safety rules (immutability, confirmation, object reuse) | `schema_query` action='get_safety_rules' | pre-publish + `goal_operation` action='aggregate_risks' |
29
29
  | Guard / Machine / Arbitration / Treasury design rules | `schema_query` action='get_guard_design_patterns' | build + `aggregate_risks` |
30
- | Common mistakes (field/unit/workflow pitfalls) | `wowok_buildin_info` action='common mistakes' | tool calls (proactive warnings) |
31
- | Deployment checklist (publish readiness) | `goal_operation` action='aggregate_risks' | deployment-scanner D-01..D-20 |
30
+ | Common mistakes (field/unit/workflow pitfalls) | `wowok_buildin_info` info='common mistakes' | tool calls (proactive warnings) |
31
+ | Deployment checklist (publish readiness) | `goal_operation` action='aggregate_risks' (findings carry CRITICAL/WARN severity) + wowok-auditor pre-publish gates | before service/machine publish |
32
32
  | Multi-round memory (decisions / feedback / problems) | `goal_operation` (Goal) + TaskProcess streams | every confirmation / user objection |
33
33
 
34
34
  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.
@@ -89,14 +89,14 @@ Ask these in order; stop at 8. Frame each in business terms. Every question maps
89
89
  ### Q1 — What do you sell, and to whom? (industry alignment)
90
90
 
91
91
  - **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.
92
- - **MCP**: `industry_pack_operation` action='recommend_industry' (business description → 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".
92
+ - **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".
93
93
  - **Output to user**: the recommended industry + "buyers in this industry mainly worry about: …", in plain language.
94
94
 
95
95
  ### Q2 — Practice on testnet first, or go straight to mainnet?
96
96
 
97
97
  - **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.
98
- - **Existing-build detection (migration)**: call `query_toolkit` query_type='migration_preflight' (account + source=testnet + target=mainnet). 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.
99
- - **Reassurance**: testnet is free; mainnet gas can be obtained via bridge/airdrop (`wowok_buildin_info` action='funding guidance').
98
+ - **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.
99
+ - **Reassurance**: testnet is free; mainnet gas can be obtained via bridge/airdrop (`wowok_buildin_info` info='funding guidance').
100
100
 
101
101
  ### Q3 — Where do you serve? (service area / location)
102
102
 
@@ -105,8 +105,8 @@ Ask these in order; stop at 8. Frame each in business terms. Every question maps
105
105
 
106
106
  ### Q4 — Which currency do you accept? (payment token)
107
107
 
108
- - **Business meaning**: On testnet everything settles in WOW (free). On mainnet you may accept stablecoins (USDT/USDC) to reduce price-volatility disputes, or ETH/BTC/WOW. This is the "should I change the payment token when going live" decision.
109
- - **MCP**: `wowok_buildin_info` action='funding guidance' (testnet=WOW) + action='mainnet bridge tokens' (USDT/USDC/ETH/BTC/WOW type tags).
108
+ - **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.
109
+ - **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).
110
110
 
111
111
  ### Q5 — What are your products, prices, and descriptions? (sales + WIP)
112
112
 
@@ -153,16 +153,16 @@ Run `goal_operation` action='aggregate_risks' before publish; fix ALL CRITICAL f
153
153
 
154
154
  ## Industry Selection Guide
155
155
 
156
- 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 the business description. 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'.
156
+ 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'.
157
157
 
158
158
  ---
159
159
 
160
160
  ## Deployment Checklist
161
161
 
162
- 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 publish readiness (D-01..D-20). 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.
162
+ 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.
163
163
 
164
164
  ---
165
165
 
166
166
  ## Common Errors
167
167
 
168
- Known field-name / unit / workflow pitfalls are served by `wowok_buildin_info` action='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.
168
+ 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.
package/wowok-order/SKILL.md CHANGED
@@ -176,7 +176,7 @@ Foundation = immutable on-chain rules (Phase 1). Messenger = encrypted, self-ver
176
176
 
177
177
  ### 2.1 Send Privacy Info
178
178
 
179
- 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).
179
+ 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).
180
180
 
181
181
  ### 2.2 Negotiate
182
182
 
package/wowok-planner/SKILL.md CHANGED
@@ -25,8 +25,8 @@ The planner sits between the user's intent and the Harness execution loop. It do
25
25
 
26
26
  - **Deterministic-first**: Rule tables and scenario templates produce the ODG skeleton. The LLM is invoked only for (a) intent clarification when keywords are ambiguous, and (b) translating free-text answers into typed fields.
27
27
  - **Scenario-driven**: The Scenario Registry maps common intent patterns to pre-built ODG templates. A fallback `general` template absorbs unmatched intents.
28
- - **Plan-before-write**: The full ODG is confirmed at R8 before any publish-bound object is created. Reversibility is tracked per object.
29
- - **Checkpointed**: The ODG is persisted after every round via `local_info_operation` so the Harness can resume on interruption.
28
+ - **Plan-before-write**: The full ODG is confirmed through the phase review gates (`user_confirm` / `risk_check` / `final_audit`) before any publish-bound object is created. Reversibility is tracked per object. (Note: the R1–R10 rounds in MCP schemas are the Guard-authoring dialogue rounds — R1=intent, R2=table, R3=tree, R4=rely, R5=binding, R6=review, R7=CREATE, R8=test, R9=bind, R10=verify — not ODG plan phases; label local build checklists "Step n", never "Rn".)
29
+ - **Checkpointed**: Round state is anchored in a Goal (`goal_operation` create/approve/advance; the Harness TaskProcess stream persists every round), and the human-readable ODG JSON is written to the local workspace via `workspace_operation` so the Harness can resume on interruption. Do NOT use `local_info_operation` for this — that store is private customer-required info, not planning state.
30
30
 
31
31
  ### What This Skill Does
32
32
 
@@ -40,7 +40,7 @@ The planner sits between the user's intent and the Harness execution loop. It do
40
40
 
41
41
  - User says "I want to build / set up / start / plan X"
42
42
  - L4 Harness opens a new Plan Loop cycle
43
- - User resumes an interrupted plan (read ODG checkpoint first)
43
+ - User resumes an interrupted plan (read the Goal state and the workspace ODG file first)
44
44
  - Do NOT invoke for: live order operations, dispute resolution, or post-publish tuning — those go to wowok-provider / wowok-arbitrator.
45
45
 
46
46
  ### Output Contract
@@ -51,7 +51,7 @@ A confirmed ODG JSON document (see §ODG Data Structure) with: scenario tag, com
51
51
 
52
52
  ## ODG Data Structure
53
53
 
54
- The ODG (Object Dependency Graph) is the single output artifact, persisted via `local_info_operation` and consumed by the Harness:
54
+ The ODG (Object Dependency Graph) is the single output artifact. Round state lives in the Goal / TaskProcess stream (`goal_operation`) and the ODG JSON itself is written to the local workspace via `workspace_operation`; the Harness consumes it phase-by-phase:
55
55
 
56
56
  ```json
57
57
  {
@@ -92,4 +92,4 @@ Each object has: `id`, `type`, `status` (planned/created/published), `reversible
92
92
  5. **Contact (customer service)** is configured before Service publish — `Service.um → Contact → ims[]`, with the local account enabled as messenger and anti-spam set.
93
93
  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`).
94
94
 
95
- 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.
95
+ 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 CHANGED
@@ -55,13 +55,13 @@ For each item, the user must provide one of: **"Reuse existing: `<name_or_id>`"*
55
55
 
56
56
  | # | Item | User Must Provide | Why Not Fabricate |
57
57
  |---|------|-------------------|--------------------|
58
- | **R1** | **Account** | Account name/address. Default `""` is fine. | Safe default exists |
59
- | **R2** | **Permission** | Existing Permission to reuse, OR name + type_parameter for new. **Reuse strongly recommended.** | Controls access to ALL your services |
60
- | **R3** | **Service (DRAFT)** | Service name, type_parameter. Create the draft FIRST (unpublished) so Guards can reference it by LocalMark NAME. | Your brand identity on-chain; breaks Guard↔Service cycle |
61
- | **R4** | **Machine** | Nodes, state transitions (pairs), forward paths. | IS your business process |
62
- | **R5** | **Guards** | For each Guard: validation logic, conditions. Reuse or define new. | Enforces your business rules |
63
- | **R6** | **Guard Bindings** | Which Guard validates which Machine forward? | Wrong binding = unauthorized access |
64
- | **R7** | **Allocators** | For each outcome: who gets what %/amount? (e.g. "success: 95% me, 5% platform") | IS your revenue model |
58
+ | **1** | **Account** | Account name/address. Default `""` is fine. | Safe default exists |
59
+ | **2** | **Permission** | Existing Permission to reuse, OR name + type_parameter for new. **Reuse strongly recommended.** | Controls access to ALL your services |
60
+ | **3** | **Service (DRAFT)** | Service name, type_parameter. Create the draft FIRST (unpublished) so Guards can reference it by LocalMark NAME. | Your brand identity on-chain; breaks Guard↔Service cycle |
61
+ | **4** | **Machine** | Nodes, state transitions (pairs), forward paths. | IS your business process |
62
+ | **5** | **Guards** | For each Guard: validation logic, conditions. Reuse or define new. | Enforces your business rules |
63
+ | **6** | **Guard Bindings** | Which Guard validates which Machine forward? | Wrong binding = unauthorized access |
64
+ | **7** | **Allocators** | For each outcome: who gets what %/amount? (e.g. "success: 95% me, 5% platform") | IS your revenue model |
65
65
 
66
66
  **Conditionally Required:**
67
67
 
@@ -74,11 +74,11 @@ For each item, the user must provide one of: **"Reuse existing: `<name_or_id>`"*
74
74
  ### Information Collection Protocol
75
75
 
76
76
  ```
77
- STEP 0: Present checklist R1-R7 to user
77
+ STEP 0: Present checklist Steps 1-7 to user
78
78
  ├── Each item: "Reuse or create new? Provide details."
79
79
  ├── Track status: [pending] / [confirmed: reuse <id>] / [confirmed: create]
80
80
  ├── If user indicates physical goods / customer_required → also confirm C1-C3
81
- └── ⛔ GATE: ALL R1-R7 must be [confirmed] before any on-chain action
81
+ └── ⛔ GATE: ALL Steps 1-7 must be [confirmed] before any on-chain action
82
82
  └── NOT confirmed → STOP. Ask. Do NOT suggest creating service.
83
83
  ```
84
84
 
@@ -96,7 +96,7 @@ STEP 0: Present checklist R1-R7 to user
96
96
 
97
97
  ## Service Build Lifecycle
98
98
 
99
- Once R1-R7 confirmed, execute in strict order. Sub-tools are invoked via `wowok({ tool: "<name>", data: { operation_type: "<type>", ... } })`; all use R1 (Account) as `env.account`.
99
+ Once Steps 1-7 confirmed, execute in strict order. Sub-tools are invoked via `wowok({ tool: "<name>", data: { operation_type: "<type>", ... } })`; all use Step 1 (Account) as `env.account`.
100
100
 
101
101
  **STEP 1 — Foundation**: Account (`account_operation` gen) → Permission (`onchain_operations` permission) → Service DRAFT (`onchain_operations` service, `publish: false` — Guards reference it by LocalMark NAME) → Machine unpublished (`onchain_operations` machine: nodes/pairs/forwards). Discovery `query_toolkit` (account_list/local_mark_list/onchain_objects); template `machineNode2file`.
102
102
 
@@ -108,7 +108,7 @@ Once R1-R7 confirmed, execute in strict order. Sub-tools are invoked via `wowok(
108
108
 
109
109
  **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).
110
110
 
111
- **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).
111
+ **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).
112
112
 
113
113
  **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.
114
114
 
@@ -135,7 +135,7 @@ Service → permission, machine (immutable), order_allocators (immutable),
135
135
  Order (runtime) → builder, service snapshot, machine, progress, dispute (Arb[]), allocation
136
136
  ```
137
137
 
138
- Cross-object references (which 9 object types hold a Guard and which 4 hold a Machine) are served by MCP `schema_query` action='get_guard_design_patterns'. Permission is the central hub — 11 objects hold BuiltinPermissionIndex.
138
+ Cross-object references — which object types host a Guard, which host a Machine, and which objects carry a `BuiltinPermissionIndex` — are served by MCP `schema_query` action='get_guard_design_patterns' (do not hardcode the counts; the object set evolves). Permission is the central access-control hub.
139
139
 
140
140
  ### Allocators + Machine Integration
141
141
 
package/wowok-supplier/SKILL.md CHANGED
@@ -110,7 +110,7 @@ If the upstream merchant stalls or withholds, escalate in order:
110
110
 
111
111
  ## Own-Interest Surfacing
112
112
 
113
- Run `query_toolkit` query_type='participation_radar' with your account + sub-order progress. The MCP derives your role (supplier) and attaches `supplier-interest` (fund_flow / responsibility / leverage / stakes). Present it as neutral information — the supplier decides.
113
+ Run `query_toolkit` query_type='participation_radar' with `radar_account` (your account) and `radar_targets: [{ progress: <sub-order Progress>, order: <sub-order, optional but recommended> }]`. The MCP derives your role (supplier) and attaches `supplier-interest` (fund_flow / responsibility / leverage / stakes). Present it as neutral information — the supplier decides.
114
114
 
115
115
  ---
116
116