hp-chell/CLAUDE.md

# hp-chell project notes

## Agent-accessible host

- **hp-chell** (`hp-chell.lan.1qaz.ca`) — KDE neon (Debian-based) x86_64 laptop (Intel Core m7-6Y75, 4 cores, 15GiB RAM, 117GB disk, Intel HD Graphics 515), full sudo (nopasswd) account `agent-user` (uid 60123). Provisioned 2026-09-03.
  - Auth: SSH key preferred (this machine's `~/.ssh/id_ed25519.pub` is already in the host's `authorized_keys`) — `ssh agent-user@hp-chell.lan.1qaz.ca`. When working *on* hp-chell itself as `matt` (no nopasswd sudo), `matt`'s own `~/.ssh/id_ed25519.pub` is also authorized (added 2026-09-27) — use `ssh agent-user@localhost 'sudo ...'` for root.
  - Fallback password: stored in local Bitwarden vault, item id `1db3b9f6-a82e-4692-846a-b4bb002a5be6` (name "agent-user@hp-chell.lan.1qaz.ca (SSH)") — fetch with `bw get password 1db3b9f6-a82e-4692-846a-b4bb002a5be6` (vault must be unlocked; `bw unlock`).
  - Host inventory/specs: see `~/AGENT_INFO.md` on the host itself. Original provisioning prompt saved at `~/AGENT_PROMPT.txt` on the host.
  - Groups: adm,cdrom,sudo,dip,plugdev,lpadmin,sambashare,docker. Has docker, tailscale0 interface (not connected as of provisioning), python3.12, git, jq, rsync, tmux.

## Hardware identity (confirmed via `sudo dmidecode -t system -t baseboard -t bios`)

This is a real **HP Chromebook 13 G1** ("chell" board), converted from ChromeOS to a normal Linux boot via custom coreboot firmware (MrChromebox project) and now running KDE neon as its OS.

- BIOS/firmware: `coreboot`, version `MrChromebox-2606.1` (release date 07/14/2026) — confirms MrChromebox custom firmware, not stock ChromeOS firmware. (Was `MrChromebox-2512.2` / 01/25/2026 as of initial provisioning 2026-09-03; updated via MrChromebox firmware utility same day — see note below.)
- System: Manufacturer `Google`, Product Name `Chell`, Family `Google_Glados`, Serial `5CD732BLC9` — `Chell`/`Glados` is the Google Chrome OS board/reference codename for the HP Chromebook 13 G1.
- Baseboard: Manufacturer `Google`, Product Name `Chell`, Serial `PFYTU018J90043`.
- Implication: fanless Core m CPU, no way to add a fan — keep sustained-load expectations modest.
- **Storage correction (2026-09-04)**: `sda` (117GB, where `/` lives) is a microSD card in the laptop's **built-in microSD slot**. The slot's reader hangs off the internal USB bus, which is why `lsblk` shows `TRAN=usb`, but it is *not* an external USB device. The whole KDE neon install boots from that microSD card, not from the eMMC. (Wording corrected 2026-09-27; earlier notes called it an "external USB/SD card".) The real internal eMMC (`mmcblk0`, ~29GB) was blank until 2026-09-04, when ChromeOS Flex was installed onto it — see "Dual boot" below. (Superseded the original note here, which incorrectly assumed `sda` was the internal eMMC.)

## Kernel 7.x black-screen bug (diagnosed and fixed 2026-09-03)

Multiple kernels are installed: `6.17.0-42-generic` (and `-35`) work fine at
boot. `7.0.0-30-generic` (and `-14`) hit a cold-boot display bug: the panel's
backlight comes on but no image ever appears — looks like a dead screen.

**Root cause**: on a 7.x kernel, i915's very first modeset at boot (Xorg/
Weston auto-configuring the panel's native `3200x1800@60`) leaves pipe A
stuck — `dmesg` shows a `CPU pipe A FIFO underrun` right after `Reducing
the compressed framebuffer size...`. Everything above that layer (DRM
connector/plane/CRTC state, backlight sysfs, Xorg/Weston logs) reports
fully healthy — `eDP-1` connected/enabled/dpms=On, pipe active, plane
visible with real framebuffer content — yet the panel shows nothing. A
*second* modeset (any resolution change via `xrandr`) reliably un-sticks
the pipe and it works perfectly afterward, including back at full native
resolution and 12bpc color. This is a kernel/i915 bug, not specific to a
display server — confirmed identical failure under both Xorg (`sddm`
default) and Wayland (`sddm` + `weston`, via `DisplayServer=wayland` in
`sddm.conf.d`, which needs the `weston` package or it silently falls back
to X11).

