@farming-labs/docs 0.2.82 → 0.2.84

package/dist/{agent-Dze2Cy5B.mjs → agent-D68WI6-N.mjs}

@@ -2408,6 +2408,8 @@ const MAX_SEARCH_WARNINGS = 16;
 const MAX_SEARCH_WARNING_VALUES = 16;
 const MAX_SEARCH_WARNING_PAGE_URLS = 8;
 const MAX_SEARCH_FACET_VALUES = 100;
+const MAX_SEARCH_EXPLANATION_TERMS = 32;
+const MAX_SEARCH_EXPLANATION_TERM_CHARS = 128;
 const RETRIEVAL_INDEX_FORMAT = "docs-retrieval-index.v1";
 const MAX_RETRIEVAL_SOURCE_URL_CHARS = 4096;
 const MAX_RETRIEVAL_SOURCE_VALUE_CHARS = 256;
@@ -2522,6 +2524,9 @@ function resolveDocsSearchRequest(searchParams) {
 	const response = searchParams.get("response");
 	const structured = response === "structured";
 	const facets = response === "facets";
+	const rawExplain = searchParams.get("explain");
+	if (rawExplain !== null && rawExplain !== "true" && rawExplain !== "false") throw new DocsSearchRequestError("Search explain must be `true` or `false`.");
+	const explain = rawExplain === "true";
 	const rawFacet = searchParams.get("facet");
 	let facet;
 	if (rawFacet !== null) {
@@ -2543,6 +2548,7 @@ function resolveDocsSearchRequest(searchParams) {
 	return {
 		filters: resolveDocsSearchFilters(searchParams),
 		structured,
+		...explain ? { explain: true } : {},
 		...facets ? { facets: true } : {},
 		...facet !== void 0 ? { facet } : {},
 		...cursor !== void 0 ? { cursor } : {},
@@ -3703,9 +3709,14 @@ function buildDocsSearchDocuments(pages, chunking = {}, audience = "human") {
 		return [...base.content ? [base] : [], ...sections];
 	});
 }
-function scoreDocument(query, document) {
+function analyzeDocsSearchDocument(query, document, explain = false) {
 	const q = normalizeSearchPhrase(query);
-	if (!q) return 0;
+	if (!q) return {
+		score: 0,
+		matchedTerms: [],
+		matchedTermsTruncated: false,
+		rankingReasons: []
+	};
 	const words = tokenizeSearchQuery(q);
 	const title = normalizeSearchPhrase(document.title);
 	const section = document.section ? normalizeSearchPhrase(document.section) : "";
@@ -3718,65 +3729,248 @@ function scoreDocument(query, document) {
 	const titleTokens = tokenizeSearchQuery(title);
 	const sectionTokens = tokenizeSearchQuery(section);
 	let score = 0;
+	const reasonContributions = explain ? /* @__PURE__ */ new Map() : void 0;
+	const addScore = (contribution, code, description) => {
+		score += contribution;
+		if (!reasonContributions) return;
+		const current = reasonContributions.get(code);
+		reasonContributions.set(code, {
+			contribution: (current?.contribution ?? 0) + contribution,
+			description: current?.description ?? description
+		});
+	};
 	const insideLiteralPriority = document.type !== "page" && hasDistinctSection && isLiteralLookupQuery(q) ? Math.max(literalMatchPriority(q, section), literalMatchPriority(q, description), literalMatchPriority(q, content)) : 0;
-	if (insideLiteralPriority > 0) score += insideLiteralPriority * 2250;
-	if (title === q) score += 1120;
-	else if (title.startsWith(q)) score += 70;
-	else if (title.includes(q)) score += 45;
+	if (insideLiteralPriority > 0) addScore(insideLiteralPriority * 2250, "literal_match", "A short literal lookup matched this section or its searchable text.");
+	if (title === q) addScore(1120, "title_phrase", "The normalized query exactly matches the page title.");
+	else if (title.startsWith(q)) addScore(70, "title_phrase", "The page title starts with the normalized query.");
+	else if (title.includes(q)) addScore(45, "title_phrase", "The page title contains the normalized query.");
 	if (hasDistinctSection) {
-		if (section === q) score += 1080;
-		else if (section.startsWith(q)) score += 55;
-		else if (section.includes(q)) score += 30;
-		if (titleSection === q) score += 1e3;
-		else if (titleSection.startsWith(q)) score += 50;
-		else if (titleSection.includes(q)) score += 28;
-	}
-	if (urlSegments.includes(q)) score += 950;
-	if (url.includes(q)) score += 12;
-	if (description.includes(q)) score += 18;
-	if (content.includes(q)) score += 12;
+		if (section === q) addScore(1080, "section_phrase", "The normalized query exactly matches the section title.");
+		else if (section.startsWith(q)) addScore(55, "section_phrase", "The section title starts with the normalized query.");
+		else if (section.includes(q)) addScore(30, "section_phrase", "The section title contains the normalized query.");
+		if (titleSection === q) addScore(1e3, "title_section_phrase", "The normalized query exactly matches the combined page and section title.");
+		else if (titleSection.startsWith(q)) addScore(50, "title_section_phrase", "The combined page and section title starts with the normalized query.");
+		else if (titleSection.includes(q)) addScore(28, "title_section_phrase", "The combined page and section title contains the normalized query.");
+	}
+	if (urlSegments.includes(q)) addScore(950, "url_phrase", "The normalized query exactly matches a URL segment.");
+	if (url.includes(q)) addScore(12, "url_phrase", "The result URL contains the normalized query.");
+	if (description.includes(q)) addScore(18, "description_phrase", "The page description contains the normalized query.");
+	if (content.includes(q)) addScore(12, "content_phrase", "The searchable content contains the normalized query.");
 	let matchedWords = 0;
 	for (const word of words) {
 		let matched = false;
 		if (title === word) {
-			score += 28;
+			addScore(28, "title_terms", "Normalized query terms match the page title.");
 			matched = true;
 		} else if (title.startsWith(word)) {
-			score += 20;
+			addScore(20, "title_terms", "Normalized query terms match the page title.");
 			matched = true;
 		} else if (title.includes(word)) {
-			score += 12;
+			addScore(12, "title_terms", "Normalized query terms match the page title.");
 			matched = true;
 		}
 		if (hasDistinctSection) {
 			if (section === word) {
-				score += 22;
+				addScore(22, "section_terms", "Normalized query terms match the section title.");
 				matched = true;
 			} else if (section.startsWith(word)) {
-				score += 16;
+				addScore(16, "section_terms", "Normalized query terms match the section title.");
 				matched = true;
 			} else if (section.includes(word)) {
-				score += 10;
+				addScore(10, "section_terms", "Normalized query terms match the section title.");
 				matched = true;
 			}
 		}
 		if (description.includes(word)) {
-			score += 6;
+			addScore(6, "description_terms", "Normalized query terms match the page description.");
 			matched = true;
 		}
 		if (content.includes(word)) {
-			score += 4;
+			addScore(4, "content_terms", "Normalized query terms match the searchable content.");
 			matched = true;
 		}
 		if (matched) matchedWords += 1;
 	}
 	if (words.length > 1) {
-		if (hasDistinctSection && sectionTokens.length > 0 && words.every((word) => sectionTokens.includes(word))) score += 30;
-		if (document.type === "page" && titleTokens.length > 0 && words.every((word) => titleTokens.includes(word))) score += 24;
+		if (hasDistinctSection && sectionTokens.length > 0 && words.every((word) => sectionTokens.includes(word))) addScore(30, "all_terms_in_section", "Every normalized query term occurs in the section title.");
+		if (document.type === "page" && titleTokens.length > 0 && words.every((word) => titleTokens.includes(word))) addScore(24, "all_terms_in_title", "Every normalized query term occurs in the page title.");
+	}
+	if (matchedWords === words.length && words.length > 1) addScore(20, "all_query_terms", "Every normalized query term matched a searchable field.");
+	if (score > 0 && document.type === "heading" && hasDistinctSection) addScore(6, "heading_boost", "A distinct matching section is preferred over a page-only hit.");
+	const matchedTerms = [];
+	let matchedTermCount = 0;
+	let matchedTermCharactersTruncated = false;
+	if (explain) {
+		const candidateTerms = words.length > 0 ? words : [q];
+		const fields = [
+			["title", title],
+			["section", section],
+			["description", description],
+			["content", content],
+			["url", url]
+		];
+		for (const term of candidateTerms) {
+			const matchingFields = fields.flatMap(([field, value]) => value.includes(term) ? [field] : []);
+			if (matchingFields.length === 0) continue;
+			matchedTermCount += 1;
+			if (matchedTerms.length < MAX_SEARCH_EXPLANATION_TERMS) {
+				matchedTermCharactersTruncated ||= term.length > MAX_SEARCH_EXPLANATION_TERM_CHARS;
+				matchedTerms.push({
+					term: term.slice(0, MAX_SEARCH_EXPLANATION_TERM_CHARS),
+					fields: matchingFields
+				});
+			}
+		}
 	}
-	if (matchedWords === words.length && words.length > 1) score += 20;
-	if (score > 0 && document.type === "heading" && hasDistinctSection) score += 6;
-	return score;
+	return {
+		score,
+		matchedTerms,
+		matchedTermsTruncated: matchedTermCount > matchedTerms.length || matchedTermCharactersTruncated,
+		rankingReasons: reasonContributions ? [...reasonContributions.entries()].map(([code, value]) => ({
+			code,
+			...value
+		})).sort((left, right) => right.contribution - left.contribution || left.code.localeCompare(right.code)) : []
+	};
+}
+function scoreDocument(query, document) {
+	return analyzeDocsSearchDocument(query, document).score;
+}
+function getDocsSearchExplanationResultIdentity(result) {
+	return JSON.stringify([
+		result.id,
+		result.url,
+		result.section ?? null
+	]);
+}
+function getDocsSearchExplanationDocumentIdentity(document) {
+	return getSearchResultKey({
+		id: document.id,
+		url: document.url,
+		content: document.title,
+		type: document.type,
+		section: document.section
+	});
+}
+function resolveDocsSearchExplanationDocument(result, documentsById, documentsByResultKey) {
+	const local = documentsById.get(result.id) ?? documentsByResultKey.get(getSearchResultKey(result));
+	if (local) return local;
+	return {
+		id: result.id,
+		url: result.url,
+		title: inferResultTitle(result),
+		content: result.content,
+		description: result.description,
+		section: result.section,
+		type: result.type
+	};
+}
+function buildDocsSearchFilterDecisions(filters, scope) {
+	return SEARCH_FILTER_FIELDS.map((field) => {
+		const requestedValues = filters[field] ?? [];
+		const selectedValues = scope?.[field] ?? [];
+		if (requestedValues.length === 0) return {
+			field,
+			requestedValues: [],
+			selectedValues: [...selectedValues],
+			matchedValues: [],
+			outcome: "not_requested"
+		};
+		const matchedValues = requestedValues.filter((requested) => selectedValues.some((selected) => docsSearchScopeValueMatches(field, requested, selected)));
+		const versionGroupsMatch = field !== "version" || !scope?.versionGroups?.length || agentVersionConstraintGroupsOverlap([requestedValues, ...scope.versionGroups]);
+		const verifiable = Boolean(scope) && !scope?.conflicts?.includes(field) && !scope?.truncated?.includes(field) && selectedValues.length > 0;
+		return {
+			field,
+			requestedValues: [...requestedValues],
+			selectedValues: [...selectedValues],
+			matchedValues,
+			outcome: verifiable && matchedValues.length > 0 && versionGroupsMatch ? "matched" : "not_verifiable"
+		};
+	});
+}
+function buildDocsSearchAmbiguityResolution(filters, scope, warnings, unverifiableFields) {
+	const decisions = SEARCH_AMBIGUITY_FIELDS.map((field) => {
+		const selectedValues = [...scope?.[field] ?? []];
+		const requestedValues = filters[field];
+		if (requestedValues?.length) return {
+			field,
+			status: "resolved_by_filter",
+			selectedValues,
+			candidateValues: [...requestedValues],
+			reason: `The explicit ${field} filter constrained the result set.`
+		};
+		const warning = warnings.find((candidate) => candidate.code === "ambiguous_scope" && candidate.field === field);
+		if (warning) return {
+			field,
+			status: "requires_filter",
+			selectedValues,
+			...warning.values ? { candidateValues: [...warning.values] } : {},
+			reason: `Results span multiple ${field} scopes; select a ${field} filter before acting on scope-specific guidance.`
+		};
+		const hasConflictingMetadata = warnings.some((candidate) => candidate.code === "conflicting_scope_metadata" && candidate.field === field);
+		if (selectedValues.length === 0 || unverifiableFields.has(field) || hasConflictingMetadata) return {
+			field,
+			status: "not_verifiable",
+			selectedValues,
+			reason: `No trusted ${field} scope is available for this result.`
+		};
+		return {
+			field,
+			status: "unambiguous",
+			selectedValues,
+			reason: `The matching result set does not contain conflicting ${field} choices.`
+		};
+	});
+	const hasUnresolved = decisions.some((decision) => decision.status === "requires_filter");
+	const isNotVerifiable = decisions.some((decision) => decision.status === "not_verifiable");
+	const hasResolved = decisions.some((decision) => decision.status === "resolved_by_filter");
+	return {
+		status: hasUnresolved ? "unresolved" : isNotVerifiable ? "not_verifiable" : hasResolved ? "resolved" : "unambiguous",
+		decisions
+	};
+}
+function explainDocsSearchResults(options) {
+	const documentsById = new Map(options.documents.map((document) => [document.id, document]));
+	const documentsByResultKey = new Map(options.documents.map((document) => [getDocsSearchExplanationDocumentIdentity(document), document]));
+	return options.results.map((result, index, results) => {
+		const document = resolveDocsSearchExplanationDocument(result, documentsById, documentsByResultKey);
+		const analysis = analyzeDocsSearchDocument(options.query, document, true);
+		const rankingStrategy = options.resolveRankingStrategy(result);
+		const rankingReasons = rankingStrategy === "provider" ? [{
+			code: "provider_order",
+			description: `The ${options.provider} search adapter supplied this result order; provider-internal ranking details are not available to the shared pipeline.`
+		}] : [...analysis.rankingReasons];
+		if (rankingStrategy === "exact") rankingReasons.unshift({
+			code: "exact_page_boost",
+			contribution: 2e3,
+			description: "An exact normalized page-title or URL-segment match was promoted."
+		});
+		if (rankingStrategy === "provider" && insideLiteralResultPriority(options.query, result) > 0) rankingReasons.push({
+			code: "literal_result_priority",
+			description: "The shared pipeline promoted this distinct section because it matched a short literal lookup."
+		});
+		const resultScore = result.score;
+		const previousScore = index > 0 ? results[index - 1]?.score : void 0;
+		const nextScore = index + 1 < results.length ? results[index + 1]?.score : void 0;
+		if (rankingStrategy !== "provider" && resultScore !== void 0 && (resultScore === previousScore || resultScore === nextScore)) rankingReasons.push({
+			code: "stable_url_tiebreak",
+			description: "A stable URL comparison resolved an equal lexical score."
+		});
+		const selectedScope = result.source?.scope;
+		return {
+			...result,
+			explanation: {
+				format: "docs-search-explanation.v1",
+				rank: options.rankOffset + index + 1,
+				rankingStrategy,
+				matchedTerms: analysis.matchedTerms,
+				matchedTermsTruncated: analysis.matchedTermsTruncated,
+				selectedScope: selectedScope ? { ...selectedScope } : null,
+				filterDecisions: buildDocsSearchFilterDecisions(options.filters, selectedScope),
+				ambiguityResolution: buildDocsSearchAmbiguityResolution(options.filters, selectedScope, options.warnings, options.unverifiableAmbiguityFields),
+				rankingReasons
+			}
+		};
+	});
 }
 function buildSnippet(document, query) {
 	const q = query.trim().toLowerCase();
@@ -4568,6 +4762,7 @@ function createMcpSearchAdapter(config) {
 								query: query.query,
 								limit: pageSize,
 								locale: query.locale,
+								...query.explain ? { explain: true } : {},
 								...providerCursor !== void 0 ? { cursor: providerCursor } : {},
 								...forwardAudience ? { audience } : {},
 								...query.filters?.framework ? { framework: query.filters.framework } : {},
@@ -4994,7 +5189,8 @@ async function performDocsSearchInternal(options) {
 		locale: options.locale,
 		pathname: options.pathname,
 		audience,
-		...hasFilters ? { filters } : {}
+		...hasFilters ? { filters } : {},
+		...options.explain ? { explain: true } : {}
 	};
 	let currentIndexGeneration;
 	const getCurrentIndexGeneration = () => {
@@ -5017,24 +5213,64 @@ async function performDocsSearchInternal(options) {
 		});
 		return hostedIndexGeneration;
 	};
-	const finalizeResults = async (results) => enrichDocsSearchResultsWithSources({
-		results,
-		pages: scopedPages,
-		generationPages: options.generationPages ?? options.pages,
-		audience,
-		chunking: search.chunking,
-		locale: options.locale,
-		baseUrl: options.baseUrl,
-		indexGeneration: options.indexGeneration,
-		strictExternalOrigins: options.strictExternalOrigins,
-		filters,
-		requireCurrentIndexGeneration
-	});
+	let explanationWarnings;
+	const getExplanationWarnings = () => {
+		explanationWarnings ??= buildDocsSearchWarnings({
+			pages: corpusPages,
+			results: [],
+			filters,
+			query: options.query,
+			audience,
+			baseUrl: options.baseUrl,
+			completeResultSet: true
+		});
+		return explanationWarnings;
+	};
+	let explanationUnverifiableAmbiguityFields;
+	const getExplanationUnverifiableAmbiguityFields = () => {
+		explanationUnverifiableAmbiguityFields ??= new Set(SEARCH_AMBIGUITY_FIELDS.filter((field) => corpusPages.some((page) => {
+			if (scoreDocument(options.query, pageToSearchDocument(page, audience)) <= 0) return false;
+			const scope = resolveDocsSearchPageScope(page);
+			if (hasFilters && !docsSearchPageMatchesFilters(scope, filters)) return false;
+			return scope.conflicts.includes(field) || scope.declarations[field].length === 0;
+		})));
+		return explanationUnverifiableAmbiguityFields;
+	};
+	const finalizeResults = async (results, ranking = "lexical") => {
+		const enriched = await enrichDocsSearchResultsWithSources({
+			results,
+			pages: scopedPages,
+			generationPages: options.generationPages ?? options.pages,
+			audience,
+			chunking: search.chunking,
+			locale: options.locale,
+			baseUrl: options.baseUrl,
+			indexGeneration: options.indexGeneration,
+			strictExternalOrigins: options.strictExternalOrigins,
+			filters,
+			requireCurrentIndexGeneration
+		});
+		if (!options.explain) return enriched.map((result) => {
+			const { explanation: _explanation, ...resultWithoutExplanation } = result;
+			return resultWithoutExplanation;
+		});
+		return explainDocsSearchResults({
+			results: enriched,
+			documents: getDocuments(),
+			query: options.query,
+			filters,
+			warnings: getExplanationWarnings(),
+			unverifiableAmbiguityFields: getExplanationUnverifiableAmbiguityFields(),
+			provider: search.provider,
+			rankOffset: options.offset ?? 0,
+			resolveRankingStrategy: typeof ranking === "function" ? ranking : () => ranking
+		});
+	};
 	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),
+			results: await finalizeResults(fallback.results, "lexical"),
 			total: options.paginated ? fallback.total : fallback.results.length,
 			paginationMode: "local"
 		};
@@ -5084,7 +5320,7 @@ async function performDocsSearchInternal(options) {
 		if (search.provider === "simple") {
 			if (options.expectedTotal !== void 0 && adapterPage.total !== options.expectedTotal) throw new DocsPaginationCursorError();
 			return {
-				results: await finalizeResults(results),
+				results: await finalizeResults(results, "lexical"),
 				total: options.paginated ? adapterPage.total : results.length,
 				paginationMode: "local"
 			};
@@ -5116,7 +5352,7 @@ async function performDocsSearchInternal(options) {
 			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),
+				results: await finalizeResults(safeAdapterResults, "provider"),
 				total: adapterPage.total,
 				...adapterPage.nextCursor !== void 0 ? { nextCursor: adapterPage.nextCursor } : {},
 				paginationMode: "provider"
@@ -5125,20 +5361,30 @@ async function performDocsSearchInternal(options) {
 		if (options.supplementExternalResults === false) {
 			const bounded = safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
 			return {
-				results: await finalizeResults(bounded),
+				results: await finalizeResults(bounded, "provider"),
 				total: bounded.length,
 				paginationMode: "provider"
 			};
 		}
 		const simpleAudienceResults = audience === "agent" || results.length === 0 || safeAdapterResults.length < results.length ? await createSimpleSearchAdapter().search(query, context) : [];
+		const exactPageResults = buildExactPageSearchResults(options.query, scopedPages, audience);
+		const rankingStrategyByResult = /* @__PURE__ */ new Map();
+		for (const [group, strategy] of [
+			[exactPageResults, "exact"],
+			[safeAdapterResults, "provider"],
+			[simpleAudienceResults, "lexical"]
+		]) for (const result of group) {
+			const identity = getDocsSearchExplanationResultIdentity(result);
+			if (!rankingStrategyByResult.has(identity)) rankingStrategyByResult.set(identity, strategy);
+		}
 		const combinedResults = mergeSearchResults([
-			buildExactPageSearchResults(options.query, scopedPages, audience),
+			exactPageResults,
 			safeAdapterResults,
 			simpleAudienceResults
 		], audience === "agent" ? (result) => getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins) : void 0);
 		const bounded = prioritizeLiteralInsideResults(options.query, combinedResults).slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
 		return {
-			results: await finalizeResults(bounded),
+			results: await finalizeResults(bounded, (result) => rankingStrategyByResult.get(getDocsSearchExplanationResultIdentity(result)) ?? "provider"),
 			total: bounded.length,
 			paginationMode: "provider"
 		};
@@ -6350,10 +6596,12 @@ function buildDocsDiagnostics(config, options = {}) {
 					human: search.enabled ? apiQueryRoute("query={query}") : null,
 					agent: search.enabled ? apiQueryRoute("query={query}&audience=agent") : null,
 					structuredAgent: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured") : null,
+					explainedAgent: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured&explain=true") : null,
 					facets: search.enabled ? apiQueryRoute("audience=agent&response=facets") : null
 				},
 				agentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent") : null,
 				structuredAgentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured") : null,
+				explainedAgentEndpoint: search.enabled ? apiQueryRoute("query={query}&audience=agent&response=structured&explain=true") : null,
 				facetsEndpoint: search.enabled ? apiQueryRoute("audience=agent&response=facets") : null,
 				audienceParam: "audience",
 				defaultAudience: "human",
@@ -6365,6 +6613,10 @@ function buildDocsDiagnostics(config, options = {}) {
 					tags: "tags"
 				},
 				responseFormat: "docs-search.v1",
+				explainParam: "explain",
+				explainValue: "true",
+				explanationField: "explanation",
+				explanationFormat: "docs-search-explanation.v1",
 				facetsResponseFormat: "docs-search-facets.v1",
 				warningsField: "warnings",
 				facetParam: "facet",
@@ -8118,7 +8370,7 @@ function appendDocsMarkdownNegotiationStartLines(lines, context, variant) {
 }
 function appendDocsSearchStartLine(lines, context, variant) {
 	if (!context.searchEnabled) return;
-	lines.push(`- Discover valid search filters with ${context.apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tags values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, variant === "skill" ? `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; optionally repeat framework, version, package, or tags filters.` : `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; optionally repeat framework, version, package, or tags filters.`);
+	lines.push(`- Discover valid search filters with ${context.apiRoute}?audience=agent&response=facets before choosing framework, version, package, or tags values; continue a large field with facet={field}, limit={limit}, and its nextCursor.`, variant === "skill" ? `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when you do not know the page; optionally repeat framework, version, package, or tags filters and add explain=true for retrieval evidence.` : `- Search with ${context.apiRoute}?query={query}&audience=agent&response=structured when the route is unknown; optionally repeat framework, version, package, or tags filters and add explain=true for retrieval evidence.`);
 }
 function appendDocsContentChangesStartLine(lines, context) {
 	if (!context.contentChangesEnabled) return;
@@ -8489,6 +8741,7 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", apiRoute, apiCata
 			endpoint: apiQueryRoute("query={query}"),
 			agentEndpoint: apiQueryRoute("query={query}&audience=agent"),
 			structuredAgentEndpoint: apiQueryRoute("query={query}&audience=agent&response=structured"),
+			explainedAgentEndpoint: apiQueryRoute("query={query}&audience=agent&response=structured&explain=true"),
 			facetsEndpoint: apiQueryRoute("audience=agent&response=facets"),
 			method: "GET",
 			queryParam: "query",
@@ -8500,6 +8753,10 @@ function buildDocsAgentDiscoverySpec({ origin, entry = "docs", apiRoute, apiCata
 			structuredResponseValue: "structured",
 			facetsResponseValue: "facets",
 			responseFormat: "docs-search.v1",
+			explainParam: "explain",
+			explainValue: "true",
+			explanationField: "explanation",
+			explanationFormat: "docs-search-explanation.v1",
 			facetsResponseFormat: "docs-search-facets.v1",
 			filterParams: {
 				framework: "framework",

package/dist/{agent-Biyd8A98.mjs → agent-DuwSq3C7.mjs}

@@ -1,6 +1,6 @@
-import { B as findDocsMarkdownPage, at as renderDocsMarkdownDocument } from "./agent-Dze2Cy5B.mjs";
+import { B as findDocsMarkdownPage, at as renderDocsMarkdownDocument } from "./agent-D68WI6-N.mjs";
 import { v as normalizePageAgentFrontmatter, x as stripGeneratedPageAgentContractMarkdown } from "./markdown-sections-7OoA7ylx.mjs";
-import { c as hashGeneratedAgentContent, d as serializeGeneratedAgentDocument, s as GENERATED_AGENT_PROVENANCE_VERSION, u as parseGeneratedAgentDocument } from "./content-change-hydration-DpQ0KdAD.mjs";
+import { c as hashGeneratedAgentContent, d as serializeGeneratedAgentDocument, s as GENERATED_AGENT_PROVENANCE_VERSION, u as parseGeneratedAgentDocument } from "./content-change-hydration-CiMxs3LF.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
 import { _ as resolveDocsContentDir, a as loadDocsConfigModule, c as loadProjectEnv, d as readNavTitle, f as readNumberProperty, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral, u as readEnvReferenceProperty } from "./config-Wcdj-D0a.mjs";
 import { createRequire } from "node:module";

package/dist/{agent-evals-Burrzyam.mjs → agent-evals-CEvUQb_Z.mjs}

@@ -1,4 +1,4 @@
-import { An as normalizeAgentFramework, Dn as agentVersionConstraintGroupsOverlap, Mn as normalizeAgentScopeValues, Nn as normalizeAgentVersion, On as agentVersionConstraintMatches, Zt as buildDocsAskAIContext, bn as resolveSearchRequestConfig, dn as performDocsSearch, jn as normalizeAgentLocale, kn as agentVersionConstraintsOverlap, un as normalizeDocsSearchFilters } from "./agent-Dze2Cy5B.mjs";
+import { An as normalizeAgentFramework, Dn as agentVersionConstraintGroupsOverlap, Mn as normalizeAgentScopeValues, Nn as normalizeAgentVersion, On as agentVersionConstraintMatches, Zt as buildDocsAskAIContext, bn as resolveSearchRequestConfig, dn as performDocsSearch, jn as normalizeAgentLocale, kn as agentVersionConstraintsOverlap, un as normalizeDocsSearchFilters } from "./agent-D68WI6-N.mjs";
 import { S as upsertPageAgentContractMarkdown, l as stripDocsGeneratedAgentContractMarkers, o as findDocsMarkdownSection } from "./markdown-sections-7OoA7ylx.mjs";
 import { t as getDocsAgentSkillsConfiguredPaths } from "./agent-skills-server-D5qYU19g.mjs";
 import { buildDocsMcpContext } from "./mcp.mjs";

package/dist/{agent-export-whKAZQUI.mjs → agent-export-BMljO4ll.mjs}

@@ -1,12 +1,12 @@
-import { A as buildDocsAgentDiscoverySpec, Ft as renderDocsSitemapXml, It as resolveDocsSitemapConfig, Pt as renderDocsSitemapMarkdown, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, at as renderDocsMarkdownDocument, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, it as renderDocsLlmsTxt, jt as buildDocsSitemapManifest, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, st as renderDocsSkillDocument, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, wt as toDocsMarkdownUrl, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-Dze2Cy5B.mjs";
+import { A as buildDocsAgentDiscoverySpec, Ft as renderDocsSitemapXml, It as resolveDocsSitemapConfig, Pt as renderDocsSitemapMarkdown, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, at as renderDocsMarkdownDocument, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, it as renderDocsLlmsTxt, jt as buildDocsSitemapManifest, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, lt as resolveDocsAgentFeedbackConfig, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, rt as renderDocsAgentsDocument, st as renderDocsSkillDocument, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, wt as toDocsMarkdownUrl, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-D68WI6-N.mjs";
 import "./markdown-sections-7OoA7ylx.mjs";
 import { A as buildDocsLegacySkillsIndex, D as buildDocsA2AAgentCard, L as resolveDocsPublishedAgentSkill, O as buildDocsAgentSkillsIndex, a as DEFAULT_A2A_AGENT_CARD_ROUTE, b as DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, x as DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX } from "./standards-discovery-BKlEnK_H.mjs";
-import "./content-change-hydration-DpQ0KdAD.mjs";
+import "./content-change-hydration-CiMxs3LF.mjs";
 import { t as resolveDocsI18n } from "./i18n-hHVWcflJ.mjs";
-import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-D96X6eVX.mjs";
-import "./sitemap-server-BefXEox6.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-HWKsiZQS.mjs";
+import "./sitemap-server-_AeFxJQB.mjs";
 import { r as resolveConfiguredAgentSkills } from "./agent-skills-server-D5qYU19g.mjs";
-import "./agent-evals-Burrzyam.mjs";
+import "./agent-evals-CEvUQb_Z.mjs";
 import { createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "./mcp.mjs";
 import "./code-blocks-0wjOsqdJ.mjs";
 import "./server.mjs";

package/dist/{agent-WS4GXGh6.d.mts → agent-qJNbZUCZ.d.mts}

@@ -1,5 +1,5 @@
-import { $n as LlmsTxtConfig, An as DocsSearchFilterInput, Bn as DocsSitemapConfig, Cn as DocsSearchConfig, F as DocsAgentContentChangesConfig, Fn as DocsSearchResult, K as DocsAgentFeedbackData, Ln as DocsSearchSourcePage, Mt as DocsConfig, Nn as DocsSearchRequest, On as DocsSearchFacetsResponse, Pr as TypesenseDocsSearchConfig, Rt as DocsContentChangesResponse, Sn as DocsSearchChunkingConfig, Ut as DocsI18nConfig, Yn as FeedbackConfig, Yt as DocsMcpConfig, bn as DocsSearchAdapterFactory, er as LlmsTxtMaxCharsConfig, f as CustomDocsSearchConfig, gn as DocsRobotsConfig, gr as PageAgentFrontmatter, jn as DocsSearchFilters, kn as DocsSearchFilterField, nr as LlmsTxtSectionConfig, on as DocsPaginatedSearchResponse, r as AlgoliaDocsSearchConfig, rr as McpDocsSearchConfig, tr as LlmsTxtMaxCharsMode, vn as DocsSearchAdapter, vt as DocsAskAIMcpConfig, wn as DocsSearchDocument, wr as ResolvedDocsRelatedLink, zt as DocsContentSnapshot } from "./types-lGEHcx_6.mjs";
-import { O as DocsA2AAgentCardOptions, R as DocsDiscoveryApiRouteOptions, z as DocsPublishedAgentSkill } from "./standards-discovery-DPUEcUmb.mjs";
+import { Dn as DocsSearchDocument, Dr as PageAgentFrontmatter, En as DocsSearchConfig, F as DocsAgentContentChangesConfig, Fn as DocsSearchFilterField, Fr as ResolvedDocsRelatedLink, Gr as TypesenseDocsSearchConfig, In as DocsSearchFilterInput, Jn as DocsSearchSourcePage, K as DocsAgentFeedbackData, Kn as DocsSearchResult, Ln as DocsSearchFilters, Mn as DocsSearchFacetsResponse, Mt as DocsConfig, Rt as DocsContentChangesResponse, Tn as DocsSearchChunkingConfig, Ut as DocsI18nConfig, Wn as DocsSearchRequest, Yt as DocsMcpConfig, Zn as DocsSitemapConfig, bn as DocsSearchAdapterFactory, dr as LlmsTxtMaxCharsConfig, f as CustomDocsSearchConfig, fr as LlmsTxtMaxCharsMode, gn as DocsRobotsConfig, mr as McpDocsSearchConfig, on as DocsPaginatedSearchResponse, or as FeedbackConfig, pr as LlmsTxtSectionConfig, r as AlgoliaDocsSearchConfig, ur as LlmsTxtConfig, vn as DocsSearchAdapter, vt as DocsAskAIMcpConfig, zt as DocsContentSnapshot } from "./types-DQl2dvDl.mjs";
+import { O as DocsA2AAgentCardOptions, R as DocsDiscoveryApiRouteOptions, z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
 import { DocsMcpPage, DocsMcpResolvedConfig } from "./mcp.mjs";
 
 //#region src/i18n.d.ts
@@ -197,6 +197,8 @@ interface PerformDocsSearchOptions {
   cursor?: string;
   /** Optional framework, version, package, and tag constraints. */
   filters?: DocsSearchFilterInput;
+  /** Include bounded explanations for the final ranked results. Defaults to false. */
+  explain?: boolean;
   /**
    * Controls provider failures. Runtime search keeps the resilient `fallback` default;
    * diagnostics can request `throw` so a broken configured provider cannot be scored as
@@ -529,6 +531,7 @@ interface DocsDiagnosticsFeature {
   routes?: Record<string, string | null>;
   agentEndpoint?: string | null;
   structuredAgentEndpoint?: string | null;
+  explainedAgentEndpoint?: string | null;
   facetsEndpoint?: string | null;
   audienceParam?: string;
   defaultAudience?: "human" | "agent";
@@ -540,6 +543,10 @@ interface DocsDiagnosticsFeature {
     tags: "tags";
   };
   responseFormat?: "docs-search.v1";
+  explainParam?: "explain";
+  explainValue?: "true";
+  explanationField?: "explanation";
+  explanationFormat?: "docs-search-explanation.v1";
   facetsResponseFormat?: "docs-search-facets.v1";
   format?: string;
   sinceParam?: string;
@@ -1162,6 +1169,7 @@ declare function buildDocsAgentDiscoverySpec({
     endpoint: string;
     agentEndpoint: string;
     structuredAgentEndpoint: string;
+    explainedAgentEndpoint: string;
     facetsEndpoint: string;
     method: string;
     queryParam: string;
@@ -1173,6 +1181,10 @@ declare function buildDocsAgentDiscoverySpec({
     structuredResponseValue: string;
     facetsResponseValue: string;
     responseFormat: string;
+    explainParam: string;
+    explainValue: string;
+    explanationField: string;
+    explanationFormat: string;
     facetsResponseFormat: string;
     filterParams: {
       framework: string;

package/dist/agent-skills-bundle.d.mts

@@ -1,4 +1,4 @@
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-DPUEcUmb.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
 
 //#region src/agent-skills-bundle.d.ts
 /**

package/dist/{agent-skills-server-q4B9kRGg.d.mts → agent-skills-server-aKgt9CR9.d.mts}

@@ -1,5 +1,5 @@
-import { tt as DocsAgentSkillsInput } from "./types-lGEHcx_6.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-DPUEcUmb.mjs";
+import { tt as DocsAgentSkillsInput } from "./types-DQl2dvDl.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
 
 //#region src/agent-skills-server.d.ts
 interface ResolveConfiguredAgentSkillsOptions {

package/dist/agent-skills-vite.d.mts

@@ -1,6 +1,6 @@
-import { tt as DocsAgentSkillsInput } from "./types-lGEHcx_6.mjs";
-import { z as DocsPublishedAgentSkill } from "./standards-discovery-DPUEcUmb.mjs";
-import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-q4B9kRGg.mjs";
+import { tt as DocsAgentSkillsInput } from "./types-DQl2dvDl.mjs";
+import { z as DocsPublishedAgentSkill } from "./standards-discovery-UdXpOfmN.mjs";
+import { t as ResolveConfiguredAgentSkillsOptions } from "./agent-skills-server-aKgt9CR9.mjs";
 
 //#region src/agent-skills-vite.d.ts
 declare const DOCS_AGENT_SKILLS_BUNDLE_MODULE = "@farming-labs/docs/agent-skills-bundle";