# ADR-002: Distribution Strategy\n\n## Status\n\nAccepted\n\n## Context\n\nProvisioning needed a clean distribution strategy that separates user-facing tools from development artifacts. Key challenges included:\n\n1. **Development Artifacts Mixed with Production**: Build tools, test files, and development utilities scattered throughout user directories\n2. **Complex Installation Process**: Users had to navigate through development-specific directories and files\n3. **Unclear User Experience**: No clear distinction between what users need versus what developers need\n4. **Configuration Complexity**: Multiple configuration files with unclear precedence and purpose\n5. **Workspace Pollution**: User workspaces contained development-only files and directories\n6. **Path Resolution Issues**: Complex path resolution logic mixing development and production concerns\n\nThe system required a distribution strategy that provides:\n\n- Clean user experience without development artifacts\n- Clear separation between user and development tools\n- Simplified configuration management\n- Consistent installation and deployment patterns\n- Maintainable development workflow\n\n## Decision\n\nImplement a **layered distribution strategy** with clear separation between development and user environments:\n\n### Distribution Layers\n\n1. **Core Distribution Layer**: Essential user-facing components\n - Main CLI tools and libraries\n - Configuration templates and defaults\n - Provider implementations\n - Task service definitions\n\n2. **Development Layer**: Development-specific tools and artifacts\n - Build scripts and development utilities\n - Test suites and validation tools\n - Development configuration templates\n - Code generation tools\n\n3. **Workspace Layer**: User-specific customization and data\n - User configurations and overrides\n - Local state and cache files\n - Custom extensions and plugins\n - User-specific templates and workflows\n\n### Distribution Structure\n\n```{$detected_lang}\n# User Distribution\n/usr/local/bin/\n├── provisioning # Main CLI entry point\n└── provisioning-* # Supporting utilities\n\n/usr/local/share/provisioning/\n├── core/ # Core libraries and modules\n├── providers/ # Provider implementations\n├── taskservs/ # Task service definitions\n├── templates/ # Configuration templates\n└── config.defaults.toml # System-wide defaults\n\n# User Workspace\n~/workspace/provisioning/\n├── config.user.toml # User preferences\n├── infra/ # User infrastructure definitions\n├── extensions/ # User extensions\n└── cache/ # Local cache and state\n\n# Development Environment\n<project-root>/\n├── src/ # Source code\n├── scripts/ # Development tools\n├── tests/ # Test suites\n└── tools/ # Build and development utilities\n```\n\n### Key Distribution Principles\n\n1. **Clean Separation**: Development artifacts never appear in user installations\n2. **Hierarchical Configuration**: Clear precedence from system defaults to user overrides\n3. **Self-Contained User Tools**: Users can work without accessing development directories\n4. **Workspace Isolation**: User data and customizations isolated from system installation\n5. **Consistent Paths**: Predictable path resolution across different installation types\n6. **Version Management**: Clear versioning and upgrade paths for distributed components\n\n## Consequences\n\n### Positive\n\n- **Clean User Experience**: Users interact only with production-ready tools and interfaces\n- **Simplified Installation**: Clear installation process without development complexity\n- **Workspace Isolation**: User customizations don't interfere with system installation\n- **Development Efficiency**: Developers can work with full toolset without affecting users\n- **Configuration Clarity**: C
