docs: plan the post-boot hygiene tasks

neogaia was installed from a configuration written before the hardware
existed, so several things are now knowably wrong rather than guessed.

Adopt the upstream hardware profile for this laptop, which fixes deep
sleep, thermal management and the touchpad driver. Bound the store, the
retained generations and the boot menu, none of which have a limit today.
Declare the commit identity, which currently lives only in one checkout.

Grow the EFI system partition, which holds around seven generations at
its present size and cannot be enlarged in place, since the encrypted
container immediately behind it would have to be relocated. That makes a
reimage the only practical route, and the cheapest moment for one is now.
It doubles as the reproducibility test of the install documentation.
This commit is contained in:
2026-07-19 16:11:52 -04:00
parent 5e254857b9
commit f80ea948ea
5 changed files with 100 additions and 0 deletions

View File

@@ -0,0 +1,18 @@
## What to build
Hand ownership of `neogaia`'s hardware facts to the upstream `nixos-hardware` profile for the Dell XPS 13 9380, replacing settings this repo currently guesses or omits.
The profile is adopted wholesale, including the Intel GPU support it pulls in. Those packages are inert on a machine with no display server, and trimming them would mean diverging from upstream for no present benefit.
Adopting it makes four things true that are false on the running machine today: the laptop suspends into deep S3 rather than s2idle, the redundant PS/2 mouse driver stops loading over the i2c touchpad, thermal management runs, and firmware updates become possible.
The microcode setting the `Host` currently declares is dropped, because the profile provides it as a default keyed off the redistributable firmware setting already enabled here.
## Acceptance criteria
- [ ] `nixos-hardware` is a flake input
- [ ] The Dell XPS 13 9380 profile is imported by the `neogaia` `Host`
- [ ] The `Host`'s own Intel microcode setting is removed, now that the profile supplies it
- [ ] `nix flake check` builds the `neogaia` toplevel
- [ ] Manual confirmation after a rebuild: the default sleep mode is deep rather than s2idle
- [ ] Manual confirmation after a rebuild: the thermal and power management services are active, and the PS/2 mouse driver is no longer loaded

View File

@@ -0,0 +1,18 @@
## What to build
Bound the three things on this machine that currently grow without any limit: the Nix store, the set of retained system generations, and the boot menu.
Garbage collection runs weekly, deleting generations older than 30 days. That window is the point of the setting — on a rolling channel with a third-party kernel, the value of an old generation is having a known-good system to boot when an update breaks something, and disk space is not scarce here: the store is under 5 GiB against 473 GiB free.
Store optimisation runs weekly on its own schedule rather than at build time, so deduplication never adds latency to a rebuild.
Retained boot configurations are capped at 15. Each generation stores a kernel and an initrd on the EFI system partition at roughly 70 MiB apiece, and that partition is small and fixed. An exhausted one fails at bootloader installation — after the build has already succeeded, which is a confusing place to get stuck. The cap assumes the enlarged partition; on the current 512 MiB one only about seven fit.
## Acceptance criteria
- [ ] Automatic garbage collection is enabled weekly, deleting generations older than 30 days
- [ ] Store optimisation is scheduled weekly, rather than performed at build time
- [ ] Retained boot configurations are capped at 15
- [ ] These are declared as plumbing in the shared base config, so every future `Host` inherits them
- [ ] `nix flake check` builds the `neogaia` toplevel
- [ ] Manual confirmation after a rebuild: the collection and optimisation timers exist and are scheduled

View File

