Sam & Claude
278ea10c63
Track C rewritten: old TS tarball-deploy plumbing replaced with the clawdie Rust binary strategies (C1: CLI, C2: wizard, C3: declarative). References the existing clawdie crate in Colibri (discover → plan → apply). C1 is zero new code — needs only 1 destructive validation test.
831 lines
34 KiB
Markdown
831 lines
34 KiB
Markdown
# 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.
|
||
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 — 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; 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 (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 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.
|