@wowok/skills 1.1.2 → 1.1.4

package/wowok-machine/SKILL.md

@@ -1,447 +1,286 @@
 ---
 name: wowok-machine
 description: |
-  WoWok Machine workflow design — defines multi-step workflows (state machines)
-  for order processing. Machines control how orders progress through stages,
-  who can advance them, and what conditions must be met at each step.
-  
-  Use this skill when designing or modifying Machine workflows, creating
-  Progress tracking, or troubleshooting workflow advancement issues.
+  WoWok Machine Workflow Design — the canonical skill for designing, building,
+  and operating automated workflow templates (Machines) on WoWok. Machines are
+  directed graphs that define how orders progress through stages, who can
+  advance them, and what conditions must be met at each step.
+
+  Covers Machine architecture (Nodes, Pairs, Forwards, Guards, Thresholds),
+  lifecycle management (create, configure, publish, pause), node operations
+  (add, exchange, rename, granular forward/prior-node manipulation),
+  Progress integration, cross-service sub-order creation, privacy-preserving
+  consensus patterns, and export/import workflows via machineNode2file.
 when_to_use:
   - User wants to create or modify a Machine workflow
   - User asks about workflow steps, state transitions, or progress
   - User needs to design order processing pipelines
   - User mentions "machine", "workflow", "progress", "state machine", "pipeline"
+  - User wants to export Machine nodes to a file or import from a file
+  - User needs to understand threshold mechanics, forward permissions, or guard bindings
 ---
 
 # WoWok Machine Workflow Design
 
-## What is a Machine?
+Design, build, and operate automated workflow templates.
 
-A Machine is a **workflow template** that defines how orders progress through stages. It's a directed graph where:
-- **Nodes** = stages/states in the workflow
-- **Forwards** = allowed transitions between nodes
-- **Guards** = conditions that must be met to advance
-- **Pairs** = data fields tracked at each node
+> **Role**: Service Provider or Workflow Designer  
+> **Key Tools**: `onchain_operations` with `operation_type: "machine"`  
+> **Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) (Guards), [wowok-provider](../wowok-provider/SKILL.md) (Service binding), [wowok-order](../wowok-order/SKILL.md) (customer perspective), [wowok-tools](../wowok-tools/SKILL.md) (schema reference)
 
-## Machine Structure
-
-**Operation**: `onchain_operations` with `operation_type: "machine"`.
-
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_machine" })`
-
-**Key Fields**:
-- `object`: Machine object name (CREATE) or ID (MODIFY)
-- `service`: Which Service this Machine belongs to
-- `guard`: Guard for workflow validation
-- `node`: Node configuration with:
-  - `op`: Operation type ("set", "add", "remove")
-  - `nodes`: Array of node definitions
-  - `bReplace`: Replace existing nodes flag
-
-### Node Structure
-
-Each node contains:
-- `name`: Unique node identifier
-- `pairs`: Data fields at this node (array of pair definitions)
-- `forwards`: Allowed next nodes (array of forward definitions)
-- `guard`: Guard for entering this node
-- `threshold`: Required signers to advance
+---
 
-## Machine Node Design Rules
+## Core Concepts
 
-### Rule 1: Every Node Needs a Unique Name
-Node names are identifiers. Use descriptive names like "pending", "in_progress", "review", "completed".
+### What is a Machine?
 
-### Rule 2: Forwards Define the Graph
-Each node's `forwards` array defines which nodes can be reached next. A node without forwards is a terminal/end state.
+A Machine is a **workflow template** — a directed graph that defines how orders progress from creation to completion. Machines can be bound to Services (one-to-many) or operate standalone for collaborative workflows. When bound to a Service, the Machine is instantiated as a **Progress** object when an order is created. The Machine defines the rules; the Progress tracks the live execution.
 
-### Rule 3: Guards Control Transitions
-Each forward can have a `guard` that must pass before the transition is allowed. This enables conditional workflows.
+**Key Analogy**: Machine = workflow blueprint, Progress = live workflow instance.
 
