lua-cli 3.0.0-alpha.9 → 3.0.1

package/template/README.md

@@ -1,1084 +1,955 @@
-# Your Lua AI Skill Project
+# 🤖 Lua AI Agent Template
 
-Welcome to your Lua AI skill project! This project is ready to customize and deploy.
+Welcome to your Lua AI Agent! This is a fully-featured template to help you build, test, and deploy intelligent AI agents with custom tools, webhooks, scheduled jobs, and message processors.
 
----
-
-## 🎯 What You Have
+## 🎯 What You've Got
 
-This project includes:
-- ✅ **LuaAgent** - New simplified agent configuration (RECOMMENDED!)
-- ✅ **7 Example Skills** - Pre-configured skill examples
-- ✅ **30+ Example Tools** - Working tool implementations
-- ✅ **2 Webhook Examples** - HTTP endpoints for external integrations
-- ✅ **4 Job Examples** - Scheduled tasks (cron, interval, one-time)
-- ✅ **Smart Basket Example** - Dynamic job creation from tools
-- ✅ **All Platform APIs** - User, Products, Baskets, Orders, Custom Data, Webhooks, Jobs
-- ✅ **TypeScript Setup** - Full type safety
-- ✅ **Ready to Deploy** - Just customize and go!
+This template includes **everything you need** to create a production-ready AI agent:
 
-> **NEW!** Check out `AGENT_CONFIGURATION.md` to learn about the simplified `LuaAgent` approach.
-> It's easier and cleaner than the legacy approach!
+- ✅ **LuaAgent Configuration** - Unified agent setup with persona and welcome message
+- ✅ **Example Skills & Tools** - 30+ pre-built tools demonstrating best practices
+- ✅ **Webhooks** - HTTP endpoints for external integrations
+- ✅ **Scheduled Jobs** - Automated background tasks
+- ✅ **Message Processors** - Pre/post-process conversations
+- ✅ **Type Safety** - Full TypeScript support with Zod validation
+- ✅ **Testing Suite** - Local testing before deployment
+- ✅ **CI/CD Ready** - Batch deployment commands
 
 ---
 
 ## 🚀 Quick Start
 
+**New to Lua?** Start here:
+
 ```bash
-# 1. Test a tool locally
-npm run test
-# or
+# 1. Test your tools locally
 lua test
 
-# 2. Start development mode (live reload + chat interface)
-npm run dev
-# or
-lua dev
-
-# 3. Push to server
-npm run push
-# or
-lua push
+# 2. Chat with your agent (sandbox mode)
+lua chat
 
-# 4. Deploy to production
-lua deploy
+# 3. Deploy to production
+lua push all --force --auto-deploy
 ```
 
-**Your AI is now live!** 🎉
-
----
-
-## 📁 Project Structure
-
-```
-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
-```
+👉 **[Read the Full Quick Start Guide →](QUICKSTART.md)**
 
 ---
 
-## 🎓 Getting Started
+## 📦 What's Inside
 
-### Step 1: Choose Your Configuration Style
+### Core Files
 
-**Option A: LuaAgent (Recommended for new projects)**
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | **Main file** - LuaAgent configuration |
+| `lua.skill.yaml` | Agent metadata and component registry |
+| `.env` | Environment variables (API keys, secrets) |
 
-The simplified approach - define everything in one place:
-
-```typescript
-import { LuaAgent, LuaSkill } from 'lua-cli';
+### Directory Structure
 
-export const agent = new LuaAgent({
-  name: 'my-assistant',
-  persona: 'You are a helpful e-commerce assistant...',
-  welcomeMessage: 'Hello! How can I help you today?',
-  skills: [weatherSkill, productSkill, basketSkill],
-  webhooks: [userWebhook],
-  jobs: [healthCheckJob]
-});
+```
+src/
+├── index.ts                    # 🎯 LuaAgent - Your agent's configuration
+├── skills/                     # Tools grouped by functionality
+│   ├── tools/                 # Individual tool implementations
+│   │   ├── GetWeatherTool.ts  # Example: External API integration
+│   │   ├── ProductsTool.ts    # Example: CRUD operations
+│   │   ├── BasketTool.ts      # Example: Shopping cart
+│   │   └── SmartBasketTool.ts # Example: Complex tool with state
+│   ├── product.skill.ts       # Skill that groups product tools
+│   └── basket.skill.ts        # Skill that groups basket tools
+├── webhooks/                   # HTTP endpoints
+│   ├── PaymentWebhook.ts      # Example: Payment notifications
+│   └── UserEventWebhook.ts    # Example: External events
+├── jobs/                       # Scheduled tasks
+│   ├── DailyCleanupJob.ts     # Example: Recurring cleanup
+│   └── HealthCheckJob.ts      # Example: Monitoring job
+├── preprocessors/              # Before-message processing
+│   └── messageMatching.ts     # Example: Route messages
+└── postprocessors/             # After-response processing
+    └── modifyResponse.ts      # Example: Format responses
 ```
 
-See `src/index-agent-example.ts` and `AGENT_CONFIGURATION.md` for details.
+---
 
-**Option B: Individual Components (Legacy)**
+## 🤖 Your Agent at a Glance
 
-Open **`src/index.ts`** - this is where your skills are defined:
+Your agent is configured in `src/index.ts`:
 
 ```typescript
