0f39bdaaa4
Account minting, knowledge sync, the archetype refresh, the matrix appservice flow and the SSO secret delivery move to pages under 4-implementation/swarm. Each handbook page keeps what an operator does or sees, with a pointer.
102 lines
3.8 KiB
Markdown
102 lines
3.8 KiB
Markdown
# 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.
|