# Hierarchical Help System with Categories
# Provides organized, drill-down help for provisioning commands

use ../lib_provisioning/config/accessor.nu *

# Main help dispatcher
export def provisioning-help [
    category?: string  # Optional category: infrastructure, orchestration, development, workspace, platform, auth, plugins, utilities, concepts, guides, integrations
]: nothing -> string {
    # If no category provided, show main help
    if ($category == null) or ($category == "") {
        return (help-main)
    }

    # Try to match the category
    let result = (match $category {
        "infrastructure" | "infra" => "infrastructure"
        "orchestration" | "orch" => "orchestration"
        "development" | "dev" => "development"
        "workspace" | "ws" => "workspace"
        "platform" | "plat" => "platform"
        "setup" | "st" => "setup"
        "authentication" | "auth" => "authentication"
        "mfa" => "mfa"
        "plugins" | "plugin" => "plugins"
        "utilities" | "utils" | "cache" => "utilities"
        "tools" => "tools"
        "vm" => "vm"
        "diagnostics" | "diag" | "status" | "health" => "diagnostics"
        "concepts" | "concept" => "concepts"
        "guides" | "guide" | "howto" => "guides"
        "integrations" | "integration" | "int" => "integrations"
        _ => "unknown"
    })

    # If unknown category, show error
    if $result == "unknown" {
        print $"❌ Unknown help category: \"($category)\"\n"
        print "Available help categories:"
        print "  infrastructure [infra]  - Server, taskserv, cluster, VM management"
        print "  orchestration [orch]    - Workflow, batch operations"
        print "  development [dev]       - Module system, layers, versioning"
        print "  workspace [ws]          - Workspace and template management"
        print "  setup [st]              - System setup, configuration, initialization"
        print "  platform [plat]         - Orchestrator, Control Center, MCP"
        print "  authentication [auth]   - JWT authentication, MFA, sessions"
        print "  mfa                     - Multi-Factor Authentication details"
        print "  plugins [plugin]        - Plugin management"
        print "  utilities [utils]       - Cache, SOPS, providers, SSH"
        print "  tools                   - Tool and dependency management"
        print "  vm                      - Virtual machine operations"
        print "  diagnostics [diag]      - System status, health checks"
        print "  concepts [concept]      - Architecture and key concepts"
        print "  guides [guide]          - Quick guides and cheatsheets"
        print "  integrations [int]      - Prov-ecosystem and provctl bridge\n"
        print "Use 'provisioning help' for main help"
        exit 1
    }

    # Match valid category
    match $result {
        "infrastructure" => (help-infrastructure)
        "orchestration" => (help-orchestration)
        "development" => (help-development)
        "workspace" => (help-workspace)
        "platform" => (help-platform)
        "setup" => (help-setup)
        "authentication" => (help-authentication)
        "mfa" => (help-mfa)
        "plugins" => (help-plugins)
        "utilities" => (help-utilities)
        "tools" => (help-tools)
        "vm" => (help-vm)
        "diagnostics" => (help-diagnostics)
        "concepts" => (help-concepts)
        "guides" => (help-guides)
        "integrations" => (help-integrations)
        _ => (help-main)
    }
}

# Main help overview with categories
def help-main []: nothing -> string {
    let show_header = not ($env.PROVISIONING_NO_TITLES? | default false)
    let header = (if $show_header {
        ($"(_ansi yellow_bold)╔════════════════════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║ (_ansi reset)  (_ansi cyan_bold)PROVISIONING SYSTEM(_ansi reset) - Layered Infrastructure Automation  (_ansi yellow_bold)    ║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚════════════════════════════════════════════════════════════════╝(_ansi reset)\n\n")
    } else {
        ""
    })
    (
        ($header) +

        $"(_ansi green_bold)📚 COMMAND CATEGORIES(_ansi reset) (_ansi default_dimmed)- Use 'provisioning help <category>' for details(_ansi reset)\n\n" +

        $"  (_ansi cyan)🏗️ infrastructure(_ansi reset) (_ansi default_dimmed)[infra](_ansi reset)\t Server, taskserv, cluster, VM, and infra management\n" +
        $"  (_ansi purple)⚡ orchestration(_ansi reset) (_ansi default_dimmed)[orch](_ansi reset)\t Workflow, batch operations, and orchestrator control\n" +
        $"  (_ansi blue)🧩 development(_ansi reset) (_ansi default_dimmed)[dev](_ansi reset)\t\t Module discovery, layers, versions, and packaging\n" +
        $"  (_ansi green)📁 workspace(_ansi reset) (_ansi default_dimmed)[ws](_ansi reset)\t\t Workspace and template management\n" +
        $"  (_ansi red)🖥️ platform(_ansi reset) (_ansi default_dimmed)[plat](_ansi reset)\t\t Orchestrator, Control Center UI, MCP Server\n" +
        $"  (_ansi magenta)⚙️  setup(_ansi reset) (_ansi default_dimmed)[st](_ansi reset)\t\t System setup, configuration, and initialization\n" +
        $"  (_ansi yellow)🔐 authentication(_ansi reset) (_ansi default_dimmed)[auth](_ansi reset)\t JWT authentication, MFA, and sessions\n" +
        $"  (_ansi cyan)🔌 plugins(_ansi reset) (_ansi default_dimmed)[plugin](_ansi reset)\t\t Plugin management and integration\n" +
        $"  (_ansi green)🛠️ utilities(_ansi reset) (_ansi default_dimmed)[utils](_ansi reset)\t\t Cache, SOPS editing, providers, plugins, SSH\n" +
        $"  (_ansi yellow)🌉 integrations(_ansi reset) (_ansi default_dimmed)[int](_ansi reset)\t\t Prov-ecosystem and provctl bridge\n" +
        $"  (_ansi green)🔍 diagnostics(_ansi reset) (_ansi default_dimmed)[diag](_ansi reset)\t\t System status, health checks, and next steps\n" +
        $"  (_ansi magenta)📚 guides(_ansi reset) (_ansi default_dimmed)[guide](_ansi reset)\t\t Quick guides and cheatsheets\n" +
        $"  (_ansi yellow)💡 concepts(_ansi reset) (_ansi default_dimmed)[concept](_ansi reset)\t\t Understanding layers, modules, and architecture\n\n" +

        $"(_ansi green_bold)🚀 QUICK START(_ansi reset)\n\n" +
        $"  1. (_ansi cyan)Understand the system(_ansi reset):  provisioning help concepts\n" +
        $"  2. (_ansi cyan)Create workspace(_ansi reset):       provisioning workspace init my-infra --activate\n" +
        $"     (_ansi default_dimmed)Or use interactive:(_ansi reset)     provisioning workspace init --interactive\n" +
        $"  3. (_ansi cyan)Discover modules(_ansi reset):       provisioning module discover taskservs\n" +
        $"  4. (_ansi cyan)Create servers(_ansi reset):         provisioning server create --infra my-infra\n" +
        $"  5. (_ansi cyan)Deploy services(_ansi reset):        provisioning taskserv create kubernetes\n\n" +

        $"(_ansi green_bold)🔧 COMMON COMMANDS(_ansi reset)\n\n" +
        $"  provisioning server list               - List all servers\n" +
        $"  provisioning workflow list             - List workflows\n" +
        $"  provisioning module discover taskservs - Discover available taskservs\n" +
        $"  provisioning layer show <workspace>    - Show layer resolution\n" +
        $"  provisioning version check             - Check component versions\n\n" +

        $"(_ansi green_bold)ℹ️  HELP TOPICS(_ansi reset)\n\n" +
        $"  provisioning help infrastructure (_ansi default_dimmed)[or: infra](_ansi reset) - Server/cluster lifecycle\n" +
        $"  provisioning help orchestration (_ansi default_dimmed)[or: orch](_ansi reset)   - Workflows and batch operations\n" +
        $"  provisioning help development (_ansi default_dimmed)[or: dev](_ansi reset)      - Module system and tools\n" +
        $"  provisioning help workspace (_ansi default_dimmed)[or: ws](_ansi reset)         - Workspace and templates\n" +
        $"  provisioning help setup (_ansi default_dimmed)[or: st](_ansi reset)             - System setup and configuration\n" +
        $"  provisioning help platform (_ansi default_dimmed)[or: plat](_ansi reset)        - Platform services with web UI\n" +
        $"  provisioning help authentication (_ansi default_dimmed)[or: auth](_ansi reset)  - JWT authentication and MFA\n" +
        $"  provisioning help plugins (_ansi default_dimmed)[or: plugin](_ansi reset)       - Plugin management\n" +
        $"  provisioning help utilities (_ansi default_dimmed)[or: utils](_ansi reset)      - Cache, SOPS, providers, and utilities\n" +
        $"  provisioning help integrations (_ansi default_dimmed)[or: int](_ansi reset)     - Prov-ecosystem and provctl bridge\n" +
        $"  provisioning help diagnostics (_ansi default_dimmed)[or: diag](_ansi reset)     - System status and health\n" +
        $"  provisioning help guides (_ansi default_dimmed)[or: guide](_ansi reset)         - Quick guides and cheatsheets\n" +
        $"  provisioning help concepts (_ansi default_dimmed)[or: concept](_ansi reset)     - Architecture and key concepts\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Most commands support --help for detailed options\n" +
        $"   Example: provisioning server --help(_ansi reset)\n"
    )
}

