@farming-labs/docs 0.2.71 → 0.2.72

package/dist/{search-x5O0-9X3.mjs → search-BbArHODP.mjs}

@@ -1,4 +1,4 @@
-import { At as resolveDocsAudienceMdxContent, G as isDocsAgentDiscoveryRequest, Gt as findDocsMarkdownSection, K as isDocsAgentsRequest, Kt as parseDocsMarkdownSections, Q as isDocsSkillRequest, Qt as PAGE_AGENT_CONTRACT_START_MARKER, Yt as PAGE_AGENT_CONTRACT_END_MARKER, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackConfig, on as upsertPageAgentContractMarkdown, pt as resolveDocsLlmsTxtRequest, rn as renderPageAgentContractMarkdown, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-FIyl4-Oa.mjs";
+import { At as resolveDocsAudienceMdxContent, G as isDocsAgentDiscoveryRequest, Gt as findDocsMarkdownSection, K as isDocsAgentsRequest, Kt as parseDocsMarkdownSections, Q as isDocsSkillRequest, Qt as PAGE_AGENT_CONTRACT_START_MARKER, Yt as PAGE_AGENT_CONTRACT_END_MARKER, _t as resolveDocsMarkdownRequest, dt as resolveDocsAgentsFormat, lt as resolveDocsAgentFeedbackConfig, on as upsertPageAgentContractMarkdown, pt as resolveDocsLlmsTxtRequest, rn as renderPageAgentContractMarkdown, ut as resolveDocsAgentFeedbackRequest, xt as resolveDocsSkillFormat } from "./agent-pS2nNQS3.mjs";
 
 //#region src/telemetry.ts
 const DOCS_PACKAGE_NAME = "@farming-labs/docs";
@@ -457,6 +457,326 @@ function serializeGeneratedAgentDocument(content, provenance) {
 	].join("\n")}\n`;
 }
 
+//#endregion
+//#region src/agent-scope.ts
+/** Normalize framework aliases used by page metadata, agent contracts, MCP, and evaluations. */
+function normalizeAgentFramework(value) {
+	const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+	if ([
+		"next",
+		"nextjs",
+		"nextjsapp",
+		"reactnext"
+	].includes(normalized)) return "nextjs";
+	if ([
+		"tanstack",
+		"tanstackstart",
+		"start"
+	].includes(normalized)) return "tanstackstart";
+	if (["svelte", "sveltekit"].includes(normalized)) return "sveltekit";
+	if (["nuxt", "nuxtjs"].includes(normalized)) return "nuxt";
+	return normalized;
+}
+function normalizeAgentLocale(value) {
+	return value.trim().toLowerCase().replace(/_/gu, "-");
+}
+function normalizeAgentVersion(value) {
+	return value.trim().toLowerCase().replace(/^v(?=\d)/u, "");
+}
+function normalizeAgentScopeValues(value) {
+	const values = Array.isArray(value) ? value : typeof value === "string" ? [value] : [];
+	return Array.from(new Set(values.map((item) => item.trim()).filter(Boolean)));
+}
+function compareVersions(left, right) {
+	for (let index = 0; index < 3; index += 1) if (left[index] !== right[index]) return left[index] > right[index] ? 1 : -1;
+	return 0;
+}
+function parseExactVersion(value) {
+	const match = normalizeAgentVersion(value).match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/iu);
+	if (!match) return void 0;
+	return [
+		Number(match[1]),
+		Number(match[2] ?? 0),
+		Number(match[3] ?? 0)
+	];
+}
+function parseVersionOperand(value) {
+	const normalized = normalizeAgentVersion(value);
+	if (normalized === "*" || normalized === "x") return {
+		version: [
+			0,
+			0,
+			0
+		],
+		components: 0,
+		wildcard: true
+	};
+	const match = normalized.match(/^(\d+)(?:\.(\d+|x|\*))?(?:\.(\d+|x|\*))?$/iu);
+	if (!match) return void 0;
+	const raw = [
+		match[1],
+		match[2],
+		match[3]
+	];
+	const wildcardIndex = raw.findIndex((part, index) => index > 0 && (part?.toLowerCase() === "x" || part === "*"));
+	if (wildcardIndex >= 0 && raw.slice(wildcardIndex + 1).some((part) => part && part.toLowerCase() !== "x" && part !== "*")) return;
+	const components = wildcardIndex >= 0 ? wildcardIndex : raw.filter(Boolean).length;
+	return {
+		version: [
+			Number(raw[0]),
+			Number(raw[1] ?? 0) || 0,
+			Number(raw[2] ?? 0) || 0
+		],
+		components,
+		wildcard: wildcardIndex >= 0
+	};
+}
+function nextVersionBoundary(operand) {
+	const [major, minor] = operand.version;
+	if (operand.components <= 0) return void 0;
+	if (operand.components === 1) return [
+		major + 1,
+		0,
+		0
+	];
+	return [
+		major,
+		minor + 1,
+		0
+	];
+}
+function operandRange(operand) {
+	if (operand.components === 0) return {
+		minimumInclusive: true,
+		maximumInclusive: false
+	};
+	if (operand.components < 3 || operand.wildcard) return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum: nextVersionBoundary(operand),
+		maximumInclusive: false
+	};
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum: operand.version,
+		maximumInclusive: true
+	};
+}
+function caretRange(operand) {
+	const [major, minor, patch] = operand.version;
+	let maximum;
+	if (major > 0) maximum = [
+		major + 1,
+		0,
+		0
+	];
+	else if (operand.components <= 1) maximum = [
+		1,
+		0,
+		0
+	];
+	else if (minor > 0 || operand.components === 2) maximum = [
+		0,
+		minor + 1,
+		0
+	];
+	else maximum = [
+		0,
+		0,
+		patch + 1
+	];
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum,
+		maximumInclusive: false
+	};
+}
+function tildeRange(operand) {
+	const [major, minor] = operand.version;
+	const maximum = operand.components <= 1 ? [
+		major + 1,
+		0,
+		0
+	] : [
+		major,
+		minor + 1,
+		0
+	];
+	return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximum,
+		maximumInclusive: false
+	};
+}
+function intersectRanges(left, right) {
+	let minimum = left.minimum;
+	let minimumInclusive = left.minimumInclusive;
+	if (!minimum || right.minimum && compareVersions(right.minimum, minimum) > 0) {
+		minimum = right.minimum;
+		minimumInclusive = right.minimumInclusive;
+	} else if (right.minimum && compareVersions(right.minimum, minimum) === 0) minimumInclusive = minimumInclusive && right.minimumInclusive;
+	let maximum = left.maximum;
+	let maximumInclusive = left.maximumInclusive;
+	if (!maximum || right.maximum && compareVersions(right.maximum, maximum) < 0) {
+		maximum = right.maximum;
+		maximumInclusive = right.maximumInclusive;
+	} else if (right.maximum && compareVersions(right.maximum, maximum) === 0) maximumInclusive = maximumInclusive && right.maximumInclusive;
+	if (minimum && maximum) {
+		const compared = compareVersions(minimum, maximum);
+		if (compared > 0 || compared === 0 && !(minimumInclusive && maximumInclusive)) return void 0;
+	}
+	return {
+		minimum,
+		minimumInclusive,
+		maximum,
+		maximumInclusive
+	};
+}
+function comparatorRange(operator, operand) {
+	if (!operator || operator === "=") return operandRange(operand);
+	if (operator === ">=") return {
+		minimum: operand.version,
+		minimumInclusive: true,
+		maximumInclusive: false
+	};
+	if (operator === ">") {
+		const partialBoundary = operand.components < 3 ? nextVersionBoundary(operand) : void 0;
+		return {
+			minimum: partialBoundary ?? operand.version,
+			minimumInclusive: Boolean(partialBoundary),
+			maximumInclusive: false
+		};
+	}
+	if (operator === "<") return {
+		minimumInclusive: true,
+		maximum: operand.version,
+		maximumInclusive: false
+	};
+	const partialBoundary = operand.components < 3 ? nextVersionBoundary(operand) : void 0;
+	return {
+		minimumInclusive: true,
+		maximum: partialBoundary ?? operand.version,
+		maximumInclusive: !partialBoundary
+	};
+}
+function parseVersionRangeBranch(value) {
+	const branch = normalizeAgentVersion(value).trim();
+	if (!branch) return void 0;
+	const hyphen = branch.match(/^(.+?)\s+-\s+(.+)$/u);
+	if (hyphen) {
+		const minimumOperand = parseVersionOperand(hyphen[1]);
+		const maximumOperand = parseVersionOperand(hyphen[2]);
+		if (!minimumOperand || !maximumOperand) return void 0;
+		const maximumBoundary = maximumOperand.components < 3 ? nextVersionBoundary(maximumOperand) : maximumOperand.version;
+		return intersectRanges({
+			minimum: minimumOperand.version,
+			minimumInclusive: true,
+			maximumInclusive: false
+		}, {
+			minimumInclusive: true,
+			maximum: maximumBoundary,
+			maximumInclusive: maximumOperand.components === 3
+		});
+	}
+	const special = branch.match(/^(\^|~)\s*(.+)$/u);
+	if (special) {
+		const operand = parseVersionOperand(special[2]);
+		if (!operand || operand.components === 0) return void 0;
+		return special[1] === "^" ? caretRange(operand) : tildeRange(operand);
+	}
+	const comparators = Array.from(branch.matchAll(/(>=|<=|>|<|=)\s*([^\s]+)/gu));
+	if (comparators.length > 0) {
+		if (comparators.map((match) => match[0]).join(" ").replace(/\s+/gu, " ") !== branch.replace(/\s+/gu, " ")) return void 0;
+		let range = {
+			minimumInclusive: true,
+			maximumInclusive: false
+		};
+		for (const comparator of comparators) {
+			const operand = parseVersionOperand(comparator[2]);
+			if (!operand) return void 0;
+			const next = intersectRanges(range, comparatorRange(comparator[1], operand));
+			if (!next) return void 0;
+			range = next;
+		}
+		return range;
+	}
+	const operand = parseVersionOperand(branch);
+	return operand ? operandRange(operand) : void 0;
+}
+function parseVersionRanges(value) {
+	return normalizeAgentVersion(value).split("||").map((branch) => parseVersionRangeBranch(branch)).filter((range) => Boolean(range));
+}
+function parseVersionConstraintBranches(value) {
+	const ranges = parseVersionRanges(value);
+	if (ranges.length > 0) return ranges.map((range) => ({
+		kind: "range",
+		range
+	}));
+	const normalized = normalizeAgentVersion(value);
+	return normalized ? [{
+		kind: "opaque",
+		value: normalized
+	}] : [];
+}
+function intersectVersionConstraintBranches(left, right) {
+	if (left.kind === "opaque" || right.kind === "opaque") return left.kind === "opaque" && right.kind === "opaque" && left.value === right.value ? left : void 0;
+	const range = intersectRanges(left.range, right.range);
+	return range ? {
+		kind: "range",
+		range
+	} : void 0;
+}
+/**
+* Return true when choosing one alternative from every group can select one shared version.
+*
+* Each inner group is an OR list while the groups themselves are intersected. Computing the
+* accumulated range prevents pairwise matches from accepting three mutually incompatible scopes.
+*/
+function agentVersionConstraintGroupsOverlap(groups) {
+	if (groups.length === 0) return false;
+	let intersections = groups[0].flatMap(parseVersionConstraintBranches);
+	if (intersections.length === 0) return false;
+	for (const group of groups.slice(1)) {
+		const branches = group.flatMap(parseVersionConstraintBranches);
+		if (branches.length === 0) return false;
+		intersections = intersections.flatMap((intersection) => branches.map((branch) => intersectVersionConstraintBranches(intersection, branch)).filter((value) => Boolean(value)));
+		if (intersections.length === 0) return false;
+	}
+	return true;
+}
+function rangeContains(range, version) {
+	if (range.minimum) {
+		const compared = compareVersions(version, range.minimum);
+		if (compared < 0 || compared === 0 && !range.minimumInclusive) return false;
+	}
+	if (range.maximum) {
+		const compared = compareVersions(version, range.maximum);
+		if (compared > 0 || compared === 0 && !range.maximumInclusive) return false;
+	}
+	return true;
+}
+function rangesOverlap(left, right) {
+	return Boolean(intersectRanges(left, right));
+}
+/** Match an exact requested version against an exact or range-like documented constraint. */
+function agentVersionConstraintMatches(requested, constraint) {
+	if (normalizeAgentVersion(requested) === normalizeAgentVersion(constraint)) return Boolean(normalizeAgentVersion(requested));
+	const wanted = parseExactVersion(requested);
+	if (!wanted) return false;
+	return parseVersionRanges(constraint).some((range) => rangeContains(range, wanted));
+}
+/** Return true when two exact or range-like documented version constraints can select one version. */
+function agentVersionConstraintsOverlap(left, right) {
+	const normalizedLeft = normalizeAgentVersion(left);
+	if (normalizedLeft === normalizeAgentVersion(right)) return Boolean(normalizedLeft);
+	const leftRanges = parseVersionRanges(left);
+	const rightRanges = parseVersionRanges(right);
+	return leftRanges.some((leftRange) => rightRanges.some((rightRange) => rangesOverlap(leftRange, rightRange)));
+}
+
 //#endregion
 //#region src/search.ts
 const DEFAULT_SEARCH_LIMIT = 10;
@@ -467,6 +787,26 @@ const syncedIndexes = /* @__PURE__ */ new Set();
 const ALGOLIA_MAX_RECORD_BYTES = 9500;
 const DEFAULT_ASK_AI_CONTEXT_CHARS = 24e3;
 const DEFAULT_ASK_AI_RESULT_CHARS = 6e3;
+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_PROVIDER_SCOPE_FILTER_IDS = 1e3;
+const MAX_PROVIDER_SCOPE_FILTER_CHARS = 16e3;
+const MAX_SEARCH_WARNINGS = 16;
+const MAX_SEARCH_WARNING_VALUES = 16;
+const MAX_SEARCH_WARNING_PAGE_URLS = 8;
+const SEARCH_FILTER_FIELDS = [
+	"framework",
+	"version",
+	"package",
+	"tags"
+];
+const SEARCH_AMBIGUITY_FIELDS = [
+	"framework",
+	"version",
+	"package"
+];
 const SEARCH_STOP_WORDS = new Set([
 	"a",
 	"an",
@@ -498,6 +838,143 @@ const SEARCH_STOP_WORDS = new Set([
 	"which",
 	"with"
 ]);
+function normalizeDocsSearchFilterValue(field, value) {
+	const bounded = value.trim().slice(0, MAX_SEARCH_FILTER_VALUE_CHARS).trim();
+	if (!bounded) return "";
+	if (field === "framework") return normalizeAgentFramework(bounded);
+	if (field === "version") return normalizeAgentVersion(bounded);
+	return bounded.toLowerCase();
+}
+function normalizeDocsSearchFilterValues(field, input) {
+	const values = typeof input === "string" ? [input] : input ?? [];
+	const normalized = [];
+	const seen = /* @__PURE__ */ new Set();
+	let remainingChars = MAX_SEARCH_FILTER_RAW_CHARS;
+	let remainingSegments = MAX_SEARCH_FILTER_SEGMENTS;
+	for (const item of values) {
+		if (remainingChars <= 0 || remainingSegments <= 0) break;
+		const boundedItem = item.slice(0, remainingChars);
+		remainingChars -= boundedItem.length;
+		for (const part of boundedItem.split(",")) {
+			if (remainingSegments <= 0) break;
+			remainingSegments -= 1;
+			const value = normalizeDocsSearchFilterValue(field, part);
+			if (!value || seen.has(value)) continue;
+			seen.add(value);
+			normalized.push(value);
+			if (normalized.length >= MAX_SEARCH_FILTER_VALUES) return normalized;
+		}
+	}
+	return normalized;
+}
+/** Normalize scalar or array-valued scope filters for programmatic, HTTP, and MCP callers. */
+function normalizeDocsSearchFilters(input = {}) {
+	const filters = {};
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = normalizeDocsSearchFilterValues(field, input[field]);
+		if (values.length > 0) filters[field] = values;
+	}
+	return filters;
+}
+/** Parse the public search scope parameters from a URL query string. */
+function resolveDocsSearchFilters(searchParams) {
+	return normalizeDocsSearchFilters({
+		framework: searchParams.getAll("framework"),
+		version: searchParams.getAll("version"),
+		package: searchParams.getAll("package"),
+		tags: searchParams.getAll("tags")
+	});
+}
+/** Resolve search filters and the backwards-compatible structured response opt-in. */
+function resolveDocsSearchRequest(searchParams) {
+	return {
+		filters: resolveDocsSearchFilters(searchParams),
+		structured: searchParams.get("response") === "structured"
+	};
+}
+function hasDocsSearchFilters(filters) {
+	return SEARCH_FILTER_FIELDS.some((field) => (filters[field]?.length ?? 0) > 0);
+}
+function resolveProviderScopeDocumentIds(query, context) {
+	if (!hasDocsSearchFilters(query.filters ?? {})) return void 0;
+	const ids = Array.from(new Set(context.documents.map((document) => document.id)));
+	return ids.length <= MAX_PROVIDER_SCOPE_FILTER_IDS ? ids : [];
+}
+function docsSearchFiltersMatch(expected, actual) {
+	return SEARCH_FILTER_FIELDS.every((field) => {
+		const expectedValues = expected[field] ?? [];
+		const actualValues = actual[field] ?? [];
+		return expectedValues.length === actualValues.length && expectedValues.every((value) => actualValues.includes(value));
+	});
+}
+function parseVerifiedMcpSearchFilters(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+	const record = value;
+	const filterFields = SEARCH_FILTER_FIELDS;
+	if (Object.keys(record).some((field) => !filterFields.includes(field))) return;
+	const input = {};
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = record[field];
+		if (values === void 0) continue;
+		if (!Array.isArray(values) || values.length > MAX_SEARCH_FILTER_VALUES || values.some((item) => typeof item !== "string" || item.length > MAX_SEARCH_FILTER_VALUE_CHARS)) return;
+		input[field] = values;
+	}
+	const normalized = normalizeDocsSearchFilters(input);
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const values = record[field];
+		if (values === void 0) continue;
+		if (!Array.isArray(values) || values.length !== (normalized[field]?.length ?? 0) || values.some((value, index) => value !== normalized[field]?.[index])) return;
+	}
+	return normalized;
+}
+function normalizeDocsSearchMetadataValues(field, value) {
+	const values = normalizeAgentScopeValues(value);
+	return Array.from(new Set(values.map((item) => normalizeDocsSearchFilterValue(field, item)).filter((item) => Boolean(item))));
+}
+function valuesOverlap(left, right, matches) {
+	return left.some((leftValue) => right.some((rightValue) => matches(leftValue, rightValue)));
+}
+function resolveDocsSearchPageScope(page) {
+	const topFramework = normalizeDocsSearchMetadataValues("framework", page.framework);
+	const contractFramework = normalizeDocsSearchMetadataValues("framework", page.agent?.appliesTo?.framework);
+	const topVersion = normalizeDocsSearchMetadataValues("version", page.version);
+	const contractVersion = normalizeDocsSearchMetadataValues("version", page.agent?.appliesTo?.version);
+	const packageValues = normalizeDocsSearchMetadataValues("package", page.agent?.appliesTo?.package);
+	const tags = normalizeDocsSearchMetadataValues("tags", page.tags);
+	const conflicts = [];
+	if (topFramework.length > 0 && contractFramework.length > 0 && !valuesOverlap(topFramework, contractFramework, (left, right) => left === right)) conflicts.push("framework");
+	if (topVersion.length > 0 && contractVersion.length > 0 && !valuesOverlap(topVersion, contractVersion, agentVersionConstraintsOverlap)) conflicts.push("version");
+	return {
+		framework: topFramework.length > 0 && contractFramework.length > 0 ? topFramework.filter((value) => contractFramework.includes(value)) : Array.from(new Set([...topFramework, ...contractFramework])),
+		version: Array.from(new Set([...topVersion, ...contractVersion])),
+		package: packageValues,
+		tags,
+		declarations: {
+			framework: [topFramework, contractFramework].filter((values) => values.length > 0),
+			version: [topVersion, contractVersion].filter((values) => values.length > 0),
+			package: packageValues.length > 0 ? [packageValues] : [],
+			tags: tags.length > 0 ? [tags] : []
+		},
+		conflicts
+	};
+}
+function docsSearchScopeValueMatches(field, requested, candidate) {
+	return field === "version" ? agentVersionConstraintsOverlap(requested, candidate) : requested === candidate;
+}
+function docsSearchPageMatchesFilters(scope, filters) {
+	if (scope.conflicts.length > 0) return false;
+	return SEARCH_FILTER_FIELDS.every((field) => {
+		const requested = filters[field];
+		if (!requested || requested.length === 0) return true;
+		return docsSearchScopeFieldMatches(scope, field, requested);
+	});
+}
+function docsSearchScopeFieldMatches(scope, field, requested) {
+	const declarations = scope.declarations[field];
+	if (declarations.length === 0) return false;
+	if (field === "version") return agentVersionConstraintGroupsOverlap([requested, ...declarations]);
+	return requested.some((value) => declarations.every((candidates) => candidates.some((candidate) => docsSearchScopeValueMatches(field, value, candidate))));
+}
 function stripMarkdownText(content) {
 	return removeMdxModuleLinesOutsideFences(content).replace(/```[^\n]*\n([\s\S]*?)```/g, "$1").replace(/```([\s\S]*?)```/g, "$1").replace(/~~~[^\n]*\n([\s\S]*?)~~~/g, "$1").replace(/~~~([\s\S]*?)~~~/g, "$1").replace(/<[^>]+\/>/g, "").replace(/<\/?[A-Z][^>]*>/g, "").replace(/<\/?[a-z][^>]*>/g, "").replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/^#{1,6}\s+/gm, "").replace(/^\|?[\s:-]+(\|[\s:-]+)+\|?\s*$/gm, "").replace(/\|/g, " ").replace(/^[-*+]\s+/gm, "").replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2").replace(/`{3,}[^\n]*$/gm, "").replace(/`([^`]+)`/g, "$1").replace(/`+/g, "").replace(/^>\s+/gm, "").replace(/^[-*_]{3,}\s*$/gm, "").replace(/\n{3,}/g, "\n\n").replace(/\s{2,}/g, " ").trim();
 }
