feat: next-page hint should mention --all (not just --page <token>)

[privatenumber]

Summary

When list/search output is capped at --max and more pages exist, gog prints a next-page hint to
stderr that only shows the page token. Surfacing --all would make full retrieval more
discoverable, especially for agents.

Current (v0.22.0, 197992a)

printNextPageHint (shared by ~39 commands) prints # Next page: --page <token>
(internal/cmd/output_helpers.go:52-57). The relevant flags are --all/--all-pages and --max
(e.g. internal/cmd/gmail_search.go:18,20).

Suggested fix

Enrich the shared hint, e.g. # More results: --all to fetch everything, or --page <token> for the next page. One change improves all ~39 commands.

Environment

gog v0.22.0 (confirmed by reading source at 197992a).

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 14, 2026, 12:40 PM ET / 16:40 UTC.

Summary
Keep open: current main and the latest release still print only # Next page: --page <token> from the shared pagination hint helper, while the existing paginated commands already expose --all, so the requested discoverability improvement remains valid and narrow.

Reproducibility: yes. Current source shows the shared helper emits only # Next page: --page <token> when a next page token is present; no live Google API call is needed to verify this deterministic hint text.

Next step
This is a narrow, aligned wording repair with clear source, test, and documentation touchpoints.

Review details

Best possible solution:

Update the shared pagination hint and its pinned tests/docs so commands that support full pagination advertise the existing full-page option consistently.

Do we have a high-confidence way to reproduce the issue?

Yes. Current source shows the shared helper emits only # Next page: --page <token> when a next page token is present; no live Google API call is needed to verify this deterministic hint text.

Is this the best way to solve the issue?

Yes. Updating the shared helper plus the tests/docs that pin the exact wording is the narrowest maintainable path because many commands already route through printNextPageHint.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 4a532bb86db2.

Label changes

Label changes:

• add P3: This is a low-risk discoverability improvement to an existing CLI hint.
• add impact:other: The issue affects CLI pagination ergonomics and agent discoverability, which falls outside the more specific impact labels.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk discoverability improvement to an existing CLI hint.
• impact:other: The issue affects CLI pagination ergonomics and agent discoverability, which falls outside the more specific impact labels.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd

What I checked:

• Repository policy: AGENTS.md was read fully; its output guidance is relevant because the request concerns keeping human hints on stderr while stdout remains parseable. (AGENTS.md:14, 4a532bb86db2)
• Vision fit: VISION.md says agent-friendly workflows and human-friendly command surfaces fit the project, which matches a shared pagination hint discoverability improvement. (VISION.md:15, 4a532bb86db2)
• Current helper text: printNextPageHint still writes # Next page: --page %s to stderr and does not mention --all. (internal/cmd/output_helpers.go:52, 4a532bb86db2)
• Existing pagination flags: A representative paginated command already has --max, --page, and --all/--all-pages, then calls the shared paging path. (internal/cmd/gmail_search.go:18, 4a532bb86db2)
• Pinned old wording: The output helper reference still documents the exact current hint format as # Next page: --page <token>. (docs/refactor/output.md:26, 4a532bb86db2)
• Latest release still matches main: The diff from v0.27.0 to current main is empty for the shared helper and output reference, so the latest release has the same old hint wording. (internal/cmd/output_helpers.go:52, 274a2a61da98)

Likely related people:

• Peter Steinberger: The available blame/log history shows the current shared pagination hint helper in the v0.27.0 release snapshot authored by Peter Steinberger. (role: recent area contributor; confidence: medium; commits: 274a2a61da98; files: internal/cmd/output_helpers.go, docs/refactor/output.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

🦞🔧
ClawSweeper is automatically building this issue.

The issue review finished and no active implementation pull request was found.

Automatic implementation progress:

• State: Blocked
• Detail: The automatic implementation worker stopped before all post-flight gates passed: checks are not clean: test: IN_PROGRESS, windows: IN_PROGRESS
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27505395405
• PR: fix(cli): mention all-pages flags in next-page hint #810
• Updated: 2026-06-14T17:08:09.079Z
• Opt out: add clawsweeper:manual-only or clawsweeper:human-review.

Result: implementation PR opened.

• PR: fix(cli): mention all-pages flags in next-page hint #810
• Branch: clawsweeper/issue-openclaw-gogcli-808
• Worker: https://github.com/openclaw/clawsweeper/actions/runs/27505395405
• Updated: 2026-06-14T16:58:03.187Z