lua-cli 3.6.7 → 3.7.2

package/docs/api/AI.md

@@ -1,6 +1,6 @@
 # AI API
 
-The AI API allows your tools to generate AI responses with custom context. Use this to add AI capabilities to your tools, such as text generation, content analysis, recommendations, and more.
+The AI API provides isolated text generation from within tools, aligned with [Vercel AI SDK `generateText`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) semantics. Requests are proxied through the Lua API to a dedicated generation endpoint — they do **not** go through the agent chat pipeline.
 
 ## Import
 
@@ -19,59 +19,122 @@ The AI API enables:
 - Create AI-powered features in your tools
 - Use different personas for different tasks
 - Multi-modal inputs (text, images, files)
+- Access rich generation metadata (usage, finish reason, sources, reasoning)
 
 ## Methods
 
-### `AI.generate(context, messages, agentId?)`
+`AI.generate` has two overloads — a simplified form that returns plain text, and a full-options form that returns a rich result object.
 
-Generates an AI response with custom runtime context.
+### Simplified: `AI.generate(prompt, content?)`
+
+Quick text generation. Returns plain text as a string.
 
 **Parameters:**
-- `context` (string) - Runtime context/instructions for the AI
-- `messages` (ChatMessage[]) - Array of messages to process
-- `agentId` (string, optional) - Agent ID to use (defaults to 'luaAgent')
+- `prompt` (string) — When called with one argument this is the user prompt. When called with two arguments it becomes the system instruction.
+- `content` (UserContent, optional) — User message content. Accepts a string or an array of multimodal parts (`TextPart`, `ImagePart`, `FilePart`) from the AI SDK.
 
-**Returns:** `Promise<string>` - AI-generated text response
+**Returns:** `Promise<string>`
 
-**Example:**
 ```typescript
-const response = await AI.generate(
-  'You are a helpful sales assistant.',
+// Single argument — prompt is the user message
+const text = await AI.generate('Summarize the latest AI news.');
+
+// Two arguments — prompt is the system instruction, content is user message
+const text2 = await AI.generate(
+  'You are a helpful assistant.',
   [{ type: 'text', text: 'What products do you recommend?' }]
 );
 
-console.log(response);
-// "I recommend starting with our best-sellers..."
+// Multi-modal content
+const analysis = await AI.generate(
+  'You are an image analysis expert.',
+  [
+    { type: 'text', text: 'What do you see in this image?' },
+    { type: 'image', url: 'https://example.com/photo.jpg' }
+  ]
+);
 ```
 
-## Message Types
+### Full options: `AI.generate(options)`
+
+Full control over generation parameters. Returns a rich result object with metadata.
+
+**Parameters (AiGenerateInput):**
+- `model?` (string) — Model to use, e.g. `'google/gemini-2.0-flash'`, `'openai/gpt-4o'`, `'anthropic/claude-sonnet-4-20250514'`. Defaults to the agent's configured model.
+- `system?` (string) — System instruction.
+- `prompt?` (string) — User prompt (simple text).
+- `messages?` (array) — Conversation messages (AI SDK `ModelMessage[]`).
+- `temperature?` (number) — Sampling temperature (0–2).
+- `maxOutputTokens?` (number) — Maximum tokens to generate.
 
-### Text Message
+**Returns:** `Promise<AiGenerateOutput>`
 
 ```typescript
-{
-  type: 'text',
-  text: string
-}
+const result = await AI.generate({
+  model: 'google/gemini-2.0-flash',
+  system: 'You are concise.',
+  prompt: 'What is the weather in London?',
+  temperature: 0.7,
+});
+
+console.log(result.text);           // Generated text
+console.log(result.finishReason);   // 'stop', 'length', etc.
+console.log(result.usage);          // { promptTokens, completionTokens, totalTokens }
+console.log(result.sources);        // Google Search grounding URLs (when available)
 ```
 
