[fix] keyman: a permission-based test the CI runner is root for

The snapshot run for 0.7.0 failed on this one test and published nothing.
`scanPrivateKeys` classifies a file it cannot open as not-a-key, and the test
made the file unopenable with `chmod 0o000` — which stops nobody with uid 0,
and Gitea's act_runner is a container running as root. So the file was read,
recognised as a private key not named id_*, and reported as skipped.

A dangling symlink instead: ENOENT is not a permission anyone can override,
and it is a realistic ~/.ssh inhabitant. Verified by running the gate in a
node:22 container as root, where the whole workspace is now green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.gitignore

@@ -1,5 +1,8 @@
 .vault
 .vagrant
+# Persistent SSH host key for the dev VM — a real private key, and machine-local
+# anyway (see the Vagrantfile).
+.vagrant-hostkeys
 .python-version
 
 node_modules

CLAUDE.md

@@ -214,13 +214,36 @@ out and watching them stay green.
 
 ## keyman architecture
 
-Much smaller: `keyman.cli.ts` (argv, plus a `--print-config` escape hatch) →
-`keyman.main.ts`, an inquirer menu loop dispatching to one module per operation
-(`list`/`copy`/`generate`/`encrypt`/`decrypt`). `keyman.config.ts` mirrors nopy's
-upward-traversal + `resolution` merge for `.keymanrc.json`, but validates the
-result with Zod and falls back to defaults instead of throwing. `VAULT_ROOT` in
-the environment beats the config file. Encryption shells out to `age` /
-`age-keygen` / `ssh-keygen`, which must be on `PATH`.
+Much smaller: `keyman.cli.ts` (wiring only — argv parsing lives in
+`keyman.args.ts`, which is covered, and the CLI is the error boundary that turns a
+`UsageError` into one line instead of a stack trace) → `keyman.main.ts`, an
+inquirer menu loop dispatching to one module per operation
+(`list`/`copy`/`generate`/`encrypt`/`decrypt`/`rotate`/`retire`/`clear`).
+`keyman.config.ts` mirrors nopy's upward traversal for `.keymanrc.json` but not
+its `resolution` merge: every keyman property is a string, so a child simply wins
+and the strategies could not change an outcome — see `docs/AUDIT.md` §3.3. It
+validates with Zod, falls back to defaults instead of throwing, and warns about a
+key it does not know rather than letting Zod strip it silently. `VAULT_ROOT` in
+the environment beats the config file. It shells out to `age`, `age-keygen`
+(`-y`, to derive the recipient from the identity rather than trusting the
+`# public key:` comment) and `ssh-keygen` (`-y`, to recover a missing `.pub`),
+which must be on `PATH`; `runTool` tells a missing binary apart from a refusing
+one. Nothing shells out to `cp` or `chmod` any more — `decrypt` copies and
+chmods in-process, because the old spawn left a private key at age's 0644 for the
+length of two processes.
+
+The write path is one function, `storeInVault` (`keyman.vault.ts`), shared by
+`encrypt`, `generate` and `rotate`; `listVaultKeys` is the one reader of the
+`<keysDir>/<name>/id_<name>.age` layout. Rotation is deliberately two operations
+(`rotate` adds a replacement under the next name in the series, `retire` deletes
+the superseded key), because a rotation that replaces the key in place locks you
+out of the host it was for. keyman never handles a passphrase: `ssh-keygen`
+prompts for it with stdio inherited, since `-N <value>` put it in argv where `ps`
+could read it.
+
+`docs/AUDIT.md` is a full audit of the package with each finding marked closed as
+it landed, and `docs/PLAN.md` the ten phases that closed them. Both are records
+now, not plans.
 
 ### Updating
 
@@ -365,4 +388,6 @@ unreachable registry). `CubePackageRef` is referenced by the exported
 `NopyConfig` but is not itself re-exported, so a consumer cannot name the type —
 one line, not yet fixed. `DOCS-AUDIT.md` tracks the drift in the remaining
 documents; §2.9 (the nopy README shipping yarn-workspace instructions to npmjs)
-is closed, so the keyman README (§2.10) is now the worst of them.
+and §2.10 (the keyman README describing four of nine operations and inventing a
+tenth) are both closed. The keyman README now quotes `helpText()` verbatim and a
+test fails if the two diverge, which is the shape worth copying for nopy.

Vagrantfile

@@ -1,6 +1,27 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 
+require 'fileutils'
+
+# A destroyed-and-recreated box generates fresh SSH host keys, so the entry in
+# ~/.ssh/known_hosts for [127.0.0.1]:2222 goes stale and pyinfra aborts with
+# "Host key ... does not match" — it reads the real known_hosts, because its
+# @vagrant connector copies only HostName/Port/User/IdentityFile out of
+# `vagrant ssh-config` and drops the StrictHostKeyChecking/UserKnownHostsFile
+# lines vagrant emits. Nor would relaxing that help: paramiko rejects a
+# *mismatched* key before any policy is consulted.
+#
+# So: keep one keypair on the host, install it into every incarnation of the
+# VM, and pin the known_hosts entry to it after boot.
+HOSTKEY_DIR  = File.join(__dir__, '.vagrant-hostkeys')
+HOSTKEY_PATH = File.join(HOSTKEY_DIR, 'ssh_host_ed25519_key')
+
+unless File.exist?(HOSTKEY_PATH)
+  FileUtils.mkdir_p(HOSTKEY_DIR)
+  system('ssh-keygen', '-q', '-t', 'ed25519', '-N', '', '-C', 'ansiblingsvm', '-f', HOSTKEY_PATH) \
+    or raise "Vagrantfile: ssh-keygen failed to create #{HOSTKEY_PATH}"
+end
+
 Vagrant.configure("2") do |config|
     config.vm.provider "vmware_desktop" do |vmware|
         vmware.gui = false
@@ -19,4 +40,71 @@ Vagrant.configure("2") do |config|
     #  echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpnZ6IxwQKL1rBE4dy7w5Sd3s2tLFZUDfjH87C1QIlc bdiedrichsen@Benjamins-MBP.lan" >> ~/.ssh/authorized_keys
     #  chmod 600 ~/.ssh/authorized_keys
     #SHELL
+
+    # Land the private key as the vagrant user first; the shell provisioner
+    # below is what moves it into /etc/ssh with root ownership and 0600.
+    config.vm.provision "hostkey-upload",
+      type: "file",
+      run: "always",
+      source: HOSTKEY_PATH,
+      destination: "/tmp/ssh_host_ed25519_key"
+    config.vm.provision "hostkey-upload-pub",
+      type: "file",
+      run: "always",
+      source: "#{HOSTKEY_PATH}.pub",
+      destination: "/tmp/ssh_host_ed25519_key.pub"
+
+    # Idempotent: only restarts sshd when the key actually changed, so a
+    # `vagrant up` on an untouched VM does not bounce the connection.
+    config.vm.provision "hostkey-install",
+      type: "shell",
+      run: "always",
+      inline: <<-SHELL
+        set -eu
+        if cmp -s /tmp/ssh_host_ed25519_key /etc/ssh/ssh_host_ed25519_key \\
+           && [ -f /etc/ssh/sshd_config.d/99-pinned-hostkey.conf ]; then
+          rm -f /tmp/ssh_host_ed25519_key /tmp/ssh_host_ed25519_key.pub
+          echo "host key already pinned"
+          exit 0
+        fi
+
+        install -o root -g root -m 600 /tmp/ssh_host_ed25519_key     /etc/ssh/ssh_host_ed25519_key
+        install -o root -g root -m 644 /tmp/ssh_host_ed25519_key.pub /etc/ssh/ssh_host_ed25519_key.pub
+        rm -f /tmp/ssh_host_ed25519_key /tmp/ssh_host_ed25519_key.pub
+
+        # Offer *only* this key. Ubuntu's sshd_config Includes sshd_config.d/*
+        # before its own (commented-out) HostKey lines, and naming any HostKey
+        # replaces the built-in default set — so a regenerated RSA or ECDSA key
+        # can never become the identity a client pins.
+        mkdir -p /etc/ssh/sshd_config.d
+        echo "HostKey /etc/ssh/ssh_host_ed25519_key" > /etc/ssh/sshd_config.d/99-pinned-hostkey.conf
+        chmod 644 /etc/ssh/sshd_config.d/99-pinned-hostkey.conf
+
+        sshd -t
+        systemctl restart ssh 2>/dev/null || service ssh restart
+        echo "host key pinned"
+      SHELL
+
+    # Established sessions survive the sshd restart above, but the *next*
+    # connection sees the new key — so refresh known_hosts on the host from the
+    # public key we already hold, rather than blind-trusting a keyscan.
+    config.trigger.after [:up, :provision, :reload] do |trigger|
+      trigger.name = "pin known_hosts entry"
+      trigger.ruby do |_env, machine|
+        info = machine.ssh_info
+        next if info.nil?
+
+        entry = "[#{info[:host]}]:#{info[:port]} #{File.read("#{HOSTKEY_PATH}.pub").split[0, 2].join(' ')}"
+        known_hosts = File.expand_path('~/.ssh/known_hosts')
+
+        FileUtils.mkdir_p(File.dirname(known_hosts), mode: 0o700)
+        FileUtils.touch(known_hosts) unless File.exist?(known_hosts)
+        system('ssh-keygen', '-q', '-R', "[#{info[:host]}]:#{info[:port]}", '-f', known_hosts,
+               out: File::NULL, err: File::NULL)
+        FileUtils.rm_f("#{known_hosts}.old")
+        File.open(known_hosts, 'a') { |f| f.puts(entry) }
+
+        machine.ui.info("known_hosts pinned to #{entry.split[1, 2].first} for #{info[:host]}:#{info[:port]}")
+      end
+    end
   end

packages/keyman/README.md

@@ -1,104 +1,80 @@
-# Keyman - SSH Key Management with Age Encryption
+# keyman — SSH key management with an age-encrypted vault
 
