@majkapp/plugin-kit 1.2.0 → 1.2.1

package/README.md

@@ -1,480 +1,135 @@
-# @majkapp/plugin-kit
+# @majk/plugin-kit
 
-**Modern, type-safe framework for building MAJK plugins with exceptional developer experience**
+**Fluent builder framework for creating robust MAJK plugins**
 
-Build production-ready MAJK plugins using a fluent builder API with comprehensive validation, auto-generated clients, and declarative configuration management.
+Build type-safe, production-ready MAJK plugins with excellent developer experience, comprehensive validation, and clear error messages.
 
-[![npm version](https://img.shields.io/npm/v/@majkapp/plugin-kit.svg)](https://www.npmjs.com/package/@majkapp/plugin-kit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## Features
 
-## ✨ Features
+✨ **Fluent API** - Chainable builder pattern with full TypeScript support
+🛡️ **Type Safety** - Compile-time checks for routes, IDs, and descriptions
+✅ **Build-Time Validation** - Catches errors before runtime
+📝 **Clear Error Messages** - Actionable suggestions when things go wrong
+🔄 **Auto HTTP Server** - Built-in routing, CORS, error handling
+⚛️ **React & HTML Screens** - Support for both SPA and simple HTML UIs
+🔧 **Tool Management** - Declare tools with schema validation
+💾 **Storage Integration** - Direct access to plugin storage
+📡 **Event Bus** - Subscribe to system events
+🧹 **Auto Cleanup** - Managed lifecycle with automatic resource cleanup
+❤️ **Health Checks** - Built-in health monitoring
 
-- 🎯 **Function-First Architecture** - Define backend functions with JSON schemas, auto-generate TypeScript clients
-- 🔧 **Configurable Entities** - Declaratively register teammates, MCP servers based on user configuration
-- 🎨 **React & HTML Support** - Build rich UIs with React or simple HTML pages
-- 🛡️ **Type Safety** - Full TypeScript support with compile-time validation
-- 📝 **Auto-Generated Clients** - Generate React hooks and TypeScript clients from function definitions
-- ✅ **Build-Time Validation** - Catch errors before runtime with comprehensive checks
-- 🔄 **HTTP Transport** - Built-in HTTP server with routing, CORS, error handling
-- 💾 **Integrated Storage** - Plugin-scoped key-value storage
-- 📡 **Event Bus** - Subscribe to system events with cleanup management
-- ❤️ **Health Monitoring** - Built-in health checks with custom logic
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
-npm install @majkapp/plugin-kit
+npm install @majk/plugin-kit
 ```
 
----
-
-## 🚀 Quick Start
+## Quick Start
 
 ```typescript
-import { definePlugin, HttpTransport } from '@majkapp/plugin-kit';
-
-export = definePlugin('my-plugin', 'My Plugin', '1.0.0')
-  .pluginRoot(__dirname)
+import { definePlugin } from '@majk/plugin-kit';
 
-  // Define a backend function
-  .function('getMessage', {
-    description: 'Gets a greeting message for the user.',
-    input: {
-      type: 'object',
-      properties: {
-        name: { type: 'string' }
-      },
-      required: ['name']
-    },
-    output: {
-      type: 'object',
-      properties: {
-        message: { type: 'string' }
-      }
-    },
-    handler: async (input, ctx) => {
-      return { message: `Hello, ${input.name}!` };
-    }
-  })
+export default definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .ui({ appDir: 'ui/dist' })
 
-  // Configure React UI
-  .ui({
-    appDir: 'dist',
-    base: '/',
-    history: 'hash'
+  .topbar('/plugin-screens/my-plugin/dashboard', {
+    icon: '🚀'
   })
 
-  // Add a screen
   .screenReact({
-    id: 'main',
-    name: 'My Plugin',
-    description: 'Main plugin screen. Shows greeting and controls.',
-    route: '/plugin-screens/my-plugin/main',
+    id: 'dashboard',
+    name: 'Dashboard',
+    description: 'Main dashboard for my plugin. Shows key metrics and actions.',
+    route: '/plugin-screens/my-plugin/dashboard',
     reactPath: '/'
   })
 
-  // Enable HTTP transport
-  .transport(new HttpTransport())
-
-  .build();
-```
-
-Generate client:
-```bash
-npx plugin-kit generate -e ./index.js -o ./ui/src/generated
-```
-
-Use in React:
-```tsx
-import { useGetMessage } from './generated';
+  .apiRoute({
+    method: 'GET',
+    path: '/api/data',
+    name: 'Get Data',
+    description: 'Retrieves plugin data. Returns formatted response with metadata.',
+    handler: async (req, res, { majk, storage }) => {
+      const data = await storage.get('data') || [];
+      return { data, count: data.length };
+    }
+  })
 
-function App() {
-  const { data, loading, error, mutate } = useGetMessage();
+  .tool('global', {
+    name: 'myTool',
+    description: 'Does something useful. Processes input and returns results.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        param: { type: 'string' }
+      },
+      required: ['param']
+    }
+  }, async (input, { logger }) => {
+    logger.info(`Tool called with: ${input.param}`);
+    return { success: true, result: input.param.toUpperCase() };
+  })
 
-  return (
-    <button onClick={() => mutate({ name: 'World' })}>
-      {loading ? 'Loading...' : data?.message}
-    </button>
-  );
-}
+  .build();
 ```
 
----
-
-## 📚 Table of Contents
-
-- [Core Concepts](#-core-concepts)
-- [Function-First Architecture](#-function-first-architecture)
-- [Configurable Entities](#-configurable-entities)
-- [UI Configuration](#-ui-configuration)
-- [API Routes (Legacy)](#-api-routes-legacy)
-- [Tools](#-tools)
-- [Static Entities](#-static-entities)
-- [Secret Providers](#-secret-providers)
-- [Lifecycle Hooks](#-lifecycle-hooks)
-- [Client Generation](#-client-generation)
-- [Complete Example](#-complete-example)
-- [API Reference](#-api-reference)
-- [MAJK API Deep Dive](#-majk-api-deep-dive)
-- [Best Practices](#-best-practices)
-- [Troubleshooting](#-troubleshooting)
-
----
-
-## 🎯 Core Concepts
+## Core Concepts
 
 ### Plugin Definition
 
 Every plugin starts with `definePlugin(id, name, version)`:
 
 ```typescript
-import { definePlugin } from '@majkapp/plugin-kit';
-
-const plugin = definePlugin('task-manager', 'Task Manager', '1.0.0')
-  .pluginRoot(__dirname)  // Important: tells plugin-kit where your files are
-  // ... builder methods
-  .build();
-
-export = plugin;
+definePlugin('system-explorer', 'System Explorer', '1.0.0')
 ```
 
 **Rules:**
 - `id` must be unique and URL-safe (kebab-case recommended)
-- `name` is the human-readable display name
-- `version` follows semantic versioning (semver)
-- Always call `.pluginRoot(__dirname)` for reliable file resolution
-
----
-
-## 🔥 Function-First Architecture
-
-The modern way to build MAJK plugins. Define functions with JSON schemas, and plugin-kit automatically:
-- Generates HTTP endpoints
-- Creates TypeScript clients with React hooks
-- Validates input/output at runtime
-- Handles errors gracefully
-
-### Defining Functions
-
-```typescript
-.function('createTask', {
-  description: 'Creates a new task with the specified details.',
-  input: {
-    type: 'object',
-    properties: {
-      title: { type: 'string' },
-      description: { type: 'string' },
-      priority: { type: 'string', enum: ['low', 'medium', 'high'] },
-      dueDate: { type: 'string', format: 'date-time' }
-    },
-    required: ['title']
-  },
-  output: {
-    type: 'object',
-    properties: {
-      id: { type: 'string' },
-      title: { type: 'string' },
-      createdAt: { type: 'string' }
-    }
-  },
-  handler: async (input, ctx) => {
-    const task = {
-      id: generateId(),
-      title: input.title,
-      description: input.description || '',
-      priority: input.priority || 'medium',
-      dueDate: input.dueDate,
-      createdAt: new Date().toISOString()
-    };
-
-    await ctx.storage.set(`task:${task.id}`, task);
-    ctx.logger.info(`Created task: ${task.id}`);
-
-    return task;
-  },
-  tags: ['tasks']
-})
-```
-
-**Handler Context (`ctx`):**
-- `storage` - Plugin-scoped key-value storage
-- `logger` - Scoped logger (debug, info, warn, error)
-- `majk` - Full MAJK API interface
-
-### Subscriptions (Async Iterators)
-
-For streaming or long-running operations:
-
-```typescript
-.subscription('watchTasks', {
-  description: 'Watches for task changes in real-time.',
-  input: {
-    type: 'object',
-    properties: {
-      filter: { type: 'string' }
-    }
-  },
-  output: {
-    type: 'object',
-    properties: {
-      taskId: { type: 'string' },
-      event: { type: 'string' },
-      timestamp: { type: 'string' }
-    }
-  },
-  handler: async function* (input, ctx) {
-    const subscription = ctx.majk.eventBus.channel('tasks').subscribe();
-
-    try {
-      for await (const event of subscription) {
-        yield {
-          taskId: event.entity.id,
-          event: event.type,
-          timestamp: new Date().toISOString()
-        };
-      }
-    } finally {
-      subscription.unsubscribe();
-    }
-  }
-})
-```
-
----
-
-## 🔧 Configurable Entities
-
-**New in v1.1.0** - Register entities (teammates, MCP servers) that are only created **after** the user completes a configuration wizard.
-
-### Configuration Schema
-
-Define a config wizard with a JSON schema:
-
-```typescript
-const ConfigSchema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-    role: { type: 'string' },
-    systemPrompt: { type: 'string' },
-    model: { type: 'string', enum: ['gpt-4', 'claude-3-sonnet'] }
-  },
-  required: ['name', 'systemPrompt']
-};
-
-.configWizard({
-  // Schema enables auto-generation of updateConfig() and getConfig()
-  schema: ConfigSchema,
-  storageKey: 'teammate-config',  // Optional, defaults to '_plugin_config'
-
-  // UI
-  path: '/plugin-screens/my-plugin/main',
-  hash: '#/config-wizard',
-  title: 'Configure Your Assistant',
-  width: 900,
-  height: 700,
-  description: 'Set up your AI assistant with custom attributes.',
-
-  // When to show the wizard
-  shouldShow: async (ctx) => {
-    const config = await ctx.storage.get('teammate-config');
-    return !config;  // Show if no config exists
-  }
-})
-```
-
-**What this does:**
-- ✅ Auto-generates `updateConfig(config)` function (validates against schema, saves to storage)
-- ✅ Auto-generates `getConfig()` function (retrieves current config)
-- ✅ Both functions available in generated client with React hooks
-- ✅ Plugin-kit loads config and calls factories at capability generation time
-
-### Configurable Teammates
-
-Register teammates that are created based on user configuration:
-
-```typescript
-.configurableTeamMember((config) => {
-  // config is loaded from storage by plugin-kit
-  return [{
-    id: 'my-assistant',
-    name: config.name,
-    role: 'assistant',
-    systemPrompt: config.systemPrompt,
-    model: config.model,
-    expertise: config.skills || [],
-    isActive: true
-  }];
-})
-```
-
-**How it works:**
-1. **First load (no config)**: Factory not called, no teammate registered, config wizard shown
-2. **User completes wizard**: UI calls auto-generated `updateConfig()`, sends `postMessage({ type: 'majk:config-complete' })`
-3. **Plugin reloads**: Config exists, factory called with config, teammate registered!
-
-### Configurable MCP Servers
-
-```typescript
-.configurableMcp((config) => {
-  if (!config.enableMcpServer) return [];
-
-  return [{
-    id: 'custom-mcp',
-    name: config.mcpServerName,
-    type: 'stdio',
-    command: config.command,
-    args: config.args || [],
-    env: config.env || {}
-  }];
-})
-```
-
-### Generic Configurable Entities
-
-```typescript
-.configurableEntity('project', (config) => {
-  return config.projects.map(p => ({
-    id: p.id,
-    name: p.name,
-    description: p.description
-  }));
-})
-```
-
-### Settings Screen
-
-Provide a way to reconfigure after initial setup using a **separate** `.settings()` call:
-
-```typescript
-.settings({
-  path: '/plugin-screens/my-plugin/main',
-  hash: '#/settings',
-  title: 'Plugin Settings',
-  description: 'Reconfigure your assistant and preferences.'
-})
-```
-
-The settings screen can use the same auto-generated `updateConfig()` and `getConfig()` functions that were created by `.configWizard({ schema })`.
-
-**Note:** While `ConfigWizardDef` type includes an optional `settings` property, the current implementation requires using the separate `.settings()` method shown above.
+- `name` is the display name
+- `version` follows semver
 
-### Build-Time Validation
-
-Plugin-kit validates your usage:
-
-```typescript
-// ❌ ERROR: Configurable entities require configWizard with schema
-.configurableTeamMember((config) => [...])
-// Missing .configWizard({ schema: ... })
-
-// ✅ CORRECT
-.configWizard({ schema: MySchema, ... })
-.configurableTeamMember((config) => [...])
-```
-
----
+### Screens
 
-## 🎨 UI Configuration
+#### React Screens
 
-### React Applications
-
-For React SPAs, configure UI first, then add screens:
+For React SPAs, configure UI first:
 
 ```typescript
 .ui({
-  appDir: 'dist',              // Where your built React app is
-  base: '/',                   // Base URL for the SPA
-  history: 'hash'              // 'browser' or 'hash' routing
+  appDir: 'ui/dist',        // Where your built React app is
+  base: '/',                // Base URL for the SPA
+  history: 'browser'        // 'browser' or 'hash' routing
 })
 
 .screenReact({
   id: 'dashboard',
   name: 'Dashboard',
-  description: 'Main dashboard view. Shows metrics and activity.',
-  route: '/plugin-screens/my-plugin/dashboard',  // Must start with /plugin-screens/{pluginId}/
-  reactPath: '/'              // Path within your React app
-})
-
-.screenReact({
-  id: 'settings',
-  name: 'Settings',
-  description: 'Plugin settings screen. Configure behavior and appearance.',
-  route: '/plugin-screens/my-plugin/settings',
-  reactPath: '/settings',
-  hash: '#/settings'          // Optional: hash fragment for hash routing
+  description: 'Main dashboard view. Shows metrics and controls.',  // 2-3 sentences
+  route: '/plugin-screens/my-plugin/dashboard',  // Must start with /plugin-screens/{id}/
+  reactPath: '/'  // Path within your React app
 })
 ```
 
-**The React app receives globals:**
-```javascript
-window.__MAJK_BASE_URL__       // Host base URL
-window.__MAJK_IFRAME_BASE__    // Plugin base path
-window.__MAJK_PLUGIN_ID__      // Your plugin ID
-```
+**The React app receives:**
+- `window.__MAJK_BASE_URL__` - Host base URL
+- `window.__MAJK_IFRAME_BASE__` - Plugin base path
+- `window.__MAJK_PLUGIN_ID__` - Your plugin ID
 
-### HTML Screens
+#### HTML Screens
 
-For simple static pages:
+For simple HTML pages:
 
 ```typescript
 .screenHtml({
   id: 'about',
   name: 'About',
-  description: 'Information about the plugin. Shows version and features.',
+  description: 'Information about the plugin. Shows version and author.',
   route: '/plugin-screens/my-plugin/about',
-  htmlFile: 'about.html'      // Relative to pluginRoot
-  // OR
-  html: '<html><body>...</body></html>'
-})
-```
-
-### Top Bar Navigation
-
-Add plugin to MAJK's top navigation:
-
-```typescript
-.topbar('/plugin-screens/my-plugin/dashboard', {
-  icon: '📊',
-  name: 'Task Manager'  // Optional, defaults to plugin name
+  html: '<html>...'  // OR htmlFile: 'about.html'
 })
 ```
 
-### Top Bar Menu
-
-Add items to MAJK's menu:
-
-```typescript
-.topBarMenu([
-  {
-    path: 'My Plugin.Dashboard',
-    label: 'Overview',
-    icon: '📊',
-    route: '/plugin-screens/my-plugin/dashboard',
-    description: 'View dashboard with key metrics.',
-    badge: { label: 'New', variant: 'success' }
-  },
-  {
-    type: 'divider',
-    path: 'My Plugin.Divider1'
-  },
-  {
-    path: 'My Plugin.Settings',
-    label: 'Settings',
-    icon: '⚙️',
-    route: '/plugin-screens/my-plugin/settings',
-    description: 'Configure plugin behavior.'
-  }
-])
-```
-
----
-
-## 🔌 API Routes (Legacy)
-
-**Note:** For new plugins, prefer [Function-First Architecture](#-function-first-architecture). API routes are still supported for backward compatibility.
+### API Routes
 
 Define REST endpoints:
 
@@ -483,74 +138,60 @@ Define REST endpoints:
   method: 'POST',
   path: '/api/tasks/:id/complete',
   name: 'Complete Task',
-  description: 'Marks a task as complete. Updates status and notifies users.',
+  description: 'Marks a task as complete. Updates task status and triggers notifications.',
   handler: async (req, res, { majk, storage, logger }) => {
-    const { id } = req.params;              // Path parameters
-    const { note } = req.body;              // Request body (JSON parsed)
-    const status = req.query.get('status'); // Query string
+    const { id } = req.params;       // Path parameters
+    const { note } = req.body;       // Request body
+    const status = req.query.get('status');  // Query params
 
     logger.info(`Completing task ${id}`);
 
-    const task = await storage.get(`task:${id}`);
-    if (!task) {
-      res.status(404).json({ error: 'Task not found' });
-      return;
-    }
-
-    task.completed = true;
-    task.completedAt = new Date().toISOString();
-    task.note = note;
+    // Access MAJK APIs
+    const todos = await majk.todos.list();
 
-    await storage.set(`task:${id}`, task);
+    // Use plugin storage
+    await storage.set(`task:${id}`, { completed: true });
 
-    return { success: true, task };
+    return { success: true, taskId: id };
   }
 })
 ```
 
 **Available Methods:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
 
