lua-cli 3.1.0-alpha.4 → 3.1.0

package/template/README.md

@@ -1,967 +1,141 @@
-# 🤖 Lua AI Agent Template
+# 🤖 Lua AI Agent
 
-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've Got
-
-This template includes **everything you need** to create a production-ready AI agent:
-
-- ✅ **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
-
----
+Welcome to your Lua AI Agent! This is a minimal project ready for you to build your custom agent.
 
 ## 🚀 Quick Start
 
-**New to Lua?** Start here:
-
 ```bash
-# 1. Test your tools locally
-lua test
-
-# 2. Chat with your agent (sandbox mode)
+# 1. Test your agent (sandbox mode)
 lua chat
 
+# 2. Create your first tool
+# See "Creating Your First Tool" below
+
 # 3. Deploy to production
 lua push all --force --auto-deploy
 ```
 
-👉 **[Read the Full Quick Start Guide →](QUICKSTART.md)**
-
----
-
-## 📦 What's Inside
-
-### Core Files
-
-| File | Purpose |
-|------|---------|
-| `src/index.ts` | **Main file** - LuaAgent configuration |
-| `lua.skill.yaml` | Agent metadata and component registry |
-| `.env` | Environment variables (API keys, secrets) |
-
-### Directory Structure
-
-```
-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
-```
-
----
-
-## 🤖 Your Agent at a Glance
-
-Your agent is configured in `src/index.ts`:
-
-```typescript
-export const agent = new LuaAgent({
-  name: 'your-agent-name',
-  persona: 'Your agent personality and behavior...',
-  
-  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
-  ]
-});
-```
-
----
-
-## 🛠️ Example Tools Included
-
-### 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
-
-### 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
-
----
-
-## 🎓 Learning Path
-
-### 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`
-
-### 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`
-
-### 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
-
----
-
-## 🔑 Key Features
-
-### Intelligent Tools
-Your agent can use tools to accomplish tasks:
-```typescript
-// User: "What's the weather in Tokyo?"
-// Agent uses: get_weather tool
-// Response: "It's 72°F and sunny in Tokyo"
-```
-
-### External Integrations
-Connect to any API:
-```typescript
-// Stripe, OpenAI, Pinecone, custom APIs
-const result = await axios.post(API_URL, data);
-```
-
-### User Context
-Access user data in every tool:
-```typescript
-const user = await User.get();
-const preferences = user.preferences;
-```
-
-### Persistent Storage
-Store data across conversations:
-```typescript
-await Data.create('notes', { 
-  title: "Meeting Notes",
-  content: "..." 
-});
-```
-
-### Scheduled Automation
-Run tasks on a schedule:
-```typescript
-// Every day at 9 AM
-schedule: {
-  type: "cron",
-  pattern: "0 9 * * *"
-}
-```
+## 📁 Project Structure
 
-### Real-time Events
-Receive HTTP webhooks:
-```typescript
-// POST /webhook/{webhookId}
-// Process payment confirmations, order updates, etc.
 ```
-
----
-
-## 📊 Development Workflow
-
-```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
+your-project/
+├── src/
+│   └── index.ts          # Your agent configuration
+├── lua.skill.yaml        # Agent metadata (auto-managed)
+├── package.json          # Dependencies
+└── tsconfig.json         # TypeScript config
 ```
 
-### Commands Reference
+## 🛠️ Creating Your First Tool
 
-| 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 |
-
----
-
-## 🔒 Environment Variables
-
-Store sensitive data in `.env`:
+### 1. Create the tool file
 
 ```bash
-# Copy from example
-cp env.example .env
-
-# Add your API keys
-OPENAI_API_KEY=sk-...
-STRIPE_SECRET_KEY=sk_live_...
-PINECONE_API_KEY=...
-
-# Optional: For CI/CD
-LUA_API_KEY=your-lua-api-key
-```
-
-**Priority:**
-1. System keychain (most secure)
-2. `LUA_API_KEY` environment variable
-3. `.env` file
-
----
-
-## 🎨 Customization Guide
-
-### 1. Update Agent Identity
-
-Edit `src/index.ts`:
-
-```typescript
-export const agent = new LuaAgent({
-  name: 'my-customer-support-bot',  // ✏️ Change this
-  
-  persona: `You are Sarah, a friendly customer support agent...`,  // ✏️ Customize
-  
-  // ...
-});
+mkdir -p src/skills/tools
 ```
 
