@kadi.build/core 0.0.1-alpha.9 → 0.1.0

package/README.md

@@ -1,1479 +1,536 @@
-# @kadi.build/core
+# kadi-core
 
-> A comprehensive toolkit for building and managing KADI abilities with multiple transport protocols
+TypeScript SDK for building KADI agents. Register tools, connect to brokers, load abilities, publish events.
 
-[![npm version](https://img.shields.io/npm/v/@kadi.build/core.svg)](https://www.npmjs.com/package/@kadi.build/core)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+kadi-core lets you:
+- **Expose functions** as callable tools over the network
+- **Discover and invoke** remote services without hardcoding URLs
+- **Communicate via events** across your service mesh
 
-## 🎯 Overview
-
-`@kadi.build/core` is the foundational library for creating KADI abilities - modular, protocol-agnostic components that can communicate via multiple transport layers. Whether you're building local tools, distributed systems, or high-performance native modules, this toolkit provides a unified, developer-friendly API that abstracts away transport complexity.
-
-## 📚 Table of Contents
-
-- [🎯 Overview](#-overview)
-- [📦 Installation](#-installation)
-- [🚀 Quick Start](#-quick-start)
-- [🔌 Transport Protocols](#-transport-protocols)
-- [🛠️ Creating Abilities](#-creating-abilities)
-- [🤖 Creating Agents](#-creating-agents)
-- [🔄 Architecture Deep Dive](#-architecture-deep-dive)
-- [📥 Loading Abilities](#-loading-abilities)
-- [⚙️ Configuration](#-configuration)
-- [🚀 Advanced Usage](#-advanced-usage)
-- [🔧 Development Workflow](#-development-workflow)
-- [📖 API Reference](#-api-reference)
-- [🎮 Running the Examples](#-running-the-examples)
-- [💡 Additional Examples](#-additional-examples)
-- [🐛 Troubleshooting](#-troubleshooting)
-- [🤝 Contributing](#-contributing)
-- [📄 License](#-license)
-- [🔗 Related Projects](#-related-projects)
-- [📚 Resources](#-resources)
-
-## 📦 Installation
+## Install
 
 ```bash
 npm install @kadi.build/core
 ```
 
-For global CLI tools:
-
-```bash
-npm install -g @kadi.build/cli
-```
-
-## 🚀 Quick Start
-
-The library provides a unified way to work with KADI through the **KadiClient** class, which can operate in multiple roles:
+**Requirements:**
+- Node.js 18+
+- TypeScript 5.0+ (recommended for full type inference)
+- ESM only (`"type": "module"` in your package.json)
 
-- **As an Ability**: Serving tools/methods that others can call
-- **As an Agent**: Calling remote tools via broker protocol
-
-### Creating Your First Ability
-
-```javascript
-#!/usr/bin/env node
-import { KadiClient } from '@kadi.build/core';
-
-// Create a ability instance
-const mathAbility = new KadiClient({
-  name: 'math-ability',
-  role: 'ability', // 'agent', 'ability'
-  protocol: 'stdio' // 'native', 'stdio', or 'broker'
-});
-
-// Register a tool
-mathAbility.registerTool('add', async ({ a, b }) => {
-  return { result: a + b };
-});
-
-// Start serving requests
-mathAbility.serve().catch(console.error);
-```
+## Quick Start
 
-### Loading and Using Abilities
-
-```javascript
-import { loadAbility } from '@kadi.build/core';
-
-async function main() {
-  // Load an ability (uses first interface defined in agent.json)
-  const math = await loadAbility('math-ability');
-
-  // Call methods like regular functions
-  const result = await math.add({ a: 5, b: 3 });
-  console.log(result); // { result: 8 }
-}
-
-main().catch(console.error);
-```
-
-### Creating a Broker-Connected Agent
-
-```javascript
-import { KadiClient } from '@kadi.build/core';
-
-// Create an agent that connects to broker
-const agent = new KadiClient({
-  name: 'my-agent',
-  role: 'agent',
-  protocol: 'broker',
-  brokers: {
-    prod: 'ws://localhost:8080',
-    dev: 'ws://localhost:8081'
-  },
-  defaultBroker: 'prod',
-  networks: ['global']
-});
-
-// Register tools that other agents can call
-agent.registerTool(
-  'greet',
-  async ({ name }) => {
-    return { greeting: `Hello, ${name}!` };
-  },
-  {
-    description: 'Greet someone by name',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', description: 'Name to greet' }
-      },
-      required: ['name']
-    }
-  }
-);
+Create a simple calculator agent:
 
-// Connect to brokers and start serving
-await agent.connectToBrokers();
+```typescript
+// calculator.ts
+import { KadiClient, z } from '@kadi.build/core';
 
-// Call tools from OTHER agents connected to the same broker
-const result = await agent.callTool('translate', 'text-tool', {
-  text: 'Hello world',
-  language: 'spanish'
+const client = new KadiClient({
+  name: 'calculator',
+  version: '1.0.0',
 });
-console.log(result);
-```
-
-## 🔌 Transport Protocols
 
-KADI abilities support three transport protocols, each optimized for different use cases:
+client.registerTool({
+  name: 'add',
+  description: 'Add two numbers',
+  input: z.object({ a: z.number(), b: z.number() }),
+}, async ({ a, b }) => ({ result: a + b }));
 
-### 1. Native Protocol (Fastest)
-
-- **Use Case**: High-performance, in-process execution
-- **How it Works**: Loads abilities as ES modules, enabling direct function calls
-- **Performance**: Zero IPC overhead - functions run in the same process
-- **Best For**: Utility libraries, data processing, performance-critical operations
-
-```javascript
-// Loads as native module by default if available
-const ability = await loadAbility('my-ability', 'native');
+// Start listening for requests over stdio
+await client.serve('stdio');
 ```
 
-### 2. Stdio Protocol (Balanced)
+Now another agent can load and use it:
 
-- **Use Case**: Language-agnostic local execution
-- **How it Works**: Spawns abilities as child processes, communicates via LSP-style JSON-RPC over stdin/stdout
-- **Performance**: Minimal overhead, reliable local IPC
-- **Best For**: Python scripts, Go binaries, Node.js abilities, development/testing
+---
 
-```javascript
-// Force stdio protocol
-const ability = await loadAbility('my-ability', 'stdio');
-```
+## Table of Contents
 
-**Environment Variables Passed to Child Process:**
+- [Core Concepts](#core-concepts)
+- [Registering Tools](#registering-tools)
+- [Connecting to Brokers](#connecting-to-brokers)
+- [Loading Abilities](#loading-abilities)
+- [Events from Abilities](#events-from-abilities)
+- [Broker Events (Pub/Sub)](#broker-events-pubsub)
+- [Serving as an Ability](#serving-as-an-ability)
+- [Error Handling](#error-handling)
+- [API Reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
 
-```bash
-KADI_PROTOCOL=stdio  # Identifies the protocol being used
-# Plus all parent process.env variables
-```
+---
 
-### 3. Broker Protocol (Distributed)
+## Core Concepts
 
-- **Use Case**: Distributed systems, containerized deployments
-- **How it Works**: Abilities connect to a WebSocket broker for network communication
-- **Performance**: Network overhead, but enables scaling and distribution
-- **Best For**: Distributed abilities, cloud deployments, load-balanced systems
+| Concept | Plain English |
+|---------|---------------|
+| **Tool** | A function other services can call over the network (like an API endpoint) |
+| **Agent** | Your service. One codebase = one agent. Agents expose tools and call other agents' tools. |
+| **Broker** | The router/registry. Agents register with brokers so they can find each other (like DNS + API gateway combined) |
+| **Ability** | A tool provider you connect to. Could be in-process, a subprocess, or a remote service. |
+| **Event** | Fire-and-forget notification. Publish events, other agents can subscribe. |
 
-```javascript
-// Use broker for distributed execution
-const ability = await loadAbility('my-ability', 'broker');
-```
+---
 
-**Environment Variables Passed to Child Process:**
+## Registering Tools
 
-```bash
-KADI_PROTOCOL=broker                       # Identifies the protocol
-KADI_BROKER_URL=ws://localhost:8080        # Broker connection URL
-KADI_ABILITY_NAME=ability.echo.1_0_0       # Ability identifier
-KADI_AGENT_SCOPE=uuid-here                 # Agent's scope/namespace
-# Plus all parent process.env variables
-```
+Tools are functions you expose for other agents to call.
 
-**Network/Namespace Visibility:**
+```typescript
+import { KadiClient, z } from '@kadi.build/core';
 
-The `KADI_AGENT_SCOPE` environment variable represents the agent's namespace. For the ability to be visible to its parent agent via the broker, it must register with the same network:
+const client = new KadiClient({ name: 'weather-service' });
 
-```javascript
-// In your ability code:
-const echoAbility = new KadiClient({
-  name: 'echo-js',
-  version: '0.0.1',
-  description: 'Echo ability with broker support',
-  network: process.env.KADI_AGENT_SCOPE // Use agent's network for visibility
+// Define input schema with Zod
+const weatherInput = z.object({
+  city: z.string().describe('City name'),
+  units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
 });
 
-// Without this, the ability would only be visible in the 'global' network
-// and the parent agent wouldn't be able to communicate with it
+// Register tool
+client.registerTool({
+  name: 'getWeather',
+  description: 'Get current weather for a city',
+  input: weatherInput,
+}, async ({ city, units }) => {
+  const temp = await fetchTemperature(city);
+  return { city, temperature: temp, units };
+});
 ```
 
-### Protocol Selection Strategy
+**Why Zod?** Type-safe schemas, 70% less code than JSON Schema, automatic TypeScript inference.
 
-When no protocol is specified, `loadAbility` defaults to the 'native' protocol. You must explicitly specify the protocol if you want to use 'stdio' or 'broker'.
+### Targeting Specific Brokers
 
-```mermaid
-graph TD
-    A[Load Ability] --> B{Protocol Specified?}
-    B -->|Yes| C[Use Specified Protocol]
-    B -->|No| D[Default to 'native']
+```typescript
+// Register tool only on specific brokers
+client.registerTool(definition, handler, { brokers: ['internal'] });
 ```
 
-## 🛠️ Creating Abilities with KadiClient
+---
 
-### Basic Ability Structure
+## Connecting to Brokers
 
-```javascript
-import { KadiClient } from '@kadi.build/core';
+Brokers let agents discover and call each other without knowing URLs.
 
-const ability = new KadiClient({
-  name: 'echo-ability',
-  role: 'ability', // 'agent', 'ability',
-  protocol: 'stdio', // 'native', 'stdio', or 'broker'
+```typescript
+const client = new KadiClient({
+  name: 'my-agent',
   brokers: {
-    local: 'ws://localhost:8080',
-    prod: 'ws://api.example.com:8080'
+    default: 'ws://localhost:8080/kadi',
+    production: 'wss://broker.example.com/kadi',
   },
-  defaultBroker: 'local'
-});
-
-// Method 1: Simple tool registration
-ability.registerTool('echo', async ({ message }) => ({
-  echo: message,
-  timestamp: new Date().toISOString()
-}));
-
-// Method 2: Tool with inline schema
-ability.registerTool(
-  'format',
-  async ({ text, style }) => ({
-    formatted: style === 'upper' ? text.toUpperCase() : text.toLowerCase()
-  }),
-  {
-    description: 'Format text with specified style',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        text: { type: 'string', description: 'Text to format' },
-        style: {
-          type: 'string',
-          enum: ['upper', 'lower'],
-          description: 'Formatting style'
-        }
-      },
-      required: ['text', 'style']
-    },
-    outputSchema: {
-      type: 'object',
-      properties: {
-        formatted: { type: 'string', description: 'Formatted text' }
-      }
-    }
-  }
-);
-
-// Start serving
-ability.serve().catch(console.error);
-```
-
-### Event Publishing and Subscription
-
-**Full Support**: Events work across all protocols - native, stdio, and broker.
-
-KadiClient provides a unified event system that works consistently across all transport protocols:
-
-```javascript
-// In your ability (ability.js)
-const ability = new KadiClient({
-  name: 'my-ability',
-  role: 'ability',
-  protocol: 'broker' // Works with all protocols
-});
-
-// Publish events from tool handlers
-ability.registerTool('echo', async ({ message }) => {
-  // Publish events during processing
-  await ability.publishEvent('echo.processing', { status: 'started' });
-
-  // Do work...
-  const result = { echo: message, timestamp: new Date().toISOString() };
-
-  await ability.publishEvent('echo.completed', { result });
-  return result;
+  defaultBroker: 'default',
+  networks: ['global'],  // Which networks to join
 });
 
-// In your agent (agent.js)
-const agent = new KadiClient({
-  name: 'my-client',
-  role: 'agent',
-  protocol: 'broker'
-});
+// Connect (uses Ed25519 authentication)
+await client.connect();
 
-// Subscribe to events using patterns
-agent.subscribeToEvent('echo.*', (data) => {
-  console.log('Echo event received:', data);
-});
+// Invoke a tool - broker routes to any available provider
+const result = await client.invokeRemote('add', { a: 5, b: 3 });
 
-// For loaded abilities with native/stdio protocols
-const ability = await loadAbility('my-ability', 'stdio');
-ability.events.on('echo.completed', (data) => {
-  console.log('Completed:', data);
-});
+// Disconnect when done
+await client.disconnect();
 ```
 
-**Event Patterns**:
-
-- Use wildcards: `math.*` matches `math.operation`, `math.milestone`
-- Protocol-specific delivery:
-  - **Native**: Direct EventEmitter (synchronous)
-  - **Stdio**: JSON-RPC notifications over stdout
-  - **Broker**: RabbitMQ pub/sub via WebSocket
-
-### Ability Configuration (agent.json)
+### Reconnection
 
-Every ability should have an `agent.json` file that defines its capabilities:
+Auto-reconnects with exponential backoff (1s → 2s → 4s → ... → 30s max) with jitter:
 
-```json
-{
-  "name": "echo-ability",
-  "kind": "ability",
-  "version": "1.0.0",
-  "license": "MIT",
-  "description": "Echo ability with multiple transport support",
-  "scripts": {
-    "setup": "npm install",
-    "start": "node ability.js"
-  },
-  "exports": [
-    {
-      "name": "echo",
-      "description": "Echo the input message",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "message": { "type": "string" }
-        },
-        "required": ["message"]
-      },
-      "outputSchema": {
-        "type": "object",
-        "properties": {
-          "echo": { "type": "string" },
-          "timestamp": { "type": "string" }
-        }
-      }
-    }
-  ],
-  "brokers": {
-    "local": "ws://localhost:8080",
-    "remote": "ws://api.example.com:8080"
-  },
-  "defaultBroker": "local"
-}
-```
-
-### Schema Definition Options
-
-The ability system provides two ways to define method schemas:
-
-1. **Export Schemas** (defined in `agent.json` exports section)
-2. **Inline Schemas** (passed directly to `registerTool()`)
-
-```javascript
-// Option 1: Define in agent.json exports section
-// The schema is picked up automatically if the method name matches
-// agent.json:
-{
-  "exports": [
-    {
-      "name": "process",
-      "description": "Process data",
-      "inputSchema": { /* ... */ },
-      "outputSchema": { /* ... */ }
-    }
-  ]
-}
-
-// Option 2: Define inline when registering the method
-ability.registerTool('process', handler, {
-  description: 'Process data',
-  inputSchema: { /* ... */ },
-  outputSchema: { /* ... */ }
+```typescript
+const client = new KadiClient({
+  name: 'resilient-agent',
+  brokers: { default: 'ws://localhost:8080/kadi' },
+  autoReconnect: true,        // Default: true
+  maxReconnectDelay: 30000,   // Cap at 30 seconds
 });
-
-// Note: If both are defined, inline schemas take precedence over exports
 ```
 
-**Important**: Specifying MCP schemas for ability handlers is particularly important for `broker` communication. If you only need `native` and `stdio` protocols, schemas can be omitted.
-
-## 🤖 Working with KadiClient
-
-KadiClient is the unified API for all KADI operations. It replaces the previous separate KadiAbility and KadiAgent classes with a single, powerful interface that can operate in multiple roles.
-
-### Direct Approach (using loadAbility)
-
-```javascript
-import { loadAbility } from '@kadi.build/core';
-
-// Load and call abilities directly
-const echoAbility = await loadAbility('echo-js', 'stdio');
-const result = await echoAbility.echo({ message: 'Hello world' });
+---
 
-// Load broker tools directly
-const remoteAbility = await loadAbility('remote-ability', 'broker', {
-  brokerUrl: 'ws://localhost:8080',
-  networks: ['global']
-});
-const brokerResult = await remoteAbility.process({ data: 'test' });
-```
+## Loading Abilities
 
-### Using KadiClient with Named Brokers
+Three ways to connect to other agents:
 
-```javascript
-import { KadiClient } from '@kadi.build/core';
+| Method | Use When | How It Works |
+|--------|----------|--------------|
+| `loadNative(name)` | Ability is a local TypeScript/JavaScript module | Runs in your process |
+| `loadStdio(name)` | Ability runs as a separate process (any language) | JSON-RPC over stdin/stdout |
+| `loadBroker(name)` | Ability is a remote service | WebSocket via broker |
 
-// Create a unified client with named brokers
-const client = new KadiClient({
-  name: 'my-ability',
-  role: 'ability', // Provider role
-  protocol: 'broker',
-  brokers: {
-    dev: 'ws://localhost:8080',
-    staging: 'ws://staging.example.com:8080',
-    prod: 'ws://prod.example.com:8080'
-  },
-  defaultBroker: 'dev',
-  networks: ['global']
-});
+### loadNative — In-Process
 
-// Register tools for others to call
-client.registerTool(
-  'greet',
-  async ({ name }) => {
-    return { greeting: `Hello, ${name}!` };
-  },
-  {
-    description: 'Greet someone by name',
-    inputSchema: {
-      type: 'object',
-      properties: { name: { type: 'string' } },
-      required: ['name']
-    }
-  }
-);
+```typescript
+// Resolves path from agent-lock.json
+const calc = await client.loadNative('calculator');
 
-// Connect to all configured brokers
-await client.connectToBrokers();
+// Or specify path directly
+const calc = await client.loadNative('calculator', { path: './abilities/calc' });
 
-// Call remote tools
-const result = await client.callTool('translator', 'translate', {
-  text: 'Hello',
-  to: 'es'
-});
+// Use it
+const result = await calc.invoke('add', { a: 5, b: 3 });
+console.log(result); // { result: 8 }
 
-// Load abilities for compatibility
-const ability = await client.loadAbility('echo-js');
+// Cleanup (no-op for native, but good practice)
+await calc.disconnect();
 ```
 
-Use `loadAbility()` for simple consumption, or KadiClient for full-featured ability development with tool registration, event publishing, and remote tool invocation.
-
-## 🔄 Architecture Deep Dive
-
-### Transport Architecture and Loading Sequence
-
-The loading process uses modular transports based on the selected protocol:
-
-```mermaid
-sequenceDiagram
-    participant Client
-    participant loadAbility
-    participant Transport
-    participant FileSystem
-    participant ChildProcess
-    participant Ability
-    participant Broker
-
-    Client->>loadAbility: loadAbility('echo-js', protocol?)
-    loadAbility->>FileSystem: Read agent.json manifests
-    FileSystem-->>loadAbility: Return config & version
-
-    alt protocol === 'native'
-        loadAbility->>Transport: new NativeTransport(config)
-        Transport->>FileSystem: import(entry point)
-        FileSystem-->>Transport: Module with KadiClient instance
-        Transport->>Ability: Extract tool handlers via getToolNames()
-        Ability-->>Transport: Return registered tools
-        Transport->>Transport: Store handlers in Map
-    else protocol === 'stdio'
-        loadAbility->>Transport: new StdioTransport(config)
-        Transport->>ChildProcess: spawn(startCmd, env: {KADI_PROTOCOL})
-        ChildProcess->>Ability: KadiClient detects stdio mode
-        Ability->>Ability: Setup FrameReader/Writer
-        Transport->>Ability: Send discovery request
-        Ability-->>Transport: Return tool list
-        Transport->>Transport: Setup JSON-RPC proxy
-    else protocol === 'broker'
-        loadAbility->>Transport: new BrokerTransport(config)
-        Transport->>Transport: Reuse existing KadiClient
-        Transport->>Broker: WebSocket connect
-        Transport->>Broker: kadi.session.hello
-        Broker-->>Transport: { nonce, heartbeatIntervalSec }
-        Transport->>Broker: kadi.session.authenticate
-        Broker-->>Transport: { sessionId }
-        Transport->>Broker: kadi.ability.list
-        Broker-->>Transport: Available tools
-        Transport->>Transport: Start heartbeat timer
-    end
-
-    loadAbility->>loadAbility: Create proxy with tool methods
-    loadAbility-->>Client: Return ability proxy
-
-    Note over Client,Ability: Tool invocation
-    Client->>Transport: ability.echo({ message })
-
-    alt native
-        Transport->>Ability: Direct handler call
-    else stdio
-        Transport->>Ability: JSON-RPC over frames
-    else broker
-        Transport->>Broker: kadi.ability.invoke
-        Broker->>Ability: Route to target
-        Ability->>Broker: kadi.ability.result
-        Broker-->>Transport: Forward result
-    end
-
-    Transport-->>Client: Return result
-```
+### loadStdio — Child Process
 
-### KadiClient Architecture: Tool Registration & Serving
-
-How KadiClient registers tools and starts serving:
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant KC as KadiClient
-    participant Transport
-    participant Network as Network Layer
-    participant RemoteClient
-
-    Note over Dev,KC: Tool Registration Phase
-    Dev->>KC: new KadiClient({ name, role, protocol })
-    KC->>KC: Initialize based on role & protocol
-
-    Dev->>KC: registerTool('echo', handler, schema?)
-    KC->>KC: Store in toolHandlers Map<name, {handler, schema}>
-
-    Dev->>KC: registerTool('process', handler, schema)
-    KC->>KC: Add to toolHandlers Map
-
-    Note over KC,Network: Connection & Serving Phase
-    Dev->>KC: serve() or connectToBrokers()
-
-    alt protocol === 'native'
-        KC->>KC: Tools available via direct reference
-        KC->>KC: Emit 'start' event
-    else protocol === 'stdio'
-        KC->>Transport: Setup StdioTransport
-        Transport->>Transport: new FrameReader(stdin)
-        Transport->>Transport: new FrameWriter(stdout)
-        Transport->>KC: on('message', handleStdioMessage)
-        KC->>KC: Process JSON-RPC requests
-    else protocol === 'broker'
-        KC->>Network: WebSocket.connect(brokerUrl)
-        KC->>Network: kadi.session.hello({ role })
-        Network-->>KC: { nonce, heartbeatIntervalSec: 30 }
-        KC->>KC: Sign nonce with Ed25519
-        KC->>Network: kadi.session.authenticate({ signature })
-        Network-->>KC: { sessionId }
-        KC->>Network: kadi.agent.register({ tools, networks })
-        KC->>KC: Start heartbeat timer (30s interval)
-    end
-
-    Note over RemoteClient,KC: Tool Invocation Flow
-    RemoteClient->>Network: Request tool invocation
-
-    alt native
-        RemoteClient->>KC: Direct method call
-        KC->>KC: toolHandlers.get(name).handler(params)
-    else stdio
-        Network->>Transport: JSON-RPC frame
-        Transport->>KC: Parsed request
-        KC->>KC: toolHandlers.get(name).handler(params)
-        KC->>Transport: JSON-RPC response
-        Transport->>Network: Framed response
-    else broker
-        Network->>KC: kadi.ability.invoke message
-        KC->>KC: toolHandlers.get(toolName).handler(params)
-        KC->>Network: kadi.ability.result message
-    end
-
-    Network-->>RemoteClient: Tool result
-```
+By default, launches the ability using `scripts.start` from the ability's `agent.json`:
 
-### Event System Architecture
-
-KadiClient provides a unified event API that works across all transport protocols:
-
-```mermaid
-sequenceDiagram
-    participant Publisher as Ability (Publisher)
-    participant Transport as Transport Layer
-    participant EventBus as Event Bus
-    participant Subscriber as Client (Subscriber)
-
-    Note over Subscriber: Setup subscription
-    Subscriber->>Subscriber: subscribeToEvent('math.*', callback)
-
-    alt protocol === 'broker'
-        Subscriber->>EventBus: kadi.event.subscribe({channels: ['math.*']})
-        EventBus-->>Subscriber: {subscribed: ['math.*'], queueName}
-    else protocol === 'stdio'
-        Subscriber->>Transport: Setup event listener
-        Transport->>Subscriber: on('transport:event', dispatcher)
-    else protocol === 'native'
-        Subscriber->>Publisher: Direct EventEmitter reference
-        Publisher->>Subscriber: on('ability:event', dispatcher)
-    end
-
-    Note over Publisher: Publish event
-    Publisher->>Publisher: publishEvent('math.operation', data)
-
-    alt protocol === 'native'
-        Publisher->>Publisher: emit('ability:event', {eventName, data})
-        Publisher-->>Subscriber: Direct EventEmitter delivery
-        Subscriber->>Subscriber: Pattern match & invoke callback
-    else protocol === 'stdio'
-        Publisher->>Transport: writer.write(__kadi_event notification)
-        Transport->>Transport: Frame with LSP headers
-        Transport-->>Subscriber: Framed event over stdout
-        Subscriber->>Transport: FrameReader parses
-        Transport->>Subscriber: emit('transport:event', {name, data})
-        Subscriber->>Subscriber: Pattern match & invoke callback
-    else protocol === 'broker'
-        Publisher->>EventBus: kadi.event.publish({channel, data})
-        EventBus->>EventBus: Route via RabbitMQ
-        EventBus-->>Subscriber: kadi.event.delivery
-        Subscriber->>Subscriber: Pattern match & invoke callback
-    end
-
-    Note over Subscriber: Cleanup
-    Subscriber->>Subscriber: unsubscribe()
-    alt protocol === 'broker'
-        Subscriber->>EventBus: kadi.event.unsubscribe
-    else
-        Subscriber->>Subscriber: Remove local listener
-    end
-```
+```typescript
+// Runs scripts.start from ability's agent.json
+const processor = await client.loadStdio('image-processor');
 
-### Broker Protocol Communication Flow
-
-Detailed view of broker-based communication with heartbeat:
-
-```mermaid
-sequenceDiagram
-    participant Client as KadiClient
-    participant Broker as KADI Broker
-    participant Target as Target Ability
-
-    Note over Client,Broker: Connection & Authentication
-    Client->>Broker: WebSocket connect
-    Client->>Broker: kadi.session.hello({ role })
-    Broker-->>Client: { nonce, heartbeatIntervalSec: 30 }
-    Client->>Client: Generate Ed25519 keypair
-    Client->>Client: Sign nonce
-    Client->>Broker: kadi.session.authenticate({ signature })
-    Broker-->>Client: { sessionId }
-
-    Note over Client,Broker: Heartbeat Management
-    Client->>Client: Start heartbeat timer (30s)
-    loop Every 30 seconds
-        Client->>Broker: kadi.session.ping
-        Note over Broker: Reset connection timeout (90s)
-    end
-
-    Note over Client,Broker: Tool Registration
-    Client->>Broker: kadi.agent.register({ tools, networks })
-    Broker->>Broker: Store in registry
-    Broker-->>Client: { registered: true }
-
-    Note over Client,Target: Remote Tool Invocation
-    Client->>Client: callTool('ability-b', 'process', params)
-    Client->>Broker: kadi.ability.invoke({
-        targetAgent: 'ability-b',
-        toolName: 'process',
-        toolInput: params
-    })
-    Broker->>Broker: Lookup ability-b
-    Broker->>Target: kadi.ability.invoke
-    Target->>Target: Execute tool handler
-    Target->>Broker: JSON-RPC response
-    Broker-->>Client: Forward response
-    Client->>Client: Resolve promise
-
-    Note over Client,Broker: Event Publishing
-    Client->>Broker: kadi.event.publish({
-        channel: 'system.status',
-        data: { status: 'healthy' }
-    })
-    Broker->>Broker: Publish to RabbitMQ exchange
-
-    Note over Client,Broker: Graceful Shutdown
-    Client->>Client: Stop heartbeat timer
-    Client->>Broker: kadi.session.goodbye
-    Client->>Client: Close WebSocket
-```
+// Use it
+const result = await processor.invoke('resize', { width: 800 });
+console.log(result);
 
-### Stdio Protocol: LSP-Style Frame Processing
-
-How KadiClient handles stdio communication with LSP-style framing:
-
-```mermaid
-sequenceDiagram
-    participant Parent as Parent Process
-    participant SR as StdioFrameReader
-    participant SW as StdioFrameWriter
-    participant Server as StdioRpcServer
-    participant Ability as KadiClient
-
-    Note over Parent,SR: Incoming Request
-    Parent->>SR: Write to stdin: "Content-Length: 52\r\n\r\n{...}"
-    SR->>SR: Buffer incoming data
-    SR->>SR: Look for Content-Length header
-    SR->>SR: Parse header, extract body length
-    SR->>SR: Wait for complete body
-    SR->>SR: Parse JSON from body
-    SR->>Server: onMessage({ success: true, data: request })
-
-    Server->>Server: Validate JSON-RPC format
-    Server->>Ability: getMethodHandler(request.method)
-    Ability-->>Server: Return handler
-    Server->>Server: Execute handler(params) with timeout
-
-    Note over Server,Parent: Response
-    Server->>SW: write(response)
-    SW->>SW: JSON.stringify(response)
-    SW->>SW: Calculate byte length
-    SW->>SW: Create header: "Content-Length: N\r\n\r\n"
-    SW->>Parent: Write header + body to stdout
-
-    Note over SR: Error Recovery
-    alt Frame Corruption
-        SR->>SR: Detect invalid frame
-        SR->>SR: Search for next Content-Length marker
-        SR->>SR: Skip corrupted bytes
-        SR->>Server: onMessage({ success: false, error: 'FRAME_CORRUPTION' })
-        Server->>Server: Log error, continue processing
-    end
+// Cleanup (terminates child process)
+await processor.disconnect();
 ```
 
-## 📥 Loading Abilities
-
-### Basic Loading
-
-```javascript
-import { loadAbility } from '@kadi.build/core';
+You can specify a different script to launch:
 
-// Auto-detect protocol from agent.json
-const ability = await loadAbility('my-ability');
-
-// Explicitly specify protocol
-const stdioAbility = await loadAbility('my-ability', 'stdio');
-const brokerAbility = await loadAbility('my-ability', 'broker');
-const nativeAbility = await loadAbility('my-ability', 'native');
+```typescript
+// Run scripts.dev instead of scripts.start
+const processor = await client.loadStdio('image-processor', { script: 'dev' });
 ```
 
-### Working with Loaded Abilities
-
-```javascript
-// Call methods directly - no need to discover them first
-const result = await ability.echo({ message: 'hello' });
-
-// Call methods
-const result = await ability.someMethod({ param: 'value' });
-
-// Direct RPC call (bypasses method validation)
-const response = await ability.__call('someMethod', { param: 'value' });
+Or bypass `agent.json` entirely with an explicit command:
 
-// Subscribe to events
-ability.events.on('custom:event', (data) => {
-  console.log('Event received:', data);
+```typescript
+// Explicit command (ignores agent.json)
+const processor = await client.loadStdio('processor', {
+  command: 'python3',
+  args: ['main.py'],
 });
-
-// Note: Events work for all protocols (native, stdio, and broker)
-// Subscribe before calling methods that emit events
 ```
 
-### KadiClient transport vs loadAbility transport
-
-KADI uses “transport” in two places and they serve different purposes:
-
-- KadiClient transport — how this client exposes its own tools after `registerTool(...)` and `serve()`.
-  - `transport: 'native'` — in‑process only. There is no network or stdio listener. Code that loads you natively (via `loadAbility('you','native')`) can call your tools directly. `serve()` simply keeps the process alive if you want a long‑running ability.
-  - `transport: 'stdio'` — the client runs a stdio server (JSON‑RPC over stdin/stdout) and answers requests with your registered handlers. `serve()` wires up the stdio loop.
-  - `transport: 'broker'` — the client connects to the broker, registers your tools, and receives remote invocations over WebSocket. `serve()` (or `connectToBrokers()`) handles connection and registration.
-
-- loadAbility transport — how this client connects to a specific ability it wants to use.
-  - `'native'` loads a module in‑process
-  - `'stdio'` talks to a spawned child process (uses the ability’s `agent.json` `scripts.start`)
-  - `'broker'` talks to a remote ability over the broker
-
-These two choices are independent: setting the client’s `transport` does not change how you load another ability, and the transport you choose in `loadAbility(...)` does not change how your client serves its own tools.
-
-Examples
-
-Provide tools over broker
+### loadBroker — Remote via Broker
 
-```ts
-import { KadiClient } from '@kadi.build/core';
+```typescript
+// Must be connected to broker first
+await client.connect();
 
-const svc = new KadiClient({
-  name: 'math',
-  role: 'ability',
-  transport: 'broker',
-  brokers: { local: 'ws://localhost:8080' },
-  defaultBroker: 'local'
+// Find and connect to a remote ability
+const gpu = await client.loadBroker('gpu-service', {
+  networks: ['gpu-cluster'],
 });
 
-svc.registerTool('add', async ({ a, b }) => ({ result: a + b }));
-await svc.serve(); // registers with the broker so others can call math.add
+const result = await gpu.invoke('inference', { model: 'llama3' });
+await gpu.disconnect();
 ```
 
-Consume a stdio ability
-
-```ts
-const agent = new KadiClient({
-  name: 'client',
-  role: 'agent',
-  transport: 'native'
-});
-const math = await agent.loadAbility('simple-math', 'stdio');
-const res = await math.add({ a: 2, b: 3 });
-```
-
-Consume a broker ability
-
-```ts
-const agent = new KadiClient({
-  name: 'client',
-  role: 'agent',
-  transport: 'broker',
-  brokers: { local: 'ws://localhost:8080' },
-  defaultBroker: 'local'
-});
+---
 
-const echo = await agent.loadAbility('echo-js', 'broker', {
-  networks: ['global']
-});
-const r = await echo.say_message({ message: 'hi' });
-```
+## Events from Abilities
 
-### Loading Context
+Abilities can emit real-time events. Subscribe with `on()`, unsubscribe with `off()`.
 
-The loader automatically resolves ability versions from:
+```typescript
+const watcher = await client.loadStdio('file-watcher');
 
-1. **Project context**: Reads from project's `agent.json`
-2. **Nested context**: When loading from within another ability
-3. **Explicit version**: Can be specified in ability name
+// Define handlers (need references to unsubscribe later)
+const onFileChanged = (data) => {
+  console.log('File changed:', data.path, data.action);
+};
 
-## ⚙️ Configuration
+const onError = (data) => {
+  console.error('Watch error:', data.message);
+};
 
-### Environment Variables
+// Subscribe to events
+watcher.on('file.changed', onFileChanged);
+watcher.on('file.error', onError);
 
-```bash
-# Set default protocol
-export KADI_PROTOCOL=stdio
+// Later, unsubscribe
+watcher.off('file.changed', onFileChanged);
 
-# Configure broker
-export KADI_BROKER_URL=ws://localhost:8080
-export KADI_ABILITY_NAME=my-ability
-export KADI_AGENT_SCOPE=project-123
+// Cleanup (terminates child process)
+await watcher.disconnect();
 ```
 
-### Environment Variables for Child Processes
-
-When abilities are spawned as child processes (stdio and broker protocols), the parent process passes down important environment variables:
+### Emitting Events (from inside an ability)
 
-```javascript
-// In your ability code, you can access these variables:
-const protocol = process.env.KADI_PROTOCOL; // 'stdio' or 'broker'
-const brokerUrl = process.env.KADI_BROKER_URL;
-const abilityName = process.env.KADI_ABILITY_NAME;
-const agentScope = process.env.KADI_AGENT_SCOPE;
+If you're building an ability that emits events:
 
-// Use them to configure your ability behavior
-const ability = new KadiClient({
-  name: 'my-ability',
-  network: process.env.KADI_AGENT_SCOPE || 'global'
-  // Ability automatically uses KADI_PROTOCOL to determine transport
-});
+```typescript
+// Inside your ability code
+client.emit('job.progress', { percent: 50, message: 'Halfway done' });
+client.emit('file.changed', { path: '/tmp/foo.txt', action: 'modified' });
 ```
 
-### Example Project Structure
-
-```
-my-project/
-├── agent.json              # Project configuration
-├── abilities/              # Installed abilities
-│   └── echo-ability/
-│       └── 1.0.0/
-│           ├── agent.json  # Ability configuration
-│           ├── ability.js  # Ability implementation
-│           └── package.json
-├── modules/                # Source modules
-│   └── echo-ability/       # Development version
-└── index.js               # Main entry point
-```
-
-## 🚀 Advanced Usage
+---
 
-### Event System
+## Broker Events (Pub/Sub)
 
-KadiClient provides a comprehensive event system that works across all protocols:
+When connected to a broker, agents can publish and subscribe to events across the network.
 
-#### 1. Lifecycle Events
+### Subscribing
 
-Monitor the ability lifecycle:
+```typescript
+await client.connect();
 
-```javascript
-const client = new KadiClient({ name: 'my-ability' });
-
-// Connection events
-client.on('connected', ({ broker }) => {
-  console.log(`Connected to broker: ${broker}`);
+// Subscribe to patterns (RabbitMQ topic exchange style)
+client.subscribe('user.*', (event) => {
+  console.log(`Channel: ${event.channel}`);   // 'user.login'
+  console.log(`Data:`, event.data);           // { userId: '123' }
+  console.log(`Network: ${event.networkId}`); // 'global'
+  console.log(`Source: ${event.source}`);     // Publisher's session ID
 });
+```
 
-client.on('disconnected', () => {
-  console.log('Disconnected from broker');
-});
+**Pattern matching:**
+- `user.*` → matches `user.login`, `user.logout` (exactly one word after dot)
+- `user.#` → matches `user`, `user.login`, `user.profile.update` (zero or more words)
+- `order.new` → matches exactly `order.new`
 
-// Tool invocation events
-client.on('tool:invoked', ({ toolName, params }) => {
-  console.log(`Tool ${toolName} invoked with:`, params);
-});
+### Publishing
 
-client.on('tool:completed', ({ toolName, result }) => {
-  console.log(`Tool ${toolName} completed:`, result);
-});
+```typescript
+// Publish to default network
+await client.publish('user.login', { userId: '123', timestamp: Date.now() });
 
-client.on('error', (error) => {
-  console.error('Ability error:', error);
-});
+// Publish to specific network
+await client.publish('order.created', orderData, { network: 'internal' });
 ```
 
-#### 2. Custom Events (All Protocols)
+### Unsubscribing
 
-Publish and subscribe to custom events across all transport protocols:
+```typescript
+const handler = (event) => console.log(event);
+client.subscribe('user.*', handler);
 
-```javascript
-// Publishing events
-const publisher = new KadiClient({
-  name: 'event-publisher',
-  role: 'ability',
-  protocol: 'broker' // Works with all protocols
-});
-
-publisher.registerTool('process', async ({ data }) => {
-  // Publish events during processing
-  await publisher.publishEvent('process.started', {
-    timestamp: Date.now(),
-    data
-  });
+// Later, remove this specific handler
+client.unsubscribe('user.*', handler);
+```
 
-  // Do work...
-  const result = await processData(data);
+---
 
-  await publisher.publishEvent('process.completed', {
-    timestamp: Date.now(),
-    result
-  });
+## Serving as an Ability
 
-  return result;
-});
+To make your agent callable by others:
 
-// Subscribing to events
-const subscriber = new KadiClient({
-  name: 'event-subscriber',
-  role: 'agent',
-  protocol: 'broker'
-});
+### Stdio Mode (for loadStdio)
 
-// Subscribe with wildcards
-subscriber.subscribeToEvent('process.*', (data) => {
-  console.log('Process event:', data);
-});
+```typescript
+const client = new KadiClient({ name: 'my-ability' });
 
-// One-time subscription
-subscriber.onceEvent('process.completed', (data) => {
-  console.log('First completion:', data);
+client.registerTool({
+  name: 'process',
+  description: 'Process data',
+  input: z.object({ data: z.string() }),
+}, async ({ data }) => {
+  return { processed: data.toUpperCase() };
 });
 
-// Multiple pattern subscription
-subscriber.subscribeToEvents(['process.*', 'system.*'], (pattern, data) => {
-  console.log(`Event from ${pattern}:`, data);
-});
+// Serve over stdio - blocks until SIGTERM/SIGINT
+await client.serve('stdio');
 ```
 
-**Protocol-Specific Behavior:**
-
-- **Native**: Direct EventEmitter, synchronous delivery
-- **Stdio**: JSON-RPC notifications with LSP framing
-- **Broker**: RabbitMQ pub/sub via WebSocket, persistent queues available
-
-### Multi-Broker Configuration
+### Broker Mode (for loadBroker)
 
-KadiClient supports connecting to multiple brokers simultaneously for redundancy and load distribution:
-
-```javascript
+```typescript
 const client = new KadiClient({
-  name: 'multi-broker-ability',
-  role: 'ability',
-  protocol: 'broker',
-  brokers: {
-    primary: 'ws://broker1.example.com:8080',
-    secondary: 'ws://broker2.example.com:8080',
-    backup: 'ws://broker3.example.com:8080'
-  },
-  defaultBroker: 'primary', // Used for sending if no specific broker targeted
-  networks: ['production']
+  name: 'my-service',
+  brokers: { default: 'ws://localhost:8080/kadi' },
 });
 
-// Connect to all configured brokers
-await client.connectToBrokers();
+client.registerTool({ /* ... */ }, handler);
 
-// The client will now:
-// 1. Maintain connections to all three brokers
-// 2. Receive messages from any broker
-// 3. Send messages to the default broker unless specified
-// 4. Automatically handle broker failover
+// Connect to broker and wait for requests
+await client.serve('broker');
 ```
 
-### Cross-Language Ability Support
+---
 
-KADI now fully supports abilities written in any language through the stdio protocol:
+## Error Handling
 
-```javascript
-// Go ability with agent.json:
-{
-  "name": "hash-go",
-  "scripts": {
-    "setup": "go build -o bin/hash_ability",
-    "start": "./bin/hash_ability"  // Binary executable
-  }
-}
+All errors are `KadiError` with structured codes and context:
 
-// Python ability:
-{
-  "name": "ml-processor",
-  "scripts": {
-    "start": "python3 main.py"
-  }
-}
+```typescript
+import { KadiError } from '@kadi.build/core';
 
-// Rust ability:
-{
-  "name": "crypto-rust",
-  "scripts": {
-    "setup": "cargo build --release",
-    "start": "./target/release/crypto_ability"
+try {
+  await client.invokeRemote('unknown-tool', {});
+} catch (error) {
+  if (KadiError.isKadiError(error)) {
+    console.log(error.code);      // 'TOOL_NOT_FOUND'
+    console.log(error.message);   // Human-readable message
+    console.log(error.context);   // { toolName: '...', hint: '...' }
   }
 }
-
-// Load and use regardless of implementation language:
-const hashAbility = await loadAbility('hash-go', 'stdio');
-const result = await hashAbility.sha256({ data: 'hello' });
 ```
 
-## 🔧 Development Workflow
-
-### Testing Local Changes
+### Error Codes
 
-When developing new features or testing changes to `@kadi.build/core` before publishing to NPM:
+| Code | When It Happens |
+|------|-----------------|
+| `TOOL_NOT_FOUND` | `invoke()` or `invokeRemote()` with unknown tool name |
+| `BROKER_NOT_CONNECTED` | Any broker operation before calling `connect()` |
+| `ABILITY_NOT_FOUND` | `loadNative/loadStdio` when ability not in agent-lock.json |
+| `ABILITY_LOAD_FAILED` | Ability exists but failed to start or initialize |
+| `TOOL_INVOCATION_FAILED` | Tool threw an error during execution |
+| `BROKER_TIMEOUT` | Request to broker timed out |
+| `INVALID_CONFIG` | Configuration error (missing required fields, etc.) |
+| `LOCKFILE_NOT_FOUND` | `loadNative/loadStdio` when agent-lock.json doesn't exist |
 
-0. **Clone the repository**
-
-```bash
-git clone https://gitlab.com/humin-game-lab/kadi/kadi-core.git
-```
-
-1. **Pack the local version** (in the kadi-core directory):
-
-```bash
-cd /path/to/kadi-core
-npm pack
-# This creates: kadi.build-core-X.Y.Z.tgz
-```
-
-2. **Install in your project**:
-
-```bash
-cd /path/to/your-project
-npm install /path/to/kadi-core/kadi.build-core-X.Y.Z.tgz
-```
-
-3. **For ability development**, update the ability's preflight script:
+---
 
-```json
-{
-  "scripts": {
-    "preflight": "npm uninstall @kadi.build/core && npm install /path/to/kadi.build-core-X.Y.Z.tgz"
-  }
+## API Reference
+
+### KadiClient
+
+```typescript
+new KadiClient(config: ClientConfig)
+```
+
+**Configuration:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `name` | `string` | required | Agent name |
+| `version` | `string` | `'1.0.0'` | Agent version |
+| `brokers` | `Record<string, string>` | `{}` | Broker name → URL map |
+| `defaultBroker` | `string` | first broker | Default broker to use |
+| `networks` | `string[]` | `['global']` | Networks to join |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `maxReconnectDelay` | `number` | `30000` | Max backoff delay (ms) |
+| `requestTimeout` | `number` | `30000` | Default request timeout (ms) |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `registerTool(def, handler, options?)` | Register a tool. See [Registering Tools](#registering-tools) |
+| `connect(broker?)` | Connect to broker |
+| `disconnect(broker?)` | Disconnect from broker |
+| `invokeRemote(tool, params, options?)` | Invoke tool via broker (broker picks provider) |
+| `loadNative(name, options?)` | Load ability in-process. See [Loading Abilities](#loading-abilities) |
+| `loadStdio(name, options?)` | Load ability as child process |
+| `loadBroker(name, options?)` | Load ability via broker |
+| `subscribe(pattern, handler, options?)` | Subscribe to broker events. See [Broker Events](#broker-events-pubsub) |
+| `unsubscribe(pattern, handler, options?)` | Unsubscribe from events |
+| `publish(channel, data, options?)` | Publish event to broker |
+| `emit(event, data)` | Emit event to consumer (when serving as ability) |
+| `serve(mode)` | Serve as ability (`'stdio'` or `'broker'`) |
+| `getConnectedBrokers()` | List connected broker names |
+
+### LoadedAbility
+
+Returned by `loadNative()`, `loadStdio()`, `loadBroker()`:
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `name` | Ability name |
+| `transport` | `'native'` \| `'stdio'` \| `'broker'` |
+| `invoke(tool, params)` | Invoke a tool |
+| `getTools()` | Get array of tool definitions |
+| `on(event, handler)` | Subscribe to events |
+| `off(event, handler)` | Unsubscribe from events |
+| `disconnect()` | Cleanup resources |
+
+### BrokerEvent
+
+Received when subscribed to broker events:
+
+```typescript
+interface BrokerEvent {
+  channel: string;      // 'user.login'
+  data: unknown;        // Event payload
+  networkId: string;    // Which network
+  source: string;       // Publisher's session ID
+  timestamp: number;    // Unix timestamp (ms)
 }
 ```
 
-## 📖 API Reference
-
-### Core Classes
-
-#### `KadiClient`
-
-The unified class for all KADI operations - serving tools, calling remote abilities, and managing events.
-
-```javascript
-import { KadiClient } from '@kadi.build/core';
-
-const client = new KadiClient({
-  name: 'my-ability',
-  role: 'ability', // 'agent' or 'ability'
-  protocol: 'broker', // 'native', 'stdio', or 'broker'
-  brokers: {
-    dev: 'ws://localhost:8080',
-    prod: 'ws://prod.example.com:8080'
-  },
-  defaultBroker: 'dev',
-  network: 'global', // Primary network
-  networks: ['global', 'custom-network'] // All networks
-});
-```
-
-**Configuration Options:**
-
-- `name` - Ability/agent name
-- `role` - Operating role: 'agent' (consumer) or 'ability' (provider)
-- `protocol` - Transport protocol to use
-- `brokers` - Named broker configurations (object mapping names to URLs)
-- `defaultBroker` - Default broker name for sending messages
-- `network` - Primary network segment for message routing
-- `networks` - All network namespaces for tool discovery
-- `heartbeatIntervalSec` - Custom heartbeat interval (default: from broker)
-
-**Tool Registration Methods:**
-
-- `registerTool(name, handler, schema?)` - Register a single tool
-- `getTools()` - Get list of registered tool names
-- `getToolNames()` - Get filtered list of tool names
-- `getToolHandler(name)` - Get a specific tool's handler
-- `getToolSchema(name)` - Get a specific tool's schema
-- `hasTool(name)` - Check if a tool is registered
-
-**Remote Tool Invocation:**
-
-- `callTool(targetAgent, toolName, params)` - Call a remote tool via broker
-- `discoverRemoteTools(targetAgent)` - List tools from a remote agent
-- `loadAbility(name, protocol?, options?)` - Load an ability (compatibility)
+---
 
-**Event System:**
+## Troubleshooting
 
-- `publishEvent(eventName, data)` - Publish an event
-- `subscribeToEvent(pattern, callback)` - Subscribe with wildcards
-- `subscribeToEvents(patterns[], callback)` - Multiple subscriptions
-- `unsubscribeFromEvent(pattern, callback)` - Remove subscription
-- `onceEvent(pattern, callback)` - One-time subscription
+### "Cannot find module" with loadNative/loadStdio
 
-**Connection Management:**
+The ability isn't in your `agent-lock.json`. Either:
+- Run `kadi install` to install abilities and generate the lock file
+- Use the `path` option: `loadNative('calc', { path: './path/to/ability' })`
+- Use explicit command: `loadStdio('calc', { command: 'node', args: ['calc.js'] })`
 
-- `serve()` - Start serving (stdio/native modes)
-- `connectToBrokers()` - Connect to all configured brokers
-- `disconnect()` - Clean disconnect
-- `isConnected` - Check connection status
+### Connection timeout to broker
 
-**Properties:**
+1. Check the broker is running
+2. Verify the URL uses `ws://` or `wss://`, not `http://`
+3. Check firewall/network allows WebSocket connections
 
-- `agentId` - Unique agent identifier
-- `name` - Ability name
-- `role` - Current operating role
-- `protocol` - Active protocol
-- `brokers` - Configured broker map
-- `defaultBroker` - Default broker name
-- `currentBroker` - Currently active broker for sending
+### Events not being received
 
-**Complete Usage Example:**
+1. Verify both publisher and subscriber are on the same network (check `networks` config)
+2. Check your pattern matches the channel (remember: `*` = one word, `#` = zero or more)
+3. Ensure you're connected before subscribing: `await client.connect()`
 
-```javascript
-import { KadiClient } from '@kadi.build/core';
+### Tool invocation times out
 
-// Create an ability that can serve tools
-const ability = new KadiClient({
-  name: 'math-ability',
-  role: 'ability',
-  protocol: 'broker',
-  brokers: {
-    local: 'ws://localhost:8080',
-    cloud: 'wss://api.example.com'
-  },
-  defaultBroker: 'local',
-  networks: ['global']
-});
-
-// Register tools with schemas
-ability.registerTool(
-  'add',
-  async ({ a, b }) => {
-    // Publish event before processing
-    await ability.publishEvent('math.operation', {
-      operation: 'add',
-      inputs: { a, b }
-    });
-
-    const result = a + b;
-
-    // Publish completion event
-    await ability.publishEvent('math.completed', {
-      operation: 'add',
-      result
-    });
-
-    return { result };
-  },
-  {
-    description: 'Add two numbers',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        a: { type: 'number', description: 'First number' },
-        b: { type: 'number', description: 'Second number' }
-      },
-      required: ['a', 'b']
-    },
-    outputSchema: {
-      type: 'object',
-      properties: {
-        result: { type: 'number', description: 'Sum of a and b' }
-      }
-    }
-  }
-);
-
-// Subscribe to events from other abilities
-ability.subscribeToEvent('system.*', (data) => {
-  console.log('System event:', data);
-});
+Increase the timeout:
+```typescript
+await client.invokeRemote('slow-tool', params, { timeout: 60000 });
+```
 
-// Connect to brokers
-await ability.connectToBrokers();
+---
 
-// Call remote tools
-const result = await ability.callTool('translator-ability', 'translate', {
-  text: 'Hello',
-  to: 'es'
-});
+## Advanced: Building CLI Tools
 
-// Graceful shutdown
-process.on('SIGTERM', async () => {
-  await ability.disconnect();
-  process.exit(0);
-});
-```
+These utilities are exported for building tooling on top of kadi-core.
 
-#### `loadAbility`
+### Zod to JSON Schema
 
-Load an ability by name and protocol.
+Convert Zod schemas to JSON Schema (useful for generating documentation or OpenAPI specs):
 
-```javascript
-import { loadAbility } from '@kadi.build/core';
+```typescript
+import { zodToJsonSchema, z } from '@kadi.build/core';
 
-const ability = await loadAbility('ability-name', 'protocol', {
-  brokerUrl: 'ws://localhost:8080', // For broker protocol
-  brokerName: 'dev', // Named broker to use
-  networks: ['global'], // Network segments
-  existingClient: client // Reuse existing KadiClient for broker
-});
+const schema = z.object({ name: z.string(), age: z.number() });
+const jsonSchema = zodToJsonSchema(schema);
+// { type: 'object', properties: { name: { type: 'string' }, ... } }
 ```
 
-**Returns:** A proxy object with:
-
-- Direct method calls (e.g., `ability.echo({ message: 'hello' })`)
-- `ability.events` - EventEmitter for subscribing to events (all protocols)
-- `ability.__call(method, params)` - Direct RPC call
-- `ability.__disconnect()` - Clean up resources
+### Lock File Resolution
 
-### Utility Functions
+Utilities for working with `agent-lock.json` (the file that tracks installed abilities):
 
-```javascript
+```typescript
 import {
-  createLogger,
-  getProjectJSON,
-  getAbilityJSON,
-  getAgentJSON,
-  getBrokerUrl,
-  runExecCommand
+  findProjectRoot,
+  readLockFile,
+  resolveAbilityPath,
+  getInstalledAbilityNames,
 } from '@kadi.build/core';
-```
-
-### Debug Mode
-
-Enable detailed logging:
-
-```bash
-DEBUG=kadi:* node index.js
-```
-
-Check ability logs:
-
-```bash
-tail -f abilities/my-ability/1.0.0/my-ability.log
-```
-
-## 💡 Additional Examples
-
-### Error Handling Pattern
-
-```javascript
-const client = new KadiClient({
-  name: 'robust-ability',
-  role: 'ability'
-});
-
-client.registerTool('riskyOperation', async (params) => {
-  try {
-    const result = await performOperation(params);
-    await client.publishEvent('operation.success', { result });
-    return { success: true, result };
-  } catch (error) {
-    await client.publishEvent('operation.error', {
-      error: error.message,
-      params
-    });
-    // Return error in structured format
-    return {
-      success: false,
-      error: error.message
-    };
-  }
-});
-```
-
-### Health Check Pattern
-
-```javascript
-// Register a standard health check tool
-client.registerTool('health', async () => {
-  const checks = {
-    memory: process.memoryUsage(),
-    uptime: process.uptime(),
-    brokers: client.isConnected ? 'connected' : 'disconnected',
-    timestamp: Date.now()
-  };
-
-  return {
-    status: 'healthy',
-    checks
-  };
-});
-```
-
-## 🐛 Troubleshooting
-
-### Common Issues and Solutions
-
-#### Broker Connection Failures
-
-**Problem**: "Failed to connect to any brokers"
-
-**Solutions**:
-
-- Verify broker URLs are correct
-- Check network connectivity
-- Ensure broker is running
-- Try connecting with lower security (ws:// before wss://)
-
-#### Events Not Arriving
-
-**Problem**: Subscribed to events but callbacks not triggered
-
-**Solutions**:
-
-- Subscribe BEFORE triggering events
-- Check pattern matching (use exact match first)
-- Verify publisher and subscriber are on same network
-- Enable debug logging to trace event flow
-
-#### Cross-Language Abilities Not Loading
-
-**Problem**: "Cannot find module 'ability.js'" when loading Go/Python abilities
-
-**Solutions**:
-
-- Ensure `scripts.start` field exists in agent.json
-- Verify the binary/script is executable
-- Check that setup script has been run
-- Use stdio protocol, not native
 
-#### Memory Leaks
+// Find the nearest directory containing agent-lock.json
+const root = findProjectRoot();
 
-**Problem**: Memory usage grows over time
+// Read and parse the lock file
+const lock = readLockFile(root);
 
-**Solutions**:
+// List installed ability names
+const abilities = getInstalledAbilityNames(lock);
+// ['calculator', 'image-processor', ...]
 
-- Always call unsubscribe functions
-- Use `onceEvent` for single-use subscriptions
-- Disconnect abilities when done
-- Clear event listeners on cleanup
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🔗 Related Projects
-
-- [@kadi.build/cli](https://gitlab.com/humin-game-lab/kadi/kadi) - Command-line interface
-- [@kadi.build/broker](https://gitlab.com/humin-game-lab/kadi/kadi-broker) - The KADI broker
-
-## 📚 Resources
-
-## ⚠️ Error Codes
-
-KADI core exposes a unified, typed error catalog to keep errors consistent across core and the broker.
-
-- CoreErrorCodes: CORE\_\* errors for library/transport concerns
-- BrokerErrorCodes: BROKER\_\* errors mirrored for broker interactions
-- ErrorCodes: merged view of both
-
-Usage:
-
-```ts
-import { KadiError, CoreErrorCodes } from '@kadi.build/core';
-
-throw new KadiError(
-  CoreErrorCodes.CORE_CONFIG_MISSING.code,
-  'scripts.start is required for stdio',
-  { transport: 'stdio', abilityName: 'echo' }
-);
+// Get the filesystem path to an ability
+const calcPath = resolveAbilityPath('calculator', root);
+// '/path/to/project/abilities/calculator@1.0.0'
 ```
 
-Guidelines:
+---
 
-- Do not use raw string codes like 'CONFIG_MISSING'; always use the exported constants.
-- Prefer KadiError helper factories where available (e.g., KadiError.abilityNotFound()).
-- KadiError automatically tags domain from the code prefix (core/broker) and preserves the original stack.
-- Broker-side codes are fully prefixed: BROKER*SESSION*_, BROKER*AUTH*_, BROKER*AGENT*_, BROKER*NETWORK*_, etc.
+## Related
 
-- [Event System Deep Dive](docs/event-system.md) - Complete guide to the event architecture
-- [API Documentation](https://docs.kadi.build) - Full API reference
-- [Examples Repository](https://github.com/kadi-examples) - More examples and patterns
+- [kadi-core-py](https://gitlab.com/humin-game-lab/kadi/kadi-core-py) — Python SDK (mirrors this API)
+- [kadi-broker](https://gitlab.com/humin-game-lab/kadi/kadi-broker) — The broker server
 
 ---
 
-Built with ❤️ by the KADI team
+## License
+
+MIT