@majkapp/plugin-kit 1.1.0 → 1.2.0

package/README.md

@@ -1,135 +1,480 @@
-# @majk/plugin-kit
+# @majkapp/plugin-kit
 
-**Fluent builder framework for creating robust MAJK plugins**
+**Modern, type-safe framework for building MAJK plugins with exceptional developer experience**
 
-Build type-safe, production-ready MAJK plugins with excellent developer experience, comprehensive validation, and clear error messages.
+Build production-ready MAJK plugins using a fluent builder API with comprehensive validation, auto-generated clients, and declarative configuration management.
 
-## Features
+[![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)
 
-✨ **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
+## ✨ Features
 
-## Installation
+- 🎯 **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
 
 ```bash
-npm install @majk/plugin-kit
+npm install @majkapp/plugin-kit
 ```
 
-## Quick Start
+---
+
+## 🚀 Quick Start
 
 ```typescript
-import { definePlugin } from '@majk/plugin-kit';
+import { definePlugin, HttpTransport } from '@majkapp/plugin-kit';
 
-export default definePlugin('my-plugin', 'My Plugin', '1.0.0')
-  .ui({ appDir: 'ui/dist' })
+export = definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
 
-  .topbar('/plugin-screens/my-plugin/dashboard', {
-    icon: '🚀'
+  // 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}!` };
+    }
   })
 
-  .screenReact({
-    id: 'dashboard',
-    name: 'Dashboard',
-    description: 'Main dashboard for my plugin. Shows key metrics and actions.',
-    route: '/plugin-screens/my-plugin/dashboard',
-    reactPath: '/'
+  // Configure React UI
+  .ui({
+    appDir: 'dist',
+    base: '/',
+    history: 'hash'
   })
 
-  .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 };
-    }
+  // Add a screen
+  .screenReact({
+    id: 'main',
+    name: 'My Plugin',
+    description: 'Main plugin screen. Shows greeting and controls.',
+    route: '/plugin-screens/my-plugin/main',
+    reactPath: '/'
   })
 
-  .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() };
-  })
+  // Enable HTTP transport
+  .transport(new HttpTransport())
 
   .build();
 ```
 
-## Core Concepts
+Generate client:
+```bash
+npx plugin-kit generate -e ./index.js -o ./ui/src/generated
+```
+
+Use in React:
+```tsx
+import { useGetMessage } from './generated';
+
+function App() {
+  const { data, loading, error, mutate } = useGetMessage();
+
+  return (
+    <button onClick={() => mutate({ name: 'World' })}>
+      {loading ? 'Loading...' : data?.message}
+    </button>
+  );
+}
+```
+
+---
+
+## 📚 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
 
 ### Plugin Definition
 
 Every plugin starts with `definePlugin(id, name, version)`:
 
 ```typescript
-definePlugin('system-explorer', 'System Explorer', '1.0.0')
+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;
 ```
 
 **Rules:**
 - `id` must be unique and URL-safe (kebab-case recommended)
-- `name` is the display name
-- `version` follows semver
+- `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.
 
-### Screens
+### 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) => [...])
+```
+
+---
 
-#### React Screens
+## 🎨 UI Configuration
 
-For React SPAs, configure UI first:
+### React Applications
+
+For React SPAs, configure UI first, then add screens:
 
 ```typescript
 .ui({
-  appDir: 'ui/dist',        // Where your built React app is
-  base: '/',                // Base URL for the SPA
-  history: 'browser'        // 'browser' or 'hash' routing
+  appDir: 'dist',              // Where your built React app is
+  base: '/',                   // Base URL for the SPA
+  history: 'hash'              // 'browser' or 'hash' routing
 })
 
 .screenReact({
   id: 'dashboard',
   name: 'Dashboard',
-  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
+  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
 })
 ```
 
-**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
+**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
+```
 
-#### HTML Screens
+### HTML Screens
 
-For simple HTML pages:
+For simple static pages:
 
 ```typescript
 .screenHtml({
   id: 'about',
   name: 'About',
-  description: 'Information about the plugin. Shows version and author.',
+  description: 'Information about the plugin. Shows version and features.',
   route: '/plugin-screens/my-plugin/about',
-  html: '<html>...'  // OR htmlFile: 'about.html'
+  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
 })
 ```
 
