lua-cli 2.2.8-alpha.2 → 2.3.0-alpha.1

package/template/README.md

@@ -1,477 +1,1056 @@
-# LuaSkill Template
+# Your Lua AI Skill Project
 
-This template provides a skeleton implementation demonstrating how to build LuaSkills with custom tools using the Lua CLI framework.
+Welcome to your Lua AI skill project! This project is ready to customize and deploy.
+
+---
+
+## 🎯 What You Have
+
+This project includes:
+- ✅ **7 Example Skills** - Pre-configured skill examples
+- ✅ **30+ Example Tools** - Working tool implementations
+- ✅ **All Platform APIs** - User, Products, Baskets, Orders, Custom Data
+- ✅ **TypeScript Setup** - Full type safety
+- ✅ **Ready to Deploy** - Just customize and go!
+
+---
 
 ## 🚀 Quick Start
 
-1. **Install the Lua CLI globally:**
-   ```bash
-   npm install -g lua-cli
-   ```
+```bash
+# 1. Test a tool locally
+npm run test
+# or
+lua test
+
+# 2. Start development mode (live reload + chat interface)
+npm run dev
+# or
+lua dev
 
-2. **Initialize a new LuaSkill project:**
-   ```bash
-   mkdir my-lua-skill
-   cd my-lua-skill
-   lua init
-   ```
+# 3. Push to server
+npm run push
+# or
+lua push
 
-3. **Compile your skill:**
-   ```bash
-   lua compile
-   ```
+# 4. Deploy to production
+lua deploy
+```
 
-4. **Test your tools:**
-   ```bash
-   lua test
-   ```
+**Your AI is now live!** 🎉
+
+---
 
 ## 📁 Project Structure
 
 ```
-my-lua-skill/
-├── tools/           # Your custom tools
-│   ├── GetWeatherTool.ts
-│   ├── GetUserDataTool.ts
-│   └── CreatePostTool.ts
-├── services/        # Shared services
-│   ├── ApiService.ts
-│   └── GetWeather.ts
-├── index.ts         # Main skill definition
-├── package.json     # Dependencies
-└── .lua/           # Generated files (auto-created)
-    ├── deploy.json  # Compiled skill data
-    └── *.js        # Bundled tool files
+your-project/
+├── src/
+│   ├── index.ts              # YOUR STARTING POINT - Define skills here
+│   └── tools/                # Tool implementations
+│       ├── GetWeatherTool.ts       # External API example
+│       ├── UserDataTool.ts         # User API example
+│       ├── ProductsTool.ts         # Products API (6 tools)
+│       ├── BasketTool.ts           # Baskets API (9 tools)
+│       ├── OrderTool.ts            # Orders API (4 tools)
+│       ├── CustomDataTool.ts       # Custom Data API (6 tools)
+│       ├── PaymentTool.ts          # Payment integration
+│       └── CreatePostTool.ts       # Simple example
+├── lua.skill.yaml            # Configuration (auto-managed)
+├── package.json              # Dependencies
+├── tsconfig.json             # TypeScript config
+├── .env                      # Environment variables (create this)
+└── README.md                 # This file
 ```
 
-## 🛠️ Creating Tools
+---
+
+## 🎓 Getting Started
 
-### Basic Tool Structure
+### Step 1: Understand the Template
 
