BUILD.md

@@ -559,16 +559,13 @@ Listed for completeness so the lean/full split stays honest:
   `FreeBSD-fwget`.
 - **Jails:** `bastille`.
 - **Operator diagnostics:** `tmux`, `screen`, `mc`, `zip`, `unzip`,
-  `7-zip`, `python312`, `dejavu`.
+  `7-zip`, `python312`, `dejavu`, `py311-pillow`.
 
-  **Python version coexistence:** FreeBSD's official package repos build
-  against Python 3.11 (`PYTHON_DEFAULT=3.11`), so system packages
-  (`git`, `libinput`, `npm-node24` and others) pull `python311` as a
-  transitive dependency. We explicitly install `python312` as the
-  **application Python** — it becomes the `python3`/`python` symlink
-  target and the version used by venvs, scripts, and operator tooling.
-  Both versions coexist on the ISO; the disk overhead (~80 MB) is
-  accepted in favor of Python 3.12 future-readiness.
+  **Python:** `python3` is **3.11** (FreeBSD's `PYTHON_DEFAULT`). `python312`
+  is also installed and available as `python3.12` for anything that needs
+  newer. The image-render / screenshot skill uses `py311-pillow` (works on
+  `python3`); `clawdie-join-hive.sh` advertises `image-render` when Pillow
+  imports and `screenshot` when a display is present.
 
 - **Xorg base:** `xorg-minimal`, `xkeyboard-config`, `xkbcomp`,
   `xf86-input-libinput`, `xf86-video-scfb`, `xf86-video-intel`,

build.sh

@@ -1267,14 +1267,16 @@ configure_live_operator_session() {
         chmod 0644 "${MOUNT_POINT}/etc/resolv.conf"
     fi
 
-    # FreeBSD packages ship pythonX.Y but not a bare python3 symlink.
-    # Scripts using /usr/bin/env python3 break without this. System deps
-    # pull python311 (FreeBSD default), we install python312 explicitly.
-    # sort -V picks the highest installed version (3.12 > 3.11), so
-    # python312 always wins the symlink — no hardcoded version here.
+    # python3 → 3.11 (FreeBSD's PYTHON_DEFAULT — don't fight it). python312 is
+    # also installed and stays available as python3.12 for anything needing newer.
+    # FreeBSD ships no bare python3 symlink; scripts use /usr/bin/env python3.
     if [ ! -e "${MOUNT_POINT}/usr/local/bin/python3" ]; then
-        py_bin=$(ls "${MOUNT_POINT}/usr/local/bin"/python3.* 2>/dev/null \
-            | sed 's@.*/@@' | grep -E '^python3\.[0-9]+$' | sort -V | tail -1)
+        if [ -x "${MOUNT_POINT}/usr/local/bin/python3.11" ]; then
+            py_bin=python3.11
+        else
+            py_bin=$(ls "${MOUNT_POINT}/usr/local/bin"/python3.* 2>/dev/null \
+                | sed 's@.*/@@' | grep -E '^python3\.[0-9]+$' | sort -V | head -1)
+        fi
         if [ -n "${py_bin}" ]; then
             ln -sf "${py_bin}" "${MOUNT_POINT}/usr/local/bin/python3"
             ln -sf "${py_bin}" "${MOUNT_POINT}/usr/local/bin/python"

live/operator-session/clawdie-join-hive.sh

@@ -89,6 +89,13 @@ if have tailscale && tailscale status >/dev/null 2>&1; then
 fi
 [ "$OS" = "freebsd" ] && CAPS="$CAPS,rc.d,jail,zfs"
 
+# image-render when Pillow imports (py311-pillow on python3=3.11); screenshot
+# also needs a live display (the XFCE session).
+if python3 -c 'import PIL' >/dev/null 2>&1; then
+    CAPS="$CAPS,image-render"
+    [ -n "${DISPLAY:-}" ] && CAPS="$CAPS,screenshot"
+fi
+
 if have python3; then
     CAPS_JSON=$(printf '%s' "$CAPS" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read().strip().split(",")))' 2>/dev/null)
 else

packages/pkg-list-live-operator.txt

@@ -67,6 +67,8 @@ unzip
 bitchx
 python312
 dejavu
+# py311-pillow: Pillow for the image-render / screenshot skill (python3 = 3.11).
+py311-pillow
 # Hardware introspection. FreeBSD base already provides pciconf(8),
 # usbconfig(8), devinfo(8), and kldstat(8); add a few extra probes that
 # complement those native tools on the live USB.