-**Handler Context:**
-- `req.params` - Path parameters from route pattern
-- `req.body` - Parsed JSON body (POST/PUT/PATCH)
-- `req.query` - URLSearchParams for query string
-- `majk` - Full MAJK API
-- `storage` - Plugin storage
-- `logger` - Scoped logger
-- `http` - HTTP config (port, baseUrl, secret)
-
----
+**Context Provided:**
+- `majk` - Full MAJK API interface
+- `storage` - Plugin-scoped key-value storage
+- `logger` - Scoped logger (debug, info, warn, error)
+- `http` - HTTP configuration (port, baseUrl, secret)
 
-## 🛠️ Tools
+### Tools
 
-Tools are functions that AI agents can invoke. They're scoped to different contexts.
+Tools are functions that agents can invoke:
 
 ```typescript
 .tool(
   'conversation',  // Scope: 'global' | 'conversation' | 'teammate' | 'project'
   {
-    name: 'analyzeCode',
-    description: 'Analyzes code for potential issues. Returns findings with severity.',
+    name: 'analyzeSentiment',
+    description: 'Analyzes text sentiment. Returns positive, negative, or neutral classification.',
     inputSchema: {
       type: 'object',
       properties: {
-        code: { type: 'string' },
-        language: { type: 'string' }
+        text: { type: 'string' }
       },
-      required: ['code', 'language']
+      required: ['text']
     }
   },
   async (input, { majk, logger }) => {
-    logger.info(`Analyzing ${input.language} code`);
+    logger.info('Analyzing sentiment');
 
-    const issues = analyzeCode(input.code, input.language);
+    // Your implementation
+    const sentiment = analyzeSentiment(input.text);
 
     return {
       success: true,
-      data: {
-        issues,
-        summary: `Found ${issues.length} issues`
-      }
+      data: { sentiment, confidence: 0.95 }
     };
   }
 )
@@ -558,342 +199,115 @@ Tools are functions that AI agents can invoke. They're scoped to different conte
 
 **Tool Scopes:**
 - `global` - Available everywhere
-- `conversation` - Scoped to specific conversations
-- `teammate` - Scoped to specific teammates
-- `project` - Scoped to specific projects
-
-**Scoped Metadata:**
-
-For non-global tools, specify scope entity in metadata:
+- `conversation` - Scoped to conversations
+- `teammate` - Scoped to teammates
+- `project` - Scoped to projects
 
-```typescript
-.tool('conversation', {
-  name: 'contextualSearch',
-  description: 'Searches within conversation context.',
-  inputSchema: { /* ... */ },
-  metadata: {
-    conversationId: 'specific-conversation-id'  // Makes tool available only in this conversation
-  }
-}, handler)
-```
-
----
+### Entities
 
-## 📦 Static Entities
-
-Declare entities your plugin always provides:
-
-### MCP Servers
+Declare entities your plugin provides:
 
 ```typescript
