docs/FREEBSD-BUILD-LANE-HANDOFF.md

@@ -52,17 +52,24 @@ cargo build --workspace --release
 cargo test --workspace            # confirm green on real FreeBSD; report output
 cargo clippy --workspace --all-targets -- -D warnings
 
-# zot agent binary (Go) — see zot/README for the exact build target
+# zot agent binary (Go) — the agent has no FreeBSD release, so build it.
+# This is the exact command clawdie-iso's preflight prints; ZOT_VERSION
+# defaults to v0.2.29. Output must land at bin/zot (the ISO default artifact
+# path). Check out the tag you intend to ship: ISO_VERSION auto-tracks the
+# zot checkout via `git describe`, so the checked-out ref becomes the ISO
+# version.
 cd ../zot
-# build per zot's instructions; produces the static agent binary
+git checkout v0.2.29
+GOOS=freebsd GOARCH=amd64 go build -trimpath -o bin/zot ./cmd/zot
 ```
 
-After the cargo build, these must exist (the ISO preflight checks them):
+After both builds, these must exist (the ISO preflight checks each):
 
 ```sh
 ls -l colibri/target/release/colibri-daemon \
       colibri/target/release/colibri \
       colibri/target/release/colibri-smoke-agent
+ls -l zot/bin/zot
 # colibri-tui is optional (staged if present)
 ```
 
@@ -86,7 +93,11 @@ Useful overrides (defaults are fine for a standard run):
 - `COLIBRI_REPO=/path/to/colibri` if not at `../colibri`.
 - `COLIBRI_ARTIFACT_DIR=...` if binaries live outside `target/release`.
 - `COLIBRI_COST_MODE=smart|fast|max` (default `smart`).
-- `FEATURE_COLIBRI=NO` to skip Colibri staging (not for this lane).
+- `ZOT_REPO=/path/to/zot` if not at `../zot`; `ZOT_ARTIFACT_DIR=...` if the
+  binary is not at `<zot>/bin/zot`.
+- `COLIBRI_STAGE_AGENT=NO` to skip the zot agent (default `YES`, needs the
+  prebuilt `zot`); `FEATURE_COLIBRI=NO` to skip Colibri entirely (not for this
+  lane).
 
 Output image name encodes the zot version, e.g. `clawdie-quindecim-<ver>.img`.