lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/TEMPLATE_GUIDE.md

@@ -1,1398 +0,0 @@
-# Lua CLI - Template Project Guide
-
-Complete guide to understanding and building skills using the template project.
-
----
-
-## 📋 Table of Contents
-
-- [Overview](#overview)
-- [Project Structure](#project-structure)
-- [Understanding the Template](#understanding-the-template)
-- [Building Your First Skill](#building-your-first-skill)
-- [Tool Examples](#tool-examples)
-- [Multi-Skill Projects](#multi-skill-projects)
-- [Best Practices](#best-practices)
-
----
-
-## Overview
-
-When you run `lua init`, a complete example project is created with:
-- ✅ Multiple skill examples
-- ✅ 30+ tool examples
-- ✅ Integration with all Lua platform APIs
-- ✅ TypeScript configuration
-- ✅ Ready to customize and deploy
-
----
-
-## Project Structure
-
-```
-your-skill/
-├── src/
-│   ├── index.ts              # Main skill definitions (YOUR STARTING POINT)
-│   ├── tools/                # Tool implementations
-│   │   ├── GetWeatherTool.ts       # External API example
-│   │   ├── UserDataTool.ts         # User API example
-│   │   ├── ProductsTool.ts         # Products API example
-│   │   ├── BasketTool.ts           # Baskets API example
-│   │   ├── OrderTool.ts            # Orders API example
-│   │   ├── CustomDataTool.ts       # Custom Data API example
-│   │   ├── PaymentTool.ts          # Payment integration example
-│   │   └── CreatePostTool.ts       # Simple tool example
-│   └── services/             # Helper services (optional)
-│       ├── ApiService.ts
-│       └── GetWeather.ts
-├── lua.skill.yaml            # Configuration (auto-managed)
-├── package.json              # Dependencies
-├── tsconfig.json             # TypeScript config
-├── .env.example              # Environment variables template
-└── README.md                 # Project documentation
-```
-
----
-
-## Understanding the Template
-
-### `src/index.ts` - The Heart of Your Project
-
-This is where you define your skills and add tools to them.
-
-**Template Structure:**
-
-```typescript
-import { LuaSkill } from "lua-cli";
-import GetWeatherTool from "./tools/GetWeatherTool";
-// ... more imports
-
-// Define your skills
-const generalSkill = new LuaSkill({
-  name: "general-skill",
-  version: "0.0.2",
-  description: "A comprehensive skill with weather and utilities",
-  context: "Use get_weather for weather info, create_post for posts...",
-  tools: [
-    new GetWeatherTool(),
-    new CreatePostTool()
-  ]
-});
-
-const productSkill = new LuaSkill({
-  name: "product-skill",
-  version: "0.0.1",
-  description: "Product catalog management",
-  context: "Use search_products to find items, create_product to add new items...",
-  tools: [
-    new SearchProductsTool(),
-    new CreateProductTool(),
-    // ... more tools
-  ]
-});
-```
-
-**Key Points:**
-- Each skill is independent
-- Skills can have different versions
-- Tools can only belong to one skill
-- Context guides the AI on when to use tools
-
----
-
-### `src/tools/` - Tool Implementations
-
-Each file contains one or more related tools.
-
-**File Organization:**
-- `GetWeatherTool.ts` - Single standalone tool
-- `ProductsTool.ts` - Multiple related tools (CRUD operations)
-- `UserDataTool.ts` - Multiple related tools (Get + Update)
-
-**Pattern: Single Tool per File**
-
-```typescript
-// GetWeatherTool.ts
-import { LuaTool } from "lua-cli";
-import { z } from "zod";
-
-export default class GetWeatherTool implements LuaTool {
-  name = "get_weather";
-  description = "Get weather for a city";
-  inputSchema = z.object({
-    city: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Implementation
-    return { weather: "sunny", temperature: 72 };
-  }
-}
-```
-
-**Pattern: Multiple Related Tools per File**
-
-```typescript
-// ProductsTool.ts
-import { LuaTool, Products } from "lua-cli";
-import { z } from "zod";
-
-export class SearchProductsTool implements LuaTool {
-  name = "search_products";
-  description = "Search products by name or description";
-  inputSchema = z.object({ query: z.string() });
-
-  async execute(input: any) {
-    return Products.search(input.query);
-  }
-}
-
-export class CreateProductTool implements LuaTool {
-  name = "create_product";
-  description = "Create a new product";
-  inputSchema = z.object({
-    name: z.string(),
-    price: z.number()
-  });
-
-  async execute(input: any) {
-    return Products.create(input);
-  }
-}
-
-// Export multiple tools
-```
-
----
-
-## Building Your First Skill
-
-### Step 1: Start with the Template
-
-```bash
-mkdir my-weather-skill
-cd my-weather-skill
-lua init
-```
-
-### Step 2: Clean Up Unused Tools
-
-The template includes many examples. Remove what you don't need:
-
-```bash
-# Delete unused tool files
-rm src/tools/ProductsTool.ts
-rm src/tools/BasketTool.ts
-rm src/tools/OrderTool.ts
-# Keep only what you need
-```
-
-### Step 3: Modify `src/index.ts`
-
-Simplify to your use case:
-
-```typescript
-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 for cities worldwide",
-  context: "Use the get_weather tool when users ask about weather, temperature, or conditions in any city. The tool requires a city name and returns current weather data including temperature, wind speed, and conditions.",
-  tools: [
-    new GetWeatherTool()
-  ]
-});
-```
-
-### Step 4: Customize or Create Tools
-
-Edit `src/tools/GetWeatherTool.ts` or create new ones:
-
-```typescript
-import { LuaTool, env } from "lua-cli";
-import { z } from "zod";
-
-export default class MyCustomTool implements LuaTool {
-  name = "my_custom_tool";
-  description = "Does something specific";
-  
-  inputSchema = z.object({
-    param1: z.string(),
-    param2: z.number().optional()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Your logic here
-    return {
-      result: "success",
-      data: {...}
-    };
-  }
-}
-```
-
-### Step 5: Test Locally
-
-```bash
-lua test
-```
-
-### Step 6: Start Development
-
-```bash
-lua dev
-```
-
-Test in the chat interface, iterate on your tools.
-
-### Step 7: Deploy
-
-```bash
-lua push      # Upload version
-lua deploy    # Deploy to production
-```
-
----
-
-## Tool Examples
-
-### Example 1: External API Call
-
-```typescript
-// File: src/tools/GetWeatherTool.ts
-import { LuaTool } from "lua-cli";
-import { z } from "zod";
-
-export default class GetWeatherTool implements LuaTool {
-  name = "get_weather";
-  description = "Get current weather for any city";
-  
-  inputSchema = z.object({
-    city: z.string().describe("City name")
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Call Open-Meteo API (free, no API key required)
-    const geoUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(input.city)}&count=1`;
-    const geoRes = await fetch(geoUrl);
-    const geoData = await geoRes.json();
-    
-    if (!geoData.results?.[0]) {
-      throw new Error(`City not found: ${input.city}`);
-    }
-    
-    const { latitude, longitude, name } = geoData.results[0];
-    
-    const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true`;
-    const weatherRes = await fetch(weatherUrl);
-    const weatherData = await weatherRes.json();
-    
-    return {
-      city: name,
-      temperature: weatherData.current_weather.temperature,
-      windSpeed: weatherData.current_weather.windspeed
-    };
-  }
-}
-```
-
-**Usage in `index.ts`:**
-```typescript
-import GetWeatherTool from "./tools/GetWeatherTool";
-
-const skill = new LuaSkill({
-  description: "Weather information skill",
-  context: "Use get_weather when users ask about weather or temperature in any city.",
-  tools: [new GetWeatherTool()]
-});
-```
-
----
-
-### Example 2: User Data Management
-
-```typescript
-// File: src/tools/UserDataTool.ts
-import { LuaTool, User } from "lua-cli";
-import { z } from "zod";
-
-export class GetUserDataTool implements LuaTool {
-  name = "get_user_data";
-  description = "Retrieve current user's profile information";
-  inputSchema = z.object({});
-
-  async execute(input: any) {
-    const user = await User.get();
-    return {
-      name: user.name,
-      email: user.email,
-      // Return relevant user data
-    };
-  }
-}
-
-export class UpdateUserDataTool implements LuaTool {
-  name = "update_user_data";
-  description = "Update user's profile information";
-  
-  inputSchema = z.object({
-    data: z.object({
-      name: z.string().optional(),
-      age: z.number().optional(),
-      preferences: z.record(z.any()).optional()
-    })
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const user = await User.get();
-    const updated = await user.update(input.data);
-    return {
-      success: true,
-      message: "Profile updated",
-      user: updated
-    };
-  }
-}
-```
-
----
-
-### Example 3: Product Management
-
-```typescript
-// File: src/tools/ProductsTool.ts
-import { LuaTool, Products } from "lua-cli";
-import { z } from "zod";
-
-export class SearchProductsTool implements LuaTool {
-  name = "search_products";
-  description = "Search for products by name or description";
-  
-  inputSchema = z.object({
-    query: z.string().describe("Search query")
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const results = await Products.search(input.query);
-    
-    return {
-      products: results.data.map(p => ({
-        id: p.id,
-        name: p.name,
-        price: p.price,
-        inStock: p.inStock
-      })),
-      count: results.data.length
-    };
-  }
-}
-
-export class CreateProductTool implements LuaTool {
-  name = "create_product";
-  description = "Add a new product to the catalog";
-  
-  inputSchema = z.object({
-    name: z.string(),
-    price: z.number().positive(),
-    category: z.string().optional(),
-    sku: z.string().optional(),
-    inStock: z.boolean().default(true)
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const product = await Products.create(input);
-    
-    return {
-      success: true,
-      productId: product.product.id,
-      message: `Product "${input.name}" created`
-    };
-  }
-}
-```
-
----
-
-### Example 4: Shopping Basket Flow
-
-```typescript
-// File: src/tools/BasketTool.ts
-import { LuaTool, Baskets, Products, BasketStatus } from "lua-cli";
-import { z } from "zod";
-
-export class CreateBasketTool implements LuaTool {
-  name = "create_basket";
-  description = "Create a new shopping basket";
-  
-  inputSchema = z.object({
-    currency: z.string().default('USD')
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const basket = await Baskets.create({
-      currency: input.currency,
-      metadata: { createdBy: 'chat' }
-    });
-    
-    return {
-      basketId: basket.id,
-      message: "New basket created"
-    };
-  }
-}
-
-export class AddItemToBasketTool implements LuaTool {
-  name = "add_to_basket";
-  description = "Add a product to the shopping basket";
-  
-  inputSchema = z.object({
-    basketId: z.string(),
-    productId: z.string(),
-    quantity: z.number().min(1).default(1)
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Get product to get price
-    const product = await Products.getById(input.productId);
-    
-    // Add to basket
-    const updated = await Baskets.addItem(input.basketId, {
-      id: input.productId,
-      price: product.price,
-      quantity: input.quantity,
-      SKU: product.sku
-    });
-    
-    return {
-      basketId: updated.id,
-      itemCount: updated.common.itemCount,
-      total: updated.common.totalAmount,
-      message: `Added ${input.quantity}x ${product.name} to basket`
-    };
-  }
-}
-
-export class CheckoutBasketTool implements LuaTool {
-  name = "checkout_basket";
-  description = "Convert basket to order";
-  
-  inputSchema = z.object({
-    basketId: z.string(),
-    shippingAddress: z.object({
-      street: z.string(),
-      city: z.string(),
-      zip: z.string()
-    }),
-    paymentMethod: z.string().default('stripe')
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const order = await Baskets.placeOrder({
-      shippingAddress: input.shippingAddress,
-      paymentMethod: input.paymentMethod
-    }, input.basketId);
-    
-    return {
-      orderId: order.id,
-      status: order.common.status,
-      total: order.common.totalAmount,
-      message: "Order created successfully"
-    };
-  }
-}
-```
-
----
-
-### Example 5: Custom Data with Vector Search
-
-```typescript
-// File: src/tools/CustomDataTool.ts
-import { LuaTool, Data } from "lua-cli";
-import { z } from "zod";
-
-export class CreateMovieTool implements LuaTool {
-  name = "create_movie";
-  description = "Add a new movie to the database";
-  
-  inputSchema = z.object({
-    title: z.string(),
-    year: z.number(),
-    director: z.string(),
-    genre: z.string(),
-    description: z.string().optional()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Create searchable text for vector search
-    const searchText = [
-      input.title,
-      input.director,
-      input.genre,
-      input.description
-    ].filter(Boolean).join(' ');
-    
-    const movie = await Data.create('movies', input, searchText);
-    
-    return {
-      id: movie.id,
-      message: `Added "${input.title}" to database`
-    };
-  }
-}
-
-export class SearchMoviesTool implements LuaTool {
-  name = "search_movies";
-  description = "Search movies by title, director, genre, or description";
-  
-  inputSchema = z.object({
-    query: z.string().describe("Search query")
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Vector search with similarity threshold
-    const results = await Data.search('movies', input.query, 10, 0.7);
-    
-    return {
-      movies: results.data.map(entry => ({
-        id: entry.id,
-        title: entry.data.title,
-        year: entry.data.year,
-        director: entry.data.director,
-        relevance: Math.round(entry.score * 100) + '%'
-      })),
-      count: results.count
-    };
-  }
-}
-
-export class GetMovieByIdTool implements LuaTool {
-  name = "get_movie";
-  description = "Get detailed information about a specific movie";
-  
-  inputSchema = z.object({
-    id: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const movie = await Data.getEntry('movies', input.id);
-    return movie.data;
-  }
-}
-```
-
----
-
-## Building Your First Skill
-
-### Scenario: Build a Task Management Skill
-
-**Goal**: Create a skill that manages tasks (create, list, complete, delete).
-
----
-
-#### Step 1: Initialize Project
-
-```bash
-mkdir task-management-skill
-cd task-management-skill
-lua init
-```
-
----
-
-#### Step 2: Clean Up Template
-
-Remove unnecessary tools:
-
-```bash
-rm src/tools/ProductsTool.ts
-rm src/tools/BasketTool.ts
-rm src/tools/OrderTool.ts
-rm src/tools/PaymentTool.ts
-rm src/tools/GetWeatherTool.ts
-# Keep CustomDataTool.ts as reference
-```
-
----
-
-#### Step 3: Create Task Tool
-
-Create `src/tools/TaskTool.ts`:
-
-```typescript
-import { LuaTool, Data } from "lua-cli";
-import { z } from "zod";
-
-export class CreateTaskTool implements LuaTool {
-  name = "create_task";
-  description = "Create a new task";
-  
-  inputSchema = z.object({
-    title: z.string().describe("Task title"),
-    description: z.string().optional(),
-    priority: z.enum(['low', 'medium', 'high']).default('medium'),
-    dueDate: z.string().optional()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const task = await Data.create('tasks', {
-      ...input,
-      status: 'pending',
-      createdAt: new Date().toISOString()
-    }, input.title + ' ' + (input.description || ''));
-    
-    return {
-      taskId: task.id,
-      message: `Task "${input.title}" created`
-    };
-  }
-}
-
-export class ListTasksTool implements LuaTool {
-  name = "list_tasks";
-  description = "List all tasks, optionally filtered by status";
-  
-  inputSchema = z.object({
-    status: z.enum(['pending', 'in_progress', 'completed']).optional()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const filter = input.status ? { status: input.status } : {};
-    const result = await Data.get('tasks', filter, 1, 50);
-    
-    return {
-      tasks: result.data.map(entry => ({
-        id: entry.id,
-        ...entry.data
-      })),
-      count: result.pagination.totalCount
-    };
-  }
-}
-
-export class CompleteTaskTool implements LuaTool {
-  name = "complete_task";
-  description = "Mark a task as completed";
-  
-  inputSchema = z.object({
-    taskId: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const task = await Data.getEntry('tasks', input.taskId);
-    
-    await Data.update('tasks', input.taskId, {
-      ...task.data,
-      status: 'completed',
-      completedAt: new Date().toISOString()
-    });
-    
-    return {
-      success: true,
-      message: `Task "${task.data.title}" marked as completed`
-    };
-  }
-}
-
-export class SearchTasksTool implements LuaTool {
-  name = "search_tasks";
-  description = "Search tasks by content";
-  
-  inputSchema = z.object({
-    query: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const results = await Data.search('tasks', input.query, 20, 0.6);
-    
-    return {
-      tasks: results.data.map(entry => ({
-        id: entry.id,
-        ...entry.data,
-        relevance: entry.score
-      }))
-    };
-  }
-}
-```
-
----
-
-#### Step 4: Update `src/index.ts`
-
-```typescript
-import { LuaSkill } from "lua-cli";
-import {
-  CreateTaskTool,
-  ListTasksTool,
-  CompleteTaskTool,
-  SearchTasksTool
-} from "./tools/TaskTool";
-
-const taskSkill = new LuaSkill({
-  name: "task-management-skill",
-  version: "1.0.0",
-  description: "Manage tasks and to-do lists with creation, listing, completion, and search",
-  context: `
-    This skill helps users manage their tasks.
-    
-    - Use create_task when users want to add a new task
-    - Use list_tasks to show all tasks or filter by status
-    - Use complete_task when users finish a task
-    - Use search_tasks to find tasks by content
-    
-    Always confirm task details before creating.
-    When listing tasks, organize by priority and due date.
-  `,
-  tools: [
-    new CreateTaskTool(),
-    new ListTasksTool(),
-    new CompleteTaskTool(),
-    new SearchTasksTool()
-  ]
-});
-```
-
----
-
-#### Step 5: Test and Deploy
-
-```bash
-# Test individual tools
-lua test
-
-# Test conversationally
-lua dev
-
-# In the chat:
-# "Create a task to buy milk"
-# "Show me my pending tasks"
-# "Mark the milk task as done"
-
-# Deploy
-lua push
-lua deploy
-```
-
----
-
-## Multi-Skill Projects
-
-You can organize related tools into multiple skills.
-
-### When to Use Multiple Skills
-
-**Use separate skills when:**
-- ✅ Tools serve different purposes (e.g., "HR Skill" vs "Sales Skill")
-- ✅ Different teams own different skills
-- ✅ Skills have different deployment schedules
-- ✅ Skills need different permissions
-
-**Use single skill when:**
-- ✅ Tools work together closely
-- ✅ Small to medium number of tools (< 20)
-- ✅ All tools deploy together
-
-### Example: Multi-Skill E-commerce
-
-```typescript
-import { LuaSkill } from "lua-cli";
-import { SearchProductsTool, GetProductTool } from "./tools/ProductsTool";
-import { CreateBasketTool, AddItemTool } from "./tools/BasketTool";
-import { CreateOrderTool, TrackOrderTool } from "./tools/OrderTool";
-
-// Product browsing skill
-const catalogSkill = new LuaSkill({
-  name: "product-catalog-skill",
-  version: "1.0.0",
-  description: "Product browsing and search",
-  context: "Use search_products to find items. Use get_product for details.",
-  tools: [
-    new SearchProductsTool(),
-    new GetProductTool()
-  ]
-});
-
-// Shopping skill
-const shoppingSkill = new LuaSkill({
-  name: "shopping-skill",
-  version: "1.0.0",
-  description: "Shopping cart management",
-  context: "Use create_basket to start shopping. Use add_item to add products.",
-  tools: [
-    new CreateBasketTool(),
-    new AddItemTool()
-  ]
-});
-
-// Order fulfillment skill
-const orderSkill = new LuaSkill({
-  name: "order-skill",
-  version: "1.0.0",
-  description: "Order creation and tracking",
-  context: "Use create_order to finalize purchase. Use track_order for status.",
-  tools: [
-    new CreateOrderTool(),
-    new TrackOrderTool()
-  ]
-});
-```
-
-**Deployment:**
-- Each skill gets its own `skillId` in `lua.skill.yaml`
-- All skills deploy together when you run `lua push`
-- Can activate/deactivate individual skills
-
----
-
-## Best Practices
-
-### Tool Design Principles
-
-#### 1. Single Responsibility
-
-**✅ Good:**
-```typescript
-// One focused task
-class GetWeatherTool { ... }
-class CreateProductTool { ... }
-```
-
-**❌ Bad:**
-```typescript
-// Too many responsibilities
-class DoEverythingTool {
-  // Gets weather, creates products, sends emails...
-}
-```
-
----
-
-#### 2. Clear Input/Output
-
-**✅ Good:**
-```typescript
-inputSchema = z.object({
-  city: z.string().describe("City name (e.g., 'London', 'Tokyo')"),
-  units: z.enum(['metric', 'imperial']).describe("Temperature units")
-});
-
-// Returns structured data
-return {
-  city: "London",
-  temperature: 15.2,
-  condition: "cloudy"
-};
-```
-
-**❌ Bad:**
-```typescript
-inputSchema = z.object({
-  input: z.string()  // Unclear what this is
-});
-
-// Returns unstructured string
-return "The weather in London is 15.2 degrees and cloudy";
-```
-
----
-
-#### 3. Error Messages
-
-**✅ Good:**
-```typescript
-if (!city) {
-  throw new Error("City parameter is required");
-}
-
-if (results.length === 0) {
-  throw new Error(`No products found matching "${query}"`);
-}
-```
-
-**❌ Bad:**
-```typescript
-throw new Error("Error");
-throw new Error("Invalid input");
-```
-
----
-
-### Context Writing Tips
-
-The `context` field guides the AI. Write it well!
-
-**Structure:**
-```typescript
-context: `
-  [Brief overview of what the skill does]
-  
-  Tool Usage:
-  - tool_1: When to use it, what it does
-  - tool_2: When to use it, what it does
-  
-  Important Notes:
-  - Special considerations
-  - Edge cases
-  - Limitations
-`
-```
-
-**Example:**
-```typescript
-context: `
-  This skill manages a product catalog and shopping experience.
-  
-  Tool Usage:
-  - search_products: Use when users want to find or browse items
-  - create_product: Use when adding new items to catalog (admin only)
-  - create_basket: Use when starting a new shopping session
-  - add_to_basket: Use when users want to add items to cart
-  - checkout_basket: Use when users are ready to complete purchase
-  
-  Important Notes:
-  - Always show prices with currency symbols
-  - Confirm order details before checkout
-  - Check product availability before adding to basket
-  - Baskets expire after 24 hours of inactivity
-`
-```
-
----
-
-## Environment Variables
-
-### Setup
-
-**Option 1: `.env` file** (recommended for local development)
-```bash
-# .env
-STRIPE_API_KEY=sk_test_abc123
-SENDGRID_API_KEY=SG.xyz789
-EXTERNAL_API_URL=https://api.example.com
-```
-
-**Option 2: `lua.skill.yaml`** (for deployed environments)
-```yaml
-skill:
-  env:
-    STRIPE_API_KEY: sk_live_abc123
-    SENDGRID_API_KEY: SG.xyz789
-    EXTERNAL_API_URL: https://api.example.com
-```
-
-### Using in Tools
-
-```typescript
-import { env } from 'lua-cli';
-
-export class PaymentTool implements LuaTool {
-  async execute(input: any) {
-    const stripeKey = env('STRIPE_API_KEY');
-    
-    if (!stripeKey) {
-      throw new Error('Payment system not configured. Please set STRIPE_API_KEY.');
-    }
-    
-    // Use the API key...
-  }
-}
-```
-
-### Security
-
-**✅ Do:**
-- Store API keys in environment variables
-- Use `.env` file for local development
-- Add `.env` to `.gitignore`
-- Use `lua.skill.yaml` for deployed secrets
-
-**❌ Don't:**
-- Hardcode API keys in code
-- Commit `.env` to git
-- Share API keys in documentation
-
----
-
-## File Organization Tips
-
-### Small Project (< 5 tools)
-
-```
-src/
-├── index.ts
-└── tools/
-    └── MyTools.ts    # All tools in one file
-```
-
-### Medium Project (5-15 tools)
-
-```
-src/
-├── index.ts
-└── tools/
-    ├── WeatherTools.ts    # Weather-related tools
-    ├── UserTools.ts       # User-related tools
-    └── ProductTools.ts    # Product-related tools
-```
-
-### Large Project (> 15 tools)
-
-```
-src/
-├── index.ts
-├── tools/
-│   ├── weather/
-│   │   ├── GetWeather.ts
-│   │   └── GetForecast.ts
-│   ├── products/
-│   │   ├── Search.ts
-│   │   ├── Create.ts
-│   │   └── Update.ts
-│   └── orders/
-│       ├── Create.ts
-│       └── Track.ts
-└── services/          # Shared utilities
-    ├── WeatherApi.ts
-    └── PaymentApi.ts
-```
-
----
-
-## Testing Strategies
-
-### 1. Unit Testing Tools
-
-```typescript
-import { describe, it, expect } from '@jest/globals';
-import GetWeatherTool from './tools/GetWeatherTool';
-
-describe('GetWeatherTool', () => {
-  it('should return weather data for valid city', async () => {
-    const tool = new GetWeatherTool();
-    const result = await tool.execute({ city: 'London' });
-    
-    expect(result).toHaveProperty('temperature');
-    expect(result).toHaveProperty('city');
-  });
-  
-  it('should throw error for invalid city', async () => {
-    const tool = new GetWeatherTool();
-    
-    await expect(
-      tool.execute({ city: 'InvalidCityXYZ123' })
-    ).rejects.toThrow('City not found');
-  });
-});
-```
-
----
-
-### 2. Interactive Testing
-
-```bash
-lua test
-```
-Select tool → Enter inputs → See results
-
----
-
-### 3. Conversational Testing
-
-```bash
-lua dev
-```
-Open http://localhost:3000 → Chat with AI → Test natural language interaction
-
----
-
-## Common Patterns
-
-### Pattern: Pagination Helper
-
-```typescript
-async execute(input: any) {
-  const page = input.page || 1;
-  const limit = input.limit || 20;
-  
-  const results = await Data.get('collection', {}, page, limit);
-  
-  return {
-    items: results.data,
-    pagination: {
-      current: results.pagination.currentPage,
-      total: results.pagination.totalPages,
-      hasMore: results.pagination.hasNextPage
-    }
-  };
-}
-```
-
----
-
-### Pattern: Input Validation
-
-```typescript
-async execute(input: any) {
-  // Zod handles schema validation
-  // Add business logic validation
-  
-  if (input.amount > 10000) {
-    throw new Error('Amount exceeds maximum limit of $10,000');
-  }
-  
-  if (input.email && !await this.isValidEmail(input.email)) {
-    throw new Error('Email domain not allowed');
-  }
-  
-  // Proceed with logic...
-}
-```
-
----
-
-### Pattern: Error Recovery
-
-```typescript
-async execute(input: any) {
-  try {
-    // Try primary method
-    return await primaryService.call(input);
-  } catch (error) {
-    console.warn('Primary service failed, trying fallback');
-    
-    try {
-      // Try fallback
-      return await fallbackService.call(input);
-    } catch (fallbackError) {
-      // Both failed
-      throw new Error('Service unavailable. Please try again later.');
-    }
-  }
-}
-```
-
----
-
-### Pattern: Response Formatting
-
-```typescript
-async execute(input: any) {
-  const products = await Products.search(input.query);
-  
-  // Format for AI consumption
-  return {
-    summary: `Found ${products.data.length} products`,
-    products: products.data.map(p => ({
-      name: p.name,
-      price: `$${p.price.toFixed(2)}`,
-      availability: p.inStock ? '✅ In Stock' : '❌ Out of Stock',
-      link: `https://shop.example.com/products/${p.id}`
-    }))
-  };
-}
-```
-
----
-
-## Deployment Checklist
-
-Before deploying your skill:
-
-- [ ] All tools have clear names and descriptions
-- [ ] Input schemas use `.describe()` for fields
-- [ ] Error messages are helpful and specific
-- [ ] Context provides clear usage guidelines
-- [ ] Environment variables are configured
-- [ ] Tools tested with `lua test`
-- [ ] Conversational flow tested with `lua dev`
-- [ ] No hardcoded secrets or API keys
-- [ ] Version number updated in `lua.skill.yaml`
-
----
-
-## Migration from Template
-
-### Customize for Your Use Case
-
-1. **Identify needed APIs**: User, Products, Baskets, Orders, Custom Data?
-2. **Remove unused tools**: Delete files you don't need
-3. **Customize remaining tools**: Modify for your domain
-4. **Update descriptions**: Change to match your business
-5. **Test thoroughly**: Use `lua test` and `lua dev`
-
-### Template to Production
-
-**Template Example:**
-```typescript
-description = "A comprehensive skill with weather and utilities"
-```
-
-**Your Production Version:**
-```typescript
-description = "Coffee shop assistant with menu, ordering, and loyalty features"
-```
-
-**Template Example:**
-```typescript
-context = "Use get_weather for weather info..."
-```
-
-**Your Production Version:**
-```typescript
-context = `
-  This skill helps customers of Java Junction Coffee Shop.
-  
-  - Use search_menu to show available drinks and food
-  - Use create_order to take customer orders
-  - Use check_loyalty_points to show rewards balance
-  - Use redeem_reward to apply loyalty discounts
-  
-  Always mention daily specials.
-  Ask about size preferences for drinks.
-  Suggest food pairings with drinks.
-`
-```
-
----
-
-## Advanced Topics
-
-### Custom Services
-
-Create helper services in `src/services/`:
-
-```typescript
-// src/services/PaymentService.ts
-import { env } from 'lua-cli';
-
-export class PaymentService {
-  private apiKey: string;
-  
-  constructor() {
-    this.apiKey = env('STRIPE_API_KEY') || '';
-  }
-  
-  async createPaymentIntent(amount: number) {
-    // Stripe integration...
-  }
-  
-  async refund(paymentId: string) {
-    // Refund logic...
-  }
-}
-```
-
-Use in tools:
-```typescript
-import { PaymentService } from '../services/PaymentService';
-
-export class ProcessPaymentTool implements LuaTool {
-  private paymentService = new PaymentService();
-  
-  async execute(input: any) {
-    return await this.paymentService.createPaymentIntent(input.amount);
-  }
-}
-```
-
----
-
-### Shared Utilities
-
-Create utilities in `src/utils/`:
-
-```typescript
-// src/utils/validation.ts
-export function isValidEmail(email: string): boolean {
-  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
-}
-
-export function formatCurrency(amount: number, currency: string = 'USD'): string {
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
-    currency
-  }).format(amount);
-}
-```
-
----
-
-## Troubleshooting
-
-### "Tool name invalid"
-```
-Error: Tool names can only contain alphanumeric characters, hyphens (-), and underscores (_).
-```
-**Fix:** Rename tool to use only allowed characters.
-
-### "Cannot find module 'lua-cli'"
-```
-Error: Cannot find module 'lua-cli'
-```
-**Fix:** Run `npm install` in your project directory.
-
-### "No API key found"
-```
-Error: No API key found. Please run "lua auth configure" first.
-```
-**Fix:** Tools using platform APIs need authentication. Run `lua auth configure`.
-
----
-
-## Resources
-
-- **CLI Commands**: `CLI_REFERENCE.md`
-- **Developer Guide**: `DEVELOPER_GUIDE.md`
-- **Example Tools**: `template/src/tools/`
-- **Platform Docs**: https://docs.heylua.ai
-
----
-
-## Quick Reference
-
-### Essential Imports
-
-```typescript
-import { LuaSkill, LuaTool, env } from 'lua-cli';
-import { User, Data, Products, Baskets, Orders } from 'lua-cli';
-import { BasketStatus, OrderStatus } from 'lua-cli';
-import { z } from 'zod';
-```
-
-### Basic Tool Template
-
-```typescript
-export default class MyTool implements LuaTool {
-  name = "my_tool";
-  description = "What it does";
-  inputSchema = z.object({
-    param: z.string()
-  });
-
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Logic here
-    return { result: "success" };
-  }
-}
-```
-
-### Basic Skill Template
-
-```typescript
-const skill = new LuaSkill({
-  name: "my-skill",
-  version: "1.0.0",
-  description: "Brief description",
-  context: "Detailed usage instructions for AI",
-  tools: [new MyTool()]
-});
-```
-
----
-
-**Happy building! 🚀**
-