-### 2. Add Your Own Tool
-
-Create `src/skills/tools/MyTool.ts`:
+Create `src/skills/tools/GreetingTool.ts`:
 
 ```typescript
-import { LuaTool } from "lua-cli/skill";
+import { LuaTool } from "lua-cli";
 import { z } from "zod";
 
-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" };
-  }
+export default class GreetingTool implements LuaTool {
+    name = "greet_user";
+    description = "Generate a personalized greeting";
+    
+    inputSchema = z.object({
+        name: z.string().describe("The name of the person to greet")
+    });
+
+    async execute(input: z.infer<typeof this.inputSchema>) {
+        return { 
+            greeting: `Hello, ${input.name}! How can I help you today?` 
+        };
+    }
 }
 ```
 
-Add to a skill in `src/index.ts`:
-
-```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()]
-});
-
-export const agent = new LuaAgent({
-  // ...
-  skills: [...existingSkills, mySkill],
-});
-```
-
-### 3. Configure Webhooks
+### 2. Create a skill to group your tools
 
-Uncomment in `src/index.ts`:
+Create `src/skills/greeting.skill.ts`:
 
 ```typescript
-import paymentWebhook from './webhooks/PaymentWebhook';
+import { LuaSkill } from "lua-cli";
+import GreetingTool from "./tools/GreetingTool";
 
-export const agent = new LuaAgent({
-  // ...
-  webhooks: [paymentWebhook],  // ✅ Enabled
+const greetingSkill = new LuaSkill({
+    name: "greeting-skill",
+    description: "Tools for greeting users",
+    context: "Use these tools when the user wants to be greeted",
+    tools: [new GreetingTool()],
 });
-```
 
-Get your webhook URLs after deployment:
-```
-https://webhook.heylua.ai/{agentId}/{webhookId}    // default
-https://webhook.heylua.ai/{agentId}/{webhook-name} // friendly alias
+export default greetingSkill;
 ```
 
-### 4. Schedule Jobs
+### 3. Add the skill to your agent
 
-Uncomment in `src/index.ts`:
+Update `src/index.ts`:
 
 ```typescript
-import dailyCleanupJob from './jobs/DailyCleanupJob';
+import { LuaAgent } from "lua-cli";
+import greetingSkill from "./skills/greeting.skill";
 
-export const agent = new LuaAgent({
-  // ...
-  jobs: [dailyCleanupJob],  // ✅ Enabled
+const agent = new LuaAgent({
+    name: `My Agent`,
+    persona: `You are a friendly assistant.`,
+    skills: [greetingSkill],
 });
 ```
 
----
-
-## 📚 Documentation
-
-### 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
-
-### Official Documentation
-- **Lua Docs:** https://docs.heylua.ai
-- **CLI Reference:** https://github.com/heylua/lua-cli
-- **Community:** https://community.heylua.ai
-
----
-
-## 🧪 Testing Strategy
-
-### Local Testing (Recommended)
-
-```bash
-# Test individual tools
-lua test
-
-# Interactive chat testing
-lua chat
-# Select: Sandbox
-```
-
-**Why sandbox?**
-- ✅ Uses your local code (not deployed)
-- ✅ Safe for experimentation
-- ✅ Instant feedback
-- ✅ No production impact
-
-### Production Testing
-
-```bash
-lua chat
-# Select: Production
-```
-
-**When to use:**
-- ✅ After deploying
-- ✅ Validate production behavior
-- ✅ Test with real data
-
----
-
-## 🚀 Deployment Options
-
-### Option 1: Interactive (Recommended for First Time)
-
-```bash
-lua push
-# Select component type
-# Confirm version
-# Choose whether to deploy
-```
-
-**Best for:**
-- Learning the deployment process
-- Reviewing changes before deploying
-- Fine-grained control
-
-### Option 2: Batch Deployment (CI/CD)
+### 4. Test it!
 
 ```bash
-lua push all --force --auto-deploy
+lua test      # Test the tool directly
+lua chat      # Chat with your agent
 ```
 
