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

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 ## Repository layout
Canonical forge location: `internal/knowledge` (org `internal`, Canonical forge location: `internal/knowledge` (org `internal`,
repo `knowledge`). Every agent's forge account is a read-only repo `knowledge`). The repo is public, so every agent's forge account
collaborator; the `core` account has push access for auto-seeding. 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, 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 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 1. **Forgejo push webhook** — `ensure_webhook` registers a push
hook on `internal/knowledge` at startup pointing at hook on `internal/knowledge` at startup pointing at
`http://127.0.0.1:<dashboard_port>/webhook/knowledge`. On any `https://<hive_domain>/webhook/knowledge` (routed through the
push to main (including merge commits) hive-c0re runs gateway, avoiding the Forgejo SSRF guard that blocks loopback
`git pull` so agents see the new content on their next turn. delivery). On any push to main (including merge commits) hive-c0re
The endpoint is loopback-only; no signature verification is runs `git pull` so agents see the new content on their next turn.
needed. 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` 2. **Periodic pull** — a background task in `hive-c0re::main`
pulls on a fixed cadence as a fallback (webhook missed, c0re pulls on a fixed cadence as a fallback (webhook missed, c0re
@ -89,9 +91,10 @@ token.
## Contributing ## Contributing
Agents are read-only collaborators on `internal/knowledge`, so they Agents have read access to `internal/knowledge` (it's public) but no
can't push a branch directly. The supported path is Forgejo's **AGit write access, so they can't push a branch directly. The supported path
flow** through the `hive-forge` CLI — no fork required. is Forgejo's **AGit flow** through the `hive-forge` CLI — no fork
required.
1. Clone the repo (credentials are injected automatically; the `-r` 1. Clone the repo (credentials are injected automatically; the `-r`
flag selects the repo, the clone lands in `./knowledge`): 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 running container sees the updated content within seconds (see
[Sync mechanism](#sync-mechanism)). [Sync mechanism](#sync-mechanism)).
Do **not** try to `git push` a branch directly — read-only Do **not** try to `git push` a branch directly — lacking write access,
collaborator access rejects it. The `--agit` flow above is the it's rejected. The `--agit` flow above is the no-fork path that works
no-fork path that works from any agent. from any agent.