lua-cli 3.0.0-alpha.9 → 3.0.0

package/template/QUICKSTART.md

@@ -1,325 +1,827 @@
-# Quick Start - 5 Minutes to Your First AI Skill
+# 🚀 Quick Start Guide
 
-Get up and running in 5 minutes!
+Welcome to your Lua AI Agent! This template provides a complete example of how to build powerful AI agents with custom tools, webhooks, scheduled jobs, and more.
 
----
-
-## ⚡ Super Quick Start
+## 📋 Table of Contents
 
-```bash
-# 1. Test the examples
-lua test
+- [Getting Started](#getting-started)
+- [Essential Commands](#essential-commands)
+- [Understanding LuaAgent](#understanding-luaagent)
+- [Project Structure](#project-structure)
+- [Next Steps](#next-steps)
 
-# 2. Start dev mode
-lua dev
+---
 
-# 3. Chat at http://localhost:3000
-# Try: "What's the weather in London?"
+## 🎯 Getting Started
 
-# 4. Customize src/index.ts
+Your project has been initialized with everything you need to build and deploy an AI agent!
 
-# 5. Deploy
-lua push
-lua deploy
-```
+### What's Included
 
-**Done!** 🎉
+✅ **Example Skills** - Pre-built tools for weather, user data, products, baskets, orders  
+✅ **Example Webhooks** - HTTP endpoints that receive external events  
+✅ **Example Jobs** - Scheduled tasks that run automatically  
+✅ **Example Processors** - Pre/post-process chat messages  
+✅ **LuaAgent Configuration** - Unified agent setup in `src/index.ts`  
 
 ---
 
-## 🧪 Step 1: Test Tools (1 minute)
+## 🛠️ Essential Commands
+
+### 1. Test Your Tools & Skills
+
+Test individual tools interactively before deploying:
 
 ```bash
 lua test
 ```
 
-**Try these:**
+**What it does:**
+- Lets you select a tool/webhook/job to test
+- Prompts for input values
+- Executes in a local sandbox
+- Shows the output
+
+**Perfect for:**
+- Testing tool logic before deployment
+- Debugging input/output schemas
+- Validating webhook handlers
+
+---
+
+### 2. Chat with Your Agent
+
+Have a conversation with your agent to see tools in action:
 
-1. **Select:** `get_weather`
-   - **Input:** city: `London`
-   - **Output:** Temperature, wind speed, conditions
+```bash
+lua chat
+```
 
-2. **Select:** `search_products`
-   - **Input:** query: `laptop`
-   - **Output:** Product list
+**Select environment:**
+- **🔧 Sandbox** - Test with your local code (not deployed yet)
+- **🚀 Production** - Chat with your deployed agent
 
-3. **Select:** `search_movies`
-   - **Input:** query: `thriller`
-   - **Output:** Movies with similarity scores
+**Try asking:**
+- "What's the weather in London?"
+- "Show me all products"
+- "Create a basket for user 123"
 
-**What you learned:** How tools work!
+**Pro tip:** Use sandbox mode to test changes before deploying!
 
 ---
 
-## 💬 Step 2: Chat Test (2 minutes)
+### 3. Deploy to Production
+
+When ready, push your skills to the server:
 
 ```bash
-lua dev
-```
+# Interactive deployment (recommended for first time)
+lua push
 
-**Browser opens at http://localhost:3000**
+# Or push all components at once
+lua push all --force
 
-**Try chatting:**
-- "What's the weather in Tokyo?"
-- "Show me your products"
-- "Create a movie called Inception directed by Christopher Nolan in 2010"
-- "Search for movies about dreams"
-- "Create a shopping basket and add a laptop"
+# Push and deploy to production in one command
+lua push all --force --auto-deploy
+```
 
-**What you learned:** How AI uses your tools!
+**What happens:**
+1. Compiles your code
+2. Bundles all tools/webhooks/jobs
+3. Pushes new version to server
+4. Updates `lua.skill.yaml` with new version
+5. Optionally deploys to production
 
 ---
 
-## 🎨 Step 3: Customize (2 minutes)
+## 🤖 Understanding LuaAgent
 
-Open **`src/index.ts`** and simplify:
+The `LuaAgent` is the **central configuration** for your AI agent. It's defined in `src/index.ts`:
 
 ```typescript
