Merge pull request 'docs(build): OSA disk policy + corrected cleanup one-liner' (#87) from docs/build-host-disk-policy into main

BUILD.md

@@ -603,6 +603,40 @@ closure and hardware behavior.
 The build is intentionally cache-friendly. If in doubt before validation, run the
 full `sudo ./build.sh` once after pulling current `main`.
 
+### Build-host disk policy
+
+When OSA gets tight on disk, prefer deleting **repo-local build artifacts**
+(`tmp/packages`, `tmp/cache/work.img`, cached FreeBSD memstick images, old output
+artifacts) over pruning host packages.
+
+Do **not** treat the remaining host-side graphics/media stack as disposable "old
+X11". On OSA it is not a full desktop environment anymore; it is a shared runtime
+closure that supports current operator tooling and validation lanes:
+
+- `ffmpeg` + `py311-pillow` back the Hermes/image-render and screenshot path.
+- `gtk3`, `cairo`, `pango`, `fontconfig`, `libX11`, `mesa-*`, `wayland`,
+  `wlroots`, and related libs are shared by Codex-adjacent tooling, VNC/screenshot
+  helpers, media/rendering packages, and Python operator tools.
+- Dry-run package removal on OSA showed that reclaiming this subtree would remove
+  far more than a stale desktop: `Codex`, `ffmpeg`, `py311-pillow`, ImageMagick,
+  graphviz, aider-adjacent Python packages, and remote-display helpers all rode on
+  the same dependency closure.
+
+In practice: if you need gigabytes quickly, clear build caches first:
+
+    sudo rm -rf tmp/packages tmp/cache tmp/output
+
+These caches typically reclaim 3-8 GB. If host pkg pressure becomes chronic,
+that is a signal to move more build/package work onto
+`mother-build` (PLANNED — see docs/POUDRIERE-BUILD-SERVER.md), not to hollow
+out the FreeBSD operator host.
+
+Note: OSA's `/tmp` is a ZFS dataset separate from build caches. If shell
+commands fail with "No space left on device" during agent operations, clear
+`/tmp` independently:
+
+    sudo rm -rf /tmp/*
+
 ---
 
 ## Boot Flow Produced by the Image

docs/POUDRIERE-BUILD-SERVER.md

@@ -47,6 +47,13 @@ Benefits:
 - `pkg upgrade colibri` on deployed machines
 - No Rust toolchain needed on the ISO build host
 - Proper `pkg info colibri` metadata
+- Less pressure to treat the OSA ISO builder as disposable package scratch space.
+  OSA still needs a meaningful local operator/runtime toolkit (Codex, Hermes/image
+  helpers, media/rendering deps, VNC/screenshot helpers). In practice those pull a
+  shared GTK/X11/Wayland/media dependency closure. When disk gets tight, deleting
+  repo-local build caches is safer than trying to strip that host closure. A real
+  `mother-build` shifts bulky package-build churn off OSA instead of forcing the
+  builder host to choose between free space and capability.
 
 ## Memory split (reference sizing — ML350p 32 GB)
 
@@ -352,6 +359,16 @@ vm-bhyve
 **Critical path:** provision `mother-build` → write the colibri port → run the two
 scripts → stand up nginx/DNS. The host purchase is gated on the HOST-MATRIX cost rows.
 
+Why this matters operationally on OSA:
+
+- repo-local ISO artifacts (`tmp/packages`, sparse `work.img`, cached memsticks)
+  are the right things to delete under pressure
+- host GUI/media/runtime packages are not just "old desktop leftovers" anymore;
+  they are shared dependencies for Codex-adjacent tooling, Hermes/image helpers,
+  and remote-display/debug paths
+- pushing package-build churn to `mother-build` is the clean fix when OSA starts
+  trading free space against operator capability
+
 ## Notes
 
 - Rust target `x86_64-unknown-freebsd` stays — that's the compiler triple.