@wowok/skills 1.1.2 → 1.1.4

package/wowok-messenger/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: wowok-messenger
+description: |
+  WoWok Messenger — end-to-end encrypted communication for pre-order negotiation,
+  evidence collection, and dispute resolution.
+
+  Core features: send/receive encrypted messages, generate WTS evidence files,
+  verify message authenticity, manage conversation lists, and integrate with
+  arbitration workflows.
+
+  Used by customers, service providers, and arbitrators for secure off-chain
+  communication that creates tamper-proof audit trails.
+when_to_use:
+  - User needs to communicate with another party (buyer, seller, arbitrator)
+  - User wants to send encrypted messages for negotiation
+  - User needs to generate WTS evidence files from conversations
+  - User wants to verify message authenticity
+  - User needs to manage conversation lists (friends, blacklist, guard)
+  - User mentions "messenger", "message", "chat", "communication", "WTS", "evidence"
+always: false
+---
+
+# WoWok Messenger Guide
+
+End-to-end encrypted messaging for secure off-chain business communication with tamper-proof audit trails.
+
+> **Role**: Any WoWok participant (customer, service provider, arbitrator)  
+> **Prerequisites**: Understand the tool pattern — use `schema_query({ action: "get", name: "messenger_operation" })`  
+> **Guard Design**: See [wowok-guard](../wowok-guard/SKILL.md) if configuring guard-based spam protection  
+> **Tool Reference**: See [wowok-tools](../wowok-tools/SKILL.md) for MCP tool schemas
+
+---
+
+## Core Concepts
+
+### Trust Model
+
+The messenger operates on a **triple-trust model**. For detailed architecture and communication mechanisms, see the [Messenger Deep Dive Documentation](https://github.com/wowok-ai/docs/blob/main/docs/stage-03b-messenger.md).
+
+**Key Design Decisions**:
+- Messages are **NOT on-chain**. Communication is off-chain for privacy and cost efficiency.
+- The server **cannot read** messages. Ciphertext is opaque; only endpoints hold decryption keys.
+- The server **proves message order**. Its Falcon512 signature on the Merkle tree is verifiable by anyone.
+- On-chain proof is **optional**. A message's Merkle root can be anchored to the blockchain via `proof_message`.
+
+### Evidence Closure Principle
+
+> **A message becomes valid evidence ONLY when the recipient explicitly responds to or decrypts it.**
+
+One-sided claims are not evidence. The system enforces this through cryptographic and behavioral rules:
+- A message alone proves nothing about the recipient's awareness.
+- ARK confirmation (recipient-signed receipt) creates cryptographic proof both parties acknowledge the message.
+- A reply is the strongest form of acknowledgment — it proves the recipient held the session key and acted on the message.
+- WTS files include both sides of the conversation for complete context.
+- Arbitration requires **confirmed**, reciprocated evidence — never unilateral claims.
+
+---
+
+## 1. Message Delivery Mechanism
+
+### 1.1 Message Delivery & Stranger Rules
+Messages from **strangers** (addresses not in the recipient's friends list) are subject to additional restrictions:
+
+- **One-message limit**: A stranger may send exactly one message. Until the recipient replies, any further messages from the same stranger are rejected.
+- **Reply unlocks**: When the recipient replies, the stranger is automatically added to the recipient's friends list, and both parties can message freely thereafter.
+- **Cool-down window**: The one-message restriction persists for a configurable duration. If the recipient does not reply within this window, the stranger may retry one message.
+- **Recipient opt-out**: A recipient can disable stranger messages entirely. When blocked, the sender receives the recipient's guard list as an alternative contact path.
+
+**Rationale**: This design prevents unsolicited spam while allowing legitimate first contact. The one-message limit forces the stranger to make their opening message count, and auto-friend-on-reply ensures smooth continuation once the recipient engages.
+
+### 1.2 Guard Message Flow (Spam-Bypass Path)
+
+When a sender provides both `guardAddress` and `passportAddress`, the server verifies the guard and passport are valid. On success the message is delivered; on failure the sender is notified.
+
+**When to use**: When the recipient has disabled stranger messages and you are not in their friends list, the rejection response includes the recipient's guard list. Obtain a valid passport from one of those guards and resend with both `guardAddress` and `passportAddress`.
+
+### 1.3 Session and Message Sequence
+
+Every conversation between two addresses has a deterministic session, ensuring both parties share the same session context. Messages are ordered by a monotonically increasing index starting from zero, establishing their absolute position in the conversation.
+
+---
+
+## 2. Anti-Spam Mechanism
+
+### 2.1 Protection Model
+
+Messages are evaluated in four sequential layers: **Blacklist** → **Friends List** → **Guard Verification** → **Stranger Rules**. See the [technical documentation](https://github.com/wowok-ai/docs/blob/main/docs/stage-03b-messenger.md) for implementation details.
+
+### 2.2 List Management
+
+Three independently managed lists control who can reach you:
+
+| List | Purpose | Operations | Hard Limits |
+|------|---------|------------|-------------|
+| **Blacklist** | Block specific addresses completely | `add`, `remove`, `clear`, `get`, `exist` | Server-configured max (default 1000) |
+| **Friends List** | Allow trusted contacts to bypass all checks | `add`, `remove`, `clear`, `get`, `exist` | Server-configured max (default 1000) |
+| **Guard List** | Specify which guards can verify strangers | `add`, `remove`, `get` | Server-configured max (default 100) |
+
+**Tool**: `messenger_operation` with `blacklist`, `friendslist`, or `guardlist` operation.
+
+**Guard List Configuration**: Each entry requires:
+- `guard`: The on-chain Guard object ID or name (see [wowok-guard](../wowok-guard/SKILL.md) for Guard design)
+- `passportValiditySeconds`: How long a passport from this guard remains valid for messaging (typically 60s to 7 days)
+
+Strangers with a valid passport from any guard in your list can message you. Passports are generated via `onchain_operations` with `gen_passport`.
+
+### 2.3 Settings Control
+
+Each user can configure two spam-protection parameters:
+
+**Tool**: `messenger_operation` with `settings` operation (`get` or `set`).
+
+- **`allowStrangerMessages`**: Toggle whether strangers (non-friends, non-guard-verified) can send you messages at all.
+  - `true` (default): Strangers can send one message each (subject to the one-message limit).
+  - `false`: All stranger messages are rejected. The rejection response includes your `guard_list` so the sender can obtain a passport and retry.
+  
+- **`maxInboxSize`**: Maximum messages retained in your inbox (typically 10–1000). Older messages are removed when the limit is reached.
+
+**Note**: The server also has global defaults for these settings.
+
+---
+
+## 3. WTS (Witness Timestamped Sequence) Mechanism
+
+### 3.1 What WTS Is
+
+A WTS file is a **tamper-proof, self-verifying export** of a **continuous** conversation message sequence between two parties. Every message in the chain is cryptographically linked to its predecessor; any gap or modification breaks the entire chain, making tampering immediately detectable. Participant signatures can be added for non-repudiation. Anyone can use a WTS file to verify the authenticity, continuity, and integrity of the conversation content.
+
+
+### 3.2 The Reciprocity Principle
+
+> **Only messages that the other party has replied to have evidentiary value.**
+
+A message alone proves nothing about the recipient's awareness. When the **recipient replies**, their reply references the last message they received, creating cryptographic proof of receipt. A WTS file shows the full conversation — which messages were acknowledged and which were not.
+
+**In practice**: When generating WTS for arbitration, include the full conversation so the arbitrator can see who said what, who acknowledged what, and the exact sequence of events.
+
+### 3.3 WTS Workflow
+
+**Step 1 — Generate WTS**:
+
+**Tool**: `messenger_operation` with `generate_wts` operation.
+
+Key decisions:
+- **Range selection**: Choose which messages to include by time range, message ID range, or sequence index (leafIndex) range.
+- **Output**: One or more `.wts` files are written to the specified output directory (files are split if the total exceeds file size limits).
+
+**Step 2 — Sign WTS**:
+
+**Tool**: `messenger_operation` with `sign_wts` operation.
+
+Adds your Falcon512 (post-quantum) signature to the WTS metadata, proving you endorse the conversation record as accurate. Multiple signatures from any party are supported — participants, arbitrators, or other third parties can all sign to attest to the content.
+
+**Step 3 — Verify WTS**:
+
+**Tool**: `messenger_operation` with `verify_wts` operation.
+
+Verification validates each message's authenticity, the sequence's continuity, the payload's integrity, and all signatures added in Step 2. When all pass, the WTS is **proven authentic, complete, and untampered** — admissible as cryptographic evidence.
+
+**Step 4 — Convert to HTML (optional)**:
+
+**Tool**: `messenger_operation` with `wts2html` operation. Produces a human-readable HTML document.
+
+
+**Step 5 — Submit as evidence**:
+
+Use `send_file` to send the signed WTS file to an arbitrator's messenger address. The arbitrator can then independently verify the WTS using their own `verify_wts` call.
+
+### 3.4 On-Chain Proof (Optional)
+
+**Tool**: `messenger_operation` with `proof_message` operation.
+
+Anchors a message to the WoWok blockchain, creating an **immutable on-chain timestamp** that proves the message existed before that point in time. Anyone can verify the message against this on-chain record independently.
+
+---
+
+## 4. Role-Specific Patterns
+
+### 4.1 Customer → Service Provider
+
+**Order creation and information delivery**:
+
+1. **Discover the service's messenger contact**:
+   - Query the Service object via `query_toolkit` with `query_type: "onchain_objects"` to extract `service.um` (Contact object ID)
+   - Query the Contact object to get `ims[].at` (list of messenger addresses the provider accepts messages at)
+
+2. **Send required customer information** (post-order):
+   - After order creation, check the Service's `customer_required` field (phone, email, delivery address, etc.)
+   - **AI should prompt**: Ask if the user wants to save this information to `local_info` for future use, or retrieve existing info from `local_info_list` to avoid re-entry
+   - Retrieve matching private information from local storage using `query_toolkit` → `local_info_list`
+   - Send via `messenger_operation` with `send_message` to the provider's customer service address
+   - **Request explicit confirmation** — unconfirmed delivery may stall order progress
+   - If this is first contact, you have exactly one message — make it count
+
+3. **WTS is for disputes only**: Generate WTS only when a disagreement escalates and arbitration evidence is required. Normal conversations are already preserved.
+
+### 4.2 Service Provider → Customer
+
+**Customer service response**:
+
+1. **Check conversations**: Use `watch_conversations` to see pending inquiries.
+2. **Respond promptly**: Use `send_message` to reply. Your reply automatically adds the customer to your friends list if they were a stranger.
+3. **Document agreements**: For any commitments (pricing, timeline changes, custom work), confirm them in messages. These become evidence if disputes arise.
+4. **WTS for disputes**: If a disagreement escalates, the provider may generate and sign WTS to demonstrate good faith and support their position.
+
+**Best practices for providers**:
+- Respond promptly to maintain trust
+- Document all agreements and changes in messages
+- Confirm understanding before proceeding with orders
+- Use guard list to allow verified strangers to reach you without opening to all strangers
+
+---
+
+## 5. Operation Order and Dependencies
+
+### 5.1 Account Setup Prerequisites
+
+Before using the messenger, the account must be properly initialized:
+
+1. **Account must exist**: Created via `account_operation` (LOCAL operation).
+2. **Messenger must be enabled**: Set a messenger name on the account via `account_operation` to enable Messenger functionality; clear it to disable.
+
+
+### 5.2 List and Settings Order
+
+When configuring spam protection:
+1. **Get current state**: Use `settings` (`get`) and list operations (`get`) to see the current configuration.
+2. **Add trusted contacts**: Use `friendslist` (`add`) for known counterparties.
+3. **Configure guards**: Use `guardlist` (`add`) if you want to accept verified strangers. The Guard objects must already exist on-chain (see [wowok-guard](../wowok-guard/SKILL.md)).
+4. **Set stranger policy**: Use `settings` (`set`) with `allowStrangerMessages` to toggle stranger access.
+5. **Block unwanted**: Use `blacklist` (`add`) for addresses you never want to hear from.
+
+---
+
+## 6. Schema Reference
+
+All messenger operations and their parameters are defined in a single schema:
+
+**Query**: `schema_query({ action: "get", name: "messenger_operation" })`
+
+This returns the complete discriminated union schema covering all 16 sub-operations with their parameter shapes and constraints.
+
+Related schemas for cross-workflow operations:
+
+| Purpose | Schema Name |
+|---------|-------------|
+| All messenger operations | `messenger_operation` |
+| Query on-chain objects (services, guards, contacts) | `query_toolkit` |
+| On-chain operations (gen_passport for guard) | `onchain_operations` |
+| Local account management | `account_operation` |
+| Local address book (marks) | `local_mark_operation` |
+| Local private info storage | `local_info_operation` |
+---
+
+## 7. Quick Reference
+
+### Messaging
+
+| Goal | Operation | Key Parameters |
+|------|-----------|----------------|
+| Send text | `send_message` | `from`, `to`, `content`, `options.guardAddress?`, `options.passportAddress?` |
+| Send file | `send_file` | `from`, `to`, `filePath`, `options.contentType?` |
+| View conversations | `watch_conversations` | `filter.unreadOnly?`, `filter.previewMessageCount?`, `filter.sortBy?` |
+| View messages | `watch_messages` | `filter.peerAddress?`, `filter.direction?`, `filter.contentType?`, `filter.keyword?` |
+| Mark as read | `mark_messages_as_viewed` | `messageIds`, `account?` |
+| Mark convo read | `mark_conversation_as_viewed` | `peerAddress`, `account?` |
+
+### Evidence (WTS)
+
+| Goal | Operation | Key Parameters |
+|------|-----------|----------------|
+| Export | `generate_wts` | `params.myAccount`, `params.peerAccount`, `params.range?`, `params.outputDir` |
+| Sign | `sign_wts` | `wtsFilePath`, `account`, `outputPath?` |
+| Verify | `verify_wts` | `wtsFilePath` |
+| View HTML | `wts2html` | `wtsPath`, `options.title?`, `options.theme?` |
+| Prove on-chain | `proof_message` | `account`, `messageId`, `network` |
+| Extract ZIP | `extract_zip_messages` | `account`, `messages`, `outputDir` |
+
+### List Management
+
+| Goal | Operation | Key Parameters |
+|------|-----------|----------------|
+| Add friend | `friendslist` (`add`) | `account`, `users` (addresses/names) |
+| Block user | `blacklist` (`add`) | `account`, `users` (addresses/names) |
+| Add guard | `guardlist` (`add`) | `account`, `guards[].guard`, `guards[].passportValiditySeconds` |
+| Toggle strangers | `settings` (`set`) | `account`, `allowStrangerMessages` |
+
+### Local Storage
+
+| Goal | Tool | Key Parameters |
+|------|------|----------------|
+| Write private info | `local_info_operation` (add) | `data`: array of `{ name, default, contents }` |
+| Read private info | `query_toolkit` → `local_info_list` | `filter.name?` |

package/wowok-order/SKILL.md

@@ -250,13 +250,13 @@ Include the selected Discount object ID in the `buy.discount` field:
 
 ### 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-output/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: wowok-output
+description: |
+  WoWok output processing and display — post-processes all WoWok tool responses
+  for human-readable presentation. Handles address resolution, name mapping,
+  amount formatting, and data visualization.
+when_to_use:
+  - AI has received response from any WoWok MCP tool
+  - Response contains addresses requiring name resolution
+  - Response contains amounts requiring human-readable formatting
+  - User queries on-chain data (events, objects, tables)
+always: true
+---
+
+# Address Display Rules
+
+## Override Condition
+
+If user explicitly requests full/long addresses (e.g., "show full addresses", "do not abbreviate"),
+this skill's shortening rules are DISABLED — display complete 66-character addresses.
+
+## Short Address Format
+
+**MUST APPLY TO ALL ADDRESSES** (0x prefix + 64 hex chars = 66 chars total):
+1. Remove `0x` prefix
+2. Take first 5 characters
+3. Convert to UPPERCASE
+4. Wrap in parentheses `()`
+
+**Example**: `0xa1d421902a3e5f2e4da7590e8f243712b3b3479d1a07c48c2de543184fc97a33` → `(A1D42)`
+
+## Resolution Priority & Display Format
+
+**Query Tool**: `query_toolkit` with `query_type: "local_names"`
+
+Returns: `{ account?: string, local_mark?: string, address: string }`
+
+### Display Format Rules (STRICT)
+
+| Condition | Display Format | Example |
+|-----------|----------------|---------|
+| **Both account AND local_mark exist** | `{account_name} \| {local_mark_name} (ABCDE)` | `alice \| my_mark (A1D42)` |
+| **Only account exists** | `{account_name} (ABCDE)` | `alice_wallet (A1D42)` |
+| **Only local_mark exists** | `{local_mark_name} (ABCDE)` | `my_service (A1D42)` |
+| **Neither exists** | `(ABCDE)` | `(A1D42)` |
+
+---
+
+## Name Length Limit
+
+- **Maximum display length**: 20 characters
+- **Overflow handling**: Truncate to 17 chars + `...`
+- **Example**: `three_body_signature_service_v2` → `three_body_sig...`
+
+# Amount Formatting Rules
+
+## Conservative Principle
+
+**When in doubt, display raw value.**
+
+| Condition | Display | Example |
+|-----------|---------|---------|
+| Token info UNAVAILABLE | Raw amount | `500000000` |
+| Token info AVAILABLE | Converted + symbol + precision | `0.5 WOW (9P)` |
+
+## Conversion Requirements
+
+ONLY convert when ALL conditions met:
+1. Token type explicitly identified
+2. Successfully queried via `query_toolkit` with `query_type: "token_list"`
+3. Metadata contains valid `decimals` and `symbol`
+
+**Formula**: `converted = raw / (10 ^ decimals)`  
+**Format**: `{amount} {symbol} ({decimals}P)`
+
+---
+
+# Event Display Format
+
+## Table Format
+
+```
+| # | Time | Sender | Service | Amount | Order |
+|---|------|--------|---------|--------|-------|
+| 1 | {time} | {name} (ABCDE) | {name} (ABCDE) | {amount} | (ABCDE) |
+```
+
+**Note**: `{name}` follows Display Format Rules above (account | local_mark). If no name, show only `(ABCDE)`.
+
+## Event Type Fields
+
+| Event Type | Key Fields |
+|------------|------------|
+| `NewOrderEvent` | sender, service, amount, object |
+| `ProgressEvent` | order, operator, machine |
+| `ArbEvent` | arbitration, voter, order, service |
+| `DemandPresentEvent` | demand, presenter, service |
+| `DemandFeedbackEvent` | demand, feedbacker |
+| `NewEntityEvent` | entity |
+
+---
+
+# Field Explanations
+
+When user asks about field meanings:
+
+## Addresses
+- **Sender**: Account that initiated the transaction
+- **Service**: Service object being ordered/interacted with
+- **Order Object**: Unique on-chain identifier for this order
+- **Short Address (ABCDE)**: First 5 chars for quick visual identification
+
+## Amounts
+- **Raw**: Actual U64 integer stored on-chain
+- **Converted**: Human-readable after applying decimals
+- **Precision (XP)**: Number of decimal places
+
+## Time
+- **Timestamp**: Unix milliseconds since epoch
+- **Human-readable**: Converted local time
+
+---
+
+# Implementation Checklist
+
+- [ ] Extract unique addresses from response
+- [ ] Query `local_names` for resolution
+- [ ] Query `token_list` for amount formatting
+- [ ] Apply address format rules
+- [ ] Apply amount format rules (conservative)
+- [ ] Render final output
+
+---
+
+# Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| [wowok-safety](../wowok-safety/SKILL.md) | Pre-operation safety checks |
+| [wowok-tools](../wowok-tools/SKILL.md) | Tool selection patterns |
+| [wowok-order](../wowok-order/SKILL.md) | Order lifecycle (buyer) |
+| [wowok-provider](../wowok-provider/SKILL.md) | Service management (merchant) |

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

@@ -136,20 +136,6 @@ Controls name collision behavior:
 - Default to `false` in production to prevent accidental name hijacking
 - Prefer versioned names (`_v1`, `_v2`) over `replaceExistName` for production
 
-### 4.2 Address Display Rules
-
-When displaying an address (0x prefix + 64 hex characters) to the user:
-
-1. **Query local mark first**:
-
-**Tool**: `query_toolkit` with `query_type: "local_mark_list"` and filter by address.
-
-2. **Display format**:
-   - If local mark exists: `{name} ({short_address})`
-   - If no local mark: `{first8}...{last3}` (e.g., `0x3a2f8e1...8c1`)
-
-3. **Short address format**: Include `0x` prefix, take first 8 chars + `...` + last 3 chars
-
 ---
 
 ## 5. Network & Token Defaults
@@ -185,47 +171,7 @@ Use `Payment` objects for commercial transfers when possible — they offer Guar
 
 ---
 
-## 7. Name Resolution & Display
-
-### 7.1 Name Resolution Priority
-
-| Priority | Source | Display Format | Example |
-|----------|--------|----------------|---------|
-| 1 (Highest) | `local_mark_operation` | `{local_mark_name} (localmark)` | `my_service (localmark)` |
-| 2 | `account_operation` (account name) | `{account_name}` | `alice_wallet` |
-| 3 (Fallback) | None / Unnamed | `{first6}...{last3}` | `0x3a2f...8c1` |
-
-### 7.2 Address Resolution & Display Format
-
-**Resolve addresses to names** via `query_toolkit`:
-
-**Tool**: `query_toolkit` with `query_type: "local_names"` and `addresses` array parameter.
-
-- Each address must be a valid WOW ID: `0x` prefix + **64 hex characters**.
-- Returns resolved account name and/or local mark name for each address.
-- Name priority follows [7.1](#71-name-resolution-priority): `local_mark` > `account`.
-
-**Address truncation** (for display):
-
-```
-{first_6_chars}...{last_3_chars}
-```
-
-- Include the `0x` prefix in the character count.
-- Use exactly **three dots** (`...`) as the separator.
-- Example: `0x3a2f...8c1`
-
-**Combined display**: human-readable name + truncated address in parentheses.
-
-| Name Source | Display Format | Example |
-|-------------|----------------|---------|
-| local_mark | `{local_mark} ({first6}...{last3})` | `my_service (0x3a2f...8c1)` |
-| account | `{account_name} ({first6}...{last3})` | `alice_wallet (0x3a2f...8c1)` |
-| none (fallback) | `{first6}...{last3}` | `0x3a2f...8c1` |
-
----
-
-## 8. Error Patterns
+## 7. Error Patterns
 
 | Error | Likely Cause |
 |-------|-------------|
@@ -236,11 +182,26 @@ Use `Payment` objects for commercial transfers when possible — they offer Guar
 
 ---
 
-## 9. Testing & Validation Workflow
+## 8. Testing & Validation Workflow
+
+1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions, Guard instructions, and value types
+
+**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.
 
-1. **Design Phase**: Use `wowok_buildin_info` to discover available permissions and Guard instructions
+**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
 
-**Tool**: `wowok_buildin_info` with `info_type: "permissions"` or `info_type: "guard_instructions"`.
+- **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
 
@@ -252,7 +213,7 @@ Use `Payment` objects for commercial transfers when possible — they offer Guar
 
 ---
 
-## 10. Incremental Object Building
+## 9. Incremental Object Building
 
 For complex objects with many fields (Service, Machine), use **incremental building** instead of creating everything in one call:
 
@@ -272,6 +233,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>" })`