-Every tool must implement the `LuaTool` interface:
+Open **`src/index.ts`** - this is where your skills are defined:
 
 ```typescript
-import { LuaTool } from "lua-cli/skill";
+// Example: General purpose skill
+const generalSkill = new LuaSkill({
+  name: "general-skill",
+  version: "0.0.2",
+  description: "Weather and utility tools",
+  context: "Use get_weather for weather info...",
+  tools: [
+    new GetWeatherTool(),
+    new CreatePostTool()
+  ]
+});
+```
+
+**You have 7 skills pre-configured:**
+1. `general-skill` - Weather and posts
+2. `user-data-skill` - User management
+3. `product-skill` - Product catalog
+4. `basket-skill` - Shopping carts
+5. `order-skill` - Order processing
+6. `custom-data-skill` - Custom data (movies example)
+7. `payment-skill` - Payment links
+
+---
+
+### Step 2: Test the Examples
+
+```bash
+lua test
+```
+
+**Try these tools:**
+- `get_weather` - Enter city: "London"
+- `search_products` - Enter query: "laptop"
+- `create_movie` - Enter title, director, year
+- `get_user_data` - No input needed
+
+---
+
+### Step 3: Start Dev Mode
+
+```bash
+lua dev
+```
+
+**Opens chat interface at http://localhost:3000**
+
+**Try chatting:**
+- "What's the weather in Tokyo?"
+- "Show me your products"
+- "Create a shopping basket"
+- "Add product XYZ to my basket"
+
+---
+
+### Step 4: Customize for Your Use Case
+
+#### Option A: Modify Existing Tools
+
+Edit `src/tools/GetWeatherTool.ts`:
+```typescript
+async execute(input: any) {
+  const weather = await this.getWeather(input.city);
+  
+  // Add your customization
+  return {
+    ...weather,
+    recommendation: this.getClothingAdvice(weather.temperature)
+  };
+}
+```
+
+#### Option B: Remove Unused Skills
+
+Clean up `src/index.ts`:
+```typescript
+// Remove skills you don't need
+// Keep only what's relevant to your use case
+
+import { LuaSkill } from "lua-cli";
+import GetWeatherTool from "./tools/GetWeatherTool";
+
+const mySkill = new LuaSkill({
+  name: "my-custom-skill",
+  version: "1.0.0",
+  description: "My specific use case",
+  context: "Clear instructions for the AI...",
+  tools: [
+    new GetWeatherTool()
+    // Add your tools
+  ]
+});
+```
+
+#### Option C: Create New Tools
+
+Create `src/tools/MyTool.ts`:
+```typescript
+import { LuaTool } from "lua-cli";
 import { z } from "zod";
 
-export default class MyTool implements LuaTool<z.ZodObject<any>, z.ZodObject<any>> {
+export default class MyTool implements LuaTool {
   name = "my_tool";
-  description = "Description of what this tool does";
+  description = "What my tool does";
   
   inputSchema = z.object({
-    // Define your input parameters
-    param1: z.string().describe("Description of param1"),
-    param2: z.number().describe("Description of param2")
-  });
-  
-  outputSchema = z.object({
-    // Define your output structure
-    result: z.string(),
-    success: z.boolean()
+    param: z.string()
   });
-  
+
   async execute(input: z.infer<typeof this.inputSchema>) {
-    // Your tool logic here
-    return {
-      result: "Tool executed successfully",
-      success: true
-    };
+    // Your logic here
+    return { success: true };
   }
 }
 ```
 
-### Tool Examples
+Add to `src/index.ts`:
+```typescript
+import MyTool from "./tools/MyTool";
+
+const mySkill = new LuaSkill({
+  tools: [new MyTool()]
+});
+```
+
+---
 
-#### 1. Simple Data Processing Tool
+## 🛠️ Tool Examples Explained
 
+### GetWeatherTool.ts
+**What it does:** Fetches weather for any city using Open-Meteo API (free, no key required)
+
+**Learn from this:**
+- External API integration
+- Error handling for API calls
+- Data transformation
+
+**Use it for:**
+- Weather information
+- Location-based services
+- External API patterns
+
+---
+
+### UserDataTool.ts
+**What it does:** Gets and updates user data (2 tools)
+
+**Learn from this:**
+- Using Platform APIs (`User`)
+- Simple CRUD operations
+- Data retrieval and updates
+
+**Use it for:**
+- User profile management
+- Preference storage
+- User-specific data
+
+---
+
+### ProductsTool.ts
+**What it does:** Complete product management (6 tools)
+
+**Learn from this:**
+- Full CRUD operations
+- Search functionality
+- Pagination handling
+- Platform API usage
+
+**Tools included:**
+- `search_products` - Search catalog
+- `get_all_products` - List with pagination
+- `create_product` - Add new products
+- `update_product` - Modify existing
+- `get_product_by_id` - Get specific product
+- `delete_product` - Remove products
+
+**Use it for:**
+- E-commerce catalogs
+- Inventory management
+- Product recommendations
+
+---
+
+### BasketTool.ts
+**What it does:** Shopping cart operations (9 tools)
+
+**Learn from this:**
+- Multi-step workflows
+- State management
+- Complex business logic
+
+**Tools included:**
+- `create_basket` - Start shopping
+- `get_baskets` - List carts
+- `add_to_basket` - Add items
+- `remove_from_basket` - Remove items
+- `clear_basket` - Empty cart
+- `update_basket_status` - Change status
+- `update_basket_metadata` - Add metadata
+- `checkout_basket` - Convert to order
+- `get_basket_by_id` - Get specific basket
+
+**Use it for:**
+- Shopping carts
+- Temporary storage
+- Multi-item collections
+
+---
+
+### OrderTool.ts
+**What it does:** Order creation and tracking (4 tools)
+
+**Learn from this:**
+- Order fulfillment flows
+- Status management
+- Basket-to-order conversion
+
+**Use it for:**
+- Order processing
+- Purchase completion
+- Order tracking
+
+---
+
+### CustomDataTool.ts
+**What it does:** Movie database with vector search (6 tools)
+
+**Learn from this:**
+- **Vector search** - Semantic similarity search
+- Custom data collections
+- Search indexing
+- CRUD on custom schemas
+
+**Tools included:**
+- `create_movie` - Add movie with search indexing
+- `get_movies` - List all movies
+- `get_movie_by_id` - Get specific movie
+- `update_movie` - Modify movie data
+- `search_movies` - **Semantic search** (find similar)
+- `delete_movie` - Remove movie
+
+**Use it for:**
+- Knowledge bases
+- Document search
+- FAQs
+- Any searchable content
+- Recommendation systems
+
+**Vector Search Example:**
 ```typescript
-import { LuaTool } from "lua-cli/skill";
-import { z } from "zod";
+// Create with search text
+await Data.create('movies', {
+  title: 'Inception',
+  director: 'Christopher Nolan'
+}, 'Inception Christopher Nolan sci-fi thriller dreams');
+
+// Search semantically
+const results = await Data.search('movies', 'mind-bending thriller', 10, 0.7);
+// Returns: Inception with high similarity score!
+```
+
+---
+
+### PaymentTool.ts
+**What it does:** Creates payment links (Stripe example)
+
+**Learn from this:**
+- Environment variables for API keys
+- External service integration
+- Payment processing
+
+**Use it for:**
+- Payment collection
+- Checkout flows
+- Subscription management
+
+---
+
+### CreatePostTool.ts
+**What it does:** Simple example tool
+
+**Learn from this:**
+- Basic tool structure
+- Minimal implementation
+- Good starting point
 
