diff --git a/README.md b/README.md
index 4367b52..a53ab97 100755
--- a/README.md
+++ b/README.md
@@ -1,16 +1,189 @@
-sam/nixos
+# sam/nixos (NixOS + Home Manager config)
 
-Host: aspire-laptop
-- NixOS 25.11 (flakes)
-- Home Manager 25.11
-- Plasma 6 + Hyprland via SDDM
-- Btrfs root, zram swap
-- zsh + kitty
-- Neovim config in home/sam/nvim (lazy.nvim downloads plugins, pinned by lazy-lock.json)
+This repo contains a reproducible NixOS + Home Manager setup for:
 
-Install:
-- Boot NixOS 25.11 Graphical ISO
-- Run scripts/install-from-iso.sh (wipes disk)
-- Clone this repo into /mnt/etc/nixos
-- Replace hosts/aspire-laptop/hardware-configuration.nix with generated one
-- nixos-install --flake /mnt/etc/nixos#aspire-laptop
+- Hostname: `aspire-laptop`
+- NixOS: `25.11` (flakes)
+- Home Manager: `25.11`
+- Desktop: KDE Plasma 6 + Hyprland (selectable at login via SDDM)
+- Filesystem: Btrfs (root + home subvolumes), zram swap
+- Shell/terminal: zsh + kitty
+- Neovim: config stored in this repo; plugins installed by `lazy.nvim`
+
+---
+
+## What you get after install
+
+- A working KDE desktop (Plasma) and Hyprland (choose at login)
+- Common CLI tools (git, curl, ripgrep, etc. as defined in NixOS config)
+- SSH server enabled (password auth currently enabled)
+- Home Manager manages user configuration (zsh, kitty config, Neovim config, etc.)
+
+---
+
+## Requirements
+
+- NixOS 25.11 Graphical ISO USB
+- Internet access during install (Wi‑Fi or Ethernet)
+- Access to this repo (Gitea)
+
+Optional but recommended:
+- Disable Secure Boot in BIOS/UEFI (simplifies bootloader and drivers)
+
+---
+
+## Install (wipe disk)
+
+### 1) Boot the NixOS ISO
+- Boot from the USB.
+- Connect to the internet from the live environment.
+
+### 2) Clone this repo in the live environment
+Open a terminal in the live ISO and run (adjust URL if needed):
+
+```bash
+git clone ssh://git@gitea.lab.audasmedia.com.au:2222/sam/nixos.git /tmp/nixos
+```
+
+### 3) Partition + mount (WIPES THE DISK)
+This repo includes a helper script that partitions `/dev/sda` and mounts Btrfs
+subvolumes at `/mnt`.
+
+```bash
+sudo bash /tmp/nixos/scripts/install-from-iso.sh
+```
+
+Read the prompt carefully: this will destroy all data on the target disk.
+
+### 4) Put the repo at `/mnt/etc/nixos`
+```bash
+sudo rm -rf /mnt/etc/nixos
+sudo mkdir -p /mnt/etc
+sudo cp -a /tmp/nixos /mnt/etc/nixos
+```
+
+### 5) Copy the generated hardware config into the repo
+`nixos-generate-config` creates a hardware file based on the laptop.
+Copy it into the correct host folder:
+
+```bash
+sudo cp -f /mnt/etc/nixos/hardware-configuration.nix \
+  /mnt/etc/nixos/hosts/aspire-laptop/hardware-configuration.nix
+```
+
+### 6) Install NixOS using the flake
+```bash
+sudo nixos-install --flake /mnt/etc/nixos#aspire-laptop
+```
+
+When finished, reboot:
+
+```bash
+reboot
+```
+
+---
+
+## First boot checklist
+
+### 1) Set the user password (if not already set)
+If needed, switch to a TTY with `Ctrl+Alt+F2`, log in as root, then:
+
+```bash
+passwd sam
+```
+
+### 2) Neovim plugin install (one-time per machine)
+This setup uses `lazy.nvim` for plugins. After the system is installed and you
+can log in, run:
+
+```bash
+nvim --headless "+Lazy! sync" "+qa"
+```
+
+Then launch Neovim normally:
+
+```bash
+nvim
+```
+
+### 3) Tailscale login (if enabled)
+```bash
+sudo tailscale up
+```
+
+---
+
+## Updating / applying changes
+
+### Apply config changes on the machine
+From the installed system:
+
+```bash
+sudo nixos-rebuild switch --flake /etc/nixos#aspire-laptop
+```
+
+### Commit/push your changes
+This repo is intended to be the single source of truth:
+
+```bash
+cd /etc/nixos
+git status
+git add -A
+git commit -m "Describe change"
+git push
+```
+
+If `git push` is rejected (remote ahead), use:
+
+```bash
+git pull --rebase origin main
+git push
+```
+
+---
+
+## Adding programs (basic)
+
+There are two places to add packages:
+
+### A) System-wide packages (available for all users)
+Edit:
+
+- `hosts/aspire-laptop/configuration.nix`
+
+Add to:
+
+- `environment.systemPackages = with pkgs; [ ... ];`
+
+Then apply:
+
+```bash
+sudo nixos-rebuild switch --flake /etc/nixos#aspire-laptop
+```
+
+### B) User packages (only for `sam`)
+Edit:
+
+- `home/sam/home.nix`
+
+Add to:
+
+- `home.packages = with pkgs; [ ... ];`
+
+Then apply the same rebuild command (Home Manager runs as a NixOS module):
+
+```bash
+sudo nixos-rebuild switch --flake /etc/nixos#aspire-laptop
+```
+
+---
+
+## Useful docs
+
+- NixOS Manual: https://nixos.org/manual/nixos/stable/
+- Home Manager Manual: https://nix-community.github.io/home-manager/
+- Flakes: https://nixos.wiki/wiki/Flakes
+- Nixpkgs search (packages/options): https://search.nixos.org/
+
+---