fix(forgejo): accept FORGEJO_ADMIN_TOKEN and document PAT setup

Align prune auth with railiance-apps forgejo tools and explain that
package prune needs a Forgejo PAT, not the OpenBao backup lane.

docs/forgejo-package-prune.md

@@ -18,17 +18,38 @@ tags slows backup growth and shortens chunked-copy duration.
 
 ## Operator commands
 
+### 1. Forgejo API token (one-time per workstation)
+
+This is **not** the OpenBao backup lane (`bao login` / Nextcloud). Prune uses a
+Forgejo **personal access token** with package scopes — same convention as
+`railiance-apps` (`FORGEJO_ADMIN_TOKEN`, `/tmp/forgejo-tegwick-api-token`).
+
+1. Log in to https://forgejo.coulomb.social as `tegwick` (or another user with
+   org package admin rights on `coulomb`).
+2. **Settings → Applications → Generate New Token**
+3. Scopes: **`read:package`** and **`write:package`**
+4. Store on the workstation (pick one):
+
+```bash
+# Option A — token file (matches forgejo-operator-bootstrap, npm smoke, webhooks)
+install -m 600 /dev/null /tmp/forgejo-tegwick-api-token
+# paste token into the file (single line, no newline required)
+
+# Option B — env for one shell session
+export FORGEJO_TOKEN='<pat>'
+# alias: export FORGEJO_ADMIN_TOKEN='<pat>'
+```
+
+Do not commit the token or paste it into workplans, State Hub, or chat.
+
+### 2. Run prune
+
 ```bash
 cd ~/railiance-platform
-export FORGEJO_TOKEN=...   # or FORGEJO_TOKEN_FILE=/path/to/token
-
 make forgejo-package-prune-dry-run   # list would-delete candidates
 make forgejo-package-prune           # delete beyond retention depth
 ```
 
-Requires a Forgejo PAT with `read:package` and `write:package`. Resolve custody via
-`warden route find "forgejo package token"` — do not store tokens in Git.
-
 ## Rollback
 
 If a needed tag was removed, restore from the latest Nextcloud `forgejo-dump-*.zip.age`

scripts/forgejo_package_prune.py

@@ -283,16 +283,23 @@ def build_delete_plans(
 
 
 def load_token() -> str:
-    token = os.environ.get("FORGEJO_TOKEN", "").strip()
-    if token:
-        return token
-    token_file = os.environ.get("FORGEJO_TOKEN_FILE", "/tmp/forgejo-tegwick-api-token")
+    for env_name in ("FORGEJO_TOKEN", "FORGEJO_ADMIN_TOKEN"):
+        token = os.environ.get(env_name, "").strip()
+        if token:
+            return token
+    token_file = os.environ.get(
+        "FORGEJO_TOKEN_FILE",
+        os.environ.get("FORGEJO_ADMIN_TOKEN_FILE", "/tmp/forgejo-tegwick-api-token"),
+    )
     path = Path(token_file).expanduser()
     if path.is_file():
         return path.read_text(encoding="utf-8").strip()
     raise SystemExit(
-        "ERROR: set FORGEJO_TOKEN or FORGEJO_TOKEN_FILE "
-        "(Forgejo PAT with read:package and write:package)"
+        "ERROR: Forgejo API token required (read:package + write:package).\n"
+        "  export FORGEJO_TOKEN=<pat>     # or FORGEJO_ADMIN_TOKEN\n"
+        "  # or save PAT to /tmp/forgejo-tegwick-api-token (chmod 600)\n"
+        "  Generate: https://forgejo.coulomb.social/user/settings/applications\n"
+        "  See: railiance-platform/docs/forgejo-package-prune.md"
     )