Add docs and project files - force for Culurien

docs/3_BACKLOG/P2-001_Binary-URL-Architecture-Mismatch.md

@@ -0,0 +1,90 @@
+# Binary URL Architecture Mismatch Fix
+
+**Priority**: P2 (New Feature - Critical Fix)
+**Source Reference**: From DEVELOPMENT_TODOS.md line 302
+**Status**: Ready for Implementation
+
+## Problem Statement
+
+The installation script template uses `/downloads/{platform}` URLs where platform = "linux", but the server only provides files at `/downloads/linux-amd64` and `/downloads/linux-arm64`. This causes binary downloads to fail with 404 errors, resulting in empty or corrupted files that cannot be executed.
+
+## Feature Description
+
+Fix the binary URL architecture mismatch by implementing server-side redirects that handle generic platform requests and redirect them to the appropriate architecture-specific binaries.
+
+## Acceptance Criteria
+
+1. Server should respond to `/downloads/linux` requests with redirects to `/downloads/linux-amd64`
+2. Server should maintain backward compatibility for existing installation scripts
+3. Installation script should work correctly for x86_64 systems without modification
+4. ARM systems should be properly handled with appropriate redirects
+5. Error handling should return clear messages for unsupported architectures
+
+## Technical Approach
+
+### Option D: Server-Side Redirect Implementation (Recommended)
+
+1. **Modify Download Handler** (`aggregator-server/internal/api/handlers/downloads.go`)
+   - Add route handler for `/downloads/{platform}` where platform is generic ("linux", "windows")
+   - Detect client architecture from User-Agent headers or default to x86_64
+   - Return HTTP 301 redirect to architecture-specific URL
+   - Example: `/downloads/linux` → `/downloads/linux-amd64`
+
+2. **Architecture Detection**
+   - Default x86_64 systems to `/downloads/linux-amd64`
+   - Use User-Agent parsing for ARM detection when available
+   - Fallback to x86_64 for unknown architectures
+
+3. **Error Handling**
+   - Return proper 404 for truly unsupported platforms
+   - Log redirect attempts for monitoring
+
+## Definition of Done
+
+- ✅ Installation scripts can successfully download binaries using generic platform URLs
+- ✅ No 404 errors for x86_64 systems
+- ✅ Proper redirect behavior implemented
+- ✅ Backward compatibility maintained
+- ✅ Error cases handled gracefully
+- ✅ Integration testing shows successful agent installations
+
+## Test Plan
+
+1. **Unit Tests**
+   - Test redirect handler with various User-Agent strings
+   - Test architecture detection logic
+   - Test error handling for invalid platforms
+
+2. **Integration Tests**
+   - Test complete installation flow using generic URLs
+   - Test Linux x86_64 installation (should redirect to amd64)
+   - Test Windows x86_64 installation
+   - Test error handling for unsupported platforms
+
+3. **Manual Tests**
+   - Run installation script on fresh Linux system
+   - Verify binary download succeeds
+   - Verify agent starts correctly after installation
+   - Test with both generic and specific URLs
+
+## Files to Modify
+
+- `aggregator-server/internal/api/handlers/downloads.go` - Add redirect handler
+- `aggregator-server/cmd/server/main.go` - Add new route
+- Test files for the download handler
+
+## Estimated Effort
+
+- **Development**: 4-6 hours
+- **Testing**: 2-3 hours
+- **Review**: 1-2 hours
+
+## Dependencies
+
+- None - this is a self-contained server-side fix
+- Install script templates can remain unchanged
+- Existing architecture-specific download endpoints remain functional
+
+## Risk Assessment
+
+**Low Risk** - This is purely additive functionality that maintains backward compatibility while fixing a critical bug. The redirect pattern is a well-established HTTP pattern with minimal risk of side effects.