docs: add ADR 0002 for kernel and nvidia strategy

Co-authored-by: Junie <junie@jetbrains.com>

docs/adr/0002-kernel-and-nvidia-strategy.md

@@ -0,0 +1,108 @@
+---
+description: >-
+  Decision to dual-install linux612 (LTS) + linux70 (stable) kernels and
+  migrate NVIDIA from the pinned 575xx branch to the mainline 595.71 branch
+  to prepare the workstation for Hyprland/Wayland.
+tags:
+  - adr
+  - kernel
+  - nvidia
+  - hyprland
+  - wayland
+last_updated: '2026-05-18'
+---
+
+# ADR 2: Kernel and NVIDIA Driver Strategy for Hyprland/Wayland
+
+## Status
+Accepted (2026-05-18)
+
+## Context
+The workstation runs Manjaro Linux on AMD Ryzen 7 2700X with an NVIDIA
+GeForce GTX 1050 Ti (Pascal, GP107) driving three monitors. The next
+infrastructure plan switches the desktop from KDE/X11 to Hyprland on
+Wayland. Two preconditions must hold before that switch is safe:
+
+1. **DRM/atomic and NVIDIA explicit-sync support** — Hyprland on NVIDIA
+   relies on driver-level explicit sync (introduced in 555.x and matured
+   through 575.x and 595.x). Without it, flickering and missed vblanks
+   are very common on Pascal+multi-monitor.
+2. **Matching kernel modules** — Manjaro ships pre-built `*-nvidia`
+   modules pinned to a single `nvidia-utils` version. Mixing `575xx`
+   userspace with a kernel that only has `595.71` modules (or vice
+   versa) breaks the driver at the next kernel boot.
+
+The starting point at the time of this ADR:
+
+| Item                      | Version                |
+|---------------------------|------------------------|
+| Running kernel            | `linux612 6.12.77-1`   |
+| NVIDIA driver             | `575.64.05-3` (575xx branch) |
+| NVIDIA kernel module pkg  | `linux612-nvidia-575xx 575.64.05-31` |
+| `linux70` available in repo | `7.0.3-1`            |
+| `linux70-nvidia` available  | `595.71.05-0.1`      |
+| `linux612-nvidia` (mainline) | `595.71.05-2`       |
+
+## Decision
+1. **Run two kernels side by side.**
+   - Keep `linux612` (LTS 6.12.x) installed as the *fallback* boot entry.
+   - Install `linux70` (stable 7.0.x) and select it as the daily-driver
+     kernel via GRUB at the next reboot.
+2. **Migrate NVIDIA from the `575xx` branch to mainline `595.71`** in
+   one atomic pacman transaction so both kernels have matching modules:
+   - Remove: `linux612-nvidia-575xx`, `nvidia-575xx-utils`,
+     `lib32-nvidia-575xx-utils`, `nvidia-575xx-settings`.
+   - Install: `linux612-nvidia`, `linux70-nvidia`, `nvidia-utils`,
+     `lib32-nvidia-utils`, `opencl-nvidia`, `nvidia-settings`.
+3. **Do not change `GRUB_DEFAULT` programmatically.** The user picks
+   `linux70` from the GRUB menu on first boot. If `linux70` misbehaves,
+   the next reboot is one menu selection away from the proven LTS path.
+4. **Encapsulate everything in an idempotent Ansible role**
+   (`ansible/roles/system-upgrade/`) that runs **before** `common`,
+   `dev-tools` and `maintenance`. It is invoked stand-alone with
+   `--tags system-upgrade` and is safe on every subsequent run.
+
+## Rationale
+- **LTS as a parachute.** 6.12 is a Linux LTS series with a multi-year
+  support window. Keeping it installed makes the migration reversible by
+  one keystroke in GRUB.
+- **7.0 as the daily driver.** The 7.0 series brings the maturest
+  DRM/atomic-modeset and NVIDIA explicit-sync paths that Hyprland on
+  Pascal needs to avoid flicker on multi-monitor.
+- **Mainline 595.71 over pinned 575.64.05.** Manjaro builds
+  `linux70-nvidia` only against `nvidia-utils=595.71.05`, so the 575xx
+  branch is not an option for the new kernel. Pascal (GP107) is fully
+  supported by 595.x, and 595.x ships the latest explicit-sync /
+  modesetting fixes upstream.
+- **Single atomic transaction.** Removing the old branch and installing
+  the new one in one pacman call (with the removal list narrowed to
+  packages that are *actually* installed) keeps the GPU-driver window
+  to roughly one second of cache I/O on a local SSD.
+- **Idempotent role over shell script.** Matches the existing
+  `common`/`dev-tools`/`maintenance` pattern, supports `--check`, and
+  re-running after success is a true no-op (validated by gating every
+  mutating task on `pacman_syu.changed or nvidia_migration.changed`).
+
+## Consequences
+- **Two kernels on `/` partition.** Roughly +120 MB for `linux70` plus
+  ~50 MB for `linux70-nvidia`. The role pre-flight refuses to start if
+  free space on `/` is below 5 GiB.
+- **`mhwd` profile referencing `575xx` stays as-is.** Only the
+  kernel-bound `linux612-nvidia-575xx` and matching userspace are
+  swapped; `mhwd-nvidia-575xx` stays installed so MHWD's profile
+  listing remains consistent. A future cleanup can switch the MHWD
+  profile to `video-nvidia` once `linux70` is verified.
+- **Manual reboot required.** The role never reboots the machine; it
+  ends with a clear notice instructing the user to boot into `linux70`
+  from GRUB before applying the next (Hyprland) playbook.
+- **Future kernel pin bumps are one-line changes** in
+  `ansible/vars/main.yml` (`kernel_packages` /
+  `nvidia_kernel_modules` lists).
+
+## References
+- Hyprland NVIDIA notes (wiki.hypr.land/Nvidia): explicit sync
+  available from driver ≥555 and required for tear-free Wayland.
+- `docs/tech/hardware-inventory.md` (NVIDIA section).
+- `ansible/roles/system-upgrade/tasks/main.yml`.
+- ADR 1: `docs/adr/0001-use-ansible-for-configuration.md` — anchors the
+  "Ansible-first" guardrail this decision follows.