@farming-labs/theme 0.1.71 → 0.1.73

package/dist/ai-search-dialog.d.mts

@@ -17,7 +17,8 @@ declare function DocsSearchDialog({
   loadingComponentHtml,
   models,
   defaultModelId,
-  analytics
+  analytics,
+  feedbackEnabled
 }: {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -29,6 +30,7 @@ declare function DocsSearchDialog({
   models?: AIModelOption[];
   defaultModelId?: string;
   analytics?: boolean;
+  feedbackEnabled?: boolean;
 }): react.ReactPortal | null;
 type FloatingPosition = "bottom-right" | "bottom-left" | "bottom-center";
 type FloatingStyle = "panel" | "modal" | "popover" | "full-modal";
@@ -43,7 +45,8 @@ declare function FloatingAIChat({
   loadingComponentHtml,
   models,
   defaultModelId,
-  analytics
+  analytics,
+  feedbackEnabled
 }: {
   api?: string;
   position?: FloatingPosition;
@@ -56,6 +59,7 @@ declare function FloatingAIChat({
   models?: AIModelOption[];
   defaultModelId?: string;
   analytics?: boolean;
+  feedbackEnabled?: boolean;
 }): react_jsx_runtime0.JSX.Element | null;
 declare function AIModalDialog({
   open,
@@ -67,7 +71,8 @@ declare function AIModalDialog({
   loadingComponentHtml,
   models,
   defaultModelId,
-  analytics
+  analytics,
+  feedbackEnabled
 }: {
   open: boolean;
   onOpenChange: (open: boolean) => void;
@@ -79,6 +84,7 @@ declare function AIModalDialog({
   models?: AIModelOption[];
   defaultModelId?: string;
   analytics?: boolean;
+  feedbackEnabled?: boolean;
 }): react.ReactPortal | null;
 //#endregion
 export { AIModalDialog, DocsSearchDialog, FloatingAIChat };

package/dist/ai-search-dialog.mjs

@@ -18,6 +18,118 @@ import { highlight } from "sugar-high";
 * - `mode="search"` (default): AI tab inside the Cmd+K search dialog
 * - `mode="floating"`: Standalone floating chat widget with configurable position
 */
+let aiMessageId = 0;
+function createAIMessageId() {
+	aiMessageId += 1;
+	return `ai_${Date.now().toString(36)}_${aiMessageId.toString(36)}`;
+}
+function getLastUserQuestion(messages, assistantIndex) {
+	for (let i = assistantIndex - 1; i >= 0; i -= 1) {
+		const message = messages[i];
+		if (message?.role === "user") return message.content;
+	}
+	return "";
+}
+function buildActionPayload(options) {
+	const location = typeof window !== "undefined" ? {
+		url: window.location.href,
+		path: window.location.pathname
+	} : {};
+	return {
+		type: options.type,
+		value: options.type === "like" || options.type === "dislike" ? options.type : void 0,
+		question: getLastUserQuestion(options.messages, options.index),
+		answer: options.message.content,
+		messageId: options.message.id,
+		messageIndex: options.index,
+		model: options.message.model,
+		surface: options.surface,
+		messages: options.messages.slice(0, options.index + 1).map((message) => ({
+			role: message.role,
+			content: message.content
+		})),
+		copied: options.copied,
+		...location
+	};
+}
+function toFeedbackPayload(data) {
+	if (data.type !== "like" && data.type !== "dislike") return null;
+	return {
+		value: data.type,
+		question: data.question,
+		answer: data.answer,
+		messageId: data.messageId,
+		messageIndex: data.messageIndex,
+		model: data.model,
+		surface: data.surface,
+		url: data.url,
+		path: data.path,
+		messages: data.messages
+	};
+}
+function emitAskAIAction(data) {
+	if (typeof window === "undefined") return;
+	try {
+		const result = window.__fdOnAIActions__?.(data);
+		if (result && typeof result.catch === "function") result.catch(() => {});
+	} catch {}
+	try {
+		window.dispatchEvent(new CustomEvent("fd:ai-action", { detail: data }));
+	} catch {}
+}
+function emitAskAIFeedback(data, analytics) {
+	if (analytics) emitClientAnalyticsEvent({
+		type: "ai_feedback",
+		input: {
+			question: data.question,
+			feedbackValue: data.value
+		},
+		properties: {
+			value: data.value,
+			surface: data.surface,
+			model: data.model,
+			questionLength: data.question.length,
+			answerLength: data.answer.length,
+			messageIndex: data.messageIndex
+		}
+	});
+	if (typeof window === "undefined") return;
+	try {
+		const result = window.__fdOnAIFeedback__?.(data);
+		if (result && typeof result.catch === "function") result.catch(() => {});
+	} catch {}
+	try {
+		window.dispatchEvent(new CustomEvent("fd:ai-feedback", { detail: data }));
+	} catch {}
+}
+function fallbackCopyText(text) {
+	if (typeof document === "undefined") return false;
+	const textarea = document.createElement("textarea");
+	textarea.value = text;
+	textarea.setAttribute("readonly", "");
+	textarea.style.position = "fixed";
+	textarea.style.top = "-9999px";
+	textarea.style.opacity = "0";
+	document.body.appendChild(textarea);
+	textarea.select();
+	try {
+		document.execCommand("copy");
+		return true;
+	} catch {
+		return false;
+	} finally {
+		document.body.removeChild(textarea);
+	}
+}
+async function copyTextToClipboard(text) {
+	if (!text) return false;
+	try {
+		await navigator.clipboard.writeText(text);
+		return true;
+	} catch {
+		return fallbackCopyText(text);
+	}
+}
 function buildCodeBlock(lang, code) {
 	const highlighted = highlight(code.replace(/\n$/, "")).replace(/<\/span>\n<span/g, "</span><span");
 	return `<div class="fd-ai-code-block"><div class="fd-ai-code-header">${lang ? `<div class="fd-ai-code-lang">${escapeHtml(lang)}</div>` : ""}<button class="fd-ai-code-copy" onclick="(function(btn){var code=btn.closest('.fd-ai-code-block').querySelector('code').textContent;navigator.clipboard.writeText(code).then(function(){btn.textContent='Copied!';setTimeout(function(){btn.textContent='Copy'},1500)})})(this)">Copy</button></div><pre><code>${highlighted}</code></pre></div>`;
@@ -146,6 +258,65 @@ function XIcon() {
 		children: [/* @__PURE__ */ jsx("path", { d: "M18 6 6 18" }), /* @__PURE__ */ jsx("path", { d: "m6 6 12 12" })]
 	});
 }
+function ThumbsUpIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		width: "14",
+		height: "14",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: [/* @__PURE__ */ jsx("path", { d: "M7 10v12" }), /* @__PURE__ */ jsx("path", { d: "M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z" })]
+	});
+}
+function ThumbsDownIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		width: "14",
+		height: "14",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: [/* @__PURE__ */ jsx("path", { d: "M17 14V2" }), /* @__PURE__ */ jsx("path", { d: "M9 18.12 10 14H4.17a2 2 0 0 1-1.92-2.56l2.33-8A2 2 0 0 1 6.5 2H20a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2h-2.76a2 2 0 0 0-1.79 1.11L12 22a3.13 3.13 0 0 1-3-3.88Z" })]
+	});
+}
+function CopyIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		width: "14",
+		height: "14",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "9",
+			y: "9",
+			width: "13",
+			height: "13",
+			rx: "2",
+			ry: "2"
+		}), /* @__PURE__ */ jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })]
+	});
+}
+function CheckIcon() {
+	return /* @__PURE__ */ jsx("svg", {
+		width: "14",
+		height: "14",
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2.4",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" })
+	});
+}
 function LoaderIndicator({ variant = "shimmer-dots" }) {
 	const text = "Thinking";
 	switch (variant) {
@@ -346,7 +517,51 @@ function ModelSelector({ models, selectedId, onChange, disabled }) {
 		})]
 	});
 }