@@ -830,6 +1307,7 @@ function hasOppositeAudienceEvidence(options) {
 	return oppositeOnlyMatches > selectedOnlyMatches;
 }
 function pageToSearchDocument(page, audience = "human") {
+	const scope = resolveDocsSearchPageScope(page);
 	return {
 		id: makeDocumentId(page.url, "page"),
 		url: page.url,
@@ -838,9 +1316,10 @@ function pageToSearchDocument(page, audience = "human") {
 		description: page.description,
 		type: "page",
 		locale: page.locale,
-		framework: page.framework,
-		version: page.version,
-		tags: page.tags
+		framework: scope.framework[0],
+		version: scope.version[0],
+		package: scope.package.length > 0 ? scope.package : void 0,
+		tags: scope.tags.length > 0 ? scope.tags : void 0
 	};
 }
 function buildExactPageSearchResults(query, pages, audience = "human") {
@@ -903,7 +1382,9 @@ function makeDocumentId(url, suffix) {
 	return `${url}#${suffix}`;
 }
 function splitPageIntoSections(page, audience = "human") {
-	return parseDocsMarkdownSections(getPageAudienceRawContent(page, audience)).flatMap((section, index) => {
+	const raw = getPageAudienceRawContent(page, audience);
+	const scope = resolveDocsSearchPageScope(page);
+	return parseDocsMarkdownSections(raw).flatMap((section, index) => {
 		const content = normalizeWhitespace(stripMarkdownText(section.content));
 		if (!content) return [];
 		return [{
@@ -915,9 +1396,10 @@ function splitPageIntoSections(page, audience = "human") {
 			description: page.description,
 			type: "heading",
 			locale: page.locale,
-			framework: page.framework,
-			version: page.version,
-			tags: page.tags
+			framework: scope.framework[0],
+			version: scope.version[0],
+			package: scope.package.length > 0 ? scope.package : void 0,
+			tags: scope.tags.length > 0 ? scope.tags : void 0
 		}];
 	});
 }
@@ -1055,7 +1537,12 @@ function buildAlgoliaRecord(document) {
 		section: document.section,
 		content: document.content,
 		description: document.description,
-		type: document.type
+		type: document.type,
+		locale: document.locale,
+		framework: document.framework,
+		version: document.version,
+		package: document.package,
+		tags: document.tags
 	};
 	const encoder = new TextEncoder();
 	const sizeOf = (value) => encoder.encode(JSON.stringify(value)).length;
@@ -1160,6 +1647,14 @@ function mapMcpSearchResult(value) {
 		section
 	};
 }
+function readMcpSearchToolPayload(payload) {
+	if (!payload || typeof payload !== "object" || !("result" in payload) || !payload.result || typeof payload.result !== "object") return null;
+	const result = payload.result;
+	if (result.structuredContent && typeof result.structuredContent === "object" && !Array.isArray(result.structuredContent)) return result.structuredContent;
+	const content = Array.isArray(result.content) ? result.content : [];
+	const resultText = content.length > 0 && content[0] && typeof content[0] === "object" && "text" in content[0] && typeof content[0].text === "string" ? content[0].text : null;
+	return resultText ? JSON.parse(resultText) : null;
+}
 async function createOllamaEmbedding(text, config, signal) {
 	const response = await fetch(`${(config.baseUrl ?? "http://127.0.0.1:11434").replace(/\/$/, "")}/api/embed`, {
 		method: "POST",
@@ -1179,6 +1674,9 @@ async function createOllamaEmbedding(text, config, signal) {
 function getTypesenseSearchBase(config) {
 	return config.baseUrl.replace(/\/$/, "");
 }
+function quoteTypesenseFilterValue(value) {
+	return `\`${value.replace(/\\/gu, "\\\\").replace(/`/gu, "\\`")}\``;
+}
 async function ensureTypesenseCollection(config, dimensions, signal) {
 	const baseUrl = getTypesenseSearchBase(config);
 	const headers = {
@@ -1237,6 +1735,11 @@ async function ensureTypesenseCollection(config, dimensions, signal) {
 			type: "string",
 			optional: true
 		},
+		{
+			name: "package",
+			type: "string[]",
+			optional: true
+		},
 		{
 			name: "tags",
 			type: "string[]",
@@ -1276,6 +1779,7 @@ function createTypesenseSearchAdapter(config) {
 					locale: document.locale,
 					framework: document.framework,
 					version: document.version,
+					package: document.package,
 					tags: document.tags
 				};
 				if (config.mode === "hybrid" && config.embeddings) next.embedding = await createOllamaEmbedding(`${document.title}\n${document.section ?? ""}\n${document.content}`.trim(), config.embeddings, context.signal);
@@ -1294,6 +1798,8 @@ function createTypesenseSearchAdapter(config) {
 			}), "Failed to sync documents to Typesense");
 		},
 		async search(query, context) {
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context);
+			if (scopedDocumentIds?.length === 0) return [];
 			const params = new URLSearchParams({
 				q: query.query,
 				query_by: (config.queryBy ?? [
@@ -1311,12 +1817,27 @@ function createTypesenseSearchAdapter(config) {
 				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 response = await fetch(`${getTypesenseSearchBase(config)}/collections/${encodeURIComponent(config.collection)}/documents/search?${params.toString()}`, {
+			const filterBy = scopedDocumentIds ? `id:=[${scopedDocumentIds.map(quoteTypesenseFilterValue).join(",")}]` : void 0;
+			if (filterBy && filterBy.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) return [];
+			const response = filterBy ? await fetch(`${getTypesenseSearchBase(config)}/multi_search`, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-TYPESENSE-API-KEY": config.apiKey
+				},
+				body: JSON.stringify({ searches: [{
+					collection: config.collection,
+					...Object.fromEntries(params),
+					filter_by: filterBy
+				}] }),
+				signal: context.signal
+			}) : await fetch(`${getTypesenseSearchBase(config)}/collections/${encodeURIComponent(config.collection)}/documents/search?${params.toString()}`, {
 				headers: { "X-TYPESENSE-API-KEY": config.apiKey },
 				signal: context.signal
 			});
 			ensureOk(response, "Typesense search failed");
-			return ((await readResponseJson(response)).hits ?? []).map((hit) => {
+			const rawPayload = await readResponseJson(response);
+			return ((filterBy ? rawPayload.results?.[0] ?? {} : rawPayload).hits ?? []).map((hit) => {
 				const document = hit.document ?? {};
 				const section = typeof document.section === "string" ? document.section : void 0;
 				const content = typeof document.title === "string" ? section ? `${document.title} — ${section}` : document.title : typeof document.content === "string" ? document.content : "Untitled result";
@@ -1427,7 +1948,11 @@ function createMcpSearchAdapter(config) {
 								query: query.query,
 								limit: query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT,
 								locale: query.locale,
-								...forwardAudience ? { audience } : {}
+								...forwardAudience ? { audience } : {},
+								...query.filters?.framework ? { framework: query.filters.framework } : {},
+								...query.filters?.version ? { version: query.filters.version } : {},
+								...query.filters?.package ? { package: query.filters.package } : {},
+								...query.filters?.tags ? { tags: query.filters.tags } : {}
 							}
 						}
 					}),
@@ -1436,9 +1961,13 @@ function createMcpSearchAdapter(config) {
 				const payload = await readMcpResponsePayload(searchResponse);
 				ensureOk(searchResponse, "MCP search request failed");
 				ensureJsonRpcOk(payload, "MCP search request failed");
-				const resultText = payload && typeof payload === "object" && "result" in payload && payload.result && typeof payload.result === "object" && "content" in payload.result && Array.isArray(payload.result.content) && typeof payload.result.content[0]?.text === "string" ? payload.result.content[0].text : null;
-				if (!resultText) return [];
-				const parsed = JSON.parse(resultText);
+				const parsed = readMcpSearchToolPayload(payload);
+				if (!parsed) return [];
+				if (hasDocsSearchFilters(query.filters ?? {})) {
+					if (Array.isArray(parsed) || parsed.format !== "docs-search.v1") return [];
+					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(mapMcpSearchResult).filter((result) => Boolean(result));
 			} finally {
 				if (sessionId) {
@@ -1465,6 +1994,9 @@ function createMcpSearchAdapter(config) {
 function getAlgoliaBase(config) {
 	return `https://${config.appId}-dsn.algolia.net`;
 }
+function quoteAlgoliaFilterValue(value) {
+	return `"${value.replace(/\\/gu, "\\\\").replace(/"/gu, "\\\"")}"`;
+}
 function createAlgoliaSearchAdapter(config) {
 	return {
 		name: "algolia",
@@ -1485,6 +2017,10 @@ function createAlgoliaSearchAdapter(config) {
 			}), "Failed to sync documents to Algolia");
 		},
 		async search(query, context) {
+			const scopedDocumentIds = resolveProviderScopeDocumentIds(query, context);
+			if (scopedDocumentIds?.length === 0) return [];
+			const filters = scopedDocumentIds?.map((id) => `objectID:${quoteAlgoliaFilterValue(id)}`).join(" OR ");
+			if (filters && filters.length > MAX_PROVIDER_SCOPE_FILTER_CHARS) return [];
 			const response = await fetch(`${getAlgoliaBase(config)}/1/indexes/${encodeURIComponent(config.indexName)}/query`, {
 				method: "POST",
 				headers: {
@@ -1495,7 +2031,8 @@ function createAlgoliaSearchAdapter(config) {
 				body: JSON.stringify({
 					query: query.query,
 					hitsPerPage: query.limit ?? config.maxResults ?? DEFAULT_SEARCH_LIMIT,
-					attributesToSnippet: ["content:20"]
+					attributesToSnippet: ["content:20"],
+					...filters ? { filters } : {}
 				}),
 				signal: context.signal
 			});
@@ -1552,9 +2089,12 @@ async function performDocsSearch(options) {
 	const search = normalizeDocsSearchConfig(options.search);
 	if (!search.enabled) return [];
 	const audience = resolveDocsSearchAudience(options.audience);
-	const documents = buildDocsSearchDocuments(options.pages, search.chunking, audience);
+	const filters = normalizeDocsSearchFilters(options.filters);
+	const hasFilters = hasDocsSearchFilters(filters);
+	const scopedPages = hasFilters ? options.pages.filter((page) => docsSearchPageMatchesFilters(resolveDocsSearchPageScope(page), filters)) : options.pages;
+	const documents = buildDocsSearchDocuments(scopedPages, search.chunking, audience);
 	const context = {
-		pages: options.pages,
+		pages: scopedPages,
 		documents,
 		audience,
 		locale: options.locale,
@@ -1567,27 +2107,30 @@ async function performDocsSearch(options) {
 		limit: options.limit ?? search.maxResults,
 		locale: options.locale,
 		pathname: options.pathname,
-		audience
+		audience,
+		...hasFilters ? { filters } : {}
 	};
 	try {
 		const adapter = await resolveSearchAdapter(search, context);
-		await maybeSyncSearchIndex(adapter, search, audience === "agent" ? {
+		await maybeSyncSearchIndex(adapter, search, audience === "agent" || hasFilters ? {
 			...context,
+			pages: options.pages,
 			documents: buildDocsSearchDocuments(options.pages, search.chunking, "human"),
 			audience: "human"
 		} : context);
 		const results = await adapter.search(query, context);
 		if (search.provider === "simple") return results;
 		const localAudienceProjectionResults = buildAudienceProjectionSearchResults(documents, options.query);
-		const localPagePaths = new Set(options.pages.map((page) => normalizeUrlPathname(page.url)));
-		const preserveUnmatched = audience === "human" || search.provider === "mcp" ? (result) => shouldPreserveUnmatchedExternalResult({
+		const localPagePaths = new Set(scopedPages.map((page) => normalizeUrlPathname(page.url)));
+		const allLocalPagePaths = hasFilters && search.provider === "mcp" ? new Set(options.pages.map((page) => normalizeUrlPathname(page.url))) : localPagePaths;
+		const preserveUnmatched = !hasFilters && audience === "human" || search.provider === "mcp" ? (result) => shouldPreserveUnmatchedExternalResult({
 			result,
-			localPagePaths,
+			localPagePaths: allLocalPagePaths,
 			baseUrl: options.baseUrl
 		}) : void 0;
 		const safeAdapterResults = sanitizeExternalAudienceSearchResults(results.filter((result) => !hasOppositeAudienceEvidence({
 			result,
-			pages: options.pages,
+			pages: scopedPages,
 			query: options.query,
 			audience,
 			baseUrl: options.baseUrl,
@@ -1596,7 +2139,7 @@ async function performDocsSearch(options) {
 		if (options.supplementExternalResults === false) return safeAdapterResults.slice(0, query.limit ?? search.maxResults ?? DEFAULT_SEARCH_LIMIT);
 		const simpleAudienceResults = audience === "agent" || results.length === 0 || safeAdapterResults.length < results.length ? await createSimpleSearchAdapter().search(query, context) : [];
 		const combinedResults = mergeSearchResults([
-			buildExactPageSearchResults(options.query, options.pages, audience),
+			buildExactPageSearchResults(options.query, scopedPages, audience),
 			safeAdapterResults,
 			simpleAudienceResults
 		], audience === "agent" ? (result) => getAskAIResultKey(result, options.baseUrl, options.strictExternalOrigins) : void 0);
@@ -1606,6 +2149,127 @@ async function performDocsSearch(options) {
 		return createSimpleSearchAdapter().search(query, context);
 	}
 }
+function compareSearchMetadataValues(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
+}
+function boundedSearchWarningValues(values) {
+	const bounded = Array.from(new Set(values)).sort(compareSearchMetadataValues).slice(0, MAX_SEARCH_WARNING_VALUES);
+	return bounded.length > 0 ? bounded : void 0;
+}
+function boundedSearchWarningPageUrls(pages) {
+	const bounded = Array.from(new Set(pages.map((page) => page.url))).sort(compareSearchMetadataValues).slice(0, MAX_SEARCH_WARNING_PAGE_URLS);
+	return bounded.length > 0 ? bounded : void 0;
+}
+function findSearchResultPages(pages, results, baseUrl) {
+	const pagesByPath = new Map(pages.map((page) => [normalizeUrlPathname(page.url), page]));
+	const found = /* @__PURE__ */ new Map();
+	for (const result of results) {
+		if (!isLocalProviderResult(result, baseUrl, true)) continue;
+		const page = pagesByPath.get(normalizeUrlPathname(result.url));
+		if (page) found.set(page.url, page);
+	}
+	return [...found.values()].sort((left, right) => compareSearchMetadataValues(left.url, right.url));
+}
+function searchScopeIsAmbiguous(field, values) {
+	if (values.length < 2) return false;
+	if (field !== "version") return true;
+	return values.some((left, index) => values.slice(index + 1).some((right) => !agentVersionConstraintsOverlap(left, right)));
+}
+function buildDocsSearchWarnings(options) {
+	const pageScopes = options.pages.map((page) => ({
+		page,
+		scope: resolveDocsSearchPageScope(page)
+	}));
+	const relevantPageScopes = pageScopes.filter(({ page }) => scoreDocument(options.query, pageToSearchDocument(page, options.audience)) > 0);
+	const warnings = [];
+	for (const field of SEARCH_FILTER_FIELDS) {
+		const conflicting = relevantPageScopes.filter(({ scope }) => scope.conflicts.includes(field));
+		if (conflicting.length > 0) warnings.push({
+			code: "conflicting_scope_metadata",
+			field,
+			message: `${conflicting.length} page${conflicting.length === 1 ? "" : "s"} declare conflicting ${field} metadata and cannot be selected safely by scoped search.`,
+			pageUrls: boundedSearchWarningPageUrls(conflicting.map(({ page }) => page)),
+			count: conflicting.length
+		});
+		const requested = options.filters[field];
+		if (!requested || requested.length === 0) continue;
+		const missing = relevantPageScopes.filter(({ scope }) => scope.declarations[field].length === 0);
+		if (missing.length > 0) warnings.push({
+			code: "missing_scope_metadata",
+			field,
+			message: `${missing.length} page${missing.length === 1 ? "" : "s"} lack ${field} metadata and were excluded by the strict scope filter.`,
+			pageUrls: boundedSearchWarningPageUrls(missing.map(({ page }) => page)),
+			count: missing.length
+		});
+		const unknown = requested.filter((value) => !pageScopes.some(({ scope }) => !scope.conflicts.includes(field) && docsSearchScopeFieldMatches(scope, field, [value])));
+		if (unknown.length > 0) warnings.push({
+			code: "unknown_filter_value",
+			field,
+			message: `No page metadata matches ${field} filter value${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`,
+			values: boundedSearchWarningValues(unknown),
+			count: unknown.length
+		});
+	}
+	const resultPages = 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) => {
+			const scope = resolveDocsSearchPageScope(page);
+			return scope.conflicts.includes(field) ? [] : scope[field];
+		});
+		const unique = Array.from(new Set(values)).sort(compareSearchMetadataValues);
+		if (!searchScopeIsAmbiguous(field, unique)) continue;
+		const contributingPages = resultPages.filter((page) => {
+			const scope = resolveDocsSearchPageScope(page);
+			return !scope.conflicts.includes(field) && scope[field].length > 0;
+		});
+		warnings.push({
+			code: "ambiguous_scope",
+			field,
+			message: `Search results span multiple ${field} scopes; add a ${field} filter before acting on scope-specific guidance.`,
+			values: boundedSearchWarningValues(unique),
+			pageUrls: boundedSearchWarningPageUrls(contributingPages),
+			count: unique.length
+		});
+	}
+	const codeOrder = {
+		ambiguous_scope: 0,
+		unknown_filter_value: 1,
+		missing_scope_metadata: 2,
+		conflicting_scope_metadata: 3
+	};
+	return warnings.sort((left, right) => {
+		const codeDelta = codeOrder[left.code] - codeOrder[right.code];
+		if (codeDelta !== 0) return codeDelta;
+		return SEARCH_FILTER_FIELDS.indexOf(left.field) - SEARCH_FILTER_FIELDS.indexOf(right.field);
+	}).slice(0, MAX_SEARCH_WARNINGS);
+}
+async function performDocsSearchWithMetadata(options) {
+	const audience = resolveDocsSearchAudience(options.audience);
+	const filters = normalizeDocsSearchFilters(options.filters);
+	const results = await performDocsSearch({
+		...options,
+		audience,
+		filters
+	});
+	return {
+		format: "docs-search.v1",
+		query: options.query,
+		audience,
+		filters,
+		resultCount: results.length,
+		results,
+		warnings: buildDocsSearchWarnings({
+			pages: options.pages,
+			results,
+			filters,
+			query: options.query,
+			audience,
+			baseUrl: options.baseUrl
+		})
+	};
+}
 async function buildDocsAskAIContext(options) {
 	const limit = options.limit ?? 5;
 	const searchLimit = Math.max(limit * 2, limit);
@@ -1621,6 +2285,7 @@ async function buildDocsAskAIContext(options) {
 		siteTitle: options.siteTitle,
 		baseUrl: options.baseUrl,
 		limit: searchLimit,
+		filters: options.filters,
 		failureMode: options.searchFailureMode,
 		strictExternalOrigins: options.strictExternalOrigins,
 		signal: options.signal
@@ -1683,4 +2348,4 @@ function createCustomSearchAdapter(adapter) {
 }
 
 //#endregion
-export { inferDocsTelemetryAgentSurface as A, resolveSidebarFolderIndexBehavior as C, emitDocsTelemetryMcpToolEvent as D, emitDocsTelemetryEvent as E, normalizeDocsTelemetryOrigin as M, resolveDocsTelemetryConfig as N, emitDocsTelemetryProjectEvent as O, resolvePageSidebarFolderIndexBehavior as S, emitDocsTelemetryAgentSurfaceEvent as T, normalizeGeneratedAgentContent as _, createMcpSearchAdapter as a, stripGeneratedAgentProvenance as b, formatDocsAskAIPackageHints as c, resolveAskAISearchRequestConfig as d, resolveDocsSearchAudience as f, hashGeneratedAgentContent as g, GENERATED_AGENT_PROVENANCE_VERSION as h, createCustomSearchAdapter as i, isLocalDocsTelemetryOrigin as j, getDocsTelemetryFeatures as k, inferDocsAskAIPackageHints as l, GENERATED_AGENT_PROVENANCE_MARKER as m, buildDocsSearchDocuments as n, createSimpleSearchAdapter as o, resolveSearchRequestConfig as p, createAlgoliaSearchAdapter as r, createTypesenseSearchAdapter as s, buildDocsAskAIContext as t, performDocsSearch as u, parseGeneratedAgentDocument as v, resolveSidebarFolderIndexBehaviorForPath as w, applySidebarFolderIndexBehavior as x, serializeGeneratedAgentDocument as y };
+export { stripGeneratedAgentProvenance as A, inferDocsTelemetryAgentSurface as B, normalizeAgentVersion as C, normalizeGeneratedAgentContent as D, hashGeneratedAgentContent as E, emitDocsTelemetryAgentSurfaceEvent as F, normalizeDocsTelemetryOrigin as H, emitDocsTelemetryEvent as I, emitDocsTelemetryMcpToolEvent as L, resolvePageSidebarFolderIndexBehavior as M, resolveSidebarFolderIndexBehavior as N, parseGeneratedAgentDocument as O, resolveSidebarFolderIndexBehaviorForPath as P, emitDocsTelemetryProjectEvent as R, normalizeAgentScopeValues as S, GENERATED_AGENT_PROVENANCE_VERSION as T, resolveDocsTelemetryConfig as U, isLocalDocsTelemetryOrigin as V, resolveSearchRequestConfig as _, createMcpSearchAdapter as a, normalizeAgentFramework as b, formatDocsAskAIPackageHints as c, performDocsSearch as d, performDocsSearchWithMetadata as f, resolveDocsSearchRequest as g, resolveDocsSearchFilters as h, createCustomSearchAdapter as i, applySidebarFolderIndexBehavior as j, serializeGeneratedAgentDocument as k, inferDocsAskAIPackageHints as l, resolveDocsSearchAudience as m, buildDocsSearchDocuments as n, createSimpleSearchAdapter as o, resolveAskAISearchRequestConfig as p, createAlgoliaSearchAdapter as r, createTypesenseSearchAdapter as s, buildDocsAskAIContext as t, normalizeDocsSearchFilters as u, agentVersionConstraintMatches as v, GENERATED_AGENT_PROVENANCE_MARKER as w, normalizeAgentLocale as x, agentVersionConstraintsOverlap as y, getDocsTelemetryFeatures as z };