-### Rule 4: Pairs Define Node Data
-Each node's `pairs` define what data is tracked at that stage. Different nodes can track different data.
+### Immutability Rules
 
-### Rule 5: Threshold Controls Multi-Sig
-The `threshold` field defines how many signers must approve to advance from this node. Use for multi-party approval workflows.
+| Object | When Immutable | Impact |
+|--------|---------------|--------|
+| **Machine** | After `publish: true` | All nodes are locked; workflow topology frozen |
+| **Guard** | After creation | CREATE-only, cannot modify |
 
-## Common Workflow Patterns
+Because published Machines are immutable, you must design the complete workflow before publishing. However, before publishing, nodes can be freely added, removed, renamed, and reorganized.
 
-### Pattern 1: Linear Pipeline
-```
-Start → Step1 → Step2 → Step3 → Done
-```
-Simple sequential workflow. Each node forwards to exactly one next node.
+---
 
-**Node Configuration**:
-- Node "pending": forwards to "in_progress"
-- Node "in_progress": forwards to "review"
-- Node "review": forwards to "completed"
-- Node "completed": no forwards (terminal)
+## Machine Architecture
 
-### Pattern 2: Branching Workflow
-```
-           → Approved → Completed
-Start → Review
-           → Rejected → Revision → Review
-```
-Conditional branching based on Guard validation.
-
-**Node Configuration**:
-- Node "review": two forwards with different guards
-  - Forward to "approved" with approval guard
-  - Forward to "rejected" with rejection guard
-- Node "approved": forward to "completed"
-- Node "rejected": forward to "revision"
-- Node "revision": forward back to "review"
-- Node "completed": terminal
-
-### Pattern 3: Multi-Party Approval
-```
-Start → Review (threshold: 3) → Completed
-```
-Requires multiple signers to advance.
+### The Building Blocks
 
-**Node Configuration**:
-- Node "review": threshold = 3, forward to "completed"
+A Machine is composed of three structural layers:
 
-### Pattern 4: Parallel Tracks
 ```
-        → Track A → Merge
-Start →
-        → Track B → Merge → Done
+Machine
+└── Nodes (up to 200)
+    └── Pairs (up to 40 per node)
+        ├── prev_node: which prior node this pair connects from
+        ├── threshold: required total forward weight to advance
+        └── Forwards (up to 20 per pair)
+            ├── name: operation identifier
+            ├── weight: contribution toward threshold
+            ├── permissionIndex | namedOperator: who can execute
+            └── guard (optional): condition that must pass
 ```
-Multiple parallel work streams that converge.
-
-## Progress Operations
 
-Progress tracks an order's movement through a Machine's workflow.
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_machine" })`
 
-### Advance Progress
+### Node
 
-**Operation**: `onchain_operations` with `operation_type: "progress"`.
+A Node represents a **stage or state** in the workflow. Each node has a unique name and contains one or more Pairs defining how to reach it and what Forwards are available from it.
 
-**Key Fields**:
-- `op`: Operation type ("advance", "create", etc.)
-- `order`: Order ID to advance
-- `node`: Target node name
-- `pairs`: Node data to submit
+Node names must be unique within a Machine. The empty string (`""`) represents the initial state — any Pair with `prev_node: ""` is an entry point. A Machine can have multiple entry nodes, each with its own threshold configuration.
 
-### Query Progress History
+### Pair (NodePair)
 
-**Tool**: `onchain_table_data` with `query_type: "onchain_table_item_progress_history"`.
+A Pair connects a previous node to the current node, defining:
+- **`prev_node`**: Source node name (`""` for entry point)
+- **`threshold`**: Total weight required to trigger advancement
+- **`forwards`**: Available operations from this Pair
 
