@wowok/skills 1.1.1 → 1.1.3

package/wowok-order/SKILL.md

@@ -184,19 +184,79 @@ Once consensus is reached, create the order through Service operation.
 
 When creating an order via the `buy` operation, you can apply a discount coupon by including the `discount` field with the coupon name/ID.
 
+**Finding Available Discounts**:
+
+Discount coupons are separate objects that you receive (usually transferred from Service marketing campaigns or other users). To find discounts applicable to the current Service:
+
+**Step 1: Query all Discount objects you own**
+
+Use `query_toolkit` with `onchain_received` query type to get all Discount objects:
+
+```json
+{
+  "query_type": "onchain_received",
+  "name_or_address": "your_account_name",
+  "type": "0x2::service::Discount", // Discount type on-chain
+  "cursor": null,
+  "limit": 50
+}
+```
+
+This returns `ReceivedNormal[]` where each item's `content_raw` contains Discount fields:
+- `name`: Discount name
+- `discount_type`: "rate" (percentage) or "fixed" (absolute amount)
+- `benchmark`: Minimum order amount required
+- `off`: Discount value (e.g., 1000 for 10% if rate, or 100 for 100 units if fixed)
+- `time_start` / `time_end`: Validity period
+- `service`: Parent Service object ID (which Service this discount belongs to)
+- `transferable`: Whether it can be transferred to others
+
+**Step 2: Filter discounts for the current Service**
+
+Each Discount has a `service` field indicating which Service it can be used with. Filter the received Discount objects by comparing each Discount's `service` field with the target Service object ID you're purchasing from. Only Discounts where `service` matches the target Service can be applied to that Service.
+
+**Step 3: Validate discount applicability**
+
+Before using a discount, verify:
+1. **Time validity**: `time_start` ≤ current_time ≤ `time_end`
+2. **Minimum amount**: Order total ≥ `benchmark`
+3. **Service match**: Discount's `service` field matches the Service being purchased
+
+**Step 4: Apply discount in order creation**
+
+Include the selected Discount object ID in the `buy.discount` field:
+
+```json
+{
+  "operation_type": "service",
+  "data": {
+    "buy": {
+      "items": [...],
+      "total_pay": "10000",
+      "discount": "discount_object_id_here"
+    }
+  }
+}
+```
+
+**Discount Calculation**:
+- If `discount_type` is "rate": Discount = `total_pay` × (`off` / 10000)
+- If `discount_type` is "fixed": Discount = min(`off`, `total_pay`)
+- Final payment = `total_pay` - Discount
+
 | `namedNewOrder` | Local name for Order | Recommended for easy reference |
 | `namedNewProgress` | Local name for Progress | Recommended |
 | `namedNewAllocation` | Local name for Allocation | Recommended |
 
 ### 3.2 Private Information Handling
 
-If Service requires private info (`customer_required`):
+After order creation, the AI must check the Service's `customer_required` field to see what information the provider needs (e.g., phone, email, delivery address).
 
-1. **NEVER put on-chain** — send via Messenger
-2. Include order ID in the message
-3. Confirm receipt with seller
-
-**Tool**: `messenger_operation` with `send_message` operation.
+1. **Retrieve from local storage**: Use `query_toolkit` → `local_info_list` to retrieve your saved private information matching the `customer_required` fields. These are sensitive records stored only on your device.
+2. **AI should prompt**: If the required info is not in `local_info`, ask if the user wants to save it there for future use. If it exists, present it for user confirmation before sending.
+3. **Send via Messenger**: Use `messenger_operation` with `send_message` — **NEVER put private information on-chain**.
+4. **Include order ID** in the message for traceability.
+5. **Request explicit confirmation**: Unconfirmed delivery may stall order progress.
 
 ### 3.3 Post-Creation Notification
 

package/wowok-provider/SKILL.md

@@ -86,7 +86,7 @@ Design your service offering before building. This phase defines what customers
 
 ### 1.1 Product Promise (WIP Files)
 
-WIP (Witness Information Promise) files are **immutable product commitments** — your on-chain promise to customers.
+WIP (Witness Immutable Promise) files are **immutable product commitments** — your on-chain promise to customers.
 
 **Creating WIP Files**:
 
@@ -419,6 +419,8 @@ Contact.ims[] → Your customer service addresses
 - Confirm understanding explicitly (ARK signature required for evidence)
 - Proactively communicate delays
 
+> **AI reminder**: When fulfilling an order, the AI should proactively check whether the Service's `customer_required` fields (phone, email, delivery address, etc.) have been provided by the customer. If any are missing, prompt the provider to request them from the customer via Messenger using `messenger_operation` with `send_message`.
+
 > **Full Guide**: See [wowok-messenger](../wowok-messenger/SKILL.md) for messaging, WTS generation, and evidence management.
 
 ---

package/wowok-safety/SKILL.md

@@ -238,9 +238,24 @@ Use `Payment` objects for commercial transfers when possible — they offer Guar
 
 ## 9. Testing & Validation Workflow
 
-1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions and Guard instructions
+1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions, Guard instructions, and value types
 
-**Tool**: `wowok_buildin_info` with `info_type: "permissions"` or `info_type: "guard_instructions"`.
+**Tool**: `wowok_buildin_info` with `info: "permissions"`, `info: "guard_instructions"`, or `info: "value types"`.
+
+### 9.1 Value Types — Built-in Type Annotation System
+
+WoWok's value type system is the foundation for type-safe data declarations used across Guards, records, and query instructions. Every data field in a Guard table or Guard submission carries a `value_type` annotation, ensuring the protocol can validate and process data correctly.
+
+**When value types matter:**
+- Defining Guard table columns: each Identifier in a Guard's `table` block requires a `value_type`
+- Submitting data to Guards: `GuardSubmission` entries must match their declared `value_type`
+- Reading Guard exports: `guard2file` output shows `value_type` for every Identifier
+- Designing query instructions: both parameters and return values carry `value_type` annotations
+
+- **String format is recommended** (e.g., `"U64"`, `"Address"`, `"VecString"`) for readability in Guard tables and submissions.
+- Numeric codes (0–18) are accepted but obscure — prefer string names in all user-facing contexts.
+- `Value` (19) is a protocol-internal type for dynamic value handling. It must **never** be used directly in user-defined Guards or submissions.
+**Available value types** (queried via `wowok_buildin_info` with `info: "value types"`)
 
 2. **Export & Review**: Before publishing, use `guard2file` and `machineNode2file` to export and review definitions
 
@@ -272,6 +287,9 @@ For complex objects with many fields (Service, Machine), use **incremental build
 | Guard export | `guard2file` |
 | Machine export | `machineNode2file` |
 | Build-in info | `wowok_buildin_info` |
+| Built-in permissions | `wowok_buildin_info` with `info: "permissions"` |
+| 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>" })`