aiox-core 5.0.0

package/docs/uninstallation.md

@@ -0,0 +1,550 @@
+# Uninstallation Guide
+
+> 🌐 **EN** | [PT](./pt/uninstallation.md) | [ES](./es/uninstallation.md)
+
+---
+
+This guide provides comprehensive instructions for uninstalling Synkra AIOX from your system.
+
+## Table of Contents
+
+1. [Before You Uninstall](#before-you-uninstall)
+2. [Quick Uninstall](#quick-uninstall)
+3. [Complete Uninstall](#complete-uninstall)
+4. [Selective Uninstall](#selective-uninstall)
+5. [Data Preservation](#data-preservation)
+6. [Clean System Removal](#clean-system-removal)
+7. [Troubleshooting Uninstall](#troubleshooting-uninstall)
+8. [Post-Uninstall Cleanup](#post-uninstall-cleanup)
+9. [Reinstallation](#reinstallation)
+
+## Before You Uninstall
+
+### Important Considerations
+
+⚠️ **Warning**: Uninstalling Synkra AIOX will:
+
+- Remove all framework files
+- Delete agent configurations (unless preserved)
+- Clear memory layer data (unless backed up)
+- Remove all custom workflows
+- Delete logs and temporary files
+
+### Pre-Uninstall Checklist
+
+- [ ] Backup important data
+- [ ] Export custom agents and workflows
+- [ ] Save API keys and configurations
+- [ ] Document custom modifications
+- [ ] Stop all running processes
+- [ ] Inform team members
+
+### Backup Your Data
+
+```bash
+# Create complete backup
+npx aiox-core backup --complete
+
+# Or manually backup important directories
+tar -czf aiox-backup-$(date +%Y%m%d).tar.gz \
+  .aiox/ \
+  agents/ \
+  workflows/ \
+  tasks/ \
+  --exclude=.aiox/logs \
+  --exclude=.aiox/cache
+```
+
+## Quick Uninstall
+
+### Using Built-in Uninstaller
+
+The fastest way to uninstall Synkra AIOX:
+
+```bash
+# Basic uninstall (preserves user data)
+npx aiox-core uninstall
+
+# Complete uninstall (removes everything)
+npx aiox-core uninstall --complete
+
+# Uninstall with data preservation
+npx aiox-core uninstall --keep-data
+```
+
+### Interactive Uninstall
+
+For guided uninstallation:
+
+```bash
+npx aiox-core uninstall --interactive
+```
+
+This will prompt you for:
+
+- What to keep/remove
+- Backup options
+- Confirmation for each step
+
+## Complete Uninstall
+
+### Step 1: Stop All Services
+
+```bash
+# Stop all running agents
+*deactivate --all
+
+# Stop all workflows
+*stop-workflow --all
+
+# Shutdown meta-agent
+*shutdown
+```
+
+### Step 2: Export Important Data
+
+```bash
+# Export configurations
+*export config --destination backup/config.json
+
+# Export agents
+*export agents --destination backup/agents/
+
+# Export workflows
+*export workflows --destination backup/workflows/
+
+# Export memory data
+*export memory --destination backup/memory.zip
+```
+
+### Step 3: Run Uninstaller
+
+```bash
+# Complete removal
+npx aiox-core uninstall --complete --no-backup
+```
+
+### Step 4: Remove Global Installation
+
+```bash
+# Remove global npm package
+npm uninstall -g aiox-core
+
+# Remove npx cache
+npm cache clean --force
+```
+
+### Step 5: Clean System Files
+
+#### Windows
+
+```powershell
+# Remove AppData files
+Remove-Item -Recurse -Force "$env:APPDATA\aiox-core"
+
+# Remove temp files
+Remove-Item -Recurse -Force "$env:TEMP\aiox-*"
+
+# Remove registry entries (if any)
+Remove-Item -Path "HKCU:\Software\Synkra AIOX" -Recurse
+```
+
+#### macOS/Linux
+
+```bash
+# Remove config files
+rm -rf ~/.aiox
+rm -rf ~/.config/aiox-core
+
+# Remove cache
+rm -rf ~/.cache/aiox-core
+
+# Remove temp files
+rm -rf /tmp/aiox-*
+```
+
+## Selective Uninstall
+
+### Remove Specific Components
+
+```bash
+# Remove only agents
+npx aiox-core uninstall agents
+
+# Remove only workflows
+npx aiox-core uninstall workflows
+
+# Remove memory layer
+npx aiox-core uninstall memory-layer
+
+# Remove specific agent
+*uninstall agent-name
+```
+
+### Keep Core, Remove Extensions
+
+```bash
+# Remove all plugins
+*plugin remove --all
+
+# Remove Squads
+rm -rf Squads/
+
+# Remove custom templates
+rm -rf templates/custom/
+```
+
+## Data Preservation
+
+### What to Keep
+
+Before uninstalling, identify what you want to preserve:
+
+1. **Custom Agents**
+
+   ```bash
+   # Copy custom agents
+   cp -r agents/custom/ ~/aiox-backup/agents/
+   ```
+
+2. **Workflows and Tasks**
+
+   ```bash
+   # Copy workflows
+   cp -r workflows/ ~/aiox-backup/workflows/
+   cp -r tasks/ ~/aiox-backup/tasks/
+   ```
+
+3. **Memory Data**
+
+   ```bash
+   # Export memory database
+   *memory export --format sqlite \
+     --destination ~/aiox-backup/memory.db
+   ```
+
+4. **Configurations**
+
+   ```bash
+   # Copy all config files
+   cp .aiox/config.json ~/aiox-backup/
+   cp .env ~/aiox-backup/
+   ```
+
+5. **Custom Code**
+   ```bash
+   # Find and backup custom files
+   find . -name "*.custom.*" -exec cp {} ~/aiox-backup/custom/ \;
+   ```
+
+### Preservation Script
+
+Create `preserve-data.sh`:
+
+```bash
+#!/bin/bash
+BACKUP_DIR="$HOME/aiox-backup-$(date +%Y%m%d-%H%M%S)"
+
+echo "Creating backup directory: $BACKUP_DIR"
+mkdir -p "$BACKUP_DIR"
+
+# Backup function
+backup_if_exists() {
+    if [ -e "$1" ]; then
+        echo "Backing up $1..."
+        cp -r "$1" "$BACKUP_DIR/"
+    fi
+}
+
+# Backup all important data
+backup_if_exists ".aiox"
+backup_if_exists "agents"
+backup_if_exists "workflows"
+backup_if_exists "tasks"
+backup_if_exists "templates"
+backup_if_exists ".env"
+backup_if_exists "package.json"
+
+echo "Backup completed at: $BACKUP_DIR"
+```
+
+## Clean System Removal
+
+### Complete Cleanup Script
+
+Create `clean-uninstall.sh`:
+
+```bash
+#!/bin/bash
+echo "Synkra AIOX Complete Uninstall"
+echo "================================="
+
+# Confirmation
+read -p "This will remove ALL Synkra AIOX data. Continue? (y/N) " -n 1 -r
+echo
+if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+    exit 1
+fi
+
+# Stop all processes
+echo "Stopping all processes..."
+pkill -f "aiox-core" || true
+pkill -f "aiox-developer" || true
+
+# Remove project files
+echo "Removing project files..."
+rm -rf .aiox/
+rm -rf agents/
+rm -rf workflows/
+rm -rf tasks/
+rm -rf templates/
+rm -rf Squads/
+rm -rf node_modules/aiox-core/
+
+# Remove global files
+echo "Removing global files..."
+npm uninstall -g aiox-core
+
+# Remove user data
+echo "Removing user data..."
+rm -rf ~/.aiox
+rm -rf ~/.config/aiox-core
+rm -rf ~/.cache/aiox-core
+
+# Clean npm cache
+echo "Cleaning npm cache..."
+npm cache clean --force
+
+# Remove from package.json
+echo "Updating package.json..."
+npm uninstall aiox-core/core
+npm uninstall aiox-core/memory
+npm uninstall aiox-core/meta-agent
+
+echo "Uninstall complete!"
+```
+
+### Registry Cleanup (Windows)
+
+```powershell
+# PowerShell script for Windows cleanup
+Write-Host "Cleaning Synkra AIOX from Windows Registry..."
+
+# Remove from PATH
+$path = [Environment]::GetEnvironmentVariable("PATH", "User")
+$newPath = ($path.Split(';') | Where-Object { $_ -notmatch 'aiox-core' }) -join ';'
+[Environment]::SetEnvironmentVariable("PATH", $newPath, "User")
+
+# Remove registry keys
+Remove-ItemProperty -Path "HKCU:\Environment" -Name "AIOX_*" -ErrorAction SilentlyContinue
+
+# Remove file associations
+Remove-Item -Path "HKCU:\Software\Classes\.aiox" -Recurse -ErrorAction SilentlyContinue
+
+Write-Host "Registry cleanup complete!"
+```
+
+## Troubleshooting Uninstall
+
+### Common Issues
+
+#### 1. Permission Denied
+
+```bash
+# Linux/macOS
+sudo npx aiox-core uninstall --complete
+
+# Windows (Run as Administrator)
+npx aiox-core uninstall --complete
+```
+
+#### 2. Process Still Running
+
+```bash
+# Force stop all processes
+# Linux/macOS
+killall -9 node
+killall -9 aiox-core
+
+# Windows
+taskkill /F /IM node.exe
+taskkill /F /IM aiox-core.exe
+```
+
+#### 3. Files Locked
+
+```bash
+# Find processes using files
+# Linux/macOS
+lsof | grep aiox
+
+# Windows (PowerShell)
+Get-Process | Where-Object {$_.Path -like "*aiox*"}
+```
+
+#### 4. Incomplete Removal
+
+```bash
+# Manual cleanup
+find . -name "*aiox*" -type d -exec rm -rf {} +
+find . -name "*.aiox*" -type f -delete
+```
+
+### Force Uninstall
+
+If normal uninstall fails:
+
+```bash
+#!/bin/bash
+# force-uninstall.sh
+echo "Force uninstalling Synkra AIOX..."
+
+# Kill all related processes
+pkill -9 -f aiox || true
+
+# Remove all files
+rm -rf .aiox* aiox* *aiox*
+rm -rf agents workflows tasks templates
+rm -rf node_modules/aiox-core
+rm -rf ~/.aiox* ~/.config/aiox* ~/.cache/aiox*
+
+# Clean npm
+npm cache clean --force
+npm uninstall -g aiox-core
+
+echo "Force uninstall complete!"
+```
+
+## Post-Uninstall Cleanup
+
+### 1. Verify Removal
+
+```bash
+# Check for remaining files
+find . -name "*aiox*" 2>/dev/null
+find ~ -name "*aiox*" 2>/dev/null
+
+# Check npm packages
+npm list -g | grep aiox
+npm list | grep aiox
+
+# Check running processes
+ps aux | grep aiox
+```
+
+### 2. Clean Environment Variables
+
+```bash
+# Remove from .bashrc/.zshrc
+sed -i '/AIOX_/d' ~/.bashrc
+sed -i '/aiox-core/d' ~/.bashrc
+
+# Remove from .env files
+find . -name ".env*" -exec sed -i '/AIOX_/d' {} \;
+```
+
+### 3. Update Project Files
+
+```javascript
+// Remove from package.json scripts
+{
+  "scripts": {
+    // Remove these entries
+    "aiox": "aiox-core",
+    "meta-agent": "aiox-core meta-agent"
+  }
+}
+```
+
+### 4. Clean Git Repository
+
+```bash
+# Remove AIOX-specific git hooks
+rm -f .git/hooks/*aiox*
+
+# Update .gitignore
+sed -i '/.aiox/d' .gitignore
+sed -i '/aiox-/d' .gitignore
+
+# Commit removal
+git add -A
+git commit -m "Remove Synkra AIOX"
+```
+
+## Reinstallation
+
+### After Complete Uninstall
+
+If you want to reinstall Synkra AIOX:
+
+1. **Wait for cleanup**
+
+   ```bash
+   # Ensure all processes stopped
+   sleep 5
+   ```
+
+2. **Clear npm cache**
+
+   ```bash
+   npm cache clean --force
+   ```
+
+3. **Fresh installation**
+   ```bash
+   npx aiox-core@latest init my-project
+   ```
+
+### Restoring from Backup
+
+```bash
+# Restore saved data
+cd my-project
+
+# Restore configurations
+cp ~/aiox-backup/config.json .aiox/
+
+# Restore agents
+cp -r ~/aiox-backup/agents/* ./agents/
+
+# Import memory
+*memory import ~/aiox-backup/memory.zip
+
+# Verify restoration
+*doctor --verify-restore
+```
+
+## Uninstall Verification Checklist
+
+- [ ] All AIOX processes stopped
+- [ ] Project files removed
+- [ ] Global npm package uninstalled
+- [ ] User configuration files deleted
+- [ ] Cache directories cleaned
+- [ ] Environment variables removed
+- [ ] Registry entries cleaned (Windows)
+- [ ] Git repository updated
+- [ ] No remaining AIOX files found
+- [ ] System PATH updated
+
+## Getting Help
+
+If you encounter issues during uninstallation:
+
+1. **Check Documentation**
+   - [FAQ](https://github.com/SynkraAI/aiox-core/wiki/faq#uninstall)
+   - [Troubleshooting](https://github.com/SynkraAI/aiox-core/wiki/troubleshooting)
+
+2. **Community Support**
+   - Discord: #uninstall-help
+   - GitHub Issues: Label with "uninstall"
+
+3. **Emergency Support**
+   ```bash
+   # Generate uninstall report
+   npx aiox-core diagnose --uninstall > uninstall-report.log
+   ```
+
+---
+
+**Remember**: Always backup your data before uninstalling. The uninstall process is irreversible, and data recovery may not be possible without proper backups.

package/docs/versioning-and-releases.md

@@ -0,0 +1,140 @@
+# How to Release a New Version
+
+> 🌐 **EN** | [PT](./pt/versioning-and-releases.md) | [ES](./es/versioning-and-releases.md)
+
+---
+
+## Automated Releases (Recommended)
+
+The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push and everything else happens automatically.
+
+### Commit Message Format
+
+Use these prefixes to control what type of release happens:
+
+```bash
+fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
+feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
+feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
+```
+
+### What Happens Automatically
+
+When you push commits with `fix:` or `feat:`, GitHub Actions will:
+
+1. ✅ Analyze your commit messages
+2. ✅ Bump version in `package.json`
+3. ✅ Generate changelog
+4. ✅ Create git tag
+5. ✅ **Publish to NPM automatically**
+6. ✅ Create GitHub release with notes
+
+### Your Simple Workflow
+
+```bash
+# Make your changes
+git add .
+git commit -m "feat: add team collaboration mode"
+git push
+
+# That's it! Release happens automatically 🎉
+# Users can now run: npx aiox-core (and get the new version)
+```
+
+### Commits That DON'T Trigger Releases
+
+These commit types won't create releases (use them for maintenance):
+
+```bash
+chore: update dependencies     # No release
+docs: fix typo in readme      # No release
+style: format code            # No release
+test: add unit tests          # No release
+```
+
+### Test Your Setup
+
+```bash
+npm run release:test    # Safe to run locally - tests the config
+```
+
+---
+
+## Manual Release Methods (Exceptions Only)
+
+⚠️ Only use these methods if you need to bypass the automatic system
+
+### Quick Manual Version Bump
+
+```bash
+npm run version:patch   # 4.1.0 → 4.1.1 (bug fixes)
+npm run version:minor   # 4.1.0 → 4.2.0 (new features)
+npm run version:major   # 4.1.0 → 5.0.0 (breaking changes)
+
+# Then manually publish:
+npm publish
+git push && git push --tags
+```
+
+### Manual GitHub Actions Trigger
+
+You can also trigger releases manually through GitHub Actions workflow dispatch if needed.
+
+---
+
+## Troubleshooting
+
+### Release Not Triggered
+
+If your merge to `main` didn't trigger a release:
+
+1. **Check commit messages** - Only `fix:` and `feat:` prefixes trigger releases
+2. **Verify CI passed** - Release only runs if lint, typecheck, and test pass
+3. **Check workflow logs** - Go to Actions → Semantic Release to see details
+
+### Release Failed
+
+Common issues and solutions:
+
+| Error | Solution |
+|-------|----------|
+| `ENOGHTOKEN` | GITHUB_TOKEN secret missing or expired |
+| `ENOPKGAUTH` | NPM_TOKEN secret missing or invalid |
+| `ENOTINHISTORY` | Branch doesn't have proper history (use `fetch-depth: 0`) |
+| `EINVALIDNPMTOKEN` | Regenerate NPM token with publish permissions |
+
+### Skip a Release
+
+To merge without triggering a release, use one of these:
+
+```bash
+# Method 1: Use non-release prefix
+git commit -m "chore: update dependencies"
+
+# Method 2: Add [skip ci] to commit message
+git commit -m "feat: new feature [skip ci]"
+```
+
+### Force a Manual Release
+
+If automatic release fails, you can manually release:
+
+```bash
+npm run version:patch   # or minor/major
+git push && git push --tags
+npm publish
+```
+
+---
+
+## Configuration Files
+
+| File | Purpose |
+|------|---------|
+| `.releaserc.json` | Semantic release configuration |
+| `.github/workflows/semantic-release.yml` | GitHub Actions workflow |
+| `package.json` | Version source, npm scripts |
+
+---
+
+*Last updated: Story 6.17 - Semantic Release Automation*