-// 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()
+export const agent = new LuaAgent({
+  name: 'your-agent-name',
+  persona: 'Your agent personality and behavior...',
+  welcomeMessage: 'First message users see',
+  
+  skills: [
+    generalSkill,      // Weather, posts, utils
+    userSkill,         // User data management
+    productSkill,      // Product operations
+    basketSkill,       // Shopping cart
+    orderSkill,        // Order processing
+    customDataSkill,   // Custom data storage
+    paymentSkill       // Payment processing
+  ],
+  
+  webhooks: [
+    // paymentWebhook,  // Uncomment to enable
+  ],
+  
+  jobs: [
+    // dailyCleanupJob,  // Uncomment to enable
+  ],
+  
+  preProcessors: [
+    // messageMatchingProcessor,  // Uncomment to enable
+  ],
+  
+  postProcessors: [
+    // responseModifierProcessor,  // Uncomment to enable
   ]
 });
 ```
 
-**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
+## 🛠️ Example Tools Included
 
-```bash
-lua test
-```
+### General Purpose
+- **get_weather** - Fetch weather data from external API
+- **create_post** - Create posts with external service
+- **create_inline_job** - Demonstrates dynamic job creation
+
+### User Management
+- **get_user_data** - Retrieve user information
+- **update_user_data** - Update user profiles
 
-**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
+### E-commerce
+- **search_products** - Search product catalog
+- **create_product** - Add new products
+- **update_product** - Modify existing products
+- **delete_product** - Remove products
+- **create_basket** - Create shopping cart
+- **add_item_to_basket** - Add products to cart
+- **checkout_basket** - Complete purchase
+- **create_order** - Place orders
+- **update_order_status** - Track order progress
+
+### Advanced Examples
+- **smart_basket_tool** - Complex state management with AI-powered recommendations
+- **game_score_tracker** - Multi-player game tracking with leaderboards
+- **create_payment_link** - Stripe integration for payments
 
 ---
 
-### Step 3: Start Dev Mode
+## 🎓 Learning Path
 
-```bash
-lua dev
-```
+### Beginner
+1. ✅ Read [QUICKSTART.md](QUICKSTART.md)
+2. ✅ Run `lua test` to try existing tools
+3. ✅ Run `lua chat` to interact with your agent
+4. ✅ Modify the agent persona in `src/index.ts`
 
-**Opens chat interface at http://localhost:3000**
+### Intermediate
+1. ✅ Create your first custom tool
+2. ✅ Group tools into a skill
+3. ✅ Add the skill to your LuaAgent
+4. ✅ Test and deploy with `lua push`
 
-**Try chatting:**
-- "What's the weather in Tokyo?"
-- "Show me your products"
-- "Create a shopping basket"
-- "Add product XYZ to my basket"
+### Advanced
+1. ✅ Create webhooks for external integrations
+2. ✅ Schedule jobs for automated tasks
+3. ✅ Add preprocessors to route/filter messages
+4. ✅ Use postprocessors to format responses
+5. ✅ Implement complex tools with external APIs
 
 ---
 
-### Step 4: Customize for Your Use Case
+## 🔑 Key Features
 
-#### Option A: Modify Existing Tools
-
-Edit `src/tools/GetWeatherTool.ts`:
+### Intelligent Tools
+Your agent can use tools to accomplish tasks:
 ```typescript
-async execute(input: any) {
-  const weather = await this.getWeather(input.city);
-  
-  // Add your customization
-  return {
-    ...weather,
-    recommendation: this.getClothingAdvice(weather.temperature)
-  };
-}
+// User: "What's the weather in Tokyo?"
+// Agent uses: get_weather tool
+// Response: "It's 72°F and sunny in Tokyo"
 ```
 
-#### Option B: Remove Unused Skills
-
-Clean up `src/index.ts`:
+### External Integrations
+Connect to any API:
 ```typescript
-// Remove skills you don't need
-// Keep only what's relevant to your use case
+// Stripe, OpenAI, Pinecone, custom APIs
+const result = await axios.post(API_URL, data);
+```
 
-import { LuaSkill } from "lua-cli";
-import GetWeatherTool from "./tools/GetWeatherTool";
+### User Context
+Access user data in every tool:
+```typescript
+const user = await User.get();
+const preferences = user.preferences;
+```
 
-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
-  ]
+### Persistent Storage
+Store data across conversations:
+```typescript
+await Data.create('notes', { 
+  title: "Meeting Notes",
+  content: "..." 
 });
 ```
 
-#### Option C: Create New Tools
-
-Create `src/tools/MyTool.ts`:
+### Scheduled Automation
+Run tasks on a schedule:
 ```typescript
-import { LuaTool } from "lua-cli";
-import { z } from "zod";
-
-export default class MyTool implements LuaTool {
-  name = "my_tool";
-  description = "What my tool does";
-  
-  inputSchema = z.object({
-    param: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Your logic here
-    return { success: true };
-  }
+// Every day at 9 AM
+schedule: {
+  type: "cron",
+  pattern: "0 9 * * *"
 }
 ```
 
-Add to `src/index.ts`:
+### Real-time Events
+Receive HTTP webhooks:
 ```typescript
-import MyTool from "./tools/MyTool";
-
-const mySkill = new LuaSkill({
-  tools: [new MyTool()]
-});
+// POST /webhook/{webhookId}
+// Process payment confirmations, order updates, etc.
 ```
 
 ---
 
-## 🛠️ Tool Examples Explained
+## 📊 Development Workflow
 
-### 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)
+```mermaid
+graph LR
+    A[Write Code] --> B[lua test]
+    B --> C[lua chat sandbox]
+    C --> D{Works?}
+    D -->|No| A
+    D -->|Yes| E[lua compile]
+    E --> F[lua push]
+    F --> G[lua chat production]
+    G --> H{Deploy?}
+    H -->|Yes| I[lua deploy]
+    H -->|No| A
+```
 
-**Learn from this:**
-- Using Platform APIs (`User`)
-- Simple CRUD operations
-- Data retrieval and updates
+### Commands Reference
 
-**Use it for:**
-- User profile management
-- Preference storage
-- User-specific data
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `lua test` | Test individual tools | During development |
+| `lua chat` | Interactive testing | Validate tool interactions |
+| `lua compile` | Bundle your code | Before pushing |
+| `lua push` | Upload to server | Ready to deploy |
+| `lua deploy` | Publish to production | Make live for users |
+| `lua push all --force` | Batch push all | CI/CD pipelines |
 
 ---
 
-### ProductsTool.ts
-**What it does:** Complete product management (6 tools)
-
-**Learn from this:**
-- Full CRUD operations
-- Search functionality
-- Pagination handling
-- Platform API usage
+## 🔒 Environment Variables
 
-**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
+Store sensitive data in `.env`:
 
-**Use it for:**
-- E-commerce catalogs
-- Inventory management
-- Product recommendations
-
----
+```bash
+# Copy from example
+cp env.example .env
 
-### BasketTool.ts
-**What it does:** Shopping cart operations (9 tools)
+# Add your API keys
+OPENAI_API_KEY=sk-...
+STRIPE_SECRET_KEY=sk_live_...
+PINECONE_API_KEY=...
 
-**Learn from this:**
-- Multi-step workflows
-- State management
-- Complex business logic
+# Optional: For CI/CD
+LUA_API_KEY=your-lua-api-key
+```
 
-**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
+**Priority:**
+1. System keychain (most secure)
+2. `LUA_API_KEY` environment variable
+3. `.env` file
 
 ---
 
-### OrderTool.ts
-**What it does:** Order creation and tracking (4 tools)
-
-**Learn from this:**
-- Order fulfillment flows
-- Status management
-- Basket-to-order conversion
+## 🎨 Customization Guide
 
-**Use it for:**
-- Order processing
-- Purchase completion
-- Order tracking
+### 1. Update Agent Identity
 
----
+Edit `src/index.ts`:
 
-### 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
-// 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!
+export const agent = new LuaAgent({
+  name: 'my-customer-support-bot',  // ✏️ Change this
+  
+  persona: `You are Sarah, a friendly customer support agent...`,  // ✏️ Customize
+  
+  welcomeMessage: 'Hi! I\'m Sarah. How can I help you today?',  // ✏️ Personalize
+  
+  // ...
+});
 ```
 
----
+### 2. Add Your Own Tool
 
-### PaymentTool.ts
-**What it does:** Creates payment links (Stripe example)
+Create `src/skills/tools/MyTool.ts`:
 
-**Learn from this:**
-- Environment variables for API keys
-- External service integration
-- Payment processing
+```typescript
+import { LuaTool } from "lua-cli/skill";
+import { z } from "zod";
 
-**Use it for:**
-- Payment collection
-- Checkout flows
-- Subscription management
+export default class MyTool implements LuaTool {
+  name = "my_tool";
+  description = "What this tool does";
+  
+  inputSchema = z.object({
+    param: z.string()
+  });
 
----
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // Your logic here
+    return { result: "success" };
+  }
+}
+```
 
-### CreatePostTool.ts
-**What it does:** Simple example tool
+Add to a skill in `src/index.ts`:
 
-**Learn from this:**
-- Basic tool structure
-- Minimal implementation
-- Good starting point
+```typescript
+import MyTool from './skills/tools/MyTool';
 
----
+const mySkill = new LuaSkill({
+  name: 'my-skill',
+  description: 'My custom skill',
+  context: 'Use these tools for...',
+  tools: [new MyTool()]
+});
 
-## 🎨 Customization Guide
+export const agent = new LuaAgent({
+  // ...
+  skills: [...existingSkills, mySkill],
+});
+```
 
-### Scenario 1: Keep Only What You Need
+### 3. Configure Webhooks
 
-**If you only need products:**
+Uncomment in `src/index.ts`:
 
-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()
-  ]
+import paymentWebhook from './webhooks/PaymentWebhook';
+
+export const agent = new LuaAgent({
+  // ...
+  webhooks: [paymentWebhook],  // ✅ Enabled
 });
 ```
 
-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
+Get your webhook URL after deployment:
 ```
-
-3. **Test:**
-```bash
-lua test
+https://webhook.heylua.ai/{agentId}/{webhookId}
 ```
 
----
-
-### Scenario 2: Build a Restaurant Skill
-
-1. **Rename tools to match your domain:**
+### 4. Schedule Jobs
 
-Rename `CustomDataTool.ts` → `MenuTool.ts`
+Uncomment in `src/index.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({
-    name: z.string(),
-    category: z.enum(['appetizers', 'mains', 'desserts', 'drinks']),
-    price: z.number(),
-    description: z.string()
-  });
-
-  async execute(input: any) {
-    const searchText = `${input.name} ${input.category} ${input.description}`;
-    return await Data.create('menu_items', input, searchText);
-  }
-}
-```
+import dailyCleanupJob from './jobs/DailyCleanupJob';
 
-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()]
+export const agent = new LuaAgent({
+  // ...
+  jobs: [dailyCleanupJob],  // ✅ Enabled
 });
 ```
 
 ---
 
-### Scenario 3: Build a CRM Skill
+## 📚 Documentation
 
-1. **Create customer management tools:**
+### Comprehensive Guides
+- **[Quick Start Guide](QUICKSTART.md)** - Step-by-step tutorial
+- **[Example Skills](src/skills/)** - Browse working examples
+- **[Example Webhooks](src/webhooks/)** - Webhook patterns
+- **[Example Jobs](src/jobs/)** - Job scheduling examples
 
-Create `src/tools/CustomerTool.ts`:
-```typescript
-import { LuaTool, Data } from "lua-cli";
-import { z } from "zod";
-
-export class CreateCustomerTool implements LuaTool {
-  name = "create_customer";
-  description = "Add a new customer to CRM";
-  
-  inputSchema = z.object({
-    name: z.string(),
-    email: z.string().email(),
-    company: z.string().optional(),
-    phone: z.string().optional()
-  });
+### Official Documentation
+- **Lua Docs:** https://docs.heylua.ai
+- **CLI Reference:** https://github.com/heylua/lua-cli
+- **Community:** https://community.heylua.ai
 
-  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
-      }))
-    };
-  }
-}
-```
+## 🧪 Testing Strategy
 
-2. **Create interaction tracking:**
+### Local Testing (Recommended)
 
-```typescript
-export class LogInteractionTool implements LuaTool {
-  name = "log_interaction";
-  description = "Log customer interaction";
-  
-  inputSchema = z.object({
-    customerId: z.string(),
-    type: z.enum(['call', 'email', 'meeting']),
-    notes: z.string()
-  });
+```bash
+# Test individual tools
+lua test
 
-  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 };
-  }
-}
+# Interactive chat testing
+lua chat
+# Select: Sandbox
 ```
 
----
+**Why sandbox?**
+- ✅ Uses your local code (not deployed)
+- ✅ Safe for experimentation
+- ✅ Instant feedback
+- ✅ No production impact
 
-## 🔧 Development Commands
+### Production Testing
 
 ```bash
-# Install dependencies
-npm install
+lua chat
+# Select: Production
+```
 
-# Test tools interactively
-npm run test
-# or
-lua test
+**When to use:**
+- ✅ After deploying
+- ✅ Validate production behavior
+- ✅ Test with real data
 
-# Start development mode
-npm run dev
-# or
-lua dev
+---
 
-# Compile skill
-npm run compile
-# or
-lua compile
+## 🚀 Deployment Options
 
-# Push to server
-npm run push
-# or
-lua push
+### Option 1: Interactive (Recommended for First Time)
 
-# Deploy to production
-lua deploy
+```bash
+lua push
+# Select component type
+# Confirm version
+# Choose whether to deploy
 ```
 
----
-
-## 📝 Configuration Files
+**Best for:**
+- Learning the deployment process
+- Reviewing changes before deploying
+- Fine-grained control
 
-### `lua.skill.yaml`
+### Option 2: Batch Deployment (CI/CD)
 
-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
+```bash
+lua push all --force --auto-deploy
 ```
 
-**Don't manually edit `skillId`** - it's auto-managed!
+**What happens:**
+1. Compiles all code
+2. Auto-bumps patch versions
+3. Pushes all skills, webhooks, jobs, processors
+4. Deploys everything to production
+
+**Best for:**
+- CI/CD pipelines
+- Batch updates
+- Production deployments
 
 ---
 
-### `.env` File
+## 💡 Pro Tips
 
-Create `.env` for environment variables:
+### Development
+- ✅ Use `lua test` frequently during development
+- ✅ Test in sandbox before deploying
+- ✅ Keep tools small and focused (single responsibility)
+- ✅ Use TypeScript for better error catching
 
-```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
-```
+### Tools
+- ✅ Validate all inputs with Zod schemas
+- ✅ Return structured objects (not just strings)
+- ✅ Handle errors gracefully
+- ✅ Use descriptive names and descriptions (the AI reads these!)
 
-**Remember:** Add `.env` to `.gitignore`!
+### Jobs
+- ✅ Always pass data via `metadata` field
+- ✅ Make execute functions self-contained
+- ✅ Use appropriate schedule types (once, cron, interval)
+- ✅ Test job logic in regular tools first
 
----
+### Webhooks
+- ✅ Validate signatures in production
+- ✅ Return proper HTTP status codes
+- ✅ Handle retries and idempotency
+- ✅ Test with tools like Postman first
 
-### `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"
-  }
-}
-```
+### Agent Persona
+- ✅ Be specific about personality and tone
+- ✅ Define what the agent can/cannot do
+- ✅ Give examples of good responses
+- ✅ Update based on user feedback
 
 ---
 
-## 🎯 Next Steps
+## 🔄 Keeping Your Agent Updated
 
-### 1. Explore the Examples
+### When You Make Changes
 
-**Try each tool:**
 ```bash
