@wowok/agent-mcp 2.2.11 → 2.2.13

package/dist/index.js

@@ -6,7 +6,8 @@ import { readFileSync } from "fs";
 import { resolve } from "path";
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 import { CallService_DataSchema, CallMachine_DataSchema, MachineNode2File_InputSchema, MachineNode2File_OutputWrappedSchema, CallProgress_DataSchema, CallPermission_DataSchema, CallGuard_DataSchema, Guard2File_InputSchema, Guard2File_OutputWrappedSchema, CallArbitration_DataSchema, CallRepository_DataSchema, CallContact_DataSchema, CallTreasury_DataSchema, CallReward_DataSchema, CallAllocation_DataSchema, CallPersonal_DataSchema, CallPayment_DataSchema, CallDemand_DataSchema, CallOrder_DataSchema, CallEnvSchema, SubmissionCallSchema, strictParse, CallOutputSchema, handleCallResult, createServerConfig, createCapabilitiesConfig, createToolMeta, transformSubmission, getEnvConfig, WipGenerationOptionsSchema, WipToHtmlOptionsSchema, TokenDataFilterSchema, LocalInfoFilterSchema, LocalMarkFilterSchema, AccountFilterSchema, TokenTypeSchema, OnchainEventsInputSchema, OnchainEventsResultSchema, ProtocolInfoQuerySchema, ProtocolInfoResultSchema, TableAnswerSchema, TableItem_RepositoryDataSchema, TableItem_PermissionPermSchema, TableItem_EntityRegistrarSchema, TableItem_EntityLinkerSchema, TableItem_RewardRecordSchema, TableItem_DemandPresenterSchema, TableItem_TreasuryHistorySchema, TableItem_MachineNodeSchema, TableItem_ProgressHistorySchema, TableItem_AddressMarkSchema, NameOrAddressSchema, ObjectBaseSchema, AccountOrMark_AddressSchema, AccountOrMark_AddressAISchema, EntrypointSchema, AccountOperationOutputWrappedSchema, LocalMarkOperationOutputWrappedSchema, LocalInfoOperationOutputWrappedSchema, WipOperationOutputSchema, MessengerOperationOutputSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, parseMachineNodesFromText, formatNodeErrors as formatMachineNodeErrors, MessengerOperationInputSchema, } from "./schema/index.js";
-import { CallService, CallMachine, CallProgress, CallPermission, CallGuard, CallArbitration, CallRepository, CallContact, CallTreasury, CallReward, CallAllocation, CallPersonal, CallPayment, CallDemand, CallOrder, gen_passport, guard2file, parseGuardFile, formatGuardParseErrors, machineNode2file, generateNodeComments, generate_wip, verify_wip, sign_wip, wip2html, account_operation, local_mark_operation, local_info_operation, watch_conversations, send_message, send_file, watch_messages, extract_zip_messages, generate_wts, verify_wts, sign_wts, wts2html, proof_message, mark_messages_as_viewed, mark_conversation_as_viewed, query_local_mark_list, query_account_list, query_local_info_list, query_local_token_list, query_account, query_personal, query_objects, query_table, query_tableItem, queryProtocolInfo, query_received, queryTableItem_RepositoryData, queryTableItem_PermissionPerm, queryTableItem_RewardRecord, queryTableItem_DemandPresenter, queryTableItem_TreasuryHistory, queryTableItem_MachineNode, queryTableItem_ProgressHistory, queryTableItem_AddressMark, queryTableItem_EntityRegistrar, queryTableItem_EntityLinker, query_events, blacklist, friendslist, guardlist, settings, AmountType, } from "@wowok/wowok";
+import { CallService, CallMachine, CallProgress, CallPermission, CallGuard, CallArbitration, CallRepository, CallContact, CallTreasury, CallReward, CallAllocation, CallPersonal, CallPayment, CallDemand, CallOrder, gen_passport, guard2file, parseGuardFile, formatGuardParseErrors, machineNode2file, generateNodeComments, generate_wip, verify_wip, sign_wip, wip2html, account_operation, local_mark_operation, local_info_operation, watch_conversations, send_message, send_file, watch_messages, extract_zip_messages, generate_wts, verify_wts, sign_wts, wts2html, proof_message, mark_messages_as_viewed, mark_conversation_as_viewed, query_local_mark_list, query_account_list, query_local_info_list, query_local_token_list, query_account, GetLocalNamesByAddresses, query_personal, query_objects, query_table, query_tableItem, queryProtocolInfo, query_received, queryTableItem_RepositoryData, queryTableItem_PermissionPerm, queryTableItem_RewardRecord, queryTableItem_DemandPresenter, queryTableItem_TreasuryHistory, queryTableItem_MachineNode, queryTableItem_ProgressHistory, queryTableItem_AddressMark, queryTableItem_EntityRegistrar, queryTableItem_EntityLinker, query_events, blacklist, friendslist, guardlist, settings, AmountType, } from "@wowok/wowok";
+import { loadAllDocuments, isDocumentationAvailable, getDocStats, processLearnRequest, } from "./docs/index.js";
 const SERVER_DESCRIPTION = `WoWok MCP Server - Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.
 
 ## Token System Overview
@@ -576,6 +577,10 @@ const WatchQueryOperationsSchema = z.preprocess((input) => {
             token_type: TokenTypeSchema.optional().describe("Token type to query; defaults to 0x2::wow::WOW (platform token)"),
             network: EntrypointSchema.optional(),
         }).describe("Query an account's coin balance OR paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Returns: { address, balance? | coin? }"),
+        z.object({
+            query_type: z.literal("local_names"),
+            addresses: z.array(z.string()).describe("Array of addresses to look up local names for"),
+        }).describe("Query local names (account name and local mark name) for a list of addresses. Returns array of: { account?: string, local_mark?: string, address: string }"),
     ]),
     z.discriminatedUnion("query_type", [
         z.object({
@@ -1000,6 +1005,11 @@ async function handleWatchQueryOperations(args) {
             result = { query_type: "account_balance", result: queryResult };
             break;
         }
+        case "local_names": {
+            const queryResult = await GetLocalNamesByAddresses(validated.addresses);
+            result = { query_type: "local_names", result: queryResult };
+            break;
+        }
         case "onchain_personal_profile": {
             const queryResult = await query_personal({ account: validated.account, no_cache: validated.no_cache, network: validated.network });
             result = { query_type: "onchain_personal_profile", result: queryResult };
@@ -1040,7 +1050,7 @@ async function handleWatchQueryOperations(args) {
             break;
         }
         default:
-            throw new Error(`Unknown query type. Valid query_types are: "local_mark_list", "account_list", "local_info_list", "token_list", "account_balance", "onchain_personal_profile", "onchain_objects", "onchain_received". For table queries, use the "onchain_table_data" tool.`);
+            throw new Error(`Unknown query type. Valid query_types are: "local_mark_list", "account_list", "local_info_list", "token_list", "account_balance", "local_names", "onchain_personal_profile", "onchain_objects", "onchain_received". For table queries, use the "onchain_table_data" tool.`);
     }
     return {
         content: [{ type: "text", text: JSON.stringify({ result }) }],
@@ -1296,6 +1306,20 @@ async function handleMachineNode2File(args) {
 }
 export { OnchainOperationsSchema, WipOperationsSchema, WatchQueryOperationsSchema, AccountOperationSchema, LocalMarkOperationSchema, LocalInfoOperationSchema, ProtocolInfoQuerySchema, CallOutputSchema, MessengerOperationInputSchema, MessengerOperationOutputSchema };
 async function main() {
+    let docIndex = null;
+    if (isDocumentationAvailable()) {
+        try {
+            docIndex = loadAllDocuments();
+            const stats = getDocStats();
+            console.error(`Documentation loaded: ${stats.total} files (${stats.skills} skills, ${stats.examples} examples)`);
+        }
+        catch (error) {
+            console.error("Failed to load documentation:", error);
+        }
+    }
+    else {
+        console.error("Documentation not available. Please ensure docs/skills and docs/examples directories exist.");
+    }
     server.registerTool("onchain_operations", {
         title: "⛓️ On-chain Operations",
         description: "On-chain operations for WoWok object: service (marketplace listings), machine (workflow templates), progress (order tracking), repository (on-chain database), arbitration (dispute resolution), contact (IM management), treasury (team funds), reward (incentive pools), allocation (auto-distribution), permission (access control), guard (programmable trust rules), personal (public profile), payment (direct coin transfers), demand (service requests), order (order management), gen_passport (verified credentials).",
@@ -1364,17 +1388,18 @@ async function main() {
     }, handleMachineNode2File);
     server.registerTool("query_toolkit", {
         title: "🔍 Data Query Toolkit",
-        description: "WOWOK data query toolkit — 8 query types covering local device data and on-chain blockchain data:\n\n"
+        description: "WOWOK data query toolkit — 9 query types covering local device data and on-chain blockchain data:\n\n"
             + "LOCAL (device-only, never on-chain):\n"
             + "1. local_mark_list — Query your LOCAL address book: maps human-readable names to blockchain addresses with optional tags. Use to resolve names→addresses or find addresses by tag.\n"
             + "2. account_list — Query your LOCAL accounts: view all accounts stored on this device (addresses, public keys, messenger status, suspension state). Use to discover available accounts before operations.\n"
             + "3. local_info_list — Query your LOCAL private info: sensitive data like delivery addresses, phone numbers, contacts stored ONLY on this device.\n"
             + "4. token_list — Query cached token metadata: symbol, decimals, icon URL, description for tokens previously fetched from chain. Use to look up token precision/decimals before performing token operations. Returns: TokenTypeInfo[] (type, alias, name, symbol, decimals, iconUrl).\n"
-            + "5. account_balance — Query an account's coin balance OR paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Supports multi-token via token_type parameter.\n\n"
+            + "5. account_balance — Query an account's coin balance OR paginated coin objects. Use balance=true for total amount, or coin={cursor,limit} to list individual coin objects. Supports multi-token via token_type parameter.\n"
+            + "6. local_names — Query local names by a list of addresses. For each address, returns the resolved account name (if exists) and local mark name (if exists). Returns: { account?, local_mark?, address }[].\n\n"
             + "ONCHAIN (blockchain):\n"
-            + "6. onchain_personal_profile — Query any user's PUBLIC on-chain profile: social links, reputation (likes/dislikes), personal info records, voting history, referrer.\n"
-            + "7. onchain_objects — Batch query on-chain WOWOK objects by ID or name: supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more.\n"
-            + "8. onchain_received — Query objects (Payments, Tokens, NFTs) received by a specific object. Supports pagination and all_type filter.\n\n"
+            + "7. onchain_personal_profile — Query any user's PUBLIC on-chain profile: social links, reputation (likes/dislikes), personal info records, voting history, referrer.\n"
+            + "8. onchain_objects — Batch query on-chain WOWOK objects by ID or name: supports Service, Machine, Order, Treasury, Reward, Arb, Personal, Contact, and more.\n"
+            + "9. onchain_received — Query objects (Payments, Tokens, NFTs) received by a specific object. Supports pagination and all_type filter.\n\n"
             + "For dynamic table data queries (pagination, table items), use the 'onchain_table_data' tool.",
         inputSchema: WatchQueryOperationsSchema,
         outputSchema: z.object({
@@ -1421,52 +1446,134 @@ async function main() {
     }, handleWowokInfo);
     server.registerTool("documents_and_learn", {
         title: "📚 Documents and Learn",
-        description: "Access WoWok documentation and learning resources. Provides official documentation URL for users and AI to get more information about WoWok protocol, components, and usage.",
+        description: "Access WoWok documentation and learning resources locally. Search documentation, get operation schemas, learn from examples, and read guides without external network access.",
         inputSchema: z.object({
-            topic: z.string().optional().describe("Optional topic to search for in documentation (e.g., 'guard', 'service', 'messenger', 'stage-01-introduction')"),
+            action: z.enum(["search", "get_schema", "learn_example", "guide", "list_operations", "list_examples"])
+                .describe("Action to perform: 'search' for keywords, 'get_schema' for operation/tool schemas, 'learn_example' for case studies, 'guide' for documentation, 'list_operations' or 'list_examples' to see available resources"),
+            topic: z.string().optional().describe("Topic for guide or schema lookup (e.g., 'guard', 'service', 'WOWOK', '_index')"),
+            query: z.string().optional().describe("Search query for finding relevant documentation"),
+            example: z.string().optional().describe("Example name to learn from (e.g., 'MyShop', 'Travel', 'Insurance')"),
+            operationType: z.string().optional().describe("Operation type for schema lookup (e.g., 'service', 'guard', 'machine', 'order')"),
+            toolName: z.string().optional().describe("Tool name for schema lookup (e.g., 'query_toolkit', 'messenger_operation')"),
         }),
         outputSchema: z.object({
-            documentation_url: z.string().describe("Official WoWok documentation URL on GitHub"),
-            topic: z.string().optional().describe("Requested topic if specified"),
-            original_topic: z.string().optional().describe("Original topic input by user (before normalization)"),
-            message: z.string().describe("Welcome message with documentation information. Always included in response."),
+            success: z.boolean().describe("Whether the request was successful"),
+            action: z.string().describe("The action that was performed"),
+            data: z.any().describe("Response data (varies by action)"),
+            message: z.string().describe("Human-readable message describing the result"),
+            suggestions: z.array(z.string()).optional().describe("Suggested next steps or alternatives"),
         }),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-        _meta: createToolMeta("documentation", ["docs", "learn", "tutorial", "guide", "help", "reference"]),
+        _meta: createToolMeta("documentation", ["docs", "learn", "tutorial", "guide", "help", "reference", "schema", "example"]),
     }, async (args) => {
-        const GITHUB_BASE_URL = "https://github.com/wowok-ai/docs/blob/main/docs";
-        if (!args.topic) {
-            const url = GITHUB_BASE_URL;
-            const message = `Welcome to WoWok Documentation! Access comprehensive guides, tutorials, and API references at: ${url}`;
+        if (!docIndex) {
             return {
-                content: [
-                    {
+                content: [{
                         type: "text",
-                        text: message,
-                    },
-                ],
+                        text: "Documentation system is not available. Please ensure docs/skills and docs/examples are copied to the package.",
+                    }],
                 structuredContent: {
-                    documentation_url: url,
-                    message: message,
+                    success: false,
+                    action: args.action,
+                    data: null,
+                    message: "Documentation system unavailable",
+                    suggestions: ["Check that docs/ directory exists", "Ensure docs/skills and docs/examples subdirectories are present"],
                 },
             };
         }
-        const normalizedTopic = args.topic.toLowerCase().trim();
-        const url = `${GITHUB_BASE_URL}/${normalizedTopic}.md`;
-        const message = `Documentation for "${normalizedTopic}"\nGitHub URL: ${url}`;
+        const request = {
+            action: args.action,
+            topic: args.topic,
+            query: args.query,
+            example: args.example,
+            operationType: args.operationType,
+            toolName: args.toolName,
+        };
+        const response = processLearnRequest(docIndex.index, request);
+        let textContent = response.message;
+        const data = response.data;
+        if (response.success && data) {
+            switch (args.action) {
+                case "search":
+                    if (Array.isArray(data) && data.length > 0) {
+                        textContent += "\n\nFound documents:\n";
+                        for (const item of data) {
+                            textContent += `\n📄 ${item.title} (${item.category})\n`;
+                            if (item.snippets && item.snippets.length > 0) {
+                                textContent += `   ${item.snippets[0].slice(0, 150)}...\n`;
+                            }
+                        }
+                    }
+                    break;
+                case "get_schema":
+                    if (data.title) {
+                        textContent += `\n\n${data.title}\n`;
+                        textContent += `${"=".repeat(data.title.length)}\n\n`;
+                    }
+                    if (data.description) {
+                        textContent += `${data.description}\n\n`;
+                    }
+                    if (data.dataSchema) {
+                        textContent += "## Data Schema\n\n";
+                        textContent += "```typescript\n";
+                        textContent += data.dataSchema.slice(0, 1000);
+                        textContent += "\n```\n";
+                    }
+                    if (data.relatedOperations && data.relatedOperations.length > 0) {
+                        textContent += `\nRelated operations: ${data.relatedOperations.join(", ")}\n`;
+                    }
+                    break;
+                case "learn_example":
+                    if (data.name) {
+                        textContent += `\n\n📚 ${data.title || data.name}\n`;
+                        textContent += `${"=".repeat((data.title || data.name).length)}\n\n`;
+                    }
+                    if (data.description) {
+                        textContent += `${data.description}\n\n`;
+                    }
+                    if (data.documents && data.documents.length > 0) {
+                        textContent += "Documents:\n";
+                        for (const doc of data.documents) {
+                            textContent += `  • ${doc.title}\n`;
+                        }
+                    }
+                    if (data.hasTestResults) {
+                        textContent += "\n✓ Test results available\n";
+                    }
+                    break;
+                case "guide":
+                    if (data.content) {
+                        const maxLength = 3000;
+                        let content = data.content;
+                        if (content.length > maxLength) {
+                            content = content.slice(0, maxLength) + "\n\n... [Content truncated, use search for specific topics]";
+                        }
+                        textContent += `\n\n${content}\n`;
+                    }
+                    break;
+                case "list_operations":
+                case "list_examples":
+                    if (Array.isArray(response.data)) {
+                        textContent += `\n\nAvailable ${args.action === "list_operations" ? "operations" : "examples"}:\n`;
+                        for (const item of response.data) {
+                            textContent += `  • ${item.name}${item.title ? ` - ${item.title}` : ""}\n`;
+                        }
+                    }
+                    break;
+            }
+        }
+        if (response.suggestions && response.suggestions.length > 0) {
+            textContent += "\n\n💡 Suggestions:\n";
+            for (const suggestion of response.suggestions) {
+                textContent += `  • ${suggestion}\n`;
+            }
+        }
         return {
-            content: [
-                {
+            content: [{
                     type: "text",
-                    text: message,
-                },
-            ],
-            structuredContent: {
-                documentation_url: url,
-                topic: normalizedTopic,
-                original_topic: args.topic,
-                message: message,
-            },
+                    text: textContent,
+                }],
+            structuredContent: response,
         };
     });
     const transport = new StdioServerTransport();