-export default class ProcessDataTool implements LuaTool<z.ZodObject<any>, z.ZodObject<any>> {
-  name = "process_data";
-  description = "Process and transform input data";
+---
+
+## 🎨 Customization Guide
+
+### Scenario 1: Keep Only What You Need
+
+**If you only need products:**
+
+1. **Update `src/index.ts`:**
+```typescript
+import { LuaSkill } from "lua-cli";
+import { SearchProductsTool, CreateProductTool } from "./tools/ProductsTool";
+
+const productSkill = new LuaSkill({
+  name: "product-catalog-skill",
+  version: "1.0.0",
+  description: "Product search and management",
+  context: "Use search_products to find items. Use create_product to add new items.",
+  tools: [
+    new SearchProductsTool(),
+    new CreateProductTool()
+  ]
+});
+```
+
+2. **Delete unused tool files:**
+```bash
+rm src/tools/BasketTool.ts
+rm src/tools/OrderTool.ts
+rm src/tools/CustomDataTool.ts
+# Keep only ProductsTool.ts
+```
+
+3. **Test:**
+```bash
+lua test
+```
+
+---
+
+### Scenario 2: Build a Restaurant Skill
+
+1. **Rename tools to match your domain:**
+
+Rename `CustomDataTool.ts` → `MenuTool.ts`
+
+2. **Update tool names and descriptions:**
+```typescript
+export class CreateMenuItemTool implements LuaTool {
+  name = "create_menu_item";
+  description = "Add a new item to the restaurant menu";
   
   inputSchema = z.object({
-    data: z.string().describe("Raw data to process"),
-    format: z.enum(["json", "xml", "csv"]).describe("Output format")
+    name: z.string(),
+    category: z.enum(['appetizers', 'mains', 'desserts', 'drinks']),
+    price: z.number(),
+    description: z.string()
   });
-  
-  outputSchema = z.object({
-    processedData: z.string(),
-    format: z.string(),
-    timestamp: z.string()
-  });
-  
-  async execute(input) {
-    // Process the data based on format
-    let processedData;
-    switch (input.format) {
-      case "json":
-        processedData = JSON.stringify({ data: input.data });
-        break;
-      case "xml":
-        processedData = `<data>${input.data}</data>`;
-        break;
-      case "csv":
-        processedData = `data\n"${input.data}"`;
-        break;
-    }
-    
-    return {
-      processedData,
-      format: input.format,
-      timestamp: new Date().toISOString()
-    };
+
+  async execute(input: any) {
+    const searchText = `${input.name} ${input.category} ${input.description}`;
+    return await Data.create('menu_items', input, searchText);
   }
 }
 ```
 
-#### 2. HTTP API Tool
+3. **Update skill context:**
+```typescript
+const restaurantSkill = new LuaSkill({
+  description: "Restaurant assistant for menu, orders, and reservations",
+  context: `
+    Help customers interact with the restaurant.
+    
+    - Use show_menu when asked about food or drinks
+    - Use create_order when taking orders (confirm items first)
+    - Use make_reservation for table bookings
+    
+    Always mention daily specials.
+    Confirm order details before submitting.
+  `,
+  tools: [new ShowMenuTool(), new CreateOrderTool()]
+});
+```
+
+---
+
+### Scenario 3: Build a CRM Skill
 
+1. **Create customer management tools:**
+
+Create `src/tools/CustomerTool.ts`:
 ```typescript
-import { LuaTool } from "lua-cli/skill";
+import { LuaTool, Data } from "lua-cli";
 import { z } from "zod";
-import axios from "axios";
 
-export default class ApiCallTool implements LuaTool<z.ZodObject<any>, z.ZodObject<any>> {
-  name = "api_call";
-  description = "Make HTTP API calls";
+export class CreateCustomerTool implements LuaTool {
+  name = "create_customer";
+  description = "Add a new customer to CRM";
   
   inputSchema = z.object({
-    url: z.string().url().describe("API endpoint URL"),
-    method: z.enum(["GET", "POST", "PUT", "DELETE"]).describe("HTTP method"),
-    data: z.any().optional().describe("Request body data"),
-    headers: z.record(z.string()).optional().describe("Custom headers")
-  });
-  
-  outputSchema = z.object({
-    status: z.number(),
-    data: z.any(),
-    success: z.boolean(),
-    error: z.string().optional()
+    name: z.string(),
+    email: z.string().email(),
+    company: z.string().optional(),
+    phone: z.string().optional()
   });
-  
-  async execute(input) {
-    try {
-      const response = await axios({
-        url: input.url,
-        method: input.method,
-        data: input.data,
-        headers: input.headers || {}
-      });
-      
-      return {
-        status: response.status,
-        data: response.data,
-        success: true
-      };
-    } catch (error: any) {
-      return {
-        status: error.response?.status || 0,
-        data: null,
-        success: false,
-        error: error.message
-      };
-    }
+
+  async execute(input: any) {
+    const searchText = `${input.name} ${input.email} ${input.company || ''}`;
+    
+    const customer = await Data.create('customers', {
+      ...input,
+      status: 'active',
+      createdAt: new Date().toISOString()
+    }, searchText);
+    
+    return {
+      customerId: customer.id,
+      message: `Customer ${input.name} added to CRM`
+    };
+  }
+}
+
+export class SearchCustomersTool implements LuaTool {
+  name = "search_customers";
+  description = "Search customers by name, email, or company";
+  inputSchema = z.object({ query: z.string() });
+
+  async execute(input: any) {
+    const results = await Data.search('customers', input.query, 10, 0.7);
+    
+    return {
+      customers: results.data.map(entry => ({
+        id: entry.id,
+        ...entry.data,
+        relevance: entry.score
+      }))
+    };
   }
 }
 ```
 
-#### 3. File Operations Tool
+2. **Create interaction tracking:**
 
 ```typescript
-import { LuaTool } from "lua-cli/skill";
-import { z } from "zod";
-import fs from "fs/promises";
-import path from "path";
-
-export default class FileTool implements LuaTool<z.ZodObject<any>, z.ZodObject<any>> {
-  name = "file_operations";
-  description = "Perform file system operations";
+export class LogInteractionTool implements LuaTool {
+  name = "log_interaction";
+  description = "Log customer interaction";
   
   inputSchema = z.object({
-    operation: z.enum(["read", "write", "list", "delete"]).describe("File operation to perform"),
-    path: z.string().describe("File or directory path"),
-    content: z.string().optional().describe("Content to write (for write operations)")
-  });
-  
-  outputSchema = z.object({
-    success: z.boolean(),
-    data: z.any().optional(),
-    error: z.string().optional()
+    customerId: z.string(),
+    type: z.enum(['call', 'email', 'meeting']),
+    notes: z.string()
   });
-  
-  async execute(input) {
-    try {
-      switch (input.operation) {
-        case "read":
-          const content = await fs.readFile(input.path, "utf8");
-          return { success: true, data: content };
-          
-        case "write":
-          await fs.writeFile(input.path, input.content || "");
-          return { success: true, data: "File written successfully" };
-          
-        case "list":
-          const files = await fs.readdir(input.path);
-          return { success: true, data: files };
-          
-        case "delete":
-          await fs.unlink(input.path);
-          return { success: true, data: "File deleted successfully" };
-          
-        default:
-          return { success: false, error: "Invalid operation" };
-      }
-    } catch (error: any) {
-      return { success: false, error: error.message };
-    }
+
+  async execute(input: any) {
+    await Data.create('interactions', {
+      customerId: input.customerId,
+      type: input.type,
+      notes: input.notes,
+      timestamp: new Date().toISOString()
+    }, `${input.type} ${input.notes}`);
+    
+    return { success: true };
   }
 }
 ```
 
-## 🔧 Creating Services
+---
 
-Services provide reusable functionality across multiple tools:
+## 🔧 Development Commands
 
-```typescript
-// services/DatabaseService.ts
-import axios from "axios";
+```bash
+# Install dependencies
+npm install
 
-export default class DatabaseService {
-  private baseUrl: string;
-  
-  constructor(baseUrl: string) {
-    this.baseUrl = baseUrl;
-  }
-  
-  async query(sql: string) {
-    const response = await axios.post(`${this.baseUrl}/query`, { sql });
-    return response.data;
-  }
-  
-  async insert(table: string, data: any) {
-    const response = await axios.post(`${this.baseUrl}/insert`, { table, data });
-    return response.data;
-  }
-}
+# Test tools interactively
+npm run test
+# or
+lua test
+
+# Start development mode
+npm run dev
+# or
+lua dev
+
+# Compile skill
+npm run compile
+# or
+lua compile
+
+# Push to server
+npm run push
+# or
+lua push
+
+# Deploy to production
+lua deploy
 ```
 
-## 📝 Main Skill Definition
+---
 
-Your `index.ts` file defines the skill and registers tools:
+## 📝 Configuration Files
 
-```typescript
-import { LuaSkill } from "lua-cli/skill";
-import ProcessDataTool from "./tools/ProcessDataTool";
-import ApiCallTool from "./tools/ApiCallTool";
-import FileTool from "./tools/FileTool";
-
-// Initialize skill
-const skill = new LuaSkill();
-
-// Add tools
-skill.addTool(new ProcessDataTool());
-skill.addTool(new ApiCallTool());
-skill.addTool(new FileTool());
-
-// Test cases (optional)
-const testCases = [
-  { tool: "process_data", data: "Hello World", format: "json" },
-  { tool: "api_call", url: "https://httpbin.org/get", method: "GET" },
-  { tool: "file_operations", operation: "list", path: "./" }
-];
-
-async function runTests() {
-  console.log("🧪 Running tool tests...\n");
-  
-  for (const [index, testCase] of testCases.entries()) {
-    try {
-      console.log(`Test ${index + 1}: ${testCase.tool}`);
-      const result = await skill.run(testCase);
-      console.log("✅ Success:", result);
-    } catch (error: any) {
-      console.log("❌ Error:", error.message);
-    }
-    console.log("");
-  }
-}
+### `lua.skill.yaml`
 
-// Run tests if this file is executed directly
-if (import.meta.url === `file://${process.argv[1]}`) {
-  runTests().catch(console.error);
-}
+Auto-managed configuration file. Contains:
+- Agent ID and organization ID
+- Skill IDs (auto-created during compilation)
+- Optional environment variables
+
+```yaml
+agent:
+  agentId: agent_abc123
+  orgId: org_xyz789
+
+skills:
+  - name: my-skill
+    version: 1.0.0
+    skillId: skill_xyz789  # Auto-created
 ```
 
-## 🎯 Best Practices
+**Don't manually edit `skillId`** - it's auto-managed!
 
-### 1. Input Validation
-Always use Zod schemas for robust input validation:
+---
 
-```typescript
-inputSchema = z.object({
-  email: z.string().email().describe("Valid email address"),
-  age: z.number().min(0).max(120).describe("Age between 0 and 120"),
-  tags: z.array(z.string()).optional().describe("Optional array of tags")
-});
+### `.env` File
+
+Create `.env` for environment variables:
+
+```bash
+# External API Keys
+STRIPE_API_KEY=sk_test_abc123
+SENDGRID_API_KEY=SG.xyz789
+OPENAI_API_KEY=sk-abc123
+
+# Configuration
+API_BASE_URL=https://api.example.com
+ENABLE_DEBUG=false
 ```
 
-### 2. Error Handling
-Provide meaningful error messages:
+**Remember:** Add `.env` to `.gitignore`!
 
-```typescript
-async execute(input) {
-  try {
-    // Your logic here
-    return { success: true, data: result };
-  } catch (error: any) {
-    return {
-      success: false,
-      error: error.message,
-      timestamp: new Date().toISOString()
-    };
+---
+
+### `package.json`
+
+Contains your dependencies and scripts:
+
+```json
+{
+  "name": "your-skill-name",
+  "version": "1.0.0",
+  "scripts": {
+    "test": "lua test",
+    "dev": "lua dev",
+    "compile": "lua compile",
+    "push": "lua push"
+  },
+  "dependencies": {
+    "lua-cli": "^2.0.0",
+    "zod": "^3.0.0"
   }
 }
 ```
 
-### 3. Async Operations
-Use async/await for better error handling:
+---
 
-```typescript
-async execute(input) {
-  const result = await someAsyncOperation(input);
-  return result;
-}
+## 🎯 Next Steps
+
+### 1. Explore the Examples
+
+**Try each tool:**
+```bash
+lua test
+```
+
+- Test `get_weather` - See external API calls
+- Test `search_products` - See platform API usage
+- Test `search_movies` - See vector search
+- Test `create_basket` → `add_to_basket` → `checkout_basket` - See workflows
+
+---
+
+### 2. Understand the Code
+
+**Read the tool files** in `src/tools/`:
+- Start with simple ones (`GetWeatherTool.ts`, `CreatePostTool.ts`)
+- Then explore complex ones (`BasketTool.ts`, `ProductsTool.ts`)
+- Study vector search (`CustomDataTool.ts`)
+
+**Key files to understand:**
+- `src/index.ts` - How skills are structured
+- `src/tools/ProductsTool.ts` - Complete CRUD pattern
+- `src/tools/CustomDataTool.ts` - Vector search pattern
+- `src/tools/BasketTool.ts` - Multi-step workflow pattern
+
+---
+
+### 3. Make It Yours
+
+**Choose your approach:**
+
+#### A. Modify Examples
+Keep examples, change them to your domain:
+- Movies → Your data type
+- Products → Your catalog
+- Weather → Your external API
+
+#### B. Start Fresh
+Delete examples, create new tools:
+```bash
+rm src/tools/*.ts
+touch src/tools/MyFirstTool.ts
+```
+
+#### C. Mix and Match
+Keep useful examples, add custom tools:
+- Keep: `UserDataTool.ts` (always useful)
+- Keep: `CustomDataTool.ts` (for knowledge base)
+- Remove: `BasketTool.ts` (if not e-commerce)
+- Add: Your custom tools
+
+---
+
+### 4. Deploy
+
+```bash
+# Test thoroughly
+lua test
+lua dev
+
+# Push to server
+lua push
+
+# Deploy to production
+lua deploy
+```
+
+---
+
+## 📚 Documentation
+
+### In This Project
+- **README.md** - This file (project overview)
+- **QUICKSTART.md** - 5-minute start guide
+- **TOOL_EXAMPLES.md** - Detailed tool explanations
+
+### Lua CLI Documentation
+- **Getting Started** - Complete tutorial
+- **API Reference** - All platform APIs
+- **CLI Reference** - All commands
+- **Template Guide** - This template explained
+
+**Access via:**
+```bash
+# In your node_modules
+ls node_modules/lua-cli/*.md
+
+# Or online
+https://docs.lua.ai
 ```
 
-### 4. Service Reuse
-Extract common functionality into services:
+---
+
+## 💡 Tips & Tricks
+
+### Tip 1: Start with Dev Mode
+
+```bash
+lua dev
+```
+
+**Why?**
+- Instant feedback
+- Chat testing
+- Live reload
+- See what the AI actually does
+
+---
+
+### Tip 2: Use Vector Search
 
+For any searchable content:
 ```typescript
-// In your tool
-import DatabaseService from "../services/DatabaseService";
+// When creating
+await Data.create('items', data, searchableText);
 
-export default class UserTool {
-  private dbService = new DatabaseService("http://localhost:3000");
+// When searching
+const results = await Data.search('items', query, 10, 0.7);
+```
+
+**Great for:**
+- FAQs
+- Documentation
+- Product descriptions
+- Customer notes
+
+---
+
+### Tip 3: Write Good Context
+
+The `context` field is critical - it guides the AI:
+
+**✅ Good:**
+```typescript
+context: `
+  This skill helps users find and purchase products.
   
-  async execute(input) {
-    const users = await this.dbService.query("SELECT * FROM users");
-    return { users };
-  }
-}
+  - Use search_products when users describe what they want
+  - Use create_basket to start a new shopping session
+  - Use add_to_basket when they want to buy something
+  - Use checkout_basket to complete the purchase
+  
+  Always confirm items and total before checkout.
+  Mention shipping options during checkout.
+`
 ```
 
-## 📦 Dependencies
+**❌ Bad:**
+```typescript
+context: "Product and shopping tools"
+```
 
-Add external dependencies to your `package.json`:
+---
 
-```json
-{
-  "dependencies": {
-    "axios": "^1.6.0",
-    "zod": "^3.22.0"
-  }
-}
+### Tip 4: Test with Real Scenarios
+
+Don't just test with perfect inputs:
+
+```bash
+lua dev
 ```
 
-The Lua CLI will automatically bundle these dependencies when you run `lua compile`.
+**Try:**
+- ✅ "What's the weather?" (missing city - should prompt)
+- ✅ "Add laptop to cart" (need basket ID - should create)
+- ✅ "XYZ" (nonsense - should handle gracefully)
+
+---
 
-## 🧪 Testing
+### Tip 5: Use Environment Variables
 
-### Interactive Testing
+**Never hardcode secrets:**
+
+```typescript
+// ❌ Bad
+const apiKey = 'sk_abc123';
+
+// ✅ Good
+import { env } from 'lua-cli';
+const apiKey = env('STRIPE_API_KEY');
+```
+
+Create `.env`:
 ```bash
-lua test
+STRIPE_API_KEY=your_key_here
 ```
 
-### Programmatic Testing
+---
+
+## 🎨 Customization Recipes
+
+### Recipe 1: Simple Weather Skill
+
 ```typescript
-const result = await skill.run({
-  tool: "my_tool",
-  param1: "value1",
-  param2: 42
+// src/index.ts
+import { LuaSkill } from "lua-cli";
+import GetWeatherTool from "./tools/GetWeatherTool";
+
+const weatherSkill = new LuaSkill({
+  name: "weather-skill",
+  version: "1.0.0",
+  description: "Provides weather information worldwide",
+  context: "Use get_weather when users ask about weather or temperature. Always include the city name.",
+  tools: [new GetWeatherTool()]
 });
-console.log(result);
 ```
 
-## 🚀 Deployment
+**Deploy:**
+```bash
+lua test  # Test it
+lua push  # Upload
+lua deploy # Go live
+```
+
+---
+
+### Recipe 2: Knowledge Base Skill
+
+Use CustomDataTool.ts as template:
+
+1. Rename collections: `movies` → `articles`
+2. Update fields: title, director → title, content, category
+3. Update descriptions to match your domain
+4. Update skill context
+
+**Result:** Searchable knowledge base!
+
+---
+
+### Recipe 3: E-commerce Skill
+
+Keep: `ProductsTool.ts`, `BasketTool.ts`, `OrderTool.ts`
+
+Remove: Everything else
+
+**Result:** Complete shopping experience!
+
+---
+
+## 🔍 Understanding Multi-Skill Projects
+
+This template has **7 skills** in one project:
+
+**Why multiple skills?**
+- Different domains (products vs orders)
+- Different deployment schedules
+- Logical organization
+- Easier to manage
+
+**How it works:**
+- Each skill gets its own `skillId` in `lua.skill.yaml`
+- All skills deploy together with `lua push`
+- All skills available to your agent
+- AI chooses right skill automatically
+
+**You can:**
+- Keep all 7 (if relevant)
+- Merge into 1 (simpler)
+- Create your own grouping
+
+---
+
+## 📊 Tool Inventory
+
+### Included Tools (30 total)
+
+| Category | Count | Examples |
+|----------|-------|----------|
+| **Weather** | 1 | get_weather |
+| **User Data** | 2 | get_user_data, update_user_data |
+| **Products** | 6 | search, create, update, get, delete, get_by_id |
+| **Baskets** | 9 | create, add_item, remove, clear, checkout, etc. |
+| **Orders** | 4 | create, update_status, get, get_by_id |
+| **Custom Data** | 6 | create, search, update, delete (movies example) |
+| **Payment** | 1 | create_payment_link |
+| **Posts** | 1 | create_post |
+
+**Total: 30 working examples** covering all major use cases!
+
+---
+
+## 🚨 Common Mistakes to Avoid
+
+### ❌ Mistake 1: Hardcoding API Keys
+```typescript
+const apiKey = 'sk_abc123';  // DON'T DO THIS
+```
+
+✅ **Fix:** Use environment variables
+```typescript
+import { env } from 'lua-cli';
+const apiKey = env('API_KEY');
+```
 
-Once your skill is ready:
+---
+
+### ❌ Mistake 2: Unclear Tool Names
+```typescript
+name = "tool1"  // Unclear
+name = "do_stuff"  // Too generic
+```
 
-1. **Compile:**
-   ```bash
-   lua compile
-   ```
+✅ **Fix:** Be specific
+```typescript
+name = "search_products"
+name = "create_order"
+name = "get_user_profile"
+```
 
-2. **Deploy:**
-   ```bash
-   lua deploy
-   ```
+---
 
-The compiled skill data will be in `.lua/deploy.json` and can be used with the Lua platform.
+### ❌ Mistake 3: Weak Descriptions
+```typescript
+description = "Gets data"  // Too vague
+```
 
-## 📚 API Reference
+✅ **Fix:** Be descriptive
+```typescript
+description = "Searches product catalog by name, category, or description"
+```
 
-### LuaSkill Class
+---
 
+### ❌ Mistake 4: Missing Error Handling
 ```typescript
-class LuaSkill {
-  constructor()
-  addTool<TInput, TOutput>(tool: LuaTool<TInput, TOutput>): void
-  async run(input: Record<string, any>): Promise<any>
+async execute(input: any) {
+  const result = await api.call(input);
+  return result;  // What if it fails?
 }
 ```
 
-### LuaTool Interface
-
+✅ **Fix:** Handle errors
 ```typescript
-interface LuaTool<TInput extends ZodType, TOutput extends ZodType> {
-  name: string;
-  description: string;
-  inputSchema: TInput;
-  outputSchema: TOutput;
-  execute(input: z.infer<TInput>): Promise<z.infer<TOutput>>;
+async execute(input: any) {
+  try {
+    const result = await api.call(input);
+    if (!result.success) {
+      throw new Error(result.error || 'API call failed');
+    }
+    return result.data;
+  } catch (error) {
+    throw new Error(`Failed to fetch data: ${error.message}`);
+  }
 }
 ```
 
-## 🔍 Troubleshooting
+---
+
+## 🎓 Learning Path
+
+### Week 1: Learn by Testing
+- ✅ Run `lua test` daily
+- ✅ Try every example tool
+- ✅ Understand inputs and outputs
+- ✅ Read the tool code
+
+### Week 2: Modify Examples
+- ✅ Change descriptions
+- ✅ Add new input fields
+- ✅ Modify return values
+- ✅ Test your changes
+
+### Week 3: Build Your Own
+- ✅ Create 1-2 custom tools
+- ✅ Remove unused examples
+- ✅ Update skill context
+- ✅ Deploy to production
+
+---
+
+## 🔗 Resources
+
+### Documentation
+- See markdown files in `node_modules/lua-cli/`
+- Visit https://docs.lua.ai
+- Check CLI help: `lua --help`
 
-### Common Issues
+### Examples
+- All tools in `src/tools/` are working examples
+- Copy, modify, learn!
 
-1. **"Tool not found" error:**
-   - Ensure the tool name matches exactly
-   - Check that the tool is added to the skill
+### Community
+- GitHub: https://github.com/lua-ai/lua-cli
+- Issues: Report bugs or ask questions
+- Email: support@lua.ai
 
-2. **Input validation errors:**
-   - Verify your Zod schema matches the input structure
-   - Check required vs optional fields
+---
 
-3. **Bundling errors:**
-   - Ensure all dependencies are in `package.json`
-   - Check import paths are correct
+## ✅ Checklist Before Deploying
 
-4. **Runtime errors:**
-   - Use try/catch blocks in your execute methods
-   - Check that all required globals are available
+- [ ] Removed unused tools and skills
+- [ ] Updated skill names and descriptions
+- [ ] Wrote clear context for AI
+- [ ] Tested all tools with `lua test`
+- [ ] Tested conversationally with `lua dev`
+- [ ] No hardcoded secrets (use `.env`)
+- [ ] Updated version number
+- [ ] Reviewed error messages
+- [ ] Checked tool names (no spaces!)
 
-### Debug Tips
+---
 
-- Use `console.log` for debugging (output appears in test mode)
-- Test individual tools before adding to the skill
-- Validate schemas with Zod's `.parse()` method
-- Check the generated `.lua/deploy.json` for compilation issues
+## 🎉 You're Ready!
 
-## 📖 Examples
+This template gives you:
+- ✅ **30 working tools** to learn from
+- ✅ **All API patterns** demonstrated
+- ✅ **Production-ready** structure
+- ✅ **Easy to customize** for your needs
 
-See the `tools/` directory for complete working examples:
-- `GetWeatherTool.ts` - Simple API call
-- `GetUserDataTool.ts` - Complex service integration
-- `CreatePostTool.ts` - POST request with data
+**Next steps:**
+1. Test the examples: `lua test`
+2. Chat with the AI: `lua dev`
+3. Make it yours: Edit tools and skills
+4. Deploy: `lua push && lua deploy`
 
-## 🤝 Contributing
+**Go build something amazing!** 🚀
 
-Found a bug or want to add a feature? Check out our [contributing guidelines](../../CONTRIBUTING.md).
+---
 
-## 📄 License
+**Quick Links:**
+- 📘 [Quick Start](QUICKSTART.md) - 5-minute guide
+- 🔧 [Tool Examples](TOOL_EXAMPLES.md) - Detailed tool docs
+- 💻 [CLI Commands](../CLI_REFERENCE.md) - Command reference
+- 📚 [API Docs](../API_REFERENCE.md) - Complete API reference
 
-This template is part of the Lua CLI framework. See the main [LICENSE](../../LICENSE) file for details.