Doc: Add official guide for migrating user settings via backup and restore

[Utakata]

Overview

When users follow the procedure to resolve installation conflicts by reinstalling SuperClaude, they risk losing all their custom configurations, including critical MCP server settings. This is because the SuperClaude uninstall command cleans the entire ~/.claude/ directory.

To prevent data loss, we must document the official procedure for safely migrating settings using the built-in backup and restore commands.

Proposed Step-by-Step Procedure

The following guide should be added to the official documentation.

---

Step 1: Create a Settings Backup

Before uninstalling anything, the user must create a backup of their current settings. This command bundles the entire ~/.claude/ directory into a single backup file.

SuperClaude backup --create

---

Step 2: Uninstall and Reinstall

Next, to resolve conflicts, completely remove all existing SuperClaude installations.

# Example for pip installation
pip uninstall SuperClaude

# Example for npm installation
npm uninstall -g @bifrost_inc/superclaude

# Finally, clean up the framework directory itself
SuperClaude uninstall

After uninstallation, reinstall SuperClaude using a single, recommended method (e.g., pipx).

pipx install SuperClaude && SuperClaude install

This will create a clean environment with default settings.

---

Step 3: Restore Settings from Backup

Finally, restore the user's custom configurations from the backup file created in Step 1.

SuperClaude backup --restore [name_of_your_backup_file.tar.gz]

This command will restore the previous MCP server settings and other customizations to the new installation.

Process Flow Diagram

This diagram illustrates the safe migration path for user settings.

graph TD
    A[Start: User has conflicting installations] --> B["Step 1: Run `SuperClaude backup --create`"];
    B --> C["State: Settings are safely backed up"];
    C --> D["Step 2: Uninstall all versions & Reinstall cleanly"];
    D --> E["State: Clean install with default settings"];
    E --> F["Step 3: Run `SuperClaude backup --restore`"];
    F --> G["✅ Finish: Clean install with all previous settings restored"];

Loading

By documenting this process, we can provide a clear and safe path for users to maintain their environments.