From 3ee831ccddcb8f9cd6980b9f597ac0d6b4a6e678 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Thu, 2 Jul 2026 14:59:20 +0200
Subject: [PATCH] docs(tools/forge): document repo-create,
 repo-add-collaborator, repo-labels verbs

---
 docs/tools/forge.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/tools/forge.md b/docs/tools/forge.md
index 8ff08374..64fd0f79 100644
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@@ -84,6 +84,14 @@ hive-forge subscription --unwatch           # unsubscribe
 hive-forge subscription --list              # list every repo you watch (audit the notification firehose)
 hive-forge -r internal/knowledge clone      # clone with creds auto-injected
 hive-forge -r internal/knowledge pr-create --agit --topic foo --title "..."  # open PR via AGit (no fork)
+# --- repo management ---
+hive-forge repo-create my-repo                                   # create under authenticated user; prints URL
+hive-forge repo-create my-repo --org myorg --private --auto-init # under an org, private, with initial commit
+hive-forge repo-add-collaborator alice                           # add write collaborator (default permission)
+hive-forge repo-add-collaborator alice --permission read         # read-only collaborator
+hive-forge repo-labels                                           # list every label defined on the repo
+hive-forge repo-labels bug                                       # filter by name substring
+hive-forge repo-labels --json                                    # full label objects (id, name, color, description)
 ```
 
 ### Which read verb when
@@ -165,6 +173,34 @@ Note: review verdicts come from *formal* Forgejo reviews (the
 approve / request-changes API). Reviewers who post their verdict as a
 plain comment show under `last comment`, not `reviews`.
 
+### Repo management
+
+Three verbs create repos and manage their membership — the supported
+path for workflows that need a fresh repo (agents cannot push to
+non-existent repos; the Forgejo instance disables push-to-create).
+
+**`repo-create <name>`** — create a repo under the authenticated user
+and print its URL. Key flags:
+
+- `--org <ORG>` — create under an org namespace instead
+- `--private` — private repo (default: public)
+- `--auto-init` — seed an initial commit so the repo is non-empty and
+  immediately cloneable; omit for a bare repo you push into
+- `--description <TEXT>` — repo description
+
+**`repo-add-collaborator <user>`** — grant a forge user access to the
+active repo (`-r`/`HIVE_FORGE_REPO`). Companion to `repo-create`. The
+`--permission` flag accepts `read` / `write` (default) / `admin`.
+`hive-c0re` uses this internally when an agent's config repo is
+initialised (`create_repo` → `repo-add-collaborator` → agent gets
+write access).
+
+**`repo-labels [PATTERN]`** — list every label defined on the repo,
+optionally filtered by a name substring (case-sensitive). Distinct from
+`labels <n>` which shows the labels on one specific issue/PR. Use this
+to discover valid label names before triaging or to audit the label set.
+`--json` emits full label objects (id, name, color, description).
+
 ## Notes
 
 - **Read-before-comment guard:** `comment` refuses to post when forge still