@clarify-labs/cli 0.9.3 → 0.9.4

package/output/{plugin-BUFe4vEb.cjs → plugin-Etn8ZfYN.cjs}

@@ -28,6 +28,7 @@ let _tailwindcss_vite = require("@tailwindcss/vite");
 _tailwindcss_vite = __toESM(_tailwindcss_vite, 1);
 let _vitejs_plugin_react = require("@vitejs/plugin-react");
 _vitejs_plugin_react = __toESM(_vitejs_plugin_react, 1);
+let _mdx_js_mdx = require("@mdx-js/mdx");
 let github_slugger = require("github-slugger");
 github_slugger = __toESM(github_slugger, 1);
 let mdast_util_to_string = require("mdast-util-to-string");
@@ -46,6 +47,80 @@ let node_os = require("node:os");
 let zod = require("zod");
 let vite = require("vite");
 let node_module = require("node:module");
+var cliPackageVersion = {
+	name: "@clarify-labs/cli",
+	version: "0.9.4",
+	license: "AGPL-3.0-only",
+	type: "module",
+	repository: {
+		"type": "git",
+		"url": "https://github.com/taicode-labs/clarify",
+		"directory": "packages/cli"
+	},
+	main: "output/index.cjs",
+	module: "output/index.js",
+	types: "output/index.d.ts",
+	bin: { "clarify": "bin/clarify.js" },
+	exports: {
+		".": {
+			"types": "./output/index.d.ts",
+			"import": "./output/index.js",
+			"require": "./output/index.cjs",
+			"default": "./output/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	files: [
+		"LICENSE",
+		"bin",
+		"output"
+	],
+	scripts: {
+		"dev": "vite build --watch",
+		"build": "vite build",
+		"lint": "eslint source/",
+		"lint:fix": "eslint source/ --fix",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest"
+	},
+	dependencies: {
+		"@apidevtools/swagger-parser": "^12.1.0",
+		"@clarify-labs/renderer": "workspace:*",
+		"@clarify-labs/templates": "workspace:*",
+		"@mdx-js/mdx": "^3.1.1",
+		"@mdx-js/rollup": "^3.1.1",
+		"@tailwindcss/vite": "^4.1.11",
+		"@vitejs/plugin-react": "^6.0.2",
+		"cac": "^7.0.0",
+		"github-slugger": "^2.0.0",
+		"gray-matter": "^4.0.3",
+		"mdast-util-to-string": "^4.0.0",
+		"mermaid": "^11.4.0",
+		"openapi-types": "^12.1.3",
+		"pagefind": "^1.5.2",
+		"react": "^19.1.0",
+		"react-dom": "^19.1.0",
+		"react-router": "^7.0.0",
+		"react-router-dom": "^7.0.0",
+		"react-zoom-pan-pinch": "^4.0.3",
+		"remark": "^15.0.1",
+		"remark-gfm": "^4.0.1",
+		"shiki": "0.14.7",
+		"unist-util-visit": "^5.1.0",
+		"vite": "^8.0.15",
+		"yaml": "^2.9.0",
+		"zod": "^4.4.3"
+	},
+	devDependencies: {
+		"@types/react": "^19.1.8",
+		"typescript": "^5.8.3",
+		"vite-plugin-dts": "^4.5.4",
+		"vitest": "^4.1.9"
+	}
+}.version ?? "0.0.0";
+var cliPackageVersionWithCaret = `^${cliPackageVersion}`;
+//#endregion
 //#region source/core/utils.ts
 function escapeHtml(text) {
 	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
@@ -134,6 +209,32 @@ var rehypePlugins = [
 	rehypeParseCodeBlocks,
 	rehypeShiki
 ];
+function formatMdxDiagnostic(error) {
+	if (error instanceof Error) return error.message;
+	return String(error);
+}
+async function compileMdxContent(content, filePath, projectRoot) {
+	try {
+		await (0, _mdx_js_mdx.compile)(content, {
+			jsx: true,
+			providerImportSource: "@clarify-labs/renderer",
+			remarkPlugins,
+			rehypePlugins
+		});
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			diagnostic: {
+				kind: "mdx",
+				title: "MDX syntax error",
+				message: "This page could not be compiled. Fix the MDX syntax or component usage above, then reload the route.",
+				filePath: filePath && projectRoot ? filePath.replace(projectRoot + "/", "").replace(/^\/+/, "") : filePath ? filePath.replace(/^[A-Za-z]:\//, "").replace(/^\/+/, "") : void 0,
+				details: formatMdxDiagnostic(error)
+			}
+		};
+	}
+}
 //#endregion
 //#region source/plugins/content-artifacts/artifacts.ts
 var UTF8_SIGNATURE = "";
@@ -582,23 +683,25 @@ async function findContentRoutes(dir, base = dir, options = {}) {
 			const cleanPath = ("/" + pathParts.map((p) => p === "index" ? "" : p).filter(Boolean).join("/")).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
 			const source = (0, node_fs.readFileSync)(fullPath, "utf-8");
 			const { frontmatter, content } = await (options.contentProcessor ?? createContentProcessor()).processMdx(source, fullPath);
+			const mdxResult = await compileMdxContent(content, fullPath, base);
 			let title = typeof frontmatter.title === "string" ? frontmatter.title : "";
 			if (!title) {
 				const lastPart = pathParts[pathParts.length - 1] ?? "";
 				title = kebabToTitle(lastPart === "index" ? pathParts.length >= 2 ? pathParts[pathParts.length - 2] : extractH1(content) : lastPart) || "Untitled";
 			}
 			routes.push({
+				kind: "mdx",
+				title,
 				path: cleanPath,
 				basePath: cleanPath,
 				filePath: fullPath,
 				virtualModuleId: "virtual:clarify-page/" + relativePath.replace(/\.mdx?$/, "").replace(/\/+/g, "/"),
-				title,
 				description: typeof frontmatter.description === "string" ? frontmatter.description : void 0,
 				keywords: frontmatterKeywords(frontmatter),
-				kind: "mdx",
 				frontmatter,
 				content,
-				sections: extractMdxSections(content)
+				sections: extractMdxSections(content),
+				diagnostic: mdxResult.ok ? void 0 : mdxResult.diagnostic
 			});
 		}
 	}
@@ -932,10 +1035,11 @@ async function readOpenAPISpec(filePath, contentProcessor) {
 		return {
 			ok: false,
 			diagnostic: {
+				kind: "openapi",
 				title: "OpenAPI spec parse failed",
 				message: `Clarify could not parse ${filePath}.`,
 				filePath,
-				cause: errorMessage(error)
+				details: errorMessage(error)
 			}
 		};
 	}
@@ -956,17 +1060,19 @@ function resolveVirtualId(id) {
 function stripVirtualPrefix(id) {
 	return id.startsWith("\0") ? id.slice(1) : id;
 }
-function generateConfigModule(projectConfig, buildOptions) {
-	return `export const config = ${JSON.stringify({
+function generateConfigModule(projectConfig, buildOptions, version) {
+	const runtimeConfig = {
 		...projectConfig,
 		...buildOptions
-	})};`;
+	};
+	if (version) runtimeConfig.version = version;
+	return `export const config = ${JSON.stringify(runtimeConfig)};`;
 }
 function moduleSpecifier(value) {
 	return JSON.stringify(value);
 }
 function generateRoutesModule(routes, resolvedNavigation, projectConfig, mode = "client") {
-	const imports = mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.virtualModuleId)};`).join("\n") : "";
+	const imports = mode === "server" ? routes.map((r, i) => `import Page${i} from ${moduleSpecifier(r.virtualModuleId)};`).join("\n") : `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';`;
 	const routesArray = routes.map((r, i) => {
 		const sections = r.sections && r.sections.length > 0 ? `, sections: ${JSON.stringify(r.sections.map((s) => ({
 			id: s.id,
@@ -984,7 +1090,7 @@ function generateRoutesModule(routes, resolvedNavigation, projectConfig, mode =
 		const description = r.description ? `, description: ${JSON.stringify(r.description)}` : "";
 		const keywords = r.keywords && r.keywords.length > 0 ? `, keywords: ${JSON.stringify(r.keywords)}` : "";
 		const sourceUrl = r.sourceUrl ? `, sourceUrl: ${JSON.stringify(r.sourceUrl)}` : "";
-		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.virtualModuleId)})`;
+		const component = mode === "server" ? `Page${i}` : `() => import(${moduleSpecifier(r.virtualModuleId)}).catch((error) => Promise.resolve({ default: createContentDiagnosticComponent({ kind: 'route-load', title: 'This page could not be loaded', message: error instanceof Error ? error.message : String(error), details: error instanceof Error ? error.stack : undefined }) }))`;
 		const lazy = mode === "client" ? ", lazy: true" : "";
 		return `  { path: ${JSON.stringify(r.path)}, title: ${JSON.stringify(r.title)}, component: ${component}${lazy}, kind: ${JSON.stringify(r.kind)}${basePath}${locale}${isFallback}${isBareAlias}${alternates}${description}${keywords}${sections}${contentArtifactUrl}${sourceUrl} }`;
 	}).join(",\n");
