@wowok/skills 1.2.3 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wowok/skills",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/references/guard-scenario-ledger.md

@@ -207,7 +207,7 @@
 - **Iterable**: Yes (not bound to any object, can create new tests anytime)
 
 **Use Cases**:
-- Test Guard logic via `onchain_operations(gen_passport)` without binding to any Host Object
+- Test Guard logic via `wowok({ tool: "onchain_operations", data: { operation_type: "gen_passport", ... } })` without binding to any Host Object
 - Verify Guard behavior under mock submission
 - Verify expected-pass and expected-fail boundary scenarios
 - Protected by `guard_gen_passport_test` confirmation rule (standard level)
@@ -319,7 +319,7 @@ For iterable scenes (buy_guard, Reward.guard, Repository.write_guard, Arbitratio
 
 1. **Export old Guard**: `guard2file` exports JSON backup
 2. **Edit JSON**: Modify based on old JSON (preserve identifier order, update table/root)
-3. **Create new Guard**: `onchain_operations(guard) CREATE`
+3. **Create new Guard**: `wowok({ tool: "onchain_operations", data: { operation_type: "guard", ... } })` CREATE
 4. **Rebind**: MODIFY Host Object's binding_field to point to new Guard
 5. **gen_passport test**: Run `gen_passport` on the new Guard
 6. **Post-verification**: Verify new Guard is active

package/references/machine-design-reference.md

@@ -48,7 +48,7 @@ A **Machine** is a **directed graph** (allows cycles): Node set + NodePair migra
 | Step | Phase | Description |
 |------|-------|-------------|
 | **M1** | Flow & Node Design | Extract business process, design nodes (entry/normal/terminal/branch), Pair + threshold, Forward + permissions |
-| **M2** | Machine Creation (unpublished) | `onchain_operations(machine) CREATE publish:false`, verify node/forward completeness |
+| **M2** | Machine Creation (unpublished) | `wowok({ tool: "onchain_operations", data: { operation_type: "machine", publish: false } })` CREATE, verify node/forward completeness |
 | **M3** | Guard Creation & Binding | Guard design (table + root tree), CREATE Guard, `gen_passport` static test, MODIFY Machine to bind Guards to Forwards |
 | **M4** | Pre-Publish Audit | 8D puzzle completeness, 5D risk assessment, topology analysis, on-chain limit checks, machineNode2file backup, independent Progress test |
 | **M5** | Publish & Bind Service | User explicit confirmation, `publish:true` (nodes frozen), bind Machine to Service, publish Service |

package/wowok-arbitrator/SKILL.md

@@ -244,9 +244,9 @@ See [Core Architecture > Key Flows](#arb-state-machine) above.
 ### Schema Access
 
 ```javascript
-schema_query({ action: "get", name: "onchain_operations_arbitration" })
-schema_query({ action: "get", name: "onchain_operations_order" })
-schema_query({ action: "get", name: "messenger_operation" })
+wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_arbitration" } })
+wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_order" } })
+wowok({ tool: "schema_query", data: { action: "get", name: "messenger_operation" } })
 ```
 
 ---

package/wowok-guard/APPENDIX.md

@@ -9,6 +9,8 @@
 
 A 10-round dialogue for the Guard authoring journey: from "I need a validation rule" through "tested, bound, and live". Guards are CREATE-only and immutable — this dialogue is deliberately heavy on design (R1-R6) before any on-chain write (R7), because there is no edit phase after creation. The sequence covers the four canonical Guard contexts (buy_guard, machine Forward guard, Allocator guard, Arbitration voting_guard) but the same shape applies to reward, repository, and demand Guards.
 
+> **Tool Call Convention**: All tool references in this document are sub-tools invoked via the single unified `wowok` tool. Translate every reference to `wowok({ tool: "<sub-tool-name>", data: {<params>} })`. See [wowok-tools](../wowok-tools/SKILL.md) for the full interface.
+
 ### R1: Validation Intent Capture
 
 **AI Goal**: Articulate the business requirement the Guard will enforce, in plain language, before any technical design. Identify which of the §Quick Decision patterns fits.
@@ -263,7 +265,7 @@ Guard needs to query object B, but caller submits object A's ID:
 ├── A = Order, B = Service? ──→ convert_witness: TypeOrderService
 ├── A = Progress, B = Machine? ──→ convert_witness: TypeProgressMachine
 ├── A = Reward, B = Service? ──→ convert_witness: TypeRewardService
-├── Other source→target pairs? ──→ query wowok_buildin_info (info: "guard instructions") for the complete witness type catalog
+├── Other source→target pairs? ──→ query `wowok({ tool: "wowok_buildin_info", data: { info: "guard instructions" } })` for the complete witness type catalog
 └── No conversion needed (caller submits the exact object the Guard queries)? ──→ omit convert_witness
 ```
 
@@ -288,7 +290,7 @@ Guard logic needs to change:
 │   ├── Export current Guard? ──→ guard2file → JSON/Markdown
 │   ├── Edit file (table, root tree, rely)? ──→ offline edit
 │   ├── Review edited JSON with user? ──→ confirm
-│   ├── CREATE new Guard from file? ──→ onchain_operations(guard) with root.type="file"
+│   ├── CREATE new Guard from file? ──→ `wowok({ tool: "onchain_operations", data: { operation_type: "guard", root: { type: "file", ... } } })`
 │   ├── Test new Guard? ──→ gen_passport with mock submissions
 │   ├── Rebind to host object? ──→ MODIFY host (if host is mutable)
 │   │   └── Host is immutable (published Machine/Service)? ──→ must create new host object too

package/wowok-guard/SKILL.md

@@ -320,7 +320,7 @@ The root tree is a computational expression whose terminal nodes read data and w
 
 Guard computational trees are built from typed nodes. Rather than listing all possible nodes (which evolves with the system), query the authoritative schema dynamically:
 
-**Tool**: `schema_query({ action: "get", name: "onchain_operations_guard" })`
+**Tool**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_guard" } })`
 
 This returns the complete `GuardNodeSchema` definition — every node type, its required fields, input/output types, and validation rules. Node categories include:
 
@@ -347,7 +347,7 @@ Use `onchain_operations` with `operation_type: "guard"`.
 - `root.type: "node"` — build the computation tree directly in the operation payload.
 - `root.type: "file"` — load the tree from a `guard2file`-exported JSON/Markdown file. Use this to iterate on existing Guards: export → edit file → create new Guard from file.
 
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_guard" })`
+**Schema Reference**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_guard" } })`
 
 ---
 
@@ -359,7 +359,7 @@ Before embedding a Guard into a live Machine, Service, or Arbitration, test it i
 
 **Tool**: `onchain_operations` with `operation_type: "gen_passport"`
 
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_gen_passport" })`
+**Schema Reference**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_gen_passport" } })`
 
 This tool verifies one or more Guards and, on success, generates an immutable Passport — a verified credential stored on-chain. Use it to:
 
@@ -390,7 +390,7 @@ Guards are immutable but iterable. The full cycle:
 1. guard2file <existing_guard> → JSON/Markdown file
 2. Edit file (table, root tree, rely)
 3. Review edited JSON with user → confirm
-4. onchain_operations(guard) with root.type="file" → new Guard created
+4. wowok({ tool: "onchain_operations", data: { operation_type: "guard", root: { type: "file", ... } } }) → new Guard created
 5. Update all references (Machine forwards, Service buy_guard, Arbitration voting_guard, etc.)
 ```
 

package/wowok-machine/SKILL.md

@@ -122,7 +122,7 @@ Machine
             └── guard (optional): condition that must pass
 ```
 
-> **Schema**: `schema_query({ action: "get", name: "onchain_operations_machine" })` — all field types, limits, valid values. This document focuses on design decisions **not captured** by the schema.
+> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_machine" } })` — all field types, limits, valid values. This document focuses on design decisions **not captured** by the schema.
 
 ### Forward Permission Model
 
@@ -188,7 +188,7 @@ Nine operations are available via the `node` field. Query schema for full parame
 - `exchange` swaps two node positions without delete/recreate. `rename` auto-updates all Pair references.
 - `add forward` supports the full `MachineForward` structure including `guard` with `retained_submission`.
 
-> **Schema**: `schema_query({ action: "get", name: "onchain_operations_machine" })` for full operation parameters.
+> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_machine" } })` for full operation parameters.
 
 ### File-Based Workflow
 
@@ -220,7 +220,7 @@ Two paths: **Service Order** (automatic when Order created on Service with bound
 
 Two-phase operations (`hold`/`unhold`) allow locking resources during multi-step operations; `adminUnhold` force-releases stale locks.
 
-> **Querying**: Progress state via `onchain_objects`, history via `onchain_table` / `onchain_table_item_progress_history`. Schema: `schema_query({ action: "get", name: "onchain_table_data" })`.
+> **Querying**: Progress state via `onchain_objects`, history via `onchain_table` / `onchain_table_item_progress_history`. Schema: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_table_data" } })`.
 
 ### Runtime: Advancing the Workflow
 

package/wowok-messenger/SKILL.md

@@ -25,7 +25,7 @@ always: false
 End-to-end encrypted messaging with tamper-proof audit trails.
 
 > **Role**: Any WoWok participant
-> **Schema**: `schema_query({ action: "get", name: "messenger_operation" })` — all 16 operations with full parameter types and constraints. This document focuses on **design decisions and strategy** not captured by the schema.
+> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "messenger_operation" } })` — all 16 operations with full parameter types and constraints. This document focuses on **design decisions and strategy** not captured by the schema.
 > **Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) (guard design), [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), [wowok-safety](../wowok-safety/SKILL.md) (safety)
 
 ---

package/wowok-onboard/APPENDIX.md

@@ -9,6 +9,8 @@
 
 Every round follows the same shape: state the goal, ask the key question(s), execute the MCP calls, verify success criteria, persist checkpoint, fall back on failure.
 
+> **Tool Call Convention**: All tool references in this document (e.g., `onchain_operations`, `query_toolkit`, `account_operation`) are sub-tools invoked via the single unified `wowok` tool. Translate every reference to `wowok({ tool: "<sub-tool-name>", data: {<params>} })`. See [wowok-tools](../wowok-tools/SKILL.md) for the full interface.
+
 ## Project-Based Deployment Integration
 
 The onboarding flow is integrated with the MCP project-based 5-stage deployment pipeline. Each stage gates progression to the next, with `project_operation` action calls providing deterministic validation:

package/wowok-order/SKILL.md

@@ -245,7 +245,7 @@ Clarify via Messenger: deliverables (E2 WIP), timeline (E3 nodes), refund/cancel
 
 ## Phase 3: Order Creation
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_service" })`. Safety: [wowok-safety](../wowok-safety/SKILL.md).
+Schema: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_service" } })`. Safety: [wowok-safety](../wowok-safety/SKILL.md).
 
 **Not in schema**:
 - Excess `buy.total_pay` auto-refunded. Agents cannot withdraw.
