roar-cli 0.2.10__tar.gz → 0.3.0__tar.gz

{roar_cli-0.2.10 → roar_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roar-cli
-Version: 0.2.10
+Version: 0.3.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Science/Research
@@ -18,10 +18,12 @@ Requires-Dist: click>=8.1.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: dependency-injector>=4.40.0
 Requires-Dist: msgpack>=1.0.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: pysqlite3-binary>=0.5.0 ; platform_machine == 'x86_64' and sys_platform == 'linux'
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: textual>=0.80
 Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
 Requires-Dist: pytest>=7.0.0 ; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.0.0 ; extra == 'dev'
@@ -65,6 +67,11 @@ uv pip install roar-cli
 
 Requires Python 3.10+.
 
+> For the full prereqs, platform support matrix, tracer-backend setup,
+> macOS SIP notes, and sdist build steps, see the canonical
+> [Installing roar](https://glaas.ai/docs/roar-guide#installing-roar) docs page.
+> What's below is a TL;DR.
+
 ### Platform Support
 
 | Platform      | Status                                                      |
@@ -74,7 +81,12 @@ Requires Python 3.10+.
 | macOS         | 🚧 Experimental ([limitations](#macos-tracing-limitations)) |
 | Windows       | Coming soon                                                 |
 
-PyPI wheels are published for Linux and macOS (`x86_64` and `arm64`).
+PyPI wheels are published for Linux (`x86_64`, `aarch64`) and macOS (`x86_64`, `arm64`).
+
+If a matching wheel isn't available, `pip install` falls through to the
+source distribution. The sdist ships the Rust tracer source but no
+pre-built binaries, so it requires a C toolchain (`gcc` / `clang`), Rust
+(`rustup`), and a few minutes to compile the tracers on first install.
 
 ### Development Installation
 
@@ -83,12 +95,20 @@ PyPI wheels are published for Linux and macOS (`x86_64` and `arm64`).
 git clone https://github.com/treqs/roar.git
 cd roar
 
-# Install in development mode
-uv pip install -e ".[dev]"
-# or without uv
-pip install -e ".[dev]"
+# One-shot dev install: Python package + Rust tracer binaries
+bash scripts/install-dev.sh
 ```
 
+`scripts/install-dev.sh` runs `pip install -e ".[dev]"` (preferring `uv`
+when available) and then builds the Rust tracer binaries
+(`roar-tracer`, `roar-tracer-preload`, `roar-tracer-ebpf`, `roard`,
+`roar-proxy`) and stages them into `roar/bin/`. A bare
+`pip install -e .` does *not* build the tracer binaries because they
+live in separate cargo crates outside the maturin manifest, so
+`roar run` would fail with "No tracer binary found" until the script
+runs. See [Building from source](#building-from-source) below for
+details and the manual flow.
+
 ## Quick Start
 
 ```bash
@@ -102,6 +122,53 @@ roar run python train.py --data features.parquet --output model.pt
 roar run python evaluate.py --model model.pt --output metrics.json
 ```
 
+## Product Telemetry
+
+`roar` keeps anonymous product telemetry counters by default so maintainers can
+prioritize reliability and platform support work. Telemetry is local-first:
+small counters are stored under the XDG cache directory and uploaded
+opportunistically in a background process. Telemetry never uploads file
+contents, command arguments, file paths, environment variables, repository
+names, hostnames, usernames, lineage payloads, or GLaaS auth tokens.
+
+Uploaded payloads are limited to:
+
+- A random `install_id`, event id, sequence number, and coarse timestamps.
+- The installed `roar` version.
+- Coarse platform values: OS family, CPU architecture, Python major/minor,
+  shell name, installer class, and whether the process appears containerized.
+- Allowlisted command counters such as `run`, `init`, `register`, and
+  successful or failed `roar run` outcomes.
+- Allowlisted tracer selection counters and coarse feature capability flags.
+
+Inspect the current status and exact next payload preview:
+
+```bash
+roar telemetry --status
+roar telemetry --print
+```
+
+When `telemetry.endpoint` is unset, roar derives the upload endpoint from the
+configured GLaaS API URL. For example, `glaas.url = "https://api.dev.glaas.ai"`
+uses `https://api.dev.glaas.ai/api/v1/telemetry/roar`.
+
+Disable telemetry globally or for a single project:
+
+```bash
+roar telemetry --disable
+roar config set telemetry.enabled false
+```
+
+Environment opt-outs always win over saved config:
+
+```bash
+DO_NOT_TRACK=1 roar run python train.py
+ROAR_NO_TELEMETRY=1 roar run python train.py
+```
+
+Telemetry is also suppressed automatically in CI, pytest, and Roar-managed
+backend worker environments such as Ray and OSMO jobs.
+
 ## Tracer Backends
 
 `roar run` relies on a Rust "tracer" binary to observe file I/O. If you see an error like "No tracer binary found", build one of the backends below.
@@ -135,10 +202,16 @@ By default, `roar` uses `auto` mode: prefer eBPF, then preload, then ptrace.
 
 ```bash
 # Show what roar can currently find and whether it looks usable
-roar tracer status
+roar tracer
 
 # Set a default backend (auto|ebpf|preload|ptrace)
-roar tracer set-default preload
+roar tracer use preload
+
+# Deep preflight for one backend, with the exact failure cause
+roar tracer check ebpf
+
+# One-shot host setup for the eBPF backend (applies CAP_BPF)
+roar tracer enable ebpf
 ```
 
 ### macOS Tracing Limitations
@@ -213,9 +286,13 @@ roar reproduce abc123de --run --package-sync
 
 # Show all required packages (no truncation)
 roar reproduce abc123de --list-requirements
+
+# Reproduce a full lineage/session by its 64-character DAG hash
+roar reproduce <lineage-hash> --lineage
+roar reproduce <lineage-hash> --lineage --run
 ```
 
-Full reproduction clones the git repository, creates a virtual environment, installs recorded packages, and runs the pipeline steps.
+Unflagged `roar reproduce <hash>` continues to default to artifact reproduction. Full reproduction clones the git repository, creates a virtual environment, installs recorded packages, and runs the pipeline steps.
 
 ### `roar build <command>`
 
@@ -234,7 +311,7 @@ Use for setup that should run before the main pipeline (compiling, installing).
 
 ### `roar auth`
 
-Manage GLaaS authentication.
+Manage SSH-key-based GLaaS registration settings.
 
 ```bash
 roar auth register    # Show SSH public key for registration
@@ -242,7 +319,7 @@ roar auth test        # Test connection to GLaaS server
 roar auth status      # Show current auth status
 ```
 
-To register with GLaaS:
+To register SSH auth with GLaaS:
 
 1. Run `roar auth register` to display your public key
 2. Sign up at <https://glaas.ai> where you can paste your public key
@@ -270,6 +347,7 @@ Run `roar config list` to see all available options with descriptions. Common op
 | `filters.ignore_tmp_files`     | true                   | Ignore /tmp files                       |
 | `glaas.url`                    | <https://api.glaas.ai> | GLaaS server URL                        |
 | `glaas.web_url`                | <https://glaas.ai>     | GLaaS web UI URL                        |
+| `registration.public_by_default` | false                | Default `register`/`put` visibility     |
 | `registration.omit.enabled`    | true                   | Enable secret filtering                 |
 | `hash.primary`                 | blake3                 | Primary hash algorithm                  |
 | `logging.level`                | warning                | Log level (debug, info, warning, error) |
@@ -304,6 +382,45 @@ Display recent job execution history.
 roar log                  # Show recent job history
 ```
 
+### `roar label`
+
+Manage local labels for DAGs (sessions), jobs, and artifacts.
+
+```bash
+# Set labels (patches the current label document)
+roar label set dag current owner=alice team=ml
+roar label set job @2 phase=train lr=0.001
+roar label set artifact ./outputs/model.pt model.name=resnet50 stage=baseline
+
+# Remove labels
+roar label unset artifact ./outputs/model.pt stage
+
+# Copy labels from one entity to another
+roar label cp job @2 artifact ./outputs/model.pt
+
+# Show current labels
+roar label show dag current
+roar label show job @2
+roar label show artifact ./outputs/model.pt
+
+# Show label history (all versions)
+roar label history dag current
+roar label history artifact <artifact-hash>
+
+# Sync local user-managed labels to GLaaS
+roar label sync
+roar label sync job @2
+roar label sync artifact ./outputs/model.pt --dry-run
+```
+
+**Entity targets:**
+
+- `dag`: `current` or a session hash prefix
+- `job`: step ref (`@N` or `@BN`) or job UID
+- `artifact`: file path or artifact hash
+
+Labels are stored locally by default. You can explicitly reconcile current local user-managed labels to GLaaS with `roar label sync ...`, and labels are also included in lineage registration/publish flows when supported by the configured server.
+
 ### `roar register`
 
 Register session, job, step, or artifact lineage with GLaaS.
@@ -330,6 +447,14 @@ roar register s3://bucket/run/out   # Register a tracked remote S3 artifact
 
 For bare 8-character hex targets, `roar register` prefers a matching local job UID before falling back to session-hash-prefix resolution.
 
+To make public publication the default for `roar register` and `roar put`:
+
+```bash
+roar config set registration.public_by_default true
+```
+
+Override per command with `--public` or `--private`. Use `--anonymous` on `roar register` or `roar put` to force public anonymous publication even when local GLaaS auth is configured. When public visibility comes from config rather than an explicit flag, `roar` prints a warning before publishing.
+
 ### `roar put`
 
 Upload artifacts to cloud storage and register lineage with GLaaS.
@@ -345,6 +470,8 @@ roar put @2 s3://bucket/outputs/ -m "Step 2 outputs"
 - `-m, --message` — Description of the upload (required)
 - `--dry-run` — Preview without uploading
 - `--no-tag` — Skip git tagging
+- `--public` / `--private` — Override configured publish visibility
+- `--anonymous` — Force public anonymous registration even when local GLaaS auth is configured
 
 **Source formats:**
 
@@ -397,12 +524,27 @@ roar show ./output/model.pkl       # Show artifact by path
 
 ### `roar status`
 
-Show a summary of the active session.
+Show a summary of the active session, including the current DAG hash.
 
 ```bash
 roar status
 ```
 
+### `roar workflow`
+
+Generate TReqs workflow YAML from a local session.
+
+```bash
+roar workflow generate
+roar workflow generate .treqs/workflows/train.yaml
+roar workflow generate --session 8d7a1f2c --name train
+```
+
+Generated workflows follow the TReqs workflow format: `name`, optional
+`working_directory`, and one YAML key per task in session step order.
+By default, `roar workflow generate` uses the active session and writes the
+workflow under `.treqs/workflows/` at the repo root.
+
 ### `roar pop`
 
 Remove the most recent job from the active session. Useful for undoing a mistaken `roar run` or correcting the pipeline before registration.
@@ -513,10 +655,62 @@ roar auth test
 ### Setup
 
 ```bash
-# Install dev dependencies
-uv pip install -e ".[dev]"
+bash scripts/install-dev.sh
 ```
 
+The script handles Python install + Rust tracer builds + staging
+binaries into `roar/bin/`. See [Building from source](#building-from-source)
+for what it does and how to run the steps manually.
+
+### Building from source
+
+`pip install -e .` runs `maturin develop` to build the `artifact-hash-py`
+pyo3 extension, but the tracer binaries (`roar-tracer*`, `roard`,
+`roar-proxy`) are separate cargo packages outside the maturin manifest.
+The PyPI wheels bundle them under `roar/bin/`; an editable install
+does not, and `roar run` fails until they're built and staged.
+
+The fastest path is `scripts/install-dev.sh`, which does this:
+
+```bash
+# 1. Python package (editable, with dev extras)
+uv pip install -e ".[dev]"   # or pip install -e ".[dev]"
+
+# 2. Build the per-platform tracer crates
+cd rust
+# Linux:
+cargo build --release \
+  -p roar-tracer -p roar-tracer-preload -p roar-tracer-ebpf -p roar-proxy
+# macOS:
+cargo build --release -p roar-tracer-preload -p roar-proxy
+
+# 3. Stage the built binaries where the editable install looks for them
+cd ..
+mkdir -p roar/bin
+# Linux: install five binaries + the preload .so
+install -m 0755 rust/target/release/{roar-tracer,roar-tracer-preload,roar-tracer-ebpf,roard,roar-proxy} roar/bin/
+install -m 0755 rust/target/release/libroar_tracer_preload.so roar/bin/
+# macOS: install the launcher + the preload .dylib + roar-proxy
+# install -m 0755 rust/target/release/{roar-tracer-preload,roar-proxy} roar/bin/
+# install -m 0755 rust/target/release/libroar_tracer_preload.dylib roar/bin/
+```
+
+The eBPF tracer (Linux only) needs `bpf-linker` and a Rust nightly
+toolchain with `rust-src` for the BPF probe build:
+
+```bash
+cargo install bpf-linker
+rustup install nightly
+rustup component add rust-src --toolchain nightly
+```
+
+`scripts/install-dev.sh` skips eBPF gracefully when `bpf-linker` is
+absent — the other tracers still work.
+
+Verify the install with `roar tracer`; every backend listed should be
+`ready` (or have a clear platform-specific reason it isn't, like
+`perf_event_paranoid=4 (needs <= 1)` for eBPF on a hardened kernel).
+
 ### Running Quality Checks
 
 ```bash

{roar_cli-0.2.10 → roar_cli-0.3.0}/README.md

@@ -18,6 +18,11 @@ uv pip install roar-cli
 
 Requires Python 3.10+.
 
+> For the full prereqs, platform support matrix, tracer-backend setup,
+> macOS SIP notes, and sdist build steps, see the canonical
+> [Installing roar](https://glaas.ai/docs/roar-guide#installing-roar) docs page.
+> What's below is a TL;DR.
+
 ### Platform Support
 
 | Platform      | Status                                                      |
@@ -27,7 +32,12 @@ Requires Python 3.10+.
 | macOS         | 🚧 Experimental ([limitations](#macos-tracing-limitations)) |
 | Windows       | Coming soon                                                 |
 
-PyPI wheels are published for Linux and macOS (`x86_64` and `arm64`).
+PyPI wheels are published for Linux (`x86_64`, `aarch64`) and macOS (`x86_64`, `arm64`).
+
+If a matching wheel isn't available, `pip install` falls through to the
+source distribution. The sdist ships the Rust tracer source but no
+pre-built binaries, so it requires a C toolchain (`gcc` / `clang`), Rust
+(`rustup`), and a few minutes to compile the tracers on first install.
 
 ### Development Installation
 
@@ -36,12 +46,20 @@ PyPI wheels are published for Linux and macOS (`x86_64` and `arm64`).
 git clone https://github.com/treqs/roar.git
 cd roar
 
-# Install in development mode
-uv pip install -e ".[dev]"
-# or without uv
-pip install -e ".[dev]"
+# One-shot dev install: Python package + Rust tracer binaries
+bash scripts/install-dev.sh
 ```
 
+`scripts/install-dev.sh` runs `pip install -e ".[dev]"` (preferring `uv`
+when available) and then builds the Rust tracer binaries
+(`roar-tracer`, `roar-tracer-preload`, `roar-tracer-ebpf`, `roard`,
+`roar-proxy`) and stages them into `roar/bin/`. A bare
+`pip install -e .` does *not* build the tracer binaries because they
+live in separate cargo crates outside the maturin manifest, so
+`roar run` would fail with "No tracer binary found" until the script
+runs. See [Building from source](#building-from-source) below for
+details and the manual flow.
+
 ## Quick Start
 
 ```bash
@@ -55,6 +73,53 @@ roar run python train.py --data features.parquet --output model.pt
 roar run python evaluate.py --model model.pt --output metrics.json
 ```
 
+## Product Telemetry
+
+`roar` keeps anonymous product telemetry counters by default so maintainers can
+prioritize reliability and platform support work. Telemetry is local-first:
+small counters are stored under the XDG cache directory and uploaded
+opportunistically in a background process. Telemetry never uploads file
+contents, command arguments, file paths, environment variables, repository
+names, hostnames, usernames, lineage payloads, or GLaaS auth tokens.
+
+Uploaded payloads are limited to:
+
+- A random `install_id`, event id, sequence number, and coarse timestamps.
+- The installed `roar` version.
+- Coarse platform values: OS family, CPU architecture, Python major/minor,
+  shell name, installer class, and whether the process appears containerized.
+- Allowlisted command counters such as `run`, `init`, `register`, and
+  successful or failed `roar run` outcomes.
+- Allowlisted tracer selection counters and coarse feature capability flags.
+
+Inspect the current status and exact next payload preview:
+
+```bash
+roar telemetry --status
+roar telemetry --print
+```
+
+When `telemetry.endpoint` is unset, roar derives the upload endpoint from the
+configured GLaaS API URL. For example, `glaas.url = "https://api.dev.glaas.ai"`
+uses `https://api.dev.glaas.ai/api/v1/telemetry/roar`.
+
+Disable telemetry globally or for a single project:
+
+```bash
+roar telemetry --disable
+roar config set telemetry.enabled false
+```
+
+Environment opt-outs always win over saved config:
+
+```bash
+DO_NOT_TRACK=1 roar run python train.py
+ROAR_NO_TELEMETRY=1 roar run python train.py
+```
+
+Telemetry is also suppressed automatically in CI, pytest, and Roar-managed
+backend worker environments such as Ray and OSMO jobs.
+
 ## Tracer Backends
 
 `roar run` relies on a Rust "tracer" binary to observe file I/O. If you see an error like "No tracer binary found", build one of the backends below.
@@ -88,10 +153,16 @@ By default, `roar` uses `auto` mode: prefer eBPF, then preload, then ptrace.
 
 ```bash
 # Show what roar can currently find and whether it looks usable
-roar tracer status
+roar tracer
 
 # Set a default backend (auto|ebpf|preload|ptrace)
-roar tracer set-default preload
+roar tracer use preload
+
+# Deep preflight for one backend, with the exact failure cause
+roar tracer check ebpf
+
+# One-shot host setup for the eBPF backend (applies CAP_BPF)
+roar tracer enable ebpf
 ```
 
 ### macOS Tracing Limitations
@@ -166,9 +237,13 @@ roar reproduce abc123de --run --package-sync
 
 # Show all required packages (no truncation)
 roar reproduce abc123de --list-requirements
+
+# Reproduce a full lineage/session by its 64-character DAG hash
+roar reproduce <lineage-hash> --lineage
+roar reproduce <lineage-hash> --lineage --run
 ```
 
-Full reproduction clones the git repository, creates a virtual environment, installs recorded packages, and runs the pipeline steps.
+Unflagged `roar reproduce <hash>` continues to default to artifact reproduction. Full reproduction clones the git repository, creates a virtual environment, installs recorded packages, and runs the pipeline steps.
 
 ### `roar build <command>`
 
@@ -187,7 +262,7 @@ Use for setup that should run before the main pipeline (compiling, installing).
 
 ### `roar auth`
 
-Manage GLaaS authentication.
+Manage SSH-key-based GLaaS registration settings.
 
 ```bash
 roar auth register    # Show SSH public key for registration
@@ -195,7 +270,7 @@ roar auth test        # Test connection to GLaaS server
 roar auth status      # Show current auth status
 ```
 
-To register with GLaaS:
+To register SSH auth with GLaaS:
 
 1. Run `roar auth register` to display your public key
 2. Sign up at <https://glaas.ai> where you can paste your public key
@@ -223,6 +298,7 @@ Run `roar config list` to see all available options with descriptions. Common op
 | `filters.ignore_tmp_files`     | true                   | Ignore /tmp files                       |
 | `glaas.url`                    | <https://api.glaas.ai> | GLaaS server URL                        |
 | `glaas.web_url`                | <https://glaas.ai>     | GLaaS web UI URL                        |
+| `registration.public_by_default` | false                | Default `register`/`put` visibility     |
 | `registration.omit.enabled`    | true                   | Enable secret filtering                 |
 | `hash.primary`                 | blake3                 | Primary hash algorithm                  |
 | `logging.level`                | warning                | Log level (debug, info, warning, error) |
@@ -257,6 +333,45 @@ Display recent job execution history.
 roar log                  # Show recent job history
 ```
 
+### `roar label`
+
+Manage local labels for DAGs (sessions), jobs, and artifacts.
+
+```bash
+# Set labels (patches the current label document)
+roar label set dag current owner=alice team=ml
+roar label set job @2 phase=train lr=0.001
+roar label set artifact ./outputs/model.pt model.name=resnet50 stage=baseline
+
+# Remove labels
+roar label unset artifact ./outputs/model.pt stage
+
+# Copy labels from one entity to another
+roar label cp job @2 artifact ./outputs/model.pt
+
+# Show current labels
+roar label show dag current
+roar label show job @2
+roar label show artifact ./outputs/model.pt
+
+# Show label history (all versions)
+roar label history dag current
+roar label history artifact <artifact-hash>
+
+# Sync local user-managed labels to GLaaS
+roar label sync
+roar label sync job @2
+roar label sync artifact ./outputs/model.pt --dry-run
+```
+
+**Entity targets:**
+
+- `dag`: `current` or a session hash prefix
+- `job`: step ref (`@N` or `@BN`) or job UID
+- `artifact`: file path or artifact hash
+
+Labels are stored locally by default. You can explicitly reconcile current local user-managed labels to GLaaS with `roar label sync ...`, and labels are also included in lineage registration/publish flows when supported by the configured server.
+
 ### `roar register`
 
 Register session, job, step, or artifact lineage with GLaaS.
@@ -283,6 +398,14 @@ roar register s3://bucket/run/out   # Register a tracked remote S3 artifact
 
 For bare 8-character hex targets, `roar register` prefers a matching local job UID before falling back to session-hash-prefix resolution.
 
+To make public publication the default for `roar register` and `roar put`:
+
+```bash
+roar config set registration.public_by_default true
+```
+
+Override per command with `--public` or `--private`. Use `--anonymous` on `roar register` or `roar put` to force public anonymous publication even when local GLaaS auth is configured. When public visibility comes from config rather than an explicit flag, `roar` prints a warning before publishing.
+
 ### `roar put`
 
 Upload artifacts to cloud storage and register lineage with GLaaS.
@@ -298,6 +421,8 @@ roar put @2 s3://bucket/outputs/ -m "Step 2 outputs"
 - `-m, --message` — Description of the upload (required)
 - `--dry-run` — Preview without uploading
 - `--no-tag` — Skip git tagging
+- `--public` / `--private` — Override configured publish visibility
+- `--anonymous` — Force public anonymous registration even when local GLaaS auth is configured
 
 **Source formats:**
 
@@ -350,12 +475,27 @@ roar show ./output/model.pkl       # Show artifact by path
 
 ### `roar status`
 
-Show a summary of the active session.
+Show a summary of the active session, including the current DAG hash.
 
 ```bash
 roar status
 ```
 
+### `roar workflow`
+
+Generate TReqs workflow YAML from a local session.
+
+```bash
+roar workflow generate
+roar workflow generate .treqs/workflows/train.yaml
+roar workflow generate --session 8d7a1f2c --name train
+```
+
+Generated workflows follow the TReqs workflow format: `name`, optional
+`working_directory`, and one YAML key per task in session step order.
+By default, `roar workflow generate` uses the active session and writes the
+workflow under `.treqs/workflows/` at the repo root.
+
 ### `roar pop`
 
 Remove the most recent job from the active session. Useful for undoing a mistaken `roar run` or correcting the pipeline before registration.
@@ -466,10 +606,62 @@ roar auth test
 ### Setup
 
 ```bash
-# Install dev dependencies
-uv pip install -e ".[dev]"
+bash scripts/install-dev.sh
 ```
 
+The script handles Python install + Rust tracer builds + staging
+binaries into `roar/bin/`. See [Building from source](#building-from-source)
+for what it does and how to run the steps manually.
+
+### Building from source
+
+`pip install -e .` runs `maturin develop` to build the `artifact-hash-py`
+pyo3 extension, but the tracer binaries (`roar-tracer*`, `roard`,
+`roar-proxy`) are separate cargo packages outside the maturin manifest.
+The PyPI wheels bundle them under `roar/bin/`; an editable install
+does not, and `roar run` fails until they're built and staged.
+
+The fastest path is `scripts/install-dev.sh`, which does this:
+
+```bash
+# 1. Python package (editable, with dev extras)
+uv pip install -e ".[dev]"   # or pip install -e ".[dev]"
+
+# 2. Build the per-platform tracer crates
+cd rust
+# Linux:
+cargo build --release \
+  -p roar-tracer -p roar-tracer-preload -p roar-tracer-ebpf -p roar-proxy
+# macOS:
+cargo build --release -p roar-tracer-preload -p roar-proxy
+
+# 3. Stage the built binaries where the editable install looks for them
+cd ..
+mkdir -p roar/bin
+# Linux: install five binaries + the preload .so
+install -m 0755 rust/target/release/{roar-tracer,roar-tracer-preload,roar-tracer-ebpf,roard,roar-proxy} roar/bin/
+install -m 0755 rust/target/release/libroar_tracer_preload.so roar/bin/
+# macOS: install the launcher + the preload .dylib + roar-proxy
+# install -m 0755 rust/target/release/{roar-tracer-preload,roar-proxy} roar/bin/
+# install -m 0755 rust/target/release/libroar_tracer_preload.dylib roar/bin/
+```
+
+The eBPF tracer (Linux only) needs `bpf-linker` and a Rust nightly
+toolchain with `rust-src` for the BPF probe build:
+
+```bash
+cargo install bpf-linker
+rustup install nightly
+rustup component add rust-src --toolchain nightly
+```
+
+`scripts/install-dev.sh` skips eBPF gracefully when `bpf-linker` is
+absent — the other tracers still work.
+
+Verify the install with `roar tracer`; every backend listed should be
+`ready` (or have a clear platform-specific reason it isn't, like
+`perf_event_paranoid=4 (needs <= 1)` for eBPF on a hardened kernel).
+
 ### Running Quality Checks
 
 ```bash