# NixOS /boot Partition Expansion Plan

## CRITICAL CONTEXT & PROBLEM STATEMENT

**System:** `zix790prors` - Dual-boot Windows 11 + NixOS on Samsung SSD 990 PRO 4TB
**Problem:** Current /boot partition (/dev/nvme0n1p1) is only 100MB, insufficient for multiple NixOS generations
**Goal:** Create 1GB /boot partition to support 20+ NixOS generations (~38MB each)

**Current Partition Layout:**
```
Device              Start        End    Sectors   Size Type
/dev/nvme0n1p1       2048     206847     204800   100M EFI System (/boot)
/dev/nvme0n1p2     206848     239615      32768    16M Microsoft reserved
/dev/nvme0n1p3     239616 1953316863 1953077248 931.3G Microsoft basic data (Windows)
/dev/nvme0n1p6 1953316864 3906394111 1953077248 931.3G Linux filesystem (/nix/store)
/dev/nvme0n1p5 3906394112 7812548607 3906154496   1.8T Linux filesystem (/games - btrfs)
/dev/nvme0n1p4 7812548608 7814031359    1482752   724M Windows recovery environment
```

**Strategy:** Shrink /games partition (p5) by 1GB and create new 1GB EFI partition

---

## PLAN A: DETAILED STEP-BY-STEP INSTRUCTIONS

