Reorganize scripts/ into secrets/, proxmox/, and lib/ subfolders

scripts/ had grown to 10 top-level scripts covering three distinct
concerns (sops/age + SSH host-key management, Proxmox deployment, and
repo-wide bootstrap/CI) with no grouping. Move the key-management scripts
(backup-admin-key.sh, rotate-admin-key.sh, prepare-host-key.sh,
sync-host-keys.sh) into scripts/secrets/, and the Proxmox scripts
(create-proxmox-resource.sh, configure-nix-cache-client.sh) into
scripts/proxmox/; leave env.sh, codex-setup.sh, codex-maintenance.sh, and
bump-nixpkgs-release.sh at the top level (frequently hand-typed or pure
shared config) and scripts/lib/ as-is.

Updates every cross-reference: each moved script's repo_root computation
(now one directory deeper), shellcheck source= directives, inter-script
paths (create-proxmox-resource.sh's call into sync-host-keys.sh and its
remote bootstrap of configure-nix-cache-client.sh on the Proxmox node),
and every doc/module mention (CLAUDE.md's Scripts section reorganized to
match, README.md, docs/auto-installer.md, docs/proxmox-images.md,
modules/installer/common.nix, modules/platforms/lxc.nix). CI workflows
need no change -- they only invoke codex-maintenance.sh, which didn't
move. Verified via bash -n, shellcheck (no new warnings beyond the
pre-existing SC1091/SC2029/SC2095 baseline), and live dry-runs of
sync-host-keys.sh --all and create-proxmox-resource.sh --list from their
new paths.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

scripts/secrets/backup-admin-key.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# Backs up the local sops age key (the private key that decrypts
+# secrets/*.yaml -- normally the one trusted as &admin) to an arbitrary
+# destination path, e.g. a USB drive or other offline storage, so it can
+# later be restored and handed to rotate-admin-key.sh if this machine's
+# copy is ever lost, or to run either script from a different machine.
+#
+# Usage:
+#   scripts/secrets/backup-admin-key.sh <dest-path> [--key-file <path>] [--force] [--dry-run]
+#
+# Source key resolution matches sops/age's own default order:
+#   $SOPS_AGE_KEY (inline identity text) if set, else
+#   --key-file if given, else
+#   $SOPS_AGE_KEY_FILE if set, else
+#   ${XDG_CONFIG_HOME:-$HOME/.config}/sops/age/keys.txt
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/../.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+
+# shellcheck source=../env.sh
+source "${repo_root}/scripts/env.sh"
+# shellcheck source=../lib/sops-age.sh
+source "${repo_root}/scripts/lib/sops-age.sh"
+
+# Pin cwd for the same reason rotate-admin-key.sh does: age/sops calls
+# below should never depend on wherever the caller's shell happened to be.
+cd "$repo_root"
+
+usage() {
+  cat <<EOF
+Usage: $0 <dest-path> [--key-file <path>] [--force] [--dry-run]
+
+  <dest-path>        Where to write the backup. Parent directories are
+                     created as needed. Written with 0600 permissions.
+  --key-file <path>  Read the key from here instead of the default
+                     sops/age resolution (\$SOPS_AGE_KEY_FILE, then
+                     \${XDG_CONFIG_HOME:-\$HOME/.config}/sops/age/keys.txt).
+                     Ignored if \$SOPS_AGE_KEY is set (that always wins,
+                     same precedence sops/age itself uses).
+  --force            Overwrite <dest-path> if it already exists.
+  --dry-run          Print what would happen; write nothing.
+EOF
+}
+
+dry_run=0
+force=0
+key_file="$DEFAULT_SOPS_AGE_KEY_FILE"
+args=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --force)
+      force=1
+      shift
+      ;;
+    --key-file)
+      key_file="${2:?--key-file requires a path}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      args+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#args[@]}" -ne 1 ]]; then
+  usage >&2
+  exit 1
+fi
+dest="${args[0]}"
+
+nix_extra_opts
+
+if [[ -n "${SOPS_AGE_KEY:-}" ]]; then
+  echo "==> Source: \$SOPS_AGE_KEY (inline identity from the environment)."
+  src_content="$SOPS_AGE_KEY"
+else
+  [[ -s "$key_file" ]] || {
+    echo "ERROR: no key found. \$SOPS_AGE_KEY is unset and ${key_file} doesn't exist or is empty." >&2
+    exit 1
+  }
+  echo "==> Source: ${key_file}"
+  src_content="$(cat "$key_file")"
+fi
+
+# Round-trip through a private scratch file (rather than trusting the
+# source string as-is) so age-keygen -y validates it's a real identity
+# before anything is written to <dest-path>.
+scratch="$(mktemp)"
+trap 'rm -f "$scratch"' EXIT
+( umask 077; printf '%s\n' "$src_content" > "$scratch" )
+
+src_pub="$(age_pubkey_from_identity_file "$scratch")" || {
+  echo "ERROR: source doesn't look like a valid age identity (age-keygen -y failed)." >&2
+  exit 1
+}
+echo "    public key: ${src_pub}"
+
+current_admin_pub="$(sops_yaml_admin_pubkey "$sops_yaml")"
+if [[ -n "$current_admin_pub" && "$current_admin_pub" != "$src_pub" ]]; then
+  echo "NOTE: this key does not match .sops.yaml's current &admin entry (${current_admin_pub})."
+  echo "      Backing it up anyway -- this script doesn't require it to be the admin key."
+fi
+
+if [[ -e "$dest" && "$force" -ne 1 ]]; then
+  echo "ERROR: ${dest} already exists. Pass --force to overwrite." >&2
+  exit 1
+fi
+
+if [[ "$dry_run" -eq 1 ]]; then
+  echo
+  echo "[dry-run] would write $(wc -c <"$scratch" | tr -d ' ') bytes to ${dest} (mode 0600)"
+  [[ -e "$dest" ]] && echo "[dry-run] would overwrite existing file (--force given)"
+  echo "[dry-run] Nothing was written. Re-run without --dry-run to apply this."
+  exit 0
+fi
+
+mkdir -p "$(dirname "$dest")"
+install -m 600 "$scratch" "$dest"
+
+dest_pub="$(age_pubkey_from_identity_file "$dest")"
+if [[ "$dest_pub" != "$src_pub" ]]; then
+  echo "ERROR: ${dest} was written but its public key doesn't match the source -- investigate before relying on this backup." >&2
+  exit 1
+fi
+
+cat <<EOF
+
+Done. Backed up to: ${dest}
+  public key: ${dest_pub}
+
+This is a private key -- store it somewhere offline/secure, not in this
+repo or anywhere it'd get committed. Restore it with:
+  scripts/secrets/rotate-admin-key.sh ${dest}
+EOF

