@clarify-labs/cli 0.11.18 → 0.11.20

package/output/{engine-DeA6EGHW.js → engine-BgfGFPKK.js}

@@ -3,16 +3,13 @@ import mdxPlugin from "@mdx-js/rollup";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import rehypeRaw from "rehype-raw";
-import { compile } from "@mdx-js/mdx";
+import { compile, createProcessor } from "@mdx-js/mdx";
+import GithubSlugger, { slug } from "github-slugger";
+import { markdownRemarkPlugins, parseCodeMeta, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
 import rehypeShiki from "@shikijs/rehype";
-import rehypeSlug from "rehype-slug";
 import { createCssVariablesTheme } from "shiki";
 import { visit } from "unist-util-visit";
-import { markdownRemarkPlugins, parseCodeMeta, themeBootstrapScript, themePresets } from "@clarify-labs/renderer";
 import { readFile, readdir, stat } from "node:fs/promises";
-import GithubSlugger, { slug } from "github-slugger";
-import { toString } from "mdast-util-to-string";
-import { remark } from "remark";
 import matter from "gray-matter";
 import { spawnSync } from "node:child_process";
 import { createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
@@ -45,6 +42,402 @@ function createContentDiagnostic(options) {
 	};
 }
 //#endregion
+//#region source/parsers/markdown/headings.ts
+var HEADING_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var INTERNAL_HEADING_ID_PREFIX = "clarify-internal-heading-id:";
+var EXPLICIT_ID_PATTERN = /\s+\{#([^{}]*)\}$/;
+var HEADING_REMARK_PLUGINS = markdownRemarkPlugins;
+function visitHeadings(node, callback) {
+	if (node.type === "heading") callback(node);
+	for (const child of node.children ?? []) visitHeadings(child, callback);
+}
+function visitHtml(node, callback) {
+	if (node.type === "html") callback(node);
+	for (const child of node.children ?? []) visitHtml(child, callback);
+}
+function visitMdxIntrinsicHeadings(node, callback) {
+	if ((node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") && node.name && /^h[1-6]$/.test(node.name)) callback(node);
+	for (const child of node.children ?? []) visitMdxIntrinsicHeadings(child, callback);
+}
+function visitHastHeadings(node, callback) {
+	if (node.type === "element" && node.tagName && /^h[1-6]$/.test(node.tagName)) callback(node);
+	for (const child of node.children ?? []) visitHastHeadings(child, callback);
+}
+function hastText$1(node) {
+	if (node.type === "text") return node.value ?? "";
+	return (node.children ?? []).map(hastText$1).join("");
+}
+function applySourceEdits(content, edits) {
+	return edits.sort((left, right) => right.start - left.start).reduce((result, edit) => result.slice(0, edit.start) + edit.replacement + result.slice(edit.end), content);
+}
+function headingPosition(node, lineOffset) {
+	return {
+		line: (node.position?.start.line ?? 1) + lineOffset,
+		column: node.position?.start.column ?? 1
+	};
+}
+function formatPosition(position) {
+	return `${position.line}:${position.column}`;
+}
+function finalTextNode(heading) {
+	const node = heading.children?.at(-1);
+	return node?.type === "text" && typeof node.value === "string" ? node : void 0;
+}
+function contentEndOffset(heading) {
+	return (heading.children?.at(-1))?.position?.end.offset ?? heading.position?.end.offset;
+}
+function explicitIdInfo(heading, content) {
+	const text = finalTextNode(heading);
+	if (!text?.position) return void 0;
+	const startOffset = text.position.start.offset;
+	const endOffset = text.position.end.offset;
+	if (startOffset === void 0 || endOffset === void 0) return void 0;
+	const match = content.slice(startOffset, endOffset).match(EXPLICIT_ID_PATTERN);
+	if (!match || match.index === void 0) return void 0;
+	return {
+		id: match[1] ?? "",
+		start: startOffset + match.index,
+		end: startOffset + match.index + match[0].length
+	};
+}
+function maskExplicitHeadingMarkers(content) {
+	const tree = createProcessor({
+		format: "md",
+		remarkPlugins: HEADING_REMARK_PLUGINS
+	}).parse(content);
+	const edits = [];
+	visitHeadings(tree, (heading) => {
+		const marker = explicitIdInfo(heading, content);
+		if (marker) edits.push({
+			start: marker.start,
+			end: marker.end,
+			replacement: "x".repeat(marker.end - marker.start)
+		});
+	});
+	return applySourceEdits(content, edits);
+}
+function parseHeadingTree(content, kind) {
+	if (kind === "markdown") return createProcessor({
+		format: "md",
+		remarkPlugins: HEADING_REMARK_PLUGINS
+	}).parse(content);
+	const maskedContent = maskExplicitHeadingMarkers(content);
+	try {
+		return createProcessor({
+			format: "mdx",
+			remarkPlugins: HEADING_REMARK_PLUGINS
+		}).parse(maskedContent);
+	} catch {
+		return;
+	}
+}
+function renderedMarkdownHeadingTitles(tree, content, kind) {
+	const originalText = /* @__PURE__ */ new Map();
+	visitHeadings(tree, (heading) => {
+		const marker = explicitIdInfo(heading, content);
+		const text = finalTextNode(heading);
+		if (!marker || !text || text.value === void 0) return;
+		originalText.set(text, text.value);
+		text.value = text.value.slice(0, -(marker.end - marker.start)).replace(/\s+$/, "");
+	});
+	try {
+		let hast;
+		const captureHast = () => (tree) => {
+			hast = tree;
+		};
+		createProcessor({
+			format: kind === "markdown" ? "md" : "mdx",
+			remarkPlugins: HEADING_REMARK_PLUGINS,
+			...kind === "markdown" ? { remarkRehypeOptions: { allowDangerousHtml: true } } : {},
+			rehypePlugins: kind === "markdown" ? [rehypeRaw, captureHast] : [captureHast]
+		}).runSync(tree, { value: content });
+		const titles = /* @__PURE__ */ new Map();
+		if (!hast) return titles;
+		visitHastHeadings(hast, (heading) => {
+			const offset = heading.position?.start.offset;
+			if (offset !== void 0) titles.set(offset, hastText$1(heading));
+		});
+		return titles;
+	} finally {
+		for (const [text, value] of originalText) text.value = value;
+	}
+}
+function isHtmlWhitespace(character) {
+	return character === "	" || character === "\n" || character === "\f" || character === "\r" || character === " ";
+}
+function isMdxWhitespace(character) {
+	return /\s/u.test(character ?? "");
+}
+function openingTagAttributeOffset(content, start, end, isWhitespace) {
+	let state = "tagName";
+	let quote;
+	for (let index = start; index < end; index++) {
+		const character = content[index];
+		const closesTag = character === ">";
+		const selfClosesTag = character === "/" && content[index + 1] === ">";
+		if (state === "quotedAttributeValue") {
+			if (character === quote) {
+				quote = void 0;
+				state = "afterQuotedAttributeValue";
+			}
+			continue;
+		}
+		if (state === "unquotedAttributeValue") {
+			if (closesTag) return index;
+			if (isWhitespace(character)) state = "beforeAttributeName";
+			continue;
+		}
+		if (closesTag) return index;
+		if (selfClosesTag && state !== "beforeAttributeValue") {
+			let cursor = index;
+			while (cursor > start && isWhitespace(content[cursor - 1])) cursor--;
+			return cursor;
+		}
+		if (state === "tagName") {
+			if (isWhitespace(character)) state = "beforeAttributeName";
+		} else if (state === "beforeAttributeName") {
+			if (!isWhitespace(character)) state = "attributeName";
+		} else if (state === "attributeName") {
+			if (character === "=") state = "beforeAttributeValue";
+			else if (isWhitespace(character)) state = "afterAttributeName";
+		} else if (state === "afterAttributeName") {
+			if (character === "=") state = "beforeAttributeValue";
+			else if (!isWhitespace(character)) state = "attributeName";
+		} else if (state === "beforeAttributeValue") {
+			if (character === "\"" || character === "'") {
+				quote = character;
+				state = "quotedAttributeValue";
+			} else if (!isWhitespace(character)) state = "unquotedAttributeValue";
+		} else if (state === "afterQuotedAttributeValue" && isWhitespace(character)) state = "beforeAttributeName";
+	}
+}
+function rawHtmlHeadings(tree, content, lineOffset) {
+	let hasRawHtml = false;
+	visitHtml(tree, () => {
+		hasRawHtml = true;
+	});
+	if (!hasRawHtml) return [];
+	const markdownOffsets = /* @__PURE__ */ new Set();
+	visitHeadings(tree, (heading) => {
+		const offset = heading.position?.start.offset;
+		if (offset !== void 0) markdownOffsets.add(offset);
+	});
+	let hast;
+	const captureHast = () => (tree) => {
+		hast = tree;
+	};
+	createProcessor({
+		format: "md",
+		remarkRehypeOptions: { allowDangerousHtml: true },
+		rehypePlugins: [rehypeRaw, captureHast]
+	}).runSync(tree, { value: content });
+	if (!hast) return [];
+	const headings = [];
+	visitHastHeadings(hast, (heading) => {
+		const offset = heading.position?.start.offset;
+		const headingEnd = heading.position?.end.offset;
+		if (offset === void 0 || headingEnd === void 0 || markdownOffsets.has(offset)) return;
+		const tagEnd = openingTagAttributeOffset(content, offset, headingEnd, isHtmlWhitespace);
+		if (tagEnd === void 0) return;
+		const rawId = heading.properties?.id;
+		headings.push({
+			title: hastText$1(heading),
+			...typeof rawId === "string" && rawId ? { id: rawId } : {},
+			position: {
+				line: (heading.position?.start.line ?? 1) + lineOffset,
+				column: heading.position?.start.column ?? 1
+			},
+			offset,
+			attributeOffset: tagEnd
+		});
+	});
+	return headings;
+}
+function staticMdxText(node) {
+	if (node.type === "text" || node.type === "inlineCode") return node.value ?? "";
+	if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
+		if (!node.name || !/^[a-z][a-z0-9-]*$/.test(node.name)) return void 0;
+	} else if (!node.children) return;
+	const parts = [];
+	for (const child of node.children ?? []) {
+		const text = staticMdxText(child);
+		if (text === void 0) return void 0;
+		parts.push(text);
+	}
+	return parts.join("");
+}
+function literalMdxId(node) {
+	let result = { kind: "missing" };
+	for (const attribute of node.attributes ?? []) {
+		if (attribute.type !== "mdxJsxAttribute") {
+			result = { kind: "unknown" };
+			continue;
+		}
+		if (attribute.name !== "id") continue;
+		result = typeof attribute.value === "string" ? {
+			kind: "literal",
+			id: attribute.value
+		} : { kind: "unknown" };
+	}
+	return result;
+}
+function mdxIntrinsicHeadings(tree, content, lineOffset) {
+	const headings = [];
+	visitMdxIntrinsicHeadings(tree, (heading) => {
+		const position = heading.position;
+		const offset = position?.start.offset;
+		const end = position?.end.offset;
+		const title = staticMdxText(heading);
+		const literalId = literalMdxId(heading);
+		if (!position || offset === void 0 || end === void 0 || literalId.kind !== "literal") return;
+		const tagEnd = openingTagAttributeOffset(content, offset, end, isMdxWhitespace);
+		if (tagEnd === void 0) return;
+		headings.push({
+			...title !== void 0 ? { title } : {},
+			id: literalId.id,
+			position: {
+				line: position.start.line + lineOffset,
+				column: position.start.column
+			},
+			offset,
+			attributeOffset: tagEnd
+		});
+	});
+	return headings;
+}
+function escapeHtmlAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}
+function analyzeHeadings(content, options) {
+	const lineOffset = options.lineOffset ?? 0;
+	const headings = [];
+	const edits = [];
+	const errors = [];
+	const ids = /* @__PURE__ */ new Map();
+	const documentHeadings = [];
+	const markdownHeadingInputs = /* @__PURE__ */ new Map();
+	const tree = parseHeadingTree(content, options.kind);
+	if (!tree) return {
+		headings,
+		normalizedContent: content
+	};
+	const renderedTitles = renderedMarkdownHeadingTitles(tree, content, options.kind);
+	const claimId = (id, position) => {
+		const owner = ids.get(id);
+		if (owner) {
+			errors.push(`Heading ID "${id}" at ${formatPosition(position)} conflicts with the heading at ${formatPosition(owner.position)}.`);
+			return;
+		}
+		ids.set(id, {
+			id,
+			position
+		});
+	};
+	visitHeadings(tree, (node) => {
+		const marker = explicitIdInfo(node, content);
+		const title = renderedTitles.get(node.position?.start.offset ?? 0) ?? "";
+		const hasValidExplicitId = marker !== void 0 && HEADING_ID_PATTERN.test(marker.id);
+		const heading = {
+			level: node.depth ?? 1,
+			title,
+			id: hasValidExplicitId ? marker.id : "",
+			position: headingPosition(node, lineOffset)
+		};
+		if (marker && !hasValidExplicitId) errors.push(`Invalid heading ID "${marker.id}" at ${formatPosition(heading.position)}. IDs must match [a-z0-9]+(?:-[a-z0-9]+)*.`);
+		headings.push(heading);
+		markdownHeadingInputs.set(heading, {
+			...marker ? { marker } : {},
+			hasValidExplicitId,
+			contentEnd: contentEndOffset(node)
+		});
+		documentHeadings.push({
+			title,
+			offset: node.position?.start.offset ?? 0,
+			markdown: heading
+		});
+	});
+	const renderedHeadings = options.kind === "markdown" ? rawHtmlHeadings(tree, content, lineOffset) : mdxIntrinsicHeadings(tree, content, lineOffset);
+	for (const rendered of renderedHeadings) documentHeadings.push({
+		...rendered.title !== void 0 ? { title: rendered.title } : {},
+		offset: rendered.offset,
+		rendered
+	});
+	documentHeadings.sort((left, right) => left.offset - right.offset);
+	const slugger = new GithubSlugger();
+	for (const documentHeading of documentHeadings) {
+		if (documentHeading.markdown) {
+			const heading = documentHeading.markdown;
+			const input = markdownHeadingInputs.get(heading);
+			if (input.hasValidExplicitId) {
+				edits.push({
+					start: input.marker.start,
+					end: input.marker.end,
+					replacement: ` [](clarify-internal-heading-id:${heading.id})`
+				});
+				continue;
+			}
+		}
+		if (documentHeading.rendered?.id !== void 0) continue;
+		if (documentHeading.title === void 0) continue;
+		const generatedId = slugger.slug(documentHeading.title);
+		if (documentHeading.markdown) {
+			const heading = documentHeading.markdown;
+			const input = markdownHeadingInputs.get(heading);
+			heading.id = generatedId;
+			const link = ` [](clarify-internal-heading-id:${heading.id})`;
+			if (input.marker) edits.push({
+				start: input.marker.start,
+				end: input.marker.end,
+				replacement: link
+			});
+			else if (input.contentEnd !== void 0) edits.push({
+				start: input.contentEnd,
+				end: input.contentEnd,
+				replacement: link
+			});
+		} else if (documentHeading.rendered && documentHeading.rendered.id === void 0) {
+			documentHeading.rendered.id = generatedId;
+			edits.push({
+				start: documentHeading.rendered.attributeOffset,
+				end: documentHeading.rendered.attributeOffset,
+				replacement: ` id="${escapeHtmlAttribute(generatedId)}"`
+			});
+		}
+	}
+	for (const documentHeading of documentHeadings) if (documentHeading.markdown) claimId(documentHeading.markdown.id, documentHeading.markdown.position);
+	else if (documentHeading.rendered?.id) claimId(documentHeading.rendered.id, documentHeading.rendered.position);
+	const diagnostic = errors.length === 0 ? void 0 : createContentDiagnostic({
+		kind: options.kind,
+		title: "Heading ID error",
+		message: "This page has invalid or conflicting heading IDs. Fix the IDs below, then reload the route.",
+		error: new Error(errors.join("\n")),
+		filePath: options.filePath,
+		projectRoot: options.projectRoot
+	});
+	return {
+		headings,
+		normalizedContent: applySourceEdits(content, edits),
+		diagnostic
+	};
+}
+function remarkApplyHeadingIds() {
+	return (tree) => {
+		visitHeadings(tree, (heading) => {
+			const finalNode = heading.children?.at(-1);
+			if (finalNode?.type !== "link" || finalNode.children?.length !== 0 || typeof finalNode.url !== "string" || !finalNode.url.startsWith(INTERNAL_HEADING_ID_PREFIX)) return;
+			const id = finalNode.url.slice(28);
+			heading.children?.pop();
+			const previousNode = heading.children?.at(-1);
+			if (previousNode?.type === "text" && typeof previousNode.value === "string") previousNode.value = previousNode.value.replace(/ $/, "");
+			heading.data = heading.data ?? {};
+			heading.data.hProperties = {
+				...heading.data.hProperties,
+				id
+			};
+		});
+	};
+}
+//#endregion
 //#region source/parsers/markdown/mdx.ts
 function getLanguage(className) {
 	return (Array.isArray(className) ? className : typeof className === "string" ? className.split(/\s+/) : []).find((item) => typeof item === "string" && item.startsWith("language-"))?.replace(/^language-/, "") || "txt";
@@ -67,9 +460,34 @@ function rehypeParseCodeBlocks() {
 		});
 	};
 }