@@ -1043,11 +1149,25 @@ function createRuntimeSlotsModule(plugins = [], root = process.cwd()) {
 function createSlotModule() {
 	return `export { useSlot } from '@clarify-labs/renderer';\n`;
 }
+function generateMdxErrorModule(diagnostic) {
+	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
+
+export const contentDiagnostic = ${JSON.stringify({
+		kind: diagnostic.kind ?? "mdx",
+		title: diagnostic.title,
+		message: diagnostic.message,
+		filePath: diagnostic.filePath,
+		details: diagnostic.details
+	})};
+
+export default createContentDiagnosticComponent(contentDiagnostic);
+`;
+}
 function buildVirtualModules(args) {
 	const modules = /* @__PURE__ */ new Map();
 	const clientEntryModule = createClientEntryModule({ themeEditor: args.themeEditor });
 	const allPlugins = [...args.plugins ?? []];
-	modules.set(VIRTUAL_CONFIG, generateConfigModule(args.projectConfig, args.generateOptions));
+	modules.set(VIRTUAL_CONFIG, generateConfigModule(args.projectConfig, args.generateOptions, args.version));
 	modules.set(VIRTUAL_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "client"));
 	modules.set(VIRTUAL_SERVER_ROUTES, generateRoutesModule(args.routes, args.navigation, args.projectConfig, "server"));
 	modules.set(VIRTUAL_SLOTS, createRuntimeSlotsModule(allPlugins, args.generateOptions.projectRoot));
@@ -1055,7 +1175,10 @@ function buildVirtualModules(args) {
 	modules.set(VIRTUAL_SLOT, createSlotModule());
 	modules.set(VIRTUAL_CLIENT_ENTRY, clientEntryModule);
 	modules.set(RESOLVED_CLIENT_ENTRY, clientEntryModule);
-	for (const route of args.routes) modules.set(route.virtualModuleId, `export { default } from ${moduleSpecifier(route.filePath)};`);
+	for (const route of args.routes) {
+		const moduleContent = route.diagnostic ? generateMdxErrorModule(route.diagnostic) : `export { default } from ${moduleSpecifier(route.filePath)};`;
+		modules.set(route.virtualModuleId, moduleContent);
+	}
 	return modules;
 }
 function generateOpenApiModule() {
@@ -1076,53 +1199,29 @@ function generateOpenAPISpecModule(spec) {
 	return `export default ${JSON.stringify(spec)};`;
 }
 function generateOpenAPIPageModule(opts) {
-	const { specKey, specRegistryKey, tagFilter } = opts;
-	return [
-		`import { createElement, useState, useEffect, useRef } from 'react';`,
-		`import { OpenApiDocument, useOpenApis } from '@clarify-labs/renderer';`,
-		`const SPEC_KEY = ${JSON.stringify(specRegistryKey)};`,
-		`const TAG_FILTER = ${JSON.stringify(tagFilter ?? void 0)};`,
-		`let loadPromise = null;`,
-		`function loadSpec() {`,
-		`  if (!loadPromise) loadPromise = import(${JSON.stringify(specVirtualModuleId(specKey))}).then(function(m) { return m.default; });`,
-		`  return loadPromise;`,
-		`}`,
-		`export default function OpenApiRoutePage() {`,
-		`  const specs = useOpenApis();`,
-		`  const serverSpec = specs[SPEC_KEY];`,
-		`  const [spec, setSpec] = useState(serverSpec || null);`,
-		`  const mountedRef = useRef(false);`,
-		`  useEffect(function() {`,
-		`    if (mountedRef.current) return;`,
-		`    mountedRef.current = true;`,
-		`    if (spec) return;`,
-		`    loadSpec().then(setSpec);`,
-		`  }, []);`,
-		`  if (!spec) return null;`,
-		`  return createElement(OpenApiDocument, { spec: spec, tagFilter: TAG_FILTER });`,
-		`}`
-	].join("\n");
+	return `import { createOpenApiRouteComponent } from '@clarify-labs/renderer';
+
+export const routeData = ${JSON.stringify({
+		spec: opts.spec,
+		tagFilter: opts.tagFilter
+	})};
+
+export default createOpenApiRouteComponent(routeData);
+`;
 }
 function generateOpenAPIErrorModule(diagnostic) {
-	return `import { createElement } from 'react';
-const diagnostic = ${JSON.stringify(diagnostic)};
-export default function OpenApiErrorRoutePage() {
-  return createElement('article', { className: 'flex h-full flex-col pt-16 pb-10' },
-    createElement('div', { className: 'prose max-w-none flex-auto dark:prose-invert' },
-      createElement('p', { className: 'mb-3 text-xs/6 font-medium tracking-widest text-red-500 uppercase dark:text-red-400' }, 'OpenAPI Error'),
-      createElement('h1', null, diagnostic.title),
-      createElement('p', { className: 'lead' }, diagnostic.message),
-      diagnostic.filePath ? createElement('div', { className: 'not-prose mt-6 rounded-lg border border-zinc-200 bg-zinc-50 p-4 text-sm dark:border-white/10 dark:bg-white/5' },
-        createElement('div', { className: 'mb-1 font-semibold text-zinc-900 dark:text-white' }, 'File'),
-        createElement('code', { className: 'break-all text-zinc-700 dark:text-zinc-300' }, diagnostic.filePath)
-      ) : null,
-      diagnostic.cause ? createElement('div', { className: 'not-prose mt-4 rounded-lg border border-red-200 bg-red-50 p-4 text-sm text-red-800 dark:border-red-500/30 dark:bg-red-500/10 dark:text-red-200' },
-        createElement('div', { className: 'mb-1 font-semibold' }, 'Why it happened'),
-        createElement('pre', { className: 'whitespace-pre-wrap break-words text-xs' }, diagnostic.cause)
-      ) : null
-    )
-  );
-}`;
+	return `import { createContentDiagnosticComponent } from '@clarify-labs/renderer';
+
+export const contentDiagnostic = ${JSON.stringify({
+		kind: diagnostic.kind ?? "openapi",
+		title: diagnostic.title,
+		message: diagnostic.message,
+		filePath: diagnostic.filePath,
+		details: diagnostic.details
+	})};
+
+export default createContentDiagnosticComponent(contentDiagnostic);
+`;
 }
 //#endregion
 //#region source/plugins/openapi/index.ts
@@ -1228,11 +1327,10 @@ function createOpenAPIPlugin() {
 					if (route.kind !== "openapi") continue;
 					if (route.diagnostic) modules.set(route.virtualModuleId, generateOpenAPIErrorModule(route.diagnostic));
 					else if (route.specFileKey) {
-						const base = (route.basePath ?? route.path).replace(/^\//, "");
-						const specRegistryKey = route.locale ? `virtual:clarify-page/${route.locale}/${base}` : `virtual:clarify-page/${base}`;
+						const entry = specs.get(route.specFileKey);
+						if (!entry) continue;
 						modules.set(route.virtualModuleId, generateOpenAPIPageModule({
-							specKey: route.specFileKey,
-							specRegistryKey,
+							spec: entry.spec,
 							tagFilter: route.openapiTagFilter
 						}));
 					}
@@ -1900,7 +1998,7 @@ function readJsonBody(req) {
 * Handle a request to the dev route endpoint. Pure function — does not touch
 * the network directly, only reads the request body and writes to `res`.
 */
-async function handleDevRouteRequest(req, res, routes, projectConfig, contentRoot) {
+async function handleDevRouteRequest(req, res, routes, context) {
 	res.setHeader("Content-Type", "application/json; charset=utf-8");
 	let body;
 	try {
@@ -1912,12 +2010,12 @@ async function handleDevRouteRequest(req, res, routes, projectConfig, contentRoo
 	}
 	const file = typeof body === "object" && body !== null ? body.file : void 0;
 	if (typeof file === "string" && file.length > 0) {
-		const route = resolveRouteForFile(file, routes, projectConfig.i18n?.defaultLocale);
+		const route = resolveRouteForFile(file, routes, context.projectConfig.i18n?.defaultLocale);
 		if (route) {
 			res.end(JSON.stringify(toDevRouteEntry(route)));
 			return;
 		}
-		const inferred = inferRouteForFile(file, contentRoot, projectConfig.i18n?.defaultLocale);
+		const inferred = inferRouteForFile(file, context.contentRoot, context.projectConfig.i18n?.defaultLocale);
 		res.end(JSON.stringify(inferred));
 		return;
 	}
@@ -1940,18 +2038,6 @@ declare module 'virtual:clarify/slot' {
 
   export function useSlot(): SlotContext
 }
-
-declare module 'virtual:clarify/slots' {
-  import type { ComponentType } from 'react'
-
-  export type RuntimeSlotEntry = {
-    plugin: string
-    /** Lazy import factory — yields the default-exported React component. */
-    component: () => Promise<{ default: ComponentType }>
-  }
-
-  export const runtimeSlots: Record<string, RuntimeSlotEntry[]>
-}
 `;
 function generateClarifyEnvDts(_plugins) {
 	return CLARIFY_ENV_TEMPLATE;
@@ -2022,6 +2108,48 @@ async function loadClarifyConfig(root, env) {
 	if (configFile.endsWith(".json")) return loadJsonConfig(configFile);
 	return assertConfigObject((await (0, vite.loadConfigFromFile)(env, configFile, root, "silent"))?.config, configFile);
 }
+//#endregion
+//#region source/core/project-context.ts
+async function resolveProjectContext(options = {}, env = {
+	command: "build",
+	mode: "production"
+}) {
+	const projectRoot = (0, node_path.resolve)(options.projectRoot ?? process.cwd());
+	const initialBuildOptions = resolveBuildOptions(options);
+	const contentRoot = (0, node_path.join)(projectRoot, initialBuildOptions.rootDirectory);
+	const configFilePath = findClarifyConfigFile(projectRoot);
+	const config = configFilePath && (0, node_fs.existsSync)(configFilePath) ? await loadClarifyConfig(projectRoot, env) : {};
+	const mergedOptions = {
+		...config,
+		...options,
+		projectRoot,
+		rootDirectory: initialBuildOptions.rootDirectory,
+		outputDirectory: initialBuildOptions.outputDirectory
+	};
+	const resolvedProjectConfig = resolveProjectConfig(mergedOptions);
+	const resolvedBuildOptions = resolveBuildOptions(mergedOptions);
+	const projectContext = {
+		projectRoot,
+		contentRoot,
+		version: cliPackageVersion,
+		projectConfig: resolvedProjectConfig,
+		generateOptions: resolvedBuildOptions
+	};
+	return {
+		projectRoot,
+		contentRoot,
+		configFilePath,
+		projectConfig: resolvedProjectConfig,
+		buildOptions: resolvedBuildOptions,
+		config,
+		hookContext: {
+			...projectContext,
+			routes: [],
+			navigation: []
+		},
+		projectContext
+	};
+}
 /**
 * File extensions Clarify treats as content files. Kept in sync with the
 * patterns used by route discovery in `parsers/routes.ts` and the OpenAPI
@@ -2038,7 +2166,8 @@ var CONTENT_FILE_EXTENSIONS = [
 /**
 * Build the project-info response payload from the resolved plugin state.
 */
-function buildProjectInfo(projectRoot, contentRoot, projectConfig) {
+function buildProjectInfo(context) {
+	const { projectRoot, contentRoot, projectConfig } = context;
 	const response = {
 		configFilenames: CONFIG_FILENAMES,
 		contentFileExtensions: CONTENT_FILE_EXTENSIONS,
@@ -2055,9 +2184,9 @@ function buildProjectInfo(projectRoot, contentRoot, projectConfig) {
 * Handle a request to the project-info endpoint. Responds to any method
 * (GET is typical) with the JSON payload — there is no request body to parse.
 */
-function handleProjectInfoRequest(_req, res, projectRoot, contentRoot, projectConfig) {
+function handleProjectInfoRequest(_req, res, context) {
 	res.setHeader("Content-Type", "application/json; charset=utf-8");
-	res.end(JSON.stringify(buildProjectInfo(projectRoot, contentRoot, projectConfig)));
+	res.end(JSON.stringify(buildProjectInfo(context)));
 }
 //#endregion
 //#region source/core/site.ts
@@ -2120,16 +2249,18 @@ async function discoverRoutes(root, contentRoot, plugins, ctx) {
 	return [...routesWithAlternates, ...bareRoutes];
 }
 async function resolveClarifySite(options = {}, resolveOptions = {}) {
-	const root = options.projectRoot ?? process.cwd();
-	const projectConfig = resolveProjectConfig(options);
-	const generateOptions = resolveBuildOptions(options);
-	const contentRoot = (0, node_path.join)(root, generateOptions.rootDirectory);
+	const context = await resolveProjectContext(options);
+	const root = context.projectRoot;
+	const projectConfig = context.projectConfig;
+	const generateOptions = context.buildOptions;
+	const contentRoot = context.contentRoot;
 	const plugins = [...createBuiltinPlugins({ htmlShell: resolveOptions.includeHtmlShellPlugin }), ...options.plugins ?? []];
 	const ctx = {
+		...context.hookContext,
+		projectRoot: root,
+		contentRoot,
 		projectConfig,
-		generateOptions,
-		routes: [],
-		navigation: []
+		generateOptions
 	};
 	setProjectContentProcessor(ctx, createProjectContentProcessor(plugins, ctx));
 	let routes = await discoverRoutes(root, contentRoot, plugins, ctx);
@@ -2227,7 +2358,11 @@ function readIndexHtml(outputDirectory) {
 		return;
 	}
 }
-function injectHtmlLocaleAttributes(html, projectConfig, route) {
+function resolveProjectConfigFromContext(contextOrConfig) {
+	return "projectConfig" in contextOrConfig ? contextOrConfig.projectConfig : contextOrConfig;
+}
+function injectHtmlLocaleAttributes(html, contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
 	const localeCode = route?.locale ?? projectConfig.i18n?.defaultLocale;
 	if (!localeCode) return html;
 	const dir = (projectConfig.i18n?.locales.find((locale) => locale.code === localeCode))?.dir;
@@ -2238,7 +2373,8 @@ function injectHtmlLocaleAttributes(html, projectConfig, route) {
 		return `<html${nextAttributes}>`;
 	});
 }
-function routeTitle(projectConfig, route) {
+function routeTitle(contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
 	const title = route?.title?.trim();
 	if (!title || title === projectConfig.title) return projectConfig.title;
 	return `${title} - ${projectConfig.title}`;
@@ -2250,24 +2386,26 @@ function setNamedMeta(html, name, content) {
 	if (metaPattern.test(html)) return html.replace(metaPattern, meta);
 	return html.replace("</head>", `  ${meta}\n  </head>`);
 }
-function canonicalUrl(projectConfig, route) {
+function canonicalUrl(contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
 	if (!projectConfig.siteUrl || !route.alternates || !route.locale) return void 0;
 	const prefixedPath = route.alternates[route.locale];
 	if (!prefixedPath || prefixedPath === route.path) return void 0;
 	return `${projectConfig.siteUrl.replace(/\/+$/, "")}${!projectConfig.routePrefix || projectConfig.routePrefix === "/" ? "" : `/${projectConfig.routePrefix.replace(/^\/+|\/+$/g, "")}`}${prefixedPath}`;
 }
-function injectCanonicalUrl(html, projectConfig, route) {
-	const url = route ? canonicalUrl(projectConfig, route) : void 0;
+function injectCanonicalUrl(html, contextOrConfig, route) {
+	const url = route ? canonicalUrl(contextOrConfig, route) : void 0;
 	html = html.replace(/<link\b[^>]*\brel=["']canonical["'][^>]*\/?>\n?/gi, "");
 	if (!url) return html;
 	return html.replace("</head>", `  <link rel="canonical" href="${escapeHtml(url)}" />\n  </head>`);
 }
-function injectSSRIntoTemplate(template, appHtml, projectConfig, route) {
-	let html = injectHtmlLocaleAttributes(template, projectConfig, route);
-	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(projectConfig, route))}</title>`);
+function injectSSRIntoTemplate(template, appHtml, contextOrConfig, route) {
+	const projectConfig = resolveProjectConfigFromContext(contextOrConfig);
+	let html = injectHtmlLocaleAttributes(template, contextOrConfig, route);
+	html = html.replace(/<title>.*?<\/title>/, `<title>${escapeHtml(routeTitle(contextOrConfig, route))}</title>`);
 	html = setNamedMeta(html, "description", route?.description ?? projectConfig.description);
 	html = setNamedMeta(html, "keywords", route?.keywords?.join(", "));
-	html = injectCanonicalUrl(html, projectConfig, route);
+	html = injectCanonicalUrl(html, contextOrConfig, route);
 	const dataPagefindIgnore = route?.isBareAlias ? " data-pagefind-ignore" : "";
 	html = html.replace(/<div id="root">([\s\S]*?)<\/div>/, `<div id="root"${dataPagefindIgnore}>${appHtml}</div>`);
 	return html;
@@ -2319,12 +2457,12 @@ async function buildSSRBundle(root, ssrEntry, ssrOutDir, plugins) {
 		}
 	});
 }
-async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundlePath, failOnError = true) {
+async function renderSSGRoutes(routes, contextOrConfig, outputDirectory, ssrBundlePath, failOnError = true) {
 	const { render } = await import((0, node_url.pathToFileURL)(ssrBundlePath).href);
 	const template = readIndexHtml(outputDirectory);
 	if (!template) throw new Error(`[clarify] index.html not found in outputDirectory "${outputDirectory}". Make sure Vite build produces it.`);
 	for (const route of routes) try {
-		const finalHtml = injectSSRIntoTemplate(template, await render(route.path), projectConfig, route);
+		const finalHtml = injectSSRIntoTemplate(template, await render(route.path), contextOrConfig, route);
 		for (const outFile of routeOutputFiles(outputDirectory, route)) {
 			(0, node_fs.mkdirSync)((0, node_path.dirname)(outFile), { recursive: true });
 			(0, node_fs.writeFileSync)(outFile, finalHtml, "utf-8");
@@ -2335,6 +2473,33 @@ async function renderSSGRoutes(routes, projectConfig, outputDirectory, ssrBundle
 	}
 }
 //#endregion
+//#region source/core/startup.ts
+function contentDirectoryLabel(projectRoot, contentRoot) {
+	const relativePath = (0, node_path.relative)(projectRoot, contentRoot);
+	return relativePath && relativePath !== "." ? relativePath : "source";
+}
+function contentFileExampleLabel(projectRoot, contentRoot) {
+	const label = contentDirectoryLabel(projectRoot, contentRoot);
+	return label === "." ? "index.mdx" : `${label}/index.mdx`;
+}
+function getStartupHints(options) {
+	const hints = [];
+	if (!options.contentDirExists) {
+		const label = contentDirectoryLabel(options.projectRoot, options.contentRoot);
+		hints.push(`Content directory "${label}" was not found. Create it or pass --content <dir> to point Clarify at a different directory.`);
+	} else if (!options.hasRoutes) {
+		const example = contentFileExampleLabel(options.projectRoot, options.contentRoot);
+		hints.push(`No content pages were found yet. Add ${example} to get started.`);
+	}
+	return hints;
+}
+function logStartupHints(options) {
+	const hints = getStartupHints(options);
+	if (hints.length === 0) return;
+	const message = hints.map((hint) => `[clarify] ${hint}`).join("\n");
+	console.warn(message);
+}
+//#endregion
 //#region source/core/plugin.ts
 function loadVirtualModule(id, modules) {
 	const bareId = stripVirtualPrefix(id);
@@ -2344,13 +2509,23 @@ function clarifyPlugin(options = {}) {
 	const root = (0, node_path.resolve)(options.projectRoot ?? process.cwd());
 	let projectConfig = resolveProjectConfig(options);
 	let generateOptions = resolveBuildOptions(options);
-	const contentRoot = (0, node_path.join)(root, generateOptions.rootDirectory);
+	let contentRoot = (0, node_path.join)(root, generateOptions.rootDirectory);
+	let runtimeContext = {
+		projectRoot: root,
+		contentRoot,
+		projectConfig,
+		generateOptions,
+		version: cliPackageVersion
+	};
 	const configFilePath = findClarifyConfigFile(root);
 	let routes = [];
 	let clarifyPlugins = [...createBuiltinPlugins(), ...options.plugins ?? []];
 	const ctx = {
+		projectRoot: root,
+		contentRoot,
 		projectConfig,
 		generateOptions,
+		version: cliPackageVersion,
 		routes,
 		navigation: []
 	};
@@ -2361,11 +2536,22 @@ function clarifyPlugin(options = {}) {
 		const site = await resolveClarifySite(overrides ?? options);
 		projectConfig = site.projectConfig;
 		generateOptions = site.generateOptions;
+		contentRoot = (0, node_path.join)(root, generateOptions.rootDirectory);
+		runtimeContext = {
+			projectRoot: root,
+			contentRoot,
+			projectConfig,
+			generateOptions,
+			version: cliPackageVersion
+		};
 		routes = site.routes;
 		resolvedNavigation = site.navigation;
 		clarifyPlugins = site.plugins;
+		ctx.projectRoot = root;
+		ctx.contentRoot = contentRoot;
 		ctx.projectConfig = projectConfig;
 		ctx.generateOptions = generateOptions;
+		ctx.version = cliPackageVersion;
 		ctx.routes = routes;
 		ctx.navigation = resolvedNavigation;
 	}
@@ -2376,7 +2562,8 @@ function clarifyPlugin(options = {}) {
 			routes,
 			navigation: resolvedNavigation,
 			plugins: clarifyPlugins,
-			themeEditor: viteConfig.command === "serve" || projectConfig.theme.editor
+			themeEditor: viteConfig.command === "serve" || projectConfig.theme.editor,
+			version: ctx.version
 		});
 		virtualModules = await runHooks(clarifyPlugins, "modules:before", virtualModules, ctx);
 	}
@@ -2424,6 +2611,12 @@ function clarifyPlugin(options = {}) {
 			name: "clarify:core",
 			async config() {
 				await resolveRoutesAndSpecs();
+				logStartupHints({
+					projectRoot: root,
+					contentRoot,
+					contentDirExists: (0, node_fs.existsSync)(contentRoot),
+					hasRoutes: routes.length > 0
+				});
 				return {
 					base: projectConfig.assetPrefix,
 					build: {
@@ -2443,14 +2636,23 @@ function clarifyPlugin(options = {}) {
 			async handleHotUpdate(ctx) {
 				const changedFile = (0, node_path.isAbsolute)(ctx.file) ? ctx.file : (0, node_path.join)(root, ctx.file);
 				if (configFilePath && changedFile === configFilePath) {
-					await resolveRoutesAndSpecs({
-						...await loadClarifyConfig(root, {
-							command: "serve",
-							mode: viteConfig.mode
-						}),
-						projectRoot: options.projectRoot,
+					const newContext = await resolveProjectContext({
+						...options,
+						projectRoot: root,
 						rootDirectory: options.rootDirectory,
 						outputDirectory: options.outputDirectory
+					}, {
+						command: "serve",
+						mode: viteConfig.mode
+					});
+					projectConfig = newContext.projectConfig;
+					generateOptions = newContext.buildOptions;
+					contentRoot = newContext.contentRoot;
+					await resolveRoutesAndSpecs({
+						...newContext.config,
+						projectRoot: newContext.projectRoot,
+						rootDirectory: newContext.buildOptions.rootDirectory,
+						outputDirectory: newContext.buildOptions.outputDirectory
 					});
 					await rebuildVirtualModules();
 					invalidateVirtualModules(ctx.server);
@@ -2483,12 +2685,13 @@ function clarifyPlugin(options = {}) {
 				server.watcher.add(contentRoot);
 				if (configFilePath) server.watcher.add(configFilePath);
 				server.middlewares.use((req, res, next) => {
-					if (req.url === "/dev/query-preview-route" && req.method === "POST") return handleDevRouteRequest(req, res, routes, projectConfig, contentRoot);
-					if (req.url === "/dev/project-info" && (req.method === "GET" || req.method === "HEAD")) return handleProjectInfoRequest(req, res, root, contentRoot, projectConfig);
+					if (req.url === "/dev/query-preview-route" && req.method === "POST") return handleDevRouteRequest(req, res, routes, runtimeContext);
+					if (req.url === "/dev/project-info" && (req.method === "GET" || req.method === "HEAD")) return handleProjectInfoRequest(req, res, runtimeContext);
 					next();
 				});
 				const handleContentTreeChange = async (filePath) => {
-					const relativeContentFile = (0, node_path.relative)(contentRoot, (0, node_path.isAbsolute)(filePath) ? filePath : (0, node_path.join)(root, filePath));
+					const changedFile = (0, node_path.isAbsolute)(filePath) ? filePath : (0, node_path.join)(root, filePath);
+					const relativeContentFile = (0, node_path.relative)(contentRoot, changedFile);
 					if (!(relativeContentFile && !relativeContentFile.startsWith("..") && !(0, node_path.isAbsolute)(relativeContentFile))) return;
 					await refreshDevServer(server);
 				};
@@ -2552,7 +2755,7 @@ function clarifyPlugin(options = {}) {
 						mdx
 					]);
 					const ssrBundlePath = (0, node_path.join)(ssrOutputDir, "entry-server.js");
-					await renderSSGRoutes(routes, projectConfig, outputDir, ssrBundlePath, generateOptions.ssg.failOnError);
+					await renderSSGRoutes(routes, runtimeContext, outputDir, ssrBundlePath, generateOptions.ssg.failOnError);
 				} catch (err) {
 					console.error("[clarify] SSG failed:", err);
 					if (generateOptions.ssg.failOnError) throw err;
@@ -2574,6 +2777,18 @@ Object.defineProperty(exports, "clarifyPlugin", {
 		return clarifyPlugin;
 	}
 });
+Object.defineProperty(exports, "cliPackageVersion", {
+	enumerable: true,
+	get: function() {
+		return cliPackageVersion;
+	}
+});
+Object.defineProperty(exports, "cliPackageVersionWithCaret", {
+	enumerable: true,
+	get: function() {
+		return cliPackageVersionWithCaret;
+	}
+});
 Object.defineProperty(exports, "createClarifyRuntimeAliases", {
 	enumerable: true,
 	get: function() {
@@ -2592,17 +2807,17 @@ Object.defineProperty(exports, "defineConfig", {
 		return defineConfig;
 	}
 });
-Object.defineProperty(exports, "loadClarifyConfig", {
+Object.defineProperty(exports, "resolveClarifySite", {
 	enumerable: true,
 	get: function() {
-		return loadClarifyConfig;
+		return resolveClarifySite;
 	}
 });
-Object.defineProperty(exports, "resolveClarifySite", {
+Object.defineProperty(exports, "resolveProjectContext", {
 	enumerable: true,
 	get: function() {
-		return resolveClarifySite;
+		return resolveProjectContext;
 	}
 });
 
-//# sourceMappingURL=plugin-BUFe4vEb.cjs.map
+//# sourceMappingURL=plugin-Etn8ZfYN.cjs.map