-.mcpServer([
+.entity('teammate', [
   {
-    id: 'github-mcp',
-    name: 'GitHub MCP Server',
-    type: 'stdio',
-    command: 'npx',
-    args: ['-y', '@modelcontextprotocol/server-github'],
-    env: {
-      GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN
-    }
+    id: 'bot-assistant',
+    name: 'Bot Assistant',
+    role: 'bot',
+    capabilities: ['analysis', 'reporting']
   }
 ])
-```
-
-### Team Members
 
-```typescript
-.teamMember([
+.entity('mcpServer', [
   {
-    id: 'code-reviewer',
-    name: 'Code Reviewer',
-    role: 'reviewer',
-    systemPrompt: 'You are an expert code reviewer focusing on best practices.',
-    model: 'claude-3-sonnet',
-    expertise: ['javascript', 'typescript', 'code-review'],
-    isActive: true
-  }
-])
-```
-
-### Generic Entities
-
-```typescript
-.entity('project', [
-  {
-    id: 'sample-project',
-    name: 'Sample Project',
-    description: 'A sample project for demonstration'
+    id: 'custom-server',
+    name: 'Custom MCP Server',
+    transport: { type: 'stdio', command: 'node', args: ['server.js'] }
   }
 ])
 ```
 
 **Supported Entity Types:**
 - `mcpServer` - MCP servers
-- `teamMember` - Team members/bots
+- `teammate` - Team members/bots
 - `conversation` - Conversations
+- `todo` - Tasks
 - `project` - Projects
 - `agent` - AI agents
 
----
-
-## 🔐 Secret Providers
+### Config Wizard & Settings
 
-Plugins can act as secret providers, allowing them to supply secrets (API keys, tokens, credentials) to MAJK and other plugins. This enables integration with external secret management services like 1Password, AWS Secrets Manager, HashiCorp Vault, etc.
+#### Config Wizard
 
-### Basic Secret Provider
+Show a wizard on first run:
 
 ```typescript
-.secretProvider({
-  name: 'My Vault',
-  priority: 50,  // Lower = queried first (default: 100)
-  scopes: ['global', 'project', 'integration'],
-  description: 'Provides secrets from my vault service',
-  icon: '🔐',
-  tags: ['vault', 'secrets'],
-  factory: (ctx) => {
-    // Initialize your secret vault connection
-    const vault = new Map([
-      ['API_KEY', { value: 'secret-key-123', scope: 'global' }],
-      ['DB_PASSWORD', { value: 'db-pass-456', scope: 'project', projectId: 'proj-1' }]
-    ]);
-
-    return {
-      // Required: resolve a secret by key
-      async resolve(key, scope, context) {
-        ctx.logger.info(`Resolving secret: ${key}`);
-
-        const secret = vault.get(key);
-        if (!secret) {
-          return {
-            found: false,
-            source: 'my-vault:not_found'
-          };
-        }
-
-        // Check scope matching
-        if (scope && secret.scope !== scope.type) {
-          return {
-            found: false,
-            source: 'my-vault:scope_mismatch'
-          };
-        }
-
-        return {
-          found: true,
-          value: secret.value,
-          scope: secret.scope,
-          source: 'my-vault'
-        };
-      },
-
-      // Optional: list available secrets
-      async list(scope) {
-        const secrets = [];
-        for (const [key, secret] of vault.entries()) {
-          if (!scope || secret.scope === scope.type) {
-            secrets.push({
-              key,
-              scope: { type: secret.scope, id: secret.projectId },
-              description: 'Secret from my vault',
-              createdAt: new Date(),
-              tags: ['my-vault']
-            });
-          }
-        }
-        return secrets;
-      },
-
-      // Optional: check if secret exists
-      async has(key, scope) {
-        const secret = vault.get(key);
-        if (!secret) return false;
-        if (!scope) return true;
-        return secret.scope === scope.type;
-      },
-
-      // Optional: get provider info
-      async getInfo() {
-        return {
-          connected: true,
-          vaultSize: vault.size,
-          lastSync: new Date(),
-          secretKeys: Array.from(vault.keys())
-        };
-      }
-    };
+.configWizard({
+  path: '/setup',
+  title: 'Initial Setup',
+  width: 600,
+  height: 400,
+  description: 'Configure plugin settings. Set up API keys and preferences.',
+  shouldShow: async (ctx) => {
+    const config = await ctx.storage.get('config');
+    return !config;  // Show if no config exists
   }
 })
 ```
 
-### Scope Types
-
-Secrets can be scoped to different contexts:
-
-- **`global`** - Available everywhere
-- **`project`** - Specific to a project (requires `projectId`)
-- **`integration`** - Specific to an integration (requires `integrationId`)
-- **`conversation`** - Specific to a conversation (requires `conversationId`)
-- **`user`** - User-specific (requires `userId`)
+#### Settings Screen
 
-### Resolution Context
-
-When resolving secrets, MAJK provides context about where the secret is being used:
+Ongoing settings management:
 
 ```typescript
-async resolve(key, scope, context) {
-  // context may contain:
-  // - conversationId: Current conversation ID
-  // - projectId: Current project ID
-  // - teamMemberId: Team member requesting the secret
-  // - integrationId: Integration requesting the secret
-  // - userId: User requesting the secret
-
-  if (scope?.type === 'project' && context?.projectId) {
-    // Find project-specific secret
-    return await getProjectSecret(key, context.projectId);
-  }
-
-  // Fall back to global secret
-  return await getGlobalSecret(key);
-}
-```
-
-### Priority
-
-Multiple secret providers can be registered. MAJK queries them in priority order (lower number = higher priority) until one returns `found: true`.
-
-**Priority Guidelines:**
-- **1-50**: High priority (external services like 1Password, AWS Secrets)
-- **100**: Default priority
-- **500+**: Low priority (fallback providers, testing)
-
-### Integration with External Services
-
-**Example: AWS Secrets Manager**
-
-```typescript
-import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
-
-.secretProvider({
-  name: 'AWS Secrets Manager',
-  priority: 10,
-  scopes: ['global', 'project'],
-  factory: (ctx) => {
-    const client = new SecretsManagerClient({ region: 'us-east-1' });
-
-    return {
-      async resolve(key, scope) {
-        try {
-          const command = new GetSecretValueCommand({ SecretId: key });
-          const response = await client.send(command);
-
-          return {
-            found: true,
-            value: response.SecretString,
-            scope: 'global',
-            source: 'aws-secrets-manager'
-          };
-        } catch (error) {
-          if (error.name === 'ResourceNotFoundException') {
-            return { found: false, source: 'aws-secrets-manager:not_found' };
-          }
-          throw error;
-        }
-      }
-    };
-  }
-})
-```
-
-**Example: 1Password CLI**
-
-```typescript
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-.secretProvider({
-  name: '1Password',
-  priority: 5,
-  scopes: ['global'],
-  factory: (ctx) => {
-    return {
-      async resolve(key) {
-        try {
-          const { stdout } = await execAsync(`op item get "${key}" --fields password`);
-          return {
-            found: true,
-            value: stdout.trim(),
-            scope: 'global',
-            source: '1password'
-          };
-        } catch (error) {
-          return { found: false, source: '1password:not_found' };
-        }
-      }
-    };
-  }
+.settings({
+  path: '/settings',
+  title: 'Plugin Settings',
+  description: 'Manage plugin configuration. Adjust behavior and display options.'
 })
 ```
 
----
-
-## 🔄 Lifecycle Hooks
+### Lifecycle Hooks
 
-### onReady
+#### onReady
 
-Called after the plugin's HTTP server starts, before `onLoad` completes:
+Called after server starts, before `onLoad` completes:
 
 ```typescript
 .onReady(async (ctx, cleanup) => {
-  ctx.logger.info('Plugin initializing...');
-
   // Subscribe to events
-  const conversationSub = ctx.majk.eventBus.conversations().subscribe((event) => {
-    ctx.logger.info(`Conversation ${event.type}: ${event.entity?.id}`);
+  const sub = ctx.majk.eventBus.conversations().subscribe((event) => {
+    ctx.logger.info(`Conversation event: ${event.type}`);
   });
-  cleanup(() => conversationSub.unsubscribe());
+  cleanup(() => sub.unsubscribe());
 
-  // Set up periodic tasks
+  // Set up timers
   const timer = setInterval(() => {
-    ctx.logger.debug('Health check');
+    ctx.logger.debug('Periodic check');
   }, 60000);
   cleanup(() => clearInterval(timer));
 
-  // Load data
-  const data = await ctx.storage.get('plugin-data') || {};
-  ctx.logger.info(`Loaded ${Object.keys(data).length} items`);
+  // Any other setup
+  await loadData(ctx.storage);
 })
 ```
 
-**Cleanup Management:**
-All cleanup functions registered via `cleanup()` are automatically called when the plugin unloads.
+**Cleanup Registration:**
+All cleanup functions are automatically called on `onUnload()`.
 
-### Health Checks
+#### Health Checks
 
 Define custom health monitoring:
 
 ```typescript
 .health(async ({ majk, storage, logger }) => {
   try {
-    // Check MAJK API
+    // Check dependencies
     await majk.conversations.list();
-
-    // Check storage
-    await storage.get('health-test');
-
-    // Check external dependencies
-    const externalOk = await checkExternalAPI();
+    await storage.get('health-check');
 
     return {
       healthy: true,
-      details: {
-        api: 'ok',
-        storage: 'ok',
-        external: externalOk ? 'ok' : 'degraded'
-      }
+      details: { api: 'ok', storage: 'ok' }
     };
   } catch (error) {
     logger.error(`Health check failed: ${error.message}`);
@@ -905,209 +319,7 @@ Define custom health monitoring:
 })
 ```
 
----
-
-## 🎨 Client Generation
-
-Plugin-kit can auto-generate TypeScript clients with React hooks from your function definitions.
-
-### Generate Client
-
-```bash
-npx plugin-kit generate -e ./index.js -o ./ui/src/generated
-```
-
-**Output:**
-```
-ui/src/generated/
-├── types.ts      # TypeScript types from schemas
-├── client.ts     # Base client with fetch wrappers
-├── hooks.ts      # React hooks (useGetMessage, etc)
-└── index.ts      # Re-exports
-```
-
-### Using Generated Hooks
-
-```tsx
-import { useCreateTask, useGetTasks } from './generated';
-
-function TaskList() {
-  // Query hook
-  const { data: tasks, loading, error, refetch } = useGetTasks({});
-
-  // Mutation hook
-  const { mutate: createTask, loading: creating } = useCreateTask();
-
-  const handleCreate = async () => {
-    const result = await createTask({
-      title: 'New task',
-      priority: 'high'
-    });
-
-    if (result.success) {
-      refetch();  // Refresh list
-    }
-  };
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-
-  return (
-    <div>
-      {tasks?.map(task => (
-        <div key={task.id}>{task.title}</div>
-      ))}
-      <button onClick={handleCreate} disabled={creating}>
-        {creating ? 'Creating...' : 'Add Task'}
-      </button>
-    </div>
-  );
-}
-```
-
-### Hook API
-
-**Query Hooks** (for data fetching):
-```typescript
-const { data, loading, error, refetch } = useGetTasks({ filter: 'active' });
-```
-
-**Mutation Hooks** (for data modification):
-```typescript
-const { mutate, loading, error } = useCreateTask();
-
-// Call the mutation
-const result = await mutate({ title: 'Task' });
-```
-
-### Auto-Generated Config Functions
-
-When you define a `configWizard` with a `schema`, plugin-kit automatically generates:
-
-```typescript
-// In your UI
-import { useUpdateConfig, useGetConfig } from './generated';
-
-function ConfigWizard() {
-  const { mutate: updateConfig, loading } = useUpdateConfig();
-  const { data: config } = useGetConfig({});
-
-  const handleSubmit = async (formData) => {
-    const result = await updateConfig(formData);
-
-    if (result.success) {
-      // Close modal
-      window.parent.postMessage({
-        type: 'majk:config-complete',
-        pluginId: 'my-plugin',
-        redirectTo: '/plugins'
-      }, '*');
-    }
-  };
-
-  return <form onSubmit={handleSubmit}>...</form>;
-}
-```
-
----
-
-## 📖 Complete Example
-
-See `samples/kitchen-sink` for a comprehensive example showing:
-
-```typescript
-import { definePlugin, HttpTransport } from '@majkapp/plugin-kit';
-
-const ConfigSchema = {
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-    systemPrompt: { type: 'string' }
-  },
-  required: ['name']
-};
-
-export = definePlugin('kitchen-sink', 'Kitchen Sink Demo', '1.0.0')
-  .pluginRoot(__dirname)
-
-  // Functions
-  .function('createTask', {
-    description: 'Creates a new task.',
-    input: { /* schema */ },
-    output: { /* schema */ },
-    handler: async (input, ctx) => { /* ... */ }
-  })
-
-  // Configurable entities
-  .configWizard({
-    schema: ConfigSchema,
-    storageKey: 'teammate-config',
-    path: '/plugin-screens/kitchen-sink/main',
-    hash: '#/config-wizard',
-    title: 'Configure Assistant',
-    shouldShow: async (ctx) => !await ctx.storage.get('teammate-config')
-  })
-
-  .configurableTeamMember((config) => [{
-    id: 'my-assistant',
-    name: config.name,
-    systemPrompt: config.systemPrompt
-  }])
-
-  // UI
-  .ui({ appDir: 'dist', base: '/', history: 'hash' })
-
-  .screenReact({
-    id: 'main',
-    name: 'Kitchen Sink',
-    description: 'Comprehensive demo of all plugin-kit features.',
-    route: '/plugin-screens/kitchen-sink/main',
-    reactPath: '/'
-  })
-
-  // Tools
-  .tool('global', {
-    name: 'analyze',
-    description: 'Analyzes input data.',
-    inputSchema: { /* ... */ }
-  }, handler)
-
-  // Static entities
-  .mcpServer([{ /* ... */ }])
-
-  // Navigation
-  .topbar('/plugin-screens/kitchen-sink/main', { icon: '🧰' })
-
-  // Settings
-  .settings({
-    path: '/plugin-screens/kitchen-sink/main',
-    hash: '#/settings',
-    title: 'Settings',
-    description: 'Reconfigure the plugin.'
-  })
-
-  // Lifecycle
-  .onReady(async (ctx, cleanup) => {
-    const sub = ctx.majk.eventBus.subscribeAll((event) => {
-      ctx.logger.info(`Event: ${event.type}`);
-    });
-    cleanup(() => sub.unsubscribe());
-  })
-
-  .health(async ({ storage }) => {
-    await storage.get('health-check');
-    return { healthy: true };
-  })
-
-  // Transport
-  .transport(new HttpTransport())
-
-  .build();
-```
-
----
-
-## 📚 API Reference
+## API Reference
 
 ### PluginContext
 
@@ -1115,71 +327,33 @@ Provided to all handlers and hooks:
 
 ```typescript
 interface PluginContext {
-  pluginId: string;              // Your plugin ID
-  pluginRoot: string;            // Plugin directory path
-  dataDir: string;               // Plugin data directory
+  pluginId: string;        // Your plugin ID
+  pluginRoot: string;      // Plugin directory path
+  dataDir: string;         // Plugin data directory
 
   app: {
-    version: string;             // MAJK version
-    name: string;                // App name
-    appDataDir: string;          // App data directory
+    version: string;       // MAJK version
+    name: string;          // App name
+    appDataDir: string;    // App data directory
   };
 
   http: {
-    port: number;                // Assigned HTTP port
-    secret: string;              // Security secret
-    baseUrl: string;             // Base URL for iframe
+    port: number;          // Assigned HTTP port
+    secret: string;        // Security secret
+    baseUrl: string;       // Base URL for iframe
   };
 
-  majk: MajkInterface;           // Full MAJK API
-  storage: PluginStorage;        // Key-value storage
-  logger: PluginLogger;          // Scoped logger
-  timers?: ScopedTimers;         // Managed timers
-  ipc?: ScopedIpcRegistry;       // Electron IPC
-}
-```
-
-### PluginStorage
-
-Simple key-value storage scoped to your plugin:
-
-```typescript
-interface PluginStorage {
-  get<T>(key: string): Promise<T | undefined>;
-  set<T>(key: string, value: T): Promise<void>;
-  delete(key: string): Promise<void>;
-  clear(): Promise<void>;
-  keys(): Promise<string[]>;
+  majk: MajkInterface;     // Full MAJK API
+  storage: PluginStorage;  // Key-value storage
+  logger: PluginLogger;    // Scoped logger
+  timers?: ScopedTimers;   // Managed timers
+  ipc?: ScopedIpcRegistry; // Electron IPC
 }
-
-// Usage
-await storage.set('user-prefs', { theme: 'dark' });
-const prefs = await storage.get('user-prefs');
-await storage.delete('old-key');
-await storage.clear();
-const allKeys = await storage.keys();
-```
-
-### PluginLogger
-
-Structured logging with levels:
-
-```typescript
-interface PluginLogger {
-  debug(message: string, ...args: any[]): void;
-  info(message: string, ...args: any[]): void;
-  warn(message: string, ...args: any[]): void;
-  error(message: string, ...args: any[]): void;
-}
-
-// Usage
-logger.info('User action', { userId, action: 'create' });
-logger.error('Failed to process', { error: error.message });
 ```
 
 ### MajkInterface
 
-The main MAJK API (subset shown):
+The main MAJK API:
 
 ```typescript
 interface MajkInterface {
@@ -1197,464 +371,266 @@ interface MajkInterface {
 }
 ```
 
-### MAJK API Deep Dive
+### PluginStorage
 
-The `ctx.majk` object provides access to the full MAJK platform API. Below are detailed examples of each subsystem with **verified** code from the kitchen-sink sample.
+Simple key-value storage scoped to your plugin:
 
-#### Conversations API
+```typescript
+interface PluginStorage {
+  get<T>(key: string): Promise<T | undefined>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+}
+```
 
-Manage conversations and messages:
+**Example:**
 
 ```typescript
-// List all conversations
-.function('getConversations', {
-  description: 'Lists all conversations.',
-  handler: async (_, ctx) => {
-    const conversations = await ctx.majk.conversations.list();
-
-    return conversations.map(conv => ({
-      id: conv.id,
-      title: conv.title || 'Untitled',
-      createdAt: conv.createdAt,
-      messageCount: conv.messageCount || 0
-    }));
-  }
-})
+// Save data
+await storage.set('user-preferences', {
+  theme: 'dark',
+  notifications: true
+});
 
-// Get a specific conversation with messages
-.function('getConversationMessages', {
-  description: 'Gets messages from a conversation.',
-  handler: async ({ conversationId }, ctx) => {
-    // Get conversation handle
-    const conversation = await ctx.majk.conversations.get(conversationId);
+// Load data
+const prefs = await storage.get<Preferences>('user-preferences');
 
-    if (!conversation) {
-      return { success: false, error: 'Conversation not found' };
-    }
+// List all keys
+const keys = await storage.keys();
 
-    // Fetch messages
-    const messages = await conversation.getMessages();
+// Delete specific key
+await storage.delete('old-data');
 
-    return {
-      success: true,
-      data: messages.map(msg => ({
-        id: msg.id,
-        content: msg.content,
-        role: msg.role,
-        createdAt: msg.createdAt
-      }))
-    };
-  }
-})
+// Clear everything
+await storage.clear();
 ```
 
-**Available Methods:**
-- `list()` - Get all conversations
-- `get(id)` - Get conversation handle
-- `conversation.getMessages()` - Get messages from conversation
-- `conversation.addMessage(message)` - Add message to conversation
-
-#### Teammates API
+### EventBus
 
-Manage AI teammates:
+Subscribe to system events:
 
 ```typescript
-// List all teammates
-.function('getTeammates', {
-  description: 'Lists all teammates.',
-  handler: async (_, ctx) => {
-    const teammates = await ctx.majk.teammates.list();
-
-    return teammates.map(teammate => ({
-      id: teammate.id,
-      name: teammate.name,
-      systemPrompt: teammate.systemPrompt,
-      expertise: teammate.expertise || [],
-      mcpServerIds: teammate.mcpServerIds || [],
-      skills: teammate.skills || {}
-    }));
-  }
-})
+// Listen to conversation events
+const sub = majk.eventBus.conversations().subscribe((event) => {
+  console.log(`Event: ${event.type}`, event.entity);
+});
 
-// Get specific teammate
-.function('getTeammate', {
-  description: 'Gets a specific teammate.',
-  handler: async ({ teammateId }, ctx) => {
-    const teammate = await ctx.majk.teammates.get(teammateId);
+// Unsubscribe
+sub.unsubscribe();
 
-    if (!teammate) {
-      return { success: false, error: 'Teammate not found' };
-    }
+// Specific event types
+majk.eventBus.conversations().created().subscribe(...);
+majk.eventBus.conversations().updated().subscribe(...);
+majk.eventBus.conversations().deleted().subscribe(...);
 
-    return {
-      success: true,
-      data: {
-        id: teammate.id,
-        name: teammate.name,
-        systemPrompt: teammate.systemPrompt,
-        expertise: teammate.expertise,
-        personality: teammate.personality,
-        metadata: teammate.metadata
-      }
-    };
-  }
-})
+// Custom channels
+majk.eventBus.channel('my-events').subscribe(...);
 ```
 
-**Available Methods:**
-- `list()` - Get all teammates
-- `get(id)` - Get specific teammate
-- `create(teammate)` - Create new teammate (used by configurable entities)
-- `update(id, teammate)` - Update teammate
-- `delete(id)` - Delete teammate
+## Validation & Error Handling
 
-#### Authentication API
+### Build-Time Validation
 
-Access user authentication information:
+The kit validates at build time:
 
-```typescript
-// Check authentication status
-.function('checkAuth', {
-  description: 'Checks if user is authenticated.',
-  handler: async (_, ctx) => {
-    const isAuthenticated = await ctx.majk.auth.isAuthenticated();
-    const account = await ctx.majk.auth.getAccount();
+✅ **Route Prefixes** - Screen routes must match plugin ID
+✅ **File Existence** - React dist and HTML files must exist
+✅ **Uniqueness** - No duplicate routes, tools, or API endpoints
+✅ **Dependencies** - UI must be configured for React screens
+✅ **Descriptions** - Must be 2-3 sentences ending with period
 
-    return {
-      authenticated: isAuthenticated,
-      account: account ? {
-        id: account.id,
-        name: account.name,
-        email: account.email
-      } : null
-    };
-  }
-})
+**Example Error:**
 
-// Get accounts of specific type
-.function('getAccounts', {
-  description: 'Gets accounts by type.',
-  handler: async ({ accountType }, ctx) => {
-    // accountType: 'github', 'google', 'email', or '*' for all
-    const accounts = await ctx.majk.auth.getAccountsOfType(accountType);
-
-    return accounts.map(account => ({
-      id: account.id,
-      type: account.type,
-      name: account.name,
-      email: account.email
-    }));
-  }
-})
+```
+❌ Plugin Build Failed: React screen route must start with "/plugin-screens/my-plugin/"
+💡 Suggestion: Change route from "/screens/dashboard" to "/plugin-screens/my-plugin/dashboard"
+📋 Context: {
+  "screen": "dashboard",
+  "route": "/screens/dashboard"
+}
 ```
 
-**Available Methods:**
-- `isAuthenticated()` - Check if user is logged in
-- `getAccount()` - Get current account
-- `getAccountsOfType(type)` - Get accounts by type ('github', 'google', 'email', '*')
-
-#### EventBus API
+### Runtime Error Handling
 
-Subscribe to real-time system events:
+All API route errors are automatically caught and logged:
 
 ```typescript
-// Subscribe to all events (in onReady hook)
-.onReady(async (ctx, cleanup) => {
-  const subscription = ctx.majk.eventBus.subscribeAll((event) => {
-    ctx.logger.info(`Event: ${event.entityType}.${event.type}`);
-    ctx.logger.info(`Entity ID: ${event.entity?.id}`);
-
-    // event structure:
+.apiRoute({
+  method: 'POST',
+  path: '/api/process',
+  name: 'Process Data',
+  description: 'Processes input data. Validates and transforms the payload.',
+  handler: async (req, res, { logger }) => {
+    // Errors are automatically caught and returned as 500 responses
+    throw new Error('Processing failed');
+
+    // Returns:
     // {
-    //   type: 'created' | 'updated' | 'deleted',
-    //   entityType: 'conversation' | 'teammate' | 'todo' | etc,
-    //   entity: { id, ...otherFields },
-    //   metadata: { ... }
+    //   "error": "Processing failed",
+    //   "route": "Process Data",
+    //   "path": "/api/process"
     // }
-  });
-
-  // Always cleanup subscriptions
-  cleanup(() => subscription.unsubscribe());
-})
-
-// Subscribe to specific entity type
-.onReady(async (ctx, cleanup) => {
-  // Conversations only
-  const convSub = ctx.majk.eventBus.conversations().subscribe((event) => {
-    if (event.type === 'created') {
-      ctx.logger.info(`New conversation: ${event.entity.title}`);
-    }
-  });
-
-  cleanup(() => convSub.unsubscribe());
-})
-
-// Subscribe to specific event type
-.onReady(async (ctx, cleanup) => {
-  // Only conversation creations
-  const sub = ctx.majk.eventBus.conversations().created().subscribe((event) => {
-    ctx.logger.info(`Created: ${event.entity.id}`);
-  });
-
-  cleanup(() => sub.unsubscribe());
-})
-
-// Custom channel
-.onReady(async (ctx, cleanup) => {
-  const sub = ctx.majk.eventBus.channel('my-plugin-events').subscribe((event) => {
-    // Handle custom events
-  });
-
-  cleanup(() => sub.unsubscribe());
-})
-```
-
-**Event Types:**
-- `created` - Entity was created
-- `updated` - Entity was modified
-- `deleted` - Entity was removed
-
-**Entity Types:**
-- `conversation` - Conversation events
-- `teammate` - Teammate events
-- `todo` - Todo/task events
-- `project` - Project events
-- `message` - Message events
-
-**Available Methods:**
-- `subscribeAll(handler)` - Subscribe to all events
-- `conversations()` - Conversation events only
-- `teammates()` - Teammate events only
-- `todos()` - Todo events only
-- `projects()` - Project events only
-- `channel(name)` - Custom event channel
-- `.created()` - Filter to created events only
-- `.updated()` - Filter to updated events only
-- `.deleted()` - Filter to deleted events only
-- `subscription.unsubscribe()` - Stop listening
-
-#### Storage API
-
-Plugin-scoped persistent storage:
-
-```typescript
-// Save data
-.function('saveSettings', {
-  description: 'Saves user settings.',
-  handler: async ({ settings }, ctx) => {
-    await ctx.storage.set('user-settings', settings);
-    return { success: true };
-  }
-})
-
-// Load data
-.function('getSettings', {
-  description: 'Loads user settings.',
-  handler: async (_, ctx) => {
-    const settings = await ctx.storage.get('user-settings');
-    return settings || { theme: 'light', notifications: true };
-  }
-})
-
-// List all keys
-.function('listStorageKeys', {
-  description: 'Lists all storage keys.',
-  handler: async (_, ctx) => {
-    const keys = await ctx.storage.keys();
-    return { keys, count: keys.length };
-  }
-})
-
-// Delete specific key
-.function('clearCache', {
-  description: 'Clears cached data.',
-  handler: async (_, ctx) => {
-    await ctx.storage.delete('cache');
-    return { success: true };
-  }
-})
-
-// Clear all storage
-.function('resetPlugin', {
-  description: 'Resets all plugin data.',
-  handler: async (_, ctx) => {
-    await ctx.storage.clear();
-    return { success: true, message: 'All data cleared' };
   }
 })
 ```
 
-**Available Methods:**
-- `get<T>(key)` - Retrieve value (returns undefined if not found)
-- `set<T>(key, value)` - Store value (any JSON-serializable data)
-- `delete(key)` - Remove specific key
-- `clear()` - Remove all plugin data
-- `keys()` - List all storage keys
-
-**Best Practices:**
-- ✅ Use namespaced keys: `user-settings`, `cache:conversations`, `state:ui`
-- ✅ Type your storage: `await ctx.storage.get<UserSettings>('settings')`
-- ✅ Handle missing data: `const data = await ctx.storage.get('key') || defaultValue`
-- ❌ Don't store secrets - use environment variables or MAJK secrets API
-
----
-
-## ✅ Best Practices
-
-### 1. Always Use `.pluginRoot(__dirname)`
-
-```typescript
-// ✅ CORRECT
-definePlugin('my-plugin', 'My Plugin', '1.0.0')
-  .pluginRoot(__dirname)
-  // ...
-
-// ❌ WRONG - file resolution may fail
-definePlugin('my-plugin', 'My Plugin', '1.0.0')
-  // ...
+Logs show:
+```
+❌ POST /api/process - Error: Processing failed
+[stack trace]
 ```
 
-### 2. Use Storage for State
+## Best Practices
+
+### 1. Use Storage for State
 
 ```typescript
-// ❌ Don't use in-memory state (lost on reload)
+// ❌ Don't use in-memory state
 let cache = {};
 
-// ✅ Use storage (persisted)
+// ✅ Use storage
 await ctx.storage.set('cache', data);
 ```
 
-### 3. Register Cleanups
+### 2. Register Cleanups
 
 ```typescript
 .onReady(async (ctx, cleanup) => {
-  // ❌ Forgot to cleanup
-  const timer = setInterval(() => { /* ... */ }, 1000);
+  // ❌ Don't forget to cleanup
+  const timer = setInterval(...);
 
-  // ✅ Registered cleanup
-  const timer = setInterval(() => { /* ... */ }, 1000);
+  // ✅ Register cleanup
+  const timer = setInterval(...);
   cleanup(() => clearInterval(timer));
 
   // ✅ Event subscriptions
-  const sub = ctx.majk.eventBus.conversations().subscribe(handler);
+  const sub = ctx.majk.eventBus.conversations().subscribe(...);
   cleanup(() => sub.unsubscribe());
 })
 ```
 
-### 4. Write Good Descriptions
+### 3. Validate Input
 
 ```typescript
-// ❌ Too short
-description: 'Dashboard screen'
+.apiRoute({
+  method: 'POST',
+  path: '/api/create',
+  name: 'Create Item',
+  description: 'Creates a new item. Validates input before processing.',
+  handler: async (req, res) => {
+    // ✅ Validate input
+    if (!req.body?.name) {
+      res.status(400).json({ error: 'Name is required' });
+      return;
+    }
 
-// ✅ 2-3 sentences, clear purpose
-description: 'Main dashboard view. Shows key metrics and recent activity.'
+    // Process...
+  }
+})
 ```
 
-### 5. Handle Errors Gracefully
+### 4. Use Structured Logging
 
 ```typescript
-// ✅ Return structured errors
-.function('process', {
-  // ...
-  handler: async (input, ctx) => {
-    try {
-      const result = await processData(input);
-      return { success: true, data: result };
-    } catch (error) {
-      ctx.logger.error('Processing failed', { error: error.message });
-      return {
-        success: false,
-        error: error.message,
-        code: 'PROCESSING_ERROR'
-      };
-    }
-  }
-})
+// ❌ Basic logging
+logger.info('User action');
+
+// ✅ Structured logging
+logger.info('User action', { userId, action: 'create', resourceId });
 ```
 
-### 6. Validate Input
+### 5. Handle Errors Gracefully
 
 ```typescript
-.function('create', {
-  // ...
-  handler: async (input, ctx) => {
-    // Validate business rules beyond schema
-    if (input.priority === 'high' && !input.assignee) {
-      return {
-        success: false,
-        error: 'High priority items must have an assignee'
-      };
-    }
-    // Process...
+.tool('global', spec, async (input, { logger }) => {
+  try {
+    const result = await processData(input);
+    return { success: true, data: result };
+  } catch (error) {
+    logger.error(`Tool failed: ${error.message}`);
+    return {
+      success: false,
+      error: error.message,
+      code: 'PROCESSING_ERROR'
+    };
   }
 })
 ```
 
-### 7. Use Configurable Entities for User Customization
+## Examples
 
-```typescript
-// ✅ Let users configure teammates
-.configWizard({ schema: TeammateConfigSchema, ... })
-.configurableTeamMember((config) => [buildTeammate(config)])
+See `example.ts` for a comprehensive example showing:
+- React and HTML screens
+- API routes with parameters
+- Tools in different scopes
+- Entity declarations
+- Config wizard
+- Event subscriptions
+- Storage usage
+- Health checks
 
-// ❌ Hard-coded teammates (less flexible)
-.teamMember([{ id: 'assistant', name: 'Assistant', ... }])
-```
+## TypeScript
 
----
+Full TypeScript support with:
 
-## 🐛 Troubleshooting
+```typescript
+import {
+  definePlugin,
+  FluentBuilder,
+  PluginContext,
+  RequestLike,
+  ResponseLike
+} from '@majk/plugin-kit';
 
-### Build Errors
+// Type-safe plugin ID
+const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0');
+//                           ^ Enforces route prefixes
 
-**"React app not built"**
-```
-❌ React app not built: /path/to/ui/dist/index.html does not exist
-💡 Run "npm run build" in your UI directory
+// Type-safe routes
+.screenReact({
+  route: '/plugin-screens/my-plugin/dashboard'
+  //                      ^^^^^^^^^ Must match plugin ID
+})
 ```
-Fix: Build your React app before building the plugin.
 
-**"Configurable entities require configWizard with schema"**
-```
-❌ You used .configurableTeamMember() but did not call .configWizard()
-💡 Add .configWizard({ schema: YourSchema, ... })
-```
+## Troubleshooting
+
+### "React app not built"
 
-**"Screen route must start with /plugin-screens/{id}/"**
 ```
-❌ Route "/screens/dashboard" doesn't match pattern
-💡 Change to "/plugin-screens/my-plugin/dashboard"
+❌ Plugin Build Failed: React app not built: /path/to/ui/dist/index.html does not exist
+💡 Suggestion: Run "npm run build" in your UI directory to build the React app
 ```
 
-### Runtime Errors
+**Fix:** Build your React app before building the plugin.
 
-**"Cannot read properties of undefined (reading 'logger')"**
-- Ensure `getCapabilities()` checks if `context` is available
-- This is handled automatically in v1.1.0+
+### "Duplicate API route"
 
-**Functions not appearing in generated client**
-- Ensure you call `.transport(new HttpTransport())`
-- Run `npx plugin-kit generate` after adding functions
+```
+❌ Plugin Build Failed: Duplicate API route: POST /api/data
+```
 
-### Config Not Working
+**Fix:** Each route (method + path) must be unique.
 
-**Teammate not appearing after config wizard**
-- Check that `postMessage({ type: 'majk:config-complete' })` is sent
-- Verify `pluginId` in postMessage matches your plugin ID
-- Check plugin logs for `[ConfigWizard]` messages
-- Ensure plugin reloaded after config completion
+### "Description must be 2-3 sentences"
 
----
+```
+❌ Plugin Build Failed: Description for "My Screen" must be 2-3 sentences, found 1 sentences
+💡 Suggestion: Rewrite the description to have 2-3 clear sentences.
+```
 
-## 📝 License
+**Fix:** Write 2-3 complete sentences ending with periods.
 
-MIT
+### "Tool names must be unique"
 
-## 🤝 Contributing
+```
+❌ Plugin Build Failed: Duplicate tool name: "analyze"
+```
 
-Issues and pull requests welcome at https://github.com/gaiin-platform/majk-plugins
+**Fix:** Each tool name must be unique within the plugin.
 
----
+## License
 
-**Built with ❤️ by the MAJK team**
+MIT