-### Image Message
+### AiGenerateOutput
+
+The full-options response mirrors AI SDK `GenerateTextResult` (serializable fields only, excluding `files` and `steps`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | `string` | Generated text |
+| `finishReason` | `FinishReason` | `'stop'`, `'length'`, `'content-filter'`, `'tool-calls'`, `'error'`, `'other'`, `'unknown'` |
+| `usage` | `LanguageModelUsage` | `{ promptTokens, completionTokens, totalTokens }` |
+| `reasoning?` | `ReasoningOutput[]` | Model reasoning steps (e.g. Gemini thinking) |
+| `reasoningText?` | `string` | Concatenated reasoning text |
+| `sources?` | `AiGenerateSource[]` | URL sources from Google Search grounding |
+| `toolCalls?` | `AiGenerateToolCall[]` | Tool calls made during generation |
+| `toolResults?` | `AiGenerateToolResult[]` | Tool results from generation |
+| `warnings?` | `CallWarning[]` | Provider warnings (e.g. unsupported settings) |
+
+## Supported Providers
+
+| Provider | Model prefix | Example |
+|----------|-------------|---------|
+| Google (Vertex AI) | `google/` | `google/gemini-2.0-flash` |
+| OpenAI | `openai/` | `openai/gpt-4o` |
+| Anthropic | `anthropic/` | `anthropic/claude-sonnet-4-20250514` |
+
+If the requested provider's API key is not configured, the request falls back to the default Vertex AI model.
+
+Google models automatically get Google Search grounding — search result URLs appear in the `sources` field of the full-options response.
+
+## Content Types
+
+### Text
 
 ```typescript
-{
-  type: 'image',
-  url: string
-}
+[{ type: 'text', text: 'Your message here' }]
 ```
 
-### File Message
+### Image
 
 ```typescript
-{
-  type: 'file',
-  url: string,
-  mimeType?: string
-}
+[
+  { type: 'text', text: 'What do you see in this image?' },
+  { type: 'image', url: 'https://example.com/photo.jpg' }
+]
+```
+
+### File
+
+```typescript
+[
+  { type: 'text', text: 'Summarize this document' },
+  { type: 'file', url: 'https://example.com/doc.pdf', mimeType: 'application/pdf' }
+]
 ```
 
 ## Complete Examples
@@ -92,34 +155,48 @@ export default class GenerateDescriptionTool implements LuaTool {
   });
   
   async execute(input: z.infer<typeof this.inputSchema>) {
-    // Get product details
     const product = await Products.getById(input.productId);
-    
     if (!product) {
       return { success: false, error: 'Product not found' };
     }
     
-    // Generate description with AI
     const style = input.style || 'professional';
-    const context = `You are a ${style} copywriter for an e-commerce store.
-    Create an engaging product description that highlights benefits and features.
-    Keep it concise but compelling (2-3 sentences).`;
-    
     const description = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: `Write a product description for: ${product.name}, Price: $${product.price}`
-      }]
+      `You are a ${style} copywriter. Create a 2-3 sentence product description.`,
+      [{ type: 'text', text: `Product: ${product.name}, Price: $${product.price}` }]
     );
     
-    // Update product with new description
     await product.update({ description });
-    
+    return { success: true, productId: input.productId, description };
+  }
+}
+```
+
+### Weather Search with Google Grounding
+
+```typescript
+import { LuaTool, AI } from 'lua-cli/skill';
+import { z } from 'zod';
+
+export default class WeatherSearchTool implements LuaTool {
+  name = 'search_weather';
+  description = 'Search for current weather using AI with Google Search grounding';
+  
+  inputSchema = z.object({
+    location: z.string().describe('City or location to search weather for')
+  });
+  
+  async execute(input: z.infer<typeof this.inputSchema>) {
+    const result = await AI.generate({
+      model: 'google/gemini-2.0-flash',
+      system: 'You report current weather conditions concisely.',
+      prompt: `What is the current weather in ${input.location}?`,
+    });
+
     return {
-      success: true,
-      productId: input.productId,
-      description
+      weather: result.text,
+      sources: result.sources?.map(s => ({ title: s.title, url: s.url })) ?? [],
+      usage: result.usage,
     };
   }
 }
