From 7cc59c4338a8ffc558e3dc54b27a94ca7d201b8a Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive>
Date: Sun, 31 May 2026 15:10:54 +0200
Subject: [PATCH] hive-forge: update --tail field doc to match count-then-page
 impl (argus on #770)

---
 hive-forge/src/verbs/comments.rs | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/hive-forge/src/verbs/comments.rs b/hive-forge/src/verbs/comments.rs
index b18a3453..f27e3047 100644
--- a/hive-forge/src/verbs/comments.rs
+++ b/hive-forge/src/verbs/comments.rs
@@ -36,9 +36,11 @@ pub struct Args {
     /// Mutually exclusive with `--tail`.
     #[arg(long, default_value_t = 50, conflicts_with = "tail")]
     limit: u64,
-    /// Return the last `N` comments in chronological order. Pages
-    /// through every comment on the issue under the hood, then
-    /// slices the tail. Mutually exclusive with `--limit`.
+    /// Return the last `N` comments in chronological order. Reads
+    /// the issue's `comments` count first, then fetches only the
+    /// `ceil(N/50) + 1` pages that contain the tail — work is
+    /// bounded by N, not by thread length. Mutually exclusive with
+    /// `--limit`.
     #[arg(long)]
     tail: Option<usize>,
 }