From 0bb2f8f260beb4d6fb1ea87f4a94ea95485f6406 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 10:12:29 +0200 Subject: [PATCH] docs: flip to python3=3.11 default (3.12 available); trim the pillow noise MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per operator decision: stop fighting FreeBSD's PYTHON_DEFAULT=3.11 — python3 is 3.11 everywhere, python3.12 stays available for apps needing newer. This makes Pillow trivial (py311-pillow imports on python3), so the prior "3.12 floor + py312-pillow absent + run on 3.11 explicitly" explanation collapses. - TOOLCHAIN.md: table row + decision section flipped to 3.11-default and cut to a few lines (supersedes the 17.jun.2026 "3.12 floor" decision); symlink note now says build.sh points python3 at 3.11. - CAPABILITY-ROUTING.md: trimmed the osa line + worked example — image-render via py311-pillow on python3, no version gymnastics. - HOST-MATRIX.md: trimmed the operator-image image-render/screenshot note. prettier + layered_soul validate clean. Dates in edited blocks use EU format. Co-Authored-By: Claude Opus 4.8 --- docs/CAPABILITY-ROUTING.md | 25 +++++-------- docs/HOST-MATRIX.md | 7 ++-- docs/TOOLCHAIN.md | 72 +++++++++++++------------------------- 3 files changed, 37 insertions(+), 67 deletions(-) diff --git a/docs/CAPABILITY-ROUTING.md b/docs/CAPABILITY-ROUTING.md index 438ef6a..a2ebf75 100644 --- a/docs/CAPABILITY-ROUTING.md +++ b/docs/CAPABILITY-ROUTING.md @@ -65,28 +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` **today**. Not because Pillow is unavailable: - the blocker was that the `py312-pillow` flavor isn't in the quarterly repo. The prebuilt - **`py311-pillow`** _is_ available (FreeBSD's pkg default is 3.11, present transitively — - clawdie-iso #84), so `image-render` can be restored on FreeBSD by adding `py311-pillow` and - running it on 3.11. (`screenshot` additionally needs a display — see the worked example.) + `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 ships no `py312-pillow` flavor in the quarterly repo, but the default-flavor - `py311-pillow` is prebuilt and `python311` is already present (clawdie-iso #84). The - **operator image now ships it** (clawdie-iso #85): `clawdie-join-hive.sh` advertises - `image-render` (Pillow on 3.11) and `screenshot` when a display is present. So the XFCE - operator image qualifies for both; headless osa would get `image-render` only (no display, - and `py311-pillow` not added there yet). +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. Both **domedog** (Linux, `image-render`/`ffmpeg`) and the **FreeBSD operator image** - (`image-render` + `screenshot` via `py311-pillow`, clawdie-iso #85) now advertise these. - `screenshot` additionally needs a display, so a _headless_ host (domedog, osa) 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 +3. Both **domedog** (Linux) and the **FreeBSD operator image** advertise `image-render`. + `screenshot` also needs a display, so a _headless_ host (domedog, osa) does not qualify — + the operator image, with its XFCE session, does. +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. diff --git a/docs/HOST-MATRIX.md b/docs/HOST-MATRIX.md index b0525bb..de63bfd 100644 --- a/docs/HOST-MATRIX.md +++ b/docs/HOST-MATRIX.md @@ -161,10 +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). - In the always-on fleet `image-render`/`ffmpeg` are domedog-only (osa is a headless - server with no `py312-pillow`). The **FreeBSD operator image** (live USB, XFCE) now - also advertises `image-render` **and** `screenshot` via prebuilt `py311-pillow` on - python 3.11 (clawdie-iso #85) — it has a display, so screenshots work there. + 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 diff --git a/docs/TOOLCHAIN.md b/docs/TOOLCHAIN.md index 5788d62..f340dda 100644 --- a/docs/TOOLCHAIN.md +++ b/docs/TOOLCHAIN.md @@ -10,36 +10,27 @@ 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` (app) + `python311` (pkg default, transitive); `py311-*` flavors prebuilt, `py312-*` absent in quarterly | 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) | -| **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) | -| **tmux** | latest stable | `tmux` | `tmux` | system pkg | +| Tool | Standard | Linux (Debian/Ubuntu) | FreeBSD 15 (pkg) | Manager / source | +| ---------- | ------------------- | ------------------------ | -------------------------------------------------------------------- | -------------------------------- | +| **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) | +| **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) | +| **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: - 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. +- Scripts use `#!/usr/bin/env python3`. **No version-pinned shebangs.** The interpreter is a + symlink set once at image/host setup, so a version change is one edit, not a sweep. +- FreeBSD ships no bare `python3`; `clawdie-iso build.sh` points it at **3.11** (prefers + `python3.11`, else the lowest installed). +- venv creation calls `python3 -m venv` (resolves via the symlink) — never a pinned version. +- **uv is the standard venv/dependency manager** across all OSes (`uv venv` / `uv pip` / + `uv sync`); it picks up whatever `python3` resolves to. ### Node — LTS only, one major across the matrix @@ -64,30 +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 - (`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`. -- **FreeBSD 3.11/3.12 coexistence (clawdie-iso #84):** FreeBSD's `PYTHON_DEFAULT` is **3.11**, - so system pkgs (git, libinput, npm-node24, …) pull `python311` transitively. `python312` is - the **application** Python and wins the `python3` symlink via `sort -V`. Both coexist - intentionally — "3.12 floor" is the floor for _our_ code, not a ban on the 3.11 the base - drags in. -- **FreeBSD packaging reality:** OSA's quarterly repo publishes `python312`, but not the - matching `py312-aider_chat`, `py312-pillow`, `py312-pip`, or `py312-pygobject` flavors yet — - only the **default-flavor `py311-*`** are prebuilt. Keep `py312-*` extras out of - `pkg-list-*.txt` until they exist; install those into explicit 3.12 venvs with uv/pip when - needed. **Exception worth noting:** for Pillow, the prebuilt `py311-pillow` is available, so - `image-render` can run on the already-present 3.11 instead of compiling Pillow into a 3.12 - venv (see [`CAPABILITY-ROUTING.md`](./CAPABILITY-ROUTING.md)). -- **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. +FreeBSD package flavors are the default `py311-*` (e.g. `py311-pillow` → `image-render`); +`py312-*` aren't in the quarterly repo, so keep them out of `pkg-list-*.txt`. + +Supersedes the 17.jun.2026 "3.12 floor" decision — 3.11 is what the base ships and nothing we +run requires 3.12. _See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md) for per-host hardware facts._