@@ -257,7 +257,7 @@ Post-creation: notify via Messenger with order ID.
 
 ## Phase 4: Order Operations
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_order" })`.
+Schema: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_order" } })`.
 
 ### Progress Advancement
 
@@ -277,7 +277,7 @@ Present all three dimensions. Never just the operation name.
 
 ## Phase 5: Arbitration
 
-Schema: `schema_query({ action: "get", name: "onchain_operations_arbitration" })`. Process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
+Schema: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_arbitration" } })`. Process: [wowok-arbitrator](../wowok-arbitrator/SKILL.md).
 
 Flow: `arbitration.dispute` → WTS evidence → Messenger → `order.arb_confirm` → voting → (`order.arb_objection`) → `order.arb_claim_compensation`.
 
@@ -410,7 +410,7 @@ Toggle example: `config_operation` → `action: "toggle"`, `service: "order_moni
 
 ## Quick Reference
 
-Schemas: `schema_query({ action: "get", name: "<name>" })` for `onchain_operations_service`, `onchain_operations_order`, `onchain_operations_arbitration`, `messenger_operation`, `query_toolkit`, `onchain_table_data`, `wip_file`.
+Schemas: `wowok({ tool: "schema_query", data: { action: "get", name: "<name>" } })` for `onchain_operations_service`, `onchain_operations_order`, `onchain_operations_arbitration`, `messenger_operation`, `query_toolkit`, `onchain_table_data`, `wip_file`.
 
 ### Phase Dependency
 

package/wowok-planner/APPENDIX.md

@@ -9,6 +9,8 @@
 
 Each round follows: state the goal, ask the minimum questions needed, gather inputs (LLM translation only when free text is ambiguous), update the ODG in memory, persist checkpoint, advance.
 
+> **Tool Call Convention**: All tool references in this document (e.g., `project_operation`, `onchain_operations`) are sub-tools invoked via the single unified `wowok` tool. Translate every reference to `wowok({ tool: "<sub-tool-name>", data: {<params>} })`. See [wowok-tools](../wowok-tools/SKILL.md) for the full interface.
+
 ## Project-Based Deployment Integration
 
 The planner flow integrates with the MCP project-based deployment pipeline (5 stages). Each stage maps to specific R rounds:

package/wowok-provider/APPENDIX.md

@@ -9,6 +9,8 @@
 
 A 10-round dialogue for the merchant operations journey: from "I want to set up a service" through "published, live, and accepting orders". This dialogue assumes the merchant has an account (per [wowok-onboard](../wowok-onboard/SKILL.md) R1) and may have a partial configuration. Each round maps to one R-item in the §PRE-FLIGHT checklist or one STEP in the §Service Build Lifecycle. The §Anti-Fabrication Rules are non-negotiable throughout — the AI never invents products, prices, workflow, or fund splits.
 
+> **Tool Call Convention**: All tool references in this document (e.g., `onchain_operations`, `query_toolkit`, `messenger_operation`) are sub-tools invoked via the single unified `wowok` tool. Translate every reference to `wowok({ tool: "<sub-tool-name>", data: {<params>} })`. See [wowok-tools](../wowok-tools/SKILL.md) for the full interface.
+
 ## Project-Based Deployment Integration
 
 The provider flow integrates with the MCP project-based deployment pipeline (5 stages). The relevant stages for the operations journey are:
@@ -320,7 +322,7 @@ Should I add a Compensation Fund?
 
 ```
 Merchant daily check-in:
