# 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):

```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: <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
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
<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.

---

## 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.