-function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, surface = "chat" }) {
+function AIFeedbackControls({ value, onCopy, onSelect }) {
+	const [copied, setCopied] = useState(false);
+	const handleCopy = useCallback(async () => {
+		if (!await onCopy()) return;
+		setCopied(true);
+		window.setTimeout(() => setCopied(false), 1500);
+	}, [onCopy]);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "fd-ai-feedback",
+		role: "group",
+		"aria-label": "Rate this Ask AI response",
+		children: [
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "fd-ai-feedback-btn",
+				"data-copied": copied ? "true" : void 0,
+				"aria-label": copied ? "Copied response" : "Copy response",
+				title: copied ? "Copied" : "Copy response",
+				onClick: handleCopy,
+				children: copied ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx(CopyIcon, {})
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "fd-ai-feedback-btn",
+				"data-active": value === "like",
+				"aria-pressed": value === "like",
+				"aria-label": "Helpful",
+				title: "Helpful",
+				onClick: () => onSelect("like"),
+				children: /* @__PURE__ */ jsx(ThumbsUpIcon, {})
+			}),
+			/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "fd-ai-feedback-btn",
+				"data-active": value === "dislike",
+				"aria-pressed": value === "dislike",
+				"aria-label": "Not helpful",
+				title: "Not helpful",
+				onClick: () => onSelect("dislike"),
+				children: /* @__PURE__ */ jsx(ThumbsDownIcon, {})
+			})
+		]
+	});
+}
+function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled = true, surface = "chat" }) {
 	const label = aiLabel || "AI";
 	const aiInputRef = useRef(null);
 	const messagesEndRef = useRef(null);
@@ -368,12 +583,15 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 			content: question
 		};
 		const newMessages = [...messages, userMessage];
+		const assistantMessage = {
+			role: "assistant",
+			content: "",
+			id: createAIMessageId(),
+			model: effectiveModelId
+		};
 		setAiInput("");
 		setIsStreaming(true);
