docs: highlight encryption-key location, backup, and override (closes #8)

CHANGELOG.md

@@ -28,6 +28,16 @@ anchoring, skill signing, and the FIPS image are now clearly marked
 roadmap. Download / verify examples use a `VERSION` variable so they no
 longer go stale.
 
+### Documentation: highlight encryption-key custody (#8)
+
+The encryption tutorial and FAQ now state plainly where the local KEK
+lives (`kek.bin` in the keyring directory), that losing it makes every
+backup under it unrecoverable, that the keyring directory must be backed
+up separately from the repository, and that `PG_HARDSTORAGE_KEYRING_DIR`
+overrides its location (with `pg_hardstorage doctor` reporting the
+resolved path). Also corrected a stale "GCP/Azure/Vault KMS slated for
+v0.5+" note (those providers ship today).
+
 ### Packaging: wire container-image publishing (GHCR)
 
 The release pipeline can now build and publish multi-arch (amd64/arm64)

docs/faq.md

@@ -329,11 +329,25 @@ guidance and sizing rules of thumb.
 
 #### Where is the KEK stored?
 
-Wherever you point the encryption plugin: AWS KMS, GCP
-KMS, Azure Key Vault, HashiCorp Vault Transit, or — for
-single-host dev — an `aes-256-gcm` keyring directory.
-HSM (PKCS#11) lands in the v1.0 build flavour.  Reference:
-[KEKRef schemes](reference/cli/pg_hardstorage_kms.md);
+With a cloud KMS scheme (AWS KMS, GCP KMS, Azure Key
+Vault, HashiCorp Vault Transit) the KEK never leaves the
+provider — pg_hardstorage only stores a reference. With the
+local `aes-256-gcm` scheme the KEK is a 32-byte file,
+`kek.bin`, in the **keyring directory** (`<config>/keyring`
+— e.g. `/etc/pg_hardstorage/keyring` for a system install,
+under your user config dir otherwise). Run `pg_hardstorage
+doctor` for the resolved path; override it with the
+`PG_HARDSTORAGE_KEYRING_DIR` environment variable. HSM
+(PKCS#11) is available in the `pkcs11` / FIPS build flavour.
+
+!!! danger "Back up your local KEK"
+    `kek.bin` unwraps every backup made under it. If you
+    lose the keyring directory you **cannot restore** — back
+    it up separately from the repository, or use a cloud KMS
+    scheme so custody isn't a single local file. The signing
+    keypair lives in the same directory.
+
+Reference: [KEKRef schemes](reference/kekref-schemes.md);
 explanation:
 [envelope encryption](explanation/envelope-encryption.md).
 
@@ -361,10 +375,11 @@ and
 
 #### What encryption algorithm does pg_hardstorage use?
 
-AES-256-GCM-SIV (RFC 8452, nonce-misuse resistant) by
-default.  AES-256-GCM with a random 96-bit nonce in FIPS
-mode (BoringCrypto's FIPS module doesn't yet ship GCM-SIV
-acceleration).  Per-chunk key derived as
+AES-256-GCM (random 96-bit nonce) is the cipher shipping
+today; AES-256-GCM-SIV (RFC 8452, nonce-misuse resistant)
+is the planned default once a validated implementation
+lands (the Go standard library and BoringCrypto's FIPS
+module don't ship GCM-SIV).  Per-chunk key derived as
 `HKDF-SHA256(BDEK, info=chunk_hash)`; see
 [envelope encryption](explanation/envelope-encryption.md).
 

docs/tutorials/encryption-walkthrough.md

@@ -26,9 +26,22 @@ copy lands in the manifest. There are two KEK schemes shipped today:
   `KMS:Encrypt` / `KMS:Decrypt` against the configured key. Good
   for fleets that already centralise key custody.
 
-Other cloud KMS providers (`gcp-kms://`, `azure-key-vault://`,
-`vault-transit://`) are slated for v0.5+; `kms shred`,
-`kms rotate`, and PKCS#11 / TPM2 binding land in the same window.
+GCP KMS (`gcp-kms://`), Azure Key Vault (`azure-key-vault://`), and
+HashiCorp Vault Transit (`vault-transit://`) ship as well, and
+`kms shred` (crypto-shred) is available today. PKCS#11 / TPM2 (HSM)
+binding ships in the `pkcs11` / FIPS build flavour.
+
+!!! danger "Back up your keys — you cannot restore without them"
+    With the local `local:default` scheme, `kek.bin` in the keyring
+    directory unwraps **every** backup. Lose the keyring directory and
+    your encrypted backups are **mathematically unrecoverable** — the
+    same effect `kms shred` produces on purpose. Find the resolved path
+    with `pg_hardstorage doctor`, override it with the
+    `PG_HARDSTORAGE_KEYRING_DIR` environment variable, and **back the
+    keyring directory up separately from the repository**, with at least
+    the care you'd give a database password. The Ed25519 signing keypair
+    lives in the same directory. For production, prefer a cloud KMS
+    scheme so key custody isn't a single local file.
 
 ---