@clarify-labs/cli 0.11.18 → 0.11.20

package/output/{engine-CNnlt59g.cjs → engine-CAis1rme.cjs}

@@ -30,18 +30,14 @@ _vitejs_plugin_react = __toESM(_vitejs_plugin_react, 1);
 let rehype_raw = require("rehype-raw");
 rehype_raw = __toESM(rehype_raw, 1);
 let _mdx_js_mdx = require("@mdx-js/mdx");
+let github_slugger = require("github-slugger");
+github_slugger = __toESM(github_slugger, 1);
+let _clarify_labs_renderer = require("@clarify-labs/renderer");
 let _shikijs_rehype = require("@shikijs/rehype");
 _shikijs_rehype = __toESM(_shikijs_rehype, 1);
-let rehype_slug = require("rehype-slug");
-rehype_slug = __toESM(rehype_slug, 1);
 let shiki = require("shiki");
 let unist_util_visit = require("unist-util-visit");
-let _clarify_labs_renderer = require("@clarify-labs/renderer");
 let node_fs_promises = require("node:fs/promises");
-let github_slugger = require("github-slugger");
-github_slugger = __toESM(github_slugger, 1);
-let mdast_util_to_string = require("mdast-util-to-string");
-let remark = require("remark");
 let gray_matter = require("gray-matter");
 gray_matter = __toESM(gray_matter, 1);
 let node_child_process = require("node:child_process");
@@ -76,6 +72,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 = _clarify_labs_renderer.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 = (0, _mdx_js_mdx.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 (0, _mdx_js_mdx.createProcessor)({
+		format: "md",
+		remarkPlugins: HEADING_REMARK_PLUGINS
+	}).parse(content);
+	const maskedContent = maskExplicitHeadingMarkers(content);
+	try {
+		return (0, _mdx_js_mdx.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;
+		};
+		(0, _mdx_js_mdx.createProcessor)({
+			format: kind === "markdown" ? "md" : "mdx",
+			remarkPlugins: HEADING_REMARK_PLUGINS,
+			...kind === "markdown" ? { remarkRehypeOptions: { allowDangerousHtml: true } } : {},
+			rehypePlugins: kind === "markdown" ? [rehype_raw.default, 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;
+	};
+	(0, _mdx_js_mdx.createProcessor)({
+		format: "md",
+		remarkRehypeOptions: { allowDangerousHtml: true },
+		rehypePlugins: [rehype_raw.default, 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 github_slugger.default();
+	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";
@@ -98,9 +490,34 @@ function rehypeParseCodeBlocks() {
 		});
 	};
 }
-var remarkPlugins = _clarify_labs_renderer.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 github_slugger.default();
+		const reservedIds = /* @__PURE__ */ new Set();
+		(0, unist_util_visit.visit)(tree, "element", (node) => {
+			if (isHeadingElement(node) && typeof node.properties?.id === "string" && node.properties.id) reservedIds.add(node.properties.id);
+		});
+		(0, unist_util_visit.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, ..._clarify_labs_renderer.markdownRemarkPlugins];
 var rehypePlugins = [
-	rehype_slug.default,
+	rehypeAddMissingHeadingIds,
 	rehypeParseCodeBlocks,
 	[_shikijs_rehype.default, {
 		theme: cssVariablesTheme,
@@ -255,9 +672,12 @@ async function runBuildDoneHooks(plugins, ctx) {
 */
 function parseFrontmatter(content) {
 	const parsed = (0, gray_matter.default)(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
@@ -268,7 +688,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,
@@ -278,7 +698,8 @@ function createContentProcessor(transform) {
 			});
 			return {
 				frontmatter: transformed.frontmatter,
-				content: transformed.content
+				content: transformed.content,
+				lineOffset
 			};
 		},
 		async processText(source, kind, filePath) {
@@ -388,13 +809,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.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 ((0, node_path.extname)(filePath).toLowerCase() === ".md" ? compileMarkdownContent : compileMdxContent)(content, {
 		filePath,
@@ -402,30 +857,6 @@ async function compileRouteDiagnostic(content, filePath, baseDir) {
 	});
 	return result.ok ? void 0 : result.diagnostic;
 }
-/** 从内容中提取第一个 H1 标题 */
-function extractH1(content) {
-	const tree = parseMdxTree(content);
-	let title = "";
-	(0, unist_util_visit.visit)(tree, "heading", (node) => {
-		if (!title && node.depth === 1) title = (0, mdast_util_to_string.toString)(node);
-	});
-	return title;
-}
-/** 从 MDX/Markdown 内容中提取 H2/H3 章节 */
-function extractMdxSections(content) {
-	const sections = [];
-	const slugger = new github_slugger.default();
-	(0, unist_util_visit.visit)(parseMdxTree(content), "heading", (node) => {
-		if (node.depth !== 2 && node.depth !== 3) return;
-		const title = (0, mdast_util_to_string.toString)(node);
-		sections.push({
-			id: slugger.slug(title),
-			title,
-			level: node.depth
-		});
-	});
-	return sections;
-}
 function navigationSections(sections) {
 	return sections.map((section) => ({
 		id: section.id,
@@ -482,11 +913,12 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 		const fullPath = (0, node_path.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 = (0, node_path.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 (0, node_fs_promises.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,
@@ -494,14 +926,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: {
@@ -511,7 +950,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?$/, "")),
@@ -520,9 +959,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
 			});
 		}
 	}
@@ -678,6 +1118,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
@@ -1144,6 +1585,7 @@ var clarifyPagesItemSchema = zod.z.lazy(() => zod.z.union([
 	zod.z.object({
 		openapi: zod.z.string(),
 		path: zod.z.string().optional(),
+		operationOrder: zod.z.array(zod.z.string()).optional(),
 		icon: zod.z.string().optional(),
 		title: clarifyLocalizedTextSchema.optional(),
 		filter: zod.z.object({ tags: zod.z.array(zod.z.string()).optional() }).strict().optional()
@@ -1626,10 +2068,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
 			};
 		}
@@ -1819,7 +2265,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: {
@@ -2022,6 +2468,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: (0, yaml.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 "";
@@ -2033,34 +2664,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((0, yaml.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
@@ -2081,30 +2690,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: (0, yaml.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)
 		}
 	};
 }
@@ -2628,9 +3214,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,
@@ -2648,16 +3234,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 {
@@ -2704,7 +3299,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) {
@@ -2725,7 +3320,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
@@ -2774,9 +3370,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}`;
@@ -2789,7 +3397,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
 				}
 			}));
 		}
@@ -2831,10 +3440,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 });
 `;
@@ -2894,7 +3504,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;
@@ -2928,7 +3538,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;
 	}
@@ -3418,7 +4031,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,
@@ -3429,6 +4042,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;
@@ -4026,8 +4640,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,
@@ -4147,10 +4762,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 = (0, node_path.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,
@@ -4163,9 +4779,8 @@ var ClarifyEngine = class {
 				console.error("[clarify] SSG failed:", err);
 				throw err;
 			} finally {
-				if (tempEntryPath) try {
-					(0, node_fs.rmSync)(tempEntryPath, { force: true });
-				} catch {}
+				removeClarifyTempDir(tempEntryPath ? (0, node_path.resolve)(tempEntryPath, "..") : void 0);
+				removeClarifyTempDir(ssrOutputDir);
 			}
 		});
 		await this.runBuildDone();
@@ -4276,4 +4891,4 @@ Object.defineProperty(exports, "searchMcpIndex", {
 	}
 });
 
-//# sourceMappingURL=engine-CNnlt59g.cjs.map
+//# sourceMappingURL=engine-CAis1rme.cjs.map