-**Key Fields**:
-- `parent`: Progress ID
-- `u64`: Sequence number
+A Node can have multiple Pairs, enabling multi-path entry (e.g., "Completed" from both "Normal" and "Express" delivery).
 
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_table_data" })`
+### Forward
 
-## Machine Creation Workflow
+A Forward is a **named operation** that users execute to advance the workflow. Each Forward has:
 
-### Step 1: Design Nodes on Paper
-Sketch the workflow graph before implementation. Identify all nodes, transitions, and conditions.
+- **`name`**: A descriptive operation identifier (e.g., "Confirm Order", "Ship Goods", "Complete Signature").
+- **`weight`**: A 16-bit unsigned integer (0-65535) representing this Forward's contribution toward the threshold. When the sum of completed Forward weights in the current session meets or exceeds the Pair's threshold, the node transition triggers.
+- **`permissionIndex`** and/or **`namedOperator`**: At least one must be specified — both can be set simultaneously, in which case the executor needs EITHER permission to execute the Forward. 
 
-### Step 2: Create Guards for Transitions
-Each conditional forward needs a Guard. Create these Guards first (see [wowok-guard](../wowok-guard/SKILL.md) skill).
+**Permission Model**:
 
-### Step 3: Create the Machine (Dry Run)
-
-**Operation**: `onchain_operations` with `operation_type: "machine"`.
+| Field | Scope | Typical Use |
+|-------|-------|-------------|
+| `permissionIndex` | Shared across ALL Progress instances from this Machine | Internal roles (merchant operators, admins) — same personnel handle all workflow instances |
+| `namedOperator` | Per-Progress namespace | External roles that differ per workflow instance |
 
-**Key Fields**:
-- `op`: "create"
-- `object`: Machine name
-- `description`: Machine description
-- `service`: Service ID this Machine belongs to
-- `guard`: Guard ID for workflow validation
-- `node`: Node configuration object
+- Use `namedOperator: ""` (empty string) to grant order owner and their agents the right to execute the Forward. This is the standard way to let customers operate on their own orders.
+- Use `namedOperator: "<role_name>"` for role-based operators managed per Progress instance — ideal when different orders have different delivery personnel or reviewers.
+- **Both set**: When `permissionIndex` AND `namedOperator` are both specified, the executor needs EITHER permission to execute the Forward — the permissions act as alternatives. This is useful when the same operation should be executable by either internal staff (via `permissionIndex`) or external roles (via `namedOperator`).
 
-### Step 4: Export and Review
+**Best Practice**: Forwards should use **custom permissions** rather than built-in indices to avoid management chaos. Either create a dedicated Permission object via `onchain_operations` with `operation_type: "permission"`, or add custom indices to an existing Permission object. Define workflow-specific roles, then reference those indices in your Forwards. Query the Permission schema via `schema_query({ action: "get", name: "onchain_operations_permission" })`.
 
-**Tool**: `machineNode2file`.
+### Guard on Forwards
 
-**Key Fields**:
-- `machine`: Machine ID
-- `file_path`: Output file path
-- `format`: Output format ("json" or "markdown")
+A Forward can include a **Guard** — an on-chain validation rule that must pass for the Forward to complete. Guards are IMMUTABLE after creation.
 
-### Step 5: Execute
-After review, add `submission` field to execute the operation.
+**Common uses**: Time-locks, external condition checks, sub-order validation, penalty verification.
 
-## Machine from File
+**Retained submissions**: Guards can preserve submitted values for subsequent nodes via `retained_submission`.
 
-Load node definitions from a local file:
+> **Full Reference**: See [wowok-guard](../wowok-guard/SKILL.md) for 70+ Guard node types.
 
-**Operation**: `onchain_operations` with `operation_type: "machine"`.
+### Threshold Mechanics
 
-**Key Fields**:
-- `op`: "create"
-- `object`: Machine name
-- `service`: Service ID
-- `node.json_or_markdown_file`: Path to node definition file
+The threshold is the **trigger value** for node advancement. Users execute Forwards from the current node, accumulating weight. When the **sum of completed Forward weights ≥ threshold**, the session finalizes: completed Forwards move to history, and the workflow advances to the next node.
 
