diff --git a/docs/forge.md b/docs/forge.md
index 093b5860..83a2481c 100644
--- a/docs/forge.md
+++ b/docs/forge.md
@@ -71,7 +71,12 @@ Two things live in the `agent-configs` Forgejo organization:
 The `hive-forge` CLI (separate workspace crate, see
 [`README.md`](../README.md) file map) wraps the Forgejo REST API
 with the per-agent token; agents call it for issue / PR / comment
-ops as if it were a peer.
+ops as if it were a peer. All REST calls across the workspace
+(`hive-forge` verbs, hive-c0re provisioning, this poller) go through
+the typed `forgejo-api` crate; only non-`/api/v1` web-router routes
+(attachment / artifact downloads, log streaming) and the poller's
+enrichment fetches of server-provided subject URLs stay on raw
+reqwest.
 
 ## Notification poller (`hive-ag3nt/src/forge_notify.rs`)
 
@@ -146,11 +151,14 @@ one path still marked-read directly (no read-before-comment value).
 
 The poller starts disabled and stays that way for any of:
 
-- `HIVE_FORGE_URL` not set (no forge configured for this hive).
+- `HIVE_FORGE_URL` not set (no forge configured for this hive), or
+  not parseable as a URL.
 - `<state>/forge-token` missing or empty (agent has no forge
   account — pre-provisioning or destroy-without-purge race).
-- Initial `reqwest::Client::builder` fails (extremely unlikely;
-  treated as fatal-to-the-task only).
+- Initial client construction fails (the typed `forgejo-api` client
+  for the API calls, or the plain reqwest client kept for the
+  best-effort enrichment fetches of server-provided subject URLs;
+  both extremely unlikely; treated as fatal-to-the-task only).
 
 Disabled = the spawned task returns immediately. All other failure
 modes (HTTP errors, parse errors, mark-read failures) are