docs: REQUIREMENTS.md — OpenGL 4.3 floor, disk/RAM planning

Acer M5-481T fails Ghostty because Ivy Bridge HD 4000 tops out at
OpenGL 4.2 in Mesa; Ghostty needs 4.3 — a generation ceiling, not a
missing driver. Document that plus UEFI/x86_64, RAM, and storage floors
(Nix store generations + BTRFS snapper + hibernate swap≈RAM). Linked
from README, docs map, HARDWARE.md; #95 points here.

README.md

@@ -102,6 +102,10 @@ probably shouldn't exist.
 
 ## 2. Try it first (live ISO)
 
+**Before you install:** check **[docs/REQUIREMENTS.md](docs/REQUIREMENTS.md)**
+(UEFI x86_64, **OpenGL 4.3** for the default terminal, disk planning for the
+Nix store + BTRFS snapshots — 128 GiB is the comfortable floor).
+
 Boot the full desktop from a USB stick or VM without installing anything:
 
 ```sh

agent/BACKLOG.md

@@ -149,6 +149,13 @@ browser posture is explicit).
 **Machine:** Acer Aspire M5-481T only. **Dell XPS 9350 starts Ghostty fine**
 (Bernardo clarified 2026-07-15 — do not treat XPS as a Ghostty failure).
 
+**Why this hardware fails:** the Aspire is Ivy Bridge–class (**Intel HD
+4000**, ~2012). Mesa’s max for that GPU is **OpenGL 4.2**; Ghostty requires
+**4.3**. That is a **generation ceiling**, not a missing package — no
+Nomarchy or Mesa tweak can make HD 4000 report 4.3 honestly. Documented in
+`docs/REQUIREMENTS.md`. The product response is a fallback terminal (or
+probe), not “fix Intel drivers.”
+
 On the Acer, Bernardo installed **kitty** by hand (worked) and launched
 Ghostty from that shell twice — **same box, two lifecycle points, two log
 shapes**:

agent/JOURNAL.md

@@ -19,6 +19,18 @@ Template:
 
 ---
 
+## 2026-07-15 — docs/REQUIREMENTS.md (OpenGL floor + disk planning)
+- **Task:** Bernardo: why Acer lacks OpenGL 4.3; start documenting minimum
+  system requirements including storage (Nix store + snapshots).
+- **Did:** Answer is hardware generation (HD 4000 / Ivy Bridge tops at GL
+  4.2; Ghostty needs 4.3). New `docs/REQUIREMENTS.md` — UEFI/x86_64, GPU
+  table, RAM, disk floors (40/64/128 GiB) + swap≈RAM, why store+snapper grow;
+  linked from README, docs map, HARDWARE.md; #95 notes the generation ceiling.
+- **Verified:** V0 (docs only).
+- **Pending:** #95 still needs a runtime fallback; tighten disk numbers when
+  a fresh install is `df`-measured end-to-end.
+- **Next suggestion:** #123 (installer bake).
+
 ## 2026-07-15 — File install findings from Acer + XPS photos (no code)
 - **Task:** Bernardo: real installs on Acer Aspire M5-481T + Dell XPS 9350;
   photos of the install end screens and post-boot sessions. Figure out

docs/HARDWARE.md

@@ -3,6 +3,10 @@
 How Nomarchy enables CPUs, GPUs, laptops, firmware, and peripherals — and
 what to do when your machine is not in the happy path.
 
+**Minimum bar** (OpenGL, RAM, disk, UEFI): [`REQUIREMENTS.md`](REQUIREMENTS.md)
+— read that before calling a machine “unsupported”; this file is the
+enablement stack and quirk list.
+
 > **Queue:** [`agent/BACKLOG.md`](../agent/BACKLOG.md) (PROPOSED › Hardware
 > product). Product framing: [`VISION.md`](VISION.md) § A. Design history:
 > [`ROADMAP.md`](ROADMAP.md). Docs map: [`README.md`](README.md).

docs/README.md

@@ -6,6 +6,7 @@ tree for the same facts.
 | Path | Audience | Role |
 |------|----------|------|
 | [../README.md](../README.md) | Everyone | What Nomarchy is, install, options tables |
+| [REQUIREMENTS.md](REQUIREMENTS.md) | Users + agents | Minimum system requirements (GPU/OpenGL, RAM, disk, UEFI) |
 | [VISION.md](VISION.md) | Maintainers + agents | Product north star toward **v1.0** and beyond — themes, not a task queue |
 | [ROADMAP.md](ROADMAP.md) | Maintainers + agents | Design/decision records + shipped log (historical ✓) |
 | [HARDWARE.md](HARDWARE.md) | Users + agents | Firmware, profiles, drivers, unsupported machines |

docs/REQUIREMENTS.md

@@ -0,0 +1,162 @@
+# Minimum system requirements
+
+What Nomarchy expects of a machine. This is a **living floor**, not a
+marketing sheet — numbers come from measured installs and known software
+floors (Ghostty, NixOS, the ISO). When a real machine pushes a bound, update
+this file in the same change.
+
+Related: [HARDWARE.md](HARDWARE.md) (profiles/drivers),
+[TESTING.md](TESTING.md) (ISO/VM), [README](../README.md) § install.
+
+---
+
+## Supported platform (hard)
+
+| Requirement | Floor | Why |
+|-------------|-------|-----|
+| Architecture | **x86_64** | Only target the flake builds today |
+| Firmware | **UEFI** | Installer uses systemd-boot; BIOS/legacy is LATER |
+| Install path | Whole disk (disko) | No dual-boot / partial-disk path yet |
+
+---
+
+## Graphics (default desktop)
+
+The default terminal is **Ghostty**, which requires **OpenGL 4.3** (desktop
+profile). That is a **GPU generation** limit, not a “driver not installed”
+problem:
+
+| Generation (examples) | Typical max OpenGL (Mesa) | Default Ghostty |
+|-----------------------|---------------------------|-----------------|
+| Ivy Bridge / HD 4000 (e.g. **Acer Aspire M5-481T**, ~2012) | **4.2** | **Does not start** (`OpenGLOutdated`) |
+| Haswell and newer Intel iGPU, most AMD GCN+, discrete GPUs of the last decade | ≥ 4.3 | OK |
+| Dell XPS 9350 (Skylake) | ≥ 4.3 | OK (verified 2026-07) |
+
+**Why 4.2 and not 4.3 on HD 4000?** The silicon and Mesa’s feature set for
+that generation top out at OpenGL 4.2. No package upgrade on the distro can
+turn Ivy Bridge into a 4.3 device. Ghostty is choosing a modern GL baseline
+on purpose.
+
+**Until a fallback ships** (BACKLOG **#95** — alternate terminal or probe when
+GL < 4.3): machines below OpenGL 4.3 can still **install and run the
+desktop**, but SUPER+Return / the default terminal entry will fail until the
+user installs another terminal (e.g. kitty) or we ship an automatic fallback.
+
+Other Wayland clients vary; Hyprland itself is usually fine on these GPUs.
+The Ghostty floor is the one that bit real hardware first.
+
+---
+
+## CPU and memory
+
+| Resource | Practical minimum | Comfortable |
+|----------|-------------------|-------------|
+| CPU | 64-bit x86_64, dual-core | Quad-core or better (rebuilds) |
+| RAM | **8 GiB** | **16 GiB+** |
+
+NixOS + Home Manager rebuilds and browser/Electron apps are memory-hungry.
+Hibernation (default installer path) sizes a **swapfile ≈ RAM**, so low RAM
+also means less disk eaten by swap — but also less headroom when building.
+
+---
+
+## Storage (the important one)
+
+Nomarchy is a full NixOS desktop with:
+
+1. **The Nix store** — every generation keeps package closures; updates add
+   new paths until you GC. Many packages appear once per generation when
+   inputs move.
+2. **Home Manager generations** — desktop switches and `nomarchy-home` leave
+   profiles behind until cleaned.
+3. **BTRFS + snapper** — `@snapshots` timeline (hourly/daily) and
+   pre-rebuild snaps. Excellent for recovery; **they retain data** and grow
+   with how full the live filesystem is.
+4. **Optional hibernation swapfile** — default size = **RAM** (e.g. 16 GiB
+   RAM → 16 GiB swapfile on disk).
+
+Closure size is **not** the same as disk use after hardlink optimisation
+and is **not** the ISO size (see ROADMAP § chromium / #121 measurements).
+Still, plan for **growth**, not for a single install footprint.
+
+### Measured / known artifacts (order of magnitude)
+
+| Artifact | Size (approx.) | Source |
+|----------|----------------|--------|
+| Offline live ISO | **~8.1 GiB** | Built image, 2026-07 (#103 era) |
+| Template HM closure (nominal) | **~9.4 GiB** | `nix path-info` style figures in ROADMAP |
+| Desktop store weight (uncompressed, pre-dedupe order) | **tens of GiB** | ISO pin / offline pin analysis (#120) |
+
+A **fresh** install on empty disk is smaller than a machine that has been
+updated and snapshotted for months.
+
+### Recommended free disk (whole-disk install)
+
+These are **planning floors** for the target SSD/HDD the installer will wipe
+and use entirely — not “free space beside Windows.”
+
+| Use | Capacity | Notes |
+|-----|----------|--------|
+| Absolute minimum to finish install + first boot | **≥ 40 GiB** | Tight; little room for GC delay or snapshots |
+| Realistic daily driver | **≥ 64 GiB** | Short GC/snap retention still required |
+| Comfortable (updates + snapper + apps) | **≥ 128 GiB** | Default recommendation |
+| Power user / many generations / big apps | **256 GiB+** | Dev toolchains, Steam, local datasets |
+
+**Plus swap:** if you keep hibernation (default), add **~RAM** on top of the
+table (installer creates `/swap/swapfile` sized to RAM unless you set 0).
+
+Example: 16 GiB RAM laptop → plan **≥ 128 GiB disk**, of which ~16 GiB is
+swapfile, leaving room for store + snapshots.
+
+### Why Nix “duplicates everything”
+
+- Each **system** and **home** generation points at a closure of store
+  paths. Unchanged paths are shared (same `/nix/store/…` hash); changed
+  inputs pull **new** paths. After several updates you hold old + new until
+  `nix-collect-garbage` / generation deletion.
+- **Snapper** snapshots the BTRFS subvolumes. A snapshot is cheap until you
+  rewrite a lot of data; then it retains the old blocks. Timeline + rebuild
+  snaps mean “I deleted that 2 GB download” may not free space until snaps
+  expire.
+- The live **ISO** is large because it pins an offline install closure; that
+  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,
+tune snapper retention — see [RECOVERY.md](RECOVERY.md) and the System ›
+Recovery menu. This requirements page only states why the disk fills up.
+
+---
+
+## What we explicitly do **not** require
+
+| Non-requirement | Note |
+|-----------------|------|
+| NVIDIA as first-class | Deferred past v1 (PROPOSED); community/docs only |
+| Secure Boot enrolled out of the box | Not the current install path |
+| Touch / tablet as primary input | Untested as a bar |
+| < 8 GiB RAM as a supported target | May boot; rebuilds and browsers will thrash |
+
+---
+
+## Machines that defined these bounds
+
+| Machine | Role |
+|---------|------|
+| **Acer Aspire M5-481T** (~2012, Intel HD 4000, OpenGL 4.2) | Ghostty floor (#95); install bake / old-HW QA |
+| **Dell XPS 9350** (Skylake) | Install bake (#123); Ghostty OK |
+| AMD dev box / Latitude / T14s | Ongoing V3 (HARDWARE-QUEUE) |
+
+When you install on something older or smaller than the table, file what
+broke in `agent/BACKLOG.md` and tighten this page.
+
+---
+
+## Related work
+
+| Item | Topic |
+|------|--------|
+| BACKLOG **#95** | Ghostty fallback when OpenGL < 4.3 |
+| BACKLOG **#120** | Lighter netinstall ISO (download size ≠ installed size) |
+| BACKLOG **#123** | Installer HM pre-activate (first-boot polish) |
+| BACKLOG **#124** | Flake pin vs main/v1 lag after install |