# Infrastructure category help
def help-infrastructure []: nothing -> string {
    (
        $"(_ansi cyan_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi cyan_bold)║(_ansi reset)  🏗️  INFRASTRUCTURE MANAGEMENT                   (_ansi cyan_bold)║(_ansi reset)\n" +
        $"(_ansi cyan_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Lifecycle](_ansi reset) Server Management\n" +
        $"  (_ansi blue)server create(_ansi reset)       - Create new servers [--infra <name>] [--check]\n" +
        $"  (_ansi blue)server delete(_ansi reset)       - Delete servers [--yes] [--keepstorage]\n" +
        $"  (_ansi blue)server list(_ansi reset)         - List all servers [--out json|yaml]\n" +
        $"  (_ansi blue)server ssh <host>(_ansi reset)   - SSH into server\n" +
        $"  (_ansi blue)server price(_ansi reset)        - Show server pricing\n\n" +

        $"(_ansi green_bold)[Services](_ansi reset) Task Service Management\n" +
        $"  (_ansi blue)taskserv create <svc>(_ansi reset)   - Install service [kubernetes, redis, postgres]\n" +
        $"  (_ansi blue)taskserv delete <svc>(_ansi reset)   - Remove service\n" +
        $"  (_ansi blue)taskserv list(_ansi reset)           - List available services\n" +
        $"  (_ansi blue)taskserv generate <svc>(_ansi reset) - Generate service configuration\n" +
        $"  (_ansi blue)taskserv validate <svc>(_ansi reset) - Validate service before deployment\n" +
        $"  (_ansi blue)taskserv test <svc>(_ansi reset)     - Test service in sandbox\n" +
        $"  (_ansi blue)taskserv check-deps <svc>(_ansi reset) - Check service dependencies\n" +
        $"  (_ansi blue)taskserv check-updates(_ansi reset)  - Check for service updates\n\n" +

        $"(_ansi green_bold)[Complete](_ansi reset) Cluster Operations\n" +
        $"  (_ansi blue)cluster create(_ansi reset)      - Create complete cluster\n" +
        $"  (_ansi blue)cluster delete(_ansi reset)      - Delete cluster\n" +
        $"  (_ansi blue)cluster list(_ansi reset)        - List cluster components\n\n" +

        $"(_ansi green_bold)[Virtual Machines](_ansi reset) VM Management\n" +
        $"  (_ansi blue)vm create [config](_ansi reset)   - Create new VM\n" +
        $"  (_ansi blue)vm list [--running](_ansi reset)  - List VMs\n" +
        $"  (_ansi blue)vm start <name>(_ansi reset)      - Start VM\n" +
        $"  (_ansi blue)vm stop <name>(_ansi reset)       - Stop VM\n" +
        $"  (_ansi blue)vm delete <name>(_ansi reset)     - Delete VM\n" +
        $"  (_ansi blue)vm info <name>(_ansi reset)       - VM information\n" +
        $"  (_ansi blue)vm ssh <name>(_ansi reset)        - SSH into VM\n" +
        $"  (_ansi blue)vm hosts check(_ansi reset)       - Check hypervisor capability\n" +
        $"  (_ansi blue)vm lifecycle list-temporary(_ansi reset) - List temporary VMs\n" +
        $"  (_ansi default_dimmed)Shortcuts: vmi=info, vmh=hosts, vml=lifecycle(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Management](_ansi reset) Infrastructure\n" +
        $"  (_ansi blue)infra list(_ansi reset)          - List infrastructures\n" +
        $"  (_ansi blue)infra validate(_ansi reset)      - Validate infrastructure config\n" +
        $"  (_ansi blue)generate infra --new <name>(_ansi reset) - Create new infrastructure\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Use --check flag for dry-run mode\n" +
        $"   Example: provisioning server create --check(_ansi reset)\n"
    )
}

# Orchestration category help
def help-orchestration []: nothing -> string {
    (
        $"(_ansi purple_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi purple_bold)║(_ansi reset)  ⚡ ORCHESTRATION & WORKFLOWS                    (_ansi purple_bold)║(_ansi reset)\n" +
        $"(_ansi purple_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Control](_ansi reset) Orchestrator Management\n" +
        $"  (_ansi blue)orchestrator start(_ansi reset)  - Start orchestrator [--background]\n" +
        $"  (_ansi blue)orchestrator stop(_ansi reset)   - Stop orchestrator\n" +
        $"  (_ansi blue)orchestrator status(_ansi reset) - Check if running\n" +
        $"  (_ansi blue)orchestrator health(_ansi reset) - Health check\n" +
        $"  (_ansi blue)orchestrator logs(_ansi reset)   - View logs [--follow]\n\n" +

        $"(_ansi green_bold)[Workflows](_ansi reset) Single Task Workflows\n" +
        $"  (_ansi blue)workflow list(_ansi reset)         - List all workflows\n" +
        $"  (_ansi blue)workflow status <id>(_ansi reset)  - Get workflow status\n" +
        $"  (_ansi blue)workflow monitor <id>(_ansi reset) - Monitor in real-time\n" +
        $"  (_ansi blue)workflow stats(_ansi reset)        - Show statistics\n" +
        $"  (_ansi blue)workflow cleanup(_ansi reset)      - Clean old workflows\n\n" +

        $"(_ansi green_bold)[Batch](_ansi reset) Multi-Provider Batch Operations\n" +
        $"  (_ansi blue)batch submit <file>(_ansi reset)    - Submit KCL workflow [--wait]\n" +
        $"  (_ansi blue)batch list(_ansi reset)             - List batches [--status Running]\n" +
        $"  (_ansi blue)batch status <id>(_ansi reset)      - Get batch status\n" +
        $"  (_ansi blue)batch monitor <id>(_ansi reset)     - Real-time monitoring\n" +
        $"  (_ansi blue)batch rollback <id>(_ansi reset)    - Rollback failed batch\n" +
        $"  (_ansi blue)batch cancel <id>(_ansi reset)      - Cancel running batch\n" +
        $"  (_ansi blue)batch stats(_ansi reset)            - Show statistics\n\n" +

        $"(_ansi default_dimmed)💡 Batch workflows support mixed providers: UpCloud, AWS, and local\n" +
        $"   Example: provisioning batch submit deployment.k --wait(_ansi reset)\n"
    )
}

# Development tools category help
def help-development []: nothing -> string {
    (
        $"(_ansi blue_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi blue_bold)║(_ansi reset)  🧩 DEVELOPMENT TOOLS                            (_ansi blue_bold)║(_ansi reset)\n" +
        $"(_ansi blue_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Discovery](_ansi reset) Module System\n" +
        $"  (_ansi blue)module discover <type>(_ansi reset)\t  - Find taskservs/providers/clusters\n" +
        $"  (_ansi blue)module load <type> <ws> <mods>(_ansi reset)  - Load modules into workspace\n" +
        $"  (_ansi blue)module list <type> <ws>(_ansi reset)\t  - List loaded modules\n" +
        $"  (_ansi blue)module unload <type> <ws> <mod>(_ansi reset) - Unload module\n" +
        $"  (_ansi blue)module sync-kcl <infra>(_ansi reset)\t  - Sync KCL dependencies\n\n" +

        $"(_ansi green_bold)[Architecture](_ansi reset) Layer System (_ansi cyan)STRATEGIC(_ansi reset)\n" +
        $"  (_ansi blue)layer explain(_ansi reset)          - Explain layer concept\n" +
        $"  (_ansi blue)layer show <ws>(_ansi reset)        - Show layer resolution\n" +
        $"  (_ansi blue)layer test <mod> <ws>(_ansi reset)  - Test layer resolution\n" +
        $"  (_ansi blue)layer stats(_ansi reset)            - Show statistics\n\n" +

        $"(_ansi green_bold)[Maintenance](_ansi reset) Version Management\n" +
        $"  (_ansi blue)version check(_ansi reset)         - Check all versions\n" +
        $"  (_ansi blue)version show(_ansi reset)          - Display status [--format table|json]\n" +
        $"  (_ansi blue)version updates(_ansi reset)       - Check available updates\n" +
        $"  (_ansi blue)version apply(_ansi reset)         - Apply config updates\n" +
        $"  (_ansi blue)version taskserv <name>(_ansi reset) - Show taskserv version\n\n" +

        $"(_ansi green_bold)[Distribution](_ansi reset) Packaging (_ansi yellow)Advanced(_ansi reset)\n" +
        $"  (_ansi blue)pack core(_ansi reset)             - Package core schemas\n" +
        $"  (_ansi blue)pack provider <name>(_ansi reset)  - Package provider\n" +
        $"  (_ansi blue)pack list(_ansi reset)             - List packages\n" +
        $"  (_ansi blue)pack clean(_ansi reset)            - Clean old packages\n\n" +

        $"(_ansi default_dimmed)💡 The layer system is key to configuration inheritance\n" +
        $"   Use 'provisioning layer explain' to understand it(_ansi reset)\n"
    )
}

