# 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 ` 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 ` for review 4. Prompt: "Deploy? [y/N]" 5. Run `clawdie apply --pool --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): ```toml [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:** ```text /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:** ```text build.sh live/operator-session/* firstboot/setup-import.sh network setup hooks ``` **Acceptance checks on live USB:** ```sh 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. ```text hmt0: /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:** ```text live/operator-session/hw-report live/operator-session/clawdie-xfce-session live/operator-session/clawdie-xfce-session-inner live/operator-session/xprofile ``` **Acceptance checks:** ```sh 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. ```text pcm0: ATI R6xx (HDMI) default pcm3: Realtek ALC294 Internal Analog Speaker hw.snd.default_unit: 0 ``` Panel mixer also points at HDMI: ```text 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:** ```sh 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:** ```text 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:** ```text 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:** ```sh 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:** ```text 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:** ```text packages/pkg-list-*.txt build.sh skills/iso-build/SKILL.md pkg bootstrap/cache logic ``` #### 2. Fix or document pkg repository URL behavior **Evidence:** ```text 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:** ```text 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:** ```sh 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:** ```text 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:** ```sh 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: ```text /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:** ```sh 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: ```xml ``` 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: ```text 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: ```sh 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: ```text /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.