nimbus-docs 0.1.0 → 0.1.1

package/dist/index.js

@@ -11,16 +11,38 @@ import { z } from "astro/zod";
 
 //#region src/_internal/runtime-config.ts
 let _cached = null;
+let _cachedCollections = null;
+let _cachedAlternates = null;
 async function loadNimbusConfig() {
 	if (_cached) return _cached;
 	_cached = (await import("virtual:nimbus/config")).config;
 	return _cached;
 }
+/**
+* Build-time-resolved list of collections the agent-facing routes
+* (llms.txt, per-page .md alternates) should iterate. Reserved names
+* (`partials`, `_*`) are already filtered. See `getIndexedEntries()`.
+*/
+async function loadIndexedCollections() {
+	if (_cachedCollections) return _cachedCollections;
+	_cachedCollections = (await import("virtual:nimbus/config")).indexedCollections;
+	return _cachedCollections;
+}
+/**
+* Build-time-resolved alternates table for cross-version SEO links.
+* Returns the same object on every call (cached after first load).
+* Empty `{}` when the site is unversioned.
+*/
+async function loadVersionAlternates() {
+	if (_cachedAlternates) return _cachedAlternates;
+	_cachedAlternates = (await import("virtual:nimbus/config")).versionAlternates ?? {};
+	return _cachedAlternates;
+}
 
 //#endregion
 //#region src/_internal/content.ts
 /** Primary collection name. Hard-coded — see also `getDocsStaticPaths`. */
-const PRIMARY_COLLECTION$1 = "docs";
+const PRIMARY_COLLECTION$3 = "docs";
 /**
 * Return visible entries from one or more collections. Drafts are
 * filtered out in production builds (matching the existing
@@ -35,7 +57,7 @@ const PRIMARY_COLLECTION$1 = "docs";
 * time. Callers that need per-collection type safety should call
 * `getCollection("api")` directly.
 */
-async function getVisibleEntries(collections = [PRIMARY_COLLECTION$1]) {
+async function getVisibleEntries(collections = [PRIMARY_COLLECTION$3]) {
 	const { getCollection } = await import("astro:content");
 	const all = (await Promise.all(collections.map((name) => getCollection(name).catch(() => [])))).flat();
 	return import.meta.env.PROD ? all.filter((entry) => !entry.data.draft) : all;
@@ -193,7 +215,7 @@ function buildFilesystemTree(entries, currentPath, directory, hrefPrefix = "") {
 	if (directory) return buildLevel(directory);
 	return buildLevel("");
 }
-function resolveConfigItems(configItems, entriesByCollection, primaryCollection, currentPath, orderStart = 0) {
+function resolveConfigItems(configItems, entriesByCollection, primaryCollection, currentPath, orderStart = 0, primaryPrefix = "") {
 	const primaryEntries = entriesByCollection[primaryCollection] ?? [];
 	const { byId } = buildEntryIndex(primaryEntries);
 	const result = [];
@@ -203,7 +225,7 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 		if (typeof item === "string") {
 			const entry = byId.get(item);
 			if (entry) {
-				const link = createLink(entry, currentPath);
+				const link = createLink(entry, currentPath, primaryPrefix);
 				link.order = order;
 				result.push(link);
 			} else console.warn(`[sidebar] Page "${item}" referenced in config but not found in primary collection "${primaryCollection}"`);
@@ -239,8 +261,8 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 				if (!collectionEntries) {
 					console.warn(`[sidebar] autogenerate references collection "${collectionName}" which is not registered in nimbus.config.collections; skipping`);
 					autoItems = [];
-				} else autoItems = buildFilesystemTree(collectionEntries, currentPath, void 0, item.autogenerate.prefix ?? (collectionName === primaryCollection ? "" : `/${collectionName}`));
-			} else autoItems = buildFilesystemTree(primaryEntries, currentPath, item.autogenerate.directory);
+				} else autoItems = buildFilesystemTree(collectionEntries, currentPath, void 0, item.autogenerate.prefix ?? (collectionName === primaryCollection ? primaryPrefix : `/${collectionName}`));
+			} else autoItems = buildFilesystemTree(primaryEntries, currentPath, item.autogenerate.directory, primaryPrefix);
 			if (item.label) {
 				const group = {
 					type: "group",
@@ -258,7 +280,7 @@ function resolveConfigItems(configItems, entriesByCollection, primaryCollection,
 				result.push(...autoItems);
 			}
 		} else if ("items" in item) {
-			const children = resolveConfigItems(item.items, entriesByCollection, primaryCollection, currentPath);
+			const children = resolveConfigItems(item.items, entriesByCollection, primaryCollection, currentPath, 0, primaryPrefix);
 			const group = {
 				type: "group",
 				label: item.label,
@@ -332,11 +354,11 @@ function flattenLinks(items) {
 * current section's children in the rail) is applied by the public
 * `getSidebar` helper via `scopeToCurrentSection`.
 */
-function buildSidebarTree(entriesByCollection, primaryCollection, currentPath, config) {
+function buildSidebarTree(entriesByCollection, primaryCollection, currentPath, config, primaryPrefix = "") {
 	const primaryEntries = entriesByCollection[primaryCollection] ?? [];
 	let items;
-	if (config?.items && config.items.length > 0) items = resolveConfigItems(config.items, entriesByCollection, primaryCollection, currentPath);
-	else items = buildFilesystemTree(primaryEntries, currentPath);
+	if (config?.items && config.items.length > 0) items = resolveConfigItems(config.items, entriesByCollection, primaryCollection, currentPath, 0, primaryPrefix);
+	else items = buildFilesystemTree(primaryEntries, currentPath, void 0, primaryPrefix);
 	const pooledEntries = Object.values(entriesByCollection).flat();
 	items = processHideChildren(items, pooledEntries);
 	return items;
@@ -747,7 +769,7 @@ async function parseComponentsRegistry(filePath) {
 	if (!match) return null;
 	const body = match[1].replace(/\/\/[^\n]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
 	const names = [];
-	for (const raw of splitTopLevelCommas(body)) {
+	for (const raw of splitTopLevelCommas$1(body)) {
 		const entry = raw.trim();
 		if (!entry) continue;
 		if (entry.startsWith("...")) continue;
@@ -763,6 +785,130 @@ async function parseComponentsRegistry(filePath) {
 * `()`, or string literals). Required because object entries can themselves
 * contain commas (e.g. `Foo: bar({ a: 1, b: 2 })`).
 */
+function splitTopLevelCommas$1(input) {
+	const result = [];
+	let depth = 0;
+	let start = 0;
+	let inString = null;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i];
+		if (inString) {
+			if (ch === "\\") {
+				i++;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") inString = ch;
+		else if (ch === "{" || ch === "[" || ch === "(") depth++;
+		else if (ch === "}" || ch === "]" || ch === ")") depth--;
+		else if (ch === "," && depth === 0) {
+			result.push(input.slice(start, i));
+			start = i + 1;
+		}
+	}
+	result.push(input.slice(start));
+	return result;
+}
+
+//#endregion
+//#region src/_internal/parse-content-collections.ts
+/**
+* Extract registered collection names from the user's `src/content.config.ts`.
+*
+* Used by `getIndexedEntries()` and the agent-facing routes (`llms.txt`,
+* per-page `.md` alternates) so they don't have to hardcode `"docs"`.
+* Adding a new collection to `content.config.ts` lights up every
+* indexing surface automatically.
+*
+* Strategy: read the file as text and locate the `export const collections =
+* { ... }` declaration, parse its top-level keys. Same approach used by
+* `parse-components-registry.ts` — we never execute user code at build
+* time.
+*
+* Supported entry shapes inside the object literal:
+*   - shorthand:    `docs,`                         → "docs"
+*   - aliased:      `docs: defineCollection(...),`  → "docs" (the key)
+*   - string key:   `"docs": defineCollection(...)` → "docs"
+*
+* Skipped:
+*   - spread elements (`...other`)
+*   - computed keys (`[expr]: value`)
+*
+* The result is *not* filtered against reserved names here — that's
+* `getIndexedEntries()`'s job, so consumers that want the raw list (e.g.
+* tooling) can still see it.
+*
+* Returns:
+*   - `string[]` of registered names when the file exists and the
+*     pattern matches.
+*   - `null` when the file is missing OR present but doesn't expose a
+*     parseable `export const collections = { ... }`. Callers decide
+*     whether to warn or fall back to `["docs"]`.
+*/
+const EXPORT_PREFIX_PATTERN = /export\s+const\s+collections\s*(?::\s*[^=]+)?=\s*\{/;
+async function parseContentCollections(filePath) {
+	let source;
+	try {
+		source = await fs.readFile(filePath, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+	const stripped = source.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "));
+	const prefixMatch = stripped.match(EXPORT_PREFIX_PATTERN);
+	if (!prefixMatch || prefixMatch.index === void 0) return null;
+	const objectStart = prefixMatch.index + prefixMatch[0].length;
+	const objectEnd = findMatchingBrace(stripped, objectStart - 1);
+	if (objectEnd === -1) return null;
+	const body = stripped.slice(objectStart, objectEnd);
+	const names = [];
+	for (const raw of splitTopLevelCommas(body)) {
+		const entry = raw.trim();
+		if (!entry) continue;
+		if (entry.startsWith("...")) continue;
+		if (entry.startsWith("[")) continue;
+		const colonIdx = entry.indexOf(":");
+		const key = (colonIdx === -1 ? entry : entry.slice(0, colonIdx)).trim().replace(/^['"`]|['"`]$/g, "");
+		if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) names.push(key);
+	}
+	return names;
+}
+/**
+* Starting from an opening brace at `openIdx`, walk forward tracking brace
+* depth (and skipping string literals + nested brackets) and return the
+* index of the matching close brace. Returns `-1` if no match is found —
+* which only happens on a syntactically broken file.
+*/
+function findMatchingBrace(input, openIdx) {
+	if (input[openIdx] !== "{") return -1;
+	let depth = 0;
+	let inString = null;
+	for (let i = openIdx; i < input.length; i++) {
+		const ch = input[i];
+		if (inString) {
+			if (ch === "\\") {
+				i++;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") inString = ch;
+		else if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Split a string on commas that are at depth 0 (not inside `{}`, `[]`,
+* `()`, or string literals). Required because object entries can themselves
+* contain commas (e.g. `docs: defineCollection(docsCollection({ a: 1 }))`).
+*/
 function splitTopLevelCommas(input) {
 	const result = [];
 	let depth = 0;
@@ -789,6 +935,21 @@ function splitTopLevelCommas(input) {
 	result.push(input.slice(start));
 	return result;
 }
+/**
+* Collection names that should never appear in the agent-facing index,
+* regardless of how they were registered. The rule pair is intentionally
+* minimal so the convention is easy to remember:
+*
+*   - `partials` — Nimbus's built-in factory for `<Render slug=…/>`
+*     snippets. They're component content, not pages.
+*   - any name starting with `_` — author-chosen "loaded but internal"
+*     marker (e.g. `_drafts`, `_archive`, `_legacy`).
+*/
+const RESERVED_LITERAL = new Set(["partials"]);
+const RESERVED_PREFIX = "_";
+function filterIndexableCollections(names) {
+	return names.filter((name) => !RESERVED_LITERAL.has(name) && !name.startsWith(RESERVED_PREFIX));
+}
 
 //#endregion
 //#region src/_internal/code-transformers.ts
@@ -1126,7 +1287,42 @@ const featuresSchema = z.object({
 	toc: true
 });
 const searchSchema = z.union([z.literal(false), z.object({ provider: z.enum(["pagefind", "custom"]).default("pagefind") })]).optional();
-const sidebarSchema = z.object({ items: z.array(z.unknown()).optional() }).passthrough().optional();
+const sidebarSchema = z.object({
+	items: z.array(z.unknown()).optional(),
+	scope: z.enum(["full", "section"]).default("full")
+}).passthrough().optional();
+const versionSlugSchema = z.string({ error: "\"versions\" entries must be strings" }).min(1, { message: "Empty string is not a valid version slug" });
+const versionsSchema = z.object({
+	current: versionSlugSchema,
+	others: z.array(versionSlugSchema).default([]),
+	deprecated: z.array(versionSlugSchema).default([]),
+	hidden: z.array(versionSlugSchema).default([])
+}).superRefine((v, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	v.others.forEach((slug, i) => {
+		if (seen.has(slug)) ctx.addIssue({
+			code: "custom",
+			message: `Duplicate version slug "${slug}" in "others"`,
+			path: ["others", i]
+		});
+		seen.add(slug);
+	});
+	if (v.others.includes(v.current)) ctx.addIssue({
+		code: "custom",
+		message: `"current" (${JSON.stringify(v.current)}) must not also appear in "others". The current version lives in the primary \`docs\` collection; entries in "others" describe older versions stored in \`docs-<slug>\` collections.`,
+		path: ["current"]
+	});
+	for (const [i, slug] of v.deprecated.entries()) if (!v.others.includes(slug)) ctx.addIssue({
+		code: "custom",
+		message: `"deprecated" entry ${JSON.stringify(slug)} is not in "others". Every deprecated version must also be listed in "others".`,
+		path: ["deprecated", i]
+	});
+	for (const [i, slug] of v.hidden.entries()) if (!v.others.includes(slug)) ctx.addIssue({
+		code: "custom",
+		message: `"hidden" entry ${JSON.stringify(slug)} is not in "others". Every hidden version must also be listed in "others".`,
+		path: ["hidden", i]
+	});
+}).optional();
 const nimbusConfigSchema = z.object({
 	site: z.string().url({ message: "\"site\" must be a valid URL" }),
 	title: z.string(),
@@ -1142,7 +1338,8 @@ const nimbusConfigSchema = z.object({
 	head: z.array(headElementSchema).default([]),
 	sidebar: sidebarSchema,
 	features: featuresSchema,
-	search: searchSchema
+	search: searchSchema,
+	versions: versionsSchema
 });
 function validateNimbusConfig(input) {
 	const result = nimbusConfigSchema.safeParse(input);
@@ -1183,18 +1380,368 @@ function formatReceived(input, path) {
 //#region src/_internal/virtual-config.ts
 const VIRTUAL_ID = "virtual:nimbus/config";
 const RESOLVED_ID = `\0${VIRTUAL_ID}`;
-function virtualConfigPlugin(config) {
+function virtualConfigPlugin(config, extras) {
 	return {
 		name: "nimbus-docs:virtual-config",
 		resolveId(id) {
 			if (id === VIRTUAL_ID) return RESOLVED_ID;
 		},
 		load(id) {
-			if (id === RESOLVED_ID) return `export const config = ${JSON.stringify(config)};\n`;
+			if (id === RESOLVED_ID) return `export const config = ${JSON.stringify(config)};\nexport const indexedCollections = ${JSON.stringify(extras.indexedCollections)};\nexport const versionAlternates = ${JSON.stringify(extras.versionAlternates)};\n`;
 		}
 	};
 }
 
+//#endregion
+//#region src/_internal/scan-version-frontmatter.ts
+/**
+* Walk every version-collection directory and extract the frontmatter
+* fields the alternates table needs (`previousSlug`, `draft`).
+*
+* Runs at `astro:config:setup` — before Astro's content layer is
+* initialized, so we can't use `getCollection()`. Walks the filesystem
+* directly, slices the YAML frontmatter from each MDX/MD file, and
+* pulls the two fields we care about. Same "never execute user code"
+* posture as `parse-content-collections.ts` and `parse-components-registry.ts`.
+*
+* Returns one `VersionEntryInput` per visible entry across the
+* versioned-docs collections. Drafts (frontmatter `draft: true`) are
+* filtered. Consumers feed this into `buildVersionAlternates()`.
+*/
+const PRIMARY_COLLECTION$2 = "docs";
+const EXTENSIONS = new Set([".mdx", ".md"]);
+async function scanVersionFrontmatter(options) {
+	const { projectRoot, versions } = options;
+	const out = [];
+	const collectionsToScan = [{
+		collection: PRIMARY_COLLECTION$2,
+		dir: path.join(projectRoot, "src/content/docs")
+	}, ...versions.others.map((slug) => ({
+		collection: `docs-${slug}`,
+		dir: path.join(projectRoot, `src/content/docs-${slug}`)
+	}))];
+	for (const { collection, dir } of collectionsToScan) {
+		const files = await walk(dir);
+		for (const file of files) {
+			let source;
+			try {
+				source = await fs.readFile(file, "utf8");
+			} catch {
+				continue;
+			}
+			const front = extractFrontmatter(source);
+			if (front === null) continue;
+			if (parseBoolField(front, "draft") === true) continue;
+			const previousSlug = parsePreviousSlugField(front);
+			const id = idFromPath(dir, file);
+			out.push({
+				collection,
+				id,
+				previousSlug
+			});
+		}
+	}
+	return out;
+}
+async function walk(dir) {
+	const out = [];
+	async function visit(current) {
+		let entries;
+		try {
+			entries = await fs.readdir(current, { withFileTypes: true });
+		} catch (err) {
+			if (err.code === "ENOENT") return;
+			throw err;
+		}
+		for (const entry of entries) {
+			const full = path.join(current, entry.name);
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+				await visit(full);
+			} else if (entry.isFile()) {
+				const ext = path.extname(entry.name);
+				if (EXTENSIONS.has(ext)) out.push(full);
+			}
+		}
+	}
+	await visit(dir);
+	return out;
+}
+/**
+* Slice the YAML frontmatter block from a source file. Returns the body
+* between the leading `---` and the closing `---` (without the markers),
+* or `null` if no frontmatter is present.
+*
+* Matches the same convention Astro's content layer enforces — leading
+* `---\n`, closing `\n---\n` (or `\n---` at EOF).
+*/
+function extractFrontmatter(source) {
+	if (!source.startsWith("---")) return null;
+	const afterFirstMarker = source.indexOf("\n");
+	if (afterFirstMarker === -1) return null;
+	if (source.slice(0, afterFirstMarker).trim() !== "---") return null;
+	const rest = source.slice(afterFirstMarker + 1);
+	const closingMatch = rest.match(/(^|\n)---\s*(\n|$)/);
+	if (!closingMatch || closingMatch.index === void 0) return null;
+	const endIndex = closingMatch[1] === "\n" ? closingMatch.index : closingMatch.index;
+	return rest.slice(0, endIndex);
+}
+/**
+* Find a top-level boolean field in YAML frontmatter. Returns the
+* boolean value or `undefined` if the field is absent / malformed.
+*
+* Handles only the shape Nimbus uses: `<field>: true` / `<field>: false`
+* on a single line, no indentation, no quotes.
+*/
+function parseBoolField(yaml, field) {
+	const re = new RegExp(`^${escapeRe(field)}\\s*:\\s*(true|false)\\s*$`, "m");
+	const m = yaml.match(re);
+	if (!m) return void 0;
+	return m[1] === "true";
+}
+/**
+* Find the top-level `previousSlug` field in YAML frontmatter. Accepts:
+*   - scalar: `previousSlug: foo`
+*   - inline array: `previousSlug: [foo, "bar", 'baz']`
+*   - multiline block array:
+*       ```yaml
+*       previousSlug:
+*         - foo
+*         - bar
+*       ```
+*
+* Returns:
+*   - `string` for a scalar
+*   - `string[]` for either array form
+*   - `undefined` if absent
+*
+* The multiline form is the canonical YAML list syntax; the scanner
+* previously accepted only scalar and inline-array, which silently
+* dropped valid block lists at build time. The schema validates the
+* post-parse shape; the scanner has to match it.
+*/
+function parsePreviousSlugField(yaml) {
+	const blockHeader = yaml.match(/^previousSlug\s*:\s*$/m);
+	if (blockHeader && blockHeader.index !== void 0) return parseBlockList(yaml.slice(blockHeader.index + blockHeader[0].length + 1));
+	const arr = yaml.match(/^previousSlug\s*:\s*\[([^\]]*)\]\s*$/m);
+	if (arr) return arr[1].split(",").map((s) => unquote(s.trim())).filter((s) => s.length > 0);
+	const scalar = yaml.match(/^previousSlug\s*:\s*(?!\[)(.+?)\s*$/m);
+	if (scalar) {
+		const raw = scalar[1].trim();
+		if (raw.length === 0) return void 0;
+		return unquote(raw);
+	}
+}
+/**
+* Parse a YAML block list (one `- value` per line, leading indent).
+* Stops at the first non-list, non-blank line (i.e. the next sibling
+* frontmatter field at the same indentation as the list header).
+*
+*   previousSlug:
+*     - foo
+*     - "bar"
+*     - 'baz'
+*   title: Whatever            ← stops here
+*/
+function parseBlockList(source) {
+	const lines = source.split("\n");
+	const out = [];
+	for (const line of lines) {
+		if (line.trim().length === 0) continue;
+		const m = line.match(/^\s+-\s+(.+?)\s*$/);
+		if (!m) break;
+		const value = unquote(m[1].trim());
+		if (value.length > 0) out.push(value);
+	}
+	return out;
+}
+function unquote(s) {
+	if (s.startsWith("\"") && s.endsWith("\"") || s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1);
+	return s;
+}
+function escapeRe(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Compute the Astro entry id (the slug) from a file's absolute path,
+* relative to the collection directory.
+*
+* Examples:
+*   - <dir>/index.mdx           → "index"
+*   - <dir>/foo.mdx             → "foo"
+*   - <dir>/guides/setup.mdx    → "guides/setup"
+*/
+function idFromPath(collectionDir, filePath) {
+	return path.relative(collectionDir, filePath).replace(/\.(mdx|md)$/, "").split(path.sep).join("/");
+}
+
+//#endregion
+//#region src/_internal/version-alternates.ts
+const PRIMARY_COLLECTION$1 = "docs";
+/**
+* Build the alternates table for one site.
+*
+* Pass:
+*   - `versions`: resolved manifest (or null when the site is unversioned).
+*   - `entries`: every visible entry from every docs-shaped version
+*     collection. Drafts already filtered.
+*
+* Returns an empty table when `versions` is null or only one version is
+* configured (no cross-linking work to do).
+*/
+function buildVersionAlternates(versions, entries) {
+	if (!versions || versions.all.length < 2) return {};
+	const refs = [];
+	for (const entry of entries) {
+		const version = collectionToVersion(versions, entry.collection);
+		if (version === null) continue;
+		refs.push({
+			collection: entry.collection,
+			version,
+			slug: entry.id,
+			url: pageUrl(versions, version, entry.id)
+		});
+	}
+	const indexByKey = /* @__PURE__ */ new Map();
+	refs.forEach((ref, i) => indexByKey.set(refKey(ref), i));
+	const parent = refs.map((_, i) => i);
+	const find = (i) => {
+		let root = i;
+		while (parent[root] !== root) root = parent[root];
+		let cursor = i;
+		while (parent[cursor] !== cursor) {
+			const next = parent[cursor];
+			parent[cursor] = root;
+			cursor = next;
+		}
+		return root;
+	};
+	const union = (a, b) => {
+		const ra = find(a);
+		const rb = find(b);
+		if (ra !== rb) parent[ra] = rb;
+	};
+	const bySlug = /* @__PURE__ */ new Map();
+	for (let i = 0; i < refs.length; i++) {
+		const slug = refs[i].slug;
+		const bucket = bySlug.get(slug);
+		if (bucket) bucket.push(i);
+		else bySlug.set(slug, [i]);
+	}
+	for (const ids of bySlug.values()) for (let i = 1; i < ids.length; i++) union(ids[0], ids[i]);
+	const orderIndex = /* @__PURE__ */ new Map();
+	versions.all.forEach((v, i) => orderIndex.set(v, i));
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (!entry.previousSlug) continue;
+		const ref = refs[refs.findIndex((r) => r.collection === entry.collection && r.slug === entry.id)];
+		if (!ref) continue;
+		const selfOrder = orderIndex.get(ref.version);
+		if (selfOrder === void 0) continue;
+		const previousSlugs = Array.isArray(entry.previousSlug) ? entry.previousSlug : [entry.previousSlug];
+		for (const prevSlug of previousSlugs) for (let j = 0; j < refs.length; j++) {
+			const other = refs[j];
+			if (other.slug !== prevSlug) continue;
+			const otherOrder = orderIndex.get(other.version);
+			if (otherOrder === void 0) continue;
+			if (otherOrder <= selfOrder) continue;
+			const selfIdx = refs.indexOf(ref);
+			if (selfIdx >= 0) union(selfIdx, j);
+		}
+	}
+	const groups = /* @__PURE__ */ new Map();
+	for (let i = 0; i < refs.length; i++) {
+		const root = find(i);
+		const g = groups.get(root);
+		if (g) g.push(i);
+		else groups.set(root, [i]);
+	}
+	const table = {};
+	for (const memberIndices of groups.values()) {
+		memberIndices.sort((a, b) => {
+			return (orderIndex.get(refs[a].version) ?? Number.MAX_SAFE_INTEGER) - (orderIndex.get(refs[b].version) ?? Number.MAX_SAFE_INTEGER);
+		});
+		const members = memberIndices.map((i) => refs[i]);
+		const currentRef = members.find((m) => m.version === versions.current) ?? null;
+		const hiddenVersions = new Set(versions.hidden);
+		for (const self of members) {
+			const alternates = members.filter((m) => m !== self && !hiddenVersions.has(m.version));
+			const canonical = currentRef && currentRef !== self ? currentRef : null;
+			table[refKey(self)] = {
+				self,
+				alternates,
+				canonical
+			};
+		}
+	}
+	return table;
+}
+/**
+* Compute the slugs that exist in `current` but are absent in a given
+* older version — the set that should auto-redirect from `/v/<slug>` to
+* `/<slug>` when a reader follows a stale link. Includes slugs reached
+* via `previousSlug` (so a renamed page's old slug in the old version
+* also redirects correctly when the user types the original new URL by
+* accident under the old prefix).
+*
+* Returns a list of `{ from, to }` redirect pairs ready for Astro's
+* `redirects` config. `from` is the URL the reader hit; `to` is the
+* current-version sibling. Both are absolute paths, leading slash, no
+* trailing slash. Astro applies trailing-slash normalisation on output.
+*/
+function computeMissingPageRedirects(versions, table, entries) {
+	if (!versions || versions.all.length < 2) return [];
+	const existing = /* @__PURE__ */ new Set();
+	for (const entry of entries) {
+		const version = collectionToVersion(versions, entry.collection);
+		if (version === null) continue;
+		existing.add(`${version}:${entry.id}`);
+	}
+	const redirects = [];
+	for (const entry of entries) {
+		const version = collectionToVersion(versions, entry.collection);
+		if (version !== versions.current) continue;
+		const currentUrl = pageUrl(versions, version, entry.id);
+		for (const oldVersion of versions.others) {
+			if (existing.has(`${oldVersion}:${entry.id}`)) continue;
+			if (table[refKey({
+				collection: entry.collection,
+				version,
+				slug: entry.id,
+				url: currentUrl
+			})]?.alternates.some((a) => a.version === oldVersion)) continue;
+			redirects.push({
+				from: pageUrl(versions, oldVersion, entry.id),
+				to: currentUrl
+			});
+		}
+	}
+	return redirects;
+}
+function refKey(ref) {
+	return `${ref.collection}:${ref.slug}`;
+}
+/**
+* Resolve the version slug for a given Astro collection ID, or null if
+* the collection is not part of the versioning manifest.
+*/
+function collectionToVersion(versions, collection) {
+	if (collection === PRIMARY_COLLECTION$1) return versions.current;
+	if (!collection.startsWith("docs-")) return null;
+	const slug = collection.slice(5);
+	return versions.all.includes(slug) ? slug : null;
+}
+/**
+* Build the URL for a `(version, slug)` pair. Matches the convention in
+* `index.ts::resolveCollectionPrefix`:
+*   - current version → root (`/foo`)
+*   - others → `/<version>/<slug>`
+*/
+function pageUrl(versions, version, slug) {
+	if (version === versions.current) return `/${slug}`;
+	return `/${version}/${slug}`;
+}
+
 //#endregion
 //#region src/integration.ts
 /**
@@ -1253,6 +1800,37 @@ function nimbus(rawConfig, options = {}) {
 						logger.info(`MDX validation passed — ${globals.length} global component${globals.length === 1 ? "" : "s"} registered, ${contentDirs.length} content dir${contentDirs.length === 1 ? "" : "s"} scanned.`);
 					}
 				}
+				const projectRoot = fileURLToPath(astroConfig.root);
+				const rawCollections = await parseContentCollections(path.join(projectRoot, "src/content.config.ts"));
+				const indexedCollections = rawCollections === null ? ["docs"] : filterIndexableCollections(rawCollections);
+				if (rawCollections === null) logger.warn("nimbus-docs: `src/content.config.ts` is missing or doesn't expose a parseable `export const collections = { ... }`. Falling back to indexing the `docs` collection only.");
+				if (config.versions && rawCollections !== null) {
+					const registered = new Set(rawCollections);
+					const missing = config.versions.others.filter((slug) => !registered.has(`docs-${slug}`));
+					if (missing.length > 0) {
+						const lines = missing.map((slug) => {
+							return `  - "${slug}" → expected a collection named "docs-${slug}" in src/content.config.ts (e.g. \`"docs-${slug}": docsCollection({ base: "docs-${slug}" })\`)`;
+						});
+						throw new Error(`nimbus-docs: \`versions.others\` references slugs without matching collections:\n${lines.join("\n")}\n\nEvery entry in \`versions.others\` must correspond to a registered Astro content collection. Register the collection(s) above in src/content.config.ts and try again.`);
+					}
+				}
+				let versionAlternates = {};
+				let versionRedirects = [];
+				if (config.versions) {
+					const resolved = {
+						current: config.versions.current,
+						others: config.versions.others ?? [],
+						deprecated: config.versions.deprecated ?? [],
+						hidden: config.versions.hidden ?? [],
+						all: [config.versions.current, ...config.versions.others ?? []]
+					};
+					const versionEntries = await scanVersionFrontmatter({
+						projectRoot,
+						versions: resolved
+					});
+					versionAlternates = buildVersionAlternates(resolved, versionEntries);
+					versionRedirects = computeMissingPageRedirects(resolved, versionAlternates, versionEntries);
+				}
 				integrationsToAdd.push(mdx(options.mdx ?? {}));
 				if (options.sitemap !== false && Boolean(config.site)) integrationsToAdd.push(sitemap());
 				updateConfig({
@@ -1269,7 +1847,11 @@ function nimbus(rawConfig, options = {}) {
 							transformers: defaultCodeTransformers()
 						}
 					},
-					vite: { plugins: [virtualConfigPlugin(config)] }
+					...versionRedirects.length > 0 ? { redirects: Object.fromEntries(versionRedirects.map(({ from, to }) => [from, to])) } : {},
+					vite: { plugins: [virtualConfigPlugin(config, {
+						indexedCollections,
+						versionAlternates
+					})] }
 				});
 			},
 			"astro:config:done": ({ injectTypes }) => {
@@ -1277,8 +1859,12 @@ function nimbus(rawConfig, options = {}) {
 					filename: "virtual-config.d.ts",
 					content: [
 						"declare module \"virtual:nimbus/config\" {",
-						"  import type { NimbusConfig } from \"nimbus-docs/types\";",
+						"  import type { NimbusConfig, VersionAlternatesTable } from \"nimbus-docs/types\";",
 						"  export const config: NimbusConfig;",
+						"  /** Build-time list of indexable collection names. See `getIndexedEntries()`. */",
+						"  export const indexedCollections: readonly string[];",
+						"  /** Build-time cross-version alternates table. See `getVersionAlternates()`. */",
+						"  export const versionAlternates: VersionAlternatesTable;",
 						"}",
 						""
 					].join("\n")
@@ -1325,6 +1911,152 @@ function defineConfig(config) {
 	return config;
 }
 /**
+* Cross-collection entry list for the agent-facing routes
+* (`llms.txt`, per-page `.md` alternates, future `llms-full.txt` and
+* `rag.jsonl`). Implements the indexing baseline of the two-layer
+* architecture documented at `/features/llms-txt`:
+*
+*   - **Multi-collection by default, zero opt-in.** Iterates every
+*     collection registered in `src/content.config.ts` except names
+*     matching `partials` or starting with `_` (reserved).
+*   - **Schema-tolerant.** Reads `title` and `description` if present;
+*     falls back to the entry id for the title and omits the
+*     description otherwise.
+*   - **Per-page filters baked in.** Drops entries with `llms: false`
+*     or `draft: true` when those fields exist; absent fields read as
+*     the docs-schema defaults (`llms: true`, `draft: false`).
+*
+* The returned shape is identical regardless of which factory created
+* the collection: hand-rolled `defineCollection({ loader, schema })`
+* collections work without modification.
+*/
+/**
+* Resolve the URL-prefix segment for a given collection ID.
+*
+* Rules, in order:
+*   1. Primary `docs` collection mounts at root → returns `""`.
+*   2. When `versions` is configured, a `docs-<slug>` collection whose
+*      slug appears in `versions.others` mounts under `/<slug>/` (not
+*      `/docs-<slug>/`). This is the versioning URL convention — a
+*      version is reached by its short label, not its collection ID.
+*   3. Any other collection (`api`, `blog`, …) mounts at `/<collection>/`
+*      — the default multi-collection convention.
+*
+* Returned shape: empty string OR `/<segment>` with leading slash, no
+* trailing slash. Callers append `/<entryId>` or `/index.md`.
+*/
+function resolveCollectionPrefix(versions, collection) {
+	if (collection === PRIMARY_COLLECTION) return "";
+	if (versions && collection.startsWith("docs-")) {
+		const slug = collection.slice(5);
+		if (versions.others.includes(slug)) return `/${slug}`;
+	}
+	return `/${collection}`;
+}
+/**
+* Resolve the URL-safe slug a collection should be referenced by — the
+* label that appears in URLs and section headers. For version
+* collections this is the manifest's short slug; for everything else
+* it's the collection ID.
+*/
+function resolveCollectionSlug(versions, collection) {
+	if (collection === PRIMARY_COLLECTION) return collection;
+	if (versions && collection.startsWith("docs-")) {
+		const slug = collection.slice(5);
+		if (versions.others.includes(slug)) return slug;
+	}
+	return collection;
+}
+async function getIndexedEntries() {
+	const { getCollection } = await import("astro:content");
+	const collectionNames = await loadIndexedCollections();
+	const names = collectionNames.length > 0 ? collectionNames : [PRIMARY_COLLECTION];
+	const versions = await getVersions();
+	const indexed = [];
+	for (const name of names) {
+		let entries;
+		try {
+			entries = await getCollection(name);
+		} catch {
+			continue;
+		}
+		const prefix = resolveCollectionPrefix(versions, name);
+		for (const entry of entries) {
+			const data = entry.data ?? {};
+			if (data.llms === false) continue;
+			if (data.draft === true) continue;
+			const title = typeof data.title === "string" && data.title.length > 0 ? data.title : entry.id;
+			const rawDescription = data.description;
+			const description = typeof rawDescription === "string" && rawDescription.length > 0 ? rawDescription : void 0;
+			indexed.push({
+				entry,
+				collection: name,
+				title,
+				description,
+				url: `${prefix}/${entry.id}`
+			});
+		}
+	}
+	return indexed;
+}
+/**
+* Partition the indexed entries into the shape the root `/llms.txt`
+* and `/[section]/llms.txt` routes need.
+*
+* Convention:
+*   - Primary `"docs"` entries follow the leaf/group rule based on
+*     their `entry.id` top segment (matches single-collection behavior).
+*   - Every other collection becomes a single top-level group named
+*     after the collection, regardless of how many entries it has.
+*     This matches the URL convention (`/api/...`, `/blog/...`).
+*/
+async function getIndexedTopLevel() {
+	const items = await getIndexedEntries();
+	const versions = await getVersions();
+	const primaryBuckets = /* @__PURE__ */ new Map();
+	const secondaryBuckets = /* @__PURE__ */ new Map();
+	const versionSlugs = new Set(versions?.others ?? []);
+	const hiddenSlugs = new Set(versions?.hidden ?? []);
+	for (const item of items) if (item.collection === PRIMARY_COLLECTION) {
+		const top = item.entry.id.split("/")[0];
+		const bucket = primaryBuckets.get(top);
+		if (bucket) bucket.push(item);
+		else primaryBuckets.set(top, [item]);
+	} else {
+		const slug = resolveCollectionSlug(versions, item.collection);
+		const bucket = secondaryBuckets.get(slug);
+		if (bucket) bucket.push(item);
+		else secondaryBuckets.set(slug, [item]);
+	}
+	const leaves = [];
+	const groups = [];
+	for (const [slug, members] of primaryBuckets) if (members.length === 1 && members[0].entry.id === slug) leaves.push(members[0]);
+	else groups.push({
+		slug,
+		label: slug,
+		members,
+		kind: "primary",
+		hidden: false
+	});
+	for (const [slug, members] of secondaryBuckets) {
+		const kind = versionSlugs.has(slug) ? "version" : "secondary";
+		groups.push({
+			slug,
+			label: slug,
+			members,
+			kind,
+			hidden: hiddenSlugs.has(slug)
+		});
+	}
+	leaves.sort((a, b) => a.url.localeCompare(b.url));
+	groups.sort((a, b) => a.slug.localeCompare(b.slug));
+	for (const g of groups) g.members.sort((a, b) => a.url.localeCompare(b.url));
+	return {
+		leaves,
+		groups
+	};
+}
+/**
 * Build the sidebar tree for the given current path, scoped to the
 * top-level section containing that page.
 *
@@ -1332,16 +2064,30 @@ function defineConfig(config) {
 * resolves config-driven sidebar. Otherwise auto-generates from filesystem
 * (i.e. the `docs` collection's entry IDs).
 *
-* The returned tree is always scoped: only the current section's children
-* are returned. To enumerate every top-level section (for header tabs or
-* a section switcher), use `getSidebarSections`.
+* Returned shape depends on `sidebar.scope` in `nimbus.config.ts`:
+*   - `"full"` (default) — every top-level item on every page.
+*   - `"section"` — only the current top-level section's children. Use
+*     the header section-tab strip (via `getSidebarSections`) for
+*     cross-section nav when this mode is on.
+*
+* **Versioning awareness.** When the page is in a version collection
+* (`docs-<v>` where `<v>` is in `versions.others`), pass `collection` as
+* the second argument. The sidebar build will swap any
+* `{ autogenerate: { collection: "docs" } }` items to autogenerate from
+* that version's collection instead, and treat it as the primary for
+* the build. Without this, version pages render the current-version
+* sidebar and prev/next derives from the wrong tree.
 *
 * @param currentSlug - The current page's URL path (e.g. "/getting-started").
 *                     Used to set `isCurrent` on matching links and to pick
-*                     which top-level section to surface.
+*                     which top-level section to surface when scoping.
+* @param options.collection - The current page's Astro collection ID.
+*                     Pass `entry.collection` from your route.
 */
-async function getSidebar(currentSlug) {
-	return scopeToCurrentSection(await buildFullSidebarTree(currentSlug), currentSlug);
+async function getSidebar(currentSlug, options) {
+	const config = await loadNimbusConfig();
+	const tree = await buildFullSidebarTree(currentSlug, options?.collection);
+	return config.sidebar?.scope === "section" ? scopeToCurrentSection(tree, currentSlug) : tree;
 }
 /**
 * Derive one section per top-level group in the sidebar — used by
@@ -1350,17 +2096,66 @@ async function getSidebar(currentSlug) {
 *
 * Reads the un-scoped tree so every section is visible, then collapses
 * each top-level group to `{ label, href, isActive }`.
+*
+* Accepts the same `collection` option as `getSidebar` so version pages
+* see version-scoped section tabs.
 */
-async function getSidebarSections(currentSlug) {
-	return deriveSidebarSections(await buildFullSidebarTree(currentSlug));
+async function getSidebarSections(currentSlug, options) {
+	return deriveSidebarSections(await buildFullSidebarTree(currentSlug, options?.collection));
 }
 /**
 * Internal: build the un-scoped sidebar tree. Shared by `getSidebar` and
 * `getSidebarSections`.
+*
+* When `pageCollection` names a registered version collection
+* (`docs-<v>` with `<v>` in `versions.others`), the sidebar treats that
+* collection as the primary for this build: autogen items referencing
+* `docs` are rewritten to reference the version collection, and the
+* `primary` argument to `buildSidebarTree` is set accordingly. The net
+* effect: version pages get the right sidebar tree and the right
+* prev/next ordering.
 */
-async function buildFullSidebarTree(currentSlug) {
+async function buildFullSidebarTree(currentSlug, pageCollection) {
 	const runtimeConfig = await loadNimbusConfig();
-	return buildSidebarTree(await getVisibleEntriesByCollection([PRIMARY_COLLECTION, ...collectSidebarCollectionRefs(runtimeConfig.sidebar?.items).filter((c) => c !== PRIMARY_COLLECTION)]), PRIMARY_COLLECTION, currentSlug, runtimeConfig.sidebar);
+	const versions = await getVersions();
+	let effectivePrimary = PRIMARY_COLLECTION;
+	let primaryPrefix = "";
+	if (versions && pageCollection && pageCollection.startsWith("docs-") && versions.others.includes(pageCollection.slice(5))) {
+		effectivePrimary = pageCollection;
+		primaryPrefix = resolveCollectionPrefix(versions, pageCollection);
+	}
+	const rewrittenItems = effectivePrimary !== PRIMARY_COLLECTION ? rewriteSidebarItemsForVersion(runtimeConfig.sidebar?.items, effectivePrimary) : runtimeConfig.sidebar?.items;
+	const referenced = collectSidebarCollectionRefs(rewrittenItems);
+	return buildSidebarTree(await getVisibleEntriesByCollection([effectivePrimary, ...referenced.filter((c) => c !== effectivePrimary)]), effectivePrimary, currentSlug, runtimeConfig.sidebar ? {
+		...runtimeConfig.sidebar,
+		items: rewrittenItems
+	} : void 0, primaryPrefix);
+}
+/**
+* Substitute the primary collection (`docs`) for `effectivePrimary`
+* inside any sidebar item that autogenerates from a named collection.
+* Used by `buildFullSidebarTree` to make version pages render their
+* own collection's sidebar instead of the current version's.
+*/
+function rewriteSidebarItemsForVersion(items, effectivePrimary) {
+	if (!items) return items;
+	return items.map((item) => {
+		if (!item || typeof item !== "object") return item;
+		const o = item;
+		const autogen = o.autogenerate;
+		if (autogen && autogen.collection === PRIMARY_COLLECTION) return {
+			...o,
+			autogenerate: {
+				...autogen,
+				collection: effectivePrimary
+			}
+		};
+		if (Array.isArray(o.items)) return {
+			...o,
+			items: rewriteSidebarItemsForVersion(o.items, effectivePrimary)
+		};
+		return item;
+	});
 }
 /**
 * Resolve prev/next links for the current page.
@@ -1474,7 +2269,261 @@ async function getDocsPageProps(astro) {
 		headings
 	};
 }
+/**
+* `getStaticPaths` implementation for a catch-all route over a non-primary
+* collection (`api`, `blog`, …). Companion to `getDocsStaticPaths`.
+*
+* Returns one path per visible entry in the named collection. Drafts are
+* filtered in production (same rule as `getDocsStaticPaths`). Each path
+* passes `{ entry }` as props for `getCollectionPageProps()`.
+*
+* Usage:
+*
+*   // src/pages/api/[...slug].astro
+*   export const prerender = true;
+*   export const getStaticPaths = getCollectionStaticPaths("api");
+*
+* Why a sibling helper instead of an option on `getDocsStaticPaths`: the
+* `Docs` name carries the "primary collection mounted at root" semantic.
+* Non-primary collections mount under their own URL namespace
+* (`/<collection>/...`) by convention; the helper name reflects that.
+*/
+function getCollectionStaticPaths(collection) {
+	return async () => {
+		return (await getVisibleEntries([collection])).map((entry) => ({
+			params: { slug: entry.id },
+			props: { entry }
+		}));
+	};
+}
+/**
+* Read the current entry from `Astro.props`, render it, and return the
+* pieces a docs-style page needs — typed for an arbitrary collection.
+*
+* Companion to `getCollectionStaticPaths`. Use this in routes mounted at
+* non-primary collections (`api`, `blog`, …) instead of `getDocsPageProps`,
+* which is typed to the `docs` collection.
+*
+* Pass the collection name as a type parameter for the entry's data
+* shape to narrow correctly:
+*
+*   const { entry, Content, headings } = await getCollectionPageProps<"api">(Astro);
+*/
+async function getCollectionPageProps(astro) {
+	const entry = astro.props.entry;
+	if (!entry) throw new Error("getCollectionPageProps(): expected `entry` in Astro.props. Ensure your route uses `getStaticPaths = getCollectionStaticPaths(<collection>)`.");
+	const { render } = await import("astro:content");
+	const { Content, headings } = await render(entry);
+	return {
+		entry,
+		Content,
+		headings
+	};
+}
+/**
+* Return the resolved versioning manifest for the current site, or `null`
+* if the site is unversioned (`nimbus.config.ts` has no `versions` block).
+*
+* Optional fields are normalised to empty arrays (`deprecated`, `hidden`)
+* and `all` is `[current, ...others]` in manifest order — convenient for
+* picker enumeration or anywhere you need every known version slug.
+*
+* Usage:
+*
+*   const versions = await getVersions();
+*   if (versions) {
+*     for (const slug of versions.all) {
+*       // …enumerate
+*     }
+*   }
+*
+* Reads from `virtual:nimbus/config`, so the cost is one cached dynamic
+* import per build.
+*/
+async function getVersions() {
+	const v = (await loadNimbusConfig()).versions;
+	if (!v) return null;
+	const others = v.others ?? [];
+	return {
+		current: v.current,
+		others,
+		deprecated: v.deprecated ?? [],
+		hidden: v.hidden ?? [],
+		all: [v.current, ...others]
+	};
+}
+/**
+* Return the version slug a given Astro content collection ID belongs to,
+* or `null` if the collection is not a version of the primary docs.
+*
+* Rules:
+*   - `"docs"` → `versions.current` (the current version's label).
+*   - `"docs-<slug>"` where `<slug>` appears in `versions.current` or
+*     `versions.others` → `<slug>`.
+*   - Anything else (e.g. `"blog"`, `"api"`, `"docs-archive"` when
+*     `archive` isn't in the manifest) → `null`.
+*
+* Returns `null` whenever the site has no `versions` config at all,
+* regardless of collection ID.
+*
+* Usage in a route:
+*
+*   const { entry } = Astro.props;
+*   const version = await getCurrentVersion(entry.collection);
+*   // version === "v3" for entries in `docs`, "v2" for entries in `docs-v2`, …
+*/
+async function getCurrentVersion(collectionId) {
+	const versions = await getVersions();
+	if (!versions) return null;
+	if (collectionId === PRIMARY_COLLECTION) return versions.current;
+	if (!collectionId.startsWith("docs-")) return null;
+	const suffix = collectionId.slice(5);
+	return versions.all.includes(suffix) ? suffix : null;
+}
+/**
+* Look up the cross-version alternates for a given Astro entry.
+*
+* Returns `null` when the entry is not part of a versioning manifest
+* (unversioned site, non-`docs` collection like `blog`/`api`, or the
+* lookup misses for any other reason). Otherwise returns a record with:
+*
+*   - `self`: the entry being looked up, expressed as a `VersionPageRef`.
+*   - `alternates`: every other version's sibling page for the same
+*     logical content (same slug or linked via `previousSlug`). Sorted
+*     in manifest version order.
+*   - `canonical`: the current-version sibling when one exists and
+*     isn't `self`. `null` when `self` is already the current version
+*     or no current-version sibling exists.
+*
+* Routes inject `<link rel="alternate">` for every entry in
+* `alternates`, and `<link rel="canonical">` pointing at `canonical.url`
+* when canonical is non-null.
+*
+* Usage in a route:
+*
+*   const { entry } = Astro.props;
+*   const alts = await getVersionAlternates(entry.collection, entry.id);
+*
+*   {alts?.alternates.map((a) => (
+*     <link rel="alternate" data-version={a.version} href={a.url} />
+*   ))}
+*   {alts?.canonical && <link rel="canonical" href={alts.canonical.url} />}
+*/
+async function getVersionAlternates(collectionId, entryId) {
+	return (await loadVersionAlternates())[`${collectionId}:${entryId}`] ?? null;
+}
+/**
+* Convenience wrapper: returns just the canonical URL for an entry, or
+* `null` when none applies. Equivalent to
+* `(await getVersionAlternates(c, e))?.canonical?.url ?? null` — handy
+* when a route only needs the canonical and not the full alternates list.
+*/
+async function getCanonicalUrl(collectionId, entryId) {
+	return (await getVersionAlternates(collectionId, entryId))?.canonical?.url ?? null;
+}
+/**
+* Return the agent index URL path (the `/llms.txt` route) that
+* corresponds to a given Astro collection. The path is mount-point
+* aware: pages in version collections point at the per-version index,
+* pages in non-primary collections point at their per-collection index,
+* and the primary `docs` collection points at the root.
+*
+*   - `"docs"`        → `"/llms.txt"`
+*   - `"docs-v1"`     → `"/v1/llms.txt"`     (when `v1` is in `versions.others`)
+*   - `"blog"`        → `"/blog/llms.txt"`
+*   - `"api"`         → `"/api/llms.txt"`
+*   - `"docs-archive"` (unrecognised version slug) → `"/docs-archive/llms.txt"`
+*
+* Returns a path with a leading slash and no trailing slash. Routes
+* resolve it against `Astro.site` to produce a full URL.
+*
+* Used by `BaseLayout` and `AgentDirective` to surface the correct
+* agent index hint on every page — readers landing on `/v1/foo` get
+* pointed at `/v1/llms.txt`, not `/llms.txt`, so agents don't crawl
+* the wrong section.
+*/
+async function getCollectionLlmsUrl(collectionId) {
+	if (collectionId === PRIMARY_COLLECTION) return "/llms.txt";
+	const versions = await getVersions();
+	if (versions && collectionId.startsWith("docs-")) {
+		const slug = collectionId.slice(5);
+		if (versions.others.includes(slug)) {
+			if (versions.hidden.includes(slug)) return "/llms.txt";
+			return `/${slug}/llms.txt`;
+		}
+	}
+	return `/${collectionId}/llms.txt`;
+}
+/**
+* Look up the versioning status for a page's collection — what the
+* layout needs to decide whether to render the deprecation banner,
+* apply the Pagefind facet filters, or exclude the page from search
+* entirely.
+*
+* Returns `null` when the site is unversioned or the page is not part
+* of a version collection (regular `docs`, `blog`, `api`, …). Layouts
+* treat that as "no versioning UI to apply" — render normally.
+*
+* Usage:
+*
+*   const status = await getVersionStatus(entry.collection);
+*   if (status?.isDeprecated) {
+*     // render the deprecation banner
+*   }
+*/
+/**
+* Resolve a URL that's guaranteed to exist within a given version's
+* collection. Used by the picker (and any other "jump to that version"
+* surface) to avoid landing readers on a 404 when the current page has
+* no same-logical-page sibling in the target version.
+*
+* Resolution order:
+*   1. If `docs-<v>/index` exists, return its URL (the conventional
+*      "version landing page").
+*   2. If `docs-<v>/overview` exists, return its URL (common alternate
+*      name for a landing page).
+*   3. Otherwise return the first indexed entry's URL in that version,
+*      sorted by URL — matches `getIndexedTopLevel()`'s sort so the
+*      choice is deterministic across builds.
+*   4. If the version has no indexed entries at all, return `null`.
+*      Callers should treat that as "this version has nothing to link
+*      to" and either omit the picker entry or fall back to the
+*      version's URL prefix root (which may still 404, but that's the
+*      authoring problem to fix, not the picker's).
+*
+* `version` is the manifest slug (e.g. `"v0"`), NOT the collection ID
+* (`"docs-v0"`). For the current version, returns `"/"` when at least
+* one current-version entry exists, else `null`.
+*
+* Reads from `getIndexedEntries()`, so the cost is one cached lookup
+* per build (the indexed list is computed once per page render).
+*/
+async function getVersionLandingUrl(version) {
+	const versions = await getVersions();
+	if (!versions) return null;
+	if (!versions.all.includes(version)) return null;
+	const targetCollection = version === versions.current ? PRIMARY_COLLECTION : `docs-${version}`;
+	const inVersion = (await getIndexedEntries()).filter((i) => i.collection === targetCollection);
+	if (inVersion.length === 0) return null;
+	const byId = new Map(inVersion.map((i) => [i.entry.id, i]));
+	const preferred = byId.get("index") ?? byId.get("overview");
+	if (preferred) return preferred.url;
+	inVersion.sort((a, b) => a.url.localeCompare(b.url));
+	return inVersion[0].url;
+}
+async function getVersionStatus(collectionId) {
+	const versions = await getVersions();
+	if (!versions) return null;
+	const version = await getCurrentVersion(collectionId);
+	if (version === null) return null;
+	return {
+		version,
+		isCurrent: version === versions.current,
+		isDeprecated: versions.deprecated.includes(version),
+		isHidden: versions.hidden.includes(version)
+	};
+}
 
 //#endregion
-export { nimbus as default, defaultCodeTransformers, defineConfig, getBreadcrumbs, getDocsPageProps, getDocsStaticPaths, getEditUrl, getLastUpdated, getPrevNext, getSidebar, getSidebarSections, getTOC, getVisibleEntries, renderEntryAsMarkdown, sidebarHash };
+export { nimbus as default, defaultCodeTransformers, defineConfig, getBreadcrumbs, getCanonicalUrl, getCollectionLlmsUrl, getCollectionPageProps, getCollectionStaticPaths, getCurrentVersion, getDocsPageProps, getDocsStaticPaths, getEditUrl, getIndexedEntries, getIndexedTopLevel, getLastUpdated, getPrevNext, getSidebar, getSidebarSections, getTOC, getVersionAlternates, getVersionLandingUrl, getVersionStatus, getVersions, getVisibleEntries, renderEntryAsMarkdown, sidebarHash };
 //# sourceMappingURL=index.js.map