# User Configuration Template for Provisioning System
# Copy this file to ~/.config/provisioning/config.toml to customize your settings
#
# This file provides user-specific overrides for the provisioning system.
# Values defined here take precedence over system defaults but are overridden
# by project-specific and infrastructure-specific configurations.
#
# Configuration Loading Order (lowest to highest precedence):
# 1. config.defaults.toml (system defaults)
# 2. ~/.config/provisioning/config.toml (this file, user settings)
# 3. ./provisioning.toml (project-specific settings)
# 4. ./.provisioning.toml (infrastructure-specific settings)

# =============================================================================
# CORE SYSTEM CONFIGURATION
# =============================================================================

[core]
# System version and name - usually no need to override
# version = "1.0.0"
# name = "provisioning-system"

# =============================================================================
# PATH CONFIGURATION
# =============================================================================
# Configure base paths for your environment
# All other paths are automatically derived from paths.base

[paths]
# REQUIRED: Base directory where provisioning system is installed
# This is the most important setting - all other paths derive from this
# Examples:
#   base = "/opt/provisioning"                    # System-wide installation
#   base = "/Users/yourname/dev/provisioning"     # User development setup
#   base = "/home/devops/provisioning"            # Linux user setup
base = "/path/to/your/provisioning"

# Optional: Override specific path components if needed
# Generally you should only set these if you have a custom directory layout
# kloud = "{{paths.base}}/my-custom-infra"
# providers = "{{paths.base}}/my-providers"
# taskservs = "{{paths.base}}/my-taskservs"
# clusters = "{{paths.base}}/my-clusters"
# resources = "{{paths.base}}/my-resources"
# templates = "{{paths.base}}/my-templates"
# tools = "{{paths.base}}/my-tools"
# core = "{{paths.base}}/my-core"

# File paths - override only if you've moved these files
# [paths.files]
# settings = "{{paths.base}}/kcl/my-settings.k"
# keys = "{{paths.base}}/my-keys.yaml"
# requirements = "{{paths.base}}/my-requirements.yaml"
# notify_icon = "{{paths.base}}/resources/my-icon.png"

# =============================================================================
# DEBUG AND LOGGING CONFIGURATION
# =============================================================================
# Control debugging output and logging behavior

[debug]
# Enable debug mode globally for your user
# This shows additional diagnostic information and verbose output
enabled = false

# Show metadata in debug output
# Includes internal system information and detailed operation traces
metadata = false

# Enable check mode by default
# When true, operations will simulate actions without making changes
check = false

# Enable remote debugging
# Shows detailed information about remote server operations
remote = false

# Set default log level for all operations
# Valid options: "trace", "debug", "info", "warn", "error"
# - trace: Most verbose, shows all internal operations
# - debug: Detailed information for troubleshooting
# - info: General information about operations (default)
# - warn: Warning messages and non-critical issues
# - error: Only errors and critical problems
log_level = "info"

# Disable terminal features if needed
# Set to true if running in environments without proper terminal support
no_terminal = false

# =============================================================================
# OUTPUT CONFIGURATION
# =============================================================================
# Configure how information is displayed and formatted

[output]
# Default file viewer for configuration files and logs
# Common options: "less", "more", "cat", "bat", "code", "vim", "nano"
file_viewer = "less"

# Default output format for data display
# Valid options: "json", "yaml", "toml", "text"
# - json: Structured JSON output, good for automation
# - yaml: Human-readable YAML format
# - toml: Configuration-friendly TOML format
# - text: Plain text, good for terminals
format = "yaml"

# =============================================================================
# SOPS ENCRYPTION CONFIGURATION
# =============================================================================
# Configure SOPS (Secrets OPerationS) for encryption/decryption of sensitive data

[sops]
# Enable or disable SOPS encryption globally
# Set to false if you don't use encrypted configuration files
use_sops = true

# Path to SOPS configuration file
# This file defines encryption rules and key providers
# config_path = "{{paths.base}}/.sops.yaml"

# Search paths for Age encryption keys
# SOPS will search these locations for your private key files
# Add your preferred key locations here
key_search_paths = [
    "{{paths.base}}/keys/age.txt",
    "~/.config/sops/age/keys.txt",
    "~/.age/keys.txt",
    "/etc/sops/age/keys.txt"
]

# =============================================================================
# RUNTIME DIRECTORIES
# =============================================================================
# Configure directories for runtime data and temporary files

[taskservs]
# Directory for task service runtime data
# This is where service state, logs, and temporary files are stored
# run_path = "{{paths.base}}/run/taskservs"