# Workspace category help
def help-workspace []: nothing -> string {
    (
        $"(_ansi green_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi green_bold)║(_ansi reset)  📁 WORKSPACE & TEMPLATES                        (_ansi green_bold)║(_ansi reset)\n" +
        $"(_ansi green_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Management](_ansi reset) Workspace Operations\n" +
        $"  (_ansi blue)workspace init <path>(_ansi reset)\t\t - Initialize workspace [--activate] [--interactive]\n" +
        $"  (_ansi blue)workspace create <path>(_ansi reset)\t - Create workspace structure [--activate]\n" +
        $"  (_ansi blue)workspace activate <name>(_ansi reset)\t - Activate existing workspace as default\n" +
        $"  (_ansi blue)workspace validate <path>(_ansi reset)\t - Validate structure\n" +
        $"  (_ansi blue)workspace info <path>(_ansi reset)\t\t - Show information\n" +
        $"  (_ansi blue)workspace list(_ansi reset)\t\t - List workspaces\n" +
        $"  (_ansi blue)workspace migrate [name](_ansi reset)\t - Migrate workspace [--skip-backup] [--force]\n" +
        $"  (_ansi blue)workspace version [name](_ansi reset)\t - Show workspace version information\n" +
        $"  (_ansi blue)workspace check-compatibility [name](_ansi reset) - Check workspace compatibility\n" +
        $"  (_ansi blue)workspace list-backups [name](_ansi reset)\t - List workspace backups\n\n" +

        $"(_ansi green_bold)[Synchronization](_ansi reset) Update Hidden Directories & Modules\n" +
        $"  (_ansi blue)workspace check-updates [name](_ansi reset)\t - Check which directories need updating\n" +
        $"  (_ansi blue)workspace update [name] [FLAGS](_ansi reset)\t - Update all hidden dirs and content\n" +
        $"                         \t\t\tUpdates: .providers, .clusters, .taskservs, .kcl\n" +
        $"  (_ansi blue)workspace sync-modules [name] [FLAGS](_ansi reset)\t - Sync workspace modules\n\n" +
        $"(_ansi default_dimmed)Note: Optional workspace name [name] defaults to active workspace if not specified(_ansi reset)\n\n" +
        $"(_ansi green_bold)[Common Flags](_ansi reset)\n" +
        $"  (_ansi cyan)--check  (-c)(_ansi reset)   - Preview changes without applying them\n" +
        $"  (_ansi cyan)--force  (-f)(_ansi reset)   - Skip confirmation prompts\n" +
        $"  (_ansi cyan)--yes    (-y)(_ansi reset)   - Auto-confirm (same as --force)\n" +
        $"  (_ansi cyan)--verbose(-v)(_ansi reset)   - Detailed operation information\n\n" +
        $"(_ansi cyan_bold)Examples:(_ansi reset)\n" +
        $"  (_ansi green)provisioning --yes workspace update(_ansi reset)              - Update active workspace with auto-confirm\n" +
        $"  (_ansi green)provisioning --verbose workspace update myws(_ansi reset)     - Update 'myws' with detailed output\n" +
        $"  (_ansi green)provisioning --check workspace update(_ansi reset)            - Preview changes before updating\n" +
        $"  (_ansi green)provisioning --yes --verbose workspace update myws(_ansi reset) - Combine flags\n\n" +
        $"(_ansi yellow_bold)⚠️  IMPORTANT - Nushell Flag Ordering:(_ansi reset)\n" +
        $"  Nushell requires (_ansi cyan)flags BEFORE positional arguments(_ansi reset). Thus:\n" +
        $"    ✅ (_ansi green)provisioning --yes workspace update(_ansi reset)     [Correct - flags first]\n" +
        $"    ❌ (_ansi red)provisioning workspace update --yes(_ansi reset)   [Wrong - parser error]\n\n" +

        $"(_ansi green_bold)[Creation Modes](_ansi reset)\n" +
        $"  (_ansi blue)--activate\(-a\)(_ansi reset)\t\t - Activate workspace as default after creation\n" +
        $"  (_ansi blue)--interactive\(-I\)(_ansi reset)\t\t - Interactive workspace creation wizard\n\n" +

        $"(_ansi green_bold)[Configuration](_ansi reset) Workspace Config Management\n" +
        $"  (_ansi blue)workspace config show [name](_ansi reset)\t\t - Show workspace config [--format yaml|json|toml]\n" +
        $"  (_ansi blue)workspace config validate [name](_ansi reset)\t - Validate all configs\n" +
        $"  (_ansi blue)workspace config generate provider <name>(_ansi reset) - Generate provider config\n" +
        $"  (_ansi blue)workspace config edit <type> [name](_ansi reset)\t - Edit config \(main|provider|platform|kms\)\n" +
        $"  (_ansi blue)workspace config hierarchy [name](_ansi reset)\t - Show config loading order\n" +
        $"  (_ansi blue)workspace config list [name](_ansi reset)\t\t - List config files [--type all|provider|platform|kms]\n\n" +

        $"(_ansi green_bold)[Patterns](_ansi reset) Infrastructure Templates\n" +
        $"  (_ansi blue)template list(_ansi reset)\t\t         - List templates [--type taskservs|providers]\n" +
        $"  (_ansi blue)template types(_ansi reset)\t         - Show template categories\n" +
        $"  (_ansi blue)template show <name>(_ansi reset)\t\t - Show template details\n" +
        $"  (_ansi blue)template apply <name> <infra>(_ansi reset)\t - Apply to infrastructure\n" +
        $"  (_ansi blue)template validate <infra>(_ansi reset)\t - Validate template usage\n\n" +

        $"(_ansi default_dimmed)💡 Config commands use active workspace if name not provided\n" +
        $"   Example: provisioning workspace config show --format json(_ansi reset)\n"
    )
}

# Platform services category help
def help-platform []: nothing -> string {
    (
        $"(_ansi red_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi red_bold)║(_ansi reset)  🖥️  PLATFORM SERVICES                           (_ansi red_bold)║(_ansi reset)\n" +
        $"(_ansi red_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Control Center](_ansi reset) (_ansi cyan_bold)🌐 Web UI + Policy Engine(_ansi reset)\n" +
        $"  (_ansi blue)control-center server(_ansi reset)\t\t\t - Start Cedar policy engine (_ansi cyan)--port 8080(_ansi reset)\n" +
        $"  (_ansi blue)control-center policy validate(_ansi reset)\t - Validate Cedar policies\n" +
        $"  (_ansi blue)control-center policy test(_ansi reset)\t\t - Test policies with data\n" +
        $"  (_ansi blue)control-center compliance soc2(_ansi reset)\t - SOC2 compliance check\n" +
        $"  (_ansi blue)control-center compliance hipaa(_ansi reset)\t - HIPAA compliance check\n\n" +

        $"(_ansi cyan_bold)  🎨 Features:(_ansi reset)\n" +
        $"    • (_ansi green)Web-based UI(_ansi reset)\t - WASM-powered control center interface\n" +
        $"    • (_ansi green)Policy Engine(_ansi reset)\t - Cedar policy evaluation and versioning\n" +
        $"    • (_ansi green)Compliance(_ansi reset)\t - SOC2 Type II and HIPAA validation\n" +
        $"    • (_ansi green)Security(_ansi reset)\t\t - JWT auth, MFA, RBAC, anomaly detection\n" +
        $"    • (_ansi green)Audit Trail(_ansi reset)\t - Complete compliance audit logging\n\n" +

        $"(_ansi green_bold)[Orchestrator](_ansi reset) Hybrid Rust/Nushell Coordination\n" +
        $"  (_ansi blue)orchestrator start(_ansi reset)    - Start orchestrator [--background]\n" +
        $"  (_ansi blue)orchestrator stop(_ansi reset)     - Stop orchestrator\n" +
        $"  (_ansi blue)orchestrator status(_ansi reset)   - Check if running\n" +
        $"  (_ansi blue)orchestrator health(_ansi reset)   - Health check with diagnostics\n" +
        $"  (_ansi blue)orchestrator logs(_ansi reset)     - View logs [--follow]\n\n" +

        $"(_ansi green_bold)[MCP Server](_ansi reset) AI-Assisted DevOps Integration\n" +
        $"  (_ansi blue)mcp-server start(_ansi reset)      - Start MCP server [--debug]\n" +
        $"  (_ansi blue)mcp-server status(_ansi reset)     - Check server status\n\n" +

        $"(_ansi cyan_bold)  🤖 Features:(_ansi reset)\n" +
        $"    • (_ansi green)AI-Powered Parsing(_ansi reset) - Natural language to infrastructure\n" +
        $"    • (_ansi green)Multi-Provider(_ansi reset)\t - AWS, UpCloud, Local support\n" +
        $"    • (_ansi green)Ultra-Fast(_ansi reset)\t - Microsecond latency, 1000x faster than Python\n" +
        $"    • (_ansi green)Type Safe(_ansi reset)\t\t - Compile-time guarantees with zero runtime errors\n\n" +

        $"(_ansi green_bold)🌐 REST API ENDPOINTS(_ansi reset)\n\n" +
        $"(_ansi yellow)Control Center(_ansi reset) - (_ansi default_dimmed)http://localhost:8080(_ansi reset)\n" +
        $"  • POST /policies/evaluate  - Evaluate policy decisions\n" +
        $"  • GET /policies            - List all policies\n" +
        $"  • GET /compliance/soc2     - SOC2 compliance check\n" +
        $"  • GET /anomalies           - List detected anomalies\n\n" +

        $"(_ansi yellow)Orchestrator(_ansi reset) - (_ansi default_dimmed)http://localhost:8080(_ansi reset)\n" +
        $"  • GET /health                    - Health check\n" +
        $"  • GET /tasks                     - List all tasks\n" +
        $"  • POST /workflows/servers/create - Server workflow\n" +
        $"  • POST /workflows/batch/submit   - Batch workflow\n\n" +

        $"(_ansi default_dimmed)💡 Control Center provides a (_ansi cyan_bold)web-based UI(_ansi reset)(_ansi default_dimmed) for managing policies!\n" +
        $"   Access at: (_ansi cyan)http://localhost:8080(_ansi reset) (_ansi default_dimmed)after starting the server\n" +
        $"   Example: provisioning control-center server --port 8080(_ansi reset)\n"
    )
}