-import { LuaSkill } from "lua-cli";
-import GetWeatherTool from "./tools/GetWeatherTool";
-
-// Keep only what you need
-const mySkill = new LuaSkill({
-  name: "my-skill",
-  version: "1.0.0",
-  description: "My custom AI assistant",
-  context: "Use get_weather when users ask about weather.",
-  tools: [
-    new GetWeatherTool()
-  ]
+export const agent = new LuaAgent({
+  name: 'my-assistant',
+  persona: 'You are a helpful AI assistant...',
+  welcomeMessage: 'Hello! How can I help you today?',
+  skills: [generalSkill, userSkill, productSkill],
+  webhooks: [paymentWebhook],
+  jobs: [dailyCleanupJob],
+  preProcessors: [messageMatchingProcessor],
+  postProcessors: [responseModifierProcessor]
 });
 ```
 
-**Save the file** - dev mode auto-reloads!
+### Key Properties
 
-Chat again: "What's the weather in Paris?"
+#### `name` (string)
+- Your agent's identifier
+- Used for logging and organization
+- Example: `'customer-support-agent'`
 
-**What you learned:** How to customize!
+#### `persona` (string)
+- Defines your agent's personality and behavior
+- How the AI should respond to users
+- What tone and style to use
 
----
+**Example:**
+```typescript
+persona: `You are Emma, a friendly customer support agent for Acme Corp. 
+You're helpful, patient, and always prioritize customer satisfaction.
+Use a warm, professional tone and offer solutions proactively.`
+```
 
-## 🚀 What's Next?
+#### `welcomeMessage` (string, optional)
+- First message users see when starting a chat
+- Should be welcoming and set expectations
 
-### Option A: Learn by Exploring
+**Example:**
+```typescript
+welcomeMessage: "Hi! I'm Emma from Acme Corp. How can I assist you today?"
+```
 
-1. Read each tool in `src/tools/`
-2. Try modifying them
-3. Test your changes
-4. Build confidence
+#### `skills` (array of LuaSkill)
+- Collections of tools grouped by functionality
+- Each skill contains multiple related tools
+- Agents can use all tools from all skills
 
-**Time:** A few hours  
-**Best for:** Visual learners
+**Example:**
+```typescript
+skills: [
+  generalSkill,      // Weather, posts, calculations
+  productSkill,      // Product search, CRUD operations
+  basketSkill,       // Shopping cart management
+  orderSkill         // Order processing
+]
+```
 
----
+#### `webhooks` (array of LuaWebhook, optional)
+- HTTP endpoints that receive external events
+- Trigger actions based on external systems
+- Examples: Payment notifications, order updates
 
-### Option B: Build Something Specific
+**Example:**
+```typescript
+webhooks: [
+  paymentWebhook,    // Stripe payment confirmations
+  userEventWebhook   // External system notifications
+]
+```
 
-Pick a use case:
-- **Knowledge Base** → Use CustomDataTool.ts as template
-- **E-commerce** → Use ProductsTool.ts + BasketTool.ts
-- **Booking System** → Modify CustomDataTool.ts
-- **CRM** → Create customer management tools
+#### `jobs` (array of LuaJob, optional)
+- Scheduled tasks that run automatically
+- Can be one-time, recurring, or cron-based
+- Examples: Daily cleanups, health checks, reminders
 
-**Time:** 1-2 hours  
-**Best for:** Goal-oriented builders
+**Example:**
+```typescript
+jobs: [
+  dailyCleanupJob,          // Runs every day at midnight
+  abandonedBasketProcessor  // Checks for abandoned baskets hourly
+]
+```
 
----
+#### `preProcessors` (array of PreProcessor, optional)
+- Run **before** messages reach the agent
+- Modify, filter, or enhance incoming messages
+- Examples: Profanity filtering, intent detection, routing
 
-### Option C: Follow Complete Tutorial
+**Example:**
+```typescript
+preProcessors: [
+  messageMatchingProcessor  // Routes messages based on patterns
+]
+```
 
-Read **README.md** in this directory for:
-- Detailed tool explanations
-- Customization recipes
-- Multi-skill projects
-- Best practices
+#### `postProcessors` (array of PostProcessor, optional)
+- Run **after** the agent generates a response
+- Modify, enhance, or format responses
+- Examples: Add disclaimers, translate, format
 
-**Time:** 30 minutes reading, 1 hour building  
-**Best for:** Thorough learners
+**Example:**
+```typescript
+postProcessors: [
+  responseModifierProcessor  // Adds custom formatting
+]
+```
 
 ---
 
-## 🎯 Common First Tasks
+## 📁 Project Structure
 
-### Remove Unused Tools
+```
+your-project/
+├── src/
+│   ├── index.ts                 # 🎯 Main file - LuaAgent definition
+│   ├── skills/                  # Skills grouped by functionality
+│   │   ├── tools/              # Individual tool implementations
+│   │   │   ├── GetWeatherTool.ts
+│   │   │   ├── ProductsTool.ts
+│   │   │   └── BasketTool.ts
+│   │   ├── product.skill.ts    # Product skill (groups product tools)
+│   │   └── basket.skill.ts     # Basket skill (groups basket tools)
+│   ├── webhooks/               # HTTP webhook handlers
+│   │   ├── PaymentWebhook.ts
+│   │   └── UserEventWebhook.ts
+│   ├── jobs/                   # Scheduled background tasks
+│   │   ├── DailyCleanupJob.ts
+│   │   └── HealthCheckJob.ts
+│   ├── preprocessors/          # Message preprocessors
+│   │   └── messageMatching.ts
+│   ├── postprocessors/         # Response postprocessors
+│   │   └── modifyResponse.ts
+│   └── services/               # Shared utilities
+│       ├── ApiService.ts
+│       └── GetWeather.ts
+├── lua.skill.yaml              # 📝 Configuration & metadata
+├── package.json
+└── tsconfig.json
+```
 
-```bash
-# Delete what you don't need
-rm src/tools/BasketTool.ts
-rm src/tools/OrderTool.ts
+---
+
+## 🎓 Key Concepts
+
+### Skills vs Tools
 
-# Update src/index.ts to remove imports
+**Tools** are individual functions:
+```typescript
+export default class GetWeatherTool implements LuaTool {
+  name = "get_weather";
+  description = "Get weather for a city";
+  // ... implementation
+}
+```
+
+**Skills** group related tools:
+```typescript
+export const weatherSkill = new LuaSkill({
+  name: 'weather-skill',
+  description: 'Weather information tools',
+  context: 'Use these tools to get weather data',
+  tools: [getWeatherTool, forecastTool]
+});
+```
+
+**Why?** Skills help organize tools and provide context to the AI about when to use them.
+
+### The LuaAgent Advantage
+
+Instead of exporting individual skills, webhooks, and jobs separately, the **LuaAgent** provides a single, unified configuration:
+
+**❌ Old Way (Legacy):**
+```typescript
+export const skill1 = new LuaSkill({...});
+export const skill2 = new LuaSkill({...});
+export const webhook1 = new LuaWebhook({...});
+// Hard to manage, hard to see the big picture
 ```
 
+**✅ New Way (LuaAgent):**
+```typescript
+export const agent = new LuaAgent({
+  name: 'my-agent',
+  persona: '...',
+  skills: [skill1, skill2],
+  webhooks: [webhook1],
+  jobs: [job1]
+});
+// Everything in one place, easy to understand
+```
+
+**Benefits:**
+- 📦 Single source of truth
+- 🎯 Clear agent configuration
+- 🔄 Automatic YAML sync
+- 📝 Better organization
+
+---
+
+## 🧪 Development Workflow
+
+### Typical Development Flow
+
+1. **Create/Modify Tools**
+   ```bash
+   # Edit your tools in src/skills/tools/
+   vim src/skills/tools/MyNewTool.ts
+   ```
+
+2. **Test Locally**
+   ```bash
+   # Test the specific tool
+   lua test
+   ```
+
+3. **Chat Test (Sandbox)**
+   ```bash
+   # Chat with your agent using local code
+   lua chat
+   # Select: Sandbox
+   ```
+
+4. **Compile**
+   ```bash
+   # Bundle everything
+   lua compile
+   ```
+
+5. **Push to Server**
+   ```bash
+   # Upload new version
+   lua push
+   ```
+
+6. **Chat Test (Production)**
+   ```bash
+   # Chat with deployed agent
+   lua chat
+   # Select: Production
+   ```
+
 ---
 
-### Add Your Own Tool
+## 🚀 Quick Examples
+
+### Example 1: Adding a New Tool
+
+Create a new tool file:
 
-1. **Create** `src/tools/MyTool.ts`:
 ```typescript
-import { LuaTool } from "lua-cli";
+// src/skills/tools/GreetingTool.ts
+import { LuaTool } from "lua-cli/skill";
 import { z } from "zod";
 
-export default class MyTool implements LuaTool {
-  name = "my_tool";
-  description = "What it does";
-  inputSchema = z.object({ param: z.string() });
+export default class GreetingTool implements LuaTool {
+  name = "greet_user";
+  description = "Generate a personalized greeting";
+  
+  inputSchema = z.object({
+    name: z.string(),
+    language: z.enum(['en', 'es', 'fr']).optional()
+  });
 
-  async execute(input: any) {
-    return { result: "Hello " + input.param };
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const greetings = {
+      en: `Hello, ${input.name}!`,
+      es: `¡Hola, ${input.name}!`,
+      fr: `Bonjour, ${input.name}!`
+    };
+    
+    const lang = input.language || 'en';
+    return { greeting: greetings[lang] };
   }
 }
 ```
 
-2. **Add to** `src/index.ts`:
+Add it to your skill:
+
 ```typescript
-import MyTool from "./tools/MyTool";
+// src/skills/general.skill.ts
+import GreetingTool from './tools/GreetingTool';
 
-const skill = new LuaSkill({
-  tools: [new MyTool()]
+export const generalSkill = new LuaSkill({
+  name: 'general-skill',
+  description: 'General purpose utilities',
+  context: 'Use these for common tasks',
+  tools: [
+    new GetWeatherTool(),
+    new GreetingTool(),  // ✅ Add your new tool
+  ]
 });
 ```
 
-3. **Test:**
+Test it:
 ```bash
 lua test
-# Select "my_tool" → Enter param → See result
+# Select: greet_user
+# Input name: "Alice"
+# Input language: "es"
+# Output: { greeting: "¡Hola, Alice!" }
 ```
 
----
+### Example 2: Creating a Scheduled Job
 
-### Use External API
+```typescript
+// src/jobs/DailyReportJob.ts
+import { LuaJob, User } from "lua-cli";
 
-Example: Call a REST API
+export default new LuaJob({
+  name: "daily-report",
+  version: "1.0.0",
+  description: "Send daily summary to admin",
+  
+  schedule: {
+    type: "cron",
+    pattern: "0 9 * * *"  // Every day at 9 AM
+  },
+  
+  execute: async (job) => {
+    const user = await job.user();
+    
+    // Generate report
+    const report = `Daily Summary for ${new Date().toDateString()}`;
+    
+    // Send to user
+    await user.send([{
+      type: "text",
+      text: report
+    }]);
+    
+    return { success: true, sent: true };
+  }
+});
+```
 
+Add to LuaAgent:
 ```typescript
-async execute(input: any) {
-  const response = await fetch('https://api.example.com/data', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(input)
-  });
+import dailyReportJob from './jobs/DailyReportJob';
+
+export const agent = new LuaAgent({
+  // ...
+  jobs: [dailyReportJob]
+});
+```
+
+### Example 3: Creating a Webhook
+
+```typescript
+// src/webhooks/OrderWebhook.ts
+import { LuaWebhook, Orders } from "lua-cli";
+import { z } from "zod";
+
+export default new LuaWebhook({
+  name: "order-notification",
+  version: "1.0.0",
+  description: "Receive order updates from external systems",
   
-  const data = await response.json();
-  return data;
-}
+  bodySchema: z.object({
+    orderId: z.string(),
+    status: z.string(),
+    amount: z.number()
+  }),
+  
+  execute: async ({ body }) => {
+    // Update order in your system
+    await Orders.updateStatus(body.status, body.orderId);
+    
+    return {
+      status: 200,
+      body: { success: true, orderId: body.orderId }
+    };
+  }
+});
 ```
 
 ---
 
-### Store Data
+## 📚 Available APIs
 
-Example: Save user preferences
+Your tools and jobs have access to these powerful APIs:
 
+### User Data
 ```typescript
-import { Data } from "lua-cli";
+const user = await User.get();
+await user.update({ preferences: 'dark mode' });
+await user.send([{ type: "text", text: "Hello!" }]);
+```
 
-async execute(input: any) {
-  // Create
-  await Data.create('preferences', {
-    theme: input.theme,
-    language: input.language
-  });
-  
-  // Later: Get
-  const prefs = await Data.get('preferences');
+### Products
+```typescript
+const products = await Products.get();
+const product = await Products.create({ name: "Widget", price: 29.99 });
+await product.update({ price: 24.99 });
+```
+
+### Baskets
+```typescript
+const basket = await Baskets.create();
+await basket.addItem({ productId: "123", quantity: 2 });
+await basket.placeOrder();
+```
+
+### Orders
+```typescript
+const orders = await Orders.get();
+await Orders.updateStatus('confirmed', orderId);
+```
+
+### Custom Data
+```typescript
+const movies = await Data.get('movies');
+await Data.create('movies', { title: "Inception", year: 2010 });
+```
+
+### Jobs (Dynamic)
+```typescript
+const job = await Jobs.create({
+  name: "remind-user",
+  schedule: { type: "once", executeAt: new Date(Date.now() + 3600000) },
+  metadata: { message: "Time for your meeting!" },
+  execute: async (job) => {
+    const user = await job.user();
+    await user.send([{ type: "text", text: job.metadata.message }]);
+    return { success: true };
+  }
+});
+```
+
+---
+
+## 🔑 Key Features
+
+### Auto-Sync Between Code and YAML
+
+Your `lua.skill.yaml` and `LuaAgent` in `index.ts` stay synchronized automatically:
+
+**When you run `lua init`:**
+- ✅ Agent name, persona, and welcome message are added to both YAML and code
+
+**When you run `lua compile`:**
+- ✅ LuaAgent persona and welcome message sync to YAML
+
+**Why?** This ensures your configuration is always consistent!
+
+### Environment Variables
+
+Use `.env` for API keys and sensitive data:
+
+```bash
+# .env
+OPENAI_API_KEY=your-key-here
+STRIPE_SECRET_KEY=your-stripe-key
+PINECONE_API_KEY=your-pinecone-key
+LUA_API_KEY=your-lua-api-key  # Optional: for CI/CD
+```
+
+Access in your code:
+```typescript
+import { env } from "lua-cli/skill";
+
+const apiKey = env('OPENAI_API_KEY');
+```
+
+---
+
+## 📖 Common Patterns
+
+### Pattern 1: Tool with External API
+
+```typescript
+import { LuaTool } from "lua-cli/skill";
+import { z } from "zod";
+import axios from "axios";
+import { env } from "lua-cli/skill";
+
+export default class WeatherTool implements LuaTool {
+  name = "get_weather";
+  description = "Get current weather for a city";
   
-  return prefs;
+  inputSchema = z.object({
+    city: z.string()
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const apiKey = env('WEATHER_API_KEY');
+    
+    const response = await axios.get(`https://api.weather.com/current`, {
+      params: { city: input.city, apiKey }
+    });
+    
+    return {
+      temperature: response.data.temp,
+      condition: response.data.condition,
+      city: input.city
+    };
+  }
 }
 ```
 
----
+### Pattern 2: Tool that Creates a Job
 
-## 🎨 Template Features
+```typescript
+import { LuaTool, Jobs, JobInstance } from "lua-cli";
+import { z } from "zod";
 
