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

package/README.md

@@ -1,545 +1,859 @@
 # Lua CLI
 
-A powerful command-line interface for the Lua AI platform that helps you develop, test, and deploy LuaSkills with custom tools.
+Build AI agents with custom capabilities using TypeScript.
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/lua-cli.svg)](https://www.npmjs.com/package/lua-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 🎯 What is Lua CLI?
+
+Lua CLI is a powerful command-line tool for building, testing, and deploying AI skills. A **skill** is a collection of **tools** (functions) that your AI agent can use to accomplish tasks.
+
+**Think of it like:**
+- 🤖 **AI Agent** = Your assistant (like ChatGPT)
+- 🎯 **Skills** = What it can do (your custom capabilities)
+- 🛠️ **Tools** = Specific functions (e.g., "get weather", "create order")
+
+---
+
+## ⚡ Quick Start
 
 ```bash
+# Install
 npm install -g lua-cli
+
+# Authenticate
+lua auth configure
+
+# Create a project
+mkdir my-skill && cd my-skill
+lua init
+
+# Test locally
+lua test
+
+# Start dev mode
+lua dev
 ```
 
-## Usage
+**Done!** Your AI skill is running at http://localhost:3000 🎉
+
+---
+
+## 📦 Installation
+
+### Global Installation (Recommended)
 
-After installation, you can use the `lua` command:
+```bash
+npm install -g lua-cli
+```
+
+### Using npx (No Installation)
 
 ```bash
-lua --help
+npx lua-cli [command]
 ```
 
-## Features
+### Requirements
 
-- 🔐 **Secure Authentication**: Support for both API key and email-based OTP authentication
-- 🏢 **Organization Management**: Select and manage multiple organizations
-- 🤖 **Agent Management**: Choose from available agents within your organizations
-- 🛠️ **Skill Development**: Initialize new Lua skills with proper configuration
-- 🔧 **Tool Development**: Create custom tools with TypeScript and Zod validation
-- 📦 **Dependency Bundling**: Automatic bundling of npm packages using esbuild
-- 🧪 **Interactive Testing**: Test your tools with real-time execution
-- 🚀 **Deployment**: Compile and deploy skills to the Lua platform
-- 🔑 **API Key Management**: Securely store, view, and manage your API keys
-- 💾 **User Data API**: Built-in API for persistent user data storage in your tools
-- 📚 **Comprehensive Documentation**: Complete guides and examples
+- **Node.js** 16.0.0 or higher
+- **npm** 7.0.0 or higher
+- **TypeScript** knowledge (for development)
 
-## Quick Start
+---
 
-1. **Configure your authentication:**
-   ```bash
-   lua auth configure
-   ```
-   Choose between API key or email authentication methods.
+## 🚀 Features
 
-2. **Initialize a new skill project:**
-   ```bash
-   lua skill init
-   ```
-   Choose between selecting an existing agent or creating a new one, then provide skill details.
+### For Developers
+- 🔨 **TypeScript-first** - Full type safety and autocomplete
+- 🎨 **Template System** - 30+ example tools to learn from
+- 🧪 **Interactive Testing** - Test tools before deployment
+- 🔄 **Live Reload** - Dev mode with automatic recompilation
+- 📦 **Auto Bundling** - Dependencies bundled automatically with esbuild
+- ✅ **Input Validation** - Zod schema validation built-in
 
-3. **Develop your tools:**
-   ```bash
-   # Create tools in the tools/ directory
-   # See template/README.md for examples
-   ```
+### For Operations
+- 🔐 **Secure Auth** - API key or email OTP authentication
+- 🌐 **Multi-Skill** - Multiple skills in one project
+- 📊 **Version Management** - Push, test, and deploy versions
+- 🎯 **Sandbox Testing** - Test in isolation before production
+- 📝 **Environment Variables** - Secure configuration management
 
-4. **Compile your skill:**
-   ```bash
-   lua skill compile
-   ```
-   Bundles dependencies and creates deployable files.
+### For Users
+- 💬 **Chat Interface** - Test your AI in real conversations
+- 🔍 **Tool Explorer** - Browse and test individual tools
+- 📊 **Real-time Logs** - WebSocket log streaming
+- 🎨 **Beautiful UI** - Modern, intuitive interface
 
-5. **Test your tools:**
-   ```bash
-   lua skill test
-   ```
-   Interactive testing interface for your tools.
+---
 
-6. **Deploy your skill:**
-   ```bash
-   lua skill deploy
-   ```
-   Deploy to the Lua platform.
+## 📖 Documentation
 
-## Commands
+### 📘 **For Beginners**
+**[Getting Started Guide](GETTING_STARTED.md)** - Zero to deployed skill in one hour
+- Installation and setup
+- Your first skill
+- Step-by-step tutorial
+- Complete restaurant skill example
 
-### Authentication Commands
+### 🔧 **For Developers**
+**[API Reference](API_REFERENCE.md)** - Complete API documentation
+- All exported APIs (User, Data, Products, Baskets, Orders)
+- Type definitions
+- Code examples
+- Best practices
 
-#### `lua auth configure`
+**[Template Guide](TEMPLATE_GUIDE.md)** - Understanding the example project
+- Template structure explained
+- 30+ tool examples
+- Building your first skill
+- Common patterns and recipes
 
-Set up your authentication credentials. You can choose between:
+### 💻 **For CLI Users**
+**[CLI Reference](CLI_REFERENCE.md)** - All command documentation
+- Complete command reference
+- Flags and options
+- Workflow examples
+- Troubleshooting
 
-- **API Key**: Direct API key input
-- **Email**: Email-based OTP authentication
+### 🏗️ **For Contributors**
+**[Developer Guide](DEVELOPER_GUIDE.md)** - Architecture and internals
+- Codebase structure
+- Module organization
+- Contributing guidelines
 
-```bash
-lua auth configure
-```
+---
 
-#### `lua auth key`
+## 🎓 Core Concepts
 
-Display your stored API key (with confirmation prompt).
+### Skills
 
-```bash
-lua auth key
+A skill is a collection of related tools:
+
+```typescript
+import { LuaSkill } from 'lua-cli';
+
+const weatherSkill = new LuaSkill({
+  name: "weather-skill",
+  version: "1.0.0",
+  description: "Provides weather information",
+  context: "Use get_weather when users ask about weather...",
+  tools: [
+    new GetWeatherTool(),
+    new GetForecastTool()
+  ]
+});
 ```
 
-#### `lua auth logout`
+### Tools
 
-Delete your stored API key and credentials.
+A tool is a single function the AI can call:
 
-```bash
-lua auth logout
+```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()
+  });
+
+  async execute(input: any) {
+    // Call weather API
+    return {
+      temperature: 72,
+      condition: "sunny",
+      city: input.city
+    };
+  }
+}
 ```
 
-### Skill Management Commands
+### Platform APIs
 
-#### `lua skill init`
+Built-in APIs for common operations:
 
-Initialize a new Lua skill project in the current directory.
+```typescript
+import { User, Data, Products, Baskets, Orders } from 'lua-cli';
 
-```bash
-lua skill init
+// User data
+const user = await User.get();
+
+// Custom data with vector search
+await Data.create('movies', movieData, searchText);
+const results = await Data.search('movies', 'sci-fi thriller');
+
+// Products
+const products = await Products.search('laptop');
+
+// Shopping baskets
+const basket = await Baskets.create({ currency: 'USD' });
+await Baskets.addItem(basketId, { id, price, quantity });
+
+// Orders
+const order = await Baskets.placeOrder(orderData, basketId);
 ```
 
-This command will:
-- Fetch your organizations and agents from the API
-- Let you select an organization by name
-- **Choose between existing agents or creating a new one:**
-  - **Existing Agent**: Select from your current agents
-  - **New Agent**: Create a custom agent with:
-    - Agent type selection (Base Agent, Shopify, WooCommerce, etc.)
-    - Required metadata collection (API keys, IDs, etc.)
-    - Feature configuration (RAG, tickets, web search, etc.)
-    - Business information (name, type, personality, traits)
-    - Automatic persona generation and welcome message
-- Prompt for skill name and description
-- Create a `lua.skill.yaml` configuration file with agent details
-- Copy template files to the current directory
+---
 
-#### `lua skill compile`
+## 💡 Examples
 
-Compile your LuaSkill and bundle all dependencies.
+### Example 1: Simple Weather Tool
 
-```bash
-lua skill compile
+```typescript
+import { LuaTool } from 'lua-cli';
+import { z } from 'zod';
+
+export default class WeatherTool implements LuaTool {
+  name = "get_weather";
+  description = "Get weather for any city";
+  inputSchema = z.object({ city: z.string() });
+
+  async execute(input: any) {
+    const response = await fetch(
+      `https://api.open-meteo.com/v1/forecast?city=${input.city}`
+    );
+    const data = await response.json();
+    return { temperature: data.temp, condition: data.condition };
+  }
+}
 ```
 
-This command will:
-- Scan your tools for imports and dependencies
-- Bundle external packages using esbuild
-- Compress the generated code for efficient storage
-- Create `.lua/deploy.json` with compiled skill data
-- Generate individual tool files in `.lua/` directory
+### Example 2: E-commerce Tool
 
-**Options:**
-- `--watch` - Watch for changes and recompile automatically
-- `--minify` - Minify the bundled code
+```typescript
+import { LuaTool, Products, Baskets } from 'lua-cli';
+import { z } from 'zod';
 
