Commit 318e1d216e96

@@ -57,16 +57,14 @@
   programs.ssh = {
     startAgent = true;
     enableAskPassword = true;
-    askPassword = "${
-      pkgs.writeShellScript "ssh-askpass-silent" ''
-        case "$1" in
-          *PIN*|*passphrase*|*password*)
-            exec ${pkgs.openssh-askpass}/libexec/gtk-ssh-askpass "$@"
-            ;;
-        esac
-        exit 0
-      ''
-    }";
+    askPassword = "${pkgs.writeShellScript "ssh-askpass-silent" ''
+      case "$1" in
+        *PIN*|*passphrase*|*password*)
+          exec ${pkgs.openssh-askpass}/libexec/gtk-ssh-askpass "$@"
+          ;;
+      esac
+      exit 0
+    ''}";
   };
 
   # Disable GNOME's gcr-ssh-agent (conflicts with programs.ssh.startAgent)

@@ -1,8 +1,71 @@
 #!/usr/bin/env bash
-# Install a new system
+# Install a NixOS system using disko-install.
+#
+# This script partitions the target disk (via disko) and installs the specified
+# NixOS configuration from this flake. It is meant to be run from the NixOS
+# live USB installer.
+#
+# Prerequisites:
+#   - Boot from a NixOS live USB
+#   - Clone or copy this repository onto the live system
+#   - Identify the target disk device (e.g., /dev/nvme0n1)
+#
+# The --disk flag maps the disko disk name (defined in systems/<host>/disks.nix)
+# to the actual block device. Most hosts use "root" as the disk name.
+#
+# Examples:
+#   # Install okinawa onto /dev/nvme0n1
+#   ./install.sh okinawa --disk root /dev/nvme0n1
+#
+#   # Install with EFI boot entries written to NVRAM (use when installing on
+#   # the machine you'll boot from, not when preparing a disk for another machine)
+#   ./install.sh okinawa --disk root /dev/nvme0n1 --write-efi-boot-entries
+#
+#   # Dry run (show commands without executing)
+#   ./install.sh okinawa --disk root /dev/nvme0n1 --dry-run
+#
+#   # Update an existing system without reformatting (mount-only mode)
+#   ./install.sh okinawa --disk root /dev/nvme0n1 --mode mount
+#
+# Tips:
+#   If you run out of space on the live USB, you can either:
+#   - Resize the tmpfs:  mount -o remount,size=28G /nix/.rw-store
+#   - Build remotely and copy the closure over SSH (see README)
+#
+# All extra arguments are forwarded to disko-install. Run with --help to see
+# the full list of disko-install options:
+#
+# disko-install options:
+#   --mode MODE              format (default) or mount (skip formatting)
+#   --disk NAME DEVICE       Map disko disk name to a block device (required)
+#   --dry-run                Print commands without running them
+#   --show-trace             Show Nix stack trace on error
+#   --extra-files SRC DEST   Copy extra files into the installed system
+#   --write-efi-boot-entries Write EFI entries to NVRAM for this machine
+#   --system-config JSON     Merge extra JSON config into the NixOS configuration
+#   --mount-point PATH       Custom mount point (default: /mnt/disko-install-root)
+#   --option NAME VALUE      Pass extra options to Nix
+#   -h, --help               Show disko-install help
 
 set -euo pipefail
 
+usage() {
+    sed -n '/^# Install a NixOS/,/^[^#]/{ /^#/s/^# \{0,1\}//p }' "$0"
+    echo ""
+    echo "Usage: $0 <hostname> [disko-install options...]"
+    echo ""
+    echo "Arguments:"
+    echo "  hostname    NixOS host configuration to install (from flake)"
+    echo ""
+    echo "Common usage:"
+    echo "  $0 okinawa --disk root /dev/nvme0n1"
+}
+
+if [[ $# -eq 0 ]] || [[ "$1" == "-h" ]] || [[ "$1" == "--help" ]]; then
+    usage
+    exit 0
+fi
+
 SYSTEM=$1
 shift