clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
clawdie-iso/PLAN-OPERATOR-USB-NEXT.md
Sam & Claude f3f47c8cdd docs/skills: switch published image + flashing from .gz to .xz 
Smaller downloads that Rufus/balenaEtcher/RPi-Imager still read directly (zstd
would break Windows flashers). Switches the image artifact, flashing commands
(xz -dc | dd, xz -t, unxz), publish flow (xz -T0 -c), the artifact-manifest
script, and all skills + docs to .img.xz. Adds a Windows (Rufus/Etcher) flashing
section + README pointer. Source tarballs (clawdie-ai *.tar.gz) unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-14 12:04:56 +02:00

794 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 |
**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
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; 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.
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 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.
- Do not add a separate dashboard/pane-fabric dependency to the live USB for
this track; Colibri is the control-plane surface.
- 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 — 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.
---
## 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 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–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.
Reference in a new issue View git blame Copy permalink