From af83a868e4283c35024149ec7e02e40daa469710 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 15 Aug 2026 12:16:03 +0200
Subject: [PATCH] docs(knowledge): fix stale collaborator model and webhook
 delivery claims

---
 docs/knowledge.md | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index 7b1e8d39..a46c2a15 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -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.