docs: propose cursor-first pagination (--limit/--continue)

[jpage-godaddy]

Summary

• Proposes an additive --limit/--continue cursor-based pagination option in cli_engine (CommandSpec::with_cursor), coexisting permanently with the existing --limit/--offset (CommandSpec::with_pagination)
• Proposes gddy adopt the cursor pattern universally across its own commands, as a separate, deliberate breaking change scoped to the consumer app rather than the framework

Motivation

Grounded in concrete findings from building the current --limit/--offset adapters (passthrough_paginate, page_size_paginate, cursor_paginate) against real backends this milestone — see the doc for specifics, including the O(N²) sequential-walk cost a pure cursor backend pays under the current offset-based design.

Test plan

• Docs-only change; no code affected
• Review comments/discussion resolved via the copilot review loop

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new proposal document contains several concrete inconsistencies/typos (including a mismatched flag name and a 5-vs-4 command count) that should be corrected before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new design proposal document describing an additive cursor-first pagination option (--limit/--continue) for cli_engine, while recommending a separate, intentional breaking change for the gddy consumer CLI to adopt cursor pagination universally.

Changes:

• Introduces a new proposal doc outlining motivation, goals, and tradeoffs for cursor-based pagination in the framework.
• Describes a parallel CommandSpec::with_cursor / CursorConfig API alongside the existing with_pagination / PaginationConfig.
• Discusses required envelope/human-output semantics changes to support cursor backends that may not know total/offset.

File summaries

File	Description
cli-engine/docs/proposals/cursor-first-pagination.md	New proposal document defining cursor-first pagination flags, API surface, envelope implications, and prior-art references.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The proposal text currently states the O(N²) behavior in a way that can be read as applying to cursor pagination generally rather than specifically to offset-emulation over a cursor backend.

Review details

Suppressed comments (1)

cli-engine/docs/proposals/cursor-first-pagination.md:19

• The complexity claim here reads as if cursor pagination itself is O(N²), but the O(N²) behavior only happens when a cursor-backed API is forced through an offset-based interface (restarting from the beginning for non-zero offsets). Also, "Slice-based" is inconsistent with the earlier "Slicing" pattern name.

❌ The Cursor pattern, on the other hand, is a terrible fit for adaptation to Slice-based arguments, especially if there is a server-persisted cursor state. Although it works ok starting at an offset of 0, fetching a second page of data requires starting over from the beginning, iterating over prior data simply to throw it away. There's no defined way to skip ahead. Reading a whole cursor-backed list sequentially costs O(N²) page fetches, not O(N). This is not an edge case; it is the common "give me the next batch" path for this exact backend shape.

• Files reviewed: 1/1 changed files
• Comments generated: 0 new
• Review effort level: Lite