Upgrade Strategy

Updates without tears. Keep your customizations while getting the latest features.

Upgrade Strategies

Loaded Vibes offers three upgrade strategies, each suited to different needs. Choose based on how much you've customized the framework.

Mirror

Clean slate. Replace all framework files with the new version.

Best for: Minimal customization

Merge

Smart merge. Preserve customizations, apply non-conflicting updates.

Best for: Moderate customization

Sandbox

Test first. Apply updates to a copy, validate, then promote.

Best for: Heavy customization

Mirror Strategy

The mirror strategy replaces all framework files with the new version. Your customizations in separate files are preserved.

# Check what will change
lv upgrade --strategy mirror --dry-run

# Apply mirror upgrade
lv upgrade --strategy mirror

# What happens:
# 1. Backup current state
# 2. Replace all @framework files
# 3. Preserve files you created
# 4. Run validation

⚠️

Destructive

Mirror will overwrite any changes you made to framework files. Use only if you haven't modified core framework assets.

When to Use

Fresh installation with minimal customization
You only add new artifacts, never modify existing ones
You want the cleanest possible upgrade path

Merge Strategy

The merge strategy attempts to preserve your changes while applying non-conflicting updates. It uses a 3-way merge algorithm.

# Check for conflicts
lv upgrade --strategy merge --dry-run

# Apply merge upgrade
lv upgrade --strategy merge

# What happens:
# 1. Backup current state
# 2. Analyze differences
# 3. Apply non-conflicting changes
# 4. Mark conflicts for manual resolution
# 5. Run validation

Handling Conflicts

# After merge with conflicts
lv upgrade status

# Output:
# Upgrade Status: Conflicts detected
# 
# Files with conflicts:
# - .github/instructions/nextjs.instructions.md
# - .github/toolsets/default.toolset.jsonc
#
# Run: lv upgrade resolve

# Resolve conflicts interactively
lv upgrade resolve

# Or resolve manually and mark done
lv upgrade resolve --manual

Conflict Resolution

Conflicts are marked with standard conflict markers:

Conflict markerstext

<<<<<<< YOURS
Your customized content here
=======
New framework content here
>>>>>>> THEIRS

When to Use

You've customized framework files but want updates
You're comfortable resolving merge conflicts
You want to review each change before applying

Sandbox Strategy

The sandbox strategy applies updates to a copy, letting you test before committing to the upgrade.

# Create sandbox with upgrade
lv upgrade --strategy sandbox

# What happens:
# 1. Create .loaded-vibes/sandbox/
# 2. Apply upgrade to sandbox
# 3. Keep production unchanged

# Test in sandbox
cd .loaded-vibes/sandbox
lv doctor
lv devcycle run validate

# If satisfied, promote to production
lv upgrade promote

# Or discard and try again
lv upgrade discard

Sandbox Testing

# Run tests in sandbox
lv upgrade sandbox test

# Compare behavior
lv upgrade sandbox compare

# Output:
# Comparing sandbox vs production:
# 
# ✓ DevCycle: init - identical behavior
# ✓ DevCycle: scaffold - identical behavior
# ! DevCycle: deploy - new checkpoint required
# 
# 2 changes detected. Review before promoting.

When to Use

Heavy customization that might break with updates
Production project where you can't risk downtime
You want to thoroughly test before upgrading

Backup & Restore

Automatic Backups

By default, upgrades create automatic backups:

# Backups are stored in
.loaded-vibes/backups/
├── 2024-01-15-pre-upgrade/
├── 2024-01-10-pre-upgrade/
└── 2024-01-05-pre-upgrade/

# List backups
lv restore --list

# Restore from backup
lv restore backup 2024-01-15-pre-upgrade

Manual Backup

# Create manual backup
lv backup create --name "before-major-upgrade"

# Export for external storage
lv backup export --output backup.tar.gz

# Import backup
lv backup import backup.tar.gz

Version Pinning

Pin to a specific version to prevent automatic updates:

loaded-vibes.config.jsonjson

{
  "version": "1.2.3",
  "features": {
    "upgrades": {
      "strategy": "merge",
      "autoCheck": true,
      "autoUpgrade": false,
      "pinnedVersion": "1.2.x"
    }
  }
}

Upgrade Checklist

Before Upgrading

Review release notes for breaking changes
Run lv doctor to ensure healthy state
Commit all local changes
Create manual backup if important
Run lv upgrade --dry-run to preview

After Upgrading

Run lv doctor to verify health
Run lv artifact validate to check artifacts
Test critical DevCycles
Review any deprecation warnings
Update custom artifacts if needed

Rollback

If an upgrade goes wrong:

# Quick rollback to pre-upgrade state
lv rollback

# Rollback to specific backup
lv rollback --to 2024-01-15-pre-upgrade

# Rollback specific files only
lv rollback --files ".github/instructions/*"

✨

Safe rollback

Rollback preserves any new files you created after the upgrade. It only reverts framework files to their previous state.

Configuration Reference

loaded-vibes.config.jsonjson

{
  "features": {
    "upgrades": {
      "strategy": "merge",           // mirror, merge, sandbox
      "autoBackup": true,            // Create backup before upgrade
      "autoCheck": true,             // Check for updates periodically
      "autoUpgrade": false,          // Apply updates automatically
      "checkFrequency": "weekly",    // never, daily, weekly, monthly
      "pinnedVersion": null,         // Pin to version pattern (e.g., "1.x")
      "backupRetention": 5           // Number of backups to keep
    }
  }
}

Next Steps

Check out the troubleshooting guide for upgrade-related issues, or return to customization to learn how to structure your modifications for easy upgrades.