-#### `lua skill test`
+export default class AddToCartTool implements LuaTool {
+  name = "add_to_cart";
+  description = "Add product to shopping cart";
+  
+  inputSchema = z.object({
+    productId: z.string(),
+    quantity: z.number().min(1)
+  });
+
+  async execute(input: any) {
+    const product = await Products.getById(input.productId);
+    const basket = await Baskets.create({ currency: 'USD' });
+    
+    await Baskets.addItem(basket.id, {
+      id: input.productId,
+      price: product.price,
+      quantity: input.quantity
+    });
+    
+    return {
+      basketId: basket.id,
+      message: `Added ${input.quantity}x ${product.name} to cart`
+    };
+  }
+}
+```
 
-Interactive testing interface for your tools.
+### Example 3: Custom Data with Search
 
-```bash
-lua skill test
+```typescript
+import { LuaTool, Data } from 'lua-cli';
+import { z } from 'zod';
+
+export class CreateMovieTool implements LuaTool {
+  name = "create_movie";
+  description = "Add a movie to the database";
+  
+  inputSchema = z.object({
+    title: z.string(),
+    director: z.string(),
+    year: z.number()
+  });
+
+  async execute(input: any) {
+    const searchText = `${input.title} ${input.director} ${input.year}`;
+    const movie = await Data.create('movies', input, searchText);
+    return { id: movie.id, message: 'Movie added' };
+  }
+}
+
+export class SearchMoviesTool implements LuaTool {
+  name = "search_movies";
+  description = "Search movies by title, director, or year";
+  inputSchema = z.object({ query: z.string() });
+
+  async execute(input: any) {
+    const results = await Data.search('movies', input.query, 10, 0.7);
+    return { movies: results.data, count: results.count };
+  }
+}
 ```
 
