docs: update installation to use official Homebrew formulas and ensure consistent ordering (#343)

Co-authored-by: raymondk <raymond.khalife@dfinity.org>

Author: marc0olo

.claude/CLAUDE.md

@@ -222,6 +222,15 @@ Documentation follows the Diátaxis framework:
 - `docs/reference/` — Information-oriented technical specifications
 - `docs/migration/` — Migration guides (e.g., from dfx)
 
+### Installation Instructions
+
+- **npm is the recommended installation method** for quickstarts, tutorials, and READMEs
+- Only `docs/guides/installation.md` should list all installation options
+- Follow DRY: other docs should link to the installation guide rather than duplicating instructions
+- Consistent ordering: npm (in Quick Install), then Homebrew, then Shell Script (in Alternative Methods)
+- When referencing alternatives in other docs, maintain this order: "Homebrew, shell script, ..." (e.g., "See the Installation Guide for Homebrew, shell script, or other options")
+- Both `icp-cli` and `ic-wasm` are available as official Homebrew formulas: `brew install icp-cli` and `brew install ic-wasm`
+
 ### Paths
 
 All paths are UTF-8. `PathBuf` and `Path` are the types from `camino`.

README.md

@@ -16,7 +16,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
 npm install -g ic-mops && mops toolchain init
 ```
 
-> **Alternative methods:** See the [Installation Guide](docs/guides/installation.md) for shell script, Homebrew, Rust setup, or platform-specific instructions.
+> **Alternative methods:** See the [Installation Guide](docs/guides/installation.md) for Homebrew, shell script, Rust setup, or platform-specific instructions.
 
 Then follow the **[Quickstart](docs/quickstart.md)** to deploy your first canister in under 5 minutes.
 

docs/guides/installation.md

@@ -20,7 +20,7 @@ Set up everything you need to build and deploy canisters on the Internet Compute
 > sudo dnf install -y dbus-libs openssl ca-certificates
 > ```
 
-## Quick Install (Recommended)
+## Quick Install via npm (Recommended)
 
 **Required:** [Node.js](https://nodejs.org/) (LTS) — needed for npm and for building frontend canisters.
 
@@ -60,33 +60,23 @@ If you prefer not to use npm, or need platform-specific options, see the section
 
 ### icp-cli
 
-**Shell Script (macOS / Linux / WSL):**
+**Homebrew (macOS/Linux):**
 
 ```bash
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh
-```
-
-Restart your shell or follow the instructions shown by the installer.
-
-**Shell Script (Windows, for Rust-only mainnet projects):**
-
-```ps1
-powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex"
+brew install icp-cli
 ```
 
-Restart your terminal after installation.
-
-**Homebrew (macOS/Linux only):**
+**Shell Script (macOS/Linux/WSL):**
 
 ```bash
-brew install dfinity/tap/icp-cli
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.sh | sh
 ```
 
-To update later: `brew upgrade dfinity/tap/icp-cli`
-
-> **Note:** Homebrew installs ic-wasm as a dependency, so you can skip the ic-wasm installation below.
+**Shell Script (Windows):**
 
-> **Note:** [Node.js](https://nodejs.org/) (LTS recommended) is still required for the Motoko toolchain and frontend canisters when using alternative installation methods.
+```ps1
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/latest/download/icp-cli-installer.ps1 | iex"
+```
 
 ### ic-wasm
 
@@ -103,12 +93,10 @@ To update later: `brew upgrade dfinity/tap/icp-cli`
 
 **Installation:**
 
-> **Note:** If you installed icp-cli via Homebrew, ic-wasm is already included. Skip this section.
-
-**npm (recommended):**
+**Homebrew (macOS/Linux):**
 
 ```bash
-npm install -g @icp-sdk/ic-wasm
+brew install ic-wasm
 ```
 
 **Shell Script (macOS/Linux):**
@@ -130,10 +118,11 @@ Learn more: [ic-wasm repository](https://github.com/dfinity/ic-wasm)
 **Motoko:**
 
 ```bash
-npm install -g ic-mops
-mops toolchain init
+curl -fsSL cli.mops.one/install.sh | sh && mops toolchain init
 ```
 
+> **Note:** Requires [Node.js](https://nodejs.org/) and a package manager (npm, pnpm, or bun). The shell script installs the latest Mops version stored onchain on ICP.
+
 **Rust:**
 
 Install from [rustup.rs](https://rustup.rs/):

docs/quickstart.md

@@ -16,7 +16,7 @@ npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm
 npm install -g ic-mops && mops toolchain init
 ```
 
-> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, or other options.
+> **Alternative methods:** See the [Installation Guide](guides/installation.md) for Homebrew, shell script, or other options.
 
 ## Steps
 

docs/tutorial.md

@@ -33,7 +33,7 @@ This installs:
 - **ic-wasm** — optimizes WebAssembly for the Internet Computer
 - **mops** — Motoko package manager, which also installs the Motoko compiler
 
-> **Alternative methods:** See the [Installation Guide](guides/installation.md) for shell script, Homebrew, Rust setup, or other options.
+> **Alternative methods:** See the [Installation Guide](guides/installation.md) for Homebrew, shell script, Rust setup, or other options.
 
 Verify the tools are installed: