fix: repair install.sh and add cross-platform installation CI

.github/workflows/install.yml

@@ -0,0 +1,73 @@
+name: Test installation script
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/install.sh'
+      - 'scripts/test-install.sh'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'setup.py'
+      - 'MANIFEST.in'
+      - '.github/workflows/install.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: install-${{ github.ref }}
+  cancel-in-progress: true
+
+# macOS installation jobs are deferred until runner capacity is available.
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      - name: Shell syntax and lint
+        run: |
+          /bin/bash -n scripts/install.sh
+          /bin/bash -n scripts/test-install.sh
+          uvx --from shellcheck-py shellcheck -e SC1091 scripts/install.sh scripts/test-install.sh
+
+  ubuntu:
+    needs: lint
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm]
+        version: ['22.04', '24.04']
+        mode: [library, dev]
+    runs-on: ${{ matrix.os }}
+    container: ubuntu:${{ matrix.version }}
+    timeout-minutes: 60
+    env:
+      INSTALL_TEST_ROOT: /tmp/dimos-install-test
+    steps:
+      # curl and Git are prerequisites for fetching and testing the installer.
+      # All DimOS runtime/build prerequisites must be installed by install.sh.
+      - name: Bootstrap checkout tools
+        run: |
+          apt-get update
+          apt-get install -y ca-certificates curl git
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Install and verify
+        run: |
+          # checkout's safe.directory setting uses a temporary HOME. The
+          # container's later steps need to trust this mounted checkout too.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          git config --global --add safe.directory "$GITHUB_WORKSPACE/.git"
+          bash scripts/test-install.sh '${{ matrix.mode }}'
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        # act has no GitHub artifact service; installation output stays in its log.
+        if: always() && !env.ACT
+        with:
+          name: install-${{ matrix.os }}-${{ matrix.version }}-${{ matrix.mode }}
+          path: /tmp/dimos-install-test/logs

AGENTS.md

@@ -9,8 +9,8 @@ The agentic operating system for generalist robotics. `Modules` communicate via
 ## Quick Start
 
 ```bash
-# Install (requires uv >=0.9.25)
-uv sync --extra all
+# Set up the current checkout, including test and lint dependencies
+bash scripts/install.sh --mode dev --project-dir .
 
 # List all runnable blueprints
 dimos list

CONTRIBUTING.md

@@ -51,7 +51,7 @@ We want people to use Dimensional, learn it, and help us build it. You do not ne
 Browse [open issues labeled](https://github.com/dimensionalOS/dimos/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) `good first issue`. These are scoped tasks that maintainers have marked as approachable for newcomers. Pick one, read the description, and comment if you want to work on it or need clarification. Maintainers are happy to point you in the right direction.
 
 **Get set up.**
-Follow [AGENTS.md](AGENTS.md) for install (`uv sync --extra all`), running blueprints in simulation or replay, and the test workflow (`uv run pytest`). Most changes can be developed and validated without a physical robot.
+Use the [official installer](docs/installation/index.md) in developer mode. Follow [AGENTS.md](AGENTS.md) for running blueprints in simulation or replay and the test workflow (`uv run pytest`). Most changes can be developed and validated without a physical robot.
 
 **This still applies to you.**
 The [critical rule](#the-critical-rule) and [AI policy](AI_POLICY.md) apply to every outside contribution, including yours. Use AI tools if they help you learn the codebase, but understand what you submit. Link your PR to the issue you are working on.

README.md

@@ -137,42 +137,40 @@ Dimensional is agent native -- "vibecode" your robots in natural language and bu
 
 # Installation
 
-## Interactive Install
+## Guided installation (recommended)
+
+Use the official installer to set up system dependencies, Python 3.12, and dimOS:
 
 ```sh skip
 curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash
 ```
 
 > See [`scripts/install.sh --help`](scripts/install.sh) for non-interactive and advanced options.
 
-## Manual System Install
-
-To set up your system dependencies, follow one of these guides:
+See [installer options](docs/installation/index.md), or platform notes:
 
 - 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md)
-- 🟩 [NixOS / General Linux](docs/installation/nix.md)
+- [NixOS / General Linux (not CI-tested)](docs/installation/nix.md)
 - 🟧 [macOS](docs/installation/osx.md)
 
 > Full system requirements, tested configs, and dependency tiers: [docs/requirements.md](docs/requirements.md)
 
-## Python Install
+## Manual installation
 
-### Quickstart
+If you need to install without the script, follow the system-package and Python steps for [Ubuntu](docs/installation/ubuntu.md#manual-installation), [macOS](docs/installation/osx.md#manual-installation), or [Nix](docs/installation/nix.md#manual-installation).
 
-```bash
-uv venv --python "3.12"
-source .venv/bin/activate
-uv pip install 'dimos[base,unitree]'
+## Quickstart
 
+Activate the environment using the command printed by the installer, then run:
+
+```bash
 # Replay a recorded quadruped session (no hardware needed)
 # NOTE: First run will show a black rerun window while ~75 MB downloads from LFS
 dimos --replay run unitree-go2
 ```
 
 ```bash
-# Install with simulation support
-uv pip install 'dimos[base,unitree,sim]'
-
+# The installer's default extras include simulation support.
 # Run quadruped in MuJoCo simulation
 dimos --simulation run unitree-go2
 

bin/run-doc-codeblocks

@@ -85,7 +85,7 @@ resolve_md_babel() {
   elif command -v md-babel-py &>/dev/null; then
     MB=(md-babel-py)
   else
-    echo "Error: md-babel-py not found. Install project deps (e.g. uv sync --extra dev or uv sync --all-extras)." >&2
+    echo "Error: md-babel-py not found. Install project deps (e.g. uv sync --group tests)." >&2
     exit 1
   fi
 }

dimos/web/relay_bridge/test_relay_process.py

@@ -116,7 +116,7 @@ def test_relay_run_cmd_resolves_symlinked_dirs(tmp_path: Path) -> None:
 
 
 def test_relay_process_reports_unpaired_tls_flag_before_reading_pem(tmp_path: Path) -> None:
-    process = RelayProcess(cert=tmp_path / "missing.pem", timeout=2.0)
+    process = RelayProcess(cert=tmp_path / "missing.pem")
 
     try:
         with pytest.raises(RuntimeError, match="--cert and --key must be given together"):

docker/python/Dockerfile

@@ -5,6 +5,8 @@ FROM ${FROM_IMAGE}
 RUN apt-get update && apt-get install -y \
     python-is-python3 \
     curl \
+    libsndfile1 \
+    ffmpeg \
     gnupg2 \
     lsb-release \
     python3-pip \

docs/capabilities/manipulation/a1z.md

@@ -6,6 +6,8 @@ the pinned Git revision until the vendor publishes a compatible release.
 
 ## Install from a source checkout
 
+Create a developer environment with the [official installer](/docs/installation/index.md) first. Then install the A1Z-specific SDK and tools below.
+
 The repository setup script shows its complete plan and asks for confirmation
 before it changes the checkout environment or installs system packages:
 
@@ -18,12 +20,11 @@ checkout. It installs `can-utils` on Ubuntu and `libusb` through Homebrew on
 macOS when needed. On other Linux distributions, it prints the missing system
 package instead of selecting a package manager for you.
 
-## Install into an existing environment
+## Add the vendor SDK to a library environment
 
-Install these requirements with the package manager that owns the environment:
+Follow the [official installation guide](/docs/installation/index.md) and select the `manipulation` extra. In that environment, add the A1Z vendor SDK with the package manager that owns it:
 
 ```bash
-python -m pip install 'dimos[manipulation]'
 python -m pip install 'a1z @ git+https://github.com/userguide-galaxea/GALAXEA-A1Z.git@e931ecd0e25ad35df251097ba42921b3d2fa7224'
 ```
 

docs/capabilities/manipulation/agentic.md

@@ -8,7 +8,7 @@ the underlying planning and perception stack.
 
 ## Prerequisites
 
-Install the manipulation dependencies:
+Use the [official installer](/docs/installation/index.md) first; its default extras include manipulation. To add the dependencies to an existing developer environment:
 
 ```bash
 uv sync --extra manipulation --inexact

docs/capabilities/manipulation/index.md

@@ -288,7 +288,7 @@ after clear.
 Validate Cartesian, twist, and teleop behavior in simulation or replay before
 hardware use.
 