@@ -0,0 +1,17 @@
## What to build
A git `Module`, following the `Enable convention` and configured natively through home-manager, that carries the operator's commit identity — enabled on `neogaia`.
Today that identity exists only in one repository's local configuration on one machine. It is therefore invisible to every other checkout, absent from any future `Host`, and lost on a reimage. Declaring it makes committing work anywhere, reproducibly, like everything else in the flake.
The identity matches the one already present throughout this repository's history, so existing commits and future ones agree. Committing it is not a disclosure: it appears in every commit this repository has ever published.
It is a `Module` rather than base plumbing because a `Host` that should not carry a personal commit identity is easy to imagine once the servers exist.
## Acceptance criteria
- [ ] A git `Module` following the `Enable convention` exists and is enabled on `neogaia`
- [ ] The commit identity is configured through home-manager and matches the one used in existing history
- [ ] `nix flake check` builds the `neogaia` toplevel
- [ ] Manual confirmation: committing in a repository outside this checkout succeeds with no per-command identity override
- [ ] The stale note in the project's agent instructions claiming git identity is unconfigured is corrected, since commits already work here through repository-local configuration

View File

@@ -0,0 +1,27 @@
---
blocked-by: [0013-nixos-hardware-profile, 0014-nix-store-housekeeping, 0015-git-module]
---
## What to build
Grow `neogaia`'s EFI system partition and reimage the laptop from the finished configuration.
The partition is 512 MiB today, holding about seven generations at roughly 70 MiB of kernel and initrd apiece, and this `Host` runs a large third-party kernel. It grows to 2 GiB, which holds around 28 — comfortably past the 15 that are retained, at a cost of 0.3% of a 512 GB disk.
It cannot be grown in place: it sits first on the disk, starting at sector 2048 with the encrypted container immediately behind it, so enlarging it means moving that container's start offset. An encrypted volume's start cannot be relocated without rewriting its entire payload, which here is over 500 GiB. A reimage is the only practical route, and it is cheapest now — the machine is days old and holds around 3 GiB, of which 136 MiB is user data.
The blocking tasks are sequencing rather than strict dependency. Only the partition size is technically required; installing from the merged configuration means wiping once and booting into a machine that is already correct.
This reimage is also the reproducibility test of the install documentation. The first install was performed while writing it; performing it a second time against the current configuration is what proves it is a procedure rather than a record of one improvised session.
One thing must be true before the disk is erased: every branch worth keeping has to exist on the remote, because work that lives only on this disk dies with it.
## Acceptance criteria
- [ ] The `Host`'s disk layout declares a 2 GiB EFI system partition
- [ ] Every local branch worth keeping exists on the remote before the disk is erased
- [ ] The reimage is performed from the merged configuration, following the existing install documentation
- [ ] The install documentation is corrected wherever the procedure diverged from what it describes
- [ ] Manual confirmation: the machine boots, the encrypted root unlocks, and console login succeeds
- [ ] Manual confirmation: reported free space on the boot partition is consistent with its 2 GiB size, resolving the discrepancy observed before the reimage — where a 512 MiB partition reported 1022 MiB
- [ ] The project's agent instructions record that a flake only sees git-tracked files, so an untracked file is invisible to evaluation

View File

@@ -0,0 +1,20 @@
---
blocked-by: 0016-esp-resize-and-reimage
---
## What to build
Replace `neogaia`'s hand-written hardware detection file with a real scan of the machine it describes.
The file was written before the laptop ran NixOS, as an educated guess at what a Dell XPS 13 9380 needs, and still says so. The guess turned out to be adequate — the module required to reach the encrypted root is present and working — so this is honesty maintenance rather than a fix. It matters because the next person to read the file, including a future reader of this repo, should be able to trust that it describes measured hardware.
Only the detection results are kept: the modules the initrd needs, the modules the kernel loads, and the platform. The generated output also contains filesystem and swap declarations, which are dropped — the declarative disk layout owns those, produces them on every evaluation, and a second stale definition would either conflict outright or silently disagree.
Generating the scan requires root on the target machine.
## Acceptance criteria
- [ ] The detection file's contents come from a scan of the running machine rather than a guess
- [ ] Filesystem and swap declarations are absent from it, leaving the disk layout as the sole source of those
- [ ] The file no longer describes itself as a placeholder, and says plainly what it holds
- [ ] `nix flake check` builds the `neogaia` toplevel