# Help system content - Data-driven help text for provisioning CLI
# This file contains all help text organized by category
# Color codes use Nushell ANSI formatting: (_ansi color)text(_ansi reset)

{
  categories = {
    infrastructure = {
      title = "🏗️  INFRASTRUCTURE MANAGEMENT",
      color = "cyan",
      sections = [
        {
          name = "Lifecycle",
          subtitle = "Server Management",
          items = [
            { cmd = "server create", desc = "Create new servers [--infra <name>] [--check]" },
            { cmd = "server delete", desc = "Delete servers [--yes] [--keepstorage]" },
            { cmd = "server list", desc = "List all servers [--out json|yaml]" },
            { cmd = "server ssh <host>", desc = "SSH into server" },
            { cmd = "server price", desc = "Show server pricing" }
          ]
        },
        {
          name = "Services",
          subtitle = "Task Service Management",
          items = [
            { cmd = "taskserv create <svc>", desc = "Install service [kubernetes, redis, postgres]" },
            { cmd = "taskserv delete <svc>", desc = "Remove service" },
            { cmd = "taskserv list", desc = "List available services" },
            { cmd = "taskserv generate <svc>", desc = "Generate service configuration" },
            { cmd = "taskserv validate <svc>", desc = "Validate service before deployment" },
            { cmd = "taskserv test <svc>", desc = "Test service in sandbox" },
            { cmd = "taskserv check-deps <svc>", desc = "Check service dependencies" },
            { cmd = "taskserv check-updates", desc = "Check for service updates" }
          ]
        },
        {
          name = "Complete",
          subtitle = "Cluster Operations",
          items = [
            { cmd = "cluster create", desc = "Create complete cluster" },
            { cmd = "cluster delete", desc = "Delete cluster" },
            { cmd = "cluster list", desc = "List cluster components" }
          ]
        },
        {
          name = "Virtual Machines",
          subtitle = "VM Management",
          items = [
            { cmd = "vm create [config]", desc = "Create new VM" },
            { cmd = "vm list [--running]", desc = "List VMs" },
            { cmd = "vm start <name>", desc = "Start VM" },
            { cmd = "vm stop <name>", desc = "Stop VM" },
            { cmd = "vm delete <name>", desc = "Delete VM" },
            { cmd = "vm info <name>", desc = "VM information" },
            { cmd = "vm ssh <name>", desc = "SSH into VM" },
            { cmd = "vm hosts check", desc = "Check hypervisor capability" },
            { cmd = "vm lifecycle list-temporary", desc = "List temporary VMs" },
            { cmd = "shortcuts", note = "vmi=info, vmh=hosts, vml=lifecycle" }
          ]
        },
        {
          name = "Management",
          subtitle = "Infrastructure",
          items = [
            { cmd = "infra list", desc = "List infrastructures" },
            { cmd = "infra validate", desc = "Validate infrastructure config" },
            { cmd = "generate infra --new <name>", desc = "Create new infrastructure" }
          ]
        }
      ],
      tip = "Use --check flag for dry-run mode\n   Example: provisioning server create --check"
    },

    orchestration = {
      title = "⚡ ORCHESTRATION & WORKFLOWS",
      color = "purple",
      sections = [
        {
          name = "Control",
          subtitle = "Orchestrator Management",
          items = [
            { cmd = "orchestrator start", desc = "Start orchestrator [--background]" },
            { cmd = "orchestrator stop", desc = "Stop orchestrator" },
            { cmd = "orchestrator status", desc = "Check if running" },
            { cmd = "orchestrator health", desc = "Health check" },
            { cmd = "orchestrator logs", desc = "View logs [--follow]" }
          ]
        },
        {
          name = "Workflows",
          subtitle = "Single Task Workflows",
          items = [
            { cmd = "workflow list", desc = "List all workflows" },
            { cmd = "workflow status <id>", desc = "Get workflow status" },
            { cmd = "workflow monitor <id>", desc = "Monitor in real-time" },
            { cmd = "workflow stats", desc = "Show statistics" },
            { cmd = "workflow cleanup", desc = "Clean old workflows" }
          ]
        },
        {
          name = "Batch",
          subtitle = "Multi-Provider Batch Operations",
          items = [
            { cmd = "batch submit <file>", desc = "Submit Nickel workflow [--wait]" },
            { cmd = "batch list", desc = "List batches [--status Running]" },
            { cmd = "batch status <id>", desc = "Get batch status" },
            { cmd = "batch monitor <id>", desc = "Real-time monitoring" },
            { cmd = "batch rollback <id>", desc = "Rollback failed batch" },
            { cmd = "batch cancel <id>", desc = "Cancel running batch" },
            { cmd = "batch stats", desc = "Show statistics" }
          ]
        }
      ],
      tip = "Batch workflows support mixed providers: UpCloud, AWS, and local\n   Example: provisioning batch submit deployment.ncl --wait"
    },

    development = {
      title = "🧩 DEVELOPMENT TOOLS",
      color = "blue",
      sections = [
        {
          name = "Discovery",
          subtitle = "Module System",
          items = [
            { cmd = "module discover <type>", desc = "Find taskservs/providers/clusters" },
            { cmd = "module load <type> <ws> <mods>", desc = "Load modules into workspace" },
            { cmd = "module list <type> <ws>", desc = "List loaded modules" },
            { cmd = "module unload <type> <ws> <mod>", desc = "Unload module" },
            { cmd = "module sync-nickel <infra>", desc = "Sync Nickel dependencies" }
          ]
        },
        {
          name = "Architecture",
          subtitle = "Layer System (STRATEGIC)",
          items = [
            { cmd = "layer explain", desc = "Explain layer concept" },
            { cmd = "layer show <ws>", desc = "Show layer resolution" },
            { cmd = "layer test <mod> <ws>", desc = "Test layer resolution" },
            { cmd = "layer stats", desc = "Show statistics" }
          ]
        },
        {
          name = "Maintenance",
          subtitle = "Version Management",
          items = [
            { cmd = "version check", desc = "Check all versions" },
            { cmd = "version show", desc = "Display status [--format table|json]" },
            { cmd = "version updates", desc = "Check available updates" },
            { cmd = "version apply", desc = "Apply config updates" },
            { cmd = "version taskserv <name>", desc = "Show taskserv version" }
          ]
        },
        {
          name = "Distribution",
          subtitle = "Packaging (Advanced)",
          items = [
            { cmd = "pack core", desc = "Package core schemas" },
            { cmd = "pack provider <name>", desc = "Package provider" },
            { cmd = "pack list", desc = "List packages" },
            { cmd = "pack clean", desc = "Clean old packages" }
          ]
        }
      ],
      tip = "The layer system is key to configuration inheritance\n   Use 'provisioning layer explain' to understand it"
    },

    workspace = {
      title = "📁 WORKSPACE & TEMPLATES",
      color = "green",
      sections = [
        {
          name = "Management",
          subtitle = "Workspace Operations",
          items = [
            { cmd = "workspace init <path>", desc = "Initialize workspace [--activate] [--interactive]" },
            { cmd = "workspace create <path>", desc = "Create workspace structure [--activate]" },
            { cmd = "workspace activate <name>", desc = "Activate existing workspace as default" },
            { cmd = "workspace validate <path>", desc = "Validate structure" },
            { cmd = "workspace info <path>", desc = "Show information" },
            { cmd = "workspace list", desc = "List workspaces" },
            { cmd = "workspace migrate [name]", desc = "Migrate workspace [--skip-backup] [--force]" },
            { cmd = "workspace version [name]", desc = "Show workspace version information" },
            { cmd = "workspace check-compatibility [name]", desc = "Check workspace compatibility" },
            { cmd = "workspace list-backups [name]", desc = "List workspace backups" }
          ]
        },
        {
          name = "Synchronization",
          subtitle = "Update Hidden Directories & Modules",
          items = [
            { cmd = "workspace check-updates [name]", desc = "Check which directories need updating" },
            { cmd = "workspace update [name] [FLAGS]", desc = "Update all hidden dirs and content\n                         \t\t\tUpdates: .providers, .clusters, .taskservs, .nickel" },
            { cmd = "workspace sync-modules [name] [FLAGS]", desc = "Sync workspace modules" }
          ]
        },
        {
          name = "Common Flags",
          items = [
            { flag = "--check  (-c)", desc = "Preview changes without applying them" },
            { flag = "--force  (-f)", desc = "Skip confirmation prompts" },
            { flag = "--yes    (-y)", desc = "Auto-confirm (same as --force)" },
            { flag = "--verbose(-v)", desc = "Detailed operation information" }
          ]
        },
        {
          name = "Creation Modes",
          items = [
            { flag = "--activate(-a)", desc = "Activate workspace as default after creation" },
            { flag = "--interactive(-I)", desc = "Interactive workspace creation wizard" }
          ]
        },
        {
          name = "Configuration",
          subtitle = "Workspace Config Management",
          items = [
            { cmd = "workspace config show [name]", desc = "Show workspace config [--format yaml|json|toml]" },
            { cmd = "workspace config validate [name]", desc = "Validate all configs" },
            { cmd = "workspace config generate provider <name>", desc = "Generate provider config" },
            { cmd = "workspace config edit <type> [name]", desc = "Edit config (main|provider|platform|kms)" },
            { cmd = "workspace config hierarchy [name]", desc = "Show config loading order" },
            { cmd = "workspace config list [name]", desc = "List config files [--type all|provider|platform|kms]" }
          ]
        },
        {
          name = "Patterns",
          subtitle = "Infrastructure Templates",
          items = [
            { cmd = "template list", desc = "List templates [--type taskservs|providers]" },
            { cmd = "template types", desc = "Show template categories" },
            { cmd = "template show <name>", desc = "Show template details" },
            { cmd = "template apply <name> <infra>", desc = "Apply to infrastructure" },
            { cmd = "template validate <infra>", desc = "Validate template usage" }
          ]
        }
      ],
      note = "Optional workspace name [name] defaults to active workspace if not specified",
      examples = [
        "provisioning --yes workspace update              - Update active workspace with auto-confirm",
        "provisioning --verbose workspace update myws     - Update 'myws' with detailed output",
        "provisioning --check workspace update            - Preview changes before updating",
        "provisioning --yes --verbose workspace update myws - Combine flags"
      ],
      warning = "Nushell Flag Ordering: Nushell requires flags BEFORE positional arguments\n    ✅ provisioning --yes workspace update     [Correct - flags first]\n    ❌ provisioning workspace update --yes   [Wrong - parser error]",
      tip = "Config commands use active workspace if name not provided\n   Example: provisioning workspace config show --format json"
    },

    platform = {
      title = "🖥️  PLATFORM SERVICES",
      color = "red",
      sections = [
        {
          name = "Control Center",
          subtitle = "🌐 Web UI + Policy Engine",
          items = [
            { cmd = "control-center server", desc = "Start Cedar policy engine (--port 8080)" },
            { cmd = "control-center policy validate", desc = "Validate Cedar policies" },
            { cmd = "control-center policy test", desc = "Test policies with data" },
            { cmd = "control-center compliance soc2", desc = "SOC2 compliance check" },
            { cmd = "control-center compliance hipaa", desc = "HIPAA compliance check" }
          ],
          features = [
            "Web-based UI              - WASM-powered control center interface",
            "Policy Engine             - Cedar policy evaluation and versioning",
            "Compliance                - SOC2 Type II and HIPAA validation",
            "Security                  - JWT auth, MFA, RBAC, anomaly detection",
            "Audit Trail               - Complete compliance audit logging"
          ]
        },
        {
          name = "Orchestrator",
          subtitle = "Hybrid Rust/Nushell Coordination",
          items = [
            { cmd = "orchestrator start", desc = "Start orchestrator [--background]" },
            { cmd = "orchestrator stop", desc = "Stop orchestrator" },
            { cmd = "orchestrator status", desc = "Check if running" },
            { cmd = "orchestrator health", desc = "Health check with diagnostics" },
            { cmd = "orchestrator logs", desc = "View logs [--follow]" }
          ]
        },
        {
          name = "MCP Server",
          subtitle = "AI-Assisted DevOps Integration",
          items = [
            { cmd = "mcp-server start", desc = "Start MCP server [--debug]" },
            { cmd = "mcp-server status", desc = "Check server status" }
          ],
          features = [
            "AI-Powered Parsing - Natural language to infrastructure",
            "Multi-Provider    - AWS, UpCloud, Local support",
            "Ultra-Fast        - Microsecond latency, 1000x faster than Python",
            "Type Safe         - Compile-time guarantees with zero runtime errors"
          ]
        }
      ],
      tip = "Control Center provides a web-based UI for managing policies!\n   Access at: http://localhost:8080 after starting the server\n   Example: provisioning control-center server --port 8080"
    },

    setup = {
      title = "⚙️  SYSTEM SETUP & CONFIGURATION",
      color = "magenta",
      sections = [
        {
          name = "Initial Setup",
          subtitle = "First-Time System Configuration",
          items = [
            { cmd = "provisioning setup system", desc = "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    Flags: --interactive, --config <file>, --defaults" }
          ]
        },
        {
          name = "Workspace Setup",
          subtitle = "Create and Configure Workspaces",
          items = [
            { cmd = "provisioning setup workspace <name>", desc = "Create new workspace\n    • Initialize workspace structure\n    • Configure workspace-specific settings\n    • Set active providers\n    Flags: --activate, --config <file>, --interactive" }
          ]
        },
        {
          name = "Provider Setup",
          subtitle = "Cloud Provider Configuration",
          items = [
            { cmd = "provisioning setup provider <name>", desc = "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    Flags: --global, --workspace <name>, --credentials" }
          ]
        },
        {
          name = "Platform Setup",
          subtitle = "Infrastructure Services",
          items = [
            { cmd = "provisioning setup platform", desc = "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    Flags: --mode solo|multiuser|cicd|enterprise, --deployment docker|k8s|podman" }
          ]
        },
        {
          name = "Update Configuration",
          subtitle = "Modify Existing Setup",
          items = [
            { cmd = "provisioning setup update [category]", desc = "Update existing settings\n    • provider - Update provider credentials\n    • platform - Update platform service config\n    • preferences - Update user preferences\n    Flags: --workspace <name>, --check" }
          ]
        }
      ],
      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"
    },

    concepts = {
      title = "💡 ARCHITECTURE & KEY CONCEPTS",
      color = "yellow",
      sections = [
        {
          name = "Layer System",
          subtitle = "Configuration Inheritance",
          content = "The system uses a 3-layer architecture for configuration:\n\n   Core Layer (100)\n   └─ Base system extensions (provisioning/extensions/)\n      • Standard provider implementations\n      • Default taskserv configurations\n      • Built-in cluster templates\n\n   Workspace Layer (200)\n   └─ Shared templates (provisioning/workspace/templates/)\n      • Reusable infrastructure patterns\n      • Organization-wide standards\n      • Team conventions\n\n   Infrastructure Layer (300)\n   └─ Specific overrides (workspace/infra/{name}/)\n      • Project-specific configurations\n      • Environment customizations\n      • Local overrides\n\n   Resolution Order: Infrastructure (300) → Workspace (200) → Core (100)\n   Higher numbers override lower numbers"
        },
        {
          name = "Module System",
          subtitle = "Reusable Components",
          content = "Taskservs - Infrastructure services\n   • kubernetes, containerd, cilium, redis, postgres\n   • Installed on servers, configured per environment\n\n   Providers - Cloud platforms\n   • upcloud, aws, local with docker or podman\n   • Provider-agnostic middleware supports multi-cloud\n\n   Clusters - Complete configurations\n   • buildkit, ci-cd, monitoring\n   • Orchestrated deployments with dependencies"
        },
        {
          name = "Workflow Types",
          content = "Single Workflows\n   • Individual server/taskserv/cluster operations\n   • Real-time monitoring, state management\n\n   Batch Workflows\n   • Multi-provider operations: UpCloud, AWS, and local\n   • Dependency resolution, rollback support\n   • Defined in Nickel workflow files"
        },
        {
          name = "Typical Workflow",
          content = "1. Create workspace:     workspace init my-project\n   2. Discover modules:     module discover taskservs\n   3. Load modules:         module load taskservs my-project kubernetes\n   4. Create servers:       server create --infra my-project\n   5. Deploy taskservs:     taskserv create kubernetes\n   6. Check layers:         layer show my-project"
        }
      ],
      tip = "For more details:\n   • provisioning layer explain  - Layer system deep dive\n   • provisioning help development - Module system commands"
    },

    guides = {
      title = "📚 GUIDES & CHEATSHEETS",
      color = "magenta",
      sections = [
        {
          name = "Quick Reference",
          subtitle = "Copy-Paste Ready Commands",
          items = [
            { cmd = "sc", desc = "Quick command reference (fastest)" },
            { cmd = "guide quickstart", desc = "Full command cheatsheet with examples" }
          ]
        },
        {
          name = "Step-by-Step Guides",
          subtitle = "Complete Walkthroughs",
          items = [
            { cmd = "guide from-scratch", desc = "Complete deployment from zero to production" },
            { cmd = "guide update", desc = "Update existing infrastructure safely" },
            { cmd = "guide customize", desc = "Customize with layers and templates" }
          ]
        },
        {
          name = "Guide Topics",
          content = "Quickstart Cheatsheet:\n    • All command shortcuts reference\n    • Copy-paste ready commands\n    • Common workflow examples\n\n  From Scratch Guide:\n    • Prerequisites and setup\n    • Initialize workspace\n    • Deploy complete infrastructure\n    • Verify deployment\n\n  Update Guide:\n    • Check for updates\n    • Update strategies\n    • Rolling updates\n    • Rollback procedures\n\n  Customize Guide:\n    • Layer system explained\n    • Using templates\n    • Creating custom modules\n    • Advanced customization patterns"
        }
      ],
      tip = "All guides provide copy-paste ready commands that you can\n   adjust and use immediately. Perfect for quick start!\n   Example: provisioning guide quickstart | less"
    },

    authentication = {
      title = "🔐 AUTHENTICATION & SECURITY",
      color = "yellow",
      sections = [
        {
          name = "Session Management",
          subtitle = "JWT Token Authentication",
          items = [
            { cmd = "auth login <username>", desc = "Login and store JWT tokens" },
            { cmd = "auth logout", desc = "Logout and clear tokens" },
            { cmd = "auth status", desc = "Show current authentication status" },
            { cmd = "auth sessions", desc = "List active sessions" },
            { cmd = "auth refresh", desc = "Verify/refresh token" }
          ]
        },
        {
          name = "Multi-Factor Auth",
          subtitle = "TOTP and WebAuthn Support",
          items = [
            { cmd = "auth mfa enroll <type>", desc = "Enroll in MFA [totp or webauthn]" },
            { cmd = "auth mfa verify --code <code>", desc = "Verify MFA code" }
          ]
        },
        {
          name = "Authentication Features",
          content = "• JWT tokens with RS256 asymmetric signing\n  • 15-minute access tokens with 7-day refresh\n  • TOTP MFA [Google Authenticator, Authy]\n  • WebAuthn/FIDO2 [YubiKey, Touch ID, Windows Hello]\n  • Role-based access [Admin, Developer, Operator, Viewer, Auditor]\n  • HTTP fallback when nu_plugin_auth unavailable"
        }
      ],
      tip = "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"
    },

    mfa = {
      title = "🔐 MULTI-FACTOR AUTHENTICATION",
      color = "yellow",
      sections = [
        {
          name = "MFA Types",
          content = "TOTP [Time-based One-Time Password]\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  WebAuthn/FIDO2\n  • Hardware security keys [YubiKey, Titan Key]\n  • Biometric authentication [Touch ID, Face ID, Windows Hello]\n  • Phishing-resistant\n  • No codes to type"
        },
        {
          name = "Enrollment Process",
          items = [
            { step = "1. Login first:", cmd = "provisioning auth login" },
            { step = "2. Enroll in MFA:", cmd = "provisioning auth mfa enroll totp" },
            { step = "3. Scan QR code:", note = "Use authenticator app" },
            { step = "4. Verify setup:", cmd = "provisioning auth mfa verify --code <code>" },
            { step = "5. Save backup codes:", note = "Store securely [shown after verification]" }
          ]
        },
        {
          name = "MFA Requirements",
          items = [
            { level = "Production Operations", desc = "MFA required for prod environment" },
            { level = "Destructive Operations", desc = "MFA required for delete/destroy" },
            { level = "Admin Operations", desc = "MFA recommended for all admins" }
          ]
        }
      ],
      tip = "MFA enrollment requires active authentication session\n   Backup codes provided after verification - store securely!\n   Can enroll multiple devices for redundancy"
    },

    plugins = {
      title = "🔌 PLUGIN MANAGEMENT",
      color = "cyan",
      sections = [
        {
          name = "Critical Provisioning Plugins",
          subtitle = "10-30x FASTER",
          content = "nu_plugin_auth (~10x faster)\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  nu_plugin_kms (~10x faster)\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  nu_plugin_orchestrator (~30x faster)\n  • Direct file-based state access (no HTTP)\n  • Nickel workflow validation\n  • Commands: orch status, tasks, validate, submit, monitor\n  • Local task queue operations"
        },
        {
          name = "Plugin Operations",
          items = [
            { cmd = "plugin list", desc = "List all plugins with status" },
            { cmd = "plugin register <name>", desc = "Register plugin with Nushell" },
            { cmd = "plugin test <name>", desc = "Test plugin functionality" },
            { cmd = "plugin status", desc = "Show plugin status and performance" }
          ]
        },
        {
          name = "Additional Plugins",
          content = "nu_plugin_tera\n  • Jinja2-compatible template rendering\n  • Used for config generation\n\n  nu_plugin_nickel\n  • Nickel configuration language\n  • Falls back to external Nickel CLI"
        }
      ],
      tip = "Plugins provide 10-30x performance improvement\n   Graceful HTTP fallback when plugins unavailable\n   Config: provisioning/config/plugins.toml"
    },

    utilities = {
      title = "🛠️  UTILITIES & TOOLS",
      color = "green",
      sections = [
        {
          name = "Cache Management",
          subtitle = "Configuration Caching",
          items = [
            { cmd = "cache status", desc = "Show cache configuration and statistics" },
            { cmd = "cache config show", desc = "Display all cache settings" },
            { cmd = "cache config get <setting>", desc = "Get specific cache setting [dot notation]" },
            { cmd = "cache config set <setting> <value>", desc = "Set cache setting" },
            { cmd = "cache list [--type <type>]", desc = "List cached items [all|nickel|sops|final]" },
            { cmd = "cache clear [--type <type>]", desc = "Clear cache [default: all]" },
            { cmd = "cache help", desc = "Show cache command help" }
          ],
          features = [
            "Intelligent TTL management (Nickel: 30m, SOPS: 15m, Final: 5m)",
            "mtime-based validation for stale data detection",
            "SOPS cache with 0600 permissions",
            "Configurable cache size (default: 100 MB)",
            "Works without active workspace",
            "Performance: 95-98% faster config loading"
          ]
        },
        {
          name = "Secrets Management",
          subtitle = "SOPS Encryption",
          items = [
            { cmd = "sops <file>", desc = "Edit encrypted file with SOPS" },
            { cmd = "encrypt <file>", desc = "Encrypt file (alias: kms encrypt)" },
            { cmd = "decrypt <file>", desc = "Decrypt file (alias: kms decrypt)" }
          ]
        },
        {
          name = "Provider Operations",
          subtitle = "Cloud & Local Providers",
          items = [
            { cmd = "providers list [--nickel] [--format <fmt>]", desc = "List available providers" },
            { cmd = "providers info <provider> [--nickel]", desc = "Show detailed provider info" },
            { cmd = "providers install <prov> <infra> [--version <v>]", desc = "Install provider" },
            { cmd = "providers remove <provider> <infra> [--force]", desc = "Remove provider" },
            { cmd = "providers installed <infra> [--format <fmt>]", desc = "List installed" },
            { cmd = "providers validate <infra>", desc = "Validate installation" }
          ]
        },
        {
          name = "Plugin Management",
          subtitle = "Native Performance",
          items = [
            { cmd = "plugin list", desc = "List installed plugins" },
            { cmd = "plugin register <name>", desc = "Register plugin with Nushell" },
            { cmd = "plugin test <name>", desc = "Test plugin functionality" },
            { cmd = "plugin status", desc = "Show all plugin status" }
          ]
        },
        {
          name = "SSH Operations",
          subtitle = "Remote Access",
          items = [
            { cmd = "ssh <host>", desc = "Connect to server via SSH" },
            { cmd = "ssh-pool list", desc = "List SSH connection pool" },
            { cmd = "ssh-pool clear", desc = "Clear SSH connection cache" }
          ]
        },
        {
          name = "Miscellaneous",
          subtitle = "Utilities",
          items = [
            { cmd = "nu", desc = "Start Nushell session with provisioning lib" },
            { cmd = "nuinfo", desc = "Show Nushell version and information" },
            { cmd = "list", desc = "Alias for resource listing" },
            { cmd = "qr <text>", desc = "Generate QR code" }
          ]
        }
      ],
      tip = "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"
    },

    tools = {
      title = "🔧 TOOLS & DEPENDENCIES",
      color = "yellow",
      sections = [
        {
          name = "Installation",
          subtitle = "Tool Setup",
          items = [
            { cmd = "tools install", desc = "Install all tools" },
            { cmd = "tools install <tool>", desc = "Install specific tool [aws|hcloud|upctl]" },
            { cmd = "tools install --update", desc = "Force reinstall all tools" }
          ]
        },
        {
          name = "Version Management",
          subtitle = "Tool Versions",
          items = [
            { cmd = "tools check", desc = "Check all tool versions" },
            { cmd = "tools versions", desc = "Show configured versions" },
            { cmd = "tools check-updates", desc = "Check for available updates" },
            { cmd = "tools apply-updates", desc = "Apply configuration updates [--dry-run]" }
          ]
        },
        {
          name = "Tool Information",
          subtitle = "Tool Details",
          items = [
            { cmd = "tools show", desc = "Display tool information" },
            { cmd = "tools show all", desc = "Show all tools and providers" },
            { cmd = "tools show <tool>", desc = "Tool-specific information" },
            { cmd = "tools show provider", desc = "Show provider information" }
          ]
        },
        {
          name = "Pinning & Configuration",
          subtitle = "Version Control",
          items = [
            { cmd = "tools pin <tool>", desc = "Pin tool to current version (prevent auto-update)" },
            { cmd = "tools unpin <tool>", desc = "Unpin tool (allow auto-update)" }
          ]
        },
        {
          name = "Provider Tools",
          subtitle = "Cloud CLI Tools",
          items = [
            { cmd = "tools check aws", desc = "Check AWS CLI status" },
            { cmd = "tools check hcloud", desc = "Check Hetzner CLI status" },
            { cmd = "tools check upctl", desc = "Check UpCloud CLI status" }
          ]
        }
      ],
      tip = "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"
    },

    diagnostics = {
      title = "🔍 DIAGNOSTICS & SYSTEM HEALTH",
      color = "green",
      sections = [
        {
          name = "System Status",
          subtitle = "Component Verification",
          items = [
            { cmd = "status", desc = "Show comprehensive system status\n    • Nushell version check (requires 0.109.0+)\n    • Nickel CLI installation and version\n    • Nushell plugins (auth, KMS, tera, nickel, 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" },
            { cmd = "status json", desc = "Machine-readable status output\n    • Structured JSON output\n    • Health percentage calculation\n    • Ready-for-deployment flag" }
          ]
        },
        {
          name = "Health Checks",
          subtitle = "Deep Validation",
          items = [
            { cmd = "health", desc = "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    • Nickel schemas validity\n    • Security configuration (KMS, auth, SOPS, Age)\n    • Provider credentials (UpCloud, AWS)\n    • Fix recommendations with doc links" },
            { cmd = "health json", desc = "Machine-readable health output\n    • Structured JSON output\n    • Health score calculation\n    • Production-ready flag" }
          ]
        },
        {
          name = "Smart Guidance",
          subtitle = "Progressive Recommendations",
          items = [
            { cmd = "next", desc = "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" },
            { cmd = "phase", desc = "Show current deployment phase\n    • Current phase (initialization → production)\n    • Progress percentage (step/total)\n    • Deployment readiness status" }
          ]
        }
      ],
      tip = "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"
    },

    integrations = {
      title = "🌉 PROV-ECOSYSTEM & PROVCTL INTEGRATIONS",
      color = "yellow",
      sections = [
        {
          name = "Runtime",
          subtitle = "Container Runtime Abstraction",
          items = [
            { cmd = "integrations runtime detect", desc = "Detect available runtime (docker, podman, orbstack, colima, nerdctl)" },
            { cmd = "integrations runtime exec", desc = "Execute command in detected runtime" },
            { cmd = "integrations runtime compose", desc = "Adapt docker-compose file for runtime" },
            { cmd = "integrations runtime info", desc = "Show runtime information" },
            { cmd = "integrations runtime list", desc = "List all available runtimes" }
          ]
        },
        {
          name = "SSH",
          subtitle = "Advanced SSH Operations with Pooling & Circuit Breaker",
          items = [
            { cmd = "integrations ssh pool connect", desc = "Create SSH pool connection to host" },
            { cmd = "integrations ssh pool exec", desc = "Execute command on SSH pool" },
            { cmd = "integrations ssh pool status", desc = "Check pool status" },
            { cmd = "integrations ssh strategies", desc = "List deployment strategies (rolling, blue-green, canary)" },
            { cmd = "integrations ssh retry-config", desc = "Configure retry strategy" },
            { cmd = "integrations ssh circuit-breaker", desc = "Check circuit breaker status" }
          ]
        },
        {
          name = "Backup",
          subtitle = "Multi-Backend Backup Management",
          items = [
            { cmd = "integrations backup create", desc = "Create backup job (restic, borg, tar, rsync)" },
            { cmd = "integrations backup restore", desc = "Restore from snapshot" },
            { cmd = "integrations backup list", desc = "List available snapshots" },
            { cmd = "integrations backup schedule", desc = "Schedule regular backups with cron" },
            { cmd = "integrations backup retention", desc = "Show retention policy" },
            { cmd = "integrations backup status", desc = "Check backup status" }
          ]
        },
        {
          name = "GitOps",
          subtitle = "Event-Driven Deployments from Git",
          items = [
            { cmd = "integrations gitops rules", desc = "Load GitOps rules from config" },
            { cmd = "integrations gitops watch", desc = "Watch for Git events (GitHub, GitLab, Gitea)" },
            { cmd = "integrations gitops trigger", desc = "Manually trigger deployment" },
            { cmd = "integrations gitops events", desc = "List supported events (push, PR, webhook, scheduled)" },
            { cmd = "integrations gitops deployments", desc = "List active deployments" },
            { cmd = "integrations gitops status", desc = "Show GitOps status" }
          ]
        },
        {
          name = "Service",
          subtitle = "Cross-Platform Service Management",
          items = [
            { cmd = "integrations service install", desc = "Install service (systemd, launchd, runit, openrc)" },
            { cmd = "integrations service start", desc = "Start service" },
            { cmd = "integrations service stop", desc = "Stop service" },
            { cmd = "integrations service restart", desc = "Restart service" },
            { cmd = "integrations service status", desc = "Check service status" },
            { cmd = "integrations service list", desc = "List services" },
            { cmd = "integrations service detect-init", desc = "Detect init system" }
          ]
        }
      ],
      tip = "Tip: Use --check flag for dry-run mode\n   Example: provisioning runtime exec 'docker ps' --check"
    },

    vm = {
      title = "🖥️  VIRTUAL MACHINE MANAGEMENT",
      color = "cyan",
      sections = [
        {
          name = "Core",
          subtitle = "VM Operations",
          items = [
            { cmd = "vm create [config]", desc = "Create new VM" },
            { cmd = "vm list [--running]", desc = "List all VMs" },
            { cmd = "vm start <name>", desc = "Start VM" },
            { cmd = "vm stop <name>", desc = "Stop VM" },
            { cmd = "vm delete <name>", desc = "Delete VM" },
            { cmd = "vm info <name>", desc = "VM information" },
            { cmd = "vm ssh <name>", desc = "SSH into VM" },
            { cmd = "vm exec <name> <cmd>", desc = "Execute command in VM" },
            { cmd = "vm scp <src> <dst>", desc = "Copy files to/from VM" }
          ]
        },
        {
          name = "Hosts",
          subtitle = "Host Management",
          items = [
            { cmd = "vm hosts check", desc = "Check hypervisor capability" },
            { cmd = "vm hosts prepare", desc = "Prepare host for VMs" },
            { cmd = "vm hosts list", desc = "List available hosts" },
            { cmd = "vm hosts status", desc = "Host status" },
            { cmd = "vm hosts ensure", desc = "Ensure VM support" }
          ]
        },
        {
          name = "Lifecycle",
          subtitle = "VM Persistence",
          items = [
            { cmd = "vm lifecycle list-permanent", desc = "List permanent VMs" },
            { cmd = "vm lifecycle list-temporary", desc = "List temporary VMs" },
            { cmd = "vm lifecycle make-permanent", desc = "Mark VM as permanent" },
            { cmd = "vm lifecycle make-temporary", desc = "Mark VM as temporary" },
            { cmd = "vm lifecycle cleanup-now", desc = "Cleanup expired VMs" },
            { cmd = "vm lifecycle extend-ttl", desc = "Extend VM TTL" },
            { cmd = "vm lifecycle scheduler start", desc = "Start cleanup scheduler" },
            { cmd = "vm lifecycle scheduler stop", desc = "Stop scheduler" },
            { cmd = "vm lifecycle scheduler status", desc = "Scheduler status" }
          ]
        }
      ],
      note = "Destructive operations: delete, cleanup require auth\n  Production operations: create, prepare may require auth\n  Bypass with --check for dry-run mode",
      tip = "Tip: Use --check flag for dry-run mode\n   Example: provisioning vm create web-01.yaml --check"
    }
  }
}