Merge pull request 'docs: python3=3.11 default (3.12 available) + image-render on FreeBSD' (#10) from docs/python-coexistence-pillow into main

docs/CAPABILITY-ROUTING.md

@@ -44,14 +44,14 @@ Implemented 2026-06-19 (colibri PR #83), using the `socat`-over-Tailscale approa
 ## [LIVE] Capability vocabulary (initial)
 
 | Piece                 | Status                                         | Action                         |
-| ----- | ------ | ------ |
+| --------------------- | ---------------------------------------------- | ------------------------------ |
 | Capability vocabulary | tags are free-form (`rust`, `python`, `linux`) | Agree a shared tag set (below) |
 
 Flat, explicit tags — the matcher does exact string comparison, no implied hierarchy.
 Sourced from the probe and recorded per host in [`HOST-MATRIX.md`](./HOST-MATRIX.md).
 
 | Category  | Tags                                 |
-| -------- | ---- |
+| --------- | ------------------------------------ |
 | OS        | `linux`, `freebsd`                   |
 | Isolation | `docker`, `freebsd-jail`             |
 | Display   | `gui`, `screenshot`, `wayland`       |
@@ -65,18 +65,21 @@ Hosts advertise only what they truly have. Actual registered agents (2026-06-19)
   `image-render` — the media/compute lane. **No** `screenshot`/`gui` (headless VM), no `docker`.
 - **debby / hermes-debby (Linux):** `linux`, `docker`, `shell`, `gateway`, `hermes`, `tailscale`.
 - **osa / hermes-osa (FreeBSD):** `freebsd`, `shell`, `gateway`, `tailscale`, `rc.d`, `pf`,
-  `nginx`, `acme`, `hermes` — no `image-render` (Pillow dropped on FreeBSD).
+  `nginx`, `acme`, `hermes` — no `image-render` (headless server; `py311-pillow` not installed
+  there). The FreeBSD operator image enables it via `py311-pillow` (below).
 
 ## [DESIGN] Worked example: the tmux-screenshot skill
 
 This illustrates the routing flow (now runnable over the [LIVE] cross-host topology above):
 
-1. FreeBSD image drops Pillow — stays lean (`pkg-list` carries only `python312`).
+1. The FreeBSD operator image ships `py311-pillow` (clawdie-iso #85), so
+   `clawdie-join-hive.sh` advertises `image-render` (Pillow on `python3` = 3.11) and
+   `screenshot` when a display is present.
 2. The skill manifest declares `required_capabilities: ["image-render"]` (or `screenshot`).
-3. Only a Linux host advertises these — today **domedog** carries `image-render`/`ffmpeg`
+3. Both **domedog** (Linux) and the **FreeBSD operator image** advertise `image-render`.
-   (osa dropped Pillow). `screenshot` additionally needs a display, so a *headless* host
+   `screenshot` also needs a display, so a _headless_ host (domedog, osa) does not qualify —
-   does not qualify for it.
+   the operator image, with its XFCE session, does.
-4. Colibri routes the task to a matching host automatically — **proven 2026-06-19: an
+4. Colibri routes the task to a matching host automatically — **proven 19.jun.2026: an
    `image-render` task routed to domedog**; with no match it parks until a capable agent appears.
 
 The capability moved hosts. It was never lost.

docs/HOST-MATRIX.md

@@ -161,7 +161,9 @@ rows only.
 - **Colibri agent (joined central board 2026-06-19)** — the headless Linux media/compute lane:
   - **Capabilities advertised**: `linux`, `python3.12`, `rust`, `go`, `node`, `ffmpeg`,
     `image-render`. **Not** `screenshot`/`gui` (headless VM), not `docker` (absent).
-    `image-render`/`ffmpeg` are domedog-only in the fleet — osa dropped Pillow.
+    In the always-on fleet `image-render`/`ffmpeg` are domedog-only; the FreeBSD operator
+    image (live USB) also advertises `image-render` + `screenshot` via `py311-pillow`
+    (clawdie-iso #85).
   - **Reach**: client shim `colibri-shim.service` (system unit, `User=clawdija`,
     `Restart=always`, reboot-persistent) runs
     `socat UNIX-LISTEN:~/.colibri/colibri.sock → TCP ${OSA_TS_IP}:9190` (osa bridge over

docs/TOOLCHAIN.md

@@ -11,10 +11,10 @@ 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.13` (debby) — ≥ floor | `python312` + `py312-*` | system pkg + **uv** for venvs     |
+| **Python** | **3.11** (default)  | `python3.13` (debby)     | `python3` → 3.11; `python3.12` also installed for apps needing newer | system pkg + **uv** for venvs    |
 | **uv**     | ≥ 0.11              | `uv` 0.11.21             | `uv` (pkg) — confirm                                                 | standalone binary                |
-| **Node**    | **24 LTS** (target)| `fnm` → v24.16.0 (debby)     | `node24` + `npm-node24` | **fnm** (Rust, cross-platform)    |
+| **Node**   | **24 LTS** (target) | `fnm` → v24.16.0 (debby) | `node24` + `npm-node24`                                              | **fnm** (Rust, cross-platform)   |
 | **Rust**   | stable (pinned)     | rustup 1.95.0            | `rust` (pkg)                                                         | `rust-toolchain.toml` per repo   |
 | **Go**     | latest stable       | `go` 1.24.4 (debby)      | `go` (pkg)                                                           | only where a Go component exists |
 | **Zig**    | 0.15.2              | `~/.local/bin/zig`       | manual                                                               | pinned (herdr build dep)         |
@@ -24,22 +24,13 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
 
 ### Python — never pin the version in a shebang
 
-- Scripts use `#!/usr/bin/env python3`. **No `python3.11` / `python3.12` shebangs.**
+- Scripts use `#!/usr/bin/env python3`. **No version-pinned shebangs.** The interpreter is a
-- The interpreter is selected by a **symlink provided at image/host setup time**, so a
+  symlink set once at image/host setup, so a version change is one edit, not a sweep.
-  future bump (3.12 → 3.13) is a one-line change in one place, not a sweep across scripts.
+- FreeBSD ships no bare `python3`; `clawdie-iso build.sh` points it at **3.11** (prefers
-- **FreeBSD ISO build provides the symlink** (FreeBSD pkg ships `python3.12` but no bare
+  `python3.11`, else the lowest installed).
-  `python3`):
+- venv creation calls `python3 -m venv` (resolves via the symlink) — never a pinned version.
-  ```sh
+- **uv is the standard venv/dependency manager** across all OSes (`uv venv` / `uv pip` /
-  # in clawdie-iso build.sh, version-agnostic:
+  `uv sync`); it picks up whatever `python3` resolves to.
-  py_bin=$(ls "${MOUNT_POINT}/usr/local/bin"/python3.* 2>/dev/null \
-    | sed 's@.*/@@' | grep -E '^python3\.[0-9]+$' | sort -V | tail -1)
-  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`
-  / `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
 
@@ -64,22 +55,17 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe
   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)
+## Python — 3.11 default, 3.12 available (decision)
 
-Consensus of operator + Hermes + Claude. Standardize on **Python 3.12 floor** everywhere.
+`python3` is **3.11** on every host — FreeBSD's `PYTHON_DEFAULT`, so we don't fight it. 3.11
+has everything we use (`zoneinfo`, `match`/`case`, `tomllib`). **3.12 stays installed as
+`python3.12`** for anything that genuinely needs newer (call it explicitly or use a uv venv).
 
-- **Rationale:** available on Debian 13 and FreeBSD 15 via pkg; has needed stdlib
+FreeBSD package flavors are the default `py311-*` (e.g. `py311-pillow` → `image-render`);
-  (`zoneinfo`, `match`/`case`); avoids 3.13 bleeding-edge quirks. Unifies a stack that was
+`py312-*` aren't in the quarterly repo, so keep them out of `pkg-list-*.txt`.
-  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
+Supersedes the 17.jun.2026 "3.12 floor" decision — 3.11 is what the base ships and nothing we
-  scripts use `env python3`.
+run requires 3.12.
-- **FreeBSD packaging reality:** OSA's FreeBSD quarterly repo publishes `python312`, but
-  not the matching `py312-aider_chat`, `py312-pillow`, `py312-pip`, or `py312-pygobject`
-  flavors yet. Keep Python package-flavored extras out of `pkg-list-*.txt` until they
-  exist; install those tools into explicit Python 3.12 venvs with uv/pip when needed.
-- **ISO direction:** `clawdie-iso` should carry `python312`, version-agnostic `python3`
-  symlinks in `build.sh`, and `python3 -m venv` calls. Drop packages such as `gnumeric`
-  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._