BUILD.md

@@ -559,9 +559,17 @@ 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`. Python package-flavored extras such as
-  Pillow stay out of pkg lists until FreeBSD quarterly publishes Python 3.12
-  flavors.
+  `7-zip`, `python312`, `dejavu`.
+
+  **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.
+
 - **Xorg base:** `xorg-minimal`, `xkeyboard-config`, `xkbcomp`,
   `xf86-input-libinput`, `xf86-video-scfb`, `xf86-video-intel`,
   `xf86-video-amdgpu`, `xf86-video-ati`, `drm-kmod`,

build.sh

@@ -1267,10 +1267,11 @@ configure_live_operator_session() {
         chmod 0644 "${MOUNT_POINT}/etc/resolv.conf"
     fi
 
-    # FreeBSD packages ship pythonX.Y (e.g. python3.12) but not a bare python3
-    # symlink. Scripts that use /usr/bin/env python3 break without this.
-    # Derive the installed minor version so a future bump (3.12 -> 3.13) needs
-    # only a package-list change, never an edit here.
+    # 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.
     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)

live/operator-session/bootstrap.html

@@ -97,7 +97,7 @@
           <li><code>pi</code> coding agent harness (npm global)</li>
           <li>DeepSeek prefix caching (~3,500 free tokens per request)</li>
           <li>FreeBSD <code>mac_do</code> for kernel-enforced privilege escalation</li>
-          <li>Python 3.12 with <code>python</code> + <code>python3</code> symlinks</li>
+          <li>Python 3.12 (application default; 3.11 present as system-package dep)</li>
         </ul>
       </div>
 

packages/pkg-list-host.txt

@@ -14,6 +14,9 @@ bsddialog
 codex
 
 # Python / tooling
+# python312 is our application Python. FreeBSD's pkg repos default to
+# Python 3.11, so system deps (git, libinput, etc.) pull python311
+# autonomously. Both versions coexist; python312 owns the python3 symlink.
 python312
 just
 uv

packages/pkg-list-jails.txt

@@ -11,6 +11,8 @@ rsync
 curl
 
 # agent-jail (Colibri agent-jail-bootstrap.sh baseline)
+# python312 is our application Python. System deps (npm-node24 etc.) pull
+# python311 as a transitive dependency from FreeBSD's default PYTHON=3.11.
 python312
 node24
 npm-node24