-## Common Machine Errors
+**Competing Transitions**: If a node has multiple Pairs leading to different next nodes, the first Pair to meet its threshold wins — subsequent completions go to the newly active node. This enables competitive workflows where different paths race to completion.
 
-| Error | Cause | Fix |
-|-------|-------|-----|
-| "node not found" | Forward references non-existent node | Check all forward names match node names |
-| "guard not found" | Forward references non-existent Guard | Create the Guard first |
-| "circular dependency" | Infinite loop in forwards | Ensure at least one terminal node |
-| "threshold not met" | Not enough signers | Check threshold value and signer count |
-| "invalid pairs" | Node data doesn't match pairs schema | Check pairs definition matches submitted data |
+**Parallel vs Sequential Execution**: By configuring thresholds and weights, you control task coordination:
+- **Sequential**: `threshold = 1`, single Forward with `weight = 1` — one completion triggers advancement
+- **Parallel (AND)**: `threshold = N`, N Forwards each with `weight = 1` — all must complete before advancing
+- **Parallel (OR)**: Multiple Pairs from same node, each with `threshold = 1` — first completion wins, enabling branching paths like `A→B→C` vs `A→C` where B is optional
 
-## Real-World Machine Workflows (from tested examples)
+---
 
-### MyShop: 4-Node Order Processing
+## Machine Lifecycle
 
-**Source**: [MyShop Example](../examples/MyShop/MyShop.md)
+### Dependency-First Construction
 
-A linear order fulfillment workflow for an e-commerce store:
+A Machine depends on a **Permission** object. Build in this order:
 
 ```
-Order Confirmation → Shipping → In Transit → Completed
-                                         ↘ Order End (Cancel Order)
+1. Permission (CREATE or MODIFY to add indices) → provides access control foundation; add custom indices anytime for Forwards
+2. Machine (CREATE, unpublished) → define structure and ALL nodes
+3. Guards (CREATE) → build conditions needed by Forwards
+4. Bind Guards to Forwards (MODIFY Machine) → add guard references to specific forwards
+5. Publish Machine → nodes become IMMUTABLE
+6. Bind Machine to Service (MODIFY Service) → machine field
 ```
 
-**Key Design**: The first node (`Order Confirmation`) has two `pairs` entries — one for the initial transition (threshold=0, from empty `prev_node`) and one for cancel. Normal flow goes through Shipping → In Transit → Completed. The customer (order owner) can cancel from Order Confirmation.
+**Schema Reference**: Query all Machine operations via `schema_query({ action: "get", name: "onchain_operations_machine" })`. This includes configuration (description, repository binding, pause control, publish, owner receive, contact binding, progress creation, etc.) and node manipulation operations.
 
-**Node Structure**:
-- Node "Order Confirmation": Two pairs
-  - From empty prev_node: threshold 0, forward to "Confirm Order"
-  - From "Order Confirmation": threshold 0, forward to "Cancel Order"
-- Node "Shipping": From "Order Confirmation", threshold 1, forward to "Start Shipping"
-- Node "In Transit": From "Shipping", threshold 1, forward to "Mark In Transit"
-- Node "Completed": From "In Transit", threshold 1, forward to "Complete Order"
+### Node Operations (Pre-Publish Only)
 
-### MyShop Advanced: 11-Node Multi-Path Workflow
+Use the `node` field with `op` value: `"add"`, `"set"`, `"remove"`, `"clear"`, `"exchange"`, `"rename"`, `"remove prior node"`, `"add forward"`, `"remove forward"`.
 
-**Source**: [MyShop Advanced Example](../examples/MyShop_Advanced/MyShop_Advanced.md)
+**File-based Workflow**: Export via `machineNode2file`, edit, then import via `node.json_or_markdown_file`.
 
