diff --git a/src/secrets.rs b/src/secrets.rs
index 16da66a..9b5e22b 100644
--- a/src/secrets.rs
+++ b/src/secrets.rs
@@ -129,6 +129,12 @@ impl PartialEq for SecretVec {
     }
 }
 
+/// Reads a raw 32-byte key from `path`, rejecting files that are not exactly
+/// 32 bytes long (a likely trailing newline is called out in the error).
+///
+/// Performs **no permission checking** on the file. Library callers who care
+/// whether the key file is readable by others must check themselves; the fcry
+/// CLI does this and prints a warning (see `read_key_file_cli` in the binary).
 pub fn read_key_file(path: &Path) -> Result<SecretBytes32, FcryError> {
     let mut file = File::open(path)?;
     let mut buf = Zeroizing::new([0u8; 33]);
@@ -165,6 +171,9 @@ pub fn read_key_file(path: &Path) -> Result<SecretBytes32, FcryError> {
     Ok(key)
 }
 
+/// Normalizes a passphrase to Unicode NFC so the same visual passphrase
+/// always derives the same key regardless of how the platform or input
+/// method composed it. Fails if the bytes are not valid UTF-8.
 pub fn normalize_passphrase(pw: SecretVec) -> Result<SecretVec, FcryError> {
     let normalized = pw.with_slice(|bytes| {
         let s = std::str::from_utf8(bytes).map_err(|_| {