Bound paged retrieval responses

docs/COMPATIBILITY.md

@@ -72,6 +72,10 @@ Milestone 0 preserves:
   version 3 adds a source-ordered incoming-edge index for bounded impact traversal.
 - Index-attestation schema version 1.
 - Incremental extraction-cache schema version 1.
+- Read-pagination schema version 1. Existing tool names and required arguments are unchanged.
+  Context and changeset MCP reads accept optional limits and opaque generation-bound cursors.
+  Direct Python changeset methods and the ordinary CLI context command retain full legacy results
+  when pagination is not requested.
 
 Indexes, attestations, extraction caches, previews, and rendered artifacts are disposable. A schema
 change may rebuild them. Canonical project content and stored proposals may not be silently
@@ -154,7 +158,10 @@ Milestone 0 records rather than redesigns these areas:
 - Tree-sitter and the JavaScript and C++ grammars remain mandatory installation dependencies even
   when their runtime modules are unused.
 - Several version strings and defaults remain duplicated.
-- Large changeset results and context responses need compact receipt or pagination contracts.
+- One individually oversized context entry is represented as explicit bounded omission evidence;
+  callers use targeted retrieval for that node.
+- One individually oversized changeset diff is transported as reconstructable canonical-JSON
+  chunks. Cursors are corruption-detecting read tokens, not authenticated authorization tokens.
 - Manual planning is not separated from rendering.
 - There is no portable graph-planning or graph-rendering contract.
 - DocForge2 does not self-host its bootstrap documentation.

docs/MCP_CONTRACT.md

@@ -49,6 +49,20 @@ project `max_results` policy. Omitted limits are still capped. Collection respon
 they were truncated. Traversal also reports whether truncation came from the result limit or its
 deterministic candidate-edge work budget; it does not scan or materialize the complete edge table.
 
+`docforge_get_context` accepts optional `limit` and `cursor` arguments. Its page is one deterministic
+stream containing selected entries first and explicit omission evidence second. The page receipt
+reports the returned count, total evidence count, whether another page exists, and an opaque
+generation-bound cursor. Packing also observes the configured MCP response limit. An individually
+oversized entry advances as a hash-identified `response size limit` omission so pagination cannot
+loop; targeted retrieval remains available for that node. The existing three-argument custom
+context-provider contract is unchanged because pagination is applied after provider selection.
+
+Version-1 cursors are canonical JSON encoded as base64url with a domain-separated SHA-256
+corruption checksum. They are opaque and fail closed, but are not authenticated authorization
+tokens. Cursors bind the project, adapter, source generation, operation parameters, collection
+hash, and position. A changed generation or collection returns `stale_cursor` with
+`restart_pagination`; DocForge never silently restarts at page one or combines generations.
+
 Adapter-backed servers also validate their process-start implementation fingerprint before every
 tool. `adapter_restart_required` is stale but not synchronizable. Its remediation is
 `restart_project_server`; the current process does not reload project code, update Git staging, or
@@ -101,6 +115,15 @@ Changeset listing returns draft and ready work by default. Stale, applied, and a
 remain available through an explicit status or history request. Applied and abandoned proposals no
 longer participate in overlap conflict detection.
 
+Changeset list, inspection, validation, and diff reads accept optional `limit` and `cursor`
+arguments. Direct Python and CLI methods still return their complete legacy result when pagination
+is not requested. MCP defaults to bounded pages while preserving the exact changeset hash and
+ordered operation sequence. Pages may contain fewer records than requested to remain inside the
+response policy. Oversized inspection or validation pages return deterministic operation summaries
+with hashes and character counts. An individually oversized diff becomes a sequence of
+`canonical_json_chunk` pages; concatenating the ASCII chunks, decoding the JSON, and verifying its
+payload hash reconstructs the exact `operations` and `changes` arrays without duplication.
+
 Successful mutations return their existing full result while it fits the configured output limit.
 Before any proposal, preview, or canonical mutation, the server verifies that a minimum exact
 success receipt can fit. An impossible receipt fails with `result_too_large`,

docs/USER_MANUAL.md

@@ -477,7 +477,7 @@ filter [--family X] [--authority X] [--status X] [--tag X] [--limit N]
 backlinks NODE_ID [--relation RELATION] [--limit N]
 dependencies NODE_ID [--depth N] [--limit N]
 impact NODE_ID [--depth N] [--limit N]
-context PROFILE [--budget N]
+context PROFILE [--budget N] [--limit N] [--cursor OPAQUE]
 ```
 
 ### Render and proposal commands
@@ -641,6 +641,22 @@ an explicit `status="stale"` query for rebase decisions. Applied and abandoned p
 terminal history, remain available by status or history request, and no longer block new proposals
 against the same canonical base.
 
+Context and changeset reads use version-1 continuation receipts when their evidence exceeds one
+page. Follow `pagination.next_cursor` with the same tool and semantic arguments until
+`pagination.has_more` is false. Page size may change between calls. Treat the cursor as opaque.
+It is bound to the project, adapter, source generation, query, exact changeset hash, and collection
+identity. `stale_cursor` means evidence changed between pages; discard prior pages and restart the
+read instead of mixing generations.
+
+`docforge_get_context` paginates one ordered evidence stream: selected entries followed by explicit
+omissions. An entry too large for one MCP response is represented by a bounded omission carrying
+its node ID and detail hash, and the cursor advances. `docforge_list_changesets`,
+`docforge_get_changeset`, `docforge_validate_changeset`, and `docforge_get_changeset_diff` accept
+the same optional `limit` and `cursor` fields. Small results keep their familiar fields. Large
+inspection pages may use hash summaries. A large diff may return `result_mode =
+"canonical_json_chunk"`; concatenate the chunks in order and verify `payload_hash` before decoding
+the reconstructed `operations` and `changes` object.
+
 Canonical application records its terminal receipt immediately after the project-owned serializer
 verifies the new canonical state. A later index or render refresh failure is reported as degraded
 derived state with remediation, not as permission to apply the same canonical change again.