-### API Routes
+### 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.
 
 Define REST endpoints:
 
@@ -138,60 +483,74 @@ Define REST endpoints:
   method: 'POST',
   path: '/api/tasks/:id/complete',
   name: 'Complete Task',
-  description: 'Marks a task as complete. Updates task status and triggers notifications.',
+  description: 'Marks a task as complete. Updates status and notifies users.',
   handler: async (req, res, { majk, storage, logger }) => {
-    const { id } = req.params;       // Path parameters
-    const { note } = req.body;       // Request body
-    const status = req.query.get('status');  // Query params
+    const { id } = req.params;              // Path parameters
+    const { note } = req.body;              // Request body (JSON parsed)
+    const status = req.query.get('status'); // Query string
 
     logger.info(`Completing task ${id}`);
 
-    // Access MAJK APIs
-    const todos = await majk.todos.list();
+    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;
 
-    // Use plugin storage
-    await storage.set(`task:${id}`, { completed: true });
+    await storage.set(`task:${id}`, task);
 
-    return { success: true, taskId: id };
+    return { success: true, task };
   }
 })
 ```
 
 **Available Methods:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
 
-**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)
+**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)
 
-### Tools
+---
 
-Tools are functions that agents can invoke:
+## 🛠️ Tools
+
+Tools are functions that AI agents can invoke. They're scoped to different contexts.
 
 ```typescript
 .tool(
   'conversation',  // Scope: 'global' | 'conversation' | 'teammate' | 'project'
   {
-    name: 'analyzeSentiment',
-    description: 'Analyzes text sentiment. Returns positive, negative, or neutral classification.',
+    name: 'analyzeCode',
+    description: 'Analyzes code for potential issues. Returns findings with severity.',
     inputSchema: {
       type: 'object',
       properties: {
-        text: { type: 'string' }
+        code: { type: 'string' },
+        language: { type: 'string' }
       },
-      required: ['text']
+      required: ['code', 'language']
     }
   },
   async (input, { majk, logger }) => {
-    logger.info('Analyzing sentiment');
+    logger.info(`Analyzing ${input.language} code`);
 
-    // Your implementation
-    const sentiment = analyzeSentiment(input.text);
+    const issues = analyzeCode(input.code, input.language);
 
     return {
       success: true,
-      data: { sentiment, confidence: 0.95 }
+      data: {
+        issues,
+        summary: `Found ${issues.length} issues`
+      }
     };
   }
 )
@@ -199,115 +558,342 @@ Tools are functions that agents can invoke:
 
 **Tool Scopes:**
 - `global` - Available everywhere
-- `conversation` - Scoped to conversations
-- `teammate` - Scoped to teammates
-- `project` - Scoped to projects
+- `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:
 
-### Entities
+```typescript
+.tool('conversation', {
+  name: 'contextualSearch',
+  description: 'Searches within conversation context.',
+  inputSchema: { /* ... */ },
+  metadata: {
+    conversationId: 'specific-conversation-id'  // Makes tool available only in this conversation
+  }
+}, handler)
+```
+
+---
 
-Declare entities your plugin provides:
+## 📦 Static Entities
+
+Declare entities your plugin always provides:
+
+### MCP Servers
 
 ```typescript
-.entity('teammate', [
+.mcpServer([
   {
-    id: 'bot-assistant',
-    name: 'Bot Assistant',
-    role: 'bot',
-    capabilities: ['analysis', 'reporting']
+    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
+    }
   }
 ])
+```
+
+### Team Members
 
-.entity('mcpServer', [
+```typescript
+.teamMember([
   {
-    id: 'custom-server',
-    name: 'Custom MCP Server',
-    transport: { type: 'stdio', command: 'node', args: ['server.js'] }
+    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'
   }
 ])
 ```
 
 **Supported Entity Types:**
 - `mcpServer` - MCP servers
-- `teammate` - Team members/bots
+- `teamMember` - Team members/bots
 - `conversation` - Conversations
-- `todo` - Tasks
 - `project` - Projects
 - `agent` - AI agents
 
-### Config Wizard & Settings
+---
+
+## 🔐 Secret Providers
 
-#### Config Wizard
+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.
 
-Show a wizard on first run:
+### Basic Secret Provider
 
 ```typescript
-.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
+.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())
+        };
+      }
+    };
   }
 })
 ```
 
-#### Settings Screen
+### 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`)
 
