docs(release): update installer migration docs

CHANGELOG.md

@@ -26,6 +26,7 @@ Installer migration improvements.
 ### Changed
 
 - Improve managed-install errors with explicit uninstall-and-reinstall guidance so users can switch to the standalone installer without relying on side-by-side PATH shadowing.
+- Update website install and troubleshooting docs with npm-to-standalone migration steps and clearer PATH shadowing guidance.
 
 ## [0.2.4] - 2026-06-01
 

docs/install.md

@@ -192,7 +192,7 @@ Both `install.sh` and `install.ps1` use the same stable exit-code contract for s
 | 4    | unsupported platform / architecture                                                                                            |
 | 5    | network or download failure                                                                                                    |
 | 6    | checksum verification failed                                                                                                   |
-| 7    | install or permission failure (non-writable dir, sudo, or refused to overwrite a managed install without `--force` / `-Force`) |
+| 7    | install or permission failure (non-writable dir, sudo, or refused to overwrite a managed install)                              |
 | 8    | post-install verification failed                                                                                               |
 
 ### Idempotent re-runs
@@ -201,7 +201,7 @@ Both installers short-circuit with exit `0` when the target install path already
 
 ### Managed-install detection
 
-Both installers refuse to overwrite an `agora` binary that came from a package manager and exit `7` with a recommended upgrade command. Override with `--force` / `-Force`.
+Both installers refuse to overwrite an `agora` binary that came from a package manager and exit `7` with a recommended upgrade command. Uninstall the package-manager version before switching to the standalone installer. For global npm installs on Unix shells, `--replace-npm` can run `npm uninstall -g agoraio-cli` before installing the standalone binary. Use `--force` / `-Force` only for intentional side-by-side installs.
 
 | Manager                | Detected by                                                  | Recommended upgrade         |
 | ---------------------- | ------------------------------------------------------------ | --------------------------- |

docs/troubleshooting.md

@@ -65,6 +65,23 @@ where.exe agora    # Windows PowerShell
 Reorder `PATH` so the installer's directory comes first, or remove the
 older binary.
 
+If the older binary came from a global npm install and you want to switch
+to the standalone installer, either migrate in one installer run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --replace-npm
+```
+
+Or uninstall npm first and then run the standalone installer:
+
+```bash
+npm uninstall -g agoraio-cli
+curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh
+```
+
+Use `--force` only when you intentionally want two installs and understand
+that the first `agora` on `PATH` wins.
+
 ## `agora init` or `agora quickstart create` fails on `git clone`
 
 The CLI shells out to `git clone` for quickstarts. Most failures map to a stable error code: