@farming-labs/docs 0.0.37 → 0.0.43

package/dist/cli/index.d.mts

@@ -1,5 +1,5 @@
 //#region src/cli/index.d.ts
 /** Parse flags like --template next, --name my-docs, --theme darksharp, --entry docs, --framework astro (exported for tests). */
-declare function parseFlags(argv: string[]): Record<string, string | undefined>;
+declare function parseFlags(argv: string[]): Record<string, string | boolean | undefined>;
 //#endregion
 export { parseFlags };

package/dist/cli/index.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import pc from "picocolors";
+import fs from "node:fs";
 import path from "node:path";
+import pc from "picocolors";
 import * as p from "@clack/prompts";
-import fs from "node:fs";
 import { execSync, spawn } from "node:child_process";
 
 //#region src/cli/utils.ts
@@ -273,6 +273,11 @@ function renderI18nConfig(cfg, indent = "  ") {
 	if (!i18n || i18n.locales.length === 0) return "";
 	return `${indent}i18n: {\n${indent}  locales: [${i18n.locales.map((locale) => `"${locale}"`).join(", ")}],\n${indent}  defaultLocale: "${i18n.defaultLocale}",\n${indent}},\n`;
 }
+function renderApiReferenceConfig(cfg, indent = "  ") {
+	const apiReference = cfg.apiReference;
+	if (!apiReference) return "";
+	return `${indent}apiReference: {\n${indent}  enabled: true,\n${indent}  path: "${apiReference.path}",\n${indent}  routeRoot: "${apiReference.routeRoot}",\n${indent}},\n`;
+}
 function toLocaleImportName(locale) {
 	return `LocalePage_${locale.replace(/[^a-zA-Z0-9_$]/g, "_")}`;
 }
@@ -329,6 +334,10 @@ function nextDocsLayoutConfigImport(useAlias, nextAppDir = "app") {
 	if (useAlias) return "@/docs.config";
 	return nextAppDir === "src/app" ? "../../../docs.config" : "../../docs.config";
 }
