From 9e7158f593cef698d30f71868733ac6408b12018 Mon Sep 17 00:00:00 2001 From: damocles Date: Sun, 2 Aug 2026 03:13:04 +0200 Subject: [PATCH] docs: describe the knowledge-change broadcast in the sync-mechanism section --- docs/knowledge.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) 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 ..` 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