Docs/onboarding feedback mac (#290)

docs/getting-started/macos.md

@@ -22,6 +22,7 @@ elsewhere — and is suitable for both Apple Silicon and Intel Macs.
 
 | Tool | Purpose |
 |------|---------|
+| Xcode Command Line Tools | Apple's compiler toolchain — required by Homebrew, Rust, and `git` |
 | Homebrew | macOS package manager — installs everything else |
 | uv | Python version and dependency manager |
 | Git | Clones the OpenJarvis repo |
@@ -35,6 +36,27 @@ elsewhere — and is suitable for both Apple Silicon and Intel Macs.
 
 ## Step-by-Step Installation
 
+### Step 0 — Install Xcode Command Line Tools
+
+On a fresh Mac, you need Apple's developer command line tools before anything else
+(`git`, `cc`, build headers). Install them with:
+
+```bash
+xcode-select --install
+```
+
+A GUI installer will pop up — accept and let it finish. If the tools are already
+installed the command instead prints
+`xcode-select: error: command line tools are already installed, use "Software Update" to install updates`
+and exits non-zero, which is fine — you can move on.
+
+!!! note "Homebrew will ask too"
+    Step 1's Homebrew installer also requests the Command Line Tools if it doesn't see
+    them. Running `xcode-select --install` upfront avoids the second prompt and confirms
+    the tools landed correctly.
+
+---
+
 ### Step 1 — Install Homebrew
 
 Homebrew is the standard macOS package manager. Everything else in this guide is installed

docs/getting-started/quickstart.md

@@ -7,6 +7,11 @@ search:
 
 # Quick Start
 
+!!! tip "Running `jarvis` commands"
+    Every `jarvis ...` example below assumes you have either activated the project venv
+    (`source .venv/bin/activate`) or are prefixing each command with `uv run`. A bare
+    `jarvis init --preset ...` from a fresh clone will fail with `command not found`.
+
 ## What You Can Build
 
 OpenJarvis is a modular AI assistant framework. Here's what developers build with it:
@@ -30,6 +35,13 @@ OpenJarvis is a modular AI assistant framework. Here's what developers build wit
     jarvis ask "How do I configure the engine?"
     ```
 
+    !!! warning "Requires the Rust extension"
+        `jarvis memory index` and `jarvis memory search` import `openjarvis_rust`. If you
+        skipped the `uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml`
+        step in [Installation](installation.md), these commands fail with
+        `ModuleNotFoundError: No module named 'openjarvis_rust'`. Build the extension
+        once and any preset (including `deep-research`) will work.
+
 === "5-Line Python SDK"
 
     ```python