-### 30+ Working Examples
+export default class ReminderTool implements LuaTool {
+  name = "set_reminder";
+  description = "Set a reminder for later";
+  
+  inputSchema = z.object({
+    message: z.string(),
+    delayMinutes: z.number()
+  });
 
-Every common pattern is demonstrated:
-- ✅ External API calls
-- ✅ Platform API usage
-- ✅ Vector search
-- ✅ CRUD operations
-- ✅ Multi-step workflows
-- ✅ Error handling
-- ✅ Input validation
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // Create a job that will notify the user later
+    const job = await Jobs.create({
+      name: `reminder-${Date.now()}`,
+      description: "User reminder",
+      metadata: {
+        message: input.message  // ✅ Pass data via metadata
+      },
+      schedule: {
+        type: "once",
+        executeAt: new Date(Date.now() + input.delayMinutes * 60000)
+      },
+      execute: async (jobInstance: JobInstance) => {
+        const user = await jobInstance.user();
+        const message = jobInstance.metadata.message;
+        
+        await user.send([{ 
+          type: "text", 
+          text: `⏰ Reminder: ${message}` 
+        }]);
+        
+        return { success: true };
+      }
+    });
+    
+    return { 
+      success: true, 
+      message: `Reminder set for ${input.delayMinutes} minutes from now`,
+      jobId: job.id 
+    };
+  }
+}
+```
 
-### All Platform APIs
+**Important:** Job execute functions must be self-contained. Use `metadata` to pass data!
 
-- ✅ User - User data management
-- ✅ Data - Custom data with search
-- ✅ Products - Product catalog
-- ✅ Baskets - Shopping carts
-- ✅ Orders - Order processing
+### Pattern 3: Webhook that Triggers Job
 
-### Production Ready
+```typescript
+import { LuaWebhook, Jobs } from "lua-cli";
+import { z } from "zod";
 
-- ✅ TypeScript configured
-- ✅ Type-safe
-- ✅ Error handling
-- ✅ Validation
-- ✅ Ready to deploy
+export default new LuaWebhook({
+  name: "order-received",
+  version: "1.0.0",
+  description: "Handle new order notifications",
+  
+  bodySchema: z.object({
+    orderId: z.string(),
+    userId: z.string()
+  }),
+  
+  execute: async ({ body }) => {
+    // Create a job to process the order in 5 minutes
+    await Jobs.create({
+      name: `process-order-${body.orderId}`,
+      metadata: { orderId: body.orderId },
+      schedule: {
+        type: "once",
+        executeAt: new Date(Date.now() + 300000)
+      },
+      execute: async (job) => {
+        // Process order logic here
+        return { success: true };
+      }
+    });
+    
+    return {
+      status: 200,
+      body: { received: true, orderId: body.orderId }
+    };
+  }
+});
+```
 
 ---
 
-## 🚨 Need Help?
+## 🎯 Next Steps
 
-### Quick Answers
+### 1. Customize Your Agent
+
+Edit `src/index.ts` and update:
+- Agent name
+- Persona (how your agent behaves)
+- Welcome message
+
+### 2. Explore Example Tools
+
+Look in `src/skills/tools/` to see:
+- `GetWeatherTool.ts` - External API integration
+- `ProductsTool.ts` - CRUD operations with Products API
+- `BasketTool.ts` - Shopping cart management
+- `GameScoreTrackerTool.ts` - Complex state management
+
+### 3. Test Everything
 
-**"How do I test?"**
 ```bash
-lua test  # Interactive testing
+# Test individual tools
+lua test
+
+# Chat with your agent
+lua chat
+
+# Compile and check for errors
+lua compile
 ```
 
-**"How do I see it work?"**
+### 4. Deploy
+
 ```bash
-lua dev  # Chat interface at http://localhost:3000
+# Push new version
+lua push
+
+# Or push everything at once
+lua push all --force --auto-deploy
 ```
 
-**"How do I deploy?"**
+### 5. Monitor & Manage
+
 ```bash
-lua push    # Upload
-lua deploy  # Go live
-```
+# View production status
+lua production
 
-**"Which tool should I start with?"**
-- Simple: `CreatePostTool.ts`
-- External API: `GetWeatherTool.ts`
-- Platform API: `UserDataTool.ts`
-- Complex: `BasketTool.ts`
+# Manage environment variables
+lua env production
+
+# Update persona
+lua persona production
+
+# View logs
+lua logs
+```
 
 ---
 
-### Documentation
+## 💡 Tips & Best Practices
+
+### Tool Design
+✅ **Clear names** - Use descriptive tool names like `get_weather`, not `weather`  
+✅ **Validate inputs** - Use Zod schemas to ensure data quality  
+✅ **Good descriptions** - Help the AI understand when to use your tool  
+✅ **Handle errors** - Return error messages instead of throwing  
+
+### Job Design
+✅ **Self-contained** - Jobs should not depend on parent scope variables  
+✅ **Use metadata** - Pass data through `metadata` field  
+✅ **Proper scheduling** - Choose appropriate schedule types (once, cron, interval)  
+✅ **Idempotent** - Jobs should be safe to run multiple times  
+
+### Webhook Design
+✅ **Validate inputs** - Use schemas for query, headers, and body  
+✅ **Return proper status** - Use HTTP status codes (200, 400, etc.)  
+✅ **Handle failures** - Return error responses gracefully  
+✅ **Security** - Validate signatures for production webhooks  
 