@@ -141,31 +218,15 @@ export default class AnalyzeImageTool implements LuaTool {
   });
   
   async execute(input: z.infer<typeof this.inputSchema>) {
-    const context = `You are an image analysis expert.
-    Describe what you see in detail, including:
-    - Main subjects and objects
-    - Colors and composition
-    - Mood and atmosphere
-    - Any text or branding visible`;
-    
-    const messages = [
-      { 
-        type: 'text' as const, 
-        text: input.question || 'Describe this image in detail' 
-      },
-      { 
-        type: 'image' as const, 
-        url: input.imageUrl 
-      }
-    ];
-    
-    const analysis = await AI.generate(context, messages);
+    const analysis = await AI.generate(
+      'You are an image analysis expert. Describe what you see in detail.',
+      [
+        { type: 'text', text: input.question || 'Describe this image in detail' },
+        { type: 'image', url: input.imageUrl }
+      ]
+    );
     
-    return {
-      success: true,
-      imageUrl: input.imageUrl,
-      analysis
-    };
+    return { success: true, imageUrl: input.imageUrl, analysis };
   }
 }
 ```
@@ -186,147 +247,19 @@ export default class SummarizeTool implements LuaTool {
   });
   
   async execute(input: z.infer<typeof this.inputSchema>) {
-    const lengthInstructions = {
+    const instructions: Record<string, string> = {
       brief: 'in 1-2 sentences',
       medium: 'in 1 paragraph',
       detailed: 'in 2-3 paragraphs with key points'
     };
-    
     const length = input.maxLength || 'medium';
     
-    const context = `You are a professional content summarizer.
-    Create a clear, accurate summary ${lengthInstructions[length]}.
-    Focus on main ideas and key takeaways.`;
-    
     const summary = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: `Summarize this content:\n\n${input.content}`
-      }]
-    );
-    
-    return {
-      success: true,
-      originalLength: input.content.length,
-      summary,
-      summaryLength: summary.length
-    };
-  }
-}
-```
-
-### Smart Recommendation Engine
-
-```typescript
-import { LuaTool, AI, User, Products } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class RecommendProductsTool implements LuaTool {
-  name = 'get_ai_recommendations';
-  description = 'Get AI-powered product recommendations based on user preferences';
-  
-  inputSchema = z.object({
-    userQuery: z.string().optional()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Get user data and product catalog
-    const user = await User.get();
-    const products = await Products.get(1, 50);
-    
-    // Build context with product data
-    const productList = products.map(p => 
-      `- ${p.name}: $${p.price} (${p.category})`
-    ).join('\n');
-    
-    const context = `You are a personal shopping assistant.
-    
-Available products:
-${productList}
-
-User preferences: ${JSON.stringify(user.data.preferences || {})}
-
-Task: Recommend 3-5 products that best match the user's needs.
-Format: Return product names with brief explanations.`;
-
-    const query = input.userQuery || 'What products would you recommend for me?';
-    
-    const recommendations = await AI.generate(
-      context,
-      [{ type: 'text', text: query }]
+      `You are a professional content summarizer. Create a clear summary ${instructions[length]}.`,
+      [{ type: 'text', text: `Summarize:\n\n${input.content}` }]
     );
     
-    return {
-      success: true,
-      recommendations,
-      basedOn: {
-        userPreferences: user.data.preferences,
-        availableProducts: products.length,
-        query
-      }
-    };
-  }
-}
-```
-
-### Content Moderator
-
-```typescript
-import { LuaTool, AI } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class ModerateContentTool implements LuaTool {
-  name = 'moderate_content';
-  description = 'Check if content is appropriate and safe';
-  
-  inputSchema = z.object({
-    content: z.string()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const context = `You are a content moderation expert.
-    
-Analyze the following content for:
-- Inappropriate language
-- Harmful content
-- Spam or advertising
-- Personal information exposure
-
-Respond with JSON in this exact format:
-{
-  "safe": true/false,
-  "reason": "explanation",
-  "category": "appropriate/profanity/spam/harmful/pii",
-  "confidence": 0.95
-}`;
-
-    const analysis = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: `Analyze this content:\n\n"${input.content}"`
-      }]
-    );
-    
-    try {
-      const result = JSON.parse(analysis);
-      return {
-        success: true,
-        ...result,
-        originalContent: input.content
-      };
-    } catch {
-      // If AI didn't return valid JSON, parse manually
-      const safe = !analysis.toLowerCase().includes('inappropriate');
-      return {
-        success: true,
-        safe,
-        reason: analysis,
-        category: 'unknown',
-        confidence: 0.5
-      };
-    }
+    return { success: true, summary, originalLength: input.content.length };
   }
 }
 ```
