engswee · d-sooter · Dec 23, 2025 · Jan 13, 2026 · Feb 2, 2026 · Feb 2, 2026
diff --git a/.github/workflows/build-artifacts.yml b/.github/workflows/build-artifacts.yml
@@ -0,0 +1,93 @@
+name: Build Artifacts
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches:
+      - main
+    paths-ignore:
+      - 'docs/**'
+      - 'licenses/**'
+      - '*.md'
+      - '.gitignore'
+      - '.gitattributes'
+      - 'LICENSE'
+      - 'NOTICE'
+      - '.github/**'
+  workflow_dispatch:
+
+jobs:
+  build-binaries:
+    name: Build Cross-Platform Binaries
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # Fetch all history for proper version tagging
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version-file: 'go.mod'
+
+    - name: Build all platforms
+      run: make build-all
+      env:
+        CGO_ENABLED: 0
+
+    - name: List built artifacts
+      run: |
+        echo "Built artifacts:"
+        ls -lh bin/
+
+    - name: Upload Windows AMD64 binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-windows-amd64
+        path: bin/flashpipex-windows-amd64.exe
+        if-no-files-found: error
+        retention-days: 90
+
+    - name: Upload Linux AMD64 binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-linux-amd64
+        path: bin/flashpipex-linux-amd64
+        if-no-files-found: error
+        retention-days: 90
+
+    - name: Upload Linux ARM64 binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-linux-arm64
+        path: bin/flashpipex-linux-arm64
+        if-no-files-found: error
+        retention-days: 90
+
+    - name: Upload macOS AMD64 binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-darwin-amd64
+        path: bin/flashpipex-darwin-amd64
+        if-no-files-found: error
+        retention-days: 90
+
+    - name: Upload macOS ARM64 binary
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-darwin-arm64
+        path: bin/flashpipex-darwin-arm64
+        if-no-files-found: error
+        retention-days: 90
+
+    - name: Upload all binaries as single archive
+      uses: actions/upload-artifact@v4
+      with:
+        name: flashpipex-all-platforms
+        path: bin/*
+        if-no-files-found: error
+        retention-days: 90
diff --git a/DOCUMENTATION_CONSOLIDATION.md b/DOCUMENTATION_CONSOLIDATION.md
@@ -0,0 +1,231 @@
+# Documentation Consolidation Summary
+
+**Date:** January 8, 2026
+
+## Overview
+
+The FlashPipe documentation has been reorganized to clearly separate user-facing documentation from internal development documentation, and all example files have been consolidated.
+
+## Changes Made
+
+### 1. Created `dev-docs/` Directory
+
+Moved 8 internal development documentation files to `dev-docs/`:
+
+- ✅ `CLI_PORTING_SUMMARY.md` - CLI porting technical details
+- ✅ `ORCHESTRATOR_ENHANCEMENTS.md` - Enhancement implementation details
+- ✅ `PARTNER_DIRECTORY_MIGRATION.md` - Partner Directory technical migration
+- ✅ `TESTING.md` - Testing guide for contributors
+- ✅ `TEST_COVERAGE_SUMMARY.md` - Test coverage reports
+- ✅ `TEST_QUICK_REFERENCE.md` - Testing quick reference
+- ✅ `UNIT_TESTING_COMPLETION.md` - Test completion status
+- ✅ `README.md` (new) - Index for dev documentation
+
+### 2. Moved User-Facing Documentation to `docs/`
+
+- ✅ `ORCHESTRATOR_MIGRATION.md` → `docs/orchestrator-migration.md` (migration guide for users)
+- ✅ Removed duplicate `ORCHESTRATOR_QUICK_START.md` (already exists in docs/)
+
+### 3. Consolidated Example Files in `docs/examples/`
+
+Moved all example YAML files from root to `docs/examples/`:
+
+- ✅ `orchestrator-config-example.yml`
+- ✅ `flashpipe-cpars-example.yml`
+- ✅ `flashpipe-cpars.yml`
+- ✅ Removed duplicate `orchestrator-config-example copy.yml`
+
+### 4. Created Missing Documentation
+
+- ✅ `docs/config-generate.md` - Comprehensive documentation for the `config-generate` command
+
+### 5. Updated README.md
+
+Enhanced the main README with:
+
+- ✅ Comprehensive "Enhanced Capabilities" section highlighting all new commands:
+  - 🎯 Orchestrator Command
+  - ⚙️ Config Generation
+  - 📁 Partner Directory Management
+- ✅ Reorganized documentation section with clear categories:
+  - New Commands Documentation
+  - Migration Guides
+  - Core FlashPipe Documentation
+  - Examples
+  - Developer Documentation
+- ✅ Updated all documentation links to reflect new file locations
+- ✅ Added reference to `dev-docs/` for contributors
+
+## Final Directory Structure
+
+### Top-Level (Clean!)
+
+```
+ci-helper/
+├── README.md                 ← Main project README
+├── CONTRIBUTING.md           ← Contribution guidelines
+├── CODE_OF_CONDUCT.md        ← Code of conduct
+├── LICENSE                   ← License file
+├── NOTICE                    ← Notice file
+├── docs/                     ← User documentation
+├── dev-docs/                 ← Developer documentation (NEW)
+├── internal/                 ← Source code
+├── cmd/                      ← CLI entry point
+└── ...
+```
+
+### docs/ (User Documentation)
+
+```
+docs/
+├── README files and guides
+├── orchestrator.md                    ← Orchestrator comprehensive guide
+├── orchestrator-quickstart.md         ← Quick start guide
+├── orchestrator-yaml-config.md        ← YAML config reference
+├── orchestrator-migration.md          ← Migration from standalone CLI (MOVED)
+├── config-generate.md                 ← Config generation guide (NEW)
+├── partner-directory.md               ← Partner Directory guide
+├── partner-directory-config-examples.md
+├── flashpipe-cli.md                   ← Core CLI reference
+├── oauth_client.md                    ← OAuth setup
+├── documentation.md                   ← General documentation
+├── release-notes.md                   ← Release notes
+└── examples/                          ← Example configurations
+    ├── orchestrator-config-example.yml (MOVED)
+    ├── flashpipe-cpars-example.yml    (MOVED)
+    ├── flashpipe-cpars.yml            (MOVED)
+    └── flashpipe-config-with-orchestrator.yml
+```
+
+### dev-docs/ (Developer Documentation - NEW)
+
+```
+dev-docs/
+├── README.md                          ← Index (NEW)
+├── CLI_PORTING_SUMMARY.md             (MOVED)
+├── ORCHESTRATOR_ENHANCEMENTS.md       (MOVED)
+├── PARTNER_DIRECTORY_MIGRATION.md     (MOVED)
+├── TESTING.md                         (MOVED)
+├── TEST_COVERAGE_SUMMARY.md           (MOVED)
+├── TEST_QUICK_REFERENCE.md            (MOVED)
+└── UNIT_TESTING_COMPLETION.md         (MOVED)
+```
+
+## Benefits
+
+### For Users
+
+1. **Cleaner Repository Root**: Only essential files (README, CONTRIBUTING, CODE_OF_CONDUCT, LICENSE)
+2. **Clear Documentation Structure**: User docs in `docs/`, examples in `docs/examples/`
+3. **Better Navigation**: README now has comprehensive sections linking to all features
+4. **Complete Command Documentation**: All 4 new commands fully documented
+
+### For Contributors
+
+1. **Dedicated Dev Docs**: All development/internal docs in one place (`dev-docs/`)
+2. **Clear Separation**: Easy to distinguish user-facing vs internal documentation
+3. **Dev Docs Index**: `dev-docs/README.md` provides quick navigation
+
+### For Maintainability
+
+1. **No Duplicate Files**: Removed duplicate ORCHESTRATOR_QUICK_START.md and example files
+2. **Logical Organization**: Related files grouped together
+3. **Updated Cross-References**: All internal links updated to reflect new structure
+
+## Commands Documented
+
+All 4 new FlashPipe commands now have comprehensive documentation:
+
+1. **`flashpipe orchestrator`** - [docs/orchestrator.md](docs/orchestrator.md)
+   - Complete deployment lifecycle orchestration
+   - YAML configuration support
+   - Parallel deployment capabilities
+   - Environment prefix support
+
+2. **`flashpipe config-generate`** - [docs/config-generate.md](docs/config-generate.md) ⭐ NEW
+   - Automatic configuration generation
+   - Smart metadata extraction
+   - Config merging capabilities
+   - Filtering support
+
+3. **`flashpipe pd-snapshot`** - [docs/partner-directory.md](docs/partner-directory.md)
+   - Download Partner Directory parameters
+   - String and binary parameter support
+   - Batch operations
+
+4. **`flashpipe pd-deploy`** - [docs/partner-directory.md](docs/partner-directory.md)
+   - Upload Partner Directory parameters
+   - Full sync mode
+   - Dry run capability
+
+## Migration Impact
+
+### For Existing Users
+
+**No Breaking Changes!** All documentation has been moved but:
+- Old links in external references may need updating
+- All functionality remains the same
+- Examples are now easier to find in `docs/examples/`
+
+### Recommended Updates
+
+If you have external documentation or scripts referencing old paths:
+
+```diff
+- ORCHESTRATOR_MIGRATION.md
++ docs/orchestrator-migration.md
+
+- orchestrator-config-example.yml
++ docs/examples/orchestrator-config-example.yml
+
+- flashpipe-cpars-example.yml
++ docs/examples/flashpipe-cpars-example.yml
+```
+
+## Next Steps
+
+1. ✅ All files organized
+2. ✅ README updated
+3. ✅ Missing documentation created
+4. ✅ Cross-references updated
+5. 📝 Consider updating GitHub Pages site to reflect new structure
+6. 📝 Update any CI/CD pipelines referencing old example paths
+
+## Verification
+
+Run these commands to verify the structure:
+
+```bash
+# Top level should only have essential markdown
+ls *.md
+# Expected: README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md
+
+# Top level should have no example YAML files
+ls *.yml
+# Expected: (empty)
+
+# Dev docs should have 8 files
+ls dev-docs/
+# Expected: 8 markdown files including README.md
+
+# Examples should have 4 YAML files
+ls docs/examples/
+# Expected: 4 YAML files
+
+# Docs should include new config-generate.md
+ls docs/config-generate.md
+# Expected: Found
+```
+
+## Summary
+
+✅ **8 development documentation files** moved to `dev-docs/`  
+✅ **3 example YAML files** consolidated in `docs/examples/`  
+✅ **1 user migration guide** moved to `docs/`  
+✅ **1 new documentation file** created (`config-generate.md`)  
+✅ **1 dev-docs index** created  
+✅ **README.md** comprehensively updated with all new features  
+✅ **Top-level directory** cleaned up (only essential files remain)  
+
+**Result:** Clear, organized, maintainable documentation structure! 🎉
+