**Ruled out** (each verified, none of these were the actual cause):
- Dim/stale backlight (`/var/lib/systemd/backlight/...` restoring a low
  saved value) — this was a *real but separate* red herring encountered
  early in diagnosis; fixed by just adjusting brightness once logged in
  normally. Not the cause of the later, reproducible black-screen bug.
- `cros-ec-gpio: Failed to attach ACPI GPIO chip` / `EC:ENABLE_BACKLIGHT`
  GPIO name collisions — present identically on working 6.17 boots too.
- `i915.nuclear_pageflip=0` boot param — was already present during the
  original failures; adding/removing it makes no difference (legacy
  atomic-modeset override, irrelevant on modern i915; also needlessly
  taints the kernel — removed from `/etc/default/grub`).
- `i915.enable_fbc=0`, `i915.enable_psr=0`, `i915.enable_sagv=0` — each
  tried individually via kernel cmdline, none fixed it.

**Fix in place**: `/usr/share/sddm/scripts/Xsetup` (SDDM's root-run hook,
fires right after the X/Wayland server starts, before the greeter draws)
detects a `7.*` kernel via `uname -r` and runs
`xrandr --output eDP-1 --mode 1600x900` — a second modeset that un-sticks
the pipe. `1600x900` was chosen (rather than cycling back to native) since
it's an exact half of the panel's native `3200x1800` (clean 2x integer
scaling) and it's only the greeter — the actual logged-in Plasma/Wayland
session correctly renews the modeset itself and comes up at full native
`3200x1800` with 125% scaling, confirmed working. No kernel cmdline
workarounds are needed — `/etc/default/grub`'s `GRUB_CMDLINE_LINUX_DEFAULT`
is back to a clean `'splash'`.

Confirmed reliable across multiple clean `sudo systemctl poweroff` /
power-on cycles. The GRUB default entry (index 0, `GRUB_DEFAULT=0`) auto-
selects the newest installed kernel, so `7.0.0-30-generic` is what boots
by default now; `6.17.0-42-generic` remains available via the GRUB
"Advanced options" submenu as a known-good fallback if ever needed.

**2026-09-27, SDDM → Plasma Login**: an `apt upgrade` (which also
brought kernel `7.0.0-34-generic`) switched the display manager to
`plasmalogin` (`/etc/X11/default-display-manager`). Its greeter runs
under `kwin_wayland` (user `plasmalogin`, uid 984, `plasma-login*.service`
in its systemd *user* manager), so the SDDM `Xsetup` hook above no
longer fires and the black screen came back. Findings:
- A resolution change via `kscreen-doctor` (1600x900 and back) is **not**
  enough under KWin: the eDP panel fitter absorbs it (kernel adjusted
  mode stays native 3200x1800, no real pipe modeset). Going to 1600x900
  and staying there would also be unusable anyway — KWin keeps the 1.85x
  scale, giving an 865x487 logical greeter.
- A DPMS cycle (`kscreen-doctor --dpms off` then `--dpms on`) fully
  disables the CRTC (`i915_display_info` shows pipe A `active=no`) and
  its re-enable is a genuine full modeset — that un-sticks the pipe.
- `kscreen-doctor` needs the greeter's session bus to *apply* changes
  (`DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/984/bus`,
  `WAYLAND_DISPLAY=wayland-0`); with `KSCREEN_BACKEND_INPROCESS=1` it
  reads outputs fine but silently fails to set ("Cannot find output
  with id 1"). Mode specs must match exactly (`1600x900@59.95`, not
  `@60`) or use mode ids.
- i915 debugfs is under `/sys/kernel/debug/dri/1/` on this box (DRM
  minor 1), not `dri/0`.

Fix: `/usr/local/libexec/hp-chell-i915-dpms-cycle` (no-op unless kernel
`7.*` and user `plasmalogin`; waits for KWin, then cycles DPMS), run via
`/etc/systemd/user/plasma-login.service.d/10-i915-kernel7-dpms-cycle.conf`
as `ExecStartPre` (plasma-login.service is ordered after
plasma-login-kwin_wayland.service, so KWin is already up).

Setup script for a fresh install: `setup-i915-kernel7-fix.sh` (in this
repo) installs both the SDDM `Xsetup` fix and the Plasma Login drop-in, and sets `GRUB_TIMEOUT=5` /
`GRUB_TIMEOUT_STYLE=menu` so the boot menu is visible for 5s. Idempotent,
safe to re-run.

**2026-09-03, post firmware update**: updated coreboot from
`MrChromebox-2512.2` to `MrChromebox-2606.1` via the MrChromebox firmware
utility, then rebooted. First boot after the flash appeared to hang after
the Plymouth splash (same visual symptom: backlight on, no image) and
required a forced power-off. The *next* boot after that came up clean at
SDDM with the `Xsetup` fix applying normally (empty `/tmp/xsetup-
modeset.log`, one `FIFO underrun` as expected, pipe un-stuck as usual) —
so this looks like a one-off "settle in" hiccup from the fresh firmware
flash itself, not a recurrence of the underlying i915 bug or a new
problem. If it happens again right after a firmware update, try a forced
power-off + power-on before assuming anything is actually broken.

## Dual boot: KDE neon (microSD) + ChromeOS (internal eMMC)

**FydeOS** (ChromiumOS-based, `iris` build; replaced ChromeOS Flex on
2026-09-27) is installed on the internal eMMC (`/dev/mmcblk0`); neon
stays on the microSD card (`sda`). **Full details are in `CHROMEOS-FLEX.md`**,
covering install/reinstall via `install-flex-emmc.sh`, why a raw `dd` of
the recovery image boots as live media, `chromeos-install`-from-Linux
gotchas, the partition layout, and boot selection.

Quick reference:
- Reinstall: `sudo ./install-flex-emmc.sh <Flex or FydeOS .bin.zip or .bin>` (wipes
  the eMMC, masks every other disk, about 2.5 min, log in
  `/var/log/flex-install.log`).
- Boot it from neon's GRUB menu with the "ChromeOS Flex (internal
  eMMC)" entry (in `/etc/grub.d/40_custom`; chainloads the ESP with FS
  UUID `F35E-F13C`; title kept from Flex), or from the firmware picker (`Esc` at POST, then
  `Internal eMMC`). With the microSD card removed, the firmware boots it
  directly.
- ChromeOS updates re-add a UEFI entry and put it first in `BootOrder`;
  see `CHROMEOS-FLEX.md`.

## Audio (neon)

Speakers, headset jack and mic work under neon thanks to custom fixes
applied 2026-03-05, documented in **`AUDIO.md`**: WeirdTreeThing's
`chromebook-linux-audio` script (`avs` driver via
`/etc/modprobe.d/snd-avs.conf`, cros UCM profiles, WirePlumber
headroom), avs topology blobs hand-downloaded from upstream
linux-firmware into `/lib/firmware/intel/avs/`, and a `Syntax 7` →
`Syntax 6` sed over the UCM files for neon's alsa-lib 1.2.11. FydeOS on
the eMMC has no audio yet (not investigated).

## zram swap (neon)

Disk swapfile replaced by an 8GiB zstd zram device via `zram-tools`
(`/etc/default/zramswap`), set up 2026-03-05. Documented in **`ZRAM.md`**.
`vm.swappiness=100` is persisted in `/etc/sysctl.d/99-zram.conf`, and the
old `/swapfile` was deleted (both 2026-09-27).

## Other neon customizations

See **`NEON-CUSTOMIZATIONS.md`** (reconstructed 2026-09-27 from shell
history): keyd Chromebook keyboard remap (built from source,
`/etc/keyd/default.conf`, internal keyboard only), USB-C DisplayPort
via `/etc/modules-load.d/cros-video.conf` (`cros_ec_typec`,
`typec_displayport`), `linux-generic-hwe-24.04-edge` (why it's on 7.x
kernels) plus the 6.17 fallback, `/tmp` on tmpfs + localepurge to spare
the microSD root, the removed r8152 DKMS driver, disabled tailscaled,
and third-party apt repos and hand-installed tools. **Suspend must stay
`s2idle`**: S3 (`deep`) made the microSD reader drop off on resume and
remounted `/` read-only (2026-09-27).