docs: add nonce handling explanation for developers

pkg/smsg/smsg.go

@@ -1,5 +1,23 @@
 package smsg
 
+// SMSG (Secure Message) provides ChaCha20-Poly1305 authenticated encryption.
+//
+// IMPORTANT: Nonce handling for developers
+// =========================================
+// Enchantrix embeds the nonce directly in the ciphertext:
+//
+//     [24-byte nonce][encrypted data][16-byte auth tag]
+//
+// The nonce is NOT transmitted separately in headers. It is:
+//   - Generated fresh (random) for each encryption
+//   - Extracted automatically from ciphertext during decryption
+//   - Safe to transmit (public) - only the KEY must remain secret
+//
+// This means wrapped keys, encrypted payloads, etc. are self-contained.
+// You only need the correct key to decrypt - no nonce management required.
+//
+// See: github.com/Snider/Enchantrix/pkg/enchantrix/crypto_sigil.go
+
 import (
 	"bytes"
 	"compress/gzip"

pkg/smsg/types.go

@@ -2,6 +2,14 @@
 // SMSG (Secure Message) enables encrypted message exchange where the recipient
 // decrypts using a pre-shared password. Useful for secure support replies,
 // confidential documents, and any scenario requiring password-protected content.
+//
+// Format versions:
+//   - v1: JSON with base64-encoded attachments (legacy)
+//   - v2: Binary format with zstd compression (current)
+//   - v3: Streaming with LTHN rolling keys (planned)
+//
+// Encryption note: Nonces are embedded in ciphertext, not transmitted separately.
+// See smsg.go header comment for details.
 package smsg
 
 import (