+# 1. Test your changes
 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. Compile
+lua compile
 
----
+# 3. Push new version
+lua push
 
-### 2. Understand the Code
+# 4. Deploy when ready
+lua deploy
+```
 
-**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`)
+### Sync Your Configuration
 
-**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
+The CLI automatically keeps your `lua.skill.yaml` and `LuaAgent` in sync:
+
+- **Run `lua init`** → Syncs agent name, persona, welcomeMessage to both files
+- **Run `lua compile`** → Syncs LuaAgent changes back to YAML
+- **Manual edit YAML** → Re-run `lua compile` to rebuild
 
 ---
 
-### 3. Make It Yours
+## 🎨 Example Use Cases
 
-**Choose your approach:**
+### Customer Support Agent
+```typescript
+persona: `You are Alex, a patient and knowledgeable customer support agent.
+You help customers with orders, returns, and product questions.
+Always be empathetic and solution-oriented.`
 
-#### A. Modify Examples
-Keep examples, change them to your domain:
-- Movies → Your data type
-- Products → Your catalog
-- Weather → Your external API
+skills: [productSkill, orderSkill, basketSkill]
+```
 
-#### B. Start Fresh
-Delete examples, create new tools:
-```bash
-rm src/tools/*.ts
-touch src/tools/MyFirstTool.ts
+### E-commerce Assistant
+```typescript
+persona: `You are Sophia, an enthusiastic shopping assistant.
+You help customers find products, make recommendations, and complete purchases.
+Use a friendly, upbeat tone and be proactive with suggestions.`
+
+skills: [productSkill, basketSkill, paymentSkill]
 ```
 
-#### 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
+### Data Analysis Agent
+```typescript
+persona: `You are DataBot, an analytical AI assistant.
+You help users query data, generate reports, and visualize insights.
+Be precise, data-driven, and thorough in your analysis.`
+
+skills: [customDataSkill, analyticsSkill, reportSkill]
+```
 
 ---
 
-### 4. Deploy
+## 🔐 Security Best Practices
 
-```bash
-# Test thoroughly
-lua test
-lua dev
+### API Keys
+- ✅ Never commit `.env` file to version control
+- ✅ Use `.env.example` as a template
+- ✅ Rotate API keys regularly
+- ✅ Use environment-specific keys (sandbox vs production)
 
