docs: update hardware/setup docs and add install script

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

docs/tech/setup.md

@@ -5,7 +5,7 @@ tags:
   - setup
   - bootstrap
   - ansible
-last_updated: '2026-03-09'
+last_updated: '2026-05-18'
 ---
 
 # Workstation Setup Guide
@@ -41,14 +41,38 @@ This guide describes how to bootstrap the **mw-pfeddersheim-workstation** infras
    ansible-vault create ansible/vars/secrets.yml
    ```
 
-4. **Run the Playbook**
+4. **Run system upgrade & kernel install** (preparation for Hyprland/Wayland)
+
+   This step runs the dedicated `system-upgrade` role: full `pacman -Syu`,
+   dual-kernel install (`linux612` LTS + `linux70` stable), and NVIDIA
+   driver migration from the pinned `575xx` branch to mainline `595.71`.
+   Always preview first with `--check`. See
+   [ADR 0002](../adr/0002-kernel-and-nvidia-strategy.md) for the rationale.
+
+   ```bash
+   # Preview — never run the live playbook before --check is clean
+   ansible-playbook -i localhost, -c local \
+     --vault-password-file ansible/vault_password \
+     ansible/workstation.yml --check --tags system-upgrade
+
+   # Apply (will install/remove packages and regenerate GRUB)
+   ansible-playbook -i localhost, -c local \
+     --vault-password-file ansible/vault_password \
+     ansible/workstation.yml --tags system-upgrade
+   ```
+
+   After it finishes, **reboot and select `linux70` from the GRUB menu**
+   before continuing to step 5. Verify with `uname -r` (expect 7.0.x)
+   and `nvidia-smi` (expect driver 595.71.05).
+
+5. **Run the Playbook** (remaining roles: common, dev-tools, maintenance)
    ```bash
    ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml --check
    # If check passes:
    ansible-playbook -i localhost, -c local --vault-password-file ansible/vault_password ansible/workstation.yml
    ```
 
-5. **Initialize Maintenance**
+6. **Initialize Maintenance**
    ```bash
    ./scripts/maintenance.sh
    ```