-Ongoing settings management:
+### Resolution Context
+
+When resolving secrets, MAJK provides context about where the secret is being used:
 
 ```typescript
-.settings({
-  path: '/settings',
-  title: 'Plugin Settings',
-  description: 'Manage plugin configuration. Adjust behavior and display options.'
+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;
+        }
+      }
+    };
+  }
 })
 ```
 
-### Lifecycle Hooks
+**Example: 1Password CLI**
 
-#### onReady
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
 
-Called after server starts, before `onLoad` completes:
+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' };
+        }
+      }
+    };
+  }
+})
+```
+
+---
+
+## 🔄 Lifecycle Hooks
+
+### onReady
+
+Called after the plugin's HTTP server starts, before `onLoad` completes:
 
 ```typescript
 .onReady(async (ctx, cleanup) => {
+  ctx.logger.info('Plugin initializing...');
+
   // Subscribe to events
-  const sub = ctx.majk.eventBus.conversations().subscribe((event) => {
-    ctx.logger.info(`Conversation event: ${event.type}`);
+  const conversationSub = ctx.majk.eventBus.conversations().subscribe((event) => {
+    ctx.logger.info(`Conversation ${event.type}: ${event.entity?.id}`);
   });
-  cleanup(() => sub.unsubscribe());
+  cleanup(() => conversationSub.unsubscribe());
 
-  // Set up timers
+  // Set up periodic tasks
   const timer = setInterval(() => {
-    ctx.logger.debug('Periodic check');
+    ctx.logger.debug('Health check');
   }, 60000);
   cleanup(() => clearInterval(timer));
 
-  // Any other setup
-  await loadData(ctx.storage);
+  // Load data
+  const data = await ctx.storage.get('plugin-data') || {};
+  ctx.logger.info(`Loaded ${Object.keys(data).length} items`);
 })
 ```
 
-**Cleanup Registration:**
-All cleanup functions are automatically called on `onUnload()`.
+**Cleanup Management:**
+All cleanup functions registered via `cleanup()` are automatically called when the plugin unloads.
 
-#### Health Checks
+### Health Checks
 
 Define custom health monitoring:
 
 ```typescript
 .health(async ({ majk, storage, logger }) => {
   try {
-    // Check dependencies
+    // Check MAJK API
     await majk.conversations.list();
-    await storage.get('health-check');
+
+    // Check storage
+    await storage.get('health-test');
+
+    // Check external dependencies
+    const externalOk = await checkExternalAPI();
 
     return {
       healthy: true,
-      details: { api: 'ok', storage: 'ok' }
+      details: {
+        api: 'ok',
+        storage: 'ok',
+        external: externalOk ? 'ok' : 'degraded'
+      }
     };
   } catch (error) {
     logger.error(`Health check failed: ${error.message}`);
@@ -319,7 +905,209 @@ Define custom health monitoring:
 })
 ```
 
-## API Reference
+---
+
+## 🎨 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
 
 ### PluginContext
 
@@ -327,33 +1115,71 @@ 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
+  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[]>;
 }
+
+// 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:
+The main MAJK API (subset shown):
 
 ```typescript
 interface MajkInterface {
@@ -371,266 +1197,464 @@ interface MajkInterface {
 }
 ```
 
-### PluginStorage
+### MAJK API Deep Dive
 
-Simple key-value storage scoped to your plugin:
+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.
 
-```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[]>;
-}
-```
+#### Conversations API
 
-**Example:**
+Manage conversations and messages:
 
 ```typescript
-// Save data
-await storage.set('user-preferences', {
-  theme: 'dark',
-  notifications: true
-});
+// 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
+    }));
+  }
+})
 
-// Load data
-const prefs = await storage.get<Preferences>('user-preferences');
+// 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);
 
-// List all keys
-const keys = await storage.keys();
+    if (!conversation) {
+      return { success: false, error: 'Conversation not found' };
+    }
 