-├── New orders? ──→ query_toolkit.onchain_events (NewOrderEvent) → fulfill per Machine workflow
+├── New orders? ──→ `wowok({ tool: "query_toolkit", data: { query_type: "onchain_events", ... } })` (NewOrderEvent) → fulfill per Machine workflow
 ├── Orders stuck at a node? ──→ query Progress → check Forward operators / Guard submissions → advance or contact customer
 ├── Customer messages? ──→ messenger_operation.watch_conversations (unreadOnly: true) → respond
 ├── Funds to claim? ──→ allocation.alloc_by_guard (anyone can trigger; verify fund flow)

package/wowok-provider/SKILL.md

@@ -91,20 +91,22 @@ STEP 0: Present checklist R1-R7 to user
 Once R1-R7 confirmed, execute in strict order. All operations use R1 (Account) as `env.account`.
 
 ```
+All Tool: references below are sub-tools invoked via wowok({ tool: "<name>", data: { operation_type: "<type>", ... } })
+
 STEP 1: Foundation
 ├── Permission — REUSE existing (strongly recommended)
-│     Tool: onchain_operations (permission) | Fields: name, type_parameter
+│     Tool: "onchain_operations" (permission) | Fields: name, type_parameter
 ├── Service (unpublished) — CREATE new
-│     Tool: onchain_operations (service) | Fields: name, type_parameter, permission
+│     Tool: "onchain_operations" (service) | Fields: name, type_parameter, permission
 └── Machine (unpublished) — CREATE new or REUSE template
-      Tool: onchain_operations (machine) | Fields: nodes, pairs, forwards
-      Discovery: query_toolkit (account_list, local_mark_list, onchain_objects)
-      Template: machineNode2file (export existing for editing)
+      Tool: "onchain_operations" (machine) | Fields: nodes, pairs, forwards
+      Discovery: "query_toolkit" (account_list, local_mark_list, onchain_objects)
+      Template: "machineNode2file" (export existing for editing)
 
 STEP 2: Trust Layer
 └── Guards — CREATE new or REUSE existing
-      Tool: onchain_operations (guard) | Fields: logic, instructions
-      Template: guard2file (export existing for editing)
+      Tool: "onchain_operations" (guard) | Fields: logic, instructions
+      Template: "guard2file" (export existing for editing)
       ⚠️ Design your Guard tables based on how the target object reads data:
          - buy_guard → pass/fail only, no data extraction
          - Allocator guard → pass/fail only
@@ -114,22 +116,22 @@ STEP 2: Trust Layer
 
 STEP 3: Business Logic (MODIFY)
 ├── Machine — bind Guards to forwards
-│     Tool: onchain_operations (machine)
+│     Tool: "onchain_operations" (machine)
 ├── Service — set Allocators
-│     Tool: onchain_operations (service) | Fields: order_allocators
+│     Tool: "onchain_operations" (service) | Fields: order_allocators
 ├── Arbitrations (optional) — REUSE existing Arb services
-│     Tool: onchain_operations (service) | Fields: arbitrations.list
+│     Tool: "onchain_operations" (service) | Fields: arbitrations.list
 ├── Compensation Fund (optional): compensation_fund_add + setting_locked_time_add (default 30 days, configurable)
-│     Tool: onchain_operations (service)
+│     Tool: "onchain_operations" (service)
 └── Reward (optional) — incentive pools
 
 STEP 4: Publication
 ├── Publish Machine → IMMUTABLE
-│     Tool: onchain_operations (machine) | publish: true
+│     Tool: "onchain_operations" (machine) | publish: true
 ├── Bind Machine to Service
-│     Tool: onchain_operations (service) | machine: "<machine_id>"
+│     Tool: "onchain_operations" (service) | machine: "<machine_id>"
 └── Publish Service → machine/allocators LOCKED
-      Tool: onchain_operations (service) | publish: true
+      Tool: "onchain_operations" (service) | publish: true
 
       ⚠️ Pre-Publish Verification:
       1. Re-check PRE-FLIGHT: all R1-R7 still confirmed?
@@ -233,7 +235,7 @@ Each `sharing[].who` field determines where funds go. Choose the correct type ba
 After the Progress reaches a terminal state, the fund allocation is NOT automatic — it must be triggered explicitly. **Anyone can call this operation**; the caller does not need to be the merchant or customer. The Guard verification determines which allocator's rules apply.
 
 ```