# Setup category help - System initialization and configuration
def help-setup []: nothing -> string {
    (
        $"(_ansi magenta_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi magenta_bold)║(_ansi reset)  ⚙️  SYSTEM SETUP & CONFIGURATION                 (_ansi magenta_bold)║(_ansi reset)\n" +
        $"(_ansi magenta_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Initial Setup](_ansi reset) First-Time System Configuration\n" +
        $"  (_ansi blue)provisioning setup system(_ansi reset)           - Complete system setup wizard\n" +
        $"    • Interactive TUI mode \(default\)\n" +
        $"    • Detects OS and configures paths\n" +
        $"    • Sets up platform services\n" +
        $"    • Configures cloud providers\n" +
        $"    • Initializes security \(KMS, auth\)\n" +
        $"    (_ansi default_dimmed)Flags: --interactive, --config <file>, --defaults(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Workspace Setup](_ansi reset) Create and Configure Workspaces\n" +
        $"  (_ansi blue)provisioning setup workspace <name>(_ansi reset)  - Create new workspace\n" +
        $"    • Initialize workspace structure\n" +
        $"    • Configure workspace-specific settings\n" +
        $"    • Set active providers\n" +
        $"    (_ansi default_dimmed)Flags: --activate, --config <file>, --interactive(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Provider Setup](_ansi reset) Cloud Provider Configuration\n" +
        $"  (_ansi blue)provisioning setup provider <name>(_ansi reset)  - Configure cloud provider\n" +
        $"    • upcloud - UpCloud provider \(API key, zones\)\n" +
        $"    • aws - Amazon Web Services \(access key, region\)\n" +
        $"    • hetzner - Hetzner Cloud \(token, datacenter\)\n" +
        $"    • local - Local docker/podman provider\n" +
        $"    (_ansi default_dimmed)Flags: --global, --workspace <name>, --credentials(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Platform Setup](_ansi reset) Infrastructure Services\n" +
        $"  (_ansi blue)provisioning setup platform(_ansi reset)          - Setup platform services\n" +
        $"    • Orchestrator \(workflow coordination\)\n" +
        $"    • Control Center \(policy engine, web UI\)\n" +
        $"    • KMS Service \(encryption backend\)\n" +
        $"    • MCP Server \(AI-assisted operations\)\n" +
        $"    (_ansi default_dimmed)Flags: --mode solo|multiuser|cicd|enterprise, --deployment docker|k8s|podman(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Update Configuration](_ansi reset) Modify Existing Setup\n" +
        $"  (_ansi blue)provisioning setup update(_ansi reset) [category]        - Update existing settings\n" +
        $"    • provider - Update provider credentials\n" +
        $"    • platform - Update platform service config\n" +
        $"    • preferences - Update user preferences\n" +
        $"    (_ansi default_dimmed)Flags: --workspace <name>, --check(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Setup Modes](_ansi reset)\n\n" +
        $"  (_ansi blue_bold)Interactive(_ansi reset) (_ansi green)Default(_ansi reset)\n" +
        $"    Beautiful TUI wizard with validation\n" +
        $"    Use: (_ansi cyan)provisioning setup system --interactive(_ansi reset)\n\n" +

        $"  (_ansi blue_bold)Configuration File(_ansi reset)\n" +
        $"    Load settings from TOML/YAML\n" +
        $"    Use: (_ansi cyan)provisioning setup system --config config.toml(_ansi reset)\n\n" +

        $"  (_ansi blue_bold)Defaults Mode(_ansi reset)\n" +
        $"    Auto-detect and use sensible defaults\n" +
        $"    Use: (_ansi cyan)provisioning setup system --defaults(_ansi reset)\n\n" +

        $"(_ansi green_bold)SETUP PHASES(_ansi reset)\n\n" +
        $"  1. (_ansi cyan)System Setup(_ansi reset)      Initialize OS-appropriate paths and services\n" +
        $"  2. (_ansi cyan)Workspace(_ansi reset)         Create infrastructure project workspace\n" +
        $"  3. (_ansi cyan)Providers(_ansi reset)       Register cloud providers with credentials\n" +
        $"  4. (_ansi cyan)Platform(_ansi reset)       Launch orchestration and control services\n" +
        $"  5. (_ansi cyan)Validation(_ansi reset)     Verify all components working\n\n" +

        $"(_ansi green_bold)QUICK START EXAMPLES(_ansi reset)\n\n" +

        $"  # Interactive system setup \(recommended\)\n" +
        $"  provisioning setup system\n\n" +

        $"  # Create workspace\n" +
        $"  provisioning setup workspace myproject\n" +
        $"  provisioning workspace activate myproject\n\n" +

        $"  # Configure provider\n" +
        $"  provisioning setup provider upcloud\n\n" +

        $"  # Setup platform services\n" +
        $"  provisioning setup platform --mode solo\n\n" +

        $"  # Update existing provider\n" +
        $"  provisioning setup update provider --workspace myproject\n\n" +

        $"(_ansi green_bold)CONFIGURATION HIERARCHY(_ansi reset)\n\n" +
        $"  Settings are loaded in order \(highest priority wins\):\n\n" +
        $"  1. (_ansi blue)Runtime Arguments(_ansi reset)   - CLI flags \(--flag value\)\n" +
        $"  2. (_ansi blue)Environment Variables(_ansi reset) - PROVISIONING_* variables\n" +
        $"  3. (_ansi blue)Workspace Config(_ansi reset)    - workspace/config/provisioning.k\n" +
        $"  4. (_ansi blue)User Preferences(_ansi reset)    - ~/.config/provisioning/user_config.yaml\n" +
        $"  5. (_ansi blue)System Defaults(_ansi reset)    - Built-in configuration\n\n" +

        $"(_ansi green_bold)DIRECTORIES CREATED(_ansi reset)\n\n" +

        $"  macOS:  $$HOME/Library/Application\\ Support/provisioning/\n" +
        $"  Linux:  $$HOME/.config/provisioning/\n" +
        $"  Windows: $$APPDATA/provisioning/\n\n" +

        $"  Structure:\n" +
        $"  ├── system.toml              \(OS info, immutable paths\)\n" +
        $"  ├── platform/*.toml          \(Orchestrator, Control Center, KMS\)\n" +
        $"  ├── providers/*.toml         \(Cloud provider configs\)\n" +
        $"  ├── workspaces/\n" +
        $"  │   └── <name>/\n" +
        $"  │       └── auth.token       \(Workspace authentication\)\n" +
        $"  └── user_preferences.toml    \(User settings, overridable\)\n\n" +

        $"(_ansi green_bold)SECURITY & CREDENTIALS(_ansi reset)\n\n" +
        $"  • RustyVault: Primary credentials storage \(encrypt/decrypt at rest\)\n" +
        $"  • SOPS/Age:   Bootstrap encryption for RustyVault key only\n" +
        $"  • Cedar:      Fine-grained access policies\n" +
        $"  • KMS:        Configurable backend \(RustyVault, Age, AWS, Vault\)\n" +
        $"  • Audit:      Complete operation logging with GDPR compliance\n\n" +

        $"(_ansi green_bold)HELP LINKS(_ansi reset)\n\n" +
        $"  provisioning help workspace      - Workspace management\n" +
        $"  provisioning help platform       - Platform services\n" +
        $"  provisioning help authentication - Auth and security\n" +
        $"  provisioning guide from-scratch  - Complete deployment guide\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Most setup operations support --check for dry-run mode\n" +
        $"   Example: provisioning setup platform --mode solo --check\n" +
        $"   Use provisioning guide from-scratch for step-by-step walkthrough(_ansi reset)\n"
    )
}

# Concepts help - Understanding the system
def help-concepts []: nothing -> string {
    (
        $"(_ansi yellow_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║(_ansi reset)  💡 ARCHITECTURE & KEY CONCEPTS                  (_ansi yellow_bold)║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)1. LAYER SYSTEM(_ansi reset) (_ansi cyan)Configuration Inheritance(_ansi reset)\n\n" +
        $"   The system uses a (_ansi cyan)3-layer architecture(_ansi reset) for configuration:\n\n" +
        $"   (_ansi blue)Core Layer (100)(_ansi reset)\n" +
        $"   └─ Base system extensions (_ansi default_dimmed)provisioning/extensions/(_ansi reset)\n" +
        $"      • Standard provider implementations\n" +
        $"      • Default taskserv configurations\n" +
        $"      • Built-in cluster templates\n\n" +

        $"   (_ansi blue)Workspace Layer (200)(_ansi reset)\n" +
        $"   └─ Shared templates (_ansi default_dimmed)provisioning/workspace/templates/(_ansi reset)\n" +
        $"      • Reusable infrastructure patterns\n" +
        $"      • Organization-wide standards\n" +
        $"      • Team conventions\n\n" +

        $"   (_ansi blue)Infrastructure Layer (300)(_ansi reset)\n" +
        $"   └─ Specific overrides (_ansi default_dimmed)workspace/infra/\{name\}/(_ansi reset)\n" +
        $"      • Project-specific configurations\n" +
        $"      • Environment customizations\n" +
        $"      • Local overrides\n\n" +

        $"   (_ansi green)Resolution Order:(_ansi reset) Infrastructure (300) → Workspace (200) → Core (100)\n" +
        $"   (_ansi default_dimmed)Higher numbers override lower numbers(_ansi reset)\n\n" +

        $"(_ansi green_bold)2. MODULE SYSTEM(_ansi reset) (_ansi cyan)Reusable Components(_ansi reset)\n\n" +
        $"   (_ansi blue)Taskservs(_ansi reset) - Infrastructure services\n" +
        $"   • kubernetes, containerd, cilium, redis, postgres\n" +
        $"   • Installed on servers, configured per environment\n\n" +

        $"   (_ansi blue)Providers(_ansi reset) - Cloud platforms\n" +
        $"   • upcloud, aws, local with docker or podman\n" +
        $"   • Provider-agnostic middleware supports multi-cloud\n\n" +

        $"   (_ansi blue)Clusters(_ansi reset) - Complete configurations\n" +
        $"   • buildkit, ci-cd, monitoring\n" +
        $"   • Orchestrated deployments with dependencies\n\n" +

        $"(_ansi green_bold)3. WORKFLOW TYPES(_ansi reset)\n\n" +
        $"   (_ansi blue)Single Workflows(_ansi reset)\n" +
        $"   • Individual server/taskserv/cluster operations\n" +
        $"   • Real-time monitoring, state management\n\n" +

        $"   (_ansi blue)Batch Workflows(_ansi reset)\n" +
        $"   • Multi-provider operations: UpCloud, AWS, and local\n" +
        $"   • Dependency resolution, rollback support\n" +
        $"   • Defined in KCL workflow files\n\n" +

        $"(_ansi green_bold)4. TYPICAL WORKFLOW(_ansi reset)\n\n" +
        $"   1. (_ansi cyan)Create workspace(_ansi reset):     workspace init my-project\n" +
        $"   2. (_ansi cyan)Discover modules(_ansi reset):     module discover taskservs\n" +
        $"   3. (_ansi cyan)Load modules(_ansi reset):         module load taskservs my-project kubernetes\n" +
        $"   4. (_ansi cyan)Create servers(_ansi reset):       server create --infra my-project\n" +
        $"   5. (_ansi cyan)Deploy taskservs(_ansi reset):     taskserv create kubernetes\n" +
        $"   6. (_ansi cyan)Check layers(_ansi reset):         layer show my-project\n\n" +

        $"(_ansi default_dimmed)💡 For more details:\n" +
        $"   • provisioning layer explain  - Layer system deep dive\n" +
        $"   • provisioning help development - Module system commands(_ansi reset)\n"
    )
}

