docs: add missing readmes for hive-c0re, hive-forge, hivectl

hive-forge/README.md

@@ -0,0 +1,58 @@
+# hive-forge
+
+Typed CLI wrapper around the in-cluster Forgejo's REST API. Replaces
+the prior bash script (`hive-forge-tools.nix`) so that agents and
+operators get the same error handling, exit codes, and JSON shapes
+regardless of how the bash mood was that day — this is the **only
+supported path** to the forge from inside an agent container; never
+`curl` it directly.
+
+Single binary, one verb subcommand per forge operation (issues, PRs,
+comments, labels, reviews, CI status, attachments, triage). Reads
+credentials from the environment: `HIVE_FORGE_URL` (base URL),
+`HIVE_FORGE_REPO` (default repo), `HYPERHIVE_STATE_DIR` (state dir —
+`forge-token` lives here). The global `-f/--forge <label>` flag
+retargets a dashboard-provisioned *external* forge account instead,
+reading `forge-<label>-token` + `forge-<label>.json` from the state
+dir rather than the internal-forge pair.
+
+## When to use it
+
+Reach for this crate when you're adding a new forge verb or changing
+how an existing one behaves — it's the single place issue/PR/comment/
+CI logic lives for every agent and `hivectl`. If you're instead adding
+a *tool* an agent's claude session calls, that's `hive-agent-mcp`
+wrapping a shellout to this binary, not new logic here.
+
+## Shape
+
+- **`verbs/`** — one module per subcommand, each exposing a clap-derived
+  `Args` struct and a `run(&Client, Args) -> Result<()>` fn. Splitting
+  one verb per module keeps each handler small and avoids the bash
+  script's monolithic `case` statement. Notable ones:
+  - **`lint.rs`** — `lint <subcommand>` triage queries (unassigned,
+    no-reviewer, stale-branches, assignments), always JSON-able via the
+    global `--json` flag.
+  - **`pr_status.rs`** — the merge-readiness verdict command
+    (`pr-status --pr <n>` / `--sha <commit>`); its exit code IS the
+    verdict, not just a report.
+  - **`comment.rs`** / **`comments.rs`** — post (refuses on unread
+    thread activity) / read (marks forge's own notification read as a
+    side effect) — see `notify.rs` for why that's safe to rely on.
+- **`client.rs`** — the app-level Forgejo client wrapper. Identity is
+  the per-agent token under `${HYPERHIVE_STATE_DIR}/forge-token`. REST
+  calls go through the typed `forgejo_api::sync::Forgejo` client
+  (`Client::api`); a minimal raw `reqwest` client remains for the few
+  *web-router* routes Forgejo doesn't serve under `/api/v1/`
+  (attachment downloads, Actions artifact/log routes).
+- **`notify.rs`** — the read-before-comment guard, backed by forge's
+  own notification read-state rather than a local mirror (which would
+  drift across container restarts). "Is there unread activity here?"
+  is just "does forge still have an unread notification for this
+  thread?" — forge is the single source of truth.
+- **`body.rs`** — body-input resolution shared by every verb that
+  posts a body: exactly one source between `--body`, `--body-file`,
+  and piped stdin (matches the old bash `resolve_body` helper);
+  passing both `--body` and `--body-file` is a clear error.
+
+Full verb reference (with worked examples): `docs/tools/forge.md`.