-Features:
-- Tool selection menu
-- Input validation with Zod schemas
-- Real-time execution in isolated VM context
-- Error reporting and debugging
-- Mock data support
+---
 
-#### `lua skill push`
+## 🎯 Commands
 
-Push your compiled skill version to the server.
+### Authentication
+```bash
+lua auth configure    # Set up API key
+lua auth key          # Display API key
+lua auth logout       # Delete API key
+```
 
+### Skill Management
 ```bash
-lua skill push
+lua init              # Create new skill project
+lua compile           # Compile TypeScript to deployable format
+lua test              # Test tools interactively
+lua push              # Upload version to server
+lua deploy            # Deploy version to production
+lua dev               # Development mode with live reload
 ```
 
-This command will:
-- Compile your skill first
-- Confirm the version you want to push
-- Send the compiled skill data to the server
-- Store the skill ID in your YAML file
+**See [CLI_REFERENCE.md](CLI_REFERENCE.md) for complete command documentation.**
+
+---
 
-#### `lua skill dev`
+## 🛠️ Development Workflow
 
-Push your compiled skill version to the sandbox for development and testing with automatic file watching and web chat interface.
+### Local Development
 
 ```bash
-lua skill dev
-```
-
-This command will:
-- Compile your skill first
-- Confirm the version you want to push to sandbox
-- **Smart Sandbox Management**:
-  - If you have a previous sandbox skill ID stored, it will try to update the existing sandbox
-  - If the update fails or no sandbox exists, it will create a new one
-  - The sandbox skill ID is securely stored on your machine for future use
-- Display the sandbox skill ID for testing
-- **Web Chat Interface**:
-  - Automatically opens a beautiful chat interface in your browser
-  - Test your sandbox skill in real-time with natural language
-  - Messages are sent to the sandbox environment via the chat API
-  - Available at `http://localhost:3000` (opens automatically)
-- **Live Log Panel**:
-  - Real-time log feed showing execution details
-  - WebSocket connection to `wss://api.heylua.ai/feed`
-  - Console-style interface with color-coded log levels
-  - Shows tool calls, errors, metrics, and execution metadata
-  - Displays detailed information in expandable sections
-  - Connection status indicator and automatic reconnection
-  - Supports log types: error, debug, warn, info
-- **File Watching Mode**:
-  - Watches for file changes in the current directory
-  - Automatically recompiles and pushes to sandbox when files change
-  - Ignores build artifacts (`.lua/`, `node_modules/`, `.git/`, etc.)
-  - Debounces rapid changes to prevent excessive builds
-  - Press `Ctrl+C` to stop watching and exit
-
-#### `lua skill deploy`
-
-Deploy a version to production.
+# Start dev mode
+lua dev
+
+# Make changes to src/tools/*.ts
+# Save → Auto-recompiles → Auto-pushes to sandbox
+# Test in browser at http://localhost:3000
+```
+
+### Testing
 
 ```bash
