feat: link dotfiles via Home Manager and add NVMe install guide

Co-authored-by: aider (openrouter/openai/gpt-5.2) <aider@aider.chat>

docs/INSTALL_NIXOS_WIPE_NVME_FLAKE.md

@@ -0,0 +1,168 @@
+# NixOS Install Guide (wipe NVMe, install from flake on Integral300)
+
+This guide assumes:
+- You are currently on Ubuntu
+- You will WIPE the entire NVMe: /dev/nvme0n1
+- You will install NixOS with:
+  - UEFI + systemd-boot
+  - Btrfs with subvolumes (@ and @home)
+  - No encryption
+  - zram swap (configured in NixOS config)
+- Your config repo is a flake with output: `#sam-4screen-desktop`
+- Integral300 (ext4) is available and will be mounted on NixOS at: /data
+  - UUID: 27febd74-20aa-4a3a-92c1-6fdd1ad7e88e
+
+Important constraints:
+- `hosts/sam-4screen-desktop/hardware-configuration.nix` is currently a placeholder.
+  You MUST generate and copy the real one during install before running nixos-install.
+
+---
+
+## A) On Ubuntu: prepare and push the config repo to Gitea
+
+1) Go to your repo folder (example):
+   - If your repo is on Integral300 already:
+     - `cd /media/sam/Integral300/<your-repo-folder>`
+   - Otherwise clone it to Integral300:
+     - `cd /media/sam/Integral300`
+     - `git clone ssh://git@<your-gitea-host>:<port>/<owner>/<repo>.git nixos-config`
+     - `cd nixos-config`
+
+2) Ensure the flake evaluates:
+   - `nix --version`
+   - `nix flake show`
+
+3) Commit your changes:
+   - `git status`
+   - `git add -A`
+   - `git commit -m "chore: prep install guide + dotfiles links"`
+
+4) Push to Gitea:
+   - `git push`
+
+If you don’t have `flake.lock` yet, you can create it:
+- `nix flake lock`
+Then commit/push it too.
+
+---
+
+## B) Boot NixOS installer (ISO)
+
+1) Boot the NixOS ISO (graphical or minimal).
+2) Open a terminal.
+
+---
+
+## C) Wipe / partition / format / mount (CLI method)
+
+WARNING: This wipes the whole NVMe. Double-check the disk is correct.
+
+### 1) Identify disks
+- `lsblk -f`
+Confirm:
+- NVMe target: /dev/nvme0n1 (about 953G)
+- Integral300 disk by UUID is present: 27febd74-20aa-4a3a-92c1-6fdd1ad7e88e
+
+### 2) Wipe and create partitions
+This creates:
+- p1 = EFI (1GiB)
+- p2 = Btrfs (rest)
+
+Commands:
+- `sudo wipefs -a /dev/nvme0n1 || true`
+- `sudo sgdisk --zap-all /dev/nvme0n1`
+
+- `sudo sgdisk -n 1:1MiB:+1GiB -t 1:EF00 -c 1:EFI /dev/nvme0n1`
+- `sudo sgdisk -n 2:0:0       -t 2:8300 -c 2:NIXOS /dev/nvme0n1`
+
+Verify:
+- `sudo fdisk -l /dev/nvme0n1`
+
+### 3) Format
+- `sudo mkfs.fat -F32 -n EFI /dev/nvme0n1p1`
+- `sudo mkfs.btrfs -L nixos /dev/nvme0n1p2`
+
+### 4) Create Btrfs subvolumes
+- `sudo mount /dev/nvme0n1p2 /mnt`
+- `sudo btrfs subvolume create /mnt/@`
+- `sudo btrfs subvolume create /mnt/@home`
+- `sudo umount /mnt`
+
+### 5) Mount target layout for install
+- `sudo mount -o subvol=@,compress=zstd,noatime /dev/nvme0n1p2 /mnt`
+- `sudo mkdir -p /mnt/home`
+- `sudo mount -o subvol=@home,compress=zstd,noatime /dev/nvme0n1p2 /mnt/home`
+
+Mount EFI at /mnt/boot (systemd-boot expects /boot):
+- `sudo mkdir -p /mnt/boot`
+- `sudo mount /dev/nvme0n1p1 /mnt/boot`
+
+### 6) Mount Integral300 so we can access the flake repo (offline-friendly)
+- `sudo mkdir -p /mnt/data`
+- `sudo mount /dev/disk/by-uuid/27febd74-20aa-4a3a-92c1-6fdd1ad7e88e /mnt/data`
+
+---
+
+## D) Generate hardware-configuration.nix (REQUIRED)
+
+1) Generate:
+- `sudo nixos-generate-config --root /mnt`
+
+2) Copy the generated hardware config into your repo (overwrite placeholder):
+- If your repo is at `/mnt/data/nixos-config`:
+  - `sudo cp /mnt/etc/nixos/hardware-configuration.nix /mnt/data/nixos-config/hosts/sam-4screen-desktop/hardware-configuration.nix`
+
+If your repo folder name is different, adjust accordingly.
+
+Optional sanity check:
+- `sed -n '1,200p' /mnt/data/nixos-config/hosts/sam-4screen-desktop/hardware-configuration.nix`
+
+---
+
+## E) Install NixOS using the flake
+
+From the installer environment, run:
+- `sudo nixos-install --flake /mnt/data/nixos-config#sam-4screen-desktop`
+
+Notes:
+- The installer may ask you to set a root password. Do so.
+- If you prefer not setting root password and using only your user + sudo, say so and we can adjust.
+
+After install:
+- `sudo reboot`
+
+---
+
+## F) First boot checklist (post-install)
+
+1) Connect to Wi-Fi:
+- `nmtui` (recommended)
+- Connect to SSID: "Aussie Broadband 8729"
+
+2) Verify static IP:
+- `ip a show wlp4s2`
+If it got DHCP, force one reconnect:
+- `nmcli networking off; nmcli networking on`
+or:
+- `nmcli connection down "<connection name>"; nmcli connection up "<connection name>"`
+
+3) Verify SSH works (from another machine):
+- `ssh sam@192.168.20.27`
+
+4) Verify /data mounted:
+- `mount | grep ' /data '`
+- `ls -la /data/home_sam_ubuntu/dotfiles`
+
+5) Home Manager activation:
+- `home-manager` is integrated via NixOS switch; it should apply on rebuild.
+- If dotfiles symlinks fail, confirm `/data` is mounted and the dotfiles paths exist.
+
+---
+
+## G) After install: commit the new hardware-configuration.nix
+Back on your running system (or from Ubuntu before wiping, if you mounted and copied it there):
+- `cd /data/nixos-config` (or wherever your repo is)
+- `git status`
+- `git add hosts/sam-4screen-desktop/hardware-configuration.nix`
+- `git commit -m "feat: add generated hardware-configuration for sam-4screen-desktop"`
+- `git push`