@farming-labs/docs 0.0.2-beta.3 → 0.0.2-beta.4

package/dist/cli/index.mjs

@@ -10,10 +10,12 @@ function detectFramework(cwd) {
 	const pkgPath = path.join(cwd, "package.json");
 	if (!fs.existsSync(pkgPath)) return null;
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-	if ({
+	const allDeps = {
 		...pkg.dependencies,
 		...pkg.devDependencies
-	}["next"]) return "nextjs";
+	};
+	if (allDeps["next"]) return "nextjs";
+	if (allDeps["@sveltejs/kit"]) return "sveltekit";
 	return null;
 }
 function detectPackageManager(cwd) {
@@ -53,12 +55,13 @@ function readFileSafe(filePath) {
 	if (!fs.existsSync(filePath)) return null;
 	return fs.readFileSync(filePath, "utf-8");
 }
-/** Common locations where global CSS files live in Next.js projects. */
+/** Common locations where global CSS files live in Next.js / SvelteKit projects. */
 const GLOBAL_CSS_CANDIDATES = [
 	"app/globals.css",
 	"app/global.css",
 	"src/app/globals.css",
 	"src/app/global.css",
+	"src/app.css",
 	"styles/globals.css",
 	"styles/global.css",
 	"src/styles/globals.css",
@@ -128,7 +131,7 @@ function spawnAndWaitFor(command, args, cwd, waitFor, timeoutMs = 6e4) {
 function docsConfigTemplate(cfg) {
 	return `\
 import { defineDocs } from "@farming-labs/docs";
-import { fumadocs } from "@farming-labs/fumadocs";
+import { fumadocs } from "@farming-labs/theme";
 
 export default defineDocs({
   entry: "${cfg.entry}",
@@ -176,7 +179,7 @@ function rootLayoutTemplate(globalCssRelPath = "app/globals.css") {
 	else cssImport = "../" + globalCssRelPath;
 	return `\
 import type { Metadata } from "next";
-import { RootProvider } from "@farming-labs/fumadocs";
+import { RootProvider } from "@farming-labs/theme";
 import docsConfig from "@/docs.config";
 import "${cssImport}";
 
@@ -225,7 +228,7 @@ function injectCssImport(existingContent, theme) {
 function docsLayoutTemplate() {
 	return `\
 import docsConfig from "@/docs.config";
-import { createDocsLayout } from "@farming-labs/fumadocs";
+import { createDocsLayout } from "@farming-labs/theme";
 
 export default createDocsLayout(docsConfig);
 `;
@@ -330,7 +333,7 @@ Your project includes a \`docs.config.ts\` at the root:
 
 \`\`\`ts
 import { defineDocs } from "@farming-labs/docs";
-import { fumadocs } from "@farming-labs/fumadocs";
+import { fumadocs } from "@farming-labs/theme";
 
 export default defineDocs({
   entry: "${cfg.entry}",
@@ -438,6 +441,268 @@ Build your docs for production:
 pnpm build
 \`\`\`
 
+Deploy to Vercel, Netlify, or any Node.js hosting platform.
+`;
+}
+function svelteDocsConfigTemplate(cfg) {
+	return `\
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/svelte-theme";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: fumadocs({
+    ui: {
+      colors: { primary: "#6366f1" },
+    },
+  }),
+
+  nav: {
+    title: "${cfg.projectName}",
+    url: "/${cfg.entry}",
+  },
+
+  breadcrumb: { enabled: true },
+
+  metadata: {
+    titleTemplate: "%s – ${cfg.projectName}",
+    description: "Documentation for ${cfg.projectName}",
+  },
+});
+`;
+}
+function svelteDocsServerTemplate(cfg) {
+	return `\
+import { createDocsServer } from "@farming-labs/svelte/server";
+import config from "../../docs.config.js";
+
+export const { load, GET, POST } = createDocsServer(config);
+`;
+}
+function svelteDocsLayoutTemplate(cfg) {
+	return `\
+<script>
+  import { DocsLayout } from "@farming-labs/svelte-theme";
+  import config from "../../../docs.config.js";
+
+  let { data, children } = $props();
+<\/script>
+
+<DocsLayout tree={data.tree} {config}>
+  {@render children()}
+</DocsLayout>
+`;
+}
+function svelteDocsLayoutServerTemplate() {
+	return `\
+export { load } from "$lib/docs.server.js";
+`;
+}
+function svelteDocsPageTemplate(cfg) {
+	return `\
+<script>
+  import { DocsContent } from "@farming-labs/svelte-theme";
+  import config from "../../../../docs.config.js";
+
+  let { data } = $props();
+<\/script>
+
+<DocsContent {data} {config} />
+`;
+}
+function svelteRootLayoutTemplate(globalCssRelPath) {
+	let cssImport;
+	if (globalCssRelPath.startsWith("src/")) cssImport = "./" + globalCssRelPath.slice(4);
+	else cssImport = "../" + globalCssRelPath;
+	return `\
+<script>
+  import "${cssImport}";
+
+  let { children } = $props();
+<\/script>
+
+{@render children()}
+`;
+}
+function svelteGlobalCssTemplate(theme) {
+	return `\
+@import "@farming-labs/svelte-theme/${theme}/css";
+`;
+}
+function svelteCssImportLine(theme) {
+	return `@import "@farming-labs/svelte-theme/${theme}/css";`;
+}
+function injectSvelteCssImport(existingContent, theme) {
+	const importLine = svelteCssImportLine(theme);
+	if (existingContent.includes(importLine)) return null;
+	const lines = existingContent.split("\n");
+	const lastImportIdx = lines.reduce((acc, l, i) => l.trimStart().startsWith("@import") ? i : acc, -1);
+	if (lastImportIdx >= 0) lines.splice(lastImportIdx + 1, 0, importLine);
+	else lines.unshift(importLine);
+	return lines.join("\n");
+}
+function svelteWelcomePageTemplate(cfg) {
+	return `\
+---
+title: "Documentation"
+description: "Welcome to ${cfg.projectName} documentation"
+---
+
+# Welcome to ${cfg.projectName}
+
+Get started with our documentation. Browse the pages on the left to learn more.
+
+## Overview
+
+This documentation was generated by \`@farming-labs/docs\`. Edit the markdown files in \`${cfg.entry}/\` to customize.
+
+## Features
+
+- **Markdown Support** — Write docs with standard Markdown
+- **Syntax Highlighting** — Code blocks with automatic highlighting
+- **Dark Mode** — Built-in theme switching
+- **Search** — Full-text search across all pages
+- **Responsive** — Works on any screen size
+
+---
+
+## Next Steps
+
+Start by reading the [Installation](/${cfg.entry}/installation) guide, then follow the [Quickstart](/${cfg.entry}/quickstart) to build something.
+`;
+}
+function svelteInstallationPageTemplate(cfg) {
+	return `\
+---
+title: "Installation"
+description: "How to install and set up ${cfg.projectName}"
+---
+
+# Installation
+
+Follow these steps to install and configure ${cfg.projectName}.
+
+## Prerequisites
+
+- Node.js 18+
+- A package manager (pnpm, npm, or yarn)
+
+## Install Dependencies
+
+\`\`\`bash
+pnpm add @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme
+\`\`\`
+
+## Configuration
+
+Your project includes a \`docs.config.ts\` at the root:
+
+\`\`\`ts title="docs.config.ts"
+import { defineDocs } from "@farming-labs/docs";
+import { fumadocs } from "@farming-labs/svelte-theme";
+
+export default defineDocs({
+  entry: "${cfg.entry}",
+  contentDir: "${cfg.entry}",
+  theme: fumadocs({
+    ui: { colors: { primary: "#6366f1" } },
+  }),
+});
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+${cfg.entry}/                   # Markdown content
+  page.md                      # /${cfg.entry}
+  installation/
+    page.md                    # /${cfg.entry}/installation
+  quickstart/
+    page.md                    # /${cfg.entry}/quickstart
+src/
+  lib/
+    docs.server.ts             # Server-side docs loader
+  routes/
+    ${cfg.entry}/
+      +layout.svelte           # Docs layout
+      +layout.server.js        # Layout data loader
+      [...slug]/
+        +page.svelte           # Dynamic doc page
+docs.config.ts                 # Docs configuration
+\`\`\`
+
+## What's Next?
+
+Head to the [Quickstart](/${cfg.entry}/quickstart) guide to start writing your first page.
+`;
+}
+function svelteQuickstartPageTemplate(cfg) {
+	return `\
+---
+title: "Quickstart"
+description: "Get up and running in minutes"
+---
+
+# Quickstart
+
+This guide walks you through creating your first documentation page.
+
+## Creating a Page
+
+Create a new folder under \`${cfg.entry}/\` with a \`page.md\` file:
+
+\`\`\`bash
+mkdir -p ${cfg.entry}/my-page
+\`\`\`
+
+Then create \`${cfg.entry}/my-page/page.md\`:
+
+\`\`\`md
+---
+title: "My Page"
+description: "A custom documentation page"
+---
+
+# My Page
+
+Write your content here using **Markdown**.
+\`\`\`
+
+Your page is now available at \`/${cfg.entry}/my-page\`.
+
+## Code Blocks
+
+Code blocks are automatically syntax-highlighted:
+
+\`\`\`typescript
+function greet(name: string): string {
+  return \\\`Hello, \\\${name}!\\\`;
+}
+
+console.log(greet("World"));
+\`\`\`
+
+## Customizing the Theme
+
+Edit \`docs.config.ts\` to change colors, typography, and component defaults:
+
+\`\`\`ts title="docs.config.ts"
+theme: fumadocs({
+  ui: {
+    colors: { primary: "#22c55e" },
+  },
+}),
+\`\`\`
+
+## Deploying
+
+Build your docs for production:
+
+\`\`\`bash
+pnpm build
+\`\`\`
+
 Deploy to Vercel, Netlify, or any Node.js hosting platform.
 `;
 }
@@ -447,19 +712,30 @@ Deploy to Vercel, Netlify, or any Node.js hosting platform.
 async function init() {
 	const cwd = process.cwd();
 	p.intro(pc.bgCyan(pc.black(" @farming-labs/docs ")));
-	if (!detectFramework(cwd)) {
-		p.log.error("Could not detect a supported framework.\n  Make sure you have a " + pc.cyan("package.json") + " with " + pc.cyan("next") + " installed.\n  Supported frameworks: Next.js");
+	const framework = detectFramework(cwd);
+	if (!framework) {
+		p.log.error("Could not detect a supported framework.\n  Make sure you have a " + pc.cyan("package.json") + " with " + pc.cyan("next") + " or " + pc.cyan("@sveltejs/kit") + " installed.\n  Supported frameworks: Next.js, SvelteKit");
 		p.outro(pc.red("Init cancelled."));
 		process.exit(1);
 	}
-	p.log.success(`Detected framework: ${pc.cyan("Next.js")}`);
+	const frameworkName = framework === "nextjs" ? "Next.js" : "SvelteKit";
+	p.log.success(`Detected framework: ${pc.cyan(frameworkName)}`);
+	const themeOptions = framework === "sveltekit" ? [{
+		value: "default",
+		label: "Default",
+		hint: "Clean, modern docs theme with sidebar, search, and dark mode"
+	}, {
+		value: "pixel-border",
+		label: "Pixel Border",
+		hint: "Sharp pixel-art inspired theme with monospace text"
+	}] : [{
+		value: "fumadocs",
+		label: "Fumadocs",
+		hint: "Clean, modern docs theme with sidebar, search, and dark mode"
+	}];
 	const theme = await p.select({
 		message: "Which theme would you like to use?",
-		options: [{
-			value: "fumadocs",
-			label: "Fumadocs",
-			hint: "Clean, modern docs theme with sidebar, search, and dark mode"
-		}]
+		options: themeOptions
 	});
 	if (p.isCancel(theme)) {
 		p.outro(pc.red("Init cancelled."));
@@ -482,6 +758,7 @@ async function init() {
 	const entryPath = entry;
 	const detectedCssFiles = detectGlobalCssFiles(cwd);
 	let globalCssRelPath;
+	const defaultCssPath = framework === "sveltekit" ? "src/app.css" : "app/globals.css";
 	if (detectedCssFiles.length === 1) {
 		globalCssRelPath = detectedCssFiles[0];
 		p.log.info(`Found global CSS at ${pc.cyan(globalCssRelPath)}`);
@@ -501,8 +778,8 @@ async function init() {
 	} else {
 		const cssPath = await p.text({
 			message: "Where is your global CSS file?",
-			placeholder: "app/globals.css",
-			defaultValue: "app/globals.css",
+			placeholder: defaultCssPath,
+			defaultValue: defaultCssPath,
 			validate: (value) => {
 				if (!value) return "CSS file path is required";
 				if (!value.endsWith(".css")) return "Path must end with .css";
@@ -518,7 +795,8 @@ async function init() {
 	const cfg = {
 		entry: entryPath,
 		theme,
-		projectName: pkgJson.name || "My Project"
+		projectName: pkgJson.name || "My Project",
+		framework
 	};
 	const s = p.spinner();
 	s.start("Scaffolding docs files");
@@ -528,32 +806,8 @@ async function init() {
 		if (writeFileSafe(path.join(cwd, rel), content, overwrite)) written.push(rel);
 		else skipped.push(rel);
 	}
-	write("docs.config.ts", docsConfigTemplate(cfg));
-	const existingNextConfig = readFileSafe(path.join(cwd, "next.config.ts")) ?? readFileSafe(path.join(cwd, "next.config.mjs")) ?? readFileSafe(path.join(cwd, "next.config.js"));
-	if (existingNextConfig) {
-		const configFile = fileExists(path.join(cwd, "next.config.ts")) ? "next.config.ts" : fileExists(path.join(cwd, "next.config.mjs")) ? "next.config.mjs" : "next.config.js";
-		const merged = nextConfigMergedTemplate(existingNextConfig);
-		if (merged !== existingNextConfig) {
-			writeFileSafe(path.join(cwd, configFile), merged, true);
-			written.push(configFile + " (updated)");
-		} else skipped.push(configFile + " (already configured)");
-	} else write("next.config.ts", nextConfigTemplate());
-	write("app/layout.tsx", rootLayoutTemplate(globalCssRelPath));
-	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
-	const existingGlobalCss = readFileSafe(globalCssAbsPath);
-	if (existingGlobalCss) {
-		const injected = injectCssImport(existingGlobalCss, theme);
-		if (injected) {
-			writeFileSafe(globalCssAbsPath, injected, true);
-			written.push(globalCssRelPath + " (updated)");
-		} else skipped.push(globalCssRelPath + " (already configured)");
-	} else write(globalCssRelPath, globalCssTemplate(theme));
-	write(`app/${entryPath}/layout.tsx`, docsLayoutTemplate());
-	write("postcss.config.mjs", postcssConfigTemplate());
-	if (!fileExists(path.join(cwd, "tsconfig.json"))) write("tsconfig.json", tsconfigTemplate());
-	write(`app/${entryPath}/page.mdx`, welcomePageTemplate(cfg));
-	write(`app/${entryPath}/installation/page.mdx`, installationPageTemplate(cfg));
-	write(`app/${entryPath}/quickstart/page.mdx`, quickstartPageTemplate(cfg));
+	if (framework === "sveltekit") scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written);
+	else scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written);
 	s.stop("Files scaffolded");
 	if (written.length > 0) p.log.success(`Created ${written.length} file${written.length > 1 ? "s" : ""}:\n` + written.map((f) => `  ${pc.green("+")} ${f}`).join("\n"));
 	if (skipped.length > 0) p.log.info(`Skipped ${skipped.length} existing file${skipped.length > 1 ? "s" : ""}:\n` + skipped.map((f) => `  ${pc.dim("-")} ${f}`).join("\n"));
@@ -562,20 +816,23 @@ async function init() {
 	const s2 = p.spinner();
 	s2.start("Installing dependencies");
 	try {
-		exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/next @farming-labs/fumadocs`, cwd);
-		const devDeps = [
-			"@tailwindcss/postcss",
-			"postcss",
-			"tailwindcss",
-			"@types/mdx",
-			"@types/node"
-		];
-		const allDeps = {
-			...pkgJson.dependencies,
-			...pkgJson.devDependencies
-		};
-		const missingDevDeps = devDeps.filter((d) => !allDeps[d]);
-		if (missingDevDeps.length > 0) exec(`${devInstallCommand(pm)} ${missingDevDeps.join(" ")}`, cwd);
+		if (framework === "sveltekit") exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/svelte @farming-labs/svelte-theme`, cwd);
+		else {
+			exec(`${installCommand(pm)} @farming-labs/docs @farming-labs/next @farming-labs/theme`, cwd);
+			const devDeps = [
+				"@tailwindcss/postcss",
+				"postcss",
+				"tailwindcss",
+				"@types/mdx",
+				"@types/node"
+			];
+			const allDeps = {
+				...pkgJson.dependencies,
+				...pkgJson.devDependencies
+			};
+			const missingDevDeps = devDeps.filter((d) => !allDeps[d]);
+			if (missingDevDeps.length > 0) exec(`${devInstallCommand(pm)} ${missingDevDeps.join(" ")}`, cwd);
+		}
 	} catch {
 		s2.stop("Failed to install dependencies");
 		p.log.error(`Dependency installation failed. Run the install command manually:
@@ -595,13 +852,23 @@ async function init() {
 		process.exit(0);
 	}
 	p.log.step("Starting dev server...");
-	try {
-		const child = await spawnAndWaitFor("npx", [
+	const devCommand = framework === "sveltekit" ? {
+		cmd: "npx",
+		args: ["vite", "dev"],
+		waitFor: "ready"
+	} : {
+		cmd: "npx",
+		args: [
 			"next",
 			"dev",
 			"--webpack"
-		], cwd, "Ready", 6e4);
-		const url = `http://localhost:3000/${entryPath}`;
+		],
+		waitFor: "Ready"
+	};
+	const defaultPort = framework === "sveltekit" ? "5173" : "3000";
+	try {
+		const child = await spawnAndWaitFor(devCommand.cmd, devCommand.args, cwd, devCommand.waitFor, 6e4);
+		const url = `http://localhost:${defaultPort}/${entryPath}`;
 		console.log();
 		p.log.success(`Dev server is running! Your docs are live at:\n\n  ${pc.cyan(pc.underline(url))}\n\n  Press ${pc.dim("Ctrl+C")} to stop the server.`);
 		p.outro(pc.green("Happy documenting!"));
@@ -617,12 +884,66 @@ async function init() {
 			});
 		});
 	} catch (err) {
+		const manualCmd = framework === "sveltekit" ? "npx vite dev" : "npx next dev --webpack";
 		p.log.error(`Could not start dev server. Try running manually:
-  ${pc.cyan("npx next dev --webpack")}`);
+  ${pc.cyan(manualCmd)}`);
 		p.outro(pc.yellow("Setup complete. Start the server manually."));
 		process.exit(1);
 	}
 }
+function scaffoldNextJs(cwd, cfg, globalCssRelPath, write, skipped, written) {
+	write("docs.config.ts", docsConfigTemplate(cfg));
+	const existingNextConfig = readFileSafe(path.join(cwd, "next.config.ts")) ?? readFileSafe(path.join(cwd, "next.config.mjs")) ?? readFileSafe(path.join(cwd, "next.config.js"));
+	if (existingNextConfig) {
+		const configFile = fileExists(path.join(cwd, "next.config.ts")) ? "next.config.ts" : fileExists(path.join(cwd, "next.config.mjs")) ? "next.config.mjs" : "next.config.js";
+		const merged = nextConfigMergedTemplate(existingNextConfig);
+		if (merged !== existingNextConfig) {
+			writeFileSafe(path.join(cwd, configFile), merged, true);
+			written.push(configFile + " (updated)");
+		} else skipped.push(configFile + " (already configured)");
+	} else write("next.config.ts", nextConfigTemplate());
+	write("app/layout.tsx", rootLayoutTemplate(globalCssRelPath));
+	const globalCssAbsPath = path.join(cwd, globalCssRelPath);
+	const existingGlobalCss = readFileSafe(globalCssAbsPath);
+	if (existingGlobalCss) {
+		const injected = injectCssImport(existingGlobalCss, cfg.theme);
+		if (injected) {
+			writeFileSafe(globalCssAbsPath, injected, true);
+			written.push(globalCssRelPath + " (updated)");
+		} else skipped.push(globalCssRelPath + " (already configured)");
+	} else write(globalCssRelPath, globalCssTemplate(cfg.theme));
+	write(`app/${cfg.entry}/layout.tsx`, docsLayoutTemplate());
+	write("postcss.config.mjs", postcssConfigTemplate());
+	if (!fileExists(path.join(cwd, "tsconfig.json"))) write("tsconfig.json", tsconfigTemplate());
+	write(`app/${cfg.entry}/page.mdx`, welcomePageTemplate(cfg));
+	write(`app/${cfg.entry}/installation/page.mdx`, installationPageTemplate(cfg));
+	write(`app/${cfg.entry}/quickstart/page.mdx`, quickstartPageTemplate(cfg));
+}
+function scaffoldSvelteKit(cwd, cfg, globalCssRelPath, write, skipped, written) {
+	write("docs.config.ts", svelteDocsConfigTemplate(cfg));
+	write("src/lib/docs.server.ts", svelteDocsServerTemplate(cfg));
+	write(`src/routes/${cfg.entry}/+layout.svelte`, svelteDocsLayoutTemplate(cfg));
+	write(`src/routes/${cfg.entry}/+layout.server.js`, svelteDocsLayoutServerTemplate());
+	write(`src/routes/${cfg.entry}/[...slug]/+page.svelte`, svelteDocsPageTemplate(cfg));
+	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);
+	const cssTheme = {
+		default: "fumadocs",
+		"pixel-border": "pixel-border",
+		fumadocs: "fumadocs"
+	}[cfg.theme] || "fumadocs";
+	if (existingGlobalCss) {
+		const injected = injectSvelteCssImport(existingGlobalCss, cssTheme);
+		if (injected) {
+			writeFileSafe(globalCssAbsPath, injected, true);
+			written.push(globalCssRelPath + " (updated)");
+		} else skipped.push(globalCssRelPath + " (already configured)");
+	} else write(globalCssRelPath, svelteGlobalCssTemplate(cssTheme));
+	write(`${cfg.entry}/page.md`, svelteWelcomePageTemplate(cfg));
+	write(`${cfg.entry}/installation/page.md`, svelteInstallationPageTemplate(cfg));
+	write(`${cfg.entry}/quickstart/page.md`, svelteQuickstartPageTemplate(cfg));
+}
 
 //#endregion
 //#region src/cli/index.ts
@@ -648,6 +969,9 @@ ${pc.dim("Usage:")}
 ${pc.dim("Commands:")}
   ${pc.cyan("init")}    Scaffold docs in your project (default)
 
+${pc.dim("Supported frameworks:")}
+  Next.js, SvelteKit
+
 ${pc.dim("Options:")}
   ${pc.cyan("-h, --help")}       Show this help message
   ${pc.cyan("-v, --version")}    Show version

package/dist/index.d.mts

@@ -442,9 +442,246 @@ interface GithubConfig {
    */
   directory?: string;
 }
+/**
+ * Configuration for "Ask AI" — a RAG-powered chat that lets users
+ * ask questions about the documentation content.
+ *
+ * The AI handler searches relevant doc pages, builds context, and
+ * streams a response from an LLM (OpenAI-compatible API).
+ *
+ * The API key is **never** stored in the config. It is read from the
+ * `OPENAI_API_KEY` environment variable at runtime on the server.
+ *
+ * @example
+ * ```ts
+ * ai: {
+ *   enabled: true,
+ *   model: "gpt-4o-mini",
+ *   systemPrompt: "You are a helpful assistant for our developer docs.",
+ * }
+ * ```
+ */
+interface AIConfig {
+  /**
+   * Whether to enable "Ask AI" functionality.
+   * When enabled, the unified `/api/docs` route handler will accept
+   * POST requests for AI chat.
+   * @default false
+   */
+  enabled?: boolean;
+  /**
+   * How the AI chat UI is presented.
+   *
+   * - `"search"` — AI tab integrated into the Cmd+K search dialog (default)
+   * - `"floating"` — A floating chat widget (bubble button + slide-out panel)
+   *
+   * @default "search"
+   *
+   * @example
+   * ```ts
+   * // Floating chat bubble in the bottom-right corner
+   * ai: {
+   *   enabled: true,
+   *   mode: "floating",
+   *   position: "bottom-right",
+   * }
+   * ```
+   */
+  mode?: "search" | "floating";
+  /**
+   * Position of the floating chat button on screen.
+   * Only used when `mode` is `"floating"`.
+   *
+   * - `"bottom-right"` — bottom-right corner (default)
+   * - `"bottom-left"` — bottom-left corner
+   * - `"bottom-center"` — bottom center
+   *
+   * @default "bottom-right"
+   */
+  position?: "bottom-right" | "bottom-left" | "bottom-center";
+  /**
+   * Visual style of the floating chat when opened.
+   * Only used when `mode` is `"floating"`.
+   *
+   * - `"panel"` — A tall panel that slides up from the button position (default).
+   *   Stays anchored near the floating button. No backdrop overlay.
+   *
+   * - `"modal"` — A centered modal dialog with a backdrop overlay,
+   *   similar to the Cmd+K search dialog. Feels more focused and immersive.
+   *
+   * - `"popover"` — A compact popover near the button. Smaller than the
+   *   panel, suitable for quick questions without taking much screen space.
+   *
+   * - `"full-modal"` — A full-screen immersive overlay (inspired by better-auth).
+   *   Messages scroll in the center, input is pinned at the bottom.
+   *   Suggested questions appear as horizontal pills. Best for
+   *   documentation-heavy sites that want a premium AI experience.
+   *
+   * @default "panel"
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   mode: "floating",
+   *   position: "bottom-right",
+   *   floatingStyle: "full-modal",
+   * }
+   * ```
+   */
+  floatingStyle?: "panel" | "modal" | "popover" | "full-modal";
+  /**
+   * Custom trigger component for the floating chat button.
+   * Only used when `mode` is `"floating"`.
+   *
+   * Pass a React element to replace the default sparkles button.
+   * The element receives an `onClick` handler automatically.
+   *
+   * @example
+   * ```tsx
+   * ai: {
+   *   enabled: true,
+   *   mode: "floating",
+   *   triggerComponent: <button className="my-chat-btn">💬 Help</button>,
+   * }
+   * ```
+   */
+  triggerComponent?: unknown;
+  /**
+   * The LLM model to use for chat completions.
+   * Must be compatible with the OpenAI Chat Completions API.
+   * @default "gpt-4o-mini"
+   */
+  model?: string;
+  /**
+   * Custom system prompt prepended to the AI conversation.
+   * The documentation context is automatically appended after this prompt.
+   *
+   * @default "You are a helpful documentation assistant. Answer questions
+   * based on the provided documentation context. Be concise and accurate.
+   * If the answer is not in the context, say so honestly."
+   */
+  systemPrompt?: string;
+  /**
+   * Base URL for an OpenAI-compatible API endpoint.
+   * Use this to point to a self-hosted model, Azure OpenAI, or any
+   * compatible provider (e.g. Groq, Together, OpenRouter).
+   * @default "https://api.openai.com/v1"
+   */
+  baseUrl?: string;
+  /**
+   * API key for the LLM provider.
+   * Pass it via an environment variable to keep it out of source control.
+   *
+   * @default process.env.OPENAI_API_KEY
+   *
+   * @example
+   * ```ts
+   * // Default — reads OPENAI_API_KEY automatically
+   * ai: { enabled: true }
+   *
+   * // Custom provider key
+   * ai: {
+   *   enabled: true,
+   *   apiKey: process.env.GROQ_API_KEY,
+   * }
+   * ```
+   */
+  apiKey?: string;
+  /**
+   * Maximum number of search results to include as context for the AI.
+   * More results = more context but higher token usage.
+   * @default 5
+   */
+  maxResults?: number;
+  /**
+   * Pre-filled suggested questions shown in the AI chat when empty.
+   * When a user clicks one, it fills the input and submits automatically.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   suggestedQuestions: [
+   *     "How do I install this?",
+   *     "What themes are available?",
+   *     "How do I create a custom component?",
+   *   ],
+   * }
+   * ```
+   */
+  suggestedQuestions?: string[];
+  /**
+   * Display name for the AI assistant in the chat UI.
+   * Shown as the message label, header title, and passed to the loading component.
+   *
+   * @default "AI"
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   aiLabel: "DocsBot",
+   * }
+   * ```
+   */
+  aiLabel?: string;
+  /**
+   * The npm package name used in import examples.
+   * The AI will use this in code snippets instead of generic placeholders.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   packageName: "@farming-labs/docs",
+   * }
+   * ```
+   */
+  packageName?: string;
+  /**
+   * The public URL of the documentation site.
+   * The AI will use this for links instead of relative paths.
+   *
+   * @example
+   * ```ts
+   * ai: {
+   *   enabled: true,
+   *   docsUrl: "https://docs.farming-labs.dev",
+   * }
+   * ```
+   */
+  docsUrl?: string;
+  /**
+   * Custom loading indicator shown while the AI is generating a response.
+   * Replaces the default "AI is thinking..." indicator.
+   *
+   * Pass a function that receives `{ name }` (the `aiLabel` value) and
+   * returns a React element. This way you don't need to duplicate the label.
+   *
+   * @example
+   * ```tsx
+   * ai: {
+   *   enabled: true,
+   *   aiLabel: "Sage",
+   *   loadingComponent: ({ name }) => (
+   *     <div className="flex items-center gap-2 text-sm text-zinc-400">
+   *       <span className="animate-pulse">🤔</span>
+   *       <span>{name} is thinking...</span>
+   *     </div>
+   *   ),
+   * }
+   * ```
+   */
+  loadingComponent?: (props: {
+    name: string;
+  }) => unknown;
+}
 interface DocsConfig {
   /** Entry folder for docs (e.g. "docs" → /docs) */
   entry: string;
+  /** Path to the content directory. Defaults to `entry` value. */
+  contentDir?: string;
   /** Theme configuration - single source of truth for UI */
   theme?: DocsTheme;
   /**
@@ -579,6 +816,39 @@ interface DocsConfig {
    * ```
    */
   pageActions?: PageActionsConfig;
+  /**
+   * AI-powered "Ask AI" chat for documentation.
+   *
+   * When enabled, the unified API route handler (`/api/docs`) accepts
+   * POST requests for AI chat. The handler uses RAG (Retrieval-Augmented
+   * Generation) — it searches relevant docs, builds context, and streams
+   * a response from an LLM.
+   *
+   * The API key defaults to `process.env.OPENAI_API_KEY`. For other providers,
+   * pass the key via `apiKey: process.env.YOUR_KEY`.
+   *
+   * @example
+   * ```ts
+   * // Enable with defaults (gpt-4o-mini, OPENAI_API_KEY)
+   * ai: { enabled: true }
+   *
+   * // Custom model + system prompt
+   * ai: {
+   *   enabled: true,
+   *   model: "gpt-4o",
+   *   systemPrompt: "You are an expert on our SDK. Be concise.",
+   * }
+   *
+   * // Use a different provider (e.g. Groq)
+   * ai: {
+   *   enabled: true,
+   *   baseUrl: "https://api.groq.com/openai/v1",
+   *   apiKey: process.env.GROQ_API_KEY,
+   *   model: "llama-3.1-70b-versatile",
+   * }
+   * ```
+   */
+  ai?: AIConfig;
   /** SEO metadata - separate from theme */
   metadata?: DocsMetadata;
   /** Open Graph image handling */
@@ -632,7 +902,7 @@ declare function createTheme(baseTheme: DocsTheme): (overrides?: Partial<DocsThe
  * @example
  * ```ts
  * import { extendTheme } from "@farming-labs/docs";
- * import { fumadocs } from "@farming-labs/fumadocs/default";
+ * import { fumadocs } from "@farming-labs/theme/default";
  *
  * // Start with fumadocs defaults, override some values
  * export const myTheme = extendTheme(fumadocs(), {
@@ -654,4 +924,4 @@ declare function resolveTitle(pageTitle: string, metadata?: DocsMetadata): strin
  */
 declare function resolveOGImage(page: PageFrontmatter, ogConfig?: OGConfig, baseUrl?: string): string | undefined;
 //#endregion
-export { type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type PageActionsConfig, type PageFrontmatter, type SidebarConfig, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };
+export { type AIConfig, type BreadcrumbConfig, type CopyMarkdownConfig, type DocsConfig, type DocsMetadata, type DocsNav, type DocsTheme, type FontStyle, type GithubConfig, type OGConfig, type OpenDocsConfig, type OpenDocsProvider, type PageActionsConfig, type PageFrontmatter, type SidebarConfig, type ThemeToggleConfig, type TypographyConfig, type UIConfig, createTheme, deepMerge, defineDocs, extendTheme, resolveOGImage, resolveTitle };

package/dist/index.mjs

@@ -5,6 +5,7 @@
 function defineDocs(config) {
 	return {
 		entry: config.entry ?? "docs",
+		contentDir: config.contentDir,
 		theme: config.theme,
 		nav: config.nav,
 		github: config.github,
@@ -14,6 +15,7 @@ function defineDocs(config) {
 		components: config.components,
 		icons: config.icons,
 		pageActions: config.pageActions,
+		ai: config.ai,
 		metadata: config.metadata,
 		og: config.og
 	};
@@ -81,7 +83,7 @@ function createTheme(baseTheme) {
 * @example
 * ```ts
 * import { extendTheme } from "@farming-labs/docs";
-* import { fumadocs } from "@farming-labs/fumadocs/default";
+* import { fumadocs } from "@farming-labs/theme/default";
 *
 * // Start with fumadocs defaults, override some values
 * export const myTheme = extendTheme(fumadocs(), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/docs",
-  "version": "0.0.2-beta.3",
+  "version": "0.0.2-beta.4",
   "description": "Modern, flexible MDX-based docs framework — core types, config, and CLI",
   "type": "module",
   "main": "./dist/index.mjs",