docs: add token scopes section to forge.md, trim forge.rs module doc + scope comments

docs/forge.md

@@ -8,6 +8,37 @@ handling live in [`docs/gateway.md`](gateway.md); this file owns the
 per-agent integration story and the notification pump that wakes
 each agent on relevant activity.
 
+## Token scopes
+
+Two scope sets live in `hive-c0re::forge`:
+
+**`TOKEN_SCOPES`** (per-agent tokens):
+
+| Scope | Why |
+|-------|-----|
+| `write:repository` | Create, clone, push, delete repos; merge PRs. |
+| `write:issue` | Open / comment / review issues **and** pull requests (Forgejo namespaces PR conversation under issues). |
+| `write:user` | Edit own profile, create repos under own user. |
+| `write:organization` | Create + manage orgs (lets agents share a forge namespace). |
+| `read:user` | Token-owner endpoint used for self-identification at harness startup. |
+| `write:misc` | Hooks, attachments, the rest of the long tail. |
+| `read:notification` | Poll `GET /notifications` for unread events. |
+| `write:notification` | Mark notifications read via `PATCH /notifications/threads/{id}`. |
+
+**`CORE_TOKEN_SCOPES`** (hive-c0re's own `core` user): everything in
+`TOKEN_SCOPES` plus `read:admin` and `write:admin`. Site-admin
+membership alone isn't sufficient — Forgejo's token scope gate runs
+before the user-permission check, so `/api/v1/admin/*` returns
+`403 Forbidden` for any token without the admin scope bits, even when
+the bearer is a site admin.
+
+**Migration note**: if `PATCH /api/v1/admin/users/{name}` returns 403
+on an existing deploy, the core token predates the admin-scope
+addition. Delete `/var/lib/hyperhive/forge-core-token` and restart
+hive-c0re to re-mint with the new scopes.
+
+---
+
 ## Per-agent forge accounts
 
 Each agent gets its own Forgejo user + access token, provisioned at