-// Delete specific key
-await storage.delete('old-data');
+    // Fetch messages
+    const messages = await conversation.getMessages();
 
-// Clear everything
-await storage.clear();
+    return {
+      success: true,
+      data: messages.map(msg => ({
+        id: msg.id,
+        content: msg.content,
+        role: msg.role,
+        createdAt: msg.createdAt
+      }))
+    };
+  }
+})
 ```
 
-### EventBus
+**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
 
-Subscribe to system events:
+Manage AI teammates:
 
 ```typescript
-// Listen to conversation events
-const sub = majk.eventBus.conversations().subscribe((event) => {
-  console.log(`Event: ${event.type}`, event.entity);
-});
+// 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 || {}
+    }));
+  }
+})
 
-// Unsubscribe
-sub.unsubscribe();
+// Get specific teammate
+.function('getTeammate', {
+  description: 'Gets a specific teammate.',
+  handler: async ({ teammateId }, ctx) => {
+    const teammate = await ctx.majk.teammates.get(teammateId);
 
-// Specific event types
-majk.eventBus.conversations().created().subscribe(...);
-majk.eventBus.conversations().updated().subscribe(...);
-majk.eventBus.conversations().deleted().subscribe(...);
+    if (!teammate) {
+      return { success: false, error: 'Teammate not found' };
+    }
 
-// Custom channels
-majk.eventBus.channel('my-events').subscribe(...);
+    return {
+      success: true,
+      data: {
+        id: teammate.id,
+        name: teammate.name,
+        systemPrompt: teammate.systemPrompt,
+        expertise: teammate.expertise,
+        personality: teammate.personality,
+        metadata: teammate.metadata
+      }
+    };
+  }
+})
 ```
 
-## Validation & Error Handling
+**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
 
-### Build-Time Validation
+#### Authentication API
 
-The kit validates at build time:
+Access user authentication information:
 
-✅ **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
+```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();
 
-**Example Error:**
+    return {
+      authenticated: isAuthenticated,
+      account: account ? {
+        id: account.id,
+        name: account.name,
+        email: account.email
+      } : null
+    };
+  }
+})
 
+// 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"
-}
-```
 
-### Runtime Error Handling
+**Available Methods:**
+- `isAuthenticated()` - Check if user is logged in
+- `getAccount()` - Get current account
+- `getAccountsOfType(type)` - Get accounts by type ('github', 'google', 'email', '*')
+
+#### EventBus API
 
-All API route errors are automatically caught and logged:
+Subscribe to real-time system events:
 
 ```typescript
-.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:
+// 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:
     // {
-    //   "error": "Processing failed",
-    //   "route": "Process Data",
-    //   "path": "/api/process"
+    //   type: 'created' | 'updated' | 'deleted',
+    //   entityType: 'conversation' | 'teammate' | 'todo' | etc,
+    //   entity: { id, ...otherFields },
+    //   metadata: { ... }
     // }
-  }
+  });
+
+  // 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());
 })
-```
 
-Logs show:
+// 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());
+})
 ```
-❌ POST /api/process - Error: Processing failed
-[stack trace]
+
+**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' };
+  }
+})
 ```
 
-## Best Practices
+**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
+
+---
 
-### 1. Use Storage for State
+## ✅ Best Practices
+
+### 1. Always Use `.pluginRoot(__dirname)`
 
 ```typescript
-// ❌ Don't use in-memory state
+// ✅ CORRECT
+definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  .pluginRoot(__dirname)
+  // ...
+
+// ❌ WRONG - file resolution may fail
+definePlugin('my-plugin', 'My Plugin', '1.0.0')
+  // ...
+```
+
+### 2. Use Storage for State
+
+```typescript
+// ❌ Don't use in-memory state (lost on reload)
 let cache = {};
 
