# {{TOOL_NAME}} Configuration
#
# This is the configuration file for {{TOOL_NAME}}.
#
# Configuration file search order (tool uses first found):
#   1. .project/{{tool_name_kebab}}.toml  - Tools ecosystem (priority)
#   2. .vapora/{{tool_name_kebab}}.toml         - VAPORA projects
#   3. .coder/{{tool_name_kebab}}.toml          - Doc tracking projects
#   4. ./{{tool_name_kebab}}.toml               - Current directory
#
# Copy this file to one of the locations above and customize as needed.

################################################################################
# MAIN SETTINGS
################################################################################

[{{tool_name_kebab}}]

# Setting 1: Description of what this setting does
# Type: string
# Default: "value1"
# Required: yes
setting1 = "value1"

# Setting 2: Another setting description
# Type: integer
# Default: 42
# Valid Range: 1-1000
# Required: no
setting2 = 42

# Enable Feature: Enable or disable feature
# Type: boolean
# Default: true
# Required: no
enable_feature = true

################################################################################
# ADVANCED SETTINGS
################################################################################

[{{tool_name_kebab}}.advanced]

# Maximum Items: Maximum number of items to process
# Type: integer
# Default: 1000
# Valid Range: 1-10000
# Recommendation: Increase for large datasets, decrease for limited memory
max_items = 1000

# Timeout Seconds: Operation timeout in seconds
# Type: integer
# Default: 30
# Valid Range: 1-300
# Recommendation: Increase for slow networks or large operations
timeout_seconds = 30

# Cache Enabled: Enable caching for better performance
# Type: boolean
# Default: true
# Recommendation: true for production, false for testing
cache_enabled = true

# Cache TTL: Cache time-to-live in seconds
# Type: integer
# Default: 3600 (1 hour)
# Valid Range: 60-86400
cache_ttl_seconds = 3600

################################################################################
# DATABASE CONFIGURATION
################################################################################

[database]

# Type: Which database backend to use
# Type: string
# Valid Values: "sqlite" (recommended), "postgres"
# Default: "sqlite"
# Recommendation: Use sqlite for single-user, postgres for production
type = "sqlite"

# SQLite Configuration (used when type = "sqlite")
#
# Path: Location of the SQLite database file
# Type: string
# Default: ".project/{{tool_name_kebab}}.db"
# Recommendation: Keep in .project/ for Tools ecosystem
# Note: Directory must exist and be writable
path = ".project/{{tool_name_kebab}}.db"

# PostgreSQL Configuration (used when type = "postgres")
#
# URL: PostgreSQL connection string
# Type: string
# Format: postgresql://[user[:password]@][host][:port][/database]
# Examples:
#   postgresql://localhost/{{tool_name_kebab}}
#   postgresql://user:pass@localhost:5432/{{tool_name_kebab}}
#   postgresql://user:pass@prod.example.com/{{tool_name_kebab}}
# Note: Uncomment and configure only if using PostgreSQL
# url = "postgresql://user:password@localhost:5432/{{tool_name_kebab}}"

# Connection Pool Size (PostgreSQL only)
# Type: integer
# Default: 5
# Valid Range: 1-20
# Recommendation: Higher for concurrent workloads
# pool_size = 5

################################################################################
# LOGGING CONFIGURATION
################################################################################

[logging]

# Level: Logging verbosity level
# Type: string
# Valid Values: "trace", "debug", "info", "warn", "error"
# Default: "info"
# Recommendation: Use "debug" for development, "info" for production
level = "info"

# Format: Log message format
# Type: string
# Valid Values: "text", "json", "compact"
# Default: "text"
# Recommendation: "text" for terminal, "json" for systems (e.g., ELK stack)
format = "text"

# Output File: Optional log file path (in addition to console)
# Type: string
# Default: (no file logging)
# Example: "/var/log/{{tool_name_kebab}}/app.log"
# Uncomment to enable file logging:
# output_file = ".project/{{tool_name_kebab}}.log"

################################################################################
# ENVIRONMENT VARIABLE OVERRIDES
################################################################################

# You can also configure via environment variables.
# Environment variables take priority over this file.
#
# Format: {{TOOL_NAME}}_SECTION_SETTING=value
#
# Examples:
#   export {{TOOL_NAME}}_SETTING1="override"
#   export {{TOOL_NAME}}_SETTING2=100
#   export {{TOOL_NAME}}_ADVANCED_MAX_ITEMS=5000
#   export {{TOOL_NAME}}_DATABASE_TYPE=postgres
#   export {{TOOL_NAME}}_DATABASE_URL=postgresql://localhost/{{tool_name_kebab}}
#   export {{TOOL_NAME}}_LOGGING_LEVEL=debug
#
# Then run: {{tool_name_kebab}} list
# The tool will use the environment variable values instead of this file.

################################################################################
# COMMON CONFIGURATIONS
################################################################################

# DEVELOPMENT CONFIGURATION
# Uncomment the following lines to use development defaults:
# [{{tool_name_kebab}}]
# enable_feature = false
#
# [{{tool_name_kebab}}.advanced]
# cache_enabled = false
# timeout_seconds = 60
#
# [logging]
# level = "debug"

# PRODUCTION CONFIGURATION
# Uncomment the following lines to use production defaults:
# [{{tool_name_kebab}}]
# enable_feature = true
#
# [{{tool_name_kebab}}.advanced]
# max_items = 10000
# cache_enabled = true
# cache_ttl_seconds = 7200
#
# [database]
# type = "postgres"
# url = "postgresql://user:password@prod-db:5432/{{tool_name_kebab}}"
# pool_size = 20
#
# [logging]
# level = "warn"
# format = "json"
# output_file = "/var/log/{{tool_name_kebab}}/app.log"

################################################################################
# HELPFUL HINTS
################################################################################

# 1. This file uses TOML format (Tom's Obvious, Minimal Language)
#    - Strings need double quotes: "value"
#    - Numbers don't: 42
#    - Booleans: true or false
#    - Sections use [name] format
#
# 2. Configuration file search order:
#    Tool automatically searches in this order and uses the first found:
#    a) .project/{{tool_name_kebab}}.toml
#    b) .vapora/{{tool_name_kebab}}.toml
#    c) .coder/{{tool_name_kebab}}.toml
#    d) ./{{tool_name_kebab}}.toml
#
# 3. To debug configuration:
#    Run: {{tool_name_kebab}} -v list
#    This shows which config file is being used
#
# 4. For sensitive data (passwords):
#    Use environment variables instead of storing in this file:
#    export {{TOOL_NAME}}_DATABASE_URL="postgresql://..."
#    {{tool_name_kebab}} list
#
# 5. Directory must exist:
#    If using SQLite with path = ".project/{{tool_name_kebab}}.db"
#    Ensure .project/ directory exists:
#    mkdir -p .project
#
# 6. File permissions:
#    Ensure config file is readable:
#    chmod 644 .project/{{tool_name_kebab}}.toml
#
# 7. Validate configuration:
#    Run: {{tool_name_kebab}} validate-config
#    This checks syntax and required fields without running commands
#
# 8. For more information:
#    - See docs/configuration.md for complete guide
#    - See README.md for all features
#    - See QUICKSTART.md for 5-minute setup