@wowok/skills 1.0.6 → 1.1.0

package/wowok-guard/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: wowok-guard
 description: |
   WoWok Guard design mastery — comprehensive reference for the recursive,
@@ -264,7 +264,7 @@ Decide what data the Guard needs:
 - Use `query` + `identifier` patterns for data fetching
 - Use comparison nodes for validation
 
-### Step 5: Create Guard (Dry-Run First)
+### Step 5: Create Guard
 ```
 onchain_operations({
   operation_type: "guard",
@@ -274,17 +274,18 @@ onchain_operations({
     table: [...],
     root: { type: "node", node: { type: "logic_and", nodes: [...] } }
   }
-  // NO submission → dry run
 })
 ```
 
+Guard creation is a **one-step** operation — the `guard` operation type has no `submission` field. It either succeeds (returns transaction) or fails (returns error).
+
 ### Step 6: Export for Review
 ```
 guard2file({ guard: "my_guard", file_path: "./my_guard.json", format: "json" })
 ```
 
-### Step 7: Execute
-Add `submission` after confirming the dry-run result.
+### Step 7: Use Guard in Operations
+The Guard is now ready to be referenced by other operations (service, machine, progress, etc.) via their `submission` field. See [Guard Submission Mechanism](../schemas/onchain_operations/_index.md) for how Guards participate in the two-step submission flow.
 
 ---
 
@@ -371,4 +372,54 @@ Add `submission` after confirming the dry-run result.
 | "type mismatch" | Wrong ValueType in table | Match table type to actual value type |
 | "table field required" | Missing table array | Guards MUST have `table[]` |
 | "guard validation failed" | Logic error | Export with `guard2file`, review logic |
-| "object not found" | Wrong query object | Verify object addresses/identifiers |
+| "object not found" | Wrong query object | Verify object addresses/identifiers |
+
+---
+
+## Query Witness Conversion Types
+
+When using a `query` node's `convert_witness` field, the following numeric IDs allow cross-object type conversion — accessing a related object from the current context:
+
+| Conversion | ID | Description |
+|-----------|-----|-------------|
+| TypeOrderProgress | 100 | From Order, get its Progress |
+| TypeOrderMachine | 101 | From Order, get its Machine |
+| TypeOrderService | 102 | From Order, get its Service |
+| TypeProgressMachine | 103 | From Progress, get its Machine |
+| TypeArbOrder | 104 | From Arb, get its Order |
+| TypeArbArbitration | 105 | From Arb, get its Arbitration |
+| TypeArbProgress | 106 | From Arb, get its Progress |
+| TypeArbMachine | 107 | From Arb, get its Machine |
+| TypeArbService | 108 | From Arb, get its Service |
+
+**Example**: To verify that an Order's Progress is at a specific node, query the Order with `convert_witness: 100` (TypeOrderProgress) to fetch the Progress object, then query the Progress's current node name.
+
+---
+
+## Discovering Query Instructions via `wowok_buildin_info`
+
+Before using `query` nodes, discover available query instructions and their signatures:
+
+```typescript
+// Query all Guard instructions and object queries
+{
+  info: "guard instructions",
+  filter: {
+    scope: "all",           // "instruct" | "object query" | "all"
+    objectType?: string,    // Filter by object type (for object queries)
+    returnType?: string,    // Filter by return type
+    paramCount?: number,    // Filter by parameter count
+    name?: string           // Case-insensitive name filter
+  }
+}
+```
+
+This returns a list of all available operations with:
+- `id`: Numeric operation ID
+- `name`: Human-readable name (e.g., "machine.description")
+- `objectType`: Target object type
+- `parameters`: Array of expected parameter types
+- `return`: Return value type
+- `description`: Detailed usage description
+
+Always query `guard instructions` before designing complex Guards to ensure correct IDs, parameter types, and return types.

package/wowok-machine/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: wowok-machine
 description: |
   WoWok Machine workflow design — defines multi-step workflows (state machines)
@@ -510,3 +510,50 @@ Designing a Machine workflow?
 | 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 |
+
+---
+
+## Privacy & Consensus via Messenger
+
+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**.
+
+| 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.
+
+---
+
+## 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 |
+
+**Order user operations** MUST use `namedOperator("")` — this maps to the order's owner (customer).
+
+---
+
+## Guard in Forwards — Use Cases
+
+The optional `guard` field in a Forward validates critical operation results before allowing the forward to complete:
+
+- **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
+
+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.
+
+---
+
+## Progress Advancement Rules
+
+- 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

package/wowok-order/SKILL.md

@@ -1,4 +1,4 @@
----
+---
 name: wowok-order
 description: |
   WoWok order lifecycle management — covers the complete order flow from
@@ -18,6 +18,30 @@ when_to_use:
 
 # WoWok Order Lifecycle Management
 
+## Runtime Objects Overview
+
+After a Service is published (see [wowok-build](../wowok-build/SKILL.md)), users interact with it creating runtime objects:
+
+| Object | Created By | Purpose |
+|--------|-----------|---------|
+| **Order** | User purchase | Order management and escrow |
+| **Progress** | Order creation | Workflow state tracking |
+| **Allocation** | Order completion | Fund distribution per consensus |
+| **Arb(s)** | Dispute request | Arbitration for compensation |
+
+```
+User Purchase
+     ↓
+Service ──→ Order ──→ Progress ──→ Allocation
+              ↓           ↓
+         Payment    Node Transitions
+         (escrow)   (Guard validated)
+                        ↓
+                   Completion
+                        ↓
+              Fund Distribution
+```
+
 ## Order Lifecycle Overview
 
 ```
@@ -497,3 +521,13 @@ The Insurance Service must already be deployed and published before the Travel S
 6. DISPUTE RESOLUTION (if needed)
    Arbitration → arb_confirm/arb_objection → resolution
 ```
+
+---
+
+## Payments & Refunds Rules
+
+- **Service purchase**: Always pay through `Service`. Name the generated `Order`, `Progress`, and `Allocation` via `namedNew*` fields for easy management.
+- **Order operations**: All order user operations MUST go through the `Order` object — do not operate on `Progress` directly for order-related actions.
+- **Refunds/withdrawals**: Users satisfy `Allocation` Guard conditions to withdraw instantly.
+- **Arbitration claims**: Compensation payouts go through `Order`.
+- **Alternative payments**: `account_operation (transfer)` for direct wallet-to-wallet, or `onchain_operations (payment)` for commercial features (purpose tracking, Guard validation).