-Tool: onchain_operations (allocation)
+Tool: wowok({ tool: "onchain_operations", data: { operation_type: "allocation", ... } })
 Operation: alloc_by_guard
 Required submission: Order ID (matching the Guard's b_submission identifier)
 ```
@@ -249,8 +251,8 @@ Required submission: Order ID (matching the Guard's b_submission identifier)
 Immutable product commitment for arbitration evidence.
 
 ```
-Create:  wip_file → generate → markdown_text + images → outputPath
-Attach: onchain_operations (service) → sales.sales[{
+Create:  wowok({ tool: "wip_file", data: { op: "generate", ... } }) → markdown_text + images → outputPath
+Attach: wowok({ tool: "onchain_operations", data: { operation_type: "service", ... } }) → sales.sales[{
           name, price, stock, wip: "<URL>", wip_hash: "" (auto)
         }]
 ```
@@ -285,7 +287,7 @@ Attach: onchain_operations (service) → sales.sales[{
 | Messenger | `messenger_operation` |
 | Query | `query_toolkit` |
 
-**Export**: `machineNode2file`, `guard2file` | **Query Schema**: `schema_query({ action: "get", name: "<name>" })`
+**Export**: `machineNode2file`, `guard2file` | **Query Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "<name>" } })`
 
 ---
 

package/wowok-safety/APPENDIX.md

@@ -9,6 +9,8 @@
 
 A guided 10-round dialogue for the safety verification journey — runs before ANY on-chain write operation. Each round has a specific AI Goal, Key Questions, Tool Calls, Success Criteria, Fallback, and Checkpoint. Checkpoints persist via `local_info_operation` so the verification can resume after interruption.
 
+> **Tool Call Convention**: All tool references in this document are sub-tools invoked via the single unified `wowok` tool. Translate every reference to `wowok({ tool: "<sub-tool-name>", data: {<params>} })`. See [wowok-tools](../wowok-tools/SKILL.md) for the full interface.
+
 > **Trigger**: This dialogue is automatically invoked when the user requests an on-chain write operation (transfer, publish, create, modify, etc.). It is the safety gate that all writes must pass through.
 
 ### R1 — Operation Intent Capture
@@ -309,24 +311,26 @@ What level of confirmation does this operation need?
 ### D3: LOCAL vs ON-CHAIN vs QUERY
 
 ```
+All sub-tools below are accessed via: wowok({ tool: "<sub-tool-name>", data: {<params>} })
+
 Classifying the operation:
 ├── LOCAL ONLY (no gas, no confirmation)
-│   ├── account_operation (gen, get, faucet, messenger, etc.)
-│   ├── local_mark_operation
-│   └── local_info_operation
+│   ├── tool: "account_operation" (gen, get, faucet, messenger, etc.)
+│   ├── tool: "local_mark_operation"
+│   └── tool: "local_info_operation"
 ├── ON-CHAIN (gas required, confirmation required)
-│   ├── onchain_operations (all 16 operation_types)
-│   ├── messenger_operation (some ops — sign, proof_message)
-│   └── wip_file (sign)
+│   ├── tool: "onchain_operations" (all 16 operation_types)
+│   ├── tool: "messenger_operation" (some ops — sign, proof_message)
+│   └── tool: "wip_file" (sign)
 ├── QUERY (read-only, no gas, no confirmation)
-│   ├── query_toolkit
-│   ├── onchain_table_data
-│   ├── onchain_events
-│   ├── guard2file
-│   ├── machineNode2file
-│   └── wowok_buildin_info
+│   ├── tool: "query_toolkit"
+│   ├── tool: "onchain_table_data"
+│   ├── tool: "onchain_events"
+│   ├── tool: "guard2file"
+│   ├── tool: "machineNode2file"
+│   └── tool: "wowok_buildin_info"
 └── ENCRYPTED (local encryption, no gas)
-    └── messenger_operation (watch/send messages — local ops)
+    └── tool: "messenger_operation" (watch/send messages — local ops)
 ```
 
 ### D4: Publish Readiness Check

package/wowok-safety/SKILL.md

@@ -262,7 +262,7 @@ For complex objects with many fields (Service, Machine), use **incremental build
 | Guard instructions | `wowok_buildin_info` with `info: "guard instructions"` |
 | Value types | `wowok_buildin_info` with `info: "value types"` |
 
-**Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
+**Query Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "<schema_name>" } })`
 
 **Related Skills**: [wowok-tools](../wowok-tools/SKILL.md) | [wowok-guard](../wowok-guard/SKILL.md) | [wowok-machine](../wowok-machine/SKILL.md) | [wowok-order](../wowok-order/SKILL.md) | [wowok-provider](../wowok-provider/SKILL.md) | [wowok-arbitrator](../wowok-arbitrator/SKILL.md) | [wowok-messenger](../wowok-messenger/SKILL.md)
 

package/wowok-tools/APPENDIX.md

@@ -19,10 +19,10 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - Are you operating on-chain or only locally?
 
 **Tool Calls**:
-1. `query_toolkit` → `local_names` — list accounts and local marks so the AI can phrase follow-ups in terms the user already knows.
+1. `wowok({ tool: "query_toolkit", data: { query_type: "local_names", ... } })` — list accounts and local marks so the AI can phrase follow-ups in terms the user already knows.
 2. (No write call yet — R1 is classification only.)
 
-**Success Criteria**: AI articulates the classified intent back to the user in plain language ("You want to write on-chain state, so we'll use `onchain_operations`. Next we pick the operation_type.") and the user confirms.
+**Success Criteria**: AI articulates the classified intent back to the user in plain language ("You want to write on-chain state, so we'll use `wowok({ tool: 'onchain_operations', data: {...} })`. Next we pick the operation_type.") and the user confirms.
 
 **Fallback**: User intent is genuinely ambiguous (e.g., "I want to set up a shop" could mean account creation OR service creation) → ask one disambiguating question, do not guess. If user invokes by raw tool name ("use `messenger_operation`"), skip R2-R3 and jump to the parameter-shape rounds.
 
@@ -38,8 +38,8 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - (Communicate) Plain message, file, or WTS evidence?
 
 **Tool Calls**:
-1. `schema_query` → `list` — confirm available schemas are generated (catches the "empty list → run `npm run generate:schemas`" trap from §13).
-2. (For `onchain_operations`) `schema_query` → `get` for the candidate operation_type schema (e.g., `onchain_operations_service`) to surface required fields early.
+1. `wowok({ tool: "schema_query", data: { action: "list" } })` — confirm available schemas are generated (catches the "empty list → run `npm run generate:schemas`" trap from §13).
+2. (For `onchain_operations`) `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_service" } })` for the candidate operation_type schema to surface required fields early.
 
 **Success Criteria**: One tool name and (for `onchain_operations`) one `operation_type` are committed. AI shows the user the high-level parameter shape and gets a "yes, that looks right".
 
@@ -56,7 +56,7 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - For everything else: do you have the `data` payload ready, or do you need to collect it across R4-R6?
 
 **Tool Calls**:
-1. `schema_query` → `get` for the specific branch (e.g., `onchain_operations_gen_passport`) to lock the exact field set.
+1. `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations_gen_passport" } })` for the specific branch to lock the exact field set.
 2. Cross-reference §Structural Wrapper Rules table to confirm `data` presence and `submission` presence.
 
 **Success Criteria**: The AI presents the exact JSON skeleton with field names (not values yet) and the user confirms the shape.
@@ -75,9 +75,9 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - (If building multiple interdependent objects) OK to set `no_cache: true` to avoid stale-read failures?
 
 **Tool Calls**:
-1. `query_toolkit` → `account_balance` for the chosen account — verify balance > 0 before any write.
-2. If balance = 0: `account_operation` → `faucet` (testnet) OR `account_operation` → `transfer` from a funded account (mainnet).
-3. (Optional) `query_toolkit` → `token_list` to confirm token decimals if amounts are involved.
+1. `wowok({ tool: "query_toolkit", data: { query_type: "account_balance", ... } })` for the chosen account — verify balance > 0 before any write.
+2. If balance = 0: `wowok({ tool: "account_operation", data: { faucet: { ... } } })` (testnet) OR `wowok({ tool: "account_operation", data: { transfer: { ... } } })` from a funded account (mainnet).
+3. (Optional) `wowok({ tool: "query_toolkit", data: { query_type: "token_list", ... } })` to confirm token decimals if amounts are involved.
 
 **Success Criteria**: An account with non-zero balance is committed; `network` and `no_cache` are decided. AI shows the final `env` block.
 
@@ -95,8 +95,8 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - (If create) What are the new object's required fields?
 
 **Tool Calls**:
-1. `query_toolkit` → `onchain_objects` — verify any "reuse" string actually resolves (catches typos before the SDK's `GetObjectExisted()` hard-errors).
-2. `local_mark_operation` → optional: tag a reused object with a friendly name for future reference.
+1. `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects", ... } })` — verify any "reuse" string actually resolves (catches typos before the SDK's `GetObjectExisted()` hard-errors).
+2. `wowok({ tool: "local_mark_operation", data: { ... } })` → optional: tag a reused object with a friendly name for future reference.
 
 **Success Criteria**: Every object-typed field is annotated as REUSE (with verified name/address) or CREATE (with field draft). The full `data` payload skeleton is now populated with placeholders.
 
@@ -114,8 +114,8 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - Custom indices must be ≥ 1000 (0–999 reserved). What indices does your Permission define?
 
 **Tool Calls**:
-1. `query_toolkit` → `onchain_objects` (filter type=Permission) — list candidates for reuse.
-2. `wowok_buildin_info` → `info: "built-in permissions"` — confirm which 0–999 indices are protocol-reserved so the user doesn't try to claim one.
+1. `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects", filter: { type: "Permission" } } })` — list candidates for reuse.
+2. `wowok({ tool: "wowok_buildin_info", data: { info: "built-in permissions" } })` — confirm which 0–999 indices are protocol-reserved so the user doesn't try to claim one.
 
 **Success Criteria**: Every `permissionIndex` value exists in the chosen Permission; every `namedOperator` is either `""` (order owner/agents) or a role name the user explicitly defined.
 
@@ -133,8 +133,8 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - Do you have that data ready, or do we collect it in R8?
 
 **Tool Calls**:
-1. `guard2file` → export every Guard the operation will hit — inspect `table` entries with `b_submission: true` to know what the prompt will ask.
-2. `wowok_buildin_info` → `info: "guard instructions"` — confirm any `query` node's instruction ID and parameter count.
+1. `wowok({ tool: "guard2file", data: { ... } })` → export every Guard the operation will hit — inspect `table` entries with `b_submission: true` to know what the prompt will ask.
+2. `wowok({ tool: "wowok_buildin_info", data: { info: "guard instructions" } })` — confirm any `query` node's instruction ID and parameter count.
 
 **Success Criteria**: AI can enumerate the exact submission fields the user will be prompted for, and the user has confirmed they can provide each.
 
@@ -151,12 +151,12 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - (If the call has no Guard) Confirm the full execution, since this is the only shot.
 
 **Tool Calls**:
-1. `onchain_operations` (or other write tool) with the full `data` and `env`, omitting `submission`.
+1. `wowok({ tool: "onchain_operations", data: { operation_type: "<type>", data: {<full payload>}, env: {<env block>}, /* omit submission */ } })` with the full payload, omitting `submission`.
 2. Capture the response: either success (no Guard) or a structured submission prompt.
 
 **Success Criteria**: Either the operation succeeds (no Guard involved) OR a structured submission prompt is returned and parsed.
 
-**Fallback**: Call reverts with a gas error → re-faucet (R4 fallback), retry. Call reverts with "object not found" despite just creating it → set `env.no_cache: true` and retry (stale-cache trap from §Error Patterns). Schema validation error → re-read the schema via `schema_query`, fix the field, retry.
+**Fallback**: Call reverts with a gas error → re-faucet (R4 fallback), retry. Call reverts with "object not found" despite just creating it → set `env.no_cache: true` and retry (stale-cache trap from §Error Patterns). Schema validation error → the response includes `schema.input`; read it, fix the field, retry. Or use `wowok({ tool: "schema_query", data: { action: "get", name: "..." } })` to re-read the schema.
 
 **Checkpoint**: Persist `{ round: R8, phase: probe, response: success|prompt, prompt_fields?: [...] }`.
 
@@ -169,9 +169,9 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 - (Verify) Want me to query the resulting object and show you the diff?
 
 **Tool Calls**:
-1. (Phase 2) `onchain_operations` with the same `data` + `env` + `submission` populated.
-2. (Verify) `query_toolkit` → `onchain_objects` for the resulting object ID; `onchain_events` for the emitted event.
-3. (Optional) `local_mark_operation` → tag the new object with a friendly name.
+1. (Phase 2) `wowok({ tool: "onchain_operations", data: { operation_type: "<type>", data: {<same payload>}, env: {<env>}, submission: {<collected answers>} } })` with `submission` populated.
+2. (Verify) `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects", ... } })` for the resulting object ID; `wowok({ tool: "onchain_events", data: { ... } })` for the emitted event.
+3. (Optional) `wowok({ tool: "local_mark_operation", data: { ... } })` → tag the new object with a friendly name.
 
 **Success Criteria**: Operation finalizes successfully; on-chain query confirms the expected state; local mark persisted for future reference.
 
@@ -204,28 +204,32 @@ A 10-round dialogue for the tool-selection journey: a user (or another Skill) ar
 ### D1: Tool Family by Operation Class
 
 ```
+All calls via: wowok({ tool: "<sub-tool>", data: {<params>} })
+
 User intent
-├── Write on-chain state? ──→ onchain_operations
+├── Write on-chain state? ──→ tool: "onchain_operations"
 │   ├── Generating a credential? ──→ operation_type: gen_passport (no data wrapper)
 │   ├── Transferring tokens? ──→ operation_type: payment (no submission)
 │   ├── Updating personal profile? ──→ operation_type: personal (no submission)
 │   └── Anything else? ──→ operation_type: service|machine|progress|guard|order|allocation|arbitration|treasury|reward|demand|contact|repository|permission (full wrapper)
-├── Read on-chain state? ──→ query_toolkit OR onchain_table_data
-│   ├── Single object or simple list? ──→ query_toolkit
-│   ├── Dynamic table row? ──→ onchain_table_data (needs parent except entity_registrar / entity_linker)
-│   └── Historical events? ──→ onchain_events
-├── Communicate? ──→ messenger_operation
-├── Local-only? ──→ account_operation | local_mark_operation | local_info_operation
-├── Export for review? ──→ guard2file | machineNode2file | wip_file (verify/wts2html)
-└── Discover schemas/instructions? ──→ schema_query | wowok_buildin_info
+├── Read on-chain state? ──→ tool: "query_toolkit" OR "onchain_table_data"
+│   ├── Single object or simple list? ──→ tool: "query_toolkit"
+│   ├── Dynamic table row? ──→ tool: "onchain_table_data" (needs parent except entity_registrar / entity_linker)
+│   └── Historical events? ──→ tool: "onchain_events"
+├── Communicate? ──→ tool: "messenger_operation"
+├── Local-only? ──→ tool: "account_operation" | "local_mark_operation" | "local_info_operation"
+├── Export for review? ──→ tool: "guard2file" | "machineNode2file" | "wip_file" (verify/wts2html)
+└── Discover schemas/instructions? ──→ tool: "schema_query" | "wowok_buildin_info"
 ```
 
 ### D2: CREATE vs MODIFY (per object-typed field)
 
 ```
+All calls via: wowok({ tool: "<sub-tool>", data: {<params>} })
+
 For each field whose value could be a string OR an object:
 ├── User said "reuse <name>" or gave 0x address? ──→ REUSE
-│   ├── query_toolkit.onchain_objects verifies it resolves? ──→ use string value
+│   ├── wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects" } }) verifies it resolves? ──→ use string value
 │   └── Does not resolve? ──→ ask: typo, or did you mean CREATE?
 ├── User said "create new" with details? ──→ CREATE (object shape)
 ├── User unsure? ──→ query on-chain candidates, present list, let user pick or create
@@ -235,7 +239,7 @@ For each field whose value could be a string OR an object:
 ### D3: Submission Loop Branch
 
 ```
-About to call onchain_operations:
+About to call wowok({ tool: "onchain_operations", data: { ... } }):
 ├── Branch is gen_passport, payment, or personal? ──→ ONE-SHOT (no submission field)
 ├── Branch has submission in schema?
 │   ├── Call WITHOUT submission first ──→ SDK returns prompt? ──→ collect answers, re-call WITH submission
@@ -246,11 +250,11 @@ About to call onchain_operations:
 ### D4: Error Recovery Routing
 
 ```
-Tool call returned error:
-├── Gas / insufficient balance? ──→ query_toolkit.account_balance → faucet or transfer → retry
+wowok() call returned error:
+├── Gas / insufficient balance? ──→ wowok({ tool: "query_toolkit", data: { query_type: "account_balance" } }) → faucet or transfer → retry
 ├── "Object not found" right after create? ──→ env.no_cache: true → retry (stale cache)
-├── Guard validation failure? ──→ guard2file export → inspect logic tree → fix submission → retry
-├── Schema validation error? ──→ schema_query.get for the branch → diff against payload → fix → retry
+├── Guard validation failure? ──→ wowok({ tool: "guard2file", data: { ... } }) export → inspect logic tree → fix submission → retry
+├── Schema validation error (result.status = "schema_mismatch")? ──→ read schema.input from response → fix → retry. Or wowok({ tool: "schema_query", data: { action: "get" } }) for full schema.
 ├── Permission denied? ──→ query Permission object → verify caller's index → add index or switch account
 ├── "machine not published" on service.publish? ──→ publish Machine first, then retry Service publish
 └── Network timeout? ──→ retry once; if persists, switch network or escalate
@@ -259,12 +263,14 @@ Tool call returned error:
 ### D5: Handoff Next-Action
 
 ```
+All calls via: wowok({ tool: "<sub-tool>", data: {<params>} })
+
 Just-completed operation:
 ├── service CREATE ──→ next: machine CREATE (Service needs a Machine before publish)
 ├── machine CREATE ──→ next: guard CREATE × N (Guards must exist before binding)
 ├── guard CREATE ──→ next: gen_passport test (verify logic before binding)
-├── service publish ──→ next: query_toolkit.onchain_objects verify bPublished=true
-├── query Service ──→ next (if user wants contact): messenger_operation
+├── service publish ──→ next: wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects" } }) verify bPublished=true
+├── query Service ──→ next (if user wants contact): wowok({ tool: "messenger_operation", data: { ... } })
 ├── messenger WTS send ──→ next: arbitration.dispute (evidence closed)
 ├── order.advance ──→ next: query allocation balance (verify fund flow)
 └── None of the above ──→ re-invoke R1 intent classification
@@ -276,17 +282,17 @@ Just-completed operation:
 
 ### F1: Schema List Returns Empty
 
-**Trigger**: `schema_query` → `list` returns `[]` or throws "schemas not generated".
+**Trigger**: `wowok({ tool: "schema_query", data: { action: "list" } })` returns `[]` or throws "schemas not generated".
 
 **Diagnosis**: The MCP server's schema files were not generated at deploy time. This is a deployment gap, not a usage error.
 
 **Recovery**:
 1. Surface the issue to the user plainly: "The schema files are missing on the server side."
-2. Instruct running `npm run generate:schemas` on the MCP server host (per tool #13 in §The 13 Tools).
+2. Instruct running `npm run generate:schemas` on the MCP server host (per §The 17 Sub-Tools, sub-tool #13).
 3. While waiting, fall back to the field shapes documented in this Skill and in [wowok-safety](../wowok-safety/SKILL.md) — they are authoritative even without the generated schema.
-4. After regeneration, re-run `schema_query.list` to confirm.
+4. After regeneration, re-run `wowok({ tool: "schema_query", data: { action: "list" } })` to confirm.
 
-**Prevention**: Add a `schema_query.list` health check at the start of every fresh session. If empty, fail fast and surface the deploy issue before any write attempt.
+**Prevention**: Add a `wowok({ tool: "schema_query", data: { action: "list" } })` health check at the start of every fresh session. If empty, fail fast and surface the deploy issue before any write attempt.
 
 ### F2: Stale Cache After Sequential Creates
 
@@ -296,14 +302,14 @@ Just-completed operation:
 
 **Recovery**:
 1. Retry operation B with `env.no_cache: true`.
-2. If still failing, query the object directly via `query_toolkit` → `onchain_objects` with `no_cache: true` to confirm it actually exists on-chain.
+2. If still failing, query the object directly via `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects", no_cache: true, ... } })` to confirm it actually exists on-chain.
 3. If on-chain confirms existence, retry B once more with `no_cache: true`.
 
 **Prevention**: When building multiple interdependent objects in one session (the common case in onboarding), set `env.no_cache: true` on EVERY operation from the start. The minor latency cost is far cheaper than debugging stale-cache failures mid-flow.
 
 ### F3: Submission Loop Misuse
 
-**Trigger**: User (or AI) calls `onchain_operations` with `submission` populated on the first try, and the call either reverts or silently accepts wrong data.
+**Trigger**: User (or AI) calls `wowok({ tool: "onchain_operations", data: { ..., submission: {...} } })` with `submission` populated on the first try, and the call either reverts or silently accepts wrong data.
 
 **Diagnosis**: The two-phase pattern was skipped. Either the AI guessed the submission fields, or the user pasted a submission from a previous unrelated call.
 
@@ -317,14 +323,14 @@ Just-completed operation:
 
 ### F4: Guard creation fails with type mismatch
 
-**Trigger**: `onchain_operations` → `operation_type: "guard"` CREATE reverts with a type-validation error (e.g., `logic_equal` received String vs U64).
+**Trigger**: `wowok({ tool: "onchain_operations", data: { operation_type: "guard", ... } })` CREATE reverts with a type-validation error (e.g., `logic_equal` received String vs U64).
 
 **Diagnosis**: The computational tree has a type incompatibility that the schema-layer validation caught. Common variants: comparing across numeric widths without `logic_as_u256_*`, missing `convert_witness` when querying Progress from an Order, or a `query` node with the wrong parameter count.
 
 **Recovery**:
 1. Inspect the error message — it usually names the offending node and the expected vs actual types.
-2. Cross-reference `wowok_buildin_info` → `info: "value types"` to confirm numeric codes.
-3. Cross-reference `wowok_buildin_info` → `info: "guard instructions"` to confirm the `query` node's instruction ID and parameter count.
+2. Cross-reference `wowok({ tool: "wowok_buildin_info", data: { info: "value types" } })` to confirm numeric codes.
+3. Cross-reference `wowok({ tool: "wowok_buildin_info", data: { info: "guard instructions" } })` to confirm the `query` node's instruction ID and parameter count.
 4. Fix the tree, re-attempt CREATE. Guards are CREATE-only — there is no MODIFY, so a failed CREATE simply retries.
 
 **Prevention**: Before any Guard CREATE, mentally (or via a scratch file) walk the tree: every `identifier` index exists in the table; every comparison node receives compatible operand types; every `query` node's parameter count matches the instruction. The §Guard Best Practices traps 1–4 catch 90% of pre-flight issues.
@@ -336,24 +342,24 @@ Just-completed operation:
 **Diagnosis**: The operating account lacks the required `permissionIndex` in the governing Permission object, OR the Forward's `namedOperator` doesn't match the caller's role.
 
 **Recovery**:
-1. `query_toolkit` → `onchain_objects` for the governing Permission — list its indices.
+1. `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects", filter: { type: "Permission" } } })` for the governing Permission — list its indices.
 2. Cross-reference the operation's required index (from the schema or the Machine Forward definition).
-3. Either: switch to an account that holds the index, OR have the Permission owner add the index for the current account, OR (if Forward uses `namedOperator`) assign the role via `progress` MODIFY.
+3. Either: switch to an account that holds the index, OR have the Permission owner add the index for the current account, OR (if Forward uses `namedOperator`) assign the role via `wowok({ tool: "onchain_operations", data: { operation_type: "progress", ... } })` MODIFY.
 
 **Prevention**: During onboarding R6 (Permission resolution), record the full index→role map in the checkpoint. Before any operation, verify the caller's account holds the required index — this is a 1-query pre-flight that prevents 100% of permission-denied failures.
 
 ### F6: Faucet Exhausted on Testnet
 
-**Trigger**: `account_operation` → `faucet` returns rate-limit or timeout.
+**Trigger**: `wowok({ tool: "account_operation", data: { faucet: { ... } } })` returns rate-limit or timeout.
 
 **Diagnosis**: Testnet faucet has per-account and per-IP rate limits. Common during onboarding loops with many test orders.
 
 **Recovery**:
 1. Wait 60 seconds and retry once.
-2. If still failing, `account_operation` → `transfer` 1 WOW (10^9 base units) from another funded account the user owns.
+2. If still failing, `wowok({ tool: "account_operation", data: { transfer: { amount: 1000000000, ... } } })` 1 WOW (10^9 base units) from another funded account the user owns.
 3. If no other account exists, surface the issue and pause — do not silently reduce example amounts (per §Mainnet operations, this rule applies to mainnet too).
 
-**Prevention**: Pre-fund each new account with 5+ WOW at creation time via a single `transfer` from a treasury account, rather than relying on faucet per-operation. Track each account's balance in `local_info_operation` and proactively top up below 1 WOW threshold.
+**Prevention**: Pre-fund each new account with 5+ WOW at creation time via a single `transfer` from a treasury account, rather than relying on faucet per-operation. Track each account's balance in `wowok({ tool: "local_info_operation", data: { ... } })` and proactively top up below 1 WOW threshold.
 
 ---
 
@@ -361,28 +367,28 @@ Just-completed operation:
 
 ### Novice Tier — Tool Discovery Path
 
-- Always start with `query_toolkit` → `local_names` to ground the conversation in objects the user already knows.
-- Use the §Decision Tree D1 (Tool Family by Operation Class) as a rigid router — do not let the user invoke tools by raw name until they've classified their intent.
-- For every `onchain_operations` call, follow the full R1-R10 sequence: classify → select → wrap → env → CREATE/MODIFY → permission → submission prep → probe → submit → handoff.
+- Always start with `wowok({ tool: "query_toolkit", data: { query_type: "local_names" } })` to ground the conversation in objects the user already knows.
+- Use the §Decision Tree D1 (Tool Family by Operation Class) as a rigid router — do not let the user invoke sub-tools by raw name until they've classified their intent.
+- For every `wowok({ tool: "onchain_operations", data: { ... } })` call, follow the full R1-R10 sequence: classify → select → wrap → env → CREATE/MODIFY → permission → submission prep → probe → submit → handoff.
 - The two-phase submission loop is non-negotiable: never pre-fill `submission`.
 - Always set `env.no_cache: true` when building multiple objects in one session.
-- After every write, verify via `query_toolkit` → `onchain_objects` before declaring success.
-- Trigger: user is new, or any time the AI is unsure which tool fits.
+- After every write, verify via `wowok({ tool: "query_toolkit", data: { query_type: "onchain_objects" } })` before declaring success.
+- Trigger: user is new, or any time the AI is unsure which sub-tool fits.
 
 ### Advanced Tier — Direct Tool Invocation
 
-- User invokes tools by name (e.g., "call `onchain_operations` with `operation_type: machine`"); AI provides the parameter shape and verifies, but does not re-classify intent from scratch.
+- User invokes sub-tools by name (e.g., "call `wowok({ tool: 'onchain_operations', data: { operation_type: 'machine' } })`"); AI provides the parameter shape and verifies, but does not re-classify intent from scratch.
 - The R1-R3 rounds can be collapsed into a single confirmation: "You want `<tool>` + `<operation_type>`. Confirm?"
 - `env.no_cache` is set selectively — only on operations known to depend on just-created objects.
-- Submission loop is still two-phase, but the AI pre-fetches the Guard's expected submissions via `guard2file` in parallel with R8's probe call, so R9 is faster.
+- Submission loop is still two-phase, but the AI pre-fetches the Guard's expected submissions via `wowok({ tool: "guard2file", data: { ... } })` in parallel with R8's probe call, so R9 is faster.
 - Handoff next-actions are surfaced as suggestions, not enforced.
 - Trigger: user says "I know what I'm doing" or has completed prior sessions.
 
 ### Expert Tier — Raw Schema & Edge Cases
 
-- User reads schemas directly via `schema_query` and constructs payloads by hand; AI's role is to catch schema-inexpressible traps (the three wrapper exceptions, first-Guard-wins ordering, convert_witness type rules) rather than to route.
+- User reads schemas directly via `wowok({ tool: "schema_query", data: { action: "get", name: "..." } })` and constructs payloads by hand; AI's role is to catch schema-inexpressible traps (the three wrapper exceptions, first-Guard-wins ordering, convert_witness type rules) rather than to route.
 - R1-R7 are skipped; AI engages at R8 (execute) and R10 (handoff).
 - The §Common Pitfalls table and §Structural Wrapper Rules become the primary reference, not the decision trees.
-- Expert users may compose multiple tool calls in a single transaction batch (where the SDK supports it) — AI verifies dependency ordering but does not serialize.
-- Expert users may use `gen_passport` as a standalone credential issuer (off-chain verification use case), not just as a Guard test — AI supports this path directly.
-- Trigger: user explicitly asks for "expert mode", references tools by raw name with parameters, or invokes `schema_query` themselves.
+- Expert users may compose multiple `wowok` calls in a single transaction batch (where the SDK supports it) — AI verifies dependency ordering but does not serialize.
+- Expert users may use `wowok({ tool: "onchain_operations", data: { operation_type: "gen_passport", ... } })` as a standalone credential issuer (off-chain verification use case), not just as a Guard test — AI supports this path directly.
+- Trigger: user explicitly asks for "expert mode", references sub-tools by raw name with parameters, or invokes `wowok({ tool: "schema_query", data: { ... } })` themselves.

package/wowok-tools/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: wowok-tools
 description: |
-  WoWok MCP tool reference — canonical documentation for all 13 MCP tools.
-  Covers schema-inexpressible constraints, business rules, interaction patterns,
-  and design decisions not captured by JSON Schema.
+  WoWok MCP tool reference — canonical documentation for the single unified
+  `wowok` tool and its 17 sub-tools. Covers schema-inexpressible constraints,
+  business rules, interaction patterns, and design decisions not captured by
+  JSON Schema.
 
   Core value: prevent common AI failures (wrong tool selection, incorrect
   parameter formats, missing structural wrappers, wrong discriminated unions).
@@ -17,13 +18,36 @@ always: true
 
 # WoWok MCP Tool Reference
 
-Canonical reference for all 13 MCP tools. Covers patterns, constraints, and design decisions that **JSON Schema cannot express**. For detailed business workflows, see the Domain and Business Skills below.
+Canonical reference for the single unified `wowok` tool and its 17 sub-tools. Covers patterns, constraints, and design decisions that **JSON Schema cannot express**. For detailed business workflows, see the Domain and Business Skills below.
 
 > **Domain Skills**: [wowok-guard](../wowok-guard/SKILL.md) (validation logic), [wowok-messenger](../wowok-messenger/SKILL.md) (encrypted messaging), [wowok-machine](../wowok-machine/SKILL.md) (workflows), [wowok-safety](../wowok-safety/SKILL.md) (safety & naming)
 > **Business Skills**: [wowok-order](../wowok-order/SKILL.md) (customer), [wowok-provider](../wowok-provider/SKILL.md) (merchant), [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (dispute resolution)
 
 ---
 
+## Single-Tool Interface (Schema-Gated Execution)
+
+MCP `tools/list` returns **only one tool**: `wowok`. All operations go through it.
+
+**Call pattern**: `wowok({ tool: "<sub-tool-name>", data: {<sub-tool params>} })`
+
+When any skill (including this one) says "Call `onchain_operations`" or "Use `schema_query`", translate it to:
+```
+wowok({ tool: "onchain_operations", data: { operation_type: "service", ... } })
+wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations" } })
+```
+
+**Schema-gated execution**: If `data` doesn't match the sub-tool's schema, the response includes:
+- `result.status = "schema_mismatch"` — validation failed
+- `result.errors` — specific field errors
+- `result.hint` — instructions to fix and retry
+- `schema.input` — the correct JSON schema for the sub-tool
+- `schema.tool` — which sub-tool this schema belongs to
+
+**Schema caching**: Each sub-tool has a different schema. When you receive a schema in a mismatch response, cache it in your context for future calls to the same sub-tool. You should only need to see each sub-tool's schema once per conversation.
+
+---
+
 ## 🔴 Gas and Faucet
 
 On-chain operations require gas. Transactions will fail if the account has insufficient balance.
@@ -32,15 +56,15 @@ On-chain operations require gas. Transactions will fail if the account has insuf
 
 When assisting users with WoWok operations:
 
-- After a user creates a new account, proactively call `account_operation` → `faucet` to claim test tokens on their behalf
-- Before starting any on-chain workflow, check balance via `query_toolkit` → `account_balance`
+- After a user creates a new account, proactively call `wowok({ tool: "account_operation", data: { faucet: { ... } } })` to claim test tokens
+- Before starting any on-chain workflow, check balance via `wowok({ tool: "query_toolkit", data: { query_type: "account_balance", ... } })`
 - If balance is below 1 WOW, automatically request faucet without asking the user
 - If a transaction fails due to gas, retry after claiming more tokens
 
 ### Tool Reference
 
-- **Claim tokens**: `account_operation` → `faucet` (not `onchain_operations`)
-- **Check balance**: `query_toolkit` → `account_balance`
+- **Claim tokens**: `wowok({ tool: "account_operation", data: { faucet: { ... } } })` (not `onchain_operations`)
+- **Check balance**: `wowok({ tool: "query_toolkit", data: { query_type: "account_balance", ... } })`
 
 Each faucet claim provides approximately 5 WOW, sufficient for dozens of transactions.
 
@@ -118,11 +142,11 @@ Step 3: MODIFY reward { object: "reward_v1", guard_add: [...] } // bind guard
 
 ---
 
-## The 13 Tools
+## The 17 Sub-Tools (all via `wowok({ tool, data })`)
 
 ### 1. `onchain_operations` — 16 Sub-Types
 
-> **Schema**: `schema_query({ name: "onchain_operations" })` for the full discriminated union. Per-type schemas: `onchain_operations_service`, `onchain_operations_machine`, etc.
+> **Schema**: `wowok({ tool: "schema_query", data: { action: "get", name: "onchain_operations" } })` for the full discriminated union. Per-type schemas: `onchain_operations_service`, `onchain_operations_machine`, etc.
 
 | `operation_type` | Schema-Inexpressible Constraints |
 |-----------------|----------------------------------|
@@ -208,16 +232,18 @@ Max 50 contents/entry, 300 chars each.
 ## Decision Tree
 
 ```
-Write state? → onchain_operations (choose operation_type)
+All calls via: wowok({ tool: "<sub-tool>", data: {<params>} })
+
+Write state? → tool: "onchain_operations" (choose operation_type in data)
 ├── No data wrapper? → only gen_passport
 ├── No submission?    → only payment, personal
 └── String (MODIFY) vs Object (CREATE)? → safety §1.1
 
-Read state?  → query_toolkit / onchain_table_data
-Communicate? → messenger_operation (encrypted)
-Local only?  → account_operation / local_mark_operation / local_info_operation
-Export?      → guard2file / machineNode2file
-Discover?    → schema_query / wowok_buildin_info / onchain_events
+Read state?  → tool: "query_toolkit" / "onchain_table_data"
+Communicate? → tool: "messenger_operation" (encrypted)
+Local only?  → tool: "account_operation" / "local_mark_operation" / "local_info_operation"
+Export?      → tool: "guard2file" / "machineNode2file"
+Discover?    → tool: "schema_query" / "wowok_buildin_info" / "onchain_events"
 ```
 
 ---
@@ -266,9 +292,11 @@ When explaining a specific technique to users, reference where it appears:
 
 | Trap | Fix |
 |------|-----|
+| **Calling sub-tool name directly** | MCP only exposes `wowok`. Use `wowok({ tool: "onchain_operations", data: {...} })`, not `onchain_operations({...})` |
+| **Schema validation error** | The response includes `schema.input` — read it, fix params, retry. Cache the schema for future calls to the same sub-tool. |
 | **Transaction fails, gas error** | → [Pre-Flight: Gas & Faucet](#pre-flight-gas--faucet). AI should auto-check balance + faucet. |
 | **Don't know how to build a service** | → [Examples Reference](#examples-reference). Match user intent → example, extract JSON templates. |
-| `gen_passport` called as standalone tool | It's not — use `onchain_operations` with `operation_type: "gen_passport"` |
+| `gen_passport` called as standalone tool | It's not — use `wowok({ tool: "onchain_operations", data: { operation_type: "gen_passport", ... } })` |
 | Missing `data` wrapper | Only `gen_passport` omits it; `payment`/`personal` omit `submission` |
 | String `object` passed expecting CREATE | String = existing (MODIFY), Object = new (CREATE) → [safety §1.1](../wowok-safety/SKILL.md) |
 | Missing `submission` on Guard call | See [Submission Loop](#submission-loop-two-phase) — two-phase pattern: call without `submission` first, collect data, re-call with it |