@kadi.build/core 0.0.1-alpha.4 → 0.0.1-alpha.6

package/README.md

@@ -7,7 +7,7 @@
 
 ## 🎯 Overview
 
-`@kadi.build/core` is the foundational library for creating KADI abilities - modular, protocol-agnostic services that can communicate via multiple transport layers. Whether you're building local tools, distributed microservices, or high-performance native modules, this toolkit provides a unified, developer-friendly API that abstracts away transport complexity.
+`@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
 
@@ -49,28 +49,27 @@ The library provides a unified way to work with KADI through the **KadiClient**
 
 - **As an Ability**: Serving tools/methods that others can call
 - **As an Agent**: Calling remote tools via broker protocol
-- **As a Service**: Combining both roles - serving and consuming tools
 
-### Creating Your First Service
+### Creating Your First Ability
 
 ```javascript
 #!/usr/bin/env node
 import { KadiClient } from '@kadi.build/core';
 
-// Create a service instance
-const mathService = new KadiClient({
-  name: 'math-service',
-  role: 'ability', // 'agent', 'ability', or 'service'
+// Create a ability instance
+const mathAbility = new KadiClient({
+  name: 'math-ability',
+  role: 'ability', // 'agent', 'ability'
   protocol: 'stdio' // 'native', 'stdio', or 'broker'
 });
 
 // Register a tool
-mathService.registerTool('add', async ({ a, b }) => {
+mathAbility.registerTool('add', async ({ a, b }) => {
   return { result: a + b };
 });
 
 // Start serving requests
-mathService.serve().catch(console.error);
+mathAbility.serve().catch(console.error);
 ```
 
 ### Loading and Using Abilities
@@ -100,7 +99,11 @@ const agent = new KadiClient({
   name: 'my-agent',
   role: 'agent',
   protocol: 'broker',
-  brokerUrls: ['ws://localhost:8080'],
+  brokers: {
+    'prod': 'ws://localhost:8080',
+    'dev': 'ws://localhost:8081'
+  },
+  defaultBroker: 'prod',
   networks: ['global']
 });
 
@@ -122,7 +125,7 @@ agent.registerTool(
   }
 );
 
-// Connect to broker and start serving
+// Connect to brokers and start serving
 await agent.connectToBrokers();
 
 // Call tools from OTHER agents connected to the same broker
@@ -154,7 +157,7 @@ const ability = await loadAbility('my-ability', 'native');
 - **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 services, development/testing
+- **Best For**: Python scripts, Go binaries, Node.js abilities, development/testing
 
 ```javascript
 // Force stdio protocol
@@ -170,10 +173,10 @@ KADI_PROTOCOL=stdio  # Identifies the protocol being used
 
 ### 3. Broker Protocol (Distributed)
 
-- **Use Case**: Distributed services, containerized deployments
+- **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**: Microservices, cloud deployments, load-balanced services
+- **Best For**: Distributed abilities, cloud deployments, load-balanced systems
 
 ```javascript
 // Use broker for distributed execution
@@ -183,77 +186,67 @@ const ability = await loadAbility('my-ability', 'broker');
 **Environment Variables Passed to Child Process:**
 
 ```bash
-KADI_PROTOCOL=broker                        # Identifies the protocol
+KADI_PROTOCOL=broker                       # Identifies the protocol
 KADI_BROKER_URL=ws://localhost:8080        # Broker connection URL
-KADI_SERVICE_NAME=ability.echo.1_0_0       # Service identifier
+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
 ```
 
-**Scope/Namespace Visibility:**
+**Network/Namespace Visibility:**
 
-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 scope:
+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:
 
 ```javascript
 // In your ability code:
-const echoAbility = new KadiAbility({
+const echoAbility = new KadiClient({
   name: 'echo-js',
   version: '0.0.1',
   description: 'Echo ability with broker support',
-  scope: process.env.KADI_AGENT_SCOPE // Use agent's scope for visibility
+  network: process.env.KADI_AGENT_SCOPE // Use agent's network for visibility
 });
 
-// Without this, the ability would only be visible in the 'global' scope
+// Without this, the ability would only be visible in the 'global' network
 // and the parent agent wouldn't be able to communicate with it
 ```
 
 ### Protocol Selection Strategy
 
-When no protocol is specified, `loadAbility` uses the **first interface** defined in the ability's `agent.json`. The KADI team recommends ordering interfaces from fastest to slowest (native → stdio → broker) for optimal default performance.
+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'.
 
 ```mermaid
 graph TD
     A[Load Ability] --> B{Protocol Specified?}
     B -->|Yes| C[Use Specified Protocol]
-    B -->|No| D{Check agent.json interfaces}
-    D --> E[Use First Interface Listed]
-    E --> F[native/stdio/broker]
+    B -->|No| D[Default to 'native']
 ```
 
-**Recommended Interface Order in agent.json:**
+## 🛠️ Creating Abilities with KadiClient
 
-```json
-{
-  "interfaces": {
-    "native": { "entry": "service.js" }, // 1st choice: Fastest
-    "stdio": { "discover": true }, // 2nd choice: Balanced
-    "broker": { "discover": true } // 3rd choice: Distributed
-  }
-}
-```
-
-## 🛠️ Creating Services with KadiClient
-
-### Basic Service Structure
+### Basic Ability Structure
 
 ```javascript
 import { KadiClient } from '@kadi.build/core';
 
-const service = new KadiClient({
-  name: 'echo-service',
-  role: 'ability',  // 'agent', 'ability', or 'service'
+const ability = new KadiClient({
+  name: 'echo-ability',
+  role: 'ability', // 'agent', 'ability',
   protocol: 'stdio', // 'native', 'stdio', or 'broker'
-  brokerUrls: ['ws://localhost:8080'] 
+  brokers: {
+    'local': 'ws://localhost:8080',
+    'prod': 'ws://api.example.com:8080'
+  },
+  defaultBroker: 'local'
 });
 
 // Method 1: Simple tool registration
-service.registerTool('echo', async ({ message }) => ({
+ability.registerTool('echo', async ({ message }) => ({
   echo: message,
   timestamp: new Date().toISOString()
 }));
 
 // Method 2: Tool with inline schema
-service.registerTool(
+ability.registerTool(
   'format',
   async ({ text, style }) => ({
     formatted: style === 'upper' ? text.toUpperCase() : text.toLowerCase()
@@ -282,7 +275,7 @@ service.registerTool(
 );
 
 // Start serving
-service.serve().catch(console.error);
+ability.serve().catch(console.error);
 ```
 
 ### Event Publishing and Subscription
@@ -292,45 +285,46 @@ service.serve().catch(console.error);
 KadiClient provides a unified event system that works consistently across all transport protocols:
 
 ```javascript
-// In your service (service.js)
-const service = new KadiClient({ 
-  name: 'my-service',
+// 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
-service.registerTool('echo', async ({ message }) => {
+ability.registerTool('echo', async ({ message }) => {
   // Publish events during processing
-  await service.publishEvent('echo.processing', { status: 'started' });
-  
+  await ability.publishEvent('echo.processing', { status: 'started' });
+
   // Do work...
   const result = { echo: message, timestamp: new Date().toISOString() };
-  
-  await service.publishEvent('echo.completed', { result });
+
+  await ability.publishEvent('echo.completed', { result });
   return result;
 });
 
-// In your client (index.js)
-const client = new KadiClient({
+// In your agent (agent.js)
+const agent = new KadiClient({
   name: 'my-client',
   role: 'agent',
   protocol: 'broker'
 });
 
 // Subscribe to events using patterns
-client.subscribeToEvent('echo.*', (data) => {
+agent.subscribeToEvent('echo.*', (data) => {
   console.log('Echo event received:', data);
 });
 
 // For loaded abilities with native/stdio protocols
-const ability = await loadAbility('my-service', 'stdio');
+const ability = await loadAbility('my-ability', 'stdio');
 ability.events.on('echo.completed', (data) => {
   console.log('Completed:', data);
 });
 ```
 
-**Event Patterns**: 
+**Event Patterns**:
+
 - Use wildcards: `math.*` matches `math.operation`, `math.milestone`
 - Protocol-specific delivery:
   - **Native**: Direct EventEmitter (synchronous)
@@ -339,7 +333,7 @@ ability.events.on('echo.completed', (data) => {
 
 ### Ability Configuration (agent.json)
 
-Every ability should have an `agent.json` file that defines its capabilities and interfaces:
+Every ability should have an `agent.json` file that defines its capabilities:
 
 ```json
 {
@@ -347,24 +341,10 @@ Every ability should have an `agent.json` file that defines its capabilities and
   "kind": "ability",
   "version": "1.0.0",
   "license": "MIT",
-  "description": "Echo service with multiple transport support",
+  "description": "Echo ability with multiple transport support",
   "scripts": {
     "setup": "npm install",
-    "start": "node service.js"
-  },
-  "interfaces": {
-    "native": {
-      "entry": "service.js"
-    },
-    "stdio": {
-      "discover": true,
-      "timeoutMs": 10000
-    },
-    "broker": {
-      "discover": true,
-      "timeoutMs": 15000,
-      "serviceName": "echo-service"
-    }
+    "start": "node ability.js"
   },
   "exports": [
     {
@@ -389,7 +369,8 @@ Every ability should have an `agent.json` file that defines its capabilities and
   "brokers": {
     "local": "ws://localhost:8080",
     "remote": "ws://api.example.com:8080"
-  }
+  },
+  "defaultBroker": "local"
 }
 ```
 
@@ -398,7 +379,7 @@ Every ability should have an `agent.json` file that defines its capabilities and
 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 `.method()`)
+2. **Inline Schemas** (passed directly to `registerTool()`)
 
 ```javascript
 // Option 1: Define in agent.json exports section
@@ -416,7 +397,7 @@ The ability system provides two ways to define method schemas:
 }
 
 // Option 2: Define inline when registering the method
-ability.method('process', handler, {
+ability.registerTool('process', handler, {
   description: 'Process data',
   inputSchema: { /* ... */ },
   outputSchema: { /* ... */ }
@@ -441,24 +422,29 @@ const echoAbility = await loadAbility('echo-js', 'stdio');
 const result = await echoAbility.echo({ message: 'Hello world' });
 
 // Load broker tools directly
-const remoteService = await loadAbility('remote-service', 'broker', {
+const remoteAbility = await loadAbility('remote-ability', 'broker', {
   brokerUrl: 'ws://localhost:8080',
   networks: ['global']
 });
-const brokerResult = await remoteService.process({ data: 'test' });
+const brokerResult = await remoteAbility.process({ data: 'test' });
 ```
 
-### Using KadiClient
+### Using KadiClient with Named Brokers
 
 ```javascript
 import { KadiClient } from '@kadi.build/core';
 
-// Create a unified client
+// Create a unified client with named brokers
 const client = new KadiClient({
-  name: 'my-service',
-  role: 'service', // Can both serve and consume
+  name: 'my-ability',
+  role: 'ability', // Provider role
   protocol: 'broker',
-  brokerUrls: ['ws://localhost:8080'],
+  brokers: {
+    'dev': 'ws://localhost:8080',
+    'staging': 'ws://staging.example.com:8080',
+    'prod': 'ws://prod.example.com:8080'
+  },
+  defaultBroker: 'dev',
   networks: ['global']
 });
 
@@ -478,7 +464,7 @@ client.registerTool(
   }
 );
 
-// Connect and serve
+// Connect to all configured brokers
 await client.connectToBrokers();
 
 // Call remote tools
@@ -491,7 +477,7 @@ const result = await client.callTool('translator', 'translate', {
 const ability = await client.loadAbility('echo-js');
 ```
 
-Use `loadAbility()` for simple consumption, or KadiClient for full-featured service development with tool registration, event publishing, and remote tool invocation.
+Use `loadAbility()` for simple consumption, or KadiClient for full-featured ability development with tool registration, event publishing, and remote tool invocation.
 
 ## 🔄 Architecture Deep Dive
 
@@ -506,31 +492,31 @@ sequenceDiagram
     participant Transport
     participant FileSystem
     participant ChildProcess
-    participant Service
+    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->>Service: Extract tool handlers via getToolNames()
-        Service-->>Transport: Return registered tools
+        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->>Service: KadiClient detects stdio mode
-        Service->>Service: Setup FrameReader/Writer
-        Transport->>Service: Send discovery request
-        Service-->>Transport: Return tool list
+        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: Create KadiClient wrapper
+        Transport->>Transport: Reuse existing KadiClient
         Transport->>Broker: WebSocket connect
         Transport->>Broker: kadi.session.hello
         Broker-->>Transport: { nonce, heartbeatIntervalSec }
@@ -543,21 +529,21 @@ sequenceDiagram
 
     loadAbility->>loadAbility: Create proxy with tool methods
     loadAbility-->>Client: Return ability proxy
-    
-    Note over Client,Service: Tool invocation
+
+    Note over Client,Ability: Tool invocation
     Client->>Transport: ability.echo({ message })
-    
+
     alt native
-        Transport->>Service: Direct handler call
-    else stdio  
-        Transport->>Service: JSON-RPC over frames
+        Transport->>Ability: Direct handler call
+    else stdio
+        Transport->>Ability: JSON-RPC over frames
     else broker
         Transport->>Broker: kadi.ability.invoke
-        Broker->>Service: Route to target
-        Service->>Broker: kadi.ability.result
+        Broker->>Ability: Route to target
+        Ability->>Broker: kadi.ability.result
         Broker-->>Transport: Forward result
     end
-    
+
     Transport-->>Client: Return result
 ```
 
@@ -576,16 +562,16 @@ sequenceDiagram
     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
@@ -608,7 +594,7 @@ sequenceDiagram
 
     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)
@@ -623,7 +609,7 @@ sequenceDiagram
         KC->>KC: toolHandlers.get(toolName).handler(params)
         KC->>Network: kadi.ability.result message
     end
-    
+
     Network-->>RemoteClient: Tool result
 ```
 
@@ -633,14 +619,14 @@ KadiClient provides a unified event API that works across all transport protocol
 
 ```mermaid
 sequenceDiagram
-    participant Publisher as Service (Publisher)
+    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}
@@ -651,10 +637,10 @@ sequenceDiagram
         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
@@ -665,14 +651,14 @@ sequenceDiagram
         Transport-->>Subscriber: Framed event over stdout
         Subscriber->>Transport: FrameReader parses
         Transport->>Subscriber: emit('transport:event', {name, data})
-        Subscriber->>Subscriber: Pattern match & invoke callback  
+        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'
@@ -690,8 +676,8 @@ Detailed view of broker-based communication with heartbeat:
 sequenceDiagram
     participant Client as KadiClient
     participant Broker as KADI Broker
-    participant Target as Target Service
-    
+    participant Target as Target Ability
+
     Note over Client,Broker: Connection & Authentication
     Client->>Broker: WebSocket connect
     Client->>Broker: kadi.session.hello({ role })
@@ -700,40 +686,40 @@ sequenceDiagram
     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('service-b', 'process', params)
-    Client->>Broker: kadi.ability.invoke({ 
-        targetAgent: 'service-b',
+    Client->>Client: callTool('ability-b', 'process', params)
+    Client->>Broker: kadi.ability.invoke({
+        targetAgent: 'ability-b',
         toolName: 'process',
         toolInput: params
     })
-    Broker->>Broker: Lookup service-b
+    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
@@ -750,10 +736,10 @@ sequenceDiagram
     participant SR as StdioFrameReader
     participant SW as StdioFrameWriter
     participant Server as StdioRpcServer
-    participant Ability as KadiAbility
+    participant Ability as KadiClient
 
     Note over Parent,SR: Incoming Request
-    Parent->>SR: Write to stdin: "Kadi-Content-Length: 52\r\n\r\n{...}"
+    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
@@ -770,7 +756,7 @@ sequenceDiagram
     Server->>SW: write(response)
     SW->>SW: JSON.stringify(response)
     SW->>SW: Calculate byte length
-    SW->>SW: Create header: "Kadi-Content-Length: N\r\n\r\n"
+    SW->>SW: Create header: "Content-Length: N\r\n\r\n"
     SW->>Parent: Write header + body to stdout
 
     Note over SR: Error Recovery
@@ -809,14 +795,14 @@ const result = await ability.echo({ message: 'hello' });
 const result = await ability.someMethod({ param: 'value' });
 
 // Direct RPC call (bypasses method validation)
-const response = await ability.call('someMethod', { param: 'value' });
+const response = await ability.__call('someMethod', { param: 'value' });
 
 // Subscribe to events
 ability.events.on('custom:event', (data) => {
   console.log('Event received:', data);
 });
 
-// Note: Events work for native and stdio protocols
+// Note: Events work for all protocols (native, stdio, and broker)
 // Subscribe before calling methods that emit events
 ```
 
@@ -838,7 +824,7 @@ export KADI_PROTOCOL=stdio
 
 # Configure broker
 export KADI_BROKER_URL=ws://localhost:8080
-export KADI_SERVICE_NAME=my-service
+export KADI_ABILITY_NAME=my-ability
 export KADI_AGENT_SCOPE=project-123
 ```
 
@@ -849,14 +835,14 @@ When abilities are spawned as child processes (stdio and broker protocols), the
 ```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 serviceName = process.env.KADI_SERVICE_NAME; 
+const brokerUrl = process.env.KADI_BROKER_URL;
+const abilityName = process.env.KADI_ABILITY_NAME;
 const agentScope = process.env.KADI_AGENT_SCOPE;
 
 // Use them to configure your ability behavior
-const ability = new KadiAbility({
+const ability = new KadiClient({
   name: 'my-ability',
-  scope: process.env.KADI_AGENT_SCOPE || 'global'
+  network: process.env.KADI_AGENT_SCOPE || 'global'
   // Ability automatically uses KADI_PROTOCOL to determine transport
 });
 ```
@@ -870,7 +856,7 @@ my-project/
 │   └── echo-ability/
 │       └── 1.0.0/
 │           ├── agent.json  # Ability configuration
-│           ├── service.js  # Ability implementation
+│           ├── ability.js  # Ability implementation
 │           └── package.json
 ├── modules/                # Source modules
 │   └── echo-ability/       # Development version
@@ -885,10 +871,10 @@ KadiClient provides a comprehensive event system that works across all protocols
 
 #### 1. Lifecycle Events
 
-Monitor the service lifecycle:
+Monitor the ability lifecycle:
 
 ```javascript
-const client = new KadiClient({ name: 'my-service' });
+const client = new KadiClient({ name: 'my-ability' });
 
 // Connection events
 client.on('connected', ({ broker }) => {
@@ -909,7 +895,7 @@ client.on('tool:completed', ({ toolName, result }) => {
 });
 
 client.on('error', (error) => {
-  console.error('Service error:', error);
+  console.error('Ability error:', error);
 });
 ```
 
@@ -921,7 +907,7 @@ Publish and subscribe to custom events across all transport protocols:
 // Publishing events
 const publisher = new KadiClient({
   name: 'event-publisher',
-  role: 'service',
+  role: 'ability',
   protocol: 'broker' // Works with all protocols
 });
 
@@ -961,12 +947,9 @@ subscriber.onceEvent('process.completed', (data) => {
 });
 
 // Multiple pattern subscription
-subscriber.subscribeToEvents(
-  ['process.*', 'system.*'],
-  (pattern, data) => {
-    console.log(`Event from ${pattern}:`, data);
-  }
-);
+subscriber.subscribeToEvents(['process.*', 'system.*'], (pattern, data) => {
+  console.log(`Event from ${pattern}:`, data);
+});
 ```
 
 **Protocol-Specific Behavior:**
@@ -975,6 +958,69 @@ subscriber.subscribeToEvents(
 - **Stdio**: JSON-RPC notifications with LSP framing
 - **Broker**: RabbitMQ pub/sub via WebSocket, persistent queues available
 
+### Multi-Broker Configuration
+
+KadiClient supports connecting to multiple brokers simultaneously for redundancy and load distribution:
+
+```javascript
+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']
+});
+
+// Connect to all configured brokers
+await client.connectToBrokers();
+
+// 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
+```
+
+### Cross-Language Ability Support
+
+KADI now fully supports abilities written in any language through the stdio protocol:
+
+```javascript
+// Go ability with agent.json:
+{
+  "name": "hash-go",
+  "scripts": {
+    "setup": "go build -o bin/hash_ability",
+    "start": "./bin/hash_ability"  // Binary executable
+  }
+}
+
+// Python ability:
+{
+  "name": "ml-processor",
+  "scripts": {
+    "start": "python3 main.py"
+  }
+}
+
+// Rust ability:
+{
+  "name": "crypto-rust",
+  "scripts": {
+    "setup": "cargo build --release",
+    "start": "./target/release/crypto_ability"
+  }
+}
+
+// Load and use regardless of implementation language:
+const hashAbility = await loadAbility('hash-go', 'stdio');
+const result = await hashAbility.sha256({ data: 'hello' });
+```
 
 ## 🔧 Development Workflow
 
@@ -982,7 +1028,7 @@ subscriber.subscribeToEvents(
 
 When developing new features or testing changes to `@kadi.build/core` before publishing to NPM:
 
-0. **clone the repository**
+0. **Clone the repository**
 
 ```bash
 git clone https://gitlab.com/humin-game-lab/kadi/kadi-core.git
@@ -996,14 +1042,14 @@ npm pack
 # This creates: kadi.build-core-X.Y.Z.tgz
 ```
 
-1. **Install in your project**:
+2. **Install in your project**:
 
 ```bash
 cd /path/to/your-project
 npm install /path/to/kadi-core/kadi.build-core-X.Y.Z.tgz
 ```
 
-1. **For ability development**, update the ability's preflight script:
+3. **For ability development**, update the ability's preflight script:
 
 ```json
 {
@@ -1019,29 +1065,38 @@ npm install /path/to/kadi-core/kadi.build-core-X.Y.Z.tgz
 
 #### `KadiClient`
 
-The unified class for all KADI operations - serving tools, calling remote services, and managing events.
+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-service',
-  role: 'service', // 'agent', 'ability', or 'service'
+  name: 'my-ability',
+  role: 'ability', // 'agent' or 'ability'
   protocol: 'broker', // 'native', 'stdio', or 'broker'
-  brokerUrls: ['ws://localhost:8080'],
-  networks: ['global', 'custom-network']
+  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` - Service/agent name
-- `role` - Operating role: 'agent' (consumer), 'ability' (provider), 'service' (both)
+
+- `name` - Ability/agent name
+- `role` - Operating role: 'agent' (consumer) or 'ability' (provider)
 - `protocol` - Transport protocol to use
-- `brokerUrls` - Array of broker WebSocket URLs (for broker protocol)
-- `networks` - Network namespaces for tool discovery
+- `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
@@ -1050,11 +1105,13 @@ const client = new KadiClient({
 - `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:**
+
 - `publishEvent(eventName, data)` - Publish an event
 - `subscribeToEvent(pattern, callback)` - Subscribe with wildcards
 - `subscribeToEvents(patterns[], callback)` - Multiple subscriptions
@@ -1062,49 +1119,58 @@ const client = new KadiClient({
 - `onceEvent(pattern, callback)` - One-time subscription
 
 **Connection Management:**
+
 - `serve()` - Start serving (stdio/native modes)
-- `connectToBrokers(urls?)` - Connect to broker(s)
+- `connectToBrokers()` - Connect to all configured brokers
 - `disconnect()` - Clean disconnect
 - `isConnected` - Check connection status
 
 **Properties:**
+
 - `agentId` - Unique agent identifier
-- `name` - Service name
+- `name` - Ability name
 - `role` - Current operating role
 - `protocol` - Active protocol
+- `brokers` - Configured broker map
+- `defaultBroker` - Default broker name
+- `currentBroker` - Currently active broker for sending
 
 **Complete Usage Example:**
 
 ```javascript
 import { KadiClient } from '@kadi.build/core';
 
-// Create a service that can both serve and consume
-const service = new KadiClient({
-  name: 'math-service',
-  role: 'service',
+// Create an ability that can serve tools
+const ability = new KadiClient({
+  name: 'math-ability',
+  role: 'ability',
   protocol: 'broker',
-  brokerUrls: ['ws://localhost:8080'],
+  brokers: {
+    'local': 'ws://localhost:8080',
+    'cloud': 'wss://api.example.com'
+  },
+  defaultBroker: 'local',
   networks: ['global']
 });
 
 // Register tools with schemas
-service.registerTool(
+ability.registerTool(
   'add',
   async ({ a, b }) => {
     // Publish event before processing
-    await service.publishEvent('math.operation', {
+    await ability.publishEvent('math.operation', {
       operation: 'add',
       inputs: { a, b }
     });
-    
+
     const result = a + b;
-    
+
     // Publish completion event
-    await service.publishEvent('math.completed', {
+    await ability.publishEvent('math.completed', {
       operation: 'add',
       result
     });
-    
+
     return { result };
   },
   {
@@ -1126,24 +1192,23 @@ service.registerTool(
   }
 );
 
-// Subscribe to events from other services
-service.subscribeToEvent('system.*', (data) => {
+// Subscribe to events from other abilities
+ability.subscribeToEvent('system.*', (data) => {
   console.log('System event:', data);
 });
 
-// Connect to broker
-await service.connectToBrokers();
+// Connect to brokers
+await ability.connectToBrokers();
 
 // Call remote tools
-const result = await service.callTool(
-  'translator-service',
-  'translate',
-  { text: 'Hello', to: 'es' }
-);
+const result = await ability.callTool('translator-ability', 'translate', {
+  text: 'Hello',
+  to: 'es'
+});
 
 // Graceful shutdown
 process.on('SIGTERM', async () => {
-  await service.disconnect();
+  await ability.disconnect();
   process.exit(0);
 });
 ```
@@ -1155,14 +1220,20 @@ Load an ability by name and protocol.
 ```javascript
 import { loadAbility } from '@kadi.build/core';
 
-const ability = await loadAbility('ability-name', 'protocol');
+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
+});
 ```
 
 **Returns:** A proxy object with:
 
 - Direct method calls (e.g., `ability.echo({ message: 'hello' })`)
-- `ability.events` - EventEmitter for subscribing to events (native/stdio protocols only)
+- `ability.events` - EventEmitter for subscribing to events (all protocols)
 - `ability.__call(method, params)` - Direct RPC call
+- `ability.__disconnect()` - Clean up resources
 
 ### Utility Functions
 
@@ -1171,6 +1242,7 @@ import {
   createLogger,
   getProjectJSON,
   getAbilityJSON,
+  getAgentJSON,
   getBrokerUrl,
   runExecCommand
 } from '@kadi.build/core';
@@ -1189,6 +1261,97 @@ 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
+
+**Problem**: Memory usage grows over time
+
+**Solutions**:
+- Always call unsubscribe functions
+- Use `onceEvent` for single-use subscriptions
+- Disconnect abilities when done
+- Clear event listeners on cleanup
 
 ## 🤝 Contributing
 
@@ -1200,13 +1363,21 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 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
+
+- [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
+
 ---
 
-Built with ❤️ by the KADI team
+Built with ❤️ by the KADI team