optimize & update osx.md

.github/workflows/macos.yml

@@ -64,7 +64,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --all-extras --no-extra dds --no-extra cuda --frozen
+          uv sync --all-extras --no-extra cuda --frozen
 
       - name: Check disk usage
         run: |
@@ -116,7 +116,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --all-extras --no-extra dds --no-extra cuda --frozen
+          uv sync --all-extras --no-extra cuda --frozen
 
       - name: Run mypy
         run: |

.github/workflows/tests.yml

@@ -38,7 +38,7 @@ jobs:
           git config --global --add safe.directory '*'
 
       - name: Install Python dependencies
-        run: uv sync --all-extras --no-extra dds --frozen
+        run: uv sync --all-extras --frozen
 
       - name: Remove pydrake stubs
         run: |

AGENTS.md

@@ -10,7 +10,7 @@ The agentic operating system for generalist robotics. `Modules` communicate via
 
 ```bash
 # Install
-uv sync --all-extras --no-extra dds
+uv sync --all-extras
 
 # List all runnable blueprints
 dimos list

README.md

@@ -313,7 +313,7 @@ export GIT_LFS_SKIP_SMUDGE=1
 git clone -b dev https://github.com/dimensionalOS/dimos.git
 cd dimos
 
-uv sync --all-extras --no-extra dds
+uv sync --all-extras
 
 # Run fast test suite
 uv run pytest dimos

docs/development/testing.md

@@ -3,7 +3,7 @@
 For development, you should install all dependencies so that tests have access to them.
 
 ```bash
-uv sync --all-extras --no-extra dds
+uv sync --all-extras
 ```
 
 ## Types of tests

docs/installation/osx.md

@@ -1,41 +1,142 @@
 # macOS Install (12.6 or newer)
 
+## 1. Install Homebrew
+
 ```sh
-# install homebrew
+# Official installer; follow prompts to add brew to PATH if the script says so.
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-# install dependencies
+```
+
+## 2. Install system dependencies
+
+```sh
 brew install gnu-sed gcc portaudio git-lfs libjpeg-turbo python pre-commit
+```
+
+## 3. Install uv (fast Python package manager)
 
-# install uv
-curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH"
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
 ```
 
-# Using DimOS as a library
+---
+
+# Using DimOS as a Library
+
+## 1. Create project
 
 ```sh
 mkdir myproject && cd myproject
-
 uv venv --python 3.12
 source .venv/bin/activate
+```
+
+---
+
+## 2. Install DimOS (choose ONE setup)
+
+### 🔹 Minimal (core only)
+
+```sh
+uv pip install dimos
+```
+
+---
+
+### 🔹 Simulation only (recommended starting point)
+
+```sh
+uv pip install 'dimos[sim,visualization]'
+```
+
+---
+
+### 🔹 AI Agents (LLM + audio)
+
+```sh
+uv pip install 'dimos[agents,cpu]'
+```
+
+---
+
+### 🔹 Vision / Perception
+
+```sh
+uv pip install 'dimos[perception,cpu]'
+```
+
+---
 
-# install everything (depending on your use case you might not need all extras,
-# check your respective platform guides)
-uv pip install 'dimos[misc,sim,visualization,agents,web,perception,unitree,manipulation,cpu,dev]'
+### 🔹 Web backend (FastAPI)
+
+```sh
+uv pip install 'dimos[web]'
+```
+
+---
+
+### 🔹 Balanced full-stack (recommended)
+
+```sh
+uv pip install 'dimos[sim,agents,web,perception,visualization,cpu]'
+```
+
+---
+
+### 🔹 Development (testing, linting)
+
+```sh
+uv pip install 'dimos[dev]'
+```
+
+---
+
+### 🔹 Unitree robots (heavy)
+
+```sh
+uv pip install 'dimos[unitree]'
 ```
 
+⚠️ This installs many dependencies automatically.
+
+---
+
+## ⚠️ Important (zsh users)
+
+Always quote extras:
+
+```sh
+uv pip install 'dimos[sim,agents]'
+```
+
+Without quotes, zsh treats `[]` as a glob pattern and the command will fail.
+
+---
+
 # Developing on DimOS
 
+<!-- Clone workflow: matches AGENTS.md / typical dev setup; DDS omitted unless you install that extra. -->
+
 ```sh
-# this allows getting large files on-demand (and not pulling all immediately)
+# Skip LFS file checkout until needed (smaller clone); fetch LFS objects when you need them.
 export GIT_LFS_SKIP_SMUDGE=1
+
 git clone -b dev https://github.com/dimensionalOS/dimos.git
 cd dimos
 
-uv sync --all-extras --no-extra dds
+# Project lockfile + all optional groups.
+uv sync --all-extras
+```
+
+## Type checking
 
-# type check
+```sh
 uv run mypy dimos
+```
 
-# tests (around a minute to run)
+## Run tests
+
+```sh
 uv run pytest dimos
 ```

docs/installation/ubuntu.md

@@ -29,7 +29,7 @@ export GIT_LFS_SKIP_SMUDGE=1
 git clone -b dev https://github.com/dimensionalOS/dimos.git
 cd dimos
 
-uv sync --all-extras --no-extra dds
+uv sync --all-extras
 
 # type check
 uv run mypy dimos