diff --git a/docs.json b/docs.json
index c2183be45..3c9d036f8 100644
--- a/docs.json
+++ b/docs.json
@@ -234,9 +234,10 @@
                 "icon": "bot",
                 "pages": [
                   "guides/automate-agent",
-                  "guides/geo",
+                  "guides/assistant-embed",
                   "guides/claude-code",
                   "guides/cursor",
+                  "guides/geo",
                   "guides/windsurf"
                 ]
               },
diff --git a/guides/assistant-embed.mdx b/guides/assistant-embed.mdx
new file mode 100644
index 000000000..c00198aed
--- /dev/null
+++ b/guides/assistant-embed.mdx
@@ -0,0 +1,422 @@
+---
+title: "Tutorial: Build an in-app documentation assistant"
+sidebarTitle: "Build an in-app assistant"
+description: "Embed the assistant in your application to answer questions with information from your documentation"
+---
+
+import { PreviewButton } from "/snippets/previewbutton.jsx"
+
+## What you will build
+
+A reusable React component that embeds the [assistant](/ai/assistant) directly in your application. The component provides:
+
+- A floating widget that opens a chat panel when clicked
+- Real-time streaming responses based on information from your documentation
+
+Users can use the widget to get help with your product without leaving your application.
+
+<PreviewButton href="https://github.com/mintlify/assistant-embed-example">Clone the repository to start working with a complete example locally.</PreviewButton>
+
+## Prerequisites
+
+- [Mintlify Pro or Custom plan](https://mintlify.com/pricing)
+- Your domain name, which appears at the end of your dashboard URL. For example, if your dashboard URL is `https://dashboard.mintlify.com/org-name/domain-name`, your domain name is `domain-name`
+- An [assistant API key](https://dashboard.mintlify.com/settings/organization/api-keys)
+- Node.js v18 or higher and npm installed
+- Basic React knowledge
+- Existing React application (Next.js, Vite, Create React App, or similar). This guide uses a Vite application
+
+### Get your assistant API key
+
+1. Navigate to the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard.
+2. Click **Create Assistant API Key**.
+3. Copy the assistant API key (starts with `mint_dsc_`) and save it securely.
+
+<Note>
+  The assistant API key is a public token that can be used in frontend code. Calls using this token count toward your plan's message allowance and can incur overages.
+</Note>
+
+## Build the widget
+
+<Steps>
+<Step title="Install dependencies">
+
+Install the AI SDK for React and a Markdown renderer:
+
+```bash
+npm install ai @ai-sdk/react react-markdown
+```
+</Step>
+<Step title="Create the assistant component"> 
+
+Create a new file `AssistantWidget.jsx` (or `.tsx` if using TypeScript) in your components directory:
+
+```jsx AssistantWidget.jsx expandable
+import { useChat } from '@ai-sdk/react';
+import { useState } from 'react';
+import ReactMarkdown from 'react-markdown';
+
+const parseSuggestionLinks = (markdown, docsURL) => {
+  // Parse (text)[/path] format from suggestions code block
+  const links = markdown
+    .split('\n')
+    .map((line) => {
+      const match = line.match(/\(([^)]*)\)\[([^\]]*)\]/);
+      if (match && match[1] && match[2]) {
+        let url = match[2];
+        // Convert relative paths to absolute URLs if docsURL is provided
+        if (docsURL && url.startsWith('/')) {
+          const baseURL = docsURL.endsWith('/') ? docsURL.slice(0, -1) : docsURL;
+          url = `${baseURL}${url}`;
+        }
+        return { text: match[1], url };
+      }
+      return null;
+    })
+    .filter(Boolean);
+  return links;
+};
+
+export function AssistantWidget({ domain, docsURL }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`,
+    headers: {
+      'Authorization': `Bearer ${import.meta.env.VITE_MINTLIFY_TOKEN}`,
+    },
+    body: {
+      fp: 'anonymous',
+      retrievalPageSize: 5,
+    },
+    streamProtocol: 'data',
+    sendExtraMessageFields: true,
+  });
+
+  return (
+    <>
+      <button
+        onClick={() => setIsOpen(!isOpen)}
+        className="fixed bottom-4 right-4 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+      >
+        {isOpen ? 'Close' : 'Ask'}
+      </button>
+
+      {isOpen && (
+        <div className="fixed bottom-16 right-4 w-96 h-[500px] bg-white rounded-lg shadow-xl flex flex-col z-50 border border-gray-200">
+          <div className="p-4 border-b border-gray-200 bg-gray-50 rounded-t-lg">
+            <h3 className="font-semibold text-gray-900">Documentation assistant</h3>
+          </div>
+
+          <div className="flex-1 overflow-y-auto p-4 space-y-4">
+            {messages.map((message) => (
+              <div key={message.id} className={`flex ${message.role === 'user' ? 'justify-end' : 'justify-start'}`}>
+                <div className={`max-w-[85%] rounded-lg px-4 py-2 break-words ${message.role === 'user' ? 'bg-blue-600 text-white' : 'bg-gray-100 text-gray-900'}`}>
+                  {message.role === 'user' ? (
+                    <div className="text-sm whitespace-pre-wrap break-words">{message.content}</div>
+                  ) : (
+                    <div className="overflow-x-hidden">
+                      <ReactMarkdown
+                        className="prose prose-sm max-w-none text-sm break-words"
+                        components={{
+                          code: ({node, inline, className, children, ...props}) => {
+                            const match = /language-(\w+)/.exec(className || '');
+                            const language = match ? match[1] : undefined;
+
+                            // Handle suggestions code block
+                            if (language === 'suggestions' && typeof children === 'string') {
+                              const links = parseSuggestionLinks(children, docsURL);
+                              return (
+                                <div className="space-y-2 my-2">
+                                  {links.map((link, i) => (
+                                    <a
+                                      key={i}
+                                      href={link.url}
+                                      target="_blank"
+                                      rel="noopener noreferrer"
+                                      className="block px-3 py-2 bg-blue-50 text-blue-600 hover:bg-blue-100 rounded-lg text-sm"
+                                    >
+                                      {link.text}
+                                    </a>
+                                  ))}
+                                </div>
+                              );
+                            }
+
+                            // Fallback to default code rendering
+                            return (
+                              <code className={className} {...props}>
+                                {children}
+                              </code>
+                            );
+                          }
+                        }}
+                      >
+                        {message.content}
+                      </ReactMarkdown>
+                    </div>
+                  )}
+                </div>
+              </div>
+            ))}
+
+            {isLoading && <div className="text-gray-500 text-sm">Loading...</div>}
+          </div>
+
+          <form onSubmit={handleSubmit} className="p-4 border-t border-gray-200 bg-white rounded-b-lg">
+            <div className="flex gap-2">
+              <input
+                type="text"
+                value={input}
+                onChange={handleInputChange}
+                placeholder="Ask a question..."
+                className="flex-1 px-3 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500 text-sm"
+                disabled={isLoading}
+              />
+              <button
+                type="submit"
+                disabled={isLoading || !input.trim()}
+                className="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 disabled:bg-gray-400 text-sm"
+              >
+                Send
+              </button>
+            </div>
+          </form>
+        </div>
+      )}
+    </>
+  );
+}
+```
+
+</Step>
+<Step title="Configure environment variables">
+
+Add your assistant API token to your `.env` file in your project root:
+
+```bash .env
+VITE_MINTLIFY_TOKEN=mint_dsc_your_token_here
+```
+
+Restart your development server to apply the changes.
+
+<Note>
+  Vite requires environment variables to be prefixed with `VITE_`. Use the appropriate prefix for your framework.
+</Note>
+
+</Step>
+<Step title="Add the widget to your app">
+
+Import and render the component in your application.
+
+Pass the required props.
+
+*`domain`: Your Mintlify project domain found at the end of your dashboard URL. For example, `domain-name` from `https://dashboard.mintlify.com/org-name/domain-name`)
+*`docsURL`: The full URL to your documentation site. For example, `https://docs.yourcompany.com`. This prop converts relative links like `/quickstart` from the assistant to absolute URLs like `https://docs.yourcompany.com/quickstart`, which makes the links navigable.
+
+```jsx App.jsx
+import { AssistantWidget } from './components/AssistantWidget';
+
+function App() {
+  return (
+    <div>
+      {/* Your existing app content */}
+      <AssistantWidget
+        domain="yourcompany"
+        docsURL="https://docs.yourcompany.com"
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+</Step>
+<Step title="Test the widget">
+  1. Start your development server:
+   ```bash
+   npm run dev
+   ```
+  2. Open your application in a browser.
+  3. Click the "Ask" button in the bottom-right corner.
+  4. Ask a question about your documentation.
+</Step>
+</Steps>
+
+## Customization ideas
+
+This guide shows a minimal working implementation. This section shows some ways to begin customizing your assistant widget.
+
+The [example repository](https://github.com/mintlify/assistant-embed-example) includes several of these customizations already implemented, including color customization, positioning options, and source citations.
+
+### Add color customization
+
+Accept color props and use them for theming:
+
+```jsx
+export function AssistantWidget({ domain, buttonColor = '#2563eb' }) {
+  // ... rest of component
+  return (
+    <>
+      <button
+        style={{ backgroundColor: buttonColor }}
+        // ... rest of button
+      >
+```
+
+### Add widget positioning options
+
+Position the widget in different corners:
+
+```jsx
+export function AssistantWidget({ domain, position = 'bottom-right' }) {
+  const positions = {
+    'bottom-right': 'bottom-4 right-4',
+    'bottom-left': 'bottom-4 left-4',
+    'top-right': 'top-4 right-4',
+    'top-left': 'top-4 left-4',
+  };
+
+  return (
+    <>
+      <button className={`fixed ${positions[position]} ...`}
+```
+
+### Source citations
+
+Extract and display sources from assistant responses:
+
+```jsx
+const extractSources = (parts) => {
+  return parts
+    ?.filter(p => p.type === 'tool-invocation' && p.toolInvocation?.toolName === 'search')
+    .flatMap(p => p.toolInvocation?.result || [])
+    .map(source => ({
+      url: source.url || source.path,
+      title: source.metadata?.title || source.path,
+    })) || [];
+};
+
+// In your message rendering:
+{messages.map((message) => {
+  const sources = message.role === 'assistant' ? extractSources(message.parts) : [];
+  return (
+    <div key={message.id}>
+      {/* message content */}
+      {sources.length > 0 && (
+        <div className="mt-2 text-xs">
+          <p className="font-semibold">Sources:</p>
+          {sources.map((s, i) => (
+            <a key={i} href={s.url} target="_blank" className="text-blue-600">
+              {s.title}
+            </a>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+})}
+```
+
+### Track conversation thread IDs
+
+Store thread IDs to maintain conversation history across sessions:
+
+```jsx
+import { useState, useEffect } from 'react';
+
+export function AssistantWidget({ domain, docsURL }) {
+  const [threadId, setThreadId] = useState(null);
+
+  useEffect(() => {
+    // Retrieve saved thread ID from localStorage
+    const saved = localStorage.getItem('assistant-thread-id');
+    if (saved) {
+      setThreadId(saved);
+    }
+  }, []);
+
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
+    api: `https://api-dsc.mintlify.com/v1/assistant/${domain}/message`,
+    headers: {
+      'Authorization': `Bearer ${import.meta.env.VITE_MINTLIFY_TOKEN}`,
+    },
+    body: {
+      fp: 'anonymous',
+      retrievalPageSize: 5,
+      ...(threadId && { threadId }), // Include thread ID if available
+    },
+    streamProtocol: 'data',
+    sendExtraMessageFields: true,
+    fetch: async (url, options) => {
+      const response = await fetch(url, options);
+      const newThreadId = response.headers.get('x-thread-id');
+      if (newThreadId) {
+        setThreadId(newThreadId);
+        localStorage.setItem('assistant-thread-id', newThreadId);
+      }
+      return response;
+    },
+  });
+
+  // ... rest of component
+}
+```
+
+### Add keyboard shortcuts
+
+Allow users to open the widget and submit messages with keyboard shortcuts:
+
+```jsx
+useEffect(() => {
+  const handleKeyDown = (e) => {
+    // Cmd/Ctrl + Shift + I to toggle widget
+    if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key === 'I') {
+      e.preventDefault();
+      setIsOpen(!isOpen);
+    }
+
+    // Enter (when widget is focused) to submit
+    if (isOpen && e.key === 'Enter' && !e.shiftKey && document.activeElement.id === 'assistant-input') {
+      e.preventDefault();
+      handleSubmit();
+      setInput('');
+    }
+  };
+
+  window.addEventListener('keydown', handleKeyDown);
+  return () => window.removeEventListener('keydown', handleKeyDown);
+}, [isOpen, handleSubmit]);
+```
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Widget not appearing">
+    - Verify the component is imported and rendered in your app.
+    - Check that Tailwind CSS or your styling solution is properly configured.
+    - Ensure the z-index values do not conflict with other fixed elements.
+  </Accordion>
+
+  <Accordion title="401 authentication error">
+    - Verify your API token starts with `mint_dsc_`.
+    - Check the token is correctly set in your environment variables.
+    - Confirm you are using the public assistant API token, not the admin API key.
+    - Restart your development server after adding environment variables.
+  </Accordion>
+
+  <Accordion title="No responses from assistant">
+    - Verify your project domain is correct.
+    - Check that your Mintlify plan includes the assistant feature.
+    - Confirm your documentation site is published and accessible.
+    - Verify the assistant API token is correctly set in your environment variables.
+  </Accordion>
+
+  <Accordion title="Debugging with browser console">
+    Open developer tools and check the Network tab to troubleshoot:
+    - Look for 401 or 403 authentication errors
+    - Verify API requests are reaching `https://api-dsc.mintlify.com/v1/assistant/{domain}/message`
+    - Check the response status and error messages
+  </Accordion>
+</AccordionGroup>