terraphim
diff --git a/‎.codex/rules‎
Lines changed: 50 additions & 0 deletions b/‎.codex/rules‎
Lines changed: 50 additions & 0 deletions
diff --git a/‎.cursor/rules/ubs.md‎
Lines changed: 50 additions & 0 deletions b/‎.cursor/rules/ubs.md‎
Lines changed: 50 additions & 0 deletions
diff --git a/‎.docs/constraints-analysis.md‎
Lines changed: 257 additions & 0 deletions b/‎.docs/constraints-analysis.md‎
Lines changed: 257 additions & 0 deletions
@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````
@@ -0,0 +1,50 @@
+
+````markdown
+## UBS Quick Reference for AI Agents
+
+UBS stands for "Ultimate Bug Scanner": **The AI Coding Agent's Secret Weapon: Flagging Likely Bugs for Fixing Early On**
+
+**Install:** `curl -sSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh | bash`
+
+**Golden Rule:** `ubs <changed-files>` before every commit. Exit 0 = safe. Exit >0 = fix & re-run.
+
+**Commands:**
+```bash
+ubs file.ts file2.py                    # Specific files (< 1s) — USE THIS
+ubs $(git diff --name-only --cached)    # Staged files — before commit
+ubs --only=js,python src/               # Language filter (3-5x faster)
+ubs --ci --fail-on-warning .            # CI mode — before PR
+ubs --help                              # Full command reference
+ubs sessions --entries 1                # Tail the latest install session log
+ubs .                                   # Whole project (ignores things like .venv and node_modules automatically)
+```
+
+**Output Format:**
+```
+⚠️  Category (N errors)
+    file.ts:42:5 – Issue description
+    💡 Suggested fix
+Exit code: 1
+```
+Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fail
+
+**Fix Workflow:**
+1. Read finding → category + fix suggestion
+2. Navigate `file:line:col` → view context
+3. Verify real issue (not false positive)
+4. Fix root cause (not symptom)
+5. Re-run `ubs <file>` → exit 0
+6. Commit
+
+**Speed Critical:** Scope to changed files. `ubs src/file.ts` (< 1s) vs `ubs .` (30s). Never full scan for small edits.
+
+**Bug Severity:**
+- **Critical** (always fix): Null safety, XSS/injection, async/await, memory leaks
+- **Important** (production): Type narrowing, division-by-zero, resource leaks
+- **Contextual** (judgment): TODO/FIXME, console logs
+
+**Anti-Patterns:**
+- ❌ Ignore findings → ✅ Investigate each
+- ❌ Full scan per edit → ✅ Scope to file
+- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
+````
@@ -0,0 +1,257 @@
+# Terraphim AI Release Constraints Analysis
+
+## Business Constraints
+
+### Release Frequency and Cadence
+- **Continuous Delivery Pressure**: Community expects regular updates with bug fixes
+- **Feature Release Timeline**: New features need predictable release windows
+- **Patch Release Speed**: Security fixes must be deployed rapidly
+- **Backward Compatibility**: Must maintain API stability between major versions
+- **Version Bumping Strategy**: Semantic versioning with clear breaking change policies
+
+### Community and User Expectations
+- **Zero-Downtime Updates**: Production deployments should not require service interruption
+- **Rollback Capability**: Users need ability to revert problematic updates
+- **Multi-Version Support**: Ability to run multiple versions concurrently for testing
+- **Documentation同步**: Release notes must match actual changes
+- **Transparent Roadmap**: Clear communication about future changes and deprecations
+
+### License and Compliance Requirements
+- **Open Source Compliance**: All licenses must be properly declared
+- **Third-Party Dependencies**: SPDX compliance and vulnerability disclosure
+- **Export Controls**: No restricted cryptographic components without compliance
+- **Data Privacy**: GDPR and privacy law compliance for user data handling
+- **Attribution Requirements**: Proper credit for open source dependencies
+
+## Technical Constraints
+
+### Multi-Platform Build Complexity
+
+#### Architecture Support Matrix
+| Architecture | Build Tool | Cross-Compilation | Testing Capability |
+|--------------|------------|-------------------|--------------------|
+| x86_64-linux | Native | Not needed | Full CI/CD |
+| aarch64-linux | Cross | QEMU required | Limited testing |
+| armv7-linux | Cross | QEMU required | Limited testing |
+| x86_64-macos | Native (self-hosted) | Not needed | Partial testing |
+| aarch64-macos | Native (self-hosted) | Not needed | Partial testing |
+| x86_64-windows | Native | Not needed | Full CI/CD |
+
+#### Toolchain Dependencies
+- **Rust Version**: Consistent toolchain across all platforms
+- **Cross-Compilation Tools**: QEMU, binutils for non-native builds
+- **System Libraries**: Platform-specific dependency management
+- **Certificate Signing**: Platform-specific code signing certificates
+- **Package Building**: cargo-deb, cargo-rpm, Tauri bundler tools
+
+### Dependency Management Constraints
+
+#### System-Level Dependencies
+```toml
+# Example dependency constraints
+[dependencies]
+# Core dependencies with version ranges
+tokio = { version = "1.0", features = ["full"] }
+serde = { version = "1.0", features = ["derive"] }
+clap = { version = "4.0", features = ["derive"] }
+
+# Platform-specific dependencies
+[target.'cfg(unix)'.dependencies]
+nix = "0.27"
+
+[target.'cfg(windows)'.dependencies]
+winapi = { version = "0.3", features = ["winuser"] }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+core-foundation = "0.9"
+```
+
+#### Package Manager Conflicts
+- **APT (Debian/Ubuntu)**: Conflicts with existing packages, dependency versions
+- **RPM (RHEL/CentOS/Fedora)**: Different naming conventions, requires explicit dependencies
+- **Pacman (Arch)**: AUR package maintenance, user expectations for PKGBUILD standards
+- **Homebrew**: Formula maintenance, bottle building for pre-compiled binaries
+
+### Build Infrastructure Constraints
+
+#### GitHub Actions Limitations
+- **Runner Availability**: Limited self-hosted runners for macOS builds
+- **Build Time Limits**: 6-hour job timeout for complex builds
+- **Storage Limits**: Artifact storage and retention policies
+- **Concurrency Limits**: Parallel job execution restrictions
+- **Network Bandwidth**: Large binary upload/download constraints
+
+#### Resource Requirements
+- **Memory Usage**: Cross-compilation can be memory-intensive
+- **CPU Time**: Multi-architecture builds require significant compute
+- **Storage Space**: Build cache management across platforms
+- **Network I/O**: Dependency downloads and artifact uploads
+
+## User Experience Constraints
+
+### Installation Simplicity
+
+#### One-Command Installation Goals
+```bash
+# Ideal user experience
+curl -fsSL https://install.terraphim.ai | sh
+
+# Should handle automatically:
+# - Platform detection
+# - Architecture detection
+# - Package manager selection
+# - Dependency resolution
+# - Service configuration
+# - User setup
+```
+
+#### Package Manager Integration
+- **Zero Configuration**: Default settings work out of the box
+- **Service Management**: Automatic systemd/launchd service setup
+- **User Permissions**: Appropriate file permissions and user groups
+- **Path Integration**: Proper PATH and environment setup
+- **Documentation**: Manual pages and help system integration
+
+### Update Reliability
+
+#### Auto-Updater Requirements
+- **Atomic Updates**: Never leave system in broken state
+- **Rollback Support**: Ability to revert to previous version
+- **Configuration Preservation**: User settings survive updates
+- **Service Continuity**: Minimal downtime during updates
+- **Progress Indication**: Clear feedback during update process
+
+#### Update Failure Scenarios
+- **Network Interruption**: Handle partial downloads gracefully
+- **Disk Space**: Verify adequate space before update
+- **Permission Issues**: Handle permission denied scenarios
+- **Service Conflicts**: Manage running services during update
+- **Dependency Conflicts**: Resolve version incompatibilities
+
+### Performance Expectations
+
+#### Binary Size Constraints
+| Component | Target Size | Current Size | Optimization Opportunities |
+|----------|-------------|--------------|---------------------------|
+| Server   | < 15MB      | 12.8MB       | Strip symbols, optimize build |
+| TUI      | < 8MB       | 7.2MB        | Reduce dependencies |
+| Desktop  | < 50MB      | 45.3MB       | Asset optimization |
+| Docker   | < 200MB     | 180MB        | Multi-stage builds |
+
+#### Startup Performance
+- **Server Cold Start**: < 3 seconds to ready state
+- **TUI Response**: < 500ms initial interface
+- **Desktop Launch**: < 2 seconds to usable state
+- **Container Startup**: < 5 seconds to service ready
+- **Memory Usage**: Server < 100MB baseline, Desktop < 200MB
+
+## Security Constraints
+
+### Code Signing and Verification
+
+#### Platform-Specific Requirements
+- **macOS**: Apple Developer certificate, notarization required
+- **Windows**: Authenticode certificate, SmartScreen compatibility
+- **Linux**: GPG signatures for packages, repository trust
+- **Docker**: Content trust, image signing support
+
+#### Certificate Management
+- **Certificate Renewal**: Automated renewal before expiration
+- **Key Rotation**: Secure private key management practices
+- **Trust Chain**: Maintain valid certificate chains
+- **Revocation Handling**: Respond to certificate compromises
+
+### Security Validation Requirements
+
+#### Vulnerability Scanning
+- **Dependency Scanning**: Automated scanning of all dependencies
+- **Container Scanning**: Docker image vulnerability assessment
+- **Static Analysis**: Code security analysis tools integration
+- **Dynamic Analysis**: Runtime security testing
+
+#### Integrity Verification
+- **Checksum Validation**: SHA256 for all release artifacts
+- **GPG Signatures**: Cryptographic verification of releases
+- **Blockchain Integration**: Immutable release records (future)
+- **Reproducible Builds**: Verifiable build process
+
+## Performance Constraints
+
+### Build Performance
+
+#### Parallelization Limits
+- **Matrix Strategy**: Optimal parallel job distribution
+- **Dependency Caching**: Effective build cache utilization
+- **Artifact Distribution**: Efficient artifact sharing between jobs
+- **Resource Allocation**: Balanced resource usage across jobs
+
+#### Build Time Targets
+| Component | Current Time | Target Time | Optimization Strategy |
+|-----------|--------------|-------------|----------------------|
+| Server Binary | 8 min | 5 min | Better caching |
+| Desktop App | 15 min | 10 min | Parallel builds |
+| Docker Image | 12 min | 8 min | Layer optimization |
+| Full Release | 45 min | 30 min | Pipeline optimization |
+
+### Runtime Performance
+
+#### Resource Utilization
+- **CPU Usage**: Efficient multi-core utilization
+- **Memory Management**: Minimal memory footprint
+- **I/O Performance**: Optimized file operations
+- **Network Efficiency**: Minimal bandwidth usage
+
+#### Scalability Constraints
+- **Concurrent Users**: Support for multiple simultaneous connections
+- **Data Volume**: Handle growing index sizes efficiently
+- **Search Performance**: Sub-second response times
+- **Update Frequency**: Efficient incremental updates
+
+## Compliance and Legal Constraints
+
+### Open Source Compliance
+
+#### License Requirements
+- **MIT/Apache 2.0**: Dual license compatibility
+- **Third-Party Licenses**: SPDX compliance for all dependencies
+- **Attribution**: Proper license notices and acknowledgments
+- **Source Availability**: Corresponding source code availability
+
+#### Export Controls
+- **Cryptography**: Export control compliance for encryption features
+- **Country Restrictions**: Geographical distribution limitations
+- **Entity List Screening**: Restricted party screening processes
+
+### Privacy and Data Protection
+
+#### Data Handling Requirements
+- **User Data**: Minimal data collection and processing
+- **Local Storage**: No unnecessary data transmission
+- **Data Retention**: Appropriate data lifecycle management
+- **User Consent**: Clear privacy policies and consent mechanisms
+
+## Operational Constraints
+
+### Monitoring and Observability
+
+#### Release Monitoring
+- **Download Metrics**: Track installation and update success rates
+- **Error Reporting**: Automated error collection and analysis
+- **Performance Metrics**: Real-time performance monitoring
+- **User Feedback**: In-app feedback collection mechanisms
+
+#### Support Infrastructure
+- **Documentation**: Comprehensive installation and troubleshooting guides
+- **Community Support**: Issue tracking and response processes
+- **Knowledge Base**: Self-service support resources
+- **Escalation Process**: Clear support escalation procedures
+
+### Maintenance Constraints
+
+#### Long-Term Support
+- **Version Support**: Multi-version support strategy
+- **Security Updates**: Backport security fixes to older versions
+- **Deprecation Policy**: Clear component deprecation timelines
+- **Migration Paths**: Smooth upgrade paths between versions
+
+This constraints analysis provides the foundation for understanding the boundaries and requirements that the release validation system must operate within. Each constraint represents a potential failure point that must be monitored and validated during the release process.