From 972a3ead68fd658910dcd9f012092574f8eb84a8 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 16:05:29 +0200
Subject: [PATCH] docs(knowledge): document hive-wide knowledge repo +
 /knowledge bind-mount
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The internal/knowledge forge repo and its /knowledge container bind-mount
have been live since feat(#1167) but had no docs/ entry — only a mention
in the agent system prompt.

Add docs/knowledge.md covering:
- Agent access (/knowledge read-only bind-mount inside every container)
- Repository layout (internal/knowledge, auto-seeded README)
- Sync mechanism (webhook on push + periodic pull fallback)
- State paths (/var/lib/hyperhive/knowledge on host)
- Contribution workflow (fork + PR, no direct push)

Also add a file-map entry and reading-path bullet in CLAUDE.md.
---
 CLAUDE.md         |  5 ++++
 docs/knowledge.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 docs/knowledge.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 34fe0d8b..be599577 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -388,6 +388,8 @@ docs/
                        env vars, matrix federation pointer
   ci.md                hive-ci Forgejo Actions runner: options, container
                        shape, auto-registration flow, nix sandbox note
+  knowledge.md         hive-wide knowledge repo: forge clone, /knowledge
+                       bind-mount, webhook + periodic sync, contribution flow
   coordinator.md       rebuild queue: queue kinds (Rebuild, MetaUpdate, Spawn),
                        dedup logic, sources, cascade tracking, step labels;
                        serialisation rationale
@@ -438,6 +440,9 @@ read them à la carte.
   [`docs/coordinator.md`](docs/coordinator.md).
 - **"How does the CI runner work? What's the auto-registration flow?"** →
   [`docs/ci.md`](docs/ci.md).
+- **"What is `/knowledge`? How does the hive-wide knowledge repo sync,
+  and how do I contribute a document?"** →
+  [`docs/knowledge.md`](docs/knowledge.md).
 
 ## Conventions & process
 
diff --git a/docs/knowledge.md b/docs/knowledge.md
new file mode 100644
index 00000000..a25c3f1f
--- /dev/null
+++ b/docs/knowledge.md
@@ -0,0 +1,75 @@
+# Hive-wide knowledge repository
+
+`internal/knowledge` on the forge is a shared reference doc repo
+readable by every agent. hive-c0re clones it to the host and
+bind-mounts the clone read-only into every agent container at
+`/knowledge`.
+
+## Agent access
+
+Inside any agent container:
+
+```
+/knowledge/          # read-only bind-mount of the local clone
+/knowledge/README.md # table of contents (seeded on first use)
+```
+
+Agents read documents directly from that path. The mount is
+read-only — agents never write through it. To contribute, fork
+`internal/knowledge` on the forge, open a PR, and the operator
+merges it. The local clone updates automatically on merge (see
+[Sync mechanism](#sync-mechanism) below).
+
+## Repository layout
+
+Canonical forge location: `internal/knowledge` (org `internal`,
+repo `knowledge`). Every agent's forge account is a read-only
+collaborator; the `core` account has push access for auto-seeding.
+
+The repo is auto-created at hive-c0re startup if it doesn't exist,
+seeded with a `README.md` containing a contribution guide and a
+blank table of contents. Add an entry to that ToC each time you
+create a new document.
+
+## Sync mechanism
+
+hive-c0re maintains the local clone at
+`/var/lib/hyperhive/knowledge` via two paths:
+
+1. **Forgejo push webhook** — `ensure_webhook` registers a push
+   hook on `internal/knowledge` at startup pointing at
+   `http://127.0.0.1:<dashboard_port>/webhook/knowledge`. On any
+   push to main (including merge commits) hive-c0re runs
+   `git pull` so agents see the new content on their next turn.
+   The endpoint is loopback-only; no signature verification is
+   needed.
+
+2. **Periodic pull** — a background task in `hive-c0re::main`
+   pulls on a fixed cadence as a fallback (webhook missed, c0re
+   restarted between pushes). The pull is best-effort — a failure
+   logs a warning and does not affect the rest of the daemon.
+
+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
+before returning.
+
+## State
+
+- **Host clone**: `/var/lib/hyperhive/knowledge` — persists across
+  hive-c0re restarts and agent destroy/recreate. Deleted only by
+  manual operator action.
+- **In-container mount**: `/knowledge` — bind-mounted read-only
+  from the host clone on every container start. Gone when container
+  is stopped; reappears on next start with the current clone state.
+
+## Contributing
+
+1. Fork `internal/knowledge` into your own namespace on the forge.
+2. Create a branch and add or update a document.
+3. Open a pull request — the operator reviews and merges.
+4. The webhook fires on merge; every running container sees the
+   updated content within seconds.
+
+Do **not** push directly to `main` — agents have read-only
+collaborator access and the push will be rejected.