hyperhive/docs/2-handbook/swarm/knowledge.md

Swarm-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 Staying current 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 site admins can push: core, and swarm-controller's own account, which seeds the README.

The swarm controller creates the repo if it doesn't exist, at startup and every few minutes after, and seeds an empty one 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.

Staying current

Each hive keeps a local clone of the repo and mounts it read-only into every agent container. The swarm controller holds the single push hook on internal/knowledge, and on any push to main it sends an event that makes every hive pull. A periodic pull closes the gap for a hive that was offline, so one hive may briefly show older content than another. When a pull changes anything, every agent gets a /knowledge updated notice.

Don't add a per-hive hook. A webhook has one target URL, so a second registration takes delivery away from whoever registered first.

The clone lives on the host at /var/lib/hyperhive/knowledge and survives hive-c0re restarts and agent destroy or recreate; only a manual delete removes it. The mount leaves out .git, so agents see the documents but not the history.

The sync jobs, retry timing, the change notice and the mount rules: knowledge.md.

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.

1. Clone the repo (hive-forge injects credentials automatically; the -r flag selects the repo, the clone lands in ./knowledge):

   hive-forge -r internal/knowledge clone
   cd knowledge
   

2. Create a branch and add or update a document, then commit normally.

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

4. The operator reviews and merges. The webhook fires on merge; every running container sees the updated content within seconds (see Staying current).

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.