Add hp-chell host notes and kernel 7.x i915 black-screen fix script

CLAUDE.md

@@ -0,0 +1,71 @@
+# 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`.
+  - 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-2512.2` (release date 01/25/2026) — confirms MrChromebox custom firmware, not stock ChromeOS firmware.
+- 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; eMMC (`mmcblk0`, ~29GB) is the original ChromeOS storage, while `/` lives on `sda` (117GB), suggesting an internal drive swap/upgrade was done as part of the conversion.
+
+## 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.

setup-i915-kernel7-fix.sh

@@ -0,0 +1,74 @@
+#!/bin/sh
+# setup-i915-kernel7-fix.sh
+#
+# Run on a fresh hp-chell (HP Chromebook 13 "chell", coreboot/MrChromebox
+# firmware, KDE neon) install to apply two things:
+#
+#   1. The kernel 7.x cold-boot black-screen workaround: a
+#      /usr/share/sddm/scripts/Xsetup hook that forces a second modeset
+#      on eDP-1 to un-stick i915's pipe A on 7.x kernels. See project
+#      CLAUDE.md for the full diagnosis writeup.
+#   2. GRUB_TIMEOUT=5 / GRUB_TIMEOUT_STYLE=menu, so the boot menu is
+#      visible for 5 seconds (useful for picking a fallback kernel like
+#      6.17.0-42-generic if a future 7.x point release regresses again).
+#
+# Safe to re-run; idempotent.
+
+set -eu
+
+if [ "$(id -u)" -ne 0 ]; then
+    echo "must run as root (sudo $0)" >&2
+    exit 1
+fi
+
+echo "==> installing SDDM Xsetup i915 kernel-7.x workaround"
+cat > /usr/share/sddm/scripts/Xsetup << 'EOF'
+#!/bin/sh
+# Xsetup - run as root before the login dialog appears
+
+if [ -e /sbin/prime-offload ]; then
+    echo running NVIDIA Prime setup /sbin/prime-offload
+    /sbin/prime-offload
+fi
+
+# Workaround: on kernel 7.x, the first i915 modeset at cold boot (Xorg's
+# auto-modeset to the panel's native 3200x1800) leaves pipe A in a bad
+# state (persistent CPU pipe A FIFO underrun -> blank panel, backlight
+# still on, even though DRM/plane state reports healthy). Forcing a
+# second modeset unsticks it. Rather than cycle back to native, just
+# land on 1600x900 (exact half of 3200x1800, clean 2x integer scaling)
+# and stay there -- it's only the login screen; the logged-in session
+# renews the modeset itself and comes up at full native resolution.
+# Not needed on 6.17.x kernels. See project CLAUDE.md for the full
+# writeup.
+case "$(uname -r)" in
+    7.*)
+        xrandr --output eDP-1 --mode 1600x900 >/tmp/xsetup-modeset.log 2>&1
+        echo "set eDP-1 to 1600x900 (i915 kernel 7.x cold-boot workaround)"
+        ;;
+esac
+EOF
+chmod 755 /usr/share/sddm/scripts/Xsetup
+
+echo "==> setting GRUB_TIMEOUT=5 / GRUB_TIMEOUT_STYLE=menu"
+grub_conf=/etc/default/grub
+
+set_grub_key() {
+    key=$1
+    value=$2
+    if grep -q "^${key}=" "$grub_conf"; then
+        sed -i "s|^${key}=.*|${key}=${value}|" "$grub_conf"
+    elif grep -q "^#${key}=" "$grub_conf"; then
+        sed -i "s|^#${key}=.*|${key}=${value}|" "$grub_conf"
+    else
+        echo "${key}=${value}" >> "$grub_conf"
+    fi
+}
+
+set_grub_key GRUB_TIMEOUT 5
+set_grub_key GRUB_TIMEOUT_STYLE menu
+
+echo "==> running update-grub"
+update-grub
+
+echo "==> done"