-- **README.md** (this directory) - Complete project guide
-- **TOOL_EXAMPLES.md** - Detailed tool explanations
-- **../API_REFERENCE.md** - Full API docs
-- **../CLI_REFERENCE.md** - All commands
-- **../GETTING_STARTED.md** - Complete tutorial
+### Agent Persona
+✅ **Be specific** - Define personality, tone, and behavior clearly  
+✅ **Set boundaries** - Explain what the agent can and cannot do  
+✅ **Give examples** - Show how the agent should respond  
+✅ **Update regularly** - Refine based on user interactions  
 
 ---
 
-## ✨ Pro Tips
+## 🆘 Need Help?
 
-1. **Start with `lua dev`** - See everything in action
-2. **Copy, don't write from scratch** - Modify examples
-3. **Test often** - `lua test` after every change
-4. **Read the code** - Examples are well-commented
-5. **Ask the AI** - Use dev mode to test edge cases
+### Commands
+```bash
+lua --help              # All available commands
+lua compile --help      # Compilation help
+lua push --help         # Deployment help
+lua test --help         # Testing help
+```
+
+### Common Issues
+
+**Q: Tool not showing up in agent?**
+- ✅ Make sure it's added to a skill
+- ✅ Make sure the skill is added to LuaAgent
+- ✅ Run `lua compile`
+
+**Q: Job execute function has undefined variables?**
+- ✅ Use `metadata` to pass data to the job
+- ✅ Job functions must be self-contained
+
+**Q: Changes not reflecting in production?**
+- ✅ Run `lua compile` first
+- ✅ Run `lua push` to upload
+- ✅ Select the right environment in `lua chat`
 
 ---
 
-## 🎯 5-Minute Challenge
+## 🎉 You're Ready!
+
+You now have everything you need to build powerful AI agents with Lua. Start by:
+
+1. Testing the example tools with `lua test`
+2. Chatting with your agent using `lua chat`
+3. Exploring the code in `src/skills/tools/`
+4. Customizing the agent persona in `src/index.ts`
+
+Happy building! 🚀
+
+---
 
-**Can you:**
-1. Run `lua dev`
-2. Chat: "What's the weather in your city?"
-3. Edit `GetWeatherTool.ts` to add a fun fact about the city
-4. Save and see it auto-reload
-5. Chat again and see your change
+## 📞 Support
 
-**If yes, you're ready to build!** 🚀
+- **Documentation:** https://docs.heylua.ai
+- **GitHub:** https://github.com/heylua/lua-cli
+- **Email:** support@heylua.ai
 
 ---
 
-**For more details, see README.md in this directory**
+*This template is part of lua-cli v3.0.0. For the latest updates, run `npm install -g lua-cli`*