vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(knowledge): fix stale collaborator model and webhook delivery claims

Browse source
This commit is contained in:
iris 2026-08-15 12:16:03 +02:00 • committed by mara
commit af83a868e4
1 changed files with 16 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

29
docs/knowledge.md
View file

@ -24,8 +24,9 @@ the local clone updates automatically (see
## 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.
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
@ -39,11 +40,12 @@ hive-c0re maintains the local clone at
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.
`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.
2. **Periodic pull** — a background task in `hive-c0re::main`
pulls on a fixed cadence as a fallback (webhook missed, c0re
@ -89,9 +91,10 @@ 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.
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 (credentials are injected automatically; the `-r`
flag selects the repo, the clone lands in `./knowledge`):
@ -125,6 +128,6 @@ flow** through the `hive-forge` CLI — no fork required.
running container sees the updated content within seconds (see
[Sync mechanism](#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.
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.