-**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
+## 📖 Essential Commands
 
----
-
-## 💡 Pro Tips
-
-### 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
-
-### 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!)
-
-### 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
-
-### 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
+| Command | Purpose |
+|---------|---------|
+| `lua test` | Test individual tools interactively |
+| `lua chat` | Interactive chat with your agent |
+| `lua compile` | Compile your code |
+| `lua push` | Upload to server |
+| `lua deploy` | Deploy to production |
+| `lua logs` | View execution logs |
 
----
+## 🎯 Want Examples?
 
-## 🔄 Keeping Your Agent Updated
-
-### When You Make Changes
+Initialize a new project with example code:
 
 ```bash
-# 1. Test your changes
-lua test
-
-# 2. Compile
-lua compile
-
-# 3. Push new version
-lua push
-
-# 4. Deploy when ready
-lua deploy
-```
-
-### Sync Your Configuration
-
-The CLI automatically keeps your `lua.skill.yaml` and `LuaAgent` in sync:
-
-- **Run `lua init`** → Syncs agent name and persona to both files
-- **Run `lua compile`** → Syncs LuaAgent changes back to YAML
-- **Manual edit YAML** → Re-run `lua compile` to rebuild
-
----
-
-## 🎨 Example Use Cases
-
-### 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.`
-
-skills: [productSkill, orderSkill, basketSkill]
-```
-
-### 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]
+mkdir my-project-with-examples && cd my-project-with-examples
+lua init --with-examples
 ```
 