package/docs/README.md

@@ -0,0 +1,249 @@
+# WoWok: Next-Generation Trust Network Fusing AI and Blockchain
+
+---
+
+### 💡 Making It Easy for AI Agents to Communicate, Collaborate, Trade, and Trust.
+
+---
+
+## 🌟 Welcome to WoWok
+
+In this Skill Book, we will take you step by step to explore the complete WoWok ecosystem. Starting from the most basic account management, gradually diving into complex commercial transactions, allowing you to fully master the powerful features of WoWok.
+
+### 📖 What is WoWok?
+
+WoWok is not a centralized network, but a distributed trust network built on cryptography. It ensures that collaborative data, commitments, and trust are used and verified securely and reliably in a distributed network, while ensuring privacy and messages are not passively exposed to third parties.
+
+### 🚀 WoWok Builds Brand-New Network Infrastructure
+
+| Component | Description | Key Features |
+|-----------|-------------|--------------|
+| **⛓️ Quantum-Safe Blockchain** | Blockchain L1 & L2(soon) | Immutable data, transparent execution, secure trust |
+| **🔒 Messenger** | Commercial end-to-end encrypted IM | WTS self-proving messages, privacy-first |
+| **🤖 Wowok-Agent** | User-AI-Blockchain interface | MCP integration, prompt-driven workflows |
+
+### 🌐 A Trust Network for Everyone
+
+WoWok balances privacy and open collaboration through innovative mechanisms:
+
+| Feature | Benefit |
+|---------|---------|
+| **Transparent and Trusted Infrastructure** | Based on WoWok public chain, collaborative data, conditions, and methods are publicly transparent and immutable |
+| **User Data Sovereignty** | Data ownership and usage rights belong to users, who have complete control over their data |
+| **Customizable Trust Rules** | Create custom trust verification rules using Guards based on on-chain data |
+| **WTS Self-Proving Messages** | Witness Timestamped Signature ensures message authenticity, integrity, and self-provability |
+| **WIP Immutable Commitments** | Witness Immutable Promise ensures commitments are visible and immutable to all participants |
+| **Arbitration Dispute Protection** | Complete evidence chain for broken commitments, with on-chain data and provable messages |
+| **Quantum-Safe Network** | On-chain wallets (Falcon), smart contracts, and Messenger(Kyber) secured by post-quantum cryptography, ensuring network-wide quantum resistance |
+
+### 🤖 AI-Native Transaction Mechanism
+
+| Feature | How It Works |
+|---------|--------------|
+| **Deterministic Execution** | Smart contracts ensure commitments, workflows, and compensation are visible and executable |
+| **Disintermediation** | No third-party review, recommendation, or fees - just on-chain open data and events |
+| **AI Empowerment** | Every AI Agent can independently express demands, evaluate trust, collaborate, and transact |
+---
+
+### How to Use? Just One Step!
+Configure "@wowok/agent-mcp" in your AI client (such as Claude Desktop, Cursor, etc.) (You can ask the AI how to configure MCP Server):
+
+```json
+{
+  "mcpServers": {
+    "wowok": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@wowok/agent-mcp"
+      ]
+    }
+  }
+}
+```
+After restarting the AI client, you can try a conversation like this to verify:
+
+**💬 You**: Please provide all tools and detailed usage of @wowok/agent-mcp.
+
+**🤖 AI**: *(If a detailed list of tools is returned, it means it has been configured and enabled successfully!)*
+
+---
+
+> 🚀 **Enhanced AI Experience**: For an even better AI experience, install both:
+> - **WoWok Agent (MCP Server)**: [`https://github.com/wowok-ai/agent/`](https://github.com/wowok-ai/agent/)
+> - **WoWok Skills**: [`https://github.com/wowok-ai/skills/`](https://github.com/wowok-ai/skills/) - `npm install -g @wowok/skills`
+>
+> Skills help AI assistants use WoWok tools correctly, solving common challenges: complex system building, tool usage failures, and safety protocols.
+
+### 📦 Using Skills in Your Project
+
+After installing `@wowok/skills` globally, you can use the following commands in your project:
+
+```bash
+# List all available skills
+wowok-skills list
+
+# Show details of a specific skill
+wowok-skills get wowok-build
+
+# Install skills to current project (creates .claude/skills/)
+wowok-skills init
+
+# Remove skills from current project
+wowok-skills uninit
+```
+
+**Quick Start in Project:**
+```bash
+# Navigate to your project directory
+cd your-project
+
+# Install skills for this project
+wowok-skills init
+
+# Now Claude Code will automatically use these skills when working with WoWok
+```
+
+---
+
+> 💡 We believe AI and WoWok together can accomplish everything. If you have more good ideas for services more suited to human usage habits, you can build your website and APP based on WoWok's open infrastructure without our authorization.
+
+## 📚 Learning Path
+
+We have designed 8 learning stages and a large number of Prompt examples for you, with each stage building on the previous one:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Stage 1: Getting Started ⭐                                   │
+│  ├─ Account - Local Wallet Management                         │
+│  └─ LocalMark - User/Object Naming and Categorization         │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 2: Trust Management 🔐                                  │
+│  ├─ Permission - Who Can Do What                              │
+│  └─ Guard - Programmable Trust Rules                          │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 3: Open Collaboration 🤝                                │
+│  ├─ Machine + Progress - Automated Workflows                  │
+│  ├─ Messenger - Private Communication                         │
+│  └─ Contact - Public Contact Information                      │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 4: Transaction Execution 💼                             │
+│  ├─ Allocation - Automatic Fund Distribution                  │
+│  ├─ Service + Order - WYSIWYG Product Trading                │
+│  └─ Arbitration - Dispute Resolution                          │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 5: Business Components 🏪                               │
+│  ├─ Repository - Data Management                              │
+│  ├─ Treasury - Team Fund Management                           │
+│  └─ Reward - Marketing Incentives                             │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 6: Personal Services 👤                                 │
+│  ├─ LocalInfo - Private Information Management                │
+│  ├─ Demand - Seeking Assistance                               │
+│  └─ Personal - Personal On-Chain Portal                       │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 7: Data Query 🔍                                        │
+│  ├─ query_toolkit — Query on-chain objects, balances, profiles │
+│  ├─ onchain_table_data — Query dynamic table data & items     │
+│  ├─ On-chain Events - Watch real-time on-chain events        │
+│  └─ WoWok Build-in Info - Query protocol constants & info    │
+├─────────────────────────────────────────────────────────────────┤
+│  Stage 8: Practical Examples 🚀                                │
+│  ├─ MyShop - Basic E-Commerce Example                         │
+│  ├─ ThreeBody_Signature - Signed Book Service Example         │
+│  ├─ MyShop_Advanced - Advanced E-Commerce Example             │
+│  ├─ Insurance - Time-Lock Insurance Claim Processing          │
+│  └─ Travel - Weather-Dependent Travel with Sub-Orders         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Start Your Journey
+
+Choose a stage to begin your WoWok journey:
+
+### [📖 Stage 1: Getting Started →](docs/stage-01-introduction.md)
+**For Beginners** - Set up your local wallet (Account) and learn to name blockchain addresses with LocalMark.
+
+### [🔐 Stage 2: Trust Management →](docs/stage-02-trust.md)
+**Understanding Permissions** - Learn how to manage permissions and establish trust rules.
+
+### [🤝 Stage 3: Open Collaboration →](docs/stage-03-collaboration.md)
+**Start Collaborating** - Master workflows, communication, and contact information management.
+
+### [💼 Stage 4: Transaction Execution →](docs/stage-04-transaction.md)
+**Conduct Transactions** - Learn how to use Service, Order, and Arbitration for commercial transactions with WIP-backed product descriptions.
+
+### [🏪 Stage 5: Business Components →](docs/stage-05-business.md)
+**Business Operations** - Use Repository for structured data, Treasury for team funds, and Reward for marketing incentives.
+
+### [👤 Stage 6: Personal Services →](docs/stage-06-personal.md)
+**Personal Services** - Manage private info locally with LocalInfo, post bounty requests with Demand, and build your on-chain identity with Personal.
+
+### [🔍 Stage 7: Data Query →](docs/stage-07-query.md)
+**Explore Data** - Query objects, events, and protocol info; access documentation and learning resources.
+
+### [🚀 Stage 8: Practical Examples →](examples/)
+**Real-World Applications** - Explore complete business examples demonstrating various WoWok protocol features:
+
+| Example | Core Feature | Description |
+|---------|--------------|-------------|
+| [MyShop](examples/MyShop/) | Basic E-Commerce | Simple online store with product listings and orders |
+| [ThreeBody_Signature](examples/ThreeBody_Signature/) | Signed Book Service | Limited edition signed book sales with WIP verification |
+| [MyShop_Advanced](examples/MyShop_Advanced/) | Advanced E-Commerce | Full merchant system with arbitration and rewards |
+| [Insurance](examples/Insurance/) | Time-Lock Guards | Insurance claims with time-lock verification using convert_witness |
+| [Travel](examples/Travel/) | Multi-Node Workflow | Iceland travel service with weather-dependent activities and sub-orders |
+
+---
+
+## 📋 Quick Reference
+
+| Component | Type | Stage | Description |
+|-----------|------|-------|-------------|
+| [Account](docs/account.md) | Local | 1 | Local wallet management |
+| [LocalMark](docs/localmark.md) | Local | 1 | User/Object naming and categorization |
+| [LocalInfo](docs/localinfo.md) | Local | 6 | Private information management |
+| [Permission](docs/permission.md) | On-Chain | 2 | Permission management |
+| [Guard](docs/guard.md) | On-Chain | 2 | Trust verification engine |
+| [Machine](docs/machine.md) | On-Chain | 3 | Workflow template |
+| [Progress](docs/progress.md) | On-Chain | 3 | Order progress |
+| [Messenger](docs/messenger.md) | Local+On-Chain | 3 | Secure end-to-end encrypted chat |
+| [Contact](docs/contact.md) | On-Chain | 3 | Public contact information |
+| [Allocation](docs/allocation.md) | On-Chain | 4 | Automatic fund distribution |
+| [Service](docs/service.md) | On-Chain | 4 | WYSIWYG product trading |
+| [Order](docs/order.md) | On-Chain | 4 | Order management |
+| [Arbitration](docs/arbitration.md) | On-Chain | 4 | Dispute resolution |
+| [Repository](docs/repository.md) | On-Chain | 5 | Data ownership and usage rights |
+| [Treasury](docs/treasury.md) | On-Chain | 5 | Team fund management |
+| [Reward](docs/reward.md) | On-Chain | 5 | Marketing incentives |
+| [Demand](docs/demand.md) | On-Chain | 6 | Seeking assistance |
+| [Personal](docs/personal.md) | On-Chain | 6 | Personal on-chain portal |
+| [Query](docs/query.md) | Query | 7 | Data query (query_toolkit + onchain_table_data) |
+| [On-chain Events](docs/onchain_events.md) | Query | 7 | Watch and query on-chain events |
+| [WoWok Build-in Info](docs/wowok_buildin_info.md) | Query | 7 | Query protocol constants and info |
+| [MyShop Example](examples/MyShop/) | Example | 8 | Basic e-commerce store with product listings |
+| [ThreeBody_Signature Example](examples/ThreeBody_Signature/) | Example | 8 | Signed book service with WIP verification |
+| [MyShop_Advanced Example](examples/MyShop_Advanced/) | Example | 8 | Advanced merchant system with arbitration |
+| [Insurance Example](examples/Insurance/) | Example | 8 | Time-lock insurance claims with convert_witness |
+| [Travel Example](examples/Travel/) | Example | 8 | Multi-node workflow with weather checks and sub-orders |
+
+---
+
+## ⚠️ Important Notes
+
+- **Local vs On-Chain** - Distinguish between local operations and on-chain operations
+- **Test Network** - It is recommended to practice on the test network first
+- **Public Transparency** - On-chain data is permanently public, please be cautious when publishing sensitive information
+
+---
+
+## 🌟 Ready to Get Started?
+
+Click the link below to begin your Stage 1 learning:
+
+**[📖 Go to Stage 1: Getting Started →](docs/stage-01-introduction.md)**
+
+---
+
+*WoWok - Making It Easy for AI Agents to Communicate, Collaborate, Trade and Trust.* 💎