diff --git a/src/KI/Embedding/KIEmbedding.h b/src/KI/Embedding/KIEmbedding.h
index 310599a..62d2fc8 100644
--- a/src/KI/Embedding/KIEmbedding.h
+++ b/src/KI/Embedding/KIEmbedding.h
@@ -8,6 +8,15 @@
 
 namespace KI {
 
+/**
+ * KIEmbedOptions and KIEmbeddingResult document the embedding API exposed by libKI providers.
+ *
+ * Semantics
+ * - Providers should accept one or many input texts and return one vector per input.
+ * - The `model` is a free-form identifier understood by the provider (e.g., "bge-m3:latest").
+ * - If `normalize` is set to "l2", providers may L2-normalize vectors client-side for cosine search.
+ */
+
 class KIEmbedOptions
 {
     Q_GADGET