docs: explain automatic generation prune for users (#128)

RECOVERY §4 documents the 14-day / keep-≥3-past policy for system and
Home Manager gens, with dry-run and timer commands. README and
REQUIREMENTS point here so install and day-2 hygiene match the product.

README.md

@@ -380,6 +380,13 @@ fonts. No runtime patching means no partial states, and `home-manager
 generations` is also your theme history. Waybar even restyles in place: it
 re-reads `style.css` when the symlink flips.
 
+**Cleanup is automatic.** A weekly timer (`nomarchy-gen-prune`) removes
+**system** and **Home Manager** generations that are older than **14 days**
+*and* beyond the **three most recent past** gens — so you always keep the
+current generation plus at least three rollbacks, even on a rarely rebuilt
+machine. Manual: `sudo nomarchy-gen-prune --dry-run`. Full story:
+[docs/RECOVERY.md §4](docs/RECOVERY.md#4-how-generations-are-kept-and-cleaned-up).
+
 The **wallpaper** is the one runtime piece (awww — nixpkgs' swww — is
 imperative; nothing in Nix consumes the path): applied at session start,
 after every switch via a tiny activation hook, and again when a monitor is

agent/JOURNAL.md

@@ -19,6 +19,14 @@ Template:
 
 ---
 
+## 2026-07-15 — Document generation prune for users (#128 docs)
+- **Task:** User-facing docs for the 14d / keep-≥3-past policy.
+- **Did:** RECOVERY §4 (how gens are kept); README generation section +
+  alias note; REQUIREMENTS hygiene points at the automatic prune.
+- **Verified:** V0 (docs only).
+- **Pending:** none.
+- **Next suggestion:** hardware V3 or human #115/#120.
+
 ## 2026-07-15 — #128 generation prune (14d + keep ≥3 past, system+HM)
 - **Task:** Implement auto-prune for system and Home Manager generations.
 - **Did:** `pkgs/nomarchy-gen-prune` + `modules/nixos/gen-prune.nix` weekly

docs/RECOVERY.md

@@ -57,20 +57,52 @@ journalctl --user -b              # Hyprland + the user services
 ## 3. A system change broke it — boot an older generation
 
 Reboot and pick an older **NixOS generation** in the systemd-boot menu
-(hold a key during firmware handoff if the menu doesn't linger; the
+(hold a key during firmware handoff if the menu doesn't linger). That
-last 10 generations are kept). That boots yesterday's system unchanged.
+boots yesterday's system unchanged.
 
 Booting an old generation is temporary — the default entry is still the
 broken one. Make the fix stick from the working boot: revert the change
 in `~/.nomarchy` (`git -C ~/.nomarchy revert …` or edit `system.nix`
 back), then `nomarchy-rebuild`.
 
-**Automatic prune (#128):** a weekly timer (`nomarchy-gen-prune`) removes
+How long generations stick around (and how cleanup works) is §4 below.
-system *and* Home Manager generations that are **older than 14 days** and
-**beyond the three most recent past gens** (current + ≥3 past always kept).
-Manual: `sudo nomarchy-gen-prune` (or `--dry-run`).
 
-## 4. Files went missing or wrong — snapshots (BTRFS installs)
+## 4. How generations are kept (and cleaned up)
+
+Every `nomarchy-rebuild` and `nomarchy-home` (and every theme switch) leaves
+a **generation** — a full previous system or desktop you can roll back to
+(§1 and §3, and **System › Recovery**). Those take disk space until they
+are removed.
+
+Nomarchy prunes them **automatically once a week** with a policy designed
+not to strand you without rollback:
+
+| Rule | Meaning |
+|------|---------|
+| **Age** | Generations older than **14 days** are eligible for removal. |
+| **Safety floor** | Always keep the **current** generation and at least **3 past** ones — even if those three are older than 14 days. |
+| **Both halves** | The same rule applies independently to the **system** (boot menu) and to **Home Manager** (desktop) profiles. |
+
+So a busy machine that rebuilds often can still free old junk after two
+weeks, while a rarely rebuilt laptop never drops below four usable
+system gens (current + three past) or four desktop gens.
+
+**What you do not need to do:** run aggressive `nix-collect-garbage -d`
+day to day — that can delete *all* old generations and wipe the floor.
+The weekly timer already reclaims store paths after a careful prune.
+
+**Manual control:**
+
+```sh
+sudo nomarchy-gen-prune --dry-run   # list what would be deleted
+sudo nomarchy-gen-prune             # prune now (same rules as the timer)
+systemctl status nomarchy-gen-prune.timer
+```
+
+After a system prune the boot menu is refreshed so removed generations
+no longer appear as boot entries.
+
+## 5. Files went missing or wrong — snapshots (BTRFS installs)
 
 With `nomarchy.system.snapper.enable` (the installer's default on
 BTRFS), the root filesystem has hourly/daily history, and

docs/REQUIREMENTS.md

@@ -116,9 +116,13 @@ swapfile, leaving room for store + snapshots.
   is a download/USB cost, not permanent free space on the installed machine
   after install (the installed system has its own store).
 
-**Hygiene (user-facing, later doc links):** delete old generations, run GC,
+**Hygiene (automatic on Nomarchy):** a weekly `nomarchy-gen-prune` removes
-tune snapper retention — see [RECOVERY.md](RECOVERY.md) and the System ›
+system and Home Manager generations that are **older than 14 days** and
-Recovery menu. This requirements page only states why the disk fills up.
+**beyond the three most recent past gens** (current + ≥3 past always kept),
+then reclaims the store. Details and manual commands:
+[RECOVERY.md §4](RECOVERY.md#4-how-generations-are-kept-and-cleaned-up).
+Also tune snapper retention for BTRFS file history (System › Recovery ›
+Files). This requirements page only states why the disk fills up.
 
 ---