-lua skill deploy
-```
-
-This command will:
-- Fetch available versions from the server
-- Let you select which version to deploy
-- Show a warning about deploying to all users
-- Publish the selected version to production
-
-**Requirements:**
-- Valid API key (configured with `lua auth configure`)
-- Compiled skill (run `lua skill compile` first)
-- Active internet connection
-
-## Template System
-
-The Lua CLI includes a comprehensive template system with examples and documentation:
-
-### Template Structure
-```
-template/
-├── README.md              # Complete user guide
-├── DEVELOPER.md           # Technical documentation  
-├── API.md                 # API reference
-├── QUICKSTART.md          # Quick start guide
-├── tools/                 # Example tools
-│   ├── GetWeatherTool.ts
-│   ├── GetUserDataTool.ts
-│   ├── CreatePostTool.ts
-│   ├── CalculatorTool.ts
-│   └── AdvancedMathTool.ts
-├── services/              # Example services
-│   ├── ApiService.ts
-│   ├── GetWeather.ts
-│   └── MathService.ts
-└── index.ts               # Main skill definition
-```
-
-### Getting Started with Templates
-
-1. **Copy the template:**
-   ```bash
-   cp -r template/ my-skill/
-   cd my-skill
-   ```
-
-2. **Install dependencies:**
-   ```bash
-   npm install
-   ```
-
-3. **Read the documentation:**
-   ```bash
-   # Start with the quick start guide
-   cat QUICKSTART.md
-   
-   # Then read the full documentation
-   cat README.md
-   ```
-
-4. **Create your tools:**
-   ```bash
-   # Modify existing tools or create new ones
-   # See tools/ directory for examples
-   ```
-
-## Configuration File
-
-The `lua.skill.yaml` file is created when you run `lua skill init`:
+# Test individual tools
+lua test
 
-```yaml
-agent:
-  agentId: "your-agent-id"
-  orgId: "your-organization-id"
-  persona: "Generated persona description" # Only for newly created agents
-  welcomeMessage: "Welcome message" # Only for newly created agents
+# Test conversationally
+lua dev
+# Use chat interface
+```
 
-skill:
-  name: "Your Skill Name"
-  version: "0.0.1"
-  skillId: "your-skill-id"
+### Deployment
+
+```bash
+# Upload new version
+lua push
+
+# Deploy to production
+lua deploy
 ```
 
-## Authentication Methods
+---
 
-### API Key Authentication
+## 📚 Built-in APIs
 
-1. Run `lua auth configure`
-2. Select "API Key"
-3. Enter your API key when prompted
-4. The key is validated and stored securely
+### User API
+```typescript
+import { User } from 'lua-cli';
 
-### Email Authentication
+const user = await User.get();
+```
 
-1. Run `lua auth configure`
-2. Select "Email"
-3. Enter your email address
-4. Check your email for the OTP code
-5. Enter the 6-digit OTP code
-6. An API key is automatically generated and stored
+### Custom Data API (with Vector Search)
+```typescript
+import { Data } from 'lua-cli';
 
