From 940404d612ffaa1eaccd1973c5556b5817f02b23 Mon Sep 17 00:00:00 2001
From: Sam & Claude <hello@clawdie.si>
Date: Sun, 21 Jun 2026 09:36:28 +0200
Subject: [PATCH] docs: document Python 3.11/3.12 coexistence with FreeBSD
 defaults
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FreeBSD pkg repos build against PYTHON_DEFAULT=3.11, so system packages
(git, libinput, npm-node24) pull python311 as transitive deps. We keep
python312 as the application Python — it wins the python3 symlink via
sort -V. Document this in BUILD.md, build.sh, package lists, and
bootstrap.html so the dual-version reality is explicit and intentional.
---
 BUILD.md                             | 14 +++++++++++---
 build.sh                             |  9 +++++----
 live/operator-session/bootstrap.html |  2 +-
 packages/pkg-list-host.txt           |  3 +++
 packages/pkg-list-jails.txt          |  2 ++
 5 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/BUILD.md b/BUILD.md
index 65c60ef9..90017cff 100644
--- a/BUILD.md
+++ b/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`,
diff --git a/build.sh b/build.sh
index f832ab6c..51fc8c5c 100755
--- a/build.sh
+++ b/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)
diff --git a/live/operator-session/bootstrap.html b/live/operator-session/bootstrap.html
index 4c62eb56..abcdb47b 100644
--- a/live/operator-session/bootstrap.html
+++ b/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>
 
diff --git a/packages/pkg-list-host.txt b/packages/pkg-list-host.txt
index db970c38..ae4a7483 100644
--- a/packages/pkg-list-host.txt
+++ b/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
diff --git a/packages/pkg-list-jails.txt b/packages/pkg-list-jails.txt
index 32bcb6f6..ae437df3 100644
--- a/packages/pkg-list-jails.txt
+++ b/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