@hivetechs/hive-ai/dist/tools/hiveai/help-system.js

Real-time streaming AI consensus platform with HTTP+SSE MCP integration for Claude Code, VS Code, Cursor, and Windsurf - powered by OpenRouter's unified API

/**
 * Comprehensive Help System for Hive AI
 *
 * Provides intelligent, context-aware help for both CLI and natural language interfaces
 * Designed to guide new users through common workflows with interactive examples
 */
import { z } from "zod";
export const HelpToolSchema = z.object({
    topic: z.string().optional().describe('Specific help topic (e.g., "consensus", "setup", "models") or leave empty for general help'),
    format: z.enum(['detailed', 'quick', 'examples']).optional().default('quick').describe('Help format preference')
});
const helpTopics = new Map([
    ['getting-started', {
            name: 'Getting Started',
            aliases: ['start', 'begin', 'new', 'first', 'setup'],
            summary: 'Quick setup guide for new Hive AI users with intelligent recommendations',
            description: `Welcome to Hive AI! 🚀 Here's how to get started with intelligent features:

1. **Smart Setup** (AI-powered configuration)
   Command: \`hive intelligent setup\` - Analyzes your needs and recommends optimal settings
   Alternative: \`hive setup\` - Traditional guided setup
   
2. **Update Model Database** (get latest AI models)
   Command: \`hive update models\` - Syncs 320+ models from 55+ providers
   
3. **Run Your First Consensus** (4-stage AI analysis)
   Command: \`hive consensus "What is the best database for my startup?"\`
   
🧠 **Intelligent Features:**
• **AUTO Mode**: Automatically selects optimal models based on question complexity
• **Expert Templates**: Pre-configured profiles for coding, research, creative work
• **Cost Intelligence**: Budget optimization and cost prediction
• **Template Maintenance**: Automatic model updates for long-term reliability`,
            examples: [
                'hive intelligent setup',
                'hive setup',
                'hive update models',
                'hive consensus "Should I use microservices or a monolith?"',
                'hive mode auto',
                'hive templates list',
                'hive cost estimate "my question"',
                'hive status'
            ],
            relatedTopics: ['intelligent-features', 'consensus', 'models', 'expert-templates'],
            difficulty: 'beginner'
        }],
    ['consensus', {
            name: 'Consensus Pipeline',
            aliases: ['analyze', 'question', 'ask', '4-stage', 'pipeline'],
            summary: 'Run 4-stage AI consensus analysis with intelligent model selection',
            description: `The Consensus Pipeline uses 4 specialized AI agents with intelligent optimization:

**4-Stage Process:**
1. **Generator** - Creates initial comprehensive analysis
2. **Refiner** - Improves and clarifies the analysis
3. **Validator** - Fact-checks and identifies issues
4. **Curator** - Produces final polished result

**Intelligent Model Selection:**
• **AUTO Mode** (default): Analyzes question complexity and selects optimal models
• **Manual Mode**: Uses your configured profile models
• **Budget-Aware**: Considers cost constraints in model selection
• **Template Matching**: Automatically chooses Expert Templates based on question type

**Usage Patterns:**
• Simple: \`hive consensus "your question"\` (uses AUTO mode)
• Force manual: \`hive consensus "your question" --manual\`
• Force auto: \`hive consensus "your question" --auto\`
• With profile: \`hive consensus "your question" --profile Expert-Coding\``,
            examples: [
                'hive consensus "What are the security implications of serverless?"',
                'hive consensus "How should I structure my React components?" --auto',
                'hive consensus "Compare PostgreSQL vs MongoDB" --manual',
                'hive run consensus on "Best practices for API versioning"',
                'hive mode auto # Enable AUTO mode permanently'
            ],
            relatedTopics: ['intelligent-features', 'profiles', 'models', 'expert-templates'],
            difficulty: 'beginner'
        }],
    ['models', {
            name: 'Model Management',
            aliases: ['ai', 'llm', 'providers', 'openrouter'],
            summary: 'Manage AI models from 55+ providers',
            description: `Hive AI connects to OpenRouter's 324+ AI models from providers like:
• OpenAI (GPT-4, GPT-3.5)
• Anthropic (Claude 3.5, Claude 3)
• Google (Gemini Pro, PaLM)
• Meta (Llama 3)
• And 50+ more providers!

**Common Commands:**
• Update models: \`hive update models\`
• List all models: \`hive list models\`
• List by provider: \`hive list openai models\`
• Check model count: \`hive status\``,
            examples: [
                'hive update models',
                'hive list models',
                'hive list anthropic models',
                'hive models list --format compact',
                'hive show me the cheapest models'
            ],
            relatedTopics: ['providers', 'setup', 'profiles'],
            difficulty: 'beginner'
        }],
    ['profiles', {
            name: 'Pipeline Profiles',
            aliases: ['config', 'configuration', 'presets', 'templates'],
            summary: 'Pre-configured model combinations for different use cases',
            description: `Pipeline Profiles let you save and reuse model configurations for the 4-stage consensus.

**Expert Templates (Recommended):**
• **Expert-Coding** - Optimized for programming tasks
• **Expert-Research** - Best for analysis and research
• **Expert-Creative** - Creative writing and ideation
• **Expert-Fast** - Quick responses (speed over depth)
• **Expert-Cheap** - Cost-effective analysis
• **Complex-Coding** - Advanced programming challenges
• **Coding-Architecture** - System design and architecture

**Profile Management:**
• List profiles: \`hive profiles list\`
• Set default: \`hive profiles set-default Expert-Coding\`
• Create custom: \`hive profiles configure MyProfile\``,
            examples: [
                'hive profiles list',
                'hive set default profile Expert-Coding',
                'hive configure profile FastDebug',
                'hive consensus "my question" --profile Expert-Research',
                'hive show me coding profiles'
            ],
            relatedTopics: ['expert-templates', 'consensus', 'models'],
            difficulty: 'intermediate'
        }],
    ['expert-templates', {
            name: 'Expert Profile Templates',
            aliases: ['templates', 'presets', 'recommended', 'suggested'],
            summary: 'Pre-built expert configurations for common use cases',
            description: `Expert Templates are carefully tuned profile configurations:

**Available Templates:**
1. **Expert-Coding** 🚀
   • Best for: Programming, debugging, code review
   • Models: High-performance coding specialists
   
2. **Expert-Research** 📚
   • Best for: Analysis, fact-checking, deep dives
   • Models: Balanced accuracy and comprehension
   
3. **Complex-Coding** 🧮
   • Best for: Algorithms, architecture, complex systems
   • Models: Advanced reasoning capabilities
   
4. **Expert-Creative** 🎨
   • Best for: Writing, brainstorming, innovation
   • Models: Creative and diverse outputs
   
5. **Expert-Fast** ⚡
   • Best for: Quick answers, rapid iteration
   • Models: Speed-optimized selection

**Quick Start:**
Run \`hive setup\` and choose option 2 for Expert Templates!`,
            examples: [
                'hive setup → Choose "2) Expert Profile Templates"',
                'hive profiles set-default Expert-Coding',
                'hive consensus "debug this error" --profile Expert-Coding',
                'hive list profiles → See all templates'
            ],
            relatedTopics: ['profiles', 'setup', 'consensus'],
            difficulty: 'beginner'
        }],
    ['intelligent-features', {
            name: 'Intelligent Features',
            aliases: ['ai', 'smart', 'auto', 'intelligence', 'optimization'],
            summary: 'Advanced AI features for automatic optimization and intelligent assistance',
            description: `Hive AI includes sophisticated intelligence features that optimize your experience:

**🧠 Question Analysis:**
• **Complexity Detection**: Automatically determines if questions need simple or complex analysis
• **Category Classification**: Identifies question type (coding, research, creative, etc.)
• **Scope Assessment**: Determines if minimal, basic, or production-level analysis is needed

**🎯 Intelligent Profile Selection:**
• **AUTO Mode**: Analyzes questions and selects optimal Expert Templates automatically
• **Template Matching**: Matches coding questions → Expert-Coding, research → Expert-Research
• **Fallback Logic**: Uses dynamic model selection when no perfect template exists

**💰 Cost Intelligence:**
• **Budget Optimization**: Selects cost-effective models within your budget constraints
• **Cost Prediction**: Estimates consensus cost before execution
• **Smart Routing**: Balances cost vs quality based on question complexity

**🔧 Template Maintenance:**
• **Health Monitoring**: Automatically validates Expert Templates against current models
• **Model Updates**: Replaces unavailable models with suitable alternatives
• **24-Hour Maintenance**: Keeps templates current with daily OpenRouter changes

**⚙️ Dynamic Optimization:**
• **Performance Targets**: Optimizes for speed, quality, or balanced performance
• **Provider Diversity**: Ensures recommendations span multiple AI providers
• **Real-time Adaptation**: Adjusts strategy based on current model availability`,
            examples: [
                'hive mode auto # Enable intelligent mode',
                'hive intelligent setup # Smart configuration',
                'hive cost estimate "complex coding question"',
                'hive templates check # Validate template health',
                'hive consensus "debug this error" # Auto-selects Expert-Coding',
                'hive cost settings 0.01 # Set budget for cost optimization'
            ],
            relatedTopics: ['consensus', 'expert-templates', 'cost-management', 'getting-started'],
            difficulty: 'intermediate'
        }],
    ['natural-language', {
            name: 'Natural Language Commands',
            aliases: ['claude', 'ai', 'chat', 'conversational'],
            summary: 'Use conversational commands with Claude Code',
            description: `When using Hive AI through Claude Code, you can use natural language:

**Conversational Examples:**
• "hive update our models please"
• "hive check if everything is working"
• "hive run consensus on my architecture question"
• "hive show me the cheapest models available"
• "hive setup a new profile for fast responses"

**How it Works:**
The \`hive\` tool understands variations and context:
• Typos are handled gracefully
• Common phrases are recognized
• Partial commands are completed
• Help is provided for ambiguous requests

**Pro Tips:**
• Be conversational - it understands context
• Use "hive help" anytime you're unsure
• Chain commands: "hive update models and then check status"`,
            examples: [
                'hive please update the models',
                'hive can you check system health?',
                'hive I need help with consensus',
                'hive what profiles do I have?',
                'hive fix any broken templates'
            ],
            relatedTopics: ['getting-started', 'consensus', 'commands'],
            difficulty: 'beginner'
        }],
    ['troubleshooting', {
            name: 'Troubleshooting',
            aliases: ['errors', 'problems', 'issues', 'debug', 'fix'],
            summary: 'Common issues and their solutions',
            description: `**Common Issues and Solutions:**

1. **"Model does not exist on OpenRouter"**
   • Solution: Run \`hive update models\` to sync latest models
   • Then: \`hive fix templates\` to update any broken profiles

2. **"No API key configured"**
   • Solution: Run \`hive setup\` or
   • Direct: \`hive configure provider openrouter <your-key>\`

3. **"No profiles configured"**
   • Solution: Run \`hive setup\` and choose Expert Templates
   • Or: \`hive profiles set-default Expert-Coding\`

4. **"Consensus failed"**
   • Check: \`hive status\` to verify system health
   • Test: \`hive test providers\` to validate API keys
   • Update: \`hive update models\` if models are stale

5. **"Stale or incorrect data"**
   • Solution: \`hive cache clear\` to refresh all caches
   • Then: \`hive models update\` to get latest model data

**Diagnostic Commands:**
• System check: \`hive status\`
• Provider test: \`hive test providers\`
• Template health: \`hive check templates\`
• Model sync: \`hive update models\`
• Clear caches: \`hive cache clear\``,
            examples: [
                'hive status',
                'hive test providers',
                'hive check templates',
                'hive fix templates',
                'hive update models'
            ],
            relatedTopics: ['setup', 'models', 'templates'],
            difficulty: 'intermediate'
        }],
    ['commands', {
            name: 'All Commands Reference',
            aliases: ['cli', 'reference', 'list', 'all'],
            summary: 'Complete list of available commands',
            description: `**Complete Command Reference:**

**Setup & Configuration:**
• \`hive setup\` - Interactive setup wizard
• \`hive configure provider openrouter <key>\` - Set API key
• \`hive status\` - System health check

**Consensus Pipeline:**
• \`hive consensus "question"\` - Run 4-stage analysis
• \`hive consensus "question" --profile Expert-Coding\` - With profile

**Model Management:**
• \`hive models update\` - Sync latest models
• \`hive models list\` - Show all models
• \`hive models list openai\` - Filter by provider

**Profile Management:**
• \`hive profiles list\` - Show all profiles
• \`hive profiles set-default <name>\` - Set default
• \`hive profiles configure <name>\` - Create/edit

**Template Maintenance:**
• \`hive templates check\` - Validate templates
• \`hive templates fix\` - Apply fixes
• \`hive templates status\` - Maintenance history

**Provider Management:**
• \`hive providers list\` - Show providers
• \`hive providers test\` - Validate API keys
• \`hive providers configure <name> <key>\` - Add provider

**Cache Management:**
• \`hive cache clear\` - Clear all system caches`,
            examples: [
                'hive help',
                'hive help consensus',
                'hive help models',
                'hive --help',
                'hive commands'
            ],
            relatedTopics: ['getting-started', 'consensus', 'models', 'profiles'],
            difficulty: 'intermediate'
        }],
    ['cache', {
            name: 'Cache Management',
            aliases: ['cache', 'clear', 'refresh', 'cleanup'],
            summary: 'Manage system caches for model data and API responses',
            description: `**🧹 Cache Management:**

**What is cached:**
• **Model Data**: Information about available AI models from OpenRouter
• **API Responses**: Cached responses to reduce API calls and improve performance
• **Consensus Results**: Recent consensus pipeline results for faster repeated queries
• **Profile Validations**: Cached validation results for pipeline profiles

**When to clear cache:**
• After updating models if you see stale data
• When troubleshooting API response issues
• If experiencing unexpected behavior with cached results
• To force fresh data from OpenRouter

**Cache Commands:**
• \`hive cache clear\` - Clear all system caches
• Caches automatically expire after a set period
• Model data cache refreshes on \`hive models update\``,
            examples: [
                'hive cache clear',
                'hive cache clear && hive models update',
                'hive cache clear && hive consensus "your question"'
            ],
            relatedTopics: ['troubleshooting', 'models', 'performance'],
            difficulty: 'beginner'
        }],
    ['backup', {
            name: 'Backup & Recovery',
            aliases: ['backup', 'restore', 'recovery', 'database-backup', 'data-protection'],
            summary: 'Database backup, restore, and disaster recovery with cloud storage integration',
            description: `**🛡️ Database Protection & Recovery:**

**📦 Creating Backups:**
• **Automatic Backups**: Daily, weekly, and monthly backups scheduled automatically
• **Manual Backups**: Create instant backups with custom labels
• **Emergency Backups**: Quick backups before major operations
• **Types**: Full (complete database), Incremental (changes only), Emergency (critical moments)

**☁️ Cloud Storage Integration:**
• **Local Cloud Folders**: Point backup locations to local folders synced with cloud storage
• **Multiple Locations**: Configure backup sync across multiple cloud providers
• **Supported**: Dropbox, Google Drive, OneDrive, iCloud Drive, or any synced folder
• **ACID Compliance**: Unified SQLite database backups maintain data integrity

**🔄 Restoration Options:**
• **Selective Restore**: Choose specific backup by date/type
• **Emergency Recovery**: Automatic restoration from latest valid backup
• **Integrity Verification**: All backups include checksum verification
• **Safety First**: Creates emergency backup before restoration

**🏥 Health Monitoring:**
• **Backup Health Checks**: Monitor backup frequency, integrity, and storage space
• **Recommendations**: AI-powered suggestions for backup optimization
• **Location Management**: Track and configure multiple backup storage locations
• **Automated Maintenance**: Clean up old backups according to retention policies`,
            examples: [
                'hive backup create # Create full backup now',
                'hive backup create emergency pre-migration # Emergency backup with label',
                'hive backup list # Show all available backups',
                'hive backup list emergency # Show emergency backups only',
                'hive backup restore /path/to/backup.db # Restore from specific backup',
                'hive backup health # Check backup system health',
                'hive backup locations # Configure cloud storage folders',
                'hive backup emergency-restore # Emergency disaster recovery'
            ],
            relatedTopics: ['health', 'troubleshooting', 'getting-started'],
            difficulty: 'intermediate'
        }],
    ['infrastructure-as-code', {
            name: 'Infrastructure as Code (IAC)',
            aliases: ['iac', 'config', 'automation', 'devops', 'scripts', 'configuration-management'],
            summary: 'Scriptable configuration management for terminal developers using YAML/JSON configurations',
            description: `**🏗️ Infrastructure as Code for Hive AI:**

**🎯 For Terminal/DevOps Developers:**
• **Script-First Approach**: PowerShell and Bash scripts for configuration deployment
• **Version Control**: YAML/JSON configurations stored in git for audit trails
• **Multi-Environment**: Support for dev/staging/production environments
• **CI/CD Ready**: Automation-friendly with validation, dry-run, and force modes

**📋 Configuration Management:**
• **YAML Schema**: Structured configuration with environment variable substitution
• **Validation**: Built-in validation before applying configurations
• **Diff Detection**: See changes before deployment
• **Export/Import**: Backup and restore configurations
• **Template Generation**: Create configuration templates for different environments

**🌍 Environment Management:**
• **Multi-Environment**: Separate configurations for development, staging, production
• **Environment Variables**: Secure secret management via environment variables
• **Validation**: Check required variables and configuration validity
• **Automated Scripts**: PowerShell and Bash scripts for deployment automation

**🔧 Available Templates:**
• **PowerShell Scripts**: Windows and cross-platform deployment automation
• **Bash Scripts**: Linux/macOS deployment and management
• **Configuration Schema**: Complete YAML configuration examples
• **CI/CD Examples**: GitHub Actions and pipeline integration templates`,
            examples: [
                'hive config apply configs/production.yaml',
                'hive config validate configs/staging.yaml',
                'hive config diff configs/dev.yaml',
                'hive config export backup-config.yaml',
                'hive config template > new-config.yaml',
                'hive config environments list',
                'hive config environments validate production',
                'hive config environments templates'
            ],
            relatedTopics: ['configuration', 'automation', 'environments', 'devops'],
            difficulty: 'intermediate'
        }],
    ['configuration', {
            name: 'Configuration Management',
            aliases: ['config-files', 'yaml', 'json', 'settings', 'configuration-files'],
            summary: 'Manage Hive AI configurations using YAML/JSON files with environment support',
            description: `**⚙️ Configuration File Management:**

**📄 Configuration Formats:**
• **YAML Format**: Primary format with environment variable substitution
• **JSON Support**: Alternative format for programmatic generation
• **Schema Validation**: Built-in validation ensures correct configuration structure
• **Environment Variables**: Use \${VAR_NAME} syntax for secure secret management

**🔧 Configuration Structure:**
\`\`\`yaml
metadata:
  name: "hive-ai-production"
  environment: "production"

license:
  key: "\${HIVE_LICENSE_KEY}"

providers:
  openrouter:
    api_key: "\${OPENROUTER_API_KEY}"

consensus:
  profile: "Consensus_Elite"
  max_agents: 8

backup:
  enabled: true
  locations:
    - path: "/data/backups/hive"
      priority: 1
\`\`\`

**🎯 Configuration Commands:**
• **Apply**: Deploy configuration to system
• **Validate**: Check configuration syntax and requirements
• **Diff**: Compare configuration with current settings
• **Export**: Create backup of current configuration
• **Template**: Generate example configurations

**💡 Best Practices:**
• Store configurations in version control (git)
• Use environment variables for secrets
• Validate before applying to production
• Create backups before major changes`,
            examples: [
                'hive config apply my-config.yaml',
                'hive config validate test-config.yaml',
                'hive config diff new-settings.yaml',
                'hive config export current-backup.yaml',
                'hive config template consensus > consensus-config.yaml',
                'export HIVE_LICENSE_KEY="your-key" && hive config apply prod.yaml'
            ],
            relatedTopics: ['infrastructure-as-code', 'environments', 'automation'],
            difficulty: 'intermediate'
        }],
    ['environments', {
            name: 'Environment Management',
            aliases: ['env', 'dev', 'staging', 'production', 'environment-variables'],
            summary: 'Manage multiple environments (dev/staging/production) with different configurations',
            description: `**🌍 Multi-Environment Configuration:**

**📂 Supported Environments:**
• **Development**: Debug features, fast models, relaxed settings
• **Staging**: Production-like testing with monitoring
• **Production**: Full monitoring, backup, elite consensus profiles

**🔧 Environment Setup:**
\`\`\`bash
# Set environment
export HIVE_CONFIG_ENV=production

# Required variables (all environments)
export HIVE_LICENSE_KEY="your-license-key"
export OPENROUTER_API_KEY="your-api-key"

# Production-specific variables
export PROD_BACKUP_KEY="backup-encryption-key"
\`\`\`

**🎯 Environment-Specific Features:**
• **Development**: Fast consensus, minimal requirements, debug logging
• **Staging**: Balanced performance, testing-friendly settings
• **Production**: Elite models, full backup, comprehensive monitoring

**🤖 Automated Management:**
Use the provided script templates for managing multiple environments:

**PowerShell (Windows/Cross-platform):**
• \`templates/powershell/manage-hive-environments.ps1\`
• Deploy all environments, validation, health checks

**Bash (Linux/macOS):**
• \`templates/bash/manage-hive-environments.sh\`
• Parallel deployment, CI/CD integration

**💡 Environment Commands:**
• **List**: Show available environments and requirements
• **Current**: Display current environment and variable status
• **Validate**: Check environment variable configuration
• **Templates**: Show available deployment script templates`,
            examples: [
                'hive config environments list',
                'hive config environments current',
                'hive config environments validate production',
                'hive config environments templates',
                'export HIVE_CONFIG_ENV=development',
                './templates/bash/manage-hive-environments.sh deploy-all',
                './templates/powershell/manage-hive-environments.ps1 -Action validate-all'
            ],
            relatedTopics: ['infrastructure-as-code', 'configuration', 'automation', 'devops'],
            difficulty: 'intermediate'
        }],
    ['automation', {
            name: 'DevOps Automation',
            aliases: ['devops', 'ci-cd', 'pipeline', 'deployment', 'scripts'],
            summary: 'Automate Hive AI deployments with PowerShell/Bash scripts and CI/CD integration',
            description: `**🚀 DevOps Automation for Hive AI:**

**📋 Script Templates:**
The \`templates/\` directory contains production-ready automation scripts:

**PowerShell Scripts:**
• \`deploy-hive-config.ps1\` - Single environment deployment
• \`manage-hive-environments.ps1\` - Multi-environment management
• Features: Logging, error handling, dry-run mode, validation

**Bash Scripts:**
• \`deploy-hive-config.sh\` - Linux/macOS deployment
• \`manage-hive-environments.sh\` - Multi-environment automation
• Features: Parallel execution, CI/CD ready, extensive logging

**🔄 CI/CD Integration:**
\`\`\`yaml
# GitHub Actions Example
- name: Deploy Hive AI Configuration
  env:
    HIVE_LICENSE_KEY: \${{ secrets.HIVE_LICENSE_KEY }}
    OPENROUTER_API_KEY: \${{ secrets.OPENROUTER_API_KEY }}
  run: |
    ./templates/bash/deploy-hive-config.sh \\
      -e production -c configs/prod.yaml --force
\`\`\`

**🎯 Automation Features:**
• **Validation**: Pre-deployment configuration validation
• **Dry Run**: Test deployments without making changes
• **Force Mode**: Skip confirmations for CI/CD
• **Logging**: Comprehensive logs for debugging
• **Rollback**: Emergency recovery and backup creation
• **Health Checks**: Post-deployment validation

**💡 Best Practices:**
• Use version control for all configuration files
• Implement environment-specific validation
• Create backups before deployments
• Monitor deployment logs for issues
• Test in staging before production`,
            examples: [
                './templates/bash/deploy-hive-config.sh -e production -c configs/prod.yaml',
                './templates/bash/deploy-hive-config.sh -e staging -c configs/staging.yaml --dry-run',
                './templates/powershell/manage-hive-environments.ps1 -Action deploy-all -Force',
                'hive config validate configs/prod.yaml && hive config apply configs/prod.yaml',
                './templates/bash/manage-hive-environments.sh validate-all'
            ],
            relatedTopics: ['infrastructure-as-code', 'environments', 'configuration', 'troubleshooting'],
            difficulty: 'advanced'
        }]
]);
export async function runHelpTool(args) {
    const { topic, format } = args;
    try {
        if (!topic) {
            return { result: generateQuickStartHelp() };
        }
        // Find matching help topic
        const helpTopic = findHelpTopic(topic);
        if (!helpTopic) {
            return { result: generateTopicNotFoundHelp(topic) };
        }
        // Generate help based on format
        switch (format) {
            case 'detailed':
                return { result: generateDetailedHelp(helpTopic) };
            case 'examples':
                return { result: generateExamplesHelp(helpTopic) };
            default:
                return { result: generateQuickHelp(helpTopic) };
        }
    }
    catch (error) {
        return {
            result: `❌ Error generating help: ${error instanceof Error ? error.message : 'Unknown error'}`
        };
    }
}
function findHelpTopic(query) {
    const normalizedQuery = query.toLowerCase().trim();
    // Direct match
    if (helpTopics.has(normalizedQuery)) {
        return helpTopics.get(normalizedQuery);
    }
    // Check aliases
    for (const [key, topic] of helpTopics.entries()) {
        if (topic.aliases.includes(normalizedQuery)) {
            return topic;
        }
        // Partial match on name or aliases
        if (topic.name.toLowerCase().includes(normalizedQuery) ||
            topic.aliases.some(alias => alias.includes(normalizedQuery))) {
            return topic;
        }
    }
    return null;
}
function generateQuickStartHelp() {
    return `🚀 **Welcome to Hive AI!**

**New to Hive AI? Start here:**

1️⃣ **Initial Setup** (one-time, 2 minutes)
   \`\`\`
   hive setup
   \`\`\`
   This will guide you through:
   • Adding your OpenRouter API key
   • Choosing an Expert Profile Template
   • Updating the AI model database

2️⃣ **Run Your First Consensus**
   \`\`\`
   hive consensus "What's the best database for a startup?"
   \`\`\`

3️⃣ **Explore More Commands**
   • \`hive help consensus\` - Learn about 4-stage analysis
   • \`hive help models\` - Manage AI models
   • \`hive help profiles\` - Configure pipelines
   • \`hive commands\` - See all commands

**Quick Examples:**
• \`hive update models\` - Get latest AI models
• \`hive list profiles\` - See available configurations
• \`hive status\` - Check system health

**Using with Claude Code?**
Just use natural language: "hive update our models" or "hive help me with consensus"

Type \`hive help <topic>\` for detailed help on any topic!`;
}
function generateQuickHelp(topic) {
    return `📘 **${topic.name}**

${topic.summary}

${topic.description}

**Quick Examples:**
${topic.examples.slice(0, 3).map(ex => `• \`${ex}\``).join('\n')}

