@wowok/skills 1.3.4 → 2.0.1

package/examples/Travel/Travel.md

@@ -1,6 +1,6 @@
 # Iceland Travel Service Example
 
-A complete example demonstrating how to create an Iceland travel service using WoWok protocol. This service integrates weather-dependent activities, insurance sub-orders, and multi-node workflow management.
+A complete example demonstrating how to create an Iceland travel service using WoWok protocol. This service integrates weather-dependent activities and multi-node workflow management. (Note: "Buy Insurance" is just the name of the first workflow node in this example — there is no real insurance sub-order mechanism.)
 
 ---
 
@@ -320,13 +320,46 @@ Create a Permission object to manage access control for the travel service. Add
 }
 ```
 
-> **Note**: Permission indices 1000-1009 are used for different workflow forwards. Index 306 is a reserved administrative permission. The travel_provider account is granted all these permissions.
+> **Note**: Permission indices 1000-1009 are used for different workflow forwards. Index 306 is the built-in `SERVICE_MACHINE` permission — it governs binding or changing a Service's Machine (`service::machine_set`), and is required in Step 5 when the Service binds `travel_machine`. The travel_provider account is granted all these permissions.
+
+---
+
+## Step 1.5: Create Arbitration Permission
+
+Create a dedicated Permission object for the Arbitration. No special permission indices are needed — the creator (`travel_provider`) automatically becomes the admin of the new Permission.
+
+> **Why a separate Permission?** When a Service binds an Arbitration, the contract asserts `arbitration.permission != service.permission` (error `E_ARBITRATION_PERMISSION_CONFLICT`). If the Arbitration shared the Service's permission, the Service owner would control dispute resolution, breaking fairness. The Arbitration must therefore use an independent Permission object.
+
+**Prompt**: Create a Permission object named "travel_arbitration_permission" for the arbitration.
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "permission",
+    "data": {
+      "object": {
+        "name": "travel_arbitration_permission",
+        "tags": ["travel", "arbitration"],
+        "replaceExistName": true
+      },
+      "description": "Independent permission for travel arbitration (must differ from the Service permission)"
+    },
+    "env": {
+      "account": "travel_provider",
+      "network": "testnet",
+      "no_cache": true,
+      "confirmed": true
+    }
+  }
+}
+```
 
 ---
 
 ## Step 2: Create Arbitration Object
 
-Create an Arbitration object for dispute resolution.
+Create an Arbitration object for dispute resolution. It uses the independent `travel_arbitration_permission` created in Step 1.5.
 
 **Prompt**: Create an Arbitration named "travel_arbitration".
 