scripts/secrets/prepare-host-key.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# Generates a new machine's SSH host key by an arbitrary name, before it
+# necessarily has a flake target yet -- prints the .sops.yaml snippet to
+# add by hand. For any host that already has a flake target,
+# scripts/secrets/sync-host-keys.sh <target> does this same job plus the
+# .sops.yaml/key_groups registration and re-encryption automatically; use
+# this script only to pre-generate a key ahead of adding the flake target
+# itself.
+#
+# Why a host key is needed at all: sops-nix derives each host's decryption key from
+# its own /etc/ssh/ssh_host_ed25519_key at *activation* time, but that
+# activation runs before systemd would otherwise generate this key on
+# first boot (sshd-keygen is a normal systemd service gated behind
+# multi-user.target; activation scripts run earlier than that). Without
+# pre-seeding, secrets — including the root/nixos login password — fail
+# to decrypt on the machine's very first boot.
+#
+# This script only touches your admin workstation and this repo's
+# .sops.yaml (it never contacts the target machine). Run it, follow the
+# printed next steps, then use the resulting key with the auto-install.sh
+# prompt (see modules/installer/common.nix) when you actually install the
+# new machine.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/../.." && pwd)"
+# shellcheck source=../env.sh
+source "${repo_root}/scripts/env.sh"
+# shellcheck source=../lib/ssh-host-keys.sh
+source "${repo_root}/scripts/lib/ssh-host-keys.sh"
+
+hostname="${1:?usage: scripts/secrets/prepare-host-key.sh <hostname>}"
+sops_yaml="${repo_root}/.sops.yaml"
+
+if [[ ! -f "$sops_yaml" ]]; then
+  echo "ERROR: $sops_yaml not found — is this script still under nixos/scripts/?" >&2
+  exit 1
+fi
+
+keydir="${repo_root}/host-keys"
+mkdir -p "$keydir"
+keyfile="${keydir}/${hostname}_ssh_host_ed25519_key"
+
+if [[ -f "$keyfile" ]]; then
+  echo "ERROR: $keyfile already exists. Remove it first if you want to regenerate." >&2
+  exit 1
+fi
+
+nix_extra_opts
+generate_host_ed25519_key "$hostname" "$keyfile"
+
+age_pub="$(ssh_pubkey_to_age "${keyfile}.pub")"
+
+cat <<EOF
+
+Generated: ${keyfile}(.pub)
+
+=== 1. Add this line under keys: in ${sops_yaml} ===
+  - &${hostname} ${age_pub}
+
+=== 2. Add *${hostname} to whichever creation_rules key_groups this host needs ===
+(e.g. secrets/common.yaml always; add a per-host secrets/${hostname}.yaml
+ block too if this host will get its own secrets, same pattern as
+ nix-cache/server.)
+
+=== 3. Re-encrypt every secrets file you just added it to ===
+  nix-shell -p sops --run 'sops updatekeys ${repo_root}/secrets/common.yaml'
+
+=== 4. Commit + push this repo so the flake build picks up the new recipient ===
+
+=== 5. Get the key onto the installer, one of two ways ===
+  a) Rebuild the installer image with all host-keys/ baked in (see
+     docs/auto-installer.md):
+       NIXOS_HOST_KEYS_DIR="${keydir}" nix build .#iso --impure
+     (or .#pxe — --impure is required since host-keys/ is gitignored and
+     flakes can't see it otherwise)
+
+  b) Or, for an image already built without keys, scp it in after boot:
+       scp ${keyfile}{,.pub} root@<target-ip>:/root/host-keys/
+
+Then continue with /etc/auto-install.sh as normal — it checks
+/etc/host-keys (baked in) before /root/host-keys (scp'd) and installs
+whichever it finds before running nixos-install.
+EOF

scripts/secrets/rotate-admin-key.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# Rotates the &admin sops age key: decrypts with a backed-up copy of the
+# key CURRENTLY trusted as &admin, replaces .sops.yaml's &admin entry with
+# a new key already present in this environment, and re-encrypts every
+# secrets/*.yaml for the new recipient set. After this runs, the old key
+# can no longer decrypt anything -- this is a real, one-way handoff of
+# trust, not a preview.
+#
+# This is the automation for the manual steps create-proxmox-resource.sh /
+# sync-host-keys.sh print when they bootstrap a brand-new, not-yet-trusted
+# age key on a machine that's never had admin access before:
+#
+#   scripts/secrets/rotate-admin-key.sh /path/to/backed-up/admin/keys.txt
+#
+# The backup key's *public* key must match .sops.yaml's current &admin
+# entry -- this script verifies that by deriving it, it doesn't just trust
+# the filename or take it on faith. The new key defaults to wherever sops
+# itself would already look ($SOPS_AGE_KEY_FILE, then the XDG default), so
+# the common case is just pointing this at the restored backup.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/../.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+
+# shellcheck source=../env.sh
+source "${repo_root}/scripts/env.sh"
+# shellcheck source=../lib/sops-age.sh
+source "${repo_root}/scripts/lib/sops-age.sh"
+
+# sops resolves .sops.yaml by walking up from the process's cwd, not from
+# the target file's own path -- if this script were invoked from somewhere
+# other than the repo root (or from inside another checkout/worktree that
+# happens to have its own .sops.yaml), `sops updatekeys` would silently
+# re-encrypt against the WRONG config's recipient list instead of this
+# repo's. Pin cwd here so every sops/age call below is unambiguous
+# regardless of where the caller's shell started out.
+cd "$repo_root"
+
+usage() {
+  cat <<EOF
+Usage: $0 <path-to-backed-up-admin-key> [--new-key-file <path>] [--dry-run]
+
+  <path-to-backed-up-admin-key>  age identity file for the key CURRENTLY
+                                 trusted as &admin. Only ever read -- never
+                                 copied or modified.
+  --new-key-file <path>          age identity file for the key to promote
+                                 to &admin. Defaults to \$SOPS_AGE_KEY_FILE,
+                                 then
+                                 \${XDG_CONFIG_HOME:-\$HOME/.config}/sops/age/keys.txt
+                                 (sops/age's own default resolution order).
+  --dry-run                      Print what would change; touches nothing
+                                  (.sops.yaml untouched, no sops updatekeys
+                                  calls).
+EOF
+}
+
+dry_run=0
+new_key_file="$DEFAULT_SOPS_AGE_KEY_FILE"
+args=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dry-run)
+      dry_run=1
+      shift
+      ;;
+    --new-key-file)
+      new_key_file="${2:?--new-key-file requires a path}"
+      shift 2
+      ;;
+    -h | --help)
+      usage
+      exit 0
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      args+=("$1")
+      shift
+      ;;
+  esac
+done
+
+if [[ "${#args[@]}" -ne 1 ]]; then
+  usage >&2
+  exit 1
+fi
+backup_key="${args[0]}"
+
+[[ -s "$backup_key" ]] || { echo "ERROR: backup key file not found or empty: ${backup_key}" >&2; exit 1; }
+[[ -s "$new_key_file" ]] || { echo "ERROR: new key file not found or empty: ${new_key_file}" >&2; exit 1; }
+
+nix_extra_opts
+
+echo "==> Deriving public keys..."
+old_pub="$(age_pubkey_from_identity_file "$backup_key")"
+new_pub="$(age_pubkey_from_identity_file "$new_key_file")"
+echo "    backup (old admin) key: ${old_pub}"
+echo "    new admin key:          ${new_pub}"
+
+if [[ "$old_pub" == "$new_pub" ]]; then
+  echo "ERROR: backup key and new key are identical -- nothing to rotate." >&2
+  exit 1
+fi
+
+current_admin_pub="$(sops_yaml_admin_pubkey "$sops_yaml")"
+if [[ -z "$current_admin_pub" ]]; then
+  echo "ERROR: couldn't find a '&admin age1...' line in ${sops_yaml}." >&2
+  exit 1
+fi
+
+if [[ "$current_admin_pub" != "$old_pub" ]]; then
+  echo "ERROR: ${backup_key} doesn't match the current &admin key in .sops.yaml." >&2
+  echo "  .sops.yaml &admin: ${current_admin_pub}" >&2
+  echo "  backup key pubkey: ${old_pub}" >&2
+  echo "Wrong backup file, or .sops.yaml has already moved on -- not touching anything." >&2
+  exit 1
+fi
+
+mapfile -t secrets_files < <(find "${repo_root}/secrets" -maxdepth 1 -name '*.yaml' | sort)
+if [[ "${#secrets_files[@]}" -eq 0 ]]; then
+  echo "ERROR: no secrets/*.yaml files found under ${repo_root}/secrets." >&2
+  exit 1
+fi
+
+# sops_can_decrypt <key-file> <secrets-file>: used both to confirm the
+# backup key still works before touching anything, and again after
+# rotation to confirm the new key does too.
+sops_can_decrypt() {
+  local key_file="$1" secrets_file="$2"
+  SOPS_AGE_KEY_FILE="$key_file" nix-shell "${NIX_OPTS[@]}" -p sops --run \
+    "sops -d '${secrets_file}'" >/dev/null
+}
+
+echo "==> Confirming the backup key can actually decrypt..."
+if ! sops_can_decrypt "$backup_key" "${secrets_files[0]}"; then
+  echo "ERROR: backup key failed to decrypt $(basename "${secrets_files[0]}") -- aborting." >&2
+  exit 1
+fi
+echo "    OK: decrypted $(basename "${secrets_files[0]}")"
+
+if [[ "$dry_run" -eq 1 ]]; then
+  echo
+  echo "[dry-run] would replace .sops.yaml's &admin line:"
+  echo "[dry-run]   - ${current_admin_pub}"
+  echo "[dry-run]   + ${new_pub}"
+  echo "[dry-run] would then re-encrypt (sops updatekeys --yes) for the new recipient set:"
+  for f in "${secrets_files[@]}"; do
+    echo "[dry-run]   secrets/$(basename "$f")"
+  done
+  echo
+  echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  exit 0
+fi
+
+echo "==> Rotating .sops.yaml's &admin key..."
+sed -i "s|^  - &admin age1[a-z0-9]*|  - \&admin ${new_pub}|" "$sops_yaml"
+grep -qF "$new_pub" "$sops_yaml" || {
+  echo "ERROR: sed edit didn't take -- .sops.yaml left unchanged, check it by hand." >&2
+  exit 1
+}
+echo "    Updated."
+
+echo "==> Re-encrypting secrets/*.yaml for the new recipient set..."
+for f in "${secrets_files[@]}"; do
+  echo "==> $(basename "$f")"
+  sops_updatekeys "$f" "$backup_key"
+done
+
+echo "==> Verifying the new key can decrypt everything..."
+for f in "${secrets_files[@]}"; do
+  if ! sops_can_decrypt "$new_key_file" "$f"; then
+    echo "ERROR: new key failed to decrypt $(basename "$f") after rotation -- investigate before committing." >&2
+    exit 1
+  fi
+  echo "    OK: $(basename "$f")"
+done
+
+cat <<EOF
+
+Done. .sops.yaml's &admin key is now:
+  ${new_pub}
+
+The old key (${old_pub}) can no longer decrypt any secrets/*.yaml
+re-encrypted above.
+
+Review the diff, then commit:
+  git add .sops.yaml secrets/*.yaml
+  git commit -m "Rotate sops admin age key"
+EOF

scripts/secrets/sync-host-keys.sh

@@ -0,0 +1,446 @@
+#!/usr/bin/env bash
+# Manages host-keys/ + .sops.yaml + secrets/*.yaml recipients together, so
+# a flake target's SSH host key and its sops registration never drift out
+# of sync with each other or with the flake itself.
+#
+#   sync-host-keys.sh --all                Generate/register every flake
+#                                           target missing a key.
+#   sync-host-keys.sh <target>              Same, for just one target.
+#   sync-host-keys.sh --remove              Interactively remove one
+#                                           locally-managed key.
+#   sync-host-keys.sh --regenerate-all-keys Remove and freshly regenerate
+#                                           every locally-managed key.
+#
+# "Generate/register" is idempotent and additive only: an existing
+# host-keys/ file is never touched, and .sops.yaml only ever gains an
+# anchor/alias it doesn't already have -- safe to re-run any time, e.g.
+# right after adding a new host to flake.nix.
+#
+# --remove and --regenerate-all-keys only ever operate on anchors that have
+# a corresponding host-keys/<name>_ssh_host_ed25519_key file. Anchors
+# without one (&admin, and any anchor for an already-deployed host whose
+# real /etc/ssh key was registered by hand, e.g. &docker/&server/&nix-cache
+# today) are never listed, removed, or regenerated -- this tooling only
+# ever touches keys it itself manages.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "$0")/../.." && pwd)"
+sops_yaml="${repo_root}/.sops.yaml"
+keydir="${repo_root}/host-keys"
+editor="${repo_root}/scripts/lib/sync-host-keys-edit-sops.py"
+
+# shellcheck source=../env.sh
+source "${repo_root}/scripts/env.sh"
+# shellcheck source=../lib/nix-eval.sh
+source "${repo_root}/scripts/lib/nix-eval.sh"
+# shellcheck source=../lib/ssh-host-keys.sh
+source "${repo_root}/scripts/lib/ssh-host-keys.sh"
+# shellcheck source=../lib/sops-age.sh
+source "${repo_root}/scripts/lib/sops-age.sh"
+# shellcheck source=../lib/confirm.sh
+source "${repo_root}/scripts/lib/confirm.sh"
+
+mkdir -p "$keydir"
+
+usage() {
+  cat <<EOF
+Usage: $0 --all [--dry-run]
+       $0 <flake-target> [--dry-run]
+       $0 --remove [--dry-run]
+       $0 --regenerate-all-keys [--dry-run]
+
+  --all                    Generate + register a host key for every flake
+                            target that's missing one.
+  <flake-target>            Same, for just one target (e.g. lxc-server).
+                            Reports if it already has one.
+  --remove                  Interactively pick one locally-managed key to
+                            remove from .sops.yaml and host-keys/.
+  --regenerate-all-keys     Remove every locally-managed key and generate
+                            fresh replacements for every current flake
+                            target. Destructive -- requires typed
+                            confirmation.
+  --dry-run                 Combine with any of the above: print what would
+                            change (host-keys/ files, .sops.yaml anchors and
+                            key_groups, which secrets/*.yaml would be
+                            re-encrypted) without touching anything. No keys
+                            generated, no files written, no sops calls,
+                            no prompts for confirmation.
+EOF
+}
+
+# --- step 0: make sure we can actually decrypt anything at all -------------
+#
+# Registering a host means editing .sops.yaml and then running
+# `sops updatekeys`, which has to decrypt each secrets file with an
+# existing recipient's key before it can re-encrypt it for the new one.
+# Check this before doing anything else, the same order sops/age itself
+# resolves a usable key in: SOPS_AGE_KEY (inline), then SOPS_AGE_KEY_FILE,
+# then the XDG default path.
+ensure_admin_decrypt_key() {
+  if [[ -n "${SOPS_AGE_KEY:-}" ]]; then
+    echo "Using SOPS_AGE_KEY from the environment."
+    return
+  fi
+
+  local key_file="$DEFAULT_SOPS_AGE_KEY_FILE"
+
+  if [[ -s "$key_file" ]]; then
+    echo "Found existing sops age key at ${key_file}."
+    return
+  fi
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] No sops age decryption key found (checked \$SOPS_AGE_KEY, \$SOPS_AGE_KEY_FILE, ${key_file})."
+    echo "[dry-run] Would generate a new one here -- continuing the dry run without one; any"
+    echo "[dry-run] 'would re-encrypt' output below couldn't actually run for real yet."
+    return
+  fi
+
+  echo "No sops age decryption key found (checked \$SOPS_AGE_KEY, \$SOPS_AGE_KEY_FILE, ${key_file})."
+  echo "Generating a new one at ${key_file}..."
+  mkdir -p "$(dirname "$key_file")"
+  nix-shell "${NIX_OPTS[@]}" -p age --run "age-keygen -o '${key_file}'" 2>&1 | grep -v "^Public key:" || true
+  local new_pub
+  new_pub="$(age_pubkey_from_identity_file "$key_file")"
+
+  cat <<EOF
+
+A brand-new age key was just generated -- it cannot decrypt anything that
+already exists in secrets/*.yaml, since nothing was ever encrypted for it.
+That trust can't be bootstrapped automatically (nobody can decrypt a file
+for a recipient that didn't exist when it was last encrypted).
+
+To actually use this key:
+  1. Have someone who currently CAN decrypt replace the &admin entry in
+     .sops.yaml with this public key:
+       ${new_pub}
+  2. They re-encrypt every secrets/*.yaml:
+       sops updatekeys --yes secrets/common.yaml
+       sops updatekeys --yes secrets/nix-cache.yaml
+       sops updatekeys --yes secrets/server.yaml
+  3. Re-run this script.
+
+Exiting without making any other changes.
+EOF
+  exit 1
+}
+
+discover_targets() {
+  # installer is the one nixosConfigurations target that doesn't import
+  # sops-nix at all (see CLAUDE.md's "Security Notes" -- hardcoded login
+  # password instead) -- config.sops.secrets doesn't exist for it.
+  list_flake_targets "$repo_root" | grep -v '^installer$'
+}
+
+locally_managed_hosts() {
+  for f in "$keydir"/*_ssh_host_ed25519_key.pub; do
+    [[ -e "$f" ]] || continue
+    basename "$f" _ssh_host_ed25519_key.pub
+  done
+}
+
+add_keys_json="[]"
+add_aliases_json="[]"
+dry_run=0
+
+queue_host_sync() {
+  local host="$1"
+  local keyfile="${keydir}/${host}_ssh_host_ed25519_key"
+  local has_local_key=0 has_anchor=0
+  [[ -f "$keyfile" ]] && has_local_key=1
+  grep -qE "^  - &${host} age1" "$sops_yaml" && has_anchor=1
+
+  if [[ "$has_local_key" -eq 0 && "$has_anchor" -eq 1 ]]; then
+    echo "SKIP ${host}: .sops.yaml already has an &${host} anchor, but"
+    echo "     host-keys/${host}_ssh_host_ed25519_key is missing locally."
+    echo "     Not generating a replacement -- it wouldn't match whatever's"
+    echo "     already registered (and possibly deployed). Remove the"
+    echo "     &${host} line from .sops.yaml first if you really want a"
+    echo "     fresh key, then re-run."
+    return 1
+  fi
+
+  if [[ "$has_local_key" -eq 0 ]]; then
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] ${host}: would generate host key"
+    else
+      echo "==> ${host}: generating host key"
+      generate_host_ed25519_key "$host" "$keyfile"
+    fi
+  else
+    echo "==> ${host}: host key already present"
+  fi
+
+  if [[ "$has_anchor" -eq 0 ]]; then
+    local age_pub
+    if [[ "$dry_run" -eq 1 ]]; then
+      age_pub="dry-run-placeholder-not-a-real-key"
+    else
+      age_pub="$(ssh_pubkey_to_age "${keyfile}.pub")"
+    fi
+    add_keys_json="$(jq --arg host "$host" --arg key "$age_pub" \
+      '. + [{host: $host, age_key: $key}]' <<<"$add_keys_json")"
+  fi
+
+  echo "==> ${host}: checking which secrets files it references"
+  local basenames
+  mapfile -t basenames < <(
+    nix eval --json --no-use-registries --no-accept-flake-config \
+      "${repo_root}#nixosConfigurations.${host}.config.sops.secrets" \
+      --apply 'builtins.mapAttrs (n: v: baseNameOf v.sopsFile)' \
+    | jq -r '[.[]] | unique | .[]'
+  )
+  local basename
+  for basename in "${basenames[@]}"; do
+    add_aliases_json="$(jq --arg host "$host" --arg basename "$basename" \
+      '. + [{host: $host, basename: $basename}]' <<<"$add_aliases_json")"
+  done
+}
+
+# In dry-run, this runs the exact same edit logic (so idempotency/what's-
+# actually-new is determined for real, not guessed) but against a scratch
+# copy of .sops.yaml that's discarded afterward -- the real file is never
+# opened for writing, and `sops updatekeys` never runs.
+apply_edit_plan() {
+  local plan="$1"
+  local target="$sops_yaml"
+  local tmpfile=""
+  if [[ "$dry_run" -eq 1 ]]; then
+    tmpfile="$(mktemp)"
+    cp "$sops_yaml" "$tmpfile"
+    target="$tmpfile"
+  fi
+
+  local result
+  result="$(echo "$plan" | nix-shell "${NIX_OPTS[@]}" -p python3 --run "python3 '${editor}' '${target}'")"
+  [[ -n "$tmpfile" ]] && rm -f "$tmpfile"
+
+  local added removed changed
+  added="$(jq -r '.added_keys[]?' <<<"$result")"
+  removed="$(jq -r '.removed_keys[]?' <<<"$result")"
+  changed="$(jq -r '.changed_secrets_files[]?' <<<"$result")"
+
+  if [[ -z "$added" && -z "$removed" && -z "$changed" ]]; then
+    echo "Nothing changed in .sops.yaml."
+    return
+  fi
+
+  local prefix=""
+  [[ "$dry_run" -eq 1 ]] && prefix="[dry-run] would "
+
+  [[ -n "$added" ]] && echo "${prefix}Add .sops.yaml anchors: $(tr '\n' ' ' <<<"$added")"
+  [[ -n "$removed" ]] && echo "${prefix}Remove .sops.yaml anchors: $(tr '\n' ' ' <<<"$removed")"
+
+  if [[ -n "$changed" ]]; then
+    if [[ "$dry_run" -eq 1 ]]; then
+      echo "[dry-run] would re-encrypt:"
+      while IFS= read -r basename; do
+        [[ -z "$basename" ]] && continue
+        echo "  secrets/${basename}"
+      done <<<"$changed"
+    else
+      echo "Re-encrypting affected secrets files..."
+      while IFS= read -r basename; do
+        [[ -z "$basename" ]] && continue
+        echo "==> secrets/${basename}"
+        sops_updatekeys "${repo_root}/secrets/${basename}"
+      done <<<"$changed"
+    fi
+  fi
+}
+
+flush_additions() {
+  if [[ "$add_keys_json" == "[]" && "$add_aliases_json" == "[]" ]]; then
+    echo "Nothing to do -- every requested target already has a fully registered host key."
+    return
+  fi
+  echo
+  echo "Applying .sops.yaml edits..."
+  local plan
+  plan="$(jq -n --argjson add_keys "$add_keys_json" --argjson add_aliases "$add_aliases_json" \
+    '{add_keys: $add_keys, add_aliases: $add_aliases}')"
+  apply_edit_plan "$plan"
+  echo
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  else
+    echo "Done. Review the .sops.yaml / secrets/*.yaml diff, then commit and push --"
+    echo "the flake build the installer uses has to see the new recipient(s) before"
+    echo "any of these hosts can decrypt their secrets on first boot."
+  fi
+}
+
+cmd_all() {
+  echo "Discovering flake targets..."
+  local targets
+  mapfile -t targets < <(discover_targets)
+  local host
+  for host in "${targets[@]}"; do
+    queue_host_sync "$host" || true
+  done
+  flush_additions
+}
+
+cmd_target() {
+  local host="$1"
+  local targets
+  mapfile -t targets < <(discover_targets)
+  if ! printf '%s\n' "${targets[@]}" | grep -qxF "$host"; then
+    echo "ERROR: '${host}' is not a current nixosConfigurations target." >&2
+    echo "Current targets:" >&2
+    printf '  %s\n' "${targets[@]}" >&2
+    exit 1
+  fi
+  queue_host_sync "$host" || exit 1
+  flush_additions
+}
+
+cmd_remove() {
+  local hosts
+  mapfile -t hosts < <(locally_managed_hosts)
+  if [[ "${#hosts[@]}" -eq 0 ]]; then
+    echo "No locally-managed keys in host-keys/ -- nothing to remove."
+    return
+  fi
+
+  echo "Locally-managed keys:"
+  local i=1 host
+  for host in "${hosts[@]}"; do
+    local registered="not registered in .sops.yaml"
+    grep -qE "^  - &${host} age1" "$sops_yaml" && registered="registered in .sops.yaml"
+    printf '  %d) %s (%s)\n' "$i" "$host" "$registered"
+    i=$((i + 1))
+  done
+
+  local choice
+  read -rp "Remove which one? (number, or blank to cancel): " choice
+  if [[ -z "$choice" ]]; then
+    echo "Cancelled."
+    return
+  fi
+  if ! [[ "$choice" =~ ^[0-9]+$ ]] || (( choice < 1 || choice > ${#hosts[@]} )); then
+    echo "ERROR: invalid selection." >&2
+    exit 1
+  fi
+  local target="${hosts[$((choice - 1))]}"
+
+  if [[ "$dry_run" -ne 1 ]]; then
+    read -rp "Really remove '${target}'? Its host-keys/ files will be deleted and it will lose access to every secrets file it can currently decrypt. (y/N): " confirm
+    if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
+      echo "Cancelled."
+      return
+    fi
+  fi
+
+  local plan
+  plan="$(jq -n --arg host "$target" \
+    '{remove_keys: [$host], remove_aliases_for_hosts: [$host]}')"
+  apply_edit_plan "$plan"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would delete host-keys/${target}_ssh_host_ed25519_key(.pub)."
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+  else
+    rm -f "${keydir}/${target}_ssh_host_ed25519_key" "${keydir}/${target}_ssh_host_ed25519_key.pub"
+    echo "Removed host-keys/${target}_ssh_host_ed25519_key(.pub)."
+    echo
+    echo "Review the diff, then commit and push."
+  fi
+}
+
+cmd_regenerate_all() {
+  local hosts
+  mapfile -t hosts < <(locally_managed_hosts)
+  if [[ "${#hosts[@]}" -eq 0 ]]; then
+    echo "No locally-managed keys in host-keys/ -- nothing to regenerate."
+    return
+  fi
+
+  echo "This will remove and freshly regenerate ALL locally-managed keys:"
+  printf '  %s\n' "${hosts[@]}"
+  echo
+  echo "Every host above will need its new key baked into a rebuilt install"
+  echo "image/tarball before it can decrypt secrets again."
+
+  if [[ "$dry_run" -ne 1 ]]; then
+    if ! confirm_typed "REGENERATE" "Type REGENERATE to confirm: "; then
+      echo "Cancelled."
+      return
+    fi
+  fi
+
+  echo
+  local hosts_json
+  hosts_json="$(printf '%s\n' "${hosts[@]}" | jq -R . | jq -s .)"
+  local plan
+  plan="$(jq -n --argjson hosts "$hosts_json" \
+    '{remove_keys: $hosts, remove_aliases_for_hosts: $hosts}')"
+  apply_edit_plan "$plan"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] would delete ${#hosts[@]} host-keys/ file pair(s)."
+    echo "[dry-run] would then generate fresh replacements for the same hosts"
+    echo "[dry-run] (not simulated further here -- run without --dry-run, or"
+    echo "[dry-run] preview a specific target with: $0 <target> --dry-run)."
+    echo
+    echo "[dry-run] Nothing was changed. Re-run without --dry-run to apply this."
+    return
+  fi
+
+  echo "Removing existing keys..."
+  local host
+  for host in "${hosts[@]}"; do
+    rm -f "${keydir}/${host}_ssh_host_ed25519_key" "${keydir}/${host}_ssh_host_ed25519_key.pub"
+  done
+  echo "Removed ${#hosts[@]} host-keys/ file pair(s)."
+
+  echo
+  echo "Regenerating fresh keys for every current flake target..."
+  cmd_all
+}
+
+main() {
+  local args=()
+  local arg
+  for arg in "$@"; do
+    if [[ "$arg" == "--dry-run" ]]; then
+      dry_run=1
+    else
+      args+=("$arg")
+    fi
+  done
+  set -- "${args[@]+"${args[@]}"}"
+
+  if [[ "$dry_run" -eq 1 ]]; then
+    echo "[dry-run] no changes will be made"
+    echo
+  fi
+
+  nix_extra_opts
+  ensure_admin_decrypt_key
+
+  case "${1:-}" in
+    --all)
+      cmd_all
+      ;;
+    --remove)
+      cmd_remove
+      ;;
+    --regenerate-all-keys)
+      cmd_regenerate_all
+      ;;
+    -h | --help | "")
+      usage
+      ;;
+    --*)
+      echo "Unknown option: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+    *)
+      cmd_target "$1"
+      ;;
+  esac
+}
+
+main "$@"