**Related Topics:** ${topic.relatedTopics.map(t => `\`${t}\``).join(', ')}

For more examples: \`hive help ${topic.aliases[0]} --format examples\`
For detailed info: \`hive help ${topic.aliases[0]} --format detailed\``;
}
function generateDetailedHelp(topic) {
    return `📘 **${topic.name}** (Detailed Guide)

**Summary:** ${topic.summary}

**Difficulty:** ${topic.difficulty}

**Also Known As:** ${topic.aliases.join(', ')}

**Full Description:**
${topic.description}

**All Examples:**
${topic.examples.map((ex, i) => `${i + 1}. \`${ex}\``).join('\n')}

**Related Topics:**
${topic.relatedTopics.map(t => {
        const related = findHelpTopic(t);
        return related ? `• **${t}** - ${related.summary}` : `• ${t}`;
    }).join('\n')}

**Next Steps:**
${generateNextSteps(topic)}`;
}
function generateExamplesHelp(topic) {
    return `📘 **${topic.name}** - Interactive Examples

${topic.summary}

**Try These Commands:**

${topic.examples.map((ex, i) => `**Example ${i + 1}:**
\`\`\`bash
${ex}
\`\`\`
${generateExampleDescription(ex)}
`).join('\n')}

**Want to Learn More?**
• Full guide: \`hive help ${topic.aliases[0]} --format detailed\`
• Related: ${topic.relatedTopics.map(t => `\`hive help ${t}\``).join(', ')}`;
}
function generateExampleDescription(example) {
    // Provide context for each example
    if (example.includes('consensus')) {
        return '↳ Runs 4-stage AI analysis on your question';
    }
    else if (example.includes('update models')) {
        return '↳ Syncs the latest AI models from OpenRouter';
    }
    else if (example.includes('list')) {
        return '↳ Shows available items in a formatted list';
    }
    else if (example.includes('setup')) {
        return '↳ Launches interactive configuration wizard';
    }
    else if (example.includes('profile')) {
        return '↳ Manages pipeline configurations';
    }
    else if (example.includes('status')) {
        return '↳ Checks system health and configuration';
    }
    else if (example.includes('fix')) {
        return '↳ Automatically repairs configuration issues';
    }
    return '↳ Try this command to see what happens!';
}
function generateNextSteps(topic) {
    switch (topic.aliases[0]) {
        case 'start':
            return `1. Run \`hive setup\` to configure Hive AI
2. Try \`hive consensus "your first question"\`
3. Explore \`hive help profiles\` for customization`;
        case 'consensus':
            return `1. Try different questions with consensus
2. Learn about profiles: \`hive help profiles\`
3. Optimize for your use case: \`hive help expert-templates\``;
        case 'models':
            return `1. Keep models updated: \`hive update models\` (weekly)
2. Explore providers: \`hive list models | less\`
3. Configure profiles: \`hive help profiles\``;
        default:
            return `1. Practice with the examples above
2. Explore related topics
3. Run \`hive status\` to check your setup`;
    }
}
function generateTopicNotFoundHelp(query) {
    // Suggest similar topics
    const suggestions = [];
    const normalizedQuery = query.toLowerCase();
    for (const [key, topic] of helpTopics.entries()) {
        if (topic.name.toLowerCase().includes(normalizedQuery) ||
            topic.summary.toLowerCase().includes(normalizedQuery) ||
            topic.aliases.some(a => a.includes(normalizedQuery))) {
            suggestions.push(topic.aliases[0]);
        }
    }
    return `❓ **No exact match for "${query}"**

${suggestions.length > 0 ?
        `**Did you mean one of these?**
${suggestions.map(s => `• \`hive help ${s}\``).join('\n')}` :
        `**Try these popular topics:**
• \`hive help getting-started\` - New user guide
• \`hive help consensus\` - 4-stage analysis
• \`hive help models\` - AI model management
• \`hive help troubleshooting\` - Fix common issues`}

**All Topics:**
${Array.from(helpTopics.values())
        .map(t => `• **${t.aliases[0]}** - ${t.summary}`)
        .join('\n')}

Or just type \`hive help\` for the quick start guide!`;
}
// Export help integration for CLI
export function getHelpForCommand(command) {
    const topic = findHelpTopic(command);
    if (topic) {
        return generateQuickHelp(topic);
    }
    return generateQuickStartHelp();
}
// Export for natural language understanding
export function getContextualHelp(userMessage) {
    // Detect help intent in natural language
    const helpPhrases = [
        'how do i', 'how to', 'what is', 'what are', 'explain',
        'help with', 'show me how', 'teach me', 'guide me',
        'i need help', 'im confused', 'im stuck', 'not sure'
    ];
    const message = userMessage.toLowerCase();
    const needsHelp = helpPhrases.some(phrase => message.includes(phrase));
    if (!needsHelp) {
        return '';
    }
    // Extract topic from message
    if (message.includes('consensus') || message.includes('question')) {
        return getHelpForCommand('consensus');
    }
    else if (message.includes('model') || message.includes('ai')) {
        return getHelpForCommand('models');
    }
    else if (message.includes('setup') || message.includes('start')) {
        return getHelpForCommand('getting-started');
    }
    else if (message.includes('profile') || message.includes('config')) {
        return getHelpForCommand('profiles');
    }
    return generateQuickStartHelp();
}
// Tool exports
export const helpToolName = 'hive_help';
export const helpToolDescription = 'Get comprehensive help and guidance for Hive AI - includes examples, tutorials, and troubleshooting';
//# sourceMappingURL=help-system.js.map