diff --git a/docs/knowledge.md b/docs/knowledge.md
index 73aa1e8f..7b1e8d39 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -50,6 +50,24 @@ hive-c0re maintains the local clone at
    restarted between pushes). The pull is best-effort — a failure
    logs a warning and does not affect the rest of the daemon.
 
+Both paths share the same `knowledge::pull()` function, which also
+handles the change notice below — neither path can forget to wire it
+in since the broadcast logic lives once, in `pull()` itself, not at
+each call site.
+
+### Change notice
+
+When a pull actually moves the local clone's `HEAD` (a real change,
+not a no-op — e.g. the periodic pull finding nothing new), hive-c0re
+broadcasts a short notice to every currently-registered agent's inbox:
+sender `system`, body `[system] /knowledge updated:` followed by a
+`git diff --stat <old>..<new>` summary of what changed (or a generic
+"see the repo" fallback if computing the diff itself fails). This is
+the same broadcast mechanism used for other hive-wide notices — inbox
+message only, no forced wake, and it carries the standard "this was a
+broadcast" hint. A diff or per-agent send failure is logged but never
+blocks the pull itself.
+
 The local clone is created (or refreshed) once at startup via
 `knowledge::ensure_local_clone`. If the repo is brand new and
 empty, `ensure_local_clone` seeds it with the default README