From 6d7117fb878e3b44c4db35fc5dec0d9fe0bbb782 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 15 May 2026 12:17:40 +0000
Subject: [PATCH] readme: demote Docker to optional hardened mode

Promote Homebrew/go install as the recommended quick-start path. The
Docker recipes still exist for defense-in-depth during key generation,
but the resulting key file lands on the host either way, so framing
Docker as the default added setup overhead without much marginal
security benefit for most users.

https://claude.ai/code/session_01TcLeyHaLrYtbhogrVBD6GN
---
 README.md | 45 +++++++++++++++++++--------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 3f9b73f..315103e 100644
--- a/README.md
+++ b/README.md
@@ -13,40 +13,21 @@ coldkey generates [post-quantum (ML-KEM-768 + X25519)](https://words.filippo.io/
 
 ![Image of Printout](image.png)
 
-## Install
+## Quick start
 
 ```bash
-# Homebrew (macOS/Linux)
+# Install — Homebrew (macOS/Linux)
 brew install --cask pike00/tap/coldkey
 
 # Or with Go
 go install github.com/pike00/coldkey/cmd/coldkey@latest
-```
-
-## Quick start
-
-### Docker (recommended)
-
-```bash
-# Pull the image
-docker pull ghcr.io/pike00/coldkey:latest
-
-# Interactive — generate a key and paper backup
-just docker-run
-
-# Backup an existing key
-just docker-backup ~/.config/sops/age/keys.txt
-```
-
-All `just docker-*` commands include security hardening flags (network isolation, read-only filesystem, dropped capabilities). Output is written to `./output/`.
 
-### From source
-
-```bash
-go install github.com/pike00/coldkey/cmd/coldkey@latest
+# Generate a key and paper backup
 coldkey generate -o ~/.config/sops/age/keys.txt
 ```
 
+For defense-in-depth during key generation, see [Hardened mode (Docker)](#hardened-mode-docker) below.
+
 ## Commands
 
 ### `coldkey` (no args) — Interactive mode
@@ -88,9 +69,21 @@ Print the version string.
 | Image | `distroless/static:nonroot` — no shell, non-root UID 65534 |
 | Memory zeroing | Best-effort `secure.Zero()` on key buffers before GC (see [Limitations](#limitations)) |
 
-### Docker flags explained
+### Hardened mode (Docker)
+
+An optional distroless Docker image runs key generation under network isolation, a read-only root filesystem, and dropped capabilities. Note that the resulting `keys.txt` is written to a host-mounted volume, so the container only hardens the generation step — the key at rest sits on the host like any other file.
+
+```bash
+docker pull ghcr.io/pike00/coldkey:latest
+
+# Interactive — generate a key and paper backup
+just docker-run
+
+# Backup an existing key
+just docker-backup ~/.config/sops/age/keys.txt
+```
 
-The `just docker-run` and `just docker-backup` commands apply these flags automatically:
+Output is written to `./output/`. The `just docker-run` and `just docker-backup` recipes apply these flags automatically:
 
 | Flag | Purpose |
 |------|---------|