+function nextApiReferenceConfigImport(useAlias, nextAppDir = "app", filePath) {
+	if (useAlias) return "@/docs.config";
+	return relativeImport(filePath, "docs.config.ts");
+}
 /** Config import for SvelteKit src/lib/docs.server.ts → src/lib/docs.config */
 function svelteServerConfigImport(useAlias) {
 	return useAlias ? "$lib/docs.config" : "./docs.config";
@@ -365,7 +374,7 @@ import { ${exportName} } from "${cfg.useAlias ? "@/themes/" + cfg.customThemeNam
 
 export default defineDocs({
   entry: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${exportName}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${exportName}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -385,7 +394,7 @@ import { ${t.factory} } from "${t.nextImport}";
 
 export default defineDocs({
   entry: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${t.factory}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${t.factory}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -523,6 +532,17 @@ export default function Layout({ children }: { children: React.ReactNode }) {
 }
 `;
 }
+function nextApiReferenceRouteTemplate(cfg, filePath) {
+	const appDir = cfg.nextAppDir ?? "app";
+	return `
+import docsConfig from "${nextApiReferenceConfigImport(cfg.useAlias, appDir, filePath)}";
+import { createNextApiReference } from "@farming-labs/next/api-reference";
+
+export const GET = createNextApiReference(docsConfig);
+
+export const revalidate = false;
+`;
+}
 function nextLocaleDocPageTemplate(defaultLocale) {
 	return `\
 import type { ComponentType } from "react";
@@ -789,7 +809,7 @@ import { ${exportName} } from "./themes/${cfg.customThemeName.replace(/\.ts$/i,
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  theme: ${exportName}({
+  ${renderApiReferenceConfig(cfg)}  theme: ${exportName}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -817,7 +837,7 @@ import { ${t.factory} } from "${t.nextImport}";
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  theme: ${t.factory}({
+  ${renderApiReferenceConfig(cfg)}  theme: ${t.factory}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -948,6 +968,24 @@ export const Route = createFileRoute("/api/docs")({
 });
 `;
 }
+function tanstackApiReferenceRouteTemplate(opts) {
+	const routePath = `/${opts.apiReferencePath}${opts.catchAll ? "/$" : "/"}`;
+	return `\
+import { createFileRoute } from "@tanstack/react-router";
+import { createTanstackApiReference } from "@farming-labs/tanstack-start/api-reference";
+import docsConfig from "${tanstackDocsConfigImport(opts.filePath)}";
+
+const handler = createTanstackApiReference(docsConfig);
+
+export const Route = createFileRoute("${routePath}")({
+  server: {
+    handlers: {
+      GET: handler,
+    },
+  },
+});
+`;
+}
 function tanstackRootRouteTemplate(globalCssRelPath) {
 	return `\
 import appCss from "${relativeAssetPath("src/routes/__root.tsx", globalCssRelPath)}?url";
@@ -1197,7 +1235,7 @@ import { ${exportName} } from "${"../../themes/" + cfg.customThemeName.replace(/
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${exportName}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${exportName}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1225,7 +1263,7 @@ import { ${t.factory} } from "${t.svelteImport}";
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${t.factory}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${t.factory}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1294,6 +1332,14 @@ function svelteDocsPageTemplate(cfg) {
 <DocsContent {data} {config} />
 `;
 }
+function svelteApiReferenceRouteTemplate(filePath, useAlias) {
+	return `\
+import { createSvelteApiReference } from "@farming-labs/svelte/api-reference";
+import config from "${useAlias ? "$lib/docs.config" : relativeImport(filePath, "src/lib/docs.config.ts")}";
+
+export const GET = createSvelteApiReference(config);
+`;
+}
 function svelteRootLayoutTemplate(globalCssRelPath) {
 	let cssImport;
 	if (globalCssRelPath.startsWith("src/")) cssImport = "./" + globalCssRelPath.slice(4);
@@ -1507,7 +1553,7 @@ import { ${exportName} } from "${"../../themes/" + cfg.customThemeName.replace(/
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${exportName}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${exportName}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1535,7 +1581,7 @@ import { ${t.factory} } from "${t.astroImport}";
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${t.factory}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${t.factory}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1676,6 +1722,14 @@ export const POST: APIRoute = async ({ request }) => {
 };
 `;
 }
+function astroApiReferenceRouteTemplate(filePath) {
+	return `\
+import { createAstroApiReference } from "@farming-labs/astro/api-reference";
+import config from "${relativeImport(filePath, "src/lib/docs.config.ts")}";
+
+export const GET = createAstroApiReference(config);
+`;
+}
 function astroGlobalCssTemplate(theme, customThemeName, globalCssRelPath) {
 	if (theme === "custom" && customThemeName && globalCssRelPath) return `\
 @import "${getCustomThemeCssImportPath(globalCssRelPath, customThemeName.replace(/\.css$/i, ""))}";
@@ -1863,7 +1917,7 @@ import { ${exportName} } from "${cfg.useAlias ? "~/themes/" + cfg.customThemeNam
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${exportName}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${exportName}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1891,7 +1945,7 @@ import { ${t.factory} } from "${t.nuxtImport}";
 export default defineDocs({
   entry: "${cfg.entry}",
   contentDir: "${cfg.entry}",
-  ${renderI18nConfig(cfg)}  theme: ${t.factory}({
+  ${renderI18nConfig(cfg)}${renderApiReferenceConfig(cfg)}  theme: ${t.factory}({
     ui: {
       colors: { primary: "#6366f1" },
     },
@@ -1973,6 +2027,14 @@ export default defineEventHandler(async (event) => {
 });
 `;
 }
+function nuxtServerApiReferenceRouteTemplate(filePath, useAlias) {
+	return `\
+import { defineApiReferenceHandler } from "@farming-labs/nuxt/api-reference";
+import config from "${useAlias ? "~/docs.config" : relativeImport(filePath, "docs.config.ts")}";
+
+export default defineApiReferenceHandler(config);
+`;
+}
 function nuxtDocsPageTemplate(cfg) {
 	return `\
 <script setup lang="ts">
@@ -2295,6 +2357,55 @@ function normalizeEntryPath(entry) {
 function getTanstackDocsRouteDir(entry) {
 	return path.posix.join("src/routes", normalizeEntryPath(entry));
 }
+function normalizeApiRouteRoot(routeRoot) {
+	return routeRoot.replace(/^\/+|\/+$/g, "");
+}
+function detectApiRouteRoot(cwd, framework, nextAppDir = "app") {
+	const defaultRoot = "api";
+	const detectFromRecursiveRouteFiles = (baseDir, matcher) => {
+		if (!fs.existsSync(baseDir)) return null;
+		const candidates = /* @__PURE__ */ new Map();
+		const walk = (dir, prefix = "") => {
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+				const fullPath = path.join(dir, entry.name);
+				if (entry.isDirectory()) {
+					walk(fullPath, relativePath);
+					continue;
+				}
+				if (!matcher(entry, relativePath)) continue;
+				const [topLevel] = relativePath.split("/");
+				if (!topLevel) continue;
+				candidates.set(topLevel, (candidates.get(topLevel) ?? 0) + 1);
+			}
+		};
+		walk(baseDir);
+		return Array.from(candidates.entries()).sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+	};
+	if (framework === "nextjs") {
+		const appRoot = path.join(cwd, nextAppDir);
+		if (fs.existsSync(path.join(appRoot, defaultRoot))) return defaultRoot;
+		return detectFromRecursiveRouteFiles(appRoot, (_entry, relativePath) => /\/?route\.(?:[cm]?[jt]sx?)$/i.test(relativePath)) ?? defaultRoot;
+	}
+	if (framework === "tanstack-start") {
+		const routesRoot = path.join(cwd, "src/routes");
+		if (fs.existsSync(path.join(routesRoot, defaultRoot))) return defaultRoot;
+		return detectFromRecursiveRouteFiles(routesRoot, (_entry, relativePath) => /(?:^|\/)[^/]+\.(?:[cm]?[jt]sx?)$/i.test(relativePath)) ?? defaultRoot;
+	}
+	if (framework === "sveltekit") {
+		const routesRoot = path.join(cwd, "src/routes");
+		if (fs.existsSync(path.join(routesRoot, defaultRoot))) return defaultRoot;
+		return detectFromRecursiveRouteFiles(routesRoot, (_entry, relativePath) => /\/?\+server\.(?:[cm]?[jt]s)$/i.test(relativePath)) ?? defaultRoot;
+	}
+	if (framework === "astro") {
+		const pagesRoot = path.join(cwd, "src/pages");
+		if (fs.existsSync(path.join(pagesRoot, defaultRoot))) return defaultRoot;
+		return detectFromRecursiveRouteFiles(pagesRoot, (entry, relativePath) => /\.(?:[cm]?[jt]s)$/i.test(relativePath) && !relativePath.endsWith(".d.ts") && entry.isFile()) ?? defaultRoot;
+	}
+	const serverRoot = path.join(cwd, "server");
+	if (fs.existsSync(path.join(serverRoot, defaultRoot))) return defaultRoot;
+	return detectFromRecursiveRouteFiles(serverRoot, (entry, relativePath) => /\.(?:[cm]?[jt]s)$/i.test(relativePath) && !relativePath.endsWith(".d.ts") && entry.isFile()) ?? defaultRoot;
+}
 async function init(options = {}) {
 	const cwd = process.cwd();
 	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
@@ -2499,54 +2610,66 @@ async function init(options = {}) {
 			nextAppDir = useSrcApp ? "src/app" : "app";
 		}
 	}
-	const theme = await p.select({
-		message: "Which theme would you like to use?",
-		options: [
-			{
-				value: "fumadocs",
-				label: "Fumadocs (Default)",
-				hint: "Clean, modern docs theme with sidebar, search, and dark mode"
-			},
-			{
-				value: "darksharp",
-				label: "Darksharp",
-				hint: "All-black, sharp edges, zero-radius look"
-			},
-			{
-				value: "pixel-border",
-				label: "Pixel Border",
-				hint: "Rounded borders, pixel-perfect spacing, refined sidebar"
-			},
-			{
-				value: "colorful",
-				label: "Colorful",
-				hint: "Fumadocs-style neutral theme with description support"
-			},
-			{
-				value: "darkbold",
-				label: "DarkBold",
-				hint: "Pure monochrome, Geist typography, clean minimalism"
-			},
-			{
-				value: "shiny",
-				label: "Shiny",
-				hint: "Glossy, modern look with subtle shimmer effects"
-			},
-			{
-				value: "greentree",
-				label: "GreenTree",
-				hint: "Emerald green accent, Inter font, Mintlify-inspired"
-			},
-			{
-				value: "custom",
-				label: "Create your own theme",
-				hint: "Scaffold a new theme file + CSS in themes/ (name asked next)"
-			}
-		]
-	});
-	if (p.isCancel(theme)) {
-		p.outro(pc.red("Init cancelled."));
-		process.exit(0);
+	const themeOptions = [
+		{
+			value: "fumadocs",
+			label: "Fumadocs (Default)",
+			hint: "Clean, modern docs theme with sidebar, search, and dark mode"
+		},
+		{
+			value: "darksharp",
+			label: "Darksharp",
+			hint: "All-black, sharp edges, zero-radius look"
+		},
+		{
+			value: "pixel-border",
+			label: "Pixel Border",
+			hint: "Rounded borders, pixel-perfect spacing, refined sidebar"
+		},
+		{
+			value: "colorful",
+			label: "Colorful",
+			hint: "Fumadocs-style neutral theme with description support"
+		},
+		{
+			value: "darkbold",
+			label: "DarkBold",
+			hint: "Pure monochrome, Geist typography, clean minimalism"
+		},
+		{
+			value: "shiny",
+			label: "Shiny",
+			hint: "Glossy, modern look with subtle shimmer effects"
+		},
+		{
+			value: "greentree",
+			label: "GreenTree",
+			hint: "Emerald green accent, Inter font, Mintlify-inspired"
+		},
+		{
+			value: "custom",
+			label: "Create your own theme",
+			hint: "Scaffold a new theme file + CSS in themes/ (name asked next)"
+		}
+	];
+	const themeValues = new Set(themeOptions.map((option) => option.value));
+	let theme;
+	if (options.theme) {
+		if (!themeValues.has(options.theme)) {
+			p.log.error(`Invalid ${pc.cyan("--theme")}. Use one of: ${themeOptions.map((option) => pc.cyan(option.value)).join(", ")}`);
+			process.exit(1);
+		}
+		theme = options.theme;
+	} else {
+		const themeAnswer = await p.select({
+			message: "Which theme would you like to use?",
+			options: themeOptions
+		});
+		if (p.isCancel(themeAnswer)) {
+			p.outro(pc.red("Init cancelled."));
+			process.exit(0);
+		}
+		theme = themeAnswer;
 	}
 	const defaultThemeName = "my-theme";
 	let customThemeName;
@@ -2609,21 +2732,84 @@ async function init(options = {}) {
 		astroAdapter = adapter;
 	}
 	const defaultEntry = "docs";
-	const entry = await p.text({
-		message: "Where should your docs live?",
-		placeholder: defaultEntry,
-		defaultValue: defaultEntry,
-		validate: (value) => {
-			const v = (value ?? "").trim();
-			if (v.startsWith("/")) return "Use a relative path (no leading /)";
-			if (v.includes(" ")) return "Path cannot contain spaces";
+	let entryPath;
+	if (options.entry) {
+		const normalizedEntry = options.entry.trim();
+		if (normalizedEntry.startsWith("/")) {
+			p.log.error("Use a relative path for --entry (no leading /)");
+			process.exit(1);
 		}
-	});
-	if (p.isCancel(entry)) {
-		p.outro(pc.red("Init cancelled."));
-		process.exit(0);
+		if (normalizedEntry.includes(" ")) {
+			p.log.error("Path passed to --entry cannot contain spaces");
+			process.exit(1);
+		}
+		entryPath = normalizedEntry || defaultEntry;
+	} else {
+		const entry = await p.text({
+			message: "Where should your docs live?",
+			placeholder: defaultEntry,
+			defaultValue: defaultEntry,
+			validate: (value) => {
+				const v = (value ?? "").trim();
+				if (v.startsWith("/")) return "Use a relative path (no leading /)";
+				if (v.includes(" ")) return "Path cannot contain spaces";
+			}
+		});
+		if (p.isCancel(entry)) {
+			p.outro(pc.red("Init cancelled."));
+			process.exit(0);
+		}
+		entryPath = entry.trim() || defaultEntry;
+	}
+	const defaultApiRouteRoot = normalizeApiRouteRoot(options.apiRouteRoot?.trim() || detectApiRouteRoot(cwd, framework, nextAppDir));
+	let apiReferenceConfig;
+	let enableApiReference;
+	if (typeof options.apiReference === "boolean") enableApiReference = options.apiReference;
+	else if (typeof options.apiRouteRoot === "string" && options.apiRouteRoot.trim()) enableApiReference = true;
+	else {
+		const apiReferenceAnswer = await p.confirm({
+			message: "Do you want to scaffold API reference support?",
+			initialValue: false
+		});
+		if (p.isCancel(apiReferenceAnswer)) {
+			p.outro(pc.red("Init cancelled."));
+			process.exit(0);
+		}
+		enableApiReference = apiReferenceAnswer;
+	}
+	if (enableApiReference) {
+		let routeRoot = options.apiRouteRoot?.trim();
+		if (!routeRoot) {
+			const routeRootAnswer = await p.text({
+				message: "API route root to scan?",
+				placeholder: defaultApiRouteRoot,
+				defaultValue: defaultApiRouteRoot,
+				validate: (value) => {
+					const normalizedValue = normalizeApiRouteRoot((value ?? "").trim());
+					if (!normalizedValue) return "Route root cannot be empty";
+					if (normalizedValue.includes(" ")) return "Route root cannot contain spaces";
+				}
+			});
+			if (p.isCancel(routeRootAnswer)) {
+				p.outro(pc.red("Init cancelled."));
+				process.exit(0);
+			}
+			routeRoot = routeRootAnswer.trim() || defaultApiRouteRoot;
+		}
+		const normalizedRouteRoot = normalizeApiRouteRoot(routeRoot);
+		if (!normalizedRouteRoot) {
+			p.log.error("Route root cannot be empty");
+			process.exit(1);
+		}
+		if (normalizedRouteRoot.includes(" ")) {
+			p.log.error("Route root cannot contain spaces");
+			process.exit(1);
+		}
+		apiReferenceConfig = {
+			path: "api-reference",
+			routeRoot: normalizedRouteRoot
+		};
 	}
-	const entryPath = entry.trim() || defaultEntry;
 	let docsI18n;
 	if (framework === "tanstack-start") p.log.info("Skipping i18n scaffold for TanStack Start. Configure localized routes manually if needed.");
 	else {
@@ -2733,6 +2919,7 @@ async function init(options = {}) {
 		useAlias,
 		astroAdapter,
 		i18n: docsI18n,
+		apiReference: apiReferenceConfig,
 		...framework === "nextjs" && { nextAppDir }
 	};
 	const s = p.spinner();
@@ -2929,6 +3116,10 @@ function scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written) {
 		} else skipped.push(globalCssRelPath + " (already configured)");
 	} else write(globalCssRelPath, globalCssTemplate(cfg.theme, cfg.customThemeName, globalCssRelPath));
 	write(`${appDir}/${cfg.entry}/layout.tsx`, docsLayoutTemplate(cfg));
+	if (cfg.apiReference) {
+		const apiReferenceRoute = `${appDir}/${cfg.apiReference.path}/[[...slug]]/route.ts`;
+		write(apiReferenceRoute, nextApiReferenceRouteTemplate(cfg, apiReferenceRoute));
+	}
 	write("postcss.config.mjs", postcssConfigTemplate());
 	if (!fileExists(path.join(cwd, "tsconfig.json"))) write("tsconfig.json", tsconfigTemplate(cfg.useAlias));
 	if (cfg.i18n?.locales.length) {
@@ -3001,6 +3192,22 @@ function scaffoldTanstackStart(cwd, cfg, globalCssRelPath, write, skipped, writt
 		projectName: cfg.projectName
 	}));
 	write(apiRoute, tanstackApiDocsRouteTemplate(cfg.useAlias, apiRoute));
+	if (cfg.apiReference) {
+		const apiReferenceIndexRoute = `src/routes/${cfg.apiReference.path}.index.ts`;
+		const apiReferenceCatchAllRoute = `src/routes/${cfg.apiReference.path}.$.ts`;
+		write(apiReferenceIndexRoute, tanstackApiReferenceRouteTemplate({
+			filePath: apiReferenceIndexRoute,
+			useAlias: cfg.useAlias,
+			apiReferencePath: cfg.apiReference.path,
+			catchAll: false
+		}));
+		write(apiReferenceCatchAllRoute, tanstackApiReferenceRouteTemplate({
+			filePath: apiReferenceCatchAllRoute,
+			useAlias: cfg.useAlias,
+			apiReferencePath: cfg.apiReference.path,
+			catchAll: true
+		}));
+	}
 	const rootRoutePath = path.join(cwd, "src/routes/__root.tsx");
 	const existingRootRoute = readFileSafe(rootRoutePath);
 	if (!existingRootRoute) write("src/routes/__root.tsx", tanstackRootRouteTemplate(globalCssRelPath), true);
@@ -3049,6 +3256,12 @@ function scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written)
 	write(`src/routes/${cfg.entry}/+layout.server.js`, svelteDocsLayoutServerTemplate(cfg));
 	write(`src/routes/${cfg.entry}/[...slug]/+page.svelte`, svelteDocsPageTemplate(cfg));
 	if (cfg.i18n?.locales.length) write(`src/routes/${cfg.entry}/+page.svelte`, svelteDocsPageTemplate(cfg));
+	if (cfg.apiReference) {
+		const apiReferenceIndexRoute = `src/routes/${cfg.apiReference.path}/+server.ts`;
+		const apiReferenceCatchAllRoute = `src/routes/${cfg.apiReference.path}/[...slug]/+server.ts`;
+		write(apiReferenceIndexRoute, svelteApiReferenceRouteTemplate(apiReferenceIndexRoute, cfg.useAlias));
+		write(apiReferenceCatchAllRoute, svelteApiReferenceRouteTemplate(apiReferenceCatchAllRoute, cfg.useAlias));
+	}
 	if (!readFileSafe(path.join(cwd, "src/routes/+layout.svelte"))) write("src/routes/+layout.svelte", svelteRootLayoutTemplate(globalCssRelPath));
 	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
 	const existingGlobalCss = readFileSafe(globalCssAbsPath);
@@ -3087,6 +3300,12 @@ function scaffoldAstro(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	write(`src/pages/${cfg.entry}/index.astro`, astroDocsIndexTemplate(cfg));
 	write(`src/pages/${cfg.entry}/[...slug].astro`, astroDocsPageTemplate(cfg));
 	write(`src/pages/api/${cfg.entry}.ts`, astroApiRouteTemplate(cfg));
+	if (cfg.apiReference) {
+		const apiReferenceIndexRoute = `src/pages/${cfg.apiReference.path}/index.ts`;
+		const apiReferenceCatchAllRoute = `src/pages/${cfg.apiReference.path}/[...slug].ts`;
+		write(apiReferenceIndexRoute, astroApiReferenceRouteTemplate(apiReferenceIndexRoute));
+		write(apiReferenceCatchAllRoute, astroApiReferenceRouteTemplate(apiReferenceCatchAllRoute));
+	}
 	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
 	const existingGlobalCss = readFileSafe(globalCssAbsPath);
 	const cssTheme = {
@@ -3124,6 +3343,12 @@ function scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written) {
 	write("server/api/docs.post.ts", nuxtServerApiDocsPostTemplate());
 	write("server/api/docs/load.get.ts", nuxtServerApiDocsLoadTemplate());
 	write(`pages/${cfg.entry}/[[...slug]].vue`, nuxtDocsPageTemplate(cfg));
+	if (cfg.apiReference) {
+		const apiReferenceIndexRoute = `server/routes/${cfg.apiReference.path}/index.ts`;
+		const apiReferenceCatchAllRoute = `server/routes/${cfg.apiReference.path}/[...slug].ts`;
+		write(apiReferenceIndexRoute, nuxtServerApiReferenceRouteTemplate(apiReferenceIndexRoute, cfg.useAlias));
+		write(apiReferenceCatchAllRoute, nuxtServerApiReferenceRouteTemplate(apiReferenceCatchAllRoute, cfg.useAlias));
+	}
 	path.join(cwd, "nuxt.config.ts");
 	if (!fileExists(path.join(cwd, "nuxt.config.ts")) && !fileExists(path.join(cwd, "nuxt.config.js"))) write("nuxt.config.ts", nuxtConfigTemplate(cfg));
 	const cssTheme = {
@@ -3156,10 +3381,11 @@ function scaffoldNuxt(cwd, cfg, globalCssRelPath, write, skipped, written) {
 //#region src/cli/upgrade.ts
 /**
 * Upgrade @farming-labs/* packages to latest.
-* Detects framework from package.json by default, or use --framework (next, nuxt, sveltekit, astro).
+* Detects framework from package.json by default, or use --framework (next, tanstack-start, nuxt, sveltekit, astro).
 */
 const PRESETS = [
 	"next",
+	"tanstack-start",
 	"nuxt",
 	"sveltekit",
 	"astro"
@@ -3170,6 +3396,11 @@ const PACKAGES_BY_FRAMEWORK = {
 		"@farming-labs/theme",
 		"@farming-labs/next"
 	],
+	"tanstack-start": [
+		"@farming-labs/docs",
+		"@farming-labs/theme",
+		"@farming-labs/tanstack-start"
+	],
 	nuxt: [
 		"@farming-labs/docs",
 		"@farming-labs/nuxt",
@@ -3223,11 +3454,7 @@ async function upgrade(options = {}) {
 	} else {
 		const detected = detectFramework(cwd);
 		if (!detected) {
-			p.log.error("Could not detect a supported framework (Next.js, Nuxt, SvelteKit, Astro). Use " + pc.cyan("--framework <next|nuxt|sveltekit|astro>") + " to specify.");
-			process.exit(1);
-		}
-		if (detected === "tanstack-start") {
-			p.log.error("TanStack Start is supported by " + pc.cyan("init") + " but not by " + pc.cyan("upgrade") + " yet. Upgrade the docs packages manually for now.");
+			p.log.error("Could not detect a supported framework (Next.js, TanStack Start, Nuxt, SvelteKit, Astro). Use " + pc.cyan("--framework <next|tanstack-start|nuxt|sveltekit|astro>") + " to specify.");
 			process.exit(1);
 		}
 		framework = detected;
@@ -3289,29 +3516,36 @@ const command = args[0];
 /** Parse flags like --template next, --name my-docs, --theme darksharp, --entry docs, --framework astro (exported for tests). */
 function parseFlags(argv) {
 	const flags = {};
+	const booleanFlags = new Set(["api-reference"]);
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (arg.startsWith("--") && arg.includes("=")) {
 			const [key, value] = arg.slice(2).split("=");
-			flags[key] = value;
+			if (key.startsWith("no-")) flags[key.slice(3)] = false;
+			else if (booleanFlags.has(key) && value === "true") flags[key] = true;
+			else if (booleanFlags.has(key) && value === "false") flags[key] = false;
+			else flags[key] = value;
 		} else if (arg.startsWith("--") && argv[i + 1] && !argv[i + 1].startsWith("--")) {
 			flags[arg.slice(2)] = argv[i + 1];
 			i++;
-		}
+		} else if (arg.startsWith("--no-")) flags[arg.slice(5)] = false;
+		else if (arg.startsWith("--") && booleanFlags.has(arg.slice(2))) flags[arg.slice(2)] = true;
 	}
 	return flags;
 }
 async function main() {
 	const flags = parseFlags(args);
 	const initOptions = {
-		template: flags.template,
-		name: flags.name,
-		theme: flags.theme,
-		entry: flags.entry
+		template: typeof flags.template === "string" ? flags.template : void 0,
+		name: typeof flags.name === "string" ? flags.name : void 0,
+		theme: typeof flags.theme === "string" ? flags.theme : void 0,
+		entry: typeof flags.entry === "string" ? flags.entry : void 0,
+		apiReference: typeof flags["api-reference"] === "boolean" ? flags["api-reference"] : void 0,
+		apiRouteRoot: typeof flags["api-route-root"] === "string" ? flags["api-route-root"] : void 0
 	};
 	if (!command || command === "init") await init(initOptions);
 	else if (command === "upgrade") await upgrade({
-		framework: flags.framework ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0),
+		framework: (typeof flags.framework === "string" ? flags.framework : void 0) ?? (args[1] && !args[1].startsWith("--") ? args[1] : void 0),
 		tag: args.includes("--beta") ? "beta" : "latest"
 	});
 	else if (command === "--help" || command === "-h") printHelp();
@@ -3335,16 +3569,19 @@ ${pc.dim("Commands:")}
   ${pc.cyan("upgrade")}  Upgrade @farming-labs/* packages to latest (auto-detect or use --framework)
 
 ${pc.dim("Supported frameworks:")}
-  Next.js, SvelteKit, Astro, Nuxt
+  Next.js, TanStack Start, SvelteKit, Astro, Nuxt
 
 ${pc.dim("Options for init:")}
   ${pc.cyan("--template <name>")}  Bootstrap a project (${pc.dim("next")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}, ${pc.dim("tanstack-start")}); use with ${pc.cyan("--name")}
   ${pc.cyan("--name <project>")}  Project folder name when using ${pc.cyan("--template")}; prompt if omitted (e.g. ${pc.dim("my-docs")})
   ${pc.cyan("--theme <name>")}     Skip theme prompt (e.g. ${pc.dim("darksharp")}, ${pc.dim("greentree")})
   ${pc.cyan("--entry <path>")}     Skip entry path prompt (e.g. ${pc.dim("docs")})
+  ${pc.cyan("--api-reference")}    Scaffold API reference support during ${pc.cyan("init")}
+  ${pc.cyan("--no-api-reference")} Skip API reference scaffold during ${pc.cyan("init")}
+  ${pc.cyan("--api-route-root <path>")}  Override the API route root scanned by ${pc.cyan("apiReference.routeRoot")} (e.g. ${pc.dim("api")}, ${pc.dim("internal-api")})
 
 ${pc.dim("Options for upgrade:")}
-  ${pc.cyan("--framework <name>")}  Explicit framework (${pc.dim("next")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}); omit to auto-detect
+  ${pc.cyan("--framework <name>")}  Explicit framework (${pc.dim("next")}, ${pc.dim("tanstack-start")}, ${pc.dim("nuxt")}, ${pc.dim("sveltekit")}, ${pc.dim("astro")}); omit to auto-detect
   ${pc.cyan("--latest")}            Install latest stable (default)
   ${pc.cyan("--beta")}             Install beta versions