diff --git a/docs/tools/forge.md b/docs/tools/forge.md
index cde6a0fc..1cd9e08b 100644
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@@ -86,6 +86,27 @@ 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)
 ```
 
+### Which read verb when
+
+Several verbs read an issue/PR and look overlapping, but each has a
+distinct output shape — pick by what you need:
+
+| Need | Verb | Shape |
+|------|------|-------|
+| The full human view of one item — title, body, **and** every comment in order | `view <n>` | prose dump; **marks the thread read** (clears the read-before-comment guard) |
+| Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue <n>` / `pr <n>` | JSON object |
+| Only the comments (skip the body), e.g. to catch up a long thread | `comments <n>` [`--tail N`] | comment list; **marks read** |
+| One specific comment by its id | `comment-show <id>` | single comment |
+| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list |
+| The code change | `diff <n>` | unified diff |
+| Is this PR ready to merge — mergeable + CI + reviews | `pr-status --pr <n>` | health view; exit code = merge-readiness |
+| The review verdicts + inline review comments | `pr-reviews <n>` | review list |
+
+Rule of thumb: **`view` first** when you're about to act on a thread (it
+shows everything and clears the unread guard so your follow-up `comment`
+isn't rejected); the JSON verbs (`issue`/`pr`) when a script needs one
+field; `pr-status` when the only question is "can I merge it".
+
 ### Contributing to a read-only repo (`clone` + `pr-create --agit`)
 
 Agents are read-only collaborators on some repos (e.g.