docs(migration): guide for migrating an existing NixOS machine to Nomarchy

Bernardo asked whether TuringMachine (NixOS 25.11) could adopt Nomarchy
without a reinstall, keeping all files. It can — it's a config switch that
reuses the existing hardware-configuration.nix, not a reformat. Adds
docs/MIGRATION.md: a generic "existing NixOS → Nomarchy" walkthrough with
TuringMachine as the worked example — candidacy checklist, the two
data-safety rules (never bump system.stateVersion; /home untouched), a
reversible Phase 0→4 (btrfs snapshot → build-only gate → nixos-rebuild
test → reconcile → cutover) and a triple rollback net. Bakes his decisions:
Nomarchy PPD (drop all ryzenadj), no Secure Boot (drop lanzaboote), full
cutover. Flake/system/home examples verified against lib.nix mkFlake +
templates/downstream, not guessed.

Also files a PROPOSED note: home.stateVersion should be mkDefault so
migrating users don't need mkForce.

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

agent/BACKLOG.md

@@ -275,6 +275,16 @@ actually float once seen (regex tolerance for the `.…-wrapped` form).
 *Agents: append here with a one-paragraph pitch (what/why/cost). Do not
 implement. Bernardo moves accepted items into a tier.*
 
+- **`home.stateVersion` should be `mkDefault`** (surfaced writing
+  docs/MIGRATION.md, 2026-07-08). `modules/home/default.nix:51` sets
+  `home.stateVersion = "26.05"` as a *plain* assignment, so a downstream
+  home.nix that needs a different value (anyone migrating an existing NixOS
+  install — their original install's stateVersion) can only override it with
+  `lib.mkForce`, which reads as a hack. Cheap fix: make it
+  `lib.mkDefault "26.05"` so a plain downstream assignment wins cleanly,
+  matching the mkDefault discipline the rest of the distro follows. (The
+  system side is already fine — the downstream owns system.nix outright.)
+
 - **Battery charge-limit — make the toggle instant** `[blocked:hw]`
   (follow-up to the preset toggle shipped 2026-07-07, iteration #55).
   The control-center now has a proper toggle (Off / 80% / 90% / 60% /

agent/JOURNAL.md

@@ -17,6 +17,33 @@ Template:
 
 ---
 
+## 2026-07-08 — Migration guide: existing NixOS → Nomarchy (docs, direct request)
+- **Task:** Bernardo asked whether THIS machine (TuringMachine, NixOS 25.11)
+  can migrate to Nomarchy without a reinstall, keeping all files — and to
+  write the walkthrough into a MIGRATION.md.
+- **Investigated the live machine:** already NixOS, personal modular flake,
+  systemd-boot, LUKS2 + btrfs with the exact subvol layout Nomarchy wants
+  (incl. `@snapshots`/`@home-snapshots`), AMD 7840U. Verdict: migration is a
+  config switch (reuse hardware-configuration.nix), NOT a reinstall; `@home`
+  is never touched. Main deltas: 25.11→26.05, keep system.stateVersion=24.11,
+  power-mgmt collision (his ryzenadj/TLP vs Nomarchy PPD), HM-module→standalone.
+- **Decisions (Bernardo):** adopt Nomarchy PPD + drop all ryzenadj; no Secure
+  Boot (drop lanzaboote); full cutover.
+- **Did:** wrote `docs/MIGRATION.md` — generic "existing NixOS → Nomarchy"
+  guide with TuringMachine as the worked example: candidacy checklist, the
+  two data-safety rules (never bump system.stateVersion; /home untouched),
+  Phase 0 snapshots → Phase 1 build-only gate → Phase 2 reversible
+  `nixos-rebuild test` → Phase 3 reconcile → Phase 4 cutover, triple rollback
+  net. Verified the downstream API against lib.nix (mkFlake src/username/
+  hardwareProfile) + templates/downstream so the flake/system/home examples
+  are real, not guessed.
+- **Verified:** V0 (docs) — referential accuracy against lib.nix + template;
+  did NOT run the migration commands (they'd alter the live machine).
+- **Follow-ups:** PROPOSED — make `home.stateVersion` mkDefault (migrating
+  users currently need mkForce).
+- **Next suggestion:** if Bernardo greenlights, scaffold Phase 1 from his real
+  hardware-configuration.nix.
+
 ## 2026-07-08 — Calendar on the clock click (iteration #68, item 42)
 - **Task:** item 42, de-scoped live by Bernardo — DON'T hook up calendar
   accounts; just ship a lightweight calendar that opens instantly on the