From 3f800d4e74ba137a2903b773bae4f1d467c91382 Mon Sep 17 00:00:00 2001
From: Oreofe <oreofeolurin@gmail.com>
Date: Sun, 7 Jun 2026 05:04:34 +0100
Subject: [PATCH 1/3] feat(ai): auto-growing composer + graceful image
 attachments

Composer (ask-dock):
- Replace the single-line <input> with an auto-growing <textarea>: taller
  default (min 46px), grows with content up to 168px, then scrolls.
- Enter sends, Shift+Enter inserts a newline.
- Add an image attachment affordance (paperclip) shown ONLY when the model
  supports vision (modelSupportsVision heuristic or explicit ai.vision flag).
  Up to 4 images, 5MB each; thumbnails as removable chips, rendered in the
  user bubble. Image data is stripped before persisting chat history so we
  never blow the localStorage quota.

Plumbing:
- transport.buildMessages() now accepts images and emits OpenAI-style
  multimodal content parts.
- /api/ai proxy accepts and forwards up to 4 data:image/ URLs.
- aiConfig() exposes vision (inferred from model id, overridable via ai.vision).

Also folds in the earlier copy fixes: 'Ask questions about this page',
generic page-relevant suggestions, neutral context chip (no hardcoded
'API Reference'), and a shorter disclaimer.
---
 app/api-reference.css           |  16 +++-
 app/api/ai/route.ts             |   8 +-
 app/docs.css                    |  16 +++-
 components/docs/ai/ask-dock.tsx | 152 +++++++++++++++++++++++++++-----
 lib/ai/transport.ts             |  17 +++-
 lib/config.ts                   |  25 ++++++
 6 files changed, 204 insertions(+), 30 deletions(-)

