# Build System Documentation\n\nThis document provides comprehensive documentation for the provisioning project's build system, including the complete Makefile reference with 40+\ntargets, build tools, compilation instructions, and troubleshooting.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Quick Start](#quick-start)\n3. [Makefile Reference](#makefile-reference)\n4. [Build Tools](#build-tools)\n5. [Cross-Platform Compilation](#cross-platform-compilation)\n6. [Dependency Management](#dependency-management)\n7. [Troubleshooting](#troubleshooting)\n8. [CI/CD Integration](#cicd-integration)\n\n## Overview\n\nThe build system is a comprehensive, Makefile-based solution that orchestrates:\n\n- **Rust compilation**: Platform binaries (orchestrator, control-center, etc.)\n- **Nushell bundling**: Core libraries and CLI tools\n- **Nickel validation**: Configuration schema validation\n- **Distribution generation**: Multi-platform packages\n- **Release management**: Automated release pipelines\n- **Documentation generation**: API and user documentation\n\n**Location**: `/src/tools/`\n**Main entry point**: `/src/tools/Makefile`\n\n## Quick Start\n\n```{$detected_lang}\n# Navigate to build system\ncd src/tools\n\n# View all available targets\nmake help\n\n# Complete build and package\nmake all\n\n# Development build (quick)\nmake dev-build\n\n# Build for specific platform\nmake linux\nmake macos\nmake windows\n\n# Clean everything\nmake clean\n\n# Check build system status\nmake status\n```\n\n## Makefile Reference\n\n### Build Configuration\n\n**Variables**:\n\n```{$detected_lang}\n# Project metadata\nPROJECT_NAME := provisioning\nVERSION := $(git describe --tags --always --dirty)\nBUILD_TIME := $(date -u +"%Y-%m-%dT%H:%M:%SZ")\n\n# Build configuration\nRUST_TARGET := x86_64-unknown-linux-gnu\nBUILD_MODE := release\nPLATFORMS := linux-amd64,macos-amd64,windows-amd64\nVARIANTS := complete,minimal\n\n# Flags\nVERBOSE := false\nDRY_RUN := false\nPARALLEL := true\n```\n\n### Build Targets\n\n#### Primary Build Targets\n\n**`make all`** - Complete build, package, and test\n\n- Runs: `clean build-all package-all test-dist`\n- Use for: Production releases, complete validation\n\n**`make build-all`** - Build all components\n\n- Runs: `build-platform build-core validate-nickel`\n- Use for: Complete system compilation\n\n**`make build-platform`** - Build platform binaries for all targets\n\n```{$detected_lang}\nmake build-platform\n# Equivalent to:\nnu tools/build/compile-platform.nu \\n    --target x86_64-unknown-linux-gnu \\n    --release \\n    --output-dir dist/platform \\n    --verbose=false\n```\n\n**`make build-core`** - Bundle core Nushell libraries\n\n```{$detected_lang}\nmake build-core\n# Equivalent to:\nnu tools/build/bundle-core.nu \\n    --output-dir dist/core \\n    --config-dir dist/config \\n    --validate \\n    --exclude-dev\n```\n\n**`make validate-nickel`** - Validate and compile Nickel schemas\n\n```{$detected_lang}\nmake validate-nickel\n# Equivalent to:\nnu tools/build/validate-nickel.nu \\n    --output-dir dist/schemas \\n    --format-code \\n    --check-dependencies\n```\n\n**`make build-cross`** - Cross-compile for multiple platforms\n\n- Builds for all platforms in `PLATFORMS` variable\n- Parallel execution support\n- Failure handling for each platform\n\n#### Package Targets\n\n**`make package-all`** - Create all distribution packages\n\n- Runs: `dist-generate package-binaries package-containers`\n\n**`make dist-generate`** - Generate complete distributions\n\n```{$detected_lang}\nmake dist-generate\n# Advanced usage:\nmake dist-generate PLATFORMS=linux-amd64,macos-amd64 VARIANTS=complete\n```\n\n**`make package-binaries`** - Package binaries for distribution\n\n- Creates platform-specific archives\n- Strips debug symbols\n- Generates checksums\n\n**`make package-containers`** - Build container images\n\n- Multi-platform container builds\n- Optimized layers and caching\n- Version tagging\n\n**`make create-archives`** - Create distribution archives\n\n- TAR and ZIP formats\n- Platform-specific and universal archives\n- Compression and checksums\n\n**`make create-installers`** - Create installation packages\n\n- Shell script installers\n- Platform-specific packages (DEB, RPM, MSI)\n- Uninstaller creation\n\n#### Release Targets\n\n**`make release`** - Create a complete release (requires VERSION)\n\n```{$detected_lang}\nmake release VERSION=2.1.0\n```\n\nFeatures:\n\n- Automated changelog generation\n- Git tag creation and push\n- Artifact upload\n- Comprehensive validation\n\n**`make release-draft`** - Create a draft release\n\n- Create without publishing\n- Review artifacts before release\n- Manual approval workflow\n\n**`make upload-artifacts`** - Upload release artifacts\n\n- GitHub Releases\n- Container registries\n- Package repositories\n- Verification and validation\n\n**`make notify-release`** - Send release notifications\n\n- Slack notifications\n- Discord announcements\n- Email notifications\n- Custom webhook support\n\n**`make update-registry`** - Update package manager registries\n\n- Homebrew formula updates\n- APT repository updates\n- Custom registry support\n\n#### Development and Testing Targets\n\n**`make dev-build`** - Quick development build\n\n```{$detected_lang}\nmake dev-build\n# Fast build with minimal validation\n```\n\n**`make test-build`** - Test build system\n\n- Validates build process\n- Runs with test configuration\n- Comprehensive logging\n\n**`make test-dist`** - Test generated distributions\n\n- Validates distribution integrity\n- Tests installation process\n- Platform compatibility checks\n\n**`make validate-all`** - Validate all components\n\n- Nickel schema validation\n- Package validation\n- Configuration validation\n\n**`make benchmark`** - Run build benchmarks\n\n- Times build process\n- Performance analysis\n- Resource usage monitoring\n\n#### Documentation Targets\n\n**`make docs`** - Generate documentation\n\n```{$detected_lang}\nmake docs\n# Generates API docs, user guides, and examples\n```\n\n**`make docs-serve`** - Generate and serve documentation locally\n\n- Starts local HTTP server on port 8000\n- Live documentation browsing\n- Development documentation workflow\n\n#### Utility Targets\n\n**`make clean`** - Clean all build artifacts\n\n```{$detected_lang}\nmake clean\n# Removes all build, distribution, and package directories\n```\n\n**`make clean-dist`** - Clean only distribution artifacts\n\n- Preserves build cache\n- Removes distribution packages\n- Faster cleanup option\n\n**`make install`** - Install the built system locally\n\n- Requires distribution to be built\n- Installs to system directories\n- Creates uninstaller\n\n**`make uninstall`** - Uninstall the system\n\n- Removes system installation\n- Cleans configuration\n- Removes service files\n\n**`make status`** - Show build system status\n\n```{$detected_lang}\nmake status\n# Output:\n# Build System Status\n# ===================\n# Project: provisioning\n# Version: v2.1.0-5-g1234567\n# Git Commit: 1234567890abcdef\n# Build Time: 2025-09-25T14:30:22Z\n#\n# Directories:\n#   Source: /Users/user/repo-cnz/src\n#   Tools: /Users/user/repo-cnz/src/tools\n#   Build: /Users/user/repo-cnz/src/target\n#   Distribution: /Users/user/repo-cnz/src/dist\n#   Packages: /Users/user/repo-cnz/src/packages\n```\n\n**`make info`** - Show detailed system information\n\n- OS and architecture details\n- Tool versions (Nushell, Rust, Docker, Git)\n- Environment information\n- Build prerequisites\n\n#### CI/CD Integration Targets\n\n**`make ci-build`** - CI build pipeline\n\n- Complete validation build\n- Suitable for automated CI systems\n- Comprehensive testing\n\n**`make ci-test`** - CI test pipeline\n\n- Validation and testing only\n- Fast feedback for pull requests\n- Quality assurance\n\n**`make ci-release`** - CI release pipeline\n\n- Build and packaging for releases\n- Artifact preparation\n- Release candidate creation\n\n**`make cd-deploy`** - CD deployment pipeline\n\n- Complete release and deployment\n- Artifact upload and distribution\n- User notifications\n\n#### Platform-Specific Targets\n\n**`make linux`** - Build for Linux only\n\n```{$detected_lang}\nmake linux\n# Sets PLATFORMS=linux-amd64\n```\n\n**`make macos`** - Build for macOS only\n\n```{$detected_lang}\nmake macos\n# Sets PLATFORMS=macos-amd64\n```\n\n**`make windows`** - Build for Windows only\n\n```{$detected_lang}\nmake windows\n# Sets PLATFORMS=windows-amd64\n```\n\n#### Debugging Targets\n\n**`make debug`** - Build with debug information\n\n```{$detected_lang}\nmake debug\n# Sets BUILD_MODE=debug VERBOSE=true\n```\n\n**`make debug-info`** - Show debug information\n\n- Make variables and environment\n- Build system diagnostics\n- Troubleshooting information\n\n## Build Tools\n\n### Core Build Scripts\n\nAll build tools are implemented as Nushell scripts with comprehensive parameter validation and error handling.\n\n#### `/src/tools/build/compile-platform.nu`\n\n**Purpose**: Compiles all Rust components for distribution\n\n**Components Compiled**:\n\n- `orchestrator` → `provisioning-orchestrator` binary\n- `control-center` → `control-center` binary\n- `control-center-ui` → Web UI assets\n- `mcp-server-rust` → MCP integration binary\n\n**Usage**:\n\n```{$detected_lang}\nnu compile-platform.nu [options]\n\nOptions:\n  --target STRING          Target platform (default: x86_64-unknown-linux-gnu)\n  --release                Build in release mode\n  --features STRING        Comma-separated features to enable\n  --output-dir STRING      Output directory (default: dist/platform)\n  --verbose                Enable verbose logging\n  --clean                  Clean before building\n```\n\n**Example**:\n\n```{$detected_lang}\nnu compile-platform.nu \\n    --target x86_64-apple-darwin \\n    --release \\n    --features "surrealdb,telemetry" \\n    --output-dir dist/macos \\n    --verbose\n```\n\n#### `/src/tools/build/bundle-core.nu`\n\n**Purpose**: Bundles Nushell core libraries and CLI for distribution\n\n**Components Bundled**:\n\n- Nushell provisioning CLI wrapper\n- Core Nushell libraries (`lib_provisioning`)\n- Configuration system\n- Template system\n- Extensions and plugins\n\n**Usage**:\n\n```{$detected_lang}\nnu bundle-core.nu [options]\n\nOptions:\n  --output-dir STRING      Output directory (default: dist/core)\n  --config-dir STRING      Configuration directory (default: dist/config)\n  --validate               Validate Nushell syntax\n  --compress               Compress bundle with gzip\n  --exclude-dev            Exclude development files (default: true)\n  --verbose                Enable verbose logging\n```\n\n**Validation Features**:\n\n- Syntax validation of all Nushell files\n- Import dependency checking\n- Function signature validation\n- Test execution (if tests present)\n\n#### `/src/tools/build/validate-nickel.nu`\n\n**Purpose**: Validates and compiles Nickel schemas\n\n**Validation Process**:\n\n1. Syntax validation of all `.ncl` files\n2. Schema dependency checking\n3. Type constraint validation\n4. Example validation against schemas\n5. Documentation generation\n\n**Usage**:\n\n```{$detected_lang}\nnu validate-nickel.nu [options]\n\nOptions:\n  --output-dir STRING      Output directory (default: dist/schemas)\n  --format-code            Format Nickel code during validation\n  --check-dependencies     Validate schema dependencies\n  --verbose                Enable verbose logging\n```\n\n#### `/src/tools/build/test-distribution.nu`\n\n**Purpose**: Tests generated distributions for correctness\n\n**Test Types**:\n\n- **Basic**: Installation test, CLI help, version check\n- **Integration**: Server creation, configuration validation\n- **Complete**: Full workflow testing including cluster operations\n\n**Usage**:\n\n```{$detected_lang}\nnu test-distribution.nu [options]\n\nOptions:\n  --dist-dir STRING        Distribution directory (default: dist)\n  --test-types STRING      Test types: basic,integration,complete\n  --platform STRING        Target platform for testing\n  --cleanup                Remove test files after completion\n  --verbose                Enable verbose logging\n```\n\n#### `/src/tools/build/clean-build.nu`\n\n**Purpose**: Intelligent build artifact cleanup\n\n**Cleanup Scopes**:\n\n- **all**: Complete cleanup (build, dist, packages, cache)\n- **dist**: Distribution artifacts only\n- **cache**: Build cache and temporary files\n- **old**: Files older than specified age\n\n**Usage**:\n\n```{$detected_lang}\nnu clean-build.nu [options]\n\nOptions:\n  --scope STRING           Cleanup scope: all,dist,cache,old\n  --age DURATION          Age threshold for 'old' scope (default: 7d)\n  --force                  Force cleanup without confirmation\n  --dry-run               Show what would be cleaned without doing it\n  --verbose               Enable verbose logging\n```\n\n### Distribution Tools\n\n#### `/src/tools/distribution/generate-distribution.nu`\n\n**Purpose**: Main distribution generator orchestrating the complete process\n\n**Generation Process**:\n\n1. Platform binary compilation\n2. Core library bundling\n3. Nickel schema validation and packaging\n4. Configuration system preparation\n5. Documentation generation\n6. Archive creation and compression\n7. Installer generation\n8. Validation and testing\n\n**Usage**:\n\n```{$detected_lang}\nnu generate-distribution.nu [command] [options]\n\nCommands:\n  <default>                Generate complete distribution\n  quick                    Quick development distribution\n  status                   Show generation status\n\nOptions:\n  --version STRING         Version to build (default: auto-detect)\n  --platforms STRING       Comma-separated platforms\n  --variants STRING        Variants: complete,minimal\n  --output-dir STRING      Output directory (default: dist)\n  --compress               Enable compression\n  --generate-docs          Generate documentation\n  --parallel-builds        Enable parallel builds\n  --validate-output        Validate generated output\n  --verbose                Enable verbose logging\n```\n\n**Advanced Examples**:\n\n```{$detected_lang}\n# Complete multi-platform release\nnu generate-distribution.nu \\n    --version 2.1.0 \\n    --platforms linux-amd64,macos-amd64,windows-amd64 \\n    --variants complete,minimal \\n    --compress \\n    --generate-docs \\n    --parallel-builds \\n    --validate-output\n\n# Quick development build\nnu generate-distribution.nu quick \\n    --platform linux \\n    --variant minimal\n\n# Status check\nnu generate-distribution.nu status\n```\n\n#### `/src/tools/distribution/create-installer.nu`\n\n**Purpose**: Creates platform-specific installers\n\n**Installer Types**:\n\n- **shell**: Shell script installer (cross-platform)\n- **package**: Platform packages (DEB, RPM, MSI, PKG)\n- **container**: Container image with provisioning\n- **source**: Source distribution with build instructions\n\n**Usage**:\n\n```{$detected_lang}\nnu create-installer.nu DISTRIBUTION_DIR [options]\n\nOptions:\n  --output-dir STRING      Installer output directory\n  --installer-types STRING Installer types: shell,package,container,source\n  --platforms STRING       Target platforms\n  --include-services       Include systemd/launchd service files\n  --create-uninstaller     Generate uninstaller\n  --validate-installer     Test installer functionality\n  --verbose                Enable verbose logging\n```\n\n### Package Tools\n\n#### `/src/tools/package/package-binaries.nu`\n\n**Purpose**: Packages compiled binaries for distribution\n\n**Package Formats**:\n\n- **archive**: TAR.GZ and ZIP archives\n- **standalone**: Single binary with embedded resources\n- **installer**: Platform-specific installer packages\n\n**Features**:\n\n- Binary stripping for size reduction\n- Compression optimization\n- Checksum generation (SHA256, MD5)\n- Digital signing (if configured)\n\n#### `/src/tools/package/build-containers.nu`\n\n**Purpose**: Builds optimized container images\n\n**Container Features**:\n\n- Multi-stage builds for minimal image size\n- Security scanning integration\n- Multi-platform image generation\n- Layer caching optimization\n- Runtime environment configuration\n\n### Release Tools\n\n#### `/src/tools/release/create-release.nu`\n\n**Purpose**: Automated release creation and management\n\n**Release Process**:\n\n1. Version validation and tagging\n2. Changelog generation from git history\n3. Asset building and validation\n4. Release creation (GitHub, GitLab, etc.)\n5. Asset upload and verification\n6. Release announcement preparation\n\n**Usage**:\n\n```{$detected_lang}\nnu create-release.nu [options]\n\nOptions:\n  --version STRING         Release version (required)\n  --asset-dir STRING       Directory containing release assets\n  --draft                  Create draft release\n  --prerelease             Mark as pre-release\n  --generate-changelog     Auto-generate changelog\n  --push-tag               Push git tag\n  --auto-upload            Upload assets automatically\n  --verbose                Enable verbose logging\n```\n\n## Cross-Platform Compilation\n\n### Supported Platforms\n\n**Primary Platforms**:\n\n- `linux-amd64` (x86_64-unknown-linux-gnu)\n- `macos-amd64` (x86_64-apple-darwin)\n- `windows-amd64` (x86_64-pc-windows-gnu)\n\n**Additional Platforms**:\n\n- `linux-arm64` (aarch64-unknown-linux-gnu)\n- `macos-arm64` (aarch64-apple-darwin)\n- `freebsd-amd64` (x86_64-unknown-freebsd)\n\n### Cross-Compilation Setup\n\n**Install Rust Targets**:\n\n```{$detected_lang}\n# Install additional targets\nrustup target add x86_64-apple-darwin\nrustup target add x86_64-pc-windows-gnu\nrustup target add aarch64-unknown-linux-gnu\nrustup target add aarch64-apple-darwin\n```\n\n**Platform-Specific Dependencies**:\n\n**macOS Cross-Compilation**:\n\n```{$detected_lang}\n# Install osxcross toolchain\nbrew install FiloSottile/musl-cross/musl-cross\nbrew install mingw-w64\n```\n\n**Windows Cross-Compilation**:\n\n```{$detected_lang}\n# Install Windows dependencies\nbrew install mingw-w64\n# or on Linux:\nsudo apt-get install gcc-mingw-w64\n```\n\n### Cross-Compilation Usage\n\n**Single Platform**:\n\n```{$detected_lang}\n# Build for macOS from Linux\nmake build-platform RUST_TARGET=x86_64-apple-darwin\n\n# Build for Windows\nmake build-platform RUST_TARGET=x86_64-pc-windows-gnu\n```\n\n**Multiple Platforms**:\n\n```{$detected_lang}\n# Build for all configured platforms\nmake build-cross\n\n# Specify platforms\nmake build-cross PLATFORMS=linux-amd64,macos-amd64,windows-amd64\n```\n\n**Platform-Specific Targets**:\n\n```{$detected_lang}\n# Quick platform builds\nmake linux      # Linux AMD64\nmake macos      # macOS AMD64\nmake windows    # Windows AMD64\n```\n\n## Dependency Management\n\n### Build Dependencies\n\n**Required Tools**:\n\n- **Nushell 0.107.1+**: Core shell and scripting\n- **Rust 1.70+**: Platform binary compilation\n- **Cargo**: Rust package management\n- **KCL 0.11.2+**: Configuration language\n- **Git**: Version control and tagging\n\n**Optional Tools**:\n\n- **Docker**: Container image building\n- **Cross**: Simplified cross-compilation\n- **SOPS**: Secrets management\n- **Age**: Encryption for secrets\n\n### Dependency Validation\n\n**Check Dependencies**:\n\n```{$detected_lang}\nmake info\n# Shows versions of all required tools\n\n# Output example:\n# Tool Versions:\n#   Nushell: 0.107.1\n#   Rust: rustc 1.75.0\n#   Docker: Docker version 24.0.6\n#   Git: git version 2.42.0\n```\n\n**Install Missing Dependencies**:\n\n```{$detected_lang}\n# Install Nushell\ncargo install nu\n\n# Install Nickel\ncargo install nickel\n\n# Install Cross (for cross-compilation)\ncargo install cross\n```\n\n### Dependency Caching\n\n**Rust Dependencies**:\n\n- Cargo cache: `~/.cargo/registry`\n- Target cache: `target/` directory\n- Cross-compilation cache: `~/.cache/cross`\n\n**Build Cache Management**:\n\n```{$detected_lang}\n# Clean Cargo cache\ncargo clean\n\n# Clean cross-compilation cache\ncross clean\n\n# Clean all caches\nmake clean SCOPE=cache\n```\n\n## Troubleshooting\n\n### Common Build Issues\n\n#### Rust Compilation Errors\n\n**Error**: `linker 'cc' not found`\n\n```{$detected_lang}\n# Solution: Install build essentials\nsudo apt-get install build-essential  # Linux\nxcode-select --install                 # macOS\n```\n\n**Error**: `target not found`\n\n```{$detected_lang}\n# Solution: Install target\nrustup target add x86_64-unknown-linux-gnu\n```\n\n**Error**: Cross-compilation linking errors\n\n```{$detected_lang}\n# Solution: Use cross instead of cargo\ncargo install cross\nmake build-platform CROSS=true\n```\n\n#### Nushell Script Errors\n\n**Error**: `command not found`\n\n```{$detected_lang}\n# Solution: Ensure Nushell is in PATH\nwhich nu\nexport PATH="$HOME/.cargo/bin:$PATH"\n```\n\n**Error**: Permission denied\n\n```{$detected_lang}\n# Solution: Make scripts executable\nchmod +x src/tools/build/*.nu\n```\n\n**Error**: Module not found\n\n```{$detected_lang}\n# Solution: Check working directory\ncd src/tools\nnu build/compile-platform.nu --help\n```\n\n#### Nickel Validation Errors\n\n**Error**: `nickel command not found`\n\n```{$detected_lang}\n# Solution: Install Nickel\ncargo install nickel\n# or\nbrew install nickel\n```\n\n**Error**: Schema validation failed\n\n```{$detected_lang}\n# Solution: Check Nickel syntax\nnickel fmt schemas/\nnickel check schemas/\n```\n\n### Build Performance Issues\n\n#### Slow Compilation\n\n**Optimizations**:\n\n```{$detected_lang}\n# Enable parallel builds\nmake build-all PARALLEL=true\n\n# Use faster linker\nexport RUSTFLAGS="-C link-arg=-fuse-ld=lld"\n\n# Increase build jobs\nexport CARGO_BUILD_JOBS=8\n```\n\n**Cargo Configuration** (`~/.cargo/config.toml`):\n\n```{$detected_lang}\n[build]\njobs = 8\n\n[target.x86_64-unknown-linux-gnu]\nlinker = "lld"\n```\n\n#### Memory Issues\n\n**Solutions**:\n\n```{$detected_lang}\n# Reduce parallel jobs\nexport CARGO_BUILD_JOBS=2\n\n# Use debug build for development\nmake dev-build BUILD_MODE=debug\n\n# Clean up between builds\nmake clean-dist\n```\n\n### Distribution Issues\n\n#### Missing Assets\n\n**Validation**:\n\n```{$detected_lang}\n# Test distribution\nmake test-dist\n\n# Detailed validation\nnu src/tools/package/validate-package.nu dist/\n```\n\n#### Size Optimization\n\n**Optimizations**:\n\n```{$detected_lang}\n# Strip binaries\nmake package-binaries STRIP=true\n\n# Enable compression\nmake dist-generate COMPRESS=true\n\n# Use minimal variant\nmake dist-generate VARIANTS=minimal\n```\n\n### Debug Mode\n\n**Enable Debug Logging**:\n\n```{$detected_lang}\n# Set environment\nexport PROVISIONING_DEBUG=true\nexport RUST_LOG=debug\n\n# Run with debug\nmake debug\n\n# Verbose make output\nmake build-all VERBOSE=true\n```\n\n**Debug Information**:\n\n```{$detected_lang}\n# Show debug information\nmake debug-info\n\n# Build system status\nmake status\n\n# Tool information\nmake info\n```\n\n## CI/CD Integration\n\n### GitHub Actions\n\n**Example Workflow** (`.github/workflows/build.yml`):\n\n```{$detected_lang}\nname: Build and Test\non: [push, pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Setup Nushell\n        uses: hustcer/setup-nu@v3.5\n\n      - name: Setup Rust\n        uses: actions-rs/toolchain@v1\n        with:\n          toolchain: stable\n\n      - name: CI Build\n        run: |\n          cd src/tools\n          make ci-build\n\n      - name: Upload Artifacts\n        uses: actions/upload-artifact@v4\n        with:\n          name: build-artifacts\n          path: src/dist/\n```\n\n### Release Automation\n\n**Release Workflow**:\n\n```{$detected_lang}\nname: Release\non:\n  push:\n    tags: ['v*']\n\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n\n      - name: Build Release\n        run: |\n          cd src/tools\n          make ci-release VERSION=${{ github.ref_name }}\n\n      - name: Create Release\n        run: |\n          cd src/tools\n          make release VERSION=${{ github.ref_name }}\n```\n\n### Local CI Testing\n\n**Test CI Pipeline Locally**:\n\n```{$detected_lang}\n# Run CI build pipeline\nmake ci-build\n\n# Run CI test pipeline\nmake ci-test\n\n# Full CI/CD pipeline\nmake ci-release\n```\n\nThis build system provides a comprehensive, maintainable foundation for the provisioning project's development lifecycle, from local development to\nproduction releases.