@@ -338,7 +371,7 @@ Create an Arbitration object for dispute resolution.
     "data": {
       "object": {
         "name": "travel_arbitration",
-        "permission": "travel_permission",
+        "permission": "travel_arbitration_permission",
         "replaceExistName": true
       },
       "description": "Arbitration for Iceland travel service disputes"
@@ -1063,7 +1096,7 @@ Create a Machine to define the travel service workflow with all nodes and forwar
 | Complete | Ice Scooting | complete_trip | 1002 | travel_complete_guard |
 | Cancel | Ice Scooting | cancel_trip | 1003 | travel_cancel_guard |
 
-> **Note**: The `prev_node` field uses an empty string `""` to denote the entry point. Each node defines how to enter it from a previous node. The `threshold` field (required) specifies the minimum forward weight needed to trigger node advancement.
+> **Note**: The `prev_node` field uses an empty string `""` to denote the entry point. Each node defines how to enter it from a previous node. The `threshold` field (optional, defaults to `0`) specifies the minimum forward weight needed to trigger node advancement.
 
 ---
 
@@ -1114,7 +1147,6 @@ Configure the travel service (created unpublished in Step 2.5) with all bindings
         "allocators": [
           {
             "guard": "merchant_victory_guard",
-            "fix": "0",
             "sharing": [
               {
                 "who": {"Entity": {"name_or_address": "travel_treasury"}},
@@ -1125,7 +1157,6 @@ Configure the travel service (created unpublished in Step 2.5) with all bindings
           },
           {
             "guard": "no_ice_scooting_guard",
-            "fix": "0",
             "sharing": [
               {
                 "who": {"Entity": {"name_or_address": "travel_treasury"}},
@@ -1141,7 +1172,6 @@ Configure the travel service (created unpublished in Step 2.5) with all bindings
           },
           {
             "guard": "no_spa_guard",
-            "fix": "0",
             "sharing": [
               {
                 "who": {"Entity": {"name_or_address": "travel_treasury"}},
@@ -1281,7 +1311,8 @@ Move from initial node ("") to "Buy Insurance" node.
         "operation": {
           "next_node_name": "Buy Insurance",
           "forward": "buy_insurance"
-        }
+        },
+        "op": "next"
       }
     },
     "env": {
@@ -1310,7 +1341,8 @@ Move from "Buy Insurance" to "SPA" node.
         "operation": {
           "next_node_name": "SPA",
           "forward": "go_spa"
-        }
+        },
+        "op": "next"
       }
     },
     "env": {
@@ -1339,7 +1371,8 @@ Move from "SPA" to "Ice Scooting" node. This forward has a Guard (`weather_check
         "operation": {
           "next_node_name": "Ice Scooting",
           "forward": "go_ice_scooting"
-        }
+        },
+        "op": "next"
       }
     },
     "submission": {
@@ -1395,7 +1428,8 @@ Move from "Ice Scooting" to "Complete" node. This forward has a Guard (`travel_c
         "operation": {
           "next_node_name": "Complete",
           "forward": "complete_trip"
-        }
+        },
+        "op": "next"
       }
     },
     "submission": {
@@ -1430,7 +1464,7 @@ Move from "Ice Scooting" to "Complete" node. This forward has a Guard (`travel_c
 }
 ```
 
-> **Note**: Replace `<ORDER_OBJECT_ID>` with the actual Order object ID (e.g., `0x7cc9f2228e130c2f6b585bb9c4666fd4d03252d38048355678f46e31b682eb38`). You can query the Progress object to find the `task` field which contains the Order ID.
+> **Note**: Replace `<ORDER_OBJECT_ID>` with the actual Order object ID (a 64-hex-character string starting with `0x`). You can query the Progress object to find the `task` field which contains the Order ID.
 >
 > **Key**: The `submission` field is at the **top level** of the input (alongside `data` and `env`), NOT inside `data`. The `impack: true` means the Guard verification result affects the final outcome.
 
@@ -1451,7 +1485,8 @@ Move from "Ice Scooting" to "Complete" node. This forward has a Guard (`travel_c
         "operation": {
           "next_node_name": "Cancel",
           "forward": "cancel_trip"
-        }
+        },
+        "op": "next"
       }
     },
     "submission": {
@@ -1487,6 +1522,7 @@ Move from "Ice Scooting" to "Complete" node. This forward has a Guard (`travel_c
 | `data.object` | string | Progress object name/ID |
 | `data.operate.operation.next_node_name` | string | Target node name to move to |
 | `data.operate.operation.forward` | string | Forward name defined in Machine |
+| `data.operate.op` | string | **Required.** Operation type: `"next"` (advance the forward), `"hold"`, `"unhold"`, or `"adminUnhold"` |
 | `submission` | object | Guard verification data (top-level, required when forward has Guard) |
 | `env.no_cache` | boolean | Set to `true` to avoid stale cache issues |
 
@@ -1524,7 +1560,7 @@ The allocation Guard requires the Order ID as a submission (identifier: 0). Quer
 
 ### 8.2 Execute Allocation (Merchant Victory Path)
 
-When the Progress is "Complete", the `merchant_victory_guard` passes, and 100% of funds go to the Service object.
+When the Progress is "Complete", the `merchant_victory_guard` passes, and 100% of funds go to the Treasury (`travel_treasury`).
 
 **Prompt**: Execute fund allocation with the merchant_victory_guard, submitting the Order ID.
 
@@ -1577,7 +1613,7 @@ When the Progress is "Complete", the `merchant_victory_guard` passes, and 100% o
 
 For refund scenarios (Cancel or SPA), use the corresponding Guard. The same submission structure applies — the Order ID is submitted to identifier 0.
 
-**Cancel/Ice Scooting path** (80% Service, 20% Order):
+**Cancel/Ice Scooting path** (80% Treasury, 20% Order (escrow, claimable by the order owner)):
 
 ```json
 {
@@ -1601,7 +1637,7 @@ For refund scenarios (Cancel or SPA), use the corresponding Guard. The same subm
 }
 ```
 
-**SPA path** (5% Service, 95% Order):
+**SPA path** (5% Treasury, 95% Order (escrow, claimable by the order owner)):
 
 ```json
 {
@@ -1660,6 +1696,57 @@ After allocation, query the Allocation and Payment objects to verify the fund di
 
 > **Important**: `alloc_by_guard` accepts Guard names (e.g., `"merchant_victory_guard"`) or Guard object IDs. The Guard must exist in the Allocation's `allocators` list. Only the first Guard that passes (first-Guard-wins) triggers fund distribution.
 
+### 8.5 Claim Allocated Funds (Unwrap CoinWrapper)
+
+Allocation does not deposit spendable coins directly. `alloc_by_guard` distributes **CoinWrapper objects** to each recipient address — these must be claimed/unwrapped before the funds are spendable:
+
+- **Treasury share** (`Entity` → `travel_treasury`): the CoinWrapper is sent to the Treasury object address. The travel provider deposits it into the Treasury balance via the Treasury `receive` operation.
+- **Customer share** (`GuardIdentifier: 0` → the Order object address submitted at runtime, i.e. escrow): the CoinWrapper is sent to the Order object address. The order owner (Alice) claims it via the Order `receive` operation, which unwraps it and transfers the coins to her wallet.
+
+**Prompt**: Alice claims the customer share escrowed to the Order (refund paths only).
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "order",
+    "data": {
+      "object": "alice_travel_order",
+      "receive": "recently"
+    },
+    "env": {
+      "account": "alice",
+      "network": "testnet",
+      "no_cache": true,
+      "confirmed": true
+    }
+  }
+}
+```
+
+**Prompt**: The travel provider deposits the Treasury's share into the Treasury balance.
+
+```json
+{
+  "tool": "onchain_operations",
+  "data": {
+    "operation_type": "treasury",
+    "data": {
+      "object": "travel_treasury",
+      "receive": "recently"
+    },
+    "env": {
+      "account": "travel_provider",
+      "network": "testnet",
+      "no_cache": true,
+      "confirmed": true
+    }
+  }
+}
+```
+
+> **Note**: `"receive": "recently"` auto-queries and claims all recently received CoinWrapper objects. For the Order, `receive` unwraps them and transfers the coins to the order owner (Alice); for the Treasury, `receive` deposits the unwrapped coins into the Treasury's balance. In the merchant-victory path (100% to Treasury) only the Treasury claim is needed; the Order claim applies only to refund paths (8.3) where the customer has a share.
+
 ---
 
 ## Best Practices

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wowok/skills",
-  "version": "1.3.4",
-  "description": "WoWok AI Skills for Claude and other AI assistants - Helping AI use WoWok MCP tools correctly",
+  "version": "2.0.1",
+  "description": "WoWok AI Skills for Claude and other AI assistants - Dialogue orchestration layer on top of the WoWok MCP server (rules/reference knowledge is served by MCP directly since v2.0.0)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -11,15 +11,11 @@
     "dist/",
     "wowok-provider/",
     "wowok-arbitrator/",
-    "wowok-guard/",
-    "wowok-tools/",
-    "wowok-safety/",
     "wowok-machine/",
     "wowok-order/",
     "wowok-messenger/",
     "wowok-output/",
     "wowok-onboard/",
-    "wowok-scenario/",
     "wowok-planner/",
     "wowok-auditor/",
     "examples/",

package/scripts/install.js

@@ -16,22 +16,47 @@ const path = require('path');
 const os = require('os');
 const { execSync } = require('child_process');
 
+/**
+ * Retained skills (post GLM5-31 sink refactor) — only these are installed.
+ * The 4 rule-reference skills (wowok-safety/tools/scenario/guard) were sunk
+ * into the MCP knowledge layer and are served by the MCP server directly:
+ *   - wowok-safety   → schema_query action='get_safety_rules'
+ *   - wowok-tools    → schema_query action='get_tool_reference'
+ *   - wowok-scenario → project_operation recommend_industry / create_project
+ *   - wowok-guard    → schema_query action='get_guard_design_patterns'
+ */
 const SKILL_DIRS = [
   'wowok-provider',
   'wowok-arbitrator',
   'wowok-order',
   'wowok-messenger',
-  'wowok-guard',
   'wowok-machine',
   'wowok-output',
-  'wowok-tools',
-  'wowok-safety',
   'wowok-onboard',
-  'wowok-scenario',
   'wowok-planner',
   'wowok-auditor',
 ];
 
+/**
+ * Deprecated skills removed in the GLM5-31 sink refactor. They are NEVER
+ * installed, but preuninstall/init still clean them up from legacy installs
+ * and warn the user where the content now lives.
+ */
+const LEGACY_SKILL_DIRS = [
+  'wowok-guard',
+  'wowok-tools',
+  'wowok-safety',
+  'wowok-scenario',
+];
+
+/** Where each deprecated skill's content now lives (migration message). */
+const SKILL_MIGRATION_MAP = {
+  'wowok-safety': "MCP schema_query action='get_safety_rules'",
+  'wowok-tools': "MCP schema_query action='get_tool_reference'",
+  'wowok-scenario': "MCP project_operation action='recommend_industry' / 'create_project'",
+  'wowok-guard': "MCP schema_query action='get_guard_design_patterns'",
+};
+
 const CLIENT_DIRS = {
   claude: path.join(os.homedir(), '.claude', 'skills'),
   cursor: path.join(os.homedir(), '.cursor', 'rules'),
@@ -172,7 +197,9 @@ function installSkills(targetDir, target) {
 function uninstallSkills(targetDir) {
   let count = 0;
 
-  for (const dir of SKILL_DIRS) {
+  // Remove both retained and legacy (deprecated) skills — legacy dirs may
+  // still exist from pre-refactor installs and must be cleaned up.
+  for (const dir of [...SKILL_DIRS, ...LEGACY_SKILL_DIRS]) {
     const dirPath = path.join(targetDir, dir);
     if (fs.existsSync(dirPath)) {
       removeDir(dirPath);
@@ -184,6 +211,23 @@ function uninstallSkills(targetDir) {
   return count;
 }
 
+/**
+ * Detect deprecated skills still present in a target dir and print a
+ * migration hint (GLM5-31 §3.2). Returns the list of legacy dirs found.
+ */
+function warnLegacySkills(targetDir) {
+  const found = LEGACY_SKILL_DIRS.filter((dir) => fs.existsSync(path.join(targetDir, dir)));
+  if (found.length > 0) {
+    console.warn(`[wowok-skills] ⚠ MIGRATION: deprecated skills detected in ${targetDir}:`);
+    for (const dir of found) {
+      console.warn(`[wowok-skills]   - ${dir} → content now served by ${SKILL_MIGRATION_MAP[dir]}`);
+    }
+    console.warn('[wowok-skills]   These skills are stale (MCP knowledge layer is the source of truth).');
+    console.warn('[wowok-skills]   Remove them with: wowok-skills uninit  (or delete the folders above)');
+  }
+  return found;
+}
+
 function getTargets() {
   const envTargets = process.env.WOWOK_SKILLS_TARGETS;
   if (!envTargets) {
@@ -206,6 +250,8 @@ function main() {
       console.log(`[wowok-skills] → ${dir}`);
       const count = installSkills(dir, target);
       total += count;
+      // GLM5-31 §3.2: warn about stale pre-refactor skills still present.
+      warnLegacySkills(dir);
     }
 
     console.log(`[wowok-skills] Done — ${total} skills installed across ${targets.length} client(s).`);
@@ -256,7 +302,7 @@ function main() {
 
 function countExisting(targetDir) {
   let count = 0;
-  for (const dir of SKILL_DIRS) {
+  for (const dir of [...SKILL_DIRS, ...LEGACY_SKILL_DIRS]) {
     if (fs.existsSync(path.join(targetDir, dir))) {
       count++;
     }

package/wowok-arbitrator/SKILL.md

@@ -30,7 +30,7 @@ The following content has been pushed down to the MCP knowledge layer and is app
 |---------|---------------------|-------------|
 | Guard design rules (structural layers, data source classification, voting_guard table design) | `knowledge/guard-design-patterns.ts` (`GUARD_DESIGN_PATTERNS`) | `project_operation.evaluate_project` (via `assessGuardRisks`) |
 | Safety rules (confirmation levels, immutability, object reuse) | `knowledge/safety-rules.ts` (`CONFIRMATION_RULES`) | Pre-publish checks + `project_operation.evaluate_project` |
-| Arbitration-specific risks | `knowledge/arb-risk.ts` (`assessArbitrationRisks`) | `project_operation.evaluate_project` |
+| Arbitration-specific risks | `knowledge/arbitration-risk.ts` (`assessArbitrationRisks`) | `project_operation.evaluate_project` |
 
 This Skill keeps the arbitration **conversation flow**, **evidence collection** scripts, and **dispute resolution** guidance — the MCP layer handles the rule evaluation.
 

package/wowok-auditor/SKILL.md

@@ -53,7 +53,7 @@ This Skill keeps the **audit flow**, the **4 audit dimensions** (Guard completen
 3. **FAIL blocks, WARN asks**: A FAIL verdict blocks R10 publish until fixed. A WARN verdict proceeds after explicit user acknowledgement. PASS is silent.
 4. **Blast-radius first**: Before reporting, classify each issue by irreversibility — a Guard logic bug post-publish is permanent; an untested Guard is recoverable.
 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.
-6. **Tiered**: A Tier-1 audit (single Service + single Guard) skips R4 Machine soundness if no Machine is bound. Tier-3 runs every rule including cross-Machine dependency chains.
+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.
 
 ---
 

package/wowok-machine/SKILL.md

@@ -234,7 +234,7 @@ All stem from the same root: **every on-chain object has a publish/create freeze
 | `refunded` (terminal) | `refund_routing` (routing) → Allocator fires |
 | N/A (dispute) | `arbiter_rule` (routing) → Arbitration off-Machine (no Allocator) |
 
-See [wowok-scenario](../wowok-scenario/SKILL.md) "Rental Mode Template (R-M1-11 Compliant)" for a complete 10-node rental topology.
+A complete R-M1-11-compliant rental topology is auto-generated by `project_operation.create_project` with `project_industry='rental'` (MCP `knowledge/scenario-modes.ts`).
 
 ### Pre-Publish Validation Checklist
 
@@ -245,7 +245,7 @@ Before `publish: true`, verify:
 - [ ] **Every node has outgoing Forwards** (except terminals): no dead-end nodes
 - [ ] **Every node has incoming Pair** (except entry): no orphaned nodes
 - [ ] **All thresholds independently achievable**: no dead branches (competing Pair always wins first)
-- [ ] **⚠ R-M1-11 Compliance** (CRITICAL for deposit/refund scenarios): NO terminal nodes named `deposit_refunded`, `deposit_deducted`, `refunded`, or any name implying Machine-internal refund/deduction. Refund/deduction MUST flow through an **Allocator** triggered by a routing node (e.g., `return_approved`, `damage_confirmed`, `arbiter_rule`). Violating this causes funds to lock in the Machine with no Allocator path. See [wowok-scenario](../wowok-scenario/SKILL.md) "Rental Mode Template (R-M1-11 Compliant)".
+- [ ] **⚠ R-M1-11 Compliance** (CRITICAL for deposit/refund scenarios): NO terminal nodes named `deposit_refunded`, `deposit_deducted`, `refunded`, or any name implying Machine-internal refund/deduction. Refund/deduction MUST flow through an **Allocator** triggered by a routing node (e.g., `return_approved`, `damage_confirmed`, `arbiter_rule`). Violating this causes funds to lock in the Machine with no Allocator path. Auto-enforced by MCP pre-publish checks and `project_operation.evaluate_project`.
 - [ ] All Guards exist on-chain and tested (use `gen_passport`)
 - [ ] `namedOperator` vs `permissionIndex` correct per Forward
 - [ ] Every Forward has at least one of `namedOperator` or `permissionIndex`

package/wowok-messenger/SKILL.md

@@ -25,8 +25,9 @@ always: false
 End-to-end encrypted messaging with tamper-proof audit trails.
 
 > **Role**: Any WoWok participant
-> All 16 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.
-> **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)
+> 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.
+> **Related Skills**: [wowok-arbitrator](../wowok-arbitrator/SKILL.md) (WTS evidence in disputes), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-provider](../wowok-provider/SKILL.md) (service provider perspective)
+> Guard design patterns and safety rules now live in the MCP knowledge layer — query via `schema_query` actions `get_guard_design_patterns` / `get_safety_rules`.
 
 ---
 
@@ -71,7 +72,7 @@ The on-chain **Contact** object (`operation_type: "contact"`) is the bridge betw
 
 **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.
 
-**Lifecycle**: Contact is mutable (unlike Proof/Guard). `im_add`/`im_remove` require permission index 453 (CONTACT_IM). No events emitted on IM mutations — poll `ims[]` field. If Contact is bound to `Permission.um` via `permission_um_set`, clear that binding BEFORE deleting the Contact (else dangling pointer). Full business guidance: [wowok-tools](../wowok-tools/SKILL.md) §"Contact (Service.um Bridge)".
+**Lifecycle**: Contact is mutable (unlike Proof/Guard). `im_add`/`im_remove` require permission index 453 (CONTACT_IM). No events emitted on IM mutations — poll `ims[]` field. If Contact is bound to `Permission.um` via `permission_um_set`, clear that binding BEFORE deleting the Contact (else dangling pointer). Full field constraints: MCP `schema_query` action='get' name='contact'.
 
 ---
 
@@ -85,6 +86,7 @@ Two approaches, depending on need:
 
 - **Quick glance** — `watch_conversations` with `unreadOnly: true` lists all conversations with unread messages, sorted by activity. Each conversation shows a preview of the last messages.
 - **Deep dive** — `watch_messages` with a specific `peerAddress` to view the full conversation with a particular counterparty. Supports keyword search, time-range filtering, direction filter, and status filter.
+- **Server sync** — `pull_messages` fetches the latest messages from the server into local storage (optional `limit` caps batch size). Use this first when the local view looks stale (e.g. after downtime or on a new device session), then read via `watch_conversations` / `watch_messages`.
 
 **Design note**: By default, retrieving messages auto-marks them as viewed (`viewedAt` timestamp). Set `skipAutoMarkViewed: true` if you want to peek without marking read.
 

package/wowok-onboard/SKILL.md

@@ -50,7 +50,7 @@ The onboarding skill dismantles the "16 operation_type × 14 object_type" wall.
 
 - Converts "I want to open a shop" into a 10-round guided build plan
 - Industry defaults auto-applied via `project_operation.create_project` (pass `project_industry` parameter; defaults sourced from MCP `knowledge/scenario-modes.ts`)
-- Enforces dependency order: Permission → Service → Machine → Progress → Guard → Allocation → Order → Publish
+- Enforces dependency order: Permission → Machine (create) → Guards → Machine (bind guards+publish) → Service Phase 1 (configure) → Service Phase 2 (publish) → Test Order → Mainnet
 - Persists checkpoints after each round via `local_info_operation` so users can resume
 - Hands off to [wowok-provider](../wowok-provider/SKILL.md) once the Service is published
 
@@ -63,7 +63,7 @@ The onboarding skill dismantles the "16 operation_type × 14 object_type" wall.
 
 ### Output Contract
 
-A published Service with: published Machine, bound Progress, validated Guards, configured order_allocators, and one successful test order digest. Handoff packet includes all object IDs and the post-publish verification report.
+A published Service with: published Machine, published Service, validated Guards, configured order_allocators, and one successful test order digest (order → progress advance → allocation). Handoff packet includes all object IDs and the post-publish verification report.
 
 ---
 
@@ -74,24 +74,43 @@ The onboarding flow is backed by the MCP SQLite-based project pipeline. Each ste
 | Step | Rounds | MCP Action | Gate |
 |------|--------|------------|------|
 | 1. Create Project | R1-R2 | `create_project` (pass `project_industry`) → project record + scenario defaults | — |
-| 2. Add Objects | R3-R8 | `add_object` for each on-chain object (Service, Machine, Guards, Allocators) | — |
-| 3. Build Graph | After R8 | `build_graph` → object dependency graph from added objects | — |
+| 2. Add Objects | R2-R7 | `add_object` for each on-chain object (Permission, Machine, Guards, Service) | — |
+| 3. Build Graph | After R7 | `build_graph` → object dependency graph from added objects | — |
 | 4. Evaluate | After graph built | `evaluate_project` (evaluation_type='risk') → risk assessment | CRITICAL risks block R9 |
 
-## R1-R10 Build Order
-
-| Round | Object | MCP Operation | Key Decision |
-|-------|--------|---------------|--------------|
-| R1 | Account | `account_operation.gen` + `faucet` | New or reuse? |
-| R2 | Industry mode | `project_operation.create_project` (pass `project_industry`) | Which driving mode? |
-| R3 | Service | `onchain_operations.service` CREATE | Name, type_parameter, description |
-| R4 | Permission | `onchain_operations.permission` CREATE/REUSE | Index 1000 = provider/merchant (customer uses `namedOperator:""` = OrderHolder; arbiter is NOT a Permission index — arbiters live in `Arbitration.voting_guard`) |
-| R5 | Machine | `onchain_operations.machine` CREATE | Nodes, forwards (mode defaults from MCP) |
-| R6 | Progress | `onchain_operations.progress` CREATE + bind | Mirror Machine nodes |
-| R7 | Guards | `onchain_operations.guard` CREATE + `gen_passport` test | 5 Guard templates (mode defaults from MCP) |
-| R8 | Allocation | `onchain_operations.allocation` CREATE + `service.order_allocators` | Fund split (mode defaults from MCP) |
-| R9 | Test order | `onchain_operations.order` CREATE + `progress` advance + `allocation.alloc_by_guard` | Full flow dry run |
-| R10 | Publish | `onchain_operations.machine` publish + `service` publish | Pre-publish audit must PASS |
+> **Async mode**: `build_graph` / `evaluate_project` accept `async_mode: true` for large projects — the call returns immediately with a `task_id`. Poll `query_task_status` with that `task_id` until `status: "completed"` before reading results / proceeding to the next step. Default is synchronous (`async_mode` omitted) — fine for the ≤10-object onboarding scale.
+
+## R1-R10 Build Order (MCP-Validated)
+
+**Core principles (from MCP schema):**
+- `service.machine` must reference a **published** Machine (Service cannot bind unpublished Machine)
+- `service.order_allocators` is L1-locked — MUST be set BEFORE `service.publish` (per service.move:503)
+- Guard uses **LocalMark NAME** in table to break circular dependency (Guard→Service→Guard)
+- `order_new` (test order) only works when `service.bPublished=true` (else E_NOT_PUBLISHED)
+- **Recommended order**: Permission → Machine (create nodes/forwards) → Guards → Machine (bind guards to forwards) → Machine (publish) → Service Phase 1 (configure) → Service Phase 2 (publish) → Test Order
+
+| Round | Phase | Object | MCP Operation | Key Decision |
+|-------|-------|--------|---------------|--------------|
+| R1 | Foundation | Project + Account | `project_operation.create_project` (pass `project_industry`) + `account_operation.gen` + `faucet` | Industry mode + new/reuse account |
+| R2 | Foundation | Permission | `onchain_operations.permission` CREATE/REUSE | Index 1000 = provider |
+| R3 | Foundation | Machine | `onchain_operations.machine` CREATE (nodes/forwards, guards optional inline) | Nodes, forwards, optional inline guards |
+| R4 | Foundation | Guards | `onchain_operations.guard` CREATE (multiple) | Buy guard, accept guard, refund guard — use LocalMark NAME for Service references |
+| R5 | Foundation | Machine guard binding | `onchain_operations.machine` MODIFY (bind guards to forwards) | `op: "add forward"` or `op: "set"` to update forward guard fields; Machine must still be unpublished |
+| R6 | Foundation | Machine publish | `onchain_operations.machine` publish | Machine must be published before Service can reference it |
+| R7 | Revenue | Service Phase 1 | `onchain_operations.service` CREATE (no publish) + set `machine` + `order_allocators` + `buy_guard` + `sales` + `arbitrations` (if compensation) | All L1-locked fields (machine, order_allocators) MUST be set here |
+| R8 | Audit | Pre-publish audit | `machineNode2file` export + `guard2file` export + `project_operation.evaluate_project` | All CRITICAL risks must be fixed before R9 |
+| R9 | Publish | Service Phase 2 | `onchain_operations.service` publish=true | Only flips publish flag; L1 fields already locked |
+| R10 | Test + Mainnet | Test order + Mainnet | `onchain_operations.service` `order_new` → `onchain_operations.progress` advance → `onchain_operations.allocation` `alloc_by_guard` → Re-run R2-R9 on mainnet | Full flow dry run: order → progress → allocation; Recommend testnet first, then mainnet |
+
+**Guard binding to Machine forwards**: Two approaches:
+1. **Inline (R3)**: Set guards directly in `MachineForwardSchema.guard` during Machine CREATE — guards must already exist
+2. **Deferred (R5)**: Create Machine first without guards (R3), create Guards (R4), then bind guards to forwards via `op: "add forward"` or `op: "set"` — allows Guards to reference Machine by LocalMark name
+
+Use approach 2 when Guards need to reference the Machine (e.g., verify current node or forward name). Use approach 1 for simple Guards that don't reference the Machine.
+
+**Circular dependency handling**: Guard that references Service → create Guard first with LocalMark NAME in table (not address), then reference Guard by name in Service Phase 1. LocalMark name is resolved to address at transaction build time.
+
+**R-M1-11 compliance** (rental/refund scenarios): Machine MUST use routing nodes (`return_approved`, `damage_confirmed`, `arbiter_rule`), NOT terminal nodes (`deposit_refunded`, `refunded`). Refund is handled by Allocator, not Machine terminal nodes.
 
 ---
 
@@ -104,13 +123,13 @@ When the user describes their business (R2), match to one of the supported indus
 | `general` | `general` | Free-form / hybrid — no presets, full manual control |
 | `retail` | `general` (retail profile) | Physical goods sales with stock + WIP product listings |
 | `service` | `general` (service profile) | Intangible services (consulting, design) — milestone delivery |
-| `rental` | `rental` | Equipment / vehicle / property rental with deposit escrow + return inspection (R-M1-11 compliant — uses `return_approved`/`damage_confirmed`/`arbiter_rule` routing nodes, NO `deposit_refunded`/`deposit_deducted`/`refunded` terminal nodes; see [wowok-scenario](../wowok-scenario/SKILL.md) "Rental Mode Template") |
+| `rental` | `rental` | Equipment / vehicle / property rental with deposit escrow + return inspection (R-M1-11 compliant — uses `return_approved`/`damage_confirmed`/`arbiter_rule` routing nodes, NO `deposit_refunded`/`deposit_deducted`/`refunded` terminal nodes; topology auto-applied by `project_operation.create_project` with `project_industry='rental'` from MCP `knowledge/scenario-modes.ts`) |
 | `freelance` | `freelance` | Design / dev / consulting — milestone allocation + acceptance gate |
 | `education` | `education` | Courses / training / tutoring — periodic release per session attendance |
 | `travel` | `travel` | Custom tours / multi-segment trips — multi-tier allocation per segment |
 | `subscription` | `subscription` | SaaS / content membership / periodic service — periodic charge + cancel guard |
 
-> If unsure which fits, default to `general`. Users can switch modes mid-onboarding (see wowok-scenario "Escape Hatch"). For mode composition (e.g., freelance + subscription retainer), see [wowok-scenario](../wowok-scenario/SKILL.md).
+> If unsure which fits, call `project_operation` action='recommend_industry' with the user's business description — it returns top-3 industry matches with reference examples. To iterate a mode mid-onboarding, use action='derive_user_mode' / 'evolve_user_mode' (user mode registry in MCP).
 
 ---
 
@@ -127,7 +146,7 @@ Before declaring onboarding complete, verify ALL items. Each is a hard gate —
 | 4 | Allocators configured | Each Allocator `sharing[].sharing` Rate entries sum to **10000** (Rate mode); or `Amount` mode values set. For rental/refund scenarios, verify Allocators' `trigger_node` references the routing nodes (e.g., `return_approved`) — NOT missing (else R-M1-11 refund path is broken) |
 | 5 | Service created with all bindings | `query_toolkit` (onchain_objects, type=service) → machine, order_allocators, buy_guard all non-empty |
 | 6 | Service published | `query_toolkit` (onchain_objects, type=service) → `bPublished: true` |
-| 7 | Test order placed | R9 test order created + Progress advanced + Allocator triggered successfully |
+| 7 | Test order placed | R9 test order created via `service.order_new` + Progress advanced + Allocator triggered successfully |
 
 > If any item fails, do NOT proceed to handoff. Fix the underlying issue, then re-verify. Use `project_operation.evaluate_project` (risk) to auto-detect missing bindings.
 
@@ -138,9 +157,9 @@ Before declaring onboarding complete, verify ALL items. Each is a hard gate —
 | Error | Cause | Fix |
 |-------|-------|-----|
 | `dynamicFieldNotFound` | SDK cannot resolve a dynamic field reference | Set `env.account` (account not configured) — pass account in the tool call wrapper |
-| `Circular dependency` (Guard ↔ Service creation) | Guard needs Service address; Service needs Guard address | Use **LocalMark NAME** (not address) in Guard query table — see [wowok-guard](../wowok-guard/SKILL.md) "Circular Dependency Handling" |
+| `Circular dependency` (Guard ↔ Service creation) | Guard needs Service address; Service needs Guard address | Use **LocalMark NAME** (not address) in Guard query table — pattern documented in MCP `schema_query` action='get_guard_design_patterns' |
 | `order.balance invalid` | Used wrong field for order amount | Use `order.amount` (not `order.balance` — `balance` is residual escrow, `amount` is original payment) |
 | Allocator `rate sum != 10000` | Rate-mode Allocator sharing percentages don't sum to 100% | Ensure all `sharing[].sharing` values in Rate mode sum to exactly **10000** basis points (e.g., 80% = 8000) |
-| `IMPACK_GUARD_NOT_FOUND` (gen_passport) | Repository query with `quote_guard = Some(addr)` | `impack_list` is empty during verify phase — only `quote_guard = None` passes; see [wowok-guard](../wowok-guard/SKILL.md) |
+| `IMPACK_GUARD_NOT_FOUND` (gen_passport) | Repository query with `quote_guard = Some(addr)` | `impack_list` is empty during verify phase — only `quote_guard = None` passes; see MCP `schema_query` action='get_guard_design_patterns' |
 | `Permission denied` (Progress advance, abort code 5) | Wrong operation path for forward's `namedOperator` | Empty `namedOperator` → use `order.progress`; non-empty → use `progress.operate`; `permissionIndex` → use `progress.operate` |
-| Allocator never fires (refund stuck) — R-M1-11 violation | Machine has a node like `deposit_refunded` instead of routing node `return_approved`; or Allocator's `trigger_node` is missing/mispelled | Rename node to `return_approved` / `damage_confirmed`; bind Allocator to that node; see [wowok-scenario](../wowok-scenario/SKILL.md) "Rental Mode Template (R-M1-11 Compliant)" |
+| Allocator never fires (refund stuck) — R-M1-11 violation | Machine has a node like `deposit_refunded` instead of routing node `return_approved`; or Allocator's `trigger_node` is missing/mispelled | Rename node to `return_approved` / `damage_confirmed`; bind Allocator to that node; R-M1-11 is auto-enforced by MCP pre-publish checks and `project_operation.evaluate_project` |