# Guides category help
def help-guides []: nothing -> string {
    (
        $"(_ansi magenta_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi magenta_bold)║(_ansi reset)  📚 GUIDES & CHEATSHEETS                          (_ansi magenta_bold)║(_ansi reset)\n" +
        $"(_ansi magenta_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Quick Reference](_ansi reset) Copy-Paste Ready Commands\n" +
        $"  (_ansi blue)sc(_ansi reset)                 - Quick command reference (_ansi yellow)fastest(_ansi reset)\n" +
        $"  (_ansi blue)guide quickstart(_ansi reset)   - Full command cheatsheet with examples\n\n" +

        $"(_ansi green_bold)[Step-by-Step Guides](_ansi reset) Complete Walkthroughs\n" +
        $"  (_ansi blue)guide from-scratch(_ansi reset) - Complete deployment from zero to production\n" +
        $"  (_ansi blue)guide update(_ansi reset)       - Update existing infrastructure safely\n" +
        $"  (_ansi blue)guide customize(_ansi reset)    - Customize with layers and templates\n\n" +

        $"(_ansi green_bold)[Guide Topics](_ansi reset)\n" +
        $"  (_ansi cyan)Quickstart Cheatsheet:(_ansi reset)\n" +
        $"    • All command shortcuts reference\n" +
        $"    • Copy-paste ready commands\n" +
        $"    • Common workflow examples\n\n" +

        $"  (_ansi cyan)From Scratch Guide:(_ansi reset)\n" +
        $"    • Prerequisites and setup\n" +
        $"    • Initialize workspace\n" +
        $"    • Deploy complete infrastructure\n" +
        $"    • Verify deployment\n\n" +

        $"  (_ansi cyan)Update Guide:(_ansi reset)\n" +
        $"    • Check for updates\n" +
        $"    • Update strategies\n" +
        $"    • Rolling updates\n" +
        $"    • Rollback procedures\n\n" +

        $"  (_ansi cyan)Customize Guide:(_ansi reset)\n" +
        $"    • Layer system explained\n" +
        $"    • Using templates\n" +
        $"    • Creating custom modules\n" +
        $"    • Advanced customization patterns\n\n" +

        $"(_ansi green_bold)📖 USAGE EXAMPLES(_ansi reset)\n\n" +
        $"  # Show quick reference\n" +
        $"  provisioning sc  (_ansi default_dimmed)# fastest(_ansi reset)\n\n" +

        $"  # Show full cheatsheet\n" +
        $"  provisioning guide quickstart\n\n" +

        $"  # Complete deployment guide\n" +
        $"  provisioning guide from-scratch\n\n" +

        $"  # Update infrastructure guide\n" +
        $"  provisioning guide update\n\n" +

        $"  # Customization guide\n" +
        $"  provisioning guide customize\n\n" +

        $"  # List all guides\n" +
        $"  provisioning guide list\n" +
        $"  provisioning howto  (_ansi default_dimmed)# shortcut(_ansi reset)\n\n" +

        $"(_ansi green_bold)🎯 QUICK ACCESS(_ansi reset)\n\n" +
        $"  (_ansi cyan)Shortcuts:(_ansi reset)\n" +
        $"    • (_ansi blue_bold)sc(_ansi reset)\t   → Quick reference (_ansi default_dimmed)fastest, no pager(_ansi reset)\n" +
        $"    • (_ansi blue)quickstart(_ansi reset)   → shortcuts, quick\n" +
        $"    • (_ansi blue)from-scratch(_ansi reset) → scratch, start, deploy\n" +
        $"    • (_ansi blue)update(_ansi reset)\t   → upgrade\n" +
        $"    • (_ansi blue)customize(_ansi reset)\t   → custom, layers, templates\n\n" +

        $"(_ansi default_dimmed)💡 All guides provide (_ansi cyan_bold)copy-paste ready commands(_ansi reset)(_ansi default_dimmed) that you can\n" +
        $"   adjust and use immediately. Perfect for quick start!\n" +
        $"   Example: provisioning guide quickstart | less(_ansi reset)\n"
    )
}

# Authentication category help
def help-authentication []: nothing -> string {
    (
        $"(_ansi yellow_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║(_ansi reset)  🔐 AUTHENTICATION & SECURITY                    (_ansi yellow_bold)║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Session Management](_ansi reset) JWT Token Authentication\n" +
        $"  (_ansi blue)auth login <username>(_ansi reset)     Login and store JWT tokens\n" +
        $"  (_ansi blue)auth logout(_ansi reset)               Logout and clear tokens\n" +
        $"  (_ansi blue)auth status(_ansi reset)               Show current authentication status\n" +
        $"  (_ansi blue)auth sessions(_ansi reset)             List active sessions\n" +
        $"  (_ansi blue)auth refresh(_ansi reset)              Verify/refresh token\n\n" +

        $"(_ansi green_bold)[Multi-Factor Auth](_ansi reset) TOTP and WebAuthn Support\n" +
        $"  (_ansi blue)auth mfa enroll <type>(_ansi reset)    Enroll in MFA [totp or webauthn]\n" +
        $"  (_ansi blue)auth mfa verify --code <code>(_ansi reset) Verify MFA code\n\n" +

        $"(_ansi green_bold)[Authentication Features](_ansi reset)\n" +
        $"  • (_ansi cyan)JWT tokens(_ansi reset) with RS256 asymmetric signing\n" +
        $"  • (_ansi cyan)15-minute(_ansi reset) access tokens with 7-day refresh\n" +
        $"  • (_ansi cyan)TOTP MFA(_ansi reset) [Google Authenticator, Authy]\n" +
        $"  • (_ansi cyan)WebAuthn/FIDO2(_ansi reset) [YubiKey, Touch ID, Windows Hello]\n" +
        $"  • (_ansi cyan)Role-based access(_ansi reset) [Admin, Developer, Operator, Viewer, Auditor]\n" +
        $"  • (_ansi cyan)HTTP fallback(_ansi reset) when nu_plugin_auth unavailable\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +
        $"  # Login interactively\n" +
        $"  provisioning auth login\n" +
        $"  provisioning login admin  (_ansi default_dimmed)# shortcut(_ansi reset)\n\n" +

        $"  # Check status\n" +
        $"  provisioning auth status\n" +
        $"  provisioning whoami       (_ansi default_dimmed)# shortcut(_ansi reset)\n\n" +

        $"  # Enroll in TOTP MFA\n" +
        $"  provisioning auth mfa enroll totp\n" +
        $"  provisioning mfa-enroll totp      (_ansi default_dimmed)# shortcut(_ansi reset)\n\n" +

        $"  # Verify MFA code\n" +
        $"  provisioning auth mfa verify --code 123456\n" +
        $"  provisioning mfa-verify --code 123456      (_ansi default_dimmed)# shortcut(_ansi reset)\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  login      → auth login\n" +
        $"  logout     → auth logout\n" +
        $"  whoami     → auth status\n" +
        $"  mfa        → auth mfa\n" +
        $"  mfa-enroll → auth mfa enroll\n" +
        $"  mfa-verify → auth mfa verify\n\n" +

        $"(_ansi default_dimmed)💡 MFA is required for production and destructive operations\n" +
        $"   Tokens stored securely in system keyring when plugin available\n" +
        $"   Use 'provisioning help mfa' for detailed MFA information(_ansi reset)\n"
    )
}

# MFA help
def help-mfa []: nothing -> string {
    (
        $"(_ansi yellow_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║(_ansi reset)  🔐 MULTI-FACTOR AUTHENTICATION                  (_ansi yellow_bold)║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[MFA Types](_ansi reset)\n\n" +
        $"  (_ansi blue_bold)TOTP [Time-based One-Time Password](_ansi reset)\n" +
        $"    • 6-digit codes that change every 30 seconds\n" +
        $"    • Works with Google Authenticator, Authy, 1Password, etc.\n" +
        $"    • No internet required after setup\n" +
        $"    • QR code for easy enrollment\n\n" +

        $"  (_ansi blue_bold)WebAuthn/FIDO2(_ansi reset)\n" +
        $"    • Hardware security keys [YubiKey, Titan Key]\n" +
        $"    • Biometric authentication [Touch ID, Face ID, Windows Hello]\n" +
        $"    • Phishing-resistant\n" +
        $"    • No codes to type\n\n" +

        $"(_ansi green_bold)[Enrollment Process](_ansi reset)\n\n" +
        $"  1. (_ansi cyan)Login first(_ansi reset):        provisioning auth login\n" +
        $"  2. (_ansi cyan)Enroll in MFA(_ansi reset):      provisioning auth mfa enroll totp\n" +
        $"  3. (_ansi cyan)Scan QR code(_ansi reset):       Use authenticator app\n" +
        $"  4. (_ansi cyan)Verify setup(_ansi reset):       provisioning auth mfa verify --code <code>\n" +
        $"  5. (_ansi cyan)Save backup codes(_ansi reset):  Store securely [shown after verification]\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +
        $"  # Enroll in TOTP\n" +
        $"  provisioning auth mfa enroll totp\n\n" +

        $"  # Scan QR code with authenticator app\n" +
        $"  # Then verify with 6-digit code\n" +
        $"  provisioning auth mfa verify --code 123456\n\n" +

        $"  # Enroll in WebAuthn\n" +
        $"  provisioning auth mfa enroll webauthn\n\n" +

        $"(_ansi green_bold)MFA REQUIREMENTS(_ansi reset)\n\n" +
        $"  (_ansi yellow)Production Operations(_ansi reset):  MFA required for prod environment\n" +
        $"  (_ansi yellow)Destructive Operations(_ansi reset): MFA required for delete/destroy\n" +
        $"  (_ansi yellow)Admin Operations(_ansi reset):       MFA recommended for all admins\n\n" +

        $"(_ansi default_dimmed)💡 MFA enrollment requires active authentication session\n" +
        $"   Backup codes provided after verification - store securely!\n" +
        $"   Can enroll multiple devices for redundancy(_ansi reset)\n"
    )
}

