# 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**: Clear hierarchy and precedence for configuration settings\n- **Maintainable Updates**: System updates don't affect user customizations\n- **Path Simplicity**: Predictable path resolution without development-specific logic\n- **Security Isolation**: User workspace separated from system components\n\n### Negative\n\n- **Distribution Complexity**: Multiple distribution targets require coordinated build processes\n- **Path Management**: More complex path resolution logic to support multiple layers\n- **Migration Overhead**: Existing users need to migrate to new workspace structure\n- **Documentation Burden**: Need clear documentation for different user types\n- **Testing Complexity**: Must validate distribution across different installation scenarios\n\n### Neutral\n\n- **Development Patterns**: Different patterns for development versus production deployment\n- **Configuration Strategy**: Layer-specific configuration management approaches\n- **Tool Integration**: Different integration patterns for development versus user tools\n\n## Alternatives Considered\n\n### Alternative 1: Monolithic Distribution\n\nShip everything (development and production) in single package.\n**Rejected**: Creates confusing user experience and bloated installations. Mixes development concerns with user needs.\n\n### Alternative 2: Container-Only Distribution\n\nPackage entire system as container images only.\n**Rejected**: Limits deployment flexibility and complicates local development workflows. Not suitable for all use cases.\n\n### Alternative 3: Source-Only Distribution\n\nRequire users to build from source with development environment.\n**Rejected**: Creates high barrier to entry and mixes user concerns with development complexity.\n\n### Alternative 4: Plugin-Based Distribution\n\nMinimal core with everything else as downloadable plugins.\n**Rejected**: Would fragment essential functionality and complicate initial setup. Network dependency for basic functionality.\n\n### Alternative 5: Environment-Based Distribution\n\nUse environment variables to control what gets installed.\n**Rejected**: Creates complex configuration matrix and potential for inconsistent installations.\n\n## Implementation Details\n\n### Distribution Build Process\n\n1. **Core Layer Build**: Extract essential user components from source\n2. **Template Processing**: Generate configuration templates with proper defaults\n3. **Path Resolution**: Generate path resolution logic for different installation types\n4. **Documentation Generation**: Create user-specific documentation excluding development details\n5. **Package Creation**: Build distribution packages for different platforms\n6. **Validation Testing**: Test installations in clean environments\n\n### Configuration Hierarchy\n\n```{$detected_lang}\nSystem Defaults (lowest precedence)\n└── User Configuration\n    └── Project Configuration\n        └── Infrastructure Configuration\n            └── Environment Configuration\n                └── Runtime Configuration (highest precedence)\n```\n\n### Workspace Management\n\n- **Automatic Creation**: User workspace created on first run\n- **Template Initialization**: Workspace populated with configuration templates\n- **Version Tracking**: Workspace tracks compatible system versions\n- **Migration Support**: Automatic migration between workspace versions\n- **Backup Integration**: Workspace backup and restore capabilities\n\n## References\n\n- Project Structure Decision (ADR-001)\n- Workspace Isolation Decision (ADR-003)\n- Configuration System Migration (CLAUDE.md)\n- User Experience Guidelines (Design Principles)\n- Installation and Deployment Procedures