Fix stale docs: grub cmdline now has resume params, swapfile back for hibernation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CHROMEOS-FLEX.md

@@ -7,10 +7,10 @@ hp-chell (HP Chromebook 13 G1, MrChromebox UEFI firmware) dual-boots:
 
 | OS | Disk | Notes |
 |---|---|---|
-| KDE neon | `sda`, external USB/SD card (117GB) | primary OS, owns GRUB |
+| KDE neon | `sda`, microSD card in the built-in slot (117GB; the reader is USB-attached internally) | primary OS, owns GRUB |
 | FydeOS (was ChromeOS Flex) | `mmcblk0`, internal eMMC (29GB) | installed from neon, see below |
 
-Because neon lives entirely on external media, the eMMC can be wiped and
+Because neon lives entirely on the microSD card, the eMMC can be wiped and
 reinstalled from the running neon system with no risk to neon.
 
 ## Installing / reinstalling
@@ -177,9 +177,9 @@ Two ways:
    Run `sudo update-grub` after editing `40_custom`. The install script
    rewrites the `--fs-uuid` value automatically.
 2. **From the firmware boot picker** (MrChromebox UEFI, `Esc` during
-   POST): `efibootmgr -v` shows `neon` (Boot0005, on the USB card) and
+   POST): `efibootmgr -v` shows `neon` (Boot0005, on the microSD card) and
    `Internal eMMC` (Boot0001), with `BootOrder` `0005,0001,0000,0003,0002`.
-   With the USB card unplugged, the firmware falls through to `Internal
+   With the microSD card removed, the firmware falls through to `Internal
    eMMC` and boots FydeOS with no menu.
 
 ## Flex takes over the UEFI boot order on updates

CLAUDE.md

@@ -16,7 +16,7 @@ This is a real **HP Chromebook 13 G1** ("chell" board), converted from ChromeOS
 - 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 actually an external USB/SD card (`lsblk` shows `TRAN=usb`) — the whole KDE neon install boots from that external card, not from anything internal. 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 internal.)
+- **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)
 
@@ -63,7 +63,9 @@ 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'`.
+has no i915 params (as of 2026-09-28 it's `'splash resume=UUID=…
+resume_offset=…'`; the resume params are for hibernation, see
+`NEON-CUSTOMIZATIONS.md`).
 
 Confirmed reliable across multiple clean `sudo systemctl poweroff` /
 power-on cycles. The GRUB default entry (index 0, `GRUB_DEFAULT=0`) auto-
@@ -117,11 +119,11 @@ 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 (USB) + ChromeOS (internal eMMC)
+## 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 external `sda`. **Full details are in `CHROMEOS-FLEX.md`**,
+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.
@@ -133,7 +135,7 @@ Quick reference:
 - 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 USB card unplugged, the firmware boots it
+  `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`.
@@ -164,5 +166,11 @@ history): keyd Chromebook keyboard remap (built from source,
 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 USB-card root, the removed r8152 DKMS driver, disabled tailscaled,
-and third-party apt repos and hand-installed tools.
+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). **Suspend-then-hibernate** (after
+3h asleep) is set up instead (2026-09-28): 16GB `/swapfile` at pri 10,
+`resume=`/`resume_offset=17674240` in GRUB + initramfs, a polkit rule
+re-enabling hibernate (Ubuntu blocks it); details in
+`NEON-CUSTOMIZATIONS.md`.

NEON-CUSTOMIZATIONS.md

@@ -62,12 +62,15 @@ named in the black-screen notes in `CLAUDE.md`. Old 7.x kernels
 `/etc/default/grub` (edited by hand several times; both `matt` and root
 history show `nano /etc/default/grub` + `update-grub`): `GRUB_DEFAULT=0`,
 `GRUB_TIMEOUT=5`, `GRUB_TIMEOUT_STYLE=menu`,
-`GRUB_CMDLINE_LINUX_DEFAULT='splash'` (see `setup-i915-kernel7-fix.sh`).
+`GRUB_CMDLINE_LINUX_DEFAULT='splash resume=UUID=3af45daa-b8c2-4053-9574-a958e0c3ea68
+resume_offset=17674240'` (the `resume` params were added 2026-09-28 for
+hibernation, see below; see also `setup-i915-kernel7-fix.sh`).
 
-## Storage / wear on the USB-card root
+## Storage / wear on the microSD root
 
-neon's root is an external USB/SD card, so a few changes cut down writes
-and space use:
+neon's root is a microSD card in the built-in slot (`sda`; the slot's
+reader is USB-attached internally), and microSD handles lots of small
+writes poorly, so a few changes cut down writes and space use:
 - **`/tmp` is tmpfs** (in `/etc/fstab`:
   `tmpfs /tmp tmpfs defaults,noatime,mode=1777 0 0`). Not in the shell
   history, so it was probably added in the same `nano /etc/fstab` edit
@@ -79,6 +82,113 @@ and space use:
   install (`USE_DPKG`, `MANDELETE`). If another language's translations
   or man pages are ever needed, add them with
   `sudo dpkg-reconfigure localepurge`.
+- **Root mounted with `commit=30`** (2026-09-27): the root line in
+  `/etc/fstab` is `defaults,commit=30`; the pre-change copy is
+  `/etc/fstab.bak-2026-09-27`. ext4 commits its journal every 30s
+  instead of every 5s, so writes are batched into fewer, larger bursts.
+  Trade-off: a crash or forced power-off can lose up to ~30s of recent
+  changes that weren't fsync'd (apt/dpkg, editors and databases fsync, so
+  they're unaffected). 30 rather than 60 because this machine has needed
+  forced power-offs. `relatime` is kept deliberately (not `noatime`).
+- **journald capped at 100MB** (2026-09-27):
+  `/etc/systemd/journald.conf.d/50-max-size.conf` sets
+  `SystemMaxUse=100M` (it was 455MB).
+- **`smartmontools` disabled** (2026-09-27, `systemctl disable --now`):
+  it failed on every boot because neither the microSD card nor the eMMC
+  supports SMART.
+- **Marked non-rotational** (2026-09-27): the Genesys reader reported
+  `rotational=1` (a spinning disk). `/etc/udev/rules.d/61-microsd-nonrotational.rules`
+  sets `queue/rotational=0` for `ID_VENDOR_ID=05e3`, `ID_MODEL_ID=0747`,
+  so `lsblk -d -o NAME,ROTA` shows `0`.
+- The card doesn't support discard/TRIM (`lsblk -D` shows 0), so
+  `fstrim.timer` does nothing for it. That's harmless and was left alone.
+
+## Suspend: stay on `s2idle`; do NOT use S3 (`deep`)
+
+Tested 2026-09-27. The firmware offers both `s2idle` (default) and `deep`
+(ACPI S3) in `/sys/power/mem_sleep`.
+- An RTC-woken 30s S3 test (`rtcwake -m mem -s 30` with `mem_sleep=deep`)
+  entered and left S3 cleanly, and the display came back. The i915
+  bug didn't show.
+- **A real lid-close S3 suspend broke the root filesystem**: on resume
+  the built-in microSD reader (USB, Genesys `05e3:0747`) didn't come
+  back in time, the kernel logged disk I/O errors, and ext4 remounted `/`
+  read-only (`errors=remount-ro`). Nothing was logged because root was
+  read-only (the previous boot's journal just stops). After a forced
+  reboot, the initramfs fsck replayed the journal and reported the
+  filesystem clean; no lasting damage was found.
+- In S3 the USB controller loses power, so the reader has to be
+  re-attached. USB "persist" (`power/persist=1`, the kernel feature
+  meant for root on USB storage) was already on and didn't save it.
+  There's no dependable fix, so **never set `mem_sleep_default=deep`**
+  while neon's root is on the microSD slot.
+- `s2idle` keeps USB powered and has worked for months. **It does
+  reach S0ix**: in a 44s lid-close test (2026-09-28),
+  `/sys/kernel/debug/pmc_core/slp_s0_residency_usec` (needs root)
+  grew by ~42.2s, and `package_cstate_show` showed Package C10 ~42.0s.
+  So ~96% of the suspend was in the deepest idle state, and drain should
+  be close to S3's. Root stayed `rw` with no I/O errors.
+- Use the `pmc_core` counter above, not
+  `/sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us`.
+  That one comes from ACPI LPIT, which isn't wired up properly under
+  coreboot here: it read 270µs for the same suspend.
+
+## Suspend-then-hibernate (set up 2026-09-28)
+
+A lid close suspends (`s2idle`, instant). If the machine is still asleep
+after **3 hours**, systemd wakes it (RTC), writes a hibernation image to
+disk and powers off. This protects against a dead battery without
+writing a multi-GB image on every lid close, which is why this was
+chosen over hybrid sleep. It doesn't need S3.
+
+Pieces:
+- **16GB `/swapfile`**, used for the hibernation image (sized to RAM for
+  the worst case; a typical image is ~4GB).
+  fstab `/swapfile none swap sw,pri=10 0 0`: priority 10 < zram's 100,
+  so normal swapping still goes to zram. Backup of the old fstab:
+  `/etc/fstab.bak-2026-09-28`.
+- **Resume location**: `resume=UUID=3af45daa-b8c2-4053-9574-a958e0c3ea68
+  resume_offset=17674240` in `GRUB_CMDLINE_LINUX_DEFAULT` (backup
+  `/etc/default/grub.bak-2026-09-28`) and in
+  `/etc/initramfs-tools/conf.d/resume`, then `update-initramfs -u -k all`
+  + `update-grub`. **If `/swapfile` is ever recreated, its offset
+  changes.** Get the new one with
+  `sudo filefrag -v /swapfile | awk '$1=="0:"{print $4}'` (strip the
+  trailing `..`), then update both places and rerun both commands.
+- **`/etc/systemd/sleep.conf.d/50-suspend-then-hibernate.conf`**:
+  `HibernateDelaySec=3h`.
+- **`/etc/polkit-1/rules.d/10-enable-hibernate.rules`**: Ubuntu's
+  `/usr/share/polkit-1/rules.d/com.ubuntu.desktop.rules` returns `NO` for
+  all `login1`/`upower` hibernate actions, so logind reported
+  `CanHibernate`/`CanSuspendThenHibernate` = `no` even though its sleep
+  checks passed (seen with
+  `systemctl service-log-level systemd-logind debug`). This rule sorts
+  earlier and returns `YES` for local, active users.
+  Ubuntu actually has *two* blockers: that JS rule and
+  `/var/lib/polkit-1/localauthority/10-vendor.d/com.ubuntu.desktop.pkla`
+  ("Disable hibernate by default in logind/upower"), which is still read
+  because `polkitd-pkla` is installed. The `10-` rule overrides both:
+  `busctl call org.freedesktop.login1 /org/freedesktop/login1
+  org.freedesktop.login1.Manager CanSuspendThenHibernate` returns `yes`
+  as `matt`.
+- **Plasma**: PowerDevil owns the lid, so each Power Management profile's
+  sleep mode is set to "Standby, then hibernate". That's `SleepMode=3`
+  under `[AC|Battery|LowBattery][SuspendAndShutdown]` in
+  `~/.config/powerdevilrc` (set 2026-09-28 for all three profiles).
+  **Gotcha:** PowerDevil caches hibernate support when it starts, so
+  after the polkit fix the option didn't appear in System Settings until
+  `systemctl --user restart plasma-powerdevil.service` and System
+  Settings was reopened. Check PowerDevil's view with
+  `qdbus6 org.freedesktop.PowerManagement /org/freedesktop/PowerManagement
+  org.freedesktop.PowerManagement.CanSuspendThenHibernate`.
+
+Tested 2026-09-28 with `systemctl hibernate`: a 3.8GB image, powered off,
+and the session resumed intact (uptime carried over, root `rw`). Right
+after resume, one readahead READ failed on `sda` ("device offline or
+changed") while the microSD reader was being reset. That's harmless:
+readahead failures are dropped, and ext4 logged no errors and stayed
+`clean`. It's the same reader re-attach that breaks S3, but a hibernate
+resume is a cold boot and the reader was back in time.
 
 ## Networking
 

ZRAM.md

@@ -3,21 +3,22 @@
 Set up **2026-03-05**, reconstructed on 2026-09-27 from `~/.bash_history`
 and the live config. It replaces the disk swapfile with compressed swap
 in RAM. That suits this machine: 15GiB RAM, and neon's root lives on a
-slow external USB/SD card (`sda`) that you don't want to swap to or wear
+slow microSD card in the built-in slot (`sda`) that you don't want to swap to or wear
 out.
 
-## Current state (2026-09-27)
+## Current state (2026-09-28)
 
 ```
-$ zramctl
-NAME       ALGORITHM DISKSIZE DATA COMPR TOTAL STREAMS MOUNTPOINT
-/dev/zram0 zstd            8G   4K   59B   20K         [SWAP]
 $ swapon --show
 NAME       TYPE      SIZE   USED PRIO
-/dev/zram0 partition   8G   0B  100
+/dev/zram0 partition   8G 582.5M  100
+/swapfile  file       16G     0B   10
 ```
 
-The zram device is the only swap. zswap is off
+zram (priority 100) takes all everyday swapping. The 16GB `/swapfile`
+(priority 10) is there for the hibernation image (see
+"Suspend-then-hibernate" in `NEON-CUSTOMIZATIONS.md`). It only gets
+ordinary swap pages if zram fills up. zswap is off
 (`/sys/module/zswap/parameters/enabled` = `N`), and there's nothing
 zram-related on the kernel command line.
 
@@ -66,7 +67,10 @@ zram-related on the kernel command line.
   guides set it to `0`, since zram has no seek cost and readahead just
   wastes work.
 - **The unused `/swapfile`** (512MiB, dated 2026-03-04, fstab line
-  commented out) was deleted.
+  commented out) was deleted. On 2026-09-28 a new **16GB `/swapfile`**
+  was added at priority 10 (below zram's 100) for hibernation. See
+  "Suspend-then-hibernate" in `NEON-CUSTOMIZATIONS.md`. zram is still
+  the everyday swap.
 
 ## Reapplying on a fresh neon install
 
@@ -79,8 +83,8 @@ SIZE=8192
 PRIORITY=100
 EOF
 sudo systemctl enable --now zramswap
-# comment out any /swapfile line in /etc/fstab, then:
-sudo swapoff /swapfile
+# drop any old swapfile from /etc/fstab (a hibernation swapfile is set
+# up separately, see NEON-CUSTOMIZATIONS.md)
 # persist swappiness
 echo 'vm.swappiness=100' | sudo tee /etc/sysctl.d/99-zram.conf && sudo sysctl --system
 ```

install-flex-emmc.sh

@@ -2,7 +2,8 @@
 # install-flex-emmc.sh
 #
 # Properly install ChromeOS Flex onto hp-chell's internal eMMC from the
-# running KDE neon system (which boots from an external USB/SD card).
+# running KDE neon system (which boots from the microSD card in the built-in
+# slot; its reader is USB-attached internally, so it shows as sda).
 #
 # Why not just dd the image: the Flex recovery .bin is an *installer*
 # image -- ROOT-B is a 2MB placeholder and STATE is a fixed ~6GB with