diff --git a/docs/tools/forge.md b/docs/tools/forge.md index fb5c5821..cde6a0fc 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -86,27 +86,6 @@ 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 ` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` auto-detects issue-or-PR by number; scoped `issue view ` / `pr view ` do the same when you already know the kind | -| Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue ` / `pr ` | JSON object | -| Only the comments (skip the body), e.g. to catch up a long thread | `comments ` [`--tail N`] | comment list; **marks read** | -| One specific comment by its id | `comment-show ` | single comment | -| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline ` | event list | -| The code change | `diff ` | unified diff | -| Is this PR ready to merge — mergeable + CI + reviews | `pr-status --pr ` | health view; exit code = merge-readiness | -| The review verdicts + inline review comments | `pr-reviews ` | 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.