[clusters]
# Directory for cluster runtime data
# Stores cluster state information and generated configurations
# run_path = "{{paths.base}}/run/clusters"

[generation]
# Directory for generated configuration files
# Generated configurations are stored here before deployment
# dir_path = "{{paths.base}}/generated"
# defs_file = "defs.toml"

# =============================================================================
# PROVIDER CONFIGURATION
# =============================================================================
# Configure cloud providers and authentication

[providers]
# Default provider to use when none is specified
# Valid options: "aws", "upcloud", "local"
# - aws: Amazon Web Services
# - upcloud: UpCloud VPS provider
# - local: Local development/testing
default = "local"

# AWS Provider Configuration
[providers.aws]
# API endpoint - leave empty for default AWS endpoints
api_url = ""
# Authentication method - leave empty to use AWS CLI/SDK defaults
auth = ""
# Interface type: "API" for direct API calls, "CLI" for AWS CLI
interface = "CLI"

# UpCloud Provider Configuration
[providers.upcloud]
# API endpoint for UpCloud
api_url = "https://api.upcloud.com/1.3"
# Authentication - set your API credentials in environment variables
auth = ""
# Interface type: "API" for direct API calls, "CLI" for UpCloud CLI
interface = "CLI"

# Local Provider Configuration (for development and testing)
[providers.local]
# No API URL needed for local provider
api_url = ""
# No authentication needed for local provider
auth = ""
# Always uses CLI interface for local operations
interface = "CLI"

# =============================================================================
# USER-SPECIFIC ENVIRONMENT OVERRIDES
# =============================================================================
# Override environment-specific settings for your workflow

# Development Environment Overrides
# Uncomment and modify these if you work primarily in development mode
# [environments.dev]
# debug.enabled = true
# debug.log_level = "debug"
# debug.metadata = true
# providers.default = "local"
# output.format = "json"

# Production Environment Overrides
# Uncomment and modify these for production deployments
# [environments.prod]
# debug.enabled = false
# debug.log_level = "warn"
# debug.check = false
# output.format = "yaml"

# Testing Environment Overrides
# Uncomment and modify these for testing scenarios
# [environments.test]
# debug.enabled = true
# debug.check = true
# debug.log_level = "info"
# providers.default = "local"

# =============================================================================
# ADVANCED USER CUSTOMIZATIONS
# =============================================================================
# Advanced settings for power users

# Custom Notification Settings (optional)
# [notifications]
# enabled = true
# icon_path = "{{paths.base}}/resources/my-custom-icon.png"
# sound_enabled = false

# Performance Tuning (optional)
# [performance]
# parallel_operations = 4
# timeout_seconds = 300
# cache_enabled = true

# Security Settings (optional)
# [security]
# require_confirmation = true
# log_sensitive_data = false
# strict_validation = true

# =============================================================================
# USAGE EXAMPLES AND COMMON CONFIGURATIONS
# =============================================================================
#
# Example 1: Developer Setup
# -------------------------
# [paths]
# base = "/Users/alice/dev/provisioning"
#
# [debug]
# enabled = true
# log_level = "debug"
#
# [providers]
# default = "local"
#
# [output]
# format = "json"
# file_viewer = "code"
#
# Example 2: Production Operations
# -------------------------------
# [paths]
# base = "/opt/provisioning"
#
# [debug]
# enabled = false
# log_level = "warn"
#
# [providers]
# default = "aws"
#
# [output]
# format = "yaml"
#
# Example 3: Team Lead Setup
# -------------------------
# [paths]
# base = "/home/teamlead/provisioning"
#
# [debug]
# enabled = true
# log_level = "info"
# metadata = true
#
# [providers]
# default = "upcloud"
#
# [sops]
# key_search_paths = [
#     "/secure/keys/team-lead.txt",
#     "~/.config/sops/age/keys.txt"
# ]
#
# =============================================================================
# QUICK START CHECKLIST
# =============================================================================
#
# To get started with this configuration:
#
# 1. Copy this file to ~/.config/provisioning/config.toml
# 2. Update paths.base to point to your provisioning installation
# 3. Choose your default provider (local, aws, upcloud)
# 4. Set debug.enabled = true if you want verbose output
# 5. Configure SOPS key paths if using encrypted configurations
# 6. Test with: ./core/nulib/provisioning validate config
#
# For more information:
# - Run: ./core/nulib/provisioning help
# - See: CLAUDE.md for project documentation
# - Visit: Project wiki for detailed guides