-An enterprise-grade workflow with dual-signature returns, reward incentives, and time-based auto-completion:
+---
 
-```
-Order Confirmed ──→ Shipping ──→ Delivery Complete ──→ Order Complete
-    │                  │   │            │    │
-    │                  │   │            │    └──→ Non-receipt Return ──→ Return Complete
-    │                  │   │            │
-    │                  │   ├──→ Wonderful
-    │                  │   ├──→ Order Complete (time >= 10d)
-    │                  │   └──→ Lost (dual-sig, threshold=2)
-    │                  │
-    └── Order Cancel ──┘            Receipt Return ──→ Return Fail (time >= 10d)
-                                                        └──→ Return Complete (dual-sig)
-```
+## Progress: The Live Workflow Instance
 
-**Key Design Decisions**:
-- **Dual-signature returns**: Lost, Non-receipt Return, Receipt Return, and Return Complete all use `threshold: 2` — requiring both customer and merchant to confirm
-- **Time-based auto-completion**: Order Complete and Return Fail use time guards (10 days) for automatic transitions
-- **Wonderful rating**: Customer can rate delivery as "Wonderful" from the Shipping node, triggering reward
-- **"Who completes, who submits"**: The party responsible for an action submits the on-chain proof (e.g., merchant submits Merkle Root for shipping, customer for returns)
+### Progress Creation
 
-### Insurance: 2-Node Time-Lock Workflow
+Progress objects are created in two ways:
+- **Service Order**: When an Order is created on a Service with a bound Machine, Progress is automatically instantiated
+- **Direct Creation**: Via `progress_new` operation with appropriate permissions
 
-**Source**: [Insurance Example](../examples/Insurance/Insurance.md)
+### Progress Operations
 
-A minimal claim processing workflow with time-lock protection:
+**Order-associated Progress** (when Forward with `namedOperator: ""`): Must advance via `order` operations.
 
-```
-Start → Complete (time-lock guard: clock > progress.current_time + 1000ms)
-```
+**All other cases**: Advance via direct `progress` operations.
 
-**Key Design**: The Complete forward uses a Guard with `convert_witness: 100` (TypeOrderProgress) to access the Order's Progress object and query `progress.current_time`. This creates a time-lock — the claim cannot be completed until the lock duration passes.
+**Advancing Progress**:
 
-**Node Structure**:
-- Node "Start": From empty prev_node, threshold 0, forward to "start_claim"
-- Node "Complete": From "Start", threshold 1, forward to "complete_claim" with time guard
+Use `operate` field with `next_node_name`, `forward`, and optional `hold` for two-phase operation (lock with `hold: true`, submit with `hold: false`). Use `adminUnhold: true` to force-release locks.
 
-### Travel: 5-Node Weather-Dependent Workflow
+**Progress-level config**:  `repository`, `progress_namedOperator`, `task(cannot be changed once set)`.
 
-**Source**: [Travel Example](../examples/Travel/Travel.md)
+### Querying Progress State
 
-A complex travel service workflow with insurance sub-order and weather-dependent activity:
+**Tools**:
 
-```
-Start → Buy Insurance (creates sub-order) → SPA → Ice Scooting (weather check guard)
-                                                      ├──→ Complete (time-lock)
-                                                      └──→ Cancel
-```
+- `query_toolkit` with `query_type: "onchain_objects"` — query the Progress object to see its current node, sessions, and metadata.
+- `query_toolkit` with `query_type: "onchain_table"` — query all history records from Progress table (paginated)
+- `query_toolkit` with `query_type: "onchain_table_item_progress_history"` — query single history record by sequence number
 
-**Key Design**:
-- **Insurance sub-order**: The "Buy Insurance" forward creates a sub-order on the Insurance Service via `forward_to_order_create`
-- **Weather-dependent activity**: The Ice Scooting forward uses a weather check Guard that queries the weather Repository
-- **Time-lock completion**: The Complete forward uses `convert_witness: 100` for time-lock (same as Insurance)
-- **Named forwards**: Each forward uses a descriptive `forward_name` for event tracking
+**Schema Reference**: `schema_query({ action: "get", name: "onchain_table_data" })`
 
