QUICKSTART-USER.adoc

AmbientOps Quickstart

Table of Contents

• What is AmbientOps?
• Prerequisites
• Clone and First Build
• First Run: Hardware Scan
• Run Tests
• Clinician Feature Gates
• End-to-End Demo
• Guided Tour
• Troubleshooting
• Project Structure (Key Paths)
• Further Reading

What is AmbientOps?

AmbientOps is a hospital-model operations framework (hybrid monorepo). Components are organized by hospital department: clinician (AI-assisted sysadmin), emergency-room (panic-safe intake), hardware-crash-team (hardware diagnostics), observatory (metrics/monitoring), and more.

Data flows: ER intake → Evidence Envelope → Procedure Plan → Receipt → System Weather.

Prerequisites

Tool	Minimum Version	Install
Rust / Cargo	>= 1.80 (nightly recommended)	asdf install rust nightly or https://rustup.rs
Elixir / Mix	>= 1.16	asdf install elixir latest
Erlang/OTP	>= 26	asdf install erlang latest
V (vlang)	>= 0.4.4	asdf install vlang latest (for emergency-room)
Deno	>= 2.0	curl -fsSL https://deno.land/install.sh | sh (for contract tests)
just	>= 1.25	cargo install just

Verify all tools:

just doctor

Clone and First Build

cd ~/Documents/hyperpolymath-repos
git clone https://github.com/hyperpolymath/ambientops.git
cd ambientops

Build everything (Rust workspace + Elixir components):

just build-all

First Run: Hardware Scan

The hardware-crash-team scanner is the most immediately useful tool:

just scan

With JSON output:

cargo run -p hardware-crash-team -- scan --format json

With SARIF output (for CI integration):

cargo run -p hardware-crash-team -- scan --format sarif

Run Tests

All components (Rust + Elixir + contracts):

just test-all

Individual component tests:

just test-rust          # Rust workspace (clinician, hardware-crash-team, contracts-rust)
just test-elixir        # Observatory + referrals
just test-contracts     # JSON schema validation (Deno)

Clinician Feature Gates

The clinician crate uses optional features to keep default builds fast:

cargo build -p ambientops-clinician                     # Default (no features, fast)
cargo build -p ambientops-clinician --features ai       # Enable ollama-rs
cargo build -p ambientops-clinician --features storage  # Enable ArangoDB
cargo build -p ambientops-clinician --features p2p      # Enable libp2p gossipsub
cargo build -p ambientops-clinician --all-features      # Everything

End-to-End Demo

just demo

Runs the scripted demo flow with build step.

Guided Tour

just tour

Troubleshooting

just doctor   # Diagnose missing tools
just heal     # Attempt automatic repair

Project Structure (Key Paths)

clinician/             Rust AI-assisted sysadmin (~4400 LOC)
emergency-room/        zig panic-safe intake (~1800 LOC)
hardware-crash-team/   Rust hardware diagnostics (~700 LOC)
observatory/           Elixir metrics and monitoring (~600 LOC)
contracts/             JSON schemas + Deno tests
contracts-rust/        Rust serde types for contracts
records/referrals/     Elixir multi-platform bug reporting
composer/              Orchestration (stubs)
Cargo.toml             Rust workspace root

Further Reading

• hardware-crash-team/.claude/CLAUDE.md — Hardware diagnostic tool details

• 0-AI-MANIFEST.a2ml — Machine-readable project manifest

• docs/SCM-FILES-GUIDE.adoc — Checkpoint file format