-### 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]
-```
-
----
-
-## 🔐 Security Best Practices
+This includes:
+- ✅ 30+ example tools
+- ✅ Example webhooks (HTTP endpoints)
+- ✅ Example scheduled jobs
+- ✅ Example pre/post processors
+- ✅ Working e-commerce flow (products, baskets, orders)
 
-### 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)
+## 📚 Learn More
 
-### Webhooks
-- ✅ Validate webhook signatures in production
-- ✅ Use HTTPS endpoints only
-- ✅ Rate limit webhook handlers
-- ✅ Log all webhook events
-
-### User Data
-- ✅ Only store necessary data
-- ✅ Encrypt sensitive information
-- ✅ Respect user privacy preferences
-- ✅ Implement data deletion on request
-
----
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**"Tool not found by agent"**
-```bash
-# 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
-```
-
-**"Job execute function: ReferenceError: input is not defined"**
-```typescript
-// ❌ Wrong: Accessing parent scope
-execute: async (job) => {
-  const message = input.message;  // Error!
-}
-
-// ✅ Correct: Use metadata
-metadata: { message: input.message },
-execute: async (job) => {
-  const message = job.metadata.message;  // Works!
-}
-```
-
-**"Version not found when deploying"**
-```bash
-# Server needs time to process. Wait 10 seconds, then:
-lua deploy
-```
-
----
-
-## 📈 Scaling Your Agent
-
-### Add More Skills
-
-As your agent grows, organize tools into skills:
-
-```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()
-  ]
-});
-```
-
-### Add Background Processing
-
-Use jobs for heavy or scheduled work:
-
-```typescript
-// 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
-  }
-});
-```
-
-### Add External Integrations
-
-Use webhooks to receive events:
-
-```typescript
-// Receive events from Stripe, Shopify, etc.
-export default new LuaWebhook({
-  name: "shopify-order",
-  execute: async (event) => {
-    const { body } = event;
-    // Process Shopify order
-    // Update your system
-    // Notify customer
-  }
-});
-```
-
----
-
-## 🔧 Advanced Configuration
-
-### Multiple Environments
-
-```bash
-# Sandbox (testing)
-lua chat  # Select Sandbox
-lua env sandbox
-
-# Production (live users)
-lua chat  # Select Production
-lua env production
-```
-
-### Skill Overrides
-
-Test specific skill versions without deploying:
-
-```typescript
-// In sandbox mode, test development versions
-// Production uses deployed versions
-```
-
-### Processor Chains
-
-Process messages in order:
-
-```typescript
-preProcessors: [
-  profanityFilter,    // 1. Clean input
-  intentClassifier,   // 2. Detect intent
-  messageRouter       // 3. Route to handler
-]
-
-postProcessors: [
-  responseFormatter,  // 1. Format output
-  addDisclaimer,      // 2. Add legal text
-  translateResponse   // 3. Translate if needed
-]
-```
-
----
-
-## 📊 Monitoring & Management
-
-### View Production Status
-
-```bash
-lua production
-```
-
-Shows:
-- Active skills and versions
-- Webhook URLs
-- Scheduled jobs
-- Environment variables
-
-### View Logs
-
-```bash
-lua logs
-```
-
-Interactive filtering by primitive type:
-- **Skills** - Filter by specific skill or view all skill logs
-- **Jobs** - Filter by specific job (including dynamically created jobs) or view all job logs
-- **Webhooks** - Filter by specific webhook or view all webhook logs
-- **Preprocessors** - Filter by specific preprocessor or view all preprocessor logs
-- **Postprocessors** - Filter by specific postprocessor or view all postprocessor logs
-
-Each log entry displays:
-- Primitive type, name, and ID
-- Tool name (for skill-related logs)
-- Timestamp and log level
-- Full message content
-
-See:
-- Agent conversations
-- Tool executions
-- Errors and warnings
-- Performance metrics
-
-### Manage Skills
-
-```bash
-# List all skills
-lua skills
-
-# Push specific skill
-lua push skill
-
-# Deploy specific version
-lua deploy
-```
-
----
-
-## 🌐 CI/CD Integration
-
-### GitHub Actions Example
-
-```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
-
-```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
-```
-
----
-
-## 🤝 Contributing
-
-### Adding Examples
-
-Have a great tool example? Add it to the template:
-
-1. Create the tool in `src/skills/tools/`
-2. Add it to a skill
-3. Test thoroughly
-4. Document the use case
-
-### Reporting Issues
-
-Found a bug or have a suggestion?
-
-- GitHub Issues: https://github.com/heylua/lua-cli/issues
-- Email: support@heylua.ai
-
----
-
-## 📝 Important Notes
-
-### About Jobs and Closures
-
-⚠️ **Job execute functions must be self-contained**
-
-```typescript
-// ❌ 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);
-    }
-  });
-}
-
-// ✅ 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.
-
-### About Bundling
-
-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!
-
----
-
-## 🎯 What's Next?
-
-### 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)
-
-### 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
-
----
-
-## 🌟 Example Projects
-
-### Simple Assistant
-- 3-5 basic tools
-- No webhooks or jobs
-- General Q&A and information retrieval
-
-### E-commerce Bot
-- Product catalog management
-- Shopping cart tools
-- Payment webhooks
-- Abandoned cart jobs
-
-### 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
-
----
-
-## 📞 Support & Resources
-
-### Get Help
 - **Documentation:** https://docs.heylua.ai
-- **CLI Reference:** Run `lua --help`
-- **Email Support:** support@heylua.ai
-- **Community:** https://community.heylua.ai
-
-### Stay Updated
-```bash
-# Check your version
-lua --version
-
-# Update to latest alpha
-npm install -g lua-cli@alpha
-```
-
----
+- **Examples:** https://docs.heylua.ai/examples
+- **API Reference:** https://docs.heylua.ai/api
 
-## 📄 License
+## 💡 Tips
 
-This template is provided as part of lua-cli. See the main project license for details.
+1. **Use Zod schemas** - They provide type safety and help the AI understand your tool inputs
+2. **Write clear descriptions** - The AI reads these to decide when to use your tools
+3. **Test in sandbox first** - Use `lua chat` with sandbox mode before deploying
+4. **Keep tools focused** - Each tool should do one thing well
 
 ---
 
-## 🎉 Happy Building!
-
-You're all set to build amazing AI agents with Lua!
-
-**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
-
-**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
-
-Build something awesome! 🚀
-
----
-
-*Template version: 3.0.0 | Last updated: October 2025*
-
+*Built with [Lua CLI](https://www.npmjs.com/package/lua-cli)*