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, use the hive-forge AGit flow (no fork needed — see Contributing); the operator reviews and merges, and the local clone updates automatically (see Sync mechanism below).

Repository layout

Canonical forge location: internal/knowledge (org internal, repo knowledge). The repo is public, so every agent's forge account has read access without an explicit per-agent collaborator grant; only 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:

Forgejo push webhook — ensure_webhook registers a push hook on internal/knowledge at startup pointing at https://<hive_domain>/webhook/knowledge (routed through the gateway, avoiding the Forgejo SSRF guard that blocks loopback delivery). 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 protected by an auto-generated HMAC secret that hive-c0re verifies on every delivery.
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.

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 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.

The mount deliberately excludes .git: the host clone embeds the core token in .git/config (it rides the clone URL), so hive-priv overlays an empty tmpfs at /knowledge/.git — agents see the documents, not the repo metadata or token.

Contributing

Agents have read access to internal/knowledge (it's public) but no write access, so they can't push a branch directly. The supported path is Forgejo's AGit flow through the hive-forge CLI — no fork required.

Clone the repo (credentials are injected automatically; the -r flag selects the repo, the clone lands in ./knowledge):
```
hive-forge -r internal/knowledge clone
cd knowledge
```
Create a branch and add or update a document, then commit normally.
Open (or update) a PR with --agit. This pushes the current HEAD to refs/for/<base>/<topic>, which Forgejo turns into a PR even though you can't push a branch:
```
hive-forge -r internal/knowledge pr-create --agit \
  --title "docs: add the X runbook" \
  --topic add-x-runbook \
  --body-file - <<'EOF'
What this document adds and why.
EOF
```
Re-running with the same --topic updates the open PR (it force-pushes the AGit scratch ref). The base defaults to main; in --agit mode the push goes to the origin remote that hive-forge clone set up.
The operator reviews and merges. The webhook fires on merge; every running container sees the updated content within seconds (see Sync mechanism).

Do not try to git push a branch directly — lacking write access, it's rejected. The --agit flow above is the no-fork path that works from any agent.

5.2 KiB Raw Blame History