npm - agentic-flow - Versions diffs - 1.9.0 → 1.9.1 - Mend

agentic-flow 1.9.0 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1223) hide show

package/docs/guides/MCP-TROUBLESHOOTING.md DELETED Viewed

@@ -1,1602 +0,0 @@
-# MCP Tools Troubleshooting Guide
-**Version:** 1.0.0
-**Last Updated:** 2025-10-22
-**Coverage:** 4 MCP servers, 233+ tools
----
-## Table of Contents
-1. [Quick Diagnostics](#quick-diagnostics)
-2. [Common Issues Matrix](#common-issues-matrix)
-3. [Per-Server Troubleshooting](#per-server-troubleshooting)
-   - [Claude Flow Issues](#claude-flow-issues)
-   - [AgentDB Issues](#agentdb-issues)
-   - [Flow Nexus Issues](#flow-nexus-issues)
-   - [Agentic Payments Issues](#agentic-payments-issues)
-4. [Diagnostic Commands](#diagnostic-commands)
-5. [Debug Mode](#debug-mode)
-6. [Error Code Reference](#error-code-reference)
-7. [Getting Help](#getting-help)
-8. [FAQ](#faq)
----
-## Quick Diagnostics
-**First Steps (run these in order):**
-```bash
-# 1. Check MCP server installation
-claude mcp list
-# 2. Verify Claude Code version
-claude --version
-# 3. Test basic connectivity
-npx claude-flow@alpha --version
-# 4. Check environment variables
-env | grep -E "(ANTHROPIC|OPENROUTER|GOOGLE)"
-```
-**Expected output:**
-```
-claude-flow (running)
-agentic-flow (optional)
-flow-nexus (optional)
-```
-If any server is missing or stopped, see [MCP Server Not Found](#1-mcp-server-not-found).
----
-## Common Issues Matrix
-| Issue | Symptoms | Cause | Quick Fix | Detailed Section |
-|-------|----------|-------|-----------|------------------|
-| **MCP server not found** | "Server 'X' not available" | Not installed/started | `claude mcp add <server>` | [§3.1](#31-server-not-installed) |
-| **Authentication failed** | "AUTH_REQUIRED" error | No login session | Run login command | [§3.3](#33-flow-nexus-authentication) |
-| **Tool not available** | "Unknown tool" error | Server not started | Restart MCP server | [§3.1](#31-server-not-installed) |
-| **Rate limit exceeded** | "RATE_LIMITED" error | Too many requests | Wait or upgrade tier | [§3.3](#flow-nexus-rate-limits) |
-| **Invalid parameters** | "INVALID_PARAMS" error | Wrong param types | Check tool docs | [§6](#error-code-reference) |
-| **Connection timeout** | No response after 30s | Network/server issue | Check network, restart | [§4.3](#43-network-diagnostics) |
-| **Out of credits** | "INSUFFICIENT_CREDITS" | Low balance | Add credits | [§3.3](#flow-nexus-credit-issues) |
-| **Keypair invalid** | "SIGNATURE_INVALID" error | Wrong private key | Regenerate keypair | [§3.4](#agentic-payments-keypair-issues) |
-| **Database locked** | "SQLITE_BUSY" error | Concurrent access | Wait, retry, or restart | [§3.2](#agentdb-database-issues) |
-| **Sandbox timeout** | Sandbox unresponsive | Long-running code | Increase timeout param | [§3.3](#flow-nexus-sandbox-issues) |
----
-## Per-Server Troubleshooting
-### 3.1 Claude Flow Issues
-**Server installation and basic operations.**
-#### Server Not Installed
-**Symptoms:**
-```
-Error: MCP server 'claude-flow' not found
-```
-**Solutions:**
-1. **Install Claude Flow:**
-   ```bash
-   # Add MCP server
-   claude mcp add claude-flow npx claude-flow@alpha mcp start
-   # Verify installation
-   claude mcp list
-   ```
-2. **Restart Claude Code:**
-   ```bash
-   # Close and reopen Claude Code
-   # Or restart the terminal
-   ```
-3. **Check npm installation:**
-   ```bash
-   # Verify claude-flow is installed
-   npm list -g | grep claude-flow
-   # If missing, install globally
-   npm install -g @ruvnet/claude-flow@alpha
-   ```
-#### Server Not Starting
-**Symptoms:**
-```
-MCP server 'claude-flow' failed to start
-Timeout waiting for server initialization
-```
-**Solutions:**
-1. **Check Node.js version:**
-   ```bash
-   node --version  # Requires v18+ or v20+
-   ```
-2. **Clear npm cache:**
-   ```bash
-   npm cache clean --force
-   npm install -g @ruvnet/claude-flow@alpha
-   ```
-3. **Check for port conflicts:**
-   ```bash
-   # Claude Flow uses ephemeral ports
-   # No manual port configuration needed
-   ```
-4. **View detailed logs:**
-   ```bash
-   # Enable debug mode (see §5)
-   DEBUG=claude-flow:* npx claude-flow@alpha mcp start
-   ```
-#### Swarm Initialization Failures
-**Symptoms:**
-```javascript
-// Returns error
-mcp__claude-flow__swarm_init({ topology: 'mesh' });
-// Error: Failed to initialize swarm
-```
-**Solutions:**
-1. **Check topology parameter:**
-   ```javascript
-   // ✅ Valid topologies
-   mcp__claude-flow__swarm_init({ topology: 'mesh' });
-   mcp__claude-flow__swarm_init({ topology: 'hierarchical' });
-   mcp__claude-flow__swarm_init({ topology: 'ring' });
-   mcp__claude-flow__swarm_init({ topology: 'star' });
-   // ❌ Invalid
-   mcp__claude-flow__swarm_init({ topology: 'custom' }); // Not supported
-   ```
-2. **Check maxAgents limit:**
-   ```javascript
-   // ✅ Within limits
-   mcp__claude-flow__swarm_init({
-     topology: 'mesh',
-     maxAgents: 8  // Default: 8, Max: 100
-   });
-   // ❌ Exceeds limit
-   mcp__claude-flow__swarm_init({
-     topology: 'mesh',
-     maxAgents: 200  // Error: exceeds max
-   });
-   ```
-3. **Destroy existing swarm:**
-   ```javascript
-   // Get swarm ID
-   const status = mcp__claude-flow__swarm_status();
-   // Destroy if exists
-   if (status.swarmId) {
-     mcp__claude-flow__swarm_destroy({
-       swarmId: status.swarmId
-     });
-   }
-   // Retry initialization
-   mcp__claude-flow__swarm_init({ topology: 'mesh' });
-   ```
-#### Memory Operations Failing
-**Symptoms:**
-```javascript
-// No error, but memory not persisting
-mcp__claude-flow__memory_usage({
-  action: 'store',
-  key: 'test',
-  value: 'data'
-});
-// Returns empty
-mcp__claude-flow__memory_usage({
-  action: 'retrieve',
-  key: 'test'
-});
-```
-**Solutions:**
-1. **Check action parameter:**
-   ```javascript
-   // ✅ Valid actions
-   'store', 'retrieve', 'list', 'delete', 'search'
-   // ❌ Invalid
-   'save', 'get', 'find'  // Use correct action names
-   ```
-2. **Verify namespace:**
-   ```javascript
-   // Namespaces are isolated
-   mcp__claude-flow__memory_usage({
-     action: 'store',
-     key: 'test',
-     namespace: 'project-a',  // Stored in namespace
-     value: 'data'
-   });
-   // Won't find it in default namespace
-   mcp__claude-flow__memory_usage({
-     action: 'retrieve',
-     key: 'test'  // Uses 'default' namespace
-   });
-   // ✅ Correct retrieval
-   mcp__claude-flow__memory_usage({
-     action: 'retrieve',
-     key: 'test',
-     namespace: 'project-a'  // Match the namespace
-   });
-   ```
-3. **Check value serialization:**
-   ```javascript
-   // ✅ Store objects as JSON strings
-   mcp__claude-flow__memory_usage({
-     action: 'store',
-     key: 'config',
-     value: JSON.stringify({ setting: 'value' })
-   });
-   // ✅ Retrieve and parse
-   const result = mcp__claude-flow__memory_usage({
-     action: 'retrieve',
-     key: 'config'
-   });
-   const config = JSON.parse(result.value);
-   ```
----
-### 3.2 AgentDB Issues
-**Agent memory, learning, and database operations.**
-#### Database Initialization
-**Symptoms:**
-```bash
-Error: AgentDB not initialized
-SQLITE_CANTOPEN: unable to open database file
-```
-**Solutions:**
-1. **Initialize database:**
-   ```bash
-   # Create .agentdb directory
-   mkdir -p .agentdb
-   # Initialize with CLI
-   npx agentdb init
-   # Or set environment variable
-   export AGENTDB_PATH="$(pwd)/.agentdb"
-   ```
-2. **Check permissions:**
-   ```bash
-   # Verify write permissions
-   ls -la .agentdb/
-   # Fix permissions if needed
-   chmod 755 .agentdb
-   chmod 644 .agentdb/*.db
-   ```
-3. **Check disk space:**
-   ```bash
-   df -h .
-   # Ensure at least 100MB free
-   ```
-#### Database Locked
-**Symptoms:**
-```
-SQLITE_BUSY: database is locked
-Error: Cannot acquire lock after 5 seconds
-```
-**Solutions:**
-1. **Close other connections:**
-   ```bash
-   # Find processes using AgentDB
-   lsof .agentdb/*.db
-   # Kill if necessary (use with caution)
-   kill <PID>
-   ```
-2. **Wait and retry:**
-   ```javascript
-   // Implement retry logic
-   async function retryQuery(fn, retries = 3) {
-     for (let i = 0; i < retries; i++) {
-       try {
-         return await fn();
-       } catch (error) {
-         if (error.code === 'SQLITE_BUSY' && i < retries - 1) {
-           await new Promise(resolve => setTimeout(resolve, 1000 * (i + 1)));
-           continue;
-         }
-         throw error;
-       }
-     }
-   }
-   // Usage
-   await retryQuery(() =>
-     mcp__agentdb__causal_query({ limit: 10 })
-   );
-   ```
-3. **Enable WAL mode (if using CLI):**
-   ```bash
-   # Write-Ahead Logging for better concurrency
-   npx agentdb config set wal_mode=ON
-   ```
-#### Causal Memory Issues
-**Symptoms:**
-```javascript
-// Adding edge fails
-mcp__agentdb__causal_add_edge({
-  from: 'event1',
-  to: 'event2',
-  metadata: {}
-});
-// Error: Invalid edge data
-```
-**Solutions:**
-1. **Validate edge parameters:**
-   ```javascript
-   // ✅ Valid edge
-   mcp__agentdb__causal_add_edge({
-     from: 'user_login',           // Source event
-     to: 'load_dashboard',         // Target event
-     relation: 'causes',           // Relationship type
-     confidence: 0.95,             // Optional: 0-1
-     metadata: {                   // Optional
-       latency_ms: 120,
-       user_id: 'abc123'
-     }
-   });
-   // ❌ Invalid
-   mcp__agentdb__causal_add_edge({
-     from: '',                     // Empty string not allowed
-     to: null,                     // Null not allowed
-     confidence: 1.5               // Must be 0-1
-   });
-   ```
-2. **Check for circular dependencies:**
-   ```javascript
-   // Detect cycles
-   const cycles = mcp__agentdb__causal_detect_cycles();
-   if (cycles.length > 0) {
-     console.log('Circular dependencies found:', cycles);
-     // Remove or restructure edges
-   }
-   ```
-3. **Query before adding:**
-   ```javascript
-   // Check if edge already exists
-   const existing = mcp__agentdb__causal_query({
-     from: 'event1',
-     to: 'event2',
-     limit: 1
-   });
-   if (!existing.edges || existing.edges.length === 0) {
-     mcp__agentdb__causal_add_edge({ ... });
-   }
-   ```
-#### Reflexion Memory Issues
-**Symptoms:**
-```javascript
-// Self-critique not working
-mcp__agentdb__reflexion_add_trajectory({
-  task: 'solve_problem',
-  actions: [...],
-  outcome: 'failed'
-});
-// No error, but no learning improvement
-```
-**Solutions:**
-1. **Provide detailed trajectory:**
-   ```javascript
-   // ✅ Complete trajectory with context
-   mcp__agentdb__reflexion_add_trajectory({
-     task: 'implement_authentication',
-     actions: [
-       { step: 1, action: 'research_patterns', duration_ms: 5000 },
-       { step: 2, action: 'write_code', duration_ms: 15000 },
-       { step: 3, action: 'test_implementation', duration_ms: 8000 }
-     ],
-     outcome: 'success',           // 'success' | 'failed' | 'partial'
-     reflection: 'Should have written tests first',
-     learned_patterns: ['tdd', 'auth_best_practices'],
-     metadata: {
-       complexity: 'medium',
-       confidence: 0.8
-     }
-   });
-   ```
-2. **Query learning history:**
-   ```javascript
-   // Check what patterns were learned
-   const learnings = mcp__agentdb__reflexion_query({
-     task: 'implement_authentication',
-     outcome: 'success',
-     limit: 10
-   });
-   console.log('Learned from past:', learnings);
-   ```
-3. **Run nightly learner:**
-   ```javascript
-   // Discover patterns from trajectories
-   const patterns = mcp__agentdb__nightly_discover_patterns({
-     min_frequency: 3,          // Minimum occurrences
-     min_confidence: 0.7,       // Minimum confidence
-     time_window_hours: 24      // Look back period
-   });
-   console.log('Discovered patterns:', patterns);
-   ```
-#### Skill Library Issues
-**Symptoms:**
-```javascript
-// Skill not found
-mcp__agentdb__skill_retrieve({ skill_id: 'my-skill' });
-// Error: Skill not found
-```
-**Solutions:**
-1. **List available skills:**
-   ```javascript
-   // See all stored skills
-   const skills = mcp__agentdb__skill_list({
-     category: 'all',
-     limit: 100
-   });
-   console.log('Available skills:', skills);
-   ```
-2. **Store skill with complete metadata:**
-   ```javascript
-   // ✅ Properly formatted skill
-   mcp__agentdb__skill_store({
-     skill_id: 'authentication_handler',
-     name: 'User Authentication Handler',
-     description: 'Secure user login with JWT',
-     code: `
-       async function authenticate(credentials) {
-         // Implementation
-       }
-     `,
-     category: 'security',
-     tags: ['auth', 'jwt', 'security'],
-     usage_count: 0,
-     success_rate: 0.0,
-     metadata: {
-       language: 'javascript',
-       dependencies: ['jsonwebtoken', 'bcrypt'],
-       author: 'system'
-     }
-   });
-   ```
-3. **Update usage metrics:**
-   ```javascript
-   // Track skill performance
-   mcp__agentdb__skill_update_metrics({
-     skill_id: 'authentication_handler',
-     increment_usage: true,
-     success: true,              // or false if failed
-     execution_time_ms: 150
-   });
-   ```
----
-### 3.3 Flow Nexus Issues
-**Cloud execution, authentication, and sandbox management.**
-#### Flow Nexus Authentication
-**Symptoms:**
-```javascript
-mcp__flow-nexus__sandbox_create({ template: 'node' });
-// Error: AUTH_REQUIRED - Please login first
-```
-**Solutions:**
-1. **Register (first-time users):**
-   ```javascript
-   // One-time registration
-   mcp__flow-nexus__user_register({
-     email: 'user@example.com',
-     password: 'secure-password-123',
-     full_name: 'John Doe'  // Optional
-   });
-   // Check email for verification link
-   ```
-2. **Verify email:**
-   ```javascript
-   // Click link in email, or use token
-   mcp__flow-nexus__user_verify_email({
-     token: 'verification-token-from-email'
-   });
-   ```
-3. **Login (each session):**
-   ```javascript
-   // Login after verification
-   mcp__flow-nexus__user_login({
-     email: 'user@example.com',
-     password: 'secure-password-123'
-   });
-   // Session token is stored automatically
-   ```
-4. **Check authentication status:**
-   ```javascript
-   const status = mcp__flow-nexus__auth_status({
-     detailed: true
-   });
-   console.log('Authenticated:', status.authenticated);
-   console.log('User ID:', status.user_id);
-   console.log('Tier:', status.tier);
-   ```
-#### Flow Nexus Rate Limits
-**Symptoms:**
-```javascript
-// After many requests
-mcp__flow-nexus__sandbox_create({ template: 'node' });
-// Error: RATE_LIMITED - Too many requests
-// { retry_after_ms: 60000 }
-```
-**Solutions:**
-1. **Implement retry logic:**
-   ```javascript
-   async function retryWithBackoff(fn, maxRetries = 3) {
-     for (let i = 0; i < maxRetries; i++) {
-       try {
-         return await fn();
-       } catch (error) {
-         if (error.code === 'RATE_LIMITED') {
-           const delay = error.details?.retry_after_ms || 1000 * (i + 1);
-           console.log(`Rate limited, waiting ${delay}ms...`);
-           await new Promise(resolve => setTimeout(resolve, delay));
-           continue;
-         }
-         throw error;
-       }
-     }
-   }
-   // Usage
-   await retryWithBackoff(() =>
-     mcp__flow-nexus__sandbox_create({ template: 'node' })
-   );
-   ```
-2. **Check current limits:**
-   ```javascript
-   const stats = mcp__flow-nexus__user_stats({
-     user_id: 'your-user-id'
-   });
-   console.log('Requests this hour:', stats.requests_this_hour);
-   console.log('Limit:', stats.rate_limit);
-   console.log('Resets at:', stats.rate_limit_reset);
-   ```
-3. **Upgrade tier:**
-   ```javascript
-   // Upgrade to pro tier (higher limits)
-   mcp__flow-nexus__user_upgrade({
-     user_id: 'your-user-id',
-     tier: 'pro'  // or 'enterprise'
-   });
-   ```
-4. **Batch operations:**
-   ```javascript
-   // ❌ INEFFICIENT: Create sandbox per task
-   for (const task of tasks) {
-     const sandbox = mcp__flow-nexus__sandbox_create({ ... });
-     mcp__flow-nexus__sandbox_execute({ ... });
-     mcp__flow-nexus__sandbox_delete({ ... });
-   }
-   // ✅ EFFICIENT: Reuse sandbox
-   const sandbox = mcp__flow-nexus__sandbox_create({ template: 'node' });
-   for (const task of tasks) {
-     mcp__flow-nexus__sandbox_execute({
-       sandbox_id: sandbox.data.sandbox_id,
-       code: task.code
-     });
-   }
-   mcp__flow-nexus__sandbox_delete({ sandbox_id: sandbox.data.sandbox_id });
-   ```
-#### Flow Nexus Credit Issues
-**Symptoms:**
-```javascript
-mcp__flow-nexus__neural_train({ config: {...}, tier: 'large' });
-// Error: INSUFFICIENT_CREDITS - Balance too low
-```
-**Solutions:**
-1. **Check balance:**
-   ```javascript
-   const balance = mcp__flow-nexus__check_balance();
-   console.log('Current balance:', balance.credits);
-   console.log('Reserved:', balance.reserved_credits);
-   console.log('Available:', balance.available_credits);
-   ```
-2. **Add credits:**
-   ```javascript
-   // Create payment link
-   const payment = mcp__flow-nexus__create_payment_link({
-     amount: 50.00  // $50 USD (minimum $10)
-   });
-   console.log('Payment URL:', payment.checkout_url);
-   // Open URL in browser to complete payment
-   ```
-3. **Configure auto-refill:**
-   ```javascript
-   // Auto-add credits when low
-   mcp__flow-nexus__configure_auto_refill({
-     enabled: true,
-     threshold: 10,    // Refill when below 10 credits
-     amount: 25.00     // Add $25 each time
-   });
-   ```
-4. **Check transaction history:**
-   ```javascript
-   const history = mcp__flow-nexus__get_payment_history({
-     limit: 10
-   });
-   console.log('Recent transactions:', history);
-   ```
-#### Flow Nexus Sandbox Issues
-**Symptoms:**
-```javascript
-// Sandbox creation hangs
-mcp__flow-nexus__sandbox_create({ template: 'node' });
-// ... no response after 60 seconds
-```
-**Solutions:**
-1. **Increase timeout:**
-   ```javascript
-   // Default timeout is 3600s (1 hour)
-   mcp__flow-nexus__sandbox_create({
-     template: 'node',
-     timeout: 7200  // 2 hours
-   });
-   ```
-2. **Check sandbox status:**
-   ```javascript
-   // List all sandboxes
-   const sandboxes = mcp__flow-nexus__sandbox_list({
-     status: 'all'  // 'running' | 'stopped' | 'all'
-   });
-   console.log('Active sandboxes:', sandboxes);
-   // Get specific sandbox
-   const status = mcp__flow-nexus__sandbox_status({
-     sandbox_id: 'sandbox-abc123'
-   });
-   console.log('Status:', status.state);
-   ```
-3. **Delete stuck sandboxes:**
-   ```javascript
-   // Force delete unresponsive sandbox
-   mcp__flow-nexus__sandbox_delete({
-     sandbox_id: 'sandbox-abc123'
-   });
-   ```
-4. **Use lighter templates:**
-   ```javascript
-   // ❌ Heavy template (slow start)
-   mcp__flow-nexus__sandbox_create({ template: 'nextjs' });
-   // ✅ Light template (fast start)
-   mcp__flow-nexus__sandbox_create({ template: 'base' });
-   // Then install only what you need
-   ```
-5. **Check sandbox logs:**
-   ```javascript
-   const logs = mcp__flow-nexus__sandbox_logs({
-     sandbox_id: 'sandbox-abc123',
-     lines: 100
-   });
-   console.log('Logs:', logs);
-   ```
----
-### 3.4 Agentic Payments Issues
-**Payment authorization, mandates, and cryptographic operations.**
-#### Agentic Payments Keypair Issues
-**Symptoms:**
-```javascript
-mcp__agentic-payments__sign_mandate({ mandate: {...}, private_key: 'key' });
-// Error: SIGNATURE_INVALID - Invalid private key format
-```
-**Solutions:**
-1. **Generate valid keypair:**
-   ```javascript
-   // Generate Ed25519 keypair
-   const identity = mcp__agentic-payments__generate_agent_identity({
-     include_private_key: true  // IMPORTANT: Store securely!
-   });
-   console.log('Public Key:', identity.public_key);
-   console.log('Private Key:', identity.private_key);
-   // ⚠️ SECURITY: Store private_key in secure vault
-   // NEVER commit to version control
-   // NEVER log in production
-   ```
-2. **Verify key format:**
-   ```javascript
-   // Private keys are 64-byte hex strings (128 chars)
-   const privateKey = identity.private_key;
-   if (!/^[0-9a-f]{128}$/i.test(privateKey)) {
-     console.error('Invalid private key format');
-   }
-   // Public keys are 32-byte hex strings (64 chars)
-   const publicKey = identity.public_key;
-   if (!/^[0-9a-f]{64}$/i.test(publicKey)) {
-     console.error('Invalid public key format');
-   }
-   ```
-3. **Store securely:**
-   ```javascript
-   // ✅ SECURE: Use environment variables
-   process.env.AGENT_PRIVATE_KEY = identity.private_key;
-   // ✅ SECURE: Use secrets manager
-   await secretsManager.store('agent-private-key', identity.private_key);
-   // ❌ INSECURE: Plain file
-   fs.writeFileSync('private-key.txt', identity.private_key);
-   // ❌ INSECURE: Version control
-   git.add('keys.json');  // NEVER DO THIS
-   ```
-#### Mandate Creation Issues
-**Symptoms:**
-```javascript
-mcp__agentic-payments__create_active_mandate({
-  agent: 'bot@example.com',
-  holder: 'user-id',
-  amount: 100,
-  currency: 'USD',
-  period: 'daily'
-});
-// Error: INVALID_PARAMS - Missing required field
-```
-**Solutions:**
-1. **Include all required fields:**
-   ```javascript
-   // ✅ Complete mandate
-   const mandate = mcp__agentic-payments__create_active_mandate({
-     agent: 'shopping-bot@agentics',      // REQUIRED
-     holder: 'user-public-key-abc123',    // REQUIRED
-     amount: 12000,                       // REQUIRED (minor units)
-     currency: 'USD',                     // REQUIRED
-     period: 'daily',                     // REQUIRED
-     kind: 'intent',                      // REQUIRED ('intent' | 'cart')
-     expires_at: '2025-12-31T23:59:59Z',  // Optional (ISO8601)
-     merchant_allow: [                    // Optional
-       'amazon.com',
-       'bestbuy.com'
-     ],
-     merchant_block: []                   // Optional
-   });
-   ```
-2. **Use correct amount format:**
-   ```javascript
-   // ✅ CORRECT: Minor units (cents)
-   amount: 12000  // $120.00
-   // ❌ WRONG: Major units (dollars)
-   amount: 120.00  // Will be interpreted as $1.20
-   // Conversion helper
-   const dollarsToMinorUnits = (dollars) => Math.round(dollars * 100);
-   amount: dollarsToMinorUnits(120.00)  // 12000
-   ```
-3. **Validate period:**
-   ```javascript
-   // ✅ Valid periods
-   period: 'single'   // One-time payment
-   period: 'daily'    // $X per day
-   period: 'weekly'   // $X per week
-   period: 'monthly'  // $X per month
-   // ❌ Invalid
-   period: 'yearly'   // Not supported
-   period: 'hourly'   // Not supported
-   ```
-4. **Validate kind:**
-   ```javascript
-   // ✅ Intent-based (high-level purchase intent)
-   kind: 'intent'
-   // ✅ Cart-based (specific line items)
-   kind: 'cart'
-   // ❌ Invalid
-   kind: 'subscription'  // Not supported
-   ```
-#### Signature Verification Issues
-**Symptoms:**
-```javascript
-mcp__agentic-payments__verify_mandate({ signed_mandate: {...} });
-// Error: SIGNATURE_INVALID - Signature verification failed
-```
-**Solutions:**
-1. **Sign mandate correctly:**
-   ```javascript
-   // Step 1: Create mandate
-   const mandate = mcp__agentic-payments__create_active_mandate({
-     agent: 'bot@example.com',
-     holder: identity.public_key,  // Use public key
-     amount: 10000,
-     currency: 'USD',
-     period: 'single',
-     kind: 'intent'
-   });
-   // Step 2: Sign with private key
-   const signed = mcp__agentic-payments__sign_mandate({
-     mandate: mandate,
-     private_key: identity.private_key  // Use private key
-   });
-   // Step 3: Verify signature
-   const verification = mcp__agentic-payments__verify_mandate({
-     signed_mandate: signed,
-     check_guards: true  // Also check expiration
-   });
-   console.log('Valid:', verification.valid);
-   ```
-2. **Check guard conditions:**
-   ```javascript
-   // Mandate may be valid but expired
-   const verification = mcp__agentic-payments__verify_mandate({
-     signed_mandate: signed,
-     check_guards: true  // Checks expiration, revocation
-   });
-   if (!verification.valid) {
-     console.log('Reason:', verification.reason);
-     if (verification.reason === 'expired') {
-       console.log('Mandate expired at:', verification.expired_at);
-     }
-     if (verification.reason === 'revoked') {
-       console.log('Revoked at:', verification.revoked_at);
-       console.log('Reason:', verification.revocation_reason);
-     }
-   }
-   ```
-3. **Check revocation status:**
-   ```javascript
-   // List all revoked mandates
-   const revocations = mcp__agentic-payments__list_revocations();
-   console.log('Revoked mandates:', revocations);
-   // Check specific mandate
-   const isRevoked = revocations.some(r =>
-     r.mandate_id === signed.mandate_id
-   );
-   if (isRevoked) {
-     console.log('Mandate was revoked');
-   }
-   ```
----
-## 4. Diagnostic Commands
-### 4.1 System Diagnostics
-**Check overall system health:**
-```bash
-# 1. Claude Code version
-claude --version
-# Expected: v1.x.x or higher
-# 2. Node.js version
-node --version
-# Expected: v18.x.x or v20.x.x
-# 3. npm version
-npm --version
-# Expected: v9.x.x or higher
-# 4. Available disk space
-df -h .
-# Expected: At least 1GB free
-# 5. Memory available
-free -h
-# Expected: At least 512MB free
-# 6. Network connectivity
-ping -c 3 api.anthropic.com
-# Expected: 0% packet loss
-```
-### 4.2 MCP Server Diagnostics
-**Check MCP server health:**
-```bash
-# 1. List installed servers
-claude mcp list
-# 2. Check server status
-claude mcp status claude-flow
-claude mcp status flow-nexus
-claude mcp status agentic-flow
-# 3. Restart specific server
-claude mcp restart claude-flow
-# 4. Restart all servers
-claude mcp restart --all
-# 5. View server logs
-claude mcp logs claude-flow --tail 50
-# 6. Test server connectivity
-npx claude-flow@alpha --version
-npx flow-nexus@latest --version
-```
-### 4.3 Network Diagnostics
-**Check network and API connectivity:**
-```bash
-# 1. Test API endpoints
-curl -I https://api.anthropic.com
-curl -I https://flow-nexus.ruv.io
-# 2. Check DNS resolution
-nslookup api.anthropic.com
-nslookup flow-nexus.ruv.io
-# 3. Test with proxy (if using one)
-export HTTPS_PROXY=http://proxy.example.com:8080
-curl -I https://api.anthropic.com
-# 4. Check SSL certificates
-openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com
-# 5. Test websocket connection (for real-time features)
-wscat -c wss://flow-nexus.ruv.io/ws
-```
-### 4.4 Database Diagnostics
-**Check AgentDB health:**
-```bash
-# 1. Verify database files exist
-ls -lh .agentdb/*.db
-# 2. Check database integrity
-sqlite3 .agentdb/agentdb.db "PRAGMA integrity_check;"
-# Expected: ok
-# 3. Check database size
-du -sh .agentdb/
-# 4. List tables
-sqlite3 .agentdb/agentdb.db ".tables"
-# 5. Check table counts
-sqlite3 .agentdb/agentdb.db "
-  SELECT 'causal_edges' as table_name, COUNT(*) FROM causal_edges
-  UNION ALL
-  SELECT 'reflexion_trajectories', COUNT(*) FROM reflexion_trajectories
-  UNION ALL
-  SELECT 'skill_library', COUNT(*) FROM skill_library;
-"
-# 6. Vacuum database (optimize)
-sqlite3 .agentdb/agentdb.db "VACUUM;"
-```
----
-## 5. Debug Mode
-### 5.1 Enable Debug Logging
-**Environment variables:**
-```bash
-# Claude Flow debug mode
-export DEBUG=claude-flow:*
-export CLAUDE_FLOW_VERBOSE=true
-# Flow Nexus debug mode
-export FLOW_NEXUS_DEBUG=true
-export FLOW_NEXUS_LOG_LEVEL=debug
-# AgentDB debug mode
-export AGENTDB_DEBUG=true
-export AGENTDB_LOG_SQL=true
-# Node.js debug mode
-export NODE_DEBUG=*
-```
-### 5.2 Debug Tool Calls
-**Test individual tools with verbose output:**
-```javascript
-// Enable debug before calling tools
-process.env.MCP_DEBUG = 'true';
-process.env.MCP_VERBOSE = 'true';
-// Test tool call
-const result = mcp__claude-flow__swarm_init({
-  topology: 'mesh',
-  maxAgents: 8
-});
-// Expected debug output:
-// [MCP] Connecting to server: claude-flow
-// [MCP] Server connected successfully
-// [MCP] Calling tool: swarm_init
-// [MCP] Parameters: {"topology":"mesh","maxAgents":8}
-// [MCP] Request sent, waiting for response...
-// [MCP] Response received in 45ms
-// [MCP] Response: {"success":true,"swarmId":"abc123"}
-```
-### 5.3 Capture Network Logs
-**Monitor MCP protocol communication:**
-```bash
-# 1. Install mitmproxy (optional)
-pip install mitmproxy
-# 2. Start proxy
-mitmweb -p 8080
-# 3. Configure Claude Code to use proxy
-export HTTP_PROXY=http://localhost:8080
-export HTTPS_PROXY=http://localhost:8080
-# 4. Open http://localhost:8081 to view traffic
-# 5. Run MCP commands
-# All traffic will be visible in mitmweb
-```
-### 5.4 Debug Sandbox Execution
-**Test sandbox code step-by-step:**
-```javascript
-// 1. Create sandbox with verbose logging
-const sandbox = mcp__flow-nexus__sandbox_create({
-  template: 'node',
-  name: 'debug-sandbox',
-  env_vars: {
-    DEBUG: '*',
-    NODE_ENV: 'development'
-  }
-});
-// 2. Execute with capture_output
-const result = mcp__flow-nexus__sandbox_execute({
-  sandbox_id: sandbox.data.sandbox_id,
-  code: `
-    console.log('Debug: Starting execution');
-    console.error('Debug: Error stream test');
-    process.stdout.write('Debug: stdout test\\n');
-    process.stderr.write('Debug: stderr test\\n');
-    console.log('Debug: Completed');
-  `,
-  capture_output: true  // Capture stdout/stderr
-});
-console.log('Output:', result.output);
-console.log('Errors:', result.errors);
-// 3. Check sandbox logs
-const logs = mcp__flow-nexus__sandbox_logs({
-  sandbox_id: sandbox.data.sandbox_id,
-  lines: 100
-});
-console.log('Full logs:', logs);
-// 4. Cleanup
-mcp__flow-nexus__sandbox_delete({
-  sandbox_id: sandbox.data.sandbox_id
-});
-```
----
-## 6. Error Code Reference
-### 6.1 Authentication Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `AUTH_REQUIRED` | No authentication session | Run login command |
-| `AUTH_EXPIRED` | Session token expired | Login again |
-| `AUTH_INVALID` | Invalid credentials | Check email/password |
-| `EMAIL_NOT_VERIFIED` | Email verification pending | Check email, click verification link |
-| `INVALID_TOKEN` | Bad verification/reset token | Request new token |
-### 6.2 Parameter Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `INVALID_PARAMS` | Wrong parameter types/values | Check tool documentation |
-| `MISSING_PARAM` | Required parameter not provided | Add missing parameter |
-| `INVALID_TOPOLOGY` | Unsupported swarm topology | Use: mesh, hierarchical, ring, star |
-| `INVALID_TEMPLATE` | Unknown sandbox template | Use: node, python, react, nextjs, base |
-| `INVALID_AMOUNT` | Payment amount out of range | Check minimum/maximum limits |
-### 6.3 Resource Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `RATE_LIMITED` | Too many requests | Wait, then retry |
-| `INSUFFICIENT_CREDITS` | Low balance | Add credits |
-| `QUOTA_EXCEEDED` | Exceeded usage quota | Upgrade tier or wait for reset |
-| `SANDBOX_LIMIT` | Too many active sandboxes | Delete unused sandboxes |
-| `MEMORY_LIMIT` | Memory usage too high | Reduce data size or upgrade |
-### 6.4 Server Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `SERVER_ERROR` | Internal server error | Retry later, report if persists |
-| `SERVICE_UNAVAILABLE` | Server temporarily down | Wait and retry |
-| `TIMEOUT` | Request took too long | Increase timeout or simplify request |
-| `CONNECTION_FAILED` | Cannot connect to server | Check network, restart server |
-| `DATABASE_ERROR` | Database operation failed | Check disk space, restart |
-### 6.5 Database Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `SQLITE_BUSY` | Database locked | Wait and retry, close other connections |
-| `SQLITE_CANTOPEN` | Cannot open database | Check permissions and path |
-| `SQLITE_CORRUPT` | Database corrupted | Restore from backup |
-| `DISK_FULL` | No disk space | Free up space |
-| `CONSTRAINT_VIOLATION` | Unique constraint failed | Check for duplicates |
-### 6.6 Cryptographic Errors
-| Code | Description | Solution |
-|------|-------------|----------|
-| `SIGNATURE_INVALID` | Signature verification failed | Check private key, regenerate if needed |
-| `KEYPAIR_MISMATCH` | Public key doesn't match private | Regenerate keypair |
-| `MANDATE_EXPIRED` | Mandate past expiration | Create new mandate |
-| `MANDATE_REVOKED` | Mandate was revoked | Create new mandate |
-| `CONSENSUS_FAILED` | Multi-agent consensus failed | Check agent keys, retry |
----
-## 7. Getting Help
-### 7.1 GitHub Issues
-**Report bugs or request features:**
-- **Claude Flow:** https://github.com/ruvnet/claude-flow/issues
-- **Flow Nexus:** https://github.com/ruvnet/flow-nexus/issues
-- **AgentDB:** https://github.com/ruvnet/agentic-flow/issues
-**When reporting issues, include:**
-1. **Environment:**
-   ```
-   OS: [e.g., macOS 14.1, Ubuntu 22.04]
-   Node.js: [e.g., v20.10.0]
-   Claude Code: [e.g., v1.2.0]
-   MCP Server: [e.g., claude-flow@alpha]
-   ```
-2. **Steps to reproduce:**
-   ```
-   1. Run command: mcp__claude-flow__swarm_init({ topology: 'mesh' })
-   2. Observe error: ...
-   3. Expected: swarm initialized successfully
-   ```
-3. **Error output:**
-   ```
-   Error: ...
-   Stack trace: ...
-   ```
-4. **Debug logs:**
-   ```bash
-   DEBUG=* npx claude-flow@alpha mcp start
-   # Include output
-   ```
-### 7.2 Documentation
-**Reference documentation:**
-- **Main docs:** `/workspaces/agentic-flow/docs/guides/MCP-TOOLS.md`
-- **Quick start:** `/workspaces/agentic-flow/docs/guides/MCP-QUICKSTART.md`
-- **Authentication:** `/workspaces/agentic-flow/docs/guides/MCP-AUTHENTICATION.md`
-- **Examples:** `/workspaces/agentic-flow/docs/guides/MCP-EXAMPLES.md`
-- **AgentDB CLI:** `/workspaces/agentic-flow/docs/agentdb/CLI_GUIDE.md`
-- **Architecture:** `/workspaces/agentic-flow/docs/mcp-tools-architecture.md`
-### 7.3 Community Support
-**Get help from the community:**
-- **Discord:** Join the Claude Flow community (link in GitHub README)
-- **Stack Overflow:** Tag questions with `claude-flow`, `mcp-tools`, `agentdb`
-- **GitHub Discussions:** https://github.com/ruvnet/claude-flow/discussions
-### 7.4 Professional Support
-**For enterprise support:**
-- **Email:** support@ruv.io
-- **Flow Nexus Platform:** https://flow-nexus.ruv.io/support
-- **Enterprise Plans:** Contact for SLA-backed support
----
-## 8. FAQ
-### 8.1 Installation & Setup
-**Q: Do I need all 4 MCP servers?**
-A: No. Start with Claude Flow (core orchestration). Add others as needed:
-- **Flow Nexus:** Cloud execution, sandboxes (requires registration)
-- **Agentic Payments:** Payment authorization (requires keypair)
-- **AgentDB:** Advanced memory (included in Claude Flow, but can be standalone)
-**Q: Why is claude-flow@alpha instead of latest?**
-A: The alpha release includes cutting-edge features. Use `@latest` for stable releases.
-**Q: Can I use MCP tools without Claude Code?**
-A: Technically yes (with MCP SDK), but Claude Code provides the best integration.
----
-**Q: What's the difference between claude-flow and flow-nexus?**
-A:
-- **Claude Flow:** Local orchestration, no auth, free
-- **Flow Nexus:** Cloud-based, auth required, free tier + paid
----
-### 8.2 Authentication & Security
-**Q: Is my Flow Nexus password secure?**
-A: Yes. Passwords are hashed with bcrypt (industry standard). Never stored in plaintext.
----
-**Q: How do I rotate my agent identity keypair?**
-A:
-```javascript
-// 1. Generate new keypair
-const newIdentity = mcp__agentic-payments__generate_agent_identity({
-  include_private_key: true
-});
-// 2. Revoke old mandates
-mcp__agentic-payments__revoke_mandate({
-  mandate_id: 'old-mandate-id',
-  reason: 'Keypair rotation'
-});
-// 3. Create new mandates with new keypair
-mcp__agentic-payments__create_active_mandate({
-  holder: newIdentity.public_key,
-  // ... other params
-});
-// 4. Update stored keypair
-// Store newIdentity.private_key securely
-```
----
-**Q: Can I share my private key between agents?**
-A: **NO.** Each agent should have its own keypair. Sharing compromises security.
----
-### 8.3 Performance & Optimization
-**Q: Why is sandbox creation slow?**
-A: Sandboxes provision cloud resources. Use lighter templates or reuse sandboxes:
-```javascript
-// ❌ SLOW: Heavy template
-mcp__flow-nexus__sandbox_create({ template: 'nextjs' });
-// ✅ FAST: Light template
-mcp__flow-nexus__sandbox_create({ template: 'base' });
-```
----
-**Q: How can I reduce API costs?**
-A:
-1. **Reuse sandboxes** instead of creating new ones
-2. **Batch operations** (store multiple items at once)
-3. **Use caching** (check memory before API calls)
-4. **Optimize swarm size** (use minimum agents needed)
----
-**Q: What's the fastest swarm topology?**
-A: Depends on use case:
-- **Mesh:** Best for peer-to-peer communication
-- **Star:** Best for centralized coordination
-- **Hierarchical:** Best for complex workflows
-- **Ring:** Best for sequential processing
----
-### 8.4 Debugging & Troubleshooting
-**Q: How do I know if a tool call succeeded?**
-A: Check the response:
-```javascript
-const result = mcp__claude-flow__swarm_init({ topology: 'mesh' });
-if (result.success) {
-  console.log('Success:', result.data);
-} else {
-  console.error('Error:', result.error);
-}
-```
----
-**Q: Can I see raw MCP protocol messages?**
-A: Yes, enable debug mode:
-```bash
-export MCP_DEBUG=true
-export MCP_VERBOSE=true
-```
----
-**Q: What if a sandbox becomes unresponsive?**
-A:
-```javascript
-// 1. Check status
-mcp__flow-nexus__sandbox_status({ sandbox_id: 'abc123' });
-// 2. Check logs
-mcp__flow-nexus__sandbox_logs({ sandbox_id: 'abc123' });
-// 3. Force delete if needed
-mcp__flow-nexus__sandbox_delete({ sandbox_id: 'abc123' });
-```
----
-### 8.5 Best Practices
-**Q: Should I use swarms for every task?**
-A: No. Use swarms for:
-- Multi-step workflows
-- Parallel execution
-- Dynamic scaling
-Skip for simple single-agent tasks.
----
-**Q: How do I persist swarm state across sessions?**
-A:
-```javascript
-// Save state
-mcp__claude-flow__memory_usage({
-  action: 'store',
-  key: 'swarm-state-abc',
-  value: JSON.stringify(swarmState),
-  namespace: 'swarms'
-});
-// Restore state
-const saved = mcp__claude-flow__memory_usage({
-  action: 'retrieve',
-  key: 'swarm-state-abc',
-  namespace: 'swarms'
-});
-const swarmState = JSON.parse(saved.value);
-```
----
-**Q: What's the recommended memory namespace strategy?**
-A:
-- `default`: Temporary data, single session
-- `global`: Cross-session, application-wide
-- `user-{id}`: Per-user data
-- `project-{id}`: Per-project data
-- `swarm-{id}`: Per-swarm coordination
----
-## 9. Quick Reference
-### 9.1 Most Common Issues
-1. **"MCP server not found"** → `claude mcp add claude-flow npx claude-flow@alpha mcp start`
-2. **"AUTH_REQUIRED"** → `mcp__flow-nexus__user_login({ email, password })`
-3. **"RATE_LIMITED"** → Wait and retry, or upgrade tier
-4. **"SQLITE_BUSY"** → Close other connections, retry
-5. **"INVALID_PARAMS"** → Check tool documentation for correct parameters
-### 9.2 Essential Commands
-```bash
-# Check server status
-claude mcp list
-# Restart server
-claude mcp restart claude-flow
-# View logs
-claude mcp logs claude-flow --tail 50
-# Enable debug mode
-export DEBUG=claude-flow:*
-# Check database
-sqlite3 .agentdb/agentdb.db "PRAGMA integrity_check;"
-```
-### 9.3 Support Contacts
-- **GitHub Issues:** https://github.com/ruvnet/claude-flow/issues
-- **Documentation:** `/workspaces/agentic-flow/docs/guides/`
-- **Community:** Discord (link in README)
-- **Enterprise:** support@ruv.io
----
-**End of Troubleshooting Guide**
-**Version:** 1.0.0
-**Last Updated:** 2025-10-22
-**Next Review:** 2025-11-22
-**Status:** ✅ Production Ready