diff --git a/app/api-reference.css b/app/api-reference.css
index 481879a..0070af5 100644
--- a/app/api-reference.css
+++ b/app/api-reference.css
@@ -501,11 +501,21 @@ body.aichat-open .ml-apiref .aichat { transform: none; }
 .ml-apiref .ac-ctx { display: inline-flex; align-items: center; gap: 8px; max-width: 100%; font-size: 12px; color: var(--accent-ink); background: var(--accent-dim); border: 1px solid var(--accent-line); border-radius: 8px; padding: 6px 10px; margin-bottom: 10px; }
 .ml-apiref .ac-ctx .bk { flex: none; display: inline-flex; }
 .ml-apiref .ac-ctx .ctxl { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.ml-apiref .ac-inwrap { display: flex; align-items: center; gap: 8px; border: 1px solid var(--line-2); border-radius: 11px; padding: 8px 8px 8px 13px; background: var(--panel-2); }
+.ml-apiref .ac-inwrap { display: flex; flex-direction: column; gap: 8px; border: 1px solid var(--line-2); border-radius: 11px; padding: 10px 10px 8px; background: var(--panel-2); }
 .ml-apiref .ac-inwrap:focus-within { border-color: var(--accent-line); }
-.ml-apiref .ac-in { flex: 1; min-width: 0; background: transparent; border: 0; outline: 0; font-family: var(--sans); font-size: 13.5px; color: var(--ink); }
+.ml-apiref .ac-in { width: 100%; min-height: 46px; max-height: 168px; resize: none; overflow-y: auto; background: transparent; border: 0; outline: 0; font-family: var(--sans); font-size: 13.5px; line-height: 1.5; color: var(--ink); }
 .ml-apiref .ac-in::placeholder { color: var(--ink-4); }
-.ml-apiref .ac-send { width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: var(--accent); color: var(--on-accent); }
+.ml-apiref .ac-inbar { display: flex; align-items: center; justify-content: space-between; }
+.ml-apiref .ac-attach { width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: transparent; color: var(--ink-4); cursor: pointer; }
+.ml-apiref .ac-attach:hover:not(:disabled) { background: color-mix(in srgb, var(--ink) 8%, transparent); color: var(--ink); }
+.ml-apiref .ac-attach:disabled { opacity: .4; cursor: default; }
+.ml-apiref .ac-attachments { display: flex; flex-wrap: wrap; gap: 6px; }
+.ml-apiref .ac-chip { position: relative; width: 46px; height: 46px; border-radius: 8px; overflow: hidden; border: 1px solid var(--line-2); }
+.ml-apiref .ac-chip img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.ml-apiref .ac-chip-x { position: absolute; top: 2px; right: 2px; width: 16px; height: 16px; display: grid; place-items: center; border: 0; border-radius: 50%; background: rgba(0,0,0,.6); color: #fff; cursor: pointer; padding: 0; }
+.ml-apiref .ac-msg-imgs { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 6px; }
+.ml-apiref .ac-msg-imgs img { max-width: 160px; max-height: 160px; border-radius: 8px; display: block; }
+.ml-apiref .ac-send { margin-left: auto; width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: var(--accent); color: var(--on-accent); cursor: pointer; }
 .ml-apiref .ac-send:hover { background: color-mix(in srgb, var(--accent) 86%, #fff); }
 .ml-apiref .ac-send:disabled { opacity: .4; }
 .ml-apiref .ac-send .ico { width: 15px; height: 15px; }
diff --git a/app/api/ai/route.ts b/app/api/ai/route.ts
index 0cefe61..eaa9d9e 100644
--- a/app/api/ai/route.ts
+++ b/app/api/ai/route.ts
@@ -46,7 +46,7 @@ export async function POST(req: Request) {
     return new Response("Rate limit exceeded", { status: 429 });
   }
 
-  let body: { question?: string; context?: string };
+  let body: { question?: string; context?: string; images?: string[] };
   try {
     body = await req.json();
   } catch {
@@ -55,6 +55,10 @@ export async function POST(req: Request) {
   const question = (body.question ?? "").trim().slice(0, 4000);
   if (!question) return new Response("Empty question", { status: 400 });
   const context = body.context?.slice(0, 8000);
+  // Accept up to 4 inline image data URLs (~base64). Drop anything else.
+  const images = Array.isArray(body.images)
+    ? body.images.filter((u) => typeof u === "string" && /^data:image\//.test(u)).slice(0, 4)
+    : undefined;
 
   const baseUrl = resolveAiBaseUrl(ai);
   try {
@@ -64,7 +68,7 @@ export async function POST(req: Request) {
       key,
       provider: ai.provider ?? "openai",
       maxTokens: ai.maxTokens ?? 1024,
-      messages: buildMessages(ai.systemPrompt, context, question),
+      messages: buildMessages(ai.systemPrompt, context, question, images),
       referer: req.headers.get("origin") ?? undefined,
       title: cfg.name,
     });
diff --git a/app/docs.css b/app/docs.css
index 387502f..922af94 100644
--- a/app/docs.css
+++ b/app/docs.css
@@ -397,11 +397,21 @@ body.aichat-open .docs-shell .aichat { transform: none; }
 .docs-shell .ac-ctx { display: inline-flex; align-items: center; gap: 8px; max-width: 100%; font-size: 12px; color: var(--accent-ink); background: var(--accent-dim); border: 1px solid var(--accent-line); border-radius: 8px; padding: 6px 10px; margin-bottom: 10px; }
 .docs-shell .ac-ctx .bk { flex: none; display: inline-flex; }
 .docs-shell .ac-ctx .ctxl { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.docs-shell .ac-inwrap { display: flex; align-items: center; gap: 8px; border: 1px solid var(--line-2); border-radius: 11px; padding: 8px 8px 8px 13px; background: var(--panel-2); }
+.docs-shell .ac-inwrap { display: flex; flex-direction: column; gap: 8px; border: 1px solid var(--line-2); border-radius: 11px; padding: 10px 10px 8px; background: var(--panel-2); }
 .docs-shell .ac-inwrap:focus-within { border-color: var(--accent-line); }
-.docs-shell .ac-in { flex: 1; min-width: 0; background: transparent; border: 0; outline: 0; font-family: inherit; font-size: 13.5px; color: var(--ink); }
+.docs-shell .ac-in { width: 100%; min-height: 46px; max-height: 168px; resize: none; overflow-y: auto; background: transparent; border: 0; outline: 0; font-family: inherit; font-size: 13.5px; line-height: 1.5; color: var(--ink); }
 .docs-shell .ac-in::placeholder { color: var(--ink-4); }
-.docs-shell .ac-send { width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: var(--accent); color: rgb(var(--c-on-brand)); cursor: pointer; }
+.docs-shell .ac-inbar { display: flex; align-items: center; justify-content: space-between; }
+.docs-shell .ac-attach { width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: transparent; color: var(--ink-4); cursor: pointer; }
+.docs-shell .ac-attach:hover:not(:disabled) { background: color-mix(in srgb, var(--ink) 8%, transparent); color: var(--ink); }
+.docs-shell .ac-attach:disabled { opacity: .4; cursor: default; }
+.docs-shell .ac-attachments { display: flex; flex-wrap: wrap; gap: 6px; }
+.docs-shell .ac-chip { position: relative; width: 46px; height: 46px; border-radius: 8px; overflow: hidden; border: 1px solid var(--line-2); }
+.docs-shell .ac-chip img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.docs-shell .ac-chip-x { position: absolute; top: 2px; right: 2px; width: 16px; height: 16px; display: grid; place-items: center; border: 0; border-radius: 50%; background: rgba(0,0,0,.6); color: #fff; cursor: pointer; padding: 0; }
+.docs-shell .ac-msg-imgs { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 6px; }
+.docs-shell .ac-msg-imgs img { max-width: 160px; max-height: 160px; border-radius: 8px; display: block; }
+.docs-shell .ac-send { margin-left: auto; width: 30px; height: 30px; flex: none; display: grid; place-items: center; border-radius: 8px; border: 0; background: var(--accent); color: rgb(var(--c-on-brand)); cursor: pointer; }
 .docs-shell .ac-send:hover { background: color-mix(in srgb, var(--accent) 86%, #fff); }
 .docs-shell .ac-send:disabled { opacity: .4; }
 .docs-shell .ac-send .ico { width: 15px; height: 15px; }
diff --git a/components/docs/ai/ask-dock.tsx b/components/docs/ai/ask-dock.tsx
index d5418de..36af555 100644
--- a/components/docs/ai/ask-dock.tsx
+++ b/components/docs/ai/ask-dock.tsx
@@ -25,14 +25,28 @@ export function openAskPanel(context?: string) {
   window.dispatchEvent(new CustomEvent("ml-ai-open", { detail: { context: context ?? null } }));
 }
 
-type Msg = { role: "user" | "ai"; text: string; sources?: string[]; error?: boolean };
+type Msg = { role: "user" | "ai"; text: string; sources?: string[]; error?: boolean; images?: string[] };
+type Attachment = { name: string; url: string };
+
+const MAX_ATTACHMENTS = 4;
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5 MB per image
+const COMPOSER_MAX_H = 168; // px — textarea grows to here, then scrolls
+
+function readAsDataUrl(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const r = new FileReader();
+    r.onload = () => resolve(String(r.result));
+    r.onerror = () => reject(r.error);
+    r.readAsDataURL(file);
+  });
+}
 type Chat = { title: string; messages: Msg[] };
 
 const CHATS_KEY = "markline-ai-chats";
 const OPEN_KEY = "markline-ai-open";
 const RKEY_KEY = "markline-ai-key";
 
-const SUGGEST = ["How do I authenticate requests?", "How do I create a resource?", "What does an error response look like?"];
+const SUGGEST = ["Summarize this page", "Explain this with an example", "What are the key concepts here?"];
 
 function trunc(s: string, n: number) {
   s = s.replace(/\s+/g, " ").trim();
@@ -78,8 +92,10 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
   const [thinking, setThinking] = useState(false);
   const [needKey, setNeedKey] = useState(false);
   const [keyDraft, setKeyDraft] = useState("");
+  const [attachments, setAttachments] = useState<Attachment[]>([]);
   const bodyRef = useRef<HTMLDivElement>(null);
-  const inputRef = useRef<HTMLInputElement>(null);
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+  const fileRef = useRef<HTMLInputElement>(null);
 
   const messages = chats[cur]?.messages ?? [];
 
@@ -97,10 +113,15 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     }
   }, []);
 
-  /* persist chats */
+  /* persist chats — drop inline image data so we never blow the localStorage
+     quota; the conversation text survives a reload, the thumbnails don't. */
   useEffect(() => {
     try {
-      localStorage.setItem(CHATS_KEY, JSON.stringify({ chats, cur }));
+      const slim = chats.map((c) => ({
+        ...c,
+        messages: c.messages.map(({ images, ...m }) => m),
+      }));
+      localStorage.setItem(CHATS_KEY, JSON.stringify({ chats: slim, cur }));
     } catch {
       /* ignore */
     }
@@ -125,6 +146,14 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     if (bodyRef.current) bodyRef.current.scrollTop = bodyRef.current.scrollHeight;
   }, [messages, thinking]);
 
+  /* auto-grow the composer textarea up to COMPOSER_MAX_H, then scroll */
+  useEffect(() => {
+    const el = inputRef.current;
+    if (!el) return;
+    el.style.height = "auto";
+    el.style.height = Math.min(el.scrollHeight, COMPOSER_MAX_H) + "px";
+  }, [input, open]);
+
   /* external open trigger + keyboard shortcuts */
   useEffect(() => {
     const onOpen = (e: Event) => {
@@ -179,8 +208,9 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     setMenu(false);
   }
 
-  async function callAi(question: string): Promise<{ text: string; sources: string[] }> {
+  async function callAi(question: string, images?: string[]): Promise<{ text: string; sources: string[] }> {
     const sources = pickSources();
+    const imgs = ai.vision && images?.length ? images : undefined;
     if (ai.mode === "byok") {
       let key = "";
       try {
@@ -200,7 +230,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
         key,
         provider: ai.provider,
         maxTokens: ai.maxTokens,
-        messages: buildMessages(undefined, `You are viewing the "${context}" section.`, question),
+        messages: buildMessages(undefined, `You are viewing the "${context}" section.`, question, imgs),
         referer: location.origin,
         title: document.title,
       });
@@ -210,23 +240,44 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     const res = await fetch(ai.endpoint || "/api/ai", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ question, context: `The user is viewing the "${context}" section.` }),
+      body: JSON.stringify({ question, context: `The user is viewing the "${context}" section.`, images: imgs }),
     });
     if (!res.ok) throw new Error((await res.text().catch(() => "")) || `Request failed (${res.status})`);
     const data = await res.json();
     return { text: (data.text || "").trim(), sources };
   }
 
+  async function addFiles(files: FileList | null) {
+    if (!files?.length) return;
+    const room = MAX_ATTACHMENTS - attachments.length;
+    const picked: Attachment[] = [];
+    for (const file of Array.from(files).slice(0, Math.max(0, room))) {
+      if (!file.type.startsWith("image/") || file.size > MAX_IMAGE_BYTES) continue;
+      try {
+        picked.push({ name: file.name, url: await readAsDataUrl(file) });
+      } catch {
+        /* skip unreadable file */
+      }
+    }
+    if (picked.length) setAttachments((a) => [...a, ...picked].slice(0, MAX_ATTACHMENTS));
+    if (fileRef.current) fileRef.current.value = ""; // allow re-picking the same file
+  }
+  function removeAttachment(i: number) {
+    setAttachments((a) => a.filter((_, idx) => idx !== i));
+  }
+
   async function submit(forced?: string) {
     const q = (forced ?? input).trim();
-    if (!q || thinking) return;
+    const imgs = attachments.map((a) => a.url);
+    if ((!q && !imgs.length) || thinking) return;
     setInput("");
+    setAttachments([]);
     const first = messages.length === 0;
-    updateMessages((m) => [...m, { role: "user", text: q }]);
-    if (first) setChats((cs) => cs.map((c, i) => (i === cur ? { ...c, title: trunc(q, 30) } : c)));
+    updateMessages((m) => [...m, { role: "user", text: q, images: imgs.length ? imgs : undefined }]);
+    if (first) setChats((cs) => cs.map((c, i) => (i === cur ? { ...c, title: trunc(q || "Image", 30) } : c)));
     setThinking(true);
     try {
-      const { text, sources } = await callAi(q);
+      const { text, sources } = await callAi(q, imgs);
       updateMessages((m) => [...m, { role: "ai", text, sources }]);
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);
@@ -309,7 +360,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
         <div className="ac-body" ref={bodyRef}>
           {messages.length === 0 && !thinking ? (
             <div className="ac-empty">
-              <div className="lead">Ask questions about this API and get help with your integration.</div>
+              <div className="lead">Ask questions about this page.</div>
               <div className="tip">
                 Tip: start a new chat with <kbd>⌘</kbd> <kbd>E</kbd>
               </div>
@@ -326,6 +377,14 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
               {messages.map((m, i) =>
                 m.role === "user" ? (
                   <div key={i} className="ac-msg user">
+                    {m.images?.length ? (
+                      <div className="ac-msg-imgs">
+                        {m.images.map((src, k) => (
+                          // eslint-disable-next-line @next/next/no-img-element
+                          <img key={k} src={src} alt="attachment" />
+                        ))}
+                      </div>
+                    ) : null}
                     {m.text}
                   </div>
                 ) : (
@@ -376,26 +435,79 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
             <span className="bk">
               <Book />
             </span>
-            <span className="ctxl">API Reference — {context}</span>
+            <span className="ctxl">{context}</span>
           </div>
           <div className="ac-inwrap">
-            <input
+            {attachments.length > 0 && (
+              <div className="ac-attachments">
+                {attachments.map((a, i) => (
+                  <div key={i} className="ac-chip" title={a.name}>
+                    {/* eslint-disable-next-line @next/next/no-img-element */}
+                    <img src={a.url} alt={a.name} />
+                    <button
+                      type="button"
+                      className="ac-chip-x"
+                      onClick={() => removeAttachment(i)}
+                      aria-label={`Remove ${a.name}`}
+                    >
+                      <Ico d="M6 6l12 12M18 6L6 18" w={12} />
+                    </button>
+                  </div>
+                ))}
+              </div>
+            )}
+            <textarea
               ref={inputRef}
               className="ac-in"
               value={input}
+              rows={1}
               onChange={(e) => setInput(e.target.value)}
-              onKeyDown={(e) => e.key === "Enter" && submit()}
+              onKeyDown={(e) => {
+                if (e.key === "Enter" && !e.shiftKey) {
+                  e.preventDefault();
+                  submit();
+                }
+              }}
               placeholder="Ask a question about the page…"
               autoComplete="off"
               spellCheck={false}
               aria-label="Ask a question"
             />
-            <button className="ac-send" onClick={() => submit()} disabled={!input.trim() || thinking} aria-label="Send">
-              <Ico d="M12 19V5M6 11l6-6 6 6" w={15} />
-            </button>
+            <div className="ac-inbar">
+              {ai.vision && (
+                <>
+                  <input
+                    ref={fileRef}
+                    type="file"
+                    accept="image/*"
+                    multiple
+                    hidden
+                    onChange={(e) => addFiles(e.target.files)}
+                  />
+                  <button
+                    type="button"
+                    className="ac-attach"
+                    onClick={() => fileRef.current?.click()}
+                    disabled={attachments.length >= MAX_ATTACHMENTS}
+                    aria-label="Attach image"
+                    title={attachments.length >= MAX_ATTACHMENTS ? `Up to ${MAX_ATTACHMENTS} images` : "Attach image"}
+                  >
+                    <Ico d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48" w={17} />
+                  </button>
+                </>
+              )}
+              <button
+                className="ac-send"
+                onClick={() => submit()}
+                disabled={(!input.trim() && attachments.length === 0) || thinking}
+                aria-label="Send"
+              >
+                <Ico d="M12 19V5M6 11l6-6 6 6" w={15} />
+              </button>
+            </div>
           </div>
           <div className="ac-disclaim">
-            Answers run on {ai.mode === "byok" ? "your key" : "your model"} · {ai.providerLabel} · may contain mistakes
+            Answers are AI-generated and may contain mistakes
           </div>
         </div>
       </aside>
diff --git a/lib/ai/transport.ts b/lib/ai/transport.ts
index 8464c48..8737d24 100644
--- a/lib/ai/transport.ts
+++ b/lib/ai/transport.ts
@@ -8,7 +8,12 @@ import type { AiProvider } from "../config";
  * (reader-BYOK mode). See _docs/AI-BYOK-DESIGN.md §1.
  */
 
-export type ChatMessage = { role: "system" | "user" | "assistant"; content: string };
+/** OpenAI-compatible multimodal content part. */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string } };
+
+export type ChatMessage = { role: "system" | "user" | "assistant"; content: string | ContentPart[] };
 
 export const DEFAULT_SYSTEM_PROMPT =
   "You are the documentation assistant for an API reference built with Markline " +
@@ -21,12 +26,20 @@ export function buildMessages(
   systemPrompt: string | undefined,
   context: string | undefined,
   question: string,
+  images?: string[],
 ): ChatMessage[] {
   const system = systemPrompt || DEFAULT_SYSTEM_PROMPT;
   const grounded = context ? `${system}\n\nContext:\n${context}` : system;
+  const userContent: string | ContentPart[] =
+    images && images.length
+      ? [
+          { type: "text", text: question },
+          ...images.map((url): ContentPart => ({ type: "image_url", image_url: { url } })),
+        ]
+      : question;
   return [
     { role: "system", content: grounded },
-    { role: "user", content: question },
+    { role: "user", content: userContent },
   ];
 }
 
diff --git a/lib/config.ts b/lib/config.ts
index f7ea22f..ac15616 100644
--- a/lib/config.ts
+++ b/lib/config.ts
@@ -191,6 +191,12 @@ export type AiConfig = {
   label?: string;
   /** Optional system-prompt override for docs Q&A. */
   systemPrompt?: string;
+  /**
+   * Whether the model accepts image attachments (multimodal). When unset, it's
+   * inferred from the model name (known vision models). Set explicitly to force
+   * the paperclip on/off regardless of the heuristic.
+   */
+  vision?: boolean;
   maxTokens?: number;
   /** Per-IP abuse limits for the proxy route. */
   rateLimit?: { perMinute?: number; perDay?: number };
@@ -207,8 +213,26 @@ export type AiPublicConfig = {
    *  provider directly (byok). Never carries a key. */
   endpoint: string | null;
   maxTokens: number;
+  /** Whether the composer should offer image attachments. */
+  vision: boolean;
 };
 
+/** Known vision-capable model families (substring match on the model id). */
+const VISION_MODEL_PATTERNS = [
+  "gpt-4o", "gpt-4.1", "gpt-4-turbo", "gpt-4-vision", "o1", "o3", "o4-mini", "chatgpt-4o",
+  "claude-3", "claude-4", "claude-opus", "claude-sonnet", "claude-haiku",
+  "gemini", "llava", "bakllava", "llama-3.2", "llama-4", "pixtral",
+  "-vl", "vision", "internvl", "molmo", "grok-2-vision", "grok-vision", "qwen2-vl", "qwen2.5-vl",
+];
+
+/** Resolve whether image attachments are supported: explicit override wins,
+ *  else infer from the model id. */
+export function modelSupportsVision(model: string | undefined, override?: boolean): boolean {
+  if (typeof override === "boolean") return override;
+  const m = (model ?? "").toLowerCase();
+  return VISION_MODEL_PATTERNS.some((p) => m.includes(p));
+}
+
 const AI_PROVIDER_LABELS: Record<AiProvider, string> = {
   openai: "OpenAI",
   openrouter: "OpenRouter",
@@ -254,6 +278,7 @@ export function aiConfig(): AiPublicConfig | null {
         ? `${resolveAiBaseUrl(ai)}/chat/completions`
         : (ai.endpoint ?? "/api/ai"),
     maxTokens: ai.maxTokens ?? 1024,
+    vision: modelSupportsVision(ai.model ?? "gpt-4o-mini", ai.vision),
   };
 }
 

From 4bd2ddd9b2d9fb19e6033bd2e5ff12e04de0ed0e Mon Sep 17 00:00:00 2001
From: Oreofe <oreofeolurin@gmail.com>
Date: Sun, 7 Jun 2026 05:13:26 +0100
Subject: [PATCH 2/3] feat(ai): summarized chat titles + sanitized error
 messages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Titles: derive the chat title from the first question with summarizeTitle()
— strip filler, capitalize, cut on a word boundary (no more mid-word
'beha…'), drop trailing punctuation. Deterministic, so it works even when
the assistant is unavailable.

Errors: never surface raw provider errors to readers. The proxy route logs
the upstream detail server-side and returns a generic message (preserving
429 for rate limits); the client maps errors to safe, actionable text via
friendlyError() and logs the raw detail to the console. Removes the old
behavior that echoed the provider's 404 JSON (incl. openrouter.ai privacy
URL) straight into the chat.
---
 app/api/ai/route.ts             | 11 +++++++--
 components/docs/ai/ask-dock.tsx | 40 +++++++++++++++++++++++++--------
 2 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/app/api/ai/route.ts b/app/api/ai/route.ts
index eaa9d9e..955ec14 100644
--- a/app/api/ai/route.ts
+++ b/app/api/ai/route.ts
@@ -74,7 +74,14 @@ export async function POST(req: Request) {
     });
     return Response.json({ text });
   } catch (e) {
-    const message = e instanceof Error ? e.message : "AI request failed";
-    return new Response(message, { status: 502 });
+    // Log the upstream detail for the operator; never leak provider internals
+    // (keys, billing/privacy URLs, model ids) to the reader.
+    const detail = e instanceof Error ? e.message : String(e);
+    console.error("[markline] AI proxy upstream error:", detail);
+    const isRate = /\b429\b|rate.?limit|too many/i.test(detail);
+    return new Response(
+      isRate ? "Too many requests. Please try again shortly." : "The assistant is temporarily unavailable.",
+      { status: isRate ? 429 : 502 },
+    );
   }
 }
diff --git a/components/docs/ai/ask-dock.tsx b/components/docs/ai/ask-dock.tsx
index 36af555..b702422 100644
--- a/components/docs/ai/ask-dock.tsx
+++ b/components/docs/ai/ask-dock.tsx
@@ -48,9 +48,33 @@ const RKEY_KEY = "markline-ai-key";
 
 const SUGGEST = ["Summarize this page", "Explain this with an example", "What are the key concepts here?"];
 
-function trunc(s: string, n: number) {
-  s = s.replace(/\s+/g, " ").trim();
-  return s.length > n ? s.slice(0, n - 1) + "…" : s;
+/** Condense the first question into a clean chat title: strip filler, capitalize,
+ *  cut on a word boundary (never mid-word), drop trailing punctuation. Purely
+ *  deterministic — no model call, so it works even when the assistant is down. */
+function summarizeTitle(q: string): string {
+  let s = q.replace(/\s+/g, " ").trim();
+  s = s.replace(/^(hi|hey|hello|yo|please|pls|so|um|ok|okay)[,\s]+/i, "");
+  if (!s) return "New chat";
+  s = s.charAt(0).toUpperCase() + s.slice(1);
+  const LIMIT = 42;
+  if (s.length <= LIMIT) return s.replace(/[\s?.!,;:]+$/, "");
+  let cut = s.slice(0, LIMIT);
+  const lastSpace = cut.lastIndexOf(" ");
+  if (lastSpace > 18) cut = cut.slice(0, lastSpace);
+  return cut.replace(/[\s?.!,;:]+$/, "") + "…";
+}
+
+/** Map a raw transport/provider error to a safe, public-facing message. The raw
+ *  detail is never surfaced to readers — it's logged to the console instead. */
+function friendlyError(detail: string, mode: "proxy" | "byok"): string {
+  const d = detail.toLowerCase();
+  if (/\b429\b|rate.?limit|too many/.test(d)) return "Too many requests right now. Please wait a moment and try again.";
+  if (mode === "byok") {
+    if (/\b401\b|\b403\b|unauthor|invalid.*key|api key|no auth/.test(d)) return "That key was rejected. Check your provider key and try again.";
+    if (/\b404\b|model|endpoint/.test(d)) return "Your provider couldn't serve that model. Check the model name in your settings.";
+    return "Couldn't reach your provider. Check your key and model, then try again.";
+  }
+  return "The assistant is unavailable right now. Please try again shortly.";
 }
 function esc(s: string) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -274,7 +298,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     setAttachments([]);
     const first = messages.length === 0;
     updateMessages((m) => [...m, { role: "user", text: q, images: imgs.length ? imgs : undefined }]);
-    if (first) setChats((cs) => cs.map((c, i) => (i === cur ? { ...c, title: trunc(q || "Image", 30) } : c)));
+    if (first) setChats((cs) => cs.map((c, i) => (i === cur ? { ...c, title: summarizeTitle(q || "Image") } : c)));
     setThinking(true);
     try {
       const { text, sources } = await callAi(q, imgs);
@@ -285,11 +309,9 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
         setThinking(false);
         return; // key prompt shown; question stays in transcript
       }
-      const friendly =
-        ai.mode === "byok"
-          ? "Couldn't reach your provider. Check your key and model, then try again."
-          : "The assistant is unavailable right now. In a real deployment this runs on your own key (BYOK) — nothing routes through Markline.";
-      updateMessages((m) => [...m, { role: "ai", text: friendly + (msg && msg.length < 200 ? `\n\n\`${msg}\`` : ""), error: true }]);
+      // Log the raw detail for operators; show readers only a safe message.
+      console.error("[markline] Ask AI error:", e);
+      updateMessages((m) => [...m, { role: "ai", text: friendlyError(msg, ai.mode), error: true }]);
     } finally {
       setThinking(false);
     }

From ec104129e613f19497ceaa036103ea70613a757f Mon Sep 17 00:00:00 2001
From: Oreofe <oreofeolurin@gmail.com>
Date: Sun, 7 Jun 2026 06:10:33 +0100
Subject: [PATCH 3/3] feat(ai): real retrieval so Ask AI answers from the docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Before: the model received only a section-name string ('you are viewing the
"Releases" section') and pickSources() returned hardcoded fake labels — so it
had no actual content and replied 'the provided context does not cover this',
even on the very page that answered the question.

Now lib/ai/retrieval.ts grounds every answer in real docs, client-side:
- Always includes the current page's text (read from the DOM: .docs-prose /
  .api-doc), so on-page questions are answered from the page.
- Ranks the build-time llms-full.txt corpus against the question (saturating
  tf·idf + title boost, with a light stemmer so 'create a service' matches the
  'Services' page) and attaches the top pages — so off-page questions are
  answered too (Mintlify-style).
- 'Used N sources' now reflects the pages actually retrieved, not placeholders.

Pure client-side (one cached fetch of /llms-full.txt) — works in BYOK mode and
on pure-static hosting; degrades to current-page-only if llms-full.txt is
absent. Proxy context cap raised 8k→16k to fit the grounding context.

Known gap: llms-full.txt is docs-only, so API-reference operation bodies aren't
in the corpus yet (the current API page's DOM text is still included).
---
 app/api/ai/route.ts             |   4 +-
 components/docs/ai/ask-dock.tsx |  16 ++--
 lib/ai/retrieval.ts             | 147 ++++++++++++++++++++++++++++++++
 3 files changed, 158 insertions(+), 9 deletions(-)
 create mode 100644 lib/ai/retrieval.ts

diff --git a/app/api/ai/route.ts b/app/api/ai/route.ts
index 955ec14..1f6feca 100644
--- a/app/api/ai/route.ts
+++ b/app/api/ai/route.ts
@@ -54,7 +54,9 @@ export async function POST(req: Request) {
   }
   const question = (body.question ?? "").trim().slice(0, 4000);
   if (!question) return new Response("Empty question", { status: 400 });
-  const context = body.context?.slice(0, 8000);
+  // Retrieved grounding context (current page + top docs) — larger than the old
+  // section-name hint, so allow more headroom.
+  const context = body.context?.slice(0, 16000);
   // Accept up to 4 inline image data URLs (~base64). Drop anything else.
   const images = Array.isArray(body.images)
     ? body.images.filter((u) => typeof u === "string" && /^data:image\//.test(u)).slice(0, 4)
diff --git a/components/docs/ai/ask-dock.tsx b/components/docs/ai/ask-dock.tsx
index b702422..2f8b5f8 100644
--- a/components/docs/ai/ask-dock.tsx
+++ b/components/docs/ai/ask-dock.tsx
@@ -233,8 +233,13 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
   }
 
   async function callAi(question: string, images?: string[]): Promise<{ text: string; sources: string[] }> {
-    const sources = pickSources();
     const imgs = ai.vision && images?.length ? images : undefined;
+    // Real retrieval: ground the answer in the current page + the most relevant
+    // docs for the question (from llms-full.txt). `sources` are the pages used.
+    const { buildGroundingContext } = await import("@/lib/ai/retrieval");
+    const basePath = process.env.NEXT_PUBLIC_MARKLINE_BASE_PATH || "";
+    const { context: grounded, sources } = await buildGroundingContext(question, { basePath, sectionHint: context });
+
     if (ai.mode === "byok") {
       let key = "";
       try {
@@ -254,7 +259,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
         key,
         provider: ai.provider,
         maxTokens: ai.maxTokens,
-        messages: buildMessages(undefined, `You are viewing the "${context}" section.`, question, imgs),
+        messages: buildMessages(undefined, grounded, question, imgs),
         referer: location.origin,
         title: document.title,
       });
@@ -264,7 +269,7 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     const res = await fetch(ai.endpoint || "/api/ai", {
       method: "POST",
       headers: { "content-type": "application/json" },
-      body: JSON.stringify({ question, context: `The user is viewing the "${context}" section.`, images: imgs }),
+      body: JSON.stringify({ question, context: grounded, images: imgs }),
     });
     if (!res.ok) throw new Error((await res.text().catch(() => "")) || `Request failed (${res.status})`);
     const data = await res.json();
@@ -332,11 +337,6 @@ export function AskDock({ ai }: { ai: AiPublicConfig }) {
     if (last) submit(last.text);
   }
 
-  function pickSources(): string[] {
-    const all = [`API Reference — ${context}`, "Authentication", "The object model", "Errors", "Guides"];
-    return all.slice(0, 3);
-  }
-
   const title = chats[cur]?.title || "New chat";
 
   return (
diff --git a/lib/ai/retrieval.ts b/lib/ai/retrieval.ts
new file mode 100644
index 0000000..38597de
--- /dev/null
+++ b/lib/ai/retrieval.ts
@@ -0,0 +1,147 @@
+/**
+ * Client-side documentation retrieval for Ask AI.
+ *
+ * The model was previously handed only a section-name string ("you are viewing
+ * the X section") and never any real page text, so it couldn't answer. This
+ * grounds answers in actual docs:
+ *   1. the full text of the page the reader is on (read from the DOM), and
+ *   2. the most relevant pages for the question, ranked from the build-time
+ *      `llms-full.txt` corpus with a lightweight BM25-style score.
+ *
+ * Pure client-side (one cached fetch of /llms-full.txt) — no server, no
+ * embeddings — so it works in BYOK mode and on pure-static hosting. If
+ * llms-full.txt is missing (older build), retrieval degrades to current-page
+ * context only.
+ */
+
+export type DocSection = { title: string; body: string };
+export type Retrieved = DocSection & { score: number };
+
+const STOP = new Set(
+  "the a an of to in is are and or for on with your you it this that be as at by from into how do does can will not what when which".split(" "),
+);
+
+/** Light stemmer: collapses common inflections so a query for "create a
+ *  service" matches a page titled "Services" (plural) or text about "creating".
+ *  Not linguistically perfect — it only needs query and docs to stem alike. */
+function stem(w: string): string {
+  if (w.length <= 3) return w;
+  if (w.endsWith("ing") && w.length > 5) w = w.slice(0, -3);
+  else if (w.endsWith("ed") && w.length > 4) w = w.slice(0, -2);
+  else if (w.endsWith("s") && !w.endsWith("ss")) w = w.slice(0, -1);
+  if (w.endsWith("e") && w.length > 3) w = w.slice(0, -1);
+  return w;
+}
+
+function tokenize(s: string): string[] {
+  return (s.toLowerCase().match(/[a-z0-9]+/g) ?? [])
+    .filter((w) => w.length > 2 && !STOP.has(w))
+    .map(stem);
+}
+
+let corpusPromise: Promise<DocSection[]> | null = null;
+
+/** Fetch + parse /llms-full.txt once; cached for the session. */
+export function loadDocsCorpus(basePath = ""): Promise<DocSection[]> {
+  if (!corpusPromise) {
+    corpusPromise = (async () => {
+      try {
+        const res = await fetch(`${basePath}/llms-full.txt`, { cache: "force-cache" });
+        if (!res.ok) return [];
+        return parseLlmsFull(await res.text());
+      } catch {
+        return [];
+      }
+    })();
+  }
+  return corpusPromise;
+}
+
+/** Split llms-full.txt into per-page sections. Pages are separated by a `---`
+ *  rule and start with a `# Title` heading (see scripts/build-search.mjs). */
+export function parseLlmsFull(text: string): DocSection[] {
+  const out: DocSection[] = [];
+  for (const part of text.split(/\n-{3,}\n/)) {
+    const m = part.match(/^\s*#\s+(.+?)\s*\n([\s\S]*)$/);
+    if (!m) continue;
+    const title = m[1].trim();
+    const body = m[2].trim();
+    if (title && body) out.push({ title, body });
+  }
+  return out;
+}
+
+/** Rank corpus sections against the question (saturating tf · idf, title-boosted). */
+export function retrieve(question: string, corpus: DocSection[], k = 3): Retrieved[] {
+  const qTerms = tokenize(question);
+  if (!qTerms.length || !corpus.length) return [];
+
+  const df = new Map<string, number>();
+  const docTokens = corpus.map((d) => {
+    const toks = tokenize(`${d.title} ${d.body}`);
+    for (const t of new Set(toks)) df.set(t, (df.get(t) ?? 0) + 1);
+    return toks;
+  });
+  const N = corpus.length;
+
+  const scored: Retrieved[] = corpus.map((d, i) => {
+    const tf = new Map<string, number>();
+    for (const t of docTokens[i]) tf.set(t, (tf.get(t) ?? 0) + 1);
+    const titleToks = new Set(tokenize(d.title));
+    let score = 0;
+    for (const q of qTerms) {
+      const f = tf.get(q) ?? 0;
+      if (!f) continue;
+      const idf = Math.log(1 + N / ((df.get(q) ?? 0) + 0.5));
+      score += idf * (f / (f + 1.5)); // saturating term frequency
+      if (titleToks.has(q)) score += idf * 0.9; // boost title matches
+    }
+    return { ...d, score };
+  });
+
+  return scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, k);
+}
+
+/** Read the current page's title + visible prose from the DOM (docs or apiref). */
+export function currentPageText(maxChars = 6000): { title: string; text: string } | null {
+  if (typeof document === "undefined") return null;
+  const title = document.querySelector("h1")?.textContent?.trim() || document.title || "This page";
+  const main = document.querySelector(".docs-prose, .api-doc, main");
+  if (!main) return null;
+  const text = (main.textContent || "").replace(/\s+/g, " ").trim().slice(0, maxChars);
+  return text ? { title, text } : null;
+}
+
+/**
+ * Assemble grounding context for a question: the current page first, then the
+ * top retrieved pages (deduped). Returns the context string (capped) plus the
+ * list of source titles actually used (for the "Used N sources" UI).
+ */
+export async function buildGroundingContext(
+  question: string,
+  opts: { basePath?: string; sectionHint?: string; maxChars?: number; k?: number } = {},
+): Promise<{ context: string; sources: string[] }> {
+  const { basePath = "", sectionHint, maxChars = 14000, k = 3 } = opts;
+  const corpus = await loadDocsCorpus(basePath);
+  const top = retrieve(question, corpus, k);
+  const cur = currentPageText();
+
+  const blocks: string[] = [];
+  const sources: string[] = [];
+
+  if (cur) {
+    blocks.push(`# Current page: ${cur.title}\n\n${cur.text}`);
+    sources.push(cur.title);
+  }
+  for (const t of top) {
+    if (cur && t.title.toLowerCase() === cur.title.toLowerCase()) continue; // already included
+    blocks.push(`# ${t.title}\n\n${t.body}`);
+    if (!sources.includes(t.title)) sources.push(t.title);
+  }
+
+  let context = blocks.join("\n\n---\n\n");
+  if (sectionHint && !cur) context = `The reader is on the "${sectionHint}" page.\n\n${context}`;
+  if (context.length > maxChars) context = context.slice(0, maxChars) + "\n\n[context truncated]";
+
+  return { context, sources: sources.slice(0, 4) };
+}