# Configuration System (v2.0.0)

## ⚠️ Migration Completed (2025-09-23)

The system has been migrated from ENV-based to config-driven architecture.

- **65+ files migrated** across entire codebase
- **200+ ENV variables replaced** with 476 config accessors
- **16 token-efficient agents** used for systematic migration
- **92% token efficiency** achieved vs monolithic approach

## Configuration Files

- **Primary Config**: `config.defaults.toml` (system defaults)
- **User Config**: `config.user.toml` (user preferences)
- **Environment Configs**: `config.{dev,test,prod}.toml.example`
- **Hierarchical Loading**: defaults → user → project → infra → env → runtime
- **Interpolation**: `{{paths.base}}`, `{{env.HOME}}`, `{{now.date}}`, `{{git.branch}}`

## Essential Commands

- `provisioning validate config` - Validate configuration
- `provisioning env` - Show environment variables
- `provisioning allenv` - Show all config and environment
- `PROVISIONING_ENV=prod provisioning` - Use specific environment

## Configuration Architecture

See [ADR-010: Configuration Format Strategy](../architecture/adr/adr-010-configuration-format-strategy.md) for complete rationale and design patterns.

### Configuration Loading Hierarchy (Priority)

When loading configuration, precedence is (highest to lowest):

1. **Runtime Arguments** - CLI flags and direct user input
2. **Environment Variables** - `PROVISIONING_*` overrides
3. **User Configuration** - `~/.config/provisioning/user_config.yaml`
4. **Infrastructure Configuration** - Nickel schemas, extensions, provider configs
5. **System Defaults** - `provisioning/config/config.defaults.toml`

### File Type Guidelines

**For new configuration**:

- Infrastructure/schemas → **Use Nickel** (type-safe, schema-validated)
- Application settings → **Use TOML** (hierarchical, supports interpolation)
- Kubernetes/CI-CD → **Use YAML** (standard, ecosystem-compatible)

**For existing workspace configs**:

- Nickel is the primary configuration language
- All new workspaces use Nickel exclusively