clawdie-iso/PLAN-OPERATOR-USB-NEXT.md

Plan: Operator USB — Next Round

Audience: Codex (FreeBSD agent), Claude (Linux agent), Operator (Sam) Author: Claude (Linux agent) — 20.may.2026

---

1. Where We Are

Live boot has cleared the "does it come up at all on real hardware" gate.

GPU vendor	Status	Notes
Intel iGPU	Working out of the box	KMS via clawdie-live-gpu pre-SDDM
AMD GPU	Working out of the box	Renoir / green-sardine firmware on live image; AMD GPU selection fix in 6485813
NVIDIA	Pending	Laptop candidate arriving; not validated yet

Load-bearing decision: keep SDDM as the live display manager. SDDM is the validated live display-manager path for Intel and AMD GUI boot. Retain SDDM until equivalent real-hardware proof validates any replacement. SDDM is now part of the operator-USB contract.

Other now-stable pieces from recent commits worth not regressing:

• clawdie-live-gpu (pre-SDDM rc.d service) — conservative KMS pick, NVIDIA gated on /boot/modules/nvidia.ko presence.
• Panel polish: xfce4-mixer runtime gate tests the audio backend (not process name); clipman runtime gate; cpugraph tuning; clock font (commits fceeb31, 82145b9, 40ea3e7, 70634ef).
• Live power policy hardened for USB-root laptops (b9290ab): powerdxx, C3 C-state default, hw.usb.no_suspend=1, and boot-time power_profile application; X blanking + DPMS disabled (0bc3514, ac9764e).
• Live agent CLI policy: ship codex, drop claude, keep pi only (c9955c6).

---

2. Scope for This Round

Five ISO tracks. Tracks A–C are the new work the operator called for. Track D is the refinement the operator flagged ("hardware detection pipeline even further"). Track E captures the "minor XFCE tweaks" bucket so it doesn't get lost. Track F is the Colibri-facing manifest surface around those ISO workflows, not a live-USB dependency.

Track A — Operator USB manual (highest immediate value)

Goal: when an operator boots the USB, they can read a short manual without needing network or external docs. Cover the live workflow only; disk install gets its own doc when it lands.

Deliverable: an HTML manual that opens from the desktop, alongside the existing bootstrap.html. Firefox is already on the live image, so HTML costs nothing extra. No new dependencies.

Sections, in operator-priority order:

1. What this USB is, what it isn't (one paragraph).
2. Network — bring up Wi-Fi via NetworkMgr; verify with ifconfig.
3. Tailscale — mdo -u root tailscale up; how to check status.
4. Operator CLIs — pi, codex; one example per.
5. GUI recovery — clawdie-gui is the stable command (per README, not clawdie-startx).
6. Power — what powerdxx is doing; how to check.
7. Diagnostics — btop, pciconf -lv, hw-probe, where the live GPU log lives (see Track D).
8. Disk install — placeholder section that says "coming next round" and points at where the wizard will live.

Implementation pointers:

• New file: live/operator-session/manual.html.
• Wire a desktop launcher: live/operator-session/clawdie-manual.desktop, installed by build.sh alongside clawdie-bootstrap.desktop.
• Optionally extend bootstrap.html with a "Read the manual" link rather than auto-opening two windows.
• Keep it static HTML + inline CSS. No JS, no build step.

Definition of done:

• Manual renders correctly in Firefox on a freshly-flashed USB.
• Desktop icon launches it.
• All commands in the manual were sanity-tested on the validated Intel + AMD live boots before merge.

Track B — Pkg list refinement + validation tests

Goal: turn packages/pkg-list-live-operator.txt from "what we tried" into "what we verified is load-bearing", with a repeatable validation hook so regressions are caught on the next build.

Steps:

1. Audit pass on the validated live boot. For each package in pkg-list-live-operator.txt, mark one of:
   • boot-critical (kernel/firmware/X/SDDM/networkmgr/etc.)
   • operator-workflow (firefox, codex, pi tools, tmux, ...)
   • diagnostic (btop, hw-probe, dmidecode, ...)
   • candidate-to-defer (used rarely or replaceable by a base tool) Write the result as comments next to each line; categorize first and defer removal to a follow-up round after the data is in.
