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): document the hive-forge AGit no-fork contribution flow

Browse source 
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.
This commit is contained in:
iris 2026-06-05 20:54:25 +02:00
commit d952e7ac01
1 changed files with 43 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

52
docs/knowledge.md
View file

@ -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.