# 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)
```

<!-- vale write-good.Passive = NO -->

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](#contributing)); the operator reviews and merges, and
the local clone updates automatically (see
[Staying current](#staying-current) below).

<!-- vale write-good.Passive = YES -->

## 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`](../../4-implementation/swarm/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`):

   ```sh
   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:

   ```sh
   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](#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.