@kadi.build/deploy-ability 0.0.3 → 0.0.5

package/docs/KADI_ABILITY_CONVERSION.md

@@ -0,0 +1,1365 @@
+# KADI Ability Conversion - Preserving Fluent APIs
+
+> **Document Purpose**: Guide for converting deploy-ability into a KADI ability while preserving the fluent API design
+>
+> **Author**: KADI Team
+>
+> **Date**: 2025-11-18
+>
+> **Status**: Design Proposal
+
+---
+
+## Executive Summary
+
+### The Question
+
+**Can we turn deploy-ability into a KADI ability while keeping the Pipeline Builder's fluent API?**
+
+### The Answer
+
+**Yes, absolutely!** Using the **dual export pattern** from secret-ability, you can have:
+
+- ✅ **Fluent API** for local/CLI use (best developer experience)
+- ✅ **Tool-based RPC** for distributed/remote use (best for agents)
+- ✅ **Both interfaces** maintained in the same package
+- ✅ **No breaking changes** to existing code
+
+### Key Insight
+
+**Fluent APIs and KADI abilities are NOT mutually exclusive.** They serve different use cases:
+
+| Use Case | Interface | Why |
+|----------|-----------|-----|
+| Local CLI commands | Fluent API | Best DX, discoverable, type-safe |
+| Agent-to-agent calls | Tool-based RPC | Stateless, distributed, simple |
+| Scripts/automation | Fluent API | Flexible, composable, clear |
+| Broker/MCP integration | Tool-based RPC | Standard protocol, interoperable |
+
+---
+
+## The Dual Export Pattern
+
+### How secret-ability Does It
+
+secret-ability successfully implements this pattern:
+
+**package.json:**
+```json
+{
+  "name": "secret-ability",
+  "main": "./dist/kadi-ability.js",
+  "exports": {
+    ".": {
+      "types": "./dist/kadi-ability.d.ts",
+      "import": "./dist/kadi-ability.js"
+    },
+    "./lib": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}
+```
+
+**File structure:**
+```
+secret-ability/
+├── src/
+│   ├── index.ts           # Library export - Fluent API (Secrets class)
+│   ├── kadi-ability.ts    # Ability export - Tool-based RPC
+│   ├── core/
+│   │   └── secrets.ts     # The Secrets class with fluent initializer
+│   └── ...
+```
+
+### Two Interfaces, One Codebase
+
+**Library Interface (`/lib`):**
+```typescript
+import { Secrets } from '@kadi.build/secret-ability/lib';
+
+const secrets = new Secrets();
+await secrets.init()
+  .ensure('wallet', { type: 'custom', path: './wallet.vault' })
+  .use('wallet');
+
+await secrets.set('MNEMONIC', 'word1 word2 ...');
+```
+
+**Ability Interface (default):**
+```typescript
+const secrets = await client.load('secret-ability', 'native');
+
+await secrets.init({ vaults: [{ name: 'wallet', type: 'custom', path: './wallet.vault' }] });
+await secrets.useVault({ vaultName: 'wallet' });
+await secrets.set({ key: 'MNEMONIC', value: 'word1 word2 ...' });
+```
+
+Same functionality, different interfaces for different use cases!
+
+---
+
+## Current State: deploy-ability
+
+### Current Architecture
+
+deploy-ability is currently a **pure library** - not yet a KADI ability.
+
+**How it's used today:**
+```typescript
+import { setupRegistryIfNeeded, loadProfile, deploy } from '@kadi.build/deploy-ability';
+
+// Manual setup and cleanup
+const registryManager = new DockerRegistryManager();
+await registryManager.startTemporaryRegistry();
+
+try {
+  const profile = await loadProfile('./agent.json', 'production');
+  await deploy(profile, wallet, certificate);
+} finally {
+  await registryManager.cleanup(); // Easy to forget!
+}
+```
+
+### The Pipeline Builder (Proposed)
+
+The fluent API design from `PIPELINE_BUILDER_DESIGN.md`:
+
+```typescript
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+
+const result = await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .withLocalImageSupport({ tunnelService: 'serveo' })
+  .withWallet(wallet)
+  .withCertificate(certificate)
+  .execute();
+// Cleanup happens automatically! ✨
+```
+
+**This is excellent design** - we want to preserve it!
+
+---
+
+## Proposed State: deploy-ability as KADI Ability
+
+### Package Structure
+
+**Updated package.json:**
+```json
+{
+  "name": "@kadi.build/deploy-ability",
+  "version": "0.0.5",
+  "description": "Multi-target deployment orchestration for KADI",
+  "type": "module",
+  "main": "./dist/kadi-ability.js",
+  "types": "./dist/kadi-ability.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/kadi-ability.d.ts",
+      "import": "./dist/kadi-ability.js"
+    },
+    "./lib": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    }
+  },
+  "dependencies": {
+    "@kadi.build/core": "^0.0.1-alpha.15",
+    "zod": "^3.22.4"
+  }
+}
+```
+
+### File Structure
+
+```
+deploy-ability/
+├── src/
+│   ├── index.ts              # Library export - FLUENT API ✅
+│   │                         # Exports: DeploymentPipeline, types, utilities
+│   │
+│   ├── kadi-ability.ts       # Ability export - TOOL-BASED RPC
+│   │                         # Registers tools, wraps fluent API
+│   │
+│   ├── pipeline-builder.ts   # The beautiful fluent API
+│   │                         # DeploymentPipeline class
+│   │
+│   ├── targets/
+│   │   ├── local/
+│   │   │   └── local.ts
+│   │   └── akash/
+│   │       ├── akash.ts
+│   │       └── deployer.ts
+│   │
+│   ├── utils/
+│   │   └── registry/
+│   │       ├── manager.ts
+│   │       └── setup.ts
+│   │
+│   └── types/
+│       └── index.ts
+│
+└── docs/
+    ├── PIPELINE_BUILDER_DESIGN.md
+    └── KADI_ABILITY_CONVERSION.md  # This document
+```
+
+### Two Interfaces Working Together
+
+The **ability layer** internally uses the **fluent library**:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Consumer Code                                       │
+├─────────────────────────────────────────────────────┤
+│                                                       │
+│  Option A: Direct Library Import                     │
+│  ┌─────────────────────────────────────────┐        │
+│  │ import { DeploymentPipeline }           │        │
+│  │ from '@kadi.build/deploy-ability/lib'   │        │
+│  │                                          │        │
+│  │ await DeploymentPipeline.create(...)    │        │
+│  └─────────────────────────────────────────┘        │
+│         ↓                                             │
+│  ┌─────────────────────────────────────────┐        │
+│  │ Pipeline Builder (Fluent API)           │        │
+│  └─────────────────────────────────────────┘        │
+│                                                       │
+│  Option B: KADI Ability Loading                      │
+│  ┌─────────────────────────────────────────┐        │
+│  │ const deploy = await client.load(...)   │        │
+│  │ await deploy.deploy({ ... })            │        │
+│  └─────────────────────────────────────────┘        │
+│         ↓                                             │
+│  ┌─────────────────────────────────────────┐        │
+│  │ Tool-based RPC Interface                │        │
+│  │ (internally uses Pipeline Builder)      │        │
+│  └─────────────────────────────────────────┘        │
+│         ↓                                             │
+│  ┌─────────────────────────────────────────┐        │
+│  │ Pipeline Builder (Fluent API)           │        │
+│  └─────────────────────────────────────────┘        │
+│                                                       │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Code Examples - Before/After
+
+### Current Usage (Library Only)
+
+**kadi-deploy using deploy-ability today:**
+
+```typescript
+// kadi-deploy/src/index.ts
+import { loadProfile, setupRegistryIfNeeded } from '@kadi.build/deploy-ability';
+import { deploy as deployToAkash } from '@kadi.build/deploy-ability/targets/akash';
+
+export async function deploy(options: DeployOptions) {
+  // Load profile
+  const profile = await loadProfile(
+    options.projectRoot,
+    options.profile,
+    options
+  );
+
+  // Setup registry if needed (manual!)
+  const registryCleanup = await setupRegistryIfNeeded(profile);
+
+  try {
+    // Deploy
+    if (profile.target === 'akash') {
+      await deployToAkash(profile, wallet, certificate);
+    }
+    // ... other targets
+  } finally {
+    // Cleanup (easy to forget!)
+    if (registryCleanup) {
+      await registryCleanup();
+    }
+  }
+}
+```
+
+**Problems:**
+- Manual registry management
+- Easy to forget cleanup
+- Verbose error handling
+- Hard to compose operations
+
+---
+
+### Proposed Usage (As KADI Ability)
+
+#### Option A: Library Import (for local/CLI use)
+
+**kadi-deploy using the fluent library API:**
+
+```typescript
+// kadi-deploy/src/index.ts
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+
+export async function deploy(options: DeployOptions) {
+  // Beautiful fluent API! ✨
+  const result = await DeploymentPipeline
+    .create({
+      projectRoot: options.projectRoot,
+      profile: options.profile
+    })
+    .withLocalImageSupport({
+      tunnelService: options.tunnelService || 'serveo'
+    })
+    .withWallet(wallet)
+    .withCertificate(certificate)
+    .execute();
+
+  // Cleanup happens automatically!
+
+  return result;
+}
+```
+
+**Benefits:**
+- ✅ Automatic cleanup
+- ✅ Discoverable API
+- ✅ Type-safe
+- ✅ Easy to read and understand
+
+---
+
+#### Option B: Ability Loading (for distributed use)
+
+**Remote agent calling deploy-ability as a KADI ability:**
+
+```typescript
+// model-manager-agent/src/services/deployment-controller.ts
+import { KadiClient } from '@kadi.build/core';
+
+export class DeploymentController {
+  private deployAbility: any;
+
+  async initialize() {
+    const client = new KadiClient({ name: 'model-manager' });
+
+    // Load deploy-ability as a KADI ability
+    this.deployAbility = await client.load('deploy-ability', 'native');
+  }
+
+  async deployModel(request: DeploymentRequest) {
+    // Tool-based interface (works remotely)
+    const result = await this.deployAbility.deploy({
+      projectRoot: './templates',
+      profile: 'ollama-runtime',
+      localImageSupport: {
+        tunnelService: 'serveo'
+      },
+      wallet: this.wallet,
+      certificate: this.certificate,
+      // Additional deployment-specific options
+      modelName: request.modelName,
+      gpuType: request.gpu
+    });
+
+    if (!result.success) {
+      throw new Error(`Deployment failed: ${result.message}`);
+    }
+
+    return result;
+  }
+}
+```
+
+**Benefits:**
+- ✅ Works across process boundaries
+- ✅ Version-isolated through KADI
+- ✅ Stateless RPC
+- ✅ Simple parameter passing
+
+---
+
+## Implementation Guide
+
+### Step 1: Create `kadi-ability.ts`
+
+This is the new file that wraps your fluent API in a tool-based interface.
+
+**File: `src/kadi-ability.ts`**
+
+```typescript
+/**
+ * KADI Ability Interface for deploy-ability
+ *
+ * Exposes deployment functionality through KADI's ability system.
+ * Uses KadiClient to register tools with proper schemas and handlers.
+ *
+ * IMPORTANT: This is a thin wrapper around the fluent library API.
+ * For local/CLI use, prefer importing from '/lib' for the fluent interface.
+ *
+ * @module kadi-ability
+ */
+
+import { KadiClient, z } from '@kadi.build/core';
+import { DeploymentPipeline } from './pipeline-builder.js';
+import type {
+  DeploymentResult,
+  AkashWallet,
+  AkashCertificate
+} from './types/index.js';
+
+// Create the KadiClient instance
+const client = new KadiClient({
+  name: 'deploy-ability',
+  version: '0.0.5',
+  description: 'Multi-target deployment orchestration for KADI',
+  role: 'ability'
+});
+
+// ============================================================================
+// Tool Registration
+// ============================================================================
+
+/**
+ * deploy - Deploy to target platform
+ *
+ * Main deployment tool that orchestrates the entire deployment process.
+ * Internally uses the DeploymentPipeline fluent API for clean resource management.
+ */
+const deployInputSchema = z.object({
+  projectRoot: z.string().describe('Project root directory'),
+  profile: z.string().describe('Deployment profile name'),
+
+  // Optional enhancements
+  localImageSupport: z.object({
+    tunnelService: z.enum(['serveo', 'ngrok', 'bore']).optional()
+      .describe('Tunnel service for exposing local registry'),
+    registryPort: z.number().optional()
+      .describe('Local registry port (default: 5001)')
+  }).optional().describe('Enable local image support with temporary registry'),
+
+  wallet: z.any().optional()
+    .describe('Akash wallet for blockchain transactions'),
+
+  certificate: z.any().optional()
+    .describe('Akash certificate for provider authentication'),
+
+  // CLI overrides
+  verbose: z.boolean().optional()
+    .describe('Enable verbose logging'),
+
+  dryRun: z.boolean().optional()
+    .describe('Simulate deployment without executing'),
+
+  yes: z.boolean().optional()
+    .describe('Auto-confirm all prompts'),
+});
+
+const deployOutputSchema = z.object({
+  success: z.boolean(),
+  deploymentId: z.string().optional()
+    .describe('Unique deployment identifier'),
+  dseq: z.string().optional()
+    .describe('Akash deployment sequence number'),
+  endpoints: z.array(z.string()).optional()
+    .describe('Accessible service endpoints'),
+  leaseInfo: z.object({
+    provider: z.string(),
+    price: z.string(),
+    priceUsd: z.number().optional()
+  }).optional().describe('Lease information for Akash deployments'),
+  message: z.string().optional()
+    .describe('Status or error message'),
+});
+
+client.registerTool({
+  name: 'deploy',
+  description: 'Deploy agent to target platform using specified profile',
+  input: deployInputSchema,
+  output: deployOutputSchema
+}, async (params: z.infer<typeof deployInputSchema>) => {
+  try {
+    // Build the deployment pipeline using the fluent API
+    let pipeline = DeploymentPipeline.create({
+      projectRoot: params.projectRoot,
+      profile: params.profile,
+      verbose: params.verbose,
+      dryRun: params.dryRun,
+      yes: params.yes
+    });
+
+    // Add local image support if requested
+    if (params.localImageSupport) {
+      pipeline = pipeline.withLocalImageSupport({
+        tunnelService: params.localImageSupport.tunnelService || 'serveo',
+        registryPort: params.localImageSupport.registryPort
+      });
+    }
+
+    // Add wallet if provided (Akash deployments)
+    if (params.wallet) {
+      pipeline = pipeline.withWallet(params.wallet as AkashWallet);
+    }
+
+    // Add certificate if provided (Akash deployments)
+    if (params.certificate) {
+      pipeline = pipeline.withCertificate(params.certificate as AkashCertificate);
+    }
+
+    // Execute the pipeline
+    // The pipeline handles all resource management and cleanup automatically
+    const result = await pipeline.execute();
+
+    return {
+      success: true,
+      deploymentId: result.deploymentId,
+      dseq: result.dseq,
+      endpoints: result.endpoints,
+      leaseInfo: result.leaseInfo,
+      message: 'Deployment completed successfully'
+    };
+
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+
+    return {
+      success: false,
+      message: `Deployment failed: ${errorMsg}`
+    };
+  }
+});
+
+/**
+ * getDeploymentStatus - Check deployment status
+ *
+ * Query the status of an existing deployment.
+ */
+const getStatusInputSchema = z.object({
+  deploymentId: z.string().describe('Deployment identifier to check'),
+  target: z.enum(['local', 'akash']).describe('Deployment target')
+});
+
+const getStatusOutputSchema = z.object({
+  success: z.boolean(),
+  status: z.enum(['pending', 'active', 'failed', 'closed']).optional(),
+  message: z.string().optional()
+});
+
+client.registerTool({
+  name: 'getDeploymentStatus',
+  description: 'Get the current status of a deployment',
+  input: getStatusInputSchema,
+  output: getStatusOutputSchema
+}, async (params: z.infer<typeof getStatusInputSchema>) => {
+  try {
+    // Implementation would query deployment status
+    // This is a placeholder for the actual implementation
+
+    return {
+      success: true,
+      status: 'active',
+      message: 'Deployment is running'
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+});
+
+/**
+ * closeDeployment - Close/stop a deployment
+ *
+ * Gracefully shut down and clean up a deployment.
+ */
+const closeInputSchema = z.object({
+  deploymentId: z.string().describe('Deployment identifier to close'),
+  target: z.enum(['local', 'akash']).describe('Deployment target')
+});
+
+const closeOutputSchema = z.object({
+  success: z.boolean(),
+  message: z.string().optional()
+});
+
+client.registerTool({
+  name: 'closeDeployment',
+  description: 'Close and cleanup a deployment',
+  input: closeInputSchema,
+  output: closeOutputSchema
+}, async (params: z.infer<typeof closeInputSchema>) => {
+  try {
+    // Implementation would close the deployment
+    // This is a placeholder for the actual implementation
+
+    return {
+      success: true,
+      message: 'Deployment closed successfully'
+    };
+  } catch (error) {
+    return {
+      success: false,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+});
+
+// Export the client as default
+export default client;
+
+// Allow running standalone as stdio server
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await client.serve('stdio');
+}
+```
+
+---
+
+### Step 2: Update Library Export (`index.ts`)
+
+Make sure the library export exposes the fluent API:
+
+**File: `src/index.ts`**
+
+```typescript
+/**
+ * deploy-ability - Library Export
+ *
+ * Main library interface for deploy-ability.
+ * Provides fluent API through DeploymentPipeline.
+ *
+ * @module deploy-ability/lib
+ */
+
+// ============================================================================
+// Fluent API - Primary Interface
+// ============================================================================
+
+export { DeploymentPipeline } from './pipeline-builder.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  DeploymentProfile,
+  AkashDeploymentProfile,
+  LocalDeploymentProfile,
+  DeploymentResult,
+  AkashWallet,
+  AkashCertificate,
+  ServiceConfig,
+  // ... all other types
+} from './types/index.js';
+
+// ============================================================================
+// Legacy Exports (for backward compatibility)
+// ============================================================================
+
+// Keep these for existing code that uses the old API
+export { loadProfile } from './utils/profileUtils.js';
+export { setupRegistryIfNeeded } from './utils/registry/setup.js';
+export { DockerRegistryManager } from './utils/registry/manager.js';
+
+// Target implementations (advanced users)
+export { deploy as deployToLocal } from './targets/local/local.js';
+export { deploy as deployToAkash } from './targets/akash/akash.js';
+```
+
+---
+
+### Step 3: Update `package.json`
+
+Add the exports configuration:
+
+```json
+{
+  "name": "@kadi.build/deploy-ability",
+  "version": "0.0.5",
+  "description": "Multi-target deployment orchestration for KADI",
+  "type": "module",
+  "main": "./dist/kadi-ability.js",
+  "types": "./dist/kadi-ability.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/kadi-ability.d.ts",
+      "import": "./dist/kadi-ability.js"
+    },
+    "./lib": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@kadi.build/core": "^0.0.1-alpha.15",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.9.2",
+    "vitest": "^1.0.0"
+  }
+}
+```
+
+---
+
+### Step 4: TypeScript Configuration
+
+Ensure TypeScript outputs both files correctly:
+
+**tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "strict": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+---
+
+## Usage Patterns
+
+### Pattern 1: CLI Commands (kadi deploy)
+
+**Use the library's fluent API:**
+
+```typescript
+// kadi-deploy/src/commands/deploy.ts
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+
+export async function deployCommand(options: CommandOptions) {
+  const logger = createLogger(options.verbose);
+
+  logger.info('Starting deployment...');
+
+  try {
+    const result = await DeploymentPipeline
+      .create({
+        projectRoot: options.projectRoot || './',
+        profile: options.profile,
+        verbose: options.verbose,
+        dryRun: options.dryRun
+      })
+      .withLocalImageSupport({
+        tunnelService: options.tunnelService || 'serveo'
+      })
+      .withWallet(await loadWallet(options.walletPath))
+      .withCertificate(await loadCertificate(options.certPath))
+      .execute();
+
+    logger.success('Deployment completed!');
+    logger.info(`Deployment ID: ${result.deploymentId}`);
+
+    if (result.endpoints) {
+      logger.info('Endpoints:');
+      result.endpoints.forEach(ep => logger.info(`  - ${ep}`));
+    }
+
+  } catch (error) {
+    logger.error('Deployment failed:', error);
+    process.exit(1);
+  }
+}
+```
+
+**Why fluent API here?**
+- Running locally, in-process
+- Best developer experience
+- Type-safe and discoverable
+- Automatic cleanup
+
+---
+
+### Pattern 2: Agent-to-Agent Calls
+
+**Use the ability's tool interface:**
+
+```typescript
+// model-manager-agent/src/services/deployment-controller.ts
+import { KadiClient } from '@kadi.build/core';
+
+export class DeploymentController {
+  private client: KadiClient;
+  private deployAbility: any;
+
+  constructor() {
+    this.client = new KadiClient({
+      name: 'model-manager-agent',
+      projectRoot: process.cwd()
+    });
+  }
+
+  async initialize() {
+    // Load deploy-ability as a KADI ability
+    this.deployAbility = await this.client.load('deploy-ability', 'native');
+  }
+
+  async deployModel(request: DeployModelRequest): Promise<DeploymentInfo> {
+    // Call the deploy tool
+    const result = await this.deployAbility.deploy({
+      projectRoot: './templates',
+      profile: this.selectProfile(request),
+      localImageSupport: {
+        tunnelService: 'serveo'
+      },
+      wallet: this.wallet,
+      certificate: this.certificate
+    });
+
+    if (!result.success) {
+      throw new Error(`Deployment failed: ${result.message}`);
+    }
+
+    return {
+      deploymentId: result.deploymentId,
+      dseq: result.dseq,
+      endpoints: result.endpoints,
+      status: 'active'
+    };
+  }
+}
+```
+
+**Why tool interface here?**
+- Might be running in different process
+- Stateless RPC
+- Simple parameter passing
+- Version isolation through KADI
+
+---
+
+### Pattern 3: Automation Scripts
+
+**Use the library's fluent API:**
+
+```typescript
+// scripts/deploy-all-profiles.ts
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+import { loadWallet, loadCertificate } from './utils.js';
+
+const profiles = ['staging', 'production', 'backup'];
+
+async function deployAll() {
+  const wallet = await loadWallet();
+  const cert = await loadCertificate();
+
+  for (const profile of profiles) {
+    console.log(`\nDeploying profile: ${profile}`);
+
+    try {
+      const result = await DeploymentPipeline
+        .create({ projectRoot: './', profile })
+        .withWallet(wallet)
+        .withCertificate(cert)
+        .execute();
+
+      console.log(`✅ ${profile}: ${result.deploymentId}`);
+    } catch (error) {
+      console.error(`❌ ${profile} failed:`, error);
+    }
+  }
+}
+
+deployAll();
+```
+
+**Why fluent API here?**
+- Local automation
+- Clear, readable code
+- Composable operations
+- Automatic resource management
+
+---
+
+### Pattern 4: MCP/Broker Integration
+
+**Use the ability's tool interface:**
+
+```typescript
+// broker-integration/src/deploy-service.ts
+export class DeployService {
+  private client: KadiClient;
+
+  async handleDeployRequest(request: BrokerRequest): Promise<BrokerResponse> {
+    // Load deploy-ability through broker's client
+    const deployAbility = await this.client.load('deploy-ability', 'native');
+
+    // Parse request parameters
+    const params = JSON.parse(request.parameters);
+
+    // Execute deployment via tool
+    const result = await deployAbility.deploy({
+      projectRoot: params.projectRoot,
+      profile: params.profile,
+      wallet: params.wallet,
+      certificate: params.certificate
+    });
+
+    return {
+      success: result.success,
+      data: result,
+      message: result.message
+    };
+  }
+}
+```
+
+**Why tool interface here?**
+- Standard protocol (MCP/JSON-RPC)
+- Broker expects tool-based interface
+- May cross process boundaries
+- Needs to be serializable
+
+---
+
+## Comparison: Why This Works
+
+### Fluent APIs vs Tool-based RPC
+
+| Aspect | Fluent API | Tool-based RPC |
+|--------|-----------|----------------|
+| **State** | Stateful (builder pattern) | Stateless (each call independent) |
+| **Location** | Local/in-process | Can be distributed |
+| **Composability** | High (method chaining) | Medium (parameter objects) |
+| **Discoverability** | Excellent (IDE autocomplete) | Good (schema-based) |
+| **Type Safety** | Excellent (compile-time) | Good (runtime validation) |
+| **Error Handling** | Synchronous exceptions | Result objects |
+| **Resource Management** | RAII pattern (automatic) | Manual or tool-managed |
+| **Network Serialization** | Not applicable | Required |
+| **Best For** | CLI, scripts, local dev | Agents, distributed, remote |
+
+### Why Both Are Valid
+
+**Fluent API strengths:**
+- Builder pattern allows incremental configuration
+- Automatic resource cleanup (RAII)
+- Type-safe at compile time
+- Great IDE support
+- Easy to read and understand
+
+**Tool-based RPC strengths:**
+- Works across process boundaries
+- Simple serialization (JSON)
+- Standard protocol (compatible with MCP, JSON-RPC)
+- Stateless (easy to scale)
+- Version isolation through KADI
+
+**The solution: Offer both!**
+
+---
+
+## Migration Strategy
+
+### Phase 1: Add Ability Layer (No Breaking Changes)
+
+**Week 1-2:**
+1. Create `kadi-ability.ts`
+2. Add exports to `package.json`
+3. Write tests for tool interface
+4. Update documentation
+
+**Result:**
+- Existing code keeps working (uses `/lib` export)
+- New consumers can choose ability or library
+- No migration required
+
+---
+
+### Phase 2: Update Internal Consumers
+
+**Week 3-4:**
+
+Update kadi-deploy and other consumers to use the fluent API:
+
+```typescript
+// Before (old verbose API)
+const registryCleanup = await setupRegistryIfNeeded(profile);
+try {
+  await deploy(profile, wallet, cert);
+} finally {
+  await registryCleanup?.();
+}
+
+// After (new fluent API)
+await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'prod' })
+  .withLocalImageSupport()
+  .withWallet(wallet)
+  .withCertificate(cert)
+  .execute();
+```
+
+**Result:**
+- Cleaner code
+- Automatic cleanup
+- Better error handling
+- Same functionality
+
+---
+
+### Phase 3: Gradual Adoption
+
+**Month 2:**
+
+As new use cases emerge:
+- **Local/CLI** → Use fluent API from `/lib`
+- **Distributed/Remote** → Use ability interface
+
+**Documentation updates:**
+- Add examples for both patterns
+- Explain when to use each
+- Migration guide for existing code
+
+**Result:**
+- Full ecosystem support
+- Clear patterns established
+- Best practices documented
+
+---
+
+## Benefits & Trade-offs
+
+### Benefits
+
+✅ **Fluent API Preserved**
+- Keep the excellent Pipeline Builder design
+- Best developer experience for local use
+- Type-safe, discoverable, clean
+
+✅ **Distributed Capability Added**
+- Agents can call deployments remotely
+- Standard tool-based interface
+- Works with KADI ecosystem
+
+✅ **Ecosystem Integration**
+- Version management through KADI
+- Ability loading and isolation
+- Compatible with MCP/broker protocols
+
+✅ **Backward Compatibility**
+- Existing code keeps working
+- No forced migration
+- Gradual adoption path
+
+✅ **Resource Management**
+- Automatic cleanup via RAII (fluent API)
+- No manual cleanup needed
+- Fewer bugs from forgotten cleanup
+
+✅ **Flexibility**
+- Choose the right interface for your use case
+- Not locked into one pattern
+- Can mix both in same project
+
+---
+
+### Trade-offs
+
+⚠️ **Slightly More Complex Package**
+- Two entry points (`./` and `./lib`)
+- Need to understand which to use when
+- More documentation needed
+
+**Mitigation:**
+- Clear documentation with examples
+- Decision tree for which interface to use
+- Both are well-designed and intuitive
+
+⚠️ **Two Interfaces to Maintain**
+- Library interface (fluent API)
+- Ability interface (tools)
+- Need to keep both in sync
+
+**Mitigation:**
+- Ability wraps library (single source of truth)
+- Changes to library automatically available in ability
+- Thin wrapper means less maintenance
+
+⚠️ **Learning Curve**
+- Developers need to know both patterns exist
+- When to use fluent vs tools
+
+**Mitigation:**
+- Good defaults (CLI → fluent, agents → tools)
+- Clear documentation and examples
+- Each interface is simple on its own
+
+---
+
+### Overall Assessment
+
+**Score: 8/10**
+
+The dual export pattern is:
+- ✅ **Worth implementing** - benefits outweigh costs
+- ✅ **Proven pattern** - secret-ability demonstrates success
+- ✅ **Best of both worlds** - no compromises on either interface
+- ✅ **Future-proof** - supports both local and distributed use cases
+
+---
+
+## Comparison with secret-ability
+
+### How They Use the Same Pattern
+
+Both use the dual export pattern, but for different domains:
+
+**secret-ability:**
+```typescript
+// Library (fluent API for vault management)
+import { Secrets } from '@kadi.build/secret-ability/lib';
+
+await secrets.init()
+  .ensure('wallet', { type: 'custom', path: './wallet.vault' })
+  .use('wallet');
+
+await secrets.set('KEY', 'value');
+```
+
+**deploy-ability (proposed):**
+```typescript
+// Library (fluent API for deployment)
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+
+await DeploymentPipeline
+  .create({ projectRoot: './', profile: 'production' })
+  .withLocalImageSupport()
+  .execute();
+```
+
+### Lessons Learned from secret-ability
+
+1. **Fluent initializer pattern works great**
+   - secret-ability's `SecretsInitializer` is excellent
+   - Chainable setup, then execute
+   - We're using the same pattern
+
+2. **Tool interface is simple**
+   - Each tool maps to a library method
+   - Thin wrapper, minimal complexity
+   - Easy to maintain
+
+3. **Clear separation of concerns**
+   - Library handles business logic
+   - Ability handles RPC and protocols
+   - Works well in practice
+
+4. **Documentation is key**
+   - Need clear examples for both interfaces
+   - Explain when to use which
+   - Show the connection between them
+
+### Differences in Use Cases
+
+**secret-ability:**
+- Manages vault initialization and lifecycle
+- Secret CRUD operations
+- Vault registry management
+
+**deploy-ability:**
+- Orchestrates deployment pipelines
+- Manages temporary resources (registry, tunnel)
+- Coordinates multiple services
+
+**Both benefit from fluent APIs** because:
+- Complex multi-step processes
+- Resource lifecycle management
+- Clear configuration builders
+- Automatic cleanup needed
+
+---
+
+## FAQ
+
+### "Why not just use fluent API for the ability too?"
+
+**Short answer:** Fluent APIs don't work across process boundaries.
+
+**Long answer:**
+
+Fluent APIs require maintaining state (the builder object):
+
+```typescript
+const pipeline = DeploymentPipeline.create({...}); // State created
+pipeline.withWallet(wallet);                        // State modified
+pipeline.withCertificate(cert);                     // State modified
+await pipeline.execute();                           // State executed
+```
+
+In a distributed system:
+- Each method call might go to a different instance
+- You can't serialize a builder object with all its state
+- The server doesn't maintain session state between calls
+
+Tool-based RPC is stateless:
+```typescript
+await deployAbility.deploy({
+  // Everything in one call
+  profile: 'prod',
+  wallet: wallet,
+  certificate: cert
+});
+```
+
+Each call is independent and self-contained.
+
+---
+
+### "Can I use the fluent API from remote services?"
+
+**Yes, but only if you import the library directly:**
+
+```typescript
+// In a remote agent
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+
+// This works because you're using the library, not the ability
+await DeploymentPipeline.create({...}).execute();
+```
+
+**However:**
+- You lose KADI version isolation
+- Direct npm dependency instead of ability loading
+- Might have version conflicts
+
+**Recommendation:** If you're remote, use the ability interface instead.
+
+---
+
+### "Which interface should I use?"
+
+**Decision tree:**
+
+```
+Are you writing...
+├─ CLI command? → Use fluent API (/lib)
+├─ Local script? → Use fluent API (/lib)
+├─ Agent calling another agent? → Use ability interface (default)
+├─ Broker/MCP integration? → Use ability interface (default)
+└─ Not sure? → Use fluent API if local, ability if distributed
+```
+
+**Rule of thumb:**
+- **Same process** → Fluent API (`/lib`)
+- **Different process** → Ability interface (default)
+
+---
+
+### "Will this break existing code?"
+
+**No! Here's why:**
+
+**For deploy-ability consumers:**
+- Current code imports from default export
+- We're keeping all existing exports in `/lib`
+- Old API remains available
+
+**Example:**
+```typescript
+// Old code (still works!)
+import { loadProfile, setupRegistryIfNeeded } from '@kadi.build/deploy-ability';
+
+// New code (better!)
+import { DeploymentPipeline } from '@kadi.build/deploy-ability/lib';
+```
+
+Both work! No forced migration.
+
+---
+
+### "Do I need to update my code immediately?"
+
+**No, it's optional:**
+
+The dual export pattern means:
+- ✅ Existing code keeps working
+- ✅ New code can use fluent API
+- ✅ Gradual migration possible
+- ✅ No breaking changes
+
+**When to update:**
+- When you want the fluent API benefits
+- When you need remote deployment capability
+- When you're writing new code
+- At your own pace
+
+---
+
+## Conclusion
+
+### Summary
+
+**The dual export pattern enables deploy-ability to be both:**
+1. A KADI ability (tool-based RPC for distributed use)
+2. A fluent API library (for local/CLI use)
+
+**This is possible because:**
+- The ability layer is a thin wrapper around the library
+- Both interfaces serve different, valid use cases
+- secret-ability proves this pattern works
+
+**The Pipeline Builder fluent API is preserved and enhanced:**
+- ✅ Available via `/lib` export
+- ✅ Best-in-class developer experience
+- ✅ Automatic resource management
+- ✅ Type-safe and discoverable
+
+**The ability interface adds new capabilities:**
+- ✅ Distributed deployments
+- ✅ Agent-to-agent communication
+- ✅ KADI ecosystem integration
+- ✅ Standard tool-based protocol
+
+### Recommendation
+
+**Proceed with converting deploy-ability to a KADI ability using the dual export pattern.**
+
+**Implementation priority:**
+1. ✅ Create `kadi-ability.ts` with tool wrappers
+2. ✅ Update `package.json` with dual exports
+3. ✅ Update `index.ts` to export fluent API
+4. ✅ Write comprehensive documentation
+5. ✅ Add examples for both use cases
+6. ✅ Update existing consumers gradually
+
+**Expected outcome:**
+- Best of both worlds
+- No breaking changes
+- Future-proof architecture
+- Happy developers ✨
+
+---
+
+**Document Version:** 1.0
+**Last Updated:** 2025-11-18
+**Author:** KADI Team
+**Status:** Design Proposal - Ready for Implementation