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`

home/sam/home.nix

@@ -1,5 +1,14 @@
 { config, pkgs, ... }:
 
+let
+  # After install, Integral300 is mounted at /data (per your NixOS config).
+  # These dotfiles are stored on that drive.
+  dotfilesDir = "/data/home_sam_ubuntu/dotfiles";
+
+  # Home Manager helper to symlink files/dirs that live outside the Nix store.
+  # This is the correct mechanism for "dotfiles stored on /data".
+  mkOOS = config.lib.file.mkOutOfStoreSymlink;
+in
 {
   home.stateVersion = "24.05";
 
@@ -26,12 +35,24 @@
       tree = "eza --tree";
       cat = "bat --color=always --paging=never";
     };
+
+    # Dotfiles integration notes:
+    # - I am NOT symlinking ~/.zshrc directly because Home Manager manages it.
+    # - If you have extra Zsh snippets in your dotfiles repo that you want sourced,
+    #   tell me the exact filename(s) and we’ll add them here safely.
+    initExtra = ''
+      # Optional: source additional Zsh config from /data dotfiles if you want.
+      # Example (uncomment + adjust if you confirm the exact file path):
+      # if [ -f "${dotfilesDir}/zsh/extra.zsh" ]; then
+      #   source "${dotfilesDir}/zsh/extra.zsh"
+      # fi
+    '';
   };
 
   programs.powerlevel10k = {
     enable = true;
-    # Optional: link your p10k config once you add it to the repo
+    # If you have a real p10k config file in dotfiles, tell me its exact path.
-    # home.file.".p10k.zsh".source = ./p10k.zsh;
+    # Then we can symlink it to ~/.p10k.zsh (or source it) reliably.
   };
 
   # ---
@@ -89,6 +110,26 @@
     p7zip
   ];
 
+  # ---
+  # Dotfiles (out-of-store symlinks from /data)
+  # ---
+  # IMPORTANT:
+  # - These paths must exist on the machine at activation time.
+  # - This assumes your dotfiles are available at:
+  #     /data/home_sam_ubuntu/dotfiles/<app>
+  # - If you rename/move the dotfiles directory, update dotfilesDir above.
+  home.file.".config/atuin".source = mkOOS "${dotfilesDir}/atuin";
+  home.file.".config/kitty".source = mkOOS "${dotfilesDir}/kitty";
+  home.file.".config/nvim".source = mkOOS "${dotfilesDir}/nvim";
+  home.file.".config/zellij".source = mkOOS "${dotfilesDir}/zellij";
+
+  # TODO (needs confirmation from you):
+  # - zsh dotfiles: what exact files do you want sourced/linked?
+  # - pk10k: what is the exact filename for your p10k config?
+  #
+  # Once you confirm, we can add e.g.:
+  # home.file.".p10k.zsh".source = mkOOS "${dotfilesDir}/pk10k/.p10k.zsh";
+
   # ---
   # Secrets policy
   # ---