From 4bedf71c2df760a8929e0a6dcafeb8a720cf0e7a Mon Sep 17 00:00:00 2001
From: despiegk <kristof@threefold.io>
Date: Fri, 22 Aug 2025 14:02:58 +0000
Subject: [PATCH] Update herodb/instructions/age_usage.md

---
 herodb/instructions/age_usage.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/herodb/instructions/age_usage.md b/herodb/instructions/age_usage.md
index 7aeab38..b3e9fab 100644
--- a/herodb/instructions/age_usage.md
+++ b/herodb/instructions/age_usage.md
@@ -43,6 +43,7 @@ redis-cli -p PORT AGE DECRYPTNAME app1 <ciphertext_b64>
 ## Stateless AGE (ephemeral)
 
 Characteristics
+
 - No server‑side storage of keys.
 - You pass the actual key material with every call.
 - Not listable via AGE LIST.
@@ -52,24 +53,28 @@ Commands and examples
 1) Ephemeral encryption keys
 
 ```bash
-# Generate an ephemeral encryption keypair
+# Generate an ephemeral encryption keypair 
 redis-cli -p PORT AGE GENENC
 # Example output (abridged):
-# 1) "age1qz..."          # recipient (public)
-# 2) "AGE-SECRET-KEY-1..." # identity (secret)
+# 1) "age1qz..."          # recipient (public key) = can be used by others e.g. to verify what I sign
+# 2) "AGE-SECRET-KEY-1..." # identity (secret) = is like my private, cannot lose this one
 
-# Encrypt with the recipient
+# Encrypt with the recipient public key
 redis-cli -p PORT AGE ENCRYPT "age1qz..." "hello world"
-# → returns bulk string payload: base64 ciphertext
 
-# Decrypt with the identity (secret)
+# → returns bulk string payload: base64 ciphertext (encrypted content)
+
+# Decrypt with the identity (secret) in other words your private key
 redis-cli -p PORT AGE DECRYPT "AGE-SECRET-KEY-1..." "<ciphertext_b64>"
 # → "hello world"
 ```
 
 2) Ephemeral signing keys
 
+> ? is this same as my private key
+
 ```bash
+
 # Generate an ephemeral signing keypair
 redis-cli -p PORT AGE GENSIGN
 # Example output: