fix(cli): mention all-pages flags in next-page hint

[clawsweeper]

Fixes #808

Summary

• update the shared next-page stderr hint to mention full-pagination flags alongside --page <token>
• refresh exact-string tests that pin the hint text
• update docs/refactor/output.md so the documented helper contract matches the new output

Notes

This is a discoverability-only wording change. It keeps stdout parseable, keeps the hint on stderr, and does not add flags or change pagination behavior.

Source issue credit: reported by @privatenumber in #808.

Validation

• go test -vet=off ./internal/cmd
• make test

ClawSweeper 🐠 replacement reef notes:

• Cluster: issue-openclaw-gogcli-808
• Source PRs: none
• Credit: Source issue: feat: next-page hint should mention --all (not just --page <token>) #808 by @privatenumber.; No source PRs are being replaced; preserve issue attribution in the PR body.
• Validation: go test -vet=off ./internal/cmd; make test
• Replacement reason: ClawSweeper could not update the source PR branch directly, so it opened a writable replacement PR instead.

fish notes: reasoning high; reviewed against 9df015c.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 15, 2026, 1:30 AM ET / 05:30 UTC.

Summary
This PR adds a flag-aware next-page hint helper, switches paginated commands with full-page flags to it, updates exact stderr tests, and documents the helper contract.

Reproducibility: yes. Current main’s shared helper deterministically emits only the page-token hint, while representative commands already expose full-page flags, so no live Google API call is needed to verify the wording gap.

Review metrics: 2 noteworthy metrics.

• Touched surface: 42 files, +58/-50. The wording change is broad across command call sites even though each edit is small.
• Helper rollout: 44 call sites switched, 1 helper added. The count confirms the PR updates the full-pagination hint paths while leaving the old helper available for page-only commands.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Next step before merge

• [P2] A collaborator explicitly stopped automation and left this PR for human review; no repair lane is needed because there are no blocking findings.

Security
Cleared: No security or supply-chain concern found; the diff is limited to CLI output wording, tests, and internal docs.

Review details

Best possible solution:

Land the focused wording PR after maintainer review and exact-head checks, preserving the old helper for commands that only support page-token navigation.

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

Yes. Current main’s shared helper deterministically emits only the page-token hint, while representative commands already expose full-page flags, so no live Google API call is needed to verify the wording gap.

Is this the best way to solve the issue?

Yes. Adding a small helper that accepts exact supported flag text and using it only on commands with full-pagination flags is narrower than changing pagination behavior or adding flags.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 23b847ca53cf.

Label changes

Label justifications:

• P3: This is a low-risk CLI discoverability and ergonomics improvement to existing pagination output.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This is a ClawSweeper bot PR with maintainer handling, so the external-contributor real behavior proof gate does not apply.

Evidence reviewed

What I checked:

• Repository policy applied: AGENTS.md was read fully; its stdout/stderr guidance is relevant because the PR keeps human pagination hints on stderr while leaving parseable stdout untouched. (AGENTS.md:21, 23b847ca53cf)
• Current main still has the old hint: The shared helper on current main only writes # Next page: --page %s, so the central requested wording is not already implemented. (internal/cmd/output_helpers.go:56, 23b847ca53cf)
• Existing commands already expose full-page flags: A representative paginated command exposes --all with all-pages aliases, which supports the requested discoverability change without adding behavior. (internal/cmd/gmail_search.go:20, 23b847ca53cf)
• PR implements a narrow helper path: The PR keeps the old helper and adds printNextPageHintWithAll, then uses exact supported flag text at full-pagination call sites. (internal/cmd/output_helpers.go:59, 30fa95935e40)
• Diff scope measured: The PR changes 42 files with 58 additions and 50 deletions; diff inspection counted 44 existing call-site switches plus one helper and one docs reference. (30fa95935e40)
• Latest release does not already ship it: The checked helper/docs paths have no diff from v0.27.0 to current main, and v0.27.0 still points at the release commit whose helper blame shows the old wording. (internal/cmd/output_helpers.go:56, 274a2a61da98)

Likely related people:

• steipete: Current-main blame/log history attributes the shared pagination helper, output-helper docs, and representative pagination flag fields to the v0.27.0 release-prep commit, and this collaborator also paused automation on the PR. (role: recent area contributor; confidence: medium; commits: 274a2a61da98, 30fa95935e40; files: internal/cmd/output_helpers.go, docs/refactor/output.md, internal/cmd/gmail_search.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

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 saw the passing review, but did not merge yet.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=9df015c8f966459756168af27279bd530520e85d)
Merge status: PR is in ClawSweeper autofix mode; merge is disabled

I left the PR open for the remaining gate instead of bypassing it.

Automerge progress:

• 2026-06-15 04:42:55 UTC review passed 9df015c8f966 (structured ClawSweeper verdict: pass (sha=9df015c8f966459756168af27279bd530520e...)

[steipete]

@clawsweeper stop

[clawsweeper]

🦞✅
Got it. ClawSweeper will leave this item for human review.

I added clawsweeper:human-review and paused the automation trail until a maintainer asks again.