clawdie-iso/doc/NVIDIA-UNIVERSAL-HANDOFF.md

# NVIDIA universal lane — Codex build + hardware validation handoff

**From:** Claude (Linux) · **To:** Codex ISO Builder (FreeBSD 15 host)
**Goal:** one ISO that boots on any NVIDIA machine — detect the GPU pre-SDDM,
install the matching branch from an on-image repo, kldload it, then SDDM/XFCE.

Authored on Linux (sh -n clean; detector + branch/pkg map unit-tested). The
package/boot behavior **must be built and proven on FreeBSD + real NVIDIA
hardware** — it cannot be validated from Linux.

## What landed (behind `NVIDIA_UNIVERSAL`, default NO — normal builds unaffected)

- `build.cfg`: `NVIDIA_UNIVERSAL` flag.
- `build.sh`:
  - `install_nvidia_universal_repo()` — `pkg fetch -d` the three families
    (`nvidia-driver-390/470/580` + settings) into
    `/usr/local/share/clawdie/nvidia-repo`, `pkg repo` it, write
    `/usr/local/etc/pkg/repos/clawdie-nvidia.conf` (file:// , enabled).
  - In universal mode: no branch baked into the root; rc.conf
    `clawdie_live_gpu_mode="nvidia-auto"`.
- `live/operator-session/clawdie-live-gpu` (`nvidia-auto` mode): detect device id
  → branch {390,470,590} → `pkg install -r clawdie-nvidia nvidia-driver-<n>
nvidia-settings` → kldload via existing select/load. **Best-effort:** any
  failure falls through to the integrated/scfb path — never worse than today.

## Must verify on the FreeBSD build host

1. **`pkg fetch -o` / `pkg repo` layout** — confirm `pkg fetch -y -o DIR -d ...`
   places archives where `pkg repo DIR` expects them; adjust if `pkg repo` needs
   `DIR/All`. Confirm the dependency closure is complete (offline boot install
   must not reach the network).
2. **Boot install command** — `pkg install -y -r clawdie-nvidia nvidia-driver-470
nvidia-settings` resolves purely from the file:// repo with no network.
3. **Writable root at boot** — the USB-root install must allow `pkg install`
   before SDDM (it does on a real on-USB FreeBSD; confirm).
4. **Kernel ABI** — the staged kmod packages must match the image's kernel.
5. **Image size** — three branches + deps add several hundred MB; confirm
   headroom against `IMAGE_SIZE`.
6. **Exactly one branch** installed at boot (no mixing).

## Build commands

```sh
# colibri artifacts first (do NOT cargo clean after)
cd /home/clawdie/ai/colibri && git fetch origin && git reset --hard origin/main
cargo build --workspace --release

# universal image (set COLIBRI_REPO explicitly if building from a tmp worktree)
cd /home/clawdie/ai/clawdie-iso && git fetch origin && git reset --hard origin/main
sudo env NVIDIA_UNIVERSAL=YES \
  FEATURE_CLAWDIE=YES CLAWDIE_ENABLE=NO COLIBRI_DAEMON_ENABLE=NO \
  CLAWDIE_AI_REPO=/home/clawdie/ai/clawdie-ai \
  COLIBRI_REPO=/home/clawdie/ai/colibri \
  CLAWDIE_ARTIFACT_DIR=/home/clawdie/ai/colibri/target/release \
  ./build.sh --skip-memstick-fetch --live-default-password
```

## Hardware acceptance

1. Boot on the NVIDIA target.
2. `cat /var/log/clawdie-live-gpu.log` — expect: detected device id, chosen
   branch + pkg, "installed nvidia-driver-<n>", selected/loaded modules.
3. `kldstat | grep nvidia` and SDDM → XFCE comes up accelerated.
4. If install/load failed, the log shows the fallback and the desktop still
   comes up on integrated/scfb (no hard failure).

## Deletion criteria

Delete this handoff once a `NVIDIA_UNIVERSAL=YES` image has, on real NVIDIA
hardware, auto-installed the correct branch and reached XFCE — with the result
recorded below.

## Results

_(Codex: build host, GPU model + device id, branch chosen, pkg install outcome,
image size delta, SDDM/XFCE result.)_