-## Security
+await Data.create('collection', data, searchText);
+const results = await Data.search('collection', 'query', limit, threshold);
+```
 
-- All API keys are stored securely using your system's credential manager
-- Email authentication uses OTP (One-Time Password) for secure verification
-- Confirmation prompts prevent accidental exposure of sensitive information
-- No credentials are stored in plain text
+### Products API
+```typescript
+import { Products } from 'lua-cli';
 
-## Development Workflow
+const products = await Products.search('laptop');
+await Products.create({ name, price });
+```
 
-### 1. Project Setup
-```bash
-# Initialize a new skill project
-lua skill init
+### Baskets API
+```typescript
+import { Baskets, BasketStatus } from 'lua-cli';
 
-# Or copy the template
-cp -r template/ my-skill/
-cd my-skill
-npm install
+const basket = await Baskets.create({ currency: 'USD' });
+await Baskets.addItem(basketId, { id, price, quantity });
 ```
 
-### 2. Tool Development
-```bash
-# Create tools in tools/ directory
-# Use TypeScript with Zod validation
-# See template/tools/ for examples
+### Orders API
+```typescript
+import { Orders, OrderStatus } from 'lua-cli';
+
+const order = await Baskets.placeOrder(orderData, basketId);
+await Orders.updateStatus(OrderStatus.FULFILLED, orderId);
 ```
 
-### 3. Testing
-```bash
-# Compile your skill
-lua skill compile
+**See [API_REFERENCE.md](API_REFERENCE.md) for complete API documentation.**
+
+---
+
+## 🎨 Template Project
+
+The template includes 30+ working examples:
+
+- 🌤️ **Weather Tool** - External API integration
+- 👤 **User Data Tools** - User management
+- 🛍️ **Product Tools** - E-commerce catalog
+- 🛒 **Basket Tools** - Shopping cart
+- 📦 **Order Tools** - Order processing
+- 🎬 **Custom Data Tools** - Vector search
+- 💳 **Payment Tool** - Payment integration
+
+**See [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md) for complete template documentation.**
 
-# Test your tools interactively
-lua skill test
+---
+
+## 🔒 Security
+
+- ✅ API keys stored in system keychain
+- ✅ Environment variables for secrets
+- ✅ Secure VM sandbox for tool execution
+- ✅ No hardcoded credentials
+- ✅ HTTPS for all API calls
+
+**Best Practices:**
+```typescript
+import { env } from 'lua-cli';
+
+// ✅ Good - Use environment variables
+const apiKey = env('EXTERNAL_API_KEY');
+
+// ❌ Bad - Hardcoded secrets
+const apiKey = 'sk_abc123';
 ```
 
-### 4. Deployment
-```bash
-# Push version to server
-lua skill push
+---
 
-# Deploy to production
-lua skill deploy
+## 🧪 Testing
+
+### Unit Testing
+
+```typescript
+import { describe, it, expect } from '@jest/globals';
+import MyTool from './tools/MyTool';
+
+describe('MyTool', () => {
+  it('should return expected result', async () => {
+    const tool = new MyTool();
+    const result = await tool.execute({ input: 'test' });
+    expect(result).toHaveProperty('success');
+  });
+});
 ```
 
-### 5. Iteration
+### Interactive Testing
+
 ```bash
