From 9e1bdd4a31dc8b758d3ccc9b500276b93e0ea6b0 Mon Sep 17 00:00:00 2001
From: Sander Declerck <sander@sdsoftware.be>
Date: Tue, 2 Dec 2025 11:57:23 +0100
Subject: [PATCH] Update docs: migration guide

---
 README.md                       |  8 ++-
 docs/npm-to-binary-migration.md | 89 +++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+), 1 deletion(-)
 create mode 100644 docs/npm-to-binary-migration.md

diff --git a/README.md b/README.md
index de5be05..6e5470c 100644
--- a/README.md
+++ b/README.md
@@ -24,7 +24,9 @@ Aikido Safe Chain works on Node.js version 16 and above and supports the followi
 
 ## Installation
 
-Installing the Aikido Safe Chain is easy with our one-line installer:
+Installing the Aikido Safe Chain is easy with our one-line installer.
+
+> ⚠️ **Already installed via npm?** See the [migration guide](docs/npm-to-binary-migration.md) to switch to the binary version.
 
 ### Unix/Linux/macOS
 
@@ -186,11 +188,13 @@ Use the `--ci` flag to automatically configure Aikido Safe Chain for CI/CD envir
 ### Unix/Linux/macOS (GitHub Actions, Azure Pipelines, etc.)
 
 **JavaScript only:**
+
 ```shell
 curl -fsSL https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-scripts/install-safe-chain.sh | sh -s -- --ci
 ```
 
 **With Python support:**
+
 ```shell
 curl -fsSL https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-scripts/install-safe-chain.sh | sh -s -- --ci --include-python
 ```
@@ -198,11 +202,13 @@ curl -fsSL https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-s
 ### Windows (Azure Pipelines, etc.)
 
 **JavaScript only:**
+
 ```powershell
 iex "& { $(iwr 'https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-scripts/install-safe-chain.ps1' -UseBasicParsing) } -ci"
 ```
 
 **With Python support:**
+
 ```powershell
 iex "& { $(iwr 'https://raw.githubusercontent.com/AikidoSec/safe-chain/main/install-scripts/install-safe-chain.ps1' -UseBasicParsing) } -ci -includepython"
 ```
diff --git a/docs/npm-to-binary-migration.md b/docs/npm-to-binary-migration.md
new file mode 100644
index 0000000..c0b8f9a
--- /dev/null
+++ b/docs/npm-to-binary-migration.md
@@ -0,0 +1,89 @@
+# Migrating from npm global tool to binary installation
+
+If you previously installed safe-chain as an npm global package, you need to migrate to the binary installation.
+
+Depending on the version manager you're using, the uninstall process differs:
+
+### Standard npm (no version manager)
+
+1. **Clean up shell aliases:**
+
+   ```bash
+   safe-chain teardown
+   ```
+
+2. **Restart your terminal**
+
+3. **Uninstall the npm package:**
+
+   ```bash
+   npm uninstall -g @aikidosec/safe-chain
+   ```
+
+4. **Install the binary version** (see [Installation](../README.md#installation))
+
+### nvm (Node Version Manager)
+
+**Important:** nvm installs global packages separately for each Node version, so safe-chain must be uninstalled from each version where it was installed.
+
+1. **Clean up shell aliases:**
+
+   ```bash
+   safe-chain teardown
+   ```
+
+2. **Restart your terminal**
+
+3. **Uninstall from all Node versions:**
+
+   **Option A** - Automated script (recommended):
+
+   ```bash
+   for version in $(nvm list | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+'); do nvm use $version && npm uninstall -g @aikidosec/safe-chain; done
+   ```
+
+   **Option B** - Manual per version:
+
+   ```bash
+   nvm use <version>
+   npm uninstall -g @aikidosec/safe-chain
+   ```
+
+   Repeat for each Node version where safe-chain was installed.
+
+4. **Install the binary version** (see [Installation](../README.md#installation))
+
+### Volta
+
+1. **Clean up shell aliases:**
+
+   ```bash
+   safe-chain teardown
+   ```
+
+2. **Restart your terminal**
+
+3. **Uninstall the Volta package:**
+
+   ```bash
+   volta uninstall @aikidosec/safe-chain
+   ```
+
+4. **Install the binary version** (see [Installation](../README.md#installation))
+
+## Troubleshooting
+
+### Shell aliases still present after migration
+
+1. Run `safe-chain teardown` (if the binary is installed)
+2. Manually remove any safe-chain entries from your shell config files:
+   - Bash: `~/.bashrc`
+   - Zsh: `~/.zshrc`
+   - Fish: `~/.config/fish/config.fish`
+   - PowerShell: `$PROFILE`
+3. Restart your terminal
+4. Re-run the install script
+
+### "command not found: safe-chain" after migration
+
+The binary installation directory (`~/.safe-chain/bin`) may not be in your PATH. Restart your terminal. If the problem persists: re-run the installation of safe-chain.