# Plugins category help
def help-plugins []: nothing -> string {
    (
        $"(_ansi cyan_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi cyan_bold)║(_ansi reset)  🔌 PLUGIN MANAGEMENT                            (_ansi cyan_bold)║(_ansi reset)\n" +
        $"(_ansi cyan_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Critical Provisioning Plugins](_ansi reset) (_ansi yellow)10-30x FASTER(_ansi reset)\n\n" +
        $"  (_ansi blue_bold)nu_plugin_auth(_ansi reset) (_ansi cyan)~10x faster(_ansi reset)\n" +
        $"    • JWT authentication with RS256 signing\n" +
        $"    • Secure token storage in system keyring\n" +
        $"    • TOTP and WebAuthn MFA support\n" +
        $"    • Commands: auth login, logout, verify, sessions, mfa\n" +
        $"    • HTTP fallback when unavailable\n\n" +

        $"  (_ansi blue_bold)nu_plugin_kms(_ansi reset) (_ansi cyan)~10x faster(_ansi reset)\n" +
        $"    • Multi-backend encryption: RustyVault, Age, AWS KMS, Vault, Cosmian\n" +
        $"    • Envelope encryption and key rotation\n" +
        $"    • Commands: kms encrypt, decrypt, generate-key, status, list-backends\n" +
        $"    • HTTP fallback when unavailable\n\n" +

        $"  (_ansi blue_bold)nu_plugin_orchestrator(_ansi reset) (_ansi cyan)~30x faster(_ansi reset)\n" +
        "    • Direct file-based state access (no HTTP)\n" +
        $"    • KCL workflow validation\n" +
        $"    • Commands: orch status, tasks, validate, submit, monitor\n" +
        $"    • Local task queue operations\n\n" +

        $"(_ansi green_bold)[Plugin Operations](_ansi reset)\n" +
        $"  (_ansi blue)plugin list(_ansi reset)              List all plugins with status\n" +
        $"  (_ansi blue)plugin register <name>(_ansi reset)   Register plugin with Nushell\n" +
        $"  (_ansi blue)plugin test <name>(_ansi reset)       Test plugin functionality\n" +
        $"  (_ansi blue)plugin status(_ansi reset)            Show plugin status and performance\n\n" +

        $"(_ansi green_bold)[Additional Plugins](_ansi reset)\n\n" +
        $"  (_ansi blue_bold)nu_plugin_tera(_ansi reset)\n" +
        $"    • Jinja2-compatible template rendering\n" +
        $"    • Used for config generation\n\n" +

        $"  (_ansi blue_bold)nu_plugin_kcl(_ansi reset)\n" +
        $"    • KCL configuration language\n" +
        $"    • Falls back to external KCL CLI\n\n" +

        $"(_ansi green_bold)PERFORMANCE COMPARISON(_ansi reset)\n\n" +
        $"  Operation           Plugin     HTTP Fallback\n" +
        $"  ─────────────────────────────────────────────\n" +
        $"  Auth verify         ~10ms      ~50ms\n" +
        $"  KMS encrypt         ~5ms       ~50ms\n" +
        $"  Orch status         ~1ms       ~30ms\n\n" +

        $"(_ansi green_bold)INSTALLATION(_ansi reset)\n\n" +
        $"  # Install all provisioning plugins\n" +
        $"  nu provisioning/core/plugins/install-plugins.nu\n\n" +

        $"  # Register pre-built plugins only\n" +
        $"  nu provisioning/core/plugins/install-plugins.nu --skip-build\n\n" +

        $"  # Test plugin functionality\n" +
        $"  nu provisioning/core/plugins/test-plugins.nu\n\n" +

        $"  # Verify registration\n" +
        $"  plugin list\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +
        $"  # Check plugin status\n" +
        $"  provisioning plugin status\n\n" +

        $"  # Use auth plugin\n" +
        $"  provisioning auth login admin\n" +
        $"  provisioning auth verify\n\n" +

        $"  # Use KMS plugin\n" +
        $"  provisioning kms encrypt \"secret\" --backend age\n" +
        $"  provisioning kms status\n\n" +

        $"  # Use orchestrator plugin\n" +
        $"  provisioning orch status\n" +
        $"  provisioning orch tasks --status pending\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  plugin-list → plugin list\n" +
        $"  plugin-add  → plugin register\n" +
        $"  plugin-test → plugin test\n" +
        $"  auth        → integrations auth\n" +
        $"  kms         → integrations kms\n" +
        $"  encrypt     → kms encrypt\n" +
        $"  decrypt     → kms decrypt\n\n" +

        $"(_ansi default_dimmed)💡 Plugins provide 10-30x performance improvement\n" +
        $"   Graceful HTTP fallback when plugins unavailable\n" +
        $"   Config: provisioning/config/plugins.toml(_ansi reset)\n"
    )
}

# Utilities category help
def help-utilities []: nothing -> string {
    (
        $"(_ansi green_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi green_bold)║(_ansi reset)  🛠️  UTILITIES & TOOLS                          (_ansi green_bold)║(_ansi reset)\n" +
        $"(_ansi green_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Cache Management](_ansi reset) Configuration Caching\n" +
        $"  (_ansi blue)cache status(_ansi reset)                  - Show cache configuration and statistics\n" +
        $"  (_ansi blue)cache config show(_ansi reset)             - Display all cache settings\n" +
        $"  (_ansi blue)cache config get <setting>(_ansi reset)    - Get specific cache setting [dot notation]\n" +
        $"  (_ansi blue)cache config set <setting> <value>(_ansi reset) - Set cache setting\n" +
        $"  (_ansi blue)cache list [--type <type>](_ansi reset)    - List cached items [all|kcl|sops|final]\n" +
        $"  (_ansi blue)cache clear [--type <type>](_ansi reset)   - Clear cache [default: all]\n" +
        $"  (_ansi blue)cache help(_ansi reset)                    - Show cache command help\n\n" +

        $"(_ansi cyan_bold)  📊 Cache Features:(_ansi reset)\n" +
        $"    • Intelligent TTL management \(KCL: 30m, SOPS: 15m, Final: 5m\)\n" +
        $"    • mtime-based validation for stale data detection\n" +
        $"    • SOPS cache with 0600 permissions\n" +
        $"    • Configurable cache size \(default: 100 MB\)\n" +
        $"    • Works without active workspace\n" +
        $"    • Performance: 95-98% faster config loading\n\n" +

        $"(_ansi cyan_bold)  ⚡ Performance Impact:(_ansi reset)\n" +
        $"    • Cache hit: <10ms \(vs 200-500ms cold load\)\n" +
        $"    • Help commands: <5ms \(near-instant\)\n" +
        $"    • Expected hit rate: 70-85%\n\n" +

        $"(_ansi green_bold)[Secrets Management](_ansi reset) SOPS Encryption\n" +
        $"  (_ansi blue)sops <file>(_ansi reset)                  - Edit encrypted file with SOPS\n" +
        $"  (_ansi blue)encrypt <file>(_ansi reset)               - Encrypt file \(alias: kms encrypt\)\n" +
        $"  (_ansi blue)decrypt <file>(_ansi reset)               - Decrypt file \(alias: kms decrypt\)\n\n" +

        $"(_ansi green_bold)[Provider Operations](_ansi reset) Cloud & Local Providers\n" +
        $"  (_ansi blue)providers list [--kcl] [--format <fmt>](_ansi reset)  - List available providers\n" +
        $"  (_ansi blue)providers info <provider> [--kcl](_ansi reset)        - Show detailed provider info\n" +
        $"  (_ansi blue)providers install <prov> <infra> [--version <v>](_ansi reset) - Install provider\n" +
        $"  (_ansi blue)providers remove <provider> <infra> [--force](_ansi reset)    - Remove provider\n" +
        $"  (_ansi blue)providers installed <infra> [--format <fmt>](_ansi reset)     - List installed\n" +
        $"  (_ansi blue)providers validate <infra>(_ansi reset)               - Validate installation\n\n" +

        $"(_ansi green_bold)[Plugin Management](_ansi reset) Native Performance\n" +
        $"  (_ansi blue)plugin list(_ansi reset)                  - List installed plugins\n" +
        $"  (_ansi blue)plugin register <name>(_ansi reset)       - Register plugin with Nushell\n" +
        $"  (_ansi blue)plugin test <name>(_ansi reset)           - Test plugin functionality\n" +
        $"  (_ansi blue)plugin status(_ansi reset)                - Show all plugin status\n\n" +

        $"(_ansi green_bold)[SSH Operations](_ansi reset) Remote Access\n" +
        $"  (_ansi blue)ssh <host>(_ansi reset)                   - Connect to server via SSH\n" +
        $"  (_ansi blue)ssh-pool list(_ansi reset)                - List SSH connection pool\n" +
        $"  (_ansi blue)ssh-pool clear(_ansi reset)               - Clear SSH connection cache\n\n" +

        $"(_ansi green_bold)[Miscellaneous](_ansi reset) Utilities\n" +
        $"  (_ansi blue)nu(_ansi reset)                           - Start Nushell session with provisioning lib\n" +
        $"  (_ansi blue)nuinfo(_ansi reset)                       - Show Nushell version and information\n" +
        $"  (_ansi blue)list(_ansi reset)                         - Alias for resource listing\n" +
        $"  (_ansi blue)qr <text>(_ansi reset)                    - Generate QR code\n\n" +

        $"(_ansi green_bold)CACHE CONFIGURATION EXAMPLES(_ansi reset)\n\n" +
        $"  # Check cache status\n" +
        $"  provisioning cache status\n\n" +

        $"  # Get specific cache setting\n" +
        $"  provisioning cache config get ttl_kcl        # Returns: 1800\n" +
        $"  provisioning cache config get enabled        # Returns: true\n\n" +

        $"  # Configure cache\n" +
        $"  provisioning cache config set ttl_kcl 3000   # Change KCL TTL to 50min\n" +
        $"  provisioning cache config set ttl_sops 600   # Change SOPS TTL to 10min\n\n" +

        $"  # List cached items\n" +
        $"  provisioning cache list                      # All cache items\n" +
        $"  provisioning cache list --type kcl           # KCL compilation cache only\n\n" +

        $"  # Clear cache\n" +
        $"  provisioning cache clear                     # Clear all\n" +
        $"  provisioning cache clear --type sops         # Clear SOPS cache only\n\n" +

        $"(_ansi green_bold)CACHE SETTINGS REFERENCE(_ansi reset)\n\n" +
        $"  enabled              - Enable/disable cache \(true/false\)\n" +
        $"  ttl_final_config     - Final merged config TTL in seconds \(default: 300/5min\)\n" +
        $"  ttl_kcl              - KCL compilation TTL \(default: 1800/30min\)\n" +
        $"  ttl_sops             - SOPS decryption TTL \(default: 900/15min\)\n" +
        $"  max_cache_size       - Maximum cache size in bytes \(default: 104857600/100MB\)\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  cache        → utils cache\n" +
        $"  providers    → utils providers\n" +
        $"  sops         → utils sops\n" +
        $"  ssh          → integrations ssh\n" +
        $"  ssh-pool     → integrations ssh\n" +
        $"  plugin/plugins → utils plugin\n\n" +

        $"(_ansi default_dimmed)💡 Cache is enabled by default\n" +
        $"   Disable with: provisioning cache config set enabled false\n" +
        $"   Or use CLI flag: provisioning --no-cache command\n" +
        $"   All commands work without active workspace(_ansi reset)\n"
    )
}