-		setMessages([...newMessages, {
-			role: "assistant",
-			content: ""
-		}]);
+		setMessages([...newMessages, assistantMessage]);
 		const startedAt = Date.now();
 		if (analytics) emitClientAnalyticsEvent({
 			type: "ai_question",
@@ -402,8 +620,9 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 					errMsg = (await res.json()).error || errMsg;
 				} catch {}
 				setMessages([...newMessages, {
-					role: "assistant",
-					content: errMsg
+					...assistantMessage,
+					content: errMsg,
+					isError: true
 				}]);
 				setIsStreaming(false);
 				if (analytics) emitClientAnalyticsEvent({
@@ -435,7 +654,7 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 						if (content) {
 							assistantContent += content;
 							setMessages([...newMessages, {
-								role: "assistant",
+								...assistantMessage,
 								content: assistantContent
 							}]);
 						}
@@ -443,7 +662,7 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 				}
 			}
 			if (assistantContent) setMessages([...newMessages, {
-				role: "assistant",
+				...assistantMessage,
 				content: assistantContent
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
@@ -458,8 +677,9 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 			});
 		} catch {
 			setMessages([...newMessages, {
-				role: "assistant",
-				content: "Failed to connect. Please try again."
+				...assistantMessage,
+				content: "Failed to connect. Please try again.",
+				isError: true
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
 				type: "ai_error",
@@ -492,6 +712,42 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 		}
 	};
 	const canSend = !!(aiInput.trim() && !isStreaming);
+	const handleFeedback = useCallback((message, index, value) => {
+		if (message.feedback === value) return;
+		const updatedMessage = {
+			...message,
+			feedback: value
+		};
+		const updatedMessages = messages.map((item, itemIndex) => itemIndex === index ? updatedMessage : item);
+		setMessages(updatedMessages);
+		const actionPayload = buildActionPayload({
+			type: value,
+			message: updatedMessage,
+			messages: updatedMessages,
+			index,
+			surface
+		});
+		emitAskAIAction(actionPayload);
+		const feedbackPayload = toFeedbackPayload(actionPayload);
+		if (feedbackPayload) emitAskAIFeedback(feedbackPayload, analytics);
+	}, [
+		analytics,
+		messages,
+		setMessages,
+		surface
+	]);
+	const handleCopyMessage = useCallback(async (message, index) => {
+		const copied = await copyTextToClipboard(message.content);
+		emitAskAIAction(buildActionPayload({
+			type: "copy",
+			message,
+			messages,
+			index,
+			surface,
+			copied
+		}));
+		return copied;
+	}, [messages, surface]);
 	return /* @__PURE__ */ jsxs("div", {
 		style: {
 			display: "flex",
@@ -536,10 +792,14 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 					children: msg.content
 				}) : /* @__PURE__ */ jsx("div", {
 					className: "fd-ai-bubble-ai",
-					children: msg.content ? /* @__PURE__ */ jsx("div", {
+					children: msg.content ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
 						className: isStreaming && i === messages.length - 1 ? "fd-ai-streaming" : void 0,
 						dangerouslySetInnerHTML: { __html: renderMarkdown(msg.content) }
-					}) : loadingComponentHtml ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: loadingComponentHtml } }) : /* @__PURE__ */ jsx(LoaderIndicator, {
+					}), feedbackEnabled && !msg.isError && !isStreaming && /* @__PURE__ */ jsx(AIFeedbackControls, {
+						value: msg.feedback,
+						onCopy: () => handleCopyMessage(msg, i),
+						onSelect: (value) => handleFeedback(msg, i, value)
+					})] }) : loadingComponentHtml ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: loadingComponentHtml } }) : /* @__PURE__ */ jsx(LoaderIndicator, {
 						variant: loaderVariant,
 						label
 					})
@@ -600,7 +860,7 @@ function AIChat({ api, messages, setMessages, aiInput, setAiInput, isStreaming,
 		})]
 	});
 }
-function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false }) {
+function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [tab, setTab] = useState("search");
 	const [searchQuery, setSearchQuery] = useState("");
 	const [searchResults, setSearchResults] = useState([]);
@@ -849,6 +1109,7 @@ function DocsSearchDialog({ open, onOpenChange, api = "/api/docs", suggestedQues
 				models,
 				defaultModelId: effectiveModelId,
 				analytics,
+				feedbackEnabled,
 				surface: "ai-dialog"
 			})
 		]
@@ -923,7 +1184,7 @@ function getContainerStyles(style, position) {
 function getAnimation(style) {
 	return style === "modal" ? "fd-ai-float-center-in 200ms ease-out" : "fd-ai-float-in 200ms ease-out";
 }
-function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false }) {
+function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [mounted, setMounted] = useState(false);
 	const [isOpen, setIsOpen] = useState(false);
 	const [messages, setMessages] = useState([]);
@@ -980,7 +1241,8 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 		position,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	});
 	const btnPosition = BTN_POSITIONS[position] || BTN_POSITIONS["bottom-right"];
 	const isModal = floatingStyle === "modal";
@@ -1028,7 +1290,10 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 				aiLabel,
 				loaderVariant,
 				loadingComponentHtml,
+				models,
+				defaultModelId,
 				analytics,
+				feedbackEnabled,
 				surface: "floating"
 			})]
 		}),
@@ -1064,7 +1329,7 @@ function FloatingAIChat({ api = "/api/docs", position = "bottom-right", floating
 		}))
 	] }), document.body);
 }
-function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, triggerComponentHtml, position, models, defaultModelId, analytics }) {
+function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessages, aiInput, setAiInput, isStreaming, setIsStreaming, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, triggerComponentHtml, position, models, defaultModelId, analytics, feedbackEnabled = true }) {
 	const label = aiLabel || "AI";
 	const inputRef = useRef(null);
 	const listRef = useRef(null);
@@ -1090,12 +1355,15 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 			content: question
 		};
 		const newMessages = [...messages, userMessage];
+		const assistantMessage = {
+			role: "assistant",
+			content: "",
+			id: createAIMessageId(),
+			model: effectiveModelId
+		};
 		setAiInput("");
 		setIsStreaming(true);
-		setMessages([...newMessages, {
-			role: "assistant",
-			content: ""
-		}]);
+		setMessages([...newMessages, assistantMessage]);
 		const startedAt = Date.now();
 		if (analytics) emitClientAnalyticsEvent({
 			type: "ai_question",
@@ -1124,8 +1392,9 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 					errMsg = (await res.json()).error || errMsg;
 				} catch {}
 				setMessages([...newMessages, {
-					role: "assistant",
-					content: errMsg
+					...assistantMessage,
+					content: errMsg,
+					isError: true
 				}]);
 				setIsStreaming(false);
 				if (analytics) emitClientAnalyticsEvent({
@@ -1157,7 +1426,7 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 						if (content) {
 							assistantContent += content;
 							setMessages([...newMessages, {
-								role: "assistant",
+								...assistantMessage,
 								content: assistantContent
 							}]);
 						}
@@ -1165,7 +1434,7 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 				}
 			}
 			if (assistantContent) setMessages([...newMessages, {
-				role: "assistant",
+				...assistantMessage,
 				content: assistantContent
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
@@ -1180,8 +1449,9 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 			});
 		} catch {
 			setMessages([...newMessages, {
-				role: "assistant",
-				content: "Failed to connect. Please try again."
+				...assistantMessage,
+				content: "Failed to connect. Please try again.",
+				isError: true
 			}]);
 			if (analytics) emitClientAnalyticsEvent({
 				type: "ai_error",
@@ -1205,6 +1475,41 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 	]);
 	const canSend = !!(aiInput.trim() && !isStreaming);
 	const showSuggestions = messages.length === 0 && !isStreaming;
+	const handleFeedback = useCallback((message, index, value) => {
+		if (message.feedback === value) return;
+		const updatedMessage = {
+			...message,
+			feedback: value
+		};
+		const updatedMessages = messages.map((item, itemIndex) => itemIndex === index ? updatedMessage : item);
+		setMessages(updatedMessages);
+		const actionPayload = buildActionPayload({
+			type: value,
+			message: updatedMessage,
+			messages: updatedMessages,
+			index,
+			surface: "full-modal"
+		});
+		emitAskAIAction(actionPayload);
+		const feedbackPayload = toFeedbackPayload(actionPayload);
+		if (feedbackPayload) emitAskAIFeedback(feedbackPayload, analytics);
+	}, [
+		analytics,
+		messages,
+		setMessages
+	]);
+	const handleCopyMessage = useCallback(async (message, index) => {
+		const copied = await copyTextToClipboard(message.content);
+		emitAskAIAction(buildActionPayload({
+			type: "copy",
+			message,
+			messages,
+			index,
+			surface: "full-modal",
+			copied
+		}));
+		return copied;
+	}, [messages]);
 	const handleKeyDown = (e) => {
 		if (e.key === "Enter" && !e.shiftKey) {
 			e.preventDefault();
@@ -1237,10 +1542,14 @@ function FullModalAIChat({ api, isOpen, setIsOpen, closeAI, messages, setMessage
 						children: msg.role === "user" ? "you" : label
 					}), /* @__PURE__ */ jsx("div", {
 						className: "fd-ai-fm-msg-content",
-						children: msg.content ? /* @__PURE__ */ jsx("div", {
+						children: msg.content ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("div", {
 							className: isStreaming && i === messages.length - 1 ? "fd-ai-streaming" : void 0,
 							dangerouslySetInnerHTML: { __html: renderMarkdown(msg.content) }
-						}) : loadingComponentHtml ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: loadingComponentHtml } }) : /* @__PURE__ */ jsx(LoaderIndicator, {
+						}), msg.role === "assistant" && feedbackEnabled && !msg.isError && !isStreaming && /* @__PURE__ */ jsx(AIFeedbackControls, {
+							value: msg.feedback,
+							onCopy: () => handleCopyMessage(msg, i),
+							onSelect: (value) => handleFeedback(msg, i, value)
+						})] }) : loadingComponentHtml ? /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: loadingComponentHtml } }) : /* @__PURE__ */ jsx(LoaderIndicator, {
 							variant: loaderVariant,
 							label
 						})
@@ -1368,7 +1677,7 @@ function TrashIcon() {
 		]
 	});
 }
-function AIModalDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false }) {
+function AIModalDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const [messages, setMessages] = useState([]);
 	const [aiInput, setAiInput] = useState("");
 	const [isStreaming, setIsStreaming] = useState(false);
@@ -1450,6 +1759,7 @@ function AIModalDialog({ open, onOpenChange, api = "/api/docs", suggestedQuestio
 				models,
 				defaultModelId,
 				analytics,
+				feedbackEnabled,
 				surface: "modal"
 			}),
 			/* @__PURE__ */ jsx("div", {

package/dist/docs-ai-features.d.mts

@@ -18,6 +18,7 @@ interface DocsAIFeaturesProps {
   }[];
   defaultModelId?: string;
   analytics?: boolean;
+  feedbackEnabled?: boolean;
 }
 declare function DocsAIFeatures({
   mode,
@@ -32,7 +33,8 @@ declare function DocsAIFeatures({
   loadingComponentHtml,
   models,
   defaultModelId,
-  analytics
+  analytics,
+  feedbackEnabled
 }: DocsAIFeaturesProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { DocsAIFeatures };

package/dist/docs-ai-features.mjs

@@ -22,7 +22,7 @@ import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 * This component is rendered inside the docs layout so the user's root layout
 * never needs to be modified — AI features work purely from `docs.config.ts`.
 */
-function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false }) {
+function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-right", floatingStyle = "panel", triggerComponentHtml, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics = false, feedbackEnabled = true }) {
 	const localizedApi = withLangInUrl(api, resolveClientLocale(useWindowSearchParams(), locale));
 	if (mode === "search") return /* @__PURE__ */ jsx(SearchModeAI, {
 		api: localizedApi,
@@ -32,7 +32,8 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	});
 	if (mode === "sidebar-icon") return /* @__PURE__ */ jsx(SidebarIconModeAI, {
 		api: localizedApi,
@@ -42,7 +43,8 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	});
 	return /* @__PURE__ */ jsx(FloatingAIChat, {
 		api: localizedApi,
@@ -55,10 +57,11 @@ function DocsAIFeatures({ mode, api = "/api/docs", locale, position = "bottom-ri
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	});
 }
-function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics }) {
+function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
 	const [open, setOpen] = useState(false);
 	useEffect(() => {
 		function handler(e) {
@@ -111,10 +114,11 @@ function SearchModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loading
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	});
 }
-function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics }) {
+function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, loadingComponentHtml, models, defaultModelId, analytics, feedbackEnabled }) {
 	const [searchOpen, setSearchOpen] = useState(false);
 	const [aiOpen, setAiOpen] = useState(false);
 	useEffect(() => {
@@ -167,7 +171,8 @@ function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, lo
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	}), /* @__PURE__ */ jsx(AIModalDialog, {
 		open: aiOpen,
 		onOpenChange: setAiOpen,
@@ -178,7 +183,8 @@ function SidebarIconModeAI({ api, suggestedQuestions, aiLabel, loaderVariant, lo
 		loadingComponentHtml,
 		models,
 		defaultModelId,
-		analytics
+		analytics,
+		feedbackEnabled
 	})] });
 }
 

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsI18nConfig, DocsMcpConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -19,6 +19,10 @@ interface AIOptions {
   model?: string | AIModelConfig;
   providers?: Record<string, AIProviderConfig>;
   systemPrompt?: string;
+  /** Package name the AI should use in import examples. */
+  packageName?: string;
+  /** Public docs URL the AI should use for absolute links. */
+  docsUrl?: string;
   /** Default baseUrl when no per-model provider is configured. */
   baseUrl?: string;
   /** Default apiKey when no per-model provider is configured. */
@@ -43,6 +47,8 @@ interface DocsAPIOptions {
   search?: boolean | DocsSearchConfig;
   /** Analytics configuration */
   analytics?: boolean | DocsAnalyticsConfig;
+  /** Observability configuration for logs, traces, and metrics callbacks. */
+  observability?: boolean | DocsObservabilityConfig;
   /** Feedback configuration */
   feedback?: boolean | FeedbackConfig;
   /** MCP configuration used for the agent discovery spec. */
@@ -59,6 +65,7 @@ interface DocsMCPAPIOptions {
   mcp?: boolean | DocsMcpConfig;
   search?: boolean | DocsSearchConfig;
   analytics?: boolean | DocsAnalyticsConfig;
+  observability?: boolean | DocsObservabilityConfig;
 }
 /**
  * Create a unified docs API route handler.

package/dist/docs-api.mjs

@@ -3,7 +3,7 @@ import { getNextAppDir } from "./get-app-dir.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { emitDocsAnalyticsEvent, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
+import { buildDocsAskAIContext, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
 import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -414,13 +414,17 @@ function readAIConfig(root) {
 			const apiKeyMatch = content.match(/ai\s*:\s*\{[^}]*apiKey\s*:\s*process\.env\.(\w+)/s);
 			const maxResultsMatch = content.match(/ai\s*:\s*\{[^}]*maxResults\s*:\s*(\d+)/s);
 			const systemPromptMatch = content.match(/ai\s*:\s*\{[^}]*systemPrompt\s*:\s*["'`]([^"'`]+)["'`]/s);
+			const packageNameMatch = content.match(/ai\s*:\s*\{[^}]*packageName\s*:\s*["'`]([^"'`]+)["'`]/s);
+			const docsUrlMatch = content.match(/ai\s*:\s*\{[^}]*docsUrl\s*:\s*["'`]([^"'`]+)["'`]/s);
 			return {
 				enabled: true,
 				model: modelMatch?.[1],
 				baseUrl: baseUrlMatch?.[1],
 				apiKey: apiKeyMatch?.[1] ? process.env[apiKeyMatch[1]] : void 0,
 				maxResults: maxResultsMatch ? parseInt(maxResultsMatch[1], 10) : void 0,
-				systemPrompt: systemPromptMatch?.[1]
+				systemPrompt: systemPromptMatch?.[1],
+				packageName: packageNameMatch?.[1],
+				docsUrl: docsUrlMatch?.[1]
 			};
 		} catch {}
 	}
@@ -936,7 +940,21 @@ function truncateSkillDescription(value) {
 function toYamlString(value) {
 	return JSON.stringify(value);
 }
-const DEFAULT_SYSTEM_PROMPT = `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. Use markdown formatting for code examples and links.`;
+function buildDefaultSystemPrompt(aiConfig) {
+	const lines = [
+		"You are a helpful documentation assistant.",
+		"Answer only from the provided documentation context.",
+		"Prefer exact code/config snippets from the context when the question asks how to implement something.",
+		"Cite the relevant documentation URL when you use a source.",
+		"Use only URLs exactly as they appear in the context; do not invent placeholder domains.",
+		"Never use placeholder package names or imports such as \"your-auth-library\", \"your-package\", \"your-sdk\", \"replace-me\", or \"example-library\". If the exact package or import is not in the context, do not include an import snippet.",
+		"Be concise and accurate. If the answer is not in the context, say so honestly.",
+		"Use markdown formatting for code examples and links."
+	];
+	if (aiConfig.packageName) lines.push(`When showing import examples, use "${aiConfig.packageName}" as the package name and prefer exact imports copied from the documentation context.`);
+	if (aiConfig.docsUrl) lines.push(`When linking to documentation pages, use "${aiConfig.docsUrl}" as the base URL (e.g. ${aiConfig.docsUrl}/docs/get-started).`);
+	return lines.join(" ");
+}
 function resolveModelAndProvider(aiConfig, requestedModelId) {
 	const raw = aiConfig.model;
 	const modelList = typeof raw === "object" && raw?.models || [];
@@ -956,9 +974,74 @@ function resolveModelAndProvider(aiConfig, requestedModelId) {
 		apiKey
 	};
 }
-async function handleAskAI(request, indexes, aiConfig, analytics, analyticsContext = {}) {
+function safeUrlOrigin(value) {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return value;
+	}
+}
+async function handleAskAI(request, indexes, aiConfig, search, analytics, observability, analyticsContext = {}) {
 	const url = new URL(request.url);
 	const requestStartedAt = Date.now();
+	const trace = createDocsAgentTraceContext("ask-ai");
+	const runSpanId = createDocsAgentTraceId("span");
+	const traceBase = {
+		source: "server",
+		traceId: trace.traceId,
+		url: request.url,
+		path: url.pathname,
+		locale: analyticsContext.locale
+	};
+	async function emitTrace(event) {
+		await emitDocsAgentTraceEvent(observability, {
+			...traceBase,
+			...event
+		});
+	}
+	async function emitRunError(reason, outputPreview = {}) {
+		const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const elapsed = Math.max(0, Date.now() - requestStartedAt);
+		const common = {
+			name: "ask-ai",
+			startedAt: trace.startedAt,
+			endedAt,
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: {
+				reason,
+				...outputPreview
+			},
+			metadata: { reason }
+		};
+		await emitTrace({
+			...common,
+			type: "error",
+			parentSpanId: runSpanId
+		});
+		await emitTrace({
+			...common,
+			type: "run.error",
+			spanId: runSpanId
+		});
+		await emitTrace({
+			...common,
+			type: "run.end",
+			spanId: runSpanId
+		});
+	}
+	await emitTrace({
+		type: "run.start",
+		name: "ask-ai",
+		spanId: runSpanId,
+		startedAt: trace.startedAt,
+		durationMs: 0,
+		status: "started",
+		inputPreview: {
+			method: request.method,
+			path: url.pathname
+		}
+	});
 	let body;
 	try {
 		body = await request.json();
@@ -974,6 +1057,7 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("invalid_json", { status: 400 });
 		return Response.json({ error: "Invalid JSON body. Expected { messages: [...] }" }, { status: 400 });
 	}
 	const messages = body.messages;
@@ -989,6 +1073,7 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_messages", { status: 400 });
 		return Response.json({ error: "messages array is required and must not be empty." }, { status: 400 });
 	}
 	const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
@@ -1005,27 +1090,101 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_user_message", {
+			status: 400,
+			messageCount: messages.length
+		});
 		return Response.json({ error: "At least one user message is required." }, { status: 400 });
 	}
 	const maxResults = aiConfig.maxResults ?? 5;
 	const query = lastUserMessage.content;
-	const scored = indexes.map((doc) => {
-		const q = query.toLowerCase();
-		const titleMatch = doc.title.toLowerCase().includes(q) ? 10 : 0;
-		const contentMatch = q.split(/\s+/).reduce((score, word) => {
-			return score + (doc.content.toLowerCase().includes(word) ? 1 : 0);
-		}, 0);
-		return {
-			...doc,
-			score: titleMatch + contentMatch
-		};
-	}).filter((d) => d.score > 0).sort((a, b) => b.score - a.score).slice(0, maxResults);
-	const context = scored.map((doc) => `## ${doc.title}\nURL: ${doc.url}\n${doc.description ? `Description: ${doc.description}\n` : ""}\n${doc.content}`).join("\n\n---\n\n");
-	const systemPrompt = aiConfig.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
-	const llmMessages = [{
+	await emitTrace({
+		type: "user.input",
+		name: "ask-ai",
+		parentSpanId: runSpanId,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: 0,
+		status: "success",
+		inputPreview: {
+			messageCount: messages.length,
+			questionLength: query.length,
+			requestedModel: typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0
+		}
+	});
+	const retrievalStartedAt = Date.now();
+	const retrievalStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const retrievalSpanId = createDocsAgentTraceId("span");
+	await emitTrace({
+		type: "retrieval.query",
+		name: "docs-index",
+		spanId: retrievalSpanId,
+		parentSpanId: runSpanId,
+		startedAt: retrievalStartedAtIso,
+		status: "started",
+		inputPreview: {
+			queryLength: query.length,
+			maxResults,
+			indexSize: indexes.length
+		}
+	});
+	const retrieval = await buildDocsAskAIContext({
+		pages: indexes,
+		query,
+		search,
+		locale: analyticsContext.locale,
+		pathname: url.searchParams.get("pathname") ?? void 0,
+		siteTitle: "Documentation",
+		baseUrl: url.origin,
+		limit: maxResults
+	});
+	const scored = retrieval.results;
+	await emitTrace({
+		type: "retrieval.result",
+		name: "docs-index",
+		parentSpanId: retrievalSpanId,
+		startedAt: retrievalStartedAtIso,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: Math.max(0, Date.now() - retrievalStartedAt),
+		status: "success",
+		outputPreview: {
+			resultCount: scored.length,
+			urls: scored.slice(0, 5).map((doc) => doc.url)
+		},
+		metadata: {
+			maxResults,
+			indexSize: indexes.length
+		}
+	});
+	const promptStartedAt = Date.now();
+	const promptStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const promptSpanId = createDocsAgentTraceId("span");
+	const context = retrieval.context;
+	const fullSystemPrompt = [aiConfig.systemPrompt ?? buildDefaultSystemPrompt(aiConfig), formatDocsAskAIPackageHints(retrieval.packageHints, aiConfig.packageName)].filter(Boolean).join("\n\n");
+	const systemMessage = {
 		role: "system",
-		content: context ? `${systemPrompt}\n\n---\n\nDocumentation context:\n\n${context}` : systemPrompt
-	}, ...messages.filter((m) => m.role !== "system")];
+		content: context ? `${fullSystemPrompt}\n\n---\n\nDocumentation context:\n\n${context}` : fullSystemPrompt
+	};
+	const llmMessages = [systemMessage, ...messages.filter((m) => m.role !== "system")];
+	await emitTrace({
+		type: "prompt.build",
+		name: "ask-ai.prompt",
+		spanId: promptSpanId,
+		parentSpanId: runSpanId,
+		startedAt: promptStartedAtIso,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: Math.max(0, Date.now() - promptStartedAt),
+		status: "success",
+		inputPreview: {
+			messageCount: messages.length,
+			retrievedCount: scored.length
+		},
+		outputPreview: {
+			llmMessageCount: llmMessages.length,
+			contextChars: context.length,
+			systemMessageChars: systemMessage.content.length
+		}
+	});
 	const resolved = resolveModelAndProvider(aiConfig, typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0);
 	if (!resolved.apiKey) {
 		await emitDocsAnalyticsEvent(analytics, {
@@ -1044,6 +1203,13 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_api_key", {
+			status: 500,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
 		return Response.json({ error: `AI is enabled but no API key was found. Either set apiKey in your docs.config ai section, configure a provider, or add OPENAI_API_KEY to your .env.local file.` }, { status: 500 });
 	}
 	await emitDocsAnalyticsEvent(analytics, {
@@ -1060,20 +1226,100 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 			model: resolved.model
 		}
 	});
-	const llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Authorization: `Bearer ${resolved.apiKey}`
-		},
-		body: JSON.stringify({
-			model: resolved.model,
+	const modelStartedAt = Date.now();
+	const modelStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const modelSpanId = createDocsAgentTraceId("span");
+	const providerOrigin = safeUrlOrigin(resolved.baseUrl);
+	await emitTrace({
+		type: "model.call",
+		name: resolved.model,
+		spanId: modelSpanId,
+		parentSpanId: runSpanId,
+		startedAt: modelStartedAtIso,
+		status: "started",
+		inputPreview: {
+			messageCount: llmMessages.length,
 			stream: true,
-			messages: llmMessages
-		})
+			providerOrigin
+		},
+		metadata: { model: resolved.model }
 	});
+	let llmResponse;
+	try {
+		llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${resolved.apiKey}`
+			},
+			body: JSON.stringify({
+				model: resolved.model,
+				stream: true,
+				messages: llmMessages
+			})
+		});
+	} catch (error) {
+		const elapsed = Math.max(0, Date.now() - modelStartedAt);
+		const message = error instanceof Error ? error.message : "Unknown error";
+		await emitTrace({
+			type: "model.error",
+			name: resolved.model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: { message },
+			metadata: {
+				model: resolved.model,
+				providerOrigin
+			}
+		});
+		await emitDocsAnalyticsEvent(analytics, {
+			type: "api_ai_error",
+			source: "server",
+			url: request.url,
+			path: url.pathname,
+			locale: analyticsContext.locale,
+			input: { question: query },
+			properties: {
+				reason: "llm_fetch_error",
+				messageCount: messages.length,
+				questionLength: query.length,
+				retrievedCount: scored.length,
+				model: resolved.model,
+				durationMs: Math.max(0, Date.now() - requestStartedAt)
+			}
+		});
+		await emitRunError("llm_fetch_error", {
+			status: 502,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
+		return Response.json({ error: "LLM API request failed." }, { status: 502 });
+	}
 	if (!llmResponse.ok) {
 		const errText = await llmResponse.text().catch(() => "Unknown error");
+		const elapsed = Math.max(0, Date.now() - modelStartedAt);
+		await emitTrace({
+			type: "model.error",
+			name: resolved.model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: {
+				status: llmResponse.status,
+				errorChars: errText.length
+			},
+			metadata: {
+				model: resolved.model,
+				providerOrigin
+			}
+		});
 		await emitDocsAnalyticsEvent(analytics, {
 			type: "api_ai_error",
 			source: "server",
@@ -1091,6 +1337,14 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("llm_error", {
+			status: 502,
+			modelStatus: llmResponse.status,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
 		return Response.json({ error: `LLM API error (${llmResponse.status}): ${errText}` }, { status: 502 });
 	}
 	await emitDocsAnalyticsEvent(analytics, {
@@ -1108,6 +1362,66 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 			durationMs: Math.max(0, Date.now() - requestStartedAt)
 		}
 	});
+	const responseEndedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const modelDurationMs = Math.max(0, Date.now() - modelStartedAt);
+	await emitTrace({
+		type: "model.response",
+		name: resolved.model,
+		parentSpanId: modelSpanId,
+		startedAt: modelStartedAtIso,
+		endedAt: responseEndedAt,
+		durationMs: modelDurationMs,
+		status: "success",
+		outputPreview: {
+			status: llmResponse.status,
+			stream: true,
+			contentType: llmResponse.headers.get("content-type") ?? void 0
+		},
+		metadata: {
+			model: resolved.model,
+			providerOrigin
+		}
+	});
+	await emitTrace({
+		type: "model.stream",
+		name: resolved.model,
+		parentSpanId: modelSpanId,
+		startedAt: modelStartedAtIso,
+		endedAt: responseEndedAt,
+		durationMs: modelDurationMs,
+		status: "success",
+		outputPreview: { stream: true },
+		metadata: { model: resolved.model }
+	});
+	const runDurationMs = Math.max(0, Date.now() - requestStartedAt);
+	await emitTrace({
+		type: "agent.final",
+		name: "ask-ai",
+		parentSpanId: runSpanId,
+		startedAt: trace.startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: runDurationMs,
+		status: "success",
+		outputPreview: {
+			stream: true,
+			retrievedCount: scored.length
+		},
+		metadata: { model: resolved.model }
+	});
+	await emitTrace({
+		type: "run.end",
+		name: "ask-ai",
+		spanId: runSpanId,
+		startedAt: trace.startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: runDurationMs,
+		status: "success",
+		outputPreview: {
+			stream: true,
+			retrievedCount: scored.length
+		},
+		metadata: { model: resolved.model }
+	});
 	return new Response(llmResponse.body, { headers: {
 		"Content-Type": "text/event-stream",
 		"Cache-Control": "no-cache",
@@ -1188,6 +1502,7 @@ function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
 	const entry = options?.entry ?? readEntry(root);
 	const analytics = options?.analytics;
+	const observability = options?.observability;
 	const appDir = getNextAppDir(root);
 	const contentDir = options?.contentDir ?? path.join(appDir, entry);
 	const changelogConfig = resolveChangelogConfig(options?.changelog);
@@ -1586,7 +1901,7 @@ function createDocsAPI(options) {
 				return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			}
 			const ctx = resolveContextFromRequest(request);
-			return handleAskAI(request, getIndexes(ctx), aiConfig, analytics, { locale: ctx.locale });
+			return handleAskAI(request, getIndexes(ctx), aiConfig, resolveSearchRequestConfig(searchConfig, request.url), analytics, observability, { locale: ctx.locale });
 		}
 	};
 }
@@ -1616,6 +1931,7 @@ function createDocsMCPAPI(options = {}) {
 		mcp: options.mcp ?? readMcpConfig(rootDir),
 		search: options.search,
 		analytics: options.analytics,
+		observability: options.observability,
 		defaultName: navTitle
 	});
 	return {

package/dist/docs-client-hooks.d.mts

@@ -1,15 +1,21 @@
-import { CodeBlockCopyData, DocsAnalyticsConfig, DocsFeedbackData } from "@farming-labs/docs";
+import { CodeBlockCopyData, DocsAnalyticsConfig, DocsAskAIActionData, DocsAskAIFeedbackData, DocsFeedbackData } from "@farming-labs/docs";
 
 //#region src/docs-client-hooks.d.ts
 type CopyHandler = (data: CodeBlockCopyData) => void;
 type FeedbackHandler = (data: DocsFeedbackData) => void | Promise<void>;
+type AIActionHandler = (data: DocsAskAIActionData) => void | Promise<void>;
+type AIFeedbackHandler = (data: DocsAskAIFeedbackData) => void | Promise<void>;
 declare function DocsClientHooks({
   onCopyClick,
   onFeedback,
+  onAIActions,
+  onAIFeedback,
   analytics
 }: {
   onCopyClick?: CopyHandler;
   onFeedback?: FeedbackHandler;
+  onAIActions?: AIActionHandler;
+  onAIFeedback?: AIFeedbackHandler;
   analytics?: boolean | DocsAnalyticsConfig;
 }): null;
 //#endregion

package/dist/docs-client-hooks.mjs

@@ -65,9 +65,11 @@ function useCodeCopyAnalytics(analytics) {
 		return () => document.removeEventListener("click", handleClick, true);
 	}, [analytics]);
 }
-function DocsClientHooks({ onCopyClick, onFeedback, analytics }) {
+function DocsClientHooks({ onCopyClick, onFeedback, onAIActions, onAIFeedback, analytics }) {
 	useWindowHook("__fdOnCopyClick__", onCopyClick);
 	useWindowHook("__fdOnFeedback__", onFeedback);
+	useWindowHook("__fdOnAIActions__", onAIActions);
+	useWindowHook("__fdOnAIFeedback__", onAIFeedback);
 	useAnalyticsHook(analytics);
 	useCodeCopyAnalytics(analytics);
 	return null;

package/dist/docs-layout.mjs

@@ -622,6 +622,7 @@ function createDocsLayout(config, options) {
 	const aiSuggestedQuestions = aiConfig?.suggestedQuestions;
 	const aiLabel = aiConfig?.aiLabel;
 	const aiLoaderVariant = aiConfig?.loader;
+	const aiFeedbackEnabled = aiConfig?.feedback === false || typeof aiConfig?.feedback === "object" && aiConfig.feedback.enabled === false ? false : true;
 	const aiLoadingComponentHtml = typeof aiConfig?.loadingComponent === "function" ? serializeIcon(aiConfig.loadingComponent({ name: aiLabel || "AI" })) : void 0;
 	const rawModelConfig = aiConfig?.model;
 	let aiModels = aiConfig?.models;
@@ -707,7 +708,8 @@ function createDocsLayout(config, options) {
 						loadingComponentHtml: aiLoadingComponentHtml,
 						models: aiModels,
 						defaultModelId: aiDefaultModelId,
-						analytics: analyticsEnabled
+						analytics: analyticsEnabled,
+						feedbackEnabled: aiFeedbackEnabled
 					})
 				}),
 				/* @__PURE__ */ jsx(Suspense, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -139,7 +139,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.71"
+    "@farming-labs/docs": "0.1.73"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",

package/styles/ai.css

@@ -337,6 +337,48 @@
   animation: fd-ai-msg-in 300ms ease-out;
 }
 
+.fd-ai-feedback {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-top: 10px;
+  padding-top: 8px;
+  border-top: 1px solid color-mix(in srgb, var(--color-fd-border, #1f1f2e) 70%, transparent);
+}
+
+.fd-ai-feedback-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  border: 1px solid transparent;
+  border-radius: var(--radius, 6px);
+  background: transparent;
+  color: var(--color-fd-muted-foreground, #71717a);
+  cursor: pointer;
+  transition:
+    background 150ms,
+    border-color 150ms,
+    color 150ms;
+}
+
+.fd-ai-feedback-btn:hover {
+  color: var(--color-fd-foreground, #e4e4e7);
+  background: var(--color-fd-accent, rgba(255, 255, 255, 0.06));
+}
+
+.fd-ai-feedback-btn[data-active="true"] {
+  color: var(--color-fd-primary, #6366f1);
+  border-color: color-mix(in srgb, var(--color-fd-primary, #6366f1) 40%, transparent);
+  background: color-mix(in srgb, var(--color-fd-primary, #6366f1) 10%, transparent);
+}
+
+.fd-ai-feedback-btn[data-copied="true"] {
+  color: var(--color-fd-primary, #6366f1);
+  background: color-mix(in srgb, var(--color-fd-primary, #6366f1) 10%, transparent);
+}
+
 @keyframes fd-ai-msg-in {
   from { opacity: 0; transform: translateY(6px); }
   to { opacity: 1; transform: translateY(0); }