@farming-labs/docs 0.2.74 → 0.2.77

package/dist/{search-DIyIl-tE.mjs → search-Da2AKaFJ.mjs}

@@ -1,4 +1,4 @@
-import { G as isDocsAgentDiscoveryRequest, K as isDocsAgentsRequest, Q as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, jt as resolveDocsAudienceMdxContent, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-BJ0KXN-A.mjs";
+import { G as isDocsAgentDiscoveryRequest, K as isDocsAgentsRequest, Q as isDocsSkillRequest, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, jt as resolveDocsAudienceMdxContent, lt as resolveDocsAgentFeedbackConfig, pt as resolveDocsLlmsTxtRequest, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-SRIJ-oF8.mjs";
 import { S as upsertPageAgentContractMarkdown, a as findDocsGeneratedAgentContractRanges, d as PAGE_AGENT_CONTRACT_END_MARKER, l as stripDocsGeneratedAgentContractMarkers, m as PAGE_AGENT_CONTRACT_START_MARKER, o as findDocsMarkdownSection, s as parseDocsMarkdownSections, y as renderPageAgentContractMarkdown } from "./markdown-sections-7OoA7ylx.mjs";
 
 //#region src/telemetry.ts
@@ -624,6 +624,103 @@ function digestDocsRetrievalContent(value) {
 	return `sha256:${Array.from(state, (word) => word.toString(16).padStart(8, "0")).join("")}`;
 }
 
+//#endregion
+//#region src/pagination.ts
+const DOCS_PAGINATION_CURSOR_VERSION = 1;
+const MAX_DOCS_PAGINATION_CURSOR_CHARS = 4096;
+const MAX_DOCS_PAGINATION_STATE_CHARS = 1024;
+const MAX_DOCS_PAGINATION_OFFSET = 1e7;
+const DOCS_PAGINATION_DIGEST_PATTERN = /^sha256:[a-f\d]{64}$/u;
+var DocsPaginationCursorError = class extends Error {
+	code = "invalid_cursor";
+	constructor() {
+		super("Invalid or stale pagination cursor.");
+		this.name = "DocsPaginationCursorError";
+	}
+};
+function paginationDigest(label, value) {
+	return digestDocsRetrievalContent(`${label}\0${value}`);
+}
+function cursorChecksum(payload) {
+	return paginationDigest("docs-pagination-checksum.v1", JSON.stringify(payload));
+}
+function encodeBase64Url(value) {
+	const bytes = new TextEncoder().encode(value);
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
+}
+function decodeBase64Url(value) {
+	const padded = `${value.replace(/-/gu, "+").replace(/_/gu, "/")}${"=".repeat((4 - value.length % 4) % 4)}`;
+	const binary = atob(padded);
+	const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+	return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function isDigest(value) {
+	return typeof value === "string" && DOCS_PAGINATION_DIGEST_PATTERN.test(value);
+}
+function assertCursorOptions(options) {
+	if (!/^[a-z][a-z\d._/-]{0,127}$/u.test(options.kind) || typeof options.scope !== "string" || typeof options.snapshot !== "string") throw new TypeError("Pagination cursor options must contain a valid kind, scope, and snapshot.");
+}
+function createDocsPaginationCursor(offset, options) {
+	assertCursorOptions(options);
+	if (!Number.isSafeInteger(offset) || offset <= 0 || offset > MAX_DOCS_PAGINATION_OFFSET) throw new TypeError("Pagination cursor offsets must be positive safe integers.");
+	if (options.state !== void 0 && (options.state.length === 0 || options.state.length > MAX_DOCS_PAGINATION_STATE_CHARS)) throw new TypeError("Pagination provider state must be a bounded, non-empty string.");
+	const unsigned = [
+		DOCS_PAGINATION_CURSOR_VERSION,
+		options.kind,
+		offset,
+		paginationDigest("docs-pagination-scope.v1", options.scope),
+		paginationDigest("docs-pagination-snapshot.v1", options.snapshot),
+		options.state ?? null
+	];
+	return encodeBase64Url(JSON.stringify([...unsigned, cursorChecksum(unsigned)]));
+}
+function resolveDocsPaginationCursor(cursor, options) {
+	assertCursorOptions(options);
+	if (cursor === void 0) return { offset: 0 };
+	if (cursor.length === 0 || cursor.length > MAX_DOCS_PAGINATION_CURSOR_CHARS || !/^[A-Za-z\d_-]+$/u.test(cursor)) throw new DocsPaginationCursorError();
+	let parsed;
+	try {
+		parsed = JSON.parse(decodeBase64Url(cursor));
+	} catch {
+		throw new DocsPaginationCursorError();
+	}
+	if (!Array.isArray(parsed) || parsed.length !== 7 || encodeBase64Url(JSON.stringify(parsed)) !== cursor) throw new DocsPaginationCursorError();
+	const [version, kind, offset, scopeDigest, snapshotDigest, state, checksum] = parsed;
+	const unsigned = [
+		version,
+		kind,
+		offset,
+		scopeDigest,
+		snapshotDigest,
+		state
+	];
+	if (version !== DOCS_PAGINATION_CURSOR_VERSION || kind !== options.kind || !Number.isSafeInteger(offset) || offset <= 0 || offset > MAX_DOCS_PAGINATION_OFFSET || !isDigest(scopeDigest) || !isDigest(snapshotDigest) || !(state === null || typeof state === "string" && state.length > 0 && state.length <= MAX_DOCS_PAGINATION_STATE_CHARS) || !isDigest(checksum) || scopeDigest !== paginationDigest("docs-pagination-scope.v1", options.scope) || snapshotDigest !== paginationDigest("docs-pagination-snapshot.v1", options.snapshot) || checksum !== cursorChecksum(unsigned)) throw new DocsPaginationCursorError();
+	return {
+		offset,
+		...typeof state === "string" ? { state } : {}
+	};
+}
+function resolveDocsPaginationOffset(cursor, options) {
+	return resolveDocsPaginationCursor(cursor, options).offset;
+}
+function paginateDocsItems(items, options) {
+	if (!Number.isSafeInteger(options.pageSize) || options.pageSize <= 0) throw new TypeError("Pagination page sizes must be positive safe integers.");
+	const offset = resolveDocsPaginationOffset(options.cursor, options);
+	if (offset >= items.length && options.cursor !== void 0) throw new DocsPaginationCursorError();
+	const pageItems = items.slice(offset, offset + options.pageSize);
+	const nextOffset = offset + pageItems.length;
+	const hasMore = nextOffset < items.length;
+	return {
+		items: pageItems,
+		resultCount: pageItems.length,
+		total: items.length,
+		hasMore,
+		...hasMore ? { nextCursor: createDocsPaginationCursor(nextOffset, options) } : {}
+	};
+}
+
 //#endregion
 //#region src/agent-scope.ts
 /** Normalize framework aliases used by page metadata, agent contracts, MCP, and evaluations. */
@@ -947,6 +1044,7 @@ function agentVersionConstraintsOverlap(left, right) {
 //#endregion
 //#region src/search.ts
 const DEFAULT_SEARCH_LIMIT = 10;
+const MAX_STRUCTURED_SEARCH_LIMIT = 25;
 const MAX_SEARCH_SNIPPET_CHARS = 160;
 const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const MCP_SESSION_CLEANUP_TIMEOUT_MS = 1e3;
@@ -959,8 +1057,14 @@ const MAX_SEARCH_FILTER_VALUES = 16;
 const MAX_SEARCH_FILTER_VALUE_CHARS = 128;
 const MAX_SEARCH_FILTER_RAW_CHARS = 4096;
 const MAX_SEARCH_FILTER_SEGMENTS = 64;
+const MAX_SEARCH_PROVIDER_CURSOR_STATE_CHARS = 1024;
 const MAX_PROVIDER_SCOPE_FILTER_IDS = 1e3;
 const MAX_PROVIDER_SCOPE_FILTER_CHARS = 16e3;
+const MAX_HOSTED_PROVIDER_CURSOR_RESULTS = 1e3;
+const MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES = 64;
+const MAX_MCP_SEARCH_CURSOR_RESULTS = MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES;
+const DOCS_UNPAGINATED_PROVIDER_QUERY = Symbol("docs-unpaginated-provider-query");
+const DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW = Symbol("docs-provider-scope-filter-overflow");
 const ALGOLIA_BATCH_OPERATIONS = 1e3;
 const MAX_SEARCH_WARNINGS = 16;
 const MAX_SEARCH_WARNING_VALUES = 16;
@@ -1057,11 +1161,41 @@ function resolveDocsSearchFilters(searchParams) {
 		tags: searchParams.getAll("tags")
 	});
 }
+var DocsSearchRequestError = class extends Error {
+	code = "invalid_search_request";
+	constructor(message) {
+		super(message);
+		this.name = "DocsSearchRequestError";
+	}
+};
+function resolveDocsSearchError(error) {
+	if (error instanceof DocsPaginationCursorError) return {
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof DocsSearchRequestError) return {
+		code: error.code,
+		message: error.message
+	};
+}
 /** Resolve search filters and the backwards-compatible structured response opt-in. */
 function resolveDocsSearchRequest(searchParams) {
+	const structured = searchParams.get("response") === "structured";
+	const cursor = searchParams.get("cursor") ?? void 0;
+	if (cursor !== void 0 && !structured) throw new DocsSearchRequestError("Search cursors require the structured response format (`response=structured`).");
+	if (cursor !== void 0 && (cursor.length === 0 || cursor.length > 4096 || !/^[A-Za-z\d_-]+$/u.test(cursor))) throw new DocsPaginationCursorError();
+	const rawLimit = searchParams.get("limit");
+	let limit;
+	if (rawLimit !== null && structured) {
+		if (!/^\d+$/u.test(rawLimit)) throw new DocsSearchRequestError("Search limit must be an integer between 1 and 25.");
+		limit = Number(rawLimit);
+		if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_STRUCTURED_SEARCH_LIMIT) throw new DocsSearchRequestError("Search limit must be an integer between 1 and 25.");
+	}
 	return {
 		filters: resolveDocsSearchFilters(searchParams),
-		structured: searchParams.get("response") === "structured"
+		structured,
+		...cursor !== void 0 ? { cursor } : {},
+		...limit !== void 0 ? { limit } : {}
 	};
 }
 function hasDocsSearchFilters(filters) {
@@ -1071,7 +1205,7 @@ function resolveProviderScopeDocumentIds(query, context, corpusId) {
 	if (!hasDocsSearchFilters(query.filters ?? {})) return void 0;
 	const documents = corpusId ? buildDocsSearchDocuments(context.pages, context.chunking ?? { strategy: "section" }, "human") : context.documents;
 	const ids = Array.from(new Set(documents.map((document) => corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id)));
-	return ids.length <= MAX_PROVIDER_SCOPE_FILTER_IDS ? ids : [];
+	return ids.length <= MAX_PROVIDER_SCOPE_FILTER_IDS ? ids : DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW;
 }
 function docsSearchFiltersMatch(expected, actual) {
 	return SEARCH_FILTER_FIELDS.every((field) => {
@@ -2257,8 +2391,12 @@ function cleanSearchResultText(value) {
 	if (!value) return void 0;
 	return normalizeWhitespace(stripHtml(stripMarkdownText(value))) || void 0;
 }
+function getHostedIndexGenerationTag(indexGeneration) {
+	return `docs-generation:${indexGeneration}`;
+}
 function buildAlgoliaRecord(document, corpusId) {
 	const providerDocumentId = corpusId ? makeHostedProviderDocumentId(corpusId, document.id) : document.id;
+	const generationTag = document.source?.indexGeneration ? getHostedIndexGenerationTag(document.source.indexGeneration) : void 0;
 	const record = {
 		objectID: providerDocumentId,
 		id: providerDocumentId,
@@ -2273,7 +2411,7 @@ function buildAlgoliaRecord(document, corpusId) {
 		version: document.version,
 		package: document.package,
 		tags: document.tags,
-		_tags: corpusId ? [corpusId] : void 0,
+		_tags: corpusId || generationTag ? [corpusId, generationTag].filter((value) => Boolean(value)) : void 0,
 		...serializeHostedRetrievalSource(document.source, corpusId, document.id)
 	};
 	const encoder = new TextEncoder();
@@ -2313,39 +2451,50 @@ function buildAlgoliaRecord(document, corpusId) {
 	if (sizeOf(record) > ALGOLIA_MAX_RECORD_BYTES) throw new Error(`Algolia record ${document.id} still exceeds the record limit after trimming.`);
 	return record;
 }
+async function searchSimpleDocsPage(query, context) {
+	const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
+	const offset = query.offset ?? 0;
+	const matches = context.documents.map((document) => ({
+		document,
+		score: scoreDocument(query.query, document)
+	})).filter((item) => item.score > 0).sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score;
+		return a.document.url.localeCompare(b.document.url);
+	});
+	const results = matches.slice(offset, offset + limit).map(({ document, score }) => ({
+		id: document.id,
+		url: document.url,
+		content: cleanSearchResultText(document.section ? `${document.title} — ${document.section}` : document.title) ?? (document.section ? `${document.title} — ${document.section}` : document.title),
+		description: cleanSearchResultText(buildSnippet(document, query.query) ?? document.description),
+		type: document.type,
+		score,
+		section: document.section,
+		source: document.source
+	}));
+	return {
+		results: context.deferSourceProvenance ? results : await enrichDocsSearchResultsWithSources({
+			results,
+			pages: context.pages,
+			audience: resolveDocsSearchAudience(context.audience),
+			chunking: context.chunking ?? { strategy: "section" },
+			locale: query.locale ?? context.locale,
+			baseUrl: context.baseUrl,
+			indexGeneration: context.indexGeneration,
+			filters: query.filters
+		}),
+		total: matches.length
+	};
+}
 function createSimpleSearchAdapter() {
 	return {
 		name: "simple",
 		async search(query, context) {
-			const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
-			const results = context.documents.map((document) => ({
-				document,
-				score: scoreDocument(query.query, document)
-			})).filter((item) => item.score > 0).sort((a, b) => {
-				if (b.score !== a.score) return b.score - a.score;
-				return a.document.url.localeCompare(b.document.url);
-			}).slice(0, limit).map(({ document, score }) => ({
-				id: document.id,
-				url: document.url,
-				content: cleanSearchResultText(document.section ? `${document.title} — ${document.section}` : document.title) ?? (document.section ? `${document.title} — ${document.section}` : document.title),
-				description: cleanSearchResultText(buildSnippet(document, query.query) ?? document.description),
-				type: document.type,
-				score,
-				section: document.section,
-				source: document.source
-			}));
-			if (context.deferSourceProvenance) return results;
-			return enrichDocsSearchResultsWithSources({
-				results,
-				pages: context.pages,
-				audience: resolveDocsSearchAudience(context.audience),
-				chunking: context.chunking ?? { strategy: "section" },
-				locale: query.locale ?? context.locale,
-				baseUrl: context.baseUrl,
-				indexGeneration: context.indexGeneration,
-				filters: query.filters
-			});
-		}
+			return (await searchSimpleDocsPage({
+				...query,
+				offset: 0
+			}, context)).results;
+		},
+		searchPage: searchSimpleDocsPage
 	};
 }
 function normalizeDocsSearchConfig(search) {
@@ -2373,6 +2522,46 @@ function normalizeDocsSearchConfig(search) {
 		raw: search
 	};
 }
+function getDocsSearchPaginationProviderIdentity(search) {
+	const raw = search.raw;
+	if (raw?.provider === "algolia") return {
+		provider: "algolia",
+		appId: raw.appId,
+		indexName: raw.indexName,
+		syncNamespace: raw.syncNamespace?.trim() || void 0
+	};
+	if (raw?.provider === "typesense") return {
+		provider: "typesense",
+		baseUrl: raw.baseUrl,
+		collection: raw.collection,
+		mode: raw.mode ?? "keyword",
+		queryBy: raw.queryBy ?? [
+			"title",
+			"section",
+			"content",
+			"description"
+		],
+		embeddings: raw.embeddings ? {
+			provider: raw.embeddings.provider,
+			model: raw.embeddings.model,
+			baseUrl: raw.embeddings.baseUrl ?? "http://127.0.0.1:11434"
+		} : void 0,
+		syncNamespace: raw.syncNamespace?.trim() || void 0
+	};
+	if (raw?.provider === "mcp") return {
+		provider: "mcp",
+		endpoint: raw.endpoint,
+		toolName: raw.toolName ?? "search_docs",
+		protocolVersion: raw.protocolVersion ?? DEFAULT_MCP_PROTOCOL_VERSION,
+		forwardAudience: raw.forwardAudience === true
+	};
+	if (raw?.provider === "custom") return {
+		provider: "custom",
+		adapterName: typeof raw.adapter === "object" && raw.adapter ? raw.adapter.name : void 0,
+		paginationRevision: raw.paginationRevision?.trim() || void 0
+	};
+	return { provider: search.provider };
+}
 async function readResponseJson(response) {
 	const text = await response.text();
 	return text ? JSON.parse(text) : null;
@@ -2688,7 +2877,7 @@ async function ensureTypesenseImportSucceeded(response, expectedRecords) {
 	}
 }
 function createTypesenseSearchAdapter(config) {
-	return {
+	const adapter = {
 		name: "typesense",
 		async index(context) {
 			const adminApiKey = config.adminApiKey ?? config.apiKey;
@@ -2733,9 +2922,23 @@ function createTypesenseSearchAdapter(config) {
 			}), docsForImport.length);
 		},
 		async search(query, context) {
+			return (await adapter.searchPage({
+				...query,
+				offset: 0,
+				[DOCS_UNPAGINATED_PROVIDER_QUERY]: true
+			}, context)).results;
+		},
+		async searchPage(query, context) {
+			const exactPagination = !query[DOCS_UNPAGINATED_PROVIDER_QUERY];
 			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
 			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
-			if (scopedDocumentIds?.length === 0) return [];
+			if (scopedDocumentIds === DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW) throw new Error("Typesense scope filters exceed the provider pagination limit.");
+			if (scopedDocumentIds?.length === 0) return {
+				results: [],
+				total: 0
+			};
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			if ((query.offset ?? 0) % pageSize !== 0) throw new Error("Typesense search offset does not match its page boundary.");
 			const params = new URLSearchParams({
 				q: query.query,
 				query_by: (config.queryBy ?? [
@@ -2744,18 +2947,23 @@ function createTypesenseSearchAdapter(config) {
 					"content",
 					"description"
 				]).join(","),
-				per_page: String(query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT),
+				per_page: String(pageSize),
 				prioritize_exact_match: "true",
 				num_typos: "2",
-				highlight_fields: "content,title,section,description"
+				highlight_fields: "content,title,section,description",
+				page: String(Math.floor((query.offset ?? 0) / pageSize) + 1)
 			});
 			if (config.mode === "hybrid" && config.embeddings) {
 				const vector = await createOllamaEmbedding(query.query, config.embeddings, context.signal);
 				params.set("vector_query", `embedding:([${vector.join(",")}],k:${Math.max((query.limit ?? 10) * 4, 20)})`);
 			}
-			const filterClauses = [corpusId ? `source_corpus_id:=${quoteTypesenseFilterValue(corpusId)}` : void 0, scopedDocumentIds ? `id:=[${scopedDocumentIds.map(quoteTypesenseFilterValue).join(",")}]` : void 0].filter((value) => Boolean(value));
+			const filterClauses = [
+				corpusId ? `source_corpus_id:=${quoteTypesenseFilterValue(corpusId)}` : void 0,
+				context.indexGeneration ? `source_index_generation:=${quoteTypesenseFilterValue(context.indexGeneration)}` : void 0,
+				scopedDocumentIds ? `id:=[${scopedDocumentIds.map(quoteTypesenseFilterValue).join(",")}]` : void 0
+			].filter((value) => Boolean(value));
 			const filterBy = filterClauses.length > 0 ? filterClauses.join(" && ") : void 0;
-			if (filterBy && filterBy.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) return [];
+			if (filterBy && filterBy.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) throw new Error("Typesense scope filters exceed the provider pagination limit.");
 			const response = filterBy ? await fetch(`${getTypesenseSearchBase(config)}/multi_search`, {
 				method: "POST",
 				headers: {
@@ -2774,7 +2982,9 @@ function createTypesenseSearchAdapter(config) {
 			});
 			ensureOk(response, "Typesense search failed");
 			const rawPayload = await readResponseJson(response);
-			return ((filterBy ? rawPayload.results?.[0] ?? {} : rawPayload).hits ?? []).flatMap((hit) => {
+			const payload = filterBy ? rawPayload.results?.[0] ?? {} : rawPayload;
+			if (exactPagination && payload.search_cutoff !== void 0 && payload.search_cutoff !== false) throw new Error("Typesense search was cut off before exact pagination completed.");
+			const results = (payload.hits ?? []).flatMap((hit) => {
 				const document = hit.document ?? {};
 				if (!hostedRecordMatchesCorpus(document, corpusId)) return [];
 				const section = typeof document.section === "string" ? document.section : void 0;
@@ -2797,8 +3007,18 @@ function createTypesenseSearchAdapter(config) {
 					...source ? { source } : {}
 				}];
 			});
+			const exactTotal = typeof payload.found === "number" && Number.isSafeInteger(payload.found) && payload.found >= 0 ? payload.found : void 0;
+			if (exactPagination && exactTotal === void 0) throw new Error("Typesense search did not return an exact result total.");
+			const total = exactTotal ?? results.length;
+			if (exactPagination && total > MAX_HOSTED_PROVIDER_CURSOR_RESULTS) throw new Error("Typesense search exceeds the exact cursor pagination window.");
+			if (exactPagination && (query.offset ?? 0) + results.length < total && results.length !== pageSize) throw new Error("Typesense search returned an incomplete non-final page.");
+			return {
+				results,
+				total
+			};
 		}
 	};
+	return adapter;
 }
 function resolveSearchRequestConfig(search, requestUrl) {
 	if (!search || search === true || typeof search !== "object" || search.provider !== "mcp") return search;
@@ -2832,44 +3052,60 @@ function resolveAskAISearchRequestConfig(options) {
 	}, options.requestUrl);
 }
 function createMcpSearchAdapter(config) {
-	return {
-		name: "mcp",
-		async search(query, context) {
-			const endpoint = resolveMcpEndpoint(config.endpoint);
-			const protocolVersion = config.protocolVersion ?? DEFAULT_MCP_PROTOCOL_VERSION;
-			const toolName = config.toolName ?? "search_docs";
-			const forwardAudience = config.forwardAudience === true;
-			const audience = resolveDocsSearchAudience(query.audience);
-			const baseHeaders = config.headers ?? {};
-			if (audience === "human" && !forwardAudience) throw new Error("MCP human-projection search requires forwardAudience: true on an audience-aware tool.");
-			const initializeResponse = await fetch(endpoint, {
+	async function runMcpSearch(query, context, paginated) {
+		const endpoint = resolveMcpEndpoint(config.endpoint);
+		const protocolVersion = config.protocolVersion ?? DEFAULT_MCP_PROTOCOL_VERSION;
+		const toolName = config.toolName ?? "search_docs";
+		const forwardAudience = config.forwardAudience === true;
+		const audience = resolveDocsSearchAudience(query.audience);
+		const baseHeaders = config.headers ?? {};
+		if (audience === "human" && !forwardAudience) throw new Error("MCP human-projection search requires forwardAudience: true on an audience-aware tool.");
+		const initializeResponse = await fetch(endpoint, {
+			method: "POST",
+			headers: {
+				...baseHeaders,
+				"Content-Type": "application/json",
+				accept: "application/json, text/event-stream",
+				"mcp-protocol-version": protocolVersion
+			},
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "initialize",
+				params: {
+					protocolVersion,
+					capabilities: {},
+					clientInfo: {
+						name: "@farming-labs/docs-search",
+						version: "0.1.2"
+					}
+				}
+			}),
+			signal: context.signal
+		});
+		const initializePayload = await readMcpResponsePayload(initializeResponse);
+		ensureOk(initializeResponse, "MCP search initialization failed");
+		ensureJsonRpcOk(initializePayload, "MCP search initialization failed");
+		const sessionId = initializeResponse.headers.get("mcp-session-id") ?? void 0;
+		try {
+			ensureOk(await fetch(endpoint, {
 				method: "POST",
 				headers: {
 					...baseHeaders,
 					"Content-Type": "application/json",
 					accept: "application/json, text/event-stream",
-					"mcp-protocol-version": protocolVersion
+					"mcp-protocol-version": protocolVersion,
+					...sessionId ? { "mcp-session-id": sessionId } : {}
 				},
 				body: JSON.stringify({
 					jsonrpc: "2.0",
-					id: 1,
-					method: "initialize",
-					params: {
-						protocolVersion,
-						capabilities: {},
-						clientInfo: {
-							name: "@farming-labs/docs-search",
-							version: "0.1.2"
-						}
-					}
+					method: "notifications/initialized",
+					params: {}
 				}),
 				signal: context.signal
-			});
-			const initializePayload = await readMcpResponsePayload(initializeResponse);
-			ensureOk(initializeResponse, "MCP search initialization failed");
-			ensureJsonRpcOk(initializePayload, "MCP search initialization failed");
-			const sessionId = initializeResponse.headers.get("mcp-session-id") ?? void 0;
-			try {
+			}), "MCP initialized notification failed");
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			const callRemoteSearchPage = async (providerCursor, id) => {
 				const searchResponse = await fetch(endpoint, {
 					method: "POST",
 					headers: {
@@ -2881,14 +3117,15 @@ function createMcpSearchAdapter(config) {
 					},
 					body: JSON.stringify({
 						jsonrpc: "2.0",
-						id: 2,
+						id,
 						method: "tools/call",
 						params: {
 							name: toolName,
 							arguments: {
 								query: query.query,
-								limit: query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT,
+								limit: pageSize,
 								locale: query.locale,
+								...providerCursor !== void 0 ? { cursor: providerCursor } : {},
 								...forwardAudience ? { audience } : {},
 								...query.filters?.framework ? { framework: query.filters.framework } : {},
 								...query.filters?.version ? { version: query.filters.version } : {},
@@ -2903,32 +3140,107 @@ function createMcpSearchAdapter(config) {
 				ensureOk(searchResponse, "MCP search request failed");
 				ensureJsonRpcOk(payload, "MCP search request failed");
 				const parsed = readMcpSearchToolPayload(payload);
-				if (!parsed) return [];
+				if (!parsed) return {
+					parsed,
+					rawResults: [],
+					results: []
+				};
 				if (hasDocsSearchFilters(query.filters ?? {})) {
-					if (Array.isArray(parsed) || parsed.format !== "docs-search.v1") return [];
+					if (Array.isArray(parsed) || parsed.format !== "docs-search.v1") {
+						if (paginated) throw new Error("MCP search returned unverifiable pagination data.");
+						return {
+							parsed,
+							rawResults: [],
+							results: []
+						};
+					}
 					const echoedFilters = parseVerifiedMcpSearchFilters(parsed.filters);
-					if (!echoedFilters || !docsSearchFiltersMatch(query.filters ?? {}, echoedFilters)) return [];
-				}
-				return (Array.isArray(parsed) ? parsed : Array.isArray(parsed.results) ? parsed.results : Array.isArray(parsed.pages) ? parsed.pages : []).map((result) => mapMcpSearchResult(result, endpoint)).filter((result) => Boolean(result));
-			} finally {
-				if (sessionId) {
-					const cleanupController = new AbortController();
-					const cleanupTimeout = setTimeout(() => cleanupController.abort(), MCP_SESSION_CLEANUP_TIMEOUT_MS);
-					try {
-						await fetch(endpoint, {
-							method: "DELETE",
-							headers: {
-								...baseHeaders,
-								"mcp-protocol-version": protocolVersion,
-								"mcp-session-id": sessionId
-							},
-							signal: cleanupController.signal
-						});
-					} catch {} finally {
-						clearTimeout(cleanupTimeout);
+					if (!echoedFilters || !docsSearchFiltersMatch(query.filters ?? {}, echoedFilters)) {
+						if (paginated) throw new Error("MCP search returned mismatched scope filters.");
+						return {
+							parsed,
+							rawResults: [],
+							results: []
+						};
 					}
 				}
+				const rawResults = Array.isArray(parsed) ? parsed : Array.isArray(parsed.results) ? parsed.results : Array.isArray(parsed.pages) ? parsed.pages : [];
+				return {
+					parsed,
+					rawResults,
+					results: rawResults.map((result) => mapMcpSearchResult(result, endpoint)).filter((result) => Boolean(result))
+				};
+			};
+			if (!paginated) return (await callRemoteSearchPage(void 0, 2)).results;
+			const targetOffset = query.offset ?? 0;
+			if (targetOffset === 0 && query.cursor !== void 0 || targetOffset > 0 && query.cursor === void 0) throw new Error("MCP search continuation is missing or misplaced its provider cursor.");
+			let consumed = 0;
+			let remoteCursor;
+			let expectedTotal;
+			const replayResultDigests = [];
+			for (let pageIndex = 0; pageIndex < MAX_MCP_SEARCH_CURSOR_REPLAY_PAGES; pageIndex += 1) {
+				const { parsed, rawResults, results } = await callRemoteSearchPage(remoteCursor, pageIndex + 2);
+				if (!parsed) {
+					if (targetOffset === 0) return {
+						results: [],
+						total: 0
+					};
+					throw new Error("MCP search continuation ended before the requested page.");
+				}
+				if (Array.isArray(parsed) || parsed.format !== "docs-search.v1" || results.length !== rawResults.length || parsed.resultCount !== void 0 && parsed.resultCount !== results.length || typeof parsed.total !== "number" || !Number.isSafeInteger(parsed.total) || parsed.total < consumed + results.length || typeof parsed.hasMore !== "boolean" || parsed.nextCursor !== void 0 && (typeof parsed.nextCursor !== "string" || parsed.nextCursor.length > 768)) throw new Error("MCP search returned malformed paginated results.");
+				const total = parsed.total;
+				const nextCursor = typeof parsed.nextCursor === "string" ? parsed.nextCursor : void 0;
+				const hasMore = consumed + results.length < total;
+				if (expectedTotal !== void 0 && total !== expectedTotal || parsed.hasMore !== hasMore || nextCursor !== void 0 !== hasMore || hasMore && results.length === 0) throw new Error("MCP search returned inconsistent pagination metadata.");
+				expectedTotal ??= total;
+				if (total > MAX_MCP_SEARCH_CURSOR_RESULTS) throw new Error("MCP search exceeds its bounded exact pagination window.");
+				replayResultDigests.push(...results.map((result) => hashDocsRetrievalValue(JSON.stringify(result))));
+				const nextOffset = consumed + results.length;
+				const nextCheckpoint = hasMore ? hashDocsRetrievalValue(JSON.stringify({
+					format: "docs-mcp-search-replay.v1",
+					total,
+					nextOffset,
+					resultDigests: replayResultDigests
+				})) : void 0;
+				if (nextOffset === targetOffset && nextCheckpoint !== query.cursor) throw new Error("MCP search continuation cursor is stale.");
+				if (consumed === targetOffset) return {
+					results,
+					total,
+					...nextCheckpoint !== void 0 ? { nextCursor: nextCheckpoint } : {}
+				};
+				if (!hasMore || nextCursor === void 0) throw new Error("MCP search continuation ended before the requested page.");
+				consumed = nextOffset;
+				if (consumed > targetOffset) throw new Error("MCP search continuation offset does not match a page boundary.");
+				remoteCursor = nextCursor;
 			}
+			throw new Error("MCP search exceeds its bounded cursor replay limit.");
+		} finally {
+			if (sessionId) {
+				const cleanupController = new AbortController();
+				const cleanupTimeout = setTimeout(() => cleanupController.abort(), MCP_SESSION_CLEANUP_TIMEOUT_MS);
+				try {
+					await fetch(endpoint, {
+						method: "DELETE",
+						headers: {
+							...baseHeaders,
+							"mcp-protocol-version": protocolVersion,
+							"mcp-session-id": sessionId
+						},
+						signal: cleanupController.signal
+					});
+				} catch {} finally {
+					clearTimeout(cleanupTimeout);
+				}
+			}
+		}
+	}
+	return {
+		name: "mcp",
+		async search(query, context) {
+			return await runMcpSearch(query, context, false);
+		},
+		async searchPage(query, context) {
+			return await runMcpSearch(query, context, true);
 		}
 	};
 }
@@ -2992,7 +3304,7 @@ function quoteAlgoliaFilterValue(value) {
 	return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"")}"`;
 }
 function createAlgoliaSearchAdapter(config) {
-	return {
+	const adapter = {
 		name: "algolia",
 		async index(context) {
 			if (!config.adminApiKey) return;
@@ -3011,13 +3323,31 @@ function createAlgoliaSearchAdapter(config) {
 			})), "Failed to sync documents to Algolia", context.signal);
 		},
 		async search(query, context) {
+			return (await adapter.searchPage({
+				...query,
+				offset: 0,
+				[DOCS_UNPAGINATED_PROVIDER_QUERY]: true
+			}, context)).results;
+		},
+		async searchPage(query, context) {
+			const exactPagination = !query[DOCS_UNPAGINATED_PROVIDER_QUERY];
 			const corpusId = resolveHostedHumanCorpusId(config.syncNamespace, context);
 			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context, corpusId);
-			if (scopedDocumentIds?.length === 0) return [];
+			if (scopedDocumentIds === DOCS_PROVIDER_SCOPE_FILTER_OVERFLOW) throw new Error("Algolia scope filters exceed the provider pagination limit.");
+			if (scopedDocumentIds?.length === 0) return {
+				results: [],
+				total: 0
+			};
 			const scopedIdsFilter = scopedDocumentIds?.map((id) => `objectID:${quoteAlgoliaFilterValue(id)}`).join(" OR ");
-			const filterClauses = [corpusId ? `_tags:${quoteAlgoliaFilterValue(corpusId)}` : void 0, scopedIdsFilter ? corpusId ? `(${scopedIdsFilter})` : scopedIdsFilter : void 0].filter((value) => Boolean(value));
+			const filterClauses = [
+				corpusId ? `_tags:${quoteAlgoliaFilterValue(corpusId)}` : void 0,
+				context.indexGeneration ? `_tags:${quoteAlgoliaFilterValue(getHostedIndexGenerationTag(context.indexGeneration))}` : void 0,
+				scopedIdsFilter ? corpusId || context.indexGeneration ? `(${scopedIdsFilter})` : scopedIdsFilter : void 0
+			].filter((value) => Boolean(value));
 			const filters = filterClauses.length > 0 ? filterClauses.join(" AND ") : void 0;
-			if (filters && filters.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) return [];
+			if (filters && filters.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) throw new Error("Algolia scope filters exceed the provider pagination limit.");
+			const pageSize = query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT;
+			if ((query.offset ?? 0) % pageSize !== 0) throw new Error("Algolia search offset does not match its page boundary.");
 			const response = await fetch(`${getAlgoliaSearchBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/query`, {
 				method: "POST",
 				headers: {
@@ -3027,7 +3357,8 @@ function createAlgoliaSearchAdapter(config) {
 				},
 				body: JSON.stringify({
 					query: query.query,
-					hitsPerPage: query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT,
+					hitsPerPage: pageSize,
+					page: Math.floor((query.offset ?? 0) / pageSize),
 					restrictSearchableAttributes: [
 						"title",
 						"section",
@@ -3040,7 +3371,8 @@ function createAlgoliaSearchAdapter(config) {
 				signal: context.signal
 			});
 			ensureOk(response, "Algolia search failed");
-			return ((await readResponseJson(response)).hits ?? []).flatMap((hit) => {
+			const payload = await readResponseJson(response);
+			const results = (payload.hits ?? []).flatMap((hit) => {
 				if (!hostedRecordMatchesCorpus(hit, corpusId)) return [];
 				const title = typeof hit.title === "string" ? hit.title : "Untitled result";
 				const section = typeof hit.section === "string" ? hit.section : void 0;
@@ -3061,8 +3393,21 @@ function createAlgoliaSearchAdapter(config) {
 					...source ? { source } : {}
 				}];
 			});
+			const exactTotal = typeof payload.nbHits === "number" && Number.isSafeInteger(payload.nbHits) && payload.nbHits >= 0 ? payload.nbHits : void 0;
+			const exactPageCount = typeof payload.nbPages === "number" && Number.isSafeInteger(payload.nbPages) && payload.nbPages >= 0 ? payload.nbPages : void 0;
+			if (exactPagination && (exactTotal === void 0 || exactPageCount === void 0)) throw new Error("Algolia search did not return exact reachable pagination metadata.");
+			const total = exactTotal ?? results.length;
+			if (exactPagination && total > MAX_HOSTED_PROVIDER_CURSOR_RESULTS) throw new Error("Algolia search exceeds the exact cursor pagination window.");
+			if (exactPagination && payload.exhaustiveNbHits === false) throw new Error("Algolia search returned an approximate result total.");
+			if (exactPagination && exactPageCount !== void 0 && total > exactPageCount * pageSize) throw new Error("Algolia search total exceeds its reachable pagination window.");
+			if (exactPagination && (query.offset ?? 0) + results.length < total && results.length !== pageSize) throw new Error("Algolia search returned an incomplete non-final page.");
+			return {
+				results,
+				total
+			};
 		}
 	};
+	return adapter;
 }
 async function resolveSearchAdapter(search, context) {
 	const raw = search.raw;
@@ -3146,9 +3491,29 @@ async function maybeSyncSearchIndex(adapter, search, context) {
 		}
 	}
 }
-async function performDocsSearch(options) {
+function normalizeDocsSearchAdapterPage(value) {
+	if (Array.isArray(value)) return {
+		results: value,
+		total: value.length
+	};
+	if (!value || !Array.isArray(value.results) || !Number.isSafeInteger(value.total) || value.total < 0 || value.results.length > value.total || value.nextCursor !== void 0 && (typeof value.nextCursor !== "string" || value.nextCursor.length === 0 || JSON.stringify([
+		1,
+		"provider",
+		value.total,
+		value.nextCursor
+	]).length > MAX_SEARCH_PROVIDER_CURSOR_STATE_CHARS)) throw new Error("Search adapter returned invalid pagination metadata.");
+	return value;
+}
+async function performDocsSearchInternal(options) {
 	const search = normalizeDocsSearchConfig(options.search);
-	if (!search.enabled) return [];
+	if (!search.enabled) {
+		if (options.paginationMode === "provider" || options.expectedTotal !== void 0 && options.expectedTotal !== 0) throw new DocsPaginationCursorError();
+		return {
+			results: [],
+			total: 0,
+			paginationMode: "local"
+		};
+	}
 	const audience = resolveDocsSearchAudience(options.audience);
 	const filters = normalizeDocsSearchFilters(options.filters);
 	const hasFilters = hasDocsSearchFilters(filters);
@@ -3181,6 +3546,8 @@ async function performDocsSearch(options) {
 	const query = {
 		query: options.query,
 		limit: options.limit ?? search.maxResults,
+		...options.paginated ? { offset: options.offset ?? 0 } : {},
+		...options.providerCursor !== void 0 ? { cursor: options.providerCursor } : {},
 		locale: options.locale,
 		pathname: options.pathname,
 		audience,
@@ -3197,6 +3564,16 @@ async function performDocsSearch(options) {
 		return currentIndexGeneration;
 	};
 	const requireCurrentIndexGeneration = search.provider === "algolia" || search.provider === "typesense";
+	let hostedIndexGeneration;
+	const getHostedIndexGeneration = () => {
+		hostedIndexGeneration ??= audience === "human" ? getCurrentIndexGeneration() : buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
+			audience: "human",
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: indexBaseUrl
+		});
+		return hostedIndexGeneration;
+	};
 	const finalizeResults = async (results) => enrichDocsSearchResultsWithSources({
 		results,
 		pages: scopedPages,
@@ -3210,6 +3587,20 @@ async function performDocsSearch(options) {
 		filters,
 		requireCurrentIndexGeneration
 	});
+	const createLocalPage = async () => {
+		const fallback = options.paginated ? await createSimpleSearchAdapter().searchPage(query, context) : normalizeDocsSearchAdapterPage(await createSimpleSearchAdapter().search(query, context));
+		if (options.expectedTotal !== void 0 && fallback.total !== options.expectedTotal) throw new DocsPaginationCursorError();
+		return {
+			results: await finalizeResults(fallback.results),
+			total: options.paginated ? fallback.total : fallback.results.length,
+			paginationMode: "local"
+		};
+	};
+	const fallBackFromProvider = () => {
+		if (options.paginationMode === "provider") throw new DocsPaginationCursorError();
+		return createLocalPage();
+	};
+	if (options.paginated && options.paginationMode === "local") return createLocalPage();
 	try {
 		const adapter = await resolveSearchAdapter(search, context);
 		if (shouldSyncOnSearch(search) && typeof adapter.index === "function") {
@@ -3223,11 +3614,17 @@ async function performDocsSearch(options) {
 				siteTitle: options.siteTitle,
 				baseUrl: indexBaseUrl,
 				indexBaseUrl,
+				...options.paginated && requireCurrentIndexGeneration ? { indexGeneration: await getHostedIndexGeneration() } : {},
 				chunking: search.chunking,
 				signal: options.signal
 			});
 		}
-		const adapterSearch = adapter.search(query, context);
+		if (options.paginated && requireCurrentIndexGeneration) context.indexGeneration = await getHostedIndexGeneration();
+		if (options.paginated && search.provider === "custom" && (!adapter.searchPage || search.raw?.provider !== "custom" || !search.raw.paginationRevision?.trim())) {
+			if (options.paginationMode === "provider") throw new DocsPaginationCursorError();
+			return createLocalPage();
+		}
+		const adapterSearch = options.paginated && adapter.searchPage ? adapter.searchPage(query, context) : adapter.search(query, context);
 		let documents;
 		try {
 			documents = getDocuments();
@@ -3235,8 +3632,20 @@ async function performDocsSearch(options) {
 			adapterSearch.catch(() => void 0);
 			throw error;
 		}
-		const results = await adapterSearch;
-		if (search.provider === "simple") return finalizeResults(results);
+		const rawAdapterResult = await adapterSearch;
+		const adapterPage = options.paginated && !adapter.searchPage && Array.isArray(rawAdapterResult) ? {
+			results: rawAdapterResult.slice(options.offset ?? 0, (options.offset ?? 0) + (query.limit ?? search.maxResults)),
+			total: rawAdapterResult.length
+		} : normalizeDocsSearchAdapterPage(rawAdapterResult);
+		const results = adapterPage.results;
+		if (search.provider === "simple") {
+			if (options.expectedTotal !== void 0 && adapterPage.total !== options.expectedTotal) throw new DocsPaginationCursorError();
+			return {
+				results: await finalizeResults(results),
+				total: options.paginated ? adapterPage.total : results.length,
+				paginationMode: "local"
+			};
+		}
 		const localAudienceProjectionResults = buildAudienceProjectionSearchResults(documents, options.query);
 		const localPagePaths = new Set(scopedPages.map((page) => normalizeUrlRouteKey(page.url)));
 		const allLocalPagePaths = hasFilters && search.provider === "mcp" ? new Set(options.pages.map((page) => normalizeUrlRouteKey(page.url))) : localPagePaths;
@@ -3246,12 +3655,7 @@ async function performDocsSearch(options) {
 			baseUrl: options.baseUrl
 		}) : void 0;
 		const isKnownLocalProviderResult = (result) => isLocalProviderResult(result, options.baseUrl) && localPagePaths.has(normalizeUrlRouteKey(result.url));
-		const expectedProviderGeneration = requireCurrentIndexGeneration ? audience === "human" ? await getCurrentIndexGeneration() : await buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
-			audience: "human",
-			chunking: search.chunking,
-			locale: options.locale,
-			baseUrl: indexBaseUrl
-		}) : void 0;
+		const expectedProviderGeneration = requireCurrentIndexGeneration ? await getHostedIndexGeneration() : void 0;
 		const providerAudience = requireCurrentIndexGeneration ? "human" : audience;
 		const safeAdapterResults = sanitizeExternalAudienceSearchResults(results.filter((result) => {
 			if (result.source === void 0) return !requireCurrentIndexGeneration || isKnownLocalProviderResult(result);
@@ -3265,19 +3669,45 @@ async function performDocsSearch(options) {
 			audience,
 			baseUrl: options.baseUrl
 		})), localAudienceProjectionResults, options.baseUrl, preserveUnmatched, requireCurrentIndexGeneration && audience === "agent");
-		if (options.supplementExternalResults === false) return finalizeResults(safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT));
+		if (options.paginated) {
+			const endOffset = (query.offset ?? 0) + safeAdapterResults.length;
+			if (safeAdapterResults.length !== results.length || safeAdapterResults.length > (query.limit ?? search.maxResults) || endOffset > adapterPage.total || requireCurrentIndexGeneration && adapterPage.total === 0 && localAudienceProjectionResults.length > 0 || endOffset < adapterPage.total && safeAdapterResults.length === 0 || adapterPage.nextCursor !== void 0 && options.providerCursor !== void 0 && adapterPage.nextCursor === options.providerCursor || adapterPage.nextCursor !== void 0 && endOffset >= adapterPage.total || options.expectedTotal !== void 0 && adapterPage.total !== options.expectedTotal) return fallBackFromProvider();
+			return {
+				results: await finalizeResults(safeAdapterResults),
+				total: adapterPage.total,
+				...adapterPage.nextCursor !== void 0 ? { nextCursor: adapterPage.nextCursor } : {},
+				paginationMode: "provider"
+			};
+		}
+		if (options.supplementExternalResults === false) {
+			const bounded = safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+			return {
+				results: await finalizeResults(bounded),
+				total: bounded.length,
+				paginationMode: "provider"
+			};
+		}
 		const simpleAudienceResults = audience === "agent" || results.length === 0 || safeAdapterResults.length < results.length ? await createSimpleSearchAdapter().search(query, context) : [];
 		const combinedResults = mergeSearchResults([
 			buildExactPageSearchResults(options.query, scopedPages, audience),
 			safeAdapterResults,
 			simpleAudienceResults
 		], audience === "agent" ? (result) => getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins) : void 0);
-		return finalizeResults(prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT));
+		const bounded = prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
+		return {
+			results: await finalizeResults(bounded),
+			total: bounded.length,
+			paginationMode: "provider"
+		};
 	} catch (error) {
+		if (error instanceof DocsPaginationCursorError) throw error;
 		if (options.failureMode === "throw") throw error;
-		return finalizeResults(await createSimpleSearchAdapter().search(query, context));
+		return fallBackFromProvider();
 	}
 }
+async function performDocsSearch(options) {
+	return (await performDocsSearchInternal(options)).results;
+}
 function compareSearchMetadataValues(left, right) {
 	if (left === right) return 0;
 	return left < right ? -1 : 1;
@@ -3340,7 +3770,7 @@ function buildDocsSearchWarnings(options) {
 			count: unknown.length
 		});
 	}
-	const resultPages = findSearchResultPages(options.pages, options.results, options.baseUrl);
+	const resultPages = options.completeResultSet ? relevantPageScopes.filter(({ scope }) => docsSearchPageMatchesFilters(scope, options.filters)).map(({ page }) => page).sort((left, right) => compareSearchMetadataValues(left.url, right.url)) : findSearchResultPages(options.pages, options.results, options.baseUrl);
 	for (const field of SEARCH_AMBIGUITY_FIELDS) {
 		if ((options.filters[field]?.length ?? 0) > 0) continue;
 		const values = resultPages.flatMap((page) => {
@@ -3374,37 +3804,108 @@ function buildDocsSearchWarnings(options) {
 		return SEARCH_FILTER_FIELDS.indexOf(left.field) - SEARCH_FILTER_FIELDS.indexOf(right.field);
 	}).slice(0, MAX_SEARCH_WARNINGS);
 }
+function parseDocsSearchCursorState(state, offset) {
+	if (offset === 0 && state === void 0) return void 0;
+	if (state === void 0) throw new DocsPaginationCursorError();
+	let parsed;
+	try {
+		parsed = JSON.parse(state);
+	} catch {
+		throw new DocsPaginationCursorError();
+	}
+	if (!Array.isArray(parsed) || parsed.length !== 4 || JSON.stringify(parsed) !== state) throw new DocsPaginationCursorError();
+	const [version, mode, total, providerCursor] = parsed;
+	if (version !== 1 || mode !== "local" && mode !== "provider" || !Number.isSafeInteger(total) || total < offset || !(providerCursor === null || typeof providerCursor === "string" && providerCursor.length <= 768) || mode === "local" && providerCursor !== null) throw new DocsPaginationCursorError();
+	return {
+		mode,
+		total,
+		...typeof providerCursor === "string" ? { providerCursor } : {}
+	};
+}
+function createDocsSearchCursorState(page) {
+	return JSON.stringify([
+		1,
+		page.paginationMode,
+		page.total,
+		page.paginationMode === "provider" ? page.nextCursor ?? null : null
+	]);
+}
 async function performDocsSearchWithMetadata(options) {
 	const audience = resolveDocsSearchAudience(options.audience);
 	const filters = normalizeDocsSearchFilters(options.filters);
 	const search = normalizeDocsSearchConfig(options.search);
+	const requestedLimit = options.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT;
+	const limit = Number.isFinite(requestedLimit) && requestedLimit > 0 ? Math.max(1, Math.floor(requestedLimit)) : DEFAULT_SEARCH_LIMIT;
 	const indexGeneration = options.indexGeneration ?? await buildDocsSearchIndexGeneration(options.generationPages ?? options.pages, {
 		audience,
 		chunking: search.chunking,
 		locale: options.locale,
 		baseUrl: options.baseUrl
 	});
-	const results = options.query.trim() ? await performDocsSearch({
+	const normalizedFilters = Object.fromEntries(SEARCH_FILTER_FIELDS.flatMap((field) => {
+		const values = filters[field];
+		return values?.length ? [[field, [...values].sort(compareSearchMetadataValues)]] : [];
+	}));
+	const provider = getDocsSearchPaginationProviderIdentity(search);
+	const cursorOptions = {
+		kind: "docs-search",
+		scope: JSON.stringify({
+			format: "docs-search-pagination.v2",
+			query: options.query,
+			audience,
+			filters: normalizedFilters,
+			locale: options.locale ? normalizeAgentLocale(options.locale) : void 0,
+			pathname: options.pathname?.trim() || void 0,
+			provider,
+			limit
+		}),
+		snapshot: indexGeneration
+	};
+	const cursorPosition = resolveDocsPaginationCursor(options.cursor, cursorOptions);
+	const offset = cursorPosition.offset;
+	const cursorState = parseDocsSearchCursorState(cursorPosition.state, offset);
+	const page = options.query.trim() ? await performDocsSearchInternal({
 		...options,
 		audience,
 		filters,
-		indexGeneration
-	}) : [];
+		indexGeneration,
+		limit,
+		offset,
+		paginated: true,
+		providerCursor: cursorState?.providerCursor,
+		paginationMode: cursorState?.mode,
+		expectedTotal: cursorState?.total
+	}) : {
+		results: [],
+		total: 0,
+		paginationMode: "local"
+	};
+	if (options.cursor !== void 0 && offset >= page.total || page.results.length > Math.min(limit, Math.max(0, page.total - offset)) || offset < page.total && page.results.length === 0) throw new DocsPaginationCursorError();
+	const nextOffset = Math.min(page.total, offset + page.results.length);
+	const hasMore = nextOffset < page.total;
+	const nextCursor = hasMore ? createDocsPaginationCursor(nextOffset, {
+		...cursorOptions,
+		state: createDocsSearchCursorState(page)
+	}) : void 0;
 	return {
 		format: "docs-search.v1",
 		query: options.query,
 		audience,
 		filters,
 		indexGeneration,
-		resultCount: results.length,
-		results,
+		resultCount: page.results.length,
+		total: page.total,
+		hasMore,
+		...nextCursor ? { nextCursor } : {},
+		results: page.results,
 		warnings: buildDocsSearchWarnings({
 			pages: options.pages,
-			results,
+			results: page.results,
 			filters,
 			query: options.query,
 			audience,
-			baseUrl: options.baseUrl
+			baseUrl: options.baseUrl,
+			completeResultSet: true
 		})
 	};
 }
@@ -3479,12 +3980,13 @@ async function buildDocsAskAIContext(options) {
 		packageHints: inferDocsAskAIPackageHints(context)
 	};
 }
-function createCustomSearchAdapter(adapter) {
+function createCustomSearchAdapter(adapter, options = {}) {
 	return {
 		provider: "custom",
-		adapter
+		adapter,
+		...options.paginationRevision ? { paginationRevision: options.paginationRevision } : {}
 	};
 }
 
 //#endregion
-export { GENERATED_AGENT_PROVENANCE_MARKER as A, resolveSidebarFolderIndexBehaviorForPath as B, agentVersionConstraintsOverlap as C, normalizeAgentVersion as D, normalizeAgentScopeValues as E, serializeGeneratedAgentDocument as F, getDocsTelemetryFeatures as G, emitDocsTelemetryEvent as H, stripGeneratedAgentProvenance as I, normalizeDocsTelemetryOrigin as J, inferDocsTelemetryAgentSurface as K, applySidebarFolderIndexBehavior as L, hashGeneratedAgentContent as M, normalizeGeneratedAgentContent as N, digestDocsRetrievalContent as O, parseGeneratedAgentDocument as P, resolvePageSidebarFolderIndexBehavior as R, agentVersionConstraintMatches as S, normalizeAgentLocale as T, emitDocsTelemetryMcpToolEvent as U, emitDocsTelemetryAgentSurfaceEvent as V, emitDocsTelemetryProjectEvent as W, resolveDocsTelemetryConfig as Y, resolveDocsSearchAudience as _, createCustomSearchAdapter as a, resolveSearchRequestConfig as b, createTypesenseSearchAdapter as c, inferDocsAskAIPackageHints as d, normalizeDocsSearchFilters as f, resolveDocsRetrievalLastModified as g, resolveAskAISearchRequestConfig as h, createAlgoliaSearchAdapter as i, GENERATED_AGENT_PROVENANCE_VERSION as j, isDocsRetrievalCanonicalUrl as k, enrichDocsSearchDocumentsWithProvenance as l, performDocsSearchWithMetadata as m, buildDocsRetrievalDigestProjection as n, createMcpSearchAdapter as o, performDocsSearch as p, isLocalDocsTelemetryOrigin as q, buildDocsSearchDocuments as r, createSimpleSearchAdapter as s, buildDocsAskAIContext as t, formatDocsAskAIPackageHints as u, resolveDocsSearchFilters as v, normalizeAgentFramework as w, agentVersionConstraintGroupsOverlap as x, resolveDocsSearchRequest as y, resolveSidebarFolderIndexBehavior as z };
+export { resolveDocsTelemetryConfig as $, DocsPaginationCursorError as A, stripGeneratedAgentProvenance as B, agentVersionConstraintGroupsOverlap as C, normalizeAgentLocale as D, normalizeAgentFramework as E, GENERATED_AGENT_PROVENANCE_VERSION as F, emitDocsTelemetryAgentSurfaceEvent as G, resolvePageSidebarFolderIndexBehavior as H, hashGeneratedAgentContent as I, emitDocsTelemetryProjectEvent as J, emitDocsTelemetryEvent as K, normalizeGeneratedAgentContent as L, digestDocsRetrievalContent as M, isDocsRetrievalCanonicalUrl as N, normalizeAgentScopeValues as O, GENERATED_AGENT_PROVENANCE_MARKER as P, normalizeDocsTelemetryOrigin as Q, parseGeneratedAgentDocument as R, resolveSearchRequestConfig as S, agentVersionConstraintsOverlap as T, resolveSidebarFolderIndexBehavior as U, applySidebarFolderIndexBehavior as V, resolveSidebarFolderIndexBehaviorForPath as W, inferDocsTelemetryAgentSurface as X, getDocsTelemetryFeatures as Y, isLocalDocsTelemetryOrigin as Z, resolveDocsRetrievalLastModified as _, createAlgoliaSearchAdapter as a, resolveDocsSearchFilters as b, createSimpleSearchAdapter as c, formatDocsAskAIPackageHints as d, inferDocsAskAIPackageHints as f, resolveAskAISearchRequestConfig as g, performDocsSearchWithMetadata as h, buildDocsSearchDocuments as i, paginateDocsItems as j, normalizeAgentVersion as k, createTypesenseSearchAdapter as l, performDocsSearch as m, buildDocsAskAIContext as n, createCustomSearchAdapter as o, normalizeDocsSearchFilters as p, emitDocsTelemetryMcpToolEvent as q, buildDocsRetrievalDigestProjection as r, createMcpSearchAdapter as s, DocsSearchRequestError as t, enrichDocsSearchDocumentsWithProvenance as u, resolveDocsSearchAudience as v, agentVersionConstraintMatches as w, resolveDocsSearchRequest as x, resolveDocsSearchError as y, serializeGeneratedAgentDocument as z };