# Tools management category help
def help-tools []: nothing -> string {
    (
        $"(_ansi yellow_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║(_ansi reset)  🔧 TOOLS & DEPENDENCIES                      (_ansi yellow_bold)║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Installation](_ansi reset) Tool Setup\n" +
        $"  (_ansi blue)tools install(_ansi reset)        - Install all tools\n" +
        $"  (_ansi blue)tools install <tool>(_ansi reset) - Install specific tool [aws|hcloud|upctl]\n" +
        $"  (_ansi blue)tools install --update(_ansi reset) - Force reinstall all tools\n\n" +

        $"(_ansi green_bold)[Version Management](_ansi reset) Tool Versions\n" +
        $"  (_ansi blue)tools check(_ansi reset)          - Check all tool versions\n" +
        $"  (_ansi blue)tools versions(_ansi reset)       - Show configured versions\n" +
        $"  (_ansi blue)tools check-updates(_ansi reset)  - Check for available updates\n" +
        $"  (_ansi blue)tools apply-updates(_ansi reset)  - Apply configuration updates [--dry-run]\n\n" +

        $"(_ansi green_bold)[Tool Information](_ansi reset) Tool Details\n" +
        $"  (_ansi blue)tools show(_ansi reset)           - Display tool information\n" +
        $"  (_ansi blue)tools show all(_ansi reset)       - Show all tools and providers\n" +
        $"  (_ansi blue)tools show <tool>(_ansi reset)    - Tool-specific information\n" +
        $"  (_ansi blue)tools show provider(_ansi reset)  - Show provider information\n\n" +

        $"(_ansi green_bold)[Pinning & Configuration](_ansi reset) Version Control\n" +
        $"  (_ansi blue)tools pin <tool>(_ansi reset)     - Pin tool to current version \(prevent auto-update\)\n" +
        $"  (_ansi blue)tools unpin <tool>(_ansi reset)   - Unpin tool \(allow auto-update\)\n\n" +

        $"(_ansi green_bold)[Provider Tools](_ansi reset) Cloud CLI Tools\n" +
        $"  (_ansi blue)tools check aws(_ansi reset)      - Check AWS CLI status\n" +
        $"  (_ansi blue)tools check hcloud(_ansi reset)   - Check Hetzner CLI status\n" +
        $"  (_ansi blue)tools check upctl(_ansi reset)    - Check UpCloud CLI status\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +

        $"  # Check all tool versions\n" +
        $"  provisioning tools check\n\n" +

        $"  # Check specific provider tool\n" +
        $"  provisioning tools check hcloud\n" +
        $"  provisioning tools versions\n\n" +

        $"  # Check for updates and apply\n" +
        $"  provisioning tools check-updates\n" +
        $"  provisioning tools apply-updates --dry-run\n" +
        $"  provisioning tools apply-updates\n\n" +

        $"  # Install or update tools\n" +
        $"  provisioning tools install\n" +
        $"  provisioning tools install --update\n" +
        $"  provisioning tools install hcloud\n\n" +

        $"  # Pin/unpin specific tools\n" +
        $"  provisioning tools pin upctl        # Lock to current version\n" +
        $"  provisioning tools unpin upctl      # Allow updates\n\n" +

        $"(_ansi green_bold)SUPPORTED TOOLS(_ansi reset)\n\n" +

        $"  • (_ansi cyan)aws(_ansi reset)     - AWS CLI v2 \(Cloud provider tool\)\n" +
        $"  • (_ansi cyan)hcloud(_ansi reset)  - Hetzner Cloud CLI \(Cloud provider tool\)\n" +
        $"  • (_ansi cyan)upctl(_ansi reset)   - UpCloud CLI \(Cloud provider tool\)\n" +
        $"  • (_ansi cyan)kcl(_ansi reset)     - KCL configuration language\n" +
        $"  • (_ansi cyan)nu(_ansi reset)      - Nushell scripting engine\n\n" +

        $"(_ansi green_bold)VERSION INFORMATION(_ansi reset)\n\n" +

        $"  Each tool can have:\n" +
        $"    - Configured version: Target version in config\n" +
        $"    - Installed version:  Currently installed on system\n" +
        $"    - Latest version:     Available upstream\n" +
        $"    - Status:             not_installed, installed, update_available, or ahead\n\n" +

        $"(_ansi green_bold)TOOL STATUS MEANINGS(_ansi reset)\n\n" +

        $"  not_installed   - Tool not found on system, needs installation\n" +
        $"  installed       - Tool is installed and version matches config\n" +
        $"  update_available - Newer version available, can be updated\n" +
        $"  ahead           - Installed version is newer than configured\n" +
        $"  behind          - Installed version is older than configured\n\n" +

        $"(_ansi default_dimmed)💡 Use 'provisioning tools install' to set up all required tools\n" +
        $"   Most tools are optional but recommended for specific cloud providers\n" +
        $"   Pinning ensures version stability for production deployments(_ansi reset)\n"
    )
}

# Diagnostics category help
def help-diagnostics []: nothing -> string {
    (
        $"(_ansi green_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi green_bold)║(_ansi reset)  🔍 DIAGNOSTICS & SYSTEM HEALTH                (_ansi green_bold)║(_ansi reset)\n" +
        $"(_ansi green_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[System Status](_ansi reset) Component Verification\n" +
        $"  (_ansi blue)status(_ansi reset)             - Show comprehensive system status\n" +
        "    • Nushell version check (requires 0.109.0+)\n" +
        $"    • KCL CLI installation and version\n" +
        "    • Nushell plugins (auth, KMS, tera, kcl, orchestrator)\n" +
        $"    • Active workspace configuration\n" +
        $"    • Cloud providers availability\n" +
        $"    • Orchestrator service status\n" +
        "    • Platform services (Control Center, MCP, API Gateway)\n" +
        $"    • Documentation links for each component\n\n" +

        $"  (_ansi blue)status json(_ansi reset)        - Machine-readable status output\n" +
        $"    • Structured JSON output\n" +
        $"    • Health percentage calculation\n" +
        $"    • Ready-for-deployment flag\n\n" +

        $"(_ansi green_bold)[Health Checks](_ansi reset) Deep Validation\n" +
        $"  (_ansi blue)health(_ansi reset)             - Run deep health validation\n" +
        "    • Configuration files (user_config.yaml, provisioning.yaml)\n" +
        "    • Workspace structure (infra/, config/, extensions/, runtime/)\n" +
        "    • Infrastructure state (servers, taskservs, clusters)\n" +
        $"    • Platform services connectivity\n" +
        $"    • KCL schemas validity\n" +
        "    • Security configuration (KMS, auth, SOPS, Age)\n" +
        "    • Provider credentials (UpCloud, AWS)\n" +
        $"    • Fix recommendations with doc links\n\n" +

        $"  (_ansi blue)health json(_ansi reset)        - Machine-readable health output\n" +
        $"    • Structured JSON output\n" +
        $"    • Health score calculation\n" +
        $"    • Production-ready flag\n\n" +

        $"(_ansi green_bold)[Smart Guidance](_ansi reset) Progressive Recommendations\n" +
        $"  (_ansi blue)next(_ansi reset)               - Get intelligent next steps\n" +
        $"    • Phase 1: No workspace → Create workspace\n" +
        $"    • Phase 2: No infrastructure → Define infrastructure\n" +
        $"    • Phase 3: No servers → Deploy servers\n" +
        $"    • Phase 4: No taskservs → Install task services\n" +
        $"    • Phase 5: No clusters → Deploy clusters\n" +
        $"    • Production: Management and monitoring tips\n" +
        $"    • Each step includes commands + documentation links\n\n" +

        $"  (_ansi blue)phase(_ansi reset)              - Show current deployment phase\n" +
        "    • Current phase (initialization → production)\n" +
        "    • Progress percentage (step/total)\n" +
        $"    • Deployment readiness status\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +
        $"  # Quick system status check\n" +
        $"  provisioning status\n\n" +

        $"  # Get machine-readable status\n" +
        $"  provisioning status json\n" +
        $"  provisioning status --out json\n\n" +

        $"  # Run comprehensive health check\n" +
        $"  provisioning health\n\n" +

        $"  # Get next steps recommendation\n" +
        $"  provisioning next\n\n" +

        $"  # Check deployment phase\n" +
        $"  provisioning phase\n\n" +

        $"  # Full diagnostic workflow\n" +
        $"  provisioning status && provisioning health && provisioning next\n\n" +

        $"(_ansi green_bold)OUTPUT FORMATS(_ansi reset)\n\n" +
        $"  • (_ansi cyan)Table Format(_ansi reset): Human-readable with icons and colors\n" +
        $"  • (_ansi cyan)JSON Format(_ansi reset): Machine-readable for automation/CI\n" +
        $"  • (_ansi cyan)Status Icons(_ansi reset): ✅ OK, ⚠️ Warning, ❌ Error\n\n" +

        $"(_ansi green_bold)USE CASES(_ansi reset)\n\n" +
        $"  • (_ansi yellow)First-time setup(_ansi reset): Run `next` for step-by-step guidance\n" +
        $"  • (_ansi yellow)Pre-deployment(_ansi reset): Run `health` to ensure system ready\n" +
        $"  • (_ansi yellow)Troubleshooting(_ansi reset): Run `status` to identify missing components\n" +
        $"  • (_ansi yellow)CI/CD integration(_ansi reset): Use `status json` for automated checks\n" +
        $"  • (_ansi yellow)Progress tracking(_ansi reset): Use `phase` to see deployment progress\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  status → System status\n" +
        $"  health → Health checks\n" +
        $"  next   → Next steps\n" +
        $"  phase  → Deployment phase\n\n" +

        $"(_ansi green_bold)DOCUMENTATION(_ansi reset)\n\n" +
        $"  • Workspace Guide: docs/user/WORKSPACE_SWITCHING_GUIDE.md\n" +
        $"  • Quick Start: docs/guides/quickstart-cheatsheet.md\n" +
        $"  • From Scratch: docs/guides/from-scratch.md\n" +
        $"  • Troubleshooting: docs/user/troubleshooting-guide.md\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Run `provisioning status` first to identify issues\n" +
        $"   Then use `provisioning health` for detailed validation\n" +
        $"   Finally, `provisioning next` shows you what to do(_ansi reset)\n"
    )
}