-# Make changes to your tools
-# Recompile and test
-lua skill compile && lua skill test
+lua test
+# Select tool → Enter inputs → See results
+```
 
-# Push updates
-lua skill push
+### Conversational Testing
 
-# Deploy updates
-lua skill deploy
+```bash
+lua dev
+# Chat with AI at http://localhost:3000
 ```
 
-## Requirements
+---
 
-- Node.js 16.0.0 or higher
-- Valid Lua AI platform account
-- TypeScript knowledge (for tool development)
-- Basic understanding of Zod schemas
+## 🎯 Use Cases
 
-## Development
+### Customer Service
+- Answer FAQs from knowledge base
+- Look up order status
+- Create support tickets
+- Search documentation
 
-To contribute to this project:
+### E-commerce
+- Product search and recommendations
+- Shopping cart management
+- Order creation and tracking
+- Inventory checks
 
-1. Clone the repository
-2. Install dependencies: `npm install`
-3. Build the project: `npm run build`
-4. Make your changes
-5. Test your changes
-6. Submit a pull request
+### Booking & Scheduling
+- Check availability
+- Create appointments
+- Send confirmations
+- Manage reservations
 
-## License
+### Data Management
+- CRUD operations on custom data
+- Vector search for semantic queries
+- Data aggregation and reporting
+- Integration with external systems
 
-MIT License - see [LICENSE](LICENSE) file for details.
+---
+
+## 📊 Architecture
 
-## User Data API
+```
+┌─────────────────┐
+│   AI Agent      │
+│   (Lua Platform)│
+└────────┬────────┘
+         │
+         ↓
+┌─────────────────┐
+│   Your Skills   │ ← Built with Lua CLI
+│   (TypeScript)  │
+└────────┬────────┘
+         │
+         ↓
+┌─────────────────┐
+│   Your Tools    │
+│   (Functions)   │
+└────────┬────────┘
+         │
+         ↓
+┌─────────────────┐
+│  Platform APIs  │ ← User, Products, Data, etc.
+│  External APIs  │ ← Weather, Stripe, SendGrid, etc.
+│  Databases      │ ← Your own systems
+└─────────────────┘
+```
 
-The Lua CLI provides a built-in User Data API that allows your tools to interact with persistent user data stored in the Lua system.
+---
 
-### Basic Usage
+## 🌟 Key Features
 
+### Type-Safe Development
 ```typescript
-import { user } from 'lua-cli/user-data-api';
-
-// Get user data
-const userData = await user.data.get();
-console.log('User data:', userData);
-
-// Create or update user data
-await user.data.create({
-  name: 'John Doe',
-  preferences: {
-    theme: 'dark',
-    language: 'en'
-  }
-});
+// Full TypeScript support
+import { LuaTool, Products } from 'lua-cli';
+import { z } from 'zod';
 
-// Update existing data
-await user.data.update({
-  name: 'Jane Doe',
-  preferences: {
-    theme: 'light',
-    language: 'es'
+// Autocomplete, type checking, and validation
+export default class MyTool implements LuaTool {
+  inputSchema = z.object({
+    query: z.string()  // Validated at runtime
+  });
+  
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    // input is fully typed!
+    return await Products.search(input.query);
   }
-});
+}
+```
+
+### Instant Feedback
+```bash
+lua dev
+# Edit file → Save → Auto-reload → Test immediately
+```
 
-// Clear all user data
-await user.data.clear();
+### Production Ready
+```bash
+lua push    # Upload to server
+lua deploy  # Deploy to all users
 ```
 
-### Using in Tools
+---
+
+## 📖 Learning Resources
+
+### 🟢 **New to Lua?**
+Start here: **[GETTING_STARTED.md](GETTING_STARTED.md)**
+- Installation
+- First skill in 1 hour
+- Complete tutorial
+- Common patterns
+
+### 🟡 **Building Skills?**
+Read: **[API_REFERENCE.md](API_REFERENCE.md)**
+- All exported APIs
+- Type definitions
+- Code examples
+- Best practices
+
+### 🟠 **Understanding Examples?**
+Read: **[TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md)**
+- Template structure
+- 30+ tool examples
+- Common recipes
+- Migration guide
+
+### 🔵 **Using the CLI?**
+Read: **[CLI_REFERENCE.md](CLI_REFERENCE.md)**
+- All commands
+- Flags and options
+- Workflows
+- Troubleshooting
+
+### 🟣 **Contributing?**
+Read: **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)**
+- Architecture
+- Module structure
+- Contribution guidelines
+
+---
+
+## 🔧 Common Tasks
+
+### Create a New Tool
+
+```bash
+# Create file
+touch src/tools/MyTool.ts
+```
 
 ```typescript
-import { LuaTool } from 'lua-cli/skill';
-import { user } from 'lua-cli/user-data-api';
+import { LuaTool } from 'lua-cli';
 import { z } from 'zod';
 
