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

package/API_REFERENCE.md

@@ -0,0 +1,1408 @@
+# Lua CLI - API Reference
+
+Complete API reference for building Lua AI skills.
+
+---
+
+## 📋 Table of Contents
+
+- [Installation](#installation)
+- [Core Concepts](#core-concepts)
+- [LuaSkill Class](#luaskill-class)
+- [LuaTool Interface](#luatool-interface)
+- [Platform APIs](#platform-apis)
+- [Environment Variables](#environment-variables)
+- [Complete Examples](#complete-examples)
+
+---
+
+## Installation
+
+```bash
+npm install lua-cli zod
+```
+
+**Dependencies:**
+- `lua-cli` - Lua CLI and APIs
+- `zod` - Schema validation (peer dependency)
+
+---
+
+## Core Concepts
+
+### What is a Lua Skill?
+
+A **skill** is a collection of **tools** that an AI agent can use. Each tool:
+- Has a specific purpose (e.g., "get weather", "create order")
+- Accepts validated inputs (using Zod schemas)
+- Returns structured outputs
+- Can call external APIs, databases, or services
+
+### Architecture
+
+```
+LuaSkill
+├── Tool 1 (e.g., Get Weather)
+├── Tool 2 (e.g., Create Product)
+└── Tool 3 (e.g., Send Email)
+```
+
+The AI agent:
+1. Receives user request
+2. Selects appropriate tool(s)
+3. Calls tools with validated inputs
+4. Returns results to user
+
+---
+
+## LuaSkill Class
+
+### Importing
+
+```typescript
+import { LuaSkill } from 'lua-cli';
+```
+
+### Constructor
+
+```typescript
+new LuaSkill(config: LuaSkillConfig)
+```
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `config.name` | string | No | Skill name (default: 'unnamed-skill') |
+| `config.version` | string | No | Skill version (default: '1.0.0') |
+| `config.description` | string | Yes | Brief description (1-2 sentences) |
+| `config.context` | string | Yes | Detailed usage instructions for the AI |
+| `config.tools` | LuaTool[] | No | Array of tools to add immediately |
+
+**Example:**
+
+```typescript
+const skill = new LuaSkill({
+  name: 'weather-skill',
+  version: '1.0.0',
+  description: 'Provides weather information for any city',
+  context: 'Use the get_weather tool when users ask about weather, temperature, or conditions. The tool requires a city name and returns current weather data.',
+  tools: [new GetWeatherTool()]
+});
+```
+
+### Methods
+
+#### `addTool(tool: LuaTool): void`
+
+Adds a single tool to the skill.
+
+```typescript
+skill.addTool(new MyTool());
+```
+
+**Validation:**
+- Tool name must be unique
+- Tool name must only contain: `a-z`, `A-Z`, `0-9`, `-`, `_`
+- Throws error if validation fails
+
+---
+
+#### `addTools(tools: LuaTool[]): void`
+
+Adds multiple tools to the skill.
+
+```typescript
+skill.addTools([
+  new Tool1(),
+  new Tool2(),
+  new Tool3()
+]);
+```
+
+**Validation:**
+- All tools validated before adding
+- Atomic operation (all or nothing)
+
+---
+
+### Best Practices
+
+**✅ Good Context:**
+```typescript
+context: "Use get_weather for current conditions. Use search_products when users want to find items. Use create_order to complete purchases. Always confirm details before creating orders."
+```
+
+**❌ Poor Context:**
+```typescript
+context: "A skill with tools"
+```
+
+**Tips:**
+- Be specific about when to use each tool
+- Mention required vs optional parameters
+- Include edge cases and limitations
+- Give the AI clear decision criteria
+
+---
+
+## LuaTool Interface
+
+### Structure
+
+```typescript
+interface LuaTool<TInput extends ZodType = ZodType> {
+  name: string;
+  description: string;
+  inputSchema: TInput;
+  execute: (input: any) => Promise<any>;
+}
+```
+
+### Implementing a Tool
+
+#### Method 1: Class Implementation
+
+```typescript
+import { LuaTool } from 'lua-cli';
+import { z } from 'zod';
+
+export default class GetWeatherTool implements LuaTool {
+  name = "get_weather";
+  description = "Get current weather for a city";
+  
+  inputSchema = z.object({
+    city: z.string().describe("City name"),
+    units: z.enum(['metric', 'imperial']).optional()
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // input is automatically validated and typed
+    const { city, units = 'metric' } = input;
+    
+    // Call weather API...
+    const weather = await fetchWeather(city, units);
+    
+    return {
+      temperature: weather.temp,
+      condition: weather.condition,
+      city: weather.location
+    };
+  }
+}
+```
+
+#### Method 2: Object Implementation
+
+```typescript
+const weatherTool: LuaTool = {
+  name: "get_weather",
+  description: "Get current weather for a city",
+  inputSchema: z.object({
+    city: z.string()
+  }),
+  async execute(input) {
+    // Implementation...
+    return { temperature: 72 };
+  }
+};
+```
+
+### Tool Properties
+
+#### `name: string`
+
+- **Format**: Lowercase, alphanumeric, hyphens, underscores only
+- **Valid**: `get_weather`, `create-product`, `sendEmail123`
+- **Invalid**: `get weather`, `create.product`, `send@email`
+- **Purpose**: Unique identifier for the tool
+
+---
+
+#### `description: string`
+
+- **Format**: Clear, concise description (1 sentence)
+- **Purpose**: Helps AI understand when to use the tool
+- **Best Practice**: Mention what the tool does and its primary use case
+
+**Examples:**
+```typescript
+description = "Get current weather conditions for any city worldwide"
+description = "Create a new product in the catalog with price and details"
+description = "Search for products by name, category, or description"
+```
+
+---
+
+#### `inputSchema: ZodType`
+
+Zod schema defining valid inputs.
+
+**Simple Schema:**
+```typescript
+inputSchema = z.object({
+  city: z.string()
+});
+```
+
+**Complex Schema:**
+```typescript
+inputSchema = z.object({
+  city: z.string().describe("City name"),
+  units: z.enum(['metric', 'imperial']).default('metric'),
+  includeForecast: z.boolean().optional(),
+  days: z.number().min(1).max(7).optional()
+});
+```
+
+**Nested Schema:**
+```typescript
+inputSchema = z.object({
+  user: z.object({
+    name: z.string(),
+    email: z.string().email()
+  }),
+  preferences: z.object({
+    notifications: z.boolean(),
+    language: z.string()
+  }).optional()
+});
+```
+
+**Supported Types:**
+- `z.string()` - String values
+- `z.number()` - Numeric values
+- `z.boolean()` - True/false
+- `z.enum([...])` - Fixed set of values
+- `z.array(T)` - Arrays
+- `z.object({...})` - Nested objects
+- `.optional()` - Optional fields
+- `.default(value)` - Default values
+
+---
+
+#### `execute: (input: any) => Promise<any>`
+
+Async function that implements the tool logic.
+
+**Signature:**
+```typescript
+async execute(input: z.infer<typeof this.inputSchema>) {
+  // Implementation
+  return result;
+}
+```
+
+**Input:**
+- Automatically validated against `inputSchema`
+- Type-safe when using `z.infer<typeof this.inputSchema>`
+
+**Return:**
+- Can return any JSON-serializable value
+- Should return structured data when possible
+
+**Error Handling:**
+```typescript
+async execute(input: any) {
+  // Throw descriptive errors
+  if (!input.id) {
+    throw new Error("ID is required");
+  }
+  
+  try {
+    const result = await externalApi.call(input);
+    return result;
+  } catch (error) {
+    // Re-throw with context
+    throw new Error(`Failed to call external API: ${error.message}`);
+  }
+}
+```
+
+---
+
+## Platform APIs
+
+The Lua CLI provides built-in APIs for common operations.
+
+### Importing
+
+```typescript
+import { User, Data, Products, Baskets, Orders } from 'lua-cli';
+```
+
+---
+
+## User API
+
+Access and manage user data.
+
+### `User.get()`
+
+Retrieves the current user's data.
+
+**Usage:**
+```typescript
+const user = await User.get();
+```
+
+**Returns:**
+```typescript
+{
+  id: string;
+  email: string;
+  name: string;
+  // ... additional user fields
+}
+```
+
+**Example:**
+```typescript
+export class GetUserDataTool implements LuaTool {
+  name = "get_user_data";
+  description = "Retrieve current user's information";
+  inputSchema = z.object({});
+
+  async execute(input: any) {
+    const user = await User.get();
+    return {
+      name: user.name,
+      email: user.email
+    };
+  }
+}
+```
+
+---
+
+## Data API
+
+Store and retrieve custom data with vector search.
+
+### `Data.create(collectionName, data, searchText?)`
+
+Creates a new entry in a collection.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `collectionName` | string | Yes | Collection name (e.g., 'movies', 'customers') |
+| `data` | object | Yes | Data to store (any JSON object) |
+| `searchText` | string | No | Text for vector search indexing |
+
+**Usage:**
+```typescript
+const entry = await Data.create('movies', {
+  title: 'Inception',
+  year: 2010,
+  director: 'Christopher Nolan'
+}, 'Inception 2010 Christopher Nolan sci-fi thriller');
+```
+
+**Returns:**
+```typescript
+{
+  id: string;
+  data: object;
+  createdAt: number;
+  updatedAt: number;
+  searchText?: string;
+}
+```
+
+---
+
+### `Data.get(collectionName, filter?, page?, limit?)`
+
+Retrieves entries from a collection.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `collectionName` | string | - | Collection name |
+| `filter` | object | {} | Filter criteria |
+| `page` | number | 1 | Page number |
+| `limit` | number | 10 | Items per page |
+
+**Usage:**
+```typescript
+// Get all
+const movies = await Data.get('movies');
+
+// With pagination
+const page2 = await Data.get('movies', {}, 2, 20);
+
+// With filter
+const recentMovies = await Data.get('movies', { year: { $gte: 2020 } });
+```
+
+**Returns:**
+```typescript
+{
+  data: Entry[];
+  pagination: {
+    currentPage: number;
+    totalPages: number;
+    totalCount: number;
+    // ...
+  };
+}
+```
+
+---
+
+### `Data.getEntry(collectionName, entryId)`
+
+Retrieves a specific entry by ID.
+
+**Usage:**
+```typescript
+const movie = await Data.getEntry('movies', 'entry_abc123');
+```
+
+---
+
+### `Data.update(collectionName, entryId, data)`
+
+Updates an existing entry.
+
+**Usage:**
+```typescript
+const updated = await Data.update('movies', 'entry_abc123', {
+  rating: 9.5,
+  reviews: 1000
+});
+```
+
+---
+
+### `Data.search(collectionName, searchText, limit?, scoreThreshold?)`
+
+Performs vector search on a collection.
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `collectionName` | string | - | Collection name |
+| `searchText` | string | - | Search query |
+| `limit` | number | 10 | Max results |
+| `scoreThreshold` | number | 0.7 | Min similarity (0-1) |
+
+**Usage:**
+```typescript
+const results = await Data.search(
+  'movies',
+  'sci-fi thriller about dreams',
+  5,
+  0.8
+);
+```
+
+**Returns:**
+```typescript
+{
+  data: Array<Entry & { score: number }>;
+  count: number;
+}
+```
+
+**Similarity Scores:**
+- `1.0` = Perfect match
+- `0.8-0.9` = Very similar
+- `0.6-0.7` = Somewhat similar
+- `<0.6` = Low similarity
+
+---
+
+### `Data.delete(collectionName, entryId)`
+
+Deletes an entry.
+
+**Usage:**
+```typescript
+await Data.delete('movies', 'entry_abc123');
+```
+
+---
+
+## Products API
+
+Manage product catalog.
+
+### `Products.get(limit?, page?)`
+
+Retrieves products with pagination.
+
+**Usage:**
+```typescript
+const products = await Products.get(20, 1);
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  data: Product[];
+  pagination: {
+    currentPage: number;
+    totalPages: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    // ...
+  };
+}
+```
+
+---
+
+### `Products.create(product)`
+
+Creates a new product.
+
+**Usage:**
+```typescript
+const product = await Products.create({
+  name: 'Laptop',
+  price: 999.99,
+  category: 'Electronics',
+  sku: 'LAP-001',
+  inStock: true
+});
+```
+
+**Returns:**
+```typescript
+{
+  updated: boolean;
+  isNew: boolean;
+  product: Product;
+}
+```
+
+---
+
+### `Products.update(data, id)`
+
+Updates an existing product.
+
+**Usage:**
+```typescript
+const updated = await Products.update({
+  price: 899.99,
+  inStock: false
+}, 'product_abc123');
+```
+
+---
+
+### `Products.delete(id)`
+
+Deletes a product.
+
+**Usage:**
+```typescript
+await Products.delete('product_abc123');
+```
+
+---
+
+### `Products.search(query)`
+
+Searches products.
+
+**Usage:**
+```typescript
+const results = await Products.search('laptop');
+```
+
+**Returns:**
+```typescript
+{
+  success: boolean;
+  data: Product[];
+}
+```
+
+---
+
+### `Products.getById(id)`
+
+Gets a specific product.
+
+**Usage:**
+```typescript
+const product = await Products.getById('product_abc123');
+```
+
+---
+
+## Baskets API
+
+Manage shopping baskets.
+
+### `Baskets.create(basketData)`
+
+Creates a new basket.
+
+**Usage:**
+```typescript
+const basket = await Baskets.create({
+  currency: 'USD',
+  metadata: {
+    source: 'web',
+    campaign: 'summer_sale'
+  }
+});
+```
+
+---
+
+### `Baskets.get(status?)`
+
+Gets baskets, optionally filtered by status.
+
+**Usage:**
+```typescript
+// All baskets
+const allBaskets = await Baskets.get();
+
+// Active baskets only
+const activeBaskets = await Baskets.get(BasketStatus.ACTIVE);
+```
+
+**Basket Statuses:**
+```typescript
+import { BasketStatus } from 'lua-cli';
+
+BasketStatus.ACTIVE        // Currently being used
+BasketStatus.CHECKED_OUT   // Converted to order
+BasketStatus.ABANDONED     // User left without checkout
+BasketStatus.EXPIRED       // TTL exceeded
+```
+
+---
+
+### `Baskets.addItem(basketId, itemData)`
+
+Adds an item to a basket.
+
+**Usage:**
+```typescript
+const updated = await Baskets.addItem('basket_abc123', {
+  id: 'product_xyz',
+  price: 29.99,
+  quantity: 2,
+  SKU: 'SHIRT-M-BLUE'
+});
+```
+
+---
+
+### `Baskets.removeItem(basketId, itemId)`
+
+Removes an item from a basket.
+
+**Usage:**
+```typescript
+await Baskets.removeItem('basket_abc123', 'item_xyz');
+```
+
+---
+
+### `Baskets.clear(basketId)`
+
+Removes all items from a basket.
+
+**Usage:**
+```typescript
+await Baskets.clear('basket_abc123');
+```
+
+---
+
+### `Baskets.updateStatus(basketId, status)`
+
+Updates basket status.
+
+**Usage:**
+```typescript
+await Baskets.updateStatus('basket_abc123', BasketStatus.ABANDONED);
+```
+
+---
+
+### `Baskets.updateMetadata(basketId, metadata)`
+
+Updates basket metadata.
+
+**Usage:**
+```typescript
+await Baskets.updateMetadata('basket_abc123', {
+  notes: 'Gift wrapping requested',
+  deliveryDate: '2025-12-25'
+});
+```
+
+---
+
+### `Baskets.placeOrder(orderData, basketId)`
+
+Converts basket to order.
+
+**Usage:**
+```typescript
+const order = await Baskets.placeOrder({
+  shippingAddress: {
+    street: '123 Main St',
+    city: 'New York',
+    zip: '10001'
+  },
+  paymentMethod: 'credit_card'
+}, 'basket_abc123');
+```
+
+---
+
+### `Baskets.getById(basketId)`
+
+Gets a specific basket.
+
+**Usage:**
+```typescript
+const basket = await Baskets.getById('basket_abc123');
+```
+
+---
+
+## Orders API
+
+Manage orders.
+
+### `Orders.create(orderData)`
+
+Creates a new order.
+
+**Usage:**
+```typescript
+const order = await Orders.create({
+  basketId: 'basket_abc123',
+  data: {
+    shippingAddress: {...},
+    paymentMethod: 'stripe'
+  }
+});
+```
+
+---
+
+### `Orders.updateStatus(status, orderId)`
+
+Updates order status.
+
+**Usage:**
+```typescript
+await Orders.updateStatus(OrderStatus.FULFILLED, 'order_abc123');
+```
+
+**Order Statuses:**
+```typescript
+import { OrderStatus } from 'lua-cli';
+
+OrderStatus.PENDING     // Created, not confirmed
+OrderStatus.CONFIRMED   // Confirmed, being processed
+OrderStatus.FULFILLED   // Completed and delivered
+OrderStatus.CANCELLED   // Cancelled
+```
+
+---
+
+### `Orders.updateData(data, orderId)`
+
+Updates order data.
+
+**Usage:**
+```typescript
+await Orders.updateData({
+  trackingNumber: 'TRACK123',
+  estimatedDelivery: '2025-10-10'
+}, 'order_abc123');
+```
+
+---
+
+### `Orders.get(status?)`
+
+Gets orders, optionally filtered by status.
+
+**Usage:**
+```typescript
+// All orders
+const allOrders = await Orders.get();
+
+// Pending orders only
+const pending = await Orders.get(OrderStatus.PENDING);
+```
+
+---
+
+### `Orders.getById(orderId)`
+
+Gets a specific order.
+
+**Usage:**
+```typescript
+const order = await Orders.getById('order_abc123');
+```
+
+---
+
+## Environment Variables
+
+### `env(key: string): string | undefined`
+
+Safely access environment variables.
+
+**Usage:**
+```typescript
+import { env } from 'lua-cli';
+
+export class MyTool implements LuaTool {
+  async execute(input: any) {
+    const apiKey = env('EXTERNAL_API_KEY');
+    const baseUrl = env('API_BASE_URL') || 'https://default.com';
+    
+    if (!apiKey) {
+      throw new Error('EXTERNAL_API_KEY not configured');
+    }
+    
+    // Use environment variables...
+  }
+}
+```
+
+**Loading Priority:**
+1. Process environment variables
+2. `.env` file in project root
+3. `lua.skill.yaml` under `skill.env`
+
+**Configuration:**
+
+```yaml
+# lua.skill.yaml
+skill:
+  env:
+    EXTERNAL_API_KEY: sk_abc123
+    API_BASE_URL: https://api.example.com
+```
+
+Or create `.env` file:
+```bash
+# .env
+EXTERNAL_API_KEY=sk_abc123
+API_BASE_URL=https://api.example.com
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Weather Tool
+
+```typescript
+import { LuaTool, env } from 'lua-cli';
+import { z } from 'zod';
+
+export default class GetWeatherTool implements LuaTool {
+  name = "get_weather";
+  description = "Get current weather conditions for any city";
+  
+  inputSchema = z.object({
+    city: z.string().describe("City name (e.g., 'London', 'New York')"),
+    units: z.enum(['metric', 'imperial']).optional().describe("Temperature units")
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const { city, units = 'metric' } = input;
+    
+    // Call weather API (using free Open-Meteo API)
+    const geoUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`;
+    const geoRes = await fetch(geoUrl);
+    const geoData = await geoRes.json();
+    
+    if (!geoData.results?.[0]) {
+      throw new Error(`City not found: ${city}`);
+    }
+    
+    const { latitude, longitude, name } = geoData.results[0];
+    
+    const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current_weather=true&temperature_unit=${units === 'imperial' ? 'fahrenheit' : 'celsius'}`;
+    const weatherRes = await fetch(weatherUrl);
+    const weatherData = await weatherRes.json();
+    
+    const current = weatherData.current_weather;
+    
+    return {
+      city: name,
+      temperature: current.temperature,
+      windSpeed: current.windspeed,
+      condition: current.weathercode
+    };
+  }
+}
+```
+
+---
+
+### Example 2: E-commerce Tool
+
+```typescript
+import { LuaTool, Products, Baskets } from 'lua-cli';
+import { z } from 'zod';
+
+export default class AddToCartTool implements LuaTool {
+  name = "add_to_cart";
+  description = "Add a product to the shopping cart";
+  
+  inputSchema = z.object({
+    productId: z.string().describe("Product ID to add"),
+    quantity: z.number().min(1).describe("Quantity to add"),
+    basketId: z.string().optional().describe("Existing basket ID (creates new if not provided)")
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const { productId, quantity, basketId } = input;
+    
+    // Get product details
+    const product = await Products.getById(productId);
+    
+    // Get or create basket
+    let basket;
+    if (basketId) {
+      basket = await Baskets.getById(basketId);
+    } else {
+      basket = await Baskets.create({
+        currency: 'USD',
+        metadata: { source: 'chat' }
+      });
+    }
+    
+    // Add item to basket
+    const updated = await Baskets.addItem(basket.id, {
+      id: productId,
+      price: product.price,
+      quantity: quantity,
+      SKU: product.sku
+    });
+    
+    return {
+      basketId: updated.id,
+      itemCount: updated.common.itemCount,
+      totalAmount: updated.common.totalAmount,
+      message: `Added ${quantity}x ${product.name} to cart`
+    };
+  }
+}
+```
+
+---
+
+### Example 3: Custom Data with Search
+
+```typescript
+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()
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // Create searchable text
+    const searchText = `${input.title} ${input.year} ${input.director} ${input.genre}`;
+    
+    const movie = await Data.create('movies', input, searchText);
+    
+    return {
+      id: movie.id,
+      message: `Created movie: ${input.title}`
+    };
+  }
+}
+
+export class SearchMoviesTool implements LuaTool {
+  name = "search_movies";
+  description = "Search for movies by title, director, or genre";
+  
+  inputSchema = z.object({
+    query: z.string().describe("Search query")
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const results = await Data.search('movies', input.query, 10, 0.7);
+    
+    return {
+      movies: results.data.map(entry => ({
+        id: entry.id,
+        ...entry.data,
+        relevance: entry.score
+      })),
+      count: results.count
+    };
+  }
+}
+```
+
+---
+
+### Example 4: Multi-Step Tool
+
+```typescript
+import { LuaTool, Products, Baskets, Orders } from 'lua-cli';
+import { z } from 'zod';
+
+export default class QuickCheckoutTool implements LuaTool {
+  name = "quick_checkout";
+  description = "Search for product, add to cart, and create order in one step";
+  
+  inputSchema = z.object({
+    productName: z.string(),
+    quantity: z.number().default(1),
+    shippingAddress: z.object({
+      street: z.string(),
+      city: z.string(),
+      zip: z.string()
+    })
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // Step 1: Search for product
+    const searchResults = await Products.search(input.productName);
+    if (searchResults.data.length === 0) {
+      throw new Error(`Product not found: ${input.productName}`);
+    }
+    
+    const product = searchResults.data[0];
+    
+    // Step 2: Create basket
+    const basket = await Baskets.create({ currency: 'USD' });
+    
+    // Step 3: Add product to basket
+    await Baskets.addItem(basket.id, {
+      id: product.id,
+      price: product.price,
+      quantity: input.quantity
+    });
+    
+    // Step 4: Create order
+    const order = await Baskets.placeOrder({
+      shippingAddress: input.shippingAddress,
+      paymentMethod: 'stripe'
+    }, basket.id);
+    
+    return {
+      orderId: order.id,
+      product: product.name,
+      quantity: input.quantity,
+      total: basket.common.totalAmount,
+      message: 'Order created successfully'
+    };
+  }
+}
+```
+
+---
+
+### Example 5: Using Environment Variables
+
+```typescript
+import { LuaTool, env } from 'lua-cli';
+import { z } from 'zod';
+
+export default class SendEmailTool implements LuaTool {
+  name = "send_email";
+  description = "Send an email via external service";
+  
+  inputSchema = z.object({
+    to: z.string().email(),
+    subject: z.string(),
+    body: z.string()
+  });
+
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // Get API credentials from environment
+    const apiKey = env('SENDGRID_API_KEY');
+    const fromEmail = env('FROM_EMAIL');
+    
+    if (!apiKey) {
+      throw new Error('SENDGRID_API_KEY not configured');
+    }
+    
+    // Call external API
+    const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        personalizations: [{
+          to: [{ email: input.to }]
+        }],
+        from: { email: fromEmail || 'noreply@example.com' },
+        subject: input.subject,
+        content: [{
+          type: 'text/plain',
+          value: input.body
+        }]
+      })
+    });
+    
+    if (!response.ok) {
+      throw new Error(`Email sending failed: ${response.statusText}`);
+    }
+    
+    return {
+      success: true,
+      message: `Email sent to ${input.to}`
+    };
+  }
+}
+```
+
+---
+
+## Type Definitions
+
+### Importing Types
+
+```typescript
+import {
+  LuaSkill,
+  LuaTool,
+  BasketStatus,
+  OrderStatus,
+  env
+} from 'lua-cli';
+```
+
+### Full Type Signature
+
+```typescript
+interface LuaTool<TInput extends ZodType = ZodType> {
+  name: string;
+  description: string;
+  inputSchema: TInput;
+  execute: (input: z.infer<TInput>) => Promise<any>;
+}
+```
+
+---
+
+## Best Practices
+
+### Tool Design
+
+**✅ Do:**
+- Use clear, descriptive names
+- Write detailed descriptions
+- Validate all inputs with Zod
+- Return structured data
+- Handle errors gracefully
+- Use environment variables for secrets
+
+**❌ Don't:**
+- Use spaces in tool names
+- Hardcode API keys
+- Return unstructured strings
+- Ignore input validation
+- Swallow errors silently
+
+---
+
+### Error Handling
+
+```typescript
+async execute(input: any) {
+  try {
+    // Validate business logic
+    if (input.amount <= 0) {
+      throw new Error("Amount must be positive");
+    }
+    
+    // Call external service
+    const result = await externalApi.call(input);
+    
+    // Validate response
+    if (!result.success) {
+      throw new Error(`API error: ${result.error}`);
+    }
+    
+    return result.data;
+    
+  } catch (error) {
+    // Add context to errors
+    throw new Error(`Failed to process request: ${error.message}`);
+  }
+}
+```
+
+---
+
+### Schema Design
+
+**Simple and Clear:**
+```typescript
+inputSchema = z.object({
+  email: z.string().email().describe("User's email address"),
+  amount: z.number().positive().describe("Amount in USD"),
+  sendReceipt: z.boolean().default(true).describe("Send email receipt")
+});
+```
+
+**With Validation:**
+```typescript
+inputSchema = z.object({
+  age: z.number().min(0).max(120),
+  email: z.string().email(),
+  password: z.string().min(8),
+  phone: z.string().regex(/^\+?[1-9]\d{1,14}$/),
+  url: z.string().url()
+});
+```
+
+---
+
+## Testing Your Skills
+
+### Local Testing
+
+```bash
+# Interactive testing
+lua test
+
+# Select tool, enter inputs, see results
+```
+
+### Development Mode
+
+```bash
+# Start dev mode
+lua dev
+
+# Chat interface opens at http://localhost:3000
+# Edit files - auto-reloads
+# Test conversational interaction
+```
+
+### Production Testing
+
+```bash
+# Push to server
+lua push
+
+# Test in sandbox before deploying
+lua dev
+
+# Deploy when ready
+lua deploy
+```
+
+---
+
+## TypeScript Support
+
+All Lua APIs are fully typed:
+
+```typescript
+import { User, Products, Data } from 'lua-cli';
+
+// Autocomplete and type checking work!
+const user = await User.get();        // user is typed
+const products = await Products.get(); // products is typed
+const data = await Data.get('movies'); // data is typed
+```
+
+---
+
+## Common Patterns
+
+### Pattern: Conditional Tool Execution
+
+```typescript
+async execute(input: any) {
+  if (input.query) {
+    // Search path
+    return await Products.search(input.query);
+  } else {
+    // List all path
+    return await Products.get(20, 1);
+  }
+}
+```
+
+### Pattern: Data Transformation
+
+```typescript
+async execute(input: any) {
+  const products = await Products.get(100);
+  
+  // Transform for AI consumption
+  return products.data.map(p => ({
+    name: p.name,
+    price: `$${p.price}`,
+    available: p.inStock ? 'Yes' : 'No'
+  }));
+}
+```
+
+### Pattern: Error Recovery
+
+```typescript
+async execute(input: any) {
+  try {
+    return await externalApi.call(input);
+  } catch (error) {
+    // Fallback behavior
+    console.warn('External API failed, using fallback');
+    return await fallbackService.call(input);
+  }
+}
+```
+
+---
+
+## Limits and Quotas
+
+- **Vector Search**: `scoreThreshold` 0-1 (0.7 recommended minimum)
+- **Pagination**: Default 10 items, max 100 per page
+- **Tool Names**: 1-50 characters, alphanumeric + `-` `_` only
+- **Data Storage**: No hard limits on custom data collections
+
+---
+
+## Additional Resources
+
+- **CLI Commands**: See `CLI_REFERENCE.md`
+- **Template Guide**: See `TEMPLATE_GUIDE.md`
+- **Development**: See `DEVELOPER_GUIDE.md`
+- **Examples**: Check `template/src/tools/` directory
+- **Platform Docs**: https://docs.lua.ai
+
+---
+
+## Support
+
+- **Issues**: https://github.com/lua-ai/lua-cli/issues
+- **Docs**: https://docs.lua.ai
+- **Email**: support@lua.ai
+