@@ -348,83 +281,23 @@ export default class TranslateTool implements LuaTool {
   });
   
   async execute(input: z.infer<typeof this.inputSchema>) {
-    const sourceLang = input.sourceLanguage || 'auto-detect';
-    
-    const context = `You are a professional translator.
-    Translate the text accurately while preserving:
-    - Tone and style
-    - Cultural context
-    - Idiomatic expressions (adapt appropriately)
-    
-Source language: ${sourceLang}
-Target language: ${input.targetLanguage}
-
-Return ONLY the translated text, nothing else.`;
-
     const translation = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: input.text
-      }]
+      `You are a professional translator. Translate accurately to ${input.targetLanguage}. Return ONLY the translated text.`,
+      [{ type: 'text', text: input.text }]
     );
     
     return {
       success: true,
       original: input.text,
       translation,
-      from: sourceLang,
+      from: input.sourceLanguage || 'auto-detect',
       to: input.targetLanguage
     };
   }
 }
 ```
 
-### Document Q&A Tool
-
-```typescript
-import { LuaTool, AI } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class DocumentQATool implements LuaTool {
-  name = 'ask_about_document';
-  description = 'Ask questions about a document using AI';
-  
-  inputSchema = z.object({
-    documentUrl: z.string().url(),
-    question: z.string()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const context = `You are a document analysis assistant.
-    
-Read the document carefully and answer the user's question based on the content.
-    
-Guidelines:
-- Only use information from the document
-- If the answer isn't in the document, say so
-- Cite specific parts when possible
-- Be accurate and precise`;
-
-    const answer = await AI.generate(
-      context,
-      [
-        { type: 'file', url: input.documentUrl },
-        { type: 'text', text: input.question }
-      ]
-    );
-    
-    return {
-      success: true,
-      question: input.question,
-      answer,
-      documentUrl: input.documentUrl
-    };
-  }
-}
-```
-
-### Sentiment Analysis
+### Structured JSON Output
 
 ```typescript
 import { LuaTool, AI } from 'lua-cli/skill';
@@ -434,404 +307,54 @@ export default class SentimentAnalysisTool implements LuaTool {
   name = 'analyze_sentiment';
   description = 'Analyze the sentiment of text';
   
-  inputSchema = z.object({
-    text: z.string()
-  });
+  inputSchema = z.object({ text: z.string() });
   
   async execute(input: z.infer<typeof this.inputSchema>) {
-    const context = `You are a sentiment analysis expert.
-    
-Analyze the sentiment of the text and respond with JSON:
-{
-  "sentiment": "positive|negative|neutral",
-  "score": 0.0 to 1.0,
-  "emotions": ["happy", "excited", "satisfied"],
-  "summary": "brief explanation"
-}`;
-
     const analysis = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: `Analyze the sentiment:\n\n"${input.text}"`
-      }]
+      `You are a sentiment analysis expert. Respond with JSON only:
+{ "sentiment": "positive|negative|neutral", "score": 0.0-1.0, "summary": "brief explanation" }`,
+      [{ type: 'text', text: `Analyze:\n\n"${input.text}"` }]
     );
     
     try {
-      const result = JSON.parse(analysis);
-      return {
-        success: true,
-        ...result,
-        originalText: input.text
-      };
+      return { success: true, ...JSON.parse(analysis), originalText: input.text };
     } catch {
-      return {
-        success: false,
-        error: 'Failed to parse AI response',
-        rawResponse: analysis
-      };
+      return { success: false, error: 'Failed to parse', rawResponse: analysis };
     }
   }
 }
 ```
 
-### Creative Writing Assistant
-
-```typescript
-import { LuaTool, AI } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class CreativeWritingTool implements LuaTool {
-  name = 'write_creative_content';
-  description = 'Generate creative content (stories, poems, descriptions)';
-  
-  inputSchema = z.object({
-    type: z.enum(['story', 'poem', 'description', 'dialogue']),
-    prompt: z.string(),
-    style: z.string().optional(),
-    length: z.enum(['short', 'medium', 'long']).optional()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const lengthGuide = {
-      short: '1-2 paragraphs',
-      medium: '3-5 paragraphs',
-      long: '6-10 paragraphs'
-    };
-    
-    const length = lengthGuide[input.length || 'medium'];
-    const style = input.style || 'engaging and creative';
-    
-    const contexts = {
-      story: `You are a creative fiction writer. Write ${length} of an ${style} story based on the prompt.`,
-      poem: `You are a poet. Write a ${style} poem based on the theme.`,
-      description: `You are a descriptive writer. Create a vivid ${length} description.`,
-      dialogue: `You are a screenwriter. Write ${length} of natural, ${style} dialogue.`
-    };
-    
-    const content = await AI.generate(
-      contexts[input.type],
-      [{
-        type: 'text',
-        text: input.prompt
-      }]
-    );
-    
-    return {
-      success: true,
-      type: input.type,
-      content,
-      wordCount: content.split(/\s+/).length
-    };
-  }
-}
-```
-
-### Email Draft Generator
-
-```typescript
-import { LuaTool, AI, User } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class DraftEmailTool implements LuaTool {
-  name = 'draft_email';
-  description = 'Generate professional email drafts';
-  
-  inputSchema = z.object({
-    purpose: z.string().describe('What the email is about'),
-    recipient: z.string().describe('Who it\'s addressed to'),
-    tone: z.enum(['formal', 'friendly', 'urgent']).optional(),
-    includeSignature: z.boolean().optional()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const tone = input.tone || 'friendly';
-    const user = await User.get();
-    
-    const context = `You are a professional email writer.
-    
-Write a ${tone} email for the following purpose: ${input.purpose}
-
-Recipient: ${input.recipient}
-Sender: ${user.data.name || 'User'}
-
-Format:
-- Subject line
-- Greeting
-- Body (2-4 paragraphs)
-- Closing${input.includeSignature ? '\n- Signature' : ''}
-
-Be clear, concise, and ${tone}.`;
-
-    const email = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: 'Generate the email'
-      }]
-    );
-    
-    return {
-      success: true,
-      email,
-      metadata: {
-        tone,
-        recipient: input.recipient,
-        purpose: input.purpose
-      }
-    };
-  }
-}
-```
-
-### Code Explainer
-
-```typescript
-import { LuaTool, AI } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class ExplainCodeTool implements LuaTool {
-  name = 'explain_code';
-  description = 'Explain code snippets in plain language';
-  
-  inputSchema = z.object({
-    code: z.string(),
-    language: z.string().optional(),
-    level: z.enum(['beginner', 'intermediate', 'expert']).optional()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const level = input.level || 'intermediate';
-    const language = input.language || 'auto-detect';
-    
-    const context = `You are a programming instructor explaining code to ${level}-level developers.
-    
-Language: ${language}
-
-Explain:
-1. What the code does (high-level)
-2. How it works (step-by-step)
-3. Key concepts used
-4. Potential improvements or issues
-
-Use clear, simple language. Include examples if helpful.`;
-
-    const explanation = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: `Explain this code:\n\n\`\`\`${language}\n${input.code}\n\`\`\``
-      }]
-    );
-    
-    return {
-      success: true,
-      code: input.code,
-      explanation,
-      level,
-      language
-    };
-  }
-}
-```
-
-### Multi-Agent Specialist
-
-```typescript
-import { LuaTool, AI } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class GetExpertOpinionTool implements LuaTool {
-  name = 'get_expert_opinion';
-  description = 'Get expert opinions from specialized AI personas';
-  
-  inputSchema = z.object({
-    expertType: z.enum(['lawyer', 'doctor', 'financial', 'technical']),
-    question: z.string()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    const expertContexts = {
-      lawyer: `You are a legal expert providing general legal information.
-      Important: This is not legal advice. Recommend consulting a licensed attorney for specific cases.`,
-      
-      doctor: `You are a medical professional providing general health information.
-      Important: This is not medical advice. Recommend seeing a healthcare provider for diagnosis/treatment.`,
-      
-      financial: `You are a financial advisor providing general financial guidance.
-      Important: This is not financial advice. Recommend consulting a certified financial planner.`,
-      
-      technical: `You are a technical expert with deep knowledge of software, hardware, and technology.
-      Provide detailed, accurate technical information.`
-    };
-    
-    const opinion = await AI.generate(
-      expertContexts[input.expertType],
-      [{
-        type: 'text',
-        text: input.question
-      }]
-    );
-    
-    return {
-      success: true,
-      expertType: input.expertType,
-      question: input.question,
-      opinion,
-      disclaimer: 'This is general information only. Consult a licensed professional for specific advice.'
-    };
-  }
-}
-```
-
-### Conversational Context Builder
-
-```typescript
-import { LuaTool, AI, User } from 'lua-cli/skill';
-import { z } from 'zod';
-
-export default class ChatWithContextTool implements LuaTool {
-  name = 'chat_with_history';
-  description = 'Generate AI response with conversation history';
-  
-  inputSchema = z.object({
-    newMessage: z.string()
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // Get chat history
-    const history = await User.getChatHistory();
-    
-    // Build conversation context
-    const conversationContext = history
-      .slice(-10) // Last 10 messages
-      .map(msg => `${msg.role}: ${msg.content[0]?.text}`)
-      .join('\n');
-    
-    const context = `You are continuing a conversation.
-    
-Previous conversation:
-${conversationContext}
-
-Maintain conversation continuity and reference previous topics when relevant.`;
-
-    const response = await AI.generate(
-      context,
-      [{
-        type: 'text',
-        text: input.newMessage
-      }]
-    );
-    
-    return {
-      success: true,
-      response,
-      contextUsed: history.length
-    };
-  }
-}
-```
-
-## Using Different Agents
-
-```typescript
-// Use a specialized agent for specific tasks
-const technicalResponse = await AI.generate(
-  'You are a technical support specialist.',
-  [{ type: 'text', text: 'How do I fix error code 500?' }],
-  'technical-support-agent-id'
-);
-
-const salesResponse = await AI.generate(
-  'You are a sales expert.',
-  [{ type: 'text', text: 'What are the benefits of product X?' }],
-  'sales-agent-id'
-);
-```
-
 ## Best Practices
 
-### ✅ DO
+### DO
 
 - Provide clear, specific context
-- Include relevant data in the context
-- Use appropriate message types (text, image, file)
-- Handle AI responses that may vary
-- Include error handling
-- Set expectations in context (format, length, style)
+- Include relevant data in the system prompt
+- Use the simplified overload for quick text generation
+- Use the full-options overload when you need metadata (usage, sources, finish reason)
+- Handle AI responses that may vary (validate, parse JSON carefully)
+- Set format expectations in the system prompt (JSON structure, length, style)
 
-### ❌ DON'T
+### DON'T
 
 - Don't expect exact JSON without clear instructions
 - Don't use AI for simple logic (if/else, calculations)
-- Don't expose sensitive data in context
+- Don't expose sensitive data in prompts
 - Don't make critical decisions purely on AI output
 - Don't forget to validate/sanitize AI responses
 
-## Context Writing Tips
-
-### Clear Instructions
-
-```typescript
-// ✅ Good - Specific and clear
-const context = `You are a product reviewer.
-Rate products on:
-1. Quality (1-10)
-2. Value (1-10)
-3. Features (1-10)
-
-Return ONLY a JSON object with these ratings.`;
-
-// ❌ Bad - Vague
-const context = `Review this product`;
-```
-
-### Structured Output
-
-```typescript
-// ✅ Good - Request specific format
-const context = `Analyze the text and return JSON:
-{
-  "summary": "brief summary",
-  "keyPoints": ["point 1", "point 2"],
-  "sentiment": "positive|negative|neutral"
-}`;
-
-// ❌ Bad - Free-form output
-const context = `Analyze the text`;
-```
-
-### Example-Driven
-
-```typescript
-// ✅ Good - Include examples
-const context = `Extract product names from text.
-
-Examples:
-"I want to buy an iPhone" → ["iPhone"]
-"Looking for Nike shoes and Adidas jacket" → ["Nike shoes", "Adidas jacket"]
-
-Return array of product names only.`;
-```
-
 ## Error Handling
 
 ```typescript
 try {
-  const response = await AI.generate(context, messages);
+  const response = await AI.generate('Summarize this article.', content);
   
-  // Validate response
   if (!response || response.trim().length === 0) {
-    return {
-      success: false,
-      error: 'AI returned empty response'
-    };
+    return { success: false, error: 'AI returned empty response' };
   }
   
-  return {
-    success: true,
-    response
-  };
+  return { success: true, response };
 } catch (error) {
   return {
     success: false,
@@ -867,16 +390,10 @@ try {
 | Recommendations | Product suggestions, content curation |
 | Moderation | Content filtering, safety checks |
 | Q&A | Document queries, knowledge retrieval |
+| Web search | Real-time information via Google Search grounding |
 
 ## Related APIs
 
 - [User API](./User.md) - Get user context for personalization
 - [Data API](./Data.md) - Store AI-generated content
 - [Jobs API](./Jobs.md) - Schedule AI tasks
-
-## See Also
-
-- [AI Integration Patterns](../guides/AIPatterns.md)
-- [Multi-Modal Examples](../guides/MultiModalAI.md)
-- [Context Engineering Guide](../guides/ContextEngineering.md)
-