-# Push to server
-lua push
+### Webhooks
+- ✅ Validate webhook signatures in production
+- ✅ Use HTTPS endpoints only
+- ✅ Rate limit webhook handlers
+- ✅ Log all webhook events
 
-# Deploy to production
-lua deploy
-```
+### User Data
+- ✅ Only store necessary data
+- ✅ Encrypt sensitive information
+- ✅ Respect user privacy preferences
+- ✅ Implement data deletion on request
 
 ---
 
-## 📚 Documentation
-
-### In This Project
-- **README.md** - This file (project overview)
-- **QUICKSTART.md** - 5-minute start guide
-- **TOOL_EXAMPLES.md** - Detailed tool explanations
+## 🐛 Troubleshooting
 
-### Lua CLI Documentation
-- **Getting Started** - Complete tutorial
-- **API Reference** - All platform APIs
-- **CLI Reference** - All commands
-- **Template Guide** - This template explained
+### Common Issues
 
-**Access via:**
+**"Tool not found by agent"**
 ```bash
-# In your node_modules
-ls node_modules/lua-cli/*.md
-
-# Or online
-https://docs.heylua.ai
+# Make sure tool is in a skill, skill is in LuaAgent
+lua compile  # Rebuilds everything
 ```
 
----
+**"Cannot find module '../services/ApiService'"**
+```bash
+# Make sure all dependencies are installed
+npm install
+```
 
-## 💡 Tips & Tricks
+**"Job execute function: ReferenceError: input is not defined"**
+```typescript
+// ❌ Wrong: Accessing parent scope
+execute: async (job) => {
+  const message = input.message;  // Error!
+}
 
-### Tip 1: Start with Dev Mode
+// ✅ Correct: Use metadata
+metadata: { message: input.message },
+execute: async (job) => {
+  const message = job.metadata.message;  // Works!
+}
+```
 
+**"Version not found when deploying"**
 ```bash
-lua dev
+# Server needs time to process. Wait 10 seconds, then:
+lua deploy
 ```
 
-**Why?**
-- Instant feedback
-- Chat testing
-- Live reload
-- See what the AI actually does
-
 ---
 
-### Tip 2: Use Vector Search
+## 📈 Scaling Your Agent
 
-For any searchable content:
-```typescript
-// When creating
-await Data.create('items', data, searchableText);
+### Add More Skills
 
-// When searching
-const results = await Data.search('items', query, 10, 0.7);
-```
+As your agent grows, organize tools into skills:
 
-**Great for:**
-- FAQs
-- Documentation
-- Product descriptions
-- Customer notes
-
----
+```typescript
+// src/skills/analytics.skill.ts
+export const analyticsSkill = new LuaSkill({
+  name: 'analytics-skill',
+  description: 'Data analytics and reporting',
+  context: 'Use these tools for data analysis',
+  tools: [
+    new GenerateReportTool(),
+    new ExportDataTool(),
+    new VisualizeTool()
+  ]
+});
+```
 
-### Tip 3: Write Good Context
+### Add Background Processing
 
-The `context` field is critical - it guides the AI:
+Use jobs for heavy or scheduled work:
 
-**✅ Good:**
 ```typescript
-context: `
-  This skill helps users find and purchase products.
-  
-  - 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.
-`
+// Instead of making users wait
+// Create a job that processes in background
+const job = await Jobs.create({
+  name: 'process-large-file',
+  metadata: { fileId: input.fileId },
+  schedule: { type: "once", executeAt: new Date() },
+  execute: async (job) => {
+    // Process file
+    // Notify user when done
+  }
+});
 ```
 
-**❌ Bad:**
+### Add External Integrations
+
+Use webhooks to receive events:
+
 ```typescript
-context: "Product and shopping tools"
+// Receive events from Stripe, Shopify, etc.
+export default new LuaWebhook({
+  name: "shopify-order",
+  execute: async ({ body }) => {
+    // Process Shopify order
+    // Update your system
+    // Notify customer
+  }
+});
 ```
 
 ---
 
-### Tip 4: Test with Real Scenarios
+## 🔧 Advanced Configuration
 
-Don't just test with perfect inputs:
+### Multiple Environments
 
 ```bash
-lua dev
+# Sandbox (testing)
+lua chat  # Select Sandbox
+lua env sandbox
+
+# Production (live users)
+lua chat  # Select Production
+lua env production
 ```
 
-**Try:**
-- ✅ "What's the weather?" (missing city - should prompt)
-- ✅ "Add laptop to cart" (need basket ID - should create)
-- ✅ "XYZ" (nonsense - should handle gracefully)
+### Skill Overrides
 
----
+Test specific skill versions without deploying:
 
-### Tip 5: Use Environment Variables
+```typescript
+// In sandbox mode, test development versions
+// Production uses deployed versions
+```
+
+### Processor Chains
 
-**Never hardcode secrets:**
+Process messages in order:
 
 ```typescript
-// ❌ Bad
-const apiKey = 'sk_abc123';
+preProcessors: [
+  profanityFilter,    // 1. Clean input
+  intentClassifier,   // 2. Detect intent
+  messageRouter       // 3. Route to handler
+]
 
-// ✅ Good
-import { env } from 'lua-cli';
-const apiKey = env('STRIPE_API_KEY');
-```
-
-Create `.env`:
-```bash
-STRIPE_API_KEY=your_key_here
+postProcessors: [
+  responseFormatter,  // 1. Format output
+  addDisclaimer,      // 2. Add legal text
+  translateResponse   // 3. Translate if needed
+]
 ```
 
 ---
 
-## 🎨 Customization Recipes
+## 📊 Monitoring & Management
 
-### Recipe 1: Simple Weather Skill
+### View Production Status
 
-```typescript
-// 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()]
-});
+```bash
+lua production
 ```
 
-**Deploy:**
+Shows:
+- Active skills and versions
+- Webhook URLs
+- Scheduled jobs
+- Environment variables
+
+### View Logs
+
 ```bash
-lua test  # Test it
-lua push  # Upload
-lua deploy # Go live
+lua logs
 ```
 
----
+See:
+- Agent conversations
+- Tool executions
+- Errors and warnings
+- Performance metrics
 
-### Recipe 2: Knowledge Base Skill
+### Manage Skills
 
-Use CustomDataTool.ts as template:
+```bash
+# List all skills
+lua skills
 
-1. Rename collections: `movies` → `articles`
-2. Update fields: title, director → title, content, category
-3. Update descriptions to match your domain
-4. Update skill context
+# Push specific skill
+lua push skill
 
-**Result:** Searchable knowledge base!
+# Deploy specific version
+lua deploy
+```
 
 ---
 
-### Recipe 3: E-commerce Skill
+## 🌐 CI/CD Integration
 
-Keep: `ProductsTool.ts`, `BasketTool.ts`, `OrderTool.ts`
+### GitHub Actions Example
 
-Remove: Everything else
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy Lua Agent
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Install Lua CLI
+        run: npm install -g lua-cli@alpha
+      
+      - name: Deploy to production
+        run: lua push all --force --auto-deploy
+        env:
+          LUA_API_KEY: ${{ secrets.LUA_API_KEY }}
+```
+
+### GitLab CI Example
 
-**Result:** Complete shopping experience!
+```yaml
+# .gitlab-ci.yml
+deploy:
+  stage: deploy
+  image: node:20
+  script:
+    - npm install
+    - npm install -g lua-cli@alpha
+    - lua push all --force --auto-deploy
+  only:
+    - main
+  variables:
+    LUA_API_KEY: $LUA_API_KEY
+```
 
 ---
 
-## 🔍 Understanding Multi-Skill Projects
+## 🤝 Contributing
 
-This template has **7 skills** in one project:
+### Adding Examples
 
-**Why multiple skills?**
-- Different domains (products vs orders)
-- Different deployment schedules
-- Logical organization
-- Easier to manage
+Have a great tool example? Add it to the template:
 
-**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
+1. Create the tool in `src/skills/tools/`
+2. Add it to a skill
+3. Test thoroughly
+4. Document the use case
 
-**You can:**
-- Keep all 7 (if relevant)
-- Merge into 1 (simpler)
-- Create your own grouping
+### Reporting Issues
 
----
+Found a bug or have a suggestion?
 
-## 📊 Tool Inventory
+- GitHub Issues: https://github.com/heylua/lua-cli/issues
+- Email: support@heylua.ai
 
-### 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 |
+## 📝 Important Notes
 
-**Total: 30 working examples** covering all major use cases!
+### About Jobs and Closures
 
----
+⚠️ **Job execute functions must be self-contained**
 
-## 🚨 Common Mistakes to Avoid
-
-### ❌ Mistake 1: Hardcoding API Keys
 ```typescript
-const apiKey = 'sk_abc123';  // DON'T DO THIS
-```
+// ❌ This will NOT work:
+async execute(input: any) {
+  const userMessage = input.message;
+  
+  await Jobs.create({
+    execute: async (job) => {
+      // userMessage is undefined here!
+      await user.send(userMessage);
+    }
+  });
+}
 
-✅ **Fix:** Use environment variables
-```typescript
-import { env } from 'lua-cli';
-const apiKey = env('API_KEY');
+// ✅ This WILL work:
+async execute(input: any) {
+  await Jobs.create({
+    metadata: { message: input.message },  // Pass via metadata
+    execute: async (job) => {
+      // Access from metadata
+      await job.user().send(job.metadata.message);
+    }
+  });
+}
 ```
 
----
+**Why?** Jobs are serialized and executed in a sandbox. They can't access parent scope variables.
 
-### ❌ Mistake 2: Unclear Tool Names
-```typescript
-name = "tool1"  // Unclear
-name = "do_stuff"  // Too generic
-```
+### About Bundling
 
-✅ **Fix:** Be specific
-```typescript
-name = "search_products"
-name = "create_order"
-name = "get_user_profile"
-```
+The CLI automatically:
+- ✅ Bundles all tool code and dependencies
+- ✅ Excludes lua-cli APIs (available in sandbox)
+- ✅ Compresses code for transmission
+- ✅ Handles imports and dependencies
+
+You don't need to worry about bundling - it just works!
 
 ---
 
-### ❌ Mistake 3: Weak Descriptions
-```typescript
-description = "Gets data"  // Too vague
-```
+## 🎯 What's Next?
 
-✅ **Fix:** Be descriptive
-```typescript
-description = "Searches product catalog by name, category, or description"
-```
+### Immediate Actions
+1. ✅ Test the example tools: `lua test`
+2. ✅ Chat with your agent: `lua chat` (select Sandbox)
+3. ✅ Read the [Quick Start Guide](QUICKSTART.md)
+4. ✅ Customize the agent persona in `src/index.ts`
 
----
+### Short Term
+1. ✅ Create your first custom tool
+2. ✅ Deploy to production: `lua push`
+3. ✅ Test in production: `lua chat` (select Production)
 
-### ❌ Mistake 4: Missing Error Handling
-```typescript
-async execute(input: any) {
-  const result = await api.call(input);
-  return result;  // What if it fails?
-}
-```
-
-✅ **Fix:** Handle errors
-```typescript
-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}`);
-  }
-}
-```
+### Long Term
+1. ✅ Add webhooks for external integrations
+2. ✅ Schedule jobs for automated tasks
+3. ✅ Build advanced tools with AI/external APIs
+4. ✅ Monitor and improve based on user feedback
 
 ---
 
-## 🎓 Learning Path
+## 🌟 Example Projects
 
-### Week 1: Learn by Testing
-- ✅ Run `lua test` daily
-- ✅ Try every example tool
-- ✅ Understand inputs and outputs
-- ✅ Read the tool code
+### Simple Assistant
+- 3-5 basic tools
+- No webhooks or jobs
+- General Q&A and information retrieval
 
-### Week 2: Modify Examples
-- ✅ Change descriptions
-- ✅ Add new input fields
-- ✅ Modify return values
-- ✅ Test your changes
+### E-commerce Bot
+- Product catalog management
+- Shopping cart tools
+- Payment webhooks
+- Abandoned cart jobs
 
-### Week 3: Build Your Own
-- ✅ Create 1-2 custom tools
-- ✅ Remove unused examples
-- ✅ Update skill context
-- ✅ Deploy to production
+### Support Agent
+- Knowledge base search
+- Ticket creation tools
+- Escalation webhooks
+- Daily summary jobs
+
+### Data Platform
+- Custom data tools
+- Report generation
+- Scheduled analytics jobs
+- Webhook integrations
 
 ---
 
-## 🔗 Resources
+## 📞 Support & Resources
 
-### Documentation
-- See markdown files in `node_modules/lua-cli/`
-- Visit https://docs.heylua.ai
-- Check CLI help: `lua --help`
+### Get Help
+- **Documentation:** https://docs.heylua.ai
+- **CLI Reference:** Run `lua --help`
+- **Email Support:** support@heylua.ai
+- **Community:** https://community.heylua.ai
 
-### Examples
-- All tools in `src/tools/` are working examples
-- Copy, modify, learn!
+### Stay Updated
+```bash
+# Check your version
+lua --version
 
-### Community
-- GitHub: https://github.com/lua-ai/lua-cli
-- Issues: Report bugs or ask questions
-- Email: support@lua.ai
+# Update to latest alpha
+npm install -g lua-cli@alpha
+```
 
 ---
 
-## ✅ Checklist Before Deploying
+## 📄 License
 
-- [ ] 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!)
+This template is provided as part of lua-cli. See the main project license for details.
 
 ---
 
-## 🎉 You're Ready!
+## 🎉 Happy Building!
+
+You're all set to build amazing AI agents with Lua!
 
-This template gives you:
-- ✅ **30 working tools** to learn from
-- ✅ **All API patterns** demonstrated
-- ✅ **Production-ready** structure
-- ✅ **Easy to customize** for your needs
+**Remember:**
+1. Start small - test one tool at a time
+2. Use sandbox mode liberally
+3. Read the example code - it's full of patterns
+4. Deploy often - iterate quickly
 
-**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`
+**Need inspiration?** Check out the example tools in `src/skills/tools/` - they demonstrate:
+- External API calls
+- State management
+- Error handling
+- Complex business logic
+- AI integrations
 
-**Go build something amazing!** 🚀
+Build something awesome! 🚀
 
 ---
 
-**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
+*Template version: 3.0.0 | Last updated: October 2025*