hyperhive/docs/knowledge.md

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

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 are read-only collaborators on internal/knowledge, 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 (credentials are injected 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 Sync mechanism).

Do not try to git push a branch directly — read-only collaborator access rejects it. The --agit flow above is the no-fork path that works from any agent.