-Install the manipulation dependencies:
+Start with the [official installer](/docs/installation/index.md); its default extras include manipulation. To add manipulation to an existing developer environment:
 
 ```bash
 uv sync --extra manipulation --inexact
@@ -307,7 +307,7 @@ are needed.
 
 For a smaller installation, use `uv sync --extra planning --inexact` or
 `uv sync --extra control --inexact`. Add `--no-default-groups` to omit contributor test
-dependencies. Library installations use `pip install 'dimos[manipulation]'`.
+dependencies. For a new library installation, pass `--mode library --extras manipulation` to the official installer.
 The `--inexact` flag preserves additional packages already installed in your
 environment. The bundle supplies its own dependencies without requiring `misc`.
 Embedding models and unrelated utilities remain available through `misc`.

docs/development/testing.md

@@ -1,5 +1,7 @@
 # Testing
 
+Start with the [official installer](/docs/installation/index.md) in developer mode to provision system, Python, test, and lint dependencies.
+
 `uv run` syncs the project deps + `tests` group on demand, so the default test suite needs no upfront install: `uv run pytest --numprocesses=auto dimos` (xdist parallelizes across cores).
 
 Self-hosted tests need the heavy optional extras (LFS data, perception models, simulation, hardware SDKs, …). Sync them explicitly before running:
@@ -69,13 +71,10 @@ pytest -m self_hosted dimos/path/to/test_something.py
 
 ## Testing on a fresh Ubuntu install
 
-CI tests dimos with pre-built images and cached deps, so it can't catch gaps
-between what [`installation/ubuntu.md`](/docs/installation/ubuntu.md) tells a new user to
-do and what a clean machine actually needs (e.g. a system package we require but
-forgot to document).
+Installation CI runs `scripts/test-install.sh` in fresh Ubuntu 22.04/24.04 containers on x86_64 and ARM64. It verifies one library or developer installation per job without starting blueprints. See [local installation checks](#test-a-checkout-locally).
 
-The [misc/fresh-ubuntu-tests/](/misc/fresh-ubuntu-tests/) harness closes that
-gap. It replays the documented install + test flow inside a fresh, official,
+The application test suite uses pre-built images and cached dependencies. For additional application tests, the
+[misc/fresh-ubuntu-tests/](/misc/fresh-ubuntu-tests/) harness runs its install and test flow inside a fresh, official,
 **unmodified** Ubuntu Desktop 24.04 VM (VirtualBox).
 
 It's intended to be executed locally.
@@ -191,3 +190,16 @@ If a test needs to be skipped for some reason, please use on of these markers, o
 * `skipif_in_ci`: tests which cannot run in GitHub Actions
 * `skipif_no_openai`: tests which require an `OPENAI_API_KEY` key in the env
 * `skipif_no_alibaba`: tests which require an `ALIBABA_API_KEY` key in the env
+
+## Test a checkout locally
+
+From the repository, run either mode in a fresh temporary directory:
+
+```sh skip
+INSTALL_TEST_ROOT="$(mktemp -d)" bash scripts/test-install.sh library
+INSTALL_TEST_ROOT="$(mktemp -d)" bash scripts/test-install.sh dev
+```
+
+Library mode tests this checkout's installer against the published package. Developer mode clones the current commit (commit local changes first to include them). Logs are saved in `logs/install.log` under each temporary directory.
+
+These checks disable GPU access and skip replay and sysctl changes. The temporary directory isolates the project and Python environment; apt or Homebrew packages are installed on the host. Use a disposable Ubuntu container for isolation. On macOS, these commands test Homebrew setup. On Arch, they require manually installed system dependencies because the test helper disables Nix.

docs/installation/index.md

@@ -0,0 +1,43 @@
+# Installation
+
+The recommended way to install dimOS is the guided `install.sh` script. It installs system dependencies, uv, Python, and dimOS into a project virtual environment (or a source checkout for contributors). Run it from a terminal:
+
+```sh skip
+curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash
+```
+
+The installer asks for a mode and project directory, sets up system dependencies and uv, installs Python 3.12 and dimOS, and verifies the CLI and native libraries. It can also configure LCM networking and run an optional replay check. Follow the printed activation instructions when it finishes.
+
+| Platform | Installation path | Validation |
+| --- | --- | --- |
+| [Ubuntu 22.04/24.04](/docs/installation/ubuntu.md), x86_64/ARM64 | apt | Both modes pass CPU installation CI |
+| [macOS](/docs/installation/osx.md), Apple Silicon | Homebrew | CI paused; local testing needed |
+| [NixOS / other Linux](/docs/installation/nix.md), including Arch | Nix | Not covered by installation CI |
+
+Linux ARM64 excludes `scene` because `usd-core` has no wheel. CUDA extras require Linux x86_64; Jetson CUDA setup is not supported. Installation checks do not qualify robot hardware or GPU workloads.
+
+## Choose a mode
+
+- **Library (recommended)** installs the published package in a project virtual environment.
+- **Developer** clones `main` and installs the checkout with test and lint dependencies. An existing checkout is reused without pulling or switching branches.
+
+Install a CPU library environment without prompts or replay:
+
+```sh skip
+curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash -s -- \
+  --mode library --project-dir ./dimos-app \
+  --non-interactive --no-nix --no-cuda --no-sysctl --skip-tests
+cd dimos-app
+source .venv/bin/activate
+uv run dimos --help
+```
+
+Use `--mode dev --project-dir ./dimos` for a source checkout. Use `--extras base,unitree` to select capabilities (developer mode defaults to `all` with platform exclusions). See [dependency tiers](/docs/requirements.md#dependency-tiers).
+
+`--skip-tests` skips replay only (installation verification still runs). `--no-sysctl` skips network tuning. These commands can install system packages on your host.
+
+For all options:
+
+```sh skip
+curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash -s -- --help
+```