# Integrations category help
def help-integrations []: nothing -> string {
    (
        $"(_ansi yellow_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi yellow_bold)║(_ansi reset)  🌉 PROV-ECOSYSTEM & PROVCTL INTEGRATIONS          (_ansi yellow_bold)║(_ansi reset)\n" +
        $"(_ansi yellow_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Runtime](_ansi reset) Container Runtime Abstraction\n" +
        $"  (_ansi blue)integrations runtime detect(_ansi reset)     - Detect available runtime \(docker, podman, orbstack, colima, nerdctl\)\n" +
        $"  (_ansi blue)integrations runtime exec(_ansi reset)       - Execute command in detected runtime\n" +
        $"  (_ansi blue)integrations runtime compose(_ansi reset)    - Adapt docker-compose file for runtime\n" +
        $"  (_ansi blue)integrations runtime info(_ansi reset)       - Show runtime information\n" +
        $"  (_ansi blue)integrations runtime list(_ansi reset)       - List all available runtimes\n\n" +

        $"(_ansi green_bold)[SSH](_ansi reset) Advanced SSH Operations with Pooling & Circuit Breaker\n" +
        $"  (_ansi blue)integrations ssh pool connect(_ansi reset)   - Create SSH pool connection to host\n" +
        $"  (_ansi blue)integrations ssh pool exec(_ansi reset)      - Execute command on SSH pool\n" +
        $"  (_ansi blue)integrations ssh pool status(_ansi reset)    - Check pool status\n" +
        $"  (_ansi blue)integrations ssh strategies(_ansi reset)     - List deployment strategies \(rolling, blue-green, canary\)\n" +
        $"  (_ansi blue)integrations ssh retry-config(_ansi reset)   - Configure retry strategy\n" +
        $"  (_ansi blue)integrations ssh circuit-breaker(_ansi reset) - Check circuit breaker status\n\n" +

        $"(_ansi green_bold)[Backup](_ansi reset) Multi-Backend Backup Management\n" +
        $"  (_ansi blue)integrations backup create(_ansi reset)      - Create backup job \(restic, borg, tar, rsync\)\n" +
        $"  (_ansi blue)integrations backup restore(_ansi reset)     - Restore from snapshot\n" +
        $"  (_ansi blue)integrations backup list(_ansi reset)        - List available snapshots\n" +
        $"  (_ansi blue)integrations backup schedule(_ansi reset)    - Schedule regular backups with cron\n" +
        $"  (_ansi blue)integrations backup retention(_ansi reset)   - Show retention policy\n" +
        $"  (_ansi blue)integrations backup status(_ansi reset)      - Check backup status\n\n" +

        $"(_ansi green_bold)[GitOps](_ansi reset) Event-Driven Deployments from Git\n" +
        $"  (_ansi blue)integrations gitops rules(_ansi reset)       - Load GitOps rules from config\n" +
        $"  (_ansi blue)integrations gitops watch(_ansi reset)       - Watch for Git events \(GitHub, GitLab, Gitea\)\n" +
        $"  (_ansi blue)integrations gitops trigger(_ansi reset)     - Manually trigger deployment\n" +
        $"  (_ansi blue)integrations gitops events(_ansi reset)      - List supported events \(push, PR, webhook, scheduled\)\n" +
        $"  (_ansi blue)integrations gitops deployments(_ansi reset) - List active deployments\n" +
        $"  (_ansi blue)integrations gitops status(_ansi reset)      - Show GitOps status\n\n" +

        $"(_ansi green_bold)[Service](_ansi reset) Cross-Platform Service Management\n" +
        $"  (_ansi blue)integrations service install(_ansi reset)    - Install service \(systemd, launchd, runit, openrc\)\n" +
        $"  (_ansi blue)integrations service start(_ansi reset)      - Start service\n" +
        $"  (_ansi blue)integrations service stop(_ansi reset)       - Stop service\n" +
        $"  (_ansi blue)integrations service restart(_ansi reset)    - Restart service\n" +
        $"  (_ansi blue)integrations service status(_ansi reset)     - Check service status\n" +
        $"  (_ansi blue)integrations service list(_ansi reset)       - List services\n" +
        $"  (_ansi blue)integrations service detect-init(_ansi reset) - Detect init system\n\n" +

        $"(_ansi green_bold)QUICK START(_ansi reset)\n\n" +
        $"  # Detect and use available runtime\n" +
        $"  provisioning runtime detect\n" +
        $"  provisioning runtime exec 'docker ps'\n\n" +
        $"  # SSH operations with pooling\n" +
        $"  provisioning ssh pool connect server.example.com root\n" +
        $"  provisioning ssh pool status\n\n" +
        $"  # Multi-backend backups\n" +
        $"  provisioning backup create daily-backup /data --backend restic\n" +
        $"  provisioning backup schedule daily-backup '0 2 * * *'\n\n" +

        $"  # Event-driven GitOps\n" +
        $"  provisioning gitops rules ./gitops-rules.yaml\n" +
        $"  provisioning gitops watch --provider github\n\n" +

        $"(_ansi green_bold)FEATURES(_ansi reset)\n\n" +
        $"  • Runtime abstraction: Docker, Podman, OrbStack, Colima, nerdctl\n" +
        $"  • SSH pooling: 90% faster distributed operations\n" +
        $"  • Circuit breaker: Fault isolation for failing hosts\n" +
        $"  • Backup flexibility: Local, S3, SFTP, REST, B2 repositories\n" +
        $"  • Event-driven GitOps: GitHub, GitLab, Gitea support\n" +
        $"  • Multi-platform services: systemd, launchd, runit, OpenRC\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  int, integ, integrations  → Access integrations\n" +
        $"  runtime, ssh, backup, gitops, service → Direct access\n\n" +

        $"(_ansi green_bold)DOCUMENTATION(_ansi reset)\n\n" +
        $"  • Architecture: docs/architecture/ECOSYSTEM_INTEGRATION.md\n" +
        $"  • Bridge crate: provisioning/platform/integrations/provisioning-bridge/\n" +
        $"  • Nushell modules: provisioning/core/nulib/lib_provisioning/integrations/\n" +
        $"  • KCL schemas: provisioning/kcl/integrations/\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Use --check flag for dry-run mode\n" +
        $"   Example: provisioning runtime exec 'docker ps' --check(_ansi reset)\n"
    )
}

# VM category help
def help-vm []: nothing -> string {
    (
        $"(_ansi cyan_bold)╔══════════════════════════════════════════════════╗(_ansi reset)\n" +
        $"(_ansi cyan_bold)║(_ansi reset)  🖥️  VIRTUAL MACHINE MANAGEMENT                  (_ansi cyan_bold)║(_ansi reset)\n" +
        $"(_ansi cyan_bold)╚══════════════════════════════════════════════════╝(_ansi reset)\n\n" +

        $"(_ansi green_bold)[Core](_ansi reset) VM Operations\n" +
        $"  (_ansi blue)vm create [config](_ansi reset)    - Create new VM\n" +
        $"  (_ansi blue)vm list [--running](_ansi reset)   - List all VMs\n" +
        $"  (_ansi blue)vm start <name>(_ansi reset)       - Start VM\n" +
        $"  (_ansi blue)vm stop <name>(_ansi reset)        - Stop VM\n" +
        $"  (_ansi blue)vm delete <name>(_ansi reset)      - Delete VM\n" +
        $"  (_ansi blue)vm info <name>(_ansi reset)        - VM information\n" +
        $"  (_ansi blue)vm ssh <name>(_ansi reset)         - SSH into VM\n" +
        $"  (_ansi blue)vm exec <name> <cmd>(_ansi reset)  - Execute command in VM\n" +
        $"  (_ansi blue)vm scp <src> <dst>(_ansi reset)    - Copy files to/from VM\n\n" +

        $"(_ansi green_bold)[Hosts](_ansi reset) Host Management\n" +
        $"  (_ansi blue)vm hosts check(_ansi reset)        - Check hypervisor capability\n" +
        $"  (_ansi blue)vm hosts prepare(_ansi reset)      - Prepare host for VMs\n" +
        $"  (_ansi blue)vm hosts list(_ansi reset)         - List available hosts\n" +
        $"  (_ansi blue)vm hosts status(_ansi reset)       - Host status\n" +
        $"  (_ansi blue)vm hosts ensure(_ansi reset)       - Ensure VM support\n\n" +

        $"(_ansi green_bold)[Lifecycle](_ansi reset) VM Persistence\n" +
        $"  (_ansi blue)vm lifecycle list-permanent(_ansi reset)      - List permanent VMs\n" +
        $"  (_ansi blue)vm lifecycle list-temporary(_ansi reset)      - List temporary VMs\n" +
        $"  (_ansi blue)vm lifecycle make-permanent(_ansi reset)      - Mark VM as permanent\n" +
        $"  (_ansi blue)vm lifecycle make-temporary(_ansi reset)      - Mark VM as temporary\n" +
        $"  (_ansi blue)vm lifecycle cleanup-now(_ansi reset)         - Cleanup expired VMs\n" +
        $"  (_ansi blue)vm lifecycle extend-ttl(_ansi reset)          - Extend VM TTL\n" +
        $"  (_ansi blue)vm lifecycle scheduler start(_ansi reset)     - Start cleanup scheduler\n" +
        $"  (_ansi blue)vm lifecycle scheduler stop(_ansi reset)      - Stop scheduler\n" +
        $"  (_ansi blue)vm lifecycle scheduler status(_ansi reset)    - Scheduler status\n\n" +

        $"(_ansi green_bold)SHORTCUTS(_ansi reset)\n\n" +
        $"  vmi → vm info              - Quick VM info\n" +
        $"  vmh → vm hosts             - Host management\n" +
        $"  vml → vm lifecycle         - Lifecycle management\n\n" +

        $"(_ansi green_bold)DUAL ACCESS(_ansi reset)\n\n" +
        $"  Both syntaxes work identically:\n" +
        $"    provisioning vm create config.yaml\n" +
        $"    provisioning infra vm create config.yaml\n\n" +

        $"(_ansi green_bold)EXAMPLES(_ansi reset)\n\n" +
        $"  # Create and manage VMs\n" +
        $"  provisioning vm create web-01.yaml\n" +
        $"  provisioning vm list --running\n" +
        $"  provisioning vmi web-01\n" +
        $"  provisioning vm ssh web-01\n\n" +

        $"  # Host preparation\n" +
        $"  provisioning vmh check\n" +
        $"  provisioning vmh prepare --check\n\n" +

        $"  # Lifecycle management\n" +
        $"  provisioning vml list-temporary\n" +
        $"  provisioning vml make-permanent web-01\n" +
        $"  provisioning vml cleanup-now --check\n\n" +

        $"(_ansi yellow_bold)AUTHENTICATION(_ansi reset)\n\n" +
        $"  Destructive operations: delete, cleanup require auth\n" +
        $"  Production operations: create, prepare may require auth\n" +
        $"  Bypass with --check for dry-run mode\n\n" +

        $"(_ansi default_dimmed)💡 Tip: Use --check flag for dry-run mode\n" +
        $"   Example: provisioning vm create web-01.yaml --check(_ansi reset)\n"
    )
}