### PREREQUISITES
1. **Boot from NixOS live USB** (build with `./build-liveusb.sh`)
2. **Have Windows recovery media ready** (just in case)
3. **Backup important data** (though this shouldn't affect user data)

### PHASE 1: PREPARATION & BACKUP

```bash
# 1. Connect to internet
sudo systemctl start wpa_supplicant
# OR for ethernet: sudo systemctl start dhcpcd

# 2. Mount current filesystems
sudo mkdir -p /mnt/{boot,nix,games}
sudo mount /dev/nvme0n1p1 /mnt/boot
sudo mount /dev/nvme0n1p6 /mnt/nix
sudo mount /dev/nvme0n1p5 /mnt/games

# 3. Backup current /boot contents
sudo mkdir -p /tmp/boot-backup
sudo cp -a /mnt/boot/* /tmp/boot-backup/
sudo ls -la /tmp/boot-backup/  # Verify backup

# 4. Record current UUIDs for later
sudo blkid /dev/nvme0n1p1 > /tmp/original-boot-uuid.txt
cat /tmp/original-boot-uuid.txt
```

### PHASE 2: SHRINK /games PARTITION

```bash
# 1. Check /games filesystem
sudo btrfs filesystem show /mnt/games
sudo btrfs filesystem usage /mnt/games

# 2. Shrink btrfs filesystem first (by 1.1GB for safety margin)
sudo btrfs filesystem resize -1200M /mnt/games

# 3. Verify shrink was successful
sudo btrfs filesystem usage /mnt/games

# 4. Unmount to resize partition
sudo umount /mnt/games

# 5. Note current partition end sector
sudo fdisk -l /dev/nvme0n1 | grep nvme0n1p5
# Current: 3906394112 7812548607 (note the END: 7812548607)

# 6. Calculate new end sector (subtract ~2M sectors for 1GB)
# New end should be approximately: 7812548607 - 2097152 = 7810451455
```

### PHASE 3: RESIZE PARTITIONS

```bash
# 1. Use parted to resize /games partition
sudo parted /dev/nvme0n1

# In parted shell:
print                                    # Show current layout
resizepart 5 7810451455                 # Resize partition 5 to new end
print                                    # Verify the change
quit

# 2. Verify partition table
sudo fdisk -l /dev/nvme0n1
```

### PHASE 4: CREATE NEW 1GB EFI PARTITION

```bash
# 1. Create new partition in freed space
sudo parted /dev/nvme0n1

# In parted shell:
print free                              # Show free space
mkpart primary fat32 7810451456 7812548607   # Create new partition
set 7 esp on                           # Set ESP flag (assuming it becomes p7)
print                                   # Verify
quit

# 2. Format new partition as FAT32
sudo mkfs.fat -F32 -n "NIXBOOT" /dev/nvme0n1p7

# 3. Get new partition UUID
sudo blkid /dev/nvme0n1p7
```

### PHASE 5: COPY BOOT CONTENTS

```bash
# 1. Mount new boot partition
sudo mkdir -p /mnt/new-boot
sudo mount /dev/nvme0n1p7 /mnt/new-boot

# 2. Copy all boot contents
sudo cp -a /tmp/boot-backup/* /mnt/new-boot/

# 3. Verify copy
sudo ls -la /mnt/new-boot/
sudo du -sh /mnt/new-boot/*
```

### PHASE 6: UPDATE CONFIGURATION

```bash
# 1. Mount root filesystem
sudo mount /dev/nvme0n1p6 /mnt/nix
sudo mount /dev/nvme0n1p6 /mnt  # For nixos-enter

# 2. Mount other needed filesystems for chroot
sudo mount --bind /dev /mnt/dev
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys
sudo mount /dev/nvme0n1p7 /mnt/boot  # Mount NEW boot partition

# 3. Enter NixOS environment
sudo nixos-enter

# 4. Inside chroot - update hardware configuration
# Edit /etc/nixos/hardware-configuration.nix or check current fstab
NEW_UUID=$(blkid /dev/nvme0n1p7 | grep -o 'UUID="[^"]*"' | cut -d'"' -f2)
echo "New boot UUID: $NEW_UUID"

# 5. Update boot partition UUID in configuration
# This step depends on your current setup - likely in hardware-configuration.nix
```

### PHASE 7: REGENERATE BOOTLOADER

```bash
# Still in nixos-enter chroot:

# 1. Rebuild bootloader configuration
nixos-rebuild switch --install-bootloader

# 2. Exit chroot
exit

# 3. Update EFI boot variables (if needed)
sudo efibootmgr -v  # Check current entries
```

### PHASE 8: VERIFICATION & CLEANUP

```bash
# 1. Unmount everything
sudo umount /mnt/new-boot
sudo umount /mnt/boot
sudo umount /mnt/nix
sudo umount /mnt/games

# 2. Remount /games with new partition size
sudo mount /dev/nvme0n1p5 /mnt/games
sudo btrfs filesystem resize max /mnt/games  # Expand btrfs to use available space

# 3. Final verification
sudo fdisk -l /dev/nvme0n1
sudo lsblk
```

### PHASE 9: TEST BOOT

```bash
# 1. Reboot and test
sudo reboot

# 2. After successful boot, update NixOS config
# Change configurationLimit to 20 (perfect for 1GB /boot)
# In /home/johno/nixos-configs/machines/zix790prors/configuration.nix:
# boot.loader.systemd-boot.configurationLimit = 20;

# 3. Test rebuild
sudo nixos-rebuild switch --flake .#zix790prors
```

---

## PLAN B: TROUBLESHOOTING & CONTEXT FOR ADDITIONAL HELP

### IF THINGS GO WRONG

**Scenario 1: System won't boot**
- Boot from live USB
- Mount old boot partition: `sudo mount /dev/nvme0n1p1 /mnt/boot`
- Check if bootloader entries exist: `ls /mnt/boot/loader/entries/`
- Regenerate from live USB using `nixos-install` with `--root /mnt`

**Scenario 2: Partition operations fail**
- **STOP IMMEDIATELY**
- Document exact error message
- Use `sudo fdisk -l` and `sudo parted /dev/nvme0n1 print` to check current state
- Do NOT proceed without understanding the error

**Scenario 3: Btrfs resize fails**
- Check available space: `sudo btrfs filesystem usage /mnt/games`
- May need to balance first: `sudo btrfs balance start /mnt/games`
- Or defragment: `sudo btrfs filesystem defragment -r /mnt/games`

### RECOVERY INFORMATION

**Original partition layout (before changes):**
```
/dev/nvme0n1p1: 100M EFI (/boot) - sectors 2048-206847
/dev/nvme0n1p5: 1.8T btrfs (/games) - sectors 3906394112-7812548607
```

**Key files to check:**
- `/etc/fstab` - filesystem mount configuration
- `/etc/nixos/hardware-configuration.nix` - NixOS hardware config
- `/boot/loader/loader.conf` - systemd-boot config

**Important UUIDs (save these before starting):**
```bash
# Run these BEFORE making changes:
sudo blkid /dev/nvme0n1p1  # Current boot partition
sudo blkid /dev/nvme0n1p5  # Games partition
sudo blkid /dev/nvme0n1p6  # Nix store partition
```

**Emergency boot options:**
- Boot from Windows (should be unaffected)
- Boot from NixOS live USB
- Use systemd-boot menu to select older generation (if available)

### ALTERNATIVE APPROACHES IF PLAN A FAILS

1. **Expand into Microsoft reserved instead** (lower risk, less space)
2. **Use external USB for /boot** (temporary solution)
3. **Recreate partition table** (nuclear option, requires full backup)

---

## TECHNICAL DETAILS FOR CLAUDE CODE ASSISTANCE

**Repository:** `/home/johno/nixos-configs` - NixOS flake-based configuration
**Machine config:** `machines/zix790prors/configuration.nix`
**Current configurationLimit:** 1 (temporarily reduced from 2)
**Target configurationLimit:** 20 (requires ~1GB /boot)

**Key commands for status checking:**
```bash
# Partition info
sudo fdisk -l /dev/nvme0n1
sudo parted /dev/nvme0n1 print free
sudo lsblk

# Filesystem info
sudo btrfs filesystem show
sudo btrfs filesystem usage /games
df -h /boot

# Boot info
sudo efibootmgr -v
ls -la /boot/loader/entries/
```

**This document created:** 2025-10-02 by Claude Code
**Hardware:** Samsung SSD 990 PRO 4TB, NixOS + Windows 11 dual boot