-Keyman is a simple command line tool built around the `age` encryption tool. It allows you to manage SSH keys in public GitHub repositories securely by encrypting the private keys.
+keyman keeps SSH private keys in a vault you can commit. Each key is encrypted
+with [age](https://github.com/FiloSottile/age) to a single recipient — the vault's
+identity file — which is the one thing that has to stay out of the repository.
 
-## Features
+It is an interactive menu rather than a set of subcommands: point it at a vault,
+pick an operation, repeat until you quit.
 
-- 🔐 Encrypt SSH private keys with age encryption
-- 📁 Organized vault structure: `vault/keys/` for encrypted keys, `vault/tmp/` for decrypted keys
-- ⚙️ Configurable via `.keymanrc.json` with sensible defaults
-- 🔍 Interactive CLI for encrypting, decrypting, and listing keys
-- 🔄 Support for key rotation
+## Requirements
 
-## Quick Start
+`age`, `age-keygen` and `ssh-keygen` on `PATH`. keyman shells out to all three and
+names the missing one instead of failing obscurely.
 
-### 1. Generate Age Encryption Key
+## Installing
 
-```bash
-# Create vault structure
-mkdir -p vault/keys vault/tmp
+```sh
+npm install -g @bitsquare/keyman@main \
+  --@bitsquare:registry=https://gitea.bitsquare.dev/api/packages/BitSquare/npm/
+```
 
-# Generate age encryption key (keep this secret!)
+Point the **scope** at that registry rather than setting a bare `--registry`: it
+serves `@bitsquare` packages only and does not proxy npmjs, so every other
+dependency has to keep resolving from npmjs. Reading needs no token while the
+repository is public, and the same line works with `pnpm`.
+
+`@main` is a snapshot of the default branch, published on every push. Name a tag —
+there is no `latest` on that registry yet, so an untagged install resolves to
+nothing, and keyman has not been released to npmjs. `keyman self-update` keeps you
+on whichever channel you installed from.
+
+## Quick start
+
+```sh
+# The vault identity. The only secret in the vault, and the only thing here you
+# cannot regenerate — back it up somewhere that is not this repository.
+mkdir -p vault
 age-keygen -o vault/age.key
 
-# Add to .gitignore
-echo "vault/age.key" >> .gitignore
-echo "vault/tmp/" >> .gitignore
-```
-
-### 2. Generate SSH Keys
-
-```bash
-# Generate SSH key pair
-ssh-keygen -t ed25519 -f vault/tmp/id_deploy -N "" -C "deploy@myapp.dev"
-```
-
-### 3. Run Keyman
-
-```bash
-# Run keyman interactively
+# Run keyman against it.
 VAULT_ROOT=./vault keyman
-
-# Or if you have .keymanrc.json configured, just run:
-keyman
 ```
 
-## Configuration
+On startup keyman creates `keys/` and `tmp/` under the vault at `0700` and writes
+a `.gitignore` beside them covering the identity and `tmp/`, so a fresh vault
+cannot be committed by accident.
 
-Keyman uses sensible defaults but can be customized via `.keymanrc.json`:
-
-```json
-{
-  "vaultRoot": "./vault",
-  "keysDir": "keys",
-  "tmpDir": "tmp",
-  "ageKeyFile": "age.key"
-}
-```
-
-### Configuration Priority
-
-1. **VAULT_ROOT** environment variable (highest priority)
-2. **.keymanrc.json** file (searched from current directory upward)
-3. **Default values** (lowest priority)
-
-### Default Values
-
-- `vaultRoot`: `"vault"`
-- `keysDir`: `"keys"`
-- `tmpDir`: `"tmp"`
-- `ageKeyFile`: `"age.key"`
-
-## Vault Structure
-
-```
-project/
-├── vault/
-│   ├── age.key         # Master encryption key (NEVER commit!)
-│   ├── keys/           # Encrypted keys (safe to commit)
-│   │   └── deploy/     # Each key has its own folder
-│   │       ├── id_deploy.pub        # Public key
-│   │       └── id_deploy.age        # Encrypted private key
-│   └── tmp/            # Decrypted keys (NEVER commit!)
-│       ├── id_deploy       # Decrypted private key
-│       └── id_deploy.pub   # Public key
-└── .keymanrc.json      # Configuration (optional)
-```
+Then pick **🆕 Generate key**: it makes the key pair and encrypts it into the vault
+in one step. `ssh-keygen` collects the passphrase itself — keyman never sees it, so
+it can never put it on a command line.
 
 ## Operations
 
-Keyman provides an interactive menu-driven interface with the following operations:
+Every operation returns to the menu, so a session can run several.
 
-- **📋 List keys** - Compact view showing all keys with checkbox indicators for their locations
-- **🔒 Encrypt keys** - Encrypt SSH keys from `vault/tmp/` and store in `vault/keys/`
-- **🔓 Decrypt keys** - Decrypt keys from `vault/keys/` to `vault/tmp/` or `~/.ssh/`
-- **❌ Quit** - Exit the program
+- **📋 List keys** — every key it can see and where it is: encrypted in the vault,
+  decrypted in `tmp/`, live in `~/.ssh`, or some combination.
+- **📝 Copy public key** — the public half of a key in `~/.ssh` or `tmp/`, to the
+  clipboard via whichever of `pbcopy`, `clip`, `wl-copy`, `xclip` or `xsel` exists.
+  With none of them, it prints the key instead.
+- **🆕 Generate key** — an `ed25519` or 4096-bit `rsa` pair into `tmp/`, encrypted
+  into the vault straight away.
+- **🔒 Encrypt keys** — pick from the private keys in `~/.ssh` *and* `tmp/`; each
+  goes to `<keysDir>/<name>/` with its public half beside it. A key that has no
+  `.pub` file gets one derived with `ssh-keygen -y`. One key failing costs only
+  that key.
+- **🔓 Decrypt keys** — pick from the vault and decrypt to `tmp/` or `~/.ssh`.
+  Never overwrites a file without asking first, and the plaintext key is `0600`
+  from the moment it exists.
+- **🔄 Rotate key** — a replacement for a vault key, encrypted *alongside* the
+  original. See below.
+- **🗑️ Retire key** — the other half of a rotation: delete a vault key and its
+  plaintext copies, after listing every path that goes.
+- **🧹 Clear decrypted keys** — remove the plaintext keys from `tmp/`.
+- **❌ Quit**
 
-After completing any operation, keyman automatically returns to the main menu, allowing you to perform multiple operations in a single session without restarting the tool.
-
-### List Keys Output
-
-The list command shows a compact, unified view of all SSH keys with their locations:
+### Listing
 
 ```
 🔑 SSH Keys:
@@ -117,36 +93,163 @@ The list command shows a compact, unified view of all SSH keys with their locati
   ⚠️  = Unmanaged (in .ssh or tmp, not encrypted in vault)
 ```
 
-**Features:**
-- Public keys are indicated with `(.pub)` suffix instead of separate entries
-- Status emoji shows management state at a glance
-- Checkboxes `[✓]` show presence in three locations:
-  - **[Vault]** - Encrypted in vault/keys/
-  - **[Tmp]** - Decrypted in vault/tmp/
-  - **[.ssh]** - Active in ~/.ssh/
-- Alphabetically sorted for easy scanning
-- New **🔓** status for keys decrypted to tmp but not yet in .ssh
+`(.pub)` means a public key was found next to the private one, in either location.
+The rows are sorted by name.
 
-## Example Usage
+### Rotating a key
 
-```bash
-# Using environment variable
-VAULT_ROOT=../../vault keyman
+Rotation is deliberately two operations, because both keys have to exist at once:
 
-# Using default configuration
-keyman
+1. **🔄 Rotate key**, and pick `prod`. keyman generates `id_prod-2` in `tmp/`,
+   encrypts it to `keys/prod-2/`, and prints both public keys. `prod` is untouched.
+2. Add the `prod-2` public key wherever `prod` is authorized.
+3. Check that you can log in with `tmp/id_prod-2`.
+4. Remove the `prod` public key from those hosts.
+5. **🗑️ Retire key**, and pick `prod`.
 
-# Keyman will show:
-# 📁 Vault Root: /path/to/vault
-# 🔑 Keys Directory: /path/to/vault/keys
-# 📂 Temp Directory: /path/to/vault/tmp
-# 🔐 Age Key: /path/to/vault/age.key
+The name has to change: the vault directory is derived from it, so a replacement
+also called `prod` *is* the `prod` entry. Rotating again continues the series
+(`prod-2` → `prod-3`), and a version already taken — in the vault, in `tmp/` or in
+`~/.ssh` — is skipped rather than overwritten.
+
+Doing it in one step instead is what this shape avoids: replace the key in the
+vault and you have locked yourself out of the host you were rotating for, because
+the replacement is not on it yet and the only copy of the key that is has gone.
+Retiring warns when nothing in the vault supersedes the key, and then asks you to
+type its name.
+
+### The `id_` prefix
+
+keyman manages keys named `id_*`; the vault directory for `id_prod` is `prod`.
+A private key named anything else is not offered by any operation — but List, Copy
+and Encrypt report the ones they found, with a count and the reason, so it is
+never silently invisible. Rename it to `id_<name>` to bring it in.
+
+## Command line
+
+```
+keyman — SSH key management and an age-encrypted key vault
+
+Usage
+  keyman                             start the interactive menu
+  keyman self-update                 update keyman itself (alias: upgrade)
+
+Flags
+  -h, --help                         print this help and exit
+  -V, --version                      print the version and exit
+      --print-config                 print the resolved paths and the config files
+                                     they came from, as JSON, and exit
+      --self-update                  same as the self-update subcommand
+
+Flags for self-update
+      --channel <latest|next|main>   channel to update from
+                                     (default: derived from the running version)
+      --registry <url>               registry to query instead of the configured one
+  -n, --dry-run                      print the install command without running it
+  -f, --force                        reinstall even when already up to date
+
+Environment
+  VAULT_ROOT                         overrides vaultRoot from .keymanrc.json
+  KEYMAN_REGISTRY                    registry for the update check and self-update
+  KEYMAN_REGISTRY_TOKEN              bearer token for a private registry
+  KEYMAN_NO_UPDATE_CHECK             set to 1 to skip the once-a-day update check
+                                     (also skipped whenever CI is set)
+  KEYMAN_PACKAGE_MANAGER             npm | pnpm | yarn | bun for the install command
+
+Configuration is read from .keymanrc.json, merged from the current directory
+upwards and then from ~/.keymanrc.json.
 ```
 
-## Best Practices
+The update channel is derived from the version you are running — a `-main.` build
+checks `main`, any other prerelease checks `next`, a clean version checks `latest`
+— so an update cannot quietly move you to a different channel. The check runs at
+most once a day and prints its hint to **stderr**, which keeps `--print-config`
+machine-readable.
 
-1. **Never commit** `vault/age.key` or `vault/tmp/` to version control
-2. **Always backup** your `age.key` securely (password manager, encrypted USB)
-3. **Commit** `vault/keys/` - encrypted keys are safe to share
-4. **Use environment variables** for CI/CD: `VAULT_ROOT=/path/to/vault keyman`
-5. **Keep .keymanrc.json** in your project root for team consistency
+## Configuration
+
+`.keymanrc.json`, with every key optional:
+
+```json
+{
+  "vaultRoot": "vault",
+  "keysDir": "keys",
+  "tmpDir": "tmp",
+  "ageKeyFile": "age.key"
+}
+```
+
+| key          | default    | meaning                                              |
+| ------------ | ---------- | ---------------------------------------------------- |
+| `vaultRoot`  | `vault`    | the vault directory; everything else lives inside it |
+| `keysDir`    | `keys`     | the encrypted keys — the part that is safe to commit |
+| `tmpDir`     | `tmp`      | decrypted keys, in plaintext                         |
+| `ageKeyFile` | `age.key`  | the age identity the vault encrypts to               |
+
+The last three are resolved against `vaultRoot` unless they are absolute. A
+relative `vaultRoot` **in a config file** is resolved against that file's
+directory, so a repository config keeps meaning the same vault from any
+subdirectory; the built-in default is resolved against the current directory.
+
+Files are read from `~/.keymanrc.json` first, then from the filesystem root down
+to the current directory, so the nearest file wins key by key. `VAULT_ROOT` in the
+environment beats all of them. A file that is not valid JSON is skipped with a
+warning rather than taken as fatal, and a key keyman does not know is reported
+instead of silently dropped — `{"vaultroot": "…"}` used to be indistinguishable
+from an empty file.
+
+`keyman --print-config` answers what all of that resolved to, and which files it
+came from:
+
+```sh
+$ keyman --print-config
+{"vaultRoot":"/srv/infra/vault","keysDir":"/srv/infra/vault/keys","tmpDir":"/srv/infra/vault/tmp","keyPath":"/srv/infra/vault/age.key","configFiles":["/srv/infra/.keymanrc.json"]}
+```
+
+## Vault layout
+
+```
+project/
+├── vault/
+│   ├── .gitignore      # written by keyman: the identity and tmp/, not keys/
+│   ├── age.key         # the vault identity (NEVER commit)
+│   ├── keys/           # encrypted keys (safe to commit)
+│   │   └── deploy/         # one directory per key, named without the id_ prefix
+│   │       ├── id_deploy.age   # the private key, encrypted to the vault recipient
+│   │       └── id_deploy.pub   # the public key
+│   └── tmp/            # decrypted keys (NEVER commit)
+│       ├── id_deploy
+│       └── id_deploy.pub
+└── .keymanrc.json      # optional
+```
+
+With a custom `keysDir` or `tmpDir`, those two names change and nothing else does.
+
+## Practices this tool assumes
+
+1. **Back up `age.key`** somewhere outside the repository. It is the only thing
+   that can decrypt the vault, and nothing in the vault can reconstruct it.
+2. **Commit `keys/`.** Encrypted keys are the point; a vault nobody shares is a
+   directory.
+3. **Do not commit the identity or `tmp/`.** keyman writes a `.gitignore` for
+   this, and never overwrites one you wrote yourself — check it if you brought
+   your own.
+4. **Clear `tmp/` when you are done with it** (🧹), so plaintext keys do not
+   outlive the reason they were decrypted.
+5. **Keep `.keymanrc.json` in the project root** so everyone resolves the same
+   vault, and use `VAULT_ROOT` for the exceptions.
+
+## Upgrading from a version before 0.7.0
+
+`keysDir` and `tmpDir` used to be honoured by some operations and ignored by
+others, which left anyone with custom names holding a **split vault**: `generate`
+and `list` used the configured directories while `encrypt` and `decrypt` used
+`<vaultRoot>/keys` and `<vaultRoot>/tmp`. All of them agree now, so anything
+written by the old `encrypt` needs moving once:
+
+```sh
+mv <vaultRoot>/keys/* <vaultRoot>/<keysDir>/
+```
+
+Nobody on the default names is affected — for them the two halves were the same
+directory all along.

packages/keyman/docs/AUDIT.md

@@ -0,0 +1,822 @@
+# keyman audit
+
+A review of `packages/keyman` for defects, unimplemented features, and drift
+between the code and the documents that describe it.
+
+Severity is about what it costs a user:
+
+- **🔴 broken** — normal use produces a crash, data loss, or a silently wrong result.
+- **🟠 misleading** — the code or a document states something that is not true.
+- **🟡 gap** — something real that nothing mentions, or dead weight nobody uses.
+
+Verified against `75983ab` with no uncommitted changes in the package. Line
+numbers are from that state. Findings marked **verified** were reproduced by
+running the code, not inferred from reading it; the reproduction is quoted.
+
+Baseline: 162 tests pass, 98.9 % lines / 96.2 % branches. High coverage is
+context for §1.2, not a defence of it.
+
+## Status
+
+**All 30 findings are closed except the second half of §1.8**, over the ten phases
+of `PLAN.md`. Each one keeps its original text as the record, with what closed it
+quoted underneath; the line numbers still point at `75983ab`, so they are history
+rather than directions. The one deliberate omission is making keys not named `id_*`
+*manageable* — they are now reported rather than silently skipped, and the rest is a
+change to the on-disk layout that wanted sizing first.
+
+Where the audit ends: 336 tests, 99.3 % statements / 95.7 % branches.
+
+---
+
+## Contents
+
+- [1. Defects](#1-defects)
+- [2. Security](#2-security)
+- [3. Unimplemented and dead](#3-unimplemented-and-dead)
+- [4. Public API and packaging](#4-public-api-and-packaging)
+- [5. Documentation drift](#5-documentation-drift)
+- [6. Checked and accurate](#6-checked-and-accurate)
+- [Suggested order of attack](#suggested-order-of-attack)
+
+---
+
+## 1. Defects
+
+### 1.1 ✅ `keysDir` and `tmpDir` are honoured by half the tool — **fixed**
+
+> **Closed in Phase 5.** `main.ts` passes `paths.keysDir` and `paths.tmpDir` to
+> `encrypt` and `decrypt`, neither of which joins `vaultRoot` itself any more, so all
+> five operations agree on the configured directories. `tests/vault-layout.test.ts` is
+> the regression test: non-default names in a real config file, the real loader, one
+> encrypt, and a listing that has to show the key in the vault column.
+
+`resolveConfigPaths()` (`keyman.config.ts:249-259`) resolves all four paths from
+the config, and `keyman.main.ts:18-21` prints them. But dispatch is inconsistent
+about what it hands each operation:
+
+| Operation | receives | uses |
+| --- | --- | --- |
+| `listKeys` (`main.ts:67`) | `paths.keysDir` | the configured directory |
+| `generateKey` (`main.ts:73`) | `paths.keysDir`, `paths.tmpDir` | the configured directories |
+| `copyKey` (`main.ts:70`) | `paths.tmpDir` | the configured directory |
+| `encryptKeys` (`main.ts:76`) | `paths.vaultRoot` | **hardcoded** `<vaultRoot>/keys` (`encrypt.ts:38`) |
+| `decryptKeys` (`main.ts:84`) | `paths.vaultRoot` | **hardcoded** `<vaultRoot>/keys` (`decrypt.ts:7`) and `<vaultRoot>/tmp` (`decrypt.ts:39,43`) |
+
+With the defaults the two halves agree, which is why this is invisible. Set
+either sub-directory and the vault splits in two.
+
+**Verified.** With `{"vaultRoot":"./v","keysDir":"encrypted","tmpDir":"plain"}`,
+`keyman --print-config` reports:
+
+```json
+{"...":"...","keysDir":"…/v/encrypted","tmpDir":"…/v/plain","keyPath":"…/v/age.key"}
+```
+
+so `generate` writes to `v/encrypted/<name>/` and `list` scans `v/encrypted`,
+while `encrypt` writes to `v/keys`, and `decrypt` reads `v/keys` and writes
+`v/tmp` — never touching either configured directory. Concretely:
+
+- encrypt a key, then list it → the list shows nothing in `[Vault]`.
+- generate a key, then decrypt it → "⚠️ No encrypted keys found."
+- decrypt to local, then encrypt → the key is not offered, because `encrypt`
+  reads the configured `tmpDir` while `decrypt` wrote to the hardcoded one.
+
+No error at any point. The user has two vaults and one of them is invisible to
+whichever operation they try next.
+
+The current behaviour is locked in by tests: `main.test.ts:164-187` asserts
+`vaultRoot` is what encrypt and decrypt receive ("encrypts keys into the vault
+root"), and `encrypt.test.ts:95` / `decrypt.test.ts:53` assert the literal
+`keys` segment. Fixing this means changing those assertions.
+
+**Fix.** Pass `paths.keysDir` and `paths.tmpDir` into `encryptKeys` and
+`decryptKeys` and delete the three `path.join(vaultDir, 'keys' | 'tmp')` calls.
+Neither function has a use for `vaultRoot` once that is done, so the parameter
+goes away rather than becoming a second source of truth.
+
+See also §5.1 — `DOCS-AUDIT.md` currently lists this layout under *checked and
+accurate*.
+
+### 1.2 ✅ Encrypt and decrypt crash with a raw stack trace on a first run — **fixed**
+
+> **Closed in Phases 1 and 2.** `keyman.cli.ts` is an error boundary — a
+> `UsageError` prints one line, anything else prints its message and exits 1, and
+> neither prints a stack. The two readdirs that threw are guarded (§1.5).
+
+Three `readdirSync` calls have no `existsSync` guard:
+
+- `encrypt.ts:13` — `~/.ssh`, which nothing creates.
+- `encrypt.ts:16` — the tmp directory.
+- `decrypt.ts:8` — `<vault>/keys`, which nothing creates either.
+
+`keyman.main.ts:40-41` creates `vaultRoot` and `tmpDir`. It does **not** create
+`keysDir`, so `decrypt` on a fresh vault throws instead of printing its
+"⚠️ No encrypted keys found." message — the message is unreachable until the
+directory exists for some other reason.
+
+**Verified**, calling both functions directly against a vault laid out the way
+`main.ts` lays it out:
+
+```
+--- A: decryptKeys with no vault/keys directory ---
+THREW: Error ENOENT ENOENT: no such file or directory, scandir '…/vault/keys'
+--- B: encryptKeys with no ~/.ssh directory ---
+THREW: Error ENOENT ENOENT: no such file or directory, scandir '…/home/.ssh'
+```
+
+What the user sees is worse than the exception, because of `keyman.cli.ts:82`:
+
+```ts
+keyman();
+```
+
+Not awaited, no `.catch`. Any rejection anywhere in the menu loop becomes an
+unhandled rejection: Node prints the stack and exits non-zero, and the menu loop
+— whose whole point (`README.md:97`) is that you can run several operations in
+one session — is gone.
+
+`copyKey` guards (`copy.ts:8`) and `listKeys` guards all three of its
+directories (`list.ts:22,50,78`). Encrypt and decrypt are the outliers, not the
+rule.
+
+Worth noting where the coverage numbers sit: `keyman.encrypt.ts` and
+`keyman.decrypt.ts` are both at **100 % lines, 100 % branches**. Every test
+creates the directories in `beforeEach` (`encrypt.test.ts:46-47`,
+`decrypt.test.ts:54-55`), so the missing guard is not a branch that went
+uncovered — it is a branch that was never written. Line coverage measures lines
+executed, not inputs considered.
+
+**Half closed (Phase 1).** `keyman()` is now awaited inside a `catch`, so a
+rejection is one line rather than an unhandled-rejection stack trace. The missing
+`existsSync` guards — and with them the menu loop surviving a failed operation —
+are Phase 2.
+
+### 1.3 ✅ A missing `age.key` becomes `age -r null` — **fixed**
+
+> **Closed in Phase 3.** The recipient is resolved once per session, before any
+> operation that needs one. A null aborts *that operation* with
+> `age-keygen -o <path>` as the remedy and returns to the menu, and is retried on the
+> next attempt, so creating the identity mid-session works. `age -r null` is now
+> unreachable.
+
+`keyman.main.ts:73` and `:80` assert away a null:
+
+```ts
+extractAgePublicKey(paths.keyPath)!
+```
+
+`extractAgePublicKey` returns `string | null` (`utils.ts:8-22`) and returns null
+in three cases: the file is missing, it is unreadable, or it parses but has no
+`# public key:` line. In all three it prints an error and returns — and the
+non-null assertion carries that null straight into an `execa` argv.
+
+**Verified**, both halves:
+
+```
+❌ ERROR: Age key file not found at /nope/age.key
+extractAgePublicKey(missing) = null
+execa with null recipient THREW: ExecaError | Command failed with exit code 1: age -r null -o /tmp/x.age /etc/hosts
+```
+
+execa stringifies the null, so the recipient becomes the literal `"null"`.
+
+The two call sites fail differently, and the generate path fails worse:
+
+- `generateKey` runs `ssh-keygen` **first** (`generate.ts:59`) and `age` second
+  (`generate.ts:68`). Its `try/catch` swallows the failure into "❌ Error
+  generating/encrypting key", but by then the private key is on disk in `tmpDir`
+  in plaintext, and the user has been told the operation failed. Nothing tells
+  them a key was left behind.
+- `encryptKeys` has no `try/catch` at all, so it takes the §1.2 path: unhandled
+  rejection, stack trace, session over.
+
+**Fix.** Resolve the recipient once, before dispatch, and treat null as a
+recoverable condition: print what to run (`age-keygen -o <keyPath>`) and return
+to the menu. The type already says this is possible; the `!` is the only thing
+claiming otherwise.
+
+### 1.4 ✅ Decrypting into `~/.ssh` silently overwrites an existing key — **fixed**
+
+> **Closed in Phase 4.** Every collision is settled before anything is written: a
+> confirmation per key defaulting to no, and a skip that says what it kept. The user
+> is answering about files that still exist.
+
+`decrypt.ts:47-49` writes the decrypted key and copies the public key with no
+existence check, no confirmation, and no backup.
+
+**Verified** that `age -o` does not refuse an existing file:
+
+```
+before: PRECIOUS EXISTING KEY
+age -o exit=0 (overwrote)
+after: secret
+```
+
+So selecting `prod` with the `SSH (~/.ssh)` destination replaces
+`~/.ssh/id_prod` outright. If the vault copy is stale, or the folder name
+happens to collide with an unrelated local key, the local key is gone — and this
+is the one operation in the tool that writes outside the vault, into the
+directory the user's actual SSH access depends on.
+
+The `Local (vault/tmp)` destination has the same behaviour but a much lower cost,
+since `vault/tmp` is scratch space by design.
+
+**Fix.** Check both output paths before decrypting anything and prompt per
+collision, or refuse and name the file. A `--force` equivalent can come later;
+the current default should not be "overwrite".
+
+### 1.5 ✅ `age` or `ssh-keygen` missing is unhandled in encrypt and decrypt — **fixed**
+
+> **Closed in Phase 2.** `runTool` turns `ENOENT` into a `ToolNotFoundError`
+> whose message is an instruction, and keeps it distinct from a tool that ran and
+> refused — whose reason is on stderr and nowhere in execa's message. `encrypt`
+> re-throws it instead of counting it against one key.
+
+Same missing `try/catch` as §1.3. `generateKey` (`generate.ts:51-76`) and
+`copyKey` (`copy.ts:43-57`) both wrap their `execa` calls and report a failure;
+`encryptKeys` and `decryptKeys` do not. On a machine without `age` on `PATH` —
+the one hard external requirement, per `CLAUDE.md` — choosing Encrypt from the
+menu produces an `ENOENT` stack trace rather than "install age".
+
+### 1.6 ✅ Encrypt copies `.pub` unconditionally and aborts the batch midway — **fixed**
+
+> **Closed in Phase 6.** `storeInVault` reads the `.pub` *before* the vault
+> directory exists and derives a missing one with `ssh-keygen -y` — stdout piped,
+> stdin and stderr inherited, because the passphrase prompt goes to stderr — storing
+> the private key alone if it cannot. And a failing key costs one key: `encrypt`
+> collects the failures and names them at the end.
+
+`encrypt.ts:45`:
+
+```ts
+fs.copyFileSync(`${keyPath}.pub`, path.join(vaultPath, `${key}.pub`));
+```
+
+The selection list is built from *private* keys only (`encrypt.ts:14,17` filter
+out `.pub`), so a private key with no `.pub` sibling is offered — and that is a
+legal state, since `ssh-keygen -y` regenerates a public key on demand and people
+do delete them.
+
+When it happens, `age` has already written the `.age` file, so the throw leaves
+the vault holding an encrypted key with no public key. Worse, the throw escapes
+the `for` loop: every remaining selected key is skipped, with no output saying
+so, and the process dies via §1.2.
+
+`generate.ts:71` has the same shape but is far less likely to fire, since
+`ssh-keygen` just wrote the file.
+
+**Fix.** Derive the public key with `ssh-keygen -y -f <key>` when the sibling is
+absent, and wrap the loop body so one bad key costs one key rather than the
+batch.
+
+### 1.7 ✅ `/home/<user>` is hardcoded — **fixed**
+
+> **Closed in Phase 8.** `keyman.home.ts` resolves a named user against the
+> sibling of the current home first, then `/home/<user>` and `/Users/<user>`, and
+> reports every path it tried. An unset `HOME` falls back to the passwd entry instead
+> of resolving `.ssh` against the filesystem root.
+
+`keyman.main.ts:33`:
+
+```ts
+const homeDir = user === '@current' ? process.env.HOME || '' : `/home/${user}`;
+```
+
+On macOS other users live under `/Users/`, and this tool is otherwise
+macOS-specific (§1.9). Nothing checks the directory exists, so a wrong guess
+feeds a nonexistent `sshDir` into §1.2 rather than into an error message.
+`main.test.ts:198-204` locks in `/home/deploy/.ssh`.
+
+**Fix.** `os.userInfo()` for the current user, and for a named user either look
+the home directory up (`getent passwd` / `dscl`) or ask for the path outright.
+Failing that, check `existsSync` and say so.
+
+### 1.8 🟡 Keys not named `id_*` are invisible, silently — **half fixed**
+
+> **Partly closed in Phase 8 — the rest is open.** `scanPrivateKeys` classifies a
+> file by reading its first 64 bytes for a private-key header, and List, Copy and
+> Encrypt report what they skipped, with the count, the directory and the reason. So
+> the keys are no longer *silently* invisible.
+>
+> They are still not manageable. The vault layout derives `id_<dir>` from the
+> directory name in four places, so accepting other names changes what is on disk;
+> the plan asked for that to be sized before being committed to, and the report is
+> the tenth of the work that closes most of the surprise. Left deliberately.
+
+Every discovery filter requires the prefix: `copy.ts:9`, `encrypt.ts:14,17`,
+`list.ts:23,51`, and `decrypt.ts:9` reconstructs `id_${dir}`. A key called
+`deploy_ed25519` cannot be listed, copied, or encrypted, and nothing says why —
+it simply is not in the menu.
+
+`generateKey` enforces the prefix (`generate.ts:43`), so keys keyman creates are
+always fine. The gap only bites pre-existing keys, which is exactly the
+population a key manager is adopted to take over.
+
+### 1.9 ✅ `pbcopy` is hardcoded — **fixed**
+
+> **Closed in Phase 8.** `keyman.clipboard.ts` picks by platform — `pbcopy`,
+> `clip`, or `wl-copy` → `xclip` → `xsel` — falls through only on `ENOENT` (a tool
+> that ran and refused is a real error, not an absent tool), and prints the key when
+> nothing is installed, since printing it was always the point.
+
+`copy.ts:49`, with the comment above it admitting the shortcut:
+
+```ts
+// Since the environment is Darwin, we prioritize pbcopy, but we can add others for completeness
+```
+
+On Linux or Windows, Copy public key always fails. It fails *cleanly* — the
+`try/catch` reports "❌ Failed to copy to clipboard" — but the package declares
+only `"node": ">=22"` in `engines` and the README says nothing, so nothing warns
+before install. `xclip`/`wl-copy`/`clip.exe` by platform is a handful of lines;
+alternatively print the key to stdout as a fallback so the operation is never a
+dead end.
+
+### 1.10 ✅ Smaller things — **fixed**
+
+> **Closed in Phases 2, 6 and 8.** All four: the `statSync` takes
+> `throwIfNoEntry: false` and still follows a symlink to a real directory; both
+> `replace` calls are anchored to `/^id_/`; a failed `age` now removes the file it
+> named and the directory while it is empty, so nothing half-made is left claiming to
+> hold a key; and both `console.log` debug lines are gone.
+
+- **`listKeys` throws on a broken symlink.** `list.ts:80` calls `fs.statSync` on
+  every entry in the keys directory; a dangling symlink throws `ENOENT`, and
+  `listKeys` has no `try/catch`, so it exits via §1.2. `lstatSync`, or a
+  `withFileTypes` readdir, or a guard.
+- **`key.replace('id_', '')` is unanchored** (`encrypt.ts:38`, `generate.ts:63`).
+  Every input is prefix-filtered today, so the first match *is* the prefix and
+  the behaviour is correct — it is a trap left for whoever loosens §1.8.
+  `replace(/^id_/, '')` costs nothing.
+- **An `age` failure leaves an empty vault directory.** `generate.ts:65` creates
+  `<keysDir>/<name>/` before `generate.ts:68` runs `age`.
+  `generate.test.ts:150-163` asserts the `.pub` is absent afterwards but not the
+  directory, so this passes today. It makes the folder show up in
+  `decrypt`'s scan as a candidate that filters back out — harmless, untidy.
+- **Debug output still in shipped code.** `encrypt.ts:18-19`
+  (`console.log(tmpKeys); console.log(sshKeys);`) is already tracked as
+  `DOCS-AUDIT.md` §6.4. `decrypt.ts:10` — a `console.log(keyfile)` *inside a
+  `filter` callback*, printing one line per vault directory — is not, and is the
+  more visible of the two.
+
+---
+
+## 2. Security
+
+### 2.1 ✅ Decrypted private keys are world-readable before the chmod — **fixed**
+
+> **Closed in Phase 4.** `fs.chmodSync(…, 0o600)` in-process, immediately after
+> `age` returns — no `cp` or `chmod` spawn, so there is no window and no failure mode
+> that leaves the mode behind. Confirmed again while probing Phase 10: age still
+> writes 0644, and `ssh-keygen -y` refuses such a file outright.
+
+`decrypt.ts:47-50` decrypts, then copies, then chmods — in three separate
+processes:
+
+```ts
+await execa('age', ['-d', '-i', ageKey, '-o', privateKeyOut, encryptedKey]);
+await execa('cp', [publicKey, publicKeyOut]);
+await execa('chmod', ['600', privateKeyOut]);
+```
+
+**Verified** what `age` creates, and what `mkdirSync` at `main.ts:41` creates:
+
+```
+-rw-r--r--  …/out                     ← the decrypted private key, as age leaves it
+drwxr-xr-x  …/tmpdir                  ← vault/tmp, as keyman creates it
+```
+
+So a plaintext private key exists at `0644` for the lifetime of two process
+spawns, inside a `0755` directory any local user can traverse. If the `chmod`
+fails or the process is killed in between, it stays `0644` — and because
+`decryptKeys` has no `try/catch` (§1.5), a failing `chmod` also kills the
+session before the next key is even attempted.
+
+**Fix.** `fs.chmodSync` immediately after `age` returns rather than a third
+spawn; create `tmpDir` with `{mode: 0o700}` and `~/.ssh` likewise if it is
+missing. Replacing `cp` and `chmod` with `fs.copyFileSync` / `fs.chmodSync` also
+removes two shell-outs that do not work on Windows and cuts three spawns per key
+to one.
+
+### 2.2 ✅ The passphrase is passed on the `ssh-keygen` command line — **fixed**
+
+> **Closed in Phase 6.** The prompt is gone and so is `-N`: `ssh-keygen` collects
+> and confirms the passphrase itself with stdio inherited. A passphrase keyman never
+> learns cannot leak from keyman — and a test asserts it never asks for one.
+
+`generate.ts:53`:
+
+```ts
+const args = ['-t', algorithm, '-f', keyPath, '-N', password, '-C', identity];
+```
+
+argv is world-readable on both Linux (`/proc/<pid>/cmdline`) and macOS
+(`ps -o command`) for the lifetime of the process. Any other user on the machine
+can read the passphrase of a key being generated. `generate.test.ts:78-87`
+asserts this exact argv.
+
+**Fix.** Omit `-N` entirely and let `ssh-keygen` prompt on the tty — it already
+asks twice and confirms, so keyman's own password prompt (`generate.ts:26-33`)
+can go away rather than being replaced. That keeps the passphrase off argv
+without keyman ever holding it.
+
+### 2.3 ✅ The age recipient is trusted from a comment, never verified — **fixed**
+
+> **Closed in Phase 3.** `age-keygen -y` derives the recipient from the secret
+> key, so it cannot disagree with it. The comment survives only as a fallback for a
+> machine with no `age-keygen`, behind a warning that it is unverified — and
+> deliberately *not* as a fallback for `age-keygen` refusing the file, which means
+> age cannot read the identity at all.
+
+`extractAgePublicKey` (`utils.ts:16`) regexes the recipient out of a comment
+line in the identity file:
+
+```ts
+fileContents.match(/^# public key:\s*(age1[^\s]+)/m)
+```
+
+Nothing checks it corresponds to the private key in that same file. Edit the
+comment — or concatenate two key files — and every subsequent encryption goes to
+a recipient the local identity cannot decrypt. The failure surfaces only later,
+at decrypt time, on keys that may no longer exist in plaintext anywhere.
+
+**Fix.** `age-keygen -y <keyPath>` derives the public key *from the private key*
+and is exactly the tool for this. Note that `age-keygen` is currently not
+invoked anywhere in the source, despite `CLAUDE.md` listing it among the
+binaries keyman shells out to (§5.5).
+
+### 2.4 ✅ Nothing manages the plaintext left in `vault/tmp` — **fixed**
+
+> **Closed in Phase 8.** A **🧹 Clear decrypted keys** operation that lists what it
+> will delete and asks before deleting it, plus a `.gitignore` written beside the
+> vault covering the identity and the tmp directory — never overwriting one that is
+> already there, and never claiming to cover a path outside the vault.
+
+Decrypted keys accumulate in `vault/tmp` indefinitely. There is no shred
+operation, no warning on exit, and keyman never writes the `.gitignore` its own
+README (`README.md:25-26`, `:148`) tells the user to write by hand. The only
+signal is the 🔓 marker in `listKeys`, which the user has to go looking for.
+
+A "Clear decrypted keys" menu entry and a `.gitignore` written alongside the
+vault on first run would cost little and close the most likely way a private key
+reaches a public repository — which is the threat this tool exists to address.
+
+---
+
+## 3. Unimplemented and dead
+
+### 3.1 ✅ There is no `--help` — **fixed**
+
+> **Closed in Phase 1.** `helpText()` in `keyman.args.ts`, checked against the
+> parser's own flag table by a test so a new flag cannot ship undocumented, and now
+> quoted verbatim in the README by a second test (§5.3).
+
+`keyman.cli.ts` handles `--print-config`, `--version`/`-V`, and
+`self-update`/`upgrade`, then falls through to the interactive session. `--help`
+is not among them, and neither is any unknown-flag handling.
+
+**Verified.** `keyman --help` with no tty:
+
+```
+📁 Vault Root: …
+? Specify USER (default: @current): (@current)
+…/@inquirer/core/dist/lib/create-prompt.js:67
+            reject(new ExitPromptError(`User force closed the prompt with ${code} ${signal}`));
+```
+
+Two problems in one output. `--help` starts a session instead of describing the
+tool, and because of §1.2 the resulting `ExitPromptError` is an unhandled
+rejection with a stack trace. That second half is what a user gets from **Ctrl-C
+at any prompt** — the normal way to leave an interactive CLI produces a crash
+dump.
+
+`keyman --vault foo` is likewise accepted and ignored.
+
+**Fix.** `--help` listing the flags, the two subcommands, and the `KEYMAN_*`
+environment variables (§5.3); an unknown-flag error; and a `catch` in
+`keyman.cli.ts` that treats `ExitPromptError` as "goodbye" and anything else as
+a one-line error. nopy uses Commander for this; keyman need not, but it does
+need the behaviour.
+
+**Closed (Phase 1).** `src/keyman.args.ts` owns the parse and the help text; the
+`catch` around `keyman()` in `keyman.cli.ts` turns `ExitPromptError` into
+"👋 Goodbye!" and exit 0, and anything else into one line and exit 1.
+
+### 3.2 ✅ `flagValue` accepts things that are not values — **fixed**
+
+> **Closed in Phase 1.** `parseArgs` rejects a value flag with no value, a boolean
+> flag given one, an unknown flag, an unknown command, an unknown channel, and a
+> self-update-only flag used without `self-update`. `--channel --force` is now a
+> usage error rather than a request for a dist-tag that cannot exist.
+
+`keyman.cli.ts:24-27` is `args.indexOf(name)` and `args[index + 1]`:
+
+- `--channel=main` is not recognised.
+- `--channel` as the last argument yields `undefined`.
+- `keyman self-update --channel --force` sets the channel to `"--force"`, which
+  is cast to `Channel` (`cli.ts:47`) and flows into the dist-tag lookup at
+  `update.ts:176` as a key that cannot exist. The registry answers, the tag is
+  absent, and the user is told "Could not reach <registry>" — which is false.
+
+Validating against the three legal channels would turn all three into one clear
+error.
+
+**Closed (Phase 1).** `parseArgs` accepts both `--flag value` and `--flag=value`,
+rejects a flag swallowed as another flag's value, and validates `--channel`
+against `CHANNELS`.
+
+### 3.3 ✅ The `resolution` merge machinery has no effect — **fixed**
+
+> **Closed in Phase 7 — deleted.** Every keyman property is a string, so a child
+> simply wins; `mergeConfigs` is one spread with a comment recording why nopy needs
+> more and keyman does not. `keyman.config.ts` lost ~45 lines.
+
+`keyman.config.ts` carries `ResolutionStrategy`, `KeymanResolutionConfig`,
+`mergeValue` and `mergeConfigs` — roughly 45 lines, imported from nopy's design.
+Every property in `KeymanConfigSchema` is a `z.string()`. For two strings,
+`mergeValue` returns `childValue` in the `override` branch (`:121-123`) and
+returns `childValue` again from the primitive fallthrough (`:156`). The two
+strategies are indistinguishable for every key the schema permits, and the
+array-concat and deep-merge branches are unreachable through a valid config —
+unknown keys pass through the merge but are then stripped by
+`KeymanConfigSchema.parse` (§3.5).
+
+So the documented knob does nothing. The doc comment at `:186-194` advertises it:
+
+```json
+{ "vaultRoot": "../vault", "resolution": { "vaultRoot": "override" } }
+```
+
+and `config.test.ts:212` — "honours an explicit override strategy" — passes for
+a case where plain merge gives the same answer, so the test does not distinguish
+them either.
+
+This is a choice to make, not a bug to fix. Either drop the machinery and the
+comment, or keep it deliberately as the shape a future object-valued or
+array-valued option would need — and say so in a comment, since right now it
+reads as functional.
+
+### 3.4 ✅ `getConfigPaths()` is exported, tested, and called by nothing — **fixed**
+
+> **Closed in Phase 7.** `describeConfig()` calls it, so `--print-config` prints
+> `configFiles` — the files that were merged, in merge order. That was the one
+> question the flag could not answer, and it existed only as unstructured stderr.
+
+`keyman.config.ts:265` is used only by `config.test.ts:122,131`. It is not
+re-exported from `src/index.ts` and not called by the CLI. nopy's equivalent
+feeds `nopy.main.ts:64`.
+
+The absence is felt: `--print-config` prints the *resolved paths* only, so there
+is no way to ask which config files were consulted. That information exists only
+as a stderr side effect of `loadConfig` ("✅ Loaded configuration from …"), which
+is not machine-readable and is interleaved with warnings. Folding
+`getConfigPaths()` into the `--print-config` JSON makes the function earn its
+keep and makes the escape hatch answer the question it is for.
+
+### 3.5 ✅ A typo in `.keymanrc.json` is silent — **fixed**
+
+> **Closed in Phase 7.** `warnUnknownKeys` names the file, the keys it ignored and
+> the keys it knows. Warned rather than fatal, which is this module's posture
+> throughout, and warned per file because that is the only place the filename is in
+> hand.
+
+`KeymanConfigSchema` is a plain `z.object`, which strips unknown keys.
+
+**Verified.** With `{"vaultRoot":"./v","vaultroot":"typo", …}`, the lowercase key
+is dropped without a word and `--print-config` reports the vault from the
+correct key. Had only the typo been present, the user would get the `vault`
+default and no clue.
+
+`.strict()` — or keeping the strip and logging the leftover keys as a warning —
+turns a silently wrong vault into one line of output. Since `loadConfig` already
+degrades to defaults rather than throwing, a warning fits the module's existing
+posture better than a hard failure.
+
+### 3.6 ✅ "Support for key rotation" does not exist — **fixed**
+
+> **Closed in Phase 10 — built.** `keyman.rotate.ts`: **🔄 Rotate key** generates a
+> replacement under the next name in the series and encrypts it *alongside* the
+> original, and **🗑️ Retire key** deletes the superseded key after listing every path
+> that goes, asking for the name to be typed out when nothing in the vault supersedes
+> it. Two operations rather than one, because a rotation that replaces the key in
+> place locks you out of the host you were rotating for.
+
+`README.md:11`. `grep -rn "rotat" packages/keyman/src/` returns nothing. Already
+tracked as `DOCS-AUDIT.md` §2.10, still open. Rotation is a genuinely useful
+operation for this tool — generate a replacement, encrypt it, keep the old one
+until the new one is deployed — so this is worth building rather than deleting.
+
+### 3.7 ✅ "Copy public key and create README" — **fixed**
+
+> **Closed in Phase 5.** The comment went with the rewrite of `encrypt`. No
+> per-key README was ever written and nothing claims one now; the `README.md` fixture
+> in `decrypt.test.ts` is a stray-file case, which `listVaultKeys` ignores.
+
+`encrypt.ts:44` says it; no README is written. Suggestively,
+`decrypt.test.ts:75` places a `README.md` inside the keys directory as a
+fixture, so a per-key README appears to have been the intent once. Either build
+it or drop the half of the comment that lies.
+
+---
+
+## 4. Public API and packaging
+
+### 4.1 ✅ A shebang on the library entry point — **fixed**
+
+> **Closed in Phase 9.** The shebang is gone, with a comment saying why the file
+> does not want one. Verified against the built `dist/index.js`.
+
+`src/index.ts:1` is `#!/usr/bin/env node`. The bin is `dist/keyman.cli.js`
+(`package.json:28`); `index.ts` is the `exports["."]` target and is only ever
+imported. nopy's `src/index.ts` has no shebang. Harmless, and a copy-paste
+artefact.
+
+### 4.2 ✅ The exported functions' types are not exported — **fixed**
+
+> **Closed in Phase 9.** `KeymanConfig` and `KeymanConfigFile` are exported;
+> `ResolutionStrategy` and `KeymanResolutionConfig` no longer exist (§3.3).
+
+`src/index.ts:2` exports `loadConfig` and `resolveConfigPaths`. It does not
+export `KeymanConfig`, `KeymanConfigFile`, `ResolutionStrategy` or
+`KeymanResolutionConfig`, so a TypeScript consumer cannot name what `loadConfig`
+returns or what `resolveConfigPaths` takes. This is the same one-line omission
+`CLAUDE.md` already records for nopy's `CubePackageRef`.
+
+### 4.3 ✅ `export * from './keyman.main.js'` exports only `keyman()` — **fixed**
+
+> **Closed in Phase 9 — decided, and written down.** The surface is deliberately
+> narrow: config resolution, the update machinery, and `keyman()`. The operation
+> modules stay internal because every one of them prompts, prints and spawns, so
+> there is nothing to do with a single one except rebuild the menu around it. The
+> rule is now a comment at the top of `src/index.ts` rather than an accident.
+
+The five operation modules and `extractAgePublicKey` are not on the public
+surface, so the package is consumable as a library only as "run the entire
+interactive menu". That may well be intended — but then `loadConfig` and
+`resolveConfigPaths` being exported is the odd part, since a consumer can obtain
+the paths and do nothing with them.
+
+### 4.4 ✅ Update-module constants are half re-exported — **fixed**
+
+> **Closed in Phase 9.** `export * from './keyman.update.js'`, so the rule is
+> "all of it" and the list cannot drift again. Verified by importing the built
+> `dist/index.js` and reading its keys.
+
+`keyman.update.ts` exports `SCOPE`, `UPDATE_CACHE_DIR`, `UPDATE_CACHE_FILE`,
+`DEFAULT_FETCH_TIMEOUT_MS` and `DEFAULT_CONFIG_TIMEOUT_MS`; `src/index.ts:12-31`
+re-exports neither, while re-exporting `DEFAULT_CHECK_INTERVAL_MS` and
+`NPMJS_REGISTRY`. Pick one rule.
+
+---
+
+## 5. Documentation drift
+
+### 5.1 ✅ `DOCS-AUDIT.md` lists §1.1 under *checked and accurate* — **fixed**
+
+> **Closed in Phase 5.** The claim `DOCS-AUDIT.md` makes — that the documented
+> vault layout matches the code — is now *true*, which is the substance of it; §1.1 is
+> what made it false. The entry has been amended to say what it actually checked.
+
+`DOCS-AUDIT.md:826-827`:
+
+> **keyman config** — priority (`VAULT_ROOT` > file > defaults), the four default
+> values, and the vault layout match `keyman.config.ts` and `keyman.encrypt.ts`.
+
+The first two clauses are correct. The third holds only because
+`keyman.encrypt.ts` hardcodes `keys` — checking the documented layout against
+the file that ignores the config is what made §1.1 invisible. The entry should
+move out of section 7 and point at §1.1.
+
+### 5.2 ✅ `README.md` operations list — **fixed**
+
+> **Closed in Phase 9.** All nine menu entries are documented, and a test asserts
+> the README contains every label `keyman.main.ts` offers, so a tenth cannot arrive
+> undocumented. Encrypt is described as it behaves: the union of `~/.ssh` and the tmp
+> directory.
+
+`DOCS-AUDIT.md` §2.10, re-verified: `README.md:90-96` lists four menu entries;
+`main.ts:54-61` has six. `Copy public key` and `Generate key` are undocumented —
+the latter being the only in-tool way to create a key, which is why the Quick
+Start at `README.md:33` tells the user to run `ssh-keygen` by hand.
+`README.md:93` says encrypt takes keys "from `vault/tmp/`"; `encrypt.ts:12-20`
+unions `~/.ssh` and tmp and offers both.
+
+### 5.3 ✅ The README documents none of the CLI surface — **fixed**
+
+> **Closed in Phase 9.** The README carries `helpText()` verbatim — every flag,
+> both subcommand spellings, and all five environment variables — with a test that
+> fails if the two diverge. Installation, the update channels and the once-a-day
+> check are documented too.
+
+`README.md` covers the interactive menu and the config file. It does not mention:
+
+- `self-update` / `upgrade`, `--dry-run`, `--force`, `--channel`, `--registry`
+- `--version` / `-V`, `--print-config`
+- `KEYMAN_REGISTRY`, `KEYMAN_REGISTRY_TOKEN`, `KEYMAN_NO_UPDATE_CHECK`,
+  `KEYMAN_PACKAGE_MANAGER`
+- the once-a-day update check, or that it is disabled when `CI` is set
+
+`README.PUBLISH.md:552-578` documents all of it, but `package.json:37-41` ships
+only `dist`, `README.md` and `LICENSE` — so a reader on the registry sees none of
+it. This is the same shape as the nopy README problem closed as
+`DOCS-AUDIT.md` §2.9, and keyman is now the worse of the two.
+
+### 5.4 ✅ The README presents a configurable layout that is half-real — **fixed**
+
+> **Closed in Phase 9.** The section documents what §1.1 made true: the three
+> inner names resolve against `vaultRoot`, a relative `vaultRoot` in a config file
+> resolves against that file's directory, and the built-in default resolves against
+> the current directory. It ends with the migration note for a vault written by the
+> old `encrypt`.
+
+`README.md:46-70` documents `keysDir` and `tmpDir` as configuration, and
+`:72-86` draws the default tree. Per §1.1 the first is only half true. Whichever
+way §1.1 is resolved, this section needs an edit.
+
+### 5.5 ✅ `CLAUDE.md` names a binary keyman never runs — **fixed**
+
+> **Closed in Phases 3 and 9.** `age-keygen` became true in Phase 3 (`-y`, to
+> derive the recipient), and `cp`/`chmod` stopped being spawned in Phase 4.
+> `CLAUDE.md` now says all of that, records the deliberate `resolution` divergence
+> from nopy, and lists the operations the menu actually has.
+
+> Encryption shells out to `age` / `age-keygen` / `ssh-keygen`, which must be on
+> `PATH`.
+
+`age-keygen` appears nowhere in `packages/keyman/src`. It appears in
+`README.md:22` as a manual setup step, which is presumably where the claim came
+from. Either note it as a prerequisite the user runs rather than something
+keyman invokes, or make §2.3 true and turn the claim into fact.
+
+`CLAUDE.md` also does not mention that `decryptKeys` shells out to `cp` and
+`chmod` (`decrypt.ts:49-50`) — see §2.1, where the recommendation is to stop.
+
+### 5.6 ✅ The update module has not drifted from nopy's
+
+`keyman.update.ts` and `nopy.update.ts` are described in `CLAUDE.md` as "two
+near-identical copies of one module", the duplication deliberate. Diffed with
+package names normalised: **every difference is a doc comment.** No behavioural
+drift at all. The stated risk of the duplication has not materialised; nopy's
+copy simply carries fuller comments, and porting the better ones over would cost
+nothing.
+
+---
+
+## 6. Checked and accurate
+
+- **Config precedence.** `VAULT_ROOT` > config file > defaults
+  (`config.ts:249-259`), matching `README.md:59-70`. Verified via
+  `--print-config`.
+- **Upward traversal and the home-directory config.** `findConfigFiles`
+  (`config.ts:85-110`) collects root-first and de-duplicates the home config
+  when it is also an ancestor (`:105`).
+- **`loadConfig` never throws.** Invalid JSON is skipped per file (`:220-226`)
+  and a failed final validation degrades to defaults (`:232-241`) — which is the
+  documented difference from nopy's behaviour, and it holds.
+- **`extractAgePublicKey` is honest about failure.** It returns `null` in every
+  failure mode and prints why; the defect in §1.3 is entirely in the caller's
+  `!`.
+- **The menu loop.** Returns to the menu after every operation
+  (`main.ts:45-91`), as `README.md:97` says.
+- **The four default values** and the `id_<name>.age` / `id_<name>.pub` layout
+  inside a per-key folder, as drawn at `README.md:72-86`.
+- **`listKeys` status logic** (`list.ts:127-128`) matches its legend and the
+  README's, including the 🔓 state.
+- **The update module**, in full — see §5.6.
+
+---
+
+## Suggested order of attack
+
+> Superseded by `PLAN.md`, which turned this into ten phases and is the record of
+> what was actually done in what order. Kept because the reasoning about which
+> findings share a shape is still the reason the phases group the way they do.
+
+**1 — the crashes, together.** §1.2, §1.3, §1.5 and §1.10's `statSync` are all
+the same shape: an unguarded call in a function with no error boundary, reaching
+a `keyman()` that is never awaited. One `catch` in `keyman.cli.ts` that
+distinguishes `ExitPromptError` from a real failure, plus `existsSync` guards and
+`try/catch` in encrypt and decrypt, closes all of them and most of §3.1's second
+half. This is the smallest change with the largest effect on what a first run
+feels like.
+
+**2 — §1.4 and §2.1.** Both are in `decryptKeys`, both are about writing outside
+the vault, and one of them destroys data. Replacing `cp`/`chmod` with the `fs`
+equivalents is part of the same edit.
+
+**3 — §1.1.** Mechanical, but it changes four test assertions, so it wants to be
+its own commit. Fix `DOCS-AUDIT.md` §5.1 in the same one.
+
+**4 — decide on §3.3 and §3.6.** Both are features the documentation claims and
+the code does not have; both are decisions rather than fixes. Rotation is worth
+building. The `resolution` machinery probably is not, and deleting it would take
+`keyman.config.ts` from 267 lines to around 220.
+
+**5 — §5.2, §5.3 and §5.4** are one rewrite of `README.md`. It is the only
+document that ships, and it currently describes two thirds of the menu and none
+of the command line.
+
+**6 — the rest.** §2.2 (drop the passphrase prompt, let `ssh-keygen` ask), §2.3
+(`age-keygen -y`), §2.4 (a shred operation), §1.6 through §1.9, §3.2, §3.4,
+§3.5, and the §4 one-liners.

packages/keyman/docs/PLAN.md

@@ -0,0 +1,452 @@
+# keyman remediation plan
+
+Turns [`AUDIT.md`](./AUDIT.md) into sequenced work. Each phase is one commit,
+independently landable, gate-green on its own. Section references (§) are to
+`AUDIT.md`.
+
+Ordering is by *blast radius per unit of risk*, not by severity: the error
+boundary comes first because it makes every later phase's failure mode legible,
+and the config threading comes late because it is the only phase that rewrites
+existing test assertions.
+
+## Status
+
+**All ten phases have landed**, one commit each, on the `keyman-remediation`
+branch. Three deviations worth knowing about:
+
+- **Phase 6's literal instruction was impossible.** "Move the `mkdirSync` after
+  `age` succeeds" cannot be done — `age -o` will not create its output directory.
+  The goal (no leftover directory) is met by cleaning up on failure instead, which
+  also removes a truncated `.age` the plan had not accounted for.
+- **§1.8 is half done, deliberately**, exactly as the plan asked: the skipped-key
+  report is in, the layout change that would make non-`id_*` keys manageable is
+  not. See `AUDIT.md` §1.8.
+- **Rollout has not been done.** No version bump, no tag, nothing published — the
+  cut points below are still proposals, and pushing this branch to `main` would
+  publish a snapshot, so that is the user's call to make.
+
+Both open decisions were resolved the way the plan recommended: the `resolution`
+machinery was deleted, and rotation was built.
+
+## Verified before planning
+
+Four things the fixes depend on, checked by running them rather than assumed —
+two of them changed the prescription:
+
+| Check | Result | Consequence |
+| --- | --- | --- |
+| `ssh-keygen` with `-N` omitted | Prompts `Enter passphrase … (empty for no passphrase)` **and** confirms | §2.2 fix works: omit `-N`, inherit stdio, keyman never holds the passphrase |
+| `ssh-keygen -y -f <encrypted key>` | **Prompts for the passphrase** | §1.6 fix cannot be a silent spawn — needs `stdio: 'inherit'` and a skip path |
+| `@inquirer/core` from keyman | `ERR_MODULE_NOT_FOUND` — transitive via `inquirer`, not a direct dep | Detect `ExitPromptError` by `error.name`, never by import |
+| `z.strictObject` in zod 4.4.3 | Available; reports `unrecognized_keys` with a `keys` array | §3.5 has a hard-failure option, though the plan prefers a warning |
+
+## What is not a breaking change
+
+Per §4.3, `src/index.ts` exports only `keyman`, `loadConfig`,
+`resolveConfigPaths` and the update module. `encryptKeys`, `decryptKeys`,
+`generateKey`, `listKeys`, `copyKey` and `extractAgePublicKey` are **not** on the
+public surface, so every signature change below is internal. Phases 2–6 are not
+semver-breaking.
+
+The one user-visible behaviour change is Phase 5 — see [Migration](#migration).
+
+## Gate discipline
+
+`lint:ci` → `typecheck` → `test:coverage` runs on `pre-push` and in CI. Two
+standing constraints:
+
+- **Every phase lands its tests with its fix.** No phase may leave a red gate,
+  so there is no "write the failing tests first" commit.
+- **`keyman.cli.ts` is excluded from coverage** (`vitest.config.ts:18`). Per
+  `CLAUDE.md`, *adding logic to those files means moving it somewhere covered* —
+  which is why Phase 1 extracts argument parsing into a new module rather than
+  growing `cli.ts`.
+
+Per-phase verification is `pnpm --filter @bitsquare/keyman run test`; the full
+gate (`pnpm run lint:ci && pnpm run typecheck && pnpm run test:coverage`) before
+each push.
+
+---
+
+## Phase 1 — Error boundary, `--help`, argument validation
+
+Closes §3.1, §3.2, and the second half of §1.2 (the crash dump).
+
+First because it is pure addition, touches no operation module, and converts
+every latent throw in phases 2–6 from a stack dump into a line of text. The
+`ExitPromptError` half is independently worth shipping: today **Ctrl-C at any
+prompt** produces a crash dump.
+
+**New file `src/keyman.args.ts`** (covered by the gate, unlike `cli.ts`):
+
+- `parseArgs(argv: string[]): ParsedArgs` — supports `--flag value` *and*
+  `--flag=value`, rejects a flag consumed as another flag's value, rejects
+  unknown flags, and validates `--channel` against `'latest' | 'next' | 'main'`
+  so §3.2's false "Could not reach <registry>" cannot happen.
+- `helpText(): string` — flags, both subcommands, and the four `KEYMAN_*`
+  variables. This is the text Phase 9 keeps in step with the README.
+
+**`src/keyman.cli.ts`** stays wiring: dispatch on the parse result, and
+
+```ts
+try {
+  await keyman();
+} catch (error) {
+  if ((error as { name?: string }).name === 'ExitPromptError') {
+    console.log('\n👋 Goodbye!\n');
+    process.exit(0);
+  }
+  console.error(`❌ ${error instanceof Error ? error.message : error}`);
+  process.exit(1);
+}
+```
+
+`error.name`, not `instanceof` — `@inquirer/core` is not a direct dependency and
+does not resolve from this package.
+
+**Tests** — new `tests/args.test.ts`: each rejection, both flag forms, the
+channel whitelist, and that `helpText()` names every flag `parseArgs` accepts
+(so the two cannot drift).
+
+**Done when** `keyman --help` prints usage and exits 0 without loading config or
+prompting; `keyman --bogus` errors; Ctrl-C prints Goodbye and exits 0.
+
+---
+
+## Phase 2 — Guards and error handling in encrypt/decrypt
+
+Closes §1.2 (first half), §1.5, and §1.10's `statSync`.
+
+- `encrypt.ts:13,16` and `decrypt.ts:8` — `existsSync` guard, falling through to
+  the "⚠️ No …" message each function already has but cannot currently reach.
+- `main.ts:40-41` — create `keysDir` alongside `vaultRoot` and `tmpDir`. Use
+  `{recursive: true, mode: 0o700}` now, so Phase 4 does not have to revisit it.
+- Wrap the `age` spawns in both functions. An `ENOENT` on the binary gets its own
+  message ("`age` was not found on PATH") — it is the one hard external
+  requirement and currently the least legible failure.
+- `list.ts:80` — `readdirSync(dir, {withFileTypes: true})` instead of
+  `statSync` per entry, which also drops N stat calls and fixes the broken-symlink
+  throw.
+- Delete the debug logging while in these files: `encrypt.ts:18-19` and
+  `decrypt.ts:10` (§1.10). That also closes `DOCS-AUDIT.md` §6.4's open bullet.
+
+**Tests** — the cases the current suite structurally cannot have, because every
+`beforeEach` pre-creates the directories: encrypt with no `~/.ssh`, encrypt with
+no tmp, decrypt with no `<vault>/keys`, each asserting the warning and no throw.
+Plus `list` with a dangling symlink in the keys directory.
+
+**Note on coverage.** `encrypt.ts` and `decrypt.ts` are at 100 % lines and
+branches *today*. The number will not move; the tests are the point.
+
+**Done when** a first run against an empty vault can reach every menu entry and
+return to the menu.
+
+---
+
+## Phase 3 — Resolve the age recipient once, and derive it properly
+
+Closes §1.3 and §2.3, and makes `CLAUDE.md`'s `age-keygen` claim true (§5.5).
+
+Two changes that belong together because both are about the recipient:
+
+1. **`utils.ts` — derive, don't scrape.** `extractAgePublicKey` currently regexes
+   `# public key:` out of a comment (`utils.ts:16`) and trusts it. Replace with
+   `age-keygen -y <keyPath>`, which derives the public key *from the private key*
+   and cannot disagree with it. Keep the comment parse as a fallback for when
+   `age-keygen` is absent, behind a warning that the recipient is unverified.
+   The function becomes `async`.
+2. **`main.ts:73,80` — delete both `!`.** Resolve the recipient once before the
+   `switch`, and treat `null` as recoverable: print the remedy
+   (`age-keygen -o <keyPath>`) and `break` back to the menu. This is the whole of
+   §1.3 — the type already said null was possible.
+
+Sequencing matters inside the phase: fix the call site first. Without it, a
+missing key file still reaches `age -r null`, and the generate path still leaves
+a **plaintext private key in `tmpDir`** after telling the user the operation
+failed.
+
+**Tests** — `utils.test.ts` gains the `age-keygen -y` path with `execa` mocked,
+the fallback-with-warning path, and the both-unavailable path. `main.test.ts`
+gains: missing recipient → neither `generateKey` nor `encryptKeys` is called, a
+remedy is printed, and the menu loop continues.
+
+**Done when** `keyman` against a vault with no `age.key` reaches the menu,
+refuses generate and encrypt with a remedy, and still offers list and decrypt.
+
+---
+
+## Phase 4 — Decrypt: stop overwriting, stop the 0644 window
+
+Closes §1.4 and §2.1. The highest-value phase — §1.4 is the only finding that
+destroys data the user did not ask to touch.
+
+- **Collision check before any decryption.** Both output paths, both modes.
+  Prompt per collision, defaulting to skip; `~/.ssh` deserves the friction more
+  than `vault/tmp` does, but the check is the same code.
+- **Replace the shell-outs** (`decrypt.ts:49-50`) with `fs.copyFileSync` and
+  `fs.chmodSync`. Three spawns per key become one, it works on Windows, and it
+  removes a `cp` that overwrites unconditionally.
+- **Close the permission window.** Verified: `age -o` creates the file `0644`
+  and `mkdirSync` creates `vault/tmp` as `0755`, so a plaintext key is
+  world-readable for the duration of two process spawns — and stays `0644` if the
+  `chmod` fails. `fs.chmodSync` immediately after `age` resolves; `mode: 0o700`
+  on the directory (already done in Phase 2); create `~/.ssh` `0700` if absent.
+
+**Test rework — the fiddliest in the plan.** `decrypt.test.ts` asserts on the
+mocked spawns: `argsOf('cp')` (`:98,111`) and `argsOf('chmod')` (`:99,112`) both
+disappear, and `execa` is mocked with a bare `mockResolvedValue` (`:57`) that
+writes no output file. Once `copyFileSync` is real it needs a real file, so the
+mock must write to its `-o` argument the way `encrypt.test.ts:51-54` already
+does. Assert the on-disk result and mode instead of the argv — a better test
+than the one it replaces, since it checks the outcome rather than the mechanism.
+`execa` call counts also change (`:123`: six spawns → two).
+
+**Done when** decrypting onto an existing key requires a confirmation, and the
+decrypted key is never observable at anything but `0600`.
+
+---
+
+## Phase 5 — Thread `keysDir` and `tmpDir` through encrypt and decrypt
+
+Closes §1.1 and the `DOCS-AUDIT.md` entry in §5.1.
+
+Mechanical, but it is the one phase that rewrites assertions that pass today, so
+it stays its own commit with nothing else in it.
+
+- `encryptKeys(sshDir, keysDir, tmpDir, pubkey)` — drop `vaultDir`, delete the
+  hardcoded `path.join(vaultDir, 'keys')` (`encrypt.ts:38`).
+- `decryptKeys(sshDir, keysDir, tmpDir, ageKey)` — drop `vaultDir`, delete the
+  hardcoded joins at `decrypt.ts:7,39,43`.
+- `main.ts:76,84` — pass `paths.keysDir` and `paths.tmpDir`. Neither function has
+  any remaining use for `vaultRoot`, so the parameter goes rather than becoming a
+  second source of truth.
+
+**Assertions to change** — all four, named so the diff is reviewable:
+
+| Location | Today | After |
+| --- | --- | --- |
+| `main.test.ts:164-175` | "encrypts keys into the vault root", asserts `paths.vaultRoot` | asserts `paths.keysDir`, `paths.tmpDir` |
+| `main.test.ts:177-187` | asserts `paths.vaultRoot` | asserts `paths.keysDir`, `paths.tmpDir` |
+| `encrypt.test.ts:95,115,128-129` | `path.join(vaultDir, 'keys', …)` | `path.join(keysDir, …)` |
+| `decrypt.test.ts:53,89` | `keyDir = path.join(vaultDir, 'keys')` | `keysDir` passed in directly |
+
+**New test, the one that would have caught this:** a config with
+`keysDir: 'encrypted'` and `tmpDir: 'plain'`, encrypt a key, then list it, and
+assert the listing shows it in `[Vault]`. That round trip fails today and is the
+regression worth owning.
+
+**Also in this commit:** move the `DOCS-AUDIT.md:826-827` bullet out of *checked
+and accurate* and point it at this finding. It was verified against
+`keyman.encrypt.ts` — the file that ignores the config — which is precisely how
+§1.1 stayed invisible.
+
+---
+
+## Phase 6 — Generate: passphrase off argv, and `.pub` recovery
+
+Closes §2.2, §1.6, and §1.10's leftover-directory bullet.
+
+**Passphrase (§2.2).** Verified: omitting `-N` makes `ssh-keygen` prompt *and*
+confirm. So delete keyman's own password prompt (`generate.ts:26-33`), omit `-N`,
+and spawn with `stdio: 'inherit'`. The passphrase never enters keyman's memory
+and never reaches argv — strictly better than routing it more carefully, and it
+deletes code. `generate.test.ts:78-87` loses `-N`/`'pw'` from the expected argv
+and the password-prompt case goes away.
+
+**Missing `.pub` (§1.6).** The selection list is built from private keys only, so
+an orphan private key is offered and `copyFileSync` throws *after* `age` has
+written the `.age` file — leaving a vault entry with no public key and killing
+the rest of the batch. Fix in two parts:
+
+- Derive it with `ssh-keygen -y -f <key>` when the sibling is absent. **Verified
+  that this prompts for a passphrase on an encrypted key**, so it needs
+  `stdio: 'inherit'` and a clean skip when the user cannot or will not supply it
+  — not a silent spawn whose stdout is captured.
+- Wrap the loop body in `encrypt.ts:36-48` per key, so one bad key costs one key.
+  Report the failures at the end rather than dying at the first.
+
+**Leftover directory.** `generate.ts:65` creates `<keysDir>/<name>/` before
+`age` runs at `:68`. Move the `mkdirSync` after `age` succeeds.
+
+---
+
+## Phase 7 — Config: warn on typos, decide on the dead machinery
+
+Closes §3.5, §3.4, and asks for a decision on §3.3.
+
+**Typos (§3.5).** Verified: `{"vaultroot": "…"}` is silently stripped by
+`z.object`. Warn per file rather than failing — diff `Object.keys(rawConfig)`
+against the schema keys plus `resolution` inside the existing per-file loop
+(`config.ts:210-227`), where the filename is in hand. That names the offending
+file, which `z.strictObject` cannot do from the merged result, and it preserves
+the module's documented posture of degrading to defaults rather than throwing.
+(`z.strictObject` is available in zod 4.4.3 and reports `unrecognized_keys` with
+a `keys` array, if a hard failure is preferred later.)
+
+**`getConfigPaths` (§3.4).** Add it to the `--print-config` JSON as
+`configFiles`. The function is currently exercised only by its own test, and
+`--print-config` currently cannot answer *which files were read* — that exists
+only as unstructured stderr from `loadConfig`. One change fixes both.
+
+**Decision needed — the `resolution` machinery (§3.3).** Roughly 45 lines
+(`config.ts:23-30,115-157`) that cannot affect a valid config, because every
+schema property is a `string` and both strategies return `childValue` for
+primitives. `config.test.ts:212` "honours an explicit override strategy" passes
+either way.
+
+- **Recommended: delete it**, along with the doc comment at `:186-194` that
+  advertises it. `keyman.config.ts` goes from 267 lines to roughly 220, and the
+  config file stops documenting a knob that does nothing.
+- **Alternative: keep it** as the shape a future array- or object-valued option
+  would need — but then say so in a comment, because today it reads as
+  functional, and make `config.test.ts:212` assert something that distinguishes
+  the two strategies (which requires a non-string property to exist first).
+
+Deleting is the smaller lie. It also diverges from nopy, where the machinery
+*is* load-bearing — worth a line in `CLAUDE.md` so the divergence reads as
+deliberate.
+
+---
+
+## Phase 8 — Portability and the gaps that make keys invisible
+
+Closes §1.7, §1.8, §1.9, §2.4. Independent of each other; split if any grows.
+
+- **Clipboard (§1.9).** `pbcopy` / `wl-copy` / `xclip` / `clip.exe` by platform,
+  falling back to printing the key to stdout so the operation is never a dead
+  end. Delete the comment at `copy.ts:46-48` that admits the shortcut.
+- **Home directory (§1.7).** `os.userInfo()` for the current user; for a named
+  user, look the home directory up rather than assuming `/home/<user>` — wrong on
+  the one platform the tool currently supports. Check `existsSync` and say so,
+  instead of feeding a nonexistent path into a `readdir`.
+  `main.test.ts:198-204` changes.
+- **Non-`id_*` keys (§1.8).** Relax the filters (`copy.ts:9`, `encrypt.ts:14,17`,
+  `list.ts:23,51`) to *any* private key with a recognisable header, or at minimum
+  print a count of the keys that were skipped and why. Today a key named
+  `deploy_ed25519` is simply absent from the menu — and pre-existing keys are the
+  population a key manager is adopted to take over. `decrypt.ts:9` reconstructs
+  `id_${dir}` from the folder name, so the vault layout has the assumption baked
+  in; relaxing discovery means storing the real filename per key, which is the
+  largest single item in this plan. **Size it before committing to it** — a
+  skipped-key count is a tenth of the work and closes most of the surprise.
+- **Plaintext hygiene (§2.4).** A "🧹 Clear decrypted keys" menu entry, and write
+  a `.gitignore` next to the vault on first run covering `age.key` and `tmp/` —
+  which `README.md:25-26` currently tells the user to do by hand. This is the
+  cheapest guard against the exact failure the tool exists to prevent.
+
+---
+
+## Phase 9 — Documentation
+
+Closes §5.2, §5.3, §5.4, §5.5. Last, so it documents what the code now does.
+
+- **`README.md` — the only shipped document** (`package.json:37-41` ships `dist`,
+  `README.md`, `LICENSE`). Currently describes four of six menu entries, invents
+  key rotation, and mentions none of `self-update`, `--print-config`,
+  `--version`, `--help`, or the four `KEYMAN_*` variables. `README.PUBLISH.md`
+  has all of it and never reaches a reader on the registry. Reuse Phase 1's
+  `helpText()` as the source for the CLI section so the two cannot drift.
+- **`README.md:46-86`** — the configuration and vault-layout sections, now that
+  Phase 5 makes `keysDir`/`tmpDir` real, plus the migration note below.
+- **`README.md:11`** — drop "Support for key rotation" unless Phase 10 lands
+  first.
+- **`README.md:33`** — stop telling the user to shell out to `ssh-keygen`; the
+  Generate operation exists.
+- **`CLAUDE.md`** — `age-keygen` becomes true in Phase 3; note that `cp`/`chmod`
+  are gone (Phase 4) and record the `resolution` divergence from nopy (Phase 7).
+- **`AUDIT.md`** — mark findings closed, keeping their text as the record, the way
+  `DOCS-AUDIT.md` does.
+
+---
+
+## Phase 10 — Key rotation (decision required)
+
+§3.6. `README.md:11` has advertised it since before this audit;
+`grep -rn "rotat" packages/keyman/src/` returns nothing.
+
+Unlike the rest of this plan it is a feature, not a repair, and it is the one
+item that could reasonably be dropped instead. **Recommendation: build it** —
+rotation is the operation that makes a key vault worth having, and the pieces all
+exist by Phase 6 (generate under a new name, encrypt, keep the old key until the
+replacement is deployed, then shred). Sketch:
+
+1. Pick an existing vault key.
+2. Generate a replacement into `tmpDir` under a versioned name.
+3. Encrypt it alongside the current one — never replacing it.
+4. Report both public keys, so the new one can be deployed before the old one
+   goes.
+5. A separate "retire" step that removes the superseded key once the user
+   confirms.
+
+Steps 3 and 4 are the whole value: a rotation that atomically replaces the key is
+a rotation that locks you out of the host you were rotating for. If this is
+deferred, delete the README claim in Phase 9 instead.
+
+---
+
+## Migration
+
+Phase 5 is the only user-visible change. Anyone with a custom `keysDir` or
+`tmpDir` currently has a **split vault** — `generate` and `list` on the
+configured directory, `encrypt` and `decrypt` on `<vaultRoot>/keys` and
+`<vaultRoot>/tmp`. After Phase 5 all five agree on the configured directory, so
+anything written by `encrypt` before the upgrade needs moving:
+
+```sh
+mv <vaultRoot>/keys/* <vaultRoot>/<keysDir>/
+```
+
+Nobody on the defaults is affected, since the two halves coincide there. The
+README gets this as a note, and it is worth a line in the release notes for
+whichever version carries Phase 5.
+
+## Rollout
+
+Per `CLAUDE.md`: bump `packages/keyman/package.json`, land on `main`, then tag
+`keyman-v<version>`.
+
+- **Snapshots come free.** Every push to `main` publishes
+  `<version>-main.<run>.g<sha>` to Gitea under the `main` dist-tag, so each phase
+  is installable for testing without a release. `pnpm run try:snapshot` installs
+  one into a throwaway project.
+- **Suggested cut points.** After Phase 4 as `0.6.0` — error boundary, guards,
+  recipient handling and the data-loss fix, which is the set worth getting to
+  users first. After Phase 9 as `0.7.0`, carrying the Phase 5 migration note.
+- **keyman can reach npmjs.** It has no `workspace:*` dependencies (`execa`,
+  `inquirer`, `semver`, `zod` only), so `scripts/linked-deps.mjs` has nothing to
+  block on — unlike `nopy`, which `CLAUDE.md` records as gated behind
+  `nopy-cubes` shipping. keyman has never been published to npmjs; `0.6.0` could
+  be the first, and versions being `0.x.y` rather than `1.0.0-alphaN` means the
+  `latest` dist-tag will now actually move.
+- **`pnpm publish`, never `npm publish`** — no `workspace:` ranges here, but the
+  rule is repo-wide and `scripts/verify-pack.mjs` enforces it in both workflows.
+
+## Sequencing at a glance
+
+```
+1  cli boundary + --help + args      §3.1 §3.2 §1.2(half)   isolated, pure addition
+2  guards in encrypt/decrypt/list    §1.2 §1.5 §1.10         new tests only
+3  age recipient, once and derived   §1.3 §2.3 §5.5          signature → async
+4  decrypt: no clobber, no 0644      §1.4 §2.1               reworks decrypt.test.ts
+   ── cut 0.6.0 ──
+5  thread keysDir/tmpDir             §1.1 §5.1               rewrites 4 assertions
+6  generate: -N gone, .pub recovery  §2.2 §1.6 §1.10         reworks generate.test.ts
+7  config: warn, prune, print        §3.5 §3.4 §3.3*         *decision
+8  portability + hygiene             §1.7 §1.8 §1.9 §2.4     §1.8 needs sizing
+9  documentation                     §5.2 §5.3 §5.4 §5.5     README is the shipped one
+   ── cut 0.7.0 ──
+10 rotation                          §3.6*                   *decision: build or delete
+```
+
+Phases 1–6 are repairs and want to land in order. 7 and 8 are independent of each
+other and of 5–6. 9 depends on everything before it. 10 is optional and gates
+one line of Phase 9.
+
+## Open decisions
+
+Neither blocks Phase 1. Both change scope where they land:
+
+1. **§3.3, at Phase 7** — delete the inert `resolution` machinery (recommended,
+   −45 lines) or keep it as future shape with a comment saying so.
+2. **§3.6, at Phase 10** — build rotation (recommended) or delete the README
+   claim in Phase 9.

packages/keyman/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitsquare/keyman",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A system to simplify ssh key management",
   "keywords": [
     "ssh",

packages/keyman/src/index.ts

@@ -1,31 +1,15 @@
-#!/usr/bin/env node
-export { loadConfig, resolveConfigPaths } from './keyman.config.js';
+/**
+ * The library surface — `exports["."]`, imported and never executed, which is why
+ * it no longer carries the bin's shebang (AUDIT §4.1). The bin is
+ * `dist/keyman.cli.js`.
+ *
+ * Deliberately narrow: config resolution, the update machinery, and `keyman()` to
+ * run the menu. The operation modules stay internal — every one of them prompts,
+ * prints and spawns, so there is nothing to do with a single one except reproduce
+ * the menu around it (§4.3). The update module is re-exported wholesale rather
+ * than by name list, because the list had drifted to half of it (§4.4).
+ */
+export type { KeymanConfig, KeymanConfigFile } from './keyman.config.js';
+export { describeConfig, loadConfig, resolveConfigPaths } from './keyman.config.js';
 export * from './keyman.main.js';
-export type {
-  Channel,
-  CommandRunner,
-  PackageManager,
-  SelfUpdateResult,
-  UpdateCache,
-  UpdateStatus,
-} from './keyman.update.js';
-export {
-  buildSelfUpdateCommand,
-  channelForVersion,
-  checkForUpdate,
-  DEFAULT_CHECK_INTERVAL_MS,
-  detectPackageManager,
-  fetchChannelVersion,
-  formatCommand,
-  formatUpdateNotice,
-  getUpdateCachePath,
-  isUpdateCheckDisabled,
-  NPMJS_REGISTRY,
-  normalizeRegistry,
-  PACKAGE_NAME,
-  readUpdateCache,
-  resolveRegistry,
-  selfUpdate,
-  updateNotice,
-  writeUpdateCache,
-} from './keyman.update.js';
+export * from './keyman.update.js';

packages/keyman/src/keyman.args.ts

@@ -0,0 +1,204 @@
+/**
+ * Argv parsing for the keyman CLI.
+ *
+ * Separate from `keyman.cli.ts` because that file is excluded from coverage: it
+ * is meant to be wiring, and *which flag takes a value* and *which channel names
+ * are legal* are behaviour. The old inline `indexOf` reader accepted
+ * `--channel --force`, which reached the registry as a dist-tag that cannot
+ * exist and reported an unreachable registry instead of a bad flag.
+ */
+
+import type { Channel } from './keyman.update.js';
+
+/** The channels `--channel` accepts, in the order the error message lists them */
+export const CHANNELS: readonly Channel[] = ['latest', 'next', 'main'];
+
+/** Flags that consume the next token, or the suffix of a `--flag=value` */
+const VALUE_FLAGS: readonly string[] = ['--channel', '--registry'];
+
+/** Flags that stand alone, short aliases included */
+const BOOLEAN_FLAGS: readonly string[] = [
+  '--help',
+  '-h',
+  '--version',
+  '-V',
+  '--print-config',
+  '--self-update',
+  '--dry-run',
+  '-n',
+  '--force',
+  '-f',
+];
+
+/**
+ * Flags that only mean anything to `self-update`. Named so that using one on its
+ * own is an error rather than a silent no-op.
+ */
+const SELF_UPDATE_ONLY: readonly string[] = [
+  '--channel',
+  '--registry',
+  '--dry-run',
+  '-n',
+  '--force',
+  '-f',
+];
+
+/** Every flag the parser accepts — the list `helpText()` is checked against */
+export const KNOWN_FLAGS: readonly string[] = [...BOOLEAN_FLAGS, ...VALUE_FLAGS];
+
+const SUBCOMMANDS: readonly string[] = ['self-update', 'upgrade'];
+
+export type ParsedArgs =
+  | { command: 'help' }
+  | { command: 'version' }
+  | { command: 'print-config' }
+  | { command: 'interactive' }
+  | {
+      command: 'self-update';
+      dryRun: boolean;
+      force: boolean;
+      channel?: Channel;
+      registry?: string;
+    };
+
+/**
+ * A mistake in the invocation. Carries a message meant for the user, so the CLI
+ * can print one line instead of a stack trace.
+ */
+export class UsageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
+
+/**
+ * Turns argv (already sliced past `node` and the script) into one command.
+ *
+ * @throws {UsageError} on an unknown flag or command, a value flag with no
+ *   value, a boolean flag given one, or a channel that is not a real channel
+ */
+export function parseArgs(argv: string[]): ParsedArgs {
+  // Before tokenising, so that help answers a line it could not otherwise parse.
+  // Exact tokens only: `--registry=--help` is a (bad) registry, not a request.
+  if (argv.some((token) => token === '--help' || token === '-h')) {
+    return { command: 'help' };
+  }
+
+  const flags = new Set<string>();
+  const values = new Map<string, string>();
+  let subcommand: string | undefined;
+
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index];
+
+    if (!token.startsWith('-')) {
+      if (!SUBCOMMANDS.includes(token)) {
+        throw new UsageError(`Unknown command: ${token}`);
+      }
+      if (subcommand) {
+        throw new UsageError(`Unexpected argument: ${token}`);
+      }
+      subcommand = token;
+      continue;
+    }
+
+    const equals = token.indexOf('=');
+    const name = equals === -1 ? token : token.slice(0, equals);
+
+    if (VALUE_FLAGS.includes(name)) {
+      // A value that looks like a flag is a forgotten value, not a value —
+      // unless it was written as --flag=-value and therefore meant.
+      const inline = equals === -1 ? undefined : token.slice(equals + 1);
+      const value = inline ?? argv[++index];
+      if (!value || (inline === undefined && value.startsWith('-'))) {
+        throw new UsageError(`${name} expects a value`);
+      }
+      values.set(name, value);
+      continue;
+    }
+
+    if (!BOOLEAN_FLAGS.includes(name)) {
+      throw new UsageError(`Unknown flag: ${name}`);
+    }
+    if (equals !== -1) {
+      throw new UsageError(`${name} does not take a value`);
+    }
+    flags.add(name);
+  }
+
+  const given = (...names: string[]) => names.some((name) => flags.has(name));
+
+  const isSelfUpdate = subcommand !== undefined || flags.has('--self-update');
+
+  if (!isSelfUpdate) {
+    const stray = [...values.keys(), ...flags].find((name) => SELF_UPDATE_ONLY.includes(name));
+    if (stray) {
+      throw new UsageError(`${stray} is only valid with \`keyman self-update\``);
+    }
+  }
+
+  if (flags.has('--print-config')) {
+    return { command: 'print-config' };
+  }
+
+  if (given('--version', '-V')) {
+    return { command: 'version' };
+  }
+
+  if (isSelfUpdate) {
+    const channel = values.get('--channel');
+    if (channel !== undefined && !CHANNELS.includes(channel as Channel)) {
+      throw new UsageError(`Unknown channel: ${channel} (expected ${CHANNELS.join(', ')})`);
+    }
+    return {
+      command: 'self-update',
+      dryRun: given('--dry-run', '-n'),
+      force: given('--force', '-f'),
+      channel: channel as Channel | undefined,
+      registry: values.get('--registry'),
+    };
+  }
+
+  return { command: 'interactive' };
+}
+
+/**
+ * What `--help` prints.
+ *
+ * Hand-written rather than generated from the flag tables, so that adding a flag
+ * to the parser without documenting it fails a test instead of shipping.
+ */
+export function helpText(): string {
+  return `keyman — SSH key management and an age-encrypted key vault
+
+Usage
+  keyman                             start the interactive menu
+  keyman self-update                 update keyman itself (alias: upgrade)
+
+Flags
+  -h, --help                         print this help and exit
+  -V, --version                      print the version and exit
+      --print-config                 print the resolved paths and the config files
+                                     they came from, as JSON, and exit
+      --self-update                  same as the self-update subcommand
+
+Flags for self-update
+      --channel <${CHANNELS.join('|')}>   channel to update from
+                                     (default: derived from the running version)
+      --registry <url>               registry to query instead of the configured one
+  -n, --dry-run                      print the install command without running it
+  -f, --force                        reinstall even when already up to date
+
+Environment
+  VAULT_ROOT                         overrides vaultRoot from .keymanrc.json
+  KEYMAN_REGISTRY                    registry for the update check and self-update
+  KEYMAN_REGISTRY_TOKEN              bearer token for a private registry
+  KEYMAN_NO_UPDATE_CHECK             set to 1 to skip the once-a-day update check
+                                     (also skipped whenever CI is set)
+  KEYMAN_PACKAGE_MANAGER             npm | pnpm | yarn | bun for the install command
+
+Configuration is read from .keymanrc.json, merged from the current directory
+upwards and then from ~/.keymanrc.json.
+`;
+}

packages/keyman/src/keyman.clear.ts

@@ -0,0 +1,86 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import inquirer from 'inquirer';
+import { scanPrivateKeys } from './keyman.keys.js';
+
+/**
+ * Writes a `.gitignore` beside the vault, once.
+ *
+ * The README told the user to do this by hand. A vault holds the age identity and,
+ * whenever anything has been decrypted, plaintext private keys — committing it is
+ * the exact failure the tool exists to prevent, and it is one file to prevent it.
+ *
+ * Never overwritten: an existing file may say more than this one does.
+ */
+export function writeVaultGitignore(vaultRoot: string, tmpDir: string, keyPath: string) {
+  const gitignore = path.join(vaultRoot, '.gitignore');
+  if (fs.existsSync(gitignore)) {
+    return;
+  }
+
+  // Both are configurable and may be absolute, so either can sit outside the vault.
+  // A .gitignore cannot speak about a path above itself, and claiming to would be
+  // worse than saying nothing.
+  const inside = (target: string) => {
+    const relative = path.relative(vaultRoot, target);
+    return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : null;
+  };
+
+  const tmp = inside(tmpDir);
+  const key = inside(keyPath);
+
+  const lines = [
+    '# Written by keyman. The encrypted keys under the keys directory are safe to',
+    '# commit; nothing else here is.',
+    ...(key ? [key, `${key}.pub`] : []),
+    ...(tmp ? [`${tmp}/`] : []),
+    '',
+  ];
+
+  fs.writeFileSync(gitignore, lines.join('\n'), { mode: 0o600 });
+}
+
+/**
+ * Deletes the decrypted keys in the vault's tmp directory.
+ *
+ * The counterpart to `decrypt`, which had none: a plaintext private key stayed
+ * there until someone remembered it, and "someone remembered" is not a security
+ * control. Only the key pairs are removed — anything else in the directory is not
+ * keyman's to delete.
+ */
+export async function clearDecryptedKeys(tmpDir: string) {
+  const { keys } = scanPrivateKeys(tmpDir);
+
+  if (keys.length === 0) {
+    console.log(`✅ Nothing decrypted in ${tmpDir}.`);
+    return;
+  }
+
+  console.log(`\n🔓 Decrypted keys in ${tmpDir}:`);
+  for (const key of keys) {
+    console.log(`   ${key}`);
+  }
+
+  const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+    {
+      type: 'confirm',
+      name: 'confirmed',
+      message: `Delete ${keys.length === 1 ? 'this key' : `these ${keys.length} keys`}?`,
+      // A key that exists only here — generated and not yet deployed — is gone for
+      // good, so this is not a question to answer by pressing return.
+      default: false,
+    },
+  ]);
+
+  if (!confirmed) {
+    console.log('⏭️  Nothing was deleted.');
+    return;
+  }
+
+  for (const key of keys) {
+    for (const file of [key, `${key}.pub`]) {
+      fs.rmSync(path.join(tmpDir, file), { force: true });
+    }
+    console.log(`🧹 Removed ${key}`);
+  }
+}

packages/keyman/src/keyman.cli.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 import { createRequire } from 'node:module';
-import { loadConfig, resolveConfigPaths } from './keyman.config.js';
+import { helpText, type ParsedArgs, parseArgs, UsageError } from './keyman.args.js';
+import { describeConfig } from './keyman.config.js';
 import { keyman } from './keyman.main.js';
-import type { Channel } from './keyman.update.js';
 import { formatCommand, selfUpdate, updateNotice } from './keyman.update.js';
 
 const { version, buildInfo } = createRequire(import.meta.url)('../package.json') as {
@@ -18,35 +18,40 @@ const { version, buildInfo } = createRequire(import.meta.url)('../package.json')
  */
 const versionLabel = buildInfo?.commit ? `${version} (${buildInfo.commit})` : version;
 
-const args = process.argv.slice(2);
-
-/** Reads `--flag value` out of argv, or undefined when the flag is absent */
-function flagValue(name: string): string | undefined {
-  const index = args.indexOf(name);
-  return index === -1 ? undefined : args[index + 1];
+let parsed: ParsedArgs;
+try {
+  parsed = parseArgs(process.argv.slice(2));
+} catch (error) {
+  if (!(error instanceof UsageError)) throw error;
+  console.error(`❌ ${error.message}`);
+  console.error('Run `keyman --help` for usage.');
+  process.exit(2);
 }
 
-if (args.includes('--print-config')) {
-  const config = loadConfig();
-  const paths = resolveConfigPaths(config);
-  console.log(JSON.stringify(paths));
+if (parsed.command === 'help') {
+  console.log(helpText());
   process.exit(0);
 }
 
-if (args.includes('--version') || args.includes('-V')) {
+if (parsed.command === 'print-config') {
+  console.log(JSON.stringify(describeConfig()));
+  process.exit(0);
+}
+
+if (parsed.command === 'version') {
   console.log(versionLabel);
   process.exit(0);
 }
 
-if (args[0] === 'self-update' || args[0] === 'upgrade' || args.includes('--self-update')) {
-  const dryRun = args.includes('--dry-run') || args.includes('-n');
+if (parsed.command === 'self-update') {
+  const { dryRun } = parsed;
   try {
     const result = await selfUpdate({
       currentVersion: version,
-      channel: flagValue('--channel') as Channel | undefined,
-      registry: flagValue('--registry'),
+      channel: parsed.channel,
+      registry: parsed.registry,
       dryRun,
-      force: args.includes('--force') || args.includes('-f'),
+      force: parsed.force,
     });
 
     const { status } = result;
@@ -79,4 +84,15 @@ if (notice) {
   console.error(`\n${notice}\n`);
 }
 
-keyman();
+try {
+  await keyman();
+} catch (error) {
+  // Ctrl-C at any inquirer prompt lands here. `name`, not `instanceof`:
+  // @inquirer/core is transitive and does not resolve from this package.
+  if ((error as { name?: string }).name === 'ExitPromptError') {
+    console.log('\n👋 Goodbye!\n');
+    process.exit(0);
+  }
+  console.error(`❌ ${error instanceof Error ? error.message : error}`);
+  process.exit(1);
+}

packages/keyman/src/keyman.clipboard.ts

@@ -0,0 +1,56 @@
+import { runTool, ToolNotFoundError } from './keyman.utils.js';
+
+/** A clipboard command and the argv it wants, in the order they are tried. */
+interface ClipboardTool {
+  binary: string;
+  args: string[];
+}
+
+/**
+ * The clipboard commands worth trying on a platform, best first.
+ *
+ * Linux is a list rather than a choice because there is no single answer:
+ * `wl-copy` under Wayland, `xclip`/`xsel` under X11, and a user may have any
+ * subset installed. Trying them in order and moving on from an absent one costs a
+ * failed spawn and removes the need to detect the session type.
+ */
+export function clipboardTools(platform: string = process.platform): ClipboardTool[] {
+  switch (platform) {
+    case 'darwin':
+      return [{ binary: 'pbcopy', args: [] }];
+    case 'win32':
+      return [{ binary: 'clip', args: [] }];
+    default:
+      return [
+        { binary: 'wl-copy', args: [] },
+        { binary: 'xclip', args: ['-selection', 'clipboard'] },
+        { binary: 'xsel', args: ['--clipboard', '--input'] },
+      ];
+  }
+}
+
+/**
+ * Puts `text` on the system clipboard.
+ *
+ * keyman used to spawn `pbcopy` unconditionally, with a comment saying so — which
+ * made "copy public key" a dead end on every platform but macOS, and reported it
+ * as a clipboard failure rather than as a missing tool.
+ *
+ * @returns the command that took it, or null if none was available
+ */
+export async function copyToClipboard(text: string, platform?: string): Promise<string | null> {
+  for (const { binary, args } of clipboardTools(platform)) {
+    try {
+      await runTool(binary, args, { input: text });
+      return binary;
+    } catch (error) {
+      // Only an absent tool is worth trying the next candidate for. One that ran
+      // and refused has an opinion, and repeating the paste elsewhere is not it.
+      if (!(error instanceof ToolNotFoundError)) {
+        throw error;
+      }
+    }
+  }
+
+  return null;
+}

packages/keyman/src/keyman.config.ts

@@ -15,27 +15,11 @@ const KeymanConfigSchema = z.object({
 
 export type KeymanConfig = z.infer<typeof KeymanConfigSchema>;
 
-/**
- * Resolution strategy for merging config properties
- * - 'merge': Arrays are concatenated, objects are deep merged (default)
- * - 'override': Child value completely replaces parent value
- */
-export type ResolutionStrategy = 'merge' | 'override';
+/** Raw config file structure */
+export type KeymanConfigFile = Partial<KeymanConfig>;
 
-/**
- * Resolution configuration for customizing merge behavior
- */
-export type KeymanResolutionConfig = {
-  [K in keyof KeymanConfig]?: ResolutionStrategy;
-};
-
-/**
- * Raw config file structure (includes resolution)
- */
-export interface KeymanConfigFile extends Partial<KeymanConfig> {
-  /** Customize merge behavior for specific properties */
-  resolution?: KeymanResolutionConfig;
-}
+/** Every key a config file may set. */
+const KNOWN_KEYS = Object.keys(KeymanConfigSchema.shape) as (keyof KeymanConfig)[];
 
 /**
  * Default configuration values
@@ -110,71 +94,36 @@ function findConfigFiles(startDir: string): string[] {
 }
 
 /**
- * Deep merges two values based on resolution strategy
+ * Reports keys a config file sets that keyman does not read.
+ *
+ * `z.object` strips them silently, so `{"vaultroot": "…"}` used to be
+ * indistinguishable from an empty file — the vault quietly stayed at the default
+ * and nothing said why. Warned rather than fatal, which is this module's posture
+ * throughout, and warned *here* because this is the only place the filename is in
+ * hand: `z.strictObject` on the merged result cannot name the file that said it.
  */
-function mergeValue(
-  parentValue: unknown,
-  childValue: unknown,
-  strategy: ResolutionStrategy
-): unknown {
-  // Override strategy: child replaces parent completely
-  if (strategy === 'override') {
-    return childValue;
-  }
+function warnUnknownKeys(configFile: KeymanConfigFile, configPath: string): void {
+  const unknown = Object.keys(configFile).filter(
+    (key) => !KNOWN_KEYS.includes(key as keyof KeymanConfig)
+  );
 
-  // Merge strategy (default)
-  if (Array.isArray(parentValue) && Array.isArray(childValue)) {
-    // Concatenate arrays, remove duplicates for primitives
-    const combined = [...parentValue, ...childValue];
-    if (combined.every((v) => typeof v !== 'object')) {
-      return [...new Set(combined)];
+  if (unknown.length > 0) {
+    console.warn(
+      `⚠️  ${configPath}: ignoring unknown ${unknown.length === 1 ? 'key' : 'keys'} ${unknown.join(', ')}. Known keys: ${KNOWN_KEYS.join(', ')}.`
+    );
   }
-    return combined;
-  }
-
-  if (
-    typeof parentValue === 'object' &&
-    parentValue !== null &&
-    typeof childValue === 'object' &&
-    childValue !== null &&
-    !Array.isArray(parentValue) &&
-    !Array.isArray(childValue)
-  ) {
-    // Deep merge objects
-    const result: Record<string, unknown> = { ...parentValue };
-    for (const [key, value] of Object.entries(childValue)) {
-      if (key in result) {
-        result[key] = mergeValue(result[key], value, 'merge');
-      } else {
-        result[key] = value;
-      }
-    }
-    return result;
-  }
-
-  // Primitives: child overrides parent
-  return childValue;
 }
 
 /**
- * Merges a child config into a parent config
+ * Merges a child config into a parent config.
+ *
+ * Every property is a string, so a child simply wins. keyman deliberately has
+ * none of nopy's `resolution` machinery: deep-merge and array-concatenation
+ * strategies are meaningful there because its config holds arrays and objects,
+ * and here they would be 45 lines that cannot change an outcome.
  */
 function mergeConfigs(parent: KeymanConfig, childFile: KeymanConfigFile): KeymanConfig {
-  const resolution = childFile.resolution || {};
-  const result: Record<string, unknown> = { ...parent };
-
-  for (const [key, value] of Object.entries(childFile)) {
-    if (key === 'resolution') continue; // Skip resolution property itself
-
-    const strategy = resolution[key as keyof KeymanConfig] || 'merge';
-    if (key in result) {
-      result[key] = mergeValue(result[key], value, strategy);
-    } else {
-      result[key] = value;
-    }
-  }
-
-  return result as unknown as KeymanConfig;
+  return { ...parent, ...childFile };
 }
 
 /**
@@ -183,16 +132,6 @@ function mergeConfigs(parent: KeymanConfig, childFile: KeymanConfigFile): Keyman
  * Searches for `.keymanrc.json` by traversing upwards from cwd to root.
  * Multiple config files are merged, with child configs overriding parent configs.
  *
- * Use the `resolution` property to customize merge behavior:
- * ```json
- * {
- *   "vaultRoot": "../vault",
- *   "resolution": {
- *     "vaultRoot": "override"
- *   }
- * }
- * ```
- *
  * @returns Validated keyman configuration
  */
 export function loadConfig(): KeymanConfig {
@@ -211,6 +150,7 @@ export function loadConfig(): KeymanConfig {
     try {
       const content = fs.readFileSync(configPath, 'utf-8');
       const rawConfig = JSON.parse(content) as KeymanConfigFile;
+      warnUnknownKeys(rawConfig, configPath);
       // Resolve path properties relative to the config file's directory
       const configDir = path.dirname(configPath);
       const resolvedConfig = resolvePathsRelativeToConfig(rawConfig, configDir);
@@ -265,3 +205,17 @@ export function resolveConfigPaths(config: KeymanConfig) {
 export function getConfigPaths(): string[] {
   return findConfigFiles(process.cwd());
 }
+
+/**
+ * What `--print-config` prints.
+ *
+ * `configFiles` is the question the flag could not answer before: which files
+ * were read, in the order they were merged. It existed only as unstructured
+ * stderr from `loadConfig`, which is exactly the wrong place for it — the JSON is
+ * the machine-readable half.
+ */
+export function describeConfig(): ReturnType<typeof resolveConfigPaths> & {
+  configFiles: string[];
+} {
+  return { ...resolveConfigPaths(loadConfig()), configFiles: getConfigPaths() };
+}

packages/keyman/src/keyman.copy.ts

@@ -1,18 +1,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execa } from 'execa';
 import inquirer from 'inquirer';
+import { copyToClipboard } from './keyman.clipboard.js';
+import { reportSkippedKeys, scanPrivateKeys } from './keyman.keys.js';
 
 export async function copyKey(sshDir: string, tmpDir: string) {
-  const getKeys = (dir: string) => {
-    if (!fs.existsSync(dir)) return [];
-    return fs.readdirSync(dir).filter((key) => key.startsWith('id_') && !key.endsWith('.pub'));
-  };
+  const ssh = scanPrivateKeys(sshDir);
+  const tmp = scanPrivateKeys(tmpDir);
 
-  const sshKeys = getKeys(sshDir);
-  const tmpKeys = getKeys(tmpDir);
+  const keys = [...new Set([...ssh.keys, ...tmp.keys])];
 
-  const keys = [...new Set([...sshKeys, ...tmpKeys])];
+  // Before the empty check: "no SSH keys found" next to four unmanageable ones is
+  // the case the report exists for.
+  reportSkippedKeys(ssh.skipped, sshDir);
+  reportSkippedKeys(tmp.skipped, tmpDir);
 
   if (keys.length === 0) {
     console.log('⚠️ No SSH keys found.');
@@ -40,19 +41,23 @@ export async function copyKey(sshDir: string, tmpDir: string) {
     return;
   }
 
-  try {
   const pubKeyContent = fs.readFileSync(pubKeyPath, 'utf-8').trim();
 
-    // Detect OS and use appropriate clipboard command
-    // Since the environment is Darwin, we prioritize pbcopy, but we can add others for completeness or use a simple check.
-    // For this specific request on Darwin:
-    const proc = execa('pbcopy');
-    proc.stdin?.write(pubKeyContent);
-    proc.stdin?.end();
-    await proc;
+  try {
+    const tool = await copyToClipboard(pubKeyContent);
 
-    console.log(`✅ Public key for ${selectedKey} copied to clipboard!`);
+    if (tool) {
+      console.log(`✅ Public key for ${selectedKey} copied to clipboard via ${tool}!`);
+      return;
+    }
+    console.warn('⚠️  No clipboard command found.');
   } catch (error) {
-    console.error(`❌ Failed to copy to clipboard: ${error}`);
+    console.error(
+      `❌ Failed to copy to clipboard: ${error instanceof Error ? error.message : error}`
+    );
   }
+
+  // Printing it is the point of the operation; the clipboard was only the
+  // convenient way to deliver it. A public key is not a secret.
+  console.log(`\n${pubKeyContent}\n`);
 }

packages/keyman/src/keyman.decrypt.ts

@@ -1,15 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execa } from 'execa';
 import inquirer from 'inquirer';
+import { runTool } from './keyman.utils.js';
+import { listVaultKeys } from './keyman.vault.js';
 
-export async function decryptKeys(sshDir: string, vaultDir: string, ageKey: string) {
-  const keyDir = path.join(vaultDir, 'keys');
-  const vaultKeys = fs.readdirSync(keyDir).filter((key) => {
-    const keyfile = path.join(keyDir, key, `id_${key}.age`);
-    console.log(keyfile);
-    return fs.existsSync(keyfile);
-  });
+/** The two decryption targets. Values, so the label can name the real directory. */
+const LOCAL_MODE = 'local';
+
+interface DecryptPlan {
+  key: string;
+  encryptedKey: string;
+  publicKey: string;
+  privateKeyOut: string;
+  publicKeyOut: string;
+}
+
+export async function decryptKeys(sshDir: string, keysDir: string, tmpDir: string, ageKey: string) {
+  const vaultKeys = listVaultKeys(keysDir);
 
   if (vaultKeys.length === 0) {
     console.log('⚠️ No encrypted keys found.');
@@ -27,27 +34,75 @@ export async function decryptKeys(sshDir: string, vaultDir: string, ageKey: stri
       type: 'list',
       name: 'decryptMode',
       message: 'Choose decryption location:',
-      choices: ['Local (vault/tmp)', 'SSH (~/.ssh)'],
+      // Named after the directories actually in use, which are configurable.
+      choices: [
+        { name: `Local (${tmpDir})`, value: LOCAL_MODE },
+        { name: `SSH (${sshDir})`, value: 'ssh' },
+      ],
     },
   ]);
 
-  for (const key of selectedKeys) {
-    const encryptedKey = path.join(keyDir, key, `id_${key}.age`);
-    const publicKey = path.join(keyDir, key, `id_${key}.pub`);
-    const privateKeyOut =
-      decryptMode === 'Local (vault/tmp)'
-        ? path.join(vaultDir, 'tmp', `id_${key}`)
-        : path.join(sshDir, `id_${key}`);
-    const publicKeyOut =
-      decryptMode === 'Local (vault/tmp)'
-        ? path.join(vaultDir, 'tmp', `id_${key}.pub`)
-        : path.join(sshDir, `id_${key}.pub`);
+  const outDir = decryptMode === LOCAL_MODE ? tmpDir : sshDir;
 
-    // Decrypt key
-    await execa('age', ['-d', '-i', ageKey, '-o', privateKeyOut, encryptedKey]);
+  const plans: DecryptPlan[] = selectedKeys.map((key: string) => ({
+    key,
+    encryptedKey: path.join(keysDir, key, `id_${key}.age`),
+    publicKey: path.join(keysDir, key, `id_${key}.pub`),
+    privateKeyOut: path.join(outDir, `id_${key}`),
+    publicKeyOut: path.join(outDir, `id_${key}.pub`),
+  }));
 
-    await execa('cp', [publicKey, publicKeyOut]);
-    await execa('chmod', ['600', privateKeyOut]);
-    console.log(`✅ Decrypted: ${privateKeyOut}`);
+  // Every collision is settled before anything is written. `age -d -o` and the
+  // old `cp` both overwrote silently, so decrypting a vault key on top of a
+  // newer working key destroyed it with no prompt and no copy — and the user is
+  // answering these questions about files that still exist.
+  const approved: DecryptPlan[] = [];
+  for (const plan of plans) {
+    const existing = [plan.privateKeyOut, plan.publicKeyOut].filter((file) => fs.existsSync(file));
+
+    if (existing.length === 0) {
+      approved.push(plan);
+      continue;
+    }
+
+    const { overwrite } = await inquirer.prompt<{ overwrite: boolean }>([
+      {
+        type: 'confirm',
+        name: 'overwrite',
+        message: `${existing.join(', ')} already present. Overwrite?`,
+        default: false,
+      },
+    ]);
+
+    if (overwrite) {
+      approved.push(plan);
+    } else {
+      console.log(`⏭️  Skipped ${plan.key} — kept what was already there.`);
+    }
+  }
+
+  if (approved.length === 0) {
+    return;
+  }
+
+  // 0700: ~/.ssh may not exist yet, and it is about to hold a private key.
+  fs.mkdirSync(outDir, { recursive: true, mode: 0o700 });
+
+  for (const plan of approved) {
+    await runTool('age', ['-d', '-i', ageKey, '-o', plan.privateKeyOut, plan.encryptedKey]);
+    // Immediately, and in-process: age creates its output 0644 regardless of
+    // umask, so this used to be a world-readable private key for the length of
+    // two process spawns — and stayed 0644 whenever the chmod itself failed.
+    fs.chmodSync(plan.privateKeyOut, 0o600);
+
+    if (fs.existsSync(plan.publicKey)) {
+      fs.copyFileSync(plan.publicKey, plan.publicKeyOut);
+    } else {
+      console.log(
+        `⚠️  ${plan.key} has no public key in the vault; only the private key was written.`
+      );
+    }
+
+    console.log(`✅ Decrypted: ${plan.privateKeyOut}`);
   }
 }

packages/keyman/src/keyman.encrypt.ts

@@ -1,24 +1,19 @@
-import fs from 'node:fs';
 import path from 'node:path';
-import { execa } from 'execa';
 import inquirer from 'inquirer';
+import { reportSkippedKeys, scanPrivateKeys } from './keyman.keys.js';
+import { ToolNotFoundError } from './keyman.utils.js';
+import { storeInVault } from './keyman.vault.js';
 
-export async function encryptKeys(
-  sshDir: string,
-  vaultDir: string,
-  tmpDir: string,
-  pubkey: string
-) {
-  const sshKeys = fs
-    .readdirSync(sshDir)
-    .filter((key) => key.startsWith('id_') && !key.endsWith('.pub'));
-  const tmpKeys = fs
-    .readdirSync(tmpDir)
-    .filter((key) => key.startsWith('id_') && !key.endsWith('.pub'));
-  console.log(tmpKeys);
-  console.log(sshKeys);
+export async function encryptKeys(sshDir: string, keysDir: string, tmpDir: string, pubkey: string) {
+  const ssh = scanPrivateKeys(sshDir);
+  const tmp = scanPrivateKeys(tmpDir);
+  const sshKeys = ssh.keys;
+  const tmpKeys = tmp.keys;
   const keys = [...new Set([...sshKeys, ...tmpKeys])];
 
+  reportSkippedKeys(ssh.skipped, sshDir);
+  reportSkippedKeys(tmp.skipped, tmpDir);
+
   if (keys.length === 0) {
     console.log('⚠️ No private SSH keys found to encrypt.');
     return;
@@ -33,17 +28,30 @@ export async function encryptKeys(
     },
   ]);
 
+  const failed: string[] = [];
+
   for (const key of selectedKeys) {
     const keyPath = path.join(tmpKeys.includes(key) ? tmpDir : sshDir, key);
-    const vaultPath = path.join(vaultDir, 'keys', key.replace('id_', ''));
-    fs.mkdirSync(vaultPath, { recursive: true });
 
-    // Encrypt key using `age`
-    await execa('age', ['-r', pubkey, '-o', path.join(vaultPath, `${key}.age`), keyPath]);
-
-    // Copy public key and create README
-    fs.copyFileSync(`${keyPath}.pub`, path.join(vaultPath, `${key}.pub`));
-
-    console.log(`🔒 Encrypted and stored: ${vaultPath}/${key}`);
+    try {
+      await storeInVault(keyPath, keysDir, pubkey);
+    } catch (error) {
+      // One bad key costs one key. Selecting ten and losing the last nine to an
+      // unreadable first one was the old behaviour, and nothing afterwards said
+      // which of the ten had made it into the vault.
+      if (error instanceof ToolNotFoundError) {
+        // Not a per-key problem: age is missing for all of them, so nine more
+        // identical failures would tell the user nothing new.
+        throw error;
+      }
+      failed.push(key);
+      console.error(`❌ ${key}: ${error instanceof Error ? error.message : error}`);
+    }
+  }
+
+  if (failed.length > 0) {
+    console.log(
+      `\n⚠️  ${failed.length} of ${selectedKeys.length} selected keys were not stored: ${failed.join(', ')}`
+    );
   }
 }

packages/keyman/src/keyman.generate.ts

@@ -1,9 +1,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { execa } from 'execa';
 import inquirer from 'inquirer';
+import { runTool } from './keyman.utils.js';
+import { storeInVault } from './keyman.vault.js';
 
-export async function generateKey(tmpDir: string, keysDir: string, pubkey: string) {
+export interface KeyOptions {
+  algorithm: string;
+  identity: string;
+}
+
+/**
+ * How a new key pair should be made: the algorithm and the comment.
+ *
+ * Shared with rotation, which asks the same two questions about a key whose name
+ * it works out for itself.
+ *
+ * @param defaultIdentity offered as the answer — the comment of the key being
+ *   replaced, when there is one
+ */
+export async function promptKeyOptions(defaultIdentity?: string): Promise<KeyOptions> {
   const { algorithm } = await inquirer.prompt<{ algorithm: string }>([
     {
       type: 'list',
@@ -14,6 +29,57 @@ export async function generateKey(tmpDir: string, keysDir: string, pubkey: strin
     },
   ]);
 
+  const { identity } = await inquirer.prompt<{ identity: string }>([
+    {
+      type: 'input',
+      name: 'identity',
+      message: 'Enter key identity (comment):',
+      default: defaultIdentity,
+    },
+  ]);
+
+  return { algorithm, identity };
+}
+
+/**
+ * Generates one key pair at `keyPath`, reporting a failure rather than throwing.
+ *
+ * @returns whether the key pair was written
+ */
+export async function createKeyPair(
+  keyPath: string,
+  algorithm: string,
+  identity: string
+): Promise<boolean> {
+  const fileName = path.basename(keyPath);
+
+  if (fs.existsSync(keyPath)) {
+    console.error(`❌ Error: Key file ${fileName} already exists in ${path.dirname(keyPath)}`);
+    return false;
+  }
+
+  const args = ['-t', algorithm, '-f', keyPath, '-C', identity];
+  if (algorithm === 'rsa') {
+    args.push('-b', '4096');
+  }
+
+  try {
+    console.log(`Generating ${algorithm} key pair...`);
+    // No `-N`, and stdio inherited: ssh-keygen asks for the passphrase itself and
+    // confirms it. keyman used to prompt for it and pass it as `-N <value>`,
+    // which put the passphrase in this process's argv — readable by any user on
+    // the box via `ps` for as long as the spawn lived, and in keyman's memory
+    // before that. A passphrase keyman never learns cannot be leaked by keyman.
+    await runTool('ssh-keygen', args, { stdio: 'inherit' });
+    console.log(`✅ Key generated: ${keyPath}`);
+    return true;
+  } catch (error) {
+    console.error(`❌ Error generating key: ${error instanceof Error ? error.message : error}`);
+    return false;
+  }
+}
+
+export async function generateKey(tmpDir: string, keysDir: string, pubkey: string) {
   const { keyName } = await inquirer.prompt<{ keyName: string }>([
     {
       type: 'input',
@@ -23,55 +89,21 @@ export async function generateKey(tmpDir: string, keysDir: string, pubkey: strin
     },
   ]);
 
-  const { password } = await inquirer.prompt<{ password: string }>([
-    {
-      type: 'password',
-      name: 'password',
-      message: 'Enter passphrase (leave empty for no passphrase):',
-      mask: '*',
-    },
-  ]);
-
-  const { identity } = await inquirer.prompt<{ identity: string }>([
-    {
-      type: 'input',
-      name: 'identity',
-      message: 'Enter key identity (comment):',
-    },
-  ]);
+  const { algorithm, identity } = await promptKeyOptions();
 
   const fileName = keyName.startsWith('id_') ? keyName : `id_${keyName}`;
   const keyPath = path.join(tmpDir, fileName);
 
-  if (fs.existsSync(keyPath)) {
-    console.error(`❌ Error: Key file ${fileName} already exists in ${tmpDir}`);
+  if (!(await createKeyPair(keyPath, algorithm, identity))) {
     return;
   }
 
   try {
-    console.log(`Generating ${algorithm} key pair...`);
-    const args = ['-t', algorithm, '-f', keyPath, '-N', password, '-C', identity];
-
-    if (algorithm === 'rsa') {
-      args.push('-b', '4096');
-    }
-
-    await execa('ssh-keygen', args);
-    console.log(`✅ Key generated: ${keyPath}`);
-
-    // Encrypt the key
-    const folderName = fileName.replace('id_', '');
-    const vaultPath = path.join(keysDir, folderName);
-    fs.mkdirSync(vaultPath, { recursive: true });
-
-    // Encrypt key using `age`
-    await execa('age', ['-r', pubkey, '-o', path.join(vaultPath, `${fileName}.age`), keyPath]);
-
-    // Copy public key
-    fs.copyFileSync(`${keyPath}.pub`, path.join(vaultPath, `${fileName}.pub`));
-
-    console.log(`🔒 Encrypted and stored: ${vaultPath}`);
+    await storeInVault(keyPath, keysDir, pubkey);
   } catch (error) {
-    console.error(`❌ Error generating/encrypting key: ${error}`);
+    // The private key is still in tmpDir, so this is recoverable by encrypting it
+    // — which is why it does not read as having lost the key.
+    console.error(`❌ Error encrypting key: ${error instanceof Error ? error.message : error}`);
+    console.error(`   ${keyPath} was generated; encrypt it once the problem is fixed.`);
   }
 }

packages/keyman/src/keyman.home.ts

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** The answer the USER prompt defaults to: whoever is running keyman. */
+export const CURRENT_USER = '@current';
+
+/**
+ * The home directory of the current user.
+ *
+ * `HOME` first, because a user who set it meant it, and `os.userInfo()` after,
+ * which reads the passwd database and so still answers when `HOME` is unset — a
+ * cron job, a `su` without `-l`, a container entrypoint. `process.env.HOME || ''`
+ * treated all of those as a fatal error.
+ */
+function currentHome(): string | null {
+  if (process.env.HOME) {
+    return process.env.HOME;
+  }
+  try {
+    return os.userInfo().homedir || null;
+  } catch {
+    // uv_os_get_passwd can fail outright when there is no passwd entry for the uid.
+    return null;
+  }
+}
+
+/**
+ * Where another user's home directory is, without asking the system.
+ *
+ * The sibling of the current user's home comes first because it is right wherever
+ * homes live together, whatever that directory is called — `/Users` on macOS,
+ * `/home` on Linux, `/export/home` on the odd installation. keyman previously
+ * hardcoded `/home/<user>`, which is wrong on the one platform it was written on.
+ *
+ * The candidates are checked for existence rather than guessed at, so a wrong one
+ * produces an error naming what was tried instead of an empty `readdir`.
+ */
+function candidateHomes(user: string): string[] {
+  const home = currentHome();
+  const siblings = home ? [path.join(path.dirname(home), user)] : [];
+
+  return [...new Set([...siblings, path.join('/home', user), path.join('/Users', user)])];
+}
+
+/**
+ * Resolves the home directory for an answer to the USER prompt.
+ *
+ * @returns the directory, or null with the reason already reported
+ */
+export function resolveHomeDir(user: string): string | null {
+  if (user === CURRENT_USER) {
+    const home = currentHome();
+    if (!home) {
+      console.error('❌ Unable to determine HOME directory for the current user.');
+      return null;
+    }
+    return home;
+  }
+
+  const candidates = candidateHomes(user);
+  const found = candidates.find((candidate) => fs.existsSync(candidate));
+
+  if (!found) {
+    console.error(`❌ No home directory found for ${user}. Tried: ${candidates.join(', ')}`);
+    return null;
+  }
+
+  return found;
+}

packages/keyman/src/keyman.keys.ts

@@ -0,0 +1,93 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Present in the first line of every private key format ssh-keygen writes. */
+const PRIVATE_KEY_MARKER = 'PRIVATE KEY-----';
+
+/** Enough for `-----BEGIN OPENSSH PRIVATE KEY-----`, and no more of a key than needed. */
+const HEADER_BYTES = 64;
+
+/**
+ * Whether a file opens with a private key header.
+ *
+ * A bounded read of the first line, not the file: classifying a key is no reason
+ * to pull one into memory.
+ */
+function looksLikePrivateKey(file: string): boolean {
+  let handle: number | undefined;
+  try {
+    handle = fs.openSync(file, 'r');
+    const buffer = Buffer.alloc(HEADER_BYTES);
+    const read = fs.readSync(handle, buffer, 0, HEADER_BYTES, 0);
+    return buffer.subarray(0, read).toString('latin1').includes(PRIVATE_KEY_MARKER);
+  } catch {
+    // A directory, a socket, a file with no read permission — none of them a key.
+    return false;
+  } finally {
+    if (handle !== undefined) {
+      fs.closeSync(handle);
+    }
+  }
+}
+
+export interface PrivateKeyScan {
+  /** Keys keyman can manage: named `id_*`, which is what the vault layout assumes. */
+  keys: string[];
+  /** Private keys it found and cannot manage, because they are named otherwise. */
+  skipped: string[];
+}
+
+/**
+ * The private keys in a directory that may not exist.
+ *
+ * A first run has neither `~/.ssh` nor the tmp directory, and an unguarded readdir
+ * there threw before the "nothing to encrypt" message could be reached.
+ *
+ * `skipped` exists because the `id_*` filter is silent: a key named
+ * `deploy_ed25519` was simply absent from every menu, and pre-existing keys are
+ * the population a key manager gets adopted to take over. Reporting them is not
+ * managing them — see `reportSkippedKeys`.
+ */
+export function scanPrivateKeys(dir: string): PrivateKeyScan {
+  if (!fs.existsSync(dir)) {
+    return { keys: [], skipped: [] };
+  }
+
+  const keys: string[] = [];
+  const skipped: string[] = [];
+
+  // Sorted, because readdir order is the filesystem's business and a menu's order
+  // should not depend on it.
+  for (const file of fs.readdirSync(dir).sort()) {
+    if (file.endsWith('.pub')) {
+      continue;
+    }
+    if (file.startsWith('id_')) {
+      // Not content-checked: what the menus offered has not changed.
+      keys.push(file);
+    } else if (looksLikePrivateKey(path.join(dir, file))) {
+      skipped.push(file);
+    }
+  }
+
+  return { keys, skipped };
+}
+
+/**
+ * Says which private keys were found and left alone, and why.
+ *
+ * The vault stores a key as `<name minus id_>/id_<name>.age` and `decrypt`
+ * reconstructs the filename from the directory, so the prefix is baked into the
+ * on-disk layout — which is why this is a report and not a fix.
+ */
+export function reportSkippedKeys(skipped: string[], dir: string): void {
+  if (skipped.length === 0) {
+    return;
+  }
+
+  const plural = skipped.length === 1 ? 'key' : 'keys';
+  console.log(
+    `ℹ️  Skipped ${skipped.length} private ${plural} in ${dir} not named id_*: ${skipped.join(', ')}`
+  );
+  console.log('   The vault layout requires the id_ prefix; rename to manage them here.');
+}

packages/keyman/src/keyman.list.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { reportSkippedKeys, scanPrivateKeys } from './keyman.keys.js';
 
 interface KeyInfo {
   name: string;
@@ -76,9 +77,12 @@ export async function listKeys(sshDir: string, vaultDir: string, tmpDir: string)
 
   // Scan vault directory
   if (fs.existsSync(vaultDir)) {
+    // throwIfNoEntry keeps a dangling symlink from aborting the whole listing;
+    // the stat still follows a symlink to a real directory, which withFileTypes
+    // would have reported as a link and skipped.
     const vaultDirs = fs.readdirSync(vaultDir).filter((dir) => {
-      const stat = fs.statSync(path.join(vaultDir, dir));
-      return stat.isDirectory();
+      const stat = fs.statSync(path.join(vaultDir, dir), { throwIfNoEntry: false });
+      return stat?.isDirectory() ?? false;
     });
 
     for (const dir of vaultDirs) {
@@ -102,6 +106,12 @@ export async function listKeys(sshDir: string, vaultDir: string, tmpDir: string)
     }
   }
 
+  // A listing that omits keys without saying so is the worst place for the id_
+  // assumption to be invisible: this is the screen a user checks it against.
+  for (const dir of [sshDir, tmpDir]) {
+    reportSkippedKeys(scanPrivateKeys(dir).skipped, dir);
+  }
+
   // Display results
   if (keyMap.size === 0) {
     console.log('⚠️  No SSH keys found.\n');

packages/keyman/src/keyman.main.ts

@@ -1,12 +1,15 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import inquirer from 'inquirer';
+import { clearDecryptedKeys, writeVaultGitignore } from './keyman.clear.js';
 import { loadConfig, resolveConfigPaths } from './keyman.config.js';
 import { copyKey } from './keyman.copy.js';
 import { decryptKeys } from './keyman.decrypt.js';
 import { encryptKeys } from './keyman.encrypt.js';
 import { generateKey } from './keyman.generate.js';
+import { CURRENT_USER, resolveHomeDir } from './keyman.home.js';
 import { listKeys } from './keyman.list.js';
+import { retireKey, rotateKey } from './keyman.rotate.js';
 import { extractAgePublicKey } from './keyman.utils.js';
 
 // 🔹 Main function to resolve paths and manage flow
@@ -25,20 +28,36 @@ export async function keyman() {
     {
       type: 'input',
       name: 'user',
-      message: 'Specify USER (default: @current):',
-      default: '@current',
+      message: `Specify USER (default: ${CURRENT_USER}):`,
+      default: CURRENT_USER,
     },
   ]);
 
-  const homeDir = user === '@current' ? process.env.HOME || '' : `/home/${user}`;
+  const homeDir = resolveHomeDir(user);
   if (!homeDir) {
-    console.error('Error: Unable to determine HOME directory.');
     process.exit(1);
   }
 
   const sshDir = path.join(homeDir, '.ssh');
-  fs.mkdirSync(paths.vaultRoot, { recursive: true });
-  fs.mkdirSync(paths.tmpDir, { recursive: true });
+  // 0700 because the vault holds the age identity and, in tmp, plaintext private
+  // keys. keysDir is created here too: decrypt used to read it before anything
+  // created it.
+  for (const dir of [paths.vaultRoot, paths.keysDir, paths.tmpDir]) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeVaultGitignore(paths.vaultRoot, paths.tmpDir, paths.keyPath);
+
+  // Resolved on demand, because only generate and encrypt need a recipient, and
+  // remembered once it succeeds. Retried while it has not: creating the identity
+  // mid-session should not mean restarting.
+  let recipient: string | null = null;
+  const ageRecipient = async () => {
+    recipient ??= await extractAgePublicKey(paths.keyPath);
+    if (!recipient) {
+      console.error(`   Create one with: age-keygen -o ${paths.keyPath}`);
+    }
+    return recipient;
+  };
 
   // Main loop - keep showing menu until user quits
   let running = true;
@@ -57,6 +76,9 @@ export async function keyman() {
           { name: '🆕 Generate key', value: 'generate' },
           { name: '🔒 Encrypt keys', value: 'encrypt' },
           { name: '🔓 Decrypt keys', value: 'decrypt' },
+          { name: '🔄 Rotate key', value: 'rotate' },
+          { name: '🗑️  Retire key', value: 'retire' },
+          { name: '🧹 Clear decrypted keys', value: 'clear' },
           { name: '❌ Quit', value: 'quit' },
         ],
       },
@@ -69,19 +91,35 @@ export async function keyman() {
       case 'copy':
         await copyKey(sshDir, paths.tmpDir);
         break;
-      case 'generate':
-        await generateKey(paths.tmpDir, paths.keysDir, extractAgePublicKey(paths.keyPath)!);
+      case 'generate': {
+        const pubkey = await ageRecipient();
+        if (pubkey) {
+          await generateKey(paths.tmpDir, paths.keysDir, pubkey);
+        }
         break;
-      case 'encrypt':
-        await encryptKeys(
-          sshDir,
-          paths.vaultRoot,
-          paths.tmpDir,
-          extractAgePublicKey(paths.keyPath)!
-        );
+      }
+      case 'encrypt': {
+        const pubkey = await ageRecipient();
+        if (pubkey) {
+          await encryptKeys(sshDir, paths.keysDir, paths.tmpDir, pubkey);
+        }
         break;
+      }
       case 'decrypt':
-        await decryptKeys(sshDir, paths.vaultRoot, paths.keyPath);
+        await decryptKeys(sshDir, paths.keysDir, paths.tmpDir, paths.keyPath);
+        break;
+      case 'rotate': {
+        const pubkey = await ageRecipient();
+        if (pubkey) {
+          await rotateKey(sshDir, paths.keysDir, paths.tmpDir, pubkey);
+        }
+        break;
+      }
+      case 'retire':
+        await retireKey(sshDir, paths.keysDir, paths.tmpDir);
+        break;
+      case 'clear':
+        await clearDecryptedKeys(paths.tmpDir);
         break;
       case 'quit':
         console.log('\n👋 Goodbye!\n');

packages/keyman/src/keyman.rotate.ts

@@ -0,0 +1,256 @@
+/**
+ * Key rotation, in two halves that are deliberately not one operation.
+ *
+ * `rotateKey` only ever *adds*: a replacement key generated under the next name in
+ * the series and encrypted alongside the key it replaces. `retireKey` is what
+ * finally deletes the old one, once the user says the replacement is deployed.
+ *
+ * Rotating in place — overwriting the key, or deleting it in the same breath —
+ * locks you out of the host you were rotating for: the replacement is not on it
+ * yet, and the only copy of the key that is has gone. The gap between the two
+ * operations is where you add the new public key and check that it works.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import inquirer from 'inquirer';
+import { createKeyPair, promptKeyOptions } from './keyman.generate.js';
+import { scanPrivateKeys } from './keyman.keys.js';
+import { listVaultKeys, storeInVault } from './keyman.vault.js';
+
+interface Series {
+  base: string;
+  version: number;
+}
+
+/** `prod-2` → base `prod`, version 2. An unsuffixed name is version 1. */
+function series(key: string): Series {
+  const match = /^(.+)-(\d+)$/.exec(key);
+  return match ? { base: match[1], version: Number(match[2]) } : { base: key, version: 1 };
+}
+
+/**
+ * The name for the replacement of `key`: same series, next version up.
+ *
+ * The name has to change. The vault layout derives the directory from it, so a
+ * replacement also called `prod` *is* the `prod` entry — and holding both at once
+ * is the whole point of rotating this way.
+ *
+ * @param taken every name already in use, in the vault or as a plaintext key, so
+ *   the suffix skips a version that was made by hand
+ */
+export function nextRotationName(key: string, taken: string[]): string {
+  const { base, version } = series(key);
+  let next = version + 1;
+
+  for (const name of taken) {
+    const other = series(name);
+    if (other.base === base && other.version >= next) {
+      next = other.version + 1;
+    }
+  }
+
+  return `${base}-${next}`;
+}
+
+/** The latest key in the vault that comes after `key` in its series, if any. */
+export function supersededBy(key: string, vaultKeys: string[]): string | null {
+  const { base, version } = series(key);
+  let successor: string | null = null;
+  let highest = version;
+
+  for (const name of vaultKeys) {
+    const other = series(name);
+    if (other.base === base && other.version > highest) {
+      successor = name;
+      highest = other.version;
+    }
+  }
+
+  return successor;
+}
+
+/** The bare names of the plaintext keys in `dir`, matching the vault's naming. */
+function plaintextNames(dir: string): string[] {
+  return scanPrivateKeys(dir).keys.map((file) => file.replace(/^id_/, ''));
+}
+
+/** The comment on a stored public key, so a rotation can carry it over. */
+function storedComment(publicKeyFile: string): string | undefined {
+  if (!fs.existsSync(publicKeyFile)) {
+    return undefined;
+  }
+
+  // `<type> <base64> <comment...>`: the comment is optional and may hold spaces.
+  const comment = fs.readFileSync(publicKeyFile, 'utf-8').trim().split(/\s+/).slice(2).join(' ');
+  return comment || undefined;
+}
+
+/** Prints a public key for copying, or says why it cannot. */
+function showPublicKey(label: string, file: string): void {
+  console.log(`\n   ${label}`);
+  if (fs.existsSync(file)) {
+    console.log(`   ${fs.readFileSync(file, 'utf-8').trim()}`);
+  } else {
+    console.log(`   (none stored at ${file})`);
+  }
+}
+
+function isFile(file: string): boolean {
+  return fs.statSync(file, { throwIfNoEntry: false })?.isFile() ?? false;
+}
+
+/**
+ * Generates a replacement for a vault key and stores it beside the original.
+ *
+ * Nothing is deleted or overwritten; `retireKey` is the other half.
+ */
+export async function rotateKey(
+  sshDir: string,
+  keysDir: string,
+  tmpDir: string,
+  pubkey: string
+): Promise<void> {
+  const vaultKeys = listVaultKeys(keysDir);
+
+  if (vaultKeys.length === 0) {
+    console.log('⚠️  No encrypted keys to rotate — generate or encrypt one first.');
+    return;
+  }
+
+  const { key } = await inquirer.prompt<{ key: string }>([
+    {
+      type: 'list',
+      name: 'key',
+      message: 'Select the key to rotate:',
+      choices: vaultKeys,
+    },
+  ]);
+
+  const currentPublicKey = path.join(keysDir, key, `id_${key}.pub`);
+  const { algorithm, identity } = await promptKeyOptions(storedComment(currentPublicKey));
+
+  const replacement = nextRotationName(key, [
+    ...vaultKeys,
+    ...plaintextNames(tmpDir),
+    ...plaintextNames(sshDir),
+  ]);
+  const keyPath = path.join(tmpDir, `id_${replacement}`);
+
+  console.log(`\n🔄 Rotating ${key} → ${replacement}`);
+  console.log(`   ${key} is left exactly as it is, in the vault and on its hosts.\n`);
+
+  fs.mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+  if (!(await createKeyPair(keyPath, algorithm, identity))) {
+    return;
+  }
+
+  try {
+    await storeInVault(keyPath, keysDir, pubkey);
+  } catch (error) {
+    console.error(
+      `❌ Error encrypting the replacement: ${error instanceof Error ? error.message : error}`
+    );
+    console.error(`   ${keyPath} was generated; encrypt it once the problem is fixed.`);
+    return;
+  }
+
+  showPublicKey(`Current — still valid (${key}):`, currentPublicKey);
+  showPublicKey(`Replacement — deploy this (${replacement}):`, `${keyPath}.pub`);
+
+  console.log('\n   Next:');
+  console.log(`     1. Add the replacement public key wherever ${key} is authorized.`);
+  console.log(`     2. Check that you can log in with ${keyPath}.`);
+  console.log(`     3. Remove ${key} from those hosts, then retire it here.\n`);
+}
+
+/**
+ * Deletes a vault key and its plaintext copies, after saying exactly what goes.
+ *
+ * The second half of a rotation, and the only operation in keyman that destroys an
+ * encrypted key.
+ */
+export async function retireKey(sshDir: string, keysDir: string, tmpDir: string): Promise<void> {
+  const vaultKeys = listVaultKeys(keysDir);
+
+  if (vaultKeys.length === 0) {
+    console.log('⚠️  No encrypted keys in the vault.');
+    return;
+  }
+
+  const { key } = await inquirer.prompt<{ key: string }>([
+    {
+      type: 'list',
+      name: 'key',
+      message: 'Select the key to retire:',
+      choices: vaultKeys,
+    },
+  ]);
+
+  const vaultPath = path.join(keysDir, key);
+  const files = [
+    ...fs.readdirSync(vaultPath).map((file) => path.join(vaultPath, file)),
+    path.join(tmpDir, `id_${key}`),
+    path.join(tmpDir, `id_${key}.pub`),
+    path.join(sshDir, `id_${key}`),
+    path.join(sshDir, `id_${key}.pub`),
+  ].filter(isFile);
+
+  const successor = supersededBy(key, vaultKeys);
+
+  console.log(`\n🗑️  Retiring ${key} deletes:`);
+  for (const file of files) {
+    console.log(`     ${file}`);
+  }
+  if (successor) {
+    console.log(`\n   ${successor} is in the vault and supersedes ${key}.`);
+  } else {
+    console.log(`\n⚠️  Nothing in the vault supersedes ${key}: this deletes the only copy.`);
+  }
+
+  const { confirmed } = await inquirer.prompt<{ confirmed: boolean }>([
+    {
+      type: 'confirm',
+      name: 'confirmed',
+      message: `Delete ${files.length} ${files.length === 1 ? 'file' : 'files'}?`,
+      default: false,
+    },
+  ]);
+
+  if (!confirmed) {
+    console.log('   Nothing was deleted.');
+    return;
+  }
+
+  // Typed out when there is no successor, because that is the deletion this tool
+  // exists to prevent: an encrypted key nothing replaces is the only copy there is,
+  // and a y/n is one keystroke away from an irreversible one.
+  if (!successor) {
+    const { typed } = await inquirer.prompt<{ typed: string }>([
+      {
+        type: 'input',
+        name: 'typed',
+        message: `Type ${key} to confirm:`,
+      },
+    ]);
+
+    if (typed.trim() !== key) {
+      console.log('   Name did not match — nothing was deleted.');
+      return;
+    }
+  }
+
+  for (const file of files) {
+    fs.rmSync(file, { force: true });
+    console.log(`   Removed ${file}`);
+  }
+
+  try {
+    // Only while empty: anything left in there was not ours to delete.
+    fs.rmdirSync(vaultPath);
+  } catch {
+    console.log(`   Kept ${vaultPath} — it still holds other files.`);
+  }
+
+  console.log(`✅ Retired ${key}.`);
+}

packages/keyman/src/keyman.utils.ts

@@ -1,16 +1,91 @@
 import fs from 'node:fs';
+import { execa, type Options } from 'execa';
+
+/** A binary keyman needs is not installed — recoverable, unlike a tool refusing */
+export class ToolNotFoundError extends Error {
+  constructor(readonly binary: string) {
+    super(`\`${binary}\` was not found on PATH. Install it and try again.`);
+    this.name = 'ToolNotFoundError';
+  }
+}
 
 /**
- * Extracts the public key from an age key file.
- * @param keyFilePath Path to the age key file.
- * @returns The public key as a string, or null if not found.
+ * Runs one of the external binaries keyman depends on.
+ *
+ * Two failures are worth telling apart, and an execa error tells a reader
+ * neither: the binary not being installed (`ENOENT`, whose message is
+ * `spawn <name> ENOENT`) and the binary refusing (whose reason is on stderr and
+ * nowhere in the thrown message). `age` is a hard requirement, so its absence
+ * has to read as an instruction.
+ *
+ * Returns only `stdout` — annotated rather than inferred because execa's result
+ * type cannot be named from here (TS2883), and it is all any caller wants. Empty
+ * when the output went somewhere else, as with `stdio: 'inherit'`.
  */
-export function extractAgePublicKey(keyFilePath: string): string | null {
+export async function runTool(
+  binary: string,
+  args: string[],
+  options?: Options
+): Promise<{ stdout: string }> {
+  try {
+    // Called without the third argument when there are no options, so a test
+    // asserting on the spawn sees the call it wrote.
+    const result = options ? await execa(binary, args, options) : await execa(binary, args);
+    return { stdout: typeof result.stdout === 'string' ? result.stdout : '' };
+  } catch (error) {
+    const failure = error as { code?: string; stderr?: string; shortMessage?: string };
+    if (failure.code === 'ENOENT') {
+      throw new ToolNotFoundError(binary);
+    }
+    throw new Error(`\`${binary}\` failed: ${failure.stderr?.trim() || failure.shortMessage}`);
+  }
+}
+
+/**
+ * The age recipient a vault encrypts to, derived from its identity file.
+ *
+ * `age-keygen -y` derives the public key from the secret key, so it cannot
+ * disagree with it. The `# public key:` comment can: it is ordinary text that
+ * nothing re-checks, and a wrong one encrypts the vault to a recipient nobody
+ * holds the private half of. Verified — rewriting the comment does not change
+ * what `-y` reports.
+ *
+ * The comment stays as a fallback for a machine with no `age-keygen`, behind a
+ * warning that it is unverified. It is *not* a fallback for `age-keygen`
+ * refusing the file: that means age cannot read the identity, and trusting the
+ * comment then would encrypt to a recipient the vault could never decrypt with.
+ *
+ * @returns the recipient, or null with the reason already reported
+ */
+export async function extractAgePublicKey(keyFilePath: string): Promise<string | null> {
   if (!fs.existsSync(keyFilePath)) {
     console.error(`❌ ERROR: Age key file not found at ${keyFilePath}`);
     return null;
   }
 
+  try {
+    const { stdout } = await runTool('age-keygen', ['-y', keyFilePath]);
+    const derived = stdout.trim();
+    if (derived.startsWith('age1')) {
+      return derived;
+    }
+    console.error(`❌ ERROR: age-keygen derived no public key from ${keyFilePath}`);
+    return null;
+  } catch (error) {
+    if (!(error instanceof ToolNotFoundError)) {
+      console.error(`❌ ERROR: ${error instanceof Error ? error.message : error}`);
+      return null;
+    }
+    console.warn(
+      `⚠️  age-keygen is not installed — reading the public key from the comment in ${keyFilePath}, unverified against the secret key.`
+    );
+  }
+
+  return publicKeyFromComment(keyFilePath);
+}
+
+/** The `# public key:` line: a claim about the key rather than a derivation from it */
+function publicKeyFromComment(keyFilePath: string): string | null {
   try {
     const fileContents = fs.readFileSync(keyFilePath, 'utf-8');
     const publicKeyMatch = fileContents.match(/^# public key:\s*(age1[^\s]+)/m);

packages/keyman/src/keyman.vault.ts

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { runTool } from './keyman.utils.js';
+
+/**
+ * The vault entries that hold an encrypted key, sorted.
+ *
+ * A directory counts as an entry when it holds `id_<dir>.age` — the layout
+ * `storeInVault` writes and `decrypt` reads back — which is what keeps a stray
+ * file, or a directory whose encryption failed, out of every menu built from this.
+ * Sorted because the order otherwise comes from the filesystem.
+ */
+export function listVaultKeys(keysDir: string): string[] {
+  // Nothing creates the keys directory until the first encrypt, so on a fresh
+  // vault this readdir threw instead of reporting an empty one.
+  if (!fs.existsSync(keysDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(keysDir)
+    .filter((key) => fs.existsSync(path.join(keysDir, key, `id_${key}.age`)))
+    .sort();
+}
+
+/**
+ * The public half of a private key, derived if the sibling file is missing.
+ *
+ * `encrypt` builds its selection list from private keys only, so a key whose
+ * `.pub` was deleted is offered like any other. Reading the sibling blindly meant
+ * finding out it was absent *after* `age` had written the encrypted key — a vault
+ * entry with no public key, and an exception that killed the rest of the batch.
+ *
+ * @returns the public key text, or null with the reason already reported
+ */
+async function publicKeyFor(keyPath: string): Promise<string | null> {
+  const sibling = `${keyPath}.pub`;
+  if (fs.existsSync(sibling)) {
+    return fs.readFileSync(sibling, 'utf-8');
+  }
+
+  const fileName = path.basename(keyPath);
+  console.log(`ℹ️  ${fileName} has no .pub file — deriving it with ssh-keygen.`);
+
+  try {
+    // stdin and stderr inherited, stdout piped: verified that `ssh-keygen -y`
+    // prompts for the passphrase of an encrypted key, and that it prompts on
+    // *stderr*. Capturing everything would hide the prompt and then fail on the
+    // passphrase nobody was asked for; inheriting everything would lose the key.
+    const { stdout } = await runTool('ssh-keygen', ['-y', '-f', keyPath], {
+      stdio: ['inherit', 'pipe', 'inherit'],
+    });
+    const derived = stdout.trim();
+    if (derived) {
+      return `${derived}\n`;
+    }
+  } catch (error) {
+    console.warn(`⚠️  ${fileName}: ${error instanceof Error ? error.message : error}`);
+  }
+
+  console.warn(`⚠️  ${fileName}: no public key could be derived; storing the private key alone.`);
+  return null;
+}
+
+/**
+ * Encrypts one private key into `<keysDir>/<name>/`, alongside its public half.
+ *
+ * Shared by `encrypt` and `generate`, which were two copies of it.
+ *
+ * @returns the vault directory the key was stored in
+ */
+export async function storeInVault(
+  keyPath: string,
+  keysDir: string,
+  pubkey: string
+): Promise<string> {
+  const fileName = path.basename(keyPath);
+  const vaultPath = path.join(keysDir, fileName.replace(/^id_/, ''));
+
+  // Before the directory exists, so a key that cannot be read does not leave one.
+  const publicKey = await publicKeyFor(keyPath);
+
+  fs.mkdirSync(vaultPath, { recursive: true, mode: 0o700 });
+  const encryptedKey = path.join(vaultPath, `${fileName}.age`);
+
+  try {
+    await runTool('age', ['-r', pubkey, '-o', encryptedKey, keyPath]);
+  } catch (error) {
+    // age writes into a directory that has to exist already, so a failure here
+    // leaves one behind — and possibly a truncated .age file, which `list` would
+    // count as a vault entry and `decrypt` would offer. Both are ours: the file
+    // because we named it, the directory only while it is empty, since one
+    // holding an earlier key is not.
+    fs.rmSync(encryptedKey, { force: true });
+    try {
+      fs.rmdirSync(vaultPath);
+    } catch {
+      // ENOTEMPTY — something else was already stored here.
+    }
+    throw error;
+  }
+
+  if (publicKey !== null) {
+    fs.writeFileSync(path.join(vaultPath, `${fileName}.pub`), publicKey);
+  }
+
+  console.log(`🔒 Encrypted and stored: ${path.join(vaultPath, `${fileName}.age`)}`);
+  return vaultPath;
+}

packages/keyman/tests/args.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for keyman's argv parsing.
+ *
+ * The old inline reader in keyman.cli.ts turned three different mistakes into
+ * silence or into a wrong diagnosis, so the interesting cases here are the
+ * rejections rather than the happy paths.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { CHANNELS, helpText, KNOWN_FLAGS, parseArgs, UsageError } from '../src/keyman.args.js';
+
+describe('parseArgs', () => {
+  it('defaults to the interactive session', () => {
+    expect(parseArgs([])).toEqual({ command: 'interactive' });
+  });
+
+  it.each([
+    [['--help'], 'help'],
+    [['-h'], 'help'],
+    [['--version'], 'version'],
+    [['-V'], 'version'],
+    [['--print-config'], 'print-config'],
+  ] as const)('%s selects %s', (argv, command) => {
+    expect(parseArgs([...argv])).toEqual({ command });
+  });
+
+  it('answers --help even when the rest of the line is wrong', () => {
+    expect(parseArgs(['--bogus', '--help'])).toEqual({ command: 'help' });
+    expect(parseArgs(['--help', '--channel'])).toEqual({ command: 'help' });
+  });
+
+  describe('self-update', () => {
+    it.each(['self-update', 'upgrade'])('is selected by the %s subcommand', (subcommand) => {
+      expect(parseArgs([subcommand])).toEqual({
+        command: 'self-update',
+        dryRun: false,
+        force: false,
+        channel: undefined,
+        registry: undefined,
+      });
+    });
+
+    it('is selected by --self-update', () => {
+      expect(parseArgs(['--self-update'])).toMatchObject({ command: 'self-update' });
+    });
+
+    it('collects its flags, long and short', () => {
+      expect(parseArgs(['self-update', '--dry-run', '--force'])).toMatchObject({
+        dryRun: true,
+        force: true,
+      });
+      expect(parseArgs(['self-update', '-n', '-f'])).toMatchObject({
+        dryRun: true,
+        force: true,
+      });
+    });
+
+    it.each(['--channel main', '--channel=main'])('accepts %s', (form) => {
+      expect(parseArgs(['self-update', ...form.split(' ')])).toMatchObject({ channel: 'main' });
+    });
+
+    it('accepts every real channel', () => {
+      for (const channel of CHANNELS) {
+        expect(parseArgs(['self-update', '--channel', channel])).toMatchObject({ channel });
+      }
+    });
+
+    it('reads a registry in either form', () => {
+      expect(parseArgs(['self-update', '--registry', 'https://r.example'])).toMatchObject({
+        registry: 'https://r.example',
+      });
+      expect(parseArgs(['self-update', '--registry=https://r.example'])).toMatchObject({
+        registry: 'https://r.example',
+      });
+    });
+
+    it('keeps a value that starts with a dash when it was written inline', () => {
+      expect(parseArgs(['self-update', '--registry=-weird'])).toMatchObject({
+        registry: '-weird',
+      });
+    });
+  });
+
+  describe('rejections', () => {
+    const reject = (argv: string[]) => () => parseArgs(argv);
+
+    it('rejects a channel that is not a channel', () => {
+      expect(reject(['self-update', '--channel', 'stable'])).toThrow(UsageError);
+      expect(reject(['self-update', '--channel', 'stable'])).toThrow(
+        'Unknown channel: stable (expected latest, next, main)'
+      );
+    });
+
+    it('rejects the next flag being eaten as a value', () => {
+      // The bug this whole module exists for: --channel --force used to set the
+      // channel to "--force" and report an unreachable registry.
+      expect(reject(['self-update', '--channel', '--force'])).toThrow('--channel expects a value');
+    });
+
+    it('rejects a value flag with nothing after it', () => {
+      expect(reject(['self-update', '--channel'])).toThrow('--channel expects a value');
+      expect(reject(['self-update', '--registry='])).toThrow('--registry expects a value');
+    });
+
+    it('rejects a boolean flag given a value', () => {
+      expect(reject(['--dry-run=yes'])).toThrow('--dry-run does not take a value');
+    });
+
+    it('rejects unknown flags and commands', () => {
+      expect(reject(['--vault', 'foo'])).toThrow('Unknown flag: --vault');
+      expect(reject(['-x'])).toThrow('Unknown flag: -x');
+      expect(reject(['encrypt'])).toThrow('Unknown command: encrypt');
+      expect(reject(['self-update', 'upgrade'])).toThrow('Unexpected argument: upgrade');
+    });
+
+    it.each(['--channel', '--registry', '--dry-run', '-n', '--force', '-f'])(
+      'rejects %s without self-update rather than ignoring it',
+      (flag) => {
+        const argv = flag === '--channel' || flag === '--registry' ? [flag, 'main'] : [flag];
+        expect(reject(argv)).toThrow('is only valid with `keyman self-update`');
+      }
+    );
+
+    it('rejects a self-update flag alongside another command', () => {
+      expect(reject(['--print-config', '--force'])).toThrow('--force is only valid');
+    });
+  });
+});
+
+describe('helpText', () => {
+  it('documents every flag the parser accepts', () => {
+    const text = helpText();
+    for (const flag of KNOWN_FLAGS) {
+      expect(text, `${flag} is missing from --help`).toContain(flag);
+    }
+  });
+
+  it('names both subcommands, every channel, and the environment variables', () => {
+    const text = helpText();
+    expect(text).toContain('self-update');
+    expect(text).toContain('upgrade');
+    for (const channel of CHANNELS) {
+      expect(text).toContain(channel);
+    }
+    for (const variable of [
+      'VAULT_ROOT',
+      'KEYMAN_REGISTRY',
+      'KEYMAN_REGISTRY_TOKEN',
+      'KEYMAN_NO_UPDATE_CHECK',
+      'KEYMAN_PACKAGE_MANAGER',
+    ]) {
+      expect(text).toContain(variable);
+    }
+  });
+});

packages/keyman/tests/clear.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Tests for the plaintext hygiene helpers: the vault .gitignore and the
+ * clear-decrypted-keys operation.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { prompt } = vi.hoisted(() => ({ prompt: vi.fn() }));
+
+vi.mock('inquirer', () => ({ default: { prompt } }));
+
+import { clearDecryptedKeys, writeVaultGitignore } from '../src/keyman.clear.js';
+
+describe('writeVaultGitignore', () => {
+  let vaultRoot: string;
+
+  const read = () => fs.readFileSync(path.join(vaultRoot, '.gitignore'), 'utf-8');
+
+  beforeEach(() => {
+    vaultRoot = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-ignore-')));
+  });
+
+  afterEach(() => {
+    fs.rmSync(vaultRoot, { recursive: true, force: true });
+  });
+
+  it('ignores the identity and the decrypted keys, not the encrypted ones', () => {
+    writeVaultGitignore(vaultRoot, path.join(vaultRoot, 'tmp'), path.join(vaultRoot, 'age.key'));
+
+    const contents = read();
+    expect(contents).toContain('age.key\n');
+    expect(contents).toContain('age.key.pub');
+    expect(contents).toContain('tmp/');
+    // The encrypted keys are the thing worth committing.
+    expect(contents).not.toContain('keys/');
+  });
+
+  it('uses the configured names', () => {
+    writeVaultGitignore(
+      vaultRoot,
+      path.join(vaultRoot, 'plain'),
+      path.join(vaultRoot, 'identity.age')
+    );
+
+    expect(read()).toContain('plain/');
+    expect(read()).toContain('identity.age');
+  });
+
+  it('says nothing about a directory outside the vault', () => {
+    writeVaultGitignore(vaultRoot, '/elsewhere/tmp', path.join(vaultRoot, 'age.key'));
+
+    // A .gitignore cannot speak for a path above itself, and pretending otherwise
+    // would read as protection that is not there.
+    expect(read()).not.toContain('elsewhere');
+    expect(read()).toContain('age.key');
+  });
+
+  it('never overwrites an existing file', () => {
+    fs.writeFileSync(path.join(vaultRoot, '.gitignore'), 'mine\n');
+
+    writeVaultGitignore(vaultRoot, path.join(vaultRoot, 'tmp'), path.join(vaultRoot, 'age.key'));
+
+    expect(read()).toBe('mine\n');
+  });
+
+  it('creates it private to the owner', () => {
+    writeVaultGitignore(vaultRoot, path.join(vaultRoot, 'tmp'), path.join(vaultRoot, 'age.key'));
+
+    expect(fs.statSync(path.join(vaultRoot, '.gitignore')).mode & 0o777).toBe(0o600);
+  });
+});
+
+describe('clearDecryptedKeys', () => {
+  let tmpDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  const messages = () => logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  const decrypted = (name: string) => {
+    fs.writeFileSync(path.join(tmpDir, name), 'PRIVATE');
+    fs.writeFileSync(path.join(tmpDir, `${name}.pub`), 'PUBLIC');
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-clear-')));
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    prompt.mockResolvedValue({ confirmed: true });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('says so when there is nothing to clear', async () => {
+    await clearDecryptedKeys(tmpDir);
+
+    expect(messages()).toContain('Nothing decrypted');
+    expect(prompt).not.toHaveBeenCalled();
+  });
+
+  it('does not mind a tmp directory that was never created', async () => {
+    fs.rmSync(tmpDir, { recursive: true });
+
+    await expect(clearDecryptedKeys(tmpDir)).resolves.toBeUndefined();
+  });
+
+  it('removes each key and its public half', async () => {
+    decrypted('id_prod');
+    decrypted('id_stage');
+
+    await clearDecryptedKeys(tmpDir);
+
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
+    expect(messages()).toContain('Removed id_prod');
+  });
+
+  it('lists what it is about to delete before asking', async () => {
+    decrypted('id_prod');
+
+    await clearDecryptedKeys(tmpDir);
+
+    const askedAt = messages().indexOf('id_prod');
+    expect(askedAt).toBeGreaterThanOrEqual(0);
+    expect(prompt.mock.calls[0][0][0]).toMatchObject({ type: 'confirm', default: false });
+  });
+
+  it('keeps everything when the confirmation is declined', async () => {
+    decrypted('id_prod');
+    prompt.mockResolvedValue({ confirmed: false });
+
+    await clearDecryptedKeys(tmpDir);
+
+    expect(fs.existsSync(path.join(tmpDir, 'id_prod'))).toBe(true);
+    expect(messages()).toContain('Nothing was deleted');
+  });
+
+  it('leaves files that are not keys alone', async () => {
+    decrypted('id_prod');
+    fs.writeFileSync(path.join(tmpDir, 'notes.md'), 'mine');
+
+    await clearDecryptedKeys(tmpDir);
+
+    expect(fs.readdirSync(tmpDir)).toEqual(['notes.md']);
+  });
+
+  it('does not fail on a key whose public half is missing', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'id_prod'), 'PRIVATE');
+
+    await clearDecryptedKeys(tmpDir);
+
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
+  });
+});

packages/keyman/tests/clipboard.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for the clipboard layer.
+ *
+ * The platform is passed in rather than stubbed, so every branch is reachable from
+ * the one machine the suite runs on.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execa } = vi.hoisted(() => ({ execa: vi.fn() }));
+
+vi.mock('execa', () => ({ execa }));
+
+import { clipboardTools, copyToClipboard } from '../src/keyman.clipboard.js';
+
+describe('clipboardTools', () => {
+  it.each([
+    ['darwin', ['pbcopy']],
+    ['win32', ['clip']],
+    ['linux', ['wl-copy', 'xclip', 'xsel']],
+    // Anything unrecognised gets the X11/Wayland list rather than nothing: a BSD
+    // running the same desktop stack is closer to linux than to no answer.
+    ['freebsd', ['wl-copy', 'xclip', 'xsel']],
+  ])('offers the right commands on %s', (platform, expected) => {
+    expect(clipboardTools(platform).map((t) => t.binary)).toEqual(expected);
+  });
+
+  it('passes the clipboard selection to the X11 tools', () => {
+    const byBinary = new Map(clipboardTools('linux').map((t) => [t.binary, t.args]));
+
+    // Without these, xclip and xsel write to the primary selection, which is not
+    // the clipboard a paste reads from.
+    expect(byBinary.get('xclip')).toEqual(['-selection', 'clipboard']);
+    expect(byBinary.get('xsel')).toEqual(['--clipboard', '--input']);
+  });
+});
+
+describe('copyToClipboard', () => {
+  const notFound = () =>
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' });
+    });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    execa.mockResolvedValue({ stdout: '' });
+  });
+
+  it('pipes the text to the first available command', async () => {
+    const tool = await copyToClipboard('ssh-ed25519 AAAA', 'darwin');
+
+    expect(tool).toBe('pbcopy');
+    expect(execa).toHaveBeenCalledWith('pbcopy', [], { input: 'ssh-ed25519 AAAA' });
+  });
+
+  it('moves on from a command that is not installed', async () => {
+    execa.mockImplementation(async (binary: string) => {
+      if (binary !== 'xclip') {
+        throw Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' });
+      }
+      return { stdout: '' };
+    });
+
+    expect(await copyToClipboard('key', 'linux')).toBe('xclip');
+    expect(execa.mock.calls.map((c) => c[0])).toEqual(['wl-copy', 'xclip']);
+  });
+
+  it('reports that nothing was available rather than throwing', async () => {
+    notFound();
+
+    expect(await copyToClipboard('key', 'linux')).toBeNull();
+    expect(execa).toHaveBeenCalledTimes(3);
+  });
+
+  it('surfaces a command that ran and refused', async () => {
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('failed'), { stderr: 'Error: No protocol specified' });
+    });
+
+    // A tool with an opinion is not an absent tool: trying the next one would
+    // hide a real problem behind a second failure.
+    await expect(copyToClipboard('key', 'linux')).rejects.toThrow('No protocol specified');
+    expect(execa).toHaveBeenCalledTimes(1);
+  });
+});

packages/keyman/tests/config.test.ts

@@ -11,6 +11,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import {
+  describeConfig,
   getConfigPaths,
   type KeymanConfigFile,
   loadConfig,
@@ -208,49 +209,82 @@ describe('keyman config', () => {
     });
   });
 
-  describe('merge strategy', () => {
-    it('honours an explicit override strategy', () => {
-      write(rootDir, { vaultRoot: '/parent-vault' });
-      const child = path.join(rootDir, 'nested');
-      write(child, { vaultRoot: '/child-vault', resolution: { vaultRoot: 'override' } });
-      process.chdir(child);
+  describe('unknown keys', () => {
+    /** What a config file is likely to get wrong: the casing of a real key. */
+    const TYPO = { vaultroot: '/somewhere-else' } as unknown as KeymanConfigFile;
 
-      expect(loadConfig().vaultRoot).toBe('/child-vault');
+    it('names the file, the key and what it could have been', () => {
+      write(rootDir, TYPO);
+
+      loadConfig();
+
+      const warned = messages(warnSpy);
+      expect(warned).toContain(path.join(rootDir, '.keymanrc.json'));
+      expect(warned).toContain('vaultroot');
+      // Without the list of known keys the warning says a key is wrong without
+      // saying what right looks like, which for a casing slip is most of the work.
+      expect(warned).toContain('vaultRoot');
     });
 
-    it('never surfaces the resolution key in the loaded config', () => {
-      write(rootDir, { keysDir: 'my-keys', resolution: { keysDir: 'override' } });
-
-      expect(loadConfig()).not.toHaveProperty('resolution');
-    });
-
-    it('tolerates and drops array-valued keys the schema does not define', () => {
-      write(rootDir, { extra: ['a', 'b'] } as unknown as KeymanConfigFile);
-      const child = path.join(rootDir, 'nested');
-      write(child, { extra: ['b', 'c'], keysDir: 'my-keys' } as unknown as KeymanConfigFile);
-      process.chdir(child);
+    it('still applies the keys it does understand', () => {
+      write(rootDir, { ...TYPO, keysDir: 'my-keys' });
 
       const config = loadConfig();
 
-      expect(config).toEqual({ ...DEFAULTS, keysDir: 'my-keys' });
+      expect(config.keysDir).toBe('my-keys');
+      expect(config.vaultRoot).toBe(DEFAULTS.vaultRoot);
     });
 
-    it('tolerates and drops object-valued keys the schema does not define', () => {
-      write(rootDir, { extra: { a: 1 } } as unknown as KeymanConfigFile);
+    it('blames the file that said it, not the merged result', () => {
+      write(rootDir, {});
       const child = path.join(rootDir, 'nested');
-      write(child, { extra: { a: 2, b: 3 } } as unknown as KeymanConfigFile);
+      write(child, TYPO);
       process.chdir(child);
 
-      expect(loadConfig()).toEqual(DEFAULTS);
+      loadConfig();
+
+      expect(messages(warnSpy)).toContain(path.join(child, '.keymanrc.json'));
+      expect(messages(warnSpy)).not.toContain(path.join(rootDir, '.keymanrc.json'));
     });
 
-    it('tolerates arrays of objects, which cannot be de-duplicated', () => {
-      write(rootDir, { extra: [{ a: 1 }] } as unknown as KeymanConfigFile);
+    it('lists every unknown key in one warning per file', () => {
+      write(rootDir, { nope: 1, alsoNope: 2 } as unknown as KeymanConfigFile);
+
+      loadConfig();
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(messages(warnSpy)).toContain('nope, alsoNope');
+      expect(messages(warnSpy)).toContain('unknown keys');
+    });
+
+    it('says key, singular, for one of them', () => {
+      write(rootDir, TYPO);
+
+      loadConfig();
+
+      expect(messages(warnSpy)).toContain('unknown key ');
+    });
+
+    it('says nothing about a file that sets only known keys', () => {
+      write(rootDir, { keysDir: 'my-keys', tmpDir: 'my-tmp' });
+
+      loadConfig();
+
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['array-valued', { extra: ['a', 'b'] }],
+      ['object-valued', { extra: { a: 1 } }],
+      ['an array of objects', { extra: [{ a: 1 }] }],
+    ])('drops a %s unknown key rather than merging it in', (_label, extra) => {
+      write(rootDir, extra as unknown as KeymanConfigFile);
       const child = path.join(rootDir, 'nested');
-      write(child, { extra: [{ a: 2 }] } as unknown as KeymanConfigFile);
+      write(child, { ...extra, keysDir: 'my-keys' } as unknown as KeymanConfigFile);
       process.chdir(child);
 
-      expect(loadConfig()).toEqual(DEFAULTS);
+      // The schema strips them; nothing in keyman merges an array or an object.
+      expect(loadConfig()).toEqual({ ...DEFAULTS, keysDir: 'my-keys' });
     });
   });
 
@@ -291,4 +325,27 @@ describe('keyman config', () => {
       expect(paths.keysDir).toBe('/elsewhere/keys');
     });
   });
+
+  describe('describeConfig', () => {
+    it('reports the resolved paths and the files they came from', () => {
+      write(rootDir, { keysDir: 'my-keys', vaultRoot: 'vault' });
+      const child = path.join(rootDir, 'nested');
+      write(child, { tmpDir: 'my-tmp' });
+      process.chdir(child);
+
+      expect(describeConfig()).toEqual({
+        vaultRoot: path.join(rootDir, 'vault'),
+        keysDir: path.join(rootDir, 'vault', 'my-keys'),
+        tmpDir: path.join(rootDir, 'vault', 'my-tmp'),
+        keyPath: path.join(rootDir, 'vault', 'age.key'),
+        // Parent first, the order they were merged in — which is the only way to
+        // read a surprising value back to the file responsible for it.
+        configFiles: [path.join(rootDir, '.keymanrc.json'), path.join(child, '.keymanrc.json')],
+      });
+    });
+
+    it('reports an empty list when nothing was found', () => {
+      expect(describeConfig().configFiles).toEqual([]);
+    });
+  });
 });

packages/keyman/tests/copy.test.ts

@@ -10,11 +10,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-const { execa, prompt, stdin } = vi.hoisted(() => ({
-  execa: vi.fn(),
-  prompt: vi.fn(),
-  stdin: { write: vi.fn(), end: vi.fn() },
-}));
+const { execa, prompt } = vi.hoisted(() => ({ execa: vi.fn(), prompt: vi.fn() }));
 
 vi.mock('execa', () => ({ execa }));
 vi.mock('inquirer', () => ({ default: { prompt } }));
@@ -27,6 +23,7 @@ describe('copyKey', () => {
   let tmpDir: string;
   let logSpy: ReturnType<typeof vi.spyOn>;
   let errorSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
 
   const touch = (dir: string, file: string, contents = '') => {
     fs.mkdirSync(dir, { recursive: true });
@@ -39,6 +36,9 @@ describe('copyKey', () => {
   /** The choices offered by the last inquirer.prompt call. */
   const choices = () => prompt.mock.calls.at(-1)?.[0][0].choices as string[];
 
+  /** What was piped into the clipboard command. */
+  const piped = () => (execa.mock.calls.at(-1)?.[2] as { input?: string } | undefined)?.input;
+
   beforeEach(() => {
     vi.clearAllMocks();
     root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-copy-')));
@@ -46,9 +46,9 @@ describe('copyKey', () => {
     tmpDir = path.join(root, 'tmp');
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
-    const proc = Object.assign(Promise.resolve({ exitCode: 0 }), { stdin });
-    execa.mockReturnValue(proc);
+    execa.mockResolvedValue({ stdout: '' });
   });
 
   afterEach(() => {
@@ -93,9 +93,7 @@ describe('copyKey', () => {
 
     await copyKey(sshDir, tmpDir);
 
-    expect(execa).toHaveBeenCalledWith('pbcopy');
-    expect(stdin.write).toHaveBeenCalledWith('ssh-ed25519 AAAA tmp');
-    expect(stdin.end).toHaveBeenCalled();
+    expect(piped()).toBe('ssh-ed25519 AAAA tmp');
     expect(messages(logSpy)).toContain('copied to clipboard');
   });
 
@@ -106,7 +104,7 @@ describe('copyKey', () => {
 
     await copyKey(sshDir, tmpDir);
 
-    expect(stdin.write).toHaveBeenCalledWith('ssh-ed25519 AAAA ssh');
+    expect(piped()).toBe('ssh-ed25519 AAAA ssh');
   });
 
   it('reports a missing public key without invoking the clipboard', async () => {
@@ -123,11 +121,38 @@ describe('copyKey', () => {
     touch(sshDir, 'id_prod');
     touch(sshDir, 'id_prod.pub', 'ssh-ed25519 AAAA ssh');
     prompt.mockResolvedValue({ selectedKey: 'id_prod' });
-    execa.mockImplementation(() => {
-      throw new Error('pbcopy missing');
-    });
+    execa.mockRejectedValue(Object.assign(new Error('refused'), { stderr: 'no display' }));
 
     await expect(copyKey(sshDir, tmpDir)).resolves.toBeUndefined();
     expect(messages(errorSpy)).toContain('Failed to copy to clipboard');
   });
+
+  it('prints the key when no clipboard command exists at all', async () => {
+    touch(sshDir, 'id_prod');
+    touch(sshDir, 'id_prod.pub', 'ssh-ed25519 AAAA ssh');
+    prompt.mockResolvedValue({ selectedKey: 'id_prod' });
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('spawn ENOENT'), { code: 'ENOENT' });
+    });
+
+    await copyKey(sshDir, tmpDir);
+
+    // The operation is "give me this public key". Without a clipboard it is still
+    // answerable, and it used to be a dead end on every platform but macOS.
+    expect(messages(logSpy)).toContain('ssh-ed25519 AAAA ssh');
+    expect(messages(warnSpy)).toContain('No clipboard command found');
+  });
+
+  it('names the private keys it cannot manage', async () => {
+    touch(sshDir, 'id_prod');
+    touch(sshDir, 'id_prod.pub', 'PUBLIC');
+    touch(sshDir, 'deploy_ed25519', '-----BEGIN OPENSSH PRIVATE KEY-----\nAAAA\n');
+    prompt.mockResolvedValue({ selectedKey: 'id_prod' });
+
+    await copyKey(sshDir, tmpDir);
+
+    expect(choices()).toEqual(['id_prod']);
+    expect(messages(logSpy)).toContain('deploy_ed25519');
+    expect(messages(logSpy)).toContain('not named id_*');
+  });
 });

packages/keyman/tests/decrypt.test.ts

@@ -1,8 +1,10 @@
 /**
  * Tests for decryptKeys.
  *
- * age, cp and chmod are all mocked; the assertions cover which keys are
- * offered and exactly where each decrypted key is written.
+ * Only `age` is mocked, and its stand-in writes the output file the way age
+ * would: the copy and the chmod are now real fs calls, so the assertions are on
+ * what ends up on disk and at what mode rather than on which binaries were
+ * spawned.
  */
 
 import fs from 'node:fs';
@@ -17,27 +19,35 @@ vi.mock('inquirer', () => ({ default: { prompt } }));
 
 import { decryptKeys } from '../src/keyman.decrypt.js';
 
-const LOCAL = 'Local (vault/tmp)';
-const SSH = 'SSH (~/.ssh)';
+const LOCAL = 'local';
+const SSH = 'ssh';
 
 describe('decryptKeys', () => {
   let root: string;
   let sshDir: string;
   let vaultDir: string;
-  let keyDir: string;
+  let keysDir: string;
+  let tmpDir: string;
   let logSpy: ReturnType<typeof vi.spyOn>;
 
   const AGE_KEY = '/vault/age.key';
 
   /** Creates <vault>/keys/<name>/id_<name>.{age,pub}. */
   const vaultKey = (name: string) => {
-    const dir = path.join(keyDir, name);
+    const dir = path.join(keysDir, name);
     fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(path.join(dir, `id_${name}.age`), 'ENCRYPTED');
-    fs.writeFileSync(path.join(dir, `id_${name}.pub`), 'PUBLIC');
+    fs.writeFileSync(path.join(dir, `id_${name}.age`), `ENCRYPTED ${name}`);
+    fs.writeFileSync(path.join(dir, `id_${name}.pub`), `PUBLIC ${name}`);
   };
 
-  const choices = () => prompt.mock.calls.at(-1)?.[0][0].choices as string[];
+  /** Answers the selection prompt, then every overwrite confirmation. */
+  const answers = (selectedKeys: string[], decryptMode = LOCAL, overwrite = false) => {
+    prompt.mockImplementation(async (questions: { name: string }[]) =>
+      questions[0].name === 'selectedKeys' ? { selectedKeys, decryptMode } : { overwrite }
+    );
+  };
+
+  const choices = () => prompt.mock.calls[0]?.[0][0].choices as string[];
 
   const argsOf = (binary: string) =>
     execa.mock.calls.find((c) => c[0] === binary)?.[1] as string[] | undefined;
@@ -45,16 +55,26 @@ describe('decryptKeys', () => {
   const messages = (spy: ReturnType<typeof vi.spyOn>) =>
     spy.mock.calls.map((c) => c.join(' ')).join('\n');
 
+  const modeOf = (file: string) => fs.statSync(file).mode & 0o777;
+
   beforeEach(() => {
     vi.clearAllMocks();
     root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-decrypt-')));
     sshDir = path.join(root, '.ssh');
     vaultDir = path.join(root, 'vault');
-    keyDir = path.join(vaultDir, 'keys');
-    fs.mkdirSync(keyDir, { recursive: true });
+    keysDir = path.join(vaultDir, 'keys');
+    tmpDir = path.join(vaultDir, 'tmp');
+    fs.mkdirSync(keysDir, { recursive: true });
     fs.mkdirSync(sshDir, { recursive: true });
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    execa.mockResolvedValue({ exitCode: 0 });
+
+    // Stand in for `age -d`: write the plaintext to -o, 0644 as age does.
+    execa.mockImplementation(async (_binary: string, args: string[]) => {
+      const out = args[args.indexOf('-o') + 1];
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, 'PLAINTEXT', { mode: 0o644 });
+      return { exitCode: 0 };
+    });
   });
 
   afterEach(() => {
@@ -63,72 +83,200 @@ describe('decryptKeys', () => {
   });
 
   it('warns when the vault holds no encrypted keys', async () => {
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
     expect(messages(logSpy)).toContain('No encrypted keys found.');
     expect(prompt).not.toHaveBeenCalled();
   });
 
+  it('warns instead of throwing when the vault has no keys directory', async () => {
+    fs.rmSync(keysDir, { recursive: true });
+
+    await expect(decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY)).resolves.toBeUndefined();
+    expect(messages(logSpy)).toContain('No encrypted keys found.');
+  });
+
+  it('reports a missing age binary rather than an ENOENT', async () => {
+    vaultKey('prod');
+    answers(['prod']);
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('spawn age ENOENT'), { code: 'ENOENT' });
+    });
+
+    await expect(decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY)).rejects.toThrow(
+      '`age` was not found on PATH'
+    );
+  });
+
   it('offers only directories that actually contain an encrypted key', async () => {
     vaultKey('prod');
-    fs.mkdirSync(path.join(keyDir, 'empty'), { recursive: true });
-    fs.writeFileSync(path.join(keyDir, 'README.md'), '');
-    prompt.mockResolvedValue({ selectedKeys: [], decryptMode: LOCAL });
+    fs.mkdirSync(path.join(keysDir, 'empty'), { recursive: true });
+    fs.writeFileSync(path.join(keysDir, 'README.md'), '');
+    answers([]);
 
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
     expect(choices()).toEqual(['prod']);
   });
 
   it('decrypts into the vault tmp directory', async () => {
     vaultKey('prod');
-    prompt.mockResolvedValue({ selectedKeys: ['prod'], decryptMode: LOCAL });
+    answers(['prod']);
 
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
-    const out = path.join(vaultDir, 'tmp', 'id_prod');
+    const out = path.join(tmpDir, 'id_prod');
     expect(argsOf('age')).toEqual([
       '-d',
       '-i',
       AGE_KEY,
       '-o',
       out,
-      path.join(keyDir, 'prod', 'id_prod.age'),
+      path.join(keysDir, 'prod', 'id_prod.age'),
     ]);
-    expect(argsOf('cp')).toEqual([path.join(keyDir, 'prod', 'id_prod.pub'), `${out}.pub`]);
-    expect(argsOf('chmod')).toEqual(['600', out]);
+    expect(fs.readFileSync(out, 'utf-8')).toBe('PLAINTEXT');
+    expect(fs.readFileSync(`${out}.pub`, 'utf-8')).toBe('PUBLIC prod');
     expect(messages(logSpy)).toContain(`Decrypted: ${out}`);
   });
 
   it('decrypts into the .ssh directory when asked', async () => {
     vaultKey('prod');
-    prompt.mockResolvedValue({ selectedKeys: ['prod'], decryptMode: SSH });
+    answers(['prod'], SSH);
 
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
     const out = path.join(sshDir, 'id_prod');
     expect(argsOf('age')?.[4]).toBe(out);
-    expect(argsOf('cp')?.[1]).toBe(`${out}.pub`);
-    expect(argsOf('chmod')).toEqual(['600', out]);
+    expect(fs.readFileSync(`${out}.pub`, 'utf-8')).toBe('PUBLIC prod');
   });
 
-  it('decrypts every selected key', async () => {
+  it('creates the .ssh directory when it does not exist, private to the owner', async () => {
+    fs.rmSync(sshDir, { recursive: true });
+    vaultKey('prod');
+    answers(['prod'], SSH);
+
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+    expect(modeOf(sshDir)).toBe(0o700);
+    expect(fs.existsSync(path.join(sshDir, 'id_prod'))).toBe(true);
+  });
+
+  it('leaves the private key at 0600, never observable at what age wrote', async () => {
+    vaultKey('prod');
+    answers(['prod']);
+
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+    expect(modeOf(path.join(tmpDir, 'id_prod'))).toBe(0o600);
+  });
+
+  it('decrypts every selected key with one spawn each', async () => {
     vaultKey('prod');
     vaultKey('stage');
-    prompt.mockResolvedValue({ selectedKeys: ['prod', 'stage'], decryptMode: LOCAL });
+    answers(['prod', 'stage']);
 
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
-    // age, cp and chmod for each of the two keys.
-    expect(execa).toHaveBeenCalledTimes(6);
+    // One age per key: the cp and chmod spawns are gone.
+    expect(execa).toHaveBeenCalledTimes(2);
+    expect(execa.mock.calls.every((c) => c[0] === 'age')).toBe(true);
   });
 
   it('does nothing when the selection is empty', async () => {
     vaultKey('prod');
-    prompt.mockResolvedValue({ selectedKeys: [], decryptMode: LOCAL });
+    answers([]);
 
-    await decryptKeys(sshDir, vaultDir, AGE_KEY);
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
 
     expect(execa).not.toHaveBeenCalled();
   });
+
+  it('writes the private key even when the vault entry has no public key', async () => {
+    vaultKey('prod');
+    fs.rmSync(path.join(keysDir, 'prod', 'id_prod.pub'));
+    answers(['prod']);
+
+    await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+    expect(fs.existsSync(path.join(tmpDir, 'id_prod'))).toBe(true);
+    expect(messages(logSpy)).toContain('has no public key in the vault');
+  });
+
+  describe('when the target already exists', () => {
+    const existing = (dir: string, name = 'id_prod') => {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, name), 'PRECIOUS EXISTING KEY');
+      return path.join(dir, name);
+    };
+
+    it('keeps the existing key by default', async () => {
+      vaultKey('prod');
+      const target = existing(tmpDir);
+      answers(['prod']);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      expect(fs.readFileSync(target, 'utf-8')).toBe('PRECIOUS EXISTING KEY');
+      expect(execa).not.toHaveBeenCalled();
+      expect(messages(logSpy)).toContain('Skipped prod');
+    });
+
+    it('asks before overwriting, defaulting to no', async () => {
+      vaultKey('prod');
+      existing(tmpDir);
+      answers(['prod']);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      const confirm = prompt.mock.calls.at(-1)?.[0][0];
+      expect(confirm).toMatchObject({ type: 'confirm', default: false });
+      expect(confirm.message).toContain(path.join(tmpDir, 'id_prod'));
+    });
+
+    it('overwrites once confirmed', async () => {
+      vaultKey('prod');
+      const target = existing(tmpDir);
+      answers(['prod'], LOCAL, true);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      expect(fs.readFileSync(target, 'utf-8')).toBe('PLAINTEXT');
+    });
+
+    it('asks about an existing public key too', async () => {
+      vaultKey('prod');
+      existing(tmpDir, 'id_prod.pub');
+      answers(['prod']);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      expect(execa).not.toHaveBeenCalled();
+      expect(prompt.mock.calls.at(-1)?.[0][0].message).toContain('id_prod.pub');
+    });
+
+    it('protects a key in .ssh the same way', async () => {
+      vaultKey('prod');
+      const target = existing(sshDir);
+      answers(['prod'], SSH);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      expect(fs.readFileSync(target, 'utf-8')).toBe('PRECIOUS EXISTING KEY');
+    });
+
+    it('settles every collision before decrypting anything', async () => {
+      vaultKey('prod');
+      vaultKey('stage');
+      existing(tmpDir);
+      answers(['prod', 'stage']);
+
+      await decryptKeys(sshDir, keysDir, tmpDir, AGE_KEY);
+
+      // stage is written, prod is kept — and the question about prod was asked
+      // before either was touched.
+      expect(fs.existsSync(path.join(tmpDir, 'id_stage'))).toBe(true);
+      expect(fs.readFileSync(path.join(tmpDir, 'id_prod'), 'utf-8')).toBe('PRECIOUS EXISTING KEY');
+      expect(execa).toHaveBeenCalledTimes(1);
+    });
+  });
 });

packages/keyman/tests/encrypt.test.ts

@@ -20,7 +20,7 @@ import { encryptKeys } from '../src/keyman.encrypt.js';
 describe('encryptKeys', () => {
   let root: string;
   let sshDir: string;
-  let vaultDir: string;
+  let keysDir: string;
   let tmpDir: string;
   let logSpy: ReturnType<typeof vi.spyOn>;
 
@@ -41,7 +41,7 @@ describe('encryptKeys', () => {
     vi.clearAllMocks();
     root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-encrypt-')));
     sshDir = path.join(root, '.ssh');
-    vaultDir = path.join(root, 'vault');
+    keysDir = path.join(root, 'vault', 'keys');
     tmpDir = path.join(root, 'vault', 'tmp');
     fs.mkdirSync(sshDir, { recursive: true });
     fs.mkdirSync(tmpDir, { recursive: true });
@@ -60,17 +60,44 @@ describe('encryptKeys', () => {
   });
 
   it('warns when there is nothing to encrypt', async () => {
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(messages(logSpy)).toContain('No private SSH keys found to encrypt.');
     expect(prompt).not.toHaveBeenCalled();
   });
 
+  it('warns instead of throwing when the .ssh directory does not exist', async () => {
+    fs.rmSync(sshDir, { recursive: true });
+
+    await expect(encryptKeys(sshDir, keysDir, tmpDir, PUBKEY)).resolves.toBeUndefined();
+    expect(messages(logSpy)).toContain('No private SSH keys found to encrypt.');
+  });
+
+  it('still offers the .ssh keys when the tmp directory does not exist', async () => {
+    fs.rmSync(tmpDir, { recursive: true });
+    key(sshDir, 'id_prod', 'ssh');
+    prompt.mockResolvedValue({ selectedKeys: [] });
+
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(choices()).toEqual(['id_prod']);
+  });
+
+  it('reports a missing age binary rather than an ENOENT', async () => {
+    key(sshDir, 'id_prod', 'ssh');
+    prompt.mockResolvedValue({ selectedKeys: ['id_prod'] });
+    execa.mockRejectedValue(Object.assign(new Error('spawn age ENOENT'), { code: 'ENOENT' }));
+
+    await expect(encryptKeys(sshDir, keysDir, tmpDir, PUBKEY)).rejects.toThrow(
+      '`age` was not found on PATH'
+    );
+  });
+
   it('ignores public keys and unrelated files when building the list', async () => {
     fs.writeFileSync(path.join(sshDir, 'known_hosts'), '');
     fs.writeFileSync(path.join(sshDir, 'id_orphan.pub'), 'PUBLIC');
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(messages(logSpy)).toContain('No private SSH keys found to encrypt.');
   });
@@ -81,7 +108,7 @@ describe('encryptKeys', () => {
     key(tmpDir, 'id_stage', 'tmp');
     prompt.mockResolvedValue({ selectedKeys: [] });
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(choices()).toEqual(['id_prod', 'id_stage']);
   });
@@ -90,9 +117,9 @@ describe('encryptKeys', () => {
     key(sshDir, 'id_prod', 'ssh');
     prompt.mockResolvedValue({ selectedKeys: ['id_prod'] });
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
-    const vaultPath = path.join(vaultDir, 'keys', 'prod');
+    const vaultPath = path.join(keysDir, 'prod');
     expect(execa).toHaveBeenCalledWith('age', [
       '-r',
       PUBKEY,
@@ -109,12 +136,10 @@ describe('encryptKeys', () => {
     key(tmpDir, 'id_prod', 'tmp');
     prompt.mockResolvedValue({ selectedKeys: ['id_prod'] });
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(execa.mock.calls[0][1]).toContain(path.join(tmpDir, 'id_prod'));
-    expect(fs.readFileSync(path.join(vaultDir, 'keys', 'prod', 'id_prod.pub'), 'utf-8')).toBe(
-      'PUBLIC tmp'
-    );
+    expect(fs.readFileSync(path.join(keysDir, 'prod', 'id_prod.pub'), 'utf-8')).toBe('PUBLIC tmp');
   });
 
   it('encrypts every selected key', async () => {
@@ -122,20 +147,125 @@ describe('encryptKeys', () => {
     key(sshDir, 'id_stage', 'ssh');
     prompt.mockResolvedValue({ selectedKeys: ['id_prod', 'id_stage'] });
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(execa).toHaveBeenCalledTimes(2);
-    expect(fs.existsSync(path.join(vaultDir, 'keys', 'prod', 'id_prod.age'))).toBe(true);
-    expect(fs.existsSync(path.join(vaultDir, 'keys', 'stage', 'id_stage.age'))).toBe(true);
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(true);
+    expect(fs.existsSync(path.join(keysDir, 'stage', 'id_stage.age'))).toBe(true);
   });
 
   it('does nothing when the selection is empty', async () => {
     key(sshDir, 'id_prod', 'ssh');
     prompt.mockResolvedValue({ selectedKeys: [] });
 
-    await encryptKeys(sshDir, vaultDir, tmpDir, PUBKEY);
+    await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
 
     expect(execa).not.toHaveBeenCalled();
-    expect(fs.existsSync(path.join(vaultDir, 'keys'))).toBe(false);
+    expect(fs.existsSync(keysDir)).toBe(false);
+  });
+
+  describe('a key with no .pub file', () => {
+    /** A private key without its sibling — what the selection list offers anyway. */
+    const orphan = (dir: string, name: string) => {
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, name), `PRIVATE ${name}`);
+    };
+
+    it('derives the public key with ssh-keygen', async () => {
+      orphan(sshDir, 'id_prod');
+      prompt.mockResolvedValue({ selectedKeys: ['id_prod'] });
+      execa.mockImplementation(async (binary: string, args: string[]) => {
+        if (binary === 'ssh-keygen') return { stdout: 'ssh-ed25519 AAAA derived' };
+        fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+        return { stdout: '' };
+      });
+
+      await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+      expect(execa).toHaveBeenCalledWith(
+        'ssh-keygen',
+        ['-y', '-f', path.join(sshDir, 'id_prod')],
+        // stderr inherited so the passphrase prompt is visible, stdout piped so
+        // the derived key can be captured.
+        { stdio: ['inherit', 'pipe', 'inherit'] }
+      );
+      expect(fs.readFileSync(path.join(keysDir, 'prod', 'id_prod.pub'), 'utf-8')).toBe(
+        'ssh-ed25519 AAAA derived\n'
+      );
+    });
+
+    it('stores the private key alone when the derivation fails', async () => {
+      orphan(sshDir, 'id_prod');
+      prompt.mockResolvedValue({ selectedKeys: ['id_prod'] });
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+      execa.mockImplementation(async (binary: string, args: string[]) => {
+        if (binary === 'ssh-keygen') {
+          throw Object.assign(new Error('bad passphrase'), { stderr: 'incorrect passphrase' });
+        }
+        fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+        return { stdout: '' };
+      });
+
+      await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+      // The encrypted key is what matters; the .pub is recoverable from it later.
+      expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(true);
+      expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.pub'))).toBe(false);
+      expect(messages(warnSpy)).toContain('no public key could be derived');
+    });
+  });
+
+  describe('when one key of several fails', () => {
+    beforeEach(() => {
+      key(sshDir, 'id_prod', 'ssh');
+      key(sshDir, 'id_stage', 'ssh');
+      prompt.mockResolvedValue({ selectedKeys: ['id_prod', 'id_stage'] });
+      // age refuses the first key only.
+      execa.mockImplementation(async (_binary: string, args: string[]) => {
+        if (args.some((arg) => arg.endsWith('id_prod'))) {
+          throw Object.assign(new Error('age refused'), { stderr: 'no identity' });
+        }
+        fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+        return { stdout: '' };
+      });
+    });
+
+    it('still encrypts the rest', async () => {
+      await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+      expect(fs.existsSync(path.join(keysDir, 'stage', 'id_stage.age'))).toBe(true);
+    });
+
+    it('reports which keys were not stored', async () => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+      await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+      expect(messages(errorSpy)).toContain('id_prod');
+      expect(messages(logSpy)).toContain('1 of 2 selected keys were not stored: id_prod');
+    });
+
+    it('leaves no vault entry for the key that failed', async () => {
+      await encryptKeys(sshDir, keysDir, tmpDir, PUBKEY);
+
+      // Not even an empty directory: list counts a directory with an .age in it,
+      // and a truncated .age would be offered for decryption.
+      expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+    });
+  });
+
+  it('gives up immediately when age is not installed', async () => {
+    key(sshDir, 'id_prod', 'ssh');
+    key(sshDir, 'id_stage', 'ssh');
+    prompt.mockResolvedValue({ selectedKeys: ['id_prod', 'id_stage'] });
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('spawn age ENOENT'), { code: 'ENOENT' });
+    });
+
+    // Not a per-key failure: nine more identical errors help nobody.
+    await expect(encryptKeys(sshDir, keysDir, tmpDir, PUBKEY)).rejects.toThrow(
+      '`age` was not found on PATH'
+    );
+    expect(execa).toHaveBeenCalledTimes(1);
   });
 });

packages/keyman/tests/generate.test.ts

@@ -42,6 +42,10 @@ describe('generateKey', () => {
   const argsOf = (binary: string) =>
     execa.mock.calls.find((c) => c[0] === binary)?.[1] as string[] | undefined;
 
+  /** The options of the mocked call to `binary`. */
+  const optionsOf = (binary: string) =>
+    execa.mock.calls.find((c) => c[0] === binary)?.[2] as { stdio?: unknown } | undefined;
+
   const messages = (spy: ReturnType<typeof vi.spyOn>) =>
     spy.mock.calls.map((c) => c.join(' ')).join('\n');
 
@@ -64,7 +68,7 @@ describe('generateKey', () => {
       return { exitCode: 0 };
     });
 
-    answer({ algorithm: 'ed25519', keyName: 'prod', password: 'pw', identity: 'me@host' });
+    answer({ algorithm: 'ed25519', keyName: 'prod', identity: 'me@host' });
   });
 
   afterEach(() => {
@@ -80,16 +84,24 @@ describe('generateKey', () => {
       'ed25519',
       '-f',
       path.join(tmpDir, 'id_prod'),
-      '-N',
-      'pw',
       '-C',
       'me@host',
     ]);
     expect(messages(logSpy)).toContain('Key generated');
   });
 
+  it('never handles the passphrase itself', async () => {
+    await generateKey(tmpDir, keysDir, PUBKEY);
+
+    // No -N, so ssh-keygen prompts and confirms; inherited stdio is what makes
+    // that prompt reach the terminal. The passphrase never touches argv.
+    expect(argsOf('ssh-keygen')).not.toContain('-N');
+    expect(optionsOf('ssh-keygen')).toEqual({ stdio: 'inherit' });
+    expect(prompt.mock.calls.map((c) => c[0][0].name)).not.toContain('password');
+  });
+
   it('does not prefix a key name that already starts with id_', async () => {
-    answer({ algorithm: 'ed25519', keyName: 'id_prod', password: '', identity: '' });
+    answer({ algorithm: 'ed25519', keyName: 'id_prod', identity: '' });
 
     await generateKey(tmpDir, keysDir, PUBKEY);
 
@@ -97,7 +109,7 @@ describe('generateKey', () => {
   });
 
   it('requests a 4096 bit key for rsa', async () => {
-    answer({ algorithm: 'rsa', keyName: 'prod', password: '', identity: '' });
+    answer({ algorithm: 'rsa', keyName: 'prod', identity: '' });
 
     await generateKey(tmpDir, keysDir, PUBKEY);
 
@@ -139,17 +151,22 @@ describe('generateKey', () => {
     expect(fs.readFileSync(path.join(tmpDir, 'id_prod'), 'utf-8')).toBe('EXISTING');
   });
 
-  it('reports a failure from ssh-keygen without leaving a vault entry', async () => {
-    execa.mockRejectedValue(new Error('ssh-keygen exploded'));
+  it('reports a failure from ssh-keygen without reaching age', async () => {
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('ssh-keygen exploded'), { stderr: 'ssh-keygen exploded' });
+    });
 
     await expect(generateKey(tmpDir, keysDir, PUBKEY)).resolves.toBeUndefined();
-    expect(messages(errorSpy)).toContain('Error generating/encrypting key');
+    expect(messages(errorSpy)).toContain('Error generating key');
+    expect(argsOf('age')).toBeUndefined();
     expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
   });
 
-  it('reports a failure from age', async () => {
+  it('reports a failure from age and says the key is still there to encrypt', async () => {
     execa.mockImplementation(async (binary: string, args: string[]) => {
-      if (binary === 'age') throw new Error('age exploded');
+      if (binary === 'age') {
+        throw Object.assign(new Error('age exploded'), { stderr: 'age exploded' });
+      }
       const keyPath = args[args.indexOf('-f') + 1];
       fs.writeFileSync(keyPath, 'PRIVATE');
       fs.writeFileSync(`${keyPath}.pub`, 'ssh-ed25519 AAAA generated');
@@ -158,7 +175,11 @@ describe('generateKey', () => {
 
     await generateKey(tmpDir, keysDir, PUBKEY);
 
-    expect(messages(errorSpy)).toContain('Error generating/encrypting key');
-    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.pub'))).toBe(false);
+    expect(messages(errorSpy)).toContain('Error encrypting key');
+    // The generated key is the thing of value, and it survived.
+    expect(fs.existsSync(path.join(tmpDir, 'id_prod'))).toBe(true);
+    expect(messages(errorSpy)).toContain(path.join(tmpDir, 'id_prod'));
+    // And no half-made vault entry was left claiming to hold it.
+    expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
   });
 });

packages/keyman/tests/home.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Tests for home directory resolution.
+ *
+ * Real directories under os.tmpdir() stand in for home directories, since the
+ * whole point of the module is that it checks whether a path exists rather than
+ * assuming a layout.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { CURRENT_USER, resolveHomeDir } from '../src/keyman.home.js';
+
+describe('resolveHomeDir', () => {
+  let homes: string;
+  let originalHome: string | undefined;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  const messages = () => errorSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  beforeEach(() => {
+    originalHome = process.env.HOME;
+    homes = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-homes-')));
+    process.env.HOME = path.join(homes, 'alice');
+    fs.mkdirSync(process.env.HOME, { recursive: true });
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+    fs.rmSync(homes, { recursive: true, force: true });
+  });
+
+  describe('the current user', () => {
+    it('uses HOME when it is set', () => {
+      expect(resolveHomeDir(CURRENT_USER)).toBe(path.join(homes, 'alice'));
+    });
+
+    it('falls back to the passwd entry when HOME is unset', () => {
+      delete process.env.HOME;
+
+      // Not asserted as a literal: what matters is that an unset HOME is no longer
+      // a fatal error, which is what `process.env.HOME || ''` made it.
+      expect(resolveHomeDir(CURRENT_USER)).toBe(os.userInfo().homedir);
+    });
+
+    it('reports the failure when neither is available', () => {
+      delete process.env.HOME;
+      vi.spyOn(os, 'userInfo').mockImplementation(() => {
+        throw new Error('no passwd entry for uid');
+      });
+
+      expect(resolveHomeDir(CURRENT_USER)).toBeNull();
+      expect(messages()).toContain('Unable to determine HOME directory');
+    });
+
+    it('treats an empty passwd home as no answer', () => {
+      delete process.env.HOME;
+      vi.spyOn(os, 'userInfo').mockReturnValue({
+        ...os.userInfo(),
+        homedir: '',
+      });
+
+      expect(resolveHomeDir(CURRENT_USER)).toBeNull();
+    });
+  });
+
+  describe('another user', () => {
+    it('looks beside the current home, whatever that directory is called', () => {
+      const bob = path.join(homes, 'bob');
+      fs.mkdirSync(bob);
+
+      // The old code hardcoded /home/<user>, which is wrong on macOS — where homes
+      // live in /Users — and on any host that puts them anywhere else.
+      expect(resolveHomeDir('bob')).toBe(bob);
+    });
+
+    it('still tries the conventional locations with no current home to go by', () => {
+      delete process.env.HOME;
+      vi.spyOn(os, 'userInfo').mockImplementation(() => {
+        throw new Error('no passwd entry for uid');
+      });
+
+      // Not knowing where *this* user lives is no reason to give up on another.
+      expect(resolveHomeDir('nobody')).toBeNull();
+      expect(messages()).toContain('/home/nobody, /Users/nobody');
+      expect(messages()).not.toContain('Unable to determine HOME');
+    });
+
+    it('reports every path it tried when there is no such home', () => {
+      expect(resolveHomeDir('nobody')).toBeNull();
+
+      expect(messages()).toContain('No home directory found for nobody');
+      expect(messages()).toContain(path.join(homes, 'nobody'));
+      expect(messages()).toContain('/home/nobody');
+      expect(messages()).toContain('/Users/nobody');
+    });
+
+    it('still checks the conventional locations when HOME is somewhere odd', () => {
+      process.env.HOME = path.join(homes, 'alice');
+      const conventional = process.platform === 'darwin' ? '/Users' : '/home';
+      const existing = fs
+        .readdirSync(conventional)
+        .find((entry) =>
+          fs.statSync(path.join(conventional, entry), { throwIfNoEntry: false })?.isDirectory()
+        );
+
+      // Skipped rather than asserted blind if the machine has no such user.
+      if (existing) {
+        expect(resolveHomeDir(existing)).toBe(path.join(conventional, existing));
+      }
+    });
+  });
+});

packages/keyman/tests/keys.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Tests for private key discovery.
+ *
+ * Real files, because the classification is a bounded read of a real header.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { reportSkippedKeys, scanPrivateKeys } from '../src/keyman.keys.js';
+
+const OPENSSH = '-----BEGIN OPENSSH PRIVATE KEY-----\nb3BlbnNzaC1rZXk\n';
+const RSA_PEM = '-----BEGIN RSA PRIVATE KEY-----\nProc-Type: 4,ENCRYPTED\n';
+const PKCS8 = '-----BEGIN PRIVATE KEY-----\nMIIB\n';
+
+describe('scanPrivateKeys', () => {
+  let dir: string;
+
+  const write = (name: string, contents: string) =>
+    fs.writeFileSync(path.join(dir, name), contents);
+
+  beforeEach(() => {
+    dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-keys-')));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns nothing for a directory that does not exist', () => {
+    expect(scanPrivateKeys(path.join(dir, 'nope'))).toEqual({ keys: [], skipped: [] });
+  });
+
+  it('offers the id_ keys and not their public halves', () => {
+    write('id_prod', OPENSSH);
+    write('id_prod.pub', 'ssh-ed25519 AAAA');
+
+    expect(scanPrivateKeys(dir)).toEqual({ keys: ['id_prod'], skipped: [] });
+  });
+
+  it('sorts the keys, so the menu order does not come from the filesystem', () => {
+    for (const name of ['id_stage', 'id_alpha', 'id_prod']) {
+      write(name, OPENSSH);
+    }
+
+    expect(scanPrivateKeys(dir).keys).toEqual(['id_alpha', 'id_prod', 'id_stage']);
+  });
+
+  it('offers an id_ file without checking what is in it', () => {
+    // Unchanged from before the scan existed: whatever was offered still is.
+    write('id_prod', 'not a key at all');
+
+    expect(scanPrivateKeys(dir).keys).toEqual(['id_prod']);
+  });
+
+  it.each([
+    ['an OpenSSH key', OPENSSH],
+    ['an encrypted PEM key', RSA_PEM],
+    ['a PKCS#8 key', PKCS8],
+  ])('reports %s that is not named id_*', (_label, contents) => {
+    write('deploy_ed25519', contents);
+
+    expect(scanPrivateKeys(dir)).toEqual({ keys: [], skipped: ['deploy_ed25519'] });
+  });
+
+  it('ignores the other files a .ssh directory is full of', () => {
+    write('known_hosts', 'github.com ssh-ed25519 AAAA');
+    write('config', 'Host *\n  AddKeysToAgent yes\n');
+    write('authorized_keys', 'ssh-ed25519 AAAA');
+    fs.mkdirSync(path.join(dir, 'sockets'));
+
+    expect(scanPrivateKeys(dir)).toEqual({ keys: [], skipped: [] });
+  });
+
+  it('ignores a path it cannot read', () => {
+    // A dangling symlink, not a 0o000 file: root reads a 0o000 file happily, so
+    // the mode-based version of this passed here and failed on the CI runner,
+    // which is a container running as root. ENOENT nobody can override.
+    fs.symlinkSync(path.join(dir, 'gone'), path.join(dir, 'secret'));
+
+    // Reported as not-a-key rather than crashing the menu it was building.
+    expect(scanPrivateKeys(dir).skipped).toEqual([]);
+  });
+
+  it('does not read past the header', () => {
+    // The marker is in the first line; a mention further down is not a key.
+    write('decoy', `${'x'.repeat(200)}\nPRIVATE KEY-----\n`);
+
+    expect(scanPrivateKeys(dir).skipped).toEqual([]);
+  });
+});
+
+describe('reportSkippedKeys', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  const messages = () => logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  beforeEach(() => {
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('says nothing when nothing was skipped', () => {
+    reportSkippedKeys([], '/home/alice/.ssh');
+
+    expect(logSpy).not.toHaveBeenCalled();
+  });
+
+  it('names the keys, the directory and the reason', () => {
+    reportSkippedKeys(['deploy_ed25519', 'backup_rsa'], '/home/alice/.ssh');
+
+    expect(messages()).toContain('deploy_ed25519, backup_rsa');
+    expect(messages()).toContain('/home/alice/.ssh');
+    expect(messages()).toContain('2 private keys');
+    // Without the reason the message is a complaint rather than an instruction.
+    expect(messages()).toContain('rename');
+  });
+
+  it('says key, singular, for one of them', () => {
+    reportSkippedKeys(['deploy_ed25519'], '/home/alice/.ssh');
+
+    expect(messages()).toContain('1 private key ');
+  });
+});

packages/keyman/tests/list.test.ts

@@ -182,6 +182,25 @@ describe('listKeys', () => {
     expect(row('id_real')).toBeDefined();
   });
 
+  it('keeps listing when the vault holds a dangling symlink', async () => {
+    vaultKey('real');
+    fs.symlinkSync(path.join(root, 'gone'), path.join(vaultDir, 'broken'));
+
+    await expect(listKeys(sshDir, vaultDir, tmpDir)).resolves.toBeUndefined();
+    expect(row('id_real')).toBeDefined();
+  });
+
+  it('follows a symlink pointing at a real vault directory', async () => {
+    const elsewhere = path.join(root, 'elsewhere', 'prod');
+    touch(elsewhere, 'id_prod.age');
+    fs.mkdirSync(vaultDir, { recursive: true });
+    fs.symlinkSync(elsewhere, path.join(vaultDir, 'prod'));
+
+    await listKeys(sshDir, vaultDir, tmpDir);
+
+    expect(row('id_prod')).toBeDefined();
+  });
+
   it('ignores loose files sitting next to the vault directories', async () => {
     vaultKey('real');
     fs.writeFileSync(path.join(vaultDir, 'README.md'), '');

packages/keyman/tests/main.test.ts

@@ -19,6 +19,8 @@ const {
   generateKey,
   encryptKeys,
   decryptKeys,
+  rotateKey,
+  retireKey,
   extractAgePublicKey,
 } = vi.hoisted(() => ({
   prompt: vi.fn(),
@@ -29,6 +31,8 @@ const {
   generateKey: vi.fn(),
   encryptKeys: vi.fn(),
   decryptKeys: vi.fn(),
+  rotateKey: vi.fn(),
+  retireKey: vi.fn(),
   extractAgePublicKey: vi.fn(),
 }));
 
@@ -39,6 +43,7 @@ vi.mock('../src/keyman.copy.js', () => ({ copyKey }));
 vi.mock('../src/keyman.generate.js', () => ({ generateKey }));
 vi.mock('../src/keyman.encrypt.js', () => ({ encryptKeys }));
 vi.mock('../src/keyman.decrypt.js', () => ({ decryptKeys }));
+vi.mock('../src/keyman.rotate.js', () => ({ rotateKey, retireKey }));
 vi.mock('../src/keyman.utils.js', () => ({ extractAgePublicKey }));
 
 import { keyman } from '../src/keyman.main.js';
@@ -81,7 +86,7 @@ describe('keyman', () => {
       ageKeyFile: 'age.key',
     });
     resolveConfigPaths.mockReturnValue(paths);
-    extractAgePublicKey.mockReturnValue('age1recipient');
+    extractAgePublicKey.mockResolvedValue('age1recipient');
 
     logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
@@ -106,6 +111,17 @@ describe('keyman', () => {
     expect(output()).toContain(paths.keyPath);
     expect(fs.existsSync(paths.vaultRoot)).toBe(true);
     expect(fs.existsSync(paths.tmpDir)).toBe(true);
+    // keysDir too: decrypt reads it, and nothing created it before the first
+    // encrypt, so a fresh vault could not be decrypted from.
+    expect(fs.existsSync(paths.keysDir)).toBe(true);
+  });
+
+  it('creates the vault directories private to the owner', async () => {
+    await keyman();
+
+    for (const dir of [paths.vaultRoot, paths.keysDir, paths.tmpDir]) {
+      expect(fs.statSync(dir).mode & 0o777, dir).toBe(0o700);
+    }
   });
 
   it('quits without running any operation', async () => {
@@ -125,6 +141,9 @@ describe('keyman', () => {
       'generate',
       'encrypt',
       'decrypt',
+      'rotate',
+      'retire',
+      'clear',
       'quit',
     ]);
   });
@@ -161,31 +180,110 @@ describe('keyman', () => {
     expect(generateKey).toHaveBeenCalledWith(paths.tmpDir, paths.keysDir, 'age1recipient');
   });
 
-  it('encrypts keys into the vault root', async () => {
+  it('encrypts keys into the configured keys directory', async () => {
     menu(['encrypt']);
 
     await keyman();
 
     expect(encryptKeys).toHaveBeenCalledWith(
       path.join(process.env.HOME as string, '.ssh'),
-      paths.vaultRoot,
+      paths.keysDir,
       paths.tmpDir,
       'age1recipient'
     );
   });
 
-  it('decrypts keys using the age identity file', async () => {
+  it('decrypts from the configured keys directory using the age identity file', async () => {
     menu(['decrypt']);
 
     await keyman();
 
     expect(decryptKeys).toHaveBeenCalledWith(
       path.join(process.env.HOME as string, '.ssh'),
-      paths.vaultRoot,
+      paths.keysDir,
+      paths.tmpDir,
       paths.keyPath
     );
   });
 
+  it('rotates a key with the age recipient, against the same directories', async () => {
+    menu(['rotate']);
+
+    await keyman();
+
+    expect(rotateKey).toHaveBeenCalledWith(
+      path.join(process.env.HOME as string, '.ssh'),
+      paths.keysDir,
+      paths.tmpDir,
+      'age1recipient'
+    );
+  });
+
+  it('retires a key without needing a recipient', async () => {
+    menu(['retire']);
+
+    await keyman();
+
+    expect(retireKey).toHaveBeenCalledWith(
+      path.join(process.env.HOME as string, '.ssh'),
+      paths.keysDir,
+      paths.tmpDir
+    );
+    // Retiring only deletes, so it works with no age identity at all.
+    expect(extractAgePublicKey).not.toHaveBeenCalled();
+  });
+
+  describe('without an age recipient', () => {
+    beforeEach(() => {
+      extractAgePublicKey.mockResolvedValue(null);
+    });
+
+    it.each([
+      ['generate', generateKey],
+      ['encrypt', encryptKeys],
+      ['rotate', rotateKey],
+    ])('refuses %s with a remedy instead of passing null to age', async (choice, operation) => {
+      menu([choice]);
+
+      await keyman();
+
+      expect(operation).not.toHaveBeenCalled();
+      const reported = errorSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+      expect(reported).toContain(`age-keygen -o ${paths.keyPath}`);
+      // The whole point: the loop survives and quit is still reached.
+      expect(output()).toContain('Goodbye!');
+    });
+
+    it('still allows the operations that need no recipient', async () => {
+      menu(['list', 'decrypt', 'retire']);
+
+      await keyman();
+
+      expect(listKeys).toHaveBeenCalled();
+      expect(decryptKeys).toHaveBeenCalled();
+      expect(retireKey).toHaveBeenCalled();
+    });
+
+    it('retries the lookup, so creating the identity mid-session works', async () => {
+      extractAgePublicKey.mockResolvedValueOnce(null).mockResolvedValueOnce('age1later');
+      menu(['generate', 'generate']);
+
+      await keyman();
+
+      expect(extractAgePublicKey).toHaveBeenCalledTimes(2);
+      expect(generateKey).toHaveBeenCalledTimes(1);
+      expect(generateKey).toHaveBeenCalledWith(paths.tmpDir, paths.keysDir, 'age1later');
+    });
+  });
+
+  it('resolves the recipient once for repeated operations', async () => {
+    menu(['generate', 'encrypt']);
+
+    await keyman();
+
+    expect(extractAgePublicKey).toHaveBeenCalledTimes(1);
+  });
+
   it('keeps showing the menu until the user quits', async () => {
     menu(['list', 'copy', 'list']);
 
@@ -196,21 +294,55 @@ describe('keyman', () => {
   });
 
   it('targets another user home directory when a user is named', async () => {
+    // A real sibling of the current HOME, because resolveHomeDir checks that the
+    // directory exists rather than assuming a layout.
+    const deployHome = path.join(root, 'deploy');
+    fs.mkdirSync(deployHome, { recursive: true });
     menu(['list'], 'deploy');
 
     await keyman();
 
-    expect(listKeys).toHaveBeenCalledWith('/home/deploy/.ssh', paths.keysDir, paths.tmpDir);
+    expect(listKeys).toHaveBeenCalledWith(
+      path.join(deployHome, '.ssh'),
+      paths.keysDir,
+      paths.tmpDir
+    );
   });
 
-  it('aborts when the home directory cannot be determined', async () => {
-    delete process.env.HOME;
+  it('aborts when the named user has no home directory', async () => {
+    menu(['list'], 'nobody-at-all');
     const exit = vi.spyOn(process, 'exit').mockImplementation(() => {
       throw new Error('process.exit');
     });
 
     await expect(keyman()).rejects.toThrow('process.exit');
     expect(exit).toHaveBeenCalledWith(1);
-    expect(errorSpy.mock.calls[0][0]).toContain('Unable to determine HOME directory');
+    expect(errorSpy.mock.calls[0][0]).toContain('No home directory found');
+  });
+
+  it('writes a .gitignore next to the vault so it cannot be committed', async () => {
+    await keyman();
+
+    const contents = fs.readFileSync(path.join(paths.vaultRoot, '.gitignore'), 'utf-8');
+    // The README used to ask the user to do this by hand.
+    expect(contents).toContain('age.key');
+    expect(contents).toContain('tmp/');
+  });
+
+  it('clears the decrypted keys on request', async () => {
+    fs.mkdirSync(paths.tmpDir, { recursive: true });
+    fs.writeFileSync(path.join(paths.tmpDir, 'id_prod'), 'PRIVATE');
+    // Not the `menu` helper: this one has to answer the confirmation too.
+    const queue = ['clear', 'quit'];
+    prompt.mockImplementation(async (questions: { name: string }[]) => {
+      const { name } = questions[0];
+      if (name === 'user') return { user: '@current' };
+      if (name === 'confirmed') return { confirmed: true };
+      return { category: queue.shift() };
+    });
+
+    await keyman();
+
+    expect(fs.existsSync(path.join(paths.tmpDir, 'id_prod'))).toBe(false);
   });
 });

packages/keyman/tests/readme.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The README is the only document that ships (`package.json` files: dist,
+ * README.md, LICENSE), so a reader on the registry sees it and nothing else. It
+ * had drifted to describing four of the menu's entries and none of the command
+ * line; these assertions are the parts that can drift again silently.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { helpText } from '../src/keyman.args.js';
+
+const README = fs.readFileSync(path.join(import.meta.dirname, '..', 'README.md'), 'utf-8');
+
+describe('README', () => {
+  it('quotes --help verbatim', () => {
+    // Copied rather than described, and checked rather than trusted: a flag added
+    // to helpText() now fails here instead of shipping undocumented.
+    expect(README).toContain(helpText().trim());
+  });
+
+  it('documents every menu operation', () => {
+    const main = fs.readFileSync(
+      path.join(import.meta.dirname, '..', 'src', 'keyman.main.ts'),
+      'utf-8'
+    );
+    const labels = [...main.matchAll(/\{ name: '([^']+)', value: '[a-z]+' \}/g)].map((m) => m[1]);
+
+    // The labels themselves, emoji included, so a renamed entry is caught too —
+    // but with runs of whitespace collapsed, because some of them carry a second
+    // space to align a variation-selector emoji in a terminal, and prose should
+    // not have to reproduce that.
+    const collapse = (text: string) => text.replace(/\s+/g, ' ');
+    const readme = collapse(README);
+
+    expect(labels.length).toBe(9);
+    for (const label of labels) {
+      expect(readme, label).toContain(collapse(label));
+    }
+  });
+
+  it('documents every configuration key', () => {
+    for (const key of ['vaultRoot', 'keysDir', 'tmpDir', 'ageKeyFile']) {
+      expect(README, key).toContain(key);
+    }
+  });
+});

packages/keyman/tests/rotate.test.ts

@@ -0,0 +1,471 @@
+/**
+ * Tests for rotation and retirement.
+ *
+ * ssh-keygen and age are mocked; the ssh-keygen stand-in writes the pair the real
+ * binary would, so the vault write is a real one. Everything the operations claim
+ * about the filesystem is asserted against the filesystem.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execa, prompt } = vi.hoisted(() => ({ execa: vi.fn(), prompt: vi.fn() }));
+
+vi.mock('execa', () => ({ execa }));
+vi.mock('inquirer', () => ({ default: { prompt } }));
+
+import { nextRotationName, retireKey, rotateKey, supersededBy } from '../src/keyman.rotate.js';
+
+describe('nextRotationName', () => {
+  it('starts a series at 2, so the first key keeps its plain name', () => {
+    expect(nextRotationName('prod', ['prod'])).toBe('prod-2');
+  });
+
+  it('continues an existing series', () => {
+    expect(nextRotationName('prod-2', ['prod', 'prod-2'])).toBe('prod-3');
+  });
+
+  it('skips past a version that already exists', () => {
+    // Rotating the original again after prod-2 and prod-3 exist: -2 is taken.
+    expect(nextRotationName('prod', ['prod', 'prod-2', 'prod-3'])).toBe('prod-4');
+  });
+
+  it('ignores other series', () => {
+    expect(nextRotationName('prod', ['prod', 'stage-7', 'prod-backup'])).toBe('prod-2');
+  });
+
+  it('treats a name that ends in a number as its own series', () => {
+    // `web2` is a host name, not a version — the separator is what makes a series.
+    expect(nextRotationName('web2', ['web2'])).toBe('web2-2');
+  });
+
+  it('keeps a hyphenated base intact', () => {
+    expect(nextRotationName('build-agent', ['build-agent'])).toBe('build-agent-2');
+    expect(nextRotationName('build-agent-2', ['build-agent-2'])).toBe('build-agent-3');
+  });
+});
+
+describe('supersededBy', () => {
+  it('finds the replacement of a key', () => {
+    expect(supersededBy('prod', ['prod', 'prod-2'])).toBe('prod-2');
+  });
+
+  it('answers with the latest one', () => {
+    expect(supersededBy('prod', ['prod', 'prod-2', 'prod-3'])).toBe('prod-3');
+  });
+
+  it('says nothing supersedes the newest key in a series', () => {
+    expect(supersededBy('prod-3', ['prod', 'prod-2', 'prod-3'])).toBeNull();
+  });
+
+  it('does not count an unrelated key', () => {
+    expect(supersededBy('prod', ['prod', 'stage-9'])).toBeNull();
+  });
+});
+
+describe('rotateKey', () => {
+  let root: string;
+  let sshDir: string;
+  let keysDir: string;
+  let tmpDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  const PUBKEY = 'age1recipient';
+
+  /** Creates <keysDir>/<name>/id_<name>.{age,pub}. */
+  const vaultKey = (name: string, comment = 'me@host') => {
+    const dir = path.join(keysDir, name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `id_${name}.age`), `ENCRYPTED ${name}`);
+    fs.writeFileSync(path.join(dir, `id_${name}.pub`), `ssh-ed25519 AAAA${name} ${comment}\n`);
+  };
+
+  /** Answers each prompt by the name of the question it asks. */
+  const answer = (answers: Record<string, unknown>) => {
+    prompt.mockImplementation(async (questions: { name: string }[]) => {
+      const { name } = questions[0];
+      return { [name]: answers[name] };
+    });
+  };
+
+  const question = (name: string) =>
+    prompt.mock.calls.map((c) => c[0][0]).find((q) => q.name === name);
+
+  const argsOf = (binary: string) =>
+    execa.mock.calls.find((c) => c[0] === binary)?.[1] as string[] | undefined;
+
+  const messages = (spy: ReturnType<typeof vi.spyOn>) =>
+    spy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-rotate-')));
+    sshDir = path.join(root, '.ssh');
+    keysDir = path.join(root, 'vault', 'keys');
+    tmpDir = path.join(root, 'vault', 'tmp');
+    fs.mkdirSync(keysDir, { recursive: true });
+    fs.mkdirSync(sshDir, { recursive: true });
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    execa.mockImplementation(async (binary: string, args: string[]) => {
+      if (binary === 'ssh-keygen') {
+        const keyPath = args[args.indexOf('-f') + 1];
+        fs.writeFileSync(keyPath, 'PRIVATE');
+        fs.writeFileSync(`${keyPath}.pub`, `ssh-ed25519 NEWKEY ${args[args.indexOf('-C') + 1]}\n`);
+      }
+      if (binary === 'age') {
+        // Written, not just recorded: what the vault ends up holding is the thing
+        // under test, and a later listing has to see the new entry.
+        fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+      }
+      return { exitCode: 0 };
+    });
+
+    answer({ key: 'prod', algorithm: 'ed25519', identity: 'me@host' });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('says there is nothing to rotate on an empty vault', async () => {
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(messages(logSpy)).toContain('No encrypted keys to rotate');
+    expect(prompt).not.toHaveBeenCalled();
+  });
+
+  it('offers the vault keys', async () => {
+    vaultKey('stage');
+    vaultKey('prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(question('key').choices).toEqual(['prod', 'stage']);
+  });
+
+  it('generates the replacement into the tmp directory under the next name', async () => {
+    vaultKey('prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(argsOf('ssh-keygen')).toEqual([
+      '-t',
+      'ed25519',
+      '-f',
+      path.join(tmpDir, 'id_prod-2'),
+      '-C',
+      'me@host',
+    ]);
+  });
+
+  it('leaves the rotated key untouched in the vault', async () => {
+    vaultKey('prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    // The whole point of rotating this way: both keys are in the vault, and the
+    // one that is deployed is byte for byte what it was.
+    expect(fs.readFileSync(path.join(keysDir, 'prod', 'id_prod.age'), 'utf-8')).toBe(
+      'ENCRYPTED prod'
+    );
+    expect(fs.existsSync(path.join(keysDir, 'prod-2', 'id_prod-2.age'))).toBe(true);
+  });
+
+  it('encrypts the replacement to the vault recipient', async () => {
+    vaultKey('prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(argsOf('age')).toEqual([
+      '-r',
+      PUBKEY,
+      '-o',
+      path.join(keysDir, 'prod-2', 'id_prod-2.age'),
+      path.join(tmpDir, 'id_prod-2'),
+    ]);
+  });
+
+  it('offers the comment of the key being replaced', async () => {
+    vaultKey('prod', 'deploy@prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(question('identity').default).toBe('deploy@prod');
+  });
+
+  it('offers no comment when the stored public key has none', async () => {
+    vaultKey('prod');
+    fs.writeFileSync(path.join(keysDir, 'prod', 'id_prod.pub'), 'ssh-ed25519 AAAAprod\n');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(question('identity').default).toBeUndefined();
+  });
+
+  it('rotates a key whose public half was never stored', async () => {
+    vaultKey('prod');
+    fs.rmSync(path.join(keysDir, 'prod', 'id_prod.pub'));
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(question('identity').default).toBeUndefined();
+    // Reported rather than printed as a blank line, since the user needs it to
+    // know what to remove from the host afterwards.
+    expect(messages(logSpy)).toContain('none stored at');
+    expect(fs.existsSync(path.join(keysDir, 'prod-2', 'id_prod-2.age'))).toBe(true);
+  });
+
+  it('prints both public keys and what to do with them', async () => {
+    vaultKey('prod', 'deploy@prod');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    const output = messages(logSpy);
+    expect(output).toContain('ssh-ed25519 AAAAprod deploy@prod');
+    expect(output).toContain('ssh-ed25519 NEWKEY me@host');
+    // Deploy-then-retire, in that order: the reverse locks you out.
+    expect(output).toContain('Add the replacement public key');
+    expect(output).toContain('retire');
+  });
+
+  it('skips a name taken by a plaintext key outside the vault', async () => {
+    vaultKey('prod');
+    fs.writeFileSync(path.join(sshDir, 'id_prod-2'), 'PRIVATE');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    // Generating id_prod-2 would have refused, or worse asked ssh-keygen to
+    // overwrite a private key that is in use.
+    expect(argsOf('ssh-keygen')).toContain(path.join(tmpDir, 'id_prod-3'));
+    expect(fs.readFileSync(path.join(sshDir, 'id_prod-2'), 'utf-8')).toBe('PRIVATE');
+  });
+
+  it('skips a name taken by an earlier rotation still in tmp', async () => {
+    vaultKey('prod');
+    fs.mkdirSync(tmpDir, { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'id_prod-2'), 'PRIVATE');
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(argsOf('ssh-keygen')).toContain(path.join(tmpDir, 'id_prod-3'));
+  });
+
+  it('requests a 4096 bit key for rsa', async () => {
+    vaultKey('prod');
+    answer({ key: 'prod', algorithm: 'rsa', identity: '' });
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(argsOf('ssh-keygen')?.slice(-2)).toEqual(['-b', '4096']);
+  });
+
+  it('stops at a failure from ssh-keygen without touching the vault', async () => {
+    vaultKey('prod');
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('ssh-keygen exploded'), { stderr: 'ssh-keygen exploded' });
+    });
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(messages(errorSpy)).toContain('Error generating key');
+    expect(fs.existsSync(path.join(keysDir, 'prod-2'))).toBe(false);
+  });
+
+  it('reports a failure from age and says where the replacement is', async () => {
+    vaultKey('prod');
+    execa.mockImplementation(async (binary: string, args: string[]) => {
+      if (binary === 'age') {
+        throw Object.assign(new Error('age exploded'), { stderr: 'age exploded' });
+      }
+      const keyPath = args[args.indexOf('-f') + 1];
+      fs.writeFileSync(keyPath, 'PRIVATE');
+      fs.writeFileSync(`${keyPath}.pub`, 'ssh-ed25519 NEWKEY me@host\n');
+      return { exitCode: 0 };
+    });
+
+    await rotateKey(sshDir, keysDir, tmpDir, PUBKEY);
+
+    expect(messages(errorSpy)).toContain('Error encrypting the replacement');
+    expect(messages(errorSpy)).toContain(path.join(tmpDir, 'id_prod-2'));
+    // No summary: nothing was stored, so there is nothing to deploy yet.
+    expect(messages(logSpy)).not.toContain('Add the replacement public key');
+  });
+});
+
+describe('retireKey', () => {
+  let root: string;
+  let sshDir: string;
+  let keysDir: string;
+  let tmpDir: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  const vaultKey = (name: string) => {
+    const dir = path.join(keysDir, name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, `id_${name}.age`), `ENCRYPTED ${name}`);
+    fs.writeFileSync(path.join(dir, `id_${name}.pub`), `PUBLIC ${name}`);
+  };
+
+  const answer = (answers: Record<string, unknown>) => {
+    prompt.mockImplementation(async (questions: { name: string }[]) => {
+      const { name } = questions[0];
+      return { [name]: answers[name] };
+    });
+  };
+
+  const question = (name: string) =>
+    prompt.mock.calls.map((c) => c[0][0]).find((q) => q.name === name);
+
+  const messages = () => logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-retire-')));
+    sshDir = path.join(root, '.ssh');
+    keysDir = path.join(root, 'vault', 'keys');
+    tmpDir = path.join(root, 'vault', 'tmp');
+    fs.mkdirSync(keysDir, { recursive: true });
+    fs.mkdirSync(sshDir, { recursive: true });
+    fs.mkdirSync(tmpDir, { recursive: true });
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    answer({ key: 'prod', confirmed: true, typed: 'prod' });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('says there is nothing to retire on an empty vault', async () => {
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(messages()).toContain('No encrypted keys in the vault');
+    expect(prompt).not.toHaveBeenCalled();
+  });
+
+  it('removes the vault entry and its directory', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+    // Only the one that was named.
+    expect(fs.existsSync(path.join(keysDir, 'prod-2', 'id_prod-2.age'))).toBe(true);
+  });
+
+  it('removes the plaintext copies as well', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+    for (const dir of [sshDir, tmpDir]) {
+      fs.writeFileSync(path.join(dir, 'id_prod'), 'PRIVATE');
+      fs.writeFileSync(path.join(dir, 'id_prod.pub'), 'PUBLIC');
+    }
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(fs.readdirSync(sshDir)).toEqual([]);
+    expect(fs.readdirSync(tmpDir)).toEqual([]);
+  });
+
+  it('lists every path before asking, and asks with a no default', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+    fs.writeFileSync(path.join(sshDir, 'id_prod'), 'PRIVATE');
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(messages()).toContain(path.join(keysDir, 'prod', 'id_prod.age'));
+    expect(messages()).toContain(path.join(sshDir, 'id_prod'));
+    expect(question('confirmed')).toMatchObject({ type: 'confirm', default: false });
+    expect(question('confirmed').message).toContain('3 files');
+  });
+
+  it('counts one file as one file', async () => {
+    vaultKey('prod-2');
+    fs.mkdirSync(path.join(keysDir, 'prod'));
+    fs.writeFileSync(path.join(keysDir, 'prod', 'id_prod.age'), 'ENCRYPTED');
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(question('confirmed').message).toContain('1 file?');
+    expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+  });
+
+  it('says what supersedes the key it is about to delete', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(messages()).toContain('prod-2 is in the vault and supersedes prod');
+    expect(question('typed')).toBeUndefined();
+  });
+
+  it('keeps everything when the confirmation is declined', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+    answer({ key: 'prod', confirmed: false });
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(true);
+    expect(messages()).toContain('Nothing was deleted');
+  });
+
+  describe('a key nothing replaces', () => {
+    beforeEach(() => {
+      vaultKey('prod');
+    });
+
+    it('warns that this is the only copy', async () => {
+      await retireKey(sshDir, keysDir, tmpDir);
+
+      expect(messages()).toContain('Nothing in the vault supersedes prod');
+    });
+
+    it('asks for the name to be typed out, and deletes when it matches', async () => {
+      await retireKey(sshDir, keysDir, tmpDir);
+
+      // A y/n is one keystroke from an irreversible deletion; this is not.
+      expect(question('typed')).toBeDefined();
+      expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+    });
+
+    it('deletes nothing when the typed name does not match', async () => {
+      answer({ key: 'prod', confirmed: true, typed: 'prodd' });
+
+      await retireKey(sshDir, keysDir, tmpDir);
+
+      expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(true);
+      expect(messages()).toContain('Name did not match');
+    });
+
+    it('accepts the name with stray whitespace', async () => {
+      answer({ key: 'prod', confirmed: true, typed: ' prod ' });
+
+      await retireKey(sshDir, keysDir, tmpDir);
+
+      expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+    });
+  });
+
+  it('keeps a vault directory that holds something else', async () => {
+    vaultKey('prod');
+    vaultKey('prod-2');
+    fs.mkdirSync(path.join(keysDir, 'prod', 'notes'));
+
+    await retireKey(sshDir, keysDir, tmpDir);
+
+    // The .age and .pub are gone; the directory stays, and says why.
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(false);
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'notes'))).toBe(true);
+    expect(messages()).toContain('it still holds other files');
+  });
+});

packages/keyman/tests/tool.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Tests for runTool.
+ *
+ * These spawn real processes rather than mocking execa. What runTool exists for
+ * is the shape of an execa failure — a mock would assert only what this test
+ * already assumes. It lives apart from utils.test.ts, which mocks execa to test
+ * the callers.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { runTool, ToolNotFoundError } from '../src/keyman.utils.js';
+
+describe('runTool', () => {
+  it('returns stdout on success', async () => {
+    const result = await runTool('node', ['-e', 'process.stdout.write("hi")']);
+
+    expect(result.stdout).toBe('hi');
+  });
+
+  it('passes options through', async () => {
+    const result = await runTool('node', ['-e', 'process.stdout.write(process.env.PROBE ?? "")'], {
+      env: { PROBE: 'from-options' },
+    });
+
+    expect(result.stdout).toBe('from-options');
+  });
+
+  it('reports empty stdout when the output went elsewhere', async () => {
+    const result = await runTool('node', ['-e', 'process.stdout.write("hi")'], {
+      stdout: 'ignore',
+    });
+
+    expect(result.stdout).toBe('');
+  });
+
+  it('turns a missing binary into an instruction rather than an ENOENT', async () => {
+    const failure = runTool('keyman-no-such-binary', []);
+
+    await expect(failure).rejects.toThrow(ToolNotFoundError);
+    await expect(failure).rejects.toThrow(
+      '`keyman-no-such-binary` was not found on PATH. Install it and try again.'
+    );
+  });
+
+  it('surfaces what the binary wrote to stderr', async () => {
+    await expect(
+      runTool('node', ['-e', 'process.stderr.write("no recipient\\n"); process.exit(1)'])
+    ).rejects.toThrow('`node` failed: no recipient');
+  });
+
+  it('falls back to the command summary when stderr is empty', async () => {
+    await expect(runTool('node', ['-e', 'process.exit(3)'])).rejects.toThrow(
+      /`node` failed: .*exit code 3/
+    );
+  });
+});

packages/keyman/tests/utils.test.ts

@@ -1,19 +1,30 @@
 /**
  * Tests for extractAgePublicKey.
  *
- * Runs against real files in a temp directory: the function is a thin wrapper
- * around fs plus a regex, and faking fs would only test the fake.
+ * Real files in a temp directory, but a mocked execa: the recipient is now
+ * derived by spawning `age-keygen -y`, and the gate cannot depend on age being
+ * installed on the machine running it. runTool itself is tested against real
+ * processes in tool.test.ts.
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execa } = vi.hoisted(() => ({ execa: vi.fn() }));
+
+vi.mock('execa', () => ({ execa }));
+
 import { extractAgePublicKey } from '../src/keyman.utils.js';
 
+const DERIVED = 'age1derivedfromthesecretkey';
+const IN_COMMENT = 'age1fromthecomment';
+
 describe('extractAgePublicKey', () => {
   let tmpDir: string;
   let errorSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
 
   const keyFile = (contents: string) => {
     const file = path.join(tmpDir, 'age.key');
@@ -21,9 +32,33 @@ describe('extractAgePublicKey', () => {
     return file;
   };
 
+  /** A well-formed identity file, whose comment can be made to disagree */
+  const identity = (comment = DERIVED) =>
+    keyFile(
+      ['# created: 2026-01-01T00:00:00Z', `# public key: ${comment}`, 'AGE-SECRET-KEY-1QQQ'].join(
+        '\n'
+      )
+    );
+
+  /**
+   * Makes age-keygen unavailable, the one case that falls back to the comment.
+   *
+   * Throws from an implementation rather than using mockRejectedValue: that
+   * builds its rejected promise when the mock is configured, and configuring it
+   * in a beforeEach leaves the rejection unhandled for a tick.
+   */
+  const noAgeKeygen = () => {
+    execa.mockImplementation(async () => {
+      throw Object.assign(new Error('spawn age-keygen ENOENT'), { code: 'ENOENT' });
+    });
+  };
+
   beforeEach(() => {
+    vi.clearAllMocks();
     tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-utils-')));
     errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    execa.mockResolvedValue({ stdout: `${DERIVED}\n` });
   });
 
   afterEach(() => {
@@ -31,49 +66,82 @@ describe('extractAgePublicKey', () => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  it('returns the public key from a standard age key file', () => {
-    const file = keyFile(
-      [
-        '# created: 2026-01-01T00:00:00Z',
-        '# public key: age1abc123xyz',
-        'AGE-SECRET-KEY-1QQQ',
-      ].join('\n')
-    );
+  it('derives the recipient from the secret key with age-keygen', async () => {
+    const file = identity();
 
-    expect(extractAgePublicKey(file)).toBe('age1abc123xyz');
+    await expect(extractAgePublicKey(file)).resolves.toBe(DERIVED);
+    expect(execa).toHaveBeenCalledWith('age-keygen', ['-y', file]);
+    expect(warnSpy).not.toHaveBeenCalled();
   });
 
-  it('tolerates extra whitespace after the label', () => {
-    const file = keyFile('# public key:    age1spaced\n');
+  it('prefers the derived key over a comment that disagrees', async () => {
+    // §2.3: the comment is editable text, and this is what makes it not matter.
+    const file = identity('age1staleorforged');
 
-    expect(extractAgePublicKey(file)).toBe('age1spaced');
+    await expect(extractAgePublicKey(file)).resolves.toBe(DERIVED);
   });
 
-  it('returns null and reports when the file does not exist', () => {
+  it('returns null and reports when the file does not exist', async () => {
     const missing = path.join(tmpDir, 'nope.key');
 
-    expect(extractAgePublicKey(missing)).toBeNull();
+    await expect(extractAgePublicKey(missing)).resolves.toBeNull();
     expect(errorSpy.mock.calls[0][0]).toContain('Age key file not found');
+    expect(execa).not.toHaveBeenCalled();
   });
 
-  it('returns null when the file has no public key line', () => {
+  it('returns null when age-keygen refuses the file, without trusting the comment', async () => {
+    const file = identity(IN_COMMENT);
+    execa.mockRejectedValue(
+      Object.assign(new Error('failed'), { exitCode: 1, stderr: 'age-keygen: error: malformed' })
+    );
+
+    await expect(extractAgePublicKey(file)).resolves.toBeNull();
+    expect(errorSpy.mock.calls[0][0]).toContain('malformed');
+  });
+
+  it('returns null when age-keygen prints something that is not a recipient', async () => {
+    const file = identity();
+    execa.mockResolvedValue({ stdout: 'Public key: (none)\n' });
+
+    await expect(extractAgePublicKey(file)).resolves.toBeNull();
+    expect(errorSpy.mock.calls[0][0]).toContain('derived no public key');
+  });
+
+  describe('without age-keygen installed', () => {
+    beforeEach(noAgeKeygen);
+
+    it('falls back to the comment, warning that it is unverified', async () => {
+      const file = identity(IN_COMMENT);
+
+      await expect(extractAgePublicKey(file)).resolves.toBe(IN_COMMENT);
+      expect(warnSpy.mock.calls[0][0]).toContain('unverified');
+    });
+
+    it('tolerates extra whitespace after the label', async () => {
+      const file = keyFile('# public key:    age1spaced\n');
+
+      await expect(extractAgePublicKey(file)).resolves.toBe('age1spaced');
+    });
+
+    it('returns null when the file has no public key line', async () => {
       const file = keyFile('AGE-SECRET-KEY-1QQQ\n');
 
-    expect(extractAgePublicKey(file)).toBeNull();
+      await expect(extractAgePublicKey(file)).resolves.toBeNull();
       expect(errorSpy).not.toHaveBeenCalled();
     });
 
-  it('ignores a key that is not on its own line', () => {
+    it('ignores a key that is not on its own line', async () => {
       const file = keyFile('prefix # public key: age1inline\n');
 
-    expect(extractAgePublicKey(file)).toBeNull();
+      await expect(extractAgePublicKey(file)).resolves.toBeNull();
     });
 
-  it('returns null and reports when the file cannot be read', () => {
+    it('returns null and reports when the file cannot be read', async () => {
       const asDirectory = path.join(tmpDir, 'age.key');
       fs.mkdirSync(asDirectory);
 
-    expect(extractAgePublicKey(asDirectory)).toBeNull();
+      await expect(extractAgePublicKey(asDirectory)).resolves.toBeNull();
       expect(errorSpy.mock.calls[0][0]).toContain('Failed to read key file');
     });
   });
+});

packages/keyman/tests/vault-layout.test.ts

@@ -0,0 +1,127 @@
+/**
+ * End-to-end over the configured vault layout.
+ *
+ * Everything except `age` and the prompts is real here — the config loader, the
+ * path resolution, encrypt and list all run — because the bug this covers lived
+ * in the seam between them: encrypt wrote to `vaultRoot` while list read from
+ * `keysDir`, so with the defaults (`keysDir: 'keys'`) an encrypted key was
+ * invisible to the very next listing. Every unit suite passed throughout, since
+ * each was told which directory to use.
+ *
+ * Non-default names on purpose: `keys`/`tmp` would also pass against a function
+ * that ignored the config entirely.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execa, prompt } = vi.hoisted(() => ({ execa: vi.fn(), prompt: vi.fn() }));
+
+vi.mock('execa', () => ({ execa }));
+vi.mock('inquirer', () => ({ default: { prompt } }));
+
+import { keyman } from '../src/keyman.main.js';
+
+describe('the configured vault layout', () => {
+  let root: string;
+  let project: string;
+  let home: string;
+  let sshDir: string;
+  let vaultRoot: string;
+  let cwd: string;
+  let env: NodeJS.ProcessEnv;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+
+  const output = () => logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  /** The one line of the listing table describing `name`. */
+  const listingRow = (name: string) =>
+    output()
+      .split('\n')
+      .find((line) => line.includes(name) && line.includes('['));
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    cwd = process.cwd();
+    env = { ...process.env };
+
+    root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-layout-')));
+    project = path.join(root, 'project');
+    home = path.join(root, 'home');
+    sshDir = path.join(home, '.ssh');
+    vaultRoot = path.join(project, 'vault');
+
+    fs.mkdirSync(project, { recursive: true });
+    fs.mkdirSync(sshDir, { recursive: true });
+    fs.writeFileSync(path.join(sshDir, 'id_prod'), 'PRIVATE');
+    fs.writeFileSync(path.join(sshDir, 'id_prod.pub'), 'PUBLIC');
+
+    fs.writeFileSync(
+      path.join(project, '.keymanrc.json'),
+      JSON.stringify({ vaultRoot: 'vault', keysDir: 'encrypted', tmpDir: 'plain' })
+    );
+
+    // HOME also redirects os.homedir(), so the real ~/.keymanrc.json cannot
+    // reach the loader and make this test depend on the machine it runs on.
+    process.env.HOME = home;
+    delete process.env.VAULT_ROOT;
+    process.chdir(project);
+
+    // The age identity has to exist before extractAgePublicKey will shell out.
+    fs.mkdirSync(vaultRoot, { recursive: true });
+    fs.writeFileSync(path.join(vaultRoot, 'age.key'), 'AGE-SECRET-KEY-1');
+
+    execa.mockImplementation(async (binary: string, args: string[]) => {
+      if (binary === 'age-keygen') {
+        return { stdout: 'age1recipient' };
+      }
+      fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+      return { stdout: '' };
+    });
+
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    process.chdir(cwd);
+    process.env = env;
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  /** Walks the menu, answering encrypt's key selection along the way. */
+  const run = (categories: string[]) => {
+    const queue = [...categories, 'quit'];
+    prompt.mockImplementation(async (questions: { name: string }[]) => {
+      switch (questions[0].name) {
+        case 'user':
+          return { user: '@current' };
+        case 'selectedKeys':
+          return { selectedKeys: ['id_prod'] };
+        default:
+          return { category: queue.shift() };
+      }
+    });
+    return keyman();
+  };
+
+  it('encrypts into the configured keys directory, where the listing looks', async () => {
+    await run(['encrypt', 'list']);
+
+    expect(fs.existsSync(path.join(vaultRoot, 'encrypted', 'prod', 'id_prod.age'))).toBe(true);
+    // ✅ is reachable only via inVault && inSsh, and the columns are
+    // [vault] [tmp] [.ssh] — either alone would pass on a blank vault column.
+    expect(listingRow('id_prod')).toContain('✅');
+    expect(listingRow('id_prod')).toMatch(/\[✓]\s+\[ ]\s+\[✓]/);
+  });
+
+  it('honours the configured directory names for every path it prints', async () => {
+    await run([]);
+
+    expect(output()).toContain(path.join(vaultRoot, 'encrypted'));
+    expect(output()).toContain(path.join(vaultRoot, 'plain'));
+  });
+});

packages/keyman/tests/vault.test.ts

@@ -0,0 +1,167 @@
+/**
+ * Tests for storeInVault, the write path encrypt and generate share.
+ *
+ * Its ordinary use is covered through those two callers; what is here is the
+ * behaviour that is awkward to reach from either — an ssh-keygen that succeeds
+ * without printing anything, and a failure over an entry that already exists.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { execa } = vi.hoisted(() => ({ execa: vi.fn() }));
+
+vi.mock('execa', () => ({ execa }));
+
+import { listVaultKeys, storeInVault } from '../src/keyman.vault.js';
+
+describe('listVaultKeys', () => {
+  let keysDir: string;
+
+  const entry = (name: string, file = `id_${name}.age`) => {
+    fs.mkdirSync(path.join(keysDir, name), { recursive: true });
+    fs.writeFileSync(path.join(keysDir, name, file), 'ENCRYPTED');
+  };
+
+  beforeEach(() => {
+    keysDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-vaultlist-')));
+  });
+
+  afterEach(() => {
+    fs.rmSync(keysDir, { recursive: true, force: true });
+  });
+
+  it('is empty for a keys directory that was never created', () => {
+    expect(listVaultKeys(path.join(keysDir, 'nope'))).toEqual([]);
+  });
+
+  it('sorts the entries rather than taking the filesystem order', () => {
+    for (const name of ['stage', 'alpha', 'prod']) {
+      entry(name);
+    }
+
+    expect(listVaultKeys(keysDir)).toEqual(['alpha', 'prod', 'stage']);
+  });
+
+  it('ignores a directory with no encrypted key in it', () => {
+    entry('prod');
+    // The shape a failed encryption used to leave behind, and a plain mistake.
+    fs.mkdirSync(path.join(keysDir, 'empty'));
+    entry('notes', 'README.md');
+
+    expect(listVaultKeys(keysDir)).toEqual(['prod']);
+  });
+
+  it('ignores a loose file', () => {
+    entry('prod');
+    fs.writeFileSync(path.join(keysDir, 'id_stage.age'), 'ENCRYPTED');
+
+    expect(listVaultKeys(keysDir)).toEqual(['prod']);
+  });
+});
+
+describe('storeInVault', () => {
+  let root: string;
+  let keysDir: string;
+  let keyPath: string;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  const PUBKEY = 'age1recipient';
+
+  const messages = (spy: ReturnType<typeof vi.spyOn>) =>
+    spy.mock.calls.map((c) => c.join(' ')).join('\n');
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'keyman-vault-')));
+    keysDir = path.join(root, 'keys');
+    keyPath = path.join(root, 'id_prod');
+    fs.writeFileSync(keyPath, 'PRIVATE');
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('warns when ssh-keygen succeeds but prints no key', async () => {
+    execa.mockImplementation(async (binary: string, args: string[]) => {
+      if (binary === 'ssh-keygen') return { stdout: '  \n' };
+      fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+      return { stdout: '' };
+    });
+
+    await storeInVault(keyPath, keysDir, PUBKEY);
+
+    // An exit code of 0 is not a public key: writing a .pub holding whitespace
+    // would put a file in the vault that no host would ever accept.
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.pub'))).toBe(false);
+    expect(messages(warnSpy)).toContain('no public key could be derived');
+    expect(fs.existsSync(path.join(keysDir, 'prod', 'id_prod.age'))).toBe(true);
+  });
+
+  it('writes the public half at the same time as the encrypted key', async () => {
+    fs.writeFileSync(`${keyPath}.pub`, 'ssh-ed25519 AAAA sibling');
+    execa.mockImplementation(async (_binary: string, args: string[]) => {
+      fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+      return { stdout: '' };
+    });
+
+    const vaultPath = await storeInVault(keyPath, keysDir, PUBKEY);
+
+    expect(vaultPath).toBe(path.join(keysDir, 'prod'));
+    expect(fs.readFileSync(path.join(vaultPath, 'id_prod.pub'), 'utf-8')).toBe(
+      'ssh-ed25519 AAAA sibling'
+    );
+    // No ssh-keygen: the sibling was there, so nothing needed deriving.
+    expect(execa.mock.calls.every((c) => c[0] === 'age')).toBe(true);
+  });
+
+  it('creates the vault entry private to the owner', async () => {
+    fs.writeFileSync(`${keyPath}.pub`, 'PUBLIC');
+    execa.mockImplementation(async (_binary: string, args: string[]) => {
+      fs.writeFileSync(args[args.indexOf('-o') + 1], 'ENCRYPTED');
+      return { stdout: '' };
+    });
+
+    await storeInVault(keyPath, keysDir, PUBKEY);
+
+    expect(fs.statSync(path.join(keysDir, 'prod')).mode & 0o777).toBe(0o700);
+  });
+
+  describe('when age fails', () => {
+    beforeEach(() => {
+      fs.writeFileSync(`${keyPath}.pub`, 'PUBLIC');
+      execa.mockImplementation(async (_binary: string, args: string[]) => {
+        // Half-written output, the way a failing age can leave it.
+        fs.writeFileSync(args[args.indexOf('-o') + 1], 'TRUNC');
+        throw Object.assign(new Error('age refused'), { stderr: 'no recipient' });
+      });
+    });
+
+    it('leaves no truncated key behind for decrypt to offer', async () => {
+      await expect(storeInVault(keyPath, keysDir, PUBKEY)).rejects.toThrow('`age` failed');
+
+      expect(fs.existsSync(path.join(keysDir, 'prod'))).toBe(false);
+    });
+
+    it('keeps an entry that was already there', async () => {
+      const vaultPath = path.join(keysDir, 'prod');
+      fs.mkdirSync(vaultPath, { recursive: true });
+      fs.writeFileSync(path.join(vaultPath, 'id_prod.pub'), 'THE OLD PUBLIC KEY');
+
+      await expect(storeInVault(keyPath, keysDir, PUBKEY)).rejects.toThrow('`age` failed');
+
+      // Cleaning up after a failure must not take the previous key with it.
+      expect(fs.readFileSync(path.join(vaultPath, 'id_prod.pub'), 'utf-8')).toBe(
+        'THE OLD PUBLIC KEY'
+      );
+      expect(messages(logSpy)).not.toContain('Encrypted and stored');
+    });
+  });
+});

packages/nopy/src/nopy.exit.ts

@@ -4,7 +4,7 @@
  */
 
 /** Parting words. Printed whenever a run ends because the user asked it to. */
-export const FAREWELL = 'Bye Bye Honeypie';
+export const FAREWELL = 'Bye Bye HoneyPy';
 
 /** Conventional exit code for "terminated by SIGINT" — 128 + 2. */
 export const CANCELLED_EXIT_CODE = 130;