-### ThreeBody Signature: 2-Node Simple Workflow
+---
 
-**Source**: [ThreeBody Signature Example](../examples/ThreeBody_Signature/ThreeBody_Signature.md)
+## Workflow Design Patterns
 
-The simplest possible workflow — just delivery and completion:
+### Multi-Path Workflow Example
 
+**MyShop Advanced** — demonstrates branching, dual-signature, and time guards:
 ```
-Book Delivered → Signature Completed
+Shipping → Delivery Complete → Order Complete
+    │  ├──→ Wonderful (rating, reward)
+    │  ├──→ Order Complete (time guard: ≥10 days, anyone push)
+    │  └──→ Lost (threshold: 2, merchant+customer dual-sig)
+    │
+    └── Delivery Complete → Non-receipt Return (threshold: 2)
+                     └──→ Receipt Return (threshold: 2) → Return Fail (time guard)
+                                                   └──→ Return Complete
 ```
 
-**Node Structure**:
-- Node "Book Delivered": From empty prev_node, threshold 0, forward to "Confirm Delivery"
-- Node "Signature Completed": From "Book Delivered", threshold 1, forward to "Complete Signature"
+### Sub-Order Creation (Supply Chain)
 
-## Machine Workflow Design Checklist
-
-Based on patterns from all tested examples:
+**Business Intent**: When advancing a Forward, automatically create a sub-order on another Service — committing to use a trusted supplier.
 
 ```
-Designing a Machine workflow?
-├─ How many nodes?
-│  ├─ 2 nodes → Pattern: Start → Complete (Insurance, ThreeBody)
-│  ├─ 4 nodes → Pattern: Linear pipeline (MyShop)
-│  ├─ 5+ nodes → Pattern: Multi-path with branches (Travel, MyShop Advanced)
-│  └─ 11+ nodes → Pattern: Enterprise with dual-sig + time + rewards
-│
-├─ Need dual-signature (multi-party approval)?
-│  └─ Set threshold: 2 on the node → Both parties must confirm
-│
-├─ Need time-based auto-advancement?
-│  └─ Add a time guard on the forward (e.g., machine_time_10d_v2)
-│
-├─ Need sub-order creation (supply chain)?
-│  └─ Use forward_to_order_create on the forward (Travel → Insurance)
-│
-├─ Need initial entry (prev_node: "")?
-│  └─ threshold: 0 on the first pair means "anyone can enter from start"
-│
-└─ Need guard on forward?
-   └─ guard: { guard: "<guard_name>" } validates the transition
+Start → Buy Insurance (creates sub-order on Insurance Service) → Main Activity → Complete
 ```
 
-## Machine Node Patterns Quick Reference
-
-| Pattern | Nodes | Threshold | Guard | Use Case |
-|---------|-------|-----------|-------|----------|
-| Auto-start | `prev_node: ""` | 0 | none | Entry point — anyone can start |
-| Single-party | `prev_node: "X"` | 1 | optional | One party advances (merchant or customer) |
-| Dual-signature | `prev_node: "X"` | 2 | optional | Both parties must confirm (returns, lost) |
-| Time-lock | `prev_node: "X"` | 1 | time guard | Auto-complete after duration |
-| Guarded | `prev_node: "X"` | 1 | condition guard | Weather check, Merkle root, etc. |
-| Sub-order | `prev_node: "X"` | 1 | guard + forward_to | Create order on another Service |
+**Key Characteristics**:
+- The Forward uses `forward_to_order_create` to specify the target Service for the sub-order
+- The Guard on the Forward validates that the sub-order was successfully created
+- Useful for supply chain transparency: "We use X supplier" becomes verifiable on-chain
 