2. Size accounting. For each line, add the pkg + flat size as a trailing comment (# 12M / 38M). Use pkg info -s <name> on the FreeBSD build host. This makes future "is X cheap to add" calls honest (see memory: feedback_pkg_cost_honesty.md).
3. Validation script. Add scripts/validate-live-image.sh. It runs against a freshly-flashed live USB (or the mounted image) and asserts:
   • SDDM is enabled in rc.conf.
   • clawdie-live-gpu rc.d service is enabled.
   • Required kmods present in /boot/modules for Intel/AMD; NVIDIA kmods are \textit{available in the offline repo} and remain unloaded unless explicitly configured.
   • Live operator pkg-list contents are actually installed in the image.
   • Panel module gates (xfce4-mixer, clipman) honor their runtime conditions (audio backend up, X session up).
   • Power: powerdxx_enable=YES, X blanking off.
4. Wire it into builds. build.sh calls the script after image assembly. Failure aborts the build with a clear message. This is the regression net for everything Track A through E touches.

Out of scope this round:

• Actually removing packages. Categorization + sizing only. We remove in a later round once the data is in.
• VSCode / Cursor. Stay off the live image — see project memory.

Track C — Disk deployment: USB → bare metal

Goal: deploy the Clawdie service from a booted operator USB onto bare FreeBSD hardware.

The clawdie binary (Rust, in crates/clawdie in Colibri) already does discover → plan → apply for ZFS layout + rc.d service + clawdie user. What's missing is the USB → disk workflow. Three strategies, ascending in automation:

Strategy C1: Direct CLI (validate now, ship immediately)

clawdie discover                    # see pools, confirm target
clawdie plan --pool tank            # review ZFS layout, datasets, rc.d
clawdie apply --pool tank --yes     # provision: datasets, user, rc.d service

What exists: discover, plan, and apply --yes are built and unit-tested. plan + dry-run apply validated on FreeBSD host (osa). Gap: apply --yes has not been run destructively on a scratch pool. Effort: 1 destructive test on a VM/scratch pool. Zero new code.

Strategy C2: Guided firstboot wizard

A /usr/local/sbin/clawdie-setup shell script (or firstboot hook):

1. Run clawdie discover, show available pools
2. Prompt: "Which pool?"
3. Show clawdie plan --pool <chosen> for review
4. Prompt: "Deploy? [y/N]"
5. Run clawdie apply --pool <chosen> --yes
6. Print success, point at service clawdie start

Effort: ~60 lines shell script + firstboot wiring. A day's work. Depends on: C1 validated first.

Strategy C3: Declarative config (repeatable, auto-deploy)

A /etc/clawdie/deploy.toml on the USB's FAT32 partition (editable from any OS before boot):

[host]
hostname = "clawdie-host"
pool = "tank"

[zfs]
raid = "mirror"
disks = ["da0", "da1"]   # only if creating a new pool

[services]
postgresql = true        # install + enable PostgreSQL + pgvector
bhyve = true             # install bhyve + vm-bhyve

Boot behavior:

• If /etc/clawdie/deploy.toml present → clawdie apply --config … runs on boot
• If absent → boots to desktop (operator USB mode)

Effort: Config schema + parser in clawdie crate (~120 lines Rust). Firstboot auto-detect (~15 lines shell). A week of work. Depends on: C1 validated first.

Definition of done:

• C1: apply --yes tested on scratch pool. FIRSTBOOT.md documents the CLI path.
• C2: clawdie-setup script exists, wired into firstboot, tested in bhyve.
• C3: deploy.toml schema defined, parser in clawdie, auto-detect on boot.

Track D — Hardware detection pipeline refinement

Goal: the operator should be able to read, after boot, why a given GPU/audio/network path was chosen. Today the choices are correct but silent.

Steps:

1. Persistent detection log. clawdie-live-gpu writes its decision to /var/log/clawdie-live-gpu.log with timestamp, detected PCI IDs, chosen kmod, and the reason (e.g., "i915kms because vendor=0x8086"). The manual (Track A) points at this file.
2. One-shot detection summary. A small helper, hw-report, that prints a friendly summary by reading the log plus pciconf -lv + webcamd status + ifconfig wlan state. Useful in issue reports.
3. NVIDIA branch selection placeholder. Stub a future clawdie-nvidia-select that, when an NVIDIA card shows up, picks between nvidia-driver-390 / 470 / 580 based on PCI ID. Ship as a no-op script with a TODO until the laptop arrives — concrete picks land in Track D-2 (next round) on real hardware.

Out of scope:

• Live Linuxulator probing — no operator workflow needs it on the USB.

Track E — XFCE minor tweaks bucket

Held open for the operator. Anything in this bucket should:

• Be cosmetic / behavioral, not architectural.
• Land as small commits with screenshots where visual.
• Not change the SDDM contract or the pre-SDDM detection flow.

If a "tweak" turns out to need either of those, lift it into Track D and discuss before merging.

Track F — Colibri: ISO workflow manifests and skills

Goal: make the ISO repo a clean producer and consumer of structured Colibri artifacts for build, publish, flash, mounted-image validation, and hardware-report workflows.

Colibri core protocol, runtime ingestion, watchdog consumption, Pi JSON event parsing, and cross-host aggregation live in clawdie-ai. The ISO repo owns the operator-USB workflow skills and the manifest shapes those workflows emit.

Colibri is the dashboard/control-plane contract for this track. It can display operator state and ingest workflow artifacts directly; no separate pane fabric is part of the FreeBSD/live-USB runtime dependency set.

Why this replaces the old glass-pane idea:

The old model was "watch a tmux pane and btop while a human copies state between agents." The new model is:

1. ISO skill runs an operator workflow.
2. The workflow writes a small JSON manifest and a human-readable summary.
3. Colibri ingests those artifacts through clawdie-ai.
4. Colibri dashboards may display the state, but the manifest is the source of truth.

This keeps terminal visibility while avoiding terminal scraping as the contract between agents.

Manifest surfaces:

Surface	Example skill / script	Schema target	Purpose
Build result	iso-build	clawdie.iso.build.v1	Commit, flags, log path, output files, static checks
Publish result	iso-publish	clawdie.iso.publish.v1	Public URLs, checksums, manifest path, symlink state
Flash verification	iso-flash-verify	clawdie.iso.flash.v1	Download, checksum, xz test, target disk fit, flash
Mounted validation	iso-validate-image	clawdie.iso.validation.v1	SDDM, CLIs, mdo, seed slice, no-blank, panel assets
Hardware report	iso-hardware-report-ingest	clawdie.iso.hardware.v1	GPU/KMS, GL renderer, input, audio, Wi-Fi, SDDM/XFCE
Package audit	iso-package-audit	clawdie.iso.package-audit.v1	Category, size, flat size, reason kept, deferral risk
Provider validation	pi-provider-check equivalent	clawdie.provider-smoke.result.v1	Pi JSONL events, provider/model identity, pass/fail

Key architectural decisions:

• ISO skills emit manifests; clawdie-ai/Colibri consumes and aggregates them.
• FreeBSD safety remains local: builds, mounts, flashes, watchdog checks, and privileged host actions are not delegated to a remote chat agent.
• Rely on Colibri as the sole control-plane surface for this track; add no separate dashboard/pane-fabric dependency to the live USB.
• Cross-host coordination starts with small JSON manifests and summaries; raw logs, screenshots, and pcaps move only on demand.
• Skills should be additive and runnable without an interactive dashboard. The same skill output should still be useful from git, tmux, or a plain shell.

Steps:

1. Document manifest conventions. Add an ISO-local note that names the schema ids, required fields, output paths under tmp/, and handoff expectations.
2. Expand skills gradually. Add iso-flash-verify, iso-validate-image, iso-hardware-report-ingest, and iso-package-audit as runbooks before adding automation.
3. Teach existing skills to reference manifests. iso-build and iso-publish should describe the JSON files they produce or expect, without changing the build path first.
4. Wire script output where low risk. Prefer small manifest writers that summarize already-known facts over new orchestration.
5. Ingest from clawdie-ai. Colibri reads the ISO manifests and turns them into activity/status updates for operators and agents.

Definition of done:

• ISO skills describe what manifest they emit or consume.
• Build/publish/flash/validation/hardware report workflows each have a stable JSON artifact path under repo-local tmp/.
• Colibri in clawdie-ai can read at least one ISO manifest and attach it to activity state.
• Hermes can flash from a published manifest without relying on terminal scrollback.
• FreeBSD live USB uses Colibri directly and carries no separate pane-fabric dependency.

Out of scope this round:

• Adding a separate dashboard/pane-fabric dependency to the FreeBSD live image.
• Replacing watchdog, hostd, tmux, or the existing build skills.
• Free-form agent-to-agent chat as the build/flash authority.
• Full workflow DAG orchestration.

---

2.1. AMD ASUS Evidence-Based Remediation Split

Source evidence: doc/AMD-ASUS-XFCE-LIVE-USB-FINDINGS.md Collection date: 25.maj.2026 Hardware: ASUS ZenBook UX325UA_UM325UA, AMD Ryzen 7 5700U, AMD Lucienne/Renoir graphics Status: hardware evidence collection is closed. The AMD ASUS report is now the canonical baseline; follow-up proof should go through TESTING.md, hw-report, and small commits rather than more handoff docs. Rule: static image inspection or bhyve is useful for build gates, but real hardware remains final proof for XFCE/session/input/audio behavior.

The AMD ASUS report proves the important baseline: the image boots to SDDM/XFCE on real AMD hardware with accelerated graphics, working USB Ethernet, exposed webcam devices, and no-blank power policy. Base fixes have landed for resolver bootstrap, internal audio preference, touchpad XInput guards, loader branding, hardware-report capture, public probe URL reporting, and the hw-probe upload dependency. The open work is now split into two follow-up lanes: pkg/tooling hygiene for Codex 5.4 and XFCE visual polish for Claude.

Order of work

1. Pi ISO Developer: base live OS/runtime fixes — committed; verify on the next rebuilt image.
2. Codex 5.4: package tooling and pkg repository hygiene remains open.
3. Claude: XFCE panel/icon/language/network visual polish remains open, after the base runtime is stable.
4. Codex ISO Builder / Operator validation: rebuild, flash, and retest on AMD ASUS hardware from the current branch head.

Pi ISO Developer — base OS/live-runtime fixes

These items are foundational and should land before cosmetic XFCE work.

1. Fix live DNS resolver handling

Evidence:

/etc/resolv.conf -> /tmp/bsdinstall_etc/resolv.conf
avahi-daemon[4436]: Failed to open /etc/resolv.conf: No such file or directory

Goal: after live boot and DHCP/network setup, /etc/resolv.conf must be a valid resolver file, not a dangling symlink to installer scratch state.

Likely areas:

build.sh
live/operator-session/*
firstboot/setup-import.sh
network setup hooks

Acceptance checks on live USB:

ls -l /etc/resolv.conf
cat /etc/resolv.conf
host code.smilepowered.org
ping -c 1 code.smilepowered.org

2. Touchpad base/input enablement and diagnostics

Evidence: the ASUE140A touchpad is detected by kernel, evdev, libinput, and Xorg, but the operator reports it does not move/click in XFCE.

hmt0: <ASUE140A:08 04F3:3134 TouchPad>
/dev/input/event8
XINPUT: Adding extended input device "ASUE140A:08 04F3:3134 TouchPad" (type: TOUCHPAD, id 13)

Goal: make the built-in touchpad usable, or capture enough first-class diagnostics to identify the exact failing layer.

Pi ISO Developer owns:

• Add missing touchpad diagnostics to hw-report.
• Verify whether the XInput device is disabled by property or XFCE pointer config.
• Add a minimal live-session sanity step only if evidence supports it.
• Prefer data-driven Xorg/libinput snippets over broad guesses.

Likely areas:

live/operator-session/hw-report
live/operator-session/clawdie-xfce-session
live/operator-session/clawdie-xfce-session-inner
live/operator-session/xprofile

Acceptance checks:

xinput list
xinput list-props "ASUE140A:08 04F3:3134 TouchPad"
xinput test "ASUE140A:08 04F3:3134 TouchPad"
xfconf-query -c pointers -lv
libinput debug-events --device /dev/input/event8

Final proof requires the operator to confirm that the touchpad moves and clicks on the AMD ASUS laptop.

3. Audio default selection

Evidence: HDMI is selected as the default audio device while the internal speaker exists.

pcm0: ATI R6xx (HDMI) default
pcm3: Realtek ALC294 Internal Analog Speaker
hw.snd.default_unit: 0

Panel mixer also points at HDMI:

sound-card="ATIR6xxHDMI"

Goal: prefer internal analog speaker/headphone output when present, and avoid pinning the base live session to HDMI by default.

Pi ISO Developer owns:

• Base FreeBSD default sound unit selection.
• Dynamic live-session selection if needed.
• Avoiding a hardcoded HDMI default.

Claude may later adjust: XFCE mixer plugin visual/config behavior after the base default is correct.

Acceptance checks:

cat /dev/sndstat
sysctl hw.snd.default_unit
mixer

Expected result on the AMD ASUS laptop: Realtek/internal speaker is the default when available.

4. Boot branding

Evidence:

loader_brand="install"
loader_menu_multi_user_prompt="Installer"

Goal: boot menu should identify the artifact as the Clawdie operator/live USB, not a generic installer.

Likely areas:

build.cfg
build.sh
boot/loader configuration templates

Acceptance: operator confirms the boot menu no longer says Installer for the live USB path.

5. Hardware report improvements

Add evidence commands that would have shortened the AMD diagnosis loop.

Add/capture:

ls -l /etc/resolv.conf
readlink /etc/resolv.conf
cat /etc/resolv.conf
xinput list
xinput list-props
xfconf-query -c pointers -lv
xrandr --query
xfconf-query -c xfce4-panel -lv
cat /dev/sndstat
sysctl hw.snd.default_unit

Goal: future hw-report output should directly expose DNS, pointer, display, panel, and audio state.

Codex 5.4 — pkg/package-tooling lane

Codex 5.4 should own package-manager consistency and repository hygiene. Keep this separate from base OS behavior and XFCE polish.

1. Resolve pkg DB/libpkg mismatch

Evidence:

pkg: warning: database version 38 is newer than libpkg(3) version 37, but still compatible

Goal: live image should not ship with a pkg database newer than the bundled/runtime libpkg expects.

Likely areas:

packages/pkg-list-*.txt
build.sh
skills/iso-build/SKILL.md
pkg bootstrap/cache logic

2. Fix or document pkg repository URL behavior

Evidence:

pkg version: pkg+https://... -- pkg+:// implies SRV mirror type

Goal: live repo config should avoid confusing warnings during ordinary diagnostics.

3. Make pkg audit behavior intentional

Evidence:

pkg audit: vulnxml file vuln.xml does not exist. Try running 'pkg audit -F' first

Decision needed: either preseed the vuln DB during build, or document that pkg audit -F requires network and should be run before pkg audit on a live USB.

Acceptance checks:

pkg -v
pkg version
pkg audit
pkg audit -F

Expected result: no unexpected DB/libpkg or repo URL warnings; audit behavior is either clean or clearly documented.

Claude — XFCE/panel polish lane

Claude should take this after the base OS/runtime items are underway or merged. This keeps cosmetic XFCE work from masking resolver, audio, or input issues.

1. Restore reliable panel icon rendering

Evidence: operator observed missing icons and dot placeholders on the panel.

Likely areas:

live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xfce4-panel.xml
live/operator-session/panel-skel/.config/xfce4/panel/launcher-2/firefox.desktop
live/operator-session/panel-skel/.config/xfce4/panel/launcher-3/pcmanfm.desktop
live/operator-session/panel-skel/.config/xfce4/panel/launcher-4/xfce4-terminal.desktop
live/operator-session/panel-skel/.config/xfce4/xfconf/xfce-perchannel-xml/xsettings.xml

Checks:

find ~/.config/xfce4/panel -maxdepth 4 -type f -print -exec cat {} \;
grep -R '^Icon=' ~/.config/xfce4/panel /usr/local/share/applications /usr/share/applications
ls /usr/local/share/icons /usr/share/icons

2. Restore Whisker/start button icon

Current config uses an absolute PNG path:

/usr/local/share/clawdie-iso/icons/clawdie-start.png

Observed result: start icon is missing.

Claude should verify whether the current XFCE/Whisker version accepts absolute PNG paths here or expects a theme icon name.

Checks:

ls -l /usr/local/share/clawdie-iso/icons/clawdie-start.png
file /usr/local/share/clawdie-iso/icons/clawdie-start.png
xfconf-query -c xfce4-panel -p /plugins/plugin-1 -lv

3. Fix language switcher display

Current XKB plugin config:

<property name="display-type" type="uint" value="1"/>
<property name="display-name" type="uint" value="0"/>

Observed result: it shows si / en, is too large, and does not show the desired compact flag/icon display.

Goal: compact flag/icon display, or another compact visual indicator accepted by the operator.

4. Reduce panel footprint

Current evidence:

panel size: 48
panel icon-size: 2
clock font: Noto Sans 14
cpugraph size: 36

Goal: smaller, cleaner panel that remains readable on 1920x1080 laptop displays and dual-display setups.

5. Improve network tray icon visibility

Current systray includes networkmgr, but the operator reports the network icon is barely visible.

Likely areas:

• icon theme selection,
• systray/legacy tray rendering,
• dark translucent panel contrast,
• panel icon sizing.

Validation after each cluster

After each owner lands a cluster, Codex ISO Builder or the operator should rebuild/flash and collect a short validation note. At minimum:

hw-report
ls -l /etc/resolv.conf
cat /etc/resolv.conf
xinput list
cat /dev/sndstat
sysctl hw.snd.default_unit
xrandr --query
xfconf-query -c xfce4-panel -lv
pkg version
pkg audit

Real-hardware acceptance should be recorded against doc/AMD-ASUS-XFCE-LIVE-USB-FINDINGS.md or a follow-up report, not inferred from a VM.

---

2.2. Live Self-Debug Code Checkout Seed

Operator request — 01.jun.2026 AMD live session: the next rebuilt operator USB should prepopulate the live clawdie home with the relevant source trees so the operator can start a local pi session from XFCE, log in with a provider, and let that agent inspect the live system and the shipped source side by side.

Goal: make the live USB self-debuggable without first cloning repositories over a possibly flaky network.

Candidate layout: keep the source snapshots under one operator-facing folder so $HOME stays uncluttered:

/home/clawdie/ai/clawdie-iso
/home/clawdie/ai/clawdie-ai
/home/clawdie/ai/colibri

Implementation notes:

• Seed clean checkouts or source snapshots only; include only code and exclude API keys, .env files, SSH private keys, build caches, package caches, tmp/, and other private host state.
• Prefer the exact branch/commit used by the image build, recorded in /usr/local/share/clawdie-iso/build-manifest.json and visible from hw-report.
• The snapshots should be owned by clawdie:clawdie and readable/writable from XFCE terminals.
• Keep provider authentication manual. The image may include code, but it must not bake provider credentials.
• If full .git history is too large, use shallow clones or archive snapshots plus a small manifest that records remote URL, branch, commit, and modified state.
• This is a live-debug aid, not a build-host replacement: Linux agents direct build commands to Codex ISO Builder on the FreeBSD host, and real hardware proof remains operator/Codex-owned.

Why it matters: when Colibri, XFCE, rc.d, input, or package-list bugs only show up on real hardware, a local Pi session can read /var/log, hw-report, XFCE config, and the source tree in the same environment where the bug occurs. That shortens the loop between operator observations and source fixes.

---

3. Sequencing

Recommended order (each can be a separate PR / commit cluster):

1. Track A (manual) — low risk, immediate operator value, no build plumbing changes.
2. Track D-1, D-2 (detection log + hw-report) — small, supports the manual, helps NVIDIA debugging when the laptop arrives.
3. Track B (pkg-list audit + validation script) — biggest win for long-term hygiene; will surface inconsistencies the other tracks should respect.
4. Track C (disk-install plumbing) — new territory, isolated by profile flag; can be developed in parallel with B but ship after.
5. NVIDIA validation — gated entirely on the laptop arriving. Track D-3 stub lands first so the validation has somewhere to write to.

Track E (XFCE tweaks) can land anywhere it doesn't conflict.

6. Track F (Colibri) — define ISO manifest surfaces, add skills, then wire low-risk manifest writers/consumers. Independent of Tracks A–E; can proceed in parallel without adding a separate pane-fabric dependency to the live USB.

---

4. Agent Ownership

Per AGENTS.md, this round uses a git-coordinated implementation/review/build split:

Role definitions are canonical in AGENTS.md. This table only maps those roles to this round:

Role	Owns in this round
Pi ISO Developer	Primary source implementation: shell scripts, validation hooks, package-list mechanics, docs updates, static checks, commits and pushes.
Codex ISO Builder	Build + flash + validate on Intel and AMD after each build target lands. Runs mounted-image checks, the validation script, USB flashing, and NVIDIA validation when hardware arrives. Reports exact logs/output back through git or handoff notes.
Claude Reviewer / XFCE Tweaker	Reviews plans/diffs, identifies blind spots, owns Track E XFCE GUI tweaks, and reviews the ISO manifest surface for Colibri compatibility.
Opencode (z.ai-GLM4.7)	Owns Linux-side Colibri/dashboard experiments and the GLM-4.7/DeepSeek provider validation lanes. Reports results as manifests/summaries. GLM-4.7 transport already proven (this session runs on it); DeepSeek uses Sam's own key with --provider deepseek.
Pi + DeepSeek v4	Provider-lane validation target: prove pi --mode json works against DeepSeek v4 with Sam's DeepSeek API key, report provider/model identity, and hand exact command/output back before anyone treats the lane as production-ready.
Codex (FreeBSD endpoint)	Build/validate endpoint for ISO manifests: runs skills on FreeBSD, emits exact build/hardware results, and keeps watchdog/hostd as local safety boundaries.
Operator (Sam)	Final product direction, hardware purchases, hands-on acceptance, release/tag decisions, and NVIDIA/portable-workstation UX judgment.

Cross-agent handoff: use git as the shared control plane. Suggestion commits are welcome, but each build target should be re-fetched and checked before build. Any agent editing Markdown must run ./scripts/check-format.sh before pushing; format drift is a tooling failure, not a style debate. When a track needs USB flashing or real hardware proof, leave a brief note in doc/ (matching existing handoff convention) with the exact build + verify commands Codex ISO Builder should run.

Claude confirms (20.may.2026)

Received bd94b87 ("Clarify operator USB agent roles"). Confirmed understanding of the 4-role split and git coordination rules. Expanding my ownership from pure reviewer to Track E (XFCE GUI improvements) — this covers the panel/theming work we already did together (commits 70634ef, 82145b9, fceeb31) and continues with:

• Panel preseed XML adjustments (plugin order, sizing, properties)
• Launcher .desktop file tuning
• GTK / xfwm4 / icon / cursor theming (Greybird, Papirus, DMZ-White)
• Wallpaper and desktop background config
• Font sizing and rendering (Noto Sans, Hack)
• xkb layout display, clipboard manager, cpugraph/mixer panel plugins
• Any cosmetic or behavioral tweak that stays within XFCE config and does not touch the SDDM contract or the pre-SDDM GPU detection flow

Scope boundary: if a GUI tweak would require touching build.sh package lists, rc.d services, or SDDM config, it gets lifted to the relevant track and discussed first.

Note: the dated confirmation block below uses the original role name "Codex ISO developer". That role was later renamed to Pi ISO Developer (see AGENTS.md). Text preserved verbatim as a historical record.

Codex ISO developer confirms (20.may.2026)

Received bd94b87 ("Clarify operator USB agent roles"). Confirmed understanding of the 4-role split and git coordination rules.

I accept the Codex ISO developer role for this round:

• source implementation in this repo
• shell/script fixes
• package-list mechanics
• docs/static checks
• commits and pushes

I treat GUI success as proven only with Pi Builder / hardware output, and I start ISO builds or flash media only when explicitly assigned.

---

5. Explicitly Out of Scope This Round

• VSCode or Cursor on the live image. Both deferred per project memory. VSCode is a candidate for disk-install extras later, after Track B gives us a real size + dep budget.
• Replacing SDDM. Load-bearing; SDDM stays as-is for this round.
• KDE profile content. Track C only scaffolds the selector; KDE pkg list comes in a later round.
• Linuxulator integration of any kind.
• Tag / release work. The current round ends when Tracks A–D are merged and the validation script passes on Intel + AMD; tagging happens in a separate operator-driven step.

---

6. Risks & Watch Items

• Regression in panel runtime gates. Recent commits hardened these. Track B's validation script must assert they still behave correctly, or future package shuffles will silently break the panel again.
• Disk-install path drifting from live path. Track C introduces real divergence. Keep one source of truth for the pkg lists; profile selection picks which lists, not what's in them.
• NVIDIA-laptop surprises. The conservative pre-SDDM detection may not pick the right branch automatically. Track D-3 stub buys us a landing spot; budget time for iteration once the laptop is in hand.
• Manual rot. Track A's manual must reference stable commands (clawdie-gui, mdo -u root ...) rather than internal script names that may move. Review the manual against the README before each merge.

---

7. Done Criteria for This Round

• Operator can flash a freshly-built USB, boot on Intel or AMD, read a manual on the desktop, and follow it to a working Wi-Fi + Tailscale + pi session without consulting the repo.
• scripts/validate-live-image.sh runs in build.sh and passes.
• pkg-list-live-operator.txt has every line categorized and sized.
• Disk-install path has a profile selector and can install pkg-list-disk-install-extras.txt via firstboot — proven in bhyve.
• A persistent GPU detection log exists; hw-report works.
• NVIDIA validation is queued behind hardware arrival, with a stub selector script in place so the round is not blocked on it.