docs(toolchain): record clean Python 3.12 FreeBSD baseline (Sam & Pi)

docs/TOOLCHAIN.md

@@ -11,8 +11,8 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
 ## Baseline versions
 
 | Tool       | Standard            | Linux (Debian/Ubuntu) | FreeBSD 15 (pkg)        | Manager / source                 |
-| ----------- | ------------------ | ---------------------------- | ----------------------- | --------------------------------- |
+| ---------- | ------------------- | --------------------- | ----------------------- | -------------------------------- |
-| **Python**  | **3.12** (floor)   | `python3.12`                 | `python312` + `py312-*` | system pkg + **uv** for venvs     |
+| **Python** | **3.12** (floor)    | `python3.12`          | `python312`             | system pkg + **uv** for venvs    |
 | **uv**     | ≥ 0.11              | `uv` (astral)         | `uv` (pkg) — confirm    | standalone binary                |
 | **Node**   | **24 LTS** (target) | `node` 24             | `node24` + `npm-node24` | LTS only; never a non-LTS major  |
 | **Rust**   | stable (pinned)     | rustup `stable`       | `rust` (pkg)            | `rust-toolchain.toml` per repo   |
@@ -23,6 +23,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
 ## Conventions
 
 ### Python — never pin the version in a shebang
+
 - Scripts use `#!/usr/bin/env python3`. **No `python3.11` / `python3.12` shebangs.**
 - The interpreter is selected by a **symlink provided at image/host setup time**, so a
   future bump (3.12 → 3.13) is a one-line change in one place, not a sweep across scripts.
@@ -30,9 +31,10 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
   `python3`):
   ```sh
   # in clawdie-iso build.sh, version-agnostic:
-  PYVER=3.12   # single source of truth for the bump
+  py_bin=$(ls "${MOUNT_POINT}/usr/local/bin"/python3.* 2>/dev/null \
-  ln -sf "python${PYVER}" "${MOUNT_POINT}/usr/local/bin/python3"
+    | sed 's@.*/@@' | grep -E '^python3\.[0-9]+$' | sort -V | tail -1)
-  ln -sf "python${PYVER}" "${MOUNT_POINT}/usr/local/bin/python"
+  ln -sf "${py_bin}" "${MOUNT_POINT}/usr/local/bin/python3"
+  ln -sf "${py_bin}" "${MOUNT_POINT}/usr/local/bin/python"
   ```
 - venv creation calls `python3 -m venv` (resolves via the symlink) — **not** `python3.12 -m venv`.
 - **uv is the standard venv/dependency manager** across all OSes. Prefer `uv venv` / `uv pip`
@@ -40,6 +42,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
   uv itself is interpreter-agnostic and picks up whatever `python3` resolves to.
 
 ### Node — LTS only, one major across the matrix
+
 - Standard target: **Node 24 LTS** (FreeBSD already ships `node24`; npm 11).
 - **Open divergence to resolve:** debby's Hermes Docker image deliberately pins **Node 22
   LTS** (Debian trixie's bundled 20.x is EOL). FreeBSD is on **24**. These must converge.
@@ -49,6 +52,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
   agreed LTS. Never run a non-LTS Node major in production.
 
 ### Rust / Go / Zig
+
 - Rust: pin per-repo with `rust-toolchain.toml` (channel `stable`) so FreeBSD pkg `rust`
   and Linux rustup resolve the same toolchain. TLS via rustls (no openssl-sys) for the
   `x86_64-unknown-freebsd` Tier-2 target.
@@ -56,6 +60,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
 - Zig pinned at 0.15.2 (herdr); bump deliberately.
 
 ### Managed tools (tmux, codex, pi, zot, …)
+
 - These are agent/utility tools, not language runtimes. Track latest stable from the
   platform package manager; record notable pins here when they matter.
 - Pi is being retired (see consolidation on zot + Colibri). Codex stays (osa, ISO builds).
@@ -69,13 +74,13 @@ Consensus of operator + Hermes + Claude. Standardize on **Python 3.12 floor** ev
   drifting (debby Docker 3.13, domedog 3.12, OSA 3.11).
 - **No code blocker:** `hermes-bsd/pyproject.toml` already allows `>=3.11,<3.14`; Hermes
   scripts use `env python3`.
-- **Work remaining is FreeBSD packaging in `clawdie-iso`:** `python311 → python312`,
+- **FreeBSD packaging reality:** OSA's FreeBSD quarterly repo publishes `python312`, but
-  `py311-* → py312-*` in `packages/pkg-list-*.txt`; version-agnostic symlink in `build.sh`;
+  not the matching `py312-aider_chat`, `py312-pillow`, `py312-pip`, or `py312-pygobject`
-  `python3 -m venv` (not `python3.11`) in `firstboot/shell-deploy.sh`; `PYTHON_VERSION` in
+  flavors yet. Keep Python package-flavored extras out of `pkg-list-*.txt` until they
-  `setup-hermes.sh`; `BUILD.md` docs.
+  exist; install those tools into explicit Python 3.12 venvs with uv/pip when needed.
-- **Gate before flipping the ISO:** confirm FreeBSD pkg coverage on OSA —
+- **ISO direction:** `clawdie-iso` should carry `python312`, version-agnostic `python3`
-  `pkg search '^py312-aider_chat' '^py312-pygobject'` (gnumeric dep). Common modules
+  symlinks in `build.sh`, and `python3 -m venv` calls. Drop packages such as `gnumeric`
-  (pillow/pip) are safe; hold any module that lacks a py312 flavor.
+  when they keep the old Python flavor alive transitively.
 
 _See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md)
 for per-host hardware facts._

skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md

@@ -19,30 +19,20 @@ python: >=3.10
 
 PyPI provides source distributions, but no FreeBSD wheels were observed for `graphifyy` or key compiled deps. FreeBSD will likely build some dependencies from source unless FreeBSD packages cover them.
 
-FreeBSD 14 amd64 quarterly packages observed available:
+FreeBSD 15 amd64 quarterly packages observed available for the clean Python
+3.12 baseline:
 
 ```text
-python311
+python312
-py311-pip
 uv
-py311-uv
-py311-numpy
-py311-scipy
-py311-rapidfuzz
-py311-networkx
-py311-tree-sitter
-py311-tree-sitter-python
-py311-tree-sitter-javascript
-py311-tree-sitter-go
-py311-tree-sitter-bash
 ```
 
-Not observed as FreeBSD packages in that check:
+Not observed as Python 3.12 FreeBSD packages in that check:
 
 ```text
 graphifyy
-py311-datasketch
+Python package-flavored graph dependencies such as datasketch, numpy, scipy,
-many tree-sitter grammar packages used by graphifyy, including typescript, rust, java, c, cpp, ruby, c-sharp, kotlin, scala, php, swift, lua, zig, powershell, elixir, objc, julia, verilog, fortran, json
+rapidfuzz, networkx, and tree-sitter grammar packages
 ```
 
 ## Integration rule
@@ -56,8 +46,8 @@ Run on the target FreeBSD builder/host from a clean repo checkout:
 ```sh
 mkdir -p tmp/graphify-test
 export TMPDIR="$(pwd)/tmp/graphify-test"
-pkg install -y python311 py311-pip uv git cmake ninja py311-numpy py311-scipy py311-rapidfuzz py311-networkx
+pkg install -y python312 uv git cmake ninja
-uvx --from graphifyy graphify --help
+uvx --python 3.12 --from graphifyy graphify --help
 ```
 
 Small extraction first: