fix(build): unblock low-resource installs and release binaries (#1041)

* fix(build): unblock low-resource installs and release binaries

* fix(ci): use supported intel macOS runner label

docs/one-click-bootstrap.md

@@ -2,7 +2,7 @@
 
 This page defines the fastest supported path to install and initialize ZeroClaw.
 
-Last verified: **February 18, 2026**.
+Last verified: **February 20, 2026**.
 
 ## Option 0: Homebrew (macOS/Linuxbrew)
 
@@ -23,6 +23,31 @@ What it does by default:
 1. `cargo build --release --locked`
 2. `cargo install --path . --force --locked`
 
+### Resource preflight and pre-built flow
+
+Source builds typically require at least:
+
+- **2 GB RAM + swap**
+- **6 GB free disk**
+
+When resources are constrained, bootstrap now attempts a pre-built binary first.
+
+```bash
+./bootstrap.sh --prefer-prebuilt
+```
+
+To require binary-only installation and fail if no compatible release asset exists:
+
+```bash
+./bootstrap.sh --prebuilt-only
+```
+
+To bypass pre-built flow and force source compilation:
+
+```bash
+./bootstrap.sh --force-source-build
+```
+
 ## Dual-mode bootstrap
 
 Default behavior is **app-only** (build/install ZeroClaw) and expects existing Rust toolchain.
@@ -37,6 +62,9 @@ Notes:
 
 - `--install-system-deps` installs compiler/build prerequisites (may require `sudo`).
 - `--install-rust` installs Rust via `rustup` when missing.
+- `--prefer-prebuilt` tries release binary download first, then falls back to source build.
+- `--prebuilt-only` disables source fallback.
+- `--force-source-build` disables pre-built flow entirely.
 
 ## Option B: Remote one-liner
 

docs/troubleshooting.md

@@ -2,7 +2,7 @@
 
 This guide focuses on common setup/runtime failures and fast resolution paths.
 
-Last verified: **February 19, 2026**.
+Last verified: **February 20, 2026**.
 
 ## Installation / Bootstrap
 
@@ -32,6 +32,48 @@ Fix:
 ./bootstrap.sh --install-system-deps
 ```
 
+### Build fails on low-RAM / low-disk hosts
+
+Symptoms:
+
+- `cargo build --release` is killed (`signal: 9`, OOM killer, or `cannot allocate memory`)
+- Build crashes after adding swap because disk space runs out
+
+Why this happens:
+
+- Runtime memory (<5MB for common operations) is not the same as compile-time memory.
+- Full source build can require **2 GB RAM + swap** and **6+ GB free disk**.
+- Enabling swap on a tiny disk can avoid RAM OOM but still fail due to disk exhaustion.
+
+Preferred path for constrained machines:
+
+```bash
+./bootstrap.sh --prefer-prebuilt
+```
+
+Binary-only mode (no source fallback):
+
+```bash
+./bootstrap.sh --prebuilt-only
+```
+
+If you must compile from source on constrained hosts:
+
+1. Add swap only if you also have enough free disk for both swap + build output.
+1. Limit cargo parallelism:
+
+```bash
+CARGO_BUILD_JOBS=1 cargo build --release --locked
+```
+
+1. Reduce heavy features when Matrix is not required:
+
+```bash
+cargo build --release --locked --no-default-features --features hardware
+```
+
+1. Cross-compile on a stronger machine and copy the binary to the target host.
+
 ### Build is very slow or appears stuck
 
 Symptoms: