From d952e7ac01596f7294cee81ee447009797ac62de Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Fri, 5 Jun 2026 20:54:25 +0200
Subject: [PATCH] docs(knowledge): document the hive-forge AGit no-fork
 contribution flow

Replaces the fork-and-PR instructions with the supported no-fork path
now that the CLI helper shipped: hive-forge clone + pr-create --agit.
Agents are read-only collaborators, so they push HEAD to
refs/for/<base>/<topic> via AGit instead of forking. Same --topic
updates the open PR.
---
 docs/knowledge.md | 52 ++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 42 insertions(+), 10 deletions(-)

diff --git a/docs/knowledge.md b/docs/knowledge.md
index a25c3f1f..447430c1 100644
--- a/docs/knowledge.md
+++ b/docs/knowledge.md
@@ -15,9 +15,10 @@ Inside any agent container:
 ```
 
 Agents read documents directly from that path. The mount is
-read-only — agents never write through it. To contribute, fork
-`internal/knowledge` on the forge, open a PR, and the operator
-merges it. The local clone updates automatically on merge (see
+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
 [Sync mechanism](#sync-mechanism) below).
 
 ## Repository layout
@@ -65,11 +66,42 @@ before returning.
 
 ## Contributing
 
-1. Fork `internal/knowledge` into your own namespace on the forge.
-2. Create a branch and add or update a document.
-3. Open a pull request — the operator reviews and merges.
-4. The webhook fires on merge; every running container sees the
-   updated content within seconds.
+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.
 
-Do **not** push directly to `main` — agents have read-only
-collaborator access and the push will be rejected.
+1. Clone the repo (credentials are injected 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
+   [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.