2026-05-24 23:21:02 +02:00
# Plan: Operator USB — Next Round
**Audience:** Codex (FreeBSD agent), Claude (Linux agent), Operator (Sam)
**Author:** Claude (Linux agent) — 2026-05-20
---
## 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 |
2026-06-13 11:38:28 +02:00
**Load-bearing decision: keep SDDM as the live display manager.**
SDDM is the validated live display-manager path for Intel and AMD GUI boot. Do
not replace it without equivalent real-hardware proof. SDDM is now part of the
2026-05-24 23:21:02 +02:00
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–
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; do NOT remove anything
yet — categorization first, removal in a follow-up.
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 _present in the offline repo but NOT loaded by default_ .
- 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 progression (first step)
**Goal:** unblock the disk-install path so it can consume
`pkg-list-disk-install-extras.txt` . Per `AGENTS.md` : "The disk-install path
does not consume `pkg-list-disk-install-extras.txt` yet."
This round does **not** ship a full installer. It sets up the plumbing.
**Steps:**
1. **Profile selection scaffold.** `firstboot/shell-desktop.sh` (or a new
`shell-profile.sh` ) reads a `CLAWDIE_PROFILE` value with three valid
options: `xfce` (default), `kde` , `headless` . Wire from
`/tmp/clawdie-install.conf` for now — no GUI surface yet.
2. **Disk-install pkg step.** New function
`clawdie_shell_pkg_install_disk_extras` in `firstboot/shell-pkg.sh`
that installs every package in `packages/pkg-list-disk-install-extras.txt`
from the bundled offline repo, gated by profile (the `kde` profile
will later pull `pkg-list-kde.txt` ; not creating that file yet).
3. **Hook from `firstboot.sh`.** Call the new function after base
firstboot completes, before `clawdie_shell_deploy_*` runs.
4. **Bhyve smoke test.** A shell script under `scripts/` that boots the
built image in bhyve, runs the disk-install path with
`CLAWDIE_PROFILE=xfce` , and asserts `blender` (the roadmap-essential
member of disk-install-extras) ends up installed on the target disk.
Bhyve is fine for plumbing; per `AGENTS.md` it's NOT proof for
graphical validation — leave that for Track A/E on real hardware.
**Definition of done:**
- One commit per step. Each step compiles and passes existing tests
before the next is added.
- A documented "what happens on disk install" paragraph in `FIRSTBOOT.md` .
### 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.
Herdr remains useful as a Linux/Hermes-side operator dashboard and pane
fabric. It can display Colibri state and drive terminals where present,
but it is not the ISO message bus and is not a FreeBSD/live-USB runtime
dependency.
**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. Herdr or another dashboard 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, gzip 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 smoke | `pi-provider-smoke` 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.
- Herdr is optional Linux operator UX. Do not add Herdr to the live USB
package list for this track.
- 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 a dashboard. If Herdr is
unavailable, 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 remains Herdr-free.
**Out of scope this round:**
- Adding Herdr 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.
---
2026-05-25 13:30:39 +02:00
## 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
2026-06-02 09:00:33 +02:00
host code.smilepowered.org
ping -c 1 code.smilepowered.org
2026-05-25 13:30:39 +02:00
```
#### 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: < 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:**
```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
2026-05-28 00:46:24 +02:00
skills/iso-build/SKILL.md
2026-05-25 13:30:39 +02:00
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
< 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:
```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.
---
2026-06-02 09:00:33 +02:00
## 2.2. Live Self-Debug Code Checkout Seed
**Operator request — 2026-06-01 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; do not copy API keys,
`.env` files, SSH private keys, build caches, package caches, `tmp/` , or
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 dirty
state.
- This is a live-debug aid, not a build-host replacement: Linux agents still do
not build the ISO, 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.
---
2026-05-24 23:21:02 +02:00
## 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–
---
## 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 Herdr/dashboard experiments and the GLM-4.7/DeepSeek provider smoke 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 (2026-05-20)
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 (2026-05-20)
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 do not treat GUI success as proven without Pi Builder / hardware output, and
I do not start ISO builds or flash media unless 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; do not touch.
- 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–
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.
