diff --git a/docs/tools/forge.md b/docs/tools/forge.md
index 4970fe63..9c420f14 100644
--- a/docs/tools/forge.md
+++ b/docs/tools/forge.md
@@ -346,7 +346,12 @@ to discover valid label names before triaging or to audit the label set.
   most 50 rows. The stderr trailer (printed in `--json` mode too)
   reports the real total from the response's `X-Total-Count`
   (`… 50 of 187 shown … 137 more`), so trust the trailer, not the row
-  count, when deciding whether you've seen everything.
+  count, when deciding whether you've seen everything. The trailer
+  reports the rows shown so far, out of the total when the forge sent
+  one, plus a `re-run with --page N+1` hint. The last page prints no
+  trailer and no hint, so silence means the list is complete. Without
+  `X-Total-Count` it falls back to `N shown … more results may exist`
+  on a full page.
 - `repo-search` reads `X-Total-Count` the same way `list` does and warns
   with the real remaining count when it's present (`… 50 of 187 shown …
   137 more exist`); without it (an older forge, a stripping proxy) it