diff --git a/README.md b/README.md
index 84fd6c65..054a20b0 100644
--- a/README.md
+++ b/README.md
@@ -30,13 +30,26 @@ OpenJarvis is that stack. It is an opinionated framework for local-first persona
 
 ## Installation
 
+### Prerequisites
+
+| Tool | Install |
+|------|---------|
+| **Python 3.10+** | [python.org](https://www.python.org/downloads/) |
+| **uv** (Python package manager) | `curl -LsSf https://astral.sh/uv/install.sh \| sh` — or `brew install uv` on macOS |
+| **Rust** | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
+| **Git** | [git-scm.com](https://git-scm.com/) — or `brew install git` on macOS |
+
+> **macOS users:** see the full [macOS Installation Guide](https://open-jarvis.github.io/OpenJarvis/getting-started/macos/) for a step-by-step walkthrough including Homebrew setup.
+
+### Setup
+
 ```bash
 git clone https://github.com/open-jarvis/OpenJarvis.git
 cd OpenJarvis
 uv sync                           # core framework
 uv sync --extra server             # + FastAPI server
 
-# Build the Rust extension (requires Rust: https://rustup.rs/)
+# Build the Rust extension
 uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml
 ```
 
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 20598dd7..3dd1f794 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -236,11 +236,18 @@ See the [Python SDK guide](../user-guide/python-sdk.md) for the full API referen
 
 ## Requirements
 
-| Requirement | Version | Notes |
-|-------------|---------|-------|
-| Python | 3.10+ | Required |
-| Inference backend | Any | At least one of Ollama, vLLM, llama.cpp, SGLang, or a cloud API |
-| Node.js | 18+ | Required for the browser UI; 22+ for the WhatsApp Baileys channel bridge |
+| Requirement | Version | Install | Notes |
+|-------------|---------|---------|-------|
+| Python | 3.10+ | [python.org](https://www.python.org/downloads/) | Required |
+| uv | latest | `curl -LsSf https://astral.sh/uv/install.sh \| sh` or `brew install uv` (macOS) | Python package & project manager |
+| Git | any | [git-scm.com](https://git-scm.com/) or `brew install git` (macOS) | Required |
+| Rust | stable | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` | Required for the Rust extension |
+| Inference backend | any | See [below](#setting-up-an-inference-backend) | At least one of Ollama, vLLM, llama.cpp, SGLang, or a cloud API |
+| Node.js | 18+ | [nodejs.org](https://nodejs.org/) or `brew install node` (macOS) | Required for the browser UI; 22+ for the WhatsApp Baileys channel bridge |
+
+!!! tip "macOS users"
+    See the [macOS Installation Guide](macos.md) for a complete step-by-step walkthrough
+    covering Homebrew, uv, Rust, llama.cpp, and common pitfalls.
 
 ## Optional Extras