Docs/onboarding feedback mac (#290)

README.md

@@ -64,6 +64,7 @@ You also need a local inference backend: [Ollama](https://ollama.com), [vLLM](ht
 git clone https://github.com/open-jarvis/OpenJarvis.git
 cd OpenJarvis
 uv sync
+uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml   # required for memory + security features
 uv run jarvis init
 
 # 2. Start Ollama and pull a model
@@ -82,9 +83,11 @@ uv run jarvis ask "What is the capital of France?"
 Install any preset with one command:
 
 ```bash
-jarvis init --preset morning-digest-mac   # or any preset below
+uv run jarvis init --preset morning-digest-mac   # or any preset below
 ```
 
+> Prefix every `jarvis ...` invocation with `uv run`, or activate the venv first (`source .venv/bin/activate`) so plain `jarvis ...` works for the rest of your shell session.
+
 | Preset | Use Case | What it does |
 |--------|----------|-------------|
 | `morning-digest-mac` | Daily Briefing (Mac) | Spoken briefing from email, calendar, health, news with Jarvis voice |
@@ -97,14 +100,14 @@ jarvis init --preset morning-digest-mac   # or any preset below
 
 ```bash
 # Example: Morning Digest on Mac
-jarvis init --preset morning-digest-mac
-jarvis connect gdrive          # one OAuth flow covers Gmail, Calendar, Tasks
-jarvis digest --fresh           # generate and play your first briefing
+uv run jarvis init --preset morning-digest-mac
+uv run jarvis connect gdrive          # one OAuth flow covers Gmail, Calendar, Tasks
+uv run jarvis digest --fresh          # generate and play your first briefing
 
 # Example: Deep Research
-jarvis init --preset deep-research
-jarvis memory index ./docs/    # index your documents
-jarvis ask "Summarize all emails about Project X"
+uv run jarvis init --preset deep-research
+uv run jarvis memory index ./docs/    # requires the Rust extension — see Setup above
+uv run jarvis ask "Summarize all emails about Project X"
 ```
 
 ### Skills

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