8c048a2692
Some checks failed
Check / eval (push) Has been cancelled
Add a self-contained "Enabling hibernation on an existing machine (no reinstall)" section to docs/MIGRATION.md, per the settled #76 call to document migration rather than ship a tool. Covers: @swap subvolume creation (subvolid=5), btrfs mkswapfile (NOCOW), reading the resume offset via map-swapfile, and wiring fileSystems."/swap" + swapDevices + resumeDevice + resume_offset into system.nix. Flags the /swap mount as required on the hand-edit path (a fresh install inherits it from disko-generated hardware-config). Notes the zram-priority reservation, a no-LUKS variant, and the swap=0 opt-out. Verification: V0. All read-only commands run live against this machine's LUKS(cryptroot)+btrfs(@)+/swap/swapfile layout; nix flake check --no-build green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
223 lines
10 KiB
Markdown
223 lines
10 KiB
Markdown
# Backlog — the prioritized task queue
|
||
|
||
**This is the only executable work list for agents.** Product themes and
|
||
v1.0 intent live in [`docs/VISION.md`](../docs/VISION.md); design history
|
||
in [`docs/ROADMAP.md`](../docs/ROADMAP.md); map in
|
||
[`docs/README.md`](../docs/README.md) and [`agent/README.md`](README.md).
|
||
|
||
**Rules:**
|
||
- Agents take the topmost actionable item (see LOOP.md). Finished items
|
||
are **deleted** here — the journal + git log are the record; durable
|
||
design notes get a ✓-entry in docs/ROADMAP.md (and/or a note in VISION)
|
||
if worth keeping.
|
||
- Item numbers are **stable IDs** — never renumbered or reused. A gap in
|
||
the sequence means shipped (or dropped) work; new items take the next
|
||
free number regardless of tier.
|
||
- Tags: `[blocked:hw]` needs real hardware (see HARDWARE-QUEUE.md) ·
|
||
`[human]` needs Bernardo · `[stuck]` two failed attempts, needs help ·
|
||
`[big]` must be split before starting.
|
||
- Agents may append to **PROPOSED** and **Decisions** freely (include
|
||
`VISION § …` or `ROADMAP § …` when relevant); only Bernardo moves items
|
||
*out* of PROPOSED into the tiers.
|
||
|
||
---
|
||
|
||
## NOW
|
||
|
||
*(empty — NEXT's top item is the queue head)*
|
||
|
||
## NEXT
|
||
|
||
### 76. Hibernation default `[big]`
|
||
**Product intent (Bernardo 2026-07-10):** hibernation on by default;
|
||
zram on alongside for live memory pressure. Disk swap ≥ RAM for the
|
||
hibernate image; zram high-priority for day-to-day swap (not sufficient
|
||
alone for resume).
|
||
|
||
**✓ zram slice shipped (2026-07-10):** `zramSwap` on by default in
|
||
`modules/nixos/oom.nix` (zstd, 50% RAM, priority 100 so day-to-day paging
|
||
stays off the disk swap reserved for the hibernate image); `checks.zram-swap`
|
||
VM test asserts device/algorithm/priority (V2 pass). **Remainder below is the
|
||
hibernation half** — disk swapfile default + resume + installer.
|
||
|
||
**Reference layout (this machine — already hibernation-capable, no zram
|
||
yet):** LUKS (`crypto_LUKS` → mapper `crypted`) holds one BTRFS with
|
||
`@swap` mounted at `/swap`; swapfile `/swap/swapfile` (here 16G);
|
||
`swapDevices = [{ device = "/swap/swapfile"; }]`;
|
||
`boot.resumeDevice = "/dev/disk/by-uuid/<LUKS-root-uuid>"`;
|
||
`boot.kernelParams = [ "resume_offset=…" ]` from
|
||
`btrfs inspect-internal map-swapfile -r`. The swapfile lives **inside
|
||
the encrypted volume** (subvolume, not a separate cleartext partition).
|
||
Installer path already sketches this (`@swap` + resume_offset patch in
|
||
`nomarchy-install` / `patch-template.py`) when `swapSize` ≥ RAM-ish.
|
||
|
||
**✓ Design settled (Bernardo 2026-07-10):**
|
||
- **Swap sizing** — keep **exactly RAM** (rounded up to whole GiB), as the
|
||
installer already does. Hibernate image ≤ RAM; zram (priority 100) takes
|
||
day-to-day paging so the file stays reserved for the image. No change.
|
||
- **`swapSize=0`** — stays a no-swap / no-resume opt-out (already handled by
|
||
installer + patch-template: no `@swap`, no `swapDevices`/resume wiring).
|
||
- **Migration (existing machines)** — **docs runbook in `docs/MIGRATION.md`**,
|
||
not a tool: create `@swap` subvol + swapfile, `map-swapfile -r` offset,
|
||
add `swapDevices`/`boot.resumeDevice`/`resume_offset` to `system.nix`.
|
||
- **No-swap Hibernate UX** — **keep the Power-menu Hibernate row**; when
|
||
hibernate fails (no swap), show a desktop **notification** explaining no
|
||
swap is configured (rather than hiding the row or a silent no-op).
|
||
|
||
**Already shipped for NEW installs** (verify, don't rebuild): installer
|
||
defaults `NOMARCHY_SWAP_GB=RAM` → hibernation-ready `@swap` swapfile encrypted
|
||
with root; `patch-template.py` writes `swapDevices` + `boot.resumeDevice` +
|
||
`resume_offset`; Power menu has a Hibernate row; hibernate+LUKS+hyprlock
|
||
interplay handled in `modules/nixos/default.nix` / `modules/home/idle.nix`.
|
||
|
||
**Remaining slices:**
|
||
|
||
1. ~~**Docs** — `docs/MIGRATION.md` hibernation-enable runbook (V0).~~ ✓
|
||
shipped 2026-07-10 (§ "Enabling hibernation on an existing machine";
|
||
commands verified live against the dev machine's LUKS+@swap layout).
|
||
2. **Menu** — Hibernate row: notify-on-failure when no swap configured
|
||
(behavioral, V1/V2). Keep the row unconditional.
|
||
3. **Verify (required)**
|
||
- **V0:** eval / option / disko contracts.
|
||
- **V2 (mandatory, agent):** exercise hibernation in the **VM harness**
|
||
(`runNixOSTest` or install-test style) — encrypted root + BTRFS
|
||
`@swap` swapfile + resume_offset; prove hibernate→resume path at
|
||
least as far as QEMU allows (fail the item if only “config
|
||
evaluates”).
|
||
- **V3:** real laptop (this LUKS+@swap layout): Hibernate → power off
|
||
→ resume session; queue HARDWARE-QUEUE.
|
||
|
||
**Out of scope:** TLP; formatter. Prefer boring NixOS knobs; extend the
|
||
existing installer swapfile story rather than inventing a second layout.
|
||
|
||
## LATER
|
||
|
||
- **Wallpapers artifact split** (ROADMAP § Faster switches — decided,
|
||
deferred): pinned `Nomarchy-wallpapers` input so a state write stops
|
||
re-copying 86 MB. Follow-on: pre-built theme variants if switches are
|
||
still slow after.
|
||
- **Installer round 2** (ROADMAP § Installer): multi-disk BTRFS RAID,
|
||
impermanence, BIOS/legacy boot.
|
||
- **Boot-from-snapshot**: a systemd-boot equivalent of grub-btrfs.
|
||
- **Night-light geo mode**: lat/long auto sunset/sunrise (means wlsunset).
|
||
- **Per-theme icon overrides** / more icon packs (ROADMAP § Icon themes).
|
||
- **MIPI/IPU software-ISP camera** support (no-UVC machines).
|
||
- **VPN exit-node richer display** (country/city) (optional).
|
||
- **NixOS release bump → v2** `[human]`: deliberate, hand-edited, never
|
||
automated; the previous attempt was discarded (2026-06-22) over a
|
||
Hyprland OOM blocker — see MEMORY.md before retrying (NOW#3 should
|
||
also soften that blocker class).
|
||
|
||
## FUTURE (decided deferred — not the agent queue head)
|
||
|
||
Work we **intend** someday but explicitly **not** NEXT. Agents do not
|
||
pick these unless Bernardo promotes one into NEXT/NOW.
|
||
|
||
### 20. KVM runner → VM suite in CI `[human]`
|
||
**Status (2026-07-10):** keep **eval-only** CI on the current Gitea
|
||
stack (act_runner in docker-compose on the 4c/4 GB IONOS VPS). Nested
|
||
KVM + RAM headroom on that host are a poor fit next to Gitea; full
|
||
`checks.*` VMs stay local / promotion-time until a **separate**
|
||
KVM-capable machine exists.
|
||
|
||
**When ready:** register a second runner (host-mode nix + `/dev/kvm`,
|
||
label `nix-kvm` — not the existing docker eval runner), then uncomment
|
||
the `vm-checks` job in `.gitea/workflows/check.yml` (`runs-on: nix-kvm`,
|
||
`nix flake check` + toplevel/HM builds). Do not enable the job until
|
||
that label is online (Gitea queues forever otherwise).
|
||
|
||
### Formatter — adopt later `[human]`
|
||
**Intent:** add a Nix formatter (likely `nixfmt-rfc-style`) in a dedicated
|
||
pass: reformat the tree once, document in CONVENTIONS, optional CI
|
||
check. **Not** the queue head — no drive-by reformats until that pass.
|
||
|
||
### Hibernation + zram
|
||
**Promoted → NEXT #76** (2026-07-10).
|
||
|
||
## PROPOSED (agent suggestions — await human triage)
|
||
|
||
*Agents: append here with a one-paragraph pitch (what/why/cost). Do not
|
||
implement. Bernardo moves accepted items into a tier.*
|
||
|
||
*Open work only. Shipped exam/A–C items (#47–#63, #14, #52 theme
|
||
high-ROI, etc.) live in the journal + ROADMAP — not here.*
|
||
|
||
### Product / day-2
|
||
|
||
_(Battery charge-limit instant → shipped 2026-07-10; V3 PASS Latitude
|
||
5310: Custom charge type + live menu + unplug re-apply.)_
|
||
|
||
_(Portal/Flatpak IR camera → **#71** docs (a); (b)/(c) still need T14s.)_
|
||
|
||
_(Post-install hardware hints residual → **#73**.)_
|
||
|
||
_(Look & Feel submenu → already shipped (Theme / wallpaper / night light);
|
||
2026-07-10: Reset wallpaper (auto) row; root stays six.)_
|
||
|
||
- **NVIDIA first-class options** — **deferred past v1** (Bernardo
|
||
2026-07-10). Keep #59 commented install guidance; no
|
||
`nomarchy.hardware.nvidia.*` until a hybrid maintainer + queue.
|
||
|
||
### Installer / template
|
||
|
||
_(Installer ↔ template SoT CI → **#72**; V2 install → **#75**.)_
|
||
_(Installer chown flake dir → **#65**.)_
|
||
_(MIGRATION.md snapshot layout → **#64**.)_
|
||
_(Unattended-install test matrix → **#74**.)_
|
||
_(Friendlier mkFlake theme-state errors → **#66**.)_
|
||
|
||
### Theme polish
|
||
|
||
_(#52 residual ANSI → **#68** ✓.)_
|
||
_(Fidelity / hierarchy nits → **#67** ✓.)_
|
||
_(Import pipeline hierarchy → **#70** ✓.)_
|
||
_(audit-theme-design identity exemptions → **#69** ✓.)_
|
||
_(summer-day/night pair polish + status CSS + preview recapture →
|
||
shipped 2026-07-10: JSON SoT, status states, theme-shot previews for
|
||
executive-slate + neon-glass.)_
|
||
|
||
_(Identity taste retunes + hand `btop.theme` for white/vantablack/lumon/
|
||
hackerman/matte-black/miasma/neon-glass/boreal/executive-slate →
|
||
shipped 2026-07-10.)_
|
||
|
||
### v1.0 pointer
|
||
|
||
See **VISION**. Open PROPOSED: NVIDIA wrappers deferred past v1; IR
|
||
portal (b)/(c) hardware. Browser default = Chromium; power = PPD.
|
||
|
||
|
||
## Decisions `[human]`
|
||
|
||
Open calls only Bernardo can make; agents add options/evidence but never
|
||
decide. **Resolved** entries stay for history; agents treat them as closed.
|
||
|
||
### Resolved (2026-07-10)
|
||
|
||
- **Docs site vs Markdown-in-repo** — **markdown in-repo for now**
|
||
(`docs/`, README). A rendered docs site is FUTURE if wanted.
|
||
- **Default browser** — **ship Chromium** in
|
||
`templates/downstream/home.nix`; mime → `chromium-browser.desktop`.
|
||
Opt out: delete the line / override mime.
|
||
- **Default power backend** — **keep PPD** (`nomarchy.system.power.backend`
|
||
default). TLP remains the one-line opt-in. Rationale: stability + live
|
||
profile API for menu/Waybar; Omarchy’s TLP experiment reverted.
|
||
|
||
### Resolved (2026-07-10, more)
|
||
|
||
- **Formatter adoption** — **yes, but not now.** Tracked as FUTURE
|
||
(below). Nix-source style only (`nixfmt-rfc-style` or similar); one
|
||
bulk reformat + CI/check when promoted. Until then: hand-aligned
|
||
style per CONVENTIONS.
|
||
|
||
- **Hibernation** — **want by default** (product intent). Needs a
|
||
disk-backed swap (file or partition) sized for resume; not zram alone.
|
||
Implementation is a future/NEXT item when designed (installer +
|
||
resume device + encrypted-root story).
|
||
|
||
### Resolved (2026-07-10, #76 design)
|
||
|
||
- **Swap sizing** — **exactly RAM** (installer default, unchanged). Hibernate
|
||
image ≤ RAM; zram takes day-to-day paging. **`swapSize=0`** stays no-swap.
|
||
- **Migration** — **docs runbook** (`docs/MIGRATION.md`), not a tool.
|
||
- **No-swap Hibernate** — keep the menu row; **notify on failure**.
|