docs: add cross-platform TOOLCHAIN baseline + Python 3.12 decision

Standardize toolchain across the matrix: Python 3.12 floor (no version-pinned
shebangs; ISO-time symlink python3->python3.N + uv for venvs), Node LTS
(flags debby Node22 vs FreeBSD node24 divergence to resolve), Rust/Go/Zig
and managed tools (tmux/codex/pi/zot) conventions.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/TOOLCHAIN.md

@@ -0,0 +1,81 @@
+# Toolchain Baseline (cross-platform)
+
+**Goal: the same frameworks and language runtimes across all hosts and OSes**, so an
+agent relocated between Linux and FreeBSD finds an identical toolchain. Version drift
+is a survivability bug — if debby and OSA disagree on Python or Node, a script that
+works on one can silently fail on the other.
+
+Probe before trusting this table — facts come from `scripts/verify_facts_probe.py
+--build-tools`, not memory. Update the row when you bump a host.
+
+## 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     |
+| **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    |
+| **Go**      | latest stable      | `golang`                     | `go` (pkg)              | only where a Go component exists  |
+| **Zig**     | 0.15.2             | `~/.local/bin/zig`           | manual                  | pinned (herdr build dep)          |
+| **tmux**    | latest stable      | `tmux`                       | `tmux`                  | system pkg                        |
+
+## 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.
+- **FreeBSD ISO build provides the symlink** (FreeBSD pkg ships `python3.12` but no bare
+  `python3`):
+  ```sh
+  # in clawdie-iso build.sh, version-agnostic:
+  PYVER=3.12   # single source of truth for the bump
+  ln -sf "python${PYVER}" "${MOUNT_POINT}/usr/local/bin/python3"
+  ln -sf "python${PYVER}" "${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`
+  / `uv sync` over raw `python -m venv` + `pip` so resolution and lockfiles match everywhere.
+  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.
+  Proposed resolution: bump the Hermes `node_source` stage `22 → 24` and retest the gateway
+  UI build. **Pending Hermes confirmation before flipping.**
+- `package.json` engines floor stays generous (`>=20`) but installed runtime tracks the
+  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.
+- Go: only where a Go component exists; track latest stable.
+- 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).
+
+## Python 3.12 standardization (decision, 2026-06-17)
+
+Consensus of operator + Hermes + Claude. Standardize on **Python 3.12 floor** everywhere.
+
+- **Rationale:** available on Debian 13 and FreeBSD 15 via pkg; has needed stdlib
+  (`zoneinfo`, `match`/`case`); avoids 3.13 bleeding-edge quirks. Unifies a stack that was
+  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`,
+  `py311-* → py312-*` in `packages/pkg-list-*.txt`; version-agnostic symlink in `build.sh`;
+  `python3 -m venv` (not `python3.11`) in `firstboot/shell-deploy.sh`; `PYTHON_VERSION` in
+  `setup-hermes.sh`; `BUILD.md` docs.
+- **Gate before flipping the ISO:** confirm FreeBSD pkg coverage on OSA —
+  `pkg search '^py312-aider_chat' '^py312-pygobject'` (gnumeric dep). Common modules
+  (pillow/pip) are safe; hold any module that lacks a py312 flavor.
+
+_See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md)
+for per-host hardware facts._