----
+**Real Example — Travel** (insurance sub-order):
+- Forward "Buy Insurance" on the "Start" node creates a sub-order on the Insurance Service
+- The Insurance sub-order follows its own Machine workflow independently
+- Both workflows (Travel and Insurance) progress in parallel
 
-## Privacy & Consensus via Messenger
+### Dual-Signature Consensus
 
-Sensitive logistics and customer data flow through Messenger's end-to-end encryption (never on-chain). Guard consensus follows: **who performs the key action, submits the proof; the other party confirms**.
+Require both parties (customer and merchant) to confirm before advancing — used for sensitive operations like returns, lost packages, and completion.
 
-| Scenario | Action | Proof Submission |
-|----------|--------|------------------|
-| Merchant ships | Receives address via Messenger, replies tracking number | Merchant submits Merkle Root to Guard |
-| Customer returns | Sends return tracking via Messenger | Customer submits Merkle Root to Guard |
-| Mutual confirmation | Both parties sign | Both submit confirmation proofs |
-
-This pattern is used in Machine workflows where off-chain actions (shipping, delivery) need on-chain verification via Guard proofs.
+- Threshold: 2 with two Forwards each of weight: 1
+- One Forward uses `namedOperator: ""` (customer), the other uses `permissionIndex` (merchant)
+- Both must execute before the node transitions
 
 ---
 
-## Forward Permission Model
-
-Each forward must specify either `permissionIndex` or `namedOperator`:
-
-| Field | Scope | Typical Use |
-|-------|-------|-------------|
-| `permissionIndex` | Shared across all Progress instances | Internal roles (merchant operators, admins) |
-| `namedOperator` | Per-Progress namespace | External roles per order instance |
+## Privacy & Off-Chain Consensus
 
-**Order user operations** MUST use `namedOperator("")` — this maps to the order's owner (customer).
+### The Messenger Pattern
 
----
+Sensitive data (addresses, tracking numbers) flows through Messenger's end-to-end encryption — never stored on-chain. Only **Merkle Root** (cryptographic proof) goes on-chain.
 
-## Guard in Forwards — Use Cases
+**The principle**: **Who performs the key action, submits the proof.** The other party confirms.
 
-The optional `guard` field in a Forward validates critical operation results before allowing the forward to complete:
+| Scenario | Off-Chain Action | On-Chain Proof |
+|----------|-----------------|----------------|
+| Merchant ships order | Receives address via Messenger, replies with tracking number | Merchant submits Merkle Root to Guard on Forward |
+| Customer returns item | Sends return tracking number via Messenger | Customer submits Merkle Root to Guard on Forward |
+| Mutual confirmation | Both parties sign via Messenger | Both submit confirmation proofs |
 
-- **Repository submission validation**: Verify that required data was successfully submitted to a specified Repository object
-- **Supply chain commitment validation**: Confirm that sub-order commitments in the supply chain were fulfilled
-- **External condition checks**: Validate any external state or conditions that must be met before proceeding
-- **Service penalty validation**: Verify compensation payments for service failures (e.g., late delivery penalties)
+The Merkle Root Guard validates that the communication matches the expected content pattern, ensuring accountability without exposing private data.
 
-When a forward has a Guard, the Guard's logic is evaluated when a user attempts to execute that forward. If the Guard returns `false`, the forward cannot be completed.
+> **Full Guide**: See [wowok-messenger](../wowok-messenger/SKILL.md) for WTS evidence generation.
 
 ---
 
-## Service Penalty & Compensation Pattern
+## Service Penalty Pattern
 
-Design Machines to handle **service failures gracefully** through automated compensation workflows. This pattern validates penalty payments before allowing workflow continuation.
+Handle service failures through automated compensation workflows. Guards validate penalty payments before allowing continuation.
 
-### Use Case: Late Delivery Compensation
+### Late Delivery Penalty Pattern
 
-**Scenario**: Courier service fails to deliver within promised timeframe. Machine requires courier to pay penalty to customer before order can proceed.
-
-```
-Delivery Node ──→ Late Delivery Detected (Guard: time > deadline)
-                      │
-                      ├──→ Penalty Payment Required ──→ Payment Verified (Guard)
-                      │                                    │
-                      └──→ Continue to Next Node ←─────────┘
-```
-
-**Machine Design**:
-- Node "Delivery" with two forwards from "Shipping" node:
-  - "On Time Delivery" forward: normal path
-  - "Late Delivery" forward: with guard checking if past deadline
-
-**Guard Logic** (`delivery_penalty_guard`):
-- Query Progress: Get `progress.current_time` vs `expected_delivery_time`
-- If late: Verify Payment object showing penalty amount transferred to Order
-- Validate: Payment amount ≥ configured penalty rate
-- Validate: Payment completed within grace period
+**Design**: The Shipping node has two Forwards — one for on-time delivery (no guard), one for late delivery (guard checks if past deadline). The late path requires a Guard that verifies a Payment from the merchant to the customer's Order before allowing progression.
 
 **Benefits**:
-- **Automatic enforcement**: Late delivery cannot proceed without compensation
-- **Verified compensation**: Guard cryptographically verifies payment occurred
-- **Customer protection**: Guaranteed penalty for service failures
-- **Service accountability**: Forces service providers to meet commitments
-
-### Cross-Service Collaboration Penalties
+- Automatic enforcement — late delivery cannot proceed without compensation
+- Cryptographically verified payment
+- Customer protection guarantee
+- Service accountability
 
-**Pattern**: When multiple services collaborate (e.g., Travel + Insurance + Courier), any party's failure can trigger penalties paid to the affected customer's Order.
-
-```
-Travel Order ──→ Courier Sub-order ──→ Late Delivery
-                                              │
-                                              ├──→ Courier pays penalty to Travel Order
-                                              │
-                                              └──→ Travel Order receives compensation
-                                                   (Order.receive to claim funds)
-```
-
-**Implementation**:
-1. Courier Service Machine has `late_delivery` node with penalty Guard
-2. Guard verifies Payment from Courier Service to Travel Order
-3. Travel Order's `receive` operation extracts penalty to customer
-4. Workflow continues only after penalty verified
-
-**Schema Reference**: `schema_query({ action: "get", name: "onchain_operations_payment" })` — for penalty payment validation
+> **Schema**: `schema_query({ action: "get", name: "onchain_operations_payment" })`
 
 ---
 
-## Progress Advancement Rules
+## Common Pitfalls
 
-- Sum of completed forward weights ≥ threshold → session moves to history, next node becomes current
-- Order users advance via `Order` object
-- Non-order users advance via `Progress` object directly
+- **Publish before Guards ready** → Cannot add after publish
+- **No entry pair** (`prev_node: ""`) → Workflow cannot start
+- **Orphaned paths** → Orders get stuck
+- **Wrong permission model** → Unauthorized access or lockout
+- **Machine without Allocator design** → Fund distribution mismatch (map terminal nodes to allocators)
 
----
+**Always test on testnet before mainnet** — Machines are immutable after publish.
 
-## Schema Reference
+---
 
-| Purpose | Schema Name |
-|---------|-------------|
-| Machine operations | `onchain_operations_machine` |
-| Progress operations | `onchain_operations_progress` |
-| Query on-chain objects | `query_toolkit` |
-| Query table data | `onchain_table_data` |
-| Payment operations | `onchain_operations_payment` |
+## Quick Reference
 
-**Query Schema**: `schema_query({ action: "get", name: "<schema_name>" })`
+**Limits**: 200 nodes, 40 Pairs/node, 20 Forwards/Pair | Weight: u16 | Threshold: u32
 
-**Related Skills**: [wowok-guard](../wowok-guard/SKILL.md) | [wowok-order](../wowok-order/SKILL.md) | [wowok-provider](../wowok-provider/SKILL.md)