toolbox: generated list help omits automatic pagination controls #15

Problem

Realmroot Toolbox inherits Restish automatic pagination: when a response exposes a next-page link, the client follows it automatically, up to 25 pages by default. This behavior is intentional. An OpenAPI --page-size option controls the server page size only; it does not limit total client traversal.

The generated resource-first operation help does not show the Toolbox pagination controls, so callers reasonably interpret --page-size 1 as a bounded one-item read and receive many page envelopes instead.

Observed with Realmroot CLI v0.5.0:

realmroot toolbox agent-kanban task list-tasks \
  --board-id <board-id> \
  --page-size 1 \
  --json

This automatically fetched 25 one-item pages and then warned that the page cap was reached.

The existing public control works:

realmroot toolbox agent-kanban task list-tasks \
  --board-id <board-id> \
  --page-size 1 \
  --no-paginate \
  --json

That returns exactly the first page. Raw internal --rsh-* flags are correctly rejected by Toolbox; callers must use the public aliases such as --no-paginate and --max-pages.

Expected behavior

Keep automatic pagination, but make it discoverable and unambiguous on generated list commands. Compact operation help should show that automatic pagination is enabled and expose the public controls.

Acceptance criteria

• Generated list-command help documents that --page-size is per-page rather than a total-result limit.
• Help exposes --no-paginate, --max-pages, and --max-items where pagination is supported.
• --no-paginate returns one page and preserves its normal page envelope.
• --max-pages 1 provides an equivalent bounded traversal while retaining the expected warning semantics.
• Tests cover the compact generated command surface and public-to-internal flag translation.

_{🤖 Created by Jarvis via Realmroot}