From 579a8ccd74d203c39b31cd108f56b443b86de03c Mon Sep 17 00:00:00 2001
From: Sam & Claude <samo.blatnik@gmail.com>
Date: Sun, 14 Jun 2026 12:27:17 +0200
Subject: [PATCH] build: document Go+Rust build-host toolchains +
 toolchain-aware preflight

Go (builds the zot agent) and Rust (builds the Colibri release binaries) are
required on the build host to produce the binaries build.sh stages, but were
undocumented. Add them to REQUIREMENTS.md (build-host only, not the image), and
make the binary-missing preflights note when the matching toolchain (go/cargo)
isn't installed so that case surfaces up front instead of later.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 REQUIREMENTS.md | 8 +++++++-
 build.sh        | 4 ++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md
index c269a632..650ed9ac 100644
--- a/REQUIREMENTS.md
+++ b/REQUIREMENTS.md
@@ -33,9 +33,15 @@ Before booting/testing:
 Install the baseline tools:
 
 ```sh
-sudo pkg install -y curl node24 npm-node24 sudo
+sudo pkg install -y curl node24 npm-node24 sudo go rust
 ```
 
+`go` and `rust` are build-host toolchains, not image packages: `go` builds the
+zot agent binary and `rust` builds the Colibri release binaries. `build.sh`
+stages those prebuilt binaries (it does not compile them itself) and fails
+preflight if they are missing — so build them on the host first. They are not
+installed onto the image.
+
 `build.sh` sets its own FreeBSD tool PATH:
 
 ```text
diff --git a/build.sh b/build.sh
index ed5e415a..84058fa1 100755
--- a/build.sh
+++ b/build.sh
@@ -340,6 +340,8 @@ preflight_colibri_artifacts() {
     for _colibri_bin in colibri-daemon colibri colibri-smoke-agent colibri-mcp; do
         if [ ! -x "${_resolved_colibri_artifact_dir}/${_colibri_bin}" ]; then
             echo "ERROR: Colibri release binary missing: ${_resolved_colibri_artifact_dir}/${_colibri_bin}"
+            command -v cargo >/dev/null 2>&1 || \
+                echo "       NOTE: rust toolchain not found on this host — install it: pkg install rust"
             echo "       Build first: (cd ${_resolved_colibri_repo} && cargo build --workspace --release)"
             echo "       Or set FEATURE_COLIBRI=NO to skip Colibri staging."
             exit 1
@@ -372,6 +374,8 @@ preflight_zot_artifacts() {
     resolve_zot_paths
     if [ ! -x "${_resolved_zot_artifact_dir}/zot" ]; then
         echo "ERROR: Colibri agent binary missing: ${_resolved_zot_artifact_dir}/zot"
+        command -v go >/dev/null 2>&1 || \
+            echo "       NOTE: go toolchain not found on this host — install it: pkg install go"
         echo "       The agent has no FreeBSD release — build it first:"
         echo "       (cd ${_resolved_zot_repo} && git checkout ${ZOT_VERSION:-v0.2.29} && \\"
         echo "          GOOS=freebsd GOARCH=amd64 go build -trimpath -o bin/zot ./cmd/zot)"