-var remarkPlugins = markdownRemarkPlugins;
+function hastText(node) {
+	if (node.type === "text") return node.value ?? "";
+	return (node.children ?? []).map(hastText).join("");
+}
+function isHeadingElement(node) {
+	return Boolean(node.tagName && /^h[1-6]$/.test(node.tagName));
+}
+function rehypeAddMissingHeadingIds() {
+	return (tree) => {
+		const slugger = new GithubSlugger();
+		const reservedIds = /* @__PURE__ */ new Set();
+		visit(tree, "element", (node) => {
+			if (isHeadingElement(node) && typeof node.properties?.id === "string" && node.properties.id) reservedIds.add(node.properties.id);
+		});
+		visit(tree, "element", (node) => {
+			if (!isHeadingElement(node)) return;
+			const title = hastText(node);
+			let fallbackId = slugger.slug(title);
+			if (node.properties?.id) return;
+			while (reservedIds.has(fallbackId)) fallbackId = slugger.slug(title);
+			node.properties = node.properties ?? {};
+			node.properties.id = fallbackId;
+		});
+	};
+}
+var remarkPlugins = [remarkApplyHeadingIds, ...markdownRemarkPlugins];
 var rehypePlugins = [
-	rehypeSlug,
+	rehypeAddMissingHeadingIds,
 	rehypeParseCodeBlocks,
 	[rehypeShiki, {
 		theme: cssVariablesTheme,
@@ -224,9 +642,12 @@ async function runBuildDoneHooks(plugins, ctx) {
 */
 function parseFrontmatter(content) {
 	const parsed = matter(content);
+	const body = parsed.content.replace(/^\r?\n/, "");
+	const prefix = content.slice(0, content.length - body.length);
 	return {
 		frontmatter: parsed.data,
-		content: parsed.content.replace(/^\r?\n/, "")
+		content: body,
+		lineOffset: [...prefix.matchAll(/\r\n|\r|\n/g)].length
 	};
 }
 //#endregion
@@ -237,7 +658,7 @@ async function transformContent(transform, input) {
 function createContentProcessor(transform) {
 	return {
 		async processMdx(source, filePath) {
-			const { frontmatter, content } = parseFrontmatter(source);
+			const { frontmatter, content, lineOffset } = parseFrontmatter(source);
 			const transformed = await transformContent(transform, {
 				kind: "markdown+jsx",
 				source,
@@ -247,7 +668,8 @@ function createContentProcessor(transform) {
 			});
 			return {
 				frontmatter: transformed.frontmatter,
-				content: transformed.content
+				content: transformed.content,
+				lineOffset
 			};
 		},
 		async processText(source, kind, filePath) {
@@ -357,13 +779,47 @@ function resolveUpdatedAt(frontmatter, detectedAt) {
 	return normalizeDate(typeof frontmatter.updatedAt === "string" ? frontmatter.updatedAt : void 0) ?? detectedAt;
 }
 //#endregion
-//#region source/parsers/routes/routes.ts
+//#region source/parsers/routes/heading-metadata.ts
 function kebabToTitle(str) {
-	return str.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-}
-function parseMdxTree(content) {
-	return remark.parse(content);
+	return str.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function headingMetadata(analysis) {
+	return { sections: analysis.headings.filter((heading) => heading.level === 2 || heading.level === 3).map((heading) => ({
+		id: heading.id,
+		title: heading.title,
+		level: heading.level
+	})) };
+}
+function resolvedRouteTitle(route, analysis) {
+	const frontmatterTitle = route.source.frontmatter?.title;
+	if (typeof frontmatterTitle === "string" && frontmatterTitle) return frontmatterTitle;
+	const routePath = route.basePath ?? route.path;
+	return kebabToTitle(routePath === "/" ? analysis.headings.find((heading) => heading.level === 1)?.title ?? "" : routePath.split("/").filter(Boolean).at(-1) ?? "") || "Untitled";
+}
+async function reanalyzeMarkdownRoute(route, projectRoot) {
+	if (route.kind !== "markdown" && route.kind !== "markdown+jsx") return route;
+	const analysis = analyzeHeadings(route.source.content ?? "", {
+		kind: route.kind,
+		filePath: route.source.filePath,
+		projectRoot,
+		lineOffset: route.source.lineOffset
+	});
+	const result = await (route.kind === "markdown" ? compileMarkdownContent : compileMdxContent)(analysis.normalizedContent, {
+		filePath: route.source.filePath,
+		projectRoot
+	});
+	return {
+		...route,
+		meta: {
+			...route.meta,
+			title: resolvedRouteTitle(route, analysis),
+			...headingMetadata(analysis)
+		},
+		diagnostic: analysis.diagnostic ?? (result.ok ? void 0 : result.diagnostic)
+	};
 }
+//#endregion
+//#region source/parsers/routes/routes.ts
 async function compileRouteDiagnostic(content, filePath, baseDir) {
 	const result = await (extname(filePath).toLowerCase() === ".md" ? compileMarkdownContent : compileMdxContent)(content, {
 		filePath,
@@ -371,30 +827,6 @@ async function compileRouteDiagnostic(content, filePath, baseDir) {
 	});
 	return result.ok ? void 0 : result.diagnostic;
 }
-/** 从内容中提取第一个 H1 标题 */
-function extractH1(content) {
-	const tree = parseMdxTree(content);
-	let title = "";
-	visit(tree, "heading", (node) => {
-		if (!title && node.depth === 1) title = toString(node);
-	});
-	return title;
-}
-/** 从 MDX/Markdown 内容中提取 H2/H3 章节 */
-function extractMdxSections(content) {
-	const sections = [];
-	const slugger = new GithubSlugger();
-	visit(parseMdxTree(content), "heading", (node) => {
-		if (node.depth !== 2 && node.depth !== 3) return;
-		const title = toString(node);
-		sections.push({
-			id: slugger.slug(title),
-			title,
-			level: node.depth
-		});
-	});
-	return sections;
-}
 function navigationSections(sections) {
 	return sections.map((section) => ({
 		id: section.id,
@@ -451,11 +883,12 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 		const fullPath = join(dir, entry.name);
 		if (entry.isDirectory()) routes.push(...await findContentRoutes(fullPath, base, options));
 		else if (entry.isFile() && /\.mdx?$/.test(entry.name)) {
+			const kind = entry.name.toLowerCase().endsWith(".mdx") ? "markdown+jsx" : "markdown";
 			const relativePath = relative(base, fullPath);
 			const pathParts = relativePath.replace(/\.mdx?$/, "").split("/");
 			const cleanPath = ("/" + pathParts.map((p) => p === "index" ? "" : p).filter(Boolean).join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
 			const source = await readFile(fullPath, "utf-8");
-			const { frontmatter, content } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
+			const { frontmatter, content, lineOffset } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
 			const updatedAt = resolveUpdatedAt(frontmatter, await getFileUpdatedAt(fullPath, base));
 			const page = {
 				path: cleanPath,
@@ -463,14 +896,21 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 				frontmatter,
 				content
 			};
-			const diagnostic = await compileRouteDiagnostic(page.content, fullPath, base);
+			const analysis = analyzeHeadings(page.content, {
+				kind,
+				filePath: fullPath,
+				projectRoot: base,
+				lineOffset
+			});
+			const compileDiagnostic = await compileRouteDiagnostic(analysis.normalizedContent, fullPath, base);
+			const { sections } = headingMetadata(analysis);
 			let title = typeof page.frontmatter.title === "string" ? page.frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
-				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(page.content) : lastPart) || "Untitled";
+				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : analysis.headings.find((heading) => heading.level === 1)?.title ?? "" : lastPart) || "Untitled";
 			}
 			routes.push({
-				kind: entry.name.toLowerCase().endsWith(".mdx") ? "markdown+jsx" : "markdown",
+				kind,
 				path: cleanPath,
 				basePath: cleanPath,
 				meta: {
@@ -480,7 +920,7 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 					group: typeof page.frontmatter.group === "string" ? page.frontmatter.group : void 0,
 					layout: page.frontmatter.layout === "documentation" || page.frontmatter.layout === "blog" ? page.frontmatter.layout : void 0,
 					updatedAt,
-					sections: extractMdxSections(page.content)
+					sections
 				},
 				module: {
 					pageVirtualModuleId: pageVirtualModuleId(relativePath.replace(/\.mdx?$/, "")),
@@ -489,9 +929,10 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 				source: {
 					filePath: fullPath,
 					frontmatter: page.frontmatter,
-					content: page.content
+					content: page.content,
+					lineOffset
 				},
-				diagnostic
+				diagnostic: analysis.diagnostic ?? compileDiagnostic
 			});
 		}
 	}
@@ -647,6 +1088,7 @@ function routeIntentFromPagesItem(item) {
 		kind: "openapi",
 		ref: item.openapi,
 		tagFilter: item.filter?.tags,
+		operationOrder: item.operationOrder,
 		path: item.path,
 		title: item.title,
 		icon: item.icon
@@ -1113,6 +1555,7 @@ var clarifyPagesItemSchema = z.lazy(() => z.union([
 	z.object({
 		openapi: z.string(),
 		path: z.string().optional(),
+		operationOrder: z.array(z.string()).optional(),
 		icon: z.string().optional(),
 		title: clarifyLocalizedTextSchema.optional(),
 		filter: z.object({ tags: z.array(z.string()).optional() }).strict().optional()
@@ -1595,10 +2038,14 @@ function createNormalizedContentPlugin(engine) {
 		transform(_code, id) {
 			if (!/\.mdx?(?:\?|$)/.test(id)) return null;
 			const filePath = id.replace(/\?.*$/, "");
-			const route = engine.routes.find((route) => (route.kind === "markdown+jsx" || route.kind === "markdown") && route.source.filePath === filePath);
-			if (!route || route.source.content === void 0) return null;
+			const route = engine.routes.find((route) => route.source.filePath === filePath);
+			if (!route || route.kind !== "markdown+jsx" && route.kind !== "markdown" || route.source.content === void 0) return null;
 			return {
-				code: route.source.content,
+				code: analyzeHeadings(route.source.content, {
+					kind: route.kind,
+					filePath,
+					projectRoot: engine.root
+				}).normalizedContent,
 				map: null
 			};
 		}
@@ -1788,7 +2235,7 @@ function createViteAdapter(engine) {
 }
 var cliPackageVersion = {
 	name: "@clarify-labs/cli",
-	version: "0.11.18",
+	version: "0.11.20",
 	license: "AGPL-3.0-only",
 	type: "module",
 	repository: {
@@ -1991,6 +2438,191 @@ function createLlmsTxtArtifact(routes, projectConfig) {
 	return withUtf8Signature(createLlmsTxt(routes, projectConfig));
 }
 //#endregion
+//#region source/plugins/openapi/aggregation.ts
+function mergeOpenAPIRecord(target, source, section, filePath) {
+	if (!source) return;
+	for (const [key, value] of Object.entries(source)) {
+		const existing = target[key];
+		if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(value)) throw new Error(`[clarify] Cannot aggregate OpenAPI specs: conflicting ${section} entry "${key}" in ${filePath}.`);
+		target[key] = value;
+	}
+}
+function openAPIVersionFamily(version) {
+	return version.split(".").slice(0, 2).join(".");
+}
+var OPENAPI_OPERATION_METHODS = /* @__PURE__ */ new Set([
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+]);
+function sourceComponentPrefix(source) {
+	return (source.id || source.filePath.split(/[\\/]/).pop()?.replace(/\.openapi\.(?:json|ya?ml)$/i, "") || "service").replace(/[^a-zA-Z0-9._-]/g, "_") || "service";
+}
+function securitySchemeNameMap(source, sourceSchemes, targetSchemes) {
+	const names = /* @__PURE__ */ new Map();
+	for (const [name, definition] of Object.entries(sourceSchemes)) {
+		const existing = targetSchemes[name];
+		if (existing === void 0 || JSON.stringify(existing) === JSON.stringify(definition)) {
+			targetSchemes[name] = definition;
+			names.set(name, name);
+			continue;
+		}
+		const prefix = sourceComponentPrefix(source);
+		let candidate = `${prefix}__${name}`;
+		let suffix = 2;
+		while (targetSchemes[candidate] !== void 0 && JSON.stringify(targetSchemes[candidate]) !== JSON.stringify(definition)) candidate = `${prefix}__${name}_${suffix++}`;
+		targetSchemes[candidate] = definition;
+		names.set(name, candidate);
+	}
+	return names;
+}
+function rewriteSecurityRequirements(value, schemeNames) {
+	if (!Array.isArray(value)) return value;
+	return value.map((requirement) => {
+		if (!requirement || typeof requirement !== "object" || Array.isArray(requirement)) return requirement;
+		return Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [schemeNames.get(name) ?? name, scopes]));
+	});
+}
+function localizePathItemContext(pathItemValue, documentServers, documentSecurity, hasDocumentSecurity, schemeNames) {
+	if (!pathItemValue || typeof pathItemValue !== "object" || Array.isArray(pathItemValue)) return pathItemValue;
+	const pathItem = structuredClone(pathItemValue);
+	const pathServers = Object.hasOwn(pathItem, "servers") ? pathItem.servers : documentServers;
+	for (const [method, operationValue] of Object.entries(pathItem)) {
+		if (!OPENAPI_OPERATION_METHODS.has(method) || !operationValue || typeof operationValue !== "object" || Array.isArray(operationValue)) continue;
+		const operation = operationValue;
+		if (!Object.hasOwn(operation, "servers") && pathServers !== void 0) operation.servers = structuredClone(pathServers);
+		if (Object.hasOwn(operation, "security")) operation.security = rewriteSecurityRequirements(operation.security, schemeNames);
+		else if (hasDocumentSecurity) operation.security = rewriteSecurityRequirements(structuredClone(documentSecurity), schemeNames);
+	}
+	delete pathItem.servers;
+	return pathItem;
+}
+function localizeOpenAPIContexts(spec, schemeNames) {
+	const document = spec;
+	const hasDocumentSecurity = Object.hasOwn(document, "security");
+	const localizeEntries = (entries) => entries && Object.fromEntries(Object.entries(entries).map(([name, pathItem]) => [name, localizePathItemContext(pathItem, document.servers, document.security, hasDocumentSecurity, schemeNames)]));
+	return {
+		paths: localizeEntries(spec.paths) ?? {},
+		webhooks: localizeEntries("webhooks" in spec ? spec.webhooks : void 0)
+	};
+}
+function aggregateOpenAPISources(sources, info) {
+	const paths = {};
+	const webhooks = {};
+	const components = {};
+	const tags = /* @__PURE__ */ new Map();
+	let openapiVersion;
+	for (const source of sources) {
+		const { document: spec, filePath } = source;
+		if (openapiVersion && openAPIVersionFamily(openapiVersion) !== openAPIVersionFamily(spec.openapi)) throw new Error(`[clarify] Cannot aggregate OpenAPI specs: incompatible versions "${openapiVersion}" and "${spec.openapi}" in ${filePath}.`);
+		openapiVersion ??= spec.openapi;
+		components.securitySchemes ??= {};
+		const sourceComponents = spec.components;
+		const localized = localizeOpenAPIContexts(spec, securitySchemeNameMap(source, sourceComponents?.securitySchemes ?? {}, components.securitySchemes));
+		mergeOpenAPIRecord(paths, localized.paths, "paths", filePath);
+		mergeOpenAPIRecord(webhooks, localized.webhooks, "webhooks", filePath);
+		for (const [section, entries] of Object.entries(sourceComponents ?? {})) {
+			if (section === "securitySchemes") continue;
+			components[section] ??= {};
+			mergeOpenAPIRecord(components[section], entries, `components.${section}`, filePath);
+		}
+		for (const tag of spec.tags ?? []) {
+			const existing = tags.get(tag.name);
+			if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(tag)) throw new Error(`[clarify] Cannot aggregate OpenAPI specs: conflicting tag "${tag.name}" in ${filePath}.`);
+			tags.set(tag.name, tag);
+		}
+	}
+	if (components.securitySchemes && Object.keys(components.securitySchemes).length === 0) delete components.securitySchemes;
+	return {
+		openapi: openapiVersion ?? "3.1.0",
+		info: {
+			title: info.title,
+			description: info.description,
+			version: info.version ?? "1.0.0"
+		},
+		paths,
+		...Object.keys(webhooks).length > 0 ? { webhooks } : {},
+		...Object.keys(components).length > 0 ? { components } : {},
+		...tags.size > 0 ? { tags: [...tags.values()] } : {}
+	};
+}
+//#endregion
+//#region source/plugins/openapi/artifacts.ts
+function selectRootOpenAPISources(routes, projectConfig) {
+	const defaultLocale = projectConfig.locales?.default;
+	const sourcesByFilePath = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		if (route.kind !== "openapi" || route.diagnostic || !route.source.content || route.openapi?.tagFilter?.length || route.isBareAlias || defaultLocale && route.locale && route.locale !== defaultLocale) continue;
+		sourcesByFilePath.set(route.source.filePath, {
+			id: route.openapi?.sourceSpecId ?? route.source.filePath.split(/[\\/]/).pop()?.replace(/\.openapi\.(?:json|ya?ml)$/i, "") ?? "service",
+			filePath: route.source.filePath,
+			document: JSON.parse(route.source.content)
+		});
+	}
+	return [...sourcesByFilePath.values()];
+}
+function createRootOpenAPISpec(routes, projectConfig) {
+	return aggregateOpenAPISources(selectRootOpenAPISources(routes, projectConfig), {
+		title: projectConfig.title,
+		description: projectConfig.description
+	});
+}
+function createOpenAPIRouteArtifacts(route) {
+	if (route.kind !== "openapi" || !route.source.content) return [];
+	const contentArtifactUrl = route.artifacts?.contentArtifactUrl;
+	if (!contentArtifactUrl) return [];
+	return [{
+		fileName: contentArtifactUrl.replace(/^\//, ""),
+		contentType: "application/json; charset=utf-8",
+		source: route.source.content
+	}, {
+		fileName: contentArtifactUrl.replace(/\.json$/, ".yaml").replace(/^\//, ""),
+		contentType: "text/yaml; charset=utf-8",
+		source: stringify(JSON.parse(route.source.content), { lineWidth: 0 })
+	}];
+}
+function createRootOpenAPIArtifact(routes, projectConfig) {
+	return {
+		fileName: "openapi.json",
+		contentType: "application/json; charset=utf-8",
+		source: JSON.stringify(createRootOpenAPISpec(routes, projectConfig), null, 2)
+	};
+}
+//#endregion
+//#region source/plugins/content-artifacts/provider.ts
+function createContentArtifacts(routes, projectConfig) {
+	const artifacts = [];
+	for (const route of routes) {
+		if (route.kind === "openapi") {
+			artifacts.push(...createOpenAPIRouteArtifacts(route));
+			continue;
+		}
+		const contentArtifactUrl = route.artifacts?.contentArtifactUrl;
+		if (!contentArtifactUrl) continue;
+		artifacts.push({
+			fileName: contentArtifactUrl.replace(/^\//, ""),
+			contentType: "text/markdown; charset=utf-8",
+			source: readRouteArtifactContent(route)
+		});
+	}
+	artifacts.push({
+		fileName: "llms.txt",
+		contentType: "text/plain; charset=utf-8",
+		source: createLlmsTxtArtifact(routes, projectConfig)
+	});
+	artifacts.push(createRootOpenAPIArtifact(routes, projectConfig));
+	return artifacts;
+}
+function findContentArtifact(path, routes, projectConfig) {
+	const fileName = path.replace(/^\/+/, "");
+	return createContentArtifacts(routes, projectConfig).find((artifact) => artifact.fileName === fileName);
+}
+//#endregion
 //#region source/plugins/content-artifacts/server.ts
 function normalizeRoutePrefix$1(routePrefix) {
 	if (!routePrefix || routePrefix === "/") return "";
@@ -2002,34 +2634,12 @@ function resolveContentArtifactPath(url, projectConfig) {
 	const hasBasePath = requestPath === basePath || requestPath.startsWith(`${basePath}/`);
 	return basePath && hasBasePath ? requestPath.slice(basePath.length) || "/" : requestPath;
 }
-function resolveContentArtifactType(route) {
-	return route.kind === "openapi" ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8";
-}
 function serveContentArtifacts(req, res, projectConfig, routes) {
-	const contentPath = resolveContentArtifactPath(req.url, projectConfig);
-	if (contentPath === "/llms.txt") {
-		res.statusCode = 200;
-		res.setHeader("Content-Type", "text/plain; charset=utf-8");
-		res.end(createLlmsTxtArtifact(routes, projectConfig), "utf8");
-		return true;
-	}
-	if (contentPath.endsWith(".openapi.yaml")) {
-		const jsonPath = contentPath.replace(/\.yaml$/, ".json");
-		const route = routes.find((route) => route.artifacts?.contentArtifactUrl === jsonPath);
-		if (route?.kind === "openapi" && route.source.content) {
-			const spec = JSON.parse(route.source.content);
-			res.statusCode = 200;
-			res.setHeader("Content-Type", "text/yaml; charset=utf-8");
-			res.end(stringify(spec, { lineWidth: 0 }), "utf8");
-			return true;
-		}
-		return false;
-	}
-	const route = routes.find((route) => route.artifacts?.contentArtifactUrl === contentPath);
-	if (!route) return false;
+	const artifact = findContentArtifact(resolveContentArtifactPath(req.url, projectConfig), routes, projectConfig);
+	if (!artifact) return false;
 	res.statusCode = 200;
-	res.setHeader("Content-Type", resolveContentArtifactType(route));
-	res.end(readRouteArtifactContent(route), "utf8");
+	res.setHeader("Content-Type", artifact.contentType);
+	res.end(artifact.source);
 	return true;
 }
 //#endregion
@@ -2050,30 +2660,7 @@ function createContentArtifactsPlugin() {
 					});
 				};
 			},
-			"build:assets": (ctx) => {
-				const assets = [];
-				for (const route of ctx.routes) {
-					const contentArtifactUrl = route.artifacts?.contentArtifactUrl;
-					if (!contentArtifactUrl) continue;
-					assets.push({
-						fileName: contentArtifactUrl.replace(/^\//, ""),
-						source: readRouteArtifactContent(route)
-					});
-					if (route.kind === "openapi" && route.source.content) {
-						const yamlFileName = contentArtifactUrl.replace(/\.json$/, ".yaml");
-						const spec = JSON.parse(route.source.content);
-						assets.push({
-							fileName: yamlFileName.replace(/^\//, ""),
-							source: stringify(spec, { lineWidth: 0 })
-						});
-					}
-				}
-				assets.push({
-					fileName: "llms.txt",
-					source: createLlmsTxtArtifact(ctx.routes, ctx.projectConfig)
-				});
-				return assets;
-			}
+			"build:assets": (ctx) => createContentArtifacts(ctx.routes, ctx.projectConfig)
 		}
 	};
 }
@@ -2597,9 +3184,9 @@ function filterSpecByTags(spec, tags) {
 	};
 }
 /** Extract endpoint operations from an OpenAPI spec as page sections. */
-function extractOpenAPISections(spec, filterTags) {
+function extractOpenAPISections(spec, filterTags, operationOrder) {
 	normalizeOpenAPISpecSectionIds(spec);
-	const sections = [];
+	const entries = [];
 	const items = [...Object.entries(spec.paths ?? {}).map(([path, pathItem]) => ({
 		path,
 		pathItem,
@@ -2617,16 +3204,25 @@ function extractOpenAPISections(spec, filterTags) {
 			const tags = Array.isArray(op?.tags) ? op.tags : void 0;
 			if (!op || !operationMatchesTags(tags, filterTags)) continue;
 			const title = typeof op.summary === "string" ? op.summary : `${method.toUpperCase()} ${path}`;
-			sections.push({
-				id: operationSectionId(op),
-				title,
-				level: 2,
-				badge: kind === "webhook" ? "WEBHOOK" : method.toUpperCase(),
-				tags
+			entries.push({
+				section: {
+					id: operationSectionId(op),
+					title,
+					level: 2,
+					badge: kind === "webhook" ? "WEBHOOK" : method.toUpperCase(),
+					tags
+				},
+				operationId: typeof op.operationId === "string" ? op.operationId : void 0
 			});
 		}
 	}
-	return sections;
+	if (!operationOrder?.length) return entries.map(({ section }) => section);
+	const orderById = new Map(operationOrder.map((operationId, index) => [operationId, index]));
+	return entries.map((entry, index) => ({
+		...entry,
+		index,
+		order: entry.operationId ? orderById.get(entry.operationId) : void 0
+	})).sort((left, right) => (left.order ?? operationOrder.length) - (right.order ?? operationOrder.length) || left.index - right.index).map(({ section }) => section);
 }
 async function readOpenAPISpec(filePath, contentProcessor, projectRoot) {
 	try {
@@ -2673,7 +3269,7 @@ function collectOpenAPIPageIntents(config) {
 				continue;
 			}
 			const intent = routeIntentFromPagesItem(item);
-			if (intent.kind === "openapi" && (intent.path || intent.tagFilter?.length)) intents.push(intent);
+			if (intent.kind === "openapi" && (intent.path || intent.tagFilter?.length || intent.operationOrder?.length)) intents.push(intent);
 		}
 	}
 	function visitPages(pages) {
@@ -2694,7 +3290,8 @@ function cloneOpenAPIRoute(route, overrides = {}) {
 		source: { ...route.source },
 		openapi: route.openapi ? {
 			...route.openapi,
-			tagFilter: route.openapi.tagFilter ? [...route.openapi.tagFilter] : void 0
+			tagFilter: route.openapi.tagFilter ? [...route.openapi.tagFilter] : void 0,
+			operationOrder: route.openapi.operationOrder ? [...route.openapi.operationOrder] : void 0
 		} : void 0,
 		alternates: route.alternates ? { ...route.alternates } : void 0,
 		...overrides
@@ -2743,9 +3340,21 @@ function expandConfiguredOpenAPIRoutes(routes, config) {
 	const existingKeys = new Set(routes.map((route) => `${route.locale ?? ""}:${route.basePath ?? route.path}`));
 	for (const intent of openAPIIntents) {
 		const tagFilter = intent.tagFilter?.filter(Boolean);
+		const operationOrder = intent.operationOrder?.filter(Boolean);
 		const sourceBasePath = openAPIPagePathFromRef(intent.ref);
 		const targetBasePath = openAPIPagePathFromRef(intent.ref, tagFilter, intent.path);
-		if (sourceBasePath === targetBasePath && !tagFilter?.length) continue;
+		if (sourceBasePath === targetBasePath && !tagFilter?.length) {
+			if (!operationOrder?.length) continue;
+			for (let index = 0; index < routes.length; index++) {
+				const route = routes[index];
+				if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
+				routes[index] = cloneOpenAPIRoute(route, { openapi: {
+					...route.openapi,
+					operationOrder: [...operationOrder]
+				} });
+			}
+			continue;
+		}
 		for (const route of routes) {
 			if (route.kind !== "openapi" || (route.basePath ?? route.path) !== sourceBasePath) continue;
 			const key = `${route.locale ?? ""}:${targetBasePath}`;
@@ -2758,7 +3367,8 @@ function expandConfiguredOpenAPIRoutes(routes, config) {
 				module: { pageVirtualModuleId: pageVirtualModuleId(path) },
 				openapi: {
 					...route.openapi,
-					tagFilter: tagFilter?.length ? tagFilter : void 0
+					tagFilter: tagFilter?.length ? tagFilter : void 0,
+					operationOrder: operationOrder?.length ? [...operationOrder] : void 0
 				}
 			}));
 		}
@@ -2800,10 +3410,11 @@ function generateOpenAPISpecModule(spec) {
 	return `export default ${JSON.stringify(spec)};`;
 }
 function generateOpenAPIPageModule(opts) {
+	const routeData = opts.operationOrder?.length ? { operationOrder: opts.operationOrder } : {};
 	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
 import spec from ${JSON.stringify(opts.specModuleId)};
 
-export const routeData = {};
+export const routeData = ${JSON.stringify(routeData)};
 
 export default createOpenApiRouteComponent({ ...routeData, spec });
 `;
@@ -2863,7 +3474,7 @@ var OpenAPIPluginState = class {
 			route.meta.title = spec.info?.title ?? route.meta.title;
 			route.meta.description = spec.info?.description ?? route.meta.description;
 			route.meta.updatedAt = updatedAt;
-			route.meta.sections = extractOpenAPISections(spec, route.openapi.tagFilter);
+			route.meta.sections = extractOpenAPISections(spec, route.openapi.tagFilter, route.openapi.operationOrder);
 			const pageSpec = route.openapi.tagFilter?.length ? filterSpecByTags(specWithMetadata, route.openapi.tagFilter) : specWithMetadata;
 			const routeSpecModuleId = routeSpecModuleIdFromSourceSpecId(sourceSpecId, route.openapi.tagFilter);
 			route.openapi.routeSpecModuleId = routeSpecModuleId;
@@ -2897,7 +3508,10 @@ var OpenAPIPluginState = class {
 			if (!route.openapi?.sourceSpecId) continue;
 			const routeSpecModuleId = route.openapi.routeSpecModuleId ?? route.openapi.sourceSpecId;
 			if (!this.specModules.has(routeSpecModuleId)) continue;
-			modules.set(route.module.pageVirtualModuleId, generateOpenAPIPageModule({ specModuleId: specVirtualModuleId(routeSpecModuleId) }));
+			modules.set(route.module.pageVirtualModuleId, generateOpenAPIPageModule({
+				specModuleId: specVirtualModuleId(routeSpecModuleId),
+				operationOrder: route.openapi.operationOrder
+			}));
 		}
 		return modules;
 	}
@@ -3387,7 +4001,7 @@ async function resolveRoutePages(routes, plugins, ctx) {
 		pageByRouteIndex.set(routeIndex, page);
 	}
 	if (pageByRouteIndex.size !== routes.length) throw new Error("[clarify] pages:resolved hooks must return exactly one page for each route");
-	return routes.map((route, routeIndex) => {
+	const updatedRoutes = routes.map((route, routeIndex) => {
 		const page = pageByRouteIndex.get(routeIndex);
 		return {
 			...route,
@@ -3398,6 +4012,7 @@ async function resolveRoutePages(routes, plugins, ctx) {
 			}
 		};
 	});
+	return Promise.all(updatedRoutes.map((route) => reanalyzeMarkdownRoute(route, ctx.projectRoot)));
 }
 function buildNavigationTree(routes, ctx) {
 	const tabs = ctx.projectConfig.navigation?.tabs;
@@ -3995,8 +4610,9 @@ var ClarifyEngine = class {
 	* - `skipModules`: skip `buildModules()` (check command).
 	* - `skipHints`: skip `logStartupHints()` (check command).
 	*
-	* Idempotent: calling prepare() again with the same env is a no-op unless
-	* `force` is set.
+	* Configuration initialization is cached unless `force` is set. Discovery
+	* and virtual module generation intentionally run on every call so callers
+	* observe content changes without rebuilding the Engine instance.
 	*/
 	async prepare(env = {
 		command: this.runtime.command,
@@ -4116,10 +4732,11 @@ var ClarifyEngine = class {
 			assertNoContentDiagnostics(this.routes);
 			const outputDir = this.runtime.outputDirectory ?? this.generateOptions.outputDirectory;
 			if (!outputDir) throw new Error("[clarify] outputDirectory is required before SSG runs");
-			const ssrOutputDir = join(outputDir, ".ssr");
+			let ssrOutputDir;
 			let tempEntryPath;
 			try {
 				tempEntryPath = createTempEntryFile(SSR_ENTRY_CODE);
+				ssrOutputDir = createClarifyTempDir("ssr-output");
 				await (this.runtime.buildSSRBundle ?? ((options) => buildSSRBundle(options.root, options.ssrEntry, options.ssrOutDir, options.plugins)))({
 					root: this.root,
 					ssrEntry: tempEntryPath,
@@ -4132,9 +4749,8 @@ var ClarifyEngine = class {
 				console.error("[clarify] SSG failed:", err);
 				throw err;
 			} finally {
-				if (tempEntryPath) try {
-					rmSync(tempEntryPath, { force: true });
-				} catch {}
+				removeClarifyTempDir(tempEntryPath ? resolve(tempEntryPath, "..") : void 0);
+				removeClarifyTempDir(ssrOutputDir);
 			}
 		});
 		await this.runBuildDone();
@@ -4174,4 +4790,4 @@ function createClarifyEngine(options = {}) {
 //#endregion
 export { createClarifyTempDir as a, cliPackageVersion as c, createViteAdapter as d, defineConfig as f, findRouteConflicts as i, cliPackageVersionWithCaret as l, createClarifyEngine as n, deserializeSearchIndex as o, createClarifyRuntimeAliases as r, searchMcpIndex as s, ClarifyEngine as t, printCliVersion as u };
 
-//# sourceMappingURL=engine-DeA6EGHW.js.map
+//# sourceMappingURL=engine-BgfGFPKK.js.map