-export class UserPreferencesTool extends LuaTool {
-  constructor() {
-    super('user-preferences', 'Manage user preferences');
+export default class MyTool implements LuaTool {
+  name = "my_tool";
+  description = "What it does";
+  inputSchema = z.object({ param: z.string() });
+
+  async execute(input: any) {
+    // Your logic here
+    return { success: true };
   }
+}
+```
 
-  async execute(input: { action: string; key?: string; value?: string }) {
-    const { action, key, value } = input;
-
-    switch (action) {
-      case 'get':
-        const userData = await user.data.get();
-        return { preferences: userData.preferences || {} };
-      
-      case 'set':
-        if (!key || !value) {
-          throw new Error('Key and value are required for set action');
-        }
-        
-        const currentData = await user.data.get();
-        const updatedData = {
-          ...currentData,
-          preferences: {
-            ...currentData.preferences,
-            [key]: value
-          }
-        };
-        
-        await user.data.update(updatedData);
-        return { success: true, message: `Set ${key} to ${value}` };
-      
-      case 'clear':
-        await user.data.clear();
-        return { success: true, message: 'All preferences cleared' };
-      
-      default:
-        throw new Error('Invalid action. Use: get, set, or clear');
-    }
+Add to skill in `src/index.ts`:
+```typescript
+import MyTool from './tools/MyTool';
+
+const skill = new LuaSkill({
+  tools: [new MyTool()]
+});
+```
+
+---
+
+### Call External APIs
+
+```typescript
+import { LuaTool, env } from 'lua-cli';
+
+export default class ExternalApiTool implements LuaTool {
+  async execute(input: any) {
+    const apiKey = env('EXTERNAL_API_KEY');
+    
+    const response = await fetch('https://api.example.com/data', {
+      headers: { 'Authorization': `Bearer ${apiKey}` }
+    });
+    
+    return await response.json();
   }
+}
+```
 
-  getInputSchema() {
-    return z.object({
-      action: z.enum(['get', 'set', 'clear']).describe('Action to perform'),
-      key: z.string().optional().describe('Preference key (required for set action)'),
-      value: z.string().optional().describe('Preference value (required for set action)')
+---
+
+### Use Platform APIs
+
+```typescript
+import { LuaTool, Products, Baskets } from 'lua-cli';
+
+export default class ShoppingTool implements LuaTool {
+  async execute(input: any) {
+    // Search products
+    const products = await Products.search(input.query);
+    
+    // Create basket
+    const basket = await Baskets.create({ currency: 'USD' });
+    
+    // Add item
+    await Baskets.addItem(basket.id, {
+      id: products.data[0].id,
+      price: products.data[0].price,
+      quantity: 1
     });
+    
+    return { basketId: basket.id };
   }
 }
 ```
 
-### API Reference
-
-- `user.data.get()` - Retrieves current user data
-- `user.data.create(data)` - Creates or updates user data
-- `user.data.update(data)` - Updates existing user data (alias for create)
-- `user.data.clear()` - Clears all user data
-
-For more details, see [USER_DATA_API.md](./USER_DATA_API.md).
-
-## Support
-
-For support and questions:
-- Create an issue on [GitHub](https://github.com/lua-ai-global/lua-cli/issues)
-- Contact: stefan@heylua.ai
-
-## Changelog
-
-### 1.4.0
-- **Agent Creation**: Added ability to create new agents during `lua skill init`
-- **Agent Type Selection**: Choose from various agent types (Base Agent, Shopify, WooCommerce, etc.)
-- **Metadata Collection**: Automatic collection of required metadata for agent types
-- **Feature Configuration**: Enable/disable features like RAG, tickets, web search
-- **Persona Generation**: Automatic persona and welcome message generation for new agents
-- **Enhanced YAML**: Added persona and welcome message fields to configuration file
-
-### 1.3.0
-- **Command Restructure**: Reorganized commands under `lua auth` and `lua skill` groups
-- **New Push Command**: Added `lua skill push` to push versions to server
-- **New Deploy Command**: Added `lua skill deploy` to deploy versions to production
-- **Version Management**: Added version field to YAML configuration
-- **Improved UX**: Better command organization and intuitive naming
-- **Enhanced Workflow**: Complete skill lifecycle from init to production deployment
-
-### 1.2.0
-- **Tool Development Framework**: Complete LuaSkill and LuaTool framework
-- **Dependency Bundling**: Automatic bundling of npm packages using esbuild
-- **Interactive Testing**: Real-time tool testing with `lua test` command
-- **Code Compression**: Gzip compression for efficient storage
-- **In-Memory Execution**: VM-based execution without temporary files
-- **Comprehensive Documentation**: Complete guides, API reference, and examples
-- **Template System**: Rich template with 5 example tools and services
-- **TypeScript Support**: Full TypeScript integration with Zod validation
-- **Error Handling**: Robust error handling and validation
-- **Performance Optimization**: Optimized bundling and execution
-
-### 1.1.0
-- **Major Refactoring**: Complete codebase reorganization into modular structure
-- **Email Authentication**: Added OTP-based email authentication
-- **API Key Display**: New `lua apiKey` command
-- **TypeScript Types**: Comprehensive type definitions
-- **Improved Architecture**: Separated commands, services, and utilities
-
-### 1.0.0
-- Initial release
-- API key authentication
-- Organization and agent management
-- Skill project initialization
-- Secure credential storage
+---
+
+### Store Custom Data
+
+```typescript
+import { LuaTool, Data } from 'lua-cli';
+
+export default class SaveNoteTool implements LuaTool {
+  async execute(input: any) {
+    // Create
+    const note = await Data.create('notes', {
+      title: input.title,
+      content: input.content,
+      tags: input.tags
+    }, `${input.title} ${input.content}`);
+    
+    // Search later
+    const results = await Data.search('notes', 'meeting notes', 10);
+    
+    return { noteId: note.id };
+  }
+}
+```
+
+---
+
+## 🎯 Example Projects
+
+### Knowledge Base Assistant
+```typescript
+Tools: search_kb, create_article, update_article
+APIs: Data (vector search)
+Use Case: Company documentation, FAQ
+```
+
+### E-commerce Bot
+```typescript
+Tools: search_products, add_to_cart, checkout
+APIs: Products, Baskets, Orders
+Use Case: Online shopping assistant
+```
+
+### Booking System
+```typescript
+Tools: check_availability, make_reservation, cancel_booking
+APIs: Data (custom collections)
+Use Case: Restaurant/hotel reservations
+```
+
+### CRM Assistant
+```typescript
+Tools: find_customer, create_lead, update_contact
+APIs: Data, User
+Use Case: Customer relationship management
+```
+
+---
+
+## 🚀 Deployment
+
+### Development → Production Flow
+
+```bash
+# 1. Develop locally
+lua dev
+# Edit, test, iterate
+
+# 2. Push to server
+lua push
+
+# 3. Test in sandbox
+lua dev
+# Final testing
+
+# 4. Deploy to production
+lua deploy
+# Available to all users!
+```
+
+### Version Management
+
+Update version in `lua.skill.yaml`:
+```yaml
+skills:
+  - name: my-skill
+    version: 1.0.1  # ← Increment this
+```
+
+Then push and deploy:
+```bash
+lua push    # Uploads v1.0.1
+lua deploy  # Deploys v1.0.1
+```
+
+---
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+**`.env` file:**
+```bash
+STRIPE_API_KEY=sk_test_abc123
+SENDGRID_KEY=SG.xyz789
+CUSTOM_API_URL=https://api.example.com
+```
+
+**`lua.skill.yaml`:**
+```yaml
+skill:
+  env:
+    PRODUCTION_API_KEY: sk_live_abc123
+    BASE_URL: https://prod.example.com
+```
+
+**Access in code:**
+```typescript
+import { env } from 'lua-cli';
+
+const key = env('STRIPE_API_KEY');
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions!
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Write tests
+5. Submit a pull request
+
+See [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for architecture details.
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🔗 Links
+
+- **Documentation**: https://docs.lua.ai
+- **Platform**: https://heylua.ai
+- **GitHub**: https://github.com/lua-ai/lua-cli
+- **npm**: https://www.npmjs.com/package/lua-cli
+
+---
+
+## 💬 Support
+
+- **Issues**: [GitHub Issues](https://github.com/lua-ai/lua-cli/issues)
+- **Email**: support@lua.ai
+- **Docs**: https://docs.lua.ai
+
+---
+
+## 🎉 Quick Links
+
+| I want to... | Read this... |
+|--------------|--------------|
+| **Get started** | [GETTING_STARTED.md](GETTING_STARTED.md) |
+| **Learn the API** | [API_REFERENCE.md](API_REFERENCE.md) |
+| **Use CLI commands** | [CLI_REFERENCE.md](CLI_REFERENCE.md) |
+| **Understand examples** | [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md) |
+| **Contribute code** | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) |
+| **See changelog** | [CHANGELOG.md](CHANGELOG.md) |
+
+---
+
+**Happy building! 🚀**
+
+Made with ❤️ by the Lua team