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

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

.gitignore

@@ -1 +1,19 @@
 .aider*
+
+# Do not commit generated drafts that may contain secrets
+results/generated_home.nix
+
+# Optional: ignore all generated results drafts (keep if you don't want them tracked)
+# results/generated_*.nix
+
+# Common secret/env files (never commit)
+.env
+.env.*
+*.pem
+*.key
+*.p12
+
+# Nix build artifacts
+result
+result-*
+.nixos-*

1)

@@ -0,0 +1 @@
+git ls-files results/generated_home.nix

1) Output of

@@ -0,0 +1 @@
+git ls-files results/generated_home.nix

1) Paste the output of

@@ -0,0 +1 @@
+git ls-files results/generated_home.nix

2) If it prints the file (meaning it’s tracked)

@@ -0,0 +1 @@
+git rm --cached results/generated_home.nix

Also confirm whether `flake.lock` exists in the repo right now. If it doesn’t, run

@@ -0,0 +1,3 @@
+nix flake lock
+git add flake.lock
+git commit -m "Add flake.lock"

Please run and paste the output of

@@ -0,0 +1 @@
+git ls-files results/generated_home.nix

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`

docs/nixos_build_spec.md

@@ -0,0 +1,68 @@
+# NixOS Build Spec (sam-4screen-desktop)
+
+## Disk / Boot (DO NOT BRICK WINDOWS)
+Target disk: /dev/nvme0n1
+- Size: 953.87 GiB (1024209543168 bytes), 2000409264 sectors
+- Model: PM951 NVMe SAMSUNG 1024GB
+- NVMe serial: S2FZNXAH301424
+- NVMe WWID: nvme.144d-2020202020205332465a4e584148333031343234-504d393531204e564d652053414d53554e4720313032344742-00000001
+- Sector size (logical/physical): 512 bytes / 512 bytes
+Install target is NVMe only. Do not select /dev/sdX devices in the installer.
+Device names like /dev/sdb, /dev/sdc can change across boots; always rely on UUID/label.
+
+NOTE: GPT partition table entries may not be stored/printed in on-disk (Start sector) order.
+- Do NOT rely on the order shown by some tools.
+- Always identify partitions by (partition number + type + UUID/label).
+- If you need the physical order, sort by the “Start” sector column (e.g. `fdisk -l` output).
+
+Verification commands (run before formatting):
+- `lsblk -o NAME,SIZE,TYPE,FSTYPE,LABEL,UUID,MOUNTPOINTS`
+- `sudo fdisk -l /dev/nvme0n1` (interpret physical order by sorting on Start)
+- `sudo blkid /dev/nvme0n1p1 /dev/nvme0n1p3 /dev/nvme0n1p4 /dev/nvme0n1p5`
+
+KEEP (do not format):
+- /dev/nvme0n1p1 (EFI vfat) UUID=94CC-9DA4 (~99MiB, FAT32, mounted at /boot/efi)
+- /dev/nvme0n1p2 (MS reserved) (~15MiB)
+- /dev/nvme0n1p3 (Windows NTFS) UUID=8294CD2994CD2111 (~503GiB)
+- /dev/nvme0n1p4 (Windows recovery NTFS) UUID=6E1AA32B1AA2EEF1 (~529MiB)
+
+WIPE + install NixOS here:
+- /dev/nvme0n1p5 (currently Ubuntu ext4 /) UUID=4e99904c-ce6f-4c3c-898a-e29cfc373489 (~449GiB)
+
+## Other attached disks (DO NOT FORMAT)
+- /dev/sda (240GB) model: Patriot Burst El (KEEP)
+  - /dev/sda1: Microsoft reserved partition (~15MiB)
+  - /dev/sda2: NTFS label "Back Up" (keep)
+- TempBackup (ext4) UUID=4f9c4bd5-fea5-408f-9370-731fc095da3f (~465GiB/500GB) (KEEP)
+  - Model: WD5000BEVT-22ZAT
+  - Serial: WD-WXNY08ND2684
+  - NOTE: device name may appear as /dev/sdb or /dev/sdc depending on boot/USB order; identify by UUID/label/model.
+- Integral300 (ext4) UUID=27febd74-20aa-4a3a-92c1-6fdd1ad7e88e (~298GiB/320GB) (mount at /data)
+  - NOTE: device name may change; config always uses /dev/disk/by-uuid.
+- XPSystemDrive (ext4) UUID=82c994f1-9adb-49e4-ba1e-5b6e5ccbd49b (~149GiB/160GB) (KEEP)
+  - Model: HTS541616J9SA00 (Hitachi)
+  - NOTE: device name may appear as /dev/sdX depending on boot/USB order; identify by UUID/label/model.
+  - Observed in hardware scan: `/dev/sde` (do not rely on this).
+
+Bootloader:
+- systemd-boot, using the existing EFI partition (/dev/nvme0n1p1)
+
+## Networking
+- Use NetworkManager
+- Static IPv4 for wired: enp0s31f6 = 192.168.20.27/24
+- Gateway: 192.168.20.1
+- DNS: 192.168.20.35, 192.168.20.13
+
+## Data drive mount
+- Integral300 ext4 UUID=27febd74-20aa-4a3a-92c1-6fdd1ad7e88e
+- Mountpoint on NixOS: /data (preferred)
+
+## Desktop
+- Primary compositor: Niri
+- Display/login manager: greetd + tuigreet
+- Session start command: `niri --session` (do not use `niri-session`)
+- GPU: Intel HD 630 + NVIDIA Quadro P620
+- Display appears to be driven by NVIDIA Quadro P620 (observed `/dev/fb0` on Ubuntu scan). Treat NVIDIA as primary unless proven otherwise.
+
+## Secrets policy
+- No API keys or WiFi PSKs committed to git

docs/software_inventory.md

@@ -0,0 +1,181 @@
+# Software Inventory (Source of Truth)
+
+This document is the canonical software list for the NixOS migration.
+It consolidates prior notes and recon logs into a deduplicated plan.
+
+Legend:
+- **NOW (Base boot / day-1)** = required for first successful NixOS boot and daily workflow basics
+- **SOON** = useful early, but not required to boot and log in
+- **LATER** = intentionally deferred until after a stable base system
+- **DEFER (Docker later)** = explicitly not installed on base system (will be deployed as containers later)
+
+---
+
+## 1) NOW (Base boot / day-1)
+
+### Desktop / session (Wayland)
+- **niri** (primary compositor)
+- **greetd + tuigreet** (display/login manager)
+- **xwayland** (X11 compatibility where needed)
+- **xdg-desktop-portal** + **xdg-desktop-portal-gtk** + **xdg-desktop-portal-gnome** (portals baseline; improves screencast/screen share odds)
+- Clipboard:
+  - **wl-clipboard**
+- Screenshots (Wayland):
+  - **grim**
+  - **slurp**
+
+### Core system services
+- **NetworkManager**
+  - Static IPv4 for wired: `enp0s31f6 = 192.168.20.27/24`
+  - Gateway: `192.168.20.1`
+  - DNS: `192.168.20.35`, `192.168.20.13`
+- **OpenSSH server** (sshd)
+- **PipeWire audio** (Pulse + ALSA) + **WirePlumber**
+- **Firewall** (NixOS default; open SSH port only)
+
+### Terminal / shell
+- **kitty**
+- **zsh**
+  - **oh-my-zsh**
+  - **powerlevel10k**
+  - Integrations enabled:
+    - **atuin**
+    - **fzf**
+    - **zoxide**
+
+### Core CLI tools (daily essentials)
+- **git**
+- **neovim**
+- Search/file tools:
+  - **ripgrep (rg)**
+  - **fd**
+- Modern replacements:
+  - **bat**
+  - **eza**
+- Convenience:
+  - **curl**
+  - **wget**
+
+---
+
+## 2) SOON (after base boot is stable)
+
+These are commonly used, easy wins, but not required for “first login”.
+
+### Dev tools
+- Compilers / build:
+  - **gcc**
+  - **gnumake**
+  - **pkg-config**
+- Language toolchains (pick pinned versions later):
+  - **nodejs**
+  - **python3** (+ `python3Packages.pip` as needed)
+  - **go**
+  - Rust strategy: prefer **rustup** if you need toolchain flexibility, otherwise `rustc`/`cargo` from nixpkgs.
+
+### CLI utilities commonly used in the previous setup
+- **jq**
+- **btop**
+- **lazygit**
+- **zellij**
+- **tealdeer (tldr)**
+- **navi**
+- **yazi**
+- **dua-cli (dua)**
+- **unzip / zip / p7zip**
+- Clipboard (X11 fallback / mixed):
+  - **xclip** (optional; Wayland-first systems typically rely on `wl-clipboard`)
+
+### Apps from Ubuntu recon (snap list) with Nix equivalents
+From `logs/04_nixos_recon.log` snap list:
+- `code` → **vscode** (unfree)
+- `firefox` → **firefox**
+- `thunderbird` → **thunderbird**
+- `telegram-desktop` → **telegram-desktop**
+- `spotify` → **spotify** (unfree)
+- `nushell` → **nushell**
+- `mqtt-explorer` → **mqtt-explorer** (verify availability in nixpkgs)
+- `notepad-plus-plus` → consider **notepadqq** or run via Wine (see “LATER”)
+
+---
+
+## 3) LATER (deliberately deferred until base is reliable)
+
+### Desktop apps / optional GUI
+- **Google Chrome** (unfree) (install once graphics/session is stable)
+- **LibreOffice**
+- **VLC**
+- **Flameshot**
+  - Note: Flameshot on Wayland can be quirky; ensure portals + permissions work first.
+- **Timeshift**
+  - Note: NixOS typically prefers rollback/snapshots via filesystem tooling (e.g., Btrfs snapshots). Use only if you explicitly want it.
+
+### Remote desktop / admin tools
+- **Tailscale** (client)
+- **RustDesk** (service/app)
+
+### Networking / diagnostics tools (as needed)
+- **nmap**
+- **arp-scan / arpwatch**
+- **minicom / screen / cu**
+- **ethtool**
+- **tcpdump**
+
+### Notepad++ situation
+- `notepad-plus-plus` snap existed on Ubuntu.
+  - NixOS options:
+    - **notepadqq** (native)
+    - **Wine** route (more moving parts)
+  - Keep this until the base system is stable.
+
+---
+
+## 4) DEFER (Docker later)
+
+These are explicitly postponed and should NOT be part of the base NixOS install.
+
+- **Apprise** — **DEFER (Docker later)**
+- **Obsidian** — **DEFER (Docker later)**
+
+---
+
+## 5) AI / Agentic stack (LATER; not part of base boot)
+
+From `ai_dev_plan.md` and `software_to_add.md`, intentionally excluded from day-1:
+
+- Orchestration / pipelines:
+  - **Airflow**
+  - **Windmill**
+  - **Activepieces**
+- Prototyping:
+  - **Flowise**
+- RAG / DB:
+  - **Chroma**
+- Crawling:
+  - **Selenium / Playwright**
+  - **Firecrawl**
+- Agent frameworks:
+  - **LangChain / LangGraph**
+- CLI AI tools:
+  - **Aider**
+  - **OpenCode**
+  - **Gemini CLI**
+  - **Goose / MCP tooling**
+- Model routing:
+  - **OpenRouter**
+
+Plan: bring these up later via Docker Compose on top of a stable NixOS base.
+
+---
+
+## 6) Notes / policies
+
+### Secrets policy (hard requirement)
+- Do **not** commit API keys, tokens, WiFi PSKs, certificates, or private keys into git.
+- Prefer:
+  - `~/.config/environment.d/*.conf` (local-only)
+  - a secrets manager (e.g. **sops-nix**) once the base system is stable
+
+### Graphics strategy note (pending confirmation)
+- Hardware includes Intel HD 630 + NVIDIA Quadro P620.
+- Final graphics configuration will depend on which GPU is actually driving the 4 monitors.

flake.nix

@@ -0,0 +1,35 @@
+{
+  description = "sam-4screen-desktop NixOS + Home Manager flake";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
+    home-manager = {
+      url = "github:nix-community/home-manager/release-24.05";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, home-manager, ... }:
+    let
+      system = "x86_64-linux";
+    in
+    {
+      nixosConfigurations.sam-4screen-desktop = nixpkgs.lib.nixosSystem {
+        inherit system;
+
+        modules = [
+          # Allow unfree (Chrome/Spotify/VSCode/NVIDIA, etc.)
+          { nixpkgs.config.allowUnfree = true; }
+
+          ./hosts/sam-4screen-desktop/configuration.nix
+
+          home-manager.nixosModules.home-manager
+          {
+            home-manager.useGlobalPkgs = true;
+            home-manager.useUserPackages = true;
+            home-manager.users.sam = import ./home/sam/home.nix;
+          }
+        ];
+      };
+    };
+}

home/sam/home.nix

@@ -0,0 +1,140 @@
+{ 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";
+
+  programs.home-manager.enable = true;
+
+  # ---
+  # Shell (zsh + oh-my-zsh + powerlevel10k)
+  # ---
+  programs.zsh = {
+    enable = true;
+    autosuggestion.enable = true;
+    syntaxHighlighting.enable = true;
+
+    oh-my-zsh = {
+      enable = true;
+      theme = "powerlevel10k/powerlevel10k";
+      plugins = [ "git" ];
+    };
+
+    shellAliases = {
+      ls = "eza --icons --git";
+      ll = "eza -l --icons --git";
+      la = "eza -la --icons --git";
+      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;
+    # If you have a real p10k config file in dotfiles, tell me its exact path.
+    # Then we can symlink it to ~/.p10k.zsh (or source it) reliably.
+  };
+
+  # ---
+  # Shell tools
+  # ---
+  programs.atuin = {
+    enable = true;
+    enableZshIntegration = true;
+  };
+
+  programs.fzf = {
+    enable = true;
+    enableZshIntegration = true;
+  };
+
+  programs.zoxide = {
+    enable = true;
+    enableZshIntegration = true;
+  };
+
+  # ---
+  # Terminal / editor
+  # ---
+  programs.kitty.enable = true;
+
+  programs.neovim = {
+    enable = true;
+    defaultEditor = true;
+  };
+
+  # ---
+  # Packages (NOW list + a few safe essentials)
+  # ---
+  home.packages = with pkgs; [
+    git
+    curl
+    wget
+
+    eza
+    bat
+    ripgrep
+    fd
+
+    btop
+    lazygit
+    zellij
+    tealdeer
+    navi
+    yazi
+    dua
+    jq
+
+    unzip
+    zip
+    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
+  # ---
+  # Do NOT put API keys here (or anywhere in git).
+  # Preferred approach (local-only):
+  #   ~/.config/environment.d/10-secrets.conf
+  # or add sops-nix later.
+}

hosts/sam-4screen-desktop/configuration.nix

@@ -0,0 +1,235 @@
+{ config, pkgs, lib, ... }:
+
+{
+  imports = [
+    ./hardware-configuration.nix
+  ];
+
+  # ---
+  # Nix (enable flakes on the installed system)
+  # ---
+  nix.settings.experimental-features = [ "nix-command" "flakes" ];
+
+  # ---
+  # Bootloader / kernel
+  # ---
+  boot.loader.systemd-boot.enable = true;
+  boot.loader.efi.canTouchEfiVariables = true;
+
+  # Known-good baseline from niri-4screen.md
+  boot.kernelParams = [ "intel_iommu=off" "dev_mem_signed_off=1" ];
+
+  # ---
+  # Identity
+  # ---
+  networking.hostName = "sam-4screen-desktop";
+  time.timeZone = "Australia/Sydney";
+
+  # ---
+  # Networking
+  # ---
+  networking.networkmanager.enable = true;
+
+  # Static IP policy:
+  # - You confirmed the static IP must be on Wi-Fi SSID "Aussie Broadband 8729"
+  # - Do NOT store Wi-Fi secrets (PSK) in git-tracked Nix files
+  #
+  # Approach:
+  # - Connect to Wi-Fi normally via nmtui/nmcli/GUI (credentials stored locally by NM)
+  # - On activation, this dispatcher script enforces the static IP/DNS/gateway
+  #   only for that SSID on interface wlp4s2.
+  environment.etc."NetworkManager/dispatcher.d/10-wlp4s2-static-ip-aussie-broadband-8729".source =
+    pkgs.writeShellScript "10-wlp4s2-static-ip-aussie-broadband-8729" ''
+      set -euo pipefail
+
+      IFACE="$1"
+      STATUS="$2"
+
+      TARGET_ID="Aussie Broadband 8729"
+      NMCLI="${pkgs.networkmanager}/bin/nmcli"
+
+      # Only touch the Wi-Fi interface you specified.
+      if [[ "$IFACE" != "wlp4s2" ]]; then
+        exit 0
+      fi
+
+      # Apply on pre-up/up so settings are in place as early as possible.
+      case "$STATUS" in
+        pre-up|up) ;;
+        *) exit 0 ;;
+      esac
+
+      # NetworkManager dispatcher provides these env vars.
+      # If they are missing, we can't safely target the right connection.
+      if [[ -z "''${CONNECTION_UUID:-}" ]]; then
+        exit 0
+      fi
+
+      # Ensure it is actually a Wi-Fi connection.
+      TYPE="$("$NMCLI" -g connection.type connection show "$CONNECTION_UUID" 2>/dev/null || true)"
+      if [[ "$TYPE" != "802-11-wireless" ]]; then
+        exit 0
+      fi
+
+      # Determine the connection "id" (name). This is typically the SSID, but not always.
+      CONN_ID="$("$NMCLI" -g connection.id connection show "$CONNECTION_UUID" 2>/dev/null || true)"
+      if [[ "$CONN_ID" != "$TARGET_ID" ]]; then
+        exit 0
+      fi
+
+      # Enforce your confirmed static IPv4 configuration.
+      "$NMCLI" connection modify "$CONNECTION_UUID" \
+        ipv4.method manual \
+        ipv4.addresses "192.168.20.27/24" \
+        ipv4.gateway "192.168.20.1" \
+        ipv4.dns "192.168.20.35 192.168.20.13" \
+        ipv4.ignore-auto-dns yes \
+        ipv6.method auto
+
+      # NOTE:
+      # This modifies the connection profile. If the connection is already "up",
+      # you may need to reconnect once for all settings to apply immediately:
+      #   nmcli connection down "$CONNECTION_UUID"
+      #   nmcli connection up "$CONNECTION_UUID"
+
+      exit 0
+    '';
+
+  environment.etc."NetworkManager/dispatcher.d/10-wlp4s2-static-ip-aussie-broadband-8729".mode = "0755";
+
+  # ---
+  # Users
+  # ---
+  programs.zsh.enable = true;
+
+  users.users.sam = {
+    isNormalUser = true;
+    description = "Sam";
+    extraGroups = [ "wheel" "networkmanager" "docker" "video" "render" ];
+    shell = pkgs.zsh;
+  };
+
+  # greetd runs the greeter session as this user; it must exist.
+  users.groups.greeter = { };
+  users.users.greeter = {
+    isSystemUser = true;
+    group = "greeter";
+    home = "/var/lib/greeter";
+    createHome = true;
+  };
+
+  # ---
+  # SSH
+  # ---
+  services.openssh.enable = true;
+  services.openssh.openFirewall = true;
+  # Defaulting to keys-only for safety. If you explicitly want password auth for the migration,
+  # flip this to true.
+  services.openssh.settings.PasswordAuthentication = false;
+
+  # Explicitly enable firewall (keep SSH as the only opened port via openFirewall above).
+  networking.firewall.enable = true;
+
+  # ---
+  # dconf (helps portals/GTK apps)
+  # ---
+  programs.dconf.enable = true;
+
+  # Polkit is commonly required for a smooth experience with portals and desktop actions,
+  # especially in minimal Wayland sessions.
+  security.polkit.enable = true;
+
+  # ---
+  # Firmware / microcode (stability)
+  # ---
+  hardware.enableRedistributableFirmware = true;
+  hardware.cpu.intel.updateMicrocode = true;
+
+  # ---
+  # OpenGL (important for NVIDIA Wayland apps)
+  # ---
+  hardware.opengl = {
+    enable = true;
+    driSupport = true;
+    driSupport32Bit = true;
+  };
+
+  # ---
+  # Audio (PipeWire)
+  # ---
+  security.rtkit.enable = true;
+  services.pipewire = {
+    enable = true;
+    pulse.enable = true;
+    alsa.enable = true;
+    alsa.support32Bit = true;
+    wireplumber.enable = true;
+  };
+
+  # ---
+  # Swap (zram; no hibernation)
+  # ---
+  zramSwap.enable = true;
+
+  # ---
+  # Docker
+  # ---
+  virtualisation.docker.enable = true;
+
+  # ---
+  # Mounts
+  # ---
+  fileSystems."/data" = {
+    device = "/dev/disk/by-uuid/27febd74-20aa-4a3a-92c1-6fdd1ad7e88e";
+    fsType = "ext4";
+    options = [ "nofail" "x-systemd.device-timeout=1s" ];
+  };
+
+  # ---
+  # Niri + login (greetd)
+  # ---
+  services.greetd = {
+    enable = true;
+    settings = {
+      default_session = {
+        user = "greeter";
+        command =
+          "${pkgs.greetd.tuigreet}/bin/tuigreet --time --remember --cmd ${
+            lib.escapeShellArg "${pkgs.niri}/bin/niri --session"
+          }";
+      };
+    };
+  };
+
+  # Wayland portals (refine later if screencast needs a different backend)
+  xdg.portal = {
+    enable = true;
+    extraPortals = [
+      pkgs.xdg-desktop-portal-gtk
+      pkgs.xdg-desktop-portal-gnome
+    ];
+  };
+
+  # Minimal system packages needed for the session and core usability
+  environment.systemPackages = with pkgs; [
+    niri
+    greetd.tuigreet
+    xwayland
+    wl-clipboard
+    grim
+    slurp
+  ];
+
+  # ---
+  # NVIDIA (simple, first-boot stable config; PRIME tuning later)
+  # ---
+  services.xserver.videoDrivers = [ "nvidia" ];
+  hardware.nvidia.modesetting.enable = true;
+  hardware.nvidia.nvidiaSettings = true;
+  hardware.nvidia.nvidiaPersistenced = true;
+
+  # ---
+  # NixOS release compatibility
+  # ---
+  system.stateVersion = "24.05";
+}

hosts/sam-4screen-desktop/hardware-configuration.nix

@@ -0,0 +1,18 @@
+# -----------------------------------------------------------------------------
+# PLACEHOLDER hardware-configuration.nix
+#
+# Replace this file with the REAL generated hardware configuration from the
+# NixOS installer before installing / switching to this host configuration.
+#
+# How:
+# 1) Boot the NixOS installer ISO
+# 2) Partition/mount target as planned
+# 3) Run: nixos-generate-config --root /mnt
+# 4) Copy the generated /mnt/etc/nixos/hardware-configuration.nix into:
+#    hosts/sam-4screen-desktop/hardware-configuration.nix
+# -----------------------------------------------------------------------------
+
+{ config, lib, pkgs, modulesPath, ... }:
+
+{
+}

logs/06_netplan_config.log

@@ -17,7 +17,7 @@
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:        "Aussie Broadband 8729":
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:          auth:
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:            key-management: "psk"
-/etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:            password: "Ffdfmunfca"
+/etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:            password: "<REDACTED>"
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:          networkmanager:
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:            uuid: "31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4"
 /etc/netplan/90-NM-31ac1c6a-4de8-4a3e-929f-aaec5cd53cf4.yaml:            name: "Aussie Broadband 8729"
@@ -73,7 +73,7 @@
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:        "NetComm Wireless":
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:          auth:
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:            key-management: "psk"
-/etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:            password: "Ffdfmunfca"
+/etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:            password: "<REDACTED>"
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:          networkmanager:
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:            uuid: "ecfc8be2-ba84-46e9-89c6-75bcb35cba55"
 /etc/netplan/90-NM-ecfc8be2-ba84-46e9-89c6-75bcb35cba55.yaml:            name: "NetComm Wireless"
@@ -99,7 +99,7 @@
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:        "Sams Pixel 8a":
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:          auth:
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:            key-management: "psk"
-/etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:            password: "sjhf3859"
+/etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:            password: "<REDACTED>"
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:          networkmanager:
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:            uuid: "bf81f458-5456-4645-b6c4-0662760765ed"
 /etc/netplan/90-NM-bf81f458-5456-4645-b6c4-0662760765ed.yaml:            name: "Sams Pixel 8a"

niri-4screen.md

@@ -23,6 +23,14 @@ HARDWARE SUMMARY
 - Notes: There may be multiple /dev/dri/card* devices. Session must pick the
   correct device driving the 4 DP outputs.
 
+NOTE (2026-01 recon):
+- Current Ubuntu hardware scan shows NVIDIA Quadro P620 is driving /dev/fb0 at 1680x1050.
+- This suggests the monitors may actually be attached to the Quadro, not the Intel outputs.
+- Before finalizing GPU/device selection, verify:
+  - ls -l /dev/dri/by-path
+  - loginctl seat-status seat0
+  - (optional) niri output listing once in session
+
 KNOWN KERNEL / PLATFORM ISSUES
 - IOMMU faults / “Operation not permitted” style crashes were avoided on Ubuntu
   with kernel flags:

plan.md

@@ -37,6 +37,8 @@ setup.md and software_to_add.md are again more files for software consolidation.
 We need development frameworks for python, php, docker-compose, node.
 
 Folder /docs has more directions for the PLAN and software list.
+- docs/nixos_build_spec.md is the source-of-truth for disk/boot/network decisions.
+- docs/software_inventory.md (or equivalent) is the source-of-truth for the final software list.
 
 
 Folder /logs has some scans and hardware profiles which can be used for planning and software. Including looking at the disks. Please ask for more info on the disks if needed.

results/generated_home.nix

@@ -90,14 +90,18 @@
   # ---
   # 5. ENVIRONMENT & API KEYS
   # ---
-  # WARNING: Storing secrets in plain text is a security risk.
-  # Consider using a tool like sops-nix for production environments.
-  home.sessionVariables = {
-    OPENAI_API_KEY = "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";
-    TAVILY_API_KEY = "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";
-    DEEPSEEK_API_KEY = "sk-26c66e4dd5b34017bd66f7aef748c625";
-  };
-
+  # SECURITY: Do NOT store secrets in git-tracked Nix files.
+  # Use a local-only file such as:
+  #   ~/.config/environment.d/10-secrets.conf
+  # or adopt sops-nix / agenix later.
+  #
+  # Example (DO NOT COMMIT):
+  # home.sessionVariables = {
+  #   OPENAI_API_KEY = "…";
+  #   TAVILY_API_KEY = "…";
+  #   DEEPSEEK_API_KEY = "…";
+  # };
+  
   # Add custom binary paths to your environment
   home.sessionPath = [
     # For the 'opencode' CLI tool
@@ -117,4 +121,3 @@
   # This section is a placeholder for linking config files from a Git repo.
   # e.g., home.file.".config/nvim/init.vim".source = ./config/nvim/init.vim;
 }
-