-// ✅ Use storage
+// ✅ Use storage (persisted)
 await ctx.storage.set('cache', data);
 ```
 
-### 2. Register Cleanups
+### 3. Register Cleanups
 
 ```typescript
 .onReady(async (ctx, cleanup) => {
-  // ❌ Don't forget to cleanup
-  const timer = setInterval(...);
+  // ❌ Forgot to cleanup
+  const timer = setInterval(() => { /* ... */ }, 1000);
 
-  // ✅ Register cleanup
-  const timer = setInterval(...);
+  // ✅ Registered cleanup
+  const timer = setInterval(() => { /* ... */ }, 1000);
   cleanup(() => clearInterval(timer));
 
   // ✅ Event subscriptions
-  const sub = ctx.majk.eventBus.conversations().subscribe(...);
+  const sub = ctx.majk.eventBus.conversations().subscribe(handler);
   cleanup(() => sub.unsubscribe());
 })
 ```
 
-### 3. Validate Input
+### 4. Write Good Descriptions
 
 ```typescript
-.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;
-    }
+// ❌ Too short
+description: 'Dashboard screen'
 
-    // Process...
-  }
-})
+// ✅ 2-3 sentences, clear purpose
+description: 'Main dashboard view. Shows key metrics and recent activity.'
 ```
 
-### 4. Use Structured Logging
+### 5. Handle Errors Gracefully
 
 ```typescript
-// ❌ Basic logging
-logger.info('User action');
-
-// ✅ Structured logging
-logger.info('User action', { userId, action: 'create', resourceId });
+// ✅ 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'
+      };
+    }
+  }
+})
 ```
 
-### 5. Handle Errors Gracefully
+### 6. Validate Input
 
 ```typescript
-.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'
-    };
+.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...
   }
 })
 ```
 
-## Examples
+### 7. Use Configurable Entities for User Customization
 
-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
+```typescript
+// ✅ Let users configure teammates
+.configWizard({ schema: TeammateConfigSchema, ... })
+.configurableTeamMember((config) => [buildTeammate(config)])
 
-## TypeScript
+// ❌ Hard-coded teammates (less flexible)
+.teamMember([{ id: 'assistant', name: 'Assistant', ... }])
+```
 
-Full TypeScript support with:
+---
 
-```typescript
-import {
-  definePlugin,
-  FluentBuilder,
-  PluginContext,
-  RequestLike,
-  ResponseLike
-} from '@majk/plugin-kit';
+## 🐛 Troubleshooting
 
-// Type-safe plugin ID
-const plugin = definePlugin('my-plugin', 'My Plugin', '1.0.0');
-//                           ^ Enforces route prefixes
+### Build Errors
 
-// Type-safe routes
-.screenReact({
-  route: '/plugin-screens/my-plugin/dashboard'
-  //                      ^^^^^^^^^ Must match plugin ID
-})
+**"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
+```
+Fix: Build your React app before building the plugin.
 
-## Troubleshooting
-
-### "React app not built"
+**"Configurable entities require configWizard with schema"**
+```
+❌ You used .configurableTeamMember() but did not call .configWizard()
+💡 Add .configWizard({ schema: YourSchema, ... })
+```
 
+**"Screen route must start with /plugin-screens/{id}/"**
 ```
-❌ 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
+❌ Route "/screens/dashboard" doesn't match pattern
+💡 Change to "/plugin-screens/my-plugin/dashboard"
 ```
 
-**Fix:** Build your React app before building the plugin.
+### Runtime Errors
 
-### "Duplicate API route"
+**"Cannot read properties of undefined (reading 'logger')"**
+- Ensure `getCapabilities()` checks if `context` is available
+- This is handled automatically in v1.1.0+
 
-```
-❌ Plugin Build Failed: Duplicate API route: POST /api/data
-```
+**Functions not appearing in generated client**
+- Ensure you call `.transport(new HttpTransport())`
+- Run `npx plugin-kit generate` after adding functions
 
-**Fix:** Each route (method + path) must be unique.
+### Config Not Working
 
-### "Description must be 2-3 sentences"
+**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
 
-```
-❌ 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.
-```
+---
 
-**Fix:** Write 2-3 complete sentences ending with periods.
+## 📝 License
 
-### "Tool names must be unique"
+MIT
 
-```
-❌ Plugin Build Failed: Duplicate tool name: "analyze"
-```
+## 🤝 Contributing
 
-**Fix:** Each tool name must be unique within the plugin.
+Issues and pull requests welcome at https://github.com/gaiin-platform/majk-plugins
 
-## License
+---
 
-MIT
+**Built with ❤️ by the MAJK team**